@omfalos/mokosh 0.1.4 → 0.1.5

package/README.md

@@ -20,7 +20,7 @@ Designed for performance and RAG (Retrieval-Augmented Generation) workflows, Mok
 - **Multi-Language Support**: Robust extraction from:
     - **JavaScript/TypeScript**: static `import`, dynamic `import()`, `require()`, and re-exports.
     - **Python**: all import forms (`import X`, `from X import Y`, relative `.`/`..` imports, star imports) via `@lezer/python` AST. Test files (`test_*.py`, `*_test.py`) and test frameworks (`pytest`, `unittest`) auto-detected.
-    - **Go**: top-level declarations and `// @tag` markers via `@lezer/go` AST. All imports are treated as external (local package resolution requires `go.mod` context).
+    - **Go**: top-level declarations and `// @tag` markers via `@lezer/go` AST. Module-local imports are resolved to internal files via `go.mod` (including `replace` directives); everything else is treated as external. See [ADR-007](./docs/adr-007-go-resolution.md).
     - **CSS/SCSS/Less/Stylus**: tracks `@import` relationships.
     - **CoffeeScript/LiveScript/Lua/Gherkin**: AST-based parsing for dependencies and tags.
 - **Graph Traversal**: Programmatically explore dependencies from any entry point with depth control.
@@ -94,6 +94,16 @@ npm run build
 
 ## Quick Start
 
+### AI Assistant Setup
+
+Scaffold a Claude Code skill and slash command that teach your AI assistant how to drive Mokosh — via MCP if it's configured, falling back to the CLI otherwise:
+
+```bash
+npx @omfalos/mokosh --init-skill
+```
+
+This writes `.claude/skills/mokosh/SKILL.md` (auto-invoked) and `.claude/commands/mokosh.md` (explicit `/mokosh`) into your project. Existing files are left untouched — pass `--force` to overwrite.
+
 ### CLI Usage
 
 Generate a dependency graph as JSON:
@@ -153,6 +163,9 @@ npx @omfalos/mokosh --query "category:logic,tag:auth" src/index.ts
 - `--query <query>`: Filter the output graph using a query string. Supported keys: `path`, `type`, `category`, `tag`, `external`, `importsFile`, `importedBy`, `minImports`, `maxImports`, `minSize`, `maxSize`, `hasDocstring`, `sort`, `limit`. Example: `category:logic,hasDocstring:false`.
 - `--query-help`: Print the full query filter reference and examples.
 - `--silent`: Suppress progress output on stderr.
+- `--init-skill`: Scaffold the bundled Claude Code skill/command (`.claude/skills/mokosh/SKILL.md`, `.claude/commands/mokosh.md`) into the current project.
+- `--init-config`: Scaffold a commented starter `mokosh.config.js` into the project root.
+- `--force`: Overwrite existing files. Use with `--init-skill` / `--init-config`.
 - `--help`: Show usage information.
 
 ### Programmatic API
@@ -174,13 +187,57 @@ graph.traverse('src/main.ts', (node, depth) => {
 console.log(graph.toMermaid());
 ```
 
+## Configuration
+
+Mokosh auto-discovers `mokosh.config.json` / `.js` / `.cjs` in the project root — no flag needed, for both the CLI and the MCP server. Scaffold a commented starter file with:
+
+```bash
+npx @omfalos/mokosh --init-config
+```
+
+> **Note:** The MCP server only loads `mokosh.config.json` (JS execution is disabled there for safety). If you want the MCP server to pick up your config, use a `.json` file rather than `.js`/`.cjs`.
+
+**`mokosh.config.json`:**
+```json
+{
+  "cachePath": "custom-cache/graph.json",
+  "entryPoints": ["src/index.ts"],
+  "ignoreDirs": ["vendor", "generated"],
+  "extensions": [".graphql"],
+  "configMatchers": [".myconfig."],
+  "testPatterns": [".unit.", ".integration."],
+  "testLibraries": ["@my-org/test-utils"],
+  "barrelThreshold": 0.7
+}
+```
+
+`ignoreDirs` and `extensions` are **additive** — they extend the built-in defaults rather than replacing them.
+
+### Config fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `cachePath` | `string` | Override default `mokosh-cache/graph.json` |
+| `entryPoints` | `string[]` | Default entry points when none passed on CLI |
+| `ignoreDirs` | `string[]` | Extra dirs to skip (merged with built-in defaults) |
+| `extensions` | `string[]` | Extra file extensions to scan (merged with built-in defaults) |
+| `configMatchers` | `string[]` | Extra basename substrings that classify a file as `"config"` |
+| `testPatterns` | `string[]` | Extra basename substrings that classify a file as `"test"` |
+| `testLibraries` | `string[]` | Extra import names that classify a file as `"test"` |
+| `barrelThreshold` | `number` | Export-ratio threshold for `"barrel"` detection (default `0.8`) |
+| `gitStats` | `boolean` | When `true`, enriches each cache-missed node with `commitCount90d` and `lastAuthor` via `git log`. Off by default. |
+| `coverageReportPath` | `string` | Path (relative to project root) to an Istanbul `coverage-summary.json`. When set, each node gets a `coveragePct` field. |
+| `coverageThreshold` | `number` | Line-coverage % below which `--find-uncovered` / `find_uncovered` flags a file. Default: `80`. |
+| `tagApplier` | `{ framework?, frameworkOverrides? }` | Configures `--apply-tags` output format. `framework` is the fallback test framework (`vitest` \| `playwright` \| `cypress` \| `jest`) used when a file's own imports don't reveal one; `frameworkOverrides` maps path-glob patterns to a framework, checked before the top-level fallback. See [ADR-008](./docs/adr-008-tag-applier-strategies.md). |
+
+See the [Usage Guide](./docs/usage.md#configuration-file) for `mokosh.config.js` (factory functions, side effects) and programmatic config-loading examples.
+
 ## Documentation
 
 For detailed information on each process, check the following guides:
 
 ### Guides
 - [Architecture Overview](./docs/architecture.md)
-- [Product Requirements Document (PRD)](./docs/prd.md)
 - [Usage Guide](./docs/usage.md)
 - [Query Language Guide](./docs/query.md)
 - [Graph Traversal](./docs/traversal.md)
@@ -188,7 +245,7 @@ For detailed information on each process, check the following guides:
 - [Lock File Analysis](./docs/lock-files.md)
 - [MCP Server](./docs/mcp.md)
 - [Monorepo Support](./docs/monorepo.md)
-- [Roadmap](./docs/roadmap.md)
+- [Releasing](./docs/releasing.md)
 
 ### Architecture Decision Records
 - [ADR-001: AST Libraries for Style Parsers](./docs/adr-001-styles-parsing.md)
@@ -197,3 +254,5 @@ For detailed information on each process, check the following guides:
 - [ADR-004: Type Graph — Type-Level Dependency Layer](./docs/adr-004-type-graph.md)
 - [ADR-005: Feature Graph — Domain Clustering by Hub Detection](./docs/adr-005-feature-graph.md)
 - [ADR-006: Responsibility Graph — Semantic Role Assignment](./docs/adr-006-responsibility-graph.md)
+- [ADR-007: Go Import Resolution](./docs/adr-007-go-resolution.md)
+- [ADR-008: Tag Applier Strategy Architecture](./docs/adr-008-tag-applier-strategies.md)