Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
blank_issues_enabled: false
contact_links:
- name: Usage and design questions
url: https://github.com/LukasNiessen/ArchUnitJava/discussions
url: https://github.com/dragonsec-ai/ArchUnitJava/discussions
about: Ask the community before opening a product issue.
- name: Private vulnerability report
url: https://github.com/LukasNiessen/ArchUnitJava/security/advisories/new
url: https://github.com/dragonsec-ai/ArchUnitJava/security/advisories/new
about: Never disclose a suspected vulnerability in a public issue.
2 changes: 1 addition & 1 deletion .github/PAGES.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# GitHub Pages

ArchUnitJava publishes its product guide and generated Java API reference at
<https://lukasniessen.github.io/ArchUnitJava/>.
<https://dragonsec-ai.github.io/ArchUnitJava/>.

The landing page is maintained in `docs/site/`. The API reference is generated from the public Java
source with the Maven Javadoc plugin. `scripts/build-pages.ps1` combines both into `target/pages`,
Expand Down
3 changes: 3 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,9 @@ jobs:
- name: Build release candidate
shell: bash
run: ./mvnw --batch-mode --no-transfer-progress -Prelease-candidate -DskipTests verify
- name: Check reviewed public API signatures
shell: pwsh
run: ./scripts/check-public-api.ps1
- name: Reject unexpected SpotBugs findings
shell: bash
run: |
Expand Down
10 changes: 8 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,17 @@ uses semantic versioning for public releases.

## [Unreleased]

### Added

- declarative type/package cycle rules with `kind=cycles` in the properties/JUnit integration;
- an explicit v1 compatibility scope and public/protected API signature regression gate.

### Fixed

- preserve ordinary member-owned dependencies in type and package cycle checks when synthetic
edges are ignored (the default), and exclude synthetic member evidence correctly; checks may
now report real cycles that `0.1.0` silently missed;
- avoid call-stack overflow in SCC detection and bounded cycle enumeration on deep graphs;
- accept documented dotted CLI rule IDs while still rejecting unknown rule fields;
- retain input and parser failures in CLI/direct `CliAnalyzer` results so corrupt archives or
malformed classes cannot silently produce passing partial checks; and
Expand Down Expand Up @@ -56,5 +62,5 @@ uses semantic versioning for public releases.
- The performance corpus is regression evidence, not an absolute scalability claim.
- Unrestricted regex and lossless non-neutralized CSV require explicitly named trusted APIs.

[Unreleased]: https://github.com/LukasNiessen/ArchUnitJava/compare/v0.1.0...HEAD
[0.1.0]: https://github.com/LukasNiessen/ArchUnitJava/releases/tag/v0.1.0
[Unreleased]: https://github.com/dragonsec-ai/ArchUnitJava/compare/v0.1.0...HEAD
[0.1.0]: https://github.com/dragonsec-ai/ArchUnitJava/releases/tag/v0.1.0
27 changes: 16 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,13 @@
<!-- spacer -->
<p></p>

