@winspan/claude-forge 8.54.4 → 9.12.0

package/dist/knowledge/adapters/typescript-adapter.js

@@ -0,0 +1,171 @@
+/**
+ * @file adapters/typescript-adapter.ts
+ * v10.0 — TypeScript adapter.
+ *
+ * Wraps the existing v9.5.x TypeScript discovery / parsing logic in the
+ * {@link LanguageAdapter} contract.  Behaviour parity with v9.5.x is
+ * load-bearing: in v10.0 `builder.ts` does NOT yet route through this adapter
+ * (it still uses the hard-coded `src/` path), but adapter methods are
+ * structured so v10.5 can swap them in without surprises.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseFileSymbols } from '../repo-map.js';
+/**
+ * Normalise a filesystem path to POSIX-style for storage inside the KB.
+ * Keeping a single convention means refs are portable across OSes.
+ */
+function toPosix(p) {
+    return p.split(path.sep).join('/');
+}
+/**
+ * Existence probe (Phase 2b-1, route A): does `dir` (recursively, depth-bounded)
+ * contain at least one non-declaration `.ts` source?  Used by `detect` to
+ * distinguish a genuine TS project (lacking `tsconfig.json`) from a pure Vue/JS
+ * project.  Returns on the first hit; skips `node_modules`/hidden dirs.
+ */
+function hasTsSource(dir, depth = 0) {
+    if (depth > 6)
+        return false;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    for (const e of entries) {
+        if (e.isFile() && e.name.endsWith('.ts') && !e.name.endsWith('.d.ts'))
+            return true;
+        if (e.isDirectory()) {
+            if (e.name === 'node_modules' || e.name.startsWith('.'))
+                continue;
+            if (hasTsSource(path.join(dir, e.name), depth + 1))
+                return true;
+        }
+    }
+    return false;
+}
+export class TypeScriptAdapter {
+    name = 'typescript';
+    fileExtensions = ['.ts'];
+    /**
+     * Project is TypeScript iff it has `package.json` + a `src/` directory AND
+     * is genuinely TS — i.e. a `tsconfig.json` exists OR a `.ts` source is
+     * reachable.  Phase 2b-1 (route A): this last clause keeps pure Vue/JS
+     * projects (no tsconfig, no `.ts`) from being claimed here so they fall
+     * through to `JsVueAdapter`.  claude-forge itself ships `tsconfig.json`, so
+     * its detection — and therefore its module hashes — are byte-for-byte
+     * unchanged (zero drift).
+     */
+    detect(projectRoot) {
+        if (!fs.existsSync(path.join(projectRoot, 'package.json')) ||
+            !fs.existsSync(path.join(projectRoot, 'src'))) {
+            return false;
+        }
+        if (fs.existsSync(path.join(projectRoot, 'tsconfig.json')))
+            return true;
+        return hasTsSource(path.join(projectRoot, 'src'));
+    }
+    /** v9.5.x: single source root at `<root>/src`. */
+    discoverSourceRoots(projectRoot) {
+        return [path.join(projectRoot, 'src')];
+    }
+    /**
+     * Equivalent to `builder.ts:discoverModules` — every first-level subdirectory
+     * of `src/` is one module.  Returns an empty array when `src/` is missing
+     * (defensive; callers should usually consult `detect()` first).
+     */
+    discoverModules(projectRoot) {
+        const srcDir = path.join(projectRoot, 'src');
+        if (!fs.existsSync(srcDir))
+            return [];
+        const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isDirectory())
+            .map((e) => ({
+            name: e.name,
+            rootDir: path.join(srcDir, e.name),
+            refPrefix: e.name,
+        }))
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    /**
+     * Equivalent to `builder.ts:readModuleFiles` + `module-hash.ts:collectModuleFiles`:
+     * recursively gather `.ts` files (excluding `.test.ts`, `.d.ts`, `node_modules`,
+     * hidden dirs).  Paths are returned as POSIX-style strings.
+     */
+    async walkModuleFiles(module) {
+        const results = [];
+        // Module's root → projectRoot lives one level above `src/`.
+        // moduleRoot = `<projectRoot>/src/<name>`; projectRoot = `<...>/`.
+        const projectRoot = path.resolve(module.rootDir, '..', '..');
+        const walk = async (dir) => {
+            let entries;
+            try {
+                entries = (await fs.promises.readdir(dir, {
+                    withFileTypes: true,
+                }));
+            }
+            catch {
+                return;
+            }
+            for (const e of entries) {
+                const name = e.name;
+                const full = path.join(dir, name);
+                if (e.isDirectory()) {
+                    if (name === 'node_modules' || name.startsWith('.'))
+                        continue;
+                    await walk(full);
+                }
+                else if (e.isFile() &&
+                    name.endsWith('.ts') &&
+                    !name.endsWith('.test.ts') &&
+                    !name.endsWith('.d.ts')) {
+                    try {
+                        const content = await fs.promises.readFile(full, 'utf-8');
+                        results.push({
+                            relPath: toPosix(path.relative(module.rootDir, full)),
+                            projectRelPath: toPosix(path.relative(projectRoot, full)),
+                            content,
+                        });
+                    }
+                    catch {
+                        // Skip unreadable files silently (parity with builder.ts).
+                    }
+                }
+            }
+        };
+        await walk(module.rootDir);
+        return results;
+    }
+    /**
+     * Parse one source file via the TypeScript Compiler API and return its
+     * symbols.  Delegates to {@link parseFileSymbols} (helper added in v10.0 to
+     * keep the legacy `buildRepoMap` batch path intact).
+     *
+     * `RepoMapSymbol.file` is set to the file's `projectRelPath` (e.g.
+     * `src/daemon/server.ts`) to match the convention used elsewhere in v10.x.
+     *
+     * v10.1.1: Changed to async for consistency with other adapters (tree-sitter-based).
+     */
+    async parseSymbols(file) {
+        // Synthesise an absolute file name for the TS Compiler.  parseFileSymbols
+        // only uses it for diagnostics + to derive line/column info.
+        const absName = file.projectRelPath;
+        return parseFileSymbols(absName, file.content, file.projectRelPath);
+    }
+    /** Returns the canonical manifest + a curated list of well-known config files. */
+    describeProjectMeta(projectRoot) {
+        const manifestPath = path.join(projectRoot, 'package.json');
+        const candidates = [
+            path.join(projectRoot, 'tsconfig.json'),
+            path.join(projectRoot, 'vitest.config.ts'),
+        ];
+        return {
+            manifestPath: fs.existsSync(manifestPath) ? manifestPath : null,
+            configPaths: candidates.filter((p) => fs.existsSync(p)),
+        };
+    }
+}
+//# sourceMappingURL=typescript-adapter.js.map

