@goodbones/core 0.1.0-beta.10 → 0.1.0-beta.12

package/src/domain/snapshot.ts

@@ -18,7 +18,7 @@ import type { ViolationKind } from "./violation.js";
 export const SNAPSHOT_SCHEMA_ID =
   "https://dataquail.github.io/goodbones/schema/conformance.schema.json";
 
-export const SNAPSHOT_VERSION = 1;
+export const SNAPSHOT_VERSION = 2;
 
 const describe = <S extends Schema.Top>(schema: S, description: string) =>
   schema.annotate({ description });
@@ -82,7 +82,16 @@ export const SnapshotViolation = Schema.Struct({
   baselined: describe(Schema.Boolean, "Carried by the baseline, so `check` does not fail on it."),
   ledgered: describe(
     Schema.Boolean,
-    "For a campaign hit: carried by the campaign's ledger, so `check` does not fail on it.",
+    "For a campaign hit: carried by the objective's ledger, so `check` does not fail on it.",
+  ),
+  objective: Schema.optionalKey(
+    describe(Schema.String, "For a campaign hit: the objective that fired."),
+  ),
+  sector: Schema.optionalKey(
+    describe(Schema.String, "For a campaign hit: the sector the hit falls in."),
+  ),
+  entry: Schema.optionalKey(
+    describe(Schema.String, "For a campaign hit: its ledger entry, relative to the sector's root."),
   ),
 });
 
@@ -130,46 +139,134 @@ export const SnapshotVacancy = Schema.Struct({
   ),
 });
 
