depvitals 0.1.2 → 0.3.0

package/dist/cli/notifier/versionCompare.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Pure version comparison for the optional CLI update notifier.
+ *
+ * The notifier may only point an interactive user at a strictly newer *stable* DepVitals release,
+ * so the ordering rule here is intentionally bounded to `major.minor.patch` with decimal digits.
+ * Full semver ordering (prerelease precedence such as `-rc.1` < `-rc.2`, numeric-vs-alphanumeric
+ * identifiers, build metadata significance) is deliberately **not** implemented: the update-notifier
+ * contract requires skipping the notification for such versions instead of inventing an unreliable
+ * comparison, so every prerelease or build-tagged version is rejected conservatively.
+ *
+ * The module is pure by design: no filesystem, no network, no environment, no cache, no output and
+ * no `semver` dependency. Untrusted strings are validated by strict pattern matching, never parsed
+ * leniently, and no input can make these functions throw.
+ *
+ * This helper performs no eligibility decision and activates nothing; callers (later notifier code)
+ * decide whether a lookup happened and whether the notice may be printed.
+ */
+/** A parsed stable version; tuple order is `major`, `minor`, `patch`. */
+type ParsedVersion = readonly [major: number, minor: number, patch: number];
+/**
+ * Parses an exact `major.minor.patch` string.
+ *
+ * Returns `undefined` for a `v` prefix, empty input, whitespace, missing or extra components
+ * (`0.2`, `1.2.3.4`), prerelease tags (`0.2.0-rc.1`), build metadata (`1.2.3+build.5`), partial
+ * tokens (`1.x.3`), leading zeros (`01.2.3`) and any other malformed metadata.
+ *
+ * Exported for the notifier's own consumers (Step 66 validates untrusted registry text with this
+ * single grammar) so exactly one place defines what "an exact stable DepVitals version" means.
+ */
+export declare function parseStableVersion(value: string): ParsedVersion | undefined;
+/**
+ * Reports whether a registry `latest` version is strictly newer than the installed DepVitals
+ * version, using numeric comparison in `major`, `minor`, `patch` order (never string ordering, so
+ * `0.2.10` is newer than `0.2.9`).
+ *
+ * Returns `false` — never a notification — when the versions are equal, when `latest` is older, or
+ * when either input is not an exact stable version. That includes a prerelease installed build
+ * (e.g. a local `0.2.0-rc.1`), which silently skips notification rather than relying on ordering
+ * this helper does not implement.
+ *
+ * @param current - The installed DepVitals CLI version; callers must validate untrusted strings
+ *   (for example registry JSON) before passing them here.
+ * @param latest - The `latest` dist-tag reported for the package.
+ * @returns `true` only for a strictly newer stable `latest`; `false` for everything else.
+ */
+export declare function isNewerStableVersion(current: string, latest: string): boolean;
+export {};
+//# sourceMappingURL=versionCompare.d.ts.map

package/dist/cli/notifier/versionCompare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versionCompare.d.ts","sourceRoot":"","sources":["../../../src/cli/notifier/versionCompare.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAQH,yEAAyE;AACzE,KAAK,aAAa,GAAG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAiB5E;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAgB3E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAoB7E"}

package/dist/cli/notifier/versionCompare.js

