@oscaner-skills/cdd-engine 4.13.0 → 4.15.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.
@@ -0,0 +1,134 @@
1
+ // packages/cdd-engine/src-next/contract/census.ts
2
+ // P37 T8 — the census execution face (design spec §8). A count claim is allowed in a
3
+ // document, but a MEASURED number must carry a `census:<id>` reference, and this module
4
+ // is what makes that reference checkable: the registry supplies one number per row, and
5
+ // the gate compares the number a `census:<id> = <n>` reference declares with the row's
6
+ // export.
7
+ //
8
+ // ONE ROW, ONE NUMBER (§8.2). `measure(): number` is deliberately not a record: the gate
9
+ // compares the single `<n>` the reference writes, so a row measuring a record would leave
10
+ // that comparison without a meaning — which is why the type, not a runtime check, refuses
11
+ // it. A measurement surface that exposes several numbers registers several rows; the id is
12
+ // the key, and there is no sub-key syntax.
13
+ //
14
+ // The registry is NOT a module singleton and must not become one: the four `pin.*` rows
15
+ // measure a corpus, so the table is built at the composition point that already resolved a
16
+ // root (`face/cli.ts#rootOf()` if a command ever reads it; the guard test here), handing
17
+ // the SAME `PinAudit` and the SAME `corpusOf(root)` the scan uses. The corpus declaration
18
+ // therefore still lives in exactly one module, and no module-scope file-system read rides
19
+ // the import graph of every `cdd` command.
20
+ //
21
+ // The gate judges ONE thing (§8.3): does each `<n>` a reference declares equal its row's
22
+ // export. `<n>` is read only from the right-hand side of the fixed form; unequal is red,
23
+ // and an unknown id throws (the same "unregistered lookup throws" shape the criteria and
24
+ // completion-criterion registries use). The reference GRAMMAR is half of the judgment
25
+ // (§8.3): only `census:<id> = <n>` whose id is dotted lowercase and whose `<n>` is a
26
+ // decimal integer is a reference at all. A `census:` word that fails that grammar is prose
27
+ // about the form — the placeholder `census:<id> = <n>` sits inside this very corpus — so it
28
+ // is neither parsed nor compared nor thrown on. That is a grammar, not a filter: a
29
+ // well-formed but unregistered id still throws, so §8.3's floor cannot be weakened by
30
+ // skipping everything that carries a metacharacter.
31
+ //
32
+ // Module-level exports are types / one declared grammar / the factory / the classes — zero
33
+ // behavior-carrying bare functions.
34
+ import { CRITERIA_ROWS, LENS_QUESTION_ROWS } from "./review-criteria.js";
35
+ /** The reference grammar (§8.3) — a dotted lowercase id and a decimal integer on the
36
+ * right of the fixed `=` form. A `census:` word outside it is prose about the form.
37
+ * The value's terminator says the whole number must be digits: guarding only the next
38
+ * digit would truncate `3.5` to `3` and judge a form (§8.3's `^\d+$`) the grammar puts
39
+ * outside the gate — a false red for `3.5`, a false green for `0.5`. */
40
+ const REFERENCE = /census:(?<id>[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*)+)\s*=\s*(?<n>\d+)(?![0-9A-Za-z.])/g;
41
+ /** The census registry — `of(id)` throws for a row nobody registered. */
42
+ export class CensusTable {
43
+ #rows;
44
+ constructor(rows) {
45
+ const byId = new Map();
46
+ for (const row of rows) {
47
+ if (byId.has(row.id))
48
+ throw new Error(`census row \`${row.id}\` is registered twice`);
49
+ byId.set(row.id, row);
50
+ }
51
+ this.#rows = byId;
52
+ }
53
+ /** The registered rows, in declaration order. */
54
+ rows() {
55
+ return [...this.#rows.values()];
56
+ }
57
+ /** The one row registered under `id`; an unregistered id throws (§8.2). */
58
+ of(id) {
59
+ const row = this.#rows.get(id);
60
+ if (row === undefined)
61
+ throw new Error(`no census row is registered for \`${id}\``);
62
+ return row;
63
+ }
64
+ }
65
+ /** Build the declared table at the composition point (§8.2): the four pin readings come
66
+ * off ONE `PinAudit.census(corpus)` call, so the four rows are readings of one scan
67
+ * rather than four computations, and the three registry rows read the shipped tables
68
+ * directly instead of copying their length into a literal. */
69
+ export const censusTableOf = (deps) => {
70
+ const pins = deps.audit.census(deps.corpus);
71
+ const cells = LENS_QUESTION_ROWS.reduce((sum, row) => sum + row.reviewKinds.length, 0);
72
+ return new CensusTable([
73
+ { id: "pin.symbol", measure: () => pins.symbol },
74
+ { id: "pin.path", measure: () => pins.path },
75
+ { id: "pin.total", measure: () => pins.total },
76
+ { id: "pin.files", measure: () => pins.files },
77
+ { id: "criteria.rows", measure: () => CRITERIA_ROWS.length },
78
+ { id: "questions.rows", measure: () => LENS_QUESTION_ROWS.length },
79
+ { id: "questions.cells", measure: () => cells },
80
+ ]);
81
+ };
82
+ /** The gate (§8.3) — it compares what the corpus declares with what the registry
83
+ * measures, and it judges nothing else: no prose semantics, no "does this number look
84
+ * reasonable", no undeclared counts. */
85
+ export class CensusGate {
86
+ #table;
87
+ #audit;
88
+ #corpus;
89
+ constructor(deps) {
90
+ this.#table = deps.table;
91
+ this.#audit = deps.audit;
92
+ this.#corpus = deps.corpus;
93
+ }
94
+ /** Every reference one text writes, in document order — the grammar, nothing else.
95
+ * A `census:` word that fails the grammar is prose about the form. */
96
+ static referencesOf(text, source) {
97
+ const references = [];
98
+ text.split("\n").forEach((line, index) => {
99
+ for (const match of line.matchAll(REFERENCE)) {
100
+ const id = match.groups?.id;
101
+ const declared = match.groups?.n;
102
+ if (id === undefined || declared === undefined)
103
+ continue;
104
+ references.push({
105
+ id,
106
+ declared: Number(declared),
107
+ source,
108
+ line: index + 1,
109
+ text: match[0],
110
+ });
111
+ }
112
+ });
113
+ return references;
114
+ }
115
+ /** Judge the whole corpus: every reference is resolved through the registry (an
116
+ * unregistered id throws) and its declared number is compared with the export. */
117
+ report() {
118
+ const mismatches = [];
119
+ let compared = 0;
120
+ for (const file of this.#audit.filesOf(this.#corpus)) {
121
+ const text = this.#audit.textOf(file);
122
+ if (text === null)
123
+ continue;
124
+ for (const reference of CensusGate.referencesOf(text, file)) {
125
+ const measured = this.#table.of(reference.id).measure();
126
+ compared += 1;
127
+ if (measured === reference.declared)
128
+ continue;
129
+ mismatches.push({ ...reference, measured });
130
+ }
131
+ }
132
+ return { compared, mismatches };
133
+ }
134
+ }