filegrc 0.3.4 → 0.4.0

package/src/server.js

@@ -4,22 +4,25 @@ import { extname, resolve } from "node:path";
 import { getResourceDefinition } from "../model/index.js";
 import { prepareAuditWorkspace } from "./audit-preparation.js";
 import { generateEvidencePacket, prepareEvidencePacket } from "./evidence-packet.js";
-import { ensureEvidenceTestDrafts } from "./evidence-tests.js";
 import { FAVICON_PNG, LOGO_MARK_PNG } from "./favicon.js";
 import { createResource, deleteResource, updateContent, updateResource } from "./files.js";
 import {
+  BROWSER_VALIDATION,
   commitAndPushWorkspace,
   getBrowserRepositoryState,
   getFileHistory,
+  getGitSummary,
   pullWorkspace,
   pushWorkspace,
   retryBrowserSync,
   runBrowserMutation
 } from "./git.js";
+import { normalizeResourceMutation, serializeWorkspaceMutation } from "./mutation.js";
 import { completeObligationOccurrence, createObligationEvent, planObligations } from "./obligations.js";
 import { isWithin, relativeToWorkspace, resolveWorkspacePath } from "./paths.js";
-import { createAppState } from "./state.js";
+import { createAppState, createResourceDetail } from "./state.js";
 import { setupWorkspace } from "./setup.js";
+import { collectTimings, measureTiming, timingEnabled } from "./timing.js";
 import { loadWorkspace } from "./workspace.js";
 import { APP_SCRIPT, APP_STYLES, renderIndex } from "./web.js";
 
@@ -34,8 +37,17 @@ export function createFilegrcServer(input = process.cwd(), options = {}) {
         return json(response, 403, { error: "Cross-origin writes are not allowed." });
       }
       if (request.method === "GET" && url.pathname === "/api/state") {
+        if (timingEnabled()) {
+          const { result, timings } = await collectTimings(() => measureTiming("state", () => createAppState(input, {
+            allowNonAuthoritativeWrites: options.allowNonAuthoritativeWrites,
+            includeDetails: false
+          })));
+          console.error(`[filegrc timing] ${JSON.stringify({ operation: "state", ...timings })}`);
+          return json(response, 200, result);
+        }
         return json(response, 200, await createAppState(input, {
-          allowNonAuthoritativeWrites: options.allowNonAuthoritativeWrites
+          allowNonAuthoritativeWrites: options.allowNonAuthoritativeWrites,
+          includeDetails: false
         }));
       }
       if (request.method === "GET" && url.pathname === "/api/history") {
@@ -50,7 +62,8 @@ export function createFilegrcServer(input = process.cwd(), options = {}) {
           from: url.searchParams.get("from") || undefined,
           through: url.searchParams.get("through") || undefined,
           now: url.searchParams.get("now") || undefined,
-          includeComplete: url.searchParams.get("includeComplete") === "true"
+          includeComplete: url.searchParams.get("includeComplete") === "true",
+          model: loaded.model
         }));
       }
       if (request.method === "POST" && url.pathname === "/api/obligation-events") {
@@ -68,7 +81,7 @@ export function createFilegrcServer(input = process.cwd(), options = {}) {
           obligationId: payload.obligationId,
           record: payload.record,
           content: payload.content,
-          expectedRevision: payload.revision
+          expectedRevision: requireRevision(payload.revision, `obligation/${payload.obligationId}`)
         }));
         return json(response, 201, result);
       }
@@ -102,49 +115,66 @@ export function createFilegrcServer(input = process.cwd(), options = {}) {
           message: () => `Prepare audit: ${payload.auditId || "engagement"}`
         }, () => prepareAuditWorkspace(input, payload)));
       }
