depvitals 0.1.2 → 0.3.0

package/README.md

@@ -1,88 +1,66 @@
 # DepVitals
 
-> A simple, lightweight dependency health checker for Node.js projects.
+[![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)
 
-DepVitals scans a Node.js project to identify declared dependencies that appear unused and imported packages that are not declared in `package.json`.
+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**.
 
-Inspired by [depcheck](https://github.com/depcheck/depcheck), DepVitals stays deliberately small. It performs lightweight static analysis locally, without making network requests, modifying the analyzed project, or executing its code.
+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`.
 
-## Usage
+## Quick start
 
-```bash
+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
-npx depvitals --help
-npx depvitals --version
 ```
 
-Run it from a project directory to scan the current directory, or provide a path to analyze another project.
-
-**Requirements:** Node.js `>=22.13.0`.
-
-**Version note:** Dependency scanning was introduced in v0.1.0, and v0.1.2 expanded the script executable allowlist. The earlier v0.0.1 release contains only the initial CLI bootstrap.
-
-**Exit status:**
+### Install globally
 
-```text
-0 = successful clean scan, help, or version
-1 = dependency findings or an operational/CLI error
+```sh
+npm i -g depvitals
+depvitals
+depvitals ./path/to/project
 ```
 
-Scan results, including dependency findings, are printed to `stdout`. Argument errors and operational errors are printed to `stderr`.
+Use `depvitals --help` or `depvitals --version` for standalone help/version; the same flags work with `npx depvitals`.
 
-## What it detects
+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).
 
-- **Unused dependencies** — packages declared in `dependencies` for which no supported source file or `package.json` script provides usage evidence.
-- **Unused devDependencies** — the same analysis applied to packages declared in `devDependencies`.
-- **Missing dependencies** — external packages referenced by supported source imports but not declared in the project's `package.json`.
+## Results
 
-DepVitals does not inspect `node_modules`, so **"missing" means "not declared", not "not installed"**. An installed but undeclared package can still be reported as missing, and package installation state is never validated.
+| 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. |
 
-Similarly, a dependency is reported as unused only when no supported usage evidence is found. Indirect or unsupported usage may still exist.
+**Missing means undeclared, not uninstalled. Unused is not proof of safe removal.** Review findings before editing your manifest. Peer and optional dependencies suppress missing findings and are never reported unused.
 
-`peerDependencies` and `optionalDependencies` are considered when checking whether imported packages are declared, but 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.
 
-**Example output:**
+## Optional configuration
 
-```text
-DepVitals
+Requires DepVitals **0.3.0 or newer**. Create `depvitals.config.json` at the scanned project root:
 
-Unused dependencies (2)
-  dotenv
-  lodash
-
-Unused devDependencies (1)
-  eslint
-
-Missing dependencies (1)
-  zod
+```json
+{
+  "ignorePaths": ["examples", "src/generated"],
+  "ignoreDependencies": ["some-adapter"]
+}
 ```
 
-## Supported in v0.1.0
-
-- **JavaScript and TypeScript:** `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`, `.mts`, `.cts`, including `.d.ts`-style declaration files.
-- **Static ESM imports and exports:** regular imports, side-effect imports, `import type`, and `export ... from`.
-- **Literal dynamic imports:** expressions such as `import("express")`.
-- **Literal CommonJS requires:** expressions such as `require("express")`.
-- **Basic `package.json` script awareness:** a declared dependency invoked by a supported script command counts as used, for example `eslint` in `"lint": "eslint ."`. Script usage can prevent unused findings but does not generate missing-dependency findings.
-- **Known executable names:** since v0.1.2, a static allowlist of 60 known executable commands resolves to 46 declared packages, so a real CLI executable credits the package that declares it, for example `tsserver` → `typescript`, `ng` → `@angular/cli`, `vue-cli-service` → `@vue/cli-service`, `depcruise` → `dependency-cruiser`, `sls` → `serverless`, and `gulp` → `gulp-cli`. Each alias was verified against published `bin` metadata beforehand: nothing is auto-discovered from `bin` fields or from `node_modules`. 32 of them are collision-sensitive, meaning a same-named declared package wins and the mapped provider gets no evidence.
-- **Node.js builtins:** built-in modules, with or without the `node:` prefix, are excluded from missing-dependency findings.
-- **Scoped packages and subpaths:** package specifiers are normalized to their package root. For example, `@scope/ui/button` counts as `@scope/ui`, and `lodash/chunk` counts as `lodash`.
-- **Ignored directories:** generated and vendor trees are skipped, including `node_modules`, `dist`, `build`, `coverage`, `out`, `.next`, `.nuxt`, `.cache`, `.turbo`, and `.git`.
-- **Deterministic output:** findings are grouped into sections in a fixed order, with package names sorted alphabetically within each section.
-
-Detection uses a lightweight static lexical scanner rather than a full JavaScript/TypeScript parser. Comments, ordinary strings, template text, and regular expressions that merely resemble imports are not counted as dependency usage.
+`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.
 
-## Current limitations
+## Scope and privacy
 
-- **Single-project analysis:** only one `package.json` is analyzed. Workspaces, monorepos, and parent-manifest lookup are not supported.
-- **No configuration-aware resolution:** framework-specific configurations, plugins, TypeScript `paths`, and bundler aliases are not resolved.
-- **Static specifiers only:** non-literal dynamic `import()`, template-literal specifiers, `require.resolve()`, and property calls such as `obj.require()` are not recognized as usage evidence.
-- **Limited script detection:** script usage relies on supported command patterns, and only the executables in the static allowlist above are translated to their declaring package, and only when the executable appears in a supported direct command position. Every other executable name keeps exact-name matching, mappings are never applied to runner arguments such as `npx tsc` or `pnpm exec tsc`, and ambiguous provider families such as `tailwindcss`, `playwright`, and `webpack` are deliberately unmapped, so only an exactly declared same-name package is credited.
-- **Fixed directory exclusions:** source discovery uses the built-in ignored-directory list above. `.gitignore` and custom ignore rules are not interpreted.
-- **Conservative error handling:** unreadable source files or source content the lexical scanner cannot safely finish scanning, such as unterminated strings, comments, templates, or regular expressions, abort the scan rather than producing partial results.
-- **No remediation features yet:** automatic fixes, custom configuration files, and per-dependency explanations are not available.
+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, JSON output or automatic fix; see [supported patterns and limits](https://github.com/MatiasRicardi/depvitals/blob/main/docs/reference.md).
 
-## License
+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. 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
+[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.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Process-facing CLI orchestration (Step 67).
+ *
+ * `runCliEntry` is the layer between the pure {@link runCli} orchestration and the real process
+ * streams. It owns exactly three things:
+ *
+ * 1. render the deterministic result: stdout first, then stderr, byte for byte as `runCli` produced
+ *    them - the report and the operational diagnostics are untouched by this module;
+ * 2. run the *optional* update check **after** that output, and append its notice to stderr only;
+ * 3. hand back the original exit code.
+ *
+ * The ordering above is the contract: a scan always finishes printing before the notifier may write,
+ * and the notifier can never rewrite, delay or contradict that output. It also cannot change the exit
+ * status, because the returned code comes from `runCli` alone and the notice is only appended text.
+ *
+ * Nothing here reads `process`: the streams, the environment, the working directory and the notifier
+ * are all injected, so the sequencing is testable without spawning anything and without network
+ * access. The thin executable adapter in `index.ts` supplies the real process objects and assigns
+ * `process.exitCode` **after** this function resolves, which is what keeps the optional asynchronous
+ * work from being truncated (and `process.exit()` is never called at all).
+ *
+ * The command kind handed to the notifier is deliberately only a literal string: no project path,
+ * manifest content or dependency name ever crosses into notifier code.
+ */
+import { type UpdateNoticeCollector, type UpdateNoticeRequest } from './notifier/updateCheck.js';
+import { type CliOptions } from './runCli.js';
+/**
+ * The minimal stream view this layer needs: a writable text sink plus its interactivity flag.
+ * `process.stdout` and `process.stderr` satisfy it, and a test double satisfies it too, which keeps
+ * the TTY gate injectable without ever faking a real terminal.
+ */
+export type StreamWriter = {
+    readonly isTTY?: boolean | undefined;
+    write(chunk: string): unknown;
+};
+/** Everything the entry layer needs from the process, injected. */
+export type CliEntryOptions = CliOptions & {
+    /** The environment map used for the notifier eligibility gates, e.g. `process.env`. */
+    readonly env: UpdateNoticeRequest['env'];
+    /** The standard output stream. */
+    readonly stdout: StreamWriter;
+    /** The standard error stream. */
+    readonly stderr: StreamWriter;
+    /**
+     * Notifier seam. Defaults to the production {@link collectUpdateNotice}; tests inject a stub so
+     * they stay deterministic and offline while still asserting the real sequencing and channels.
+     */
+    readonly updateNotice?: UpdateNoticeCollector;
+};
+/**
+ * Render one CLI invocation and return the exit code the caller must assign to `process.exitCode`.
+ *
+ * @param args - The raw arguments after `node` and the script path.
+ * @param options - Version, working directory, environment, the two output streams and the
+ *   optional notifier seam.
+ * @returns The unchanged exit code of the scan: 0 for clean/help/version, 1 for findings/errors.
+ */
+export declare function runCliEntry(args: readonly string[], options: CliEntryOptions): Promise<number>;
+//# sourceMappingURL=entry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"entry.d.ts","sourceRoot":"","sources":["../../src/cli/entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,KAAK,UAAU,EAA0B,MAAM,aAAa,CAAC;AAEtE;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B,CAAC;AAEF,mEAAmE;AACnE,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG;IACzC,uFAAuF;IACvF,QAAQ,CAAC,GAAG,EAAE,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACzC,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,qBAAqB,CAAC;CAC/C,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,MAAM,CAAC,CAmBjB"}

package/dist/cli/entry.js

@@ -0,0 +1,95 @@
+/**
+ * Process-facing CLI orchestration (Step 67).
+ *
+ * `runCliEntry` is the layer between the pure {@link runCli} orchestration and the real process
+ * streams. It owns exactly three things:
+ *
+ * 1. render the deterministic result: stdout first, then stderr, byte for byte as `runCli` produced
+ *    them - the report and the operational diagnostics are untouched by this module;
+ * 2. run the *optional* update check **after** that output, and append its notice to stderr only;
+ * 3. hand back the original exit code.
+ *
+ * The ordering above is the contract: a scan always finishes printing before the notifier may write,
+ * and the notifier can never rewrite, delay or contradict that output. It also cannot change the exit
+ * status, because the returned code comes from `runCli` alone and the notice is only appended text.
+ *
+ * Nothing here reads `process`: the streams, the environment, the working directory and the notifier
+ * are all injected, so the sequencing is testable without spawning anything and without network
+ * access. The thin executable adapter in `index.ts` supplies the real process objects and assigns
+ * `process.exitCode` **after** this function resolves, which is what keeps the optional asynchronous
+ * work from being truncated (and `process.exit()` is never called at all).
+ *
+ * The command kind handed to the notifier is deliberately only a literal string: no project path,
+ * manifest content or dependency name ever crosses into notifier code.
+ */
+import { collectUpdateNotice, } from './notifier/updateCheck.js';
+import { parseCliArgs } from './parseCliArgs.js';
+import { runCli } from './runCli.js';
+/**
+ * Render one CLI invocation and return the exit code the caller must assign to `process.exitCode`.
+ *
+ * @param args - The raw arguments after `node` and the script path.
+ * @param options - Version, working directory, environment, the two output streams and the
+ *   optional notifier seam.
+ * @returns The unchanged exit code of the scan: 0 for clean/help/version, 1 for findings/errors.
+ */
+export async function runCliEntry(args, options) {
+    const result = await runCli(args, { version: options.version, cwd: options.cwd });
+    // The deterministic output goes out before anything optional happens.
+    if (result.stdout.length > 0) {
+        options.stdout.write(result.stdout);
+    }
+    if (result.stderr.length > 0) {
+        options.stderr.write(result.stderr);
+    }
+    const notice = await collectNotice(args, result, options);
+    if (notice !== undefined && notice.length > 0) {
+        options.stderr.write(notice);
+    }
+    return result.exitCode;
+}
+/**
+ * Ask the notifier for its notice, if this invocation has one.
+ *
+ * The call is wrapped so that a notifier failing in any way - a thrown error, a rejected promise, a
+ * malformed return value - behaves exactly like "no notice": the scan's own status and diagnostics
+ * stand on their own. An unexpected type is discarded rather than printed.
+ */
+async function collectNotice(args, result, options) {
+    try {
+        const collect = options.updateNotice ?? collectUpdateNotice;
+        const notice = await collect({
+            commandKind: commandKindOf(args, options.cwd, result),
+            currentVersion: options.version,
+            env: options.env,
+            stdoutTTY: options.stdout.isTTY === true,
+            stderrTTY: options.stderr.isTTY === true,
+        });
+        return typeof notice === 'string' ? notice : undefined;
+    }
+    catch {
+        // An optional notification never becomes a failure of its own.
+        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

@@ -0,0 +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"}

package/dist/cli/index.js

@@ -1,31 +1,27 @@
 #!/usr/bin/env node
 import { readFileSync } from 'node:fs';
-import { runCli } from './runCli.js';
+import { runCliEntry } from './entry.js';
 /**
- * Thin executable adapter for the `v0.1.0` CLI.
+ * Thin executable adapter for the CLI.
  *
  * Its only responsibilities are:
  * 1. resolve the package version from the single source of truth (`package.json`);
- * 2. collect `process.argv`, `process.cwd()` and the version;
- * 3. await the pure orchestration in `runCli`;
- * 4. render the returned stdout/stderr;
- * 5. assign `process.exitCode` (never call `process.exit()`).
+ * 2. hand `process.argv`, `process.cwd()`, `process.env` and the two output streams to
+ *    `runCliEntry`, which prints the report, then optionally appends the update notice to stderr;
+ * 3. assign `process.exitCode` from the returned status (never call `process.exit()`, so the
+ *    optional update check is never truncated and can never change the status).
  *
- * All argument handling, scanning orchestration and error mapping live in `runCli`, so this file
- * only wires process I/O to that orchestration. The relative path works both from the TypeScript
- * source (`src/cli/index.ts`) and from the built output (`dist/cli/index.js`), because both resolve
- * to the repository root `package.json`.
+ * All argument handling, scanning orchestration, error mapping and the notifier sequencing live in
+ * `runCli`/`runCliEntry`, so this file only wires process objects to them. The relative path works
+ * both from the TypeScript source (`src/cli/index.ts`) and from the built output
+ * (`dist/cli/index.js`), because both resolve to the repository root `package.json`.
  */
 const version = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
-const result = await runCli(process.argv.slice(2), {
+process.exitCode = await runCliEntry(process.argv.slice(2), {
     version: version.version,
     cwd: process.cwd(),
+    env: process.env,
+    stdout: process.stdout,
+    stderr: process.stderr,
 });
-if (result.stdout.length > 0) {
-    process.stdout.write(result.stdout);
-}
-if (result.stderr.length > 0) {
-    process.stderr.write(result.stderr);
-}
-process.exitCode = result.exitCode;
 //# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CACxB,YAAY,CAAC,IAAI,GAAG,CAAC,oBAAoB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAC9C,CAAC;AAEzB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IACjD,OAAO,EAAE,OAAO,CAAC,OAAO;IACxB,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;CACnB,CAAC,CAAC;AAEH,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;IAC7B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AACtC,CAAC;AAED,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;IAC7B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AACtC,CAAC;AAED,OAAO,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CACxB,YAAY,CAAC,IAAI,GAAG,CAAC,oBAAoB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAC9C,CAAC;AAEzB,OAAO,CAAC,QAAQ,GAAG,MAAM,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IAC1D,OAAO,EAAE,OAAO,CAAC,OAAO;IACxB,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;IAClB,GAAG,EAAE,OAAO,CAAC,GAAG;IAChB,MAAM,EAAE,OAAO,CAAC,MAAM;IACtB,MAAM,EAAE,OAAO,CAAC,MAAM;CACvB,CAAC,CAAC"}

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

@@ -0,0 +1,65 @@
+/**
+ * Pure eligibility predicate for the optional CLI update check (Step 64).
+ *
+ * The update-notifier contract allows a *newer DepVitals version* notice to be printed to stderr
+ * only after a normal, completed scan in an interactive terminal. Everything before that network
+ * convenience is decided here, so the gates are auditable in one place:
+ *
+ * 1. a completed normal scan invocation (clean **or** with findings) - not help, not version,
+ *    not an argument error, not a failed scan;
+ * 2. both stdout and stderr are interactive TTYs (a pipe or redirection on either stream skips);
+ * 3. no reliable CI flag;
+ * 4. no explicit `DEPVITALS_NO_UPDATE_CHECK=1` opt-out.
+ *
+ * An ineligible invocation must trigger **no** registry lookup, **no** cache read and **no**
+ * notice, so this module deliberately has no imports: it touches no filesystem, no network, no
+ * cache, no clock, no output stream and no ambient global state. Every input is passed in by the
+ * caller (an environment map, two booleans and the command kind), which keeps the decision
+ * deterministic, offline and unit-testable without any real global state.
+ *
+ * The decision is safe by default: anything unknown or unrecognized resolves to `false`, and no
+ * input can make this function throw.
+ */
+/**
+ * The environment map to consult, shaped exactly like the ambient environment the CLI entry point
+ * already holds. Injecting it (instead of reading globals) is what makes every gate testable with
+ * arbitrary, hostile or partially known values.
+ */
+export type NotifierEnv = Readonly<Record<string, string | undefined>>;
+/**
+ * What the CLI is about to do, expressed in the same vocabulary as the argument parser plus the
+ * one outcome the parser cannot know:
+ *
+ * - `scan` - a normal scan invocation that completed (clean or with findings; findings alone set
+ *   exit code 1 and stay eligible);
+ * - `help` / `version` - standalone meta options that never scan;
+ * - `error` - an argument error from {@link parseCliArgs}, i.e. nothing was scanned;
+ * - `scan-failure` - the scan started but failed operationally, so no report was produced.
+ */
+export type NotifierCommandKind = 'scan' | 'help' | 'version' | 'error' | 'scan-failure';
+/** Everything the decision depends on, with no implicit global reads. */
+export type NotifierEligibilityInput = {
+    /** Environment map to consult, e.g. the caller's own environment object. */
+    readonly env: NotifierEnv;
+    /**
+     * Whether the standard output stream is an interactive terminal. Node reports a pipe or a
+     * redirection as non-interactive (its `isTTY` flag is absent), and any falsy value here is
+     * ineligible, so the caller only has to pass the stream's own flag.
+     */
+    readonly stdoutTTY: boolean;
+    /** Whether the error output stream is an interactive terminal, with the same rule as stdout. */
+    readonly stderrTTY: boolean;
+    /** Which command the CLI completed. Only a completed scan can ever be eligible. */
+    readonly commandKind: NotifierCommandKind;
+};
+/**
+ * Decide whether a human interactive invocation may attempt the optional update check.
+ *
+ * Returns `true` only when every gate in the contract's eligibility order passes. `false` means
+ * the caller must not touch the network, must not read the cache and must not print a notice.
+ *
+ * @param input - The injected environment map, the two stream TTY flags and the command kind.
+ * @returns `true` only for an interactive, non-CI, non-opted-out completed normal scan.
+ */
+export declare function isEligibleUpdateCheck(input: NotifierEligibilityInput): boolean;
+//# sourceMappingURL=eligibility.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"eligibility.d.ts","sourceRoot":"","sources":["../../../src/cli/notifier/eligibility.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAEvE;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,cAAc,CAAC;AAEzF,yEAAyE;AACzE,MAAM,MAAM,wBAAwB,GAAG;IACrC,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,gGAAgG;IAChG,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;CAC3C,CAAC;AA0FF;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAe9E"}

package/dist/cli/notifier/eligibility.js

@@ -0,0 +1,123 @@
+/**
+ * Pure eligibility predicate for the optional CLI update check (Step 64).
+ *
+ * The update-notifier contract allows a *newer DepVitals version* notice to be printed to stderr
+ * only after a normal, completed scan in an interactive terminal. Everything before that network
+ * convenience is decided here, so the gates are auditable in one place:
+ *
+ * 1. a completed normal scan invocation (clean **or** with findings) - not help, not version,
+ *    not an argument error, not a failed scan;
+ * 2. both stdout and stderr are interactive TTYs (a pipe or redirection on either stream skips);
+ * 3. no reliable CI flag;
+ * 4. no explicit `DEPVITALS_NO_UPDATE_CHECK=1` opt-out.
+ *
+ * An ineligible invocation must trigger **no** registry lookup, **no** cache read and **no**
+ * notice, so this module deliberately has no imports: it touches no filesystem, no network, no
+ * cache, no clock, no output stream and no ambient global state. Every input is passed in by the
+ * caller (an environment map, two booleans and the command kind), which keeps the decision
+ * deterministic, offline and unit-testable without any real global state.
+ *
+ * The decision is safe by default: anything unknown or unrecognized resolves to `false`, and no
+ * input can make this function throw.
+ */
+/** The only supported opt-out variable; see the update-notifier contract. */
+const NO_UPDATE_CHECK_VARIABLE = 'DEPVITALS_NO_UPDATE_CHECK';
+/** The opt-out is honored for exactly this value and for no other. */
+const NO_UPDATE_CHECK_VALUE = '1';
+/**
+ * The explicit list of environment variables that reliably mean "this is a non-interactive
+ * continuous-integration run". Matching is by exact variable name, never by substring, so
+ * unrelated variables such as `MY_CI`, `CIRCLE_CI` or `GITLAB` are ignored.
+ */
+const CI_VARIABLES = [
+    'CI',
+    'GITHUB_ACTIONS',
+    'GITLAB_CI',
+    'TF_BUILD',
+    'CIRCLECI',
+    'TRAVIS',
+    'BUILDKITE',
+    'JENKINS_URL',
+    'TEAMCITY_VERSION',
+    'APPVEYOR',
+];
+/**
+ * Values that explicitly cancel a CI flag. Providers write real identifiers into these variables
+ * (`CI=TeamCity`, `TF_BUILD=True`), so a value that is present, non-empty and not one of these
+ * tokens counts as CI. Skipping on an unrecognized value is the conservative direction: it costs a
+ * missing notice, never an unexpected request or an extra line in a CI log.
+ */
+const CANCELLED_VALUES = new Set(['', '0', 'false', 'no', 'off']);
+/**
+ * Read one variable from the injected environment map.
+ */
+function read(env, name) {
+    return env[name];
+}
+/**
+ * Whether a CI variable is present with a value that is not an explicit cancellation. Absent and
+ * empty values are not CI; comparison of cancellation tokens is case-insensitive.
+ */
+function isSet(value) {
+    if (value === undefined) {
+        return false;
+    }
+    return !CANCELLED_VALUES.has(value.toLowerCase());
+}
+/**
+ * Whether any recognized CI variable reports a CI run.
+ */
+function isCiRun(env) {
+    return CI_VARIABLES.some((name) => isSet(read(env, name)));
+}
+/**
+ * Whether the user opted out. `DEPVITALS_NO_UPDATE_CHECK` disables the update check if and only if
+ * it equals exactly `"1"`: `0`, ``, `2`, `true`, `01` and padded values do not opt out, and no
+ * broader truthy handling is implemented or implied.
+ */
+function hasOptedOut(env) {
+    return read(env, NO_UPDATE_CHECK_VARIABLE) === NO_UPDATE_CHECK_VALUE;
+}
+/**
+ * Whether the invocation is a completed normal scan. `help`, `version`, argument errors and failed
+ * scans are excluded; a scan that finished with findings is included, because findings are a
+ * successful deterministic result and only change the exit code.
+ */
+function isCompletedScan(commandKind) {
+    switch (commandKind) {
+        case 'scan':
+            return true;
+        case 'help':
+        case 'version':
+        case 'error':
+        case 'scan-failure':
+            return false;
+        default:
+            // A value outside the declared union can only come from an untyped caller; unknown work is
+            // not a completed scan, so the safe default applies here too.
+            return false;
+    }
+}
+/**
+ * Decide whether a human interactive invocation may attempt the optional update check.
+ *
+ * Returns `true` only when every gate in the contract's eligibility order passes. `false` means
+ * the caller must not touch the network, must not read the cache and must not print a notice.
+ *
+ * @param input - The injected environment map, the two stream TTY flags and the command kind.
+ * @returns `true` only for an interactive, non-CI, non-opted-out completed normal scan.
+ */
+export function isEligibleUpdateCheck(input) {
+    if (!isCompletedScan(input.commandKind)) {
+        return false;
+    }
+    // Both streams must be interactive; a pipe or redirection on either one suppresses the check.
+    if (!input.stdoutTTY || !input.stderrTTY) {
+        return false;
+    }
+    if (isCiRun(input.env)) {
+        return false;
+    }
+    return !hasOptedOut(input.env);
+}
+//# sourceMappingURL=eligibility.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"eligibility.js","sourceRoot":"","sources":["../../../src/cli/notifier/eligibility.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAqCH,6EAA6E;AAC7E,MAAM,wBAAwB,GAAG,2BAA2B,CAAC;AAE7D,sEAAsE;AACtE,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAElC;;;;GAIG;AACH,MAAM,YAAY,GAAsB;IACtC,IAAI;IACJ,gBAAgB;IAChB,WAAW;IACX,UAAU;IACV,UAAU;IACV,QAAQ;IACR,WAAW;IACX,aAAa;IACb,kBAAkB;IAClB,UAAU;CACX,CAAC;AAEF;;;;;GAKG;AACH,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;AAEvF;;GAEG;AACH,SAAS,IAAI,CAAC,GAAgB,EAAE,IAAY;IAC1C,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,SAAS,KAAK,CAAC,KAAyB;IACtC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,CAAC,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;AACpD,CAAC;AAED;;GAEG;AACH,SAAS,OAAO,CAAC,GAAgB;IAC/B,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAAC,GAAgB;IACnC,OAAO,IAAI,CAAC,GAAG,EAAE,wBAAwB,CAAC,KAAK,qBAAqB,CAAC;AACvE,CAAC;AAED;;;;GAIG;AACH,SAAS,eAAe,CAAC,WAAgC;IACvD,QAAQ,WAAW,EAAE,CAAC;QACpB,KAAK,MAAM;YACT,OAAO,IAAI,CAAC;QACd,KAAK,MAAM,CAAC;QACZ,KAAK,SAAS,CAAC;QACf,KAAK,OAAO,CAAC;QACb,KAAK,cAAc;YACjB,OAAO,KAAK,CAAC;QACf;YACE,2FAA2F;YAC3F,8DAA8D;YAC9D,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAA+B;IACnE,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;QACxC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,8FAA8F;IAC9F,IAAI,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;QACzC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AACjC,CAAC"}