depvitals 0.0.1 → 0.1.1

package/dist/scanner/scriptUsage.js

@@ -0,0 +1,490 @@
+/**
+ * Basic package.json script usage detection.
+ *
+ * This module answers exactly one narrow question: which declared dependencies are referenced by
+ * the static strings found in a project's `package.json` `scripts`? It turns those strings into a
+ * conservative set of package names that have clear static usage evidence, so later steps can avoid
+ * reporting them as unused.
+ *
+ * It deliberately does not:
+ * - execute, expand, substitute, resolve, spawn, source or evaluate anything;
+ * - shell-out, read the filesystem or consult `node_modules`;
+ * - map arbitrary shell binaries to packages; only the small, explicit `BINARY_TO_PACKAGE` list
+ *   (currently `tsc` -> `typescript`) is ever translated, and only against declared packages;
+ * - report missing dependencies (undeclared command tokens are ignored);
+ * - inspect installed `bin` metadata, config, workspaces or framework detectors.
+ *
+ * The strings are treated as inert text. This module performs no I/O and has no side effects.
+ *
+ * Recognition is intentionally conservative:
+ * - a shell segment's first effective command token counts only when that token is exactly a package
+ *   name, so paths and package subpaths (`scripts/build.js`, `eslint/bin/cli`) are never usage
+ *   evidence for the package they point into;
+ * - the small explicit `BINARY_TO_PACKAGE` list translates a recognized direct executable (currently
+ *   `tsc` -> `typescript`) to its declared package; every other command keeps exact-name matching.
+ * - the five documented package-runner forms count (`npx`, `npm exec`, `pnpm exec`, `pnpm dlx`,
+ *   `yarn dlx`) with the package in its immediate position;
+ * - leading POSIX environment assignments (`NODE_ENV=test`, `FOO=1 BAR=2`) are skipped;
+ * - quoted tokens keep their content, so separators and text inside quotes are not misread.
+ *
+ * Shell syntax this scanner does not understand invalidates the segment that contains it: single `&`
+ * (background execution), redirection (`<`, `>`), command and parameter expansion (`$(...)`,
+ * `${...}`), legacy backtick substitution and backslash escapes outside single quotes, plus a quote
+ * that is still open at the end of the script. Each such region is consumed as an opaque block, so a
+ * separator inside it never delimits the surrounding script. An invalidated segment yields no
+ * evidence at all, while the neighbouring segments delimited by real supported separators are still
+ * analyzed normally.
+ */
+import { classifyPackageSpecifier } from './packageSpecifier.js';
+/**
+ * Package-manager command words that are never evidence that the manager itself is a used dependency.
+ *
+ * Invoked without a supported runner form (for example `npm run build`, `pnpm test`, `yarn lint`),
+ * they do not prove usage of a declared dependency. The package they actually run (if any) is what
+ * may count, and only through the supported runner forms above.
+ */
+const PACKAGE_MANAGER_COMMANDS = new Set(['npm', 'pnpm', 'yarn', 'npx']);
+/**
+ * Leading POSIX-style environment assignment prefix, e.g. `NODE_ENV=`, `FOO=`.
+ *
+ * Only the name part is matched; the value (quoted or not) is consumed by the tokenizer.
+ */
+const ASSIGNMENT_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*=/;
+/**
+ * Explicit static executable -> declared-package mappings for supported direct command positions.
+ *
+ * A shell command position carries binaries and file paths, not package names, so this list is
+ * strictly opt-in: each executable here is known to provide exactly the mapped package.
+ * - `tsc` is the compiler front-end of the `typescript` package; the deprecated standalone `tsc`
+ *   npm package is intentionally NOT treated as providing the TypeScript compiler.
+ * - `docsify` is the executable provided by the `docsify-cli` package.
+ * Only lowercase `tsc` and `docsify` map; runner forms such as `npx tsc` or `npx docsify` keep their
+ * own (unmapped) semantics for now.
+ *
+ * The mapping is applied after safe command extraction and can only match a package that is actually
+ * declared, so it can never create a missing-dependency finding. When both a bare package name and
+ * its mapped package are declared (for example `docsify` and `docsify-cli`), only the declared
+ * mapped package (`docsify-cli`) receives this evidence; the bare `docsify` package is unaffected
+ * unless independent source or script evidence supports it.
+ */
+const BINARY_TO_PACKAGE = new Map([
+    ['tsc', 'typescript'],
+    ['docsify', 'docsify-cli'],
+]);
+/**
+ * Recognize the declared dependencies that `package.json` scripts clearly reference.
+ *
+ * For every script command the module collects the package names that have clear static usage
+ * evidence (a command token, a recognized executable mapped through `BINARY_TO_PACKAGE`, or a
+ * supported runner package position) and keeps only those that are present in
+ * {@link declaredPackageNames}. Undeclared command tokens and undeclared mapped packages are ignored:
+ * this module never creates missing-dependency findings.
+ *
+ * The result is built in alphabetical package-name order so iteration is deterministic. Neither
+ * {@link scripts} nor {@link declaredPackageNames} is mutated.
+ *
+ * @param scripts - `package.json` `scripts` entries as static strings (never executed).
+ * @param declaredPackageNames - the declared dependency names that may be suppressed as used.
+ */
+export function findPackageScriptUsage(scripts, declaredPackageNames) {
+    const used = new Set();
+    for (const command of Object.values(scripts)) {
+        for (const candidate of collectScriptCandidates(command)) {
+            if (declaredPackageNames.has(candidate)) {
+                used.add(candidate);
+            }
+        }
+    }
+    return new Set([...used].sort(compareNames));
+}
+/**
+ * Collect the package-name candidates referenced by a single script command.
+ *
+ * Each shell segment contributes at most one candidate: the package supplied to a supported runner
+ * form, or the segment's first effective command token when that token is exactly a package name.
+ * Segments containing unsupported shell syntax contribute nothing.
+ */
+function collectScriptCandidates(command) {
+    const candidates = [];
+    for (const segment of splitSegments(command)) {
+        // An unsupported segment is never partially trusted, not even its leading command.
+        if (segment.unsupported) {
+            continue;
+        }
+        const significant = skipLeadingAssignments(segment.tokens);
+        if (significant.length === 0) {
+            continue;
+        }
+        const runnerPackage = matchRunnerPackage(significant);
+        if (runnerPackage !== undefined) {
+            candidates.push(runnerPackage);
+            continue;
+        }
+        // A package manager invoked without a supported runner form is never evidence that the manager
+        // itself is a used dependency.
+        const commandName = significant[0]?.value;
+        if (commandName === undefined) {
+            continue;
+        }
+        if (PACKAGE_MANAGER_COMMANDS.has(commandName)) {
+            continue;
+        }
+        // Only the first effective command token is inspected, and it must be exactly the package root.
+        // Shell command position carries binaries and file paths, so a package subpath such as
+        // `eslint/bin/cli` or a script path such as `scripts/build.js` is never usage evidence.
+        const classification = classifyPackageSpecifier(commandName);
+        if (classification.kind === 'external' && commandName === classification.packageName) {
+            // An explicit executable mapping takes precedence over same-name matching: `tsc` resolves to
+            // the declared `typescript` package only, never to a hypothetical `tsc` package, so a single
+            // executable yields at most one piece of usage evidence.
+            const mapped = BINARY_TO_PACKAGE.get(commandName);
+            candidates.push(mapped ?? commandName);
+        }
+    }
+    return candidates;
+}
+/**
+ * Drop leading `VAR=value` assignments so the first real command token can be inspected.
+ */
+function skipLeadingAssignments(segment) {
+    let index = 0;
+    while (index < segment.length) {
+        const token = segment[index];
+        if (token === undefined || !ASSIGNMENT_PATTERN.test(token.value)) {
+            break;
+        }
+        index += 1;
+    }
+    return segment.slice(index);
+}
+/**
+ * Recognize the package position of the five supported runner forms.
+ *
+ * Returns the package token only when it appears in the expected immediate position. Forms that add
+ * flags, `--package` options or version/tags (for example `npx --no-install eslint`) return
+ * `undefined` and fall back to command-token handling.
+ */
+function matchRunnerPackage(significant) {
+    const command = significant[0]?.value;
+    if (command === 'npx') {
+        return significant[1]?.value;
+    }
+    if (command === 'npm') {
+        return significant[1]?.value === 'exec' ? significant[2]?.value : undefined;
+    }
+    if (command === 'pnpm') {
+        const subcommand = significant[1]?.value;
+        return subcommand === 'exec' || subcommand === 'dlx' ? significant[2]?.value : undefined;
+    }
+    if (command === 'yarn') {
+        return significant[1]?.value === 'dlx' ? significant[2]?.value : undefined;
+    }
+    return undefined;
+}
+/**
+ * Split a script string into segments on the supported separators (`&&`, `||`, `;`, `|`, newline
+ * outside quotes).
+ *
+ * The scanner only needs enough shell awareness to preserve quoted tokens, to keep separators and
+ * text inside quotes from being misread, and to detect the syntax it refuses to interpret. It never
+ * executes, expands or substitutes anything.
+ *
+ * Unsupported constructs (single `&`, redirection, `$(...)`, `${...}`, quotes left open at the end of
+ * the script) mark the current segment as unsupported instead of guessing tokens from inside it. The
+ * marker is reset by the next real separator, so invalidation stays local to the affected segment.
+ */
+function splitSegments(script) {
+    const segments = [];
+    let tokens = [];
+    let unsupported = false;
+    let i = 0;
+    const length = script.length;
+    // A real separator ends the current segment and clears its unsupported marker.
+    const flush = () => {
+        segments.push({ tokens, unsupported });
+        tokens = [];
+        unsupported = false;
+    };
+    while (i < length) {
+        const ch = script[i];
+        if (ch === undefined) {
+            break;
+        }
+        // Whitespace separates tokens within a segment.
+        if (isWhitespace(ch)) {
+            i += 1;
+            continue;
+        }
+        // Supported separators. `&&`/`||` are two-character; `;`, `|` and newline are single-character.
+        if (ch === ';' || ch === '\n') {
+            i += 1;
+            flush();
+            continue;
+        }
+        if (ch === '|') {
+            i += script[i + 1] === '|' ? 2 : 1;
+            flush();
+            continue;
+        }
+        // A single `&` is background execution, which is unsupported in v0.1.0. It deliberately does not
+        // behave like `&&`: it never splits the segment, it only invalidates it, so `eslint & prettier`
+        // yields no evidence instead of two independently trusted commands.
+        if (ch === '&') {
+            if (script[i + 1] === '&') {
+                i += 2;
+                flush();
+            }
+            else {
+                i += 1;
+                unsupported = true;
+            }
+            continue;
+        }
+        // Every other character starts an unquoted token. The token scan consumes exactly the characters
+        // of one token, so it always advances at least one position here.
+        const scanned = scanToken(script, i);
+        if (scanned.unsupported) {
+            unsupported = true;
+        }
+        if (scanned.text.length > 0) {
+            tokens = [...tokens, { value: scanned.text }];
+        }
+        i = scanned.next;
+    }
+    segments.push({ tokens, unsupported });
+    return segments;
+}
+/**
+ * Scan a single unquoted token starting at `start`.
+ *
+ * Quoted runs inside the token are consumed with their content kept verbatim, so `"eslint"`,
+ * `FOO="a;b"` and `echo "a && b"` tokenize safely. Redirection and shell expansion are reported as
+ * unsupported rather than interpreted, and a quote left open at the end of the script drops the
+ * partially accumulated token entirely.
+ */
+function scanToken(script, start) {
+    let value = '';
+    let unsupported = false;
+    let i = start;
+    while (i < script.length) {
+        const ch = script[i];
+        if (ch === undefined) {
+            break;
+        }
+        if (isWhitespace(ch) || ch === ';' || ch === '\n' || ch === '|' || ch === '&') {
+            break;
+        }
+        // Redirection is not parsed in v0.1.0; its presence alone invalidates the segment.
+        if (ch === '<' || ch === '>') {
+            unsupported = true;
+            i += 1;
+            continue;
+        }
+        // `$(...)`, `${...}` and backticks are never parsed or expanded here. The whole region is
+        // consumed as an opaque block so that separators (`;`, `|`, `&&`, newline) found inside it can
+        // never reach the outer segment logic and flush the current segment.
+        if (isUnsupportedRegionStart(script, i)) {
+            unsupported = true;
+            i = skipUnsupportedRegion(script, i);
+            continue;
+        }
+        // Outside single quotes a backslash escapes the following character, so that character can never
+        // act as a separator. The pair is consumed together; its exact meaning is irrelevant here.
+        if (ch === '\\') {
+            unsupported = true;
+            value += ch + (script[i + 1] ?? '');
+            i += 2;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            const run = scanQuoted(script, i + 1, ch);
+            if (run.open) {
+                // EOF before the quote closes: the segment is invalid and the partial token is dropped.
+                return { text: '', next: run.next, unsupported: true };
+            }
+            if (run.expands) {
+                unsupported = true;
+            }
+            value += run.text;
+            i = run.next;
+            continue;
+        }
+        value += ch;
+        i += 1;
+    }
+    return { text: value, next: i, unsupported };
+}
+/**
+ * Consume a quoted run, keeping its content verbatim.
+ *
+ * Separators and redirection characters inside quotes stay literal text. Single quotes are fully
+ * literal. Inside double quotes `$(...)`, `${...}`, backticks and a backslash count as expansion or
+ * escape and invalidate the segment; each such region is still consumed as an opaque block. Newlines
+ * are literal in both quote forms, so a quoted string may span several lines; only an unclosed quote
+ * at the end of the script is malformed.
+ */
+function scanQuoted(script, start, quote) {
+    const doubleQuoted = quote === '"';
+    let text = '';
+    let expands = false;
+    let i = start;
+    while (i < script.length) {
+        const ch = script[i];
+        if (ch === undefined) {
+            break;
+        }
+        if (ch === quote) {
+            return { text, next: i + 1, open: false, expands };
+        }
+        if (doubleQuoted && isUnsupportedRegionStart(script, i)) {
+            // Inside double quotes, `$(...)`, `${...}` and backticks are real expansion. The region is
+            // consumed as an opaque block so its inner separators never reach the outer segment, while the
+            // expansion itself still invalidates the segment.
+            expands = true;
+            i = skipUnsupportedRegion(script, i);
+            continue;
+        }
+        // Inside double quotes a backslash escapes the following character, so that character can never
+        // close the quoted run. The pair is consumed together and invalidates the segment.
+        if (doubleQuoted && ch === '\\') {
+            expands = true;
+            text += ch + (script[i + 1] ?? '');
+            i += 2;
+            continue;
+        }
+        text += ch;
+        i += 1;
+    }
+    return { text, next: i, open: true, expands };
+}
+/**
+ * Whether the character right after `$` opens a shell expansion (`$(` or `${`).
+ */
+function opensExpansion(next) {
+    return next === '(' || next === '{';
+}
+/**
+ * Whether an unsupported opaque region starts at `index`: `$(`, `${` or a legacy backtick.
+ */
+function isUnsupportedRegionStart(script, index) {
+    const ch = script[index];
+    if (ch === '`') {
+        return true;
+    }
+    return ch === '$' && opensExpansion(script[index + 1]);
+}
+/**
+ * Skip one unsupported shell region starting at `start`, which must point at `$(`, `${` or a
+ * backtick, and return the index just past its matching closing delimiter.
+ *
+ * The region is consumed opaquely: its contents are never interpreted, so separators found inside it
+ * can never flush the outer segment. Every open region is pushed onto a stack, which keeps mixed
+ * nesting balanced (`${A:-$(...)}`, `$(echo ${X})`, ``${X:-`cmd`}``) no matter which delimiter type
+ * opened it. Quoted runs are stack entries too, so a closing delimiter inside a quote never ends a
+ * region early, and a backslash consumes the character after it so an escaped `\)`, `\}` or backtick
+ * cannot close a region either. A single quote is literal text inside a double-quoted run, which is
+ * the one quote form that does not nest.
+ *
+ * If EOF is reached first the region is unterminated and `script.length` is returned, leaving the
+ * current outer segment unsupported. This never interprets shell semantics; it only locates opaque
+ * region boundaries safely.
+ */
+function skipUnsupportedRegion(script, start) {
+    const length = script.length;
+    const stack = [];
+    const first = script[start];
+    const second = script[start + 1];
+    let i;
+    if (first === '`') {
+        stack.push('`');
+        i = start + 1;
+    }
+    else if (first === '$' && (second === '(' || second === '{')) {
+        stack.push(second === '(' ? ')' : '}');
+        i = start + 2;
+    }
+    else {
+        // Not a region opener; advance by one so a caller can never loop forever.
+        return start + 1;
+    }
+    while (i < length && stack.length > 0) {
+        const ch = script[i];
+        if (ch === undefined) {
+            break;
+        }
+        const top = stack.at(-1);
+        // Inside single quotes everything is literal, so only the closing single quote is special.
+        if (top === "'") {
+            if (ch === "'") {
+                stack.pop();
+            }
+            i += 1;
+            continue;
+        }
+        // A backslash consumes the next character in `$()`, `${}`, backticks and double quotes.
+        if (ch === '\\') {
+            i += 2;
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            // A single quote is literal text inside a double-quoted run, so it must never open a region of
+            // its own. Doing so would keep the outer double quote open until EOF and hide the separators
+            // that follow it.
+            if (ch === "'" && top === '"') {
+                i += 1;
+                continue;
+            }
+            // A double quote closes only the quoted run it opened; any other quote opens a literal run.
+            if (ch === '"' && top === '"') {
+                stack.pop();
+            }
+            else {
+                stack.push(ch);
+            }
+            i += 1;
+            continue;
+        }
+        const next = script[i + 1];
+        if (ch === '$' && opensExpansion(next)) {
+            stack.push(next === '(' ? ')' : '}');
+            i += 2;
+            continue;
+        }
+        if (ch === '`') {
+            if (top === '`') {
+                stack.pop();
+            }
+            else {
+                stack.push('`');
+            }
+            i += 1;
+            continue;
+        }
+        // `)` and `}` close only a matching region; otherwise they are inert region content.
+        if ((ch === ')' || ch === '}') && ch === top) {
+            stack.pop();
+        }
+        i += 1;
+    }
+    // An empty stack means the outermost region closed just before `i`; otherwise EOF arrived first.
+    return stack.length === 0 ? i : length;
+}
+/**
+ * Whether a character is whitespace (spaces, tabs, CR, FF, VT).
+ */
+function isWhitespace(ch) {
+    return ch === ' ' || ch === '\t' || ch === '\r' || ch === '\f' || ch === '\v';
+}
+/**
+ * Locale-independent lexicographic ordering, so the same scripts always yield the same order.
+ */
+function compareNames(a, b) {
+    if (a < b) {
+        return -1;
+    }
+    if (a > b) {
+        return 1;
+    }
+    return 0;
+}
+//# sourceMappingURL=scriptUsage.js.map

