@goodbones/campaigns 0.1.0

package/src/host/diff.ts

@@ -0,0 +1,203 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import * as path from "node:path";
+
+// What the nudge is scoped to: the files a diff touches, and where in each.
+// Read from git — the working tree against `HEAD` on a developer's machine,
+// or against `--base <ref>` in CI — with `-U0`, so a hunk is exactly the
+// lines that changed and "nearest your change" means something.
+
+export type Hunk = {
+  // One-based, inclusive, in the new file; a pure deletion is a zero-length
+  // hunk at the line after it.
+  readonly start: number;
+  readonly end: number;
+};
+
+export type Diff = {
+  // The ref the diff was taken against; `null` for the working tree
+  // against HEAD.
+  readonly base: string | null;
+  // Repo-relative paths, forward slashes, with the hunks in each. A file
+  // added whole has one hunk covering it; a deleted file is not here.
+  readonly touched: ReadonlyMap<string, ReadonlyArray<Hunk>>;
+  readonly deleted: ReadonlyArray<string>;
+  readonly added: ReadonlyArray<string>;
+};
+
+const git = (repoRoot: string, args: ReadonlyArray<string>): string =>
+  execFileSync("git", args, {
+    cwd: repoRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    maxBuffer: 256 * 1024 * 1024,
+  });
+
+const HUNK = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
+
+const HEADER = /^diff --git a\/(.+?) b\/(.+)$/;
+
+// Parses `git diff -U0`: one entry per file header, one hunk per `@@`. An
+// empty file added or deleted has a header and a mode line and nothing
+// else, so the mode lines are read too.
+export const parseDiff = (
+  text: string,
+): { touched: Map<string, Array<Hunk>>; deleted: Array<string>; added: Array<string> } => {
+  const touched = new Map<string, Array<Hunk>>();
+  const deleted = new Set<string>();
+  const added = new Set<string>();
+  let current: string | null = null;
+  for (const line of text.split("\n")) {
+    const header = HEADER.exec(line);
+    if (header !== null) {
+      current = header[2] ?? null;
+      continue;
+    }
+    if (current === null) continue;
+    if (line.startsWith("deleted file mode")) {
+      deleted.add(current);
+      touched.delete(current);
+      continue;
+    }
+    if (line.startsWith("new file mode")) {
+      added.add(current);
+      if (!touched.has(current)) touched.set(current, []);
+      continue;
+    }
+    if (line.startsWith("+++ ")) {
+      if (line.slice(4) === "/dev/null") {
+        deleted.add(current);
+        touched.delete(current);
+      } else if (!deleted.has(current) && !touched.has(current)) {
+        touched.set(current, []);
+      }
+      continue;
+    }
+    const hunk = HUNK.exec(line);
+    if (hunk !== null && !deleted.has(current)) {
+      const start = Number(hunk[3]);
+      const count = hunk[4] === undefined ? 1 : Number(hunk[4]);
+      const hunks = touched.get(current) ?? [];
+      hunks.push({ start, end: count === 0 ? start : start + count - 1 });
+      touched.set(current, hunks);
+    }
+  }
+  // A file added whole with no hunk of its own (empty) covers itself.
+  for (const file of added) {
+    if ((touched.get(file) ?? []).length === 0) touched.set(file, [{ start: 1, end: 1 }]);
+  }
+  return { touched, deleted: [...deleted].sort(), added: [...added].sort() };
+};
+
+// The diff of the working tree against `base` (or HEAD), untracked files
+// included as added whole.
+export const readDiff = (repoRoot: string, base: string | null): Diff => {
+  const against = base ?? "HEAD";
+  const parsed = parseDiff(git(repoRoot, ["diff", "-U0", "--no-color", "--no-ext-diff", against]));
+  const untracked = git(repoRoot, ["ls-files", "--others", "--exclude-standard"])
+    .split("\n")
+    .map((one) => one.trim())
+    .filter((one) => one !== "");
+  for (const file of untracked) {
+    if (parsed.touched.has(file)) continue;
+    parsed.touched.set(file, [{ start: 1, end: Number.MAX_SAFE_INTEGER }]);
+    parsed.added.push(file);
+  }
+  return {
+    base,
+    touched: parsed.touched,
+    deleted: parsed.deleted,
+    added: [...new Set(parsed.added)].sort(),
+  };
+};
+
+// The distance, in lines, from a range to the nearest hunk of a file: zero
+// when they overlap. `Infinity` for a file with no hunk.
+export const distanceToHunks = (hunks: ReadonlyArray<Hunk>, start: number, end: number): number => {
+  let nearest = Number.POSITIVE_INFINITY;
+  for (const hunk of hunks) {
+    const distance = hunk.end < start ? start - hunk.end : end < hunk.start ? hunk.start - end : 0;
+    if (distance < nearest) nearest = distance;
+  }
+  return nearest;
+};
+
+// A file's text as it was at `ref`, or `null` when it did not exist there.
+export const textAt = (repoRoot: string, ref: string, file: string): string | null => {
+  try {
+    return git(repoRoot, ["show", `${ref}:${file}`]);
+  } catch {
+    return null;
+  }
+};
+
+export const commitOf = (repoRoot: string, ref: string): string =>
+  git(repoRoot, ["rev-parse", ref]).trim();
+
+// The tree at `ref`, materialized in a temporary directory with the
+// repository's `node_modules` linked beside it, so the packs resolve as
+// they would in the checkout. The exact mode of the nudge evaluates it
+// whole; the caller disposes of it.
+export const materializeTree = (
+  repoRoot: string,
+  ref: string,
+): { readonly root: string; readonly dispose: () => void } => {
+  const root = realpathSync(mkdtempSync(path.join(tmpdir(), "goodbones-base-")));
+  execFileSync(
+    "sh",
+    ["-c", `git archive ${JSON.stringify(ref)} | tar -x -C ${JSON.stringify(root)}`],
+    {
+      cwd: repoRoot,
+      stdio: ["ignore", "ignore", "ignore"],
+    },
+  );
+  const modules = path.join(repoRoot, "node_modules");
+  if (existsSync(modules) && !existsSync(path.join(root, "node_modules"))) {
+    symlinkSync(modules, path.join(root, "node_modules"), "dir");
+  }
+  return {
+    root,
+    dispose: () => {
+      rmSync(root, { recursive: true, force: true });
+    },
+  };
+};
+
+// The commits that touched any of these paths, oldest first.
+export type Commit = {
+  readonly sha: string;
+  readonly at: string;
+  readonly subject: string;
+  readonly files: ReadonlyArray<string>;
+};
+
+export const commitsTouching = (
+  repoRoot: string,
+  paths: ReadonlyArray<string>,
+  since: string | null,
+): ReadonlyArray<Commit> => {
+  const range = since === null ? [] : [`${since}..HEAD`];
+  const log = git(repoRoot, [
+    "log",
+    "--reverse",
+    "--format=%x00%H%x09%aI%x09%s",
+    "--name-only",
+    ...range,
+    "--",
+    ...paths,
+  ]);
+  const commits: Array<Commit> = [];
+  for (const block of log.split("\u0000")) {
+    if (block.trim() === "") continue;
+    const [head = "", ...rest] = block.split("\n");
+    const [sha = "", at = "", ...subject] = head.split("\t");
+    commits.push({
+      sha,
+      at,
+      subject: subject.join("\t"),
+      files: rest.map((one) => one.trim()).filter((one) => one !== ""),
+    });
+  }
+  return commits;
+};

