ng-checkup 0.0.0-stage → 0.2.0

package/dist/graph.d.ts

@@ -0,0 +1,44 @@
+import ts from 'typescript';
+import type { SourceFileFacts } from './scan.js';
+/** A group of files that import each other in a loop, directly or through others. */
+export interface DependencyTangle {
+    /** Report paths of every file in the group, sorted. */
+    files: string[];
+    /**
+     * One concrete loop through the group, first file repeated at the end
+     * (`a.ts → b.ts → a.ts`), so a reader can see where to cut. A large group
+     * holds many loops; this is the shortest one through its first file.
+     */
+    example: string[];
+}
+/**
+ * Finds the import cycles among the analysed files.
+ *
+ * Counts groups (strongly connected components) rather than individual cycles.
+ * Two files that import each other plus a third that closes a second loop
+ * through them are one problem to untangle, while a cycle count would call it
+ * two or more and grows combinatorially with the size of the group, which is
+ * why tools that list every cycle report numbers nobody can act on.
+ *
+ * Only eager, value-level edges count: `import type` is erased at compile time
+ * and `import()` loads later, so neither can produce the initialisation-order
+ * crash a cycle is dangerous for. Spec files are left out because nothing
+ * imports them.
+ *
+ * @param compilerOptions The repository's compiler options, for `paths`
+ *   aliases. Module resolution itself is forced to `bundler`, which is how the
+ *   Angular CLI resolves and which needs no file extensions.
+ */
+export declare function findTangles(files: SourceFileFacts[], compilerOptions: ts.CompilerOptions): DependencyTangle[];
+/**
+ * Tarjan's algorithm, written iteratively. The recursive textbook version
+ * overflows the stack on a long import chain, and a 3 000-file app has those.
+ */
+export declare function stronglyConnectedComponents(edges: Map<string, string[]>): string[][];
+/**
+ * Compiler options from the repository's root tsconfig, `extends` included,
+ * which is where Nx and many CLI workspaces keep their `paths` aliases.
+ * Returns empty options when there is no tsconfig or it cannot be parsed; the
+ * graph then still resolves every relative import.
+ */
+export declare function readCompilerOptions(tsconfigPath: string | undefined): ts.CompilerOptions;

package/dist/graph.js

