@aprimediet/codewalker 1.0.0 → 1.2.0

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,123 @@
+import { describe, it, expect } from 'vitest';
+import { formatCompact, formatCardBody } from './format.ts';
+import type { QueryResultRow, StalenessInfo } from './types.ts';
+
+function makeLibRow(overrides: Partial<QueryResultRow> = {}): QueryResultRow {
+  return {
+    id: 100,
+    name: 'createMiddleware',
+    kind: 'function',
+    file_path: 'hono/dist/helper.d.ts',
+    line_start: 0,
+    line_end: 0,
+    signature: 'export declare function createMiddleware<E>(...): MiddlewareHandler',
+    summary: 'Define a typed middleware handler.',
+    score: 0.3,
+    source: 'lib',
+    lib: 'hono',
+    version: '4.6.3',
+    ...overrides,
+  };
+}
+
+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('formatCompact with lib rows', () => {
+  it('renders a lib row with [lib@version] origin tag', () => {
+    const rows = [makeLibRow()];
+    const result = formatCompact(rows, null);
+    expect(result).toContain('createMiddleware');
+    expect(result).toContain('function');
+    expect(result).toContain('[hono@4.6.3]');
+    expect(result).toContain('Define a typed middleware handler.');
+  });
+
+  it('renders mixed code and lib rows', () => {
+    const libRow = makeLibRow();
+    const codeRow: QueryResultRow = {
+      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', score: 0.5,
+    };
+    const result = formatCompact([codeRow, libRow], null);
+    expect(result).toContain('helper.ts:10-20');
+    expect(result).toContain('[hono@4.6.3]');
+    // Two lines
+    expect(result.split('\n')).toHaveLength(2);
+  });
+
+  it('bounded output for lib rows (one line per hit)', () => {
+    const rows = Array.from({ length: 5 }, (_, i) =>
+      makeLibRow({ name: `fn${i}`, lib: 'test-pkg', version: '1.0.0' })
+    );
+    const result = formatCompact(rows, null);
+    expect(result.split('\n')).toHaveLength(5);
+    expect(result).toContain('[test-pkg@1.0.0]');
+  });
+});
+
+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,69 @@
+/**
+ * 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) => {
+    if (row.source === "lib" && row.lib && row.version) {
+      const origin = `[${row.lib}@${row.version}]`;
+      const summary = truncate(row.summary || "", SUMMARY_MAX);
+      const loc = row.file_path ? `${basename(row.file_path)}:${row.line_start}-${row.line_end}` : `lib`;
+      return `${row.name} · ${row.kind} · ${origin} · ${loc} · ${summary}`;
+    }
+    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);
+}

package/src/git.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { execSync } from 'node:child_process';
+import { getHeadSha, changedFilesSince, parseDiffNameOnly } from './git.ts';
+
+describe('parseDiffNameOnly', () => {
+  it('parses git diff --name-only output into string[]', () => {
+    const output = `src/a.ts\nsrc/b.ts\nREADME.md\n`;
+    const files = parseDiffNameOnly(output);
+    expect(files).toEqual(['src/a.ts', 'src/b.ts', 'README.md']);
+  });
+
+  it('returns empty array for empty output', () => {
+    expect(parseDiffNameOnly('')).toEqual([]);
+  });
+
+  it('trims whitespace from each line', () => {
+    const output = `  src/a.ts \n  src/b.ts\n`;
+    const files = parseDiffNameOnly(output);
+    expect(files).toEqual(['src/a.ts', 'src/b.ts']);
+  });
+});
+
+describe('git operations in a real repo', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cw-git-'));
+    execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
+    execSync('git config user.email test@test.com', { cwd: tmpDir, stdio: 'ignore' });
+    execSync('git config user.name Test', { cwd: tmpDir, stdio: 'ignore' });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('getHeadSha returns the current HEAD commit hash', () => {
+    fs.writeFileSync(path.join(tmpDir, 'a.ts'), 'content');
+    execSync('git add . && git commit -m "first"', { cwd: tmpDir, stdio: 'ignore' });
+    const sha = getHeadSha(tmpDir);
+    expect(sha).toBeTruthy();
+    expect(sha!.length).toBe(40);
+  });
+
+  it('getHeadSha returns null when there are no commits', () => {
+    const sha = getHeadSha(tmpDir);
+    expect(sha).toBeNull();
+  });
+
+  it('changedFilesSince returns [] when lastCommit === HEAD', () => {
+    fs.writeFileSync(path.join(tmpDir, 'a.ts'), 'content');
+    execSync('git add . && git commit -m "first"', { cwd: tmpDir, stdio: 'ignore' });
+    const sha = getHeadSha(tmpDir)!;
+    const files = changedFilesSince(tmpDir, sha);
+    expect(files).toEqual([]);
+  });
+
+  it('changedFilesSince returns changed files since a previous commit', () => {
+    fs.writeFileSync(path.join(tmpDir, 'a.ts'), 'v1');
+    execSync('git add . && git commit -m "first"', { cwd: tmpDir, stdio: 'ignore' });
+    const firstSha = getHeadSha(tmpDir)!;
+
+    // Second commit
+    fs.writeFileSync(path.join(tmpDir, 'a.ts'), 'v2');
+    fs.writeFileSync(path.join(tmpDir, 'b.ts'), 'new');
+    execSync('git add . && git commit -m "second"', { cwd: tmpDir, stdio: 'ignore' });
+
+    const files = changedFilesSince(tmpDir, firstSha);
+    expect(files).toContain('a.ts');
+    expect(files).toContain('b.ts');
+  });
+});