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
104 changes: 104 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
name: Release

on:
workflow_dispatch:
inputs:
version:
description: Version from Cargo.toml, without a leading v
required: true
type: string

concurrency:
group: crates-io-release
cancel-in-progress: false

jobs:
publish:
name: Publish archunit ${{ inputs.version }}
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
timeout-minutes: 30
environment: release
permissions:
contents: read
id-token: write
steps:
- name: Check out the release commit
uses: actions/checkout@v7
with:
fetch-depth: 0
persist-credentials: false

- name: Install stable Rust with quality components
run: rustup toolchain install stable --profile minimal --component rustfmt,clippy --no-self-update

- name: Verify the requested version and release inputs
env:
RELEASE_VERSION: ${{ inputs.version }}
run: |
actual_version=$(cargo +stable metadata --no-deps --format-version 1 | jq -r '.packages[] | select(.name == "archunit") | .version')
if [ "$actual_version" != "$RELEASE_VERSION" ]; then
echo "Requested $RELEASE_VERSION, but Cargo.toml contains $actual_version" >&2
exit 1
fi
if git rev-parse --quiet --verify "refs/tags/v$RELEASE_VERSION" >/dev/null; then
echo "Tag v$RELEASE_VERSION already exists" >&2
exit 1
fi
grep --fixed-strings "archunit = \"=$RELEASE_VERSION\"" tests/fixtures/registry_consumer/Cargo.toml.template

- name: Re-run every release quality gate
run: |
cargo +stable fmt --all -- --check
cargo +stable clippy --workspace --all-targets --all-features --locked -- -D warnings
cargo +stable test --workspace --all-features --locked
RUSTDOCFLAGS="-D warnings" cargo +stable doc --workspace --all-features --no-deps --locked
cargo +stable publish --dry-run --locked

- name: Acquire a short-lived crates.io token
id: auth
uses: rust-lang/crates-io-auth-action@v1

- name: Publish the immutable crate archive
env:
CARGO_REGISTRY_TOKEN: ${{ steps.auth.outputs.token }}
run: cargo +stable publish --locked

verify:
name: Verify registry installation and create the GitHub release
needs: publish
runs-on: ubuntu-latest
timeout-minutes: 10
permissions:
contents: write
steps:
- name: Check out the published commit
uses: actions/checkout@v7
with:
fetch-depth: 0
persist-credentials: false

- name: Install stable Rust
run: rustup toolchain install stable --profile minimal --no-self-update

- name: Install the exact registry version in a standalone project
run: |
consumer="$RUNNER_TEMP/archunit-registry-consumer"
mkdir -p "$consumer"
cp tests/fixtures/registry_consumer/Cargo.toml.template "$consumer/Cargo.toml"
cp -R tests/fixtures/registry_consumer/src "$consumer/src"
cp -R tests/fixtures/registry_consumer/tests "$consumer/tests"
for attempt in $(seq 1 18); do
if CARGO_TARGET_DIR="$RUNNER_TEMP/registry-consumer-target" cargo +stable test --manifest-path "$consumer/Cargo.toml"; then
exit 0
fi
echo "Registry version is not visible yet (attempt $attempt of 18)" >&2
sleep 10
done
exit 1

- name: Tag the verified commit and create the GitHub release
env:
GH_TOKEN: ${{ github.token }}
RELEASE_VERSION: ${{ inputs.version }}
run: gh release create "v$RELEASE_VERSION" --target "$GITHUB_SHA" --title "archunit v$RELEASE_VERSION" --generate-notes
29 changes: 29 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# Changelog

All notable changes to ArchUnitRust are documented in this file. The project follows Semantic
Versioning; the `0.0.x` line deliberately signals that the public API is still experimental.

## [Unreleased]

## [0.0.1] - 2026-08-24

### Added

- Deterministic Cargo package and workspace discovery with Rust module-tree and dependency
extraction.
- Fluent architecture rules for files, named layers, captured slices, and external Cargo modules.
- Public graph projections, cycle analysis, six offline report formats, and PlantUML policies.
- Rust-native count, cohesion, coupling, distance, custom-metric, and metrics-report APIs.
- Strict empty-test protection, reusable pattern exclusions, typed violations, deterministic
diagnostics, `assert_passes!`, and opt-in per-check logging.
- Self-hosting architecture tests, a cross-platform CI matrix, a source-checked user guide, and
generated API documentation.

### Known limitations

- Analysis is syntax-based and does not expand macros or build-script-generated source.
- Conditional compilation branches are modeled as a conservative union.
- Dependency nodes are source files rather than individual Rust items.

