@wringer/core 0.1.1 → 0.2.0

package/README.md

@@ -39,6 +39,7 @@ export const registry = createWringer({ name: 'shop' })
     }),
   })
   .feature({ name: 'checkout', summary: 'Pay for the cart', paths: ['src/checkout/**'] })
+  .ignore('docs/**', '**/*.md', '**/*.test.ts')
   .build();
 ```
 
@@ -53,22 +54,28 @@ own file.
 - Read-only targets: each driver client and exec refuses a write there with `read-only` and the
   target's hint. A target's driver config lists the writes it grants.
 - One supervisor process per run, which owns the app and every driver service.
-- The built-in commands, from `up` and `doctor` to `done`, `report` and `gate`.
+- The built-in commands, from `up` and `doctor` to `done`, `report` and `gate`. `gate` fails a PR
+  when a changed feature lacks a verdict at the current fingerprint, and when a changed path matches
+  neither a feature's `paths` nor an `.ignore` glob. `report` lists those unmapped paths.
+- The ignore list: `.ignore(...globs)` names the paths with no runtime effect, such as docs and
+  tests. Any path an ignore glob matches counts as no change, even when a feature's `paths` match it
+  too. The gate skips it and the fingerprint leaves it out, so a README edit keeps each verdict
+  fresh. Feature `paths` and ignore globs both match with `Bun.Glob`.
 - The envelope's zod schema, and the JSON Schema built from it.
 - A closed set of error codes, each mapped to one exit code.
 - Run state on disk: `state.json` holds pointers, and each run's `log.ndjson` holds its events.
-- The fingerprint: `git patch-id --verbatim` of the working tree against the merge base, which stays
-  the same across a commit and across a clean rebase that leaves the 3 lines around each change as
-  they were. A rebase that changes those lines changes the fingerprint, because the hash keeps the
-  diff's context. It needs git 2.39 or later. Only the tracked files and git's defaults shape it:
-  the config, attributes and ignore files of the clone, the user and the system never apply, so the
-  same change gets the same fingerprint in any clone. A clone whose config converts a file as git
-  adds it, such as `core.autocrlf` or a clean filter, can get another fingerprint once the change is
-  committed; the verdict then reads as stale, never as fresh. A sparse checkout, a linked worktree,
-  a shallow or partial clone and a detached HEAD get the fingerprint of the same change in a full
-  clone, and a file on disk that the index marks skip-worktree counts as any other. A repo with no
-  commit, a shallow clone that lacks the merge base, and a submodule that holds work it has not
-  committed fail with an `environment` error.
+- The fingerprint: `git patch-id --verbatim` of the working tree against the merge base, less the
+  state folder and the ignored paths, which stays the same across a commit and across a clean rebase
+  that leaves the 3 lines around each change as they were. A rebase that changes those lines changes
+  the fingerprint, because the hash keeps the diff's context. It needs git 2.39 or later. Only the
+  tracked files and git's defaults shape it: the config, attributes and ignore files of the clone,
+  the user and the system never apply, so the same change gets the same fingerprint in any clone. A
+  clone whose config converts a file as git adds it, such as `core.autocrlf` or a clean filter, can
+  get another fingerprint once the change is committed; the verdict then reads as stale, never as
+  fresh. A sparse checkout, a linked worktree, a shallow or partial clone and a detached HEAD get
+  the fingerprint of the same change in a full clone, and a file on disk that the index marks
+  skip-worktree counts as any other. A repo with no commit, a shallow clone that lacks the merge
+  base, and a submodule that holds work it has not committed fail with an `environment` error.
 - Two hosts for exec: `local()`, and `ssh()` with an argv prefix in layers, quoted once per shell
   layer. Each host also follows a long-running command, such as `tail -F`, line by line.
 

package/dist/build-change-request.d.ts

@@ -0,0 +1,8 @@
+import type { Wringer } from './types.ts';
+export interface ChangeRequest {
+    readonly cwd: string;
+    readonly base: string;
+    readonly exclude: readonly string[];
+    readonly ignore: readonly string[];
+}
+export declare function buildChangeRequest(wringer: Pick<Wringer, 'stateDir' | 'ignore'>, cwd: string, base: string): ChangeRequest;

package/dist/create-wringer.d.ts

@@ -10,6 +10,7 @@ export interface WringerBuilder<Ds extends AnyDrivers> {
     readonly action: <Input, Data>(action: ActionDefinition<Input, Data, Ds>) => WringerBuilder<Ds>;
     readonly check: <Input, Data>(check: CheckDefinition<Input, Data, Ds>) => WringerBuilder<Ds>;
     readonly feature: (...features: readonly FeatureDefinition[]) => WringerBuilder<Ds>;
+    readonly ignore: (...globs: readonly string[]) => WringerBuilder<Ds>;
     readonly hook: <Name extends keyof HookHandlers>(name: Name, handler: HookHandlers[Name]) => WringerBuilder<Ds>;
     readonly build: () => Wringer;
 }

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { bindDrivers } from './bind-drivers.ts';
 export type { BoundHelpers } from './bind-drivers.ts';
+export { buildBuiltinCommand } from './build-commands.ts';
 export { buildEnvelope } from './build-envelope.ts';
 export type { EnvelopeInput } from './build-envelope.ts';
 export { buildEnvelopeJSONSchema } from './build-envelope-json-schema.ts';
@@ -16,6 +17,7 @@ export type { StateFileSystem } from './create-node-state-file-system.ts';
 export { createWringer, defaultStateDir } from './create-wringer.ts';
 export type { WringerBuilder, WringerOptions } from './create-wringer.ts';
 export { defineDriver } from './define-driver.ts';
+export { prepareArgs } from './prepare-args.ts';
 export { findOwnValue } from './find-own-value.ts';
 export type { DriverDefinition, DriverFactory } from './define-driver.ts';
 export { dataCapBytes } from './cap-data.ts';

package/dist/is-glob-match.d.ts

@@ -0,0 +1 @@
+export declare function isGlobMatch(path: string, globs: readonly string[]): boolean;

package/dist/pick-submodule-refusal.d.ts

@@ -1,2 +1,2 @@
 import { WringerError } from './wringer-error.ts';
-export declare function pickSubmoduleRefusal(statusEntries: Uint8Array): WringerError | null;
+export declare function pickSubmoduleRefusal(statusEntries: Uint8Array, ignore: readonly string[]): WringerError | null;

package/dist/read-changed-paths.d.ts

@@ -1,7 +1,3 @@
+import type { ChangeRequest } from './build-change-request.ts';
 import type { FingerprintHost } from './read-fingerprint.ts';
-export interface ChangedPathsRequest {
-    readonly cwd: string;
-    readonly base: string;
-    readonly exclude: readonly string[];
-}
-export declare function readChangedPaths(host: Pick<FingerprintHost, 'runGit'>, request: ChangedPathsRequest): Promise<readonly string[]>;
+export declare function readChangedPaths(host: Pick<FingerprintHost, 'runGit' | 'runGitBytes'>, request: ChangeRequest): Promise<readonly string[]>;

package/dist/read-fingerprint.d.ts

@@ -1,3 +1,4 @@
+import type { ChangeRequest } from './build-change-request.ts';
 import type { GitRequest } from './run-git.ts';
 import type { ProcessResult } from './run-process.ts';
 export interface FingerprintHost {
@@ -5,9 +6,5 @@ export interface FingerprintHost {
     readonly runGitBytes: (request: GitRequest) => Promise<Uint8Array>;
     readonly removeDirectory: (path: string) => Promise<void>;
 }
-export interface FingerprintRequest {
-    readonly cwd: string;
-    readonly base: string;
-    readonly exclude: readonly string[];
-}
+export type FingerprintRequest = ChangeRequest;
 export declare function readFingerprint(host: FingerprintHost, request: FingerprintRequest): Promise<string>;

package/dist/report-schema.d.ts

@@ -46,6 +46,7 @@ export declare const reportSchema: z.ZodObject<{
             }, z.core.$strict>>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
+    unmapped: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 export type Report = z.infer<typeof reportSchema>;
 export {};

package/dist/types.d.ts

@@ -317,6 +317,7 @@ export interface Wringer {
     readonly commands: ReadonlyMap<string, RegisteredCommand>;
     readonly checks: readonly RunnableRepoCheck[];
     readonly features: readonly FeatureDefinition[];
+    readonly ignore: readonly string[];
     readonly hooks: Partial<HookHandlers>;
 }
 export interface SupervisorStartRequest {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wringer/core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "The core of wringer: the envelope, the registry, the fence, the run state and the evidence",
   "homepage": "https://github.com/zgeoff/wringer/tree/main/packages/core#readme",
   "bugs": "https://github.com/zgeoff/wringer/issues",
@@ -35,13 +35,13 @@
     "schema": "bun scripts/write-envelope-schema.ts"
   },
   "dependencies": {
-    "@zgeoff/std": "0.4.2",
+    "@zgeoff/std": "0.4.3",
     "ts-pattern": "5.9.2",
     "xstate": "5.33.3",
     "zod": "4.6.7"
   },
   "devDependencies": {
-    "@zgeoff/testing": "0.2.1",
+    "@zgeoff/testing": "0.3.0",
     "ajv": "8.20.0",
     "tiny-invariant": "1.3.3"
   },

package/src/build-change-request.ts

@@ -0,0 +1,18 @@
+import type { Wringer } from './types.ts';
+
+export interface ChangeRequest {
+  readonly cwd: string;
+  readonly base: string;
+  readonly exclude: readonly string[];
+  readonly ignore: readonly string[];
+}
+
+// Every read of the fingerprint or the changed paths leaves out the same paths, so a verdict, a run
+// and the gate agree on what the branch changes.
+export function buildChangeRequest(
+  wringer: Pick<Wringer, 'stateDir' | 'ignore'>,
+  cwd: string,
+  base: string,
+): ChangeRequest {
+  return { cwd, base, exclude: [wringer.stateDir], ignore: wringer.ignore };
+}

package/src/build-report.ts

@@ -1,3 +1,4 @@
+import { isGlobMatch } from './is-glob-match.ts';
 import type { FeatureStatus, Report, Verdict } from './report-schema.ts';
 import type { FeatureDefinition } from './types.ts';
 
@@ -10,13 +11,11 @@ export interface ReportInput {
 }
 
 // Each feature whose paths the branch changes needs a verdict at the current fingerprint. A feature
-// the branch leaves alone is `unchanged`, whatever its verdict.
+// the branch leaves alone is `unchanged`, whatever its verdict. A changed path no feature maps is
+// unmapped, and leaves the report incomplete.
 export function buildReport(input: ReportInput): Report {
   const features = input.features.map((feature) => {
-    const changed = input.changedPaths.some((path) =>
-      feature.paths.some((pattern) => new Bun.Glob(pattern).match(path)),
-    );
-
+    const changed = input.changedPaths.some((path) => isGlobMatch(path, feature.paths));
     const verdict = input.verdicts.get(feature.name) ?? null;
 
     return {
@@ -27,14 +26,19 @@ export function buildReport(input: ReportInput): Report {
     };
   });
 
+  const unmapped = input.changedPaths.filter(
+    (path) => !input.features.some((feature) => isGlobMatch(path, feature.paths)),
+  );
+
   return {
     version: 1,
     base: input.base,
     fingerprint: input.fingerprint,
-    complete: features.every(
-      (feature) => feature.status === 'verified' || feature.status === 'unchanged',
-    ),
+    complete:
+      unmapped.length === 0 &&
+      features.every((feature) => feature.status === 'verified' || feature.status === 'unchanged'),
     features,
+    unmapped,
   };
 }
 

package/src/builtins/build-verdict-commands.ts

@@ -1,5 +1,6 @@
 import { isAbsolute, join } from 'node:path';
 import { z } from 'zod';
+import { buildChangeRequest } from '../build-change-request.ts';
 import { buildBuiltinCommand } from '../build-commands.ts';
 import { buildReport } from '../build-report.ts';
 import type { Evidence } from '../envelope.ts';
@@ -38,6 +39,7 @@ const gateFailureSchema = z.strictObject({ name: z.string(), reason: z.string()
 const gateDataSchema = z.strictObject({
   fingerprint: z.string(),
   failing: z.array(gateFailureSchema),
+  unmapped: z.array(z.string()),
 });
 
 type GateData = z.infer<typeof gateDataSchema>;
@@ -47,7 +49,8 @@ type GateData = z.infer<typeof gateDataSchema>;
 export function buildVerdictCommands(): readonly RegisteredCommand[] {
   const done: BuiltinCommandSpec<DoneArgs, Verdict> = {
     path: [doneCommand],
-    summary: 'Record a verdict for a feature from the drives since the doctor passed',
+    summary:
+      'Record a verdict for a feature from its commands that touched the app since the doctor passed',
     args: doneArgsSchema,
     data: verdictSchema,
     effect: 'read',
@@ -75,7 +78,7 @@ export function buildVerdictCommands(): readonly RegisteredCommand[] {
   const gate: BuiltinCommandSpec<GateArgs, GateData> = {
     path: ['gate'],
     summary:
-      'Fail when a changed feature lacks a verdict at the current fingerprint in the PR body',
+      'Fail when a changed feature lacks a verdict at the current fingerprint in the PR body, or a changed path maps to no feature',
     args: gateArgsSchema,
     data: gateDataSchema,
     effect: 'read',
@@ -120,7 +123,7 @@ async function recordVerdict(args: DoneArgs, ctx: BuiltinContext): Promise<Verdi
 
   if (drives.length === 0) {
     throw new WringerError('check-failed', {
-      message: `No drive of ${feature} passed on run ${ctx.run.runID} since the doctor passed.`,
+      message: `No command of ${feature} that touches the app passed on run ${ctx.run.runID} since the doctor passed.`,
       hint: `Drive the feature with \`--feature ${feature}\`, then run \`done\` again.`,
     });
   }
