depvitals 0.2.0 → 0.4.0

package/dist/detectors/jestManifestConfig.js

@@ -11,9 +11,9 @@
  * - execute Jest, `import()`/`require()` its configuration loader, or evaluate any target code;
  * - implement the Jest configuration schema. Only `preset`, `testEnvironment` and `transform` are
  *   read, and only through the fixed allowlists below;
- * - read the `transform` map *keys*. Every key of that map is a regular expression selecting the
- *   files a transformer applies to, so a key is a pattern and never a package name, even when it
- *   literally reads `"ts-jest"`; no regular expression is ever evaluated here;
+ * - use `transform` map keys as package evidence. Keys are retained only in JSON pointers; they
+ *   select the transformer field and never name a package, even when a key literally reads
+ *   `"ts-jest"`. No regular expression is evaluated here;
  * - expand Jest shorthands. In particular `testEnvironment: "jsdom"` is *not* credited to
  *   `jest-environment-jsdom`: whether that shorthand is a package reference at all depends on the
  *   Jest major version in use, which DepVitals does not read, so it stays outside the supported
@@ -36,9 +36,11 @@
  * use. Ignoring is deliberate — an unusable `jest` block is not an error, and diagnosing one here would
  * duplicate the manifest loader.
  */
-import { readFile, readdir } from 'node:fs/promises';
+import { readdir } from 'node:fs/promises';
 import { resolve } from 'node:path';
