@ts-stack/cycle-detector 1.0.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Костя Третяк.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE

package/README.md

@@ -0,0 +1,25 @@
+# @ts-stack/cycle-detector
+
+A blistering fast, lightweight, zero-dependency CLI utility designed to detect circular dependencies in TypeScript (ESM) projects. 
+
+Unlike other tools, it uses the native TypeScript Compiler API for smart path resolution (respecting your `tsconfig.json` paths/aliases) and **completely ignores type-only imports** (`import type`), as they don't cause actual runtime issues in Node.js.
+
+## Features
+
+- ⚡ **Blazing Fast**: Uses static AST parsing without full type-checking overhead.
+- 🧠 **Smart Resolution**: Fully supports `tsconfig.json` `paths`, path mappings, and ESM extensions out of the box.
+- 🧱 **Monorepo & Glob Support**: Can check multiple packages at once using wildcards.
+- 🛑 **Type-Safe**: Intelligently skips `import type` and type-only named bindings.
+- 🤖 **CI/CD Ready**: Returns non-zero exit codes when cycles are found.
+
+Note: required Node.js >= v22.0.0.
+
+## Installation
+
+You don't even need to install it! Just run it via `npx`:
+
+```bash
+npx @ts-stack/cycle-detector src/index.ts
+# OR
+npx @ts-stack/cycle-detector packages/*/src/index.ts
+```

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import ts from 'typescript';
+const graph = new Map();
+const visited = new Map();
+const currentStack = [];
+const detectedCycles = [];
+/**
+ * Parses command line arguments to separate options from entry point patterns.
+ */
+function parseArgs() {
+    const args = [...process.argv.slice(2)];
+    let projectPath;
+    const entryPatterns = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--project' || args[i] === '-p') {
+            projectPath = args[i + 1];
+            i++;
+        }
+        else {
+            entryPatterns.push(args[i]);
+        }
+    }
+    return { entryPatterns, projectPath };
+}
+/**
+ * Checks if an import/export declaration is type-only.
+ * Type-only imports are stripped during compilation and don't cause runtime cycles.
+ */
+function isRuntimeImport(node) {
+    if (ts.isExportDeclaration(node)) {
+        if (!node.moduleSpecifier)
+            return false;
+        return !node.isTypeOnly;
+    }
+    if (ts.isImportDeclaration(node)) {
+        if (!node.importClause)
+            return true; // Side-effect import: import './foo'
+        if (node.importClause.isTypeOnly)
+            return false; // import type { X } from './foo'
+        // Check individual specifiers: import { type A, B } from './foo'
+        const namedBindings = node.importClause.namedBindings;
+        if (namedBindings && ts.isNamedImports(namedBindings)) {
+            return !namedBindings.elements.every((el) => el.isTypeOnly);
+        }
+        return true;
+    }
+    return false;
+}
+/**
+ * Resolves module paths using the TypeScript Compiler API.
+ * Respects tsconfig paths/aliases and ESM extensions.
+ */
+function resolveModule(moduleName, containingFile, options) {
+    const result = ts.resolveModuleName(moduleName, containingFile, options, ts.sys);
+    if (result.resolvedModule && !result.resolvedModule.isExternalLibraryImport) {
+        return result.resolvedModule.resolvedFileName;
+    }
+    return null;
+}
+/**
+ * Analyzes a single entry point, builds its dependency graph, and detects cycles.
+ */
+function analyzeEntryPoint(entryPoint, projectPath) {
+    graph.clear();
+    visited.clear();
+    currentStack.length = 0;
+    detectedCycles.length = 0;
+    // Locate tsconfig.json automatically if not explicitly provided
+    const configPath = projectPath
+        ? path.resolve(projectPath)
+        : ts.findConfigFile(path.dirname(entryPoint), ts.sys.fileExists, 'tsconfig.json');
+    let compilerOptions = {};
+    if (configPath && fs.existsSync(configPath)) {
+        const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
+        const parsedConfig = ts.parseJsonConfigFileContent(configFile.config, ts.sys, path.dirname(configPath));
+        compilerOptions = parsedConfig.options;
+    }
+    // Recursive AST parsing to build the graph
+    function parseFile(filePath) {
+        if (graph.has(filePath) || !fs.existsSync(filePath))
+            return;
+        graph.set(filePath, []);
+        const content = fs.readFileSync(filePath, 'utf8');
+        const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);
+        const imports = [];
+        function walk(node) {
+            if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) {
+                if (isRuntimeImport(node)) {
+                    const specifier = node.moduleSpecifier;
+                    if (specifier && ts.isStringLiteral(specifier)) {
+                        const resolved = resolveModule(specifier.text, filePath, compilerOptions);
+                        if (resolved && !imports.includes(resolved))
+                            imports.push(resolved);
+                    }
+                }
+            }
+            ts.forEachChild(node, walk);
+        }
+        walk(sourceFile);
+        graph.set(filePath, imports);
+        for (const dep of imports)
+            parseFile(dep);
+    }
+    // Graph coloring DFS algorithm for cycle detection
+    function findCycles(node) {
+        visited.set(node, 'VISITING');
+        currentStack.push(node);
+        for (const neighbor of graph.get(node) || []) {
+            const state = visited.get(neighbor);
+            if (state === 'VISITING') {
+                const startIdx = currentStack.indexOf(neighbor);
+                const cycle = currentStack.slice(startIdx);
+                cycle.push(neighbor);
+                detectedCycles.push(cycle);
+            }
+            else if (!state) {
+                findCycles(neighbor);
+            }
+        }
+        currentStack.pop();
+        visited.set(node, 'VISITED');
+    }
+    parseFile(entryPoint);
+    findCycles(entryPoint);
+    return detectedCycles;
+}
+function main() {
+    const { entryPatterns, projectPath } = parseArgs();
+    if (entryPatterns.length == 0) {
+        console.error('❌ Error: Please specify at least one entry point or glob pattern (e.g., packages/*/src/index.ts)');
+        process.exit(1);
+    }
+    const entryPoints = [];
+    // Expand glob patterns or fall back to direct paths
+    for (const pattern of entryPatterns) {
+        const matches = fs.globSync ? fs.globSync(pattern) : [pattern];
+        for (const match of matches) {
+            let fullPath = path.resolve(match);
+            if (fs.existsSync(fullPath) && fs.statSync(fullPath).isDirectory()) {
+                const indexTs = path.join(fullPath, 'index.ts');
+                const indexTsx = path.join(fullPath, 'index.tsx');
+                fullPath = fs.existsSync(indexTs) ? indexTs : indexTsx;
+            }
+            if (fs.existsSync(fullPath) && !entryPoints.includes(fullPath)) {
+                entryPoints.push(fullPath);
+            }
+        }
+    }
+    if (entryPoints.length === 0) {
+        console.error('❌ Error: No entry files found matching the provided paths or patterns.');
+        process.exit(1);
+    }
+    console.log(`🔍 Found ${entryPoints.length} entry point(s) for analysis...\n`);
+    let globalHasCycles = false;
+    for (const entryPoint of entryPoints) {
+        const relativeEntry = path.relative(process.cwd(), entryPoint);
+        const cycles = analyzeEntryPoint(entryPoint, projectPath);
+        if (cycles.length > 0) {
+            globalHasCycles = true;
+            console.error(`❌ [${relativeEntry}] — Found ${cycles.length} circular dependencies:`);
+            cycles.forEach((cycle, index) => {
+                const readableCycle = cycle.map((p) => path.relative(process.cwd(), p)).join(' -> ');
+                console.error(`  ${index + 1}) ${readableCycle}`);
+            });
+            console.error('');
+        }
+        else {
+            console.log(`✅ [${relativeEntry}] — Clean!`);
+        }
+    }
+    if (globalHasCycles) {
+        console.error('💥 Validation failed. Circular dependencies detected.');
+        process.exit(1);
+    }
+    else {
+        console.log('🎉 All packages checked. No circular dependencies found!');
+        process.exit(0);
+    }
+}
+main();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/eslint.config.mjs

