@hegemonart/get-design-done 1.22.0 → 1.23.0

package/scripts/lib/touches-pattern-miner.cjs

@@ -0,0 +1,195 @@
+/**
+ * touches-pattern-miner.cjs — auto-crystallization PROPOSALS only
+ * (Plan 23-06).
+ *
+ * Scans archived task markdown across cycles, normalizes their
+ * `Touches:` signatures, and emits a JSON proposal file when a
+ * signature recurs in ≥ minTasks tasks across ≥ minCycles cycles.
+ *
+ * NEVER auto-applies. The reflector + `/gdd:apply-reflections`
+ * pipeline consumes the proposal JSON separately and asks the user
+ * before materializing anything.
+ *
+ * Reads:  cwd/cycleDir/cycle-{slug}/tasks/{name}.md
+ *         (cycleDir defaults to .design/archive)
+ * Writes: cwd/.design/learnings/touches-patterns.json
+ *         (atomic via .tmp sibling + rename)
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { parseTouches } = require('./touches-analyzer/index.cjs');
+
+const DEFAULT_CYCLE_DIR = '.design/archive';
+const DEFAULT_OUT_PATH = '.design/learnings/touches-patterns.json';
+const DEFAULT_MIN_TASKS = 3;
+const DEFAULT_MIN_CYCLES = 2;
+
+const CYCLE_DATED_RE = /^cycle-\d{4}-\d{2}-\d{2}.*/i;
+const CYCLE_SLUG_RE = /^cycle-[a-z0-9-]+$/i;
+
+/**
+ * Canonicalize a glob list into a stable signature string.
+ *
+ * @param {string[]} globs
+ * @returns {string}
+ */
+function canonicalize(globs) {
+  if (!Array.isArray(globs) || globs.length === 0) return '';
+  const norm = globs
+    .map((g) => stripCycleSlugs(String(g).replace(/\\/g, '/').toLowerCase()))
+    .filter((g) => g.length > 0);
+  const dedup = Array.from(new Set(norm));
+  dedup.sort();
+  return dedup.join(',');
+}
+
+/**
+ * Replace `cycle-2026-04-01` / `cycle-foo-bar` segments with `<cycle>`.
+ *
+ * @param {string} normalizedPath
+ * @returns {string}
+ */
+function stripCycleSlugs(normalizedPath) {
+  return normalizedPath
+    .split('/')
+    .map((seg) => (CYCLE_DATED_RE.test(seg) || CYCLE_SLUG_RE.test(seg) ? '<cycle>' : seg))
+    .join('/');
+}
+
+/**
+ * @typedef {Object} TouchesSignature
+ * @property {string} signature
+ * @property {string[]} globs
+ * @property {Array<{cycle: string, task: string}>} occurrences
+ * @property {number} cycleCount
+ * @property {number} taskCount
+ */
+
+/**
+ * @typedef {Object} MinerProposal
+ * @property {string} schema_version
+ * @property {string} generated_at
+ * @property {{minTasks: number, minCycles: number}} thresholds
+ * @property {TouchesSignature[]} proposals
+ */
+
+/**
+ * Walk archived cycles and tally signature occurrences.
+ *
+ * @param {{cwd?: string, cycleDir?: string, minTasks?: number, minCycles?: number}} [opts]
+ * @returns {Promise<MinerProposal>}
+ */
+async function mine(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const cycleDir = opts.cycleDir ?? DEFAULT_CYCLE_DIR;
+  const minTasks = opts.minTasks ?? DEFAULT_MIN_TASKS;
+  const minCycles = opts.minCycles ?? DEFAULT_MIN_CYCLES;
+
+  const archiveRoot = path.isAbsolute(cycleDir) ? cycleDir : path.join(cwd, cycleDir);
+  /** @type {Map<string, {globs: string[], occurrences: Array<{cycle: string, task: string}>, cycleSet: Set<string>}>} */
+  const byKey = new Map();
+
+  let entries = [];
+  try {
+    entries = fs.readdirSync(archiveRoot, { withFileTypes: true });
+  } catch {
+    // Archive dir missing → empty proposal envelope.
+  }
+
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    if (!ent.name.toLowerCase().startsWith('cycle-')) continue;
+    const cycleId = ent.name;
+    const tasksDir = path.join(archiveRoot, cycleId, 'tasks');
+    let taskFiles = [];
+    try {
+      taskFiles = fs
+        .readdirSync(tasksDir, { withFileTypes: true })
+        .filter((d) => d.isFile() && d.name.toLowerCase().endsWith('.md'))
+        .map((d) => d.name);
+    } catch {
+      continue;
+    }
+    for (const taskName of taskFiles) {
+      const taskPath = path.join(tasksDir, taskName);
+      let md;
+      try {
+        md = fs.readFileSync(taskPath, 'utf8');
+      } catch {
+        continue;
+      }
+      const globs = parseTouches(md);
+      if (globs.length === 0) continue;
+      const sig = canonicalize(globs);
+      if (sig.length === 0) continue;
+      let bucket = byKey.get(sig);
+      if (!bucket) {
+        bucket = {
+          globs: sig.split(','),
+          occurrences: [],
+          cycleSet: new Set(),
+        };
+        byKey.set(sig, bucket);
+      }
+      bucket.occurrences.push({ cycle: cycleId, task: taskName });
+      bucket.cycleSet.add(cycleId);
+    }
+  }
+
+  /** @type {TouchesSignature[]} */
+  const proposals = [];
+  for (const [signature, bucket] of byKey) {
+    if (bucket.occurrences.length < minTasks) continue;
+    if (bucket.cycleSet.size < minCycles) continue;
+    proposals.push({
+      signature,
+      globs: bucket.globs,
+      occurrences: bucket.occurrences.slice(),
+      cycleCount: bucket.cycleSet.size,
+      taskCount: bucket.occurrences.length,
+    });
+  }
+  proposals.sort((a, b) => {
+    if (a.taskCount !== b.taskCount) return b.taskCount - a.taskCount;
+    return a.signature < b.signature ? -1 : a.signature > b.signature ? 1 : 0;
+  });
+
+  return {
+    schema_version: '1.0.0',
+    generated_at: new Date().toISOString(),
+    thresholds: { minTasks, minCycles },
+    proposals,
+  };
+}
+
+/**
+ * Atomic write of the proposal envelope. Returns the absolute path
+ * written.
+ *
+ * @param {MinerProposal} proposal
+ * @param {{cwd?: string, outPath?: string}} [opts]
+ * @returns {string}
+ */
+function writeProposals(proposal, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const outRel = opts.outPath ?? DEFAULT_OUT_PATH;
+  const out = path.isAbsolute(outRel) ? outRel : path.join(cwd, outRel);
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  const tmp = out + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(proposal, null, 2));
+  fs.renameSync(tmp, out);
+  return out;
+}
+
+module.exports = {
+  mine,
+  writeProposals,
+  canonicalize,
+  stripCycleSlugs,
+  DEFAULT_CYCLE_DIR,
+  DEFAULT_OUT_PATH,
+};