@@ -0,0 +1,151 @@
+import { dirname, resolve } from 'node:path';
+import ts from 'typescript';
+/**
+ * Finds the import cycles among the analysed files.
+ *
+ * Counts groups (strongly connected components) rather than individual cycles.
+ * Two files that import each other plus a third that closes a second loop
+ * through them are one problem to untangle, while a cycle count would call it
+ * two or more and grows combinatorially with the size of the group, which is
+ * why tools that list every cycle report numbers nobody can act on.
+ *
+ * Only eager, value-level edges count: `import type` is erased at compile time
+ * and `import()` loads later, so neither can produce the initialisation-order
+ * crash a cycle is dangerous for. Spec files are left out because nothing
+ * imports them.
+ *
+ * @param compilerOptions The repository's compiler options, for `paths`
+ *   aliases. Module resolution itself is forced to `bundler`, which is how the
+ *   Angular CLI resolves and which needs no file extensions.
+ */
+export function findTangles(files, compilerOptions) {
+    const sources = files.filter((file) => !file.isSpec);
+    const byAbsolute = new Map(sources.map((file) => [resolve(file.absolutePath), file]));
+    const options = { ...compilerOptions, moduleResolution: ts.ModuleResolutionKind.Bundler, module: ts.ModuleKind.ESNext, allowJs: false };
+    const cache = ts.createModuleResolutionCache(process.cwd(), (name) => name, options);
+    const edges = new Map();
+    for (const file of sources) {
+        const targets = new Set();
+        for (const fact of file.imports) {
+            if (fact.typeOnly || fact.dynamic)
+                continue;
+            // Bare specifiers that are not path aliases resolve into node_modules and are dropped below;
+            // skipping the obvious ones first saves most of the resolution work.
+            if (!fact.specifier.startsWith('.') && !options.paths)
+                continue;
+            const resolved = ts.resolveModuleName(fact.specifier, file.absolutePath, options, ts.sys, cache).resolvedModule;
+            if (!resolved || resolved.isExternalLibraryImport)
+                continue;
+            const target = resolve(resolved.resolvedFileName);
+            if (byAbsolute.has(target))
+                targets.add(target);
+        }
+        edges.set(resolve(file.absolutePath), [...targets]);
+    }
+    return stronglyConnectedComponents(edges)
+        .filter((component) => component.length > 1 || (edges.get(component[0]) ?? []).includes(component[0]))
+        .map((component) => {
+        const members = new Set(component);
+        const sorted = component.map((path) => byAbsolute.get(path).path).sort();
+        const start = component.find((path) => byAbsolute.get(path).path === sorted[0]);
+        return { files: sorted, example: shortestLoop(start, edges, members).map((path) => byAbsolute.get(path).path) };
+    })
+        .sort((left, right) => right.files.length - left.files.length || left.files[0].localeCompare(right.files[0]));
+}
+/**
+ * Tarjan's algorithm, written iteratively. The recursive textbook version
+ * overflows the stack on a long import chain, and a 3 000-file app has those.
+ */
+export function stronglyConnectedComponents(edges) {
+    let counter = 0;
+    const index = new Map();
+    const lowLink = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const components = [];
+    for (const start of edges.keys()) {
+        if (index.has(start))
+            continue;
+        const work = [{ node: start, next: 0 }];
+        index.set(start, counter);
+        lowLink.set(start, counter++);
+        stack.push(start);
+        onStack.add(start);
+        while (work.length > 0) {
+            const frame = work[work.length - 1];
+            const successors = edges.get(frame.node) ?? [];
+            if (frame.next < successors.length) {
+                const successor = successors[frame.next++];
+                if (!index.has(successor)) {
+                    index.set(successor, counter);
+                    lowLink.set(successor, counter++);
+                    stack.push(successor);
+                    onStack.add(successor);
+                    work.push({ node: successor, next: 0 });
+                }
+                else if (onStack.has(successor)) {
+                    lowLink.set(frame.node, Math.min(lowLink.get(frame.node), index.get(successor)));
+                }
+                continue;
+            }
+            work.pop();
+            const parent = work[work.length - 1];
+            if (parent)
+                lowLink.set(parent.node, Math.min(lowLink.get(parent.node), lowLink.get(frame.node)));
+            if (lowLink.get(frame.node) === index.get(frame.node)) {
+                const component = [];
+                let member;
+                do {
+                    member = stack.pop();
+                    onStack.delete(member);
+                    component.push(member);
+                } while (member !== frame.node);
+                components.push(component);
+            }
+        }
+    }
+    return components;
+}
+/**
+ * The shortest path from `start` back to itself inside one component, by
+ * breadth-first search. Always finds one, since every node of a strongly
+ * connected component lies on a loop.
+ */
+function shortestLoop(start, edges, members) {
+    const previous = new Map();
+    const queue = [start];
+    for (let head = 0; head < queue.length; head++) {
+        const node = queue[head];
+        for (const successor of edges.get(node) ?? []) {
+            if (!members.has(successor))
+                continue;
+            if (successor === start) {
+                // Walk back from the node that closes the loop; a self-import leaves the chain empty.
+                const chain = [];
+                for (let step = node; step !== undefined && step !== start; step = previous.get(step))
+                    chain.unshift(step);
+                return [start, ...chain, start];
+            }
+            if (!previous.has(successor) && successor !== start) {
+                previous.set(successor, node);
+                queue.push(successor);
+            }
+        }
+    }
+    return [start, start];
+}
+/**
+ * Compiler options from the repository's root tsconfig, `extends` included,
+ * which is where Nx and many CLI workspaces keep their `paths` aliases.
+ * Returns empty options when there is no tsconfig or it cannot be parsed; the
+ * graph then still resolves every relative import.
+ */
+export function readCompilerOptions(tsconfigPath) {
+    if (!tsconfigPath)
+        return {};
+    const config = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
+    if (config.error)
+        return {};
+    return ts.parseJsonConfigFileContent(config.config, ts.sys, dirname(tsconfigPath), undefined, tsconfigPath).options;
+}
+//# sourceMappingURL=graph.js.map

