Polychro v1.0.0-alpha4 — "Yawl" ⛵

Polychro v1.0.0-alpha4 — "Yawl" ⛵ — Release Notes

🔬 The fourth Alpha sharpens the focus. After alpha3 launched the engine, "Yawl" makes
Polychro's diagnostics point precisely — built-in and polyglot ruleset violations now
carry iso-Spectral source ranges, so every finding lands on the exact scalar that triggered
it. Add CLI smoke tests, a nightly quality gate, and a cleaner build, and this is the most
production-ready Polychro yet.

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
(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.

💡 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.

This v1.0.0-alpha4 release is the first incremental release after alpha3's initial drop.
It is focused on diagnostic precision and CI maturity — no breaking changes to the SPI
or ruleset grammar.

✨ Highlights

🎯 Iso-Spectral Source Ranges for Ruleset Diagnostics (#32)

Ruleset violations now report the exact source location of the offending value, matching
Spectral's positioning semantics — so editors, SARIF consumers, and AI agents can highlight
precisely the right span:

• New JacksonSourceMap computes 0-based, end-exclusive source ranges (iso-Spectral) for
  every scalar — plain, quoted, escaped, block, and array-nested — by scanning each token's
  full extent
• The range is propagated through RulesetValidator into every Diagnostic for built-in YAML
  ruleset findings
• Polyglot ruleset functions (JavaScript, via GraalVM) are now wired into production
  validation with a per-violation range: the SPI carries a new Violation record
  (message + path), a FunctionRegistry resolves functions per ruleset, and
  PolyglotRuleFunction extracts the JsonPath of each violation so the diagnostic carries an
  iso-Spectral range
• Backed by extensive golden and end-scan tests (JacksonSourceMapTest,
  JacksonSourceMapEndScanTest, PolyglotPathExtractionTest,
  PolyglotRulesetEndToEndTest) (#32)

Non-YAML formats currently keep SourceMap.NONE — JSON, Markdown, and HTML source ranges are
tracked for follow-up (#34–#37).

🌙 CLI Smoke Tests & Nightly Quality Gate

• CLI smoke tests added — end-to-end coverage that exercises the packaged binary, not just
  the in-process API
• Nightly test workflow implemented — the full quality gate runs on a schedule, catching
  regressions independently of PR activity

🤝 Agent & Contributor Experience

• pr-review skill repointed to the shared agents-shared capability in the
  code-standards golden repo — the per-repo copy is removed, eliminating duplication across
  Naftiko repositories

🧹 Build & Dependency Hygiene

• Removed the stale talend-restlet repository from polychro-capability — the
  org.restlet dependency now resolves cleanly from Maven Central, simplifying the build
  (#3)
• polychro-coverage/target aggregate output added to .gitignore
• Maven publish pipeline validated

📚 Documentation

• README and in-repo documentation links now point to the Shipyard portal
  (https://shipyard.naftiko.io)
• Added a link to the dedicated Polychro Comparison page
• README readability touch-ups

⚠️ Known Issues & Limitations

• Non-YAML source ranges — built-in and polyglot ruleset diagnostics carry precise ranges
  for YAML documents; JSON, Markdown, and HTML still report SourceMap.NONE pending
  follow-up (#34–#37)
• 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 via java -jar polychro.jar
• polychro-rulesets JaCoCo coverage — pre-existing gap on main; coverage gate not yet
  enforced for this module
• Checkov — requires a local Checkov installation; not bundled in the binary

🔢 By the Numbers

• 13 commits merged since v1.0.0-alpha3
• 42 files changed, +3,495 / −210 lines
• 3 contributors

🙏 Contributors

Huge thanks to the team for shipping this release:

• @eskenazit — iso-Spectral source ranges & polyglot
  per-violation diagnostics (#32), talend-restlet cleanup (#3), pr-review repoint to
  agents-shared, documentation & Shipyard links
• @farah-t-trigui — CLI smoke tests, nightly quality-gate
  workflow, Maven publish validation
• @jlouvel — engine support and release coordination

Full Changelog: v1.0.0-alpha3...v1.0.0-alpha4