depvitals 0.2.0 → 0.4.0

package/dist/scanner/sourceFiles.d.ts

@@ -8,7 +8,7 @@
  * It deliberately does not:
  * - read, parse or execute any discovered file (that belongs to the analyzers / specifier extractor);
  * - decide whether anything is used, unused or missing;
- * - parse `.gitignore` or honor custom ignore configuration (`v0.1.0` uses a fixed built-in set);
+ * - parse `.gitignore` or load user configuration (callers supply validated literal rules);
  * - follow symlinks, which avoids cycles and scanning content outside the intended project tree;
  * - mutate the analyzed project.
  *
@@ -16,10 +16,19 @@
  * instead of walking every subtree and filtering afterwards. The result is sorted deterministically
  * so the same tree always yields the same order.
  */
+/** Pure effective defaults for report scope; never starts discovery or exposes mutable sets. */
+export declare function sourceDiscoveryDefaults(): {
+    sourceExtensions: readonly string[];
+    excludedDirectories: readonly string[];
+};
 /**
  * A discovered source file as an absolute, platform-separated path, sorted lexicographically.
  */
 export type DiscoveredSourceFile = string;
+/** Internal discovery inputs; callers supply normalized, validated project-relative rules. */
+export type SourceDiscoveryOptions = {
+    readonly ignorePaths?: readonly string[] | undefined;
+};
 /**
  * Why source discovery could not run.
  *
@@ -48,5 +57,15 @@ export declare class SourceFilesError extends Error {
  *
  * @throws {SourceFilesError} when the root is missing, is not a directory, or cannot be read.
  */
-export declare function discoverSourceFiles(projectRoot: string): Promise<readonly DiscoveredSourceFile[]>;
+export declare function discoverSourceFiles(projectRoot: string, options?: SourceDiscoveryOptions): Promise<readonly DiscoveredSourceFile[]>;
+/**
+ * Validate that the resolved root exists and is a directory before walking it. A missing root is
+ * reported separately from a root that is a regular file, and any other I/O failure stays
+ * `unreadable`.
+ *
+ * `lstat` (not `stat`) is used on purpose: it does not follow a symlink supplied as the root, so a
+ * symlinked root is rejected instead of being traversed, keeping the "never follow symlinks"
+ * contract consistent from the entry point down.
+ */
+export declare function assertReadableRoot(root: string): Promise<void>;
 //# sourceMappingURL=sourceFiles.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"sourceFiles.d.ts","sourceRoot":"","sources":["../../src/scanner/sourceFiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA2CH;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAE1C;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,iBAAiB,GAAG,YAAY,CAAC;AAEhF;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;gBAExB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,EAAE,KAAK,CAAC,EAAE,OAAO;CAKzE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,SAAS,oBAAoB,EAAE,CAAC,CAY1C"}
+{"version":3,"file":"sourceFiles.d.ts","sourceRoot":"","sources":["../../src/scanner/sourceFiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA6CH,gGAAgG;AAChG,wBAAgB,uBAAuB,IAAI;IACzC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC,CAKA;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAE1C,8FAA8F;AAC9F,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CACtD,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,iBAAiB,GAAG,YAAY,CAAC;AAEhF;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;gBAExB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,EAAE,KAAK,CAAC,EAAE,OAAO;CAKzE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,SAAS,oBAAoB,EAAE,CAAC,CAY1C;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBpE"}

package/dist/scanner/sourceFiles.js

@@ -8,7 +8,7 @@
  * It deliberately does not:
  * - read, parse or execute any discovered file (that belongs to the analyzers / specifier extractor);
  * - decide whether anything is used, unused or missing;
- * - parse `.gitignore` or honor custom ignore configuration (`v0.1.0` uses a fixed built-in set);
+ * - parse `.gitignore` or load user configuration (callers supply validated literal rules);
  * - follow symlinks, which avoids cycles and scanning content outside the intended project tree;
  * - mutate the analyzed project.
  *
@@ -18,6 +18,7 @@
  */
 import { lstat, readdir } from 'node:fs/promises';
 import { extname, join, resolve } from 'node:path';
+import { matchesIgnoredPath } from '../config/ignorePaths.js';
 /**
  * The supported source and declaration extensions for `v0.1.0`.
  *
@@ -54,6 +55,13 @@ const IGNORED_DIRECTORY_NAMES = new Set([
     '.next',
     '.nuxt',
 ]);
+/** Pure effective defaults for report scope; never starts discovery or exposes mutable sets. */
+export function sourceDiscoveryDefaults() {
+    return {
+        sourceExtensions: [...SUPPORTED_EXTENSIONS].sort(),
+        excludedDirectories: [...IGNORED_DIRECTORY_NAMES].sort(),
+    };
+}
 /**
  * Operational error for source discovery. The `code` lets callers (the CLI in a later step) render
  * a clean message without matching on error strings.
@@ -77,11 +85,11 @@ export class SourceFilesError extends Error {
  *
  * @throws {SourceFilesError} when the root is missing, is not a directory, or cannot be read.
  */
-export async function discoverSourceFiles(projectRoot) {
+export async function discoverSourceFiles(projectRoot, options = {}) {
     const root = resolve(projectRoot);
     await assertReadableRoot(root);
     const files = [];
-    await walk(root, files);
+    await walk(root, '', files, options.ignorePaths ?? []);
     // Sort the final result so the contract is explicitly deterministic regardless of filesystem
     // enumeration order.
     files.sort(comparePaths);
@@ -96,7 +104,7 @@ export async function discoverSourceFiles(projectRoot) {
  * symlinked root is rejected instead of being traversed, keeping the "never follow symlinks"
  * contract consistent from the entry point down.
  */
-async function assertReadableRoot(root) {
+export async function assertReadableRoot(root) {
     try {
         const info = await lstat(root);
         if (info.isSymbolicLink()) {
@@ -117,7 +125,7 @@ async function assertReadableRoot(root) {
  * Recursively collect supported files under `directory`, pruning ignored directories and skipping
  * symlinks before descending.
  */
-async function walk(directory, files) {
+async function walk(directory, relativeDirectory, files, ignorePaths) {
     let entries;
     try {
         entries = await readdir(directory, { withFileTypes: true });
@@ -130,13 +138,18 @@ async function walk(directory, files) {
         if (entry.isSymbolicLink()) {
             continue;
         }
+        // Build the portable matching path from directory entries, preserving literal backslashes on
+        // POSIX. Only traversal separators become '/', independently of the host's native separator.
+        const relativePath = relativeDirectory === '' ? entry.name : `${relativeDirectory}/${entry.name}`;
+        if (matchesIgnoredPath(relativePath, ignorePaths))
+            continue;
         const fullPath = join(directory, entry.name);
         if (entry.isDirectory()) {
             if (IGNORED_DIRECTORY_NAMES.has(entry.name)) {
                 // Prune before descending so trees like `node_modules` are never enumerated.
                 continue;
             }
-            await walk(fullPath, files);
+            await walk(fullPath, relativePath, files, ignorePaths);
             continue;
         }
         if (entry.isFile() && isSupportedFile(entry.name)) {

package/dist/scanner/sourceFiles.js.map

@@ -1 +1 @@
-{"version":3,"file":"sourceFiles.js","sourceRoot":"","sources":["../../src/scanner/sourceFiles.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sourceFiles.js","sourceRoot":"","sources":["../../src/scanner/sourceFiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAE9D;;;;;;;;;GASG;AACH,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC;IACnC,KAAK;IACL,MAAM;IACN,MAAM;IACN,MAAM;IACN,KAAK;IACL,MAAM;IACN,MAAM;IACN,MAAM;CACP,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,uBAAuB,GAAG,IAAI,GAAG,CAAC;IACtC,MAAM;IACN,cAAc;IACd,MAAM;IACN,OAAO;IACP,UAAU;IACV,KAAK;IACL,QAAQ;IACR,QAAQ;IACR,OAAO;IACP,OAAO;CACR,CAAC,CAAC;AAEH,gGAAgG;AAChG,MAAM,UAAU,uBAAuB;IAIrC,OAAO;QACL,gBAAgB,EAAE,CAAC,GAAG,oBAAoB,CAAC,CAAC,IAAI,EAAE;QAClD,mBAAmB,EAAE,CAAC,GAAG,uBAAuB,CAAC,CAAC,IAAI,EAAE;KACzD,CAAC;AACJ,CAAC;AAsBD;;;GAGG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,IAAI,CAAuB;IAEpC,YAAY,OAAe,EAAE,IAA0B,EAAE,KAAe;QACtE,KAAK,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,WAAmB,EACnB,UAAkC,EAAE;IAEpC,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAClC,MAAM,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAE/B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;IAEvD,6FAA6F;IAC7F,qBAAqB;IACrB,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAEzB,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAAY;IACnD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;QAE/B,IAAI,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC;YAC1B,MAAM,IAAI,gBAAgB,CACxB,gBAAgB,IAAI,wCAAwC,EAC5D,iBAAiB,CAClB,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,MAAM,IAAI,gBAAgB,CACxB,gBAAgB,IAAI,gCAAgC,EACpD,iBAAiB,CAClB,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,gBAAgB,EAAE,CAAC;YACtC,MAAM,KAAK,CAAC;QACd,CAAC;QAED,MAAM,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACjC,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,IAAI,CACjB,SAAiB,EACjB,iBAAyB,EACzB,KAAe,EACf,WAA8B;IAE9B,IAAI,OAAO,CAAC;IAEZ,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,gBAAgB,CACxB,4BAA4B,SAAS,KAAK,SAAS,CAAC,KAAK,CAAC,EAAE,EAC5D,YAAY,EACZ,KAAK,CACN,CAAC;IACJ,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,uFAAuF;QACvF,IAAI,KAAK,CAAC,cAAc,EAAE,EAAE,CAAC;YAC3B,SAAS;QACX,CAAC;QAED,6FAA6F;QAC7F,6FAA6F;QAC7F,MAAM,YAAY,GAChB,iBAAiB,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,iBAAiB,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;QAC/E,IAAI,kBAAkB,CAAC,YAAY,EAAE,WAAW,CAAC;YAAE,SAAS;QAE5D,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAE7C,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,IAAI,uBAAuB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC5C,6EAA6E;gBAC7E,SAAS;YACX,CAAC;YAED,MAAM,IAAI,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;YACvD,SAAS;QACX,CAAC;QAED,IAAI,KAAK,CAAC,MAAM,EAAE,IAAI,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAClD,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAS,eAAe,CAAC,QAAgB;IACvC,OAAO,oBAAoB,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;AACrD,CAAC;AAED;;;GAGG;AACH,SAAS,WAAW,CAAC,IAAY,EAAE,KAAc;IAC/C,IAAI,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,IAAI,gBAAgB,CAAC,gBAAgB,IAAI,iBAAiB,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IACvF,CAAC;IAED,OAAO,IAAI,gBAAgB,CACzB,+BAA+B,IAAI,KAAK,SAAS,CAAC,KAAK,CAAC,EAAE,EAC1D,YAAY,EACZ,KAAK,CACN,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC;IAED,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED;;GAEG;AACH,SAAS,eAAe,CAAC,KAAc;IACrC,OAAO,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC;AAC9E,CAAC;AAED;;GAEG;AACH,SAAS,YAAY,CAAC,CAAS,EAAE,CAAS;IACxC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACV,OAAO,CAAC,CAAC,CAAC;IACZ,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACV,OAAO,CAAC,CAAC;IACX,CAAC;IAED,OAAO,CAAC,CAAC;AACX,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "depvitals",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Find unused and undeclared npm dependencies in JavaScript and TypeScript projects with a zero-config CLI and no runtime dependencies.",
   "keywords": [
     "nodejs",
@@ -30,7 +30,8 @@
   "homepage": "https://github.com/MatiasRicardi/depvitals#readme",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "schemas"
   ],
   "bin": {
     "depvitals": "./dist/cli/index.js"
@@ -59,6 +60,7 @@
     "@eslint/js": "10.0.1",
     "@types/node": "22.20.5",
     "@vitest/coverage-v8": "5.0.3",
+    "ajv": "6.15.0",
     "eslint": "10.12.0",
     "eslint-config-prettier": "10.1.8",
     "globals": "17.13.0",

package/schemas/README.md

@@ -0,0 +1,47 @@
+# DepVitals JSON report format v1
+
+[report-v1.schema.json](report-v1.schema.json) is the Draft 7 schema for dependency scans and exact-package explanations. It is a data artifact, not a JavaScript API or a runtime validation dependency. The schema version is independent of the CLI release version; `tool.version` identifies the actual producing version.
+
+A report is one UTF-8 JSON document, indented by two spaces, followed by one LF. Its fields are `schemaVersion`, `tool`, `mode`, `project`, `scope`, `findings`, `counts`, `packages` and `query`, in that order. There are no timestamps, durations, banners or error-shaped documents. An operational failure produces no report.
+
+`project.root` is the absolute native-platform root. Evidence filenames are relative paths using `/` separators, preserving casing and literal filename characters. JSON escaping preserves the original strings, including control characters and backslashes; terminal display escaping is separate. Changing the checkout root changes document identity.
+
+`scope` contains the actual source extensions, fixed excluded directory names and effective normalized `ignorePaths` and `ignoreDependencies`. It describes supported discovery, not proof that a package can safely be removed. Source evidence can suppress unused findings and produce missing findings. Script/config evidence only credits eligible declared packages. Exclusions are policy, not evidence.
+
+A package retains all four declaration memberships, status, dependency exclusion, underlying findings before exclusions, visible findings after exclusions and genuine source/script/config evidence. Unused dependencies and devDependencies remain separate, including when a name occurs in both. Peer/optional-only declarations are not unused candidates. Exclusion preserves evidence and underlying findings while hiding visible findings.
+
+In scan mode, `query` is null. In explanation mode, exactly one package and its visible findings/counts are reported, with `{ "packageName": "...", "known": true }` or false. An absent valid query is a completed unknown record; exclusion-only names are known. Unrelated findings are omitted, but unrelated retained-input errors still prevent completion of the scan.
+
+Consumers should ignore unknown object properties. In addition to schema validation, check that counts equal corresponding visible array lengths, packages agree with findings/status, query identity matches its single record and all prescribed sorting/identity rules hold. Schema validation alone cannot prove these relationships or the correctness of source locations.
+
+## Ordering and duplicate identity
+
+All string comparisons use case-sensitive ECMAScript lexicographic order over UTF-16 code units, independent of locale. Do not lowercase or Unicode-normalize strings. Findings and each scope array are sorted and duplicate-free. Packages are unique by exact `name` and sorted by that string; an empty scanned name remains valid data.
+
+Declaration groups always follow `dependencies`, `devDependencies`, `peerDependencies`, `optionalDependencies`. Finding identifiers in package `underlyingFindings` and `findings` always follow `unusedDependencies`, `unusedDevDependencies`, `missingDependencies`. These arrays have no duplicates. The three fields in the envelope's findings/counts objects follow that same category order. Count each category independently: a name unused in both dependency groups contributes one to each corresponding count.
+
+Within each package, evidence is ordered by kind (source, script, config), then by `file` using the string comparison above, then by these kind-specific fields, in order:
+
+| Kind   | Remaining sort keys                                                                                                                                                                                               |
+| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| source | Numeric `position.offset`; reference rank `import`, `export-from`, `dynamic-import`, `require`; `specifier`; numeric `position.line`; numeric `position.column`. The final two keys break ties deterministically. |
+| script | `pointer`; numeric `occurrence`; via rank `direct`, `mapping`, `runner`, `node-preload`; `command`.                                                                                                               |
+| config | `pointer`; detector rank `eslint`, `jest`; `value`.                                                                                                                                                               |
+
+Deduplicate only complete semantic records of the same kind. Source identity includes `kind`, `file`, `reference`, `specifier` and all three position fields. Script identity includes `kind`, `file`, `pointer`, `command`, `via` and `occurrence`. Config identity includes `kind`, `file`, `pointer`, `value` and `detector`. Object-property insertion order and unrecognized additive properties do not change these identities. Distinct offsets, script ordinals, config pointers or kinds remain distinct even when they name the same package or selector. Do not deduplicate solely by package name or specifier.
+
+## Evidence meaning and position units
+
+Source records have fields `kind`, `file`, `reference`, `specifier`, `position`, in that order; position has `offset`, `line`, `column`. The specifier is the decoded recognized string before package-root normalization. A subpath may therefore differ from the owning package name.
+
+`position.offset` is the zero-based UTF-16 code-unit offset of the opening quote of the specifier literal in the original source text decoded as UTF-8. It points to the quote, not the import/require keyword. Lines and columns are one-based; columns count UTF-16 code units, not bytes, Unicode scalar values or display width. A tab adds one column and a surrogate pair adds two. LF, CR, CRLF, U+2028 and U+2029 end a line, with CRLF counted once. Do not normalize line endings or strip a BOM before measuring: both CRLF code units participate in offsets, and a BOM participates in offsets/columns. Escapes are decoded in `specifier` but positions still refer to the original source spelling. No end position or JSON-config character position is implied.
+
+Evidence filenames are lexical project-relative paths with `/` separators and no leading slash, empty component, `.` or `..` component. Preserve actual casing; a literal backslash in a POSIX filename remains data. Do not resolve filesystem targets to interpret a display path.
+
+Script fields are `kind`, `file`, `pointer`, `command`, `via`, `occurrence`. The file is `package.json`; the pointer identifies the actual script key. `command` is the dequoted semantic selector: executable for direct/mapped commands, immediate package argument for a supported runner, or module selector without the option prefix for a supported Node preload. It is not the complete script text or an installed executable path. `occurrence` is a zero-based ordinal of accepted external candidate events across the whole script, before declaration filtering, deduplication or dependency exclusions; it resets per script key. Undeclared external candidates consume ordinals; internal/builtin/unsupported selectors and discarded candidates do not. Repeated accepted selectors keep distinct ordinals. Script credit remains gated to dependencies/devDependencies and never creates missing findings.
+
+Config fields are `kind`, `file`, `pointer`, `value`, `detector`. The filename preserves the actual selected configuration filename's casing. `value` is the exact recognized string, not inferred source usage. The detector is `eslint` or `jest`; only eligible declared packages gain config evidence. Neither config nor script records claim source line/column positions.
+
+Pointers are RFC 6901 data pointers, not URL fragments: escape each object-key token's `~` as `~0` and `/` as `~1`; array indices are zero-based decimal without leading zeroes. A pointer identifies the exact string field/array element, not a config object or transformer options. Preserve original pointer strings through JSON escaping; do not percent-encode them or interpret literal escape text as a control character.
+
+The six [normative examples](examples/README.md) illustrate target-release documents. They are not evidence of release publication or feature availability in an earlier installed CLI. No package JavaScript entrypoint is introduced.

package/schemas/examples/README.md

@@ -0,0 +1,27 @@
+# Report format v1 examples
+
+These six normative examples describe the target v0.4.0 release. Their conceptual root is `/example/project` and their illustrative `tool.version` is `0.4.0`; actual reports use the real selected root and installed tool version. They do not claim that an earlier CLI already accepts format or explanation options. See the [schema](../report-v1.schema.json) and [format description](../README.md).
+
+| Document                                               | Scenario and intended exit                                                                                                                                                                                               |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [scan-clean.json](scan-clean.json)                     | Empty manifest and no supported source; scan exit 0.                                                                                                                                                                     |
+| [scan-findings.json](scan-findings.json)               | Dependencies declare `unused`, devDependencies declare `unused-tool`; `src/index.ts` contains `import item from 'missing';` and a final LF. Scan exit 1. The quote is at zero-based UTF-16 offset 17, line 1, column 18. |
+| [explain-missing.json](explain-missing.json)           | Query `missing` in that same project; exit 1, excluding unrelated unused findings.                                                                                                                                       |
+| [explain-excluded.json](explain-excluded.json)         | Dependency `unused`, no sources, exact ignoreDependencies entry `unused`; query exit 0, preserving its underlying unused finding.                                                                                        |
+| [explain-unknown.json](explain-unknown.json)           | Empty project, query `absent`; completed unknown record and exit 1.                                                                                                                                                      |
+| [explain-node-preload.json](explain-node-preload.json) | Dev dependency `preload` used by the selected Node preload recognition described below; query exit 0.                                                                                                                    |
+
+The Node-preload example assumes this manifest and an empty `entry.cjs`:
+
+```json
+{
+  "devDependencies": { "preload": "1" },
+  "scripts": {
+    "check/node~": "unlisted-tool && node --import=preload/esm --import=preload/esm ./entry.cjs"
+  }
+}
+```
+
+The candidate ordinals are unlisted-tool=0, node=1, preload=2 and preload=3 before declaration filtering. The undeclared commands create no package records or missing findings. The two preload selectors retain distinct script occurrences and the escaped pointer `/scripts/check~1node~0`. Their module selector is `preload/esm`, owned by package `preload`, without installed resolution or execution. This example describes the target recognition; serializing supplied facts alone does not establish that a particular CLI version collects them.
+
+Invalid manifest/config/source inputs intentionally have no report fixture. Their expected stdout is empty, stderr identifies the error and exit is 1. They must not be represented as successful clean documents.

package/schemas/examples/explain-excluded.json

@@ -0,0 +1,53 @@
+{
+  "schemaVersion": 1,
+  "tool": {
+    "name": "depvitals",
+    "version": "0.4.0"
+  },
+  "mode": "explain",
+  "project": {
+    "root": "/example/project"
+  },
+  "scope": {
+    "sourceExtensions": [".cjs", ".cts", ".js", ".jsx", ".mjs", ".mts", ".ts", ".tsx"],
+    "excludedDirectories": [
+      ".cache",
+      ".git",
+      ".next",
+      ".nuxt",
+      ".turbo",
+      "build",
+      "coverage",
+      "dist",
+      "node_modules",
+      "out"
+    ],
+    "ignorePaths": [],
+    "ignoreDependencies": ["unused"]
+  },
+  "findings": {
+    "unusedDependencies": [],
+    "unusedDevDependencies": [],
+    "missingDependencies": []
+  },
+  "counts": {
+    "unusedDependencies": 0,
+    "unusedDevDependencies": 0,
+    "missingDependencies": 0
+  },
+  "packages": [
+    {
+      "name": "unused",
+      "status": "excluded",
+      "declaredIn": ["dependencies"],
+      "excluded": true,
+      "underlyingFindings": ["unusedDependencies"],
+      "findings": [],
+      "evidence": []
+    }
+  ],
+  "query": {
+    "packageName": "unused",
+    "known": true
+  }
+}

package/schemas/examples/explain-missing.json

@@ -0,0 +1,65 @@
+{
+  "schemaVersion": 1,
+  "tool": {
+    "name": "depvitals",
+    "version": "0.4.0"
+  },
+  "mode": "explain",
+  "project": {
+    "root": "/example/project"
+  },
+  "scope": {
+    "sourceExtensions": [".cjs", ".cts", ".js", ".jsx", ".mjs", ".mts", ".ts", ".tsx"],
+    "excludedDirectories": [
+      ".cache",
+      ".git",
+      ".next",
+      ".nuxt",
+      ".turbo",
+      "build",
+      "coverage",
+      "dist",
+      "node_modules",
+      "out"
+    ],
+    "ignorePaths": [],
+    "ignoreDependencies": []
+  },
+  "findings": {
+    "unusedDependencies": [],
+    "unusedDevDependencies": [],
+    "missingDependencies": ["missing"]
+  },
+  "counts": {
+    "unusedDependencies": 0,
+    "unusedDevDependencies": 0,
+    "missingDependencies": 1
+  },
+  "packages": [
+    {
+      "name": "missing",
+      "status": "missing",
+      "declaredIn": [],
+      "excluded": false,
+      "underlyingFindings": ["missingDependencies"],
+      "findings": ["missingDependencies"],
+      "evidence": [
+        {
+          "kind": "source",
+          "file": "src/index.ts",
+          "reference": "import",
+          "specifier": "missing",
+          "position": {
+            "offset": 17,
+            "line": 1,
+            "column": 18
+          }
+        }
+      ]
+    }
+  ],
+  "query": {
+    "packageName": "missing",
+    "known": true
+  }
+}

package/schemas/examples/explain-node-preload.json

@@ -0,0 +1,70 @@
+{
+  "schemaVersion": 1,
+  "tool": {
+    "name": "depvitals",
+    "version": "0.4.0"
+  },
+  "mode": "explain",
+  "project": {
+    "root": "/example/project"
+  },
+  "scope": {
+    "sourceExtensions": [".cjs", ".cts", ".js", ".jsx", ".mjs", ".mts", ".ts", ".tsx"],
+    "excludedDirectories": [
+      ".cache",
+      ".git",
+      ".next",
+      ".nuxt",
+      ".turbo",
+      "build",
+      "coverage",
+      "dist",
+      "node_modules",
+      "out"
+    ],
+    "ignorePaths": [],
+    "ignoreDependencies": []
+  },
+  "findings": {
+    "unusedDependencies": [],
+    "unusedDevDependencies": [],
+    "missingDependencies": []
+  },
+  "counts": {
+    "unusedDependencies": 0,
+    "unusedDevDependencies": 0,
+    "missingDependencies": 0
+  },
+  "packages": [
+    {
+      "name": "preload",
+      "status": "used",
+      "declaredIn": ["devDependencies"],
+      "excluded": false,
+      "underlyingFindings": [],
+      "findings": [],
+      "evidence": [
+        {
+          "kind": "script",
+          "file": "package.json",
+          "pointer": "/scripts/check~1node~0",
+          "command": "preload/esm",
+          "via": "node-preload",
+          "occurrence": 2
+        },
+        {
+          "kind": "script",
+          "file": "package.json",
+          "pointer": "/scripts/check~1node~0",
+          "command": "preload/esm",
+          "via": "node-preload",
+          "occurrence": 3
+        }
+      ]
+    }
+  ],
+  "query": {
+    "packageName": "preload",
+    "known": true
+  }
+}

package/schemas/examples/explain-unknown.json

@@ -0,0 +1,53 @@
+{
+  "schemaVersion": 1,
+  "tool": {
+    "name": "depvitals",
+    "version": "0.4.0"
+  },
+  "mode": "explain",
+  "project": {
+    "root": "/example/project"
+  },
+  "scope": {
+    "sourceExtensions": [".cjs", ".cts", ".js", ".jsx", ".mjs", ".mts", ".ts", ".tsx"],
+    "excludedDirectories": [
+      ".cache",
+      ".git",
+      ".next",
+      ".nuxt",
+      ".turbo",
+      "build",
+      "coverage",
+      "dist",
+      "node_modules",
+      "out"
+    ],
+    "ignorePaths": [],
+    "ignoreDependencies": []
+  },
+  "findings": {
+    "unusedDependencies": [],
+    "unusedDevDependencies": [],
+    "missingDependencies": []
+  },
+  "counts": {
+    "unusedDependencies": 0,
+    "unusedDevDependencies": 0,
+    "missingDependencies": 0
+  },
+  "packages": [
+    {
+      "name": "absent",
+      "status": "unknown",
+      "declaredIn": [],
+      "excluded": false,
+      "underlyingFindings": [],
+      "findings": [],
+      "evidence": []
+    }
+  ],
+  "query": {
+    "packageName": "absent",
+    "known": false
+  }
+}

package/schemas/examples/scan-clean.json

@@ -0,0 +1,40 @@
+{
+  "schemaVersion": 1,
+  "tool": {
+    "name": "depvitals",
+    "version": "0.4.0"
+  },
+  "mode": "scan",
+  "project": {
+    "root": "/example/project"
+  },
+  "scope": {
+    "sourceExtensions": [".cjs", ".cts", ".js", ".jsx", ".mjs", ".mts", ".ts", ".tsx"],
+    "excludedDirectories": [
+      ".cache",
+      ".git",
+      ".next",
+      ".nuxt",
+      ".turbo",
+      "build",
+      "coverage",
+      "dist",
+      "node_modules",
+      "out"
+    ],
+    "ignorePaths": [],
+    "ignoreDependencies": []
+  },
+  "findings": {
+    "unusedDependencies": [],
+    "unusedDevDependencies": [],
+    "missingDependencies": []
+  },
+  "counts": {
+    "unusedDependencies": 0,
+    "unusedDevDependencies": 0,
+    "missingDependencies": 0
+  },
+  "packages": [],
+  "query": null
+}

package/schemas/examples/scan-findings.json

@@ -0,0 +1,80 @@
+{
+  "schemaVersion": 1,
+  "tool": {
+    "name": "depvitals",
+    "version": "0.4.0"
+  },
+  "mode": "scan",
+  "project": {
+    "root": "/example/project"
+  },
+  "scope": {
+    "sourceExtensions": [".cjs", ".cts", ".js", ".jsx", ".mjs", ".mts", ".ts", ".tsx"],
+    "excludedDirectories": [
+      ".cache",
+      ".git",
+      ".next",
+      ".nuxt",
+      ".turbo",
+      "build",
+      "coverage",
+      "dist",
+      "node_modules",
+      "out"
+    ],
+    "ignorePaths": [],
+    "ignoreDependencies": []
+  },
+  "findings": {
+    "unusedDependencies": ["unused"],
+    "unusedDevDependencies": ["unused-tool"],
+    "missingDependencies": ["missing"]
+  },
+  "counts": {
+    "unusedDependencies": 1,
+    "unusedDevDependencies": 1,
+    "missingDependencies": 1
+  },
+  "packages": [
+    {
+      "name": "missing",
+      "status": "missing",
+      "declaredIn": [],
+      "excluded": false,
+      "underlyingFindings": ["missingDependencies"],
+      "findings": ["missingDependencies"],
+      "evidence": [
+        {
+          "kind": "source",
+          "file": "src/index.ts",
+          "reference": "import",
+          "specifier": "missing",
+          "position": {
+            "offset": 17,
+            "line": 1,
+            "column": 18
+          }
+        }
+      ]
+    },
+    {
+      "name": "unused",
+      "status": "unused",
+      "declaredIn": ["dependencies"],
+      "excluded": false,
+      "underlyingFindings": ["unusedDependencies"],
+      "findings": ["unusedDependencies"],
+      "evidence": []
+    },
+    {
+      "name": "unused-tool",
+      "status": "unused",
+      "declaredIn": ["devDependencies"],
+      "excluded": false,
+      "underlyingFindings": ["unusedDevDependencies"],
+      "findings": ["unusedDevDependencies"],
+      "evidence": []
+    }
+  ],
+  "query": null
+}