ng-upgrade-doctor 0.2.0

package/src/analyzers/verdict.js

@@ -0,0 +1,118 @@
+'use strict';
+
+/**
+ * Blends the analyses into a single 0–100 Upgrade Readiness Score, an effort
+ * band, and a prioritized, deduped action list. The score is intentionally
+ * transparent: every deduction is itemized so the number is auditable.
+ */
+function computeVerdict({ snapshot, versionGap, deps, census, breakingChanges }) {
+  const deductions = [];
+  let score = 100;
+
+  const add = (points, label) => {
+    if (points <= 0) return;
+    score -= points;
+    deductions.push({ points, label });
+  };
+
+  // Version distance
+  if (versionGap.known && versionGap.majorsBehind > 0) {
+    add(Math.min(40, versionGap.majorsBehind * 8), `${versionGap.majorsBehind} major version(s) behind latest`);
+  }
+
+  // EOL / unsupported current version
+  if (versionGap.known && versionGap.eol && versionGap.eol < '2026-07') {
+    add(12, `Angular ${versionGap.currentMajor} is past its support window (~${versionGap.eol})`);
+  }
+
+  // Dependency risk
+  const s = deps.summary;
+  add(Math.min(30, s.blocker * 5), `${s.blocker} dependency blocker(s) with no compatible release`);
+  add(Math.min(20, s.removed * 4), `${s.removed} package(s) removed/discontinued from Angular`);
+  add(Math.min(12, s.abandoned * 2), `${s.abandoned} abandoned/unmaintained package(s)`);
+  add(Math.min(8, s.partial * 1), `${s.partial} package(s) only partially compatible`);
+  add(Math.min(6, s.deprecated * 1), `${s.deprecated} package(s) marked deprecated on npm`);
+
+  // Code signals — prefer the richer AST breaking-change scan when present.
+  if (breakingChanges && breakingChanges.summary) {
+    const bc = breakingChanges.summary;
+    add(Math.min(14, bc.removed * 1), `${bc.removed} removed-API usage(s) in source (${breakingChanges.summary.filesAffected} files affected)`);
+    add(Math.min(6, bc.deprecated * 0.5), `${bc.deprecated} deprecated-API usage(s) in source`);
+  } else {
+    const sig = census ? census.signals : {};
+    add(Math.min(6, (sig.rxjsCompatImports || 0) * 2), `rxjs-compat still imported in ${sig.rxjsCompatImports || 0} place(s)`);
+    add(Math.min(4, (sig.entryComponents || 0) * 1), `entryComponents used in ${sig.entryComponents || 0} place(s) (removed API)`);
+    add(Math.min(3, (sig.legacyRxjsAddImports || 0) * 1), `legacy rxjs/add imports in ${sig.legacyRxjsAddImports || 0} place(s)`);
+  }
+
+  // Floor at 5 rather than 0 so the number stays informative even for repos
+  // that are very far behind (a hard 0 can't distinguish "bad" from "worse").
+  const SCORE_FLOOR = 5;
+  score = Math.max(SCORE_FLOOR, Math.round(score));
+
+  let band, bandLabel;
+  if (score >= 80) { band = 'healthy'; bandLabel = 'Healthy — low-risk upgrade'; }
+  else if (score >= 60) { band = 'moderate'; bandLabel = 'Moderate — plan a focused effort'; }
+  else if (score >= 40) { band = 'significant'; bandLabel = 'Significant — clear blockers first'; }
+  else { band = 'major'; bandLabel = 'Major — treat as a dedicated project'; }
+
+  // Rough effort band (person-days), deliberately a range not a false-precise number.
+  const hops = versionGap.known ? versionGap.hopCount : 0;
+  const effortLow = hops * 2 + s.blocker * 1 + s.removed * 1 + s.partial * 0.5;
+  const effortHigh = hops * 4 + s.blocker * 3 + s.removed * 2 + s.partial * 1 + s.abandoned * 1;
+  const effort = {
+    lowDays: Math.max(1, Math.round(effortLow)),
+    highDays: Math.max(2, Math.round(effortHigh)),
+  };
+
+  return {
+    score,
+    band,
+    bandLabel,
+    deductions: deductions.sort((a, b) => b.points - a.points),
+    effort,
+    blockers: buildBlockerList(deps),
+    quickWins: buildQuickWins(deps, census, versionGap, breakingChanges),
+  };
+}
+
+function buildBlockerList(deps) {
+  return deps.packages
+    .filter((p) => p.category === 'blocker' || p.category === 'removed')
+    .map((p) => ({
+      name: p.name,
+      category: p.category,
+      reason: p.reason,
+      replacement: p.replacement,
+      supports: p.maxAngularSupported,
+    }));
+}
+
+function buildQuickWins(deps, census, versionGap, breakingChanges) {
+  const wins = [];
+  const removedTooling = deps.packages.filter((p) => p.category === 'removed');
+  if (removedTooling.length) {
+    wins.push(`Replace removed tooling first: ${removedTooling.map((p) => p.name).join(', ')}.`);
+  }
+  // Auto-fixable code migrations worth calling out.
+  if (breakingChanges && breakingChanges.rules) {
+    const byId = Object.fromEntries(breakingChanges.rules.map((r) => [r.id, r]));
+    if (byId['entry-components']) wins.push(`Remove entryComponents (${byId['entry-components'].count} usage(s)) — no longer needed under Ivy.`);
+    if (byId['rxjs-compat-import']) wins.push('Finish the RxJS 7 migration and drop rxjs-compat.');
+    if (byId['testbed-get']) wins.push(`Swap TestBed.get() → TestBed.inject() (${byId['testbed-get'].count} usage(s)).`);
+    const cf = ['cf-ngif', 'cf-ngfor', 'cf-ngswitch'].reduce((n, id) => n + (byId[id] ? byId[id].count : 0), 0);
+    if (cf > 0) wins.push(`After reaching v17+, run the control-flow schematic to modernize ${cf} *ngIf/*ngFor/*ngSwitch usage(s).`);
+  } else if (census && census.signals.rxjsCompatImports > 0) {
+    wins.push('Finish the RxJS 7 migration and drop rxjs-compat.');
+  }
+  const abandoned = deps.packages.filter((p) => p.category === 'abandoned');
+  if (abandoned.length) {
+    wins.push(`Audit ${abandoned.length} unmaintained package(s) for replacement before upgrading.`);
+  }
+  if (versionGap.known && versionGap.hopCount > 1) {
+    wins.push(`Upgrade one major at a time via ng update (${versionGap.hopCount} hops), running tests between each.`);
+  }
+  return wins;
+}
+
+module.exports = { computeVerdict };

