@aprimediet/codewalker 1.0.0 → 1.1.0

package/src/extract/docs.ts

@@ -0,0 +1,169 @@
+/**
+ * Extract leading doc comments from source code.
+ *
+ * Given a source file and the line number of a symbol, walk upward collecting
+ * adjacent comment lines. PURE module — no I/O.
+ */
+
+/**
+ * Extract the doc comment block immediately above a given line in source.
+ * Returns the concatenated text of the comment(s), or "" if none.
+ */
+export function extractDocComment(source: string, symbolLine: number): string {
+  if (symbolLine <= 1) return "";
+
+  const lines = source.split("\n");
+  const parts: string[] = [];
+
+  // Walk upward from the line just above the symbol
+  let i = symbolLine - 2; // 0-based
+  if (i < 0) return "";
+
+  while (i >= 0) {
+    const rawLine = lines[i] as string;
+    const trimmed = rawLine.trim();
+
+    // Blank line stops collection
+    if (!trimmed) break;
+
+    // Line comment (//)
+    if (trimmed.startsWith("//")) {
+      parts.unshift(trimmed.replace(/^\/\/\s*/, ""));
+      i--;
+      continue;
+    }
+
+    // Block comment handling
+    const isBlockOpen = trimmed.startsWith("/*") || trimmed.startsWith("/**");
+    const isBlockClose = trimmed.endsWith("*/");
+
+    // Block comment continuation line (starts with *)
+    // These appear between /* and */, typically "* text" or "*"
+    const isBlockContent = /^\*\s?/.test(trimmed) && !isBlockOpen && !isBlockClose;
+
+    if (isBlockClose) {
+      // Line contains `*/`
+      const content = extractStarContent(trimmed);
+      if (content) parts.unshift(content);
+      if (isBlockOpen) {
+        // Single line: /** ... */
+        i--;
+        continue;
+      }
+      // Multi-line: enter block content mode
+      // Continue walking up
+      i--;
+      while (i >= 0) {
+        const aboveTrimmed = (lines[i] as string).trim();
+        if (!aboveTrimmed) break;
+        if (aboveTrimmed.startsWith("//")) {
+          // Line comment ends the block, insert it and stop
+          parts.unshift(aboveTrimmed.replace(/^\/\/\s*/, ""));
+          i--;
+          continue;
+        }
+        if (aboveTrimmed.startsWith("/*") || aboveTrimmed.startsWith("/**")) {
+          // Found the opening
+          const openContent = extractStarContent(aboveTrimmed);
+          if (openContent) parts.unshift(openContent);
+          i--;
+          break;
+        }
+        // Block content line: * text or *
+        if (/^\*\s?/.test(aboveTrimmed)) {
+          const c = aboveTrimmed.replace(/^\*\s?/, "").trim();
+          if (c) parts.unshift(c);
+          i--;
+          continue;
+        }
+        // Not block content — stop
+        break;
+      }
+      continue;
+    }
+
+    if (isBlockContent) {
+      // Encountered a * continuation line without having seen */
+      // This means the */ is below us (closer to the symbol)
+      // Walk DOWN to find it, then walk back UP
+      // Actually, simpler: just treat * lines as content and walk up
+      const content = trimmed.replace(/^\*\s?/, "").trim();
+      if (content) parts.unshift(content);
+      i--;
+      continue;
+    }
+
+    if (isBlockOpen) {
+      // Found opening without a close marker — extract and continue
+      const content = extractStarContent(trimmed);
+      if (content) parts.unshift(content);
+      i--;
+      continue;
+    }
+
+    // Python docstring (""" or ''')
+    if (trimmed.startsWith('"""') || trimmed.startsWith("'''")) {
+      const quote = trimmed.startsWith('"""') ? '"""' : "'''";
+
+      // Single-line: """text"""
+      if (trimmed.startsWith(quote) && trimmed.endsWith(quote) && trimmed.length > quote.length) {
+        const inner = trimmed.slice(quote.length, -quote.length).trim();
+        if (inner) parts.unshift(inner);
+        i--;
+        continue;
+      }
+
+      // Multi-line opening
+      if (trimmed.startsWith(quote) && !trimmed.endsWith(quote)) {
+        const afterQuote = trimmed.slice(quote.length).trim();
+        if (afterQuote) parts.unshift(afterQuote);
+        i--;
+        // Walk up to find closing quote
+        while (i >= 0) {
+          const aboveTrimmed = (lines[i] as string).trim();
+          if (aboveTrimmed.endsWith(quote)) {
+            const beforeQuote = aboveTrimmed.slice(0, -quote.length).trim();
+            if (beforeQuote) parts.unshift(beforeQuote);
+            i--;
+            break;
+          }
+          parts.unshift(aboveTrimmed);
+          i--;
+        }
+        continue;
+      }
+
+      // Just """ on its own line (closing or opening a multi-line)
+      if (trimmed === quote) {
+        // This is the closing """ — walk up to find the opening
+        i--;
+        while (i >= 0) {
+          const aboveTrimmed = (lines[i] as string).trim();
+          if (aboveTrimmed.startsWith(quote)) {
+            const afterQuote = aboveTrimmed.slice(quote.length).trim();
+            if (afterQuote) parts.unshift(afterQuote);
+            i--;
+            break;
+          }
+          parts.unshift(aboveTrimmed);
+          i--;
+        }
+        continue;
+      }
+    }
+
+    // Not a comment — stop
+    break;
+  }
+
+  return parts.join("\n").trim();
+}
+
+/** Extract visible content from a line inside a /* or /** block comment. */
+function extractStarContent(line: string): string {
+  return line
+    .replace(/^\/\**\s*/, "") // strip /* or /**
+    .replace(/\s*\*\/$/, "")  // strip */
+    .replace(/^\*\s?/, "")    // strip leading *
+    .trim();
+}

