@bompus/house-rules 0.0.0-stage → 0.13.0

package/skills/hr-usage-report/assets/example-report.json

@@ -0,0 +1,125 @@
+{
+  "title": "Example: three models across effort levels (illustrative data)",
+  "series": {
+    "small": { "name": "Model S", "slot": 0 },
+    "mid": { "name": "Model M", "slot": 1 },
+    "large": { "name": "Model L", "slot": 2 },
+    "previous": { "name": "Model L (previous)", "reference": true }
+  },
+  "sections": [
+    {
+      "type": "curve",
+      "title": "Score against cost per task, every effort level",
+      "sub": "Illustrative values. Each line runs low to max on a log cost axis.",
+      "xLog": true,
+      "xDomain": [0.05, 20],
+      "yDomain": [20, 60],
+      "xTicks": [0.1, 0.3, 1, 3, 10],
+      "xPrefix": "$",
+      "yTicks": [20, 30, 40, 50, 60],
+      "ySuffix": "%",
+      "xLabel": "cost per task (log)",
+      "series": [
+        {
+          "key": "small",
+          "points": [
+            { "label": "low", "x": 0.08, "y": 28, "tip": "28% · $0.08/task" },
+            { "label": "medium", "x": 0.2, "y": 34, "tip": "34% · $0.20/task" },
+            { "label": "max", "x": 1, "y": 45, "tip": "45% · $1.00/task" }
+          ]
+        },
+        {
+          "key": "mid",
+          "points": [
+            { "label": "low", "x": 0.5, "y": 35, "tip": "35% · $0.50/task" },
+            { "label": "medium", "x": 0.8, "y": 40, "tip": "40% · $0.80/task" },
+            { "label": "max", "x": 8, "y": 54, "tip": "54% · $8.00/task" }
+          ]
+        },
+        {
+          "key": "large",
+          "points": [
+            { "label": "low", "x": 1.2, "y": 44, "tip": "44% · $1.20/task" },
+            { "label": "medium", "x": 3, "y": 52, "tip": "52% · $3.00/task" },
+            { "label": "max", "x": 12, "y": 57, "tip": "57% · $12.00/task" }
+          ]
+        },
+        {
+          "key": "previous",
+          "points": [
+            { "label": "low", "x": 5, "y": 43, "tip": "43% · $5.00/task" },
+            { "label": "max", "x": 16, "y": 50, "tip": "50% · $16.00/task" }
+          ]
+        }
+      ]
+    },
+    {
+      "type": "ladder",
+      "title": "Review: bugs found per effort level",
+      "sub": "Illustrative values; notes carry run counts.",
+      "categories": ["low", "medium", "high", "max"],
+      "yDomain": [0, 50],
+      "yTicks": [0, 25, 50],
+      "series": [
+        {
+          "key": "small",
+          "values": [10, 12, 16, null],
+          "notes": ["1 run", "1 run", "2 runs", "no row"]
+        },
+        {
+          "key": "mid",
+          "values": [18, 23, 34, 45],
+          "notes": ["3 runs", "3 runs", "3 runs", "3 runs"]
+        },
+        {
+          "key": "large",
+          "values": [22, 30, 32, 41],
+          "notes": ["3 runs", "3 runs", "3 runs", "3 runs"]
+        }
+      ]
+    },
+    {
+      "type": "pair",
+      "items": [
+        {
+          "type": "bars",
+          "title": "Generation speed: output tokens/s",
+          "max": 400,
+          "rows": [
+            { "label": "Model S", "key": "small", "value": 380 },
+            { "label": "Model M", "key": "mid", "value": 220 },
+            { "label": "Model L", "key": "large", "value": 125 }
+          ]
+        },
+        {
+          "type": "bars",
+          "title": "Task time: minutes per task",
+          "max": 3,
+          "rows": [
+            { "label": "Model S", "key": "small", "value": 2.6, "display": "2:36" },
+            { "label": "Model M", "key": "mid", "value": 1, "display": "1:00" },
+            { "label": "Model L", "key": "large", "value": 2.1, "display": "2:06" }
+          ]
+        }
+      ]
+    },
+    {
+      "type": "table",
+      "title": "Model S: where it fits",
+      "columns": ["Role", "Key evidence", "Verdict"],
+      "rows": [
+        [
+          "Narrow read-only lookups",
+          "Equal accuracy on known-answer lookups at a fraction of the cost",
+          { "text": "Yes", "verdict": "yes" }
+        ],
+        [
+          "Mechanical edits",
+          "Matches Model M medium at lower cost; untested on your work",
+          { "text": "Try on a named task", "verdict": "maybe" }
+        ],
+        ["Review", "Finds about half of what Model L finds", { "text": "No", "verdict": "no" }]
+      ]
+    }
+  ]
+}

