prinfer 0.5.2 → 0.6.0

package/README.md

@@ -6,7 +6,8 @@
 
 **Typehints for your AI agent.**
 
-prinfer gives AI coding assistants the ability to inspect TypeScript's inferred types — so they can write cleaner code without redundant type annotations.
+Give AI coding assistant the ability to inspect TypeScript's inferred types mimicking the IDE's hover behavior.
+so they can write cleaner code without redundant type annotations.
 
 ## Why?
 
@@ -40,13 +41,15 @@ prinfer setup
 
 ### MCP Server (`prinfer-mcp`)
 
-Your agent gets an `infer_type` tool to check what TypeScript infers:
+Your agent gets a `hover` tool to check what TypeScript infers at any position:
 
 ```
-infer_type(file: "src/utils.ts", name: "myFunction")
-infer_type(file: "src/utils.ts", name: "commandResult", line: 75)
+hover(file: "src/utils.ts", line: 75, column: 10)
+hover(file: "src/utils.ts", line: 75, column: 10, include_docs: true)
 ```
 
+The position-based API matches IDE behavior and returns instantiated generic types at call sites.
+
 ### Claude Skill (`~/.claude/skills/prefer-infer.md`)
 
 A coding guideline that encourages your agent to:
@@ -55,22 +58,16 @@ A coding guideline that encourages your agent to:
 - Use prinfer to verify types before adding redundant hints
 - Write idiomatic TypeScript
 
-Plus a `/check-type` command for quick lookups.
+Plus a `/hover` command for quick lookups.
 
 ## Manual Setup
 
 If `prinfer setup` doesn't work, configure manually:
 
-**1. Add MCP server** to `~/.claude/settings.json`:
+**1. Add MCP server** using the Claude CLI:
 
-```json
-{
-  "mcpServers": {
-    "prinfer": {
-      "command": "prinfer-mcp"
-    }
-  }
-}
+```bash
+claude mcp add prinfer node /path/to/node_modules/prinfer/dist/mcp.js
 ```
 
 **2. Create skill file** at `~/.claude/skills/prefer-infer.md` with content from [prefer-infer.md](https://github.com/clockblocker/prinfer/blob/master/src/postinstall.ts#L10-L42)
@@ -80,8 +77,9 @@ If `prinfer setup` doesn't work, configure manually:
 prinfer also works as a standalone CLI:
 
 ```bash
-prinfer src/utils.ts myFunction
-prinfer src/utils.ts:75 commandResult
+prinfer src/utils.ts:75:10
+prinfer src/utils.ts:75:10 --docs
+prinfer src/utils.ts:75:10 --project ./tsconfig.json
 ```
 
 Output:
@@ -89,18 +87,25 @@ Output:
 ```
 (x: number, y: string) => boolean
 returns: boolean
+name: myFunction
+kind: function
+docs: Adds two numbers together.
 ```
 
 ## Programmatic API
 
 ```typescript
-import { inferType } from "prinfer";
+import { hover } from "prinfer";
+
+const result = hover("./src/utils.ts", 75, 10);
+// => { signature: "(x: number, y: string) => boolean", returnType: "boolean", line: 75, column: 10, kind: "function", name: "myFunction" }
 
-const result = inferType("./src/utils.ts", "myFunction");
-// => { signature: "(x: number, y: string) => boolean", returnType: "boolean", line: 4 }
+// With documentation
+const result2 = hover("./src/utils.ts", 75, 10, { include_docs: true });
+// => { ..., documentation: "Adds two numbers together." }
 
