@makinzm/mille 0.0.9 → 0.0.11

package/README.md

@@ -1,59 +1,51 @@
 # mille
 
-> Architecture Checker — static analysis CLI for layered architecture rules
+> Like a mille crêpe — your architecture, one clean layer at a time.
 
-`mille` is a CLI tool that enforces **dependency rules for layered architectures** (Clean Architecture, Onion Architecture, Hexagonal Architecture, etc.).
+```
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  presentation
+  · · · · · · · · · · · · · · · · · ·  (deps only flow inward)
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  infrastructure
+  · · · · · · · · · · · · · · · · · ·
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  usecase
+  · · · · · · · · · · · · · · · · · ·
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  domain
+```
 
-It is implemented in Rust, supports multiple languages from a single TOML config, and is designed to run in CI/CD pipelines.
+`mille` is a static analysis CLI that enforces **dependency rules for layered architectures** — Clean Architecture, Onion Architecture, Hexagonal Architecture, and more.
 
-## Features
+One TOML config. Rust-powered. CI-ready. Supports multiple languages from a single config file.
 
-| Feature | Status |
-|---|---|
-| Internal layer dependency check (`dependency_mode`) | ✅ |
-| External library dependency check (`external_mode`) | ✅ |
-| DI entrypoint method call check (`allow_call_patterns`) | ✅ |
-| Rust support | ✅ |
-| Go support | ✅ |
-| Python support | ✅ |
-| TypeScript / JavaScript support | ✅ |
+## What it checks
 
-## How to Install
+| Check | Rust | Go | TypeScript | JavaScript | Python |
+|---|:---:|:---:|:---:|:---:|:---:|
+| Layer dependency rules (`dependency_mode`) | ✅ | ✅ | ✅ | ✅ | ✅ |
+| External library rules (`external_mode`) | ✅ | ✅ | ✅ | ✅ | ✅ |
+| DI method call rules (`allow_call_patterns`) | ✅ | ✅ | ✅ | ✅ | ✅ |
 
-### cargo (Rust users)
-
-```sh
-cargo install mille
-```
+## Install
 
-### pip / uv (Python users)
+### cargo
 
 ```sh
-# uv (recommended)
-uv add --dev mille
-uv run mille check
-
-# pip
-pip install mille
-mille check
+cargo install mille
 ```
 
