filegrc 0.1.0 → 0.3.0

package/src/resource-markdown.js

@@ -8,13 +8,14 @@ export function resourceDataPath(model, record) {
   return join(definition.collection, recordPath).replaceAll("\\", "/");
 }
 
-export function markdownSlots(model, type) {
+export function markdownSlots(model, type, record = null) {
   const definition = getResourceDefinition(model, type);
   const dedicated = Object.entries(definition.markdown ?? {}).map(([name, slot]) => ({
     name,
     label: slot.label ?? humanize(name),
     primary: Boolean(slot.primary),
-    required: Boolean(slot.required)
+    required: Boolean(slot.required || (record && conditionMatches(record, slot.requiredWhen))),
+    requiredWhen: slot.requiredWhen ?? null
   }));
   if (dedicated.length) return dedicated;
   return [{
@@ -26,7 +27,7 @@ export function markdownSlots(model, type) {
 }
 
 export function markdownDataPath(model, record, slotName) {
-  const slot = markdownSlots(model, record.type).find(({ name }) => name === slotName);
+  const slot = markdownSlots(model, record.type, record).find(({ name }) => name === slotName);
   if (!slot) throw new Error(`Unknown Markdown slot "${slotName}" for ${record.type}.`);
   const recordPath = resourceDataPath(model, record);
   const extension = extname(recordPath);
@@ -36,11 +37,17 @@ export function markdownDataPath(model, record, slotName) {
 }
 
 export function markdownEntries(model, record) {
-  return markdownSlots(model, record.type)
+  return markdownSlots(model, record.type, record)
     .map((slot) => ({ ...slot, path: markdownDataPath(model, record, slot.name) }))
     .filter(({ path }) => path);
 }
 
+function conditionMatches(record, condition) {
+  return condition && Object.entries(condition).every(([name, expected]) => (
+    Array.isArray(expected) ? expected.includes(record[name]) : record[name] === expected
+  ));
+}
+
 export function isMarkdownChoice(value) {
   return typeof value === "string" && value.startsWith("$markdown:");
 }

package/src/server.js

@@ -4,16 +4,18 @@ 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 } from "./favicon.js";
 import { createResource, deleteResource, updateContent, updateResource } from "./files.js";
 import { commitAndPushWorkspace, getFileHistory, pullWorkspace, pushWorkspace } from "./git.js";
 import { completeObligationOccurrence, createObligationEvent, planObligations } from "./obligations.js";
 import { isWithin, relativeToWorkspace, resolveWorkspacePath } from "./paths.js";
 import { createAppState } from "./state.js";
+import { setupWorkspace } from "./setup.js";
 import { loadWorkspace } from "./workspace.js";
 import { APP_SCRIPT, APP_STYLES, renderIndex } from "./web.js";
 
-export function createFileGRCServer(input = process.cwd(), options = {}) {
+export function createFilegrcServer(input = process.cwd(), options = {}) {
   return createHttpServer(async (request, response) => {
     try {
       if (!expectedHost(request, options.allowedHosts)) {
@@ -82,6 +84,12 @@ export function createFileGRCServer(input = process.cwd(), options = {}) {
       if (request.method === "POST" && url.pathname === "/api/audit-preparation") {
         return json(response, 201, await prepareAuditWorkspace(input, await readJson(request)));
       }
+      if (request.method === "POST" && url.pathname === "/api/evidence-test-drafts") {
+        return json(response, 201, await ensureEvidenceTestDrafts(input));
+      }
+      if (request.method === "POST" && url.pathname === "/api/setup") {
+        return json(response, 200, await setupWorkspace(input, await readJson(request)));
+      }
       if (request.method === "POST" && url.pathname === "/api/resources") {
         const payload = await readJson(request);
         const record = payload.record ?? payload;
@@ -176,7 +184,7 @@ export async function serveWorkspace(input = process.cwd(), options = {}) {
   }
   const loaded = await loadWorkspace(input);
   getResourceDefinition(loaded.model, "workspace");
-  const server = createFileGRCServer(loaded.root, { allowedHosts: [host] });
+  const server = createFilegrcServer(loaded.root, { allowedHosts: [host] });
   await new Promise((resolve, reject) => {
     server.once("error", reject);
     server.listen(port, host, resolve);

package/src/setup.js

@@ -0,0 +1,187 @@
+import { createResource, updateResource } from "./files.js";
+import { ensureEvidenceTestDrafts } from "./evidence-tests.js";
+import { createResourceId } from "./id.js";
+import { loadWorkspace } from "./workspace.js";
+
+const PROGRAM_GOALS = new Set(["none", "readiness", "type-1", "type-2"]);
+const CRITICALITIES = new Set(["low", "medium", "high", "critical"]);
+
+export async function setupWorkspace(input = process.cwd(), payload = {}) {
+  const loaded = await loadWorkspace(input);
+  const setup = normalizeSetupPayload(payload);
+  validateSetup(loaded, setup);
+
+  let current = loaded;
+  let system = findSetupSystem(current.resources, setup);
+  const systemId = system?.id || createResourceId("system", setup.serviceName, current.resources.map(({ id }) => id));
+  system = {
+    ...(system || {}),
+    schemaVersion: 1,
+    id: systemId,
+    type: "system",
+    title: setup.serviceName,
+    status: setup.draft ? system?.status || "planned" : (system?.status === "planned" ? "active" : system?.status || "active"),
+    criticality: setup.criticality,
+    ownerIds: [setup.ownerId],
+    description: setup.boundary,
+    systemKind: system?.systemKind || "service",
+    dataClassification: setup.dataClassification,
+    internetExposed: setup.internetExposed,
+    inScope: true
+  };
+  await upsertResource(current.root, current.resources.find(({ id }) => id === systemId), system);
+
+  current = await loadWorkspace(current.root);
+  const linkedControlIds = [];
+  for (const control of current.resources.filter(({ type, status }) => (
+    type === "control" && !["not-applicable", "retired"].includes(status)
+  ))) {
+    if ((control.systemIds || []).includes(systemId)) continue;
+    await updateResource(current.root, "control", control.id, {
+      ...control,
+      systemIds: [...new Set([...(control.systemIds || []), systemId])]
+    });
+    linkedControlIds.push(control.id);
+  }
+
+  current = await loadWorkspace(current.root);
+  const existingWorkspace = current.resources.find(({ type }) => type === "workspace");
+  if (!existingWorkspace) throw new Error("The workspace settings record was not found.");
+  const workspace = {
+    ...existingWorkspace,
+    assuranceGoal: assuranceGoalFromSetup(setup.programGoal),
+    frameworkIds: current.resources
+      .filter(({ type, status }) => type === "framework" && status === "active")
+      .map(({ id }) => id),
+    requirementIds: current.resources
+      .filter(({ type, applicability }) => type === "requirement" && applicability === "applicable")
+      .map(({ id }) => id),
+    controlIds: current.resources
+      .filter(({ type, status }) => type === "control" && !["not-applicable", "retired"].includes(status))
+      .map(({ id }) => id),
+    systemIds: [...new Set([...(existingWorkspace.systemIds || []), systemId])]
+  };
+  await updateResource(current.root, "workspace", workspace.id, workspace);
+
+  current = await loadWorkspace(current.root);
+  const renderer = current.resources.find(({ type }) => type === "renderer-settings");
+  if (renderer) {
+    await updateResource(current.root, renderer.type, renderer.id, {
+      ...renderer,
+      showOnboarding: setup.draft
+    });
+  }
+  const evidenceTestDrafts = setup.draft
+    ? { created: [], existing: [], total: 0 }
+    : await ensureEvidenceTestDrafts(current.root);
+
+  return {
+    draft: setup.draft,
+    system,
+    workspace,
+    linkedControlIds,
+    evidenceTestDraftIds: evidenceTestDrafts.created.map(({ id }) => id),
+    onboardingComplete: !setup.draft
+  };
+}
+
+export function normalizeSetupPayload(payload = {}) {
+  if (!payload || Array.isArray(payload) || typeof payload !== "object") {
+    throw new Error("Setup input must be a JSON object.");
+  }
+  const draft = payload.draft === true;
+  return {
+    serviceName: cleanText(payload.serviceName, "serviceName"),
+    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"),
+    internetExposed: booleanValue(payload.internetExposed, "internetExposed"),
+    programGoal: cleanText(payload.programGoal ?? "none", "programGoal"),
+    draft,
+    systemId: cleanOptionalText(payload.systemId, "systemId")
+  };
+}
+
+function validateSetup(loaded, setup) {
+  for (const [name, value] of [
+    ["serviceName", setup.serviceName],
+    ["boundary", setup.boundary],
+    ["ownerId", setup.ownerId],
+    ["criticality", setup.criticality],
+    ["dataClassification", setup.dataClassification]
+  ]) {
+    if (!value) throw new Error(`Setup field "${name}" is required.`);
+  }
+  if (setup.serviceName.length > 200) throw new Error("serviceName must be 200 characters or fewer.");
+  if (setup.boundary.length > 2_000) throw new Error("boundary must be 2,000 characters or fewer.");
+  if (!CRITICALITIES.has(setup.criticality)) {
+    throw new Error(`criticality must be one of ${[...CRITICALITIES].join(", ")}.`);
+  }
+  if (!PROGRAM_GOALS.has(setup.programGoal)) {
+    throw new Error(`programGoal must be one of ${[...PROGRAM_GOALS].join(", ")}.`);
+  }
+  const owner = loaded.resources.find(({ id, type }) => id === setup.ownerId && type === "person");
+  if (!owner || owner.status !== "active") throw new Error(`Active person "${setup.ownerId}" was not found.`);
+  if (setup.systemId) {
+    const system = loaded.resources.find(({ id, type }) => id === setup.systemId && type === "system");
+    if (!system) throw new Error(`System "${setup.systemId}" was not found.`);
+    if (["deprecated", "retired"].includes(system.status)) {
+      throw new Error(`System "${setup.systemId}" cannot be used for initial scope because it is ${system.status}.`);
+    }
+  }
+  const classifications = Object.keys(loaded.workspace.classificationDefinitions || {});
+  if (classifications.length && !classifications.includes(setup.dataClassification)) {
+    throw new Error(`dataClassification must be one of ${classifications.join(", ")}.`);
+  }
+}
+
+function findSetupSystem(resources, setup) {
+  return (setup.systemId && resources.find(({ type, id }) => type === "system" && id === setup.systemId))
+    || resources.find(({ type, title, inScope, status }) => (
+      type === "system"
+      && inScope === true
+      && status !== "retired"
+      && title.trim().toLowerCase() === setup.serviceName.toLowerCase()
+    ));
+}
+
+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";
+  if (goal === "readiness") return "readiness";
+  return "none";
+}
+
+function booleanValue(value, name) {
+  if (value === true || value === false) return value;
+  if (value === "true") return true;
+  if (value === "false") return false;
+  throw new Error(`Setup field "${name}" must be true or false.`);
+}
+
+function cleanText(value, name) {
+  if (value === undefined || value === null) return "";
+  const result = String(value).trim();
+  if (/[\u0000-\u001f\u007f]/.test(result)) throw new Error(`Setup field "${name}" contains control characters.`);
+  return result;
+}
+
+function cleanMultilineText(value, name) {
+  if (value === undefined || value === null) return "";
+  const result = String(value).trim();
+  if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(result)) {
+    throw new Error(`Setup field "${name}" contains unsupported control characters.`);
+  }
+  return result;
+}
+
+function cleanOptionalText(value, name) {
+  return value === undefined || value === null || value === "" ? "" : cleanText(value, name);
+}

package/src/state.js

@@ -5,6 +5,7 @@ import { getGitSummary, getWorkspaceHistories } from "./git.js";
 import { renderMarkdown } from "./markdown.js";
 import { planObligations } from "./obligations.js";
 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";
@@ -46,18 +47,23 @@ export async function createAppState(input = process.cwd(), options = {}) {
     dataModelVersion: loaded.model.modelVersion,
     id: "workspace",
     type: "workspace",
-    title: "FileGRC workspace",
+    title: "filegrc workspace",
     organizationName: "Workspace configuration unavailable",
     timezone: "UTC"
   };
   const asOf = options.asOf ?? currentCalendarDate(workspace.timezone);
   const generatedAt = new Date().toISOString();
+  const programReadiness = await assessProgramReadiness(loaded, {
+    asOf,
+    generatedAt
+  });
   const audits = loaded.resources.filter((record) => record.type === "audit");
   const auditPreparations = Object.fromEntries(await Promise.all(
     (audits.length ? audits : [null]).map(async (audit) => {
       const preparation = await assessAuditPreparation(loaded, {
         auditId: audit?.id,
-        generatedAt
+        generatedAt,
+        programReadiness
       });
       return [audit?.id || "none", preparation];
     })
@@ -74,6 +80,7 @@ export async function createAppState(input = process.cwd(), options = {}) {
       diagnostics: validation.diagnostics
     },
     obligations: planObligations(entries, { asOf, now: options.now ?? generatedAt }),
+    programReadiness,
     auditPreparations,
     git
   };

package/src/validate.js

@@ -2,8 +2,10 @@ import { stat } from "node:fs/promises";
 import { getResourceDefinition } from "../model/index.js";
 import { isCanonicalDataPath, resolveDataPath } from "./paths.js";
 import { parseCalendarDate, validCalendarRecurrence } from "./recurrence.js";
+import { obligationIsRunning } from "./program-lifecycle.js";
+import { partyPeople } from "./parties.js";
 import { isMarkdownChoice, markdownEntries } from "./resource-markdown.js";
-import { isRfc3339Timestamp } from "./time.js";
+import { currentCalendarDate, isRfc3339Timestamp } from "./time.js";
 import { indexResources, loadWorkspace } from "./workspace.js";
 
 const ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -17,6 +19,14 @@ export async function validateWorkspace(input = process.cwd()) {
   const diagnostics = [...loaded.diagnostics];
   const { byId } = indexResources(loaded.resources);
   const seen = new Map();
+  const asOf = currentCalendarDate(loaded.workspace?.timezone || "UTC");
+  const obligationsByControl = new Map();
+  for (const obligation of loaded.resources.filter((record) => record.type === "obligation" && record.status !== "retired")) {
+    for (const controlId of obligation.controlIds || []) {
+      if (!obligationsByControl.has(controlId)) obligationsByControl.set(controlId, []);
+      obligationsByControl.get(controlId).push(obligation);
+    }
+  }
 
   for (const entry of loaded.entries) {
     const { record } = entry;
@@ -88,6 +98,7 @@ export async function validateWorkspace(input = process.cwd()) {
     }
     validateIndependentApproval(record, byId, displayPath, diagnostics);
     validateCompletedObligationEvent(record, byId, displayPath, diagnostics);
+    validateImplementedControlSchedules(record, obligationsByControl, byId, asOf, displayPath, diagnostics);
     await validateMarkdown(record, definition, loaded.model, loaded.root, displayPath, diagnostics);
   }
 
@@ -104,10 +115,41 @@ export async function validateWorkspace(input = process.cwd()) {
   };
 }
 
+function validateImplementedControlSchedules(record, obligationsByControl, byId, asOf, path, diagnostics) {
+  if (record.type !== "control" || record.status !== "implemented") return;
+  const schedules = obligationsByControl.get(record.id) || [];
+  if (!schedules.length || schedules.every((obligation) => obligationIsRunning(obligation, byId, asOf))) return;
+  const stopped = schedules.filter((obligation) => !obligationIsRunning(obligation, byId, asOf));
+  const paused = stopped.filter((obligation) => obligation.status === "paused");
+  const waiting = stopped.filter((obligation) => obligation.status === "active");
+  const policyBlockers = [...new Set(waiting.flatMap((obligation) => (obligation.policyIds || []).map((id) => {
+    const policy = byId.get(id);
+    if (!policy || policy.type !== "policy") return `${id} (missing)`;
+    if (policy.status !== "active") return `${policy.title} (${policy.status})`;
+    if (!policy.effectiveOn) return `${policy.title} (effective date missing)`;
+    if (policy.effectiveOn > asOf) return `${policy.title} (effective ${policy.effectiveOn})`;
+    return null;
+  })).filter(Boolean))];
+  const reasons = [
+    waiting.length
+      ? `${waiting.length} enabled ${waiting.length === 1 ? "schedule is" : "schedules are"} waiting for governing ${policyBlockers.length === 1 ? "policy" : "policies"} to become active and effective${policyBlockers.length ? `: ${policyBlockers.join(", ")}` : ""}. Complete Step 2 first.`
+      : "",
+    paused.length
+      ? `${paused.length} linked ${paused.length === 1 ? "schedule is" : "schedules are"} paused. Enable ${paused.length === 1 ? "it" : "them"} before implementing the control.`
+      : ""
+  ].filter(Boolean).join(" ");
+  diagnostics.push(error(
+    "control-work-queue-not-running",
+    path,
+    `This control cannot be marked implemented yet. ${reasons}`
+  ));
+}
+
 function validateDateRanges(record, path, diagnostics) {
   for (const [startField, endField] of [
     ["startDate", "endDate"],
     ["periodStart", "periodEnd"],
+    ["candidatePeriodStart", "candidatePeriodEnd"],
     ["dueWindowStart", "dueWindowEnd"]
   ]) {
     const start = record[startField];
@@ -131,9 +173,11 @@ function validateCompletedObligationEvent(record, byId, path, diagnostics) {
       "completedOn cannot be before occurredOn."
     ));
   }
-  const actionIds = record.actionItemIds || [];
+  const actionIds = [...byId.values()]
+    .filter((candidate) => candidate.type === "action-item" && candidate.sourceResourceId === record.id)
+    .map((candidate) => candidate.id);
   if (actionIds.length === 0) {
-    diagnostics.push(error("incomplete-obligation-event", path, "A complete obligation event must have action items."));
+    diagnostics.push(error("incomplete-obligation-event", path, "A complete Policy Event must have action items."));
     return;
   }
   for (const actionId of actionIds) {
@@ -180,9 +224,10 @@ function validateEvidencePaths(record, path, diagnostics) {
 }
 
 function validateIndependentApproval(record, byId, path, diagnostics) {
-  if (!["policy", "document"].includes(record.type) || !(record.approverIds || []).length) return;
-  const owners = expandPeople(record.ownerIds || [], byId);
-  const approvers = expandPeople(record.approverIds || [], byId);
+  if (!["policy", "document"].includes(record.type)) return;
+  if (!(record.approverIds || []).length) return;
+  const owners = partyPeople(record.ownerIds || [], byId);
+  const approvers = partyPeople(record.approverIds || [], byId);
   const overlap = [...owners].filter((id) => approvers.has(id));
   if (overlap.length) {
     diagnostics.push(error(
@@ -193,22 +238,6 @@ function validateIndependentApproval(record, byId, path, diagnostics) {
   }
 }
 
-function expandPeople(ids, byId, seen = new Set()) {
-  const people = new Set();
-  for (const id of ids) {
-    if (seen.has(id)) continue;
-    seen.add(id);
-    const record = byId.get(id);
-    if (record?.type === "person") people.add(id);
-    if (record?.type === "team") {
-      for (const personId of expandPeople([...(record.memberIds || []), ...(record.chairIds || [])], byId, seen)) {
-        people.add(personId);
-      }
-    }
-  }
-  return people;
-}
-
 function validateObligation(record, path, diagnostics) {
   const recurrence = record.recurrence;
   if (!recurrence || Array.isArray(recurrence) || typeof recurrence !== "object") return;
@@ -364,7 +393,9 @@ async function validateMarkdown(record, definition, model, root, path, diagnosti
     }
   }
 
-  for (const choices of definition.oneOf ?? []) {
+  for (const group of definition.oneOf ?? []) {
+    const choices = Array.isArray(group) ? group : group.fields;
+    if (!Array.isArray(choices) || (!Array.isArray(group) && !conditionMatches(record, group.when))) continue;
     const satisfied = choices.some((name) => (
       isMarkdownChoice(name)
         ? present.has(name.slice("$markdown:".length))
@@ -480,7 +511,9 @@ function isTimezone(value) {
 }
 
 function conditionMatches(record, condition) {
-  return Object.entries(condition).every(([name, value]) => record[name] === value);
+  return Boolean(condition) && Object.entries(condition).every(([name, expected]) => (
+    Array.isArray(expected) ? expected.includes(record[name]) : record[name] === expected
+  ));
 }
 
 function findDefinitionType(model, definition) {