package/scripts/lib/visual-baseline/diff.cjs

@@ -0,0 +1,137 @@
+/**
+ * visual-baseline/diff.cjs — pixel-diff primitive (Plan 23-07).
+ *
+ * Compares two PNG buffers. With `pngjs` installed (probeOptional),
+ * decodes both and counts pixels whose R/G/B/A channels differ beyond
+ * the tolerance. Without `pngjs`, falls back to bytewise equality
+ * (SHA-256 hash compare) — ratio is `equal ? 0 : 1`.
+ *
+ * Dimension mismatch in pixel mode → ratio=1, drifted=true,
+ * reason='dimension-mismatch'. Never throws on shape mismatch.
+ */
+
+'use strict';
+
+const { createHash } = require('node:crypto');
+const { probeOptional } = require('../probe-optional.cjs');
+
+const _pngjs = probeOptional('pngjs');
+
+const DEFAULT_THRESHOLD = 0.005;
+const DEFAULT_TOLERANCE = 4;
+
+/**
+ * @typedef {Object} DiffResult
+ * @property {boolean} drifted
+ * @property {number} ratio
+ * @property {number} diffPixels
+ * @property {number} totalPixels
+ * @property {'pixel'|'bytewise'} mode
+ * @property {string} [reason]
+ */
+
+function bytewiseDiff(a, b, threshold) {
+  const ha = createHash('sha256').update(a).digest('hex');
+  const hb = createHash('sha256').update(b).digest('hex');
+  const equal = ha === hb;
+  const ratio = equal ? 0 : 1;
+  return {
+    drifted: ratio > threshold,
+    ratio,
+    diffPixels: equal ? 0 : 1,
+    totalPixels: 1,
+    mode: 'bytewise',
+    reason: 'pngjs-not-available',
+  };
+}
+
+function pixelDiff(a, b, threshold, tolerance) {
+  const { PNG } = _pngjs;
+  let pa;
+  let pb;
+  try {
+    pa = PNG.sync.read(a);
+  } catch (err) {
+    return {
+      drifted: true,
+      ratio: 1,
+      diffPixels: 0,
+      totalPixels: 0,
+      mode: 'pixel',
+      reason: `decode-a-failed: ${err && err.message ? err.message : String(err)}`,
+    };
+  }
+  try {
+    pb = PNG.sync.read(b);
+  } catch (err) {
+    return {
+      drifted: true,
+      ratio: 1,
+      diffPixels: 0,
+      totalPixels: 0,
+      mode: 'pixel',
+      reason: `decode-b-failed: ${err && err.message ? err.message : String(err)}`,
+    };
+  }
+  if (pa.width !== pb.width || pa.height !== pb.height) {
+    return {
+      drifted: true,
+      ratio: 1,
+      diffPixels: 0,
+      totalPixels: 0,
+      mode: 'pixel',
+      reason: 'dimension-mismatch',
+    };
+  }
+  const total = pa.width * pa.height;
+  const A = pa.data;
+  const B = pb.data;
+  let diffPx = 0;
+  for (let i = 0; i < A.length; i += 4) {
+    const dr = Math.abs(A[i] - B[i]);
+    const dg = Math.abs(A[i + 1] - B[i + 1]);
+    const db = Math.abs(A[i + 2] - B[i + 2]);
+    const da = Math.abs(A[i + 3] - B[i + 3]);
+    if (dr > tolerance || dg > tolerance || db > tolerance || da > tolerance) {
+      diffPx += 1;
+    }
+  }
+  const ratio = total > 0 ? diffPx / total : 0;
+  return {
+    drifted: ratio > threshold,
+    ratio,
+    diffPixels: diffPx,
+    totalPixels: total,
+    mode: 'pixel',
+  };
+}
+
+/**
+ * Compare two PNG buffers.
+ *
+ * @param {Buffer} a
+ * @param {Buffer} b
+ * @param {{threshold?: number, tolerance?: number}} [opts]
+ * @returns {DiffResult}
+ */
+function diff(a, b, opts = {}) {
+  if (!Buffer.isBuffer(a) || !Buffer.isBuffer(b)) {
+    throw new TypeError('visual-baseline/diff: both inputs must be Buffers');
+  }
+  const threshold = typeof opts.threshold === 'number' ? opts.threshold : DEFAULT_THRESHOLD;
+  const tolerance = typeof opts.tolerance === 'number' ? opts.tolerance : DEFAULT_TOLERANCE;
+  if (!_pngjs) return bytewiseDiff(a, b, threshold);
+  return pixelDiff(a, b, threshold, tolerance);
+}
+
+/** Test-only: report whether pngjs is available. */
+function pngjsAvailable() {
+  return _pngjs !== null && _pngjs !== undefined;
+}
+
+module.exports = {
+  diff,
+  pngjsAvailable,
+  DEFAULT_THRESHOLD,
+  DEFAULT_TOLERANCE,
+};