package/dist/knowledge/adapters/typescript-adapter.js.map

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

package/dist/knowledge/audit-applier.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @file audit-applier.ts
+ * Knowledge Base audit-result applier.
+ *
+ * Consumed by `cf knowledge audit --fix` to persist per-page audit verdicts:
+ *   1. Update `.forge-knowledge/.meta.json` — `pages[name].audit_status`
+ *      (atomic write via `.meta.json.tmp` + rename).
+ *   2. Append a reverse-chronological section to `.forge-knowledge/.audit-log.md`
+ *      (best-effort; failure does not abort the meta update).
+ *
+ * Single source of truth contract:
+ *   `.meta.json` is the canonical record of `audit_status`. The KBPage
+ *   markdown frontmatter is written once at build time and is NEVER
+ *   re-synced by this module. Any consumer that needs the current audit
+ *   status MUST read `.meta.json` first and only fall back to frontmatter
+ *   when the page is missing from meta.
+ */
+import type { ValidationIssue } from './types.js';
+/** Per-page audit verdict supplied by `auditCmd`. */
+export interface AuditPageResult {
+    /** Page name, e.g. `modules/daemon.md`. */
+    name: string;
+    /** Verdict derived from `deriveAuditStatus(issues)`. */
+    status: 'ok' | 'stale' | 'error';
+    /** Raw issues from `validatePage` (rendered verbatim into the log). */
+    issues: ValidationIssue[];
+}
+/** Input options for {@link applyAuditResult}. */
+export interface AuditApplyOptions {
+    /** Absolute path to `.forge-knowledge/`. */
+    kbDir: string;
+    /** Per-page audit results to persist. Empty array → no-op. */
+    results: AuditPageResult[];
+    /** Current git HEAD short hash (recorded in log header). */
+    sourceHash: string;
+    /** Injected clock for deterministic tests. Defaults to `new Date()`. */
+    now?: Date;
+}
+/** Outcome of an apply call (used by callers and tests). */
+export interface AuditApplyOutcome {
+    /** True when `.meta.json` was rewritten. */
+    metaUpdated: boolean;
+    /** True when a new section was appended to `.audit-log.md`. */
+    logAppended: boolean;
+    /** Absolute path to the audit log file. */
+    logPath: string;
+    /** Absolute path to the meta file. */
+    metaPath: string;
+}
+/**
+ * Map a list of validation issues to a single audit status.
+ *
+ * Decision tree:
+ *   - no issues                                   → 'ok'
+ *   - any issue.severity === 'error'              → 'error'
+ *   - any issue.severity === 'warn' (no error)    → 'stale'
+ *   - otherwise (only 'info' issues, or empty)    → 'ok'
+ */
+export declare function deriveAuditStatus(issues: ValidationIssue[]): 'ok' | 'stale' | 'error';
+/**
+ * Apply a batch of per-page audit results to disk.
+ *
+ * Order of operations:
+ *   1. Read existing `.meta.json`, patch `pages[name].audit_status`.
+ *   2. Atomic write via `.meta.json.tmp` + `renameSync`.
+ *   3. Best-effort: prepend a new section to `.audit-log.md`.
+ *      Failures here log to stderr but do not throw.
+ */
+export declare function applyAuditResult(opts: AuditApplyOptions): AuditApplyOutcome;
+//# sourceMappingURL=audit-applier.d.ts.map

