@oscaner-skills/cdd-engine 1.0.0 → 2.0.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.
- package/README.md +9 -8
- package/README.zh-CN.md +9 -8
- package/package.json +15 -22
- package/src-next/__tests__/bin.test.ts +128 -0
- package/src-next/__tests__/smoke.integration.test.ts +202 -0
- package/src-next/__tests__/zero-dep.test.ts +134 -0
- package/src-next/bin.ts +61 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +238 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +153 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +173 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +89 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +225 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +155 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +175 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +85 -0
- package/src-next/contract/__tests__/declare.test.ts +242 -0
- package/src-next/contract/__tests__/doc.test.ts +358 -0
- package/src-next/contract/__tests__/judge.test.ts +873 -0
- package/src-next/contract/__tests__/lint.test.ts +314 -0
- package/src-next/contract/__tests__/project.test.ts +419 -0
- package/src-next/contract/__tests__/translate.test.ts +96 -0
- package/src-next/contract/declare.ts +983 -0
- package/src-next/contract/doc.ts +753 -0
- package/src-next/contract/invariants.ts +1268 -0
- package/src-next/contract/judge.ts +142 -0
- package/src-next/contract/lint.ts +275 -0
- package/src-next/contract/project.ts +596 -0
- package/src-next/contract/skill-anatomy.ts +273 -0
- package/src-next/contract/translate.ts +113 -0
- package/src-next/face/__tests__/board-view.test.ts +948 -0
- package/src-next/face/__tests__/capsule.test.ts +276 -0
- package/src-next/face/__tests__/channel-closure.guard.test.ts +102 -0
- package/src-next/face/__tests__/cli.test.ts +4643 -0
- package/src-next/face/__tests__/face.test.ts +289 -0
- package/src-next/face/__tests__/graph-view.test.ts +61 -0
- package/src-next/face/__tests__/host.test.ts +24 -0
- package/src-next/face/__tests__/negation.ts +6 -0
- package/src-next/face/__tests__/projection.test.ts +301 -0
- package/src-next/face/__tests__/sync-runner.test.ts +70 -0
- package/src-next/face/__tests__/words.guard.test.ts +93 -0
- package/src-next/face/artifacts.ts +195 -0
- package/src-next/face/board-view.ts +662 -0
- package/src-next/face/capsule.ts +149 -0
- package/src-next/face/cli.ts +819 -0
- package/src-next/face/declare.ts +326 -0
- package/src-next/face/gate.ts +170 -0
- package/src-next/face/graph-view.ts +74 -0
- package/src-next/face/host.ts +326 -0
- package/src-next/face/lifecycle.ts +700 -0
- package/src-next/face/projection.ts +282 -0
- package/src-next/face/route-render.ts +160 -0
- package/src-next/face/words.ts +296 -0
- package/src-next/infra/__tests__/infra.test.ts +287 -0
- package/src-next/infra/config.ts +42 -0
- package/src-next/infra/git.ts +39 -0
- package/src-next/infra/process.ts +34 -0
- package/src-next/infra/runtime.ts +185 -0
- package/src-next/infra/workspace.ts +232 -0
- package/src-next/render/__tests__/render.test.ts +499 -0
- package/src-next/render/__tests__/skeleton.test.ts +466 -0
- package/src-next/render/brief.ts +121 -0
- package/src-next/render/issue-body.ts +159 -0
- package/src-next/render/skeleton.ts +437 -0
- package/src-next/render/templates.ts +650 -0
- package/src-next/session/__tests__/graph.test.ts +270 -0
- package/src-next/session/__tests__/handoff-plane.guard.test.ts +48 -0
- package/src-next/session/__tests__/handoff-schema.test.ts +310 -0
- package/src-next/session/__tests__/ledger.test.ts +744 -0
- package/src-next/session/__tests__/next.test.ts +368 -0
- package/src-next/session/__tests__/preflight.test.ts +491 -0
- package/src-next/session/__tests__/run.test.ts +1014 -0
- package/src-next/session/__tests__/wave-line-phase.guard.test.ts +49 -0
- package/src-next/session/__tests__/wave.test.ts +469 -0
- package/src-next/session/faces.ts +110 -0
- package/src-next/session/graph.ts +411 -0
- package/src-next/session/handoff-schema.ts +373 -0
- package/src-next/session/ledger.ts +1004 -0
- package/src-next/session/next.ts +192 -0
- package/src-next/session/preflight.ts +240 -0
- package/src-next/session/run.ts +606 -0
- package/src-next/session/state.ts +30 -0
- package/src-next/session/wave.ts +139 -0
- package/templates/report/issue-body.json +18 -20
- package/dist/chunks/branch.mjs +0 -480
- package/dist/chunks/docs.mjs +0 -253
- package/dist/chunks/task.mjs +0 -913
- package/dist/cli.mjs +0 -5457
- package/dist/documents/schema/add-phase-protocol.json +0 -126
- package/dist/documents/schema/overall.json +0 -361
- package/dist/documents/schema/phase-spec.json +0 -145
- package/dist/documents/schema/plan.json +0 -191
- package/dist/documents/schema/skill-anatomy.json +0 -233
- package/dist/resources/harness-registry.json +0 -49
- package/dist/shared/cdd-engine.liioziig.mjs +0 -184
- package/templates/engine-config.json +0 -302
- package/templates/schema/cache-profile-schema.json +0 -23
- package/templates/schema/docs-handoff-schema.json +0 -129
- package/templates/schema/task-handoff-schema.json +0 -332
- package/templates/template-contract.json +0 -231
|
@@ -0,0 +1,1268 @@
|
|
|
1
|
+
// packages/cdd-engine/src-next/contract/invariants.ts
|
|
2
|
+
// T4 — the invariant strategy class family (design spec §2.1): the single
|
|
3
|
+
// judgment face. Every structural judgment of the contract plane is one strategy:
|
|
4
|
+
// base nine — presence / uniqueness / domain / crosslink / order / continuity /
|
|
5
|
+
// residue / hollow / selfBounded;
|
|
6
|
+
// context — file-existence / sibling-scan / cross-doc-chain /
|
|
7
|
+
// section-scoped-domain (the four seam strategies that absorb the
|
|
8
|
+
// old doctype classes' contextual judgment — fourTableAudit,
|
|
9
|
+
// deviations, Class-A/B, effectiveWaves).
|
|
10
|
+
// Each strategy is one subclass of `abstract Invariant { evaluate(ctx) }`; the
|
|
11
|
+
// judgment data is always the declared registries + the derived parse face (never
|
|
12
|
+
// a hand-written structure prose). Judgment dispatch is the coordinator's
|
|
13
|
+
// data-driven per-doc-key composition (judge.ts) — zero switch-case here and zero
|
|
14
|
+
// exported behavior-carrying bare functions.
|
|
15
|
+
|
|
16
|
+
import { existsSync, readdirSync, readFileSync } from "node:fs";
|
|
17
|
+
import path from "node:path";
|
|
18
|
+
import type { ElementRegistry, RegistryElement } from "./declare.ts";
|
|
19
|
+
import type {
|
|
20
|
+
ChainLink,
|
|
21
|
+
DesignGroup,
|
|
22
|
+
OverallParsed,
|
|
23
|
+
ParsedDoc,
|
|
24
|
+
PhaseSpecParsed,
|
|
25
|
+
PlanParsed,
|
|
26
|
+
SectionBlock,
|
|
27
|
+
TaskBlock,
|
|
28
|
+
} from "./doc.ts";
|
|
29
|
+
import { MarkdownPrimitives } from "./doc.ts";
|
|
30
|
+
import type { DocKey, DocShape, DocSlices, ElementSlice } from "./project.ts";
|
|
31
|
+
|
|
32
|
+
// ---------------------------------------------------------------------------
|
|
33
|
+
// judgment records + the context
|
|
34
|
+
// ---------------------------------------------------------------------------
|
|
35
|
+
|
|
36
|
+
/** One contract finding — a single invariant violation, bound to a doc + field. */
|
|
37
|
+
export interface Finding {
|
|
38
|
+
/** The doc file the finding refers to. */
|
|
39
|
+
path: string;
|
|
40
|
+
/** The anchored field the finding refers to (an anchor token or a section name). */
|
|
41
|
+
field: string;
|
|
42
|
+
/** The one-line finding message (what is wrong). */
|
|
43
|
+
message: string;
|
|
44
|
+
/** The actionable fix. */
|
|
45
|
+
fix: string;
|
|
46
|
+
/** The invariant class name that produced the finding. */
|
|
47
|
+
kind: string;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** The filesystem seam the context-seam invariants read through (test-injectable). */
|
|
51
|
+
export interface DocFs {
|
|
52
|
+
/** Whether a path exists. */
|
|
53
|
+
exists(p: string): boolean;
|
|
54
|
+
/** The UTF-8 content of a path, or null when unreadable. */
|
|
55
|
+
read(p: string): string | null;
|
|
56
|
+
/** The entry names of a directory, or [] when unreadable. */
|
|
57
|
+
list(p: string): readonly string[];
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** The node:fs default — the production seam for file-existence / sibling scans. */
|
|
61
|
+
export class NodeFs implements DocFs {
|
|
62
|
+
exists(p: string): boolean {
|
|
63
|
+
return existsSync(p);
|
|
64
|
+
}
|
|
65
|
+
read(p: string): string | null {
|
|
66
|
+
try {
|
|
67
|
+
return readFileSync(p, "utf8");
|
|
68
|
+
} catch {
|
|
69
|
+
return null;
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
list(p: string): readonly string[] {
|
|
73
|
+
try {
|
|
74
|
+
return readdirSync(p);
|
|
75
|
+
} catch {
|
|
76
|
+
return [];
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** The judgment context — everything a strategy reads, assembled by the coordinator. */
|
|
82
|
+
export interface JudgeContext {
|
|
83
|
+
/** The doc-type record key of the document under judgment. */
|
|
84
|
+
docKey: DocKey;
|
|
85
|
+
/** The parsed structural record of the document. */
|
|
86
|
+
parsed: ParsedDoc;
|
|
87
|
+
/** The judged document's normalized content lines — the canonicalize view the
|
|
88
|
+
* row-source seam (Contract.validate) builds ONCE per judgment: every
|
|
89
|
+
* valuePattern / anchor-literal face (occurrenceLines · carrierLines ·
|
|
90
|
+
* anchorLines and the parsed records) matches the view. The view is never
|
|
91
|
+
* written back — the source document stays byte-identical. */
|
|
92
|
+
lines: readonly string[];
|
|
93
|
+
/** The document's file path (message attribution + the doc's own dir for links). */
|
|
94
|
+
path: string;
|
|
95
|
+
/** The workspace/repo root the doc chain resolves against. */
|
|
96
|
+
root: string;
|
|
97
|
+
/** The derived parse face of the judged doc type. */
|
|
98
|
+
slices: DocSlices;
|
|
99
|
+
/** The derived section skeleton of the judged doc type. */
|
|
100
|
+
shape: DocShape;
|
|
101
|
+
/** The four declared registries — the element-level judgment data. */
|
|
102
|
+
registries: {
|
|
103
|
+
"overall-spec": ElementRegistry;
|
|
104
|
+
plan: ElementRegistry;
|
|
105
|
+
"phase-spec": ElementRegistry;
|
|
106
|
+
"single-spec": ElementRegistry;
|
|
107
|
+
};
|
|
108
|
+
/** The dispatch phase id — enables the face-④ phase-registration check. */
|
|
109
|
+
phaseId?: string;
|
|
110
|
+
/** Pre-parsed chain/sibling docs (path → parsed record). */
|
|
111
|
+
chainDocs?: ReadonlyMap<string, ParsedDoc>;
|
|
112
|
+
/** The filesystem seam (defaults to node:fs). */
|
|
113
|
+
fs: DocFs;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
// ---------------------------------------------------------------------------
|
|
117
|
+
// the abstract strategy base
|
|
118
|
+
// ---------------------------------------------------------------------------
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* The abstract invariant — one strategy = one structural judgment. Subclasses
|
|
122
|
+
* implement evaluate(ctx) and read all judgment data from the declared registries
|
|
123
|
+
* + the parse face carried by the context. The base extends MarkdownPrimitives:
|
|
124
|
+
* the link/token/table-row parsers shared with the parse face live in one home
|
|
125
|
+
* (doc.ts), never re-declared here.
|
|
126
|
+
*/
|
|
127
|
+
export abstract class Invariant extends MarkdownPrimitives {
|
|
128
|
+
/** The invariant's name — the finding attribution label. */
|
|
129
|
+
abstract readonly name: string;
|
|
130
|
+
/** Run the strategy — the single evaluation entry. */
|
|
131
|
+
abstract evaluate(ctx: JudgeContext): Finding[];
|
|
132
|
+
|
|
133
|
+
/** The single finding-construction point. */
|
|
134
|
+
protected finding(ctx: JudgeContext, field: string, message: string, fix: string): Finding {
|
|
135
|
+
return { path: ctx.path, field, message, fix, kind: this.name };
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/** The judged doc type's declared registry. */
|
|
139
|
+
protected registry(ctx: JudgeContext): ElementRegistry {
|
|
140
|
+
return ctx.registries[ctx.docKey];
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/** The judged doc type's registered elements in registry order. */
|
|
144
|
+
protected elementsOf(ctx: JudgeContext): readonly RegistryElement[] {
|
|
145
|
+
return this.registry(ctx).elements;
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/** The slice of one registered anchor (undefined when the anchor is not registered here). */
|
|
149
|
+
protected sliceOf(ctx: JudgeContext, anchor: string): ElementSlice | undefined {
|
|
150
|
+
return ctx.slices.slices.find((slice) => slice.anchor === anchor);
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
/** Whether a line carries the element — the literal anchor or the declared value shape. */
|
|
154
|
+
protected lineCarries(slice: ElementSlice, line: string): boolean {
|
|
155
|
+
return line.includes(slice.anchor) || (slice.valuePattern?.test(line) ?? false);
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/** The lines carrying the element's anchor token literal. */
|
|
159
|
+
protected anchorLines(ctx: JudgeContext, anchor: string): readonly string[] {
|
|
160
|
+
return ctx.lines.filter((line) => line.includes(anchor));
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
/** The lines carrying the element (literal anchor or declared value shape). */
|
|
164
|
+
protected occurrenceLines(ctx: JudgeContext, slice: ElementSlice): readonly string[] {
|
|
165
|
+
return ctx.lines.filter((line) => this.lineCarries(slice, line));
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/** The lines that carry the element as a real structural occurrence — a line whose
|
|
169
|
+
* anchor only appears as a citation (a backticked code span, or a table cell of a
|
|
170
|
+
* non-table element) is not a carrier and is never judged as a value. */
|
|
171
|
+
protected carrierLines(ctx: JudgeContext, slice: ElementSlice): readonly string[] {
|
|
172
|
+
return ctx.lines.filter(
|
|
173
|
+
(line) => this.lineCarries(slice, line) && this.#isStructuralCarrier(line, slice),
|
|
174
|
+
);
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
#isStructuralCarrier(line: string, slice: ElementSlice): boolean {
|
|
178
|
+
if (this.#isTableRow(line) && slice.home !== "table") return false;
|
|
179
|
+
if (!line.includes(slice.anchor)) return true;
|
|
180
|
+
return !this.#everyAnchorMentionIsCodeSpan(line, slice.anchor);
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
#isTableRow(line: string): boolean {
|
|
184
|
+
const trimmed = line.trim();
|
|
185
|
+
return trimmed.startsWith("|") && trimmed.endsWith("|");
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/** Whether every literal anchor mention on the line stays inside a backtick code span. */
|
|
189
|
+
#everyAnchorMentionIsCodeSpan(line: string, anchor: string): boolean {
|
|
190
|
+
return !this.#withoutCodeSpans(line).includes(anchor);
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/** The line with its backtick-quoted region removed. A line's quoted content is
|
|
194
|
+
* the region between its FIRST and LAST backtick (inclusive) — ONE contiguous
|
|
195
|
+
* quoted fragment, the shape the doc prose actually uses: a simple `` `span` ``
|
|
196
|
+
* and a quoted command fragment with a NESTED citation (`` `read X + the plan's
|
|
197
|
+
* \`## Constraints\` (by the wave brief mirror)` ``) both read as one quoted region (the
|
|
198
|
+
* find-#8 gap: the old span-by-span strip left a nested citation naked after its
|
|
199
|
+
* opener got consumed by the outer span, judging quoted prose as a value). The
|
|
200
|
+
* tradeoff is pinned: a line carrying TWO separate backtick spans (`` `x` … `y` ``)
|
|
201
|
+
* also reads as ONE quoted region, so the mid-span prose between the spans is not
|
|
202
|
+
* judged (judge.test.ts pins this — an anchor quoted only between two adjacent
|
|
203
|
+
* spans stays invisible to the presence/domain rules; no enforced doc carries that
|
|
204
|
+
* shape). A zero- or one-tick line carries no quoted region (unbalanced — nothing
|
|
205
|
+
* to strip). */
|
|
206
|
+
#withoutCodeSpans(line: string): string {
|
|
207
|
+
const first = line.indexOf("`");
|
|
208
|
+
if (first === -1) return line;
|
|
209
|
+
const last = line.lastIndexOf("`");
|
|
210
|
+
if (first === last) return line;
|
|
211
|
+
return line.slice(0, first) + line.slice(last + 1);
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
/** The parsed overall record — when the judged doc is an overall. */
|
|
215
|
+
protected overall(ctx: JudgeContext): OverallParsed | null {
|
|
216
|
+
return ctx.docKey === "overall-spec" ? (ctx.parsed as OverallParsed) : null;
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
/** The parsed plan record — when the judged doc is a plan. */
|
|
220
|
+
protected plan(ctx: JudgeContext): PlanParsed | null {
|
|
221
|
+
return ctx.docKey === "plan" ? (ctx.parsed as PlanParsed) : null;
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
/** The parsed phase-spec record — when the judged doc is a phase-spec. */
|
|
225
|
+
protected phaseSpec(ctx: JudgeContext): PhaseSpecParsed | null {
|
|
226
|
+
return ctx.docKey === "phase-spec" ? (ctx.parsed as PhaseSpecParsed) : null;
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
/** The four-table section heading anchors of the overall (registry-declared). */
|
|
230
|
+
protected overallTableHeadings(ctx: JudgeContext): readonly string[] {
|
|
231
|
+
const headings = this.overall(ctx);
|
|
232
|
+
if (headings === null) return [];
|
|
233
|
+
const declared = ctx.registries["overall-spec"].elements
|
|
234
|
+
.filter((element) => element.home === "section" && element.anchor.startsWith("## "))
|
|
235
|
+
.map((element) => element.anchor);
|
|
236
|
+
return declared.filter((anchor) =>
|
|
237
|
+
["File paths", "Issue inventory", "Phase inventory", "Change history"].some((name) =>
|
|
238
|
+
anchor.includes(name),
|
|
239
|
+
),
|
|
240
|
+
);
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
// ---------------------------------------------------------------------------
|
|
245
|
+
// base nine
|
|
246
|
+
// ---------------------------------------------------------------------------
|
|
247
|
+
|
|
248
|
+
/** Home surfaces the presence invariant judges — the structural doc surface
|
|
249
|
+
* (table rows/columns/tokens are judged by hollow/section-scoped strategies). */
|
|
250
|
+
const PRESENCE_HOMES = new Set([
|
|
251
|
+
"header",
|
|
252
|
+
"section",
|
|
253
|
+
"facet",
|
|
254
|
+
"graph",
|
|
255
|
+
"task-block",
|
|
256
|
+
"task-field",
|
|
257
|
+
"task-step",
|
|
258
|
+
"design-body",
|
|
259
|
+
"conditional",
|
|
260
|
+
]);
|
|
261
|
+
|
|
262
|
+
/** presence — every required structural element of the declared registry must occur. */
|
|
263
|
+
export class PresenceInvariant extends Invariant {
|
|
264
|
+
readonly name = "presence";
|
|
265
|
+
|
|
266
|
+
evaluate(ctx: JudgeContext): Finding[] {
|
|
267
|
+
const findings: Finding[] = [];
|
|
268
|
+
for (const element of this.elementsOf(ctx)) {
|
|
269
|
+
if (element.presence !== "required") continue;
|
|
270
|
+
if (PRESENCE_HOMES.has(element.home) === false) continue;
|
|
271
|
+
const slice = this.sliceOf(ctx, element.anchor);
|
|
272
|
+
if (slice === undefined) continue;
|
|
273
|
+
if (this.#derivedPresenceHolds(ctx, slice)) continue;
|
|
274
|
+
if (this.occurrenceLines(ctx, slice).length === 0) {
|
|
275
|
+
findings.push(
|
|
276
|
+
this.finding(
|
|
277
|
+
ctx,
|
|
278
|
+
element.anchor,
|
|
279
|
+
`missing required element: ${element.anchor}`,
|
|
280
|
+
`add the "${element.anchor}" ${element.home} element to the document`,
|
|
281
|
+
),
|
|
282
|
+
);
|
|
283
|
+
}
|
|
284
|
+
}
|
|
285
|
+
findings.push(...this.taskFieldPresence(ctx));
|
|
286
|
+
return findings;
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/** A required surface whose occurrence is established by the parsed structure rather
|
|
290
|
+
* than a line scan — the plan's `Task id token` only ever appears inside the
|
|
291
|
+
* `### Task N:` headings, so it is present iff a task block exists. */
|
|
292
|
+
#derivedPresenceHolds(ctx: JudgeContext, slice: ElementSlice): boolean {
|
|
293
|
+
if (slice.home !== "task-block" || slice.anchor.startsWith("#")) return false;
|
|
294
|
+
return (this.plan(ctx)?.taskBlocks.length ?? 0) > 0;
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
/** The per-task-block required field keys — derived from the plan registry's
|
|
298
|
+
* task-field elements (the bold `**Key**` markers; the `File path token` and
|
|
299
|
+
* DependsOn-value leaves carry non-key anchors, and `Step action` lives on the
|
|
300
|
+
* task-step home). Single-source: a field key added to the registry is enforced
|
|
301
|
+
* per task block automatically. */
|
|
302
|
+
#requiredFieldKeys(ctx: JudgeContext): readonly string[] {
|
|
303
|
+
return this.elementsOf(ctx)
|
|
304
|
+
.filter(
|
|
305
|
+
(element) =>
|
|
306
|
+
element.home === "task-field" &&
|
|
307
|
+
element.anchor.startsWith("**") &&
|
|
308
|
+
element.anchor.endsWith("**"),
|
|
309
|
+
)
|
|
310
|
+
.map((element) => element.anchor.slice(2, -2));
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
/** The per-task-block field surface — every required task-field key of a plan. */
|
|
314
|
+
private taskFieldPresence(ctx: JudgeContext): Finding[] {
|
|
315
|
+
const data = this.plan(ctx);
|
|
316
|
+
if (data === null) return [];
|
|
317
|
+
const findings: Finding[] = [];
|
|
318
|
+
for (const block of data.taskBlocks) {
|
|
319
|
+
const keys = new Set(block.fields.map((field) => field.key));
|
|
320
|
+
for (const key of this.#requiredFieldKeys(ctx)) {
|
|
321
|
+
if (!keys.has(key)) {
|
|
322
|
+
findings.push(
|
|
323
|
+
this.finding(
|
|
324
|
+
ctx,
|
|
325
|
+
`**${key}**`,
|
|
326
|
+
`task ${block.id} carries no **${key}** field`,
|
|
327
|
+
`add the - **${key}**: line to ### Task ${block.id}:`,
|
|
328
|
+
),
|
|
329
|
+
);
|
|
330
|
+
}
|
|
331
|
+
}
|
|
332
|
+
}
|
|
333
|
+
return findings;
|
|
334
|
+
}
|
|
335
|
+
}
|
|
336
|
+
|
|
337
|
+
/** uniqueness — every identity-carrying surface registers exactly once. */
|
|
338
|
+
export class UniquenessInvariant extends Invariant {
|
|
339
|
+
readonly name = "uniqueness";
|
|
340
|
+
|
|
341
|
+
evaluate(ctx: JudgeContext): Finding[] {
|
|
342
|
+
const findings = [...this.headingUniqueness(ctx), ...this.derivedUniqueness(ctx)];
|
|
343
|
+
return findings;
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
/** Heading-style anchors: a duplicated heading line text is a duplicate registration. */
|
|
347
|
+
private headingUniqueness(ctx: JudgeContext): Finding[] {
|
|
348
|
+
const findings: Finding[] = [];
|
|
349
|
+
const seenLine = new Set<string>();
|
|
350
|
+
for (const element of this.elementsOf(ctx)) {
|
|
351
|
+
if (!element.anchor.startsWith("#")) continue;
|
|
352
|
+
const slice = this.sliceOf(ctx, element.anchor);
|
|
353
|
+
if (slice === undefined) continue;
|
|
354
|
+
for (const line of this.occurrenceLines(ctx, slice)) {
|
|
355
|
+
const trimmed = line.trim();
|
|
356
|
+
const key = `${element.anchor}::${trimmed}`;
|
|
357
|
+
if (seenLine.has(key)) {
|
|
358
|
+
findings.push(
|
|
359
|
+
this.finding(
|
|
360
|
+
ctx,
|
|
361
|
+
element.anchor,
|
|
362
|
+
`duplicate heading registration: ${trimmed}`,
|
|
363
|
+
`keep "${trimmed}" in exactly one place`,
|
|
364
|
+
),
|
|
365
|
+
);
|
|
366
|
+
}
|
|
367
|
+
seenLine.add(key);
|
|
368
|
+
}
|
|
369
|
+
}
|
|
370
|
+
return findings;
|
|
371
|
+
}
|
|
372
|
+
|
|
373
|
+
/** The derived identity rows: task ids, phase ids, change-history versions. */
|
|
374
|
+
private derivedUniqueness(ctx: JudgeContext): Finding[] {
|
|
375
|
+
const findings: Finding[] = [];
|
|
376
|
+
if (ctx.docKey === "plan") {
|
|
377
|
+
const seenIds = new Set<number>();
|
|
378
|
+
for (const block of this.plan(ctx)?.taskBlocks ?? []) {
|
|
379
|
+
if (seenIds.has(block.id)) {
|
|
380
|
+
findings.push(
|
|
381
|
+
this.finding(
|
|
382
|
+
ctx,
|
|
383
|
+
"### Task N:",
|
|
384
|
+
`duplicate task id: Task ${block.id} registers more than once`,
|
|
385
|
+
"keep each task id in exactly one task block",
|
|
386
|
+
),
|
|
387
|
+
);
|
|
388
|
+
}
|
|
389
|
+
seenIds.add(block.id);
|
|
390
|
+
}
|
|
391
|
+
}
|
|
392
|
+
if (ctx.docKey === "overall-spec") {
|
|
393
|
+
const data = this.overall(ctx);
|
|
394
|
+
if (data !== null) {
|
|
395
|
+
const seenPhases = new Set<string>();
|
|
396
|
+
for (const phase of data.chain.phases) {
|
|
397
|
+
const lower = phase.id.toLowerCase();
|
|
398
|
+
if (seenPhases.has(lower)) {
|
|
399
|
+
findings.push(
|
|
400
|
+
this.finding(
|
|
401
|
+
ctx,
|
|
402
|
+
"Phase inventory",
|
|
403
|
+
`duplicate phase registration: ${phase.id} registers more than once`,
|
|
404
|
+
"keep each phase id in exactly one Phase-inventory row",
|
|
405
|
+
),
|
|
406
|
+
);
|
|
407
|
+
}
|
|
408
|
+
seenPhases.add(lower);
|
|
409
|
+
}
|
|
410
|
+
const seenVersions = new Set<string>();
|
|
411
|
+
for (const row of data.tables["Change history"].rows) {
|
|
412
|
+
const version = this.#firstVersion(row[0] ?? "");
|
|
413
|
+
if (version !== null && seenVersions.has(version)) {
|
|
414
|
+
findings.push(
|
|
415
|
+
this.finding(
|
|
416
|
+
ctx,
|
|
417
|
+
"Change history",
|
|
418
|
+
`duplicate change-history version: ${version} registers more than once`,
|
|
419
|
+
"keep each lineage version in exactly one Change-history row",
|
|
420
|
+
),
|
|
421
|
+
);
|
|
422
|
+
}
|
|
423
|
+
if (version !== null) seenVersions.add(version);
|
|
424
|
+
}
|
|
425
|
+
}
|
|
426
|
+
}
|
|
427
|
+
return findings;
|
|
428
|
+
}
|
|
429
|
+
|
|
430
|
+
#firstVersion(text: string): string | null {
|
|
431
|
+
const match = text.match(/v\d+\.\d+/);
|
|
432
|
+
return match === null ? null : match[0];
|
|
433
|
+
}
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
/** domain — every value an anchor literal carries must conform to its declared shape. */
|
|
437
|
+
export class DomainInvariant extends Invariant {
|
|
438
|
+
readonly name = "domain";
|
|
439
|
+
|
|
440
|
+
evaluate(ctx: JudgeContext): Finding[] {
|
|
441
|
+
const findings: Finding[] = [];
|
|
442
|
+
for (const element of this.elementsOf(ctx)) {
|
|
443
|
+
const slice = this.sliceOf(ctx, element.anchor);
|
|
444
|
+
if (slice === undefined || slice.valuePattern === undefined) continue;
|
|
445
|
+
// The element is judged by the SHAPE of the lines that carry it structurally —
|
|
446
|
+
// a `**Status**: Draft` line must match its declared pattern. A prose citation
|
|
447
|
+
// (a backticked code-span mention, or a table cell of a non-table element) is
|
|
448
|
+
// not a carrier and is never judged as a value.
|
|
449
|
+
for (const line of this.carrierLines(ctx, slice)) {
|
|
450
|
+
if (!slice.valuePattern.test(line)) {
|
|
451
|
+
findings.push(
|
|
452
|
+
this.finding(
|
|
453
|
+
ctx,
|
|
454
|
+
element.anchor,
|
|
455
|
+
`value outside the declared domain: ${line.trim()}`,
|
|
456
|
+
`make the line match ${slice.valuePattern.source}`,
|
|
457
|
+
),
|
|
458
|
+
);
|
|
459
|
+
}
|
|
460
|
+
}
|
|
461
|
+
}
|
|
462
|
+
return findings;
|
|
463
|
+
}
|
|
464
|
+
}
|
|
465
|
+
|
|
466
|
+
/** crosslink — in-document reference resolution against the doc's own identity sets. */
|
|
467
|
+
export class CrosslinkInvariant extends Invariant {
|
|
468
|
+
readonly name = "crosslink";
|
|
469
|
+
|
|
470
|
+
evaluate(ctx: JudgeContext): Finding[] {
|
|
471
|
+
if (ctx.docKey === "overall-spec") return this.overallCrosslinks(ctx);
|
|
472
|
+
if (ctx.docKey === "plan") return this.planCrosslinks(ctx);
|
|
473
|
+
return [];
|
|
474
|
+
}
|
|
475
|
+
|
|
476
|
+
/** The overall's in-doc reference surfaces: issue rows + graph edges + dependency cells. */
|
|
477
|
+
private overallCrosslinks(ctx: JudgeContext): Finding[] {
|
|
478
|
+
const data = this.overall(ctx);
|
|
479
|
+
if (data === null) return [];
|
|
480
|
+
const findings: Finding[] = [];
|
|
481
|
+
const ids = new Set(data.chain.phases.map((phase) => phase.id.toLowerCase()));
|
|
482
|
+
// Issue-inventory rows: the Phase column must be a registered inventory id.
|
|
483
|
+
for (const row of data.tables["Issue inventory"].rows) {
|
|
484
|
+
const phaseCell = row[0]?.trim() ?? "";
|
|
485
|
+
if (phaseCell !== "" && !ids.has(phaseCell.toLowerCase())) {
|
|
486
|
+
findings.push(
|
|
487
|
+
this.finding(
|
|
488
|
+
ctx,
|
|
489
|
+
"Issue inventory",
|
|
490
|
+
`issue row phase ${JSON.stringify(phaseCell)} is not a Phase-inventory id`,
|
|
491
|
+
"set the Issue-inventory Phase column to a registered phase id",
|
|
492
|
+
),
|
|
493
|
+
);
|
|
494
|
+
}
|
|
495
|
+
}
|
|
496
|
+
// Graph edges: every from/to token must be a registered phase id.
|
|
497
|
+
for (const edge of data.graphEdges) {
|
|
498
|
+
if (!ids.has(edge.from.toLowerCase())) {
|
|
499
|
+
findings.push(
|
|
500
|
+
this.finding(
|
|
501
|
+
ctx,
|
|
502
|
+
"Dependency graph",
|
|
503
|
+
`graph edge from ${edge.from} is not a Phase-inventory id`,
|
|
504
|
+
`register ${edge.from} in the Phase inventory or fix the edge`,
|
|
505
|
+
),
|
|
506
|
+
);
|
|
507
|
+
}
|
|
508
|
+
if (!ids.has(edge.to.toLowerCase())) {
|
|
509
|
+
findings.push(
|
|
510
|
+
this.finding(
|
|
511
|
+
ctx,
|
|
512
|
+
"Dependency graph",
|
|
513
|
+
`graph edge to ${edge.to} is not a Phase-inventory id`,
|
|
514
|
+
`register ${edge.to} in the Phase inventory or fix the edge`,
|
|
515
|
+
),
|
|
516
|
+
);
|
|
517
|
+
}
|
|
518
|
+
}
|
|
519
|
+
// Phase-row dependency cells: every P-token must be a registered phase id.
|
|
520
|
+
for (const phase of data.chain.phases) {
|
|
521
|
+
for (const token of this.#phaseTokens(phase.dependencyCell)) {
|
|
522
|
+
if (!ids.has(token.toLowerCase())) {
|
|
523
|
+
findings.push(
|
|
524
|
+
this.finding(
|
|
525
|
+
ctx,
|
|
526
|
+
"Phase inventory",
|
|
527
|
+
`dependency of ${phase.id} references unregistered phase ${token}`,
|
|
528
|
+
`register ${token} in the Phase inventory or fix the dependency cell`,
|
|
529
|
+
),
|
|
530
|
+
);
|
|
531
|
+
}
|
|
532
|
+
}
|
|
533
|
+
}
|
|
534
|
+
return findings;
|
|
535
|
+
}
|
|
536
|
+
|
|
537
|
+
/** The plan's in-doc reference surfaces: the DependsOn ids — the single structural
|
|
538
|
+
* reference gate. Prose task mentions are NOT consumed here (T6): the WARN-only
|
|
539
|
+
* observation belongs to the reference-lint pass, never a hard finding. */
|
|
540
|
+
private planCrosslinks(ctx: JudgeContext): Finding[] {
|
|
541
|
+
const data = this.plan(ctx);
|
|
542
|
+
if (data === null) return [];
|
|
543
|
+
const findings: Finding[] = [];
|
|
544
|
+
const ids = new Set(data.taskBlocks.map((block) => block.id));
|
|
545
|
+
for (const block of data.taskBlocks) {
|
|
546
|
+
const dependsOn = this.#dependsOnOf(block);
|
|
547
|
+
for (const id of dependsOn) {
|
|
548
|
+
if (!ids.has(id)) {
|
|
549
|
+
findings.push(
|
|
550
|
+
this.finding(
|
|
551
|
+
ctx,
|
|
552
|
+
`Task ${block.id}`,
|
|
553
|
+
`task ${block.id} depends on unregistered task ${id}`,
|
|
554
|
+
"set DependsOn to a task id present in the plan (or `none`)",
|
|
555
|
+
),
|
|
556
|
+
);
|
|
557
|
+
}
|
|
558
|
+
}
|
|
559
|
+
}
|
|
560
|
+
return findings;
|
|
561
|
+
}
|
|
562
|
+
|
|
563
|
+
/** The numeric DependsOn values of a task block. */
|
|
564
|
+
#dependsOnOf(block: TaskBlock): readonly number[] {
|
|
565
|
+
const ids: number[] = [];
|
|
566
|
+
const field = block.fields.find((field) => field.key === "DependsOn");
|
|
567
|
+
if (field === undefined) return ids;
|
|
568
|
+
for (const value of field.lines) {
|
|
569
|
+
for (const match of value.matchAll(/\b([1-9]\d*)\b/g)) ids.push(Number(match[1]));
|
|
570
|
+
}
|
|
571
|
+
return ids;
|
|
572
|
+
}
|
|
573
|
+
|
|
574
|
+
/** The `P<n>` tokens of a comment struct (dependency cells / depends-on values). */
|
|
575
|
+
#phaseTokens(text: string): readonly string[] {
|
|
576
|
+
const tokens: string[] = [];
|
|
577
|
+
for (const match of text.matchAll(/P(\d+(?:\.\d+)*)/g)) tokens.push(`P${match[1]}`);
|
|
578
|
+
return tokens;
|
|
579
|
+
}
|
|
580
|
+
}
|
|
581
|
+
|
|
582
|
+
/** order — structural surfaces appear in their declared sequence. */
|
|
583
|
+
export class OrderInvariant extends Invariant {
|
|
584
|
+
readonly name = "order";
|
|
585
|
+
|
|
586
|
+
evaluate(ctx: JudgeContext): Finding[] {
|
|
587
|
+
return [...this.sectionOrder(ctx), ...this.historyOrder(ctx)];
|
|
588
|
+
}
|
|
589
|
+
|
|
590
|
+
/** Rank-2 headings must follow the declared registry order (design before constraints…). */
|
|
591
|
+
private sectionOrder(ctx: JudgeContext): Finding[] {
|
|
592
|
+
const findings: Finding[] = [];
|
|
593
|
+
const anchors = this.elementsOf(ctx)
|
|
594
|
+
.filter((element) => element.anchor.startsWith("## "))
|
|
595
|
+
.map((element) => element.anchor);
|
|
596
|
+
const docSections: readonly SectionBlock[] = this.#docSections(ctx);
|
|
597
|
+
let previous = -1;
|
|
598
|
+
for (const section of docSections) {
|
|
599
|
+
const match = this.#registryAnchorFor(section, anchors, ctx);
|
|
600
|
+
if (match === null) continue;
|
|
601
|
+
if (match.index < previous) {
|
|
602
|
+
findings.push(
|
|
603
|
+
this.finding(
|
|
604
|
+
ctx,
|
|
605
|
+
section.heading,
|
|
606
|
+
`${section.heading} appears out of the declared section order`,
|
|
607
|
+
`move the section to its registry position (${match.index + 1} of the declared sequence)`,
|
|
608
|
+
),
|
|
609
|
+
);
|
|
610
|
+
}
|
|
611
|
+
previous = Math.max(previous, match.index);
|
|
612
|
+
}
|
|
613
|
+
return findings;
|
|
614
|
+
}
|
|
615
|
+
|
|
616
|
+
/** The overall's change-history rows must be version-ascending — oldest first, the
|
|
617
|
+
* latest revision last (the canonical repo format). */
|
|
618
|
+
private historyOrder(ctx: JudgeContext): Finding[] {
|
|
619
|
+
const data = this.overall(ctx);
|
|
620
|
+
if (data === null) return [];
|
|
621
|
+
const findings: Finding[] = [];
|
|
622
|
+
const versions = data.tables["Change history"].rows
|
|
623
|
+
.map((row) => this.#versionPair(row[0] ?? ""))
|
|
624
|
+
.filter((pair) => pair !== null) as readonly { major: number; minor: number }[];
|
|
625
|
+
for (let i = 1; i < versions.length; i++) {
|
|
626
|
+
const earlier = versions[i - 1];
|
|
627
|
+
const later = versions[i];
|
|
628
|
+
if (
|
|
629
|
+
earlier.major > later.major ||
|
|
630
|
+
(earlier.major === later.major && earlier.minor > later.minor)
|
|
631
|
+
) {
|
|
632
|
+
findings.push(
|
|
633
|
+
this.finding(
|
|
634
|
+
ctx,
|
|
635
|
+
"Change history",
|
|
636
|
+
`change-history rows are not version-ascending (v${earlier.major}.${earlier.minor} above v${later.major}.${later.minor})`,
|
|
637
|
+
"order the Change-history rows oldest-first",
|
|
638
|
+
),
|
|
639
|
+
);
|
|
640
|
+
break;
|
|
641
|
+
}
|
|
642
|
+
}
|
|
643
|
+
return findings;
|
|
644
|
+
}
|
|
645
|
+
|
|
646
|
+
/** The document's rank-2 section blocks in document order. */
|
|
647
|
+
#docSections(ctx: JudgeContext): readonly SectionBlock[] {
|
|
648
|
+
if (ctx.docKey === "overall-spec") return (ctx.parsed as OverallParsed).sections;
|
|
649
|
+
if (ctx.docKey === "plan") return (ctx.parsed as PlanParsed).sections;
|
|
650
|
+
return (ctx.parsed as PhaseSpecParsed).sections;
|
|
651
|
+
}
|
|
652
|
+
|
|
653
|
+
/** The registry anchor a doc section heading conforms to (null when unregistered). */
|
|
654
|
+
#registryAnchorFor(
|
|
655
|
+
section: SectionBlock,
|
|
656
|
+
anchors: readonly string[],
|
|
657
|
+
ctx: JudgeContext,
|
|
658
|
+
): { anchor: string; index: number } | null {
|
|
659
|
+
for (let index = 0; index < anchors.length; index++) {
|
|
660
|
+
const slice = this.sliceOf(ctx, anchors[index]);
|
|
661
|
+
if (slice?.valuePattern?.test(section.heading) === true) {
|
|
662
|
+
return { anchor: anchors[index], index };
|
|
663
|
+
}
|
|
664
|
+
if (slice === undefined && section.heading.startsWith(anchors[index])) {
|
|
665
|
+
return { anchor: anchors[index], index };
|
|
666
|
+
}
|
|
667
|
+
}
|
|
668
|
+
return null;
|
|
669
|
+
}
|
|
670
|
+
|
|
671
|
+
#versionPair(text: string): { major: number; minor: number } | null {
|
|
672
|
+
const match = text.match(/v(\d+)\.(\d+)/);
|
|
673
|
+
return match === null ? null : { major: Number(match[1]), minor: Number(match[2]) };
|
|
674
|
+
}
|
|
675
|
+
}
|
|
676
|
+
|
|
677
|
+
/** continuity — numbered surfaces are 1-indexed and contiguous. */
|
|
678
|
+
export class ContinuityInvariant extends Invariant {
|
|
679
|
+
readonly name = "continuity";
|
|
680
|
+
|
|
681
|
+
evaluate(ctx: JudgeContext): Finding[] {
|
|
682
|
+
if (ctx.docKey === "plan") return this.taskContinuity(ctx);
|
|
683
|
+
if (ctx.docKey === "phase-spec") return this.groupContinuity(ctx);
|
|
684
|
+
return [];
|
|
685
|
+
}
|
|
686
|
+
|
|
687
|
+
/** Plan task ids must be exactly 1..N. */
|
|
688
|
+
private taskContinuity(ctx: JudgeContext): Finding[] {
|
|
689
|
+
const data = this.plan(ctx);
|
|
690
|
+
if (data === null || data.taskBlocks.length === 0) return [];
|
|
691
|
+
const findings: Finding[] = [];
|
|
692
|
+
data.taskBlocks.forEach((block, index) => {
|
|
693
|
+
const expected = index + 1;
|
|
694
|
+
if (block.id !== expected) {
|
|
695
|
+
findings.push(
|
|
696
|
+
this.finding(
|
|
697
|
+
ctx,
|
|
698
|
+
`Task ${block.id}`,
|
|
699
|
+
`task numbering is not contiguous from 1 (task ${block.id} at position ${index + 1})`,
|
|
700
|
+
"renumber the tasks so they run exactly 1..N without gaps or duplicates",
|
|
701
|
+
),
|
|
702
|
+
);
|
|
703
|
+
}
|
|
704
|
+
});
|
|
705
|
+
return findings;
|
|
706
|
+
}
|
|
707
|
+
|
|
708
|
+
/** Phase-spec design groups (and their items) must be 1-indexed and contiguous. */
|
|
709
|
+
private groupContinuity(ctx: JudgeContext): Finding[] {
|
|
710
|
+
const data = this.phaseSpec(ctx);
|
|
711
|
+
if (data === null || data.design.length === 0) return [];
|
|
712
|
+
const findings: Finding[] = [];
|
|
713
|
+
data.design.forEach((group, index) => {
|
|
714
|
+
if (Number(group.number) !== index + 1) {
|
|
715
|
+
findings.push(
|
|
716
|
+
this.finding(
|
|
717
|
+
ctx,
|
|
718
|
+
"### N. group heading",
|
|
719
|
+
`design group numbering is not contiguous from 1 (group ${group.number} at position ${index + 1})`,
|
|
720
|
+
"renumber the design groups so they run exactly 1..N",
|
|
721
|
+
),
|
|
722
|
+
);
|
|
723
|
+
}
|
|
724
|
+
this.#itemContinuity(ctx, group, group.number, findings);
|
|
725
|
+
});
|
|
726
|
+
return findings;
|
|
727
|
+
}
|
|
728
|
+
|
|
729
|
+
#itemContinuity(
|
|
730
|
+
ctx: JudgeContext,
|
|
731
|
+
group: DesignGroup,
|
|
732
|
+
groupNumber: string,
|
|
733
|
+
findings: Finding[],
|
|
734
|
+
): void {
|
|
735
|
+
group.items.forEach((item, index) => {
|
|
736
|
+
if (item.number !== `${groupNumber}.${index + 1}`) {
|
|
737
|
+
findings.push(
|
|
738
|
+
this.finding(
|
|
739
|
+
ctx,
|
|
740
|
+
"#### N.M item heading",
|
|
741
|
+
`design item numbering drifts within group ${groupNumber} (item ${item.number} at position ${index + 1})`,
|
|
742
|
+
"renumber the items within each group so they run N.1..N.M",
|
|
743
|
+
),
|
|
744
|
+
);
|
|
745
|
+
}
|
|
746
|
+
});
|
|
747
|
+
}
|
|
748
|
+
}
|
|
749
|
+
|
|
750
|
+
/** residue — conditional content leaves zero residue when its condition does not hold. */
|
|
751
|
+
export class ResidueInvariant extends Invariant {
|
|
752
|
+
readonly name = "residue";
|
|
753
|
+
|
|
754
|
+
evaluate(ctx: JudgeContext): Finding[] {
|
|
755
|
+
const findings: Finding[] = [];
|
|
756
|
+
const elements = this.elementsOf(ctx);
|
|
757
|
+
let owner: string | null = null;
|
|
758
|
+
for (const element of elements) {
|
|
759
|
+
if (element.home === "conditional" && element.anchor.startsWith("## ")) {
|
|
760
|
+
owner = element.anchor;
|
|
761
|
+
continue;
|
|
762
|
+
}
|
|
763
|
+
if (element.home !== "conditional" || owner === null) continue;
|
|
764
|
+
const slice = this.sliceOf(ctx, element.anchor);
|
|
765
|
+
if (slice === undefined || slice.valuePattern === undefined) continue;
|
|
766
|
+
if (this.anchorLines(ctx, owner).length > 0) continue; // the condition holds — the section is present
|
|
767
|
+
const leaked = this.occurrenceLines(ctx, slice).length;
|
|
768
|
+
if (leaked > 0) {
|
|
769
|
+
findings.push(
|
|
770
|
+
this.finding(
|
|
771
|
+
ctx,
|
|
772
|
+
element.anchor,
|
|
773
|
+
`conditional residue: ${element.anchor} content appears while ${owner} is absent`,
|
|
774
|
+
`remove the ${element.anchor} content or add the ${owner} section`,
|
|
775
|
+
),
|
|
776
|
+
);
|
|
777
|
+
}
|
|
778
|
+
}
|
|
779
|
+
return findings;
|
|
780
|
+
}
|
|
781
|
+
}
|
|
782
|
+
|
|
783
|
+
/** hollow — a structural surface that is present but carries no content. */
|
|
784
|
+
export class HollowInvariant extends Invariant {
|
|
785
|
+
readonly name = "hollow";
|
|
786
|
+
|
|
787
|
+
evaluate(ctx: JudgeContext): Finding[] {
|
|
788
|
+
const findings = [...this.tableHollow(ctx), ...this.taskHollow(ctx), ...this.designHollow(ctx)];
|
|
789
|
+
return findings;
|
|
790
|
+
}
|
|
791
|
+
|
|
792
|
+
/** The overall's four tables: a present table section with zero data rows is hollow. */
|
|
793
|
+
private tableHollow(ctx: JudgeContext): Finding[] {
|
|
794
|
+
const data = this.overall(ctx);
|
|
795
|
+
if (data === null) return [];
|
|
796
|
+
const findings: Finding[] = [];
|
|
797
|
+
for (const anchor of this.overallTableHeadings(ctx)) {
|
|
798
|
+
const headingExists = this.anchorLines(ctx, anchor).length > 0;
|
|
799
|
+
if (!headingExists) continue;
|
|
800
|
+
const section = data.sections.find((s) => s.heading.includes(anchor.replace(/^## /, "")));
|
|
801
|
+
const tableRows = section === undefined ? [] : this.tableRows(section.lines).slice(1);
|
|
802
|
+
if (tableRows.length === 0) {
|
|
803
|
+
findings.push(
|
|
804
|
+
this.finding(
|
|
805
|
+
ctx,
|
|
806
|
+
anchor,
|
|
807
|
+
`${anchor} section is hollow — the section heading carries no data rows`,
|
|
808
|
+
"either add the table's data rows or remove the empty section",
|
|
809
|
+
),
|
|
810
|
+
);
|
|
811
|
+
}
|
|
812
|
+
}
|
|
813
|
+
return findings;
|
|
814
|
+
}
|
|
815
|
+
|
|
816
|
+
/** A task block that carries no keyed fields is a hollow shell. */
|
|
817
|
+
private taskHollow(ctx: JudgeContext): Finding[] {
|
|
818
|
+
const data = this.plan(ctx);
|
|
819
|
+
if (data === null) return [];
|
|
820
|
+
const findings: Finding[] = [];
|
|
821
|
+
for (const block of data.taskBlocks) {
|
|
822
|
+
if (block.fields.length === 0) {
|
|
823
|
+
findings.push(
|
|
824
|
+
this.finding(
|
|
825
|
+
ctx,
|
|
826
|
+
`Task ${block.id}`,
|
|
827
|
+
`task ${block.id} is a hollow shell — the block carries no fields`,
|
|
828
|
+
"fill the task block with its Object/Files/Consumes/Produces/Steps/Acceptance/DependsOn fields or delete it",
|
|
829
|
+
),
|
|
830
|
+
);
|
|
831
|
+
}
|
|
832
|
+
}
|
|
833
|
+
return findings;
|
|
834
|
+
}
|
|
835
|
+
|
|
836
|
+
/** The phase-spec skeleton: a present Design with no groups (or an empty conditional section). */
|
|
837
|
+
private designHollow(ctx: JudgeContext): Finding[] {
|
|
838
|
+
const data = this.phaseSpec(ctx);
|
|
839
|
+
if (data === null) return [];
|
|
840
|
+
const findings: Finding[] = [];
|
|
841
|
+
const designSlice = this.sliceOf(ctx, "## Design");
|
|
842
|
+
if (
|
|
843
|
+
designSlice !== undefined &&
|
|
844
|
+
this.anchorLines(ctx, "## Design").length > 0 &&
|
|
845
|
+
data.design.length === 0
|
|
846
|
+
) {
|
|
847
|
+
findings.push(
|
|
848
|
+
this.finding(
|
|
849
|
+
ctx,
|
|
850
|
+
"## Design",
|
|
851
|
+
"the Design section is hollow — the heading carries no design groups",
|
|
852
|
+
"add the double-layer design outline (### N. groups with #### N.M items) or remove the section",
|
|
853
|
+
),
|
|
854
|
+
);
|
|
855
|
+
}
|
|
856
|
+
for (const section of data.sections) {
|
|
857
|
+
if (section.heading.trim().length === 0) continue;
|
|
858
|
+
const bodyCount = section.lines.filter((line) => line.trim().length > 0).length;
|
|
859
|
+
if (bodyCount === 0) {
|
|
860
|
+
findings.push(
|
|
861
|
+
this.finding(
|
|
862
|
+
ctx,
|
|
863
|
+
section.heading,
|
|
864
|
+
`${section.heading} section is hollow — the heading carries no content`,
|
|
865
|
+
"add the section's content or remove the empty section",
|
|
866
|
+
),
|
|
867
|
+
);
|
|
868
|
+
}
|
|
869
|
+
}
|
|
870
|
+
return findings;
|
|
871
|
+
}
|
|
872
|
+
}
|
|
873
|
+
|
|
874
|
+
/** selfBounded — the doc's own-scope lineage stays consistent with itself. */
|
|
875
|
+
export class SelfBoundedInvariant extends Invariant {
|
|
876
|
+
readonly name = "selfBounded";
|
|
877
|
+
|
|
878
|
+
evaluate(ctx: JudgeContext): Finding[] {
|
|
879
|
+
const headerVersion = this.#headerVersion(ctx);
|
|
880
|
+
const historyVersions = this.#historyVersions(ctx);
|
|
881
|
+
if (headerVersion === null || historyVersions.length === 0) return [];
|
|
882
|
+
const findings: Finding[] = [];
|
|
883
|
+
const newest = this.#newestVersion(historyVersions);
|
|
884
|
+
if (headerVersion !== newest) {
|
|
885
|
+
findings.push(
|
|
886
|
+
this.finding(
|
|
887
|
+
ctx,
|
|
888
|
+
"**Version**",
|
|
889
|
+
`the header version ${headerVersion} is not the change-history's newest row (${newest})`,
|
|
890
|
+
"bump both the **Version** header and the newest Change-history row together",
|
|
891
|
+
),
|
|
892
|
+
);
|
|
893
|
+
}
|
|
894
|
+
if (!historyVersions.includes(headerVersion)) {
|
|
895
|
+
findings.push(
|
|
896
|
+
this.finding(
|
|
897
|
+
ctx,
|
|
898
|
+
"**Version**",
|
|
899
|
+
`the header version ${headerVersion} is outside the document's own lineage`,
|
|
900
|
+
`the **Version** header must belong to the Change-history row versions: ${historyVersions.join(", ")}`,
|
|
901
|
+
),
|
|
902
|
+
);
|
|
903
|
+
}
|
|
904
|
+
return findings;
|
|
905
|
+
}
|
|
906
|
+
|
|
907
|
+
/** The doc's Change-history row versions — the overall reads its parsed table,
|
|
908
|
+
* the plan/spec read the `## Change history` section's table rows (the shared
|
|
909
|
+
* row primitive — the P4.1 T2 isomorphic lineage: the same lineage judgment rides
|
|
910
|
+
* all doc types). */
|
|
911
|
+
#historyVersions(ctx: JudgeContext): readonly string[] {
|
|
912
|
+
if (ctx.docKey === "overall-spec") {
|
|
913
|
+
const data = this.overall(ctx);
|
|
914
|
+
if (data === null) return [];
|
|
915
|
+
return data.tables["Change history"].rows
|
|
916
|
+
.map((row) => this.#firstVersion(row[0] ?? ""))
|
|
917
|
+
.filter((version) => version !== null) as readonly string[];
|
|
918
|
+
}
|
|
919
|
+
const section =
|
|
920
|
+
ctx.docKey === "plan"
|
|
921
|
+
? (ctx.parsed as PlanParsed).sections.find((s) => s.heading.includes("Change history"))
|
|
922
|
+
: (ctx.parsed as PhaseSpecParsed).sections.find((s) =>
|
|
923
|
+
s.heading.includes("Change history"),
|
|
924
|
+
);
|
|
925
|
+
if (section === undefined) return [];
|
|
926
|
+
return this.tableRows(section.lines)
|
|
927
|
+
.map((row) => this.#firstVersion(row[0] ?? ""))
|
|
928
|
+
.filter((version) => version !== null) as readonly string[];
|
|
929
|
+
}
|
|
930
|
+
|
|
931
|
+
#headerVersion(ctx: JudgeContext): string | null {
|
|
932
|
+
for (const line of this.anchorLines(ctx, "**Version**")) {
|
|
933
|
+
const tokens = this.versionTokens(line);
|
|
934
|
+
if (tokens.length > 0) return tokens[0];
|
|
935
|
+
}
|
|
936
|
+
return null;
|
|
937
|
+
}
|
|
938
|
+
|
|
939
|
+
#firstVersion(text: string): string | null {
|
|
940
|
+
const match = text.match(/v\d+\.\d+/);
|
|
941
|
+
return match === null ? null : match[0];
|
|
942
|
+
}
|
|
943
|
+
|
|
944
|
+
/** The newest lineage version — the numerically greatest (major, minor) row. */
|
|
945
|
+
#newestVersion(versions: readonly string[]): string {
|
|
946
|
+
let best = versions[0];
|
|
947
|
+
for (const version of versions) {
|
|
948
|
+
const [bestMajor, bestMinor] = this.#versionNumber(best);
|
|
949
|
+
const [currentMajor, currentMinor] = this.#versionNumber(version);
|
|
950
|
+
if (currentMajor > bestMajor || (currentMajor === bestMajor && currentMinor > bestMinor)) {
|
|
951
|
+
best = version;
|
|
952
|
+
}
|
|
953
|
+
}
|
|
954
|
+
return best;
|
|
955
|
+
}
|
|
956
|
+
|
|
957
|
+
#versionNumber(version: string): readonly [number, number] {
|
|
958
|
+
const match = version.match(/v(\d+)\.(\d+)/);
|
|
959
|
+
return match === null ? [0, 0] : [Number(match[1]), Number(match[2])];
|
|
960
|
+
}
|
|
961
|
+
}
|
|
962
|
+
|
|
963
|
+
// ---------------------------------------------------------------------------
|
|
964
|
+
// the four context-seam strategies
|
|
965
|
+
// ---------------------------------------------------------------------------
|
|
966
|
+
|
|
967
|
+
/** file-existence — every chain link target of the doc resolves to an existing file. */
|
|
968
|
+
export class FileExistenceInvariant extends Invariant {
|
|
969
|
+
readonly name: string = "file-existence";
|
|
970
|
+
|
|
971
|
+
evaluate(ctx: JudgeContext): Finding[] {
|
|
972
|
+
const findings: Finding[] = [];
|
|
973
|
+
for (const { source, link } of this.chainLinks(ctx)) {
|
|
974
|
+
if (this.isPlaceholder(link.target)) continue;
|
|
975
|
+
if (!this.#targetExists(ctx, link.target)) {
|
|
976
|
+
findings.push(
|
|
977
|
+
this.finding(
|
|
978
|
+
ctx,
|
|
979
|
+
source,
|
|
980
|
+
`the chain link target does not resolve to an existing file: ${link.target}`,
|
|
981
|
+
"fix the link target (repo-root form docs/kairos/... or a file-relative path)",
|
|
982
|
+
),
|
|
983
|
+
);
|
|
984
|
+
}
|
|
985
|
+
}
|
|
986
|
+
return findings;
|
|
987
|
+
}
|
|
988
|
+
|
|
989
|
+
/** The chain links of the judged doc type (overall design/plan cells; plan/spec lineage links). */
|
|
990
|
+
protected chainLinks(ctx: JudgeContext): readonly { source: string; link: ChainLink }[] {
|
|
991
|
+
const links: { source: string; link: ChainLink }[] = [];
|
|
992
|
+
if (ctx.docKey === "overall-spec") {
|
|
993
|
+
const data = this.overall(ctx);
|
|
994
|
+
if (data !== null) {
|
|
995
|
+
for (const phase of data.chain.phases) {
|
|
996
|
+
for (const link of this.linksOnLine(phase.designCell)) {
|
|
997
|
+
links.push({ source: `Phase inventory · ${phase.id}`, link });
|
|
998
|
+
}
|
|
999
|
+
for (const link of this.linksOnLine(phase.planCell)) {
|
|
1000
|
+
links.push({ source: `Phase inventory · ${phase.id}`, link });
|
|
1001
|
+
}
|
|
1002
|
+
}
|
|
1003
|
+
}
|
|
1004
|
+
}
|
|
1005
|
+
if (ctx.docKey === "plan") {
|
|
1006
|
+
const data = this.plan(ctx);
|
|
1007
|
+
if (data !== null) {
|
|
1008
|
+
if (data.chain.specLink !== null)
|
|
1009
|
+
links.push({ source: "**Spec:**", link: data.chain.specLink });
|
|
1010
|
+
if (data.chain.parentLink !== null)
|
|
1011
|
+
links.push({ source: "**Parent program**", link: data.chain.parentLink });
|
|
1012
|
+
}
|
|
1013
|
+
}
|
|
1014
|
+
if (ctx.docKey === "phase-spec") {
|
|
1015
|
+
const data = this.phaseSpec(ctx);
|
|
1016
|
+
if (data !== null && data.chain.parentLink !== null) {
|
|
1017
|
+
links.push({ source: "**Parent program**", link: data.chain.parentLink });
|
|
1018
|
+
}
|
|
1019
|
+
}
|
|
1020
|
+
return links;
|
|
1021
|
+
}
|
|
1022
|
+
|
|
1023
|
+
/** Whether a target's raw form marks it as a holder placeholder (no existence judgment). */
|
|
1024
|
+
protected isPlaceholder(target: string): boolean {
|
|
1025
|
+
const trimmed = target.trim();
|
|
1026
|
+
if (trimmed === "") return true;
|
|
1027
|
+
if (trimmed === "Pending" || trimmed === "[Pending]") return true;
|
|
1028
|
+
return /^<[^>]+>$/.test(trimmed);
|
|
1029
|
+
}
|
|
1030
|
+
|
|
1031
|
+
/** Whether the target exists — absolute targets directly; repo-root form first, the
|
|
1032
|
+
* doc's own dir as the file-relative fallback. */
|
|
1033
|
+
#targetExists(ctx: JudgeContext, target: string): boolean {
|
|
1034
|
+
if (path.isAbsolute(target)) return ctx.fs.exists(target);
|
|
1035
|
+
return (
|
|
1036
|
+
ctx.fs.exists(path.join(ctx.root, target)) ||
|
|
1037
|
+
ctx.fs.exists(path.join(path.dirname(ctx.path), target))
|
|
1038
|
+
);
|
|
1039
|
+
}
|
|
1040
|
+
}
|
|
1041
|
+
|
|
1042
|
+
/** sibling-scan — every cross-linked doc must be a same-family sibling of this doc. */
|
|
1043
|
+
export class SiblingScanInvariant extends FileExistenceInvariant {
|
|
1044
|
+
readonly name = "sibling-scan";
|
|
1045
|
+
|
|
1046
|
+
evaluate(ctx: JudgeContext): Finding[] {
|
|
1047
|
+
const findings: Finding[] = [];
|
|
1048
|
+
const baseline = new Set<string>();
|
|
1049
|
+
for (const root of SiblingScanInvariant.#scanRoots(ctx.path)) {
|
|
1050
|
+
for (const entry of ctx.fs.list(root)) {
|
|
1051
|
+
if (entry.endsWith(".md")) baseline.add(entry);
|
|
1052
|
+
}
|
|
1053
|
+
}
|
|
1054
|
+
for (const { source, link } of this.chainLinks(ctx)) {
|
|
1055
|
+
if (this.isPlaceholder(link.target)) continue;
|
|
1056
|
+
const basename = path.basename(link.target);
|
|
1057
|
+
if (!baseline.has(basename)) {
|
|
1058
|
+
findings.push(
|
|
1059
|
+
this.finding(
|
|
1060
|
+
ctx,
|
|
1061
|
+
source,
|
|
1062
|
+
`the cross-linked doc ${basename} is not a same-family sibling (not present in the sibling docs scan)`,
|
|
1063
|
+
"link to a sibling doc under the same specs/plans family",
|
|
1064
|
+
),
|
|
1065
|
+
);
|
|
1066
|
+
}
|
|
1067
|
+
}
|
|
1068
|
+
return findings;
|
|
1069
|
+
}
|
|
1070
|
+
|
|
1071
|
+
/** The doc's own dir + its sibling specs/plans dirs — the same-family scan roots. */
|
|
1072
|
+
static #scanRoots(docPath: string): readonly string[] {
|
|
1073
|
+
const own = path.dirname(docPath);
|
|
1074
|
+
const grand = path.dirname(own);
|
|
1075
|
+
return [own, path.join(grand, "specs"), path.join(grand, "plans")];
|
|
1076
|
+
}
|
|
1077
|
+
}
|
|
1078
|
+
|
|
1079
|
+
/** cross-doc-chain — the Class-A/B chain resolves and its lineage tokens belong to the parent. */
|
|
1080
|
+
export class CrossDocChainInvariant extends Invariant {
|
|
1081
|
+
readonly name = "cross-doc-chain";
|
|
1082
|
+
|
|
1083
|
+
evaluate(ctx: JudgeContext): Finding[] {
|
|
1084
|
+
if (ctx.docKey === "overall-spec") return this.overallChain(ctx);
|
|
1085
|
+
if (ctx.docKey === "plan") return this.planChain(ctx);
|
|
1086
|
+
return this.specChain(ctx);
|
|
1087
|
+
}
|
|
1088
|
+
|
|
1089
|
+
/** The overall chain-root face: a dispatch phase must be registered in the inventory. */
|
|
1090
|
+
private overallChain(ctx: JudgeContext): Finding[] {
|
|
1091
|
+
if (ctx.phaseId === undefined || ctx.phaseId === null) return [];
|
|
1092
|
+
const data = this.overall(ctx);
|
|
1093
|
+
if (data === null) return [];
|
|
1094
|
+
const registered = new Set(data.chain.phases.map((phase) => phase.id.toLowerCase()));
|
|
1095
|
+
if (!registered.has(ctx.phaseId.toLowerCase())) {
|
|
1096
|
+
return [
|
|
1097
|
+
this.finding(
|
|
1098
|
+
ctx,
|
|
1099
|
+
"Phase inventory",
|
|
1100
|
+
`dispatch phase ${ctx.phaseId} is not registered in the parent overall's Phase inventory`,
|
|
1101
|
+
`register phase ${ctx.phaseId} in the Phase inventory`,
|
|
1102
|
+
),
|
|
1103
|
+
];
|
|
1104
|
+
}
|
|
1105
|
+
return [];
|
|
1106
|
+
}
|
|
1107
|
+
|
|
1108
|
+
/** The Class-A/Class-B plan chain: `**Spec:**` label == basename + the Class-B lineage. */
|
|
1109
|
+
private planChain(ctx: JudgeContext): Finding[] {
|
|
1110
|
+
const data = this.plan(ctx);
|
|
1111
|
+
if (data === null) return [];
|
|
1112
|
+
const findings: Finding[] = [];
|
|
1113
|
+
const specLink = data.chain.specLink;
|
|
1114
|
+
if (specLink === null) {
|
|
1115
|
+
findings.push(
|
|
1116
|
+
this.finding(
|
|
1117
|
+
ctx,
|
|
1118
|
+
"**Spec:**",
|
|
1119
|
+
"the plan carries no **Spec:** reference",
|
|
1120
|
+
"add a **Spec:** link pointing at the phase design spec",
|
|
1121
|
+
),
|
|
1122
|
+
);
|
|
1123
|
+
} else if (specLink.label.trim() !== path.basename(specLink.target)) {
|
|
1124
|
+
findings.push(
|
|
1125
|
+
this.finding(
|
|
1126
|
+
ctx,
|
|
1127
|
+
"**Spec:**",
|
|
1128
|
+
`the **Spec:** link label ${specLink.label.trim()} does not equal the resolved basename ${path.basename(specLink.target)}`,
|
|
1129
|
+
"make the link label equal the resolved file's basename",
|
|
1130
|
+
),
|
|
1131
|
+
);
|
|
1132
|
+
}
|
|
1133
|
+
if (data.chain.parentLink === null) {
|
|
1134
|
+
findings.push(
|
|
1135
|
+
this.finding(
|
|
1136
|
+
ctx,
|
|
1137
|
+
"**Parent program**",
|
|
1138
|
+
"the plan carries no **Parent program** link",
|
|
1139
|
+
"add the **Parent program** link pointing at the parent overall",
|
|
1140
|
+
),
|
|
1141
|
+
);
|
|
1142
|
+
}
|
|
1143
|
+
findings.push(...this.classB(ctx, data.chain.parentLink, data.chain.parentTokens));
|
|
1144
|
+
return findings;
|
|
1145
|
+
}
|
|
1146
|
+
|
|
1147
|
+
/** The Class-B phase-spec chain: the parent-link lineage belongs to the parent overall. */
|
|
1148
|
+
private specChain(ctx: JudgeContext): Finding[] {
|
|
1149
|
+
const data = this.phaseSpec(ctx);
|
|
1150
|
+
if (data === null) return [];
|
|
1151
|
+
const findings: Finding[] = [];
|
|
1152
|
+
if (data.chain.parentLink === null) {
|
|
1153
|
+
findings.push(
|
|
1154
|
+
this.finding(
|
|
1155
|
+
ctx,
|
|
1156
|
+
"**Parent program**",
|
|
1157
|
+
"the phase-spec carries no **Parent program** link",
|
|
1158
|
+
"add the **Parent program** link pointing at the parent overall",
|
|
1159
|
+
),
|
|
1160
|
+
);
|
|
1161
|
+
}
|
|
1162
|
+
findings.push(...this.classB(ctx, data.chain.parentLink, data.chain.parentTokens));
|
|
1163
|
+
return findings;
|
|
1164
|
+
}
|
|
1165
|
+
|
|
1166
|
+
/** Class-B: the parent version tokens must belong to the parent overall's lineage. */
|
|
1167
|
+
private classB(
|
|
1168
|
+
ctx: JudgeContext,
|
|
1169
|
+
parentLink: ChainLink | null,
|
|
1170
|
+
parentTokens: readonly string[],
|
|
1171
|
+
): Finding[] {
|
|
1172
|
+
const findings: Finding[] = [];
|
|
1173
|
+
if (parentLink === null || parentTokens.length === 0) return findings;
|
|
1174
|
+
const parentParsed = ctx.chainDocs?.get(parentLink.target);
|
|
1175
|
+
if (parentParsed === undefined) return findings;
|
|
1176
|
+
const lineage = this.#parentLineage(parentParsed);
|
|
1177
|
+
for (const token of parentTokens) {
|
|
1178
|
+
if (!lineage.has(token)) {
|
|
1179
|
+
findings.push(
|
|
1180
|
+
this.finding(
|
|
1181
|
+
ctx,
|
|
1182
|
+
"**Parent program**",
|
|
1183
|
+
`the **Parent program** version token ${token} does not belong to the parent overall's lineage`,
|
|
1184
|
+
`use a version the parent overall declares (its **Version** header or a Change-history row): ${[...lineage].join(", ")}`,
|
|
1185
|
+
),
|
|
1186
|
+
);
|
|
1187
|
+
}
|
|
1188
|
+
}
|
|
1189
|
+
return findings;
|
|
1190
|
+
}
|
|
1191
|
+
|
|
1192
|
+
/** The parent overall's lineage: its header version + every Change-history row version. */
|
|
1193
|
+
#parentLineage(parent: ParsedDoc): Set<string> {
|
|
1194
|
+
const lineage = new Set<string>();
|
|
1195
|
+
if (parent.docType !== "overall-spec") return lineage;
|
|
1196
|
+
for (const line of (parent as OverallParsed).headerLines) {
|
|
1197
|
+
if (line.includes("**Version**")) {
|
|
1198
|
+
for (const token of this.versionTokens(line)) lineage.add(token);
|
|
1199
|
+
}
|
|
1200
|
+
}
|
|
1201
|
+
for (const row of (parent as OverallParsed).tables["Change history"].rows) {
|
|
1202
|
+
const match = row[0]?.match(/v\d+\.\d+/);
|
|
1203
|
+
if (match !== null) lineage.add(match[0]);
|
|
1204
|
+
}
|
|
1205
|
+
return lineage;
|
|
1206
|
+
}
|
|
1207
|
+
}
|
|
1208
|
+
|
|
1209
|
+
/** section-scoped-domain — a value shape is enforced only inside its owning section. */
|
|
1210
|
+
export class SectionScopedDomainInvariant extends Invariant {
|
|
1211
|
+
readonly name = "section-scoped-domain";
|
|
1212
|
+
|
|
1213
|
+
evaluate(ctx: JudgeContext): Finding[] {
|
|
1214
|
+
if (ctx.docKey === "overall-spec") return this.issueScopedRefs(ctx);
|
|
1215
|
+
if (ctx.docKey === "phase-spec") return this.designScoping(ctx);
|
|
1216
|
+
return [];
|
|
1217
|
+
}
|
|
1218
|
+
|
|
1219
|
+
/** Issue-ref forms are judged only within `## Issue inventory` (a content-wide rule
|
|
1220
|
+
* would misfire on legacy `## Requirement inventory` tables whose ref cells are prose). */
|
|
1221
|
+
private issueScopedRefs(ctx: JudgeContext): Finding[] {
|
|
1222
|
+
const data = this.overall(ctx);
|
|
1223
|
+
if (data === null) return [];
|
|
1224
|
+
const slice = this.sliceOf(ctx, "Issue ref cell");
|
|
1225
|
+
if (slice?.valuePattern === undefined) return [];
|
|
1226
|
+
const findings: Finding[] = [];
|
|
1227
|
+
for (const row of data.tables["Issue inventory"].rows) {
|
|
1228
|
+
const ref = row[1]?.trim() ?? "";
|
|
1229
|
+
if (ref === "" || ref.toLowerCase() === "none") continue;
|
|
1230
|
+
if (!slice.valuePattern.test(ref)) {
|
|
1231
|
+
findings.push(
|
|
1232
|
+
this.finding(
|
|
1233
|
+
ctx,
|
|
1234
|
+
"Issue inventory",
|
|
1235
|
+
`issue ref inside Issue inventory is outside its declared domain: ${ref}`,
|
|
1236
|
+
"use the anchored `#NNN#issuecomment-<digits>` / bare `#NNN` / `[#NNN]` / `none` or a parenthetical note",
|
|
1237
|
+
),
|
|
1238
|
+
);
|
|
1239
|
+
}
|
|
1240
|
+
}
|
|
1241
|
+
return findings;
|
|
1242
|
+
}
|
|
1243
|
+
|
|
1244
|
+
/** `### N.` design-group headings may appear only inside `## Design`. */
|
|
1245
|
+
private designScoping(ctx: JudgeContext): Finding[] {
|
|
1246
|
+
const data = this.phaseSpec(ctx);
|
|
1247
|
+
if (data === null) return [];
|
|
1248
|
+
const slice = this.sliceOf(ctx, "### N. group heading");
|
|
1249
|
+
if (slice?.valuePattern === undefined) return [];
|
|
1250
|
+
const findings: Finding[] = [];
|
|
1251
|
+
for (const section of data.sections) {
|
|
1252
|
+
if (this.sliceOf(ctx, "## Design")?.valuePattern?.test(section.heading) === true) continue;
|
|
1253
|
+
for (const line of section.lines) {
|
|
1254
|
+
if (slice.valuePattern.test(line.trim())) {
|
|
1255
|
+
findings.push(
|
|
1256
|
+
this.finding(
|
|
1257
|
+
ctx,
|
|
1258
|
+
"### N. group heading",
|
|
1259
|
+
`a design-group heading appears outside ## Design: ${line.trim()}`,
|
|
1260
|
+
"move the group heading under ## Design (design-body surface only)",
|
|
1261
|
+
),
|
|
1262
|
+
);
|
|
1263
|
+
}
|
|
1264
|
+
}
|
|
1265
|
+
}
|
|
1266
|
+
return findings;
|
|
1267
|
+
}
|
|
1268
|
+
}
|