@aprimediet/codewalker 1.0.0 → 1.2.0

package/src/query.test.ts

@@ -0,0 +1,169 @@
+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 { openDb, upsertSymbol, setMeta, getMeta, upsertLibSymbol, searchLibSymbols } from './db.ts';
+import { runQuery } from './query.ts';
+
+describe('query.ts', () => {
+  let tmpDir: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cw-query-'));
+    dbPath = path.join(tmpDir, 'test.db');
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns compact rows with file:line for a text query', () => {
+    const db = openDb(dbPath);
+    upsertSymbol(db, {
+      name: 'probeCompat', kind: 'function', file_path: 'src/compat.ts',
+      line_start: 201, line_end: 243, signature: '(cwd: string) => CompatResult',
+      doc: 'Detect integration status', summary: '', card_path: '',
+    });
+    upsertSymbol(db, {
+      name: 'detectStack', kind: 'function', file_path: 'src/detect.ts',
+      line_start: 10, line_end: 30, signature: '() => string[]',
+      doc: 'Detect tech stack', summary: '', card_path: '',
+    });
+    db.close();
+
+    const result = runQuery(dbPath, { query: 'probeCompat' });
+    expect(result.rows).toHaveLength(1);
+    expect(result.rows[0]!.name).toBe('probeCompat');
+    expect(result.rows[0]!.file_path).toBe('src/compat.ts');
+    expect(result.staleness).toBeNull();
+  });
+
+  it('kind filter narrows results', () => {
+    const db = openDb(dbPath);
+    upsertSymbol(db, {
+      name: 'MyClass', kind: 'class', file_path: 'src/a.ts',
+      line_start: 1, line_end: 10, signature: '', doc: '', summary: '', card_path: '',
+    });
+    upsertSymbol(db, {
+      name: 'myFunc', kind: 'function', file_path: 'src/b.ts',
+      line_start: 1, line_end: 5, signature: '', doc: '', summary: '', card_path: '',
+    });
+    db.close();
+
+    const result = runQuery(dbPath, { query: 'MyClass', kind: 'class' });
+    expect(result.rows).toHaveLength(1);
+    expect(result.rows[0]!.kind).toBe('class');
+  });
+
+  it('limit defaults to 10', () => {
+    const db = openDb(dbPath);
+    for (let i = 0; i < 15; i++) {
+      upsertSymbol(db, {
+        name: `sym${i}`, kind: 'function', file_path: 'src/a.ts',
+        line_start: i, line_end: i, signature: '', doc: '', summary: '', card_path: '',
+      });
+    }
+    db.close();
+
+    const result = runQuery(dbPath, { query: '' });
+    expect(result.rows.length).toBeLessThanOrEqual(10);
+  });
+
+  it('limit parameter caps results', () => {
+    const db = openDb(dbPath);
+    for (let i = 0; i < 15; i++) {
+      upsertSymbol(db, {
+        name: `sym${i}`, kind: 'function', file_path: 'src/a.ts',
+        line_start: i, line_end: i, signature: '', doc: '', summary: '', card_path: '',
+      });
+    }
+    db.close();
+
+    const result = runQuery(dbPath, { query: '', limit: 3 });
+    expect(result.rows).toHaveLength(3);
+  });
+
+  it('reports staleness when last_indexed_commit differs from HEAD', () => {
+    // Without git, staleness will be null (no commit to compare)
+    const db = openDb(dbPath);
+    setMeta(db, 'last_indexed_commit', 'abc123');
+    db.close();
+
+    const result = runQuery(dbPath, { query: '' });
+    // The staleness signal depends on git context
+    // In a non-git dir, staleness should be null
+    expect(result.staleness).toBeNull();
+  });
+
+  // ── source filter ───────────────────────────────────────────
+  it('source="code" returns only code symbols (default)', () => {
+    const db = openDb(dbPath);
+    upsertSymbol(db, {
+      name: 'myFunc', kind: 'function', file_path: 'src/a.ts',
+      line_start: 1, line_end: 1, signature: '', doc: '', summary: '', card_path: '',
+    });
+    upsertLibSymbol(db, {
+      lib: 'hono', version: '4.6.3', name: 'honoFunc',
+      kind: 'function', signature: '', doc: '', summary: '', card_path: '',
+    });
+    db.close();
+
+    const result = runQuery(dbPath, { query: '', source: 'code' });
+    expect(result.rows).toHaveLength(1);
+    expect(result.rows[0]!.name).toBe('myFunc');
+    expect(result.rows[0]!.source).toBeUndefined();
+  });
+
+  it('source="libs" returns only lib symbols', () => {
+    const db = openDb(dbPath);
+    upsertSymbol(db, {
+      name: 'myFunc', kind: 'function', file_path: 'src/a.ts',
+      line_start: 1, line_end: 1, signature: '', doc: '', summary: '', card_path: '',
+    });
+    upsertLibSymbol(db, {
+      lib: 'hono', version: '4.6.3', name: 'honoFunc',
+      kind: 'function', signature: '', doc: '', summary: '', card_path: '',
+    });
+    db.close();
+
+    const result = runQuery(dbPath, { query: '', source: 'libs' });
+    expect(result.rows).toHaveLength(1);
+    expect(result.rows[0]!.name).toBe('honoFunc');
+    expect(result.rows[0]!.source).toBe('lib');
+    expect(result.rows[0]!.lib).toBe('hono');
+    expect(result.rows[0]!.version).toBe('4.6.3');
+  });
+
+  it('source="all" returns merged code and lib symbols', () => {
+    const db = openDb(dbPath);
+    upsertSymbol(db, {
+      name: 'myFunc', kind: 'function', file_path: 'src/a.ts',
+      line_start: 1, line_end: 1, signature: '', doc: '', summary: '', card_path: '',
+    });
+    upsertLibSymbol(db, {
+      lib: 'hono', version: '4.6.3', name: 'honoFunc',
+      kind: 'function', signature: '', doc: '', summary: '', card_path: '',
+    });
+    db.close();
+
+    const result = runQuery(dbPath, { query: '', source: 'all' });
+    expect(result.rows).toHaveLength(2);
+  });
+
+  it('source=all respects limit across merged set', () => {
+    const db = openDb(dbPath);
+    upsertSymbol(db, {
+      name: 'aCode', kind: 'function', file_path: 'src/a.ts',
+      line_start: 1, line_end: 1, signature: '', doc: '', summary: '', card_path: '',
+    });
+    upsertLibSymbol(db, {
+      lib: 'pkg', version: '1.0.0', name: 'bLib',
+      kind: 'function', signature: '', doc: '', summary: '', card_path: '',
+    });
+    db.close();
+
+    const result = runQuery(dbPath, { query: '', source: 'all', limit: 1 });
+    expect(result.rows).toHaveLength(1);
+  });
+});

