@intentius/chant 0.124.67 → 0.124.69

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1144,7 +1144,7 @@ export async function recordSkips(
1144
1144
  const written: ReleaseRecord[] = [];
1145
1145
  try {
1146
1146
  for (const v of fresh) {
1147
- const { record } = await appendReleaseRecord(unchangedRecord(v.since, { releaseDigest, runId: run.runId, ...(run.runOrigin ? { runOrigin: run.runOrigin } : {}), timestamp, actor }), { cwd });
1147
+ const { record } = await appendReleaseRecord(unchangedRecord(v.since, { releaseDigest, runId: run.runId, ...(run.runOrigin ? { runOrigin: run.runOrigin } : {}), timestamp, actor }, v.normalized), { cwd });
1148
1148
  written.push(record);
1149
1149
  console.error(`Recorded skip: ${formatBold(record.component)}@${record.env} keeps ${record.digest} under release ${releaseDigest}`);
1150
1150
  }
@@ -1177,7 +1177,7 @@ export function releaseRunPrepare(
1177
1177
  if (declaring.length > 0 && skip.deployUnchanged) {
1178
1178
  console.error(formatInfo(`--deploy-unchanged: deploying ${declaring.map((c) => c.name).join(", ")} whatever their inputs`));
1179
1179
  } else if (declaring.length > 0) {
1180
- const { compareInputs, gitChangedPaths } = await import("../../components/unchanged-inputs");
1180
+ const { compareInputs, gitChangedPaths, gitNormalizedCompare } = await import("../../components/unchanged-inputs");
1181
1181
  const { readReleaseLedger, latestPerComponent } = await import("../../lifecycle/release-ledger");
1182
1182
  const { readRelease } = await import("../../lifecycle/release-store");
1183
1183
  const current = latestPerComponent((await readReleaseLedger(env, { cwd: projectPath }).catch(() => ({ records: [] }))).records);
@@ -1190,10 +1190,12 @@ export function releaseRunPrepare(
1190
1190
  current: current.get(c.name),
1191
1191
  readRelease: (digest) => readRelease(digest, { cwd: projectPath }),
1192
1192
  changedPaths: gitChangedPaths(projectPath),
1193
+ normalizedCompare: gitNormalizedCompare(projectPath),
1193
1194
  });
1194
1195
  if (verdict.unchanged) {
1195
1196
  skip.skipped.set(c.name, verdict);
1196
1197
  console.error(formatInfo(`${c.name}: inputs unchanged since the deploy "${env}" runs (run ${verdict.since.runId}); not deploying it (--deploy-unchanged deploys it)`));
1198
+ for (const n of verdict.normalized ?? []) console.error(formatInfo(`${c.name}: ${n.path} is the same after \`${n.command}\``));
1197
1199
  } else {
1198
1200
  console.error(formatInfo(`${c.name}: deploying, since ${verdict.reason}`));
1199
1201
  }
@@ -92,6 +92,24 @@
92
92
  "type": "array",
93
93
  "description": "Build parameters, by name, whose values in the environment's target the component deploys from. A value that differs between the two releases deploys it.",
94
94
  "items": { "type": "string", "minLength": 1 }
95
+ },
96
+ "normalize": {
97
+ "type": "array",
98
+ "description": "Optional (#4718): commands a changed input file is compared through. A file that changed between the two releases' commits and that an entry's paths match is read at each commit and piped through the first such entry's command; it is unchanged when the two outputs are the same bytes. The command runs with sh -c from the repository's top level, the file on stdin, {path} replaced by its path from the top level; it must be deterministic. A command that fails counts the file as changed. A skip that used one lists the files in normalizedInputs on its record. Read by chant 0.124.68 and newer.",
99
+ "items": {
100
+ "type": "object",
101
+ "required": ["paths", "command"],
102
+ "additionalProperties": false,
103
+ "properties": {
104
+ "paths": {
105
+ "type": "array",
106
+ "minItems": 1,
107
+ "description": "Git pathspecs, relative to the member's directory, as in inputs.paths.",
108
+ "items": { "type": "string", "minLength": 1 }
109
+ },
110
+ "command": { "type": "string", "minLength": 1, "description": "The normalizer, such as scripts/release blank {path}." }
111
+ }
112
+ }
95
113
  }
96
114
  }
97
115
  }
