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

package/schema/conformance.schema.json

@@ -8,7 +8,7 @@
     "version": {
       "type": "number",
       "enum": [
-        1
+        2
       ],
       "description": "The shape of this document."
     },
@@ -450,7 +450,19 @@
           },
           "ledgered": {
             "type": "boolean",
-            "description": "For a campaign hit: carried by the campaign's ledger, so `check` does not fail on it."
+            "description": "For a campaign hit: carried by the objective's ledger, so `check` does not fail on it."
+          },
+          "objective": {
+            "type": "string",
+            "description": "For a campaign hit: the objective that fired."
+          },
+          "sector": {
+            "type": "string",
+            "description": "For a campaign hit: the sector the hit falls in."
+          },
+          "entry": {
+            "type": "string",
+            "description": "For a campaign hit: its ledger entry, relative to the sector's root."
           }
         },
         "required": [
@@ -649,7 +661,7 @@
         "properties": {
           "id": {
             "type": "string",
-            "description": "The campaign's id; its ledger is `<ledger>/<id>.json`."
+            "description": "The campaign's id; its ledgers are under `<ledger>/<id>/`."
           },
           "title": {
             "type": "string",
@@ -659,35 +671,11 @@
             "type": "string",
             "description": "Who is running the campaign, as the manifest names them."
           },
-          "initial": {
-            "type": "number",
-            "allOf": [
-              {
-                "description": "Entries the day the ledger was written."
-              }
-            ]
-          },
-          "allowed": {
-            "type": "number",
-            "allOf": [
-              {
-                "description": "Entries added since by `campaigns allow`, each with a regression record."
-              }
-            ]
-          },
           "count": {
             "type": "number",
             "allOf": [
               {
-                "description": "Entries in the ledger now."
-              }
-            ]
-          },
-          "fixed": {
-            "type": "number",
-            "allOf": [
-              {
-                "description": "Entries removed by `campaigns prune` since the ledger was written."
+                "description": "Holdouts across every objective and sector."
               }
             ]
           },
@@ -695,29 +683,285 @@
             "type": "number",
             "allOf": [
               {
-                "description": "`1 - count / (initial + allowed)`: how much of everything ever ledgered has been paid down."
+                "description": "Cleared over everything ever ledgered, across the campaign's objectives."
               }
             ]
           },
-          "lastProgress": {
-            "type": "string",
-            "description": "When an entry last left the ledger, ISO 8601 — the stall clock's reading."
-          },
-          "regressions": {
-            "type": "number",
-            "allOf": [
-              {
-                "description": "How many times the count was allowed to go up."
+          "objectives": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "description": "The objective's id; its ledger is `<ledger>/<campaign>/<objective>.json`."
+                },
+                "phase": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "The phase naming the objective, or `null` for one no phase names — in window everywhere."
+                },
+                "initial": {
+                  "type": "number",
+                  "allOf": [
+                    {
+                      "description": "Holdouts recorded as each sector entered the window, summed."
+                    }
+                  ]
+                },
+                "allowed": {
+                  "type": "number",
+                  "allOf": [
+                    {
+                      "description": "Holdouts added since by `objectives concede` or a re-baseline, each with a concession."
+                    }
+                  ]
+                },
+                "count": {
+                  "type": "number",
+                  "allOf": [
+                    {
+                      "description": "Holdouts in the ledger now, every sector summed."
+                    }
+                  ]
+                },
+                "cleared": {
+                  "type": "number",
+                  "allOf": [
+                    {
+                      "description": "Holdouts removed by `objectives clear` because they stopped firing."
+                    }
+                  ]
+                },
+                "closed": {
+                  "type": "number",
+                  "allOf": [
+                    {
+                      "description": "Holdouts still firing when a sector left the window — not progress."
+                    }
+                  ]
+                },
+                "progress": {
+                  "type": "number",
+                  "allOf": [
+                    {
+                      "description": "`1 - count / (initial + allowed - closed)`: how much of everything ever ledgered has been paid down."
+                    }
+                  ]
+                },
+                "lastCleared": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "When a holdout last left the ledger, ISO 8601 — the stall clock's reading; `null` with no ledger."
+                },
+                "concessions": {
+                  "type": "number",
+                  "allOf": [
+                    {
+                      "description": "How many times a count was allowed to go up."
+                    }
+                  ]
+                },
+                "complete": {
+                  "type": "boolean",
+                  "description": "No holdouts remain."
+                },
+                "ledgered": {
+                  "type": "boolean",
+                  "description": "Whether a ledger exists. An objective with none has been declared and not yet cleared."
+                }
+              },
+              "required": [
+                "id",
+                "phase",
+                "initial",
+                "allowed",
+                "count",
+                "cleared",
+                "closed",
+                "progress",
+                "lastCleared",
+                "concessions",
+                "complete",
+                "ledgered"
+              ],
+              "additionalProperties": false
+            },
+            "description": "Every objective, in manifest order."
+          },
+          "phases": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "description": "The phase's id."
+                },
+                "defined": {
+                  "type": "boolean",
+                  "description": "Whether the phase names criteria. An open phase has only an intent, and is last."
+                },
+                "sectors": {
+                  "type": "number",
+                  "allOf": [
+                    {
+                      "description": "How many sectors are derived to stand at this phase."
+                    }
+                  ]
+                }
+              },
+              "required": [
+                "id",
+                "defined",
+                "sectors"
+              ],
+              "additionalProperties": false
+            },
+            "description": "The ladder, in order, with how many sectors stand at each phase."
+          },
+          "sectors": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "description": "The sector's identity, as its perimeter names it."
+                },
+                "phase": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "The phase the sector is derived to stand at, or `null` when it is past the last one."
+                },
+                "reached": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "The furthest phase the sector's record says it has reached; `null` before its first `clear`."
+                },
+                "files": {
+                  "type": "number",
+                  "allOf": [
+                    {
+                      "description": "How many files the sector claims."
+                    }
+                  ]
+                },
+                "residue": {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "number"
+                  },
+                  "description": "One dimension per objective in window for the sector: its holdouts there, never summed."
+                },
+                "stalled": {
+                  "type": "boolean",
+                  "description": "Holdouts remain for the sector and nothing has been cleared, attested or noted within `staleAfter`."
+                }
+              },
+              "required": [
+                "name",
+                "phase",
+                "reached",
+                "files",
+                "residue",
+                "stalled"
+              ],
+              "additionalProperties": false
+            },
+            "description": "Every sector the perimeter births, by name."
+          },
+          "legacy": {
+            "type": "object",
+            "properties": {
+              "files": {
+                "type": "number",
+                "allOf": [
+                  {
+                    "description": "Files in the scope no sector claims."
+                  }
+                ]
+              },
+              "holdouts": {
+                "type": "number",
+                "allOf": [
+                  {
+                    "description": "Holdouts in the legacy, under the first phase's objectives — where a holdout moved out of a sector lands."
+                  }
+                ]
               }
-            ]
+            },
+            "required": [
+              "files",
+              "holdouts"
+            ],
+            "additionalProperties": false,
+            "description": "The unclaimed remainder of the scope, which stands at the first phase and is not a sink."
+          },
+          "plan": {
+            "type": "object",
+            "properties": {
+              "refined": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Phases refined since the last `clear`: an open phase that gained criteria, or a new one. Free."
+              },
+              "changed": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Defined phases whose definition changed since the last `clear` — what a reviewer reads every time."
+              },
+              "unreceipted": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Changed phases carrying no new concession; `check` fails on them."
+              }
+            },
+            "required": [
+              "refined",
+              "changed",
+              "unreceipted"
+            ],
+            "additionalProperties": false,
+            "description": "What changed in the plan, refinements and changes apart."
           },
           "stalled": {
             "type": "boolean",
-            "description": "Entries remain and `lastProgress` is older than the campaign's `staleAfter`."
+            "description": "Holdouts remain and nothing has been cleared, attested or noted within the campaign's `staleAfter`."
           },
           "complete": {
             "type": "boolean",
-            "description": "No entries remain."
+            "description": "No holdouts remain in any objective."
           },
           "onComplete": {
             "type": "string",
@@ -729,18 +973,18 @@
           },
           "ledgered": {
             "type": "boolean",
-            "description": "Whether a ledger exists. A campaign with none has been declared and not yet initialised."
+            "description": "Whether every objective has a ledger."
           }
         },
         "required": [
           "id",
-          "initial",
-          "allowed",
           "count",
-          "fixed",
           "progress",
-          "lastProgress",
-          "regressions",
+          "objectives",
+          "phases",
+          "sectors",
+          "legacy",
+          "plan",
           "stalled",
           "complete",
           "onComplete",

package/src/core/structure.ts

@@ -333,9 +333,11 @@ export const structureRulesFailingTheirProbe = (
 
   const layoutOnly = { ...structure, parity: [] };
   const reported = (file: string): ReadonlyArray<string> =>
-    evaluateStructure(layoutOnly, { exists: () => true, readText: () => null }, file).map(
-      (violation) => violation.ruleName,
-    );
+    evaluateStructure(
+      layoutOnly,
+      { exists: () => true, readText: () => null, list: () => [] },
+      file,
+    ).map((violation) => violation.ruleName);
 
   for (const rule of structure.folders) {
     // A folder that admits any name claims its folder but states no policy, so

package/src/domain/architecture-config.ts

@@ -4,7 +4,7 @@ import * as Schema from "effect/Schema";
 // matched against a repo-relative, forward-slash path — the same vocabulary
 // dependency-cruiser rules are written in, so a rule ported from there keeps its
 // pattern character-for-character. A list matches when ANY member matches.
-const PatternList = Schema.Union([Schema.String, Schema.Array(Schema.String)]);
+export const PatternList = Schema.Union([Schema.String, Schema.Array(Schema.String)]);
 
 // An import edge is a violation when the importer matches `from` (and not
 // `fromNot`) AND the resolved target matches `to` (and not `toNot`). Omitting
@@ -99,7 +99,7 @@ export const ExportFix = Schema.Literals(["subpath-namespace-import"]);
 // Which binding form an import site used. A rule that fences off a factory
 // function cares about `named`; one steering people to namespace subpath imports
 // cares that `named` was used at all.
-const BindingKind = Schema.Literals(["named", "default", "namespace"]);
+export const BindingKind = Schema.Literals(["named", "default", "namespace"]);
 
 // `source`, when present, is a snippet the loading adapter parses: the probe
 // then holds only if a binding named `symbol` comes out of the parser and the
@@ -164,7 +164,7 @@ export const DeclarationKind = Schema.Literals([
 // identifiers (the hooks a tier may reach for). Which declarations a `members`
 // rule speaks to is `declares`' to say, so the vocabulary carries no language's
 // split between types and values.
-const MemberSubject = Schema.Literals(["members", "calls"]);
+export const MemberSubject = Schema.Literals(["members", "calls"]);
 
 // `source`, when present, is a snippet the loading adapter parses: the probe
 // then holds only if a site named `name` comes out of the parser and the rule
@@ -295,177 +295,6 @@ export const GraphConfig = Schema.Struct({
   reach: Schema.optionalKey(Schema.Array(GraphReachRule)),
 });
 
-// A campaign: a migration tracked as an object in the repository. Where a
-// rule says what may never happen, a campaign names a pattern the code is
-// moving away from, ledgers every place it still occurs, and refuses to let
-// the count go up unrecorded. Lowered from the manifest's `campaigns` list
-// with its globs resolved; the detector below is what the evaluator compiles.
-
-// What a hit is: a whole file, a named declaration in it, or one matched
-// expression. The unit decides what a term from another level means (a
-// file-level term in a declaration campaign is a filter; a declaration-level
-// term in a file campaign is existential) and what the fingerprint anchors on.
-export const CampaignUnit = Schema.Literals(["file", "declaration", "match"]);
-
-// The detector's leaf terms. Every pattern is a regular-expression source,
-// as everywhere else in this config; the manifest writes globs and lowering
-// translates them. Each term answers at one level — `path`, `imports`,
-// `requires`, `content` and a boolean `fn` about the file; `exports` and
-// `members` about a declaration; `syntax` and a listing `fn` about a match.
-const PathTerm = Schema.Struct({
-  file: PatternList,
-  fileNot: Schema.optionalKey(PatternList),
-  // With `convention`: which capture group of `file` holds the name being
-  // judged, and the shape it must have for the term to hold.
-  subject: Schema.optionalKey(Schema.Finite),
-  convention: Schema.optionalKey(Schema.String),
-});
-export type PathTerm = (typeof PathTerm)["Type"];
-
-const ImportsTerm = Schema.Struct({
-  // Where an edge of the file must resolve to: a path pattern, a package
-  // name, or a builtin. Holds when at least one edge does.
-  resolves: ImportProbeTarget,
-  // Names that must be pulled across that edge; omit for any binding.
-  symbols: Schema.optionalKey(Schema.Array(Schema.String)),
-});
-export type ImportsTerm = (typeof ImportsTerm)["Type"];
-
-const ExportsTerm = Schema.Struct({
-  name: Schema.optionalKey(PatternList),
-  kinds: Schema.optionalKey(Schema.Array(BindingKind)),
-  declares: Schema.optionalKey(Schema.Array(DeclarationKind)),
-  reexport: Schema.optionalKey(Schema.Boolean),
-});
-export type ExportsTerm = (typeof ExportsTerm)["Type"];
-
-const MembersTerm = Schema.Struct({
-  subject: MemberSubject,
-  name: Schema.optionalKey(PatternList),
-  in: Schema.optionalKey(PatternList),
-  declares: Schema.optionalKey(Schema.Array(DeclarationKind)),
-});
-export type MembersTerm = (typeof MembersTerm)["Type"];
-
-const ContentTerm = Schema.Struct({ regex: Schema.String });
-type ContentTerm = (typeof ContentTerm)["Type"];
-
-// How a metavariable of a syntax rule is narrowed: by the text it captured,
-// or by what the identifier at its root is bound to — the module it was
-// imported from and the name it was imported as.
-const BindingNarrowing = Schema.Struct({
-  resolves: ImportProbeTarget,
-  member: Schema.optionalKey(Schema.Array(Schema.String)),
-});
-
-const CaptureNarrowing = Schema.Struct({
-  regex: Schema.optionalKey(Schema.String),
-  binding: Schema.optionalKey(BindingNarrowing),
-});
-
-const SyntaxTerm = Schema.Struct({
-  // The engine's rule object, carried opaquely: the matcher validates it.
-  rule: Schema.Unknown,
-  where: Schema.optionalKey(Schema.Record(Schema.String, CaptureNarrowing)),
-});
-export type SyntaxTerm = (typeof SyntaxTerm)["Type"];
-
-// A pattern no parser of ours sees, reported by another program: a type
-// error, another linter's finding. Exactly one of `command` (run from the
-// repository root, once per process) and `file` (written by an earlier
-// step), each a list — the manifest's one string lowered to a list of one —
-// read as one report. Each diagnostic on a file is a match anchored on the
-// declaration at its position, keyed by its code and a hash of its message.
-export const ReportFormat = Schema.Literals(["tsc", "eslint", "oxlint", "regex"]);
-
-const ReportTerm = Schema.Struct({
-  command: Schema.optionalKey(Schema.Array(Schema.String)),
-  file: Schema.optionalKey(Schema.Array(Schema.String)),
-  format: ReportFormat,
-  // `regex` only: named groups `file`, `line`, and optionally `column`,
-  // `code`, `message`.
-  pattern: Schema.optionalKey(Schema.String),
-  // The codes the term speaks to; omit for every one.
-  codes: Schema.optionalKey(Schema.Array(Schema.String)),
-  codesNot: Schema.optionalKey(Schema.Array(Schema.String)),
-});
-export type ReportTerm = (typeof ReportTerm)["Type"];
-
-export type Detector =
-  | { readonly all: ReadonlyArray<Detector> }
-  | { readonly any: ReadonlyArray<Detector> }
-  | { readonly not: Detector }
-  | { readonly path: PathTerm }
-  | { readonly imports: ImportsTerm }
-  | { readonly exports: ExportsTerm }
-  | { readonly members: MembersTerm }
-  | { readonly requires: ReadonlyArray<string> }
-  | { readonly content: ContentTerm }
-  | { readonly syntax: SyntaxTerm }
-  | { readonly report: ReportTerm }
-  // `module#export`, resolved by the host before the policy loads.
-  | { readonly fn: string };
-
-const DetectorRef = Schema.suspend((): Schema.Codec<Detector> => Detector);
-
-export const Detector = Schema.Union([
-  Schema.Struct({ all: Schema.Array(DetectorRef) }),
-  Schema.Struct({ any: Schema.Array(DetectorRef) }),
-  Schema.Struct({ not: DetectorRef }),
-  Schema.Struct({ path: PathTerm }),
-  Schema.Struct({ imports: ImportsTerm }),
-  Schema.Struct({ exports: ExportsTerm }),
-  Schema.Struct({ members: MembersTerm }),
-  Schema.Struct({ requires: Schema.Array(Schema.String) }),
-  Schema.Struct({ content: ContentTerm }),
-  Schema.Struct({ syntax: SyntaxTerm }),
-  Schema.Struct({ report: ReportTerm }),
-  Schema.Struct({ fn: Schema.String }),
-]);
-
-// One diagnostic a probe stands in for, positions one-based as a tool
-// prints them.
-export const ProbeDiagnostic = Schema.Struct({
-  line: Schema.Finite,
-  column: Schema.optionalKey(Schema.Finite),
-  code: Schema.optionalKey(Schema.String),
-  message: Schema.optionalKey(Schema.String),
-});
-
-// A source the campaign is proven against: the path it would have, its text
-// when a term needs one, the target of each of its edges (in place of the live
-// resolver), the files beside it (in place of the file system) and the
-// diagnostics reported on it (in place of the report source).
-export const CampaignProbe = Schema.Struct({
-  path: Schema.String,
-  source: Schema.optionalKey(Schema.String),
-  edges: Schema.optionalKey(Schema.Record(Schema.String, ImportProbeTarget)),
-  files: Schema.optionalKey(Schema.Array(Schema.String)),
-  report: Schema.optionalKey(Schema.Array(ProbeDiagnostic)),
-});
-
-export const CampaignRule = Schema.Struct({
-  // `campaign/<id>`, the rule name a violation carries.
-  name: Schema.String,
-  id: Schema.String,
-  title: Schema.optionalKey(Schema.String),
-  // The `how`: what a reader at a hit does about it.
-  message: Schema.String,
-  why: Schema.String,
-  owner: Schema.optionalKey(Schema.String),
-  scope: PatternList,
-  unit: CampaignUnit,
-  detect: Detector,
-  probes: Schema.Struct({
-    fires: Schema.Array(CampaignProbe),
-    ignores: Schema.Array(CampaignProbe),
-  }),
-  // Milliseconds without progress after which the campaign is stalled.
-  staleAfter: Schema.Finite,
-  // What `check` demands once the count is zero: keep the campaign as a
-  // guard against recurrence, or remove it from the manifest.
-  onComplete: Schema.Literals(["keep", "remove"]),
-});
 
 const PathProbe = Schema.Struct({ path: Schema.String });
 
@@ -559,12 +388,6 @@ export type StructureRoot = (typeof StructureRoot)["Type"];
 export type StructureFolder = (typeof StructureFolder)["Type"];
 export type StructureParity = (typeof StructureParity)["Type"];
 export type StructureNaming = (typeof StructureNaming)["Type"];
-export type CampaignUnit = (typeof CampaignUnit)["Type"];
-export type CampaignProbe = (typeof CampaignProbe)["Type"];
-export type ProbeDiagnostic = (typeof ProbeDiagnostic)["Type"];
-export type ReportFormat = (typeof ReportFormat)["Type"];
-export type CampaignRule = (typeof CampaignRule)["Type"];
-export type CaptureNarrowing = (typeof CaptureNarrowing)["Type"];
 
 // The file pattern an open folder's layout rule carries: it admits any name,
 // so it claims the folder without policing it. Coverage counts it apart.