@topogram/cli 0.3.34

package/src/generator/context/digest.js

@@ -0,0 +1,182 @@
+import {
+  maintainedProofMetadata,
+  graphCounts,
+  relatedJourneysForCapability,
+  relatedProjectionsForCapability,
+  relatedWorkflowDocsForCapability,
+  summarizeById,
+  summarizeProjection,
+  summarizeStatement,
+  verificationIdsForTarget,
+  workspaceInventory
+} from "./shared.js";
+import {
+  defaultOwnershipBoundary,
+  reviewBoundaryForEntity,
+  reviewBoundaryForJourneyDoc,
+  reviewBoundaryForWorkflowDoc
+} from "../../policy/review-boundaries.js";
+
+function workspaceDigest(graph) {
+  const inventory = workspaceInventory(graph);
+
+  return {
+    type: "context_digest",
+    version: 1,
+    focus: {
+      kind: "workspace",
+      id: "workspace"
+    },
+    workspace: {
+      root: graph.root,
+      counts: graphCounts(graph)
+    },
+    inventory,
+    review_boundary: {
+      automation_class: "manual_decision",
+      reasons: ["workspace_requires_scoped_review"]
+    },
+    ownership_boundary: defaultOwnershipBoundary(),
+    maintained_boundary_pointer: "maintained-boundary.context.json",
+    pointers: {
+      capabilities: inventory.capabilities.map((id) => `capabilities/${id}.context-digest.json`),
+      workflows: inventory.workflows.map((id) => `workflows/${id}.context-digest.json`),
+      entities: inventory.entities.map((id) => `entities/${id}.context-digest.json`),
+      projections: inventory.projections.map((id) => `projections/${id}.context-digest.json`),
+      journeys: inventory.journeys.map((id) => `journeys/${id}.context-digest.json`),
+      maintained_boundary: "maintained-boundary.context.json"
+    }
+  };
+}
+
+function capabilityDigest(graph, capability) {
+  const projections = relatedProjectionsForCapability(graph, capability.id);
+  const journeys = relatedJourneysForCapability(graph, capability.id).map((doc) => doc.id).sort();
+  const workflows = relatedWorkflowDocsForCapability(graph, capability.id).map((doc) => doc.id).sort();
+
+  return {
+    type: "context_digest",
+    version: 1,
+    focus: {
+      kind: "capability",
+      id: capability.id
+    },
+    summary: summarizeStatement(capability),
+    dependencies: {
+      shapes: [...new Set([...(capability.input || []).map((item) => item.id), ...(capability.output || []).map((item) => item.id)])].sort(),
+      entities: [...new Set([
+        ...(capability.reads || []).map((item) => item.id),
+        ...(capability.creates || []).map((item) => item.id),
+        ...(capability.updates || []).map((item) => item.id),
+        ...(capability.deletes || []).map((item) => item.id)
+      ])].sort()
+    },
+    journeys,
+    workflows,
+    projections,
+    verifications: verificationIdsForTarget(graph, [capability.id, ...projections]),
+    review_boundary: capability.reviewBoundary,
+    ownership_boundary: defaultOwnershipBoundary()
+  };
+}
+
+function workflowDigest(graph, workflow) {
+  return {
+    type: "context_digest",
+    version: 1,
+    focus: {
+      kind: "workflow",
+      id: workflow.id
+    },
+    summary: summarizeById(graph, workflow.id),
+    dependencies: {
+      capabilities: [...(workflow.relatedCapabilities || [])].sort(),
+      projections: [...(workflow.relatedProjections || [])].sort()
+    },
+    verifications: verificationIdsForTarget(graph, [workflow.id, ...(workflow.relatedCapabilities || [])]),
+    review_boundary: reviewBoundaryForWorkflowDoc(workflow),
+    ownership_boundary: defaultOwnershipBoundary()
+  };
+}
+
+function entityDigest(graph, entity) {
+  return {
+    type: "context_digest",
+    version: 1,
+    focus: {
+      kind: "entity",
+      id: entity.id
+    },
+    summary: summarizeStatement(entity),
+    verifications: verificationIdsForTarget(graph, [entity.id]),
+    review_boundary: reviewBoundaryForEntity(entity),
+    ownership_boundary: defaultOwnershipBoundary()
+  };
+}
+
+function projectionDigest(graph, projection) {
+  return {
+    type: "context_digest",
+    version: 1,
+    focus: {
+      kind: "projection",
+      id: projection.id
+    },
+    summary: summarizeProjection(projection),
+    verifications: verificationIdsForTarget(graph, [projection.id, ...projection.realizes.map((item) => item.id)]),
+    review_boundary: projection.reviewBoundary,
+    ownership_boundary: defaultOwnershipBoundary()
+  };
+}
+
+function journeyDigest(graph, journey) {
+  return {
+    type: "context_digest",
+    version: 1,
+    focus: {
+      kind: "journey",
+      id: journey.id
+    },
+    summary: summarizeById(graph, journey.id),
+    verifications: verificationIdsForTarget(graph, [journey.id, ...(journey.relatedCapabilities || [])]),
+    review_boundary: reviewBoundaryForJourneyDoc(journey),
+    ownership_boundary: defaultOwnershipBoundary()
+  };
+}
+
+export function generateContextDigest(graph) {
+  const files = {
+    "workspace.context-digest.json": workspaceDigest(graph),
+    "maintained-boundary.context.json": {
+      type: "maintained_boundary",
+      version: 1,
+      summary: {
+        focus: "Machine-readable maintained-app ownership and change boundary surface",
+        story_count: maintainedProofMetadata(graph).length
+      },
+      stories: maintainedProofMetadata(graph)
+    }
+  };
+
+  for (const capability of (graph.byKind.capability || []).slice().sort((a, b) => a.id.localeCompare(b.id))) {
+    files[`capabilities/${capability.id}.context-digest.json`] = capabilityDigest(graph, capability);
+  }
+
+  for (const workflow of (graph.docs || []).filter((doc) => doc.kind === "workflow").sort((a, b) => a.id.localeCompare(b.id))) {
+    files[`workflows/${workflow.id}.context-digest.json`] = workflowDigest(graph, workflow);
+  }
+
+  for (const entity of (graph.byKind.entity || []).slice().sort((a, b) => a.id.localeCompare(b.id))) {
+    files[`entities/${entity.id}.context-digest.json`] = entityDigest(graph, entity);
+  }
+
+  for (const projection of (graph.byKind.projection || []).slice().sort((a, b) => a.id.localeCompare(b.id))) {
+    files[`projections/${projection.id}.context-digest.json`] = projectionDigest(graph, projection);
+  }
+
+  for (const journey of (graph.docs || []).filter((doc) => doc.kind === "journey").sort((a, b) => a.id.localeCompare(b.id))) {
+    files[`journeys/${journey.id}.context-digest.json`] = journeyDigest(graph, journey);
+  }
+
+  return files;
+}

