mille 0.0.14

Architecture Checker — static analysis for layered architecture rules

mille

Like a mille crêpe — your architecture, one clean layer at a time.

mille is a static analysis CLI that enforces dependency rules for layered architectures — Clean Architecture, Onion Architecture, Hexagonal Architecture, and more.

One TOML config. Rust-powered. CI-ready. Supports multiple languages from a single config file.

What it checks

Languages: Rust, Go, TypeScript, JavaScript, Python, Java, Kotlin, PHP, C

Check	Description
dependency_mode	Layer dependency rules — control which layers can import from which
external_mode	External library rules — restrict third-party package usage per layer
allow_call_patterns	DI method call rules — limit which methods may be called on injected types
name_deny	Naming convention rules — forbid infrastructure keywords in domain/usecase

Install

cargo

cargo install mille

npm

npm install -g @makinzm/mille
mille check

Or without installing globally:

npx @makinzm/mille check

Requires Node.js ≥ 18. Bundles mille.wasm — no native compilation needed.

go install

go install github.com/makinzm/mille/packages/go/mille@latest

Embeds mille.wasm via wazero — fully self-contained binary.

pip / uv

# uv (recommended)
uv add --dev mille
uv run mille check

# pip
pip install mille
mille check

Binary download

Pre-built binaries are on GitHub Releases:

Platform	Archive
Linux x86_64	mille-<version>-x86_64-unknown-linux-gnu.tar.gz
Linux arm64	mille-<version>-aarch64-unknown-linux-gnu.tar.gz
macOS x86_64	mille-<version>-x86_64-apple-darwin.tar.gz
macOS arm64	mille-<version>-aarch64-apple-darwin.tar.gz
Windows x86_64	mille-<version>-x86_64-pc-windows-msvc.zip

Quick Start

1. Generate mille.toml with mille init

mille init

mille init analyzes actual import statements in your source files to infer layer structure and dependencies — no predetermined naming conventions needed. It prints the inferred dependency graph before writing the config:

Detected languages: rust
Scanning imports...
Using layer depth: 2

Inferred layer structure:
  domain               ← (no internal dependencies)
  usecase              → domain
    external: anyhow
  infrastructure       → domain
    external: serde, tokio

Generated 'mille.toml'

Flag	Default	Description
--output <path>	mille.toml	Write config to a custom path
--force	false	Overwrite an existing file without prompting
--depth <N>	auto	Layer detection depth from project root

--depth and auto-detection: mille init automatically finds the right layer depth by trying depths 1–6, skipping common source-layout roots (src, lib, app, etc.), and selecting the first depth that yields 2–8 candidate layers. For a project with src/domain/entity, src/domain/repository, src/usecase/ — depth 2 is chosen, rolling entity and repository up into domain. Use --depth N to override when auto-detection picks the wrong level.

The generated config includes allow (inferred internal dependencies) and external_allow (detected external packages) per layer. After generating, review the config and run mille check to see results.

Naming in monorepos: When multiple sub-projects contain a directory with the same name (e.g. crawler/src/domain and server/src/domain), mille init gives each its own layer with a distinguishing prefix (crawler_domain, server_domain). Merging is left to you.

