@aprimediet/codewalker 1.0.0 → 1.2.0

package/src/extract/ctags-parse.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect } from 'vitest';
+import { parseCtagsLine, parseCtagsOutput, mapCtagsKind, type CtagsTag } from './ctags-parse.ts';
+
+describe('mapCtagsKind', () => {
+  it('maps ctags kind to SymbolKind', () => {
+    expect(mapCtagsKind('function')).toBe('function');
+    expect(mapCtagsKind('variable')).toBe('const');
+    expect(mapCtagsKind('class')).toBe('class');
+    expect(mapCtagsKind('member')).toBe('method');
+    expect(mapCtagsKind('enum')).toBe('enum');
+    expect(mapCtagsKind('typedef')).toBe('type');
+    expect(mapCtagsKind('interface')).toBe('interface');
+    expect(mapCtagsKind('namespace')).toBe('namespace');
+    expect(mapCtagsKind('module')).toBe('module');
+  });
+
+  it('returns the kind as-is for unknown kinds', () => {
+    expect(mapCtagsKind('macro')).toBe('macro');
+    expect(mapCtagsKind('unknown')).toBe('unknown');
+  });
+});
+
+describe('parseCtagsLine', () => {
+  it('parses a valid ctags JSON line into a CtagsTag', () => {
+    const line = '{"_type":"tag","name":"myFunction","path":"src/file.ts","pattern":"/^export function myFunction()/","line":10,"kind":"function","signature":"(param: string)"}';
+    const result = parseCtagsLine(line);
+    expect(result).not.toBeNull();
+    expect(result!.name).toBe('myFunction');
+    expect(result!.path).toBe('src/file.ts');
+    expect(result!.line).toBe(10);
+    expect(result!.kind).toBe('function');
+    expect(result!.signature).toBe('(param: string)');
+  });
+
+  it('returns null for non-tag lines', () => {
+    expect(parseCtagsLine('{"_type":"other","name":"foo"}')).toBeNull();
+    expect(parseCtagsLine('not json')).toBeNull();
+    expect(parseCtagsLine('')).toBeNull();
+  });
+
+  it('tolerates missing signature field', () => {
+    const line = '{"_type":"tag","name":"foo","path":"a.ts","line":5,"kind":"function"}';
+    const result = parseCtagsLine(line);
+    expect(result).not.toBeNull();
+    expect(result!.signature).toBe('');
+  });
+
+  it('tolerates missing kind field', () => {
+    const line = '{"_type":"tag","name":"foo","path":"a.ts","line":5}';
+    const result = parseCtagsLine(line);
+    expect(result).not.toBeNull();
+    expect(result!.kind).toBe('unknown');
+  });
+
+  it('handles numeric kind field (ctags numeric kind)', () => {
+    const line = '{"_type":"tag","name":"Foo","path":"a.ts","line":10,"kind":"class"}';
+    const result = parseCtagsLine(line);
+    expect(result).not.toBeNull();
+    expect(result!.kind).toBe('class');
+  });
+});
+
+describe('parseCtagsOutput', () => {
+  it('parses multi-line ctags JSON output into Symbol array', () => {
+    const output = [
+      '{"_type":"tag","name":"myFunc","path":"src/a.ts","line":5,"kind":"function","signature":"()"}',
+      '{"_type":"tag","name":"MyClass","path":"src/a.ts","line":20,"kind":"class","signature":""}',
+      '{"_type":"tag","name":"MY_CONST","path":"src/b.ts","line":1,"kind":"variable","signature":"42"}',
+    ].join('\n');
+
+    const symbols = parseCtagsOutput(output, '/root/project');
+    expect(symbols).toHaveLength(3);
+
+    expect(symbols[0]!.name).toBe('myFunc');
+    expect(symbols[0]!.kind).toBe('function');
+    expect(symbols[0]!.file_path).toBe('/root/project/src/a.ts');
+    expect(symbols[0]!.line_start).toBe(5);
+
+    expect(symbols[1]!.name).toBe('MyClass');
+    expect(symbols[1]!.kind).toBe('class');
+
+    expect(symbols[2]!.name).toBe('MY_CONST');
+    expect(symbols[2]!.kind).toBe('const');
+  });
+
+  it('skips malformed and non-tag lines', () => {
+    const output = [
+      '{"_type":"tag","name":"valid","path":"a.ts","line":1,"kind":"function","signature":""}',
+      'not json at all',
+      '{"_type":"notag","name":"skip"}',
+      '',
+      '{"_type":"tag","name":"valid2","path":"a.ts","line":5,"kind":"class","signature":""}',
+    ].join('\n');
+
+    const symbols = parseCtagsOutput(output, '/root');
+    expect(symbols).toHaveLength(2);
+  });
+
+  it('returns empty array for empty output', () => {
+    expect(parseCtagsOutput('', '/root')).toEqual([]);
+  });
+
+  it('resolves relative paths against project root', () => {
+    const output = '{"_type":"tag","name":"f","path":"src/lib/util.ts","line":3,"kind":"function","signature":""}';
+    const symbols = parseCtagsOutput(output, '/home/user/project');
+    expect(symbols[0]!.file_path).toBe('/home/user/project/src/lib/util.ts');
+  });
+});

