ng-upgrade-doctor 0.2.0

package/src/report/terminal.js

@@ -0,0 +1,109 @@
+'use strict';
+
+const { c, write } = require('../utils/log');
+
+const CAT_LABEL = {
+  ok: '🟢 OK', upgrade: '🟡 Upgrade', partial: '🟡 Partial', blocker: '🔴 Blocker',
+  removed: '🔵 Removed', abandoned: '⚫ Abandoned', agnostic: '🟢 Agnostic', unknown: '⚪ Unknown',
+};
+
+function renderTerminal(report) {
+  const { snapshot, versionGap, deps, verdict, census, breakingChanges } = report;
+
+  write('');
+  write(c.bold(c.cyan('  ng-upgrade-doctor')) + c.dim('  · Angular upgrade readiness report'));
+  write(c.dim('  ' + '─'.repeat(56)));
+  write('');
+
+  // Headline
+  const scoreColor = verdict.score >= 80 ? c.green : verdict.score >= 60 ? c.yellow : c.red;
+  write('  ' + c.bold('Project:      ') + snapshot.name);
+  write('  ' + c.bold('Angular:      ') + `${snapshot.angularVersion || '?'}  ` +
+    c.dim(`(${versionGap.known ? versionGap.majorsBehind + ' major(s) behind ' + versionGap.latestStable : 'version unknown'})`));
+  write('  ' + c.bold('Readiness:    ') + scoreColor(c.bold(`${verdict.score}/100`)) + '  ' + c.dim(verdict.bandLabel));
+  write('  ' + c.bold('Effort est.:  ') + `${verdict.effort.lowDays}–${verdict.effort.highDays} person-days` +
+    c.dim(`  (${versionGap.hopCount || 0} hop${versionGap.hopCount === 1 ? '' : 's'})`));
+  write('');
+
+  // Inventory
+  write(c.bold('  Inventory'));
+  line('Dependencies', `${snapshot.totalDependencyCount} (${snapshot.prodDependencyCount} prod / ${snapshot.devDependencyCount} dev)`);
+  if (snapshot.transitiveDependencyCount != null) line('Transitive (lockfile)', String(snapshot.transitiveDependencyCount));
+  line('Angular packages', String(snapshot.angularPackageCount));
+  line('3rd-party Angular libs', String(snapshot.thirdPartyAngularCount));
+  line('Package manager', `${snapshot.packageManager}${snapshot.lockfile ? ' (' + snapshot.lockfile + ')' : ''}`);
+  line('Workspace', `${snapshot.workspaceType}${snapshot.builder ? ' · ' + shortBuilder(snapshot.builder) : ''}`);
+  line('TypeScript', snapshot.tsVersion || 'unknown');
+  line('Test / e2e', `${snapshot.testRunner} / ${snapshot.e2e}`);
+  if (census) {
+    line('Components', `${census.counts.components}  ` + c.dim(`(${census.counts.standaloneComponents} standalone${census.standaloneRatio != null ? ', ' + census.standaloneRatio + '%' : ''})`));
+    line('NgModules / Services', `${census.counts.modules} / ${census.counts.services}`);
+    line('Source files', `${census.fileCounts.tsFiles} ts · ${census.fileCounts.htmlTemplates} html · ${census.fileCounts.specFiles} specs`);
+  }
+  write('');
+
+  // Dependency compatibility
+  const s = deps.summary;
+  write(c.bold(`  Dependency compatibility  `) + c.dim(`(target: Angular ${deps.targetMajor})`));
+  line('Compatible', c.green(`${s.ok + s.agnostic}`), true);
+  line('Needs upgrade / partial', c.yellow(`${s.upgrade + s.partial}`), true);
+  line('Blockers (no compatible release)', c.red(`${s.blocker}`), true);
+  line('Removed / discontinued', c.blue(`${s.removed}`), true);
+  line('Abandoned / unmaintained', c.gray(`${s.abandoned}`), true);
+  if (s.unknown) line('Unknown (offline/not found)', c.dim(`${s.unknown}`), true);
+  write('');
+
+  // Code breaking changes (AST scan)
+  if (breakingChanges && breakingChanges.summary.totalHits > 0) {
+    const b = breakingChanges.summary;
+    write(c.bold('  Code breaking changes  ') + c.dim(`(${breakingChanges.astAvailable ? 'AST' : 'regex fallback'} · ${b.filesAffected} files)`));
+    line('Removed APIs in use', c.red(`${b.removed}`), true);
+    line('Deprecated APIs in use', c.yellow(`${b.deprecated}`), true);
+    line('Modernization opportunities', c.blue(`${b.opportunity}`), true);
+    breakingChanges.rules.slice(0, 6).forEach((r) => {
+      const tag = r.severity === 'removed' ? c.red('removed') : r.severity === 'deprecated' ? c.yellow('deprec.') : c.blue('opportun');
+      write('    ' + tag + ' ' + c.bold(r.title) + c.dim(` ×${r.count} in ${r.fileCount} file(s)`));
+    });
+    write('');
+  }
+
+  // Top blockers
+  if (verdict.blockers.length) {
+    write(c.bold('  Must-fix before upgrading'));
+    verdict.blockers.slice(0, 12).forEach((b) => {
+      write('  ' + c.red('✗ ') + c.bold(b.name) + c.dim(` — ${b.reason}`));
+      if (b.replacement) write('      ' + c.dim('→ ' + b.replacement));
+    });
+    if (verdict.blockers.length > 12) write(c.dim(`    …and ${verdict.blockers.length - 12} more (see full report)`));
+    write('');
+  }
+
+  // Path
+  if (versionGap.known && versionGap.hops.length) {
+    write(c.bold('  Recommended upgrade path'));
+    write('  ' + versionGap.hops.map((h) => c.cyan('v' + h.major)).join(c.dim(' → ')));
+    write('');
+  }
+
+  // Quick wins
+  if (verdict.quickWins.length) {
+    write(c.bold('  Quick wins'));
+    verdict.quickWins.forEach((w) => write('  ' + c.green('•') + ' ' + w));
+    write('');
+  }
+
+  write(c.dim('  ' + '─'.repeat(56)));
+  write('  ' + c.dim('Full HTML & JSON reports written alongside this run. Re-run with --help for options.'));
+  write('');
+}
+
+function line(label, value, indent) {
+  const pad = indent ? '    ' : '    ';
+  process.stdout.write(pad + c.dim((label + ':').padEnd(28)) + ' ' + value + '\n');
+}
+
+function shortBuilder(b) {
+  return b.replace('@angular-devkit/build-angular:', 'devkit:').replace('@angular/build:', 'ng-build:');
+}
+
+module.exports = { renderTerminal, CAT_LABEL };