[![CI](https://github.com/LukasNiessen/ArchUnitJava/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/LukasNiessen/ArchUnitJava/actions/workflows/ci.yml?query=branch%3Amain)
[![Documentation](https://github.com/LukasNiessen/ArchUnitJava/actions/workflows/docs.yml/badge.svg)](https://lukasniessen.github.io/ArchUnitJava/)
[![CI](https://github.com/dragonsec-ai/ArchUnitJava/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/dragonsec-ai/ArchUnitJava/actions/workflows/ci.yml?query=branch%3Amain)
[![Documentation](https://github.com/dragonsec-ai/ArchUnitJava/actions/workflows/docs.yml/badge.svg)](https://dragonsec-ai.github.io/ArchUnitJava/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Java 25](https://img.shields.io/badge/Java-25-E76F00?logo=openjdk&logoColor=white)](https://openjdk.org/projects/jdk/25/)
[![Maven Central](https://img.shields.io/maven-central/v/io.github.tristankruse/archunitjava.svg?label=Maven%20Central)](https://central.sonatype.com/artifact/io.github.tristankruse/archunitjava/0.1.0)
[![Status: public beta](https://img.shields.io/badge/status-public%20beta-f89820)](docs/RELEASE.md)
[![GitHub stars](https://img.shields.io/github/stars/LukasNiessen/ArchUnitJava.svg)](https://github.com/LukasNiessen/ArchUnitJava)
[![GitHub stars](https://img.shields.io/github/stars/dragonsec-ai/ArchUnitJava.svg)](https://github.com/dragonsec-ai/ArchUnitJava)

</div>

Expand All @@ -27,14 +27,19 @@ deterministic policies, and produces evidence for JUnit and CI.
> in the [release assessment](docs/RELEASE.md). The pre-1.0 API remains provisional and may change
> between minor versions.

The current source prepares **1.0.0**. See the [release checklist](docs/V1_READINESS.md) and
[family feature comparison](docs/V1_FEATURE_COMPARISON.md). The cycle-evidence correction and
properties cycle rules described there require the development candidate; they are absent from
the published `0.1.0` beta.

_Inspired by the established [ArchUnit](https://www.archunit.org/) project, but independently
implemented and not affiliated with ArchUnit. This is not a drop-in replacement._

[Quickstart](#-five-minute-quickstart) · [Use cases](#-use-cases) ·
[Capabilities](#-capabilities) · [Inspection](#-logging-and-inspection) · [Reports](#-reports) ·
[Example repository](#-independent-example-repository) ·
[User guide](docs/USER_GUIDE.md) · [CLI reference](docs/CLI_REFERENCE.md) ·
[Documentation](https://lukasniessen.github.io/ArchUnitJava/) ·
[Documentation](https://dragonsec-ai.github.io/ArchUnitJava/) ·
[FAQ](#-faq) · [Contributing](CONTRIBUTING.md) ·
[Support](SUPPORT.md) · [Limitations](#-current-limitations) ·
[Adoption metrics](#-adoption-metrics)
Expand Down Expand Up @@ -219,15 +224,15 @@ analysis failure (`4`), and policy violations (`5`).
| Metrics | Source, cohesion, and dependency metrics with deterministic snapshots |
| Operational controls | Bounded diagnostics, import filters, `.archignore`, cache keys, resource and path limits |

The [generated API reference](https://lukasniessen.github.io/ArchUnitJava/api/) lists every public
The [generated API reference](https://dragonsec-ai.github.io/ArchUnitJava/api/) lists every public
package and type. The [user guide](docs/USER_GUIDE.md) maps every important feature area to its
normal workflow and API entry point; the [CLI reference](docs/CLI_REFERENCE.md) documents every
configuration key, command, format, and exit code. The internal architecture and ownership rules
are described in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).

## 🔎 Logging and inspection

> These logging and pretty-report APIs require **0.2.0 or later**, or a build of
> These logging and pretty-report APIs require the **unreleased 1.0 candidate**, or a build of
> the current `main` branch from source. The published **0.1.0** artifact used in
> the quickstart does not include them.

Expand Down Expand Up @@ -461,7 +466,7 @@ change should include a focused regression test, and packaging or integration ch
be verified against the independent RAG consumer.

Please report vulnerabilities through GitHub's private
[security-advisory form](https://github.com/LukasNiessen/ArchUnitJava/security/advisories/new), not a
[security-advisory form](https://github.com/dragonsec-ai/ArchUnitJava/security/advisories/new), not a
public issue. The supported scope and reporting guidance are in [SECURITY.md](SECURITY.md).

## ⚖️ Should I use this or ArchUnit?
Expand Down Expand Up @@ -536,9 +541,9 @@ ArchUnitJava is maintained by [Lukas Niessen](https://github.com/LukasNiessen),
To participate:

- read the [support policy](SUPPORT.md) for usage questions and bug reports;
- join [GitHub Discussions](https://github.com/LukasNiessen/ArchUnitJava/discussions) for usage and design questions;
- [open an issue](https://github.com/LukasNiessen/ArchUnitJava/issues/new/choose) for a reproducible bug or feature;
- [review existing issues](https://github.com/LukasNiessen/ArchUnitJava/issues); or
- join [GitHub Discussions](https://github.com/dragonsec-ai/ArchUnitJava/discussions) for usage and design questions;
- [open an issue](https://github.com/dragonsec-ai/ArchUnitJava/issues/new/choose) for a reproducible bug or feature;
- [review existing issues](https://github.com/dragonsec-ai/ArchUnitJava/issues); or
- contribute code or documentation through a pull request.

Participation is governed by the [code of conduct](CODE_OF_CONDUCT.md). Report vulnerabilities
Expand All @@ -557,7 +562,7 @@ workflow.
## 📄 License

The current development version is licensed under the [MIT License](LICENSE). The published
[`0.1.0` release](https://github.com/LukasNiessen/ArchUnitJava/blob/v0.1.0/LICENSE) remains under
[`0.1.0` release](https://github.com/dragonsec-ai/ArchUnitJava/blob/v0.1.0/LICENSE) remains under
the Apache License 2.0; released artifacts keep the license under which they were published.

<div align="right">
Expand Down
2 changes: 1 addition & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ long-term support commitment or stable release line exists before 1.0.
## Reporting a vulnerability

Please use GitHub's private
[security-advisory form](https://github.com/LukasNiessen/ArchUnitJava/security/advisories/new).
[security-advisory form](https://github.com/dragonsec-ai/ArchUnitJava/security/advisories/new).
Do not include exploit details, malicious bytecode, credentials, or private repository content in a
public issue.

Expand Down
8 changes: 4 additions & 4 deletions SUPPORT.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@

ArchUnitJava is currently a public beta maintained on a best-effort basis.

- Ask usage and design questions in [GitHub Discussions](https://github.com/LukasNiessen/ArchUnitJava/discussions).
- Report reproducible bugs with the [bug form](https://github.com/LukasNiessen/ArchUnitJava/issues/new?template=bug_report.yml).
- Propose product improvements with the [feature form](https://github.com/LukasNiessen/ArchUnitJava/issues/new?template=feature_request.yml).
- Report vulnerabilities privately through [GitHub Security Advisories](https://github.com/LukasNiessen/ArchUnitJava/security/advisories/new), following [SECURITY.md](SECURITY.md).
- Ask usage and design questions in [GitHub Discussions](https://github.com/dragonsec-ai/ArchUnitJava/discussions).
- Report reproducible bugs with the [bug form](https://github.com/dragonsec-ai/ArchUnitJava/issues/new?template=bug_report.yml).
- Propose product improvements with the [feature form](https://github.com/dragonsec-ai/ArchUnitJava/issues/new?template=feature_request.yml).
- Report vulnerabilities privately through [GitHub Security Advisories](https://github.com/dragonsec-ai/ArchUnitJava/security/advisories/new), following [SECURITY.md](SECURITY.md).

Before opening a bug, test the latest published beta, check the
[known limitations](README.md#-current-limitations), and include the JDK, operating system,
Expand Down
29 changes: 26 additions & 3 deletions docs/CLI_REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,10 +54,11 @@ For each ID in `rules`, use the prefix `rule.<id>.`.

| Field | Required | Values and behavior |
| --- | --- | --- |
| `kind` | no | `dependency` (default) or `cycles` |
| `domain` | yes | `types` or `packages` |
| `mode` | yes | `no`, `only`, `any`, or `required` |
| `mode` | dependency only | `no`, `only`, `any`, or `required` |
| `origins` | yes | One `exact:` or `glob:` qualified-name pattern |
| `targets` | yes | One `exact:` or `glob:` qualified-name pattern |
| `targets` | dependency only | One `exact:` or `glob:` qualified-name pattern |
| `self` | no | `include` or `ignore` (default `ignore`) |
| `external` | no | `ignore`, `fail`, `non-matching`, or `treat-as-non-matching` (default `fail`) |
| `displayName` | no | Human-readable name, 1–4,096 characters |
Expand All @@ -76,6 +77,28 @@ Rule modes mean:
imported model are intentionally irrelevant. `non-matching` retains external edges and lets the
rule mode decide whether they violate the policy.

### Cycle rules

Use `kind=cycles` with `domain=types` or `packages` and a single `origins` selection:

```properties
schema=archunitjava.cli.v1
inputs=target/classes
rules=cycles
rule.cycles.kind=cycles
rule.cycles.domain=packages
rule.cycles.origins=glob:com.example.**
```

The induced graph contains only selected imported subjects; paths through unselected types or
packages are outside the check. Empty selections fail by default. Cycle rules include type-use
dependencies and ignore synthetic evidence by default, using `CycleRuleOptions.defaults()`.
Ordinary member-owned dependencies are retained, including edges with mixed synthetic evidence.
`mode`, `targets`, `self`, and `external` are rejected for cycle rules. Use the Java API to customize
cycle policies. Metadata (`displayName`, `rationale`, `tags`, `severity`), result formats, and
incomplete-import handling work for both rule kinds. Older beta readers reject the new `kind` key;
omit it for dependency configurations shared with those versions.

## Patterns

`exact:` matches one qualified binary name. `glob:` supports the bounded project pattern language;
Expand Down Expand Up @@ -137,4 +160,4 @@ ordinary architecture violation.

Continue with the [user guide](USER_GUIDE.md), the
[working example](../examples/basic), or the
[CLI API reference](https://lukasniessen.github.io/ArchUnitJava/api/dev.archunitjava/dev/archunitjava/cli/package-summary.html).
[CLI API reference](https://dragonsec-ai.github.io/ArchUnitJava/api/dev.archunitjava/dev/archunitjava/cli/package-summary.html).
32 changes: 32 additions & 0 deletions docs/COMPATIBILITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,38 @@ development candidates. Release notes must identify them. ArchUnitJava does not
with the original ArchUnit API or its rule semantics. Configuration and report formats carry their
own schema versions and reject unknown schemas where ingestion exists.

## Version 1 contract (candidate)

The development version is `1.0.0-SNAPSHOT`; the public registry still contains the `0.1.0` beta.
These promises become effective with publication of `1.0.0`, after the
[candidate gates](V1_READINESS.md) pass:

- Public/protected declarations in the primary artifact form the supported Java API. Package-private
implementation and generated files are excluded. Public records' constructors/components are
API, including the preserved pre-cycle `CliRuleConfiguration` constructor.
- Compatible additions may ship in minor releases. Removing or changing existing signatures,
changing required configuration fields, raising the runtime floor, or making other incompatible
contract changes requires a major release. Fixing a documented rule's incorrect result is a bug
fix: cycle checks may correctly fail after an upgrade when earlier versions missed a violation.
- The v1 runtime/build baseline is JDK 25, with supported analyzed `javac` releases 8–25 as above.
Other runtimes, compilers, obfuscators and future class-file versions are not promised.
- Maven coordinates remain `io.github.tristankruse:archunitjava` despite the organization transfer.
The automatic module name remains `dev.archunitjava`. Consumers need no publishing account.
- Existing `archunitjava.cli.v1` dependency configurations keep their defaults. The new cycle kind is
additive; older beta readers reject that new field. Incompatible ingestion changes use a new
schema. CLI exit codes 0/2/3/4/5 preserve their documented meanings.
- Structured report IDs and schema-versioned fields are contracts; exact human prose, stack traces,
wall times, HTML/CSS layout and diagnostic ordering beyond documented deterministic sorting are
not byte-for-byte compatibility promises. Consumers should tolerate additive output fields.
- No Java serialization format, original ArchUnit API compatibility, complete dynamic-dependency
detection, or fixed performance/heap guarantee is promised.

`scripts/check-public-api.ps1` extracts public/protected declarations, descriptors, generic
signatures and constants using JDK 25 `javap` without initializing the analyzed classes. CI checks
them against `docs/api/v1-public-api.txt`. The gate deliberately flags additions too, requiring a
reviewed `-Update` change. It is a signature regression gate, not a proof of every behavioral or
binary compatibility property: tests and release review still cover semantics and schemas.

## Decision

The `0.1.x` line retains JDK 25 instead of adding a third-party parser solely to lower the
Expand Down
11 changes: 6 additions & 5 deletions docs/MAINTAINER_HANDOVER.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
# Maintainer handover

Status as of 2026-09-17: the GitHub repository transfer is complete.
[Lukas Niessen](https://github.com/LukasNiessen) owns
[`LukasNiessen/ArchUnitJava`](https://github.com/LukasNiessen/ArchUnitJava).
Status as of 2026-11-02: the repository now belongs to the `dragonsec-ai` organization at
[`dragonsec-ai/ArchUnitJava`](https://github.com/dragonsec-ai/ArchUnitJava).
[Lukas Niessen](https://github.com/LukasNiessen) is a maintainer following the earlier personal
account transfer on 2026-09-17.
Tristan Kruse remains a collaborator. The independent
[`TristanKruse/ArchUnitJava-TestRepo-RAG`](https://github.com/TristanKruse/ArchUnitJava-TestRepo-RAG)
was deliberately not transferred; library CI continues to check it out from Tristan's account.
Expand All @@ -13,9 +14,9 @@ was deliberately not transferred; library CI continues to check it out from Tris
point to Lukas's repository. Historical publishing facts and the RAG fixture's separate owner
remain unchanged.
- The repository homepage and GitHub Pages site use
<https://lukasniessen.github.io/ArchUnitJava/>. GitHub does not redirect the former Pages URL;
<https://dragonsec-ai.github.io/ArchUnitJava/>. GitHub does not redirect the former Pages URL;
it currently returns 404. Git repository and Git activity URLs redirect, but other local clones
should update their remotes to `https://github.com/LukasNiessen/ArchUnitJava.git`.
should update their remotes to `https://github.com/dragonsec-ai/ArchUnitJava.git`.
- Release-tag automation uses the workflow initiator as tagger rather than hard-coding Tristan.
Existing signed tags and their attribution have not been modified. A future tag's GitHub
verification also depends on the signing key's identity matching the new tagger address.
Expand Down
6 changes: 5 additions & 1 deletion docs/RELEASE.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# Release status

The next release is the `1.0.0` candidate. Its current evidence and remaining go/no-go gates are
tracked in [V1_READINESS.md](V1_READINESS.md). The record below describes the immutable published
beta; its test counts and account configuration are historical, not current candidate evidence.

**Decision: PUBLISHED PUBLIC BETA.** Version `0.1.0` became publicly available from Maven Central on
2026-09-01.

Expand Down Expand Up @@ -76,7 +80,7 @@ Publication evidence:
- Signed tag `v0.1.0` resolves to reviewed commit
`631e4506e99b8604b096971792fadba9e5edb55d`; independent GPG verification returned `GOODSIG` and
`VALIDSIG` for the dedicated signing-key fingerprint.
- [GitHub Actions staging run 33523489977](https://github.com/LukasNiessen/ArchUnitJava/actions/runs/33523489977)
- [GitHub Actions staging run 33523489977](https://github.com/dragonsec-ai/ArchUnitJava/actions/runs/33523489977)
verified the tag, materialized `0.1.0`, ran 347 tests with zero failures or errors, signed the four
release artifacts, uploaded the bundle, and waited for Central validation.
- Central deployment `12dfc7c7-4015-4fbf-887e-bc3103ff6560` validated one out of one components and
Expand Down
Loading
Loading