Excluded paths: mille check automatically skips .venv, venv, node_modules, target, dist, build, and similar build/dependency directories, so generated paths patterns like apps/** are safe to use.

Python submodule imports: external_allow = ["matplotlib"] correctly allows both import matplotlib and import matplotlib.pyplot.

Python src/ layout (namespace packages): When your project uses a src/ layout and imports like from src.domain.entity import Foo, mille init detects that src is used as a top-level import prefix and automatically adds it to package_names. This means from src.domain... is classified as Internal and src does not appear in external_allow. Cross-layer imports like from src.domain.entity import Foo (written in src/infrastructure/) are correctly resolved to the src/domain layer and appear as an allow dependency in the generated mille.toml. Files at the project root of a sub-tree (e.g. src/main.py) are included in the src layer rather than being silently skipped.

Go projects: mille init reads go.mod and generates [resolve.go] module_name automatically — internal module imports are classified correctly during mille check. External packages appear in external_allow with their full import paths (e.g. "github.com/cilium/ebpf", "fmt", "net/http").

TypeScript/JavaScript subpath imports: external_allow = ["vitest"] correctly allows both import "vitest" and import "vitest/config". Scoped packages (@scope/name/sub) are matched by "@scope/name".

Java/Kotlin projects: mille init uses package declarations — not directory depth — to detect layers. This works correctly for Maven's src/main/java/com/example/myapp/domain/ as well as flat src/domain/ layouts. pom.xml (Maven) and build.gradle + settings.gradle (Gradle) are read automatically to generate [resolve.java] module_name. Layer paths use **/layer/** globs so mille check matches regardless of the source root depth.

Detected languages: java
Scanning imports...

Inferred layer structure:
  domain               ← (no internal dependencies)
  infrastructure       → domain
    external: java.util.List
  usecase              → domain
  main                 → domain, infrastructure, usecase

Generated 'mille.toml'

2. (Or) Create mille.toml manually

Place mille.toml in your project root:

Rust:

[project]
name      = "my-app"
root      = "."
languages = ["rust"]

[[layers]]
name            = "domain"
paths           = ["src/domain/**"]
dependency_mode = "opt-in"
allow           = []
external_mode   = "opt-in"
external_allow  = []

[[layers]]
name            = "usecase"
paths           = ["src/usecase/**"]
dependency_mode = "opt-in"
allow           = ["domain"]
external_mode   = "opt-in"
external_allow  = []

[[layers]]
name            = "infrastructure"
paths           = ["src/infrastructure/**"]
dependency_mode = "opt-out"
deny            = []
external_mode   = "opt-out"
external_deny   = []

[[layers]]
name            = "main"
paths           = ["src/main.rs"]
dependency_mode = "opt-in"
allow           = ["domain", "infrastructure", "usecase"]
external_mode   = "opt-in"
external_allow  = ["clap"]

  [[layers.allow_call_patterns]]
  callee_layer  = "infrastructure"
  allow_methods = ["new", "build", "create", "init", "setup"]

TypeScript / JavaScript:

[project]
name      = "my-ts-app"
root      = "."
languages = ["typescript"]

[resolve.typescript]
tsconfig = "./tsconfig.json"

[[layers]]
name            = "domain"
paths           = ["domain/**"]
dependency_mode = "opt-in"
allow           = []
external_mode   = "opt-out"
external_deny   = []

[[layers]]
name            = "usecase"
paths           = ["usecase/**"]
dependency_mode = "opt-in"
allow           = ["domain"]
external_mode   = "opt-in"
external_allow  = ["zod"]

[[layers]]
name            = "infrastructure"
paths           = ["infrastructure/**"]
dependency_mode = "opt-out"
deny            = []
external_mode   = "opt-out"
external_deny   = []

Use languages = ["javascript"] for plain .js / .jsx projects (no [resolve.typescript] needed).

Go:

[project]
name      = "my-go-app"
root      = "."
languages = ["go"]

[resolve.go]
module_name = "github.com/myorg/my-go-app"

[[layers]]
name            = "domain"
paths           = ["domain/**"]
dependency_mode = "opt-in"
allow           = []

[[layers]]
name            = "usecase"
paths           = ["usecase/**"]
dependency_mode = "opt-in"
allow           = ["domain"]

[[layers]]
name            = "infrastructure"
paths           = ["infrastructure/**"]
dependency_mode = "opt-out"
deny            = []

[[layers]]
name            = "cmd"
paths           = ["cmd/**"]
dependency_mode = "opt-in"
allow           = ["domain", "usecase", "infrastructure"]

Python:

[project]
name      = "my-python-app"
root      = "."
languages = ["python"]

[resolve.python]
src_root      = "."
package_names = ["domain", "usecase", "infrastructure"]

[[layers]]
name            = "domain"
paths           = ["domain/**"]
dependency_mode = "opt-in"
allow           = []
external_mode   = "opt-out"
external_deny   = []

[[layers]]
name            = "usecase"
paths           = ["usecase/**"]
dependency_mode = "opt-in"
allow           = ["domain"]
external_mode   = "opt-out"
external_deny   = []

[[layers]]
name            = "infrastructure"
paths           = ["infrastructure/**"]
dependency_mode = "opt-out"
deny            = []
external_mode   = "opt-out"
external_deny   = []

Java / Kotlin:

[project]
name      = "my-java-app"
root      = "."
languages = ["java"]   # or ["kotlin"] for Kotlin projects

[resolve.java]
module_name = "com.example.myapp"

[[layers]]
name            = "domain"
paths           = ["src/domain/**"]
dependency_mode = "opt-in"
allow           = []
external_mode   = "opt-out"

[[layers]]
name            = "usecase"
paths           = ["src/usecase/**"]
dependency_mode = "opt-in"
allow           = ["domain"]
external_mode   = "opt-out"

[[layers]]
name            = "infrastructure"
paths           = ["src/infrastructure/**"]
dependency_mode = "opt-in"
allow           = ["domain"]
external_mode   = "opt-in"
external_allow  = ["java.util.List", "java.util.Map"]

module_name is the base package of your project (e.g. com.example.myapp). Imports starting with this prefix are classified as Internal and matched against layer globs. All other imports (including java.util.* stdlib) are classified as External and subject to external_allow / external_deny rules.

2. Visualize with mille analyze

Before enforcing rules, you can inspect the actual dependency graph:

mille analyze                  # human-readable terminal output (default)
mille analyze --format json    # machine-readable JSON graph
mille analyze --format dot     # Graphviz DOT (pipe to: dot -Tsvg -o graph.svg)
mille analyze --format svg     # self-contained SVG image (open in a browser)

Example SVG output (dark theme, green edges):

mille analyze --format svg > graph.svg && open graph.svg

mille analyze always exits 0 — it only visualizes, never enforces rules.

3. Inspect external dependencies with mille report external

mille report external                  # human-readable table (default)
mille report external --format json    # machine-readable JSON
mille report external --output report.json --format json   # write to file

Shows which external packages each layer actually imports — useful for auditing external_allow lists or documenting your dependency footprint.

Example output:

External Dependencies by Layer

  domain          (none)
  usecase         (none)
  infrastructure  database/sql
  cmd             fmt, os

mille report external always exits 0 — it only reports, never enforces rules.

4. Run mille check

mille check

Output formats:

mille check                          # human-readable terminal output (default)
mille check --format github-actions  # GitHub Actions annotations (::error file=...)
mille check --format json            # machine-readable JSON

Fail threshold:

mille check                         # exit 1 on error-severity violations only (default)
mille check --fail-on warning       # exit 1 on any violation (error or warning)
mille check --fail-on error         # explicit default — same as no flag

Exit codes:

Code	Meaning
0	No violations (or only warnings without --fail-on warning)
1	One or more violations at the configured fail threshold
3	Configuration file error

Configuration Reference

[project]

Key	Description
name	Project name
root	Root directory for analysis
languages	Languages to check: "rust", "go", "typescript", "javascript", "python", "java", "kotlin", "php", "c"

[[layers]]

Key	Description
name	Layer name
paths	Glob patterns for files in this layer
dependency_mode	"opt-in" (deny all except allow) or "opt-out" (allow all except deny)
allow	Allowed layers (when dependency_mode = "opt-in")
deny	Forbidden layers (when dependency_mode = "opt-out")
external_mode	"opt-in" or "opt-out" for external library usage
external_allow	Allowed external packages (when external_mode = "opt-in")
external_deny	Forbidden external packages (when external_mode = "opt-out")
name_deny	Forbidden keywords for naming convention check (case-insensitive partial match)
name_allow	Substrings to strip before name_deny check (e.g. "category" prevents "go" match inside it)
name_targets	Targets to check: "file", "symbol", "variable", "comment", "string_literal", "identifier" (default: all)
name_deny_ignore	Glob patterns for files to exclude from naming checks (e.g. "**/test_*.rs")