@@ -214,6 +214,27 @@ export interface ComponentInputs {
214
214
  paths?: string[];
215
215
  /** Build parameters, by name. A value that differs between the two releases' targets for the environment deploys the component. */
216
216
  params?: string[];
217
+ /**
218
+ * Commands that a changed file is compared through (#4718), for files
219
+ * whose changes the component doesn't care about, such as its own version
220
+ * bumped in a Cargo.toml or a lock file. See {@link ComponentInputNormalize}.
221
+ */
222
+ normalize?: ComponentInputNormalize[];
223
+ }
224
+
225
+ /**
226
+ * One normalization of a component's inputs (#4718). A file `paths` matches
227
+ * that changed between the two releases' commits is read at each commit and
228
+ * piped through `command`; the file is unchanged when the two outputs are the
229
+ * same. The command runs with `sh -c` from the repository's top level, with
230
+ * the file on stdin and `{path}` replaced by its path from the top level. It
231
+ * must be deterministic. A command that fails counts the file as changed.
232
+ */
233
+ export interface ComponentInputNormalize {
234
+ /** Git pathspecs, relative to the member's directory, as in `paths`. A file the first entry matches is compared through that entry. */
235
+ paths: string[];
236
+ /** The normalizer, such as `scripts/release blank {path}`. */
237
+ command: string;
217
238
  }
218
239
 
219
240
  /** One environment a component declares it deploys to (#3153). */
@@ -16,6 +16,7 @@ export {
16
16
  type Component,
17
17
  type ComponentEnvironmentDeclaration,
18
18
  type ComponentInputs,
19
+ type ComponentInputNormalize,
19
20
  phase,
20
21
  gate,
21
22
  stackOutput,
@@ -3,7 +3,11 @@
3
3
  * the release the environment runs it from.
4
4
  */
5
5
  import { describe, test, expect } from "vitest";
6
- import { compareInputs, unchangedRecord, type ChangedPaths } from "./unchanged-inputs";
6
+ import { spawnSync } from "node:child_process";
7
+ import { mkdirSync, writeFileSync } from "node:fs";
8
+ import { join } from "node:path";
9
+ import { withTestDir } from "@intentius/chant-test-utils";
10
+ import { compareInputs, gitNormalizedCompare, unchangedRecord, type ChangedPaths, type NormalizedCompare } from "./unchanged-inputs";
7
11
  import { makeRelease, type Release } from "../lifecycle/release-store";
8
12
  import type { ReleaseRecord } from "../lifecycle/release-ledger";
9
13
 
@@ -96,3 +100,147 @@ describe("unchangedRecord", () => {
96
100
  });
97
101
  });
98
102
  });
