filegrc 0.1.0

package/src/git.js

@@ -0,0 +1,289 @@
+import { execFileSync } from "node:child_process";
+import { serializeWorkspaceMutation } from "./mutation.js";
+import { resolveWorkspaceRoot } from "./paths.js";
+import { validateWorkspace } from "./validate.js";
+
+export function getGitSummary(input = process.cwd()) {
+  const root = resolveWorkspaceRoot(input);
+  try {
+    const topLevel = git(root, ["rev-parse", "--show-toplevel"]);
+    const status = git(root, ["status", "--porcelain=v1", "--", "."]);
+    const commit = tryGit(root, ["rev-parse", "HEAD"]) || null;
+    const branch = tryGit(root, ["symbolic-ref", "--short", "HEAD"]) || null;
+    const upstream = branch ? tryGit(root, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"]) || null : null;
+    const remotes = lines(tryGit(root, ["remote"]));
+    const last = commit ? parseLogLine(tryGit(root, ["log", "-1", "--format=%H%x1f%aI%x1f%an%x1f%s"])) : null;
+    return {
+      available: true,
+      root: topLevel,
+      commit,
+      shortCommit: commit?.slice(0, 8) ?? "no commits",
+      branch,
+      upstream,
+      remotes,
+      clean: status === "",
+      changes: status ? status.split("\n") : [],
+      lastCommit: last
+    };
+  } catch (error) {
+    return {
+      available: false,
+      clean: null,
+      changes: [],
+      message: "Git history is unavailable. Commit the workspace to enable audit metadata."
+    };
+  }
+}
+
+export function getFileHistory(input, relativePath, limit = 50) {
+  const root = resolveWorkspaceRoot(input);
+  try {
+    const output = git(root, [
+      "log",
+      "--follow",
+      `--max-count=${Math.max(1, Math.min(Number(limit) || 50, 200))}`,
+      "--format=%H%x1f%aI%x1f%an%x1f%s",
+      "--",
+      relativePath
+    ]);
+    if (!output) return [];
+    return output.split("\n").map(parseLogLine);
+  } catch {
+    return [];
+  }
+}
+
+export function getWorkspaceHistories(input, relativePaths, limitPerFile = 12) {
+  const root = resolveWorkspaceRoot(input);
+  const wanted = new Set(relativePaths);
+  const histories = new Map([...wanted].map((path) => [path, []]));
+  if (!wanted.size) return histories;
+  try {
+    const output = git(root, ["log", "--relative", "--format=%x1e%H%x1f%aI%x1f%an%x1f%s", "--name-only", "--", "data"]);
+    for (const block of output.split("\x1e")) {
+      const lines = block.trim().split("\n").filter(Boolean);
+      if (lines.length < 2) continue;
+      const commit = parseLogLine(lines[0]);
+      for (const path of lines.slice(1)) {
+        const history = histories.get(path);
+        if (history && history.length < limitPerFile) history.push(commit);
+      }
+    }
+  } catch {
+    // An uncommitted workspace has no history yet.
+  }
+  return histories;
+}
+
+export function getFileAtRevision(input, revision, relativePath) {
+  const root = resolveWorkspaceRoot(input);
+  if (!/^[a-f0-9]{40}$/i.test(String(revision)) || typeof relativePath !== "string" || !relativePath.startsWith("data/")) {
+    throw new Error("Historical file exports require a Git commit and a data/ path.");
+  }
+  try {
+    return execFileSync("git", ["show", `${revision}:${relativePath}`], {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 10_000,
+      maxBuffer: 20_000_000
+    });
+  } catch {
+    return null;
+  }
+}
+
+export function hasGitRevision(input, revision) {
+  if (!/^[a-f0-9]{40}$/i.test(String(revision))) return false;
+  const root = resolveWorkspaceRoot(input);
+  try {
+    git(root, ["cat-file", "-e", `${revision}^{commit}`]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function commitWorkspace(input, message) {
+  return serializeWorkspaceMutation(input, (root) => commitWorkspaceUnlocked(root, message));
+}
+
+export async function commitAndPushWorkspace(input, message) {
+  return serializeWorkspaceMutation(input, (root) => commitAndPushWorkspaceUnlocked(root, message));
+}
+
+export async function pullWorkspace(input = process.cwd()) {
+  return serializeWorkspaceMutation(input, pullWorkspaceUnlocked);
+}
+
+export async function pushWorkspace(input = process.cwd()) {
+  return serializeWorkspaceMutation(input, pushWorkspaceUnlocked);
+}
+
+async function commitWorkspaceUnlocked(root, message) {
+  const subject = String(message ?? "").trim();
+  if (!subject || subject.length > 200 || /[\u0000-\u001f\u007f]/.test(subject)) {
+    throw new Error("Commit messages must be one line from 1 through 200 characters.");
+  }
+  const validation = await validateWorkspace(root);
+  if (!validation.ok) {
+    throw new Error(`The workspace has ${validation.counts.errors} validation ${validation.counts.errors === 1 ? "error" : "errors"}. Fix them before committing.`);
+  }
+  const before = getGitSummary(root);
+  if (!before.available) throw new Error("Git history is unavailable for this workspace.");
+  if (before.clean) throw new Error("The workspace has no changes to commit.");
+  if (!tryGit(root, ["config", "user.name"]) || !tryGit(root, ["config", "user.email"])) {
+    throw new Error("Configure git user.name and user.email before committing.");
+  }
+  gitForWrite(root, ["add", "--all", "--", "."]);
+  gitForWrite(root, ["commit", "-m", subject, "--", "."]);
+  const after = getGitSummary(root);
+  return {
+    commit: after.commit,
+    shortCommit: after.shortCommit,
+    subject: after.lastCommit?.subject || subject
+  };
+}
+
+async function commitAndPushWorkspaceUnlocked(root, message) {
+  const before = getGitSummary(root);
+  const committed = await commitWorkspaceUnlocked(root, message);
+  if (!before.upstream && !before.remotes?.length) {
+    return {
+      ...committed,
+      pushed: false,
+      pushSkipped: true
+    };
+  }
+  try {
+    const pushed = await pushWorkspaceUnlocked(root);
+    return {
+      ...committed,
+      pushed: true,
+      pushSkipped: false,
+      upstream: pushed.upstream
+    };
+  } catch (error) {
+    return {
+      ...committed,
+      pushed: false,
+      pushSkipped: false,
+      pushError: error.message
+    };
+  }
+}
+
+async function pullWorkspaceUnlocked(root) {
+  const before = syncReadySummary(root, "pull");
+  if (!before.upstream) {
+    throw new Error("This branch has no upstream branch. Push it first or configure an upstream with Git.");
+  }
+  try {
+    gitForWrite(root, ["pull", "--rebase", "--no-autostash"], "pull with rebase");
+  } catch (error) {
+    tryGitForWrite(root, ["rebase", "--abort"]);
+    throw error;
+  }
+  const after = getGitSummary(root);
+  return {
+    updated: before.commit !== after.commit,
+    commit: after.commit,
+    shortCommit: after.shortCommit,
+    branch: after.branch,
+    upstream: after.upstream
+  };
+}
+
+async function pushWorkspaceUnlocked(root) {
+  const before = syncReadySummary(root, "push");
+  const validation = await validateWorkspace(root);
+  if (!validation.ok) {
+    throw new Error(`The workspace has ${validation.counts.errors} validation ${validation.counts.errors === 1 ? "error" : "errors"}. Fix them before pushing.`);
+  }
+  if (before.upstream) {
+    gitForWrite(root, ["push"], "push");
+  } else {
+    const remote = before.remotes.includes("origin")
+      ? "origin"
+      : before.remotes.length === 1
+        ? before.remotes[0]
+        : null;
+    if (!remote) {
+      throw new Error(before.remotes.length
+        ? "This branch has no upstream and the repository has multiple remotes. Configure an upstream with Git."
+        : "This repository has no Git remote. Add one before pushing.");
+    }
+    gitForWrite(root, ["push", "--set-upstream", "--", remote, "HEAD"], "push");
+  }
+  const after = getGitSummary(root);
+  return {
+    commit: after.commit,
+    shortCommit: after.shortCommit,
+    branch: after.branch,
+    upstream: after.upstream
+  };
+}
+
+function syncReadySummary(root, action) {
+  const summary = getGitSummary(root);
+  if (!summary.available) throw new Error(`Git history is unavailable for this workspace, so FileGRC cannot ${action}.`);
+  if (!summary.branch) throw new Error(`Check out a branch before trying to ${action}.`);
+  if (!summary.clean) throw new Error(`Commit or discard workspace changes before trying to ${action}.`);
+  return summary;
+}
+
+function parseLogLine(line) {
+  if (!line) return null;
+  const [commit, timestamp, author, subject] = line.split("\x1f");
+  return { commit, shortCommit: commit?.slice(0, 8), timestamp, author, subject };
+}
+
+function lines(source) {
+  return source ? source.split("\n").filter(Boolean) : [];
+}
+
+function git(cwd, args) {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: 10_000,
+    maxBuffer: 20_000_000
+  }).trim();
+}
+
+function tryGit(cwd, args) {
+  try {
+    return git(cwd, args);
+  } catch {
+    return "";
+  }
+}
+
+function gitForWrite(cwd, args, action = "create the commit") {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 30_000,
+      maxBuffer: 20_000_000,
+      env: {
+        ...process.env,
+        GIT_TERMINAL_PROMPT: "0",
+        GIT_MERGE_AUTOEDIT: "no"
+      }
+    }).trim();
+  } catch (error) {
+    const message = error.stderr?.trim() || error.stdout?.trim() || error.message;
+    throw new Error(`Git could not ${action}. ${message}`);
+  }
+}
+
+function tryGitForWrite(cwd, args) {
+  try {
+    gitForWrite(cwd, args);
+  } catch {
+    // Best-effort cleanup after a failed remote operation.
+  }
+}