package/src/generator/context/domain-coverage.js

@@ -0,0 +1,94 @@
+import {
+  domainById,
+  relatedCapabilitiesForDomain,
+  relatedEntitiesForDomain,
+  relatedProjectionsForDomain,
+  relatedRulesForDomain,
+  relatedVerificationsForDomain,
+  stableSortedStrings,
+  summarizeDomain
+} from "./shared.js";
+
+function platformsFromProjections(projections) {
+  const platforms = new Set();
+  for (const projection of projections) {
+    if (projection?.platform) {
+      platforms.add(projection.platform);
+    }
+  }
+  return [...platforms].sort();
+}
+
+export function generateDomainCoverage(graph, options = {}) {
+  if (!options.domainId) {
+    throw new Error("generateDomainCoverage requires options.domainId");
+  }
+  const domain = domainById(graph, options.domainId);
+  if (!domain) {
+    throw new Error(`No domain found with id '${options.domainId}'`);
+  }
+  const capabilities = relatedCapabilitiesForDomain(graph, options.domainId);
+  const entities = relatedEntitiesForDomain(graph, options.domainId);
+  const rules = relatedRulesForDomain(graph, options.domainId);
+  const verifications = relatedVerificationsForDomain(graph, options.domainId);
+  const projectionIds = relatedProjectionsForDomain(graph, options.domainId);
+  const projectionsByCapability = {};
+  const projectionStatements = (graph?.byKind?.projection || []).filter((projection) =>
+    projectionIds.includes(projection.id)
+  );
+
+  for (const capabilityId of capabilities) {
+    projectionsByCapability[capabilityId] = stableSortedStrings(
+      projectionStatements
+        .filter((projection) => (projection.realizes || []).some((entry) => entry.id === capabilityId))
+        .map((projection) => projection.id)
+    );
+  }
+
+  const platforms = platformsFromProjections(projectionStatements);
+  const matrix = {};
+  for (const capabilityId of capabilities) {
+    matrix[capabilityId] = {};
+    for (const platform of platforms) {
+      const realized = projectionStatements.some(
+        (projection) =>
+          projection.platform === platform &&
+          (projection.realizes || []).some((entry) => entry.id === capabilityId)
+      );
+      matrix[capabilityId][platform] = realized;
+    }
+  }
+
+  return {
+    type: "domain_coverage",
+    version: 1,
+    focus: { kind: "domain", id: domain.id },
+    summary: summarizeDomain(domain),
+    platforms,
+    capabilities,
+    entities,
+    rules,
+    verifications,
+    projections: stableSortedStrings(projectionStatements.map((p) => p.id)),
+    projections_by_capability: projectionsByCapability,
+    coverage_matrix: matrix
+  };
+}
+
+export function generateDomainList(graph) {
+  const domains = (graph?.byKind?.domain || []).map((domain) => ({
+    id: domain.id,
+    name: domain.name,
+    description: domain.description,
+    status: domain.status,
+    parent_domain: domain.parentDomain ? domain.parentDomain.id : null,
+    members_count: Object.values(domain.members || {}).reduce((total, list) => total + list.length, 0)
+  }));
+  domains.sort((a, b) => a.id.localeCompare(b.id));
+
+  return {
+    type: "domain_list",
+    version: 1,
+    domains
+  };
+}

