depvitals 0.0.1 → 0.1.0

package/README.md

@@ -2,28 +2,85 @@
 
 > A simple, lightweight dependency health checker for Node.js projects.
 
-DepVitals is currently under development.
+DepVitals scans a Node.js project to identify declared dependencies that appear unused and imported packages that are not declared in `package.json`.
 
-It is inspired by [depcheck](https://github.com/depcheck/depcheck) and aims to provide a modern,
-focused alternative for checking project dependencies, without becoming a large all-in-one analysis
-tool.
+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.
 
 ## Usage
 
-The `v0.0.1` CLI supports:
-
 ```bash
 npx depvitals
+npx depvitals ./path/to/project
 npx depvitals --help
 npx depvitals --version
 ```
 
-## Current status
+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. The earlier v0.0.1 release contains only the initial CLI bootstrap.
+
+**Exit status:**
+
+```text
+0 = successful clean scan, help, or version
+1 = dependency findings or an operational/CLI error
+```
+
+Scan results, including dependency findings, are printed to `stdout`. Argument errors and operational errors are printed to `stderr`.
+
+## What it detects
+
+- **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`.
+
+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.
+
+Similarly, a dependency is reported as unused only when no supported usage evidence is found. Indirect or unsupported usage may still exist.
+
+`peerDependencies` and `optionalDependencies` are considered when checking whether imported packages are declared, but are never reported as unused.
+
+**Example output:**
+
+```text
+DepVitals
+
+Unused dependencies (2)
+  dotenv
+  lodash
+
+Unused devDependencies (1)
+  eslint
+
+Missing dependencies (1)
+  zod
+```
+
+## 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.
+- **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.
 
-DepVitals is in early development.
+## Current limitations
 
-- `v0.0.1` establishes the package and CLI foundation only.
-- Dependency scanning is not implemented yet and begins in `v0.1.0`.
+- **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 exact package-name matching. Executable names that differ from their package names are not automatically mapped; for example, `tsc` does not mark `typescript` as used.
+- **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.
 
 ## License
 

package/dist/cli/index.js

@@ -2,19 +2,25 @@
 import { readFileSync } from 'node:fs';
 import { runCli } from './runCli.js';
 /**
- * Thin executable adapter for the `v0.0.1` CLI bootstrap.
+ * Thin executable adapter for the `v0.1.0` CLI.
  *
  * Its only responsibilities are:
  * 1. resolve the package version from the single source of truth (`package.json`);
- * 2. delegate argument handling to the pure `runCli` function;
- * 3. render the result to stdout/stderr;
- * 4. assign `process.exitCode` (never call `process.exit()`).
+ * 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()`).
  *
- * 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 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`.
  */
 const version = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
-const result = runCli(process.argv.slice(2), version.version);
+const result = await runCli(process.argv.slice(2), {
+    version: version.version,
+    cwd: process.cwd(),
+});
 if (result.stdout.length > 0) {
     process.stdout.write(result.stdout);
 }

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;;;;;;;;;;;GAWG;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,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;AAE9D,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,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"}

package/dist/cli/parseCliArgs.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Pure, deterministic argument parsing for the `v0.1.0` CLI.
+ *
+ * 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
+ * rules are fully unit-testable without any I/O.
+ *
+ * The supported shapes are intentionally small:
+ * - 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
+ *
+ * `--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.
+ */
+/** The command selected after parsing the arguments. */
+export type ParsedCommand = {
+    kind: 'help';
+} | {
+    kind: 'version';
+} | {
+    kind: 'scan';
+    projectPath: string;
+} | {
+    kind: 'error';
+    message: string;
+};
+/**
+ * Parse the raw arguments (already stripped of `node` and the script path) into a single command.
+ *
+ * @param args - The raw arguments after `node` and the script path.
+ * @param cwd - The current working directory used as the base for relative project paths and as
+ *   the default project when no argument is supplied.
+ */
+export declare function parseCliArgs(args: readonly string[], cwd: string): ParsedCommand;
+//# sourceMappingURL=parseCliArgs.d.ts.map

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

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

package/dist/cli/parseCliArgs.js