[Unreleased]: https://github.com/LukasNiessen/ArchUnitRust/compare/v0.0.1...HEAD
[0.0.1]: https://github.com/LukasNiessen/ArchUnitRust/releases/tag/v0.0.1
3 changes: 2 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ ArchUnitRust follows the same issue-driven product plan as the other ArchUnitEve
an intentionally sequential delivery workflow while the initial public surface is being formed.

Read [AGENTS.md](AGENTS.md), the [porting plan](docs/PORTING_PLAN.md), and the relevant issue before
changing code.
changing code. Release maintainers must also follow [RELEASING.md](RELEASING.md).

## Workflow

Expand Down Expand Up @@ -39,6 +39,7 @@ cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features
cargo test --doc
cargo doc --workspace --all-features --no-deps
cargo package --locked
```

Tests must be deterministic and independent of execution order. Public failures should assert the
Expand Down
16 changes: 15 additions & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,26 @@ edition = "2024"
rust-version = "1.85"
description = "Architecture testing for Rust"
repository = "https://github.com/LukasNiessen/ArchUnitRust"
homepage = "https://lukasniessen.github.io/ArchUnitRust/"
documentation = "https://lukasniessen.github.io/ArchUnitRust/api/archunit/"
license = "MIT"
readme = "README.md"
keywords = ["architecture", "testing", "dependencies", "static-analysis"]
categories = ["development-tools::testing"]
exclude = ["docs/assets/og.png"]
publish = ["crates-io"]
exclude = [
".github/**",
"AGENTS.md",
"CLAUDE.md",
"CONTRIBUTING.md",
"RELEASING.md",
"docs/PORTING_PLAN.md",
"docs/_config.yml",
"docs/_layouts/**",
"docs/adr/**",
"docs/assets/**",
"tests/**",
]

[lib]
path = "src/lib.rs"
Expand Down
16 changes: 16 additions & 0 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
Copyright 2026 Lukas Niessen <lks.niessen@gmail.com> https://lukasniessen.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
associated documentation files (the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge, publish, distribute,
sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT
OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
53 changes: 53 additions & 0 deletions RELEASING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# Releasing ArchUnitRust

Crates.io versions are immutable. A release is complete only when the registry archive can be
installed by a separate project, the matching Git tag and GitHub release exist, and the public
installation instructions name that published version.

## One-time bootstrap for 0.0.1

Crates.io requires a crate's first version to be published manually before a trusted GitHub
publisher can be configured. From a clean, current `main` whose CI is green:

1. Sign in to crates.io, verify the account email address, and create a short-lived API token that
is permitted to publish a new crate. Never put the token in Git, an issue, a workflow log, or a
chat message.
2. Store it with `cargo login`, run `cargo publish --dry-run --locked`, inspect the reported archive
contents, then run `cargo publish --locked` exactly once.
3. Copy `tests/fixtures/registry_consumer/` to a temporary directory, rename
`Cargo.toml.template` to `Cargo.toml`, and run `cargo test --manifest-path <temp>/Cargo.toml`.
Retry briefly if the crates.io index has not propagated yet. This fixture must resolve
`archunit = "=0.0.1"`; do not add a path or Git override.
4. Only after that test passes, create the matching release boundary:

```console
gh release create v0.0.1 --target main --title "archunit v0.0.1" --generate-notes
```

5. Remove the local token with `cargo logout` if it is not needed for another crate.
6. In the crate's crates.io Trusted Publishing settings, add the GitHub repository owner
`LukasNiessen`, repository `ArchUnitRust`, workflow `release.yml`, and environment `release`.

Do not invoke `.github/workflows/release.yml` for 0.0.1: the trusted publisher cannot exist until
that first version has reserved the crate name.

## Later releases

Prepare each version in its own reviewed branch and PR:

1. Update `package.version` in `Cargo.toml` and refresh `Cargo.lock`.
2. Move the relevant changelog entries under a dated version heading and update comparison links.
3. Update the exact `archunit` version in
`tests/fixtures/registry_consumer/Cargo.toml.template` and the constant in
`tests/release_workflow.rs`.
4. Run the complete local gate set and merge only after CI is green.
5. From `main`, manually dispatch the Release workflow with the version number and no leading `v`.

The publish job rechecks the version, tag absence, formatting, Clippy, all tests, rustdoc, and the
crate archive before obtaining a short-lived crates.io token through OpenID Connect. The verify job
then installs the exact registry version in the standalone fixture. Only after that succeeds does it
create the Git tag and GitHub release.

If registry propagation delays the fixture, rerun only the failed verify job. The successful publish
job must not be rerun for an immutable version. If publication itself fails before crates.io accepts
the archive, correct the cause in a new PR; never reuse a version that the registry accepted.
59 changes: 59 additions & 0 deletions docs/adr/0025-bootstrap-then-use-trusted-publishing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# ADR 0025: Bootstrap once, then publish with short-lived credentials

**Status:** accepted

## Context

Publishing a crates.io version is irreversible: its archive cannot be overwritten or deleted. A
long-lived repository secret would make later automation possible, but it would also remain useful
to an attacker until rotated or expired. Crates.io Trusted Publishing exchanges GitHub's OpenID
Connect identity for a short-lived token, but the trusted publisher can only be configured by an
owner after the crate's first version exists.

A release also has two different success boundaries. Uploading the archive proves registry
acceptance; it does not prove that a clean consumer can resolve, compile, and exercise the exact
version. Combining upload and propagation-sensitive verification in one job makes recovery unsafe:
rerunning a failed job would attempt to publish the same immutable version again.

## Decision

Publish 0.0.1 manually from a clean, green `main` with a locally entered, short-lived crates.io token.
The token is never committed or transmitted through GitHub. Verify the accepted version through a
standalone fixture whose development dependency pins `archunit = "=0.0.1"`. Create the Git tag and
GitHub release only after that registry-backed test passes, then remove the local token.

After the crate exists, configure crates.io to trust `.github/workflows/release.yml` in the GitHub
`release` environment. Later releases use manual workflow dispatch from `main`. The workflow denies
version drift and existing tags, repeats all quality gates, obtains an ephemeral token through the
Rust project's authentication action, and publishes with the lockfile enforced.

Keep publication and verification in separate jobs. The second job polls registry installation,
runs a real fluent architecture rule, and creates the tag and GitHub release. A delayed registry
index can therefore rerun verification without rerunning a successful upload.

## Consequences

- The first release has one documented manual credential step; later releases store no crates.io
token in GitHub.
- A version tag means both crates.io acceptance and successful clean-consumer installation.
- The registry fixture is version-coupled release data and must change with every version bump.
- The `release` environment becomes part of the crates.io trust identity and cannot be renamed
casually.
- A publication accepted by crates.io remains released even if a later verification service is
temporarily unavailable; the split job makes completing that boundary safely rerunnable.

## Alternatives considered

### Store a crates.io token as a GitHub Actions secret

Rejected. It solves the first upload but leaves a reusable credential in a second system for every
later release.

### Create the tag before publishing

Rejected. A rejected archive would leave a public release marker for a version users cannot install.

### Publish and verify in one job

Rejected. Registry propagation failure would make the failed job unsafe to rerun because its upload
step may already have succeeded.
1 change: 1 addition & 0 deletions docs/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,3 +28,4 @@ rewriting history after released behavior depends on it.
- [0022: Enforce a Rust-aware self-architecture](0022-enforce-rust-aware-self-architecture.md)
- [0023: Publish a source-checked guide beside rustdoc](0023-publish-a-source-checked-guide-beside-rustdoc.md)
- [0024: Split CI by evidence and supported host](0024-split-ci-by-evidence-and-supported-host.md)
- [0025: Bootstrap once, then publish with short-lived credentials](0025-bootstrap-then-use-trusted-publishing.md)
8 changes: 8 additions & 0 deletions tests/fixtures/registry_consumer/Cargo.toml.template
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
[package]
name = "archunit-registry-consumer"
version = "0.0.0"
edition = "2024"
publish = false

[dev-dependencies]
archunit = "=0.0.1"
3 changes: 3 additions & 0 deletions tests/fixtures/registry_consumer/src/api.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
pub fn health() -> &'static str {
"ok"
}
5 changes: 5 additions & 0 deletions tests/fixtures/registry_consumer/src/lib.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
mod api;
mod persistence;

pub use api::health;
pub use persistence::schema_version;
3 changes: 3 additions & 0 deletions tests/fixtures/registry_consumer/src/persistence.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
pub fn schema_version() -> u32 {
1
}
14 changes: 14 additions & 0 deletions tests/fixtures/registry_consumer/tests/architecture.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
use archunit::{assert_passes, project_files_in};

const PROJECT_ROOT: &str = env!("CARGO_MANIFEST_DIR");

#[test]
fn api_does_not_depend_on_persistence() {
let rule = project_files_in(PROJECT_ROOT)
.in_path("src/api.rs")
.should_not()
.depend_on_files()
.in_path("src/persistence.rs");

assert_passes!(rule);
}
Loading