ci: add lime-elements integration validation workflow

[adrianschmidt-bot]

Summary

Adds a PR check that validates kompendium changes against lime-elements to catch regressions before they're released.

How It Works

1. Build kompendium PR → register for npm linking
2. Checkout lime-elements main branch
3. Stage 1 (Baseline): Build lime-elements docs with published kompendium
4. Stage 2 (PR): Link PR kompendium via npm link and rebuild
5. Validate: Check kompendium.json exists and has valid structure
6. Report: Clear results in GitHub Step Summary

Key Design Decisions

Decision	Rationale
Advisory (non-required)	lime-elements issues shouldn't block kompendium development
Two-stage build	Clearly distinguishes "lime-elements is broken" from "this PR broke it"
npm link over tarball	Avoids npm dependency resolution that can cause conflicting package versions
Aggressive caching	lime-elements is large; cache node_modules by lockfile hash
Fail only on regression	If baseline failed too, it's not this PR's fault

Why npm link instead of tarball?

When installing a tarball, npm re-resolves dependencies which can cause:

• Hoisting issues where conflicting versions get installed at the top level
• Peer dependency auto-installation (npm 7+) modifying existing packages
• Massive dependency tree changes (~250 packages added/removed/changed)

npm link creates a symlink without dependency resolution, preserving lime-elements' existing node_modules structure.

Future improvement: Use a local npm registry (e.g., verdaccio) to publish the PR and install from there. This would perfectly simulate real-world installation behavior.

Failure Behavior

Baseline	PR Build	Result
✅ Pass	✅ Pass	✅ Check passes
✅ Pass	❌ Fail	❌ Regression - check fails
❌ Fail	✅ Pass	✅ Check passes (pre-existing issue)
❌ Fail	❌ Fail	⚠️ Check passes with warning

Additional Changes

This PR also includes two fixes discovered during integration testing:

1. fix(deps): Move typescript from dependencies to devDependencies and update to ^4.9.5

   • TypeDoc uses typescript as a peerDependency, so kompendium shouldn't bundle it
   • Fixes invalid dependency tree (cosmiconfig requires typescript >=4.9.5)

2. fix(typedoc): Use ts.getDecorators() API for TypeScript 4.8+

   • TypeScript 4.8 deprecated node.decorators property
   • New API: ts.canHaveDecorators(node) + ts.getDecorators(node)

Future Enhancements (not in this PR)

• Visual regression testing
• Live preview deployments
• Testing against latest stable tag as additional baseline

Summary by CodeRabbit

• Chores
  • Added an automated validation workflow that builds and compares documentation against a baseline, posts summary statuses to pull requests, and blocks regressions.
  • Moved TypeScript to devDependencies and upgraded its version to ^4.9.5.
  • Improved TypeScript-based decorator handling to be more robust and reduce potential runtime issues.

[adrianschmidt-bot]

Fixed both issues in 685706b:

1. Validation: The structure is .docs.components, not .components - corrected
2. Caching: Added cache: 'npm' to setup-node for kompendium. Kept actions/cache for lime-elements' node_modules since setup-node only caches npm's global cache, not node_modules from external repos.

[Copilot]

Pull request overview

Adds a new advisory GitHub Actions workflow that builds lime-elements docs twice (baseline vs. PR kompendium) to detect kompendium regressions against lime-elements before release.

Changes:

• Introduces .github/workflows/validate-lime-elements.yml to build kompendium, pack it, and run a two-stage lime-elements docs build (published vs PR tarball).
• Adds validation of generated .kompendium/kompendium.json structure and publishes a Step Summary.
• Implements a “fail only on regression” gate based on baseline vs PR outcomes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[adrianschmidt-bot]

Addressed all Copilot review feedback in 3923acf:

1. ✅ continue-on-error for PR build — Now the job won't fail immediately, allowing the regression gate to work properly
2. ✅ Conditional validation — Only runs if PR build succeeded, with outcome included in regression check
3. ✅ Concurrency group fix — Now uses ${{ github.repository }}-${{ github.event.pull_request.number }} to avoid fork collisions
4. ✅ Cache key robustness — Added runner OS and node version to the cache key
5. ✅ npm pack output — Tarball name now captured directly from npm pack output instead of ls

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[adrianschmidt]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new CI workflow that builds a baseline with the published kompendium, packs and installs the kompendium PR tarball into lime-elements, runs a PR docs build, validates the produced kompendium.json (existence, valid JSON, .docs.components) and fails the PR on regressions.

Changes

Cohort / File(s)	Summary
GitHub Actions Workflow /.github/workflows/validate-lime-elements.yml	Adds a workflow that checks out the kompendium PR and lime-elements, sets up Node, builds & packs the kompendium PR, runs a baseline build with the published kompendium and a PR build with the packed tarball, validates kompendium.json (exists, JSON parse, .docs.components), reports component counts/warnings, posts a PR summary, and fails on regressions.
Package manifest package.json	Moves typescript from dependencies to devDependencies and updates TypeScript from ^4.7.4 to ^4.9.5.
TypeScript AST access src/kompendium/typedoc.ts	Replaces unsafe (node as any).decorators access with guarded API: ts.canHaveDecorators(node) ? ts.getDecorators(node) : undefined to safely retrieve decorators.

Sequence Diagram(s)

sequenceDiagram
    participant PR as Kompendium PR
    participant GA as GitHub Actions
    participant Node as Node/npm
    participant LE as lime-elements repo
    participant Validator as kompendium.json validator

    rect rgba(100,150,240,0.5)
    PR->>GA: open PR -> trigger workflow
    end

    GA->>PR: checkout kompendium PR
    GA->>Node: setup Node.js & cache deps
    GA->>PR: build & pack kompendium -> tarball

    GA->>LE: checkout lime-elements (main)
    GA->>LE: restore/cache node_modules

    rect rgba(150,200,120,0.5)
    GA->>LE: baseline build (published kompendium)
    LE->>GA: baseline artifacts/status
    end

    rect rgba(240,180,120,0.5)
    GA->>LE: install PR tarball
    GA->>LE: PR build
    LE->>Validator: emit kompendium.json for validation
    Validator->>GA: validation result (exists, JSON, .docs.components) + counts
    end

    GA->>PR: post PR summary & mark fail on regression

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐇 I packed a tarball, hopped into CI's light,

Baseline ran first, then the PR's flight,
JSON counted components, truthful and spry,
I twitched my whiskers — pass, warn, or cry,
A rabbit hums: validate, then merge tonight.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the primary change: adding a GitHub Actions CI workflow to validate lime-elements integration.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

No actionable comments were generated in the recent review. 🎉

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @.github/workflows/validate-lime-elements.yml:
- Around line 47-60: The cache step using actions/cache@v4 (step id: cache-le)
currently saves lime-elements/node_modules after later running `npm link
kompendium`, which inserts workspace-specific symlinks that poison the cache;
change the workflow to use separate restore and save actions
(actions/cache/restore@v4 and actions/cache/save@v4) so you restore before `npm
ci` and save immediately after `npm ci` (and before the `npm link kompendium`
step) to ensure the cached node_modules are the clean, link-free state; update
the cache key usage the same way but only perform the final save prior to
running `npm link kompendium`.

[adrianschmidt]

@coderabbitai resume

[coderabbitai]

✅ Actions performed

Reviews resumed.

[jgroth]

🎉 This PR is included in version 1.0.1 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