dependency-radar 0.2.0 → 0.3.0

package/README.md

@@ -17,6 +17,18 @@ Dependency Radar is a local-first CLI tool that inspects a Node.js project’s i
 - Not a bundler or build tool
 - Not a dependency updater
 
+
+## License Scanning
+
+Dependency Radar validates SPDX licenses declared in `package.json` and can infer licenses from `LICENSE` files when declarations are missing or invalid. It works offline and uses a bundled SPDX identifier list (generated at build time) with no runtime network access. Each dependency gets a structured license record with:
+
+- Declared SPDX validation (including deprecated IDs and `WITH` exceptions)
+- Inferred SPDX license (with confidence: `high`, `medium`, `low`) based on deterministic text matching
+- A status (`declared-only`, `inferred-only`, `match`, `mismatch`, `invalid-spdx`, `unknown`) to make review decisions easier
+
+This logic applies to all dependencies (direct and transitive). Inferred licenses are never treated as authoritative over valid declared SPDX expressions.
+
+
 ## Setup
 
 ```bash
@@ -53,10 +65,10 @@ Keep the temporary `.dependency-radar` folder for debugging raw tool outputs:
 npx dependency-radar --keep-temp
 ```
 
-Skip `npm audit` (useful for offline scans):
+Skip `npm audit` and `npm outdated` (useful for offline scans):
 
 ```bash
-npx dependency-radar --no-audit
+npx dependency-radar --offline
 ```
 
 Output JSON instead of HTML report:
@@ -65,6 +77,12 @@ Output JSON instead of HTML report:
 npx dependency-radar --json
 ```
 
+Open the generated report using the system default:
+
+```bash
+npx dependency-radar --open
+```
+
 Show options:
 
 ```bash
@@ -81,7 +99,7 @@ npx dependency-radar --help
 
 - The target project must have node_modules installed (run npm install first).
 - The scan is local-first and does not upload your code or dependencies anywhere.
-- `npm audit` performs registry lookups; use `--no-audit` for offline-only scans.
+- `npm audit` and `npm outdated` perform registry lookups; use `--offline` for offline-only scans.
 - A temporary `.dependency-radar` folder is created during the scan to store intermediate tool output.
 - Use `--keep-temp` to retain this folder for debugging; otherwise it is deleted automatically.
 - If a tool fails, its section is marked as unavailable, but the report is still generated.