package/src/query.ts

@@ -0,0 +1,89 @@
+/**
+ * Query orchestration: wraps DB search with staleness detection.
+ */
+
+import type { QueryResult, QueryResultRow, StalenessInfo } from "./types.ts";
+import { openDb, searchSymbols, searchLibSymbols, getMeta } from "./db.ts";
+import { getHeadSha, changedFilesSince } from "./git.ts";
+
+export interface QueryParams {
+  query: string;
+  kind?: string;
+  limit?: number;
+  /** Source scope: "code" (default, only code symbols), "libs" (only lib symbols), or "all" (both). */
+  source?: "code" | "libs" | "all";
+}
+
+/**
+ * Run a query against a codewalker DB.
+ *
+ * @param dbPath - Path to the SQLite DB file.
+ * @param params - Query parameters.
+ * @param repoDir - Optional repo directory for staleness detection.
+ */
+export function runQuery(
+  dbPath: string,
+  params: QueryParams,
+  repoDir?: string,
+): QueryResult {
+  const db = openDb(dbPath);
+
+  try {
+    const source = params.source ?? "code";
+    const limit = params.limit ?? 10;
+
+    let rows: QueryResultRow[];
+
+    if (source === "libs") {
+      rows = searchLibSymbols(db, params.query, params.kind, limit) as unknown as QueryResultRow[];
+    } else if (source === "all") {
+      // Run both code and lib searches, merge, sort by score, apply limit
+      const codeRows = searchSymbols(db, params.query, params.kind, limit);
+      const libRows = searchLibSymbols(db, params.query, params.kind, limit) as unknown as QueryResultRow[];
+
+      // Merge and sort by score ascending (lower bm25 = better match)
+      const merged: QueryResultRow[] = [...codeRows, ...libRows];
+      merged.sort((a, b) => a.score - b.score);
+      rows = merged.slice(0, limit);
+    } else {
+      // "code" — default, existing behavior
+      rows = searchSymbols(db, params.query, params.kind, limit);
+    }
+
+    const staleness = detectStaleness(db, repoDir);
+
+    return { rows, staleness };
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Detect whether the index is stale compared to the current git HEAD.
+ */
+function detectStaleness(
+  db: Database,
+  repoDir?: string,
+): StalenessInfo | null {
+  if (!repoDir) return null;
+
+  const indexedCommit = getMeta(db, "last_indexed_commit");
+  if (!indexedCommit) return null;
+
+  const headCommit = getHeadSha(repoDir);
+  if (!headCommit) return null;
+
+  if (indexedCommit === headCommit) return null;
+
+  const changedFiles = changedFilesSince(repoDir, indexedCommit);
+
+  return {
+    indexedCommit,
+    headCommit,
+    changedFiles: changedFiles.length,
+    message: `Index is stale (${changedFiles.length} file(s) changed since last index)`,
+  };
+}
+
+// Re-export for test convenience
+export { detectStaleness };

package/src/sync.test.ts

@@ -0,0 +1,116 @@
+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 { sync } from './indexer.ts';
+import { openDb, getMeta, searchSymbols } from './db.ts';
+
+describe('sync', () => {
+  let tmpDir: string;
+  let globalDir: string;
+  let cardsDir: string;
+  let symbolsDir: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cw-sync-'));
+    globalDir = path.join(tmpDir, '.pi-global', 'projects', 'test-project', 'codewalker');
+    cardsDir = path.join(globalDir, 'entries');
+    symbolsDir = path.join(cardsDir, 'symbols');
+    dbPath = path.join(globalDir, 'index.db');
+    fs.mkdirSync(symbolsDir, { recursive: true });
+
+    // Init git repo
+    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 });
+  });
+
+  function writeFile(name: string, content: string): void {
+    const p = path.join(tmpDir, name);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, content, 'utf-8');
+  }
+
+  it('sync reindexes only changed files after an edit', async () => {
+    writeFile('src/a.ts', 'function alpha() {}');
+    writeFile('src/b.ts', 'function beta() {}');
+    execSync('git add . && git commit -m "initial"', { cwd: tmpDir, stdio: 'ignore' });
+
+    // First full scan
+    await sync({
+      projectRoot: tmpDir,
+      globalCodewalkerDir: globalDir,
+      dbPath,
+      entriesDir: cardsDir,
+      symbolsDir,
+      useCtags: false,
+    });
+
+    const db = openDb(dbPath);
+    expect(getMeta(db, 'last_indexed_commit')).toBeTruthy();
+    const beforeEdit = searchSymbols(db, '', undefined, 100);
+    const beforeCount = beforeEdit.length;
+    db.close();
+
+    // Edit one file
+    writeFile('src/b.ts', 'function beta() {}\nfunction beta2() {}');
+    execSync('git add . && git commit -m "edit b"', { cwd: tmpDir, stdio: 'ignore' });
+
+    // Sync
+    await sync({
+      projectRoot: tmpDir,
+      globalCodewalkerDir: globalDir,
+      dbPath,
+      entriesDir: cardsDir,
+      symbolsDir,
+      useCtags: false,
+    });
+
+    const db2 = openDb(dbPath);
+    const afterEdit = searchSymbols(db2, '', undefined, 100);
+    // Should have one more symbol (beta2 added)
+    expect(afterEdit.length).toBe(beforeCount + 1);
+    expect(afterEdit.some(s => s.name === 'beta2')).toBe(true);
+    db2.close();
+  });
+
+  it('sync removes symbols for deleted files', async () => {
+    writeFile('src/keep.ts', 'function keep() {}');
+    writeFile('src/remove.ts', 'function removeMe() {}');
+    execSync('git add . && git commit -m "initial"', { cwd: tmpDir, stdio: 'ignore' });
+
+    await sync({
+      projectRoot: tmpDir,
+      globalCodewalkerDir: globalDir,
+      dbPath,
+      entriesDir: cardsDir,
+      symbolsDir,
+      useCtags: false,
+    });
+
+    // Delete one file
+    fs.rmSync(path.join(tmpDir, 'src/remove.ts'));
+    execSync('git add . && git commit -m "delete remove"', { cwd: tmpDir, stdio: 'ignore' });
+
+    await sync({
+      projectRoot: tmpDir,
+      globalCodewalkerDir: globalDir,
+      dbPath,
+      entriesDir: cardsDir,
+      symbolsDir,
+      useCtags: false,
+    });
+
+    const db = openDb(dbPath);
+    const all = searchSymbols(db, '', undefined, 100);
+    expect(all.some(s => s.name === 'keep')).toBe(true);
+    expect(all.some(s => s.name === 'removeMe')).toBe(false);
+    db.close();
+  });
+});

