@oscaner-skills/cdd-engine 3.0.0 → 3.1.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.
Files changed (143) hide show
  1. package/{src-next/bin.ts → dist/bin.js} +18 -21
  2. package/dist/contract/declare.js +998 -0
  3. package/dist/contract/doc.js +565 -0
  4. package/dist/contract/frontmatter.js +209 -0
  5. package/dist/contract/home-extractors.js +379 -0
  6. package/dist/contract/invariants.js +1030 -0
  7. package/dist/contract/judge.js +109 -0
  8. package/dist/contract/lint.js +206 -0
  9. package/dist/contract/project.js +371 -0
  10. package/dist/contract/skill-anatomy.js +156 -0
  11. package/dist/contract/translate.js +85 -0
  12. package/dist/face/artifacts.js +189 -0
  13. package/dist/face/board-view.js +522 -0
  14. package/dist/face/capsule.js +149 -0
  15. package/dist/face/cli.js +893 -0
  16. package/dist/face/declare.js +241 -0
  17. package/dist/face/gate.js +158 -0
  18. package/dist/face/graph-view.js +66 -0
  19. package/dist/face/host.js +211 -0
  20. package/dist/face/lifecycle.js +702 -0
  21. package/dist/face/preview.js +136 -0
  22. package/dist/face/projection.js +259 -0
  23. package/dist/face/route-render.js +162 -0
  24. package/dist/face/termination.js +504 -0
  25. package/dist/face/words.js +258 -0
  26. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  27. package/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
  28. package/dist/infra/git.js +37 -0
  29. package/dist/infra/process.js +22 -0
  30. package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
  31. package/dist/infra/runtime.js +85 -0
  32. package/dist/infra/workspace.js +276 -0
  33. package/dist/render/brief.js +82 -0
  34. package/dist/render/issue-body.js +129 -0
  35. package/dist/render/skeleton.js +434 -0
  36. package/dist/render/templates.js +520 -0
  37. package/dist/session/faces.js +38 -0
  38. package/dist/session/graph.js +309 -0
  39. package/dist/session/handoff-schema.js +295 -0
  40. package/dist/session/ledger.js +762 -0
  41. package/dist/session/next.js +211 -0
  42. package/dist/session/preflight.js +194 -0
  43. package/dist/session/round-naming.js +73 -0
  44. package/dist/session/run.js +453 -0
  45. package/dist/session/state.js +8 -0
  46. package/dist/session/wave.js +92 -0
  47. package/package.json +5 -5
  48. package/src-next/__tests__/bin.test.ts +0 -128
  49. package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
  50. package/src-next/__tests__/floor.guard.test.ts +0 -69
  51. package/src-next/__tests__/issue-body.guard.test.ts +0 -66
  52. package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
  53. package/src-next/__tests__/smoke.integration.test.ts +0 -185
  54. package/src-next/__tests__/support/strip-comments.ts +0 -99
  55. package/src-next/__tests__/zero-dep.test.ts +0 -94
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
  58. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
  59. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
  62. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
  63. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
  64. package/src-next/contract/__tests__/declare.test.ts +0 -481
  65. package/src-next/contract/__tests__/doc.test.ts +0 -527
  66. package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
  67. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
  68. package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
  69. package/src-next/contract/__tests__/judge.test.ts +0 -1111
  70. package/src-next/contract/__tests__/lint.test.ts +0 -324
  71. package/src-next/contract/__tests__/project.test.ts +0 -460
  72. package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
  73. package/src-next/contract/__tests__/translate.test.ts +0 -96
  74. package/src-next/contract/declare.ts +0 -1071
  75. package/src-next/contract/doc.ts +0 -816
  76. package/src-next/contract/frontmatter.ts +0 -233
  77. package/src-next/contract/home-extractors.ts +0 -397
  78. package/src-next/contract/invariants.ts +0 -1413
  79. package/src-next/contract/judge.ts +0 -151
  80. package/src-next/contract/lint.ts +0 -239
  81. package/src-next/contract/project.ts +0 -656
  82. package/src-next/contract/skill-anatomy.ts +0 -301
  83. package/src-next/contract/translate.ts +0 -113
  84. package/src-next/face/__tests__/board-view.test.ts +0 -1151
  85. package/src-next/face/__tests__/capsule.test.ts +0 -300
  86. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
  87. package/src-next/face/__tests__/cli.test.ts +0 -4897
  88. package/src-next/face/__tests__/face.test.ts +0 -289
  89. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  90. package/src-next/face/__tests__/host.test.ts +0 -24
  91. package/src-next/face/__tests__/install-rows.guard.test.ts +0 -58
  92. package/src-next/face/__tests__/negation.ts +0 -6
  93. package/src-next/face/__tests__/preview.test.ts +0 -374
  94. package/src-next/face/__tests__/projection.test.ts +0 -303
  95. package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
  96. package/src-next/face/__tests__/termination.test.ts +0 -650
  97. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  98. package/src-next/face/artifacts.ts +0 -248
  99. package/src-next/face/board-view.ts +0 -652
  100. package/src-next/face/capsule.ts +0 -163
  101. package/src-next/face/cli.ts +0 -1028
  102. package/src-next/face/declare.ts +0 -323
  103. package/src-next/face/gate.ts +0 -171
  104. package/src-next/face/graph-view.ts +0 -74
  105. package/src-next/face/host.ts +0 -302
  106. package/src-next/face/lifecycle.ts +0 -725
  107. package/src-next/face/preview.ts +0 -151
  108. package/src-next/face/projection.ts +0 -285
  109. package/src-next/face/route-render.ts +0 -185
  110. package/src-next/face/termination.ts +0 -573
  111. package/src-next/face/words.ts +0 -314
  112. package/src-next/infra/__tests__/infra.test.ts +0 -333
  113. package/src-next/infra/__tests__/root.test.ts +0 -56
  114. package/src-next/infra/git.ts +0 -39
  115. package/src-next/infra/process.ts +0 -34
  116. package/src-next/infra/runtime.ts +0 -132
  117. package/src-next/infra/workspace.ts +0 -322
  118. package/src-next/render/__tests__/render.test.ts +0 -550
  119. package/src-next/render/__tests__/skeleton.test.ts +0 -684
  120. package/src-next/render/brief.ts +0 -121
  121. package/src-next/render/issue-body.ts +0 -162
  122. package/src-next/render/skeleton.ts +0 -502
  123. package/src-next/render/templates.ts +0 -645
  124. package/src-next/session/__tests__/graph.test.ts +0 -277
  125. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  126. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  127. package/src-next/session/__tests__/ledger.test.ts +0 -745
  128. package/src-next/session/__tests__/next.test.ts +0 -460
  129. package/src-next/session/__tests__/preflight.test.ts +0 -545
  130. package/src-next/session/__tests__/round-naming.test.ts +0 -142
  131. package/src-next/session/__tests__/run.test.ts +0 -1026
  132. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  133. package/src-next/session/__tests__/wave.test.ts +0 -476
  134. package/src-next/session/faces.ts +0 -110
  135. package/src-next/session/graph.ts +0 -411
  136. package/src-next/session/handoff-schema.ts +0 -373
  137. package/src-next/session/ledger.ts +0 -1076
  138. package/src-next/session/next.ts +0 -293
  139. package/src-next/session/preflight.ts +0 -271
  140. package/src-next/session/round-naming.ts +0 -84
  141. package/src-next/session/run.ts +0 -610
  142. package/src-next/session/state.ts +0 -30
  143. package/src-next/session/wave.ts +0 -139
