@topogram/cli 0.3.64 → 0.3.66

package/src/project-config.js

@@ -1,564 +1,22 @@
 // @ts-check
 
-import fs from "node:fs";
-import path from "node:path";
-
-import {
-  isGeneratorCompatible,
-  resolveGeneratorManifestForBinding,
-  validateGeneratorManifest
-} from "./generator/registry.js";
-import { validateProjectGeneratorPolicy } from "./generator-policy.js";
-
-/**
- * @typedef {Object} GeneratorBinding
- * @property {string} id
- * @property {string} version
- * @property {string} [package]
- */
-
-/**
- * @typedef {Object} RuntimeTopologyRuntime
- * @property {string} id
- * @property {"api_service"|"web_surface"|"ios_surface"|"android_surface"|"database"} kind
- * @property {string} projection
- * @property {GeneratorBinding} generator
- * @property {number|null} [port]
- * @property {string} [uses_api]
- * @property {string} [uses_database]
- * @property {Record<string, string>} [env]
- */
-
-/**
- * @typedef {Object} ProjectConfig
- * @property {string} version
- * @property {Record<string, { path: string, ownership: "generated"|"maintained" }>} outputs
- * @property {{ runtimes: RuntimeTopologyRuntime[] }} topology
- * @property {{ id?: string, module?: string, export?: string, implementation_module?: string, implementation_export?: string }} [implementation]
- * @property {Record<string, any>} [template]
- */
-
-/**
- * @typedef {Object} ProjectConfigInfo
- * @property {ProjectConfig} config
- * @property {string|null} configPath
- * @property {string} configDir
- * @property {boolean} [compatibility]
- */
-
-/**
- * @typedef {Object} ValidationError
- * @property {string} message
- * @property {any} loc
- */
-
-const PROJECT_CONFIG_FILE = "topogram.project.json";
-const LEGACY_IMPLEMENTATION_FILE = "topogram.implementation.json";
-const GENERATED_OUTPUT_SENTINEL = ".topogram-generated.json";
-const IDENTIFIER_PATTERN = /^[a-z][a-z0-9_]*$/;
-
-/**
- * @param {string|null|undefined} root
- * @returns {string|null}
- */
-function normalizeSearchRoot(root) {
-  if (!root) {
-    return null;
-  }
-  const absolute = path.resolve(root);
-  try {
-    return fs.realpathSync(absolute);
-  } catch {
-    return absolute;
-  }
-}
-
-/**
- * @param {string} root
- * @returns {string}
- */
-function normalizeRoot(root) {
-  return String(root || "").replace(/\\/g, "/");
-}
-
-/**
- * @param {string} filePath
- * @returns {string}
- */
-function resolveComparablePath(filePath) {
-  const absolute = path.resolve(filePath);
-  try {
-    return fs.existsSync(absolute)
-      ? fs.realpathSync(absolute)
-      : path.join(fs.realpathSync(path.dirname(absolute)), path.basename(absolute));
-  } catch {
-    return absolute;
-  }
-}
-
-/**
- * @param {string} filePath
- * @returns {any}
- */
-function readJson(filePath) {
-  return JSON.parse(fs.readFileSync(filePath, "utf8"));
-}
-
-/**
- * @param {string} oldName
- * @param {string} newName
- * @param {string} example
- * @returns {string}
- */
-function renameDiagnostic(oldName, newName, example) {
-  return `${oldName} was renamed to ${newName}. Example fix: ${example}`;
-}
-
 /**
- * @param {string} root
- * @param {string} fileName
- * @returns {{ config: any, configPath: string, configDir: string }|null}
- */
-function findConfigFile(root, fileName) {
-  let current = normalizeSearchRoot(root);
-  while (current && current !== path.dirname(current)) {
-    const candidate = path.join(current, fileName);
-    if (fs.existsSync(candidate)) {
-      return {
-        config: readJson(candidate),
-        configPath: candidate,
-        configDir: path.dirname(candidate)
-      };
-    }
-    current = path.dirname(current);
-  }
-  return null;
-}
-
-/**
- * @param {string} root
- * @returns {{ config: any, configPath: string, configDir: string }|null}
- */
-export function findProjectConfig(root) {
-  return findConfigFile(root, PROJECT_CONFIG_FILE);
-}
-
-/**
- * @param {string} root
- * @returns {{ config: any, configPath: string, configDir: string }|null}
- */
-export function findLegacyImplementationConfig(root) {
-  return findConfigFile(root, LEGACY_IMPLEMENTATION_FILE);
-}
-
-/**
- * @param {Record<string, any>} graph
- * @param {Record<string, any>|null} [implementation]
- * @returns {ProjectConfig}
- */
-export function defaultProjectConfigForGraph(graph, implementation = null) {
-  const runtimeReference = implementation?.runtime?.reference || {};
-  /** @type {Array<Record<string, any>>} */
-  const projections = graph.byKind.projection || [];
-  const apiProjection = projections.find((projection) => (projection.http || []).length > 0 || projection.type === "api_contract");
-  const webProjection =
-    projections.find((projection) => projection.id === "proj_web") ||
-    projections.find((projection) => projection.type === "web_surface");
-  const dbProjection =
-    projections.find((projection) => projection.id === runtimeReference.localDbProjectionId) ||
-    projections.find((projection) => projection.type === "db_contract");
-  const ports = runtimeReference.ports || {};
-  const dbProfile = (dbProjection?.generatorDefaults || []).find((/** @type {Record<string, any>} */ entry) => entry.key === "profile")?.value;
-  const dbGenerator = dbProfile === "sqlite_sql" ? "topogram/sqlite" : "topogram/postgres";
-  const dbRuntimeId = dbProfile === "sqlite_sql" ? "app_sqlite" : "app_postgres";
-  /** @type {RuntimeTopologyRuntime[]} */
-  const runtimes = [
-    ...(apiProjection
-      ? [{
-          id: "app_api",
-          kind: /** @type {"api_service"} */ ("api_service"),
-          projection: apiProjection.id,
-          generator: { id: "topogram/hono", version: "1" },
-          port: ports.server || 3000,
-          ...(dbProjection ? { uses_database: dbRuntimeId } : {})
-        }]
-      : []),
-    ...(webProjection
-      ? [{
-          id: "app_sveltekit",
-          kind: /** @type {"web_surface"} */ ("web_surface"),
-          projection: webProjection.id,
-          generator: { id: "topogram/sveltekit", version: "1" },
-          port: ports.web || 5173,
-          ...(apiProjection ? { uses_api: "app_api" } : {})
-        }]
-      : []),
-    ...(dbProjection
-      ? [{
-          id: dbRuntimeId,
-          kind: /** @type {"database"} */ ("database"),
-          projection: dbProjection.id,
-          generator: { id: dbGenerator, version: "1" },
-          port: dbProfile === "sqlite_sql" ? null : 5432
-        }]
-      : [])
-  ];
-
-  return {
-    version: "0.1",
-    implementation: implementation?.exampleId
-      ? {
-          id: implementation.exampleId
-        }
-      : undefined,
-    outputs: {
-      app: {
-        path: "./app",
-        ownership: "generated"
-      }
-    },
-    topology: {
-      runtimes
-    }
-  };
-}
-
-/**
- * @param {string} root
- * @returns {ProjectConfigInfo|null}
- */
-export function loadProjectConfig(root) {
-  const found = findProjectConfig(root);
-  if (!found) {
-    return null;
-  }
-  return {
-    ...found,
-    config: found.config,
-    compatibility: false
-  };
-}
-
-/**
- * @param {string} root
- * @param {Record<string, any>|null} [graph]
- * @param {Record<string, any>|null} [implementation]
- * @returns {ProjectConfigInfo|null}
- */
-export function projectConfigOrDefault(root, graph = null, implementation = null) {
-  const found = loadProjectConfig(root);
-  if (found) {
-    return found;
-  }
-  if (!graph) {
-    return null;
-  }
-  return {
-    config: defaultProjectConfigForGraph(graph, implementation),
-    configPath: null,
-    configDir: path.dirname(path.resolve(root)),
-    compatibility: true
-  };
-}
-
-/**
- * @param {ValidationError[]} errors
- * @param {string} message
- * @param {any} [loc]
- * @returns {void}
- */
-function pushError(errors, message, loc = null) {
-  errors.push({ message, loc });
-}
-
-/**
- * @param {Record<string, any>} graph
- * @returns {Map<string, Record<string, any>>}
- */
-function projectionById(graph) {
-  /** @type {Array<Record<string, any>>} */
-  const projections = graph?.byKind?.projection || [];
-  return new Map(projections.map((projection) => [projection.id, projection]));
-}
-
-/**
- * @param {ValidationError[]} errors
- * @param {any} config
- * @returns {void}
- */
-function validateOutputConfig(errors, config) {
-  if (!config.outputs || typeof config.outputs !== "object" || Array.isArray(config.outputs)) {
-    pushError(errors, "topogram.project.json outputs must be an object");
-    return;
-  }
-  for (const [name, output] of Object.entries(config.outputs)) {
-    if (!output || typeof output !== "object" || Array.isArray(output)) {
-      pushError(errors, `Output '${name}' must be an object`);
-      continue;
-    }
-    if (!["generated", "maintained"].includes(output.ownership)) {
-      pushError(errors, `Output '${name}' ownership must be generated or maintained`);
-    }
-    if (typeof output.path !== "string" || output.path.length === 0) {
-      pushError(errors, `Output '${name}' path must be a non-empty string`);
-    }
-  }
-}
-
-/**
- * @param {any} runtime
- * @returns {string}
- */
-function runtimeLabel(runtime) {
-  return runtime?.id ? `Runtime '${runtime.id}'` : "Topology runtime";
-}
-
-/**
- * @param {ValidationError[]} errors
- * @param {any} runtime
- * @param {Set<string>} seenIds
- * @returns {boolean}
- */
-function validateRuntimeShape(errors, runtime, seenIds) {
-  if (!runtime || typeof runtime !== "object" || Array.isArray(runtime)) {
-    pushError(errors, "Topology runtime must be an object");
-    return false;
-  }
-  if (typeof runtime.id !== "string" || !IDENTIFIER_PATTERN.test(runtime.id)) {
-    pushError(errors, `${runtimeLabel(runtime)} id must match ${IDENTIFIER_PATTERN}`);
-  } else if (seenIds.has(runtime.id)) {
-    pushError(errors, `Duplicate topology runtime id '${runtime.id}'`);
-  } else {
-    seenIds.add(runtime.id);
-  }
-  if (runtime.type != null) {
-    pushError(errors, `${runtimeLabel(runtime)} ${renameDiagnostic("'type'", "'kind'", `"kind": "api_service"`)}`);
-  }
-  if (runtime.database != null) {
-    pushError(errors, `${runtimeLabel(runtime)} ${renameDiagnostic("'database'", "'uses_database'", `"uses_database": "app_db"`)}`);
-  }
-  if (runtime.api != null) {
-    pushError(errors, `${runtimeLabel(runtime)} ${renameDiagnostic("'api'", "'uses_api'", `"uses_api": "app_api"`)}`);
-  }
-  if (!["api_service", "web_surface", "ios_surface", "android_surface", "database"].includes(runtime.kind)) {
-    pushError(errors, `${runtimeLabel(runtime)} kind must be api_service, web_surface, ios_surface, android_surface, or database`);
-  }
-  if (typeof runtime.projection !== "string" || runtime.projection.length === 0) {
-    pushError(errors, `${runtimeLabel(runtime)} projection must be a non-empty string`);
-  }
-  if (!runtime.generator || typeof runtime.generator !== "object") {
-    pushError(errors, `${runtimeLabel(runtime)} generator must be an object`);
-  } else {
-    if (typeof runtime.generator.id !== "string" || runtime.generator.id.length === 0) {
-      pushError(errors, `${runtimeLabel(runtime)} generator.id must be a non-empty string`);
-    }
-    if (typeof runtime.generator.version !== "string" || runtime.generator.version.length === 0) {
-      pushError(errors, `${runtimeLabel(runtime)} generator.version must be a non-empty string`);
-    }
-    if (runtime.generator.package != null && (typeof runtime.generator.package !== "string" || runtime.generator.package.length === 0)) {
-      pushError(errors, `${runtimeLabel(runtime)} generator.package must be a non-empty string when provided`);
-    }
-  }
-  if (runtime.port != null && (!Number.isInteger(runtime.port) || runtime.port <= 0 || runtime.port > 65535)) {
-    pushError(errors, `${runtimeLabel(runtime)} port must be an integer from 1 to 65535`);
-  }
-  return true;
-}
-
-/**
- * @param {ValidationError[]} errors
- * @param {RuntimeTopologyRuntime} runtime
- * @param {Map<string, Record<string, any>>} projections
- * @param {{ configDir?: string|null, rootDir?: string|null }} [options]
- * @returns {void}
- */
-function validateRuntimeCompatibility(errors, runtime, projections, options = {}) {
-  const projection = projections.get(runtime.projection);
-  if (!projection) {
-    pushError(errors, `${runtimeLabel(runtime)} references missing projection '${runtime.projection}'`);
-    return;
-  }
-
-  const resolvedManifest = resolveGeneratorManifestForBinding(runtime.generator, options);
-  const manifest = resolvedManifest.manifest;
-  if (!manifest) {
-    const details = resolvedManifest.errors.length > 0 ? `: ${resolvedManifest.errors.join("; ")}` : "";
-    pushError(errors, `${runtimeLabel(runtime)} for projection '${projection.id}' uses unknown generator '${runtime.generator?.id}' version '${runtime.generator?.version || "unknown"}'${details}`);
-    return;
-  }
-  const manifestValidation = validateGeneratorManifest(manifest);
-  if (!manifestValidation.ok) {
-    for (const message of manifestValidation.errors) {
-      pushError(errors, `${runtimeLabel(runtime)} generator manifest invalid: ${message}`);
-    }
-  }
-  if (manifest.planned) {
-    pushError(errors, `${runtimeLabel(runtime)} for projection '${projection.id}' uses planned generator '${manifest.id}@${manifest.version}', which is not implemented yet`);
-  }
-  if (manifest.version !== runtime.generator.version) {
-    pushError(errors, `${runtimeLabel(runtime)} for projection '${projection.id}' generator '${manifest.id}' version '${runtime.generator.version}' is unsupported; expected '${manifest.version}'`);
-  }
-  if (!isGeneratorCompatible(manifest, runtime.kind, projection)) {
-    pushError(errors, `${runtimeLabel(runtime)} for projection '${projection.id}' generator '${manifest.id}@${manifest.version}' is incompatible with runtime kind '${runtime.kind}' and projection type '${projection.type || "api_contract"}'`);
-  }
-}
-
-/**
- * @param {ValidationError[]} errors
- * @param {RuntimeTopologyRuntime[]} runtimes
- * @returns {void}
- */
-function validateTopologyReferences(errors, runtimes) {
-  const byId = new Map(runtimes.map((runtime) => [runtime.id, runtime]));
-  const usedPorts = new Map();
-  for (const runtime of runtimes) {
-    if (runtime.port != null) {
-      const existing = usedPorts.get(runtime.port);
-      if (existing) {
-        pushError(errors, `Port ${runtime.port} is used by both '${existing}' and '${runtime.id}'`);
-      } else {
-        usedPorts.set(runtime.port, runtime.id);
-      }
-    }
-    if (runtime.kind === "api_service") {
-      if (runtime.uses_database && byId.get(runtime.uses_database)?.kind !== "database") {
-        pushError(errors, `${runtimeLabel(runtime)} references missing database runtime '${runtime.uses_database}'`);
-      }
-    }
-    if (["web_surface", "ios_surface", "android_surface"].includes(runtime.kind)) {
-      if (runtime.uses_api && byId.get(runtime.uses_api)?.kind !== "api_service") {
-        pushError(errors, `${runtimeLabel(runtime)} references missing api runtime '${runtime.uses_api}'`);
-      }
-    }
-  }
-}
-
-/**
- * @param {any} config
- * @param {Record<string, any>|null} [graph]
- * @param {{ configDir?: string|null, rootDir?: string|null }} [options]
- * @returns {{ ok: boolean, errors: ValidationError[] }}
- */
-export function validateProjectConfig(config, graph = null, options = {}) {
-  /** @type {ValidationError[]} */
-  const errors = [];
-  if (!config || typeof config !== "object" || Array.isArray(config)) {
-    return { ok: false, errors: [{ message: "topogram.project.json must contain a JSON object", loc: null }] };
-  }
-  if (typeof config.version !== "string" || config.version.length === 0) {
-    pushError(errors, "topogram.project.json version must be a non-empty string");
-  }
-  validateOutputConfig(errors, config);
-  if (config.topology?.components != null) {
-    pushError(errors, `topogram.project.json ${renameDiagnostic("'topology.components'", "'topology.runtimes'", `"topology": { "runtimes": [] }`)}`);
-  }
-  if (!config.topology || typeof config.topology !== "object" || !Array.isArray(config.topology.runtimes)) {
-    pushError(errors, "topogram.project.json topology.runtimes must be an array");
-  } else {
-    const seenIds = new Set();
-    for (const runtime of config.topology.runtimes) {
-      validateRuntimeShape(errors, runtime, seenIds);
-    }
-    const generatorPolicy = validateProjectGeneratorPolicy(config, options);
-    for (const error of generatorPolicy.errors) {
-      pushError(errors, error.message, error.loc);
-    }
-    if (graph) {
-      const projections = projectionById(graph);
-      for (const runtime of config.topology.runtimes) {
-        validateRuntimeCompatibility(errors, runtime, projections, options);
-      }
-      validateTopologyReferences(errors, config.topology.runtimes);
-    }
-  }
-  return {
-    ok: errors.length === 0,
-    errors
-  };
-}
-
-/**
- * @param {{ errors: ValidationError[] }} result
- * @param {string} [configPath]
- * @returns {string}
- */
-export function formatProjectConfigErrors(result, configPath = PROJECT_CONFIG_FILE) {
-  return result.errors
-    .map((error) => `${normalizeRoot(configPath)} ${error.message}`)
-    .join("\n");
-}
-
-/**
- * @param {ProjectConfigInfo|null|undefined} configInfo
- * @param {string} outputName
- * @returns {string|null}
- */
-export function resolveOutputPath(configInfo, outputName) {
-  const output = configInfo?.config?.outputs?.[outputName];
-  if (!configInfo || !output?.path) {
-    return null;
-  }
-  const baseDir = configInfo.configDir || process.cwd();
-  return resolveComparablePath(path.resolve(baseDir, output.path));
-}
-
-/**
- * @param {ProjectConfigInfo|null|undefined} configInfo
- * @param {string} outDir
- * @returns {{ name: string, ownership: string, path: string }|null}
- */
-export function outputOwnershipForPath(configInfo, outDir) {
-  if (!configInfo?.config?.outputs) {
-    return null;
-  }
-  const resolvedOutDir = resolveComparablePath(outDir);
-  for (const [name, output] of Object.entries(configInfo.config.outputs)) {
-    if (!output?.path) {
-      continue;
-    }
-    const resolvedOutput = resolveComparablePath(path.resolve(configInfo.configDir || process.cwd(), output.path));
-    if (resolvedOutput === resolvedOutDir) {
-      return {
-        name,
-        ownership: output.ownership,
-        path: resolvedOutput
-      };
-    }
-  }
-  return null;
-}
-
-/**
- * @param {ProjectConfigInfo|null|undefined} configInfo
- * @returns {{ ok: boolean, errors: ValidationError[] }}
- */
-export function validateProjectOutputOwnership(configInfo) {
-  /** @type {ValidationError[]} */
-  const errors = [];
-  if (!configInfo?.config?.outputs) {
-    return { ok: true, errors };
-  }
-  for (const [name, output] of Object.entries(configInfo.config.outputs)) {
-    if (!output?.path || !["generated", "maintained"].includes(output.ownership)) {
-      continue;
-    }
-    const resolvedOutput = resolveComparablePath(path.resolve(configInfo.configDir || process.cwd(), output.path));
-    const sentinelPath = path.join(resolvedOutput, GENERATED_OUTPUT_SENTINEL);
-    if (output.ownership === "generated" && fs.existsSync(resolvedOutput) && !fs.existsSync(sentinelPath)) {
-      pushError(
-        errors,
-        `Generated output '${name}' at '${normalizeRoot(resolvedOutput)}' is missing ${GENERATED_OUTPUT_SENTINEL}`
-      );
-    }
-    if (output.ownership === "maintained" && fs.existsSync(sentinelPath)) {
-      pushError(
-        errors,
-        `Maintained output '${name}' at '${normalizeRoot(resolvedOutput)}' contains ${GENERATED_OUTPUT_SENTINEL}`
-      );
-    }
-  }
-  return {
-    ok: errors.length === 0,
-    errors
-  };
-}
+ * @typedef {import("./project-config/index.js").GeneratorBinding} GeneratorBinding
+ * @typedef {import("./project-config/index.js").RuntimeTopologyRuntime} RuntimeTopologyRuntime
+ * @typedef {import("./project-config/index.js").ProjectConfig} ProjectConfig
+ * @typedef {import("./project-config/index.js").ProjectConfigInfo} ProjectConfigInfo
+ * @typedef {import("./project-config/index.js").ValidationError} ValidationError
+ */
+
+export {
+  defaultProjectConfigForGraph,
+  findLegacyImplementationConfig,
+  findProjectConfig,
+  formatProjectConfigErrors,
+  loadProjectConfig,
+  outputOwnershipForPath,
+  projectConfigOrDefault,
+  resolveOutputPath,
+  validateProjectConfig,
+  validateProjectOutputOwnership
+} from "./project-config/index.js";

