Skip to content

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, this project adheres to Semantic Versioning, commits follow Conventional Commits, and this changelog is generated by Structured Changelog.

Unreleased

v0.6.0 - 2026-09-13

Highlights

  • Module renamed to github.com/plexusone/systemspec-apistyle as part of the PlexusOne systemspec-{domain} family consolidation (breaking)
  • HTML style guide and gap-analysis report generators, with new generate guide-html and generate gap-analysis CLI commands
  • CategoryGroup semantic rule grouping applied to the default profile
  • PayPal REST API style guide added as a reference exemplar

Added

  • generate guide-html command producing an HTML style guide from a profile (84ae447)
  • generate gap-analysis command producing an HTML gap-analysis report (84ae447)
  • HTML gap analysis report generator (3a0264f)
  • HTML style guide generator (574a6e1)
  • CategoryGroup type for semantic rule grouping (3196f99)
  • Category groups added to the default profile (b32efc1)
  • generate report accepts score-profile JSON input (b8657ac)
  • PayPal REST API style guide reference exemplar (3dd99ec)

Changed

  • Renamed Go module from github.com/plexusone/api-style-spec to github.com/plexusone/systemspec-apistyle; schema $id and rule URLs moved from api-style-spec.dev to plexusone.dev/systemspec-apistyle (19101fe)
  • Updated README, MkDocs site, and guides for the systemspec-apistyle name and the "SystemSpec: API Style" display name (5ddcbce)
  • Exported category helper functions from the generate package for reuse (c81a445)
  • MCP server derives its tool list and version from single sources instead of duplicated literals (bb08493)

Fixed

  • x-extension JSONPath expressions use bracket notation to avoid analyzer crashes (844f657)
  • omniagent-rest profile's dangling basedOn pointer, restoring schema validity (4ff406e)
  • Implemented Version method required by omniskill v0.12 (b4e424f)
  • LLM judge surfaces spec truncation instead of silently discarding it (51f07a4)
  • Exception scopes support glob matching and a Paths list (59da435)
  • Version constant was stale at 0.3.0 while the changelog and release docs were at v0.5.0; bumped to match (3fd396f)

Build

  • Updated go.mod dependencies across several rounds, including omniskill, structured-evaluation, assistantkit, mogo, modelcontextprotocol/go-sdk, vacuum, and testify (0b22ff7)

Tests

  • Backfilled coverage for types, schema embeds, and CLI registration (b878f18)
  • Pinned pattern-rule lint behavior and retired a stale bug report fixture (fb88a9e)
  • Generate test fixtures use neutral EXT- rule IDs instead of vendor-specific ones (39c4a93)

v0.5.0 - 2026-07-15

Highlights

  • Exemplar specifications - reference OpenAPI specs demonstrating style profile best practices
  • Pattern library - reusable solutions for common API design problems with examples
  • MCP resource handlers - AI agents can access profiles, exemplars, patterns, and rubrics
  • Fix suggestions - AI-powered suggestions to fix style violations with JSON Patch support

Added

  • exemplar list command to list available exemplar specifications
  • exemplar show command to display exemplar content
  • exemplar copy command to copy an exemplar to a local file
  • pattern list command to list design patterns for a profile
  • pattern show command to display pattern details with examples
  • suggest-fixes command to generate fix suggestions for violations
  • --suggest-fixes flag for lint command to include fix suggestions
  • Exemplar specs: default-minimal and default-comprehensive for default profile
  • Pattern library with cursor-pagination, rfc9457-errors, discriminated-unions patterns
  • MCP resource URIs: apistyle://profiles, apistyle://profile/{name}
  • MCP resource URIs: apistyle://exemplars, apistyle://exemplar/{name}
  • MCP resource URIs: apistyle://patterns/{profile}, apistyle://pattern/{profile}/{id}
  • MCP resource URIs: apistyle://rubric/{profile}/{mode} for evaluation/generation rubrics
  • pkg/fix package with RuleFixer for generating fix suggestions
  • RuleFixer.SuggestFixes for violation-based fix suggestions with JSON Patch
  • RuleFixer.DesignCheck for proactive design checklist generation
  • RuleFixer.ConformancePath for conformance level upgrade guidance
  • Generation rubric generation from style profiles (GenerationRubricFromSpec)
  • Exemplar loader functions: ListExemplars, ListExemplarsForProfile, GetExemplar

Changed

  • Default profile includes patterns for pagination, errors, and schemas
  • LintReport extended with Suggestions field for fix recommendations

Documentation

  • README updated with exemplar, pattern, and suggest-fixes commands
  • README updated with MCP resources and AI agent integration sections
  • Quick start examples for exemplar and pattern commands

Tests

  • Unit tests for pkg/fix/rule_fixer.go covering all fix suggestion methods
  • Unit tests for exemplar loading functions in pkg/profile/loader_test.go
  • Unit tests for MCP resource handlers in skills/apistyle/resources_test.go

v0.4.0 - 2026-07-06

