feat: improve SVG diagram embedding and add release automation

[sheldonj]

Summary

• Descriptive alt text — SVG image references now use the entity name (e.g. ![User diagram]) instead of generic ![diagram] for better accessibility and hover tooltips
• Inline SVG embedding — new diagramEmbed plugin option ('file' | 'inline'). When set to 'inline', SVG XML is embedded directly in the markdown, making pages fully self-contained with no companion files
• Responsive wrapper — all diagram outputs are wrapped in <div style="max-width:100%;overflow-x:auto"> so large diagrams scroll horizontally instead of overflowing
• Enhanced SKILL.md — added Mermaid ERD, consolidated relationships table, access policy matrix, compact field summaries, and improved workflow section. Fixed mixin-inherited fields not appearing via getAllFields. Routed SKILL.md through the SVG rendering pipeline
• Release Please — automated versioning and changelog generation via conventional commits. Merging PRs to main creates a Release PR; merging that triggers npm publish
• CONTRIBUTING.md — documented conventional commit format and updated stale monorepo references

Test plan

• All 168 tests pass (pnpm test)
• TypeScript compiles cleanly (pnpm run typecheck)
• ESLint passes (pnpm run lint)
• New tests for descriptive alt text, responsive wrapper, and inline SVG embedding (8 new tests in diagram-svg.test.ts)
• Updated skill-page tests for new section structure and SVG alt text
• Verify Release Please workflow triggers correctly after merge to main

Summary by CodeRabbit

• New Features

  • Added diagramEmbed configuration option to control SVG diagram display ("file" for external references or "inline" for embedded content)
  • Enhanced SKILL page documentation with relationships visualization, policy matrix, field summaries, and structured validation sections
  • Automated release workflow for streamlined version management

• Documentation

  • Updated README with diagram embedding configuration details and usage examples
  • Improved SKILL page guidance with creation order, include patterns, and better workflow instructions

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 53d6e99a-e669-428f-a227-8d780bed6508

📥 Commits

Reviewing files that changed from the base of the PR and between 9de3936 and 3b4baab.

📒 Files selected for processing (1)

• eslint.config.js

---

📝 Walkthrough

Walkthrough

This pull request introduces release automation infrastructure via GitHub Actions and release-please configuration, adds a new diagramEmbed feature to control SVG diagram embedding modes (file-based or inline), substantially refactors skill page rendering to include relationships, validation matrices, and topological ordering, and updates documentation and tests accordingly.

Changes

Cohort / File(s)	Summary
Release Automation Setup .github/workflows/release-please.yml, .release-please-manifest.json, release-please-config.json	Adds GitHub Actions workflow and configuration files for automated release management using googleapis/release-please-action. Configures changelog sections to display features, fixes, and performance as visible sections while hiding docs, chore, test, ci, and refactor.
Documentation Updates CONTRIBUTING.md, README.md	CONTRIBUTING.md overhauled to document release workflow, Conventional Commits, commit type semantics with version bumps, breaking change guidance, and updated build/preview commands. README.md adds new diagramEmbed configuration option ("file" or "inline") and expands diagram format documentation with embed behavior and examples.
Configuration Updates eslint.config.js	Extends ESLint ignores to exclude release-please files and adds package.json config block with jsonc/sort-keys override.
Diagram Embedding Feature src/generator.ts, src/renderers/diagram-processor.ts	Introduces diagramEmbed option ('file' | 'inline') threaded through rendering pipeline. Updates writePageWithDiagrams and processDiagrams signatures to accept embed parameter. Implements responsive SVG container wrapping and conditional logic for inline vs. file-based embedding with Mermaid source fallbacks.
Skill Page Rendering Enhancement src/renderers/skill-page.ts	Major refactoring adding relationships visualization (renderRelationshipMap, renderRelationshipsTable), validation/access policy matrix (renderPolicyMatrix), topological sort for FK-respecting creation order, consolidated Validation section, field summaries with include patterns, and enhanced workflow guidance. Replaces schema with relations in public interface.
Type System Updates src/types.ts	Adds diagramEmbed?: 'file' | 'inline' to PluginOptions. Changes SkillPageProps.schema to relations?: Relationship[] to expose relationship data.
Test Suite Updates test/generator/diagram-svg.test.ts, test/generator/skill-page.test.ts, test/integration/showcase.test.ts	Comprehensive test additions for inline and file-based diagram embedding modes, descriptive alt text validation, responsive container verification, and extensive skill page rendering tests covering relationships table, access policies matrix, field summaries, topological sort, and diagram format variations. Updates integration test expectations for new Validation and Relationships sections.

Sequence Diagram(s)

sequenceDiagram
    participant Gen as Generator
    participant DP as Diagram Processor
    participant FS as File System
    participant Out as Markdown Output
    
    rect rgba(100, 150, 200, 0.5)
    Note over Gen,Out: File-based Embedding (Default)
    Gen->>DP: processDiagrams(..., embed='file')
    DP->>FS: Queue SVG file for writing
    DP->>Out: Insert markdown image reference<br/>![Entity diagram](./Entity-diagram.svg)
    DP-->>Out: Wrap in responsive container
    end
    
    rect rgba(150, 200, 100, 0.5)
    Note over Gen,Out: Inline Embedding
    Gen->>DP: processDiagrams(..., embed='inline')
    DP->>Out: Inline SVG content directly<br/>into markdown
    DP-->>Out: Wrap in responsive container
    DP-->>Out: Add collapsible Mermaid source<br/>(if format='both')
    end

Loading

sequenceDiagram
    participant Gen as Generator
    participant SP as Skill Page Renderer
    participant Out as Markdown Output
    
    rect rgba(200, 150, 100, 0.5)
    Note over Gen,Out: Enhanced Skill Page Rendering
    Gen->>SP: renderSkillPage(SkillPageProps + relations)
    SP->>Out: Render Relationships Table<br/>(From, Field, To, Cardinality)
    SP->>Out: Render Access Policy Matrix<br/>(Model x Operation x Rule)
    SP->>SP: topologicalSort(models by FK)
    SP->>Out: Render Creation Order<br/>based on FK dependencies
    SP->>Out: Render Include Patterns<br/>& Field Summaries
    SP->>Out: Consolidated Validation Section<br/>(inherited from constraints)
    end

Loading

Estimated Code Review Effort

🎯 4 (Complex) | ⏱️ ~55 minutes

Poem

🐰 Diagrams now float free or stay tucked in files,
Release automation makes versioning smile,
Relationships mapped with topological grace,
Validation and policies find their place,
A skill page reborn, more eloquent still! ✨

🚥 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 'feat: improve SVG diagram embedding and add release automation' accurately and specifically captures the two main changes in the PR: SVG diagram improvements and release automation setup.
Docstring Coverage	✅ Passed	Docstring coverage is 92.59% 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 (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/improve-skill-generation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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