@topogram/cli 0.3.64 → 0.3.66

package/src/resolver/shared.js

@@ -0,0 +1,278 @@
+import { blockEntries, getFieldValue, symbolValues, valueAsArray } from "../validator.js";
+
+export function groupBy(items, keyFn) {
+  const grouped = {};
+  for (const item of items) {
+    const key = keyFn(item);
+    if (!Object.hasOwn(grouped, key)) {
+      grouped[key] = [];
+    }
+    grouped[key].push(item);
+  }
+  return grouped;
+}
+
+export function resolveReference(registry, id) {
+  return registry.get(id) || null;
+}
+
+export function toRef(target) {
+  if (!target) {
+    return null;
+  }
+
+  return {
+    id: target.id,
+    kind: target.kind
+  };
+}
+
+export function resolveReferenceList(registry, value) {
+  return symbolValues(value).map((id) => ({
+    id,
+    target: toRef(resolveReference(registry, id))
+  }));
+}
+
+export function resolveDomainTag(statement, registry) {
+  const domainField = statement.fields.find((field) => field.key === "domain");
+  if (!domainField || domainField.value.type !== "symbol") {
+    return null;
+  }
+  const id = domainField.value.value;
+  return {
+    id,
+    target: toRef(resolveReference(registry, id))
+  };
+}
+
+export function normalizeDomainScopeList(statement, key) {
+  const field = statement.fields.find((f) => f.key === key);
+  if (!field) return [];
+  const items = field.value.type === "list" || field.value.type === "sequence"
+    ? field.value.items
+    : [field.value];
+  return items
+    .map((item) => (item.type === "string" || item.type === "symbol" ? item.value : null))
+    .filter((value) => value !== null);
+}
+
+export function normalizeSequence(items) {
+  return items.map((item) => {
+    if (item.type === "symbol" || item.type === "string") {
+      return item.value;
+    }
+    if (item.type === "list") {
+      return item.items.map((nested) => nested.value);
+    }
+    return item.type;
+  });
+}
+
+export function normalizeFieldsBlock(statement, key = "fields") {
+  return blockEntries(getFieldValue(statement, key)).map((entry) => {
+    const [name, type, requiredness, ...rest] = entry.items;
+    let defaultValue = null;
+
+    for (let i = 0; i < rest.length - 1; i += 1) {
+      if (rest[i].type === "symbol" && rest[i].value === "default") {
+        defaultValue = rest[i + 1]?.value ?? null;
+      }
+    }
+
+    return {
+      name: name?.value ?? null,
+      fieldType: type?.value ?? null,
+      requiredness: requiredness?.value ?? null,
+      defaultValue,
+      raw: normalizeSequence(entry.items),
+      loc: entry.loc
+    };
+  });
+}
+
+export function normalizeGenericBlock(statement, key) {
+  return blockEntries(getFieldValue(statement, key)).map((entry) => ({
+    raw: normalizeSequence(entry.items),
+    loc: entry.loc
+  }));
+}
+
+export function tokenValue(token) {
+  return token?.value ?? null;
+}
+
+export function parseDefaultLiteral(token) {
+  if (!token) return null;
+  if (token.type === "list") {
+    return (token.items || []).map((item) => parseDefaultLiteral(item));
+  }
+  if (token.type === "string") {
+    return token.value ?? null;
+  }
+  if (token.type === "symbol") {
+    if (token.value === "true") return true;
+    if (token.value === "false") return false;
+    if (token.value === "null") return null;
+    if (/^-?\d+$/.test(token.value)) return Number.parseInt(token.value, 10);
+    if (/^-?\d+\.\d+$/.test(token.value)) return Number.parseFloat(token.value);
+    return token.value;
+  }
+  return token.value ?? null;
+}
+
+export function parseLiteralToken(token) {
+  const value = tokenValue(token);
+  if (value == null) {
+    return null;
+  }
+
+  if (value === "true") {
+    return { kind: "boolean", value: true };
+  }
+  if (value === "false") {
+    return { kind: "boolean", value: false };
+  }
+  if (value === "null") {
+    return { kind: "null", value: null };
+  }
+  if (/^-?\d+$/.test(value)) {
+    return { kind: "integer", value: Number.parseInt(value, 10) };
+  }
+  if (/^-?\d+\.\d+$/.test(value)) {
+    return { kind: "number", value: Number.parseFloat(value) };
+  }
+
+  return { kind: "symbol", value };
+}
+
+export function parseComparison(left, operator, right) {
+  if (!left || !operator || !right) {
+    return null;
+  }
+
+  return {
+    type: "comparison",
+    left: tokenValue(left),
+    operator,
+    right: parseLiteralToken(right)
+  };
+}
+
+export function parseInvariantEntry(entry) {
+  const tokens = entry.items;
+  const values = tokens.map((item) => item.value);
+  const [a, b, c, d, e, f, g] = tokens;
+
+  if (tokenValue(b) === "requires") {
+    return {
+      type: "requires",
+      field: tokenValue(a),
+      predicate: parseComparison(c, tokenValue(d), e),
+      raw: values,
+      loc: entry.loc
+    };
+  }
+
+  if (tokenValue(b) === "length") {
+    return {
+      type: "length_check",
+      field: tokenValue(a),
+      operator: tokenValue(c),
+      value: parseLiteralToken(d),
+      raw: values,
+      loc: entry.loc
+    };
+  }
+
+  if (tokenValue(b) === "format") {
+    return {
+      type: "format_check",
+      field: tokenValue(a),
+      operator: tokenValue(c),
+      format: tokenValue(d),
+      raw: values,
+      loc: entry.loc
+    };
+  }
+
+  if (tokenValue(d) === "implies") {
+    return {
+      type: "implication",
+      when: parseComparison(a, tokenValue(b), c),
+      then:
+        tokenValue(f) === "is"
+          ? {
+              type: "state_check",
+              field: tokenValue(e),
+              operator: "is",
+              value: parseLiteralToken(g)
+            }
+          : parseComparison(e, tokenValue(f), g),
+      raw: values,
+      loc: entry.loc
+    };
+  }
+
+  if (["==", "!=", "<", "<=", ">", ">="].includes(tokenValue(b))) {
+    return {
+      type: "comparison",
+      left: tokenValue(a),
+      operator: tokenValue(b),
+      right: parseLiteralToken(c),
+      raw: values,
+      loc: entry.loc
+    };
+  }
+
+  return {
+    type: "unknown",
+    raw: values,
+    loc: entry.loc
+  };
+}
+
+export function parseRuleExpression(value) {
+  const text = valueAsArray(value).map((item) => item.value).join(" ").trim();
+  const match = text.match(/^(.+?)\s*(==|!=|<=|>=|<|>)\s*(.+)$/);
+  if (!match) {
+    return {
+      type: "unknown",
+      raw: text
+    };
+  }
+
+  return {
+    type: "comparison",
+    left: match[1].trim(),
+    operator: match[2],
+    right: {
+      kind: "symbol",
+      value: match[3].trim()
+    },
+    raw: text
+  };
+}
+
+export function parseSymbolNode(value) {
+  return {
+    type: "symbol",
+    id: value
+  };
+}
+
+export function parseSymbolNodes(values) {
+  return values.map((value, index) => ({
+    ...parseSymbolNode(value),
+    order: index
+  }));
+}
+
+export function parseReferenceNodes(values) {
+  return values.map((entry, index) => ({
+    type: "reference",
+    id: entry.id,
+    target: entry.target || { id: entry.id, kind: null },
+    order: index
+  }));
+}

