bausteinsicht-archunit

Prototype of Variant C from the Bausteinsicht ArchUnit RFE (docToolchain/Bausteinsicht#562): a Java adapter that lets a Bausteinsicht architecture model govern real Java code — in both directions — with no intermediate diagram.

Scope: happy-path only, enough to pin down the two contracts and prove the round-trip. No error handling / edge cases. codeMapping is a proposed Bausteinsicht field; the real Bausteinsicht changes land later.

The two contracts

Direction	Contract	This prototype
Forward	the Bausteinsicht JSONC model (with codeMapping)	BausteinsichtRules.fromModel(model) builds ArchUnit rules and checks the code
Reverse	a minimal, language-neutral codegraph JSON	CodeGraphExporter.export(classes, base) dumps the real package graph for Bausteinsicht to ingest as asIs

Projection stays in Bausteinsicht, not here: the reverse exporter emits the raw package graph and does not read the model. Bausteinsicht owns codeMapping and collapses that graph onto model elements.

Modules

bausteinsicht-archunit/
├── example-app/   – tiny analysis target: com.acme.backend.{api → svc → db}
└── adapter/       – the library + the integration test
    ├── ModelLoader           – JSONC (comments + trailing commas) → model
    ├── BausteinsichtRules     – forward: model → ArchUnit rules
    ├── CodeGraphExporter      – reverse: JavaClasses → codegraph JSON
    └── VariantCIT             – happy-path integration test (both directions)

Build & test

mvn -ntp verify

Runs the integration test (VariantCIT) via Failsafe:

• forward — the example app follows api → svc → db, matching the model, so the generated rules pass;
• reverse — the exported codegraph contains the api → svc and svc → db package edges (and not api → db).

Requires JDK 17+ (built with maven.compiler.release=17).

Forward contract example (adapter/src/test/resources/architecture.jsonc)

{
  "model": {
    "backend.api": { "codeMapping": { "packages": ["com.acme.backend.api"] } },
    "backend.svc": { "codeMapping": { "packages": ["com.acme.backend.svc"] } },
    "backend.db":  { "codeMapping": { "packages": ["com.acme.backend.db"] } }
  },
  "relationships": [
    { "from": "backend.api", "to": "backend.svc" },
    { "from": "backend.svc", "to": "backend.db" }
  ]
}

Reverse contract example (codegraph JSON)

{
  "schemaVersion": "1.0",
  "kind": "bausteinsicht.codegraph",
  "language": "java",
  "nodes": [ { "id": "com.acme.backend.api", "kind": "package" } ],
  "edges": [ { "from": "com.acme.backend.api", "to": "com.acme.backend.svc",
               "weight": 1, "examples": ["OrderController -> OrderService"] } ]
}

License

TBD — to be aligned with the docToolchain organisation's policy before first release.