package/src/extract/regex.test.ts

@@ -0,0 +1,202 @@
+import { describe, it, expect } from 'vitest';
+import { extractRegex, extractTsJs, extractPython, extractGo } from './regex.ts';
+
+describe('extractTsJs', () => {
+  it('extracts function declarations', () => {
+    const source = `
+function hello() {
+  return 1;
+}
+
+function greet(name: string) {
+  return "hi";
+}
+`;
+    const symbols = extractTsJs(source, 'src/test.ts');
+    expect(symbols).toHaveLength(2);
+    expect(symbols[0]!.name).toBe('hello');
+    expect(symbols[0]!.kind).toBe('function');
+    expect(symbols[0]!.line_start).toBe(2);
+    expect(symbols[1]!.name).toBe('greet');
+    expect(symbols[1]!.line_start).toBe(6);
+  });
+
+  it('extracts export const (not plain const)', () => {
+    const source = `
+export const PI = 3.14;
+export const getName = () => "hello";
+const local = "secret";
+`;
+    const symbols = extractTsJs(source, 'src/consts.ts');
+    expect(symbols).toHaveLength(2);
+    expect(symbols[0]!.name).toBe('PI');
+    expect(symbols[0]!.kind).toBe('const');
+    expect(symbols[1]!.name).toBe('getName');
+    expect(symbols[1]!.kind).toBe('const');
+  });
+
+  it('extracts class declarations', () => {
+    const source = `
+class MyClass {
+  method() {}
+}
+
+export class ExportedClass {
+  foo() {}
+}
+`;
+    const symbols = extractTsJs(source, 'src/classes.ts');
+    expect(symbols).toHaveLength(2);
+    expect(symbols[0]!.name).toBe('MyClass');
+    expect(symbols[0]!.kind).toBe('class');
+    expect(symbols[1]!.name).toBe('ExportedClass');
+    expect(symbols[1]!.kind).toBe('class');
+  });
+
+  it('extracts type and interface declarations', () => {
+    const source = `
+type UserId = string;
+interface User {
+  name: string;
+}
+export type Status = "active" | "inactive";
+`;
+    const symbols = extractTsJs(source, 'src/types.ts');
+    expect(symbols).toHaveLength(3);
+    expect(symbols[0]!.name).toBe('UserId');
+    expect(symbols[0]!.kind).toBe('type');
+    expect(symbols[1]!.name).toBe('User');
+    expect(symbols[1]!.kind).toBe('interface');
+    expect(symbols[2]!.name).toBe('Status');
+    expect(symbols[2]!.kind).toBe('type');
+  });
+
+  it('extracts async functions and generators', () => {
+    const source = `
+async function fetchData() {}
+function* generate() {}
+async function* stream() {}
+`;
+    const symbols = extractTsJs(source, 'src/async.ts');
+    expect(symbols).toHaveLength(3);
+    expect(symbols[0]!.name).toBe('fetchData');
+    expect(symbols[1]!.name).toBe('generate');
+    expect(symbols[2]!.name).toBe('stream');
+  });
+
+  it('extracts export function', () => {
+    const source = 'export function doSomething(arg: string): void {}';
+    const symbols = extractTsJs(source, 'src/exports.ts');
+    expect(symbols).toHaveLength(1);
+    expect(symbols[0]!.name).toBe('doSomething');
+    expect(symbols[0]!.kind).toBe('function');
+  });
+});
+
+describe('extractPython', () => {
+  it('extracts function definitions', () => {
+    const source = `
+def hello():
+    return 1
+
+def greet(name):
+    return "hi"
+`;
+    const symbols = extractPython(source, 'src/test.py');
+    expect(symbols).toHaveLength(2);
+    expect(symbols[0]!.name).toBe('hello');
+    expect(symbols[0]!.kind).toBe('function');
+    expect(symbols[0]!.line_start).toBe(2);
+    expect(symbols[1]!.name).toBe('greet');
+    expect(symbols[1]!.line_start).toBe(5);
+  });
+
+  it('extracts class definitions and methods', () => {
+    const source = `
+class MyClass:
+    pass
+
+class AnotherClass:
+    def method(self):
+        pass
+`;
+    const symbols = extractPython(source, 'src/classes.py');
+    expect(symbols).toHaveLength(3);
+    expect(symbols[0]!.name).toBe('MyClass');
+    expect(symbols[0]!.kind).toBe('class');
+    expect(symbols[1]!.name).toBe('AnotherClass');
+    expect(symbols[1]!.kind).toBe('class');
+    expect(symbols[2]!.name).toBe('method');
+    expect(symbols[2]!.kind).toBe('function');
+  });
+
+  it('extracts async def', () => {
+    const source = 'async def fetch_data(): pass';
+    const symbols = extractPython(source, 'src/async.py');
+    expect(symbols).toHaveLength(1);
+    expect(symbols[0]!.name).toBe('fetch_data');
+    expect(symbols[0]!.kind).toBe('function');
+  });
+});
+
+describe('extractGo', () => {
+  it('extracts function declarations', () => {
+    const source = `
+func hello() {}
+
+func greet(name string) string {
+  return name
+}
+`;
+    const symbols = extractGo(source, 'src/main.go');
+    expect(symbols).toHaveLength(2);
+    expect(symbols[0]!.name).toBe('hello');
+    expect(symbols[0]!.kind).toBe('function');
+    expect(symbols[0]!.line_start).toBe(2);
+    expect(symbols[1]!.name).toBe('greet');
+    expect(symbols[1]!.line_start).toBe(4);
+  });
+
+  it('extracts methods with receivers', () => {
+    const source = `
+func (u *User) GetName() string {
+  return u.name
+}
+
+func (s *Service) Serve() error {
+  return nil
+}
+`;
+    const symbols = extractGo(source, 'src/methods.go');
+    expect(symbols).toHaveLength(2);
+    expect(symbols[0]!.name).toBe('GetName');
+    expect(symbols[0]!.kind).toBe('method');
+    expect(symbols[1]!.name).toBe('Serve');
+    expect(symbols[1]!.kind).toBe('method');
+  });
+});
+
+describe('extractRegex', () => {
+  it('dispatches to the correct language extractor for .ts', () => {
+    const symbols = extractRegex('function foo() {}', 'src/test.ts');
+    expect(symbols).toHaveLength(1);
+    expect(symbols[0]!.name).toBe('foo');
+  });
+
+  it('dispatches to the correct language extractor for .py', () => {
+    const symbols = extractRegex('def foo(): pass', 'src/test.py');
+    expect(symbols).toHaveLength(1);
+    expect(symbols[0]!.name).toBe('foo');
+  });
+
+  it('dispatches to the correct language extractor for .go', () => {
+    const symbols = extractRegex('func foo() {}', 'src/test.go');
+    expect(symbols).toHaveLength(1);
+    expect(symbols[0]!.name).toBe('foo');
+  });
+
+  it('returns empty array for unsupported file extensions', () => {
+    const symbols = extractRegex('fn foo() {}', 'src/test.rs');
+    expect(symbols).toEqual([]);
+  });
+});

