@htilabs/platform-common-models 0.2.0-beta.4 → 0.3.0-beta.5
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 +38 -0
- package/dist/constants/index.cjs +0 -843
- package/dist/constants/index.cjs.map +1 -1
- package/dist/constants/index.d.cts +146 -5
- package/dist/constants/index.d.ts +146 -5
- package/dist/constants/index.js +0 -786
- package/dist/constants/index.js.map +1 -1
- package/dist/{platform-role-AHv1l5Og.d.cts → cvcEntry-wqktWfzE.d.cts} +231 -37
- package/dist/{platform-role-AHv1l5Og.d.ts → cvcEntry-wqktWfzE.d.ts} +231 -37
- package/dist/cvcs/index.cjs +2184 -0
- package/dist/cvcs/index.cjs.map +1 -0
- package/dist/cvcs/index.d.cts +2384 -0
- package/dist/cvcs/index.d.ts +2384 -0
- package/dist/cvcs/index.js +2154 -0
- package/dist/cvcs/index.js.map +1 -0
- package/dist/index--NCIPluF.d.cts +378 -0
- package/dist/index-CFOrHA8l.d.ts +378 -0
- package/dist/index.cjs +2962 -843
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +217 -3
- package/dist/index.d.ts +217 -3
- package/dist/index.js +2934 -786
- package/dist/index.js.map +1 -1
- package/dist/models/index.cjs +211 -0
- package/dist/models/index.cjs.map +1 -1
- package/dist/models/index.d.cts +3 -292
- package/dist/models/index.d.ts +3 -292
- package/dist/models/index.js +209 -0
- package/dist/models/index.js.map +1 -1
- package/dist/{platform-auth-BTbQIY3b.d.cts → platform-auth-C-G2qeGM.d.cts} +1 -297
- package/dist/{platform-auth-BTbQIY3b.d.ts → platform-auth-C-G2qeGM.d.ts} +1 -297
- package/dist/schemas/index.cjs +195 -729
- package/dist/schemas/index.cjs.map +1 -1
- package/dist/schemas/index.d.cts +11 -11
- package/dist/schemas/index.d.ts +11 -11
- package/dist/schemas/index.js +189 -729
- package/dist/schemas/index.js.map +1 -1
- package/dist/services/index.cjs +1442 -0
- package/dist/services/index.cjs.map +1 -0
- package/dist/services/index.d.cts +305 -0
- package/dist/services/index.d.ts +305 -0
- package/dist/services/index.js +1417 -0
- package/dist/services/index.js.map +1 -0
- package/dist/types/index.d.cts +2 -2
- package/dist/types/index.d.ts +2 -2
- package/dist/validation/index.cjs +261 -0
- package/dist/validation/index.cjs.map +1 -0
- package/dist/validation/index.d.cts +251 -0
- package/dist/validation/index.d.ts +251 -0
- package/dist/validation/index.js +228 -0
- package/dist/validation/index.js.map +1 -0
- package/package.json +36 -12
- package/src/__tests__/__snapshots__/cvc-sot.snap +22 -0
- package/src/__tests__/cvc-sot-snapshot.test.ts +184 -0
- package/src/__tests__/cvc-structural.test.ts +130 -0
- package/src/constants/ic.ts +0 -925
- package/src/constants/service-catalog.ts +146 -4
- package/src/cvcs/index.ts +31 -0
- package/src/cvcs/missingness.v1.0.0.json +50 -0
- package/src/cvcs/serviceCategories.v1.0.0.json +1947 -0
- package/src/cvcs/serviceMechanisms.v1.0.0.json +47 -0
- package/src/cvcs/serviceStates.v1.0.0.json +106 -0
- package/src/generated/cvc-enums.ts +215 -0
- package/src/index.ts +61 -1
- package/src/models/cvcEntryModel.ts +32 -0
- package/src/models/cvcRegistryModel.ts +35 -0
- package/src/models/index.ts +8 -0
- package/src/schemas/cvcEntry.ts +158 -0
- package/src/schemas/cvcRegistry.ts +149 -0
- package/src/schemas/index.ts +16 -0
- package/src/services/__tests__/cvcRegistryService.test.ts +614 -0
- package/src/services/cvcRegistryService.ts +729 -0
- package/src/services/index.ts +21 -0
- package/src/validation/cvc.ts +414 -0
- package/src/validation/index.ts +15 -0
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
// src/validation/cvc.ts
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
var CvcCodeSchema = z.string().regex(/^\d{2}(-\d{2}){6}$/);
|
|
4
|
+
var CvcKeySchema = z.string().regex(/^[a-z][a-z0-9_]*$/);
|
|
5
|
+
var CvcEntrySchema = z.object({
|
|
6
|
+
code: CvcCodeSchema,
|
|
7
|
+
key: CvcKeySchema,
|
|
8
|
+
title: z.string().min(1),
|
|
9
|
+
selectable: z.boolean(),
|
|
10
|
+
parentCode: CvcCodeSchema.nullable(),
|
|
11
|
+
childCodes: z.array(CvcCodeSchema),
|
|
12
|
+
definition: z.string().nullable()
|
|
13
|
+
}).passthrough();
|
|
14
|
+
var ServiceCategoryEntrySchema = CvcEntrySchema.extend({
|
|
15
|
+
relevantMechanisms: z.array(CvcKeySchema).nullable()
|
|
16
|
+
});
|
|
17
|
+
var CvcEnvelopeSchema = z.object({
|
|
18
|
+
domain: z.string().min(1),
|
|
19
|
+
name: z.string().min(1),
|
|
20
|
+
version: z.string().min(1),
|
|
21
|
+
missingness: z.array(z.string()).optional(),
|
|
22
|
+
levels: z.record(z.string(), z.string()),
|
|
23
|
+
entries: z.array(CvcEntrySchema)
|
|
24
|
+
});
|
|
25
|
+
function getCvcLevel(code) {
|
|
26
|
+
const segments = code.split("-");
|
|
27
|
+
if (segments[6] !== "00") return 0;
|
|
28
|
+
for (let i = 5; i >= 1; i -= 1) {
|
|
29
|
+
if (segments[i] !== "00") return i;
|
|
30
|
+
}
|
|
31
|
+
return 0;
|
|
32
|
+
}
|
|
33
|
+
function validateCvc(envelope, options = {}) {
|
|
34
|
+
const errors = [];
|
|
35
|
+
const { entries } = envelope;
|
|
36
|
+
if (envelope.domain !== "missingness" && envelope.missingness === void 0) {
|
|
37
|
+
errors.push({
|
|
38
|
+
invariant: "C7",
|
|
39
|
+
message: "envelope is missing required field `missingness` (must be an array, use `[]` to opt out of the missingness merge)"
|
|
40
|
+
});
|
|
41
|
+
}
|
|
42
|
+
const codeRe = /^\d{2}(-\d{2}){6}$/;
|
|
43
|
+
const seenCodes = /* @__PURE__ */ new Set();
|
|
44
|
+
for (const entry of entries) {
|
|
45
|
+
if (!codeRe.test(entry.code)) {
|
|
46
|
+
errors.push({
|
|
47
|
+
invariant: "C1",
|
|
48
|
+
message: `code does not match /^\\d{2}(-\\d{2}){6}$/`,
|
|
49
|
+
code: entry.code,
|
|
50
|
+
key: entry.key
|
|
51
|
+
});
|
|
52
|
+
}
|
|
53
|
+
if (seenCodes.has(entry.code)) {
|
|
54
|
+
errors.push({
|
|
55
|
+
invariant: "C1",
|
|
56
|
+
message: `duplicate code`,
|
|
57
|
+
code: entry.code,
|
|
58
|
+
key: entry.key
|
|
59
|
+
});
|
|
60
|
+
}
|
|
61
|
+
seenCodes.add(entry.code);
|
|
62
|
+
}
|
|
63
|
+
const keyRe = /^[a-z][a-z0-9_]*$/;
|
|
64
|
+
const seenKeys = /* @__PURE__ */ new Set();
|
|
65
|
+
for (const entry of entries) {
|
|
66
|
+
if (!keyRe.test(entry.key)) {
|
|
67
|
+
errors.push({
|
|
68
|
+
invariant: "C2",
|
|
69
|
+
message: `key does not match /^[a-z][a-z0-9_]*$/`,
|
|
70
|
+
code: entry.code,
|
|
71
|
+
key: entry.key
|
|
72
|
+
});
|
|
73
|
+
}
|
|
74
|
+
if (seenKeys.has(entry.key)) {
|
|
75
|
+
errors.push({
|
|
76
|
+
invariant: "C2",
|
|
77
|
+
message: `duplicate key`,
|
|
78
|
+
code: entry.code,
|
|
79
|
+
key: entry.key
|
|
80
|
+
});
|
|
81
|
+
}
|
|
82
|
+
seenKeys.add(entry.key);
|
|
83
|
+
}
|
|
84
|
+
const byCode = /* @__PURE__ */ new Map();
|
|
85
|
+
for (const entry of entries) {
|
|
86
|
+
if (codeRe.test(entry.code)) byCode.set(entry.code, entry);
|
|
87
|
+
}
|
|
88
|
+
for (const entry of entries) {
|
|
89
|
+
if (entry.parentCode === null) continue;
|
|
90
|
+
if (!byCode.has(entry.parentCode)) {
|
|
91
|
+
errors.push({
|
|
92
|
+
invariant: "C3",
|
|
93
|
+
message: `parentCode ${entry.parentCode} does not resolve to any entry in this CVC`,
|
|
94
|
+
code: entry.code,
|
|
95
|
+
key: entry.key
|
|
96
|
+
});
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
for (const entry of entries) {
|
|
100
|
+
const visited = /* @__PURE__ */ new Set();
|
|
101
|
+
let cursor = entry;
|
|
102
|
+
while (cursor && cursor.parentCode !== null) {
|
|
103
|
+
if (visited.has(cursor.code)) {
|
|
104
|
+
errors.push({
|
|
105
|
+
invariant: "C3",
|
|
106
|
+
message: `cycle detected in parentCode chain starting from ${entry.code}`,
|
|
107
|
+
code: entry.code,
|
|
108
|
+
key: entry.key
|
|
109
|
+
});
|
|
110
|
+
break;
|
|
111
|
+
}
|
|
112
|
+
visited.add(cursor.code);
|
|
113
|
+
cursor = byCode.get(cursor.parentCode);
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
const parentToChildrenFromParent = /* @__PURE__ */ new Map();
|
|
117
|
+
for (const entry of entries) {
|
|
118
|
+
if (entry.parentCode !== null) {
|
|
119
|
+
let set = parentToChildrenFromParent.get(entry.parentCode);
|
|
120
|
+
if (!set) {
|
|
121
|
+
set = /* @__PURE__ */ new Set();
|
|
122
|
+
parentToChildrenFromParent.set(entry.parentCode, set);
|
|
123
|
+
}
|
|
124
|
+
set.add(entry.code);
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
for (const entry of entries) {
|
|
128
|
+
const declared = new Set(entry.childCodes);
|
|
129
|
+
const derived = parentToChildrenFromParent.get(entry.code) ?? /* @__PURE__ */ new Set();
|
|
130
|
+
for (const child of declared) {
|
|
131
|
+
if (!derived.has(child)) {
|
|
132
|
+
errors.push({
|
|
133
|
+
invariant: "C4",
|
|
134
|
+
message: `entry lists ${child} in childCodes but that entry's parentCode is not ${entry.code}`,
|
|
135
|
+
code: entry.code,
|
|
136
|
+
key: entry.key
|
|
137
|
+
});
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
for (const child of derived) {
|
|
141
|
+
if (!declared.has(child)) {
|
|
142
|
+
errors.push({
|
|
143
|
+
invariant: "C4",
|
|
144
|
+
message: `entry ${child} has parentCode ${entry.code} but is missing from its childCodes`,
|
|
145
|
+
code: entry.code,
|
|
146
|
+
key: entry.key
|
|
147
|
+
});
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
for (const entry of entries) {
|
|
152
|
+
if (typeof entry.selectable !== "boolean") {
|
|
153
|
+
errors.push({
|
|
154
|
+
invariant: "C5",
|
|
155
|
+
message: `selectable must be a boolean, got ${typeof entry.selectable}`,
|
|
156
|
+
code: entry.code,
|
|
157
|
+
key: entry.key
|
|
158
|
+
});
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
if (options.mechanismKeys) {
|
|
162
|
+
for (const entry of entries) {
|
|
163
|
+
const raw = entry["relevantMechanisms"];
|
|
164
|
+
if (raw === void 0 || raw === null) continue;
|
|
165
|
+
if (!Array.isArray(raw)) {
|
|
166
|
+
errors.push({
|
|
167
|
+
invariant: "C6",
|
|
168
|
+
message: `relevantMechanisms must be an array or null`,
|
|
169
|
+
code: entry.code,
|
|
170
|
+
key: entry.key
|
|
171
|
+
});
|
|
172
|
+
continue;
|
|
173
|
+
}
|
|
174
|
+
for (const mechKey of raw) {
|
|
175
|
+
if (typeof mechKey !== "string" || !options.mechanismKeys.has(mechKey)) {
|
|
176
|
+
errors.push({
|
|
177
|
+
invariant: "C6",
|
|
178
|
+
message: `relevantMechanisms references unknown service_mechanisms key: ${String(mechKey)}`,
|
|
179
|
+
code: entry.code,
|
|
180
|
+
key: entry.key
|
|
181
|
+
});
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
const walkForProvided = (value, entry) => {
|
|
187
|
+
if (value === null || value === void 0) return;
|
|
188
|
+
if (Array.isArray(value)) {
|
|
189
|
+
for (const item of value) walkForProvided(item, entry);
|
|
190
|
+
return;
|
|
191
|
+
}
|
|
192
|
+
if (typeof value === "object") {
|
|
193
|
+
for (const [k, v] of Object.entries(value)) {
|
|
194
|
+
if (k === "provided") {
|
|
195
|
+
errors.push({
|
|
196
|
+
invariant: "C8",
|
|
197
|
+
message: `entry contains forbidden legacy key 'provided' (see locked spec \xA74)`,
|
|
198
|
+
code: entry.code,
|
|
199
|
+
key: entry.key
|
|
200
|
+
});
|
|
201
|
+
}
|
|
202
|
+
walkForProvided(v, entry);
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
};
|
|
206
|
+
for (const entry of entries) {
|
|
207
|
+
walkForProvided(entry, entry);
|
|
208
|
+
if (entry.key === "provided") {
|
|
209
|
+
errors.push({
|
|
210
|
+
invariant: "C8",
|
|
211
|
+
message: `entry key must not be the legacy label 'provided'`,
|
|
212
|
+
code: entry.code,
|
|
213
|
+
key: entry.key
|
|
214
|
+
});
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
return errors;
|
|
218
|
+
}
|
|
219
|
+
export {
|
|
220
|
+
CvcCodeSchema,
|
|
221
|
+
CvcEntrySchema,
|
|
222
|
+
CvcEnvelopeSchema,
|
|
223
|
+
CvcKeySchema,
|
|
224
|
+
ServiceCategoryEntrySchema,
|
|
225
|
+
getCvcLevel,
|
|
226
|
+
validateCvc
|
|
227
|
+
};
|
|
228
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../../src/validation/cvc.ts"],"sourcesContent":["/**\n * @htilabs/platform-common-models — Controlled Vocabulary (CVC) Validation\n *\n * Zod schemas for validating CVC Source-of-Truth (SOT) JSON files and\n * individual CVC entries. Implements the locked spec §9.2 shapes.\n *\n * Used by:\n * - CI structural tests that parse every committed SOT file.\n * - The generalized seed CLI (`seedCvc`) prior to persistence.\n * - Downstream consumers that need to validate CVC payloads.\n *\n * Canonical spec:\n * /gt/docs/data/cvcs/CVC Implementation Spec 2780449faf8045258c67daab0f1c5569.md\n *\n * Locked decisions (2026-04-10):\n * - Positional 7-segment codes `XX-XX-XX-XX-XX-XX-XX` (§3).\n * - `missingness` envelope field is an optional `string[]`; `[\"all\"]` is the\n * sentinel meaning \"merge all missingness values\" (§2.1, §5.2).\n * - `missingness.v1.0.0.json` wraps its values under a synthetic root\n * (`missingness_root`) which is the one sanctioned parent-child exception\n * for level-consistency, scoped by segment-1 domain prefix (§5.1).\n */\n\nimport { z } from \"zod\";\n\n// ─── Primitive schemas ───────────────────────────────────────────────────────\n\n/**\n * 7-segment positional CVC code: `XX-XX-XX-XX-XX-XX-XX` (two digits per\n * segment). Segments are filled left-to-right as levels deepen; unused\n * segments remain `00`. See locked spec §3.\n */\nexport const CvcCodeSchema = z.string().regex(/^\\d{2}(-\\d{2}){6}$/);\n\n/**\n * Stable machine key for a CVC entry. Must start with a lowercase letter and\n * contain only lowercase alphanumerics or underscores. Used as a cross-CVC\n * reference target (e.g. `relevantMechanisms` pointing at mechanism keys).\n * See locked spec §3.2.\n */\nexport const CvcKeySchema = z.string().regex(/^[a-z][a-z0-9_]*$/);\n\n// ─── Entry schemas ───────────────────────────────────────────────────────────\n\n/**\n * Base entry shape shared by every CVC domain. Domain-specific extensions\n * (e.g. `ServiceCategoryEntrySchema`) should use `.extend()` to add fields.\n * See locked spec §9.2.\n *\n * Uses `.passthrough()` so that domain-specific fields (like\n * `relevantMechanisms` on service-category entries) survive base parsing\n * unmodified. This keeps cross-CVC reference validation honest: the §4.5\n * structural validator needs to see the raw referenced keys, and a strip-by-\n * default schema would silently hide them.\n */\nexport const CvcEntrySchema = z\n .object({\n code: CvcCodeSchema,\n key: CvcKeySchema,\n title: z.string().min(1),\n selectable: z.boolean(),\n parentCode: CvcCodeSchema.nullable(),\n childCodes: z.array(CvcCodeSchema),\n definition: z.string().nullable(),\n })\n .passthrough();\n\n/**\n * Service-category-specific entry. Adds `relevantMechanisms` — a cross-CVC\n * reference into the `service_mechanisms` domain via entry keys. `null` means\n * \"not applicable\" (e.g. structural L1 topic rows). See locked spec §9.2.\n */\nexport const ServiceCategoryEntrySchema = CvcEntrySchema.extend({\n relevantMechanisms: z.array(CvcKeySchema).nullable(),\n});\n\n// ─── Envelope schema ─────────────────────────────────────────────────────────\n\n/**\n * Top-level SOT JSON envelope. One envelope per (domain, version) pair.\n *\n * `missingness` is an optional array of missingness keys to merge into this\n * CVC at seed time. `[\"all\"]` is the sentinel meaning \"merge the missingness\n * root plus all three value entries\". Individual keys merge only those.\n * Absent, empty, or null means \"skip missingness merge\". The missingness CVC\n * file itself omits this field because merging missingness into itself is\n * nonsensical. See locked spec §2.1 and §5.2.\n *\n * `levels` is a positional map from level number (`\"0\"`, `\"1\"`, …) to a human\n * label describing the level.\n */\nexport const CvcEnvelopeSchema = z.object({\n domain: z.string().min(1),\n name: z.string().min(1),\n version: z.string().min(1),\n missingness: z.array(z.string()).optional(),\n levels: z.record(z.string(), z.string()),\n entries: z.array(CvcEntrySchema),\n});\n\n// ─── Inferred types ──────────────────────────────────────────────────────────\n\nexport type CvcCode = z.infer<typeof CvcCodeSchema>;\nexport type CvcKey = z.infer<typeof CvcKeySchema>;\nexport type CvcEntry = z.infer<typeof CvcEntrySchema>;\nexport type ServiceCategoryEntry = z.infer<typeof ServiceCategoryEntrySchema>;\nexport type CvcEnvelope = z.infer<typeof CvcEnvelopeSchema>;\n\n/**\n * SOT family identifier (e.g. `\"service_categories\"`, `\"service_states\"`,\n * `\"service_mechanisms\"`, `\"missingness\"`). The canonical list of domains is\n * enumerated by the SOT JSON files in `src/cvcs/`. Typed as `string` rather\n * than a closed union so adding a new SOT file does not require touching this\n * type. See locked spec §2.\n */\nexport type CvcDomain = string;\n\n// ─── Structural validator (locked spec §4 / §9.3) ───────────────────────────\n\n/**\n * Derive an entry's level from its 7-segment code per locked spec §3.3.\n *\n * - Segment 7 non-zero → level 0 (missingness value entry, e.g. `unknown`).\n * - Otherwise return the index (1..5) of the last non-zero hierarchy segment.\n * - All segments zero → level 0 (missingness root, `00-00-00-00-00-00-00`).\n */\nexport function getCvcLevel(code: string): number {\n const segments = code.split(\"-\");\n // segments[6] is the missingness slot (positional segment 7).\n if (segments[6] !== \"00\") return 0;\n // Walk hierarchy segments 6..2 (indices 5..1) looking for the deepest\n // populated level.\n for (let i = 5; i >= 1; i -= 1) {\n if (segments[i] !== \"00\") return i;\n }\n return 0;\n}\n\n/**\n * Error collected by {@link validateCvc}. Each error names the invariant it\n * violates (`C1`..`C8`) so CI output points straight at the locked spec rule\n * that failed. `code` or `key` narrow the error to a specific entry when the\n * violation is entry-scoped.\n */\nexport interface CvcValidationError {\n invariant: \"C1\" | \"C2\" | \"C3\" | \"C4\" | \"C5\" | \"C6\" | \"C7\" | \"C8\";\n message: string;\n code?: string;\n key?: string;\n}\n\n/**\n * Structural invariants to enforce on every committed SOT file per locked spec\n * §4. Zod's schema `parse()` guarantees the *shape* of the envelope; this\n * function enforces the cross-entry *semantics* that Zod cannot express.\n *\n * Invariants (locked spec §4):\n * - **C1** Code format + uniqueness (§4.1).\n * - **C2** Key format + uniqueness (§4.2).\n * - **C3** Tree: every `parentCode` resolves to an existing entry or null; no\n * cycles (§4.3).\n * - **C4** `childCodes` are the exact bidirectional inverse of `parentCode`\n * (§4.3).\n * - **C5** Selectability is a boolean (§4.4).\n * - **C6** Cross-CVC `relevantMechanisms` references resolve against a\n * provided `service_mechanisms` key set (§4.5, §7). Only checked when the\n * caller supplies `options.mechanismKeys`.\n * - **C7** Envelope has all 6 required fields (`domain`, `name`, `version`,\n * `missingness`, `levels`, `entries`) — treating the optional-in-Zod\n * `missingness` as required at CI time (§4.6).\n * - **C8** No entry anywhere contains a key `'provided'` (legacy Thread UI\n * label guard; not a canonical state).\n *\n * @param envelope Parsed envelope (typically from `CvcEnvelopeSchema.parse()`).\n * @param options.mechanismKeys Optional set of valid `service_mechanisms`\n * entry keys. If provided and the envelope entries have `relevantMechanisms`\n * fields, each referenced key must be in this set (C6).\n * @returns An array of {@link CvcValidationError}. An empty array means valid.\n */\nexport function validateCvc(\n envelope: CvcEnvelope,\n options: { mechanismKeys?: ReadonlySet<string> } = {},\n): CvcValidationError[] {\n const errors: CvcValidationError[] = [];\n const { entries } = envelope;\n\n // C7: envelope-level required fields. Zod already rejects missing `domain`,\n // `name`, `version`, `levels`, and `entries`. We additionally require\n // `missingness` to be present (even as an empty array) at CI time so the\n // seed CLI sees an explicit \"opt-out\" rather than an undefined field.\n //\n // Exemption: the `missingness` CVC file itself legitimately omits this\n // field because merging missingness into itself is nonsensical (locked spec\n // §9.2). This is the one sanctioned omission.\n if (envelope.domain !== \"missingness\" && envelope.missingness === undefined) {\n errors.push({\n invariant: \"C7\",\n message:\n \"envelope is missing required field `missingness` (must be an array, \" +\n \"use `[]` to opt out of the missingness merge)\",\n });\n }\n\n // ── C1: code format + uniqueness ──────────────────────────────────────────\n const codeRe = /^\\d{2}(-\\d{2}){6}$/;\n const seenCodes = new Set<string>();\n for (const entry of entries) {\n if (!codeRe.test(entry.code)) {\n errors.push({\n invariant: \"C1\",\n message: `code does not match /^\\\\d{2}(-\\\\d{2}){6}$/`,\n code: entry.code,\n key: entry.key,\n });\n }\n if (seenCodes.has(entry.code)) {\n errors.push({\n invariant: \"C1\",\n message: `duplicate code`,\n code: entry.code,\n key: entry.key,\n });\n }\n seenCodes.add(entry.code);\n }\n\n // ── C2: key format + uniqueness ───────────────────────────────────────────\n const keyRe = /^[a-z][a-z0-9_]*$/;\n const seenKeys = new Set<string>();\n for (const entry of entries) {\n if (!keyRe.test(entry.key)) {\n errors.push({\n invariant: \"C2\",\n message: `key does not match /^[a-z][a-z0-9_]*$/`,\n code: entry.code,\n key: entry.key,\n });\n }\n if (seenKeys.has(entry.key)) {\n errors.push({\n invariant: \"C2\",\n message: `duplicate key`,\n code: entry.code,\n key: entry.key,\n });\n }\n seenKeys.add(entry.key);\n }\n\n // Build a lookup by code for the remaining tree checks. Skip entries whose\n // code we already know is malformed — their index would be meaningless.\n const byCode = new Map<string, CvcEntry>();\n for (const entry of entries) {\n if (codeRe.test(entry.code)) byCode.set(entry.code, entry);\n }\n\n // ── C3: tree — parents resolve, no cycles ─────────────────────────────────\n for (const entry of entries) {\n if (entry.parentCode === null) continue;\n if (!byCode.has(entry.parentCode)) {\n errors.push({\n invariant: \"C3\",\n message: `parentCode ${entry.parentCode} does not resolve to any entry in this CVC`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n\n // Cycle detection: walk parent chain from each entry, bail if we revisit.\n for (const entry of entries) {\n const visited = new Set<string>();\n let cursor: CvcEntry | undefined = entry;\n while (cursor && cursor.parentCode !== null) {\n if (visited.has(cursor.code)) {\n errors.push({\n invariant: \"C3\",\n message: `cycle detected in parentCode chain starting from ${entry.code}`,\n code: entry.code,\n key: entry.key,\n });\n break;\n }\n visited.add(cursor.code);\n cursor = byCode.get(cursor.parentCode);\n }\n }\n\n // ── C4: childCodes are exact inverse of parentCode ────────────────────────\n // Build the set of (parent, child) edges from parentCode, then from\n // childCodes, and require they match exactly.\n const parentToChildrenFromParent = new Map<string, Set<string>>();\n for (const entry of entries) {\n if (entry.parentCode !== null) {\n let set = parentToChildrenFromParent.get(entry.parentCode);\n if (!set) {\n set = new Set();\n parentToChildrenFromParent.set(entry.parentCode, set);\n }\n set.add(entry.code);\n }\n }\n\n for (const entry of entries) {\n const declared = new Set(entry.childCodes);\n const derived = parentToChildrenFromParent.get(entry.code) ?? new Set();\n\n for (const child of declared) {\n if (!derived.has(child)) {\n errors.push({\n invariant: \"C4\",\n message: `entry lists ${child} in childCodes but that entry's parentCode is not ${entry.code}`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n for (const child of derived) {\n if (!declared.has(child)) {\n errors.push({\n invariant: \"C4\",\n message: `entry ${child} has parentCode ${entry.code} but is missing from its childCodes`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n }\n\n // ── C5: selectability per §4.4 ────────────────────────────────────────────\n // Zod already enforces `selectable: boolean`; we make the invariant explicit\n // at validator level so a future schema loosening cannot silently bypass it.\n for (const entry of entries) {\n if (typeof entry.selectable !== \"boolean\") {\n errors.push({\n invariant: \"C5\",\n message: `selectable must be a boolean, got ${typeof entry.selectable}`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n\n // ── C6: cross-CVC refs — `relevantMechanisms` resolves against provided set\n if (options.mechanismKeys) {\n for (const entry of entries) {\n const raw = (entry as unknown as Record<string, unknown>)[\n \"relevantMechanisms\"\n ];\n if (raw === undefined || raw === null) continue;\n if (!Array.isArray(raw)) {\n errors.push({\n invariant: \"C6\",\n message: `relevantMechanisms must be an array or null`,\n code: entry.code,\n key: entry.key,\n });\n continue;\n }\n for (const mechKey of raw) {\n if (\n typeof mechKey !== \"string\" ||\n !options.mechanismKeys.has(mechKey)\n ) {\n errors.push({\n invariant: \"C6\",\n message: `relevantMechanisms references unknown service_mechanisms key: ${String(mechKey)}`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n }\n }\n\n // ── C8: legacy `'provided'` key guard ─────────────────────────────────────\n // Walk every property of every entry (including nested arrays) looking for\n // a key named `'provided'`. It is a Thread UI label, not a canonical state.\n const walkForProvided = (value: unknown, entry: CvcEntry): void => {\n if (value === null || value === undefined) return;\n if (Array.isArray(value)) {\n for (const item of value) walkForProvided(item, entry);\n return;\n }\n if (typeof value === \"object\") {\n for (const [k, v] of Object.entries(value as Record<string, unknown>)) {\n if (k === \"provided\") {\n errors.push({\n invariant: \"C8\",\n message: `entry contains forbidden legacy key 'provided' (see locked spec §4)`,\n code: entry.code,\n key: entry.key,\n });\n }\n walkForProvided(v, entry);\n }\n }\n };\n for (const entry of entries) {\n walkForProvided(entry, entry);\n // Also guard against a literal string value of 'provided' appearing as an\n // entry's `key`, which would be an obvious smuggling attempt.\n if (entry.key === \"provided\") {\n errors.push({\n invariant: \"C8\",\n message: `entry key must not be the legacy label 'provided'`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n\n return errors;\n}\n"],"mappings":"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","names":[]}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@htilabs/platform-common-models",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0-beta.5",
|
|
4
4
|
"description": "Shared constants, types, and models for HTI Labs applications",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.cjs",
|
|
@@ -31,21 +31,27 @@
|
|
|
31
31
|
"types": "./dist/models/index.d.ts",
|
|
32
32
|
"import": "./dist/models/index.js",
|
|
33
33
|
"require": "./dist/models/index.cjs"
|
|
34
|
+
},
|
|
35
|
+
"./services": {
|
|
36
|
+
"types": "./dist/services/index.d.ts",
|
|
37
|
+
"import": "./dist/services/index.js",
|
|
38
|
+
"require": "./dist/services/index.cjs"
|
|
39
|
+
},
|
|
40
|
+
"./validation": {
|
|
41
|
+
"types": "./dist/validation/index.d.ts",
|
|
42
|
+
"import": "./dist/validation/index.js",
|
|
43
|
+
"require": "./dist/validation/index.cjs"
|
|
44
|
+
},
|
|
45
|
+
"./cvcs": {
|
|
46
|
+
"types": "./dist/cvcs/index.d.ts",
|
|
47
|
+
"import": "./dist/cvcs/index.js",
|
|
48
|
+
"require": "./dist/cvcs/index.cjs"
|
|
34
49
|
}
|
|
35
50
|
},
|
|
36
51
|
"files": [
|
|
37
52
|
"dist",
|
|
38
53
|
"src"
|
|
39
54
|
],
|
|
40
|
-
"scripts": {
|
|
41
|
-
"build": "tsup",
|
|
42
|
-
"dev": "tsup --watch",
|
|
43
|
-
"typecheck": "tsc --noEmit",
|
|
44
|
-
"lint": "eslint src --ext .ts",
|
|
45
|
-
"lint:fix": "eslint src --ext .ts --fix",
|
|
46
|
-
"clean": "rm -rf dist",
|
|
47
|
-
"prepublishOnly": "npm run build"
|
|
48
|
-
},
|
|
49
55
|
"keywords": [
|
|
50
56
|
"hti",
|
|
51
57
|
"platform-common",
|
|
@@ -62,7 +68,9 @@
|
|
|
62
68
|
"eslint": "^8.57.0",
|
|
63
69
|
"mongoose": "^9.3.1",
|
|
64
70
|
"tsup": "^8.0.0",
|
|
65
|
-
"
|
|
71
|
+
"tsx": "^4.19.0",
|
|
72
|
+
"typescript": "^5.3.0",
|
|
73
|
+
"vitest": "^1.6.1"
|
|
66
74
|
},
|
|
67
75
|
"dependencies": {
|
|
68
76
|
"zod": "^3.22.0"
|
|
@@ -77,5 +85,21 @@
|
|
|
77
85
|
},
|
|
78
86
|
"engines": {
|
|
79
87
|
"node": ">=18.0.0"
|
|
88
|
+
},
|
|
89
|
+
"scripts": {
|
|
90
|
+
"build": "tsup",
|
|
91
|
+
"dev": "tsup --watch",
|
|
92
|
+
"typecheck": "tsc --noEmit && tsc --noEmit -p scripts/tsconfig.json",
|
|
93
|
+
"lint": "eslint src --ext .ts",
|
|
94
|
+
"lint:fix": "eslint src --ext .ts --fix",
|
|
95
|
+
"test": "vitest run",
|
|
96
|
+
"test:watch": "vitest",
|
|
97
|
+
"test:snapshot": "UPDATE_SNAPSHOT=1 vitest run",
|
|
98
|
+
"clean": "rm -rf dist",
|
|
99
|
+
"codegen:cvc": "tsx scripts/codegen-cvc-enums.ts",
|
|
100
|
+
"codegen:cvc:check": "tsx scripts/codegen-cvc-enums.ts --check",
|
|
101
|
+
"seed:cvc": "tsx scripts/seed-cvc.ts",
|
|
102
|
+
"seed:cvc:all": "tsx scripts/seed-all-cvcs.ts",
|
|
103
|
+
"test:seed": "node --import tsx --test scripts/seed-cvc.test.ts"
|
|
80
104
|
}
|
|
81
|
-
}
|
|
105
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
{
|
|
2
|
+
"version": 1,
|
|
3
|
+
"generated": "run `npm run test:snapshot` to regenerate",
|
|
4
|
+
"cvcs": {
|
|
5
|
+
"missingness": {
|
|
6
|
+
"count": 4,
|
|
7
|
+
"hash": "bce1ba0b47f4f33ab02db42abd77e29f39def976aed6a5aa8b22b21f4b46566a"
|
|
8
|
+
},
|
|
9
|
+
"service_mechanisms": {
|
|
10
|
+
"count": 4,
|
|
11
|
+
"hash": "9a1040dff253dd97f05b91dd15d19f9e95543c39a002f8b3faedf5886b080571"
|
|
12
|
+
},
|
|
13
|
+
"service_states": {
|
|
14
|
+
"count": 10,
|
|
15
|
+
"hash": "f8cee319292546557408eed104b81d7286e2c8ee46bed1620083e9a01c0635cc"
|
|
16
|
+
},
|
|
17
|
+
"service_categories": {
|
|
18
|
+
"count": 147,
|
|
19
|
+
"hash": "4829fb73888e7072108020c8716adab16a09bda52a8570a1ded2de23e95d0f51"
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
}
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* CVC SOT Snapshot CI Test
|
|
3
|
+
*
|
|
4
|
+
* Catches unreviewed drift in any committed SOT JSON file via two locks:
|
|
5
|
+
*
|
|
6
|
+
* 1. **Row count per CVC** — hardcoded against locked spec §1 + §8 scope
|
|
7
|
+
* numbers. A one-off delta is a loud failure, not a silent rebalance.
|
|
8
|
+
*
|
|
9
|
+
* 2. **Normalized content hash per CVC** — SHA256 over a canonicalized
|
|
10
|
+
* JSON rendering (recursively sorted object keys, compact serialization,
|
|
11
|
+
* no incidental whitespace). Stored in `__snapshots__/cvc-sot.snap` as
|
|
12
|
+
* a committed JSON file. Any change to SOT content fails CI until the
|
|
13
|
+
* developer explicitly regenerates the snapshot:
|
|
14
|
+
*
|
|
15
|
+
* UPDATE_SNAPSHOT=1 npm test
|
|
16
|
+
* # or: npm run test:snapshot
|
|
17
|
+
*
|
|
18
|
+
* Regenerating is a deliberate act recorded in git, so drift is
|
|
19
|
+
* always visible in review.
|
|
20
|
+
*
|
|
21
|
+
* 3. **`'provided'` grep guard** — string-level assertion that the legacy
|
|
22
|
+
* Thread UI label key does not appear anywhere in the raw SOT JSON.
|
|
23
|
+
* This is redundant with the structural validator's C8 check but
|
|
24
|
+
* cheap and catches smuggling attempts that might bypass the Zod
|
|
25
|
+
* parser (e.g. stray string values).
|
|
26
|
+
*/
|
|
27
|
+
|
|
28
|
+
import { createHash } from "node:crypto";
|
|
29
|
+
import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
|
|
30
|
+
import path from "node:path";
|
|
31
|
+
import { fileURLToPath } from "node:url";
|
|
32
|
+
|
|
33
|
+
import { describe, it, expect } from "vitest";
|
|
34
|
+
|
|
35
|
+
// ─── Paths ──────────────────────────────────────────────────────────────────
|
|
36
|
+
|
|
37
|
+
const __filename = fileURLToPath(import.meta.url);
|
|
38
|
+
const __dirname = path.dirname(__filename);
|
|
39
|
+
const CVCS_DIR = path.resolve(__dirname, "..", "cvcs");
|
|
40
|
+
const SNAPSHOT_DIR = path.resolve(__dirname, "__snapshots__");
|
|
41
|
+
const SNAPSHOT_FILE = path.join(SNAPSHOT_DIR, "cvc-sot.snap");
|
|
42
|
+
|
|
43
|
+
// ─── SOT files + locked row counts (spec §1, §8) ───────────────────────────
|
|
44
|
+
|
|
45
|
+
interface SotSpec {
|
|
46
|
+
/** Filename in `src/cvcs/`. */
|
|
47
|
+
file: string;
|
|
48
|
+
/** Domain name as stored in the envelope. */
|
|
49
|
+
domain: string;
|
|
50
|
+
/**
|
|
51
|
+
* Expected entry count. Sourced from locked spec §1 (Scope) and §8
|
|
52
|
+
* (Domain Details). Includes the missingness root entry for the
|
|
53
|
+
* missingness domain per §8.4 (1 root + 3 values = 4 total).
|
|
54
|
+
*/
|
|
55
|
+
expectedCount: number;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
const SOT_SPECS: readonly SotSpec[] = [
|
|
59
|
+
// Spec §8.4 — "Entries: 4 (1 structural root + 3 values)"
|
|
60
|
+
{ file: "missingness.v1.0.0.json", domain: "missingness", expectedCount: 4 },
|
|
61
|
+
// Spec §8.3 — "Entries: 4"
|
|
62
|
+
{ file: "serviceMechanisms.v1.0.0.json", domain: "service_mechanisms", expectedCount: 4 },
|
|
63
|
+
// Spec §8.2 — "Entries: 10"
|
|
64
|
+
{ file: "serviceStates.v1.0.0.json", domain: "service_states", expectedCount: 10 },
|
|
65
|
+
// Spec §8.1 — "Entries: 147"
|
|
66
|
+
{ file: "serviceCategories.v1.0.0.json", domain: "service_categories", expectedCount: 147 },
|
|
67
|
+
] as const;
|
|
68
|
+
|
|
69
|
+
// ─── Helpers ────────────────────────────────────────────────────────────────
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Recursively sort object keys so the serialization is deterministic
|
|
73
|
+
* regardless of key insertion order in the source JSON. Arrays are NOT
|
|
74
|
+
* sorted — their order is semantically meaningful (entry order, childCodes).
|
|
75
|
+
*/
|
|
76
|
+
function canonicalize(value: unknown): unknown {
|
|
77
|
+
if (value === null || typeof value !== "object") return value;
|
|
78
|
+
if (Array.isArray(value)) return value.map(canonicalize);
|
|
79
|
+
const obj = value as Record<string, unknown>;
|
|
80
|
+
const sortedKeys = Object.keys(obj).sort();
|
|
81
|
+
const out: Record<string, unknown> = {};
|
|
82
|
+
for (const key of sortedKeys) out[key] = canonicalize(obj[key]);
|
|
83
|
+
return out;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* Compute a SHA256 hash of the canonicalized JSON representation of a SOT
|
|
88
|
+
* file. Stable across commit order and whitespace.
|
|
89
|
+
*/
|
|
90
|
+
function hashSot(raw: unknown): string {
|
|
91
|
+
const canonical = JSON.stringify(canonicalize(raw));
|
|
92
|
+
return createHash("sha256").update(canonical).digest("hex");
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
interface SotSnapshot {
|
|
96
|
+
version: 1;
|
|
97
|
+
generated: string; // comment-style marker; not used for comparison
|
|
98
|
+
cvcs: Record<string, { count: number; hash: string }>;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
function buildCurrentSnapshot(): SotSnapshot {
|
|
102
|
+
const cvcs: Record<string, { count: number; hash: string }> = {};
|
|
103
|
+
for (const spec of SOT_SPECS) {
|
|
104
|
+
const raw = JSON.parse(
|
|
105
|
+
readFileSync(path.join(CVCS_DIR, spec.file), "utf-8"),
|
|
106
|
+
) as { entries: unknown[] };
|
|
107
|
+
cvcs[spec.domain] = {
|
|
108
|
+
count: raw.entries.length,
|
|
109
|
+
hash: hashSot(raw),
|
|
110
|
+
};
|
|
111
|
+
}
|
|
112
|
+
return {
|
|
113
|
+
version: 1,
|
|
114
|
+
generated: "run `npm run test:snapshot` to regenerate",
|
|
115
|
+
cvcs,
|
|
116
|
+
};
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
function readCommittedSnapshot(): SotSnapshot | null {
|
|
120
|
+
if (!existsSync(SNAPSHOT_FILE)) return null;
|
|
121
|
+
const txt = readFileSync(SNAPSHOT_FILE, "utf-8");
|
|
122
|
+
return JSON.parse(txt) as SotSnapshot;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
function writeSnapshot(snap: SotSnapshot): void {
|
|
126
|
+
if (!existsSync(SNAPSHOT_DIR)) mkdirSync(SNAPSHOT_DIR, { recursive: true });
|
|
127
|
+
writeFileSync(SNAPSHOT_FILE, `${JSON.stringify(snap, null, 2)}\n`, "utf-8");
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
const UPDATING = process.env["UPDATE_SNAPSHOT"] === "1";
|
|
131
|
+
|
|
132
|
+
// ─── Tests ──────────────────────────────────────────────────────────────────
|
|
133
|
+
|
|
134
|
+
describe("CVC SOT row counts (locked spec §1, §8)", () => {
|
|
135
|
+
for (const spec of SOT_SPECS) {
|
|
136
|
+
it(`${spec.domain} has exactly ${spec.expectedCount} entries`, () => {
|
|
137
|
+
const raw = JSON.parse(
|
|
138
|
+
readFileSync(path.join(CVCS_DIR, spec.file), "utf-8"),
|
|
139
|
+
) as { entries: unknown[] };
|
|
140
|
+
expect(raw.entries.length).toBe(spec.expectedCount);
|
|
141
|
+
});
|
|
142
|
+
}
|
|
143
|
+
});
|
|
144
|
+
|
|
145
|
+
describe("CVC SOT content hash snapshot", () => {
|
|
146
|
+
it("matches committed __snapshots__/cvc-sot.snap", () => {
|
|
147
|
+
const current = buildCurrentSnapshot();
|
|
148
|
+
|
|
149
|
+
if (UPDATING) {
|
|
150
|
+
// Explicit developer opt-in via UPDATE_SNAPSHOT=1. Persist the current
|
|
151
|
+
// hashes and let the assertion pass trivially. The regenerated file
|
|
152
|
+
// will show up in git diff and must be reviewed before merge.
|
|
153
|
+
writeSnapshot(current);
|
|
154
|
+
expect(current).toEqual(current);
|
|
155
|
+
return;
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
const committed = readCommittedSnapshot();
|
|
159
|
+
if (committed === null) {
|
|
160
|
+
throw new Error(
|
|
161
|
+
`No committed snapshot at ${path.relative(
|
|
162
|
+
process.cwd(),
|
|
163
|
+
SNAPSHOT_FILE,
|
|
164
|
+
)}. Run \`npm run test:snapshot\` to generate one, then commit it.`,
|
|
165
|
+
);
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
// Compare cvcs map only; ignore `generated` comment field.
|
|
169
|
+
expect(current.cvcs).toEqual(committed.cvcs);
|
|
170
|
+
});
|
|
171
|
+
});
|
|
172
|
+
|
|
173
|
+
describe("CVC SOT legacy `'provided'` key guard (C8 redundant string check)", () => {
|
|
174
|
+
for (const spec of SOT_SPECS) {
|
|
175
|
+
it(`${spec.file} does not contain the literal key "provided"`, () => {
|
|
176
|
+
const txt = readFileSync(path.join(CVCS_DIR, spec.file), "utf-8");
|
|
177
|
+
// Match only on a JSON property-name position: `"provided":`. A JSON
|
|
178
|
+
// property name is always double-quoted and followed by a colon, so
|
|
179
|
+
// this won't false-positive on prose in a `definition` field that
|
|
180
|
+
// happens to use the word "provided".
|
|
181
|
+
expect(txt).not.toMatch(/"provided"\s*:/);
|
|
182
|
+
});
|
|
183
|
+
}
|
|
184
|
+
});
|