{"id":13414162,"url":"https://github.com/kornysietsma/polyglot-code-explorer","last_synced_at":"2025-03-14T21:31:48.954Z","repository":{"id":42253142,"uuid":"280675484","full_name":"kornysietsma/polyglot-code-explorer","owner":"kornysietsma","description":"Multi-language source code metrics visualization","archived":false,"fork":false,"pushed_at":"2024-06-04T13:16:04.000Z","size":5270,"stargazers_count":45,"open_issues_count":2,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-07-31T21:51:45.360Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kornysietsma.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-07-18T14:41:48.000Z","updated_at":"2024-06-04T13:16:07.000Z","dependencies_parsed_at":"2023-11-10T16:25:13.250Z","dependency_job_id":"4d1040ed-58f2-481f-943c-5ae92497882e","html_url":"https://github.com/kornysietsma/polyglot-code-explorer","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kornysietsma%2Fpolyglot-code-explorer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kornysietsma%2Fpolyglot-code-explorer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kornysietsma%2Fpolyglot-code-explorer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kornysietsma%2Fpolyglot-code-explorer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kornysietsma","download_url":"https://codeload.github.com/kornysietsma/polyglot-code-explorer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221508974,"owners_count":16834807,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T21:00:15.773Z","updated_at":"2024-10-26T07:30:33.667Z","avatar_url":"https://github.com/kornysietsma.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Code"],"sub_categories":[],"readme":"# Polyglot Code Explorer\n\nThis is the front-end visualisation part of my cross-language polyglot code tools - it allows you to visualise and explore a whole lot of information about a codebase.\n\nFor an overview and more documentation, take a look at \u003chttps://polyglot.korny.info\u003e\n\n*NOTE* you will need to use other tools, documented on the site above, to create JSON data files that reflect your own projects!\n\n## WORK IN PROGRESS WARNING\n\nI'm doing a lot of changes right now - if you fetch the current code, things may break.\n\nEspecially note, I'm changed the data file formats created by the explorer and used by the scanner - I've added version number checks, but data files from the Scanner must match expectations of the Explorer, so for now it's a bit of \"make sure you pull changes often\" or things will break.\n\n## Installing and running\n\nYou can run with node.js (see below) - or you can grab a compiled static site and run it yourself.\n\n### Running from a static release\n\nSee also \u003chttps://polyglot.korny.info/tools/explorer/howto\u003e for more detailed instructions\n\nStatic releases are published to \u003chttps://github.com/kornysietsma/polyglot-code-explorer/releases\u003e\n\nThese are published as a static site - you can run them by:\n\n- Download the zip file from the latest release\n- Unzip it somewhere\n- Optionally copy your own JSON data file over `data/default.json`\n- Load the static site in your favourite static web server\n\nThere are quite a ways to run a static web server locally - many people have python pre-installed, in which case you can run a simple web server very easily:\n\n```sh\n# Check python version\npython -V\n# If Python version returned above is 3.X\npython3 -m http.server\n# On windows try \"python\" instead of \"python3\", or \"py -3\"\n# If Python version returned above is 2.X\npython -m SimpleHTTPServer\n```\n\n### Running using node.js\n\nYou need node.js installed, currently tested on node 14.5.0 though it may well work on older or newer versions.\n\nYou need `yarn` installed - see \u003chttps://classic.yarnpkg.com/en/docs/install\u003e\n\nrun `yarn install` in the project directory to fetch all dependencies.\n\n## Running the explorer\n\nYou can run with the default data file by running `yarn run` - a browser window will open on \u003chttp://localhost:3000\u003e\n\n## Running with a particular data file\n\nInitially I had data files in `src/data/flare.json` loaded with\n\n```js\nimport rawData from \"./data/flare.json\";\n```\n\nThis works, but it doesn't work well if you want to change data files at run-time.\n\nNow, instead it looks for a file in `public/data/default.json` and loads it via an `xmlhttprequest` in `index.js`\n\nIf you want a different file, set `REACT_APP_EXPLORER_DATA` with the file prefix (ignoring the `.json` part) - create-react-app\nwill pass variables starting `REACT_APP_` to the app, so `index.js` can read it and load the right file.\n\nFor example:\n\n```sh\nREACT_APP_EXPLORER_DATA=big yarn start\n```\n\nor if you don't want to re-open the browser:\n\n```sh\nREACT_APP_EXPLORER_DATA=big BROWSER=none yarn start\n```\n\nFor a discussion of how I use React and D3 together, take a look at [my blog post](https://blog.korny.info/2020/07/19/better-d3-with-react.html) and [demo code](https://github.com/kornysietsma/d3-react-demo)\n\nThis was created using Create-React-App and hasn't been \"ejected\" yet so you can upgrade react versions and the like.  You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started).\n\n## Testing\n\nTo run tests, `yarn test`\n\nI have hardly any tests - mostly as this started as all UI code with little logic, and frankly the effort for UI testing on a rapidly changing pet project just didn't seem worth the benefits.\n\nI'm finally adding some tests now, but mostly around pure JavaScript logic which is\neasy to test - and initially, just where I'm doing something new, and complex, and especially where I find bugs.\n\nI'm a huge fan of proper testing for code that anyone depends on day-to-day - if someone wants to fund me to quit my job and write a comprehensive test suite, I'd be very happy!\n\n## A note on typescript and eslint checks\n\nI found, after some digging, that Typescript by default doesn't check or warn you\nif you access an array with a possibly out-of-range index:\n\n```js\nfunction last(days: number[]): number {\n    return days.sort((a, b) =\u003e b - a)[0];\n}\nlast([]); // undefined!\n```\n\nThere's a lot of discussion [here](https://stackoverflow.com/questions/50647399/typescript-accessing-an-array-element-does-not-account-for-the-possibility-of-u)\n\nI have enabled the new-ish flag `noUncheckedIndexedAccess` (see tsconfig.json) so that this is checked.  But, sadly, typescript doesn't then like code like:\n\n```js\n if (index \u003c bigColourRange.length) {\n        team.colour = bigColourRange[index];\n```\n\nSo, I'm using a lot of non-null-assertion `!` operators:\n\n```js\n if (index \u003c bigColourRange.length) {\n        team.colour = bigColourRange[index]!;\n```\n\nand I had to disable the `@typescript-eslint/no-non-null-assertion` check to avoid lots of eslint warnings.  I feel this is a valid place for the non-null assertion!\n\nIn cases where I'm not confident that the index can never be out of range, I throw an error for clarity:\n\n```js\n    const colour = bigColourRange[index];\n    if (colour == undefined) {\n        throw new Error(\"Logic error: invalid colour index\");\n    }\n```\n\nFor me, this feels like a lesser evil - I'd prefer to be told \"hey, this array access might be out of range, please confirm it's OK!\" than not.  YMMV.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkornysietsma%2Fpolyglot-code-explorer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkornysietsma%2Fpolyglot-code-explorer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkornysietsma%2Fpolyglot-code-explorer/lists"}