package/src/generator/context/domain-page.js

@@ -0,0 +1,137 @@
+import {
+  domainById,
+  relatedCapabilitiesForDomain,
+  relatedEntitiesForDomain,
+  relatedProjectionsForDomain,
+  relatedRulesForDomain,
+  relatedVerificationsForDomain,
+  summarizeDomain
+} from "./shared.js";
+import { generateDomainCoverage } from "./domain-coverage.js";
+
+function summarizeStatementForRow(graph, id, kind) {
+  const statement = (graph?.byKind?.[kind] || []).find((item) => item.id === id);
+  if (!statement) return { id, name: id, status: null };
+  return {
+    id,
+    name: statement.name || id,
+    status: statement.status || null
+  };
+}
+
+function renderTable(headers, rows) {
+  const lines = [
+    `| ${headers.join(" | ")} |`,
+    `| ${headers.map(() => "---").join(" | ")} |`,
+    ...rows.map((row) => `| ${row.join(" | ")} |`)
+  ];
+  return lines.join("\n");
+}
+
+function renderMembersSection(graph, title, ids, kind) {
+  if (!ids.length) {
+    return `### ${title}\n\nNone.`;
+  }
+  const rows = ids.map((id) => {
+    const summary = summarizeStatementForRow(graph, id, kind);
+    return [`\`${summary.id}\``, summary.name, summary.status || "—"];
+  });
+  return `### ${title}\n\n${renderTable(["Id", "Name", "Status"], rows)}`;
+}
+
+export function generateDomainPage(graph, options = {}) {
+  if (!options.domainId) {
+    throw new Error("generateDomainPage requires options.domainId");
+  }
+  const domain = domainById(graph, options.domainId);
+  if (!domain) {
+    throw new Error(`No domain found with id '${options.domainId}'`);
+  }
+  const summary = summarizeDomain(domain);
+  const coverage = generateDomainCoverage(graph, options);
+
+  const lines = [];
+  lines.push(`# ${summary.name || domain.id}`);
+  lines.push("");
+  lines.push(`> ${summary.description || ""}`);
+  lines.push("");
+  lines.push(`- Identifier: \`${domain.id}\``);
+  lines.push(`- Status: \`${summary.status || "unknown"}\``);
+  if (summary.parent_domain) {
+    lines.push(`- Parent domain: \`${summary.parent_domain}\``);
+  }
+  if (summary.aliases.length) {
+    lines.push(`- Aliases: ${summary.aliases.map((a) => `\`${a}\``).join(", ")}`);
+  }
+  lines.push("");
+
+  if (summary.in_scope.length) {
+    lines.push("## In scope");
+    lines.push("");
+    for (const item of summary.in_scope) {
+      lines.push(`- ${item}`);
+    }
+    lines.push("");
+  }
+
+  if (summary.out_of_scope.length) {
+    lines.push("## Out of scope");
+    lines.push("");
+    for (const item of summary.out_of_scope) {
+      lines.push(`- ${item}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## Members");
+  lines.push("");
+  lines.push(renderMembersSection(graph, "Capabilities", relatedCapabilitiesForDomain(graph, domain.id), "capability"));
+  lines.push("");
+  lines.push(renderMembersSection(graph, "Entities", relatedEntitiesForDomain(graph, domain.id), "entity"));
+  lines.push("");
+  lines.push(renderMembersSection(graph, "Rules", relatedRulesForDomain(graph, domain.id), "rule"));
+  lines.push("");
+  lines.push(renderMembersSection(graph, "Verifications", relatedVerificationsForDomain(graph, domain.id), "verification"));
+  lines.push("");
+
+  if (coverage.platforms.length) {
+    lines.push("## Per-platform coverage");
+    lines.push("");
+    const headers = ["Capability", ...coverage.platforms];
+    const rows = coverage.capabilities.map((capabilityId) => {
+      const cells = coverage.platforms.map((platform) =>
+        coverage.coverage_matrix[capabilityId]?.[platform] ? "✓" : "—"
+      );
+      return [`\`${capabilityId}\``, ...cells];
+    });
+    lines.push(renderTable(headers, rows));
+    lines.push("");
+    lines.push(`Projections involved: ${coverage.projections.map((id) => `\`${id}\``).join(", ") || "none"}`);
+  } else {
+    lines.push("## Per-platform coverage");
+    lines.push("");
+    lines.push("No projections currently realize capabilities in this domain.");
+  }
+
+  return {
+    type: "domain_page",
+    version: 1,
+    focus: { kind: "domain", id: domain.id },
+    output: {
+      path: `topogram/docs-generated/domains/${domain.id}.md`,
+      contents: lines.join("\n") + "\n"
+    },
+    summary
+  };
+}
+
+export function generateAllDomainPages(graph) {
+  const pages = (graph?.byKind?.domain || []).map((domain) =>
+    generateDomainPage(graph, { domainId: domain.id })
+  );
+  return {
+    type: "domain_pages",
+    version: 1,
+    pages
+  };
+}

package/src/generator/context/index.js

@@ -0,0 +1,42 @@
+import { generateContextBundle } from "./bundle.js";
+import { generateContextDigest } from "./digest.js";
+import { generateContextDiff } from "./diff.js";
+import { generateContextReport } from "./report.js";
+import { generateContextSlice } from "./slice.js";
+import { generateContextTaskMode } from "./task-mode.js";
+import { generateDomainCoverage, generateDomainList } from "./domain-coverage.js";
+import { generateAllDomainPages, generateDomainPage } from "./domain-page.js";
+
+export function generateContextTarget(target, graph, options = {}) {
+  if (target === "context-digest") {
+    return generateContextDigest(graph, options);
+  }
+  if (target === "context-diff") {
+    return generateContextDiff(graph, options);
+  }
+  if (target === "context-slice") {
+    return generateContextSlice(graph, options);
+  }
+  if (target === "context-bundle") {
+    return generateContextBundle(graph, options);
+  }
+  if (target === "context-report") {
+    return generateContextReport(graph, options);
+  }
+  if (target === "context-task-mode") {
+    return generateContextTaskMode(graph, options);
+  }
+  if (target === "domain-coverage") {
+    return generateDomainCoverage(graph, options);
+  }
+  if (target === "domain-list") {
+    return generateDomainList(graph);
+  }
+  if (target === "domain-page") {
+    return options.domainId
+      ? generateDomainPage(graph, options)
+      : generateAllDomainPages(graph);
+  }
+
+  throw new Error(`Unsupported context target '${target}'`);
+}

package/src/generator/context/report.js

@@ -0,0 +1,121 @@
+import fs from "node:fs";
+
+import { generateContextBundle } from "./bundle.js";
+import { generateContextDigest } from "./digest.js";
+import { generateContextDiff } from "./diff.js";
+import { generateContextSlice } from "./slice.js";
+import { jsonByteSize, jsonLineCount, percentOf } from "./shared.js";
+
+function walkTopogramFiles(root) {
+  const output = [];
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    const absolutePath = `${root}/${entry.name}`;
+    if (entry.isDirectory()) {
+      output.push(...walkTopogramFiles(absolutePath));
+      continue;
+    }
+    if (entry.isFile() && entry.name.endsWith(".tg")) {
+      output.push(absolutePath);
+    }
+  }
+  return output;
+}
+
+function rawWorkspaceMetrics(graph) {
+  const files = walkTopogramFiles(graph.root);
+  let bytes = 0;
+  let lines = 0;
+
+  for (const file of files) {
+    const contents = fs.readFileSync(file, "utf8");
+    bytes += Buffer.byteLength(contents);
+    lines += contents.split("\n").length;
+  }
+
+  return { bytes, lines };
+}
+
+function pickFirstId(items) {
+  return (items || [])[0]?.id || null;
+}
+
+export function generateContextReport(graph, options = {}) {
+  const rawWorkspace = rawWorkspaceMetrics(graph);
+  const resolvedGraph = {
+    bytes: jsonByteSize(graph),
+    lines: jsonLineCount(graph)
+  };
+  const digest = generateContextDigest(graph);
+  const digestMetrics = {
+    bytes: jsonByteSize(digest),
+    lines: jsonLineCount(digest)
+  };
+
+  const sliceRows = [];
+  const capabilityId = pickFirstId(graph.byKind.capability);
+  const workflowId = (graph.docs || []).find((doc) => doc.kind === "workflow")?.id || null;
+  const projectionId = pickFirstId(graph.byKind.projection);
+  const entityId = pickFirstId(graph.byKind.entity);
+
+  for (const [kind, selector] of [
+    ["capability", capabilityId ? { capabilityId } : null],
+    ["workflow", workflowId ? { workflowId } : null],
+    ["projection", projectionId ? { projectionId } : null],
+    ["entity", entityId ? { entityId } : null]
+  ]) {
+    if (!selector) {
+      continue;
+    }
+    const slice = generateContextSlice(graph, selector);
+    const bytes = jsonByteSize(slice);
+    sliceRows.push({
+      kind,
+      id: slice.focus.id,
+      bytes,
+      lines: jsonLineCount(slice),
+      slice_vs_resolved_percent: percentOf(bytes, resolvedGraph.bytes)
+    });
+  }
+
+  const bundleRows = [];
+  for (const task of ["api", "ui", "db", "maintained-app"]) {
+    const bundle = generateContextBundle(graph, { taskId: task });
+    const bytes = jsonByteSize(bundle);
+    bundleRows.push({
+      task,
+      bytes,
+      lines: jsonLineCount(bundle),
+      bundle_vs_resolved_percent: percentOf(bytes, resolvedGraph.bytes)
+    });
+  }
+
+  let diffMetrics = null;
+  if (options.fromTopogramPath) {
+    const diff = generateContextDiff(graph, options);
+    const bytes = jsonByteSize(diff);
+    diffMetrics = {
+      bytes,
+      lines: jsonLineCount(diff),
+      diff_vs_resolved_percent: percentOf(bytes, resolvedGraph.bytes),
+      diff_vs_digest_percent: percentOf(bytes, digestMetrics.bytes)
+    };
+  }
+
+  return {
+    type: "context_report",
+    version: 1,
+    roots: {
+      workspace: graph.root,
+      baseline: options.fromTopogramPath || null
+    },
+    raw_workspace: rawWorkspace,
+    resolved_graph: resolvedGraph,
+    workspace_digest: {
+      ...digestMetrics,
+      digest_vs_resolved_percent: percentOf(digestMetrics.bytes, resolvedGraph.bytes)
+    },
+    slices: sliceRows,
+    bundles: bundleRows,
+    diff: diffMetrics
+  };
+}