package/src/types.ts

@@ -0,0 +1,117 @@
+/**
+ * Core types for the codewalker code index.
+ *
+ * These types are shared across all layers (extraction, cards, DB, query).
+ */
+
+/** Library symbol kind — extends SymbolKind with reexport + namespace. */
+export type LibSymbolKind =
+  | "function"
+  | "const"
+  | "class"
+  | "interface"
+  | "type"
+  | "enum"
+  | "namespace"
+  | "reexport"
+  | "module";
+
+/** The kind of a code symbol. */
+export type SymbolKind =
+  | "function"
+  | "const"
+  | "class"
+  | "type"
+  | "method"
+  | "enum"
+  | "variable"
+  | "interface"
+  | "namespace"
+  | "module";
+
+/** A single symbol extracted from a library's .d.ts file. */
+export interface LibSymbol {
+  lib: string;
+  version: string;
+  name: string;
+  kind: LibSymbolKind;
+  signature: string;
+  doc: string;
+  summary: string;
+  card_path: string;
+}
+
+/** A single symbol extracted from source code. */
+export interface Symbol {
+  name: string;
+  kind: SymbolKind;
+  file_path: string;
+  line_start: number;
+  line_end: number;
+  signature: string;
+  doc: string;
+  summary: string; // reserved for v1.3; empty in v1.1
+  card_path: string;
+}
+
+/** The frontmatter head of a markdown card — what `query` returns (compact, token-cheap). */
+export interface CardHead {
+  name: string;
+  kind: string;
+  signature: string;
+  location: string; // "file.ts:10-42"
+  tags: string[];
+  summary: string;
+}
+
+/** A single row returned from a query. */
+export interface QueryResultRow {
+  name: string;
+  kind: string;
+  file_path: string;
+  line_start: number;
+  line_end: number;
+  signature: string;
+  summary: string;
+  score: number;
+  id: number;
+  /** Origin fields — code rows omit these; lib rows set them. */
+  source?: "code" | "lib";
+  lib?: string;
+  version?: string;
+}
+
+/** The full result of a query, including staleness info. */
+export interface QueryResult {
+  rows: QueryResultRow[];
+  staleness: StalenessInfo | null;
+}
+
+/** Git-anchored staleness signal attached to every query result. */
+export interface StalenessInfo {
+  indexedCommit: string;
+  headCommit: string;
+  changedFiles: number;
+  message: string;
+}
+
+/** Metadata about the index stored in meta.json. */
+export interface IndexMeta {
+  schemaVersion: number;
+  lastIndexedCommit: string;
+  lastFullScan: string; // ISO date
+}
+
+/** Configuration for the codebase indexer. */
+export interface IndexerConfig {
+  language: "ts" | "js" | "py" | "go" | "rs";
+  extensions: string[];
+}
+
+/** Map of language → file extension list. */
+export const SUPPORTED_LANGUAGES: Record<string, string[]> = {
+  ts: [".ts", ".tsx"],
+  js: [".js", ".jsx", ".mjs", ".cjs"],
+  py: [".py"],
+  go: [".go"],
+};

