depvitals 0.0.1 → 0.1.1

package/dist/scanner/sourceFiles.js

@@ -0,0 +1,190 @@
+/**
+ * Source file discovery.
+ *
+ * This module answers exactly one question: "which source files should DepVitals inspect?". It
+ * walks a single Node.js project tree and returns the supported JavaScript/TypeScript files without
+ * parsing them.
+ *
+ * It deliberately does not:
+ * - read, parse or execute any discovered file (that belongs to the analyzers / specifier extractor);
+ * - decide whether anything is used, unused or missing;
+ * - parse `.gitignore` or honor custom ignore configuration (`v0.1.0` uses a fixed built-in set);
+ * - follow symlinks, which avoids cycles and scanning content outside the intended project tree;
+ * - mutate the analyzed project.
+ *
+ * Traversal uses `fs.readdir` with `withFileTypes` so ignored directories are pruned before descent
+ * instead of walking every subtree and filtering afterwards. The result is sorted deterministically
+ * so the same tree always yields the same order.
+ */
+import { lstat, readdir } from 'node:fs/promises';
+import { extname, join, resolve } from 'node:path';
+/**
+ * The supported source and declaration extensions for `v0.1.0`.
+ *
+ * Multi-part declaration files are included through their base extension:
+ * - `foo.d.ts`    resolves to `.ts`
+ * - `foo.d.mts`   resolves to `.mts`
+ * - `foo.d.cts`   resolves to `.cts`
+ *
+ * The rule that matters is only "never exclude a name because it starts with `.d`".
+ */
+const SUPPORTED_EXTENSIONS = new Set([
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.cjs',
+    '.ts',
+    '.tsx',
+    '.mts',
+    '.cts',
+]);
+/**
+ * Directories pruned by name wherever they appear. These are generated, vendor or tooling trees
+ * that must never be enumerated (in particular `node_modules`).
+ */
+const IGNORED_DIRECTORY_NAMES = new Set([
+    '.git',
+    'node_modules',
+    'dist',
+    'build',
+    'coverage',
+    'out',
+    '.cache',
+    '.turbo',
+    '.next',
+    '.nuxt',
+]);
+/**
+ * Operational error for source discovery. The `code` lets callers (the CLI in a later step) render
+ * a clean message without matching on error strings.
+ */
+export class SourceFilesError extends Error {
+    code;
+    constructor(message, code, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = 'SourceFilesError';
+        this.code = code;
+    }
+}
+/**
+ * Discover the supported JavaScript/TypeScript source files of the project rooted at `projectRoot`.
+ *
+ * The supplied root is resolved to an absolute path; `process.cwd()` is never changed and the
+ * target project is never read as code or written to.
+ *
+ * The returned paths are absolute and sorted lexicographically so the same tree always yields the
+ * same order.
+ *
+ * @throws {SourceFilesError} when the root is missing, is not a directory, or cannot be read.
+ */
+export async function discoverSourceFiles(projectRoot) {
+    const root = resolve(projectRoot);
+    await assertReadableRoot(root);
+    const files = [];
+    await walk(root, files);
+    // Sort the final result so the contract is explicitly deterministic regardless of filesystem
+    // enumeration order.
+    files.sort(comparePaths);
+    return files;
+}
+/**
+ * Validate that the resolved root exists and is a directory before walking it. A missing root is
+ * reported separately from a root that is a regular file, and any other I/O failure stays
+ * `unreadable`.
+ *
+ * `lstat` (not `stat`) is used on purpose: it does not follow a symlink supplied as the root, so a
+ * symlinked root is rejected instead of being traversed, keeping the "never follow symlinks"
+ * contract consistent from the entry point down.
+ */
+async function assertReadableRoot(root) {
+    try {
+        const info = await lstat(root);
+        if (info.isSymbolicLink()) {
+            throw new SourceFilesError(`Project root ${root} is a symlink and will not be followed`, 'not-a-directory');
+        }
+        if (!info.isDirectory()) {
+            throw new SourceFilesError(`Project root ${root} exists but is not a directory`, 'not-a-directory');
+        }
+    }
+    catch (error) {
+        if (error instanceof SourceFilesError) {
+            throw error;
+        }
+        throw toReadError(root, error);
+    }
+}
+/**
+ * Recursively collect supported files under `directory`, pruning ignored directories and skipping
+ * symlinks before descending.
+ */
+async function walk(directory, files) {
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        throw new SourceFilesError(`Could not read directory ${directory}: ${messageOf(error)}`, 'unreadable', error);
+    }
+    for (const entry of entries) {
+        // Never follow symlinks: this avoids cycles, duplicates and escaping the project tree.
+        if (entry.isSymbolicLink()) {
+            continue;
+        }
+        const fullPath = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (IGNORED_DIRECTORY_NAMES.has(entry.name)) {
+                // Prune before descending so trees like `node_modules` are never enumerated.
+                continue;
+            }
+            await walk(fullPath, files);
+            continue;
+        }
+        if (entry.isFile() && isSupportedFile(entry.name)) {
+            files.push(fullPath);
+        }
+    }
+}
+/**
+ * Whether a file name has a supported source extension.
+ */
+function isSupportedFile(fileName) {
+    return SUPPORTED_EXTENSIONS.has(extname(fileName));
+}
+/**
+ * Classify a filesystem failure while validating the root: a missing root is expected and reported
+ * separately from any other I/O problem.
+ */
+function toReadError(root, error) {
+    if (isNotFoundError(error)) {
+        return new SourceFilesError(`Project root ${root} does not exist`, 'missing', error);
+    }
+    return new SourceFilesError(`Could not read project root ${root}: ${messageOf(error)}`, 'unreadable', error);
+}
+/**
+ * A short, human-readable reason extracted from an unknown thrown value, for error messages only.
+ */
+function messageOf(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+/**
+ * Whether an unknown thrown value is the filesystem `ENOENT` error.
+ */
+function isNotFoundError(error) {
+    return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}
+/**
+ * Locale-independent lexicographic ordering, so the same tree always yields the same order.
+ */
+function comparePaths(a, b) {
+    if (a < b) {
+        return -1;
+    }
+    if (a > b) {
+        return 1;
+    }
+    return 0;
+}
+//# sourceMappingURL=sourceFiles.js.map

package/dist/scanner/sourceFiles.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "depvitals",
-  "version": "0.0.1",
+  "version": "0.1.1",
   "description": "A simple, lightweight dependency health checker for Node.js projects.",
   "keywords": [
     "nodejs",
@@ -9,6 +9,8 @@
     "dependency-analysis",
     "dependency-checker",
     "dependency-health",
+    "unused-dependencies",
+    "missing-dependencies",
     "depcheck",
     "cli"
   ],