package/src/id.js

@@ -0,0 +1,19 @@
+export function createResourceId(type, title, existingIds = []) {
+  const slugPart = (value) => String(value)
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+  const prefix = slugPart(type) || "record";
+  const name = slugPart(title) || "new";
+  const base = `${prefix}-${name}`;
+  const used = new Set([...existingIds].map(String));
+  let candidate = base;
+  let suffix = 2;
+  while (used.has(candidate)) {
+    candidate = `${base}-${suffix}`;
+    suffix += 1;
+  }
+  return candidate;
+}

package/src/index.js

@@ -0,0 +1,47 @@
+export { getResourceDefinition, loadModel } from "../model/index.js";
+export { buildAgentGuide, findResourceReferences, listResourceTypes, scaffoldResourceMutation } from "./agent.js";
+export { assessAuditPreparation, prepareAuditWorkspace } from "./audit-preparation.js";
+export { buildWorkspace } from "./build.js";
+export { generateEvidencePacket, prepareEvidencePacket, writeEvidencePacket } from "./evidence-packet.js";
+export {
+  addEvidenceAttachment,
+  createResource,
+  createResourceAndLink,
+  createResources,
+  deleteResource,
+  removeEvidenceAttachment,
+  resourcePath,
+  updateContent,
+  updateResource
+} from "./files.js";
+export {
+  commitAndPushWorkspace,
+  commitWorkspace,
+  getFileHistory,
+  getGitSummary,
+  getWorkspaceHistories,
+  pullWorkspace,
+  pushWorkspace
+} from "./git.js";
+export { generateModelDocumentation } from "./model-docs.js";
+export { renderMarkdown } from "./markdown.js";
+export {
+  completeObligationAction,
+  completeObligationEvent,
+  completeObligationOccurrence,
+  createObligationEvent,
+  planObligations
+} from "./obligations.js";
+export {
+  addCalendarDays,
+  calendarDayDifference,
+  calendarOccurrence,
+  calendarOccurrenceIndex,
+  nextCalendarOccurrence
+} from "./recurrence.js";
+export { searchResources, searchableValues } from "./search.js";
+export { createFileGRCServer, serveWorkspace } from "./server.js";
+export { createAppState } from "./state.js";
+export { currentCalendarDate, formatCalendarDate, formatLocalDateTime } from "./time.js";
+export { validateWorkspace } from "./validate.js";
+export { indexResources, loadWorkspace } from "./workspace.js";