package/src/extract/regex.ts

@@ -0,0 +1,192 @@
+/**
+ * Regex-based fallback symbol extraction for TS/JS/Py/Go.
+ *
+ * Used when ctags is not available on PATH. PURE module — no I/O.
+ *
+ * This is best-effort: it uses line-oriented regex patterns and does a simple
+ * comment/string skip that handles most common cases but is not an AST parser.
+ */
+
+import type { Symbol, SymbolKind } from "../types.ts";
+
+/** Extract symbols from TypeScript/JavaScript source. */
+export function extractTsJs(source: string, filePath: string): Symbol[] {
+  const lines = source.split("\n");
+  const symbols: Symbol[] = [];
+
+  // Track multi-line comments
+  let inBlockComment = false;
+
+  // Patterns for TS/JS declarations
+  const patterns: Array<{ regex: RegExp; kind: SymbolKind }> = [
+    { regex: /^(?:export\s+)?(?:async\s+)?function\s+(?:<[^>]+>\s+)?(\w+)/, kind: "function" },
+    { regex: /^(?:export\s+)?(?:async\s+)?function\s*\*?\s*(\w+)/, kind: "function" },
+    { regex: /^(?:export\s+)?class\s+(\w+)/, kind: "class" },
+    { regex: /^(?:export\s+)?interface\s+(\w+)/, kind: "interface" },
+    { regex: /^(?:export\s+)?type\s+(\w+)\s*=/, kind: "type" },
+    { regex: /^export\s+(?:const|let|var)\s+(\w+)\s*(?::\s*[^=]+)?\s*=/, kind: "const" },
+    { regex: /^export\s+(?:const|let|var)\s+(\w+)\s*(?::\s*[^;{]+)?;/, kind: "const" },
+    { regex: /^(?:export\s+)?enum\s+(\w+)/, kind: "enum" },
+    { regex: /^(?:export\s+)?abstract\s+class\s+(\w+)/, kind: "class" },
+    { regex: /^(?:export\s+)?default\s+(?:async\s+)?function\s+(\w+)/, kind: "function" },
+  ];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] as string;
+    const trimmed = line.trim();
+
+    // Skip empty lines
+    if (!trimmed) continue;
+
+    // Track block comments
+    if (inBlockComment) {
+      if (trimmed.includes("*/")) {
+        inBlockComment = false;
+      }
+      continue;
+    }
+    if (trimmed.startsWith("/*") || trimmed.startsWith("/**")) {
+      if (trimmed.includes("*/") && !trimmed.startsWith("*/")) {
+        // Single-line block comment, skip
+        continue;
+      }
+      if (!trimmed.includes("*/")) {
+        inBlockComment = true;
+      }
+      continue;
+    }
+
+    // Skip single-line comments
+    if (trimmed.startsWith("//") || trimmed.startsWith("#")) continue;
+
+    // Apply patterns
+    for (const { regex, kind } of patterns) {
+      const match = trimmed.match(regex);
+      if (match && match[1]) {
+        symbols.push({
+          name: match[1],
+          kind,
+          file_path: filePath,
+          line_start: i + 1, // 1-based
+          line_end: i + 1,
+          signature: "",
+          doc: "",
+          summary: "",
+          card_path: "",
+        });
+        break; // one symbol per line
+      }
+    }
+  }
+
+  return symbols;
+}
+
+/** Extract symbols from Python source. */
+export function extractPython(source: string, filePath: string): Symbol[] {
+  const lines = source.split("\n");
+  const symbols: Symbol[] = [];
+
+  const patterns: Array<{ regex: RegExp; kind: SymbolKind }> = [
+    { regex: /^(?:async\s+)?def\s+(\w+)\s*\(/, kind: "function" },
+    { regex: /^class\s+(\w+)/, kind: "class" },
+  ];
+
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = (lines[i] as string).trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    for (const { regex, kind } of patterns) {
+      const match = trimmed.match(regex);
+      if (match && match[1]) {
+        symbols.push({
+          name: match[1],
+          kind,
+          file_path: filePath,
+          line_start: i + 1,
+          line_end: i + 1,
+          signature: "",
+          doc: "",
+          summary: "",
+          card_path: "",
+        });
+        break;
+      }
+    }
+  }
+
+  return symbols;
+}
+
+/** Extract symbols from Go source. */
+export function extractGo(source: string, filePath: string): Symbol[] {
+  const lines = source.split("\n");
+  const symbols: Symbol[] = [];
+
+  const funcPattern = /^func\s+(?:\([^)]*\)\s+)?(\w+)\s*\(/;
+  const methodPattern = /^func\s+\([^)]*\)\s+(\w+)\s*\(/;
+
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = (lines[i] as string).trim();
+    if (!trimmed || trimmed.startsWith("//") || trimmed.startsWith("/*")) continue;
+
+    // Check for method first (has receiver)
+    const methodMatch = trimmed.match(methodPattern);
+    if (methodMatch && methodMatch[1]) {
+      symbols.push({
+        name: methodMatch[1],
+        kind: "method",
+        file_path: filePath,
+        line_start: i + 1,
+        line_end: i + 1,
+        signature: "",
+        doc: "",
+        summary: "",
+        card_path: "",
+      });
+      continue;
+    }
+
+    // Then check for regular function
+    const funcMatch = trimmed.match(funcPattern);
+    if (funcMatch && funcMatch[1]) {
+      symbols.push({
+        name: funcMatch[1],
+        kind: "function",
+        file_path: filePath,
+        line_start: i + 1,
+        line_end: i + 1,
+        signature: "",
+        doc: "",
+        summary: "",
+        card_path: "",
+      });
+    }
+  }
+
+  return symbols;
+}
+
+/**
+ * Dispatch to the correct language extractor based on file extension.
+ * Returns an empty array for unsupported languages.
+ */
+export function extractRegex(source: string, filePath: string): Symbol[] {
+  const ext = filePath.toLowerCase().split(".").pop() ?? "";
+
+  switch (ext) {
+    case "ts":
+    case "tsx":
+    case "js":
+    case "jsx":
+    case "mjs":
+    case "cjs":
+      return extractTsJs(source, filePath);
+    case "py":
+      return extractPython(source, filePath);
+    case "go":
+      return extractGo(source, filePath);
+    default:
+      return [];
+  }
+}