103
+
104
+ describe("compareInputs with inputs.normalize (#4718)", () => {
105
+ const blank = "scripts/release blank {path}";
106
+ const inputs = {
107
+ paths: ["../crates/control", "../Cargo.lock", "../Cargo.toml"],
108
+ normalize: [{ paths: ["../Cargo.lock", "../Cargo.toml"], command: blank }],
109
+ };
110
+ /** git diff over `paths`: the changed files, and of those the ones a normalize entry's `../<file>` names. */
111
+ const changedPaths = (changed: string[]): ChangedPaths =>
112
+ (_from, _to, paths) => (paths === inputs.paths ? changed : changed.filter((f) => paths.includes(`../${f}`)));
113
+ const compareN = (changed: string[], normalizedCompare?: NormalizedCompare, over: { inputs?: typeof inputs } = {}) =>
114
+ compareInputs({
115
+ component: "control",
116
+ inputs: over.inputs ?? inputs,
117
+ env: "prod",
118
+ release: release("b"),
119
+ current: record(),
120
+ readRelease: async () => before,
121
+ changedPaths: changedPaths(changed),
122
+ ...(normalizedCompare ? { normalizedCompare } : {}),
123
+ });
124
+
125
+ test("a file that is the same after its normalization is unchanged, and the verdict names the normalization", async () => {
126
+ const calls: unknown[] = [];
127
+ const verdict = await compareN(["Cargo.lock", "Cargo.toml"], (command, path, from, to) => (calls.push([command, path, from, to]), { same: true }));
128
+ expect(verdict).toEqual({
129
+ unchanged: true,
130
+ since: record(),
131
+ recorded: false,
132
+ normalized: [
133
+ { path: "Cargo.lock", command: blank },
134
+ { path: "Cargo.toml", command: blank },
135
+ ],
136
+ });
137
+ expect(calls).toEqual([
138
+ [blank, "Cargo.lock", "a".repeat(40), "b".repeat(40)],
139
+ [blank, "Cargo.toml", "a".repeat(40), "b".repeat(40)],
140
+ ]);
141
+ });
142
+
143
+ test("a file that differs after its normalization deploys, and says so", async () => {
144
+ expect(await compareN(["Cargo.lock"], () => ({ same: false }))).toEqual({
145
+ unchanged: false,
146
+ reason: `input file Cargo.lock changed since ${"a".repeat(12)}, also after \`${blank}\``,
147
+ });
148
+ });
149
+
150
+ test("a normalizer that fails counts the file as changed, with its message", async () => {
151
+ expect(await compareN(["Cargo.lock"], () => ({ error: "`scripts/release blank 'Cargo.lock'` exited 2 on Cargo.lock at aaaaaaaaaaaa: no such kind" }))).toEqual({
152
+ unchanged: false,
153
+ reason: "the normalization of Cargo.lock failed, so it counts as changed: `scripts/release blank 'Cargo.lock'` exited 2 on Cargo.lock at aaaaaaaaaaaa: no such kind",
154
+ });
155
+ // With nothing to run the normalizer, a covered file is changed too.
156
+ expect(await compareN(["Cargo.lock"])).toMatchObject({ unchanged: false, reason: expect.stringMatching(/normalization of Cargo\.lock failed, so it counts as changed: no normalizer runs here/) });
157
+ });
158
+
159
+ test("a changed file no normalization covers is compared as before, and no normalizer runs", async () => {
160
+ let ran = 0;
161
+ const counting: NormalizedCompare = () => (ran++, { same: true });
162
+ expect(await compareN(["Cargo.lock", "crates/control/src/main.rs"], counting)).toEqual({
163
+ unchanged: false,
164
+ reason: `1 input file(s) changed since ${"a".repeat(12)}, such as crates/control/src/main.rs`,
165
+ });
166
+ expect(ran).toBe(0);
167
+ // No normalize at all: the plain diff, as before #4718.
168
+ expect(await compareN(["Cargo.lock"], counting, { inputs: { ...inputs, normalize: [] } })).toMatchObject({ unchanged: false, reason: expect.stringMatching(/1 input file\(s\) changed .* such as Cargo\.lock/) });
169
+ expect(ran).toBe(0);
170
+ // Nothing changed: unchanged with nothing normalized.
171
+ expect(await compareN([], counting)).toEqual({ unchanged: true, since: record(), recorded: false });
172
+ });
173
+
174
+ test("the first entry that matches a file is the one used", async () => {
175
+ const two = { ...inputs, normalize: [{ paths: ["../Cargo.lock"], command: "first {path}" }, { paths: ["../Cargo.lock", "../Cargo.toml"], command: blank }] };
176
+ const verdict = await compareN(["Cargo.lock", "Cargo.toml"], () => ({ same: true }), { inputs: two });
177
+ expect(verdict).toMatchObject({ unchanged: true, normalized: [{ path: "Cargo.lock", command: "first {path}" }, { path: "Cargo.toml", command: blank }] });
178
+ });
179
+ });
180
+
181
+ describe("gitNormalizedCompare (#4718)", () => {
182
+ const git = (dir: string, ...args: string[]): string => {
183
+ const r = spawnSync("git", args, { cwd: dir, encoding: "utf-8" });
184
+ if (r.status !== 0) throw new Error(`git ${args.join(" ")}: ${r.stderr}`);
185
+ return r.stdout.trim();
186
+ };
187
+ const commitFile = (dir: string, file: string, content: string): string => {
188
+ mkdirSync(join(dir, file, ".."), { recursive: true });
189
+ writeFileSync(join(dir, file), content);
190
+ git(dir, "add", ".");
191
+ git(dir, "commit", "-q", "-m", `change ${file}`);
192
+ return git(dir, "rev-parse", "HEAD");
193
+ };
194
+ // Blanks the version under [package], as Arugula's `scripts/release blank` does for its own crates.
195
+ const blankVersion = `sed -e 's/^version = ".*"/version = "@V@"/'`;
196
+
197
+ test("runs the command from the top level on each commit's copy, with {path} from the top level", async () => {
198
+ await withTestDir(async (dir) => {
199
+ git(dir, "init", "-q", "-b", "main");
200
+ git(dir, "config", "user.email", "test@chant.dev");
201
+ git(dir, "config", "user.name", "Test");
202
+ const a = commitFile(dir, "crates/control/Cargo.toml", `[package]\nname = "control"\nversion = "1.0.0"\n`);
203
+ const b = commitFile(dir, "crates/control/Cargo.toml", `[package]\nname = "control"\nversion = "1.0.1"\n`);
204
+ const c = commitFile(dir, "crates/control/Cargo.toml", `[package]\nname = "control"\nversion = "1.0.1"\n\n[dependencies]\nserde = "1"\n`);
205
+ mkdirSync(join(dir, "ops"), { recursive: true });
206
+ const compare = gitNormalizedCompare(join(dir, "ops"));
207
+ const path = "crates/control/Cargo.toml";
208
+
209
+ expect(compare(blankVersion, path, a, b)).toEqual({ same: true });
210
+ expect(compare(blankVersion, path, b, c)).toEqual({ same: false });
211
+ // {path} is the path from the top level, and the command's directory is the top level.
212
+ expect(compare(`test -f {path} && ${blankVersion}`, path, a, b)).toEqual({ same: true });
213
+ // A file missing at one commit is changed.
214
+ expect(compare(blankVersion, "crates/control/Cargo.lock", a, b)).toEqual({ same: false });
215
+ // A failing command is an error naming the command, the file, the commit and what it said.
216
+ expect(compare("echo no such kind >&2; exit 2", path, a, b)).toEqual({ error: `\`echo no such kind >&2; exit 2\` exited 2 on ${path} at ${a.slice(0, 12)}: no such kind` });
217
+ });
218
+ });
219
+
220
+ test("a command that exits without reading the file is judged by its exit status, not the write's EPIPE", async () => {
221
+ await withTestDir(async (dir) => {
222
+ git(dir, "init", "-q", "-b", "main");
223
+ git(dir, "config", "user.email", "test@chant.dev");
224
+ git(dir, "config", "user.name", "Test");
225
+ // Larger than a pipe's buffer, so writing it to a command that never reads fails with EPIPE every time.
226
+ const big = "x".repeat(4 * 1024 * 1024) + "\n";
227
+ const a = commitFile(dir, "big.txt", big);
228
+ const b = commitFile(dir, "big.txt", big + "y\n");
229
+ const compare = gitNormalizedCompare(dir);
230
+ expect(compare("exit 3", "big.txt", a, b)).toEqual({ error: `\`exit 3\` exited 3 on big.txt at ${a.slice(0, 12)}` });
231
+ expect(compare("echo same", "big.txt", a, b)).toEqual({ same: true });
232
+ });
233
+ });
234
+ });
235
+
236
+ describe("unchangedRecord with normalized inputs (#4718)", () => {
237
+ test("names each file and its normalization in normalizedInputs", () => {
238
+ const now = release("b");
239
+ const out = unchangedRecord(record(), { releaseDigest: now.releaseDigest, runId: "run-2", timestamp: "2026-11-02T10:00:00.000Z", actor: "ci" }, [
240
+ { path: "Cargo.lock", command: "scripts/release blank {path}" },
241
+ ]);
242
+ expect(out.normalizedInputs).toEqual([{ path: "Cargo.lock", command: "scripts/release blank {path}" }]);
243
+ expect(out.unchangedSince).toEqual({ env: "prod", runId: "run-1", timestamp: "2026-11-01T10:00:00.000Z" });
244
+ expect(unchangedRecord(record(), { releaseDigest: now.releaseDigest, runId: "run-2", timestamp: "2026-11-02T10:00:00.000Z", actor: "ci" }, [])).not.toHaveProperty("normalizedInputs");
245
+ });
246
+ });
@@ -30,12 +30,34 @@
30
30
  * environment, a record made from no release, a release that isn't stored, a
