@shrkcrft/knowledge 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SharkCraft contributors
+
+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/README.md

@@ -0,0 +1,15 @@
+# @shrkcrft/knowledge
+
+SharkCraft structured knowledge model: typed entries, index, search, loaders (TS + markdown), validation.
+
+Part of [SharkCraft](https://github.com/sharkcraft/sharkcraft) — a deterministic, local-first toolkit that gives AI coding agents durable project context. See the main repo for documentation, examples, and the `shrk` CLI.
+
+## Install
+
+```bash
+bun add @shrkcrft/knowledge
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/define/define-knowledge-base.d.ts

@@ -0,0 +1,7 @@
+import type { IKnowledgeBaseDefinition } from '../model/knowledge-base.js';
+import type { IKnowledgeEntry } from '../model/knowledge-entry.js';
+export declare function defineKnowledgeBase(input: {
+    name?: string;
+    entries: readonly IKnowledgeEntry[];
+}): IKnowledgeBaseDefinition;
+//# sourceMappingURL=define-knowledge-base.d.ts.map

package/dist/define/define-knowledge-base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-knowledge-base.d.ts","sourceRoot":"","sources":["../../src/define/define-knowledge-base.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAC3E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAEnE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;CACrC,GAAG,wBAAwB,CAE3B"}

package/dist/define/define-knowledge-base.js

@@ -0,0 +1,3 @@
+export function defineKnowledgeBase(input) {
+    return { name: input.name, entries: Object.freeze([...input.entries]) };
+}

package/dist/define/define-knowledge-entry.d.ts

@@ -0,0 +1,20 @@
+import type { IKnowledgeEntry, IKnowledgeExample, IKnowledgeSource } from '../model/knowledge-entry.js';
+import type { IActionHints } from '../model/action-hints.js';
+export interface DefineKnowledgeInput {
+    id: string;
+    title: string;
+    type: string;
+    priority?: string;
+    scope?: readonly string[];
+    tags?: readonly string[];
+    appliesWhen?: readonly string[];
+    content: string;
+    summary?: string;
+    examples?: readonly IKnowledgeExample[];
+    related?: readonly string[];
+    source?: IKnowledgeSource;
+    metadata?: Readonly<Record<string, unknown>>;
+    actionHints?: IActionHints;
+}
+export declare function defineKnowledgeEntry(input: DefineKnowledgeInput): IKnowledgeEntry;
+//# sourceMappingURL=define-knowledge-entry.d.ts.map

package/dist/define/define-knowledge-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-knowledge-entry.d.ts","sourceRoot":"","sources":["../../src/define/define-knowledge-entry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACxG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAI7D,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACxC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC7C,WAAW,CAAC,EAAE,YAAY,CAAC;CAC5B;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,oBAAoB,GAAG,eAAe,CAmCjF"}

package/dist/define/define-knowledge-entry.js

@@ -0,0 +1,35 @@
+import { KnowledgePriority } from "../model/knowledge-priority.js";
+import { isValidKnowledgeId } from '@shrkcrft/core';
+export function defineKnowledgeEntry(input) {
+    if (!input.id || typeof input.id !== 'string') {
+        throw new Error(`defineKnowledgeEntry: 'id' is required (got ${String(input.id)})`);
+    }
+    if (!isValidKnowledgeId(input.id)) {
+        throw new Error(`defineKnowledgeEntry: 'id' must match /^[a-z0-9]+([.-][a-z0-9]+)*$/ (got "${input.id}")`);
+    }
+    if (!input.title) {
+        throw new Error(`defineKnowledgeEntry: 'title' is required for ${input.id}`);
+    }
+    if (!input.type) {
+        throw new Error(`defineKnowledgeEntry: 'type' is required for ${input.id}`);
+    }
+    if (typeof input.content !== 'string') {
+        throw new Error(`defineKnowledgeEntry: 'content' is required for ${input.id}`);
+    }
+    return {
+        id: input.id,
+        title: input.title,
+        type: input.type,
+        priority: input.priority ?? KnowledgePriority.Medium,
+        scope: Object.freeze([...(input.scope ?? [])]),
+        tags: Object.freeze([...(input.tags ?? [])]),
+        appliesWhen: Object.freeze([...(input.appliesWhen ?? [])]),
+        content: input.content,
+        summary: input.summary,
+        examples: input.examples ? Object.freeze([...input.examples]) : undefined,
+        related: input.related ? Object.freeze([...input.related]) : undefined,
+        source: input.source,
+        metadata: input.metadata,
+        actionHints: input.actionHints,
+    };
+}

package/dist/format/action-hints-formatter.d.ts

@@ -0,0 +1,35 @@
+import type { IKnowledgeEntry } from '../model/knowledge-entry.js';
+import type { IActionHintCommand, IActionHintMcpTool } from '../model/action-hints.js';
+export interface IAggregatedActionHints {
+    commands: IActionHintCommand[];
+    mcpTools: IActionHintMcpTool[];
+    preferredFlow: readonly string[];
+    preferredFlowSourceId?: string;
+    forbiddenActions: string[];
+    relatedTemplates: string[];
+    relatedPathConventions: string[];
+    relatedKnowledge: string[];
+    verificationCommands: string[];
+    safetyNotes: string[];
+    requiresHumanReview: boolean;
+    writePolicy?: string;
+    /** Entry ids that contributed at least one hint. */
+    contributingEntries: string[];
+}
+/**
+ * Combine actionHints from a list of relevant entries into a single bundle.
+ * Order of entries determines tie-breaking: the highest-priority entry wins
+ * for `preferredFlow` and `writePolicy`. Other fields are deduped union.
+ */
+export declare function aggregateActionHints(entries: readonly IKnowledgeEntry[]): IAggregatedActionHints;
+export interface FormatActionHintsOptions {
+    /** Title prefix (used by the context builder as section headings). */
+    level?: '##' | '###';
+    /** When true, omit empty subsections instead of rendering a heading. */
+    compact?: boolean;
+}
+export declare function formatAggregatedHints(hints: IAggregatedActionHints, options?: FormatActionHintsOptions): string;
+export declare function formatEntryActionHints(entry: IKnowledgeEntry, options?: FormatActionHintsOptions): string;
+/** Returns a single text block for an aggregated bundle. Useful for CLI output. */
+export declare function aggregatedHintsToText(hints: IAggregatedActionHints): string;
+//# sourceMappingURL=action-hints-formatter.d.ts.map

package/dist/format/action-hints-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-hints-formatter.d.ts","sourceRoot":"","sources":["../../src/format/action-hints-formatter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAEnB,MAAM,0BAA0B,CAAC;AAGlC,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,mBAAmB,EAAE,MAAM,EAAE,CAAC;CAC/B;AAkBD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,SAAS,eAAe,EAAE,GAClC,sBAAsB,CAyCxB;AAED,MAAM,WAAW,wBAAwB;IACvC,sEAAsE;IACtE,KAAK,CAAC,EAAE,IAAI,GAAG,KAAK,CAAC;IACrB,wEAAwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAgBD,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,sBAAsB,EAC7B,OAAO,GAAE,wBAA6B,GACrC,MAAM,CA2DR;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,eAAe,EACtB,OAAO,GAAE,wBAA6B,GACrC,MAAM,CAGR;AAED,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,sBAAsB,GAAG,MAAM,CAE3E"}

package/dist/format/action-hints-formatter.js

@@ -0,0 +1,120 @@
+import { priorityWeight } from "../model/knowledge-priority.js";
+function dedupePush(out, items, key) {
+    if (!items)
+        return;
+    const seen = new Set(out.map(key));
+    for (const item of items) {
+        const k = key(item);
+        if (!seen.has(k)) {
+            seen.add(k);
+            out.push(item);
+        }
+    }
+}
+function dedupeStrings(out, items) {
+    dedupePush(out, items, (s) => s);
+}
+/**
+ * Combine actionHints from a list of relevant entries into a single bundle.
+ * Order of entries determines tie-breaking: the highest-priority entry wins
+ * for `preferredFlow` and `writePolicy`. Other fields are deduped union.
+ */
+export function aggregateActionHints(entries) {
+    const out = {
+        commands: [],
+        mcpTools: [],
+        preferredFlow: [],
+        forbiddenActions: [],
+        relatedTemplates: [],
+        relatedPathConventions: [],
+        relatedKnowledge: [],
+        verificationCommands: [],
+        safetyNotes: [],
+        requiresHumanReview: false,
+        contributingEntries: [],
+    };
+    // Sort by priority desc so highest-priority entries win for "preferredFlow".
+    const sorted = [...entries].sort((a, b) => priorityWeight(b.priority) - priorityWeight(a.priority));
+    for (const entry of sorted) {
+        const h = entry.actionHints;
+        if (!h)
+            continue;
+        dedupePush(out.commands, h.commands, (c) => c.command);
+        dedupePush(out.mcpTools, h.mcpTools, (m) => m.tool);
+        if (!out.preferredFlow.length && h.preferredFlow?.length) {
+            out.preferredFlow = h.preferredFlow;
+            out.preferredFlowSourceId = entry.id;
+        }
+        dedupeStrings(out.forbiddenActions, h.forbiddenActions);
+        dedupeStrings(out.relatedTemplates, h.relatedTemplates);
+        dedupeStrings(out.relatedPathConventions, h.relatedPathConventions);
+        dedupeStrings(out.relatedKnowledge, h.relatedKnowledge);
+        dedupeStrings(out.verificationCommands, h.verificationCommands);
+        dedupeStrings(out.safetyNotes, h.safetyNotes);
+        if (h.requiresHumanReview)
+            out.requiresHumanReview = true;
+        if (h.writePolicy && !out.writePolicy)
+            out.writePolicy = String(h.writePolicy);
+        out.contributingEntries.push(entry.id);
+    }
+    return out;
+}
+function formatCmd(c) {
+    const req = c.required ? ' (required)' : '';
+    const when = c.when ? ` — when: ${c.when}` : '';
+    const purpose = c.purpose ? ` — ${c.purpose}` : '';
+    return `\`${c.command}\`${req}${purpose}${when}`;
+}
+function formatTool(t) {
+    const req = t.required ? ' (required)' : '';
+    const when = t.when ? ` — when: ${t.when}` : '';
+    const purpose = t.purpose ? ` — ${t.purpose}` : '';
+    return `\`${t.tool}\`${req}${purpose}${when}`;
+}
+export function formatAggregatedHints(hints, options = {}) {
+    const level = options.level ?? '##';
+    const lines = [];
+    function section(name, body) {
+        if (!body)
+            return;
+        lines.push(`${level} ${name}`);
+        lines.push('');
+        lines.push(body);
+        lines.push('');
+    }
+    section('Recommended MCP Tools', hints.mcpTools.map((t) => `- ${formatTool(t)}`).join('\n'));
+    section('Recommended CLI Commands', hints.commands.map((c) => `- ${formatCmd(c)}`).join('\n'));
+    if (hints.preferredFlow.length) {
+        const src = hints.preferredFlowSourceId ? ` _(from ${hints.preferredFlowSourceId})_` : '';
+        section(`Preferred Flow${src}`, hints.preferredFlow.map((s, i) => `${i + 1}. ${s}`).join('\n'));
+    }
+    section('Forbidden Actions', hints.forbiddenActions.map((a) => `- ${a}`).join('\n'));
+    section('Verification Commands', hints.verificationCommands.map((c) => `- \`${c}\``).join('\n'));
+    section('Safety Notes', hints.safetyNotes.map((n) => `- ${n}`).join('\n'));
+    if (hints.relatedTemplates.length) {
+        section('Related Templates', hints.relatedTemplates.map((t) => `- \`${t}\``).join('\n'));
+    }
+    if (hints.relatedPathConventions.length) {
+        section('Related Path Conventions', hints.relatedPathConventions.map((p) => `- \`${p}\``).join('\n'));
+    }
+    if (hints.requiresHumanReview || hints.writePolicy) {
+        const parts = [];
+        if (hints.requiresHumanReview)
+            parts.push('Requires human review.');
+        if (hints.writePolicy)
+            parts.push(`Write policy: \`${hints.writePolicy}\`.`);
+        section('Human Review Points', parts.map((p) => `- ${p}`).join('\n'));
+    }
+    if (options.compact && lines.length === 0)
+        return '';
+    return lines.join('\n').trim();
+}
+export function formatEntryActionHints(entry, options = {}) {
+    if (!entry.actionHints)
+        return '';
+    return formatAggregatedHints(aggregateActionHints([entry]), options);
+}
+/** Returns a single text block for an aggregated bundle. Useful for CLI output. */
+export function aggregatedHintsToText(hints) {
+    return formatAggregatedHints(hints, { compact: true });
+}

