Add ArchUnitTS architecture tests for hexagonal layering

[cteyton]

Explanation

Introduces executable enforcement of Packmind's hexagonal (ports & adapters) architecture using ArchUnitTS. The new architecture-tests package contains rules that validate import dependencies across the monorepo's domain packages and API layer, ensuring the documented workflow is followed in practice.

The test suite is intentionally separate from the main test suite (npm run test) and runs via a dedicated npm run test:arch command. It scans the entire monorepo's dependency graph (slower) and surfaces pre-existing violations as failures, allowing the team to track and gradually refactor architecture debt without blocking the main CI pipeline.

Key additions:

• packages/architecture-tests/ — New package with three rule suites:
  • Layering rules (layering.arch.spec.ts) — Enforce the request flow: controller → service → adapter → use case → application service → repository interface → repository implementation
  • Domain purity rules (domain-purity.arch.spec.ts) — Prevent domain layer from importing application or infrastructure
  • Cross-domain isolation rules (cross-domain.arch.spec.ts) — Ensure domains collaborate only through @packmind/types ports, never by importing each other's source
• scripts/build-arch-tsconfig.mjs — Generates a self-contained tsconfig.arch.json (git-ignored) with inlined path aliases, required because ArchUnitTS does not resolve extends in tsconfig
• .github/workflows/architecture.yml — Non-blocking CI job that reports violations without failing the workflow
• Updated eslint.config.mjs to tolerate jest.*.config.ts naming variants
• Updated .gitignore to exclude the generated tsconfig.arch.json

Current status: 8 of 15 rules pass; 7 fail with real, documented violations (see README "Known violations" section). Failures are intentionally left visible to track architecture debt.

Type of Change

• New feature
• Documentation

Affected Components

• All domain packages (accounts, spaces, standards, recipes, skills, git, deployments, coding-agent)
• API app (NestJS controllers)
• CI/CD (new non-blocking architecture check)

Testing

• Architecture tests are self-contained and run via npm run test:arch
• The test suite uses ArchUnitTS to analyze the real TypeScript dependency graph (aliases resolved via tsconfig)
• Violations point to exact offending files with clickable paths
• CI job is non-blocking (continue-on-error: true) so pre-existing violations don't block merges
• No unit/integration tests needed — the architecture rules themselves are the tests

TODO List

• CHANGELOG Updated (implicit in new feature)
• Documentation Updated (comprehensive README in packages/architecture-tests/)

Reviewer Notes

The 7 failing rules document real architecture debt (e.g., coding-agent importing concrete repositories, git use cases importing GithubTokenResolverFactory, domain interfaces importing concrete application classes). These are intentionally left failing to make the violations visible and trackable. Each failure references the specific standard it guards (e.g., standard-use-case-architecture-patterns, standard-port-adapter-cross-domain-integration).

The generated tsconfig.arch.json is git-ignored and rebuilt by the arch Nx target before each run, ensuring path aliases always match the current edition.

https://claude.ai/code/session_01KaYguqCn23xyuPLqkj4UtQ

[greptile-apps]

Greptile Summary

This PR introduces executable hexagonal architecture enforcement via ArchUnitTS (packages/architecture-tests), while simultaneously fixing several real cross-domain violations it would otherwise flag — most notably removing direct ClaudePluginDeployer imports from the deployments domain and eliminating PackageRepository's cross-domain ORM reads (RecipeSchema, StandardSchema, etc.).

• New architecture-tests package: three spec suites (layering, domain purity, cross-domain isolation) plus a boundaries suite, backed by a build-arch-tsconfig.mjs generator and a dedicated arch Nx target. 8/15 rules pass; 7 failures are intentionally left visible to track architecture debt.
• RenderPackageAsPluginUseCase decoupled: direct import of @packmind/coding-agent's ClaudePluginDeployer replaced by ICodingAgentPort.renderPackageAsClaudePlugin; the new port method is added to @packmind/types and implemented in CodingAgentRepositories.
• PackageRepository cleaned up: cross-domain entity hydration moved from the infra repository into PackageService via lazily-wired cross-domain ports (setArtefactPorts), called by DeploymentsAdapter.initialize; IPackageRepository gains a single findBySlugsAndSpaceIds replacing the two previous WithArtefacts variants.

Confidence Score: 4/5

Safe to merge after addressing the pre-push hook and the missing continue-on-error in build.yml; the core architecture enforcement and cross-domain refactoring are solid.

The pre-push hook runs arch tests as a hard blocking step while 7/15 rules are intentionally failing, which will abort every developer push until all violations are resolved. The reusable build.yml also adds the architecture-tests job without continue-on-error: true, meaning the entire build workflow will fail on every run while the known violations remain. Both issues directly break day-to-day developer workflow. The rest of the PR — the ArchUnitTS test suites, the ICodingAgentDeployer type migration, PackageRepository cleanup, and RenderPackageAsPluginUseCase decoupling — is well-executed.