-      if (request.method === "POST" && url.pathname === "/api/evidence-test-drafts") {
-        return json(response, 201, await browserMutation(input, options, {
-          message: "Create evidence collection test drafts"
-        }, () => ensureEvidenceTestDrafts(input)));
-      }
       if (request.method === "POST" && url.pathname === "/api/setup") {
         const payload = await readJson(request);
-        return json(response, 200, await browserMutation(input, options, {
-          message: (result) => `${payload.draft === true ? "Save onboarding draft" : "Complete onboarding"} for ${result.workspace.organizationName}`
-        }, () => setupWorkspace(input, payload)));
+        const completeSetup = async () => {
+          return browserMutation(input, options, {
+            message: (setupResult) => `${payload.draft === true ? "Save onboarding draft" : "Complete onboarding"} for ${setupResult.workspace.organizationName}`
+          }, () => setupWorkspace(input, payload));
+        };
+        return json(response, 200, await completeSetup());
       }
       if (request.method === "POST" && url.pathname === "/api/resources") {
-        const payload = await readJson(request);
-        const record = payload.record ?? payload;
+        const payload = normalizeResourceMutation(await readJson(request));
+        const { record } = payload;
         const result = await browserMutation(input, options, {
           message: () => `Create ${resourceTypeLabel(record.type)}: ${record.title || record.id}`
-        }, () => createResource(input, record, { content: payload.record ? payload.content : undefined }));
-        return json(response, 201, { record: result.record, synchronization: result.synchronization });
+        }, () => createResource(input, record, { content: payload.content }));
+        return json(response, 201, { record: result.record, synchronization: result.synchronization, state: result.state });
       }
       if (request.method === "POST" && url.pathname === "/api/commit") {
         await requireManualBrowserGit(input, options);
         const payload = await readJson(request);
-        return json(response, 201, await commitAndPushWorkspace(input, payload.message));
+        return json(response, 201, await manualGitResultWithState(input, options, () => commitAndPushWorkspace(input, payload.message)));
       }
       if (request.method === "POST" && url.pathname === "/api/git/pull") {
         await requireManualBrowserGit(input, options);
-        return json(response, 200, await pullWorkspace(input));
+        return json(response, 200, await manualGitResultWithState(input, options, () => pullWorkspace(input)));
       }
       if (request.method === "POST" && url.pathname === "/api/git/push") {
         await requireManualBrowserGit(input, options);
-        return json(response, 200, await pushWorkspace(input));
+        return json(response, 200, await manualGitResultWithState(input, options, () => pushWorkspace(input)));
       }
       if (request.method === "POST" && url.pathname === "/api/git/retry-sync") {
-        return json(response, 200, await retryBrowserSync(input, {
+        const result = await retryBrowserSync(input, {
           allowNonAuthoritativeWrites: options.allowNonAuthoritativeWrites
-        }));
+        });
+        const state = await createAppState(input, {
+          allowNonAuthoritativeWrites: options.allowNonAuthoritativeWrites,
+          includeDetails: false
+        });
+        return json(response, 200, { ...result, state });
+      }
+      if (request.method === "GET" && url.pathname === "/api/git/sync-status") {
+        const repository = await getBrowserRepositoryState(input, {
+          allowNonAuthoritativeWrites: options.allowNonAuthoritativeWrites
+        });
+        const git = getGitSummary(input);
+        delete git.root;
+        return json(response, 200, {
+          repository,
+          git,
+          readOnly: repository.mode === "trunk" && !repository.writesAllowed
+        });
       }
       if (request.method === "PUT" && url.pathname === "/api/content") {
         const payload = await readJson(request);
         const result = await browserMutation(input, options, {
           message: () => `Update content: ${payload.path}`
-        }, () => updateContent(input, payload.path, payload.source, { expectedRevision: payload.revision }));
-        return json(response, 200, { path: result.dataRelativePath, synchronization: result.synchronization });
+        }, () => updateContent(input, payload.path, payload.source, {
+          expectedRevision: requireRevision(payload.revision, `content/${payload.path}`)
+        }));
+        return json(response, 200, { path: result.dataRelativePath, synchronization: result.synchronization, state: result.state });
       }
       const match = /^\/api\/resource\/([^/]+)\/([^/]+)$/.exec(url.pathname);
       if (match) {
@@ -152,32 +182,34 @@ export function createFilegrcServer(input = process.cwd(), options = {}) {
         const id = decodeURIComponent(match[2]);
         if (!safeSegment(type) || !safeSegment(id)) return json(response, 400, { error: "Unsafe resource identifier." });
         if (request.method === "GET") {
-          const state = await createAppState(input);
-          const entry = state.resources.find(({ record }) => record.type === type && record.id === id);
+          const entry = await createResourceDetail(input, type, id);
           return entry ? json(response, 200, entry) : json(response, 404, { error: "Resource not found." });
         }
         if (request.method === "PUT") {
-          const payload = await readJson(request);
-          const record = payload.record ?? payload;
+          const payload = normalizeResourceMutation(await readJson(request), { requireRevision: true });
+          const { record } = payload;
           const result = await browserMutation(input, options, {
             message: () => `Update ${resourceTypeLabel(type)}: ${record.title || id}`
           }, () => updateResource(input, type, id, record, {
-            content: payload.record ? payload.content : undefined,
+            content: payload.content,
             expectedRevision: payload.revision,
-            expectedContentRevisions: payload.contentRevisions
+            expectedContentRevisions: payload.contentRevisions,
+            requireExpectedContentRevisions: true
           }));
-          return json(response, 200, { record: result.record, synchronization: result.synchronization });
+          return json(response, 200, { record: result.record, synchronization: result.synchronization, state: result.state });
         }
         if (request.method === "DELETE") {
+          const revision = requireRevision(url.searchParams.get("revision"), `${type}/${id}`);
           const result = await browserMutation(input, options, {
             message: () => `Delete ${resourceTypeLabel(type)}: ${id}`
-          }, () => deleteResource(input, type, id, { expectedRevision: url.searchParams.get("revision") }));
+          }, () => deleteResource(input, type, id, { expectedRevision: revision }));
           return json(response, 200, {
             deleted: true,
             type,
             id,
             deletedContent: result.deletedContent,
-            synchronization: result.synchronization
+            synchronization: result.synchronization,
+            state: result.state
           });
         }
       }
