projscan 0.11.0 → 0.14.0

package/dist/tool-manifest.json

@@ -0,0 +1,446 @@
+{
+  "name": "projscan",
+  "version": "0.14.0",
+  "mcpProtocolVersion": "2025-03-26",
+  "generatedAt": "2026-04-26T14:13:37.446Z",
+  "toolCount": 19,
+  "tools": [
+    {
+      "name": "projscan_analyze",
+      "description": "Run a full projscan analysis of the project: languages, frameworks, dependencies, issues, and health score. Use this to understand a codebase before making changes.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "package": {
+            "type": "string",
+            "description": "Optional. Workspace package name (from projscan_workspaces) to scope results to one package only."
+          }
+        }
+      }
+    },
+    {
+      "name": "projscan_doctor",
+      "description": "Run a health check on the project. Returns a 0-100 score, letter grade, and the list of issues (linting, formatting, tests, security, architecture).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "package": {
+            "type": "string",
+            "description": "Optional. Workspace package name (from projscan_workspaces) to scope results to one package only."
+          }
+        }
+      }
+    },
+    {
+      "name": "projscan_hotspots",
+      "description": "Rank files by risk using git churn × AST cyclomatic complexity × open issues. Returns the most dangerous files to touch. Each hotspot includes `cyclomaticComplexity` (null for non-AST languages, where line count is used as fallback). Supports cursor-based pagination: pass the `nextCursor` from a previous response back as `cursor` to fetch the next page. Pass `view: \"functions\"` to flatten results into the top-N riskiest individual functions across all hotspots, ranked by per-function CC.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "limit": {
+            "type": "number",
+            "description": "Cap on total hotspots ranked (default 100). For paging the returned set, use `page_size` + `cursor` instead."
+          },
+          "since": {
+            "type": "string",
+            "description": "Git history window. Examples: \"12 months ago\", \"2024-01-01\". Default: \"12 months ago\"."
+          },
+          "cursor": {
+            "type": "string",
+            "description": "Opaque cursor from a previous response. Omit for the first page."
+          },
+          "page_size": {
+            "type": "number",
+            "description": "Items per page (default 50, max 500)."
+          },
+          "max_tokens": {
+            "type": "number",
+            "description": "Cap response to roughly this many tokens."
+          },
+          "package": {
+            "type": "string",
+            "description": "Optional. Workspace package name (from projscan_workspaces) to scope hotspots to one package only."
+          },
+          "view": {
+            "type": "string",
+            "enum": [
+              "files",
+              "functions"
+            ],
+            "description": "Output shape. \"files\" (default) returns ranked hotspot files. \"functions\" returns the top-N individual functions across all hotspots, sorted by per-function CC desc."
+          }
+        }
+      }
+    },
+    {
+      "name": "projscan_explain",
+      "description": "Explain a single file: purpose, imports, exports, and potential issues. Useful for understanding unfamiliar code before editing.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "file": {
+            "type": "string",
+            "description": "Path to the file relative to the project root."
+          }
+        },
+        "required": [
+          "file"
+        ]
+      }
+    },
+    {
+      "name": "projscan_file",
+      "description": "Drill into a single file: purpose, imports, exports, churn/risk/ownership, related health issues, AST cyclomatic complexity, coupling (fan-in / fan-out), and per-function CC ranked by complexity. Use this after projscan_hotspots when deciding how to approach a specific risky file.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "file": {
+            "type": "string",
+            "description": "Path to the file relative to the project root."
+          }
+        },
+        "required": [
+          "file"
+        ]
+      }
+    },
+    {
+      "name": "projscan_structure",
+      "description": "Return the project directory tree with file counts.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "package": {
+            "type": "string",
+            "description": "Optional. Workspace package name (from projscan_workspaces) to scope results to one package only."
+          }
+        }
+      }
+    },
+    {
+      "name": "projscan_dependencies",
+      "description": "Analyze package.json dependencies and return counts and risks (deprecated packages, wildcard versions, etc.). In a monorepo, returns aggregated totals plus a `byWorkspace` breakdown; pass `package` to scope to one workspace.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "package": {
+            "type": "string",
+            "description": "Optional. Workspace package name to scope analysis to one workspace only."
+          }
+        }
+      }
+    },
+    {
+      "name": "projscan_outdated",
+      "description": "Compare declared vs installed versions of every package. Reports drift (patch/minor/major). Workspace-aware in monorepos: each package.json is scanned, and each entry is tagged with the workspace it came from. Pass `package` to scope to a single workspace. Offline - does not hit the npm registry. Supports cursor pagination.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "package": {
+            "type": "string",
+            "description": "Optional. Workspace package name (from projscan_workspaces) to scope results to one package only."
+          },
+          "cursor": {
+            "type": "string",
+            "description": "Opaque cursor from a previous response."
+          },
+          "page_size": {
+            "type": "number",
+            "description": "Items per page (default 50)."
+          },
+          "max_tokens": {
+            "type": "number",
+            "description": "Cap response size."
+          }
+        }
+      }
+    },
+    {
+      "name": "projscan_audit",
+      "description": "Run `npm audit` and return a normalized summary of vulnerabilities (critical / high / moderate / low / info). Requires package-lock.json. Supports cursor pagination on the findings array. Pass `package` in a monorepo to scope findings to direct deps of one workspace package.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "cursor": {
+            "type": "string",
+            "description": "Opaque cursor from a previous response."
+          },
+          "page_size": {
+            "type": "number",
+            "description": "Items per page (default 50)."
+          },
+          "max_tokens": {
+            "type": "number",
+            "description": "Cap response size."
+          },
+          "package": {
+            "type": "string",
+            "description": "Optional. Workspace package name to scope audit findings to one workspace only."
+          }
+        }
+      }
+    },
+    {
+      "name": "projscan_upgrade",
+      "description": "Preview the impact of upgrading a package: semver drift, breaking-change markers from the local CHANGELOG, and the files in your repo that import it. Offline.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "package": {
+            "type": "string",
+            "description": "Name of the package to preview."
+          }
+        },
+        "required": [
+          "package"
+        ]
+      }
+    },
+    {
+      "name": "projscan_coverage",
+      "description": "Join test coverage with hotspot risk. Returns files ranked by \"risk × uncovered fraction\" - the scariest untested files. Requires a coverage file at coverage/lcov.info, coverage/coverage-final.json, or coverage/coverage-summary.json.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "limit": {
+            "type": "number",
+            "description": "How many entries to return (default: 30, max: 200)."
+          },
+          "max_tokens": {
+            "type": "number",
+            "description": "Cap the response size to roughly this many tokens (~4 chars/token). Truncates the entries array to fit."
+          },
+          "package": {
+            "type": "string",
+            "description": "Optional. Workspace package name (from projscan_workspaces) to scope results to one package only."
+          }
+        }
+      }
+    },
+    {
+      "name": "projscan_graph",
+      "description": "Query the AST-based code graph directly. Returns imports, exports, importers, or symbol definitions for a file or symbol. Agents should prefer this over analyze/doctor/explain for targeted structural questions - it is much cheaper and more accurate.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "file": {
+            "type": "string",
+            "description": "File path (relative to project root) to query."
+          },
+          "symbol": {
+            "type": "string",
+            "description": "Symbol name to query (e.g. a function or class). Use instead of `file` to find where a symbol is defined."
+          },
+          "direction": {
+            "type": "string",
+            "description": "What to return: \"imports\" (what the file imports), \"exports\" (what the file exports), \"importers\" (who imports the file), \"symbol_defs\" (files defining the symbol), \"package_importers\" (files importing a package by name).",
+            "enum": [
+              "imports",
+              "exports",
+              "importers",
+              "symbol_defs",
+              "package_importers"
+            ]
+          },
+          "limit": {
+            "type": "number",
+            "description": "Max entries returned (default 50)."
+          },
+          "max_tokens": {
+            "type": "number",
+            "description": "Cap the response to roughly this many tokens."
+          }
+        },
+        "required": [
+          "direction"
+        ]
+      }
+    },
+    {
+      "name": "projscan_coupling",
+      "description": "Per-file coupling metrics (fan-in, fan-out, instability) and circular-import cycles, derived from the AST code graph. Use `direction` to focus the result: \"all\" returns every file sorted by fan-in; \"high_fan_in\" / \"high_fan_out\" sort accordingly; \"cycles_only\" returns just the files participating in import cycles. Cycles are reported separately as strongly-connected components of size >= 2.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "file": {
+            "type": "string",
+            "description": "Optional. When set, the response includes only this file's coupling row (cycles list still returned in full)."
+          },
+          "direction": {
+            "type": "string",
+            "description": "Filter/sort applied to `files`. Default \"all\".",
+            "enum": [
+              "all",
+              "high_fan_in",
+              "high_fan_out",
+              "cycles_only"
+            ]
+          },
+          "limit": {
+            "type": "number",
+            "description": "Max file rows returned (default 25, max 500)."
+          },
+          "max_tokens": {
+            "type": "number",
+            "description": "Cap the response to roughly this many tokens."
+          },
+          "package": {
+            "type": "string",
+            "description": "Optional. Workspace package name (from projscan_workspaces) to scope coupling rows to one package only."
+          }
+        }
+      }
+    },
+    {
+      "name": "projscan_workspaces",
+      "description": "List monorepo workspace packages (npm/yarn workspaces, pnpm-workspace.yaml, Nx/Turbo/Lerna fallback). Returns one row per package with name, relative path, and version. Use the package `name` as the `package` argument on projscan_hotspots / projscan_coupling to scope those tools to a single package.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "projscan_pr_diff",
+      "description": "Structural (AST) diff between two refs - what changed in exports, imports, call sites, cyclomatic complexity, and fan-in. Not a text diff: this surfaces the symbols and edges that an agent reviewing a PR actually cares about. Defaults: base=origin/main (falls back to main/master/HEAD~1), head=HEAD. Spins up a throwaway git worktree at the base ref to get a clean second graph.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "base": {
+            "type": "string",
+            "description": "Base ref (branch, tag, sha). Default: origin/main, falling back to main/master/HEAD~1."
+          },
+          "head": {
+            "type": "string",
+            "description": "Head ref. Default: HEAD."
+          },
+          "max_tokens": {
+            "type": "number",
+            "description": "Cap the response to roughly this many tokens."
+          },
+          "package": {
+            "type": "string",
+            "description": "Optional. Workspace package name (from projscan_workspaces) to scope results to one package only."
+          }
+        }
+      }
+    },
+    {
+      "name": "projscan_review",
+      "description": "One-call PR review. Combines projscan_pr_diff + per-changed-file risk score + new/expanded import cycles + risky function additions + dependency changes, plus a verdict (\"ok\" | \"review\" | \"block\") with a one-line summary. Use when an agent is asked \"is this PR safe to merge?\" Defaults: base=origin/main (falls back to main/master/HEAD~1), head=HEAD.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "base": {
+            "type": "string",
+            "description": "Base ref (branch, tag, sha). Default: origin/main, falling back to main/master/HEAD~1."
+          },
+          "head": {
+            "type": "string",
+            "description": "Head ref. Default: HEAD."
+          },
+          "max_tokens": {
+            "type": "number",
+            "description": "Cap the response to roughly this many tokens."
+          },
+          "package": {
+            "type": "string",
+            "description": "Optional. Workspace package name to scope all sections of the review to a single package."
+          }
+        }
+      }
+    },
+    {
+      "name": "projscan_fix_suggest",
+      "description": "Given an issue id (from projscan_doctor / projscan_analyze) OR a file + rule pair, return a structured action prompt: headline, why it matters, where to change, one-paragraph instruction the agent can execute, optional suggested test. Rule-driven; no LLM inside projscan. Use this to close the diagnose -> fix loop.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "issue_id": {
+            "type": "string",
+            "description": "Issue id from a previous projscan_doctor / projscan_analyze response."
+          },
+          "file": {
+            "type": "string",
+            "description": "File path (repo-relative). Required when no `issue_id` is given - combined with `rule` to synthesize a fix request."
+          },
+          "rule": {
+            "type": "string",
+            "description": "Rule / issue-id prefix (e.g. \"unused-dependency\", \"cycle-detected\"). Required when no `issue_id` is given."
+          },
+          "severity": {
+            "type": "string",
+            "enum": [
+              "info",
+              "warning",
+              "error"
+            ],
+            "description": "Optional. When synthesizing via file+rule, sets the severity for the suggestion. Default: warning."
+          }
+        }
+      }
+    },
+    {
+      "name": "projscan_explain_issue",
+      "description": "Deep-dive on a single open issue: severity, surrounding code excerpt, other issues touching the same file, similar fixes from git log (commit messages that mention this rule), and the structured fix-action prompt. Use when an agent needs more context than projscan_doctor gives - typically before applying a fix.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "issue_id": {
+            "type": "string",
+            "description": "Issue id from a previous projscan_doctor / projscan_analyze response."
+          }
+        },
+        "required": [
+          "issue_id"
+        ]
+      }
+    },
+    {
+      "name": "projscan_search",
+      "description": "Ranked search across the project. Lexical (BM25) by default; optional semantic (vector) and hybrid (RRF fusion) modes available when the @xenova/transformers peer dependency is installed. Scope controls what to search: \"auto\"/\"content\" (ranked content matches with excerpts), \"symbols\" (exported names), \"files\" (path substring).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "Search string. Multi-word queries are treated as OR across BM25 terms; semantic mode embeds the full query."
+          },
+          "scope": {
+            "type": "string",
+            "description": "What to search over: \"auto\" (= content), \"symbols\", \"files\", \"content\".",
+            "enum": [
+              "auto",
+              "symbols",
+              "files",
+              "content"
+            ]
+          },
+          "mode": {
+            "type": "string",
+            "description": "\"lexical\" (default, BM25) | \"semantic\" (embeddings, requires peer dep) | \"hybrid\" (BM25 + semantic via reciprocal rank fusion). Ignored for \"symbols\" and \"files\" scopes.",
+            "enum": [
+              "lexical",
+              "semantic",
+              "hybrid"
+            ]
+          },
+          "limit": {
+            "type": "number",
+            "description": "Max matches returned (default 30)."
+          },
+          "max_tokens": {
+            "type": "number",
+            "description": "Cap the response to roughly this many tokens."
+          },
+          "package": {
+            "type": "string",
+            "description": "Optional. Workspace package name (from projscan_workspaces) to scope results to one package only."
+          }
+        },
+        "required": [
+          "query"
+        ]
+      }
+    }
+  ]
+}