.husky/pre-push and .github/workflows/build.yml — both introduce blocking behavior for currently-failing architecture tests.

Important Files Changed

Filename	Overview
.husky/pre-push	Architecture tests added as a blocking pre-push step; will abort every push while 7/15 rules are intentionally failing, preventing all developer pushes.
.github/workflows/build.yml	New architecture-tests job added to the reusable build workflow without continue-on-error: true; will make the workflow fail while 7 known violations remain.
.github/workflows/architecture.yml	New workflow: correctly uses continue-on-error: true at the job level to remain non-blocking while surfacing current violations on every PR.
packages/architecture-tests/src/architecture.ts	New file: defines shared constants (ARCH_TSCONFIG, DOMAIN_PACKAGES, LAYER_GLOBS, etc.) for ArchUnitTS test suites; filesystem-driven domain discovery is clean and avoids manual lists.
packages/architecture-tests/src/layering.arch.spec.ts	New file: 11 layering rules enforcing the hexagonal stack; rules are correctly scoped and commented with the standards they guard.
packages/architecture-tests/src/cross-domain.arch.spec.ts	New file: per-domain cross-import isolation rules generated via it.each; correctly excludes the subject domain from its own target regex.
packages/architecture-tests/src/domain-purity.arch.spec.ts	New file: two rules preventing domain/ from reaching up into application/ or infra/; known failures are acknowledged inline.
packages/architecture-tests/src/boundaries.arch.spec.ts	New file: three reverse-dependency rules ensuring @packmind/types and base packages never import domain packages and no domain imports the API app.
packages/architecture-tests/project.json	New file: Nx project with a dedicated arch target; comprehensively-specified inputs ensure cache invalidation when any source file changes.
scripts/build-arch-tsconfig.mjs	New file: generates self-contained tsconfig.arch.json with inlined path aliases; fails loudly if the effective config has no paths (preventing false-green runs).
packages/deployments/src/application/services/PackageService.ts	Cross-domain artefact hydration moved from the infra repository into the application service via injected ports; lazy setArtefactPorts() wiring is called by DeploymentsAdapter.initialize() before use.
packages/deployments/src/infra/repositories/PackageRepository.ts	Removed cross-domain ORM reads (RecipeSchema, StandardSchema, SkillSchema, SpaceSchema); repository now only reads its own tables and returns Package[] with artefact ID lists.
packages/deployments/src/application/useCases/renderPackageAsPlugin/RenderPackageAsPluginUseCase.ts	Removed direct import of ClaudePluginDeployer from @packmind/coding-agent; now delegates to ICodingAgentPort.renderPackageAsClaudePlugin, properly isolating the domains.
packages/types/src/coding-agent/ICodingAgentDeployer.ts	New file: ICodingAgentDeployer interface and related types migrated from coding-agent's domain layer to @packmind/types, making the port accessible without importing coding-agent source.
packages/coding-agent/src/infra/repositories/CodingAgentRepositories.ts	Implements the new renderPackageAsClaudePlugin port method; correct placement in infra as a concrete implementation delegating to ClaudePluginDeployer.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    subgraph CI["CI Workflows"]
        AY["architecture.yml - continue-on-error true"]
        BY["build.yml arch job - missing continue-on-error"]
        HP[".husky/pre-push - blocking step"]
    end

    subgraph ArchTests["packages/architecture-tests"]
        AT["arch Nx target"]
        L["layering.arch.spec.ts"]
        DP["domain-purity.arch.spec.ts"]
        CD["cross-domain.arch.spec.ts"]
        B["boundaries.arch.spec.ts"]
        AT --> L
        AT --> DP
        AT --> CD
        AT --> B
    end

    subgraph CrossDomainFix["Cross-Domain Fix"]
        UC["RenderPackageAsPluginUseCase"]
        PORT["ICodingAgentPort in types"]
        IMPL["CodingAgentRepositories.renderPackageAsClaudePlugin"]
        UC -->|"delegates via port"| PORT
        PORT -.->|"implemented by"| IMPL
    end

    subgraph PackageSvcFix["PackageRepository Cleanup"]
        PS["PackageService.enrichWithArtefacts"]
        PR["PackageRepository.findBySlugsAndSpaceIds returns IDs only"]
        PS --> PR
        PS --> RP["IRecipesPort / IStandardsPort / ISkillsPort / ISpacesPort"]
    end

    CI --> AT

Loading

_{Reviews (11): Last reviewed commit: "👷 ci(arch): use pnpm in architecture-te..." | Re-trigger Greptile}

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
3 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.5% Duplication on New Code

See analysis details on SonarQube Cloud