@zxyycom/vibe-check 0.0.2 → 0.0.3

package/src/project-definition/project-definition.ts

@@ -3,12 +3,11 @@ import type { MeaninglessCheckWarning } from "./check-tree/authoring.ts";
 import type { CheckDescriptor } from "../check/descriptor.ts";
 import type {
   Check,
-  CheckExecution,
-  CheckFlagEnablement,
-  CheckPreflight,
+  CheckPreparation,
   CheckResourceClaims,
-  CheckVisibility
+  CheckFlagEnablement
 } from "../check/check.ts";
+import type { HandoffProviderIdentity } from "../check/handoff-provider-identity.ts";
 import { DEFAULT_PROJECT_OUTPUTS, resolveProgressRenderingOutput } from "./output-defaults.ts";
 import type {
   ProgressRenderingOutput,
@@ -19,6 +18,11 @@ import {
   EMPTY_RESOURCE_UNIT_MAPPING,
   snapshotResourceUnitMapping
 } from "./resource-unit-mapping.ts";
+import {
+  parseProjectChangesConfiguration,
+  type NormalizedProjectChangesConfiguration,
+  type ProjectChangesConfiguration
+} from "./project-changes.ts";
 export { createDeclarativeFingerprint } from "./declarative-snapshot.ts";
 
 /** 一次 Project Run 的明确输出配置。 */
@@ -92,7 +96,7 @@ export type {
   SchedulerMeasurementAdmission,
   SchedulerMeasurementContext,
   SchedulerMeasurementEffect,
-  SchedulerMeasurementHook,
+  SchedulerTerminalEffect,
   SchedulerMeasurementIntervalContribution,
   SchedulerMeasurementPeakCounts,
   SchedulerMeasurementTiming,
@@ -103,10 +107,7 @@ export type {
 } from "./scheduler-policy.ts";
 import type {
   AdmissionPolicy,
-  CustomAdmissionStrategy,
-  CustomAdmissionPreparationContext,
   DeclarativeSchedulerPolicy,
-  PreparedCustomAdmissionStrategy,
   SchedulerPolicy
 } from "./scheduler-policy.ts";
 
@@ -119,12 +120,15 @@ import type {
 export interface ProjectDefinition {
   readonly apiVersion: "1";
   readonly checks: readonly Check[];
+  /** 可选的静态 Git comparison 与本次 Run 的 change-flag regions。 */
+  readonly changes?: ProjectChangesConfiguration;
   readonly outputs: ProjectOutputs;
   readonly scheduler: SchedulerPolicy;
 }
 type ProjectDefinitionInput = Readonly<{
   apiVersion?: "1";
   checks?: readonly Check[];
+  changes?: ProjectChangesConfiguration;
   outputs?: Partial<{
     machinePublication: Partial<ProjectOutputs["machinePublication"]>;
     progressRendering: Partial<ProjectOutputs["progressRendering"]>;
@@ -150,26 +154,30 @@ export interface NormalizedCheckDeclaration {
   readonly admissionPriority: number;
   readonly definition: CheckDescriptor;
   readonly dependsOn: readonly string[];
+  /** Definition 已验证、snapshot 并冻结的单一 recursive flag-condition control。 */
   readonly enabledByFlags?: CheckFlagEnablement;
   readonly maxParallel: number;
   readonly mutex: readonly string[];
   readonly observes: readonly string[];
   readonly options: object;
   readonly resourceClaims: CheckResourceClaims;
-  readonly visibility: CheckVisibility;
+  readonly omitQuietPassedRow: boolean;
 }
 export interface NormalizedCheck extends NormalizedCheckDeclaration {
-  readonly execution: CheckExecution;
-  readonly preflight?: CheckPreflight;
+  readonly execute: NonNullable<Check["execute"]>;
+  readonly handoff?: HandoffProviderIdentity;
+  readonly prepare?: CheckPreparation;
 }
 export interface DeclarativeProjectSnapshot {
   readonly apiVersion: "1";
   readonly checks: readonly NormalizedCheckDeclaration[];
+  readonly changes?: NormalizedProjectChangesConfiguration;
   readonly outputs: DeclarativeProjectOutputs;
   readonly scheduler: DeclarativeSchedulerPolicy;
 }
 export interface NormalizedProjectDefinition {
   readonly checks: readonly NormalizedCheck[];
+  readonly changes?: NormalizedProjectChangesConfiguration;
   readonly declarative: DeclarativeProjectSnapshot;
   readonly definitionWarnings: readonly DefinitionWarning[];
   /** Runtime scheduler policy；custom callback 保留在此处。 */
@@ -178,54 +186,6 @@ export interface NormalizedProjectDefinition {
 const STATIC_ADMISSION_POLICY: AdmissionPolicy = Object.freeze({
   kind: "static"
 });
-type ExactAdmissionPolicy<T extends AdmissionPolicy> =
-  T extends Readonly<{ readonly kind: "static" }>
-    ? T & Record<Exclude<keyof T, "kind">, never>
-    : T extends Readonly<{ readonly kind: "custom" }>
-      ? T &
-          Record<Exclude<keyof T, "kind" | "strategy">, never> &
-          Readonly<{
-            readonly strategy: ExactCustomAdmissionStrategy<T["strategy"]>;
-          }>
-      : never;
-
-type ExactCustomAdmissionStrategy<T extends CustomAdmissionStrategy> =
-  T extends Readonly<{ readonly kind: "simple" }>
-    ? T & Record<Exclude<keyof T, "kind" | "decide">, never>
-    : T extends Readonly<{ readonly kind: "prepared" }>
-      ? T &
-          Record<Exclude<keyof T, "kind" | "prepare">, never> &
-          Readonly<{ readonly prepare: ExactCustomPreparation<T["prepare"]> }>
-      : never;
-
-type ExactCustomPreparation<T> = T extends (
-  this: void,
-  context: CustomAdmissionPreparationContext
-) => infer Result
-  ? (this: void, context: CustomAdmissionPreparationContext) => ExactCustomPreparationResult<Result>
-  : never;
-
-type ExactCustomPreparationResult<T> =
-  T extends Promise<unknown>
-    ? Promise<ExactPreparedCustomAdmissionStrategy<Awaited<T>>>
-    : ExactPreparedCustomAdmissionStrategy<T>;
-
-type ExactPreparedCustomAdmissionStrategy<T> = T extends PreparedCustomAdmissionStrategy
-  ? T & Record<Exclude<keyof T, "decide" | "complete">, never>
-  : never;
-
-/**
- * 保留 closed admission policy literal 的 TypeScript inference，不创建额外运行语义。
- *
- * @remarks inline policy 与此 helper 的结果完全等价。custom simple `decide` 同步运行；prepared
- * strategy 为每个 graph-ready Run 解析独立 closure，调用方负责其 trusted host callback 的可重入性。
- */
-export function defineAdmissionPolicy<const T extends AdmissionPolicy>(
-  policy: ExactAdmissionPolicy<T>
-): T {
-  return policy;
-}
-
 /** 使用 Product 默认输出创建普通 Project Definition。 */
 export function defineConfig<const T extends ProjectDefinitionInput>(
   value: T & Record<Exclude<keyof T, keyof ProjectDefinitionInput>, never>
@@ -233,6 +193,7 @@ export function defineConfig<const T extends ProjectDefinitionInput>(
   return {
     apiVersion: value.apiVersion ?? "1",
     checks: value.checks ?? [],
+    ...(value.changes === undefined ? {} : { changes: value.changes }),
     outputs: {
       machinePublication: {
         directory:
@@ -255,7 +216,7 @@ export function defineConfig<const T extends ProjectDefinitionInput>(
     scheduler: {
       admissionPolicy: value.scheduler?.admissionPolicy ?? STATIC_ADMISSION_POLICY,
       maxParallel: value.scheduler?.maxParallel ?? 4,
-      measurementHooks: value.scheduler?.measurementHooks ?? [],
+      terminalEffects: value.scheduler?.terminalEffects ?? [],
       resourceCapacities: value.scheduler?.resourceCapacities ?? EMPTY_RESOURCE_UNIT_MAPPING
     }
   };
@@ -272,12 +233,23 @@ export function normalizeProjectDefinition(
   if (tree === undefined)
     throw new TypeError("Project Definition Check tree failed closed normalization");
   const checks = Object.freeze(tree.leaves.map(normalizeCheck));
+  const changes =
+    definition.changes === undefined
+      ? undefined
+      : parseProjectChangesConfiguration(definition.changes);
+  if (definition.changes !== undefined && changes === undefined) {
+    throw new TypeError("Project Definition changes failed closed normalization");
+  }
+  const { changes: _authoredChanges, ...baseDefinition } = definition;
+  const normalizedDefinition = Object.freeze({
+    ...baseDefinition,
+    ...(changes === undefined ? {} : { changes }),
+    scheduler
+  });
   return Object.freeze({
     checks,
-    declarative: createDeclarativeProjectSnapshot(
-      Object.freeze({ ...definition, scheduler }),
-      checks
-    ),
+    ...(changes === undefined ? {} : { changes }),
+    declarative: createDeclarativeProjectSnapshot(normalizedDefinition, checks),
     definitionWarnings: tree.warnings,
     scheduler
   });
@@ -288,14 +260,15 @@ function normalizeCheck(leaf: ResolvedCheckTreeLeaf): NormalizedCheck {
     definition: leaf.definition,
     dependsOn: leaf.dependsOn,
     ...(leaf.enabledByFlags === undefined ? {} : { enabledByFlags: leaf.enabledByFlags }),
-    execution: leaf.execution,
+    execute: leaf.execute,
+    ...(leaf.handoff === undefined ? {} : { handoff: leaf.handoff }),
     maxParallel: leaf.maxParallel,
     mutex: leaf.mutex,
     observes: leaf.observes,
     options: leaf.options,
-    ...(leaf.preflight === undefined ? {} : { preflight: leaf.preflight }),
+    ...(leaf.prepare === undefined ? {} : { prepare: leaf.prepare }),
     resourceClaims: leaf.resourceClaims,
-    visibility: leaf.visibility
+    omitQuietPassedRow: leaf.omitQuietPassedRow
   });
 }
 function normalizeSchedulerPolicy(policy: SchedulerPolicy): SchedulerPolicy {
@@ -315,7 +288,7 @@ function normalizeSchedulerPolicy(policy: SchedulerPolicy): SchedulerPolicy {
   return Object.freeze({
     admissionPolicy,
     maxParallel: policy.maxParallel,
-    measurementHooks: Object.freeze([...policy.measurementHooks]),
+    terminalEffects: Object.freeze([...policy.terminalEffects]),
     resourceCapacities
   });
 }

package/src/project-definition/scheduler-policy.ts

@@ -202,7 +202,10 @@ export interface PreparedCustomAdmissionStrategy {
   /** Scheduler 每轮同步调用；不得返回 Promise 或 thenable。 */
   readonly decide: (this: void, context: AdmissionPolicyContext) => AdmissionProposal;
   /** Scheduler 的 generic Hooks 完成后，才以 sealed terminal context 调用一次。 */
-  readonly complete?: (this: void, context: SchedulerMeasurementContext) => void | Promise<void>;
+  readonly terminalEffect?: (
+    this: void,
+    context: SchedulerMeasurementContext
+  ) => void | Promise<void>;
 }
 
 /** custom 的 closed authoring grammar。 */
@@ -525,7 +528,7 @@ export interface SchedulerMeasurementContext {
 }
 
 /** 一次 terminal Scheduler measurement 的 caller-owned sync/async consumer。 */
-export type SchedulerMeasurementHook =
+export type SchedulerTerminalEffect =
   | ((this: void, context: SchedulerMeasurementContext) => void)
   | ((this: void, context: SchedulerMeasurementContext) => Promise<void>);
 
@@ -536,7 +539,7 @@ export interface SchedulerPolicy {
   /** 同时 running 的 root Check 上限。 */
   readonly maxParallel: number;
   /** terminal measurement 的 caller-owned consumers，按配置顺序调用。 */
-  readonly measurementHooks: readonly SchedulerMeasurementHook[];
+  readonly terminalEffects: readonly SchedulerTerminalEffect[];
   /** 本次 Definition 中可由 Check 原子占用的 named resource 总 units。 */
   readonly resourceCapacities: Readonly<Record<string, number>>;
 }

package/src/project-run/admission-strategy-provider/custom-strategy-preparation.ts

@@ -35,18 +35,18 @@ async function prepareCustomStrategy(
     throw new AdmissionStrategyPreparationFailure();
   }
   const record = snapshotClosedPolicyRecord(prepared, {
-    optional: ["complete"],
+    optional: ["terminalEffect"],
     required: ["decide"]
   });
   if (record === undefined || !isPreparedCustomDecision(record.decide)) {
     throw new AdmissionStrategyPreparationFailure();
   }
-  if (record.complete !== undefined && !isPreparedCustomCompletion(record.complete)) {
+  if (record.terminalEffect !== undefined && !isPreparedCustomCompletion(record.terminalEffect)) {
     throw new AdmissionStrategyPreparationFailure();
   }
   return Object.freeze({
     decide: record.decide,
-    ...(record.complete === undefined ? {} : { complete: record.complete })
+    ...(record.terminalEffect === undefined ? {} : { terminalEffect: record.terminalEffect })
   });
 }
 
@@ -58,21 +58,24 @@ function isPreparedCustomDecision(
 
 function isPreparedCustomCompletion(
   value: unknown
-): value is NonNullable<PreparedCustomAdmissionStrategy["complete"]> {
+): value is NonNullable<PreparedCustomAdmissionStrategy["terminalEffect"]> {
   return typeof value === "function";
 }
 
 function preparedCustomAdmissionStrategy(
-  strategy: Pick<PreparedCustomAdmissionStrategy, "decide" | "complete">
+  strategy: Pick<PreparedCustomAdmissionStrategy, "decide" | "terminalEffect">
 ): PreparedAdmissionStrategy {
   const completion =
-    strategy.complete === undefined
+    strategy.terminalEffect === undefined
       ? Object.freeze({ kind: "none" as const })
-      : Object.freeze({ kind: "measurement-hook" as const, complete: strategy.complete });
+      : Object.freeze({
+          kind: "terminal-effect" as const,
+          terminalEffect: strategy.terminalEffect
+        });
   return Object.freeze({
     admissionPolicy: admissionSelectionPolicyFor(strategy.decide),
     completion,
-    requiresTerminalMeasurement: completion.kind === "measurement-hook"
+    requiresTerminalMeasurement: completion.kind === "terminal-effect"
   });
 }
 

package/src/project-run/admission-strategy-provider/prepared-admission-strategy.ts

@@ -12,8 +12,8 @@ export type PreparedAdmissionStrategyCompletion =
       readonly complete: (context: InternalAdmissionStrategyCompleteContext) => Promise<void>;
     }>
   | Readonly<{
-      readonly kind: "measurement-hook";
-      readonly complete: (context: SchedulerMeasurementContext) => void | Promise<void>;
+      readonly kind: "terminal-effect";
+      readonly terminalEffect: (context: SchedulerMeasurementContext) => void | Promise<void>;
     }>;
 
 /** The invocation-scoped handoff from an admission provider to Scheduler and terminal delivery. */

package/src/project-run/aggregation.ts

@@ -1,95 +1,72 @@
-import type {
-  RunControlDiagnostic,
-  RunControlValidationResult
-} from "./controls/validation-result.ts";
-import type { CheckAggregate, CheckAggregation } from "./controls/contract.ts";
 import type { CoreCheck, CoreSnapshot } from "../check-settlement/facts.ts";
+import type { CheckAggregate, CheckAggregation } from "./controls/contract.ts";
 
-type AggregateStatus = Exclude<CheckAggregate, "not-applicable">;
+/** Identifies a callback failure so the invocation boundary can close outputs before rethrowing it. */
+export class CheckAggregationFailure extends Error {
+  readonly originalError: Error;
 
-/** Validates that aggregation selects only normalized executable Check IDs. */
-export function validateCheckAggregationSelection(
-  aggregation: CheckAggregation | undefined,
-  checkIds: readonly string[]
-): RunControlValidationResult<CheckAggregation | undefined> {
-  if (aggregation === undefined) return Object.freeze({ ok: true, value: undefined });
-  if (aggregation.checks === "all" || aggregation.checks === "effective") {
-    return Object.freeze({ ok: true, value: aggregation });
+  public constructor(originalError: Error) {
+    super("Check aggregation failed", { cause: originalError });
+    this.originalError = originalError;
   }
-  const knownCheckIds = new Set(checkIds);
-  const selectedCheckIds = new Set<string>();
-  for (const checkId of aggregation.checks) {
-    if (!knownCheckIds.has(checkId) || selectedCheckIds.has(checkId)) {
-      return invalidControls("controls.checkAggregation.checks");
-    }
-    selectedCheckIds.add(checkId);
-  }
-  return Object.freeze({ ok: true, value: aggregation });
 }
 
-/** Derives one explicit consumer-selected aggregate from settled Check statuses only. */
-export function aggregateCheckOutcomes(
+/** Builds the canonical ordered, read-only effective Check list and derives its invocation aggregate. */
+export function aggregateEffectiveChecks(
   snapshot: CoreSnapshot,
-  aggregation: CheckAggregation,
-  effectiveCheckIds: readonly string[]
+  effectiveCheckIds: readonly string[],
+  aggregation: CheckAggregation | undefined
 ): CheckAggregate {
-  const statuses = selectedChecks(snapshot, aggregation.checks, effectiveCheckIds).map((check) =>
-    aggregateStatus(check, aggregation)
-  );
-  if (statuses.includes("unavailable")) return "unavailable";
-  return aggregateSelectedStatuses(
-    statuses.filter(
-      (status): status is Exclude<AggregateStatus, "unavailable"> =>
-        status !== null && status !== "unavailable"
-    ),
-    aggregation
-  );
+  const checks = effectiveChecks(snapshot, effectiveCheckIds);
+  return aggregation === undefined
+    ? strictAggregate(checks)
+    : invokeAggregation(aggregation, checks);
 }
 
-function selectedChecks(
+function effectiveChecks(
   snapshot: CoreSnapshot,
-  selection: CheckAggregation["checks"],
   effectiveCheckIds: readonly string[]
 ): readonly CoreCheck[] {
-  if (selection === "all") return snapshot.checks;
-  const selectedCheckIds = selection === "effective" ? effectiveCheckIds : selection;
-  return selectedCheckIds.map((checkId) => {
-    const check = snapshot.checks.find((candidate) => candidate.checkId === checkId);
-    if (check === undefined) throw new TypeError("Aggregation selection was not validated");
-    return check;
-  });
+  const effectiveCheckIdSet = new Set(effectiveCheckIds);
+  return Object.freeze(snapshot.checks.filter((check) => effectiveCheckIdSet.has(check.checkId)));
 }
 
-function aggregateStatus(check: CoreCheck, aggregation: CheckAggregation): AggregateStatus | null {
-  switch (check.outcome.status) {
-    case "passed":
-    case "failed":
-      return check.outcome.status;
-    case "unavailable": {
-      if (aggregation.unavailable === "propagate") return "unavailable";
-      return aggregation.unavailable === "fail" ? "failed" : null;
-    }
-    case "not-applicable": {
-      if (aggregation.notApplicable === "pass") return "passed";
-      return aggregation.notApplicable === "fail" ? "failed" : null;
-    }
-  }
+function strictAggregate(checks: readonly CoreCheck[]): CheckAggregate {
+  return checks.length > 0 && checks.every((check) => check.outcome.status === "passed")
+    ? "passed"
+    : "failed";
 }
 
-function aggregateSelectedStatuses(
-  statuses: readonly Exclude<AggregateStatus, "unavailable">[],
-  aggregation: CheckAggregation
+function invokeAggregation(
+  aggregation: CheckAggregation,
+  checks: readonly CoreCheck[]
 ): CheckAggregate {
-  if (statuses.length === 0) return aggregation.empty;
-  if (aggregation.mode === "all") return statuses.includes("failed") ? "failed" : "passed";
-  return statuses.includes("passed") ? "passed" : "failed";
+  let aggregate: unknown;
+  try {
+    aggregate = aggregation(checks);
+  } catch (error) {
+    throw new CheckAggregationFailure(errorFromThrownValue(error));
+  }
+  if (isCheckAggregate(aggregate)) return aggregate;
+  discardPromiseRejection(aggregate);
+  throw new CheckAggregationFailure(
+    new TypeError("Check aggregation must synchronously return a CheckAggregate")
+  );
+}
+
+function isCheckAggregate(value: unknown): value is CheckAggregate {
+  return (
+    value === "passed" ||
+    value === "failed" ||
+    value === "not-applicable" ||
+    value === "unavailable"
+  );
+}
+
+function discardPromiseRejection(value: unknown): void {
+  if (value instanceof Promise) void value.catch(() => undefined);
 }
 
-function invalidControls(path: string): RunControlValidationResult<never> {
-  const error: RunControlDiagnostic = Object.freeze({
-    kind: "invalid-run-controls",
-    path,
-    reason: "invalid-value"
-  });
-  return Object.freeze({ ok: false, error });
+function errorFromThrownValue(value: unknown): Error {
+  return value instanceof Error ? value : new Error("Check aggregation threw a non-Error value");
 }

package/src/project-run/changes/git.ts

@@ -0,0 +1,206 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+import { execaSync } from "execa";
+
+import { matchesAnyConfigGlob } from "../../data-boundary/config-glob.ts";
+import { isNormalizedProjectRelativePath } from "../../data-boundary/project-path.ts";
+import type { ProjectChanges } from "../../check/check.ts";
+import type { NormalizedProjectChangesConfiguration } from "../../project-definition/project-changes.ts";
+
+export const CHANGE_FLAG_PREFIX = "vibe-check:change:";
+export const GIT_CHANGES_UNAVAILABLE_CODE = "git-changes-unavailable";
+
+export type PreparedProjectChanges = Readonly<{
+  readonly effectiveFlags: readonly string[];
+  readonly projectChanges: ProjectChanges;
+}>;
+
+/** Prepares one configured Git change snapshot before Run flag selection. */
+export function prepareProjectChanges(
+  input: Readonly<{
+    readonly callerFlags: readonly string[];
+    readonly changes: NormalizedProjectChangesConfiguration;
+    readonly projectRoot: string;
+  }>
+): PreparedProjectChanges {
+  const declaredFlags = declaredChangeFlags(input.changes);
+  try {
+    const paths = collectGitChangedPaths(input.projectRoot, input.changes.source.compareWith);
+    const projectChanges = matchedProjectChanges(paths, input.changes);
+    return Object.freeze({
+      effectiveFlags: combineFlags(
+        input.callerFlags,
+        projectChanges.files.flatMap(({ flags }) => flags)
+      ),
+      projectChanges
+    });
+  } catch {
+    return Object.freeze({
+      effectiveFlags: combineFlags(input.callerFlags, declaredFlags),
+      projectChanges: Object.freeze({
+        ok: false,
+        reason: Object.freeze({ code: GIT_CHANGES_UNAVAILABLE_CODE })
+      })
+    });
+  }
+}
+
+function declaredChangeFlags(changes: NormalizedProjectChangesConfiguration): readonly string[] {
+  return Object.freeze(
+    Object.keys(changes.flags)
+      .sort(compareText)
+      .map((flagId) => `${CHANGE_FLAG_PREFIX}${flagId}`)
+  );
+}
+
+function collectGitChangedPaths(projectRoot: string, compareWith: string): readonly string[] {
+  const root = resolve(projectRoot);
+  const repositoryRoot = gitText(root, ["rev-parse", "--show-toplevel"]);
+  if (!isProjectRootInRepository(root, resolve(repositoryRoot))) {
+    throw new Error("project root is outside the Git repository");
+  }
+
+  const committed = gitNameStatus(root, [
+    "diff",
+    "--relative",
+    "--name-status",
+    "-z",
+    "--find-renames",
+    `${compareWith}...HEAD`
+  ]);
+  const staged = gitNameStatus(root, [
+    "diff",
+    "--cached",
+    "--relative",
+    "--name-status",
+    "-z",
+    "--find-renames"
+  ]);
+  const unstaged = gitNameStatus(root, [
+    "diff",
+    "--relative",
+    "--name-status",
+    "-z",
+    "--find-renames"
+  ]);
+  const untracked = gitNulPaths(root, [
+    "ls-files",
+    "--others",
+    "--exclude-standard",
+    "-z",
+    "--",
+    "."
+  ]);
+  return Object.freeze(
+    [
+      ...new Set([...committed, ...staged, ...unstaged, ...untracked].map(normalizedChangedPath))
+    ].sort(compareText)
+  );
+}
+
+function isProjectRootInRepository(projectRoot: string, repositoryRoot: string): boolean {
+  const fromRepository = relative(repositoryRoot, projectRoot);
+  return (
+    !isAbsolute(fromRepository) && fromRepository !== ".." && !fromRepository.startsWith(`..${sep}`)
+  );
+}
+
+function gitText(cwd: string, args: readonly string[]): string {
+  const text = gitOutput(cwd, args).trim();
+  if (text.length === 0) throw new Error("Git command returned no text");
+  return text;
+}
+
+function gitOutput(cwd: string, args: readonly string[]): string {
+  const result = execaSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    reject: false,
+    stripFinalNewline: false,
+    windowsHide: true
+  });
+  if (result.failed || result.exitCode !== 0) throw new Error("Git command failed");
+  if (typeof result.stdout !== "string") throw new Error("Git command returned non-text output");
+  return result.stdout;
+}
+
+function gitNameStatus(cwd: string, args: readonly string[]): readonly string[] {
+  return parseGitNameStatus(gitOutput(cwd, args));
+}
+
+function gitNulPaths(cwd: string, args: readonly string[]): readonly string[] {
+  return gitOutput(cwd, args)
+    .split("\0")
+    .filter((path) => path.length > 0);
+}
+
+/** Parses Git's `--name-status -z` protocol without line or tab splitting. */
+function parseGitNameStatus(stdout: string): readonly string[] {
+  const tokens = stdout.split("\0");
+  if (tokens.at(-1) === "") tokens.pop();
+  const paths: string[] = [];
+  for (let index = 0; index < tokens.length;) {
+    const entry = parseGitNameStatusEntry(tokens, index);
+    paths.push(...entry.paths);
+    index = entry.nextIndex;
+  }
+  return Object.freeze(paths);
+}
+
+function parseGitNameStatusEntry(
+  tokens: readonly string[],
+  statusIndex: number
+): Readonly<{ readonly nextIndex: number; readonly paths: readonly string[] }> {
+  const status = tokens[statusIndex];
+  if (status === undefined || !isNameStatus(status))
+    throw new Error("invalid Git name-status output");
+  const pathCount = nameStatusPathCount(status);
+  const paths = tokens.slice(statusIndex + 1, statusIndex + 1 + pathCount);
+  if (paths.length !== pathCount || paths.some((path) => path.length === 0))
+    throw new Error("missing Git changed path");
+  return Object.freeze({ nextIndex: statusIndex + 1 + pathCount, paths: Object.freeze(paths) });
+}
+
+function nameStatusPathCount(status: string): 1 | 2 {
+  return status.startsWith("R") || status.startsWith("C") ? 2 : 1;
+}
+
+function isNameStatus(value: string): boolean {
+  return /^(?:[ACDMRTUXB][0-9]*|[RC][0-9]+)$/u.test(value);
+}
+
+function normalizedChangedPath(path: string): string {
+  if (!isNormalizedProjectRelativePath(path)) throw new Error("invalid Git project-relative path");
+  return path;
+}
+
+function matchedProjectChanges(
+  paths: readonly string[],
+  changes: NormalizedProjectChangesConfiguration
+): Extract<ProjectChanges, { readonly ok: true }> {
+  const regions = Object.entries(changes.flags).sort(([left], [right]) => compareText(left, right));
+  const files = paths.flatMap((path) => {
+    const flags = regions.flatMap(([flagId, region]) =>
+      matchesRegion(path, region) ? [`${CHANGE_FLAG_PREFIX}${flagId}`] : []
+    );
+    return flags.length === 0 ? [] : [Object.freeze({ flags: Object.freeze(flags), path })];
+  });
+  return Object.freeze({ ok: true, files: Object.freeze(files) });
+}
+
+function matchesRegion(
+  path: string,
+  region: NormalizedProjectChangesConfiguration["flags"][string]
+): boolean {
+  return matchesAnyConfigGlob(path, region.include) && !matchesAnyConfigGlob(path, region.exclude);
+}
+
+function combineFlags(...sets: readonly (readonly string[])[]): readonly string[] {
+  return Object.freeze([...new Set(sets.flat())].sort(compareText));
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}