@abloh/repository 1.0.1 → 1.0.2-staging.34831384081

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { RepoReader, PackageManifestReading, MatrixLeg, MatrixLegs, FailFastReading, SetupCandidateTrigger, SetupWorkflowCaller, SetupCandidateGate, NativeVocabulary, SetupFailFast, SetupCandidateExclusion, Refusal, YamlQuote, CoverageProviderChoice, MatrixValue, WorkflowNodePin, SetupScriptStep, ValueOrigin, CommandScriptHop, AngularTestTarget, PreparedTestCommand, InitFailureClass, InitQuestionKey, EnvironmentConfig, TargetSelectionKind, EvidenceOutputId, resolvePreparedTestCommand, MeasurementPlan, PackageExclusion } from '@abloh/core';
+import { RepoReader, PackageManifestReading, ProposedFile, MatrixLeg, MatrixLegs, FailFastReading, SetupCandidateTrigger, SetupWorkflowCaller, SetupCandidateGate, NativeVocabulary, SetupFailFast, SetupCandidateExclusion, Refusal, YamlQuote, CoverageProviderChoice, MatrixValue, WorkflowNodePin, SetupScriptStep, ValueOrigin, CommandScriptHop, AngularTestTarget, PreparedTestCommand, InitFailureClass, InitQuestionKey, EnvironmentConfig, TargetSelectionKind, EvidenceOutputId, resolvePreparedTestCommand, MeasurementPlan, PackageExclusion } from '@abloh/core';
 export { SETUP_STEP_ACTION, SETUP_STEP_IF, SETUP_STEP_JOB_STATUS, SETUP_STEP_NAME, setupStepIf } from '@abloh/core';
 import { JasmineSuite, ProofRunner, StrykerMutationRunner } from '@abloh/measure';
 
@@ -56,6 +56,17 @@ interface RepoAccess {
 }
 /** The access `abloh init` and every existing caller get: a checkout on this machine. */
 declare function diskRepoAccess(repoDir: string): RepoAccess;
+/**
+ * THE SAME ACCESS, READING {@link ProposedFile} BYTES FOR THE PATHS SOMEBODY HAS AGREED TO.
+ *
+ * WHAT IT IS FOR (the audit's class 5, 2026-09-12). `abloh init` has to draft as if an answered edit
+ * to a file of the maintainer's were already there, and it used to do that by writing the file and
+ * reading it back - before the confirmation that says abloh has written nothing yet. The root, the
+ * spellings of it and the realpath rule are untouched: only what the reader answers moves.
+ *
+ * An empty list returns the access itself, so the ordinary road pays nothing.
+ */
+declare function overlayRepoAccess(base: RepoAccess, files: readonly ProposedFile[]): RepoAccess;
 /**
  * The repository-relative path an absolute one names, or null when it names nothing in here.
  *
@@ -88,6 +99,257 @@ declare function accessKind(ctx: RepoAccess, absolute: string): "file" | "direct
 /** Immediate child directory NAMES of a path, or none when it is absent or unreadable. */
 declare function accessSubdirectories(ctx: RepoAccess, absolute: string): string[];
 