package/src/index.ts

@@ -0,0 +1,256 @@
+// The campaigns family: a refactor tracked as an object in the repository —
+// `objectives`, each a detector with a ledger that only shrinks on its own,
+// over `sectors` the code declares through a `perimeter`, through ordered
+// `phases` toward an end.
+//
+// It is a family @goodbones/core does not own. A host composes it:
+//
+//   loadPolicy({ …, extensions: [campaignsExtension({ functions, reports })] })
+//
+// and reads its state back with `campaignsOf(policy)`. The core carries the
+// value and never looks inside it, which is what keeps a policy that only
+// states architecture from paying for any of this.
+export {
+  type CampaignEvaluation,
+  type CampaignEvaluationInput,
+  evaluateCampaign,
+  hitsInWindow,
+  type ObjectiveHit,
+  type SectorState,
+  towardNextOf,
+} from "./core/campaign-state.js";
+export {
+  type CampaignHit,
+  type CampaignInput,
+  campaignsFailingTheirProbe,
+  campaignsSelecting,
+  compileCampaignRule,
+  compileCampaignRules,
+  type CompiledCampaign,
+  type CompiledDetector,
+  type CompiledObjective,
+  type CompiledPerimeter,
+  type CompiledSectorTerm,
+  compileObjective,
+  candidatesOf as detectorCandidatesOf,
+  detectorOf,
+  evaluateObjective,
+  evaluateObjectives,
+  explainDetector,
+  explainObjective,
+  type FailedProbe,
+  leafTermsOf,
+  matchKeyOf,
+  needsSyntax,
+  perFileObjectivesOf,
+  probeInputOf,
+  reportSpecsOf,
+  type TermAnswer,
+} from "./core/campaigns.js";
+export {
+  allowedOf,
+  type Attestation,
+  attestedRecord,
+  clearedOf,
+  clearedSector,
+  closedOf,
+  concededSector,
+  type Concession,
+  type ConcessionRecord,
+  decodeLedger,
+  decodePlanRecord,
+  decodeSectorRecord,
+  deltaOf,
+  EMPTY_LEDGER,
+  EMPTY_SECTOR_RECORD,
+  encodeSectorName,
+  holdoutsOf,
+  initialOf,
+  isComplete,
+  isLegacyLedger,
+  isStalled,
+  lastClearedOf,
+  type Ledger,
+  ledgerArithmeticHolds,
+  ledgerPathOf,
+  Ledger as LedgerSchema,
+  legacyLedgerPathOf,
+  type Note,
+  NOTE_CAP,
+  NOTE_LENGTH,
+  notedRecord,
+  type PlanDiff,
+  planDiffOf,
+  planOf,
+  planPathOf,
+  type PlanRecord,
+  positionOf,
+  progressOf,
+  reachedRecord,
+  rebaselinedSector,
+  reconcileSector,
+  type Reconciliation,
+  sectorArithmeticHolds,
+  sectorClockOf,
+  type SectorLedger,
+  type SectorRecord,
+  sectorRecordPathOf,
+  serializeLedger,
+  serializePlanRecord,
+  serializeSectorRecord,
+} from "./core/ledger.js";
+export {
+  compareResidue,
+  derivePhase,
+  type Direction,
+  donePhaseOf,
+  inWindow,
+  isDefinedPhase,
+  isOpenPhase,
+  isShut,
+  LEGACY_PHASE,
+  objectivesInWindow,
+  onTouchOf,
+  type Residue as ResidueVector,
+  type SectorPosition,
+  UNPLACED,
+  type Window,
+  windowOf,
+  worsened,
+} from "./core/phases.js";
+export {
+  discoverSectors,
+  fixedPrefixOf,
+  IMPLICIT_SECTOR,
+  LEGACY_SECTOR,
+  membershipOf,
+  parseSectorMarker,
+  type Placement,
+  rootOf,
+  type Sector,
+  SECTOR_HOLDOUT,
+  type SectorDiscovery,
+  entryOf as sectorEntryOf,
+  type SectorIndex,
+  type SectorMarker,
+  sectorNamed,
+  withoutExtension,
+} from "./core/sectors.js";
+export {
+  type CampaignProbe,
+  type CampaignProbes,
+  type CampaignRule,
+  type CampaignUnit,
+  type Detector,
+  type Holdout,
+  type ObjectiveRule,
+  type OnTouch,
+  type PerimeterRule,
+  type PhaseConcession,
+  type PhaseRule,
+  type ProbeDiagnostic,
+  type SectorTerm,
+} from "./domain/config.js";
+export {
+  type Diagnostic,
+  indexByFile,
+  parseReport,
+  type ParseReportOptions,
+  type ReportFormat,
+  uniqueDiagnostics,
+} from "./domain/report.js";
+export {
+  type Ask,
+  attest,
+  authorOf,
+  type BaseSide,
+  baseSideAt,
+  baseSideOf,
+  campaignFailuresOf,
+  type CampaignReport,
+  campaignReportsOf,
+  clear,
+  type ClearOutcome,
+  concede,
+  type ConcedeOutcome,
+  evaluateCampaigns,
+  explainCampaignLines,
+  historyOf,
+  type HistoryRow,
+  HOLDOUT_CAP,
+  ledgeredFilter,
+  note,
+  type Nudge,
+  type NudgeHoldout,
+  nudgeOf,
+  type ObjectiveReport,
+  type Readers,
+  renderCampaignReports,
+  renderCampaignRows,
+  renderHistory,
+  renderNudge,
+  type SectorNudge,
+  type SectorObjectiveReport,
+  type SectorReport,
+  snapshotCampaignsOf,
+  type Verdict,
+  widenedExtensions,
+} from "./host/campaigns.js";
+export {
+  type Commit,
+  commitOf,
+  commitsTouching,
+  type Diff,
+  distanceToHunks,
+  type Hunk,
+  materializeTree,
+  parseDiff,
+  readDiff,
+  textAt,
+} from "./host/diff.js";
+export {
+  loadCampaignFunctions,
+  type LoadedCampaignFunctions,
+} from "./infrastructure/campaign-functions.js";
+export { makeReportSourceLive } from "./infrastructure/report-source-live.js";
+export {
+  type CampaignPolicy,
+  CAMPAIGNS_EXTENSION_ID,
+  campaignsExtension,
+  type CampaignsExtensionOptions,
+  campaignsOf,
+  ledgerKeyOf,
+} from "./load/extension.js";
+export {
+  END_STATE_ROOT,
+  endStateObjectiveId,
+  lowerCampaigns,
+  lowerEndState,
+} from "./manifest/lower.js";
+export {
+  type CampaignProbeSpec,
+  type CampaignProbesSpec,
+  CampaignsManifest,
+  type CampaignSpec,
+  DEFAULT_LEDGER_DIR,
+  type DetectorSpec,
+  durationMs,
+  type EndStateSpec,
+  type ObjectiveSpec,
+  type PerimeterSpec,
+  type PhaseSpec,
+  type SectorTermSpec,
+  type SyntaxTermSpec,
+} from "./manifest/spec.js";
+export {
+  type CampaignPredicate,
+  type CampaignPredicateInput,
+  type CampaignSubject,
+  type Range,
+} from "./ports/campaign-predicate.js";
+export {
+  NO_REPORTS,
+  type ReportSource,
+  reportSourcesOf,
+  type ReportSpec,
+} from "./ports/report-source.js";