Highlights

  • Default profile expanded to 106 rules with SDK generation optimization (ogen, openapi-generator)
  • New built-in profiles: comprehensive, minimal, microsoft-rest, microsoft-graph
  • New score-profile command for evaluating style guide quality using LLM-as-Judge
  • JSONPath validation system to prevent linting crashes from unsupported expressions

Added

  • score-profile command for LLM-based style guide quality evaluation (d2044dd)
  • JSONPath validation functions: ValidateProfile, FilterInvalidRules, DisableInvalidRules (349eb87)
  • JSONPath validation integration in VacuumLinter initialization (d03be3d)
  • New profiles: comprehensive (88 rules), minimal (29 rules), microsoft-rest (123 rules), microsoft-graph (82 rules) (0fc1bcd)
  • Expanded default profile to 106 rules across 27 categories with SDK optimization (d114350)
  • Multi-tenancy patterns with ~ alias for current tenant context (d114350)
  • RFC 9457 Problem Details for standardized error responses (d114350)
  • Discriminated unions for clean polymorphism in generated SDK code (d114350)
  • Compliant API example spec demonstrating all style patterns (496db88)

Changed

  • Profiles now embedded in pkg/profile/builtin/ and loaded via profile.Load() (48c2376)

Fixed

  • Spectral ruleset generation for truthy/falsy functions outputs field instead of functionOptions.match (bf42a46)
  • Error handling in file watcher with proper cleanup on close (27123b9)
  • Error comparison for context cancellation uses errors.Is (27123b9)
  • Remove custom min function (use Go 1.21+ builtin) (27123b9)

Documentation

  • Profile documentation for comprehensive, minimal, microsoft-rest, microsoft-graph (4a23af9)
  • Updated default profile documentation with accurate 106 rules, 27 categories (4a23af9)
  • Profile comparison guide (1c61eb8)
  • Profile scoring guide (1c61eb8)
  • CLI documentation for score-profile command (8d9aaf7)

Build

  • Update github.com/daveshanley/vacuum from v0.29.6 to v0.29.9 (050b73b)
  • Update github.com/daveshanley/vacuum from v0.29.4 to v0.29.6 (1ebcbd7)
  • Update github.com/plexusone/assistantkit from v0.13.0 to v0.14.0 (83aafea)
  • Update dependencies via go mod tidy (9387ad6)

Tests

  • Updated tests for profile version and rule count expectations (bf67471)

v0.3.0 - 2026-06-22

Highlights

  • Extended type definitions for patterns, principles, glossary, decision tables, and migration guidance
  • MkDocs multi-page documentation site generator with Material theme support
  • Rubric generation for structured-evaluation LLM-as-Judge integration
  • Vendor API style profiles for reference implementations

Added

  • Extended type definitions: Pattern, Principle, GlossaryTerm, Section, DecisionTable, DetailedExample, MigrationGuidance, RuleApplicability, Condition, RuleRelation, DeprecationInfo (c378ada)
  • Enhanced Rule type with description, background, priority, version, deprecated, applicability, conditions, relations, decisionTables, and migration fields (c378ada)
  • Enhanced JudgeCriteria with pass/partial/fail criteria and few-shot examples (c378ada)
  • Markdown generator support for patterns, principles, glossary, decision tables, and detailed examples (5e91d31)
  • Mermaid diagram support in markdown output (5e91d31)
  • MkDocs multi-page documentation site generator with Material theme (c43cd15)
  • MkDocs generator options: --split-patterns, --no-split-categories, --no-search (c43cd15)
  • Rubric generation for structured-evaluation integration (GenerateRubricSet) (52777df)
  • generate mkdocs CLI subcommand with site configuration flags (10a3666)
  • generate rubric CLI subcommand for LLM evaluation rubrics (10a3666)
  • generate guide flags: --no-patterns, --no-principles, --no-glossary (10a3666)
  • Vendor API style profiles: Microsoft Graph, Microsoft REST, OmniAgent, PayPal, PlexusOne, Zalando (b6d4000)

Changed

  • JSON schema updated with extended type definitions (303dc94)
  • Style guide quality rubric added to schema (303dc94)

Documentation

  • CI/CD integration guide with exit codes, pipeline examples, pre-commit hooks (3e4fc8b)
  • Documentation generation guide comparing Markdown and MkDocs output (3e4fc8b)
  • CLI reference updates for generate mkdocs and generate rubric (52ab216)
  • Getting started and profiles guides updated for new features (52ab216)

Build

  • Add github.com/plexusone/structured-evaluation v0.8.0 dependency (b1507dd)
  • Update github.com/plexusone/omniskill from v0.8.0 to v0.9.0 (b1507dd)
  • Update github.com/plexusone/assistantkit from v0.12.0 to v0.13.0 (1563232)
  • Update github.com/daveshanley/vacuum from v0.29.2 to v0.29.4 (6da1e2e)
  • Update indirect dependencies via go mod tidy (e3dc8ca)

Tests

  • Unit tests for extended markdown generation (patterns, principles, glossary, decision tables) (6c414aa)

v0.2.0 - 2026-06-07