-import { loadProjectManifest, ProjectManifestError } from '../scanner/projectManifest.js';
+import { compareEvidence, compareStrings, jsonPointer, } from '../core/evidence.js';
+import { loadProjectManifest, ProjectManifestError, readManifestText, } from '../scanner/projectManifest.js';
+import { assertReadableRoot, SourceFilesError } from '../scanner/sourceFiles.js';
 import { classifyPackageSpecifier } from '../scanner/packageSpecifier.js';
 /**
  * The only `preset` packages recognized by this release.
@@ -108,22 +110,50 @@ const JEST_CONFIG_ENTRY_NAMES = new Set([
  * @param declaredPackageNames - Declared dependency names, the only names this may return.
  */
 export function findJestConfigUsage(jestConfig, declaredPackageNames) {
-    if (!isPlainRecord(jestConfig)) {
-        return new Set();
-    }
-    const candidates = [
-        ...matchAllowedPackage(jestConfig['preset'], PRESET_PACKAGE_NAMES),
-        ...matchAllowedPackage(jestConfig['testEnvironment'], TEST_ENVIRONMENT_PACKAGE_NAMES),
-        ...matchTransformValues(jestConfig['transform'], TRANSFORM_PACKAGE_NAMES),
-    ];
-    const used = new Set();
-    for (const candidate of candidates) {
-        if (declaredPackageNames.has(candidate)) {
-            used.add(candidate);
+    return new Set(collectJestConfigUsage(jestConfig, declaredPackageNames).map(({ packageName }) => packageName));
+}
+/** Pure collector for standalone readers and the later shared validated-context handoff. */
+export function collectJestConfigUsage(jestConfig, declaredPackageNames) {
+    if (!isPlainRecord(jestConfig))
+        return [];
+    const occurrences = [];
+    const add = (value, allowedPackages, pointerTokens) => {
+        if (typeof value !== 'string')
+            return;
+        for (const packageName of matchAllowedPackage(value, allowedPackages)) {
+            if (declaredPackageNames.has(packageName)) {
+                occurrences.push({
+                    packageName,
+                    evidence: {
+                        kind: 'config',
+                        file: 'package.json',
+                        pointer: jsonPointer('jest', ...pointerTokens),
+                        value,
+                        detector: 'jest',
+                    },
+                });
+            }
+        }
+    };
+    add(jestConfig['preset'], PRESET_PACKAGE_NAMES, ['preset']);
+    add(jestConfig['testEnvironment'], TEST_ENVIRONMENT_PACKAGE_NAMES, ['testEnvironment']);
+    const transform = jestConfig['transform'];
+    if (isPlainRecord(transform)) {
+        for (const [key, value] of Object.entries(transform)) {
+            // Keys identify fields only. A tuple must have exactly two items and object-shaped options;
+            // those options remain opaque, and only its first item can supply a recognized value.
+            if (Array.isArray(value)) {
+                if (value.length === 2 && isPlainRecord(value[1])) {
+                    add(value[0], TRANSFORM_PACKAGE_NAMES, ['transform', key, '0']);
+                }
+            }
+            else {
+                add(value, TRANSFORM_PACKAGE_NAMES, ['transform', key]);
+            }
         }
     }
-    // Rebuilt from sorted names so iteration is deterministic for every input.
-    return new Set([...used].sort(compareNames));
+    // Different fields and transform keys remain distinct, even when their package/value repeats.
+    return occurrences.sort((a, b) => compareStrings(a.packageName, b.packageName) || compareEvidence(a.evidence, b.evidence));
 }
 /**
  * Collect the `package.json#jest` hints for the project rooted at `projectRoot`.
@@ -140,9 +170,13 @@ export function findJestConfigUsage(jestConfig, declaredPackageNames) {
  * @param projectRoot - Project directory to inspect; resolved to an absolute path.
  */
 export async function findJestManifestUsage(projectRoot) {
+    return new Set((await collectJestManifestUsage(projectRoot)).map(({ packageName }) => packageName));
+}
+/** Retain manifest facts through the existing barrier, validation and text-read path. */
+export async function collectJestManifestUsage(projectRoot) {
     const root = resolve(projectRoot);
     if (await hasRootJestConfigEntry(root)) {
-        return new Set();
+        return [];
     }
     let packageJsonPath;
     let declaredPackageNames;
@@ -152,12 +186,12 @@ export async function findJestManifestUsage(projectRoot) {
         declaredPackageNames = manifest.declaredDependencyNames;
     }
     catch (error) {
-        if (error instanceof ProjectManifestError) {
-            return new Set();
+        if (error instanceof ProjectManifestError || error instanceof SourceFilesError) {
+            return [];
         }
         throw error;
     }
-    return findJestConfigUsage(await readJestConfigValue(packageJsonPath), declaredPackageNames);
+    return collectJestConfigUsage(await readJestConfigValue(packageJsonPath), declaredPackageNames);
 }
 /**
  * Whether a root Jest configuration file name exists in the project root.
@@ -170,11 +204,16 @@ export async function findJestManifestUsage(projectRoot) {
 export async function hasRootJestConfigEntry(root) {
     let entries;
     try {
+        await assertReadableRoot(root);
         entries = await readdir(root);
     }
     catch {
         return false;
     }
+    return hasRootJestConfigEntries(entries);
+}
+/** Pure barrier decision for a shared per-scan root listing. */
+export function hasRootJestConfigEntries(entries) {
     return entries.some((entry) => JEST_CONFIG_ENTRY_NAMES.has(entry.toLowerCase()));
 }
 /**
@@ -187,7 +226,7 @@ export async function hasRootJestConfigEntry(root) {
 async function readJestConfigValue(packageJsonPath) {
     let text;
     try {
-        text = await readFile(packageJsonPath, 'utf8');
+        text = await readManifestText(packageJsonPath);
     }
     catch {
         return undefined;
@@ -224,69 +263,10 @@ function matchAllowedPackage(value, allowedPackages) {
     }
     return allowedPackages.has(specifier.packageName) ? [specifier.packageName] : [];
 }
-/**
- * The allowlisted packages named by the *values* of one `jest.transform` map.
- *
- * Only values are read: `Object.values` is used precisely so that a key can never become evidence.
- * Every key of a Jest transform map is a regular expression such as `"^.+\\.tsx?$"`, and a key that
- * happens to read `"ts-jest"` is still only a pattern, so it credits nothing. A `transform` field
- * that is not a plain JSON object (an array, a string, a number, `null`, absent) contributes nothing.
- */
-function matchTransformValues(transform, allowedPackages) {
-    if (!isPlainRecord(transform)) {
-        return [];
-    }
-    const matches = [];
-    for (const value of Object.values(transform)) {
-        matches.push(...matchTransformValue(value, allowedPackages));
-    }
-    return matches;
-}
-/**
- * The allowlisted package named by one `jest.transform` value, if any.
- *
- * Exactly two shapes are supported, and no others:
- *
- * - the transformer string itself, `"ts-jest"`, matched by the same rules as the other supported
- *   Jest fields - the value is classified first and must then be an exact member of
- *   `allowedPackages`, so `"./local-transform.js"`, `"<rootDir>/transform.js"`, `"file:./t.js"`,
- *   `""`, `"ts jest"`, `"ts-jest-extras"` and every other module yield nothing. As in `preset`, a
- *   literal subpath of an allowlisted package collapses to its package root
- *   (`"ts-jest/preprocessor.js"`, the historical ts-jest transformer path), because the first path
- *   segment still names the package that provides the transformer;
- * - the `[transformer, options]` tuple: exactly two elements, the second a JSON options object, the
- *   first matched as above. The options object is only checked for being an object and is never
- *   inspected, so a supported package name that appears only inside it - as a label or an option
- *   value - is not evidence.
- *
- * A one- or three-element array, a non-object second tuple element, an object used in place of the
- * whole value or any other shape is outside the supported subset and yields nothing.
- */
-function matchTransformValue(value, allowedPackages) {
-    if (Array.isArray(value)) {
-        if (value.length !== 2 || !isPlainRecord(value[1])) {
-            return [];
-        }
-        return matchAllowedPackage(value[0], allowedPackages);
-    }
-    return matchAllowedPackage(value, allowedPackages);
-}
 /**
  * A JSON object (not an array, not `null`) whose keys are strings.
  */
 function isPlainRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-/**
- * Locale-independent lexicographic ordering, so the same configuration always yields the same order.
- */
-function compareNames(a, b) {
-    if (a < b) {
-        return -1;
-    }
-    if (a > b) {
-        return 1;
-    }
-    return 0;
-}
 //# sourceMappingURL=jestManifestConfig.js.map

package/dist/detectors/jestManifestConfig.js.map

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

package/dist/reporters/jsonReporter.d.ts

@@ -0,0 +1,39 @@
+/** Pure versioned JSON projection; internal scan objects never cross the document boundary. */
+import type { AnalysisFindings, DetailedAnalysisResult, PackageExplanation } from '../core/analyzeProject.js';
+import { type FindingCategory, type PackageFact } from '../core/evidence.js';
+export type JsonReportInput = {
+    readonly mode: 'scan';
+    readonly result: DetailedAnalysisResult;
+} | {
+    readonly mode: 'explain';
+    readonly result: PackageExplanation;
+};
+export type JsonReport = {
+    readonly schemaVersion: 1;
+    readonly tool: {
+        readonly name: 'depvitals';
+        readonly version: string;
+    };
+    readonly mode: 'scan' | 'explain';
+    readonly project: {
+        readonly root: string;
+    };
+    readonly scope: {
+        readonly sourceExtensions: readonly string[];
+        readonly excludedDirectories: readonly string[];
+        readonly ignorePaths: readonly string[];
+        readonly ignoreDependencies: readonly string[];
+    };
+    readonly findings: AnalysisFindings;
+    readonly counts: Readonly<Record<FindingCategory, number>>;
+    readonly packages: readonly PackageFact[];
+    readonly query: {
+        readonly packageName: string;
+        readonly known: boolean;
+    } | null;
+};
+/** The caller injects actual metadata version; only completed scan/query facts are accepted. */
+export declare function createJsonReport(input: JsonReportInput, version: string): JsonReport;
+/** Exactly one pretty-printed document and one LF; no process I/O, error envelope or banner. */
+export declare function formatJsonReport(input: JsonReportInput, version: string): string;
+//# sourceMappingURL=jsonReporter.d.ts.map

package/dist/reporters/jsonReporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonReporter.d.ts","sourceRoot":"","sources":["../../src/reporters/jsonReporter.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,OAAO,KAAK,EACV,gBAAgB,EAChB,sBAAsB,EACtB,kBAAkB,EACnB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAML,KAAK,eAAe,EACpB,KAAK,WAAW,EACjB,MAAM,qBAAqB,CAAC;AAG7B,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAA;CAAE,GAClE;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAEtE,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;QAC7C,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;QAChD,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;QACxC,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;KAChD,CAAC;IACF,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3D,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CAClF,CAAC;AAEF,gGAAgG;AAChG,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,CAiCpF;AAED,gGAAgG;AAChG,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhF"}

package/dist/reporters/jsonReporter.js

@@ -0,0 +1,91 @@
+import { compareStrings, DECLARATION_GROUPS, FINDING_CATEGORIES, sortedUniqueEvidence, } from '../core/evidence.js';
+import { sourceDiscoveryDefaults } from '../scanner/sourceFiles.js';
+/** The caller injects actual metadata version; only completed scan/query facts are accepted. */
+export function createJsonReport(input, version) {
+    const { result } = input;
+    const defaults = sourceDiscoveryDefaults();
+    const findings = {
+        unusedDependencies: names(result.findings.unusedDependencies),
+        unusedDevDependencies: names(result.findings.unusedDevDependencies),
+        missingDependencies: names(result.findings.missingDependencies),
+    };
+    return {
+        schemaVersion: 1,
+        tool: { name: 'depvitals', version },
+        mode: input.mode,
+        project: { root: result.projectRoot },
+        scope: {
+            sourceExtensions: defaults.sourceExtensions,
+            excludedDirectories: defaults.excludedDirectories,
+            ignorePaths: names(result.config.ignorePaths),
+            ignoreDependencies: names(result.config.ignoreDependencies),
+        },
+        findings,
+        counts: {
+            unusedDependencies: findings.unusedDependencies.length,
+            unusedDevDependencies: findings.unusedDevDependencies.length,
+            missingDependencies: findings.missingDependencies.length,
+        },
+        packages: [...result.packages]
+            .sort((a, b) => compareStrings(a.name, b.name))
+            .map(packageRecord),
+        query: input.mode === 'explain'
+            ? { packageName: input.result.query.packageName, known: input.result.query.known }
+            : null,
+    };
+}
+/** Exactly one pretty-printed document and one LF; no process I/O, error envelope or banner. */
+export function formatJsonReport(input, version) {
+    return JSON.stringify(createJsonReport(input, version), null, 2) + '\n';
+}
+function names(values) {
+    return [...new Set(values)].sort(compareStrings);
+}
+function ordered(values, order) {
+    return [...values].sort((a, b) => order.indexOf(a) - order.indexOf(b));
+}
+function packageRecord(pkg) {
+    return {
+        name: pkg.name,
+        status: pkg.status,
+        declaredIn: ordered(pkg.declaredIn, DECLARATION_GROUPS),
+        excluded: pkg.excluded,
+        underlyingFindings: ordered(pkg.underlyingFindings, FINDING_CATEGORIES),
+        findings: ordered(pkg.findings, FINDING_CATEGORIES),
+        evidence: sortedUniqueEvidence(pkg.evidence).map(evidenceRecord),
+    };
+}
+function evidenceRecord(fact) {
+    switch (fact.kind) {
+        case 'source':
+            return {
+                kind: 'source',
+                file: fact.file,
+                reference: fact.reference,
+                specifier: fact.specifier,
+                position: {
+                    offset: fact.position.offset,
+                    line: fact.position.line,
+                    column: fact.position.column,
+                },
+            };
+        case 'script':
+            return {
+                kind: 'script',
+                file: fact.file,
+                pointer: fact.pointer,
+                command: fact.command,
+                via: fact.via,
+                occurrence: fact.occurrence,
+            };
+        case 'config':
+            return {
+                kind: 'config',
+                file: fact.file,
+                pointer: fact.pointer,
+                value: fact.value,
+                detector: fact.detector,
+            };
+    }
+}
+//# sourceMappingURL=jsonReporter.js.map

package/dist/reporters/jsonReporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonReporter.js","sourceRoot":"","sources":["../../src/reporters/jsonReporter.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GAIrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAuBpE,gGAAgG;AAChG,MAAM,UAAU,gBAAgB,CAAC,KAAsB,EAAE,OAAe;IACtE,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IACzB,MAAM,QAAQ,GAAG,uBAAuB,EAAE,CAAC;IAC3C,MAAM,QAAQ,GAAG;QACf,kBAAkB,EAAE,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAC;QAC7D,qBAAqB,EAAE,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAC;QACnE,mBAAmB,EAAE,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAC;KAChE,CAAC;IACF,OAAO;QACL,aAAa,EAAE,CAAC;QAChB,IAAI,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE;QACpC,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,WAAW,EAAE;QACrC,KAAK,EAAE;YACL,gBAAgB,EAAE,QAAQ,CAAC,gBAAgB;YAC3C,mBAAmB,EAAE,QAAQ,CAAC,mBAAmB;YACjD,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC;YAC7C,kBAAkB,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC;SAC5D;QACD,QAAQ;QACR,MAAM,EAAE;YACN,kBAAkB,EAAE,QAAQ,CAAC,kBAAkB,CAAC,MAAM;YACtD,qBAAqB,EAAE,QAAQ,CAAC,qBAAqB,CAAC,MAAM;YAC5D,mBAAmB,EAAE,QAAQ,CAAC,mBAAmB,CAAC,MAAM;SACzD;QACD,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC;aAC3B,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;aAC9C,GAAG,CAAC,aAAa,CAAC;QACrB,KAAK,EACH,KAAK,CAAC,IAAI,KAAK,SAAS;YACtB,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE;YAClF,CAAC,CAAC,IAAI;KACX,CAAC;AACJ,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,gBAAgB,CAAC,KAAsB,EAAE,OAAe;IACtE,OAAO,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;AAC1E,CAAC;AAED,SAAS,KAAK,CAAC,MAAyB;IACtC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;AACnD,CAAC;AACD,SAAS,OAAO,CAAmB,MAAoB,EAAE,KAAmB;IAC1E,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AACzE,CAAC;AACD,SAAS,aAAa,CAAC,GAAgB;IACrC,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,kBAAkB,CAAC;QACvD,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,kBAAkB,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,kBAAkB,CAAC;QACvE,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,kBAAkB,CAAC;QACnD,QAAQ,EAAE,oBAAoB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC;KACjE,CAAC;AACJ,CAAC;AACD,SAAS,cAAc,CAAC,IAAc;IACpC,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,QAAQ;YACX,OAAO;gBACL,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,QAAQ,EAAE;oBACR,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM;oBAC5B,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI;oBACxB,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM;iBAC7B;aACF,CAAC;QACJ,KAAK,QAAQ;YACX,OAAO;gBACL,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,GAAG,EAAE,IAAI,CAAC,GAAG;gBACb,UAAU,EAAE,IAAI,CAAC,UAAU;aAC5B,CAAC;QACJ,KAAK,QAAQ;YACX,OAAO;gBACL,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;aACxB,CAAC;IACN,CAAC;AACH,CAAC"}

package/dist/reporters/terminalReporter.d.ts

@@ -1,9 +1,9 @@
 /**
  * Deterministic terminal reporter.
  *
- * Renders an {@link AnalysisResult} as plain terminal text and nothing else: the module performs no
+ * Renders legacy findings or a completed package explanation as plain terminal text. The module performs no
  * process I/O, never imports `node:process`, never writes to a stream, never assigns an exit code,
- * and never reads the filesystem. It is a pure `AnalysisResult -> string` transformation, so the
+ * and never reads the filesystem. Both formatters are pure transformations, so the
  * exact output is fully testable and can be reused by any future presentation layer.
  *
  * The `v0.1.0` output is intentionally plain. It contains exactly:
@@ -11,7 +11,7 @@
  * - one section per non-empty findings category, in a fixed order;
  * - the clean-project message when there are no findings at all.
  *
- * It deliberately does not contain colors, symbols, spinners, tables, terminal-width detection,
+ * The legacy scan deliberately does not contain colors, symbols, spinners, tables, terminal-width detection,
  * links, prompts, source locations, advice, remediation commands, dependency counts, project paths
  * or any summary footer. Those belong to later releases, if they are added at all.
  *
@@ -30,7 +30,7 @@
  * the received arrays, and never uses locale-sensitive comparison. Deduplication stays the analyzer's
  * responsibility, so a duplicated name inside a category would be rendered twice by design.
  */
-import type { AnalysisResult } from '../core/analyzeProject.js';
+import type { AnalysisResult, PackageExplanation } from '../core/analyzeProject.js';
 /**
  * Whether the analysis produced at least one unused or missing dependency finding.
  *
@@ -46,4 +46,15 @@ export declare function hasDependencyIssues(result: AnalysisResult): boolean;
  *   findings sections in deterministic order.
  */
 export declare function formatTerminalReport(result: AnalysisResult): string;
+/** Render one completed package projection without collection, classification or process I/O. */
+export declare function formatTerminalExplanation(result: PackageExplanation): string;
+/**
+ * Escape C0/C1 control characters and DEL as `\uXXXX` so a package name extracted from target
+ * source can never carry a terminal control sequence (such as an ESC from `"\x1b[2J"`) into the
+ * rendered report. Printable characters pass through unchanged.
+ *
+ * The scan is written as explicit code points instead of a control-character regex range so the
+ * ESLint `no-control-regex` rule stays meaningful.
+ */
+export declare function escapeControlCharacters(value: string): string;
 //# sourceMappingURL=terminalReporter.d.ts.map

package/dist/reporters/terminalReporter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"terminalReporter.d.ts","sourceRoot":"","sources":["../../src/reporters/terminalReporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAchE;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAMnE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAQnE"}
+{"version":3,"file":"terminalReporter.d.ts","sourceRoot":"","sources":["../../src/reporters/terminalReporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAsBpF;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAMnE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAQnE;AAgBD,iGAAiG;AACjG,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAuB5E;AAiED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAe7D"}

package/dist/reporters/terminalReporter.js

@@ -1,9 +1,9 @@
 /**
  * Deterministic terminal reporter.
  *
- * Renders an {@link AnalysisResult} as plain terminal text and nothing else: the module performs no
+ * Renders legacy findings or a completed package explanation as plain terminal text. The module performs no
  * process I/O, never imports `node:process`, never writes to a stream, never assigns an exit code,
- * and never reads the filesystem. It is a pure `AnalysisResult -> string` transformation, so the
+ * and never reads the filesystem. Both formatters are pure transformations, so the
  * exact output is fully testable and can be reused by any future presentation layer.
  *
  * The `v0.1.0` output is intentionally plain. It contains exactly:
@@ -11,7 +11,7 @@
  * - one section per non-empty findings category, in a fixed order;
  * - the clean-project message when there are no findings at all.
  *
- * It deliberately does not contain colors, symbols, spinners, tables, terminal-width detection,
+ * The legacy scan deliberately does not contain colors, symbols, spinners, tables, terminal-width detection,
  * links, prompts, source locations, advice, remediation commands, dependency counts, project paths
  * or any summary footer. Those belong to later releases, if they are added at all.
  *
@@ -30,6 +30,7 @@
  * the received arrays, and never uses locale-sensitive comparison. Deduplication stays the analyzer's
  * responsibility, so a duplicated name inside a category would be rendered twice by design.
  */
+import { compareEvidence, DECLARATION_GROUPS, FINDING_CATEGORIES, } from '../core/evidence.js';
 /** Heading printed as the first line of every report. */
 const HEADER = 'DepVitals';
 /** Exact report returned when the analysis contains no findings at all. */
@@ -59,6 +60,65 @@ export function formatTerminalReport(result) {
     const sections = findingsSections(result).filter((section) => section.names.length > 0);
     return `${HEADER}\n\n${sections.map(renderSection).join('\n\n')}\n`;
 }
+const EXPLANATION_REASONS = {
+    used: 'Supported usage evidence was found within the effective scope.',
+    unused: 'No supported usage evidence was found within the effective scope. Review before removing the package.',
+    missing: 'Supported source evidence references this package, but no dependency group declares it.',
+    excluded: 'An exact ignoreDependencies rule suppresses findings for this package. Exclusion is not usage evidence.',
+    declared: 'Declared only in peerDependencies and/or optionalDependencies without supported usage evidence. These groups are not checked for unused.',
+    unknown: 'No declaration, supported source reference or dependency exclusion was found for this package.',
+};
+/** Render one completed package projection without collection, classification or process I/O. */
+export function formatTerminalExplanation(result) {
+    const pkg = result.packages[0];
+    const evidence = [...pkg.evidence].sort(compareEvidence);
+    const summary = [
+        `Package: ${escapeControlCharacters(pkg.name)}`,
+        `Status: ${pkg.status}`,
+        `Declared in: ${orderedSummary(pkg.declaredIn, DECLARATION_GROUPS)}`,
+        `Excluded: ${pkg.excluded ? 'yes' : 'no'}`,
+        `Underlying findings: ${orderedSummary(pkg.underlyingFindings, FINDING_CATEGORIES)}`,
+        `Findings: ${orderedSummary(pkg.findings, FINDING_CATEGORIES)}`,
+    ].join('\n');
+    const evidenceSection = [
+        `Evidence (${String(evidence.length)})`,
+        ...(evidence.length === 0 ? ['  none'] : evidence.map(renderEvidence)),
+    ].join('\n');
+    const scope = [
+        'Scope',
+        `  Ignored source paths: ${quotedRules(result.config.ignorePaths)}`,
+        `  Ignored dependency names: ${quotedRules(result.config.ignoreDependencies)}`,
+    ].join('\n');
+    return ([HEADER, summary, EXPLANATION_REASONS[pkg.status], evidenceSection, scope].join('\n\n') + '\n');
+}
+function orderedSummary(values, order) {
+    return values.length === 0
+        ? 'none'
+        : [...values]
+            .sort((a, b) => order.indexOf(a) - order.indexOf(b))
+            .map(escapeControlCharacters)
+            .join(', ');
+}
+function quotedRules(values) {
+    return values.length === 0
+        ? 'none'
+        : [...values].sort(compareNames).map(quoteTerminalValue).join(', ');
+}
+function renderEvidence(evidence) {
+    const file = quoteTerminalValue(evidence.file);
+    switch (evidence.kind) {
+        case 'source':
+            return `  source ${file}:${String(evidence.position.line)}:${String(evidence.position.column)} ${evidence.reference} ${quoteTerminalValue(evidence.specifier)}`;
+        case 'script':
+            return `  script ${file}#${quoteTerminalValue(evidence.pointer)} ${evidence.via} ${quoteTerminalValue(evidence.command)} (occurrence ${String(evidence.occurrence)})`;
+        case 'config':
+            return `  config ${file}#${quoteTerminalValue(evidence.pointer)} ${evidence.detector} ${quoteTerminalValue(evidence.value)}`;
+    }
+}
+/** Quote printable text first, then reuse the legacy control escape without double-escaping it. */
+function quoteTerminalValue(value) {
+    return '"' + escapeControlCharacters(value.replaceAll('\\', '\\\\').replaceAll('"', '\\"')) + '"';
+}
 /**
  * The findings categories in their fixed rendering order. Keeping the order here means the section
  * sequence can never depend on the shape or key order of the incoming result.
@@ -95,7 +155,7 @@ function renderSection(section) {
  * The scan is written as explicit code points instead of a control-character regex range so the
  * ESLint `no-control-regex` rule stays meaningful.
  */
-function escapeControlCharacters(value) {
+export function escapeControlCharacters(value) {
     let out = '';
     for (let index = 0; index < value.length; index += 1) {
         const code = value.charCodeAt(index);

package/dist/reporters/terminalReporter.js.map

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

package/dist/scanner/moduleSpecifiers.d.ts

@@ -18,6 +18,7 @@
  * template literal text and regex literals so they never produce false findings. JavaScript inside
  * template interpolations (`${...}`) is still lexed, so specifiers there are found.
  */
+import type { SourceEvidence } from '../core/evidence.js';
 /**
  * The kind of module construct a specifier came from.
  */
@@ -29,6 +30,10 @@ export type ModuleSpecifierOccurrence = {
     readonly specifier: string;
     readonly kind: ModuleSpecifierKind;
 };
+/** A retained occurrence measured in the original, unnormalized UTF-16 source text. */
+export type PositionedModuleSpecifierOccurrence = ModuleSpecifierOccurrence & {
+    readonly position: Readonly<SourceEvidence['position']>;
+};
 /**
  * Error code for the module specifier scanner.
  *
@@ -53,8 +58,8 @@ export declare class ModuleSpecifierError extends Error {
  */
 export type ExtractModuleSpecifiersOptions = {
     jsx?: boolean;
-    /** Treat top-level `await` as a keyword. Omitted and false retain script/CommonJS behavior. */
-    module?: boolean;
+    /** Explicit module/script grammar, or bounded syntax detection for ambiguous `.js` input. */
+    module?: boolean | 'detect';
 };
 /**
  * Extract the statically knowable module specifiers from `source`.
@@ -65,4 +70,9 @@ export type ExtractModuleSpecifiersOptions = {
  *   from which the scanner cannot safely continue.
  */
 export declare function extractModuleSpecifiers(source: string, options?: ExtractModuleSpecifiersOptions): readonly ModuleSpecifierOccurrence[];
+/**
+ * Authoritative occurrence collector. The lexer must finish successfully before locations escape.
+ * Recognition is shared with the legacy projection above; no additional extraction is performed.
+ */
+export declare function collectModuleSpecifiers(source: string, options?: ExtractModuleSpecifiersOptions): readonly PositionedModuleSpecifierOccurrence[];
 //# sourceMappingURL=moduleSpecifiers.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"moduleSpecifiers.d.ts","sourceRoot":"","sources":["../../src/scanner/moduleSpecifiers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,aAAa,GAAG,gBAAgB,GAAG,SAAS,CAAC;AAE1F;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;CACpC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,wBAAwB,GAAG,gBAAgB,CAAC;AAExD;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,wBAAwB,EAAE,MAAM,EAAE,MAAM;CAM5E;AAED;;GAEG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAI3C,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,+FAA+F;IAC/F,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,8BAAmC,GAC3C,SAAS,yBAAyB,EAAE,CAEtC"}
+{"version":3,"file":"moduleSpecifiers.d.ts","sourceRoot":"","sources":["../../src/scanner/moduleSpecifiers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,aAAa,GAAG,gBAAgB,GAAG,SAAS,CAAC;AAE1F;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;CACpC,CAAC;AAEF,uFAAuF;AACvF,MAAM,MAAM,mCAAmC,GAAG,yBAAyB,GAAG;IAC5E,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC;CACzD,CAAC;AAIF;;;;;;GAMG;AACH,MAAM,MAAM,wBAAwB,GAAG,gBAAgB,CAAC;AAExD;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,wBAAwB,EAAE,MAAM,EAAE,MAAM;CAM5E;AAED;;GAEG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAI3C,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,6FAA6F;IAC7F,MAAM,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC7B,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,8BAAmC,GAC3C,SAAS,yBAAyB,EAAE,CAKtC;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,8BAAmC,GAC3C,SAAS,mCAAmC,EAAE,CA8BhD"}