figdiff 0.0.0-stage → 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 figdiff contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,309 @@
-# Temporary Holding Version
+# figdiff
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Review design changes the way you review code.**
+
+`figdiff` compares two versions of a [FigCraft](https://github.com/storytold/figcraft) design file (`.figcraft`) and explains what changed, both as a readable list of changes and as before/after images.
+
+> **Status: early development (pre-alpha).** Phase 0 is in progress. The parser and a basic text diff exist and are published as a pre-alpha on npm (see [Try it](#try-it)); the HTML report, visual diff and GitHub Action are still planned. Commands in the usage section below are the intended interface and may change. Feedback is very welcome: please open an issue.
+
+> **Not affiliated.** figdiff is an independent community project. It is not made by, endorsed by, or connected to the FigCraft / ArtCraft authors. FigCraft is a trademark of its respective owners.
+
+---
+
+## Table of contents
+
+- [Try it](#try-it)
+- [The problem](#the-problem)
+- [The idea](#the-idea)
+- [Planned usage](#planned-usage)
+- [How it will work](#how-it-will-work)
+- [Who is it for](#who-is-it-for)
+- [Roadmap](#roadmap)
+- [Risks and open questions](#risks-and-open-questions)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Try it
+
+The first pre-alpha is on npm under the `alpha` tag. It needs Node.js 20 or newer.
+
+```sh
+npx figdiff@alpha before.figcraft after.figcraft
+```
+
+To install it globally instead: `npm install -g figdiff@alpha`.
+
+Today it compares two files and prints a grouped list of changes (`--json` and `--exit-code` are available). The HTML report, visual diff and GitHub Action are on the roadmap below. Matching of nodes relies on ids staying stable between saves in FigCraft, which is not yet verified, so treat results as preliminary.
+
+---
+
+## The problem
+
+A `.figcraft` file is a zip archive. When it changes in a Git repository, GitHub and `git diff` can only say "binary file changed". A reviewer has no way to tell whether a designer moved one button or rebuilt a whole screen, short of opening the file in FigCraft and comparing by eye.
+
+Code has diffs, pull request comments, and review tools. Design files, stored in the same repositories, have none of that.
+
+## The idea
+
+figdiff gives design files the same review workflow as code:
+
+- **Semantic diff.** A list of changes in plain language, for example:
+  `Frame "Login" › Button "Sign in": fill #2563EB → #1D4ED8`
+- **Visual diff.** Before, after, and highlighted-difference images for every frame that changed.
+- **Automatic pull request comments.** A GitHub Action that posts both of the above on every pull request that touches a design file.
+
+## Planned usage
+
+> These commands are the intended interface and may change.
+
+**Compare two files locally**
+
+```sh
+npx figdiff before.figcraft after.figcraft
+```
+
+```text
+Page "App"
+  Frame "Components"
+    - Landscape › Time=Day › Sun (ellipse)
+    ~ Chip › Selected=On › Label: characters All trails → All routes
+  Frame "Home — Light"
+    ~ Status bar › Indicators › Signal › Bar 1: fills #0F172A → #E6172A
+    ~ Status bar › Indicators › Signal › Bar 1: width 3 → 15
+
+4 changes in 2 frames (1 removed, 3 property changes)
+```
+
+Useful flags: `--html report.html` also writes a self-contained HTML report (add `--images` for rendered before/after images), `--json` prints the summary and every change as JSON, and `--exit-code` exits with 1 when the files differ, so it can fail a CI step.
+
+**Generate a shareable report**
+
+```sh
+npx figdiff before.figcraft after.figcraft --html report.html
+```
+
+One self-contained HTML file with the list of changes, filters, and light and dark mode. No server needed, so it can be sent by email or chat to a developer or client. With `--images` (and FigCraft's `figcraft-cli` installed) it also embeds before/after images with a swipe slider and a difference view. This part is experimental: it has been tested with a stand-in for `figcraft-cli` but not yet with the real one.
+
+**Compare against another Git branch**
+
+```sh
+npx figdiff design/app.figcraft --against main
+```
+
+`--against` accepts any git revision (a branch, tag, or commit such as `HEAD~1`). The file is compared with its committed version, so it also works for uncommitted edits: `--against HEAD` shows what you changed since the last commit.
+
+**Use it as a `git difftool`**
+
+```sh
+git config difftool.figdiff.cmd 'figdiff "$LOCAL" "$REMOTE"'
+git difftool -y -t figdiff main -- design/app.figcraft
+```
+
+**Run on every pull request**
+
+The GitHub Action (`action.yml`, currently in alpha) posts one comment per pull request with what changed in each `.figcraft` file, and keeps that comment up to date on every push. Full HTML reports are attached to the workflow run.
+
+```yaml
+# .github/workflows/figdiff.yml  (also in examples/figdiff.yml)
+name: Design changes
+on:
+  pull_request:
+    paths: ["**/*.figcraft"]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  figdiff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # needed to read the base commit
+      - uses: bintangyoga/figdiff@main
+        with:
+          files: "design/**/*.figcraft"
+```
+
+| Input | Default | Meaning |
+| --- | --- | --- |
+| `files` | `**/*.figcraft` | Glob patterns (commas or new lines) of the design files to look at |
+| `comment` | `true` | `false` writes the reports without commenting |
+| `max-files` | `20` | Compare at most this many files per pull request |
+| `upload-reports` | `true` | Upload the HTML reports as the artifact `figdiff-reports` |
+| `report-dir` | `figdiff-reports` | Where the reports are written |
+| `version` | `latest` | Version of the `figdiff` npm package to use |
+| `token` | `github.token` | Token used to comment |
+
+Pull requests from forks get a read-only token, so no comment is posted; the changes are printed in the job log instead. Images in the comment are not included yet (see Phase 3).
+
+## How it will work
+
+```text
+before.figcraft ─┐                    ┌─ semantic diff (changes as text/JSON)
+                 ├─► parse + match ──►┤
+after.figcraft  ─┘                    └─ visual diff (render + compare images)
+```
+
+1. **Parser.** Opens the `.figcraft` archive and reads its `document.json` into an internal model. This is the only part that depends on the file format, so it is isolated and versioned.
+2. **Differ.** Matches nodes between the two versions (by id, with fallbacks) and produces a list of added, removed, moved, and modified nodes.
+3. **Renderer.** Uses FigCraft's own headless CLI (`figcraft-cli`) to render the changed frames to images, then compares them pixel by pixel.
+4. **Reporters.** Terminal output, JSON, a self-contained HTML report, and a GitHub pull request comment.
+
+Design principles:
+
+- **Independent.** A separate project. It reads the public file format and uses the public CLI; it does not modify FigCraft.
+- **Local-first.** Runs on your machine or in your CI. No accounts, no servers, no telemetry.
+- **Resilient to format changes.** FigCraft is in alpha and its format may change. The parser is kept separate from the diff logic and tested against files from multiple FigCraft versions.
+- **Useful without Git.** The CLI and HTML report work on any two files.
+
+## Who is it for
+
+- **Developers** who receive design files and want to know what changed since the last version.
+- **Design engineers and designers who use Git**, and want design changes reviewed in pull requests.
+- **Freelancers and agencies** who exchange versions with clients and need a clear "what changed since last time" report.
+
+---
+
+## Roadmap
+
+Estimated timeline: about 18 weeks to v1.0, assuming one maintainer at roughly 10 hours per week. Each phase ends with a usable release, and the next phase starts only after the exit criteria are met.
+
+| Phase | Weeks | Goal | Release |
+| --- | --- | --- | --- |
+| 0 | 1–2 | Research and setup | n/a |
+| 1 | 3–6 | Semantic diff in the CLI | v0.1.0 |
+| 2 | 7–10 | HTML report and visual diff | v0.2.0 |
+| 3 | 11–14 | GitHub Action | v0.3.0 |
+| 4 | 15–18 | Public launch | v1.0.0 |
+| 5 | After v1.0 | Driven by user demand | n/a |
+
+### Phase 0: Research and setup (weeks 1–2)
+
+Confirm that FigCraft's file format and CLI are stable enough to build on, before writing product code.
+
+- [x] Download sample files from FigCraft's `examples/` folder, unzip them, and study the structure of `document.json`
+- [x] Document the node schema: id, type, name, parent, position, size, fills, strokes, text, auto layout, components, variables
+- [ ] Verify that node ids stay stable when a file is saved again (critical for matching nodes between versions)
+- [ ] Test `figcraft-cli render`, `export --node`, and `convert` on headless Linux
+- [ ] Check whether `figcraft-cli` is available as a prebuilt binary or must be built with Cargo
+- [ ] Check name availability on npm and GitHub; choose a fallback name if needed
+- [x] Set up the repository: TypeScript, tests, CI
+- [ ] Add linting and formatting (ESLint, Prettier)
+
+**Deliverables:** format notes (`docs/format-notes.md`), 5–10 before/after sample file pairs, a working project skeleton.
+
+**Exit criteria:** the `document.json` schema is understood and node ids are proven stable, or a fallback matching strategy is designed.
+
+### Phase 1: Semantic diff in the CLI (weeks 3–6)
+
+Deliver `figdiff a.figcraft b.figcraft` printing a correct list of changes in the terminal. No images yet.
+
+- [x] Parser for core properties: type, name, hierarchy, position, size, fills, strokes, corner radius, text, font
+- [ ] Node matching by id, with fallback to name and hierarchy path
+- [x] Detect added, removed, reparented, and modified nodes
+- [x] Group results by page and top-level frame so output is easy to read
+- [x] Summary line (for example, "12 changes in 3 frames")
+- [x] `--json` output for use by other tools
+- [x] `--exit-code` flag and stable exit codes (0 ok, 1 differences, 2 error)
+- [x] Detect changes in layer order
+- [ ] Tests using the sample file pairs from Phase 0
+
+**Release:** `v0.1.0` on npm, usable with `npx figdiff`.
+
+**Exit criteria:** on every sample pair, the list of changes is complete and contains no false changes.
+
+### Phase 2: HTML report and visual diff (weeks 7–10)
+
+Deliver a self-contained HTML report that anyone can open, including designers who do not use Git.
+
+- [x] Self-contained HTML report of the semantic diff (`--html report.html`), with filters and light/dark mode
+- [x] Before/after swipe slider and a difference view with the share of changed pixels
+- [x] Pixel comparison with highlighted changed areas (own PNG decoder, no dependencies; checked against real FigCraft PNGs)
+- [x] A single `report.html` with embedded images and no server
+- [x] Graceful fallback when `figcraft-cli` is unavailable: the report is still written, with a warning
+- [x] Frames that exist in only one version (added or removed) are shown on their own
+- [ ] Verify rendering against a real `figcraft-cli` (implemented from its documentation and tested with a stand-in; the exact `--node` and `--page` behavior is unconfirmed)
+- [ ] Render at 2x as well as 1x
+- [x] Side-by-side view next to the swipe slider
+- [ ] Semantic change list next to the images; clicking a change highlights its location
+- [x] `--against <revision>` (compare a file with its version on a branch, tag or commit) and `git difftool` usage
+
+**Release:** `v0.2.0`, with the first demo GIF in this README.
+
+**Exit criteria:** 3–5 people outside the project open the report and understand the changes without extra explanation.
+
+### Phase 3: GitHub Action (weeks 11–14)
+
+Deliver an automatic comment on every pull request that changes a `.figcraft` file, set up with one workflow file.
+
+- [x] Detect changed `.figcraft` files in a pull request and compare each with its base version
+- [ ] Install `figcraft-cli` on the runner, with caching
+- [x] Pull request comment with a summary and per-frame changes (before/after images still to do)
+- [ ] Host images via workflow artifacts or a dedicated branch (GitHub comments need image URLs)
+- [x] Update a single comment on each push instead of posting new ones
+- [x] Configuration options: file patterns, file limit, report folder (render scale and comment language still to do)
+- [ ] Public example repository that uses the Action as a live demo
+
+**Release:** `v0.3.0` and a listing on GitHub Marketplace.
+
+**Exit criteria:** the Action runs reliably on the example repository and on at least one real project.
+
+### Phase 4: Public launch (weeks 15–18)
+
+Deliver a project that other people can use and contribute to, then announce it.
+
+- [ ] Support for advanced properties: components and instances, variants, variables and tokens, effects, prototyping, images
+- [ ] Performance testing on large files (thousands of nodes); target a diff in a few seconds
+- [ ] Compatibility table of tested FigCraft versions, updated with each FigCraft release
+- [ ] Documentation: CLI guide, Action guide, contributor guide
+- [ ] `good first issue` labels to welcome contributors
+- [ ] Announcement: FigCraft community, Show HN, Reddit, and design communities
+
+**Release:** `v1.0.0`, with a stable CLI and JSON output format.
+
+### Phase 5: After v1.0
+
+Direction will follow user demand. Candidates:
+
+- **Three-way merge** of design files from different branches, with conflict markers
+- **Token and consistency checks** that warn in a pull request about colors or spacing outside the design system
+- **Other platforms:** GitLab CI, Gitea, Forgejo
+- **MCP server**, so AI agents can ask "what changed in this design?"
+- **Automatic design changelog** generated from Git tags
+- **Upstream collaboration:** open a diff report directly in FigCraft, if the maintainers are interested
+
+---
+
+## Risks and open questions
+
+| Risk | Impact | Mitigation |
+| --- | --- | --- |
+| The `.figcraft` format changes (FigCraft is alpha) | Parser breaks on new FigCraft releases | Isolated parser, compatibility table, tests on files from each version |
+| Node ids are not stable between saves | Diffs full of false changes | Fallback matching by name and path, validated in Phase 0 |
+| `figcraft-cli` is hard to install in CI | Slow or failing GitHub Action | Cache the binary; fall back to semantic diff only |
+| FigCraft adds its own diff feature | Less reason to use figdiff | Focus on review in Git and pull requests; talk to the maintainers early |
+| Small FigCraft user base | Slow adoption | Start from real needs; keep the core model usable for other formats later |
+
+Open questions:
+
+- Is the project name `figdiff` available on npm and GitHub?
+- Does `figcraft-cli` ship as a downloadable binary for Linux, macOS, and Windows?
+- How much of FigCraft's built-in `versions/` and `branches/` data is useful to reuse?
+
+## Contributing
+
+Contributions are welcome, even at this early stage. The most useful things right now:
+
+- Feedback on the plan: open an issue with your use case
+- Sample `.figcraft` file pairs (before/after) that you are allowed to share
+- Notes on the file format, once Phase 0 begins
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## License
+
+[MIT](LICENSE)

package/dist/action/changed-files.d.ts

@@ -0,0 +1,14 @@
+export interface ChangedFile {
+    status: "added" | "modified" | "deleted" | "renamed";
+    /** Path in the new version (or the old one, for a deleted file). */
+    path: string;
+    /** Path in the base version, for a renamed file. */
+    oldPath?: string;
+}
+/**
+ * Parse the output of `git diff --name-status -z`. Entries are separated by NUL characters;
+ * renames and copies carry two paths.
+ */
+export declare function parseNameStatus(output: string): ChangedFile[];
+/** Keep the files that match one of the patterns (a rename matches on either of its two paths). */
+export declare function filterByPatterns(files: ChangedFile[], patterns: string[]): ChangedFile[];

package/dist/action/changed-files.js

@@ -0,0 +1,35 @@
+import { matchesAny } from "./glob.js";
+/**
+ * Parse the output of `git diff --name-status -z`. Entries are separated by NUL characters;
+ * renames and copies carry two paths.
+ */
+export function parseNameStatus(output) {
+    const tokens = output.split("\0");
+    const files = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const code = tokens[i];
+        if (code === "")
+            continue;
+        const kind = code[0];
+        if (kind === "R") {
+            const oldPath = tokens[++i];
+            const path = tokens[++i];
+            files.push({ status: "renamed", path, oldPath });
+        }
+        else if (kind === "C") {
+            i++; // the copy source is not interesting
+            files.push({ status: "added", path: tokens[++i] });
+        }
+        else {
+            const path = tokens[++i];
+            const status = kind === "A" ? "added" : kind === "D" ? "deleted" : "modified";
+            files.push({ status, path });
+        }
+    }
+    return files;
+}
+/** Keep the files that match one of the patterns (a rename matches on either of its two paths). */
+export function filterByPatterns(files, patterns) {
+    return files.filter((f) => matchesAny(f.path, patterns) || (f.oldPath !== undefined && matchesAny(f.oldPath, patterns)));
+}
+//# sourceMappingURL=changed-files.js.map

package/dist/action/changed-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"changed-files.js","sourceRoot":"","sources":["../../src/action/changed-files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAUvC;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,KAAK,GAAkB,EAAE,CAAC;IAChC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAW,CAAC;QACjC,IAAI,IAAI,KAAK,EAAE;YAAE,SAAS;QAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACrB,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;YACjB,MAAM,OAAO,GAAG,MAAM,CAAC,EAAE,CAAC,CAAW,CAAC;YACtC,MAAM,IAAI,GAAG,MAAM,CAAC,EAAE,CAAC,CAAW,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QACnD,CAAC;aAAM,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;YACxB,CAAC,EAAE,CAAC,CAAC,qCAAqC;YAC1C,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,CAAW,EAAE,CAAC,CAAC;QAC/D,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,GAAG,MAAM,CAAC,EAAE,CAAC,CAAW,CAAC;YACnC,MAAM,MAAM,GAAG,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC;YAC9E,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,gBAAgB,CAAC,KAAoB,EAAE,QAAkB;IACvE,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,KAAK,SAAS,IAAI,UAAU,CAAC,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;AAC3H,CAAC"}

package/dist/action/comment.d.ts

@@ -0,0 +1,28 @@
+import type { Summary } from "../diff/types.js";
+import type { ChangedFile } from "./changed-files.js";
+/** Hidden marker used to find our own comment again on later pushes. */
+export declare const COMMENT_MARKER = "<!-- figdiff-comment -->";
+export interface FileResult {
+    file: ChangedFile;
+    /** Present when the two versions were compared. */
+    summary?: Summary;
+    /** The text diff, as printed by `figdiff`. */
+    text?: string;
+    /** Why the comparison could not be made. */
+    error?: string;
+    /** Name of the HTML report written for this file, if any. */
+    reportName?: string;
+}
+export interface CommentContext {
+    /** Link to the workflow run, where the report artifact can be downloaded. */
+    runUrl?: string;
+    /** Whether the HTML reports were uploaded as an artifact. */
+    reportsUploaded: boolean;
+    version?: string;
+}
+/** A file counts as changed unless it was only re-saved without any design difference. */
+export declare function isSubstantive(r: FileResult): boolean;
+/** The pull request comment for a set of compared files. */
+export declare function buildComment(results: FileResult[], ctx: CommentContext): string;
+/** Replaces an earlier comment when a later push no longer changes any design file. */
+export declare function buildEmptyComment(): string;

package/dist/action/comment.js

@@ -0,0 +1,70 @@
+import { formatSummary } from "../report.js";
+/** Hidden marker used to find our own comment again on later pushes. */
+export const COMMENT_MARKER = "<!-- figdiff-comment -->";
+/** GitHub rejects comments over 65,536 characters; stay well below. */
+const MAX_COMMENT = 60_000;
+const MAX_FILE_TEXT = 15_000;
+/** A file counts as changed unless it was only re-saved without any design difference. */
+export function isSubstantive(r) {
+    if (r.error)
+        return true;
+    if (r.file.status === "added" || r.file.status === "deleted" || r.file.status === "renamed")
+        return true;
+    return (r.summary?.changes ?? 0) > 0;
+}
+/** Wrap text in a code span, choosing a delimiter that cannot be broken by backticks inside. */
+function code(text) {
+    const longest = Math.max(0, ...(text.match(/`+/g) ?? []).map((m) => m.length));
+    const fence = "`".repeat(longest + 1);
+    return `${fence}${text.startsWith("`") || text.endsWith("`") ? ` ${text} ` : text}${fence}`;
+}
+/** A fenced code block whose fence is longer than any backtick run inside. */
+function block(text) {
+    const longest = Math.max(2, ...(text.match(/`+/g) ?? []).map((m) => m.length));
+    const fence = "`".repeat(longest + 1);
+    return `${fence}text\n${text.replace(/\n$/, "")}\n${fence}`;
+}
+function truncate(text, limit) {
+    if (text.length <= limit)
+        return text;
+    const cut = text.slice(0, limit);
+    const kept = cut.slice(0, Math.max(cut.lastIndexOf("\n"), 0));
+    const hidden = text.slice(kept.length).split("\n").filter(Boolean).length;
+    return `${kept}\n… ${hidden} more lines not shown`;
+}
+function section(r) {
+    const { file } = r;
+    const name = code(file.path);
+    switch (file.status) {
+        case "added":
+            return `**${name}**: new design file, nothing earlier to compare with.`;
+        case "deleted":
+            return `**${name}**: design file deleted.`;
+        default:
+    }
+    const renamed = file.status === "renamed" ? ` (renamed from ${code(file.oldPath ?? "")})` : "";
+    if (r.error)
+        return `**${name}**${renamed}: could not be compared. ${r.error}`;
+    if (!r.summary || r.summary.changes === 0) {
+        return `**${name}**${renamed}: ${file.status === "renamed" ? "renamed, no design changes." : "saved again, no design changes."}`;
+    }
+    const details = r.text
+        ? `\n\n<details><summary>Show changes</summary>\n\n${block(truncate(r.text, MAX_FILE_TEXT))}\n\n</details>`
+        : "";
+    return `**${name}**${renamed}: ${formatSummary(r.summary)}${details}`;
+}
+/** The pull request comment for a set of compared files. */
+export function buildComment(results, ctx) {
+    const parts = [`${COMMENT_MARKER}\n## Design changes`, ...results.map(section)];
+    if (ctx.reportsUploaded && ctx.runUrl && results.some((r) => r.reportName)) {
+        parts.push(`Full HTML reports (with filters and, if enabled, images) are attached to [this workflow run](${ctx.runUrl}) as the artifact **figdiff-reports**.`);
+    }
+    parts.push(`<sub>Generated by figdiff${ctx.version ? ` ${ctx.version}` : ""}. Changes are matched by node id.</sub>`);
+    const body = parts.join("\n\n");
+    return body.length <= MAX_COMMENT ? body : `${body.slice(0, MAX_COMMENT)}\n\n… (comment shortened)`;
+}
+/** Replaces an earlier comment when a later push no longer changes any design file. */
+export function buildEmptyComment() {
+    return `${COMMENT_MARKER}\n## Design changes\n\nThis pull request no longer changes any design file.`;
+}
+//# sourceMappingURL=comment.js.map

package/dist/action/comment.js.map

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

package/dist/action/github.d.ts

@@ -0,0 +1,15 @@
+/** An error from the GitHub API, with the HTTP status so callers can tell "no permission" apart. */
+export declare class GitHubError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export interface GitHubApi {
+    fetch: typeof fetch;
+    /** For example https://api.github.com */
+    baseUrl: string;
+    token: string;
+}
+/** Find the comment figdiff wrote earlier on this pull request, if any. */
+export declare function findComment(api: GitHubApi, repo: string, pr: number): Promise<number | undefined>;
+/** Create the comment, or update the one found earlier so a pull request only ever has one. */
+export declare function upsertComment(api: GitHubApi, repo: string, pr: number, body: string, existing?: number): Promise<"created" | "updated">;

package/dist/action/github.js

@@ -0,0 +1,62 @@
+import { COMMENT_MARKER } from "./comment.js";
+/** An error from the GitHub API, with the HTTP status so callers can tell "no permission" apart. */
+export class GitHubError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+async function request(api, method, path, body) {
+    const res = await api.fetch(`${api.baseUrl}${path}`, {
+        method,
+        headers: {
+            authorization: `Bearer ${api.token}`,
+            accept: "application/vnd.github+json",
+            "x-github-api-version": "2022-11-28",
+            "user-agent": "figdiff-action",
+            ...(body === undefined ? {} : { "content-type": "application/json" }),
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    if (!res.ok) {
+        let detail = "";
+        try {
+            detail = (await res.json()).message ?? "";
+        }
+        catch {
+            // the error body was not JSON
+        }
+        throw new GitHubError(`GitHub API ${method} ${path} failed with ${res.status}${detail ? `: ${detail}` : ""}`, res.status);
+    }
+    return (res.status === 204 ? undefined : await res.json());
+}
+/** Find the comment figdiff wrote earlier on this pull request, if any. */
+export async function findComment(api, repo, pr) {
+    for (let page = 1; page <= 10; page++) {
+        const comments = await request(api, "GET", `/repos/${repo}/issues/${pr}/comments?per_page=100&page=${page}`);
+        const found = comments.find((c) => c.body?.includes(COMMENT_MARKER));
+        if (found)
+            return found.id;
+        if (comments.length < 100)
+            return undefined;
+    }
+    return undefined;
+}
+/** Create the comment, or update the one found earlier so a pull request only ever has one. */
+export async function upsertComment(api, repo, pr, body, existing) {
+    if (existing !== undefined) {
+        try {
+            await request(api, "PATCH", `/repos/${repo}/issues/comments/${existing}`, { body });
+            return "updated";
+        }
+        catch (err) {
+            // The old comment may have been deleted or belong to someone else: fall through and post a new one.
+            if (!(err instanceof GitHubError) || (err.status !== 404 && err.status !== 403))
+                throw err;
+        }
+    }
+    await request(api, "POST", `/repos/${repo}/issues/${pr}/comments`, { body });
+    return "created";
+}
+//# sourceMappingURL=github.js.map

package/dist/action/github.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.js","sourceRoot":"","sources":["../../src/action/github.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,oGAAoG;AACpG,MAAM,OAAO,WAAY,SAAQ,KAAK;IAGzB;IAFX,YACE,OAAe,EACN,MAAc;QAEvB,KAAK,CAAC,OAAO,CAAC,CAAC;QAFN,WAAM,GAAN,MAAM,CAAQ;IAGzB,CAAC;CACF;AASD,KAAK,UAAU,OAAO,CAAI,GAAc,EAAE,MAAc,EAAE,IAAY,EAAE,IAAc;IACpF,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,OAAO,GAAG,IAAI,EAAE,EAAE;QACnD,MAAM;QACN,OAAO,EAAE;YACP,aAAa,EAAE,UAAU,GAAG,CAAC,KAAK,EAAE;YACpC,MAAM,EAAE,6BAA6B;YACrC,sBAAsB,EAAE,YAAY;YACpC,YAAY,EAAE,gBAAgB;YAC9B,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC;SACtE;QACD,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;KAC5D,CAAC,CAAC;IACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,CAAC;YACH,MAAM,GAAI,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA0B,CAAC,OAAO,IAAI,EAAE,CAAC;QACtE,CAAC;QAAC,MAAM,CAAC;YACP,8BAA8B;QAChC,CAAC;QACD,MAAM,IAAI,WAAW,CAAC,cAAc,MAAM,IAAI,IAAI,gBAAgB,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5H,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAM,CAAC;AAClE,CAAC;AAED,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAc,EAAE,IAAY,EAAE,EAAU;IACxE,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC;QACtC,MAAM,QAAQ,GAAG,MAAM,OAAO,CAC5B,GAAG,EACH,KAAK,EACL,UAAU,IAAI,WAAW,EAAE,+BAA+B,IAAI,EAAE,CACjE,CAAC;QACF,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC;QACrE,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC,EAAE,CAAC;QAC3B,IAAI,QAAQ,CAAC,MAAM,GAAG,GAAG;YAAE,OAAO,SAAS,CAAC;IAC9C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,+FAA+F;AAC/F,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,GAAc,EACd,IAAY,EACZ,EAAU,EACV,IAAY,EACZ,QAAiB;IAEjB,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,IAAI,CAAC;YACH,MAAM,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,UAAU,IAAI,oBAAoB,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;YACpF,OAAO,SAAS,CAAC;QACnB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,oGAAoG;YACpG,IAAI,CAAC,CAAC,GAAG,YAAY,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC;gBAAE,MAAM,GAAG,CAAC;QAC7F,CAAC;IACH,CAAC;IACD,MAAM,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,IAAI,WAAW,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7E,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/action/glob.d.ts

@@ -0,0 +1,10 @@
+/** Split an input such as "design/**\/*.figcraft, assets/*.figcraft" (commas or new lines) into patterns. */
+export declare function parsePatterns(input: string): string[];
+/**
+ * Convert a glob to a regular expression. Supports `*` (within a folder), `**` (across folders)
+ * and `?`. `**\/` also matches no folder at all, so `design/**\/*.figcraft` matches
+ * `design/app.figcraft`.
+ */
+export declare function globToRegExp(pattern: string): RegExp;
+/** True when the path matches at least one pattern. */
+export declare function matchesAny(path: string, patterns: string[]): boolean;

package/dist/action/glob.js

@@ -0,0 +1,45 @@
+/** Split an input such as "design/**\/*.figcraft, assets/*.figcraft" (commas or new lines) into patterns. */
+export function parsePatterns(input) {
+    return input
+        .split(/[\n,]/)
+        .map((p) => p.trim().replace(/^\.\//, ""))
+        .filter((p) => p.length > 0);
+}
+/**
+ * Convert a glob to a regular expression. Supports `*` (within a folder), `**` (across folders)
+ * and `?`. `**\/` also matches no folder at all, so `design/**\/*.figcraft` matches
+ * `design/app.figcraft`.
+ */
+export function globToRegExp(pattern) {
+    let source = "";
+    for (let i = 0; i < pattern.length; i++) {
+        const c = pattern[i];
+        if (c === "*") {
+            if (pattern[i + 1] === "*") {
+                i++;
+                if (pattern[i + 1] === "/") {
+                    i++;
+                    source += "(?:.*/)?";
+                }
+                else {
+                    source += ".*";
+                }
+            }
+            else {
+                source += "[^/]*";
+            }
+        }
+        else if (c === "?") {
+            source += "[^/]";
+        }
+        else {
+            source += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+        }
+    }
+    return new RegExp(`^${source}$`);
+}
+/** True when the path matches at least one pattern. */
+export function matchesAny(path, patterns) {
+    return patterns.some((p) => globToRegExp(p).test(path));
+}
+//# sourceMappingURL=glob.js.map

package/dist/action/glob.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.js","sourceRoot":"","sources":["../../src/action/glob.ts"],"names":[],"mappings":"AAAA,6GAA6G;AAC7G,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,KAAK;SACT,KAAK,CAAC,OAAO,CAAC;SACd,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;SACzC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACjC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACxC,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAW,CAAC;QAC/B,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;YACd,IAAI,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;gBAC3B,CAAC,EAAE,CAAC;gBACJ,IAAI,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;oBAC3B,CAAC,EAAE,CAAC;oBACJ,MAAM,IAAI,UAAU,CAAC;gBACvB,CAAC;qBAAM,CAAC;oBACN,MAAM,IAAI,IAAI,CAAC;gBACjB,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,OAAO,CAAC;YACpB,CAAC;QACH,CAAC;aAAM,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;YACrB,MAAM,IAAI,MAAM,CAAC;QACnB,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,CAAC,CAAC,OAAO,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IACD,OAAO,IAAI,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC;AACnC,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,QAAkB;IACzD,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AAC1D,CAAC"}