@winspan/claude-forge 8.54.3 → 9.2.0

package/dist/knowledge/query.js

@@ -0,0 +1,341 @@
+/**
+ * @file query.ts
+ * KB Phase 3A — Retrieval layer.
+ *
+ * v9.0 strategy: keyword-only search across KB pages + optional repo-map
+ * symbol matching.  No AI calls, no vector index.
+ *
+ * Public API:
+ *   queryKnowledge  – keyword search returning scored hits
+ *   listKnowledge   – enumerate all KB pages
+ *   getPage         – fetch a single page by name
+ *   isKnowledgeBuilt – check whether .forge-knowledge/ is initialised
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { extractRefsFromMarkdown } from './validator.js';
+import { loadRepoMap } from './repo-map.js';
+import * as K from './constants.js';
+import { LRUCache } from '../core/utils/lru-cache.js';
+import { logger } from '../core/utils/logger.js';
+const PAGE_CACHE_SIZE = 50;
+const pageCache = new LRUCache(PAGE_CACHE_SIZE);
+/** Test-only hook — flush the cache between isolated tmpdir test runs. */
+export function _clearPageCacheForTests() {
+    pageCache.clear();
+}
+/** Test-only hook — inspect cache size without exposing the cache itself. */
+export function _pageCacheSizeForTests() {
+    return pageCache.size();
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Split a query string into lowercase, deduplicated tokens.
+ *
+ * Rules:
+ *   - Lowercase everything.
+ *   - Replace non-word / non-CJK characters with spaces.
+ *   - Drop ASCII tokens shorter than 2 characters (usually stop-words or noise).
+ *   - For each contiguous CJK segment, additionally emit 2-char and 3-char
+ *     sliding n-grams. Mandarin/Japanese/Korean have no inter-word whitespace,
+ *     so whitespace splitting alone produces a single block per phrase that
+ *     almost never matches KB pages verbatim (KPI C1 root cause).
+ *     n-gram fallback bumps recall dramatically; false positives are accepted
+ *     in v1 (score formula unchanged — to be revisited if noise is excessive).
+ *   - Deduplicate.
+ */
+function tokenize(query) {
+    const tokens = new Set();
+    const cleaned = query.toLowerCase().replace(/[^\w一-鿿\s]/g, ' ');
+    // 1. Whitespace-split tokens (back-compat: ASCII words + full CJK runs).
+    for (const t of cleaned.split(/\s+/)) {
+        if (t.length >= 2)
+            tokens.add(t);
+    }
+    // 2. CJK char-level n-gram fallback. For each contiguous CJK run of length
+    //    ≥2, emit every 2-char and (when long enough) 3-char window.
+    const cjkSegments = cleaned.match(/[一-鿿]{2,}/g) ?? [];
+    for (const seg of cjkSegments) {
+        for (let i = 0; i + 2 <= seg.length; i++) {
+            tokens.add(seg.slice(i, i + 2));
+        }
+        if (seg.length >= 3) {
+            for (let i = 0; i + 3 <= seg.length; i++) {
+                tokens.add(seg.slice(i, i + 3));
+            }
+        }
+    }
+    return [...tokens];
+}
+/**
+ * Score a single KB page against the token list.
+ *
+ * Weight table:
+ *   title / page-name match  → +30 per keyword
+ *   refs.symbol match        → +20 per keyword
+ *   content match            → +10 per keyword
+ *
+ * The raw score is normalised to 0-100 relative to the theoretical maximum
+ * (`keywords.length * (30 + 20 + 10)`).
+ */
+function scoreHit(page, keywords) {
+    const titleLower = `${page.title} ${page.name}`.toLowerCase();
+    const contentLower = page.content.toLowerCase();
+    const refSymbolsLower = page.refs.map((r) => (r.symbol ?? '').toLowerCase());
+    let rawScore = 0;
+    const matchedKeywords = new Set();
+    const matchedIn = new Set();
+    for (const kw of keywords) {
+        if (titleLower.includes(kw)) {
+            rawScore += 30;
+            matchedKeywords.add(kw);
+            matchedIn.add('title');
+        }
+        if (refSymbolsLower.some((s) => s.includes(kw))) {
+            rawScore += 20;
+            matchedKeywords.add(kw);
+            matchedIn.add('refs');
+        }
+        if (contentLower.includes(kw)) {
+            rawScore += 10;
+            matchedKeywords.add(kw);
+            matchedIn.add('content');
+        }
+    }
+    const maxPossible = keywords.length * (30 + 20 + 10);
+    const score = maxPossible > 0 ? Math.min(100, Math.round((rawScore / maxPossible) * 100)) : 0;
+    return {
+        page,
+        score,
+        matched_keywords: [...matchedKeywords],
+        matched_in: [...matchedIn],
+    };
+}
+/**
+ * Find repo-map symbols whose name contains any of the keywords (case-insensitive).
+ * Capped at 10 results to keep response sizes manageable.
+ */
+function findSymbolHits(symbols, keywords) {
+    const hits = symbols.filter((s) => {
+        const nameLower = s.name.toLowerCase();
+        return keywords.some((kw) => nameLower.includes(kw));
+    });
+    return hits.slice(0, 10);
+}
+/**
+ * Parse a single `.md` file on disk and reconstruct a `KBPage` from its
+ * content.
+ *
+ * Layout assumed on disk (written by the builder):
+ *   # <title>
+ *   > Generated: <ISO-datetime> | source: <hash>
+ *   … markdown body …
+ *   with inline refs like `src/foo.ts:L42`
+ *
+ * Missing or unparseable fields fall back to safe defaults so that malformed
+ * pages still surface in query results rather than being silently dropped.
+ */
+function loadPageFromFile(filePath, pageName, projectRoot) {
+    try {
+        // F6 cache: stat first (cheap), reuse parsed page when mtime unchanged.
+        // statSync still touches the FS, but it's an order of magnitude cheaper
+        // than readFileSync + parseMarkdown for the typical ~5KB KB page.
+        const stat = fs.statSync(filePath);
+        const cached = pageCache.get(filePath);
+        if (cached && cached.mtimeMs === stat.mtimeMs) {
+            return cached.page;
+        }
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const lines = raw.split('\n');
+        // ── Title: first `# …` heading ────────────────────────────────────────────
+        const titleLine = lines.find((l) => l.startsWith('# '));
+        const title = titleLine ? titleLine.replace(/^#\s+/, '').trim() : pageName;
+        // ── Metadata line: `> Generated: … | source: …` ──────────────────────────
+        const metaLine = lines.find((l) => l.startsWith('> Generated:'));
+        let generated_at = '';
+        let source_hash = '';
+        if (metaLine) {
+            const m = metaLine.match(/Generated:\s*(\S+).*source:\s*(\S+)/);
+            if (m) {
+                generated_at = m[1];
+                source_hash = m[2];
+            }
+        }
+        // ── Refs: re-extract from markdown body (with src/ fallback) ──────────────
+        const refs = extractRefsFromMarkdown(raw, { projectRoot });
+        const page = {
+            name: pageName,
+            title,
+            content: raw,
+            refs,
+            generated_at,
+            source_hash,
+        };
+        pageCache.set(filePath, { mtimeMs: stat.mtimeMs, page });
+        return page;
+    }
+    catch {
+        return null;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Public API
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Keyword search over all KB pages.
+ *
+ * Algorithm:
+ *   1. Load all pages from `.forge-knowledge/` (top-level + modules/).
+ *   2. Tokenise the query string.
+ *   3. Score every page against the token list.
+ *   4. Return the top `maxResults` pages sorted by score descending.
+ *   5. Optionally include repo-map symbol hits for the same tokens.
+ *
+ * When the KB directory does not exist, returns an empty result without
+ * throwing so callers do not need to guard.
+ */
+export async function queryKnowledge(query, options = {}) {
+    const t0 = Date.now();
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const kbDir = path.join(projectRoot, K.KB_DIRNAME);
+    // Inner helper that writes the log row if storage is provided. Always
+    // fail-silent — telemetry MUST NEVER affect the user's main path.
+    const writeTelemetry = (resultCount) => {
+        if (!options.storage)
+            return;
+        try {
+            options.storage.writeKbQueryLog({
+                ts: Date.now(),
+                project_path: projectRoot,
+                query,
+                result_count: resultCount,
+                duration_ms: Date.now() - t0,
+            });
+        }
+        catch (err) {
+            logger.warn(`[KB] telemetry write failed: ${err}`);
+        }
+    };
+    if (!fs.existsSync(kbDir)) {
+        writeTelemetry(0);
+        return {
+            query,
+            pages: [],
+            total_pages_scanned: 0,
+        };
+    }
+    // Step 1: load all pages
+    const pages = await listKnowledge(projectRoot);
+    // Step 2: tokenise
+    const keywords = tokenize(query);
+    // Short-circuit: empty token list → nothing can match
+    if (keywords.length === 0) {
+        writeTelemetry(0);
+        return {
+            query,
+            pages: [],
+            total_pages_scanned: pages.length,
+        };
+    }
+    // Step 3: score every page
+    const hits = [];
+    for (const page of pages) {
+        const hit = scoreHit(page, keywords);
+        if (hit.score > 0)
+            hits.push(hit);
+    }
+    // Step 4: sort descending + cap
+    hits.sort((a, b) => b.score - a.score);
+    const maxResults = options.maxResults ?? 3;
+    const topHits = hits.slice(0, maxResults);
+    // Step 5: repo-map symbol search (optional, default on)
+    let repoMapHits;
+    if (options.includeRepoMap !== false) {
+        const repoMap = loadRepoMap(kbDir);
+        if (repoMap) {
+            const symbolHits = findSymbolHits(repoMap.symbols, keywords);
+            if (symbolHits.length > 0) {
+                repoMapHits = symbolHits;
+            }
+        }
+    }
+    const result = {
+        query,
+        pages: topHits,
+        repo_map_hits: repoMapHits,
+        total_pages_scanned: pages.length,
+    };
+    writeTelemetry(topHits.length);
+    return result;
+}
+/**
+ * List every KB page under `<projectRoot>/.forge-knowledge/`.
+ *
+ * Scans:
+ *   - Top-level `*.md` files (e.g. `overview.md`, `architecture.md`)
+ *   - `modules/*.md` files
+ *
+ * Pages that cannot be parsed are silently skipped.
+ */
+export async function listKnowledge(projectRoot = process.cwd()) {
+    const kbDir = path.join(projectRoot, K.KB_DIRNAME);
+    if (!fs.existsSync(kbDir))
+        return [];
+    const pages = [];
+    // ── Top-level .md files ───────────────────────────────────────────────────
+    for (const entry of fs.readdirSync(kbDir, { withFileTypes: true })) {
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.endsWith('.md'))
+            continue;
+        // Convention: any `.`-prefixed `.md` is KB metadata, not a page.
+        if (entry.name.startsWith('.'))
+            continue;
+        // Explicit safety net (mirrors the convention above; grep-friendly).
+        if (K.KB_META_MD_FILES.has(entry.name))
+            continue;
+        const page = loadPageFromFile(path.join(kbDir, entry.name), entry.name, projectRoot);
+        if (page)
+            pages.push(page);
+    }
+    // ── modules/ + agents-experience/ sub-directories ────────────────────────
+    // agents-experience/ holds runtime-accumulated lessons from PostToolUse
+    // changelog writeback (Phase 6). They are first-class KB pages so queries
+    // can surface past agent gotchas alongside the build-time module pages.
+    for (const subdir of [K.KB_MODULES_DIR, K.KB_AGENTS_EXPERIENCE_DIR]) {
+        const dirPath = path.join(kbDir, subdir);
+        if (!fs.existsSync(dirPath))
+            continue;
+        for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+            if (entry.isFile() && entry.name.endsWith('.md')) {
+                const pageName = `${subdir}/${entry.name}`;
+                const page = loadPageFromFile(path.join(dirPath, entry.name), pageName, projectRoot);
+                if (page)
+                    pages.push(page);
+            }
+        }
+    }
+    return pages;
+}
+/**
+ * Retrieve a single KB page by its `name` field (relative path within
+ * `.forge-knowledge/`, e.g. `"modules/daemon.md"`).
+ *
+ * Returns `null` when the page file does not exist.
+ */
+export async function getPage(name, projectRoot = process.cwd()) {
+    const filePath = path.join(projectRoot, K.KB_DIRNAME, name);
+    if (!fs.existsSync(filePath))
+        return null;
+    return loadPageFromFile(filePath, name, projectRoot);
+}
+/**
+ * Return `true` when the KB has been initialised in `projectRoot`
+ * (i.e. the `.meta.json` sentinel file is present inside `.forge-knowledge/`).
+ */
+export function isKnowledgeBuilt(projectRoot = process.cwd()) {
+    return fs.existsSync(path.join(projectRoot, K.KB_DIRNAME, K.KB_META_FILE));
+}
+//# sourceMappingURL=query.js.map

package/dist/knowledge/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../src/knowledge/query.ts"],"names":[],"mappings":"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"}

package/dist/knowledge/repo-map.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @file repo-map.ts
+ * Static layer of the KB system (Phase 1B).
+ *
+ * Uses the TypeScript Compiler API to extract symbols from the project's
+ * `src/` directory and produces a compact `RepoMap` JSON that downstream
+ * AI-compilation and query layers can consume.
+ *
+ * No AI calls are made here — this is a pure static-analysis pass.
+ */
+export type RepoMapSymbolKind = 'class' | 'function' | 'method' | 'interface' | 'type' | 'const' | 'enum';
+export interface RepoMapSymbol {
+    /** File path relative to `src/` (e.g. `daemon/handlers/tool-use.ts`). */
+    file: string;
+    /** 1-based line number. */
+    line: number;
+    kind: RepoMapSymbolKind;
+    /**
+     * Fully-qualified name.
+     * Methods are written as `ClassName.methodName`.
+     */
+    name: string;
+    /** Signature without body, single-line, max 200 chars. */
+    signature: string;
+    /** Whether the symbol carries an `export` modifier. */
+    exports: boolean;
+    /** Leading JSDoc comment, truncated to 200 chars. */
+    docComment?: string;
+}
+export interface RepoMap {
+    version: '1.0';
+    generated_at: string;
+    /** `git rev-parse --short HEAD` at generation time. */
+    source_hash: string;
+    symbols: RepoMapSymbol[];
+    file_count: number;
+    symbol_count: number;
+}
+/**
+ * Scan the `srcDir` directory and extract all symbols using the TypeScript
+ * Compiler API.
+ *
+ * @param srcDir Absolute path to `src/` (e.g. `path.join(cwd, 'src')`).
+ * @returns A fully-populated `RepoMap`.
+ */
+export declare function buildRepoMap(srcDir: string): RepoMap;
+/**
+ * v10.0 — Single-file symbol extraction.
+ *
+ * Adapter-friendly variant of {@link buildRepoMap}: parses one file's content
+ * via the TypeScript Compiler API and returns its symbols.  Used by
+ * `TypeScriptAdapter.parseSymbols` so adapters can drive the static layer one
+ * file at a time without re-running `ts.createProgram` for the whole repo.
+ *
+ * The existing batch path (`buildRepoMap`) is preserved verbatim so v9.5.x
+ * behavior is unchanged in v10.0.
+ *
+ * @param fileName     Absolute path of the file (used for diagnostics + line info).
+ * @param sourceText   File contents.
+ * @param projectRelPath Path written into `RepoMapSymbol.file` (relative to the
+ *                       project root, e.g. `src/daemon/server.ts`). The legacy
+ *                       batch path stores paths relative to `src/`; adapters
+ *                       are responsible for passing a value compatible with
+ *                       their KB layout.
+ * @returns extracted symbols (possibly empty).
+ */
+export declare function parseFileSymbols(fileName: string, sourceText: string, projectRelPath: string): RepoMapSymbol[];
+/**
+ * Persist a `RepoMap` to `<outDir>/repo-map.json`.
+ */
+export declare function writeRepoMap(outDir: string, repoMap: RepoMap): void;
+/**
+ * Load an existing `RepoMap` from `<outDir>/repo-map.json`.
+ * Returns `null` if the file does not exist or cannot be parsed.
+ */
+export declare function loadRepoMap(outDir: string): RepoMap | null;
+/**
+ * Return all symbols whose `file` path starts with `src/<moduleName>/`.
+ *
+ * @param repoMap  The repo-map to filter.
+ * @param moduleName  Module directory name (e.g. `'daemon'`).
+ */
+export declare function filterByModule(repoMap: RepoMap, moduleName: string): RepoMapSymbol[];
+/**
+ * Look up a single symbol by its fully-qualified name (exact match).
+ *
+ * @param repoMap  The repo-map to search.
+ * @param name  Symbol name (e.g. `'SocketServer'` or `'SocketServer.start'`).
+ */
+export declare function lookupSymbol(repoMap: RepoMap, name: string): RepoMapSymbol | null;
+//# sourceMappingURL=repo-map.d.ts.map

package/dist/knowledge/repo-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-map.d.ts","sourceRoot":"","sources":["../../src/knowledge/repo-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAWH,MAAM,MAAM,iBAAiB,GACzB,OAAO,GACP,UAAU,GACV,QAAQ,GACR,WAAW,GACX,MAAM,GACN,OAAO,GACP,MAAM,CAAC;AAEX,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,iBAAiB,CAAC;IACxB;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,OAAO,EAAE,OAAO,CAAC;IACjB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,KAAK,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAwTD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAsCpD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GACrB,aAAa,EAAE,CAuBjB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAGnE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAS1D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,aAAa,EAAE,CAGpF;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAEjF"}