ng-upgrade-doctor 0.2.0

package/src/data/breaking-changes.js

@@ -0,0 +1,223 @@
+'use strict';
+
+/**
+ * Versioned rulebook of Angular / RxJS breaking changes and migration
+ * opportunities, detectable from source code.
+ *
+ * Each rule:
+ *   id       - stable slug
+ *   title    - short human label
+ *   severity - 'removed' (hard break) | 'deprecated' (soft) | 'opportunity' (modernization)
+ *   since    - Angular major that introduced the change (informational)
+ *   scope    - 'ts' (TypeScript AST) | 'template' (HTML)
+ *   match    - matcher spec for the AST scanner (ts scope) — see ts-scanner.js
+ *   regex    - fallback line regex used when the AST parser isn't available,
+ *              and the primary matcher for 'template' scope
+ *   message  - what/why
+ *   fix      - recommended migration
+ *   docs     - reference URL
+ */
+
+const TS_RULES = [
+  {
+    id: 'entry-components',
+    title: 'entryComponents removed',
+    severity: 'removed', since: 13, scope: 'ts',
+    match: { type: 'property', name: 'entryComponents' },
+    regex: /\bentryComponents\s*:/,
+    message: 'entryComponents is obsolete under Ivy and was removed from @NgModule.',
+    fix: 'Delete entryComponents arrays; components can be created dynamically without them.',
+    docs: 'https://angular.dev/reference/migrations',
+  },
+  {
+    id: 'angular-http',
+    title: '@angular/http removed',
+    severity: 'removed', since: 8, scope: 'ts',
+    match: { type: 'import', module: '@angular/http' },
+    regex: /from\s+['"]@angular\/http['"]/,
+    message: 'The legacy @angular/http package was removed.',
+    fix: 'Use HttpClient from @angular/common/http.',
+    docs: 'https://angular.dev/guide/http',
+  },
+  {
+    id: 'rxjs-add-imports',
+    title: 'RxJS patch imports (rxjs/add) removed',
+    severity: 'removed', since: 15, scope: 'ts',
+    match: { type: 'import', module: /^rxjs\/add\// },
+    regex: /from\s+['"]rxjs\/add\//,
+    message: 'RxJS 5 “patch” imports (rxjs/add/operator/*) were removed in RxJS 6+.',
+    fix: 'Import operators from "rxjs" / "rxjs/operators" and use pipe().',
+    docs: 'https://rxjs.dev/deprecations/breaking-changes',
+  },
+  {
+    id: 'rxjs-deep-imports',
+    title: 'RxJS deep type imports removed',
+    severity: 'removed', since: 15, scope: 'ts',
+    match: { type: 'import', module: /^rxjs\/(Observable|Subject|BehaviorSubject|ReplaySubject|Subscription|Observer)$/ },
+    regex: /from\s+['"]rxjs\/(Observable|Subject|BehaviorSubject|ReplaySubject|Subscription|Observer)['"]/,
+    message: 'RxJS 5 deep imports (e.g. rxjs/Observable) were removed.',
+    fix: 'Import from the "rxjs" root barrel instead.',
+    docs: 'https://rxjs.dev/deprecations/breaking-changes',
+  },
+  {
+    id: 'rxjs-compat-import',
+    title: 'rxjs-compat still imported',
+    severity: 'removed', since: 15, scope: 'ts',
+    match: { type: 'import', module: /^rxjs-compat/ },
+    regex: /from\s+['"]rxjs-compat/,
+    message: 'rxjs-compat is a temporary migration shim and cannot remain.',
+    fix: 'Finish the RxJS 7 migration and remove rxjs-compat.',
+    docs: 'https://rxjs.dev/deprecations/breaking-changes',
+  },
+  {
+    id: 'material-barrel-import',
+    title: '@angular/material barrel import removed',
+    severity: 'removed', since: 9, scope: 'ts',
+    match: { type: 'import', module: '@angular/material' },
+    regex: /from\s+['"]@angular\/material['"]/,
+    message: 'Importing from the @angular/material barrel was removed; use secondary entry points.',
+    fix: 'Import from the specific entry point, e.g. @angular/material/button.',
+    docs: 'https://material.angular.io',
+  },
+  {
+    id: 'renderer-v1',
+    title: 'Renderer (v1) removed',
+    severity: 'removed', since: 9, scope: 'ts',
+    match: { type: 'import', module: '@angular/core', named: ['Renderer'] },
+    regex: /\bRenderer\b(?!2)/,
+    message: 'The original Renderer was removed.',
+    fix: 'Use Renderer2 from @angular/core.',
+    docs: 'https://angular.dev/api/core/Renderer2',
+  },
+  {
+    id: 'view-encapsulation-native',
+    title: 'ViewEncapsulation.Native removed',
+    severity: 'removed', since: 9, scope: 'ts',
+    match: { type: 'propertyAccess', object: 'ViewEncapsulation', name: 'Native' },
+    regex: /ViewEncapsulation\s*\.\s*Native\b/,
+    message: 'ViewEncapsulation.Native was removed.',
+    fix: 'Use ViewEncapsulation.ShadowDom.',
+    docs: 'https://angular.dev/api/core/ViewEncapsulation',
+  },
+  {
+    id: 'reflective-injector',
+    title: 'ReflectiveInjector removed',
+    severity: 'removed', since: 13, scope: 'ts',
+    match: { type: 'identifier', name: 'ReflectiveInjector' },
+    regex: /\bReflectiveInjector\b/,
+    message: 'ReflectiveInjector was removed.',
+    fix: 'Use Injector.create({ providers }).',
+    docs: 'https://angular.dev/api/core/Injector',
+  },
+  {
+    id: 'wrapped-value',
+    title: 'WrappedValue removed',
+    severity: 'removed', since: 13, scope: 'ts',
+    match: { type: 'identifier', name: 'WrappedValue' },
+    regex: /\bWrappedValue\b/,
+    message: 'WrappedValue was removed; pipes should return new references to signal change.',
+    fix: 'Return a new object/array reference instead of wrapping values.',
+    docs: 'https://angular.dev/reference/migrations',
+  },
+  {
+    id: 'router-preserve-query-params',
+    title: 'preserveQueryParams removed',
+    severity: 'removed', since: 7, scope: 'ts',
+    match: { type: 'property', name: 'preserveQueryParams' },
+    regex: /\bpreserveQueryParams\s*:/,
+    message: 'Router option preserveQueryParams was removed.',
+    fix: "Use queryParamsHandling: 'preserve'.",
+    docs: 'https://angular.dev/api/router/NavigationExtras',
+  },
+  {
+    id: 'loadchildren-string',
+    title: 'String loadChildren removed',
+    severity: 'removed', since: 9, scope: 'ts',
+    match: { type: 'property', name: 'loadChildren', valueContains: '#' },
+    regex: /loadChildren\s*:\s*['"][^'"]*#[^'"]*['"]/,
+    message: 'The "path#ModuleName" string form of loadChildren was removed.',
+    fix: 'Use a dynamic import: loadChildren: () => import("./x").then(m => m.XModule).',
+    docs: 'https://angular.dev/guide/routing/common-router-tasks',
+  },
+  {
+    id: 'testbed-get',
+    title: 'TestBed.get() deprecated',
+    severity: 'deprecated', since: 9, scope: 'ts',
+    match: { type: 'call', object: 'TestBed', callee: 'get' },
+    regex: /TestBed\s*\.\s*get\s*\(/,
+    message: 'TestBed.get() is deprecated and type-unsafe.',
+    fix: 'Use TestBed.inject().',
+    docs: 'https://angular.dev/api/core/testing/TestBed',
+  },
+  {
+    id: 'rxjs-to-promise',
+    title: '.toPromise() deprecated',
+    severity: 'deprecated', since: 15, scope: 'ts',
+    match: { type: 'call', callee: 'toPromise' },
+    regex: /\.\s*toPromise\s*\(/,
+    message: 'Observable.toPromise() is deprecated in RxJS 7 and removed in RxJS 8.',
+    fix: 'Use firstValueFrom() or lastValueFrom().',
+    docs: 'https://rxjs.dev/deprecations/to-promise',
+  },
+  {
+    id: 'test-async-helper',
+    title: 'async() test helper renamed',
+    severity: 'deprecated', since: 10, scope: 'ts',
+    match: { type: 'call', callee: 'async', firstArgFunction: true },
+    regex: /(?<![.\w])async\s*\(\s*(?:async\s*)?(?:\([^)]*\)|function)/,
+    message: 'The async() testing helper was renamed to waitForAsync().',
+    fix: 'Use waitForAsync() from @angular/core/testing.',
+    docs: 'https://angular.dev/api/core/testing/waitForAsync',
+  },
+  {
+    id: 'canload-guard',
+    title: 'CanLoad guard deprecated',
+    severity: 'deprecated', since: 15, scope: 'ts',
+    match: { type: 'identifier', name: 'CanLoad' },
+    regex: /\bCanLoad\b/,
+    message: 'The CanLoad route guard interface is deprecated.',
+    fix: 'Migrate to CanMatch (and prefer functional guards).',
+    docs: 'https://angular.dev/api/router/CanMatch',
+  },
+];
+
+const TEMPLATE_RULES = [
+  {
+    id: 'cf-ngif',
+    title: '*ngIf → @if opportunity',
+    severity: 'opportunity', since: 17, scope: 'template',
+    regex: /\*ngIf\b/g,
+    message: 'Built-in control flow @if is the modern replacement for *ngIf.',
+    fix: 'Run `ng generate @angular/core:control-flow` after upgrading to v17+.',
+    docs: 'https://angular.dev/guide/templates/control-flow',
+  },
+  {
+    id: 'cf-ngfor',
+    title: '*ngFor → @for opportunity',
+    severity: 'opportunity', since: 17, scope: 'template',
+    regex: /\*ngFor\b/g,
+    message: 'Built-in control flow @for replaces *ngFor and improves performance.',
+    fix: 'Run the control-flow migration schematic after upgrading to v17+.',
+    docs: 'https://angular.dev/guide/templates/control-flow',
+  },
+  {
+    id: 'cf-ngswitch',
+    title: '*ngSwitch → @switch opportunity',
+    severity: 'opportunity', since: 17, scope: 'template',
+    regex: /\[ngSwitch\]|\*ngSwitchCase|\*ngSwitchDefault/g,
+    message: 'Built-in control flow @switch replaces the ngSwitch directives.',
+    fix: 'Run the control-flow migration schematic after upgrading to v17+.',
+    docs: 'https://angular.dev/guide/templates/control-flow',
+  },
+  {
+    id: 'flex-layout-directives',
+    title: 'flex-layout directives (fx*) in templates',
+    severity: 'removed', since: 16, scope: 'template',
+    regex: /\sfx(Layout|Flex|LayoutAlign|LayoutGap|Show|Hide|Fill)\b/g,
+    message: '@angular/flex-layout is discontinued; its fx* directives have no supported replacement.',
+    fix: 'Migrate to CSS Flexbox/Grid or Angular CDK Layout.',
+    docs: 'https://github.com/angular/flex-layout',
+  },
+];
+
+module.exports = { TS_RULES, TEMPLATE_RULES };

package/src/data/known-packages.js

@@ -0,0 +1,92 @@
+'use strict';
+
+/**
+ * Curated knowledge base of packages that need special handling during an
+ * Angular upgrade — things a registry lookup alone can't tell you:
+ * officially removed tooling, discontinued libraries, and recommended
+ * replacements. This is data, not logic, so it can grow with community PRs.
+ *
+ * status:
+ *   'removed'       - removed from Angular / no longer part of the toolchain
+ *   'discontinued'  - officially discontinued by its maintainers
+ *   'abandoned'     - Angular-2/legacy era, effectively unmaintained
+ *   'transitional'  - a shim that should be removed after migration
+ *   'maintenance'   - still works but recommended to move off
+ */
+
+const KNOWN = {
+  tslint: {
+    status: 'removed',
+    reason: 'TSLint is deprecated and unsupported. Angular linting moved to ESLint.',
+    replacement: 'angular-eslint (@angular-eslint/schematics)',
+  },
+  codelyzer: {
+    status: 'removed',
+    reason: 'Codelyzer targets TSLint, which is deprecated.',
+    replacement: 'angular-eslint',
+  },
+  'rxjs-tslint': {
+    status: 'removed',
+    reason: 'TSLint-based RxJS migration tool; obsolete after moving to RxJS 7 + ESLint.',
+    replacement: 'rxjs 7 + eslint-plugin-rxjs (or drop entirely)',
+  },
+  protractor: {
+    status: 'removed',
+    reason: 'Protractor is deprecated and was dropped from the Angular CLI.',
+    replacement: 'Playwright or Cypress',
+  },
+  '@angular/flex-layout': {
+    status: 'discontinued',
+    reason: 'Officially discontinued by the Angular team; no releases past v15.',
+    replacement: 'Angular CDK Layout + native CSS Flexbox/Grid',
+  },
+  'rxjs-compat': {
+    status: 'transitional',
+    reason: 'Compatibility shim for the RxJS 5 -> 6 migration. Should not survive an upgrade.',
+    replacement: 'Complete RxJS 7 migration and remove',
+  },
+  'ngrx-store-freeze': {
+    status: 'abandoned',
+    reason: 'Deprecated; NgRx has built-in runtime checks for state immutability.',
+    replacement: 'NgRx runtimeChecks (strictStateImmutability)',
+  },
+  moment: {
+    status: 'maintenance',
+    reason: 'Moment.js is in maintenance mode and is large; the team recommends alternatives.',
+    replacement: 'date-fns, Luxon, Day.js, or native Temporal',
+  },
+  'moment-timezone': {
+    status: 'maintenance',
+    reason: 'Tied to Moment.js which is in maintenance mode.',
+    replacement: 'Luxon or @js-temporal/polyfill',
+  },
+  jquery: {
+    status: 'maintenance',
+    reason: 'Direct DOM libraries fight Angular change detection; usually avoidable.',
+    replacement: 'Angular APIs / Renderer2 / signals',
+  },
+  'angular2-modal': { status: 'abandoned', reason: 'Angular 2-era, unmaintained.', replacement: 'Angular CDK Overlay or @angular/material dialog' },
+  'angular2-multiselect-dropdown': { status: 'abandoned', reason: 'Angular 2-era, unmaintained.', replacement: 'Angular Material / CDK-based multiselect' },
+  'ng2-select': { status: 'abandoned', reason: 'Angular 2-era, unmaintained.', replacement: 'ng-select or Angular Material' },
+  'ng2-dnd': { status: 'abandoned', reason: 'Angular 2-era, unmaintained.', replacement: '@angular/cdk/drag-drop' },
+  'ng2-cache': { status: 'abandoned', reason: 'Angular 2-era, unmaintained.', replacement: 'Custom service or a maintained cache lib' },
+  'ng2-truncate': { status: 'abandoned', reason: 'Angular 2-era, unmaintained.', replacement: 'CSS line-clamp or a custom pipe' },
+  'ng2-search-filter': { status: 'abandoned', reason: 'Angular 2-era, unmaintained.', replacement: 'Custom pipe / RxJS filtering' },
+  'ng2-material-dropdown': { status: 'abandoned', reason: 'Angular 2-era, unmaintained.', replacement: '@angular/material menu/select' },
+  'ngx-modialog': { status: 'abandoned', reason: 'Unmaintained modal library.', replacement: '@angular/cdk/overlay or @angular/material dialog' },
+  mydaterangepicker: { status: 'abandoned', reason: 'Unmaintained date picker.', replacement: '@angular/material datepicker or ngx-daterangepicker-material' },
+  'angular-wizard-form': { status: 'abandoned', reason: 'Unmaintained; low activity.', replacement: '@angular/cdk/stepper or @angular/material stepper' },
+};
+
+/** Package name prefixes that strongly imply an Angular-coupled library. */
+const ANGULAR_LIB_PREFIXES = ['@angular/', '@ngrx/', '@ngtools/', 'ng2-', 'ngx-', 'angular2-', 'angularx-', '@angular-eslint/', '@nguniversal/', '@ng-'];
+
+function lookup(name) {
+  return KNOWN[name] || null;
+}
+
+function looksAngularCoupled(name) {
+  return ANGULAR_LIB_PREFIXES.some((p) => name.startsWith(p)) || /(^|[-/])ng(x|2)?[-/]/.test(name);
+}
+
+module.exports = { KNOWN, lookup, looksAngularCoupled, ANGULAR_LIB_PREFIXES };

package/src/index.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { analyzeSnapshot } = require('./analyzers/project-snapshot');
+const { analyzeCensus } = require('./analyzers/code-census');
+const { analyzeVersionGap } = require('./analyzers/version-gap');
+const { analyzeDependencies } = require('./analyzers/dependency-compat');
+const { analyzeBreakingChanges } = require('./analyzers/breaking-changes');
+const { computeVerdict } = require('./analyzers/verdict');
+const { renderTerminal } = require('./report/terminal');
+const { renderHtml } = require('./report/html');
+const { renderJson } = require('./report/json');
+const { LATEST_STABLE } = require('./data/angular-versions');
+const { c, write } = require('./utils/log');
+
+const TOOL_VERSION = require('../package.json').version;
+
+async function run(options) {
+  const projectDir = path.resolve(options.projectDir || process.cwd());
+
+  if (!fs.existsSync(path.join(projectDir, 'package.json'))) {
+    write(c.red(`✗ No package.json found in ${projectDir}`));
+    process.exitCode = 2;
+    return;
+  }
+
+  write(c.dim('  Reading project…'));
+  const snapshot = analyzeSnapshot(projectDir);
+
+  if (!snapshot.angularMajor) {
+    write(c.yellow('  ⚠ Could not detect @angular/core — is this an Angular project?'));
+  }
+
+  const targetMajor = options.target || LATEST_STABLE;
+  const versionGap = analyzeVersionGap(snapshot.angularMajor, targetMajor);
+
+  let census = null;
+  let breakingChanges = null;
+  if (!options.noCode) {
+    write(c.dim('  Scanning source tree…'));
+    census = analyzeCensus(projectDir);
+    breakingChanges = analyzeBreakingChanges(projectDir);
+    if (!breakingChanges.astAvailable) {
+      write(c.dim('  (TypeScript compiler not found in project — used regex fallback for code scan)'));
+    }
+  }
+
+  write(c.dim(`  Analyzing ${snapshot.totalDependencyCount} dependencies${options.offline ? ' (offline)' : ' against the npm registry'}…`));
+  const deps = await analyzeDependencies(snapshot, targetMajor, {
+    offline: options.offline,
+    concurrency: options.concurrency || 8,
+    onProgress: options.quiet ? null : throttleProgress(snapshot.totalDependencyCount),
+  });
+  deps.offline = Boolean(options.offline);
+
+  const verdict = computeVerdict({ snapshot, versionGap, deps, census, breakingChanges });
+
+  const report = {
+    snapshot,
+    versionGap,
+    deps,
+    census,
+    breakingChanges,
+    verdict,
+    meta: { toolVersion: TOOL_VERSION, generatedAt: options.now || '', projectDir },
+  };
+
+  // Terminal output
+  renderTerminal(report);
+
+  // Write artifacts
+  const outDir = path.resolve(options.out || projectDir);
+  const htmlPath = path.join(outDir, 'ng-upgrade-report.html');
+  const jsonPath = path.join(outDir, 'ng-upgrade-report.json');
+  try {
+    fs.mkdirSync(outDir, { recursive: true });
+    fs.writeFileSync(htmlPath, renderHtml(report), 'utf8');
+    fs.writeFileSync(jsonPath, renderJson(report), 'utf8');
+    write('  ' + c.green('✓') + ' HTML report:  ' + c.cyan(htmlPath));
+    write('  ' + c.green('✓') + ' JSON report:  ' + c.cyan(jsonPath));
+    write('');
+  } catch (e) {
+    write(c.red('  ✗ Could not write reports: ' + e.message));
+  }
+
+  // CI gate
+  if (options.ci) {
+    const fail = deps.summary.blocker + deps.summary.removed > 0 || verdict.score < (options.minScore || 0);
+    process.exitCode = fail ? 1 : 0;
+  }
+
+  return report;
+}
+
+function throttleProgress(total) {
+  let last = 0;
+  return (done) => {
+    const pct = Math.floor((done / total) * 100);
+    if (pct >= last + 10 || done === total) {
+      last = pct;
+      if (process.stdout.isTTY) process.stdout.write(`\r  …resolved ${done}/${total} packages   `);
+      if (done === total && process.stdout.isTTY) process.stdout.write('\r' + ' '.repeat(40) + '\r');
+    }
+  };
+}
+
+module.exports = { run, TOOL_VERSION };

package/src/registry.js

@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * Zero-dependency npm registry client built on Node's global fetch (Node 18+).
+ * Fetches lightweight "packuments" and extracts only the fields we need.
+ * Everything degrades gracefully: on any network failure we return null and
+ * the analysis falls back to the local knowledge base.
+ */
+
+const https = require('https');
+const { URL } = require('url');
+
+const REGISTRY = process.env.NPM_REGISTRY || 'https://registry.npmjs.org';
+const ACCEPT = 'application/vnd.npm.install-v1+json, application/json';
+
+function encodeName(name) {
+  // Scoped package @scope/name -> @scope%2Fname
+  return name.startsWith('@') ? '@' + encodeURIComponent(name.slice(1)) : encodeURIComponent(name);
+}
+
+/** True when Node's global fetch is available (Node 18+). */
+const hasGlobalFetch = typeof fetch === 'function';
+
+async function fetchPackument(name, timeoutMs = 8000) {
+  const url = `${REGISTRY}/${encodeName(name)}`;
+  // The "abbreviated" packument is much smaller and still carries peerDeps.
+  const json = hasGlobalFetch
+    ? await fetchViaGlobal(url, timeoutMs)
+    : await fetchViaHttps(url, timeoutMs);
+  return json;
+}
+
+async function fetchViaGlobal(url, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { headers: { Accept: ACCEPT }, signal: controller.signal });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch (_) {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Fallback for Node <18 (no global fetch). Requests identity encoding so we
+ *  don't have to decompress gzip ourselves. */
+function fetchViaHttps(url, timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (v) => { if (!settled) { settled = true; resolve(v); } };
+    try {
+      const u = new URL(url);
+      const req = https.get(
+        {
+          hostname: u.hostname,
+          path: u.pathname + u.search,
+          headers: { Accept: ACCEPT, 'Accept-Encoding': 'identity', 'User-Agent': 'ng-upgrade-doctor' },
+        },
+        (res) => {
+          if (res.statusCode !== 200) { res.resume(); return done(null); }
+          let data = '';
+          res.setEncoding('utf8');
+          res.on('data', (chunk) => { data += chunk; });
+          res.on('end', () => { try { done(JSON.parse(data)); } catch (_) { done(null); } });
+        }
+      );
+      req.on('error', () => done(null));
+      req.setTimeout(timeoutMs, () => { req.destroy(); done(null); });
+    } catch (_) {
+      done(null);
+    }
+  });
+}
+
+/** Run async `worker` over `items` with a bounded concurrency pool. */
+async function mapPool(items, concurrency, worker) {
+  const results = new Array(items.length);
+  let cursor = 0;
+  const runners = new Array(Math.min(concurrency, items.length)).fill(0).map(async () => {
+    while (cursor < items.length) {
+      const idx = cursor++;
+      try {
+        results[idx] = await worker(items[idx], idx);
+      } catch (_) {
+        results[idx] = null;
+      }
+    }
+  });
+  await Promise.all(runners);
+  return results;
+}
+
+module.exports = { fetchPackument, mapPool, REGISTRY };