@mmerterden/multi-agent-toolkit-mcp 3.13.1 → 3.15.0

package/tools/design-check/index.js

@@ -9,6 +9,7 @@
  *   design_scenario_inventory - every state driver the mock build exposes (audit target set)
  *   design_mock_launch    - launch the app in mock mode (UserDefaults launch arg / intent extra)
  *   design_ui_geometry    - flat element bounding boxes of the current screen
+ *   design_component_variants - design node -> component set -> variants, from caller-supplied Figma data
  *   design_visual_compare - normalize + pixel/geometry/color/type diff vs a Figma render
  *   design_report         - render HTML (+ optional PDF) from a report object
  */
@@ -17,10 +18,11 @@ import { join } from "path";
 import { existsSync, mkdirSync } from "fs";
 
 import { detectMock } from "./mock-detect.js";
-import { inventoryScenarios } from "./scenario-inventory.js";
+import { inventoryScenarios, TARGET_SCHEMA } from "./scenario-inventory.js";
 import { flattenIosAxTree, flattenAndroidUiXml, flattenIdbDescribeAll } from "./geometry.js";
 import { compareVisual } from "./visual-compare.js";
-import { writeReport } from "./report.js";
+import { walkComponents } from "./component-walk.js";
+import { writeReport, writeRollup } from "./report.js";
 
 // Single-quote for POSIX sh; the swift dumper path is interpolated into a shell
 // command via ctx.run. Kept local so this module stays self-contained.
