@topogram/cli 0.3.62 → 0.3.64

package/src/topogram-config.js

@@ -0,0 +1,306 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const TOPOGRAM_CONFIG_FILE = "topogram.config.json";
+
+export const DEFAULT_FIRST_PARTY_GENERATOR_REPOS = [
+  "topogram-generator-express-api",
+  "topogram-generator-hono-api",
+  "topogram-generator-postgres-db",
+  "topogram-generator-react-web",
+  "topogram-generator-sqlite-db",
+  "topogram-generator-sveltekit-web",
+  "topogram-generator-swiftui-native",
+  "topogram-generator-vanilla-web"
+];
+
+export const DEFAULT_RELEASE_CONSUMER_REPOS = [
+  ...DEFAULT_FIRST_PARTY_GENERATOR_REPOS,
+  "topogram-starters",
+  "topogram-template-todo",
+  "topogram-demo-todo",
+  "topogram-hello",
+  "topograms"
+];
+
+export const DEFAULT_RELEASE_CONSUMER_WORKFLOWS = {
+  "topogram-generator-express-api": "Generator Verification",
+  "topogram-generator-hono-api": "Generator Verification",
+  "topogram-generator-postgres-db": "Generator Verification",
+  "topogram-generator-react-web": "Generator Verification",
+  "topogram-generator-sqlite-db": "Generator Verification",
+  "topogram-generator-sveltekit-web": "Generator Verification",
+  "topogram-generator-swiftui-native": "Generator Verification",
+  "topogram-generator-vanilla-web": "Generator Verification",
+  "topogram-starters": "Starter Verification",
+  "topogram-template-todo": "Template Verification",
+  "topogram-demo-todo": "Demo Verification",
+  "topogram-hello": "Topogram Package Verification",
+  "topograms": "Catalog Verification"
+};
+
+export const DEFAULT_RELEASE_CONSUMER_WORKFLOW_JOBS = {
+  topograms: [
+    "Validate catalog",
+    "Smoke native starter",
+    "Smoke starter alias (hello-web)",
+    "Smoke starter alias (hello-api)",
+    "Smoke starter alias (hello-db)",
+    "Smoke starter alias (web-api)",
+    "Smoke starter alias (web-api-db)"
+  ]
+};
+
+export const DEFAULT_TOPOGRAM_CONFIG = {
+  github: {
+    owner: "attebury",
+    repo: "topogram"
+  },
+  catalog: {
+    owner: "attebury",
+    repo: "topograms",
+    ref: "main",
+    path: "topograms.catalog.json",
+    source: null
+  },
+  release: {
+    consumers: DEFAULT_RELEASE_CONSUMER_REPOS,
+    workflows: DEFAULT_RELEASE_CONSUMER_WORKFLOWS,
+    workflowJobs: DEFAULT_RELEASE_CONSUMER_WORKFLOW_JOBS
+  }
+};
+
+export const DEFAULT_CATALOG_SOURCE = `https://raw.githubusercontent.com/${DEFAULT_TOPOGRAM_CONFIG.catalog.owner}/${DEFAULT_TOPOGRAM_CONFIG.catalog.repo}/${DEFAULT_TOPOGRAM_CONFIG.catalog.ref}/${DEFAULT_TOPOGRAM_CONFIG.catalog.path}`;
+
+/**
+ * @typedef {Object} TopogramRuntimeConfig
+ * @property {{ owner: string, repo: string }} github
+ * @property {{ owner: string, repo: string, ref: string, path: string, source: string|null }} catalog
+ * @property {{ consumers: string[], workflows: Record<string, string>, workflowJobs: Record<string, string[]> }} release
+ */
+
+/**
+ * @param {string} cwd
+ * @returns {string|null}
+ */
+export function findTopogramConfigFile(cwd = process.cwd()) {
+  if (process.env.TOPOGRAM_CONFIG_PATH) {
+    return path.resolve(process.env.TOPOGRAM_CONFIG_PATH);
+  }
+  let current = path.resolve(cwd);
+  while (true) {
+    const candidate = path.join(current, TOPOGRAM_CONFIG_FILE);
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Record<string, any>}
+ */
+export function readTopogramConfigFile(cwd = process.cwd()) {
+  const filePath = findTopogramConfigFile(cwd);
+  if (!filePath) {
+    return {};
+  }
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+/**
+ * @param {string|null|undefined} value
+ * @returns {string[]|null}
+ */
+function parseListEnv(value) {
+  if (!value) {
+    return null;
+  }
+  return String(value)
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+/**
+ * @param {string|null|undefined} value
+ * @returns {Record<string, any>|null}
+ */
+function parseJsonEnv(value) {
+  if (!value) {
+    return null;
+  }
+  return JSON.parse(value);
+}
+
+/**
+ * @param {Record<string, any>} fileConfig
+ * @returns {Record<string, any>}
+ */
+function envConfig(fileConfig = {}) {
+  const consumers = parseListEnv(process.env.TOPOGRAM_RELEASE_CONSUMERS);
+  const workflows = parseJsonEnv(process.env.TOPOGRAM_RELEASE_WORKFLOWS || process.env.TOPOGRAM_RELEASE_CONSUMER_WORKFLOWS_JSON);
+  const workflowJobs = parseJsonEnv(process.env.TOPOGRAM_RELEASE_WORKFLOW_JOBS || process.env.TOPOGRAM_RELEASE_CONSUMER_WORKFLOW_JOBS_JSON);
+  return {
+    github: {
+      owner: process.env.TOPOGRAM_GITHUB_OWNER || fileConfig.github?.owner,
+      repo: process.env.TOPOGRAM_GITHUB_REPO || process.env.TOPOGRAM_REPO_NAME || fileConfig.github?.repo
+    },
+    catalog: {
+      owner: process.env.TOPOGRAM_CATALOG_OWNER || fileConfig.catalog?.owner,
+      repo: process.env.TOPOGRAM_CATALOG_REPO || fileConfig.catalog?.repo,
+      ref: process.env.TOPOGRAM_CATALOG_REF || fileConfig.catalog?.ref,
+      path: process.env.TOPOGRAM_CATALOG_PATH || fileConfig.catalog?.path,
+      source: fileConfig.catalog?.source
+    },
+    release: {
+      consumers: consumers || fileConfig.release?.consumers,
+      workflows: workflows || fileConfig.release?.workflows,
+      workflowJobs: workflowJobs || fileConfig.release?.workflowJobs
+    }
+  };
+}
+
+/**
+ * @param {unknown} value
+ * @param {string[]} fallback
+ * @returns {string[]}
+ */
+function normalizeStringList(value, fallback) {
+  if (!Array.isArray(value)) {
+    return [...fallback];
+  }
+  const items = value.map((item) => String(item || "").trim()).filter(Boolean);
+  return [...new Set(items)];
+}
+
+/**
+ * @param {unknown} value
+ * @param {Record<string, string>} fallback
+ * @returns {Record<string, string>}
+ */
+function normalizeStringMap(value, fallback) {
+  const output = { ...fallback };
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return output;
+  }
+  for (const [key, item] of Object.entries(value)) {
+    const name = String(key || "").trim();
+    const text = String(item || "").trim();
+    if (name && text) {
+      output[name] = text;
+    }
+  }
+  return output;
+}
+
+/**
+ * @param {unknown} value
+ * @param {Record<string, string[]>} fallback
+ * @returns {Record<string, string[]>}
+ */
+function normalizeStringListMap(value, fallback) {
+  const output = Object.fromEntries(Object.entries(fallback).map(([key, items]) => [key, [...items]]));
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return output;
+  }
+  for (const [key, item] of Object.entries(value)) {
+    const name = String(key || "").trim();
+    if (!name) {
+      continue;
+    }
+    output[name] = normalizeStringList(item, []);
+  }
+  return output;
+}
+
+/**
+ * @param {string} cwd
+ * @returns {TopogramRuntimeConfig}
+ */
+export function topogramRuntimeConfig(cwd = process.cwd()) {
+  const fileConfig = readTopogramConfigFile(cwd);
+  const overrides = envConfig(fileConfig);
+  return {
+    github: {
+      owner: overrides.github.owner || DEFAULT_TOPOGRAM_CONFIG.github.owner,
+      repo: overrides.github.repo || DEFAULT_TOPOGRAM_CONFIG.github.repo
+    },
+    catalog: {
+      owner: overrides.catalog.owner || DEFAULT_TOPOGRAM_CONFIG.catalog.owner,
+      repo: overrides.catalog.repo || DEFAULT_TOPOGRAM_CONFIG.catalog.repo,
+      ref: overrides.catalog.ref || DEFAULT_TOPOGRAM_CONFIG.catalog.ref,
+      path: overrides.catalog.path || DEFAULT_TOPOGRAM_CONFIG.catalog.path,
+      source: overrides.catalog.source || DEFAULT_TOPOGRAM_CONFIG.catalog.source
+    },
+    release: {
+      consumers: normalizeStringList(overrides.release.consumers, DEFAULT_TOPOGRAM_CONFIG.release.consumers),
+      workflows: normalizeStringMap(overrides.release.workflows, DEFAULT_TOPOGRAM_CONFIG.release.workflows),
+      workflowJobs: normalizeStringListMap(overrides.release.workflowJobs, DEFAULT_TOPOGRAM_CONFIG.release.workflowJobs)
+    }
+  };
+}
+
+/**
+ * @param {TopogramRuntimeConfig} [config]
+ * @returns {string}
+ */
+export function defaultCatalogSource(config = topogramRuntimeConfig()) {
+  if (config.catalog.source) {
+    return config.catalog.source;
+  }
+  return `https://raw.githubusercontent.com/${config.catalog.owner}/${config.catalog.repo}/${config.catalog.ref}/${config.catalog.path}`;
+}
+
+/**
+ * @param {string|null|undefined} repo
+ * @param {string} [cwd]
+ * @param {string|null|undefined} owner
+ * @returns {string}
+ */
+export function githubRepoSlug(repo, cwd = process.cwd(), owner = null) {
+  const config = topogramRuntimeConfig(cwd);
+  return `${owner || config.github.owner}/${repo || config.github.repo}`;
+}
+
+/**
+ * @param {string} [cwd]
+ * @returns {string}
+ */
+export function catalogRepoSlug(cwd = process.cwd()) {
+  const config = topogramRuntimeConfig(cwd);
+  return githubRepoSlug(config.catalog.repo, cwd, config.catalog.owner);
+}
+
+/**
+ * @param {string} [cwd]
+ * @returns {string[]}
+ */
+export function releaseConsumerRepos(cwd = process.cwd()) {
+  return [...topogramRuntimeConfig(cwd).release.consumers];
+}
+
+/**
+ * @param {string} name
+ * @param {string} [cwd]
+ * @returns {string|null}
+ */
+export function releaseConsumerWorkflowName(name, cwd = process.cwd()) {
+  return topogramRuntimeConfig(cwd).release.workflows[name] || null;
+}
+
+/**
+ * @param {string} name
+ * @param {string} [cwd]
+ * @returns {string[]}
+ */
+export function releaseConsumerWorkflowJobs(name, cwd = process.cwd()) {
+  return [...(topogramRuntimeConfig(cwd).release.workflowJobs[name] || [])];
+}

package/src/validator.d.ts

@@ -0,0 +1,2 @@
+export function formatValidationErrors(validation: any, configPath?: string): string;
+export function validateWorkspace(ast: any): any;

package/src/workflows/adoption/index.js

@@ -0,0 +1,26 @@
+// @ts-check
+import {
+  buildAdoptionStatusFiles as buildAdoptionStatusFilesReport,
+  buildAdoptionStatusSummary as buildAdoptionStatusSummaryReport
+} from "../../adoption/reporting.js";
+import { selectNextBundle } from "../../adoption/review-groups.js";
+import {
+  formatDocDriftSummaryInline,
+  formatDocLinkSuggestionInline,
+  formatDocMetadataPatchInline,
+  reconcileWorkflow
+} from "../reconcile/index.js";
+import { normalizeWorkspacePaths } from "../shared.js";
+
+/** @param {string} inputPath @returns {any} */
+export function adoptionStatusWorkflow(inputPath) {
+  const reconcile = reconcileWorkflow(inputPath);
+  const report = reconcile.summary;
+  const summary = buildAdoptionStatusSummaryReport(report, selectNextBundle);
+  const files = buildAdoptionStatusFilesReport(summary, formatDocLinkSuggestionInline, formatDocDriftSummaryInline, formatDocMetadataPatchInline);
+  return {
+    summary,
+    files,
+    defaultOutDir: normalizeWorkspacePaths(inputPath).topogramRoot
+  };
+}

package/src/workflows/docs-generate.js

@@ -0,0 +1,262 @@
+// @ts-check
+import fs from "node:fs";
+import path from "node:path";
+
+import { stableStringify } from "../format.js";
+import { parsePath } from "../parser.js";
+import { resolveWorkspace } from "../resolver.js";
+import { buildJourneyDrafts as buildJourneyDraftsReconcile } from "../reconcile/journeys.js";
+import { relativeTo } from "../path-helpers.js";
+import { ensureTrailingNewline, titleCase } from "../text-helpers.js";
+import { listFilesRecursive, markdownTitle, normalizeWorkspacePaths, renderMarkdownDoc } from "./shared.js";
+
+/** @param {string} kind @returns {any} */
+export function docDirForKind(kind) {
+  if (kind === "glossary") {
+    return "glossary";
+  }
+  if (kind === "workflow") {
+    return "workflows";
+  }
+  if (kind === "journey") {
+    return "journeys";
+  }
+  return "reports";
+}
+
+/** @param {ResolvedGraph} graph @returns {any} */
+export function generateDocsBundleFromGraph(graph) {
+  /** @type {WorkflowFiles} */
+  /** @type {WorkflowFiles} */
+  const files = {};
+  for (const entity of graph.byKind.entity || []) {
+    const id = entity.id.replace(/^entity_/, "");
+    /** @type {WorkflowRecord} */
+    const metadata = {
+      id,
+      kind: "glossary",
+      title: entity.name || titleCase(id),
+      status: "canonical",
+      summary: entity.description || `Generated glossary entry for ${entity.id}.`,
+      related_entities: [entity.id],
+      source_of_truth: "canonical",
+      confidence: "high",
+      review_required: false,
+      tags: ["generated", "glossary"]
+    };
+    const body = [
+      entity.description || `Canonical entity \`${entity.id}\`.`,
+      "",
+      "Fields:",
+      ...(entity.fields || []).map((/** @type {any} */ field) => `- \`${field.name}\` (${field.fieldType}) ${field.required ? "required" : "optional"}`)
+    ].join("\n");
+    files[`glossary/${id}.md`] = renderMarkdownDoc(metadata, body);
+  }
+
+  for (const capability of graph.byKind.capability || []) {
+    const writes = [...capability.creates, ...capability.updates, ...capability.deletes];
+    if (writes.length === 0) {
+      continue;
+    }
+    const id = capability.id.replace(/^cap_/, "");
+    const relatedEntities = [...new Set(writes.map((/** @type {any} */ entry) => entry.id).filter(Boolean))];
+    const metadata = {
+      id,
+      kind: "workflow",
+      title: capability.name || titleCase(id),
+      status: "canonical",
+      summary: capability.description || `Generated workflow entry for ${capability.id}.`,
+      related_capabilities: [capability.id],
+      related_entities: relatedEntities,
+      source_of_truth: "canonical",
+      confidence: "high",
+      review_required: false,
+      tags: ["generated", "workflow"]
+    };
+    const body = [
+      capability.description || `Canonical workflow surface for \`${capability.id}\`.`,
+      "",
+      `Actors: ${(capability.actors || []).map((/** @type {any} */ actor) => `\`${actor.id}\``).join(", ") || "_none_"}`,
+      `Creates: ${(capability.creates || []).map((/** @type {any} */ ref) => `\`${ref.id}\``).join(", ") || "_none_"}`,
+      `Updates: ${(capability.updates || []).map((/** @type {any} */ ref) => `\`${ref.id}\``).join(", ") || "_none_"}`,
+      `Deletes: ${(capability.deletes || []).map((/** @type {any} */ ref) => `\`${ref.id}\``).join(", ") || "_none_"}`,
+      `Input: ${capability.input?.id ? `\`${capability.input.id}\`` : "_none_"}`,
+      `Output: ${capability.output?.id ? `\`${capability.output.id}\`` : "_none_"}`
+    ].join("\n\n");
+    files[`workflows/${id}.md`] = renderMarkdownDoc(metadata, body);
+  }
+
+  const reportMetadata = {
+    id: "model_overview",
+    kind: "report",
+    title: "Model Overview",
+    status: "canonical",
+    summary: "Generated overview of the current Topogram model surface.",
+    source_of_truth: "canonical",
+    confidence: "high",
+    review_required: false,
+    tags: ["generated", "report"]
+  };
+  files["reports/model-overview.md"] = renderMarkdownDoc(
+    reportMetadata,
+    [
+      `Entities: ${(graph.byKind.entity || []).length}`,
+      `Capabilities: ${(graph.byKind.capability || []).length}`,
+      `Shapes: ${(graph.byKind.shape || []).length}`,
+      `Projections: ${(graph.byKind.projection || []).length}`,
+      `Companion docs: ${(graph.docs || []).length}`
+    ].join("\n\n")
+  );
+
+  const index = Object.entries(files).map(([filePath, contents]) => ({
+    path: filePath,
+    title: markdownTitle(filePath, contents)
+  }));
+  files["docs-index.json"] = `${stableStringify(index)}\n`;
+  return files;
+}
+
+/** @param {string} inputPath @returns {any} */
+export function loadResolvedGraph(inputPath) {
+  const ast = parsePath(inputPath);
+  const resolved = resolveWorkspace(ast);
+  if (!resolved.ok) {
+    const error = /** @type {Error & { validation?: any }} */ (new Error("Workspace validation failed"));
+    error.validation = resolved.validation;
+    throw error;
+  }
+  return resolved.graph;
+}
+
+/** @param {string} inputPath @returns {any} */
+export function tryLoadResolvedGraph(inputPath) {
+  try {
+    return loadResolvedGraph(inputPath);
+  } catch {
+    return null;
+  }
+}
+
+/** @param {string} inputPath @returns {any} */
+export function refreshDocsWorkflow(inputPath) {
+  const paths = normalizeWorkspacePaths(inputPath);
+  const graph = loadResolvedGraph(paths.topogramRoot);
+  const generated = generateDocsBundleFromGraph(graph);
+  const canonicalRoot = path.join(paths.topogramRoot, "docs");
+  const generatedRoot = path.join(paths.topogramRoot, "candidates", "docs", "refreshed");
+  /** @type {WorkflowRecord} */
+  const report = {
+    type: "refresh_docs",
+    workspace: paths.topogramRoot,
+    missing: [],
+    stale: [],
+    orphaned: []
+  };
+
+  for (const [relativePath, contents] of Object.entries(generated)) {
+    if (relativePath === "docs-index.json") {
+      continue;
+    }
+    const canonicalPath = path.join(canonicalRoot, relativePath);
+    if (!fs.existsSync(canonicalPath)) {
+      report.missing.push(relativePath);
+      continue;
+    }
+    if ((fs.readFileSync(canonicalPath, "utf8")) !== contents) {
+      report.stale.push(relativePath);
+    }
+  }
+
+  for (const filePath of listFilesRecursive(canonicalRoot, (/** @type {any} */ child) => child.endsWith(".md"))) {
+    const relativePath = relativeTo(canonicalRoot, filePath);
+    if (!generated[relativePath]) {
+      report.orphaned.push(relativePath);
+    }
+  }
+
+  /** @type {WorkflowFiles} */
+
+  const files = {
+    "candidates/docs/refreshed/report.json": `${stableStringify(report)}\n`,
+    "candidates/docs/refreshed/report.md": ensureTrailingNewline(
+      `# Docs Refresh Report\n\n## Missing\n\n${report.missing.length ? report.missing.map((/** @type {any} */ item) => `- \`${item}\``).join("\n") : "- None"}\n\n## Stale\n\n${report.stale.length ? report.stale.map((/** @type {any} */ item) => `- \`${item}\``).join("\n") : "- None"}\n\n## Orphaned\n\n${report.orphaned.length ? report.orphaned.map((/** @type {any} */ item) => `- \`${item}\``).join("\n") : "- None"}\n`
+    )
+  };
+
+  for (const [relativePath, contents] of Object.entries(generated)) {
+    files[path.join("candidates/docs/refreshed/generated", relativePath).replaceAll(path.sep, "/")] = contents;
+  }
+
+  return {
+    summary: report,
+    files,
+    defaultOutDir: paths.topogramRoot
+  };
+}
+
+/** @param {string} inputPath @returns {any} */
+export function generateDocsWorkflow(inputPath) {
+  const paths = normalizeWorkspacePaths(inputPath);
+  const graph = loadResolvedGraph(paths.topogramRoot);
+  const files = generateDocsBundleFromGraph(graph);
+  return {
+    summary: {
+      type: "generate_docs",
+      workspace: paths.topogramRoot,
+      bootstrapped_topogram_root: paths.bootstrappedTopogramRoot,
+      file_count: Object.keys(files).length
+    },
+    files,
+    defaultOutDir: path.join(paths.topogramRoot, "docs-generated")
+  };
+}
+
+/** @param {string} inputPath @returns {any} */
+export function generateJourneyDraftsWorkflow(inputPath) {
+  const paths = normalizeWorkspacePaths(inputPath);
+  const graph = loadResolvedGraph(paths.topogramRoot);
+  const canonicalJourneys = (graph.docs || []).filter((/** @type {any} */ doc) => doc.kind === "journey");
+  const { drafts, skippedEntities } = buildJourneyDraftsReconcile(graph);
+  /** @type {WorkflowFiles} */
+  /** @type {WorkflowFiles} */
+  const files = {};
+
+  for (const draft of drafts) {
+    files[draft.path] = renderMarkdownDoc(draft.metadata, draft.body);
+  }
+
+  /** @type {WorkflowRecord} */
+  const summary = {
+    type: "generate_journeys",
+    workspace: paths.topogramRoot,
+    bootstrapped_topogram_root: paths.bootstrappedTopogramRoot,
+    canonical_journey_count: canonicalJourneys.length,
+    generated_draft_count: drafts.length,
+    draft_journeys: drafts.map((/** @type {any} */ draft) => ({
+      id: draft.id,
+      title: draft.title,
+      entity_id: draft.entity_id,
+      path: draft.path,
+      type: draft.type,
+      related_capabilities: draft.related_capabilities
+    })),
+    skipped_entities: skippedEntities
+  };
+
+  files["candidates/docs/journeys/import-report.json"] = `${stableStringify(summary)}\n`;
+  files["candidates/docs/journeys/import-report.md"] = ensureTrailingNewline(
+    `# Journey Draft Report\n\n` +
+      `Canonical journeys: ${canonicalJourneys.length}\n\n` +
+      `Generated drafts: ${drafts.length}\n\n` +
+      `## Draft Journeys\n\n` +
+      `${drafts.length === 0 ? "- None" : drafts.map((/** @type {any} */ draft) => `- \`${draft.id}\` -> \`${draft.path}\``).join("\n")}\n\n` +
+      `## Skipped Entities\n\n` +
+      `${skippedEntities.length === 0 ? "- None" : skippedEntities.map((/** @type {any} */ entry) => `- \`${entry.entity_id}\` (${entry.reason})`).join("\n")}\n`
+  );
+
+  return {
+    summary,
+    files,
+    defaultOutDir: paths.topogramRoot
+  };
+}