package/dist/format/knowledge-formatter.d.ts

@@ -0,0 +1,11 @@
+import type { IKnowledgeEntry } from '../model/knowledge-entry.js';
+export interface FormatEntryOptions {
+    includeExamples?: boolean;
+    includeContent?: boolean;
+    includeMetadata?: boolean;
+    includeActionHints?: boolean;
+    maxContentChars?: number;
+}
+export declare function formatEntryCompact(entry: IKnowledgeEntry): string;
+export declare function formatEntryFull(entry: IKnowledgeEntry, options?: FormatEntryOptions): string;
+//# sourceMappingURL=knowledge-formatter.d.ts.map

package/dist/format/knowledge-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-formatter.d.ts","sourceRoot":"","sources":["../../src/format/knowledge-formatter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAGnE,MAAM,WAAW,kBAAkB;IACjC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAKjE;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,eAAe,EACtB,OAAO,GAAE,kBAAuB,GAC/B,MAAM,CA4CR"}

package/dist/format/knowledge-formatter.js

@@ -0,0 +1,58 @@
+import { formatEntryActionHints } from "./action-hints-formatter.js";
+export function formatEntryCompact(entry) {
+    const tags = entry.tags.length ? ` tags=[${entry.tags.join(', ')}]` : '';
+    const scope = entry.scope.length ? ` scope=[${entry.scope.join(', ')}]` : '';
+    const appliesWhen = entry.appliesWhen.length ? ` appliesWhen=[${entry.appliesWhen.join(', ')}]` : '';
+    return `${entry.id} (${entry.type}, ${entry.priority}) — ${entry.title}${tags}${scope}${appliesWhen}`;
+}
+export function formatEntryFull(entry, options = {}) {
+    const { includeExamples = true, includeContent = true, maxContentChars } = options;
+    const lines = [];
+    lines.push(`# ${entry.title}`);
+    lines.push(`id: ${entry.id}`);
+    lines.push(`type: ${entry.type}`);
+    lines.push(`priority: ${entry.priority}`);
+    if (entry.scope.length)
+        lines.push(`scope: ${entry.scope.join(', ')}`);
+    if (entry.tags.length)
+        lines.push(`tags: ${entry.tags.join(', ')}`);
+    if (entry.appliesWhen.length)
+        lines.push(`appliesWhen: ${entry.appliesWhen.join(', ')}`);
+    if (entry.summary) {
+        lines.push('');
+        lines.push(`Summary: ${entry.summary}`);
+    }
+    if (includeContent) {
+        lines.push('');
+        let content = entry.content.trim();
+        if (maxContentChars && content.length > maxContentChars) {
+            content = content.slice(0, maxContentChars) + '…';
+        }
+        lines.push(content);
+    }
+    if (includeExamples && entry.examples?.length) {
+        lines.push('');
+        lines.push('Examples:');
+        for (const ex of entry.examples) {
+            if (ex.title)
+                lines.push(`- ${ex.title}`);
+            if (ex.description)
+                lines.push(`  ${ex.description}`);
+            if (ex.code) {
+                const lang = ex.language ?? '';
+                lines.push('  ```' + lang);
+                for (const codeLine of ex.code.split('\n'))
+                    lines.push('  ' + codeLine);
+                lines.push('  ```');
+            }
+        }
+    }
+    if (options.includeActionHints !== false && entry.actionHints) {
+        const block = formatEntryActionHints(entry, { level: '###', compact: true });
+        if (block) {
+            lines.push('');
+            lines.push(block);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/index/knowledge-index.d.ts

@@ -0,0 +1,16 @@
+import type { IKnowledgeEntry } from '../model/knowledge-entry.js';
+import type { IKnowledgeQuery } from '../model/knowledge-query.js';
+import type { IKnowledgeSearchResult } from '../model/knowledge-search-result.js';
+export declare class KnowledgeIndex {
+    private readonly byId;
+    private readonly all;
+    constructor(entries?: readonly IKnowledgeEntry[]);
+    add(entry: IKnowledgeEntry): void;
+    has(id: string): boolean;
+    get(id: string): IKnowledgeEntry | null;
+    list(): readonly IKnowledgeEntry[];
+    size(): number;
+    filter(predicate: (entry: IKnowledgeEntry) => boolean): IKnowledgeEntry[];
+    search(query: IKnowledgeQuery): IKnowledgeSearchResult[];
+}
+//# sourceMappingURL=knowledge-index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-index.d.ts","sourceRoot":"","sources":["../../src/index/knowledge-index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAIlF,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAsC;IAC3D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAyB;gBAEjC,OAAO,GAAE,SAAS,eAAe,EAAO;IAIpD,GAAG,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAajC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAIvC,IAAI,IAAI,SAAS,eAAe,EAAE;IAIlC,IAAI,IAAI,MAAM;IAId,MAAM,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,OAAO,GAAG,eAAe,EAAE;IAIzE,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,sBAAsB,EAAE;CA4BzD"}

package/dist/index/knowledge-index.js

@@ -0,0 +1,63 @@
+import { priorityWeight } from "../model/knowledge-priority.js";
+import { scoreEntry } from "./relevance-score.js";
+export class KnowledgeIndex {
+    byId = new Map();
+    all = [];
+    constructor(entries = []) {
+        for (const e of entries)
+            this.add(e);
+    }
+    add(entry) {
+        if (this.byId.has(entry.id)) {
+            // Keep the first definition; tolerate duplicates with a warning marker.
+            const existing = this.byId.get(entry.id);
+            if (existing.content !== entry.content || existing.title !== entry.title) {
+                // Don't throw — multiple files may legitimately re-export.
+            }
+            return;
+        }
+        this.byId.set(entry.id, entry);
+        this.all.push(entry);
+    }
+    has(id) {
+        return this.byId.has(id);
+    }
+    get(id) {
+        return this.byId.get(id) ?? null;
+    }
+    list() {
+        return this.all;
+    }
+    size() {
+        return this.all.length;
+    }
+    filter(predicate) {
+        return this.all.filter(predicate);
+    }
+    search(query) {
+        const minPriorityWeight = query.minPriority
+            ? priorityWeight(query.minPriority)
+            : 0;
+        const candidates = this.all.filter((e) => {
+            if (query.types?.length && !query.types.includes(String(e.type)))
+                return false;
+            if (minPriorityWeight > 0 && priorityWeight(e.priority) < minPriorityWeight) {
+                return false;
+            }
+            return true;
+        });
+        const scored = candidates
+            .map((entry) => {
+            const { score, reasons } = scoreEntry(entry, query);
+            return { entry, score, reasons };
+        })
+            .filter((r) => {
+            if (query.query || query.appliesWhen?.length || query.scope?.length || query.tags?.length) {
+                return r.score > 0 && r.reasons.length > 0;
+            }
+            return true;
+        })
+            .sort((a, b) => b.score - a.score);
+        return query.limit && query.limit > 0 ? scored.slice(0, query.limit) : scored;
+    }
+}

package/dist/index/relevance-score.d.ts

@@ -0,0 +1,9 @@
+import type { IKnowledgeEntry } from '../model/knowledge-entry.js';
+import type { IKnowledgeQuery } from '../model/knowledge-query.js';
+import type { IKnowledgeMatchReason } from '../model/knowledge-search-result.js';
+export interface ScoredMatch {
+    score: number;
+    reasons: IKnowledgeMatchReason[];
+}
+export declare function scoreEntry(entry: IKnowledgeEntry, query: IKnowledgeQuery): ScoredMatch;
+//# sourceMappingURL=relevance-score.d.ts.map

package/dist/index/relevance-score.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relevance-score.d.ts","sourceRoot":"","sources":["../../src/index/relevance-score.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAGjF,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,qBAAqB,EAAE,CAAC;CAClC;AAYD,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,eAAe,GAAG,WAAW,CAiFtF"}

package/dist/index/relevance-score.js

@@ -0,0 +1,89 @@
+import { priorityWeight } from "../model/knowledge-priority.js";
+const FIELD_WEIGHTS = {
+    id: 80,
+    title: 50,
+    tags: 35,
+    scope: 30,
+    appliesWhen: 40,
+    summary: 25,
+    content: 15,
+};
+export function scoreEntry(entry, query) {
+    let score = 0;
+    const reasons = [];
+    // Priority baseline always contributes (so a critical rule outranks a low-priority match).
+    score += priorityWeight(entry.priority) / 10;
+    // Type filter is a hard match — only score the rest if type matches when types specified.
+    const queryText = (query.query ?? '').trim().toLowerCase();
+    const queryWords = queryText
+        .split(/\s+/)
+        .map((w) => w.trim())
+        .filter((w) => w.length >= 2);
+    // Free-text matches
+    if (queryText.length > 0) {
+        if (entry.id.toLowerCase().includes(queryText)) {
+            score += FIELD_WEIGHTS.id;
+            reasons.push({ field: 'id', match: queryText });
+        }
+        if (entry.title.toLowerCase().includes(queryText)) {
+            score += FIELD_WEIGHTS.title;
+            reasons.push({ field: 'title', match: queryText });
+        }
+        if (entry.summary?.toLowerCase().includes(queryText)) {
+            score += FIELD_WEIGHTS.summary;
+            reasons.push({ field: 'summary', match: queryText });
+        }
+        if (entry.content.toLowerCase().includes(queryText)) {
+            score += FIELD_WEIGHTS.content;
+            reasons.push({ field: 'content', match: queryText });
+        }
+        // Per-word matches against tag/scope/appliesWhen.
+        for (const word of queryWords) {
+            if (entry.tags.some((t) => t.toLowerCase().includes(word))) {
+                score += FIELD_WEIGHTS.tags / queryWords.length;
+                reasons.push({ field: 'tags', match: word });
+            }
+            if (entry.scope.some((s) => s.toLowerCase().includes(word))) {
+                score += FIELD_WEIGHTS.scope / queryWords.length;
+                reasons.push({ field: 'scope', match: word });
+            }
+            if (entry.appliesWhen.some((a) => a.toLowerCase().includes(word))) {
+                score += FIELD_WEIGHTS.appliesWhen / queryWords.length;
+                reasons.push({ field: 'appliesWhen', match: word });
+            }
+        }
+    }
+    // appliesWhen exact-match bonus.
+    if (query.appliesWhen?.length) {
+        const matches = entry.appliesWhen.filter((a) => query.appliesWhen.includes(a));
+        if (matches.length > 0) {
+            score += FIELD_WEIGHTS.appliesWhen;
+            for (const m of matches)
+                reasons.push({ field: 'appliesWhen', match: m });
+        }
+    }
+    // scope exact-match bonus.
+    if (query.scope?.length) {
+        const matches = entry.scope.filter((s) => query.scope.includes(s));
+        if (matches.length > 0) {
+            score += FIELD_WEIGHTS.scope;
+            for (const m of matches)
+                reasons.push({ field: 'scope', match: m });
+        }
+    }
+    // tag exact-match bonus.
+    if (query.tags?.length) {
+        const matches = entry.tags.filter((t) => query.tags.includes(t));
+        if (matches.length === query.tags.length) {
+            score += FIELD_WEIGHTS.tags;
+            for (const m of matches)
+                reasons.push({ field: 'tags', match: m });
+        }
+        else if (matches.length > 0) {
+            score += FIELD_WEIGHTS.tags / 2;
+            for (const m of matches)
+                reasons.push({ field: 'tags', match: m });
+        }
+    }
+    return { score, reasons };
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export * from './model/knowledge-entry.js';
+export * from './model/action-hints.js';
+export * from './model/knowledge-type.js';
+export * from './model/knowledge-priority.js';
+export * from './model/knowledge-query.js';
+export * from './model/knowledge-search-result.js';
+export * from './model/knowledge-base.js';
+export * from './define/define-knowledge-entry.js';
+export * from './define/define-knowledge-base.js';
+export * from './load/knowledge-loader.js';
+export * from './load/typescript-knowledge-loader.js';
+export * from './load/markdown-knowledge-loader.js';
+export * from './index/relevance-score.js';
+export * from './index/knowledge-index.js';
+export * from './search/knowledge-search.js';
+export * from './search/knowledge-filter.js';
+export * from './format/knowledge-formatter.js';
+export * from './format/action-hints-formatter.js';
+export * from './validate/validate-knowledge-entries.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oCAAoC,CAAC;AACnD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oCAAoC,CAAC;AACnD,cAAc,mCAAmC,CAAC;AAClD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AACpD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,iCAAiC,CAAC;AAChD,cAAc,oCAAoC,CAAC;AACnD,cAAc,0CAA0C,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+export * from "./model/knowledge-entry.js";
+export * from "./model/action-hints.js";
+export * from "./model/knowledge-type.js";
+export * from "./model/knowledge-priority.js";
+export * from "./model/knowledge-query.js";
+export * from "./model/knowledge-search-result.js";
+export * from "./model/knowledge-base.js";
+export * from "./define/define-knowledge-entry.js";
+export * from "./define/define-knowledge-base.js";
+export * from "./load/knowledge-loader.js";
+export * from "./load/typescript-knowledge-loader.js";
+export * from "./load/markdown-knowledge-loader.js";
+export * from "./index/relevance-score.js";
+export * from "./index/knowledge-index.js";
+export * from "./search/knowledge-search.js";
+export * from "./search/knowledge-filter.js";
+export * from "./format/knowledge-formatter.js";
+export * from "./format/action-hints-formatter.js";
+export * from "./validate/validate-knowledge-entries.js";

package/dist/load/knowledge-loader.d.ts

@@ -0,0 +1,11 @@
+import type { IKnowledgeEntry } from '../model/knowledge-entry.js';
+export interface ILoadedKnowledge {
+    entries: IKnowledgeEntry[];
+    warnings: string[];
+    sourceFiles: string[];
+}
+export interface IKnowledgeLoader {
+    load(filePath: string): Promise<ILoadedKnowledge>;
+    canLoad(filePath: string): boolean;
+}
+//# sourceMappingURL=knowledge-loader.d.ts.map

package/dist/load/knowledge-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-loader.d.ts","sourceRoot":"","sources":["../../src/load/knowledge-loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAEnE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAClD,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CACpC"}

package/dist/load/knowledge-loader.js

@@ -0,0 +1 @@
+export {};

package/dist/load/markdown-knowledge-loader.d.ts

@@ -0,0 +1,6 @@
+import type { ILoadedKnowledge, IKnowledgeLoader } from './knowledge-loader.js';
+export declare class MarkdownKnowledgeLoader implements IKnowledgeLoader {
+    canLoad(filePath: string): boolean;
+    load(filePath: string): Promise<ILoadedKnowledge>;
+}
+//# sourceMappingURL=markdown-knowledge-loader.d.ts.map

package/dist/load/markdown-knowledge-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-knowledge-loader.d.ts","sourceRoot":"","sources":["../../src/load/markdown-knowledge-loader.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAqDhF,qBAAa,uBAAwB,YAAW,gBAAgB;IAC9D,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAI5B,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAyCxD"}