package/src/resolver/widgets.js

@@ -0,0 +1,132 @@
+import { blockEntries, getFieldValue, symbolValues } from "../validator.js";
+import { normalizeSequence, parseDefaultLiteral, parseReferenceNodes, tokenValue } from "./shared.js";
+
+export function normalizeWidgetProps(statement) {
+  return blockEntries(getFieldValue(statement, "props")).map((entry) => {
+    const [name, type, requiredness, ...rest] = entry.items;
+    let defaultValue = null;
+
+    for (let i = 0; i < rest.length - 1; i += 1) {
+      if (rest[i].type === "symbol" && rest[i].value === "default") {
+        defaultValue = parseDefaultLiteral(rest[i + 1]);
+      }
+    }
+
+    return {
+      name: name?.value ?? null,
+      fieldType: type?.value ?? null,
+      requiredness: requiredness?.value ?? null,
+      defaultValue,
+      raw: normalizeSequence(entry.items),
+      loc: entry.loc
+    };
+  });
+}
+
+export function normalizeWidgetEvents(statement, registry) {
+  return blockEntries(getFieldValue(statement, "events")).map((entry) => {
+    const [eventName, shapeRef] = entry.items;
+    const shapeId = tokenValue(shapeRef);
+    return {
+      id: tokenValue(eventName),
+      shape: shapeId
+        ? {
+            id: shapeId,
+            kind: registry.get(shapeId)?.kind || null
+          }
+        : null,
+      raw: normalizeSequence(entry.items),
+      loc: entry.loc
+    };
+  });
+}
+
+export function normalizeWidgetSlots(statement) {
+  return blockEntries(getFieldValue(statement, "slots")).map((entry) => ({
+    id: tokenValue(entry.items[0]),
+    description: tokenValue(entry.items[1]),
+    raw: normalizeSequence(entry.items),
+    loc: entry.loc
+  }));
+}
+
+export function normalizeBehaviorValue(token) {
+  if (!token) {
+    return null;
+  }
+  if (token.type === "list") {
+    return token.items.map((item) => normalizeBehaviorValue(item));
+  }
+  return parseDefaultLiteral(token);
+}
+
+export function normalizeWidgetBehaviors(statement) {
+  const structured = blockEntries(getFieldValue(statement, "behaviors")).map((entry) => {
+    const kind = tokenValue(entry.items[0]);
+    const directives = {};
+    for (let i = 1; i < entry.items.length; i += 2) {
+      const key = tokenValue(entry.items[i]);
+      if (!key) {
+        continue;
+      }
+      directives[key] = normalizeBehaviorValue(entry.items[i + 1]);
+    }
+    return {
+      kind,
+      directives,
+      source: "structured",
+      raw: normalizeSequence(entry.items),
+      loc: entry.loc
+    };
+  });
+
+  const structuredKinds = new Set(structured.map((entry) => entry.kind));
+  const shorthand = symbolValues(getFieldValue(statement, "behavior"))
+    .filter((kind) => !structuredKinds.has(kind))
+    .map((kind) => ({
+      kind,
+      directives: {},
+      source: "shorthand",
+      raw: [kind],
+      loc: null
+    }));
+
+  return [...structured, ...shorthand];
+}
+
+export function buildWidgetContract(statement) {
+  return {
+    type: "ui_widget_contract",
+    id: statement.id,
+    name: statement.name || statement.id,
+    description: statement.description || null,
+    category: statement.category || null,
+    version: statement.version || null,
+    status: statement.status || null,
+    props: (statement.props || []).map((prop) => ({
+      name: prop.name,
+      type: prop.fieldType,
+      requiredness: prop.requiredness,
+      defaultValue: prop.defaultValue ?? null
+    })),
+    events: (statement.events || []).map((event) => ({
+      id: event.id,
+      shape: event.shape || null
+    })),
+    slots: (statement.slots || []).map((slot) => ({
+      id: slot.id,
+      description: slot.description || null
+    })),
+    behavior: [...(statement.behavior || [])],
+    behaviors: (statement.behaviors || []).map((behavior) => ({
+      kind: behavior.kind,
+      directives: { ...(behavior.directives || {}) },
+      source: behavior.source || null
+    })),
+    patterns: [...(statement.patterns || [])],
+    regions: [...(statement.regions || [])],
+    approvals: [...(statement.approvals || [])],
+    lookups: parseReferenceNodes(statement.lookups || []),
+    dependencies: parseReferenceNodes(statement.dependencies || [])
+  };
+}

