justskill-design 0.0.1 → 3.2.0

package/lib/node/verbs/set.mjs

@@ -0,0 +1,150 @@
+/**
+ * `node design.mjs set <file> <data-id> [--style 'a:b;c:d'] [--text T] [--attr name=value]`
+ *
+ * One op per declaration, per attribute and per text change. Each op is one
+ * undo step and one byte range, which is what makes an edit reviewable and
+ * cheap to reverse.
+ */
+
+import { EXIT_OK, SHARED_FLAGS, out, parseArgs, readDesignFile } from "../cli.mjs";
+import { applyAndWrite, refusedReceipt, reportRefusal, reportWrite, styleOps, canonicalStyleOp } from "../write-verbs.mjs";
+import { normalizeValue, CSS_ALIASES, CSS_SET } from "../../table.mjs";
+import { shorthandHint } from "../../validate.mjs";
+
+export const USAGE = `Usage: node design.mjs set <file> <data-id> [options]
+
+  --style 'a:b;c:d'    set style declarations, one op each
+  --text <value>       replace the element's text
+  --attr name=value    set an attribute (repeatable)
+  --unset name         remove an attribute or a style declaration (repeatable)
+  --force              write even when the edit introduces a new error
+  --dry-run            report what would change, write nothing
+  --json               print the receipt as JSON
+  --quiet              print nothing
+
+Exit codes: 0 changed, 1 refused, 2 unreadable or bad arguments.
+
+The data-id is the address. To change an id, use \`rename\`, which also updates
+every reference to it.`;
+
+export default async function run(argv) {
+  const { values, positionals } = parseArgs(argv, {
+    flags: {
+      ...SHARED_FLAGS,
+      style: { type: "string" },
+      text: { type: "string" },
+      attr: { type: "list" },
+      unset: { type: "list" },
+    },
+    positionals: { min: 2, max: 2 },
+    usage: USAGE,
+  });
+
+  if (values.help) {
+    out(USAGE);
+    return EXIT_OK;
+  }
+
+  const [file, target] = positionals;
+  const loaded = await readDesignFile(file);
+
+  const ops = [];
+  try {
+    if (values.style !== undefined) ops.push(...styleOps(target, values.style, normalizeValue));
+  } catch (error) {
+    // A property the format does not use is a refusal, not a crash: report it
+    // the same way the funnel reports one, so the shape is identical. The hint
+    // is generated from the value, so `margin-top:16px` is told to write
+    // `margin: 16px 0 0 0` and not a fixed example.
+    if (error.property && error.hint === undefined) {
+      error.hint = shorthandHint(error.property, error.value) ?? null;
+    }
+    const receipt = {
+      ok: false, verb: "set", applied: [], added: [], normalized: [], dropped: [],
+      diagnostics: error.hint ? [{ severity: "error", code: error.code, message: error.message, hint: error.hint }] : [],
+      revision: null, changed: false,
+      refused: { code: error.code ?? "cli/bad-style", message: error.message, hint: error.hint ?? null },
+    };
+    if (values.json) out(JSON.stringify(receipt));
+    else {
+      out([`REFUSED  ${error.message}`, error.hint ? `  ${error.hint}` : null, `${file} was not changed.`].filter(Boolean).join("\n"));
+    }
+    return 1;
+  }
+  if (values.text !== undefined) ops.push({ op: "set", target, prop: "text", value: values.text });
+
+  for (const pair of asList(values.attr)) {
+    const equals = String(pair).indexOf("=");
+    if (equals === -1) {
+      out(`REFUSED  --attr wants name=value, and got ${JSON.stringify(pair)}`);
+      return 1;
+    }
+    const name = String(pair).slice(0, equals).trim();
+    // An id is an address, not a property: `set` edits what a node is, and this
+    // attribute would change what it is called. It refuses and names the verb that
+    // owns an address. Case-insensitive because `applySet` lowercases before it
+    // compares.
+    if (name.toLowerCase() === "data-id") {
+      const receipt = refusedReceipt("set", "data-id is the address, so `set` cannot change it.", {
+        code: "cli/data-id-is-the-address",
+        diagnostics: [],
+        hint: `Use \`node design.mjs rename ${file} <old-id> <new-id>\`.`,
+      });
+      reportRefusal(receipt, values, file);
+      return 1;
+    }
+    ops.push({ op: "set", target, prop: name, value: String(pair).slice(equals + 1) });
+  }
+
+  for (const name of asList(values.unset)) {
+    const text = String(name);
+    if (text.toLowerCase() === "data-id") {
+      const receipt = refusedReceipt("set", "data-id is the address, so `set --unset` cannot remove it.", {
+        code: "cli/data-id-is-the-address",
+        diagnostics: [],
+        hint: `Use \`node design.mjs rename ${file} <old-id> <new-id>\` to give it a different one.`,
+      });
+      reportRefusal(receipt, values, file);
+      return 1;
+    }
+    if (isCssProperty(text)) {
+      // The same alias rule applies to an unset, or removing `background` would
+      // leave the `background-color` it was meant to remove.
+      const property = CSS_ALIASES[text.toLowerCase()] ?? text.toLowerCase();
+      ops.push({ op: "unset", target, prop: `style:${property}` });
+    } else {
+      ops.push({ op: "unset", target, prop: text });
+    }
+  }
+
+  if (ops.length === 0) {
+    out(`REFUSED  Nothing to set. Use --style, --text, --attr or --unset.`);
+    return 1;
+  }
+
+  const receipt = await applyAndWrite(loaded, ops, { values, verb: "set" });
+  if (receipt.refused) return 1;
+  reportWrite(receipt, values, file);
+  return EXIT_OK;
+}
+
+function asList(value) {
+  if (value === undefined || value === null) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+/**
+ * A bare `--unset background-color` is a style declaration, and a bare
+ * `--unset data-name` is an attribute. Style properties have no `data-` prefix,
+ * which is the whole difference.
+ *
+ * The table decides, not the spelling. "Has a hyphen" reads well until
+ * `--unset top`, `--unset width` or `--unset display`: those are single words,
+ * so the old rule called them attributes and refused the edit with `has no
+ * "top" attribute` — for a declaration the file was carrying.
+ */
+function isCssProperty(name) {
+  const text = String(name).toLowerCase();
+  if (text.startsWith("data-")) return false;
+  return CSS_SET.has(text) || Object.hasOwn(CSS_ALIASES, text);
+}

package/lib/node/verbs/show.mjs

@@ -0,0 +1,122 @@
+/**
+ * `node design.mjs show <file> <data-id> [--json]` — one element, in full.
+ *
+ * Prints the element's open tag exactly as the file has it, its attribute list,
+ * its text, and how many element children it has.
+ */
+
+import { CliError, EXIT_INVALID, EXIT_OK, SHARED_FLAGS, out, parseArgs, readDesignFile } from "../cli.mjs";
+import { attrValue, collectElements } from "../../diagnostics.mjs";
+import { byteOffsetToLineCol } from "../../spans.mjs";
+
+export const USAGE = `Usage: node design.mjs show <file> <data-id> [options]
+
+  --json     print one line of JSON instead of the human report
+  --quiet    print nothing (with --json it still prints the payload)
+  --help     print this usage
+
+Exit codes: 0 shown, 1 no such data-id, 2 unreadable.`;
+
+function isElement(node) {
+  if (!node || typeof node !== "object") return false;
+  if (node.kind === "element") return true;
+  return typeof node.tag === "string" && Array.isArray(node.attrs);
+}
+
+/** The element's own text, without the indentation that surrounds its children. */
+function textOf(node) {
+  const children = Array.isArray(node.children) ? node.children : [];
+  const text = children
+    .filter((child) => child && child.kind === "text")
+    .map((child) => (typeof child.value === "string" ? child.value : typeof child.raw === "string" ? child.raw : ""))
+    .join("");
+  return text.trim();
+}
+
+/**
+ * The data `show` prints, for one element.
+ *
+ * @param {object} node
+ * @param {string} source
+ * @returns {object}
+ */
+export function describeNode(node, source) {
+  const start = Number.isFinite(node.start) ? node.start : 0;
+  const end = Number.isFinite(node.end) ? node.end : start;
+  const openStart = Number.isFinite(node.openStart) ? node.openStart : start;
+  const openEnd = Number.isFinite(node.openEnd) ? node.openEnd : end;
+  const text = String(source === undefined || source === null ? "" : source);
+  const at = byteOffsetToLineCol(text, start);
+
+  const attrs = (Array.isArray(node.attrs) ? node.attrs : []).map((attr) => {
+    const attrStart = Number.isFinite(attr.attrStart) ? attr.attrStart : Number.isFinite(attr.start) ? attr.start : 0;
+    const attrEnd = Number.isFinite(attr.end) ? attr.end : attrStart;
+    return {
+      name: typeof attr.name === "string" ? attr.name : String(attr.rawName || ""),
+      rawName: typeof attr.rawName === "string" ? attr.rawName : String(attr.name || ""),
+      value: attr.value === undefined || attr.value === null ? "" : String(attr.value),
+      quote: typeof attr.quote === "string" ? attr.quote : '"',
+      raw: text.slice(attrStart, attrEnd),
+    };
+  });
+
+  const children = (Array.isArray(node.children) ? node.children : []).filter(isElement);
+
+  return {
+    tag: typeof node.tag === "string" ? node.tag : "",
+    rawTag: typeof node.rawTag === "string" ? node.rawTag : typeof node.tag === "string" ? node.tag : "",
+    dataId: attrValue(node, "data-id"),
+    dataType: attrValue(node, "data-type"),
+    name: attrValue(node, "data-name"),
+    openTag: text.slice(openStart, openEnd),
+    attrs,
+    text: textOf(node),
+    childCount: children.length,
+    start,
+    end,
+    line: at.line,
+    column: at.column,
+  };
+}
+
+function humanReport(file, dataId, described) {
+  const lines = [];
+  lines.push(`${dataId}  <${described.tag}>${described.dataType ? `  ${described.dataType}` : ""}`);
+  lines.push(`open tag    ${described.openTag}`);
+  lines.push(`attributes  ${described.attrs.length}`);
+  for (const attr of described.attrs) {
+    lines.push(`  ${attr.name} = ${JSON.stringify(attr.value)}`);
+  }
+  lines.push(`text        ${described.text === "" ? "(none)" : described.text}`);
+  lines.push(`children    ${described.childCount}`);
+  lines.push(`at          ${file} line ${described.line}, column ${described.column}`);
+  return `${lines.join("\n")}\n`;
+}
+
+export default async function run(argv) {
+  const { values, positionals } = parseArgs(argv, {
+    flags: SHARED_FLAGS,
+    positionals: { min: 2, max: 2 },
+    usage: USAGE,
+  });
+
+  if (values.help) {
+    out(USAGE);
+    return EXIT_OK;
+  }
+
+  const [file, dataId] = positionals;
+  const loaded = await readDesignFile(file);
+  const index = collectElements(loaded.doc);
+  const node = index.byId.get(String(dataId));
+  if (!node) throw new CliError(`No element with data-id ${JSON.stringify(String(dataId))} in ${file}`, EXIT_INVALID);
+
+  const described = describeNode(node, typeof loaded.doc.source === "string" ? loaded.doc.source : loaded.text);
+
+  if (values.json) {
+    out(JSON.stringify({ file, id: String(dataId), ...described }));
+  } else {
+    out(humanReport(file, String(dataId), described), { quiet: values.quiet, newline: false });
+  }
+  return EXIT_OK;
+}

package/lib/node/verbs/tokens.mjs

@@ -0,0 +1,167 @@
+/**
+ * `node design.mjs tokens <file> ls | set <组.名> <值> | rm <组.名>`
+ *
+ * A design token is not an element, so no other verb can reach it. Without this one,
+ * "make the brand color purple" meant rewriting the whole file, which is the one thing
+ * `SKILL.md` tells a model never to do ("Write it, do not rewrite it"). v1 could
+ * address a token as `/tokens/color/bg`; this is that ability, on a file whose tokens
+ * are CSS.
+ *
+ * Two spellings of a name reach the same token, and `lib/tokens.mjs` is where they
+ * become one: `color.accent` (what `plan.md` §5.1 documents, and what a shell can
+ * accept without reading `--` as a flag) and `--color-accent` (what the file says, and
+ * what `tokens ls` prints).
+ *
+ * `set` and `rm` go through the same funnel as every other write: re-read, validate,
+ * apply, validate, refuse on a NEW error, write atomically, report. So a `set` that
+ * would introduce a cycle is refused by name rather than written and discovered later.
+ */
+
+import { CliError, EXIT_INVALID, EXIT_OK, SHARED_FLAGS, out, parseArgs, readDesignFile } from "../cli.mjs";
+import { applyAndWrite, refusedReceipt, reportRefusal, reportWrite } from "../write-verbs.mjs";
+import { groupOfToken, normalizeTokenValue, resolveTokenName, tokenSites } from "../../tokens.mjs";
+import { suggest } from "../../levenshtein.mjs";
+
+export const USAGE = `Usage: node design.mjs tokens <file> <subcommand> [options]
+
+  ls                        list the token block, one token per line
+  set <组.名> <值>           set a token, adding it when it is not there
+  rm <组.名>                 remove a token
+
+A name is written either way, and both mean the same token:
+
+  color.accent              the seven groups are color font space radius size shadow border
+  --color-accent            needs a \`--\` first, because a leading dash reads as a flag
+
+    node design.mjs tokens t.html set -- --color-accent '#7c3aed'
+
+Everything after \`--\` is a name or a value, never a flag.
+
+A numeric group carries a unit. \`set space.md 16\` writes 16px, and a value that is not
+a length is refused. A color is written as the hex the rest of the file uses. font,
+shadow and border values are written as given.
+
+  --dry-run    report what would change, write nothing
+  --json       print the receipt as JSON
+  --quiet      print nothing
+  --help       print this usage
+
+Exit codes: 0 changed, 1 refused, 2 unreadable or bad arguments.`;
+
+/** The file's tokens, plus every name that is declared more than once. */
+function sitesOf(loaded) {
+  const { sites, duplicates } = tokenSites(loaded.doc);
+  return { sites, duplicates };
+}
+
+function refuse(loaded, values, message, extra) {
+  const receipt = refusedReceipt("tokens", message, { diagnostics: [], ...extra });
+  reportRefusal(receipt, values, loaded.file);
+  return EXIT_INVALID;
+}
+
+async function list(loaded, values) {
+  const { sites, duplicates } = sitesOf(loaded);
+  const rows = [...sites.values()].map((site) => ({ name: site.name, value: site.value, offset: site.offset }));
+  if (values.json) {
+    out(JSON.stringify({
+      file: loaded.file,
+      tokens: rows,
+      duplicates: duplicates.map((entry) => entry.name),
+    }));
+    return EXIT_OK;
+  }
+  if (rows.length === 0) {
+    out(`${loaded.file}: no tokens`, { quiet: false });
+    return EXIT_OK;
+  }
+  out(`${loaded.file}: ${rows.length} token${rows.length === 1 ? "" : "s"}`, { quiet: false });
+  for (const row of rows) out(`  ${row.name}  ${row.value}`, { quiet: false });
+  for (const entry of duplicates) {
+    out(`  ${entry.name} is declared ${entry.offsets.length} times`, { quiet: false });
+  }
+  return EXIT_OK;
+}
+
+export default async function run(argv) {
+  const { values, positionals } = parseArgs(argv, {
+    flags: { ...SHARED_FLAGS },
+    positionals: { min: 2, max: 4 },
+    usage: USAGE,
+  });
+
+  if (values.help) {
+    out(USAGE);
+    return EXIT_OK;
+  }
+
+  const [file, sub, spec, raw] = positionals;
+  if (!["ls", "set", "rm"].includes(sub)) {
+    throw new CliError(`Unknown tokens subcommand: ${sub}\n\n${USAGE}`);
+  }
+  if (sub === "set" && (spec === undefined || raw === undefined)) {
+    throw new CliError(`tokens set needs a name and a value\n\n${USAGE}`);
+  }
+  if (sub === "rm" && spec === undefined) {
+    throw new CliError(`tokens rm needs a name\n\n${USAGE}`);
+  }
+
+  const loaded = await readDesignFile(file);
+  if (sub === "ls") return list(loaded, values);
+
+  let name;
+  try {
+    name = resolveTokenName(spec);
+  } catch (error) {
+    // The same code the validator reports for the same problem, so a model that reads
+    // one message and writes the other is not being told two different things.
+    return refuse(loaded, values, error.message, { code: error.code ?? "style/token-name", hint: error.hint ?? null });
+  }
+
+  const { sites, duplicates } = sitesOf(loaded);
+  const clash = duplicates.find((entry) => entry.name === name);
+  if (clash !== undefined) {
+    // `findDeclaration` returns the first declaration and the file has two. A `set`
+    // would write to one of them while the other kept winning, and an `rm` would leave
+    // the token in place while reporting that it removed it. Both are silent wrong
+    // answers, so neither is allowed to happen.
+    return refuse(loaded, values, `${name} is declared ${clash.offsets.length} times, so which one to change has no answer.`, {
+      code: "cli/duplicate-token",
+      hint: "Keep one declaration per token, then run this again.",
+    });
+  }
+
+  if (sub === "rm") {
+    if (!sites.has(name)) {
+      const known = [...sites.keys()];
+      const closest = suggest(name, known);
+      return refuse(loaded, values, `There is no token ${name}.`, {
+        code: "cli/no-such-token",
+        hint: closest ? `Did you mean ${closest}?` : (known.length === 0 ? "This design has no tokens." : `Declared: ${known.join(", ")}.`),
+      });
+    }
+    const receipt = await applyAndWrite(loaded, [{ op: "unset-token", name }], { values, verb: "tokens" });
+    if (receipt.refused) return EXIT_INVALID;
+    reportWrite(receipt, values, file);
+    return EXIT_OK;
+  }
+
+  let normalized;
+  try {
+    normalized = normalizeTokenValue(groupOfToken(name), raw);
+  } catch (error) {
+    return refuse(loaded, values, error.message, { code: error.code ?? "style/bad-value", hint: error.hint ?? null });
+  }
+
+  const receipt = await applyAndWrite(loaded, [{ op: "set-token", name, value: normalized.value }], { values, verb: "tokens" });
+  if (receipt.refused) return EXIT_INVALID;
+  reportWrite(receipt, values, file);
+  if (normalized.changed && receipt.changed && !values.json && !values.quiet) {
+    // Zero silent drops covers a value this tool rewrote as much as one it discarded:
+    // `set space.md 16` writes 16px, and the line says so. Same shape as `add`. Not
+    // printed when the file did not move — a line about a rewrite that did not happen
+    // is the opposite of a report a reader can trust.
+    out(`normalized: ${String(raw)} → ${normalized.value}`);
+  }
+  return EXIT_OK;
+}

package/lib/node/verbs/validate.mjs

@@ -0,0 +1,130 @@
+/**
+ * `node design.mjs validate <file> [--json] [--strict]` — the four-layer report.
+ *
+ * The validator is `lib/validate.mjs`; this verb only reads the file, runs it,
+ * and prints. Exit codes: 0 no errors, 1 errors (or warnings under --strict),
+ * 2 the file is unreadable or the arguments are wrong.
+ */
+
+import { EXIT_INVALID, EXIT_OK, EXIT_UNREADABLE, SHARED_FLAGS, loadExport, out, parseArgs, readDesignFile } from "../cli.mjs";
+import { dedupeDiagnostics, groupDiagnostics, sortDiagnostics, summarize } from "../../diagnostics.mjs";
+import { byteOffsetToLineCol } from "../../spans.mjs";
+
+export const USAGE = `Usage: node design.mjs validate <file> [options]
+
+  --json     print one line of JSON instead of the human report
+  --strict   exit 1 when there are warnings as well as errors
+  --quiet    print nothing when the file is valid
+  --help     print this usage
+
+Exit codes: 0 valid, 1 invalid, 2 unreadable.`;
+
+function codeOf(diagnostic) {
+  return typeof diagnostic.code === "string" && diagnostic.code !== "" ? diagnostic.code : "(no code)";
+}
+
+function whereOf(diagnostic, source) {
+  let line = Number.isFinite(diagnostic.line) ? diagnostic.line : null;
+  let column = Number.isFinite(diagnostic.column) ? diagnostic.column : null;
+  if ((line === null || column === null) && Number.isFinite(diagnostic.offset)) {
+    const at = byteOffsetToLineCol(source, diagnostic.offset);
+    if (line === null) line = at.line;
+    if (column === null) column = at.column;
+  }
+  if (line === null) return "";
+  return `line ${line}, column ${column === null ? 1 : column}`;
+}
+
+/**
+ * The grouped human report: one header per code, then that group's findings.
+ *
+ * @param {string} file
+ * @param {object[]} diagnostics
+ * @param {string} source
+ * @returns {string}
+ */
+export function humanReport(file, diagnostics, source) {
+  const sorted = sortDiagnostics(diagnostics);
+  const lines = [];
+
+  for (const group of groupDiagnostics(sorted)) {
+    const label = group.severity === "error" ? "ERROR  " : "WARNING";
+    lines.push(`${label}  ${group.code}  x${group.count}`);
+    for (const diagnostic of sorted) {
+      if (codeOf(diagnostic) !== group.code) continue;
+      const target = typeof diagnostic.target === "string" && diagnostic.target !== "" ? diagnostic.target : "";
+      const path = typeof diagnostic.path === "string" ? diagnostic.path : "";
+      const where = whereOf(diagnostic, source);
+      const position = [target, path].filter(Boolean).join("  ");
+      lines.push(`  ${position}${where ? `  (${where})` : ""}`.trimEnd());
+      if (diagnostic.message) lines.push(`    ${diagnostic.message}`);
+      if (diagnostic.hint) lines.push(`    hint  ${diagnostic.hint}`);
+      if (diagnostic.fix) lines.push(`    fix   ${diagnostic.fix}`);
+    }
+  }
+
+  const { errors, warnings } = summarize(sorted);
+  lines.push(`${file}: ${errors} errors, ${warnings} warnings${errors === 0 ? " — valid" : " — invalid"}`);
+  return `${lines.join("\n")}\n`;
+}
+
+export default async function run(argv) {
+  const { values, positionals } = parseArgs(argv, {
+    flags: { ...SHARED_FLAGS, strict: { type: "boolean" } },
+    positionals: { min: 1, max: 1 },
+    usage: USAGE,
+  });
+
+  if (values.help) {
+    out(USAGE);
+    return EXIT_OK;
+  }
+
+  const file = positionals[0];
+
+  let loaded;
+  try {
+    loaded = await readDesignFile(file);
+  } catch (error) {
+    if (values.json && error && (error.name === "FsError" || error.name === "CliError")) {
+      out(JSON.stringify({ file, ok: false, reason: error.code || "cli/error", message: error.message }));
+      return EXIT_UNREADABLE;
+    }
+    throw error;
+  }
+
+  const validateDesign = await loadExport("validate.mjs", ["validateDesign", "validate", "default"], "validateDesign");
+  const parserDiagnostics = Array.isArray(loaded.doc.diagnostics) ? loaded.doc.diagnostics : [];
+  // `strict` is passed through so the report and the exit code agree: under
+  // --strict the validator itself promotes a warning to an error.
+  const produced = validateDesign(loaded.doc, {
+    file,
+    text: loaded.text,
+    format: loaded.format,
+    strict: values.strict === true,
+  });
+  const diagnostics = sortDiagnostics(
+    dedupeDiagnostics([...parserDiagnostics, ...(Array.isArray(produced) ? produced : [])]),
+  );
+
+  const counts = summarize(diagnostics);
+  const ok = counts.errors === 0 && (!values.strict || counts.warnings === 0);
+
+  if (values.json) {
+    out(
+      JSON.stringify({
+        file,
+        format: loaded.format,
+        revision: loaded.revision,
+        ok,
+        counts: { errors: counts.errors, warnings: counts.warnings },
+        groups: groupDiagnostics(diagnostics),
+        diagnostics,
+      }),
+    );
+  } else if (!values.quiet || !ok) {
+    out(humanReport(file, diagnostics, loaded.text), { newline: false });
+  }
+
+  return ok ? EXIT_OK : EXIT_INVALID;
+}