-// With line number for disambiguation
-const result2 = inferType("./src/utils.ts", "commandResult", { line: 75 });
+// With custom tsconfig
+const result3 = hover("./src/utils.ts", 75, 10, { project: "./tsconfig.json" });
 ```
 
 ## Requirements

package/dist/cli.cjs

@@ -24,6 +24,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/cli.ts
+var import_node_child_process = require("child_process");
 var import_node_fs2 = __toESM(require("fs"), 1);
 var import_node_os = __toESM(require("os"), 1);
 var import_node_path3 = __toESM(require("path"), 1);
@@ -71,66 +72,203 @@ function loadProgram(entryFileAbs, project) {
 function isArrowOrFnExpr(n) {
   return !!n && (import_typescript.default.isArrowFunction(n) || import_typescript.default.isFunctionExpression(n));
 }
-function nodeNameText(n) {
-  if (!n) return void 0;
-  if (import_typescript.default.isIdentifier(n)) return n.text;
-  if (import_typescript.default.isStringLiteral(n)) return n.text;
-  if (import_typescript.default.isNumericLiteral(n)) return n.text;
-  return void 0;
-}
-function isFunctionLikeNamed(node, name) {
-  if (import_typescript.default.isFunctionDeclaration(node) && node.name?.text === name) return true;
-  if (import_typescript.default.isVariableDeclaration(node) && import_typescript.default.isIdentifier(node.name) && node.name.text === name) {
-    return isArrowOrFnExpr(node.initializer);
-  }
-  if ((import_typescript.default.isMethodDeclaration(node) || import_typescript.default.isMethodSignature(node)) && nodeNameText(node.name) === name) {
-    return true;
-  }
-  if (import_typescript.default.isPropertyAssignment(node) && nodeNameText(node.name) === name) {
-    return isArrowOrFnExpr(node.initializer);
+function findSmallestNodeAtPosition(sourceFile, position) {
+  let result;
+  function visit(node) {
+    const start = node.getStart(sourceFile);
+    const end = node.getEnd();
+    if (position < start || position >= end) {
+      return;
+    }
+    if (!result || node.getWidth(sourceFile) <= result.getWidth(sourceFile)) {
+      result = node;
+    }
+    import_typescript.default.forEachChild(node, visit);
   }
-  return false;
+  visit(sourceFile);
+  return result;
 }
-function isVariableNamed(node, name) {
-  if (import_typescript.default.isVariableDeclaration(node) && import_typescript.default.isIdentifier(node.name) && node.name.text === name) {
+function findHoverableAncestor(sourceFile, position) {
+  const smallestNode = findSmallestNodeAtPosition(sourceFile, position);
+  if (!smallestNode) return void 0;
+  let bestMatch = smallestNode;
+  function visit(n) {
+    const start = n.getStart(sourceFile);
+    const end = n.getEnd();
+    if (position < start || position >= end) {
+      return false;
+    }
+    if (import_typescript.default.isCallExpression(n)) {
+      const expr = n.expression;
+      if (import_typescript.default.isIdentifier(expr)) {
+        if (position >= expr.getStart(sourceFile) && position < expr.getEnd()) {
+          bestMatch = n;
+        }
+      } else if (import_typescript.default.isPropertyAccessExpression(expr)) {
+        if (position >= expr.name.getStart(sourceFile) && position < expr.name.getEnd()) {
+          bestMatch = n;
+        }
+      }
+    }
+    if (import_typescript.default.isFunctionDeclaration(n) && n.name) {
+      if (position >= n.name.getStart(sourceFile) && position < n.name.getEnd()) {
+        bestMatch = n;
+      }
+    }
+    if (import_typescript.default.isVariableDeclaration(n) && import_typescript.default.isIdentifier(n.name)) {
+      if (position >= n.name.getStart(sourceFile) && position < n.name.getEnd()) {
+        bestMatch = n;
+      }
+    }
+    if ((import_typescript.default.isMethodDeclaration(n) || import_typescript.default.isMethodSignature(n)) && import_typescript.default.isIdentifier(n.name)) {
+      if (position >= n.name.getStart(sourceFile) && position < n.name.getEnd()) {
+        bestMatch = n;
+      }
+    }
+    if (import_typescript.default.isClassDeclaration(n) && n.name) {
+      if (position >= n.name.getStart(sourceFile) && position < n.name.getEnd()) {
+        bestMatch = n;
+      }
+    }
+    if (import_typescript.default.isInterfaceDeclaration(n) && n.name) {
+      if (position >= n.name.getStart(sourceFile) && position < n.name.getEnd()) {
+        bestMatch = n;
+      }
+    }
+    import_typescript.default.forEachChild(n, visit);
     return true;
   }
-  return false;
-}
-function isNamedNode(node, name) {
-  return isFunctionLikeNamed(node, name) || isVariableNamed(node, name);
+  visit(sourceFile);
+  return bestMatch;
 }
-function getLineNumber(sourceFile, node) {
-  const { line } = sourceFile.getLineAndCharacterOfPosition(
-    node.getStart(sourceFile)
+function findNodeAtPosition(sourceFile, line, column) {
+  const lineCount = sourceFile.getLineStarts().length;
+  if (line < 1 || line > lineCount) {
+    return void 0;
+  }
+  const lineStart = sourceFile.getLineStarts()[line - 1];
+  const lineEnd = line < lineCount ? sourceFile.getLineStarts()[line] : sourceFile.getEnd();
+  const lineLength = lineEnd - lineStart;
+  if (column < 1 || column > lineLength + 1) {
+    return void 0;
+  }
+  const position = sourceFile.getPositionOfLineAndCharacter(
+    line - 1,
+    column - 1
   );
-  return line + 1;
+  return findHoverableAncestor(sourceFile, position);
 }
-function findNodeByNameAndLine(sourceFile, name, line) {
-  let found;
-  const visit = (node) => {
-    if (found) return;
-    if (isNamedNode(node, name)) {
-      if (line !== void 0) {
-        const nodeLine = getLineNumber(sourceFile, node);
-        if (nodeLine === line) {
-          found = node;
-          return;
-        }
-      } else {
-        found = node;
-        return;
-      }
+function getSymbolKind(node) {
+  if (import_typescript.default.isFunctionDeclaration(node)) return "function";
+  if (import_typescript.default.isArrowFunction(node)) return "function";
+  if (import_typescript.default.isFunctionExpression(node)) return "function";
+  if (import_typescript.default.isMethodDeclaration(node)) return "method";
+  if (import_typescript.default.isMethodSignature(node)) return "method";
+  if (import_typescript.default.isVariableDeclaration(node)) {
+    const init = node.initializer;
+    if (init && (import_typescript.default.isArrowFunction(init) || import_typescript.default.isFunctionExpression(init))) {
+      return "function";
     }
-    import_typescript.default.forEachChild(node, visit);
-  };
-  visit(sourceFile);
-  return found;
+    return "variable";
+  }
+  if (import_typescript.default.isParameter(node)) return "parameter";
+  if (import_typescript.default.isPropertyDeclaration(node)) return "property";
+  if (import_typescript.default.isPropertySignature(node)) return "property";
+  if (import_typescript.default.isPropertyAccessExpression(node)) return "property";
+  if (import_typescript.default.isCallExpression(node)) return "call";
+  if (import_typescript.default.isTypeAliasDeclaration(node)) return "type";
+  if (import_typescript.default.isInterfaceDeclaration(node)) return "interface";
+  if (import_typescript.default.isClassDeclaration(node)) return "class";
+  if (import_typescript.default.isIdentifier(node)) return "identifier";
+  return "unknown";
 }
-function getTypeInfo(program, node, sourceFile) {
+function getNodeName(node) {
+  if (import_typescript.default.isFunctionDeclaration(node) && node.name) {
+    return node.name.text;
+  }
+  if (import_typescript.default.isVariableDeclaration(node) && import_typescript.default.isIdentifier(node.name)) {
+    return node.name.text;
+  }
+  if ((import_typescript.default.isMethodDeclaration(node) || import_typescript.default.isMethodSignature(node)) && import_typescript.default.isIdentifier(node.name)) {
+    return node.name.text;
+  }
+  if (import_typescript.default.isPropertyAccessExpression(node)) {
+    return node.name.text;
+  }
+  if (import_typescript.default.isCallExpression(node)) {
+    const expr = node.expression;
+    if (import_typescript.default.isIdentifier(expr)) return expr.text;
+    if (import_typescript.default.isPropertyAccessExpression(expr)) return expr.name.text;
+  }
+  if (import_typescript.default.isParameter(node) && import_typescript.default.isIdentifier(node.name)) {
+    return node.name.text;
+  }
+  if (import_typescript.default.isIdentifier(node)) {
+    return node.text;
+  }
+  if (import_typescript.default.isTypeAliasDeclaration(node) || import_typescript.default.isInterfaceDeclaration(node) || import_typescript.default.isClassDeclaration(node)) {
+    return node.name?.text;
+  }
+  return void 0;
+}
+function getDocumentation(checker, symbol) {
+  if (!symbol) return void 0;
+  const docs = symbol.getDocumentationComment(checker);
+  if (docs.length === 0) return void 0;
+  return import_typescript.default.displayPartsToString(docs);
+}
+function getHoverInfo(program, node, sourceFile, includeDocs) {
   const checker = program.getTypeChecker();
-  const sf = sourceFile ?? node.getSourceFile();
-  const line = getLineNumber(sf, node);
+  const sf = sourceFile;
+  const { line, character } = sf.getLineAndCharacterOfPosition(
+    node.getStart(sf)
+  );
+  const flags = import_typescript.default.TypeFormatFlags.NoTruncation;
+  const kind = getSymbolKind(node);
+  const name = getNodeName(node);
+  let symbol;
+  if (import_typescript.default.isCallExpression(node)) {
+    const expr = node.expression;
+    if (import_typescript.default.isPropertyAccessExpression(expr)) {
+      symbol = checker.getSymbolAtLocation(expr.name);
+    } else {
+      symbol = checker.getSymbolAtLocation(expr);
+    }
+  } else {
+    const nodeWithName2 = node;
+    if (nodeWithName2.name) {
+      symbol = checker.getSymbolAtLocation(nodeWithName2.name);
+    } else {
+      symbol = checker.getSymbolAtLocation(node);
+    }
+  }
+  const documentation = includeDocs ? getDocumentation(checker, symbol) : void 0;
+  if (import_typescript.default.isCallExpression(node)) {
+    const sig2 = checker.getResolvedSignature(node);
+    if (sig2) {
+      const signature = checker.signatureToString(sig2, void 0, flags);
+      const ret = checker.getReturnTypeOfSignature(sig2);
+      const returnType = checker.typeToString(ret, void 0, flags);
+      return {
+        signature,
+        returnType,
+        line: line + 1,
+        column: character + 1,
+        documentation,
+        kind,
+        name
+      };
+    }
+    const t2 = checker.getTypeAtLocation(node);
+    return {
+      signature: checker.typeToString(t2, void 0, flags),
+      line: line + 1,
+      column: character + 1,
+      documentation,
+      kind,
+      name
+    };
+  }
   let sig;
   if (import_typescript.default.isFunctionDeclaration(node) || import_typescript.default.isMethodDeclaration(node)) {
     sig = checker.getSignatureFromDeclaration(node) ?? void 0;
@@ -145,26 +283,39 @@ function getTypeInfo(program, node, sourceFile) {
   } else if (import_typescript.default.isMethodSignature(node)) {
     sig = checker.getSignatureFromDeclaration(node) ?? void 0;
   }
-  const flags = import_typescript.default.TypeFormatFlags.NoTruncation;
   if (sig) {
     const signature = checker.signatureToString(sig, void 0, flags);
     const ret = checker.getReturnTypeOfSignature(sig);
     const returnType = checker.typeToString(ret, void 0, flags);
-    return { signature, returnType, line };
+    return {
+      signature,
+      returnType,
+      line: line + 1,
+      column: character + 1,
+      documentation,
+      kind,
+      name
+    };
   }
   const nodeWithName = node;
-  let nameNode = node;
+  let targetNode = node;
   if (nodeWithName.name && import_typescript.default.isIdentifier(nodeWithName.name)) {
-    nameNode = nodeWithName.name;
+    targetNode = nodeWithName.name;
   }
-  const t = checker.getTypeAtLocation(nameNode);
-  return { signature: checker.typeToString(t, void 0, flags), line };
+  const t = checker.getTypeAtLocation(targetNode);
+  return {
+    signature: checker.typeToString(t, void 0, flags),
+    line: line + 1,
+    column: character + 1,
+    documentation,
+    kind,
+    name
+  };
 }
 
 // src/index.ts
-function inferType(file, name, options) {
-  const opts = typeof options === "string" ? { project: options } : options ?? {};
-  const { line, project } = opts;
+function hover(file, line, column, options) {
+  const { project, include_docs = false } = options ?? {};
   const entryFileAbs = import_node_path2.default.resolve(process.cwd(), file);
   if (!import_node_fs.default.existsSync(entryFileAbs)) {
     throw new Error(`File not found: ${entryFileAbs}`);
@@ -176,58 +327,69 @@ function inferType(file, name, options) {
       `Could not load source file into the program (check tsconfig include/exclude): ${entryFileAbs}`
     );
   }
-  const node = findNodeByNameAndLine(sourceFile, name, line);
+  const node = findNodeAtPosition(sourceFile, line, column);
   if (!node) {
-    const lineInfo = line !== void 0 ? ` at line ${line}` : "";
-    throw new Error(
-      `No symbol named "${name}"${lineInfo} found in ${entryFileAbs}`
-    );
+    throw new Error(`No symbol found at ${entryFileAbs}:${line}:${column}`);
   }
-  return getTypeInfo(program, node, sourceFile);
+  return getHoverInfo(program, node, sourceFile, include_docs);
 }
 
 // src/cli.ts
+var import_meta = {};
 var HELP = `
 prinfer - TypeScript type inference inspection tool
 
 Usage:
