feat: auto-detect depth_level from committed baseline by ivanmilevtues · Pull Request #34 · CodeBoarding/CodeBoarding-action

ivanmilevtues · 2026-06-15T13:32:21Z

What

When depth_level is empty (the new default), the action reads metadata.depth_level from the committed .codeboarding/analysis.json:

Sync mode: from the working-tree checkout
Review mode: from the PR base SHA via git show

Falls back to 2 when no baseline exists or the field is missing/unparseable. An explicit depth_level input always overrides auto-detection.

Why

Consumers currently hardcode depth_level: '2' in their sync workflows. If the committed baseline was generated at a different depth, this mismatch either forces an unnecessary full regeneration or silently uses the wrong depth. Auto-detection eliminates this — the workflow stays in sync with the baseline automatically.

Changes

action.yml: input default changed from '2' to '' (auto)
New Resolve analysis depth step after checkout, before analysis
All 12 downstream references (cache keys, env vars, validate-base) now use steps.resolve_depth.outputs.depth
Guard validation updated to accept empty

When depth_level input is empty (new default), the action reads metadata.depth_level from the committed .codeboarding/analysis.json: - sync mode: from the working-tree checkout - review mode: from the PR base SHA via git show Falls back to 2 when no baseline exists or the field is missing. An explicit depth_level input always overrides auto-detection.

codeboarding-review · 2026-06-15T13:32:36Z

Architecture review · no architectural changes

graph LR
    n_Workflow_Controller["Workflow Controller"]
    n_Structural_Analysis_Engine["Structural Analysis Engine"]
    n_Developer_Experience_DevEx_Layer["Developer Experience #40;DevEx#41; Layer"]
    n_Telemetry_Integration_Gateway["Telemetry #amp; Integration Gateway"]
    n_Workflow_Controller -- "Triggers the analysis process and passes enviro…" --> n_Structural_Analysis_Engine
    n_Structural_Analysis_Engine -- "Provides rendered diagrams and diffs for PR com…" --> n_Developer_Experience_DevEx_Layer
    n_Workflow_Controller -- "Sends execution status and health check results" --> n_Telemetry_Integration_Gateway
    n_Developer_Experience_DevEx_Layer -- "Forwards user-initiated feedback and interactio…" --> n_Telemetry_Integration_Gateway
    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;

Colors indicate component changes compared to main: 🟩 Added · 🟨 Modified · 🟥 Removed

Explore this PR’s architecture in your browser or VS Code.

_{codeboarding-action · run 27549876297}

ivanmilevtues · 2026-06-15T13:53:45Z

+        DEPTH=2
+        if [ "$MODE" = "sync" ]; then
+          if [ -f "$TARGET_REPO/.codeboarding/analysis.json" ]; then
+            DEPTH=$(python3 -c "import json; print(json.load(open('$TARGET_REPO/.codeboarding/analysis.json')).get('metadata',{}).get('depth_level',2))" 2>/dev/null || echo 2)


This is the important line.

Amp-Thread-ID: https://ampcode.com/threads/T-019ecb81-dc76-76cb-8bf3-22a366c9be41 Co-authored-by: Amp <amp@ampcode.com>

Amp-Thread-ID: https://ampcode.com/threads/T-019ecb81-dc76-76cb-8bf3-22a366c9be41 Co-authored-by: Amp <amp@ampcode.com> # Conflicts: # .codeboarding/analysis.json # .codeboarding/health/health_report.json

ivanmilevtues

Sync works on your main branch (Configurable)

For a review/PR (the user decides on what action), we will look for the first PR in the history which has anlaysis.json and do iterative on it, if not a full analysis.

The result will be uploaded and the link is in the description for now.

ivanmilevtues · 2026-06-15T19:48:42Z

        REPO_NAME: ${{ github.event.repository.name }}
        RUN_ID_BASE: ${{ github.run_id }}-${{ github.run_attempt }}-base
-        DEPTH: ${{ inputs.depth_level }}
+        DEPTH: ${{ steps.resolve_depth.outputs.depth }}


this is important change

Iiuc, it's either the default from before or what the user provides as input?

ivanmilevtues · 2026-06-15T19:49:28Z

+    - name: Upload PR analysis artifact
+      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review'
+      id: upload_review_artifact
+      uses: actions/upload-artifact@v4


THis is the other important thing

ivanmilevtues · 2026-06-15T19:51:49Z

+        OWNER_REPO: ${{ github.repository }}
+        RUN_ID: ${{ github.run_id }}
+        RUN_ATTEMPT: ${{ github.run_attempt }}
+      run: |


This is the imporant new thing where we upload the artifacts: analysis.json and manifest.json (contains base refs)

ivanmilevtues · 2026-06-15T19:53:07Z

+        # Use the newest analysis.json reachable by walking backwards through
+        # the PR head branch ancestry. If the PR branch is a->b->c->d and master
+        # is a->b->m1->m2, this deliberately searches d,c,b,a — not m2,m1,b,a.
+        while IFS= read -r candidate; do


This is the new thing which resolves the proper analysis.json to be based on going backwards in time as it says above. IT goes back on the branch that is about to be merged.

Svilen-Stefanov

