@winspan/claude-forge 8.54.4 → 9.2.0

package/dist/knowledge/builder.d.ts

@@ -0,0 +1,261 @@
+/**
+ * @file builder.ts
+ * KB Phase 2 — AI compilation layer orchestrator.
+ *
+ * Main entry point: `buildKnowledge(options?)`.
+ *
+ * Pipeline:
+ *   1. Static layer   → buildRepoMap (TypeScript Compiler API)
+ *   2. Discover       → src/ first-level subdirectories
+ *   3. AI compile     → buildModulePage per module (concurrency-limited)
+ *   4. Validate       → validatePage on each compiled page
+ *   5. Report         → generateBuildReport → ~/.claude-forge/knowledge-build-report.md
+ *   6. Apply (opt)    → applyPages → .forge-knowledge/modules/*.md + .meta.json + repo-map.json
+ *
+ * ── v9.1.2: module-hash cache ──────────────────────────────────────────────
+ * Per-module SHA-256 fingerprints (see module-hash.ts) are stored in
+ * `KBMeta.pages[*].source_hash`. When a hash matches the previous build, the
+ * AI call is skipped and the existing `.md` is left in place.
+ *
+ * Bypass mechanism: `BuildOptions.force = true` (CLI: `--force`).
+ *
+ * Known cache-aware-of-nothing edge: changes to `prompt.ts` do NOT invalidate
+ * cached pages. Run `--force` after prompt edits.
+ *
+ * Cross-module overview / architecture pages are reserved for Phase 3.
+ */
+import type { KBPage, ValidationResult } from './types.js';
+import type { RepoMap } from './repo-map.js';
+import type { SourceFile } from './adapters/types.js';
+/**
+ * Minimal structural shape that builder.ts consumes from any AI provider.
+ *
+ * Production wiring goes through `CliKnowledgeProvider` (cli-provider.ts).
+ * Tests inject a mock that matches this shape so the build pipeline can be
+ * exercised end-to-end without spawning a subprocess.
+ */
+export interface AIProviderLike {
+    completeWithUsage(prompt: string, options?: {
+        system?: string;
+        maxTokens?: number;
+        timeoutMs?: number;
+    }): Promise<{
+        text: string;
+        model?: string;
+        usage?: {
+            input_tokens: number;
+            output_tokens: number;
+        };
+    }>;
+}
+/**
+ * v9.4: Build event types emitted via the optional `onEvent` callback.
+ *
+ * Consumers (currently: web SSE) use the discriminated `type` field. Any
+ * additional fields are optional metadata. New event types may be added in
+ * a backward-compatible manner — clients should tolerate unknown `type`s.
+ */
+export type BuildEvent = {
+    type: 'start';
+    modules: string[];
+    force: boolean;
+    apply: boolean;
+    skipCrossModule: boolean;
+} | {
+    type: 'repo-map';
+    symbolCount: number;
+    fileCount: number;
+    sourceHash: string;
+} | {
+    type: 'module';
+    name: string;
+    status: 'compiling';
+} | {
+    type: 'module';
+    name: string;
+    status: 'ok' | 'issues' | 'failed';
+    refsValid?: number;
+    refsTotal?: number;
+    durationMs?: number;
+    cached?: boolean;
+} | {
+    type: 'cross-module';
+    name: string;
+    status: 'compiling';
+} | {
+    type: 'cross-module';
+    name: string;
+    status: 'ok' | 'failed' | 'cached';
+    durationMs?: number;
+    cached?: boolean;
+} | {
+    type: 'done';
+    stats: BuildResult['stats'];
+    reportPath: string;
+    appliedTo?: string;
+} | {
+    type: 'error';
+    message: string;
+    step?: string;
+};
+export interface BuildOptions {
+    /** Project root to scan. Defaults to `process.cwd()`. */
+    projectRoot?: string;
+    /**
+     * Restrict compilation to these modules (first-level `src/` subdirectories).
+     * When undefined every discovered module is compiled.
+     */
+    modules?: string[];
+    /**
+     * Force a full rebuild even if `source_hash` matches the last run.
+     * When `true`, every module's AI compilation runs regardless of cache state.
+     */
+    force?: boolean;
+    /**
+     * `false` (default) → dry-run: only generate the report, no files written.
+     * `true`            → apply: write pages to `.forge-knowledge/`.
+     */
+    apply?: boolean;
+    /** Output path for the build report. Defaults to `K.KB_BUILD_REPORT_PATH`. */
+    reportPath?: string;
+    /** Maximum number of concurrent AI module-compilation calls. Defaults to `K.KB_MAX_CONCURRENCY`. */
+    maxConcurrency?: number;
+    /**
+     * Test-only injection door for a mock AI provider.
+     *
+     * Production code MUST NOT set this — the field exists exclusively so that
+     * `builder-incremental.test.ts`, `builder.test.ts`, `cross-module.test.ts`
+     * and similar fixtures can exercise the pipeline without spawning a
+     * subprocess. When omitted, builder defaults to `CliKnowledgeProvider`
+     * (cli-provider.ts) which spawns `claude --agent knowledge-builder ...`.
+     *
+     * Spec: docs/design/2026-05-29/0902-ai-config-removal-master-spec.md §2.4.2
+     * Decision: f5a5b030 sub-spec B R-D — retained intentionally as the
+     * lowest-risk test seam; tests are not refactored to spawn-level stubs in
+     * this phase.
+     */
+    aiProvider?: AIProviderLike;
+    /**
+     * v9.2: When `true`, skip generating the 5 cross-module pages
+     * (overview/architecture/decisions/glossary/tech-stack). Default `false` —
+     * cross-module pages are produced on every build.
+     *
+     * CLI: `--skip-cross-module`.
+     */
+    skipCrossModule?: boolean;
+    /**
+     * v9.4: optional event sink for real-time progress (used by web SSE).
+     *
+     * Backward-compatible: CLI callers do not set this. Listener errors are
+     * caught internally and never propagate to `buildKnowledge`.
+     */
+    onEvent?: (event: BuildEvent) => void;
+}
+export interface BuildResult {
+    /** Whether this was a preview or a live run. */
+    mode: 'dry-run' | 'apply';
+    /** Per-page compilation + validation results. */
+    pages: Array<{
+        /** Page name / relative path within `.forge-knowledge/`. */
+        name: string;
+        /** Compiled page content and metadata. */
+        page: KBPage;
+        /** Ref-validation result for this page. */
+        validation: ValidationResult;
+        /** `true` when no error-level validation issues were found. */
+        ready: boolean;
+        /**
+         * `true` when this page was reused from the previous build via module
+         * hash match. `false` when freshly compiled by the AI (or when this is
+         * the first build and there is no prior cache).
+         */
+        cached: boolean;
+        /**
+         * v9.2: Page kind. `'module'` for `modules/<name>.md` pages,
+         * `'cross'` for the five cross-module root pages (overview/architecture/
+         * decisions/glossary/tech-stack). Optional for backward compatibility —
+         * pre-v9.2 consumers can ignore this field.
+         */
+        kind?: 'module' | 'cross';
+        /**
+         * Project-relative POSIX paths of the source files that fed the AI prompt
+         * for this page. Persisted to `.meta.json.pages[name].source_files`.
+         *
+         * Population rules:
+         *   - module pages, fresh compile → `adapter.walkModuleFiles(mod)`
+         *     (the same set fed to the prompt).
+         *   - module pages, cache hit     → previous `oldMeta.pages[name].source_files`
+         *     when available; otherwise re-walked from disk.
+         *   - cross-module pages          → `undefined` (writeMetadata falls back to []).
+         *
+         * Optional for backward compatibility with tests that synthesize page
+         * entries directly.
+         */
+        sourceFiles?: string[];
+    }>;
+    /** Absolute path to the written build report. */
+    reportPath: string;
+    /** Absolute path to `.forge-knowledge/` — only present in `apply` mode. */
+    appliedTo?: string;
+    /** Per-build cache hit/miss summary. */
+    stats: {
+        /** Pages that ran the AI compiler this build. */
+        built: number;
+        /** Pages reused via module hash cache. */
+        cached: number;
+        /** Total pages produced (= built + cached). */
+        total: number;
+        /** v9.2: cross-module pages freshly compiled by AI this build. */
+        crossModuleBuilt?: number;
+        /** v9.2: cross-module pages reused via cross hash cache. */
+        crossModuleCached?: number;
+    };
+}
+/**
+ * Main entry: scan source roots → buildRepoMap → AI-compile each module →
+ * validate refs → write dry-run report.  When `options.apply` is `true`,
+ * pages are also persisted to `.forge-knowledge/`.
+ *
+ * v10.1: Uses LanguageAdapter to support multi-language projects (TypeScript + Java).
+ */
+export declare function buildKnowledge(options?: BuildOptions): Promise<BuildResult>;
+/**
+ * Compile a single module knowledge page.
+ *
+ * Called by `buildKnowledge` internally and exported for use by
+ * `cf knowledge build --module <name>` (Phase 3 CLI).
+ *
+ * On AI failure (malformed response / API error) the function returns an
+ * invalid page rather than throwing, so the overall build continues.
+ *
+ * v10.1: Accepts SourceFile[] from adapter instead of legacy { path, content }.
+ */
+export declare function buildModulePage(moduleName: string, files: Array<SourceFile | {
+    path: string;
+    content: string;
+}>, repoMap: RepoMap, ai: AIProviderLike, projectName?: string): Promise<{
+    page: KBPage;
+    validation: ValidationResult;
+}>;
+/**
+ * Write a markdown dry-run report to `reportPath`.
+ *
+ * Uses synchronous fs calls so this function can remain non-async and
+ * be called easily from both CLI and test contexts.
+ */
+export declare function generateBuildReport(result: BuildResult, options: {
+    reportPath: string;
+}): void;
+/**
+ * Write compiled pages to `.forge-knowledge/`, backing up any
+ * previous content into `.forge-knowledge/backups/<timestamp>/`.
+ *
+ * Backs up both `modules/<name>.md` and the 5 root-level cross-module pages
+ * (`overview.md` / `architecture.md` / `decisions.md` / `glossary.md` /
+ * `tech-stack.md`) so `cf knowledge rollback` can restore the full set.
+ */
+export declare function applyPages(pages: BuildResult['pages'], projectRoot: string): {
+    appliedPath: string;
+    backupPath: string;
+};
+//# sourceMappingURL=builder.d.ts.map

package/dist/knowledge/builder.d.ts.map

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