@mnstry/atelier 0.2.0-alpha.5 → 0.2.0-alpha.8

package/src/graph/graph.mjs

@@ -6,9 +6,12 @@ import {
   REPO_ACCESS_SCHEMA,
   VALID_RELATION_TYPES,
   buildKnowledgeGraph,
+  createGraphFileCache,
   parseYamlSubset,
 } from './knowledge-graph.mjs'
 
+export { createGraphFileCache }
+
 // Compatibility exports. Parsing, census, validation, and diagnostics all live
 // in knowledge-graph.mjs; this module only projects its canonical result into
 // the long-standing `atelier graph` artifact shape.
@@ -100,12 +103,71 @@ function externalRepos(project) {
     .sort((a, b) => String(a.name).localeCompare(String(b.name)))
 }
 
-function canonicalBuild(project) {
+function canonicalBuild(project, overrides = {}) {
   const input = canonicalInput(project)
-  const result = buildKnowledgeGraph(input.options)
+  const result = buildKnowledgeGraph({ ...input.options, ...overrides })
   return { input, result }
 }
 
+// The supported project-to-options seam: the exact buildKnowledgeGraph options
+// every graph consumer derives from a loaded project, plus the configured
+// repositories that could not be read.
+export function canonicalGraphOptions(project) {
+  return canonicalInput(project)
+}
+
+const canonicalEdgeId = (edge) => JSON.stringify([edge.source, edge.type, edge.target])
+
+// The canonical graph for a loaded project, for consumers that need derived
+// edges and the source offsets behind them. Nothing is resolved here: nodes,
+// edges, link occurrences and link findings all come from
+// buildKnowledgeGraph. Each edge gains a stable id and an origin; a derived
+// edge carries every source occurrence that produced it. Embedded assets are
+// reported beside the graph, like link occurrences: `embeds` holds one record
+// per embed occurrence and `assets` each embedded file once. Neither adds a
+// node or an edge.
+// `fileCache` (createGraphFileCache) lets repeated builds of one workspace
+// reuse the per-file census and link scan of every Markdown source whose
+// bytes did not change; the result is the same as without it. `observedDigest`
+// (see createGraphFileCache) lets a caller that observes sources by digest
+// spare the read of a source it knows unchanged.
+export function buildCanonicalGraph(project, { isLinkTargetEligible, isAssetEligible, fileCache = null, observedDigest = null } = {}) {
+  const { input, result } = canonicalBuild(project, {
+    ...(isLinkTargetEligible ? { isLinkTargetEligible } : {}),
+    ...(isAssetEligible ? { isAssetEligible } : {}),
+    ...(fileCache ? { fileCache } : {}),
+    ...(observedDigest ? { observedDigest } : {}),
+  })
+  const canonical = result.workspaceGraph ?? { nodes: [], edges: [], diagnostics: [] }
+  const occurrences = new Map()
+  for (const link of result.resolvedLinks ?? []) {
+    const id = canonicalEdgeId(link)
+    if (!occurrences.has(id)) occurrences.set(id, [])
+    occurrences.get(id).push(link)
+  }
+  const edges = canonical.edges.map((edge) => {
+    const id = canonicalEdgeId(edge)
+    return edge.declared === true
+      ? { id, ...edge, origin: 'declared' }
+      : { id, ...edge, origin: 'ordinary-link', occurrences: occurrences.get(id) ?? [] }
+  })
+  const embeds = result.resolvedEmbeds ?? []
+  const assets = [...new Map(embeds.map((embed) => [embed.asset.id, embed.asset])).values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+  return {
+    ok: result.ok && input.missing.length === 0,
+    errors: [...input.missing, ...result.errors],
+    options: input.options,
+    nodes: canonical.nodes,
+    edges,
+    diagnostics: canonical.diagnostics,
+    links: result.resolvedLinks ?? [],
+    embeds,
+    assets,
+    linkDiagnostics: result.linkDiagnostics ?? [],
+    ...(result.fileCensus ? { fileCensus: result.fileCensus } : {}),
+  }
+}
+
 export function buildGraph(project) {
   const { input, result } = canonicalBuild(project)
   const canonical = result.workspaceGraph ?? { nodes: [], edges: [], diagnostics: [] }