@oscaner-skills/cdd-engine 4.10.0 → 4.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -184,10 +184,10 @@ export const FIX_DISPOSITIONS_EMPTY_INPUT = "the requesting review carrier carri
184
184
  * by summary text. Booked soft: the round is judged, and the ledger says the key it
185
185
  * used. No carrier migration — present facts only. */
186
186
  export const FIX_DISPOSITIONS_LEGACY_KEYS = "the requesting review carrier carries no finding `id` — the dispositions were matched by summary text, the legacy key";
187
- /** The legacy-record observation — no requesting carrier is locatable, so the
188
- * judgment is skipped visibly (reading the gap as an empty input set would restore
189
- * an always-passing criterion). */
190
- export const FIX_DISPOSITIONS_UNRECORDED = "the requesting review round records no carrierPath and the route carried no --reviews path — the disposition judgment is skipped";
187
+ /** The legacy-record observation — the requesting round resolves no carrier and the
188
+ * route handed none over, so the judgment is skipped visibly (reading the gap as an
189
+ * empty input set would restore an always-passing criterion). */
190
+ export const FIX_DISPOSITIONS_UNRECORDED = "the requesting review round resolves no carrier and the route carried no --reviews path — the disposition judgment is skipped";
191
191
  /**
192
192
  * FixDispositions — the fix criterion: the round is done when its work carrier's
193
193
  * `dispositions` cover every finding of the requesting review carrier (design spec
@@ -214,32 +214,29 @@ export const FIX_DISPOSITIONS_UNRECORDED = "the requesting review round records
214
214
  * answers from the carrier, never from the diff.
215
215
  */