@@ -140,11 +143,10 @@ async function recordVerdict(args: DoneArgs, ctx: BuiltinContext): Promise<Verdi
 }
 
 function readCurrentFingerprint(ctx: BuiltinContext, base: string): Promise<string> {
-  return readFingerprint(ctx.session.repoHost, {
-    cwd: ctx.session.root,
-    base,
-    exclude: [ctx.wringer.stateDir],
-  });
+  return readFingerprint(
+    ctx.session.repoHost,
+    buildChangeRequest(ctx.wringer, ctx.session.root, base),
+  );
 }
 
 async function readReport(ctx: BuiltinContext, givenBase: string | undefined): Promise<Report> {
@@ -152,11 +154,7 @@ async function readReport(ctx: BuiltinContext, givenBase: string | undefined): P
 
   const [fingerprint, changedPaths, verdicts] = await Promise.all([
     readCurrentFingerprint(ctx, base),
-    readChangedPaths(ctx.session.repoHost, {
-      cwd: ctx.session.root,
-      base,
-      exclude: [ctx.wringer.stateDir],
-    }),
+    readChangedPaths(ctx.session.repoHost, buildChangeRequest(ctx.wringer, ctx.session.root, base)),
     readVerdicts(ctx.state, ctx.session.repoHost, ctx.session.root),
   ]);
 
@@ -211,11 +209,10 @@ async function checkGate(args: GateArgs, ctx: BuiltinContext): Promise<GateData>
 
   const [fingerprint, changedPaths] = await Promise.all([
     readCurrentFingerprint(ctx, args.base),
-    readChangedPaths(ctx.session.repoHost, {
-      cwd: ctx.session.root,
-      base: args.base,
-      exclude: [ctx.wringer.stateDir],
-    }),
+    readChangedPaths(
+      ctx.session.repoHost,
+      buildChangeRequest(ctx.wringer, ctx.session.root, args.base),
+    ),
   ]);
 
   const claimed = block.ok
@@ -251,15 +248,44 @@ async function checkGate(args: GateArgs, ctx: BuiltinContext): Promise<GateData>
     return [];
   });
 
