@intentius/chant 0.34.1 → 0.37.2

package/src/cli/handlers/components.ts

@@ -46,7 +46,7 @@ import { discoverComponents } from "../../components/discover";
 import { formatError, formatWarning, formatSuccess, formatBold } from "../format";
 import type { CommandContext } from "../registry";
 import type { LexiconPlugin } from "../../lexicon";
-import { normalizeObservation, unobservedAll, type NormalizedObservation } from "../../observation";
+import { normalizeObservation, mergeObservations, unobservedAll, type NormalizedObservation } from "../../observation";
 import type { Phase, Component } from "../../components/component";
 
 /**
@@ -184,6 +184,22 @@ interface StatusJsonRow {
   /** Why live state could not be read for this component (#1089). Mutually exclusive with `live`. */
   unobserved?: { reason: string; detail?: string };
   stack?: { name: string; status?: string; healthy?: boolean };
+  /**
+   * How this component's own resources answered (behold#98, chant#1300).
+   *
+   * `stack` above exists only where the substrate has a deploy object to read,
+   * which is AWS; these counts are the substrate-neutral answer to the same
+   * question, and finer-grained than a single stack verdict wherever both are
+   * present. #1300 added the field to `ComponentStatusRow` but not to this
+   * projection, which is the only surface a consumer sees — so until behold#100
+   * it never left the CLI.
+   *
+   * On AWS the counts inherit `describe-stack-resources`, so they report
+   * CloudFormation's per-resource inventory rather than independently observed
+   * existence; the per-type reader registry (#1269/#1271) applied to this thin
+   * path is what would make them a live check.
+   */
+  resources?: { total: number; present: number; absent: number; unobserved: number };
 }
 
 /**
@@ -340,6 +356,28 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
       try {
         const targetSerializers = serializers;
         const buildResult = await build(resolve(args.src ?? config.sourceDir ?? "."), targetSerializers);
+        // Which deployed stack(s) to read the change set from (behold#100).
+        //
+        // `describeResources` defaults to the single-stack convention — the
+        // stack named after the environment — which is wrong for exactly the
+        // projects this command exists for: a component project deploys the
+        // stack its own `cfn-deploy` names, and that is almost never the env
+        // name. Every declared resource then came back absent, so the rollup
+        // #1300 computes read `present: 0` over a healthy estate. That was
+        // invisible while nothing consumed the rollup; behold#100 paints from
+        // it, so it has to be right.
+        //
+        // The components' own `cfn-deploy` stacks are the authority (the same
+        // ones `observeComponentStacks` reads below), with `config.stacks` as
+        // the declared override for a project whose stacks aren't derivable
+        // from a deploy step. `[undefined]` keeps the old single-read
+        // behaviour for a project with neither.
+        const componentStackNames = new Set<string>();
+        for (const { component } of discovery.components.values()) {
+          for (const stack of cfnDeployStacks(component.deploy)) componentStackNames.add(stack);
+        }
+        for (const stack of config.stacks ?? []) componentStackNames.add(stack.name);
+        const readTargets: Array<string | undefined> = componentStackNames.size ? [...componentStackNames] : [undefined];
         const merged: { env: string; entries: import("../../lifecycle/change-set").ChangeSetEntry[] } = { env: environment, entries: [] };
         for (const plugin of plugins) {
           if (!plugin.describeResources) continue;
@@ -356,8 +394,20 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
           }
           let observed: NormalizedObservation;
           try {
-            observed = normalizeObservation(
-              await plugin.describeResources({ environment, buildOutput: "", entityNames: Array.from(declared), entities }),
+            observed = mergeObservations(
+              await Promise.all(
+                readTargets.map(async (stack) =>
+                  normalizeObservation(
+                    await plugin.describeResources!({
+                      environment,
+                      buildOutput: "",
+                      entityNames: Array.from(declared),
+                      entities,
+                      ...(stack ? { stack } : {}),
+                    }),
+                  ),
+                ),
+              ),
             );
           } catch (err) {
             // A failed read is not an empty environment (#1089): mark every
@@ -464,6 +514,7 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
         ...(row.live !== undefined ? { live: row.live } : {}),
         ...(row.unobserved ? { unobserved: row.unobserved } : {}),
         ...(row.stack ? { stack: row.stack } : {}),
+        ...(row.resources ? { resources: row.resources } : {}),
       });
     }
   }

package/src/cli/handlers/graph.test.ts

@@ -572,6 +572,67 @@ describe("runGraph", () => {
       expect((opts as { owned: boolean }).owned).toBe(true);
     });
 
+    // #1158: a project that declares its stacks in `ChantConfig.stacks` — rather
+    // than deriving them from `*.component.ts` — must observe each declared
+    // stack, the same contract `resolveStackTargets` gives lifecycle
+    // snapshot/diff. Every other test here passes `stacks: []`, so without this
+    // the declared-stack path is implemented and unguarded.
+    test("ChantConfig.stacks: observeResources gets every declared stack, with its region and src", async () => {
+      resolveLexMock.mockResolvedValue(["aws"]);
+      loadPluginsMock.mockResolvedValue([
+        { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
+      ]);
+      loadChantConfigMock.mockResolvedValue({
+        config: {
+          stacks: [
+            { name: "estate-east", region: "us-east-1", src: "east/src" },
+            { name: "estate-west", region: "us-west-2", src: "west/src" },
+          ],
+        },
+      });
+      observeMock.mockResolvedValue({ observations: [], errors: [], warnings: [] });
+      const exit = await runGraph({ args: makeArgs({ format: "ir", live: true, env: "prod" }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      expect(observeMock).toHaveBeenCalledTimes(1);
+      const [, , , opts] = observeMock.mock.calls[0];
+      // The region/src carry through — a multi-region estate observes each
+      // stack in its own region, not all of them in the ambient default.
+      expect((opts as { stacks: Array<{ name: string; region?: string; src?: string }> }).stacks).toEqual([
+        { name: "estate-east", region: "us-east-1", src: "east/src" },
+        { name: "estate-west", region: "us-west-2", src: "west/src" },
+      ]);
+    });
+
+    // A stack can be both component-derived and declared. It must be observed
+    // once — `describeResources` is a live API call per stack, so a duplicate
+    // is a wasted round trip and a doubled node set to reconcile.
+    test("ChantConfig.stacks: a stack also derived from a component is not observed twice", async () => {
+      resolveLexMock.mockResolvedValue(["aws"]);
+      loadPluginsMock.mockResolvedValue([
+        { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
+      ]);
+      discoverComponentsMock.mockResolvedValue({
+        errors: [],
+        sourceFiles: [],
+        components: new Map([
+          ["loom-db", { component: { name: "loom-db", dependsOn: [], deploy: [
+            { phase: "deploy", steps: [{ kind: "cfn-deploy", stack: "shared-estate" }] },
+          ] }, exportName: "loomDb", filePath: "components/loom-db.component.ts" }],
+        ]),
+      });
+      loadChantConfigMock.mockResolvedValue({
+        config: { stacks: [{ name: "shared-estate" }, { name: "estate-west" }] },
+      });
+      observeMock.mockResolvedValue({ observations: [], errors: [], warnings: [] });
+      const exit = await runGraph({ args: makeArgs({ format: "ir", live: true, env: "prod" }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      const [, , , opts] = observeMock.mock.calls[0];
+      expect((opts as { stacks: Array<{ name: string }> }).stacks.map((s) => s.name)).toEqual([
+        "shared-estate",
+        "estate-west",
+      ]);
+    });
+
     test("component discovery errors: falls back to the single-stack path with a warning", async () => {
       resolveLexMock.mockResolvedValue(["aws"]);
       loadPluginsMock.mockResolvedValue([

package/src/cli/handlers/lifecycle.ts

@@ -273,11 +273,18 @@ export async function runLifecycleRollback(ctx: CommandContext): Promise<number>
   const { config } = await loadChantConfig(resolve("."));
   const sourceDir = config.sourceDir ?? ".";
   try {
-    const result = await rollbackToRevision({ ref, env: environment, sourceDir, cwd: resolve(".") });
+    const result = await rollbackToRevision({ ref, env: environment, sourceDir, cwd: resolve("."), dryRun: args.dryRun });
     if (result.noop) {
       console.error(formatSuccess(`${sourceDir} already matches ${ref} — nothing to roll back`));
       return 0;
     }
+    if (args.dryRun) {
+      // The delta on stdout, so it pipes and diffs like any other patch; the
+      // summary on stderr, matching the PR path's split.
+      process.stdout.write(result.diff ?? "");
+      console.error(formatSuccess(`Rollback delta for ${ref} computed — no PR opened, nothing pushed`));
+      return 0;
+    }
     console.log(result.prUrl); // the PR URL — the consumer (behold) reads this from stdout
     console.error(formatSuccess(`Opened rollback PR on ${result.branch}`));
     return 0;

package/src/cli/main.ts

@@ -211,6 +211,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.migrateTo = args[++i];
     } else if (arg === "--emit") {
       result.emit = args[++i];
+    } else if (arg === "--dry-run") {
+      result.dryRun = true;
     } else if (arg === "--strict") {
       result.strict = true;
     } else if (arg === "--validate") {

package/src/cli/registry.ts

@@ -63,6 +63,8 @@ export interface ParsedArgs {
   selectName?: string;
   /** `chant import --owned` — restrict live import to chant-owned resources */
   owned?: boolean;
