@topogram/cli 0.3.72 → 0.3.74

package/src/sdlc/gate.js

@@ -0,0 +1,352 @@
+// @ts-check
+
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import { loadImplementationProvider } from "../example-implementation.js";
+import { parsePath } from "../parser.js";
+import {
+  loadProjectConfig,
+  projectConfigOrDefault,
+  validateProjectConfig,
+  validateProjectOutputOwnership
+} from "../project-config.js";
+import { resolveWorkspace } from "../resolver.js";
+import { validateProjectImplementationTrust } from "../template-trust.js";
+import { resolveTopoRoot, resolveWorkspaceContext } from "../workspace-paths.js";
+import { checkWorkspace as checkSdlcWorkspace } from "./check.js";
+import { loadSdlcPolicy } from "./policy.js";
+
+/**
+ * @typedef {Object} SdlcGateOptions
+ * @property {string|null} [base]
+ * @property {string|null} [head]
+ * @property {string[]} [sdlcIds]
+ * @property {string|null} [exemption]
+ * @property {boolean} [requireAdopted]
+ * @property {string[]} [changedFiles]
+ * @property {string|null} [prBody]
+ */
+
+/**
+ * @param {string} flag
+ * @returns {string}
+ */
+function envValue(flag) {
+  return process.env[flag] || "";
+}
+
+/**
+ * @param {string} pattern
+ * @returns {RegExp}
+ */
+function globPatternToRegex(pattern) {
+  const escaped = pattern
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*\*/g, "\u0000")
+    .replace(/\*/g, "[^/]*")
+    .replace(/\u0000/g, ".*");
+  return new RegExp(`^${escaped}$`);
+}
+
+/**
+ * @param {string} file
+ * @param {string[]} patterns
+ * @returns {boolean}
+ */
+function matchesAnyProtectedPath(file, patterns) {
+  const normalized = file.replace(/\\/g, "/");
+  return patterns.some((pattern) => globPatternToRegex(pattern).test(normalized));
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string|null|undefined} base
+ * @param {string|null|undefined} head
+ * @returns {{ ok: true, files: string[] } | { ok: false, error: string }}
+ */
+function gitChangedFiles(projectRoot, base, head) {
+  if (!base || !head) {
+    return { ok: true, files: [] };
+  }
+  const result = childProcess.spawnSync("git", ["diff", "--name-only", `${base}...${head}`], {
+    cwd: projectRoot,
+    encoding: "utf8"
+  });
+  if (result.status !== 0) {
+    return {
+      ok: false,
+      error: (result.stderr || result.stdout || `git diff failed with status ${result.status}`).trim()
+    };
+  }
+  return {
+    ok: true,
+    files: result.stdout.split(/\r?\n/).map(/** @param {string} line */ (line) => line.trim()).filter(Boolean)
+  };
+}
+
+/**
+ * @returns {string|null}
+ */
+function githubPullRequestBody() {
+  const eventPath = envValue("GITHUB_EVENT_PATH");
+  if (!eventPath || !fs.existsSync(eventPath)) {
+    return null;
+  }
+  try {
+    const event = JSON.parse(fs.readFileSync(eventPath, "utf8"));
+    return typeof event?.pull_request?.body === "string" ? event.pull_request.body : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string|null|undefined} body
+ * @returns {string[]}
+ */
+function sdlcIdsFromText(body) {
+  if (!body) {
+    return [];
+  }
+  const matches = body.match(/\b(?:task|bug|req|pitch)_[a-z][a-z0-9_]*\b/g) || [];
+  return [...new Set(matches)];
+}
+
+/**
+ * @param {string|null|undefined} body
+ * @returns {string|null}
+ */
+function exemptionFromText(body) {
+  if (!body) {
+    return null;
+  }
+  const match = body.match(/exemption\s+reason\s*:\s*(.+)/i);
+  const value = match?.[1]?.trim();
+  return value && value.toLowerCase() !== "none" && value !== "N/A" ? value : null;
+}
+
+/**
+ * @param {string} file
+ * @returns {boolean}
+ */
+function isSdlcRecordChange(file) {
+  const normalized = file.replace(/\\/g, "/");
+  if (normalized === "topogram.sdlc-policy.json") {
+    return true;
+  }
+  return [
+    "topo/sdlc/pitches/",
+    "topo/sdlc/requirements/",
+    "topo/sdlc/acceptance_criteria/",
+    "topo/sdlc/tasks/",
+    "topo/sdlc/plans/",
+    "topo/sdlc/bugs/",
+    "topo/sdlc/decisions/",
+    "topo/sdlc/docs/",
+    "topo/pitches/",
+    "topo/requirements/",
+    "topo/acceptance_criteria/",
+    "topo/tasks/",
+    "topo/plans/",
+    "topo/bugs/",
+    "topo/docs/"
+  ].some((prefix) => normalized.startsWith(prefix));
+}
+
+/**
+ * @param {string} topogramPath
+ * @returns {Promise<Record<string, any>>}
+ */
+async function runTopogramCheckPayload(topogramPath) {
+  const ast = parsePath(topogramPath);
+  const resolved = resolveWorkspace(ast);
+  const implementation = await loadImplementationProvider(topogramPath).catch(() => null);
+  const explicitProjectConfig = loadProjectConfig(topogramPath);
+  const projectConfigInfo = explicitProjectConfig ||
+    (implementation ? projectConfigOrDefault(topogramPath, resolved.ok ? resolved.graph : null, implementation) : null);
+  const projectValidation = projectConfigInfo
+    ? {
+        ok: [
+          validateProjectConfig(projectConfigInfo.config, resolved.ok ? resolved.graph : null, { configDir: projectConfigInfo.configDir }),
+          validateProjectOutputOwnership(projectConfigInfo),
+          validateProjectImplementationTrust(projectConfigInfo)
+        ].every((result) => result.ok),
+        errors: [
+          ...validateProjectConfig(projectConfigInfo.config, resolved.ok ? resolved.graph : null, { configDir: projectConfigInfo.configDir }).errors,
+          ...validateProjectOutputOwnership(projectConfigInfo).errors,
+          ...validateProjectImplementationTrust(projectConfigInfo).errors
+        ]
+      }
+    : { ok: false, errors: [{ message: "Missing topogram.project.json or compatible topogram.implementation.json", loc: null }] };
+  return {
+    ok: Boolean(resolved.ok && projectValidation.ok),
+    topogram: resolved.ok,
+    project: projectValidation.ok,
+    errors: [
+      ...(!resolved.ok ? resolved.validation.errors.map(/** @param {any} error */ (error) => ({ source: "topogram", message: error.message })) : []),
+      ...projectValidation.errors.map((error) => ({ source: "project", message: error.message }))
+    ]
+  };
+}
+
+/**
+ * @param {Record<string, any>} graph
+ * @param {string[]} ids
+ * @param {string[]} requiredKinds
+ * @returns {{ valid: string[], invalid: string[] }}
+ */
+function validateSdlcIds(graph, ids, requiredKinds) {
+  const byId = new Map((graph?.statements || []).map(/** @param {any} statement */ (statement) => [statement.id, statement]));
+  /** @type {string[]} */
+  const valid = [];
+  /** @type {string[]} */
+  const invalid = [];
+  for (const id of ids) {
+    const statement = byId.get(id);
+    if (statement && requiredKinds.includes(String(statement.kind))) {
+      valid.push(id);
+    } else {
+      invalid.push(id);
+    }
+  }
+  return { valid, invalid };
+}
+
+/**
+ * @param {string} inputPath
+ * @param {SdlcGateOptions} [options]
+ * @returns {Promise<Record<string, any>>}
+ */
+export async function runSdlcGate(inputPath = ".", options = {}) {
+  const context = resolveWorkspaceContext(inputPath || ".");
+  const projectRoot = context.projectRoot;
+  const topogramRoot = resolveTopoRoot(inputPath || ".");
+  const policyInfo = loadSdlcPolicy(projectRoot);
+  const policy = policyInfo.policy;
+  /** @type {string[]} */
+  const errors = [];
+  /** @type {string[]} */
+  const warnings = [];
+
+  if (policyInfo.diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
+    errors.push(...policyInfo.diagnostics.filter((diagnostic) => diagnostic.severity === "error").map((diagnostic) => diagnostic.message));
+  }
+
+  if (!policyInfo.exists || policyInfo.status !== "adopted") {
+    if (options.requireAdopted) {
+      errors.push("SDLC policy is not adopted; required because --require-adopted was passed.");
+    }
+    return {
+      type: "sdlc_gate",
+      version: "1",
+      ok: errors.length === 0,
+      projectRoot,
+      topogramRoot,
+      policy: {
+        exists: policyInfo.exists,
+        path: policyInfo.path,
+        status: policyInfo.status,
+        mode: policyInfo.mode
+      },
+      changedFiles: [],
+      protectedChanges: [],
+      sdlcIds: [],
+      validSdlcIds: [],
+      invalidSdlcIds: [],
+      sdlcRecordChanges: [],
+      exemption: null,
+      checks: [],
+      warnings,
+      errors,
+      nextCommands: policyInfo.exists ? ["topogram sdlc policy check --json"] : ["topogram sdlc policy init ."]
+    };
+  }
+
+  if (!policy) {
+    errors.push("SDLC policy could not be loaded.");
+  }
+
+  const checkPayload = await runTopogramCheckPayload(topogramRoot);
+  if (!checkPayload.ok) {
+    errors.push("topogram check failed.");
+  }
+  const ast = parsePath(topogramRoot);
+  const resolved = resolveWorkspace(ast);
+  let sdlcCheck = { ok: false, errors: [{ message: "workspace did not resolve" }], warnings: [] };
+  if (resolved.ok) {
+    sdlcCheck = checkSdlcWorkspace(topogramRoot, resolved);
+    if (!sdlcCheck.ok || sdlcCheck.warnings.length > 0) {
+      errors.push("topogram sdlc check --strict failed.");
+    }
+  } else {
+    errors.push("workspace resolution failed before SDLC check.");
+  }
+
+  /** @type {{ ok: true, files: string[] } | { ok: false, error: string }} */
+  const diffResult = options.changedFiles
+    ? { ok: true, files: options.changedFiles }
+    : gitChangedFiles(projectRoot, options.base || null, options.head || null);
+  if (!diffResult.ok) {
+    errors.push(`Could not compute changed files: ${diffResult.error}`);
+  }
+  const changedFiles = diffResult.ok ? diffResult.files : [];
+  const protectedChanges = changedFiles.filter((file) => matchesAnyProtectedPath(file, policy?.protectedPaths || []));
+  const sdlcRecordChanges = changedFiles.filter(isSdlcRecordChange);
+  const prBody = options.prBody ?? githubPullRequestBody();
+  const explicitIds = options.sdlcIds || [];
+  const sdlcIds = [...new Set([...explicitIds, ...sdlcIdsFromText(prBody)])];
+  const idValidation = resolved.ok
+    ? validateSdlcIds(resolved.graph, sdlcIds, policy?.requiredItemKinds || [])
+    : { valid: [], invalid: sdlcIds };
+  const exemption = options.exemption || exemptionFromText(prBody);
+  const hasAllowedExemption = Boolean(exemption && policy?.allowExemptions);
+  const hasSdlcLinkage = idValidation.valid.length > 0 || sdlcRecordChanges.length > 0 || hasAllowedExemption;
+
+  if (idValidation.invalid.length > 0) {
+    warnings.push(`Ignored invalid SDLC id(s): ${idValidation.invalid.join(", ")}`);
+  }
+  if (protectedChanges.length > 0 && !hasSdlcLinkage) {
+    const message = "Protected changes require a valid SDLC item, a topo/*.tg SDLC record change, or an allowed exemption.";
+    if (policy?.mode === "enforced") {
+      errors.push(message);
+    } else {
+      warnings.push(message);
+    }
+  }
+
+  return {
+    type: "sdlc_gate",
+    version: "1",
+    ok: errors.length === 0,
+    projectRoot,
+    topogramRoot,
+    policy: {
+      exists: policyInfo.exists,
+      path: policyInfo.path,
+      status: policyInfo.status,
+      mode: policyInfo.mode,
+      protectedPaths: policy?.protectedPaths || [],
+      requiredItemKinds: policy?.requiredItemKinds || [],
+      allowExemptions: policy?.allowExemptions ?? false
+    },
+    changedFiles,
+    protectedChanges,
+    sdlcIds,
+    validSdlcIds: idValidation.valid,
+    invalidSdlcIds: idValidation.invalid,
+    sdlcRecordChanges,
+    exemption: exemption || null,
+    checks: [
+      { command: "topogram check", ok: checkPayload.ok, errors: checkPayload.errors || [] },
+      { command: "topogram sdlc check --strict", ok: Boolean(sdlcCheck.ok && sdlcCheck.warnings.length === 0), errors: sdlcCheck.errors || [], warnings: sdlcCheck.warnings || [] }
+    ],
+    warnings,
+    errors,
+    nextCommands: [
+      "topogram sdlc explain <task-id> --json",
+      "topogram query single-agent-plan . --mode modeling --capability <cap-id> --json"
+    ]
+  };
+}

package/src/sdlc/history.d.ts

@@ -0,0 +1,7 @@
+export function historyPath(...args: any[]): any;
+export function readHistory(...args: any[]): any;
+export function validateHistory(...args: any[]): any;
+export function writeHistory(...args: any[]): any;
+export function appendTransition(...args: any[]): any;
+export function lastTransition(...args: any[]): any;
+export function detectDriftedStatus(...args: any[]): any;

package/src/sdlc/history.js

@@ -1,6 +1,6 @@
 // SDLC history sidecar.
 //
-// Stored at `<topogram-root>/.topogram-sdlc-history.json` as a
+// Stored at `<topogram-root>/sdlc/.topogram-sdlc-history.json` as a
 // JSON object keyed by statement id. Each entry is an append-only array of
 // transition records:
 //
@@ -15,18 +15,28 @@
 // CLI" warnings when an artifact's current status doesn't match the last
 // recorded transition.
 
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { topogramRootForSdlc } from "./paths.js";
+import { sdlcRootForSdlc, topogramRootForSdlc } from "./paths.js";
 
 const HISTORY_FILENAME = ".topogram-sdlc-history.json";
 
 export function historyPath(workspaceRoot) {
+  return path.join(sdlcRootForSdlc(workspaceRoot), HISTORY_FILENAME);
+}
+
+function legacyHistoryPath(workspaceRoot) {
   return path.join(topogramRootForSdlc(workspaceRoot), HISTORY_FILENAME);
 }
 
 export function readHistory(workspaceRoot) {
-  const file = historyPath(workspaceRoot);
+  let file = historyPath(workspaceRoot);
+  if (!existsSync(file)) {
+    const legacyFile = legacyHistoryPath(workspaceRoot);
+    if (existsSync(legacyFile)) {
+      file = legacyFile;
+    }
+  }
   if (!existsSync(file)) return {};
   try {
     return JSON.parse(readFileSync(file, "utf8"));
@@ -35,8 +45,43 @@ export function readHistory(workspaceRoot) {
   }
 }
 
+export function validateHistory(history) {
+  const warnings = [];
+  if (!history || typeof history !== "object" || Array.isArray(history)) {
+    return [{ message: "SDLC history sidecar must be a JSON object keyed by statement id" }];
+  }
+  for (const [id, entries] of Object.entries(history)) {
+    if (id === "__error") continue;
+    if (!Array.isArray(entries)) {
+      warnings.push({ id, message: `SDLC history entry '${id}' must be an array of transition records` });
+      continue;
+    }
+    entries.forEach((entry, index) => {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        warnings.push({ id, message: `SDLC history entry '${id}' transition ${index + 1} must be an object` });
+        return;
+      }
+      for (const key of ["from", "to", "at"]) {
+        if (typeof entry[key] !== "string" || entry[key].trim() === "") {
+          warnings.push({ id, message: `SDLC history entry '${id}' transition ${index + 1} must include string '${key}'` });
+        }
+      }
+      for (const key of ["by", "note"]) {
+        if (entry[key] !== null && entry[key] !== undefined && typeof entry[key] !== "string") {
+          warnings.push({ id, message: `SDLC history entry '${id}' transition ${index + 1} field '${key}' must be a string or null` });
+        }
+      }
+    });
+  }
+  return warnings;
+}
+
 export function writeHistory(workspaceRoot, history) {
   const file = historyPath(workspaceRoot);
+  const dir = path.dirname(file);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
   writeFileSync(file, JSON.stringify(history, null, 2) + "\n", "utf8");
 }
 
@@ -59,7 +104,7 @@ export function appendTransition(workspaceRoot, id, record) {
 
 export function lastTransition(history, id) {
   const entries = history[id];
-  if (!entries || entries.length === 0) return null;
+  if (!Array.isArray(entries) || entries.length === 0) return null;
   return entries[entries.length - 1];
 }
 

package/src/sdlc/link.js

@@ -0,0 +1,172 @@
+// @ts-check
+
+import fs from "node:fs";
+
+import { parsePath } from "../parser.js";
+import { resolveWorkspace } from "../resolver.js";
+import { resolveTopoRoot } from "../workspace-paths.js";
+
+/**
+ * @typedef {{ field: string, property: string, mode: "list"|"single" }} LinkRule
+ */
+
+/** @type {Map<string, LinkRule>} */
+const LINK_RULES = new Map([
+  ["task:requirement", { field: "satisfies", property: "satisfies", mode: "list" }],
+  ["task:acceptance_criterion", { field: "acceptance_refs", property: "acceptanceRefs", mode: "list" }],
+  ["task:verification", { field: "verification_refs", property: "verificationRefs", mode: "list" }],
+  ["bug:task", { field: "fixed_in", property: "fixedIn", mode: "list" }],
+  ["bug:verification", { field: "fixed_in_verification", property: "fixedInVerification", mode: "list" }],
+  ["acceptance_criterion:requirement", { field: "requirement", property: "requirement", mode: "single" }]
+]);
+
+/**
+ * @param {Record<string, any>} workspaceAst
+ * @param {string} id
+ * @returns {Record<string, any>|null}
+ */
+function findAstStatement(workspaceAst, id) {
+  for (const file of workspaceAst.files || []) {
+    for (const statement of file.statements || []) {
+      if (statement.id === id) {
+        return statement;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {Record<string, any>} statement
+ * @param {string} key
+ * @returns {Record<string, any>|null}
+ */
+function findAstField(statement, key) {
+  return (statement.fields || []).find(/** @param {any} field */ (field) => field.key === key) || null;
+}
+
+/**
+ * @param {Record<string, any>|null|undefined} ref
+ * @returns {string|null}
+ */
+function refId(ref) {
+  return typeof ref === "string" ? ref : (typeof ref?.id === "string" ? ref.id : null);
+}
+
+/**
+ * @param {Record<string, any>} statement
+ * @param {LinkRule} rule
+ * @returns {string[]}
+ */
+function currentLinkIds(statement, rule) {
+  const value = statement[rule.property];
+  if (rule.mode === "single") {
+    const id = refId(value);
+    return id ? [id] : [];
+  }
+  return Array.isArray(value)
+    ? value.map(refId).filter((id) => typeof id === "string")
+    : [];
+}
+
+/**
+ * @param {string} source
+ * @param {number} offset
+ * @returns {{ start: number, end: number }}
+ */
+function lineRangeForOffset(source, offset) {
+  const start = source.lastIndexOf("\n", Math.max(0, offset - 1)) + 1;
+  const newline = source.indexOf("\n", offset);
+  const end = newline >= 0 ? newline + 1 : source.length;
+  return { start, end };
+}
+
+/**
+ * @param {Record<string, any>} statement
+ * @returns {number}
+ */
+function insertionOffset(statement) {
+  const statusField = findAstField(statement, "status");
+  if (statusField) {
+    return statusField.loc.start.offset;
+  }
+  return Math.max(statement.loc.end.offset - 2, statement.loc.start.offset);
+}
+
+/**
+ * @param {string} source
+ * @param {Record<string, any>} astStatement
+ * @param {LinkRule} rule
+ * @param {string[]} ids
+ * @returns {string}
+ */
+function rewriteLinkField(source, astStatement, rule, ids) {
+  const value = rule.mode === "single" ? ids[0] : `[${ids.join(" ")}]`;
+  const replacement = `  ${rule.field} ${value}\n`;
+  const existing = findAstField(astStatement, rule.field);
+  if (existing) {
+    const range = lineRangeForOffset(source, existing.loc.start.offset);
+    return `${source.slice(0, range.start)}${replacement}${source.slice(range.end)}`;
+  }
+  const offset = insertionOffset(astStatement);
+  const range = lineRangeForOffset(source, offset);
+  return `${source.slice(0, range.start)}${replacement}${source.slice(range.start)}`;
+}
+
+/**
+ * @param {string} workspaceRoot
+ * @param {string} fromId
+ * @param {string} toId
+ * @param {{ write?: boolean }} [options]
+ * @returns {Record<string, any>}
+ */
+export function linkSdlcRecord(workspaceRoot, fromId, toId, options = {}) {
+  const sdlcRoot = resolveTopoRoot(workspaceRoot || ".");
+  const ast = parsePath(sdlcRoot);
+  const resolved = resolveWorkspace(ast);
+  if (!resolved.ok) {
+    return { ok: false, error: "workspace failed validation; cannot link SDLC records", validation: resolved.validation };
+  }
+
+  const from = resolved.graph.byId?.get(fromId) || resolved.graph.statements.find(/** @param {any} statement */ (statement) => statement.id === fromId);
+  const to = resolved.graph.byId?.get(toId) || resolved.graph.statements.find(/** @param {any} statement */ (statement) => statement.id === toId);
+  if (!from) {
+    return { ok: false, error: `Statement '${fromId}' not found` };
+  }
+  if (!to) {
+    return { ok: false, error: `Statement '${toId}' not found` };
+  }
+  const rule = LINK_RULES.get(`${from.kind}:${to.kind}`);
+  if (!rule) {
+    return { ok: false, error: `No supported SDLC link from ${from.kind} to ${to.kind}` };
+  }
+
+  const current = currentLinkIds(from, rule);
+  const next = rule.mode === "single" ? [toId] : [...new Set([...current, toId])];
+  if (rule.mode === "single" && current[0] && current[0] !== toId) {
+    return { ok: false, error: `${fromId} already links ${rule.field} to ${current[0]}` };
+  }
+  const astStatement = findAstStatement(ast, fromId);
+  if (!astStatement) {
+    return { ok: false, error: `Source statement '${fromId}' not found` };
+  }
+
+  const file = astStatement.loc.file;
+  const original = fs.readFileSync(file, "utf8");
+  const rewritten = rewriteLinkField(original, astStatement, rule, next);
+  if (options.write) {
+    fs.writeFileSync(file, rewritten, "utf8");
+  }
+
+  return {
+    ok: true,
+    from: { id: fromId, kind: from.kind },
+    to: { id: toId, kind: to.kind },
+    field: rule.field,
+    file,
+    before: current,
+    after: next,
+    dryRun: !options.write,
+    written: Boolean(options.write)
+  };
+}

package/src/sdlc/paths.d.ts

@@ -0,0 +1,4 @@
+export const SDLC_RECORD_ROOT: string;
+export function topogramRootForSdlc(...args: any[]): any;
+export function sdlcRootForSdlc(...args: any[]): any;
+export function projectRootForSdlc(...args: any[]): any;

package/src/sdlc/paths.js

@@ -1,9 +1,17 @@
+import path from "node:path";
+
 import { resolveTopoRoot, resolveWorkspaceContext } from "../workspace-paths.js";
 
+export const SDLC_RECORD_ROOT = "sdlc";
+
 export function topogramRootForSdlc(inputPath) {
   return resolveTopoRoot(inputPath);
 }
 
+export function sdlcRootForSdlc(inputPath) {
+  return path.join(topogramRootForSdlc(inputPath), SDLC_RECORD_ROOT);
+}
+
 export function projectRootForSdlc(inputPath) {
   return resolveWorkspaceContext(inputPath).projectRoot;
 }