-  const data = { fingerprint, failing };
+  const data = { fingerprint, failing, unmapped: computed.unmapped };
 
-  if (failing.length > 0) {
+  if (failing.length > 0 || computed.unmapped.length > 0) {
     throw new WringerError('check-failed', {
-      message: `${failing.length} changed feature(s) lack a verdict at the current fingerprint: ${failing.map((feature) => feature.name).join(', ')}.`,
-      hint: 'Drive each feature, run `done` and `report --human`, and update the PR body.',
+      message: formatGateFailure(failing, computed.unmapped),
+      hint: pickGateHint(failing, computed.unmapped),
       data,
     });
   }
 
   return data;
 }
+
+function formatGateFailure(
+  failing: readonly { readonly name: string }[],
+  unmapped: readonly string[],
+): string {
+  const lines = [
+    failing.length > 0
+      ? `${failing.length} changed feature(s) lack a verdict at the current fingerprint: ${failing.map((feature) => feature.name).join(', ')}.`
+      : null,
+    unmapped.length > 0
+      ? `${unmapped.length} changed path(s) map to no feature: ${unmapped.join(', ')}.`
+      : null,
+  ];
+
+  return lines.filter((line) => line !== null).join(' ');
+}
+
+const verdictHint = 'Drive each feature, run `done` and `report --human`, and update the PR body.';
+
+const unmappedHint =
+  "Add each unmapped path to a feature's `paths`, or to the registry's ignore list when it has no runtime effect.";
+
+function pickGateHint(failing: readonly unknown[], unmapped: readonly string[]): string {
+  if (unmapped.length === 0) {
+    return verdictHint;
+  }
+
+  return failing.length === 0 ? unmappedHint : `${unmappedHint} ${verdictHint}`;
+}

