depvitals 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matias Ricardi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# DepVitals
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> A simple, lightweight dependency health checker for Node.js projects.
+
+DepVitals scans a Node.js project to identify declared dependencies that appear unused and imported packages that are not declared in `package.json`.
+
+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
+
+```bash
+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. 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.
+
+## Current limitations
+
+- **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
+
+MIT

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}

package/dist/cli/index.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { runCli } from './runCli.js';
+/**
+ * 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. 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()`).
+ *
+ * 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 = await runCli(process.argv.slice(2), {
+    version: version.version,
+    cwd: process.cwd(),
+});
+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

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

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

@@ -0,0 +1,44 @@
+/**
+ * Asynchronous CLI orchestration for `v0.1.0`.
+ *
+ * `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.
+ *
+ * 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;
+    stdout: string;
+    stderr: string;
+};
+/**
+ * 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 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[], options: CliOptions): Promise<CliResult>;
+//# sourceMappingURL=runCli.d.ts.map

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

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

@@ -0,0 +1,103 @@
+/**
+ * Asynchronous CLI orchestration for `v0.1.0`.
+ *
+ * `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.
+ *
+ * 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`.
+ */
+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 [project]',
+    '',
+    'Arguments:',
+    '  project          Project directory to analyze (default: current directory)',
+    '',
+    'Options:',
+    '  -h, --help       Show help',
+    '  -v, --version    Show version',
+].join('\n');
+/**
+ * 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.
+ */
+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);
+    }
+}
+/**
+ * Run the scan for a single project and render its report.
+ *
+ * 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.
+ */
+async function runScan(projectPath) {
+    let result;
+    try {
+        result = await analyzeProject(projectPath);
+    }
+    catch (error) {
+        if (isOperationalError(error)) {
+            return { exitCode: 1, stdout: '', stderr: `${error.message}\n` };
+        }
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: `${unexpectedErrorMessage(projectPath, error)}\n`,
+        };
+    }
+    const hasIssues = hasDependencyIssues(result);
+    return { exitCode: hasIssues ? 1 : 0, stdout: formatTerminalReport(result), stderr: '' };
+}
+/**
+ * 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 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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"analyzeProject.d.ts","sourceRoot":"","sources":["../../src/core/analyzeProject.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAUH;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,uDAAuD;IACvD,qBAAqB,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,+FAA+F;IAC/F,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,mBAAmB,GAAG,gBAAgB,CAAC;AAEvE;;;;;;;GAOG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;gBAErB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,CAAC,EAAE,OAAO;CAKtE;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CA6CjF"}