@makinzm/mille 0.0.10 → 0.0.12

package/README.md

@@ -18,11 +18,11 @@ One TOML config. Rust-powered. CI-ready. Supports multiple languages from a sing
 
 ## What it checks
 
-| Check | Rust | Go | TypeScript | JavaScript | Python |
-|---|:---:|:---:|:---:|:---:|:---:|
-| Layer dependency rules (`dependency_mode`) | ✅ | ✅ | ✅ | ✅ | ✅ |
-| External library rules (`external_mode`) | ✅ | ✅ | ✅ | ✅ | ✅ |
-| DI method call rules (`allow_call_patterns`) | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Check | Rust | Go | TypeScript | JavaScript | Python | Java | Kotlin |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| Layer dependency rules (`dependency_mode`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| External library rules (`external_mode`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| DI method call rules (`allow_call_patterns`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 
 ## Install
 
@@ -114,6 +114,32 @@ Generated 'mille.toml'
 
 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`.
+
+**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:
@@ -274,7 +300,85 @@ external_mode   = "opt-out"
 external_deny   = []
 ```
 
-### 2. Run `mille check`
+**Java / Kotlin:**
+
+```toml
+[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:
+
+```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
+```
+
+`mille report external` always exits `0` — it only reports, never enforces rules.
+
+### 4. Run `mille check`
 
 ```sh
 mille check
@@ -288,12 +392,20 @@ 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 violations 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
@@ -304,7 +416,7 @@ Exit codes:
 |---|---|
 | `name` | Project name |
 | `root` | Root directory for analysis |
-| `languages` | Languages to check: `"rust"`, `"go"`, `"typescript"`, `"javascript"`, `"python"` |
+| `languages` | Languages to check: `"rust"`, `"go"`, `"typescript"`, `"javascript"`, `"python"`, `"java"`, `"kotlin"` |
 
 ### `[[layers]]`
 
@@ -348,6 +460,27 @@ test_patterns = ["**/*_test.go", "**/*.spec.ts", "**/*.test.ts"]
 - `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 |
@@ -368,7 +501,7 @@ test_patterns = ["**/*_test.go", "**/*.spec.ts", "**/*.test.ts"]
 
 | Key | Description |
 |---|---|
-| `module_name` | Go module name (matches `go.mod`) |
+| `module_name` | Go module name (matches `go.mod`). `mille init` generates this automatically from `go.mod`. |
 
 ### `[resolve.python]`
 
@@ -385,6 +518,24 @@ test_patterns = ["**/*_test.go", "**/*.spec.ts", "**/*.test.ts"]
 | `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.
+
 ## How it Works
 
 mille uses [tree-sitter](https://tree-sitter.github.io/) for AST-based import extraction — no regex heuristics.
@@ -395,7 +546,7 @@ mille.toml
     ▼
 Layer definitions
     │
-Source files (*.rs, *.go, *.py, *.ts, *.js, ...)
+Source files (*.rs, *.go, *.py, *.ts, *.js, *.java, ...)
     │ tree-sitter parse
     ▼
 RawImport list

package/package.json

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