filegrc 0.3.3 → 0.4.0

package/src/index.js

@@ -3,9 +3,9 @@ export { buildAgentGuide, findResourceReferences, listResourceTypes, scaffoldRes
 export { assessAuditPreparation, prepareAuditWorkspace } from "./audit-preparation.js";
 export { buildWorkspace } from "./build.js";
 export { generateEvidencePacket, prepareEvidencePacket, writeEvidencePacket } from "./evidence-packet.js";
-export { ensureEvidenceTestDrafts, planEvidenceTestDrafts } from "./evidence-tests.js";
 export {
   addEvidenceAttachment,
+  applyResourceBatch,
   createResource,
   createResourceAndLink,
   createResources,
@@ -18,14 +18,18 @@ export {
 export {
   commitAndPushWorkspace,
   commitWorkspace,
+  getBrowserRepositoryState,
   getFileHistory,
   getGitSummary,
   getWorkspaceHistories,
   pullWorkspace,
-  pushWorkspace
+  pushWorkspace,
+  retryBrowserSync,
+  runBrowserMutation
 } from "./git.js";
 export { generateModelDocumentation } from "./model-docs.js";
 export { renderMarkdown } from "./markdown.js";
+export { migrateModel, planModelMigration } from "./model-migration.js";
 export {
   completeObligationAction,
   completeObligationEvent,
@@ -33,11 +37,9 @@ export {
   createObligationEvent,
   planObligations
 } from "./obligations.js";
-export { assessProgramReadiness } from "./program-readiness.js";
+export { assessEvidenceMap, assessProgramReadiness } from "./program-readiness.js";
 export {
   buildAgentProgramPath,
-  policyEventName,
-  POLICY_EVENT_NAMES,
   PROGRAM_PATH,
   RESOURCE_INSTRUCTIONS,
   resourceProgramContext
@@ -50,9 +52,10 @@ export {
   nextCalendarOccurrence
 } from "./recurrence.js";
 export { searchResources, searchableValues } from "./search.js";
+export { effectiveResourceStatus } from "./resource-status.js";
 export { createFilegrcServer, serveWorkspace } from "./server.js";
 export { normalizeSetupPayload, planWorkspaceSetup, setupWorkspace, summarizeSetupResult } from "./setup.js";
-export { createAppState } from "./state.js";
+export { createAppState, createResourceDetail } from "./state.js";
 export { currentCalendarDate, formatCalendarDate, formatLocalDateTime } from "./time.js";
 export { validateWorkspace } from "./validate.js";
 export { indexResources, loadWorkspace } from "./workspace.js";

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,52 @@ 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(", ")} |`
+    )),
+    "",
+    "## 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 +99,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 +112,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",
@@ -143,7 +189,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 +202,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", " ");
 }