Naming Convention Check (name_deny)

Forbid infrastructure-specific keywords from appearing in a layer's names.

[[layers]]
name = "usecase"
paths = ["src/usecase/**"]
dependency_mode = "opt-out"
deny = []
external_mode = "opt-out"
external_deny = []

# Usecase layer must not reference specific infrastructure technologies
name_deny    = ["gcp", "aws", "azure", "mysql", "postgres"]
name_allow   = ["category"]   # "category" contains "go" but should not be flagged
name_targets = ["file", "symbol", "variable", "comment", "string_literal", "identifier"]  # default: all targets
name_deny_ignore = ["**/test_*.rs", "tests/**"]  # exclude test files from naming checks

Rules:

• Case-insensitive (GCP = gcp = Gcp)
• Partial match (ManageGcp also matches gcp)
• name_allow strips listed substrings before matching (e.g. "category" prevents false positive on "go")
• name_deny_ignore excludes files matching glob patterns from naming checks entirely
• name_targets restricts which entity types are checked:
  • "file": file basename (e.g. aws_client.rs)
  • "symbol": function, class, struct, enum, trait, interface, type alias names
  • "variable": variable, const, let, static declaration names
  • "comment": inline comment content
  • "string_literal": string literal content
  • "identifier": attribute/field access identifiers (e.g. gcp in cfg.gcp.bucket)
