smart-context-mcp 0.8.0

package/src/tools/smart-read/code.js

@@ -0,0 +1,216 @@
+import path from 'node:path';
+import ts from 'typescript';
+import { joinSections, toUniqueLines, truncateSection } from './shared.js';
+
+const scriptKindByExtension = {
+  '.js': ts.ScriptKind.JS,
+  '.jsx': ts.ScriptKind.JSX,
+  '.ts': ts.ScriptKind.TS,
+  '.tsx': ts.ScriptKind.TSX,
+  '.mjs': ts.ScriptKind.JS,
+  '.cjs': ts.ScriptKind.JS,
+};
+
+const getNodeName = (node) => {
+  if (node.name && ts.isIdentifier(node.name)) {
+    return node.name.text;
+  }
+
+  return 'anonymous';
+};
+
+const formatImport = (statement) => {
+  const moduleName = statement.moduleSpecifier.getText();
+  const clause = statement.importClause;
+
+  if (!clause) {
+    return `import ${moduleName}`;
+  }
+
+  const parts = [];
+
+  if (clause.name) {
+    parts.push(clause.name.text);
+  }
+
+  if (clause.namedBindings) {
+    if (ts.isNamespaceImport(clause.namedBindings)) {
+      parts.push(`* as ${clause.namedBindings.name.text}`);
+    } else {
+      const names = clause.namedBindings.elements.map((element) => {
+        if (element.propertyName) {
+          return `${element.propertyName.text} as ${element.name.text}`;
+        }
+
+        return element.name.text;
+      });
+      parts.push(`{ ${names.join(', ')} }`);
+    }
+  }
+
+  return `import ${parts.join(', ')} from ${moduleName}`;
+};
+
+const formatDeclarationName = (name) => {
+  if (ts.isIdentifier(name)) {
+    return name.text;
+  }
+
+  return name.getText();
+};
+
+const collectVariableNames = (declarationList) => declarationList.declarations.map((declaration) => formatDeclarationName(declaration.name));
+
+const formatTopLevelStatement = (statement, sourceFile) => {
+  const exported = statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+  const prefix = exported ? 'export ' : '';
+
+  if (ts.isImportDeclaration(statement)) {
+    return formatImport(statement);
+  }
+
+  if (ts.isFunctionDeclaration(statement)) {
+    return `${prefix}function ${getNodeName(statement)}()`;
+  }
+
+  if (ts.isClassDeclaration(statement)) {
+    return `${prefix}class ${getNodeName(statement)}`;
+  }
+
+  if (ts.isInterfaceDeclaration(statement)) {
+    return `${prefix}interface ${statement.name.text}`;
+  }
+
+  if (ts.isTypeAliasDeclaration(statement)) {
+    return `${prefix}type ${statement.name.text}`;
+  }
+
+  if (ts.isEnumDeclaration(statement)) {
+    return `${prefix}enum ${statement.name.text}`;
+  }
+
+  if (ts.isVariableStatement(statement)) {
+    const declarationKind = statement.declarationList.flags & ts.NodeFlags.Const
+      ? 'const'
+      : statement.declarationList.flags & ts.NodeFlags.Let
+        ? 'let'
+        : 'var';
+    return `${prefix}${declarationKind} ${collectVariableNames(statement.declarationList).join(', ')}`;
+  }
+
+  if (ts.isExportAssignment(statement)) {
+    return `export default ${statement.expression.getText(sourceFile)}`;
+  }
+
+  return statement.getText(sourceFile).split('\n')[0];
+};
+
+const collectHooks = (sourceFile) => {
+  const hooks = new Set();
+
+  const visit = (node) => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && /^use[A-Z]/.test(node.expression.text)) {
+      hooks.add(node.expression.text);
+    }
+
+    ts.forEachChild(node, visit);
+  };
+
+  ts.forEachChild(sourceFile, visit);
+
+  return [...hooks].sort();
+};
+
+const parseSource = (fullPath, content) => {
+  const extension = path.extname(fullPath).toLowerCase();
+  const scriptKind = scriptKindByExtension[extension] ?? ts.ScriptKind.TS;
+  return ts.createSourceFile(fullPath, content, ts.ScriptTarget.Latest, true, scriptKind);
+};
+
+const getDeclarationName = (statement) => {
+  if (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement) ||
+      ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement) ||
+      ts.isEnumDeclaration(statement)) {
+    return statement.name?.text ?? null;
+  }
+
+  if (ts.isVariableStatement(statement)) {
+    return statement.declarationList.declarations.map((d) => formatDeclarationName(d.name));
+  }
+
+  return null;
+};
+
+const matchesSymbolName = (statement, symbolName) => {
+  const name = getDeclarationName(statement);
+  if (Array.isArray(name)) return name.includes(symbolName);
+  return name === symbolName;
+};
+
+const nodeToNumberedLines = (node, sourceFile, content) => {
+  const startPos = node.getStart(sourceFile);
+  const endPos = node.getEnd();
+  const { line: startLine } = sourceFile.getLineAndCharacterOfPosition(startPos);
+  const { line: endLine } = sourceFile.getLineAndCharacterOfPosition(endPos);
+  const lines = content.split('\n').slice(startLine, endLine + 1);
+  return lines.map((l, i) => `${startLine + i + 1}|${l}`).join('\n');
+};
+
+const getNodeIdentifierName = (node) => {
+  if (node.name && ts.isIdentifier(node.name)) return node.name.text;
+  if (node.name && ts.isComputedPropertyName(node.name)) return null;
+  return null;
+};
+
+const findSymbolNode = (node, symbolName) => {
+  if (ts.isMethodDeclaration(node) || ts.isPropertyDeclaration(node) ||
+      ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node)) {
+    if (getNodeIdentifierName(node) === symbolName) return node;
+  }
+
+  if (ts.isPropertyAssignment(node) || ts.isShorthandPropertyAssignment(node)) {
+    if (getNodeIdentifierName(node) === symbolName) return node;
+  }
+
+  if (ts.isMethodSignature(node) || ts.isPropertySignature(node)) {
+    if (getNodeIdentifierName(node) === symbolName) return node;
+  }
+
+  let found = null;
+  ts.forEachChild(node, (child) => {
+    if (!found) found = findSymbolNode(child, symbolName);
+  });
+  return found;
+};
+
+export const extractCodeSymbol = (fullPath, content, symbolName) => {
+  const sourceFile = parseSource(fullPath, content);
+
+  for (const statement of sourceFile.statements) {
+    if (matchesSymbolName(statement, symbolName)) {
+      return nodeToNumberedLines(statement, sourceFile, content);
+    }
+  }
+
+  const nested = findSymbolNode(sourceFile, symbolName);
+  if (nested) {
+    return nodeToNumberedLines(nested, sourceFile, content);
+  }
+
+  return `Symbol not found: ${symbolName}`;
+};
+
+export const summarizeCode = (fullPath, content, mode) => {
+  const sourceFile = parseSource(fullPath, content);
+  const topLevel = sourceFile.statements.map((statement) => formatTopLevelStatement(statement, sourceFile));
+  const hooks = collectHooks(sourceFile);
+
+  if (mode === 'signatures') {
+    return truncateSection('# Signatures', toUniqueLines(topLevel), 4000);
+  }
+
+  return joinSections([
+    truncateSection('# Outline', toUniqueLines(topLevel), 4000),
+    truncateSection('# Hooks', hooks, 1200),
+  ], 5000);
+};