@@ -0,0 +1,85 @@
+/**
+ * Pure, deterministic argument parsing for the `v0.1.0` CLI.
+ *
+ * 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
+ * rules are fully unit-testable without any I/O.
+ *
+ * The supported shapes are intentionally small:
+ * - 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
+ *
+ * `--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';
+/** Help/version flags that must be used alone. */
+const HELP_FLAGS = new Set(['--help', '-h']);
+/** Version flags that must be used alone. */
+const VERSION_FLAGS = new Set(['--version', '-v']);
+/** Hint appended to every argument error, so a failing run always points back to `--help`. */
+const HINT = "Run 'depvitals --help' for available commands.";
+/** Error returned when an empty string is passed as the project path. */
+const INVALID_EMPTY_PROJECT_PATH = 'Invalid project path: project path must not be empty.\n' + HINT;
+/** Error returned when more than one positional path is supplied. */
+const TOO_MANY_ARGUMENTS = 'Too many arguments: expected at most one project path.\n' + HINT;
+/**
+ * Parse the raw arguments (already stripped of `node` and the script path) into a single command.
+ *
+ * @param args - The raw arguments after `node` and the script path.
+ * @param cwd - The current working directory used as the base for relative project paths and as
+ *   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.
+    const metaFlag = args.find((arg) => HELP_FLAGS.has(arg) || VERSION_FLAGS.has(arg));
+    if (metaFlag !== undefined) {
+        return { kind: 'error', message: metaFlagMustBeUsedAlone(metaFlag) };
+    }
+    // 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 };
+}
+/**
+ * The error message for an unrecognized option.
+ */
+function unknownOptionMessage(option) {
+    return `Unknown option: ${option}\n${HINT}`;
+}
+/**
+ * The error message when a meta flag is combined with additional tokens.
+ */
+function metaFlagMustBeUsedAlone(flag) {
+    return `Option ${flag} must be used alone.\n${HINT}`;
+}
+//# sourceMappingURL=parseCliArgs.js.map

package/dist/cli/parseCliArgs.js.map

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

package/dist/cli/runCli.d.ts

