filegrc 0.3.4 → 0.4.0

package/src/program-readiness.js

@@ -1,4 +1,5 @@
 import { readFile } from "node:fs/promises";
+import { coverageEnd, coverageStart } from "./coverage.js";
 import { planObligations } from "./obligations.js";
 import { resolveDataPath } from "./paths.js";
 import { obligationIsRunning } from "./program-lifecycle.js";
@@ -7,8 +8,6 @@ import { markdownEntries } from "./resource-markdown.js";
 import { currentCalendarDate } from "./time.js";
 import { loadWorkspace } from "./workspace.js";
 
-const TEST_EVIDENCE_KINDS = new Set(["test-capture", "test-export"]);
-
 export async function assessProgramReadiness(input, options = {}) {
   const loaded = input?.resources && input?.model && input?.entries
     ? input
@@ -25,38 +24,33 @@ export async function assessProgramReadiness(input, options = {}) {
     return markdown.get(record.id);
   };
 
+  const controlStage = await controlsStage(scope, byId, readMarkdown, asOf);
   const sourceStage = await evidenceSourcesStage(scope, byId, loaded.model, readMarkdown);
-  const collectionStage = evidenceCollectionStage(scope, records, byId, loaded.model);
-  const evidenceStage = stage(
-    "evidence",
-    "Test Evidence Collection",
-    "For external evidence without a dedicated Step 5 record, catalog the authoritative Systems, document repeatable extraction, and verify one test capture before operation begins.",
-    [...sourceStage.items, ...collectionStage.items]
-  );
+  controlStage.items.push(...sourceStage.items);
+  controlStage.description = "Each implemented control needs an owner, actual procedure, scope, operation pattern, mappings, an implementation date, and complete authoritative source Systems with the required evidence roles, access owners, and retrieval instructions.";
   const evidenceGateStages = [
     scopeStage(workspace, scope, records, byId),
     await policiesStage(scope, byId, readMarkdown, asOf),
-    await controlsStage(scope, byId, readMarkdown, asOf),
-    evidenceStage
+    controlStage
   ];
   for (const current of evidenceGateStages) finalizeStage(current);
   const evidenceReady = evidenceGateStages.every((current) => current.counts.action === 0);
   const stages = [
     ...evidenceGateStages,
-    operationStage(workspace, scope, records, byId, asOf, evidenceReady)
+    operationStage(workspace, scope, records, byId, asOf, evidenceReady, loaded.model)
   ];
   finalizeStage(stages.at(-1));
   const candidateStarted = Boolean(
     workspace?.assuranceGoal === "soc-2-type-2"
-    && workspace.candidatePeriodStart
-    && workspace.candidatePeriodStart <= asOf
+    && workspace.candidateCoverage?.kind === "range"
+    && coverageStart(workspace.candidateCoverage) <= asOf
   );
-  const obligations = planObligations(records, { asOf, through: asOf });
+  const obligations = planObligations(records, { asOf, through: asOf, model: loaded.model });
   const operating = evidenceReady && candidateStarted && obligations.counts.overdue === 0;
   const canStartCandidatePeriod = Boolean(
     evidenceReady
     && workspace?.assuranceGoal === "soc-2-type-2"
-    && !workspace.candidatePeriodStart
+    && !workspace.candidateCoverage
   );
   const items = stages.flatMap((current) => current.items);
   const managedItems = items.filter((current) => !["info", "later"].includes(current.status));
@@ -70,9 +64,7 @@ export async function assessProgramReadiness(input, options = {}) {
     target: {
       goal: workspace?.assuranceGoal || "none",
       label: assuranceGoalLabel(workspace?.assuranceGoal),
-      candidateTypeOneAsOf: workspace?.candidateTypeOneAsOf || null,
-      candidatePeriodStart: workspace?.candidatePeriodStart || null,
-      candidatePeriodEnd: workspace?.candidatePeriodEnd || null
+      candidateCoverage: workspace?.candidateCoverage || null
     },
     status: operating ? "operating" : evidenceReady ? "evidence-ready" : "needs-work",
     evidenceReady,
@@ -96,15 +88,37 @@ export async function assessProgramReadiness(input, options = {}) {
   };
 }
 
+export async function assessEvidenceMap(input, options = {}) {
+  const readiness = await assessProgramReadiness(input, options);
+  const evidenceItems = readiness.stages
+    .find((stage) => stage.id === "controls")
+    ?.items.filter((current) => current.id.startsWith("source-family-")) || [];
+  const counts = countStatuses(evidenceItems);
+  return {
+    schemaVersion: 1,
+    generatedAt: readiness.generatedAt,
+    asOf: readiness.asOf,
+    status: counts.action ? "action" : "complete",
+    counts,
+    workflow: [
+      "Choose an existing System or create the System that is authoritative for each evidence family.",
+      "On every source System, set an evidence source role, name current evidence access owners, and write repeatable retrieval instructions in Record Markdown.",
+      "Set each selected Control's evidenceSourceIds to the authoritative Systems that produce its evidence.",
+      "Run program-readiness again and resolve every incomplete source check and control mapping before marking the Controls implemented."
+    ],
+    items: evidenceItems
+  };
+}
+
 function programScope(workspace, records, byId) {
   const select = (ids, type, fallback) => {
     if (ids?.length) return ids.map((id) => byId.get(id)).filter((record) => record?.type === type);
     return records.filter(fallback);
   };
   return {
-    systems: select(workspace?.systemIds, "system", (record) => (
-      record.type === "system" && record.inScope === true && record.status !== "retired"
-    )),
+    systems: (workspace?.systemIds || [])
+      .map((id) => byId.get(id))
+      .filter((record) => record?.type === "system" && record.status !== "retired"),
     frameworks: select(workspace?.frameworkIds, "framework", (record) => (
       record.type === "framework" && record.status === "active"
     )),
@@ -134,9 +148,8 @@ function scopeStage(workspace, scope, records, byId) {
 
   const completeSystems = scope.systems.filter((system) => (
     system.status === "active"
-    && system.inScope === true
     && system.description
-    && system.dataClassification
+    && system.classificationId
     && (system.ownerIds || []).length
   ));
   items.push(item(
@@ -188,6 +201,9 @@ function programOwnershipItem(records, byId) {
   ));
   const unresolved = ownedRecords.filter((record) => currentPartyPeople(record.ownerIds, byId).size === 0);
   const currentOwners = new Set(ownedRecords.flatMap((record) => [...currentPartyPeople(record.ownerIds, byId)]));
+  const missingJobTitles = [...currentOwners]
+    .map((id) => byId.get(id))
+    .filter((record) => record?.type === "person" && record.status === "active" && !String(record.jobTitle || "").trim());
   const oversight = byId.get("team-security-risk-oversight");
   const policyOwnerIds = new Set(records
     .filter((record) => record.type === "policy" && !["retired", "superseded"].includes(record.status))
@@ -202,7 +218,10 @@ function programOwnershipItem(records, byId) {
     && oversightChairs.size > 0
     && ![...oversightChairs].some((id) => policyOwnerIds.has(id))
   );
-  const complete = currentOwners.size > 0 && unresolved.length === 0 && oversightComplete;
+  const complete = currentOwners.size > 0
+    && unresolved.length === 0
+    && missingJobTitles.length === 0
+    && oversightComplete;
   const unresolvedAssignments = unresolved.map((record) => ({
     resourceType: record.type,
     resourceId: record.id,
@@ -215,6 +234,9 @@ function programOwnershipItem(records, byId) {
   if (unresolved.length) {
     detail.push(`${unresolved.length} ${unresolved.length === 1 ? "record has" : "records have"} no current person owner.`);
   }
+  if (missingJobTitles.length) {
+    detail.push(`${missingJobTitles.length} active ${missingJobTitles.length === 1 ? "owner needs" : "owners need"} an organizational job title.`);
+  }
   if (!oversightComplete) detail.push("Finish and activate Security and Risk Oversight with a current chair who is separate from policy ownership.");
   const oversightId = oversight?.id ? shellArgument(oversight.id) : null;
   return item(
@@ -227,9 +249,11 @@ function programOwnershipItem(records, byId) {
     !oversightComplete ? oversight : unresolved[0] || { type: "person" },
     {
       unresolvedAssignments,
+      missingJobTitleIds: missingJobTitles.map(({ id }) => id),
       ...(!oversightComplete && oversight ? {
         commands: [
           "npx filegrc guide person --json",
+          "npx filegrc guide appointment --json",
           "npx filegrc list person --json",
           'npx filegrc scaffold person --title "REVIEWER NAME" | npx filegrc create - --json',
           `npx filegrc get ${oversightId} --mutation`,
@@ -251,8 +275,13 @@ function ownershipResolutionReasons(ownerIds, byId) {
     if (owner.type === "team" && owner.status !== "active") {
       return [{ ownerId, reason: "inactive-team" }];
     }
+    if (owner.type === "appointment" && owner.status !== "active") {
+      return [{ ownerId, reason: "inactive-appointment" }];
+    }
     if (currentPartyPeople([ownerId], byId).size === 0) {
-      return [{ ownerId, reason: owner.type === "team" ? "team-has-no-current-members" : "no-current-person" }];
+      if (owner.type === "team") return [{ ownerId, reason: "team-has-no-current-members" }];
+      if (owner.type === "appointment") return [{ ownerId, reason: "appointment-has-no-current-holder" }];
+      return [{ ownerId, reason: "no-current-person" }];
     }
     return [];
   });
@@ -312,7 +341,7 @@ async function policiesStage(scope, byId, readMarkdown, asOf) {
         && policy.approvedOn
         && partiesIndependent(policy.ownerIds, policy.approverIds, byId),
       effective: policy.status === "active" && policy.effectiveOn && policy.effectiveOn <= asOf,
-      linkedControls: (policy.controlIds || []).some((id) => scope.controls.some((control) => control.id === id)),
+      linkedControls: scope.controls.some((control) => (control.policyIds || []).includes(policy.id)),
       contentComplete: Boolean(source.trim()) && placeholderCount === 0
     };
     const missing = Object.entries(checks).filter(([, value]) => !value).map(([name]) => policyCheckLabel(name));
@@ -348,13 +377,14 @@ async function controlsStage(scope, byId, readMarkdown, asOf) {
       owner: (control.ownerIds || []).length > 0,
       procedure: substantiveMarkdown(source) && openPlaceholderCount(source) === 0,
       scope: (control.systemIds || []).some((id) => scope.systems.some((system) => system.id === id)),
-      cadence: Boolean(control.frequency),
+      operationPattern: Boolean(control.operationPattern),
       evidenceSource: sourceSystems.length > 0,
       implementationDate: Boolean(control.effectiveOn && control.effectiveOn <= asOf),
       policyMapping: (control.policyIds || []).length > 0,
       criteriaMapping: (control.requirementIds || []).length > 0,
-      ...(queueSchedules.length ? {
-        workQueue: queueSchedules.every((obligation) => obligationIsRunning(obligation, byId, asOf))
+      ...(["scheduled", "event-driven", "mixed"].includes(control.operationPattern) ? {
+        workQueue: queueSchedules.length > 0
+          && queueSchedules.every((obligation) => obligationIsRunning(obligation, byId, asOf))
       } : {})
     };
     const missing = Object.entries(checks).filter(([, value]) => !value).map(([name]) => controlCheckLabel(name));
@@ -375,36 +405,68 @@ async function controlsStage(scope, byId, readMarkdown, asOf) {
       }
     ));
   }
-  return stage("controls", "Implement Controls", "Each implemented control needs an owner, actual procedure, scope, cadence, evidence source, mappings, an implementation date, and any linked Work Queue schedules running.", items);
+  return stage("controls", "Implement Controls", "Each implemented control needs an owner, actual procedure, scope, operation pattern, evidence source, mappings, an implementation date, and any required Work Queue schedules running.", items);
 }
 
 async function evidenceSourcesStage(scope, byId, model, readMarkdown) {
-  const families = selectedControlFamilies(scope.controls, model).filter(requiresCollectionTest);
+  const families = selectedControlFamilies(scope.controls, model);
   const items = [];
   for (const family of families) {
     const selectedSources = [...new Set(family.controls.flatMap((control) => control.evidenceSourceIds || []))]
       .map((id) => byId.get(id))
       .filter((record) => record?.type === "system");
     const completeSources = [];
+    const sourceSystemChecks = [];
     for (const source of selectedSources) {
       const instructions = await readMarkdown(source);
       const matchesRole = !family.sourceKinds.length
         || family.sourceKinds.some((kind) => (source.evidenceSourceKinds || []).includes(kind));
-      if (
-        source.status === "active"
-        && matchesRole
-        && (source.evidenceSourceKinds || []).length
-        && (source.evidenceOwnerIds || []).length
-        && substantiveMarkdown(instructions)
-        && openPlaceholderCount(instructions) === 0
-      ) {
+      const checks = {
+        active: source.status === "active",
+        sourceRole: matchesRole && (source.evidenceSourceKinds || []).length > 0,
+        accessOwners: (source.evidenceOwnerIds || []).length > 0,
+        retrievalInstructions: substantiveMarkdown(instructions) && openPlaceholderCount(instructions) === 0
+      };
+      const complete = Object.values(checks).every(Boolean);
+      sourceSystemChecks.push({
+        sourceSystemId: source.id,
+        complete,
+        checks
+      });
+      if (complete) {
         completeSources.push(source);
       }
     }
-    const coveredControls = family.controls.filter((control) => (
-      (control.evidenceSourceIds || []).some((id) => completeSources.some((source) => source.id === id))
-    ));
+    const controlMappings = family.controls.map((control) => {
+      const sourceSystemIds = (control.evidenceSourceIds || []).filter((id) => selectedSources.some((source) => source.id === id));
+      const completeSourceSystemIds = sourceSystemIds.filter((id) => completeSources.some((source) => source.id === id));
+      return {
+        controlId: control.id,
+        sourceSystemIds,
+        completeSourceSystemIds,
+        mapped: sourceSystemIds.length > 0,
+        complete: completeSourceSystemIds.length > 0
+      };
+    });
+    const coveredControls = controlMappings.filter(({ complete }) => complete);
     const complete = completeSources.length > 0 && coveredControls.length === family.controls.length;
+    const commands = [
+      ...(selectedSources.length
+        ? sourceSystemChecks.filter(({ complete: sourceComplete }) => !sourceComplete).flatMap(({ sourceSystemId }) => [
+            `npx filegrc get ${shellArgument(sourceSystemId)} --mutation > /tmp/${shellArgument(sourceSystemId)}.json`,
+            `npx filegrc update system ${shellArgument(sourceSystemId)} /tmp/${shellArgument(sourceSystemId)}.json --json`
+          ])
+        : [
+            "npx filegrc list system --json",
+            'npx filegrc scaffold system --title "SYSTEM NAME" > /tmp/filegrc-system.json',
+            "npx filegrc create /tmp/filegrc-system.json --json"
+          ]),
+      ...controlMappings.filter(({ mapped }) => !mapped).flatMap(({ controlId }) => [
+        `npx filegrc get ${shellArgument(controlId)} --mutation > /tmp/${shellArgument(controlId)}.json`,
+        `npx filegrc update control ${shellArgument(controlId)} /tmp/${shellArgument(controlId)}.json --json`
+      ]),
+      "npx filegrc program-readiness --json"
+    ];
     items.push(item(
       `source-family-${family.id}`,
       complete ? "complete" : "action",
@@ -413,57 +475,27 @@ async function evidenceSourcesStage(scope, byId, model, readMarkdown) {
         ? `${completeSources.map((source) => source.title).join(", ")} cover all ${family.controls.length} selected controls and record access owners and extraction instructions.`
         : `${coveredControls.length} of ${family.controls.length} selected controls have an active authoritative system with the required source role, access owners, and extraction instructions.`,
       completeSources[0] || selectedSources[0] || { type: "system" },
-      { controlIds: family.controls.map((control) => control.id), sourceSystemIds: selectedSources.map((source) => source.id) }
-    ));
-  }
-  return stage("sources", "Configure Evidence Sources", "Catalog the authoritative systems, name who can export from them, and write repeatable extraction instructions.", items);
-}
-
-function evidenceCollectionStage(scope, records, byId, model) {
-  const families = selectedControlFamilies(scope.controls, model).filter(requiresCollectionTest);
-  const captures = records.filter((record) => (
-    record.type === "evidence"
-    && TEST_EVIDENCE_KINDS.has(record.evidenceKind)
-  ));
-  const items = families.map((family) => {
-    const configuredSourceIds = new Set(family.controls.flatMap((control) => control.evidenceSourceIds || []));
-    const controlIds = new Set(family.controls.map((control) => control.id));
-    const capture = captures.find((record) => record.collectionTestFamilyId === family.id)
-      || captures.find((record) => (
-        [...controlIdsForRecord(record, byId)].some((id) => controlIds.has(id))
-      ));
-    const sourceIds = new Set([
-      ...configuredSourceIds,
-      ...(capture?.sourceSystemId ? [capture.sourceSystemId] : [])
-    ]);
-    const verified = capture?.status === "verified";
-    return item(
-      `test-family-${family.id}`,
-      verified ? "complete" : "action",
-      family.title,
-      verified
-        ? `${capture.title} proves that management successfully captured and verified evidence from ${byId.get(capture.sourceSystemId)?.title || "the authoritative source"}.`
-        : capture?.status === "draft"
-          ? `${capture.title} is a draft. Open it, select the authoritative source System, collect the named artifact, and have another person verify it.`
-          : capture
-            ? `${capture.title} is ${capture.status} but must be verified before this family is ready.`
-          : `Run and verify one test export or test capture from an authoritative source outside filegrc, then link it to a family control.`,
-      capture || { type: "evidence" },
       {
         familyId: family.id,
-        controlIds: [...controlIds],
-        sourceSystemIds: [...sourceIds],
-        evidenceId: capture?.id || null,
-        evidenceStatus: capture?.status || null,
-        testEvidenceKind: family.testEvidenceKind,
-        testPrompt: family.testPrompt
+        sourceKinds: family.sourceKinds,
+        controlIds: family.controls.map((control) => control.id),
+        sourceSystemIds: selectedSources.map((source) => source.id),
+        completeSourceSystemIds: completeSources.map((source) => source.id),
+        sourceSystemChecks,
+        controlMappings,
+        evidenceForm: family.evidenceForm,
+        evidencePrompt: family.evidencePrompt,
+        description: family.description,
+        timing: family.timing,
+        operationRecordTypes: family.operationRecordTypes,
+        commands
       }
-    );
-  });
-  return stage("collection", "Test Evidence Collection", "A verified test export or capture is required for each external evidence family that does not already have a dedicated Step 5 operating record.", items);
+    ));
+  }
+  return stage("sources", "Control Evidence Sources", "Complete the authoritative Systems for every selected control family before marking the Controls implemented.", items);
 }
 
-function operationStage(workspace, scope, records, byId, asOf, evidenceReady) {
+function operationStage(workspace, scope, records, byId, asOf, evidenceReady, model) {
   const goal = workspace?.assuranceGoal || "none";
   if (!evidenceReady) {
     return stage("operation", "Operate the Program", "Run the controls and preserve dated evidence after the Evidence Ready gate passes.", [
@@ -471,13 +503,15 @@ function operationStage(workspace, scope, records, byId, asOf, evidenceReady) {
         "operation-later",
         "later",
         "Begin reliable evidence collection",
-        "Finish scope, policy adoption, control implementation, source configuration, and test captures before recording the candidate period.",
+        "Finish scope, policy adoption, and control implementation, including complete authoritative evidence sources, before recording the candidate period.",
         workspace || { type: "workspace" }
       )
     ]);
   }
   if (goal !== "soc-2-type-2") {
-    const date = workspace?.candidateTypeOneAsOf;
+    const date = workspace?.candidateCoverage?.kind === "as-of"
+      ? workspace.candidateCoverage.on
+      : null;
     return stage("operation", "Operate the Program", "Run the controls and preserve dated evidence before engaging the CPA firm.", [
       item(
         "candidate-type-one-date",
@@ -492,9 +526,13 @@ function operationStage(workspace, scope, records, byId, asOf, evidenceReady) {
     ]);
   }
 
-  const obligations = planObligations(records, { asOf, through: asOf });
-  const start = workspace.candidatePeriodStart;
-  const end = workspace.candidatePeriodEnd;
+  const obligations = planObligations(records, { asOf, through: asOf, model });
+  const start = workspace.candidateCoverage?.kind === "range"
+    ? coverageStart(workspace.candidateCoverage)
+    : null;
+  const end = workspace.candidateCoverage?.kind === "range"
+    ? coverageEnd(workspace.candidateCoverage)
+    : null;
   const startStatus = !start ? "action" : start <= asOf ? "complete" : "later";
   return stage("operation", "Operate the Program", "Start the management candidate Type 2 period only after the Evidence Ready gate, then keep collection running.", [
     item(
@@ -536,7 +574,7 @@ function riskAssessmentItem(scope, records, byId, asOf) {
     && record.status === "complete"
     && record.methodology
     && record.approvedOn
-    && record.assessmentDate >= shiftYear(asOf, -1)
+    && record.completedOn >= shiftYear(asOf, -1)
     && partiesIndependent(record.assessorIds, record.reviewerIds, byId)
     && (!scope.systems.length || !(record.systemIds || []).length || record.systemIds.some((id) => scope.systems.some((system) => system.id === id)))
   ));
@@ -562,9 +600,10 @@ export function selectedControlFamilies(controls, model) {
       id: definition.id,
       title: definition.title,
       sourceKinds: definition.sourceKinds || [],
-      testEvidenceKind: definition.testEvidenceKind || "test-capture",
-      testPrompt: definition.testPrompt || `Capture usable evidence for ${definition.title.toLowerCase()}.`,
-      collectionTestRequired: definition.collectionTestRequired !== false,
+      evidenceForm: definition.evidenceForm || "capture",
+      evidencePrompt: definition.evidencePrompt || `Retain usable evidence for ${definition.title.toLowerCase()}.`,
+      description: definition.description || "",
+      timing: definition.timing || "",
       operationRecordTypes: definition.operationRecordTypes || [],
       controls: selected
     });
@@ -586,9 +625,10 @@ export function selectedControlFamilies(controls, model) {
       id: `control-${prefix}`,
       title,
       sourceKinds: [],
-      testEvidenceKind: "test-capture",
-      testPrompt: `Capture usable evidence for the selected ${title.toLowerCase()} controls.`,
-      collectionTestRequired: true,
+      evidenceForm: "capture",
+      evidencePrompt: `Retain usable evidence for the selected ${title.toLowerCase()} controls.`,
+      description: `Record the authoritative Systems that produce evidence for the selected ${title.toLowerCase()} controls.`,
+      timing: "Map the source and document repeatable retrieval before program operation begins.",
       operationRecordTypes: [],
       controls: selected
     });
@@ -596,10 +636,6 @@ export function selectedControlFamilies(controls, model) {
   return families;
 }
 
-function requiresCollectionTest(family) {
-  return family.collectionTestRequired !== false;
-}
-
 async function primaryMarkdown(loaded, record) {
   const definition = loaded.model.resources[record.type];
   const selected = markdownEntries(loaded.model, record).find((entry) => (
@@ -657,7 +693,7 @@ function controlCheckLabel(name) {
     owner: "owner",
     procedure: "actual procedure in Record Markdown",
     scope: "in-scope systems",
-    cadence: "cadence",
+    operationPattern: "operation pattern",
     evidenceSource: "authoritative evidence source",
     implementationDate: "implementation date",
     policyMapping: "policy mapping",

package/src/resource-status.js

@@ -0,0 +1,17 @@
+export function effectiveResourceStatus(record, asOf) {
+  if (
+    record?.type === "attestation"
+    && record.status === "pending"
+    && record.dueOn
+    && asOf
+    && record.dueOn < asOf
+  ) return "overdue";
+  if (
+    record?.type === "evidence"
+    && ["collected", "verified"].includes(record.status)
+    && record.expiresOn
+    && asOf
+    && record.expiresOn < asOf
+  ) return "expired";
+  return record?.status;
+}