|
| 1 | +// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. |
| 2 | + |
| 3 | +/** |
| 4 | + * Build-time semantic-role diagnostics (ADR-0085). |
| 5 | + * |
| 6 | + * The object-level semantic roles (`stageField`, `highlightFields` / |
| 7 | + * deprecated `compactLayout`, `fieldGroups` + `Field.group`) are pointers |
| 8 | + * into the object's own field map. A dangling pointer is Zod-valid but |
| 9 | + * silently inert at render time — the exact "parsed, unmarked, silently |
| 10 | + * inert" shape ADR-0078 prohibits — so the completeness lint flags it here, |
| 11 | + * uniformly for `os build`/`os validate`, MCP authoring and hand authors. |
| 12 | + * |
| 13 | + * All three rules are warnings, not errors: every consumer degrades |
| 14 | + * gracefully (an unknown `Field.group` renders in the ungrouped bucket, an |
| 15 | + * unknown highlight name is skipped, an unknown `stageField` falls back to |
| 16 | + * heuristics), so nothing is fully broken — but the author almost certainly |
| 17 | + * typo'd a name and should be told at author time, not discover it by |
| 18 | + * staring at an unchanged page. |
| 19 | + */ |
| 20 | + |
| 21 | +export const FIELD_GROUP_UNDECLARED = 'field-group-undeclared'; |
| 22 | +export const FIELD_GROUP_EMPTY = 'field-group-empty'; |
| 23 | +export const SEMANTIC_ROLE_FIELD_UNKNOWN = 'semantic-role-field-unknown'; |
| 24 | + |
| 25 | +export type SemanticRoleSeverity = 'error' | 'warning'; |
| 26 | + |
| 27 | +export interface SemanticRoleFinding { |
| 28 | + /** Always `warning` today — all three rules are advisory (see module note). */ |
| 29 | + severity: SemanticRoleSeverity; |
| 30 | + /** Diagnostic rule id, e.g. `field-group-undeclared`. */ |
| 31 | + rule: string; |
| 32 | + /** Human-readable location, e.g. `object "invoice"`. */ |
| 33 | + where: string; |
| 34 | + /** Config path, e.g. `objects[3]`. */ |
| 35 | + path: string; |
| 36 | + /** What is wrong. */ |
| 37 | + message: string; |
| 38 | + /** How to fix it. */ |
| 39 | + hint: string; |
| 40 | +} |
| 41 | + |
| 42 | +type AnyRec = Record<string, unknown>; |
| 43 | + |
| 44 | +/** Coerce a collection (array or name-keyed map) to an array of records. */ |
| 45 | +function asArray(v: unknown): AnyRec[] { |
| 46 | + if (Array.isArray(v)) return v as AnyRec[]; |
| 47 | + if (v && typeof v === 'object') { |
| 48 | + return Object.entries(v as AnyRec).map(([name, def]) => ({ name, ...(def as AnyRec) })); |
| 49 | + } |
| 50 | + return []; |
| 51 | +} |
| 52 | + |
| 53 | +/** |
| 54 | + * Validate every object's semantic-role pointers. Returns the list of |
| 55 | + * findings (empty = clean). Advisory only — the caller must never fail the |
| 56 | + * build on these alone. |
| 57 | + */ |
| 58 | +export function validateSemanticRoles(stack: AnyRec): SemanticRoleFinding[] { |
| 59 | + const findings: SemanticRoleFinding[] = []; |
| 60 | + |
| 61 | + const objects = asArray(stack.objects); |
| 62 | + for (let i = 0; i < objects.length; i++) { |
| 63 | + const obj = objects[i]; |
| 64 | + if (!obj || typeof obj !== 'object') continue; // tolerate junk entries |
| 65 | + const objName = typeof obj.name === 'string' ? obj.name : `(object ${i})`; |
| 66 | + const where = `object "${objName}"`; |
| 67 | + const path = `objects[${i}]`; |
| 68 | + |
| 69 | + const fields = (obj.fields && typeof obj.fields === 'object' && !Array.isArray(obj.fields)) |
| 70 | + ? (obj.fields as Record<string, AnyRec | undefined>) |
| 71 | + : {}; |
| 72 | + const fieldNames = new Set(Object.keys(fields)); |
| 73 | + |
| 74 | + // ── (a) Field.group → declared fieldGroups[].key ── |
| 75 | + const declaredGroups = new Set( |
| 76 | + (Array.isArray(obj.fieldGroups) ? obj.fieldGroups : []) |
| 77 | + .filter((g): g is AnyRec => !!g && typeof g === 'object') |
| 78 | + .map((g) => g.key) |
| 79 | + .filter((k): k is string => typeof k === 'string' && k.length > 0), |
| 80 | + ); |
| 81 | + const referencedGroups = new Set<string>(); |
| 82 | + for (const [fname, f] of Object.entries(fields)) { |
| 83 | + const g = f?.group; |
| 84 | + if (typeof g !== 'string' || g.length === 0) continue; |
| 85 | + referencedGroups.add(g); |
| 86 | + if (!declaredGroups.has(g)) { |
| 87 | + findings.push({ |
| 88 | + severity: 'warning', |
| 89 | + rule: FIELD_GROUP_UNDECLARED, |
| 90 | + where, |
| 91 | + path: `${path}.fields.${fname}.group`, |
| 92 | + message: |
| 93 | + `${objName}.${fname}: group "${g}" is not declared in fieldGroups — ` + |
| 94 | + `the field renders in the ungrouped bucket, not under "${g}"`, |
| 95 | + hint: |
| 96 | + `Declare { key: '${g}', label: '…' } in ${objName}.fieldGroups, or fix ` + |
| 97 | + `the field's group reference. Group keys are snake_case and must match exactly.`, |
| 98 | + }); |
| 99 | + } |
| 100 | + } |
| 101 | + |
| 102 | + // ── (b) declared group no field references ── |
| 103 | + for (const key of declaredGroups) { |
| 104 | + if (!referencedGroups.has(key)) { |
| 105 | + findings.push({ |
| 106 | + severity: 'warning', |
| 107 | + rule: FIELD_GROUP_EMPTY, |
| 108 | + where, |
| 109 | + path: `${path}.fieldGroups`, |
| 110 | + message: |
| 111 | + `${objName}: fieldGroups declares "${key}" but no field references it — ` + |
| 112 | + `the group never renders`, |
| 113 | + hint: |
| 114 | + `Assign at least one field via group: '${key}', or remove the unused ` + |
| 115 | + `group declaration.`, |
| 116 | + }); |
| 117 | + } |
| 118 | + } |
| 119 | + |
| 120 | + // ── (c) semantic-role pointers name real fields ── |
| 121 | + const stage = obj.stageField; |
| 122 | + if (typeof stage === 'string' && stage.length > 0 && !fieldNames.has(stage)) { |
| 123 | + findings.push({ |
| 124 | + severity: 'warning', |
| 125 | + rule: SEMANTIC_ROLE_FIELD_UNKNOWN, |
| 126 | + where, |
| 127 | + path: `${path}.stageField`, |
| 128 | + message: |
| 129 | + `${objName}: stageField "${stage}" is not a field on this object — ` + |
| 130 | + `consumers fall back to heuristic stage detection`, |
| 131 | + hint: |
| 132 | + `Point stageField at an existing select/status field, or set ` + |
| 133 | + `stageField: false to declare the object has no linear lifecycle.`, |
| 134 | + }); |
| 135 | + } |
| 136 | + |
| 137 | + const highlights = Array.isArray(obj.highlightFields) |
| 138 | + ? obj.highlightFields |
| 139 | + : Array.isArray(obj.compactLayout) // deprecated alias (pre-normalization input) |
| 140 | + ? obj.compactLayout |
| 141 | + : []; |
| 142 | + for (const entry of highlights) { |
| 143 | + if (typeof entry !== 'string' || entry.length === 0 || fieldNames.has(entry)) continue; |
| 144 | + findings.push({ |
| 145 | + severity: 'warning', |
| 146 | + rule: SEMANTIC_ROLE_FIELD_UNKNOWN, |
| 147 | + where, |
| 148 | + path: `${path}.highlightFields`, |
| 149 | + message: |
| 150 | + `${objName}: highlightFields entry "${entry}" is not a field on this ` + |
| 151 | + `object — it is silently skipped by every consumer`, |
| 152 | + hint: |
| 153 | + `Fix the field name (highlightFields drives default columns, cards, ` + |
| 154 | + `previews and the detail highlight strip, in order).`, |
| 155 | + }); |
| 156 | + } |
| 157 | + } |
| 158 | + |
| 159 | + return findings; |
| 160 | +} |
0 commit comments