@@ -1,15 +1,24 @@
 /**
- * Deterministic, side-effect-free CLI behavior for the `v0.0.1` bootstrap.
+ * Asynchronous CLI orchestration for `v0.1.0`.
  *
- * The function never touches `process`: it receives the raw arguments and the package version and
- * returns a plain result object that the thin adapter renders. This keeps the argument handling
- * fully testable without mutating global process state.
+ * `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
+ * `index.ts` is the only code that renders the result.
  *
- * Behavior is intentionally strict for `v0.0.1`:
- * - no arguments            -> early-development message (exit 0)
- * - exactly `--help`/`-h`   -> help output (exit 0)
- * - exactly `--version`/`-v`-> version output (exit 0)
- * - anything else           -> error (exit 1)
+ * The responsibilities here are:
+ * - delegate argument validation to the pure {@link parseCliArgs};
+ * - run the static dependency scan with `analyzeProject`;
+ * - render the report with the pure terminal reporter;
+ * - decide the scan exit code from `hasDependencyIssues`, not from the report string;
+ * - 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`.
+ */
+/**
+ * The rendered CLI result: an exit code and the text to write to each stream. Exactly one of
+ * stdout/stderr is non-empty for every command, so a successful scan never mixes a report with an
+ * error and a failure never prints a misleading clean report.
  */
 export type CliResult = {
     exitCode: number;
@@ -17,10 +26,19 @@ export type CliResult = {
     stderr: string;
 };
 /**
- * Entry point for CLI argument handling.
+ * Options supplied by the process adapter. Injecting `cwd` (rather than reading `process.cwd()`)
+ * keeps the orchestration pure and fully testable without mutating the working directory.
+ */
+export type CliOptions = {
+    version: string;
+    cwd: string;
+};
+/**
+ * Orchestrate the CLI for the given arguments.
  *
- * @param args - The raw arguments (already stripped of `node` and the script path).
- * @param version - The package version read from `package.json`.
+ * @param args - The raw arguments after `node` and the script path.
+ * @param options - The package version and the current working directory.
+ * @returns The exit code and the stdout/stderr text to render.
  */
-export declare function runCli(args: readonly string[], version: string): CliResult;
+export declare function runCli(args: readonly string[], options: CliOptions): Promise<CliResult>;
 //# sourceMappingURL=runCli.d.ts.map

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

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

package/dist/cli/runCli.js

@@ -1,111 +1,103 @@
 /**
- * Deterministic, side-effect-free CLI behavior for the `v0.0.1` bootstrap.
+ * Asynchronous CLI orchestration for `v0.1.0`.
  *
- * The function never touches `process`: it receives the raw arguments and the package version and
- * returns a plain result object that the thin adapter renders. This keeps the argument handling
- * fully testable without mutating global process state.
+ * `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
+ * `index.ts` is the only code that renders the result.
  *
- * Behavior is intentionally strict for `v0.0.1`:
- * - no arguments            -> early-development message (exit 0)
- * - exactly `--help`/`-h`   -> help output (exit 0)
- * - exactly `--version`/`-v`-> version output (exit 0)
- * - anything else           -> error (exit 1)
+ * The responsibilities here are:
+ * - delegate argument validation to the pure {@link parseCliArgs};
+ * - run the static dependency scan with `analyzeProject`;
+ * - render the report with the pure terminal reporter;
+ * - decide the scan exit code from `hasDependencyIssues`, not from the report string;
+ * - 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`.
  */
-const EARLY_DEVELOPMENT_MESSAGE = [
-    'DepVitals',
-    '',
-    'A simple, lightweight dependency health checker for Node.js projects.',
-    '',
-    'Early development release.',
-    'Run `depvitals --help` for available commands.',
-].join('\n');
+import { AnalysisError, analyzeProject } from '../core/analyzeProject.js';
+import { formatTerminalReport, hasDependencyIssues } from '../reporters/terminalReporter.js';
+import { ProjectManifestError } from '../scanner/projectManifest.js';
+import { SourceFilesError } from '../scanner/sourceFiles.js';
+import { parseCliArgs } from './parseCliArgs.js';
 const HELP_MESSAGE = [
     'DepVitals',
     '',
     'A simple, lightweight dependency health checker for Node.js projects.',
     '',
     'Usage:',
-    '  depvitals [options]',
+    '  depvitals [project]',
+    '',
+    'Arguments:',
+    '  project          Project directory to analyze (default: current directory)',
     '',
     'Options:',
-    '  -h, --help     Show help',
-    '  -v, --version  Show version',
+    '  -h, --help       Show help',
+    '  -v, --version    Show version',
 ].join('\n');
-const PRODUCT_NAME = 'depvitals';
-/**
- * Render the early-development message shown when no argument is provided.
- */
-function renderEarlyDevelopment() {
-    return {
-        exitCode: 0,
-        stdout: `${EARLY_DEVELOPMENT_MESSAGE}\n`,
-        stderr: '',
-    };
-}
-/**
- * Render the help output.
- */
-function renderHelp() {
-    return {
-        exitCode: 0,
-        stdout: `${HELP_MESSAGE}\n`,
-        stderr: '',
-    };
-}
-/**
- * Render the package version. The version is passed in so the source of truth stays in
- * `package.json` and is never duplicated as a hard-coded constant.
- */
-function renderVersion(version) {
-    return {
-        exitCode: 0,
-        stdout: `${version}\n`,
-        stderr: '',
-    };
-}
 /**
- * Build the error result for an unsupported argument or combination.
+ * Orchestrate the CLI for the given arguments.
+ *
+ * @param args - The raw arguments after `node` and the script path.
+ * @param options - The package version and the current working directory.
+ * @returns The exit code and the stdout/stderr text to render.
  */
-function renderUnknownOption(option) {
-    const stderr = [
-        `Unknown option: ${option}`,
-        `Run '${PRODUCT_NAME} --help' for available commands.`,
-    ].join('\n');
-    return {
-        exitCode: 1,
-        stdout: '',
-        stderr: `${stderr}\n`,
-    };
+export async function runCli(args, options) {
+    const command = parseCliArgs(args, options.cwd);
+    switch (command.kind) {
+        case 'help':
+            return { exitCode: 0, stdout: `${HELP_MESSAGE}\n`, stderr: '' };
+        case 'version':
+            return { exitCode: 0, stdout: `${options.version}\n`, stderr: '' };
+        case 'error':
+            return { exitCode: 1, stdout: '', stderr: `${command.message}\n` };
+        case 'scan':
+            return await runScan(command.projectPath);
+    }
 }
 /**
- * Entry point for CLI argument handling.
+ * Run the scan for a single project and render its report.
  *
- * @param args - The raw arguments (already stripped of `node` and the script path).
- * @param version - The package version read from `package.json`.
+ * Operational failures from the scanner are converted into a concise CLI error result (exit 1,
+ * 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.
  */
-export function runCli(args, version) {
-    if (args.length === 0) {
-        return renderEarlyDevelopment();
+async function runScan(projectPath) {
+    let result;
+    try {
+        result = await analyzeProject(projectPath);
     }
-    if (args.length === 1) {
-        switch (args[0]) {
-            case '--help':
-            case '-h':
-                return renderHelp();
-            case '--version':
-            case '-v':
-                return renderVersion(version);
+    catch (error) {
+        if (isOperationalError(error)) {
+            return { exitCode: 1, stdout: '', stderr: `${error.message}\n` };
         }
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: `${unexpectedErrorMessage(projectPath, error)}\n`,
+        };
     }
-    // Exactly one argument was expected for a flag; anything else (extra tokens, combinations,
-    // positional paths, unknown flags) is unsupported for `v0.0.1`.
-    const firstUnknown = args.find((argument) => !isKnownFlag(argument));
-    return renderUnknownOption(firstUnknown ?? args.join(' '));
+    const hasIssues = hasDependencyIssues(result);
+    return { exitCode: hasIssues ? 1 : 0, stdout: formatTerminalReport(result), stderr: '' };
 }
 /**
- * Whether a single argument is one of the flags supported by `v0.0.1`.
+ * Whether the thrown value is a scanner error the CLI knows how to render. Only the existing typed
+ * error classes count; everything else is treated as an unexpected internal failure.
  */
-function isKnownFlag(argument) {
-    return (argument === '--help' || argument === '-h' || argument === '--version' || argument === '-v');
+function isOperationalError(error) {
+    return (error instanceof ProjectManifestError ||
+        error instanceof SourceFilesError ||
+        error instanceof AnalysisError);
+}
+/**
+ * The fallback message for an unexpected thrown value. The path is always included so the failure
+ * is traceable; the underlying message is only appended when it is a non-empty, useful `Error`
+ * message, so unknown throwables never leak serialized internals.
+ */
+function unexpectedErrorMessage(projectPath, error) {
+    if (error instanceof Error && error.message.trim().length > 0) {
+        return `Unexpected error while analyzing project ${projectPath}: ${error.message}`;
+    }
+    return `Unexpected error while analyzing project ${projectPath}.`;
 }
 //# sourceMappingURL=runCli.js.map

package/dist/cli/runCli.js.map

@@ -1 +1 @@
-{"version":3,"file":"runCli.js","sourceRoot":"","sources":["../../src/cli/runCli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,MAAM,yBAAyB,GAAG;IAChC,WAAW;IACX,EAAE;IACF,uEAAuE;IACvE,EAAE;IACF,4BAA4B;IAC5B,gDAAgD;CACjD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,YAAY,GAAG;IACnB,WAAW;IACX,EAAE;IACF,uEAAuE;IACvE,EAAE;IACF,QAAQ;IACR,uBAAuB;IACvB,EAAE;IACF,UAAU;IACV,4BAA4B;IAC5B,+BAA+B;CAChC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,YAAY,GAAG,WAAW,CAAC;AAEjC;;GAEG;AACH,SAAS,sBAAsB;IAC7B,OAAO;QACL,QAAQ,EAAE,CAAC;QACX,MAAM,EAAE,GAAG,yBAAyB,IAAI;QACxC,MAAM,EAAE,EAAE;KACX,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,UAAU;IACjB,OAAO;QACL,QAAQ,EAAE,CAAC;QACX,MAAM,EAAE,GAAG,YAAY,IAAI;QAC3B,MAAM,EAAE,EAAE;KACX,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,aAAa,CAAC,OAAe;IACpC,OAAO;QACL,QAAQ,EAAE,CAAC;QACX,MAAM,EAAE,GAAG,OAAO,IAAI;QACtB,MAAM,EAAE,EAAE;KACX,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,mBAAmB,CAAC,MAAc;IACzC,MAAM,MAAM,GAAG;QACb,mBAAmB,MAAM,EAAE;QAC3B,QAAQ,YAAY,kCAAkC;KACvD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,OAAO;QACL,QAAQ,EAAE,CAAC;QACX,MAAM,EAAE,EAAE;QACV,MAAM,EAAE,GAAG,MAAM,IAAI;KACtB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAC,IAAuB,EAAE,OAAe;IAC7D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,sBAAsB,EAAE,CAAC;IAClC,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,QAAQ,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YAChB,KAAK,QAAQ,CAAC;YACd,KAAK,IAAI;gBACP,OAAO,UAAU,EAAE,CAAC;YACtB,KAAK,WAAW,CAAC;YACjB,KAAK,IAAI;gBACP,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,2FAA2F;IAC3F,gEAAgE;IAChE,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC;IACrE,OAAO,mBAAmB,CAAC,YAAY,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED;;GAEG;AACH,SAAS,WAAW,CAAC,QAAgB;IACnC,OAAO,CACL,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,WAAW,IAAI,QAAQ,KAAK,IAAI,CAC5F,CAAC;AACJ,CAAC"}
+{"version":3,"file":"runCli.js","sourceRoot":"","sources":["../../src/cli/runCli.ts"],"names":[],"mappings":"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"}

package/dist/core/analyzeProject.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Dependency analysis.
+ *
+ * This module combines the outputs of the manifest loader, source discovery, module-specifier
+ * extraction, package-specifier classification and script-usage detection into the first real
+ * dependency-analysis engine.
+ *
+ * It answers exactly three questions about a single Node.js project:
+ * - which `dependencies` are never referenced (neither by source files nor by `package.json`
+ *   scripts)?
+ * - which `devDependencies` are never referenced?
+ * - which external packages are referenced by source files but are not declared anywhere?
+ *
+ * It deliberately does not:
+ * - decide whether a dependency is misplaced, a misconfigured peer/optional, or a scoped
+ *   dependency (that belongs to later releases);
+ * - resolve specifiers against `node_modules`, `tsconfig` `paths`, `package.json#imports` or
+ *   bundler aliases (Step 10 only classifies a raw specifier);
+ * - render terminal output, JSON, evidence or confidence (that belongs to later steps);
+ * - execute or import any analyzed source, run package scripts, or mutate the analyzed project;
+ * - consult the network or the npm registry.
+ *
+ * The pipeline is intentionally sequential and single-pass: each discovered source file is read
+ * once and parsed once. No concurrency pool, cache or index is introduced before a measured need
+ * appears.
+ *
+ * Usage/missing formulas (`usedNames` is the union of source-external package roots and script-used
+ * package names; `declaredDependencyNames` is the union of every declared dependency section):
+ *
+ * ```text
+ * sourceUsedNames = external package roots extracted from source files
+ * scriptUsedNames = findPackageScriptUsage(scripts, dependencies ∪ devDependencies)
+ * usedNames       = sourceUsedNames ∪ scriptUsedNames
+ * unusedDependencies    = dependencies    − usedNames
+ * unusedDevDependencies = devDependencies − usedNames
+ * missingDependencies   = sourceUsedNames − declaredDependencyNames
+ * ```
+ *
+ * Scripts never generate missing-dependency findings, and peer/optional declarations suppress false
+ * missing results through `declaredDependencyNames`.
+ */
+/**
+ * The structured outcome of a dependency analysis.
+ *
+ * Every package-name list is sorted alphabetically and contains no duplicates. The result carries
+ * only the facts needed by the `v0.1.0` report: the project root and the three unused/missing
+ * categories. Confidence, explanations, evidence, severity and JSON schema version are deliberately
+ * absent: they are future roadmap concepts.
+ */
+export type AnalysisResult = {
+    /** Absolute, normalized project root (from the manifest). */
+    projectRoot: string;
+    /** Unused `dependencies`, sorted alphabetically. */
+    unusedDependencies: readonly string[];
+    /** Unused `devDependencies`, sorted alphabetically. */
+    unusedDevDependencies: readonly string[];
+    /** External packages referenced by source but not declared anywhere, sorted alphabetically. */
+    missingDependencies: readonly string[];
+};
+/**
+ * Why the analysis could not complete.
+ *
+ * - `unreadable-source`: a discovered source file could not be read from disk.
+ * - `invalid-source`: a discovered source file reached a lexical state from which the specifier
+ *   extractor cannot safely continue (an unterminated string/comment/template/regex, or a malformed
+ *   string escape).
+ */
+export type AnalysisErrorCode = 'unreadable-source' | 'invalid-source';
+/**
+ * Operational error for the dependency-analysis engine.
+ *
+ * The `code` lets callers (the CLI in a later step) render a clean message without matching on error
+ * strings, and the preserved `cause` keeps the original filesystem or parsing failure. The affected
+ * source-file path is always included in the message so an unreadable or invalid file is never
+ * silently skipped.
+ */
+export declare class AnalysisError extends Error {
+    readonly code: AnalysisErrorCode;
+    constructor(message: string, code: AnalysisErrorCode, cause?: unknown);
+}
+/**
+ * Analyze the single project rooted at `projectRoot` and return the structured unused/missing result.
+ *
+ * The supplied root is resolved to an absolute path; `process.cwd()` is never changed and the target
+ * project is never written to.
+ *
+ * @throws {AnalysisError} when a discovered source file cannot be read or cannot be safely analyzed.
+ * @throws {ProjectManifestError} when the manifest is missing, unreadable, invalid or malformed.
+ * @throws {SourceFilesError} when the root is missing, is not a directory, or cannot be read.
+ */
+export declare function analyzeProject(projectRoot: string): Promise<AnalysisResult>;
+//# sourceMappingURL=analyzeProject.d.ts.map