+  /** `chant lifecycle rollback --dry-run` — compute the rollback delta and print it; open no PR, push nothing, leave no branch. */
+  dryRun?: boolean;
   /** `chant import --verbatim` — keep server-defaulted fields in live import */
   verbatim?: boolean;
   /** `chant lifecycle … --src <dir>` — build root override for lifecycle commands */

package/src/codegen/docs-rule-scanning.ts

@@ -109,17 +109,26 @@ function extractDescriptionFromComment(
   return ruleId;
 }
 
+function plural(n: number, noun: string): string {
+  return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+
 export function generateRules(config: DocsConfig, rules: RuleMeta[]): string {
   const lintRules = rules.filter((r) => r.type === "lint");
   const postSynthRules = rules.filter((r) => r.type === "post-synth");
 
   const lines: string[] = [
     "---",
-    `title: "Lint Rules"`,
-    `description: "Lint rules and post-synth checks provided by the ${config.displayName} lexicon"`,
+    // "All Rules", not "Lint Rules": most lexicons also ship a hand-written
+    // page under the latter title that covers a selected subset, and two pages
+    // with the same title reads as a duplicate rather than a complete table.
+    `title: "All Rules"`,
+    `description: "Every lint rule and post-synth check provided by the ${config.displayName} lexicon"`,
     "---",
     "",
-    `The ${config.displayName} lexicon provides **${rules.length}** rules: ${lintRules.length} lint rules and ${postSynthRules.length} post-synth checks.`,
+    `The ${config.displayName} lexicon provides **${rules.length}** rules: ` +
+      `${plural(lintRules.length, "lint rule")} and ` +
+      `${plural(postSynthRules.length, "post-synth check")}.`,
     "",
   ];
 

package/src/codegen/docs-sections.ts

@@ -64,9 +64,11 @@ export function generateOverview(
       `- [Pseudo-Parameters](./pseudo-parameters) — ${Object.keys(manifest.pseudoParameters).length} pseudo-parameters`,
     );
   }
-  const overviewExtraSlugs = new Set((config.extraPages ?? []).map((p) => p.slug));
-  if (!suppress.has("rules") && !overviewExtraSlugs.has("lint-rules") && rules.length > 0) {
-    lines.push(`- [Lint Rules](./rules) — ${rules.length} rules`);
+  // Same reasoning as the sidebar's rules entry: link the complete table on
+  // every lexicon, under the label the sidebar uses, whether or not a prose
+  // `lint-rules` page also exists.
+  if (!suppress.has("rules") && rules.length > 0) {
+    lines.push(`- [All Rules](./rules) — ${rules.length} rules`);
   }
   if (!suppress.has("serialization")) {
     lines.push(`- [Serialization](./serialization) — output format details`);
@@ -95,7 +97,7 @@ export function generateIntrinsics(
     "",
     `The ${config.displayName} lexicon provides **${intrinsics.length}** intrinsic functions.`,
     "",
-    `**Tag?** shows how an intrinsic is authored: a genuine tagged template (\`Sub\\\`...\\\`\`) or a plain function call (\`Ref(...)\`). **Folds?** shows whether [\`chant build --fold\`](/chant/concepts/typescript-as-data/#folded-vs-run) can reduce a use of this intrinsic today, without running the file — generated directly from this lexicon's registration, not restated by hand. A tagged template folds once it is registered. A plain call folds only where this lexicon has opted that intrinsic in one at a time (\`foldsAsCall\`), so a \`No\` in this column means this intrinsic has not been opted in, not that calls in general cannot fold.`,
+    `**Tag?** shows how an intrinsic is authored: a genuine tagged template (\`Sub\\\`...\\\`\`) or a plain function call (\`Ref(...)\`). **Folds?** shows whether [folding](/chant/concepts/typescript-as-data/#folded-vs-run) — the default \`chant build\` path — can reduce a use of this intrinsic today, without running the file — generated directly from this lexicon's registration, not restated by hand. A tagged template folds once it is registered. A plain call folds only where this lexicon has opted that intrinsic in one at a time (\`foldsAsCall\`), so a \`No\` in this column means this intrinsic has not been opted in, not that calls in general cannot fold.`,
     "",
     "| Function | Description | Output Key | Tag? | Folds? |",
     "|----------|-------------|------------|------|--------|",

package/src/codegen/docs-sidebar.ts

@@ -39,8 +39,14 @@ export function buildSidebar(
     items.push({ label: "Pseudo-Parameters", slug: "pseudo-parameters" });
   }
 
-  if (!suppress.has("rules") && !extraSlugs.has("rules") && !extraSlugs.has("lint-rules") && result.pages.has("rules.mdx")) {
-    items.push({ label: "Lint Rules", slug: "rules" });
+  // Every lexicon links its generated rules table, whether or not it also
+  // ships a prose `lint-rules` page. Skipping it when one existed was how gcp
+  // ended up emitting a page nothing pointed at (#1312), and it left readers
+  // with no complete list on the lexicons whose prose covers only part of the
+  // set — aws documented 26 of 50 that way. The label distinguishes the
+  // generated table from a prose page rather than competing with it.
+  if (!suppress.has("rules") && !extraSlugs.has("rules") && result.pages.has("rules.mdx")) {
+    items.push({ label: "All Rules", slug: "rules" });
   }
 
   if (!suppress.has("serialization") && !extraSlugs.has("serialization") && result.pages.has("serialization.mdx")) {

package/src/codegen/docs.ts

@@ -7,7 +7,7 @@
  * (service grouping, resource type URLs, custom overview content).
  */
 
-import { copyFileSync, readFileSync, writeFileSync, mkdirSync, rmSync } from "fs";
+import { copyFileSync, existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, rmSync } from "fs";
 import { join } from "path";
 import { fileURLToPath } from "url";
 
@@ -71,6 +71,7 @@ export function docsPipeline(config: DocsConfig): DocsResult {
   }
   pages.set("index.mdx", overviewContent);
   const suppress = new Set(config.suppressPages ?? []);
+  const extraSlugs = new Set((config.extraPages ?? []).map((p) => p.slug));
 
   // Extra pages from lexicon config
   if (config.extraPages) {
@@ -96,12 +97,28 @@ export function docsPipeline(config: DocsConfig): DocsResult {
     }
   }
 
-  if (!suppress.has("intrinsics") && manifest.intrinsics && manifest.intrinsics.length > 0) {
+  // A generated page must not overwrite one the lexicon explicitly declared.
+  // The extraPages above are written into `pages` first, so an unguarded
+  // `pages.set` below silently discards them: helm declared its own
+  // "Intrinsics Reference" and pre-synth rules pages and shipped neither for
+  // as long as both slugs collided (#1312). Explicit authorship wins, and the
+  // collision is reported rather than resolved in silence.
+  const claimed = (slug: string): boolean => {
+    if (suppress.has(slug)) return true;
+    if (!extraSlugs.has(slug)) return false;
+    console.warn(
+      `[docs:${config.name}] extraPages declares "${slug}", which is also a generated page — keeping the declared one.\n` +
+        `  Add "${slug}" to suppressPages to make that explicit, or rename the extraPage if both are wanted.`,
+    );
+    return true;
+  };
+
+  if (!claimed("intrinsics") && manifest.intrinsics && manifest.intrinsics.length > 0) {
     pages.set("intrinsics.mdx", generateIntrinsics(config, manifest));
   }
 
   if (
-    !suppress.has("pseudo-parameters") &&
+    !claimed("pseudo-parameters") &&
     manifest.pseudoParameters &&
     Object.keys(manifest.pseudoParameters).length > 0
   ) {
@@ -111,14 +128,23 @@ export function docsPipeline(config: DocsConfig): DocsResult {
     );
   }
 
-  if (!suppress.has("rules") && rules.length > 0) {
+  if (!claimed("rules") && rules.length > 0) {
     pages.set("rules.mdx", generateRules(config, rules));
   }
 
-  if (!suppress.has("serialization")) {
+  if (!claimed("serialization")) {
     pages.set("serialization.mdx", generateSerialization(config));
   }
 
+  // Stamp every emitted page with its provenance. These files look exactly
+  // like the hand-written pages sitting beside them, and without a marker they
+  // get edited directly — the k8s "Live Cluster" sidebar group and the AWS
+  // intrinsics guide's #1044 claim were both fixed in the emitted `.mdx` and
+  // silently reverted by the next regen (#1312).
+  for (const [filename, content] of pages) {
+    pages.set(filename, withGeneratedMarker(config, content));
+  }
+
   return {
     pages,
     stats: {
@@ -131,6 +157,85 @@ export function docsPipeline(config: DocsConfig): DocsResult {
   };
 }
 
+/**
+ * Insert a provenance comment directly after a page's frontmatter.
+ *
+ * MDX parses `<!-- -->` as JSX rather than a comment, so this uses the
+ * `{/* … *\/}` form the rest of the docs already use for generated markers.
+ */
+function withGeneratedMarker(config: DocsConfig, content: string): string {
+  const marker = `{/* ${GENERATED_MARKER_TAG} by \`npm run docs -w @intentius/chant-lexicon-${config.name}\` — DO NOT EDIT.\n    Edit lexicons/${config.name}/src/codegen/docs.ts instead; changes here are overwritten. */}`;
+  const lines = content.split("\n");
+  // Frontmatter is the leading `---` … `---` block; the marker goes after it.
+  if (lines[0] === "---") {
+    const close = lines.indexOf("---", 1);
+    if (close > 0) {
+      lines.splice(close + 1, 0, "", marker);
+      return lines.join("\n");
+    }
+  }
+  return `${marker}\n\n${content}`;
+}
+
+/**
+ * Render the complete rules table for a lexicon that has no {@link docsPipeline}
+ * site of its own.
+ *
+ * The docker lexicon hand-authors its docs, which left its rule table the only
+ * one in the repo that could drift from source without anything noticing
+ * (#1312). This is the one page worth generating even when the rest of a site
+ * is hand-written; the caller writes the result to `rules.mdx` and links it.
+ * Returns null when the lexicon declares no rules.
+ */
+export function generateRulesPage(
+  config: DocsConfig,
+  srcDir: string,
+): string | null {
+  const rules = scanRules(srcDir);
+  if (rules.length === 0) return null;
+  return withGeneratedMarker(config, generateRules(config, rules));
+}
+
+/**
+ * Marks a page as pipeline output. Used both to warn readers off editing the
+ * file and, in {@link writeDocsSite}, to tell a page this pipeline owns from a
+ * hand-written one when reaping pages it no longer emits.
+ */
+export const GENERATED_MARKER_TAG = "GENERATED-BY-CHANT-DOCS";
+
+/**
+ * Every slug a Starlight sidebar reaches, including nested group items.
+ */
+export function collectSidebarSlugs(items: Array<Record<string, unknown>>): Set<string> {
+  const slugs = new Set<string>();
+  const walk = (list: Array<Record<string, unknown>>): void => {
+    for (const item of list) {
+      if (typeof item.slug === "string") slugs.add(item.slug);
+      if (Array.isArray(item.items)) walk(item.items as Array<Record<string, unknown>>);
+    }
+  };
+  walk(items);
+  return slugs;
+}
+
+/**
+ * Content pages that no sidebar entry points at.
+ *
+ * `index` is always the site root and never needs an entry of its own.
+ */
+export function unreachablePages(
+  contentDir: string,
+  sidebar: Array<Record<string, unknown>>,
+): string[] {
+  if (!existsSync(contentDir)) return [];
+  const slugs = collectSidebarSlugs(sidebar);
+  return readdirSync(contentDir)
+    .filter((f) => f.endsWith(".mdx") || f.endsWith(".md"))
+    .map((f) => f.replace(/\.mdx?$/, ""))
+    .filter((slug) => slug !== "index" && !slugs.has(slug))
+    .sort();
+}
+
 /**
  * Write generated docs pages to disk.
  */
@@ -161,6 +266,23 @@ export function writeDocsSite(config: DocsConfig, result: DocsResult): void {
     const filePath = join(contentDir, filename);
     rmSync(filePath, { force: true });
   }
+
+  // Reap pages this pipeline used to emit and no longer does. Suppressing a
+  // page only stops it being written; the copy from the last run stayed on
+  // disk, unreferenced by the sidebar and indistinguishable from a
+  // hand-written page — which is how azure, gcp and helm each kept a `rules`
+  // page after adopting their own (#1312). The provenance marker is what makes
+  // this safe: only a file this pipeline stamped is ever removed.
+  if (existsSync(contentDir)) {
+    for (const filename of readdirSync(contentDir)) {
+      if (!filename.endsWith(".mdx") && !filename.endsWith(".md")) continue;
+      if (result.pages.has(filename)) continue;
+      const filePath = join(contentDir, filename);
+      if (readFileSync(filePath, "utf-8").includes(GENERATED_MARKER_TAG)) {
+        rmSync(filePath, { force: true });
+      }
+    }
+  }
   rmSync(join(outDir, ".astro"), { recursive: true, force: true });
   rmSync(join(outDir, "node_modules", ".astro"), { recursive: true, force: true });
 
@@ -170,6 +292,20 @@ export function writeDocsSite(config: DocsConfig, result: DocsResult): void {
   // Build sidebar from generated pages
   const sidebar = buildSidebar(config, result);
 
+  // Starlight does not auto-discover pages, so a page absent from the sidebar
+  // is reachable only by typing its URL. The pipeline deliberately preserves
+  // hand-written pages it did not emit (above), which makes it easy to add one
+  // and never wire it up — azure, temporal, helm and github each accumulated
+  // several that way (#1312). Report them; `chant dev check-lexicon` gates on
+  // the same condition.
+  const unreachable = unreachablePages(contentDir, sidebar);
+  if (unreachable.length > 0) {
+    console.warn(
+      `[docs:${config.name}] ${unreachable.length} page(s) in no sidebar entry — reachable only by direct URL: ${unreachable.join(", ")}.\n` +
+        `  Declare them in this lexicon's DocsConfig \`sidebarExtra\` (or \`extraPages\`) to surface them.`,
+    );
+  }
+
   // package.json
   writeFileSync(
     join(outDir, "package.json"),

package/src/codegen/fetch.test.ts

@@ -182,12 +182,26 @@ describe("fetchWithRetry", () => {
     expect(fetchMock).toHaveBeenCalledTimes(3);
   });
 
-  test("calls fetch with no init argument when none is given", async () => {
+  test("bounds an attempt with a signal even when no init is given", async () => {
     const fetchMock = vi.fn().mockResolvedValue(ok());
     vi.stubGlobal("fetch", fetchMock);
 
     await fetchWithRetry("https://example.test/x", 4, 1);
-    expect(fetchMock).toHaveBeenCalledWith("https://example.test/x");
+    // A hung connect would otherwise wait on the OS default, which is long
+    // enough to run a CI job past its timeout.
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://example.test/x",
+      expect.objectContaining({ signal: expect.any(AbortSignal) }),
+    );
+  });
+
+  test("a caller's own signal wins over the attempt bound", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(ok());
+    vi.stubGlobal("fetch", fetchMock);
+
+    const controller = new AbortController();
+    await fetchWithRetry("https://example.test/x", 4, 1, { signal: controller.signal });
+    expect(fetchMock.mock.calls[0][1].signal).toBe(controller.signal);
   });
 
   test("passes request init through to fetch", async () => {
@@ -196,7 +210,10 @@ describe("fetchWithRetry", () => {
 
     const init = { headers: { Accept: "application/vnd.github+json" } };
     await fetchWithRetry("https://example.test/x", 4, 1, init);
-    expect(fetchMock).toHaveBeenCalledWith("https://example.test/x", init);
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://example.test/x",
+      expect.objectContaining({ headers: init.headers, signal: expect.any(AbortSignal) }),
+    );
   });
 
   test("preserves init across retries on a transient status", async () => {
@@ -210,8 +227,10 @@ describe("fetchWithRetry", () => {
     const resp = await fetchWithRetry("https://example.test/x", 4, 1, init);
     expect(resp.ok).toBe(true);
     expect(fetchMock).toHaveBeenCalledTimes(2);
-    expect(fetchMock).toHaveBeenNthCalledWith(1, "https://example.test/x", init);
-    expect(fetchMock).toHaveBeenNthCalledWith(2, "https://example.test/x", init);
+    for (const call of fetchMock.mock.calls) {
+      expect(call[0]).toBe("https://example.test/x");
+      expect(call[1]).toEqual(expect.objectContaining({ headers: init.headers, signal: expect.any(AbortSignal) }));
+    }
   });
 
   test("does not retry a permanent status when init is given", async () => {

package/src/codegen/fetch.ts

@@ -30,6 +30,20 @@ const RETRYABLE_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
 
 const DEFAULT_RETRIES = 4;
 const DEFAULT_BACKOFF_MS = 1000;
+/**
+ * Per-attempt ceiling, so an upstream that accepts a connection and then stops
+ * answering cannot hold a build open.
+ *
+ * Without one, a hung connect waits on the OS default — which on Linux is over
+ * a minute — and five of those plus back-off is enough to run a CI job past its
+ * timeout. That is not hypothetical: it is what pushed chant's `check` job from
+ * ~9m30s to a cancellation at 10m, twice, on two unreachable spec endpoints
+ * whose results are only ever a fallback to a committed snapshot anyway.
+ *
+ * Generous enough for a slow-but-alive endpoint; the point is a bound, not
+ * speed.
+ */
+const DEFAULT_ATTEMPT_TIMEOUT_MS = 15_000;
 /** Hard cap on Retry-After delays so a rogue header cannot stall CI indefinitely. */
 const MAX_RETRY_AFTER_MS = 60_000;
 
@@ -85,6 +99,7 @@ export async function fetchWithRetry(
   retries = DEFAULT_RETRIES,
   backoffMs = DEFAULT_BACKOFF_MS,
   init?: RequestInit,
+  attemptTimeoutMs = DEFAULT_ATTEMPT_TIMEOUT_MS,
 ): Promise<Response> {
   let lastStatus: number | undefined;
   let lastError: Error | undefined;
@@ -101,8 +116,11 @@ export async function fetchWithRetry(
     }
 
     let response: Response;
+    // A caller's own signal still wins; this only bounds an attempt that would
+    // otherwise hang with no signal at all.
+    const signal = init?.signal ?? AbortSignal.timeout(attemptTimeoutMs);
     try {
-      response = init === undefined ? await fetch(url) : await fetch(url, init);
+      response = await fetch(url, { ...(init ?? {}), signal });
     } catch (e) {
       // Network-level failure (DNS, connection reset, timeout). Transient.
       lastError = e instanceof Error ? e : new Error(String(e));