filegrc 0.3.4 → 0.5.0

package/src/model-docs.js

@@ -15,7 +15,7 @@ export function generateModelDocumentation(model) {
     "",
     "## Program path",
     "",
-    "The renderer, CLI, generated agent instructions, and this reference use the same six-step lifecycle:",
+    "The renderer, CLI, generated agent instructions, and this reference use the same five-step lifecycle:",
     "",
     ...programPath.flatMap((stage) => [
       `### Step ${stage.number}. ${stage.title}`,
@@ -35,6 +35,62 @@ export function generateModelDocumentation(model) {
       ...stage.commands.map((command) => `- \`${command}\``),
       ""
     ]),
+    "## Relation groups",
+    "",
+    "Relationship fields use the named groups below. The registry expands each group to explicit resource types, so no relationship accepts an unrestricted wildcard.",
+    "",
+    "| Group | Resource types |",
+    "| --- | --- |",
+    ...Object.entries(model.relationGroups || {}).map(([name, types]) => (
+      `| \`${name}\` | ${types.map((type) => `\`${type}\``).join(", ")} |`
+    )),
+    "",
+    "## Collection review confirmations",
+    "",
+    "FileGRC derives record issues, but it cannot infer that management reviewed an apparently complete or empty collection. Each configured collection review records the conclusion, reviewer, date, current scope revision, and exact collection revision. A record or material scope change makes the confirmation stale.",
+    "",
+    "| Resource type | Review | Allowed conclusions | What to review |",
+    "| --- | --- | --- | --- |",
+    ...Object.entries(model.collectionReviews || {}).map(([type, review]) => (
+      `| \`${type}\` | ${escapeCell(review.title)} | ${review.decisions.map((decision) => `\`${decision}\``).join(", ")} | ${escapeCell(review.reviewPoints.join(" "))} |`
+    )),
+    "",
+    "## Relationship constraints",
+    "",
+    "Relationship constraints prevent cycles and duplicate active authority or access records.",
+    "",
+    ...((model.relationshipConstraints?.acyclic || []).map((constraint) => (
+      `- \`${constraint.resourceType}.${constraint.field}\` must be acyclic.`
+    ))),
+    ...((model.relationshipConstraints?.unique || []).map((constraint) => (
+      `- \`${constraint.resourceType}\` records in ${constraint.statuses.map((status) => `\`${status}\``).join(", ")} must be unique by ${constraint.fields.map((field) => `\`${field}\``).join(", ")}.`
+    ))),
+    "",
+    "## Obligation activities",
+    "",
+    "The model owns each activity name, allowed recurrence modes and scope types, its default completion record, and every record type that can prove completion.",
+    "",
+    "| Activity | Title | Recurrence | Scope resource types | Default completion | Accepted completion records |",
+    "| --- | --- | --- | --- | --- | --- |",
+    ...Object.entries(model.obligationActivities || {}).map(([name, activity]) => (
+      `| \`${name}\` | ${escapeCell(activity.title)} | ${activity.recurrenceModes.map((mode) => `\`${mode}\``).join(", ")} | ${activity.scopeResourceTypes.map((type) => `\`${type}\``).join(", ")} | \`${activity.completionType}\` | ${activity.completionResourceTypes.map((type) => `\`${type}\``).join(", ")} |`
+    )),
+    "",
+    "## Policy events",
+    "",
+    "The model owns each event title and the minimum and maximum count for each subject resource type.",
+    "",
+    "| Event | Title | Subject rules |",
+    "| --- | --- | --- |",
+    ...Object.entries(model.policyEvents || {}).map(([name, event]) => (
+      `| \`${name}\` | ${escapeCell(event.title)} | ${event.subjectRules.map(({ resourceType, minimum = 0, maximum }) => `\`${resourceType}\` ${minimum}..${Number.isInteger(maximum) ? maximum : "*"}`).join(", ")} |`
+    )),
+    "",
+    "## Nested object schemas",
+    "",
+    "Named object schemas reject unknown keys unless the schema explicitly allows a typed map or arbitrary JSON. Conditional properties are valid only for the selected discriminator.",
+    "",
+    ...Object.entries(model.objectTypes || {}).flatMap(([name, schema]) => objectTypeDocumentation(name, schema)),
     "## Common fields",
     "",
     "| Field | Type | Required | Meaning |",
@@ -53,7 +109,7 @@ export function generateModelDocumentation(model) {
     "",
     "## Program and audit readiness defaults",
     "",
-    "Program Readiness checks management scope, policy adoption, control implementation, authoritative source configuration, and verified test captures without requiring an audit record. Audit Readiness starts after a CPA firm is engaged and uses the defaults below to prepare Type 1 and Type 2 fieldwork.",
+    "Program Readiness checks management scope, policy adoption, control implementation, and authoritative evidence mapping without requiring an audit record. Audit Readiness starts after a CPA firm is engaged and uses the defaults below to prepare Type 1 and Type 2 fieldwork.",
     "",
     "Management documents:",
     "",
@@ -66,9 +122,9 @@ export function generateModelDocumentation(model) {
     "Authoritative systems of record:",
     "",
     ...model.evidenceSourceFamilies.map((item) => (
-      item.collectionTestRequired === false
-        ? `- **${item.title}** (${item.sourceKinds.map((kind) => `\`${kind}\``).join(", ")}): ${item.description} filegrc operating records: ${item.operationRecordTypes.map((type) => `\`${type}\``).join(", ")}. No separate collection test is required. ${item.timing}`
-        : `- **${item.title}** (${item.sourceKinds.map((kind) => `\`${kind}\``).join(", ")}): ${item.description} Test external collection: ${item.testPrompt} ${item.timing}`
+      item.filegrcManaged === true
+        ? `- **${item.title}** (${item.sourceKinds.map((kind) => `\`${kind}\``).join(", ")}): ${item.description} FileGRC operating records: ${item.operationRecordTypes.map((type) => `\`${type}\``).join(", ")}. Expected evidence: ${item.evidencePrompt} ${item.timing}`
+        : `- **${item.title}** (${item.sourceKinds.map((kind) => `\`${kind}\``).join(", ")}): ${item.description} Expected evidence: ${item.evidencePrompt} ${item.timing}`
     )),
     "",
     "## Resource groups",
@@ -84,6 +140,11 @@ export function generateModelDocumentation(model) {
       lines.push(`Instructions: ${RESOURCE_INSTRUCTIONS[type] || resource.description}`, "");
       lines.push(`Policy basis: ${resource.guidance.policyBasis}`, "");
       lines.push(`Timing: ${resource.guidance.cadence}`, "");
+      if (resource.guidance.reviewPoints?.length) {
+        lines.push("When reviewing:", "");
+        for (const point of resource.guidance.reviewPoints) lines.push(`- ${point}`);
+        lines.push("");
+      }
       if (resource.guidance.sourceResourceIds?.length) {
         lines.push(`Default sources: ${resource.guidance.sourceResourceIds.map((id) => `\`${id}\``).join(", ")}`, "");
       }
@@ -143,7 +204,12 @@ function choiceLabel(name) {
 }
 
 function fieldType(field) {
-  if (field.type === "array") return `array of ${field.items ?? "values"}`;
+  if (field.type === "array") {
+    return field.itemObjectType
+      ? `array of object (\`${field.itemObjectType}\`)`
+      : `array of ${field.items ?? "values"}`;
+  }
+  if (field.type === "object" && field.objectType) return `object (\`${field.objectType}\`)`;
   return field.format && field.format !== field.type ? `${field.type} (${field.format})` : field.type;
 }
 