package/src/markdown.js

@@ -0,0 +1,123 @@
+export function renderMarkdown(source = "") {
+  const lines = String(source).replace(/\r\n?/g, "\n").split("\n");
+  const output = [];
+  let paragraph = [];
+  let list = null;
+  let code = null;
+  let table = null;
+
+  const flushParagraph = () => {
+    if (!paragraph.length) return;
+    output.push(`<p>${inline(paragraph.join(" "))}</p>`);
+    paragraph = [];
+  };
+  const flushList = () => {
+    if (!list) return;
+    output.push(`<${list.kind}>${list.items.map((item) => `<li>${inline(item)}</li>`).join("")}</${list.kind}>`);
+    list = null;
+  };
+  const flushTable = () => {
+    if (!table) return;
+    const [head, ...rows] = table;
+    output.push(`<div class="table-wrap"><table><thead><tr>${head.map((cell) => `<th>${inline(cell)}</th>`).join("")}</tr></thead><tbody>${rows.map((row) => `<tr>${row.map((cell) => `<td>${inline(cell)}</td>`).join("")}</tr>`).join("")}</tbody></table></div>`);
+    table = null;
+  };
+  const flush = () => {
+    flushParagraph();
+    flushList();
+    flushTable();
+  };
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (code) {
+      if (line.startsWith("```")) {
+        output.push(`<pre><code>${escapeHtml(code.join("\n"))}</code></pre>`);
+        code = null;
+      } else {
+        code.push(line);
+      }
+      continue;
+    }
+    if (line.startsWith("```")) {
+      flush();
+      code = [];
+      continue;
+    }
+    const heading = /^(#{1,6})\s+(.+)$/.exec(line);
+    if (heading) {
+      flush();
+      const level = heading[1].length;
+      output.push(`<h${level}>${inline(heading[2])}</h${level}>`);
+      continue;
+    }
+    if (/^>\s?/.test(line)) {
+      flush();
+      output.push(`<blockquote>${inline(line.replace(/^>\s?/, ""))}</blockquote>`);
+      continue;
+    }
+    if (/^[-*_]{3,}\s*$/.test(line)) {
+      flush();
+      output.push("<hr>");
+      continue;
+    }
+    const unordered = /^\s*[-*]\s+(.+)$/.exec(line);
+    const ordered = /^\s*\d+[.)]\s+(.+)$/.exec(line);
+    if (unordered || ordered) {
+      flushParagraph();
+      flushTable();
+      const kind = ordered ? "ol" : "ul";
+      if (list && list.kind !== kind) flushList();
+      list ??= { kind, items: [] };
+      list.items.push((unordered ?? ordered)[1]);
+      continue;
+    }
+    if (line.includes("|") && index + 1 < lines.length && isTableDivider(lines[index + 1])) {
+      flush();
+      table = [parseTableRow(line)];
+      index += 1;
+      continue;
+    }
+    if (table && line.includes("|")) {
+      table.push(parseTableRow(line));
+      continue;
+    }
+    if (!line.trim()) {
+      flush();
+      continue;
+    }
+    paragraph.push(line.trim());
+  }
+  flush();
+  if (code) output.push(`<pre><code>${escapeHtml(code.join("\n"))}</code></pre>`);
+  return output.join("\n");
+}
+
+function inline(source) {
+  let value = escapeHtml(source);
+  value = value.replace(/`([^`]+)`/g, "<code>$1</code>");
+  value = value.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
+  value = value.replace(/\*([^*]+)\*/g, "<em>$1</em>");
+  value = value.replace(/\[([^\]]+)]\(([^)\s]+)\)/g, (_, label, target) => {
+    if (!/^(?:https?:|mailto:|#)/.test(target)) return label;
+    return `<a href="${target.replaceAll("`", "&#96;")}" rel="noreferrer">${label}</a>`;
+  });
+  return value;
+}
+
+function parseTableRow(line) {
+  return line.replace(/^\s*\||\|\s*$/g, "").split("|").map((cell) => cell.trim());
+}
+
+function isTableDivider(line) {
+  return /^\s*\|?\s*:?-{3,}/.test(line) && line.includes("|");
+}
+
+export function escapeHtml(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}