Highlights

  • Configuration file support (.api-style.yaml) for project-level governance settings
  • Multi-file linting with glob patterns and recursive directory search
  • Watch mode for continuous linting during development
  • Git pre-commit hook generator for blocking commits with violations

Added

  • Configuration file support with profile, level, include/exclude patterns, exceptions, and severity overrides (57e12de)
  • Config file auto-discovery (.api-style.yaml, .api-style.yml, api-style.yaml) (57e12de)
  • Multi-file resolution with glob patterns (api/*.yaml) (d503276)
  • Recursive directory search (--recursive flag) (d503276)
  • Include/exclude pattern filtering with ** double-star glob support (d503276)
  • MultiLintReport type for aggregating results from multiple files (d503276)
  • Git pre-commit hook generator (api-style hooks init) (aea5ab6)
  • Pre-commit hook with configurable profile and conformance level (aea5ab6)
  • File watcher using fsnotify with debouncing (646b0e6)
  • Watch mode (--watch flag) for continuous re-linting (e0d70e2)
  • --config flag for explicit config file path (e0d70e2)
  • --recursive flag for directory traversal (e0d70e2)
  • hooks init subcommand with --force, --level flags (2196a98)

Changed

  • api-style lint accepts multiple file arguments (e0d70e2)
  • CLI flags override config file settings (e0d70e2)

Documentation

  • Configuration file reference (docs/reference/config.md) (e8d019b)
  • Example config file (.api-style.yaml.example) (e8d019b)
  • CLI reference updates for new flags and commands (d4c6513)
  • Getting started guide with config, multi-file, watch, pre-commit sections (d4c6513)
  • Hooks reference with git pre-commit section (d4c6513)
  • Automated API Governance guide for AI-first API design workflow (e2e58e5)
  • README and examples updates for v0.2.0 features (baa143f)

Build

  • Add github.com/fsnotify/fsnotify v1.10.1 dependency (d079ec2)
  • Update indirect dependencies (regexp2/v2 to v2.2.1) (bcb9687)

v0.1.0 - 2026-06-06

Highlights

  • OpenAPI style linting with vacuum integration and configurable style profiles (Azure, Google, custom)
  • LLM-powered API evaluation using Claude for semantic analysis beyond static rules
  • MCP server for Claude Desktop and Claude Code integration with resources and prompts
  • Web UI with Lit components and REST API backend for browser-based linting

Added

  • Core types package with LintReport, Violation, StyleProfile, and EvaluationResult structs (ed56956)
  • JSON Schema generation from Go types with embedded schemas (ed56956)
  • Vacuum-based linting engine with severity mapping and JSON path extraction (731017d)
  • Style profile loading from YAML/JSON with built-in Azure and Google profiles (a65f682)
  • Profile inheritance via extends field for building on base profiles (a65f682)
  • LLM evaluation with Claude using structured prompts and JSON output (5d6a8b3)
  • Evaluation categories: naming, structure, documentation, security, versioning (5d6a8b3)
  • Analysis orchestrator combining static linting and LLM evaluation (d7fd114)
  • Spectral ruleset generator from style profiles (b4685ea)
  • Markdown report generator with configurable output options (b4685ea)
  • CLI with lint, analyze, and evaluate commands (982c201)
  • Multiple output formats: text, JSON, SARIF (982c201)
  • Exit codes based on violation severity for CI integration (982c201)
  • MCP server with openapi:// resource URIs for spec access (c436afe)
  • MCP prompts for guided API review workflows (c436afe)
  • MCP tools for linting and evaluation from Claude Desktop (c436afe)
  • Claude Code hooks for pre-commit and post-save linting (7d3d506)
  • Claude Code skills for /lint and /evaluate slash commands (7d3d506)
  • SARIF 2.1.0 output format for IDE integration (VS Code, JetBrains) (ec6b375)
  • GitHub Code Scanning compatible SARIF output (ec6b375)
  • REST API server with /api/lint and /api/profiles endpoints (dc0f2f2)
  • CORS support for development and cross-origin requests (dc0f2f2)
  • Web UI with Lit components: spec editor, profile selector, results panel (f51327c)
  • Vite-based frontend build with hot module replacement (f51327c)
  • Example OpenAPI specs: PetStore and E-Commerce APIs (cd7afe6)
  • Example custom style profiles demonstrating profile customization (cd7afe6)

Documentation

  • MkDocs documentation site with Material theme (73d3ef3)
  • Getting started guide with installation and basic usage (73d3ef3)
  • Profile customization guide with YAML examples (73d3ef3)
  • MCP integration guide for Claude Desktop setup (73d3ef3)
  • Feature roadmap with prioritized enhancements

Build

  • GitHub Actions workflows for CI/CD: build, lint, test (5c19ac8)
  • golangci-lint configuration with security and style checks (a2545a4)
  • Schema generator tool for JSON Schema from Go types (148c114)

Tests

  • Unit tests for analyze package (82% coverage) (d7fd114)
  • Unit tests for judge package (76% coverage) (5d6a8b3)
  • Unit tests for lint package (79% coverage) (731017d)
  • Unit tests for SARIF package (92% coverage) (ec6b375)