Roadmap: prioritized release readiness and ArchSpec capability gaps #66

Scope

Capability audit as of 2026-10-25. Our reference is merged main 1cc0eca (development version 0.0.2), not the still-published archunit 0.0.1 gem. The closest direct comparison is published ArchSpec 1.1.0, source commit 1d321d3585a86672e65b2488681393f9d52656a9, not its newer master branch.

This is a prioritized planning issue, not authorization to implement every competitor feature or publish a release. Separate delivery issues should carry acceptance criteria and a design choice before implementation.

Current differentiators and gaps

• Shared capabilities: static analysis without booting an application; dependency boundaries, layer/component direction, cycles, naming, and rule rationale.
• Our strengths: native RSpec/Minitest fluent assertions; explicit require/require_relative/autoload/load dependency analysis including safely known local strings; quantitative metrics/custom thresholds; graph and Mermaid/DOT/D2/CSV/JSON/HTML exports; PlantUML conformance. ArchSpec's published rule surface has no equivalent built-in quantitative metrics/diagram-report suite.
• ArchSpec advantages: native named-method-call restrictions and method/signature protocols; namespace/constant/descendant component selectors; first-class public/private component APIs; architecture presets; CLI init/check/explain and focused-path reporting; TODO baselines for gradual adoption.
• Some gaps are expressible manually with our existing file/layer rules or custom predicates. That is not equivalent to a supported first-class semantic API, but it is also not absence of all boundary testing.
• ArchSpec master has newer reflection/stale-TODO functionality not present in the pinned 1.1.0 source. Do not present development-only features as shipped 1.1.0 parity requirements.
• Neither tool is a complete Ruby interpreter. Selected inherited/alias-member probes did not produce our direct API-to-db violation in either tool; they are not evidence that all semantic forms are handled by one competitor.

Proposed order (maintainer decision required)

• First resolve the parse-failure and ||= false-clean findings, and tighten coverage-report scope. Keep these separate from feature work.
• Refresh .github/PRE_RELEASE_CHECKLIST.md: it still describes merged PRs and closed issues as pending and describes the now-implemented canary as future work.
• Prepare a reviewed stable-release contract after correctness checks: choose/bump version, update locked local gem, date the changelog, align install snippets, run strict release metadata checks, obtain separate publish approval, then verify the published gem in a clean project. Current --release check intentionally fails on the undated changelog and old README install pin.
• Design a small CLI around existing Checkable/rule execution plus explainable structured diagnostics. Do not replace RSpec/Minitest.
• Design a violation baseline with stable fingerprints and stale-entry detection for gradual adoption. Distinguish deliberate accepted debt from ignoring entire files/imports.
• Evaluate the demand and semantic backend for first-class method-call restrictions/protocol checks and richer selectors. Preserve an explicit analysis-mode compatibility contract; do not add regex heuristics advertised as semantic call resolution.
• Add a small family-consistent preset layer (e.g. Rails/layered/hexagonal) by composing existing rules before duplicating core assertion logic.
• Repeat fair performance checks on Linux and representative real Rails/monorepo shapes, permitted as well as forbidden policies, more densities, startup/memory measures, and file changes. Do not optimize to a synthetic leaderboard before correctness.

Initial performance evidence (not a global speed claim)

Same Windows x64 machine, Ruby 4.0.6, Prism 1.9.0, ArchSpec 1.1.0 / RubyDEX 0.4.0; seven alternating trials per tool. Our expanded mode is used. Generated projects contain paired API/db files with explicit imports and fully qualified constant uses. Each tool must return exactly 100 or 500 forbidden-dependency diagnostics in every trial.

Medians; libraries/definitions preloaded and fixture creation excluded. OS file caches were not flushed. Cold means analyzer graph rebuilt, not fresh-process/uncached-disk startup. Warm ArchSpec uses explicit reuse of the returned graph through its public evaluator, not a claimed persistent CLI cache. The analyzers do different additional work, and these are small synthetic sources, so this does not establish an overall performance winner or equal semantic coverage.

Authoritative feature references: ArchSpec 1.1.0 README, 1.1.0 DSL, our API.

Related audit findings

• Parse-failure diagnostics: Extraction: surface parse failures instead of silently passing malformed source #63
• Constant ||= definitions: Constant analysis: index ||= declarations and qualified constant writes #64
• Coverage measurement scope: QA: enforce coverage thresholds on library source rather than aggregate tooling #65

Delivery update — 2026-10-27

The first three readiness items are complete: #68-70 and #71 merged; archunit 1.0.0 is published and its registry checksum, tag, and clean-project acceptance checks were verified. Evidence: #71 (comment) . Dependabot #67 is now merged after refreshing against 1.0.0 and passing fresh CI. Its missing configured dependencies label was also created.

The next bounded delivery milestone is #72: init/check/explain CLI with text/versioned JSON diagnostics and installed-package tests. Implementation is in progress on a separate unreleased 1.1.0 branch. Deeper semantic explanations/focused-path reports, baselines, method/protocol semantics, presets, and representative Rails performance studies remain separate work; this roadmap stays open.