package/src/utils/fs-helpers.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function readJson(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(raw);
+  } catch (_) {
+    return null;
+  }
+}
+
+function exists(filePath) {
+  try {
+    fs.accessSync(filePath);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+const IGNORE_DIRS = new Set([
+  'node_modules', 'dist', '.git', '.angular', 'coverage', '.nx', 'tmp',
+  'out-tsc', '.cache', 'e2e-results', 'playwright-report', 'test-results',
+]);
+
+/**
+ * Recursively collect files matching one of `extensions` under `root`.
+ * Bounded by `maxFiles` so it stays fast on huge repos.
+ */
+function walkFiles(root, extensions, maxFiles = 20000) {
+  const results = [];
+  const stack = [root];
+  while (stack.length && results.length < maxFiles) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (_) {
+      continue;
+    }
+    for (const entry of entries) {
+      if (results.length >= maxFiles) break;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!IGNORE_DIRS.has(entry.name) && !entry.name.startsWith('.')) {
+          stack.push(full);
+        }
+      } else if (extensions.some((ext) => entry.name.endsWith(ext))) {
+        results.push(full);
+      }
+    }
+  }
+  return results;
+}
+
+function safeReadFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch (_) {
+    return '';
+  }
+}
+
+module.exports = { readJson, exists, walkFiles, safeReadFile };

package/src/utils/log.js

@@ -0,0 +1,34 @@
+'use strict';
+
+/**
+ * Tiny zero-dependency ANSI logging helper. Colors auto-disable when the
+ * output is not a TTY or when NO_COLOR is set.
+ */
+
+const enabled = process.stdout.isTTY && !process.env.NO_COLOR;
+
+const codes = {
+  reset: 0,
+  bold: 1,
+  dim: 2,
+  red: 31,
+  green: 32,
+  yellow: 33,
+  blue: 34,
+  magenta: 35,
+  cyan: 36,
+  gray: 90,
+};
+
+function wrap(name) {
+  return (str) => (enabled ? `[${codes[name]}m${str}` : String(str));
+}
+
+const c = {};
+Object.keys(codes).forEach((k) => (c[k] = wrap(k)));
+
+function write(str = '') {
+  process.stdout.write(str + '\n');
+}
+
+module.exports = { c, write, enabled };