package/src/analyzers/version-gap.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const { LATEST_STABLE, getVersionInfo, upgradePath } = require('../data/angular-versions');
+
+/**
+ * Where the project stands relative to the latest Angular, the support status
+ * of the current version, and the hop-by-hop path to the target.
+ */
+function analyzeVersionGap(currentMajor, targetMajor = LATEST_STABLE) {
+  if (!currentMajor) {
+    return { known: false, message: 'Could not determine the current Angular version.' };
+  }
+
+  const majorsBehind = Math.max(0, targetMajor - currentMajor);
+  const currentInfo = getVersionInfo(currentMajor);
+  const targetInfo = getVersionInfo(targetMajor);
+  const path = upgradePath(currentMajor, targetMajor);
+
+  // Rough EOL assessment against a reference "now". We can't call Date.now()
+  // in some sandboxes, but comparing YYYY-MM strings lexically is fine.
+  const eol = currentInfo ? currentInfo.eol : null;
+
+  return {
+    known: true,
+    currentMajor,
+    targetMajor,
+    majorsBehind,
+    latestStable: LATEST_STABLE,
+    isLatest: majorsBehind === 0,
+    currentInfo,
+    targetInfo,
+    eol,
+    hops: path,
+    hopCount: path.length,
+  };
+}
+
+module.exports = { analyzeVersionGap };

