@domandigital/craft 0.5.0 → 0.7.0

package/dist/chunk-IQTZWNEK.js

@@ -0,0 +1,112 @@
+import {
+  snapshotUrl
+} from "./chunk-OA7SGPN4.js";
+import {
+  describeTypicality,
+  loadNull,
+  typicality
+} from "./chunk-GV3QOTQU.js";
+import {
+  SOURCE_FILE,
+  finish,
+  loadExceptions,
+  parseFlags,
+  readPaths
+} from "./chunk-YYC4EGER.js";
+import {
+  fingerprint
+} from "./chunk-Q54JSNC5.js";
+import {
+  SNAPSHOT_VERSION,
+  auditSnapshot,
+  scanSource
+} from "./chunk-3AP4PJMX.js";
+
+// src/audit/cli.ts
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { resolve } from "path";
+var fmt = (o) => o ? `oklch(${o.l.toFixed(3)} ${o.c.toFixed(3)} ${o.h.toFixed(1)})` : "none";
+function describeFingerprint(fp) {
+  return [
+    "Fingerprint",
+    `  accent     ${fmt(fp.accent)}`,
+    `  ground     ${fmt(fp.ground)}`,
+    `  display    ${fp.display.family} (${fp.display.class})`,
+    `  body       ${fp.body.family} (${fp.body.class})`,
+    `  roundness  ${fp.roundness === null ? "no buttons" : fp.roundness.toFixed(2)}`,
+    `  motion     ${Math.round(fp.motion * 100)}% of sections below the fold reveal on scroll`,
+    `  effects    ${fp.effects.join(", ") || "none"}`,
+    `  layout     ${fp.layout.join(" > ") || "none"}`
+  ].join("\n");
+}
+function merge(a, b) {
+  const byTell = { ...a.summary.byTell };
+  for (const [k, v] of Object.entries(b.summary.byTell)) byTell[k] = (byTell[k] ?? 0) + v;
+  return {
+    catalogueVersion: a.catalogueVersion,
+    findings: [...a.findings, ...b.findings],
+    rejectedExceptions: a.rejectedExceptions,
+    excepted: [...a.excepted, ...b.excepted],
+    suppressed: [...a.suppressed, ...b.suppressed],
+    summary: {
+      files: a.summary.files + b.summary.files,
+      findings: a.summary.findings + b.summary.findings,
+      byGeneration: { 1: a.summary.byGeneration[1] + b.summary.byGeneration[1], 2: a.summary.byGeneration[2] + b.summary.byGeneration[2], 3: a.summary.byGeneration[3] + b.summary.byGeneration[3] },
+      byTell,
+      blocking: a.summary.blocking + b.summary.blocking
+    }
+  };
+}
+function readSnapshot(path) {
+  const data = JSON.parse(readFileSync(path, "utf8"));
+  if (data.version !== SNAPSHOT_VERSION) throw new Error(`${path} is snapshot version ${String(data.version)}; this craft reads ${SNAPSHOT_VERSION}`);
+  return data;
+}
+async function runAudit(command, args, io) {
+  try {
+    const flags = parseFlags(args);
+    if (typeof flags === "string") throw new Error(flags);
+    const target = flags.positional[0];
+    if (!target) throw new Error(`usage: craft ${command} <url${command === "audit" ? " | snapshot.json" : ""}>`);
+    const viewport = flags.width || flags.height ? { width: Number(flags.width ?? 1440), height: Number(flags.height ?? 900) } : void 0;
+    const local = resolve(io.cwd, target);
+    const snapshot = command === "audit" && /\.json$/i.test(target) && existsSync(local) ? readSnapshot(local) : await snapshotUrl(target, { viewport });
+    if (flags.out) writeFileSync(resolve(io.cwd, flags.out), `${JSON.stringify(snapshot, null, 2)}
+`);
+    if (command === "snapshot") {
+      if (!flags.out) io.out(JSON.stringify(snapshot, null, 2));
+      else io.out(`craft snapshot: ${snapshot.url} saved to ${flags.out}`);
+      return 0;
+    }
+    const exceptions = loadExceptions(flags, flags.repo ? resolve(io.cwd, flags.repo) : io.cwd);
+    let report = auditSnapshot(snapshot, { exceptions });
+    if (flags.repo) {
+      const repo = resolve(io.cwd, flags.repo);
+      report = merge(scanSource(readPaths(["."], repo, SOURCE_FILE), { exceptions }), report);
+    }
+    const fp = fingerprint(snapshot);
+    const nulls = flags.null ? flags.null.split(",").map((p) => loadNull(p.trim(), io.cwd)) : [];
+    const typical = nulls.length ? typicality(fp, nulls.flatMap((m, i) => m.runs.map((r) => nulls.length > 1 ? { ...r, id: `${i + 1}/${r.id}` } : r))) : null;
+    if (flags.json) {
+      io.out(JSON.stringify({ report, fingerprint: fp, typicality: typical, snapshot: flags.out ?? null }, null, 2));
+      return report.summary.blocking > 0 || flags.strict && report.summary.findings > 0 ? 1 : 0;
+    }
+    const code = finish(report, { ...flags, json: false }, `craft audit ${snapshot.url}`, io);
+    io.out("");
+    io.out(describeFingerprint(fp));
+    if (typical) {
+      io.out("");
+      io.out(describeTypicality(typical, nulls.reduce((s, m) => s + m.runs.length, 0), nulls.length));
+    }
+    return code;
+  } catch (error) {
+    io.err(`craft: ${error.message}`);
+    return 2;
+  }
+}
+
+export {
+  describeFingerprint,
+  merge,
+  runAudit
+};