@@ -0,0 +1,60 @@
+// @ts-check
+
+import eslint from '@eslint/js';
+import { defineConfig } from 'eslint/config';
+import tseslint from 'typescript-eslint';
+
+export default defineConfig([
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+      },
+    },
+  },
+  {
+    rules: {
+      semi: ['error', 'always'],
+      quotes: ['error', 'single', { avoidEscape: true }],
+      '@typescript-eslint/no-floating-promises': 'error',
+      '@typescript-eslint/no-misused-promises': 1,
+      '@typescript-eslint/no-unused-expressions': 'warn',
+      '@typescript-eslint/consistent-type-imports': 1,
+      '@typescript-eslint/no-empty-object-type': 0,
+      '@typescript-eslint/no-non-null-assertion': 0,
+      '@typescript-eslint/no-empty-function': 0,
+      '@typescript-eslint/no-empty-interface': 0,
+      '@typescript-eslint/explicit-function-return-type': 0,
+      '@typescript-eslint/explicit-module-boundary-types': 0,
+      '@typescript-eslint/no-explicit-any': 0,
+      '@typescript-eslint/no-inferrable-types': 0,
+      '@typescript-eslint/no-non-null-asserted-optional-chain': 0,
+      '@typescript-eslint/no-unused-vars': 0,
+      '@typescript-eslint/triple-slash-reference': 0,
+      '@typescript-eslint/no-unsafe-function-type': 0,
+      'no-unused-private-class-members': 'warn',
+      'no-useless-assignment': 'warn',
+      'no-restricted-imports': ['error', 'fs'],
+      'prefer-const': 'warn',
+      'no-async-promise-executor': 0,
+      'no-prototype-builtins': 0,
+    },
+  },
+  {
+    ignores: [
+      '**/dist*',
+      '**/*.d.ts',
+      'website/*',
+      'node_modules/*',
+      'eslint.config.mjs',
+      '**/jest.config.ts',
+      '**/vitest.config.ts',
+      '**/jest.setup.js',
+      '**/jest.d.ts',
+      '**/jest.matchers.ts',
+      'packages/openapi/ui/*',
+    ],
+  },
+]);

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@ts-stack/cycle-detector",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "A fast, zero-dependency CLI tool to detect circular dependencies in TypeScript ESM projects, ignoring type-only imports.",
+  "repository": "https://github.com/ts-stack/cycle-detector",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "imports": {
+    "#lib/*": "./dist/*"
+  },
+  "scripts": {
+    "start": "npm run build && node dist/index.js",
+    "test": "npm run build-test && npm run esm-jest",
+    "esm-jest": "node --experimental-vm-modules --no-warnings=ExperimentalWarning node_modules/jest/bin/jest.js",
+    "build": "tsc -b tsconfig.build.json",
+    "build-test": "tsc -b tsconfig.unit.json",
+    "clean": "rimraf dist*"
+  },
+  "keywords": ["lint", "circular dependencies"],
+  "author": "Kostia Tretiak",
+  "license": "MIT",
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^26.0.0",
+    "eslint": "^10.5.0",
+    "jest": "^29.7.0",
+    "nodemon": "^3.1.14",
+    "prettier": "^3.8.4",
+    "rimraf": "^5.0.10",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.62.0"
+  },
+  "engines": {
+    "node": ">= 22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import ts from 'typescript';
+
+type NodeState = 'VISITING' | 'VISITED';
+
+const graph = new Map<string, string[]>();
+const visited = new Map<string, NodeState>();
+const currentStack: string[] = [];
+const detectedCycles: string[][] = [];
+
+/**
+ * Parses command line arguments to separate options from entry point patterns.
+ */
+function parseArgs() {
+  const args = [...process.argv.slice(2)];
+  let projectPath: string | undefined;
+  const entryPatterns: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--project' || args[i] === '-p') {
+      projectPath = args[i + 1];
+      i++;
+    } else {
+      entryPatterns.push(args[i]);
+    }
+  }
+
+  return { entryPatterns, projectPath };
+}
+
+/**
+ * Checks if an import/export declaration is type-only.
+ * Type-only imports are stripped during compilation and don't cause runtime cycles.
+ */
+function isRuntimeImport(node: ts.ImportDeclaration | ts.ExportDeclaration): boolean {
+  if (ts.isExportDeclaration(node)) {
+    if (!node.moduleSpecifier) return false;
+    return !node.isTypeOnly;
+  }
+
+  if (ts.isImportDeclaration(node)) {
+    if (!node.importClause) return true; // Side-effect import: import './foo'
+    if (node.importClause.isTypeOnly) return false; // import type { X } from './foo'
+
+    // Check individual specifiers: import { type A, B } from './foo'
+    const namedBindings = node.importClause.namedBindings;
+    if (namedBindings && ts.isNamedImports(namedBindings)) {
+      return !namedBindings.elements.every((el) => el.isTypeOnly);
+    }
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Resolves module paths using the TypeScript Compiler API.
+ * Respects tsconfig paths/aliases and ESM extensions.
+ */
+function resolveModule(moduleName: string, containingFile: string, options: ts.CompilerOptions): string | null {
+  const result = ts.resolveModuleName(moduleName, containingFile, options, ts.sys);
+  if (result.resolvedModule && !result.resolvedModule.isExternalLibraryImport) {
+    return result.resolvedModule.resolvedFileName;
+  }
+  return null;
+}
+
+/**
+ * Analyzes a single entry point, builds its dependency graph, and detects cycles.
+ */
+function analyzeEntryPoint(entryPoint: string, projectPath?: string): string[][] {
+  graph.clear();
+  visited.clear();
+  currentStack.length = 0;
+  detectedCycles.length = 0;
+
+  // Locate tsconfig.json automatically if not explicitly provided
+  const configPath = projectPath
+    ? path.resolve(projectPath)
+    : ts.findConfigFile(path.dirname(entryPoint), ts.sys.fileExists, 'tsconfig.json');
+
+  let compilerOptions: ts.CompilerOptions = {};
+
+  if (configPath && fs.existsSync(configPath)) {
+    const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
+    const parsedConfig = ts.parseJsonConfigFileContent(configFile.config, ts.sys, path.dirname(configPath));
+    compilerOptions = parsedConfig.options;
+  }
+
+  // Recursive AST parsing to build the graph
+  function parseFile(filePath: string) {
+    if (graph.has(filePath) || !fs.existsSync(filePath)) return;
+    graph.set(filePath, []);
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);
+    const imports: string[] = [];
+
+    function walk(node: ts.Node) {
+      if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) {
+        if (isRuntimeImport(node)) {
+          const specifier = node.moduleSpecifier;
+          if (specifier && ts.isStringLiteral(specifier)) {
+            const resolved = resolveModule(specifier.text, filePath, compilerOptions);
+            if (resolved && !imports.includes(resolved)) imports.push(resolved);
+          }
+        }
+      }
+      ts.forEachChild(node, walk);
+    }
+
+    walk(sourceFile);
+    graph.set(filePath, imports);
+
+    for (const dep of imports) parseFile(dep);
+  }
+
+  // Graph coloring DFS algorithm for cycle detection
+  function findCycles(node: string) {
+    visited.set(node, 'VISITING');
+    currentStack.push(node);
+
+    for (const neighbor of graph.get(node) || []) {
+      const state = visited.get(neighbor);
+      if (state === 'VISITING') {
+        const startIdx = currentStack.indexOf(neighbor);
+        const cycle = currentStack.slice(startIdx);
+        cycle.push(neighbor);
+        detectedCycles.push(cycle);
+      } else if (!state) {
+        findCycles(neighbor);
+      }
+    }
+
+    currentStack.pop();
+    visited.set(node, 'VISITED');
+  }
+
+  parseFile(entryPoint);
+  findCycles(entryPoint);
+
+  return detectedCycles;
+}
+
+function main() {
+  const { entryPatterns, projectPath } = parseArgs();
+
+  if (entryPatterns.length == 0) {
+    console.error('❌ Error: Please specify at least one entry point or glob pattern (e.g., packages/*/src/index.ts)');
+    process.exit(1);
+  }
+
+  const entryPoints: string[] = [];
+
+  // Expand glob patterns or fall back to direct paths
+  for (const pattern of entryPatterns) {
+    const matches = fs.globSync ? fs.globSync(pattern) : [pattern];
+
+    for (const match of matches) {
+      let fullPath = path.resolve(match);
+
+      if (fs.existsSync(fullPath) && fs.statSync(fullPath).isDirectory()) {
+        const indexTs = path.join(fullPath, 'index.ts');
+        const indexTsx = path.join(fullPath, 'index.tsx');
+        fullPath = fs.existsSync(indexTs) ? indexTs : indexTsx;
+      }
+
+      if (fs.existsSync(fullPath) && !entryPoints.includes(fullPath)) {
+        entryPoints.push(fullPath);
+      }
+    }
+  }
+
+  if (entryPoints.length === 0) {
+    console.error('❌ Error: No entry files found matching the provided paths or patterns.');
+    process.exit(1);
+  }
+
+  console.log(`🔍 Found ${entryPoints.length} entry point(s) for analysis...\n`);
+
+  let globalHasCycles = false;
+
+  for (const entryPoint of entryPoints) {
+    const relativeEntry = path.relative(process.cwd(), entryPoint);
+    const cycles = analyzeEntryPoint(entryPoint, projectPath);
+
+    if (cycles.length > 0) {
+      globalHasCycles = true;
+      console.error(`❌ [${relativeEntry}] — Found ${cycles.length} circular dependencies:`);
+      cycles.forEach((cycle, index) => {
+        const readableCycle = cycle.map((p) => path.relative(process.cwd(), p)).join(' -> ');
+        console.error(`  ${index + 1}) ${readableCycle}`);
+      });
+      console.error('');
+    } else {
+      console.log(`✅ [${relativeEntry}] — Clean!`);
+    }
+  }
+
+  if (globalHasCycles) {
+    console.error('💥 Validation failed. Circular dependencies detected.');
+    process.exit(1);
+  } else {
+    console.log('🎉 All packages checked. No circular dependencies found!');
+    process.exit(0);
+  }
+}
+
+main();