@winspan/claude-forge 8.54.4 → 9.12.0

package/dist/knowledge/graph/impact.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @file impact.ts
+ * Impact analysis over the codegraph (Phase 2).
+ *
+ * decision 95df9d97 / spec 1112-codegraph-call-graph-spec.md (Phase 2).
+ *
+ * "改这个符号会影响谁" — compute the transitive set of symbols that would be
+ * affected by changing a target symbol. This is a reverse-edge BFS: from the
+ * target node we walk `getCallers` (callers point AT the target via a `calls`
+ * edge) outward, level by level, accumulating every caller reachable within
+ * `maxDepth` hops. A visited-set guards against cycles (A→B→A) so the BFS
+ * always terminates.
+ */
+import type { CodeGraphStore, SymbolCandidate } from '../../core/storage/codegraph.js';
+/** A single impacted symbol, annotated with the BFS depth it was reached at. */
+export interface ImpactedSymbol {
+    /** Fully-qualified symbol name. */
+    name: string;
+    /** File path relative to src root. */
+    file: string;
+    /** 1-based DECLARATION line of the impacted symbol. */
+    line: number;
+    /**
+     * 1-based line of the call site through which this symbol was reached (the
+     * exact reference, not the caller's declaration). `null` for edges stored
+     * before the call_line column existed.
+     */
+    call_line: number | null;
+    /** Symbol kind. */
+    kind: string;
+    /** BFS depth at which this symbol was first reached (1 = direct caller). */
+    depth: number;
+}
+/** Options for {@link computeImpact}. */
+export interface ComputeImpactOptions {
+    /** Maximum reverse-BFS depth (hops away from the target). Default 5. */
+    maxDepth?: number;
+}
+/** Result of {@link computeImpact}. */
+export interface ImpactResult {
+    /** The symbol whose impact was computed. */
+    symbol: string;
+    /** Whether the target symbol exists in the graph. */
+    found: boolean;
+    /** The effective maxDepth used. */
+    maxDepth: number;
+    /** Whether the BFS was cut off by maxDepth (more impact may exist deeper). */
+    truncated: boolean;
+    /** Transitively impacted callers, ordered by ascending depth then name. */
+    impacted: ImpactedSymbol[];
+    /**
+     * When the symbol is ambiguous (bare name → multiple candidates), the BFS is
+     * skipped and these candidates are returned so the caller can re-query with a
+     * disambiguated name. Empty when the symbol resolved cleanly.
+     */
+    candidates?: SymbolCandidate[];
+    /** How the target symbol was resolved (exact / suffix / ambiguous / none). */
+    resolvedVia?: 'exact' | 'exact-ambiguous' | 'suffix' | 'suffix-ambiguous' | 'none';
+}
+/**
+ * Compute the transitive impact set of `nodeName` — every symbol that
+ * (transitively) calls it, up to `maxDepth` hops.
+ *
+ * Reverse BFS over `calls` edges via {@link CodeGraphStore.getCallers}. A
+ * visited set keyed by symbol name prevents revisiting nodes (cycle-safe). The
+ * target symbol itself is never included in the result.
+ *
+ * @param store     the codegraph store to query.
+ * @param nodeName  fully-qualified symbol name to analyze.
+ * @param options   `{ maxDepth }` — defaults to 5.
+ */
+export declare function computeImpact(store: CodeGraphStore, nodeName: string, options?: ComputeImpactOptions): ImpactResult;
+//# sourceMappingURL=impact.d.ts.map

package/dist/knowledge/graph/impact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"impact.d.ts","sourceRoot":"","sources":["../../../src/knowledge/graph/impact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EAChB,MAAM,iCAAiC,CAAC;AAEzC,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC7B,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;CACf;AAED,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACnC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,KAAK,EAAE,OAAO,CAAC;IACf,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,SAAS,EAAE,OAAO,CAAC;IACnB,2EAA2E;IAC3E,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B;;;;OAIG;IACH,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;IAC/B,8EAA8E;IAC9E,WAAW,CAAC,EAAE,OAAO,GAAG,iBAAiB,GAAG,QAAQ,GAAG,kBAAkB,GAAG,MAAM,CAAC;CACpF;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,oBAAyB,GACjC,YAAY,CAyEd"}

package/dist/knowledge/graph/impact.js