package/src/builtins/start-run.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { buildChangeRequest } from '../build-change-request.ts';
 import type { RunView } from '../build-run-view.ts';
 import { findOwnValue } from '../find-own-value.ts';
 import { readDefaultBase } from '../read-default-base.ts';
@@ -52,11 +53,10 @@ export function startRun(ctx: BuiltinContext, request: StartRunRequest): Promise
 
     const base = await readDefaultBase(ctx.session.repoHost, ctx.session.root);
 
-    const fingerprint = await readFingerprint(ctx.session.repoHost, {
-      cwd: ctx.session.root,
-      base,
-      exclude: [ctx.wringer.stateDir],
-    });
+    const fingerprint = await readFingerprint(
+      ctx.session.repoHost,
+      buildChangeRequest(ctx.wringer, ctx.session.root, base),
+    );
 
     // The caller has its timeout already once the deadline passes, so no run starts after it.
     if (ctx.signal.aborted) {

package/src/create-wringer.ts

@@ -33,6 +33,7 @@ export interface WringerBuilder<Ds extends AnyDrivers> {
   readonly action: <Input, Data>(action: ActionDefinition<Input, Data, Ds>) => WringerBuilder<Ds>;
   readonly check: <Input, Data>(check: CheckDefinition<Input, Data, Ds>) => WringerBuilder<Ds>;
   readonly feature: (...features: readonly FeatureDefinition[]) => WringerBuilder<Ds>;
+  readonly ignore: (...globs: readonly string[]) => WringerBuilder<Ds>;
   readonly hook: <Name extends keyof HookHandlers>(
     name: Name,
     handler: HookHandlers[Name],
@@ -50,6 +51,7 @@ export function createWringer(options: WringerOptions): WringerBuilder<readonly
     commands: [],
     checks: [],
     features: [],
+    ignore: [],
     hooks: {},
   });
 }