31
31
  * commit git doesn't have. `--deploy-unchanged` deploys it anyway.
32
32
  *
33
+ * A changed file that one of `normalize`'s entries covers (#4718) is compared
34
+ * after that entry's command. A daemon release bumps Arugula's own crate
35
+ * versions in every Cargo.toml and in Cargo.lock, which the hub lists among
36
+ * its inputs; with
37
+ *
38
+ * ```ts
39
+ * normalize: [{ paths: ["../Cargo.lock", "../crates/control/Cargo.toml"], command: "scripts/release blank {path}" }]
40
+ * ```
41
+ *
42
+ * each such file is read at the two commits (`git show <commit>:<path>`),
43
+ * each copy is piped through the command, and the file counts as unchanged
44
+ * when the two outputs are the same bytes. The command runs with `sh -c` from
45
+ * the repository's top level in the checkout, the commit being released, so
46
+ * the same normalizer reads both copies; `{path}` is the file's path from the
47
+ * top level, shell-quoted. It must print the same bytes for the same input.
48
+ * A command that exits non-zero, times out or can't start counts the file as
49
+ * changed and the reason says so. A file that is missing at either commit is
50
+ * changed. A changed file no entry covers is changed as before, and then no
51
+ * command runs. The first entry whose `paths` match a file is the one used.
52
+ *
33
53
  * A skip is recorded ({@link unchangedRecord}): a release record of this
