ng-upgrade-doctor 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammed S Hirani
+
+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

@@ -0,0 +1,91 @@
+# ng-upgrade-doctor
+
+> Zero-dependency Angular upgrade readiness & blast-radius diagnostic.
+
+Run one command in any Angular project and get the whole picture: what's installed, what's compatible with the next Angular versions, what will block the upgrade, what's abandoned, and roughly how much effort it will take — as a shareable HTML report, machine-readable JSON, and a terminal summary.
+
+`ng-upgrade-doctor` is a **diagnostician, not an upgrader**. It tells you what you're walking into *before* you run `ng update`. It never modifies your code — it's completely read-only.
+
+## Quick start
+
+```bash
+npx ng-upgrade-doctor
+```
+
+That's it. No install, no config, no `ng add`. It writes `ng-upgrade-report.html` and `ng-upgrade-report.json` into your project.
+
+## Why "zero dependency"?
+
+The published package has an empty `dependencies` map. It relies only on the Node standard library:
+
+- **Reading `package.json` / lockfiles** — `fs` + `JSON.parse`
+- **Querying the npm registry** — global `fetch` (Node 18+) with an automatic `https` fallback for Node 14–16
+- **Parsing the source tree** — plain regex census (no AST parser bundled)
+- **Rendering the report** — template strings → one self-contained HTML file
+
+This keeps installs instant, supply-chain risk near zero, and makes it safe to run in CI.
+
+## What's in the report
+
+| Section | Highlights |
+|---|---|
+| **Project inventory** | dependency counts (prod/dev/transitive), Angular packages, 3rd-party Angular libs, components, NgModules, services, standalone ratio, file counts, LOC, build system, test/e2e stack |
+| **Version gap** | how many majors behind, support/EOL status, hop-by-hop upgrade path with per-version Node/TS requirements |
+| **Dependency compatibility** | every dependency classified: compatible / needs upgrade / partial / blocker / removed / abandoned, with the highest Angular major each supports (resolved from live npm peer dependencies) and recommended replacements |
+| **Readiness score** | a transparent 0–100 score with every deduction itemized, plus an effort band in person-days |
+| **Must-fix + quick wins** | the ordered blocker list and the fastest things to clear first |
+
+## Usage
+
+```
+npx ng-upgrade-doctor [path] [options]
+
+Options:
+  --target <major>     Target Angular major to assess against (default: latest known)
+  --offline            Skip the registry; classify from the local knowledge base only
+  --no-code            Skip the source-tree census (deps only, faster)
+  --out <dir>          Where to write reports (default: project dir)
+  --concurrency <n>    Parallel registry lookups (default: 8)
+  --ci                 Exit 1 if hard blockers exist or score < --min-score
+  --min-score <n>      Minimum readiness score for --ci to pass
+  --quiet              Suppress progress output
+  -h, --help / -v, --version
+```
+
+### CI gate example
+
+```bash
+npx ng-upgrade-doctor --ci --min-score 60
+```
+
+Fails the build if there are hard blockers or the readiness score drops below 60 — a way to stop upgrade debt from piling up.
+
+## How compatibility is determined
+
+For each dependency, the tool fetches the npm packument and finds the **highest Angular major** that any published version's `peerDependencies["@angular/core"]` accepts. Compared against your target, that yields the classification. A curated knowledge base (`src/data/known-packages.js`) overlays truths a registry lookup can't know — officially removed tooling (`tslint`, `protractor`), discontinued libraries (`@angular/flex-layout`), and recommended replacements.
+
+> Compatibility is *inferred*. Always confirm against the official [Angular Update Guide](https://angular.dev/update-guide) before upgrading.
+
+## Code breaking-change scan (AST)
+
+For `.ts` files the tool borrows the target project's own **TypeScript compiler**
+and walks the real AST, matching against a versioned rulebook
+(`src/data/breaking-changes.js`) of removed/deprecated APIs — e.g. `entryComponents`,
+legacy `rxjs/add` and `rxjs-compat` imports, `TestBed.get()`, `.toPromise()`, the
+`async()` test helper, `@angular/material` barrel imports, and more. Templates are
+scanned for modernization opportunities (`*ngIf`/`*ngFor`/`*ngSwitch` → built-in
+control flow) and discontinued `fx*` flex-layout directives. Every hit is reported
+as `file:line:col`. If the compiler can't be resolved, it falls back to a regex scan
+so the section still has value.
+
+## Roadmap
+
+- **v0.1** — inventory, version gap, dependency compatibility matrix, readiness score, HTML/JSON/terminal reports ✅
+- **v0.2** — AST-based breaking-change scanner (removed/deprecated API usage + modernization opportunities with `file:line:col`) ✅
+- **v0.3** — staged migration planner with per-hop effort and modernization guidance (standalone, signals, zoneless)
+- **v0.4** — Nx/monorepo awareness, richer CI output (SARIF/markdown)
+- **v1.0** — community-maintained rules database
+
+## License
+
+MIT

package/bin/ng-upgrade-doctor.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+'use strict';
+
+const { main } = require('../src/cli');
+main();

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "ng-upgrade-doctor",
+  "version": "0.2.0",
+  "description": "Zero-dependency Angular upgrade readiness & blast-radius diagnostic. Run npx ng-upgrade-doctor in any Angular project to get a full picture of what needs upgrading, what will break, and how hard it will be.",
+  "keywords": [
+    "angular",
+    "upgrade",
+    "migration",
+    "ng-update",
+    "audit",
+    "dependencies",
+    "readiness",
+    "diagnostic"
+  ],
+  "license": "MIT",
+  "author": "Mohammed S Hirani <mohammadhirani-cmpn@atharvacoe.ac.in>",
+  "homepage": "https://github.com/mohd-hirani/ng-upgrade-doctor#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mohd-hirani/ng-upgrade-doctor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mohd-hirani/ng-upgrade-doctor/issues"
+  },
+  "type": "commonjs",
+  "bin": {
+    "ng-upgrade-doctor": "bin/ng-upgrade-doctor.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/ng-upgrade-doctor.js",
+    "test": "node test/run.js"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "private": false
+}