package/src/utils/semver.js

@@ -0,0 +1,208 @@
+'use strict';
+
+/**
+ * Minimal, zero-dependency semver subset.
+ *
+ * Supports the range syntax that actually shows up in npm peerDependencies:
+ *   exact (1.2.3), x-ranges (1.x, 1.2.x, *), caret (^1.2.3), tilde (~1.2.3),
+ *   comparators (>=, >, <=, <, =), hyphen ranges (1.2.3 - 2.3.4),
+ *   AND (space separated) and OR (||) combinations.
+ *
+ * Prerelease handling is intentionally simplified: a prerelease tag makes a
+ * version sort just below its release, which is good enough for classifying
+ * Angular peer-dependency support.
+ */
+
+function parse(version) {
+  if (version == null) return null;
+  const clean = String(version).trim().replace(/^v/, '');
+  const m = clean.match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-.]+))?/);
+  if (!m) return null;
+  return {
+    major: Number(m[1]),
+    minor: Number(m[2]),
+    patch: Number(m[3]),
+    prerelease: m[4] || '',
+    raw: clean,
+  };
+}
+
+/** Pull the first x.y.z out of an arbitrary string (e.g. "~4.9.5" -> 4.9.5). */
+function coerce(str) {
+  if (str == null) return null;
+  const m = String(str).match(/(\d+)\.(\d+)\.(\d+)/) || String(str).match(/(\d+)\.(\d+)/) || String(str).match(/(\d+)/);
+  if (!m) return null;
+  const major = Number(m[1] || 0);
+  const minor = Number(m[2] || 0);
+  const patch = Number(m[3] || 0);
+  return parse(`${major}.${minor}.${patch}`);
+}
+
+function major(version) {
+  const p = parse(version) || coerce(version);
+  return p ? p.major : null;
+}
+
+function compare(a, b) {
+  const pa = parse(a);
+  const pb = parse(b);
+  if (!pa || !pb) return 0;
+  if (pa.major !== pb.major) return pa.major < pb.major ? -1 : 1;
+  if (pa.minor !== pb.minor) return pa.minor < pb.minor ? -1 : 1;
+  if (pa.patch !== pb.patch) return pa.patch < pb.patch ? -1 : 1;
+  // A prerelease is lower than its corresponding release.
+  if (pa.prerelease && !pb.prerelease) return -1;
+  if (!pa.prerelease && pb.prerelease) return 1;
+  if (pa.prerelease === pb.prerelease) return 0;
+  return pa.prerelease < pb.prerelease ? -1 : 1;
+}
+
+const gt = (a, b) => compare(a, b) > 0;
+const gte = (a, b) => compare(a, b) >= 0;
+const lt = (a, b) => compare(a, b) < 0;
+const lte = (a, b) => compare(a, b) <= 0;
+const eq = (a, b) => compare(a, b) === 0;
+
+/** Compare two version strings, treating null/invalid as lowest. Useful for max-by. */
+function maxVersion(list) {
+  return list.filter(Boolean).reduce((best, v) => {
+    if (!best) return v;
+    return gt(v, best) ? v : best;
+  }, null);
+}
+
+// ---- Range parsing -------------------------------------------------------
+
+function xToZero(part) {
+  return part === undefined || part === '' || part === 'x' || part === 'X' || part === '*'
+    ? 0
+    : Number(part);
+}
+
+/** Expand a single simple range token into a list of {op, version} comparators. */
+function expandToken(token) {
+  token = token.trim();
+  if (token === '' || token === '*' || token === 'x' || token === 'X' || token === 'latest') {
+    return [{ op: '>=', version: '0.0.0' }];
+  }
+
+  // Caret: ^1.2.3
+  if (token.startsWith('^')) {
+    const [maj, min, pat] = token.slice(1).split('.');
+    const M = xToZero(maj), m = xToZero(min), p = xToZero(pat);
+    let upper;
+    if (M > 0 || maj === undefined) upper = `${M + 1}.0.0`;
+    else if (m > 0 || min === undefined || min === 'x') upper = `0.${m + 1}.0`;
+    else upper = `0.0.${p + 1}`;
+    return [{ op: '>=', version: `${M}.${m}.${p}` }, { op: '<', version: upper }];
+  }
+
+  // Tilde: ~1.2.3
+  if (token.startsWith('~')) {
+    const [maj, min, pat] = token.slice(1).split('.');
+    const M = xToZero(maj), m = xToZero(min), p = xToZero(pat);
+    const hasMinor = min !== undefined && min !== '' && min !== 'x' && min !== 'X';
+    const upper = hasMinor ? `${M}.${m + 1}.0` : `${M + 1}.0.0`;
+    return [{ op: '>=', version: `${M}.${m}.${p}` }, { op: '<', version: upper }];
+  }
+
+  // Comparators: >=, >, <=, <, =
+  const cmp = token.match(/^(>=|<=|>|<|=)\s*(.+)$/);
+  if (cmp) {
+    const c = coerce(cmp[2]);
+    return [{ op: cmp[1], version: c ? c.raw : '0.0.0' }];
+  }
+
+  // X-range or exact: 1, 1.2, 1.2.3, 1.x, 1.2.x
+  const parts = token.split('.');
+  const majX = parts[0];
+  const minX = parts[1];
+  const patX = parts[2];
+  const majWild = majX === undefined || majX === 'x' || majX === 'X' || majX === '*';
+  const minWild = minX === undefined || minX === 'x' || minX === 'X' || minX === '*';
+  const patWild = patX === undefined || patX === 'x' || patX === 'X' || patX === '*';
+
+  if (majWild) return [{ op: '>=', version: '0.0.0' }];
+  const M = Number(majX);
+  if (minWild) {
+    return [{ op: '>=', version: `${M}.0.0` }, { op: '<', version: `${M + 1}.0.0` }];
+  }
+  const m = Number(minX);
+  if (patWild) {
+    return [{ op: '>=', version: `${M}.${m}.0` }, { op: '<', version: `${M}.${m + 1}.0` }];
+  }
+  return [{ op: '=', version: `${M}.${m}.${Number(patX)}` }];
+}
+
+function testComparator(version, { op, version: target }) {
+  switch (op) {
+    case '>=': return gte(version, target);
+    case '>': return gt(version, target);
+    case '<=': return lte(version, target);
+    case '<': return lt(version, target);
+    case '=': return eq(version, target);
+    default: return false;
+  }
+}
+
+/** Split an AND-group into comparators, handling hyphen ranges. */
+function groupComparators(group) {
+  const tokens = group.trim().split(/\s+/).filter(Boolean);
+  // Hyphen range: a - b
+  const hyphenIdx = tokens.indexOf('-');
+  if (hyphenIdx > 0 && tokens[hyphenIdx + 1]) {
+    const lower = coerce(tokens[hyphenIdx - 1]);
+    const upperToken = tokens[hyphenIdx + 1];
+    const up = upperToken.split('.');
+    let upperCmp;
+    if (up[1] === undefined) upperCmp = { op: '<', version: `${Number(up[0]) + 1}.0.0` };
+    else if (up[2] === undefined) upperCmp = { op: '<', version: `${Number(up[0])}.${Number(up[1]) + 1}.0` };
+    else upperCmp = { op: '<=', version: coerce(upperToken).raw };
+    return [{ op: '>=', version: lower ? lower.raw : '0.0.0' }, upperCmp];
+  }
+  return tokens.flatMap(expandToken);
+}
+
+/** Does `version` satisfy `range`? */
+function satisfies(version, range) {
+  const v = parse(version);
+  if (!v) return false;
+  if (range == null || range === '' || range === '*' || range === 'latest') return true;
+  const orGroups = String(range).split('||');
+  return orGroups.some((group) => {
+    const comparators = groupComparators(group);
+    return comparators.every((c) => testComparator(v.raw, c));
+  });
+}
+
+/**
+ * Given a peerDependency range on @angular/core (e.g. "^15.0.0 || ^16.0.0"),
+ * return the highest Angular major that it accepts, scanning a sane window.
+ */
+function highestSupportedMajor(range, minMajor = 2, maxMajor = 40) {
+  if (!range) return null;
+  let best = null;
+  for (let M = minMajor; M <= maxMajor; M++) {
+    // Probe both the low and high end of the major so ranges like "^15.2.0"
+    // (which excludes 15.0.0) and "<15.2.0" are both handled.
+    if (satisfies(`${M}.0.0`, range) || satisfies(`${M}.99.99`, range)) {
+      best = M;
+    }
+  }
+  return best;
+}
+
+module.exports = {
+  parse,
+  coerce,
+  major,
+  compare,
+  gt,
+  gte,
+  lt,
+  lte,
+  eq,
+  maxVersion,
+  satisfies,
+  highestSupportedMajor,
+};