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

package/src/graph/knowledge-graph.mjs

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto'
 import fs from 'node:fs'
 import path from 'node:path'
 import { VALID_AUDIENCES } from '../projection/policy.mjs'
@@ -586,7 +587,9 @@ export function generatedFrontmatter({ id, repoName, rel, title, summary, domain
   ].join('\n')
 }
 
-export function nodeForFile(repoName, repoRoot, coverage, file, repoAccessConfig) {
+// `sourceText`, when given, is the Markdown source already read as UTF-8 text,
+// so a caller that holds the bytes does not read the file again.
+export function nodeForFile(repoName, repoRoot, coverage, file, repoAccessConfig, sourceText = null) {
   const inferredLifecycle = inferLifecycle(file.rel)
   const inferredDomain = inferDomain(repoName, file.rel)
   const inferredStatus = inferStatus(inferredLifecycle, file.rel)
@@ -601,7 +604,7 @@ export function nodeForFile(repoName, repoRoot, coverage, file, repoAccessConfig
   let atelier = { section: coverage.sections.get(file.rel) || null, status: null, kind: null }
 
   if (file.ext === '.md') {
-    const raw = fs.readFileSync(file.abs, 'utf8')
+    const raw = typeof sourceText === 'string' ? sourceText : fs.readFileSync(file.abs, 'utf8')
     const frontmatter = markdownFrontmatterState(raw)
     metadata = frontmatter.metadata
     if (frontmatter.kind !== 'valid' || !isPlainObject(metadata.kg)) {
@@ -693,27 +696,461 @@ export function nodeForFile(repoName, repoRoot, coverage, file, repoAccessConfig
   }
 }
 
-export function markdownLinkEdges(repoRoot, nodesByPath) {
-  const edges = []
-  for (const [rel, node] of nodesByPath) {
-    if (!rel.endsWith('.md')) continue
-    const raw = fs.readFileSync(path.join(repoRoot, rel), 'utf8')
-    const re = /\[[^\]]+\]\(([^)\s#]+)(?:#[^)]+)?\)/g
-    let m
-    while ((m = re.exec(raw))) {
-      const href = m[1]
-      if (/^[a-z]+:/i.test(href) || href.startsWith('#')) continue
-      const target = path
-        .normalize(path.join(path.dirname(rel), decodeURIComponent(href)))
-        .split(path.sep)
-        .join('/')
-      const direct = nodesByPath.get(target)
-      const index = nodesByPath.get(posixJoin(target, 'README.md')) || nodesByPath.get(posixJoin(target, 'index.md'))
-      const targetNode = direct || index
-      if (targetNode) edges.push({ source: node.id, target: targetNode.id, type: 'links_to' })
+// ---------------------------------------------------------------------------
+// Ordinary links: Markdown links and wikilinks
+// ---------------------------------------------------------------------------
+
+// Link findings are reported beside the graph, never inside a graph artifact,
+// so committed graphs stay free of offsets and unresolved-link noise.
+export const LINK_DIAGNOSTIC_CODES = Object.freeze([
+  'link-target-unresolved',
+  'link-target-outside-enrolled-roots',
+  'link-target-ambiguous',
+  'link-href-malformed',
+  'link-source-not-utf8',
+])
+
+const MARKDOWN_LINK_RE = /\[[^\]]+\]\(([^)\s#]+)(#[^)]+)?\)/g
+const WIKILINK_RE = /\[\[([^[\]|#^]+)([#^][^[\]|]*)?(?:\|[^[\]]*)?\]\]/g
+
+function frontMatterEnd(text) {
+  if (!/^---\r?\n/.test(text)) return 0
+  const closeRe = /\r?\n---[ \t]*\r?\n/g
+  closeRe.lastIndex = 3
+  const close = closeRe.exec(text)
+  return close ? close.index + close[0].length : 0
+}
+
+// Fenced code from `bodyStart` on: the closed blocks, and the fence still open
+// when the text ends, if any. The one statement of the fence rules, shared by
+// the link scanner and by `unclosedFenceAtEnd`.
+function fencedBlocks(text, bodyStart) {
+  const ranges = []
+  let fence = null
+  let offset = bodyStart
+  while (offset < text.length) {
+    const eol = text.indexOf('\n', offset)
+    const next = eol === -1 ? text.length : eol + 1
+    const line = text.slice(offset, eol === -1 ? text.length : eol).replace(/\r$/, '')
+    if (fence) {
+      const close = line.match(/^ {0,3}(`{3,}|~{3,})[ \t]*$/)
+      if (close && close[1][0] === fence.char && close[1].length >= fence.length) {
+        ranges.push([fence.start, next])
+        fence = null
+      }
+    } else {
+      const open = line.match(/^( {0,3})(`{3,}|~{3,})(.*)$/)
+      if (open && !(open[2][0] === '`' && open[3].includes('`'))) {
+        fence = { char: open[2][0], length: open[2].length, indent: open[1].length, start: offset }
+      }
     }
+    offset = next
   }
-  return edges
+  return { ranges, open: fence }
+}
+
+// The fence a Markdown text ends inside, as the link scanner reads it:
+// { char, length, indent }, or null when every fence closes. Front matter is
+// never read for fences. Anything appended after such a text is code until a
+// closing fence of the same character and at least the same length.
+export function unclosedFenceAtEnd(raw) {
+  const text = String(raw ?? '')
+  const { open } = fencedBlocks(text, frontMatterEnd(text))
+  return open ? { char: open.char, length: open.length, indent: open.indent } : null
+}
+
+// Regions whose text is never read as a link: front matter (known or unknown
+// YAML alike), fenced code and inline code. Offsets index the text as read,
+// with no newline normalization.
+function unscannedRanges(text) {
+  const bodyStart = frontMatterEnd(text)
+  const fenced = fencedBlocks(text, bodyStart)
+  const ranges = bodyStart > 0 ? [[0, bodyStart], ...fenced.ranges] : fenced.ranges
+  if (fenced.open) ranges.push([fenced.open.start, text.length])
+
+  // Inline code between the block ranges. A span closes on a backtick run of
+  // the same length inside the same paragraph; an unclosed run is plain text.
+  const blocks = [...ranges].sort((a, b) => a[0] - b[0])
+  let segmentStart = bodyStart
+  for (const [blockStart, blockEnd] of [...blocks.filter(([start]) => start >= bodyStart), [text.length, text.length]]) {
+    inlineCodeRanges(text, segmentStart, blockStart, ranges)
+    segmentStart = Math.max(segmentStart, blockEnd)
+  }
+  return ranges.sort((a, b) => a[0] - b[0])
+}
+
+function inlineCodeRanges(text, from, to, ranges) {
+  const runRe = /`+/g
+  runRe.lastIndex = from
+  let open
+  while ((open = runRe.exec(text)) && open.index < to) {
+    const blankRe = /\n[ \t]*\r?\n/g
+    blankRe.lastIndex = open.index
+    const blank = blankRe.exec(text)
+    const paragraphEnd = Math.min(to, blank ? blank.index : text.length)
+    const closeRe = /`+/g
+    closeRe.lastIndex = open.index + open[0].length
+    let close
+    let closed = false
+    while ((close = closeRe.exec(text)) && close.index < paragraphEnd) {
+      if (close[0].length !== open[0].length) continue
+      ranges.push([open.index, close.index + close[0].length])
+      runRe.lastIndex = close.index + close[0].length
+      closed = true
+      break
+    }
+    if (!closed) runRe.lastIndex = open.index + open[0].length
+  }
+}
+
+// Every ordinary link occurrence in one Markdown text, in source order.
+// `range` covers the whole construct and `targetRange` the written target, as
+// half-open UTF-16 offsets into the text exactly as read; byte offsets are
+// added by the resolver once the source is known to round-trip as UTF-8.
+export function scanMarkdownLinks(raw) {
+  const text = String(raw ?? '')
+  const skipped = unscannedRanges(text)
+  const overlaps = (ranges, start, end) => ranges.some(([a, b]) => start < b && end > a)
+  // A construct is unscanned when it begins inside such a region. Inline code
+  // inside a link's own label ([`name`](target)) is an ordinary link.
+  const beginsInside = (ranges, start) => ranges.some(([a, b]) => start >= a && start < b)
+  const found = []
+  const wikiRanges = []
+
+  for (const m of text.matchAll(WIKILINK_RE)) {
+    const start = m.index
+    const end = start + m[0].length
+    if (beginsInside(skipped, start)) continue
+    wikiRanges.push([start, end])
+    found.push({
+      syntax: 'wikilink',
+      embed: text[start - 1] === '!',
+      href: m[1].trim(),
+      fragment: m[2] ?? '',
+      range: { start, end },
+      targetRange: { start: start + 2, end: start + 2 + m[1].length },
+    })
+  }
+
+  for (const m of text.matchAll(MARKDOWN_LINK_RE)) {
+    const start = m.index
+    const end = start + m[0].length
+    if (beginsInside(skipped, start) || overlaps(wikiRanges, start, end)) continue
+    const targetStart = start + m[0].indexOf('](') + 2
+    found.push({
+      syntax: 'markdown',
+      embed: text[start - 1] === '!',
+      href: m[1],
+      fragment: m[2] ?? '',
+      range: { start, end },
+      targetRange: { start: targetStart, end: targetStart + m[1].length },
+    })
+  }
+
+  return found.sort((a, b) => a.range.start - b.range.start)
+}
+
+function addByteOffsets(text, occurrences) {
+  const offsets = [...new Set(occurrences.flatMap((item) => [item.range.start, item.range.end, item.targetRange.start, item.targetRange.end]))].sort(
+    (a, b) => a - b,
+  )
+  const bytes = new Map()
+  let previous = 0
+  let total = 0
+  for (const offset of offsets) {
+    total += Buffer.byteLength(text.slice(previous, offset), 'utf8')
+    bytes.set(offset, total)
+    previous = offset
+  }
+  for (const item of occurrences) {
+    for (const range of [item.range, item.targetRange]) {
+      range.byteStart = bytes.get(range.start)
+      range.byteEnd = bytes.get(range.end)
+    }
+  }
+}
+
+// `pathOf` and `repoNameOf` come from the census keys, so a caller's node
+// needs only an id: markdownLinkEdges has always accepted such nodes.
+function wikilinkCandidates(target, nodes, pathOf, repoNameOf) {
+  if (target.includes('/')) {
+    const wanted = new Set([target, `${target}.md`])
+    return { by: 'path', nodes: nodes.filter((node) => wanted.has(pathOf.get(node)) || wanted.has(`${repoNameOf.get(node)}/${pathOf.get(node)}`)) }
+  }
+  const byTitle = nodes.filter((node) => node.title !== undefined && node.title === target)
+  const byName = nodes.filter((node) => {
+    const base = path.posix.basename(pathOf.get(node))
+    return base === target || base.replace(/\.[^.]+$/, '') === target
+  })
+  const merged = [...new Map([...byTitle, ...byName].map((node) => [node.id, node])).values()]
+  return { by: byTitle.length ? 'title' : 'basename', nodes: merged }
+}
+
+// Embedded assets: files an embed names that are not documents of the census.
+// An asset is a regular file inside an enrolled repository root: never a link
+// on disk, never reached through one, never git-ignored, never inside `.git`,
+// never Markdown and never a census node.
+const assetId = (repoName, rel) => `${repoName}:asset:${rel}`
+const insideGitDirectory = (rel) => rel.split('/').includes('.git')
+const isMarkdownPath = (rel) => rel.toLowerCase().endsWith('.md')
+
+// `gitIgnoreFilter` lists a fully ignored directory once, so every ancestor of
+// a path is tested, not the path alone.
+function ignoredAtAnyDepth(isIgnored, rel) {
+  const parts = rel.split('/')
+  return parts.some((_, index) => isIgnored(parts.slice(0, index + 1).join('/')))
+}
+
+// True only for a regular file whose real location is exactly `rel` under the
+// real repository root: a link anywhere on the way, or a name that matches
+// only because the filesystem folds case, is not this file.
+function isRegularFileInside(root, rel) {
+  try {
+    const abs = path.join(root, rel)
+    if (!fs.lstatSync(abs).isFile()) return false
+    return relPath(fs.realpathSync.native(root), fs.realpathSync.native(abs)) === rel
+  } catch {
+    return false
+  }
+}
+
+// The one resolver for ordinary links across every enrolled repository.
+// `repos` is [{ name, root, nodesByPath, isIgnored? }]. A target that is
+// absent, outside the census or refused by `isLinkTargetEligible` is reported
+// identically and never inspected, so a finding cannot confirm that a withheld
+// target exists. `isAssetEligible({ repo, path })` gives embedded assets the
+// same rule: a refused asset reads exactly as an absent one.
+// The link scan of one Markdown source: its occurrences, with byte offsets
+// when the bytes round-trip as UTF-8. A pure function of the bytes, which is
+// what lets a builder keep it under the source's content digest.
+export function scanMarkdownSource(buffer) {
+  const text = buffer.toString('utf8')
+  const occurrences = scanMarkdownLinks(text)
+  const utf8Exact = Buffer.from(text, 'utf8').equals(buffer)
+  if (utf8Exact) addByteOffsets(text, occurrences)
+  return { occurrences, utf8Exact }
+}
+
+// `scanned` maps a census node to the scan of its source (scanMarkdownSource)
+// when the caller already holds it; any other Markdown node is read here.
+export function resolveWorkspaceLinks({ repos = [], isLinkTargetEligible = () => true, isAssetEligible = () => true, scanned = null } = {}) {
+  const links = []
+  const embeds = []
+  const diagnostics = []
+  const enrolled = repos.map((repo) => ({ ...repo, root: path.resolve(repo.root) }))
+  const ownerOf = new Map(enrolled.flatMap((repo) => [...repo.nodesByPath.values()].map((node) => [node, repo])))
+  const eligibleNodes = [...ownerOf.keys()].filter((node) => isLinkTargetEligible(node))
+  const pathOf = new Map(enrolled.flatMap((repo) => [...repo.nodesByPath].map(([rel, node]) => [node, rel])))
+  const repoNameOf = new Map([...ownerOf].map(([node, repo]) => [node, repo.name]))
+
+  const owningRepo = (abs) =>
+    enrolled
+      .filter((repo) => abs === repo.root || abs.startsWith(`${repo.root}${path.sep}`))
+      .sort((a, b) => b.root.length - a.root.length)[0] ?? null
+
+  // One ignore lookup per repository, made only when an embed needs it.
+  const ignoreFilters = new Map()
+  const ignoredIn = (owner) => {
+    if (!ignoreFilters.has(owner)) ignoreFilters.set(owner, owner.isIgnored ?? gitIgnoreFilter(owner.root))
+    return ignoreFilters.get(owner)
+  }
+  // Eligibility is asked before the file is looked at, so a refused asset and
+  // an absent one take the same path to the same finding.
+  const assetAt = (owner, rel) => {
+    if (!rel || rel.startsWith('../') || rel === '..' || path.posix.isAbsolute(rel)) return null
+    if (owner.nodesByPath.has(rel) || isMarkdownPath(rel) || insideGitDirectory(rel)) return null
+    if (isAssetEligible({ repo: owner.name, path: rel }) !== true) return null
+    if (ignoredAtAnyDepth(ignoredIn(owner), rel) || !isRegularFileInside(owner.root, rel)) return null
+    return { id: assetId(owner.name, rel), repo: owner.name, path: rel, extension: path.posix.extname(rel).slice(1).toLowerCase() }
+  }
+
+  // Basename index over every enrolled repository: built once, and only when a
+  // bare wikilink embed asks for it. It holds names only; eligibility is tested
+  // per candidate when a name is looked up.
+  let basenameIndex = null
+  const assetsNamed = (name) => {
+    if (!basenameIndex) {
+      basenameIndex = new Map()
+      const roots = new Set(enrolled.map((item) => item.root))
+      for (const owner of enrolled) {
+        const isIgnored = ignoredIn(owner)
+        const visit = (dir) => {
+          for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (ent.name === '.git') continue
+            const abs = path.join(dir, ent.name)
+            const rel = relPath(owner.root, abs)
+            if (isIgnored(rel)) continue
+            // A nested enrolled repository owns its own files.
+            if (ent.isDirectory()) {
+              if (!roots.has(abs)) visit(abs)
+            } else if (ent.isFile() && !isMarkdownPath(rel) && !owner.nodesByPath.has(rel)) {
+              if (!basenameIndex.has(ent.name)) basenameIndex.set(ent.name, [])
+              basenameIndex.get(ent.name).push({ owner, rel })
+            }
+          }
+        }
+        visit(owner.root)
+      }
+    }
+    return (basenameIndex.get(name) ?? []).map(({ owner, rel }) => assetAt(owner, rel)).filter(Boolean)
+  }
+
+  // A wikilink embed names an asset by repository-relative path (the source's
+  // own repository first, then `<repository>/<path>`), or by bare file name.
+  const wikilinkAssets = (repo, target) => {
+    if (!target.includes('/')) return { by: 'basename', assets: assetsNamed(target) }
+    const wanted = path.posix.normalize(target)
+    const candidates = [
+      assetAt(repo, wanted),
+      ...enrolled.filter((owner) => wanted.startsWith(`${owner.name}/`)).map((owner) => assetAt(owner, wanted.slice(owner.name.length + 1))),
+    ].filter(Boolean)
+    return { by: 'path', assets: candidates.slice(0, 1) }
+  }
+
+  for (const repo of enrolled) {
+    for (const [rel, node] of repo.nodesByPath) {
+      if (!rel.endsWith('.md') || !isLinkTargetEligible(node)) continue
+      const { occurrences, utf8Exact } = scanned?.get(node) ?? scanMarkdownSource(fs.readFileSync(path.join(repo.root, rel)))
+      const finding = (code, occurrence, detail, extra = {}) =>
+        diagnostics.push({
+          severity: 'warning',
+          type: code,
+          code,
+          node: node.id,
+          repo: repo.name,
+          path: rel,
+          ...(occurrence
+            ? { syntax: occurrence.syntax, href: portableText(occurrence.href), range: occurrence.range, targetRange: occurrence.targetRange }
+            : {}),
+          ...extra,
+          message: `${repo.name}/${rel}: ${detail}`,
+        })
+
+      if (!utf8Exact && occurrences.length) finding('link-source-not-utf8', null, 'source is not valid UTF-8; link byte offsets are withheld')
+
+      for (const occurrence of occurrences) {
+        const shown = JSON.stringify(portableText(occurrence.href))
+        let targetNode = null
+        let asset = null
+        let resolvedBy = 'path'
+
+        if (occurrence.syntax === 'wikilink') {
+          const candidates = wikilinkCandidates(occurrence.href, eligibleNodes, pathOf, repoNameOf)
+          if (candidates.nodes.length > 1) {
+            finding('link-target-ambiguous', occurrence, `wikilink ${shown} matches ${candidates.nodes.length} documents; refusing to choose`, {
+              candidates: candidates.nodes.map((item) => item.id).sort(),
+            })
+            continue
+          }
+          targetNode = candidates.nodes[0] ?? null
+          resolvedBy = candidates.by
+          if (!targetNode && occurrence.embed) {
+            const found = wikilinkAssets(repo, occurrence.href)
+            if (found.assets.length > 1) {
+              finding('link-target-ambiguous', occurrence, `embed ${shown} matches ${found.assets.length} files; refusing to choose`, {
+                candidates: found.assets.map((item) => item.id).sort(),
+              })
+              continue
+            }
+            asset = found.assets[0] ?? null
+            resolvedBy = found.by
+          }
+        } else {
+          const href = occurrence.href
+          if (/^[a-z]+:/i.test(href) || href.startsWith('#')) continue
+          let decoded
+          try {
+            decoded = decodeURIComponent(href)
+          } catch {
+            finding('link-href-malformed', occurrence, `link ${shown} is not valid percent-encoding`)
+            continue
+          }
+          const abs = path.join(repo.root, path.dirname(rel), decoded)
+          const owner = owningRepo(abs)
+          if (!owner) {
+            finding('link-target-outside-enrolled-roots', occurrence, `link ${shown} leaves every enrolled repository`)
+            continue
+          }
+          // A link that climbs above its own repository and comes back in
+          // through the checkout's directory name depends on where the
+          // repository happens to be checked out. It is not a repository-local
+          // link and never was one; only a link into ANOTHER enrolled
+          // repository may leave the root.
+          const lexical = path.posix.normalize(posixJoin(path.posix.dirname(rel), decoded.split(path.sep).join('/')))
+          if (owner === repo && (lexical === '..' || lexical.startsWith('../'))) {
+            finding('link-target-outside-enrolled-roots', occurrence, `link ${shown} leaves its repository and re-enters through the checkout path`)
+            continue
+          }
+          const target = relPath(owner.root, abs)
+          // Eligibility is tested per candidate, before choosing: a withheld
+          // candidate is skipped exactly as an absent one, so it can never
+          // shadow an eligible fallback and change the edge set.
+          targetNode =
+            [target, posixJoin(target, 'README.md'), posixJoin(target, 'index.md')]
+              .map((candidate) => owner.nodesByPath.get(candidate))
+              .find((candidate) => candidate && isLinkTargetEligible(candidate)) ?? null
+          if (!targetNode && occurrence.embed) asset = assetAt(owner, target)
+        }
+
+        if (asset) {
+          embeds.push({
+            source: node.id,
+            type: 'embeds_asset',
+            asset,
+            syntax: occurrence.syntax,
+            href: occurrence.href,
+            fragment: occurrence.fragment,
+            resolvedBy,
+            crossRepository: asset.repo !== repo.name,
+            sourceRepo: repo.name,
+            sourcePath: rel,
+            range: occurrence.range,
+            targetRange: occurrence.targetRange,
+          })
+          continue
+        }
+        if (!targetNode) {
+          finding('link-target-unresolved', occurrence, `link ${shown} does not resolve to an enrolled document`)
+          continue
+        }
+        links.push({
+          source: node.id,
+          target: targetNode.id,
+          type: 'links_to',
+          syntax: occurrence.syntax,
+          embed: occurrence.embed,
+          href: occurrence.href,
+          fragment: occurrence.fragment,
+          resolvedBy,
+          crossRepository: ownerOf.get(targetNode) !== repo,
+          sourceRepo: repo.name,
+          sourcePath: rel,
+          targetRepo: ownerOf.get(targetNode).name,
+          targetPath: targetNode.path,
+          range: occurrence.range,
+          targetRange: occurrence.targetRange,
+        })
+      }
+    }
+  }
+
+  const order = (item) => `${item.sourceRepo ?? item.repo}/${item.sourcePath ?? item.path}`
+  const byPosition = (a, b) => order(a).localeCompare(order(b)) || (a.range?.start ?? -1) - (b.range?.start ?? -1)
+  return { links: links.sort(byPosition), embeds: embeds.sort(byPosition), diagnostics: diagnostics.sort(byPosition) }
+}
+
+// A repository's own artifact depends on that repository alone: path links
+// that stay inside it. Wikilinks and cross-repository links resolve against
+// the whole enrolment and belong to the workspace graph only.
+function repoLocalLink(link) {
+  return !link.crossRepository && link.syntax === 'markdown'
+}
+
+const linkEdge = (link) => ({ source: link.source, target: link.target, type: 'links_to' })
+
+export function markdownLinkEdges(repoRoot, nodesByPath) {
+  const { links } = resolveWorkspaceLinks({ repos: [{ name: path.basename(repoRoot), root: repoRoot, nodesByPath }] })
+  return links.filter(repoLocalLink).map(linkEdge)
 }
 
 export function declaredRelationEdges(nodes) {
@@ -854,6 +1291,57 @@ export function validateKnowledgeGraph(nodes, edges, orphanSidecars = [], { exte
   return errors
 }
 
+// A per-file cache for repeated builds of one workspace: the census node and
+// the link scan of every Markdown source, kept under the sha256 of the bytes
+// they were derived from together with the per-file inputs that are not in
+// the bytes (coverage and the repository's read boundary). Both derivations
+// are pure functions of those inputs, so an entry is reused only when a build
+// with no cache would compute the same values; a file whose bytes or inputs
+// differ is parsed again, and a file no longer in the census leaves the cache.
+// Without `observedDigest` every source is read and hashed on every build: the
+// cache never trusts a digest it did not compute from the bytes. A caller that
+// already observes the sources by digest (the maintenance engine's index: stat
+// hint between full reconciliations, every file hashed on a full one) may pass
+// `observedDigest(repoName, rel)`, returning `sha256:<hex>` or null. An entry
+// whose digest equals the observed one is then reused without opening the
+// file; the tradeoff is exactly the observer's: bytes that change under an
+// unchanged stat hint are not seen until the observer hashes the file again,
+// and until then no view is rebuilt for them either. Any other file is read
+// and hashed here as always. Derived, droppable state.
+export function createGraphFileCache() {
+  return { files: new Map() }
+}
+
+function isGraphFileCache(cache) {
+  return cache !== null && typeof cache === 'object' && cache.files instanceof Map
+}
+
+const sha256Hex = (bytes) => createHash('sha256').update(bytes).digest('hex')
+
+// The Markdown census entry for one file, from the cache under an equal digest
+// and equal inputs, or freshly derived. The returned node and scan are clones
+// so a caller's changes never reach the cache.
+function markdownCensus({ repoName, repoRoot, coverage, file, accessConfig, cache, next, observedDigest }) {
+  const inputs = JSON.stringify([coverage.surfaced.has(file.rel), coverage.sections.get(file.rel) || null, repoReadBoundary(accessConfig, repoName)])
+  const key = `${repoName}\u0000${file.rel}`
+  const cached = cache?.files.get(key)
+  const observed = cached && observedDigest ? observedDigest(repoName, file.rel) : null
+  let entry
+  let read = false
+  if (cached && cached.inputs === inputs && typeof observed === 'string' && observed === `sha256:${cached.digest}`) {
+    entry = cached
+  } else {
+    read = true
+    const buffer = fs.readFileSync(file.abs)
+    const digest = sha256Hex(buffer)
+    entry = cached && cached.digest === digest && cached.inputs === inputs
+      ? cached
+      : { digest, inputs, node: nodeForFile(repoName, repoRoot, coverage, file, accessConfig, buffer.toString('utf8')), scan: scanMarkdownSource(buffer) }
+  }
+  next?.set(key, entry)
+  return { node: structuredClone(entry.node), scan: structuredClone(entry.scan), reused: entry === cached, read }
+}
+
 export function buildKnowledgeGraph({
   workspaceRoot,
   repoAccessConfig,
@@ -863,8 +1351,14 @@ export function buildKnowledgeGraph({
   externalRepos = [],
   externalRelationPrefixes = [],
   externalRelationIds = [],
+  isLinkTargetEligible = undefined,
+  isAssetEligible = undefined,
+  fileCache = null,
+  observedDigest = null,
 } = {}) {
   if (!workspaceRoot) throw new Error('workspaceRoot is required')
+  if (fileCache !== null && !isGraphFileCache(fileCache)) throw new Error('fileCache must come from createGraphFileCache')
+  if (observedDigest !== null && typeof observedDigest !== 'function') throw new Error('observedDigest must be a function')
   const resolvedWorkspaceRoot = path.resolve(workspaceRoot)
   const external = new Set(externalRepos)
   const discoveredEntries = repoEntries
@@ -896,6 +1390,10 @@ export function buildKnowledgeGraph({
   const workspaceOrphanSidecars = []
   const workspaceIgnoredSidecars = []
   const repoGraphs = []
+  const census = []
+  const scanned = new Map()
+  const nextCache = fileCache ? new Map() : null
+  const reuse = { reused: 0, derived: 0, read: 0 }
 
   for (const entry of roots) {
     const repoRoot = entry.path
@@ -910,12 +1408,32 @@ export function buildKnowledgeGraph({
     const nodesByPath = new Map()
 
     for (const file of files) {
-      const node = nodeForFile(repoName, repoRoot, coverage, file, accessConfig)
+      let node
+      if (file.ext === '.md') {
+        // One read per Markdown source: the census entry and the link scan come from the same bytes.
+        const entry = markdownCensus({ repoName, repoRoot, coverage, file, accessConfig, cache: fileCache, next: nextCache, observedDigest })
+        node = entry.node
+        scanned.set(node, entry.scan)
+        reuse[entry.reused ? 'reused' : 'derived'] += 1
+        if (entry.read) reuse.read += 1
+      } else {
+        node = nodeForFile(repoName, repoRoot, coverage, file, accessConfig)
+      }
       nodes.push(node)
       nodesByPath.set(file.rel, node)
     }
 
-    const edges = uniqueEdges([...markdownLinkEdges(repoRoot, nodesByPath), ...declaredRelationEdges(nodes)])
+    census.push({ name: repoName, root: repoRoot, nodes, nodesByPath, isIgnored })
+  }
+  // The cache holds exactly the Markdown sources of this census, each under the digest this build read.
+  if (nextCache) fileCache.files = nextCache
+
+  // Links resolve once, against every enrolled repository together.
+  const resolved = resolveWorkspaceLinks({ repos: census, scanned, ...(isLinkTargetEligible ? { isLinkTargetEligible } : {}), ...(isAssetEligible ? { isAssetEligible } : {}) })
+
+  for (const { name: repoName, root: repoRoot, nodes } of census) {
+    const localLinks = resolved.links.filter((link) => link.sourceRepo === repoName && repoLocalLink(link))
+    const edges = uniqueEdges([...localLinks.map(linkEdge), ...declaredRelationEdges(nodes)])
     const graph = {
       schema: KNOWLEDGE_GRAPH_SCHEMA,
       repo: repoName,
@@ -930,6 +1448,7 @@ export function buildKnowledgeGraph({
     workspaceNodes.push(...graph.nodes)
     workspaceEdges.push(...graph.edges)
   }
+  workspaceEdges.push(...resolved.links.filter((link) => !repoLocalLink(link)).map(linkEdge))
 
   const validationErrors = validateKnowledgeGraph(workspaceNodes, workspaceEdges, workspaceOrphanSidecars, {
     externalRelationPrefixes,
@@ -940,7 +1459,7 @@ export function buildKnowledgeGraph({
     workspace: path.basename(resolvedWorkspaceRoot),
     diagnostics: graphDiagnostics(workspaceNodes),
     nodes: workspaceNodes.sort((a, b) => `${a.repo}/${a.path}`.localeCompare(`${b.repo}/${b.path}`)),
-    edges: workspaceEdges.sort((a, b) => `${a.source}:${a.target}:${a.type}`.localeCompare(`${b.source}:${b.target}:${b.type}`)),
+    edges: uniqueEdges(workspaceEdges).sort((a, b) => `${a.source}:${a.target}:${a.type}`.localeCompare(`${b.source}:${b.target}:${b.type}`)),
   }
   workspaceGraph.nodeCount = workspaceGraph.nodes.length
   workspaceGraph.edgeCount = workspaceGraph.edges.length
@@ -952,6 +1471,11 @@ export function buildKnowledgeGraph({
     workspaceGraph,
     orphanSidecars: workspaceOrphanSidecars,
     ignoredSidecars: workspaceIgnoredSidecars,
+    resolvedLinks: resolved.links,
+    resolvedEmbeds: resolved.embeds,
+    linkDiagnostics: resolved.diagnostics,
+    // How many Markdown census entries this build derived, how many it reused from the file cache, and how many sources it opened.
+    fileCensus: reuse,
   }
 }