package/dist/knowledge/audit-applier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-applier.d.ts","sourceRoot":"","sources":["../../src/knowledge/audit-applier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAYH,OAAO,KAAK,EAAU,eAAe,EAAE,MAAM,YAAY,CAAC;AAO1D,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IAEb,wDAAwD;IACxD,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,OAAO,CAAC;IAEjC,uEAAuE;IACvE,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IAEd,8DAA8D;IAC9D,OAAO,EAAE,eAAe,EAAE,CAAC;IAE3B,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IAEnB,wEAAwE;IACxE,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,4DAA4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,WAAW,EAAE,OAAO,CAAC;IAErB,+DAA+D;IAC/D,WAAW,EAAE,OAAO,CAAC;IAErB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAEhB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,eAAe,EAAE,GACxB,IAAI,GAAG,OAAO,GAAG,OAAO,CAK1B;AAMD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,iBAAiB,CAiG3E"}

package/dist/knowledge/audit-applier.js

@@ -0,0 +1,251 @@
+/**
+ * @file audit-applier.ts
+ * Knowledge Base audit-result applier.
+ *
+ * Consumed by `cf knowledge audit --fix` to persist per-page audit verdicts:
+ *   1. Update `.forge-knowledge/.meta.json` — `pages[name].audit_status`
+ *      (atomic write via `.meta.json.tmp` + rename).
+ *   2. Append a reverse-chronological section to `.forge-knowledge/.audit-log.md`
+ *      (best-effort; failure does not abort the meta update).
+ *
+ * Single source of truth contract:
+ *   `.meta.json` is the canonical record of `audit_status`. The KBPage
+ *   markdown frontmatter is written once at build time and is NEVER
+ *   re-synced by this module. Any consumer that needs the current audit
+ *   status MUST read `.meta.json` first and only fall back to frontmatter
+ *   when the page is missing from meta.
+ */
+import { existsSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import path from 'node:path';
+import * as K from './constants.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// deriveAuditStatus
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Map a list of validation issues to a single audit status.
+ *
+ * Decision tree:
+ *   - no issues                                   → 'ok'
+ *   - any issue.severity === 'error'              → 'error'
+ *   - any issue.severity === 'warn' (no error)    → 'stale'
+ *   - otherwise (only 'info' issues, or empty)    → 'ok'
+ */
+export function deriveAuditStatus(issues) {
+    if (!issues || issues.length === 0)
+        return 'ok';
+    if (issues.some((iss) => iss.severity === 'error'))
+        return 'error';
+    if (issues.some((iss) => iss.severity === 'warn'))
+        return 'stale';
+    return 'ok';
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// applyAuditResult
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Apply a batch of per-page audit results to disk.
+ *
+ * Order of operations:
+ *   1. Read existing `.meta.json`, patch `pages[name].audit_status`.
+ *   2. Atomic write via `.meta.json.tmp` + `renameSync`.
+ *   3. Best-effort: prepend a new section to `.audit-log.md`.
+ *      Failures here log to stderr but do not throw.
+ */
+export function applyAuditResult(opts) {
+    const { kbDir, results, sourceHash } = opts;
+    const now = opts.now ?? new Date();
+    const metaPath = path.join(kbDir, K.KB_META_FILE);
+    const logPath = path.join(kbDir, '.audit-log.md');
+    // No-op for empty input.
+    if (results.length === 0) {
+        return {
+            metaUpdated: false,
+            logAppended: false,
+            logPath,
+            metaPath,
+        };
+    }
+    // ── Step 1: update .meta.json (atomic) ────────────────────────────────────
+    const metaRaw = readFileSync(metaPath, 'utf-8');
+    const meta = JSON.parse(metaRaw);
+    meta.pages = meta.pages ?? {};
+    for (const r of results) {
+        const existing = meta.pages[r.name];
+        if (existing) {
+            existing.audit_status = r.status;
+        }
+        else {
+            // Page absent from meta (edge case): create a minimal placeholder so
+            // the audit status is still recorded.
+            meta.pages[r.name] = {
+                source_files: [],
+                source_hash: '',
+                ai_model: 'unknown',
+                refs_count: 0,
+                audit_status: r.status,
+            };
+        }
+    }
+    const tmpPath = `${metaPath}.tmp`;
+    try {
+        writeFileSync(tmpPath, JSON.stringify(meta, null, 2));
+        renameSync(tmpPath, metaPath);
+    }
+    catch (err) {
+        // Best-effort cleanup; ignore secondary failure.
+        try {
+            if (existsSync(tmpPath))
+                unlinkSync(tmpPath);
+        }
+        catch {
+            /* swallow */
+        }
+        throw err;
+    }
+    // ── Step 2: append to .audit-log.md (best-effort) ─────────────────────────
+    let logAppended = false;
+    try {
+        const section = renderSection(results, sourceHash, now);
+        if (!existsSync(logPath)) {
+            const header = '# Knowledge Base Audit Log\n\n' +
+                '> Generated by `cf knowledge audit --fix`. Newest entries at top.\n\n' +
+                '---\n\n';
+            writeFileSync(logPath, header + section);
+        }
+        else {
+            // Reverse-chronological: insert the new section right after the leading
+            // H1 + description + first `---` separator, preserving everything else
+            // byte-for-byte.
+            const existing = readFileSync(logPath, 'utf-8');
+            const updated = prependSection(existing, section);
+            writeFileSync(logPath, updated);
+        }
+        logAppended = true;
+        // 1MB warning (post-write).
+        try {
+            const size = statSync(logPath).size;
+            if (size > K.KB_AUDIT_LOG_WARN_SIZE) {
+                process.stderr.write(`audit-log.md is over 1MB (${size} bytes), consider archiving\n`);
+            }
+        }
+        catch {
+            /* swallow */
+        }
+    }
+    catch (err) {
+        process.stderr.write(`audit-log update failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        logAppended = false;
+    }
+    return {
+        metaUpdated: true,
+        logAppended,
+        logPath,
+        metaPath,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Render one log section for a single audit run.
+ *
+ * Format mirrors spec §3.2:
+ *   ## <ISO timestamp> (source: <hash>, kb-version: <ver>)
+ *   **Summary**: ...
+ *   ### Stale pages (N) / Error pages (N) / OK pages (N)
+ *   ### Suggested actions
+ */
+function renderSection(results, sourceHash, now) {
+    const stale = results.filter((r) => r.status === 'stale');
+    const errored = results.filter((r) => r.status === 'error');
+    const okPages = results.filter((r) => r.status === 'ok');
+    const lines = [];
+    lines.push(`## ${now.toISOString()} (source: ${sourceHash}, kb-version: ${K.KB_VERSION})`);
+    lines.push('');
+    lines.push(`**Summary**: ${results.length} pages audited — ${okPages.length} ok, ${stale.length} stale, ${errored.length} error`);
+    lines.push('');
+    if (results.length > 0 && stale.length === 0 && errored.length === 0) {
+        lines.push('All OK');
+        lines.push('');
+    }
+    if (stale.length > 0) {
+        lines.push(`### Stale pages (${stale.length})`);
+        lines.push('');
+        for (const p of stale) {
+            const warnIssues = p.issues.filter((i) => i.severity === 'warn');
+            lines.push(`- \`${p.name}\` — ${warnIssues.length} issue(s)`);
+            for (const iss of warnIssues) {
+                lines.push(`  - ${iss.msg}`);
+            }
+        }
+        lines.push('');
+    }
+    if (errored.length > 0) {
+        lines.push(`### Error pages (${errored.length})`);
+        lines.push('');
+        for (const p of errored) {
+            const errIssues = p.issues.filter((i) => i.severity === 'error');
+            lines.push(`- \`${p.name}\` — ${errIssues.length} issue(s)`);
+            for (const iss of errIssues) {
+                lines.push(`  - ${iss.msg}`);
+            }
+        }
+        lines.push('');
+    }
+    if (okPages.length > 0) {
+        lines.push(`### OK pages (${okPages.length})`);
+        lines.push('');
+        for (const p of okPages) {
+            lines.push(`- \`${p.name}\``);
+        }
+        lines.push('');
+    }
+    if (stale.length > 0 || errored.length > 0) {
+        lines.push('### Suggested actions');
+        lines.push('');
+        const suggested = new Set();
+        for (const p of [...stale, ...errored]) {
+            // Derive a module-ish hint from page name, e.g. modules/daemon.md → daemon
+            const m = p.name.match(/^modules\/([^/]+)\.md$/);
+            if (m)
+                suggested.add(m[1]);
+        }
+        if (suggested.size === 0) {
+            lines.push('- Run `cf knowledge update` to refresh affected pages');
+        }
+        else {
+            for (const name of suggested) {
+                lines.push(`- Run \`cf knowledge update --module ${name}\` to refresh`);
+            }
+        }
+        lines.push('');
+    }
+    lines.push('---');
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Insert `section` between the leading H1/description block (ending at the
+ * first `---` separator) and the rest of the file.
+ *
+ * If no `---` separator is found we treat the entire file as legacy content
+ * and prepend our own H1 + separator before it (defensive, should not occur
+ * for files we created).
+ */
+function prependSection(existing, section) {
+    // Find the first standalone `---` line that terminates the header.
+    const sepIdx = existing.indexOf('\n---\n');
+    if (sepIdx === -1) {
+        const header = '# Knowledge Base Audit Log\n\n' +
+            '> Generated by `cf knowledge audit --fix`. Newest entries at top.\n\n' +
+            '---\n\n';
+        return header + section + existing;
+    }
+    const headerEnd = sepIdx + '\n---\n'.length;
+    const head = existing.slice(0, headerEnd);
+    const tail = existing.slice(headerEnd);
+    // Ensure a blank line between separator and new section.
+    const glue = head.endsWith('\n') ? '\n' : '\n\n';
+    return head + glue + section + tail;
+}
+//# sourceMappingURL=audit-applier.js.map

package/dist/knowledge/audit-applier.js.map

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