package/src/sdlc/adopt.js

@@ -6,6 +6,7 @@
 
 import { existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
 import path from "node:path";
+import { DEFAULT_TOPO_FOLDER_NAME, resolveTopoRoot } from "../workspace-paths.js";
 
 const SDLC_FOLDERS = [
   "pitches",
@@ -17,7 +18,7 @@ const SDLC_FOLDERS = [
 ];
 
 function ensureFolder(root, name) {
-  const dir = path.join(root, "topogram", name);
+  const dir = path.join(resolveTopoRoot(root), name);
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true });
     return { name, created: true };
@@ -29,8 +30,8 @@ function scanPressure(root) {
   // Pressure scan: count statements per kind so the operator knows the
   // workspace's current shape. We do not attempt to backfill — that's the
   // operator's job after they pick a starting point.
-  const tg = path.join(root, "topogram");
-  if (!existsSync(tg)) return { error: `No 'topogram/' directory found at ${root}` };
+  const tg = resolveTopoRoot(root);
+  if (!existsSync(tg)) return { error: `No '${DEFAULT_TOPO_FOLDER_NAME}/' workspace folder found at ${root}` };
   let totalFiles = 0;
   function walk(dir) {
     for (const entry of readdirSync(dir)) {
@@ -50,8 +51,8 @@ function scanPressure(root) {
 
 export function sdlcAdopt(workspaceRoot) {
   const root = path.resolve(workspaceRoot);
-  if (!existsSync(path.join(root, "topogram"))) {
-    return { ok: false, error: `No 'topogram/' directory at ${root}; run 'topogram new' first` };
+  if (!existsSync(resolveTopoRoot(root))) {
+    return { ok: false, error: `No '${DEFAULT_TOPO_FOLDER_NAME}/' workspace folder at ${root}; run 'topogram new' first` };
   }
   const folders = SDLC_FOLDERS.map((name) => ensureFolder(root, name));
   const pressure = scanPressure(root);

package/src/sdlc/paths.js

@@ -1,11 +1,9 @@
-import path from "node:path";
+import { resolveTopoRoot, resolveWorkspaceContext } from "../workspace-paths.js";
 
 export function topogramRootForSdlc(inputPath) {
-  const absolute = path.resolve(inputPath);
-  return path.basename(absolute) === "topogram" ? absolute : path.join(absolute, "topogram");
+  return resolveTopoRoot(inputPath);
 }
 
 export function projectRootForSdlc(inputPath) {
-  const absolute = path.resolve(inputPath);
-  return path.basename(absolute) === "topogram" ? path.dirname(absolute) : absolute;
+  return resolveWorkspaceContext(inputPath).projectRoot;
 }

package/src/sdlc/scaffold.js

@@ -3,6 +3,7 @@
 
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
+import { resolveTopoRoot } from "../workspace-paths.js";
 
 const TEMPLATES = {
   pitch: (slug) => `pitch pitch_${slug} {
@@ -73,7 +74,7 @@ export function scaffoldNew(workspaceRoot, kind, slug) {
   if (!slug || !/^[a-z][a-z0-9_]*$/.test(slug)) {
     return { ok: false, error: `Invalid slug '${slug}' — must match /^[a-z][a-z0-9_]*$/` };
   }
-  const targetDir = path.join(workspaceRoot, "topogram", `${kind === "acceptance_criterion" ? "acceptance_criteria" : kind + "s"}`);
+  const targetDir = path.join(resolveTopoRoot(workspaceRoot), `${kind === "acceptance_criterion" ? "acceptance_criteria" : kind + "s"}`);
   if (!existsSync(targetDir)) mkdirSync(targetDir, { recursive: true });
   const targetFile = path.join(targetDir, `${slug}.tg`);
   if (existsSync(targetFile)) {

package/src/template-trust/constants.js

@@ -0,0 +1,62 @@
+// @ts-check
+
+export const TEMPLATE_TRUST_FILE = ".topogram-template-trust.json";
+export const TEMPLATE_TRUST_POLICY = "topogram-template-executable-implementation-v1";
+export const IGNORED_IMPLEMENTATION_ENTRIES = new Set([".DS_Store", "node_modules", ".tmp"]);
+export const MAX_TEXT_DIFF_BYTES = 256 * 1024;
+export const TRUST_REVIEW_COMMANDS = "`topogram trust status`, `topogram trust diff`, and `topogram trust template`";
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+export function normalizeRoot(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+export function normalizeRelativePath(value) {
+  return value.replace(/\\/g, "/");
+}
+
+/**
+ * @param {string} relativePath
+ * @returns {string}
+ */
+export function unsupportedImplementationSymlinkMessage(relativePath) {
+  return `Template implementation contains unsupported symlink '${relativePath}'. Implementation trust hashes real files under implementation/; symlinks can point outside the trusted root. Replace symlinks with real files under implementation/, then run ${TRUST_REVIEW_COMMANDS} after review.`;
+}
+
+/**
+ * @param {string} modulePath
+ * @returns {string}
+ */
+export function implementationOutsideRootMessage(modulePath) {
+  return `Template implementation module '${modulePath}' must be under implementation/ for template-attached projects. Keep executable template code inside implementation/ so the trust record covers what topogram generate may load. Move the module back under implementation/, then run ${TRUST_REVIEW_COMMANDS} after review.`;
+}
+
+/**
+ * @param {string|string[]} issueOrIssues
+ * @returns {string}
+ */
+export function templateTrustRecoveryGuidance(issueOrIssues) {
+  const issues = Array.isArray(issueOrIssues) ? issueOrIssues : [issueOrIssues];
+  const text = issues.join("\n");
+  if (issues.length > 0 && issues.every((issue) =>
+    issue.includes("topogram trust status") &&
+    issue.includes("topogram trust diff") &&
+    issue.includes("topogram trust template")
+  )) {
+    return "";
+  }
+  if (text.includes("unsupported symlink")) {
+    return `Replace symlinks with real files under implementation/, then run ${TRUST_REVIEW_COMMANDS} after review.`;
+  }
+  if (text.includes("must be under implementation/")) {
+    return `Keep executable template code under implementation/ so it can be hashed and trusted; move the module back under implementation/, then run ${TRUST_REVIEW_COMMANDS} after review.`;
+  }
+  return `Run \`topogram trust status\` and \`topogram trust diff\` to review implementation changes; after review, run \`topogram trust template\` to trust the current files.`;
+}