@webpieces/nx-webpieces-rules 0.4.919 → 0.4.921

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

@@ -1,5 +1,5 @@
 /**
- * Impact mode's data: what one COMPARISON's build looks like, in three shades (plus untouched grey).
+ * Impact mode's data: what one COMPARISON's build looks like, and WHY each project is in it.
  *
  * There are two comparisons, and only two (#1163). Both end at the WORKING TREE, so uncommitted and
  * untracked work counts in either:
@@ -25,15 +25,13 @@
  *  - 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. 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.
+ *    inputs, namedInputs, implicitDependencies, nested roots and deleted files. It never reads
+ *    NX_BASE/NX_HEAD, whose value depends on whoever launched the process.
+ *  - WHY each affected project is in it (#1264) — changed, dependent (with the edge path), implicitly
+ *    touched (with the target, glob and file) or root-file touched — comes from nx's OWN affected
+ *    locators, run in-process against the workspace's own nx (graph-impact-reasons.ts). They are
+ *    loaded ONCE and shared by every comparison. 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,
@@ -52,7 +50,12 @@
  * stale one is removed) and the page disables Impact with a one-line reason. It never fails
  * generation.
  */
+import type { NxJsonConfiguration, ProjectGraph } from '@nx/devkit';
+import type { FileChange } from 'nx/src/project-graph/file-utils';
+import type { PackageJson } from 'nx/src/utils/package-json';
 import { DiffScope } from '@webpieces/rules-config';
+import { AffectedClassification, AffectedClassifier, AffectedReason, WorkspaceNx } from './graph-impact-reasons';
+import { EdgeChangeScanner, EdgeDiffReport, LiveGraphSource } from './graph-edge-diff';
 import type { EnhancedGraph } from './graph-sorter';
 /** Relative to the architecture/ directory the page lives in; the page's `<script src>`. */
 export declare const IMPACT_SIDECAR_DIR = ".impact";