@@ -151,14 +217,44 @@ function fieldNotes(field) {
   return [
     field.label,
     field.values ? `Values: ${field.values.map((item) => `\`${item}\``).join(", ")}` : "",
+    field.registry ? `Values come from the \`${field.registry}\` registry.` : "",
+    field.relationGroup ? `Relation group: \`${field.relationGroup}\`.` : "",
     field.relation ? `References: ${field.relation.map((item) => `\`${item}\``).join(", ")}` : "",
     field.minimum !== undefined ? `Minimum: \`${field.minimum}\`.` : "",
     field.maximum !== undefined ? `Maximum: \`${field.maximum}\`.` : "",
+    field.managed ? "Managed by filegrc." : "",
     field.disjointFrom ? `Must not overlap \`${field.disjointFrom}\`.` : "",
-    field.requiredWhen ? `Required when ${Object.entries(field.requiredWhen).map(([key, value]) => `\`${key}\` is \`${value}\``).join(" and ")}` : ""
+    field.requiredWhen ? `Required when ${conditionText(field.requiredWhen)}.` : "",
+    field.allowedWhen ? `Allowed when ${conditionText(field.allowedWhen)}.` : ""
   ].filter(Boolean).join(" ");
 }
 
+function objectTypeDocumentation(name, schema) {
+  const lines = [`### \`${name}\``, ""];
+  const properties = Object.entries(schema.properties || {});
+  if (properties.length) {
+    const required = new Set(schema.required || []);
+    lines.push("| Property | Type | Required | Notes |", "| --- | --- | --- | --- |");
+    for (const [propertyName, property] of properties) {
+      const requiredLabel = required.has(propertyName)
+        ? "Yes"
+        : property.requiredWhen
+          ? "Conditional"
+          : "No";
+      lines.push(`| \`${propertyName}\` | ${fieldType(property)} | ${requiredLabel} | ${escapeCell(fieldNotes(property))} |`);
+    }
+  } else if (schema.additionalProperties === true) {
+    lines.push("Allows arbitrary JSON properties.");
+  } else if (schema.additionalProperties) {
+    lines.push(`Allows dynamic keys whose values are ${fieldType(schema.additionalProperties)}.`);
+  } else {
+    lines.push("Does not allow properties.");
+  }
+  if (schema.keyFormat) lines.push("", `Key format: \`${schema.keyFormat}\`.`);
+  lines.push("");
+  return lines;
+}
+
 function escapeCell(value) {
   return String(value).replaceAll("|", "\\|").replaceAll("\n", " ");
 }