@webpieces/nx-webpieces-rules 0.4.874 → 0.4.876

package/src/lib/graph-impact.d.ts

@@ -1,40 +1,56 @@
 /**
- * Impact mode's data: what THIS BRANCH's build looks like, in three shades (plus untouched grey).
+ * Impact mode's data: what one COMPARISON's build looks like, in three shades (plus untouched grey).
  *
+ * There are two comparisons, and only two (#1163). Both end at the WORKING TREE, so uncommitted and
+ * untracked work counts in either:
+ *
+ *  - BRANCH, "Changed on this branch": the fork point (`DiffScope.detectBase` in rules-config:
+ *    `git merge-base HEAD origin/main`, falling back to `main`) → working tree.
+ *  - COMMIT, "Last commit": `HEAD^` → working tree. To see what another commit changed, check it out
+ *    (`git checkout <hash>`) and run `pnpm arch:visualize`: nx computes `--affected` against the code
+ *    that is actually on disk, so nothing here ever jumps to another commit.
+ *
+ * Which of them exist is decided by `ImpactScopeResolver` from where HEAD is. On `main` (by BRANCH
+ * NAME, so a local main with unpushed commits still counts as main) and on a detached HEAD only the
+ * last commit exists — the fork point IS HEAD there, so the branch comparison would always be empty.
+ * On a feature branch with commits past its fork point both exist, the branch one first. On a FRESH
+ * feature branch (fork point = HEAD) only the branch one exists: falling through to "last commit"
+ * would show main's last PR as if it were the branch's own work.
+ *
+ * Per comparison:
  *  - BUILD INPUT is every transitive dependency of the affected set that is not itself affected:
  *    `ci` dependsOn `^build`, so they must exist as build output though their inputs did not change.
  *    nx restores them from cache when it has them and compiles them otherwise — which one happens is
  *    not knowable here, so nothing claims it. A pure downward walk over the graph's own edges.
- *
- *  - AFFECTED is `nx show projects --affected --base=<fork point> --json`, with NO `--head`, so
- *    uncommitted and untracked work counts. nx already gets right everything a hand-rolled diff gets
- *    wrong: lockfile and package.json changes resolved per project, root/global inputs, namedInputs,
- *    implicitDependencies, nested roots and deleted files. This uses its public CLI surface only, never
- *    nx internals.
+ *  - AFFECTED is `nx show projects --affected --base=<the comparison's base> --json`, with NO
+ *    `--head`, so uncommitted and untracked work counts. nx already gets right everything a
+ *    hand-rolled diff gets wrong: lockfile and package.json changes resolved per project, root/global
+ *    inputs, namedInputs, implicitDependencies, nested roots and deleted files. This uses its public
+ *    CLI surface only, never nx internals, and never NX_BASE/NX_HEAD, whose value depends on whoever
+ *    launched the process.
  *  - TOUCHED is the subset of that set which OWNS a changed file, by nx's own file-to-project
  *    ownership (the project file map from `createProjectFileMapUsingProjectGraph`, public devkit API)
- *    — never a path-prefix guess. A project whose only change is a DELETED file is not in that map
- *    (the file is gone), so it shows as affected rather than touched.
+ *    — never a path-prefix guess. The ownership map is computed ONCE and shared by every comparison.
+ *    A project whose only change is a DELETED file is not in that map (the file is gone), so it shows
+ *    as affected rather than touched. The changed-file list is `DiffScope.getChangedFiles`, the same
+ *    base→working-tree diff (with untracked files) every code rule uses.
  *
- * The base is the repo's existing merge-base computation (`DiffScope.detectBase` in rules-config:
- * `git merge-base HEAD origin/main`, falling back to `main`) — never NX_BASE/NX_HEAD, whose value
- * depends on whoever launched the process. The changed-file list is `DiffScope.getChangedFiles`, the
- * same base→working-tree diff (with untracked files) every code rule uses.
+ * The answer changes per checkout, so it never goes into the committed dependencies.html or
+ * dependencies.json (both stay byte-stable). It goes into a SIDECAR,
+ * `architecture/.impact/dependencies.impact.js`: a plain script setting one window global,
+ * `window.__WP_IMPACT__ = { scans, defaultKind }`, loaded with `<script src>` — the one way a page
+ * opened straight from disk (file://) can read a neighbouring file. The directory carries its own
+ * `.gitignore` containing `*`, which ignores the directory and everything in it, so a consumer repo
+ * needs no gitignore edit and the PR gate's "build left nothing uncommitted" check never sees it.
  *
- * The answer changes per branch, so it never goes into the committed dependencies.html or
- * dependencies.json (both stay byte-stable across branches). It goes into a SIDECAR,
- * `architecture/.impact/dependencies.impact.js`: a plain script setting one window global, loaded
- * with `<script src>` — the one way a page opened straight from disk (file://) can read a
- * neighbouring file. The directory carries its own `.gitignore` containing `*`, which ignores the
- * directory and everything in it, so a consumer repo needs no gitignore edit and the PR gate's
- * "build left nothing uncommitted" check never sees it.
+ * `architecture:visualize` scans every comparison that exists. `architecture:generate` refreshes
+ * ONLY the branch comparison (`GENERATE_IMPACT_KINDS`) and never scans the last commit; on main or a
+ * detached HEAD that leaves nothing to write, so it removes the sidecar and the page says to run
+ * `pnpm arch:visualize`.
  *
- * Both `architecture:generate` and `architecture:visualize` refresh it: the answer changes with the
- * branch, not with the architecture, so viewing the SAVED graph re-scans Impact against it without
- * regenerating anything else (#1158).
- *
- * Impact is a convenience. When nx or git cannot answer, NO sidecar is written (a stale one is
- * removed) and the page disables Impact with a one-line reason. It never fails generation.
+ * Impact is a convenience. When nx or git cannot answer any comparison, NO sidecar is written (a
+ * stale one is removed) and the page disables Impact with a one-line reason. It never fails
+ * generation.
  */
 import { DiffScope } from '@webpieces/rules-config';
 import type { EnhancedGraph } from './graph-sorter';
