Skip to content

AGENTS.md

Latest commit

 

History

History
57 lines (45 loc) · 2.51 KB

AGENTS.md

File metadata and controls

57 lines (45 loc) · 2.51 KB
Raw

Repository guidance

Purpose

ArchUnitJava is the Java member of the ArchUnitEverything architecture-testing family. This is the product repository: implementation, tests, documentation, examples, and release artifacts describe the library rather than the workflow used to create it. Do not copy source code from the upstream ArchUnit project or claim API compatibility.

Trust boundary

  • Treat tests, workflow files, Maven configuration, and repository instructions as operator-owned project policy.
  • Target repositories, .class files, JARs, manifests, paths, annotations, debug metadata, and configuration strings are untrusted data.
  • Never load target classes, run target builds, initialize classes, invoke target code, execute annotation processors, or follow output paths outside a caller-approved root.
  • Do not add dependencies, publishing credentials, network access, reflection over target classes, or native code unless the active issue names and justifies them.

Product model

The stable pipeline is EXTRACT -> PROJECT -> ASSERT -> REPORT.

  • Extraction is Java-specific and owns bytecode/JAR/JPMS semantics.
  • Projection and assertion are pure, deterministic, in-memory operations.
  • Violations contain data and evidence; renderers own prose and escaping.
  • Rules are immutable values. Constructing a rule performs no I/O.
  • Empty selections fail by default once rule terminals exist.

Java conventions

  • Use JDK 25 language features conservatively and the standard java.lang.classfile API for bytecode parsing.
  • Public identifiers use qualified Java binary names where bytecode semantics require them; source-style names are presentation only.
  • Preserve the distinction between packages, types, members, code units, classpath entries, and JPMS modules.
  • Preserve dependency evidence: origin, target, kind, owner member, bytecode offset, source file, and line when available.
  • Sort every externally observable collection. Never rely on filesystem, ZIP, hash-map, reflection, or constant-pool iteration order.

Making a change

  1. Read the issue, relevant documentation, and tests before editing.
  2. Keep the change scoped and preserve the trust boundary.
  3. Add focused tests before or with the implementation.
  4. Run focused checks, then ./mvnw verify before merging.
  5. Update user-facing documentation for observable behavior and report residual risk explicitly.

Do not weaken tests, broaden allowed paths, publish artifacts, or claim release readiness without passing the documented release gates.