package/src/tools/smart-read/fallback.js

@@ -0,0 +1,23 @@
+import { truncate } from '../../utils/text.js';
+
+export const summarizeFallback = (content, mode) => {
+  const lines = content.split('\n');
+  const matches = lines.filter((line) => {
+    const trimmed = line.trim();
+
+    return (
+      trimmed.startsWith('import ') ||
+      trimmed.startsWith('export ') ||
+      trimmed.includes('function ') ||
+      trimmed.includes('const ') ||
+      trimmed.includes('return (') ||
+      trimmed.includes('class ') ||
+      trimmed.includes('def ') ||
+      trimmed.includes('resource ') ||
+      trimmed.includes('FROM ') ||
+      trimmed.includes('fn ')
+    );
+  });
+
+  return truncate(matches.join('\n') || content, mode === 'signatures' ? 4000 : 5000);
+};

package/src/tools/smart-read/python.js

@@ -0,0 +1,178 @@
+import { joinSections, toUniqueLines, truncateSection } from './shared.js';
+
+export const extractPythonSymbol = (content, symbolName) => {
+  const lines = content.split('\n');
+  let startIdx = -1;
+  let baseIndent = -1;
+
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    const indent = lines[i].length - lines[i].trimStart().length;
+
+    const match = trimmed.match(/^(?:async\s+)?(?:def|class)\s+([A-Za-z_][A-Za-z0-9_]*)/);
+    if (match && match[1] === symbolName) {
+      startIdx = i;
+      baseIndent = indent;
+      break;
+    }
+  }
+
+  if (startIdx === -1) return `Symbol not found: ${symbolName}`;
+
+  let endIdx = startIdx + 1;
+  while (endIdx < lines.length) {
+    const line = lines[endIdx];
+    const trimmed = line.trim();
+    if (trimmed && !trimmed.startsWith('#')) {
+      const indent = line.length - line.trimStart().length;
+      if (indent <= baseIndent) break;
+    }
+    endIdx++;
+  }
+
+  const slice = lines.slice(startIdx, endIdx);
+  return slice.map((l, i) => `${startIdx + i + 1}|${l}`).join('\n');
+};
+
+export const summarizePython = (content, mode) => {
+  const lines = content.split('\n');
+  const imports = [];
+  const topLevelDefs = [];
+  const classNames = [];
+  const classMethods = new Map();
+  const constants = [];
+  let currentClass = null;
+  let currentClassIndent = -1;
+  let pendingDecorators = 0;
+  let pendingHeader = null;
+
+  const normalizeHeader = (parts) => parts.join(' ').replace(/\s+/g, ' ').trim();
+
+  const finalizePendingHeader = () => {
+    if (!pendingHeader) {
+      return;
+    }
+
+    const header = normalizeHeader(pendingHeader.parts);
+
+    if (pendingHeader.kind === 'class') {
+      const classMatch = header.match(/^class\s+([A-Za-z_][A-Za-z0-9_]*)\s*(?:\((.*?)\))?\s*:/);
+      const className = classMatch?.[1] ?? header.replace(/:$/, '');
+      const bases = classMatch?.[2] ? `(${classMatch[2].trim()})` : '';
+      const prefix = pendingHeader.decorated ? '@decorated ' : '';
+      const classLabel = `${prefix}class ${className}${bases}`;
+
+      classNames.push(classLabel);
+      if (!classMethods.has(classLabel)) {
+        classMethods.set(classLabel, []);
+      }
+      currentClass = classLabel;
+      currentClassIndent = pendingHeader.indent;
+    }
+
+    if (pendingHeader.kind === 'function') {
+      const functionMatch = header.match(/^(async\s+def|def)\s+([A-Za-z_][A-Za-z0-9_]*)\s*\((.*)\)\s*(?:->\s*([^:]+))?\s*:/);
+      const functionKind = functionMatch?.[1] ?? 'def';
+      const functionName = functionMatch?.[2] ?? 'anonymous';
+      const params = (functionMatch?.[3] ?? '').trim();
+      const returnType = functionMatch?.[4]?.trim();
+      const prefix = pendingHeader.decorated ? '@decorated ' : '';
+      const asyncPrefix = functionKind === 'async def' ? 'async ' : '';
+      const returnSuffix = returnType ? ` -> ${returnType}` : '';
+      const signature = `${prefix}${asyncPrefix}def ${functionName}(${params})${returnSuffix}`;
+
+      if (currentClass && pendingHeader.indent > currentClassIndent) {
+        classMethods.get(currentClass).push(signature);
+      } else {
+        topLevelDefs.push(signature);
+      }
+    }
+
+    pendingHeader = null;
+    pendingDecorators = 0;
+  };
+
+  for (const rawLine of lines) {
+    const trimmed = rawLine.trim();
+    const indent = rawLine.length - rawLine.trimStart().length;
+
+    if (!trimmed || trimmed.startsWith('#')) {
+      continue;
+    }
+
+    if (pendingHeader) {
+      pendingHeader.parts.push(trimmed);
+      if (trimmed.endsWith(':')) {
+        finalizePendingHeader();
+      }
+      continue;
+    }
+
+    if (currentClass && indent <= currentClassIndent && !trimmed.startsWith('@')) {
+      currentClass = null;
+      currentClassIndent = -1;
+    }
+
+    const importMatch = rawLine.match(/^\s*(import\s+.+|from\s+.+\s+import\s+.+)$/);
+    if (importMatch) {
+      imports.push(importMatch[1].trim());
+      pendingDecorators = 0;
+      continue;
+    }
+
+    if (/^\s*@/.test(rawLine)) {
+      pendingDecorators += 1;
+      continue;
+    }
+
+    if (/^\s*class\s+[A-Za-z_][A-Za-z0-9_]*/.test(rawLine)) {
+      pendingHeader = { kind: 'class', indent, parts: [trimmed], decorated: pendingDecorators > 0 };
+      if (trimmed.endsWith(':')) {
+        finalizePendingHeader();
+      }
+      continue;
+    }
+
+    if (/^\s*(async\s+def|def)\s+[A-Za-z_][A-Za-z0-9_]*\s*\(/.test(rawLine)) {
+      pendingHeader = { kind: 'function', indent, parts: [trimmed], decorated: pendingDecorators > 0 };
+      if (trimmed.endsWith(':')) {
+        finalizePendingHeader();
+      }
+      continue;
+    }
+
+    const constantMatch = rawLine.match(/^\s*([A-Z][A-Z0-9_]+)\s*=/);
+    if (constantMatch) {
+      constants.push(`const ${constantMatch[1]}`);
+    }
+
+    pendingDecorators = 0;
+  }
+
+  finalizePendingHeader();
+
+  const importLines = toUniqueLines(imports, mode === 'signatures' ? 6 : 12);
+  const topLevelLines = toUniqueLines(topLevelDefs, 12);
+  const classLines = toUniqueLines(classNames, 12);
+  const methodLines = [...classMethods.entries()].flatMap(([classLabel, methods]) => {
+    const limitedMethods = toUniqueLines(methods, 8);
+    return limitedMethods.length === 0 ? [classLabel] : [classLabel, ...limitedMethods.map((method) => `  ${method}`)];
+  });
+  const constantLines = toUniqueLines(constants, 12);
+
+  if (mode === 'signatures') {
+    return joinSections([
+      truncateSection('# Classes and methods', methodLines.length > 0 ? methodLines : classLines, 2200),
+      truncateSection('# Top-level definitions', topLevelLines, 900),
+      truncateSection('# Imports', importLines, 700),
+    ], 4000);
+  }
+
+  return joinSections([
+    truncateSection('# Classes and methods', methodLines, 2200),
+    truncateSection('# Classes', classLines, 900),
+    truncateSection('# Top-level definitions', topLevelLines, 1200),
+    truncateSection('# Imports', importLines, 1200),
+    truncateSection('# Constants', constantLines, 800),
+  ], 5000);
+};

package/src/tools/smart-read/shared.js

@@ -0,0 +1,39 @@
+import { truncate, uniqueLines } from '../../utils/text.js';
+
+export const toUniqueLines = (items, limit = Infinity) => uniqueLines(items.join('\n')).split('\n').filter(Boolean).slice(0, limit);
+
+export const truncateSection = (title, lines, maxChars) => {
+  if (lines.length === 0) {
+    return '';
+  }
+
+  return truncate(`${title}\n${lines.join('\n')}`, maxChars);
+};
+
+export const joinSections = (sections, maxChars) => truncate(sections.filter(Boolean).join('\n\n'), maxChars);
+
+export const summarizeJson = (content, mode) => {
+  try {
+    const parsed = JSON.parse(content);
+    const entries = Object.entries(parsed ?? {});
+    const lines = entries.map(([key, value]) => {
+      if (Array.isArray(value)) {
+        return `${key}: array(${value.length})`;
+      }
+
+      if (value && typeof value === 'object') {
+        return `${key}: object(${Object.keys(value).length})`;
+      }
+
+      if (typeof value === 'string') {
+        return `${key}: ${value.slice(0, 48)}`;
+      }
+
+      return `${key}: ${String(value)}`;
+    });
+
+    return truncateSection('# JSON outline', lines, mode === 'signatures' ? 4000 : 5000);
+  } catch {
+    return truncate(content, 4000);
+  }
+};

package/src/tools/smart-read/structured.js

@@ -0,0 +1,72 @@
+import { joinSections, toUniqueLines, truncateSection } from './shared.js';
+
+export const summarizeToml = (content, mode) => {
+  const lines = content.split('\n');
+  const sections = [];
+  const keys = [];
+  let currentSection = 'root';
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+
+    if (!line || line.startsWith('#')) {
+      continue;
+    }
+
+    const sectionMatch = line.match(/^\[\[?([^\]]+)\]\]?$/);
+    if (sectionMatch) {
+      currentSection = sectionMatch[1];
+      sections.push(`[${currentSection}]`);
+      continue;
+    }
+
+    const keyMatch = line.match(/^([A-Za-z0-9_.-]+)\s*=/);
+    if (keyMatch) {
+      keys.push(`${currentSection}.${keyMatch[1]}`);
+    }
+  }
+
+  if (mode === 'signatures') {
+    return truncateSection('# TOML sections', toUniqueLines(sections), 4000);
+  }
+
+  return joinSections([
+    truncateSection('# TOML sections', toUniqueLines(sections), 1800),
+    truncateSection('# Keys', toUniqueLines(keys), 2800),
+  ], 5000);
+};
+
+export const summarizeYaml = (content, mode) => {
+  const lines = content.split('\n');
+  const sections = [];
+  const nestedKeys = [];
+
+  for (const rawLine of lines) {
+    if (!rawLine.trim() || rawLine.trim().startsWith('#')) {
+      continue;
+    }
+
+    const keyMatch = rawLine.match(/^(\s*)([^\s:#][^:]*):/);
+    if (!keyMatch) {
+      continue;
+    }
+
+    const indent = keyMatch[1].length / 2;
+    const key = keyMatch[2].trim();
+
+    if (indent === 0) {
+      sections.push(key);
+    } else {
+      nestedKeys.push(`${'  '.repeat(indent)}${key}`);
+    }
+  }
+
+  if (mode === 'signatures') {
+    return truncateSection('# YAML keys', toUniqueLines(sections), 4000);
+  }
+
+  return joinSections([
+    truncateSection('# YAML top-level', toUniqueLines(sections), 1600),
+    truncateSection('# YAML nested', toUniqueLines(nestedKeys), 2800),
+  ], 5000);
+};

package/src/tools/smart-read-batch.js

@@ -0,0 +1,63 @@
+import { smartRead } from './smart-read.js';
+import { countTokens } from '../tokenCounter.js';
+
+export const smartReadBatch = async ({ files, maxTokens }) => {
+  const results = [];
+  let totalTokens = 0;
+  let totalRawTokens = 0;
+  let filesSkipped = 0;
+
+  for (const item of files) {
+    try {
+      const readResult = await smartRead({
+        filePath: item.path,
+        mode: item.mode,
+        symbol: item.symbol,
+        startLine: item.startLine,
+        endLine: item.endLine,
+        maxTokens: item.maxTokens,
+      });
+
+      const itemTokens = countTokens(readResult.content);
+
+      if (maxTokens && totalTokens + itemTokens > maxTokens && results.length > 0) {
+        filesSkipped = files.length - results.length;
+        break;
+      }
+
+      results.push({
+        filePath: readResult.filePath,
+        mode: readResult.mode,
+        parser: readResult.parser,
+        truncated: readResult.truncated,
+        content: readResult.content,
+        ...(readResult.confidence ? { confidence: readResult.confidence } : {}),
+        ...(readResult.indexHint !== undefined ? { indexHint: readResult.indexHint } : {}),
+        ...(readResult.chosenMode ? { chosenMode: readResult.chosenMode, budgetApplied: true } : {}),
+      });
+
+      totalTokens += itemTokens;
+      totalRawTokens += readResult.metrics?.rawTokens ?? 0;
+    } catch (err) {
+      results.push({
+        filePath: item.path,
+        mode: item.mode ?? 'outline',
+        error: err.message || 'Failed to read file',
+      });
+    }
+  }
+
+  const totalSavingsPct = totalRawTokens > 0
+    ? Math.max(0, Math.round(((totalRawTokens - totalTokens) / totalRawTokens) * 100))
+    : 0;
+
+  return {
+    results,
+    metrics: {
+      totalTokens,
+      filesRead: results.length,
+      filesSkipped,
+      totalSavingsPct,
+    },
+  };
+};