Mermaid PR architecture-diff action (level-1 default, nested opt-in)#2
Open
brovatten wants to merge 12 commits into
Open
Mermaid PR architecture-diff action (level-1 default, nested opt-in)#2brovatten wants to merge 12 commits into
brovatten wants to merge 12 commits into
Conversation
…t-in)
Replaces the webview/Playwright PNG approach with an inline Mermaid diagram
that GitHub renders natively in the PR comment — no image, no orphan branch,
no contents:write, and fork-friendly.
How it works:
- Resolve a base ("before") analysis: use the committed
.codeboarding/analysis.json at the PR base if present, else generate one via
a full engine run on the base commit.
- Analyze the PR head incrementally, seeded from the base (stable component
ids), falling back to a full run on cache miss.
- scripts/diff_to_mermaid.py diffs the two analyses (name-based matching;
relation label change => modified) and emits a graph LR with nodes colored
via classDef/class and arrows via positional linkStyle: green added, yellow
modified, red dashed deleted. Escaping, deleted-namespace keying, and a size
guard (GitHub's ~500-edge / 50k-char cap -> changed-only or text fallback).
Rendering:
- Level 1 (flat, top-level) is the default — readable inline, never trips the
size cap.
- nested: true draws depth>1 sub-components as subgraphs (leaf nodes filled,
parent containers outlined). Optional --font-size/--node-padding/spacing emit
an %%{init}%% directive to enlarge nodes.
scripts/run_local.sh mirrors the action for local iteration (fast diff-only or
full pipeline) and writes a browser HTML preview rendered with mermaid.js.
Architecture review · 6 components changedgraph LR
n_Orchestration_Rendering["Orchestration & Rendering"]
n_Diff_Analysis_Engine["Diff Analysis Engine"]
n_User_Engagement_Integration_CTA_["User Engagement & Integration (CTA)"]
del_Environment_Context_Resolver["Environment & Context Resolver"]
del_Remote_Job_Orchestrator["Remote Job Orchestrator"]
del_Artifact_Result_Processor["Artifact & Result Processor"]
n_Orchestration_Rendering -- "Passes raw JSON analysis data to" --> n_Diff_Analysis_Engine
n_Diff_Analysis_Engine -- "Returns structured diff object to" --> n_Orchestration_Rendering
n_Orchestration_Rendering -- "Triggers generation of interactive links in" --> n_User_Engagement_Integration_CTA_
del_Environment_Context_Resolver -- "passes resolved repository URL and branch to in…" --> del_Remote_Job_Orchestrator
del_Remote_Job_Orchestrator -- "hands off JSON response containing full job res…" --> del_Artifact_Result_Processor
del_Artifact_Result_Processor -- "writes extracted documentation data to runner f…" --> del_Artifact_Result_Processor
del_Remote_Job_Orchestrator -- "manages job configuration and polls for status…" --> del_Remote_Job_Orchestrator
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 n_Orchestration_Rendering,n_Diff_Analysis_Engine,n_User_Engagement_Integration_CTA_ added;
class del_Environment_Context_Resolver,del_Remote_Job_Orchestrator,del_Artifact_Result_Processor deleted;
linkStyle 0,1,2 stroke:#0b5d23,stroke-width:2px;
linkStyle 3,4,5,6 stroke:#82071e,stroke-width:2px,stroke-dasharray:5 3;
Colours indicate components that have been 🟩 added · 🟨 modified · 🟥 removed — versus 🧭 See this architecture in your editor: Open in VS Code → 💡 New to CodeBoarding? Get the extension → codeboarding-action · run 26918728374 |
…ace/extension CTA via click proxy
…n editor' CTA Move CTA building into scripts/build_cta.py (testable; docstring cites the 2025 SO survey: VS Code 75.9% + Cursor 17.9% ~= 94% justifies VS Code+Cursor only). .vscode dir -> VS Code, .cursor -> Cursor, both -> both, neither -> VS Code.
depth_level drives the engine (deep, rich data); new render_depth controls how many component levels the PR Mermaid draws (default 1 = top-level flat). Replaces the nested boolean. Self-test now runs depth_level=2 + render_depth=1.
…rl), unit tests + CI - engine_ref default main -> v0.12.0 (verified to have the run_full/run_incremental/ health/StaticAnalysisCache API); reproducible default, overridable. - README: engine_ref + cta_base_url rows; depth_level vs render_depth clarified. - tests/: 21 stdlib unittest cases for diff_to_mermaid + build_cta. - .github/workflows/test.yml runs them on push/PR (no LLM).
…cache The manual .venv cache was restored then immediately wiped by 'uv venv --clear', so it never helped. Reuse it when present and enable uv's download cache for cold installs.
Guard now resolves the PR from either a pull_request event or an issue_comment '/codeboarding' command (comment body read from env, never interpolated -> no injection; SHAs fetched via gh api). Reacts 👀 to acknowledge. Configurable via trigger_command. Sticky comment + base_ref now use the resolved PR explicitly.
…e); CTA -> extension-direct - docs/COMMIT_STRATEGY.md: commit analysis.json + health_report.json (text, display-critical); do NOT commit static_analysis.pkl (binary -> actions/cache). Forward-compatible with a future hosted webview. - build_cta: drop the 'explore in browser' webview tier (deferred); footer now drives straight to the extension (open in VS Code/Cursor + get the extension).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Replaces the webview/Playwright PNG approach with an inline Mermaid diagram GitHub renders natively in the PR comment.
.codeboarding/analysis.jsonif present, else a full engine run on the base commit; head analyzed incrementally from it.scripts/diff_to_mermaid.pydiffs the two analyses and emits a coloredgraph LR(green added / yellow modified / red deleted, nodes + arrows).nested: truefor depth>1 subgraphs.scripts/run_local.shfor local iteration.The
test-self.ymlworkflow runs this action on this PR as a live test (remove before merge). This PR comment thread should get an architecture-diff comment shortly.