@@ -40,14 +42,16 @@ export const DESIGN_TOOLS = [
   },
   {
     name: "design_scenario_inventory",
-    description: "Enumerate every state driver a mock-mode build exposes, so a design audit has a countable target set instead of walking the UI until it feels done. Returns { targets:[{id,kind,label,screen,driver,cost,evidence}], plan[], relaunchCount, groups[], byKind, byCost, targetCount, ignored[], truncated }. Kinds: launch-arg (relaunch flags / boolean intent extras), scenario-case (cases of *Scenario / *Outcome / *MockCase enums), code-scenario (short uppercase codes typed at an entry field, read only from debug/mock code), fixture (MockData JSON), deep-link (custom-scheme URLs). Each target carries a cost ('relaunch' vs 'in-app') and `plan` batches them so ONE relaunch serves every in-app target on that screen - relaunchCount, not targetCount, is the real cost of full coverage. Signal-based and generic; every target has file+line evidence. Run right after design_mock_detect; feed targets + truncated into the design_report coverage gate.",
-    inputSchema: { type: "object", properties: {
+    description: "Enumerate every state driver a mock-mode build exposes, so a design audit has a countable target set instead of walking the UI until it feels done. Returns { targets:[{id,kind,label,screen,driver,cost,evidence}], plan[], relaunchCount, groups[], byKind, byCost, targetCount, ignored[], acceptedSelectors[], rejectedSelectors[], truncated }. Kinds: launch-arg (relaunch flags / boolean intent extras), scenario-case (cases of *Scenario / *Outcome / *MockCase enums - counted only when the type is declared in debug-only code (#if DEBUG, an Android debug/mock source set), referenced only from debug/mock code, or read from a runtime key; a production type that merely shares the suffix is listed in rejectedSelectors with the production reference that disqualified it), code-scenario (short uppercase codes typed at an entry field, read only from debug/mock code), prefix-code, fixture (MockData JSON), deep-link (custom-scheme URLs). Each target carries a cost ('relaunch' vs 'in-app') and `plan` batches them so ONE relaunch serves every in-app target on that screen - relaunchCount, not targetCount, is the real cost of full coverage. Pass targets_file and/or targets[] to supply the target set from an external catalog instead: source scanning is skipped and plan, groups, relaunchCount and the coverage gate work unchanged. Run right after design_mock_detect; feed targets + truncated into the design_report coverage gate.",
+    inputSchema: { type: "object", additionalProperties: false, properties: {
       repo_path: { type: "string", description: "Absolute path to the repo or module to scan" },
       platform: { type: "string", enum: ["ios", "android"], description: "Optional; auto-detected if omitted" },
       extra_launch_args: { type: "array", items: { type: "string" }, description: "Project-specific launch args no signal reveals" },
       extra_targets: { type: "array", items: { type: "object" }, description: "Config-declared targets [{id,kind,label,screen,driver}]" },
       ignore_targets: { type: "array", items: { type: "string" }, description: "Target ids to drop entirely (dead drivers, states retired in code). Returned in `ignored` - unlike a skip these never reach the coverage gate, so prefer a skip with a reason." },
-      summary: { type: "boolean", description: "Return counts, groups and plan without the per-target list. The full payload measured 71k characters for a 109-target module and exceeded the tool-result cap on every run; plan[].targetIds and groups[].ids still carry every id, so a run can be driven from the summary and fetch labels + file/line evidence later with summary:false." },
+      targets_file: { type: "string", description: "Path to a JSON target catalog: a bare array of targets, or { version: 1, platform?, description?, targets: [...] }. Each target has the shape this tool returns ({ id, driver:{type,...}, kind?, label?, screen?, cost?, evidence? }); unknown fields are refused. When given, source scanning is skipped." },
+      targets: { type: "array", items: TARGET_SCHEMA, description: "Inline target catalog, same shape as targets_file entries. When given, source scanning is skipped. Combined with targets_file when both are passed; ids must be unique across the two." },
+      summary: { type: "boolean", description: "Return counts, groups and plan without the per-target list, for modules whose full payload exceeds a host's tool-result cap. plan[].targetIds and groups[].ids still carry every id, so a run can be driven from the summary and fetch labels + file/line evidence later with summary:false." },
     }, required: ["repo_path"] },
   },
   {
@@ -72,6 +76,29 @@ export const DESIGN_TOOLS = [
       max_depth: { type: "number", description: "iOS AX tree depth (default 12)" },
     }, required: ["platform"] },
   },
+  {
+    name: "design_component_variants",
+    description: "Resolve design nodes to the component set they belong to and list that set's variants, so a live component is compared against its own variant instead of a screen frame whose mock content (5 rows in the design, 3 in the app) shifts every container. Works only on Figma data the caller already fetched - this server never contacts Figma: per file, a REST GET /v1/files/:key/nodes response (`nodes`) or MCP get_metadata XML (`metadata`, parent-relative x/y), plus optionally the library's GET /v1/files/:key/component_sets listing, which locates a set that lives in another file. Walks instance -> main component -> component set -> variant children (names like 'State=Error, Size=L'). Returns { components:[{ requested, resolvedVia, component, componentSet:{nodeId,name,fileKey}, codeConnect, properties, variants:[{ name, nodeId, fileKey, properties, frame:{w,h}, spec[], render:{fileKey,nodeId,format,scale}, image }], matches[], unmatchedStates[] }], needs[], rendersNeeded[], unresolved[] }. needs[] names nodes to fetch before the walk can finish; rendersNeeded[] names the variant renders to download. Per variant, pass spec as figma_spec, frame as figma_frame and the render as figma_png to design_visual_compare, with the live component's bounds as live_region; pass componentFindingFields-shaped `component` so design_report shows the main component and variant thumbnails. States (e.g. inventory targets) are matched to variants by name; an ambiguous or distant match is listed in unmatchedStates, never assigned.",
+    inputSchema: { type: "object", additionalProperties: false, properties: {
+      sources: { type: "array", minItems: 1, description: "Figma data per file: [{ file_key, nodes? (REST /v1/files/:key/nodes response object), metadata? (MCP get_metadata XML string) }]. List the audited screen's file first.", items: {
+        type: "object", additionalProperties: false, required: ["file_key"], properties: {
+          file_key: { type: "string", minLength: 1 },
+          nodes: { type: "object" },
+          metadata: { type: "string" },
+        } } },
+      component_sets: { type: "array", description: "The meta.component_sets array of a library's GET /v1/files/:key/component_sets response: [{ key, file_key, node_id, name, ... }]", items: {
+        type: "object", required: ["file_key", "node_id"], properties: { key: { type: "string" }, file_key: { type: "string" }, node_id: { type: "string" }, name: { type: "string" } } } },
+      node_ids: { type: "array", items: { type: "string" }, description: "Nodes to resolve (instances, components or sets), as a node id or as fileKey/nodeId to pick one of several sources that use the same id. Default: the top-level nodes of the first source." },
+      code_connect: { type: "array", description: "Code Connect mapping: [{ url | file_key + node_id, component, source? }]. The component a node maps to names the result.", items: {
+        type: "object", additionalProperties: false, required: ["component"], properties: {
+          url: { type: "string" }, file_key: { type: "string" }, node_id: { type: "string" },
+          component: { type: "string", minLength: 1 }, source: { type: "string" },
+        } } },
+      states: { type: "array", description: "Audited states to match to variants by name: [{ id, label?, screen? }] (inventory targets reduced to these fields).", items: {
+        type: "object", additionalProperties: false, required: ["id"], properties: { id: { type: "string" }, label: { type: "string" }, screen: { type: "string" } } } },
+      renders: { type: "object", description: "Variant renders already downloaded: { '<nodeId>' or '<fileKey>/<nodeId>': '/abs/path.png' }. Each becomes the variant's image." },
+    }, required: ["sources"] },
+  },
   {
     name: "design_visual_compare",
     description: "Compare a Figma render PNG against a live device screenshot WITHOUT failing on size mismatch. RESPONSIVE BY DEFAULT: because the device and the Figma frame are usually different widths (e.g. 402pt vs 375pt), raw width/height deltas are meaningless - so it measures what a designer actually specs, in POINTS: per-element edge insets (left/right), the GAPS between consecutive elements (text <-> divider spacing), vertical placement, font size/family and text colour (sampled from the text ink, not the box average). Height is still reported but flagged advisory, since a content-hugging container changes height whenever the fixture differs; advisories never decide pass/fail. Pass responsive:false for the legacy absolute-delta behaviour. Writes figma/live/diff/overlay/side-by-side PNGs. Returns findings + image paths. For a BOTTOM SHEET / modal / partial overlay pass live_region (the sheet's bounds from design_ui_geometry): the Figma frame covers only the sheet while the capture is the whole screen, and stretching one onto the other misplaces every element inside it. Add expected_region to have the sheet's own edge insets reported as findings - a design showing a sheet flush to the edges is not satisfied by one floating inset from them.",
@@ -96,6 +123,11 @@ export const DESIGN_TOOLS = [
       relations: { type: "boolean", description: "Default true. Emit content-independent relational checks - centred-in-frame, left/right margin symmetry, shared centre lines (is the close button aligned with the title), and icon/control sizing. These are what actually answer 'is it built 1:1', because absolute Y moves with the mock content above it." },
       responsive: { type: "boolean", description: "Default true. Measure edge insets + inter-element gaps in points instead of raw width/height in the stretched compare space. Requires figma_frame + live_screen. Turn off only to get legacy absolute deltas." },
       verify_font_family: { type: "boolean", description: "Emit an advisory per text element naming the design's font family (not readable from the device, so it is a code-review item, never a measured delta). Default false." },
+      component: { type: "object", additionalProperties: false, description: "The component this capture region belongs to, from design_component_variants: { component, componentNode, componentFileKey, componentVariant?, componentVariants:[{name,node,fileKey,image}] }. Stamped onto every finding that names no component of its own, so design_report renders the main component link and the variant thumbnails.", properties: {
+        component: { type: "string" }, componentNode: { type: "string" }, componentFileKey: { type: "string" }, componentVariant: { type: "string" },
+        componentVariants: { type: "array", items: { type: "object", additionalProperties: false, required: ["name"], properties: {
+          name: { type: "string" }, node: { type: "string" }, fileKey: { type: "string" }, image: { type: "string" } } } },
+      } },
       content_cardinality: { type: "boolean", description: "Demote the geometry findings a fixture-count difference explains (5 design rows vs 3 live rows shifts every container height and everything below it). Default true. Demoted findings are NOT removed - they become advisory with a shared root cause and are reported in `contentCardinality.demoted`. Copy, colour, typography and tap-target findings, and anything above the first differing group, are never demoted. Pass false to see the raw findings." },
       color_tolerance: { type: "number", description: "Ignore color ΔE ≤ this (default 3)" },
       perceptual_precision: { type: "number", description: "pixelmatch threshold 0..1 (default 0.1)" },
@@ -104,11 +136,18 @@ export const DESIGN_TOOLS = [
   },
   {
     name: "design_report",
-    description: "Render a design-audit report object into a self-contained HTML file (base64 images, CSS-positioned annotations over the live capture) and optionally PDF. Enforces a COVERAGE GATE: pass report.coverage = { targets, covered, skipped:[{id,group,reason}], floor? } and every target must be audited or skipped WITH a reason - otherwise the returned object carries coverage.gate='fail' + coverageError and the report renders a red gate banner. Human-facing wording comes from report.lang ('en' default, 'tr' built in) and per-key report.labels overrides. Returns written file paths + the coverage verdict. Confluence upload is handled by the caller.",
+    description: "Render a design-audit report object into a self-contained HTML file (base64 images, CSS-positioned annotations over the live capture) and optionally PDF. Enforces a COVERAGE GATE: pass report.coverage = { targets, covered, skipped:[{id,group,reason}], floor? } and every target must be audited or skipped WITH a reason - otherwise the returned object carries coverage.gate='fail' + coverageError and the report renders a red gate banner. Human-facing wording comes from report.lang ('en' default, 'tr' built in) and per-key report.labels overrides. Returns written file paths + the coverage verdict. ROLL-UP MODE: pass modules:[{ module, report | report_file, href? }] and a header-only report ({ project, platform, timestamp, lang, labels }) to render index.html with one row per module (coverage, gate, deviations, link to the module's own report, rendered into <out_dir>/<module>/ unless href points at an existing one). Each module runs through the same coverage gate, and any module that fails it - or declares no coverage - makes the roll-up gate fail; the result carries rollup:{ gate, modules[], failedModules[] }. Confluence upload is handled by the caller.",
     inputSchema: { type: "object", properties: {
       report: { type: "object", description: "{ project, module, platform, figmaUrl, timestamp, lang, labels, coverage:{targets,covered,skipped:[{id,group,reason}],floor}, variants:[{name, figmaNodeId, perceptualPct, passed, compareSize, images:{figma,live,diff,overlay,sideBySide}, findings:[...], fixPrompt, componentRefs:[{name,image}] }] }" },
       out_dir: { type: "string", description: "Directory to write report into" },
       formats: { type: "array", items: { type: "string", enum: ["html", "pdf", "confluence"] }, description: "Default ['html']" },
+      modules: { type: "array", minItems: 1, description: "Roll-up mode: the module reports to summarise. `report` then carries only the roll-up header.", items: {
+        type: "object", additionalProperties: false, required: ["module"], properties: {
+          module: { type: "string", minLength: 1 },
+          report: { type: "object", description: "The module's report object, same shape as a single design_report call" },
+          report_file: { type: "string", description: "Path to a JSON file holding the module's report object" },
+          href: { type: "string", description: "Link to an already-rendered module report; when omitted one is rendered and linked" },
+        } } },
     }, required: ["report", "out_dir"] },
   },
 ];
@@ -135,11 +174,16 @@ export async function handleDesign(name, args, ctx) {
       return JSON.stringify(detectMock({ repoPath: args.repo_path, platform: args.platform, extraKeys: args.extra_keys || [] }), null, 2);
 
     case "design_scenario_inventory":
-      return JSON.stringify(inventoryScenarios({
-        repoPath: args.repo_path, platform: args.platform,
-        extraLaunchArgs: args.extra_launch_args || [], extraTargets: args.extra_targets || [],
-        ignoreTargets: args.ignore_targets || [], summary: args.summary === true,
-      }), null, 2);
+      try {
+        return JSON.stringify(inventoryScenarios({
+          repoPath: args.repo_path, platform: args.platform,
+          extraLaunchArgs: args.extra_launch_args || [], extraTargets: args.extra_targets || [],
+          ignoreTargets: args.ignore_targets || [], summary: args.summary === true,
+          targets: args.targets ?? null, targetsFile: args.targets_file ?? null,
+        }), null, 2);
+      } catch (err) {
+        return `ERROR: ${err.message}`;
+      }
 
     case "design_mock_launch": {
       if (args.platform === "ios") {
@@ -188,6 +232,20 @@ export async function handleDesign(name, args, ctx) {
       return JSON.stringify({ platform: "android", unit: "pixels", screen: sm ? { w: +sm[1], h: +sm[2] } : null, count: elements.length, elements }, null, 2);
     }
 
+    case "design_component_variants":
+      try {
+        return JSON.stringify(walkComponents({
+          sources: args.sources.map((src) => ({ fileKey: src.file_key, nodes: src.nodes, metadata: src.metadata })),
+          componentSets: args.component_sets || null,
+          nodeIds: args.node_ids || null,
+          codeConnect: (args.code_connect || []).map((e) => ({ url: e.url, fileKey: e.file_key, nodeId: e.node_id, component: e.component, source: e.source })),
+          states: args.states || [],
+          renders: args.renders || {},
+        }), null, 2);
+      } catch (err) {
+        return `ERROR: ${err.message}`;
+      }
+
     case "design_visual_compare": {
       ensureDir(args.out_dir);
       const res = await compareVisual({
@@ -204,6 +262,7 @@ export async function handleDesign(name, args, ctx) {
         edges: args.edges !== false,
         designCopy: args.design_copy || null,
         verifyFontFamily: args.verify_font_family === true,
+        component: args.component || null,
         perceptualPrecision: args.perceptual_precision, maxDiffPct: args.max_diff_pct,
       });
       return JSON.stringify(res, null, 2);
@@ -211,6 +270,14 @@ export async function handleDesign(name, args, ctx) {
 
     case "design_report": {
       ensureDir(args.out_dir);
+      if (args.modules) {
+        try {
+          const out = await writeRollup({ rollup: args.report, modules: args.modules, outDir: args.out_dir, formats: args.formats || ["html"] });
+          return JSON.stringify(out, null, 2);
+        } catch (err) {
+          return `ERROR: ${err.message}`;
+        }
+      }
       const out = await writeReport({ report: args.report, outDir: args.out_dir, formats: args.formats || ["html"] });
       return JSON.stringify(out, null, 2);
     }

package/tools/design-check/report.js

@@ -20,7 +20,7 @@
  * single natural language.
  */
 
-import { readFileSync, writeFileSync, existsSync } from "fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
 import { join } from "path";
 
 // Single-quote a value for POSIX sh: pdfPath/htmlPath derive from the caller's
@@ -47,6 +47,7 @@ const LABEL_PACKS = {
     variantsWord: "variants",
     toggleHint: "(show/hide · click → Figma)",
     noPreview: "No preview captured.",
+    variantNotRendered: "not rendered",
     fixPromptTitle: "Developer prompt (paste into an agent)",
     figmaCol: "FIGMA · expected", liveCol: "LIVE · actual",
     coverageTitle: "Coverage",
@@ -59,6 +60,12 @@ const LABEL_PACKS = {
     coverageUndeclared: "target undeclared by the run",
     coverageTruncated: "The scenario inventory hit its cap, so the target set is incomplete and this percentage is measured against a partial denominator.",
     coverageBelowFloor: "below the required coverage floor",
+    rollupTitle: "Design Check Roll-up",
+    thModule: "Module", thCoverage: "Coverage", thGate: "Gate", thReport: "Report",
+    rollupGatePass: "ROLL-UP GATE PASSED", rollupGateFail: "ROLL-UP GATE FAILED",
+    rollupGateHint: "every module must pass its own coverage gate",
+    rollupNoCoverage: "no coverage declared",
+    rollupOpen: "open",
     footerNote: "multi-agent-toolkit-mcp design-check · copy is compared against the design's source-of-truth UX writing, not a stale frame render; localization differences are not counted as defects.",
   },
   tr: {
@@ -78,6 +85,7 @@ const LABEL_PACKS = {
     variantsWord: "varyant",
     toggleHint: "(göster/gizle · tıkla → Figma)",
     noPreview: "Önizleme çekilmedi.",
+    variantNotRendered: "render alınmadı",
     fixPromptTitle: "Geliştirme promptu (ajana yapıştır)",
     figmaCol: "FIGMA · olması gereken", liveCol: "CANLI · mevcut",
     coverageTitle: "Kapsam",
@@ -90,6 +98,12 @@ const LABEL_PACKS = {
     coverageUndeclared: "hedef koşuda hiç bildirilmedi",
     coverageTruncated: "Senaryo envanteri üst sınıra takıldı; hedef kümesi eksik ve bu yüzde kısmi bir payda üzerinden hesaplandı.",
     coverageBelowFloor: "istenen kapsam tabanının altında",
+    rollupTitle: "Design Check Özeti",
+    thModule: "Modül", thCoverage: "Kapsam", thGate: "Geçit", thReport: "Rapor",
+    rollupGatePass: "ÖZET GEÇİDİ GEÇTİ", rollupGateFail: "ÖZET GEÇİDİ BAŞARISIZ",
+    rollupGateHint: "her modül kendi kapsam geçidini geçmeli",
+    rollupNoCoverage: "kapsam bildirilmedi",
+    rollupOpen: "aç",
     footerNote: "multi-agent-toolkit-mcp design-check · metin karşılaştırması tasarımın kaynak-doğru UX-writing'ine göre yapılır (bayat frame render'ına değil); localization farkları hata sayılmaz.",
   },
 };
@@ -117,16 +131,16 @@ function figmaNodeUrl(fileKey, node) {
 /**
  * The file a finding's component actually lives in.
  *
- * Components are NOT all in the audited screen's file. Observed on a real module:
+ * Components are NOT all in the audited screen's file; a design system spreads
+ * them over library files:
  *
- *   CardsFlightCardsCheckinCheckinStart -> 9ipBvrtsq9HlQ175B9k0wx
- *   CheckinBoardingPassLayout           -> ps4xrJzhn7WNbfkZs895Bi
+ *   ProductCardHeader  -> AAAAfileKeyA
+ *   ProductDetailLayout -> BBBBfileKeyB
  *
- * Every component link was built from the report-level `figmaFileKey`, so a
- * component from a second library file got a URL into the wrong file. That link
- * still opens - it just resolves to nothing - which is worse than no link,
- * because the reader concludes the node was deleted. Prefer the per-finding key;
- * fall back to the report-level one, which is correct for the same-file case.
+ * A link built from the report-level `figmaFileKey` for a component in another
+ * file still opens but resolves to nothing, which reads as "the node was
+ * deleted" rather than "the link is wrong". So the per-finding key wins, and the
+ * report-level key is the fallback for the same-file case.
  */
 function componentFileKey(finding, reportFileKey) {
   return (finding && finding.componentFileKey) || reportFileKey;
@@ -323,7 +337,7 @@ function componentsBlock(v, fileKey, L) {
     const compKey = componentFileKey(f, fileKey);
     const url = figmaNodeUrl(compKey, f.componentNode);
     const thumbs = variants.length
-      ? `<div class="cvgrid">${variants.map((cv) => `<figure>${cv.node && url ? `<a href="${esc(figmaNodeUrl(cv.fileKey || compKey, cv.node))}" target="_blank">` : ""}<img src="${dataUri(cv.image)}" alt="">${cv.node && url ? "</a>" : ""}<figcaption>${esc(cv.name)}</figcaption></figure>`).join("")}</div>`
+      ? `<div class="cvgrid">${variants.map((cv) => { const src = dataUri(cv.image); return `<figure>${cv.node && url ? `<a href="${esc(figmaNodeUrl(cv.fileKey || compKey, cv.node))}" target="_blank">` : ""}${src ? `<img src="${src}" alt="">` : `<div class="cvmissing">${esc(L.variantNotRendered)}</div>`}${cv.node && url ? "</a>" : ""}<figcaption>${esc(cv.name)}</figcaption></figure>`; }).join("")}</div>`
       : `<p class="cvnote">${esc(L.noPreview)}</p>`;
     const name = url ? `<a href="${esc(url)}" target="_blank">${esc(f.component)} ↗</a>` : `<b>${esc(f.component)}</b>`;
     return `<details class="cvcomp"><summary>◈ ${esc(L.mainComponent)}: ${name}${variants.length ? ` · ${variants.length} ${esc(L.variantsWord)}` : ""} <span class="cvhint">${esc(L.toggleHint)}</span></summary>${thumbs}</details>`;
@@ -514,6 +528,7 @@ code{background:#eee;padding:1px 5px;border-radius:4px;font-size:12px}
 .cvgrid figure{margin:0;text-align:center}.cvgrid img{height:150px;border:1px solid var(--line);border-radius:6px;display:block}
 .cvgrid figcaption{font-size:11px;color:var(--muted);margin-top:4px;max-width:160px}
 .cvnote{color:var(--muted);font-size:12px;margin:10px 0 2px}
+.cvmissing{height:150px;width:110px;border:1px dashed var(--line);border-radius:6px;display:flex;align-items:center;justify-content:center;color:var(--muted);font-size:11px}
 a{color:#0A66C2;text-decoration:none}a:hover{text-decoration:underline}
 .coverage{border-radius:12px;padding:20px;margin-bottom:28px}
 .covfail{border:2px solid #cf222e;background:#fff5f5}.covpass{border:1px solid #0A7D33;background:#f6fff8}
@@ -604,3 +619,130 @@ export async function writeReport({ report, outDir, formats = ["html"] }) {
   }
   return out;
 }
+
+/**
+ * Roll-up over several module reports: one row per module with its coverage,
+ * deviations and a link to its own report.
+ *
+ * Each module runs through the same coverageVerdict as a single report, and the
+ * roll-up gate is the conjunction: any module that fails - or declares no
+ * coverage, which leaves nothing to verify - makes the roll-up fail. A green
+ * roll-up therefore never averages a failing module away behind passing ones.
+ *
+ * modules: [{ module, report? (report object), report_file? (JSON of one),
+ *             href? (an existing sub-report; otherwise one is rendered into
+ *             <outDir>/<slug>/report.html and linked relatively) }]
+ */
+const deviationsOf = (report) => (report.variants || []).reduce((n, v) =>
+  n + (v.findings || []).filter((f) => f.status !== "verified" && !f.advisory).length, 0);
+const advisoriesOf = (report) => (report.variants || []).reduce((n, v) =>
+  n + (v.findings || []).filter((f) => f.status !== "verified" && f.advisory).length, 0);
+const slugOf = (s) => String(s || "").replace(/[^A-Za-z0-9]+/g, "-").replace(/^-|-$/g, "").toLowerCase() || "module";
+
+function loadModuleReport(entry, i) {
+  if (!entry || typeof entry.module !== "string" || !entry.module) throw new Error(`modules[${i}].module is required`);
+  if (entry.report && typeof entry.report === "object") return entry.report;
+  if (entry.report_file) {
+    let raw;
+    try { raw = readFileSync(entry.report_file, "utf-8"); } catch (err) { throw new Error(`modules[${i}].report_file unreadable: ${entry.report_file} (${err.code || err.message})`); }
+    try { return JSON.parse(raw); } catch (err) { throw new Error(`modules[${i}].report_file is not valid JSON: ${err.message}`); }
+  }
+  throw new Error(`modules[${i}] needs report or report_file`);
+}
+
+export function rollupVerdict(modules) {
+  const rows = modules.map(({ module, report, href }) => {
+    const cv = coverageVerdict(report.coverage, (report.variants || []).length);
+    const row = {
+      module, href,
+      gate: cv ? cv.gate : "fail",
+      audited: cv ? cv.audited : 0,
+      target: cv ? cv.target : 0,
+      pct: cv ? Math.round(cv.pct * 1000) / 10 : 0,
+      unaccounted: cv ? cv.unaccountedCount : 0,
+      deviations: deviationsOf(report),
+      advisories: advisoriesOf(report),
+      screens: (report.variants || []).length,
+    };
+    if (!cv) row.reason = "no coverage declared";
+    else if (cv.truncatedInventory) row.reason = "inventory truncated";
+    else if (cv.belowFloor) row.reason = "below coverage floor";
+    else if (cv.unaccountedCount) row.reason = `${cv.unaccountedCount} target(s) neither audited nor skipped with a reason`;
+    return row;
+  });
+  const failedModules = rows.filter((r) => r.gate === "fail").map((r) => r.module);
+  return { gate: failedModules.length ? "fail" : "pass", modules: rows, failedModules };
+}
+
+export function renderRollupHtml(header, verdict) {
+  const L = labels(header || {});
+  const fail = verdict.gate === "fail";
+  const rows = verdict.modules.map((m) => `<tr class="${m.gate === "fail" ? "bad" : ""}">
+    <td>${esc(m.module)}</td>
+    <td>${m.target ? `<b>${m.audited}</b> / ${m.target} · ${esc(m.pct)}%` : "-"}${m.reason ? `<div class="why">${esc(m.reason === "no coverage declared" ? L.rollupNoCoverage : m.reason)}</div>` : ""}</td>
+    <td><span class="badge ${m.gate === "fail" ? "bad" : "good"}">${esc(m.gate.toUpperCase())}</span></td>
+    <td>${m.deviations}${m.advisories ? ` <small>(+${m.advisories} ${esc(L.advisoryWord)})</small>` : ""}</td>
+    <td>${m.href ? `<a href="${esc(m.href)}">${esc(L.rollupOpen)} ↗</a>` : "-"}</td></tr>`).join("");
+  return `<!doctype html><html lang="${esc(L.htmlLang)}"><head><meta charset="utf-8">
+<title>${esc(L.rollupTitle)} - ${esc(header.project)}</title>
+<style>
+body{font:14px/1.5 -apple-system,Segoe UI,Roboto,sans-serif;color:#1a1a1a;margin:0;padding:32px;max-width:1180px;margin-inline:auto;background:#fff}
+h1{font-size:22px;margin:0 0 4px}.sub{color:#666;margin:0 0 20px}
+.gate{border-radius:12px;padding:14px 18px;margin-bottom:22px;font-weight:700}
+.gate small{display:block;font-weight:400;color:#666}
+.gate.bad{border:2px solid #cf222e;background:#fff5f5;color:#cf222e}.gate.good{border:1px solid #0A7D33;background:#f6fff8;color:#0A7D33}
+table{border-collapse:collapse;width:100%}th,td{text-align:left;padding:8px 12px;border-bottom:1px solid #e5e5e5;vertical-align:top}
+th{font-size:12px;text-transform:uppercase;letter-spacing:.04em;color:#666}
+tr.bad td:first-child{border-left:3px solid #cf222e}
+.badge{font-size:11px;font-weight:700;padding:3px 9px;border-radius:10px;color:#fff}.badge.bad{background:#cf222e}.badge.good{background:#0A7D33}
+.why{color:#cf222e;font-size:12px}small{color:#666}
+a{color:#0A66C2;text-decoration:none}
+</style></head><body>
+<h1>${esc(L.rollupTitle)}</h1>
+<p class="sub">${esc(header.project)} · ${esc(header.platform || "")} · ${esc(header.timestamp || "")}</p>
+<div class="gate ${fail ? "bad" : "good"}">${esc(fail ? L.rollupGateFail : L.rollupGatePass)}<small>${esc(L.rollupGateHint)}</small></div>
+<table><thead><tr><th>${esc(L.thModule)}</th><th>${esc(L.thCoverage)}</th><th>${esc(L.thGate)}</th><th>${esc(L.thDeviations)}</th><th>${esc(L.thReport)}</th></tr></thead>
+<tbody>${rows}</tbody></table>
+</body></html>`;
+}
+
+export async function writeRollup({ rollup = {}, modules, outDir, formats = ["html"] }) {
+  if (!Array.isArray(modules) || !modules.length) throw new Error("modules must be a non-empty array");
+  const names = new Set();
+  const loaded = modules.map((entry, i) => {
+    const report = loadModuleReport(entry, i);
+    if (names.has(entry.module)) throw new Error(`duplicate module: ${entry.module}`);
+    names.add(entry.module);
+    return { module: entry.module, report, href: entry.href || null };
+  });
+  const slugs = new Set();
+  for (const m of loaded) {
+    if (m.href) continue;
+    let slug = slugOf(m.module);
+    for (let n = 2; slugs.has(slug); n++) slug = `${slugOf(m.module)}-${n}`;
+    slugs.add(slug);
+    const dir = join(outDir, slug);
+    mkdirSync(dir, { recursive: true });
+    await writeReport({ report: { lang: rollup.lang, labels: rollup.labels, ...m.report, module: m.report.module || m.module }, outDir: dir, formats: ["html"] });
+    m.href = `${slug}/report.html`;
+  }
+  const verdict = rollupVerdict(loaded);
+  const out = { rollup: verdict };
+  if (verdict.gate === "fail") {
+    out.coverageError = `Roll-up gate FAILED: ${verdict.failedModules.length} of ${loaded.length} module(s) failed their coverage gate: ${verdict.failedModules.join(", ")}.`;
+  }
+  const html = renderRollupHtml(rollup, verdict);
+  out.html = join(outDir, "index.html");
+  writeFileSync(out.html, html, "utf-8");
+  if (formats.includes("pdf")) {
+    const pdfPath = join(outDir, "index.pdf");
+    try {
+      const { chromium } = await import("playwright");
+      await renderPdf({ html, pdfPath, chromium });
+      out.pdf = pdfPath;
+    } catch (err) {
+      out.pdfError = `PDF skipped (${err.message}).`;
+    }
+  }
+  return out;
+}

package/tools/design-check/scan.js

@@ -33,7 +33,7 @@ export function rg(pattern, path, { multiline = false, files = false, globs = RG
     ? ["--files", ...globs, "-g", pattern]
     : ["-n", "--no-heading", "--no-messages", ...(multiline ? ["-U", "--multiline-dotall"] : []), ...globs, "-e", pattern];
   try {
-    const out = execSync(`rg ${base.map((a) => `'${String(a).replace(/'/g, "'\\''")}'`).join(" ")} '${path.replace(/'/g, "'\\''")}'`,
+    const out = execSync(`rg ${base.map((a) => `'${String(a).replace(/'/g, "'\\''")}'`).join(" ")} -- '${path.replace(/'/g, "'\\''")}'`,
       { encoding: "utf-8", timeout: 45000, maxBuffer: 32 * 1024 * 1024 });
     const lines = out.split("\n").filter(Boolean);
     if (files) return lines.map((f) => ({ file: f, line: 0, text: "" }));