filegrc 0.15.0 → 0.15.2

package/src/retention.js

@@ -10,18 +10,26 @@ export async function assessRetentionReadiness(loaded, program, options = {}) {
   if (!loaded.model.resources["retention-schedule-item"]) return [];
   const byId = new Map(loaded.resources.map((record) => [record.id, record]));
   const rules = loaded.resources.filter((record) => (
-    record.type === "retention-schedule-item" && record.status === "active"
+    record.type === "retention-schedule-item"
+    && !["retired", "superseded"].includes(record.status)
   ));
-  const revisions = await resourceReviewRevisions(loaded, rules.flatMap((rule) => retentionReviewResourceIds(rule, loaded)));
-  const usableRules = rules.filter((rule) => retentionRuleIsCurrent(rule, revisions, byId, loaded));
+  const activeRules = rules.filter(({ status }) => status === "active");
+  const revisions = await resourceReviewRevisions(loaded, activeRules.flatMap((rule) => retentionReviewResourceIds(rule, loaded)));
+  const usableRules = activeRules.filter((rule) => retentionRuleIsCurrent(rule, revisions, byId, loaded));
+  const proposedRules = rules.filter(retentionRuleHasCoverageProposal);
   const uses = retentionUses(loaded, program);
-  const items = rules.filter((rule) => !usableRules.includes(rule)).map((rule) => readinessItem(
+  const items = rules.map((rule) => readinessItem(
     `retention-rule-${rule.id}`,
-    "action",
-    `Review ${rule.title}`,
-    "This active retention schedule item is incomplete or is not bound to every current source revision. Review it before relying on its period or disposition behavior.",
+    usableRules.includes(rule) ? "complete" : "action",
+    usableRules.includes(rule) ? `${rule.title} proposal is ready` : `Finish ${rule.title}`,
+    usableRules.includes(rule)
+      ? "The owner completed this row and bound it to its current source revisions. It will become part of the authoritative schedule only when the complete schedule is approved."
+      : rule.status === "planned"
+        ? "Finish the type, scope, cutoff, period, disposition, sources, and owner review for this proposed row before requesting schedule approval."
+        : "This row is incomplete or is not bound to every current source revision. Review it before requesting schedule approval.",
     rule,
     {
+      coverageState: usableRules.includes(rule) ? "proposed" : "incomplete",
       sourceResourceIds: retentionReviewResourceIds(rule, loaded),
       commands: [
         `npx filegrc get ${rule.id} --mutation`,
@@ -32,22 +40,52 @@ export async function assessRetentionReadiness(loaded, program, options = {}) {
       ]
     }
   ));
-  items.push(...uses.map((use) => {
-    const matches = usableRules.filter((rule) => ruleCoversUse(rule, use, program));
+  const usesByInformationType = new Map();
+  for (const use of uses) {
+    const grouped = usesByInformationType.get(use.informationTypeId) || [];
+    grouped.push(use);
+    usesByInformationType.set(use.informationTypeId, grouped);
+  }
+  items.push(...[...usesByInformationType].map(([informationTypeId, informationTypeUses]) => {
+    const absentUses = informationTypeUses.filter((use) => (
+      !proposedRules.some((rule) => ruleCoversUse(rule, use, program))
+    ));
+    const pendingUses = informationTypeUses.filter((use) => (
+      !usableRules.some((rule) => ruleCoversUse(rule, use, program))
+    ));
+    const approvalPending = !options.scheduleApproved;
+    const matches = usableRules.filter((rule) => (
+      informationTypeUses.some((use) => ruleCoversUse(rule, use, program))
+    ));
+    const informationTypeTitle = byId.get(informationTypeId)?.title || informationTypeId;
+    const affectedTitles = absentUses.map(({ resource }) => resource.title);
+    const affectedSummary = affectedTitles.length > 3
+      ? `${affectedTitles.slice(0, 3).join(", ")}, and ${affectedTitles.length - 3} more`
+      : affectedTitles.join(", ");
     return readinessItem(
-      `retention-use-${use.resource.id}-${use.informationTypeId}`,
-      matches.length ? "complete" : "action",
-      `Decide retention for ${byId.get(use.informationTypeId)?.title || use.informationTypeId}`,
-      matches.length
-        ? `${use.resource.title} is covered by ${matches.map(({ title }) => title).join(", ")}.`
-        : `${use.resource.title} uses this Information Type, but no active, current retention schedule item covers both the type and scope. Management must choose the cutoff, period, and disposition.`,
-      use.resource,
+      `retention-use-${informationTypeId}`,
+      absentUses.length ? "action" : pendingUses.length || approvalPending ? "info" : "complete",
+      `Decide retention for ${informationTypeTitle}`,
+      absentUses.length
+        ? `${affectedTitles.length} in-scope ${affectedTitles.length === 1 ? "resource uses" : "resources use"} this Information Type without an active, current retention decision, including ${affectedSummary}. Management must choose the cutoff, period, disposition, and whether one program-wide rule or separate scoped rules apply.`
+        : pendingUses.length
+          ? `Proposed rows cover every in-scope type-and-scope pair. Finish the row review, then approve the complete schedule once instead of approving these coverage checks separately.`
+          : approvalPending
+            ? "Completed row proposals cover every in-scope type-and-scope pair. Approve the complete schedule once; these derived checks are not separate approval work."
+          : `The approved schedule covers all ${informationTypeUses.length} in-scope ${informationTypeUses.length === 1 ? "use" : "uses"}.`,
+      { type: "retention-schedule-item" },
       {
-        informationTypeId: use.informationTypeId,
+        progressUnit: false,
+        coverageState: absentUses.length ? "absent" : pendingUses.length || approvalPending ? "proposed" : "approved",
+        informationTypeId,
+        affectedResourceIds: absentUses.map(({ resource }) => resource.id),
+        retentionScopeResourceIds: absentUses.length === informationTypeUses.length
+          ? [program.id]
+          : absentUses.map(({ resource }) => resource.id),
         retentionScheduleItemIds: matches.map(({ id }) => id),
         commands: [
           "npx filegrc guide retention-schedule-item --json",
-          `npx filegrc scaffold retention-schedule-item --title ${shellArgument(`Retention for ${byId.get(use.informationTypeId)?.title || use.informationTypeId}`)}`
+          `npx filegrc scaffold retention-schedule-item --title ${shellArgument(`Retention for ${informationTypeTitle}`)}`
         ]
       }
     );
@@ -55,6 +93,11 @@ export async function assessRetentionReadiness(loaded, program, options = {}) {
 
   for (const coverage of loaded.resources.filter((record) => record.type === "source-coverage" && record.status === "active")) {
     const linked = (coverage.retentionScheduleItemIds || []).map((id) => byId.get(id)).filter(Boolean);
+    const proposed = linked.filter((rule) => (
+      rule.type === "retention-schedule-item"
+      && proposedRules.includes(rule)
+      && (rule.scopeResourceIds || []).includes(coverage.id)
+    ));
     const matching = linked.filter((rule) => (
       rule.type === "retention-schedule-item"
       && rule.status === "active"
@@ -63,13 +106,17 @@ export async function assessRetentionReadiness(loaded, program, options = {}) {
     ));
     items.push(readinessItem(
       `retention-source-coverage-${coverage.id}`,
-      matching.length ? "complete" : "action",
+      matching.length && options.scheduleApproved ? "complete" : proposed.length ? "info" : "action",
       `Confirm retained evidence for ${coverage.title}`,
-      matching.length
+      matching.length && options.scheduleApproved
         ? `The source-coverage record references a current schedule item scoped to this population.`
-        : `The source-coverage record must reference an active, current schedule item whose scope includes ${coverage.id}. A draft schedule or unrelated rule does not satisfy this check.`,
+        : proposed.length
+          ? "A proposed schedule row covers this evidence source. Finish that row and approve the complete schedule before relying on it."
+          : `No proposed schedule row covers ${coverage.id}. Add the genuine type-and-scope decision before schedule approval.`,
       coverage,
       {
+        progressUnit: false,
+        coverageState: matching.length && options.scheduleApproved ? "approved" : proposed.length ? "proposed" : "absent",
         retentionScheduleItemIds: matching.map(({ id }) => id),
         commands: [
           `npx filegrc get ${coverage.id} --mutation`,
@@ -198,8 +245,11 @@ function reviewSource(loaded, entry) {
     && entry.record.workflowScope === "program"
   ) {
     const approved = structuredClone(entry.record);
-    if (approved.status === "active") approved.status = "approved";
     for (const field of [
+      "status",
+      "approverIds",
+      "approvedOn",
+      "approvedContentRevisions",
       "activationBasis",
       "activatedByIds",
       "activatedOn",
@@ -232,6 +282,14 @@ function ruleCoversUse(rule, use, program) {
   return scope.has(use.resource.id) || scope.has(program.id);
 }
 
+function retentionRuleHasCoverageProposal(rule) {
+  return Boolean(
+    (rule.informationTypeIds || []).length
+    && (rule.scopeResourceIds || []).length
+    && rule.scheduleDocumentId
+  );
+}
+
 export function retentionReviewResourceIds(rule, loaded) {
   const programUseIds = [];
   if (loaded) {
@@ -259,7 +317,7 @@ export function retentionRuleIsCurrent(rule, revisions, byId = new Map(), loaded
   if (!(rule.informationTypeIds || []).length || !(rule.scopeResourceIds || []).length || !rule.scheduleDocumentId) return false;
   const schedule = byId.get(rule.scheduleDocumentId);
   if (schedule?.type !== "document" || schedule.documentKind !== "schedule" || schedule.workflowScope !== "program" || ["superseded", "retired"].includes(schedule.status)) return false;
-  if (!(rule.ownerIds || []).length || !(rule.approvedByIds || []).length || !rule.approvedOn) return false;
+  if (!(rule.ownerIds || []).length) return false;
   if (!rule.reviewedSourceRevisions || typeof rule.reviewedSourceRevisions !== "object") return false;
   if (!retentionCutoffIsComplete(rule.cutoff) || !retentionPeriodIsComplete(rule.retentionPeriod)) return false;
   if (!["delete", "destroy", "erase", "anonymize", "transfer", "retain-permanently"].includes(rule.dispositionAction)) return false;

package/src/server.js

@@ -33,6 +33,7 @@ import {
   pushWorkspace,
   retryBrowserSync,
   runBrowserMutation,
+  synchronizeBrowserStartup,
   withGitCommandCache,
   withGitCommandDeadline
 } from "./git.js";
@@ -777,6 +778,18 @@ export async function serveWorkspace(input = process.cwd(), options = {}) {
   if (!Number.isInteger(port) || port < 0 || port > 65_535) {
     throw new Error("The server port must be an integer from 0 through 65535.");
   }
+  let startupSynchronization;
+  try {
+    startupSynchronization = await synchronizeBrowserStartup(input, {
+      allowNonAuthoritativeWrites: options.allowNonAuthoritativeWrites === true
+    });
+  } catch (error) {
+    startupSynchronization = {
+      status: "failed",
+      updated: false,
+      message: error.message
+    };
+  }
   const loaded = await loadWorkspace(input);
   getResourceDefinition(loaded.model, "workspace");
   const server = createFilegrcServer(loaded.root, {
@@ -806,7 +819,8 @@ export async function serveWorkspace(input = process.cwd(), options = {}) {
     address: server.address(),
     url: `http://${urlHost(host)}:${server.address().port}`,
     requestedPort: port,
-    usedFallbackPort
+    usedFallbackPort,
+    startupSynchronization
   };
 }
 

package/src/source-coverage.js

@@ -1,4 +1,7 @@
 import { resourceReviewRevisions, retentionReviewResourceIds, retentionRuleIsCurrent } from "./retention.js";
+import { retentionScheduleIsAuthoritative } from "./collection-review.js";
+import { modelSupports } from "../model/index.js";
+import { resolveProgram } from "./program.js";
 
 export async function sourceCoverageComplete(record, loaded, program = loaded.workspace) {
   const structuredRetention = loaded.model.resources["retention-schedule-item"];
@@ -6,6 +9,10 @@ export async function sourceCoverageComplete(record, loaded, program = loaded.wo
     return false;
   }
   if (structuredRetention) {
+    const retentionProgram = modelSupports(loaded.model, "program-scope")
+      ? resolveProgram(loaded, program?.type === "program" ? program.id : undefined)
+      : program;
+    if (!retentionScheduleIsAuthoritative(loaded, retentionProgram)) return false;
     const linkedRules = (record.retentionScheduleItemIds || []).map((id) => (
       loaded.resources.find((resource) => resource.id === id && resource.type === "retention-schedule-item")
     ));

package/src/state.js

@@ -347,6 +347,8 @@ function serializeCollectionReviewAssessment(assessment) {
     status: assessment.status,
     complete: assessment.complete,
     message: assessment.message,
+    ...(assessment.recordProposals ? { recordProposals: assessment.recordProposals } : {}),
+    ...(assessment.incompleteRecordProposals ? { incompleteRecordProposals: assessment.incompleteRecordProposals } : {}),
     ...(assessment.eligibleReviewerIds ? { eligibleReviewerIds: assessment.eligibleReviewerIds } : {}),
     ...(assessment.reviewerConflictIds ? { reviewerConflictIds: assessment.reviewerConflictIds } : {}),
     ...(assessment.approvalIssues ? { approvalIssues: assessment.approvalIssues } : {})

package/src/validate.js

@@ -3,7 +3,7 @@ import { createReadStream } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
 import { performance } from "node:perf_hooks";
 import { getResourceDefinition, modelSupports } from "../model/index.js";
-import { scopedCollectionRecords, selectScopedCollectionRecords } from "./collection-scope.js";
+import { collectionRecordProposals, retentionScheduleReviewScope, scopedCollectionRecords, selectScopedCollectionRecords } from "./collection-scope.js";
 import {
   collectionRevision,
   collectionRevisionMatches
@@ -1224,6 +1224,10 @@ function sameRouteProposal(proposal, finalized) {
   return [...keys].every((key) => allowed.has(key) || JSON.stringify(proposal[key]) === JSON.stringify(finalized[key]));
 }
 
+function sameStringIds(left = [], right = []) {
+  return JSON.stringify([...left].sort()) === JSON.stringify([...right].sort());
+}
+
 function validateTimestampTimezone(value, timezone, path, diagnostics, label) {
   if (!value || !timezone) return;
   const source = String(value);
@@ -1252,10 +1256,19 @@ function validateCollectionReview(record, loaded, byId, path, diagnostics) {
   const program = modelSupports(model, "program-scope")
     ? (record.scopeResourceIds || []).map((id) => byId.get(id)).find(({ type } = {}) => type === "program")
     : null;
+  const workspaceWideRetentionReview = record.resourceType === "retention-schedule-item"
+    && modelSupports(model, "retention-schedule-approval");
+  const retentionScope = workspaceWideRetentionReview ? retentionScheduleReviewScope(loaded) : null;
   const recordCount = scopedCollectionRecords(loaded, record.resourceType, program).length;
   const currentPopulationIds = scopedCollectionRecords(loaded, record.resourceType, program)
     .map(({ id }) => id)
     .sort();
+  const incompleteProposals = collectionRecordProposals(
+    loaded,
+    record.resourceType,
+    scopedCollectionRecords(loaded, record.resourceType, program),
+    program
+  ).filter(({ complete }) => !complete);
   const currentRevision = collectionRevision(loaded, record.resourceType, {
     program,
     authoritativeSourceId: record.decision === "externally-managed"
@@ -1274,6 +1287,20 @@ function validateCollectionReview(record, loaded, byId, path, diagnostics) {
       currentRevision
     }
   );
+  if (current && workspaceWideRetentionReview && !sameStringIds(record.scopeResourceIds, retentionScope.programIds)) {
+    diagnostics.push(error(
+      "invalid-retention-schedule-review-scope",
+      path,
+      "The current Data Retention Schedule review must cover every active Program as one workspace-wide approval."
+    ));
+  }
+  if (current && incompleteProposals.length) {
+    diagnostics.push(error(
+      "incomplete-collection-review-proposals",
+      path,
+      `Complete every ${configuration.title.toLowerCase()} record proposal before the collection review. Remaining: ${incompleteProposals.map(({ title }) => title).join(", ")}.`
+    ));
+  }
   if (current && record.resourceType === "control") {
     const controls = scopedCollectionRecords(loaded, "control", program);
     const controlIds = new Set(controls.map(({ id }) => id));
@@ -1299,8 +1326,11 @@ function validateCollectionReview(record, loaded, byId, path, diagnostics) {
   }
   if (current && record.resourceType === "retention-schedule-item" && modelSupports(model, "retention-schedule-approval")) {
     const rows = scopedCollectionRecords(loaded, record.resourceType, program);
-    for (const issue of retentionScheduleApprovalIssues(loaded, program || {}, rows, {
-      informationTypesReviewed: collectionReviewIsCurrent(loaded, "information-type", program)
+    for (const issue of retentionScheduleApprovalIssues(loaded, retentionScope, rows, {
+      informationTypesReviewed: retentionScope.programIds.every((id) => (
+        collectionReviewIsCurrent(loaded, "information-type", byId.get(id))
+      )),
+      approvalReview: record
     })) {
       diagnostics.push(error(issue.code, path, issue.message));
     }