@@ -0,0 +1,89 @@
+/**
+ * Pure version comparison for the optional CLI update notifier.
+ *
+ * The notifier may only point an interactive user at a strictly newer *stable* DepVitals release,
+ * so the ordering rule here is intentionally bounded to `major.minor.patch` with decimal digits.
+ * Full semver ordering (prerelease precedence such as `-rc.1` < `-rc.2`, numeric-vs-alphanumeric
+ * identifiers, build metadata significance) is deliberately **not** implemented: the update-notifier
+ * contract requires skipping the notification for such versions instead of inventing an unreliable
+ * comparison, so every prerelease or build-tagged version is rejected conservatively.
+ *
+ * The module is pure by design: no filesystem, no network, no environment, no cache, no output and
+ * no `semver` dependency. Untrusted strings are validated by strict pattern matching, never parsed
+ * leniently, and no input can make these functions throw.
+ *
+ * This helper performs no eligibility decision and activates nothing; callers (later notifier code)
+ * decide whether a lookup happened and whether the notice may be printed.
+ */
+/**
+ * One strictly numeric version component: no sign, no whitespace, no exponent, no leading zeros
+ * (padding is ambiguous and is not part of how npm publishes stable versions).
+ */
+const COMPONENT = /^(?:0|[1-9][0-9]*)$/;
+/**
+ * Parses one numeric component, returning `undefined` when it is not strictly numeric or when its
+ * value is not a safe integer (absurdly large digit strings must never be compared by floating-point
+ * rounding).
+ */
+function parseComponent(value) {
+    if (value === undefined || !COMPONENT.test(value)) {
+        return undefined;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+/**
+ * Parses an exact `major.minor.patch` string.
+ *
+ * Returns `undefined` for a `v` prefix, empty input, whitespace, missing or extra components
+ * (`0.2`, `1.2.3.4`), prerelease tags (`0.2.0-rc.1`), build metadata (`1.2.3+build.5`), partial
+ * tokens (`1.x.3`), leading zeros (`01.2.3`) and any other malformed metadata.
+ *
+ * Exported for the notifier's own consumers (Step 66 validates untrusted registry text with this
+ * single grammar) so exactly one place defines what "an exact stable DepVitals version" means.
+ */
+export function parseStableVersion(value) {
+    const parts = value.split('.');
+    if (parts.length !== 3) {
+        return undefined;
+    }
+    const major = parseComponent(parts[0]);
+    const minor = parseComponent(parts[1]);
+    const patch = parseComponent(parts[2]);
+    if (major === undefined || minor === undefined || patch === undefined) {
+        return undefined;
+    }
+    return [major, minor, patch];
+}
+/**
+ * Reports whether a registry `latest` version is strictly newer than the installed DepVitals
+ * version, using numeric comparison in `major`, `minor`, `patch` order (never string ordering, so
+ * `0.2.10` is newer than `0.2.9`).
+ *
+ * Returns `false` — never a notification — when the versions are equal, when `latest` is older, or
+ * when either input is not an exact stable version. That includes a prerelease installed build
+ * (e.g. a local `0.2.0-rc.1`), which silently skips notification rather than relying on ordering
+ * this helper does not implement.
+ *
+ * @param current - The installed DepVitals CLI version; callers must validate untrusted strings
+ *   (for example registry JSON) before passing them here.
+ * @param latest - The `latest` dist-tag reported for the package.
+ * @returns `true` only for a strictly newer stable `latest`; `false` for everything else.
+ */
+export function isNewerStableVersion(current, latest) {
+    const installed = parseStableVersion(current);
+    const published = parseStableVersion(latest);
+    if (installed === undefined || published === undefined) {
+        return false;
+    }
+    const [installedMajor, installedMinor, installedPatch] = installed;
+    const [publishedMajor, publishedMinor, publishedPatch] = published;
+    if (publishedMajor !== installedMajor) {
+        return publishedMajor > installedMajor;
+    }
+    if (publishedMinor !== installedMinor) {
+        return publishedMinor > installedMinor;
+    }
+    return publishedPatch > installedPatch;
+}
+//# sourceMappingURL=versionCompare.js.map

package/dist/cli/notifier/versionCompare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versionCompare.js","sourceRoot":"","sources":["../../../src/cli/notifier/versionCompare.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;GAGG;AACH,MAAM,SAAS,GAAG,qBAAqB,CAAC;AAKxC;;;;GAIG;AACH,SAAS,cAAc,CAAC,KAAyB;IAC/C,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAClD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAE1C,OAAO,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAE/B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAEvC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACtE,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe,EAAE,MAAc;IAClE,MAAM,SAAS,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,SAAS,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAE7C,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QACvD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,CAAC,cAAc,EAAE,cAAc,EAAE,cAAc,CAAC,GAAG,SAAS,CAAC;IACnE,MAAM,CAAC,cAAc,EAAE,cAAc,EAAE,cAAc,CAAC,GAAG,SAAS,CAAC;IAEnE,IAAI,cAAc,KAAK,cAAc,EAAE,CAAC;QACtC,OAAO,cAAc,GAAG,cAAc,CAAC;IACzC,CAAC;IAED,IAAI,cAAc,KAAK,cAAc,EAAE,CAAC;QACtC,OAAO,cAAc,GAAG,cAAc,CAAC;IACzC,CAAC;IAED,OAAO,cAAc,GAAG,cAAc,CAAC;AACzC,CAAC"}

package/dist/cli/runCli.d.ts

@@ -7,6 +7,8 @@
  *
  * The responsibilities here are:
  * - delegate argument validation to the pure {@link parseCliArgs};
+ * - hand the configuration-only package names recognized in the project to the analyzer, which is
+ *   the only component allowed to turn evidence into an unused/missing category;
  * - run the static dependency scan with `analyzeProject`;
  * - render the report with the pure terminal reporter;
  * - decide the scan exit code from `hasDependencyIssues`, not from the report string;

package/dist/cli/runCli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runCli.d.ts","sourceRoot":"","sources":["../../src/cli/runCli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AASH;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAkBF;;;;;;GAMG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAa7F"}
+{"version":3,"file":"runCli.d.ts","sourceRoot":"","sources":["../../src/cli/runCli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAaH;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAkBF;;;;;;GAMG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAa7F"}

package/dist/cli/runCli.js

@@ -7,6 +7,8 @@
  *
  * The responsibilities here are:
  * - delegate argument validation to the pure {@link parseCliArgs};
+ * - hand the configuration-only package names recognized in the project to the analyzer, which is
+ *   the only component allowed to turn evidence into an unused/missing category;
  * - run the static dependency scan with `analyzeProject`;
  * - render the report with the pure terminal reporter;
  * - decide the scan exit code from `hasDependencyIssues`, not from the report string;
@@ -15,9 +17,13 @@
  * It deliberately does not implement any scanning or dependency-analysis logic: that stays in
  * `src/core`, and the reporter stays in `src/reporters`.
  */
+import { readProjectConfig, ProjectConfigError } from '../config/readProjectConfig.js';
 import { AnalysisError, analyzeProject } from '../core/analyzeProject.js';
+import { findEslintManifestUsage } from '../detectors/eslintManifestConfig.js';
+import { EslintRcJsonError, findEslintRcJsonUsage } from '../detectors/eslintRcJsonConfig.js';
+import { findJestManifestUsage } from '../detectors/jestManifestConfig.js';
 import { formatTerminalReport, hasDependencyIssues } from '../reporters/terminalReporter.js';
-import { ProjectManifestError } from '../scanner/projectManifest.js';
+import { loadProjectManifest, ProjectManifestError } from '../scanner/projectManifest.js';
 import { SourceFilesError } from '../scanner/sourceFiles.js';
 import { parseCliArgs } from './parseCliArgs.js';
 const HELP_MESSAGE = [
@@ -65,7 +71,14 @@ export async function runCli(args, options) {
 async function runScan(projectPath) {
     let result;
     try {
-        result = await analyzeProject(projectPath);
+        // Validate mandatory root metadata, then the selected-root policy, before detector reads.
+        await loadProjectManifest(projectPath);
+        const config = await readProjectConfig(projectPath);
+        // Legacy ESLint configuration contributes configuration-only names. They are passed through the
+        // analyzer's config handoff, which merges them into `usedNames` only, so they can suppress an
+        // unused finding and can never create a missing one.
+        const configUsedNames = await collectConfigUsedNames(projectPath);
+        result = await analyzeProject(projectPath, { ...config, configUsedNames });
     }
     catch (error) {
         if (isOperationalError(error)) {
@@ -80,14 +93,33 @@ async function runScan(projectPath) {
     const hasIssues = hasDependencyIssues(result);
     return { exitCode: hasIssues ? 1 : 0, stdout: formatTerminalReport(result), stderr: '' };
 }
+/**
+ * Collect the configuration-only package names of one project.
+ *
+ * Both legacy ESLint sources share one precedence computation: a hard barrier disables both, and
+ * otherwise `.eslintrc.json` wins over the `package.json#eslintConfig` block, so the two readers are
+ * mutually exclusive and the union never combines contradictory configuration. The `package.json#jest`
+ * reader is independent of the ESLint rules but obeys the same style of guard, producing nothing once
+ * a root `jest.config.*` file exists. The analyzer re-validates and sorts the merged hints, so no
+ * ordering is imposed here.
+ */
+async function collectConfigUsedNames(projectPath) {
+    const manifestNames = await findEslintManifestUsage(projectPath);
+    const eslintRcJsonNames = await findEslintRcJsonUsage(projectPath);
+    const jestNames = await findJestManifestUsage(projectPath);
+    return new Set([...manifestNames, ...eslintRcJsonNames, ...jestNames]);
+}
 /**
  * Whether the thrown value is a scanner error the CLI knows how to render. Only the existing typed
- * error classes count; everything else is treated as an unexpected internal failure.
+ * error classes plus configuration errors count; everything else is treated as an
+ * unexpected internal failure.
  */
 function isOperationalError(error) {
     return (error instanceof ProjectManifestError ||
         error instanceof SourceFilesError ||
-        error instanceof AnalysisError);
+        error instanceof AnalysisError ||
+        error instanceof EslintRcJsonError ||
+        error instanceof ProjectConfigError);
 }
 /**
  * The fallback message for an unexpected thrown value. The path is always included so the failure

package/dist/cli/runCli.js.map

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

package/dist/config/ignoreDependencies.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Preserve exact case and spelling; validate whole entries before sorting/deduplicating.
+ * This bounded grammar is independent of source subpath normalization and builtin classification.
+ * configPath is diagnostic context only. No inventory, filesystem or registry is consulted.
+ */
+export declare function normalizeIgnoreDependencies(rawNames: readonly string[], configPath: string): readonly string[];
+//# sourceMappingURL=ignoreDependencies.d.ts.map

package/dist/config/ignoreDependencies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ignoreDependencies.d.ts","sourceRoot":"","sources":["../../src/config/ignoreDependencies.ts"],"names":[],"mappings":"AAMA;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,UAAU,EAAE,MAAM,GACjB,SAAS,MAAM,EAAE,CAUnB"}

package/dist/config/ignoreDependencies.js

@@ -0,0 +1,18 @@
+/** Exact identifier validation; analysis applies validated names only to final findings. */
+import { ProjectConfigError } from './projectConfigError.js';
+const COMPONENT = '[A-Za-z0-9][A-Za-z0-9._-]*';
+const IDENTIFIER = new RegExp(`^(?:${COMPONENT}|@${COMPONENT}/${COMPONENT})$`, 'u');
+/**
+ * Preserve exact case and spelling; validate whole entries before sorting/deduplicating.
+ * This bounded grammar is independent of source subpath normalization and builtin classification.
+ * configPath is diagnostic context only. No inventory, filesystem or registry is consulted.
+ */
+export function normalizeIgnoreDependencies(rawNames, configPath) {
+    for (const [index, name] of rawNames.entries()) {
+        if (name.length > 214 || IDENTIFIER.exec(name)?.[0] !== name) {
+            throw new ProjectConfigError(`${configPath} field ignoreDependencies[${String(index)}] must be an exact package root (name or @scope/name), at most 214 characters; components must start with ASCII alphanumeric and contain only ASCII alphanumeric, '.', '_' or '-'`, 'invalid-shape');
+        }
+    }
+    return Object.freeze([...new Set(rawNames)].sort());
+}
+//# sourceMappingURL=ignoreDependencies.js.map

package/dist/config/ignoreDependencies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ignoreDependencies.js","sourceRoot":"","sources":["../../src/config/ignoreDependencies.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,MAAM,SAAS,GAAG,4BAA4B,CAAC;AAC/C,MAAM,UAAU,GAAG,IAAI,MAAM,CAAC,OAAO,SAAS,KAAK,SAAS,IAAI,SAAS,IAAI,EAAE,GAAG,CAAC,CAAC;AAEpF;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CACzC,QAA2B,EAC3B,UAAkB;IAElB,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;QAC/C,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YAC7D,MAAM,IAAI,kBAAkB,CAC1B,GAAG,UAAU,6BAA6B,MAAM,CAAC,KAAK,CAAC,mLAAmL,EAC1O,eAAe,CAChB,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AACtD,CAAC"}

package/dist/config/ignorePaths.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Validate every raw rule before returning a normalized, sorted, deduplicated snapshot. Both slash
+ * spellings are config separators on every host. No rule destination is probed or resolved.
+ * configPath is diagnostic context supplied by the caller, not a file to read here.
+ */
+export declare function normalizeIgnorePaths(rawRules: readonly string[], configPath: string): readonly string[];
+/**
+ * Compare a canonical '/'-separated project-relative discovery path against validated rules.
+ * The caller converts native discovery separators; this matcher does not resolve or normalize
+ * candidate filenames. Matching is case-sensitive, extension-independent and segment-bounded.
+ */
+export declare function matchesIgnoredPath(projectRelativePath: string, normalizedRules: readonly string[]): boolean;
+//# sourceMappingURL=ignorePaths.d.ts.map

package/dist/config/ignorePaths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ignorePaths.d.ts","sourceRoot":"","sources":["../../src/config/ignorePaths.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,UAAU,EAAE,MAAM,GACjB,SAAS,MAAM,EAAE,CA8BnB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,mBAAmB,EAAE,MAAM,EAC3B,eAAe,EAAE,SAAS,MAAM,EAAE,GACjC,OAAO,CAIT"}

package/dist/config/ignorePaths.js

@@ -0,0 +1,47 @@
+/** Literal path policy shared by configuration validation and source discovery. */
+import { ProjectConfigError } from './projectConfigError.js';
+/**
+ * Validate every raw rule before returning a normalized, sorted, deduplicated snapshot. Both slash
+ * spellings are config separators on every host. No rule destination is probed or resolved.
+ * configPath is diagnostic context supplied by the caller, not a file to read here.
+ */
+export function normalizeIgnorePaths(rawRules, configPath) {
+    const normalized = rawRules.map((rule, index) => {
+        const fail = (reason) => {
+            throw new ProjectConfigError(`${configPath} field ignorePaths[${String(index)}] ${reason}`, 'invalid-shape');
+        };
+        // Check the original spelling: normalization must never hide a rooted or drive-relative rule.
+        if (rule.startsWith('/') || rule.startsWith('\\') || /^[A-Za-z]:/.test(rule)) {
+            fail('must be project-relative; absolute, rooted, UNC and drive-relative paths are unsupported');
+        }
+        if (rule !== rule.trim())
+            fail('must not have leading or trailing whitespace');
+        if (rule.includes(':'))
+            fail('must not contain a colon');
+        if (/\p{Cc}/u.test(rule))
+            fail('must not contain a control character');
+        if (['*', '?', '[', ']', '{', '}', '!'].some((character) => rule.includes(character))) {
+            fail('contains unsupported pattern characters; use a literal file or subtree path');
+        }
+        const segments = rule.replaceAll('\\', '/').split('/');
+        if (segments.includes('..'))
+            fail('must not contain a .. traversal segment');
+        const result = segments.filter((segment) => segment !== '' && segment !== '.').join('/');
+        if (result.length === 0)
+            fail('must name a nonempty path, not the project root');
+        // Dot/separator removal can expose whitespace that was interior in the raw spelling.
+        if (result !== result.trim())
+            fail('must not have leading or trailing whitespace after normalization');
+        return result;
+    });
+    return Object.freeze([...new Set(normalized)].sort());
+}
+/**
+ * Compare a canonical '/'-separated project-relative discovery path against validated rules.
+ * The caller converts native discovery separators; this matcher does not resolve or normalize
+ * candidate filenames. Matching is case-sensitive, extension-independent and segment-bounded.
+ */
+export function matchesIgnoredPath(projectRelativePath, normalizedRules) {
+    return normalizedRules.some((rule) => projectRelativePath === rule || projectRelativePath.startsWith(`${rule}/`));
+}
+//# sourceMappingURL=ignorePaths.js.map

package/dist/config/ignorePaths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ignorePaths.js","sourceRoot":"","sources":["../../src/config/ignorePaths.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAA2B,EAC3B,UAAkB;IAElB,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QAC9C,MAAM,IAAI,GAAG,CAAC,MAAc,EAAS,EAAE;YACrC,MAAM,IAAI,kBAAkB,CAC1B,GAAG,UAAU,sBAAsB,MAAM,CAAC,KAAK,CAAC,KAAK,MAAM,EAAE,EAC7D,eAAe,CAChB,CAAC;QACJ,CAAC,CAAC;QACF,8FAA8F;QAC9F,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7E,IAAI,CACF,0FAA0F,CAC3F,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,KAAK,IAAI,CAAC,IAAI,EAAE;YAAE,IAAI,CAAC,8CAA8C,CAAC,CAAC;QAC/E,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,IAAI,CAAC,0BAA0B,CAAC,CAAC;QACzD,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,IAAI,CAAC,sCAAsC,CAAC,CAAC;QACvE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC;YACtF,IAAI,CAAC,6EAA6E,CAAC,CAAC;QACtF,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACvD,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,IAAI,CAAC,yCAAyC,CAAC,CAAC;QAC7E,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,IAAI,CAAC,iDAAiD,CAAC,CAAC;QACjF,qFAAqF;QACrF,IAAI,MAAM,KAAK,MAAM,CAAC,IAAI,EAAE;YAC1B,IAAI,CAAC,kEAAkE,CAAC,CAAC;QAC3E,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,mBAA2B,EAC3B,eAAkC;IAElC,OAAO,eAAe,CAAC,IAAI,CACzB,CAAC,IAAI,EAAE,EAAE,CAAC,mBAAmB,KAAK,IAAI,IAAI,mBAAmB,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,CACrF,CAAC;AACJ,CAAC"}

package/dist/config/projectConfigError.d.ts

@@ -0,0 +1,7 @@
+export type ProjectConfigErrorCode = 'unreadable' | 'invalid-json' | 'invalid-shape';
+/** Operational configuration failure; broken present data must never become empty defaults. */
+export declare class ProjectConfigError extends Error {
+    readonly code: ProjectConfigErrorCode;
+    constructor(message: string, code: ProjectConfigErrorCode, cause?: unknown);
+}
+//# sourceMappingURL=projectConfigError.d.ts.map

package/dist/config/projectConfigError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectConfigError.d.ts","sourceRoot":"","sources":["../../src/config/projectConfigError.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,sBAAsB,GAAG,YAAY,GAAG,cAAc,GAAG,eAAe,CAAC;AAErF,+FAA+F;AAC/F,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;gBAE1B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,sBAAsB,EAAE,KAAK,CAAC,EAAE,OAAO;CAK3E"}

package/dist/config/projectConfigError.js

@@ -0,0 +1,10 @@
+/** Operational configuration failure; broken present data must never become empty defaults. */
+export class ProjectConfigError extends Error {
+    code;
+    constructor(message, code, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = 'ProjectConfigError';
+        this.code = code;
+    }
+}
+//# sourceMappingURL=projectConfigError.js.map

package/dist/config/projectConfigError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectConfigError.js","sourceRoot":"","sources":["../../src/config/projectConfigError.ts"],"names":[],"mappings":"AAEA,+FAA+F;AAC/F,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,IAAI,CAAyB;IAEtC,YAAY,OAAe,EAAE,IAA4B,EAAE,KAAe;QACxE,KAAK,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/config/readProjectConfig.d.ts

@@ -0,0 +1,23 @@
+export type RawProjectConfig = {
+    readonly ignorePaths: readonly string[];
+    readonly ignoreDependencies: readonly string[];
+};
+export { ProjectConfigError, type ProjectConfigErrorCode } from './projectConfigError.js';
+/**
+ * Read exactly the canonical config entry in the selected root. No parents, alternatives or rule
+ * destinations are consulted. Only absence is defaults. Present non-regular/unreadable entries and
+ * malformed documents fail as a whole. Existing root errors use the shared SourceFilesError guard.
+ *
+ * Strings retain their original spelling, order and duplicates for later semantic validators.
+ * A single leading UTF-8 BOM is accepted; all remaining syntax is native strict JSON.parse.
+ * Stable entry checks do not claim adversarial protection against replacement between I/O calls.
+ */
+export declare function readRawProjectConfig(projectRoot: string): Promise<RawProjectConfig>;
+/** Validated internal snapshot; no policy is applied to discovery or findings here. */
+export type ProjectConfig = {
+    readonly ignorePaths: readonly string[];
+    readonly ignoreDependencies: readonly string[];
+};
+/** Read once, validate all path/name rules, and return no partial configuration on failure. */
+export declare function readProjectConfig(projectRoot: string): Promise<ProjectConfig>;
+//# sourceMappingURL=readProjectConfig.d.ts.map

package/dist/config/readProjectConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readProjectConfig.d.ts","sourceRoot":"","sources":["../../src/config/readProjectConfig.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;CAChD,CAAC;AAEF,OAAO,EAAE,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAI1F;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAwDzF;AAwCD,uFAAuF;AACvF,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;CAChD,CAAC;AAEF,+FAA+F;AAC/F,wBAAsB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAOnF"}

package/dist/config/readProjectConfig.js

@@ -0,0 +1,106 @@
+/**
+ * Internal, root-only JSON configuration readers. The CLI loads readProjectConfig on scans only;
+ * only that reader returns semantically validated rules.
+ */
+import { lstat, readFile, readdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { assertReadableRoot } from '../scanner/sourceFiles.js';
+import { normalizeIgnoreDependencies } from './ignoreDependencies.js';
+import { normalizeIgnorePaths } from './ignorePaths.js';
+import { ProjectConfigError } from './projectConfigError.js';
+export { ProjectConfigError } from './projectConfigError.js';
+const CONFIG_FILENAME = 'depvitals.config.json';
+/**
+ * Read exactly the canonical config entry in the selected root. No parents, alternatives or rule
+ * destinations are consulted. Only absence is defaults. Present non-regular/unreadable entries and
+ * malformed documents fail as a whole. Existing root errors use the shared SourceFilesError guard.
+ *
+ * Strings retain their original spelling, order and duplicates for later semantic validators.
+ * A single leading UTF-8 BOM is accepted; all remaining syntax is native strict JSON.parse.
+ * Stable entry checks do not claim adversarial protection against replacement between I/O calls.
+ */
+export async function readRawProjectConfig(projectRoot) {
+    const root = resolve(projectRoot);
+    const path = join(root, CONFIG_FILENAME);
+    await assertReadableRoot(root);
+    let entries;
+    try {
+        // Exact entry-name comparison also enforces canonical casing on case-insensitive hosts.
+        entries = await readdir(root);
+    }
+    catch (error) {
+        throw unreadable(path, error);
+    }
+    if (!entries.includes(CONFIG_FILENAME))
+        return emptyConfig();
+    let info;
+    try {
+        info = await lstat(path);
+    }
+    catch (error) {
+        // The directory entry was already present, so disappearance is an error, not absence.
+        throw unreadable(path, error);
+    }
+    if (!info.isFile()) {
+        throw new ProjectConfigError(`${path} must be a regular file; symlinks and non-regular entries are not read`, 'unreadable');
+    }
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        throw unreadable(path, error);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
+    }
+    catch (error) {
+        throw new ProjectConfigError(`${path} is not valid JSON`, 'invalid-json', error);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new ProjectConfigError(`${path} must contain a JSON object`, 'invalid-shape');
+    }
+    for (const key of Object.keys(parsed)) {
+        if (key !== 'ignorePaths' && key !== 'ignoreDependencies') {
+            throw new ProjectConfigError(`${path} has unsupported field ${JSON.stringify(key)}; only ignorePaths and ignoreDependencies are supported`, 'invalid-shape');
+        }
+    }
+    const config = parsed;
+    return Object.freeze({
+        ignorePaths: readStrings(config['ignorePaths'], 'ignorePaths', path),
+        ignoreDependencies: readStrings(config['ignoreDependencies'], 'ignoreDependencies', path),
+    });
+}
+function readStrings(value, field, path) {
+    if (value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value)) {
+        throw new ProjectConfigError(`${path} field ${field} must be an array of strings`, 'invalid-shape');
+    }
+    const strings = [];
+    for (let index = 0; index < value.length; index++) {
+        const entry = value[index];
+        if (typeof entry !== 'string' || entry.trim().length === 0) {
+            throw new ProjectConfigError(`${path} field ${field}[${String(index)}] must be a nonempty, non-whitespace string`, 'invalid-shape');
+        }
+        strings.push(entry);
+    }
+    return Object.freeze(strings);
+}
+function emptyConfig() {
+    return Object.freeze({ ignorePaths: Object.freeze([]), ignoreDependencies: Object.freeze([]) });
+}
+function unreadable(path, cause) {
+    return new ProjectConfigError(`Could not read ${CONFIG_FILENAME} at ${path}`, 'unreadable', cause);
+}
+/** Read once, validate all path/name rules, and return no partial configuration on failure. */
+export async function readProjectConfig(projectRoot) {
+    const raw = await readRawProjectConfig(projectRoot);
+    const path = join(resolve(projectRoot), CONFIG_FILENAME);
+    return Object.freeze({
+        ignorePaths: normalizeIgnorePaths(raw.ignorePaths, path),
+        ignoreDependencies: normalizeIgnoreDependencies(raw.ignoreDependencies, path),
+    });
+}
+//# sourceMappingURL=readProjectConfig.js.map

package/dist/config/readProjectConfig.js.map

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

package/dist/core/analyzeProject.d.ts

@@ -24,20 +24,27 @@
  * once and parsed once. No concurrency pool, cache or index is introduced before a measured need
  * appears.
  *
- * Usage/missing formulas (`usedNames` is the union of source-external package roots and script-used
- * package names; `declaredDependencyNames` is the union of every declared dependency section):
+ * Usage/missing formulas (`usedNames` is the union of source-external package roots, script-used
+ * package names and validated configuration-only package names; `declaredDependencyNames` is the
+ * union of every declared dependency section):
  *
  * ```text
  * sourceUsedNames = external package roots extracted from source files
  * scriptUsedNames = findPackageScriptUsage(scripts, dependencies ∪ devDependencies)
- * usedNames       = sourceUsedNames ∪ scriptUsedNames
+ * configUsedNames = validated configuration-only names handed to the analyzer (empty for now)
+ * usedNames       = sourceUsedNames ∪ scriptUsedNames ∪ configUsedNames
  * unusedDependencies    = dependencies    − usedNames
  * unusedDevDependencies = devDependencies − usedNames
  * missingDependencies   = sourceUsedNames − declaredDependencyNames
  * ```
  *
- * Scripts never generate missing-dependency findings, and peer/optional declarations suppress false
- * missing results through `declaredDependencyNames`.
+ * The evidence sources are deliberately asymmetric:
+ * - source imports and requires may contribute to `missingDependencies`;
+ * - package scripts and validated static tool configuration may only suppress an unused finding and
+ *   can never create a missing finding, because a command or configuration string is not evidence
+ *   that source code references the package.
+ *
+ * Peer/optional declarations suppress false missing results through `declaredDependencyNames`.
  */
 /**
  * The structured outcome of a dependency analysis.
@@ -57,6 +64,39 @@ export type AnalysisResult = {
     /** External packages referenced by source but not declared anywhere, sorted alphabetically. */
     missingDependencies: readonly string[];
 };
+/**
+ * Internal handoff for package names recognized by a validated static configuration reader.
+ *
+ * This is deliberately not the future public `why` evidence model: it carries no location, kind, or
+ * explanation, and it is never rendered or exposed. A configuration reader hands the package names it
+ * recognized to the analyzer through this set; only {@link analyzeProject} turns them into final
+ * unused/missing categories, so no configuration reader may edit report arrays directly.
+ *
+ * The analyzer validates every entry with {@link classifyPackageSpecifier} before using it, so
+ * arbitrary configuration text can never be treated as a package name. Accepted entries are collapsed
+ * to their package root and deduplicated case-sensitively, matching package-specifier classification
+ * (names are compared case-sensitively throughout DepVitals).
+ *
+ * The set may only suppress unused findings; it is never merged into the source-derived names that
+ * produce missing findings.
+ */
+export type ConfigUsageHints = ReadonlySet<string>;
+/**
+ * Optional inputs for {@link analyzeProject}.
+ */
+export type AnalysisOptions = {
+    /**
+     * Validated configuration-only package names, see {@link ConfigUsageHints}.
+     *
+     * Omitted or empty is the default, which is the state of the released product: no configuration
+     * rule is active yet, so the default keeps every report byte-for-byte identical.
+     */
+    readonly configUsedNames?: ConfigUsageHints | undefined;
+    /** Validated, normalized literal paths excluded from source discovery only; omitted is empty. */
+    readonly ignorePaths?: readonly string[] | undefined;
+    /** Validated exact package roots omitted from final findings only; never usage evidence. */
+    readonly ignoreDependencies?: readonly string[] | undefined;
+};
 /**
  * Why the analysis could not complete.
  *
@@ -84,9 +124,11 @@ export declare class AnalysisError extends Error {
  * The supplied root is resolved to an absolute path; `process.cwd()` is never changed and the target
  * project is never written to.
  *
+ * @param projectRoot - Directory to analyze.
+ * @param options - Optional static tool hints and validated source exclusions; omitted inputs change nothing.
  * @throws {AnalysisError} when a discovered source file cannot be read or cannot be safely analyzed.
  * @throws {ProjectManifestError} when the manifest is missing, unreadable, invalid or malformed.
  * @throws {SourceFilesError} when the root is missing, is not a directory, or cannot be read.
  */
-export declare function analyzeProject(projectRoot: string): Promise<AnalysisResult>;
+export declare function analyzeProject(projectRoot: string, options?: AnalysisOptions): Promise<AnalysisResult>;
 //# sourceMappingURL=analyzeProject.d.ts.map