+/**
+ * Workspace AGGREGATORS - turbo, lage and nx - and the one monorepo shape whose packages are not
+ * declared in a manifest at all.
+ *
+ * TWO FACTS, ONE FILE, because they are the two halves of the same question. A repository whose
+ * root `scripts.test` is `turbo run test` has not told us how to run a suite; it has told us that
+ * every package runs its own. So the aggregator's name is a routing fact (this root is not a
+ * runner - go and measure the packages), and for the Nx flavour that declares no `workspaces` the
+ * package list has to come from somewhere other than the root manifest.
+ *
+ * WHY THE AGGREGATOR IS NOT A RUNNER, and why leaving it to classify as the generic `command`
+ * adapter was wrong in two directions:
+ *
+ *   1. it MEASURES THE WHOLE REPOSITORY. `npm test` at the root of a Turborepo runs every
+ *      package's suite through one process tree, so Stryker's command runner re-runs all of them
+ *      per mutant and diff coverage has no single provider to read - the exact shape the multi-suite
+ *      fanout work refused for `vitest a && vitest b`, one level up: packages compose the way
+ *      suites do.
+ *   2. it can be READ AS A RUNNER BY ACCIDENT. `runnerNamesInScript` looks for a runner binary
+ *      anywhere in the script, and `turbo run test --filter=./packages/jest` ends in the bare token
+ *      `jest` behind a path separator, which is exactly the shape that function admits. That
+ *      repository would have classified as a direct jest project and had jest's coverage flags
+ *      appended to a turbo invocation.
+ *
+ * So an aggregator invocation is recognised BEFORE any runner name is looked for, and a package
+ * whose test script is one classifies as no runner at all - the same treatment `npm-run-all`
+ * already gets in {@link classifyPackageManifest}, for the same reason.
+ *
+ * PACKAGE-BASED MONOREPOS ARE UNAFFECTED BY DESIGN. A root that declares `workspaces` (or a
+ * `pnpm-workspace.yaml`) already rides per-package composition, whatever aggregator its scripts
+ * name - the aggregator is ignored, and that is the correct outcome, not an oversight. What is new
+ * here is the INTEGRATED Nx flavour, which declares no `workspaces` field at all: its projects are
+ * declared one `project.json` at a time and the root carries `nx.json`. Without a reader for that
+ * shape the selector found no workspace definition, skipped, and the run fell back to measuring the
+ * aggregator command at the root.
+ *
+ * THE THIRD WORKING DIRECTORY, added 2026-08-16. An integrated-Nx project declares its suite through
+ * an executor Nx runs FROM THE WORKSPACE ROOT against a root-relative config, and per-package
+ * composition had only two positions for a working directory - the repository root, measuring the
+ * repository, or a package's own directory, measuring that package. So those projects were honest
+ * excluded rows. {@link WorkspaceRootSuite} is the third position: the runner runs where the
+ * declaration says it runs, and the measurement is scoped to the project directory. It is keyed on
+ * that structural fact and never on the name of the tool that produced it.
+ *
+ * Everything here is fail-closed. A script that is not exactly one aggregator invocation is not an
+ * aggregator, an `nx.json` that does not parse yields no projects, and a project whose test target
+ * this file cannot drive is named as unmeasurable rather than guessed at.
+ */
+/**
+ * The workspace task runners. `nx` covers both flavours; the flavour is a separate fact.
+ *
+ * `lerna` IS ONE OF THEM AND ITS ONLY SHAPE IS `lerna run <task>`. It has no subcommand that runs a
+ * suite of its own - `lerna test` was removed in v3 - so a script that is exactly `lerna run test`
+ * is the same routing fact `turbo run test` is, spelled by the older tool: one suite per package,
+ * each with its own runner and its own coverage. Measuring it as one command re-runs every
+ * package's suite per mutant, which is precisely what this vocabulary exists to prevent.
+ */
+type AggregatorTool = "turbo" | "lage" | "nx" | "lerna";
+interface AggregatorInvocation {
+    tool: AggregatorTool;
+    /**
+     * The task names the invocation selects, when they are stated positionally or through nx's
+     * `-t`/`--target`. Empty when the invocation selects its tasks some other way (an nx
+     * `run-many` with no target reads its own default) - the tool is still the routing fact.
+     */
+    tasks: string[];
+}
+/**
+ * The aggregator a test script invokes, or null when it invokes none.
+ *
+ * ONE STAGE ONLY, deliberately. A script that composes an aggregator with anything else
+ * (`nx run-many -t lint && nx run-many -t test`, `turbo run test | tee log`) is left to the
+ * existing fanout and gate machinery, which already reads chains; claiming the aggregator for a
+ * composed script would take a routing decision on a script this file has not read whole.
+ */
+declare function aggregatorInvocation(testScript: string | null): AggregatorInvocation | null;
+/**
+ * The tasks half of an aggregator invocation, as one printable phrase for a refusal message.
+ *
+ * An invocation that names no task reads its selection from configuration this file does not
+ * parse, and saying so is more honest than naming a task nobody read.
+ *
+ * COMMAS ONCE THERE ARE MORE THAN TWO, because this sentence became reachable for a long list on
+ * 2026-09-01: it was only ever produced for a directly-written `turbo run test` until the aliased
+ * root started reaching it, and TanStack/query's run-many names eight tasks. Eight joined by "and"
+ * is not a sentence anybody reads.
+ */
+declare function aggregatorTaskPhrase(invocation: AggregatorInvocation): string;
+/** One integrated-Nx project: its directory and what its own `project.json` says about testing. */
+interface NxProject {
+    /** Repository-relative project directory, never "" (the workspace root is not a project). */
+    directory: string;
+    /** The project's own name, when it declares one. */
+    name: string | null;
+    /** What the project's `test` target is, once read. */
+    test: NxTestTarget;
+}
+type NxTestTarget = {
+    state: "runner";
+    runner: string;
+    command: string;
+} | ({
+    state: "workspace-root";
+} & WorkspaceRootSuite) | {
+    state: "unmeasurable";
+    reason: string;
+    remedy: string;
+};
+/**
+ * A suite whose runner runs FROM THE WORKSPACE ROOT against a root-relative config, while the
+ * measurement it produces belongs to one project directory.
+ *
+ * THE STRUCTURAL FACT, and it is deliberately not "this repository uses Nx". Two positions used to
+ * be the whole vocabulary - a suite runs at the repository root and measures the repository, or a
+ * suite runs inside a package and measures that package. This is the third: the working directory
+ * and the measured directory are DIFFERENT, and the declaration says which is which. Nx's official
+ * executors are the first shape that produces it; nothing below reads the string "nx" to decide.
+ *
+ * Every field is what the run needs to act on it, and each is a fact somebody wrote down:
+ *  - `runner` is a runner the existing adapters already drive; an executor that maps to none stays
+ *    an excluded row, which is the boundary this mode does not widen.
+ *  - `configFile` is the workspace-root-relative config the declaration names. Never guessed: a
+ *    target that names none is excluded, because running a root-found config against one project
+ *    would measure a suite nobody selected.
+ *  - `directory` is the measured project, which is what scopes coverage, mutation and attribution.
+ *  - `declaredBy` is the executor that said so, carried for the log and the artifact.
+ */
+interface WorkspaceRootSuite {
+    runner: "jest" | "vitest";
+    /** Workspace-root-relative config file the runner is pointed at. */
+    configFile: string;
+    /** Repository-relative directory whose measurement this suite produces. */
+    directory: string;
+    /** The declaration this was read from, e.g. `@nx/jest:jest`. */
+    declaredBy: string;
+    /** The runner invocation, run from the workspace root. */
+    command: string;
+}
+/**
+ * Read one project's `test` target into the answers per-package composition can act on.
+ *
+ * A `run-commands` target whose command is one literal runner invocation AND whose `cwd` is the
+ * project's own directory is drivable exactly as a package script is - it is the same invocation,
+ * written in a different file. Everything else is named.
+ */
+declare function classifyNxTestTarget(projectJson: unknown, directory: string): NxTestTarget;
+/**
+ * Enumerate an integrated-Nx workspace's projects from the files a tree listing already has.
+ *
+ * READ THROUGH A SEAM, on purpose. Selection reads the TRUSTED merge-base tree and `abloh prepare`
+ * reads the working tree; both must enumerate identically or they desync on the same repository -
+ * the same rule `classifyPackageManifest` carries for manifests. So this function takes the path
+ * list and a reader and never touches the filesystem itself.
+ *
+ * @param paths every repository-relative path in the tree
+ * @param readFile the bytes of one path, or null when absent/unreadable
+ */
+declare function enumerateNxProjects(paths: readonly string[], readFile: (path: string) => string | null, limit: number): NxProject[];
+
+/**
+ * THE SUITE BEHIND AN AGGREGATOR, FOLLOWED TO THE RUNNER THAT RUNS IT.
+ *
+ * WHAT WAS WRONG. `aggregatorInvocation` one file over answers the ROUTING question - this root is
+ * not a runner, go and measure the packages - and nothing ever walked the road it points down. So a
+ * repository whose whole test script is one aggregator invocation was read as a script naming no
+ * runner, and `abloh init` drafted the aggregator as the test command with a note saying the
+ * baseline would report nothing. `TanStack/query` (`pnpm run test:ci` -> `nx run-many
+ * --targets=...,test:lib,...`) and `discordjs/discord.js` (`turbo run test --concurrency=4`) both
+ * produced the same sentence: "nothing in it invokes a test runner abloh recognizes", on
+ * repositories where 25 and 13 packages respectively declare a vitest suite the same reading
+ * already resolves per package.
+ *
+ * SO THE CHAIN IS FOLLOWED ONCE, HERE, AND IT IS THE READING THAT WAS ALREADY THERE. Nothing in
+ * this file is a new grammar: the root's own invocation and its task list come from
+ * {@link classifyWithAliasHop}, the packages come from the workspace declaration's own enumeration,
+ * and each package's suite is read by {@link classifyPackageManifest} under exactly the task names
+ * the root wrote down. A package is admitted here on the terms a `test` script is admitted on
+ * everywhere else, because it is the same function that admits it.
+ *
+ * WHAT THE CALLER DOES WITH IT IS THE CALLER'S. This answers which packages the aggregator reaches
+ * and what runs each one's suite; whether that becomes a question, a draft or a refusal is decided
+ * where those are decided. `abloh init` spends it by drafting from one of these packages - the road
+ * a workspace root with no test script at all has taken since 2026-08-26 - reading `packages`, the
+ * enumeration's own `refusals` and `unreadSelection`; `gaps` and `excluded` are the rest of this
+ * reading's account of itself, for a caller that has somewhere to put them.
+ *
+ * IT NEVER SILENTLY NARROWS OR SILENTLY WIDENS. Only a plain path-glob `--exclude` is applied,
+ * because that is the one selection form whose meaning is a directory and nothing else; every other
+ * selection flag names a PROJECT, and applying one would be a second reading of somebody's workspace
+ * graph. A flag this reading cannot apply is carried on {@link AggregatorChain.unreadSelection}
+ * rather than dropped - which is `docs/lessons/a-discarded-input-is-never-silent.md` over a filter -
+ * and `abloh init` states it beside the package list a maintainer is choosing from.
+ */
+
+/** One package the aggregator reaches, and what runs its suite. */
+interface AggregatorChainPackage {
+    /** Repository-relative package directory. */
+    directory: string;
+    /**
+     * The script key its suite was read from.
+     *
+     * `test` for a package that declares one - which is what `discordjs/discord.js`'s packages do -
+     * and one of the aggregator's own task names otherwise, which is the shape `TanStack/query` has:
+     * not one of its 27 packages declares `test`, and `test:lib` is the key the root wrote down.
+     */
+    task: string;
+    /** That script's text, exactly as the package spells it. */
+    script: string;
+    /** The runner it runs. */
+    runner: string;
+    /**
+     * The runner config that suite is measured against, repository-relative, or null when abloh found
+     * none. A path the script names itself wins; otherwise it is the config file sitting in the
+     * package's own directory, which is where the runner looks from when the script names none.
+     */
+    configFile: string | null;
+}
+/** A package the aggregator reaches whose suite this reading could not resolve, and why. */
+interface AggregatorChainGap {
+    directory: string;
+    reason: string;
+}
+interface AggregatorChain {
+    /** The workspace task runner the root's test script delegates to. */
+    tool: AggregatorTool;
+    /** The task names that invocation selects, empty when it selects them some other way. */
+    tasks: readonly string[];
+    /** Every package it reaches that answers one of those tasks with a suite abloh can measure. */
+    packages: readonly AggregatorChainPackage[];
+    /** Every package it reaches that answers none, with the reason it was read as none. */
+    gaps: readonly AggregatorChainGap[];
+    /**
+     * Selection flags on the invocation this reading does not model, verbatim.
+     *
+     * Empty is the ordinary case and the package list is then exactly what the aggregator runs. A
+     * non-empty list means the list may be WIDER than what runs, never narrower, and a caller that
+     * states the set has to say so.
+     */
+    unreadSelection: readonly string[];
+    /** Packages a readable `--exclude` glob took out of the list. */
+    excluded: readonly string[];
+    /** What the enumeration could not see, in its own words. */
+    refusals: readonly string[];
+}
+/**
+ * FOLLOW THE ROOT'S TEST SCRIPT THROUGH THE AGGREGATOR TO THE PACKAGES THAT RUN THE SUITES.
+ *
+ * Null when this root's test script does not delegate at all, which is nearly every repository.
+ */
+declare function aggregatorChain(repoDir: string, ctx?: RepoAccess): AggregatorChain | null;
+
 /**
  * WHICH REPOSITORIES ACTUALLY HAVE A BROWSER LANE, read from what they committed rather than from
  * what they called a script.
@@ -975,6 +1237,20 @@ interface CiRecipe {
      * sets environment values Abloh has no key for, a build scoped to one workspace package.
      */
     notices: readonly string[];