@@ -0,0 +1,94 @@
+/**
+ * @file impact.ts
+ * Impact analysis over the codegraph (Phase 2).
+ *
+ * decision 95df9d97 / spec 1112-codegraph-call-graph-spec.md (Phase 2).
+ *
+ * "改这个符号会影响谁" — compute the transitive set of symbols that would be
+ * affected by changing a target symbol. This is a reverse-edge BFS: from the
+ * target node we walk `getCallers` (callers point AT the target via a `calls`
+ * edge) outward, level by level, accumulating every caller reachable within
+ * `maxDepth` hops. A visited-set guards against cycles (A→B→A) so the BFS
+ * always terminates.
+ */
+const DEFAULT_MAX_DEPTH = 5;
+/**
+ * Compute the transitive impact set of `nodeName` — every symbol that
+ * (transitively) calls it, up to `maxDepth` hops.
+ *
+ * Reverse BFS over `calls` edges via {@link CodeGraphStore.getCallers}. A
+ * visited set keyed by symbol name prevents revisiting nodes (cycle-safe). The
+ * target symbol itself is never included in the result.
+ *
+ * @param store     the codegraph store to query.
+ * @param nodeName  fully-qualified symbol name to analyze.
+ * @param options   `{ maxDepth }` — defaults to 5.
+ */
+export function computeImpact(store, nodeName, options = {}) {
+    const rawDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+    // Clamp to a sane positive integer so a caller cannot request depth 0 / -1.
+    const maxDepth = Math.max(1, Math.floor(rawDepth));
+    // Resolve the target through exact → suffix matching (bare names usable).
+    const resolution = store.resolveSymbol(nodeName);
+    const target = resolution.node;
+    const found = target !== null;
+    if (!found) {
+        // Ambiguous? Surface candidates so the caller can re-query; don't BFS a
+        // guess. Truly-missing → empty candidates.
+        return {
+            symbol: nodeName,
+            found: false,
+            maxDepth,
+            truncated: false,
+            impacted: [],
+            candidates: resolution.candidates,
+            resolvedVia: resolution.via,
+        };
+    }
+    // Traverse by node_id, NOT name — same-named symbols (22 `register`s) keep
+    // their caller sets separate instead of串台. visited is keyed by node_id.
+    const visited = new Set([target.node_id]);
+    const impacted = [];
+    // BFS frontier: node ids discovered at the previous depth still to expand.
+    let frontier = [target.node_id];
+    let depth = 0;
+    let truncated = false;
+    while (frontier.length > 0) {
+        depth += 1;
+        if (depth > maxDepth) {
+            // There were still nodes to expand but we hit the depth cap.
+            truncated = true;
+            break;
+        }
+        const nextFrontier = [];
+        for (const current of frontier) {
+            const callers = store.getCallers('', current);
+            for (const caller of callers) {
+                if (visited.has(caller.node_id))
+                    continue;
+                visited.add(caller.node_id);
+                impacted.push({
+                    name: caller.name,
+                    file: caller.file,
+                    line: caller.line,
+                    call_line: caller.call_line,
+                    kind: caller.kind,
+                    depth,
+                });
+                nextFrontier.push(caller.node_id);
+            }
+        }
+        frontier = nextFrontier;
+    }
+    // Stable ordering: ascending depth, then name.
+    impacted.sort((a, b) => a.depth - b.depth || a.name.localeCompare(b.name));
+    return {
+        symbol: nodeName,
+        found,
+        maxDepth,
+        truncated,
+        impacted,
+        resolvedVia: resolution.via,
+    };
+}
+//# sourceMappingURL=impact.js.map

package/dist/knowledge/graph/impact.js.map

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

