@atolis-hq/corum 0.1.44 → 0.1.46

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.
@@ -1,14 +1,17 @@
1
1
  import { getEdgeTypeConstraints } from '../graph/roles.js';
2
+ import { CORE_EDGE_TYPE_MAP } from '../loader/constants.js';
3
+ import { validateNodeId } from '../loader/id-grammar.js';
2
4
  import { getTemplateSchema } from '../loader/template-props.js';
3
5
  /**
4
6
  * Full linter rule set (ADR-006 / ADR-006b, review finding S6).
5
7
  *
6
8
  * Runs against an already-loaded Graph and returns warning-severity
7
- * diagnostics only — the linter never raises errors, since the underlying
8
- * structural invariants it depends on (node/edge existence, template
9
- * resolution) are already enforced by the loader itself. Callers append the
10
- * result to the loader's diagnostics array; `strict` loads are unaffected
11
- * because they only throw on `error` severity.
9
+ * diagnostics in all but one case — the underlying structural invariants the
10
+ * linter depends on (node/edge existence, template resolution) are already
11
+ * enforced by the loader itself. The exception is the hidden-edge live-end
12
+ * rule (error severity, see below), which can only fire on graphs assembled
13
+ * in memory (mutations): the loader drops such edges before they ever reach
14
+ * a loaded Graph, so `strict` loads are unaffected in practice.
12
15
  *
13
16
  * Rules implemented (see docs/adr/REF-006-rules.md for the full catalogue):
14
17
  * - T-003/T-004/T-005: node properties validated (shallow) against the
@@ -23,15 +26,54 @@ import { getTemplateSchema } from '../loader/template-props.js';
23
26
  * (`{component}.Schema.{name}`) — the order-dependent interim state
24
27
  * between an importer creating the inline copy and a later re-import
25
28
  * converging it via reuse-before-inline.
29
+ * - Design §11 (node identity): hidden edge types (bookkeeping such as
30
+ * renamed-from) are exempt from endpoint checks on `to` — a retired ID is
31
+ * legitimate there — but their `from` must be a live node (error).
32
+ * `previousNames` is a system property on any node: a list of valid node
33
+ * IDs, each expected to differ from the node's current ID (warnings).
26
34
  */
27
35
  export function lintGraph(graph) {
28
36
  const diagnostics = [];
29
37
  lintNodeProperties(graph, diagnostics);
38
+ lintPreviousIds(graph, diagnostics);
30
39
  lintEdgeTypeConstraints(graph, diagnostics);
31
40
  lintEdgeProperties(graph, diagnostics);
41
+ lintHiddenEdgeLiveEnds(graph, diagnostics);
32
42
  lintInlineStandaloneSchemaCollisions(graph, diagnostics);
33
43
  return diagnostics;
34
44
  }