package/skills/hr-usage-report/assets/report-template.html

@@ -0,0 +1,377 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <!-- Model comparison report. scripts/render-report.ts fills #report-data from a data file;
+     section types and rules: SKILL.md. Colors: up to three categorical series
+     (validated dark-surface slots) plus one dashed neutral "reference" series. -->
+    <style>
+      :root {
+        --s1: #3987e5;
+        --s2: #d95926;
+        --s3: #199e70;
+        --ref: #a8a7a0;
+        --fg: var(--foreground, #f2f2f0);
+        --mut: var(--muted-foreground, #b5b4ad);
+        --bd: var(--border, #3a3a38);
+        --bg: var(--background, #1a1a19);
+        --grid: color-mix(in srgb, var(--fg) 12%, transparent);
+      }
+      html,
+      body {
+        background: var(--bg);
+      }
+      body {
+        font-family: var(--font-sans, system-ui, sans-serif);
+        color: var(--fg);
+        margin: 0;
+      }
+      .wrap {
+        display: flex;
+        flex-direction: column;
+        gap: 22px;
+      }
+      h2 {
+        font-size: 18px;
+        margin: 0;
+      }
+      h3 {
+        font-size: 15px;
+        margin: 0 0 2px;
+      }
+      .sub {
+        color: var(--mut);
+        font-size: 12.5px;
+        margin: 0 0 8px;
+        line-height: 1.4;
+      }
+      .legend {
+        display: flex;
+        gap: 14px;
+        flex-wrap: wrap;
+        font-size: 12.5px;
+        color: var(--mut);
+        margin-bottom: 6px;
+      }
+      .legend span {
+        display: inline-flex;
+        align-items: center;
+        gap: 6px;
+      }
+      .sw {
+        width: 18px;
+        height: 0;
+        border-top: 2px solid;
+      }
+      .grid2 {
+        display: grid;
+        grid-template-columns: 1fr 1fr;
+        gap: 18px;
+      }
+      @media (max-width: 560px) {
+        .grid2 {
+          grid-template-columns: 1fr;
+        }
+      }
+      svg {
+        display: block;
+        width: 100%;
+        overflow: visible;
+      }
+      svg text {
+        font-family: inherit;
+        font-size: 11px;
+        fill: var(--mut);
+      }
+      svg .lbl {
+        fill: var(--fg);
+      }
+      .tip {
+        position: fixed;
+        pointer-events: none;
+        background: var(--popover, #262624);
+        color: var(--popover-foreground, var(--fg));
+        border: 1px solid var(--bd);
+        border-radius: 6px;
+        padding: 6px 8px;
+        font-size: 12px;
+        opacity: 0;
+        transition: opacity 0.08s;
+        z-index: 5;
+        max-width: 260px;
+      }
+      table {
+        border-collapse: collapse;
+        width: 100%;
+        font-size: 12.5px;
+      }
+      th,
+      td {
+        text-align: left;
+        padding: 6px 8px;
+        border-bottom: 1px solid var(--bd);
+        vertical-align: top;
+      }
+      th {
+        color: var(--mut);
+        font-weight: 600;
+      }
+      td.n {
+        font-variant-numeric: tabular-nums;
+        white-space: nowrap;
+      }
+      .yes {
+        color: var(--success, #3fb37f);
+      }
+      .no {
+        color: var(--mut);
+      }
+      .maybe {
+        color: var(--warning, #e0a63a);
+      }
+    </style>
+  </head>
+  <body>
+    <div class="wrap" id="root"></div>
+    <div class="tip" id="tip"></div>
+    <script id="report-data" type="application/json">
+      __REPORT_DATA__
+    </script>
+    <script>
+      const DATA = JSON.parse(document.getElementById("report-data").textContent);
+      const SLOTS = ["var(--s1)", "var(--s2)", "var(--s3)"];
+      const NS = "http://www.w3.org/2000/svg";
+      const tip = document.getElementById("tip");
+      const esc = (s) =>
+        String(s).replace(
+          /[&<>"]/g,
+          (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c],
+        );
+      function showTip(e, h) {
+        tip.innerHTML = h;
+        tip.style.opacity = 1;
+        tip.style.left = Math.min(e.clientX + 12, innerWidth - 270) + "px";
+        tip.style.top = e.clientY + 12 + "px";
+      }
+      function hideTip() {
+        tip.style.opacity = 0;
+      }
+      function el(t, a, p) {
+        const n = document.createElementNS(NS, t);
+        for (const k in a) n.setAttribute(k, a[k]);
+        if (p) p.appendChild(n);
+        return n;
+      }
+      function hover(node, html) {
+        node.addEventListener("mousemove", (e) => showTip(e, html));
+        node.addEventListener("mouseleave", hideTip);
+      }
+      // Color follows the entity: a series key keeps its slot across every chart in the report.
+      const keys = DATA.series || {};
+      const color = (k) => (keys[k]?.reference ? "var(--ref)" : SLOTS[keys[k]?.slot ?? 0]);
+      const isRef = (k) => !!keys[k]?.reference;
+      const name = (k) => keys[k]?.name ?? k;
+      const legend = (ks) =>
+        `<div class="legend">${ks.map((k) => `<span><i class="sw" style="border-color:${color(k)};${isRef(k) ? "border-top-style:dashed" : ""}"></i>${esc(name(k))}</span>`).join("")}</div>`;
+      function marker(svg, x, y, k, html) {
+        el(
+          "circle",
+          {
+            cx: x,
+            cy: y,
+            r: 4.5,
+            fill: isRef(k) ? "var(--bg)" : color(k),
+            stroke: isRef(k) ? color(k) : "var(--bg)",
+            "stroke-width": 2,
+          },
+          svg,
+        );
+        hover(el("circle", { cx: x, cy: y, r: 11, fill: "transparent" }, svg), html);
+      }
+      function endLabels(svg, items) {
+        items.sort((a, b) => a.y - b.y);
+        let last = -99;
+        for (const it of items) {
+          const y = Math.max(it.y, last + 13);
+          last = y;
+          el("text", { x: it.x + 8, y: y + 4, class: "lbl" }, svg).textContent = it.text;
+        }
+      }
+      const draw = {
+        // Score against cost (or any two measures): one polyline per series through its effort points.
+        curve(s, svg) {
+          const W = svg.clientWidth,
+            H = s.height || 300,
+            m = { l: 44, r: 74, t: 10, b: 34 };
+          svg.setAttribute("height", H);
+          const xs = s.series.flatMap((r) => r.points.map((p) => p.x)),
+            ys = s.series.flatMap((r) => r.points.map((p) => p.y));
+          const [x0, x1] = s.xDomain || [Math.min(...xs) * 0.7, Math.max(...xs) * 1.4],
+            [y0, y1] = s.yDomain || [
+              Math.floor(Math.min(...ys) / 10) * 10,
+              Math.ceil(Math.max(...ys) / 10) * 10,
+            ];
+          const tx = (v) =>
+            (s.xLog ? Math.log10(v) - Math.log10(x0) : v - x0) /
+            (s.xLog ? Math.log10(x1) - Math.log10(x0) : x1 - x0);
+          const x = (v) => m.l + tx(v) * (W - m.l - m.r),
+            y = (v) => H - m.b - ((v - y0) / (y1 - y0)) * (H - m.t - m.b);
+          for (const v of s.xTicks || []) {
+            el("line", { x1: x(v), x2: x(v), y1: m.t, y2: H - m.b, stroke: "var(--grid)" }, svg);
+            el("text", { x: x(v), y: H - m.b + 15, "text-anchor": "middle" }, svg).textContent =
+              (s.xPrefix || "") + v + (s.xSuffix || "");
+          }
+          for (const v of s.yTicks || []) {
+            el("line", { x1: m.l, x2: W - m.r, y1: y(v), y2: y(v), stroke: "var(--grid)" }, svg);
+            el("text", { x: m.l - 6, y: y(v) + 4, "text-anchor": "end" }, svg).textContent =
+              v + (s.ySuffix || "");
+          }
+          el("text", { x: W / 2, y: H - 2, "text-anchor": "middle" }, svg).textContent =
+            s.xLabel || "";
+          const ends = [];
+          for (const r of s.series) {
+            el(
+              "polyline",
+              {
+                points: r.points.map((p) => x(p.x) + "," + y(p.y)).join(" "),
+                fill: "none",
+                stroke: color(r.key),
+                "stroke-width": 2,
+                "stroke-dasharray": isRef(r.key) ? "5 4" : "",
+              },
+              svg,
+            );
+            for (const p of r.points)
+              marker(
+                svg,
+                x(p.x),
+                y(p.y),
+                r.key,
+                `<b>${esc(name(r.key))} ${esc(p.label)}</b><br>${esc(p.tip || "")}`,
+              );
+            const L = r.points[r.points.length - 1];
+            ends.push({ x: x(L.x), y: y(L.y), text: name(r.key).split(" ")[0] });
+          }
+          endLabels(svg, ends);
+        },
+        // One value per category per series (effort ladders).
+        ladder(s, svg) {
+          const W = svg.clientWidth,
+            H = s.height || 250,
+            m = { l: 34, r: 74, t: 10, b: 26 },
+            n = s.categories.length;
+          svg.setAttribute("height", H);
+          const [y0, y1] = s.yDomain,
+            x = (i) => m.l + (i / (n - 1)) * (W - m.l - m.r),
+            y = (v) => H - m.b - ((v - y0) / (y1 - y0)) * (H - m.t - m.b);
+          for (const v of s.yTicks || []) {
+            el("line", { x1: m.l, x2: W - m.r, y1: y(v), y2: y(v), stroke: "var(--grid)" }, svg);
+            el("text", { x: m.l - 6, y: y(v) + 4, "text-anchor": "end" }, svg).textContent = v;
+          }
+          s.categories.forEach((c, i) => {
+            el("text", { x: x(i), y: H - m.b + 16, "text-anchor": "middle" }, svg).textContent = c;
+          });
+          const ends = [];
+          for (const r of s.series) {
+            const pts = r.values.map((v, i) => [i, v]).filter((p) => p[1] !== null);
+            el(
+              "polyline",
+              {
+                points: pts.map(([i, v]) => x(i) + "," + y(v)).join(" "),
+                fill: "none",
+                stroke: color(r.key),
+                "stroke-width": 2,
+                "stroke-dasharray": isRef(r.key) ? "5 4" : "",
+              },
+              svg,
+            );
+            for (const [i, v] of pts)
+              marker(
+                svg,
+                x(i),
+                y(v),
+                r.key,
+                `<b>${esc(name(r.key))} ${esc(s.categories[i])}</b><br>${esc(v)}${r.notes?.[i] ? " · " + esc(r.notes[i]) : ""}`,
+              );
+            const L = pts[pts.length - 1];
+            ends.push({ x: x(L[0]), y: y(L[1]), text: name(r.key).split(" ")[0] });
+          }
+          endLabels(svg, ends);
+        },
+        // Horizontal bars; rows name their series for color.
+        bars(s, svg) {
+          const W = svg.clientWidth,
+            H = s.height || 190,
+            lw = s.labelWidth || 96,
+            rh = (H - 6) / s.rows.length,
+            max = s.max || Math.max(...s.rows.map((r) => r.value)) * 1.1;
+          svg.setAttribute("height", H);
+          s.rows.forEach((r, i) => {
+            const w = ((W - lw - 46) * r.value) / max,
+              yy = i * rh + 4,
+              bh = rh - 12;
+            el("text", { x: 0, y: yy + bh / 2 + 4 }, svg).textContent = r.label;
+            const b = el(
+              "rect",
+              {
+                x: lw,
+                y: yy,
+                width: Math.max(w, 2),
+                height: bh,
+                rx: 4,
+                fill: isRef(r.key) ? "none" : color(r.key),
+                stroke: isRef(r.key) ? color(r.key) : "none",
+                "stroke-dasharray": isRef(r.key) ? "5 4" : "",
+                "stroke-width": isRef(r.key) ? 1.5 : 0,
+              },
+              svg,
+            );
+            el("text", { x: lw + w + 6, y: yy + bh / 2 + 4, class: "lbl" }, svg).textContent =
+              r.display ?? r.value;
+            hover(b, `<b>${esc(r.label)}</b><br>${esc(r.tip || "")}`);
+          });
+        },
+      };
+      function section(s) {
+        const box = document.createElement("section");
+        box.innerHTML = `<h3>${esc(s.title || "")}</h3>${s.sub ? `<p class="sub">${esc(s.sub)}</p>` : ""}`;
+        if (s.type === "pair") {
+          box.className = "grid2";
+          box.innerHTML = "";
+          for (const c of s.items) box.appendChild(section(c));
+          return box;
+        }
+        if (s.type === "table") {
+          const cls = (v) => ({ yes: "yes", no: "no", maybe: "maybe" })[v] || "";
+          box.innerHTML += `<table><thead><tr>${s.columns.map((c) => `<th>${esc(c)}</th>`).join("")}</tr></thead><tbody>${s.rows
+            .map(
+              (row) =>
+                `<tr>${row
+                  .map((c, i) => {
+                    const v = typeof c === "object" && c ? c : { text: c };
+                    return `<td class="${s.numeric?.includes(i) ? "n" : ""} ${cls(v.verdict)}">${esc(v.text)}</td>`;
+                  })
+                  .join("")}</tr>`,
+            )
+            .join("")}</tbody></table>`;
+          return box;
+        }
+        const ks = s.series ? s.series.map((r) => r.key) : [];
+        if (ks.length > 1) box.insertAdjacentHTML("beforeend", legend(ks));
+        const svg = el("svg", { height: s.height || 200 }, box);
+        box._draw = () => {
+          svg.innerHTML = "";
+          draw[s.type](s, svg);
+        };
+        return box;
+      }
+      const root = document.getElementById("root");
+      if (DATA.title) root.insertAdjacentHTML("beforeend", `<h2>${esc(DATA.title)}</h2>`);
+      const nodes = DATA.sections.map(section);
+      nodes.forEach((n) => root.appendChild(n));
+      const redraw = () => root.querySelectorAll("section").forEach((n) => n._draw && n._draw());
+      redraw();
+      addEventListener("resize", redraw);
+    </script>
+  </body>
+</html>

package/skills/hr-usage-report/scripts/render-report.ts

@@ -0,0 +1,86 @@
+#!/usr/bin/env bun
+// Render a model comparison report: data JSON in, self-contained HTML out.
+//
+//   bun render-report.ts <data.json> <out.html>
+//
+// Data shape and section types: ../SKILL.md. Example data:
+// ../assets/example-report.json.
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+type Series = { name: string; slot?: number; reference?: boolean };
+type Section = {
+  type: string;
+  items?: Section[];
+  series?: { key: string }[];
+  rows?: { key?: string }[];
+};
+export type ReportData = { title?: string; series: Record<string, Series>; sections: Section[] };
+
+const TYPES = new Set(["curve", "ladder", "bars", "table", "pair"]);
+
+/** Problems that would make the page wrong or unreadable; empty when the data is usable. */
+export function check(data: ReportData): string[] {
+  const errors: string[] = [];
+  const entries = Object.entries(data.series);
+  const colored = entries.filter(([, s]) => !s.reference);
+  // The template's three dark-surface slots pass the all-pairs color-vision check;
+  // a fourth hue does not, so further series must be a dashed reference or a separate chart.
+  if (colored.length > 3) {
+    errors.push(
+      `at most 3 colored series (got ${colored.length}); mark one more "reference": true or put the rest in a separate report`,
+    );
+  }
+  if (entries.filter(([, s]) => s.reference).length > 1) {
+    errors.push("at most one reference series");
+  }
+  const slots = colored.map(([, s]) => s.slot);
+  if (
+    slots.some((s) => s === undefined || s < 0 || s > 2) ||
+    new Set(slots).size !== slots.length
+  ) {
+    errors.push("each colored series needs a distinct slot 0, 1 or 2");
+  }
+  const walk = (sections: Section[], path: string) =>
+    sections.forEach((s, i) => {
+      const where = `${path}[${i}]`;
+      if (!TYPES.has(s.type)) {
+        errors.push(`${where}: unknown type ${s.type}`);
+      }
+      for (const k of [
+        ...(s.series ?? []).map((r) => r.key),
+        ...(s.rows ?? []).map((r) => r.key),
+      ]) {
+        if (k !== undefined && !data.series[k]) {
+          errors.push(`${where}: series key ${k} is not declared`);
+        }
+      }
+      if (s.items) {
+        walk(s.items, `${where}.items`);
+      }
+    });
+  walk(data.sections, "sections");
+  return errors;
+}
+
+export function render(data: ReportData, template: string): string {
+  const errors = check(data);
+  if (errors.length) {
+    throw new Error(errors.join("\n"));
+  }
+  // Inside <script>, a literal "</" would close the element early.
+  return template.replace("__REPORT_DATA__", () => JSON.stringify(data).replaceAll("</", "<\\/"));
+}
+
+if (import.meta.main) {
+  const [input, output] = process.argv.slice(2);
+  if (!input || !output) {
+    throw new Error("usage: bun render-report.ts <data.json> <out.html>");
+  }
+  const template = readFileSync(
+    join(import.meta.dir, "..", "assets", "report-template.html"),
+    "utf8",
+  );
+  writeFileSync(output, render(JSON.parse(readFileSync(input, "utf8")), template));
+  console.log(output);
+}