package/scripts/lib/visual-baseline/index.cjs

@@ -0,0 +1,139 @@
+/**
+ * visual-baseline/index.cjs — baseline manager for PNG drift checks
+ * (Plan 23-07).
+ *
+ * Reads/writes `.design/baselines/<key>.png`. Compare delegates to
+ * `./diff.cjs#diff`. Atomic write via `.tmp` sibling + rename.
+ *
+ * Defers Playwright/Preview MCP screenshot capture orchestration to a
+ * later phase — this module only handles "given a PNG buffer, compare it
+ * / save it as the baseline".
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { diff, DEFAULT_THRESHOLD, DEFAULT_TOLERANCE } = require('./diff.cjs');
+
+const DEFAULT_BASELINE_DIR = '.design/baselines';
+const SAFE_KEY_RE = /^[a-z0-9][a-z0-9._-]{0,127}$/i;
+
+/**
+ * @typedef {Object} CompareOutcome
+ * @property {boolean} drifted
+ * @property {number} ratio
+ * @property {boolean} baselineExists
+ * @property {string} baselinePath
+ * @property {'pixel'|'bytewise'|'absent'} mode
+ * @property {number} [diffPixels]
+ * @property {number} [totalPixels]
+ * @property {string} [reason]
+ */
+
+/**
+ * Validate a baseline key. Rejects path separators, '..', and unsafe
+ * characters that could traverse outside the baseline dir.
+ *
+ * @param {string} key
+ * @returns {string}
+ */
+function validateKey(key) {
+  if (typeof key !== 'string' || key.length === 0) {
+    throw new TypeError('visual-baseline: key must be a non-empty string');
+  }
+  if (key.includes('..') || key.includes('/') || key.includes('\\')) {
+    throw new RangeError(
+      `visual-baseline: key "${key}" contains illegal characters (/, \\, ..)`,
+    );
+  }
+  if (!SAFE_KEY_RE.test(key)) {
+    throw new RangeError(
+      `visual-baseline: key "${key}" must match /^[a-z0-9][a-z0-9._-]{0,127}$/i`,
+    );
+  }
+  return key;
+}
+
+/**
+ * Resolve baseline file path.
+ *
+ * @param {string} key
+ * @param {{cwd?: string, baselineDir?: string}} [opts]
+ * @returns {string}
+ */
+function baselinePathFor(key, opts = {}) {
+  validateKey(key);
+  const cwd = opts.cwd ?? process.cwd();
+  const dir = opts.baselineDir ?? DEFAULT_BASELINE_DIR;
+  const root = path.isAbsolute(dir) ? dir : path.join(cwd, dir);
+  return path.join(root, `${key}.png`);
+}
+
+/**
+ * Compare a PNG buffer to the on-disk baseline.
+ *
+ * @param {string} key
+ * @param {Buffer} pngBuffer
+ * @param {{cwd?: string, threshold?: number, tolerance?: number, baselineDir?: string}} [opts]
+ * @returns {CompareOutcome}
+ */
+function compareToBaseline(key, pngBuffer, opts = {}) {
+  if (!Buffer.isBuffer(pngBuffer)) {
+    throw new TypeError('visual-baseline: pngBuffer must be a Buffer');
+  }
+  const baselinePath = baselinePathFor(key, opts);
+  if (!fs.existsSync(baselinePath)) {
+    return {
+      drifted: true,
+      ratio: NaN,
+      baselineExists: false,
+      baselinePath,
+      mode: 'absent',
+      reason: 'baseline-not-found',
+    };
+  }
+  const a = fs.readFileSync(baselinePath);
+  const r = diff(a, pngBuffer, opts);
+  return {
+    drifted: r.drifted,
+    ratio: r.ratio,
+    baselineExists: true,
+    baselinePath,
+    mode: r.mode,
+    diffPixels: r.diffPixels,
+    totalPixels: r.totalPixels,
+    reason: r.reason,
+  };
+}
+
+/**
+ * Persist a PNG buffer as the baseline. Atomic write (.tmp + rename).
+ *
+ * @param {string} key
+ * @param {Buffer} pngBuffer
+ * @param {{cwd?: string, baselineDir?: string}} [opts]
+ * @returns {string} absolute path written
+ */
+function applyBaseline(key, pngBuffer, opts = {}) {
+  if (!Buffer.isBuffer(pngBuffer)) {
+    throw new TypeError('visual-baseline: pngBuffer must be a Buffer');
+  }
+  const out = baselinePathFor(key, opts);
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  const tmp = out + '.tmp';
+  fs.writeFileSync(tmp, pngBuffer);
+  fs.renameSync(tmp, out);
+  return out;
+}
+
+module.exports = {
+  compareToBaseline,
+  applyBaseline,
+  baselinePathFor,
+  validateKey,
+  DEFAULT_BASELINE_DIR,
+  DEFAULT_THRESHOLD,
+  DEFAULT_TOLERANCE,
+};