-// One campaign's burn-down: what its ledger says, and what the clock says
-// about it. Every count is over ledger entries, which are hits by fingerprint.
-export const SnapshotCampaign = Schema.Struct({
-  id: describe(Schema.String, "The campaign's id; its ledger is `<ledger>/<id>.json`."),
-  title: Schema.optionalKey(describe(Schema.String, "The campaign's title, when it states one.")),
-  owner: Schema.optionalKey(
-    describe(Schema.String, "Who is running the campaign, as the manifest names them."),
+// One objective's burn-down: what its ledger says, summed over its sectors.
+export const SnapshotObjective = Schema.Struct({
+  id: describe(
+    Schema.String,
+    "The objective's id; its ledger is `<ledger>/<campaign>/<objective>.json`.",
+  ),
+  phase: describe(
+    Schema.NullOr(Schema.String),
+    "The phase naming the objective, or `null` for one no phase names — in window everywhere.",
   ),
-  initial: describe(Schema.Finite, "Entries the day the ledger was written."),
+  initial: describe(Schema.Finite, "Holdouts recorded as each sector entered the window, summed."),
   allowed: describe(
     Schema.Finite,
-    "Entries added since by `campaigns allow`, each with a regression record.",
+    "Holdouts added since by `objectives concede` or a re-baseline, each with a concession.",
   ),
-  count: describe(Schema.Finite, "Entries in the ledger now."),
-  fixed: describe(
+  count: describe(Schema.Finite, "Holdouts in the ledger now, every sector summed."),
+  cleared: describe(
     Schema.Finite,
-    "Entries removed by `campaigns prune` since the ledger was written.",
+    "Holdouts removed by `objectives clear` because they stopped firing.",
+  ),
+  closed: describe(
+    Schema.Finite,
+    "Holdouts still firing when a sector left the window — not progress.",
   ),
   progress: describe(
     Schema.Finite,
-    "`1 - count / (initial + allowed)`: how much of everything ever ledgered has been paid down.",
+    "`1 - count / (initial + allowed - closed)`: how much of everything ever ledgered has been paid down.",
   ),
-  lastProgress: describe(
-    Schema.String,
-    "When an entry last left the ledger, ISO 8601 — the stall clock's reading.",
+  lastCleared: describe(
+    Schema.NullOr(Schema.String),
+    "When a holdout last left the ledger, ISO 8601 — the stall clock's reading; `null` with no ledger.",
+  ),
+  concessions: describe(Schema.Finite, "How many times a count was allowed to go up."),
+  complete: describe(Schema.Boolean, "No holdouts remain."),
+  ledgered: describe(
+    Schema.Boolean,
+    "Whether a ledger exists. An objective with none has been declared and not yet cleared.",
+  ),
+});
+
+// One phase of the ladder, and how many sectors stand at it.
+export const SnapshotPhase = Schema.Struct({
+  id: describe(Schema.String, "The phase's id."),
+  defined: describe(
+    Schema.Boolean,
+    "Whether the phase names criteria. An open phase has only an intent, and is last.",
+  ),
+  sectors: describe(Schema.Finite, "How many sectors are derived to stand at this phase."),
+});
+
+// One sector: where it stands, and its residue toward its next phase.
+export const SnapshotSector = Schema.Struct({
+  name: describe(Schema.String, "The sector's identity, as its perimeter names it."),
+  phase: describe(
+    Schema.NullOr(Schema.String),
+    "The phase the sector is derived to stand at, or `null` when it is past the last one.",
+  ),
+  reached: describe(
+    Schema.NullOr(Schema.String),
+    "The furthest phase the sector's record says it has reached; `null` before its first `clear`.",
+  ),
+  files: describe(Schema.Finite, "How many files the sector claims."),
+  residue: describe(
+    Schema.Record(Schema.String, Schema.Finite),
+    "One dimension per objective in window for the sector: its holdouts there, never summed.",
+  ),
+  stalled: describe(
+    Schema.Boolean,
+    "Holdouts remain for the sector and nothing has been cleared, attested or noted within `staleAfter`.",
+  ),
+});
+
+// One campaign: its objectives' burn-down, the distribution of its sectors
+// over its phases, the legacy remainder, and what changed in its plan.
+export const SnapshotCampaign = Schema.Struct({
+  id: describe(Schema.String, "The campaign's id; its ledgers are under `<ledger>/<id>/`."),
+  title: Schema.optionalKey(describe(Schema.String, "The campaign's title, when it states one.")),
+  owner: Schema.optionalKey(
+    describe(Schema.String, "Who is running the campaign, as the manifest names them."),
+  ),
+  count: describe(Schema.Finite, "Holdouts across every objective and sector."),
+  progress: describe(
+    Schema.Finite,
+    "Cleared over everything ever ledgered, across the campaign's objectives.",
+  ),
+  objectives: describe(Schema.Array(SnapshotObjective), "Every objective, in manifest order."),
+  phases: describe(
+    Schema.Array(SnapshotPhase),
+    "The ladder, in order, with how many sectors stand at each phase.",
+  ),
+  sectors: describe(Schema.Array(SnapshotSector), "Every sector the perimeter births, by name."),
+  legacy: describe(
+    Schema.Struct({
+      files: describe(Schema.Finite, "Files in the scope no sector claims."),
+      holdouts: describe(
+        Schema.Finite,
+        "Holdouts in the legacy, under the first phase's objectives — where a holdout moved out of a sector lands.",
+      ),
+    }),
+    "The unclaimed remainder of the scope, which stands at the first phase and is not a sink.",
+  ),
+  plan: describe(
+    Schema.Struct({
+      refined: describe(
+        Schema.Array(Schema.String),
+        "Phases refined since the last `clear`: an open phase that gained criteria, or a new one. Free.",
+      ),
+      changed: describe(
+        Schema.Array(Schema.String),
+        "Defined phases whose definition changed since the last `clear` — what a reviewer reads every time.",
+      ),
+      unreceipted: describe(
+        Schema.Array(Schema.String),
+        "Changed phases carrying no new concession; `check` fails on them.",
+      ),
+    }),
+    "What changed in the plan, refinements and changes apart.",
   ),
-  regressions: describe(Schema.Finite, "How many times the count was allowed to go up."),
   stalled: describe(
     Schema.Boolean,
-    "Entries remain and `lastProgress` is older than the campaign's `staleAfter`.",
+    "Holdouts remain and nothing has been cleared, attested or noted within the campaign's `staleAfter`.",
   ),
-  complete: describe(Schema.Boolean, "No entries remain."),
+  complete: describe(Schema.Boolean, "No holdouts remain in any objective."),
   onComplete: describe(
     Schema.Literals(["keep", "remove"]),
     "What the manifest asks once complete: keep the campaign as a guard, or remove it.",
   ),
-  ledgered: describe(
-    Schema.Boolean,
-    "Whether a ledger exists. A campaign with none has been declared and not yet initialised.",
-  ),
+  ledgered: describe(Schema.Boolean, "Whether every objective has a ledger."),
 });
 
 export const Snapshot = Schema.Struct({
@@ -271,6 +368,9 @@ export type SnapshotSlack = typeof SnapshotSlack.Type;
 export type SnapshotConcentration = typeof SnapshotConcentration.Type;
 export type SnapshotVacancy = typeof SnapshotVacancy.Type;
 export type SnapshotCampaign = typeof SnapshotCampaign.Type;
+export type SnapshotObjective = typeof SnapshotObjective.Type;
+export type SnapshotPhase = typeof SnapshotPhase.Type;
+export type SnapshotSector = typeof SnapshotSector.Type;
 
 // Decodes a document some other run wrote — the base of a pull request, a
 // stored one — refusing a key the shape does not declare, so a consumer never

package/src/index.ts

@@ -3,6 +3,15 @@
 // manifest into a policy. A host composes these with a language pack and the
 // live file system; a language pack implements the ports. Nothing here names a
 // language. The fakes are under `@goodbones/core/testing`.
+//
+// A family the core does not own — `campaigns`, in @goodbones/campaigns —
+// arrives as a `PolicyExtension` the host passes to `loadPolicy`: it claims
+// its own manifest keys, decodes them with its own codec, and reads its state
+// back off `LoadedPolicy.extensions`. What such a family needs from here is
+// exported deliberately: the glob primitives its lowering must match
+// character for character, the pattern vocabulary its detectors share with
+// the other families, and `lowerManifest` itself, which an `endState` runs a
+// sector-relative tree through.
 export {
   type Baseline,
   type BaselineFilter,
@@ -14,25 +23,6 @@ export {
   staleEntriesOf,
   unbaselined,
 } from "./core/baseline.js";
-export {
-  type CampaignHit,
-  type CampaignInput,
-  campaignsFailingTheirProbe,
-  campaignsSelecting,
-  compileCampaignRule,
-  compileCampaignRules,
-  type CompiledCampaign,
-  type CompiledDetector,
-  evaluateCampaign,
-  evaluateCampaigns,
-  explainCampaign,
-  type FailedProbe,
-  leafTermsOf,
-  matchKeyOf,
-  probeInputOf,
-  reportSpecsOf,
-  type TermAnswer,
-} from "./core/campaigns.js";
 export {
   type Coverage,
   type CoverageFamily,
@@ -83,27 +73,6 @@ export {
   rulesSelecting,
   type SelectedRule,
 } from "./core/imports.js";
-export {
-  allowed,
-  decodeLedger,
-  EMPTY_LEDGER,
-  entryOf,
-  isComplete,
-  isStalled,
-  type Ledger,
-  ledgerArithmeticHolds,
-  ledgerOf,
-  Ledger as LedgerSchema,
-  newEntriesOf,
-  progressOf,
-  pruned,
-  reconcile,
-  type Reconciliation,
-  type Regression,
-  type RegressionRecord,
-  serializeLedger,
-  staleEntriesOf as staleLedgerEntriesOf,
-} from "./core/ledger.js";
 export {
   type CompiledMemberRule,
   compileMemberRules,
@@ -111,6 +80,16 @@ export {
   memberRulesFailingTheirProbe,
   memberRulesSelecting,
 } from "./core/members.js";
+export {
+  compilePatterns,
+  firstFromMatch,
+  matchesAny,
+  type Selectable,
+  sourcesOf,
+  targetAllowed,
+  type Targeted,
+  validateTargetPatterns,
+} from "./core/patterns.js";
 export {
   type Concentration,
   type ObservedEdge,
@@ -124,6 +103,7 @@ export {
   EMPTY_STRUCTURE,
   evaluateStructure,
   requiredSiblingsOf,
+  siblingsOf,
   structureRulesFailingTheirProbe,
 } from "./core/structure.js";
 export {
@@ -135,12 +115,8 @@ export {
 } from "./core/surface.js";
 export {
   type Allowance,
-  type BindingKind,
-  type CampaignProbe,
-  type CampaignRule,
-  type CampaignUnit,
-  type DeclarationKind,
-  type Detector,
+  BindingKind,
+  DeclarationKind,
   type ExportFix,
   type ExportRule,
   type GraphConfig,
@@ -148,11 +124,11 @@ export {
   type GraphOrphanRule,
   type GraphReachRule,
   type ImportProbe,
-  type ImportProbeTarget,
+  ImportProbeTarget,
   type ImportRule,
   type MemberRule,
-  type MemberSubject,
-  type ProbeDiagnostic,
+  MemberSubject,
+  PatternList,
   type ResolveConfig,
   type ResolveScope,
   type StructureConfig,
@@ -177,14 +153,6 @@ export {
   type ManifestPosition,
   renderManifestPath,
 } from "./domain/manifest-location.js";
-export {
-  type Diagnostic,
-  indexByFile,
-  parseReport,
-  type ParseReportOptions,
-  type ReportFormat,
-  uniqueDiagnostics,
-} from "./domain/report.js";
 export {
   CONFORMANCE_MEASURES,
   type ConformanceMeasure,
@@ -195,7 +163,10 @@ export {
   type SnapshotCampaign,
   type SnapshotConcentration,
   snapshotJsonSchema,
+  type SnapshotObjective,
+  type SnapshotPhase,
   Snapshot as SnapshotSchema,
+  type SnapshotSector,
   type SnapshotSlack,
   type SnapshotVacancy,
   type SnapshotViolation,
@@ -206,10 +177,6 @@ export {
   type Violation,
   type ViolationKind,
 } from "./domain/violation.js";
-export {
-  loadCampaignFunctions,
-  type LoadedCampaignFunctions,
-} from "./infrastructure/campaign-functions.js";
 export { makeFileSystemLive } from "./infrastructure/file-system-live.js";
 export {
   findManifestFile,
@@ -224,16 +191,25 @@ export {
   type IncludeReader,
   type SourceDocument,
 } from "./infrastructure/manifest-include.js";
-export { makeReportSourceLive } from "./infrastructure/report-source-live.js";
 export {
   listPackageRoots,
   listSourceFiles,
+  listWorkspaceProjects,
   type PackagedLanguage,
   type PackageRoot,
   type WalkedLanguage,
+  type WorkspaceProject,
 } from "./infrastructure/walk.js";
+export {
+  type ExtensionContext,
+  type ExtensionRoute,
+  type LoadedExtension,
+  type PolicyExtension,
+} from "./load/extension.js";
 export { type LoadedPolicy, loadPolicy, type LoadPolicyInput } from "./load/policy.js";
 export {
+  CONVENTIONS,
+  expandAliases,
   type LoweredRules,
   lowerManifest,
   type LowerOptions,
@@ -247,6 +223,15 @@ export {
   originOf,
   type Substitution,
 } from "./manifest/expand.js";
+export { type ManifestExtension } from "./manifest/extension.js";
+export {
+  anchored,
+  type CaptureIndex,
+  type GlobCompilation,
+  globToRegExp,
+  globToRegexSource,
+  prefixed,
+} from "./manifest/glob.js";
 export {
   type Candidate,
   candidatesOf,
@@ -263,26 +248,20 @@ export {
   MANIFEST_NODE_SCHEMA_ID,
   MANIFEST_SCHEMA_ID,
   manifestJsonSchema,
+  type ManifestJsonSchemaOptions,
   manifestNodeJsonSchema,
 } from "./manifest/json-schema.js";
 export {
-  type CampaignSpec,
   type DecodedManifest,
   decodeManifest,
   type DecodeManifestOptions,
-  DEFAULT_LEDGER_DIR,
-  type DetectorSpec,
-  durationMs,
+  decodeManifestTree,
+  globsOf,
   type Manifest,
   type ManifestNode,
   Manifest as ManifestSchema,
+  SurfaceConvention,
 } from "./manifest/manifest.js";
-export {
-  type CampaignPredicate,
-  type CampaignPredicateInput,
-  type CampaignSubject,
-  type Range,
-} from "./ports/campaign-predicate.js";
 export { type FactExtractor } from "./ports/fact-extractor.js";
 export { type FileSystem } from "./ports/file-system.js";
 export { type Language } from "./ports/language.js";
@@ -291,12 +270,6 @@ export {
   type ModuleResolver,
   type ResolvedTarget,
 } from "./ports/module-resolver.js";
-export {
-  NO_REPORTS,
-  type ReportSource,
-  reportSourcesOf,
-  type ReportSpec,
-} from "./ports/report-source.js";
 export {
   type Position,
   type SyntaxMatch,

package/src/infrastructure/file-system-fake.ts

@@ -10,5 +10,17 @@ export const makeFileSystemFake = (
   return {
     exists: (repoRelativePath) => paths.has(repoRelativePath),
     readText: (repoRelativePath) => contents[repoRelativePath] ?? null,
+    list: (repoRelativeDir) => {
+      const prefix = repoRelativeDir === "" ? "" : `${repoRelativeDir}/`;
+      return [
+        ...new Set(
+          [...paths]
+            .filter((one) => one.startsWith(prefix))
+            .map((one) => one.slice(prefix.length).split("/")[0] ?? ""),
+        ),
+      ]
+        .filter((one) => one !== "")
+        .sort();
+    },
   };
 };

package/src/infrastructure/file-system-live.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import * as path from "node:path";
 
 import type { FileSystem } from "../ports/file-system.js";
@@ -23,5 +23,12 @@ export const makeFileSystemLive = (repoRoot: string): FileSystem => {
         return null;
       }
     },
+    list: (repoRelativeDir) => {
+      try {
+        return readdirSync(path.resolve(repoRoot, repoRelativeDir)).sort();
+      } catch {
+        return [];
+      }
+    },
   };
 };

package/src/infrastructure/walk.ts

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import * as path from "node:path";
 
 import type { Language } from "../ports/language.js";
@@ -24,13 +24,16 @@ export type WalkedLanguage = Pick<Language, "extensions" | "ignoredFiles">;
 // Which files count as source is the languages' to say: the extension set is
 // the union of theirs, and so is the set of files to step over. A root that
 // names a file is that file, whatever its extension — `architecture check
-// <file>` is a reasonable thing to type.
+// <file>` is a reasonable thing to type. `widened` adds the extensions a
+// campaign's scope names beyond the packs' — a file the pack cannot parse
+// contributes no facts, and only a campaign that asked for it sees it.
 export const listSourceFiles = (
   repoRoot: string,
   roots: ReadonlyArray<string>,
   languages: ReadonlyArray<WalkedLanguage>,
+  widened: ReadonlyArray<string> = [],
 ): ReadonlyArray<string> => {
-  const extensions = new Set(languages.flatMap((language) => language.extensions));
+  const extensions = new Set([...languages.flatMap((language) => language.extensions), ...widened]);
   const ignored = languages.flatMap((language) => language.ignoredFiles);
   const isSource = (entry: string): boolean =>
     extensions.has(path.extname(entry)) && !ignored.some((pattern) => pattern.test(entry));
@@ -121,3 +124,55 @@ export const listPackageRoots = (
   }
   return [...found.values()].sort((a, b) => a.root.localeCompare(b.root));
 };
+
+export type WorkspaceProject = {
+  readonly name: string;
+  // Repo-relative folder with forward slashes.
+  readonly root: string;
+};
+
+// The workspace's projects, for an `nx` perimeter: every folder under the
+// roots holding a `project.json`, named by it — or, when it names nothing,
+// by the `package.json` beside it, or the folder. Read from the files
+// rather than from `nx graph`, so no process is spawned and a checkout
+// without the workspace's tooling installed still has its sectors.
+export const listWorkspaceProjects = (
+  repoRoot: string,
+  roots: ReadonlyArray<string>,
+): ReadonlyArray<WorkspaceProject> => {
+  const found: Array<WorkspaceProject> = [];
+  const nameIn = (absolute: string, file: string): string | null => {
+    try {
+      const parsed = JSON.parse(readFileSync(path.join(absolute, file), "utf8")) as unknown;
+      const name =
+        typeof parsed === "object" && parsed !== null
+          ? (parsed as { readonly name?: unknown }).name
+          : undefined;
+      return typeof name === "string" && name !== "" ? name : null;
+    } catch {
+      return null;
+    }
+  };
+  const walk = (absolute: string): void => {
+    if (existsSync(path.join(absolute, "project.json"))) {
+      const root = path.relative(repoRoot, absolute).replaceAll(path.sep, "/");
+      found.push({
+        name:
+          nameIn(absolute, "project.json") ??
+          nameIn(absolute, "package.json") ??
+          path.basename(absolute),
+        root,
+      });
+    }
+    for (const entry of readdirSync(absolute)) {
+      if (SKIPPED.has(entry)) continue;
+      const child = path.join(absolute, entry);
+      if (statSync(child).isDirectory()) walk(child);
+    }
+  };
+  for (const root of roots) {
+    const absolute = path.resolve(repoRoot, root);
+    if (statSync(absolute).isDirectory()) walk(absolute);
+  }
+  return found.sort((a, b) => a.root.localeCompare(b.root));
+};

package/src/load/extension.ts

@@ -0,0 +1,66 @@
+import type * as Result from "effect/Result";
+
+import type { ResolveScope } from "../domain/architecture-config.js";
+import type { ConfigInvalid, PatternInvalid } from "../domain/architecture-error.js";
+import type { ManifestExtension } from "../manifest/extension.js";
+import type { Manifest } from "../manifest/manifest.js";
+import type { FactExtractor } from "../ports/fact-extractor.js";
+import type { FileSystem } from "../ports/file-system.js";
+import type { Language } from "../ports/language.js";
+import type { SyntaxMatcher } from "../ports/syntax-matcher.js";
+
+// The load half of a family the core does not own: what `loadPolicy` hands it,
+// and what it hands back.
+//
+// A host composes the extensions it wants — `loadPolicy({ …, extensions: [
+// campaignsExtension({ functions, reports }) ] })` — and reads its family's
+// state back off `LoadedPolicy.extensions` through whatever typed accessor
+// that package exports. The core carries the value and never looks inside it.
+//
+// An extension is given the same things the core's own families are given at
+// load: the routing extractor and syntax matcher, the file system port, the
+// language packs, and which scope covers a given file. It is not given the
+// resolver, which is built after every rule has been probed — a family that
+// needs one resolves at evaluation, off `LoadedPolicy`.
+
+export type ExtensionRoute = {
+  readonly language: Language;
+  readonly scope: ResolveScope;
+};
+
+export type ExtensionContext<Spec = unknown> = {
+  // What this family's `decode` returned.
+  readonly spec: Spec;
+  readonly configPath: string;
+  readonly repoRoot: string;
+  // The manifest the core decoded — `resolve`, `aliases`, `tree`, the
+  // families the core owns. The family's own keys are in `spec`.
+  readonly config: Manifest;
+  readonly languages: ReadonlyArray<Language>;
+  readonly fileSystem: FileSystem;
+  // Routes each file to the extractor of the language whose scope covers it:
+  // the same one the core parsed its own probes with.
+  readonly extractor: FactExtractor;
+  // Routes each file to the syntax matcher of its scope's language; `parse`
+  // answers `null` for a language carrying none.
+  readonly syntax: SyntaxMatcher;
+  readonly routeFor: (file: string) => ExtensionRoute | undefined;
+  readonly now: number;
+};
+
+export type LoadedExtension<Value = unknown> = {
+  // Carried on `LoadedPolicy.extensions`, keyed by the extension's id.
+  readonly value: Value;
+  // Rules of this family that do not report their own probe. Merged into the
+  // one refusal the loader raises for every family at once, so a vacuous
+  // campaign and a vacuous import rule are reported in the same sentence.
+  readonly vacuous?: ReadonlyArray<string> | undefined;
+};
+
+export type PolicyExtension<Spec = unknown, Value = unknown> = ManifestExtension<Spec> & {
+  // A method, like `decode`, so the loader can hold every extension at one
+  // erased type after their specs have been decoded.
+  load(
+    context: ExtensionContext<Spec>,
+  ): Result.Result<LoadedExtension<Value>, ConfigInvalid | PatternInvalid>;
+};