@@ -42,10 +58,31 @@ import type { EnhancedGraph } from './graph-sorter';
 export declare const IMPACT_SIDECAR_DIR = ".impact";
 export declare const IMPACT_SIDECAR_FILE = "dependencies.impact.js";
 export declare const IMPACT_SIDECAR_SRC = ".impact/dependencies.impact.js";
-/** What the sidecar carries; the page reads it as `window.__WP_IMPACT__`. */
+export declare const NOTHING_CHANGED_ON_BRANCH = "Nothing changed on this branch yet";
+export declare const ROOT_COMMIT_REASON = "HEAD is the repository's first commit; there is no previous commit to compare against";
+export declare const UNCOMMITTED_SUFFIX = " + uncommitted changes";
+/** Which of the two comparisons a scan answers. */
+export declare enum ImpactKind {
+    /** Fork point → working tree: "Changed on this branch". */
+    BRANCH = "branch",
+    /** HEAD^ → working tree: "Last commit". */
+    COMMIT = "commit"
+}
+/** `architecture:visualize` scans every comparison that exists. */
+export declare const VISUALIZE_IMPACT_KINDS: readonly ImpactKind[];
+/** `architecture:generate` refreshes the branch comparison only and never scans the last commit. */
+export declare const GENERATE_IMPACT_KINDS: readonly ImpactKind[];
+/** One scan as the sidecar carries it; the page reads `window.__WP_IMPACT__.scans`. */
 export declare class ImpactReport {
+    readonly kind: ImpactKind;
+    /** What the page says this scan compares, e.g. "Changed on this branch (since abc1234)". */
+    readonly label: string;
+    /** The working tree had uncommitted or untracked changes (they count in the scan). */
+    readonly dirty: boolean;
     readonly available: boolean;
+    /** Why the scan is unavailable; for an available but EMPTY scan, the note the page shows. */
     readonly reason: string;
+    /** The base's short sha ('' when there is none). */
     readonly base: string;
     /** Affected AND owning a changed file (node ids). */
     readonly touched: string[];
@@ -71,7 +108,15 @@ export declare class ImpactReport {
      * legend names them. Empty when nx's file ownership was unavailable — then nothing is known.
      */
     readonly globalFiles: string[];
-    constructor(available: boolean, reason: string, base: string, 
+    constructor(kind: ImpactKind, 
+    /** What the page says this scan compares, e.g. "Changed on this branch (since abc1234)". */
+    label: string, 
+    /** The working tree had uncommitted or untracked changes (they count in the scan). */
+    dirty: boolean, available: boolean, 
+    /** Why the scan is unavailable; for an available but EMPTY scan, the note the page shows. */
+    reason: string, 
+    /** The base's short sha ('' when there is none). */
+    base: string, 
     /** Affected AND owning a changed file (node ids). */
     touched: string[], 
     /** Affected but owning no changed file (node ids): their ci re-runs. */
@@ -96,10 +141,67 @@ export declare class ImpactReport {
      */
     globalFiles: string[]);
 }
-/** A scan that could not produce an answer: no sidecar is written, only this reason printed. */
+/** The sidecar's one global: every scan, and the one the page shows first. */
+export declare class ImpactSidecarData {
+    readonly scans: ImpactReport[];
+    readonly defaultKind: ImpactKind;
+    constructor(scans: ImpactReport[], defaultKind: ImpactKind);
+}
+/** A scan (or a whole plan) that could not produce an answer. */
 export declare class ImpactUnavailable {
     readonly reason: string;
-    constructor(reason: string);
+    readonly label: string;
+    constructor(reason: string, label?: string);
+}
+/** One comparison to scan. `base` is a full sha; null when it does not exist (`reason` says why). */
+export declare class ImpactComparison {
+    readonly kind: ImpactKind;
+    readonly base: string | null;
+    readonly label: string;
+    readonly dirty: boolean;
+    readonly reason: string;
+    constructor(kind: ImpactKind, base: string | null, label: string, dirty: boolean, reason: string);
+}
+/** The comparisons that exist where HEAD is, and which one the page shows first. */
+export declare class ImpactPlan {
+    readonly comparisons: ImpactComparison[];
+    readonly defaultKind: ImpactKind;
+    constructor(comparisons: ImpactComparison[], defaultKind: ImpactKind);
+}
+/** The few git facts the resolver needs. Injected so specs never spawn git. */
+export declare class ImpactGit {
+    /** The checked-out branch's short name; null on a detached HEAD (or without git). */
+    branch(root: string): string | null;
+    /** The full sha `ref` names; null when it does not resolve (e.g. `HEAD^` on the first commit). */
+    sha(root: string, ref: string): string | null;
+    /** `git status --porcelain` is non-empty: uncommitted or untracked work. */
+    dirty(root: string): boolean;
+    /** HEAD's subject line ('' when unknown). */
+    subject(root: string): string;
+    /** Trimmed stdout, or null on any failure. */
+    private run;
+}
+/**
+ * Decides which comparisons exist from where HEAD is (#1163):
+ *
+ * | where | comparisons | default |
+ * |---|---|---|
+ * | `main` (by branch NAME) | last commit | last commit |
+ * | detached HEAD | last commit | last commit |
+ * | feature branch with commits past the fork point | branch, last commit | branch |
+ * | fresh feature branch (fork point = HEAD) | branch | branch |
+ *
+ * HEAD with no parent leaves the last commit unavailable, with `ROOT_COMMIT_REASON`.
+ */
+export declare class ImpactScopeResolver {
+    private readonly git;
+    private readonly diffScope;
+    constructor(git?: ImpactGit, diffScope?: DiffScope);
+    resolve(root: string): ImpactPlan | ImpactUnavailable;
+    private lastCommit;
+    /** detectBase may hand back a full or an abbreviated sha; compare on the shorter of the two. */
+    private sameCommit;
+    private short;
 }
 /** Runs the workspace's own nx CLI. Injected so specs never spawn nx. */
 export declare class NxCli {
@@ -112,13 +214,32 @@ export declare class NxCli {
 export declare class ProjectFileOwners {
     owners(): Promise<Map<string, string>>;
 }
+/**
+ * nx's ownership map, computed at most ONCE however many comparisons ask for it. Failing is not
+ * fatal: the set then shows in one shade, all "affected".
+ */
+export declare class SharedOwners {
+    private readonly ownership;
+    private pending;
+    constructor(ownership: ProjectFileOwners);
+    get(): Promise<Map<string, string>>;
+    private load;
+}
 export declare class NxImpactScanner {
     private readonly diffScope;
     private readonly nx;
     private readonly ownership;
     private readonly names;
     constructor(diffScope?: DiffScope, nx?: NxCli, ownership?: ProjectFileOwners);
-    scan(workspaceRoot: string, graph: EnhancedGraph): Promise<ImpactReport | ImpactUnavailable>;
+    /** Every comparison, in order, sharing one ownership map. */
+    scanAll(workspaceRoot: string, graph: EnhancedGraph, comparisons: ImpactComparison[]): Promise<(ImpactReport | ImpactUnavailable)[]>;
+    /** One comparison: nx affected from ITS base, with NO `--head`, so uncommitted work counts. */
+    scan(workspaceRoot: string, graph: EnhancedGraph, comparison: ImpactComparison, owners?: SharedOwners): Promise<ImpactReport | ImpactUnavailable>;
+    /**
+     * An empty scan is still an ANSWER (available, zero sets): a fresh branch with a clean tree has
+     * simply changed nothing yet, and the page says so instead of disabling Impact.
+     */
+    emptyNote(comparison: ImpactComparison, changedFiles: number, short: string): string;
     /** Changed files no project owns; none are claimed when ownership itself was unavailable. */
     globalFiles(files: string[], owners: Map<string, string>): string[];
     /**
@@ -131,23 +252,30 @@ export declare class NxImpactScanner {
     touched(affected: string[], files: string[], owners: Map<string, string>): string[];
     /** The JSON list, narrowed to projects the graph draws; null when it is not a list of names. */
     parse(json: string, graph: EnhancedGraph): string[] | null;
-    /** Ownership failing is not fatal: the set then shows in one shade, all "affected". */
-    private owners;
+    private report;
     private ids;
 }
 /** Writes (or removes) the sidecar, self-ignored, beside architecture/dependencies.html. */
 export declare class ImpactSidecar {
     /** Never throws: a sidecar that cannot be written just leaves Impact disabled on the page. */
-    write(architectureDir: string, report: ImpactReport): string | null;
-    /** A stale sidecar from an earlier branch must never be shown as this branch's impact. */
+    write(architectureDir: string, data: ImpactSidecarData): string | null;
+    /** A stale sidecar from an earlier checkout must never be shown as this one's impact. */
     remove(architectureDir: string): void;
-    script(report: ImpactReport): string;
+    script(data: ImpactSidecarData): string;
 }
-/** The generator's one call: scan, write, and report the result and its cost in one line. */
+/** The executors' one call: resolve, scan each comparison, write, and report one line per comparison. */
 export declare class ImpactRefresh {
     private readonly scanner;
     private readonly sidecar;
-    constructor(scanner?: NxImpactScanner, sidecar?: ImpactSidecar);
-    /** Never throws — Impact is optional, generation is not. */
-    run(architectureDir: string, workspaceRoot: string, graph: EnhancedGraph): Promise<string>;
+    private readonly resolver;
+    constructor(scanner?: NxImpactScanner, sidecar?: ImpactSidecar, resolver?: ImpactScopeResolver);
+    /**
+     * Scans the comparisons in `kinds` that exist here (`VISUALIZE_IMPACT_KINDS` /
+     * `GENERATE_IMPACT_KINDS`). Never throws — Impact is optional, generation is not.
+     */
+    run(architectureDir: string, workspaceRoot: string, graph: EnhancedGraph, kinds: readonly ImpactKind[]): Promise<string>;
+    /** The plan's default when that scan is available, else the first available one. */
+    private defaultKind;
+    private none;
+    private line;
 }