filegrc 0.16.4 → 0.16.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "filegrc",
-  "version": "0.16.4",
+  "version": "0.16.5",
   "description": "Zero-dependency Git-native GRC engine",
   "license": "MIT",
   "repository": {

package/src/cli.js

@@ -1830,7 +1830,7 @@ function buildProgramPathResult(model, readiness, auditReadiness) {
   const readinessById = new Map(readiness.stages.map((stage) => [stage.id, stage]));
   const stages = buildAgentProgramPath(model).map((stage) => {
     if (stage.id === "audit") {
-      const auditAction = auditReadiness?.status === "not-started"
+      const auditAction = !auditReadiness || auditReadiness.status === "not-started"
         ? {
             id: "create-audit",
             status: "action",
@@ -2001,11 +2001,11 @@ function nextActionCommands(stage, action) {
   const commands = [`npx filegrc guide ${resourceType} --json`];
   if (action.resourceId) {
     const resourceId = shellArgument(action.resourceId);
-    commands.push(`npx filegrc get ${resourceId} --mutation`);
+    commands.push(`npx filegrc get ${resourceId} --mutation > MUTATION.json`);
     commands.push(`npx filegrc update ${resourceType} ${resourceId} MUTATION.json --json`);
   } else {
     commands.push(`npx filegrc list ${resourceType} --json`);
-    commands.push(`npx filegrc scaffold ${resourceType} --title "NAME"`);
+    commands.push(`npx filegrc scaffold ${resourceType} --title "NAME" > MUTATION.json`);
     commands.push("npx filegrc create MUTATION.json --json");
   }
   return commands;

package/src/program-readiness.js

@@ -470,7 +470,7 @@ function scopeStage(workspace, scope, records, byId, model, collectionReviews =
     )));
     items.push(item(
       "commitments",
-      scope.systems.length && uncoveredSystems.length === 0 && unscopedCommitments.length === 0 ? "complete" : "action",
+      !scope.systems.length ? "later" : uncoveredSystems.length === 0 && unscopedCommitments.length === 0 ? "complete" : "action",
       "Record service commitments and system requirements",
       scope.systems.length
         ? `${completeCommitments.length} complete active ${completeCommitments.length === 1 ? "commitment covers" : "commitments cover"} ${scope.systems.length - uncoveredSystems.length} of ${scope.systems.length} in-scope systems.${unscopedCommitments.length ? ` ${unscopedCommitments.length} Commitment${unscopedCommitments.length === 1 ? " has" : "s have"} no System scope and must be reviewed explicitly.` : ""}`
@@ -711,14 +711,23 @@ function reportingRouteItem(records, byId, asOf, timezone = "UTC") {
 }
 
 export function collectionReviewReadinessItem(assessment) {
+  const firstIncomplete = assessment.incompleteRecordProposals?.[0]
+    || assessment.recordProposals?.find(({ complete }) => !complete);
+  const needsFirstRecord = assessment.recordCount === 0
+    && !(assessment.configuration.decisions || []).some((decision) => ["zero-population", "externally-managed"].includes(decision));
+  const proposalAction = !assessment.complete && firstIncomplete;
+  const pendingRetentionRow = assessment.resourceType === "retention-schedule-item"
+    ? assessment.records?.find(({ status }) => status === "planned")
+    : null;
+  const approvalAction = !proposalAction && !pendingRetentionRow
+    ? collectionApprovalIssueAction(assessment)
+    : null;
   const proposalUnits = (assessment.recordProposals || []).map((proposal) => ({
     id: `${assessment.resourceType}-proposal-${proposal.resourceId}`,
     status: proposal.complete ? "complete" : "action",
     title: `${proposal.title} proposal`
   }));
   const proposalBatchComplete = proposalUnits.every(({ status }) => status === "complete");
-  const scheduleApprovalBlocked = assessment.resourceType === "retention-schedule-item"
-    && proposalUnits.some(({ status }) => status !== "complete");
   const batchProgressUnits = assessment.resourceType !== "retention-schedule-item" && proposalUnits.length
     ? [
         {
@@ -737,24 +746,100 @@ export function collectionReviewReadinessItem(assessment) {
     : null;
   return item(
     `collection-review-${assessment.resourceType}`,
-    assessment.complete ? "complete" : scheduleApprovalBlocked ? "blocked" : "action",
-    assessment.status === "stale"
-      ? `Review ${assessment.configuration.title.toLowerCase()} again`
-      : `Review ${assessment.configuration.title.toLowerCase()}`,
-    assessment.message,
-    assessment.review || { type: assessment.resourceType },
+    assessment.complete ? "complete" : pendingRetentionRow && !proposalAction ? "blocked" : "action",
+    proposalAction
+      ? `Complete ${firstIncomplete.title} proposal`
+      : needsFirstRecord
+        ? `Add a record for ${assessment.configuration.title.toLowerCase()}`
+        : approvalAction
+          ? approvalAction.title
+        : assessment.status === "stale"
+          ? `Review ${assessment.configuration.title.toLowerCase()} again`
+          : `Review ${assessment.configuration.title.toLowerCase()}`,
+    proposalAction
+      ? `Complete ${firstIncomplete.title} before reviewing ${assessment.configuration.title.toLowerCase()}.`
+      : assessment.message,
+    proposalAction
+      ? { id: firstIncomplete.resourceId, type: assessment.resourceType }
+      : needsFirstRecord ? { type: assessment.resourceType }
+        : approvalAction ? { type: approvalAction.resourceType, ...(approvalAction.resourceId ? { id: approvalAction.resourceId } : {}) }
+          : assessment.review || { type: assessment.resourceType },
     {
-      resourceType: assessment.resourceType,
+      resourceType: approvalAction?.resourceType || assessment.resourceType,
       reviewPoints: assessment.configuration.reviewPoints,
+      ...(approvalAction?.createResource ? { createResource: true } : {}),
+      ...(pendingRetentionRow && !proposalAction ? { unresolvedAssignments: [{
+        resourceType: "retention-schedule-item",
+        resourceId: pendingRetentionRow.id,
+        reasons: ["Complete or retire the planned retention row before approving the schedule."]
+      }] } : {}),
       ...(batchProgressUnits ? { progressUnits: batchProgressUnits } : {}),
-      commands: [
-        `npx filegrc review-collection ${assessment.resourceType} --scaffold`,
-        `npx filegrc review-collection ${assessment.resourceType} REVIEW.json --preview --json`
-      ]
+      commands: proposalAction
+        ? [
+            `npx filegrc guide ${assessment.resourceType} --json`,
+            `npx filegrc get ${shellArgument(firstIncomplete.resourceId)} --mutation > MUTATION.json`,
+            `npx filegrc update ${assessment.resourceType} ${shellArgument(firstIncomplete.resourceId)} MUTATION.json --json`
+          ]
+        : needsFirstRecord
+          ? [
+              `npx filegrc guide ${assessment.resourceType} --json`,
+              `npx filegrc scaffold ${assessment.resourceType} --title "NAME" > MUTATION.json`,
+              "npx filegrc create MUTATION.json --json"
+            ]
+          : approvalAction
+            ? approvalAction.commands
+            : [
+              `npx filegrc review-collection ${assessment.resourceType} --scaffold > REVIEW.json`,
+              `npx filegrc review-collection ${assessment.resourceType} REVIEW.json --preview --json`,
+              `npx filegrc review-collection ${assessment.resourceType} REVIEW.json --yes --json`
+            ]
     }
   );
 }
 
+function collectionApprovalIssueAction(assessment) {
+  const issue = assessment.approvalIssues?.[0];
+  if (!issue || issue.code === "invalid-retention-schedule-approval-binding") return null;
+  const rows = assessment.records || [];
+  const documentId = issue.resourceId || rows.find(({ scheduleDocumentId }) => scheduleDocumentId)?.scheduleDocumentId;
+  if (issue.code.includes("retention-schedule-document")) {
+    const resourceId = issue.code === "missing-retention-schedule-document" || issue.code === "multiple-retention-schedule-documents"
+      ? null : documentId;
+    return {
+      title: issue.code === "missing-retention-schedule-document" ? "Add the Data Retention Schedule document"
+        : issue.code === "multiple-retention-schedule-documents" ? "Resolve duplicate Data Retention Schedule documents"
+          : "Complete the Data Retention Schedule document",
+      resourceType: "document",
+      resourceId,
+      createResource: issue.code === "missing-retention-schedule-document",
+      commands: resourceId
+        ? ["npx filegrc guide document --json", `npx filegrc get ${shellArgument(resourceId)} --mutation > MUTATION.json`, `npx filegrc update document ${shellArgument(resourceId)} MUTATION.json --json`]
+        : issue.code === "missing-retention-schedule-document"
+          ? ["npx filegrc guide document --json", 'npx filegrc scaffold document --title "Data Retention Schedule" > MUTATION.json', "npx filegrc create MUTATION.json --json"]
+          : ["npx filegrc guide document --json", "npx filegrc list document --workflow --json"]
+    };
+  }
+  if (["retention-row-wrong-schedule-document", "incomplete-retention-schedule-row"].includes(issue.code)) {
+    const row = rows.find(({ id }) => id === issue.resourceId);
+    if (row) return {
+      title: `Complete ${row.title}`,
+      resourceType: "retention-schedule-item",
+      resourceId: row.id,
+      commands: ["npx filegrc guide retention-schedule-item --json", `npx filegrc get ${shellArgument(row.id)} --mutation > MUTATION.json`, `npx filegrc update retention-schedule-item ${shellArgument(row.id)} MUTATION.json --json`]
+    };
+  }
+  if (issue.code === "unreviewed-similar-information-types") return {
+    title: "Review similar Information Types",
+    resourceType: "information-type",
+    commands: ["npx filegrc list information-type --workflow --json", "npx filegrc review-collection information-type --scaffold > REVIEW.json", "npx filegrc review-collection information-type REVIEW.json --preview --json", "npx filegrc review-collection information-type REVIEW.json --yes --json"]
+  };
+  return {
+    title: "Complete retention schedule coverage",
+    resourceType: "retention-schedule-item",
+    commands: ["npx filegrc guide retention-schedule-item --json", "npx filegrc list retention-schedule-item --workflow --json", 'npx filegrc scaffold retention-schedule-item --title "RETENTION RULE" > MUTATION.json', "npx filegrc create MUTATION.json --json"]
+  };
+}
+
 function requiredAppointmentsItem(records, model) {
   const assessments = assessRequiredAppointments(records, model);
   const incomplete = assessments.filter(({ requiredness, state }) => (

package/src/reconciliation.js

@@ -769,6 +769,7 @@ function validateMergeIdentities(index, model) {
     const identities = new Map();
     for (const parent of parents) {
       const state = recordStateAtCommit(index, model, parent);
+      if (!state) continue;
       let snapshot = snapshots.get(state);
       if (!snapshot) {
         snapshot = state.snapshot || snapshotRecordState(state);

package/src/retention-schedule-approval.js

@@ -43,7 +43,7 @@ export function retentionScheduleApprovalIssues(loaded, program, rows, options =
     || !substantiveMarkdown(scheduleContent)
     || openPlaceholderCount(scheduleContent) > 0)
   ) {
-    issues.push(issue("incomplete-retention-schedule-document", "Complete the Data Retention Schedule document, its owner, linked Control, and Markdown before requesting approval of the complete schedule."));
+    issues.push(issue("incomplete-retention-schedule-document", "Complete the Data Retention Schedule document, its owner, linked Control, and Markdown before requesting approval of the complete schedule.", schedule.id));
   }
   if (
     schedule
@@ -60,7 +60,7 @@ export function retentionScheduleApprovalIssues(loaded, program, rows, options =
     ? activeRows.filter(({ scheduleDocumentId }) => scheduleDocumentId !== schedule.id)
     : [];
   if (mismatched.length) {
-    issues.push(issue("retention-row-wrong-schedule-document", `Link every active retention row to the current Data Retention Schedule document before approval: ${mismatched[0].title}.`));
+    issues.push(issue("retention-row-wrong-schedule-document", `Link every active retention row to the current Data Retention Schedule document before approval: ${mismatched[0].title}.`, mismatched[0].id));
   }
   const revisions = resourceReviewRevisionsSync(
     loaded,
@@ -68,7 +68,7 @@ export function retentionScheduleApprovalIssues(loaded, program, rows, options =
   );
   const incomplete = activeRows.filter((row) => !retentionRuleIsCurrent(row, revisions, byId, loaded));
   if (incomplete.length) {
-    issues.push(issue("incomplete-retention-schedule-row", `Complete the retention decisions before approving the schedule revision: ${incomplete[0].title}.`));
+    issues.push(issue("incomplete-retention-schedule-row", `Complete the retention decisions before approving the schedule revision: ${incomplete[0].title}.`, incomplete[0].id));
   }
   const proposedRows = rows.filter(rowProposesCoverage);
   const scopedPrograms = program.programIds
@@ -96,8 +96,8 @@ function sameIds(left = [], right = []) {
   return JSON.stringify([...left].sort()) === JSON.stringify([...right].sort());
 }
 
-function issue(code, message) {
-  return { code, message };
+function issue(code, message, resourceId) {
+  return { code, message, ...(resourceId ? { resourceId } : {}) };
 }
 
 function primaryMarkdown(loaded, record) {

package/src/web.js

@@ -578,8 +578,8 @@ function readinessOverview() {
     const stage = READINESS_STAGES.find((candidate) => candidate.id === id);
     const current = stageProgress(stage);
     const remaining = current.total - current.complete;
-    const status = !remaining ? "Ready" : current.complete ? remaining + " pages need work" : "Needs work";
-    return [stage.title, stage.summary, href, status, !remaining ? "good" : current.complete ? "warn" : "neutral"];
+    const status = current.status === "In progress" ? remaining + " pages need work" : current.status;
+    return [stage.title, stage.summary, href, status, current.tone];
   };
   const stages = [
     programStage("scope", "#/stage/scope"),
@@ -787,6 +787,7 @@ function wireRetentionScheduleTable(total, initialPage = 1) {
 function renderRetentionScheduleIssues() {
   const actions = retentionSchedulePageItems().filter((item) => (
     item.id !== "collection-review-retention-schedule-item"
+      || !item.commands?.some((command) => command.includes(" review-collection retention-schedule-item"))
   ));
   if (!actions.length) return "";
   return '<section class="retention-issues"><div class="section-head"><div><p class="kicker">Before approval</p><h2>Items to resolve</h2></div></div><div class="retention-issue-list">' + actions.map((item) => {
@@ -1719,7 +1720,7 @@ function retentionSchedulePageItems() {
         key: item.id,
         state: "ready",
         href: item.id === "collection-review-retention-schedule-item"
-          ? "#/retention-schedule"
+          ? retentionCollectionActionHref(item)
           : item.id?.startsWith("retention-use-")
             ? retentionScheduleItemHref(item)
             : item.resourceId && item.resourceType
@@ -1732,6 +1733,19 @@ function retentionSchedulePageItems() {
   ]);
 }
 
+function retentionCollectionActionHref(item) {
+  if (item.resourceType === "document") return item.resourceId
+    ? '#/resource/document/' + encodeURIComponent(item.resourceId) + '?stage=policies'
+    : item.createResource
+      ? '#/resources/document?new=1&documentScope=program&documentKind=schedule&programRole=required&title=Data%20Retention%20Schedule'
+      : '#/resources/document';
+  if (item.resourceType === "information-type") return '#/resources/information-type?review-collection=1';
+  if (item.resourceType === "retention-schedule-item" && item.resourceId && item.resourceId !== item.id) {
+    return '#/resource/retention-schedule-item/' + encodeURIComponent(item.resourceId) + '?stage=policies';
+  }
+  return "#/retention-schedule";
+}
+
 function distinctPageActionItems(items) {
   const distinct = new Map();
   for (const item of items) {
@@ -1842,14 +1856,14 @@ function derivedStagePageState(stage, destination) {
       .filter(({ id }) => id.startsWith("source-family-")) || [];
     const incomplete = evidenceItems.filter(({ status }) => status !== "complete").length;
     return incomplete
-      ? { complete: false, label: incomplete + " " + pluralize("source", incomplete) + " need work" }
+      ? { complete: false, label: incomplete + " " + pluralize("source", incomplete) + (incomplete === 1 ? " needs work" : " need work") }
       : { complete: evidenceItems.length > 0, label: evidenceItems.length ? "Ready" : "Not configured", countsTowardProgress: evidenceItems.length > 0 };
   }
   if (destination.utility === "retention-schedule") {
     const incomplete = retentionSchedulePageItems().length;
     return !incomplete
       ? { complete: true, label: "Approved" }
-      : { complete: false, label: incomplete ? incomplete + " " + pluralize("item", incomplete) + " need work" : "Approval needed" };
+      : { complete: false, label: incomplete ? incomplete + " " + pluralize("item", incomplete) + (incomplete === 1 ? " needs work" : " need work") : "Approval needed" };
   }
   const items = stagePageItems(stage, destination);
   const deferredStates = new Set(["later", "scheduled", "upcoming", "waiting-external"]);
@@ -3223,6 +3237,7 @@ function renderList(main, type, params = new URLSearchParams()) {
       ...(params.get("title") ? { title: params.get("title") } : {}),
       ...(params.get("documentKind") ? { documentKind: params.get("documentKind") } : {}),
       ...(documentScope ? { workflowScope: documentScope } : {}),
+      ...(params.get("programRole") ? { programRole: params.get("programRole") } : {}),
       ...relationshipSeed
     } : {
       ...(params.get("title") ? { title: params.get("title") } : {}),