+    /**
+     * THE CHOSEN JOB'S OWN STEPS THAT ABLOH READ AND DID NOT COPY INTO `.abloh/setup.sh`.
+     *
+     * THE RULING (the captain, 2026-09-12, review finding F4): init copies only the steps the tests
+     * need, a lint, format, docs or publish step is not one of them, and the maintainer is told which
+     * ones were left out. `honojs/hono` is the repository that earned it - its job runs `format`,
+     * `lint` and `editorconfig-checker` before its suite, and the checker downloads a release binary
+     * and cannot, so a repository that was never measured stopped on a step about trailing newlines.
+     *
+     * NOT {@link refusal} AND NOT A REFUSAL'S LIST. Those say abloh could not READ a step; these say
+     * abloh read it and the suite does not read what it produces. Only the first is a gap in abloh's
+     * reading, and folding the two would tell a maintainer to go and copy in a linter.
+     */
+    stepsNotCopied: readonly CiDroppedStep[];
 }
 type AptReading = {
     ok: true;
@@ -1029,6 +1305,21 @@ interface NodeEnvironment {
  *   cell does Abloh's step actually run on".
  */
 declare function readCiNodeDeclaration(raw: string | null, matrix: unknown, reader: RepoReader, leg?: MatrixLeg | null | undefined, env?: NodeEnvironment): CiNodeVersion | null;
+/** One step of a candidate job abloh read and declined to translate, with its own sentence. */
+/**
+ * ONE STEP ABLOH READ AND DID NOT COPY: where it sits, what it runs, and why it was left out.
+ *
+ * THE COMMAND IS THE MAINTAINER'S OWN TEXT, so it is local-only wherever it is shown - the same
+ * rule `setup-ci-steps-unread` already carries its step bodies under.
+ */
+interface CiDroppedStep {
+    /** 1-based, as a maintainer counts the `steps:` of their own job. Null for Travis and CircleCI. */
+    step: number | null;
+    /** The step's own command line. */
+    command: string;
+    /** Why the suite does not need it, in the reading's own words. */
+    why: string;
+}
 /**
  * DO TWO JOB REFERENCES NAME THE SAME JOB, whichever spelling each of them uses?
  *
@@ -2219,8 +2510,27 @@ interface DraftService {
  *
  * A constant because a re-run has to RECOGNIZE it: the block is replaced from its own `environment:`
  * line down, and a header left stranded above the replacement appears twice in the customer's file.
+ *
+ * IT NAMES CI RATHER THAN A CONTAINER (the audit of 2026-09-12, 10.4). "the proof container" is a
+ * thing one road builds: a run on the maintainer's own machine measures a copy of their own tree
+ * with their own installed dependencies, and reads none of the keys under this header. The block is
+ * still written on both roads, because it is what their CI needs the day they add abloh's check
+ * there, and the header now says so instead of describing work that is not happening.
  */
-declare const ENVIRONMENT_BLOCK_HEADER = "# Rebuild recipe for the proof container. Comments name the source file.";
+declare const ENVIRONMENT_BLOCK_HEADER = "# How CI rebuilds this project for abloh's check. Comments name the source file.";
+/**
+ * HEADERS THIS COMMAND USED TO WRITE, so a re-run still recognizes a file it wrote before.
+ *
+ * WHY IT EXISTS. The recognition above is an exact string match. Change the constant with no list
+ * beside it and every `abloh.yml` already carrying the old line gets the new header written above
+ * the old one - the exact duplication that constant's own header warns about, arriving through the
+ * one edit it did not anticipate.
+ *
+ * IT ONLY GROWS. A line here is a line some repository has committed, and nothing rewrites it.
+ */
+declare const RETIRED_ENVIRONMENT_BLOCK_HEADERS: readonly string[];
+/** Is this line an environment-block header this command has ever written? */
+declare function isEnvironmentBlockHeader(line: string): boolean;
 /**
  * WHAT ABLOH READ ABOUT THE JOB ITS STEP RIDES, as the contract will state it.
  *
@@ -2319,7 +2629,25 @@ declare function initStepRole(what: string): "systemPackages" | "installCommand"
  * pinned packages alone.
  */
 declare function systemPackagesStep(pinned: readonly ConfigSystemPackage[]): SetupScriptStep | null;
-declare function setupScriptSteps(input: ConfigInput): SetupScriptStep[];
+/**
+ * EVERYTHING {@link setupScriptSteps} READS, AND NOTHING ELSE.
+ *
+ * WHY IT IS NARROW (the captain's second ruling of 2026-09-15, round-2 maintainer review C1). The
+ * proof-image check has to know what abloh's own script puts on PATH before the suite runs, and the
+ * script is the source of truth for that - so `environment-check.ts` composes the steps and reads
+ * them. It is asked BEFORE the check runs, which is before the whole contract exists, and a caller
+ * that had to build a `ConfigInput` to ask would end up building a second one.
+ *
+ * A `ConfigInput` still satisfies it structurally, so the one composer serves both callers exactly
+ * as {@link systemPackagesStep} already serves two. A second derivation of what this script runs is
+ * the divergence `script-runs.ts` exists to end, one layer down.
+ */
+type SetupScriptInput = Pick<ConfigInput, "systemPackages" | "installCommand" | "installUnlocked" | "installEnvironment" | "setupCommands"> & {
+    readonly evidence: {
+        readonly installCommand: string;
+    };
+};
+declare function setupScriptSteps(input: SetupScriptInput): SetupScriptStep[];
 
 /**
  * WHERE AN ANSWER IS APPLIED, because three of them are not values in the contract at all.
@@ -2500,157 +2828,6 @@ declare function denoLockfilePath(dir: string, readText?: ReadTextAt): string |
  */
 declare function scriptRunsDenoTest(testScript: string | null): boolean;
 
-/**
- * Workspace AGGREGATORS - turbo, lage and nx - and the one monorepo shape whose packages are not
- * declared in a manifest at all.
- *
- * TWO FACTS, ONE FILE, because they are the two halves of the same question. A repository whose
- * root `scripts.test` is `turbo run test` has not told us how to run a suite; it has told us that
- * every package runs its own. So the aggregator's name is a routing fact (this root is not a
- * runner - go and measure the packages), and for the Nx flavour that declares no `workspaces` the
- * package list has to come from somewhere other than the root manifest.
- *
- * WHY THE AGGREGATOR IS NOT A RUNNER, and why leaving it to classify as the generic `command`
- * adapter was wrong in two directions:
- *
- *   1. it MEASURES THE WHOLE REPOSITORY. `npm test` at the root of a Turborepo runs every
- *      package's suite through one process tree, so Stryker's command runner re-runs all of them
- *      per mutant and diff coverage has no single provider to read - the exact shape the multi-suite
- *      fanout work refused for `vitest a && vitest b`, one level up: packages compose the way
- *      suites do.
- *   2. it can be READ AS A RUNNER BY ACCIDENT. `runnerNamesInScript` looks for a runner binary
- *      anywhere in the script, and `turbo run test --filter=./packages/jest` ends in the bare token
- *      `jest` behind a path separator, which is exactly the shape that function admits. That
- *      repository would have classified as a direct jest project and had jest's coverage flags
- *      appended to a turbo invocation.
- *
- * So an aggregator invocation is recognised BEFORE any runner name is looked for, and a package
- * whose test script is one classifies as no runner at all - the same treatment `npm-run-all`
- * already gets in {@link classifyPackageManifest}, for the same reason.
- *
- * PACKAGE-BASED MONOREPOS ARE UNAFFECTED BY DESIGN. A root that declares `workspaces` (or a
- * `pnpm-workspace.yaml`) already rides per-package composition, whatever aggregator its scripts
- * name - the aggregator is ignored, and that is the correct outcome, not an oversight. What is new
- * here is the INTEGRATED Nx flavour, which declares no `workspaces` field at all: its projects are
- * declared one `project.json` at a time and the root carries `nx.json`. Without a reader for that
- * shape the selector found no workspace definition, skipped, and the run fell back to measuring the
- * aggregator command at the root.
- *
- * THE THIRD WORKING DIRECTORY, added 2026-08-16. An integrated-Nx project declares its suite through
- * an executor Nx runs FROM THE WORKSPACE ROOT against a root-relative config, and per-package
- * composition had only two positions for a working directory - the repository root, measuring the
- * repository, or a package's own directory, measuring that package. So those projects were honest
- * excluded rows. {@link WorkspaceRootSuite} is the third position: the runner runs where the
- * declaration says it runs, and the measurement is scoped to the project directory. It is keyed on
- * that structural fact and never on the name of the tool that produced it.
- *
- * Everything here is fail-closed. A script that is not exactly one aggregator invocation is not an
- * aggregator, an `nx.json` that does not parse yields no projects, and a project whose test target
- * this file cannot drive is named as unmeasurable rather than guessed at.
- */
-/** The three workspace task runners. `nx` covers both flavours; the flavour is a separate fact. */
-type AggregatorTool = "turbo" | "lage" | "nx";
-interface AggregatorInvocation {
-    tool: AggregatorTool;
-    /**
-     * The task names the invocation selects, when they are stated positionally or through nx's
-     * `-t`/`--target`. Empty when the invocation selects its tasks some other way (an nx
-     * `run-many` with no target reads its own default) - the tool is still the routing fact.
-     */
-    tasks: string[];
-}
-/**
- * The aggregator a test script invokes, or null when it invokes none.
- *
- * ONE STAGE ONLY, deliberately. A script that composes an aggregator with anything else
- * (`nx run-many -t lint && nx run-many -t test`, `turbo run test | tee log`) is left to the
- * existing fanout and gate machinery, which already reads chains; claiming the aggregator for a
- * composed script would take a routing decision on a script this file has not read whole.
- */
-declare function aggregatorInvocation(testScript: string | null): AggregatorInvocation | null;
-/**
- * The tasks half of an aggregator invocation, as one printable phrase for a refusal message.
- *
- * An invocation that names no task reads its selection from configuration this file does not
- * parse, and saying so is more honest than naming a task nobody read.
- *
- * COMMAS ONCE THERE ARE MORE THAN TWO, because this sentence became reachable for a long list on
- * 2026-09-01: it was only ever produced for a directly-written `turbo run test` until the aliased
- * root started reaching it, and TanStack/query's run-many names eight tasks. Eight joined by "and"
- * is not a sentence anybody reads.
- */
-declare function aggregatorTaskPhrase(invocation: AggregatorInvocation): string;
-/** One integrated-Nx project: its directory and what its own `project.json` says about testing. */
-interface NxProject {
-    /** Repository-relative project directory, never "" (the workspace root is not a project). */
-    directory: string;
-    /** The project's own name, when it declares one. */
-    name: string | null;
-    /** What the project's `test` target is, once read. */
-    test: NxTestTarget;
-}
-type NxTestTarget = {
-    state: "runner";
-    runner: string;
-    command: string;
-} | ({
-    state: "workspace-root";
-} & WorkspaceRootSuite) | {
-    state: "unmeasurable";
-    reason: string;
-    remedy: string;
-};
-/**
- * A suite whose runner runs FROM THE WORKSPACE ROOT against a root-relative config, while the
- * measurement it produces belongs to one project directory.
- *
- * THE STRUCTURAL FACT, and it is deliberately not "this repository uses Nx". Two positions used to
- * be the whole vocabulary - a suite runs at the repository root and measures the repository, or a
- * suite runs inside a package and measures that package. This is the third: the working directory
- * and the measured directory are DIFFERENT, and the declaration says which is which. Nx's official
- * executors are the first shape that produces it; nothing below reads the string "nx" to decide.
- *
- * Every field is what the run needs to act on it, and each is a fact somebody wrote down:
- *  - `runner` is a runner the existing adapters already drive; an executor that maps to none stays
- *    an excluded row, which is the boundary this mode does not widen.
- *  - `configFile` is the workspace-root-relative config the declaration names. Never guessed: a
- *    target that names none is excluded, because running a root-found config against one project
- *    would measure a suite nobody selected.
- *  - `directory` is the measured project, which is what scopes coverage, mutation and attribution.
- *  - `declaredBy` is the executor that said so, carried for the log and the artifact.
- */
-interface WorkspaceRootSuite {
-    runner: "jest" | "vitest";
-    /** Workspace-root-relative config file the runner is pointed at. */
-    configFile: string;
-    /** Repository-relative directory whose measurement this suite produces. */
-    directory: string;
-    /** The declaration this was read from, e.g. `@nx/jest:jest`. */
-    declaredBy: string;
-    /** The runner invocation, run from the workspace root. */
-    command: string;
-}
-/**
- * Read one project's `test` target into the answers per-package composition can act on.
- *
- * A `run-commands` target whose command is one literal runner invocation AND whose `cwd` is the
- * project's own directory is drivable exactly as a package script is - it is the same invocation,
- * written in a different file. Everything else is named.
- */
-declare function classifyNxTestTarget(projectJson: unknown, directory: string): NxTestTarget;
-/**
- * Enumerate an integrated-Nx workspace's projects from the files a tree listing already has.
- *
- * READ THROUGH A SEAM, on purpose. Selection reads the TRUSTED merge-base tree and `abloh prepare`
- * reads the working tree; both must enumerate identically or they desync on the same repository -
- * the same rule `classifyPackageManifest` carries for manifests. So this function takes the path
- * list and a reader and never touches the filesystem itself.
- *
- * @param paths every repository-relative path in the tree
- * @param readFile the bytes of one path, or null when absent/unreadable
- */
-declare function enumerateNxProjects(paths: readonly string[], readFile: (path: string) => string | null, limit: number): NxProject[];
-
 /**
  * The tool that installs a repository's dependencies.
  *
@@ -3515,6 +3692,16 @@ interface ManifestClassification {
      * handed down; see {@link rootAggregatorTasks}.
      */
     aggregatorTasks: readonly string[];
+    /**
+     * The SCRIPT TEXT that aggregator invocation was read from, when it delegates.
+     *
+     * Carried for the same reason the task list is, one fact further: the invocation's own FLAGS are
+     * the only place a workspace filter is written, and on an ALIASED root - `TanStack/query`'s
+     * `pnpm run test:ci` - reading them off {@link testScript} reads the flags of the alias, which has
+     * none. A reader that resolved the hop again to find them would be a second copy of the one rule
+     * {@link classifyWithAliasHop} exists to keep single.
+     */
+    aggregatorInvocationScript: string | null;
     /**
      * The aggregator task {@link testScript} was read from, when this package declares no `test`
      * script of its own and the root's aggregator named a task it does declare. Null everywhere
@@ -4427,6 +4614,29 @@ declare function placeSetupStep(input: {
         before: string;
     } | null;
 }): SetupStepPlacement | Refusal;
+/**
+ * Is abloh's step already the last thing this job does?
+ *
+ * MATCHED ON THE ACTION REPOSITORY AND NOT ON THE PIN. A customer who is already running abloh at
+ * an older commit has an abloh step, and appending a second one would run the measurement twice and
+ * put two check runs on every pull request. The pin is ours to bump and theirs to keep.
+ */
+/**
+ * DOES THIS WORKFLOW ALREADY RUN ABLOH, in any job of it?
+ *
+ * WHO ASKS (the captain's ruling of 2026-09-12). Re-running `abloh init` adds a lane, so the command
+ * has to be able to tell a repository that is already set up for pull requests from one that is not
+ * - and the step in one of the maintainer's own jobs is the fact that says so.
+ *
+ * IT IS THE SAME MATCHER THE WRITER USES, over every job rather than over one. A second reading of
+ * "is abloh's step here" is how one of them comes to answer differently, and the writer's answer is
+ * what decides whether a second step is appended.
+ *
+ * AN UNREADABLE FILE ANSWERS FALSE. What that costs is an offer to set up a lane that is already
+ * there, which a maintainer can decline. Answering true would hide the offer from somebody who
+ * needs it.
+ */
+declare function workflowRunsAbloh(text: string): boolean;
 
 /**
  * WHICH OF THE MAINTAINER'S SUITE STEPS ABLOH'S STEP GOES BEHIND, ON THE LEG IT PINNED.
@@ -4628,4 +4838,4 @@ declare function selectAutoTarget(input: {
  */
 declare function committedYarnVersion(directory: string, lockfileName: string, ctx?: RepoAccess): string | null;
 
-export { ANSWERABLE_SETUP_KEYS, ANSWERED_EVIDENCE, type AggregatorInvocation, type AggregatorTool, type AttestationJob, type AutoTargetSelection, type BrowserLane, type BrowserLaneEvidence, type BrowserLaneKind, CI_RECIPE_REFUSALS, type CiBorrowJob, type CiBrowserLane, type CiEnvironmentValue, type CiInstallStep, type CiJobStep, type CiJobTestStep, type CiManagerVersion, type CiNodeVersion, type CiRecipe, type CiRequiredVariable, type CiService, type CiSetupCommand, type CiSystemPackage, type CiTestCommand, type CiUnreadableJobCall, type CiUnsupportedService, type ConfigInput, type ConfigSystemPackage, type CoverageChildSuite, DENO_CONFIG_FILES, DENO_LOCKFILE, type DeclaredBinding, type DeclaredCommandContext, type DenoProject, type DraftService, ENVIRONMENT_BLOCK_HEADER, InitRefusal, type LockfileChoice, type ManifestClassification, type NodeChoice, type NodeDeclaration, type NodeDeclarationProblem, type NodeDeclarationRejection, type NodeEnvironment, type NodeRelease, type NodeRequirement, type NodeSpecReading, type NxProject, type NxTestTarget, type PackageManager, type PackageManagerContext, type PackageManagerResolution, type PlanDeclaration, type PolicyDeclaration, RUSH_CONFIG_DIRECTORY, RUSH_CONFIG_FILE, RUSH_INSTALL_COMMAND, RUSH_INSTALL_SCRIPT, RUSH_LOCKFILE_NAME, RUSH_REPO_STATE_NAME, RUSH_SUBSPACE_DIRECTORY, RUSH_TEST_SCRIPTS, type ReadTextAt, type RebuildDraftValue, type RepoAccess, type ResolveMeasurementPlanInput, type Runner, type RuntimeNeed, type RushProject, type RushTestTarget, SETUP_QUESTION_DESCRIPTORS, STEP_WHAT, type SetupAnswerChannel, type SetupAnswerShape, type SetupDraftValues, type SetupFailFastDecision, type SetupJobDecision, type SetupJobQuestion, type SetupMatrixLeg, type SetupPin, type SetupPublishPlacement, type SetupQuestionDescriptor, type SetupStepAnchor, type SetupStepPlacement, type SetupStepPrecondition, type SubmoduleRoot, type TargetDetection, TargetDetectionError, TargetNotFoundError, type TargetNotFoundReason, type TargetResolution, type TargetResolutionInput, type WorkflowEnvironmentEntry, type WorkflowEnvironmentLevel, type WorkflowEnvironmentScope, type WorkflowExpressionFacts, type WorkflowExpressionReading, type WorkspaceEnumeration, type WorkspaceRootSuite, __testing, accessExists, accessKind, accessManifest, accessSubdirectories, accessText, admitSubmodules, aggregatorInvocation, aggregatorTaskPhrase, aliasHopFamily, answeredTargetDirectory, applyAnswersToContract, applyDeclaredRunner, argvInvokesNodeTest, assertNoGitlinkChanges, bindDeclaredCommand, bindPreparedTestCommand, chooseNodeVersion, ciInstallSteps, ciInstallersFor, ciManagerVersions, ciRefusalIsActionable, classicPerTestRefusal, classicPerTestRunner, classifyNxTestTarget, classifyPackageDirectory, classifyPackageManifest, classifyRushTestScript, classifyWithAliasHop, commentLines, committedYarnVersion, contractDescriptors, decideSetupJob, declarableSetupJobs, declaredCommandContext, declaredRunner, declaredRunnerInvocation, declaredSetupJob, declaredSetupPin, denoLockfilePath, denoTestInvocation, deriveCiRecipe, detectJasmineSuite, detectPackageManager, detectPackageManagerContext, detectTarget, detectVitestDir, diskRepoAccess, diskRepoReader, doorSetupJobs, emptyCiRecipe, engineRunner, enumerateNxProjects, enumerateRushProjects, enumerateWorkspacePackages, enumerateWorkspacePackagesOnDisk, initFailureClassOf, initRefusal, initStepRole, invokesNodeTest, isBrowserInstallCommand, isInstallStep, jasmineSuiteFromScript, layerEnvironment, materializeSubmodule, nodeDeclarationProblemReason, nodeSpecVersions, placeSetupStep, policyDeclaration, preRunnerStageCommands, readAnswerValue, readBrowserLane, readDenoProject, readNodeSpec, readWorkflowExpressions, referencesExpression, referencesSecret, refusalRemedyOf, renderConfig, renderEnvironmentBlock, renderWorkflow, repoPath, resolveMeasurementPlan, resolveSetupPin, resolveTarget, resolveTargetDetection, rootAggregatorTasks, runnerInvocation, runnerStageCommand, runnerSuiteInvocations, rushIdentityFiles, rushLockfiles, rushNodeVersionRange, sameJobReference, scriptRunsDenoTest, selectAutoTarget, setupAnswerProblem, setupJobCandidates, setupJobReference, setupScriptSteps, setupStepAnchor, setupStepOrigin, splitAnswerList, suiteStages, systemPackagesStep, testCommandReceipt, testStepLabel, testableWorkspacePackages, unreadableConditionLine, vitestDirIn, withoutPackageRunnerPrefix, workDirPrefix };
+export { ANSWERABLE_SETUP_KEYS, ANSWERED_EVIDENCE, type AggregatorChain, type AggregatorChainGap, type AggregatorChainPackage, type AggregatorInvocation, type AggregatorTool, type AttestationJob, type AutoTargetSelection, type BrowserLane, type BrowserLaneEvidence, type BrowserLaneKind, CI_RECIPE_REFUSALS, type CiBorrowJob, type CiBrowserLane, type CiDroppedStep, type CiEnvironmentValue, type CiInstallStep, type CiJobStep, type CiJobTestStep, type CiManagerVersion, type CiNodeVersion, type CiRecipe, type CiRequiredVariable, type CiService, type CiSetupCommand, type CiSystemPackage, type CiTestCommand, type CiUnreadableJobCall, type CiUnsupportedService, type ConfigInput, type ConfigSystemPackage, type CoverageChildSuite, DENO_CONFIG_FILES, DENO_LOCKFILE, type DeclaredBinding, type DeclaredCommandContext, type DenoProject, type DraftService, ENVIRONMENT_BLOCK_HEADER, InitRefusal, type LockfileChoice, type ManifestClassification, type NodeChoice, type NodeDeclaration, type NodeDeclarationProblem, type NodeDeclarationRejection, type NodeEnvironment, type NodeRelease, type NodeRequirement, type NodeSpecReading, type NxProject, type NxTestTarget, type PackageManager, type PackageManagerContext, type PackageManagerResolution, type PlanDeclaration, type PolicyDeclaration, RETIRED_ENVIRONMENT_BLOCK_HEADERS, RUSH_CONFIG_DIRECTORY, RUSH_CONFIG_FILE, RUSH_INSTALL_COMMAND, RUSH_INSTALL_SCRIPT, RUSH_LOCKFILE_NAME, RUSH_REPO_STATE_NAME, RUSH_SUBSPACE_DIRECTORY, RUSH_TEST_SCRIPTS, type ReadTextAt, type RebuildDraftValue, type RepoAccess, type ResolveMeasurementPlanInput, type Runner, type RuntimeNeed, type RushProject, type RushTestTarget, SETUP_QUESTION_DESCRIPTORS, STEP_WHAT, type SetupAnswerChannel, type SetupAnswerShape, type SetupDraftValues, type SetupFailFastDecision, type SetupJobDecision, type SetupJobQuestion, type SetupMatrixLeg, type SetupPin, type SetupPublishPlacement, type SetupQuestionDescriptor, type SetupScriptInput, type SetupStepAnchor, type SetupStepPlacement, type SetupStepPrecondition, type SubmoduleRoot, type TargetDetection, TargetDetectionError, TargetNotFoundError, type TargetNotFoundReason, type TargetResolution, type TargetResolutionInput, type WorkflowEnvironmentEntry, type WorkflowEnvironmentLevel, type WorkflowEnvironmentScope, type WorkflowExpressionFacts, type WorkflowExpressionReading, type WorkspaceEnumeration, type WorkspaceRootSuite, __testing, accessExists, accessKind, accessManifest, accessSubdirectories, accessText, admitSubmodules, aggregatorChain, aggregatorInvocation, aggregatorTaskPhrase, aliasHopFamily, answeredTargetDirectory, applyAnswersToContract, applyDeclaredRunner, argvInvokesNodeTest, assertNoGitlinkChanges, bindDeclaredCommand, bindPreparedTestCommand, chooseNodeVersion, ciInstallSteps, ciInstallersFor, ciManagerVersions, ciRefusalIsActionable, classicPerTestRefusal, classicPerTestRunner, classifyNxTestTarget, classifyPackageDirectory, classifyPackageManifest, classifyRushTestScript, classifyWithAliasHop, commentLines, committedYarnVersion, contractDescriptors, decideSetupJob, declarableSetupJobs, declaredCommandContext, declaredRunner, declaredRunnerInvocation, declaredSetupJob, declaredSetupPin, denoLockfilePath, denoTestInvocation, deriveCiRecipe, detectJasmineSuite, detectPackageManager, detectPackageManagerContext, detectTarget, detectVitestDir, diskRepoAccess, diskRepoReader, doorSetupJobs, emptyCiRecipe, engineRunner, enumerateNxProjects, enumerateRushProjects, enumerateWorkspacePackages, enumerateWorkspacePackagesOnDisk, initFailureClassOf, initRefusal, initStepRole, invokesNodeTest, isBrowserInstallCommand, isEnvironmentBlockHeader, isInstallStep, jasmineSuiteFromScript, layerEnvironment, materializeSubmodule, nodeDeclarationProblemReason, nodeSpecVersions, overlayRepoAccess, placeSetupStep, policyDeclaration, preRunnerStageCommands, readAnswerValue, readBrowserLane, readDenoProject, readNodeSpec, readWorkflowExpressions, referencesExpression, referencesSecret, refusalRemedyOf, renderConfig, renderEnvironmentBlock, renderWorkflow, repoPath, resolveMeasurementPlan, resolveSetupPin, resolveTarget, resolveTargetDetection, rootAggregatorTasks, runnerInvocation, runnerStageCommand, runnerSuiteInvocations, rushIdentityFiles, rushLockfiles, rushNodeVersionRange, sameJobReference, scriptRunsDenoTest, selectAutoTarget, setupAnswerProblem, setupJobCandidates, setupJobReference, setupScriptSteps, setupStepAnchor, setupStepOrigin, splitAnswerList, suiteStages, systemPackagesStep, testCommandReceipt, testStepLabel, testableWorkspacePackages, unreadableConditionLine, vitestDirIn, withoutPackageRunnerPrefix, workDirPrefix, workflowRunsAbloh };