Static analysis and the pipeline
Summary. The architecture is held by analyzers, not by review comments. Three of them share one set of rule ids, each where it is exact: the kit's own checker reads paths, text and the glossary; the ESLint plugin reads the syntax tree; dependency-cruiser reads the resolved import graph. knip finds dead code, and the TypeScript compiler in strict mode closes the set. A generated project carries two TypeScript versions side by side, because the native compiler (7) has no JavaScript API yet and the lint tools need one. The same gates run on GitHub Actions and on GitLab CI from the same npm scripts. This page compares the tools, says what was verified and what was not, and when a lighter setup is enough.
Why several analyzers
Section titled “Why several analyzers”A single rule such as layer/domain-purity (see the rule table of the
architecture reference) can be broken in ways that different tools see.
Each case below was run through the three analyzers on a small project:
- a direct
import { z } from 'zod'in a value object: all three report it; - the same text in a comment or a string: a plain text search would report it; the checker's lexer skips comments and strings, and the syntax tree has no import there, so none does, rightly;
- an import through a
tsconfigpath other than the alias of the project (#billing-infra/invoice-row, leading toinfrastructure/): the checker and the ESLint plugin read the specifier as written and report "the package#billing-infra"; dependency-cruiser resolves it like the compiler and names the real file,infrastructure/invoice-row.ts; - a type of
zodre-exported byshared-kernel/index.ts, which the domain may import: none reports it. The checker does not resolve re-exports, the ESLint plugin sees an allowed import, and the generated dependency-cruiser rules judge each edge alone. What no rule constrains is reviewed by hand (see Limits).
So the cheapest tool runs most often and the most exact one has the last word.
What a finding looks like, and what to write instead. The checker answers the direct import with the rule, the place and the fix:
// Instead of: domain/value-objects/email.vo.ts validating with a libraryimport { ValueObject } from '@ddd-ts-kit/kernel';import { z } from 'zod';
export class Email extends ValueObject<{ readonly value: string }> { private constructor(props: { readonly value: string }) { super(props); }
static create(value: string): Email { return new Email({ value: z.string().email().parse(value) }); }}$ npx ddd-ts-kit check-file src/contexts/billing/domain/value-objects/email.vo.tssrc/contexts/billing/domain/value-objects/email.vo.ts:2 error layer/domain-purity The domain imports the package "zod". fix: Remove the import: express the need as plain TypeScript or as a port in application/ports, and keep decorators and schemas of "zod" in infrastructure or presentation.
1 error, 0 warnings, 0 suppressions in 1 file.The shape of a request is validated at the edge, by the schema of its route; the rule of the business stays in plain TypeScript, with a refusal named after what it refuses:
import { DomainRefusal, ValueObject } from '@ddd-ts-kit/kernel';
export const IdentityCodes = { InvalidEmail: 'INVALID_EMAIL' } as const;
// domain/errors/invalid-email.error.tsexport class InvalidEmail extends DomainRefusal { readonly code = IdentityCodes.InvalidEmail;
static forAddress(value: string) { return InvalidEmail.refusal(`"${value}" is not an email address.`, { value }); }}
// domain/value-objects/email.vo.ts: the domain imports only the kernelexport class Email extends ValueObject<{ readonly value: string }> { private constructor(props: { readonly value: string }) { super(props); }
static create(value: string): Email { const address = value.trim().toLowerCase();
if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(address)) { throw InvalidEmail.forAddress(value); }
return new Email({ value: address }); }
get value(): string { return this.props.value; }}Comparison
Section titled “Comparison”Versions and licences were read from npm on 2026-10-10.
ddd-ts-kit check |
@ddd-ts-kit/eslint-plugin |
dependency-cruiser | knip | TypeScript (strict) | |
|---|---|---|---|---|---|
| Reads | paths, text through a small lexer, CONTEXT.md, the config |
the syntax tree of one file, types when asked | the resolved module graph | the project's entry points and exports | the whole program |
| Authority for | the tree, names, the glossary, the config, required specs and builders, the generated barrel, unique consumer and job names | code rules: layers, context imports, purity, clean code, aggregate and handler shape, ports, declarations | the same boundaries through barrels and re-exports, cycles, orphans, undeclared dependencies | unused files, exports, types, dependencies | types |
| Dependencies | none | ESLint 9 or 10, typescript-eslint, @stylistic/eslint-plugin |
dependency-cruiser 18.5.0 (MIT), a TypeScript parser | knip 6.41.0 (ISC) | the compiler |
| Runs | after each file write (editor hook), on staged files, in CI | on staged files, in CI | in CI | in CI | pre-push, in CI |
| Cost on the sample project of the pipeline README (three contexts, 87 files) | 0.3 s | 4.5 s with types | 0.8 s | 0.6 s | 0.4 s with the native compiler |
| Blind spots | no compiler: barrels and re-exports not resolved, arrow functions not judged for some rules, heuristics on comments | one file at a time: nothing about the project as a whole | says nothing about what a file does, only what it imports | needs correct entry points; discovered files must be declared as entries | does not know the architecture |
Other tools exist for parts of this job (import-boundary ESLint plugins, monorepo boundary
rules, other dead-code finders). None was evaluated for this page; the module boundary rule of Nx
was tried beside the kit in Composing the kit with other tools.
The kit's configuration for
dependency-cruiser, .dependency-cruiser.cjs, is generated from ddd-ts-kit.config.json,
which is what makes it follow the context map without hand editing:
ddd-ts-kit depcruise-config --write rewrites it (generate context does too), and the
generated npm run depcruise starts with depcruise-config --check, which fails on a stale
file.
ddd-ts-kit rules lists every rule id with its default severity. Most code rules exist in
both the checker (a fast approximation on text) and the ESLint plugin (the exact one). Thirteen
are held by the ESLint plugin only, and the listing says so: domain/aggregate-encapsulation,
domain/value-object-immutability, domain/no-generic-error, errors/through-factory,
errors/constructor-not-public, errors/factory-name, clean/no-magic-number,
application/handler-shape, application/command-query-separation,
presentation/controller-shape, presentation/controller-delegates,
presentation/shared-cache-varies, presentation/guard-at-the-edge. One, clean/formatted, is
held by neither: the formatter of the project, Biome, lays out every file, and the listing says
"checked by Biome":
$ npx ddd-ts-kit rules...domain/aggregate-encapsulation error An aggregate or entity has a private or protected constructor, no public mutable property and no setter. (checked by @ddd-ts-kit/eslint-plugin)...clean/formatted error Every TypeScript, JavaScript and JSON file is laid out by the formatter of the project, Biome, at a line width of 120: the format check reports nothing to change. (checked by Biome)The ESLint side of a project is one function, which reads ddd-ts-kit.config.json next to it:
// eslint.config.ts (init writes the same as eslint.config.mjs)import { dddTsKit } from '@ddd-ts-kit/eslint-plugin';
export default dddTsKit({ tsconfigRootDir: import.meta.dirname });What every project gets, tool by tool, is on the quality baseline page.
Selection criteria
Section titled “Selection criteria”- Feedback time. A rule that answers in under a second can run at every write. One that needs types cannot. Keep both, in that order.
- Exactness. When two tools disagree on a code rule, the syntax tree wins: the ESLint plugin README says the checker is then the one to fix.
- What must be judged project-wide. A missing spec, a stale barrel, a name absent from the glossary or a cycle in the context map are not facts of one file.
- Cost of a false positive. A heuristic rule (noise comments, commented-out code) defaults
to a warning; structural rules default to errors. The
lintandci:lintscripts fail on both (ddd-ts-kit lint): a warning says what kind of finding it is, not that it may stay.
Put together, a generated project runs each analyzer at the moment its cost allows:
The hooks of the laptop are in the lefthook.yml that init writes. Its lefthook: line makes
the hook run the lefthook of the checkout it fires in: the hooks of a repository are shared by
all its worktrees, and without that line they would run the lefthook of whichever checkout
installed them last, or skip every check once that checkout is gone. A worktree without its
dependencies now fails the commit loudly; npx ddd-ts-kit doctor says when the line or the
installed hook is missing. The file sets output: [failure]: a commit that passes prints one line, and a job that
fails prints its findings.
lefthook: node_modules/.bin/lefthook
output: - failure
pre-commit: parallel: true jobs: - name: eslint glob: '*.{ts,mts,cts,js,mjs,cjs}' run: npx --no -- eslint --no-warn-ignored {staged_files} - name: format glob: '*.{ts,mts,cts,js,mjs,cjs,json,jsonc}' run: npx --no -- biome format --no-errors-on-unmatched {staged_files} - name: architecture glob: 'src/**/*.{ts,mts,cts}' run: npx --no -- ddd-ts-kit check {staged_files} - name: behaviour pages glob: - '**/*.spec.ts' - 'src/**/*.{ts,mts,cts}' - 'ddd-ts-kit.config.json' run: 'if [ -f .ddd-ts-kit/worker.json ]; then echo "behaviour pages: left to the trunk, as every shared file of a worker."; else npx --no -- ddd-ts-kit docs --behaviour && git add docs/behaviour; fi' - name: commit size run: npx --no -- ddd-ts-kit check --commit-size --staged
pre-push: jobs: - name: typecheck run: npm run ci:typecheck - name: unit tests # The contexts the branch reaches and the ones downstream of them, as on a pull request; everything when git # cannot tell (no origin/HEAD: `git remote set-head origin --auto`). The pipeline runs everything on the trunk. run: npx --no -- ddd-ts-kit affected --base origin/HEAD --run ci:test:unit - name: merges run: npx --no -- ddd-ts-kit verify-merge --warn
commit-msg: jobs: - name: conventional commit run: npx --no -- commitlint --edit {1}Before a push the unit specs run as on a pull request: ddd-ts-kit affected --run sets
DDD_TS_KIT_AFFECTED to the contexts the branch reaches since origin/HEAD and the ones
downstream of them, runs nothing when only documents changed, and everything when a shared
path changed or git cannot tell. A push no longer runs every spec of a project that grows; the
pipeline does, on the trunk and every night. Outside a pipeline the test runner takes half of
the cores (Sandboxing coding agents).
The ESLint job before a commit has no --max-warnings: it shows a warning and lets the commit
through, and npm run lint, verify and the pipeline fail on it. How a project made by an
earlier version takes the limit, fixing or recording the warnings it already has:
Quality baseline.
TypeScript 6 and 7 side by side
Section titled “TypeScript 6 and 7 side by side”TypeScript 7 is the native compiler. It compiles and type-checks much faster, and as released it ships no JavaScript API. Tools that load the compiler as a library cannot run on it.
What was found on 2026-10-10:
typescripton npm is 7.0.2;typescript-eslint8.71.1 declares the peer rangetypescript >=4.8.4 <6.1.0, so it does not accept TypeScript 7;- articles on the 7.0 release report that a new programmatic API is expected in a later 7.x release. Whether and when typescript-eslint will support it could not be verified from an official statement of that project.
The kit's answer, as its READMEs state: a generated project installs both. typescript 6
serves the tools that read sources through the compiler API (ESLint with types,
dependency-cruiser), and @typescript/native, an npm alias of typescript 7, compiles and
type-checks, run by ddd-ts-kit tsc because both packages declare a tsc binary and npx tsc
would pick one of them. ddd-ts-kit tsc finds the native one wherever the package manager put
it, in the project or hoisted to the root of a workspace, and passes its arguments on.
In the package.json of a generated project:
{ "scripts": { "typecheck": "ddd-ts-kit tsc -p tsconfig.json --noEmit", "build": "ddd-ts-kit tsc -p tsconfig.build.json && ddd-ts-kit build-aliases" }, "devDependencies": { "@typescript/native": "npm:typescript@~7.0.2", "typescript": "~6.0.3", "typescript-eslint": "^8.71.1" }}With typescript 7 alone, ESLint with types does not start, and the
dependency-cruiser configuration falls back to @swc/core when it is installed (it then
follows type-only imports without telling them apart) and fails loudly otherwise.
The cost is two compilers to keep compatible: a syntax accepted by 7 and not by 6 would
type-check and then fail to lint. Renovate or Dependabot will propose bumping typescript
itself to 7; refuse it until the lint tools accept it.
GitHub Actions and GitLab CI
Section titled “GitHub Actions and GitLab CI”The rule of the pipeline directory: CI logic lives in npm scripts, and the two platform files
only orchestrate. Every gate therefore runs on a laptop with the same command. The same gate, in
the two files init writes:
# .github/workflows/ci.yml: the steps of the Architecture job- name: Architecture rules run: npm run ci:arch:check -- --format github- name: Dependency graph run: npm run ci:arch:graph# .gitlab-ci.yml: the architecture jobarchitecture: extends: .node stage: test needs: [install] script: - mkdir -p reports - npm run --silent ci:arch:check -- --format gitlab > reports/gl-code-quality-arch.json - npm run ci:arch:graphand on a laptop, npm run ci:arch, which runs both.
| Piece | GitHub Actions | GitLab CI |
|---|---|---|
| Triggers | pushes to the default branch and pull requests | merge requests and the default branch |
| Runner | ubuntu-26.04, pinned: a new image of GitHub reaches the project when the team changes the label, not when ubuntu-latest moves |
the image each job names (node:24-bookworm-slim by default) |
| Node | the newest patch of the release line (check-latest of setup-node), not the older one the runner image may hold: a security release of Node reaches the next run |
the image tag, which follows the newest patch of its release line |
| Redundant runs | cancelled by concurrency groups | cancelled by interruptible jobs |
| Gates | the same ci:* scripts |
the same ci:* scripts |
| Lint and architecture findings | annotations on the pull request (check --format github) |
Code Quality reports (check --format gitlab writes the report directly; ESLint through its GitLab formatter) |
| A lint warning | fails the lint job (ci:lint runs ddd-ts-kit lint) |
fails the lint job, and is in the Code Quality report |
| The reason of a rule, for the reviewer | check --format github --explain: each annotation ends with it |
check --format gitlab --explain: each issue ends with it, the fingerprints unchanged |
| Test reports | the Vitest reporter for Actions, coverage as an artifact | JUnit and Cobertura reports in the merge request |
| Secrets scan | gitleaks | gitleaks |
| Image build without push | the Docker build action | BuildKit rootless |
| Title check | commitlint on the pull request title | commitlint on the merge request title |
| What makes it binding | one gate job as the required check |
"pipelines must succeed" |
| Dependency updates | Renovate or Dependabot | Renovate |
The pipelines init writes use free tools only. What depends on a plan, or spends API tokens,
is opt-in (init --ci-extras, ci.extras in the config): CodeQL and dependency review, free on
public GitHub repositories and paid on private ones; GitLab's SAST, Secret Detection (findings in
the merge request on Ultimate only) and Dependency Scanning (Ultimate); and two jobs that run
Claude Code on both platforms, claude-review (a review of each pull or merge request, posted as
a comment that neither approves nor blocks) and claude-triage (a three-line triage of a failed
run, read-only, on the job summary and the request); and, on GitHub only, intent-to-spec (the
story skill run headless on each intent a merge accepts, its specification opened as a pull
request). None is required by the gate job: a person still approves. On both platforms the two checks that block on every plan are npm audit
and gitleaks. The table of every tool, its class, its cost and the vendors' pages it was read
from is in pipeline/README.md.
Selection between the two is rarely a free choice: it follows where the code is hosted. The point of the design is that the choice costs nothing in the gates themselves.
What this kit supports and verified
Section titled “What this kit supports and verified”From pipeline/README.md, the
CLI README and the
ESLint plugin README:
- Checker. No runtime dependency. Each violation has a rule id, a severity, a location and
a
fixsentence;explain <rule-id>gives the reason with a bad and a good example, andcheck --explainthe reason of each rule a run reports, once. Output formats for people, JSON, GitHub annotations and GitLab Code Quality. A generation test produces every kind for every stack and requires zero violation, so generator and checker cannot disagree. - ESLint plugin. Flat config only, ESLint 9 and 10. A preset function returns a complete configuration with typescript-eslint strict and type-checked rules; standard rules are enabled where they fully cover a convention, and ten strict rules are adjusted, each for a stated reason. Run on a generated project clean and with one deliberate violation per rule.
- dependency-cruiser. Configuration derived from the project config; run with version 18
with the TypeScript 6 parser and with
@swc/core, every rule reporting its deliberate violation. - knip. Unused file, export, type and dependency reported on the sample project.
- Hooks. lefthook: ESLint, the Biome format check and the checker on staged files before a
commit, the pages of what the tests state regenerated and added when a spec, a source under
src/orddd-ts-kit.config.jsonis staged (left to the trunk in the worktree of a worker), with the advisorycheck --commit-size --staged; type check and unit tests before a push; commitlint on the message. - Coverage thresholds per layer, highest for
domain/, lowest forinfrastructure/, read from the config file, applied to each context, enforced byverifyand by the pipeline. - Drift gates. The context map, the generated parts of each
CONTEXT.md, the barrels (declarations/barrel-current),.dependency-cruiser.cjs, the OpenAPI document, the AsyncAPI document and the event catalog are regenerated and compared.
Not executed, by the pipeline README's own account: the GitHub workflows were parsed and
checked with actionlint, not run on GitHub; the GitLab file was parsed and its stages resolved
by a script, glab ci lint was not run, and it was not executed on GitLab; branch protection
and merge request settings were written from the API documentation.
Mutation testing runs every night. The mutation job of the pipeline runs
npm run test:mutation on the default branch when the schedule fires: Stryker 10.1.1 with the
runner of the project, Vitest or Jest, on the domain and application layers of every context, its configuration read
from the kit (governedMutation(), held by test/mutation-governed: the texts of refusals and the
static mutants left out), then ddd-ts-kit mutation, which holds each context to the mutation
floor of ddd-ts-kit.config.json, the ignored mutants shown beside each score. Not a gate of a pull
request: five minutes for the example are too long for the loop of a change. A pull request gets
the mutation-changed job instead, a reading: Stryker reuses the report of the last night for what
the change leaves alone, about a minute when the change stays in the domain, the use cases and the specs, and runs everything again, about five, when it touches code it does not diff (a route, an adapter, a fake, a builder, the platform, a dependency), the common case of a feature, and ddd-ts-kit mutation --changed <base>
lists the survivors of the files the change touched. The pipeline README holds the measures that
decided it (2026-10-24).
Limits and when not to use it
Section titled “Limits and when not to use it”- The checker is a text reader. Its README lists what it misses: re-exports and barrels,
.tsx, arrow functions for the stepdown and size rules, aliased imports for several rules, a schema name in raw SQL, a cross-context transaction. It is the fast net, not the proof. - The ESLint plugin judges one file. It cannot know that a spec is missing or that two consumers share a name.
- Nothing constrains what
shared-kernel/,platform/andmain.tsimport in the checker. Review those by hand. - Analyzers check shape, not design. An anemic aggregate with private setters renamed as
methods passes every rule. The
architecture-revieweragent and human review exist for that. - A fresh scaffold can be reported: a port or a fake generated before anything uses it is an unused file for knip and an orphan for dependency-cruiser, per the pipeline README. Generate it with the use case that needs it.
- Typed lint is the slowest static gate (seconds, not milliseconds). Without types the preset is faster and loses the rules that read types.
- When a lighter setup is enough: a prototype or a script with no bounded context gains little from the structural rules. The checker has a mode that runs only the clean code rules on any directory, without a project or a config.
- Relaxing a rule is a recorded decision, not a local edit: see
governance/recorded-deviation.
Recommendation by situation
Section titled “Recommendation by situation”| Situation | Choice |
|---|---|
A project generated by init |
keep everything as generated; mark the single gate job as required |
| Adopting the kit in an existing codebase | start with the checker and the ESLint preset; record the errors of the checker the legacy already has in ddd-ts-kit-baseline.json (npx ddd-ts-kit check --baseline write) and its lint findings in eslint-suppressions.json (npx eslint . --suppress-all, a warning raised to error first), both of which then only shrink (check --baseline prune, eslint --prune-suppressions); each relaxation of a rule recorded with its decision record; add dependency-cruiser when the tree is in place |
| The editor loop of a coding agent | the per-file check after each write, the full gate before finishing |
| A monorepo with its own boundary tooling | keep it for package boundaries; the kit's rules still hold inside each service |
| TypeScript 7 only, no TypeScript 6 | not possible today with typed lint; keep both |
| GitLab on a free tier | the pipeline as generated: audit and gitleaks block; scanner findings are visible in the job logs only |
| Wanting the mutation score before the night | npm run test:mutation by hand: Stryker on the domain and application layers of every context, then each layer of each context against its floor; the html report lands in reports/mutation/ |
Sources
Section titled “Sources”- This repository:
pipeline/README.md,packages/cli/README.md(sectionscheck, "Limits"),packages/eslint-plugin/README.md,docs/ARCHITECTURE.md("Who checks what"). - typescript-eslint: https://typescript-eslint.io ; peer range read with
npm view typescript-eslint peerDependencies. - TypeScript 7.0 announcement: https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/
- ESLint flat config: https://eslint.org/docs/latest/use/configure/configuration-files
- dependency-cruiser: https://github.com/sverweij/dependency-cruiser
- knip: https://knip.dev
- GitHub Actions: https://docs.github.com/actions ; GitLab CI/CD: https://docs.gitlab.com/ci/
- gitleaks: https://github.com/gitleaks/gitleaks ; lefthook: https://github.com/evilmartians/lefthook ; commitlint: https://commitlint.js.org
- Stryker: https://stryker-mutator.io
- Robert C. Martin, Clean Architecture, Prentice Hall, 2017 (the dependency rule the analyzers enforce).
See also
Section titled “See also”- Layers and the dependency rule
- Clean code
- Test runners
- Commit discipline
- Team workflow
- Configuration:
rules,limits,deviations,guard