@topogram/cli 0.3.72 → 0.3.73

package/src/sdlc/plan-steps.js

@@ -0,0 +1,71 @@
+// @ts-check
+
+import { blockEntries } from "../validator.js";
+
+/**
+ * @typedef {{
+ *   id: string|null,
+ *   status: string|null,
+ *   description: string|null,
+ *   notes: string|null,
+ *   outcome: string|null,
+ *   raw: string[],
+ *   loc: any
+ * }} PlanStep
+ */
+
+/**
+ * @param {any} token
+ * @returns {string|null}
+ */
+function tokenValue(token) {
+  return token && (token.type === "symbol" || token.type === "string") ? token.value : null;
+}
+
+/**
+ * @param {any[]} items
+ * @param {string} key
+ * @returns {string|null}
+ */
+function keyedValue(items, key) {
+  for (let index = 2; index < items.length - 1; index += 2) {
+    if (tokenValue(items[index]) === key) {
+      return tokenValue(items[index + 1]);
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {any} entry
+ * @returns {PlanStep}
+ */
+export function parsePlanStepEntry(entry) {
+  const items = entry?.items || [];
+  return {
+    id: tokenValue(items[1]),
+    status: keyedValue(items, "status"),
+    description: keyedValue(items, "description"),
+    notes: keyedValue(items, "notes"),
+    outcome: keyedValue(items, "outcome"),
+    raw: items.map(/** @param {any} item */ (item) => tokenValue(item)).filter(/** @param {string|null} value */ (value) => value !== null),
+    loc: entry?.loc || null
+  };
+}
+
+/**
+ * @param {any} value
+ * @returns {PlanStep[]}
+ */
+export function parsePlanSteps(value) {
+  return blockEntries(value).map((entry) => parsePlanStepEntry(entry));
+}
+
+/**
+ * @param {string} planId
+ * @param {string} stepId
+ * @returns {string}
+ */
+export function planStepHistoryId(planId, stepId) {
+  return `${planId}#${stepId}`;
+}

package/src/sdlc/plan.js

@@ -0,0 +1,245 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { parsePath } from "../parser.js";
+import { resolveWorkspace } from "../resolver.js";
+import { PLAN_STEP_STATUSES } from "../validator/kinds.js";
+import { appendTransition, lastTransition, readHistory } from "./history.js";
+import { sdlcRootForSdlc } from "./paths.js";
+import { parsePlanStepEntry, planStepHistoryId } from "./plan-steps.js";
+
+/** @type {Record<string, string[]>} */
+const STEP_TRANSITIONS = {
+  pending: ["in-progress", "blocked", "done", "skipped"],
+  "in-progress": ["done", "blocked", "pending", "skipped"],
+  blocked: ["pending", "in-progress", "skipped"],
+  done: [],
+  skipped: []
+};
+
+/**
+ * @param {string} slug
+ * @returns {string}
+ */
+function humanize(slug) {
+  return slug
+    .replace(/[_-]+/g, " ")
+    .replace(/\b\w/g, (m) => m.toUpperCase());
+}
+
+/**
+ * @param {any} ast
+ * @param {string} id
+ * @returns {{file: any, statement: any}|null}
+ */
+function findAstStatement(ast, id) {
+  for (const file of ast.files) {
+    for (const statement of file.statements) {
+      if (statement.id === id) {
+        return { file, statement };
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {any} statement
+ * @param {string} stepId
+ * @returns {{entry: any, parsed: import("./plan-steps.js").PlanStep, statusToken: any}|null}
+ */
+function findStepEntry(statement, stepId) {
+  const stepsField = statement.fields.find(/** @param {any} field */ (field) => field.key === "steps");
+  if (!stepsField || stepsField.value.type !== "block") return null;
+  for (const entry of stepsField.value.entries) {
+    const parsed = parsePlanStepEntry(entry);
+    if (parsed.id !== stepId) continue;
+    for (let index = 2; index < entry.items.length - 1; index += 2) {
+      if (entry.items[index]?.type === "symbol" && entry.items[index].value === "status") {
+        return { entry, parsed, statusToken: entry.items[index + 1] };
+      }
+    }
+    return { entry, parsed, statusToken: null };
+  }
+  return null;
+}
+
+/**
+ * @param {string} source
+ * @param {any} token
+ * @param {string} status
+ * @returns {string}
+ */
+function rewriteToken(source, token, status) {
+  return source.slice(0, token.loc.start.offset) + status + source.slice(token.loc.end.offset);
+}
+
+/**
+ * @param {string} workspaceRoot
+ * @param {string} taskId
+ * @param {string} slug
+ * @param {{write?: boolean}} [options]
+ * @returns {any}
+ */
+export function createPlan(workspaceRoot, taskId, slug, options = {}) {
+  if (!taskId || !/^task_[a-z][a-z0-9_]*$/.test(taskId)) {
+    return { ok: false, error: `Invalid task id '${taskId}'` };
+  }
+  if (!slug || !/^[a-z][a-z0-9_]*$/.test(slug)) {
+    return { ok: false, error: `Invalid slug '${slug}' — must match /^[a-z][a-z0-9_]*$/` };
+  }
+
+  const ast = parsePath(workspaceRoot);
+  const resolved = resolveWorkspace(ast);
+  if (!resolved.ok) {
+    return { ok: false, error: "workspace failed validation; cannot create plan", validation: resolved.validation };
+  }
+  const task = resolved.graph.statements.find(/** @param {any} statement */ (statement) => statement.id === taskId && statement.kind === "task");
+  if (!task) {
+    return { ok: false, error: `Task '${taskId}' not found` };
+  }
+
+  const planId = `plan_${slug}`;
+  if (resolved.graph.statements.some(/** @param {any} statement */ (statement) => statement.id === planId)) {
+    return { ok: false, error: `Statement '${planId}' already exists` };
+  }
+
+  const targetDir = path.join(sdlcRootForSdlc(workspaceRoot), "plans");
+  const targetFile = path.join(targetDir, `${slug}.tg`);
+  const content = `plan ${planId} {
+  name "${humanize(slug)}"
+  description "Implementation plan for ${taskId}."
+  task ${taskId}
+  priority medium
+  notes "Record approach notes here."
+  outcome "Record what worked, what did not, and what to repeat later."
+  steps {
+    step inspect_current_state status pending description "Inspect current behavior and constraints."
+    step implement_changes status pending description "Implement the planned changes."
+    step verify_results status pending description "Run focused checks and record verification."
+  }
+  status draft
+}
+`;
+
+  if (!options.write) {
+    return { ok: true, dryRun: true, id: planId, task: taskId, file: targetFile, content };
+  }
+  if (!fs.existsSync(targetDir)) fs.mkdirSync(targetDir, { recursive: true });
+  if (fs.existsSync(targetFile)) {
+    return { ok: false, error: `Refusing to overwrite '${targetFile}'` };
+  }
+  fs.writeFileSync(targetFile, content, "utf8");
+  return { ok: true, dryRun: false, id: planId, task: taskId, file: targetFile };
+}
+
+/**
+ * @param {string} workspaceRoot
+ * @param {string} planId
+ * @returns {any}
+ */
+export function explainPlan(workspaceRoot, planId) {
+  const ast = parsePath(workspaceRoot);
+  const resolved = resolveWorkspace(ast);
+  if (!resolved.ok) {
+    return { ok: false, error: "workspace failed validation; cannot explain plan", validation: resolved.validation };
+  }
+  const plan = resolved.graph.statements.find(/** @param {any} statement */ (statement) => statement.id === planId && statement.kind === "plan");
+  if (!plan) {
+    return { ok: false, error: `Plan '${planId}' not found` };
+  }
+  const history = readHistory(workspaceRoot);
+  const steps = (plan.steps || []).map(/** @param {any} step */ (step) => ({
+    ...step,
+    last_transition: lastTransition(history, planStepHistoryId(plan.id, step.id))
+  }));
+  const nextStep = steps.find(/** @param {any} step */ (step) => step.status !== "done" && step.status !== "skipped") || null;
+  return {
+    ok: true,
+    type: "sdlc_plan_explain",
+    id: plan.id,
+    status: plan.status,
+    task: plan.task?.id || null,
+    summary: {
+      name: plan.name,
+      description: plan.description,
+      notes: plan.notes || null,
+      outcome: plan.outcome || null
+    },
+    steps,
+    next_step: nextStep,
+    next_action: nextStep
+      ? { kind: "work", step: nextStep.id, reason: `next incomplete step is '${nextStep.id}'` }
+      : { kind: "none", reason: "all steps are done or skipped" }
+  };
+}
+
+/**
+ * @param {string} workspaceRoot
+ * @param {string} planId
+ * @param {string} stepId
+ * @param {string} targetStatus
+ * @param {{write?: boolean, dryRun?: boolean, actor?: string|null, note?: string|null}} [options]
+ * @returns {any}
+ */
+export function transitionPlanStep(workspaceRoot, planId, stepId, targetStatus, options = {}) {
+  if (!PLAN_STEP_STATUSES.has(targetStatus)) {
+    return { ok: false, error: `Invalid plan step status '${targetStatus}'` };
+  }
+
+  const ast = parsePath(workspaceRoot);
+  const resolved = resolveWorkspace(ast);
+  if (!resolved.ok) {
+    return { ok: false, error: "workspace failed validation; cannot transition plan step", validation: resolved.validation };
+  }
+
+  const located = findAstStatement(ast, planId);
+  if (!located || located.statement.kind !== "plan") {
+    return { ok: false, error: `Plan '${planId}' not found` };
+  }
+  const step = findStepEntry(located.statement, stepId);
+  if (!step) {
+    return { ok: false, error: `Step '${stepId}' not found on plan '${planId}'` };
+  }
+  if (!step.statusToken) {
+    return { ok: false, error: `Step '${stepId}' on plan '${planId}' has no status field to rewrite` };
+  }
+
+  const fromStatus = step.parsed.status;
+  const allowed = STEP_TRANSITIONS[fromStatus || ""];
+  if (!allowed) {
+    return { ok: false, error: `Unknown plan step status '${fromStatus}'` };
+  }
+  if (!allowed.includes(targetStatus)) {
+    return {
+      ok: false,
+      error: `Plan step cannot transition from '${fromStatus}' to '${targetStatus}' — allowed: ${allowed.join(", ") || "(terminal)"}`
+    };
+  }
+
+  const sourcePath = located.statement.loc.file;
+  const original = fs.readFileSync(sourcePath, "utf8");
+  const rewritten = rewriteToken(original, step.statusToken, targetStatus);
+  const shouldWrite = options.write === true && options.dryRun !== true;
+  if (shouldWrite) {
+    fs.writeFileSync(sourcePath, rewritten, "utf8");
+    appendTransition(workspaceRoot, planStepHistoryId(planId, stepId), {
+      from: fromStatus,
+      to: targetStatus,
+      by: options.actor || null,
+      note: options.note || null
+    });
+  }
+
+  return {
+    ok: true,
+    id: planId,
+    step: stepId,
+    from: fromStatus,
+    to: targetStatus,
+    file: sourcePath,
+    dryRun: !shouldWrite
+  };
+}

package/src/sdlc/policy.js

@@ -0,0 +1,249 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { resolveWorkspaceContext } from "../workspace-paths.js";
+
+export const SDLC_POLICY_FILE = "topogram.sdlc-policy.json";
+export const SDLC_POLICY_VERSION = "1";
+
+export const SDLC_POLICY_STATUSES = new Set(["adopted", "not_adopted"]);
+export const SDLC_POLICY_MODES = new Set(["advisory", "enforced"]);
+export const SDLC_POLICY_ITEM_KINDS = new Set(["task", "bug", "requirement", "pitch"]);
+
+export const DEFAULT_PROTECTED_PATHS = [
+  "engine/**",
+  "docs/**",
+  "scripts/**",
+  ".github/**",
+  "topo/**",
+  "AGENTS.md",
+  "CONTRIBUTING.md",
+  "README.md",
+  "package.json"
+];
+
+export const DEFAULT_REQUIRED_ITEM_KINDS = ["task", "bug", "requirement", "pitch"];
+
+/**
+ * @typedef {Object} SdlcPolicy
+ * @property {string} version
+ * @property {"adopted"|"not_adopted"} status
+ * @property {"advisory"|"enforced"} mode
+ * @property {string[]} protectedPaths
+ * @property {string[]} requiredItemKinds
+ * @property {boolean} allowExemptions
+ * @property {boolean} releaseNotes
+ */
+
+/**
+ * @typedef {Object} SdlcPolicyInfo
+ * @property {boolean} exists
+ * @property {string} path
+ * @property {SdlcPolicy|null} policy
+ * @property {"adopted"|"not_adopted"} status
+ * @property {"advisory"|"enforced"|null} mode
+ * @property {Array<{ severity: "error"|"warning", message: string }>} diagnostics
+ */
+
+/**
+ * @returns {SdlcPolicy}
+ */
+export function defaultSdlcPolicy() {
+  return {
+    version: SDLC_POLICY_VERSION,
+    status: "adopted",
+    mode: "enforced",
+    protectedPaths: [...DEFAULT_PROTECTED_PATHS],
+    requiredItemKinds: [...DEFAULT_REQUIRED_ITEM_KINDS],
+    allowExemptions: true,
+    releaseNotes: true
+  };
+}
+
+/**
+ * @param {string} inputPath
+ * @returns {string}
+ */
+export function policyProjectRoot(inputPath = ".") {
+  return resolveWorkspaceContext(inputPath || ".").projectRoot;
+}
+
+/**
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isSafeRelativePattern(value) {
+  const normalized = value.replace(/\\/g, "/").trim();
+  return Boolean(normalized) &&
+    !path.isAbsolute(normalized) &&
+    normalized !== ".." &&
+    !normalized.startsWith("../") &&
+    !normalized.includes("/../") &&
+    !normalized.endsWith("/..");
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string[]}
+ */
+function stringArray(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+
+/**
+ * @param {unknown} value
+ * @returns {{ ok: boolean, policy: SdlcPolicy|null, diagnostics: SdlcPolicyInfo["diagnostics"] }}
+ */
+export function validateSdlcPolicy(value) {
+  /** @type {SdlcPolicyInfo["diagnostics"]} */
+  const diagnostics = [];
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {
+      ok: false,
+      policy: null,
+      diagnostics: [{ severity: "error", message: `${SDLC_POLICY_FILE} must contain a JSON object.` }]
+    };
+  }
+
+  const record = /** @type {Record<string, unknown>} */ (value);
+  if (record.version !== SDLC_POLICY_VERSION) {
+    diagnostics.push({ severity: "error", message: `SDLC policy version must be "${SDLC_POLICY_VERSION}".` });
+  }
+  if (typeof record.status !== "string" || !SDLC_POLICY_STATUSES.has(record.status)) {
+    diagnostics.push({ severity: "error", message: "SDLC policy status must be adopted or not_adopted." });
+  }
+  if (typeof record.mode !== "string" || !SDLC_POLICY_MODES.has(record.mode)) {
+    diagnostics.push({ severity: "error", message: "SDLC policy mode must be advisory or enforced." });
+  }
+  if (record.status === "not_adopted" && record.mode === "enforced") {
+    diagnostics.push({ severity: "error", message: "SDLC policy cannot be not_adopted and enforced." });
+  }
+  if (!Array.isArray(record.protectedPaths) || record.protectedPaths.length === 0) {
+    diagnostics.push({ severity: "error", message: "SDLC policy protectedPaths must be a non-empty string array." });
+  } else {
+    for (const item of record.protectedPaths) {
+      if (typeof item !== "string" || !isSafeRelativePattern(item)) {
+        diagnostics.push({ severity: "error", message: `Invalid protected path '${String(item)}'. Paths must be relative and must not escape the project root.` });
+      }
+    }
+  }
+  if (!Array.isArray(record.requiredItemKinds) || record.requiredItemKinds.length === 0) {
+    diagnostics.push({ severity: "error", message: "SDLC policy requiredItemKinds must be a non-empty string array." });
+  } else {
+    for (const item of record.requiredItemKinds) {
+      if (typeof item !== "string" || !SDLC_POLICY_ITEM_KINDS.has(item)) {
+        diagnostics.push({ severity: "error", message: `Invalid required SDLC item kind '${String(item)}'.` });
+      }
+    }
+  }
+  if (typeof record.allowExemptions !== "boolean") {
+    diagnostics.push({ severity: "error", message: "SDLC policy allowExemptions must be a boolean." });
+  }
+  if (typeof record.releaseNotes !== "boolean") {
+    diagnostics.push({ severity: "error", message: "SDLC policy releaseNotes must be a boolean." });
+  }
+
+  const ok = diagnostics.every((diagnostic) => diagnostic.severity !== "error");
+  if (!ok) {
+    return { ok, policy: null, diagnostics };
+  }
+
+  return {
+    ok,
+    policy: {
+      version: String(record.version),
+      status: /** @type {"adopted"|"not_adopted"} */ (record.status),
+      mode: /** @type {"advisory"|"enforced"} */ (record.mode),
+      protectedPaths: stringArray(record.protectedPaths),
+      requiredItemKinds: stringArray(record.requiredItemKinds),
+      allowExemptions: Boolean(record.allowExemptions),
+      releaseNotes: Boolean(record.releaseNotes)
+    },
+    diagnostics
+  };
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {SdlcPolicyInfo}
+ */
+export function loadSdlcPolicy(projectRoot) {
+  const policyPath = path.join(projectRoot, SDLC_POLICY_FILE);
+  if (!fs.existsSync(policyPath)) {
+    return {
+      exists: false,
+      path: policyPath,
+      policy: null,
+      status: "not_adopted",
+      mode: null,
+      diagnostics: []
+    };
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(policyPath, "utf8"));
+    const validation = validateSdlcPolicy(parsed);
+    return {
+      exists: true,
+      path: policyPath,
+      policy: validation.policy,
+      status: validation.policy?.status || "not_adopted",
+      mode: validation.policy?.mode || null,
+      diagnostics: validation.diagnostics
+    };
+  } catch (error) {
+    return {
+      exists: true,
+      path: policyPath,
+      policy: null,
+      status: "not_adopted",
+      mode: null,
+      diagnostics: [{ severity: "error", message: `Could not read ${SDLC_POLICY_FILE}: ${error instanceof Error ? error.message : String(error)}` }]
+    };
+  }
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {{ ok: boolean, file: string, policy: SdlcPolicy }}
+ */
+export function writeDefaultSdlcPolicy(projectRoot) {
+  const file = path.join(projectRoot, SDLC_POLICY_FILE);
+  if (fs.existsSync(file)) {
+    throw new Error(`${SDLC_POLICY_FILE} already exists.`);
+  }
+  const policy = defaultSdlcPolicy();
+  fs.writeFileSync(file, `${JSON.stringify(policy, null, 2)}\n`, "utf8");
+  return { ok: true, file, policy };
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {Record<string, any>}
+ */
+export function explainSdlcPolicy(projectRoot) {
+  const info = loadSdlcPolicy(projectRoot);
+  return {
+    type: "sdlc_policy_explain",
+    version: "1",
+    ok: info.diagnostics.every((diagnostic) => diagnostic.severity !== "error"),
+    policy: {
+      exists: info.exists,
+      path: info.path,
+      status: info.status,
+      mode: info.mode,
+      protectedPaths: info.policy?.protectedPaths || [],
+      requiredItemKinds: info.policy?.requiredItemKinds || [],
+      allowExemptions: info.policy?.allowExemptions ?? false,
+      releaseNotes: info.policy?.releaseNotes ?? false
+    },
+    diagnostics: info.diagnostics,
+    enforcement: info.status === "adopted"
+      ? (info.mode === "enforced" ? "Protected changes require SDLC linkage or an allowed exemption." : "Gaps are reported without failing.")
+      : "Project has not adopted enforced SDLC.",
+    nextCommands: info.exists
+      ? ["topogram sdlc policy check --json", "topogram sdlc gate . --require-adopted --json"]
+      : ["topogram sdlc policy init .", "topogram sdlc policy check --json"]
+  };
+}