@goodbones/campaigns 0.1.0 → 0.1.1-beta.2

package/src/host/diff.ts

@@ -26,10 +26,38 @@ export type Diff = {
   readonly added: ReadonlyArray<string>;
 };
 
+// git exports GIT_DIR, GIT_WORK_TREE, GIT_INDEX_FILE and friends into the
+// environment of every hook it runs, and those WIN OVER `cwd`. Everything here
+// is told which repository to read — `repoRoot` — so inheriting them would make
+// the nudge silently read whichever repository invoked the hook rather than the
+// one it was pointed at. That is not theoretical: `campaigns status --changed`
+// is designed to run from a pre-commit hook.
+//
+// Stripped, so `cwd` governs. In the ordinary case — a hook on the same
+// repository the tool was pointed at — this changes nothing.
+const AMBIENT_GIT = [
+  "GIT_DIR",
+  "GIT_WORK_TREE",
+  "GIT_INDEX_FILE",
+  "GIT_COMMON_DIR",
+  "GIT_OBJECT_DIRECTORY",
+  "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+  "GIT_NAMESPACE",
+  "GIT_PREFIX",
+  "GIT_CEILING_DIRECTORIES",
+  "GIT_QUARANTINE_PATH",
+];
+
+export const gitEnv = (): NodeJS.ProcessEnv =>
+  Object.fromEntries(
+    Object.entries(process.env).filter(([key]) => !AMBIENT_GIT.includes(key)),
+  );
+
 const git = (repoRoot: string, args: ReadonlyArray<string>): string =>
   execFileSync("git", args, {
     cwd: repoRoot,
     encoding: "utf8",
+    env: gitEnv(),
     stdio: ["ignore", "pipe", "ignore"],
     maxBuffer: 256 * 1024 * 1024,
   });
@@ -149,6 +177,7 @@ export const materializeTree = (
     ["-c", `git archive ${JSON.stringify(ref)} | tar -x -C ${JSON.stringify(root)}`],
     {
       cwd: repoRoot,
+      env: gitEnv(),
       stdio: ["ignore", "ignore", "ignore"],
     },
   );

package/src/host/measure-command.ts