@@ -84,10 +87,16 @@ export declare class ImpactReport {
     readonly reason: string;
     /** The base's short sha ('' when there is none). */
     readonly base: string;
-    /** Affected AND owning a changed file (node ids). */
+    /** Affected AND owning a changed file (node ids): "changed". */
     readonly touched: string[];
-    /** Affected but owning no changed file (node ids): their ci re-runs. */
-    readonly affected: string[];
+    /** Affected through dependency edges from a changed or touched project (node ids). */
+    readonly dependents: string[];
+    /** Affected because a `{workspaceRoot}` target input matched a changed file (node ids). */
+    readonly implicit: string[];
+    /** Affected by a lockfile, package.json, tsconfig.base.json, nx.json or deleted-config change (node ids). */
+    readonly rootFile: string[];
+    /** Affected, and nothing here could say why (node ids). Never shown as a dependent. */
+    readonly unexplained: string[];
     /**
      * Transitive dependencies of the affected set that are NOT affected (node ids). `ci` dependsOn
      * `^build`, so they must exist as build output although their inputs did not change: nx
@@ -98,16 +107,16 @@ export declare class ImpactReport {
     readonly changedFiles: number;
     /**
      * Transitive dependencies of the TOUCHED set that are not touched themselves (node ids): the
-     * Filter popover's "Changed + dependencies". ("Changed + dependents" is touched + affected,
-     * which nx already computed as the dependents whose tests re-run.)
+     * Filter popover's "Changed + dependencies". ("Changed + dependents" is every affected project.)
      */
     readonly dependencies: string[];
     /**
      * Changed files no project owns (repo-relative, sorted): workspace-global inputs such as
-     * pnpm-lock.yaml. When nothing is touched they are WHY everything is affected, and the
-     * legend names them. Empty when nx's file ownership was unavailable — then nothing is known.
+     * pnpm-lock.yaml. Empty when nx's locators were unavailable — then nothing is known.
      */
     readonly globalFiles: string[];
+    /** WHY each affected project is in the build (graph-impact-reasons.ts): one per affected node. */
+    readonly reasons: AffectedReason[];
     constructor(kind: ImpactKind, 
     /** What the page says this scan compares, e.g. "Changed on this branch (since abc1234)". */
     label: string, 
@@ -117,10 +126,16 @@ export declare class ImpactReport {
     reason: string, 
     /** The base's short sha ('' when there is none). */
     base: string, 
-    /** Affected AND owning a changed file (node ids). */
+    /** Affected AND owning a changed file (node ids): "changed". */
     touched: string[], 
-    /** Affected but owning no changed file (node ids): their ci re-runs. */
-    affected: string[], 
+    /** Affected through dependency edges from a changed or touched project (node ids). */
+    dependents: string[], 
+    /** Affected because a `{workspaceRoot}` target input matched a changed file (node ids). */
+    implicit: string[], 
+    /** Affected by a lockfile, package.json, tsconfig.base.json, nx.json or deleted-config change (node ids). */
+    rootFile: string[], 
+    /** Affected, and nothing here could say why (node ids). Never shown as a dependent. */
+    unexplained: string[], 
     /**
      * Transitive dependencies of the affected set that are NOT affected (node ids). `ci` dependsOn
      * `^build`, so they must exist as build output although their inputs did not change: nx
@@ -130,22 +145,40 @@ export declare class ImpactReport {
     buildInputs: string[], changedFiles: number, 
     /**
      * Transitive dependencies of the TOUCHED set that are not touched themselves (node ids): the
-     * Filter popover's "Changed + dependencies". ("Changed + dependents" is touched + affected,
-     * which nx already computed as the dependents whose tests re-run.)
+     * Filter popover's "Changed + dependencies". ("Changed + dependents" is every affected project.)
      */
     dependencies: string[], 
     /**
      * Changed files no project owns (repo-relative, sorted): workspace-global inputs such as
-     * pnpm-lock.yaml. When nothing is touched they are WHY everything is affected, and the
-     * legend names them. Empty when nx's file ownership was unavailable — then nothing is known.
+     * pnpm-lock.yaml. Empty when nx's locators were unavailable — then nothing is known.
      */
-    globalFiles: string[]);
+    globalFiles: string[], 
+    /** WHY each affected project is in the build (graph-impact-reasons.ts): one per affected node. */
+    reasons: AffectedReason[]);
+}
+/** The one-line count split, shared by the executor's console line (the page builds the same line). */
+export declare class ImpactCounts {
+    /** `8 changed · 3 dependents · 22 implicitly touched (runtime-wiring-check inputs) · 47 dependencies`. */
+    line(report: ImpactReport): string;
+    private targets;
 }
 /** 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);
+    /**
+     * The edges this branch gained or lost since its FORK POINT, the live graph against the fork
+     * point's committed one (graph-edge-diff.ts, #1264). One per sidecar: it does not depend on
+     * which scan is shown.
+     */
+    readonly edges: EdgeDiffReport;
+    constructor(scans: ImpactReport[], defaultKind: ImpactKind, 
+    /**
+     * The edges this branch gained or lost since its FORK POINT, the live graph against the fork
+     * point's committed one (graph-edge-diff.ts, #1264). One per sidecar: it does not depend on
+     * which scan is shown.
+     */
+    edges: EdgeDiffReport);
 }
 /** A scan (or a whole plan) that could not produce an answer. */
 export declare class ImpactUnavailable {
@@ -210,49 +243,64 @@ export declare class NxCli {
     /** Resolved the way node would from the workspace, so a linked worktree finds its main tree's nx. */
     private binary;
 }
-/** nx's own file → project ownership, from the public devkit file map. Injected for specs. */
-export declare class ProjectFileOwners {
-    owners(): Promise<Map<string, string>>;
+/**
+ * The workspace's nx facts every comparison classifies against: its project graph (with npm nodes
+ * and every edge), nx.json, package.json, and nx's own affected locators. Subclassed by specs.
+ */
+export declare class AffectedContext {
+    readonly graph: ProjectGraph;
+    readonly nxJson: NxJsonConfiguration;
+    readonly packageJson: PackageJson;
+    readonly classifier: AffectedClassifier;
+    private readonly nx;
+    constructor(graph: ProjectGraph, nxJson: NxJsonConfiguration, packageJson: PackageJson, classifier: AffectedClassifier, nx: WorkspaceNx | null);
+    /** nx's FileChange list for `files`, base → working tree. */
+    fileChanges(files: string[], base: string): FileChange[];
+}
+/** Loads the workspace's nx facts. Injected so specs never load the real project graph. */
+export declare class AffectedContextLoader {
+    load(workspaceRoot: string): Promise<AffectedContext>;
 }
 /**
- * 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".
+ * The context, loaded at most ONCE however many comparisons ask for it. Failing is not fatal: every
+ * affected project is then "unexplained", with this error as its reason — never a dependent.
  */
-export declare class SharedOwners {
-    private readonly ownership;
+export declare class SharedContext {
+    private readonly loader;
+    private readonly workspaceRoot;
     private pending;
-    constructor(ownership: ProjectFileOwners);
-    get(): Promise<Map<string, string>>;
+    constructor(loader: AffectedContextLoader, workspaceRoot: string);
+    get(): Promise<AffectedContext | Error>;
     private load;
 }
 export declare class NxImpactScanner {
     private readonly diffScope;
     private readonly nx;
-    private readonly ownership;
+    private readonly loader;
     private readonly names;
-    constructor(diffScope?: DiffScope, nx?: NxCli, ownership?: ProjectFileOwners);
-    /** Every comparison, in order, sharing one ownership map. */
+    constructor(diffScope?: DiffScope, nx?: NxCli, loader?: AffectedContextLoader);
+    /** Every comparison, in order, sharing one nx context. */
     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>;
+    scan(workspaceRoot: string, graph: EnhancedGraph, comparison: ImpactComparison, context?: SharedContext): Promise<ImpactReport | ImpactUnavailable>;
+    /** nx's locators' answer; any failure makes every affected project "unexplained", with the reason. */
+    classify(context: AffectedContext | Error, files: string[], base: string, affected: string[]): Promise<AffectedClassification>;
     /**
      * 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[];
     /**
      * Every transitive dependency of `roots` that is not itself one of them: a pure downward walk over
      * the graph's own dependsOn edges, no nx call. Of the affected set these are the build inputs; of
      * the touched set, "Changed + dependencies".
      */
     buildInputs(roots: string[], graph: EnhancedGraph): string[];
-    /** Affected projects that own one of the changed files, by nx's own ownership. */
-    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;
+    /** The JSON list of project names, sorted; null when it is not a list of names. */
+    parse(json: string): string[] | null;
+    /** The drawn projects only: a reason for a project the page does not draw has nowhere to show. */
     private report;
+    private empty;
     private ids;
 }
 /** Writes (or removes) the sidecar, self-ignored, beside architecture/dependencies.html. */
@@ -268,12 +316,16 @@ export declare class ImpactRefresh {
     private readonly scanner;
     private readonly sidecar;
     private readonly resolver;
-    constructor(scanner?: NxImpactScanner, sidecar?: ImpactSidecar, resolver?: ImpactScopeResolver);
+    private readonly edges;
+    constructor(scanner?: NxImpactScanner, sidecar?: ImpactSidecar, resolver?: ImpactScopeResolver, edges?: EdgeChangeScanner);
     /**
      * Scans the comparisons in `kinds` that exist here (`VISUALIZE_IMPACT_KINDS` /
-     * `GENERATE_IMPACT_KINDS`). Never throws — Impact is optional, generation is not.
+     * `GENERATE_IMPACT_KINDS`), and the edge changes since the fork point against the LIVE graphs
+     * `live` computes. Never throws — Impact is optional, generation is not.
      */
-    run(architectureDir: string, workspaceRoot: string, graph: EnhancedGraph, kinds: readonly ImpactKind[]): Promise<string>;
+    run(architectureDir: string, workspaceRoot: string, graph: EnhancedGraph, kinds: readonly ImpactKind[], live: LiveGraphSource): Promise<string>;
+    /** `✅ Edges since abc1234: dependencies 1 gained · 1 lost; runtime 0 gained · 0 lost`, or why not. */
+    private edgeLine;
     /** The plan's default when that scan is available, else the first available one. */
     private defaultKind;
     private none;