@makinzm/mille 0.0.10 → 0.0.11

package/README.md

@@ -114,6 +114,16 @@ 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"`.
+
 ### 2. (Or) Create `mille.toml` manually
 
 Place `mille.toml` in your project root:
@@ -274,7 +284,49 @@ external_mode   = "opt-out"
 external_deny   = []
 ```
 
-### 2. Run `mille check`
+### 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 +340,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
@@ -348,6 +408,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 +449,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]`
 

package/package.json

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