filegrc 0.9.1 → 0.10.0

package/src/cli.js

@@ -223,6 +223,7 @@ export async function runCli(argv = process.argv.slice(2)) {
         : `Needs review: ${result.missing.length} missing values, ${result.conflicts.length} conflicts, ${result.manualActions.length} manual actions.`);
     } else {
       console.log(`Migrated workspace from model v${result.sourceModelVersion} to v${result.targetModelVersion}.`);
+      if (result.migrationReportPath) console.log(`Migration report: ${result.migrationReportPath}`);
     }
     return result;
   }
@@ -261,7 +262,10 @@ export async function runCli(argv = process.argv.slice(2)) {
     const audit = auditId ? loaded.resources.find(({ id, type }) => id === auditId && type === "audit") : null;
     const programId = flags.program || audit?.programId;
     const readiness = await assessProgramReadiness(loaded, { asOf: flags["as-of"], programId });
-    const auditReadiness = auditId ? await assessAuditPreparation(loaded, { auditId }) : null;
+    const auditReadiness = auditId ? await assessAuditPreparation(loaded, {
+      auditId,
+      asOf: flags["as-of"]
+    }) : null;
     const result = buildProgramPathResult(loaded.model, readiness, auditReadiness);
     const output = selectProgramPathOutput(result, flags);
     if (flags.json) console.log(JSON.stringify(output, null, 2));
@@ -481,7 +485,10 @@ export async function runCli(argv = process.argv.slice(2)) {
   }
   if (command === "audit-readiness") {
     const loaded = await loadWorkspace(root);
-    const result = await assessAuditPreparation(loaded, { auditId: positionals[0] || flags.audit });
+    const result = await assessAuditPreparation(loaded, {
+      auditId: positionals[0] || flags.audit,
+      asOf: flags["as-of"]
+    });
     if (flags.json) console.log(JSON.stringify(result, null, 2));
     else {
       console.log(`${result.status.toUpperCase()}: ${result.progress.complete} of ${result.progress.total} management items complete`);
@@ -1115,7 +1122,7 @@ Usage:
   filegrc build [root] [--output .filegrc/site]
   filegrc validate [root] [--json]
   filegrc model [--json|--write-docs|--check-docs]
-  filegrc migrate --to-model <2|3|4|5|6> [--preview] [--decisions path] [--job-title text] [--starts-on YYYY-MM-DD] [--yes] [--json]
+  filegrc migrate --to-model <${SUPPORTED_MODEL_VERSIONS.join("|")}> [--preview] [--decisions path] [--job-title text] [--starts-on YYYY-MM-DD] [--yes] [--json]
   filegrc describe <resource-type>
   filegrc types [--json]
   filegrc guide [resource-type] [--id resource-id] [--program program-id] [--json]
@@ -1129,7 +1136,7 @@ Usage:
   filegrc obligations [--as-of YYYY-MM-DD] [--from YYYY-MM-DD] [--through YYYY-MM-DD] [--now RFC3339] [--complete] [--json]
   filegrc program-readiness [--as-of YYYY-MM-DD] [--require-ready] [--summary] [--json]
   filegrc evidence-map [--as-of YYYY-MM-DD] [--json]
-  filegrc audit-readiness [audit-id] [--require-ready] [--json]
+  filegrc audit-readiness [audit-id] [--as-of YYYY-MM-DD] [--require-ready] [--json]
   filegrc prepare-audit <audit-id> [--json]
   filegrc reconcile [--preview|--apply --candidate fingerprint (--occurred-on YYYY-MM-DD | --occurred-at RFC3339) --yes] [--risk-level normal|high] [--json]
   filegrc external-reviewer-setup --scaffold
@@ -1214,7 +1221,8 @@ workspaces migrate to v2 first. Continue one version at a time through v${ACTIVE
 the repository Workspace, management Program, bounded Systems, operational Components,
 specific Assets, Vendors, normalized information, and Evidence Artifacts. Model v5 separates
 Document approval from activation and records program-versus-engagement scope. Model v6 gives
-Training the same approval and activation split and moves its schedule into Obligations. v3 migration
+Training the same approval and activation split and moves its schedule into Obligations. Model v7
+keeps issued historical Documents neutral and requires a current activation for legacy Training. v3 migration
 previews may require a decisions JSON file for ambiguous old Systems. v3 still creates planned
 core Appointments, removal of obsolete manual page state, classified review work,
 and dataModelVersion changed last. The command writes no Git commit.
@@ -1231,7 +1239,8 @@ Options:
   --help                Show this help
 
 Start with:
-  npx filegrc migrate --to-model ${ACTIVE_MODEL_VERSION} --preview --json`);
+  npx filegrc guide --json
+  # Use the next model version shown by the guide.`);
     return;
   }
   if (command === "program-readiness") {
@@ -1398,6 +1407,10 @@ Options:
 }
 
 function agentOverview(model) {
+  const currentModelIndex = SUPPORTED_MODEL_VERSIONS.indexOf(String(model.modelVersion));
+  const nextModelVersion = currentModelIndex >= 0 && currentModelIndex < SUPPORTED_MODEL_VERSIONS.length - 1
+    ? SUPPORTED_MODEL_VERSIONS[currentModelIndex + 1]
+    : ACTIVE_MODEL_VERSION;
   const commands = {
     help: "filegrc help",
     version: "filegrc version",
@@ -1406,7 +1419,7 @@ function agentOverview(model) {
     build: "filegrc build [root]",
     validate: "filegrc validate [root] --json",
     model: "filegrc model --json",
-    migrate: "filegrc migrate --to-model 6 --preview --json",
+    migrate: `filegrc migrate --to-model ${nextModelVersion} --preview --json`,
     describe: "filegrc describe <resource-type>",
     types: "filegrc types --json",
     guide: "filegrc guide [resource-type] --json",

package/src/collection-review.js

@@ -1,6 +1,9 @@
 import { createHash } from "node:crypto";
 import { modelSupports } from "../model/index.js";
-import { collectionRevision } from "./collection-revision.js";
+import {
+  collectionRevision,
+  collectionRevisionMatches
+} from "./collection-revision.js";
 import { scopedCollectionRecords } from "./collection-scope.js";
 import { applyResourceBatch } from "./files.js";
 import { getGitSummary } from "./git.js";
@@ -41,15 +44,25 @@ export function assessCollectionReview(loaded, resourceType, options = {}) {
   const allowsEmptyCollection = allowedDecisions.some((decision) => (
     decision === "zero-population" || decision === "externally-managed"
   ));
+  const revisionMatches = collectionRevisionMatches(
+    loaded,
+    resourceType,
+    review?.collectionRevision,
+    {
+      programId: program.id,
+      authoritativeSourceId,
+      currentRevision
+    }
+  );
   const complete = Boolean(
     review?.status === "active"
     && allowedDecisions.includes(review.decision)
-    && review.collectionRevision === currentRevision
+    && revisionMatches
   );
   const stale = Boolean(
     review?.status === "active"
     && review.collectionRevision
-    && review.collectionRevision !== currentRevision
+    && !revisionMatches
   );
   return {
     resourceType,

package/src/collection-revision.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import {
+  authoritativeSourceRevisionValue,
   collectionRevisionInputs,
   collectionScopeRevisionFacts
 } from "./collection-scope.js";
@@ -9,22 +10,46 @@ import { resolveProgram } from "./program.js";
 import { markdownEntries } from "./resource-markdown.js";
 
 export function collectionRevision(loaded, resourceType, options = {}) {
+  return calculateCollectionRevision(loaded, resourceType, options, false);
+}
+
+export function legacyCollectionRevision(loaded, resourceType, options = {}) {
+  return calculateCollectionRevision(loaded, resourceType, options, true);
+}
+
+export function collectionRevisionMatches(loaded, resourceType, storedRevision, options = {}) {
+  if (!storedRevision) return false;
+  const currentRevision = options.currentRevision
+    || collectionRevision(loaded, resourceType, options);
+  // Version 0.9.2 narrowed this hash basis. Keep unchanged 0.9.1 reviews valid
+  // until management records a new review on the current basis.
+  return storedRevision === currentRevision
+    || storedRevision === legacyCollectionRevision(loaded, resourceType, options);
+}
+
+function calculateCollectionRevision(loaded, resourceType, options, legacy) {
   const program = Object.hasOwn(options, "program")
     ? options.program
     : resolveProgram(loaded, options.programId);
-  const inputs = new Map(collectionRevisionInputs(loaded, resourceType, program)
+  const inputs = new Map(collectionRevisionInputs(loaded, resourceType, program, { legacy })
     .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 });
+    inputs.set(authoritativeSource.id, {
+      record: authoritativeSource,
+      value: legacy
+        ? authoritativeSource
+        : authoritativeSourceRevisionValue(authoritativeSource),
+      includeContent: true
+    });
   }
   const records = [...inputs.values()]
-    .map(({ record, value }) => ({
+    .map(({ record, value, includeContent }) => ({
       id: record.id,
       revision: createHash("sha256")
         .update(JSON.stringify(canonicalRecordValue(loaded.model, record.type, value)))
         .digest("hex"),
-      contentRevisions: markdownEntries(loaded.model, record).flatMap(({ path }) => {
+      contentRevisions: (legacy || includeContent ? markdownEntries(loaded.model, record) : []).flatMap(({ path }) => {
         try {
           const content = readFileSync(resolveDataPath(loaded.root, path), "utf8");
           return [{ path, revision: createHash("sha256").update(content).digest("hex") }];

package/src/collection-scope.js

@@ -5,8 +5,27 @@ export function scopedCollectionRecords(loaded, resourceType, program) {
   if (!modelSupports(loaded.model, "program-scope")) {
     return loaded.resources.filter((record) => record.type === resourceType);
   }
+  if (resourceType === "person") {
+    return scopedProgramPeople(loaded, program);
+  }
   if (resourceType === "vendor") {
-    return loaded.resources.filter((record) => record.type === "vendor");
+    const scopedVendorIds = new Set(programComponents(loaded, program).map(({ vendorId }) => vendorId).filter(Boolean));
+    const auditVendorIds = new Set(loaded.resources
+      .filter((record) => record.type === "audit" && record.auditorVendorId)
+      .map(({ auditorVendorId }) => auditorVendorId));
+    const auditOnlyVendorIds = Number(loaded.model.modelVersion) >= 7
+      ? auditVendorIds
+      : new Set(loaded.resources
+          .filter((record) => (
+            record.type === "vendor"
+            && auditVendorIds.has(record.id)
+            && /(?:audit|accounting|cpa)/i.test(record.category || "")
+          ))
+          .map(({ id }) => id));
+    return loaded.resources.filter((record) => (
+      record.type === "vendor"
+      && (!auditOnlyVendorIds.has(record.id) || scopedVendorIds.has(record.id))
+    ));
   }
   const scopedProgram = program || {};
   const components = programComponents(loaded, scopedProgram);
@@ -36,10 +55,47 @@ export function scopedCollectionRecords(loaded, resourceType, program) {
   ));
 }
 
-export function collectionRevisionInputs(loaded, resourceType, program) {
+function scopedProgramPeople(loaded, program = {}) {
+  const personIds = new Set(loaded.resources.filter(({ type }) => type === "person").map(({ id }) => id));
+  const systemIds = new Set(program.systemIds || []);
+  const controlIds = new Set(program.controlIds || []);
+  const policyIds = new Set(loaded.resources
+    .filter(({ type, status, programRole }) => type === "policy" && status !== "retired" && programRole !== "reference")
+    .map(({ id }) => id));
+  const components = programComponents(loaded, program);
+  const componentIds = new Set(components.map(({ id }) => id));
+  const vendorIds = new Set([
+    ...components.map(({ vendorId }) => vendorId).filter(Boolean),
+    ...scopedCollectionRecords(loaded, "vendor", program).map(({ id }) => id)
+  ]);
+  const sources = loaded.resources.filter((record) => (
+    ["workspace", "program", "appointment", "team"].includes(record.type)
+    || record.type === "system" && systemIds.has(record.id)
+    || record.type === "component" && componentIds.has(record.id)
+    || record.type === "vendor" && vendorIds.has(record.id)
+    || record.type === "control" && controlIds.has(record.id)
+    || record.type === "policy" && policyIds.has(record.id)
+    || record.type === "document" && record.workflowScope !== "engagement"
+    || record.type === "obligation" && (
+      (record.controlIds || []).some((id) => controlIds.has(id))
+      || (record.policyIds || []).some((id) => policyIds.has(id))
+    )
+  ));
+  const selected = new Set();
+  const visit = (value) => {
+    if (typeof value === "string" && personIds.has(value)) selected.add(value);
+    else if (Array.isArray(value)) value.forEach(visit);
+    else if (value && typeof value === "object") Object.values(value).forEach(visit);
+  };
+  sources.forEach(visit);
+  return loaded.resources.filter((record) => record.type === "person" && selected.has(record.id));
+}
+
+export function collectionRevisionInputs(loaded, resourceType, program, options = {}) {
+  const legacy = options.legacy === true;
   const reviewed = scopedCollectionRecords(loaded, resourceType, program);
   if (!modelSupports(loaded.model, "program-scope")) {
-    return reviewed.map((record) => ({ record, value: record }));
+    return reviewed.map((record) => ({ record, value: record, includeContent: true }));
   }
   const byId = new Map(loaded.resources.map((record) => [record.id, record]));
   const records = new Map(reviewed.map((record) => [record.id, record]));
@@ -90,7 +146,10 @@ export function collectionRevisionInputs(loaded, resourceType, program) {
     record,
     value: reviewedIds.has(record.id)
       ? record
-      : dependencyRevisionValue(resourceType, record)
+      : dependencyRevisionValue(resourceType, record, legacy),
+    includeContent: legacy
+      || reviewedIds.has(record.id)
+      || dependencyContentAffectsRevision(resourceType, record.type)
   }));
 }
 
@@ -138,9 +197,20 @@ export function collectionScopeRevisionFacts(loaded, resourceType, program) {
   return common;
 }
 
+export function authoritativeSourceRevisionValue(record) {
+  return Object.fromEntries(Object.entries(record).filter(([field]) => (
+    !authoritativeSourceBookkeepingFields.has(field)
+  )));
+}
+
+const authoritativeSourceBookkeepingFields = new Set([
+  "tags",
+  "statusTransition"
+]);
+
 const dependencyFields = {
   framework: {
-    system: ["id", "type", "status", "purpose", "servicesProvided", "boundary", "exclusions", "informationTypeIds", "classificationId", "internetExposed"],
+    system: ["id", "type", "status", "purpose", "servicesProvided", "boundary", "exclusions", "criticality", "informationTypeIds", "classificationId", "internetExposed", "continuityObjectives"],
     requirement: ["id", "type", "title", "frameworkId", "reference", "description", "parentRequirementId"]
   },
   vendor: {
@@ -154,30 +224,59 @@ const dependencyFields = {
   },
   component: {
     system: ["id", "type", "status", "purpose", "servicesProvided", "boundary", "exclusions", "criticality", "informationTypeIds", "classificationId", "internetExposed", "continuityObjectives"],
-    control: ["id", "type", "status", "statement", "activity", "controlType", "operationMode", "operationPattern", "systemIds", "componentIds", "evidenceSourceComponentIds"],
-    vendor: ["id", "type", "status", "category", "criticality", "description", "standardAgreement", "agreementDocumentId", "startDate", "endDate", "classificationId", "informationTypeIds"],
+    control: ["id", "type", "systemIds", "componentIds", "evidenceSourceComponentIds"],
+    vendor: ["id", "type", "status", "category", "criticality", "description", "startDate", "endDate"],
     classification: ["id", "type", "status", "rank", "description", "handlingRequirements"],
     "information-type": ["id", "type", "status", "classificationId", "description"]
   },
   "complementary-control": {
-    system: ["id", "type", "status", "purpose", "servicesProvided", "boundary", "exclusions", "informationTypeIds", "classificationId", "internetExposed"],
-    control: ["id", "type", "status", "statement", "activity", "controlType", "operationMode", "operationPattern", "systemIds", "componentIds", "evidenceSourceComponentIds"],
+    system: ["id", "type", "status", "purpose", "servicesProvided", "boundary", "exclusions", "criticality", "informationTypeIds", "classificationId", "internetExposed", "continuityObjectives"],
+    control: ["id", "type", "status", "statement", "activity", "systemIds", "componentIds", "evidenceSourceComponentIds"],
     vendor: ["id", "type", "status", "category", "criticality", "description", "standardAgreement", "agreementDocumentId", "startDate", "endDate", "classificationId", "informationTypeIds"],
     requirement: ["id", "type", "title", "frameworkId", "reference", "description", "parentRequirementId"],
     commitment: ["id", "type", "status", "commitmentKind", "statement", "systemIds", "requirementIds", "controlIds", "customerFacing", "effectiveOn"],
     document: ["id", "type", "status", "documentKind", "version", "effectiveOn", "approvedOn", "approvedContentRevisions", "systemIds", "controlIds", "componentIds", "classificationId"],
+    component: ["id", "type", "status", "componentKind", "description", "criticality", "vendorId", "systemUses", "informationUses", "internetExposed", "classificationId", "continuityObjectives"]
+  }
+};
+
+const legacyDependencyFieldOverrides = {
+  framework: {
+    system: ["id", "type", "status", "purpose", "servicesProvided", "boundary", "exclusions", "informationTypeIds", "classificationId", "internetExposed"]
+  },
+  component: {
+    control: ["id", "type", "status", "statement", "activity", "controlType", "operationMode", "operationPattern", "systemIds", "componentIds", "evidenceSourceComponentIds"],
+    vendor: ["id", "type", "status", "category", "criticality", "description", "standardAgreement", "agreementDocumentId", "startDate", "endDate", "classificationId", "informationTypeIds"]
+  },
+  "complementary-control": {
+    system: ["id", "type", "status", "purpose", "servicesProvided", "boundary", "exclusions", "informationTypeIds", "classificationId", "internetExposed"],
+    control: ["id", "type", "status", "statement", "activity", "controlType", "operationMode", "operationPattern", "systemIds", "componentIds", "evidenceSourceComponentIds"],
     component: ["id", "type", "status", "componentKind", "description", "vendorId", "systemUses", "informationUses", "internetExposed"]
   }
 };
 
-function dependencyRevisionValue(resourceType, record) {
-  const fields = dependencyFields[resourceType]?.[record.type];
+const dependencyContentTypes = {
+  framework: new Set(["system"]),
+  vendor: new Set(["document"]),
+  component: new Set(["system"]),
+  "complementary-control": new Set(["system", "control", "document", "component"])
+};
+
+function dependencyRevisionValue(resourceType, record, legacy) {
+  const fields = legacy
+    ? legacyDependencyFieldOverrides[resourceType]?.[record.type]
+      || dependencyFields[resourceType]?.[record.type]
+    : dependencyFields[resourceType]?.[record.type];
   if (!fields) return { id: record.id, type: record.type };
   return Object.fromEntries(fields
     .filter((field) => record[field] !== undefined)
     .map((field) => [field, record[field]]));
 }
 
+function dependencyContentAffectsRevision(resourceType, dependencyType) {
+  return dependencyContentTypes[resourceType]?.has(dependencyType) || false;
+}
+
 function sorted(values) {
   return [...(values || [])].sort();
 }

package/src/document-activation.js

@@ -14,6 +14,13 @@ export async function scaffoldDocumentActivation(input = process.cwd(), options
   const revisionById = new Map(loaded.entries.map((entry) => [entry.record.id, contentRevision(entry.source)]));
   const today = currentCalendarDate(loaded.workspace.timezone);
   return {
+    available: candidates.length > 0,
+    message: candidates.length
+      ? `${candidates.length} approved ${candidates.length === 1 ? "Document is" : "Documents are"} ready to activate.`
+      : `No ${options.auditId ? "engagement Document" : "program Document"} is ready to activate. Review the current readiness actions first.`,
+    nextCommand: candidates.length ? null : options.auditId
+      ? `npx filegrc audit-readiness ${options.auditId} --json`
+      : "npx filegrc program-path --next --json",
     documentIds: candidates.filter(({ resourceType }) => resourceType === "document").map(({ resourceId }) => resourceId),
     ...(options.auditId ? { auditId: options.auditId, workflowScope: "engagement" } : { workflowScope: "program" }),
     activatedByIds: [],
@@ -141,12 +148,17 @@ export async function scaffoldGovernedContentActivation(input = process.cwd(), o
   const loaded = await loadWorkspace(input);
   requireDocumentLifecycle(loaded);
   if (!modelSupports(loaded.model, "governed-training-activation")) {
-    throw new Error("Unified governed-content activation requires a model v6 workspace.");
+    throw new Error("Unified governed-content activation requires a model v6 or later workspace.");
   }
   const candidates = await activationCandidates(loaded, { ...options, auditId: undefined });
   const revisionById = new Map(loaded.entries.map((entry) => [entry.record.id, contentRevision(entry.source)]));
   const today = currentCalendarDate(loaded.workspace.timezone);
   return {
+    available: candidates.length > 0,
+    message: candidates.length
+      ? `${candidates.length} approved governed-content ${candidates.length === 1 ? "record is" : "records are"} ready to activate.`
+      : "No program Document or Training record is ready to activate. Review the current readiness actions first.",
+    nextCommand: candidates.length ? null : "npx filegrc program-path --next --json",
     resourceIds: candidates.map(({ resourceId }) => resourceId),
     documentIds: candidates.filter(({ resourceType }) => resourceType === "document").map(({ resourceId }) => resourceId),
     trainingIds: candidates.filter(({ resourceType }) => resourceType === "training").map(({ resourceId }) => resourceId),