34
54
  * release for the component that repeats the digest of the deploy it keeps
35
- * and names that deploy in `unchangedSince`.
55
+ * and names that deploy in `unchangedSince`. When a file was the same only
56
+ * after a normalization, the record lists it with the command in
57
+ * `normalizedInputs`.
36
58
  */
37
59
 
38
- import { execFileSync } from "node:child_process";
60
+ import { execFileSync, spawnSync } from "node:child_process";
39
61
  import type { ComponentInputs } from "./component";
40
62
  import type { Release } from "../lifecycle/release-store";
41
63
  import type { ReleaseRecord, ReleaseRecordInput, RunOrigin } from "../lifecycle/release-ledger";
@@ -44,6 +66,17 @@ import { releaseTemplatesDigest } from "./release-promote";
44
66
  /** The first chant that reads a component's `inputs` and writes `unchangedSince` on a release record (#4695). */
45
67
  export const UNCHANGED_INPUTS_FLOOR = "0.124.65";
46
68
 
69
+ /** The first chant that reads `inputs.normalize` and writes `normalizedInputs` on a skip record (#4718). */
70
+ export const NORMALIZED_INPUTS_FLOOR = "0.124.68";
71
+
72
+ /** A file that differed between the two commits and was the same after a normalization (#4718). */
73
+ export interface NormalizedInput {
74
+ /** From the repository's top level, as git prints it. */
75
+ path: string;
76
+ /** The `command` of the `normalize` entry that covered it, as declared. */
77
+ command: string;
78
+ }
79
+
47
80
  /** Whether a component's inputs are the same as in the release the environment runs it from. */
48
81
  export type InputsVerdict =
49
82
  | {
@@ -52,6 +85,8 @@ export type InputsVerdict =
52
85
  since: ReleaseRecord;
53
86
  /** The environment's record already names this release: there is nothing new to record. */
54
87
  recorded: boolean;
88
+ /** The files that differed and were the same after a normalization (#4718), when there were any. */
89
+ normalized?: NormalizedInput[];
55
90
  }
56
91
  | { unchanged: false; reason: string };
57
92
 
