v1.0.0-alpha3
Pre-release
Polychro v1.0.0-alpha3 — 🔬 Release Notes
🔍 The first Alpha drops anchor! Polychro is a deterministic linting engine built for spec-driven development — validating YAML, JSON, Markdown, and OpenAPI through composable layers with sub-second latency. Designed from day one for AI agent loops where non-deterministic generation needs deterministic guardrails.
What is Polychro?
Polychro is a deterministic linting engine for spec-driven development. It validates semi-structured specifications — YAML, JSON, Markdown, and OpenAPI — through composable layers including well-formedness, schema-model, ruleset, and format-aware validation, in a single embeddable pipeline with sub-second latency.
Built on Spectral's shoulders. Polychro adopts Spectral's given/then ruleset grammar — the de facto standard for API governance rules — and extends it into a fully self-contained, polyglot engine. Where Spectral requires Node.js and is narrowly focused on OpenAPI, Polychro runs as a single JVM binary with no external runtime, supports custom rule functions in JavaScript, Python, and Groovy, and lints YAML, JSON, Markdown, and OpenAPI in the same pipeline. A natural next step for teams already invested in the Spectral ruleset ecosystem.
💡 Polychro is designed to work alongside Ikanos — validating capability specs before they reach the runtime — but it is fully standalone and works with any YAML, JSON, or Markdown document.
Built on Spectral's shoulders. Polychro adopts Spectral's given/then ruleset grammar — the de facto standard for API governance rules — and extends it into a fully self-contained, polyglot engine. Where Spectral requires Node.js and is narrowly focused on OpenAPI, Polychro runs as a single JVM binary with no external runtime, supports custom rule functions in JavaScript, Python, and Groovy, and lints YAML, JSON, Markdown, and OpenAPI in the same pipeline. A natural next step for teams already invested in the Spectral ruleset ecosystem.
| Feature | Description |
|---|---|
| CLI | Single binary — lint any YAML/JSON/Markdown spec from the command line |
| MCP Server Mode | Expose linting as MCP tools for AI agent consumption |
| Native Executable | Standalone binaries for Linux, macOS, and Windows — no JVM required |
| GitHub Action | Lint specs in CI with structured SARIF output |
| Spectral-Format Rulesets | Execute governance rulesets with given/then semantics |
| Polyglot Custom Functions | JavaScript, Python, and Groovy custom functions via sandboxed GraalVM |
| Schema-Model Validation | JSON Schema Draft 2020-12 and JSON Structure |
| Well-Formedness Validation | Duplicate keys, encoding, depth limits, YAML-specific traps |
| Format-Aware Validation | Heading hierarchy, internal links, relative file references |
| Unified Diagnostics | All validators produce the same Diagnostic — one pipeline, one output |
| Embeddable Java API | In-process linting for JVM applications — no subprocess, no Node.js |
| Pluggable SPI | Add custom validators via ServiceLoader — zero framework coupling |
✨ Highlights
📐 Spectral-Compatible Rulesets — and Beyond
Polychro rulesets speak the same given/then grammar as Spectral, making migration straightforward. But Polychro goes further:
- Polyglot custom functions — write rule functions in JavaScript, Python, or Groovy; no Node.js runtime required
- Projected format rules — format-aware rules that understand document structure, not just raw text
- Multi-format targets — lint YAML, JSON, Markdown, and OpenAPI in the same pipeline
- Zero Node.js dependency — the entire engine is a single JVM binary or native executable
Built-in rulesets ship with alpha1:
| Ruleset | Purpose |
|---|---|
polychro:ai-safety |
Guard AI-generated specs against unsafe patterns |
polychro:governance |
Enforce organizational naming and structure conventions |
polychro:security |
Detect common security misconfigurations |
polychro:resilience |
Validate resilience patterns in capability specs |
🤖 AI-Native by Design — MCP Server Mode
Polychro exposes its full linting pipeline as MCP tools, making it a first-class citizen in AI agent loops:
linttool — validates any spec document and returns structured diagnosticsservecommand — starts an MCP server with configurable rulesets- Agent output format —
--format agentreturns LLM-optimized JSON with token-counted diagnostics - Built-in rulesets (
polychro:ai-safety,polychro:governance,polychro:security,polychro:resilience) ready for agent consumption - Polychro ships as the linting backend for Ikanos
polychro-capability, exposing lint-as-a-tool over MCP
🧩 Composable Validation Pipeline
Four independent validator layers compose in a single pass:
- Well-formedness — encoding, duplicate keys, depth limits, YAML-specific traps (tab indentation, implicit typing)
- Schema-model — JSON Schema Draft 2020-12 and JSON Structure formal validation
- Ruleset — declarative
given/thenrules in YAML, Spectral-compatible syntax with polyglot custom functions (JavaScript, Python, Groovy via GraalVM) - Format-aware — document-specific structural checks: Markdown heading hierarchy, internal link resolution, relative file references, HTML reference integrity
All layers produce the same Diagnostic SPI record — one unified output regardless of which validator fired.
🔌 Pluggable SPI Architecture
Every validator is a plugin. The polychro-api module defines the SPI contracts:
Validator/ValidatorFactory— implement and register viaServiceLoaderDiagnostic/SourceRange— universal diagnostic recordDocument/ValidatorConfig— document model and configuration contracts- Zero framework coupling — validators have no dependency on Polychro internals
Built-in validators (polychro-wellformedness, polychro-json-schema, polychro-json-structure, polychro-markdown, polychro-checkov, polychro-html) all implement the same SPI.
🛡️ Checkov IaC Security Bridge
Infrastructure-as-Code security scanning is a first-class validator:
- Checkov bridge (
polychro-checkov) — delegates to Checkov for IaC and capability security checks - Cross-platform process execution with interrupt handling
- Diagnostics surfaced in the unified Polychro output format
📄 Format-Aware Markdown & HTML Validation
Document-specific validators go beyond schema:
- Markdown — heading hierarchy, internal anchors, relative file links, nested block recursion, list item links
- HTML (
polychro-html) —<link>and<a>reference integrity, required document parts - Common format layer (
polychro-format-common) — shared projection infrastructure for format-aware rules
🚀 Distribution & Polyglot SDKs
Polychro ships in multiple forms:
- Native CLI binaries — Linux AMD64/ARM64, macOS ARM64, Windows AMD64 (no JVM required)
- GitHub Action —
naftiko/polychroaction with SARIF output for CI integration - Embeddable JAR —
polychro-coreas a Maven dependency for JVM applications - Thin-wrapper SDKs — Python (
polychro-python), Node.js/TypeScript (polychro-node), Go (polychro-go) — delegate to the native binary
⚠️ Known Issues & Limitations
- CLI pre-built binary installation — running the binary directly is not straightforward on macOS (Gatekeeper quarantine:
xattr -dr com.apple.quarantine) or Windows (SmartScreen warning, unsigned binary). Workaround: run viajava -jar polychro.jar polychro-rulesetsJaCoCo coverage — pre-existing gap onmain; coverage gate not yet enforced for this module- Checkov — requires a local Checkov installation; not bundled in the binary
- Conditional routing and async execution — not yet in scope for the linting pipeline
🔢 By the Numbers
- ~114 commits — initial release
- 430 files, +41,077 / −1,325 lines
- 2 contributors
🙏 Contributors
Huge thanks to the team for shipping this first release:
- @jlouvel — core engine, validation pipeline, SPI architecture, format-aware validators, MCP server mode, native builds
- @eskenazit — rulesets, AGENTS.md governance, schema-model validation, CI hardening, JaCoCo enforcement
Full Changelog: initial release