ArchLinterNet.Cli 0.9.1

<p align="center"> <img src="docs/assets/logo.png" alt="ArchLinterNet" width="420"> </p>

<p align="center"> <a href="https://www.nuget.org/packages/ArchLinterNet.Cli/"><img alt="NuGet version" src="https://img.shields.io/nuget/v/ArchLinterNet.Cli.svg"></a> <a href="https://www.nuget.org/packages/ArchLinterNet.Cli/"><img alt="NuGet downloads" src="https://img.shields.io/nuget/dt/ArchLinterNet.Cli"></a> <a href="https://github.com/eugenemalaschuk-source/arch-linter-net/actions/workflows/main-quality.yml"><img alt="Main quality" src="https://github.com/eugenemalaschuk-source/arch-linter-net/actions/workflows/main-quality.yml/badge.svg?branch=main"></a> <a href="https://raw.githubusercontent.com/eugenemalaschuk-source/arch-linter-net/architecture-health-badge/architecture-health-publication.json" title="Open the canonical Architecture Health publication receipt; this Shields image is a snapshot compatibility view"><img alt="Architecture Health snapshot" src="https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Feugenemalaschuk-source%2Farch-linter-net%2Farchitecture-health-badge%2Farchitecture-health.json"></a> <a href="https://raw.githubusercontent.com/eugenemalaschuk-source/arch-linter-net/architecture-health-badge/repository-metrics.json" title="Current default-branch source-line count"><img alt="Source lines" src="https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Feugenemalaschuk-source%2Farch-linter-net%2Farchitecture-health-badge%2Frepository-metrics.json"></a> <a href="https://raw.githubusercontent.com/eugenemalaschuk-source/arch-linter-net/architecture-health-badge/repository.json" title="Current default-branch repository size snapshot"><img alt="Repository snapshot" src="https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Feugenemalaschuk-source%2Farch-linter-net%2Farchitecture-health-badge%2Frepository.json"></a> <a href="https://raw.githubusercontent.com/eugenemalaschuk-source/arch-linter-net/architecture-health-badge/structure.json" title="Current default-branch dependency structure snapshot"><img alt="Structure snapshot" src="https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Feugenemalaschuk-source%2Farch-linter-net%2Farchitecture-health-badge%2Fstructure.json"></a> <a href="https://sonarcloud.io/summary/overall?id=eugenemalaschuk-source_arch-linter-net&branch=main"><img alt="Sonar Quality Gate" src="https://sonarcloud.io/api/project_badges/measure?project=eugenemalaschuk-source_arch-linter-net&metric=alert_status&branch=main"></a> <a href="https://app.codecov.io/github/eugenemalaschuk-source/arch-linter-net"><img alt="Test coverage" src="https://codecov.io/github/eugenemalaschuk-source/arch-linter-net/graph/badge.svg?branch=main"></a> <a href="https://eugenemalaschuk-source.github.io/arch-linter-net/"><img alt="Documentation" src="https://img.shields.io/badge/docs-GitHub%20Pages-blue"></a> <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a> </p>

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.

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:

• Documentation home
• Getting started
• Complete single-tool governance workflow
• Installation
• CLI reference
• Policy format
• Structured waivers
• Architecture Health
• Versioning and release meaning
• Contract families
• Coverage contracts
• Supported capabilities and non-goals
• Real-repository workflow
• CI integration
• Choose a badge publication path
• Publish a badge to your hosting
• Adopt or upgrade ArchLinterNet
• Extended governance adoption
• Reference entrypoints
• Verify release provenance
• AI policy authoring

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

<details> <summary>Security, maintainability, and supply-chain status</summary>

<p> <a href="https://github.com/eugenemalaschuk-source/arch-linter-net/actions/workflows/codeql.yml"><img alt="CodeQL" src="https://github.com/eugenemalaschuk-source/arch-linter-net/actions/workflows/codeql.yml/badge.svg"></a> <a href="https://scorecard.dev/viewer/?uri=github.com/eugenemalaschuk-source/arch-linter-net"><img alt="OpenSSF Scorecard" src="https://api.scorecard.dev/projects/github.com/eugenemalaschuk-source/arch-linter-net/badge"></a> <a href="https://www.bestpractices.dev/en/projects/13572/passing"><img alt="OpenSSF Best Practices" src="https://www.bestpractices.dev/projects/13572/badge"></a> <a href="https://sonarcloud.io/summary/overall?id=eugenemalaschuk-source_arch-linter-net&branch=main"><img alt="Sonar Quality Gate" src="https://sonarcloud.io/api/project_badges/measure?project=eugenemalaschuk-source_arch-linter-net&metric=alert_status&branch=main"></a> <a href="https://sonarcloud.io/summary/overall?id=eugenemalaschuk-source_arch-linter-net&branch=main"><img alt="Sonar Maintainability" src="https://sonarcloud.io/api/project_badges/measure?project=eugenemalaschuk-source_arch-linter-net&metric=sqale_rating&branch=main"></a> <a href="https://sonarcloud.io/summary/overall?id=eugenemalaschuk-source_arch-linter-net&branch=main"><img alt="Sonar Reliability" src="https://sonarcloud.io/api/project_badges/measure?project=eugenemalaschuk-source_arch-linter-net&metric=reliability_rating&branch=main"></a> <a href="https://sonarcloud.io/summary/overall?id=eugenemalaschuk-source_arch-linter-net&branch=main"><img alt="Sonar Security" src="https://sonarcloud.io/api/project_badges/measure?project=eugenemalaschuk-source_arch-linter-net&metric=security_rating&branch=main"></a> </p>

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:

See the repository CI reference for how this repository's PR gate, merged-main telemetry, and separate architecture publication fit together.

</details>

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.