From 332e5e36a6fb6940fcdc38b2fb4b2a8b668795a9 Mon Sep 17 00:00:00 2001 From: brovatten Date: Fri, 12 Jun 2026 09:05:16 +0200 Subject: [PATCH 1/3] docs: mock up per-component file dropdowns for the sticky PR comment Two candidate formats for listing changed files under each changed component, rendered as collapsed
blocks below the diagram: Variant A (component -> changed files) and Variant B (component -> file dropdowns -> methods tagged added/modified/removed). Mockup only, no action behavior change. Co-Authored-By: Claude Fable 5 --- docs/mockups/pr-comment-file-dropdowns.md | 207 ++++++++++++++++++++++ 1 file changed, 207 insertions(+) create mode 100644 docs/mockups/pr-comment-file-dropdowns.md diff --git a/docs/mockups/pr-comment-file-dropdowns.md b/docs/mockups/pr-comment-file-dropdowns.md new file mode 100644 index 0000000..5d5e240 --- /dev/null +++ b/docs/mockups/pr-comment-file-dropdowns.md @@ -0,0 +1,207 @@ +# Mockup: per-component file dropdowns in the sticky PR comment + +The sticky PR comment currently shows the Mermaid diff diagram, the color legend, +and the CTA footer — but never lists *which files* made a component change color. +The data is already there: every component in `analysis.json` carries +`file_methods[]` (file paths + methods), which the diff logic uses internally but +never renders. + +This doc mocks up two candidate formats, both using collapsed-by-default +`
` blocks below the legend so the diagram stays the hero. The same two +variants are posted as comments on the mockup PR so they can be compared exactly +as reviewers would see them. All component/file/method names below are invented. + +--- + +## Variant A — component → changed files + +One dropdown per changed component; expanding it lists the files in that +component that the PR actually touched (intersection of the component's +`file_methods[]` with the git diff — not the component's full file list). + +--- + +### Architecture review · 3 components changed + +```mermaid +graph LR + API["API Gateway"] + AUTH["AuthService"] + RL["RateLimiter"] + LSS["LegacySessionStore"] + DB["UserStore"] + API -- "authenticates via" --> AUTH + API -- "throttled by" --> RL + AUTH -- "reads/writes" --> DB + AUTH -- "persisted sessions in" --> LSS + classDef added fill:#1f883d,stroke:#0b5d23,color:#ffffff; + classDef modified fill:#bf8700,stroke:#7d4e00,color:#ffffff; + classDef deleted fill:#cf222e,stroke:#82071e,color:#ffffff,stroke-dasharray:5 3; + class RL added; + class AUTH modified; + class LSS deleted; + linkStyle 1 stroke:#0b5d23,stroke-width:2px; + linkStyle 3 stroke:#82071e,stroke-width:2px,stroke-dasharray:5 3; +``` + +Colors indicate component changes compared to `main`: 🟩 Added · 🟨 Modified · 🟥 Removed + +
+🟨 AuthService — 3 files changed + +- `src/auth/handler.py` +- `src/auth/session.py` +- `src/auth/middleware.py` + +
+
+🟩 RateLimiter — 2 files added + +- `src/ratelimit/bucket.py` +- `src/ratelimit/config.py` + +
+
+🟥 LegacySessionStore — 2 files removed + +- `src/auth/legacy/store.py` +- `src/auth/legacy/migrations.py` + +
+ +--- + +See this architecture in your editor: [**Open in VS Code →**](https://marketplace.visualstudio.com/items?itemName=Codeboarding.codeboarding) + +codeboarding-action · run 0000000001 · **mockup — Variant A: component → changed files** + +--- + +## Variant B — component → files → methods + +Same as Variant A, but each file is itself a dropdown that reveals the changed +methods inside it, each tagged added / modified / removed. The inner dropdowns +sit in a `
` so they indent under their component. + +--- + +### Architecture review · 3 components changed + +```mermaid +graph LR + API["API Gateway"] + AUTH["AuthService"] + RL["RateLimiter"] + LSS["LegacySessionStore"] + DB["UserStore"] + API -- "authenticates via" --> AUTH + API -- "throttled by" --> RL + AUTH -- "reads/writes" --> DB + AUTH -- "persisted sessions in" --> LSS + classDef added fill:#1f883d,stroke:#0b5d23,color:#ffffff; + classDef modified fill:#bf8700,stroke:#7d4e00,color:#ffffff; + classDef deleted fill:#cf222e,stroke:#82071e,color:#ffffff,stroke-dasharray:5 3; + class RL added; + class AUTH modified; + class LSS deleted; + linkStyle 1 stroke:#0b5d23,stroke-width:2px; + linkStyle 3 stroke:#82071e,stroke-width:2px,stroke-dasharray:5 3; +``` + +Colors indicate component changes compared to `main`: 🟩 Added · 🟨 Modified · 🟥 Removed + +
+🟨 AuthService — 3 files · 6 methods changed +
+ +
+🟨 src/auth/handler.py · 3 methods + +- 🟩 `validate_token` added +- 🟨 `login` modified +- 🟥 `legacy_login` removed + +
+
+🟨 src/auth/session.py · 1 method + +- 🟨 `refresh` modified + +
+
+🟩 src/auth/middleware.py · 2 methods + +- 🟩 `require_auth` added +- 🟩 `inject_claims` added + +
+ +
+
+
+🟩 RateLimiter — 2 files · 3 methods added +
+ +
+🟩 src/ratelimit/bucket.py · 2 methods + +- 🟩 `acquire` added +- 🟩 `refill` added + +
+
+🟩 src/ratelimit/config.py · 1 method + +- 🟩 `load_limits` added + +
+ +
+
+
+🟥 LegacySessionStore — 2 files · 4 methods removed +
+ +
+🟥 src/auth/legacy/store.py · 3 methods + +- 🟥 `get_session` removed +- 🟥 `put_session` removed +- 🟥 `evict_expired` removed + +
+
+🟥 src/auth/legacy/migrations.py · 1 method + +- 🟥 `migrate_v1_sessions` removed + +
+ +
+
+ +--- + +See this architecture in your editor: [**Open in VS Code →**](https://marketplace.visualstudio.com/items?itemName=Codeboarding.codeboarding) + +codeboarding-action · run 0000000002 · **mockup — Variant B: component → files → methods** + +--- + +## Implementation notes (if either variant is adopted) + +- **List changed files only.** Intersect each component's `file_methods[]` paths + with the PR's git diff. A component can own 40 files while the PR touched 2 — + listing all of them answers the wrong question. +- **Method statuses** (Variant B) come from comparing base vs head + `file_methods[].methods` per file — the same comparison + `_has_method_changes()` already does, surfaced instead of discarded. +- **Comment size cap.** GitHub caps comment bodies at 65,536 chars and the + Mermaid block alone may use ~45k. Cap files per component (e.g. 15 + + "…and N more") and drop the dropdowns before dropping the diagram. +- **Rendering gotchas.** Markdown inside `
` needs a blank line after + ``; nested dropdowns need the `
` wrapper for indentation. + Build the block in a Python helper next to `build_cta.py` rather than inline + bash in `action.yml`. +- **Deleted components/files** don't exist on the head ref — render paths as + plain code spans, not links. From d17345705dd66cbe96e930f135e63ad6f4e26f27 Mon Sep 17 00:00:00 2001 From: brovatten Date: Fri, 12 Jun 2026 09:20:34 +0200 Subject: [PATCH 2/3] docs: index the 10 additional format variants posted on the mockup PR Co-Authored-By: Claude Fable 5 --- docs/mockups/pr-comment-file-dropdowns.md | 28 +++++++++++++++++++---- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/docs/mockups/pr-comment-file-dropdowns.md b/docs/mockups/pr-comment-file-dropdowns.md index 5d5e240..d8e1ed3 100644 --- a/docs/mockups/pr-comment-file-dropdowns.md +++ b/docs/mockups/pr-comment-file-dropdowns.md @@ -6,10 +6,11 @@ The data is already there: every component in `analysis.json` carries `file_methods[]` (file paths + methods), which the diff logic uses internally but never renders. -This doc mocks up two candidate formats, both using collapsed-by-default -`
` blocks below the legend so the diagram stays the hero. The same two -variants are posted as comments on the mockup PR so they can be compared exactly -as reviewers would see them. All component/file/method names below are invented. +This doc details two candidate formats (A and B below); ten further variants +(C–L) live as comments on the mockup PR (#26) so they can be compared exactly as +reviewers would see them — an index is at the end of this doc. All +component/file/method names are invented, and every variant uses the same toy +data so the formats are directly comparable. --- @@ -188,7 +189,24 @@ See this architecture in your editor: [**Open in VS Code →**](https://marketpl --- -## Implementation notes (if either variant is adopted) +## Index of all variants (posted as comments on PR #26) + +| Variant | Format | Always-visible footprint | +|:-:|:--|:--| +| A | One dropdown per component → changed files | one summary line per component | +| B | Component → file dropdowns → methods (nested) | one summary line per component | +| C | Compact pipe table with `+3 ~2 −1` method deltas | one table row per component | +| D | Single dropdown → native diff manifest with `@@` component hunks | one line | +| E | Single dropdown → monospace file tree grouped by directory | one line | +| F | Blast-radius-ordered review checklist (live checkboxes) | one line per step | +| G | Question-grouped: `[!IMPORTANT]` alert for removals + two dropdowns | alert + two lines | +| H | HTML cross-tab (`+/~/−` columns) with dropdowns inside cells | one table row per component | +| I | Release-notes prose: Added / Changed / Removed sentences | one sentence per component | +| J | One italic "dek" sentence above the diagram + single changelog dropdown | one sentence + one line | +| K | Typographic ledger: one line per component, methods in small type | one line per component | +| L | Narrative paragraph with GFM footnotes carrying the manifest | one paragraph | + +## Implementation notes (if a variant is adopted) - **List changed files only.** Intersect each component's `file_methods[]` paths with the PR's git diff. A component can own 40 files while the PR touched 2 — From 287b0106f01db99406f75c8347e03b58464b25de Mon Sep 17 00:00:00 2001 From: brovatten Date: Fri, 12 Jun 2026 09:39:38 +0200 Subject: [PATCH 3/3] docs: index the 4 simplistic variants (M-P) posted on the mockup PR Co-Authored-By: Claude Fable 5 --- docs/mockups/pr-comment-file-dropdowns.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/mockups/pr-comment-file-dropdowns.md b/docs/mockups/pr-comment-file-dropdowns.md index d8e1ed3..8b444f4 100644 --- a/docs/mockups/pr-comment-file-dropdowns.md +++ b/docs/mockups/pr-comment-file-dropdowns.md @@ -205,6 +205,10 @@ See this architecture in your editor: [**Open in VS Code →**](https://marketpl | J | One italic "dek" sentence above the diagram + single changelog dropdown | one sentence + one line | | K | Typographic ledger: one line per component, methods in small type | one line per component | | L | Narrative paragraph with GFM footnotes carrying the manifest | one paragraph | +| M | One-liner: component names + file counts | one line | +| N | Flat bullets: component + file basenames inline | one bullet per component | +| O | Single dropdown → plain nested list (component → full paths) | one line | +| P | Plain monospace block: name, status, files — no markup at all | one block | ## Implementation notes (if a variant is adopted)