API Policy & Compatibility Checker
Relevant source files
The following files were used as context for generating this wiki page:
The API Policy & Compatibility Checker ensures that Crucible API models adhere to defined style guides and maintain backward compatibility across releases. It consumes lowered Intermediate Representation (IR) to perform static analysis and directional comparisons between different versions of a service contract.
Sources: AGENTS.md:111-112, crates/crucible-cli/tests/client_policy.rs:104-111
System Architecture
The checker operates as a build-time and editor-time component. It integrates with the crucible-cli for automated checks and the Language Server Protocol (LSP) for real-time feedback. The system distinguishes between static linting rules and dynamic compatibility checks against a frozen baseline.
The checker relies on the crucible-policy crate to analyze models without re-deriving semantics settled in crucible-ir.
Sources: AGENTS.md:111-112, crates/crucible-lsp/src/manifest.rs:11-44, crates/crucible-cli/tests/client_policy.rs:114-123
Policy Configuration
The checker reads configuration from crucible.toml. Users define rule parameters and default severity levels (error, warning, or off).
Rule Categories
| Category | Table Name | Purpose |
|---|---|---|
| Naming | rules.naming | Enforces case conventions (PascalCase, camelCase) and regex patterns. |
| Paths | rules.paths | Validates URI prefixes, literal segment cases, and parameter naming. |
| Documentation | rules.documentation | Mandates documentation for specific targets (service, operations, shapes). |
| Examples | rules.examples | Requires modeled examples and error coverage in documentation. |
| Compatibility | compatibility | Checks for breaking changes against a previous release. |
Sources: crates/crucible-lsp/src/manifest.rs:83-200
Rule Value Types
Rules support multiple forms of configuration:
- Case: Enforces specific naming styles like
SCREAMING_SNAKE_CASE. - Pattern: Validates names against a full-name regular expression.
- Prefix: Ensures URI paths start with a specific string (e.g.,
/v1). - Enabled: Simple boolean toggle for specific checks.
Sources: crates/crucible-lsp/src/manifest.rs:13-40
Compatibility Checking
The checker protects service contracts by comparing the current IR against a baseline snapshot. It identifies breaking changes that would impact existing clients.
Breaking Change Types
The system detects various categories of incompatible modifications:
- Wire Compatibility: Changes that break the HTTP/JSON interface, such as moving a route or making a member required.
- SDK Source Compatibility: Changes that cause generated client code to stop compiling for users.
- Member Evolution: Renaming members or retyping fields to incompatible formats.
Sources: crates/crucible-lsp/src/manifest.rs:218-228, crates/crucible-codegen-docs/src/markdown.rs:955-1060
Exception Handling
The checker supports an exceptions mechanism to accept known rule violations. Each exception must specify:
- The rule being violated (e.g.,
naming.members). - The shape or member target (e.g.,
namespace#Shape$member). - A mandatory reason for the violation.
Sources: crates/crucible-lsp/src/manifest.rs:232-255
Linting Details
Naming Conventions
The checker validates the names of operations, shapes, members, and enum values. It can check both the model name and the wire value (for string enums).
Path Validation
URI paths are checked for consistency. Literal segments typically use kebab-case, while path parameters use camelCase. The checker also enforces mandatory prefixes at segment boundaries.
Documentation Requirements
The system ensures that critical components are documented using ///. Targets can include the entire service, specific operations, or individual members and errors.
Sources: crates/crucible-lsp/src/manifest.rs:114-190
Release History Analysis
The checker tracks the evolution of elements across releases. This metadata is used to generate upgrade guides and changelogs.
Detailed change analysis includes:
- Rename: Detecting when a member is renamed but serves the same purpose.
- Reshape: Identifying when structure definitions change between releases.
- Behavior: Tracking documented changes in how an operation behaves without wire changes.
Sources: crates/crucible-codegen-docs/tests/upgrade.rs:480-505, crates/crucible-codegen-docs/src/markdown.rs:955-1040
The API Policy & Compatibility Checker is a fundamental tool for maintaining high-quality, stable service definitions throughout the API lifecycle. By enforcing consistency and warning of breaking changes early, it reduces integration friction for client developers.
Sources: AGENTS.md:111-120, crates/crucible-cli/tests/client_policy.rs:56-65