45
+ /**
46
+ * System-owned node properties, valid on any node regardless of the owning
47
+ * template's property schema (see design §11: `previousNames` rename trail).
48
+ */
49
+ function getEdgeTypeDefs(graph) {
50
+ return graph.edgeTypes ?? CORE_EDGE_TYPE_MAP;
51
+ }
52
+ /**
53
+ * Per-node lint primitive (design §7: mutations reuse the linter's checks).
54
+ * Property-schema and previousNames rules for a single node — same rules and
55
+ * severities `lintGraph` applies graph-wide.
56
+ */
57
+ export function lintNode(graph, node) {
58
+ const diagnostics = [];
59
+ lintNodePropertiesFor(graph, node, diagnostics);
60
+ lintPreviousIdsFor(graph, node, diagnostics);
61
+ return diagnostics;
62
+ }
63
+ /**
64
+ * Per-edge lint primitive (design §7). Endpoint edge-type constraints, edge
65
+ * property schema, and the hidden-edge live-end rule for a single edge —
66
+ * same rules and severities `lintGraph` applies graph-wide. The edge does
67
+ * not need to be inserted in the graph's indexes yet.
68
+ */
69
+ export function lintEdge(graph, edge) {
70
+ const diagnostics = [];
71
+ const edgeTypes = getEdgeTypeDefs(graph);
72
+ lintEdgeConstraintsFor(graph, edge, edgeTypes, diagnostics);
73
+ lintEdgePropertiesFor(graph, edge, diagnostics);
74
+ lintHiddenEdgeLiveEndFor(graph, edge, edgeTypes, diagnostics);
75
+ return diagnostics;
76
+ }
35
77
  function lintInlineStandaloneSchemaCollisions(graph, diagnostics) {
36
78
  for (const node of graph.nodesById.values()) {
37
79
  const parts = node.id.split('.');
@@ -54,83 +96,174 @@ function lintInlineStandaloneSchemaCollisions(graph, diagnostics) {
54
96
  }
55
97
  function lintNodeProperties(graph, diagnostics) {
56
98
  for (const node of graph.nodesById.values()) {
57
- const template = graph.templates.get(node.template);
58
- if (!template?.properties)
59
- continue;
60
- const schema = getTemplateSchema(template.properties);
61
- const file = approxFilePath(graph, node);
62
- if (!schema.additionalProperties) {
63
- for (const key of Object.keys(node.properties)) {
64
- if (!(key in schema.properties)) {
65
- diagnostics.push({
66
- severity: 'warning',
67
- file,
68
- nodeId: node.id,
69
- message: `unknown property '${key}' is not declared in template '${node.template}'`,
70
- });
71
- }
72
- }
73
- }
74
- for (const [key, propSchema] of Object.entries(schema.properties)) {
75
- const value = node.properties[key];
76
- if (value === undefined)
77
- continue;
78
- const type = propSchema.type;
79
- if (typeof type === 'string' && !valueMatchesType(value, type)) {
99
+ lintNodePropertiesFor(graph, node, diagnostics);
100
+ }
101
+ }
102
+ function lintNodePropertiesFor(graph, node, diagnostics) {
103
+ const template = graph.templates.get(node.template);
104
+ if (!template?.properties)
105
+ return;
106
+ const schema = getTemplateSchema(template.properties);
107
+ const file = approxFilePath(graph, node);
108
+ if (!schema.additionalProperties) {
109
+ for (const key of Object.keys(node.properties)) {
110
+ if (!(key in schema.properties)) {
80
111
  diagnostics.push({
81
112
  severity: 'warning',
82
113
  file,
83
114
  nodeId: node.id,
84
- message: `property '${key}' expected type '${type}' but got '${describeType(value)}'`,
115
+ message: `unknown property '${key}' is not declared in template '${node.template}'`,
85
116
  });
86
117
  }
87
118
  }
88
- for (const key of schema.required) {
89
- if (node.properties[key] === undefined) {
90
- diagnostics.push({
91
- severity: 'warning',
92
- file,
93
- nodeId: node.id,
94
- message: `missing required property '${key}' declared by template '${node.template}'`,
95
- });
96
- }
119
+ }
120
+ for (const [key, propSchema] of Object.entries(schema.properties)) {
121
+ const value = node.properties[key];
122
+ if (value === undefined)
123
+ continue;
124
+ const type = propSchema.type;
125
+ if (typeof type === 'string' && !valueMatchesType(value, type)) {
126
+ diagnostics.push({
127
+ severity: 'warning',
128
+ file,
129
+ nodeId: node.id,
130
+ message: `property '${key}' expected type '${type}' but got '${describeType(value)}'`,
131
+ });
132
+ }
133
+ }
134
+ for (const key of schema.required) {
135
+ if (node.properties[key] === undefined) {
136
+ diagnostics.push({
137
+ severity: 'warning',
138
+ file,
139
+ nodeId: node.id,
140
+ message: `missing required property '${key}' declared by template '${node.template}'`,
141
+ });
142
+ }
143
+ }
144
+ }
145
+ /**
146
+ * Design §11: `previousNames` (rename trail) must be a list of valid node
147
+ * IDs, each expected to differ from the node's current ID. Warnings only.
148
+ */
149
+ function lintPreviousIds(graph, diagnostics) {
150
+ for (const node of graph.nodesById.values()) {
151
+ lintPreviousIdsFor(graph, node, diagnostics);
152
+ }
153
+ }
154
+ function lintPreviousIdsFor(graph, node, diagnostics) {
155
+ const value = node.corum?.identity?.previousIds;
156
+ if (value === undefined)
157
+ return;
158
+ const file = approxFilePath(graph, node);
159
+ if (!Array.isArray(value)) {
160
+ diagnostics.push({
161
+ severity: 'warning',
162
+ file,
163
+ nodeId: node.id,
164
+ message: `corum.identity.previousIds must be a list of node ids but got '${describeType(value)}'`,
165
+ });
166
+ return;
167
+ }
168
+ for (const entry of value) {
169
+ if (typeof entry !== 'string') {
170
+ diagnostics.push({
171
+ severity: 'warning',
172
+ file,
173
+ nodeId: node.id,
174
+ message: `corum.identity.previousIds entries must be node id strings but got '${describeType(entry)}'`,
175
+ });
176
+ continue;
177
+ }
178
+ const idError = validateNodeId(entry);
179
+ if (idError) {
180
+ diagnostics.push({
181
+ severity: 'warning',
182
+ file,
183
+ nodeId: node.id,
184
+ message: `corum.identity.previousIds entry is not a valid node id: ${idError}`,
185
+ });
186
+ }
187
+ else if (entry === node.id) {
188
+ diagnostics.push({
189
+ severity: 'warning',
190
+ file,
191
+ nodeId: node.id,
192
+ message: `corum.identity.previousIds contains the node's current id '${node.id}'`,
193
+ });
194
+ }
195
+ }
196
+ }
197
+ /**
198
+ * Design §11: a hidden edge type's `from` is the live end and must resolve
199
+ * to a live node (e.g. a `renamed-from` edge whose `from` does not exist is
200
+ * an error). The loader already drops such edges at load time, so this rule
201
+ * only fires on graphs assembled in memory (mutation working graphs).
202
+ * The dangling `to` of a hidden edge is intentional and never flagged.
203
+ */
204
+ function lintHiddenEdgeLiveEnds(graph, diagnostics) {
205
+ const edgeTypes = getEdgeTypeDefs(graph);
206
+ for (const [from, edges] of graph.edgesByFrom) {
207
+ if (graph.nodesById.has(from))
208
+ continue;
209
+ for (const edge of edges) {
210
+ lintHiddenEdgeLiveEndFor(graph, edge, edgeTypes, diagnostics);
97
211
  }
98
212
  }
99
213
  }
214
+ function lintHiddenEdgeLiveEndFor(graph, edge, edgeTypes, diagnostics) {
215
+ if (edgeTypes.get(edge.type)?.hidden !== true)
216
+ return;
217
+ if (graph.nodesById.has(edge.from))
218
+ return;
219
+ diagnostics.push({
220
+ severity: 'error',
221
+ file: edge.id,
222
+ message: `hidden edge type '${edge.type}' requires a live 'from' node: ${edge.from} (edge ${edge.id})`,
223
+ });
224
+ }
100
225
  function lintEdgeTypeConstraints(graph, diagnostics) {
226
+ const edgeTypes = getEdgeTypeDefs(graph);
101
227
  for (const edges of graph.edgesByFrom.values()) {
102
228
  for (const edge of edges) {
103
- if (edge.generated)
104
- continue;
105
- const fromNode = graph.nodesById.get(edge.from);
106
- if (fromNode) {
107
- const constraints = getEdgeTypeConstraints(graph.templates, fromNode.template);
108
- if (constraints) {
109
- const allowed = new Set([...(constraints.outgoing ?? []), ...(constraints.supports ?? [])]);
110
- if (!allowed.has(edge.type)) {
111
- diagnostics.push({
112
- severity: 'warning',
113
- file: approxFilePath(graph, fromNode),
114
- nodeId: fromNode.id,
115
- message: `edge type '${edge.type}' is not declared as outgoing or supported by template '${fromNode.template}' (edge ${edge.id})`,
116
- });
117
- }
118
- }
229
+ lintEdgeConstraintsFor(graph, edge, edgeTypes, diagnostics);
230
+ }
231
+ }
232
+ }
233
+ function lintEdgeConstraintsFor(graph, edge, edgeTypes, diagnostics) {
234
+ if (edge.generated)
235
+ return;
236
+ // Hidden edge types are system bookkeeping (e.g. renamed-from trails):
237
+ // templates never declare them, so constraint checks do not apply.
238
+ if (edgeTypes.get(edge.type)?.hidden === true)
239
+ return;
240
+ const fromNode = graph.nodesById.get(edge.from);
241
+ if (fromNode) {
242
+ const constraints = getEdgeTypeConstraints(graph.templates, fromNode.template);
243
+ if (constraints) {
244
+ const allowed = new Set([...(constraints.outgoing ?? []), ...(constraints.supports ?? [])]);
245
+ if (!allowed.has(edge.type)) {
246
+ diagnostics.push({
247
+ severity: 'warning',
248
+ file: approxFilePath(graph, fromNode),
249
+ nodeId: fromNode.id,
250
+ message: `edge type '${edge.type}' is not declared as outgoing or supported by template '${fromNode.template}' (edge ${edge.id})`,
251
+ });
119
252
  }
120
- const toNode = graph.nodesById.get(edge.to);
121
- if (toNode) {
122
- const constraints = getEdgeTypeConstraints(graph.templates, toNode.template);
123
- if (constraints) {
124
- const allowed = new Set([...(constraints.incoming ?? []), ...(constraints.supports ?? [])]);
125
- if (!allowed.has(edge.type)) {
126
- diagnostics.push({
127
- severity: 'warning',
128
- file: approxFilePath(graph, toNode),
129
- nodeId: toNode.id,
130
- message: `edge type '${edge.type}' is not declared as incoming or supported by template '${toNode.template}' (edge ${edge.id})`,
131
- });
132
- }
133
- }
253
+ }
254
+ }
255
+ const toNode = graph.nodesById.get(edge.to);
256
+ if (toNode) {
257
+ const constraints = getEdgeTypeConstraints(graph.templates, toNode.template);
258
+ if (constraints) {
259
+ const allowed = new Set([...(constraints.incoming ?? []), ...(constraints.supports ?? [])]);
260
+ if (!allowed.has(edge.type)) {
261
+ diagnostics.push({
262
+ severity: 'warning',
263
+ file: approxFilePath(graph, toNode),
264
+ nodeId: toNode.id,
265
+ message: `edge type '${edge.type}' is not declared as incoming or supported by template '${toNode.template}' (edge ${edge.id})`,
266
+ });
134
267
  }
135
268
  }
136
269
  }
@@ -140,47 +273,50 @@ function lintEdgeProperties(graph, diagnostics) {
140
273
  return;
141
274
  for (const edges of graph.edgesByFrom.values()) {
142
275
  for (const edge of edges) {
143
- const def = graph.edgeTypes.get(edge.type);
144
- if (!def?.properties)
145
- continue;
146
- const schema = getTemplateSchema(def.properties);
147
- const props = edge.properties ?? {};
148
- const file = edgePropertyFile(graph, edge);
149
- if (!schema.additionalProperties) {
150
- for (const key of Object.keys(props)) {
151
- if (!(key in schema.properties)) {
152
- diagnostics.push({
153
- severity: 'warning',
154
- file,
155
- message: `edge '${edge.id}' has unknown property '${key}' not declared by edge type '${edge.type}'`,
156
- });
157
- }
158
- }
159
- }
160
- for (const [key, propSchema] of Object.entries(schema.properties)) {
161
- const value = props[key];
162
- if (value === undefined)
163
- continue;
164
- const type = propSchema.type;
165
- if (typeof type === 'string' && !valueMatchesType(value, type)) {
166
- diagnostics.push({
167
- severity: 'warning',
168
- file,
169
- message: `edge '${edge.id}' property '${key}' expected type '${type}' but got '${describeType(value)}'`,
170
- });
171
- }
172
- }
173
- for (const key of schema.required) {
174
- if (props[key] === undefined) {
175
- diagnostics.push({
176
- severity: 'warning',
177
- file,
178
- message: `edge '${edge.id}' missing required property '${key}' declared by edge type '${edge.type}'`,
179
- });
180
- }
276
+ lintEdgePropertiesFor(graph, edge, diagnostics);
277
+ }
278
+ }
279
+ }
280
+ function lintEdgePropertiesFor(graph, edge, diagnostics) {
281
+ const def = graph.edgeTypes?.get(edge.type);
282
+ if (!def?.properties)
283
+ return;
284
+ const schema = getTemplateSchema(def.properties);
285
+ const props = edge.properties ?? {};
286
+ const file = edgePropertyFile(graph, edge);
287
+ if (!schema.additionalProperties) {
288
+ for (const key of Object.keys(props)) {
289
+ if (!(key in schema.properties)) {
290
+ diagnostics.push({
291
+ severity: 'warning',
292
+ file,
293
+ message: `edge '${edge.id}' has unknown property '${key}' not declared by edge type '${edge.type}'`,
294
+ });
181
295
  }
182
296
  }
183
297
  }
298
+ for (const [key, propSchema] of Object.entries(schema.properties)) {
299
+ const value = props[key];
300
+ if (value === undefined)
301
+ continue;
302
+ const type = propSchema.type;
303
+ if (typeof type === 'string' && !valueMatchesType(value, type)) {
304
+ diagnostics.push({
305
+ severity: 'warning',
306
+ file,
307
+ message: `edge '${edge.id}' property '${key}' expected type '${type}' but got '${describeType(value)}'`,
308
+ });
309
+ }
310
+ }
311
+ for (const key of schema.required) {
312
+ if (props[key] === undefined) {
313
+ diagnostics.push({
314
+ severity: 'warning',
315
+ file,
316
+ message: `edge '${edge.id}' missing required property '${key}' declared by edge type '${edge.type}'`,
317
+ });
318
+ }
319
+ }
184
320
  }
185
321
  function edgePropertyFile(graph, edge) {
186
322
  const fromNode = graph.nodesById.get(edge.from);
@@ -48,7 +48,8 @@ export function loadClusters(content, templates, diagnostics) {
48
48
  ...(typeof meta.extractedFrom === 'string' && { extractedFrom: meta.extractedFrom }),
49
49
  ...(typeof meta.derivation === 'string' && { derivation: meta.derivation }),
50
50
  ...(typeof meta.derivedBy === 'string' && { derivedBy: meta.derivedBy }),
51
- properties: isRecord(record.properties) ? record.properties : {},
51
+ ...(extractCorum(record.corum, record.properties) !== undefined && { corum: extractCorum(record.corum, record.properties) }),
52
+ properties: isRecord(record.properties) ? stripLegacyBookkeeping(record.properties) : {},
52
53
  };
53
54
  addNode(result, root, key, diagnostics);
54
55
  const rootTemplate = templates.get(root.template);
@@ -95,7 +96,13 @@ function getNodeRefTargets(node, template) {
95
96
  }
96
97
  return targets;
97
98
  }
98
- function materialiseChildren(result, parent, clusterRoot, source, templates, filePath, diagnostics) {
99
+ /**
100
+ * Materialise owned children of `parent` from a cluster-style `source`
101
+ * record into `result` (nodes + structural edges), recursively. Exported for
102
+ * the mutation engine's `createNode` (design §7/§8), which reuses the exact
103
+ * loader semantics for owned-child creation instead of reimplementing them.
104
+ */
105
+ export function materialiseChildren(result, parent, clusterRoot, source, templates, filePath, diagnostics) {
99
106
  const template = templates.get(parent.template);
100
107
  if (!template) {
101
108
  diagnostics.push({ severity: 'error', file: filePath, nodeId: parent.id, message: `unknown template: ${parent.template}` });
@@ -135,6 +142,7 @@ function materialiseChildren(result, parent, clusterRoot, source, templates, fil
135
142
  stability: asStability(value.stability, parent.stability, diagnostics, filePath, childId),
136
143
  schemaVersion: parent.schemaVersion,
137
144
  lastModifiedAt: parent.lastModifiedAt,
145
+ ...(extractCorum(value.corum, value) !== undefined && { corum: extractCorum(value.corum, value) }),
138
146
  properties: stripOwnedSections(value, childTemplateName, templates),
139
147
  };
140
148
  addNode(result, child, filePath, diagnostics);
@@ -174,9 +182,34 @@ function materialiseChildren(result, parent, clusterRoot, source, templates, fil
174
182
  }
175
183
  function stripOwnedSections(value, templateName, templates) {
176
184
  const ownedSections = new Set(Object.keys(getOwnedSections(templates.get(templateName) ?? ({ name: templateName, info: { version: 'unknown' } }))));
177
- const nodeMetadata = new Set(['state', 'stability']);
185
+ const nodeMetadata = new Set(['state', 'stability', 'corum', 'previousNames']);
178
186
  return Object.fromEntries(Object.entries(value).filter(([key]) => !ownedSections.has(key) && !nodeMetadata.has(key)));
179
187
  }
188
+ function stripLegacyBookkeeping(properties) {
189
+ const { previousNames: _previousNames, ...rest } = properties;
190
+ return rest;
191
+ }
192
+ function extractCorum(corumValue, propertySource) {
193
+ const previousIds = extractPreviousIds(corumValue);
194
+ if (previousIds !== undefined)
195
+ return { identity: { previousIds } };
196
+ if (isRecord(propertySource) && Array.isArray(propertySource.previousNames)) {
197
+ return {
198
+ identity: {
199
+ previousIds: propertySource.previousNames.filter((value) => typeof value === 'string'),
200
+ },
201
+ };
202
+ }
203
+ return undefined;
204
+ }
205
+ function extractPreviousIds(corumValue) {
206
+ if (!isRecord(corumValue))
207
+ return undefined;
208
+ const identity = corumValue.identity;
209
+ if (!isRecord(identity) || !Array.isArray(identity.previousIds))
210
+ return undefined;
211
+ return identity.previousIds.filter((value) => typeof value === 'string');
212
+ }
180
213
  function addNode(result, node, file, diagnostics) {
181
214
  if (result.nodes.has(node.id)) {
182
215
  diagnostics.push({ severity: 'error', file, nodeId: node.id, message: `duplicate node id: ${node.id}` });
@@ -25,12 +25,18 @@ export function loadEdges(content, nodes, diagnostics, edgeTypes = CORE_EDGE_TYP
25
25
  diagnostics.push({ severity: 'error', file: key, message: `invalid edge type: ${edgeRecord.type}` });
26
26
  continue;
27
27
  }
28
+ // Hidden edge types (bookkeeping such as renamed-from) legitimately
29
+ // point their `to` at a retired ID, so no resolution is required there —
30
+ // but the `from` is the live end and MUST resolve (design §3/§11).
31
+ const hidden = edgeTypes.get(edgeRecord.type)?.hidden === true;
28
32
  let unresolvedEndpoint = false;
29
33
  if (!nodes.has(edgeRecord.from)) {
30
- diagnostics.push({ severity: 'warning', file: key, message: `edge from unresolved node: ${edgeRecord.from}` });
34
+ diagnostics.push(hidden
35
+ ? { severity: 'error', file: key, message: `hidden edge type '${edgeRecord.type}' requires a live 'from' node: ${edgeRecord.from}` }
36
+ : { severity: 'warning', file: key, message: `edge from unresolved node: ${edgeRecord.from}` });
31
37
  unresolvedEndpoint = true;
32
38
  }
33
- if (!nodes.has(edgeRecord.to)) {
39
+ if (!hidden && !nodes.has(edgeRecord.to)) {
34
40
  diagnostics.push({ severity: 'warning', file: key, message: `edge to unresolved node: ${edgeRecord.to}` });
35
41
  unresolvedEndpoint = true;
36
42
  }