• Supported languages: Rust, TypeScript, JavaScript, Python, Go, Java, Kotlin, PHP, C
• Severity is controlled by severity.naming_violation (default: "error")

[[layers.allow_call_patterns]]

Restricts which methods may be called on a given layer's types. Only valid on the main layer (or equivalent DI entrypoint).

Key	Description
callee_layer	The layer whose methods are being restricted
allow_methods	List of method names that are permitted

[ignore]

Exclude files from the architecture check entirely, or suppress violations for test/mock files.

Key	Description
paths	Glob patterns — matching files are excluded from collection and not counted in layer stats
test_patterns	Glob patterns — matching files are still counted in layer stats but their imports are not violation-checked

[ignore]
paths         = ["**/mock/**", "**/generated/**", "**/testdata/**"]
test_patterns = ["**/*_test.go", "**/*.spec.ts", "**/*.test.ts"]

When to use paths vs test_patterns:

• paths: Files that should not be analyzed at all (generated code, vendor directories, mocks)
• test_patterns: Test files that intentionally import across layers (e.g., integration tests that import both domain and infrastructure)

[severity]

Control the severity level of each violation type. Violations can be "error", "warning", or "info".

Key	Default	Description
dependency_violation	"error"	Layer dependency rule violated
external_violation	"error"	External library rule violated
call_pattern_violation	"error"	DI entrypoint method call rule violated
unknown_import	"warning"	Import that could not be classified
naming_violation	"error"	Naming convention rule violated (name_deny)

[severity]
dependency_violation   = "warning"   # treat as warning for gradual adoption
external_violation     = "error"
call_pattern_violation = "error"
unknown_import         = "warning"
naming_violation       = "warning"   # treat as warning while rolling out naming rules

Use --fail-on warning to exit 1 even for warnings when integrating into CI gradually.

[resolve.typescript]