216
216
  export class FixDispositions {
217
- /** The requesting carrier's path — the LATEST attempt of the same-cycle review of the
218
- * SAME key (the row's records are already the key's), the record whose digest the
219
- * checked read compares against; a legacy record without `carrierPath` falls back to
220
- * the route's `--reviews` path. */
221
- static requesterPathOf(records, cycle, reviewsPath) {
222
- return _b.#requesterOf(records, cycle)?.carrierPath ?? reviewsPath;
223
- }
224
217
  /** Read the requesting carrier's input set (the findings, deduped by disposition
225
218
  * key in carrier order). The read is synchronous on purpose: the input is ONE small
226
219
  * carrier, and the dispatch face already reads its small inputs synchronously at
227
220
  * the same seam.
228
221
  *
222
+ * The PATH arrives from the caller (`CompletionContext.reviewsPath`) — the ledger's
223
+ * single resolution of the same-cycle review record's carrier identity, or the
224
+ * route's `--reviews` flag. A null path is `unrecorded`: the round recorded no
225
+ * carrier and the route handed none over, so the judgment is skipped visibly.
226
+ *
229
227
  * Every path resolves against `repoRoot`, never `process.cwd()`: the engine runs
230
- * from a subdirectory too, `--reviews` arrives repoRoot-relative and a record's
231
- * `carrierPath` arrives absolute — both must land on the one basis (`RepoRoot`'s
232
- * rule). The reported `path` is the resolved one, so a failure names a real file.
228
+ * from a subdirectory too, `--reviews` arrives repoRoot-relative and the resolved
229
+ * carrier path is absolute — both must land on the one basis (`RepoRoot`'s rule).
230
+ * The reported `path` is the resolved one, so a failure names a real file.
233
231
  *
234
232
  * P31 §2.2 — the read is the ONE checked carrier read (`CarrierIntegrity.read`):
235
233
  * the requesting round's recorded digest decides ok / mismatch, so a tampered
236
234
  * input throws instead of being judged as if the round had written those bytes. */
237
235
  static requesterInputOf(records, cycle, reviewsPath, repoRoot) {
238
- const requester = _b.#requesterOf(records, cycle);
239
- const declared = requester?.carrierPath ?? reviewsPath;
240
- if (declared === null)
236
+ if (reviewsPath === null)
241
237
  return { kind: "unrecorded" };
242
- const target = path.resolve(repoRoot, declared);
238
+ const requester = _b.#requesterOf(records, cycle);
239
+ const target = path.resolve(repoRoot, reviewsPath);
243
240
  let carrier;
244
241
  try {
245
242
  // P31 §2.2 — the input carrier is read through the ONE checked seam: the
@@ -287,13 +284,10 @@ export class FixDispositions {
287
284
  .reduce((newest, record) => newest === undefined || record.attempt >= newest.attempt ? record : newest, undefined);
288
285
  }
289
286
  /** The digest the requesting review round recorded — read off the SAME record
290
- * `requesterPathOf` selects. Null when that record declared no path (the legacy
291
- * `--reviews` fallback carries no digest, so the read performs no comparison) or when
292
- * the record predates the digest column. */
287
+ * `#requesterOf` selects. Null when the record predates the digest column: the
288
+ * read performs no comparison (present facts). */
293
289
  static #requesterDigestOf(record) {
294
- if (record === undefined || record.carrierPath === null)
295
- return null;
296
- return record.carrierDigest ?? null;
290
+ return record?.carrierDigest ?? null;
297
291
  }
298
292
  /** The carrier's `dispositions` map — null when the slot is absent or not an
299
293
  * object (the criterion's own shape refusal; the schema only pins the slot type). */
@@ -354,10 +348,7 @@ export class FixDispositions {
354
348
  #ownRefusal(ctx) {
355
349
  const carrier = ctx.carrier;
356
350
  if (carrier === null || typeof carrier !== "object" || Array.isArray(carrier)) {
357
- const at = ctx.record.carrierPath;
358
- return this.#hard(at === null
359
- ? "the fix round persisted no work carrier and recorded no carrier path"
360
- : `the fix round persisted no work carrier at ${at}`);
351
+ return this.#hard("the fix round persisted no work carrier — the round identity resolves none");
361
352
  }
362
353
  if (_b.dispositionsOf(carrier) === null) {
363
354
  return this.#hard("the fix carrier declares no `dispositions` object — every requesting finding owes a fixed/rejected row");
@@ -83,6 +83,30 @@ export class MarkdownPrimitives {
83
83
  // ---------------------------------------------------------------------------
84
84
  // the DocType base — parse + projection consumption + chain root
85
85
  // ---------------------------------------------------------------------------
86
+ /**
87
+ * The document-syntax rejection — a structural break of a document's OWN grammar
88
+ * (a reserved task section declared twice today), thrown by the parse face and
89
+ * materialized as a `Finding` by the judgment face. It carries the three faces a
90
+ * finding needs (the anchored field, the one-line message and the actionable
91
+ * fix), so the consumer never re-derives them from a message string. It sits
92
+ * beside the `DocType` base because the parse face is its only thrower: a
93
+ * doc-type's grammar break is a value, never a bare `Error`.
94
+ */
95
+ export class DocSyntaxError extends Error {
96
+ /** The anchored field the break sits on (an anchor token or a section name). */
97
+ field;
98
+ /** The one-line finding message — what is structurally wrong. */
99
+ message;
100
+ /** The actionable fix. */
101
+ fix;
102
+ constructor(field, message, fix) {
103
+ super(message);
104
+ this.name = "DocSyntaxError";
105
+ this.field = field;
106
+ this.message = message;
107
+ this.fix = fix;
108
+ }
109
+ }
86
110
  /**
87
111
  * The abstract doc-type base. Each subclass binds its registry-derived projection
88
112
  * face (slices + shape) and implements parse — pure structural extraction into a
@@ -250,24 +250,27 @@ export class LedgerRuleBase {
250
250
  return { path: ctx.path, field, message, fix, kind: this.name };
251
251
  }
252
252
  }
253
- /** closed-wave-fits-depends-on-layers — a closed wave stays inside one DependsOn layer.
254
- * The wave's members must share ONE layer of the plan's topological decomposition;
255
- * a wave spanning two layers was dispatched against a plan whose edges moved under
256
- * the closed ledgers. The read is a SUBSET one: a wave whose members all sit in one
257
- * layer fits even when it does not fill that layer (`{2}` against `[{1},{2,3}]` is
258
- * green) — the append-wave dispatch relies on the same liberal read. */
253
+ /** closed-wave-fits-depends-on-layers — an OPEN wave stays inside one DependsOn layer.
254
+ * The rule reads the ledger's open waves alone: a closed wave is settled history whose
255
+ * layer fit was judged at its own dispatch, so a later plan edit never retro-flags it —
256
+ * only a wave still dispatchable can be corrected by the plan itself. An open wave's
257
+ * members must share ONE layer of the plan's topological decomposition; a wave spanning
258
+ * two layers was dispatched against a plan whose edges moved under the open ledgers.
259
+ * The read is a SUBSET one: a wave whose members all sit in one layer fits even when it
260
+ * does not fill that layer (`{2}` against `[{1},{2,3}]` is green) — the append-wave
261
+ * dispatch relies on the same liberal read. */
259
262
  export class LedgerLayeringRule extends LedgerRuleBase {
260
263
  name = "closed-wave-fits-depends-on-layers";
261
264
  evaluate(ctx, ledger) {
262
265
  const findings = [];
263
- for (const wave of ledger.closedWaves) {
266
+ for (const wave of ledger.openWaves) {
264
267
  if (wave.length === 0)
265
268
  continue;
266
269
  const fits = ledger.layers.some((layer) => wave.every((id) => layer.includes(id)));
267
270
  if (fits)
268
271
  continue;
269
272
  const layers = ledger.layers.map((layer) => `{${layer.join(",")}}`).join(" ");
270
- findings.push(this.finding(ctx, "closed Waves", `the closed wave {${wave.join(",")}} spans more than one DependsOn layer (${layers})`, "keep a wave on one topological layer — add the missing DependsOn edges so the batch is one layer"));
273
+ findings.push(this.finding(ctx, "open Waves", `the open wave {${wave.join(",")}} spans more than one DependsOn layer (${layers})`, "keep a wave on one topological layer — add the missing DependsOn edges so the batch is one layer"));
271
274
  }
272
275
  return findings;
273
276
  }
@@ -7,9 +7,10 @@
7
7
  // index over the declared strategy set — zero switch-case, zero hand-written
8
8
  // judgment branches in this module (the plan's coordinator semantics: the
9
9
  // polymorphic strategy family judges, the coordinator assembles).
10
+ var _a;
10
11
  import { Words } from "../face/words.js";
11
12
  import { declaredRegistries } from "./declare.js";
12
- import { docTypeParsers } from "./doc.js";
13
+ import { DocSyntaxError, docTypeParsers } from "./doc.js";
13
14
  import { NodeFs } from "./invariants.js";
14
15
  import { MarkdownTree } from "./markdown-tree.js";
15
16
  import { DOC_KEYS, Projector } from "./project.js";
@@ -53,7 +54,7 @@ export class Contract {
53
54
  /** The row source — the ONE canonicalize seam (split + canonicalize once). */
54
55
  #rowSource;
55
56
  constructor() {
56
- this.#strategies = Contract.policy();
57
+ this.#strategies = _a.policy();
57
58
  this.#projector = new Projector(declaredRegistries);
58
59
  this.#translator = new Translator(new Words());
59
60
  this.#rowSource = new RowSource(this.#translator);
@@ -83,7 +84,18 @@ export class Contract {
83
84
  * and JudgeContext.head (§2.2's delivery seam — the chain facts the head carries
84
85
  * are the same record the invariants judge). The source stays intact. */
85
86
  validate(input) {
86
- const context = this.#contextOf(input);
87
+ return this.#docFindings(input);
88
+ }
89
+ /** The doc-scope judgment body — the context construction (the ONLY caught step)
90
+ * plus every declared strategy of the input's doc key. */
91
+ #docFindings(input) {
92
+ let context;
93
+ try {
94
+ context = this.#contextOf(input);
95
+ }
96
+ catch (error) {
97
+ return [_a.#syntaxFinding(input, error)];
98
+ }
87
99
  const findings = [];
88
100
  for (const strategy of this.#strategies[input.docKey]) {
89
101
  findings.push(...strategy.evaluate(context));
@@ -95,7 +107,18 @@ export class Contract {
95
107
  * `scope: "ledger"` declaration applicable to the input's doc key. Two arguments,
96
108
  * one judgment — the doc-scope rules never run here (and vice versa). */
97
109
  validateLedger(input, ledger) {
98
- const context = this.#contextOf(input);
110
+ return this.#ledgerFindings(input, ledger);
111
+ }
112
+ /** The ledger-scope judgment body — the context construction (the ONLY caught
113
+ * step) plus every declared `scope: "ledger"` rule of the input's doc key. */
114
+ #ledgerFindings(input, ledger) {
115
+ let context;
116
+ try {
117
+ context = this.#contextOf(input);
118
+ }
119
+ catch (error) {
120
+ return [_a.#syntaxFinding(input, error)];
121
+ }
99
122
  const findings = [];
100
123
  for (const declaration of RULE_REGISTRY) {
101
124
  if (declaration.scope !== "ledger")
@@ -107,6 +130,23 @@ export class Contract {
107
130
  }
108
131
  return findings;
109
132
  }
133
+ /** The document-syntax face of a judgment — the parse face throws a typed
134
+ * `DocSyntaxError`, the judgment materializes exactly ONE Finding bound to the
135
+ * contract path (never a registered rule, never a new gate). The catch wraps the
136
+ * `#contextOf` call ALONE (spec §2.2's seam): it never catches the strategy loop,
137
+ * so a `DocSyntaxError` from a strategy is a programming break that rethrows
138
+ * instead of discarding the findings this judgment already collected. */
139
+ static #syntaxFinding(input, error) {
140
+ if (!(error instanceof DocSyntaxError))
141
+ throw error;
142
+ return {
143
+ path: input.path,
144
+ field: error.field,
145
+ message: error.message,
146
+ fix: error.fix,
147
+ kind: "doc-syntax",
148
+ };
149
+ }
110
150
  /** The assembled judgment context — the shared split/parse/translate seam of both
111
151
  * entries (one context construction, one canonicalize pass). */
112
152
  #contextOf(input) {
@@ -135,3 +175,4 @@ export class Contract {
135
175
  };
136
176
  }
137
177
  }
178
+ _a = Contract;
@@ -43,6 +43,17 @@ import { DOC_TYPE_VALUES } from "./declare.js";
43
43
  * The judge's policy composition and the board's declaration domain read THIS
44
44
  * tuple; a value drift is impossible (one array). */
45
45
  export const DOC_KEYS = DOC_TYPE_VALUES;
46
+ /** The task-heading accessor — a module-scope `this`-typed function expression, so
47
+ * every projection carries the SAME function instance (the projection-identity
48
+ * assertion compares two independent projections with `toEqual`, which compares
49
+ * function values by identity) while each call still reads that projection's own
50
+ * `slices` (the registry slice table stays the one fact source). An arrow would
51
+ * bind no `this`; a hand-written `RegExp` here would declare a second copy.
52
+ * `check:no-bare-functions` only matches line-leading `function`, so the const
53
+ * binding is inside the discipline. */
54
+ const taskHeadingPatternOf = function () {
55
+ return this.slices.find((slice) => slice.anchor === "### Task N:")?.valuePattern;
56
+ };
46
57
  /**
47
58
  * The projection carrier — the registered registries' single derivation surface.
48
59
  * Constructed on the declared registries (the domain's `declaredRegistries`),
@@ -195,7 +206,7 @@ export class Projector {
195
206
  : new RegExp(element.valuePattern),
196
207
  });
197
208
  }
198
- return { docType: registry.docType, slices };
209
+ return { docType: registry.docType, slices, taskHeadingPattern: taskHeadingPatternOf };
199
210
  }
200
211
  /** Project one registry onto its anchor-lexicon face. */
201
212
  #projectDocTokens(registry) {
@@ -8,6 +8,7 @@
8
8
  // The parse is split out of the tree facade (markdown-tree.ts) so the block
9
9
  // grammar, the document index and the selector engine each own one concern.
10
10
  import { TASK_ID_VALUE_PATTERN } from "./declare.js";
11
+ import { DocSyntaxError } from "./doc.js";
11
12
  /**
12
13
  * TaskBlockGrammar — the task-block structural constants. They live with the ONE
13
14
  * block parse, so the grammar has exactly one home.
@@ -276,8 +277,9 @@ export class TaskBlocksParser {
276
277
  for (const field of block.fields) {
277
278
  if (!TaskBlockGrammar.RESERVED.includes(field.key))
278
279
  continue;
280
+ const anchor = `#### ${field.key}`;
279
281
  if (seen.has(field.key)) {
280
- throw new Error(`task ${block.id} carries the reserved section "#### ${field.key}" more than once`);
282
+ throw new DocSyntaxError(anchor, `task ${block.id} carries the reserved section "${anchor}" more than once`, `keep one "${anchor}" section per task block — merge the duplicate bodies into the first one`);
281
283
  }
282
284
  seen.add(field.key);
283
285
  }