package/src/ast/loader.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const path = require('path');
+
+/**
+ * Zero-dependency trick: the tool ships no parser. Instead we borrow the
+ * TypeScript compiler (and, when present, @angular/compiler) from the *target*
+ * project's own node_modules — every Angular repo already has them. If they
+ * can't be resolved, callers fall back to a regex scan.
+ */
+function loadTypeScript(projectDir) {
+  const candidates = [projectDir, path.join(projectDir, 'node_modules')];
+  // 1) Resolve relative to the project (handles hoisting, workspaces, pnpm).
+  try {
+    const resolved = require.resolve('typescript', { paths: candidates });
+    return { ts: require(resolved), source: resolved };
+  } catch (_) {
+    /* fall through */
+  }
+  // 2) Last resort: whatever TypeScript the tool itself might see (usually none).
+  try {
+    return { ts: require('typescript'), source: 'tool' };
+  } catch (_) {
+    return { ts: null, source: null };
+  }
+}
+
+function loadAngularCompiler(projectDir) {
+  const candidates = [projectDir, path.join(projectDir, 'node_modules')];
+  try {
+    const resolved = require.resolve('@angular/compiler', { paths: candidates });
+    return { compiler: require(resolved), source: resolved };
+  } catch (_) {
+    return { compiler: null, source: null };
+  }
+}
+
+module.exports = { loadTypeScript, loadAngularCompiler };

package/src/ast/regex-scanner.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const path = require('path');
+const { safeReadFile } = require('../utils/fs-helpers');
+
+/**
+ * Line-by-line regex scanner. Used for:
+ *   - HTML template rules (no AST available for templates in this MVP)
+ *   - a graceful fallback for TS rules when the TypeScript compiler can't be
+ *     borrowed from the target project.
+ *
+ * Each rule must carry a `regex`. Findings: { ruleId, file, line, col }.
+ */
+function scanWithRegex(files, rules, projectDir, onProgress) {
+  const findings = [];
+  files.forEach((file, i) => {
+    const content = safeReadFile(file);
+    if (content) {
+      const rel = path.relative(projectDir, file);
+      const lines = content.split(/\r?\n/);
+      for (const rule of rules) {
+        if (!rule.regex) continue;
+        // Use a fresh, global-flagged clone so we can find every hit per line.
+        const re = new RegExp(rule.regex.source, rule.regex.flags.includes('g') ? rule.regex.flags : rule.regex.flags + 'g');
+        for (let ln = 0; ln < lines.length; ln++) {
+          const line = lines[ln];
+          if (isLikelyComment(line)) continue;
+          re.lastIndex = 0;
+          let m;
+          while ((m = re.exec(line)) !== null) {
+            findings.push({ ruleId: rule.id, file: rel, line: ln + 1, col: m.index + 1 });
+            if (m.index === re.lastIndex) re.lastIndex++; // avoid zero-width loop
+          }
+        }
+      }
+    }
+    if (onProgress) onProgress(i + 1, files.length);
+  });
+  return findings;
+}
+
+function isLikelyComment(line) {
+  const t = line.trim();
+  return t.startsWith('//') || t.startsWith('*') || t.startsWith('<!--');
+}
+
+module.exports = { scanWithRegex };

package/src/ast/ts-scanner.js