@@ -232,7 +264,8 @@ export async function serveWorkspace(input = process.cwd(), options = {}) {
   getResourceDefinition(loaded.model, "workspace");
   const server = createFilegrcServer(loaded.root, {
     allowedHosts: [host],
-    allowNonAuthoritativeWrites: options.allowNonAuthoritativeWrites === true
+    allowNonAuthoritativeWrites: options.allowNonAuthoritativeWrites === true,
+    backgroundPushDelayMs: options.backgroundPushDelayMs
   });
   await new Promise((resolve, reject) => {
     server.once("error", reject);
@@ -247,10 +280,32 @@ export async function serveWorkspace(input = process.cwd(), options = {}) {
 }
 
 function browserMutation(input, options, mutationOptions, task) {
-  return runBrowserMutation(input, {
-    ...mutationOptions,
-    allowNonAuthoritativeWrites: options.allowNonAuthoritativeWrites === true
-  }, task);
+  const run = () => serializeWorkspaceMutation(input, async (root) => {
+    const result = await runBrowserMutation(root, {
+      ...mutationOptions,
+      allowNonAuthoritativeWrites: options.allowNonAuthoritativeWrites === true,
+      backgroundPushDelayMs: options.backgroundPushDelayMs
+    }, task);
+    const state = await measureTiming("state", () => createAppState(root, {
+      allowNonAuthoritativeWrites: options.allowNonAuthoritativeWrites,
+      includeDetails: false,
+      validationProof: result?.[BROWSER_VALIDATION]
+    }));
+    if (result?.synchronization?.status === "syncing" && state.repository.status !== "syncing") {
+      result.synchronization = {
+        ...result.synchronization,
+        status: state.repository.status === "synced" ? "synced" : "not-synced",
+        synchronizedAt: state.repository.lastSuccessfulSynchronization ?? null,
+        pushError: state.repository.backgroundSyncError ?? null
+      };
+    }
+    return { ...result, state };
+  });
+  if (!timingEnabled()) return run();
+  return collectTimings(run).then(({ result, timings }) => {
+    console.error(`[filegrc timing] ${JSON.stringify({ operation: "browser-mutation", ...timings })}`);
+    return result;
+  });
 }
 
 async function requireManualBrowserGit(input, options) {
@@ -262,6 +317,15 @@ async function requireManualBrowserGit(input, options) {
   }
 }
 
+async function manualGitResultWithState(input, options, task) {
+  const result = await task();
+  const state = await createAppState(input, {
+    allowNonAuthoritativeWrites: options.allowNonAuthoritativeWrites,
+    includeDetails: false
+  });
+  return { ...result, state };
+}
+
 function resourceTypeLabel(value) {
   return String(value || "record").replaceAll("-", " ");
 }
@@ -319,6 +383,13 @@ function safeSegment(value) {
   return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
 }
 
+function requireRevision(value, target) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`A revision is required when changing ${target}. Reload the resource and try again.`);
+  }
+  return value;
+}
+
 function sameOrigin(request) {
   const origin = request.headers.origin;
   if (!origin) return true;
@@ -364,7 +435,7 @@ function statusFor(error) {
   if (/exceeds 2 MB/i.test(error.message)) return 413;
   if (/changed after you opened|source changed|revision changed/i.test(error.message)) return 409;
   if (/already exists|target file already exists/i.test(error.message)) return 409;
-  if (/Git could not|upstream branch|multiple remotes|no Git remote|configured repository remote|safe Git name|check out a branch|before trying to (?:pull|push)|authoritative branch|not synchronized|not synced|diverged|waiting to be pushed|Retry sync|outside this FileGRC workspace|worktree has uncommitted changes|development write override|browser commit, pull, and push/i.test(error.message)) return 409;
+  if (/Git could not|upstream branch|multiple remotes|no Git remote|configured repository remote|safe Git name|check out a branch|before trying to (?:pull|push)|authoritative branch|not synchronized|not synced|diverged|waiting to be pushed|Retry sync|background push|outside this FileGRC workspace|worktree has uncommitted changes|development write override|browser commit, pull, and push/i.test(error.message)) return 409;
   if (/not found|ENOENT/i.test(error.message)) return 404;
   if (/invalid|required|unsafe|match|workspace|singleton|commit message|no changes|git history|git user|unknown resource type|must use|must be|content path|data path|path leaves|valid .*date|not found|no active obligations|end date|through date|already exists|EEXIST/i.test(error.message)) return 400;
   return 500;

package/src/setup.js

@@ -1,4 +1,4 @@
-import { createResource, updateResource } from "./files.js";
+import { applyResourceBatch } from "./files.js";
 import { createResourceId } from "./id.js";
 import { loadWorkspace } from "./workspace.js";
 
@@ -10,10 +10,19 @@ export async function setupWorkspace(input = process.cwd(), payload = {}) {
   const setup = normalizeSetupPayload(payload);
   validateSetup(loaded, setup);
   const plan = buildSetupRecords(loaded, setup);
-
-  await upsertResource(loaded.root, plan.existingSystem, plan.system);
-  await updateResource(loaded.root, "workspace", plan.workspace.id, plan.workspace);
-  if (plan.renderer) await updateResource(loaded.root, plan.renderer.type, plan.renderer.id, plan.renderer);
+  const updates = [
+    ...(plan.existingSystem ? [plan.system] : []),
+    plan.workspace,
+    ...(plan.renderer ? [plan.renderer] : [])
+  ];
+  const revisionById = new Map(loaded.entries.map((entry) => [entry.record.id, entry.revision]));
+
+  await applyResourceBatch(loaded.root, {
+    create: plan.existingSystem ? [] : [plan.system],
+    update: updates,
+    expectedRevisions: Object.fromEntries(updates.map((record) => [record.id, revisionById.get(record.id)])),
+    validateWholeWorkspace: true
+  });
 
   return {
     draft: setup.draft,
@@ -21,7 +30,6 @@ export async function setupWorkspace(input = process.cwd(), payload = {}) {
     workspace: plan.workspace,
     renderer: plan.renderer,
     linkedControlIds: [],
-    evidenceTestDraftIds: [],
     onboardingComplete: !setup.draft
   };
 }
@@ -39,8 +47,7 @@ export async function planWorkspaceSetup(input = process.cwd(), payload = {}) {
       system: plan.existingSystem ? "update" : "create",
       workspace: "update",
       renderer: plan.renderer ? "update" : "unchanged",
-      controls: 0,
-      evidenceDrafts: 0
+      controls: 0
     },
     system: setupSystemSummary(plan.system),
     target: setupTargetSummary(plan.workspace),
@@ -57,8 +64,7 @@ export function summarizeSetupResult(result) {
     changes: {
       system: "saved",
       workspace: "updated",
-      controls: result.linkedControlIds?.length || 0,
-      evidenceDrafts: result.evidenceTestDraftIds?.length || 0
+      controls: result.linkedControlIds?.length || 0
     },
     system: setupSystemSummary(result.system),
     target: setupTargetSummary(result.workspace),
@@ -77,7 +83,7 @@ export function normalizeSetupPayload(payload = {}) {
     boundary: cleanMultilineText(payload.boundary ?? payload.scope, "boundary"),
     ownerId: cleanText(payload.ownerId ?? payload.owner, "ownerId"),
     criticality: cleanText(payload.criticality, "criticality"),
-    dataClassification: cleanText(payload.dataClassification ?? payload.classification, "dataClassification"),
+    classificationId: cleanText(payload.classificationId, "classificationId"),
     internetExposed: booleanValue(payload.internetExposed, "internetExposed"),
     programGoal: cleanText(payload.programGoal ?? "none", "programGoal"),
     draft,
@@ -91,7 +97,7 @@ function validateSetup(loaded, setup) {
     ["boundary", setup.boundary],
     ["ownerId", setup.ownerId],
     ["criticality", setup.criticality],
-    ["dataClassification", setup.dataClassification]
+    ["classificationId", setup.classificationId]
   ]) {
     if (!value) throw new Error(`Setup field "${name}" is required.`);
   }
@@ -113,23 +119,24 @@ function validateSetup(loaded, setup) {
     }
   }
   const classifications = Object.keys(loaded.workspace.classificationDefinitions || {});
-  if (classifications.length && !classifications.includes(setup.dataClassification)) {
-    throw new Error(`dataClassification must be one of ${classifications.join(", ")}.`);
+  if (classifications.length && !classifications.includes(setup.classificationId)) {
+    throw new Error(`classificationId must be one of ${classifications.join(", ")}.`);
   }
 }
 
-function findSetupSystem(resources, setup) {
+function findSetupSystem(resources, workspace, setup) {
+  const scopedSystemIds = new Set(workspace.systemIds || []);
   return (setup.systemId && resources.find(({ type, id }) => type === "system" && id === setup.systemId))
-    || resources.find(({ type, title, inScope, status }) => (
+    || resources.find(({ type, id, title, status }) => (
       type === "system"
-      && inScope === true
+      && scopedSystemIds.has(id)
       && status !== "retired"
       && title.trim().toLowerCase() === setup.serviceName.toLowerCase()
     ));
 }
 
 function buildSetupRecords(loaded, setup) {
-  const existingSystem = findSetupSystem(loaded.resources, setup);
+  const existingSystem = findSetupSystem(loaded.resources, loaded.workspace, setup);
   const systemId = existingSystem?.id || createResourceId(
     "system",
     setup.serviceName,
@@ -137,7 +144,6 @@ function buildSetupRecords(loaded, setup) {
   );
   const system = {
     ...(existingSystem || {}),
-    schemaVersion: 1,
     id: systemId,
     type: "system",
     title: setup.serviceName,
@@ -150,9 +156,8 @@ function buildSetupRecords(loaded, setup) {
     ownerIds: [setup.ownerId],
     description: setup.boundary,
     systemKind: existingSystem?.systemKind || "service",
-    dataClassification: setup.dataClassification,
-    internetExposed: setup.internetExposed,
-    inScope: true
+    classificationId: setup.classificationId,
+    internetExposed: setup.internetExposed
   };
   const existingWorkspace = loaded.resources.find(({ type }) => type === "workspace");
   if (!existingWorkspace) throw new Error("The workspace settings record was not found.");
@@ -166,12 +171,6 @@ function buildSetupRecords(loaded, setup) {
   return { existingSystem, system, workspace, renderer };
 }
 
-async function upsertResource(root, existing, record) {
-  return existing
-    ? updateResource(root, record.type, record.id, record)
-    : createResource(root, record);
-}
-
 function assuranceGoalFromSetup(goal) {
   if (goal === "type-1") return "soc-2-type-1";
   if (goal === "type-2") return "soc-2-type-2";

package/src/state.js

@@ -8,36 +8,38 @@ import { resolveDataPath } from "./paths.js";
 import { assessProgramReadiness } from "./program-readiness.js";
 import { markdownEntries } from "./resource-markdown.js";
 import { currentCalendarDate } from "./time.js";
-import { validateWorkspace } from "./validate.js";
+import { serializeWorkspaceMutation } from "./mutation.js";
+import { fingerprintWorkspace, validateWorkspace } from "./validate.js";
+
+const renderedMarkdownCache = new Map();
+const MAX_RENDERED_MARKDOWN_CACHE_ENTRIES = 1_000;
 
 export async function createAppState(input = process.cwd(), options = {}) {
-  const validation = await validateWorkspace(input);
+  return serializeWorkspaceMutation(input, (root) => createAppStateUnlocked(root, options));
+}
+
+async function createAppStateUnlocked(input, options) {
+  let validation;
+  if (options.validationProof) {
+    const current = await fingerprintWorkspace(input);
+    validation = current.fingerprint === options.validationProof.fingerprint
+      ? { ...options.validationProof.validation, loaded: current.loaded }
+      : await validateWorkspace(current.loaded);
+  } else {
+    validation = await validateWorkspace(input);
+  }
   const { loaded } = validation;
   const entries = [];
-  const relativePaths = loaded.entries.map((entry) => `data/${entry.relativePath}`);
-  const histories = getWorkspaceHistories(loaded.root, relativePaths, 12);
+  const includeDetails = options.includeDetails !== false;
+  const histories = includeDetails
+    ? getWorkspaceHistories(loaded.root, loaded.entries.map((entry) => `data/${entry.relativePath}`), 12)
+    : new Map();
 
   for (const entry of loaded.entries) {
-    const record = structuredClone(entry.record);
-    const content = {};
-    if (loaded.model.resources[record.type]) {
-      for (const item of markdownEntries(loaded.model, record)) {
-        try {
-          const path = resolveDataPath(loaded.root, item.path);
-          const source = await readFile(path, "utf8");
-          content[item.name] = { source, html: renderMarkdown(source), path: item.path, revision: contentRevision(source) };
-        } catch {
-          // Validation reports missing required Markdown.
-        }
-      }
-    }
-    entries.push({
-      record,
-      relativePath: `data/${entry.relativePath}`,
-      revision: contentRevision(entry.source),
-      content,
+    entries.push(await createStateEntry(loaded, entry, {
+      includeDetails,
       history: histories.get(`data/${entry.relativePath}`) ?? []
-    });
+    }));
   }
 
   const git = getGitSummary(loaded.root);
@@ -47,7 +49,6 @@ export async function createAppState(input = process.cwd(), options = {}) {
     allowNonAuthoritativeWrites: options.allowNonAuthoritativeWrites
   });
   const workspace = loaded.workspace ?? {
-    schemaVersion: 1,
     dataModelVersion: loaded.model.modelVersion,
     id: "workspace",
     type: "workspace",
@@ -74,6 +75,7 @@ export async function createAppState(input = process.cwd(), options = {}) {
   ));
   return {
     generatedAt,
+    asOf,
     readOnly: Boolean(options.readOnly || (repository.mode === "trunk" && !repository.writesAllowed)),
     repository,
     workspace,
@@ -84,13 +86,72 @@ export async function createAppState(input = process.cwd(), options = {}) {
       counts: validation.counts,
       diagnostics: validation.diagnostics
     },
-    obligations: planObligations(entries, { asOf, now: options.now ?? generatedAt }),
+    obligations: planObligations(entries, { asOf, now: options.now ?? generatedAt, model: loaded.model }),
     programReadiness,
     auditPreparations,
     git
   };
 }
 
+export async function createResourceDetail(input, type, id) {
+  return serializeWorkspaceMutation(input, async (root) => {
+    const validation = await validateWorkspace(root);
+    const entry = validation.loaded.entries.find(({ record }) => record.type === type && record.id === id);
+    if (!entry) return null;
+    const relativePath = `data/${entry.relativePath}`;
+    const histories = getWorkspaceHistories(validation.loaded.root, [relativePath], 12);
+    return createStateEntry(validation.loaded, entry, {
+      includeDetails: true,
+      history: histories.get(relativePath) ?? []
+    });
+  });
+}
+
+async function createStateEntry(loaded, entry, options) {
+  const record = structuredClone(entry.record);
+  const content = {};
+  if (loaded.model.resources[record.type]) {
+    for (const item of markdownEntries(loaded.model, record)) {
+      try {
+        const path = resolveDataPath(loaded.root, item.path);
+        const source = await readFile(path, "utf8");
+        content[item.name] = {
+          source,
+          ...(options.includeDetails ? { html: renderMarkdownCached(source) } : {}),
+          path: item.path,
+          revision: contentRevision(source)
+        };
+      } catch {
+        // Validation reports missing required Markdown.
+      }
+    }
+  }
+  return {
+    record,
+    relativePath: `data/${entry.relativePath}`,
+    revision: contentRevision(entry.source),
+    content,
+    history: options.includeDetails ? options.history : undefined,
+    detailsLoaded: options.includeDetails
+  };
+}
+
+function renderMarkdownCached(source) {
+  const revision = contentRevision(source);
+  const cached = renderedMarkdownCache.get(revision);
+  if (cached !== undefined) {
+    renderedMarkdownCache.delete(revision);
+    renderedMarkdownCache.set(revision, cached);
+    return cached;
+  }
+  const html = renderMarkdown(source);
+  renderedMarkdownCache.set(revision, html);
+  if (renderedMarkdownCache.size > MAX_RENDERED_MARKDOWN_CACHE_ENTRIES) {
+    renderedMarkdownCache.delete(renderedMarkdownCache.keys().next().value);
+  }
+  return html;
+}
+
 function contentRevision(source) {
   return createHash("sha256").update(source).digest("hex");
 }

package/src/timing.js

@@ -0,0 +1,41 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { performance } from "node:perf_hooks";
+
+const timingContext = new AsyncLocalStorage();
+
+export async function collectTimings(task) {
+  const timings = new Map();
+  const result = await timingContext.run(timings, task);
+  return { result, timings: Object.fromEntries(timings) };
+}
+
+export async function measureTiming(name, task) {
+  const started = performance.now();
+  try {
+    return await task();
+  } finally {
+    recordTiming(name, performance.now() - started);
+  }
+}
+
+export function measureTimingSync(name, task) {
+  const started = performance.now();
+  try {
+    return task();
+  } finally {
+    recordTiming(name, performance.now() - started);
+  }
+}
+
+export function recordTiming(name, durationMs) {
+  const timings = timingContext.getStore();
+  if (!timings) return;
+  const current = timings.get(name) ?? { count: 0, durationMs: 0 };
+  current.count += 1;
+  current.durationMs += durationMs;
+  timings.set(name, current);
+}
+
+export function timingEnabled() {
+  return process.env.FILEGRC_TIMING === "1";
+}