@@ -1,151 +0,0 @@
1
- // packages/cdd-engine/src-next/contract/judge.ts
2
- // T4 — the single interpreter's coordinator (design spec §2.1): the Contract
3
- // class's validate() is the ONLY entry for structural judgment. It loads the
4
- // parse context through the doc-type parsers (doc.ts — pure parse), composes the
5
- // per-doc-key invariant strategy set (invariants.ts) as declared data, runs every
6
- // strategy in order, and aggregates the findings. Judgment dispatch is a record
7
- // index over the declared strategy set — zero switch-case, zero hand-written
8
- // judgment branches in this module (the plan's coordinator semantics: the
9
- // polymorphic strategy family judges, the coordinator assembles).
10
-
11
- import { Words } from "../face/words.ts";
12
- import { declaredRegistries } from "./declare.ts";
13
- import type { ParsedDoc } from "./doc.ts";
14
- import { docTypeParsers } from "./doc.ts";
15
- import { FrontMatterExtractor } from "./frontmatter.ts";
16
- import type { DocFs, Finding, Invariant, JudgeContext } from "./invariants.ts";
17
- import {
18
- ContinuityInvariant,
19
- CrossDocChainInvariant,
20
- CrosslinkInvariant,
21
- DomainInvariant,
22
- FileExistenceInvariant,
23
- HollowInvariant,
24
- LinkShapeInvariant,
25
- NodeFs,
26
- OrderInvariant,
27
- PresenceInvariant,
28
- ResidueInvariant,
29
- SectionScopedDomainInvariant,
30
- SelfBoundedInvariant,
31
- SiblingScanInvariant,
32
- UniquenessInvariant,
33
- } from "./invariants.ts";
34
- import type { DocKey } from "./project.ts";
35
- import { DOC_KEYS, Projector } from "./project.ts";
36
- import { Translator } from "./translate.ts";
37
-
38
- /** The judgment input — the doc's identity, content and the seam closures. */
39
- export interface ContractInput {
40
- /** The doc-type record key of the document under judgment. */
41
- docKey: DocKey;
42
- /** The document's file path (message attribution + the doc's own dir). */
43
- path: string;
44
- /** The document's raw content. */
45
- content: string;
46
- /** The workspace/repo root the doc chain resolves against. */
47
- root: string;
48
- /** The dispatch phase id — enables the face-④ phase-registration check. */
49
- phaseId?: string;
50
- /** Pre-parsed chain/sibling docs (path → parsed record). */
51
- chainDocs?: ReadonlyMap<string, ParsedDoc>;
52
- /** The filesystem seam (defaults to node:fs). */
53
- fs?: DocFs;
54
- }
55
-
56
- /**
57
- * The contract coordinator — the interpreter's single face. One instance; the
58
- * strategy set is stateless (each strategy reads its judgment data from the
59
- * context), so construction is cheap and validates compose safely.
60
- *
61
- * The P7 structure-plane canonicalize seam (design spec §2.1) + the T6 front-matter
62
- * delivery seam (§2.2): the Contract self-holds a Translator, and validate()
63
- * canonicalizes EVERY body line once at the row source — the normalized view
64
- * shared by parse and JudgeContext.lines. The split order is RAW-first: the raw
65
- * content resolves its front-matter head BEFORE any canonicalize (front matter is
66
- * data — the canonicalize view would silently rewrite registered Chinese aliases
67
- * inside header values), then the post-fence body lines canonicalize and the SAME
68
- * typed head rides into parse(lines, head) and JudgeContext.head. Every
69
- * valuePattern judgment face (presence occurrenceLines · domain carrierLines ·
70
- * section-scoped · crosslink) matches the view, so the legacy Chinese charter
71
- * markers (the doc-arch decision-group / upstream-endorsements leaves) match their
72
- * English canonical element patterns through the recognition face — never a second
73
- * hand-written zh pattern. The view is never written back: the source document
74
- * stays byte-identical and the original lines remain in input.content.
75
- */
76
- export class Contract {
77
- /** The per-doc-key policy sets — the declared composition of the strategy family.
78
- * All thirteen strategies are registry-driven and judge every doc type, so the
79
- * per-key sets are the same ordered family; the record keying is what a future
80
- * per-type ordering/selection change would carry. */
81
- readonly #strategies: Record<DocKey, readonly Invariant[]>;
82
- /** The projection carrier — the derived parse/skeleton faces the judgment reads. */
83
- readonly #projector: Projector;
84
- /** The row-source translator — the canonicalize seam carrier. One instance over
85
- * the same locale word table the rest of the plane reads (the recognition face
86
- * of the P7 translation layer); embedded like the projector, so the production
87
- * construction points (`new Contract()`) stay argument-free. */
88
- readonly #translator: Translator;
89
-
90
- constructor() {
91
- this.#strategies = Contract.#buildPolicy();
92
- this.#projector = new Projector(declaredRegistries);
93
- this.#translator = new Translator(new Words());
94
- }
95
-
96
- /** validate(doc) — split, parse, compose, run, aggregate. The single judgment entry.
97
- * The RAW content resolves its front-matter head first (the data plane — never
98
- * canonicalized); the post-fence body lines canonicalize ONCE at the row source
99
- * (the normalized view), and the SAME typed head rides into parse(lines, head)
100
- * and JudgeContext.head (§2.2's delivery seam — the chain facts the head carries
101
- * are the same record the invariants judge). The source stays intact. */
102
- validate(input: ContractInput): Finding[] {
103
- const { head, body } = FrontMatterExtractor.split(input.content);
104
- const lines = body.split("\n").map((line) => this.#translator.canonicalize(line));
105
- const parsed = docTypeParsers[input.docKey].parse(lines, head);
106
- const context: JudgeContext = {
107
- docKey: input.docKey,
108
- parsed,
109
- head,
110
- lines,
111
- path: input.path,
112
- root: input.root,
113
- slices: this.#projector.slices()[input.docKey],
114
- shape: this.#projector.shape()[input.docKey],
115
- registries: declaredRegistries,
116
- phaseId: input.phaseId,
117
- chainDocs: input.chainDocs,
118
- fs: input.fs ?? new NodeFs(),
119
- };
120
- const findings: Finding[] = [];
121
- for (const strategy of this.#strategies[input.docKey]) {
122
- findings.push(...strategy.evaluate(context));
123
- }
124
- return findings;
125
- }
126
-
127
- /** The declared strategy composition — one ordered family set per doc key. */
128
- static #buildPolicy(): Record<DocKey, readonly Invariant[]> {
129
- const family: readonly Invariant[] = [
130
- new PresenceInvariant(),
131
- new UniquenessInvariant(),
132
- new DomainInvariant(),
133
- new CrosslinkInvariant(),
134
- new OrderInvariant(),
135
- new ContinuityInvariant(),
136
- new ResidueInvariant(),
137
- new HollowInvariant(),
138
- new SelfBoundedInvariant(),
139
- new LinkShapeInvariant(),
140
- new FileExistenceInvariant(),
141
- new SiblingScanInvariant(),
142
- new CrossDocChainInvariant(),
143
- new SectionScopedDomainInvariant(),
144
- ];
145
- const policy = {} as Record<DocKey, readonly Invariant[]>;
146
- for (const key of DOC_KEYS) {
147
- policy[key] = family;
148
- }
149
- return policy;
150
- }
151
- }
@@ -1,239 +0,0 @@
1
- // packages/cdd-engine/src-next/contract/lint.ts
2
- // T5 — the reference lint WARN pass (design spec §2.3): an independent observation
3
- // face that runs at the dispatch gate, never part of the judgment definition.
4
- // The reference vocabulary it applies is the derived projection (project.ts —
5
- // `Projector.reference()`, the per-element reference rows) — zero self-copied
6
- // reference patterns. The lint consumes the SAME doc.ts parse record the dispatch
7
- // and the graph read (parse once, reuse everywhere), so its observations are
8
- // anchored on the parsed task blocks and the chain root, never a re-scan of raw
9
- // text.
10
- //
11
- // The WARN families:
12
- // · missing-edge suspect (plan) — a backward `Task N` / `T<N>` prose reference
13
- // inside a task's Objective/Acceptance value that has no matching
14
- // `- **DependsOn**:` declaration. The graph's edge classes never fire here:
15
- // unregistered targets (missing-id) and self-edges (self-loop) stay silent —
16
- // a suspect is always an existing task with a lower id whose edge was simply
17
- // not declared (forward references are legal — no contradiction class).
18
- //
19
- // The cross-doc label-drift observation (Class-B `parent-program:` label vs
20
- // target basename) retired with the ChainLink label face at the front-matter flip
21
- // (T6) — the chain facts ride the typed head scalars, a link label is not a fact.
22
- //
23
- // Every warning is a Warn — a WARN-only observation, never a Finding, never a
24
- // BLOCK. Module-level exports are types / the class — zero behavior-carrying
25
- // bare functions (the plan's zero-bare-function discipline).
26
-
27
- import { declaredRegistries } from "./declare.ts";
28
- import type { ParsedDoc, PlanParsed, TaskBlock } from "./doc.ts";
29
- import { MarkdownPrimitives } from "./doc.ts";
30
- import type { ReferenceEntry, ReferenceProjection } from "./project.ts";
31
- import { Projector } from "./project.ts";
32
-
33
- /** One reference-lint warning — a WARN-only observation, never a judge Finding. */
34
- export interface Warn {
35
- /** The doc file the warning refers to. */
36
- path: string;
37
- /** The anchored surface the warning anchors to (a `Task N` block or a field name). */
38
- field: string;
39
- /** The one-line warning message — what the observation suspects. */
40
- message: string;
41
- /** The actionable fix. */
42
- fix: string;
43
- /** The lint family that produced the warning. */
44
- kind: "reference-lint";
45
- }
46
-
47
- /** The lint input — the document's path + the shared doc.ts parse instance (the
48
- * doc type rides the parsed record's docType, never a re-typed key — no field
49
- * the pass does not read). */
50
- export interface LintInput {
51
- /** The document's file path (message attribution). */
52
- path: string;
53
- /** The shared parsed record — the same instance the dispatch and the graph read. */
54
- parsed: ParsedDoc;
55
- }
56
-
57
- /**
58
- * The reference-lint pass — the WARN observation face over the derived reference
59
- * vocabulary. One instance; every reference pattern it applies is read from the
60
- * projection, never re-typed. The prose scan surface (Objective / Acceptance) is
61
- * a scanning-semantics decision, tied to the vocabulary by a construction guard
62
- * that fails loudly if the plan registry renames either prose field.
63
- */
64
- export class LintPass extends MarkdownPrimitives {
65
- /** The derived reference vocabulary — the single source the lint applies. */
66
- readonly #reference: ReferenceProjection;
67
- /** The derived `Task prose reference` token pattern (global — matchAll over prose lines). */
68
- readonly #proseToken: RegExp;
69
- /** The derived `DependsOn id` value pattern (whole-token — the declared-edge values). */
70
- readonly #depIdToken: RegExp;
71
- /** The prose-owning task fields of the plan — the scanning-semantics surface. */
72
- readonly #proseFieldKeys: readonly string[] = ["Objective", "Acceptance"];
73
-
74
- constructor() {
75
- super();
76
- this.#reference = new Projector(declaredRegistries).reference();
77
- const planEntries = this.#reference.plan.entries;
78
- this.#proseToken = new RegExp(this.#valuePatternOf(planEntries, "Task prose reference"), "g");
79
- this.#depIdToken = new RegExp(this.#valuePatternOf(planEntries, "DependsOn id"));
80
- for (const key of this.#proseFieldKeys) {
81
- this.#valuePatternOf(planEntries, `**${key}**`);
82
- }
83
- }
84
-
85
- /** run — the single observation entry: one Warn per offending surface. */
86
- run(input: LintInput): Warn[] {
87
- const warns: Warn[] = [];
88
- if (input.parsed.docType === "plan") {
89
- warns.push(...this.#missingEdgeWarns(input, input.parsed));
90
- warns.push(...this.#numberingAdvisories(input, input.parsed));
91
- warns.push(...this.#transitiveAdvisories(input, input.parsed));
92
- }
93
- return warns;
94
- }
95
-
96
- // -------------------------------------------------------------------------
97
- // the missing-edge suspect scan (plan)
98
- // -------------------------------------------------------------------------
99
-
100
- /** One WARN per task block whose prose references an existing lower task with no edge. */
101
- #missingEdgeWarns(input: LintInput, parsed: PlanParsed): Warn[] {
102
- const warns: Warn[] = [];
103
- const registered = new Set(parsed.taskBlocks.map((block) => block.id));
104
- for (const block of parsed.taskBlocks) {
105
- const declared = this.#declaredEdgesOf(block);
106
- const suspects = this.#suspectRefsOf(block, declared, registered);
107
- if (suspects.length === 0) continue;
108
- const list = suspects.map((id) => `Task ${id}`).join(" and ");
109
- warns.push({
110
- path: input.path,
111
- field: `Task ${block.id}`,
112
- message: `task ${block.id} prose-references ${list} with no matching **DependsOn** declaration — a suspected missing edge (WARN: the author's intent is authoritative, never a gate)`,
113
- fix: `declare the edge in the block's **DependsOn** line, or treat the reference as prose (task ${list})`,
114
- kind: "reference-lint",
115
- });
116
- }
117
- return warns;
118
- }
119
-
120
- /** One WARN per forward reference (a dep on a higher-numbered task) — the numbering
121
- * read-order advisory (T24: legal after the anti-dependency gate retired, but a
122
- * hint that the numbering no longer follows the topological reading order). */
123
- #numberingAdvisories(input: LintInput, parsed: PlanParsed): Warn[] {
124
- const warns: Warn[] = [];
125
- for (const block of parsed.taskBlocks) {
126
- for (const dep of this.#declaredEdgesOf(block)) {
127
- if (dep <= block.id) continue;
128
- warns.push({
129
- path: input.path,
130
- field: `Task ${block.id}`,
131
- message: `task ${block.id} depends on the higher-numbered Task ${dep} — legal (forward references), but the numbering no longer follows the topological reading order; consider renumbering (advisory only)`,
132
- fix: "renumber the pair for a linear reading order, or keep the forward dependency — the engine derives waves from **DependsOn** alone",
133
- kind: "reference-lint",
134
- });
135
- }
136
- }
137
- return warns;
138
- }
139
-
140
- /** One WARN per transitively-redundant declaration (a dep d reachable from another
141
- * declared dep) — the direct-only advisory: redundant edges are harmless (the
142
- * waves derive over the closure) but clutter the display, so the engine hints
143
- * the author to declare direct prerequisites only. */
144
- #transitiveAdvisories(input: LintInput, parsed: PlanParsed): Warn[] {
145
- const warns: Warn[] = [];
146
- const declared = new Map<number, Set<number>>();
147
- for (const block of parsed.taskBlocks) declared.set(block.id, this.#declaredEdgesOf(block));
148
- const reachOf = (from: number): Set<number> => {
149
- const seen = new Set<number>();
150
- const stack = [...(declared.get(from) ?? [])];
151
- while (stack.length > 0) {
152
- const current = stack.pop()!;
153
- if (seen.has(current)) continue;
154
- seen.add(current);
155
- stack.push(...(declared.get(current) ?? []));
156
- }
157
- return seen;
158
- };
159
- const reach = new Map<number, Set<number>>();
160
- for (const id of declared.keys()) reach.set(id, reachOf(id));
161
- for (const block of parsed.taskBlocks) {
162
- for (const dep of declared.get(block.id) ?? []) {
163
- const redundantVia = [...(declared.get(block.id) ?? [])].find(
164
- (other) => other !== dep && (reach.get(other) ?? new Set()).has(dep),
165
- );
166
- if (redundantVia === undefined) continue;
167
- warns.push({
168
- path: input.path,
169
- field: `Task ${block.id}`,
170
- message: `task ${block.id} depends on Task ${dep}, already reachable via declared dependency Task ${redundantVia} — declare direct prerequisites only (advisory: redundant edges are inert for the wave derivation, but clutter the graph)`,
171
- fix: `drop ${dep} from the block's **DependsOn** (or keep it — the engine reduces the display, the closure is unchanged)`,
172
- kind: "reference-lint",
173
- });
174
- }
175
- }
176
- return warns;
177
- }
178
-
179
- /** The block's declared edge ids — read from its **DependsOn** VALUE PREFIX only
180
- * (the first `(`/`(` truncates — a trailing parenthetical's numbers are prose,
181
- * never an edge; the same §3.8 value-domain contract the graph's extractor keeps). */
182
- #declaredEdgesOf(block: TaskBlock): Set<number> {
183
- const edges = new Set<number>();
184
- const field = block.fields.find((entry) => entry.key === "DependsOn");
185
- if (field === undefined) return edges;
186
- for (const line of field.lines) {
187
- const prefix = line.split(/[((]/)[0]!;
188
- for (const token of prefix.split(/[,\s]+/)) {
189
- if (this.#depIdToken.test(token.trim())) edges.add(Number(token.trim()));
190
- }
191
- }
192
- return edges;
193
- }
194
-
195
- /** The backward prose references of a block that exist, are undeclared and are not a
196
- * code-span citation — the missing-edge suspects. */
197
- #suspectRefsOf(
198
- block: TaskBlock,
199
- declared: ReadonlySet<number>,
200
- registered: ReadonlySet<number>,
201
- ): number[] {
202
- const suspects: number[] = [];
203
- const seenId = new Set<number>();
204
- for (const field of block.fields) {
205
- if (!this.#proseFieldKeys.includes(field.key)) continue;
206
- for (const line of field.lines) {
207
- const prose = this.#withoutCodeSpans(line);
208
- for (const match of prose.matchAll(this.#proseToken)) {
209
- const id = Number(match[1]);
210
- if (id >= block.id) continue; // forward / self — undeclareable, never a suspect
211
- if (!registered.has(id)) continue; // missing-id — the graph's class, never a suspect
212
- if (declared.has(id) || seenId.has(id)) continue;
213
- seenId.add(id);
214
- suspects.push(id);
215
- }
216
- }
217
- }
218
- return suspects.sort((a, b) => a - b);
219
- }
220
-
221
- /** The line with its backtick-delimited inline code spans removed (a span cites a symbol, never prose). */
222
- #withoutCodeSpans(line: string): string {
223
- return line.replace(/`+[^`\n]*`+/g, "");
224
- }
225
-
226
- // -------------------------------------------------------------------------
227
- // construction helpers
228
- // -------------------------------------------------------------------------
229
-
230
- /** The value pattern of a registered reference entry — a lookup that fails
231
- * loudly when the declaration renames an anchor the lint consumes. */
232
- #valuePatternOf(entries: readonly ReferenceEntry[], anchor: string): string {
233
- const entry = entries.find((row) => row.anchor === anchor);
234
- if (entry === undefined) {
235
- throw new Error(`reference-lint requires the registered reference entry "${anchor}"`);
236
- }
237
- return entry.valuePattern ?? "";
238
- }
239
- }