YAML-first architecture governance for .NET repositories.
ArchLinterNet turns architecture decisions into executable, reviewable contracts. It governs namespace and assembly boundaries, project/package metadata, semantic roles and contexts, public API surfaces, architecture coverage, migration debt, and CI change gates — with deterministic diagnostics that humans and automation can consume.
One packed ArchLinterNet CLI covers the complete static architecture-governance cycle: declare and check policy, prove applicability, validate topology and visible contract surfaces, govern finding and waiver debt, measure budgets, bind repository-local SARIF, compare change, project Architecture Health, and render PR Markdown and the real Health badge. CI invokes and transports the resulting canonical artifacts; it is not a second governance implementation.
The goal is not just to lint dependencies. ArchLinterNet makes architecture rules explicit and safe to evolve as normal repository code.
Versioning and updates
ArchLinterNet follows Semantic Versioning with an explicit release-train convention while the project remains in the 0.x initial-development range:
0.Y.0 is a capability release: a reviewed user-facing product increment. Minor releases may include compatibility changes while the project is pre-1.0, so review the release notes before upgrading.0.Y.Z with Z > 0 is a maintenance release for the same 0.Y capability line: correctness/integration fixes, reliability fixes, documentation corrections, and behavior-preserving engineering cleanup. Unrelated next-minor capability work is intentionally excluded.*-preview.N is an early-validation preview release and may still change before stable publication.X.Y.Z-main.N is an internal development/dogfood build, not a public stable release.
Within a released minor line, consumers should normally prefer the latest available patch after reviewing its release notes. See Versioning and release meaning for the complete public contract and Adopt or upgrade ArchLinterNet for upgrade steps.
Why ArchLinterNet?
Architecture rules often start as diagrams, ADRs, review comments, handwritten test helpers, or tribal knowledge. That works for a while, but the rules quickly become hard to discover, hard to reuse across repositories, and hard for humans or AI agents to review consistently.
ArchLinterNet uses a repository-owned YAML policy file as the source of truth:
architecture/arch.yml (recommended; any selected filename works)
↓
ArchLinterNet CLI / test adapter
↓
strict or audit architecture validation
↓
human diagnostics + JSON/SARIF/CI artifacts
Use it when you want architecture rules to be declarative, reviewable, CI-friendly, and independent from one-off test code.
Quick start
Create a root policy. This quick start uses the recommended concise path architecture/arch.yml; the filename is configurable and has no runtime semantics. New policy authoring should prefer version: 2, which defaults manual waivers to strict lifecycle governance; existing version: 1 policies remain supported with compatibility defaults.
version: 2
name: Example Architecture Contract
layers:
application:
namespace: MyApp.Application
domain:
namespace: MyApp.Domain
infrastructure:
namespace: MyApp.Infrastructure
analysis:
target_assemblies:
- MyApp.Application
- MyApp.Domain
- MyApp.Infrastructure
contracts:
strict:
- id: application-not-infrastructure
name: application-must-not-depend-on-infrastructure
source: application
forbidden: [infrastructure]
reason: Application code must depend on abstractions, not concrete infrastructure.
strict_layers:
- id: clean-architecture-layering
name: clean-architecture-layering
layers: [infrastructure, application, domain]
reason: Dependencies must point inward toward the domain.
Run from this repository during development:
dotnet run --project src/ArchLinterNet.Cli -- --policy architecture/arch.yml --mode strict
After installing the .NET tool from NuGet.org:
arch-linter-net --policy architecture/arch.yml --mode strict
For repository/CI adoption, prefer a local tool manifest and run dotnet arch-linter-net ...; see Installation.
Main capabilities
ArchLinterNet focuses on static architecture governance:
- YAML root policies, deterministic local imports, packaged schemas, and reusable bounded source sets.
- Namespace/layer dependency, allow-only, ordered-layer, protected-surface, cycle, independence, assembly, and module-container governance.
- External dependency, NuGet package, framework-reference, project-metadata, method-body, and Unity
.asmdef rules.
- Type placement, source-layout conventions, attribute usage, inheritance, interface implementation, composition boundaries, and public API surface snapshots.
- Semantic classification from implemented code facts, selector-backed layers, contextual dependency/allow-only rules, and semantic port/ACL boundaries.
- Coverage contracts for
namespace, project, assembly, dependency_edge, rule_input, and semantic_role inventory.
- Native declared topology with capture/diff/verify, recursive contract-surface exposure, architecture metrics, absolute/baseline-relative budgets, and repository-local external SARIF evidence.
- Project/solution discovery, explicit build-state preflight, opt-in
--ensure-built, condition sets, persistent analysis cache, and bounded parallel scanning.
- Strict gates, audit discovery, migration baselines, structured waiver lifecycle, effective policy inventory, policy consistency, policy-context export, and policy-weakening review.
- Architecture change snapshots/reports, history forensics, dependency graphs/path explanation, Architecture Health, deterministic PR Markdown, Health and legacy architecture-policy badge projections, and public API lifecycle commands.
- Human, normalized JSON, SARIF where applicable, repeatable report sinks, timings, analysis profiles, and CI-oriented coverage artifacts.
- CEL-backed
when predicates at documented closed locations — standard CEL under a safe profile, not an open-ended scripting language.
Optional canonical annotations
Stable ArchLinterNet 0.10.x releases include the separate ArchLinterNet.Annotations package for C# role and context annotations. It compiles internal source definitions into each directly referencing authoring project and adds no annotation runtime assembly or package dependency. Use the matching 0.10.x tool line. The package is not part of v0.10 preview or earlier package sets; see the semantic annotation adoption guide and canonical annotation catalog for the compatibility contract.
ArchLinterNet does not validate runtime dependency-injection behavior, authorization/security correctness, code ownership, arbitrary semantic data flow, or undocumented custom YAML contract families.
Documentation
Public product documentation is published through MkDocs and GitHub Pages:
The public capability references are checked against runtime/schema/CLI inventories by make lint-docs, so a new executable capability cannot silently leave the main documentation matrix stale.
Internal project documentation remains in repository Markdown files such as docs/internal/, openspec/, .github/, and root governance files. It is not part of the published product site.
GitHub Pages is deployed only by the public release workflow. A merge to main refreshes focused quality telemetry and development/dogfood main.N packages, but does not deploy MkDocs. A successfully processed red Sonar quality gate remains visible through the direct Sonar badge/dashboard while Main quality represents successful current-SHA telemetry delivery; scanner, upload, processing, revision, import, or Codecov delivery failures still make that workflow red.
Local documentation workflow
make venv # create Python virtual environment
make docs-serve # preview MkDocs locally
make docs-build # build the static documentation site
make fmt-docs # auto-format markdown documentation
make lint-docs # strict structure + semantic documentation validation
Generated site/ output is a build artifact and should not be committed.
Architecture Health badge
Start with CI integration,
then choose a publication path.
Private checks and reports need no public badge or hosting account. none is
the built-in private default; publication is never enabled automatically.
Render a badge from an existing canonical Health document:
arch-linter-net badge architecture-health \
--input architecture-health.json \
--output architecture-health-badge.json
Health, Gate, explicit ignore debt, rule counts, and colors belong to the CLI.
The badge is not a score, test-coverage percentage, or workflow status. Missing
evidence remains UNASSESSABLE/?, not zero debt.
Public repositories can use static snapshots, including github-raw.
Private or public repositories can also use a
consumer-owned publisher and hosting:
verify the exact source/run attempt/tree/digests, publish only the approved
projection, and check the public response. This path needs neither Relay
bootstrap nor badge-refresh commits to main; its verifier, credentials,
expiry, and operation belong to the consumer. It is not a new CLI transport mode.
Private Relay remains experimental / opt-in; full hosted/lifecycle acceptance
is still pending. It is a separate adopter-owned Worker/Durable Object/OIDC
integration, not a required service or a turnkey readiness claim. See
experimental setup
and the matching distribution/lifecycle guides before choosing it. Core
functionality does not depend on Relay, and experimental status does not waive
security, privacy, integrity, or false-success defects.
This repository's own README uses a public raw snapshot, not Relay.
Its image links to the
canonical publication receipt.
Compare that receipt and the raw payload before diagnosing Shields/Camo cache
lag; an unchanged headline alone does not prove staleness. Static files do not
expire on read, and no hosting choice can recall saved images. See
publication verification.
badge architecture-policy --input architecture-strict.json remains the older,
narrower strict-validation signal. It is not Architecture Health.
Project health and assurance
The Main quality badge tracks successful current-SHA post-merge telemetry delivery. That run requires all three Linux coverage shards, one canonical complete coverage receipt, successful Sonar scanner/upload/processing/revision/import verification, and a successful Codecov upload. A processed Sonar Quality Gate failure remains a warning and direct Sonar branch badge/dashboard signal rather than being misclassified as a failed telemetry refresh. The Architecture Health badge is different: a required PR Architecture Coverage job creates the exact ArchLinterNet payload, and a trusted post-merge publisher releases it only after proving the PR head and squash-merged main commit have the same Git tree. Missing, stale, or mismatched evidence replaces the stable endpoint with an explicit unassessable badge; it never leaves an old healthy payload represented as current. This publication does not rerun the architecture matrix or deploy MkDocs. SonarCloud also analyzes trusted pull requests, decorates the PR, and evaluates the quality gate on new code before merge:
| Quality signal | Source |
|---|
| Build/test | Required pull-request validation runs make acceptance-equivalent unit/E2E/packed-artifact gates before merge |
| Test coverage (line %) | PR CI and post-merge Main Quality Telemetry collect coverage; the merged-main run uploads Cobertura XML to Codecov so the primary coverage badge follows main |
| Architecture Health | Canonical Health, accumulated explicit ignore debt, and effective policy controls from required PR evidence promoted only after exact merged-tree proof; it is not generic CI, a score, or coverage |
| SonarCloud PR quality gate | trusted pull_request runs analyze new code, publish a SonarCloud PR result link, and fail CI when the Sonar quality gate fails |
| SonarCloud main quality signals | Main Quality Telemetry analyzes the merged revision with OpenCover/TRX/Python coverage; successful delivery may coexist with a red direct Sonar Quality Gate badge because the processed gate result is telemetry, while delivery/integrity failures keep Main quality red |
| OpenSSF Scorecard | trusted pull requests produce reviewable SARIF; default-branch and scheduled runs publish the supply-chain score to the public Scorecard API and GitHub code scanning |
| Architecture validation | strict ArchLinterNet self-policy check (architecture/dependencies.arch.yml), including the reviewed public API snapshots under architecture/api/; read-only, never rewrites either |
| Architecture coverage | strict/audit coverage JSON artifacts + Markdown report + sticky PR comment on the required pull-request gate |
See the repository CI reference for how this repository's PR gate, merged-main telemetry, and separate architecture publication fit together.
NuGet and repository links
NuGet packages should expose only public user-facing links:
- project/documentation URL: the GitHub Pages MkDocs site;
- repository URL: this GitHub repository;
- package README: this concise product README;
- license: repository license expression.
NuGet metadata must not point users to internal backlog governance, OpenSpec archives, or maintenance-agent instructions as product documentation.
Security
Report suspected vulnerabilities privately through GitHub Private Vulnerability Reporting. Do not disclose unresolved vulnerabilities in public issues, pull requests, or discussions. See the security policy for supported preview releases, reporting guidance, and disclosure expectations.
License
MIT.