@@ -62,7 +97,7 @@ export type ChangedPaths = (from: string, to: string, paths: readonly string[])
62
97
  export function gitChangedPaths(memberDir: string): ChangedPaths {
63
98
  return (from, to, paths) => {
64
99
  try {
65
- const out = execFileSync("git", ["diff", "--name-only", "--no-renames", from, to, "--", ...paths], {
100
+ const out = execFileSync("git", ["diff", "--name-only", "--no-renames", "--no-relative", from, to, "--", ...paths], {
66
101
  cwd: memberDir,
67
102
  encoding: "utf-8",
68
103
  stdio: ["ignore", "pipe", "pipe"],
@@ -74,6 +109,55 @@ export function gitChangedPaths(memberDir: string): ChangedPaths {
74
109
  };
75
110
  }
76
111
 
112
+ /**
113
+ * Whether the file at `path` (from the top level) is the same at two commits
114
+ * after `command` reads each copy on stdin (#4718), or why it can't tell.
115
+ */
116
+ export type NormalizedCompare = (command: string, path: string, from: string, to: string) => { same: boolean } | { error: string };
117
+
118
+ /** How long one run of a normalizer may take. */
119
+ const NORMALIZE_TIMEOUT_MS = 60_000;
120
+
121
+ const shellQuote = (s: string): string => `'${s.replace(/'/g, `'\\''`)}'`;
122
+
123
+ /**
124
+ * {@link NormalizedCompare} through git and `sh -c`, from the top level of
125
+ * the repository `memberDir` is in. A file missing at either commit is not
126
+ * the same.
127
+ */
128
+ export function gitNormalizedCompare(memberDir: string): NormalizedCompare {
129
+ let top: string | undefined;
130
+ return (command, path, from, to) => {
131
+ try {
132
+ top ??= execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: memberDir, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
133
+ } catch {
134
+ return { error: `${memberDir} is not in a git work tree` };
135
+ }
136
+ const outputs: Buffer[] = [];
137
+ for (const commit of [from, to]) {
138
+ const show = spawnSync("git", ["show", `${commit}:${path}`], { cwd: top, maxBuffer: 256 * 1024 * 1024 });
139
+ if (show.status !== 0) return { same: false };
140
+ const run = spawnSync("sh", ["-c", command.replaceAll("{path}", shellQuote(path))], {
141
+ cwd: top,
142
+ input: show.stdout,
143
+ timeout: NORMALIZE_TIMEOUT_MS,
144
+ maxBuffer: 256 * 1024 * 1024,
145
+ });
146
+ const at = `${path} at ${commit.slice(0, 12)}`;
147
+ // A command that exits without reading all of its stdin makes the write
148
+ // fail with EPIPE while the command itself ran: its exit status decides.
149
+ const epipe = (run.error as NodeJS.ErrnoException | undefined)?.code === "EPIPE" && run.status !== null;
150
+ if (run.error && !epipe) return { error: `\`${command}\` could not run on ${at}: ${run.error.message}` };
151
+ if (run.status !== 0) {
152
+ const said = run.stderr.toString("utf-8").trim().split("\n")[0];
153
+ return { error: `\`${command}\` ${run.signal ? `was killed (${run.signal})` : `exited ${run.status}`} on ${at}${said ? `: ${said}` : ""}` };
154
+ }
155
+ outputs.push(run.stdout);
156
+ }
157
+ return { same: outputs[0]!.equals(outputs[1]!) };
158
+ };
159
+ }
160
+
77
161
  const shortDigest = (d: string): string => d.replace(/^jcs1-sha256:/, "").slice(0, 12);
78
162
 
79
163
  /** Compare `component`'s declared inputs in `release` with the release the environment's `current` record names. */
@@ -86,8 +170,11 @@ export async function compareInputs(input: {
86
170
  current: ReleaseRecord | undefined;
87
171
  readRelease: (digest: string) => Promise<Release | null>;
88
172
  changedPaths: ChangedPaths;
173
+ /** Compares a file `inputs.normalize` covers (#4718); without it such a file counts as changed. */
174
+ normalizedCompare?: NormalizedCompare;
89
175
  }): Promise<InputsVerdict> {
90
176
  const { component, inputs, env, release, current } = input;
177
+ const normalized: NormalizedInput[] = [];
91
178
  const paths = inputs.paths ?? [];
92
179
  const params = inputs.params ?? [];
93
180
  if (paths.length === 0 && params.length === 0) return { unchanged: false, reason: "it declares no paths or params in inputs" };
@@ -114,11 +201,48 @@ export async function compareInputs(input: {
114
201
  if (changed === null) {
115
202
  return { unchanged: false, reason: `git can't compare ${prior.commit.slice(0, 12)} and ${release.commit.slice(0, 12)} here; fetch the history between them` };
116
203
  }
117
- if (changed.length > 0) {
118
- return { unchanged: false, reason: `${changed.length} input file(s) changed since ${prior.commit.slice(0, 12)}, such as ${changed[0]}` };
204
+ const since = prior.commit.slice(0, 12);
205
+ const covering = normalizeCoverage(inputs, changed, (p) => input.changedPaths(prior.commit, release.commit, p));
206
+ if ("error" in covering) return { unchanged: false, reason: covering.error };
207
+ const plain = changed.filter((f) => !covering.byFile.has(f));
208
+ if (plain.length > 0) {
209
+ return { unchanged: false, reason: `${plain.length} input file(s) changed since ${since}, such as ${plain[0]}` };
210
+ }
211
+ for (const [file, command] of covering.byFile) {
212
+ const result = input.normalizedCompare
213
+ ? input.normalizedCompare(command, file, prior.commit, release.commit)
214
+ : { error: "no normalizer runs here" };
215
+ if ("error" in result) {
216
+ return { unchanged: false, reason: `the normalization of ${file} failed, so it counts as changed: ${result.error}` };
217
+ }
218
+ if (!result.same) {
219
+ return { unchanged: false, reason: `input file ${file} changed since ${since}, also after \`${command}\`` };
220
+ }
221
+ normalized.push({ path: file, command });
119
222
  }
120
223
  }
121
- return { unchanged: true, since: current, recorded: false };
224
+ return { unchanged: true, since: current, recorded: false, ...(normalized.length > 0 ? { normalized } : {}) };
225
+ }
226
+
227
+ /**
228
+ * The `normalize` entry, by its command, that covers each of the `changed`
229
+ * files (#4718): the first entry whose `paths` git matches the file with.
230
+ */
231
+ function normalizeCoverage(
232
+ inputs: ComponentInputs,
233
+ changed: readonly string[],
234
+ matching: (paths: readonly string[]) => string[] | null,
235
+ ): { byFile: Map<string, string> } | { error: string } {
236
+ const byFile = new Map<string, string>();
237
+ if (changed.length === 0) return { byFile };
238
+ const pending = new Set(changed);
239
+ for (const entry of inputs.normalize ?? []) {
240
+ if (entry.paths.length === 0) continue;
241
+ const matched = matching(entry.paths);
242
+ if (matched === null) return { error: `git can't match the paths of the normalization \`${entry.command}\`, so its files count as changed` };
243
+ for (const f of matched) if (pending.delete(f)) byFile.set(f, entry.command);
244
+ }
245
+ return { byFile };
122
246
  }
123
247
 
124
248
  /**
@@ -130,6 +254,7 @@ export async function compareInputs(input: {
130
254
  export function unchangedRecord(
131
255
  since: ReleaseRecord,
132
256
  run: { releaseDigest: string; runId: string; runOrigin?: RunOrigin; timestamp: string; actor: string },
257
+ normalized?: readonly NormalizedInput[],
133
258
  ): ReleaseRecordInput {
134
259
  return {
135
260
  component: since.component,
@@ -146,5 +271,6 @@ export function unchangedRecord(
146
271
  actor: run.actor,
147
272
  releaseDigest: run.releaseDigest,
148
273
  unchangedSince: { env: since.env, runId: since.runId, timestamp: since.timestamp },
274
+ ...(normalized && normalized.length > 0 ? { normalizedInputs: normalized.map((n) => ({ path: n.path, command: n.command })) } : {}),
149
275
  };
150
276
  }
@@ -253,6 +253,15 @@ export interface ReleaseRecord {
253
253
  * every deploy.
254
254
  */
255
255
  unchangedSince?: ReleaseRef;
256
+ /**
257
+ * Optional: on a skip record (`unchangedSince`), the input files that
258
+ * differed between the two releases' commits and were the same after a
259
+ * normalization the component declares in `inputs.normalize` (#4718), each
260
+ * with that normalization's command. Written from chant
261
+ * `NORMALIZED_INPUTS_FLOOR` (../components/unchanged-inputs.ts); absent
262
+ * when no file needed one.
263
+ */
264
+ normalizedInputs?: { path: string; command: string }[];
256
265
  /**
257
266
  * Optional: the release this deploy came from (#4026, ws-104), the
258
267
  * `releaseDigest` of `_releases/<releaseDigest>.json`. Written by
@@ -19,4 +19,4 @@
19
19
  * this constant to the next patch (#4501). The check fails while a floor
20
20
  * still names this constant after its version shipped.
21
21
  */
22
- export const NEXT_RELEASE = "0.124.67";
22
+ export const NEXT_RELEASE = "0.124.69";