depvitals 0.2.0 → 0.4.0

package/dist/config/ignoreDependencies.js

@@ -0,0 +1,22 @@
+/** 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');
+/** Shared exact-root grammar for dependency exclusions and explanation input; no normalization. */
+export function isExactPackageRoot(name) {
+    return name.length <= 214 && IDENTIFIER.exec(name)?.[0] === name;
+}
+/**
+ * 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 (!isExactPackageRoot(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,mGAAmG;AACnG,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,IAAI,CAAC,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;AACnE,CAAC;AAED;;;;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,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9B,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,28 @@
+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>;
+/** Per-scan policy and entry names; not an atomic filesystem snapshot or a global cache. */
+export declare function readProjectConfigSnapshot(projectRoot: string): Promise<{
+    config: ProjectConfig;
+    rootEntries: readonly string[];
+}>;
+//# 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,CAEzF;AAyGD,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,CAEnF;AAED,4FAA4F;AAC5F,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC,CAUpE"}

package/dist/config/readProjectConfig.js

@@ -0,0 +1,120 @@
+/**
+ * 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) {
+    return (await readRawConfigWithEntries(projectRoot)).raw;
+}
+/** Preserve canonical-entry checks and errors while sharing this read's entry names. */
+async function readRawConfigWithEntries(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 { raw: emptyConfig(), rootEntries: Object.freeze(entries) };
+    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 {
+        raw: Object.freeze({
+            ignorePaths: readStrings(config['ignorePaths'], 'ignorePaths', path),
+            ignoreDependencies: readStrings(config['ignoreDependencies'], 'ignoreDependencies', path),
+        }),
+        rootEntries: Object.freeze(entries),
+    };
+}
+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) {
+    return (await readProjectConfigSnapshot(projectRoot)).config;
+}
+/** Per-scan policy and entry names; not an atomic filesystem snapshot or a global cache. */
+export async function readProjectConfigSnapshot(projectRoot) {
+    const { raw, rootEntries } = await readRawConfigWithEntries(projectRoot);
+    const path = join(resolve(projectRoot), CONFIG_FILENAME);
+    return {
+        config: Object.freeze({
+            ignorePaths: normalizeIgnorePaths(raw.ignorePaths, path),
+            ignoreDependencies: normalizeIgnoreDependencies(raw.ignoreDependencies, path),
+        }),
+        rootEntries,
+    };
+}
+//# 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

@@ -46,6 +46,9 @@
  *
  * Peer/optional declarations suppress false missing results through `declaredDependencyNames`.
  */
+import { type ProjectManifest } from '../scanner/projectManifest.js';
+import type { ScanContext } from './scanContext.js';
+import { type FindingCategory, type PackageFact } from './evidence.js';
 /**
  * The structured outcome of a dependency analysis.
  *
@@ -64,6 +67,17 @@ export type AnalysisResult = {
     /** External packages referenced by source but not declared anywhere, sorted alphabetically. */
     missingDependencies: readonly string[];
 };
+/** Internal categories before or after dependency policy; no additional finding kind. */
+export type AnalysisFindings = Pick<AnalysisResult, 'unusedDependencies' | 'unusedDevDependencies' | 'missingDependencies'>;
+/** Complete internal scan facts. Presentation projects explicit fields instead of serializing this object. */
+export type DetailedAnalysisResult = {
+    readonly projectRoot: string;
+    readonly manifest: ProjectManifest;
+    readonly config: ScanContext['config'];
+    readonly underlyingFindings: AnalysisFindings;
+    readonly findings: AnalysisFindings;
+    readonly packages: readonly PackageFact[];
+};
 /**
  * Internal handoff for package names recognized by a validated static configuration reader.
  *
@@ -92,6 +106,10 @@ export type AnalysisOptions = {
      * 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.
@@ -121,10 +139,31 @@ export declare class AnalysisError extends Error {
  * project is never written to.
  *
  * @param projectRoot - Directory to analyze.
- * @param options - Optional {@link ConfigUsageHints}; an omitted or empty set changes nothing.
+ * @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, options?: AnalysisOptions): Promise<AnalysisResult>;
+/** Keep the small CLI/legacy result projection while collecting the same complete scan facts. */
+export declare function analyzeProjectWithContext(context: ScanContext): Promise<AnalysisResult>;
+/** Detailed analysis accepts eligible typed facts only, never the legacy names-only hint seam. */
+export declare function analyzeProjectDetailed(context: ScanContext): Promise<DetailedAnalysisResult>;
+/** Pure legacy projection; no collection, reclassification or input reads. */
+export declare function projectAnalysisResult(result: DetailedAnalysisResult): AnalysisResult;
+/** Internal package-local outcome; effective scan policy remains available to later reporters. */
+export type PackageExplanation = {
+    readonly projectRoot: string;
+    readonly config: DetailedAnalysisResult['config'];
+    readonly findings: AnalysisFindings;
+    readonly counts: Readonly<Record<FindingCategory, number>>;
+    readonly packages: readonly [PackageFact];
+    readonly query: {
+        readonly packageName: string;
+        readonly known: boolean;
+    };
+    readonly exitCode: 0 | 1;
+};
+/** Project only completed scan facts. This function performs no collection or resolution. */
+export declare function projectPackageExplanation(result: DetailedAnalysisResult, packageName: string): PackageExplanation;
 //# sourceMappingURL=analyzeProject.d.ts.map

package/dist/core/analyzeProject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzeProject.d.ts","sourceRoot":"","sources":["../../src/core/analyzeProject.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAWH;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,uDAAuD;IACvD,qBAAqB,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,+FAA+F;IAC/F,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,gBAAgB,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;AAEnD;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;CACzD,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,mBAAmB,GAAG,gBAAgB,CAAC;AAEvE;;;;;;;GAOG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;gBAErB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,CAAC,EAAE,OAAO;CAKtE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAqDzB"}
+{"version":3,"file":"analyzeProject.d.ts","sourceRoot":"","sources":["../../src/core/analyzeProject.ts"],"names":[],"mappings":"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"}