@noahnu/unused-files 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+<!-- MONODEPLOY:BELOW -->
+
+## [0.0.1](https://github.com/noahnu/nodejs-tools/compare/@noahnu/unused-files@0.0.0...@noahnu/unused-files@0.0.1) "@noahnu/unused-files" (2024-01-15)<a name="0.0.1"></a>
+
+### Bug Fixes
+
+* initial release ([f2f8e6b](https://github.com/noahnu/nodejs-tools/commits/f2f8e6b))
+
+

package/README.md

@@ -0,0 +1,33 @@
+# @noahnu/unused-files
+
+## Usage
+
+```sh
+DEBUG=unused-files yarn dlx @noahnu/unused-files --entry src/index.ts --ignore '**/node_modules' --ignore '**/dist' --depth 10 ./src
+```
+
+Or use the Node API:
+
+```ts
+import { findUnusedFiles } from '@noahnu/unused-files'
+
+const result = await findUnusedFiles({
+    entryFiles: ['src/index.ts'],
+
+    // optional
+    sourceDirectories: [process.cwd()],
+    ignorePatterns: ['**/node_modules'],
+    aliases: {
+        '@my/alias': 'path/to/file/index.ts',
+    },
+    depth: 10,
+})
+
+console.log(result.unusedFiles.join('\n'))
+```
+
+## Development
+
+```sh
+yarn workspace @noahnu/unused-files run-local
+```

package/lib/api/index.d.ts

@@ -0,0 +1,30 @@
+export type FindUnusedFilesOptions = {
+    /**
+     * Entry files into the codebase. These files are known to be used and any files that
+     * are dependencies of these entry files are also considered used files.
+     */
+    entryFiles: string[];
+    /**
+     * Directories to search for files within. Relative to the current working directory.
+     */
+    sourceDirectories?: string[];
+    /**
+     * Glob patterns used to exclude directories and files. Files which begin with
+     * a dot (i.e. hidden) are ignored by default.
+     */
+    ignorePatterns?: string[];
+    /**
+     * Custom aliases that are consulted first before attempting to resolve the import path.
+     * It is recommended to rely on package.json aliases over these custom ones.
+     */
+    aliases?: Partial<Record<string, string>>;
+    /**
+     * Maximum depth to traverse. -1 can be used to disable the depth limit (the default).
+     */
+    depth?: number;
+    cwd?: string;
+};
+export type UnusedFilesResult = {
+    unusedFiles: string[];
+};
+export declare function findUnusedFiles({ entryFiles, ignorePatterns, sourceDirectories, aliases, depth, cwd, }: FindUnusedFilesOptions): Promise<UnusedFilesResult>;

package/lib/api/index.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findUnusedFiles = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const debug_1 = __importDefault(require("debug"));
+const fast_glob_1 = __importDefault(require("fast-glob"));
+const walkDependencyTree_1 = require("./walkDependencyTree");
+const debug = (0, debug_1.default)('unused-files');
+async function findUnusedFiles({ entryFiles, ignorePatterns = ['**/node_modules'], sourceDirectories = [], aliases, depth, cwd = process.cwd(), }) {
+    const globFromSource = (source) => fast_glob_1.default.glob(fast_glob_1.default.isDynamicPattern(source) ? source : node_path_1.default.join(source, '**'), {
+        dot: false,
+        ignore: ignorePatterns,
+        absolute: true,
+        cwd,
+    });
+    const sourceDirs = sourceDirectories.length > 0 ? sourceDirectories : [cwd];
+    const files = new Set([].concat(...(await Promise.all(sourceDirs.map((source) => globFromSource(source))))));
+    const unvisitedFiles = new Set(files);
+    for (const entryFile of entryFiles) {
+        const entry = node_path_1.default.resolve(cwd, entryFile);
+        unvisitedFiles.delete(entry);
+        for await (const { source, dependency } of (0, walkDependencyTree_1.walkDependencyTree)(entry, {
+            aliases,
+            depth,
+        })) {
+            if (files.has(dependency)) {
+                debug(`${source}: ${dependency} [dependency]`);
+            }
+            else {
+                debug(`${source}: ${dependency} [unknown dependency]`);
+            }
+            unvisitedFiles.delete(dependency);
+        }
+    }
+    return {
+        unusedFiles: Array.from(unvisitedFiles)
+            .map((abspath) => node_path_1.default.relative(cwd, abspath))
+            .sort(),
+    };
+}
+exports.findUnusedFiles = findUnusedFiles;

package/lib/api/walkDependencyTree.d.ts

@@ -0,0 +1,8 @@
+export declare function walkDependencyTree(source: string, { aliases, visited, depth, }?: {
+    aliases?: Partial<Record<string, string>>;
+    visited?: Set<string>;
+    depth?: number;
+}): AsyncGenerator<{
+    source: string;
+    dependency: string;
+}, void, void>;

package/lib/api/walkDependencyTree.js

@@ -0,0 +1,99 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.walkDependencyTree = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const typescript_estree_1 = require("@typescript-eslint/typescript-estree");
+const debug_1 = __importDefault(require("debug"));
+const debug = (0, debug_1.default)('unused-files:parse');
+const DEFAULT_DEPTH_LIMIT = -1; // no depth limit
+const VALID_EXTENSIONS = new Set(['ts', 'tsx', 'mts', 'cts', 'js', 'mjs', 'cjs']);
+async function* walkDependencyTree(source, { aliases, visited, depth = DEFAULT_DEPTH_LIMIT, } = {}) {
+    const ext = node_path_1.default.extname(source).substring(1);
+    if (!VALID_EXTENSIONS.has(ext)) {
+        debug(`${source}: Unknown file extension '${ext}' [skipping]`);
+        return;
+    }
+    const visitedSet = visited ?? new Set();
+    if (visitedSet.has(source))
+        return;
+    visitedSet.add(source);
+    const code = await node_fs_1.default.promises.readFile(source, { encoding: 'utf-8' });
+    const ast = (0, typescript_estree_1.parse)(code, {
+        allowInvalidAST: true,
+        comment: false,
+        suppressDeprecatedPropertyWarnings: true,
+        errorOnUnknownASTType: false,
+        filePath: source,
+        jsDocParsingMode: 'none',
+    });
+    const importFroms = new Set();
+    const visitors = {
+        [typescript_estree_1.TSESTree.AST_NODE_TYPES.ImportDeclaration]: (node) => {
+            if (node.type === typescript_estree_1.TSESTree.AST_NODE_TYPES.ImportDeclaration) {
+                importFroms.add(node.source.value);
+            }
+        },
+        [typescript_estree_1.TSESTree.AST_NODE_TYPES.CallExpression]: (node) => {
+            if (node.type === typescript_estree_1.TSESTree.AST_NODE_TYPES.CallExpression &&
+                node.callee.type === typescript_estree_1.TSESTree.AST_NODE_TYPES.Identifier &&
+                node.callee.name === 'require') {
+                const arg = node.arguments[0];
+                if (arg.type === typescript_estree_1.TSESTree.AST_NODE_TYPES.Literal) {
+                    if (typeof arg.value === 'string') {
+                        importFroms.add(arg.value);
+                    }
+                }
+                else {
+                    debug(`${source}: Dynamic require expression found at ${node.loc.start}:${node.loc.end}`);
+                }
+            }
+        },
+        [typescript_estree_1.TSESTree.AST_NODE_TYPES.ImportExpression]: (node) => {
+            if (node.type === typescript_estree_1.TSESTree.AST_NODE_TYPES.ImportExpression) {
+                if (node.source.type === typescript_estree_1.TSESTree.AST_NODE_TYPES.Literal) {
+                    if (typeof node.source.value === 'string') {
+                        importFroms.add(node.source.value);
+                    }
+                }
+                else {
+                    debug(`${source}: Dynamic import expression found at ${node.loc.start}:${node.loc.end}`);
+                }
+            }
+        },
+    };
+    for (const body of ast.body) {
+        (0, typescript_estree_1.simpleTraverse)(body, { visitors });
+    }
+    const resolveToAbsPath = (request) => {
+        const aliasedPath = aliases?.[request];
+        if (aliasedPath) {
+            return node_path_1.default.resolve(aliasedPath);
+        }
+        try {
+            return require.resolve(request, { paths: [node_path_1.default.dirname(source)] });
+        }
+        catch { }
+        return undefined;
+    };
+    for (const importFrom of Array.from(importFroms)) {
+        const absPath = resolveToAbsPath(importFrom);
+        if (absPath) {
+            yield { dependency: absPath, source };
+            if (depth === -1 || depth > 0) {
+                yield* walkDependencyTree(absPath, {
+                    aliases,
+                    visited: visitedSet,
+                    depth: depth === -1 ? depth : depth - 1,
+                });
+            }
+        }
+        else {
+            debug(`${source}: Unable to resolve '${importFrom}'`);
+        }
+    }
+}
+exports.walkDependencyTree = walkDependencyTree;

package/lib/bin.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/bin.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const clipanion_1 = require("clipanion");
+const command_1 = require("./command");
+const cli = new clipanion_1.Cli({
+    binaryLabel: '@noahnu/unused-files',
+    binaryName: 'yarn @noahnu/unused-files',
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    binaryVersion: require('../package.json').version,
+    enableCapture: true,
+});
+cli.register(command_1.BaseCommand);
+cli.runExit(process.argv.slice(2));

package/lib/command.d.ts

@@ -0,0 +1,8 @@
+import { Command } from 'clipanion';
+export declare class BaseCommand extends Command {
+    entryFiles: string[];
+    ignorePatterns: string[] | undefined;
+    depth: number | undefined;
+    sourceDirectories: string[];
+    execute(): Promise<number | void>;
+}

package/lib/command.js

@@ -0,0 +1,63 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseCommand = void 0;
+const clipanion_1 = require("clipanion");
+const t = __importStar(require("typanion"));
+const api_1 = require("./api");
+class BaseCommand extends clipanion_1.Command {
+    entryFiles = clipanion_1.Option.Array('--entry', {
+        description: 'Entry files into the codebase. These files are known to be ' +
+            'used and any files that are dependencies of these entry files ' +
+            'are also considered used files.',
+        required: true,
+    });
+    ignorePatterns = clipanion_1.Option.Array('--ignore', {
+        description: 'Glob patterns usued to exclude files. ' +
+            'The patterns are applied during traversal ' +
+            'of the directory tree.',
+        required: false,
+    });
+    depth = clipanion_1.Option.String('--depth', {
+        description: 'Depth limit. Set to -1 to disable.',
+        required: false,
+        validator: t.isNumber(),
+    });
+    sourceDirectories = clipanion_1.Option.Rest();
+    async execute() {
+        const result = await (0, api_1.findUnusedFiles)({
+            entryFiles: this.entryFiles,
+            ignorePatterns: this.ignorePatterns,
+            sourceDirectories: this.sourceDirectories.length
+                ? this.sourceDirectories
+                : [process.cwd()],
+            depth: typeof this.depth === 'undefined'
+                ? -1
+                : parseInt(Math.max(this.depth, -1).toFixed(0), 10),
+        });
+        this.context.stdout.write(result.unusedFiles.join('\n'));
+    }
+}
+exports.BaseCommand = BaseCommand;

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@noahnu/unused-files",
+  "version": "0.0.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/noahnu/nodejs-tools.git",
+    "directory": "packages/unused-files"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "noahnu",
+    "email": "noah@noahnu.com",
+    "url": "https://noahnu.com"
+  },
+  "scripts": {
+    "clean": "run workspace:clean \"$(pwd)\"",
+    "prepack": "run workspace:build \"$(pwd)\"",
+    "run-local": "run -T ts-node --transpileOnly ./src/bin.ts"
+  },
+  "bin": "./lib/bin.js",
+  "main": "./lib/api/index.js",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public",
+    "bin": "./lib/bin.js",
+    "main": "./lib/api/index.js",
+    "types": "./lib/api/index.d.ts"
+  },
+  "files": [
+    "lib"
+  ],
+  "dependencies": {
+    "@types/debug": "^4.1.12",
+    "@typescript-eslint/typescript-estree": "^6.18.1",
+    "clipanion": "4.0.0-rc.2",
+    "debug": "^4.3.4",
+    "fast-glob": "^3.3.2",
+    "typanion": "^3.14.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "@noahnu/internal-test-utils": "0.0.0",
+    "@types/node": "^20.9.0"
+  },
+  "types": "./lib/api/index.d.ts"
+}