@atolis-hq/corum 0.1.38 → 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.
@@ -1,10 +1,11 @@
1
- import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
1
+ import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
2
2
  import fs from 'node:fs';
3
3
  import path from 'node:path';
4
4
  import * as git from 'isomorphic-git';
5
5
  import { parse as parseYaml } from 'yaml';
6
6
  import { isPackRef } from '../loader/fs-utils.js';
7
7
  import { SourceError } from './index.js';
8
+ import { resolveContentPath } from './safe-path.js';
8
9
  const DEFAULT_GRAPH_DIR = '.corum/graph';
9
10
  const DEFAULT_PACKS_PATH = '.corum/packs';
10
11
  export class FileGraphSource {
@@ -73,23 +74,116 @@ export class FileGraphSource {
73
74
  return [];
74
75
  }
75
76
  }
76
- async commit(branch, changes, _message, options = {}) {
77
+ async commit(branch, changes, message, options = {}) {
77
78
  const defaultBranch = await this.defaultBranch();
78
79
  if (branch !== defaultBranch) {
79
80
  throw new SourceError(`FileGraphSource only supports its local branch '${defaultBranch}', got '${branch}'`);
80
81
  }
81
- if (options.replaceGraphContent && existsSync(this.graphDir)) {
82
- rmSync(this.graphDir, { recursive: true, force: true });
82
+ if (options.replaceGraphContent) {
83
+ this.replaceGraphContent(changes);
83
84
  }
84
- for (const [key, content] of changes) {
85
- const filePath = resolveContentPath(this.graphDir, key);
86
- mkdirSync(path.dirname(filePath), { recursive: true });
87
- writeFileSync(filePath, content);
85
+ else {
86
+ writeContentMap(this.graphDir, changes);
87
+ }
88
+ await commitToGitIfRepo(this.graphDir, message);
89
+ }
90
+ /**
91
+ * Replace the full graph directory contents with `changes`, closing the
92
+ * crash window that a naive `rmSync` + rewrite leaves open (a crash between
93
+ * delete and rewrite used to lose the graph entirely) and never deleting
94
+ * non-YAML files a user kept alongside the graph.
95
+ *
96
+ * Approach: stage the new content in a sibling temp directory (copying over
97
+ * the old directory first so untouched non-YAML files survive, then
98
+ * overlaying the new files and dropping stale YAML that's no longer in the
99
+ * ContentMap), then atomically swap it in via two renames. The original
100
+ * directory is never observably empty or partially written.
101
+ *
102
+ * Exception: if `graphDir` is itself a git repository root (contains a
103
+ * `.git` entry), renaming it away would move `.git` too, so we fall back to
104
+ * an in-place selective delete — write new content first, then remove only
105
+ * the stale `.yaml` files no longer present in `changes`.
106
+ */
107
+ replaceGraphContent(changes) {
108
+ if (!existsSync(this.graphDir)) {
109
+ writeContentMap(this.graphDir, changes);
110
+ return;
111
+ }
112
+ if (existsSync(path.join(this.graphDir, '.git'))) {
113
+ writeContentMap(this.graphDir, changes);
114
+ deleteStaleYamlFiles(this.graphDir, changes);
115
+ return;
116
+ }
117
+ const parent = path.dirname(this.graphDir);
118
+ const base = path.basename(this.graphDir);
119
+ const suffix = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
120
+ const tmpDir = path.join(parent, `${base}.corum-tmp-${suffix}`);
121
+ const oldDir = path.join(parent, `${base}.corum-old-${suffix}`);
122
+ rmSync(tmpDir, { recursive: true, force: true });
123
+ cpSync(this.graphDir, tmpDir, { recursive: true });
124
+ writeContentMap(tmpDir, changes);
125
+ deleteStaleYamlFiles(tmpDir, changes);
126
+ renameSync(this.graphDir, oldDir);
127
+ try {
128
+ renameSync(tmpDir, this.graphDir);
129
+ }
130
+ catch (err) {
131
+ renameSync(oldDir, this.graphDir);
132
+ throw err;
133
+ }
134
+ rmSync(oldDir, { recursive: true, force: true });
135
+ }
136
+ }
137
+ function writeContentMap(baseDir, changes) {
138
+ for (const [key, content] of changes) {
139
+ const filePath = resolveContentPath(baseDir, key);
140
+ mkdirSync(path.dirname(filePath), { recursive: true });
141
+ writeFileSync(filePath, content);
142
+ }
143
+ }
144
+ function deleteStaleYamlFiles(baseDir, changes) {
145
+ const existingYaml = new Map();
146
+ walkYamlFilesIntoMap(baseDir, baseDir, existingYaml);
147
+ for (const key of existingYaml.keys()) {
148
+ if (!changes.has(key)) {
149
+ rmSync(resolveContentPath(baseDir, key), { force: true });
88
150
  }
89
- // TODO: create a git commit for these changes via git.add() + git.commit().
90
- // Currently _message is unused — file writes are persisted but not committed to git history.
91
151
  }
92
152
  }
153
+ async function commitToGitIfRepo(graphDir, message) {
154
+ let repoRoot;
155
+ try {
156
+ repoRoot = await git.findRoot({ fs, filepath: path.resolve(graphDir) });
157
+ }
158
+ catch {
159
+ return; // Not inside a git repo — plain directory writes only.
160
+ }
161
+ const rel = path.relative(repoRoot, path.resolve(graphDir)).split(path.sep).join('/');
162
+ const matrix = await git.statusMatrix({
163
+ fs,
164
+ dir: repoRoot,
165
+ filepaths: rel === '' ? undefined : [rel],
166
+ });
167
+ let staged = false;
168
+ for (const [filepath, head, workdir] of matrix) {
169
+ if (head === 1 && workdir === 0) {
170
+ await git.remove({ fs, dir: repoRoot, filepath });
171
+ staged = true;
172
+ }
173
+ else if (workdir === 2) {
174
+ await git.add({ fs, dir: repoRoot, filepath });
175
+ staged = true;
176
+ }
177
+ }
178
+ if (!staged)
179
+ return;
180
+ await git.commit({
181
+ fs,
182
+ dir: repoRoot,
183
+ message,
184
+ author: { name: 'corum', email: 'corum@localhost' },
185
+ });
186
+ }
93
187
  function readPackTemplatesIntoMap(packDir, map) {
94
188
  if (!existsSync(packDir))
95
189
  return;
@@ -100,25 +194,6 @@ function readPackTemplatesIntoMap(packDir, map) {
100
194
  map.set(`${packName}/${relKey}`, content);
101
195
  }
102
196
  }
103
- function resolveContentPath(baseDir, key) {
104
- if (key.includes('\\') ||
105
- key.includes('\0') ||
106
- path.posix.isAbsolute(key) ||
107
- path.win32.isAbsolute(key)) {
108
- throw new SourceError(`invalid ContentMap key: ${key}`);
109
- }
110
- const normalised = path.posix.normalize(key);
111
- if (normalised === '..' || normalised.startsWith('../') || normalised === '.') {
112
- throw new SourceError(`invalid ContentMap key: ${key}`);
113
- }
114
- const resolvedBase = path.resolve(baseDir);
115
- const resolvedPath = path.resolve(resolvedBase, ...normalised.split('/'));
116
- const relative = path.relative(resolvedBase, resolvedPath);
117
- if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
118
- throw new SourceError(`ContentMap key escapes graphDir: ${key}`);
119
- }
120
- return resolvedPath;
121
- }
122
197
  function walkYamlFilesIntoMap(baseDir, currentDir, map, excludeDirs = new Set()) {
123
198
  for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
124
199
  const fullPath = path.join(currentDir, entry.name);
@@ -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, 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)
@@ -514,10 +493,22 @@ export function createApp(graph, reloadEvents = createReloadEvents(), source, mu
514
493
  const multi = await multiCache.get();
515
494
  overlay = computeClusterOverlay(multi, req.query.ref, overlayRefs, nodeId);
516
495
  }
496
+ // Compute included nodes from dangling semantic edges: data-type nodes (Schema,
497
+ // EnumDefinition) are expanded with structural children; operational nodes get
498
+ // root metadata only (for connectivity panels).
499
+ const clusterIds = new Set([cluster.root.id, ...cluster.descendants.map(n => n.id)]);
500
+ const externalIds = new Set();
501
+ for (const edge of cluster.edges) {
502
+ if (!clusterIds.has(edge.from))
503
+ externalIds.add(edge.from);
504
+ if (!clusterIds.has(edge.to))
505
+ externalIds.add(edge.to);
506
+ }
507
+ const includedNodes = expandExternalNodes(targetGraph, externalIds);
517
508
  res.json({
518
509
  root: summarizeNodeForNavigation(targetGraph, annotateNode(targetGraph, cluster.root)),
519
510
  descendants: cluster.descendants.map(child => summarizeNodeForNavigation(targetGraph, annotateNode(targetGraph, child))),
520
- includedNodes: cluster.includedNodes.map(node => summarizeNodeForNavigation(targetGraph, annotateNode(targetGraph, node))),
511
+ includedNodes: includedNodes.map(node => summarizeNodeForNavigation(targetGraph, annotateNode(targetGraph, node))),
521
512
  edges: cluster.edges,
522
513
  overlay,
523
514
  });
@@ -627,6 +618,7 @@ export function startWebServer(graph, options = {}) {
627
618
  : await loadGraph({ graphPath, strict: true });
628
619
  replaceGraph(graph, nextGraph);
629
620
  multiCache?.invalidate();
621
+ options.onReload?.();
630
622
  reloadEvents.notify();
631
623
  logger(`[corum] graph reloaded after ${reason}`);
632
624
  })();
@@ -645,6 +637,7 @@ export function startWebServer(graph, options = {}) {
645
637
  logger,
646
638
  onReload: () => {
647
639
  multiCache?.invalidate();
640
+ options.onReload?.();
648
641
  reloadEvents.notify();
649
642
  },
650
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.38",
3
+ "version": "0.1.40",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",