@@ -0,0 +1,154 @@
+'use strict';
+
+const path = require('path');
+const { safeReadFile } = require('../utils/fs-helpers');
+
+/**
+ * Walk each TypeScript file's AST and match nodes against the rulebook.
+ * Matcher types supported: import, property, propertyAccess, call, identifier.
+ * Returns a flat list of findings: { ruleId, file, line, col }.
+ */
+function scanTsFiles(ts, files, rules, projectDir, onProgress) {
+  const byType = groupBy(rules, (r) => r.match.type);
+  const findings = [];
+
+  files.forEach((file, i) => {
+    const content = safeReadFile(file);
+    if (content) {
+      let sf;
+      try {
+        sf = ts.createSourceFile(file, content, ts.ScriptTarget.Latest, /*setParentNodes*/ true);
+      } catch (_) {
+        sf = null;
+      }
+      if (sf) scanSourceFile(ts, sf, file, byType, projectDir, findings);
+    }
+    if (onProgress) onProgress(i + 1, files.length);
+  });
+
+  return findings;
+}
+
+function scanSourceFile(ts, sf, file, byType, projectDir, findings) {
+  const rel = path.relative(projectDir, file);
+  const record = (rule, node) => {
+    let pos;
+    try {
+      pos = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+    } catch (_) {
+      pos = { line: 0, character: 0 };
+    }
+    findings.push({ ruleId: rule.id, file: rel, line: pos.line + 1, col: pos.character + 1 });
+  };
+
+  const importRules = byType.import || [];
+  const propRules = byType.property || [];
+  const paRules = byType.propertyAccess || [];
+  const callRules = byType.call || [];
+  const idRules = byType.identifier || [];
+
+  const visit = (node) => {
+    // import ... from 'module'
+    if (ts.isImportDeclaration(node) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+      const mod = node.moduleSpecifier.text;
+      const named = getNamedImports(ts, node);
+      for (const r of importRules) {
+        if (!moduleMatches(mod, r.match.module)) continue;
+        if (r.match.named && !r.match.named.some((n) => named.includes(n))) continue;
+        record(r, node);
+      }
+    }
+
+    // { key: value } object literal property
+    if (ts.isPropertyAssignment(node) && node.name) {
+      const name = safeText(ts, node.name, sf);
+      for (const r of propRules) {
+        if (name !== r.match.name) continue;
+        if (r.match.valueContains) {
+          const init = node.initializer ? safeText(ts, node.initializer, sf) : '';
+          if (!init.includes(r.match.valueContains)) continue;
+        }
+        record(r, node);
+      }
+    }
+
+    // Foo.Bar member access
+    if (ts.isPropertyAccessExpression(node)) {
+      const object = safeText(ts, node.expression, sf);
+      const name = safeText(ts, node.name, sf);
+      for (const r of paRules) {
+        if (r.match.object === object && r.match.name === name) record(r, node);
+      }
+    }
+
+    // callee(...) or object.callee(...)
+    if (ts.isCallExpression(node)) {
+      const expr = node.expression;
+      let callee = null;
+      let object = null;
+      if (ts.isPropertyAccessExpression(expr)) {
+        callee = safeText(ts, expr.name, sf);
+        object = safeText(ts, expr.expression, sf);
+      } else if (ts.isIdentifier(expr)) {
+        callee = safeText(ts, expr, sf);
+      }
+      for (const r of callRules) {
+        if (r.match.callee !== callee) continue;
+        if (r.match.object && r.match.object !== object) continue;
+        if (r.match.firstArgFunction) {
+          const arg0 = node.arguments && node.arguments[0];
+          if (!arg0 || !(ts.isArrowFunction(arg0) || ts.isFunctionExpression(arg0))) continue;
+        }
+        record(r, node);
+      }
+    }
+
+    // bare identifier usage (distinctive names only — see rulebook)
+    if (idRules.length && ts.isIdentifier(node)) {
+      const name = node.escapedText ? String(node.escapedText) : safeText(ts, node, sf);
+      for (const r of idRules) {
+        if (name === r.match.name) record(r, node);
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  };
+
+  visit(sf);
+}
+
+function getNamedImports(ts, importDecl) {
+  const names = [];
+  const clause = importDecl.importClause;
+  if (!clause) return names;
+  if (clause.name) names.push(String(clause.name.escapedText || ''));
+  const bindings = clause.namedBindings;
+  if (bindings && ts.isNamedImports(bindings)) {
+    bindings.elements.forEach((el) => names.push(String((el.name && el.name.escapedText) || '')));
+  }
+  return names;
+}
+
+function moduleMatches(mod, matcher) {
+  if (matcher instanceof RegExp) return matcher.test(mod);
+  return mod === matcher;
+}
+
+function safeText(ts, node, sf) {
+  try {
+    return node.getText(sf);
+  } catch (_) {
+    return '';
+  }
+}
+
+function groupBy(arr, keyFn) {
+  const out = {};
+  for (const item of arr) {
+    const k = keyFn(item);
+    (out[k] = out[k] || []).push(item);
+  }
+  return out;
+}
+
+module.exports = { scanTsFiles };

package/src/cli.js

@@ -0,0 +1,73 @@
+'use strict';
+
+const { run, TOOL_VERSION } = require('./index');
+const { write, c } = require('./utils/log');
+
+const HELP = `
+  ng-upgrade-doctor v${TOOL_VERSION}
+  Zero-dependency Angular upgrade readiness & blast-radius diagnostic.
+
+  USAGE
+    npx ng-upgrade-doctor [path] [options]
+
+  ARGUMENTS
+    path                 Path to the Angular project (default: current directory)
+
+  OPTIONS
+    --target <major>     Target Angular major to assess against (default: latest known)
+    --offline            Skip the npm registry; classify from the local knowledge base only
+    --no-code            Skip the source-tree census (faster; deps only)
+    --out <dir>          Directory to write HTML/JSON reports (default: project dir)
+    --concurrency <n>    Parallel registry lookups (default: 8)
+    --ci                 CI mode: exit 1 if hard blockers exist or score < --min-score
+    --min-score <n>      Minimum readiness score for --ci to pass (default: 0)
+    --quiet              Suppress progress output
+    -h, --help           Show this help
+    -v, --version        Show version
+
+  EXAMPLES
+    npx ng-upgrade-doctor
+    npx ng-upgrade-doctor ./apps/web --target 18
+    npx ng-upgrade-doctor --ci --min-score 60
+`;
+
+function parseArgs(argv) {
+  const opts = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case '-h': case '--help': opts.help = true; break;
+      case '-v': case '--version': opts.version = true; break;
+      case '--offline': opts.offline = true; break;
+      case '--no-code': opts.noCode = true; break;
+      case '--ci': opts.ci = true; break;
+      case '--quiet': opts.quiet = true; break;
+      case '--target': opts.target = Number(argv[++i]); break;
+      case '--out': opts.out = argv[++i]; break;
+      case '--concurrency': opts.concurrency = Number(argv[++i]); break;
+      case '--min-score': opts.minScore = Number(argv[++i]); break;
+      default:
+        if (a.startsWith('--target=')) opts.target = Number(a.split('=')[1]);
+        else if (a.startsWith('--out=')) opts.out = a.split('=')[1];
+        else if (a.startsWith('-')) { write(c.yellow(`  Unknown option: ${a}`)); }
+        else positional.push(a);
+    }
+  }
+  if (positional[0]) opts.projectDir = positional[0];
+  return opts;
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) { write(HELP); return; }
+  if (opts.version) { write(TOOL_VERSION); return; }
+  try {
+    await run(opts);
+  } catch (e) {
+    write(c.red('  ✗ ng-upgrade-doctor failed: ' + (e && e.stack ? e.stack : e)));
+    process.exitCode = 2;
+  }
+}
+
+module.exports = { main, parseArgs };