package/src/extract/ctags-parse.ts

@@ -0,0 +1,112 @@
+/**
+ * Parse Universal Ctags JSON output into Symbol[].
+ *
+ * Universal Ctags emits one JSON object per line with `--output-format=json`.
+ * Fields: _type, name, path, pattern, line, kind, signature.
+ *
+ * This module is PURE — no I/O, takes strings and returns objects.
+ */
+
+import type { Symbol, SymbolKind } from "../types.ts";
+
+/** Raw ctags tag as parsed from a JSON line. */
+export interface CtagsTag {
+  name: string;
+  path: string;
+  line: number;
+  kind: string;
+  signature: string;
+}
+
+/**
+ * Map a ctags `kind` string to our canonical SymbolKind.
+ * Unknown kinds are returned as-is so callers can handle them or skip.
+ */
+export function mapCtagsKind(kind: string): string {
+  const mapping: Record<string, string> = {
+    function: "function",
+    variable: "const",
+    class: "class",
+    member: "method",
+    enum: "enum",
+    typedef: "type",
+    interface: "interface",
+    namespace: "namespace",
+    module: "module",
+  };
+  return mapping[kind] ?? kind;
+}
+
+/**
+ * Parse a single ctags JSON line into a CtagsTag, or null if it's not a tag line.
+ */
+export function parseCtagsLine(line: string): CtagsTag | null {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(trimmed) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+
+  // Only process _type === "tag"
+  if (parsed["_type"] !== "tag") return null;
+
+  const name = parsed["name"];
+  const path = parsed["path"];
+  const lineNum = parsed["line"];
+  const kind = parsed["kind"];
+  const signature = parsed["signature"];
+
+  if (typeof name !== "string" || typeof path !== "string") return null;
+  if (typeof lineNum !== "number") return null;
+
+  return {
+    name,
+    path,
+    line: lineNum,
+    kind: typeof kind === "string" ? kind : "unknown",
+    signature: typeof signature === "string" ? signature : "",
+  };
+}
+
+/**
+ * Parse multi-line ctags JSON output, returning Symbol[] with absolute paths.
+ *
+ * @param output - The raw stdout from ctags (one JSON object per line).
+ * @param projectRoot - Absolute path to the project root, used to resolve relative file paths.
+ */
+export function parseCtagsOutput(output: string, projectRoot: string): Symbol[] {
+  if (!output.trim()) return [];
+
+  const lines = output.split("\n");
+  const symbols: Symbol[] = [];
+
+  for (const line of lines) {
+    const tag = parseCtagsLine(line);
+    if (!tag) continue;
+
+    // Resolve relative paths against project root
+    const filePath = tag.path.startsWith("/")
+      ? tag.path
+      : `${projectRoot.replace(/\/+$/, "")}/${tag.path}`;
+
+    symbols.push({
+      name: tag.name,
+      kind: mapCtagsKind(tag.kind) as SymbolKind,
+      file_path: filePath,
+      line_start: tag.line,
+      line_end: tag.line, // ctags only gives start line
+      signature: tag.signature,
+      doc: "",
+      summary: "",
+      card_path: "",
+    });
+  }
+
+  return symbols;
+}
+
+

