archunit 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f46c756e84f01c2d6a5b1d4e39865dbb86181dd228cbdb1ec0bbf21110e77f37
-  data.tar.gz: 37d35e46c78fc1afd46d6a86a998257c2157c36d09d6a2f73ff520a3437f6209
+  metadata.gz: 2ed496ce492119fbd9af981d5f3438d801fdcb27e4de3a620e90ec617ff00146
+  data.tar.gz: beacb18bfd3cf88bdd8907e58ba4e9f9eecce710893e77d934f0a5416531fc9f
 SHA512:
-  metadata.gz: 95d51bad089bd4f9ad8b1f9f4a61e0c768221d54bbd89ea9e074ca31b39b79c107208fdf53530f0e59f971d82d3b698cb1a34d714bd5a787147ae8f5f7130218
-  data.tar.gz: fcd6d488f34413e94a24fc4780a1feb6f15b511d5138af9510b3550299163a7821f2f3fc11049039a6d9465f02b3ea7966e5418758b958c7f38a417d2e377446
+  metadata.gz: 8393fc4f6c4c7606a671015dc4a6a8e6258e0fe39c6750d2c518b309e00651d72222d92da438e7623dcdee5fce71d4c4a98bc019a1ff1df2228f515da2afc35d
+  data.tar.gz: 9690eea349c54b022ca11a92caa72f9342795082ffd520aafec76514f8fb11cbc6368d2e4606db4ac44bc4ff3f4c44ad1ff64fae5de6fd5672b5750175596dfb

data/API.md