package/src/data/angular-versions.js

@@ -0,0 +1,83 @@
+'use strict';
+
+/**
+ * Angular release reference data — the maintainable "rulebook".
+ *
+ * This is deliberately plain data so it can be updated each Angular release
+ * without touching engine code. `eol` dates are approximate (Angular gives
+ * each major ~6 months active + 12 months LTS). `latestStable` should be
+ * bumped when a new major ships.
+ *
+ * Fields per major:
+ *   node   - supported Node.js ranges (human readable)
+ *   ts     - supported TypeScript range
+ *   rxjs   - supported RxJS range
+ *   zone   - zone.js range (null once zoneless is the norm for that line)
+ *   eol    - approximate end-of-life (YYYY-MM) for the LTS window
+ *   notes  - headline breaking changes / themes for the release
+ */
+
+const LATEST_STABLE = 20;
+
+const VERSIONS = {
+  12: {
+    node: '12.14 / 14.15+', ts: '4.2 – 4.3', rxjs: '6.5 / 7.x', zone: '~0.11',
+    eol: '2022-11',
+    notes: ['Ivy-only libraries', 'IE11 deprecated', 'Nullish coalescing in templates'],
+  },
+  13: {
+    node: '12.20 / 14.15 / 16.10', ts: '4.4 – 4.5', rxjs: '6.5 / 7.4+', zone: '~0.11',
+    eol: '2023-05',
+    notes: ['View Engine removed (Ivy only)', 'IE11 support removed', 'Dynamic component API simplified'],
+  },
+  14: {
+    node: '14.15 / 16.10', ts: '4.6 – 4.8', rxjs: '6.5 / 7.x', zone: '~0.11',
+    eol: '2023-11',
+    notes: ['Standalone components (preview)', 'Typed reactive forms', 'CLI autocompletion'],
+  },
+  15: {
+    node: '14.20 / 16.13 / 18.10', ts: '4.8 – 4.9', rxjs: '6.5 / 7.x', zone: '~0.11',
+    eol: '2024-05',
+    notes: ['Standalone APIs stable', 'MDC-based Angular Material', 'Directive composition API', 'enableIvy removed'],
+  },
+  16: {
+    node: '16.14 / 18.10', ts: '>=4.9.3 <5.2', rxjs: '6.x / 7.x', zone: '~0.13',
+    eol: '2024-11',
+    notes: ['Signals (developer preview)', 'Required inputs', 'esbuild dev-server (preview)', 'entryComponents removed', 'Standalone ng new'],
+  },
+  17: {
+    node: '18.13 / 20.9', ts: '>=5.2 <5.5', rxjs: '6.x / 7.x', zone: '~0.14',
+    eol: '2025-05',
+    notes: ['New control flow @if/@for/@switch', 'Deferrable views', 'esbuild + Vite default build', 'New brand / angular.dev', 'View transitions'],
+  },
+  18: {
+    node: '18.19 / 20.11 / 22', ts: '>=5.4 <5.6', rxjs: '6.x / 7.x', zone: '~0.14 (optional)',
+    eol: '2025-11',
+    notes: ['Zoneless change detection (preview)', 'Control flow stable', 'Material 3 stable', 'Event replay for SSR'],
+  },
+  19: {
+    node: '18.19 / 20.11 / 22', ts: '>=5.5 <5.7', rxjs: '6.x / 7.x', zone: '~0.15 (optional)',
+    eol: '2026-05',
+    notes: ['Standalone by default', 'Incremental hydration', 'linkedSignal & resource APIs', 'Hot module replacement'],
+  },
+  20: {
+    node: '20.11 / 22 / 24', ts: '>=5.8 <5.9', rxjs: '7.x', zone: 'optional (zoneless stable path)',
+    eol: '2026-11',
+    notes: ['Signals stable', 'Zoneless developer preview → stable path', 'Several long-deprecated APIs removed', 'Style/template diagnostics'],
+  },
+};
+
+function getVersionInfo(major) {
+  return VERSIONS[major] || null;
+}
+
+/** Build the ordered hop path from `from` to `to` (exclusive of `from`). */
+function upgradePath(from, to) {
+  const path = [];
+  for (let v = from + 1; v <= to; v++) {
+    if (VERSIONS[v]) path.push({ major: v, ...VERSIONS[v] });
+  }
+  return path;
+}
+
+module.exports = { LATEST_STABLE, VERSIONS, getVersionInfo, upgradePath };