@@ -61,6 +63,7 @@ interface Parts {
   readonly commands: readonly ((driverNames: readonly string[]) => RegisteredCommand)[];
   readonly checks: readonly ((driverNames: readonly string[]) => RunnableRepoCheck)[];
   readonly features: readonly FeatureDefinition[];
+  readonly ignore: readonly string[];
   readonly hooks: Partial<HookHandlers>;
 }
 
@@ -83,6 +86,7 @@ function makeBuilder<Ds extends AnyDrivers>(parts: Parts): WringerBuilder<Ds> {
     check: (check) =>
       makeBuilder({ ...parts, checks: [...parts.checks, (names) => buildRepoCheck(check, names)] }),
     feature: (...features) => makeBuilder({ ...parts, features: [...parts.features, ...features] }),
+    ignore: (...globs) => makeBuilder({ ...parts, ignore: [...parts.ignore, ...globs] }),
     hook: (name, handler) => makeBuilder({ ...parts, hooks: { ...parts.hooks, [name]: handler } }),
     build: () => buildWringer(parts),
   };
@@ -147,6 +151,7 @@ function buildWringer(parts: Parts): Wringer {
     ),
     checks: Object.freeze(parts.checks.map((buildEntry) => buildEntry(driverNames))),
     features: Object.freeze([...parts.features]),
+    ignore: Object.freeze([...parts.ignore]),
     hooks: Object.freeze({ ...parts.hooks }),
   });
 }

package/src/dispatch.ts

@@ -1,5 +1,6 @@
 import { join } from 'node:path';
 import { match } from 'ts-pattern';
+import { buildChangeRequest } from './build-change-request.ts';
 import { buildEnvelope } from './build-envelope.ts';
 import type { RunView } from './build-run-view.ts';
 import { buildRunPaths } from './build-state-paths.ts';
