create-cmp-cli 0.8.0 → 0.10.0

package/template/qa/lib/comments.mjs

@@ -0,0 +1,252 @@
+// The comments ledger — the console's talk-back channel (VERIFICATION-LAYER-DESIGN.md
+// §7.3). Approvals stay binding; comments are advisory input the agent must read, act
+// on, and close. This file is the bridge seam: the console's `POST /api/comment` (via a
+// dynamic bridge, same degrade-honestly pattern as approvals-bridge.mjs) and the
+// `review_comments`/`resolve_comment` MCP tools call the SAME functions this file
+// exports — the contract below is binding for both sides and must not drift.
+//
+// Three concerns, kept separable (mirrors qa/lib/approvals.mjs's split):
+//   1. STATE (`qa/comments.json`) — the ledger: { schema, comments: Comment[] }.
+//   2. VALIDATION (`addComment`) — refuses empty text and malformed/unknown targets
+//      before anything is written. Refusal over fabrication: an invalid comment is
+//      never silently coerced into a valid-looking one.
+//   3. TRANSITIONS (`addComment`/`resolveComment`) — append-only; resolving never
+//      deletes a comment, it flips status and records who closed it and why.
+//
+// Read/write asymmetry is deliberate and differs from approvals.mjs on purpose:
+//   - A MISSING file is tolerated as the empty seed on read (a brand-new project has
+//     no comments yet — that's not corruption) and is created on first write.
+//   - A file that EXISTS but is corrupt (unparsable JSON, wrong shape, or a schema
+//     string that isn't "cmp-comments/1") is NOT tolerated on read — listComments
+//     throws a descriptive error instead of returning an empty list. Approvals can
+//     safely treat corruption as "all unreviewed" because that is the conservative
+//     (non-blocking) default; silently reading a broken comments ledger as "no
+//     comments" would instead HIDE real human feedback, which is the one thing this
+//     file exists to surface. Honest failure beats a fabricated empty inbox. Writers
+//     (addComment/resolveComment) catch that same error and turn it into
+//     {ok:false, reason} — they never overwrite a ledger they could not parse.
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const COMMENTS_REL_PATH = "qa/comments.json";
+export const COMMENTS_SCHEMA = "cmp-comments/1";
+
+/** target.type -> the fields addComment requires on `target` for that type. */
+const TARGET_FIELD_REQUIREMENTS = {
+  screen: ["screen"],
+  element: ["screen", "testTag"],
+  "spec-line": ["file", "clauseId"],
+  "design-system": ["token"],
+  architecture: ["path"],
+  general: [],
+};
+
+const VALID_TARGET_TYPES = Object.keys(TARGET_FIELD_REQUIREMENTS);
+
+function ledgerPath(root) {
+  return path.join(root, COMMENTS_REL_PATH);
+}
+
+/**
+ * Parse a comments.json payload already read from disk. Throws a descriptive
+ * Error for anything that isn't a well-formed `{schema, comments:[]}` ledger —
+ * callers decide whether that means "surface it" (read) or "refuse the write"
+ * (addComment/resolveComment).
+ * @param {string} raw
+ * @returns {{schema: string, comments: object[]}}
+ */
+function parseLedger(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(
+      `${COMMENTS_REL_PATH} is not valid JSON — refusing to treat it as an empty ledger (that would silently hide any comments it actually contains). Fix or restore the file.`,
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.comments)) {
+    throw new Error(
+      `${COMMENTS_REL_PATH} has an unexpected shape (expected {schema, comments: [...]}) — refusing to read it as a ledger.`,
+    );
+  }
+  if (parsed.schema !== undefined && parsed.schema !== COMMENTS_SCHEMA) {
+    throw new Error(
+      `${COMMENTS_REL_PATH} declares schema "${parsed.schema}", expected "${COMMENTS_SCHEMA}" — refusing to read an unknown-schema ledger.`,
+    );
+  }
+  return { schema: COMMENTS_SCHEMA, comments: parsed.comments };
+}
+
+/**
+ * Read the ledger. A MISSING file is the tolerated empty seed. A file that
+ * exists but fails `parseLedger` throws — see the file-level note on why reads
+ * do not tolerate corruption the way qa/lib/approvals.mjs does.
+ * @param {string} root
+ * @returns {{schema: string, comments: object[]}}
+ */
+function readLedger(root) {
+  let raw;
+  try {
+    raw = fs.readFileSync(ledgerPath(root), "utf8");
+  } catch {
+    return { schema: COMMENTS_SCHEMA, comments: [] };
+  }
+  return parseLedger(raw);
+}
+
+/**
+ * Write the ledger (deterministic key order, trailing newline) — creates
+ * qa/comments.json and its parent dir if this is the first write.
+ * @param {string} root
+ * @param {{comments: object[]}} state
+ */
+function writeLedger(root, state) {
+  const p = ledgerPath(root);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const out = { schema: COMMENTS_SCHEMA, comments: state.comments };
+  fs.writeFileSync(p, `${JSON.stringify(out, null, 2)}\n`);
+}
+
+/**
+ * Next id: "c" + (1 + the highest existing numeric suffix), so ids are
+ * monotonic and never reused even if the ledger is edited by hand between
+ * calls (count-based numbering would reuse an id after any external edit;
+ * max-based numbering does not).
+ * @param {object[]} comments
+ * @returns {string}
+ */
+function nextId(comments) {
+  let max = 0;
+  for (const c of comments) {
+    const m = typeof c.id === "string" && c.id.match(/^c(\d+)$/);
+    if (m) max = Math.max(max, Number(m[1]));
+  }
+  return `c${max + 1}`;
+}
+
+function nonEmptyString(v) {
+  return typeof v === "string" && v.trim().length > 0;
+}
+
+// ── Reads ────────────────────────────────────────────────────────────────────
+
+/**
+ * Every comment in the ledger, optionally filtered by status. Throws if
+ * qa/comments.json exists but is corrupt or declares an unknown schema (see
+ * the file-level note) — callers that must never throw (a console route, a
+ * blocking MCP tool) should catch and surface the message rather than
+ * swallow it into a fabricated empty list.
+ * @param {string} root
+ * @param {{status?: "open"|"resolved"}} [opts]
+ * @returns {{schema: string, comments: object[]}}
+ */
+export function listComments(root, opts = {}) {
+  const state = readLedger(root);
+  const comments = opts.status ? state.comments.filter((c) => c.status === opts.status) : state.comments;
+  return { schema: COMMENTS_SCHEMA, comments };
+}
+
+// ── Writes ───────────────────────────────────────────────────────────────────
+
+/**
+ * Add a comment. Refuses (never throws):
+ *   - empty or whitespace-only `text`
+ *   - a missing/malformed `target` or an unknown `target.type`
+ *   - a `target` missing a field its type requires (screen -> screen; element ->
+ *     screen, testTag; spec-line -> file, clauseId; design-system -> token;
+ *     architecture -> path; general -> none)
+ *   - a ledger that exists but cannot be parsed (corrupt/unknown-schema) — the
+ *     write is refused rather than overwriting a file we could not honestly read
+ * @param {string} root
+ * @param {{target: object, text: string, author?: string}} input
+ * @returns {{ok: true, comment: object} | {ok: false, reason: string}}
+ */
+export function addComment(root, { target, text, author } = {}) {
+  if (!nonEmptyString(text)) {
+    return { ok: false, reason: "comment text is empty or whitespace-only — refusing to record an empty comment." };
+  }
+  if (!target || typeof target !== "object" || typeof target.type !== "string") {
+    return {
+      ok: false,
+      reason: `comment target is missing or malformed — expected {type, ...} with type one of: ${VALID_TARGET_TYPES.join(", ")}.`,
+    };
+  }
+  const requiredFields = TARGET_FIELD_REQUIREMENTS[target.type];
+  if (!requiredFields) {
+    return {
+      ok: false,
+      reason: `unknown target type "${target.type}" — valid types: ${VALID_TARGET_TYPES.join(", ")}.`,
+    };
+  }
+  const missingFields = requiredFields.filter((f) => !nonEmptyString(target[f]));
+  if (missingFields.length > 0) {
+    return {
+      ok: false,
+      reason: `target type "${target.type}" requires ${requiredFields.join(", ")} — missing or empty: ${missingFields.join(", ")}.`,
+    };
+  }
+
+  let state;
+  try {
+    state = readLedger(root);
+  } catch (err) {
+    return { ok: false, reason: err.message };
+  }
+
+  const comment = {
+    id: nextId(state.comments),
+    target,
+    text: text.trim(),
+    author: nonEmptyString(author) ? author.trim() : "anonymous",
+    createdAt: new Date().toISOString(),
+    status: "open",
+  };
+  writeLedger(root, { comments: [...state.comments, comment] });
+  return { ok: true, comment };
+}
+
+/**
+ * Resolve a comment: stamps status "resolved", who closed it, when, and an
+ * optional note explaining what changed as a result. Refuses (never throws):
+ *   - an unknown id
+ *   - a comment that is already resolved (double-resolve)
+ *   - a ledger that exists but cannot be parsed
+ * @param {string} root
+ * @param {string} id
+ * @param {{note?: string, author?: string}} [opts]
+ * @returns {{ok: true, comment: object} | {ok: false, reason: string}}
+ */
+export function resolveComment(root, id, opts = {}) {
+  let state;
+  try {
+    state = readLedger(root);
+  } catch (err) {
+    return { ok: false, reason: err.message };
+  }
+
+  const idx = state.comments.findIndex((c) => c.id === id);
+  if (idx === -1) {
+    const known = state.comments.map((c) => c.id).join(", ") || "(none — the ledger is empty)";
+    return { ok: false, reason: `unknown comment id "${id}" — known ids: ${known}.` };
+  }
+  const existing = state.comments[idx];
+  if (existing.status === "resolved") {
+    return {
+      ok: false,
+      reason: `comment "${id}" is already resolved (at ${existing.resolvedAt} by ${existing.resolvedBy}) — refusing to double-resolve.`,
+    };
+  }
+
+  const resolved = {
+    ...existing,
+    status: "resolved",
+    resolvedAt: new Date().toISOString(),
+    resolvedBy: nonEmptyString(opts.author) ? opts.author.trim() : "anonymous",
+    ...(nonEmptyString(opts.note) ? { resolutionNote: opts.note.trim() } : {}),
+  };
+  const comments = [...state.comments];
+  comments[idx] = resolved;
+  writeLedger(root, { comments });
+  return { ok: true, comment: resolved };
+}

