{"id":20916168,"url":"https://github.com/emosheeep/circular-dependency-scanner","last_synced_at":"2025-10-20T07:46:35.554Z","repository":{"id":220353256,"uuid":"751406404","full_name":"emosheeep/circular-dependency-scanner","owner":"emosheeep","description":"Out-of-box circular dependencies detector, support js, jsx, ts, tsx, mjs, cjs, vue.","archived":false,"fork":false,"pushed_at":"2024-09-10T06:23:07.000Z","size":1277,"stargazers_count":13,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-14T08:09:12.125Z","etag":null,"topics":["ast","circular","circular-dependency","cli","cycles","cyclic","detector","scanner","web"],"latest_commit_sha":null,"homepage":"","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/emosheeep.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-01T14:52:56.000Z","updated_at":"2025-05-09T11:14:18.000Z","dependencies_parsed_at":"2024-02-29T17:48:29.249Z","dependency_job_id":"422ab5c3-3853-4337-aa77-d30a99470570","html_url":"https://github.com/emosheeep/circular-dependency-scanner","commit_stats":{"total_commits":14,"total_committers":3,"mean_commits":4.666666666666667,"dds":0.1428571428571429,"last_synced_commit":"79a103c9bd8fcfb6efc25e52896567c134e85094"},"previous_names":["emosheeep/circular-dependency-scanner"],"tags_count":4,"template":false,"template_full_name":"emosheeep/cli-template","purl":"pkg:github/emosheeep/circular-dependency-scanner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emosheeep%2Fcircular-dependency-scanner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emosheeep%2Fcircular-dependency-scanner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emosheeep%2Fcircular-dependency-scanner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emosheeep%2Fcircular-dependency-scanner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emosheeep","download_url":"https://codeload.github.com/emosheeep/circular-dependency-scanner/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emosheeep%2Fcircular-dependency-scanner/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260278558,"owners_count":22985305,"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":["ast","circular","circular-dependency","cli","cycles","cyclic","detector","scanner","web"],"created_at":"2024-11-18T16:20:12.071Z","updated_at":"2025-10-20T07:46:30.485Z","avatar_url":"https://github.com/emosheeep.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# circular dependencies scanner ⚡\n\n[![npm version](https://img.shields.io/npm/v/circular-dependency-scanner)](https://npmjs.com/package/circular-dependency-scanner)\n![weekly downloads](https://img.shields.io/npm/dw/circular-dependency-scanner)\n![license](https://img.shields.io/npm/l/circular-dependency-scanner)\n\nOut-of-box circular dependencies detector, with both JavaScript API and Command Line Tool built in, support all file types we used in common like `.js,.jsx,.ts,.tsx,.mjs,.cjs,.vue`.\n\nPull out `import/require/export` path from files and revert it into to real path (if aliased) with path alias configurations, then calculate the circles among and print which with colors.\n\nEnglish | [中文](./README.zh_CN.md)\n\n# Features\n\n- 📦 All file types support.\n- 🗑 Support dropping pure TS type references.\n- 💡 Friendly Command Line Tool.\n- 🛠️ Fully Typed JavaScript APIs and Prompts.\n- 🌩 Tiny, Pretty, Fast and Reliable.\n\n# Example\n\nHere the running example for the `ds -o circles.json` execution:\n\n![cli.gif](https://raw.githubusercontent.com/emosheeep/circular-dependency-scanner/HEAD/snapshots/cli.gif)\n\nThe `ts,js,vue` files will be printed directly into console as `blue,yellow,green` as follows if you didn't pass an output filename param:\n\n![output-snapshot](https://raw.githubusercontent.com/emosheeep/circular-dependency-scanner/HEAD/snapshots/output.png)\n\n# Motivation\n\nOn one hand there are few tools, on the other hand there are too many annoyed problems among the exist tools on the market:\n\n1. Not reliable, **usually missed lots of dep-circles**. This is because in common they can't pull out the import/require sources correctly from source files\n2. Not a standalone tool, they often appears as a webpack/rollup/vite plugin, and analyze the relations with help of the module graph created by the plugin's host, which usually under limitations, slow and hard to use.\n\nBut now, you just run `ds`, all of the **(.js,.jsx,.ts,.tsx,.mjs,.cjs,.vue)** files under current directory will be parsed directly and fast with TypeScript API, which almost include all file types we used. And then the circles among these files will be printed.\n\n# Command Line Tool (Prefer)\n\nThe `ds` command which means `depscan` will be available after you installed this package globally.\n\n```sh\npnpm i -g circular-dependency-scanner # or npm/yarn\ncd path/to/execute # change directory\nds # run `ds` command\n```\n\nThere are detailed documentations built in, you can use `-h` option to print help information anytime.\n\n```sh\nds [options] [path] # Automatically detect circular dependencies under the current directory and print the circles.\n```\n\n## Options\n\n```sh\nds -h # print help info\nds -V/--version # print cli version\n\nds # current dir by default\nds src # detect src directory...and so on.\nds --filter 'src/router/*.ts' # only print the circles matched the pattern.\nds --absolute # print absolute path.\nds --ignore output dist node_modules # path to ignore.\nds --output circles.json # output analysis into specified file.\nds --throw # exit with code 1 when cycles're found.\nds --exclude-type # exclude pure type-references when calculating circles.\n```\n\n# JavaScript API\n\nSometime you may want to manually write script and make an analysis, just use JavaScript API as follows:\n\n```ts\nimport { circularDepsDetect } from 'circular-dependency-scanner';\n\nconst results = circularDepsDetect({\n  /**\n   * Base path to execute command.\n   * @default process.cwd()\n   */\n  cwd?: string;\n  /**\n   * Whether to use absolute path.\n   * @default false\n   */\n  absolute?: boolean;\n  /**\n   * Glob patterns to exclude from matches.\n   * @default ['node_modules']\n   */\n  ignore?: string[];\n  /**\n   * Glob pattern to filter output circles.\n   * @default ['node_modules']\n   */\n  filter?: string;\n  /**\n   * Exclude pure type-references when calculating circles.\n   * @default false\n   */\n  excludeTypes?: boolean;\n});\n\n```\n\n# QA\n\n## How does this tool handle alias paths?\n\nWe use `get-tsconfig` to transform ts alias imports, which means you should manually configure `compilerOptions.paths` in the nearest `tsconfig/jsconfig` so that the tool can recognize it correctly, unknown aliases will be dropped.\n\n## Which reference will be pull out from the files\n\nIn a short, it find references like:\n\n```ts\nimport test from './test'; // got './test'\nimport './test'; // got './test'\nimport('./test'); // got './test'\nrequire('./test'); // got './test'\nexport * from './test'; // got './test'\nexport { test }; // got no export source\n```\n\nPure type-references will be dropped if `excludeTypes` is set `true`:\n\n```ts\n// import statement\nimport * as a from './import * as a'; // ✅\nimport type * as a from './import type * as a';\n\nimport a from './import a'; // ✅\nimport type a from './import type a';\nimport type { a } from './import type { a }';\nimport { type a } from './import { type a }';\n\nimport { type a, b } from './import { type a, b }'; // ✅\n\n// export statement\nexport * from './export *'; // ✅\nexport * as a from './export * as a' // ✅\nexport type * from './export type *';\nexport type * as a from './export type * as a';\n\nexport type { a } from './export type { a }';\nexport { type a } from './export { type a }';\nexport { type a, b } from './export { type a, b }'; // ✅\n```\n\nScreen out circles that make sense by `--filter` option.\n\n## Running at monorepo\n\nThe analysis of file reference depend on the `alias` configurations you supplied. So if you run this command at your monorepo root directory, you may find that some of the different projects may include same `alias` but redirect to a different path, which cause the results unreliable.\n\n**If you want to analyze multiple projects, please execute one by one**.\n\n# Reference\n\n- The Command Line Tool is based on [commander](https://github.com/tj/commander.js).\n- The circular dependencies analysis algorithm is based on [graph-cycles](https://github.com/grantila/graph-cycles).\n- The typescript paths are transformed by [get-tsconfig](https://github.com/privatenumber/get-tsconfig).\n\n# Issues\n\nNo tool is perfect, and if you run into problems with it, welcome to file an issue, I’ll respond as soon as possible.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femosheeep%2Fcircular-dependency-scanner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femosheeep%2Fcircular-dependency-scanner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femosheeep%2Fcircular-dependency-scanner/lists"}