@nodii/dev 0.6.1 → 0.6.2

package/dist/guidelines.js

@@ -0,0 +1,223 @@
+// `nodii-dev design guideline list|show|propose` and `design changeset
+// list|show`: design-system guideline edits (A-032, DEV-DS-GUIDELINES-EDIT-1).
+// A proposal is a guideline change set in Dev. Approving or rejecting one is a
+// person's action in Dev, and nobody decides their own, so there is no command
+// for it here.
+//
+// The Markdown form is what `guideline show` prints and `propose --file` reads:
+//
+//   # Button (`button`)
+//   ## dos
+//   <!-- sourced; refs: … -->
+//   - Use one primary button per view.
+//   ## anatomy (drafted)
+//   - …
+//
+// One `## <list>` heading per statement list, `(drafted)` when the text still
+// awaits a real source, one bullet per item (a line break inside an item reads
+// back as a space). Lines that are HTML comments are ignored; the `#` title
+// names the entry, and `propose` refuses a file titled for another one. Only
+// the lists that differ from Dev's current guideline are sent.
+import { readFile } from "node:fs/promises";
+import { CliError, devRequest, encode, query } from "./core.js";
+
+// Dev's editable statement lists (the request schema's `edits[].list` enum).
+// A parked guideline has only the first four.
+export const BASE_LISTS = ["whenToUse", "whenNotToUse", "dos", "donts"];
+export const GUIDELINE_LISTS = [...BASE_LISTS, "anatomy", "states.states", "states.loading", "states.empty", "states.error", "copy", "composition", "data.notes"];
+export const CHANGE_SET_STATES = ["in_review", "approved", "pr_open", "merged", "closed", "rejected", "conflict"];
+
+const getList = (guideline, path) => path.split(".").reduce((node, key) => node?.[key], guideline);
+/** The lists this guideline has that Dev lets a change set edit. */
+export const editableLists = (guideline) =>
+  (guideline?.status === "active" ? GUIDELINE_LISTS : BASE_LISTS).filter((path) => getList(guideline, path) !== undefined);
+
+/** A guideline as the Markdown `propose --file` reads back. */
+export function guidelineMarkdown(entry) {
+  const lines = [`# ${entry.title} (\`${entry.key}\`)`, "", `<!-- guideline: ${entry.guideline.status}. Edit the items, then: nodii-dev design guideline propose ${entry.key} --file FILE -->`];
+  for (const path of editableLists(entry.guideline)) {
+    const list = getList(entry.guideline, path);
+    lines.push("", `## ${path}${list.provenance === "drafted" ? " (drafted)" : ""}`, `<!-- ${list.provenance}${list.refs.length ? `; refs: ${list.refs.join(", ")}` : ""} -->`, ...list.items.map((item) => `- ${item}`));
+  }
+  return lines.join("\n");
+}
+
+const problem = (line, message) => `line ${line}: ${message}`;
+/** Parse the Markdown form into Dev's `edits` and the entry key its title names. Throws one error listing every problem. */
+export function parseGuidelineMarkdown(text) {
+  const edits = [];
+  let entryKey = null;
+  const problems = [];
+  // undefined before the first heading; null under a heading that is not a list (its items are skipped).
+  let current;
+  let comment = false;
+  let last = null;
+  const lines = text.replace(/\r\n?/g, "\n").split("\n");
+  lines.forEach((raw, i) => {
+    const n = i + 1;
+    let line = raw;
+    if (comment) {
+      const end = line.indexOf("-->");
+      if (end === -1) return;
+      comment = false;
+      line = line.slice(end + 3);
+    }
+    // A comment is a line of its own; `<!--` inside an item is the item's text.
+    while (/^\s*<!--/.test(line)) {
+      const end = line.indexOf("-->");
+      if (end === -1) { comment = true; return; }
+      line = line.slice(end + 3);
+    }
+    if (!line.trim()) { last = null; return; }
+    const title = /^#\s+(.*)$/.exec(line);
+    if (title && current === undefined && entryKey === null) {
+      entryKey = /\(`([^`]+)`\)\s*$/.exec(title[1])?.[1] ?? "";
+      last = null;
+      return;
+    }
+    const heading = /^##\s+(\S+)(\s+\(drafted\))?\s*$/.exec(line);
+    if (heading) {
+      last = null;
+      const [, list, drafted] = heading;
+      if (!GUIDELINE_LISTS.includes(list)) {
+        problems.push(problem(n, `\`${list}\` is not a guideline list (${GUIDELINE_LISTS.join(", ")})`));
+        current = null;
+        return;
+      }
+      if (edits.some((e) => e.list === list)) problems.push(problem(n, `${list} appears twice`));
+      current = { list, items: [], drafted: Boolean(drafted), line: n };
+      edits.push(current);
+      return;
+    }
+    if (/^#/.test(line)) { problems.push(problem(n, `expected \`## <list>\`, got: ${line.trim()}`)); return; }
+    const item = /^\s{0,3}(?:[-*+]|\d+\.)\s+(.*)$/.exec(line);
+    if (item) {
+      if (current === undefined) problems.push(problem(n, "a list item before any `## <list>` heading"));
+      if (!current) return;
+      last = { text: item[1].trim() };
+      current.items.push(last);
+      return;
+    }
+    // An indented line continues the item above it.
+    if (/^\s/.test(line) && last) { last.text = `${last.text} ${line.trim()}`; return; }
+    if (current !== null) problems.push(problem(n, `expected a \`- \` list item, got: ${line.trim()}`));
+  });
+  if (comment) problems.push("an HTML comment is not closed");
+  for (const edit of edits) {
+    edit.items = edit.items.map((x) => x.text);
+    // The checks Dev (and the design-system validator) apply to a list's items.
+    if (!edit.items.length) problems.push(problem(edit.line, `${edit.list} needs at least one item`));
+    if (edit.items.some((x) => x === "")) problems.push(problem(edit.line, `${edit.list} has an empty item`));
+    const seen = new Set();
+    for (const x of edit.items) if (seen.has(x)) problems.push(problem(edit.line, `${edit.list} repeats: ${x}`)); else seen.add(x);
+  }
+  if (!edits.length && !problems.length) problems.push("no `## <list>` sections");
+  if (problems.length) throw new CliError("GUIDELINE_FILE_INVALID", `The guideline file has problems:\n  ${problems.join("\n  ")}`, 2);
+  return { entryKey: entryKey || null, edits: edits.map(({ list, items, drafted }) => ({ list, items, drafted })) };
+}
+
+/** The edits that change Dev's current guideline; refuses lists it cannot edit. */
+export function changedEdits(entry, edits) {
+  if (!entry.guideline) throw new CliError("GUIDELINE_MISSING", `${entry.key} has no synced guideline to edit`, 1);
+  const allowed = editableLists(entry.guideline);
+  const refused = edits.filter((e) => !allowed.includes(e.list)).map((e) => e.list);
+  if (refused.length)
+    throw new CliError("GUIDELINE_LIST_NOT_EDITABLE", `${refused.join(", ")}: not a list of ${entry.key}'s ${entry.guideline.status} guideline (it has ${allowed.join(", ")})`, 2);
+  return edits.filter((e) => {
+    const now = getList(entry.guideline, e.list);
+    return JSON.stringify(now.items) !== JSON.stringify(e.items) || (now.provenance === "drafted") !== e.drafted;
+  });
+}
+
+const person = (p) => (p ? (p.displayName?.value ?? p.displayName?.hint ?? p.id) : "—");
+const changeSetLine = (x) => `${x.id}\t${x.state}\t${x.entryKey}\t${x.edits.map((e) => e.list).join(",")}\t${x.summary ?? ""}`;
+function changeSetText(x) {
+  const out = [
+    `${x.id} ${x.state} — ${x.entryTitle} (${x.entryKey})`,
+    ...(x.summary ? [x.summary] : []),
+    `proposed by ${person(x.createdBy)} at ${x.createdAt}`,
+    ...(x.decidedAt ? [`decided by ${person(x.decidedBy)} at ${x.decidedAt}${x.decisionComment ? `: ${x.decisionComment}` : ""}`] : []),
+    ...(x.pr ? [`PR #${x.pr.number} ${x.pr.url}${x.mergedAt ? ` (merged ${x.mergedAt})` : ""}`] : []),
+    ...(x.error ? [`error: ${x.error}`] : []),
+  ];
+  for (const edit of x.edits) {
+    const before = x.before?.[edit.list];
+    out.push("", `## ${edit.list}${edit.drafted ? " (drafted)" : ""}`);
+    // Removed items first, then the new list: `-` removed, `+` added, blank kept.
+    for (const item of before?.items ?? []) if (!edit.items.includes(item)) out.push(`- ${item}`);
+    for (const item of edit.items) out.push(`${before?.items.includes(item) ? " " : "+"} ${item}`);
+  }
+  return out.join("\n");
+}
+
+const usage = (text) => new CliError("USAGE", text, 2);
+const flagValue = (flags, name, example) => {
+  if (flags[name] === true) throw usage(`--${name} needs a value, e.g. --${name} ${example}`);
+  if (Array.isArray(flags[name])) throw usage(`--${name} is given more than once`);
+  return flags[name];
+};
+
+export async function guidelineCommand(action, args, flags, { request = devRequest, read = (path) => readFile(path, "utf8") } = {}) {
+  if (action === "list") {
+    const params = { kind: flagValue(flags, "kind", "component"), group: flagValue(flags, "group", "inputs"), q: flagValue(flags, "q", "button"), guidelineDrafted: flags.drafted ? "true" : undefined, limit: flagValue(flags, "limit", "100") ?? 100 };
+    let cursor = flagValue(flags, "cursor", "CURSOR");
+    const data = [];
+    let nextCursor;
+    do {
+      const page = await request("GET", `/api/v1/design/entries${query({ ...params, cursor })}`);
+      data.push(...page.data);
+      nextCursor = page.nextCursor ?? null;
+      cursor = nextCursor;
+    } while (flags.all && cursor);
+    return {
+      payload: { data, nextCursor },
+      // Dev lists root entries with their parts nested; a part is shown indented under its root.
+      human: (p) => [p.data.flatMap((x) => [x, ...(x.parts ?? []).map((part) => ({ ...part, key: `  ${part.key}` }))]).map((x) => `${x.key}\t${x.kind}\t${x.status}\tdrafted=${x.guidelineDraftedCount}\t${x.title}`).join("\n") || "No design entries.", ...(p.nextCursor ? [`more: --cursor ${p.nextCursor} (or --all)`] : [])].join("\n"),
+    };
+  }
+  const key = args[0];
+  if (action === "show") {
+    if (!key || args.length > 1) throw usage("design guideline show ENTRY");
+    const payload = await request("GET", `/api/v1/design/entries/${encode(key)}`);
+    if (!payload.data.guideline && !flags.json) throw new CliError("GUIDELINE_MISSING", `${key} has no synced guideline`, 1);
+    return { payload, human: (p) => guidelineMarkdown(p.data) };
+  }
+  if (action === "propose") {
+    if (!key || args.length > 1) throw usage("design guideline propose ENTRY --file FILE.md [--summary TEXT] [--dry-run]");
+    const file = flagValue(flags, "file", "ENTRY.md");
+    if (!file) throw usage("Missing --file FILE.md (start from `nodii-dev design guideline show ENTRY > FILE.md`)");
+    const summary = flagValue(flags, "summary", "'Clarify when to use'")?.trim();
+    if (summary !== undefined && (summary === "" || summary.length > 500)) throw usage("--summary must be 1 to 500 characters");
+    let text;
+    try { text = await read(file); } catch (error) { throw new CliError("NOT_FOUND", `Cannot read ${file}: ${error.message}`, 2); }
+    const { entryKey, edits } = parseGuidelineMarkdown(text);
+    if (entryKey && entryKey !== key) throw usage(`${file} is titled for ${entryKey}, not ${key}`);
+    const entry = (await request("GET", `/api/v1/design/entries/${encode(key)}`)).data;
+    const changed = changedEdits(entry, edits);
+    if (!changed.length) throw new CliError("NO_CHANGES", `${file} matches ${key}'s current guideline; nothing to propose`, 1);
+    const body = { ...(summary ? { summary } : {}), edits: changed };
+    if (flags["dry-run"])
+      return { payload: { dryRun: true, entryKey: key, body }, human: () => `Would propose ${changed.map((e) => e.list).join(", ")} for ${key} (dry run; nothing sent).` };
+    const payload = await request("POST", `/api/v1/design/entries/${encode(key)}/guideline-change-sets`, body);
+    return { payload, human: (p) => `Proposed ${p.data.id} (${p.data.state}) for ${p.data.entryKey}: ${p.data.edits.map((e) => e.list).join(", ")}. A person approves or rejects it in Dev.` };
+  }
+  throw usage("design guideline list|show ENTRY|propose ENTRY --file FILE.md");
+}
+
+export async function changeSetCommand(action, args, flags, { request = devRequest } = {}) {
+  if (action === "list") {
+    const states = flags.state === undefined ? undefined : [flags.state].flat();
+    for (const state of states ?? [])
+      if (!CHANGE_SET_STATES.includes(state)) throw usage(`--state is one of ${CHANGE_SET_STATES.join(", ")}`);
+    const payload = await request("GET", `/api/v1/design/guideline-change-sets${query({ entryKey: flagValue(flags, "entry", "button"), state: states, limit: flagValue(flags, "limit", "100") })}`);
+    return { payload, human: (p) => [p.data.map(changeSetLine).join("\n") || "No guideline change sets.", ...(p.total > p.data.length ? [`showing ${p.data.length} of ${p.total}; raise --limit (up to 200) or narrow with --entry/--state`] : [])].join("\n") };
+  }
+  if (action === "show") {
+    if (!args[0] || args.length > 1) throw usage("design changeset show ID");
+    const payload = await request("GET", `/api/v1/design/guideline-change-sets/${encode(args[0])}`);
+    return { payload, human: (p) => changeSetText(p.data) };
+  }
+  if (["approve", "reject"].includes(action))
+    throw usage(`Approving or rejecting a guideline change set is a person's action in Dev; nodii-dev has no ${action}.`);
+  throw usage("design changeset list [--entry KEY] [--state STATE] | show ID");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodii/dev",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Agent CLI for Nodii Dev, reached through the platform edge",
   "type": "module",
   "bin": {