package/vitest.config.ts

@@ -0,0 +1,28 @@
+import { defineConfig } from 'vitest/config';
+import path from 'path';
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, 'src'),
+    },
+  },
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'lcov'],
+      exclude: [
+        'src/**/*.test.ts',
+        '**/node_modules/**',
+        '**/dist/**',
+      ],
+    },
+    sequence: {
+      concurrent: false,
+    },
+    testTimeout: 15_000,
+  },
+});

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 aprimediet
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/agents.ts

@@ -1,126 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-
-// Agent-facing guide lives at the repo root by convention (AGENTS.md), with a thin
-// CLAUDE.md pointer next to it so Claude Code auto-imports the same source of truth.
-const AGENTS_CANDIDATES = ["AGENTS.md", ".agents/AGENTS.md", "docs/AGENTS.md"];
-const CLAUDE_CANDIDATES = ["CLAUDE.md", ".claude/CLAUDE.md"];
-
-export function findExistingAgentsMd(root: string): string | null {
-  for (const p of AGENTS_CANDIDATES) {
-    const filePath = path.join(root, p);
-    if (fs.existsSync(filePath)) {
-      return filePath;
-    }
-  }
-  return null;
-}
-
-export function findExistingClaudeMd(root: string): string | null {
-  for (const p of CLAUDE_CANDIDATES) {
-    const filePath = path.join(root, p);
-    if (fs.existsSync(filePath)) {
-      return filePath;
-    }
-  }
-  return null;
-}
-
-export function createAgentsMd(root: string, content: string): string {
-  const outPath = path.join(root, "AGENTS.md");
-  fs.writeFileSync(outPath, content, "utf-8");
-  return outPath;
-}
-
-export function createClaudeMd(root: string, content: string): string {
-  const outPath = path.join(root, "CLAUDE.md");
-  fs.writeFileSync(outPath, content, "utf-8");
-  return outPath;
-}
-
-/**
- * The agent-facing engineering guide. This is the "how to work in this repo" document:
- * tech stack, structure, commands, conventions, technical boundaries, gotchas, and how
- * the agent should use the minion/memory companion extensions. Product "what & why"
- * (goals, users, features, metrics) belongs in the PRD, not here.
- */
-export function agentsMdTemplate(p: {
-  projectName: string;
-  summary: string;
-  techStack: string;
-  structure: string;
-  commands: { setup?: string; build?: string; test?: string; run?: string; lint?: string };
-  conventions: string;
-  boundaries: string;
-  knownIssues: string[];
-  integration: string;
-  currentFocus: string;
-  prdPath: string | null;
-}): string {
-  const cmd = p.commands;
-  const commandRows = [
-    cmd.setup ? `- **Setup:** \`${cmd.setup}\`` : null,
-    cmd.build ? `- **Build:** \`${cmd.build}\`` : null,
-    cmd.test ? `- **Test:** \`${cmd.test}\`` : null,
-    cmd.run ? `- **Run:** \`${cmd.run}\`` : null,
-    cmd.lint ? `- **Lint:** \`${cmd.lint}\`` : null,
-  ]
-    .filter(Boolean)
-    .join("\n");
-  const commandsSection = commandRows || "_(none detected — ask the user)_";
-  const issuesSection = p.knownIssues.length
-    ? p.knownIssues.map((i) => `- ${i}`).join("\n")
-    : "_(none known)_";
-  const productLink = p.prdPath
-    ? `Product context (goals, users, features, success metrics): see [${p.prdPath}](${p.prdPath}).`
-    : "Product context: no PRD found.";
-
-  return `# AGENTS.md — ${p.projectName}
-
-Guide for coding agents working in this repository. ${productLink}
-
-## Summary
-${p.summary}
-
-## Tech Stack
-${p.techStack}
-
-## Project Structure
-${p.structure}
-
-## Commands
-${commandsSection}
-
-## Conventions
-${p.conventions}
-
-## Boundaries (technical)
-${p.boundaries}
-
-## Known Issues & Gotchas
-${issuesSection}
-
-## Companion Extensions
-${p.integration}
-
-## Current Focus
-${p.currentFocus}
-`;
-}
-
-/**
- * A thin CLAUDE.md that points Claude Code at AGENTS.md as the single source of truth.
- * The `@AGENTS.md` line triggers Claude Code's file-import so the content is pulled in.
- */
-export function claudeMdTemplate(projectName: string): string {
-  return `# CLAUDE.md — ${projectName}
-
-Guidance for Claude Code in this repository.
-
-All project conventions, architecture, build/test commands, and boundaries live in
-**[AGENTS.md](./AGENTS.md)** — the shared guide for every coding agent. Keep that file
-as the single source of truth; do not duplicate its content here.
-
-@AGENTS.md
-`;
-}