prinfer 0.5.3 → 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,7 +58,7 @@ 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
 
@@ -74,8 +77,9 @@ claude mcp add prinfer node /path/to/node_modules/prinfer/dist/mcp.js
 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:
@@ -83,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

@@ -72,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 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 getTypeInfo(program, node, sourceFile) {
+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;
@@ -146,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}`);
@@ -177,14 +327,11 @@ 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
@@ -193,24 +340,24 @@ 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 = `
@@ -256,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();
@@ -317,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);
@@ -334,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) {
@@ -354,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);
@@ -362,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);