{"id":13801953,"url":"https://github.com/brettz9/es-file-traverse","last_synced_at":"2025-09-27T20:30:52.811Z","repository":{"id":40846291,"uuid":"245792593","full_name":"brettz9/es-file-traverse","owner":"brettz9","description":"Traverse ECMAScript (JavaScript) files by their `import`/`require` chains","archived":false,"fork":false,"pushed_at":"2024-07-11T00:27:05.000Z","size":1250,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-08T18:56:47.893Z","etag":null,"topics":["amd","ecmascript","import","require","traversal"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/brettz9.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE-MIT.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-03-08T10:17:19.000Z","updated_at":"2024-07-11T00:27:08.000Z","dependencies_parsed_at":"2024-01-02T23:43:24.769Z","dependency_job_id":"e957f0c1-5bca-47a4-aa95-abb1e849502e","html_url":"https://github.com/brettz9/es-file-traverse","commit_stats":{"total_commits":151,"total_committers":4,"mean_commits":37.75,"dds":0.06622516556291391,"last_synced_commit":"0fe673b3f3f029103d0956535497098e1b982b20"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brettz9%2Fes-file-traverse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brettz9%2Fes-file-traverse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brettz9%2Fes-file-traverse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brettz9%2Fes-file-traverse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brettz9","download_url":"https://codeload.github.com/brettz9/es-file-traverse/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234455938,"owners_count":18835665,"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":["amd","ecmascript","import","require","traversal"],"created_at":"2024-08-04T00:01:31.391Z","updated_at":"2025-09-27T20:30:47.462Z","avatar_url":"https://github.com/brettz9.png","language":"JavaScript","funding_links":["https://issuehunt.io/r/brettz9/es-file-traverse"],"categories":["Tools"],"sub_categories":["Testing Tools"],"readme":"[![npm](https://img.shields.io/npm/v/es-file-traverse.svg)](https://www.npmjs.com/package/es-file-traverse)\n[![Dependencies](https://img.shields.io/david/brettz9/es-file-traverse.svg)](https://david-dm.org/brettz9/es-file-traverse)\n[![devDependencies](https://img.shields.io/david/dev/brettz9/es-file-traverse.svg)](https://david-dm.org/brettz9/es-file-traverse?type=dev)\n\n[![eslint badge](https://raw.githubusercontent.com/brettz9/es-file-traverse/master/badges/eslint-badge.svg?sanitize=true)](badges/eslint-badge.svg)\n[![eslint 3rd party badge](https://raw.githubusercontent.com/brettz9/es-file-traverse/master/badges/eslint-thirdparty.svg?sanitize=true)](badges/eslint-thirdparty.svg)\n\n[![testing badge](https://raw.githubusercontent.com/brettz9/es-file-traverse/master/badges/tests-badge.svg?sanitize=true)](badges/tests-badge.svg)\n[![coverage badge](https://raw.githubusercontent.com/brettz9/es-file-traverse/master/badges/coverage-badge.svg?sanitize=true)](badges/coverage-badge.svg)\n\u003c!--\n[![Actions Status](https://github.com/brettz9/es-file-traverse/workflows/Coverage/badge.svg)](https://github.com/brettz9/es-file-traverse/actions)\n--\u003e\n\n[![Known Vulnerabilities](https://snyk.io/test/github/brettz9/es-file-traverse/badge.svg)](https://snyk.io/test/github/brettz9/es-file-traverse)\n[![Total Alerts](https://img.shields.io/lgtm/alerts/g/brettz9/es-file-traverse.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/brettz9/es-file-traverse/alerts)\n[![Code Quality: Javascript](https://img.shields.io/lgtm/grade/javascript/g/brettz9/es-file-traverse.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/brettz9/es-file-traverse/context:javascript)\n\n\u003c!--[![License](https://img.shields.io/npm/l/es-file-traverse.svg)](LICENSE-MIT.txt)--\u003e\n[![Licenses badge](https://raw.githubusercontent.com/brettz9/es-file-traverse/master/badges/licenses-badge.svg?sanitize=true)](badges/licenses-badge.svg)\n\n(see also [licenses for dev. deps.](https://raw.githubusercontent.com/brettz9/es-file-traverse/master/badges/licenses-badge-dev.svg?sanitize=true))\n\n[![issuehunt-to-marktext](https://issuehunt.io/static/embed/issuehunt-button-v1.svg)](https://issuehunt.io/r/brettz9/es-file-traverse)\n\n# es-file-traverse\n\nAllows traversing ECMAScript (JavaScript) files by their `import`/`require`\nchains, building a list of files and optionally executing a callback with\nthe file name, source and AST.\n\n## Installation\n\n```shell\nnpm i es-file-traverse\n```\n\n## Comparison to other projects\n\nThis project is similar to [imports-visitor](https://www.npmjs.com/package/imports-visitor),\nbut it uses `@babel/eslint-parser` so as to report ESTree (ESLint) AST.\n\n## Usage with ESLint\n\nOne of the motivations behind this library was to allow linting of code from\nthird parties, not for stylistic purposes, but to avoid introducing serious\nvulnerabilities or globals and other intrusions.\n\nWhile one can opt to lint `node_modules`, this can be a heavy hammer, as:\n\n1. Not all of your production code uses every folder in `node_modules`.\n2. You may get other errors from files you are not actually using (including\n    possibly files that were accidentally included in the dependency you are\n    checking as mere test files). While you may wish to be a good citizen\n    and lint the whole package, `es-file-traverse` lets you confine yourself\n    to those public APIs that are of most concern and may impact your users.\n\n`es-file-traverse` can be used with ESLint to target files for linting which\nare actually used by your application (not the ESLint behavior of checking\nall files in a directory unless ignored, but following imports/require\nstatements into (and possibly out of) `node_modules` to find the files\nused by your script(s)). For browser applications, it is recommended you\npoint `es-file-traverse` to your HTML files to ensure the source type\n(module or script) is set properly and automatically. For Node applications,\nit is recommended you do not set `--no-check-package-json` as this\nwil allow you to detect source type properly for Node.\n\nFor an example, you can see that `es-file-traverse` adds its own linting\nof third party scripts, using the config [`.eslintrc-3rdparty.js`](./.eslintrc-3rdparty.js). Note that this is a small subset of the rules we use on our\nown project, and is instead focused on checking for more serious\nvulnerabilities or intrusive practices (e.g., `no-eval` or `no-global-assign`).\n\nIt is recommended that you use suitable\n[ESLint's command-line flags](https://eslint.org/docs/user-guide/command-line-interface). Here are the flags we are using with a quick summary of why:\n\n- `--no-inline-config` - 3rd parties may disable rules you wish to check\n    or they may reference rules which your config does not include,\n    causing linting errors.\n- `--no-ignore` - Don't apply our own `.eslintignore` to the explicit\n    list of third party files we are including.\n- `--no-eslintrc` - We don't want to check the normal hierarchy of\n    `.eslintrc.*` files, as these are used by our and other projects' for\n    their stylstic concerns. We instead use `--config` to indicate the rules\n    we wish to be applied.\n- `--config` - Indicates the actual rules we want applied to third party\n    files discovered to be used by, or by the dependencies of, the `--file`\n    file passed to `es-file-traverse`.\n\nWe use the backticks to ensure that the list of files returned by\n`es-file-traverse` is passed on to `eslint`.\n\n```sh\neslint --no-inline-config --no-ignore --no-eslintrc --config .eslintrc-3rdparty.js `es-file-traverse --file ./bin/cli.js --node --cjs`\n```\n\n(Note that we actually use `node ./bin/cli.js` instead of `es-file-traverse`\nin our script as our own binary file is not available to us, but it is when\ninstalled, so you can use `es-file-traverse` with your own scripts.)\n\n## Usage with `eslint-formatter-sourcemaps`\n\nIn normal linting you typically wish to enforce stylistic checks on your\nproject, so you will mostly want to target source files in such linting.\n\nHowever, when linting third party code (e.g., to check for security\nvulnerabilities or intrusive practices)--a compelling use case of\n`es-file-traverse`--distribution files are generally preferable as targets,\nas they are the final authority on the code of your project that will be\nexecutable (including any embedding or importing/requiring of 3rd party\ncode, e.g., within `node_modules`). (Also note that if using `--typescript`\nmode, `es-file-traverse` will, as per the TypeScript module resolution\nalgorithm, follow `.d.ts` declaration files rather than the resulting\n`.js` files, so if your source is TypeScript, this is another reason you\nmay not want to trouble parsing source.)\n\nBut the default ESLint formatter won't follow sourcemaps to tell you\nwhere the original source file for the problematic code is, so you may, as\nneeded, report a problem to the third party or avoid its dependency.\nYou may therefore also wish to use\n[eslint-formatter-sourcemaps](https://github.com/brettz9/eslint-formatter-sourcemaps)\nwith your `es-file-traverse`-driven `eslint` linting process in order to\nget the original paths shown for any linting violations.\n\n## Usage with `eslint-formatter-badger`\n\nOnce we are linting files from our own projects, and particularly when we are\nlinting third party dependencies, we may wish to inform consumers of our\nproject of the degree to which we have looked out for weaknesses, such as by\nlisting the number of rules passing or the types of rules (e.g., for\nvulnerabilities or intrusive code).\n\nSee [eslint-formatter-badger](https://github.com/brettz9/eslint-formatter-badger)\nfor more on how to do this, in particular the section\n``\"Usage with `es-file-traverse`\".``\n\n## CLI\n\nNote that while `es-file-traverse` does not currently provide traces of the\nroutes, you might find `--serial` (for consistent ordering) and\n`--format json` (for easy reading) helpful as when `--serial` is applied, you\ncan at least see the order in which the files were processed, e.g., first\ngoing through one file's imports, then another's, etc.\n\n![doc-includes/cli.svg](doc-includes/cli.svg)\n\n## To-dos\n\n1. Build globals list for users also!\n1. Options\n    1. Option to give an error or report listing **files which were not\n        traversed** but within a set of specified files.\n1. Iteration methods\n    1. Support a pnpm resolver\n        (https://www.npmjs.com/package/@pnpm/local-resolver ?)\n    1. For modules, check also for `require` when Node's `module.createRequire`\n        or `module.createRequireFromPath` are used.\n    1. Utilize **import maps** then return that result with file name/path\n        (and module type used, e.g., if multiple module types\n        are being queried).\n    1. Handle **dynamic `require`** (or `define`?) (e.g., pass\n        back the file name and expression)?\n    1. Support **transpiling** (e.g., Rollup with node-resolve and CJS plugins)\n    1. **`fetch` or `XMLHttpRequest`** could be used with `eval` but that\n        rule could not be readily used without a lot of complexity.\n    1. Follow through with any **binaries** that are executed (e.g.,\n        `child_process.spawn('node_mod_a')` -\u003e\n        `node_modules/.bin/node_mod_a` -\u003e\n        `node_modules/node_mod_a/cli/index.js`); could have linting to ensure\n        though that instead of spawning raw `node_mod` which could conflict\n        with a native `node_mod_a`, should use fixed paths for child processes.\n        Could, however, whitelist certain trusted native executables, albeit\n        with a potential risk of namespace conflicts.\n    1. Esp. if ESLint started supporting linting of URLs, we could\n        provide **loading of HTML from a server** (as with a `baseUrl`; see\n        commit history for a partial attempt); would return URLs instead\n        of files as well.\n1. Uses elsewhere:\n    1. **Linter**: Propose this traversal mechanism as a **command line\n        option for eslint itself**, esp. if get as a working demo (in\n        place of, or in addition to, a set of whitelisted files).\n        1. tern-like linting validator; build scopes across files with\n            `escope` and use for checking function calls/references.\n        1. Perform linting (or if doing along the way, only perform linting\n            once per discovered file). Traversal code should remain\n            separate so can keep a useful generic traverser by\n            import/require (dynamic or static) rather than becoming a linter.\n        1. Ensure linters can lint any extension found for an imported/required\n            file, not just those with `--ext` at command line.\n        1. With a need to follow through the individual files anyways, we can\n            also check along the way whether this is strict mode file or not,\n            and lint that file accordingly, avoiding undue parsing failures.\n            Can also avoid errors when the file type is detected as JSON\n            (requiring a JSON file) or if the feature of registering a file\n            type was used (then handling that as appropriate).\n        1. Check source maps to refer back to source\n            1. See also:\n                1. \u003chttps://github.com/Bartvds/eslint-path-formatter\u003e\n                1. \u003chttps://github.com/a-x-/eslint-path-formatter2\u003e\n        1. Allow collecting whole modules in use rather than files, so\n            can indicate desire to lint entire modules in use (e.g.,\n            so as to report back problems across the whole repo)\n    1. Use esp. for `eslint-plugin-privileges` (and `eslint-plugin-query`).\n    1. Use for `eslint-plugin-jsdoc` in getting at defined variables\n    1. **Validate JavaScript with JSDoc** alone (no TypeScript needed),\n        e.g., function calls which are supplying the wrong type; added\n        as `eslint-plugin-jsdoc` to-do\n    1. Validate function signatures, etc., as with `eslint-plugin-jsdoc`,\n        but finding the source of each `/** @type */` and subsituting\n        its `@typedef`.\n    1. Use for gathering info to use in **autocomplete** (not only import\n        paths but variables/symbols)?\n    1. Collect comments (which have no AST)\n    1. See uses in `eslint-plugin-query` to-dos\n    1. Note: if looking also for what is *exported*, e.g., to know what\n        globals are, if non-module mode in browser, should look at `var`\n        and even `const`/`let`; can then use, e.g., for\n        `jsdoc/no-undefined-types`; as with `no-unrestricted-properties`,\n        etc., we want to find out when `window` or other globals are used,\n        but to collect the uses, rather than report them.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrettz9%2Fes-file-traverse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrettz9%2Fes-file-traverse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrettz9%2Fes-file-traverse/lists"}