knip 6.24.0 → 6.25.0

package/dist/types/config.d.ts

@@ -30,6 +30,10 @@ export type IgnorePatterns = (string | RegExp)[];
 type IgnorableExport = Exclude<SymbolType, 'unknown'>;
 export type IgnoreExportsUsedInFile = boolean | Partial<Record<IgnorableExport, boolean>>;
 export type IgnoreIssues = Record<string, IssueType[]>;
+export type CyclesConfig = {
+    allow?: string[][];
+    dynamicImports?: boolean;
+};
 export type GetImportsAndExportsOptions = {
     skipTypeOnly: boolean;
     isFixExports: boolean;
@@ -43,6 +47,7 @@ export interface Configuration {
     ignoreDependencies: IgnorePatterns;
     ignoreExportsUsedInFile: IgnoreExportsUsedInFile;
     ignoreFiles: NormalizedGlob;
+    cycles: CyclesConfig;
     ignoreIssues: IgnoreIssues;
     ignoreMembers: IgnorePatterns;
     ignoreUnresolved: IgnorePatterns;
@@ -130,6 +135,10 @@ export type PluginVisitorContext = {
     sourceText: string;
     addScript: (script: string) => void;
     addImport: (specifier: string, pos: number, modifiers: number) => void;
+    addImportGlob: (patterns: string[], options?: {
+        base?: string;
+        filter?: RegExp;
+    }) => void;
     markExportRegistered: (name: string) => void;
 };
 export type PluginVisitorObject = VisitorObject;

package/dist/types/issues.d.ts

@@ -3,6 +3,8 @@ import type { Fixes } from './exports.ts';
 export type SymbolType = (typeof SYMBOL_TYPE)[keyof typeof SYMBOL_TYPE];
 export interface IssueSymbol {
     symbol: string;
+    kind?: string;
+    specifier?: string;
     pos?: number;
     line?: number;
     col?: number;
@@ -40,6 +42,7 @@ export type Issues = {
     enumMembers: IssueRecords;
     namespaceMembers: IssueRecords;
     catalog: IssueRecords;
+    cycles: IssueRecords;
 };
 export type IssueType = keyof Issues;
 export type Report = {

package/dist/types/module-graph.d.ts

@@ -29,6 +29,7 @@ export interface Import extends Position {
     readonly filePath: string | undefined;
     readonly identifier: string | undefined;
     readonly isTypeOnly: boolean;
+    readonly modifiers: number;
 }
 export interface ExternalRef {
     readonly specifier: string;
@@ -68,8 +69,14 @@ export type FileNode = {
     exports: ExportMap;
     duplicates: Iterable<Array<IssueSymbol>>;
     scripts: Set<string>;
+    importGlobs: ImportGlob[];
     importedBy: undefined | ImportMaps;
     internalImportCache: undefined | ImportMap;
 };
+export interface ImportGlob {
+    patterns: string[];
+    base?: string;
+    filter?: RegExp;
+}
 export type ModuleGraph = Map<FilePath, FileNode>;
 export {};

package/dist/types/package-json.d.ts

@@ -1,7 +1,6 @@
 import type { PluginMap, WorkspaceConfiguration } from './config.ts';
 type Primitive = null | undefined | string | number | boolean | symbol | bigint;
 type LiteralUnion<LiteralType, BaseType extends Primitive> = LiteralType | (BaseType & Record<never, never>);
-type Dependencies = Record<string, string>;
 type C = 'import' | 'require' | 'node' | 'node-addons' | 'deno' | 'browser' | 'electron' | 'react-native' | 'default';
 type ExportCondition = LiteralUnion<C, string>;
 type Exports = null | string | string[] | {
@@ -25,6 +24,7 @@ type Plugins = PluginConfig<PluginMap>;
 export type Scripts = Record<string, string>;
 export type Catalog = Record<string, string>;
 export type Catalogs = Record<string, Catalog>;
+export type Dependencies = Record<string, string>;
 export type PackageJson = {
     name?: string;
     main?: string;
@@ -57,6 +57,9 @@ export type PackageJson = {
     engines?: Record<string, string>;
     pnpm?: {
         overrides?: Dependencies;
+        packageExtensions?: Record<string, {
+            peerDependencies?: Dependencies;
+        }>;
     };
     knip?: WorkspaceConfiguration;
 } & Plugins;

package/dist/typescript/ast-nodes.d.ts

@@ -1,4 +1,4 @@
-import { type TSEnumDeclaration, type TSModuleDeclaration } from 'oxc-parser';
+import { type TemplateLiteral, type TSEnumDeclaration, type TSModuleDeclaration } from 'oxc-parser';
 import type { GetImportsAndExportsOptions, IgnoreExportsUsedInFile } from '../types/config.ts';
 import type { SymbolType } from '../types/issues.ts';
 import type { ExportMember } from '../types/module-graph.ts';
@@ -16,6 +16,8 @@ export declare const getLineAndCol: (lineStarts: number[], pos: number) => {
 export declare const stripQuotes: (name: string) => string;
 export declare const isStringLiteral: (node: any) => boolean;
 export declare const getStringValue: (node: any) => string | undefined;
+export declare const getScriptFromTemplate: (template: TemplateLiteral) => string;
+export declare const getScriptFromArg: (arg: any) => string | undefined;
 export declare const getSafeScriptFromArgs: (executable: any, argsArray: any) => string | undefined;
 export declare const shouldCountRefs: (ignoreExportsUsedInFile: IgnoreExportsUsedInFile, type: SymbolType) => boolean | undefined;
 export declare function extractNamespaceMembers(decl: TSModuleDeclaration, options: GetImportsAndExportsOptions, lineStarts: number[], getJSDocTags: (start: number) => Set<string>, prefix?: string): ExportMember[];

package/dist/typescript/ast-nodes.js

@@ -1,5 +1,5 @@
 import { parseSync, rawTransferSupported, visitorKeys, } from 'oxc-parser';
-import { DEFAULT_EXTENSIONS, FIX_FLAGS, SYMBOL_TYPE } from '../constants.js';
+import { DEFAULT_EXTENSIONS, FIX_FLAGS, SCRIPT_INTERPOLATION, SYMBOL_TYPE } from '../constants.js';
 import { extname } from '../util/path.js';
 import { timerify } from '../util/Performance.js';
 import { EMPTY_TAGS } from './visitors/jsdoc.js';
@@ -53,6 +53,14 @@ export const getStringValue = (node) => {
         return node.quasis[0].value?.cooked ?? node.quasis[0].value?.raw;
     return undefined;
 };
+export const getScriptFromTemplate = (template) => {
+    const { quasis } = template;
+    let script = quasis[0].value.raw;
+    for (let i = 1; i < quasis.length; i++)
+        script += SCRIPT_INTERPOLATION + quasis[i].value.raw;
+    return script;
+};
+export const getScriptFromArg = (arg) => isStringLiteral(arg) ? getStringValue(arg) : arg?.type === 'TemplateLiteral' ? getScriptFromTemplate(arg) : undefined;
 const SAFE_SCRIPT_ARG = /^[\w@.,:/=+~-]+$/;
 export const getSafeScriptFromArgs = (executable, argsArray) => {
     if (!isStringLiteral(executable))

package/dist/typescript/get-imports-and-exports.js

@@ -24,6 +24,7 @@ const getImportsAndExports = (filePath, sourceText, resolveModule, options, igno
     const aliasedExports = new Map();
     const specifierExportNames = new Set();
     const scripts = new Set();
+    const importGlobs = [];
     const importAliases = new Map();
     const addImportAlias = (aliasName, id, importFilePath) => {
         const aliases = importAliases.get(aliasName);
@@ -58,6 +59,7 @@ const getImportsAndExports = (filePath, sourceText, resolveModule, options, igno
             line: opts.line,
             col: opts.col,
             isTypeOnly: isDts || !!(modifiers & IMPORT_FLAGS.TYPE_ONLY),
+            modifiers,
         });
         const file = internal.get(importFilePath);
         const importMaps = file ?? createImports();
@@ -93,6 +95,10 @@ const getImportsAndExports = (filePath, sourceText, resolveModule, options, igno
         if (!specifier || isBuiltin(specifier))
             return;
         const module = preResolvedModule ?? resolveModule(specifier, filePath);
+        if (modifiers & IMPORT_FLAGS.AUGMENT &&
+            (!module || module.isExternalLibraryImport || isInNodeModules(module.resolvedFileName))) {
+            return;
+        }
         if (module) {
             const resolvedFileName = module.resolvedFileName;
             if (resolvedFileName) {
@@ -134,6 +140,7 @@ const getImportsAndExports = (filePath, sourceText, resolveModule, options, igno
                         line,
                         col,
                         isTypeOnly: isDts || !!(modifiers & IMPORT_FLAGS.TYPE_ONLY),
+                        modifiers,
                     });
                 }
             }
@@ -158,6 +165,7 @@ const getImportsAndExports = (filePath, sourceText, resolveModule, options, igno
                     line,
                     col,
                     isTypeOnly: isDts || !!(modifiers & IMPORT_FLAGS.TYPE_ONLY),
+                    modifiers,
                 });
             }
         }
@@ -266,6 +274,7 @@ const getImportsAndExports = (filePath, sourceText, resolveModule, options, igno
         pluginCtx.sourceText = sourceText;
         pluginCtx.addScript = (s) => scripts.add(s);
         pluginCtx.addImport = (spec, pos, mod) => addImport(spec, undefined, undefined, undefined, pos, mod);
+        pluginCtx.addImportGlob = (patterns, opts) => importGlobs.push({ patterns, base: opts?.base, filter: opts?.filter });
         pluginCtx.markExportRegistered = (name) => registeredCustomElements.add(name);
     }
     const localRefs = _walkAST(result.program, sourceText, filePath, {
@@ -314,6 +323,7 @@ const getImportsAndExports = (filePath, sourceText, resolveModule, options, igno
         exports,
         duplicates: [...aliasedExports.values()],
         scripts,
+        importGlobs,
         importedBy: undefined,
         internalImportCache: undefined,
     };

package/dist/typescript/glob-imports.d.ts

@@ -0,0 +1,3 @@
+import type { ImportGlob } from '../types/module-graph.ts';
+import type { ResolveGlobPattern } from './resolve-module-names.ts';
+export declare function resolveImportGlobs(items: ImportGlob[], containingFile: string, resolveGlobPattern: ResolveGlobPattern, workspaceRoot: string): string[];

package/dist/typescript/glob-imports.js

@@ -0,0 +1,49 @@
+import { existsSync } from 'node:fs';
+import { _syncGlob } from '../util/glob.js';
+import { dirname, isAbsolute, join, toRelative } from '../util/path.js';
+function resolveBaseDir(base, dir, resolveGlobPattern) {
+    if (base.startsWith('.'))
+        return join(dir, base);
+    if (isAbsolute(base))
+        return base;
+    for (const resolved of resolveGlobPattern(base, dir)) {
+        if (resolved !== base && existsSync(resolved))
+            return resolved;
+    }
+    return undefined;
+}
+export function resolveImportGlobs(items, containingFile, resolveGlobPattern, workspaceRoot) {
+    const filePaths = [];
+    const dir = dirname(containingFile);
+    for (const { patterns, base, filter } of items) {
+        if (base !== undefined) {
+            const cwd = resolveBaseDir(base, dir, resolveGlobPattern);
+            if (!cwd)
+                continue;
+            for (const filePath of _syncGlob({ patterns, cwd })) {
+                if (!filter || filter.test(`./${toRelative(filePath, cwd)}`))
+                    filePaths.push(filePath);
+            }
+        }
+        else {
+            const resolved = [];
+            for (const pattern of patterns) {
+                const isNegated = pattern[0] === '!';
+                const specifier = isNegated ? pattern.slice(1) : pattern;
+                if (specifier[0] === '/') {
+                    const rooted = join(workspaceRoot, specifier);
+                    resolved.push(isNegated ? `!${rooted}` : rooted);
+                }
+                else {
+                    for (const p of resolveGlobPattern(pattern, dir))
+                        resolved.push(p);
+                }
+            }
+            if (resolved.length === 0)
+                continue;
+            for (const filePath of _syncGlob({ patterns: resolved, cwd: dir }))
+                filePaths.push(filePath);
+        }
+    }
+    return filePaths;
+}

package/dist/typescript/resolve-module-names.d.ts

@@ -9,6 +9,8 @@ type ScopedRootDirs = Array<{
     rootDirs: string[];
 }>;
 export declare function clearModuleResolutionCaches(): void;
+export type ResolveGlobPattern = (pattern: string, dir: string) => string[];
+export declare function createGlobAliasResolver(scopedPaths: ScopedPaths | undefined): ResolveGlobPattern;
 export declare function createCustomModuleResolver(compilerOptions: {
     scopedPaths?: ScopedPaths;
     scopedRootDirs?: ScopedRootDirs;

package/dist/typescript/resolve-module-names.js

@@ -3,7 +3,7 @@ import { isBuiltin } from 'node:module';
 import { DEFAULT_EXTENSIONS, DTS_EXTENSIONS } from '../constants.js';
 import { sanitizeSpecifier } from '../util/modules.js';
 import { timerify } from '../util/Performance.js';
-import { dirname, extname, isAbsolute, isInNodeModules, join } from '../util/path.js';
+import { dirname, extname, isAbsolute, isInNodeModules, join, toPosix } from '../util/path.js';
 import { _createSyncModuleResolver, _resolveModuleSync } from '../util/resolve.js';
 function pickStringTarget(value) {
     if (typeof value === 'string')
@@ -56,6 +56,40 @@ function compileRootDirs(scopedRootDirs) {
     scoped.sort((a, b) => b.scope.length - a.scope.length);
     return scoped;
 }
+export function createGlobAliasResolver(scopedPaths) {
+    const mappings = compilePathMappings(scopedPaths);
+    return (pattern, dir) => {
+        if (!mappings)
+            return [pattern];
+        const isNegated = pattern[0] === '!';
+        const specifier = isNegated ? pattern.slice(1) : pattern;
+        let best;
+        for (const mapping of mappings) {
+            const { prefix, wildcard, scope } = mapping;
+            if (dir !== scope && !dir.startsWith(`${scope}/`))
+                continue;
+            const matches = wildcard
+                ? specifier.startsWith(prefix)
+                : specifier === prefix || specifier.startsWith(`${prefix}/`);
+            if (!matches)
+                continue;
+            if (!best ||
+                scope.length > best.scope.length ||
+                (scope.length === best.scope.length && prefix.length > best.prefix.length))
+                best = mapping;
+        }
+        if (!best)
+            return [pattern];
+        const captured = specifier.slice(best.prefix.length);
+        const resolved = [];
+        for (const value of best.values) {
+            const starIdx = value.indexOf('*');
+            const mapped = toPosix(starIdx >= 0 ? value.slice(0, starIdx) + captured + value.slice(starIdx + 1) : value + captured);
+            resolved.push(isNegated ? `!${mapped}` : mapped);
+        }
+        return resolved;
+    };
+}
 export function createCustomModuleResolver(compilerOptions, customCompilerExtensions, toSourceFilePath, findWorkspaceManifestImports, tsConfigFile) {
     const customCompilerExtensionsSet = new Set(customCompilerExtensions);
     const hasCustomExts = customCompilerExtensionsSet.size > 0;

package/dist/typescript/visitors/calls.js

@@ -1,6 +1,6 @@
 import { IMPORT_FLAGS, OPAQUE } from '../../constants.js';
 import { addValue } from '../../util/module-graph.js';
-import { getSafeScriptFromArgs, getStringValue, isStringLiteral } from '../ast-nodes.js';
+import { getSafeScriptFromArgs, getScriptFromArg, getStringValue, isStringLiteral } from '../ast-nodes.js';
 import { isShadowed } from './walk.js';
 function getRegisteredCustomElement(node, s) {
     const callee = node.callee;
@@ -162,11 +162,9 @@ export function handleCallExpression(node, s) {
         if (method) {
             const arg = node.arguments[0];
             if (CHILD_PROCESS_COMMAND_METHODS.has(method)) {
-                if (isStringLiteral(arg)) {
-                    const command = getStringValue(arg);
-                    if (command)
-                        s.scripts.add(command);
-                }
+                const command = getScriptFromArg(arg);
+                if (command)
+                    s.scripts.add(command);
                 return;
             }
             if (CHILD_PROCESS_FILE_METHODS.has(method)) {

package/dist/typescript/visitors/imports.js

@@ -26,16 +26,16 @@ export function handleVariableDeclarator(node, s) {
                             : undefined;
                     const localName = prop.value?.type === 'Identifier' ? prop.value.name : importedName;
                     const alias = localName !== importedName ? localName : undefined;
-                    s.addImport(specifier, importedName, alias, undefined, prop.key?.start ?? prop.start, IMPORT_FLAGS.NONE);
+                    s.addImport(specifier, importedName, alias, undefined, prop.key?.start ?? prop.start, IMPORT_FLAGS.DYNAMIC);
                 }
                 else if (prop.type === 'RestElement' && prop.argument?.type === 'Identifier') {
-                    s.addImport(specifier, IMPORT_STAR, prop.argument.name, undefined, prop.start, IMPORT_FLAGS.NONE);
+                    s.addImport(specifier, IMPORT_STAR, prop.argument.name, undefined, prop.start, IMPORT_FLAGS.DYNAMIC);
                 }
             }
         }
         else if (node.id.type === 'Identifier') {
             if (init.type === 'AwaitExpression') {
-                s.addImport(specifier, 'default', node.id.name, undefined, importExpr.source.start, IMPORT_FLAGS.NONE);
+                s.addImport(specifier, 'default', node.id.name, undefined, importExpr.source.start, IMPORT_FLAGS.DYNAMIC);
                 const resolved = s.resolveModule(specifier, s.filePath);
                 if (resolved && !resolved.isExternalLibraryImport && !isInNodeModules(resolved.resolvedFileName)) {
                     s.localImportMap.set(node.id.name, {
@@ -47,11 +47,11 @@ export function handleVariableDeclarator(node, s) {
                 }
             }
             else {
-                s.addImport(specifier, undefined, undefined, undefined, importExpr.source.start, IMPORT_FLAGS.OPAQUE);
+                s.addImport(specifier, undefined, undefined, undefined, importExpr.source.start, IMPORT_FLAGS.DYNAMIC | IMPORT_FLAGS.OPAQUE);
             }
         }
         else {
-            s.addImport(specifier, undefined, undefined, undefined, importExpr.source.start, IMPORT_FLAGS.OPAQUE);
+            s.addImport(specifier, undefined, undefined, undefined, importExpr.source.start, IMPORT_FLAGS.DYNAMIC | IMPORT_FLAGS.OPAQUE);
         }
         return;
     }
@@ -117,10 +117,10 @@ export function handleVariableDeclarator(node, s) {
                     }
                 }
                 else if (binding?.type === 'Identifier') {
-                    s.addImport(specifier, 'default', binding.name, undefined, imp.source.start, IMPORT_FLAGS.NONE);
+                    s.addImport(specifier, 'default', binding.name, undefined, imp.source.start, IMPORT_FLAGS.DYNAMIC);
                 }
                 else {
-                    s.addImport(specifier, undefined, undefined, undefined, imp.source.start, IMPORT_FLAGS.SIDE_EFFECTS);
+                    s.addImport(specifier, undefined, undefined, undefined, imp.source.start, IMPORT_FLAGS.DYNAMIC | IMPORT_FLAGS.SIDE_EFFECTS);
                 }
             }
         }
@@ -257,6 +257,6 @@ export function handleImportExpression(node, s) {
         return;
     const specifier = getStringValue(node.source);
     if (specifier) {
-        s.addImport(specifier, undefined, undefined, undefined, node.source.start, IMPORT_FLAGS.OPAQUE);
+        s.addImport(specifier, undefined, undefined, undefined, node.source.start, IMPORT_FLAGS.DYNAMIC | IMPORT_FLAGS.OPAQUE);
     }
 }

package/dist/typescript/visitors/script-visitors.js

@@ -1,12 +1,12 @@
+import { getScriptFromTemplate } from '../ast-nodes.js';
 export function createBunShellVisitor(ctx) {
     return {
         TaggedTemplateExpression(node) {
             const tag = node.tag;
             if (tag.type === 'Identifier' && tag.name === '$') {
-                for (const q of node.quasi.quasis) {
-                    if (q.value.raw)
-                        ctx.addScript(q.value.raw);
-                }
+                const script = getScriptFromTemplate(node.quasi);
+                if (script)
+                    ctx.addScript(script);
             }
         },
     };

package/dist/typescript/visitors/walk.js

@@ -213,9 +213,8 @@ const coreVisitorObject = {
         state.nsRanges.push([node.start, node.end]);
         if (node.kind !== 'global' && isStringLiteral(node.id)) {
             const specifier = getStringValue(node.id);
-            if (specifier.startsWith('.'))
-                for (const name of collectAugmentationRefs(node))
-                    state.addImport(specifier, name, undefined, undefined, node.id.start, IMPORT_FLAGS.TYPE_ONLY);
+            for (const name of collectAugmentationRefs(node))
+                state.addImport(specifier, name, undefined, undefined, node.id.start, IMPORT_FLAGS.TYPE_ONLY | IMPORT_FLAGS.AUGMENT);
         }
     },
     ClassDeclaration(node) {

package/dist/util/cli-arguments.d.ts

@@ -1,9 +1,10 @@
-export declare const helpText = "\u2702\uFE0F  Find unused dependencies, exports and files in your JavaScript and TypeScript projects\n\nUsage: knip [options]\n\nOptions:\n  -h, --help                   Print this help text\n  -V, --version                Print version\n  -n, --no-progress            Don't show dynamic progress updates (automatically enabled in CI environments)\n  -c, --config [file]          Configuration file path\n                               (default: [.]knip.json[c], knip.(js|ts), knip.config.(js|ts) or package.json#knip)\n      --use-tsconfig-files     Use tsconfig.json to define project files (override `project` patterns)\n  -t, --tsConfig [file]        TypeScript configuration path (default: tsconfig.json)\n\nMode\n      --cache                  Enable caching\n      --cache-location         Change cache location (default: node_modules/.cache/knip)\n      --include-entry-exports  Include entry files when reporting unused exports\n      --no-gitignore           Don't respect .gitignore\n  -p, --production             Analyze only production source files (e.g. no test files, devDependencies)\n  -s, --strict                 Consider only direct dependencies of workspace (not devDependencies, not other workspaces)\n  -w, --watch                  Watch mode\n\nScope\n  -W, --workspace [filter]     Filter workspaces by name, directory, or glob (can be repeated)\n  -D, --directory [dir]        Run process from a different directory (default: cwd)\n      --include                Report only provided issue type(s), can be comma-separated or repeated (1)\n      --exclude                Exclude provided issue type(s) from report, can be comma-separated or repeated (1)\n      --dependencies           Shortcut for --include dependencies,unlisted,binaries,unresolved,catalog\n      --exports                Shortcut for --include exports,nsExports,types,nsTypes,enumMembers,namespaceMembers,duplicates\n      --files                  Shortcut for --include files\n      --tags                   Include or exclude tagged exports\n\nFix\n  -f, --fix                    Fix issues (modifies files in your repo)\n      --fix-type               Fix only issues of type, can be comma-separated or repeated (2)\n      --allow-remove-files     Allow Knip to remove files (with --fix)\n  -F, --format                 Format modified files after --fix using the local formatter\n\nOutput\n      --preprocessor           Preprocess the results before providing it to the reporter(s), can be repeated\n      --preprocessor-options   Pass extra options to the preprocessor (as JSON string, see --reporter-options example)\n      --reporter               Select reporter (default: symbols), can be repeated (3)\n      --reporter-options       Pass extra options to the reporter (as JSON string, see example)\n      --no-config-hints        Suppress configuration hints\n      --no-tag-hints           Suppress tag hints\n      --treat-config-hints-as-errors   Exit with non-zero code (1) if there are any configuration hints\n      --treat-tag-hints-as-errors      Exit with non-zero code (1) if there are any tag hints\n      --max-issues             Maximum number of total issues before non-zero exit code (default: 0)\n      --max-show-issues        Maximum number of issues to display per type\n      --no-exit-code           Always exit with code zero (0)\n\nTroubleshooting\n  -d, --debug                  Show debug output\n      --memory                 Measure memory usage and display data table\n      --memory-realtime        Log memory usage in realtime\n      --performance            Measure count and running time of key functions and display stats table\n      --performance-fn [name]  Measure only function [name]\n  -u, --duration               Print total running time (zero overhead, no instrumentation)\n      --trace                  Show trace output\n      --trace-dependency [name]  Show files that import the named dependency\n      --trace-export [name]    Show trace output for named export(s)\n      --trace-file [file]      Show trace output for exports in file\n\n(1) Issue types: files, dependencies, unlisted, unresolved, exports, nsExports, types, nsTypes, enumMembers, namespaceMembers, duplicates, catalog\n(2) Fixable issue types: dependencies, exports, types, files, catalog\n(3) Built-in reporters: symbols (default), compact, codeowners, json, codeclimate, markdown, disclosure, github-actions\n\nExamples:\n\n$ knip\n$ knip --production\n$ knip --workspace packages/client --include files,dependencies\n$ knip --workspace @myorg/* --workspace '!@myorg/legacy'\n$ knip --workspace './apps/*' --workspace '@shared/utils'\n$ knip -c ./config/knip.json --reporter compact\n$ knip --reporter codeowners --reporter-options '{\"path\":\".github/CODEOWNERS\"}'\n$ knip --tags=-lintignore\n\nWebsite: https://knip.dev";
+export declare const helpText = "\u2702\uFE0F  Find unused dependencies, exports and files in your JavaScript and TypeScript projects\n\nUsage: knip [options]\n\nOptions:\n  -h, --help                   Print this help text\n  -V, --version                Print version\n  -n, --no-progress            Don't show dynamic progress updates (automatically enabled in CI environments)\n  -c, --config [file]          Configuration file path\n                               (default: [.]knip.json[c], knip.(js|ts), knip.config.(js|ts) or package.json#knip)\n      --use-tsconfig-files     Use tsconfig.json to define project files (override `project` patterns)\n  -t, --tsConfig [file]        TypeScript configuration path (default: tsconfig.json)\n\nMode\n      --cache                  Enable caching\n      --cache-location         Change cache location (default: node_modules/.cache/knip)\n      --include-entry-exports  Include entry files when reporting unused exports\n      --no-gitignore           Don't respect .gitignore\n  -p, --production             Analyze only production source files (e.g. no test files, devDependencies)\n  -s, --strict                 Consider only direct dependencies of workspace (not devDependencies, not other workspaces)\n  -w, --watch                  Watch mode\n\nScope\n  -W, --workspace [filter]     Filter workspaces by name, directory, or glob (can be repeated)\n  -D, --directory [dir]        Run process from a different directory (default: cwd)\n      --include                Report only provided issue type(s), can be comma-separated or repeated (1)\n      --exclude                Exclude provided issue type(s) from report, can be comma-separated or repeated (1)\n      --dependencies           Shortcut for --include dependencies,unlisted,binaries,unresolved,catalog\n      --exports                Shortcut for --include exports,nsExports,types,nsTypes,enumMembers,namespaceMembers,duplicates\n      --files                  Shortcut for --include files\n      --cycles                 Shortcut for --include cycles (circular dependencies)\n      --tags                   Include or exclude tagged exports\n\nFix\n  -f, --fix                    Fix issues (modifies files in your repo)\n      --fix-type               Fix only issues of type, can be comma-separated or repeated (2)\n      --allow-remove-files     Allow Knip to remove files (with --fix)\n  -F, --format                 Format modified files after --fix using the local formatter\n\nOutput\n      --preprocessor           Preprocess the results before providing it to the reporter(s), can be repeated\n      --preprocessor-options   Pass extra options to the preprocessor (as JSON string, see --reporter-options example)\n      --reporter               Select reporter (default: symbols), can be repeated (3)\n      --reporter-options       Pass extra options to the reporter (as JSON string, see example)\n      --no-config-hints        Suppress configuration hints\n      --no-tag-hints           Suppress tag hints\n      --treat-config-hints-as-errors   Exit with non-zero code (1) if there are any configuration hints\n      --treat-tag-hints-as-errors      Exit with non-zero code (1) if there are any tag hints\n      --max-issues             Maximum number of total issues before non-zero exit code (default: 0)\n      --max-show-issues        Maximum number of issues to display per type\n      --no-exit-code           Always exit with code zero (0)\n\nTroubleshooting\n  -d, --debug                  Show debug output\n      --memory                 Measure memory usage and display data table\n      --memory-realtime        Log memory usage in realtime\n      --performance            Measure count and running time of key functions and display stats table\n      --performance-fn [name]  Measure only function [name]\n  -u, --duration               Print total running time (zero overhead, no instrumentation)\n      --trace                  Show trace output\n      --trace-dependency [name]  Show files that import the named dependency\n      --trace-export [name]    Show trace output for named export(s)\n      --trace-file [file]      Show trace output for exports in file\n\n(1) Issue types: files, dependencies, unlisted, unresolved, exports, nsExports, types, nsTypes, enumMembers, namespaceMembers, duplicates, catalog, cycles\n(2) Fixable issue types: dependencies, exports, types, files, catalog\n(3) Built-in reporters: symbols (default), compact, codeowners, cycles, json, codeclimate, markdown, disclosure, github-actions\n\nExamples:\n\n$ knip\n$ knip --production\n$ knip --workspace packages/client --include files,dependencies\n$ knip --workspace @myorg/* --workspace '!@myorg/legacy'\n$ knip --workspace './apps/*' --workspace '@shared/utils'\n$ knip -c ./config/knip.json --reporter compact\n$ knip --reporter codeowners --reporter-options '{\"path\":\".github/CODEOWNERS\"}'\n$ knip --tags=-lintignore\n\nWebsite: https://knip.dev";
 export type ParsedCLIArgs = ReturnType<typeof parseCLIArgs>;
 export default function parseCLIArgs(): {
     cache?: boolean | undefined;
     'cache-location'?: string | undefined;
     config?: string | undefined;
+    cycles?: boolean | undefined;
     debug?: boolean | undefined;
     dependencies?: boolean | undefined;
     directory?: string | undefined;

package/dist/util/cli-arguments.js

@@ -29,6 +29,7 @@ Scope
       --dependencies           Shortcut for --include dependencies,unlisted,binaries,unresolved,catalog
       --exports                Shortcut for --include exports,nsExports,types,nsTypes,enumMembers,namespaceMembers,duplicates
       --files                  Shortcut for --include files
+      --cycles                 Shortcut for --include cycles (circular dependencies)
       --tags                   Include or exclude tagged exports
 
 Fix
@@ -62,9 +63,9 @@ Troubleshooting
       --trace-export [name]    Show trace output for named export(s)
       --trace-file [file]      Show trace output for exports in file
 
-(1) Issue types: files, dependencies, unlisted, unresolved, exports, nsExports, types, nsTypes, enumMembers, namespaceMembers, duplicates, catalog
+(1) Issue types: files, dependencies, unlisted, unresolved, exports, nsExports, types, nsTypes, enumMembers, namespaceMembers, duplicates, catalog, cycles
 (2) Fixable issue types: dependencies, exports, types, files, catalog
-(3) Built-in reporters: symbols (default), compact, codeowners, json, codeclimate, markdown, disclosure, github-actions
+(3) Built-in reporters: symbols (default), compact, codeowners, cycles, json, codeclimate, markdown, disclosure, github-actions
 
 Examples:
 
@@ -84,6 +85,7 @@ export default function parseCLIArgs() {
             cache: { type: 'boolean' },
             'cache-location': { type: 'string' },
             config: { type: 'string', short: 'c' },
+            cycles: { type: 'boolean' },
             debug: { type: 'boolean', short: 'd' },
             dependencies: { type: 'boolean' },
             directory: { type: 'string', short: 'D' },

package/dist/util/create-options.d.ts

@@ -9,6 +9,7 @@ export declare const createOptions: (options: CreateOptions) => Promise<{
     config: string | undefined;
     configFilePath: string | undefined;
     cwd: string;
+    cycles: boolean;
     dependencies: boolean;
     exports: boolean;
     files: boolean;
@@ -30,6 +31,7 @@ export declare const createOptions: (options: CreateOptions) => Promise<{
     isProduction: boolean;
     isReportDependencies: boolean;
     isReportExports: boolean;
+    isReportCycles: boolean;
     isReportFiles: boolean;
     isReportTypes: boolean;
     isReportValues: boolean;
@@ -193,6 +195,11 @@ export declare const createOptions: (options: CreateOptions) => Promise<{
             entry?: string | string[] | undefined;
             project?: string | string[] | undefined;
         } | undefined;
+        eve?: string | boolean | string[] | {
+            config?: string | string[] | undefined;
+            entry?: string | string[] | undefined;
+            project?: string | string[] | undefined;
+        } | undefined;
         execa?: string | boolean | string[] | {
             config?: string | string[] | undefined;
             entry?: string | string[] | undefined;
@@ -213,6 +220,11 @@ export declare const createOptions: (options: CreateOptions) => Promise<{
             entry?: string | string[] | undefined;
             project?: string | string[] | undefined;
         } | undefined;
+        fumadocs?: string | boolean | string[] | {
+            config?: string | string[] | undefined;
+            entry?: string | string[] | undefined;
+            project?: string | string[] | undefined;
+        } | undefined;
         gatsby?: string | boolean | string[] | {
             config?: string | string[] | undefined;
             entry?: string | string[] | undefined;
@@ -829,7 +841,7 @@ export declare const createOptions: (options: CreateOptions) => Promise<{
             project?: string | string[] | undefined;
         } | undefined;
         $schema?: string | undefined;
-        rules?: Partial<Record<"binaries" | "catalog" | "dependencies" | "devDependencies" | "duplicates" | "enumMembers" | "exports" | "files" | "namespaceMembers" | "nsExports" | "nsTypes" | "optionalPeerDependencies" | "types" | "unlisted" | "unresolved", "error" | "off" | "warn">> | undefined;
+        rules?: Partial<Record<"binaries" | "catalog" | "cycles" | "dependencies" | "devDependencies" | "duplicates" | "enumMembers" | "exports" | "files" | "namespaceMembers" | "nsExports" | "nsTypes" | "optionalPeerDependencies" | "types" | "unlisted" | "unresolved", "error" | "off" | "warn">> | undefined;
         entry?: string | string[] | undefined;
         project?: string | string[] | undefined;
         paths?: Record<string, string[]> | undefined;
@@ -840,7 +852,11 @@ export declare const createOptions: (options: CreateOptions) => Promise<{
         ignoreMembers?: (string | RegExp)[] | undefined;
         ignoreUnresolved?: (string | RegExp)[] | undefined;
         ignoreExportsUsedInFile?: boolean | Record<string, boolean | undefined> | undefined;
-        ignoreIssues?: Record<string, ("binaries" | "catalog" | "dependencies" | "devDependencies" | "duplicates" | "enumMembers" | "exports" | "files" | "namespaceMembers" | "nsExports" | "nsTypes" | "optionalPeerDependencies" | "types" | "unlisted" | "unresolved")[]> | undefined;
+        ignoreIssues?: Record<string, ("binaries" | "catalog" | "cycles" | "dependencies" | "devDependencies" | "duplicates" | "enumMembers" | "exports" | "files" | "namespaceMembers" | "nsExports" | "nsTypes" | "optionalPeerDependencies" | "types" | "unlisted" | "unresolved")[]> | undefined;
+        cycles?: {
+            allow?: string[][] | undefined;
+            dynamicImports?: boolean | undefined;
+        } | undefined;
         ignoreWorkspaces?: string[] | undefined;
         includeEntryExports?: boolean | undefined;
         compilers?: Record<string, true | import("../compilers/types.ts").CompilerAsync | import("../compilers/types.ts").CompilerSync> | undefined;
@@ -849,8 +865,8 @@ export declare const createOptions: (options: CreateOptions) => Promise<{
         tags?: string[] | undefined;
         treatConfigHintsAsErrors?: boolean | undefined;
         treatTagHintsAsErrors?: boolean | undefined;
-        include?: ("binaries" | "catalog" | "dependencies" | "devDependencies" | "duplicates" | "enumMembers" | "exports" | "files" | "namespaceMembers" | "nsExports" | "nsTypes" | "optionalPeerDependencies" | "types" | "unlisted" | "unresolved")[] | undefined;
-        exclude?: ("binaries" | "catalog" | "dependencies" | "devDependencies" | "duplicates" | "enumMembers" | "exports" | "files" | "namespaceMembers" | "nsExports" | "nsTypes" | "optionalPeerDependencies" | "types" | "unlisted" | "unresolved")[] | undefined;
+        include?: ("binaries" | "catalog" | "cycles" | "dependencies" | "devDependencies" | "duplicates" | "enumMembers" | "exports" | "files" | "namespaceMembers" | "nsExports" | "nsTypes" | "optionalPeerDependencies" | "types" | "unlisted" | "unresolved")[] | undefined;
+        exclude?: ("binaries" | "catalog" | "cycles" | "dependencies" | "devDependencies" | "duplicates" | "enumMembers" | "exports" | "files" | "namespaceMembers" | "nsExports" | "nsTypes" | "optionalPeerDependencies" | "types" | "unlisted" | "unresolved")[] | undefined;
         workspaces?: Record<string, {
             angular?: string | boolean | string[] | {
                 config?: string | string[] | undefined;
@@ -1002,6 +1018,11 @@ export declare const createOptions: (options: CreateOptions) => Promise<{
                 entry?: string | string[] | undefined;
                 project?: string | string[] | undefined;
             } | undefined;
+            eve?: string | boolean | string[] | {
+                config?: string | string[] | undefined;
+                entry?: string | string[] | undefined;
+                project?: string | string[] | undefined;
+            } | undefined;
             execa?: string | boolean | string[] | {
                 config?: string | string[] | undefined;
                 entry?: string | string[] | undefined;
@@ -1022,6 +1043,11 @@ export declare const createOptions: (options: CreateOptions) => Promise<{
                 entry?: string | string[] | undefined;
                 project?: string | string[] | undefined;
             } | undefined;
+            fumadocs?: string | boolean | string[] | {
+                config?: string | string[] | undefined;
+                entry?: string | string[] | undefined;
+                project?: string | string[] | undefined;
+            } | undefined;
             gatsby?: string | boolean | string[] | {
                 config?: string | string[] | undefined;
                 entry?: string | string[] | undefined;
@@ -1647,13 +1673,14 @@ export declare const createOptions: (options: CreateOptions) => Promise<{
             ignoreMembers?: (string | RegExp)[] | undefined;
             ignoreUnresolved?: (string | RegExp)[] | undefined;
             ignoreExportsUsedInFile?: boolean | Record<string, boolean | undefined> | undefined;
-            ignoreIssues?: Record<string, ("binaries" | "catalog" | "dependencies" | "devDependencies" | "duplicates" | "enumMembers" | "exports" | "files" | "namespaceMembers" | "nsExports" | "nsTypes" | "optionalPeerDependencies" | "types" | "unlisted" | "unresolved")[]> | undefined;
+            ignoreIssues?: Record<string, ("binaries" | "catalog" | "cycles" | "dependencies" | "devDependencies" | "duplicates" | "enumMembers" | "exports" | "files" | "namespaceMembers" | "nsExports" | "nsTypes" | "optionalPeerDependencies" | "types" | "unlisted" | "unresolved")[]> | undefined;
             includeEntryExports?: boolean | undefined;
         }> | undefined;
     };
     rules: {
         binaries: import("../types/issues.ts").IssueSeverity;
         catalog: import("../types/issues.ts").IssueSeverity;
+        cycles: import("../types/issues.ts").IssueSeverity;
         dependencies: import("../types/issues.ts").IssueSeverity;
         devDependencies: import("../types/issues.ts").IssueSeverity;
         duplicates: import("../types/issues.ts").IssueSeverity;

package/dist/util/create-options.js

@@ -4,7 +4,7 @@ import { knipConfigurationSchema } from '../schema/configuration.js';
 import { getCatalogContainer } from './catalog.js';
 import { ConfigurationError } from './errors.js';
 import { findFile, loadJSON } from './fs.js';
-import { getIncludedIssueTypes, shorthandDeps, shorthandExports, shorthandFiles } from './get-included-issue-types.js';
+import { getIncludedIssueTypes, shorthandCycles, shorthandDeps, shorthandExports, shorthandFiles, } from './get-included-issue-types.js';
 import { defaultRules } from './issue-initializers.js';
 import { loadResolvedConfigFile } from './load-config.js';
 import { _load } from './loader.js';
@@ -82,6 +82,7 @@ export const createOptions = async (options) => {
             ...(args.dependencies ? shorthandDeps : []),
             ...(args.exports ? shorthandExports : []),
             ...(args.files ? shorthandFiles : []),
+            ...(args.cycles ? shorthandCycles : []),
         ],
     });
     for (const [key, value] of Object.entries(includedIssueTypes)) {
@@ -98,6 +99,7 @@ export const createOptions = async (options) => {
         config: args.config,
         configFilePath,
         cwd,
+        cycles: args.cycles ?? false,
         dependencies: args.dependencies ?? false,
         exports: args.exports ?? false,
         files: args.files ?? false,
@@ -128,6 +130,7 @@ export const createOptions = async (options) => {
             includedIssueTypes.enumMembers ||
             includedIssueTypes.namespaceMembers ||
             includedIssueTypes.duplicates,
+        isReportCycles: includedIssueTypes.cycles,
         isReportFiles: includedIssueTypes.files,
         isReportTypes: includedIssueTypes.types ||
             includedIssueTypes.nsTypes ||

package/dist/util/get-included-issue-types.d.ts

@@ -10,5 +10,6 @@ export declare const defaultExcludedIssueTypes: string[];
 export declare const shorthandDeps: string[];
 export declare const shorthandExports: string[];
 export declare const shorthandFiles: string[];
+export declare const shorthandCycles: string[];
 export declare const getIncludedIssueTypes: (options: GetIncludedIssueTypesOptions) => Report;
 export {};