package/src/extract/ctags.ts

@@ -0,0 +1,51 @@
+/**
+ * Thin shell: detect ctags on PATH and run it.
+ *
+ * Separated from ctags-parse.ts (PURE parsing) so the I/O boundary is explicit.
+ */
+
+import { execSync } from "node:child_process";
+
+/**
+ * Detect whether ctags is available on PATH.
+ */
+export function detectCtags(): boolean {
+  try {
+    execSync("ctags --version", { stdio: "ignore", timeout: 5000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run ctags on a list of files and return raw JSON output.
+ */
+export function runCtags(files: string[], projectRoot: string): string {
+  const fileList = files.join(" ");
+  return execSync(
+    `ctags --output-format=json --fields=+nKzS -f - ${fileList}`,
+    {
+      cwd: projectRoot,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 30000,
+      maxBuffer: 10 * 1024 * 1024,
+    },
+  );
+}
+
+/**
+ * Run ctags on a single file and return raw JSON output.
+ */
+export function runCtagsOnFile(filePath: string, projectRoot: string): string {
+  return execSync(
+    `ctags --output-format=json --fields=+nKzS -f - "${filePath}"`,
+    {
+      cwd: projectRoot,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 10000,
+    },
+  );
+}

package/src/extract/docs.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect } from 'vitest';
+import { extractDocComment } from './docs.ts';
+
+describe('extractDocComment', () => {
+  it('extracts a JSDoc block comment above a given line', () => {
+    const source = `/**
+ * This is a doc comment for myFunc.
+ * It has multiple lines.
+ */
+function myFunc() {}
+`;
+    const doc = extractDocComment(source, 4);
+    expect(doc).toContain('This is a doc comment for myFunc');
+    expect(doc).toContain('It has multiple lines');
+  });
+
+  it('extracts // line comment block above a given line', () => {
+    const source = `// This is a line comment
+// that spans two lines
+function myFunc() {}
+`;
+    const doc = extractDocComment(source, 3);
+    expect(doc).toContain('This is a line comment');
+    expect(doc).toContain('that spans two lines');
+  });
+
+  it('extracts a Python docstring above a given line', () => {
+    const source = `"""This is a Python docstring
+for my function.
+"""
+def my_func():
+    pass
+`;
+    const doc = extractDocComment(source, 4);
+    expect(doc).toContain('This is a Python docstring');
+    expect(doc).toContain('for my function.');
+  });
+
+  it('returns empty string when there is no doc comment', () => {
+    const source = `const x = 1;
+function myFunc() {}
+`;
+    const doc = extractDocComment(source, 2);
+    expect(doc).toBe('');
+  });
+
+  it('returns empty string for a symbol on the first line with no preceding comments', () => {
+    const source = `function first() {}`;
+    const doc = extractDocComment(source, 1);
+    expect(doc).toBe('');
+  });
+
+  it('extracts mixed // and /* */ comment lines', () => {
+    const source = `// A brief explanation
+/* Then a block comment */
+function mixed() {}
+`;
+    const doc = extractDocComment(source, 3);
+    expect(doc).toContain('A brief explanation');
+    expect(doc).toContain('Then a block comment');
+  });
+
+  it('stops at blank lines when collecting adjacent comments', () => {
+    const source = `// Not adjacent
+
+// Directly above
+function myFunc() {}
+`;
+    const doc = extractDocComment(source, 4);
+    expect(doc).toContain('Directly above');
+    expect(doc).not.toContain('Not adjacent');
+  });
+
+  it('handles single-line Python docstrings', () => {
+    const source = `"""Single line docstring."""
+def quick(): pass
+`;
+    const doc = extractDocComment(source, 2);
+    expect(doc).toContain('Single line docstring.');
+  });
+});

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();
+}