-  prinfer <file.ts>[:<line>] <name> [--project <tsconfig.json>]
+  prinfer <file.ts>:<line>:<column> [--docs] [--project <tsconfig.json>]
   prinfer setup
 
 Commands:
   setup                Install MCP server and skill for Claude Code
 
 Arguments:
-  file.ts              Path to the TypeScript file
-  :line                Optional line number to narrow search (e.g., file.ts:75)
-  name                 Name of the function/variable to inspect
+  file.ts:line:column  Path to TypeScript file with 1-based line and column
 
 Options:
+  --docs, -d           Include JSDoc/TSDoc documentation
   --project, -p        Path to tsconfig.json (optional)
   --help, -h           Show this help message
 
 Examples:
-  prinfer src/utils.ts myFunction
-  prinfer src/utils.ts:75 commandResult
+  prinfer src/utils.ts:75:10
+  prinfer src/utils.ts:75:10 --docs
+  prinfer src/utils.ts:75:10 --project ./tsconfig.json
   prinfer setup
 `.trim();
 var MANUAL_SETUP = `
 Manual setup instructions:
 
-1. Add MCP server to ~/.claude/settings.json:
-
-   {
-     "mcpServers": {
-       "prinfer": {
-         "command": "prinfer-mcp"
-       }
-     }
-   }
+1. Add MCP server:
+   Run: claude mcp add prinfer node /path/to/prinfer-mcp
 
 2. Create skill file at ~/.claude/skills/prefer-infer.md:
