Skip to content

CLI milestone: init/check/explain with structured diagnostics #72

Open

Description

@TristanKruse

Goal

Deliver the first CLI milestone from #66 without replacing the fluent API, RSpec, or Minitest. The user authorized tackling the remaining follow-ups after the verified 1.0.0 publication.

Design choice

  • Add the gem executable archunit, composing existing Checkable rules and violation formatters.
  • A project .archunit.rb explicitly declares named rules using rule('name') { ... }. File/layer/slice/metric helpers default to the selected project root.
  • Configuration is trusted executable Ruby, not a sandbox. Load only the selected configuration; never automatically require target source, evaluate a target Gemfile/gemspec, install its dependencies, or boot Rails.
  • init creates a commented cycle-rule starter only when the destination does not exist; never overwrite existing files, directories, or symlinks.
  • check supports text / versioned JSON output, an explicit project/config path, and the existing import-only or opt-in expanded analysis modes.
  • explain lists configured rule names, rationales, project, and analysis mode without running checks; it must say that results are not evaluated. Deeper semantic tracing and focused-path reports remain separate milestones.

Acceptance criteria

  • archunit init, check, explain, --help, and --version work from the installed gem on supported Ruby versions/platforms.
  • Exit status 0 = successful command / all checked rules pass; 1 = architecture violations; 2 = argument/configuration/analysis errors. Missing/empty/duplicate/invalid rules never pass silently.
  • Text reuses existing violation wording and rationale. JSON has a schema version, rule results, violation types/messages/details, summary, and structured parse diagnostics on technical failures.
  • Regression and subprocess tests cover passing/failing rules after edits, default vs opt-in constant edges, empty selections, invalid source, multiple rules, config errors, explicit paths, non-destructive init, and target code not executing.
  • Gem packaging includes the executable; CI installs the built artifact and invokes its CLI from a clean project. Existing compatibility, coverage, lint, dogfood, security, docs, and corpus checks remain green.
  • README/API document usage, JSON/exit contracts, trusted-config boundary, and milestone limits. Track this as an unreleased 1.1.0 additive feature; do not republish or modify 1.0.0.

Baselines, first-class method/protocol semantics, presets, and larger Rails performance studies are not part of this issue.

Implementation status — 2026-10-27

Implemented in #73, ready for review/merge, with all fresh CI checks green. Final local suite: 667 examples, zero failures, 98.54% line / 91.82% branch coverage. Native Windows symlink coverage now passes after fixing a real dangling-link initialization bug. Configuration exit-zero false success is also reproduced and fixed. This issue stays open until the PR merges; no 1.1.0 publication occurred.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions