filegrc 0.6.4 → 0.7.0

package/src/batch-review.js

@@ -1,7 +1,13 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
 import { applyResourceBatch } from "./files.js";
-import { getGitSummary } from "./git.js";
-import { loadWorkspace } from "./workspace.js";
+import { getWorkspaceRevisionSnapshot } from "./git.js";
+import { serializeWorkspaceMutation } from "./mutation.js";
+import { resolveDataPath } from "./paths.js";
 import { resolveProgram } from "./program.js";
+import { markdownEntries } from "./resource-markdown.js";
+import { assessWorkflow, buildWorkflowDelta } from "./workflow.js";
+import { loadWorkspace } from "./workspace.js";
 
 const REVIEWABLE_TYPES = new Set([
   "requirement",
@@ -11,7 +17,8 @@ const REVIEWABLE_TYPES = new Set([
 ]);
 
 export async function scaffoldApplicabilityReview(input = process.cwd(), options = {}) {
-  const loaded = await loadWorkspace(input);
+  const context = await applicabilityReviewContext(input);
+  const { loaded } = context;
   if (!["3", "4"].includes(String(loaded.model.modelVersion))) {
     throw new Error("Batch applicability review requires a model v3 or v4 workspace.");
   }
@@ -32,6 +39,7 @@ export async function scaffoldApplicabilityReview(input = process.cwd(), options
     && !["retired", "superseded"].includes(record.status)
   ));
   return {
+    basis: context.basis,
     reviewedByIds: [],
     reviewedOn: null,
     decisions: records
@@ -45,14 +53,25 @@ export async function scaffoldApplicabilityReview(input = process.cwd(), options
 }
 
 export async function planApplicabilityReview(input = process.cwd(), options = {}) {
-  const loaded = await loadWorkspace(input);
+  const context = await applicabilityReviewContext(input);
+  return planApplicabilityReviewWithContext(context, options);
+}
+
+function planApplicabilityReviewWithContext(context, options) {
+  const { basis, loaded } = context;
   if (!["3", "4"].includes(String(loaded.model.modelVersion))) {
     throw new Error("Batch applicability review requires a model v3 or v4 workspace.");
   }
   if (!Array.isArray(options.decisions) || !options.decisions.length) {
     throw new Error("Applicability review needs at least one decision.");
   }
+  if (options.basis !== undefined) assertApplicabilityReviewBasis(options.basis, basis);
   const byId = new Map(loaded.resources.map((record) => [record.id, record]));
+  const revisionById = new Map(loaded.entries.map((entry) => [entry.record.id, entry.revision]));
+  const expectedRevisions = options.expectedRevisions ?? {};
+  if (Array.isArray(expectedRevisions) || typeof expectedRevisions !== "object" || expectedRevisions === null) {
+    throw new Error("Batch expected revisions must be keyed by resource ID.");
+  }
   const program = resolveProgram(loaded, options.programId);
   const v4RequirementDecisions = [];
   const update = options.decisions.flatMap((decision) => {
@@ -62,12 +81,6 @@ export async function planApplicabilityReview(input = process.cwd(), options = {
     }
     const reviewedByIds = [...new Set((decision.reviewedByIds || options.reviewedByIds || []).map(String))];
     const reviewedOn = String(decision.reviewedOn || options.reviewedOn || "").trim();
-    const scopeRevision = String(
-      decision.scopeRevision
-      || options.scopeRevision
-      || getGitSummary(loaded.root).commit
-      || "uncommitted"
-    ).trim();
     const rationale = String(decision.rationale || "").trim();
     const result = String(decision.decision || "").trim();
     if (!["applicable", "not-applicable", "externally-managed", "zero-population"].includes(result)) {
@@ -83,7 +96,7 @@ export async function planApplicabilityReview(input = process.cwd(), options = {
         rationale,
         reviewedByIds,
         reviewedOn,
-        scopeRevision
+        scopeRevision: basis.scopeRevision
       }
     };
     if (record.type === "requirement") {
@@ -91,7 +104,14 @@ export async function planApplicabilityReview(input = process.cwd(), options = {
         throw new Error(`Requirement "${record.id}" must be applicable or not-applicable.`);
       }
       if (String(loaded.model.modelVersion) === "4") {
-        v4RequirementDecisions.push({ requirementId: record.id, decision: result, rationale, reviewedByIds, reviewedOn, scopeRevision });
+        v4RequirementDecisions.push({
+          requirementId: record.id,
+          decision: result,
+          rationale,
+          reviewedByIds,
+          reviewedOn,
+          scopeRevision: basis.scopeRevision
+        });
         return [];
       }
       next.applicability = result;
@@ -113,20 +133,125 @@ export async function planApplicabilityReview(input = process.cwd(), options = {
   }
   return {
     operation: "applicability-review",
+    basis,
     reviewedIds: options.decisions.map(({ id }) => id),
     changes: {
       update,
-      expectedRevisions: options.expectedRevisions || {},
+      expectedRevisions: Object.fromEntries(update.map((record) => [
+        record.id,
+        expectedRevisions[record.id] || revisionById.get(record.id)
+      ])),
       validateWholeWorkspace: true
     }
   };
 }
 
-export async function applyApplicabilityReview(input = process.cwd(), options = {}) {
+export function applyApplicabilityReview(input = process.cwd(), options = {}) {
+  return applyApplicabilityReviewWithContext(input, options);
+}
+
+export async function applyApplicabilityReviewWithContext(input = process.cwd(), options = {}, contextOptions = {}) {
   if (options.confirmed !== true) {
     throw new Error("Preview the applicability decisions and confirm the write.");
   }
-  const plan = await planApplicabilityReview(input, options);
-  const result = await applyResourceBatch(input, plan.changes);
-  return { ...plan, result };
+  return serializeWorkspaceMutation(input, async (root) => {
+    const context = await applicabilityReviewContext(root, contextOptions);
+    if (options.basis === undefined) {
+      throw new Error("Applicability review apply requires the basis returned by scaffold or --preview --json. Generate the decisions again before confirming the write.");
+    }
+    const plan = planApplicabilityReviewWithContext(context, options);
+    const before = contextOptions.includeWorkflowDelta
+      ? await assessWorkflow(context.loaded, { git: workflowGitState(context.repository) })
+      : null;
+    const result = await applyResourceBatch(root, plan.changes);
+    if (!before) return { ...plan, result };
+    const after = await assessWorkflow(result.validation.loaded, {
+      git: workflowGitState(context.repository),
+      validation: result.validation
+    });
+    return {
+      ...plan,
+      result,
+      workflowDelta: buildWorkflowDelta(before, after)
+    };
+  });
+}
+
+async function applicabilityReviewContext(input, options = {}) {
+  const loaded = await loadWorkspace(input);
+  const repository = options.repositorySnapshot ?? await getWorkspaceRevisionSnapshot(loaded.root);
+  return {
+    basis: await applicabilityReviewBasis(loaded, repository),
+    loaded,
+    repository
+  };
+}
+
+function workflowGitState(repository) {
+  return {
+    ...repository,
+    commit: repository.currentCommit ?? repository.commit ?? null
+  };
+}
+
+async function applicabilityReviewBasis(loaded, repository) {
+  const scopeFingerprint = await applicabilityScopeFingerprint(loaded);
+  const commit = repository.currentCommit ?? repository.commit ?? null;
+  const clean = repository.clean === true || repository.wholeWorktreeClean === true;
+  return {
+    scopeRevision: commit && clean ? commit : `uncommitted:${scopeFingerprint}`,
+    scopeFingerprint
+  };
+}
+
+function assertApplicabilityReviewBasis(expected, current) {
+  if (
+    !expected
+    || Array.isArray(expected)
+    || typeof expected !== "object"
+    || typeof expected.scopeRevision !== "string"
+    || typeof expected.scopeFingerprint !== "string"
+  ) {
+    throw new Error("Applicability review basis must include its scope revision and scope fingerprint. Generate a new scaffold or preview.");
+  }
+  if (
+    expected.scopeRevision !== current.scopeRevision
+    || expected.scopeFingerprint !== current.scopeFingerprint
+  ) {
+    throw new Error("The workspace scope changed after this applicability review was prepared. Generate a new preview before confirming the write.");
+  }
+}
+
+async function applicabilityScopeFingerprint(loaded) {
+  const hash = createHash("sha256");
+  hash.update(`model\0${loaded.model.modelVersion}\0`);
+  for (const entry of [...loaded.entries].sort((left, right) => compareText(left.relativePath, right.relativePath))) {
+    hash.update(`record\0${entry.relativePath}\0${stableJson(entry.record)}\0`);
+    for (const markdown of markdownEntries(loaded.model, entry.record).sort((left, right) => (
+      compareText(left.path, right.path)
+    ))) {
+      try {
+        const source = await readFile(resolveDataPath(loaded.root, markdown.path), "utf8");
+        hash.update(`markdown\0${markdown.path}\0${source.length}\0${source}\0`);
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+        hash.update(`markdown-missing\0${markdown.path}\0`);
+      }
+    }
+  }
+  return hash.digest("hex");
+}
+
+function compareText(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => (
+      `${JSON.stringify(key)}:${stableJson(value[key])}`
+    )).join(",")}}`;
+  }
+  return JSON.stringify(value);
 }

package/src/cli.js

@@ -6,7 +6,7 @@ import { buildAgentGuide, findResourceReferences, listResourceTypes, scaffoldRes
 import { assessAuditPreparation, prepareAuditWorkspace } from "./audit-preparation.js";
 import { createNextAuditCycle, planNextAuditCycle } from "./audit-transition.js";
 import {
-  applyApplicabilityReview,
+  applyApplicabilityReviewWithContext,
   planApplicabilityReview,
   scaffoldApplicabilityReview
 } from "./batch-review.js";
@@ -41,6 +41,7 @@ import {
   setupExternalReviewerGovernance
 } from "./external-reviewer.js";
 import { relativeToWorkspace, resolveDataPath } from "./paths.js";
+import { activatePolicies, planPolicyActivation, scaffoldPolicyActivation } from "./policy-activation.js";
 import { buildAgentProgramPath } from "./program-path.js";
 import { assessEvidenceMap, assessProgramReadiness } from "./program-readiness.js";
 import { resolveProgram } from "./program.js";
@@ -432,6 +433,12 @@ export async function runCli(argv = process.argv.slice(2)) {
         console.log(`\n${stage.title}`);
         for (const item of stage.items) console.log(`${item.status.toUpperCase()}\t${item.title}\t${item.message}`);
       }
+      if (result.policyActivations.length) {
+        console.log("\nPolicy activation assessments");
+        for (const policy of result.policyActivations) {
+          console.log(`${policy.label.toUpperCase()}\t${policy.title}\t${policy.gapCount} implementation gaps`);
+        }
+      }
       if (result.canStartCandidatePeriod && !result.operating) {
         console.log(`\nEvidence Ready: management can start the candidate Type 2 period on or after ${result.suggestedCandidatePeriodStart || result.asOf}.`);
       }
@@ -561,7 +568,7 @@ export async function runCli(argv = process.argv.slice(2)) {
     const options = { ...payload, confirmed: flags.yes === true };
     const result = flags.preview
       ? await planApplicabilityReview(root, options)
-      : await withWorkflowDelta(root, () => applyApplicabilityReview(root, options));
+      : await applyApplicabilityReviewWithContext(root, options, { includeWorkflowDelta: true });
     if (flags.json) console.log(JSON.stringify(result, null, 2));
     else if (flags.preview) console.log(`Applicability preview: ${result.reviewedIds.length} decisions.`);
     else console.log(`Recorded ${result.reviewedIds.length} reviewed applicability decisions.`);
@@ -588,6 +595,27 @@ export async function runCli(argv = process.argv.slice(2)) {
     else console.log(`Confirmed ${result.assessment.configuration.title}.`);
     return result;
   }
+  if (command === "activate-policies") {
+    if (flags.scaffold) {
+      const result = await scaffoldPolicyActivation(root, { programId: flags.program });
+      console.log(JSON.stringify(result, null, 2));
+      return result;
+    }
+    const payload = await readSetupPayload(positionals[0]);
+    const options = {
+      ...payload,
+      policyIds: flags.policy ? String(flags.policy).split(",").filter(Boolean) : payload.policyIds,
+      effectiveOn: flags["effective-on"] || payload.effectiveOn,
+      confirmed: flags.yes === true
+    };
+    const result = flags.preview
+      ? await planPolicyActivation(root, options)
+      : await withWorkflowDelta(root, () => activatePolicies(root, options));
+    if (flags.json) console.log(JSON.stringify(result, null, 2));
+    else if (flags.preview) console.log(`Policy activation preview: ${result.policyIds.length} Policies effective ${result.effectiveOn}.`);
+    else console.log(`Activated ${result.policyIds.length} Policies effective ${result.effectiveOn}.`);
+    return result;
+  }
   if (command === "trigger") {
     const result = await withWorkflowDelta(root, () => createObligationEvent(root, {
       eventType: positionals[0],
@@ -1025,6 +1053,7 @@ Usage:
   filegrc next-audit-cycle <prior-audit-id> [cycle.json|-] --start YYYY-MM-DD --end YYYY-MM-DD [--preview|--yes] [--json]
   filegrc review-applicability [--scaffold --type requirement|control|commitment|complementary-control] [decisions.json|-] [--preview|--yes] [--json]
   filegrc review-collection <resource-type> [--scaffold | review.json|-] [--preview|--yes] [--json]
+  filegrc activate-policies [--scaffold | activation.json|-] [--effective-on YYYY-MM-DD] [--preview|--yes] [--json]
   filegrc trigger <event-type> (--occurred-on YYYY-MM-DD | --occurred-at RFC3339) [--risk-level normal|high] [--subject resource-id[,resource-id]] [--title text] [--json]
   filegrc evidence-packet [--audit audit-id] [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--output .filegrc/path] [--preview] [--require-ready] [--json]
   filegrc get [resource-type] <id> [--mutation]
@@ -1174,6 +1203,26 @@ Options:
   --help             Show this help`);
     return;
   }
+  if (command === "activate-policies") {
+    console.log(`Usage:
+  filegrc activate-policies --scaffold [--program id]
+  filegrc activate-policies <activation.json|-> [--effective-on YYYY-MM-DD] [--preview|--yes] [--json]
+
+Review and atomically activate selected approved Policies at the end of Step 3.
+The scaffold includes every required, approved, inactive Policy and its current
+revision. A past effective date is rejected.
+
+Options:
+  --scaffold             Print a cutover payload without writing
+  --program <id>         Program to assess when more than one active Program exists
+  --effective-on <date>  Shared effective date for the selected Policies
+  --preview              Validate and show the atomic updates without writing
+  --yes                  Confirm and apply the reviewed cutover
+  --json                 Print the result as JSON
+  --root <path>          Workspace path
+  --help                 Show this help`);
+    return;
+  }
   if (command === "evidence-map") {
     console.log(`Usage:
   filegrc evidence-map [options]
@@ -1220,6 +1269,7 @@ function agentOverview(model) {
     prepareAudit: "filegrc prepare-audit <audit-id>",
     reconcile: "filegrc reconcile --preview --json",
     externalReviewerSetup: "filegrc external-reviewer-setup [--scaffold | <reviewer.json|-> --preview] --json",
+    policyActivation: "filegrc activate-policies [--scaffold | <activation.json|-> --preview] --json",
     nextAuditCycle: "filegrc next-audit-cycle <prior-audit-id> --start <date> --end <date> --preview --json",
     reviewApplicability: "filegrc review-applicability <decisions.json|-> --preview --json",
     reviewCollection: "filegrc review-collection <resource-type> [--scaffold | <review.json|-> --preview] --json",
@@ -1371,6 +1421,8 @@ function buildProgramPathResult(model, readiness, auditReadiness) {
     currentStep: { id: currentStep.id, number: currentStep.number, title: currentStep.title },
     evidenceReady: readiness.evidenceReady,
     operating: readiness.operating,
+    policyActivations: readiness.policyActivations,
+    policyLibraryProposals: readiness.policyLibraryProposals,
     stages
   };
 }
@@ -1418,6 +1470,8 @@ function summarizeProgramPath(result) {
     currentStep: result.currentStep,
     evidenceReady: result.evidenceReady,
     operating: result.operating,
+    policyActivations: result.policyActivations,
+    policyLibraryProposals: result.policyLibraryProposals,
     stages: result.stages.map((stage) => ({
       id: stage.id,
       number: stage.number,
@@ -1439,6 +1493,8 @@ function nextProgramPath(result) {
     currentStep: result.currentStep,
     evidenceReady: result.evidenceReady,
     operating: result.operating,
+    policyActivations: result.policyActivations,
+    policyLibraryProposals: result.policyLibraryProposals,
     step: stage ? {
       id: stage.id,
       number: stage.number,
@@ -1562,6 +1618,14 @@ function summarizeProgramReadiness(result) {
     scopeCounts: Object.fromEntries(
       Object.entries(result.scope).map(([name, ids]) => [name.replace(/Ids$/, ""), ids.length])
     ),
+    policyActivations: result.policyActivations.map(({ policyId, title, state, label, gapCount }) => ({
+      policyId,
+      title,
+      state,
+      label,
+      gapCount
+    })),
+    policyLibraryProposals: result.policyLibraryProposals,
     unresolvedOwnership: {
       count: unresolvedOwnership.length,
       byReason: ownershipReasons,

package/src/collection-review.js

@@ -1,33 +1,12 @@
 import { createHash } from "node:crypto";
+import { collectionRevision } from "./collection-revision.js";
 import { scopedCollectionRecords } from "./collection-scope.js";
 import { applyResourceBatch } from "./files.js";
 import { getGitSummary } from "./git.js";
 import { loadWorkspace } from "./workspace.js";
-import { resolveProgram, selectedRequirementIds } from "./program.js";
+import { resolveProgram } from "./program.js";
 
-export function collectionRevision(loaded, resourceType, options = {}) {
-  const program = resolveProgram(loaded, options.programId);
-  const scopedIds = new Set(scopedCollectionRecords(loaded, resourceType, program).map(({ id }) => id));
-  const records = loaded.entries
-    .filter(({ record }) => record.type === resourceType && scopedIds.has(record.id))
-    .map(({ record, source }) => ({
-      id: record.id,
-      revision: createHash("sha256").update(source).digest("hex")
-    }))
-    .sort((left, right) => left.id.localeCompare(right.id));
-  const workspaceScope = {
-    programId: program?.id ?? null,
-    assuranceGoal: program?.assuranceGoal ?? null,
-    candidateCoverage: program?.candidateCoverage ?? null,
-    systemIds: [...(program?.systemIds || [])].sort(),
-    frameworkIds: [...(program?.frameworkIds || [])].sort(),
-    requirementIds: [...selectedRequirementIds(program || {}, loaded.model)].sort(),
-    controlIds: [...(program?.controlIds || [])].sort()
-  };
-  return createHash("sha256")
-    .update(JSON.stringify({ resourceType, records, workspaceScope }))
-    .digest("hex");
-}
+export { collectionRevision };
 
 export function assessCollectionReviews(input, options = {}) {
   const loaded = input?.resources && input?.model && input?.entries
@@ -50,7 +29,13 @@ export function assessCollectionReview(loaded, resourceType, options = {}) {
     && (String(loaded.model.modelVersion) !== "4" || (record.scopeResourceIds || []).includes(program.id))
   ));
   const review = reviewEntry?.record || null;
-  const currentRevision = collectionRevision(loaded, resourceType, { programId: program.id });
+  const authoritativeSourceId = review?.decision === "externally-managed"
+    ? review.authoritativeComponentId || review.authoritativeSystemId
+    : null;
+  const currentRevision = collectionRevision(loaded, resourceType, {
+    programId: program.id,
+    authoritativeSourceId
+  });
   const allowedDecisions = configuration.decisions || ["complete"];
   const allowsEmptyCollection = allowedDecisions.some((decision) => (
     decision === "zero-population" || decision === "externally-managed"
@@ -147,6 +132,10 @@ export async function planCollectionReview(input = process.cwd(), options = {})
     ));
     if (!system) throw new Error(`${configuration.title} review needs an active authoritative ${v4 ? "Component" : "System"}.`);
   }
+  const currentRevision = collectionRevision(loaded, resourceType, {
+    programId: program.id,
+    authoritativeSourceId: decision === "externally-managed" ? authoritativeSourceId : null
+  });
   const existing = assessment.review;
   const record = {
     ...(existing || {
@@ -161,7 +150,7 @@ export async function planCollectionReview(input = process.cwd(), options = {})
     rationale,
     reviewedByIds,
     reviewedOn,
-    collectionRevision: assessment.collectionRevision,
+    collectionRevision: currentRevision,
     scopeRevision,
     ...(decision === "externally-managed"
       ? { [v4 ? "authoritativeComponentId" : "authoritativeSystemId"]: authoritativeSourceId }

package/src/collection-revision.js

@@ -0,0 +1,83 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import {
+  collectionRevisionInputs,
+  collectionScopeRevisionFacts
+} from "./collection-scope.js";
+import { resolveDataPath } from "./paths.js";
+import { resolveProgram } from "./program.js";
+import { markdownEntries } from "./resource-markdown.js";
+
+export function collectionRevision(loaded, resourceType, options = {}) {
+  const program = Object.hasOwn(options, "program")
+    ? options.program
+    : resolveProgram(loaded, options.programId);
+  const inputs = new Map(collectionRevisionInputs(loaded, resourceType, program)
+    .map((input) => [input.record.id, input]));
+  const authoritativeSource = loaded.resources.find(({ id }) => id === options.authoritativeSourceId);
+  if (authoritativeSource) {
+    inputs.set(authoritativeSource.id, { record: authoritativeSource, value: authoritativeSource });
+  }
+  const records = [...inputs.values()]
+    .map(({ record, value }) => ({
+      id: record.id,
+      revision: createHash("sha256")
+        .update(JSON.stringify(canonicalRecordValue(loaded.model, record.type, value)))
+        .digest("hex"),
+      contentRevisions: markdownEntries(loaded.model, record).flatMap(({ path }) => {
+        try {
+          const content = readFileSync(resolveDataPath(loaded.root, path), "utf8");
+          return [{ path, revision: createHash("sha256").update(content).digest("hex") }];
+        } catch (error) {
+          if (error.code === "ENOENT") return [];
+          throw error;
+        }
+      })
+    }))
+    .sort((left, right) => left.id.localeCompare(right.id));
+  const workspaceScope = collectionScopeRevisionFacts(loaded, resourceType, program);
+  return createHash("sha256")
+    .update(JSON.stringify({ resourceType, records, workspaceScope }))
+    .digest("hex");
+}
+
+function canonicalRecordValue(model, resourceType, value) {
+  const fields = {
+    ...model.commonFields,
+    ...model.resources[resourceType]?.fields
+  };
+  return canonicalObject(model, value, fields);
+}
+
+function canonicalObject(model, value, fields = {}) {
+  return Object.fromEntries(Object.keys(value).sort().map((name) => [
+    name,
+    canonicalFieldValue(model, value[name], fields[name])
+  ]));
+}
+
+function canonicalFieldValue(model, value, field) {
+  if (Array.isArray(value)) {
+    const objectType = field?.itemObjectType;
+    const itemFields = objectType ? model.objectTypes?.[objectType]?.properties : undefined;
+    const items = value.map((item) => (
+      item && typeof item === "object" && !Array.isArray(item)
+        ? canonicalObject(model, item, itemFields)
+        : item
+    ));
+    return field?.type === "array"
+      ? items.sort(compareCanonicalValues)
+      : items;
+  }
+  if (value && typeof value === "object") {
+    const objectType = field?.objectType;
+    return canonicalObject(model, value, objectType ? model.objectTypes?.[objectType]?.properties : undefined);
+  }
+  return value;
+}
+
+function compareCanonicalValues(left, right) {
+  const leftValue = JSON.stringify(left);
+  const rightValue = JSON.stringify(right);
+  return leftValue < rightValue ? -1 : leftValue > rightValue ? 1 : 0;
+}