package/src/infrastructure/campaign-functions.ts

@@ -0,0 +1,99 @@
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { ConfigInvalid } from "@goodbones/core";
+
+import type { CampaignPredicate } from "../ports/campaign-predicate.js";
+
+// A campaign's `fn` term names a predicate function as `module#export`,
+// resolved relative to the root manifest. Importing it touches the module
+// loader, which is why this lives in infrastructure and both hosts call it
+// before `loadPolicy`: the core receives the functions as a map and never
+// imports anything.
+//
+// A `.mjs` manifest may write the function itself in place of the string.
+// It is lifted out here, keyed by a synthesized name, and the manifest handed
+// back with the string in its place — so the schema, which decodes a data
+// file and a module alike, sees one shape. The whole value is walked, not
+// only `campaigns`, so a term written in a `defs` fragment is found too.
+
+export type LoadedCampaignFunctions = {
+  readonly functions: ReadonlyMap<string, CampaignPredicate>;
+  // The manifest with every function value replaced by its synthesized name.
+  readonly manifest: unknown;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const REFERENCE = /^(.+)#([A-Za-z_$][\w$]*)$/;
+
+// A `fn` term is an object whose one key is `fn`.
+const isFnTerm = (value: Record<string, unknown>): boolean =>
+  "fn" in value && Object.keys(value).length === 1;
+
+export const loadCampaignFunctions = async (
+  manifestPath: string,
+  rawManifest: unknown,
+): Promise<LoadedCampaignFunctions> => {
+  const functions = new Map<string, CampaignPredicate>();
+  const root = path.dirname(manifestPath);
+  const refuse = (detail: string): never => {
+    throw new ConfigInvalid({ configPath: manifestPath, detail });
+  };
+
+  const imported = async (reference: string): Promise<void> => {
+    if (functions.has(reference)) return;
+    const parsed = REFERENCE.exec(reference);
+    if (parsed === null) {
+      return refuse(
+        `the \`fn\` term ${JSON.stringify(reference)} is not \`module#export\`: name the ` +
+          `module (relative to the manifest) and the export, joined by \`#\`.`,
+      );
+    }
+    const [, module = "", exportName = ""] = parsed;
+    const at = path.resolve(root, module);
+    let loaded: unknown;
+    try {
+      loaded = await import(pathToFileURL(at).href);
+    } catch (cause) {
+      return refuse(
+        `the \`fn\` term ${JSON.stringify(reference)} names a module that does not load: ${String(cause)}`,
+      );
+    }
+    const found = isRecord(loaded) ? loaded[exportName] : undefined;
+    if (typeof found !== "function") {
+      return refuse(
+        `the \`fn\` term ${JSON.stringify(reference)} names an export that is not a function ` +
+          `(${found === undefined ? "absent" : typeof found}).`,
+      );
+    }
+    functions.set(reference, found as CampaignPredicate);
+  };
+
+  let synthesized = 0;
+  const lift = async (value: unknown): Promise<unknown> => {
+    if (Array.isArray(value)) {
+      const items: Array<unknown> = [];
+      for (const item of value) items.push(await lift(item));
+      return items;
+    }
+    if (!isRecord(value)) return value;
+    if (isFnTerm(value)) {
+      const fn = value.fn;
+      if (typeof fn === "function") {
+        synthesized += 1;
+        const name = `<manifest>#fn${String(synthesized)}`;
+        functions.set(name, fn as CampaignPredicate);
+        return { fn: name };
+      }
+      if (typeof fn === "string") await imported(fn);
+      return value;
+    }
+    const rebuilt: Record<string, unknown> = {};
+    for (const [key, entry] of Object.entries(value)) rebuilt[key] = await lift(entry);
+    return rebuilt;
+  };
+
+  return { functions, manifest: await lift(rawManifest) };
+};

package/src/infrastructure/report-source-fake.ts

@@ -0,0 +1,10 @@
+import type { Diagnostic } from "../domain/report.js";
+import type { ReportSource } from "../ports/report-source.js";
+
+// Keyed by file: a test states which diagnostics another tool reported on
+// which file, and never runs the tool. Every spec is answered alike.
+export const makeReportSourceFake = (
+  staged: Readonly<Record<string, ReadonlyArray<Omit<Diagnostic, "file">>>>,
+): ReportSource => ({
+  diagnosticsOf: (_spec, file) => (staged[file] ?? []).map((one) => ({ ...one, file })),
+});