@treeseed/sdk 0.12.62 → 0.13.0-rc.2

package/dist/graph/build/md-node.js

@@ -0,0 +1,210 @@
+import GithubSlugger from "github-slugger";
+import { toString } from "mdast-util-to-string";
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import remarkMdx from "remark-mdx";
+import remarkParse from "remark-parse";
+import { unified } from "unified";
+import { readCanonicalFieldValue } from "../../entrypoints/models/sdk-fields.js";
+import {
+  normalizeText
+} from "../schema.js";
+const markdownProcessor = unified().use(remarkParse).use(remarkMdx);
+async function walkMarkdownFiles(root) {
+  try {
+    const entries = await readdir(root, { withFileTypes: true });
+    const children = await Promise.all(entries.map(async (entry) => {
+      const fullPath = path.join(root, entry.name);
+      if (entry.isDirectory()) {
+        return walkMarkdownFiles(fullPath);
+      }
+      if (entry.isFile() && /\.(md|mdx)$/iu.test(entry.name)) {
+        return [fullPath];
+      }
+      return [];
+    }));
+    return children.flat();
+  } catch {
+    return [];
+  }
+}
+function stripMarkdownExtension(value) {
+  return value.replace(/\.(md|mdx)$/iu, "");
+}
+function inferSlug(filePath, root) {
+  return stripMarkdownExtension(path.relative(root, filePath).replace(/\\/gu, "/"));
+}
+function readGraphField(definition, frontmatter, field) {
+  const binding = definition.fields[field];
+  if (binding) {
+    const value = readCanonicalFieldValue(definition, { frontmatter }, field);
+    if (value !== void 0) {
+      return value;
+    }
+  }
+  const keys = /* @__PURE__ */ new Set([field]);
+  if (binding) {
+    for (const alias of binding.aliases ?? []) keys.add(alias);
+    for (const key of binding.contentKeys ?? []) keys.add(key);
+  }
+  for (const key of keys) {
+    if (key in frontmatter) {
+      return frontmatter[key];
+    }
+  }
+  return void 0;
+}
+function walkTree(node, visit) {
+  visit(node);
+  for (const child of node.children ?? []) {
+    walkTree(child, visit);
+  }
+}
+function extractMarkdownArtifacts(body) {
+  const tree = markdownProcessor.parse(body);
+  const slugger = new GithubSlugger();
+  const headings = [];
+  const links = [];
+  const mdxImports = [];
+  walkTree(tree, (node) => {
+    const startOffset = node.position?.start?.offset ?? 0;
+    const endOffset = node.position?.end?.offset ?? startOffset;
+    if (node.type === "heading" && typeof node.depth === "number") {
+      headings.push({
+        text: toString(node).trim(),
+        slug: slugger.slug(toString(node).trim() || "section"),
+        level: node.depth,
+        startOffset,
+        endOffset
+      });
+    }
+    if (node.type === "link" && typeof node.url === "string") {
+      links.push({
+        url: node.url,
+        text: toString(node).trim(),
+        startOffset,
+        endOffset
+      });
+    }
+    if (node.type === "mdxjsEsm" && typeof node.value === "string") {
+      const matches = node.value.matchAll(/(?:import|export)\s+(?:[^'"]+?\s+from\s+)?['"]([^'"]+)['"]/gu);
+      for (const match of matches) {
+        if (match[1]) {
+          mdxImports.push(match[1]);
+        }
+      }
+    }
+  });
+  return { headings, links, mdxImports };
+}
+function buildSections(fileId, body, headings, links) {
+  const sections = [];
+  const lines = body.length;
+  const nonWhitespace = /\S/u.test(body);
+  const headingOrdinals = /* @__PURE__ */ new Map();
+  const headingPathStack = [];
+  const sectionEndForHeading = (index) => {
+    const current = headings[index];
+    for (let pointer = index + 1; pointer < headings.length; pointer += 1) {
+      if (headings[pointer].level <= current.level) {
+        return headings[pointer].startOffset;
+      }
+    }
+    return lines;
+  };
+  if (headings.length === 0) {
+    if (!nonWhitespace) {
+      return sections;
+    }
+    sections.push({
+      id: `section:${fileId}:__intro:0`,
+      fileId,
+      heading: null,
+      headingSlug: "__intro",
+      headingPath: "__intro",
+      level: 0,
+      ordinal: 0,
+      startOffset: 0,
+      endOffset: lines,
+      rawText: body,
+      normalizedText: normalizeText(body),
+      outboundLinks: links,
+      referencedEntityIds: []
+    });
+    return sections;
+  }
+  const introEnd = headings[0]?.startOffset ?? 0;
+  if (introEnd > 0 && /\S/u.test(body.slice(0, introEnd))) {
+    sections.push({
+      id: `section:${fileId}:__intro:0`,
+      fileId,
+      heading: null,
+      headingSlug: "__intro",
+      headingPath: "__intro",
+      level: 0,
+      ordinal: 0,
+      startOffset: 0,
+      endOffset: introEnd,
+      rawText: body.slice(0, introEnd),
+      normalizedText: normalizeText(body.slice(0, introEnd)),
+      outboundLinks: links.filter((link) => link.startOffset >= 0 && link.startOffset < introEnd),
+      referencedEntityIds: []
+    });
+  }
+  for (let index = 0; index < headings.length; index += 1) {
+    const heading = headings[index];
+    while ((headingPathStack.at(-1)?.level ?? 0) >= heading.level) {
+      headingPathStack.pop();
+    }
+    const parentPath = headingPathStack.at(-1)?.path;
+    const headingPath = parentPath ? `${parentPath}/${heading.slug}` : heading.slug;
+    headingPathStack.push({ level: heading.level, path: headingPath });
+    const ordinal = headingOrdinals.get(headingPath) ?? 0;
+    headingOrdinals.set(headingPath, ordinal + 1);
+    const endOffset = sectionEndForHeading(index);
+    const rawText = body.slice(heading.startOffset, endOffset);
+    sections.push({
+      id: `section:${fileId}:${headingPath}:${ordinal}`,
+      fileId,
+      heading: heading.text,
+      headingSlug: heading.slug,
+      headingPath,
+      level: heading.level,
+      ordinal,
+      startOffset: heading.startOffset,
+      endOffset,
+      rawText,
+      normalizedText: normalizeText(rawText),
+      outboundLinks: links.filter((link) => link.startOffset >= heading.startOffset && link.startOffset < endOffset),
+      referencedEntityIds: []
+    });
+  }
+  return sections;
+}
+function normalizeReferenceValue(value) {
+  return value.trim().replace(/^\.\/+/u, "").replace(/\\/gu, "/");
+}
+const GRAPH_FRONTMATTER_RELATION_FIELDS = [
+  { field: "related", edgeType: "RELATES_TO", multiple: true },
+  { field: "references", edgeType: "REFERENCES", multiple: true },
+  { field: "dependsOn", edgeType: "DEPENDS_ON", multiple: true },
+  { field: "implements", edgeType: "IMPLEMENTS", multiple: true },
+  { field: "extends", edgeType: "EXTENDS", multiple: true },
+  { field: "supersedes", edgeType: "SUPERSEDES", multiple: true },
+  { field: "belongsTo", edgeType: "BELONGS_TO", multiple: true },
+  { field: "about", edgeType: "ABOUT", multiple: true },
+  { field: "usedBy", edgeType: "USED_BY", multiple: true },
+  { field: "generatedFrom", edgeType: "GENERATED_FROM", multiple: true }
+];
+export {
+  GRAPH_FRONTMATTER_RELATION_FIELDS,
+  buildSections,
+  extractMarkdownArtifacts,
+  inferSlug,
+  markdownProcessor,
+  normalizeReferenceValue,
+  readGraphField,
+  stripMarkdownExtension,
+  walkMarkdownFiles,
+  walkTree
+};

package/dist/graph/build/parse-graph-document.d.ts

@@ -0,0 +1,30 @@
+import type { SdkModelDefinition, SdkModelRegistry } from '../../entrypoints/models/sdk-types.js';
+import { type GraphFileCatalogEntry, type ParsedGraphDocument, type ParsedGraphSection } from '../schema.js';
+export declare function parseGraphDocument(definition: SdkModelDefinition, filePath: string, source: string): ParsedGraphDocument;
+export declare function catalogForDocument(document: ParsedGraphDocument, hash: string): GraphFileCatalogEntry;
+export declare function buildReferenceMaps(documents: ParsedGraphDocument[], models: SdkModelRegistry): {
+    entityById: Map<string, ParsedGraphDocument>;
+    fileById: Map<string, ParsedGraphDocument>;
+    fileByPath: Map<string, ParsedGraphDocument>;
+    fileByRelativePath: Map<string, ParsedGraphDocument>;
+    entityByModelAndSlug: Map<string, ParsedGraphDocument>;
+    sectionById: Map<string, ParsedGraphSection>;
+    sectionByAnchor: Map<string, ParsedGraphSection>;
+    resolveReferenceString: (reference: string, sourceDocument?: ParsedGraphDocument) => {
+        kind: "unresolved";
+        targetId?: undefined;
+        fileId?: undefined;
+    } | {
+        kind: "entity";
+        targetId: string;
+        fileId: string;
+    } | {
+        kind: "section";
+        targetId: string;
+        fileId: string;
+    } | {
+        kind: "file";
+        targetId: string;
+        fileId: string;
+    };
+};

package/dist/graph/build/parse-graph-document.js

@@ -0,0 +1,206 @@
+import path from "node:path";
+import { parseFrontmatterDocument } from "../../content/frontmatter.js";
+import { resolveModelDefinition } from "../../entrypoints/models/model-registry.js";
+import {
+  createEntityNodeId,
+  createFileNodeId,
+  ensureArray,
+  normalizeText,
+  resolveGraphModelConfig
+} from "../schema.js";
+import { GRAPH_FRONTMATTER_RELATION_FIELDS, buildSections, extractMarkdownArtifacts, inferSlug, normalizeReferenceValue, readGraphField, stripMarkdownExtension } from "./md-node.js";
+function parseGraphDocument(definition, filePath, source) {
+  const parsed = parseFrontmatterDocument(source);
+  const graphConfig = resolveGraphModelConfig(definition);
+  const slug = inferSlug(filePath, definition.contentDir);
+  const fileId = createFileNodeId(definition.name, slug);
+  const entityId = createEntityNodeId(definition, slug, parsed.frontmatter);
+  const titleValue = readGraphField(definition, parsed.frontmatter, graphConfig.titleField);
+  const title = typeof titleValue === "string" && titleValue.trim() ? titleValue.trim() : slug;
+  const groupIds = graphConfig.groupField ? ensureArray(readGraphField(definition, parsed.frontmatter, graphConfig.groupField)) : [];
+  const seriesValue = graphConfig.seriesField ? readGraphField(definition, parsed.frontmatter, graphConfig.seriesField) : void 0;
+  const series = typeof seriesValue === "string" && seriesValue.trim() ? seriesValue.trim() : null;
+  const explicitId = typeof parsed.frontmatter.id === "string" && parsed.frontmatter.id.trim() ? parsed.frontmatter.id.trim() : null;
+  const status = typeof parsed.frontmatter.status === "string" && parsed.frontmatter.status.trim() ? parsed.frontmatter.status.trim() : null;
+  const canonical = parsed.frontmatter.canonical === true;
+  const canonicalRef = typeof parsed.frontmatter.canonical === "string" && parsed.frontmatter.canonical.trim() ? normalizeReferenceValue(parsed.frontmatter.canonical.trim()) : null;
+  const version = typeof parsed.frontmatter.version === "string" && parsed.frontmatter.version.trim() ? parsed.frontmatter.version.trim() : null;
+  const domain = typeof parsed.frontmatter.domain === "string" && parsed.frontmatter.domain.trim() ? parsed.frontmatter.domain.trim() : null;
+  const audience = ensureArray(parsed.frontmatter.audience);
+  const updatedAtValue = readGraphField(definition, parsed.frontmatter, "updated_at") ?? parsed.frontmatter.updatedAt ?? parsed.frontmatter.updated_at;
+  const updatedAt = typeof updatedAtValue === "string" && updatedAtValue.trim() ? updatedAtValue.trim() : null;
+  const body = parsed.body;
+  const { headings, links, mdxImports } = extractMarkdownArtifacts(body);
+  const sections = graphConfig.enableSections ? buildSections(fileId, body, headings, links) : [];
+  const configuredReferences = graphConfig.referenceFields.flatMap((referenceField) => {
+    const rawValue = readGraphField(definition, parsed.frontmatter, referenceField.field);
+    return ensureArray(rawValue).map((value) => ({
+      field: referenceField.field,
+      value: normalizeReferenceValue(value),
+      targetModels: referenceField.targetModels,
+      edgeType: referenceField.edgeType ?? "REFERENCES"
+    }));
+  });
+  const inferredRelationshipReferences = GRAPH_FRONTMATTER_RELATION_FIELDS.flatMap(
+    (entry) => ensureArray(parsed.frontmatter[entry.field]).map((value) => ({
+      field: entry.field,
+      value: normalizeReferenceValue(value),
+      edgeType: entry.edgeType
+    }))
+  );
+  const canonicalReference = canonicalRef ? [{ field: "canonical", value: canonicalRef, edgeType: "REFERENCES" }] : [];
+  const explicitReferences = [...configuredReferences, ...inferredRelationshipReferences, ...canonicalReference];
+  return {
+    fileId,
+    entityId,
+    model: definition.name,
+    entityType: graphConfig.entityType,
+    slug,
+    title,
+    path: filePath,
+    relativePath: path.relative(definition.contentDir, filePath).replace(/\\/gu, "/"),
+    dirname: path.dirname(path.relative(definition.contentDir, filePath).replace(/\\/gu, "/")),
+    body,
+    normalizedBody: normalizeText(body),
+    frontmatter: parsed.frontmatter,
+    explicitId,
+    groupIds,
+    series,
+    status,
+    canonical,
+    canonicalRef,
+    version,
+    domain,
+    audience,
+    updatedAt,
+    sections,
+    headings,
+    links,
+    mdxImports,
+    explicitReferences
+  };
+}
+function catalogForDocument(document, hash) {
+  return {
+    path: document.path,
+    relativePath: document.relativePath,
+    model: document.model,
+    slug: document.slug,
+    fileId: document.fileId,
+    hash
+  };
+}
+function buildReferenceMaps(documents, models) {
+  const entityById = /* @__PURE__ */ new Map();
+  const fileById = /* @__PURE__ */ new Map();
+  const fileByPath = /* @__PURE__ */ new Map();
+  const fileByRelativePath = /* @__PURE__ */ new Map();
+  const entityByModelAndSlug = /* @__PURE__ */ new Map();
+  const sectionById = /* @__PURE__ */ new Map();
+  const sectionByAnchor = /* @__PURE__ */ new Map();
+  for (const document of documents) {
+    entityById.set(document.entityId, document);
+    fileById.set(document.fileId, document);
+    fileByPath.set(path.resolve(document.path), document);
+    fileByRelativePath.set(stripMarkdownExtension(document.relativePath), document);
+    entityByModelAndSlug.set(`${document.model}:${document.slug}`, document);
+    for (const section of document.sections) {
+      sectionById.set(section.id, section);
+      sectionByAnchor.set(`${document.fileId}#${section.headingSlug}`, section);
+      sectionByAnchor.set(`${document.fileId}#${section.headingPath}`, section);
+    }
+  }
+  const resolveReferenceString = (reference, sourceDocument) => {
+    const trimmed = reference.trim();
+    if (!trimmed) {
+      return { kind: "unresolved" };
+    }
+    const [pathPart, hashPart = ""] = trimmed.split("#");
+    if (entityById.has(trimmed)) {
+      const entity = entityById.get(trimmed);
+      return { kind: "entity", targetId: entity.entityId, fileId: entity.fileId };
+    }
+    if (pathPart.includes("/")) {
+      const [modelPrefix, ...slugParts] = pathPart.split("/");
+      if (slugParts.length > 0) {
+        try {
+          const model = resolveModelDefinition(modelPrefix, models).name;
+          const slug = slugParts.join("/");
+          const target = entityByModelAndSlug.get(`${model}:${slug}`);
+          if (target) {
+            if (hashPart) {
+              const section = sectionByAnchor.get(`${target.fileId}#${hashPart}`);
+              if (section) {
+                return { kind: "section", targetId: section.id, fileId: target.fileId };
+              }
+            }
+            return { kind: "entity", targetId: target.entityId, fileId: target.fileId };
+          }
+        } catch {
+        }
+      }
+    }
+    if (sourceDocument && !pathPart.includes("/")) {
+      const sameModel = entityByModelAndSlug.get(`${sourceDocument.model}:${pathPart}`);
+      if (sameModel) {
+        return { kind: "entity", targetId: sameModel.entityId, fileId: sameModel.fileId };
+      }
+    }
+    if (sourceDocument && pathPart) {
+      const absolute = path.resolve(path.dirname(sourceDocument.path), pathPart);
+      const normalized = stripMarkdownExtension(absolute);
+      for (const [filePath, document] of fileByPath.entries()) {
+        if (stripMarkdownExtension(filePath) === normalized) {
+          if (hashPart) {
+            const section = sectionByAnchor.get(`${document.fileId}#${hashPart}`);
+            if (section) {
+              return { kind: "section", targetId: section.id, fileId: document.fileId };
+            }
+          }
+          return { kind: "file", targetId: document.fileId, fileId: document.fileId };
+        }
+      }
+    }
+    if (pathPart.startsWith("/")) {
+      const normalizedRelative = stripMarkdownExtension(pathPart.replace(/^\/+/u, ""));
+      const direct = fileByRelativePath.get(normalizedRelative);
+      if (direct) {
+        if (hashPart) {
+          const section = sectionByAnchor.get(`${direct.fileId}#${hashPart}`);
+          if (section) {
+            return { kind: "section", targetId: section.id, fileId: direct.fileId };
+          }
+        }
+        return { kind: "file", targetId: direct.fileId, fileId: direct.fileId };
+      }
+      for (const document of documents) {
+        const routeLike = `${document.model}/${document.slug}`.replace(/^knowledge\//u, "knowledge/");
+        if (routeLike === normalizedRelative || document.slug === normalizedRelative) {
+          return { kind: "file", targetId: document.fileId, fileId: document.fileId };
+        }
+      }
+    }
+    if (hashPart && sourceDocument) {
+      const section = sectionByAnchor.get(`${sourceDocument.fileId}#${hashPart}`);
+      if (section) {
+        return { kind: "section", targetId: section.id, fileId: sourceDocument.fileId };
+      }
+    }
+    return { kind: "unresolved" };
+  };
+  return {
+    entityById,
+    fileById,
+    fileByPath,
+    fileByRelativePath,
+    entityByModelAndSlug,
+    sectionById,
+    sectionByAnchor,
+    resolveReferenceString
+  };
+}
+export {
+  buildReferenceMaps,
+  catalogForDocument,
+  parseGraphDocument
+};

package/dist/graph/build/read-snapshot-file.d.ts

@@ -0,0 +1,16 @@
+import type { SdkModelDefinition, SdkModelRegistry } from '../../entrypoints/models/sdk-types.js';
+import { GraphBuildState } from './md-node.js';
+export declare function readSnapshotFile<T>(filePath: string): Promise<T | null>;
+export declare function loadGraphSnapshot(repoRoot: string, models: SdkModelRegistry): Promise<GraphBuildState | null>;
+export declare function saveGraphSnapshot(state: GraphBuildState): Promise<void>;
+export declare function hashFile(filePath: string): Promise<{
+    source: string;
+    hash: string;
+}>;
+export declare function contentDefinitions(models: SdkModelRegistry): (SdkModelDefinition & {
+    contentDir: string;
+})[];
+export declare function refreshGraphBuildState(repoRoot: string, models: SdkModelRegistry, request?: {
+    paths?: string[];
+}, priorState?: GraphBuildState | null): Promise<GraphBuildState>;
+export declare function clearGraphSnapshot(repoRoot: string): Promise<void>;

package/dist/graph/build/read-snapshot-file.js

@@ -0,0 +1,177 @@
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  GRAPH_SNAPSHOT_VERSION,
+  computeModelSignature,
+  emptyGraphMetrics,
+  emptyGraphValidation,
+  graphSnapshotRoot,
+  sha1
+} from "../schema.js";
+import { buildGraphFromDocuments } from "./build-graph-from-documents.js";
+import { walkMarkdownFiles } from "./md-node.js";
+import { catalogForDocument, parseGraphDocument } from "./parse-graph-document.js";
+async function readSnapshotFile(filePath) {
+  try {
+    return JSON.parse(await readFile(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function loadGraphSnapshot(repoRoot, models) {
+  const snapshotRoot = graphSnapshotRoot(repoRoot);
+  const graph = await readSnapshotFile(
+    path.join(snapshotRoot, "graph.json")
+  );
+  const catalog = await readSnapshotFile(path.join(snapshotRoot, "catalog.json"));
+  const metrics = await readSnapshotFile(path.join(snapshotRoot, "metrics.json"));
+  const delta = await readSnapshotFile(path.join(snapshotRoot, "deltas.json"));
+  const currentSignature = computeModelSignature(models);
+  if (!graph || graph.version !== GRAPH_SNAPSHOT_VERSION || graph.modelSignature !== currentSignature || !catalog) {
+    return null;
+  }
+  return {
+    modelSignature: graph.modelSignature,
+    documents: graph.documents,
+    nodes: graph.nodes,
+    edges: graph.edges,
+    catalog: catalog.catalog,
+    metrics: metrics ?? emptyGraphMetrics(),
+    validation: graph.validation ?? emptyGraphValidation(),
+    delta: delta ?? { added: [], modified: [], removed: [] },
+    snapshotRoot
+  };
+}
+async function saveGraphSnapshot(state) {
+  await mkdir(state.snapshotRoot, { recursive: true });
+  const graphPayload = {
+    version: GRAPH_SNAPSHOT_VERSION,
+    modelSignature: state.modelSignature,
+    documents: state.documents,
+    nodes: state.nodes,
+    edges: state.edges,
+    validation: state.validation
+  };
+  await Promise.all([
+    writeFile(path.join(state.snapshotRoot, "graph.json"), `${JSON.stringify(graphPayload, null, 2)}
+`, "utf8"),
+    writeFile(path.join(state.snapshotRoot, "catalog.json"), `${JSON.stringify({ catalog: state.catalog }, null, 2)}
+`, "utf8"),
+    writeFile(path.join(state.snapshotRoot, "metrics.json"), `${JSON.stringify(state.metrics, null, 2)}
+`, "utf8"),
+    writeFile(path.join(state.snapshotRoot, "deltas.json"), `${JSON.stringify(state.delta, null, 2)}
+`, "utf8"),
+    writeFile(
+      path.join(state.snapshotRoot, "indexes.json"),
+      `${JSON.stringify({ files: [], sections: [], entities: [] }, null, 2)}
+`,
+      "utf8"
+    )
+  ]);
+}
+async function hashFile(filePath) {
+  const source = await readFile(filePath, "utf8");
+  return {
+    source,
+    hash: sha1(source)
+  };
+}
+function contentDefinitions(models) {
+  return Object.values(models).filter((definition) => definition.storage === "content" && Boolean(definition.contentDir)).sort((left, right) => left.name.localeCompare(right.name));
+}
+async function refreshGraphBuildState(repoRoot, models, request, priorState) {
+  const snapshotRoot = graphSnapshotRoot(repoRoot);
+  const modelSignature = computeModelSignature(models);
+  const priorDocuments = new Map((priorState?.documents ?? []).map((document) => [document.fileId, document]));
+  const priorCatalog = new Map((priorState?.catalog ?? []).map((entry) => [path.resolve(entry.path), entry]));
+  const nextDocuments = new Map(priorDocuments);
+  const nextCatalog = new Map(priorCatalog);
+  const requestedPaths = request?.paths?.map((entry) => path.resolve(repoRoot, entry)).filter(Boolean);
+  const changed = { added: [], modified: [], removed: [] };
+  const trackedPaths = /* @__PURE__ */ new Set();
+  const definitions = contentDefinitions(models);
+  if (requestedPaths && requestedPaths.length > 0) {
+    for (const requestedPath of requestedPaths) {
+      const matchingDefinition = definitions.find((definition) => requestedPath.startsWith(path.resolve(definition.contentDir)));
+      if (!matchingDefinition) {
+        continue;
+      }
+      trackedPaths.add(requestedPath);
+      try {
+        const fileStats = await stat(requestedPath);
+        if (!fileStats.isFile()) continue;
+        const { source, hash } = await hashFile(requestedPath);
+        const parsed = parseGraphDocument(matchingDefinition, requestedPath, source);
+        const existing = priorCatalog.get(requestedPath);
+        nextDocuments.set(parsed.fileId, parsed);
+        nextCatalog.set(requestedPath, catalogForDocument(parsed, hash));
+        if (!existing) {
+          changed.added.push(parsed.fileId);
+        } else if (existing.hash !== hash) {
+          changed.modified.push(parsed.fileId);
+        }
+      } catch {
+        const existing = priorCatalog.get(requestedPath);
+        if (existing) {
+          changed.removed.push(existing.fileId);
+          nextCatalog.delete(requestedPath);
+          nextDocuments.delete(existing.fileId);
+        }
+      }
+    }
+  } else {
+    for (const definition of definitions) {
+      const files = await walkMarkdownFiles(definition.contentDir);
+      for (const filePath of files) {
+        const resolvedPath = path.resolve(filePath);
+        trackedPaths.add(resolvedPath);
+        const { source, hash } = await hashFile(resolvedPath);
+        const parsed = parseGraphDocument(definition, resolvedPath, source);
+        const existing = priorCatalog.get(resolvedPath);
+        nextDocuments.set(parsed.fileId, parsed);
+        nextCatalog.set(resolvedPath, catalogForDocument(parsed, hash));
+        if (!existing) {
+          changed.added.push(parsed.fileId);
+        } else if (existing.hash !== hash) {
+          changed.modified.push(parsed.fileId);
+        }
+      }
+    }
+    for (const [existingPath, existing] of priorCatalog.entries()) {
+      if (!trackedPaths.has(existingPath)) {
+        changed.removed.push(existing.fileId);
+        nextCatalog.delete(existingPath);
+        nextDocuments.delete(existing.fileId);
+      }
+    }
+  }
+  const built = buildGraphFromDocuments(
+    [...nextDocuments.values()].sort((left, right) => left.fileId.localeCompare(right.fileId)),
+    models,
+    priorState?.metrics,
+    changed
+  );
+  return {
+    modelSignature,
+    documents: [...nextDocuments.values()].sort((left, right) => left.fileId.localeCompare(right.fileId)),
+    nodes: built.nodes,
+    edges: built.edges,
+    catalog: [...nextCatalog.values()].sort((left, right) => left.fileId.localeCompare(right.fileId)),
+    metrics: built.metrics,
+    validation: built.validation,
+    delta: changed,
+    snapshotRoot
+  };
+}
+async function clearGraphSnapshot(repoRoot) {
+  await rm(graphSnapshotRoot(repoRoot), { recursive: true, force: true });
+}
+export {
+  clearGraphSnapshot,
+  contentDefinitions,
+  hashFile,
+  loadGraphSnapshot,
+  readSnapshotFile,
+  refreshGraphBuildState,
+  saveGraphSnapshot
+};

package/dist/graph/build.d.ts

@@ -1,19 +1,4 @@
-import type { SdkGraphEdge, SdkGraphNode, SdkModelRegistry } from '../sdk-types.js';
-import { type GraphDelta, type GraphFileCatalogEntry, type GraphMetrics, type GraphValidation, type ParsedGraphDocument } from './schema.js';
-export type GraphBuildState = {
-    modelSignature: string;
-    documents: ParsedGraphDocument[];
-    nodes: SdkGraphNode[];
-    edges: SdkGraphEdge[];
-    catalog: GraphFileCatalogEntry[];
-    metrics: GraphMetrics;
-    validation: GraphValidation;
-    delta: GraphDelta;
-    snapshotRoot: string;
-};
-export declare function loadGraphSnapshot(repoRoot: string, models: SdkModelRegistry): Promise<GraphBuildState | null>;
-export declare function saveGraphSnapshot(state: GraphBuildState): Promise<void>;
-export declare function refreshGraphBuildState(repoRoot: string, models: SdkModelRegistry, request?: {
-    paths?: string[];
-}, priorState?: GraphBuildState | null): Promise<GraphBuildState>;
-export declare function clearGraphSnapshot(repoRoot: string): Promise<void>;
+export * from './build/build-graph-from-documents.js';
+export * from './build/md-node.js';
+export * from './build/parse-graph-document.js';
+export * from './build/read-snapshot-file.js';