@@ -367,11 +368,10 @@ async function runCommand(request: CommandRequest): Promise<CommandOutcome> {
 async function probeFingerprintChanged(request: CommandRequest): Promise<boolean> {
   const base = await readDefaultBase(request.session.repoHost, request.session.root);
 
-  const fingerprint = await readFingerprint(request.session.repoHost, {
-    cwd: request.session.root,
-    base,
-    exclude: [request.wringer.stateDir],
-  });
+  const fingerprint = await readFingerprint(
+    request.session.repoHost,
+    buildChangeRequest(request.wringer, request.session.root, base),
+  );
 
   return fingerprint !== request.context.run?.fingerprint;
 }

package/src/index.ts

@@ -1,5 +1,6 @@
 export { bindDrivers } from './bind-drivers.ts';
 export type { BoundHelpers } from './bind-drivers.ts';
+export { buildBuiltinCommand } from './build-commands.ts';
 export { buildEnvelope } from './build-envelope.ts';
 export type { EnvelopeInput } from './build-envelope.ts';
 export { buildEnvelopeJSONSchema } from './build-envelope-json-schema.ts';
@@ -16,6 +17,7 @@ export type { StateFileSystem } from './create-node-state-file-system.ts';
 export { createWringer, defaultStateDir } from './create-wringer.ts';
 export type { WringerBuilder, WringerOptions } from './create-wringer.ts';
 export { defineDriver } from './define-driver.ts';
+export { prepareArgs } from './prepare-args.ts';
 export { findOwnValue } from './find-own-value.ts';
 export type { DriverDefinition, DriverFactory } from './define-driver.ts';
 export { dataCapBytes } from './cap-data.ts';

package/src/is-glob-match.ts

@@ -0,0 +1,5 @@
+// Every glob matches through Bun's matcher, never as a git pathspec, whose `*` and `**` differ, so
+// the changed paths, the fingerprint and the report agree on which paths a glob covers.
+export function isGlobMatch(path: string, globs: readonly string[]): boolean {
+  return globs.some((glob) => new Bun.Glob(glob).match(path));
+}

package/src/pick-submodule-refusal.ts

@@ -1,10 +1,16 @@
+import { isGlobMatch } from './is-glob-match.ts';
 import { WringerError } from './wringer-error.ts';
 
 // `status --porcelain=v2` gives each submodule a field `S<c><m><u>`: `m` is `M` when its tracked
 // files changed and `u` is `U` when it holds untracked files. A moved commit alone reaches the
 // fingerprint through the gitlink, but work inside a submodule never does.
-export function pickSubmoduleRefusal(statusEntries: Uint8Array): WringerError | null {
-  const dirty = collectDirtySubmodules(Buffer.from(statusEntries).toString('utf8'));
+export function pickSubmoduleRefusal(
+  statusEntries: Uint8Array,
+  ignore: readonly string[],
+): WringerError | null {
+  const dirty = collectDirtySubmodules(Buffer.from(statusEntries).toString('utf8')).filter(
+    (path) => !isGlobMatch(path, ignore),
+  );
 
   if (dirty.length === 0) {
     return null;

package/src/read-changed-paths.ts

@@ -1,16 +1,12 @@
+import type { ChangeRequest } from './build-change-request.ts';
+import { isGlobMatch } from './is-glob-match.ts';
 import type { FingerprintHost } from './read-fingerprint.ts';
 
-export interface ChangedPathsRequest {
-  readonly cwd: string;
-  readonly base: string;
-  readonly exclude: readonly string[];
-}
-
 // The paths the branch changes against its merge base: committed, staged and unstaged edits, and
-// untracked files that git does not ignore.
+// untracked files that git does not ignore. A path an ignore glob matches is left out.
 export async function readChangedPaths(
-  host: Pick<FingerprintHost, 'runGit'>,
-  request: ChangedPathsRequest,
+  host: Pick<FingerprintHost, 'runGit' | 'runGitBytes'>,
+  request: ChangeRequest,
 ): Promise<readonly string[]> {
   const mergeBaseResult = await host.runGit({
     cwd: request.cwd,
@@ -21,19 +17,41 @@ export async function readChangedPaths(
   const excludes = request.exclude.map((path) => `:(exclude)${path}`);
 
   // `-z` gives each path as it is: without it, git quotes a path with a tab, a newline or a
-  // non-ASCII letter, and the quoted form matches no feature's glob.
+  // non-ASCII letter, and the quoted form matches no feature's glob. Each path is decoded on its
+  // own, as the fingerprint decodes it, so a leading byte-order mark stays part of the name.
   const [tracked, untracked] = await Promise.all([
-    host.runGit({
+    host.runGitBytes({
       cwd: request.cwd,
       args: ['diff', '--name-only', '-z', '--no-renames', mergeBase, '--', '.', ...excludes],
     }),
-    host.runGit({
+    host.runGitBytes({
       cwd: request.cwd,
       args: ['ls-files', '-z', '--others', '--exclude-standard', '--', '.', ...excludes],
     }),
   ]);
 
-  const paths = `${tracked.stdout}\0${untracked.stdout}`.split('\0').filter((path) => path !== '');
+  const paths = [...splitNames(tracked), ...splitNames(untracked)].filter(
+    (path) => !isGlobMatch(path, request.ignore),
+  );
 
   return [...new Set(paths)].toSorted();
 }
+
+function splitNames(output: Uint8Array): readonly string[] {
+  const names: string[] = [];
+  const bytes = Buffer.from(output);
+  let start = 0;
+
+  while (start < bytes.length) {
+    const end = bytes.indexOf(0, start);
+    const stop = end === -1 ? bytes.length : end;
+
+    if (stop > start) {
+      names.push(bytes.subarray(start, stop).toString('utf8'));
+    }
+
+    start = stop + 1;
+  }
+
+  return names;
+}

package/src/read-fingerprint.ts

@@ -1,8 +1,10 @@
 import { randomUUID } from 'node:crypto';
 import { join, resolve } from 'node:path';
+import type { ChangeRequest } from './build-change-request.ts';
 import { buildPromisedObjectReads } from './build-promised-object-reads.ts';
 import { buildSkipWorktreeMarks } from './build-skip-worktree-marks.ts';
 import { buildSubmoduleAdds } from './build-submodule-adds.ts';
+import { isGlobMatch } from './is-glob-match.ts';
 import { parsePatchID } from './parse-patch-id.ts';
 import { pickMergeBaseFailure } from './pick-merge-base-failure.ts';
 import { pickMergeBaseSteps } from './pick-merge-base-steps.ts';
@@ -17,11 +19,9 @@ export interface FingerprintHost {
   readonly removeDirectory: (path: string) => Promise<void>;
 }
 
-export interface FingerprintRequest {
-  readonly cwd: string;
-  readonly base: string;
-  readonly exclude: readonly string[];
-}
+// `ignore` holds globs of paths with no runtime effect: a change to a path one matches leaves the
+// fingerprint alone.
+export type FingerprintRequest = ChangeRequest;
 
 const pinnedDiffOptions = [
   '--unified=3',
@@ -46,7 +46,7 @@ export async function readFingerprint(
   const mergeBase = await readMergeBase(host, root, request.base);
 
   await readPromisedObjects(host, root, mergeBase);
-  await readSubmoduleWork(host, root);
+  await readSubmoduleWork(host, root, request.ignore);
 
   const gitDir = await readGitPath(host, root, `wringer-${randomUUID()}`);
 
@@ -75,6 +75,7 @@ export async function readFingerprint(
     });
 
     await addSubmodules(host, root, env);
+    await restoreIgnoredPaths(host, { root, env, mergeBase, ignore: request.ignore });
 
     // The exclusions apply to the diff, not to `add`: `add` refuses an ignored path in a pathspec,
     // and a committed change to an excluded path reaches the index from the repo's own anyway.
@@ -156,7 +157,11 @@ async function readPromisedObjects(
 
 // `--no-optional-locks` keeps status from writing the repo's own index, and `-uno` skips the
 // repo's own untracked files, which `add --all` counts anyway.
-async function readSubmoduleWork(host: FingerprintHost, root: string): Promise<void> {
+async function readSubmoduleWork(
+  host: FingerprintHost,
+  root: string,
+  ignore: readonly string[],
+): Promise<void> {
   const status = await host.runGitBytes({
     cwd: root,
     args: [
@@ -169,7 +174,7 @@ async function readSubmoduleWork(host: FingerprintHost, root: string): Promise<v
     ],
   });
 
-  const refusal = pickSubmoduleRefusal(status);
+  const refusal = pickSubmoduleRefusal(status, ignore);
 
   if (refusal !== null) {
     throw refusal;
@@ -269,3 +274,95 @@ async function addSubmodules(
     await host.runGit(request);
   }
 }
+
+interface IgnoredPathsRequest {
+  readonly root: string;
+  readonly env: Readonly<Record<string, string>>;
+  readonly mergeBase: string;
+  readonly ignore: readonly string[];
+}
+
+// Each changed path an ignore glob matches goes back to its merge-base state in the index, so the
+// diff leaves it out. The names go to git as the bytes it listed, on stdin, so a name that is not
+// UTF-8 still matches, no count of names outgrows the argument list, and `*` stays a plain letter.
+async function restoreIgnoredPaths(
+  host: FingerprintHost,
+  request: IgnoredPathsRequest,
+): Promise<void> {
+  if (request.ignore.length === 0) {
+    return;
+  }
+
+  const names = await host.runGitBytes({
+    cwd: request.root,
+    args: [
+      'diff',
+      '--cached',
+      '--name-only',
+      '-z',
+      '--no-renames',
+      '--no-relative',
+      request.mergeBase,
+    ],
+    env: request.env,
+  });
+
+  const ignored = collectIgnoredNames(Buffer.from(names), request.ignore);
+
+  if (ignored.length === 0) {
+    return;
+  }
+
+  await host.runGit({
+    cwd: request.root,
+    args: [
+      '--literal-pathspecs',
+      'restore',
+      '--staged',
+      `--source=${request.mergeBase}`,
+      '--pathspec-from-file=-',
+      '--pathspec-file-nul',
+    ],
+    stdin: Buffer.concat(ignored.flatMap((name) => [name, Buffer.from([0])])),
+    env: request.env,
+  });
+}
+
+// A name matches as the changed paths decode it, and stays the bytes git wrote. An ignored name
+// stays in the diff when a counted name sits inside it or around it, such as a file that became a
+// folder: restoring one would remove the other from the index.
+function collectIgnoredNames(output: Buffer, ignore: readonly string[]): readonly Buffer[] {
+  const names = collectNames(output);
+  const ignored = names.filter((name) => isGlobMatch(name.toString('utf8'), ignore));
+  const counted = names.filter((name) => !ignored.includes(name));
+
+  return ignored.filter(
+    (name) => !counted.some((other) => isInsidePath(other, name) || isInsidePath(name, other)),
+  );
+}
+
+function collectNames(output: Buffer): readonly Buffer[] {
+  const names: Buffer[] = [];
+  let start = 0;
+
+  while (start < output.length) {
+    const end = output.indexOf(0, start);
+    const stop = end === -1 ? output.length : end;
+
+    if (stop > start) {
+      names.push(output.subarray(start, stop));
+    }
+
+    start = stop + 1;
+  }
+
+  return names;
+}
+
+function isInsidePath(path: Buffer, folder: Buffer): boolean {
+  return (
+    path.length > folder.length &&
+    path[folder.length] === 0x2f &&
+    path.subarray(0, folder.length).equals(folder)
+  );
+}

package/src/render-report-markdown.ts

@@ -16,7 +16,7 @@ export function renderReportMarkdown(report: Report): string {
   const lines = [
     '## wringer report',
     '',
-    `Fingerprint \`${report.fingerprint}\` against \`${report.base}\`: ${report.complete ? 'every changed feature is verified' : 'some changed features need a verdict'}.`,
+    `Fingerprint \`${report.fingerprint}\` against \`${report.base}\`: ${pickSummary(report)}.`,
     '',
     '| Feature | Status | Evidence |',
     '| --- | --- | --- |',
@@ -25,6 +25,7 @@ export function renderReportMarkdown(report: Report): string {
         `| ${feature.name} | ${statusLabels[feature.status]} | ${formatEvidence(feature.verdict?.evidence ?? [])} |`,
     ),
     '',
+    ...formatUnmapped(report.unmapped),
     reportBlockOpen,
     JSON.stringify(report).replaceAll('>', String.raw`\u003e`),
     reportBlockClose,
@@ -34,6 +35,16 @@ export function renderReportMarkdown(report: Report): string {
   return lines.join('\n');
 }
 
+function pickSummary(report: Report): string {
+  if (report.complete) {
+    return 'every changed feature is verified';
+  }
+
+  return report.unmapped.length > 0
+    ? 'some changed paths map to no feature'
+    : 'some changed features need a verdict';
+}
+
 function formatEvidence(
   evidence: readonly {
     readonly kind: string;
@@ -51,3 +62,16 @@ function formatEvidence(
     )
     .join(', ');
 }
+
+function formatUnmapped(unmapped: readonly string[]): readonly string[] {
+  if (unmapped.length === 0) {
+    return [];
+  }
+
+  return [
+    'Changed paths that no feature maps. Map each to a feature, or add it to the ignore list:',
+    '',
+    ...unmapped.map((path) => `- \`${path}\``),
+    '',
+  ];
+}

package/src/report-schema.ts

@@ -32,6 +32,10 @@ export const reportSchema = z.strictObject({
   fingerprint: z.string(),
   complete: z.boolean(),
   features: z.array(featureReportSchema),
+
+  // The changed paths that no feature maps and the repo does not ignore. A report written before
+  // the field existed reads as having none; `gate` works the paths out again either way.
+  unmapped: z.array(z.string()).default([]),
 });
 
 export type Report = z.infer<typeof reportSchema>;

package/src/types.ts

@@ -427,6 +427,10 @@ export interface Wringer {
   readonly commands: ReadonlyMap<string, RegisteredCommand>;
   readonly checks: readonly RunnableRepoCheck[];
   readonly features: readonly FeatureDefinition[];
+
+  // Globs of paths with no runtime effect, such as docs: a change to one maps to no feature and
+  // leaves the fingerprint alone.
+  readonly ignore: readonly string[];
   readonly hooks: Partial<HookHandlers>;
 }