package/dist/graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["../src/graph.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import type { AnalysisContext, Check } from './checks/context.js';
+import type { CheckupOptions, Report } from './types.js';
+export type * from './types.js';
+export { renderHtml } from './report/html.js';
+export { renderMarkdown } from './report/markdown.js';
+export { overallScore, topPriorities } from './report/summary.js';
+export { CONFIG_FILE, loadConfig, type CheckupConfig } from './config.js';
+export { planInit, type InitChange, type InitOptions, type InitPlan } from './init.js';
+/**
+ * The newest Angular major this release of the tool knows about. Used only
+ * when the registry cannot be reached or `--offline` is set, and the report
+ * says so next to the number, because it goes stale with every Angular release.
+ */
+export declare const BUNDLED_LATEST_ANGULAR_MAJOR = 22;
+/**
+ * The checks in report order: the upgrade blockers first (version,
+ * deprecations), then the modernisation areas, then the structural ones.
+ */
+export declare const CHECKS: Check[];
+/** This package's own name and version, read from its package.json at runtime so the two never drift. */
+export declare const TOOL: {
+    name: string;
+    version: string;
+};
+/**
+ * Analyses the Angular codebase at `root` and returns the full report.
+ *
+ * Reads the disk and, unless `offline` is set, makes one request to the npm
+ * registry for the latest `@angular/core` version (three-second timeout,
+ * falling back to `BUNDLED_LATEST_ANGULAR_MAJOR`). Nothing else leaves the
+ * machine: no source, no file names, no telemetry. Never writes anything.
+ */
+export declare function runCheckup(root: string, options?: CheckupOptions): Promise<Report>;
+/** Gathers everything the checks read. Exported for tests that want to inspect the facts. */
+export declare function buildContext(root: string, options: CheckupOptions): Promise<AnalysisContext>;
+/**
+ * `angularCompilerOptions` of a tsconfig, merged along its `extends` chain
+ * with the child winning. TypeScript's own config parser resolves `extends`
+ * for `compilerOptions` only and drops this block, so it is merged by hand.
+ * Follows relative `extends` paths (strings or, since TS 5.0, arrays); a
+ * package-name `extends` is skipped, since no shared tsconfig package sets
+ * Angular's options.
+ */
+export declare function readAngularCompilerOptions(tsconfigPath: string, depth?: number): Record<string, unknown>;

package/dist/index.js

@@ -0,0 +1,135 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { changeDetectionCheck } from './checks/change-detection.js';
+import { circularDepsCheck } from './checks/circular-deps.js';
+import { componentsCheck } from './checks/components.js';
+import { deprecatedApisCheck } from './checks/deprecated-apis.js';
+import { stateCheck } from './checks/state.js';
+import { testingCheck } from './checks/testing.js';
+import { typeSafetyCheck } from './checks/type-safety.js';
+import { versionCheck } from './checks/version.js';
+import { buildDeprecationIndex } from './deprecations.js';
+import { ignoreMatcher } from './config.js';
+import { collectFiles } from './files.js';
+import { findTangles, readCompilerOptions } from './graph.js';
+import { scanSourceFile, scanTemplateFile } from './scan.js';
+import { asRecord, majorOf, readJson, readWorkspace } from './workspace.js';
+// The renderers and the score are public so a script can turn a report from
+// `runCheckup` into the same HTML or Markdown the CLI writes, e.g. to post it
+// as a pull-request comment.
+export { renderHtml } from './report/html.js';
+export { renderMarkdown } from './report/markdown.js';
+export { overallScore, topPriorities } from './report/summary.js';
+export { CONFIG_FILE, loadConfig } from './config.js';
+export { planInit } from './init.js';
+/**
+ * The newest Angular major this release of the tool knows about. Used only
+ * when the registry cannot be reached or `--offline` is set, and the report
+ * says so next to the number, because it goes stale with every Angular release.
+ */
+export const BUNDLED_LATEST_ANGULAR_MAJOR = 22;
+/**
+ * The checks in report order: the upgrade blockers first (version,
+ * deprecations), then the modernisation areas, then the structural ones.
+ */
+export const CHECKS = [versionCheck, deprecatedApisCheck, changeDetectionCheck, componentsCheck, stateCheck, testingCheck, typeSafetyCheck, circularDepsCheck];
+/** This package's own name and version, read from its package.json at runtime so the two never drift. */
+export const TOOL = readToolInfo();
+/**
+ * Analyses the Angular codebase at `root` and returns the full report.
+ *
+ * Reads the disk and, unless `offline` is set, makes one request to the npm
+ * registry for the latest `@angular/core` version (three-second timeout,
+ * falling back to `BUNDLED_LATEST_ANGULAR_MAJOR`). Nothing else leaves the
+ * machine: no source, no file names, no telemetry. Never writes anything.
+ */
+export async function runCheckup(root, options = {}) {
+    const started = Date.now();
+    const absoluteRoot = resolve(root);
+    const context = await buildContext(absoluteRoot, options);
+    const checks = CHECKS.map((check) => check(context));
+    const application = context.sources.filter((file) => !file.isSpec);
+    return {
+        tool: TOOL,
+        generatedAt: new Date().toISOString(),
+        root: absoluteRoot,
+        project: {
+            name: context.workspace.name,
+            kind: context.workspace.kind,
+            angularVersion: context.workspace.angular.installed ?? context.workspace.angular.declared,
+            sourceFiles: context.sources.length,
+            templateFiles: context.templates.filter((template) => !template.inline).length,
+            linesOfCode: application.reduce((sum, file) => sum + file.linesOfCode, 0),
+        },
+        checks,
+        durationMs: Date.now() - started,
+    };
+}
+/** Gathers everything the checks read. Exported for tests that want to inspect the facts. */
+export async function buildContext(root, options) {
+    const files = collectFiles(root, ignoreMatcher(options.ignore));
+    const workspace = readWorkspace(root, files.projectJsons);
+    const sources = files.typescript.map((path) => scanSourceFile(root, path));
+    const templates = [...files.html.map((path) => scanTemplateFile(root, path)), ...sources.flatMap((file) => file.inlineTemplates)];
+    const appCompilerOptions = readCompilerOptions(workspace.appTsconfig);
+    return {
+        workspace,
+        sources,
+        templates,
+        deprecations: buildDeprecationIndex(root),
+        tangles: findTangles(sources, readCompilerOptions(workspace.rootTsconfig)),
+        latestAngular: options.offline ? { major: BUNDLED_LATEST_ANGULAR_MAJOR, source: 'bundled' } : await fetchLatestAngularMajor(),
+        appCompilerOptions,
+        angularCompilerOptions: workspace.appTsconfig ? readAngularCompilerOptions(workspace.appTsconfig) : {},
+        maxExamples: options.maxExamples ?? 5,
+    };
+}
+/**
+ * The latest `@angular/core` major from the npm registry, or the bundled
+ * fallback when the request fails or takes longer than three seconds. A slow
+ * or offline network must never stall a run that is otherwise local.
+ */
+async function fetchLatestAngularMajor() {
+    try {
+        const response = await fetch('https://registry.npmjs.org/@angular/core/latest', { signal: AbortSignal.timeout(3000) });
+        if (response.ok) {
+            const major = majorOf(asRecord(await response.json())['version']);
+            if (major !== undefined)
+                return { major, source: 'registry' };
+        }
+    }
+    catch {
+        // Offline, blocked by a proxy, or timed out: the bundled value is the answer.
+    }
+    return { major: BUNDLED_LATEST_ANGULAR_MAJOR, source: 'bundled' };
+}
+/**
+ * `angularCompilerOptions` of a tsconfig, merged along its `extends` chain
+ * with the child winning. TypeScript's own config parser resolves `extends`
+ * for `compilerOptions` only and drops this block, so it is merged by hand.
+ * Follows relative `extends` paths (strings or, since TS 5.0, arrays); a
+ * package-name `extends` is skipped, since no shared tsconfig package sets
+ * Angular's options.
+ */
+export function readAngularCompilerOptions(tsconfigPath, depth = 0) {
+    const config = readJson(tsconfigPath);
+    if (!config || depth > 10)
+        return {};
+    const parents = (Array.isArray(config['extends']) ? config['extends'] : [config['extends']]).filter((entry) => typeof entry === 'string' && entry.startsWith('.'));
+    const inherited = parents.reduce((merged, parent) => {
+        const path = resolve(dirname(tsconfigPath), parent.endsWith('.json') ? parent : `${parent}.json`);
+        return { ...merged, ...readAngularCompilerOptions(path, depth + 1) };
+    }, {});
+    return { ...inherited, ...asRecord(config['angularCompilerOptions']) };
+}
+/** Reads name and version from this package's package.json, one level above both `src/` and `dist/`. */
+function readToolInfo() {
+    try {
+        const packageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+        return { name: packageJson.name ?? 'ng-checkup', version: packageJson.version ?? '0.0.0' };
+    }
+    catch {
+        return { name: 'ng-checkup', version: '0.0.0' };
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/init.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The two reads `planInit` needs. `ng-checkup init` backs it with `node:fs`,
+ * `ng add` with the schematic's virtual tree, and tests with a plain object,
+ * which is why the planner never touches the disk itself.
+ */
+export interface InitFileSystem {
+    /** File content, or undefined when the path is missing. Paths are root-relative with `/`. */
+    read(path: string): string | undefined;
+    /** True for an existing file or directory. */
+    exists(path: string): boolean;
+}
+/** Where the CI step goes. `auto` picks from what the repository already has. */
+export type CiChoice = 'auto' | 'github' | 'gitlab' | 'none';
+/** What `planInit` should do. */
+export interface InitOptions {
+    /** Defaults to `auto`: GitHub when `.github/` exists, GitLab when `.gitlab-ci.yml` does, else none. */
+    ci?: CiChoice;
+    /**
+     * Add `ng-checkup` to `devDependencies`. Defaults to true. `ng add` passes
+     * false because the Angular CLI has already installed and saved it.
+     */
+    addDependency?: boolean;
+    /** The version to pin, normally this package's own. */
+    version: string;
+    /** Replace an existing `checkup` script that runs something else. */
+    force?: boolean;
+}
+/** One file to write. Content is the whole new file. */
+export interface InitChange {
+    path: string;
+    action: 'create' | 'update';
+    content: string;
+    /** One line for the user: what this change does. */
+    summary: string;
+}
+/** Everything `init` would do, and what the user has to do afterwards. */
+export interface InitPlan {
+    changes: InitChange[];
+    /** Things left alone or left to the user, one line each. */
+    notes: string[];
+    /** Commands the user runs next, in order. */
+    nextSteps: string[];
+    ci: Exclude<CiChoice, 'auto'>;
+    packageManager: PackageManager;
+}
+/** The package managers whose lockfiles `init` recognises. */
+export type PackageManager = 'npm' | 'pnpm' | 'yarn';
+/**
+ * Plans what `ng-checkup init` and `ng add ng-checkup` set up in a repository:
+ *
+ * 1. a `checkup` script in `package.json` (and `ng-checkup` in `devDependencies`),
+ * 2. `ng-checkup.config.json` with the local report and an empty `ignore` list,
+ * 3. the generated reports in `.gitignore`, when there is one,
+ * 4. a CI step: a GitHub Actions workflow, or a GitLab CI file to `include`.
+ *
+ * Idempotent: on a repository that already has all of it, the plan is empty.
+ * It never overwrites a file the user wrote: an existing workflow, config or
+ * different `checkup` script is kept and reported in `notes` instead
+ * (`force` replaces the script only). It does not edit `.gitlab-ci.yml`
+ * either, since merging into someone's pipeline YAML is where a tool does
+ * damage; it writes a separate file and says which `include` to add.
+ *
+ * @throws When there is no `package.json` or it is not valid JSON. Both mean
+ *   this is not the root of a Node project, and writing anything would be wrong.
+ */
+export declare function planInit(files: InitFileSystem, options: InitOptions): InitPlan;
+/** The package manager, from its lockfile. npm when there is none or only npm's. */
+export declare function detectPackageManager(files: InitFileSystem): PackageManager;
+/** A GitHub Actions workflow for the repository's package manager. */
+export declare function githubWorkflow(manager: PackageManager): string;
+/** A GitLab CI job file for the repository's package manager, meant to be `include`d. */
+export declare function gitlabJob(manager: PackageManager): string;
+/**
+ * Serialises `value` with the indentation and final newline of `original`,
+ * so `init` changes only the lines it means to and a `git diff` of
+ * `package.json` shows exactly the added keys.
+ */
+export declare function formatJsonLike(original: string, value: unknown): string;