@@ -0,0 +1,290 @@
+# ArchUnitRuby API Guide
+
+This guide is the stable map of ArchUnitRuby's public fluent API. The
+[class and method reference](class_list.html) is generated from the source, while this page explains
+which entry point to choose and how the stages fit together.
+
+All rule builders are immutable and lazy. Constructing a rule does not read the project; `check`,
+`measure`, `snapshot`, and export methods are the terminals that perform work.
+
+## 1.x compatibility contract
+
+This guide defines the supported 1.0 public surface: documented entry points, fluent methods,
+options, public data/error types, and report formats. Additive capabilities can arrive in minor
+versions; incompatible public API changes require a major version and migration notes. Private
+helpers and classes marked as implementation details are not part of that compatibility promise.
+Correctness fixes can change detected violations; compatibility is not a promise to preserve missed
+dependencies or misleading clean results.
+
+Static extraction remains bounded and does not execute the target application's source or gemspecs.
+Import-only is the default; expanded constant analysis is explicit opt-in. The documented unresolved
+lookup cases, project source/exclusion policy, strict parser failures, and explicit cache-clearing
+behavior remain important when upgrading. See the README's migration notes for changes from 0.0.1.
+
+## Common rule shape
+
+~~~ruby
+rule = ArchUnit.project_files
+               .in_folder('app/api/**')
+               .should_not.depend_on_files
+               .in_folder('app/database/**')
+
+violations = rule.check
+~~~
+
+| Stage | Public vocabulary | Result |
+| --- | --- | --- |
+| Entry | `project_files`, `project_layers`, `project_slices`, `project_graph`, `metrics` | Immutable builder |
+| Scope | `with_name`, `in_folder`, `in_path`, `in_file`, `for_classes_matching` | Narrower builder |
+| Mood | `should`, `should_not` | Positive or negated predicate builder |
+| Predicate | File, layer, slice, or metric policy | Checkable rule |
+| Terminal | `check`, `measure`, `snapshot`, `to_*`, `export_as_*` | Data or an artifact |
+
+String patterns are anchored globs. `*` stays inside one path segment, `**` crosses zero or more
+segments, and `?` matches one non-separator character. A trailing folder glob such as
+`app/api/**` includes the `app/api` folder itself and every descendant folder. Regular expressions
+are accepted by all pattern selectors except the exact `in_file` selector.
+
+Every pattern selector accepts `except:`. Pass a pattern, an array of patterns, or explicit selector
+keys such as `{ in_folder: 'generated', with_name: '*_spec.rb' }`.
+
+## File rules
+
+Every completed rule implementing `ArchUnit::Checkable` supports `.because(reason)`. Append it
+after all selectors and modifiers to get a distinct frozen rule of the same type, with a trimmed,
+immutable `rationale` string. Non-string or blank reasons raise `ArgumentError`. The original rule,
+violations, graph cache, and `check` options are unchanged. The shared result formatter adds
+`Because: ...` exactly once to failed framework-neutral, RSpec, and Minitest assertions, including
+failed negated RSpec expectations. Successful assertions and raw violation formatting omit it.
+
+Start with `ArchUnit.project_files(project_locator = nil)`; `ArchUnit.files` is its short alias.
+Without a locator, ArchUnitRuby searches upward for a `Gemfile` or gemspec.
+
+Discovery skips symlinked source files and directories, including aliases inside the project root.
+Direct `FileInfo` extraction validates canonical as well as lexical containment before reading.
+The source walker reuses a single file-status result per entry for type and symlink decisions.
+
+The detected root's `.archignore` is applied centrally to graphs and file-based metrics. It accepts
+blank lines, full-line `#` comments, basename globs, root-relative path globs, leading `/` anchors,
+and trailing `/` directory patterns. Backslashes normalize to `/`. Bare names match at any depth;
+patterns containing a separator match from the project root. A directory pattern excludes its
+descendants but not a similarly named regular file. Nested ignore files are not read.
+
+Repository patterns combine with defaults or explicit `exclude_patterns:`. An explicit `[]` only
+disables defaults, never repository patterns. The normalized effective pattern set participates in
+graph cache identity; changing the file is noticed on the next check without `clear_cache`.
+Changing source contents still requires explicit cache clearing. Reads are bounded to 1 MiB; UTF-8
+BOMs are accepted and invalid bytes replaced. Symlinks (including project-local ones), non-regular
+files, negation, NUL characters, and a bare `/` are rejected. No Ruby or gemspec code is evaluated.
+
+| Scope or predicate | Purpose |
+| --- | --- |
+| `with_name(pattern)` | Select or require a filename pattern |
+| `in_folder(pattern)` | Select or require a project-relative directory |
+| `in_path(pattern)` | Select or require a complete project-relative path |
+| `in_file(path)` | Select one exact project-relative file |
+| `have_no_cycles` | Reject cycles among selected project files |
+| `depend_on_files` | Allow or reject dependencies matching target selectors |
+| `depend_on_external_modules` | Allow or reject standard-library or gem imports |
+| `adhere_to(callable, message)` | Evaluate a custom predicate over immutable `FileInfo` values |
+
+~~~ruby
+service_scope = ArchUnit.project_files.in_folder('app/services/**')
+
+rules = [
+  service_scope.should.have_name('*_service.rb'),
+  service_scope.should_not.depend_on_files.in_folder('app/controllers/**'),
+  service_scope.should_not.depend_on_external_modules.matching('net/http'),
+  service_scope.should.adhere_to(
+    ->(file) { file.lines_of_code < 300 },
+    'services must stay below 300 non-blank lines'
+  )
+]
+~~~
+
+Positive dependency rules are allowlists: every selected dependency must match at least one target.
+Negated dependency rules are blocklists: matching dependencies become violations.
+
+Cycle projection uses iterative strongly-connected-component and elementary-cycle traversals, so
+long dependency chains do not consume Ruby's call stack. It still enumerates all elementary cycles;
+dense graphs can have exponentially many results. Scope cycle rules to meaningful components.
+
+## Layer rules
+
+Use `ArchUnit.project_layers(project_locator = nil)` to name architectural layers and then declare
+their allowed or forbidden relationships.
+
+~~~ruby
+rule = ArchUnit.project_layers
+               .layer('api').defined_by('app/api/**/*.rb')
+               .layer('services').defined_by_folder('app/services/**')
+               .layer('database').defined_by('app/database/**/*.rb')
+               .where_layer('api').may_only_depend_on_layers('services')
+               .where_layer('services').may_only_depend_on_layers('database')
+               .where_layer('database').may_only_depend_on_layers
+~~~
+
+`may_only_depend_on_layers` creates an allowlist. Calling it without targets seals the layer.
+`may_not_depend_on_layers` creates a blocklist and requires at least one target. Dependencies inside
+one layer are allowed; edges with an unassigned endpoint are ignored.
+
+## Slices and diagrams
+
+Use `ArchUnit.project_slices(project_locator = nil)` to capture one segment from project paths.
+`(**)` is the glob capture; `defined_by_regex` uses the first regular-expression capture.
+
+~~~ruby
+slices = ArchUnit.project_slices.defined_by('lib/my_app/(**)/')
+
+dependency_rule = slices.should_not.contain_dependency('api', 'database')
+diagram_rule = slices.should
+                     .ignoring_external_slices
+                     .ignoring_orphan_slices
+                     .adhere_to_diagram_in_file('docs/architecture.puml')
+
+plantuml = slices.to_plantuml
+slices.export_as_plantuml('reports/architecture.puml')
+~~~
+
+`adhere_to_diagram` accepts inline PlantUML. The supported subset includes components, directed
+dependencies, comments, `@startuml`, and `@enduml`.
+
+## Dependency graph reports
+
+Use `ArchUnit.project_graph(project_locator = nil)` for queryable snapshots and reports.
+
+~~~ruby
+report = ArchUnit.project_graph
+                 .include_external_dependencies
+                 .focus_on('app/services/**', 2)
+                 .collapse_to_folder_depth(2)
+                 .titled('Service dependencies')
+
+summary = report.summary
+snapshot = report.snapshot
+report.export_as_mermaid('reports/services.mmd')
+report.export_as_html('reports/services.html')
+~~~
+
+Query modifiers are `focus_on(pattern, depth)`, `reachable_from(pattern)`, and
+`dependents_of(pattern)`. Group nodes with `collapse_to_folder_depth` or
+`collapse_by_pattern(pattern, replacement)`. Formats are DOT, Mermaid, D2, CSV, JSON, and
+self-contained HTML; each provides both `to_<format>` and `export_as_<format>`.
+
+## Metrics
+
+Start with `ArchUnit.metrics(project_locator = nil)`. Select files with the standard file selectors
+and classes with `for_classes_matching`.
+
+~~~ruby
+services = ArchUnit.metrics
+                   .in_path('app/services/**/*.rb')
+                   .for_classes_matching('*Service')
+
+rules = [
+  services.count.method_count.should_be_below_or_equal(20),
+  services.lcom.lcom4.should_be(1),
+  services.distance.instability.should_be_below(0.8)
+]
+
+measurements = services.count.method_count.measure
+services.count.export_as_html('reports/service-counts')
+~~~
+
+Count metrics cover methods, fields, lines, statements, imports, classes, and top-level functions.
+Cohesion provides LCOM96a, LCOM96b, LCOM1-5, and LCOM*. Distance metrics include abstractness,
+instability, main-sequence distance, normalized distance, and coupling factor.
+
+Thresholds use exactly `should_be_below`, `should_be_above`, `should_be`,
+`should_be_below_or_equal`, `should_be_above_or_equal`, and `should_satisfy`. Use `custom_metric`
+for a calculation over `ClassInfo`; zone guards are `not_in_zone_of_pain` and
+`not_in_zone_of_uselessness`.
+
+## Checking and test frameworks
+
+Every architecture rule includes `ArchUnit::Checkable` and exposes `check(options = nil)`. It returns
+an array of structured `Violation` values; an architecture disagreement is not an exception until
+an assertion adapter translates it at the test boundary.
+
+~~~ruby
+violations = rule.check
+
+expect(rule).to pass         # RSpec
+assert_passes(rule)          # Minitest
+ArchUnit.assert_passes(rule) # Framework-neutral
+~~~
+
+Use `ArchUnit.format_violations` or `ArchUnit::ResultFactory` when integrating with another test
+framework or command-line interface.
+
+## Check options and logging
+
+`ArchUnit::CheckOptions` keeps optional execution behavior out of the fluent sentence:
+
+~~~ruby
+logging = ArchUnit::LoggingOptions.new(
+  level: :debug,
+  output_directory: 'tmp/archunit-logs'
+)
+
+options = ArchUnit::CheckOptions.new(
+  allow_empty_tests: false,
+  clear_cache: false,
+  load_paths: ['components/billing/lib'],
+  dependency_analysis: :imports,
+  logging: logging
+)
+
+violations = rule.check(options)
+~~~
+
+Zero selected subjects produce `EmptyTestViolation` by default. Set `allow_empty_tests: true` only
+when an empty scope is intentionally valid. Set `clear_cache: true` after modifying the analyzed
+project during one process. `load_paths` adds project-contained source roots without evaluating
+gemspecs or running application code.
+
+`dependency_analysis` defaults to `:imports`. Imports accept literal arguments and preceding local
+literal-string assignments in supported straight-line scopes. Aliases, mutation/escape, closures,
+reflection, and unsupported control flow invalidate inferred values; runtime paths are not guessed.
+
+For autoloaded projects, opt into known project constant references alongside imports:
+
+~~~ruby
+options = ArchUnit::CheckOptions.new(dependency_analysis: :imports_and_constants)
+violations = rule.check(options)
+json = ArchUnit.project_graph.with_check_options(options).to_json
+values = ArchUnit.metrics.distance.instability.measure(options)
+~~~
+
+Expanded analysis resolves supported lexical, compact, and root-qualified references to their
+definition files. Explicit superclass and mixin references also contribute edges. Missing or
+ambiguous definitions, inherited-member lookup, and dynamic metaprogramming stay unresolved under
+the bounded contract in the main guide. Namespaces that fail to stabilize within eight index passes
+fall back to import-only results. Unknown third-party constants do not create architecture violations.
+
+Declarations include ordinary `=` and conditional `||=`, with lexical/qualified/root-qualified
+ownership and definition evidence. This does not predict runtime execution or load order. Multiple
+definition files remain ambiguous; update-only compound and multiple-assignment forms are not
+inferred as new declaration owners.
+
+Expanded edges include `:constant_reference` in `import_kinds` and retain `DependencyEvidence` with
+names and source lines in `edge.evidence` and JSON reports. An import and a constant use supporting
+the same file pair merge into one edge. Import-only edge evidence stays empty for compatibility;
+`ArchUnit::Extraction.extract_imports` retains import call locations in both modes. The analysis
+mode participates in graph-cache identity, and `clear_cache: true` rebuilds the symbol index.
+
+## Errors and support
+
+Invalid API input raises `ArchUnit::UserError` or `ArgumentError`; library or environment failures
+raise `ArchUnit::TechnicalError`. Rule failures remain violation data.
+
+Malformed included Ruby raises `ArchUnit::SourceParseError`, a `TechnicalError`, during graph or
+AST-metric extraction. No partial graph is returned or cached. `error.diagnostics` is an immutable
+array of `ArchUnit::ParseDiagnostic` values with `path`, one-based `line`/`column`, and `message`;
+each value supports `to_h`. RSpec/Minitest assertions propagate this technical failure instead of
+reporting a pass or an ordinary architecture violation. Excluded files are not parsed. The profile's
+`malformed_files` counter records a rejected file; existing cache-clearing rules still apply.
+
+See the [main guide](index.html) for installation and complete examples, [SUPPORT.md](https://github.com/LukasNiessen/ArchUnitRuby/blob/main/SUPPORT.md)
+for help, and [SECURITY.md](https://github.com/LukasNiessen/ArchUnitRuby/blob/main/SECURITY.md) for
+responsible vulnerability reporting.

data/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 1.0.0 - 2026-10-26
+
+First stable API baseline. The previously unreleased 0.0.2 development work is included here;
+0.0.1 remains the preceding published version. See the README's migration notes before upgrading.
+
+- Fail closed on malformed included Ruby in dependency graphs and AST metrics, with structured
+  source diagnostics and profile counters instead of silently treating incomplete analysis as clean.
+
+- Add development-only locked dependency scanning with advisory refresh, fail-closed health checks,
+  Windows path normalization, and retained CI reports.
+
+- Avoid stack overflows in strongly-connected-component detection, elementary-cycle traversal,
+  and blocked-vertex propagation on deep dependency graphs.
+- Skip symlinked source entries and enforce canonical project boundaries for direct file metadata.
+- Reuse source-entry file status instead of repeating separate directory and file probes.
+- Validate version/changelog/lock consistency in CI and require prepared release metadata before
+  RubyGems publication.
+- Enforce the unchanged coverage thresholds on runtime library source only, with a real-report
+  regression check that excludes loaded specs, benchmarks, and scripts from the denominator.
+
+- Apply bounded project-root `.archignore` exclusions consistently to dependency graphs and metrics,
+  with cache invalidation, cross-platform glob handling, and configuration safety checks.
+
+- Add immutable `.because(...)` explanations to every executable rule and shared assertion output.
+
+- Add opt-in debug inspection of project roots, graphs, and selected files on cold and cached checks.
+- Log passing metric values without repeating custom calculations.
+- Document verbosity, CI log artifacts, and existing colored violation reports.
+
+- Add opt-in project constant-reference dependencies with lexical lookup and conservative ambiguity handling.
+- Index lexical, qualified, and root-qualified `||=` declarations in expanded analysis without
+  executing source or changing import-only mode.
+- Infer import paths from safely known local literal strings without evaluating application code.
+- Preserve dependency source evidence in expanded mode through graph merging and JSON reporting,
+  while keeping import-only edge values compatible with existing consumers.
+- Support check options on metric measurements and add installed-gem extraction regression checks.
+- Make trailing folder globs such as `app/api/**` include the named folder itself.
+- Validate the README quickstart as a passing and failing end-to-end architecture test.
+- Add a curated API guide, reliable Markdown rendering, responsive documentation navigation, and
+  documentation quality checks.
+- Add the ArchUnitRuby family logo, social preview, and repository community health files.
+- Discover adjacent `lib` directories in multi-gemspec repositories without evaluating gemspecs.
+- Support validated, project-local custom load paths through `CheckOptions`.
+- Add cold/warm extraction profiling, a reproducible benchmark, and resolution caching.
+
 ## 0.0.1 - 2026-08-11
 
 Initial executable prototype.