depvitals 0.2.0 → 0.4.0

package/README.md

@@ -1,70 +1,135 @@
 # DepVitals
 
-DepVitals finds unused and undeclared npm dependencies in single-package JavaScript and TypeScript projects. It is a zero-config Node.js CLI with a custom static scanner and no runtime dependencies.
+[![npm version](https://img.shields.io/npm/v/depvitals)](https://www.npmjs.com/package/depvitals)
+[![Runtime dependencies: 0](https://img.shields.io/badge/runtime_dependencies-0-brightgreen)](https://github.com/MatiasRicardi/depvitals/blob/main/package.json)
+[![CI](https://github.com/MatiasRicardi/depvitals/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/MatiasRicardi/depvitals/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/MatiasRicardi/depvitals/graph/badge.svg?branch=main)](https://codecov.io/gh/MatiasRicardi/depvitals)
+[![CodeQL](https://github.com/MatiasRicardi/depvitals/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/MatiasRicardi/depvitals/actions/workflows/codeql.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/MatiasRicardi/depvitals/blob/main/LICENSE)
 
-[Depcheck](https://github.com/depcheck/depcheck)-inspired, DepVitals focuses on dependency declarations and supported usage evidence. Use it to review dependencies during maintenance or before a release; review each finding before changing your manifest.
+DepVitals is a lightweight, [Depcheck](https://github.com/depcheck/depcheck)-inspired **npm dependency analyzer for Node.js, JavaScript and TypeScript projects**. It finds **unused dependencies, unused devDependencies and missing (undeclared) dependencies** using a custom static scanner with **zero runtime dependencies**.
 
-Documentation on `main` can be ahead of the [published npm package](https://www.npmjs.com/package/depvitals). Check the [changelog](https://github.com/MatiasRicardi/depvitals/blob/main/CHANGELOG.md) for release-specific behavior.
+Designed for fast, zero-config dependency checks during development, maintenance and CI, its CLI can also be used in scripts and AI coding-agent workflows. It analyzes one project root at a time; review findings before changing `package.json`.
+
+## What's new in v0.4.0
+
+Export a versioned JSON report, explain why a package was used or flagged, and run a
+[version-pinned CI check](#ci-with-a-fixed-version) that preserves reports and diagnostics.
+Explanations point to supported source, script and configuration evidence. Supported explicit
+Node preloads now count as script usage for declared packages. See the
+[v0.4.0 release notes](https://github.com/MatiasRicardi/depvitals/blob/main/docs/releases/v0.4.0.md)
+for compatibility details and remaining limits.
 
 ## Quick start
 
-Requires **Node.js 22.13.0 or newer**. From a directory containing `package.json`:
+Requires **Node.js 22.13.0 or newer**. Scan the current directory containing `package.json`, or pass a project path:
 
 ```sh
 npx depvitals
+npx depvitals ./path/to/project
 ```
 
-Scan an explicit project path, or request standalone help/version:
+### Install globally
 
 ```sh
-npx depvitals ./path/to/project
-npx depvitals --help
-npx depvitals --version
+npm i -g depvitals
+depvitals
+depvitals ./path/to/project
 ```
 
-These commands run the npm release. For development-branch behavior, build and run the local CLI as described in [Contributing](https://github.com/MatiasRicardi/depvitals/blob/main/CONTRIBUTING.md).
+Use `depvitals --help` or `depvitals --version` for standalone help/version; the same flags work with `npx depvitals`.
+
+These commands use the npm release. Documentation on `main` can describe unreleased changes; see the [changelog](https://github.com/MatiasRicardi/depvitals/blob/main/CHANGELOG.md). To try the development checkout, [build and run the local CLI](https://github.com/MatiasRicardi/depvitals/blob/main/CONTRIBUTING.md#local-setup).
+
+## Results
 
-## Understand the results
+| Finding                | Meaning                                                                                |
+| ---------------------- | -------------------------------------------------------------------------------------- |
+| Unused dependencies    | Declared in `dependencies`, without supported usage evidence.                          |
+| Unused devDependencies | The same check for `devDependencies`.                                                  |
+| Missing dependencies   | Referenced by supported source imports/exports/requires, but undeclared in all groups. |
 
-| Finding                | Meaning                                                                                                      |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
-| Unused dependencies    | Entries in `dependencies` with no supported source, script or configuration usage evidence.                  |
-| Unused devDependencies | The same check for `devDependencies`.                                                                        |
-| Missing dependencies   | Packages referenced by supported source imports/requires but absent from every dependency declaration group. |
+**Missing means undeclared.** DepVitals checks the manifest and supported evidence. Review each unused finding before editing your manifest. Peer and optional dependencies suppress missing findings and are never reported unused.
 
-**Missing means undeclared, not uninstalled.** DepVitals does not inspect `node_modules`. **Unused is not proof of safe removal**: indirect or unsupported usage may exist. Peer and optional declarations suppress missing findings and are never reported as unused.
+Reports use stdout; operational errors use stderr without a partial report. Exit **0** means clean/help/version; **1** means findings/errors. An optional update notice can use stderr without changing the status.
 
-A scan can report:
+## JSON reports and package explanations
+
+These examples require **v0.4.0 or newer**. To try them from a checkout, use
+`node /path/to/depvitals/dist/cli/index.js` in place of `depvitals` after
+[building the development checkout](https://github.com/MatiasRicardi/depvitals/blob/main/CONTRIBUTING.md#local-setup).
+
+For example, suppose `./project` declares `unused` as a dependency and `unused-tool` as a
+devDependency, and `src/index.ts` contains `import item from 'missing';`.
+
+```sh
+depvitals ./project
+```
 
 ```text
 DepVitals
 
 Unused dependencies (1)
-  lodash
+  unused
 
 Unused devDependencies (1)
-  echo-only
+  unused-tool
 
 Missing dependencies (1)
-  undeclared-pkg
+  missing
 ```
 
-Reports go to stdout; operational errors go to stderr. Exit status is **0** for a clean scan, help or version, and **1** for findings or errors. An eligible update notice may additionally use stderr without changing the status.
+Run these commands from outside the selected project.
 
-## Coverage and fit
+```sh
+depvitals ./project --format json > depvitals-report.json
+depvitals ./project --explain missing
+depvitals --format json --explain missing ./project
+```
+
+1. Start with a full scan. This example reports findings and returns exit 1, including when stdout
+   is redirected to JSON.
+2. Explain the package and check its evidence. Here `missing` is undeclared and its explanation
+   points to the import in `src/index.ts:1:18`. Check which package owns the file and whether the
+   import belongs in that project.
+3. For an unused finding, review actual uses and test the project before changing the manifest.
+   Use an exclusion only to record a deliberate scope or reporting decision.
 
-DepVitals recognizes literal ESM/CommonJS imports, exports and requires in JavaScript, TypeScript, JSX/TSX and declaration files. It normalizes scoped/subpath imports and excludes Node builtins and internal paths.
+An explanation reports one exact package. Its exit status follows that package's result. Use a full
+scan to enforce a project-wide check. The v0.4.0 [report schema and examples](https://github.com/MatiasRicardi/depvitals/blob/main/schemas/README.md)
+are shipped in the npm package under `schemas/`. See the [CLI and report contract](https://github.com/MatiasRicardi/depvitals/blob/main/docs/reference.md#cli-and-json-reports).
 
-Supported `package.json` commands and bounded ESLint/Jest configuration hints can prevent unused findings for declared packages. Only source evidence creates missing findings. See the [technical reference](https://github.com/MatiasRicardi/depvitals/blob/main/docs/reference.md) for supported patterns, precedence and exclusions.
+## CI with a fixed version
 
-## Limits and update check
+Install v0.4.0 from npm as an exact development dependency. If you are testing a candidate before
+publication, use the local tarball procedure in the CI recipe below.
+
+```sh
+npm install --save-dev --save-exact depvitals@0.4.0
+```
+
+Commit the generated lockfile and use `"check:dependencies": "depvitals --format json"` in the
+manifest's `scripts`. The [tested CI recipe](https://github.com/MatiasRicardi/depvitals/blob/main/docs/examples/ci/README.md)
+captures the installed executable's report, diagnostics and status. It preserves those artifacts
+on failure.
+
+## Optional configuration
+
+Requires DepVitals **0.3.0 or newer**. Create `depvitals.config.json` at the scanned project root:
+
+```json
+{
+  "ignorePaths": ["examples", "src/generated"],
+  "ignoreDependencies": ["some-adapter"]
+}
+```
 
-Analysis covers one project root, without workspace aggregation, alias/tsconfig resolution or blanket `@types` inference. The scanner is not a full compiler or resolver. Dynamic references can be missed; generated/vendor directories are excluded using fixed rules. There is no JSON output, public analyzer API, per-package explanation or automatic fix.
+`ignorePaths` excludes literal source paths/subtrees; `ignoreDependencies` hides exact package names from findings. No globs. Exclusions narrow what a clean report means; excluding the only source reference can make a dependency unused. See the [configuration reference](https://github.com/MatiasRicardi/depvitals/blob/main/docs/reference.md#optional-project-configuration) for validation and precedence.
 
-Core analysis is offline and never executes or modifies the analyzed project. After a completed interactive scan, an optional, bounded update check can request public metadata for **DepVitals itself** and cache it outside the project for about 24 hours. It uploads no source or dependency list and adds no telemetry. CI, non-TTY, help/version and failed scans skip the check. Set `DEPVITALS_NO_UPDATE_CHECK=1` to disable it; the [reference](https://github.com/MatiasRicardi/depvitals/blob/main/docs/reference.md#update-notice-and-privacy) shows POSIX and PowerShell examples.
+## Scope and privacy
 
-## More
+Scans cover JS/TS, JSX/TSX and declaration files, literal ESM/CommonJS references, supported script commands and bounded ESLint/Jest hints. Only source evidence creates missing findings. There is no workspace aggregation, alias/tsconfig resolution, blanket `@types` inference or automatic fix; see [supported patterns and limits](https://github.com/MatiasRicardi/depvitals/blob/main/docs/reference.md).
 
-[Technical reference](https://github.com/MatiasRicardi/depvitals/blob/main/docs/reference.md) · [Contributing](https://github.com/MatiasRicardi/depvitals/blob/main/CONTRIBUTING.md) · [Changelog](https://github.com/MatiasRicardi/depvitals/blob/main/CHANGELOG.md) · [npm](https://www.npmjs.com/package/depvitals) · [Repository](https://github.com/MatiasRicardi/depvitals)
+Core analysis is offline and never executes or modifies the project or inspects `node_modules`. After completed interactive scans, an optional update check requests public metadata for **DepVitals itself**, caches it outside the project and uploads no project data. CI, non-TTY, help/version and failed scans skip it. In v0.4.0, JSON scans and all explanations also skip it before any cache or network access. Set `DEPVITALS_NO_UPDATE_CHECK=1` to disable it; see [privacy and shell examples](https://github.com/MatiasRicardi/depvitals/blob/main/docs/reference.md#update-notice-and-privacy).
 
-[MIT license](https://github.com/MatiasRicardi/depvitals/blob/main/LICENSE).
+[Technical reference](https://github.com/MatiasRicardi/depvitals/blob/main/docs/reference.md) · [Contributing](https://github.com/MatiasRicardi/depvitals/blob/main/CONTRIBUTING.md) · [Changelog](https://github.com/MatiasRicardi/depvitals/blob/main/CHANGELOG.md) · [MIT license](https://github.com/MatiasRicardi/depvitals/blob/main/LICENSE)

package/dist/cli/entry.js

@@ -56,10 +56,17 @@ export async function runCliEntry(args, options) {
  * stand on their own. An unexpected type is discarded rather than printed.
  */
 async function collectNotice(args, result, options) {
+    const command = parseCliArgs(args, options.cwd);
+    if (command.kind !== 'scan' ||
+        command.format === 'json' ||
+        command.explain !== undefined ||
+        result.stdout.length === 0 ||
+        result.stderr.length > 0)
+        return undefined;
     try {
         const collect = options.updateNotice ?? collectUpdateNotice;
         const notice = await collect({
-            commandKind: commandKindOf(args, options.cwd, result),
+            commandKind: 'scan',
             currentVersion: options.version,
             env: options.env,
             stdoutTTY: options.stdout.isTTY === true,
@@ -72,24 +79,4 @@ async function collectNotice(args, result, options) {
         return undefined;
     }
 }
-/**
- * Classify the invocation in the vocabulary the eligibility predicate expects.
- *
- * The argument parser is the single source of truth for `help`, `version` and usage errors, so it is
- * consulted again here (a pure, deterministic function of the same arguments and the same working
- * directory) instead of widening {@link CliResult}, whose three keys are pinned by the contract gate.
- * A parsed `scan` is then split by what the scan produced: {@link runCli} renders a report whenever
- * the scan completed - clean or with findings - and leaves stdout empty for an operational failure,
- * so an empty report means the scan never finished and nothing may be suggested to the user.
- *
- * Only the literal kind crosses the boundary; the parsed project path stays here and is never passed
- * into notifier code.
- */
-function commandKindOf(args, cwd, result) {
-    const command = parseCliArgs(args, cwd);
-    if (command.kind !== 'scan') {
-        return command.kind;
-    }
-    return result.stdout.length === 0 ? 'scan-failure' : 'scan';
-}
 //# sourceMappingURL=entry.js.map

package/dist/cli/entry.js.map

@@ -1 +1 @@
-{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../src/cli/entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EACL,mBAAmB,GAGpB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAmC,MAAM,EAAE,MAAM,aAAa,CAAC;AA2BtE;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAuB,EACvB,OAAwB;IAExB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAElF,sEAAsE;IACtE,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACtC,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAE1D,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO,MAAM,CAAC,QAAQ,CAAC;AACzB,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,aAAa,CAC1B,IAAuB,EACvB,MAAiB,EACjB,OAAwB;IAExB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,OAAO,CAAC,YAAY,IAAI,mBAAmB,CAAC;QAE5D,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC;YAC3B,WAAW,EAAE,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC;YACrD,cAAc,EAAE,OAAO,CAAC,OAAO;YAC/B,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI;YACxC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI;SACzC,CAAC,CAAC;QAEH,OAAO,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,+DAA+D;QAC/D,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAS,aAAa,CACpB,IAAuB,EACvB,GAAW,EACX,MAAiB;IAEjB,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAExC,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC5B,OAAO,OAAO,CAAC,IAAI,CAAC;IACtB,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC;AAC9D,CAAC"}
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../src/cli/entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EACL,mBAAmB,GAGpB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAmC,MAAM,EAAE,MAAM,aAAa,CAAC;AA2BtE;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAuB,EACvB,OAAwB;IAExB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAElF,sEAAsE;IACtE,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACtC,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAE1D,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO,MAAM,CAAC,QAAQ,CAAC;AACzB,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,aAAa,CAC1B,IAAuB,EACvB,MAAiB,EACjB,OAAwB;IAExB,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IAChD,IACE,OAAO,CAAC,IAAI,KAAK,MAAM;QACvB,OAAO,CAAC,MAAM,KAAK,MAAM;QACzB,OAAO,CAAC,OAAO,KAAK,SAAS;QAC7B,MAAM,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;QAC1B,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;QAExB,OAAO,SAAS,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,OAAO,CAAC,YAAY,IAAI,mBAAmB,CAAC;QAE5D,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC;YAC3B,WAAW,EAAE,MAAM;YACnB,cAAc,EAAE,OAAO,CAAC,OAAO;YAC/B,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI;YACxC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI;SACzC,CAAC,CAAC;QAEH,OAAO,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,+DAA+D;QAC/D,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/cli/parseCliArgs.d.ts

@@ -1,5 +1,5 @@
 /**
- * Pure, deterministic argument parsing for the `v0.1.0` CLI.
+ * Pure, deterministic CLI argument parsing.
  *
  * This module only validates the argument shape and resolves the selected project path. It never
  * touches the filesystem, never calls the analyzer, and never accesses `process`, so the parsing
@@ -9,7 +9,8 @@
  * - no arguments            -> scan the injected `cwd`
  * - exactly one positional  -> scan the resolved project directory
  * - exactly one meta flag   -> help or version (exit 0, no scan)
- * - anything else           -> a deterministic error message
+ * - separated format/explain options may surround the single project path
+ * - malformed or unsupported shapes produce a deterministic error message
  *
  * `--help`/`-h`/`--version`/`-v` must stay standalone: combining them with any other token, or
  * combining them with each other, is rejected rather than given precedence.
@@ -22,6 +23,8 @@ export type ParsedCommand = {
 } | {
     kind: 'scan';
     projectPath: string;
+    format?: 'terminal' | 'json';
+    explain?: string;
 } | {
     kind: 'error';
     message: string;

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

@@ -1 +1 @@
-{"version":3,"file":"parseCliArgs.d.ts","sourceRoot":"","sources":["../../src/cli/parseCliArgs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,wDAAwD;AACxD,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAiBvC;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CA8ChF"}
+{"version":3,"file":"parseCliArgs.d.ts","sourceRoot":"","sources":["../../src/cli/parseCliArgs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,wDAAwD;AACxD,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACrF;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAiBvC;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CA+ChF"}

package/dist/cli/parseCliArgs.js

@@ -1,5 +1,5 @@
 /**
- * Pure, deterministic argument parsing for the `v0.1.0` CLI.
+ * Pure, deterministic CLI argument parsing.
  *
  * This module only validates the argument shape and resolves the selected project path. It never
  * touches the filesystem, never calls the analyzer, and never accesses `process`, so the parsing
@@ -9,12 +9,15 @@
  * - no arguments            -> scan the injected `cwd`
  * - exactly one positional  -> scan the resolved project directory
  * - exactly one meta flag   -> help or version (exit 0, no scan)
- * - anything else           -> a deterministic error message
+ * - separated format/explain options may surround the single project path
+ * - malformed or unsupported shapes produce a deterministic error message
  *
  * `--help`/`-h`/`--version`/`-v` must stay standalone: combining them with any other token, or
  * combining them with each other, is rejected rather than given precedence.
  */
 import { resolve } from 'node:path';
+import { isExactPackageRoot } from '../config/ignoreDependencies.js';
+import { escapeControlCharacters } from '../reporters/terminalReporter.js';
 /** Help/version flags that must be used alone. */
 const HELP_FLAGS = new Set(['--help', '-h']);
 /** Version flags that must be used alone. */
@@ -33,48 +36,60 @@ const TOO_MANY_ARGUMENTS = 'Too many arguments: expected at most one project pat
  *   the default project when no argument is supplied.
  */
 export function parseCliArgs(args, cwd) {
-    if (args.length === 0) {
-        return { kind: 'scan', projectPath: cwd };
-    }
-    if (args.length === 1) {
-        const arg = args[0];
-        // An empty string (or the unreachable undefined) is an explicit, invalid positional: it must
-        // not silently become `cwd`.
-        if (arg === undefined || arg === '') {
-            return { kind: 'error', message: INVALID_EMPTY_PROJECT_PATH };
-        }
-        if (HELP_FLAGS.has(arg)) {
-            return { kind: 'help' };
-        }
-        if (VERSION_FLAGS.has(arg)) {
-            return { kind: 'version' };
-        }
-        // Anything else that is not an option is treated as a project path.
-        if (!arg.startsWith('-')) {
-            return { kind: 'scan', projectPath: resolve(cwd, arg) };
-        }
-        return { kind: 'error', message: unknownOptionMessage(arg) };
-    }
-    // Two or more tokens: help/version must remain standalone, so any meta flag combined with
-    // additional tokens (including other meta flags) is rejected as used alone.
+    if (args.length === 1 && HELP_FLAGS.has(args[0] ?? ''))
+        return { kind: 'help' };
+    if (args.length === 1 && VERSION_FLAGS.has(args[0] ?? ''))
+        return { kind: 'version' };
     const metaFlag = args.find((arg) => HELP_FLAGS.has(arg) || VERSION_FLAGS.has(arg));
-    if (metaFlag !== undefined) {
+    if (metaFlag !== undefined)
         return { kind: 'error', message: metaFlagMustBeUsedAlone(metaFlag) };
+    let format;
+    let explain;
+    const paths = [];
+    const error = (body) => ({ kind: 'error', message: body + '\n' + HINT });
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index] ?? '';
+        if (arg === '--format' || arg === '--explain') {
+            if ((arg === '--format' && format !== undefined) ||
+                (arg === '--explain' && explain !== undefined)) {
+                return error(`Option ${arg} may be specified only once.`);
+            }
+            const value = args[index + 1];
+            if (value === undefined || value === '' || value.startsWith('-'))
+                return error(`Option ${arg} requires a value.`);
+            if (arg === '--format') {
+                if (value !== 'terminal' && value !== 'json')
+                    return error(`Invalid value for --format: ${escapeControlCharacters(value)}. Expected terminal or json.`);
+                format = value;
+            }
+            else {
+                if (!isExactPackageRoot(value))
+                    return error('Invalid value for --explain: expected an exact package root (name or @scope/name), at most 214 characters.');
+                explain = value;
+            }
+            index += 1;
+        }
+        else if (arg.startsWith('-'))
+            return { kind: 'error', message: unknownOptionMessage(arg) };
+        else
+            paths.push(arg);
     }
-    // No meta flag: reject unknown options before falling back to the positional rule, so an unknown
-    // flag is reported even when it appears alongside a positional path.
-    const unknownOption = args.find((arg) => arg.startsWith('-'));
-    if (unknownOption !== undefined) {
-        return { kind: 'error', message: unknownOptionMessage(unknownOption) };
-    }
-    // Remaining tokens are all positionals, which is more than one.
-    return { kind: 'error', message: TOO_MANY_ARGUMENTS };
+    if (paths.length > 1)
+        return { kind: 'error', message: TOO_MANY_ARGUMENTS };
+    if (paths[0] === '')
+        return { kind: 'error', message: INVALID_EMPTY_PROJECT_PATH };
+    return {
+        kind: 'scan',
+        projectPath: paths[0] === undefined ? cwd : resolve(cwd, paths[0]),
+        ...(format === undefined ? {} : { format }),
+        ...(explain === undefined ? {} : { explain }),
+    };
 }
 /**
  * The error message for an unrecognized option.
  */
 function unknownOptionMessage(option) {
-    return `Unknown option: ${option}\n${HINT}`;
+    return `Unknown option: ${escapeControlCharacters(option)}\n${HINT}`;
 }
 /**
  * The error message when a meta flag is combined with additional tokens.

package/dist/cli/parseCliArgs.js.map

@@ -1 +1 @@
-{"version":3,"file":"parseCliArgs.js","sourceRoot":"","sources":["../../src/cli/parseCliArgs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"parseCliArgs.js","sourceRoot":"","sources":["../../src/cli/parseCliArgs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAS3E,kDAAkD;AAClD,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;AAE7C,6CAA6C;AAC7C,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC;AAEnD,8FAA8F;AAC9F,MAAM,IAAI,GAAG,gDAAgD,CAAC;AAE9D,yEAAyE;AACzE,MAAM,0BAA0B,GAAG,yDAAyD,GAAG,IAAI,CAAC;AAEpG,qEAAqE;AACrE,MAAM,kBAAkB,GAAG,0DAA0D,GAAG,IAAI,CAAC;AAE7F;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAuB,EAAE,GAAW;IAC/D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAChF,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IACtF,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IACnF,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,uBAAuB,CAAC,QAAQ,CAAC,EAAE,CAAC;IAEjG,IAAI,MAAuC,CAAC;IAC5C,IAAI,OAA2B,CAAC;IAChC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAG,CAAC,IAAY,EAAiB,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC,CAAC;IAChG,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACpD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAC9B,IAAI,GAAG,KAAK,UAAU,IAAI,GAAG,KAAK,WAAW,EAAE,CAAC;YAC9C,IACE,CAAC,GAAG,KAAK,UAAU,IAAI,MAAM,KAAK,SAAS,CAAC;gBAC5C,CAAC,GAAG,KAAK,WAAW,IAAI,OAAO,KAAK,SAAS,CAAC,EAC9C,CAAC;gBACD,OAAO,KAAK,CAAC,UAAU,GAAG,8BAA8B,CAAC,CAAC;YAC5D,CAAC;YACD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;YAC9B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;gBAC9D,OAAO,KAAK,CAAC,UAAU,GAAG,oBAAoB,CAAC,CAAC;YAClD,IAAI,GAAG,KAAK,UAAU,EAAE,CAAC;gBACvB,IAAI,KAAK,KAAK,UAAU,IAAI,KAAK,KAAK,MAAM;oBAC1C,OAAO,KAAK,CACV,+BAA+B,uBAAuB,CAAC,KAAK,CAAC,8BAA8B,CAC5F,CAAC;gBACJ,MAAM,GAAG,KAAK,CAAC;YACjB,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC;oBAC5B,OAAO,KAAK,CACV,4GAA4G,CAC7G,CAAC;gBACJ,OAAO,GAAG,KAAK,CAAC;YAClB,CAAC;YACD,KAAK,IAAI,CAAC,CAAC;QACb,CAAC;aAAM,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,oBAAoB,CAAC,GAAG,CAAC,EAAE,CAAC;;YACxF,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvB,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC5E,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,0BAA0B,EAAE,CAAC;IACnF,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;QAClE,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;QAC3C,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;KAC9C,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,oBAAoB,CAAC,MAAc;IAC1C,OAAO,mBAAmB,uBAAuB,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;AACvE,CAAC;AAED;;GAEG;AACH,SAAS,uBAAuB,CAAC,IAAY;IAC3C,OAAO,UAAU,IAAI,yBAAyB,IAAI,EAAE,CAAC;AACvD,CAAC"}

package/dist/cli/runCli.d.ts

@@ -1,5 +1,5 @@
 /**
- * Asynchronous CLI orchestration for `v0.1.0`.
+ * Asynchronous CLI orchestration.
  *
  * `runCli` turns parsed arguments into a plain {@link CliResult}. It performs no process I/O of its
  * own: it never writes to stdout/stderr and never touches `process`. The thin adapter in
@@ -7,10 +7,9 @@
  *
  * 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;
+ * - prepare one validated root/policy/detector context for the analyzer, which alone owns findings;
+ * - run one full detailed dependency scan;
+ * - render the selected terminal or JSON scan/query projection;
  * - decide the scan exit code from `hasDependencyIssues`, not from the report string;
  * - convert operational failures into a concise CLI error result.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"runCli.d.ts","sourceRoot":"","sources":["../../src/cli/runCli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAYH;;;;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;;;;;;;;;;;;;;;;;GAiBG;AAsBH;;;;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;AAoBF;;;;;;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

@@ -1,5 +1,5 @@
 /**
- * Asynchronous CLI orchestration for `v0.1.0`.
+ * Asynchronous CLI orchestration.
  *
  * `runCli` turns parsed arguments into a plain {@link CliResult}. It performs no process I/O of its
  * own: it never writes to stdout/stderr and never touches `process`. The thin adapter in
@@ -7,23 +7,23 @@
  *
  * 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;
+ * - prepare one validated root/policy/detector context for the analyzer, which alone owns findings;
+ * - run one full detailed dependency scan;
+ * - render the selected terminal or JSON scan/query projection;
  * - decide the scan exit code from `hasDependencyIssues`, not from the report string;
  * - convert operational failures into a concise CLI error result.
  *
  * It deliberately does not implement any scanning or dependency-analysis logic: that stays in
  * `src/core`, and the reporter stays in `src/reporters`.
  */
-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 { ProjectConfigError } from '../config/readProjectConfig.js';
+import { AnalysisError, analyzeProjectDetailed, projectAnalysisResult, projectPackageExplanation, } from '../core/analyzeProject.js';
+import { createScanContext } from '../core/scanContext.js';
+import { EslintRcJsonError } from '../detectors/eslintRcJsonConfig.js';
+import { formatTerminalExplanation, formatTerminalReport, hasDependencyIssues, } from '../reporters/terminalReporter.js';
 import { ProjectManifestError } from '../scanner/projectManifest.js';
 import { SourceFilesError } from '../scanner/sourceFiles.js';
+import { formatJsonReport } from '../reporters/jsonReporter.js';
 import { parseCliArgs } from './parseCliArgs.js';
 const HELP_MESSAGE = [
     'DepVitals',
@@ -31,12 +31,14 @@ const HELP_MESSAGE = [
     'A simple, lightweight dependency health checker for Node.js projects.',
     '',
     'Usage:',
-    '  depvitals [project]',
+    '  depvitals [project] [--format terminal|json] [--explain <package>]',
     '',
     'Arguments:',
     '  project          Project directory to analyze (default: current directory)',
     '',
     'Options:',
+    '  --format <format>    Output format: terminal or json (default: terminal)',
+    '  --explain <package>  Explain one exact package root (default: full scan)',
     '  -h, --help       Show help',
     '  -v, --version    Show version',
 ].join('\n');
@@ -57,7 +59,7 @@ export async function runCli(args, options) {
         case 'error':
             return { exitCode: 1, stdout: '', stderr: `${command.message}\n` };
         case 'scan':
-            return await runScan(command.projectPath);
+            return await runScan(command, options.version);
     }
 }
 /**
@@ -67,54 +69,47 @@ export async function runCli(args, options) {
  * empty stdout). Any other thrown value is surfaced through a generic fallback message so the CLI
  * never leaks internal error objects and never leaves an unhandled rejection.
  */
-async function runScan(projectPath) {
-    let result;
+async function runScan(command, version) {
+    const projectPath = command.projectPath;
     try {
-        // 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, { configUsedNames });
-    }
-    catch (error) {
-        if (isOperationalError(error)) {
-            return { exitCode: 1, stdout: '', stderr: `${error.message}\n` };
+        const context = await createScanContext(projectPath);
+        const detailed = await analyzeProjectDetailed(context);
+        if (command.explain !== undefined) {
+            const result = projectPackageExplanation(detailed, command.explain);
+            return {
+                exitCode: result.exitCode,
+                stdout: command.format === 'json'
+                    ? formatJsonReport({ mode: 'explain', result }, version)
+                    : formatTerminalExplanation(result),
+                stderr: '',
+            };
         }
+        const result = projectAnalysisResult(detailed);
         return {
-            exitCode: 1,
-            stdout: '',
-            stderr: `${unexpectedErrorMessage(projectPath, error)}\n`,
+            exitCode: hasDependencyIssues(result) ? 1 : 0,
+            stdout: command.format === 'json'
+                ? formatJsonReport({ mode: 'scan', result: detailed }, version)
+                : formatTerminalReport(result),
+            stderr: '',
         };
     }
-    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]);
+    catch (error) {
+        if (isOperationalError(error))
+            return { exitCode: 1, stdout: '', stderr: `${error.message}\n` };
+        return { exitCode: 1, stdout: '', stderr: `${unexpectedErrorMessage(projectPath, error)}\n` };
+    }
 }
 /**
  * Whether the thrown value is a scanner error the CLI knows how to render. Only the existing typed
- * error classes plus the unusable-`.eslintrc.json` error count; everything else is treated as an
+ * 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 EslintRcJsonError);
+        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,9 @@
+/** Shared exact-root grammar for dependency exclusions and explanation input; no normalization. */
+export declare function isExactPackageRoot(name: string): boolean;
+/**
+ * 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,mGAAmG;AACnG,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,UAAU,EAAE,MAAM,GACjB,SAAS,MAAM,EAAE,CAUnB"}