package/src/format.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest';
+import { formatCompact, formatCardBody } from './format.ts';
+import type { QueryResultRow, StalenessInfo } from './types.ts';
+
+function makeRow(overrides: Partial<QueryResultRow> = {}): QueryResultRow {
+  return {
+    id: 1,
+    name: 'myFunc',
+    kind: 'function',
+    file_path: 'src/util/helper.ts',
+    line_start: 10,
+    line_end: 20,
+    signature: '(x: number) => string',
+    summary: 'Does something useful with the input',
+    score: 0.5,
+    ...overrides,
+  };
+}
+
+describe('formatCompact', () => {
+  it('formats N rows into N compact lines', () => {
+    const rows = [makeRow({ name: 'foo' }), makeRow({ name: 'bar', kind: 'class' })];
+    const result = formatCompact(rows, null);
+    expect(result).toContain('foo');
+    expect(result).toContain('bar');
+    expect(result).toContain('function');
+    expect(result).toContain('class');
+    expect(result).toContain('helper.ts:10-20');
+  });
+
+  it('truncates long summaries', () => {
+    const longSummary = 'A'.repeat(200);
+    const rows = [makeRow({ summary: longSummary })];
+    const result = formatCompact(rows, null);
+    // Summary should be truncated
+    expect(result.length).toBeLessThan(400);
+  });
+
+  it('outputs capped at limit', () => {
+    const rows = Array.from({ length: 20 }, (_, i) => makeRow({ name: `func${i}` }));
+    const result = formatCompact(rows.slice(0, 5), null);
+    expect(result).toContain('func0');
+    expect(result).not.toContain('func10');
+  });
+
+  it('returns a friendly message for empty rows', () => {
+    const result = formatCompact([], null);
+    expect(result).toContain('No matches');
+  });
+
+  it('appends staleness note when present', () => {
+    const staleness: StalenessInfo = {
+      indexedCommit: 'abc123',
+      headCommit: 'def456',
+      changedFiles: 3,
+      message: 'index stale',
+    };
+    const rows = [makeRow()];
+    const result = formatCompact(rows, staleness);
+    expect(result).toContain('index stale');
+    expect(result).toContain('abc123');
+    expect(result).toContain('def456');
+  });
+});
+
+describe('formatCardBody', () => {
+  it('returns the card body text', () => {
+    const body = '# myFunc\n\nDoes something.\n';
+    expect(formatCardBody(body)).toContain('Does something.');
+  });
+});

