filegrc 0.7.1 → 0.9.0

package/src/model-migration.js

@@ -1,5 +1,5 @@
 import { createResourceId } from "./id.js";
-import { applyResourceBatch, contentRevision } from "./files.js";
+import { applyModelMigrationBatch, applyResourceBatch, contentRevision } from "./files.js";
 import { loadWorkspace } from "./workspace.js";
 import { ACTIVE_MODEL_VERSION, loadModel } from "../model/index.js";
 import { legacyCoverage } from "./coverage.js";
@@ -882,7 +882,7 @@ async function migrateV1ToV2(input = process.cwd(), options = {}) {
       + "and resolve every missing value, conflict, and manual action."
     );
   }
-  const result = await applyResourceBatch(input, plan.changes);
+  const result = await applyModelMigrationBatch(input, plan.changes);
   return { ...plan, applied: true, result };
 }
 
@@ -891,7 +891,11 @@ export async function planModelMigration(input = process.cwd(), options = {}) {
   const sourceVersion = String(loaded.workspace?.dataModelVersion || "");
   const requestedTarget = options.targetModelVersion
     ? String(options.targetModelVersion)
-    : sourceVersion === "1" ? V1_TARGET_MODEL_VERSION : sourceVersion === "2" ? "3" : ACTIVE_MODEL_VERSION;
+    : sourceVersion === "1" ? V1_TARGET_MODEL_VERSION
+      : sourceVersion === "2" ? "3"
+        : sourceVersion === "3" ? "4"
+          : sourceVersion === "4" ? "5"
+            : ACTIVE_MODEL_VERSION;
   if (sourceVersion === requestedTarget) return emptyPlan(sourceVersion, requestedTarget);
   if (sourceVersion === "1" && requestedTarget === "2") {
     return planV1ToV2Migration(input, options);
@@ -899,13 +903,19 @@ export async function planModelMigration(input = process.cwd(), options = {}) {
   if (sourceVersion === "2" && requestedTarget === "3") {
     return planV2ToV3Migration(loaded);
   }
-  if (sourceVersion === "3" && requestedTarget === ACTIVE_MODEL_VERSION) {
+  if (sourceVersion === "3" && requestedTarget === "4") {
     return planV3ToV4Migration(loaded, options);
   }
+  if (sourceVersion === "4" && requestedTarget === "5") {
+    return planV4ToV5Migration(loaded, options);
+  }
+  if (sourceVersion === "5" && requestedTarget === ACTIVE_MODEL_VERSION) {
+    return planV5ToV6Migration(loaded);
+  }
   if (sourceVersion === "1" && requestedTarget === ACTIVE_MODEL_VERSION) {
     throw new Error(
       "Model v1 workspaces must migrate to model v2 first. "
-      + "Preview and apply `npx filegrc migrate --to-model 2`, then migrate to model v3 and v4."
+      + "Preview and apply `npx filegrc migrate --to-model 2`, then migrate one version at a time through model v6."
     );
   }
   throw new Error(`Model migration does not support v${sourceVersion} to v${requestedTarget}.`);
@@ -925,7 +935,7 @@ export async function migrateModel(input = process.cwd(), options = {}) {
   if (plan.sourceModelVersion === "1" && plan.targetModelVersion === "2") {
     return migrateV1ToV2(input, options);
   }
-  const result = await applyResourceBatch(input, plan.changes);
+  const result = await applyModelMigrationBatch(input, plan.changes);
   return {
     ...plan,
     applied: true,
@@ -1498,6 +1508,352 @@ async function planV3ToV4Migration(loaded, options = {}) {
   };
 }
 
+async function planV4ToV5Migration(loaded, options = {}) {
+  if (!loaded.workspace?.id) throw new Error("Model migration requires a valid Workspace record.");
+  const targetModel = loadModel("5");
+  const revisions = new Map(loaded.entries.map((entry) => [entry.record.id, contentRevision(entry.source)]));
+  const automatic = [];
+  const reviewRequired = [];
+  const unsupported = [];
+  const missing = [];
+  const manualActions = [];
+  const updates = [];
+  const documentScopeDecisions = options.documentScopes && typeof options.documentScopes === "object"
+    ? options.documentScopes
+    : {};
+  const auditDocumentFields = [
+    "engagementTermsDocumentId",
+    ...(targetModel.auditReadiness?.managementDocuments || []).map(({ field }) => field)
+  ];
+  const auditsByDocumentId = new Map();
+  const allAuditsByDocumentId = new Map();
+  const addAuditReference = (map, documentId, audit) => {
+    if (!documentId) return;
+    if (!map.has(documentId)) map.set(documentId, new Map());
+    map.get(documentId).set(audit.id, audit);
+  };
+  for (const audit of loaded.resources.filter(({ type }) => type === "audit")) {
+    for (const field of auditDocumentFields) {
+      const documentId = audit[field];
+      if (!documentId) continue;
+      addAuditReference(auditsByDocumentId, documentId, audit);
+      addAuditReference(allAuditsByDocumentId, documentId, audit);
+    }
+    for (const documentId of audit.supplementalDocumentIds || []) {
+      addAuditReference(allAuditsByDocumentId, documentId, audit);
+    }
+  }
+  const programDocumentIds = new Set([
+    ...loaded.resources.filter(({ type }) => type === "policy").flatMap(({ relatedDocumentIds }) => relatedDocumentIds || []),
+    ...loaded.resources.filter(({ type }) => type === "obligation").flatMap((record) => [
+      ...(record.scopeResourceIds || []),
+      ...(record.templateResourceId ? [record.templateResourceId] : [])
+    ])
+  ]);
+  const auditDocumentKinds = new Set([
+    ...(targetModel.auditReadiness?.managementDocuments || []).map(({ kind }) => kind),
+    "soc2-engagement-terms"
+  ]);
+  const resetDocumentIds = [];
+  const legacyDocumentIds = [];
+  const documentIds = new Set(loaded.resources.filter(({ type }) => type === "document").map(({ id }) => id));
+
+  for (const documentId of Object.keys(documentScopeDecisions)) {
+    if (!documentIds.has(documentId)) {
+      unsupported.push(classifiedChange(
+        "unsupported",
+        documentId,
+        "workflowScope",
+        `Document scope decision "${documentId}" does not match a Document in this workspace.`
+      ));
+    }
+  }
+
+  for (const original of loaded.resources) {
+    if (original.type === "workspace") {
+      updates.push({ ...original, dataModelVersion: "5" });
+      automatic.push(classifiedChange(
+        "automatic",
+        original.id,
+        "dataModelVersion",
+        "Select model v5 and enable the separate governed Document approval and activation lifecycle."
+      ));
+      continue;
+    }
+    if (original.type !== "document") continue;
+    const governedAuditReferences = [...(auditsByDocumentId.get(original.id)?.values() || [])];
+    const auditReferences = [...(allAuditsByDocumentId.get(original.id)?.values() || [])];
+    const explicitScope = normalizeDocumentScopeDecision(documentScopeDecisions[original.id]);
+    if (Object.hasOwn(documentScopeDecisions, original.id) && !explicitScope) {
+      unsupported.push(classifiedChange(
+        "unsupported",
+        original.id,
+        "workflowScope",
+        `Document scope decision for "${original.id}" must be "program" or "engagement".`
+      ));
+    }
+    const engagementSignal = governedAuditReferences.length > 0 || auditDocumentKinds.has(original.documentKind);
+    const programSignal = programDocumentIds.has(original.id);
+    if (!explicitScope && engagementSignal && programSignal) {
+      unsupported.push(classifiedChange(
+        "unsupported",
+        original.id,
+        "workflowScope",
+        `Document "${original.title}" is linked to both program governance and an Audit. Choose program or engagement in documentScopes.${original.id}.`
+      ));
+    }
+    const workflowScope = explicitScope || (engagementSignal && !programSignal ? "engagement" : "program");
+    const record = { ...original, workflowScope };
+    if (workflowScope === "engagement") delete record.programRole;
+    automatic.push(classifiedChange(
+      "automatic",
+      original.id,
+      "workflowScope",
+      explicitScope
+        ? `Use the reviewed ${workflowScope} workflow scope.`
+        : `Classify this Document as ${workflowScope} from its model kind and authoritative relationships.`
+    ));
+    const historicalEngagement = workflowScope === "engagement" && auditReferences.some(({ status }) => (
+      ["issued", "delivered", "complete"].includes(status)
+    ));
+    if (["superseded", "retired"].includes(record.status)) {
+      if (historicalEngagement) {
+        record.activationBasis = "legacy-v4";
+        legacyDocumentIds.push(record.id);
+      } else delete record.activationBasis;
+      delete record.activatedOn;
+      delete record.activatedByIds;
+      delete record.activatedContentRevisions;
+    } else if (record.status === "active" && historicalEngagement) {
+      record.activationBasis = "legacy-v4";
+      delete record.activatedOn;
+      delete record.activatedByIds;
+      delete record.activatedContentRevisions;
+      legacyDocumentIds.push(record.id);
+      reviewRequired.push(classifiedChange(
+        "review-required",
+        record.id,
+        "activationBasis",
+        "Preserve this historical engagement Document as active with a visible legacy-v4 basis. Model v4 recorded one combined approval and activation state, so the migration does not invent an activation date, actor, or second revision."
+      ));
+    } else if (record.status === "active") {
+      record.status = "approved";
+      if (record.effectiveOn) record.proposedEffectiveOn = record.effectiveOn;
+      delete record.effectiveOn;
+      delete record.activationBasis;
+      delete record.activatedOn;
+      delete record.activatedByIds;
+      delete record.activatedContentRevisions;
+      resetDocumentIds.push(record.id);
+      reviewRequired.push(classifiedChange(
+        "review-required",
+        record.id,
+        "status",
+        workflowScope === "engagement"
+          ? "Model v4 recorded one combined approval and activation state. Preserve the approval and approved revision, then record a separate Step 5 activation after confirming the current engagement facts."
+          : "Model v4 recorded one combined approval and activation state. Preserve the approval and approved revision, confirm the linked requirements, then record a separate Step 3 activation."
+      ));
+    }
+    updates.push(record);
+  }
+
+  const updatedById = new Map(updates.map((record) => [record.id, record]));
+  const migratedRecords = loaded.resources.map((record) => updatedById.get(record.id) || record);
+  await collectTargetValidationActions(loaded, migratedRecords, targetModel, missing, manualActions);
+  for (const item of [...missing, ...manualActions]) {
+    unsupported.push(classifiedChange(
+      "unsupported",
+      item.resourceId,
+      item.field,
+      item.message || `Resolve ${item.field} before applying the model v5 migration.`
+    ));
+  }
+  const ready = unsupported.length === 0;
+  return {
+    schemaVersion: 2,
+    sourceModelVersion: "4",
+    targetModelVersion: "5",
+    ready,
+    missing,
+    conflicts: [],
+    manualActions,
+    classifications: { automatic, reviewRequired, unsupported },
+    notes: reviewRequired,
+    migrationReport: {
+      resetDocumentIds,
+      legacyDocumentIds
+    },
+    summary: {
+      create: 0,
+      update: updates.length,
+      automatic: automatic.length,
+      reviewRequired: reviewRequired.length,
+      unsupported: unsupported.length
+    },
+    fileDiff: {
+      create: [],
+      update: updates.map((record) => ({
+        type: record.type,
+        id: record.id,
+        before: loaded.resources.find(({ id }) => id === record.id),
+        after: record
+      }))
+    },
+    changes: {
+      create: [],
+      update: updates,
+      expectedRevisions: Object.fromEntries(updates.map(({ id }) => [id, revisions.get(id)])),
+      validateWholeWorkspace: true,
+      targetModelVersion: "5"
+    }
+  };
+}
+
+async function planV5ToV6Migration(loaded) {
+  if (!loaded.workspace?.id) throw new Error("Model migration requires a valid Workspace record.");
+  const targetModel = loadModel("6");
+  const revisions = new Map(loaded.entries.map((entry) => [entry.record.id, contentRevision(entry.source)]));
+  const automatic = [];
+  const reviewRequired = [];
+  const unsupported = [];
+  const missing = [];
+  const manualActions = [];
+  const updates = [];
+  const legacyTrainingIds = [];
+  const removedTrainingScheduleFields = [];
+  const obligations = loaded.resources.filter(({ type }) => type === "obligation");
+
+  for (const original of loaded.resources) {
+    if (original.type === "workspace") {
+      updates.push({ ...original, dataModelVersion: "6" });
+      automatic.push(classifiedChange(
+        "automatic",
+        original.id,
+        "dataModelVersion",
+        "Select model v6 and enable separate Training approval and activation."
+      ));
+      continue;
+    }
+    if (original.type !== "training") continue;
+    const record = { ...original };
+    if (record.approvedByIds) {
+      record.approverIds = record.approvedByIds;
+      delete record.approvedByIds;
+      automatic.push(classifiedChange(
+        "automatic",
+        record.id,
+        "approverIds",
+        "Use the common governed-content approver field."
+      ));
+    }
+    if (record.effectiveContentRevisions) {
+      record.approvedContentRevisions = record.effectiveContentRevisions;
+      delete record.effectiveContentRevisions;
+      automatic.push(classifiedChange(
+        "automatic",
+        record.id,
+        "approvedContentRevisions",
+        "Preserve the exact Training revision previously bound to approval and activation as the approved revision."
+      ));
+    }
+    const removedSchedule = {};
+    for (const field of ["assignmentTrigger", "completionWindowDays"]) {
+      if (record[field] === undefined) continue;
+      removedSchedule[field] = record[field];
+      delete record[field];
+    }
+    if (Object.keys(removedSchedule).length) {
+      const obligationIds = obligations.filter((obligation) => (
+        obligation.templateResourceId === record.id
+        || (obligation.scopeResourceIds || []).includes(record.id)
+      )).map(({ id }) => id);
+      removedTrainingScheduleFields.push({ trainingId: record.id, values: removedSchedule, obligationIds });
+      reviewRequired.push(classifiedChange(
+        "review-required",
+        record.id,
+        "assignmentSchedule",
+        `Training assignment schedules now belong only in Obligations. Confirm the removed ${Object.keys(removedSchedule).join(" and ")} values against ${obligationIds.length ? obligationIds.join(", ") : "a new Step 3 Obligation"}.`
+      ));
+    }
+    if (record.status === "draft" && record.effectiveOn) {
+      record.proposedEffectiveOn = record.effectiveOn;
+      delete record.effectiveOn;
+      reviewRequired.push(classifiedChange(
+        "review-required",
+        record.id,
+        "proposedEffectiveOn",
+        "Keep the draft Training date as proposed until the approved revision is activated in Step 3."
+      ));
+    }
+    if (["active", "retired"].includes(record.status) && record.approvedContentRevisions) {
+      record.activationBasis = "legacy-v5";
+      legacyTrainingIds.push(record.id);
+      reviewRequired.push(classifiedChange(
+        "review-required",
+        record.id,
+        "activationBasis",
+        "Preserve the combined model v5 Training approval and activation as legacy-v5. The migration does not invent a separate activation actor, date, or revision."
+      ));
+    }
+    updates.push(record);
+  }
+
+  const updatedById = new Map(updates.map((record) => [record.id, record]));
+  const migratedRecords = loaded.resources.map((record) => updatedById.get(record.id) || record);
+  await collectTargetValidationActions(loaded, migratedRecords, targetModel, missing, manualActions);
+  for (const item of [...missing, ...manualActions]) {
+    unsupported.push(classifiedChange(
+      "unsupported",
+      item.resourceId,
+      item.field,
+      item.message || `Resolve ${item.field} before applying the model v6 migration.`
+    ));
+  }
+  const ready = unsupported.length === 0;
+  return {
+    schemaVersion: 2,
+    sourceModelVersion: "5",
+    targetModelVersion: "6",
+    ready,
+    missing,
+    conflicts: [],
+    manualActions,
+    classifications: { automatic, reviewRequired, unsupported },
+    notes: reviewRequired,
+    migrationReport: { legacyTrainingIds, removedTrainingScheduleFields },
+    summary: {
+      create: 0,
+      update: updates.length,
+      automatic: automatic.length,
+      reviewRequired: reviewRequired.length,
+      unsupported: unsupported.length
+    },
+    fileDiff: {
+      create: [],
+      update: updates.map((record) => ({
+        type: record.type,
+        id: record.id,
+        before: loaded.resources.find(({ id }) => id === record.id),
+        after: record
+      }))
+    },
+    changes: {
+      create: [],
+      update: updates,
+      expectedRevisions: Object.fromEntries(updates.map(({ id }) => [id, revisions.get(id)])),
+      validateWholeWorkspace: true,
+      targetModelVersion: "6"
+    }
+  };
+}
+
+function normalizeDocumentScopeDecision(value) {
+  const candidate = typeof value === "object" && value
+    ? value.workflowScope || value.scope
+    : value;
+  return ["program", "engagement"].includes(candidate) ? candidate : null;
+}
+
 async function collectTargetValidationActions(loaded, records, model, missing, manualActions) {
   const { validateWorkspace } = await import("./validate.js");
   const existingById = new Map(loaded.entries.map((entry) => [entry.record.id, entry]));
@@ -2003,7 +2359,7 @@ function migrateInverseArrays(resources, byId, editable, conflicts, mapping) {
 }
 
 function emptyPlan(version, targetVersion = V1_TARGET_MODEL_VERSION) {
-  const classifiedPlan = ["3", "4"].includes(String(targetVersion));
+  const classifiedPlan = Number(targetVersion) >= 3;
   const includesPathMoves = String(targetVersion) === "4";
   return {
     schemaVersion: classifiedPlan ? 2 : 1,

package/src/obligations.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { scaffoldResourceMutation } from "./agent.js";
 import { createResourceId } from "./id.js";
 import { createResourceAndLink, createResources, updateResource } from "./files.js";
-import { loadModel } from "../model/index.js";
+import { loadModel, modelSupports } from "../model/index.js";
 import { coverageEnd } from "./coverage.js";
 import {
   addCalendarDays,
@@ -14,7 +14,7 @@ import {
 } from "./recurrence.js";
 import { currentCalendarDate, isRfc3339Timestamp } from "./time.js";
 import { loadWorkspace } from "./workspace.js";
-import { obligationProgramStatus } from "./program-lifecycle.js";
+import { obligationGovernedContent, obligationProgramStatus } from "./program-lifecycle.js";
 import { resolveProgram } from "./program.js";
 
 const COMPLETION_DATE_FIELDS = [
@@ -75,7 +75,7 @@ export function planObligations(resources, options = {}) {
   for (const obligation of obligations) {
     const activity = obligationActivity(model, obligation.activityType);
     const expectedCompletionTypes = activity.completionResourceTypes;
-    const programStatus = obligationProgramStatus(obligation, byId, asOf);
+    const programStatus = obligationProgramStatus(obligation, byId, asOf, model);
     if (obligation.recurrence?.mode === "event" && obligation.recurrence.eventType) {
       const eventType = obligation.recurrence.eventType;
       const group = triggerGroups.get(eventType) ?? {
@@ -111,7 +111,7 @@ export function planObligations(resources, options = {}) {
     }
 
     const configuredAnchor = obligation.recurrence?.anchorDate || obligation.startsOn;
-    const activationDate = obligationActivationDate(obligation, byId);
+    const activationDate = obligationActivationDate(obligation, byId, model);
     const recurrence = {
       ...(obligation.recurrence || {}),
       anchorDate: configuredAnchor && activationDate
@@ -258,8 +258,8 @@ export async function createObligationEvent(input, options) {
     )
   ));
   if (!eventType || templates.length === 0) throw new Error(`No active obligations use event type "${eventType}".`);
-  if (templates.some((record) => obligationProgramStatus(record, byId, occurredOn) === "proposed")) {
-    throw new Error(`Event type "${eventType}" still has starter proposals. Make every governing policy effective and implement at least one linked control before starting this workflow.`);
+  if (templates.some((record) => obligationProgramStatus(record, byId, occurredOn, loaded.model) === "proposed")) {
+    throw new Error(`Event type "${eventType}" still has starter proposals. Make every governing Policy and required governed-content record active and effective, then implement at least one linked Control before starting this workflow.`);
   }
   if (templates.some((record) => normalizedEventWindow(record.window).precision === "timestamp") && !occurredAt) {
     throw new Error(`Event type "${eventType}" has hour-based deadlines and requires an RFC 3339 occurredAt timestamp.`);
@@ -720,7 +720,7 @@ function completionTeam(resources, ownerIds) {
 }
 
 function defaultClassificationId(loaded) {
-  if (String(loaded.model.modelVersion) === "4") {
+  if (modelSupports(loaded.model, "program-scope")) {
     return loaded.resources.find(({ type, id, status }) => type === "classification" && id === "internal" && status === "active")?.id
       || loaded.resources.find(({ type, status }) => type === "classification" && status === "active")?.id
       || "";
@@ -792,7 +792,7 @@ function planEventRun(event, actionItems, byId, asOf, now, model) {
       const completionProfile = obligation?.type === "obligation"
         ? obligationActivity(model, obligation.activityType).completionProfile || null
         : null;
-      const completionIds = ["3", "4"].includes(String(model.modelVersion))
+      const completionIds = modelSupports(model, "guided-workflow")
         ? record.completionResourceIds || []
         : [...(record.completionResourceIds || []), ...(record.evidenceIds || [])];
       const linkedCompletionIds = [...new Set(completionIds)];
@@ -991,13 +991,16 @@ function occurrenceStatus(window, asOf, complete) {
   return "upcoming";
 }
 
-function obligationActivationDate(obligation, byId) {
-  const dates = (obligation.policyIds || [])
+function obligationActivationDate(obligation, byId, model) {
+  const policyDates = (obligation.policyIds || [])
     .map((id) => byId.get(id))
     .filter((policy) => policy?.type === "policy")
     .map((policy) => policy.effectiveOn)
     .filter(Boolean);
-  return dates.sort().at(-1) || null;
+  const governedContentDates = obligationGovernedContent(obligation, byId, model)
+    .map((record) => record.effectiveOn)
+    .filter(Boolean);
+  return [...policyDates, ...governedContentDates].sort().at(-1) || null;
 }
 
 function relativeTiming(window, asOf) {

package/src/policy-library.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
+import { modelSupports } from "../model/index.js";
 import { applyResourceBatch, contentRevision } from "./files.js";
 import { serializeWorkspaceMutation } from "./mutation.js";
 import { resolveDataPath } from "./paths.js";
@@ -514,8 +515,11 @@ async function buildPolicyLibraryPlan(loaded) {
     const source = await readResourceSource(loaded, TRAINING_CONTENT_PATH);
     const rawSourceRevision = contentRevision(source);
     const sourceRevision = normalizedTrainingRevision(source, loaded.workspace?.organizationName);
-    if (["active", "retired"].includes(trainingEntry.record.status)) {
-      skipped.push(skippedItem(TRAINING_ID, "adopted", "Active and retired Training content is never changed by a starter-library proposal."));
+    const adoptedStatuses = modelSupports(loaded.model, "governed-training-activation")
+      ? ["approved", "active", "superseded", "retired"]
+      : ["active", "retired"];
+    if (adoptedStatuses.includes(trainingEntry.record.status)) {
+      skipped.push(skippedItem(TRAINING_ID, "adopted", "Approved, active, superseded, and retired Training content is never changed by a starter-library proposal."));
     } else if (sourceRevision === CURRENT_TRAINING_REVISION) {
       skipped.push(skippedItem(TRAINING_ID, "current", "The Security Awareness Training already contains the current starter language."));
     } else if (!PRIOR_TRAINING_REVISIONS.has(sourceRevision)) {
@@ -658,7 +662,7 @@ async function buildPolicyLibraryPlan(loaded) {
     });
   }
 
-  for (const addition of String(loaded.model.modelVersion) === "4" ? OBLIGATION_ADDITIONS : []) {
+  for (const addition of modelSupports(loaded.model, "program-scope") ? OBLIGATION_ADDITIONS : []) {
     if (byId.has(addition.id)) {
       skipped.push(skippedItem(addition.id, "present", "An Obligation with this ID already exists, so FileGRC will not replace it."));
       continue;