@design-parity/action 0.1.0

package/README.md

@@ -0,0 +1,109 @@
+# @design-parity/action
+
+The integration layer — it wires every other package into one parity run and
+renders the verdict the bot posts on a PR.
+
+```
+resolver ──(Correspondence[])──┐
+                               ▼
+        registry[source].resolve ──(DesignReference)──┐
+                                                       ▼
+   candidate render ──(CandidateRender)──►  diff + checks ──(Verdict)──┐
+                                                                       ▼
+            policy direction ───────────────►  ParityReport ──► markdown
+```
+
+## What's here (this increment)
+
+- **`createAdapterRegistry()`** — the `source → ReferenceAdapter` map (figma /
+  stitch / claude-design). It lives here because it's the one place that imports
+  all three drivers; `core` must not depend on adapters.
+- **`orchestrate()`** — per component: resolve the reference via its adapter,
+  pair with the candidate render, `diff` them, aggregate. **Fail-soft**: an
+  adapter/diff error is captured and surfaced, never thrown, and never escalates
+  the overall status — only real verdicts do. The parity **direction** decides
+  whether a failure blocks (`design-led`) or is advisory (`code-led`).
+- **`resolveRunConfig()`** — loads the committed `design-map.json` and
+  `.design-parity.json` (deterministic; no model, no network).
+- **`renderReport()`** — the single markdown comment (with a stable marker so
+  the GitHub surface can update its own comment in place).
+- **`design-parity run`** CLI — a local run; candidate renders come from
+  `--candidates <file>` for now (reproducible offline).
+
+## GitHub Action
+
+`action.yml` + `dist/cli/action.js` **auto-select a mode from the triggering
+event** (mirroring the sibling `compose-ai-tools` `apply` action):
+
+- **comment** — a `pull_request`: read the changed files, keep the
+  `design-map.json` components whose file changed (a PR that touches none is
+  treated as non-UI and skipped), run the pipeline, and **post/update a single
+  verdict comment** (idempotent via the report marker). Exits non-zero only when
+  the direction blocks (`design-led` + a failure). If the repo has **no
+  committed `design-map.json`** (parity isn't set up), it posts a one-time
+  notice pointing at the interactive bootstrap (`design-parity-bootstrap`, #11)
+  rather than guessing the design ↔ code mapping at run time — and never blocks.
+- **baseline** — a `push` to the **`development_branch`** (default `main`):
+  render the **full** mapped surface, run the pipeline, and **publish the
+  browsable artifacts** — a top-level `index.html`, each component's
+  self-contained `report.html` triptych, and a machine-readable `verdict.json` —
+  to a permanent **`artifact_branch`** (default `design-parity/<dev-branch>`),
+  force-updated each run. This gives a stable, always-current view of `main`'s
+  parity state without committing generated PNGs/HTML onto `main`, and a real
+  baseline a PR can diff its candidate against. Requires `contents: write`.
+- **skip** — nothing applies (e.g. a push to a non-dev branch).
+
+`mode: baseline|comment|skip` overrides the selector when needed.
+
+```yaml
+# .github/workflows/design-parity.yml
+on:
+  pull_request:
+  push:
+    branches: [main]
+jobs:
+  parity:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write       # baseline mode force-updates the artifact branch
+      pull-requests: write  # comment mode posts the verdict comment
+    steps:
+      - uses: actions/checkout@v4
+      # ... a prior step renders candidates -> candidates.json (or bundles) ...
+      - uses: yschimke/design-parity/packages/action@main
+        with:
+          candidates: candidates.json        # CandidateRender[] …
+          # candidate_bundles: out/previews   # … and/or compose-preview bundles
+          # development_branch: main          # push here → baseline mode
+          # artifact_branch: design-parity/main
+```
+
+The selector + surface logic (`selectMode`, `postReport`,
+`componentsForChangedFiles`, `checkConclusion`) and the artifact builders
+(`baselineSummary`, `renderBaselineIndex`) are pure and unit-tested; the git
+plumbing (`publishBaseline`) takes an injectable `GitRunner` so its
+orphan/re-parent/force-push sequence is unit-tested without a real remote.
+
+## Still to come (issue #8)
+
+- Live `compose-preview` rendering in the candidate provider (today candidates
+  come from a precomputed `CandidateRender[]` / preview bundles).
+- Bundle + commit `dist/` so the action is directly consumable (e.g. via `ncc`)
+  and can be pinned as `yschimke/design-parity/packages/action@<tag>`.
+- Comment mode diffing the PR candidate against the published baseline (the
+  `verdict.json` on the artifact branch) for regression detection.
+
+## Use
+
+```ts
+import { createAdapterRegistry, orchestrate, renderReport } from "@design-parity/action";
+
+const report = await orchestrate({
+  repoRoot,
+  registry: createAdapterRegistry(),
+  correspondences,            // from @design-parity/resolver
+  candidate: (id) => renders.get(id),
+  direction,                  // from @design-parity/policy
+});
+console.log(renderReport(report));
+```

package/dist/baseline.d.ts

@@ -0,0 +1,48 @@
+import type { VerdictStatus } from "@design-parity/core";
+import type { ParityReport, ComponentResult } from "./orchestrate.js";
+export interface BaselineComponent {
+    code: string;
+    source?: string;
+    status: ComponentResult["status"];
+    verdict?: VerdictStatus;
+    /** Counts by severity, when a verdict was produced. */
+    findings?: number;
+    /** Path to the component's `report.html`, relative to the artifact root. */
+    report?: string;
+    note?: string;
+}
+export interface BaselineSummary {
+    /** ISO timestamp the baseline was assembled. */
+    generatedAt: string;
+    /** The commit the baseline was rendered from, when known. */
+    commit?: string;
+    direction: ParityReport["direction"];
+    status: VerdictStatus;
+    blocked: boolean;
+    components: BaselineComponent[];
+    warnings: string[];
+}
+export interface BaselineMeta {
+    /** Source commit SHA (`GITHUB_SHA`), recorded in the summary + index. */
+    commit?: string;
+    /** Override the timestamp (tests); defaults to `new Date()`. */
+    now?: Date;
+}
+/** The machine-readable roll-up written as `verdict.json`. */
+export declare function baselineSummary(report: ParityReport, outDir: string, meta?: BaselineMeta): BaselineSummary;
+/** The self-contained `index.html` landing page. */
+export declare function renderBaselineIndex(summary: BaselineSummary): string;
+export interface BaselineArtifacts {
+    /** Relative path written: `index.html`. */
+    indexPath: string;
+    /** Relative path written: `verdict.json`. */
+    verdictPath: string;
+    summary: BaselineSummary;
+}
+/**
+ * Write `index.html` + `verdict.json` into `outDir` (alongside the per-component
+ * subdirs `orchestrate` already populated). Returns the relative paths and the
+ * computed summary.
+ */
+export declare function writeBaselineArtifacts(outDir: string, report: ParityReport, meta?: BaselineMeta): Promise<BaselineArtifacts>;
+//# sourceMappingURL=baseline.d.ts.map

package/dist/baseline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline.d.ts","sourceRoot":"","sources":["../src/baseline.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAQtE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC;IAClC,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,YAAY,CAAC,WAAW,CAAC,CAAC;IACrC,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAOD,8DAA8D;AAC9D,wBAAgB,eAAe,CAC7B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,YAAiB,GACtB,eAAe,CAsBjB;AAUD,oDAAoD;AACpD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CA4DpE;AAED,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,eAAe,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,EACpB,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC,iBAAiB,CAAC,CAM5B"}

package/dist/baseline.js

@@ -0,0 +1,126 @@
+/**
+ * Assemble the browsable baseline artifacts published to the permanent branch
+ * (issue #56). `orchestrate` already writes each component's self-contained
+ * `report.html` triptych into its own subdir of `outDir`; this layer adds the
+ * two top-level files that make the branch a stable, always-current view of the
+ * dev branch's parity state:
+ *
+ * - **`index.html`** — the landing page: overall verdict + a row per component
+ *   linking into its `report.html`. Self-contained, no assets, no JS.
+ * - **`verdict.json`** — the machine-readable roll-up (status, direction, per
+ *   component verdict + relative report path). This is the baseline a PR run can
+ *   load to diff its candidate against `main` rather than only the static
+ *   design reference.
+ *
+ * The HTML/JSON builders are pure (string / object in, no I/O); only
+ * {@link writeBaselineArtifacts} touches disk.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+const STATUS_ICON = {
+    pass: "✅",
+    warn: "⚠️",
+    fail: "❌",
+};
+/** Relative path from the artifact root to a component's report, if it has one. */
+function reportRel(outDir, result) {
+    return result.reportPath ? relative(outDir, result.reportPath) : undefined;
+}
+/** The machine-readable roll-up written as `verdict.json`. */
+export function baselineSummary(report, outDir, meta = {}) {
+    const components = report.results.map((r) => {
+        const rel = reportRel(outDir, r);
+        return {
+            code: r.code,
+            ...(r.source ? { source: r.source } : {}),
+            status: r.status,
+            ...(r.verdict ? { verdict: r.verdict.status } : {}),
+            ...(r.verdict ? { findings: r.verdict.findings.length } : {}),
+            ...(rel ? { report: rel } : {}),
+            ...(r.note ? { note: r.note } : {}),
+        };
+    });
+    return {
+        generatedAt: (meta.now ?? new Date()).toISOString(),
+        ...(meta.commit ? { commit: meta.commit } : {}),
+        direction: report.direction,
+        status: report.status,
+        blocked: report.blocked,
+        components,
+        warnings: report.warnings,
+    };
+}
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+/** The self-contained `index.html` landing page. */
+export function renderBaselineIndex(summary) {
+    const headline = summary.blocked
+        ? `${STATUS_ICON.fail} Parity failed — blocking (${summary.direction})`
+        : `${STATUS_ICON[summary.status]} Parity ${summary.status} (${summary.direction})`;
+    const rows = summary.components
+        .map((c) => {
+        const icon = c.verdict ? STATUS_ICON[c.verdict] : "—";
+        const state = c.verdict ?? c.status;
+        const label = c.report
+            ? `<a href="${escapeHtml(c.report)}">${escapeHtml(c.code)}</a>`
+            : escapeHtml(c.code);
+        const detail = c.note ? escapeHtml(c.note) : "";
+        return (`<tr><td>${icon}</td><td>${label}</td>` +
+            `<td>${escapeHtml(c.source ?? "")}</td>` +
+            `<td>${escapeHtml(state)}</td>` +
+            `<td>${escapeHtml(detail)}</td></tr>`);
+    })
+        .join("\n");
+    const warnings = summary.warnings.length > 0
+        ? `<details><summary>${summary.warnings.length} warning(s)</summary><ul>` +
+            summary.warnings.map((w) => `<li>${escapeHtml(w)}</li>`).join("") +
+            `</ul></details>`
+        : "";
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Design parity baseline</title>
+<style>
+  body { font: 15px/1.5 system-ui, sans-serif; margin: 2rem auto; max-width: 60rem; padding: 0 1rem; }
+  h1 { font-size: 1.4rem; }
+  .meta { color: #666; font-size: 0.85rem; }
+  table { border-collapse: collapse; width: 100%; margin-top: 1rem; }
+  th, td { text-align: left; padding: 0.4rem 0.6rem; border-bottom: 1px solid #eee; }
+  th { font-size: 0.8rem; text-transform: uppercase; letter-spacing: 0.04em; color: #666; }
+  code { font-family: ui-monospace, monospace; }
+</style>
+</head>
+<body>
+<h1>${escapeHtml(headline)}</h1>
+<p class="meta">Generated ${escapeHtml(summary.generatedAt)}${summary.commit ? ` · commit <code>${escapeHtml(summary.commit.slice(0, 12))}</code>` : ""}</p>
+<table>
+<thead><tr><th></th><th>Component</th><th>Source</th><th>State</th><th>Note</th></tr></thead>
+<tbody>
+${rows || '<tr><td colspan="5">No components were checked.</td></tr>'}
+</tbody>
+</table>
+${warnings}
+</body>
+</html>
+`;
+}
+/**
+ * Write `index.html` + `verdict.json` into `outDir` (alongside the per-component
+ * subdirs `orchestrate` already populated). Returns the relative paths and the
+ * computed summary.
+ */
+export async function writeBaselineArtifacts(outDir, report, meta = {}) {
+    const summary = baselineSummary(report, outDir, meta);
+    await mkdir(outDir, { recursive: true });
+    await writeFile(join(outDir, "verdict.json"), JSON.stringify(summary, null, 2));
+    await writeFile(join(outDir, "index.html"), renderBaselineIndex(summary));
+    return { indexPath: "index.html", verdictPath: "verdict.json", summary };
+}
+//# sourceMappingURL=baseline.js.map

package/dist/baseline.js.map

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

package/dist/candidate.d.ts

@@ -0,0 +1,48 @@
+import type { CandidateRender, DesignMap } from "@design-parity/core";
+import { type CandidateSource } from "@design-parity/candidate";
+import type { CandidateProvider } from "./orchestrate.js";
+/** A {@link CandidateSource} backed by an in-memory `CandidateRender[]`. */
+export declare function precomputedSource(candidates: Iterable<CandidateRender>): CandidateSource;
+/** Load a precomputed `CandidateRender[]` JSON (array or `{ candidates }`). */
+export declare function loadPrecomputed(repoRoot: string, path: string): Promise<CandidateSource>;
+/**
+ * Expand a comma-separated list of preview-bundle inputs (each a polyglot
+ * `.png` file or a directory of them) into concrete bundle file paths, resolved
+ * against `repoRoot`.
+ */
+export declare function resolveBundlePaths(repoRoot: string, inputs: string[]): Promise<string[]>;
+/** A {@link CandidateProvider} from a {@link CandidateSource}. */
+export declare function providerFromSource(source: CandidateSource): CandidateProvider;
+export interface BuildProviderOptions {
+    repoRoot: string;
+    /** Precomputed `CandidateRender[]` JSON path (array or `{ candidates }`). */
+    candidatesPath?: string;
+    /** Preview-bundle inputs: polyglot `.png` files and/or directories of them. */
+    bundlePaths?: string[];
+    /**
+     * The loaded `design-map.json`, used to reconcile bundle preview ids to code
+     * handles so bundle candidates pair with their references (issue #44).
+     */
+    designMap?: DesignMap;
+}
+/** The candidate provider plus any non-fatal diagnostics from building it. */
+export interface BuiltCandidateProvider {
+    /** `undefined` when no candidate source was configured. */
+    provider?: CandidateProvider;
+    /** e.g. preview ids that couldn't be reconciled to a code handle (#44). */
+    warnings: string[];
+}
+/**
+ * Assemble a {@link CandidateProvider} from the configured inputs. When both a
+ * precomputed JSON and bundles are given, bundles are tried first and the JSON
+ * is the fallback (a hand-authored override). The `provider` is `undefined`
+ * when neither is configured (the run has no candidate source).
+ *
+ * Bundle preview ids are reconciled to code handles through
+ * `@design-parity/resolver` (the `design-map` `previewId` field, else the
+ * `sourceFile#functionName` convention) so a bundle candidate keys on the same
+ * id the orchestrator pairs references by (issue #44). Unreconcilable preview
+ * ids surface as `warnings` rather than silently failing to pair.
+ */
+export declare function buildCandidateProvider(options: BuildProviderOptions): Promise<BuiltCandidateProvider>;
+//# sourceMappingURL=candidate.d.ts.map

package/dist/candidate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate.d.ts","sourceRoot":"","sources":["../src/candidate.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAEV,eAAe,EACf,SAAS,EACV,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,QAAQ,CAAC,eAAe,CAAC,GACpC,eAAe,CASjB;AAED,+EAA+E;AAC/E,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,eAAe,CAAC,CAK1B;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EAAE,GACf,OAAO,CAAC,MAAM,EAAE,CAAC,CAenB;AAED,kEAAkE;AAClE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,iBAAiB,CAG7E;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACrC,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,sBAAsB,CAAC,CAwCjC"}

package/dist/candidate.js

@@ -0,0 +1,109 @@
+/**
+ * Build the {@link CandidateProvider} a parity run uses to obtain candidate
+ * renders.
+ *
+ * Two committed, offline inputs are supported (Principle 1 — no live model):
+ *
+ * 1. A precomputed `CandidateRender[]` JSON (today's path) — reproducible, the
+ *    renderer's output captured as an artifact.
+ * 2. A directory / list of compose-ai-tools **preview-bundle** polyglots
+ *    (issue #38, Phase 1) — the project's own pipeline already rendered these;
+ *    `@design-parity/candidate`'s {@link bundleCandidateSource} reads them
+ *    statically (pure JS, no JVM) into the same `CandidateRender`s.
+ *
+ * Both reduce to a {@link CandidateProvider}; {@link firstAvailable} lets a run
+ * combine them (e.g. bundles first, precomputed JSON as a fallback).
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+import { bundleCandidateSource, firstAvailable, readPreviewBundle, } from "@design-parity/candidate";
+import { resolvePreviewIds } from "@design-parity/resolver";
+/** A {@link CandidateSource} backed by an in-memory `CandidateRender[]`. */
+export function precomputedSource(candidates) {
+    const index = new Map();
+    for (const c of candidates)
+        index.set(c.componentId, c);
+    return {
+        kind: "precomputed",
+        async getCandidate(componentId) {
+            return index.get(componentId);
+        },
+    };
+}
+/** Load a precomputed `CandidateRender[]` JSON (array or `{ candidates }`). */
+export async function loadPrecomputed(repoRoot, path) {
+    const raw = JSON.parse(await readFile(resolve(repoRoot, path), "utf8"));
+    return precomputedSource(Array.isArray(raw) ? raw : raw.candidates);
+}
+/**
+ * Expand a comma-separated list of preview-bundle inputs (each a polyglot
+ * `.png` file or a directory of them) into concrete bundle file paths, resolved
+ * against `repoRoot`.
+ */
+export async function resolveBundlePaths(repoRoot, inputs) {
+    const paths = [];
+    for (const input of inputs) {
+        const abs = isAbsolute(input) ? input : resolve(repoRoot, input);
+        const info = await stat(abs);
+        if (info.isDirectory()) {
+            const names = await readdir(abs);
+            for (const name of names.sort()) {
+                if (name.toLowerCase().endsWith(".png"))
+                    paths.push(join(abs, name));
+            }
+        }
+        else {
+            paths.push(abs);
+        }
+    }
+    return paths;
+}
+/** A {@link CandidateProvider} from a {@link CandidateSource}. */
+export function providerFromSource(source) {
+    return (componentId, ctx) => source.getCandidate(componentId, ctx);
+}
+/**
+ * Assemble a {@link CandidateProvider} from the configured inputs. When both a
+ * precomputed JSON and bundles are given, bundles are tried first and the JSON
+ * is the fallback (a hand-authored override). The `provider` is `undefined`
+ * when neither is configured (the run has no candidate source).
+ *
+ * Bundle preview ids are reconciled to code handles through
+ * `@design-parity/resolver` (the `design-map` `previewId` field, else the
+ * `sourceFile#functionName` convention) so a bundle candidate keys on the same
+ * id the orchestrator pairs references by (issue #44). Unreconcilable preview
+ * ids surface as `warnings` rather than silently failing to pair.
+ */
+export async function buildCandidateProvider(options) {
+    const sources = [];
+    const warnings = [];
+    if (options.bundlePaths && options.bundlePaths.length > 0) {
+        const paths = await resolveBundlePaths(options.repoRoot, options.bundlePaths);
+        if (paths.length > 0) {
+            const bundles = [];
+            for (const p of paths)
+                bundles.push(await readPreviewBundle(p));
+            const identities = bundles.flatMap((b) => b.previews.map((e) => ({
+                id: e.id,
+                ...(e.sourceFile !== undefined ? { sourceFile: e.sourceFile } : {}),
+                ...(e.functionName !== undefined
+                    ? { functionName: e.functionName }
+                    : {}),
+            })));
+            const { matches, warnings: mapWarnings } = resolvePreviewIds(identities, options.designMap);
+            warnings.push(...mapWarnings);
+            sources.push(bundleCandidateSource({
+                bundles,
+                resolveComponentId: (preview) => matches.get(preview.id)?.code,
+            }));
+        }
+    }
+    if (options.candidatesPath) {
+        sources.push(await loadPrecomputed(options.repoRoot, options.candidatesPath));
+    }
+    if (sources.length === 0)
+        return { warnings };
+    const source = sources.length === 1 ? sources[0] : firstAvailable(sources);
+    return { provider: providerFromSource(source), warnings };
+}
+//# sourceMappingURL=candidate.js.map

package/dist/candidate.js.map

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

package/dist/cli/action.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=action.d.ts.map

package/dist/cli/action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../../src/cli/action.ts"],"names":[],"mappings":""}