Skip to content
Open
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
20 changes: 20 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -72,3 +72,23 @@ jobs:

- name: Run the dogfooding architecture tests
run: dotnet test tests/ArchUnitSharp.Dogfood.Tests --no-restore

packages:
runs-on: ${{ matrix.os }}
needs: build
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-dotnet@v4
with:
dotnet-version: '10.0.x'
- uses: actions/setup-python@v5
with:
python-version: '3.x'
- name: Pack complete dependency graph
run: dotnet pack ArchUnitSharp.sln -c Release -p:Version=3.0.0-beta.1 -o artifacts/packages
- name: Inspect packages and test isolated consumer
run: python eng/verify-packages.py --version 3.0.0-beta.1
95 changes: 95 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
name: prepare or publish packages

on:
workflow_dispatch:
inputs:
version:
description: Coordinated SemVer package version
required: true
default: 3.0.0-beta.1
publish:
description: Publish the validated artifacts (requires resolved license and NuGet environment)
type: boolean
default: false

permissions:
contents: read

concurrency:
group: nuget-release
cancel-in-progress: false

jobs:
prepare:
runs-on: ubuntu-latest
env:
RELEASE_VERSION: ${{ inputs.version }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-dotnet@v4
with:
dotnet-version: '10.0.x'
- uses: actions/setup-python@v5
with:
python-version: '3.x'
- name: Validate version
run: |
python - <<'PY'
import os, re
if not re.fullmatch(r'[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?', os.environ['RELEASE_VERSION']):
raise SystemExit('Expected a plain SemVer release version.')
PY
- name: Restore and build
run: |
dotnet restore ArchUnitSharp.sln -p:Version="$RELEASE_VERSION"
dotnet build ArchUnitSharp.sln -c Release --no-restore -p:Version="$RELEASE_VERSION"
- name: Check formatting and tests
run: |
dotnet format ArchUnitSharp.sln --verify-no-changes --no-restore
dotnet test ArchUnitSharp.sln -c Release --no-build --no-restore -p:Version="$RELEASE_VERSION"
- name: Pack and test isolated consumer
run: |
dotnet pack ArchUnitSharp.sln -c Release --no-build --no-restore -p:Version="$RELEASE_VERSION" -o artifacts/packages
python eng/verify-packages.py --version "$RELEASE_VERSION"
- uses: actions/upload-artifact@v4
with:
name: nuget-packages
path: artifacts/packages/*.nupkg
if-no-files-found: error

publish:
if: inputs.publish && github.ref == 'refs/heads/main'
needs: prepare
runs-on: ubuntu-latest
environment: nuget
env:
RELEASE_VERSION: ${{ inputs.version }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-dotnet@v4
with:
dotnet-version: '10.0.x'
- uses: actions/setup-python@v5
with:
python-version: '3.x'
- uses: actions/download-artifact@v4
with:
name: nuget-packages
path: artifacts/packages
- name: Require confirmed license in every package
run: python eng/verify-packages.py --version "$RELEASE_VERSION" --require-license --inspect-only
- name: Publish the validated artifacts
env:
NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }}
run: |
test -n "$NUGET_API_KEY" || { echo 'Configure NUGET_API_KEY in the nuget environment.'; exit 1; }
dotnet nuget push 'artifacts/packages/*.nupkg' --source https://api.nuget.org/v3/index.json --api-key "$NUGET_API_KEY" --skip-duplicate
- name: Verify public installation
run: |
for attempt in 1 2 3 4 5; do
if python eng/verify-packages.py --version "$RELEASE_VERSION" --require-license --public; then
exit 0
fi
sleep 30
done
exit 1
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,4 @@ TestResults/
.idea/
docs/_site/
docs/api/
artifacts/
4 changes: 4 additions & 0 deletions NOTES.md
Original file line number Diff line number Diff line change
Expand Up @@ -664,3 +664,7 @@ restore, build (0 warnings, 0 errors), format --verify-no-changes, 112 extractio
tests passed (test-attribute count 166 at base -> 213 now, nothing removed, nothing skipped), no
vulnerable packages. The crash is the reviewer-tooling hang class already noted in Round 2, not a
code defect; there is nothing to fix.

WHY: Issue #53 packaging preparation uses the proposed ArchUnit 3.0.0-beta.1 identity with coordinated ArchUnitSharp.* dependencies and retains net10.0/namespaces; public publication is explicitly gated on a reviewed LICENSE because neither promoted repository supplies a confirmed license and the legacy package's declaration cannot be assumed.
WHY: Issue #54 is addressed only for the demonstrated trailing-/** base-folder omission; broader sibling glob compatibility choices remain open rather than changing unrelated selector semantics in a release-packaging PR.
WHY: Issue #51 adds Testing→Metrics to format structured metric violations; the dogfood dependency table now permits that acyclic edge while Metrics remains Common-only. No architecture checks are skipped.
10 changes: 8 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
# ArchUnit.NET

The canonical repository is [LukasNiessen/ArchUnitNET](https://github.com/LukasNiessen/ArchUnitNET).
The canonical repository is [dragonsec-ai/ArchUnitNET](https://github.com/dragonsec-ai/ArchUnitNET).
This implementation was developed by [Robey Beswick](https://github.com/RobeyBeswick) as
ArchUnitSharp and promoted here on 5 October 2026. Its project names and C# namespaces remain
`ArchUnitSharp` while the package and API transition is planned. The previous implementation,
`ArchUnitSharp`. The proposed package transition is documented in the
[migration guide](docs/guide/migration.md). The previous implementation,
including its branches and release tags, is preserved in
[Deprecated-ArchUnitNET](https://github.com/LukasNiessen/Deprecated-ArchUnitNET).

Expand Down Expand Up @@ -44,6 +45,11 @@ the composition root and the assertion adapter to your test project:
use the framework-agnostic helper `ArchUnitSharp.Testing.RuleAssert.Passes(rule)` /
`RuleAssert.Fails(rule)`; it works with every framework and needs no configuration.

The proposed `3.0.0-beta.1` packages can be built and tested with an isolated consumer using
the [release guide](docs/guide/release.md). Public publication remains blocked until the promoted
implementation's license is confirmed. This is a breaking .NET 10/API transition, not an
in-place upgrade of the existing NuGet package.

## A first rule in ten lines

A rule is checked from a test. The entry point locates your project by walking up from the current
Expand Down
146 changes: 146 additions & 0 deletions docs/guide/migration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,146 @@
# Migrating from ArchUnit 2.4.0-alpha.2

The promoted implementation is a breaking replacement, developed by Robey Beswick as
ArchUnitSharp and adopted on 5 October 2026. Historical packages and tags are unchanged;
the previous source is preserved in [Deprecated-ArchUnitNET](https://github.com/LukasNiessen/Deprecated-ArchUnitNET).

## Distribution and runtime

The proposed first release is `3.0.0-beta.1`. It is **not yet published**. The source and
packages require .NET 10; a .NET 8 or 9 test project cannot reference them. The application
being inspected is a C# source tree and need not itself target .NET 10.

The composition-root package keeps the `ArchUnit` install identity. Its assembly and
namespaces are `ArchUnitSharp`. Ten supporting `ArchUnitSharp.*` packages carry the same
version. For xUnit, install `ArchUnit` and `ArchUnitSharp.Testing.Xunit`; for a generic
assertion helper, install `ArchUnit` and `ArchUnitSharp.Testing`. All other module
dependencies restore transitively. There are no current native NUnit or MSTest adapters.

To try the locally built packages before publication, follow [the release guide](release.md).
Once the exact version is publicly available, the equivalent xUnit installation is:

```sh
dotnet add package ArchUnit --version 3.0.0-beta.1
dotnet add package ArchUnitSharp.Testing.Xunit --version 3.0.0-beta.1
```

## API changes

| Previous implementation | Promoted implementation |
| --- | --- |
| `using ArchUnitNet;` | `using ArchUnitSharp;` |
| `ArchUnit.ProjectFiles(path)` | `Project.ProjectFiles(ProjectLocator.Locate(path))` |
| `DependOnFiles()` | `DependOn()` |
| `await rule.CheckAsync()` | `rule.Check()` |
| `await rule.PassesAsync()` | `rule.AssertPasses()` from `ArchUnitSharp.Testing.Xunit` |
| Framework-specific old adapters | xUnit adapter or `RuleAssert.Passes(rule)` |
| `Metrics<T>()` | Source selection with `Project.Metrics(location)`; type-scoped entry is unsupported |
| `{Layer}` / `{Slice}` grouping | Explicit named layer definitions / slice glob captures |

The following examples belong inside tests with these imports and a location pointing to
the source project. `eng/package-consumer/ArchitectureTests.cs` compiles and exercises the
new files, layers, slices, metrics and assertion surfaces using packages alone.

```csharp
using ArchUnitSharp;
using ArchUnitSharp.Extraction;
using ArchUnitSharp.Testing;
using ArchUnitSharp.Testing.Xunit;

var location = ProjectLocator.Locate("/path/to/source-project");
```

### Files and assertions

Replace `ArchUnit.ProjectFiles(path).InFolder("src/App").ShouldNot().DependOnFiles()`
and its asynchronous assertion with:

```csharp
var rule = Project.ProjectFiles(location)
.InFolder("src/App/**").ShouldNot().DependOn().InFolder("src/Storage/**");
rule.AssertPasses();
// Alternative without a framework-native adapter:
RuleAssert.Passes(rule);
// Or inspect structured violations directly:
var violations = rule.Check();
```

`InFolder("src/App/**")` includes the base folder and its descendants. Dependencies
still follow local `using` imports, not every semantic type reference (issue #47).
Repeated checks cache extraction within a process. If a tool edits the source between
checks, use the documented `CheckOptions.ClearCache` option or `GraphCache.Clear()`.

### Layers

The previous `{Layer}` extraction and `Where(Layer.Defined(...)).MayOnlyDependOn(...)`
becomes explicit declarations and a named constraint:

```csharp
Project.Layers(location)
.Layer("App").DefinedByFolder("src/App")
.Layer("Models").DefinedByFolder("src/Models")
.WhereLayer("App").MayOnlyDependOnLayers("Models")
.AssertPasses();
```

### Slices and cycles

`DefinedBy("src/{Slice}/**").Should().BeAcyclic()` has no direct slice-cycle equivalent
in this implementation. Use slice dependency constraints where appropriate:

```csharp
Project.Slices(location).DefinedBy("src/(**)/*.cs")
.ShouldNot().ContainDependency("src/Models/**", "src/App/**")
.AssertPasses();
```

File cycles are supported separately; they are not the same as cycles in a collapsed
slice graph:

```csharp
Project.ProjectFiles(location).Should().HaveNoCycles().AssertPasses();
```

### Metrics

Replace reflection/type-scoped metrics and old threshold method names with a source
selection and the new threshold grammar. For example:

```csharp
Project.Metrics(location).Count().LinesOfCode().ShouldBeBelowOrEqual(300).AssertPasses();
Project.Metrics(location).Count().MethodCount().ShouldBeBelow(20).AssertPasses();
```

Lines of code counts non-blank source lines. `ShouldBeBelow` is strict; use
`ShouldBeBelowOrEqual` for an inclusive maximum. Failed metric assertions now format
the measured value and expected condition through both generic and xUnit helpers.

## Legacy feature status

| Legacy feature | Current status |
| --- | --- |
| File boundaries, naming, file cycles | Replaced by the current files DSL |
| Named layers | Replaced by explicit declarations and layer constraints |
| Slice grouping and dependency rules | Replaced by capture globs and current slice rules |
| Slice-level cycle API | Deferred; file-cycle checks are not equivalent |
| Count/cohesion metrics | Replaced by source-based count/LCOM rules; review metric definitions |
| Architecture presets | Deferred; express policies explicitly |
| JSON configuration | Deferred; declare rules in C# |
| Baselines/snapshots | Deferred; no migrated baseline API |
| SARIF/JSON/text/HTML violation exports | Deferred; graph exports and metric HTML reports are separate features |
| Graph reports | Current DOT/Mermaid/D2/CSV/JSON/HTML exporters |
| Profiling API | Deferred |
| xUnit integration | Replaced by synchronous `AssertPasses` / `AssertFails` |
| Native NUnit/MSTest adapters | Deferred; use framework-neutral `RuleAssert` |

Empty selections fail by default. Do not use `AllowEmptyTests` to conceal a migration
that selects the wrong files. Known selector differences beyond trailing `/**` remain
tracked in issue #54; this release does not claim glob compatibility with every sibling.

## Remaining release work

Issue #53 stays open until the promoted implementation's license/provenance is confirmed,
the package identity/version choices are reviewed, the complete package graph is published
and publicly verified, and the website accurately reflects this API and runtime boundary.
The owner of the former `RobeyBeswick/ArchUnitSharp` repository must also coordinate its
redirect or retirement; this change does not claim that owner action is complete.
65 changes: 65 additions & 0 deletions docs/guide/release.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# Building and releasing packages

The packaging proposal keeps the root NuGet ID `ArchUnit`, with `ArchUnitSharp` assemblies
and namespaces and ten `ArchUnitSharp.*` supporting packages. All eleven share one version,
currently `3.0.0-beta.1`, and target .NET 10. The legacy `2.4.0-alpha.2` package is unchanged.
The original implementation is attributed to Robey Beswick in every package.

## Local verification

With .NET 10 and Python 3.9 or newer:

```sh
dotnet restore ArchUnitSharp.sln -p:Version=3.0.0-beta.1
dotnet build ArchUnitSharp.sln -c Release --no-restore -p:Version=3.0.0-beta.1
dotnet format ArchUnitSharp.sln --verify-no-changes --no-restore
dotnet test ArchUnitSharp.sln -c Release --no-build --no-restore -p:Version=3.0.0-beta.1
dotnet pack ArchUnitSharp.sln -c Release --no-build --no-restore -p:Version=3.0.0-beta.1 -o artifacts/packages
python eng/verify-packages.py --version 3.0.0-beta.1
```

Use an empty output directory when changing versions: the verifier rejects unexpected
or missing packages. It inspects IDs, versions, all internal dependencies, net10.0 DLLs,
XML documentation, repository metadata, README and attribution. It then copies the xUnit
consumer outside this checkout, uses a fresh NuGet package cache, maps all ArchUnit package
IDs exclusively to the local feed, and restores external dependencies from nuget.org.
No project references or source-built DLL paths are permitted in that consumer.

The consumer tests forbidden dependencies, cycles and LOC limits through failure and
repair, plus layer/slice/graph examples. CI repeats package consumption on Linux, Windows
and macOS. This is a prerequisite for release, not a claim of complete platform coverage.

## License and publication gate

The promoted source currently has no confirmed license declaration. Both the canonical
and former repositories lack a recognized license. The old package's Apache-2.0 metadata
does not establish the rewrite's license. **Publication remains blocked under issue #53.**

After resolving provenance with the implementation owner, commit the reviewed root
`LICENSE` text. Shared package metadata includes it as a NuGet file license automatically.
The publication job requires that license in every artifact; it does not infer an SPDX
identifier or silently reuse the old license. Local inspection artifacts are for evaluating
the packaging and are not a completed public release.

## Workflow

The `prepare or publish packages` workflow is manual. Its default `publish=false` runs
formatting, the full test suite, package inspection and the isolated consumer, and retains
the exact package artifacts. Review these before enabling publication.

For publication, run from `main` with the approved version and `publish=true`. Configure
the repository's `nuget` environment and its `NUGET_API_KEY` with publishing rights for
all eleven IDs. Confirm ownership of new IDs before release. The job downloads the
already-tested artifacts, enforces the license gate, pushes them and checks installation
from public NuGet with a fresh cache. Indexing retries are bounded; inspect failures rather
than declaring a successful publication merely from a push response.

Publish the complete graph: `ArchUnit`, `ArchUnitSharp.Common`, `ArchUnitSharp.Extraction`,
`ArchUnitSharp.Projection`, `ArchUnitSharp.Files`, `ArchUnitSharp.Graph`,
`ArchUnitSharp.Layers`, `ArchUnitSharp.Slices`, `ArchUnitSharp.Metrics`,
`ArchUnitSharp.Testing`, and `ArchUnitSharp.Testing.Xunit`.

After public installation is verified, update the README's unpublished status and the
website's package version, .NET 10 requirement, namespaces, synchronous examples, adapter
list, license and feature claims. Keep historical NuGet download totals labelled as
historical. Do not advertise the new implementation as published before this succeeds.
6 changes: 5 additions & 1 deletion docs/toc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@
items:
- name: Getting started
href: guide/getting-started.md
- name: Migrating from the previous implementation
href: guide/migration.md
- name: Building and releasing packages
href: guide/release.md
- name: The fluent grammar
href: guide/fluent-grammar.md
- name: Files
Expand All @@ -21,4 +25,4 @@
- name: Limitations
href: guide/limitations.md
- name: API reference
href: api/ArchUnitSharp.yml
href: api/ArchUnitSharp.yml
Loading
Loading