@@ -0,0 +1,36 @@
+import { spawnSync } from "node:child_process";
+
+import { type CompiledMeasure, numberFromOutput } from "../core/campaigns.js";
+
+// A `command` measure's number: the command run once from the repository
+// root through the shell, its stdout read whole or through the measure's
+// pattern. Cached per command for the life of the returned function, which
+// the host makes once per evaluation — a number about the repository is
+// one number however many sectors ask. A command that cannot be spawned, or
+// whose output reads as no number, measures `NaN`, and `check` refuses it.
+// The exit status is not read: a tool that exits non-zero when the number
+// is over its own threshold is still a tool that printed the number.
+
+const MAX_BUFFER = 64 * 1024 * 1024;
+
+export const commandValues = (repoRoot: string): ((measure: CompiledMeasure) => number) => {
+  const outputs = new Map<string, string | null>();
+  const outputOf = (command: string): string | null => {
+    if (outputs.has(command)) return outputs.get(command) ?? null;
+    const run = spawnSync(command, {
+      cwd: repoRoot,
+      shell: true,
+      encoding: "utf8",
+      maxBuffer: MAX_BUFFER,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const output = run.error === undefined ? run.stdout : null;
+    outputs.set(command, output);
+    return output;
+  };
+  return (measure) => {
+    if (measure.kind !== "command") return Number.NaN;
+    const output = outputOf(measure.command);
+    return output === null ? Number.NaN : numberFromOutput(measure, output);
+  };
+};

package/src/index.ts

@@ -28,12 +28,15 @@ export {
   compileCampaignRules,
   type CompiledCampaign,
   type CompiledDetector,
+  type CompiledMeasure,
+  type CompiledMeasureSource,
   type CompiledObjective,
   type CompiledPerimeter,
   type CompiledSectorTerm,
   compileObjective,
   candidatesOf as detectorCandidatesOf,
   detectorOf,
+  distanceToTarget,
   evaluateObjective,
   evaluateObjectives,
   explainDetector,
@@ -41,40 +44,61 @@ export {
   type FailedProbe,
   leafTermsOf,
   matchKeyOf,
+  measureDetectorsOf,
+  measureFile,
+  type MeasureParts,
   needsSyntax,
+  numberFromOutput,
+  perFileMeasuresOf,
   perFileObjectivesOf,
   probeInputOf,
   reportSpecsOf,
+  roundMeasure,
   type TermAnswer,
+  valueOfParts,
 } from "./core/campaigns.js";
 export {
   allowedOf,
   type Attestation,
   attestedRecord,
+  clearedMeasure,
   clearedOf,
   clearedSector,
   closedOf,
+  concededMeasure,
   concededSector,
   type Concession,
   type ConcessionRecord,
   decodeLedger,
+  decodeMeasureLedger,
   decodePlanRecord,
   decodeSectorRecord,
   deltaOf,
   EMPTY_LEDGER,
+  EMPTY_MEASURE_LEDGER,
   EMPTY_SECTOR_RECORD,
   encodeSectorName,
   holdoutsOf,
   initialOf,
   isComplete,
   isLegacyLedger,
+  isMeasureLedger,
   isStalled,
   lastClearedOf,
+  lastImprovedOf,
   type Ledger,
   ledgerArithmeticHolds,
   ledgerPathOf,
   Ledger as LedgerSchema,
   legacyLedgerPathOf,
+  measureArithmeticHolds,
+  type MeasureConcession,
+  type MeasureLedger,
+  measureLedgerArithmeticHolds,
+  MeasureLedger as MeasureLedgerSchema,
+  measureProgressOf,
+  type MeasureSectorLedger,
+  measureStandingOf,
   type Note,
   NOTE_CAP,
   NOTE_LENGTH,
@@ -90,12 +114,14 @@ export {
   rebaselinedSector,
   reconcileSector,
   type Reconciliation,
+  recordedOf,
   sectorArithmeticHolds,
   sectorClockOf,
   type SectorLedger,
   type SectorRecord,
   sectorRecordPathOf,
   serializeLedger,
+  serializeMeasureLedger,
   serializePlanRecord,
   serializeSectorRecord,
 } from "./core/ledger.js";
@@ -143,6 +169,9 @@ export {
   type CampaignUnit,
   type Detector,
   type Holdout,
+  type Measure,
+  type MeasureDirection,
+  type MeasureSource,
   type ObjectiveRule,
   type OnTouch,
   type PerimeterRule,
@@ -236,12 +265,14 @@ export {
   type DetectorSpec,
   durationMs,
   type EndStateSpec,
+  type MeasureSourceSpec,
   type ObjectiveSpec,
   type PerimeterSpec,
   type PhaseSpec,
   type SectorTermSpec,
   type SyntaxTermSpec,
 } from "./manifest/spec.js";
+export { type CampaignMeasure } from "./ports/campaign-measure.js";
 export {
   type CampaignPredicate,
   type CampaignPredicateInput,

package/src/load/extension.ts

@@ -28,15 +28,19 @@ import {
   type CompiledDetector,
   detectorOf,
   leafTermsOf,
+  measureDetectorsOf,
 } from "../core/campaigns.js";
 import {
   decodeLedger,
+  decodeMeasureLedger,
   decodePlanRecord,
   decodeSectorRecord,
   isLegacyLedger,
+  isMeasureLedger,
   type Ledger,
   ledgerPathOf,
   legacyLedgerPathOf,
+  type MeasureLedger,
   planPathOf,
   type PlanRecord,
   type SectorRecord,
@@ -69,8 +73,10 @@ export type CampaignPolicy = {
   // has seen, is one `objectives clear` has not been run for, and `check`
   // says so.
   readonly campaignRules: ReadonlyArray<CompiledCampaign>;
-  // Keyed `<campaign>/<objective>`.
+  // Keyed `<campaign>/<objective>`: the holdout ledgers, and the scalar
+  // objectives' in a map of their own — the same file, a second schema.
   readonly ledgers: ReadonlyMap<string, Ledger>;
+  readonly measureLedgers: ReadonlyMap<string, MeasureLedger>;
   // Ledgers read from the family's first layout, `<ledgerDir>/<campaign>.json`,
   // by campaign: `clear` rewrites each in the new layout and removes it.
   readonly legacyLedgers: ReadonlyMap<string, string>;
@@ -91,6 +97,7 @@ export type CampaignPolicy = {
 const NOTHING: CampaignPolicy = {
   campaignRules: [],
   ledgers: new Map(),
+  measureLedgers: new Map(),
   legacyLedgers: new Map(),
   sectorRecords: new Map(),
   plans: new Map(),
@@ -130,18 +137,19 @@ const referencedFunctions = (detect: CompiledDetector): ReadonlyArray<string> =>
   }
 };
 
-// Every detector a campaign holds: its objectives' (a `has` term's included)
-// and its perimeter's.
+// Every detector a campaign holds: its objectives' (a `has` term's and a
+// measure's report and function sources included) and its perimeter's.
 const detectorsOf = (rule: CompiledCampaign): ReadonlyArray<CompiledDetector> => [
   ...rule.objectives.flatMap((objective) => {
     const detect = detectorOf(objective);
-    return detect === null ? [] : [detect];
+    return [...(detect === null ? [] : [detect]), ...measureDetectorsOf(objective)];
   }),
   ...(rule.perimeter?.kind === "match" ? [rule.perimeter.detect] : []),
 ];
 
 type ReadLedgers = {
   readonly ledgers: ReadonlyMap<string, Ledger>;
+  readonly measureLedgers: ReadonlyMap<string, MeasureLedger>;
   readonly legacy: ReadonlyMap<string, string>;
   readonly sectorRecords: ReadonlyMap<string, SectorRecord>;
   readonly plans: ReadonlyMap<string, PlanRecord>;
@@ -176,6 +184,7 @@ const readLedgers = (
   campaigns: ReadonlyArray<CompiledCampaign>,
 ): Result.Result<ReadLedgers, ConfigInvalid> => {
   const ledgers = new Map<string, Ledger>();
+  const measureLedgers = new Map<string, MeasureLedger>();
   const legacy = new Map<string, string>();
   const sectorRecords = new Map<string, SectorRecord>();
   const plans = new Map<string, PlanRecord>();
@@ -202,6 +211,57 @@ const readLedgers = (
         if (raw.success !== null) legacy.set(campaign.id, from);
       }
       if (raw.success === null) continue;
+      // A scalar objective's ledger is the second schema. Either kind in the
+      // other's place is refused by name: read as the wrong one it would be
+      // a decode error that says nothing about why.
+      if ((objective.measure !== null) !== isMeasureLedger(raw.success)) {
+        return Result.fail(
+          new ConfigInvalid({
+            configPath,
+            detail:
+              objective.measure !== null
+                ? `the ledger ${from} is a holdout ledger, and ${campaign.id}/${objective.id} is a scalar objective. Remove it and run \`objectives clear\` to record the number.`
+                : `the ledger ${from} is a scalar objective's, and ${campaign.id}/${objective.id} holds out ${objective.holdout ?? "matches"}. Remove it and run \`objectives clear\`.`,
+          }),
+        );
+      }
+      if (objective.measure !== null) {
+        const measured = decodeMeasureLedger(raw.success);
+        if (Result.isFailure(measured)) {
+          return Result.fail(
+            new ConfigInvalid({
+              configPath,
+              detail: `the ledger ${from} does not decode:\n${measured.failure}`,
+            }),
+          );
+        }
+        if (
+          measured.success.campaign !== campaign.id ||
+          measured.success.objective !== objective.id
+        ) {
+          return Result.fail(
+            new ConfigInvalid({
+              configPath,
+              detail:
+                `the ledger ${from} says it belongs to "${measured.success.campaign}/${measured.success.objective}", ` +
+                `not "${campaign.id}/${objective.id}".`,
+            }),
+          );
+        }
+        if (measured.success.direction !== objective.direction) {
+          return Result.fail(
+            new ConfigInvalid({
+              configPath,
+              detail:
+                `the ledger ${from} records ${campaign.id}/${objective.id} with \`direction: ${measured.success.direction}\`, ` +
+                `and the manifest now says \`${objective.direction}\`. A number that changed which way is better is a new objective: ` +
+                `remove the ledger and run \`objectives clear\`.`,
+            }),
+          );
+        }
+        measureLedgers.set(ledgerKeyOf(campaign.id, objective.id), measured.success);
+        continue;
+      }
       const decoded = decodeLedger(raw.success);
       if (Result.isFailure(decoded)) {
         return Result.fail(
@@ -270,7 +330,7 @@ const readLedgers = (
       plans.set(campaign.id, decoded.success);
     }
   }
-  return Result.succeed({ ledgers, legacy, sectorRecords, plans });
+  return Result.succeed({ ledgers, measureLedgers, legacy, sectorRecords, plans });
 };
 
 const load = (
@@ -423,7 +483,10 @@ const load = (
     ).map((failed) =>
       failed.outOfScope === true
         ? `${failed.name} (its probe ${failed.probe.path} is outside the campaign's own scope)`
-        : failed.expected === "fires"
+        : failed.measured !== undefined
+          ? `${failed.name} (${failed.expected} probe ${failed.probe.path} measured ${String(failed.measured)}, ` +
+            `${failed.expected === "ignores" ? "not 0" : failed.probe.value === undefined ? "not above 0" : `not ${String(failed.probe.value)}`})`
+          : failed.expected === "fires"
           ? `${failed.name} (fires probe ${failed.probe.path} did not fire)`
           : failed.expected === "end-shape"
             ? `${failed.name} (no fires probe is a sector in its end shape — one that no objective ` +
@@ -442,6 +505,7 @@ const load = (
     value: {
       campaignRules: campaignRules.success,
       ledgers: ledgers.success.ledgers,
+      measureLedgers: ledgers.success.measureLedgers,
       legacyLedgers: ledgers.success.legacy,
       sectorRecords: ledgers.success.sectorRecords,
       plans: ledgers.success.plans,

package/src/manifest/lower.ts

@@ -17,6 +17,8 @@ import type {
   CampaignProbe,
   CampaignRule,
   Detector,
+  Measure,
+  MeasureSource,
   ObjectiveRule,
   PerimeterRule,
   PhaseRule,
@@ -28,6 +30,7 @@ import {
   type CampaignSpec,
   type DetectorSpec,
   durationMs,
+  type MeasureSourceSpec,
   type PhaseSpec,
   type SyntaxTermSpec,
 } from "./spec.js";
@@ -376,9 +379,66 @@ const lowerCampaign = (
         campaign: id,
         message,
         ...(why === undefined ? {} : { why }),
-        holdout: spec.holdout,
+        ...(spec.holdout === undefined ? {} : { holdout: spec.holdout }),
         ...(spec.until === undefined ? {} : { until: spec.until }),
       };
+      if (spec.measure !== undefined) {
+        const measure = spec.measure;
+        if ("command" in measure && campaign.perimeter !== undefined) {
+          refuse(
+            `(${objectiveId}) measures a \`command\`, and the campaign has a perimeter. A ` +
+              `command's number is about the repository, not a sector; it belongs to a ` +
+              `campaign with no perimeter, whose scope is its one sector.`,
+          );
+        }
+        const source = (one: MeasureSourceSpec): MeasureSource =>
+          "report" in one || "fn" in one
+            ? (lower(one, objectiveId) as MeasureSource)
+            : "lines" in one
+              ? { lines: true }
+              : { files: true };
+        const lowered: Measure =
+          "ratio" in measure
+            ? {
+                ratio: {
+                  of: source(measure.ratio.of),
+                  per: source(measure.ratio.per),
+                  scale: measure.ratio.scale ?? 1,
+                },
+              }
+            : "command" in measure
+              ? {
+                  command: measure.command,
+                  ...(measure.pattern === undefined ? {} : { pattern: measure.pattern }),
+                }
+              : source(measure);
+        if ("command" in measure && measure.pattern !== undefined) {
+          let groups: Readonly<Record<string, unknown>> | undefined;
+          try {
+            groups = new RegExp(`${measure.pattern}|`).exec("")?.groups;
+          } catch (cause) {
+            refuse(
+              `(${objectiveId}) has a \`pattern\` that is not a regular expression: ${String(cause)}`,
+            );
+          }
+          if (groups === undefined || !("value" in groups)) {
+            refuse(
+              `(${objectiveId}) has a \`pattern\` with no named group \`value\` to read the number from.`,
+            );
+          }
+        }
+        return {
+          ...base,
+          measure: lowered,
+          direction: spec.direction ?? "down",
+          tolerance: spec.tolerance ?? 0,
+          ...(spec.target === undefined ? {} : { target: spec.target }),
+          probes: {
+            fires: [...(spec.probes?.fires ?? [])],
+            ignores: [...(spec.probes?.ignores ?? [])],
+          },
+        };
+      }
       if (spec.match !== undefined) {
         return {
           ...base,
@@ -469,6 +529,15 @@ const lowerCampaign = (
           `phase "${phase.id}" names an objective "${objectiveId}" the campaign does not declare.`,
         );
       }
+      const named = objectives.find((one) => one.id === objectiveId);
+      if (named?.measure !== undefined && named.target === undefined) {
+        refuse(
+          `phase "${phase.id}" names the scalar objective "${objectiveId}", which states no ` +
+            `\`target\`. A phase's objectives are what a sector must meet to leave it, and a ` +
+            `number with no target is never met: give it one, or leave it out of every phase ` +
+            `as a standing measure.`,
+        );
+      }
       const already = namedBy.get(objectiveId);
       if (already !== undefined) {
         refuse(
@@ -564,6 +633,16 @@ const lowerCampaign = (
           match: objective?.match ?? null,
           sector: objective?.sector ?? null,
           until: objective?.until ?? null,
+          // Only when present, so a phase with no scalar hashes as it did
+          // before scalars existed and no committed plan reads as changed.
+          ...(objective?.measure === undefined
+            ? {}
+            : {
+                measure: objective.measure,
+                direction: objective.direction ?? null,
+                tolerance: objective.tolerance ?? null,
+                target: objective.target ?? null,
+              }),
         };
       }),
     }),

package/src/manifest/spec.ts

@@ -184,6 +184,8 @@ const CampaignProbe = Schema.Struct({
   edges: Schema.optionalKey(Schema.Record(Schema.String, ImportProbeTarget)),
   files: Schema.optionalKey(Schema.Array(Schema.String)),
   report: Schema.optionalKey(Schema.Array(ProbeDiagnostic)),
+  // A scalar objective's probe: the number the file contributes.
+  value: Schema.optionalKey(Schema.Finite),
 });
 
 const CampaignProbes = Schema.Struct({
@@ -207,29 +209,122 @@ const SectorTermSpec = Schema.Union([
   Schema.Struct({ oneHost: Globs }),
 ]);
 
+// Where a scalar objective's number comes from, per file, summed over a
+// sector: `lines` (non-blank), `files` (one each), the diagnostics a
+// `report` puts on the file, or the number an `fn` returns for it.
+const MeasureSourceSpec = Schema.Union([
+  Schema.Struct({ lines: Schema.Literal(true) }),
+  Schema.Struct({ files: Schema.Literal(true) }),
+  Schema.Struct({ report: ReportTerm }),
+  Schema.Struct({ fn: Schema.String }),
+]);
+
+// A scalar objective's number: one source, a `ratio` of two (`scale × Σof /
+// Σper`, `scale` defaulting to 1), or a `command` whose output is the number
+// — whole, or the `value` group of `pattern`. A command measures the
+// repository, not a file, so only a campaign with no perimeter may run one.
+const MeasureSpec = Schema.Union([
+  MeasureSourceSpec,
+  Schema.Struct({
+    ratio: Schema.Struct({
+      of: MeasureSourceSpec,
+      per: MeasureSourceSpec,
+      scale: Schema.optionalKey(Schema.Finite),
+    }),
+  }),
+  Schema.Struct({ command: Schema.String, pattern: Schema.optionalKey(Schema.String) }),
+]);
+
+type MeasureSpec = typeof MeasureSpec.Type;
+export type MeasureSourceSpec = typeof MeasureSourceSpec.Type;
+
+// Whether any source of the measure is one a probe must prove: a report or
+// a function, which can drift into measuring nothing.
+const measureNeedsProbe = (measure: MeasureSpec): boolean => {
+  const sources = "ratio" in measure ? [measure.ratio.of, measure.ratio.per] : [measure];
+  return sources.some((one) => "report" in one || "fn" in one);
+};
+
 // An objective: a detector with a ledger that only shrinks on its own. The
 // `holdout` says what one ledger entry is; `match` is a per-file detector
 // and `sector` a term over the sector's files, exactly one of them.
-// `until` names the phase at which it stops counting.
+// `until` names the phase at which it stops counting. A scalar objective
+// has a `measure` in place of both, a `direction`, a `tolerance` either side
+// of its record, and the `target` at which it is met.
 const Objective = Schema.Struct({
   // What a reader at a holdout does about it — the message every hit
   // carries; falls back to the campaign's.
   how: Schema.optionalKey(Schema.String),
   why: Schema.optionalKey(Schema.String),
-  holdout: Holdout,
+  holdout: Schema.optionalKey(Holdout),
   match: Schema.optionalKey(DetectorRef),
   sector: Schema.optionalKey(SectorTermSpec),
+  measure: Schema.optionalKey(MeasureSpec),
+  direction: Schema.optionalKey(Schema.Literals(["down", "up"])),
+  tolerance: Schema.optionalKey(Schema.Finite.check(Schema.isGreaterThanOrEqualTo(0))),
+  target: Schema.optionalKey(Schema.Finite),
   until: Schema.optionalKey(KebabId),
   probes: Schema.optionalKey(CampaignProbes),
 }).check(
   Schema.makeFilter((objective) => {
     const issues: Array<Schema.FilterIssue> = [];
-    if ((objective.match === undefined) === (objective.sector === undefined)) {
+    const named = [objective.match, objective.sector, objective.measure].filter(
+      (one) => one !== undefined,
+    ).length;
+    if (named !== 1) {
       issues.push(
-        "an objective names exactly one of `match` (a detector over each file) and `sector` (a term over the sector's files)",
+        "an objective names exactly one of `match` (a detector over each file), `sector` (a term over the sector's files) and `measure` (a number per sector)",
       );
     }
-    if (objective.sector !== undefined && objective.holdout !== "sector") {
+    if (objective.measure !== undefined) {
+      if (objective.holdout !== undefined) {
+        issues.push({
+          path: ["holdout"],
+          issue: "a `measure` objective holds nothing out: it is a number, so drop `holdout`",
+        });
+      }
+      if (objective.direction === undefined) {
+        issues.push({
+          path: ["direction"],
+          issue:
+            "a `measure` objective states which way is better: `direction: down` or `direction: up`",
+        });
+      }
+      if ("command" in objective.measure && objective.probes !== undefined) {
+        issues.push({
+          path: ["probes"],
+          issue:
+            "a `command` measure is a number about the repository, which no probe of one file can stand in for: drop `probes`",
+        });
+      } else if (
+        measureNeedsProbe(objective.measure) &&
+        (objective.probes?.fires.length ?? 0) === 0
+      ) {
+        issues.push({
+          path: ["probes"],
+          issue:
+            "a `measure` with a `report` or `fn` source carries `probes.fires`: at least one file it must measure above zero",
+        });
+      }
+      return issues;
+    }
+    for (const key of ["direction", "tolerance", "target"] as const) {
+      if (objective[key] !== undefined) {
+        issues.push({ path: [key], issue: `\`${key}\` belongs to a \`measure\` objective` });
+      }
+    }
+    if (objective.holdout === undefined) {
+      issues.push({
+        path: ["holdout"],
+        issue:
+          "an objective with `match` or `sector` says what one holdout is: `holdout: file`, `declaration`, `match` or `sector`",
+      });
+    }
+    if (
+      objective.sector !== undefined &&
+      objective.holdout !== undefined &&
+      objective.holdout !== "sector"
+    ) {
       issues.push({
         path: ["holdout"],
         issue: "a `sector` objective's holdout is the sector: write `holdout: sector`",

package/src/ports/campaign-measure.ts

@@ -0,0 +1,11 @@
+import type { CampaignPredicateInput } from "./campaign-predicate.js";
+
+// The floor of a scalar objective's measure: a function the repository
+// writes, named from the manifest as `module#export` exactly as a `fn`
+// detector term is, and loaded the same way. It is given what the evaluator
+// has about one file and answers the number that file contributes — a
+// count, a size, a weight — which the host sums over each sector. Anything
+// but a finite number of zero or more is a measure that did not answer, and
+// `check` refuses it. Exported as a public type so a referenced module
+// typechecks on its own.
+export type CampaignMeasure = (input: CampaignPredicateInput) => number;