package/src/analyzers/breaking-changes.js

@@ -0,0 +1,118 @@
+'use strict';
+
+const path = require('path');
+const { walkFiles } = require('../utils/fs-helpers');
+const { loadTypeScript } = require('../ast/loader');
+const { scanTsFiles } = require('../ast/ts-scanner');
+const { scanWithRegex } = require('../ast/regex-scanner');
+const { TS_RULES, TEMPLATE_RULES } = require('../data/breaking-changes');
+
+const RULE_INDEX = {};
+[...TS_RULES, ...TEMPLATE_RULES].forEach((r) => (RULE_INDEX[r.id] = r));
+
+const SAMPLE_CAP = 8; // locations retained per rule for the report
+
+/**
+ * Scans the source tree for removed/deprecated API usage and modernization
+ * opportunities. Uses the target project's TypeScript compiler for .ts files
+ * (AST) and regex for .html templates; falls back to regex for .ts when the
+ * compiler can't be borrowed.
+ */
+function analyzeBreakingChanges(projectDir, options = {}) {
+  const { onProgress } = options;
+  const srcRoot = requireSrc(projectDir);
+
+  const tsFiles = walkFiles(srcRoot, ['.ts'], 15000).filter((f) => !f.endsWith('.d.ts'));
+  const htmlFiles = walkFiles(srcRoot, ['.html'], 15000);
+
+  const { ts, source } = loadTypeScript(projectDir);
+  const astAvailable = Boolean(ts);
+
+  let tsFindings;
+  if (astAvailable) {
+    tsFindings = scanTsFiles(ts, tsFiles, TS_RULES, projectDir, progress(onProgress, 'ts', tsFiles.length));
+  } else {
+    // Degrade to regex over TS files.
+    tsFindings = scanWithRegex(tsFiles, TS_RULES, projectDir, progress(onProgress, 'ts', tsFiles.length));
+  }
+
+  const templateFindings = scanWithRegex(htmlFiles, TEMPLATE_RULES, projectDir, progress(onProgress, 'html', htmlFiles.length));
+
+  const findings = tsFindings.concat(templateFindings);
+  return aggregate(findings, {
+    astAvailable,
+    tsCompilerSource: source ? path.relative(projectDir, source) || source : null,
+    filesScanned: { ts: tsFiles.length, html: htmlFiles.length },
+  });
+}
+
+function aggregate(findings, extra) {
+  const perRule = {};
+  const affectedFiles = new Set();
+  const severityCounts = { removed: 0, deprecated: 0, opportunity: 0 };
+
+  for (const f of findings) {
+    const rule = RULE_INDEX[f.ruleId];
+    if (!rule) continue;
+    affectedFiles.add(f.file);
+    severityCounts[rule.severity] = (severityCounts[rule.severity] || 0) + 1;
+
+    if (!perRule[f.ruleId]) {
+      perRule[f.ruleId] = {
+        id: rule.id,
+        title: rule.title,
+        severity: rule.severity,
+        since: rule.since,
+        scope: rule.scope,
+        message: rule.message,
+        fix: rule.fix,
+        docs: rule.docs,
+        count: 0,
+        files: new Set(),
+        samples: [],
+      };
+    }
+    const entry = perRule[f.ruleId];
+    entry.count += 1;
+    entry.files.add(f.file);
+    if (entry.samples.length < SAMPLE_CAP) {
+      entry.samples.push(`${f.file}:${f.line}:${f.col}`);
+    }
+  }
+
+  const SEV_ORDER = { removed: 0, deprecated: 1, opportunity: 2 };
+  const rules = Object.values(perRule)
+    .map((r) => ({ ...r, fileCount: r.files.size, files: undefined }))
+    .sort((a, b) => (SEV_ORDER[a.severity] - SEV_ORDER[b.severity]) || (b.count - a.count));
+
+  return {
+    astAvailable: extra.astAvailable,
+    tsCompilerSource: extra.tsCompilerSource,
+    filesScanned: extra.filesScanned,
+    summary: {
+      totalHits: findings.length,
+      removed: severityCounts.removed,
+      deprecated: severityCounts.deprecated,
+      opportunity: severityCounts.opportunity,
+      rulesTriggered: rules.length,
+      filesAffected: affectedFiles.size,
+    },
+    rules,
+  };
+}
+
+function requireSrc(projectDir) {
+  const fs = require('fs');
+  const src = path.join(projectDir, 'src');
+  try {
+    if (fs.existsSync(src)) return src;
+  } catch (_) { /* ignore */ }
+  return projectDir;
+}
+
+function progress(onProgress, phase, total) {
+  if (!onProgress) return null;
+  return (done) => onProgress(phase, done, total);
+}
+
+module.exports = { analyzeBreakingChanges };

package/src/analyzers/code-census.js

@@ -0,0 +1,101 @@
+'use strict';
+
+const path = require('path');
+const { walkFiles, safeReadFile, exists } = require('../utils/fs-helpers');
+
+/**
+ * Lightweight, regex-based census of the source tree. No AST, no dependency —
+ * just counts the building blocks so the report can say "N components,
+ * M NgModules, standalone ratio", plus a few cheap upgrade signals.
+ *
+ * These are heuristics (comments/strings can inflate counts slightly), and
+ * the report labels them as approximate.
+ */
+function analyzeCensus(projectDir) {
+  const srcRoot = exists(path.join(projectDir, 'src')) ? path.join(projectDir, 'src') : projectDir;
+  const tsFiles = walkFiles(srcRoot, ['.ts'], 15000).filter((f) => !f.endsWith('.d.ts'));
+  const htmlFiles = walkFiles(srcRoot, ['.html'], 15000);
+  const styleFiles = walkFiles(srcRoot, ['.scss', '.css', '.sass', '.less'], 15000);
+  const specFiles = tsFiles.filter((f) => f.endsWith('.spec.ts'));
+
+  const counts = {
+    components: 0,
+    standaloneComponents: 0,
+    modules: 0,
+    services: 0,
+    directives: 0,
+    pipes: 0,
+    totalLoc: 0,
+  };
+
+  // Upgrade-relevant signals (cheap, high-signal patterns)
+  const signals = {
+    rxjsCompatImports: 0,
+    deepRxjsOperatorImports: 0, // rxjs/operators - fine, but rxjs/add/... is legacy
+    legacyRxjsAddImports: 0,
+    entryComponents: 0,
+    viewChildStatic: 0,
+    moduleWithProvidersNoGeneric: 0,
+    ngModuleFiles: 0,
+    filesWithHits: new Set(),
+  };
+
+  for (const file of tsFiles) {
+    const content = safeReadFile(file);
+    if (!content) continue;
+    counts.totalLoc += content.split('\n').length;
+
+    counts.components += countMatches(content, /@Component\s*\(/g);
+    counts.modules += countMatches(content, /@NgModule\s*\(/g);
+    counts.services += countMatches(content, /@Injectable\s*\(/g);
+    counts.directives += countMatches(content, /@Directive\s*\(/g);
+    counts.pipes += countMatches(content, /@Pipe\s*\(/g);
+    counts.standaloneComponents += countMatches(content, /standalone\s*:\s*true/g);
+
+    if (/@NgModule\s*\(/.test(content)) signals.ngModuleFiles += 1;
+
+    const localHits = [];
+    localHits.push(['rxjsCompatImports', countMatches(content, /from\s+['"]rxjs-compat/g)]);
+    localHits.push(['legacyRxjsAddImports', countMatches(content, /from\s+['"]rxjs\/add\//g)]);
+    localHits.push(['entryComponents', countMatches(content, /entryComponents\s*:/g)]);
+    localHits.push(['viewChildStatic', countMatches(content, /@ViewChild\([^)]*static\s*:/g)]);
+    localHits.push(['moduleWithProvidersNoGeneric', countMatches(content, /:\s*ModuleWithProviders\s*[;,)]/g)]);
+
+    let fileHit = false;
+    for (const [key, n] of localHits) {
+      if (n > 0) {
+        signals[key] += n;
+        fileHit = true;
+      }
+    }
+    if (fileHit) signals.filesWithHits.add(file);
+  }
+
+  return {
+    fileCounts: {
+      tsFiles: tsFiles.length,
+      htmlTemplates: htmlFiles.length,
+      styleFiles: styleFiles.length,
+      specFiles: specFiles.length,
+    },
+    counts,
+    standaloneRatio:
+      counts.components > 0 ? Math.round((counts.standaloneComponents / counts.components) * 100) : null,
+    signals: {
+      rxjsCompatImports: signals.rxjsCompatImports,
+      legacyRxjsAddImports: signals.legacyRxjsAddImports,
+      entryComponents: signals.entryComponents,
+      viewChildStatic: signals.viewChildStatic,
+      moduleWithProvidersNoGeneric: signals.moduleWithProvidersNoGeneric,
+      ngModuleFiles: signals.ngModuleFiles,
+      filesWithBreakingSignals: signals.filesWithHits.size,
+    },
+  };
+}
+
+function countMatches(str, regex) {
+  const m = str.match(regex);
+  return m ? m.length : 0;
+}
+
+module.exports = { analyzeCensus };

package/src/analyzers/dependency-compat.js

@@ -0,0 +1,174 @@
+'use strict';
+
+const semver = require('../utils/semver');
+const { fetchPackument, mapPool } = require('../registry');
+const knownPackages = require('../data/known-packages');
+
+/**
+ * Classification buckets:
+ *   ok         🟢 compatible with the target Angular (a supporting version exists)
+ *   upgrade    🟡 compatible but you're behind the latest
+ *   partial    🟡 supports some hops but not all the way to target
+ *   blocker    🔴 no published version supports the target Angular major
+ *   removed    🔵 removed from Angular / discontinued (from knowledge base)
+ *   abandoned  ⚫ unmaintained (old last-publish or npm-deprecated)
+ *   agnostic   🟢 not Angular-coupled; version-independent
+ *   unknown    ⚪ could not resolve (offline / not found)
+ */
+
+const STALE_YEARS = 2;
+
+async function analyzeDependencies(snapshot, targetMajor, options = {}) {
+  const { offline = false, concurrency = 8, onProgress } = options;
+  const currentMajor = snapshot.angularMajor || targetMajor;
+  const entries = Object.entries(snapshot.allDeps);
+  const isDev = (name) => name in (snapshot.devDependencies || {});
+
+  let done = 0;
+  const results = await mapPool(entries, concurrency, async ([name, range]) => {
+    const res = await classifyPackage(name, range, targetMajor, { offline, isDev: isDev(name), currentMajor });
+    done += 1;
+    if (onProgress) onProgress(done, entries.length, name);
+    return res;
+  });
+
+  const summary = tally(results);
+  return { packages: results.sort(sortBySeverity), summary, targetMajor };
+}
+
+async function classifyPackage(name, declaredRange, targetMajor, { offline, isDev, currentMajor }) {
+  const known = knownPackages.lookup(name);
+  const base = {
+    name,
+    declaredRange,
+    dev: isDev,
+    angularCoupled: knownPackages.looksAngularCoupled(name),
+    latestVersion: null,
+    lastPublish: null,
+    maxAngularSupported: null,
+    deprecated: false,
+    replacement: known ? known.replacement : null,
+  };
+
+  // Knowledge-base overrides come first — these are curated truths that hold
+  // regardless of what the registry says.
+  if (known && (known.status === 'removed' || known.status === 'discontinued')) {
+    return { ...base, category: 'removed', reason: known.reason, kbStatus: known.status };
+  }
+  if (known && known.status === 'transitional') {
+    // e.g. rxjs-compat — a migration shim that must not survive an upgrade.
+    return { ...base, category: 'blocker', reason: known.reason, kbStatus: known.status };
+  }
+
+  if (offline) {
+    return offlineClassify(base, known, targetMajor);
+  }
+
+  const packument = await fetchPackument(name);
+  if (!packument) {
+    return offlineClassify(base, known, targetMajor, 'Registry lookup failed (offline or not found).');
+  }
+
+  const latest = (packument['dist-tags'] && packument['dist-tags'].latest) || null;
+  base.latestVersion = latest;
+  base.deprecated = Boolean(
+    (packument.versions && latest && packument.versions[latest] && packument.versions[latest].deprecated) ||
+    packument.deprecated
+  );
+  if (packument.time && latest && packument.time[latest]) {
+    base.lastPublish = packument.time[latest];
+  }
+
+  // Determine the highest Angular major supported across published versions.
+  let maxSupported = null;
+  if (packument.versions) {
+    for (const [ver, meta] of Object.entries(packument.versions)) {
+      const peer = meta && meta.peerDependencies && meta.peerDependencies['@angular/core'];
+      if (peer) {
+        const hi = semver.highestSupportedMajor(peer);
+        if (hi != null && (maxSupported == null || hi > maxSupported)) maxSupported = hi;
+      }
+    }
+  }
+  base.maxAngularSupported = maxSupported;
+
+  const stale = isStale(base.lastPublish);
+
+  // Non-Angular-coupled library: generally version-independent.
+  if (maxSupported == null && !base.angularCoupled) {
+    if (base.deprecated) return { ...base, category: 'abandoned', reason: 'Marked deprecated on npm.' };
+    if (stale && known && known.status) return { ...base, category: 'abandoned', reason: known.reason };
+    if (stale) return { ...base, category: 'abandoned', reason: `No release in over ${STALE_YEARS} years.` };
+    if (known && known.status === 'maintenance') return { ...base, category: 'upgrade', reason: known.reason };
+    return { ...base, category: 'agnostic', reason: 'Framework-agnostic; not tied to an Angular version.' };
+  }
+
+  // Angular-coupled library — judge by max supported major.
+  if (maxSupported == null) {
+    // Coupled by name but no peer dep info; lean on KB / staleness.
+    if (known && known.status === 'abandoned') return { ...base, category: 'abandoned', reason: known.reason };
+    if (stale) return { ...base, category: 'abandoned', reason: `No release in over ${STALE_YEARS} years.` };
+    return { ...base, category: 'unknown', reason: 'Angular-coupled but peer dependency on @angular/core not declared.' };
+  }
+
+  if (maxSupported >= targetMajor) {
+    return { ...base, category: 'ok', reason: `Supports Angular ${maxSupported} (>= target ${targetMajor}).` };
+  }
+  if (maxSupported >= currentMajor) {
+    // Works at your current version (or beyond) but can't reach the target yet.
+    return { ...base, category: 'partial', reason: `Supports up to Angular ${maxSupported}; blocks the final jump to ${targetMajor}.` };
+  }
+  return {
+    ...base,
+    category: 'blocker',
+    reason: `Highest supported is Angular ${maxSupported} — behind even your current Angular ${currentMajor}.`,
+  };
+}
+
+function offlineClassify(base, known, targetMajor, note) {
+  if (known) {
+    if (known.status === 'abandoned') return { ...base, category: 'abandoned', reason: known.reason };
+    if (known.status === 'transitional') return { ...base, category: 'blocker', reason: known.reason };
+    if (known.status === 'maintenance') return { ...base, category: 'upgrade', reason: known.reason };
+  }
+  return {
+    ...base,
+    category: base.angularCoupled ? 'unknown' : 'agnostic',
+    reason: note || 'Offline mode: classified from local knowledge base only.',
+  };
+}
+
+function isStale(dateStr) {
+  if (!dateStr) return false;
+  // Compare year lexically to avoid Date.now(); "2022" vs "2024" style.
+  const year = Number(String(dateStr).slice(0, 4));
+  if (!year) return false;
+  // Reference year derived from the newest Angular EOL data (kept conservative).
+  const referenceYear = 2026;
+  return referenceYear - year >= STALE_YEARS;
+}
+
+function tally(results) {
+  const s = {
+    total: results.length,
+    ok: 0, upgrade: 0, partial: 0, blocker: 0, removed: 0, abandoned: 0, agnostic: 0, unknown: 0,
+    deprecated: 0, stale: 0,
+  };
+  for (const r of results) {
+    s[r.category] = (s[r.category] || 0) + 1;
+    if (r.deprecated) s.deprecated += 1;
+    if (isStale(r.lastPublish)) s.stale += 1;
+  }
+  s.hardBlockers = s.blocker + s.removed;
+  s.needsAttention = s.blocker + s.removed + s.partial + s.abandoned;
+  return s;
+}
+
+const SEVERITY = { removed: 0, blocker: 1, abandoned: 2, partial: 3, unknown: 4, upgrade: 5, agnostic: 6, ok: 7 };
+function sortBySeverity(a, b) {
+  const d = (SEVERITY[a.category] ?? 9) - (SEVERITY[b.category] ?? 9);
+  if (d !== 0) return d;
+  return a.name.localeCompare(b.name);
+}
+
+module.exports = { analyzeDependencies, classifyPackage };

package/src/analyzers/project-snapshot.js

@@ -0,0 +1,124 @@
+'use strict';
+
+const path = require('path');
+const { readJson, exists, safeReadFile } = require('../utils/fs-helpers');
+const semver = require('../utils/semver');
+
+/**
+ * Builds the "what's present" inventory from package.json, the lockfile and
+ * angular.json — no network required.
+ */
+function analyzeSnapshot(projectDir) {
+  const pkg = readJson(path.join(projectDir, 'package.json')) || {};
+  const deps = pkg.dependencies || {};
+  const devDeps = pkg.devDependencies || {};
+  const allDeps = { ...deps, ...devDeps };
+  const names = Object.keys(allDeps);
+
+  const angularPackages = names
+    .filter((n) => n.startsWith('@angular/') || n === '@angular-devkit/build-angular')
+    .sort();
+
+  const thirdPartyAngular = names.filter(
+    (n) => !n.startsWith('@angular/') && /(^@ngrx\/|^ngx-|^ng2-|^angular2?-|^angularx-|-ng2?$)/.test(n)
+  );
+
+  // Package manager + lockfile detection
+  let packageManager = 'unknown';
+  let lockfile = null;
+  let transitiveCount = null;
+  if (exists(path.join(projectDir, 'package-lock.json'))) {
+    packageManager = 'npm';
+    lockfile = 'package-lock.json';
+    const lock = readJson(path.join(projectDir, 'package-lock.json'));
+    if (lock && lock.packages) {
+      transitiveCount = Math.max(0, Object.keys(lock.packages).length - 1);
+    } else if (lock && lock.dependencies) {
+      transitiveCount = Object.keys(lock.dependencies).length;
+    }
+  } else if (exists(path.join(projectDir, 'yarn.lock'))) {
+    packageManager = 'yarn';
+    lockfile = 'yarn.lock';
+    const raw = safeReadFile(path.join(projectDir, 'yarn.lock'));
+    const m = raw.match(/^\S+@/gm);
+    if (m) transitiveCount = m.length;
+  } else if (exists(path.join(projectDir, 'pnpm-lock.yaml'))) {
+    packageManager = 'pnpm';
+    lockfile = 'pnpm-lock.yaml';
+  }
+
+  // Angular version (resolved from lockfile if possible, else from range)
+  const declaredAngular = allDeps['@angular/core'] || null;
+  const angularVersion = resolveInstalledVersion(projectDir, '@angular/core') || (declaredAngular ? semver.coerce(declaredAngular)?.raw : null);
+  const angularMajor = angularVersion ? semver.major(angularVersion) : null;
+
+  const tsVersion = resolveInstalledVersion(projectDir, 'typescript') || (allDeps['typescript'] ? semver.coerce(allDeps['typescript'])?.raw : null);
+
+  // angular.json shape
+  const angularJson = readJson(path.join(projectDir, 'angular.json'));
+  let projectCount = null;
+  let builder = null;
+  let workspaceType = 'single project';
+  if (angularJson && angularJson.projects) {
+    const projNames = Object.keys(angularJson.projects);
+    projectCount = projNames.length;
+    if (projectCount > 1) workspaceType = 'multi-project workspace';
+    const first = angularJson.projects[projNames[0]];
+    builder = first?.architect?.build?.builder || first?.targets?.build?.builder || null;
+  }
+  if (exists(path.join(projectDir, 'nx.json'))) workspaceType = 'Nx monorepo';
+
+  // Test / e2e stack
+  const testRunner = allDeps['jest'] ? 'Jest'
+    : allDeps['karma'] ? 'Karma + Jasmine'
+    : allDeps['@web/test-runner'] ? 'Web Test Runner'
+    : 'unknown';
+  const e2e = allDeps['@playwright/test'] || allDeps['playwright'] ? 'Playwright'
+    : allDeps['cypress'] ? 'Cypress'
+    : allDeps['protractor'] ? 'Protractor (deprecated)'
+    : 'none detected';
+
+  return {
+    name: pkg.name || path.basename(projectDir),
+    prodDependencyCount: Object.keys(deps).length,
+    devDependencyCount: Object.keys(devDeps).length,
+    totalDependencyCount: names.length,
+    transitiveDependencyCount: transitiveCount,
+    angularPackageCount: angularPackages.length,
+    angularPackages,
+    thirdPartyAngularCount: thirdPartyAngular.length,
+    thirdPartyAngular,
+    packageManager,
+    lockfile,
+    angularVersion,
+    angularMajor,
+    declaredAngular,
+    tsVersion,
+    workspaceType,
+    projectCount,
+    builder,
+    testRunner,
+    e2e,
+    allDeps,
+    dependencies: deps,
+    devDependencies: devDeps,
+  };
+}
+
+/** Read the concrete installed version from node_modules or lockfile. */
+function resolveInstalledVersion(projectDir, name) {
+  const pkgJson = readJson(path.join(projectDir, 'node_modules', name, 'package.json'));
+  if (pkgJson && pkgJson.version) return pkgJson.version;
+  const lock = readJson(path.join(projectDir, 'package-lock.json'));
+  if (lock) {
+    if (lock.packages && lock.packages[`node_modules/${name}`]) {
+      return lock.packages[`node_modules/${name}`].version;
+    }
+    if (lock.dependencies && lock.dependencies[name]) {
+      return lock.dependencies[name].version;
+    }
+  }
+  return null;
+}
+
+module.exports = { analyzeSnapshot, resolveInstalledVersion };