@@ -99,27 +117,167 @@ The JSON schema matches the `AggregatedData` TypeScript interface in `src/types.
 
 ```ts
 export interface AggregatedData {
-  generatedAt: string;
-  projectPath: string;
-  gitBranch?: string;
-  dependencyRadarVersion?: string;
-  maintenanceEnabled: boolean;
+  schemaVersion: '1.2'; // Report schema version for compatibility checks
+  generatedAt: string; // ISO timestamp when the scan finished
+  dependencyRadarVersion: string; // CLI version that produced the report
+  git: {
+    branch: string; // Git branch name, empty when unavailable/detached
+  };
+  project: {
+    projectDir: string; // Project path relative to the user's home directory (e.g. /Developer/app)
+  };
   environment: {
-    node: {
-      runtimeVersion: string;
-      runtimeMajor: number;
-      minRequiredMajor?: number;
-      source: 'dependency-engines' | 'project-engines' | 'unknown';
+    nodeVersion: string; // Node.js version from process.versions.node
+    runtimeVersion: string; // Node.js runtime version from process.version
+    minRequiredMajor: number; // Strictest Node major required by dependency engines (0 if unknown)
+    platform?: string; // OS platform (process.platform)
+    arch?: string; // CPU architecture (process.arch)
+    ci?: boolean; // True when running in CI (process.env.CI === 'true')
+    packageManagerField?: string; // package.json packageManager field (e.g. pnpm@9.1.0)
+    packageManager?: 'npm' | 'pnpm' | 'yarn'; // Package manager used to scan
+    packageManagerVersion?: string; // Version of the package manager used to scan
+    toolVersions?: {
+      npm?: string;
+      pnpm?: string;
+      yarn?: string;
+    };
+  };
+  workspaces: {
+    enabled: boolean; // True when the scan used workspace aggregation
+    type?: 'npm' | 'pnpm' | 'yarn' | 'none'; // Workspace type if detected
+    packageCount?: number; // Number of workspace packages scanned
+  };
+  summary: {
+    dependencyCount: number; // Total dependencies in the graph
+    directCount: number; // Dependencies listed in package.json
+    transitiveCount: number; // Dependencies pulled in by other dependencies
+  };
+  dependencies: Record<string, DependencyRecord>; // Keyed by name@version
+}
+
+export interface DependencyRecord {
+  package: {
+    id: string; // Stable identifier in the form name@version
+    name: string; // Package name from npm metadata
+    version: string; // Installed version from npm ls
+    description?: string; // Description from the installed package.json (if present)
+    deprecated: boolean; // True if the package.json has a deprecated flag
+    links: {
+      npm: string; // npm package page URL
+      repository?: string; // Repository URL (if present)
+      homepage?: string; // Homepage URL (if present)
+      bugs?: string; // Issue tracker URL (if present)
+    };
+  };
+  compliance: {
+    license: {
+      declared?: {
+        spdxId: string; // SPDX ID or expression from package.json
+        expression: boolean; // True when SPDX expression (AND/OR/WITH)
+        deprecated: boolean; // True if SPDX ID is deprecated
+        valid: boolean; // True if SPDX ID/expression is valid
+      };
+      inferred?: {
+        spdxId: string; // SPDX ID inferred from LICENSE text
+        confidence: 'high' | 'medium' | 'low'; // Heuristic confidence
+      };
+      exception?: {
+        id: string; // SPDX exception id
+        deprecated: boolean; // True if exception is deprecated
+        valid: boolean; // True if exception id is valid
+      };
+      status:
+        | 'declared-only'
+        | 'inferred-only'
+        | 'match'
+        | 'mismatch'
+        | 'invalid-spdx'
+        | 'unknown';
+    };
+    licenseRisk: 'green' | 'amber' | 'red'; // Risk classification derived from declared/inferred SPDX ids
+  };
+  security: {
+    summary: {
+      critical: number; // npm audit counts for critical issues
+      high: number; // npm audit counts for high issues
+      moderate: number; // npm audit counts for moderate issues
+      low: number; // npm audit counts for low issues
+      highest: 'low' | 'moderate' | 'high' | 'critical' | 'none'; // Highest severity present
+      risk: 'green' | 'amber' | 'red'; // Risk classification derived from audit counts
+    };
+    advisories?: Array<{
+      id: string; // GHSA identifier
+      title: string; // Human-readable advisory title
+      severity: 'low' | 'moderate' | 'high' | 'critical';
+      vulnerableRange: string; // Semver range
+      fixAvailable: boolean; // True if npm audit indicates a fix exists
+      url: string; // Advisory URL
+    }>;
+  };
+  upgrade: {
+    nodeEngine: string | null; // engines.node from the package.json (if present)
+    outdatedStatus?: 'current' | 'patch' | 'minor' | 'major' | 'unknown'; // Derived from npm outdated (if present)
+    latestVersion?: string; // npm latest version (present only when status is not current)
+    blockers?: Array<'nodeEngine' | 'peerDependency' | 'nativeBindings' | 'deprecated'>; // Reasons for upgrade friction
+    blocksNodeMajor?: boolean; // True if local signals indicate a node major bump is risky
+  };
+  usage: {
+    direct: boolean; // True if declared in package.json (dependencies/devDependencies/etc.)
+    scope: 'runtime' | 'dev' | 'optional' | 'peer'; // Scope inferred from the declaring root package(s)
+    depth: number; // Minimum dependency tree depth observed in npm ls
+    origins: {
+      rootPackageCount: number; // Number of direct roots that introduce this dependency
+      topRootPackages: Array<{ name: string; version: string }>; // Up to 10 root packages (name/version)
+      parentPackageCount: number; // Number of direct parents
+      topParentPackages: string[]; // Up to 5 direct parent ids (name@version)
+      workspaces?: string[]; // Workspace packages that declare/use this dependency
+    };
+    introduction?: 'direct' | 'tooling' | 'framework' | 'testing' | 'transitive' | 'unknown'; // Heuristic for why the dependency exists
+    runtimeImpact?: 'runtime' | 'build' | 'testing' | 'tooling' | 'mixed'; // Heuristic based on import locations
+    importUsage?: {
+      fileCount: number; // Number of project files importing this package (import graph)
+      topFiles: string[]; // Top import locations (bounded to 5)
+    };
+    tsTypes: 'bundled' | 'definitelyTyped' | 'none' | 'unknown'; // TypeScript type availability
+  };
+  graph: {
+    fanIn: number; // Number of packages that depend on this package
+    fanOut: number; // Number of packages this package depends on
+    subDeps?: {
+      // Declared outgoing dependency edges; values are tuples.
+      // tuple[0] = declared version range, tuple[1] = resolved dependency id or null if not installed.
+      // Only installed dependencies have full dependency records in the top-level list.
+      dep?: Record<string, [string, string | null]>; // Declared runtime deps
+      dev?: Record<string, [string, string | null]>; // Declared dev deps
+      peer?: Record<string, [string, string | null]>; // Declared peer deps
+      opt?: Record<string, [string, string | null]>; // Declared optional deps
+    };
+  };
+  execution?: {
+    risk: 'amber' | 'red'; // Install-time risk (green implied when absent)
+    native?: true; // True if native bindings or build tooling are detected
+    scripts?: {
+      hooks: Array<'preinstall' | 'install' | 'postinstall' | 'prepare'>; // Lifecycle hooks detected
+      complexity?: number; // Heuristic complexity (stored only when high)
+      signals?: Array<
+        | 'network-access'
+        | 'dynamic-exec'
+        | 'child-process'
+        | 'encoding'
+        | 'obfuscated'
+        | 'reads-env'
+        | 'reads-home'
+        | 'uses-ssh'
+      >; // Review-worthy install-time signals (sparse)
     };
   };
-  dependencies: DependencyRecord[];
-  toolErrors: Record<string, string>;
-  raw: RawOutputs;
-  importAnalysis?: ImportAnalysisSummary;
 }
 ```
 
-For full details on `DependencyRecord`, `RawOutputs`, and related types, see `src/types.ts`.
+For full details and any future changes, see `src/types.ts`.
+
+Environment data includes Node.js version, OS platform, CPU architecture, and package manager versions.
+No personal information, usernames, paths, or environment variables are collected.
 
 ## Development
 
@@ -149,4 +307,3 @@ This opens the report UI in your browser with sample data covering all dependenc
 - `report-ui/sample-data.json` – Sample data for development
 - `report-ui/types.ts` – Client-side TypeScript types
 - `src/report-assets.ts` – Auto-generated file with bundled CSS/JS (do not edit directly)
-