package/src/format.ts

@@ -0,0 +1,63 @@
+/**
+ * Compact result formatter for codewalker queries.
+ *
+ * PURE module — no I/O. Produces token-bounded, one-line-per-hit output.
+ */
+
+import type { QueryResultRow, StalenessInfo } from "./types.ts";
+
+const SUMMARY_MAX = 60;
+
+/**
+ * Format query results into compact, token-efficient output.
+ *
+ * Each row becomes one line: `name · kind · file:line · summary`
+ * The total output is bounded by the number of rows.
+ */
+export function formatCompact(
+  rows: QueryResultRow[],
+  staleness: StalenessInfo | null,
+): string {
+  if (rows.length === 0) {
+    let msg = "No matches found.";
+    if (staleness) {
+      msg += ` (${staleness.message})`;
+    }
+    return msg;
+  }
+
+  const lines = rows.map((row) => {
+    const loc = `${basename(row.file_path)}:${row.line_start}-${row.line_end}`;
+    const summary = truncate(row.summary || "", SUMMARY_MAX);
+    return `${row.name} · ${row.kind} · ${loc} · ${summary}`;
+  });
+
+  if (staleness) {
+    lines.push(
+      `---\n⚠ ${staleness.message}: indexed @${shortSha(staleness.indexedCommit)}, HEAD @${shortSha(staleness.headCommit)} (${staleness.changedFiles} file(s) changed)`,
+    );
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format a card body for display.
+ */
+export function formatCardBody(body: string): string {
+  return body.trim();
+}
+
+function basename(filePath: string): string {
+  const idx = filePath.lastIndexOf("/");
+  return idx >= 0 ? filePath.slice(idx + 1) : filePath;
+}
+
+function truncate(s: string, max: number): string {
+  if (s.length <= max) return s;
+  return s.slice(0, max - 1) + "…";
+}
+
+function shortSha(sha: string): string {
+  return sha.slice(0, 7);
+}