-The Python package is a native extension built with [maturin](https://github.com/PyO3/maturin) (PyO3). It provides both a CLI (`mille check`) and a Python API (`import mille; mille.check(...)`).
-
-### npm (Node.js users)
+### npm
 
 ```sh
 npm install -g @makinzm/mille
 mille check
 ```
 
-Or use it without installing globally:
+Or without installing globally:
 
 ```sh
 npx @makinzm/mille check
 ```
 
-Requires Node.js ≥ 18. The npm package bundles `mille.wasm` (the compiled Rust core) and runs it via Node.js's built-in `node:wasi` module — no native compilation or network access required at install time.
+Requires Node.js ≥ 18. Bundles `mille.wasm` — no native compilation needed.
 
 ### go install
 
@@ -61,11 +53,23 @@ Requires Node.js ≥ 18. The npm package bundles `mille.wasm` (the compiled Rust
 go install github.com/makinzm/mille/packages/go/mille@latest
 ```
 
-The Go wrapper embeds `mille.wasm` (the compiled Rust core) and runs it via [wazero](https://wazero.io/) — a zero-dependency WebAssembly runtime. No network access or caching required; the binary is fully self-contained.
+Embeds `mille.wasm` via [wazero](https://wazero.io/) — fully self-contained binary.
 
-### Direct binary download
+### pip / uv
 
-Pre-built binaries for each platform are available on [GitHub Releases](https://github.com/makinzm/mille/releases):
+```sh
+# 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](https://github.com/makinzm/mille/releases):
 
 | Platform | Archive |
 |---|---|
@@ -75,19 +79,56 @@ Pre-built binaries for each platform are available on [GitHub Releases](https://
 | 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`
+
 ```sh
-# Example: Linux x86_64
-curl -L https://github.com/makinzm/mille/releases/latest/download/mille-<version>-x86_64-unknown-linux-gnu.tar.gz | tar xz
-./mille check
+mille init
 ```
 
-## Quick Start
+`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.
 
-### 1. Create `mille.toml`
+**Python submodule imports**: `external_allow = ["matplotlib"]` correctly allows both `import matplotlib` and `import matplotlib.pyplot`.
+
+**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"`.
+
+### 2. (Or) Create `mille.toml` manually
 
 Place `mille.toml` in your project root:
 
-**Rust project example:**
+**Rust:**
 
 ```toml
 [project]
@@ -132,17 +173,16 @@ external_allow  = ["clap"]
   allow_methods = ["new", "build", "create", "init", "setup"]
 ```
 
-**Python project example:**
+**TypeScript / JavaScript:**
 
 ```toml
 [project]
-name      = "my-python-app"
+name      = "my-ts-app"
 root      = "."
-languages = ["python"]
+languages = ["typescript"]
 
-[resolve.python]
-src_root      = "."
-package_names = ["domain", "usecase", "infrastructure"]
+[resolve.typescript]
+tsconfig = "./tsconfig.json"
 
 [[layers]]
 name            = "domain"
@@ -157,8 +197,8 @@ name            = "usecase"
 paths           = ["usecase/**"]
 dependency_mode = "opt-in"
 allow           = ["domain"]
-external_mode   = "opt-out"
-external_deny   = []
+external_mode   = "opt-in"
+external_allow  = ["zod"]
 
 [[layers]]
 name            = "infrastructure"
@@ -169,92 +209,151 @@ external_mode   = "opt-out"
 external_deny   = []
 ```
 
-**TypeScript / JavaScript project example:**
+> Use `languages = ["javascript"]` for plain `.js` / `.jsx` projects (no `[resolve.typescript]` needed).
+
+**Go:**
 
 ```toml
 [project]
-name      = "my-ts-app"
+name      = "my-go-app"
 root      = "."
-languages = ["typescript"]
+languages = ["go"]
 
-[resolve.typescript]
-tsconfig = "./tsconfig.json"
+[resolve.go]
+module_name = "github.com/myorg/my-go-app"
 
 [[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).
+[[layers]]
+name            = "cmd"
+paths           = ["cmd/**"]
+dependency_mode = "opt-in"
+allow           = ["domain", "usecase", "infrastructure"]
+```
 
-**Go project example:**
+**Python:**
 
 ```toml
 [project]
-name      = "my-go-app"
+name      = "my-python-app"
 root      = "."
-languages = ["go"]
+languages = ["python"]
 
-[resolve.go]
-module_name = "github.com/myorg/my-go-app"
+[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   = []
+```
 
-[[layers]]
-name            = "cmd"
-paths           = ["cmd/**"]
-dependency_mode = "opt-in"
-allow           = ["domain", "usecase", "infrastructure"]
+### 2. Visualize with `mille analyze`
+
+Before enforcing rules, you can inspect the actual dependency graph:
+
+```sh
+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):
+
+```sh
+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`
+
+```sh
+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
 ```
 
-### 2. Run `mille check`
+`mille report external` always exits `0` — it only reports, never enforces rules.
+
+### 4. Run `mille check`
 
 ```sh
 mille check
 ```
 
+Output formats:
+
+```sh
+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:
+
+```sh
+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 |
-| `1` | One or more errors detected |
+| `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
@@ -265,100 +364,111 @@ Exit codes:
 |---|---|
 | `name` | Project name |
 | `root` | Root directory for analysis |
-| `languages` | List of languages to check (e.g. `["rust", "go"]`) |
+| `languages` | Languages to check: `"rust"`, `"go"`, `"typescript"`, `"javascript"`, `"python"` |
 
 ### `[[layers]]`
 
 | Key | Description |
 |---|---|
 | `name` | Layer name |
-| `paths` | Glob patterns for files belonging to this layer |
+| `paths` | Glob patterns for files in this layer |
 | `dependency_mode` | `"opt-in"` (deny all except `allow`) or `"opt-out"` (allow all except `deny`) |
-| `allow` | Layers allowed as dependencies (when `dependency_mode = "opt-in"`) |
-| `deny` | Layers forbidden as dependencies (when `dependency_mode = "opt-out"`) |
+| `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` | Regex patterns of allowed external packages (when `external_mode = "opt-in"`) |
-| `external_deny` | Regex patterns of forbidden external packages (when `external_mode = "opt-out"`) |
+| `external_allow` | Allowed external packages (when `external_mode = "opt-in"`) |
+| `external_deny` | Forbidden external packages (when `external_mode = "opt-out"`) |
 
 ### `[[layers.allow_call_patterns]]`
 
-Restricts which methods may be called on a given layer's types. Only valid on the `main` layer.
+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 |
+
+```toml
+[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 |
+
+```toml
+[severity]
+dependency_violation   = "warning"   # treat as warning for gradual adoption
+external_violation     = "error"
+call_pattern_violation = "error"
+unknown_import         = "warning"
+```
+
+Use `--fail-on warning` to exit 1 even for warnings when integrating into CI gradually.
+
 ### `[resolve.typescript]`
 
 | Key | Description |
 |---|---|
-| `tsconfig` | Path to `tsconfig.json`. When specified, mille reads `compilerOptions.paths` and resolves path aliases (e.g. `@/*`) as internal imports. |
+| `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"` (starts with `./`) | Internal |
-| `import X from "../module"` (starts with `../`) | Internal |
+| `import X from "./module"` | Internal |
+| `import X from "../module"` | Internal |
 | `import X from "@/module"` (path alias in `tsconfig.json`) | Internal |
-| `import X from "react"` (npm package) | External |
-| `import fs from "node:fs"` (Node.js built-in) | External |
-
-For relative imports, mille resolves the path from the importing file and matches it against layer glob patterns. For example, `import { User } from "../domain/user"` in `usecase/user_usecase.ts` resolves to `domain/user`, matching the layer glob `domain/**`.
-
-For path aliases, mille expands the alias using `compilerOptions.paths` and treats the result as an internal import. For example, with `"@/*": ["./src/*"]`, `import { User } from "@/domain/user"` resolves to `src/domain/user`.
+| `import X from "react"` | External |
+| `import fs from "node:fs"` | External |
 
 ### `[resolve.go]`
 
 | Key | Description |
 |---|---|
-| `module_name` | Go module name (matches the module path in `go.mod`) |
+| `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` | List of your own package names (used to classify absolute imports as internal). e.g. `["domain", "usecase", "infrastructure"]` |
+| `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 a `package_names` entry) | Internal |
-| `import os`, `import sqlalchemy` (others) | External |
-
-## Python API
-
-In addition to the CLI, the Python package exposes a programmatic API:
-
-```python
-import mille
-
-# Run architecture check and get a result object
-result = mille.check("path/to/mille.toml")  # defaults to "mille.toml"
-
-print(f"violations: {len(result.violations)}")
-for v in result.violations:
-    print(f"  {v.file}:{v.line}  {v.from_layer} -> {v.to_layer}  ({v.import_path})")
-
-for stat in result.layer_stats:
-    print(f"  {stat.name}: {stat.file_count} file(s), {stat.violation_count} violation(s)")
-```
-
-**Types exposed:**
-
-| Class | Attributes |
-|---|---|
-| `CheckResult` | `violations: list[Violation]`, `layer_stats: list[LayerStat]` |
-| `Violation` | `file`, `line`, `from_layer`, `to_layer`, `import_path`, `kind` |
-| `LayerStat` | `name`, `file_count`, `violation_count` |
+| `import domain.entity` (matches `package_names`) | Internal |
+| `import os`, `import sqlalchemy` | External |
 
 ## How it Works
 
-mille uses [tree-sitter](https://tree-sitter.github.io/) for AST-based import extraction — no regex heuristics. The core engine is language-agnostic; language-specific logic is isolated to the `parser` and `resolver` layers.
+mille uses [tree-sitter](https://tree-sitter.github.io/) for AST-based import extraction — no regex heuristics.
 
 ```
 mille.toml
@@ -366,7 +476,7 @@ mille.toml
     ▼
 Layer definitions
     │
-Source files (*.rs, *.go, *.py, ...)
+Source files (*.rs, *.go, *.py, *.ts, *.js, ...)
     │ tree-sitter parse
     ▼
 RawImport list

package/index.js

@@ -8,6 +8,16 @@ process.on('warning', (w) => {
   process.stderr.write(w.stack + '\n');
 });
 
+// NOTE: Intercept --version/-V before forwarding to WASM so that the npm
+// package version (updated by `npm version X.Y.Z` at release time) is shown,
+// rather than the version baked into mille.wasm at WASM-build time.
+const userArgs = process.argv.slice(2);
+if (userArgs.includes('--version') || userArgs.includes('-V')) {
+  const { version } = require('./package.json');
+  process.stdout.write(`mille ${version}\n`);
+  process.exit(0);
+}
+
 const { WASI } = require('node:wasi');
 const { readFileSync } = require('node:fs');
 const { join } = require('node:path');

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@makinzm/mille",
-    "version": "0.0.9",
+    "version": "0.0.11",
     "description": "Architecture Checker — Rust-based multi-language architecture linter",
     "main": "index.js",
     "bin": {