FAQ · HexPatrol

Question 1

How does HexPatrol enforce ports and adapters at the import-graph level?

Accepted Answer

HexPatrol parses the import graph for every commit, classifies each import by its source and target layer (domain, application, infrastructure, UI), then applies HexPatrol’s own `LayerBoundaryPolicy` to every edge. An edge that violates the dependency rule is reported as a layer-boundary violation on the offending line, with a suggested patch that flips the call site behind a port. Adapters themselves live in the infrastructure layer and implement ports declared by the application — the scanner checks both halves.

Question 2

How does HexPatrol decide where one bounded context ends and another begins?

Accepted Answer

HexPatrol takes the same starting point a domain-driven design team would: the import graph. Cohesive clusters of imports — where one team consistently owns a vocabulary and a set of types — become candidate bounded contexts. The scanner then cross-checks against the ubiquitous-language signals it can find in code, tests, and comments, and surfaces suggested context boundaries on the context map. Translation layers between contexts are also called out — every cross-context edge is a candidate anti-corruption layer.

Question 3

How does HexPatrol use the repository pattern without leaking Prisma?

Accepted Answer

HexPatrol defines a `RepositoryPort` per aggregate (e.g. `ScanRepositoryPort`) in the application layer, and the Postgres adapter implements it in the infrastructure layer. The domain and use-cases import the port interface only — they have no `import { prisma }` lines, no PrismaClient types, and no SQL fragments. Tests use an in-memory adapter that satisfies the same port. If the storage layer changes, the only files that move are inside `infrastructure/`; everything above the port compiles unchanged.

Question 4

How does HexPatrol detect when the ubiquitous language has drifted?

Accepted Answer

HexPatrol looks for the same vocabulary in three places: the domain code (entity names, methods, tests), the README and ADRs in that bounded context, and the surrounding PR titles and code-review comments that touched the context. When the same concept is named in three different ways across those places, the scanner tags that context as showing "language drift" and surfaces the most common cluster of synonyms so a human can decide whether to consolidate them or split the context.

Question 5

Is this lock-in versus standard linters?

Accepted Answer

No. Rules are expressed in plain JSON (`hex.config.json`) sitting in the repo — no proprietary DSL, no closed binary that only HexPatrol can read. The CI step is one extra process in the pipeline you already run, and nothing proprietary ships in the build: HexPatrol emits a patch but does not modify source itself. Disable a rule, replace it with your own check, or run HexPatrol on a subset of the codebase while you evaluate — the same escape hatches you would expect from eslint or any other portable linter.

Question 6

Onboarding friction for new engineers?

Accepted Answer

New engineers see the rule that fires, the suggested patch, and a one-paragraph "why this rule exists" — the same UX as ESLint on first encounter. The scanner is the teacher: it explains the violation at the line, links to the relevant bounded-context page, and proposes the smallest patch that satisfies the rule. PR review picks up the rest. There is no separate mental model to learn — hexagonal enforcement just shows up where the import was wrong, the way a missing-semicolon error would.

Question 7

What does "architecture enforcement" actually mean in a CI pipeline?

Accepted Answer

Architecture enforcement means continuously, automatically checking that the code and dependencies still respect the rules the team agreed on. In HexPatrol the rules are derived from the hexagonal model — every bounded context has a clear boundary, every layer has a clear dependency direction, and every port has a clear adapter. The checks run on each commit, fail loudly when something breaks, and ship an auto-correction patch the moment a violation is detected.

Question 8

What does this cost on CI / dev-loop latency?

Accepted Answer

For repos under a few thousand files, the scan runs in parallel across CPU cores, completes in well under thirty seconds, and caches results by commit so unchanged files are skipped on subsequent runs. The dev-loop cost is a single local CLI invocation (`hexpatrol scan`) that runs the same engine — no remote call required. Compare that with the cost of catching the same violations in code review: a round-trip comment, a re-review, a merge delay. Enforcing it once on CI replaces that loop for every PR from now on.

Question 9

What is hexagonal architecture, and how is HexPatrol itself an example of it?

Accepted Answer

Hexagonal architecture (also called ports and adapters) puts the application at the centre and isolates every external system behind a swappable adapter. The application declares the ports it needs — interfaces for the outer world — and adapters implement them. HexPatrol itself is hexagonal: the scanning engine sits at the centre with ports for source-code fetching, finding storage, and PR creation; each port has concrete adapters per provider. Swapping GitHub for a generic Git host, for example, is a new adapter plus a wiring line in the composition root — no domain or application code changes.

Question 10

What is a "port" in HexPatrol — and who owns the contract?

Accepted Answer

A port is an interface declared by the application that an external system must implement to be usable. The application owns the contract, not the infrastructure: the domain and use-cases depend on the port interface, and adapters depend on the same interface. In HexPatrol the ports are usually named `<…>Port` and live in the application layer. Concrete adapters — a Postgres adapter, an in-memory test adapter, a remote-service adapter — implement them. Wiring happens in the composition root, never in the domain.

Question 11

Will this fire false positives and block legitimate work?

Accepted Answer

Every rule ships disabled by default — the team enables only the boundaries it cares about, and each enabled rule carries a per-edge rationale (why this import is forbidden here). When a violation does fire, the report cites the offending import line, the rule that fired, and a suggested patch; severity is graded (error blocks the build, warn is reported, info is informational). Suppression is opt-in per rule or per path (`hex.config.json` `ignore` lists) and the same rule set is what CI runs — there is no "production-only" config that surprises the dev.

Question 12

Why not just enforce in code review?

Accepted Answer

Code review is human-time — expensive, inconsistent, and scales linearly with PR count. Reviewers cannot hold the whole import graph in their head, so the architectural drift that matters most (a domain file quietly importing an adapter, a bounded context leaking into another) slips through anyway. Architecture enforcement is automated, deterministic, runs on every commit, and produces a patch — review happens *after* the rule is satisfied, so reviewers spend their attention on the parts humans are uniquely good at (naming, semantics, edge cases).

Question 13

Why is the dependency rule "inward only" so important?

Accepted Answer

The dependency rule states that source-code dependencies may point inward (toward the domain) but never outward (toward infrastructure, frameworks, or UI). The inner layers therefore know nothing about the outer layers, which means the domain code compiles and unit-tests even if every adapter is deleted. HexPatrol treats any outward dependency as a violation: when a file under `domain/` imports anything from `infrastructure/`, the build fails and a patch is emitted that moves the call behind a port instead.