package/src/model-docs.js

@@ -0,0 +1,119 @@
+export function generateModelDocumentation(model) {
+  const lines = [
+    "# GRC Data Model",
+    "",
+    `<!-- Generated from packages/filegrc/model/v${model.modelVersion}.json. Do not edit by hand. -->`,
+    "",
+    `Model version: \`${model.modelVersion}\``,
+    "",
+    model.description,
+    "",
+    "Each structured resource is one UTF-8 JSON file. Long-form work is an implicit Markdown companion beside that JSON file. Git supplies file authors, timestamps, diffs, commit messages, and revisions, so records do not duplicate those fields or file paths.",
+    "",
+    "## Common fields",
+    "",
+    "| Field | Type | Required | Meaning |",
+    "| --- | --- | --- | --- |"
+  ];
+  for (const [name, field] of Object.entries(model.commonFields)) {
+    lines.push(`| \`${name}\` | ${fieldType(field)} | ${field.required ? "Yes" : "No"} | ${escapeCell(fieldNotes(field))} |`);
+  }
+  lines.push(
+    "",
+    "## Record Markdown",
+    "",
+    "Resources with no dedicated Markdown use an optional companion with the same basename as the JSON record. The renderer creates and discovers this file from the stable record location, so no path is stored in the record.",
+    "",
+    `Record Markdown is shown by default for: ${model.recordContent.defaultResourceTypes.map((type) => `\`${type}\``).join(", ")}. Other resources without dedicated Markdown can add it when structured fields are not enough.`,
+    "",
+    "## Audit preparation defaults",
+    "",
+    "The engine and renderer use these model-owned defaults to prepare Type 1 and Type 2 engagements. Preparation creates engagement-specific management documents from the local starter templates. Management still confirms scope, approves documents, catalogs authoritative source systems, reconciles Type 2 populations, and supplies source evidence.",
+    "",
+    "Management documents:",
+    "",
+    ...model.auditReadiness.managementDocuments.map((item) => `- **${item.title}** (\`${item.kind}\`): ${item.timing}`),
+    "",
+    "Standard populations, including zero-event populations:",
+    "",
+    ...model.auditReadiness.populationTemplates.map((item) => `- **${item.title}** (\`${item.kind}\`): source role \`${item.sourceKind}\`; start with ${item.sourcePrompt}. ${item.timing}`),
+    "",
+    "Authoritative systems of record:",
+    "",
+    ...model.auditReadiness.externalEvidence.map((item) => `- **${item.title}** (${item.sourceKinds.map((kind) => `\`${kind}\``).join(", ")}): ${item.description} ${item.timing}`),
+    "",
+    "## Resource groups",
+    ""
+  );
+
+  for (const group of model.groups) {
+    const resources = Object.entries(model.resources).filter(([, resource]) => resource.group === group.id);
+    if (!resources.length) continue;
+    lines.push(`### ${group.title}`, "");
+    for (const [type, resource] of resources) {
+      lines.push(`#### \`${type}\``, "", resource.description, "");
+      lines.push(`Policy basis: ${resource.guidance.policyBasis}`, "");
+      lines.push(`Timing: ${resource.guidance.cadence}`, "");
+      if (resource.guidance.sourceResourceIds?.length) {
+        lines.push(`Default sources: ${resource.guidance.sourceResourceIds.map((id) => `\`${id}\``).join(", ")}`, "");
+      }
+      if (resource.titleLabel) lines.push(`The UI labels the common \`title\` field as **${resource.titleLabel}**.`, "");
+      const recordPath = (resource.recordPath ?? "{id}.json").replaceAll("{id}", "<id>");
+      lines.push(`Path: \`${resource.singleton ? `data/${resource.singleton}` : `data/${resource.collection}/${recordPath}`}\``, "");
+      const contentMode = recordContentMode(model, type, resource);
+      if (contentMode) {
+        lines.push(`Record Markdown: ${contentMode === "default" ? "shown by default" : "available when needed"} as an implicit companion file.`, "");
+      }
+      if (resource.markdown) {
+        lines.push("Markdown companions:", "");
+        for (const [name, markdown] of Object.entries(resource.markdown)) {
+          const suffix = markdown.primary ? ".md" : `-${name}.md`;
+          lines.push(`- **${markdown.label}**: \`${suffix}\` beside the JSON record${markdown.required ? " (required)" : " (optional)"}.`);
+        }
+        lines.push("");
+      }
+      lines.push("| Field | Type | Required | Notes |", "| --- | --- | --- | --- |");
+      const required = new Set(resource.required ?? []);
+      for (const [name, field] of Object.entries(resource.fields ?? {})) {
+        const requiredLabel = required.has(name) || field.required ? "Yes" : field.requiredWhen ? "Conditional" : "No";
+        lines.push(`| \`${name}\` | ${fieldType(field)} | ${requiredLabel} | ${escapeCell(fieldNotes(field))} |`);
+      }
+      for (const choices of resource.oneOf ?? []) {
+        lines.push("", `At least one of ${choices.map(choiceLabel).join(", ")} is required.`);
+      }
+      lines.push("");
+    }
+  }
+  return lines.join("\n");
+}
+
+function recordContentMode(model, type, resource) {
+  if (!model.recordContent?.slot || resource.markdown) return null;
+  return model.recordContent.defaultResourceTypes.includes(type) ? "default" : "optional";
+}
+
+function choiceLabel(name) {
+  if (name.startsWith("$markdown:")) return `**${name.slice("$markdown:".length)} Markdown**`;
+  return `\`${name}\``;
+}
+
+function fieldType(field) {
+  if (field.type === "array") return `array of ${field.items ?? "values"}`;
+  return field.format && field.format !== field.type ? `${field.type} (${field.format})` : field.type;
+}
+
+function fieldNotes(field) {
+  return [
+    field.label,
+    field.values ? `Values: ${field.values.map((item) => `\`${item}\``).join(", ")}` : "",
+    field.relation ? `References: ${field.relation.map((item) => `\`${item}\``).join(", ")}` : "",
+    field.minimum !== undefined ? `Minimum: \`${field.minimum}\`.` : "",
+    field.maximum !== undefined ? `Maximum: \`${field.maximum}\`.` : "",
+    field.disjointFrom ? `Must not overlap \`${field.disjointFrom}\`.` : "",
+    field.requiredWhen ? `Required when ${Object.entries(field.requiredWhen).map(([key, value]) => `\`${key}\` is \`${value}\``).join(" and ")}` : ""
+  ].filter(Boolean).join(" ");
+}
+
+function escapeCell(value) {
+  return String(value).replaceAll("|", "\\|").replaceAll("\n", " ");
+}

package/src/mutation.js

@@ -0,0 +1,15 @@
+import { resolveWorkspaceRoot } from "./paths.js";
+
+const mutationQueues = new Map();
+
+export function serializeWorkspaceMutation(input, task) {
+  const root = resolveWorkspaceRoot(input);
+  const previous = mutationQueues.get(root) ?? Promise.resolve();
+  const run = previous.catch(() => {}).then(() => task(root));
+  let tracked;
+  tracked = run.finally(() => {
+    if (mutationQueues.get(root) === tracked) mutationQueues.delete(root);
+  });
+  mutationQueues.set(root, tracked);
+  return tracked;
+}