package/template/qa/lib/component-stories.mjs

@@ -0,0 +1,183 @@
+// component-stories.mjs — the component ↔ story parity gate (the IMP-1
+// screen↔registry parity idea, applied at component granularity).
+//
+// Every `@Composable fun` in `composeApp/src/commonMain/**/presentation/
+// components/*.kt` must have a preview-registry story whose id is
+// `component.<kebab-case-of-the-composable-name>` (AppHeader →
+// "component.app-header"), registered in the desktopMain inspector sources
+// (ComponentStories.kt, or PreviewRegistry.kt for generated conditional
+// components like PlaceholderScreen). The gate fails BOTH directions, like
+// specCoverage: a component with no story (the render pipeline is blind to
+// it) and a story id with no component (a stale story surviving a rename).
+//
+// Detection is a pragmatic source scan, not a Kotlin front-end — the same
+// stance as the console's components scan (inspector/mcp/src/lib/
+// components.mjs, whose @Composable-window heuristic and kebab derivation
+// this file mirrors; keep the two in sync).
+
+import fs from "node:fs";
+import path from "node:path";
+
+/** PascalCase/camelCase → kebab-case: AppHeader → app-header, ListItemCard → list-item-card. */
+export function kebabCase(name) {
+  return String(name)
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+    .toLowerCase();
+}
+
+/** The registry story id a component of this name must register. */
+export function componentStoryId(name) {
+  return `component.${kebabCase(name)}`;
+}
+
+// How far past an `@Composable` occurrence to look for the `fun Name(` it
+// governs — mirrors the console scan's FUN_SEARCH_WINDOW.
+const FUN_SEARCH_WINDOW = 500;
+
+/**
+ * Every `@Composable fun Name(` declaration name in one file's text —
+ * includes private/internal composables (the console's Components page lists
+ * them, so the parity gate covers them too).
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function findComposableNames(text) {
+  const names = [];
+  const composableRe = /@Composable\b/g;
+  let m;
+  while ((m = composableRe.exec(text))) {
+    const window = text.slice(m.index, m.index + FUN_SEARCH_WINDOW);
+    const funMatch = window.match(/fun\s+(?:<[^>]*>\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*(?:<[^>]*>)?\s*\(/);
+    if (funMatch) names.push(funMatch[1]);
+  }
+  return names;
+}
+
+function walkDirs(root, wanted) {
+  const out = [];
+  (function walk(dir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const p = path.join(dir, e.name);
+      if (e.name === wanted) out.push(p);
+      else walk(p);
+    }
+  })(root);
+  return out;
+}
+
+function ktFilesIn(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isFile() && e.name.endsWith(".kt"))
+    .map((e) => path.join(dir, e.name));
+}
+
+function walkKtFilesDeep(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...walkKtFilesDeep(p));
+    else if (e.name.endsWith(".kt")) out.push(p);
+  }
+  return out;
+}
+
+const STORY_ID_RE = /"component\.([a-z0-9][a-z0-9.-]*)"/g;
+
+/**
+ * Evaluate component ↔ story parity for a project root.
+ * SKIPs (never fails) when the surface doesn't exist: no components dir, or
+ * no desktopMain inspector dir (the `--no-inspector` scaffold has no preview
+ * registry to hold stories).
+ * @param {string} root project root (contains composeApp/)
+ * @returns {{verdict: "PASS"|"FAIL"|"SKIP", reason?: string, details?: object}}
+ */
+export function evaluateComponentStoryParity(root) {
+  const commonRoot = path.join(root, "composeApp", "src", "commonMain", "kotlin");
+  const desktopRoot = path.join(root, "composeApp", "src", "desktopMain", "kotlin");
+
+  const componentsDirs = walkDirs(commonRoot, "presentation")
+    .map((p) => path.join(p, "components"))
+    .filter((p) => fs.existsSync(p));
+  if (componentsDirs.length === 0) {
+    return { verdict: "SKIP", reason: "no presentation/components directory under commonMain — nothing to check" };
+  }
+
+  const inspectorDirs = walkDirs(desktopRoot, "inspector");
+  if (inspectorDirs.length === 0) {
+    return {
+      verdict: "SKIP",
+      reason: "no desktopMain inspector sources (preview harness not included) — no story registry to check against",
+    };
+  }
+
+  // Components: every @Composable in the registry dir (direct children only —
+  // the same surface the console's Components page scans).
+  const components = []; // { name, file }
+  for (const dir of componentsDirs) {
+    for (const file of ktFilesIn(dir)) {
+      const rel = path.relative(root, file).split(path.sep).join("/");
+      for (const name of findComposableNames(fs.readFileSync(file, "utf8"))) {
+        components.push({ name, file: rel });
+      }
+    }
+  }
+
+  // Stories: every quoted "component.<kebab>" id in the inspector sources.
+  const storyIds = new Set();
+  for (const dir of inspectorDirs) {
+    for (const file of walkKtFilesDeep(dir)) {
+      const text = fs.readFileSync(file, "utf8");
+      for (const match of text.matchAll(STORY_ID_RE)) {
+        storyIds.add(`component.${match[1]}`);
+      }
+    }
+  }
+
+  const expectedIds = new Map(components.map((c) => [componentStoryId(c.name), c]));
+  const missing = [...expectedIds.entries()].filter(([id]) => !storyIds.has(id));
+  const orphans = [...storyIds].filter((id) => !expectedIds.has(id)).sort();
+
+  const details = {
+    components: components.length,
+    stories: storyIds.size,
+    missing: missing.map(([id]) => id),
+    orphans,
+  };
+
+  if (missing.length === 0 && orphans.length === 0) {
+    return { verdict: "PASS", details };
+  }
+
+  const lines = ["Component ↔ story parity broken — the components registry and its preview stories have drifted apart:"];
+  for (const [id, c] of missing) {
+    lines.push(
+      `  [${c.name}] ${c.file} — no component story registered. Add ScreenPreview("${id}", …) to composeApp/src/desktopMain/**/inspector/ComponentStories.kt (kebab-case of the composable name).`,
+    );
+  }
+  for (const id of orphans) {
+    lines.push(
+      `  ["${id}"] story id has no matching @Composable in presentation/components — remove the stale story or fix the id.`,
+    );
+  }
+  return { verdict: "FAIL", reason: lines.join("\n"), details };
+}

package/template/qa/lib/inputs-hash.mjs

@@ -125,7 +125,11 @@ function resolveSurfaceFiles(root) {
  * @returns {{ hash: string, fileCount: number }}
  */
 export function computeInputsHash(root) {
-  const files = [...new Set(resolveSurfaceFiles(root))].sort((a, b) => a.localeCompare(b));
+  // Code-unit sort (default String sort), NOT localeCompare: the hash depends
+  // on iteration order, and ICU collation varies with the machine's locale
+  // (e.g. a da_DK machine orders "aa" after "z"; en orders case-insensitively
+  // where code units do not) — the same tree must hash identically everywhere.
+  const files = [...new Set(resolveSurfaceFiles(root))].sort();
 
   const overall = createHash("sha256");
   for (const relPath of files) {