package/src/resolver/enrich/acceptance-criterion.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Resolver enrichment for acceptance criteria.
 //
 // Back-link arrays:
@@ -5,6 +6,7 @@
 //   verifications  — verifications whose `acceptance_refs` includes this AC
 //   supersededBy   — ACs that supersede *this* one
 
+/** @param {TopogramStatement} ac @param {ResolverBacklinkIndex} index */
 export function enrichAcceptanceCriterion(ac, index) {
   return {
     tasks: (index.tasksByAcceptanceRef.get(ac.id) || []).slice().sort(),

package/src/resolver/enrich/bug.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Resolver enrichment for bugs.
 //
 // Back-link arrays:
@@ -5,6 +6,7 @@
 //                 (typically same set as bug.fixedInVerification, but the
 //                 author may set only one side; we surface both)
 
+/** @param {TopogramStatement} bug @param {ResolverBacklinkIndex} index */
 export function enrichBug(bug, index) {
   return {
     verifiedBy: (index.verificationsFixingBug.get(bug.id) || []).slice().sort()

package/src/resolver/enrich/pitch.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Resolver enrichment for pitches.
 //
 // Builds back-link arrays so consumers can ask a pitch "who follows you?"
@@ -10,6 +11,7 @@
 //
 // Output is merged into the statement by `resolveWorkspace`.
 
+/** @param {TopogramStatement} pitch @param {ResolverBacklinkIndex} index */
 export function enrichPitch(pitch, index) {
   return {
     requirements: (index.requirementsByPitch.get(pitch.id) || []).slice().sort(),

package/src/resolver/enrich/requirement.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Resolver enrichment for requirements.
 //
 // Back-link arrays:
@@ -8,6 +9,7 @@
 //   documents           — docs whose `satisfies` frontmatter points here
 //   rules               — rules whose `from_requirement` is this requirement
 
+/** @param {TopogramStatement} requirement @param {ResolverBacklinkIndex} index */
 export function enrichRequirement(requirement, index) {
   return {
     acceptanceCriteria: (index.acsByRequirement.get(requirement.id) || []).slice().sort(),

package/src/resolver/enrich/task.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Resolver enrichment for tasks.
 //
 // Back-link arrays:
@@ -8,6 +9,7 @@
 // `blocked_by` are reciprocal, because authors only write one side. The
 // resolver bridges them.
 
+/** @param {TopogramStatement} task @param {ResolverBacklinkIndex} index */
 export function enrichTask(task, index) {
   return {
     blockingMe: (index.tasksThatBlockTarget.get(task.id) || []).slice().sort(),