package/dist/scanner/scriptUsage.js.map

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

package/dist/scanner/sourceFiles.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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.
+ */
+/**
+ * A discovered source file as an absolute, platform-separated path, sorted lexicographically.
+ */
+export type DiscoveredSourceFile = string;
+/**
+ * Why source discovery could not run.
+ *
+ * - `missing`: the project root does not exist.
+ * - `not-a-directory`: the project root exists but is a regular file.
+ * - `unreadable`: the root exists, or a nested directory, could not be read (permissions, I/O
+ *   error, ...).
+ */
+export type SourceFilesErrorCode = 'missing' | 'not-a-directory' | 'unreadable';
+/**
+ * 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 declare class SourceFilesError extends Error {
+    readonly code: SourceFilesErrorCode;
+    constructor(message: string, code: SourceFilesErrorCode, cause?: unknown);
+}
+/**
+ * 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 declare function discoverSourceFiles(projectRoot: string): Promise<readonly DiscoveredSourceFile[]>;
+//# sourceMappingURL=sourceFiles.d.ts.map

package/dist/scanner/sourceFiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sourceFiles.d.ts","sourceRoot":"","sources":["../../src/scanner/sourceFiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA2CH;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAE1C;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,iBAAiB,GAAG,YAAY,CAAC;AAEhF;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;gBAExB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,EAAE,KAAK,CAAC,EAAE,OAAO;CAKzE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,SAAS,oBAAoB,EAAE,CAAC,CAY1C"}