Key	Description
tsconfig	Path to tsconfig.json. mille reads compilerOptions.paths and resolves path aliases (e.g. @/*) as internal imports.

How TypeScript / JavaScript imports are classified:

Import	Classification
import X from "./module"	Internal
import X from "../module"	Internal
import X from "@/module" (path alias in tsconfig.json)	Internal
import X from "react"	External
import fs from "node:fs"	External

[resolve.go]

Key	Description
module_name	Go module name (matches go.mod). mille init generates this automatically from go.mod.

[resolve.python]

Key	Description
src_root	Root directory of the Python source tree (relative to mille.toml)
package_names	Your package names — imports starting with these are classified as internal. e.g. ["domain", "usecase"]

How Python imports are classified:

Import	Classification
from .sibling import X (relative)	Internal
import domain.entity (matches package_names)	Internal
import os, import sqlalchemy	External

[resolve.java]

Key	Description
module_name	Base package of your project (e.g. com.example.myapp). Imports starting with this prefix are classified as Internal. Generated automatically by mille init.
pom_xml	Path to pom.xml (relative to mille.toml). groupId.artifactId is used as module_name when module_name is not set.
build_gradle	Path to build.gradle (relative to mille.toml). group + rootProject.name from settings.gradle is used as module_name when module_name is not set.

How Java imports are classified:

Import	Classification
import com.example.myapp.domain.User (starts with module_name)	Internal
import static com.example.myapp.util.Helper.method	Internal
import java.util.List, import org.springframework.*	External

Both regular and static imports are supported. Wildcard imports (import java.util.*) are not yet extracted by the parser.

[resolve.php]

Key	Description
namespace	Base namespace of your project (e.g. App). Imports starting with this prefix are classified as Internal.
composer_json	Path to composer.json (relative to mille.toml). The first PSR-4 key in autoload.psr-4 is used as the base namespace when namespace is not set.

How PHP imports are classified:

Import	Classification
use App\Models\User (starts with namespace)	Internal
use App\Services\{Auth, Logger} (group use, expanded)	Internal
use function App\Helpers\format_date	Internal
use DateTime, use PDO, use Exception	Stdlib
use Illuminate\Http\Request	External

Supported use forms: simple, aliased (as), grouped ({}), use function, use const. PHP stdlib classes (DateTime, PDO, Exception, etc.) are automatically classified as Stdlib without any configuration.

Example mille.toml for a Laravel project:

[project]
name    = "my-laravel-app"
root    = "."
languages = ["php"]

[[layers]]
name  = "domain"
paths = ["app/Domain/**"]

[[layers]]
name  = "application"
paths = ["app/Application/**"]
dependency_mode = "opt-in"
allow = ["domain"]

[[layers]]
name  = "infrastructure"
paths = ["app/Infrastructure/**"]
dependency_mode = "opt-in"
allow = ["domain", "application"]

[resolve.php]
composer_json = "composer.json"   # auto-detects "App\\" from autoload.psr-4

C

#include "..." is classified as Internal (project header). #include <...> is classified as Stdlib (standard/POSIX headers) or External (third-party libraries).

Example mille.toml for a C project:

[project]
name    = "my-c-app"
root    = "."
languages = ["c"]

[[layers]]
name  = "domain"
paths = ["src/domain/**"]

[[layers]]
name  = "usecase"
paths = ["src/usecase/**"]
dependency_mode = "opt-in"
allow = ["domain"]

[[layers]]
name  = "infrastructure"
paths = ["src/infrastructure/**"]
dependency_mode = "opt-in"
allow = ["domain"]

How it Works

mille uses tree-sitter for AST-based import extraction — no regex heuristics.

mille.toml
    │
    ▼
Layer definitions
    │
Source files (*.rs, *.go, *.py, *.ts, *.js, *.java, ...)
    │ tree-sitter parse
    ▼
RawImport list
    │ Resolver (stdlib / internal / external)
    ▼
ResolvedImport list
    │ ViolationDetector
    ▼
Violations → terminal output

Dogfooding

mille checks its own source code on every CI run:

mille check   # uses ./mille.toml

See mille.toml for the architecture rules applied to mille itself.

Documentation

• spec.md — Full specification (in Japanese)
• docs/TODO.md — Development roadmap