@atolis-hq/corum 0.1.39 → 0.1.40

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.
@@ -5,6 +5,8 @@ import { parse as parseYaml } from 'yaml';
5
5
  import { SourceError } from './index.js';
6
6
  import { GitCacheManager } from './git-cache.js';
7
7
  const DEFAULT_GRAPH_DIR = '.corum/graph';
8
+ // Module-level so two GitGraphSource instances in one process still serialise.
9
+ const commitLocks = new Map();
8
10
  export class GitGraphSource {
9
11
  graphDir;
10
12
  localPath;
@@ -171,57 +173,115 @@ export class GitGraphSource {
171
173
  return map;
172
174
  }
173
175
  async commit(branch, changes, message, options = {}) {
176
+ const dir = await this.dir();
177
+ if (this.localPath) {
178
+ let checkedOut;
179
+ try {
180
+ checkedOut = (await git.currentBranch({ fs, dir })) ?? undefined;
181
+ }
182
+ catch {
183
+ checkedOut = undefined;
184
+ }
185
+ if (checkedOut === branch) {
186
+ throw new SourceError(`cannot commit to branch '${branch}' - it is checked out in ${dir}; ` +
187
+ `moving the ref would silently diverge the working tree. Switch to another branch first.`);
188
+ }
189
+ }
174
190
  const defaultBranch = await this.defaultBranch();
175
191
  if (branch === defaultBranch) {
176
192
  throw new SourceError(`cannot commit to default branch '${branch}' - it is read-only`);
177
193
  }
178
- const dir = await this.dir();
194
+ // Serialise in-process writers per repo+branch so concurrent commits stack
195
+ // instead of racing; the CAS check in commitLocked covers external writers.
196
+ const lockKey = `${dir}|${branch}`;
197
+ const previous = commitLocks.get(lockKey) ?? Promise.resolve();
198
+ const run = previous
199
+ .catch(() => { })
200
+ .then(() => this.commitLocked(dir, branch, defaultBranch, changes, message, options));
201
+ commitLocks.set(lockKey, run.then(() => { }, () => { }));
202
+ return run;
203
+ }
204
+ async commitLocked(dir, branch, defaultBranch, changes, message, options) {
179
205
  const prefix = this.graphDir.endsWith('/') ? this.graphDir : `${this.graphDir}/`;
180
- let parentSha;
181
- try {
182
- parentSha = await this.resolveBranchOid(branch);
183
- }
184
- catch (err) {
185
- throw new SourceError(`cannot resolve branch '${branch}'`, err);
186
- }
187
- const { commit: parentCommit } = await git.readCommit({ fs, dir, oid: parentSha });
188
- const blobMap = new Map();
189
- for (const [key, content] of changes) {
190
- const repoPath = `${prefix}${normalizeContentKey(key)}`;
191
- const oid = await git.writeBlob({ fs, dir, blob: Buffer.from(content, 'utf-8') });
192
- blobMap.set(repoPath, oid);
193
- }
194
- const newTreeOid = options.replaceGraphContent
195
- ? await buildReplacedGraphTree(fs, dir, parentCommit.tree, prefix, blobMap)
196
- : await buildUpdatedTree(fs, dir, parentCommit.tree, blobMap);
197
- const now = Math.floor(Date.now() / 1000);
198
- const newCommitOid = await git.writeCommit({
199
- fs,
200
- dir,
201
- commit: {
202
- tree: newTreeOid,
203
- parent: [parentSha],
204
- message,
205
- author: { name: 'corum', email: 'corum@localhost', timestamp: now, timezoneOffset: 0 },
206
- committer: { name: 'corum', email: 'corum@localhost', timestamp: now, timezoneOffset: 0 },
207
- },
208
- });
209
- await git.writeRef({ fs, dir, ref: `refs/heads/${branch}`, value: newCommitOid, force: true });
210
- if (this.remoteUrl) {
206
+ const MAX_ATTEMPTS = 3;
207
+ for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
208
+ let parentSha;
209
+ let branchExisted = true;
211
210
  try {
212
- await git.push({
213
- fs,
214
- http: (await import('isomorphic-git/http/node')).default,
215
- dir,
216
- remote: 'origin',
217
- ref: branch,
218
- onAuth: this.onAuth(),
219
- });
211
+ parentSha = await this.resolveBranchOid(branch);
220
212
  }
221
213
  catch (err) {
222
- throw new SourceError(`failed to push branch '${branch}'`, err);
214
+ if (!options.createBranchIfMissing) {
215
+ throw new SourceError(`cannot resolve branch '${branch}'`, err);
216
+ }
217
+ branchExisted = false;
218
+ try {
219
+ parentSha = await this.resolveBranchOid(defaultBranch);
220
+ }
221
+ catch (err2) {
222
+ throw new SourceError(`cannot resolve default branch '${defaultBranch}' to create '${branch}'`, err2);
223
+ }
224
+ }
225
+ const { commit: parentCommit } = await git.readCommit({ fs, dir, oid: parentSha });
226
+ const blobMap = new Map();
227
+ for (const [key, content] of changes) {
228
+ const repoPath = `${prefix}${normalizeContentKey(key)}`;
229
+ const oid = await git.writeBlob({ fs, dir, blob: Buffer.from(content, 'utf-8') });
230
+ blobMap.set(repoPath, oid);
231
+ }
232
+ const newTreeOid = options.replaceGraphContent
233
+ ? await buildReplacedGraphTree(fs, dir, parentCommit.tree, prefix, blobMap)
234
+ : await buildUpdatedTree(fs, dir, parentCommit.tree, blobMap);
235
+ const now = Math.floor(Date.now() / 1000);
236
+ const newCommitOid = await git.writeCommit({
237
+ fs,
238
+ dir,
239
+ commit: {
240
+ tree: newTreeOid,
241
+ parent: [parentSha],
242
+ message,
243
+ author: { name: 'corum', email: 'corum@localhost', timestamp: now, timezoneOffset: 0 },
244
+ committer: { name: 'corum', email: 'corum@localhost', timestamp: now, timezoneOffset: 0 },
245
+ },
246
+ });
247
+ // Compare-and-swap: if the ref moved while we built the commit, rebuild
248
+ // on the new parent instead of silently discarding the other write.
249
+ let currentSha;
250
+ try {
251
+ currentSha = await this.resolveBranchOid(branch);
252
+ }
253
+ catch {
254
+ currentSha = undefined;
255
+ }
256
+ if (branchExisted ? currentSha !== parentSha : currentSha !== undefined)
257
+ continue;
258
+ await git.writeRef({ fs, dir, ref: `refs/heads/${branch}`, value: newCommitOid, force: true });
259
+ if (this.remoteUrl) {
260
+ try {
261
+ await git.push({
262
+ fs,
263
+ http: (await import('isomorphic-git/http/node')).default,
264
+ dir,
265
+ remote: 'origin',
266
+ ref: branch,
267
+ onAuth: this.onAuth(),
268
+ });
269
+ }
270
+ catch (err) {
271
+ // Roll the local ref back so the cached clone does not diverge from
272
+ // origin; otherwise the committed data becomes invisible on next read.
273
+ if (branchExisted) {
274
+ await git.writeRef({ fs, dir, ref: `refs/heads/${branch}`, value: parentSha, force: true });
275
+ }
276
+ else {
277
+ await git.deleteRef({ fs, dir, ref: `refs/heads/${branch}` }).catch(() => { });
278
+ }
279
+ throw new SourceError(`failed to push branch '${branch}'`, err);
280
+ }
223
281
  }
282
+ return;
224
283
  }
284
+ throw new SourceError(`concurrent updates to branch '${branch}' - retries exhausted`);
225
285
  }
226
286
  async reloadSignature() {
227
287
  const dir = await this.dir();
@@ -0,0 +1,26 @@
1
+ import path from 'node:path';
2
+ import { SourceError } from './index.js';
3
+ /**
4
+ * Resolve a relative content key against a base directory, rejecting any key
5
+ * that is absolute, contains backslashes or NUL bytes, or escapes the base
6
+ * directory via `..` segments.
7
+ */
8
+ export function resolveContentPath(baseDir, key) {
9
+ if (key.includes('\\') ||
10
+ key.includes('\0') ||
11
+ path.posix.isAbsolute(key) ||
12
+ path.win32.isAbsolute(key)) {
13
+ throw new SourceError(`invalid ContentMap key: ${key}`);
14
+ }
15
+ const normalised = path.posix.normalize(key);
16
+ if (normalised === '..' || normalised.startsWith('../') || normalised === '.') {
17
+ throw new SourceError(`invalid ContentMap key: ${key}`);
18
+ }
19
+ const resolvedBase = path.resolve(baseDir);
20
+ const resolvedPath = path.resolve(resolvedBase, ...normalised.split('/'));
21
+ const relative = path.relative(resolvedBase, resolvedPath);
22
+ if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
23
+ throw new SourceError(`ContentMap key escapes graphDir: ${key}`);
24
+ }
25
+ return resolvedPath;
26
+ }
@@ -5,16 +5,17 @@ import { existsSync, readFileSync, readdirSync, watch } from 'node:fs';
5
5
  import { readdir } from 'node:fs/promises';
6
6
  import { fileURLToPath, pathToFileURL } from 'node:url';
7
7
  import { parse as parseYaml } from 'yaml';
8
- import { computeClusterOverlay, getClusterView, getGraphSummary, expandExternalNodes, getLineage, listNodes, searchNodes, } from '../graph/index.js';
8
+ import { computeClusterOverlay, getClusterView, getGraphSummary, expandExternalNodes, getLineage, getStructuralNodeTemplates, isVisibleEdgeType, listNodes, searchNodes, } from '../graph/index.js';
9
9
  import { loadGraph, loadMultiGraph } from '../loader/index.js';
10
- import { VALID_EDGE_TYPE_SET } from '../loader/constants.js';
10
+ import { CORE_EDGE_TYPES } from '../loader/constants.js';
11
11
  import { getOwnedSections } from '../loader/pack-loader.js';
12
+ import { getPropertySchemasFromTemplate } from '../loader/template-props.js';
12
13
  import { QueryError } from '../schema/index.js';
13
14
  import { createGraphRuntimeConfig } from '../source/config.js';
14
15
  const __filename = fileURLToPath(import.meta.url);
15
16
  const __dirname = path.dirname(__filename);
16
17
  const WEB_DIR = path.join(__dirname, '..', '..', '..', 'web');
17
- function createMultiGraphCache(source) {
18
+ export function createMultiGraphCache(source) {
18
19
  let cache = null;
19
20
  return {
20
21
  async get() {
@@ -70,10 +71,10 @@ function summarizeNodeForNavigation(graph, node) {
70
71
  ...(ownership ?? {}),
71
72
  };
72
73
  }
73
- function resolveLocalRef(graph, nodeId, section, name) {
74
+ function resolveLocalRef(graph, node, section, name) {
74
75
  // Walk up the node ID hierarchy to find the nearest ancestor owning section.name.
75
- // This handles refs on both root nodes and nested Field nodes correctly.
76
- let ancestor = nodeId.replace(/\.fields\.[^.]+$/, '');
76
+ // This handles refs on both root nodes and nested child nodes correctly.
77
+ let ancestor = node.parentId ?? node.id;
77
78
  while (ancestor.length > 0) {
78
79
  const candidate = `${ancestor}.${section}.${name}`;
79
80
  if (graph.nodesById.has(candidate))
@@ -86,42 +87,22 @@ function resolveLocalRef(graph, nodeId, section, name) {
86
87
  return undefined;
87
88
  }
88
89
  function resolveNodeRef(graph, node, rawValue) {
89
- if (rawValue.startsWith('#/schemas/')) {
90
- const name = rawValue.slice(10);
91
- const id = resolveLocalRef(graph, node.id, 'schemas', name);
92
- return id ? { display: name, nodeId: id } : { display: name };
93
- }
94
- if (rawValue.startsWith('#/enums/')) {
95
- const name = rawValue.slice(8);
96
- const id = resolveLocalRef(graph, node.id, 'enums', name);
97
- return id ? { display: name, nodeId: id } : { display: name };
98
- }
99
- if (rawValue.startsWith('#/mappings/')) {
100
- const name = rawValue.slice(11);
101
- const id = resolveLocalRef(graph, node.id, 'mappings', name);
90
+ // Local refs use #/{section}/{name} for any owned section — section names
91
+ // are pack-defined, so no fixed prefix list here.
92
+ const local = /^#\/([^/]+)\/(.+)$/.exec(rawValue);
93
+ if (local) {
94
+ const [, section, name] = local;
95
+ const id = resolveLocalRef(graph, node, section, name);
102
96
  return id ? { display: name, nodeId: id } : { display: name };
103
97
  }
104
98
  if (graph.nodesById.has(rawValue))
105
99
  return { display: rawValue, nodeId: rawValue };
106
100
  return { display: rawValue };
107
101
  }
108
- function getPropertySchemas(templateProperties) {
109
- if (Array.isArray(templateProperties.allOf)) {
110
- const merged = {};
111
- for (const schema of templateProperties.allOf) {
112
- Object.assign(merged, getPropertySchemas(schema));
113
- }
114
- return merged;
115
- }
116
- if (typeof templateProperties.properties === 'object' && templateProperties.properties !== null) {
117
- return templateProperties.properties;
118
- }
119
- return {};
120
- }
121
102
  function annotateNodeRefProperties(graph, node, template) {
122
103
  if (!template.properties)
123
104
  return node.properties;
124
- const propSchemas = getPropertySchemas(template.properties);
105
+ const propSchemas = getPropertySchemasFromTemplate(template.properties);
125
106
  const result = { ...node.properties };
126
107
  for (const [key, schema] of Object.entries(propSchemas)) {
127
108
  const value = result[key];
@@ -146,13 +127,14 @@ function annotateNode(graph, node) {
146
127
  const template = graph.templates.get(node.template);
147
128
  return template ? { ...node, properties: annotateNodeRefProperties(graph, node, template) } : node;
148
129
  }
149
- function parseIncludeEdges(value) {
130
+ function parseIncludeEdges(value, graph) {
150
131
  if (typeof value !== 'string' || value.trim() === '')
151
132
  return [];
133
+ const known = graph.edgeTypes ?? new Map(Object.entries(CORE_EDGE_TYPES));
152
134
  const types = value
153
135
  .split(',')
154
136
  .map(item => item.trim())
155
- .filter((item) => VALID_EDGE_TYPE_SET.has(item));
137
+ .filter((item) => known.has(item));
156
138
  return [...new Set(types)];
157
139
  }
158
140
  function createReloadEvents() {
@@ -178,12 +160,14 @@ function createReloadEvents() {
178
160
  },
179
161
  };
180
162
  }
181
- function replaceGraph(target, source) {
163
+ export function replaceGraph(target, source) {
182
164
  target.nodesById = source.nodesById;
183
165
  target.edgesByFrom = source.edgesByFrom;
184
166
  target.edgesByTo = source.edgesByTo;
185
167
  target.templates = source.templates;
186
168
  target.diagnostics = source.diagnostics;
169
+ target.edgeTypes = source.edgeTypes;
170
+ target.sourceContent = source.sourceContent;
187
171
  }
188
172
  function isFileWatcherEnabled(options) {
189
173
  if (options.fileWatcher !== undefined)
@@ -352,12 +336,6 @@ export function createApp(graph, reloadEvents = createReloadEvents(), source, mu
352
336
  });
353
337
  res.json(nodes);
354
338
  });
355
- const GRAPH_EXCLUDED_TEMPLATES = new Set([
356
- 'Schema', 'EnumDefinition', 'Field', 'EnumValue', 'Mapping',
357
- ]);
358
- const GRAPH_SEMANTIC_EDGE_TYPES = new Set([
359
- 'triggers', 'produces', 'reads', 'calls', 'implements', 'maps-to', 'derived-from',
360
- ]);
361
339
  app.get('/api/graph', async (req, res) => {
362
340
  try {
363
341
  let targetGraph = graph;
@@ -376,7 +354,7 @@ export function createApp(graph, reloadEvents = createReloadEvents(), source, mu
376
354
  ? null
377
355
  : filterExcludeTemplates?.length
378
356
  ? new Set(filterExcludeTemplates)
379
- : GRAPH_EXCLUDED_TEMPLATES;
357
+ : getStructuralNodeTemplates(targetGraph);
380
358
  const nodes = [];
381
359
  for (const node of targetGraph.nodesById.values()) {
382
360
  if (filterTemplates?.length && !filterTemplates.includes(node.template))
@@ -402,7 +380,7 @@ export function createApp(graph, reloadEvents = createReloadEvents(), source, mu
402
380
  const edges = [];
403
381
  for (const edgeList of targetGraph.edgesByFrom.values()) {
404
382
  for (const edge of edgeList) {
405
- if (!GRAPH_SEMANTIC_EDGE_TYPES.has(edge.type))
383
+ if (!isVisibleEdgeType(targetGraph, edge.type))
406
384
  continue;
407
385
  if (!nodeIds.has(edge.from) || !nodeIds.has(edge.to))
408
386
  continue;
@@ -471,8 +449,9 @@ export function createApp(graph, reloadEvents = createReloadEvents(), source, mu
471
449
  const direction = ['downstream', 'upstream', 'both'].includes(req.query.direction)
472
450
  ? req.query.direction
473
451
  : 'downstream';
452
+ const knownEdgeTypes = targetGraph.edgeTypes ?? new Map(Object.entries(CORE_EDGE_TYPES));
474
453
  const edgeTypes = Array.isArray(req.query.edge_types)
475
- ? req.query.edge_types.filter((type) => typeof type === 'string' && VALID_EDGE_TYPE_SET.has(type))
454
+ ? req.query.edge_types.filter((type) => typeof type === 'string' && knownEdgeTypes.has(type))
476
455
  : undefined;
477
456
  const excludeNodeTypes = Array.isArray(req.query.exclude_node_types)
478
457
  ? req.query.exclude_node_types.filter((type) => typeof type === 'string')
@@ -502,7 +481,7 @@ export function createApp(graph, reloadEvents = createReloadEvents(), source, mu
502
481
  if (typeof req.query.ref === 'string' && multiCache) {
503
482
  targetGraph = await getGraphForRef(req.query.ref, multiCache, graph);
504
483
  }
505
- const cluster = getClusterView(targetGraph, nodeId, parseIncludeEdges(req.query.includeEdges));
484
+ const cluster = getClusterView(targetGraph, nodeId, parseIncludeEdges(req.query.includeEdges, targetGraph));
506
485
  const rawOverlayRefs = req.query.overlayRefs;
507
486
  const overlayRefs = Array.isArray(rawOverlayRefs)
508
487
  ? rawOverlayRefs.filter((r) => typeof r === 'string' && r.length > 0)
@@ -639,6 +618,7 @@ export function startWebServer(graph, options = {}) {
639
618
  : await loadGraph({ graphPath, strict: true });
640
619
  replaceGraph(graph, nextGraph);
641
620
  multiCache?.invalidate();
621
+ options.onReload?.();
642
622
  reloadEvents.notify();
643
623
  logger(`[corum] graph reloaded after ${reason}`);
644
624
  })();
@@ -657,6 +637,7 @@ export function startWebServer(graph, options = {}) {
657
637
  logger,
658
638
  onReload: () => {
659
639
  multiCache?.invalidate();
640
+ options.onReload?.();
660
641
  reloadEvents.notify();
661
642
  },
662
643
  })
@@ -2,9 +2,10 @@ import fs from 'node:fs';
2
2
  import path from 'node:path';
3
3
  import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
4
4
  import { getOwnedSections } from '../loader/pack-loader.js';
5
+ import { getPropertySchemasFromTemplate } from '../loader/template-props.js';
6
+ import { isStructuralEdgeType } from '../graph/index.js';
5
7
  import { isPackRef } from '../loader/fs-utils.js';
6
8
  import { FileGraphSource } from '../source/file-source.js';
7
- const STRUCTURAL_EDGE_TYPES = new Set(['has-field', 'has-value']);
8
9
  const YAML_STRINGIFY_OPTIONS = { singleQuote: true };
9
10
  export function serializeGraph(graph, options = {}) {
10
11
  const map = new Map();
@@ -13,10 +14,10 @@ export function serializeGraph(graph, options = {}) {
13
14
  map.set(clusterPath(root), stringifyGraphYaml(toClusterDocument(graph, root)));
14
15
  }
15
16
  const explicitEdges = getAllEdges(graph)
16
- .filter(edge => !STRUCTURAL_EDGE_TYPES.has(edge.type) && edge.generated !== true)
17
+ .filter(edge => !isStructuralEdgeType(graph, edge.type) && edge.generated !== true)
17
18
  .sort((a, b) => a.id.localeCompare(b.id));
18
19
  if (explicitEdges.length > 0) {
19
- map.set('edges/corum.edges.yaml', stringifyGraphYaml({ edges: explicitEdges.map(toEdgeDocument) }));
20
+ map.set('edges/corum.edges.yaml', stringifyGraphYaml({ edges: explicitEdges.map(edge => toEdgeDocument(graph, edge)) }));
20
21
  }
21
22
  return map;
22
23
  }
@@ -79,7 +80,7 @@ function toClusterDocument(graph, root) {
79
80
  metadata,
80
81
  };
81
82
  if (Object.keys(root.properties).length > 0) {
82
- doc.properties = root.properties;
83
+ doc.properties = orderNodeProperties(graph, root);
83
84
  }
84
85
  appendOwnedSections(graph, root, doc);
85
86
  return doc;
@@ -94,7 +95,7 @@ function appendOwnedSections(graph, parent, target) {
94
95
  continue;
95
96
  const section = {};
96
97
  for (const child of children) {
97
- const childDoc = { ...child.properties };
98
+ const childDoc = { ...orderNodeProperties(graph, child) };
98
99
  if (child.state !== parent.state)
99
100
  childDoc.state = child.state;
100
101
  if (child.stability !== parent.stability)
@@ -122,7 +123,41 @@ function getLocalName(childId, parentId, sectionName) {
122
123
  function stringifyGraphYaml(value) {
123
124
  return stringifyYaml(value, YAML_STRINGIFY_OPTIONS);
124
125
  }
125
- function toEdgeDocument(edge) {
126
+ /**
127
+ * Canonical property key order at serialisation time: template-declared
128
+ * property order first, then any remaining (undeclared) keys alphabetically.
129
+ * This keeps git diffs stable across import/merge paths that spread-merge
130
+ * properties in arbitrary insertion order (see reconcile/index.ts).
131
+ */
132
+ function orderNodeProperties(graph, node) {
133
+ const template = graph.templates.get(node.template);
134
+ const declaredOrder = template?.properties
135
+ ? Object.keys(getPropertySchemasFromTemplate(template.properties))
136
+ : [];
137
+ return orderKeys(node.properties, declaredOrder);
138
+ }
139
+ function orderEdgeProperties(graph, edge) {
140
+ const edgeTypeDef = graph.edgeTypes?.get(edge.type);
141
+ const declaredOrder = edgeTypeDef?.properties
142
+ ? Object.keys(getPropertySchemasFromTemplate(edgeTypeDef.properties))
143
+ : [];
144
+ return orderKeys(edge.properties ?? {}, declaredOrder);
145
+ }
146
+ function orderKeys(obj, preferredOrder) {
147
+ const ordered = {};
148
+ const remaining = new Set(Object.keys(obj));
149
+ for (const key of preferredOrder) {
150
+ if (remaining.has(key)) {
151
+ ordered[key] = obj[key];
152
+ remaining.delete(key);
153
+ }
154
+ }
155
+ for (const key of [...remaining].sort()) {
156
+ ordered[key] = obj[key];
157
+ }
158
+ return ordered;
159
+ }
160
+ function toEdgeDocument(graph, edge) {
126
161
  const doc = {
127
162
  from: edge.from,
128
163
  to: edge.to,
@@ -134,6 +169,9 @@ function toEdgeDocument(edge) {
134
169
  doc.stability = edge.stability;
135
170
  if (edge.notes !== undefined)
136
171
  doc.notes = edge.notes;
172
+ if (edge.properties !== undefined && Object.keys(edge.properties).length > 0) {
173
+ doc.properties = orderEdgeProperties(graph, edge);
174
+ }
137
175
  return doc;
138
176
  }
139
177
  function getAllEdges(graph) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atolis-hq/corum",
3
- "version": "0.1.39",
3
+ "version": "0.1.40",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",