code-auditor-mcp 3.0.2 → 3.0.4

package/plugin/skills/code-auditor/SKILL-SEARCH.md

@@ -0,0 +1,117 @@
+# Search Operator Reference
+
+`code-audit search <query>` supports operators for precise queries against the code index.
+
+## Operators
+
+### Type & Location
+
+| Operator | Aliases | Example | Description |
+|----------|---------|---------|-------------|
+| `file:` | `path:` | `file:src/auth` | Files whose path matches the glob |
+| `lang:` | `language:` | `lang:typescript` | Files in a specific language |
+| `type:` | — | `type:.ts` | Files with a specific extension |
+| `exported:` | — | `exported:` | Exported functions/components only |
+
+### Complexity
+
+| Operator | Example | Description |
+|----------|---------|-------------|
+| `complexity:N` | `complexity:10` | Exact cyclomatic complexity |
+| `complexity:>N` | `complexity:>10` | Greater than N |
+| `complexity:<N` | `complexity:<5` | Less than N |
+| `complexity:N..M` | `complexity:5..15` | Range (inclusive) |
+| `complexity:N-M` | `complexity:5-15` | Range (inclusive) |
+
+### Documentation
+
+| Operator | Aliases | Example | Description |
+|----------|---------|---------|-------------|
+| `jsdoc:` | `doc:` | `jsdoc:` | Has JSDoc documentation |
+
+### Signatures
+
+| Operator | Aliases | Example | Description |
+|----------|---------|---------|-------------|
+| `param:` | `parameter:` | `param:userId` | Has a parameter named userId |
+| `return:` | `returns:` | `return:Promise` | Return type contains Promise |
+
+### React/Components
+
+| Operator | Aliases | Example | Description |
+|----------|---------|---------|-------------|
+| `component:` | — | `component:functional` | Component type: functional, class, memo, forwardRef |
+| `hook:` | `hooks:` | `hook:useState` | Components using a specific hook |
+| `prop:` | `props:` | `prop:onClick` | Components with a specific prop |
+| `entity:` | — | `entity:function` | Entity type: function or component |
+
+### Call Graph & Dependencies
+
+| Operator | Aliases | Example | Description |
+|----------|---------|---------|-------------|
+| `calls:` | — | `calls:validateUser` | Functions that call a specific function |
+| `calledby:` | `dependents-of:`, `used-by:` | `calledby:UserService` | Functions called by a specific function |
+| `dep:` | `dependency:`, `uses:` | `dep:express` | Functions importing a specific module |
+| `depends-on:` | `imports-from:` | `depends-on:lodash` | Functions depending on a module |
+| `unused-imports` | `dead-imports` | `unused-imports` | Functions with unused imports |
+
+### Free-text & Matching
+
+| Feature | Example | Description |
+|---------|---------|-------------|
+| Terms | `validate user` | Search function names, signatures, JSDoc, bodies via FTS5 |
+| Exact phrase | `"user authentication"` | Double-quoted exact phrase match |
+| Excluded terms | `validation -email` | Exclude results matching a term |
+| Fuzzy search | `~` or `fuzzy` | Enable fuzzy matching |
+| Stemming | `stem` or `stemming` | Enable word stemming |
+
+## Combining Operators
+
+Operators combine with AND semantics. Examples:
+
+```bash
+# Complex Go functions that call validateUser
+code-audit search "calls:validateUser lang:go complexity:>10"
+
+# Exported TypeScript functions with JSDoc in the auth directory
+code-audit search "exported: lang:typescript jsdoc: file:src/auth"
+
+# Functional components using useState but not useEffect
+code-audit search "component:functional hook:useState -useEffect"
+
+# Functions depending on lodash (to audit lodash usage before removing it)
+code-audit search "dep:lodash lang:typescript"
+
+# Find dead imports across the codebase
+code-audit search "unused-imports"
+```
+
+## Symbol Lookup
+
+Use `--definition` to look up a specific symbol's full metadata:
+
+```bash
+code-audit search --definition "UserService.createUser"
+```
+
+Returns: signature, parameters, return type, JSDoc, dependencies, callers, complexity, file location.
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output results as JSON |
+| `--limit N` | Maximum results (default: 20) |
+| `--language <lang>` | Filter results by language |
+| `--definition` | Look up a specific symbol by name instead of searching |
+
+## How It Works
+
+Free-text terms are run through the QueryParser which:
+1. Extracts operators (`calls:`, `lang:`, etc.) and their values
+2. Extracts exact phrases (quoted strings)
+3. Expands terms with synonym expansion (e.g., `get` → `fetch`, `retrieve`, `obtain`)
+4. Splits camelCase (`getUserData` → `get`, `user`, `data`) and snake_case identifiers
+5. Compiles to SQL with FTS5 MATCH expressions against the `functions_fts` virtual table
+
+This means `search "getUser"` will match `getUserData`, `fetchUser`, `retrieveUser`, etc. — much broader than grep.

package/plugin/skills/code-auditor/SKILL.md