package/dist/chunk-J2BOAIHJ.js

@@ -0,0 +1,175 @@
+import {
+  REFLEX_FONTS_1,
+  REFLEX_FONTS_2,
+  deltaEOk,
+  isAiViolet,
+  isCream,
+  normaliseFamily,
+  parseColour
+} from "./chunk-3AP4PJMX.js";
+
+// src/direction/types.ts
+var DIRECTION_VERSION = 1;
+var SOURCE_KINDS = [
+  "livery",
+  "shopfront",
+  "signage",
+  "packaging",
+  "product",
+  "uniform",
+  "interior",
+  "place",
+  "material",
+  "trade",
+  "print",
+  "photo",
+  "founder"
+];
+var CHOICE_KEYS = ["accent", "ground", "display", "body", "shape", "motif", "signature"];
+
+// src/direction/validate.ts
+var PREFERENCE = /\b(?:client (?:likes|liked|wants|wanted|asked|chose|prefers?)|(?:we|they|i) (?:like|liked|love|loved|prefer)|on[- ]trend|trendy|popular|what (?:everyone|competitors) (?:uses?|does)|brand (?:colou?r|font|guidelines?) (?:is|are|says?))\b/i;
+var MOOD = /\b(?:modern|clean|fresh|professional|trustworthy|premium|elegant|sleek|timeless|minimal(?:ist)?|bold|vibrant|friendly|approachable|luxur(?:y|ious)|sophisticated|contemporary|stylish|warm|inviting|high[- ]end)\b/gi;
+var VALUE_WORDS = /* @__PURE__ */ new Set(["green", "blue", "navy", "black", "white", "cream", "grey", "gray", "gold", "yellow", "orange", "purple", "violet", "pink", "brown", "teal", "bottle", "dark", "light", "deep", "pale", "bright", "colour", "color", "font", "face", "serif", "sans", "type", "lettering"]);
+var STOP = /* @__PURE__ */ new Set(["with", "that", "this", "from", "their", "they", "have", "been", "were", "which", "what", "when", "where", "there", "about", "into", "onto", "over", "same", "each", "every"]);
+function words(text) {
+  return new Set((text.toLowerCase().match(/[a-z][a-z'-]{3,}/g) ?? []).map((w) => w.replace(/'s$/, "")).filter((w) => !STOP.has(w) && !VALUE_WORDS.has(w)));
+}
+function tellFor(key, value) {
+  if (key === "accent") {
+    const c = parseColour(value);
+    return c && isAiViolet(c.oklch) ? "ai-violet" : null;
+  }
+  if (key === "ground") {
+    const c = parseColour(value);
+    return c && isCream(c.oklch) ? "cream-palette" : null;
+  }
+  if (key === "display" || key === "body") {
+    const name = normaliseFamily(value).toLowerCase();
+    if (REFLEX_FONTS_1.some((f) => f.toLowerCase() === name)) return "reflex-font";
+    if (REFLEX_FONTS_2.some((f) => f.toLowerCase() === name)) return "reflex-font-2";
+  }
+  return null;
+}
+function validateDirection(input, ctx = {}) {
+  const problems = [];
+  const err = (at, message) => problems.push({ severity: "error", at, message });
+  const warn = (at, message) => problems.push({ severity: "warn", at, message });
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    err("", "art-direction.json must be a JSON object");
+    return { valid: false, problems, decided: 0 };
+  }
+  const d = input;
+  const legacy = d.version === void 0 && d.choices === void 0 && Array.isArray(d.exceptions);
+  if (legacy) {
+    warn("", "exceptions only: run craft direction init to record the choices and their reasons");
+    return { valid: true, problems, decided: 0 };
+  }
+  if (d.version !== DIRECTION_VERSION) err("version", `version must be ${DIRECTION_VERSION}`);
+  if (typeof d.client !== "string" || !d.client.trim()) err("client", "name the client");
+  if (typeof d.brief !== "string" || d.brief.trim().split(/\s+/).length < 8) err("brief", "the brief needs a sentence: who, where, and what they do");
+  const sources = Array.isArray(d.sources) ? d.sources : [];
+  if (!Array.isArray(d.sources)) err("sources", "sources must be a list");
+  if (sources.length === 0) err("sources", "no sources: a reason needs something in the client's world to point at");
+  const ids = /* @__PURE__ */ new Set();
+  sources.forEach((s, i) => {
+    const at = `sources[${i}]`;
+    if (!s || typeof s !== "object") return err(at, "a source must be an object");
+    if (typeof s.id !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(s.id)) err(`${at}.id`, "id must be short kebab-case");
+    else if (ids.has(s.id)) err(`${at}.id`, `"${s.id}" is used twice`);
+    else ids.add(s.id);
+    if (!SOURCE_KINDS.includes(s.kind)) err(`${at}.kind`, `kind must be one of: ${SOURCE_KINDS.join(", ")}`);
+    if (typeof s.note !== "string" || s.note.trim().split(/\s+/).length < 3) err(`${at}.note`, "say what it is and where");
+    if (s.path && ctx.pathExists && !/^https?:/.test(s.path) && !ctx.pathExists(s.path)) err(`${at}.path`, `${s.path} does not exist`);
+    for (const [j, c] of (s.colours ?? []).entries()) if (!parseColour(c)) err(`${at}.colours[${j}]`, `"${c}" is not a colour`);
+  });
+  const choices = d.choices && typeof d.choices === "object" ? d.choices : {};
+  if (!d.choices || typeof d.choices !== "object") err("choices", "choices must be an object");
+  const exceptions = Array.isArray(d.exceptions) ? d.exceptions : [];
+  let decided = 0;
+  for (const key of Object.keys(choices)) {
+    if (!CHOICE_KEYS.includes(key)) err(`choices.${key}`, `not a choice craft knows. Choices are: ${CHOICE_KEYS.join(", ")}. Layout and navigation stay conventional.`);
+  }
+  for (const key of CHOICE_KEYS) {
+    const c = choices[key];
+    const at = `choices.${key}`;
+    if (!c) {
+      warn(at, "not decided yet");
+      continue;
+    }
+    let ok = true;
+    if (typeof c.value !== "string" || !c.value.trim()) {
+      err(`${at}.value`, "no value");
+      ok = false;
+    } else if ((key === "accent" || key === "ground") && !parseColour(c.value)) {
+      err(`${at}.value`, `"${c.value}" is not a colour`);
+      ok = false;
+    }
+    const because = typeof c.because === "string" ? c.because.trim() : "";
+    const evidence = Array.isArray(c.evidence) ? c.evidence : [];
+    if (because.split(/\s+/).filter(Boolean).length < 8) {
+      err(`${at}.because`, "a reason is at least a sentence. Without one this is a default, however good it looks.");
+      ok = false;
+    } else if (because.startsWith("PROPOSED:")) {
+      err(`${at}.because`, "a proposal, not yet a decision. Check it against the source, then rewrite the reason in your own words.");
+      ok = false;
+    } else {
+      if (PREFERENCE.test(because)) {
+        err(`${at}.because`, "that is a preference, not a reason. Say what in the client's world this comes from.");
+        ok = false;
+      }
+      const moods = because.match(MOOD) ?? [];
+      if (moods.length >= 2) {
+        err(`${at}.because`, `"${moods.join(", ")}" describes a mood, not a source. Name the thing it comes from.`);
+        ok = false;
+      }
+    }
+    if (evidence.length === 0) {
+      err(`${at}.evidence`, "cite at least one source");
+      ok = false;
+    }
+    for (const id of evidence) {
+      if (!ids.has(id)) {
+        err(`${at}.evidence`, `no source called "${id}"`);
+        ok = false;
+      }
+    }
+    if (ok) {
+      const cited = sources.filter((s) => evidence.includes(s.id));
+      const reasonWords = words(because);
+      const tied = cited.some((s) => reasonWords.has(s.id) || [...words(`${s.note} ${s.lettering ?? ""}`)].some((w) => reasonWords.has(w)));
+      if (!tied) {
+        err(`${at}.because`, `the reason does not mention what its evidence shows (${evidence.join(", ")}). Say what on it this comes from.`);
+        ok = false;
+      }
+    }
+    if (typeof c.value === "string") {
+      const tell = tellFor(key, c.value);
+      if (tell && !exceptions.some((e) => e.tell === tell)) {
+        err(`${at}.value`, `${c.value} is on the tell catalogue (${tell}). Keep it only with an exception for ${tell}, carrying the same reason.`);
+        ok = false;
+      }
+    }
+    const fp = ctx.fingerprint;
+    if (fp && typeof c.value === "string") {
+      if ((key === "accent" || key === "ground") && parseColour(c.value)) {
+        const declared = parseColour(c.value).oklch;
+        const measured = key === "accent" ? fp.accent : fp.ground;
+        if (measured && deltaEOk(declared, measured) > 0.08) {
+          warn(`${at}.value`, `the page does not show it: its ${key} measures oklch(${measured.l.toFixed(2)} ${measured.c.toFixed(3)} ${measured.h.toFixed(0)})`);
+        }
+      }
+      if (key === "display" || key === "body") {
+        const measured = key === "display" ? fp.display.family : fp.body.family;
+        if (normaliseFamily(c.value).toLowerCase() !== measured.toLowerCase()) warn(`${at}.value`, `the page sets ${measured}, not ${c.value}`);
+      }
+    }
+    if (ok) decided += 1;
+  }
+  return { valid: problems.every((p) => p.severity !== "error"), problems, decided };
+}
+
+export {
+  DIRECTION_VERSION,
+  validateDirection
+};