Apart from the other questions, I have two other things I'm wondering:

do we want to make the action configurable to either run on every commit or run only when prompted?
what's the retention time of the artifacts and do they get lost after deleting a branch? I suppose one downside of this is the fact that we loose information sooner than later but I think it's okay for now.

Svilen-Stefanov · 2026-06-15T20:48:25Z

+    head_sha: str,
+    base_sha: str,
+    *,
+    pr: str = "",


One thing that I noticed here - this design suggests that we cannot compare branches without PRs, right? That might change the way we show things on the webview as well

Svilen-Stefanov · 2026-06-15T20:51:07Z


+def _supported_depth(metadata: dict) -> int | None:
+    depth = _metadata_depth(metadata)
+    return depth if depth in range(1, 4) else None


Should we make this global to be easier to see?

hmm, probably if you have license this should be fine and there shouldn't be any limit

Svilen-Stefanov · 2026-06-15T20:58:30Z

 *.py[cod]

 # CodeBoarding generated cache/log artifacts
-.codeboarding/static_analysis.pkl


Why are we removing only these? I suppose we should either keep all of these ignored or remove them all or do we treat the pkl and the other files (e.g healh) differently?
I suppose we want to still keep them all ignored and only the action commits them in the main branch?

One strange thing for me with this is that if they are ignored, someone will think they could be removed from main overall. If they are not, they could be committed. I guess they should generally remain ignored?

fair probably, then the extension will need to force add and push them

Svilen-Stefanov · 2026-06-15T21:06:46Z

        REPO_NAME: ${{ github.event.repository.name }}
        RUN_ID_BASE: ${{ github.run_id }}-${{ github.run_attempt }}-base
-        DEPTH: ${{ inputs.depth_level }}
+        DEPTH: ${{ steps.resolve_depth.outputs.depth }}


Iiuc, it's either the default from before or what the user provides as input?

Amp-Thread-ID: https://ampcode.com/threads/T-019ecb81-dc76-76cb-8bf3-22a366c9be41 Co-authored-by: Amp <amp@ampcode.com>

chore(codeboarding): update architecture analysis

5c1509e

ivanmilevtues commented Jun 15, 2026

View reviewed changes

ivanmilevtues and others added 2 commits June 15, 2026 19:49

feat: store PR analysis artifacts

b1e06a8

Amp-Thread-ID: https://ampcode.com/threads/T-019ecb81-dc76-76cb-8bf3-22a366c9be41 Co-authored-by: Amp <amp@ampcode.com>

fix: trust committed PR baseline

99358c0

Amp-Thread-ID: https://ampcode.com/threads/T-019ecb81-dc76-76cb-8bf3-22a366c9be41 Co-authored-by: Amp <amp@ampcode.com>

ivanmilevtues self-assigned this Jun 15, 2026

ivanmilevtues and others added 5 commits June 15, 2026 21:37

fix: find nearest committed PR baseline

4fd34d4

Amp-Thread-ID: https://ampcode.com/threads/T-019ecb81-dc76-76cb-8bf3-22a366c9be41 Co-authored-by: Amp <amp@ampcode.com>

fix: log review analysis mode

ddde28f

Amp-Thread-ID: https://ampcode.com/threads/T-019ecb81-dc76-76cb-8bf3-22a366c9be41 Co-authored-by: Amp <amp@ampcode.com>

fix: minimize review artifact payload

26e02f5

Amp-Thread-ID: https://ampcode.com/threads/T-019ecb81-dc76-76cb-8bf3-22a366c9be41 Co-authored-by: Amp <amp@ampcode.com>

fix: resolve review baseline from PR head history

ff27892

Amp-Thread-ID: https://ampcode.com/threads/T-019ecb81-dc76-76cb-8bf3-22a366c9be41 Co-authored-by: Amp <amp@ampcode.com>

Merge remote-tracking branch 'origin/main' into feat/depth-auto-detect

7b13c3c

Amp-Thread-ID: https://ampcode.com/threads/T-019ecb81-dc76-76cb-8bf3-22a366c9be41 Co-authored-by: Amp <amp@ampcode.com> # Conflicts: # .codeboarding/analysis.json # .codeboarding/health/health_report.json

ivanmilevtues commented Jun 15, 2026

View reviewed changes

Svilen-Stefanov approved these changes Jun 15, 2026

View reviewed changes

ivanmilevtues and others added 2 commits June 16, 2026 00:19

refactor: rename default depth parameter

5be29a1

Amp-Thread-ID: https://ampcode.com/threads/T-019ecb81-dc76-76cb-8bf3-22a366c9be41 Co-authored-by: Amp <amp@ampcode.com>

fix: ignore generated CodeBoarding artifacts

3ac95e5

Amp-Thread-ID: https://ampcode.com/threads/T-019ecb81-dc76-76cb-8bf3-22a366c9be41 Co-authored-by: Amp <amp@ampcode.com>

Conversation

ivanmilevtues commented Jun 15, 2026

What

Why

Changes

Uh oh!

codeboarding-review Bot commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Architecture review · no architectural changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ivanmilevtues left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Svilen-Stefanov left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codeboarding-review Bot commented Jun 15, 2026 •

edited

Loading