@design-parity/report-html 0.1.0 → 0.1.2

package/README.md

@@ -43,6 +43,23 @@ Reference and candidate PNGs are read from disk via `repoRoot + Image.uri`
 (the same resolution the diff engine uses) and inlined. A side with no images
 (a semantic/token-only verdict) degrades cleanly — the findings still render.
 
+## Branch landing page
+
+`report.html` is per-component; `renderIndex` stitches a whole run together so
+the published artifact branch has an entry point instead of a wall of
+machine-named directories. Given the run's components it returns
+`{ readme, html }`:
+
+- `README.md` — what GitHub renders when you open the branch: a "generated, do
+  not edit" banner, the source commit, and a table linking each component to
+  its report.
+- `index.html` — a self-contained landing page for GitHub Pages / local view.
+
+Because GitHub serves a linked `.html` blob as source (the slider JS won't run),
+pass the published `repoSlug` + `branch` to wrap the README's report links
+through `htmlpreview.github.io` so they render on click; without them the links
+are relative. Deterministic, same as `renderHtmlReport`.
+
 ## CLI
 
 A small demo CLI ships as `design-parity-report`:

package/dist/index-page.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `renderIndex` — the **branch landing page**.
+ *
+ * The orchestrator writes one self-contained `report.html` per component into
+ * its own subdir. That's great once you know which file to open, but a human
+ * landing on the published branch (`design-parity/main`) sees only a list of
+ * machine-named directories with no entry point. This stitches them together:
+ *
+ * - `README.md` — what GitHub renders when you open the branch: a "generated,
+ *   do not edit" banner, the source commit, and a table linking each component
+ *   to its report.
+ * - `index.html` — a self-contained landing page for GitHub Pages / local view.
+ *
+ * GitHub serves a linked `.html` blob as source (it won't render the slider
+ * JS), so when the published `repoSlug` + `branch` are known the README links
+ * are wrapped through htmlpreview.github.io so they render on click; otherwise
+ * they fall back to relative links (which still navigate to the file).
+ *
+ * Output is deterministic: same input → byte-identical strings. No timestamps,
+ * random ids, or `Date.now()` — entries render in the order given.
+ */
+import type { VerdictStatus } from "@design-parity/core";
+/** A component status as shown on the landing page (verdict or non-verdict). */
+export type IndexStatus = VerdictStatus | "skipped" | "error";
+export interface IndexEntry {
+    /** Component id, e.g. `ui/DeviceBody.kt#DeviceBodyPreview`. */
+    code: string;
+    /** Verdict status, or why the component produced no verdict. */
+    status: IndexStatus;
+    /** Path to the component's `report.html`, relative to the branch root. */
+    reportPath?: string;
+}
+export interface IndexInput {
+    /** Page title (default `Design parity`). */
+    title?: string;
+    /** Candidate commit the reports were rendered from, shown if provided. */
+    sourceCommit?: string;
+    /**
+     * `owner/repo` the index is published to. With {@link branch}, README report
+     * links are wrapped through htmlpreview.github.io so they render on click.
+     */
+    repoSlug?: string;
+    /** Branch the index is published to (e.g. `design-parity/main`). */
+    branch?: string;
+    /** Optional overview image at the branch root, e.g. `candidates.bundle.png`. */
+    bundleImage?: string;
+    /** One row per component, in display order. */
+    entries: IndexEntry[];
+}
+/** Render the branch's `README.md`. */
+export declare function renderReadme(input: IndexInput): string;
+/** Render the branch's self-contained `index.html` landing page. */
+export declare function renderIndexHtml(input: IndexInput): string;
+/** Render both branch landing artifacts from one input. */
+export declare function renderIndex(input: IndexInput): {
+    readme: string;
+    html: string;
+};
+//# sourceMappingURL=index-page.d.ts.map

package/dist/index-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-page.d.ts","sourceRoot":"","sources":["../src/index-page.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIzD,gFAAgF;AAChF,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,SAAS,GAAG,OAAO,CAAC;AAE9D,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,MAAM,EAAE,WAAW,CAAC;IACpB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAoCD,uCAAuC;AACvC,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAiCtD;AAgCD,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAmCzD;AAED,2DAA2D;AAC3D,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAE/E"}

package/dist/index-page.js

@@ -0,0 +1,122 @@
+import { escapeHtml } from "./html.js";
+const STATUS_TEXT = {
+    pass: "Pass",
+    warn: "Warn",
+    fail: "Fail",
+    skipped: "Skipped",
+    error: "Error",
+};
+const STATUS_EMOJI = {
+    pass: "✅",
+    warn: "⚠️",
+    fail: "❌",
+    skipped: "⏭️",
+    error: "🚫",
+};
+function short(sha) {
+    return /^[0-9a-f]{7,40}$/i.test(sha) ? sha.slice(0, 7) : sha;
+}
+/** Escape a cell for a GitHub-flavored markdown table. */
+function mdCell(value) {
+    return value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
+}
+/** README link target for a report, htmlpreview-wrapped when the repo is known. */
+function readmeReportHref(reportPath, input) {
+    if (input.repoSlug && input.branch) {
+        const blob = `https://github.com/${input.repoSlug}/blob/${input.branch}/${reportPath}`;
+        return `https://htmlpreview.github.io/?${blob}`;
+    }
+    return `./${reportPath}`;
+}
+/** Render the branch's `README.md`. */
+export function renderReadme(input) {
+    const title = input.title ?? "Design parity";
+    const lines = [`# ${title}`, ""];
+    const commit = input.sourceCommit
+        ? ` Rendered from \`${short(input.sourceCommit)}\` — see [\`SOURCE_COMMIT\`](./SOURCE_COMMIT).`
+        : " Rendered from the commit in [`SOURCE_COMMIT`](./SOURCE_COMMIT).";
+    lines.push(`> **Generated by [design-parity](https://github.com/yschimke/design-parity) — do not edit by hand.**`, `> This branch is rebuilt on every run.${commit}`, "");
+    if (input.bundleImage) {
+        lines.push(`![Candidate overview](./${input.bundleImage})`, "");
+    }
+    lines.push("| Component | Status | Report |", "| --- | --- | --- |");
+    for (const e of input.entries) {
+        const status = `${STATUS_EMOJI[e.status]} ${STATUS_TEXT[e.status]}`;
+        const report = e.reportPath
+            ? `[report](${readmeReportHref(e.reportPath, input)})`
+            : "—";
+        lines.push(`| ${mdCell(e.code)} | ${status} | ${report} |`);
+    }
+    lines.push("");
+    lines.push("Each report is a self-contained HTML page — open one in a browser to view the", "reference / candidate / diff comparison. GitHub shows a linked `.html` as", "source; use the rendered links above, GitHub Pages, or download and open it.", "");
+    return lines.join("\n");
+}
+const STYLE = `:root{color-scheme:light dark}
+*{box-sizing:border-box}
+body{margin:0;font:14px/1.5 system-ui,-apple-system,Segoe UI,Roboto,sans-serif;background:#0f0f14;color:#e7e7ef}
+a{color:#9db8ff}
+header.page{padding:24px 28px;border-bottom:1px solid #26262f}
+header.page h1{margin:0 0 6px;font-size:18px}
+.subtitle{color:#9a9ab0;font-size:13px}
+.subtitle code{background:#222230;padding:1px 6px;border-radius:5px}
+main{padding:20px 28px;max-width:900px}
+.overview{max-width:100%;border:1px solid #26262f;border-radius:10px;margin-bottom:20px}
+table{border-collapse:collapse;width:100%}
+th,td{text-align:left;padding:8px 12px;border-bottom:1px solid #26262f;font-size:13px}
+th{color:#9a9ab0;font-weight:600;text-transform:uppercase;letter-spacing:.04em;font-size:11px}
+td.code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace}
+.status{display:inline-block;padding:2px 10px;border-radius:999px;font-weight:600;font-size:12px}
+.status-pass{background:#16351f;color:#7ee29a}
+.status-warn{background:#3a3115;color:#e8c66b}
+.status-fail{background:#3a1820;color:#f08a9c}
+.status-skipped{background:#222230;color:#b8b8cc}
+.status-error{background:#3a1820;color:#f08a9c}
+.muted{color:#666}`;
+function rowMarkup(e) {
+    const status = `<span class="status status-${e.status}">${STATUS_TEXT[e.status]}</span>`;
+    const report = e.reportPath
+        ? `<a href="./${escapeHtml(e.reportPath)}">report</a>`
+        : `<span class="muted">—</span>`;
+    return `<tr><td class="code">${escapeHtml(e.code)}</td><td>${status}</td><td>${report}</td></tr>`;
+}
+/** Render the branch's self-contained `index.html` landing page. */
+export function renderIndexHtml(input) {
+    const title = input.title ?? "Design parity";
+    const commit = input.sourceCommit
+        ? `Rendered from <code>${escapeHtml(short(input.sourceCommit))}</code>`
+        : "Generated by design-parity";
+    const overview = input.bundleImage
+        ? `<img class="overview" src="./${escapeHtml(input.bundleImage)}" alt="Candidate overview" />`
+        : "";
+    const rows = input.entries.map(rowMarkup).join("\n");
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${escapeHtml(title)}</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<header class="page">
+  <h1>${escapeHtml(title)}</h1>
+  <div class="subtitle">${commit} — generated by design-parity, do not edit by hand.</div>
+</header>
+<main>
+${overview}
+<table>
+<thead><tr><th>Component</th><th>Status</th><th>Report</th></tr></thead>
+<tbody>
+${rows}
+</tbody>
+</table>
+</main>
+</body>
+</html>
+`;
+}
+/** Render both branch landing artifacts from one input. */
+export function renderIndex(input) {
+    return { readme: renderReadme(input), html: renderIndexHtml(input) };
+}
+//# sourceMappingURL=index-page.js.map

package/dist/index-page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-page.js","sourceRoot":"","sources":["../src/index-page.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -14,4 +14,6 @@ export { pairVariants } from "./variants.js";
 export type { Variant } from "./variants.js";
 export { groupFindings, tokenDelta, SECTIONS } from "./findings.js";
 export type { FindingSection, GroupedSection, TokenDelta } from "./findings.js";
+export { renderIndex, renderReadme, renderIndexHtml } from "./index-page.js";
+export type { IndexEntry, IndexInput, IndexStatus } from "./index-page.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,YAAY,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACpE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,YAAY,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACpE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC7E,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -11,4 +11,5 @@
 export { renderHtmlReport } from "./render.js";
 export { pairVariants } from "./variants.js";
 export { groupFindings, tokenDelta, SECTIONS } from "./findings.js";
+export { renderIndex, renderReadme, renderIndexHtml } from "./index-page.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEpE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design-parity/report-html",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Self-contained HTML comparison page per parity run: reference | candidate | diff side by side with the verdict findings, inlined to one offline .html file (data-URI PNGs + inline CSS/JS, no external assets).",
   "license": "Apache-2.0",
   "type": "module",
@@ -20,7 +20,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@design-parity/core": "^0.1.0"
+    "@design-parity/core": "^0.1.2"
   },
   "repository": {
     "type": "git",