filegrc 0.3.4 → 0.5.0

package/src/audit-transition.js

@@ -0,0 +1,96 @@
+import { createResource } from "./files.js";
+import { createResourceId } from "./id.js";
+import { loadWorkspace } from "./workspace.js";
+
+export async function planNextAuditCycle(input = process.cwd(), options = {}) {
+  const loaded = await loadWorkspace(input);
+  if (String(loaded.model.modelVersion) !== "3") {
+    throw new Error("Audit-cycle carry-forward requires a model v3 workspace.");
+  }
+  const prior = loaded.resources.find((record) => (
+    record.type === "audit" && record.id === options.priorAuditId
+  ));
+  if (!prior) throw new Error("A prior Audit record is required.");
+  const startsOn = required(options.startsOn, "Next period start");
+  const endsOn = required(options.endsOn, "Next period end");
+  if (startsOn > endsOn) throw new Error("The next period end must be on or after its start.");
+  const priorEnd = prior.coverage?.endsOn || prior.coverage?.on;
+  if (prior.auditKind === "soc-2-type-1" && priorEnd && startsOn <= priorEnd) {
+    throw new Error(`A Type 2 operating period must start after the Type 1 as-of date ${priorEnd}.`);
+  }
+  const title = String(options.title || nextTitle(prior, startsOn, endsOn)).trim();
+  const audit = {
+    id: options.id || createResourceId("audit", title, loaded.resources.map(({ id }) => id)),
+    type: "audit",
+    title,
+    status: "planned",
+    auditKind: "soc-2-type-2",
+    priorAuditId: prior.id,
+    coverage: { kind: "range", startsOn, endsOn },
+    frameworkIds: [...(prior.frameworkIds || [])],
+    systemIds: [...(prior.systemIds || [])],
+    requirementIds: [...(prior.requirementIds || [])],
+    controlIds: [...(prior.controlIds || [])],
+    complementaryControlIds: [...(prior.complementaryControlIds || [])],
+    subserviceVendorIds: [...(prior.subserviceVendorIds || [])],
+    ...(prior.subserviceMethod ? { subserviceMethod: prior.subserviceMethod } : {}),
+    ...(prior.complementaryControlsConclusion
+      ? { complementaryControlsConclusion: prior.complementaryControlsConclusion }
+      : {}),
+    ...(prior.auditorVendorId ? { auditorVendorId: prior.auditorVendorId } : {}),
+    contactIds: [...(prior.contactIds || [])],
+    ownerIds: [...(prior.ownerIds || [])],
+    signatoryAppointmentIds: [...(prior.signatoryAppointmentIds || [])],
+    scope: String(options.scope || prior.scope || "").trim(),
+    ...(String(options.scopeRevision || "").trim()
+      ? { scopeRevision: String(options.scopeRevision).trim() }
+      : {})
+  };
+  return {
+    operation: prior.auditKind === "soc-2-type-1" ? "type-1-to-type-2" : "next-audit-cycle",
+    priorAuditId: prior.id,
+    audit,
+    carriedForward: [
+      "frameworkIds",
+      "systemIds",
+      "requirementIds",
+      "controlIds",
+      "complementaryControlIds",
+      "subserviceVendorIds",
+      "subserviceMethod",
+      "auditorVendorId",
+      "contactIds",
+      "ownerIds",
+      "signatoryAppointmentIds",
+      "scope"
+    ],
+    reviewRequired: [
+      "coverage",
+      "scopeRevision",
+      "criteria and control changes since the prior audit",
+      "source and policy continuity",
+      "subservice assurance coverage",
+      "new or changed commitments"
+    ]
+  };
+}
+
+export async function createNextAuditCycle(input = process.cwd(), options = {}) {
+  if (options.confirmed !== true) {
+    throw new Error("Preview the next audit cycle and confirm the write.");
+  }
+  const plan = await planNextAuditCycle(input, options);
+  const result = await createResource(input, plan.audit);
+  return { ...plan, result };
+}
+
+function required(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${label} is required.`);
+  return normalized;
+}
+
+function nextTitle(prior, startsOn, endsOn) {
+  const year = endsOn.slice(0, 4) || startsOn.slice(0, 4);
+  return `${year} SOC 2 Type 2 audit after ${prior.title}`;
+}

package/src/batch-review.js

@@ -0,0 +1,109 @@
+import { applyResourceBatch } from "./files.js";
+import { getGitSummary } from "./git.js";
+import { loadWorkspace } from "./workspace.js";
+
+const REVIEWABLE_TYPES = new Set([
+  "requirement",
+  "control",
+  "commitment",
+  "complementary-control"
+]);
+
+export async function scaffoldApplicabilityReview(input = process.cwd(), options = {}) {
+  const loaded = await loadWorkspace(input);
+  if (String(loaded.model.modelVersion) !== "3") {
+    throw new Error("Batch applicability review requires a model v3 workspace.");
+  }
+  const requestedType = options.type ? String(options.type) : null;
+  if (requestedType && !REVIEWABLE_TYPES.has(requestedType)) {
+    throw new Error(`Applicability review type must be one of ${[...REVIEWABLE_TYPES].join(", ")}.`);
+  }
+  const records = loaded.resources.filter((record) => (
+    REVIEWABLE_TYPES.has(record.type)
+    && (!requestedType || record.type === requestedType)
+    && !record.applicabilityReview
+    && !["retired", "superseded"].includes(record.status)
+  ));
+  return {
+    reviewedByIds: [],
+    reviewedOn: null,
+    decisions: records
+      .sort((left, right) => `${left.type}:${left.title}:${left.id}`.localeCompare(`${right.type}:${right.title}:${right.id}`))
+      .map((record) => ({
+        id: record.id,
+        decision: null,
+        rationale: null
+      }))
+  };
+}
+
+export async function planApplicabilityReview(input = process.cwd(), options = {}) {
+  const loaded = await loadWorkspace(input);
+  if (String(loaded.model.modelVersion) !== "3") {
+    throw new Error("Batch applicability review requires a model v3 workspace.");
+  }
+  if (!Array.isArray(options.decisions) || !options.decisions.length) {
+    throw new Error("Applicability review needs at least one decision.");
+  }
+  const byId = new Map(loaded.resources.map((record) => [record.id, record]));
+  const update = options.decisions.map((decision) => {
+    const record = byId.get(decision.id);
+    if (!record || !REVIEWABLE_TYPES.has(record.type)) {
+      throw new Error(`Resource "${decision.id}" is not an applicability-review record.`);
+    }
+    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)) {
+      throw new Error(`Decision for "${record.id}" must be applicable, not-applicable, externally-managed, or zero-population.`);
+    }
+    if (!reviewedByIds.length || !reviewedOn || !rationale) {
+      throw new Error(`Decision for "${record.id}" needs a reviewer, review date, and rationale.`);
+    }
+    const next = {
+      ...record,
+      applicabilityReview: {
+        decision: result,
+        rationale,
+        reviewedByIds,
+        reviewedOn,
+        scopeRevision
+      }
+    };
+    if (record.type === "requirement") {
+      if (!["applicable", "not-applicable"].includes(result)) {
+        throw new Error(`Requirement "${record.id}" must be applicable or not-applicable.`);
+      }
+      next.applicability = result;
+      next.applicabilityRationale = rationale;
+    }
+    if (record.type === "control" && result === "not-applicable") next.status = "not-applicable";
+    if (record.type === "control" && result === "applicable" && record.status === "not-applicable") next.status = "planned";
+    return next;
+  });
+  return {
+    operation: "applicability-review",
+    reviewedIds: update.map(({ id }) => id),
+    changes: {
+      update,
+      expectedRevisions: options.expectedRevisions || {},
+      validateWholeWorkspace: true
+    }
+  };
+}
+
+export async function applyApplicabilityReview(input = process.cwd(), options = {}) {
+  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 };
+}