@shrkcrft/knowledge 0.1.0-alpha.2 → 0.1.0-alpha.20

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

@@ -1 +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"}
+{"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;AAoCD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,SAAS,eAAe,EAAE,GAClC,sBAAsB,CA0CxB;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

@@ -1,6 +1,9 @@
 import { priorityWeight } from "../model/knowledge-priority.js";
 function dedupePush(out, items, key) {
-    if (!items)
+    // Defensive: an entry may author an object-array hint (commands / mcpTools)
+    // as a scalar by mistake. Iterating a non-array here would walk string chars
+    // and produce garbage keys, so anything that isn't an array is ignored.
+    if (!Array.isArray(items))
         return;
     const seen = new Set(out.map(key));
     for (const item of items) {
@@ -11,8 +14,24 @@ function dedupePush(out, items, key) {
         }
     }
 }
+/**
+ * Coerce an authored hint value into a string array. A common authoring typo
+ * is to write a single-value field as a scalar (`preferredFlow: 'x'`) instead
+ * of an array (`preferredFlow: ['x']`). A scalar string has `.length` but no
+ * `.map`, which previously crashed the formatter (`preferredFlow.map is not a
+ * function`) and took down the whole `shrk context` entrypoint. Normalizing
+ * here preserves the authored content while guaranteeing the all-array contract
+ * of `IAggregatedActionHints`.
+ */
+function toHintStrings(value) {
+    if (Array.isArray(value))
+        return value.filter((v) => typeof v === 'string');
+    if (typeof value === 'string' && value.trim().length > 0)
+        return [value];
+    return [];
+}
 function dedupeStrings(out, items) {
-    dedupePush(out, items, (s) => s);
+    dedupePush(out, toHintStrings(items), (s) => s);
 }
 /**
  * Combine actionHints from a list of relevant entries into a single bundle.
@@ -41,8 +60,9 @@ export function aggregateActionHints(entries) {
             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;
+        const flow = toHintStrings(h.preferredFlow);
+        if (!out.preferredFlow.length && flow.length) {
+            out.preferredFlow = flow;
             out.preferredFlowSourceId = entry.id;
         }
         dedupeStrings(out.forbiddenActions, h.forbiddenActions);

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

@@ -7,5 +7,17 @@ export interface FormatEntryOptions {
     maxContentChars?: number;
 }
 export declare function formatEntryCompact(entry: IKnowledgeEntry): string;
+/**
+ * Project an entry to a plain JSON-serialisable object by reading each declared
+ * `IKnowledgeEntry` field by DIRECT property access.
+ *
+ * Spreading (`{ ...entry }`) copies only own-enumerable properties, so a
+ * pack-contributed entry whose fields are getters / non-enumerable /
+ * prototype-backed would serialise to `{ id, source }` only — the JSON looked
+ * "empty" while the text form (which reads fields directly) was complete.
+ * Direct access matches the text path and is robust to the entry's property
+ * descriptors. Undefined optionals drop out of `JSON.stringify` naturally.
+ */
+export declare function projectKnowledgeEntryForJson(entry: IKnowledgeEntry): Record<string, unknown>;
 export declare function formatEntryFull(entry: IKnowledgeEntry, options?: FormatEntryOptions): string;
 //# sourceMappingURL=knowledge-formatter.d.ts.map

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

@@ -1 +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"}
+{"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;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAmB5F;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,eAAe,EACtB,OAAO,GAAE,kBAAuB,GAC/B,MAAM,CA4CR"}

package/dist/format/knowledge-formatter.js

@@ -5,6 +5,37 @@ export function formatEntryCompact(entry) {
     const appliesWhen = entry.appliesWhen.length ? ` appliesWhen=[${entry.appliesWhen.join(', ')}]` : '';
     return `${entry.id} (${entry.type}, ${entry.priority}) — ${entry.title}${tags}${scope}${appliesWhen}`;
 }
+/**
+ * Project an entry to a plain JSON-serialisable object by reading each declared
+ * `IKnowledgeEntry` field by DIRECT property access.
+ *
+ * Spreading (`{ ...entry }`) copies only own-enumerable properties, so a
+ * pack-contributed entry whose fields are getters / non-enumerable /
+ * prototype-backed would serialise to `{ id, source }` only — the JSON looked
+ * "empty" while the text form (which reads fields directly) was complete.
+ * Direct access matches the text path and is robust to the entry's property
+ * descriptors. Undefined optionals drop out of `JSON.stringify` naturally.
+ */
+export function projectKnowledgeEntryForJson(entry) {
+    return {
+        id: entry.id,
+        title: entry.title,
+        type: entry.type,
+        priority: entry.priority,
+        scope: entry.scope,
+        tags: entry.tags,
+        appliesWhen: entry.appliesWhen,
+        content: entry.content,
+        summary: entry.summary,
+        examples: entry.examples,
+        related: entry.related,
+        source: entry.source,
+        metadata: entry.metadata,
+        actionHints: entry.actionHints,
+        references: entry.references,
+        anchors: entry.anchors,
+    };
+}
 export function formatEntryFull(entry, options = {}) {
     const { includeExamples = true, includeContent = true, maxContentChars } = options;
     const lines = [];

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

@@ -1 +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"}
+{"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,CAmHtF"}

package/dist/index/relevance-score.js

@@ -11,8 +11,18 @@ const FIELD_WEIGHTS = {
 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;
+    // Priority baseline always contributes so that — once an entry has *any*
+    // match reason — a foundational critical rule (e.g. architecture.layer-order)
+    // outranks a non-critical entry that merely shares a keyword. The old
+    // `/ 10` shrank Critical (weight 100) to a baseline of 10, an order of
+    // magnitude below a single lexical hit (id 80, title 50, appliesWhen 40), so
+    // critical rules were reliably buried. Use the full priority weight: Critical
+    // 100, High 70, Medium 40, Low 10 — on par with a strong lexical hit, while
+    // a *strong* multi-field lexical match (which sums well past 100) still wins.
+    // This does not surface no-reason entries: the index drops score>0 results
+    // with empty reasons, so an irrelevant critical rule never leaks in on
+    // priority alone.
+    score += priorityWeight(entry.priority);
     // 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
@@ -25,13 +35,39 @@ export function scoreEntry(entry, query) {
             score += FIELD_WEIGHTS.id;
             reasons.push({ field: 'id', match: queryText });
         }
-        if (entry.title.toLowerCase().includes(queryText)) {
+        // Title / summary: an exact full-phrase hit earns the full weight; otherwise
+        // credit by the SHARE of query words present. Matching per-word — not only
+        // the whole query string — lets a semantically relevant title (e.g.
+        // "Catalog i18n overlay" for "localize product catalog translations
+        // currency") outscore an entry that merely shares one incidental tag. The
+        // old full-phrase-only check earned title/summary zero on every multi-word
+        // query, so a single off-topic tag hit could win.
+        const wordCount = Math.max(1, queryWords.length);
+        const titleLc = entry.title.toLowerCase();
+        if (titleLc.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 });
+        else {
+            const hits = queryWords.filter((w) => titleLc.includes(w));
+            if (hits.length > 0) {
+                score += FIELD_WEIGHTS.title * (hits.length / wordCount);
+                reasons.push({ field: 'title', match: hits.join(' ') });
+            }
+        }
+        const summaryLc = entry.summary?.toLowerCase() ?? '';
+        if (summaryLc.length > 0) {
+            if (summaryLc.includes(queryText)) {
+                score += FIELD_WEIGHTS.summary;
+                reasons.push({ field: 'summary', match: queryText });
+            }
+            else {
+                const hits = queryWords.filter((w) => summaryLc.includes(w));
+                if (hits.length > 0) {
+                    score += FIELD_WEIGHTS.summary * (hits.length / wordCount);
+                    reasons.push({ field: 'summary', match: hits.join(' ') });
+                }
+            }
         }
         if (entry.content.toLowerCase().includes(queryText)) {
             score += FIELD_WEIGHTS.content;

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@shrkcrft/knowledge",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.20",
   "description": "SharkCraft structured knowledge model: typed entries, index, search, loaders (TS + markdown), validation.",
   "license": "MIT",
   "author": "SharkCraft contributors",
   "type": "module",
   "main": "./dist/index.js",
-  "types": "./dist/index.d.d.ts",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -44,7 +44,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.2"
+    "@shrkcrft/core": "^0.1.0-alpha.20"
   },
   "publishConfig": {
     "access": "public"