@@ -0,0 +1,119 @@
+---
+description: Audit code quality, search the codebase semantically, enforce invariants, and fix violations inline.
+---
+
+# Code Auditor Skill
+
+You have the `code-audit` CLI available. It indexes every function, component, and struct in the codebase for semantic search and invariant enforcement. Use these commands instead of raw grep/find whenever possible.
+
+## When to use which command
+
+### `code-audit search` — find code by meaning, not just text
+
+Use `code-audit search <query>` with its operator syntax instead of `grep` or `rg`. The full operator reference is in `SKILL-SEARCH.md`.
+
+Key operators:
+- `calls:<fn>` — every caller of a function (uses the call graph, not regex)
+- `dep:<module>` — everything importing a module
+- `lang:<lang> complexity:>N` — complex functions in a specific language
+- `exported:` — public API surface
+- `file:<glob>` — scope to matching file paths
+- `unused-imports` — dead imports to clean up
+
+Free-text terms search function names, signatures, JSDoc, and bodies via FTS5. This is almost always faster and more accurate than grepping.
+
+```bash
+code-audit search "calls:validateUser lang:typescript complexity:>5" --limit 20 --json
+code-audit search --definition "UserService.createUser"   # look up a specific symbol
+code-audit search "dep:express exported:" --language go   # Go functions that import express and are exported
+```
+
+### `code-audit audit` — run analysis before claiming work is done
+
+Run an audit before declaring a task complete:
+
+```bash
+code-audit audit --path .                           # Full audit
+code-audit changed --json --fail-on critical         # Diff-scoped audit (hook contract)
+```
+
+Use `code-audit changed` after edits to confirm you haven't introduced violations. If the hook is active it already runs `code-audit changed --fail-on critical` automatically on Write/Edit — pay attention to its output.
+
+Expected output: JSON violation list (with `--json`) or colored terminal summary. Non-zero exit code means violations at or above `--fail-on` severity were found.
+
+### `code-audit config` — know the project's laws
+
+At session start, check for invariant rules:
+
+```bash
+code-audit config rules-list                         # List active rules
+code-audit config rules-check                        # Validate .codeauditor.json
+```
+
+These are the codebase's declared constraints — "no importing X from Y," "module A must not import module B," "exported names must match this pattern," "ban specific AST patterns." You can't comply with rules you don't know about. The full rule-kind reference is in `SKILL-RULE-KINDS.md`.
+
+### `code-audit tasks` — queue remediation work
+
+```bash
+code-audit tasks list                                # List all tasks
+code-audit tasks create --title "Fix SQL injection" --priority high
+code-audit tasks get <taskId>                        # Get task details
+code-audit tasks update <taskId> --status in_progress
+code-audit tasks complete <taskId>                   # Mark task done
+code-audit tasks delete <taskId>                     # Delete a task
+code-audit tasks from-audit                          # Create tasks from audit violations
+```
+
+Use `tasks from-audit` to convert audit violations into a tracked task list. This lets you triage findings: fix criticals now, file warnings for later, dismiss suggestions. Tasks carry fingerprints so duplicates are automatically deduplicated across audit runs.
+
+### `code-audit index` — refresh the index after structural changes
+
+```bash
+code-audit index sync --path .
+```
+
+If you've added, renamed, or deleted files, run this so searches and audits reflect the current state. The index is rebuilt incrementally; a full sync is fast.
+
+### `code-audit map` — get a structural overview
+
+```bash
+code-audit map -p .                                  # Generate a codebase map
+```
+
+Use this for a high-level architecture overview. Useful when orienting in an unfamiliar codebase.
+
+### `code-audit generate-config` — generate AI tool integration configs
+
+```bash
+code-audit generate-config                           # Generate MCP configs for AI coding tools
+code-audit generate-config --tool claude             # Claude-specific MCP config
+```
+
+Creates MCP server configuration files for AI coding assistants (Claude, Cursor, Continue, Copilot, etc.) so they can connect to code-auditor as an MCP server.
+
+## Interpreting hook feedback
+
+When the PostToolUse hook blocks your edit with a violation message:
+
+1. **Read the violation** — it includes the invariant rule's `message` field explaining *why* the edit was blocked
+2. **Fix the violation** — change your approach to comply with the invariant
+3. **Do NOT retry the same edit** — the hook will block it again
+4. The hook runs `code-audit changed --fail-on critical`, so only critical-severity invariant violations block edits. Warnings and suggestions pass through as non-blocking output — still worth fixing.
+
+The hook auto-installs the package via npx on first use — no manual npm step needed. If the hook reports `[code-auditor] code-audit could not run`, the npx auto-install failed (network, unsupported platform). The agent should try again; if it persists, `npm install code-auditor-mcp` is the manual fix.
+
+## Quick reference
+
+| Task | Command |
+|------|---------|
+| Find callers | `code-audit search "calls:<fn>"` |
+| Find by import | `code-audit search "dep:<module>"` |
+| Complex functions | `code-audit search "lang:go complexity:>10"` |
+| Look up symbol | `code-audit search --definition "<name>"` |
+| Diff-scoped audit | `code-audit changed --json --fail-on critical` |
+| List invariant rules | `code-audit config rules-list` |
+| Triage violations | `code-audit tasks from-audit` |
+| Sync index | `code-audit index sync --path .` |
+| Codebase map | `code-audit map -p .` |
+| Rule reference | See `SKILL-RULE-KINDS.md` |
+| Search reference | See `SKILL-SEARCH.md` |

package/server.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
+  "name": "io.github.BenAHammond/code-auditor-mcp",
+  "description": "Architectural invariants and code quality analysis, enforced inside your AI agent's edit loop. MCP server + CLI + Claude Code plugin. TypeScript, JavaScript, Go.",
+  "repository": {
+    "url": "https://github.com/BenAHammond/code-auditor-mcp",
+    "source": "github"
+  },
+  "version": "3.0.3",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "code-auditor-mcp",
+      "version": "3.0.3",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}