-
    See https://github.com/clockblocker/prinfer for skill content.
 `.trim();
+function getMcpBinaryPath() {
+  const thisScript = new URL(import_meta.url).pathname;
+  return import_node_path3.default.join(import_node_path3.default.dirname(thisScript), "mcp.js");
+}
+function installMcpServer() {
+  try {
+    const mcpPath = getMcpBinaryPath();
+    try {
+      (0, import_node_child_process.execSync)("claude mcp remove prinfer", { stdio: "pipe" });
+    } catch {
+    }
+    (0, import_node_child_process.execSync)(`claude mcp add prinfer node ${mcpPath}`, {
+      stdio: "inherit"
+    });
+    console.log("[ok] Added prinfer MCP server");
+    return true;
+  } catch (err) {
+    console.error(`[error] MCP setup failed: ${err.message}`);
+    return false;
+  }
+}
 var SKILL_CONTENT = `# TypeScript Type Inference (prinfer)
 
 ## Coding Guideline
@@ -241,26 +403,26 @@ When writing TypeScript code, prefer relying on type inference over explicit typ
   - The type serves as documentation for complex structures
   - You're defining a public API contract
 
-Use the \`prinfer\` MCP tool (\`infer_type\`) to verify what TypeScript infers before adding explicit types.
+Use the \`prinfer\` MCP tool (\`hover\`) to verify what TypeScript infers before adding explicit types.
 
 ## Commands
 
-### /check-type
+### /hover
 
-Check the inferred type of a TypeScript symbol.
+Check the inferred type at a specific position in a TypeScript file.
 
-Usage: \`/check-type <file>:<line> <name>\` or \`/check-type <file> <name>\`
+Usage: \`/hover <file>:<line>:<column>\`
 
 Examples:
-- \`/check-type src/utils.ts:75 commandResult\`
-- \`/check-type src/utils.ts myFunction\`
+- \`/hover src/utils.ts:75:10\`
+- \`/hover src/utils.ts:42:5\`
 
-<command-name>check-type</command-name>
+<command-name>hover</command-name>
 
-Use the \`infer_type\` MCP tool to check the type:
-1. Parse the arguments to extract file, optional line number, and symbol name
-2. Call \`infer_type(file, name, line?)\`
-3. Report the inferred signature and return type
+Use the \`hover\` MCP tool to check the type:
+1. Parse the arguments to extract file, line, and column
+2. Call \`hover(file, line, column, { include_docs: true })\`
+3. Report the inferred signature, return type, and documentation
 `;
 function runSetup() {
   const homeDir = import_node_os.default.homedir();
@@ -271,33 +433,8 @@ function runSetup() {
     console.error(MANUAL_SETUP);
     process.exit(1);
   }
-  let mcpOk = false;
+  const mcpOk = installMcpServer();
   let skillOk = false;
-  const configFile = import_node_path3.default.join(claudeDir, "settings.json");
-  try {
-    let config = {};
-    if (import_node_fs2.default.existsSync(configFile)) {
-      config = JSON.parse(import_node_fs2.default.readFileSync(configFile, "utf-8"));
-    }
-    if (config.mcpServers?.prinfer) {
-      console.log("[ok] MCP server already configured");
-      mcpOk = true;
-    } else {
-      config.mcpServers = config.mcpServers || {};
-      config.mcpServers.prinfer = { command: "prinfer-mcp" };
-      import_node_fs2.default.writeFileSync(
-        configFile,
-        `${JSON.stringify(config, null, 2)}
-`
-      );
-      console.log("[ok] Added MCP server to settings.json");
-      mcpOk = true;
-    }
-  } catch (err) {
-    console.error(
-      `[error] Failed to configure MCP server: ${err.message}`
-    );
-  }
   const skillsDir = import_node_path3.default.join(claudeDir, "skills");
   const skillFile = import_node_path3.default.join(skillsDir, "prefer-infer.md");
   try {
@@ -327,12 +464,16 @@ function runSetup() {
     process.exit(1);
   }
 }
-function parseFileArg(arg) {
-  const match = arg.match(/^(.+):(\d+)$/);
+function parsePositionArg(arg) {
+  const match = arg.match(/^(.+):(\d+):(\d+)$/);
   if (match) {
-    return { file: match[1], line: Number.parseInt(match[2], 10) };
+    return {
+      file: match[1],
+      line: Number.parseInt(match[2], 10),
+      column: Number.parseInt(match[3], 10)
+    };
   }
-  return { file: arg };
+  return null;
 }
 function parseArgs(argv) {
   const args = argv.slice(2);
@@ -344,16 +485,17 @@ function parseArgs(argv) {
     runSetup();
     return null;
   }
-  const fileArg = args[0];
-  const name = args[1];
-  if (!fileArg || !name) {
+  const positionArg = args[0];
+  const parsed = parsePositionArg(positionArg);
+  if (!parsed) {
     console.error(
-      "Error: Both <file> and <name> arguments are required.\n"
+      "Error: Position argument must be in format <file>:<line>:<column>\n"
     );
     console.log(HELP);
     process.exit(1);
   }
-  const { file, line } = parseFileArg(fileArg);
+  const { file, line, column } = parsed;
+  const includeDocs = args.includes("--docs") || args.includes("-d");
   let project;
   const projectIdx = args.findIndex((a) => a === "--project" || a === "-p");
   if (projectIdx >= 0) {
@@ -364,7 +506,7 @@ function parseArgs(argv) {
       process.exit(1);
     }
   }
-  return { file, name, line, project };
+  return { file, line, column, includeDocs, project };
 }
 function main() {
   const options = parseArgs(process.argv);
@@ -372,14 +514,21 @@ function main() {
     process.exit(0);
   }
   try {
-    const result = inferType(options.file, options.name, {
-      line: options.line,
+    const result = hover(options.file, options.line, options.column, {
+      include_docs: options.includeDocs,
       project: options.project
     });
     console.log(result.signature);
     if (result.returnType) {
       console.log("returns:", result.returnType);
     }
+    if (result.name) {
+      console.log("name:", result.name);
+    }
+    console.log("kind:", result.kind);
+    if (result.documentation) {
+      console.log("docs:", result.documentation);
+    }
   } catch (error) {
     console.error(error.message);
     process.exit(1);