package/dist/knowledge/graph/types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @file types.ts
+ * Shared types for the codegraph (call-graph) subsystem — Phase 1.
+ *
+ * decision 95df9d97 / spec 1112-codegraph-call-graph-spec.md.
+ *
+ * The node/edge data types moved to `src/core/storage/codegraph-types.ts`
+ * (decision ed98c8e8, 2026-06-10) so the core storage layer no longer imports
+ * from the knowledge layer. This file re-exports them for all knowledge-layer
+ * callers and keeps the knowledge-specific `RepoGraph` aggregate.
+ */
+export type { CodeGraphEdgeKind, CodeGraphNode, CodeGraphEdge, } from '../../core/storage/codegraph-types.js';
+import type { CodeGraphNode, CodeGraphEdge } from '../../core/storage/codegraph-types.js';
+/**
+ * Result of {@link buildRepoGraph}: the symbols (same source of truth as
+ * repo-map) plus the extracted edges.
+ */
+export interface RepoGraph {
+    nodes: CodeGraphNode[];
+    edges: CodeGraphEdge[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/knowledge/graph/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/knowledge/graph/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,aAAa,GACd,MAAM,uCAAuC,CAAC;AAE/C,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,uCAAuC,CAAC;AAE1F;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB"}

package/dist/knowledge/graph/types.js

@@ -0,0 +1,13 @@
+/**
+ * @file types.ts
+ * Shared types for the codegraph (call-graph) subsystem — Phase 1.
+ *
+ * decision 95df9d97 / spec 1112-codegraph-call-graph-spec.md.
+ *
+ * The node/edge data types moved to `src/core/storage/codegraph-types.ts`
+ * (decision ed98c8e8, 2026-06-10) so the core storage layer no longer imports
+ * from the knowledge layer. This file re-exports them for all knowledge-layer
+ * callers and keeps the knowledge-specific `RepoGraph` aggregate.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/knowledge/graph/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/knowledge/graph/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/knowledge/module-hash.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @file module-hash.ts
+ * Compute a deterministic content fingerprint for a single KB module.
+ *
+ * Used by `buildKnowledge` (builder.ts) to short-circuit AI compilation when
+ * a module's source content has not changed since the last build.
+ *
+ * ── Hash input面 = AI prompt 输入面 ────────────────────────────────────────
+ * The set of files this module hashes MUST match what `readModuleFiles` in
+ * builder.ts feeds to the AI prompt:
+ *   - recursive walk under `src/<module>/`
+ *   - include  : `*.ts`
+ *   - exclude  : `*.test.ts`, `*.d.ts`, `node_modules/`, dot-directories
+ *
+ * If you change `readModuleFiles`'s filter, mirror the change here or the
+ * cache will give stale hits (or miss too aggressively).
+ *
+ * ── Known limitations (v9.1) ───────────────────────────────────────────────
+ *   - Changes to `prompt.ts` are NOT detected. If you alter the prompt
+ *     template, run `cf knowledge build --apply --force` to bypass the cache.
+ *   - Cross-module dependencies are NOT tracked. Module A may reference
+ *     symbols from module B; if B changes, A's KB page is not invalidated.
+ *     Workaround: `--force`.
+ */
+import type { KBMeta } from './types.js';
+/** Length of the truncated SHA-256 hex digest stored in `KBMeta.pages[*].source_hash`. */
+export declare const MODULE_HASH_LENGTH = 12;
+interface CollectedFile {
+    /** POSIX-style path relative to `moduleDir` (e.g. `handlers/tool-use.ts`). */
+    relPath: string;
+    /** UTF-8 file contents. */
+    content: string;
+}
+/**
+ * Compute a content fingerprint for a single KB module.
+ *
+ * Algorithm:
+ *   1. Collect every `.ts` source file under `moduleDir` matching the
+ *      AI-prompt input filter (see file header).
+ *   2. For each file, compute `sha256("<relPath>|<content>")`.
+ *   3. Sort the per-file digests by relPath (stable across OS readdir order).
+ *   4. Hash `digests.join('\n')` and truncate to `MODULE_HASH_LENGTH`.
+ *
+ * Determinism is the entire point — same bytes => same hash on any OS.
+ */
+export declare function computeModuleHash(moduleDir: string): Promise<string>;
+/**
+ * Recursively gather `.ts` source files under `moduleDir`.
+ *
+ * Exported for tests only — production code should call `computeModuleHash`.
+ *
+ * @internal
+ */
+export declare function collectModuleFiles(moduleDir: string): Promise<CollectedFile[]>;
+/**
+ * Compute a content fingerprint covering the full set of module hashes (and
+ * optionally the tech-stack-related config files).
+ *
+ * Algorithm:
+ *   1. Sort moduleHashes entries by name (stable, OS-independent ordering).
+ *   2. Build lines `<name>|<hash>`; for each provided configFile append a line
+ *      `__<tag>|<sha256short>`.
+ *   3. SHA-256 over `lines.join('\n')` truncated to `MODULE_HASH_LENGTH`.
+ *
+ * Used by `compileCrossModulePages` to detect whether the cross-module pages
+ * (`overview.md`, `architecture.md`, `decisions.md`, `glossary.md`,
+ * `tech-stack.md`) need rebuilding. Any module hash change OR any config file
+ * change → cross hash changes → all 5 pages re-compile.
+ *
+ * @param moduleHashes Map of `modules/<name>.md` → `source_hash`.
+ * @param configFiles  Optional raw contents of `package.json`, `tsconfig.json`,
+ *                     `vitest.config.ts`. Each is hashed with sha256 and the
+ *                     first 12 hex chars are folded into the cross hash.
+ */
+export declare function computeCrossModuleHash(moduleHashes: Map<string, string>, configFiles?: {
+    packageJson?: string;
+    tsconfig?: string;
+    vitest?: string;
+}): string;
+/**
+ * Read `.forge-knowledge/.meta.json` if present, returning `null` on any error
+ * (missing file, malformed JSON, IO failure).
+ *
+ * Used by builder.ts to look up the previous build's per-module hashes.
+ */
+export declare function loadKBMetaSafe(projectRoot: string): KBMeta | null;
+export {};
+//# sourceMappingURL=module-hash.d.ts.map

package/dist/knowledge/module-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-hash.d.ts","sourceRoot":"","sources":["../../src/knowledge/module-hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAOH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,0FAA0F;AAC1F,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC,UAAU,aAAa;IACrB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAY1E;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CA0CpF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EACjC,WAAW,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACzE,MAAM,CAgBR;AAOD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAejE"}

package/dist/knowledge/module-hash.js

@@ -0,0 +1,162 @@
+/**
+ * @file module-hash.ts
+ * Compute a deterministic content fingerprint for a single KB module.
+ *
+ * Used by `buildKnowledge` (builder.ts) to short-circuit AI compilation when
+ * a module's source content has not changed since the last build.
+ *
+ * ── Hash input面 = AI prompt 输入面 ────────────────────────────────────────
+ * The set of files this module hashes MUST match what `readModuleFiles` in
+ * builder.ts feeds to the AI prompt:
+ *   - recursive walk under `src/<module>/`
+ *   - include  : `*.ts`
+ *   - exclude  : `*.test.ts`, `*.d.ts`, `node_modules/`, dot-directories
+ *
+ * If you change `readModuleFiles`'s filter, mirror the change here or the
+ * cache will give stale hits (or miss too aggressively).
+ *
+ * ── Known limitations (v9.1) ───────────────────────────────────────────────
+ *   - Changes to `prompt.ts` are NOT detected. If you alter the prompt
+ *     template, run `cf knowledge build --apply --force` to bypass the cache.
+ *   - Cross-module dependencies are NOT tracked. Module A may reference
+ *     symbols from module B; if B changes, A's KB page is not invalidated.
+ *     Workaround: `--force`.
+ */
+import { createHash } from 'node:crypto';
+import { promises as fs, readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import * as K from './constants.js';
+/** Length of the truncated SHA-256 hex digest stored in `KBMeta.pages[*].source_hash`. */
+export const MODULE_HASH_LENGTH = 12;
+/**
+ * Compute a content fingerprint for a single KB module.
+ *
+ * Algorithm:
+ *   1. Collect every `.ts` source file under `moduleDir` matching the
+ *      AI-prompt input filter (see file header).
+ *   2. For each file, compute `sha256("<relPath>|<content>")`.
+ *   3. Sort the per-file digests by relPath (stable across OS readdir order).
+ *   4. Hash `digests.join('\n')` and truncate to `MODULE_HASH_LENGTH`.
+ *
+ * Determinism is the entire point — same bytes => same hash on any OS.
+ */
+export async function computeModuleHash(moduleDir) {
+    const files = await collectModuleFiles(moduleDir);
+    files.sort((a, b) => (a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0));
+    const perFileHashes = files.map((f) => createHash('sha256').update(`${f.relPath}|${f.content}`).digest('hex'));
+    return createHash('sha256')
+        .update(perFileHashes.join('\n'))
+        .digest('hex')
+        .slice(0, MODULE_HASH_LENGTH);
+}
+/**
+ * Recursively gather `.ts` source files under `moduleDir`.
+ *
+ * Exported for tests only — production code should call `computeModuleHash`.
+ *
+ * @internal
+ */
+export async function collectModuleFiles(moduleDir) {
+    const out = [];
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = (await fs.readdir(dir, { withFileTypes: true }));
+        }
+        catch {
+            // Directory does not exist or is unreadable — treat as empty.
+            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')) {
+                let content;
+                try {
+                    content = await fs.readFile(full, 'utf-8');
+                }
+                catch {
+                    continue; // unreadable file — skip
+                }
+                // Force POSIX separators so Windows builds produce the same hash as
+                // macOS/Linux for the same logical layout.
+                const relPath = path.relative(moduleDir, full).split(path.sep).join('/');
+                out.push({ relPath, content });
+            }
+        }
+    }
+    await walk(moduleDir);
+    return out;
+}
+/**
+ * Compute a content fingerprint covering the full set of module hashes (and
+ * optionally the tech-stack-related config files).
+ *
+ * Algorithm:
+ *   1. Sort moduleHashes entries by name (stable, OS-independent ordering).
+ *   2. Build lines `<name>|<hash>`; for each provided configFile append a line
+ *      `__<tag>|<sha256short>`.
+ *   3. SHA-256 over `lines.join('\n')` truncated to `MODULE_HASH_LENGTH`.
+ *
+ * Used by `compileCrossModulePages` to detect whether the cross-module pages
+ * (`overview.md`, `architecture.md`, `decisions.md`, `glossary.md`,
+ * `tech-stack.md`) need rebuilding. Any module hash change OR any config file
+ * change → cross hash changes → all 5 pages re-compile.
+ *
+ * @param moduleHashes Map of `modules/<name>.md` → `source_hash`.
+ * @param configFiles  Optional raw contents of `package.json`, `tsconfig.json`,
+ *                     `vitest.config.ts`. Each is hashed with sha256 and the
+ *                     first 12 hex chars are folded into the cross hash.
+ */
+export function computeCrossModuleHash(moduleHashes, configFiles) {
+    const sorted = [...moduleHashes.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    const parts = sorted.map(([name, hash]) => `${name}|${hash}`);
+    if (configFiles) {
+        if (configFiles.packageJson)
+            parts.push(`__pkg|${sha256short(configFiles.packageJson)}`);
+        if (configFiles.tsconfig)
+            parts.push(`__tsc|${sha256short(configFiles.tsconfig)}`);
+        if (configFiles.vitest)
+            parts.push(`__vit|${sha256short(configFiles.vitest)}`);
+    }
+    return createHash('sha256')
+        .update(parts.join('\n'))
+        .digest('hex')
+        .slice(0, MODULE_HASH_LENGTH);
+}
+/** Short SHA-256 (12 hex chars) of an arbitrary string. Internal to cross-module hash. */
+function sha256short(input) {
+    return createHash('sha256').update(input).digest('hex').slice(0, MODULE_HASH_LENGTH);
+}
+/**
+ * Read `.forge-knowledge/.meta.json` if present, returning `null` on any error
+ * (missing file, malformed JSON, IO failure).
+ *
+ * Used by builder.ts to look up the previous build's per-module hashes.
+ */
+export function loadKBMetaSafe(projectRoot) {
+    const metaPath = path.join(projectRoot, K.KB_DIRNAME, K.KB_META_FILE);
+    if (!existsSync(metaPath))
+        return null;
+    try {
+        const raw = readFileSync(metaPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        // Minimal structural check — we only need .pages for cache lookup.
+        if (!parsed || typeof parsed !== 'object' || typeof parsed.pages !== 'object') {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=module-hash.js.map

package/dist/knowledge/module-hash.js.map

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

package/dist/knowledge/project-detector.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @file project-detector.ts
+ * v10.0 — Project-kind detection for the KB CLI.
+ *
+ * Scans the project root for well-known manifest files in a fixed priority
+ * order and returns a {@link ProjectInfo} describing what kind of project we
+ * are looking at.  Detection is purely filesystem-based (no parsing) so it is
+ * safe to call before any adapter / AI logic.
+ *
+ * Used by:
+ *   - `cf knowledge init` (CLI):
+ *      • TS  → continue existing build flow
+ *      • non-TS → emit a friendly "v10.0 only supports TypeScript" message
+ *      • unknown → emit a list of expected manifest files
+ *   - future adapters (v10.1+): higher tiers will use `sourceRoots` to drive
+ *     module discovery, replacing the hard-coded `src/` path.
+ *
+ * Priority order (first match wins):
+ *   1. `package.json` + `src/`               → typescript
+ *   2. `pom.xml`                              → java
+ *   3. `build.gradle` / `build.gradle.kts`    → java
+ *   4. `pyproject.toml`                       → python
+ *   5. `setup.py`                             → python
+ *   6. `go.mod`                               → go
+ *   7. `Cargo.toml`                           → rust
+ *   8. (none of the above)                    → unknown
+ *
+ * NOTE: only TypeScript currently has its `sourceRoots` populated.  Other
+ * kinds return `sourceRoots: []` — Tier 2/3 will fill those in.
+ */
+export type ProjectKind = 'typescript' | 'java' | 'python' | 'go' | 'rust' | 'monorepo' | 'unknown';
+/**
+ * The result of inspecting a project root.
+ *
+ * `reason` describes which manifest file (or absence thereof) drove the
+ * classification — useful in CLI error messages.
+ */
+export interface ProjectInfo {
+    kind: ProjectKind;
+    /** Absolute paths to discovered source roots; `[]` for unknown / not-yet-implemented kinds. */
+    sourceRoots: string[];
+    /** Human-readable explanation (e.g. `"package.json + src/ found"`). */
+    reason: string;
+}
+/**
+ * One sub-project inside a monorepo root.
+ *
+ * `name` is the literal directory name (e.g. `aipin-consumer`) — it becomes the
+ * KB module name verbatim (monorepo OQ2: never fall back to an adapter's default
+ * module name like Java's `app`).
+ */
+export interface SubprojectInfo {
+    /** Directory name, e.g. `"aipin-consumer"`. */
+    name: string;
+    /** Absolute path to the sub-project root. */
+    path: string;
+    /** Identifier of the adapter that recognised this sub-project. */
+    adapterName: string;
+}
+/**
+ * Result of a successful monorepo probe — at least two direct sub-directories
+ * are each recognised by some {@link LanguageAdapter}.
+ */
+export interface MonorepoInfo {
+    kind: 'monorepo';
+    subprojects: SubprojectInfo[];
+    reason: string;
+}
+/**
+ * List the names of direct child directories of `projectRoot` that pass the
+ * monorepo candidate filter. Used both by {@link detectMonorepo} and by the CLI
+ * warning text when degrading a true-generic project (so the operator can see
+ * what was scanned).
+ *
+ * Best-effort: any fs error yields `[]`.
+ */
+export declare function listCandidateSubdirs(projectRoot: string): string[];
+/**
+ * Detect a polyglot / multi-package monorepo rooted at `projectRoot`.
+ *
+ * A monorepo is recognised when the root itself has NO single-language adapter
+ * match (callers should only reach here after `getAdapter(projectRoot)` returned
+ * `null`) yet ≥ 2 direct child directories are each recognised by some adapter
+ * (they carry `package.json` / `pom.xml` / `build.gradle` / `go.mod` /
+ * `Cargo.toml` / `pyproject.toml` …).
+ *
+ * The `≥ 2` threshold avoids classifying a project that merely nests one library
+ * as a monorepo.
+ *
+ * @returns a {@link MonorepoInfo} when ≥ 2 sub-projects are found, else `null`.
+ */
+export declare function detectMonorepo(projectRoot: string): MonorepoInfo | null;
+/**
+ * Detect the project kind rooted at `projectRoot`.
+ *
+ * @param projectRoot absolute path to the project root.
+ * @returns a {@link ProjectInfo} describing the detected kind, source roots and a
+ *          human-readable reason.
+ */
+export declare function detectProject(projectRoot: string): ProjectInfo;
+//# sourceMappingURL=project-detector.d.ts.map

package/dist/knowledge/project-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-detector.d.ts","sourceRoot":"","sources":["../../src/knowledge/project-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAWH,MAAM,MAAM,WAAW,GACnB,YAAY,GACZ,MAAM,GACN,QAAQ,GACR,IAAI,GACJ,MAAM,GACN,UAAU,GACV,SAAS,CAAC;AAEd;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,WAAW,CAAC;IAClB,+FAA+F;IAC/F,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,cAAc,EAAE,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;CAChB;AA2CD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAWlE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CA0BvE;AAcD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CA4E9D"}