@unbrained/pm-cli 2026.6.19 → 2026.6.21

package/dist/core/item/status-filter.js

@@ -4,7 +4,7 @@
  * Defines item parsing, formatting, and lifecycle helpers for Status Filter.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a820defb-5037-5162-aef4-7ac9d17cc596")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="68b0f67b-4043-5b34-a8ed-39f5d6baea42")}catch(e){}}();
 import { EXIT_CODE } from "../shared/constants.js";
 import { PmCliError } from "../shared/errors.js";
 import { levenshteinDistanceWithinLimit } from "../shared/levenshtein.js";
@@ -20,6 +20,18 @@ const STATUS_GROUP_ALIASES = {
     canceled: "canceled_status",
     cancelled: "canceled_status",
 };
+const STATUS_ALL_SENTINEL = "all";
+/** Return true when a status-filter input is the standalone all-status sentinel. */
+export function isStatusAllFilterInput(raw) {
+    if (typeof raw !== "string") {
+        return false;
+    }
+    const tokens = raw
+        .split(",")
+        .map((entry) => entry.trim().toLowerCase())
+        .filter((entry) => entry.length > 0);
+    return tokens.length === 1 && tokens[0] === STATUS_ALL_SENTINEL;
+}
 /**
  * Resolve a single status-filter token to a concrete runtime status id.
  *
@@ -66,9 +78,11 @@ function suggestClosestStatus(value, registry) {
 }
 /**
  * Parse a comma-separated status filter into a de-duplicated list of concrete
- * status ids. Shared by `pm list` (lenient) and `pm search` (strict, with a
- * did-you-mean hint on typos) so both surfaces resolve the open/closed/canceled
- * workflow-group aliases identically.
+ * status ids. A standalone `all` sentinel intentionally resolves to no filter
+ * so duplicate-discovery loops can search every lifecycle bucket with the same
+ * `--status` flag shape. Shared by `pm list` (lenient) and `pm search`
+ * (strict, with a did-you-mean hint on typos) so both surfaces resolve the
+ * open/closed/canceled workflow-group aliases identically.
  */
 export function parseStatusFilterCsv(raw, registry, options) {
     if (typeof raw !== "string") {
@@ -83,6 +97,13 @@ export function parseStatusFilterCsv(raw, registry, options) {
     if (tokens.length === 0) {
         return undefined;
     }
+    const allTokenCount = tokens.filter((token) => token.trim().toLowerCase() === STATUS_ALL_SENTINEL).length;
+    if (allTokenCount > 0) {
+        if (tokens.length === 1) {
+            return undefined;
+        }
+        throw new PmCliError(`Invalid ${flagLabel} value "all". Use it by itself, or omit ${flagLabel} to search every status.`, EXIT_CODE.USAGE);
+    }
     const resolved = [];
     for (const token of tokens) {
         const status = resolveStatusFilterToken(token, registry);
@@ -99,4 +120,4 @@ export function parseStatusFilterCsv(raw, registry, options) {
     return [...new Set(resolved)];
 }
 //# sourceMappingURL=status-filter.js.map
-//# debugId=a820defb-5037-5162-aef4-7ac9d17cc596
+//# debugId=68b0f67b-4043-5b34-a8ed-39f5d6baea42

package/dist/core/item/status-filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"status-filter.js","sources":["core/item/status-filter.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/item/status-filter\n *\n * Defines item parsing, formatting, and lifecycle helpers for Status Filter.\n */\nimport { EXIT_CODE } from \"../shared/constants.js\";\nimport { PmCliError } from \"../shared/errors.js\";\nimport { levenshteinDistanceWithinLimit } from \"../shared/levenshtein.js\";\nimport type { RuntimeStatusRegistry } from \"../schema/runtime-schema.js\";\nimport type { ItemStatus } from \"../../types/index.js\";\nimport { normalizeStatusInput } from \"./status.js\";\n\n// Workflow-group aliases shared by every status-filter consumer so that the\n// agent-friendly `open`/`closed`/`canceled` shorthands resolve to whatever the\n// runtime workflow has configured as its open/close/cancel anchors, rather than\n// hardcoding the built-in status ids. `cancelled` is accepted as a spelling\n// variant of `canceled`.\nconst STATUS_GROUP_ALIASES: Readonly<Record<string, \"open_status\" | \"close_status\" | \"canceled_status\">> = {\n  open: \"open_status\",\n  closed: \"close_status\",\n  canceled: \"canceled_status\",\n  cancelled: \"canceled_status\",\n};\n\n/**\n * Resolve a single status-filter token to a concrete runtime status id.\n *\n * Returns `undefined` when the token is not a recognized workflow-group alias\n * (open/closed/canceled) and does not normalize to a known registry status.\n * Callers decide whether an unrecognized token is an error (strict mode) or is\n * passed through verbatim (lenient mode) — see {@link parseStatusFilterCsv}.\n */\nexport function resolveStatusFilterToken(\n  token: string,\n  registry: RuntimeStatusRegistry,\n): ItemStatus | undefined {\n  const trimmed = token.trim().toLowerCase();\n  if (trimmed.length === 0) {\n    return undefined;\n  }\n  const group = STATUS_GROUP_ALIASES[trimmed];\n  if (group) {\n    return registry[group] as ItemStatus;\n  }\n  return normalizeStatusInput(token, registry);\n}\n\nfunction collectStatusSuggestionCandidates(registry: RuntimeStatusRegistry): string[] {\n  const candidates = new Set<string>(Object.keys(STATUS_GROUP_ALIASES));\n  for (const definition of registry.definitions) {\n    candidates.add(definition.id);\n    for (const alias of definition.aliases) {\n      candidates.add(alias);\n    }\n  }\n  return [...candidates];\n}\n\nfunction suggestClosestStatus(value: string, registry: RuntimeStatusRegistry): string | undefined {\n  // Only ever called for an unresolved, already-non-empty token (parseStatusFilterCsv\n  // filters blanks first), so no empty-input guard is needed here.\n  const normalized = value.trim().toLowerCase();\n  let best: string | undefined;\n  let bestDistance = Number.POSITIVE_INFINITY;\n  for (const candidate of collectStatusSuggestionCandidates(registry)) {\n    const distance = levenshteinDistanceWithinLimit(normalized, candidate.toLowerCase(), 2);\n    if (distance !== null && distance < bestDistance) {\n      best = candidate;\n      bestDistance = distance;\n    }\n  }\n  return best;\n}\n\n/**\n * Documents the parse status filter options payload exchanged by command, SDK, and package integrations.\n */\nexport interface ParseStatusFilterOptions {\n  /**\n   * When true, an unrecognized token throws a USAGE error with a did-you-mean\n   * hint. When false (default), an unrecognized token is passed through\n   * verbatim so custom/unknown statuses still compare against item values by\n   * their raw string — preserving the long-standing lenient `pm list` behavior.\n   */\n  strict?: boolean;\n  /** Flag label used in error messages (default: \"--status\"). */\n  flagLabel?: string;\n}\n\n/**\n * Parse a comma-separated status filter into a de-duplicated list of concrete\n * status ids. Shared by `pm list` (lenient) and `pm search` (strict, with a\n * did-you-mean hint on typos) so both surfaces resolve the open/closed/canceled\n * workflow-group aliases identically.\n */\nexport function parseStatusFilterCsv(\n  raw: unknown,\n  registry: RuntimeStatusRegistry,\n  options?: ParseStatusFilterOptions,\n): ItemStatus[] | undefined {\n  if (typeof raw !== \"string\") {\n    return undefined;\n  }\n  const strict = options?.strict === true;\n  const flagLabel = options?.flagLabel ?? \"--status\";\n  const tokens = raw\n    .split(\",\")\n    .map((entry) => entry.trim())\n    .filter((entry) => entry.length > 0);\n  if (tokens.length === 0) {\n    return undefined;\n  }\n  const resolved: ItemStatus[] = [];\n  for (const token of tokens) {\n    const status = resolveStatusFilterToken(token, registry);\n    if (status === undefined) {\n      if (strict) {\n        const suggestion = suggestClosestStatus(token, registry);\n        throw new PmCliError(\n          `Invalid ${flagLabel} value \"${token}\". Use open|closed|canceled or a configured status id${\n            suggestion ? `. Did you mean \"${suggestion}\"?` : \".\"\n          }`,\n          EXIT_CODE.USAGE,\n        );\n      }\n      resolved.push(token as ItemStatus);\n      continue;\n    }\n    resolved.push(status);\n  }\n  return [...new Set(resolved)];\n}\n"],"names":[],"mappings":"AAAA;;;;GAIG;;;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,8BAA8B,EAAE,MAAM,0BAA0B,CAAC;AAG1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,4EAA4E;AAC5E,+EAA+E;AAC/E,gFAAgF;AAChF,4EAA4E;AAC5E,yBAAyB;AACzB,MAAM,oBAAoB,GAAiF;IACzG,IAAI,EAAE,aAAa;IACnB,MAAM,EAAE,cAAc;IACtB,QAAQ,EAAE,iBAAiB;IAC3B,SAAS,EAAE,iBAAiB;CAC7B,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAAa,EACb,QAA+B;IAE/B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,KAAK,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC5C,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,QAAQ,CAAC,KAAK,CAAe,CAAC;IACvC,CAAC;IACD,OAAO,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,iCAAiC,CAAC,QAA+B;IACxE,MAAM,UAAU,GAAG,IAAI,GAAG,CAAS,MAAM,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC;IACtE,KAAK,MAAM,UAAU,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC;QAC9C,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QAC9B,KAAK,MAAM,KAAK,IAAI,UAAU,CAAC,OAAO,EAAE,CAAC;YACvC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,UAAU,CAAC,CAAC;AACzB,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAa,EAAE,QAA+B;IAC1E,oFAAoF;IACpF,iEAAiE;IACjE,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,IAAI,IAAwB,CAAC;IAC7B,IAAI,YAAY,GAAG,MAAM,CAAC,iBAAiB,CAAC;IAC5C,KAAK,MAAM,SAAS,IAAI,iCAAiC,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpE,MAAM,QAAQ,GAAG,8BAA8B,CAAC,UAAU,EAAE,SAAS,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC;QACxF,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,GAAG,YAAY,EAAE,CAAC;YACjD,IAAI,GAAG,SAAS,CAAC;YACjB,YAAY,GAAG,QAAQ,CAAC;QAC1B,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAiBD;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAAY,EACZ,QAA+B,EAC/B,OAAkC;IAElC,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,UAAU,CAAC;IACnD,MAAM,MAAM,GAAG,GAAG;SACf,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;SAC5B,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACvC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,QAAQ,GAAiB,EAAE,CAAC;IAClC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,wBAAwB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACzD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,UAAU,GAAG,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;gBACzD,MAAM,IAAI,UAAU,CAClB,WAAW,SAAS,WAAW,KAAK,wDAClC,UAAU,CAAC,CAAC,CAAC,mBAAmB,UAAU,IAAI,CAAC,CAAC,CAAC,GACnD,EAAE,EACF,SAAS,CAAC,KAAK,CAChB,CAAC;YACJ,CAAC;YACD,QAAQ,CAAC,IAAI,CAAC,KAAmB,CAAC,CAAC;YACnC,SAAS;QACX,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC;AAChC,CAAC","debugId":"a820defb-5037-5162-aef4-7ac9d17cc596"}
+{"version":3,"file":"status-filter.js","sources":["core/item/status-filter.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/item/status-filter\n *\n * Defines item parsing, formatting, and lifecycle helpers for Status Filter.\n */\nimport { EXIT_CODE } from \"../shared/constants.js\";\nimport { PmCliError } from \"../shared/errors.js\";\nimport { levenshteinDistanceWithinLimit } from \"../shared/levenshtein.js\";\nimport type { RuntimeStatusRegistry } from \"../schema/runtime-schema.js\";\nimport type { ItemStatus } from \"../../types/index.js\";\nimport { normalizeStatusInput } from \"./status.js\";\n\n// Workflow-group aliases shared by every status-filter consumer so that the\n// agent-friendly `open`/`closed`/`canceled` shorthands resolve to whatever the\n// runtime workflow has configured as its open/close/cancel anchors, rather than\n// hardcoding the built-in status ids. `cancelled` is accepted as a spelling\n// variant of `canceled`.\nconst STATUS_GROUP_ALIASES: Readonly<Record<string, \"open_status\" | \"close_status\" | \"canceled_status\">> = {\n  open: \"open_status\",\n  closed: \"close_status\",\n  canceled: \"canceled_status\",\n  cancelled: \"canceled_status\",\n};\n\nconst STATUS_ALL_SENTINEL = \"all\";\n\n/** Return true when a status-filter input is the standalone all-status sentinel. */\nexport function isStatusAllFilterInput(raw: unknown): boolean {\n  if (typeof raw !== \"string\") {\n    return false;\n  }\n  const tokens = raw\n    .split(\",\")\n    .map((entry) => entry.trim().toLowerCase())\n    .filter((entry) => entry.length > 0);\n  return tokens.length === 1 && tokens[0] === STATUS_ALL_SENTINEL;\n}\n\n/**\n * Resolve a single status-filter token to a concrete runtime status id.\n *\n * Returns `undefined` when the token is not a recognized workflow-group alias\n * (open/closed/canceled) and does not normalize to a known registry status.\n * Callers decide whether an unrecognized token is an error (strict mode) or is\n * passed through verbatim (lenient mode) — see {@link parseStatusFilterCsv}.\n */\nexport function resolveStatusFilterToken(\n  token: string,\n  registry: RuntimeStatusRegistry,\n): ItemStatus | undefined {\n  const trimmed = token.trim().toLowerCase();\n  if (trimmed.length === 0) {\n    return undefined;\n  }\n  const group = STATUS_GROUP_ALIASES[trimmed];\n  if (group) {\n    return registry[group] as ItemStatus;\n  }\n  return normalizeStatusInput(token, registry);\n}\n\nfunction collectStatusSuggestionCandidates(registry: RuntimeStatusRegistry): string[] {\n  const candidates = new Set<string>(Object.keys(STATUS_GROUP_ALIASES));\n  for (const definition of registry.definitions) {\n    candidates.add(definition.id);\n    for (const alias of definition.aliases) {\n      candidates.add(alias);\n    }\n  }\n  return [...candidates];\n}\n\nfunction suggestClosestStatus(value: string, registry: RuntimeStatusRegistry): string | undefined {\n  // Only ever called for an unresolved, already-non-empty token (parseStatusFilterCsv\n  // filters blanks first), so no empty-input guard is needed here.\n  const normalized = value.trim().toLowerCase();\n  let best: string | undefined;\n  let bestDistance = Number.POSITIVE_INFINITY;\n  for (const candidate of collectStatusSuggestionCandidates(registry)) {\n    const distance = levenshteinDistanceWithinLimit(normalized, candidate.toLowerCase(), 2);\n    if (distance !== null && distance < bestDistance) {\n      best = candidate;\n      bestDistance = distance;\n    }\n  }\n  return best;\n}\n\n/**\n * Documents the parse status filter options payload exchanged by command, SDK, and package integrations.\n */\nexport interface ParseStatusFilterOptions {\n  /**\n   * When true, an unrecognized token throws a USAGE error with a did-you-mean\n   * hint. When false (default), an unrecognized token is passed through\n   * verbatim so custom/unknown statuses still compare against item values by\n   * their raw string — preserving the long-standing lenient `pm list` behavior.\n   */\n  strict?: boolean;\n  /** Flag label used in error messages (default: \"--status\"). */\n  flagLabel?: string;\n}\n\n/**\n * Parse a comma-separated status filter into a de-duplicated list of concrete\n * status ids. A standalone `all` sentinel intentionally resolves to no filter\n * so duplicate-discovery loops can search every lifecycle bucket with the same\n * `--status` flag shape. Shared by `pm list` (lenient) and `pm search`\n * (strict, with a did-you-mean hint on typos) so both surfaces resolve the\n * open/closed/canceled workflow-group aliases identically.\n */\nexport function parseStatusFilterCsv(\n  raw: unknown,\n  registry: RuntimeStatusRegistry,\n  options?: ParseStatusFilterOptions,\n): ItemStatus[] | undefined {\n  if (typeof raw !== \"string\") {\n    return undefined;\n  }\n  const strict = options?.strict === true;\n  const flagLabel = options?.flagLabel ?? \"--status\";\n  const tokens = raw\n    .split(\",\")\n    .map((entry) => entry.trim())\n    .filter((entry) => entry.length > 0);\n  if (tokens.length === 0) {\n    return undefined;\n  }\n  const allTokenCount = tokens.filter((token) => token.trim().toLowerCase() === STATUS_ALL_SENTINEL).length;\n  if (allTokenCount > 0) {\n    if (tokens.length === 1) {\n      return undefined;\n    }\n    throw new PmCliError(\n      `Invalid ${flagLabel} value \"all\". Use it by itself, or omit ${flagLabel} to search every status.`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  const resolved: ItemStatus[] = [];\n  for (const token of tokens) {\n    const status = resolveStatusFilterToken(token, registry);\n    if (status === undefined) {\n      if (strict) {\n        const suggestion = suggestClosestStatus(token, registry);\n        throw new PmCliError(\n          `Invalid ${flagLabel} value \"${token}\". Use open|closed|canceled or a configured status id${\n            suggestion ? `. Did you mean \"${suggestion}\"?` : \".\"\n          }`,\n          EXIT_CODE.USAGE,\n        );\n      }\n      resolved.push(token as ItemStatus);\n      continue;\n    }\n    resolved.push(status);\n  }\n  return [...new Set(resolved)];\n}\n"],"names":[],"mappings":"AAAA;;;;GAIG;;;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,8BAA8B,EAAE,MAAM,0BAA0B,CAAC;AAG1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,4EAA4E;AAC5E,+EAA+E;AAC/E,gFAAgF;AAChF,4EAA4E;AAC5E,yBAAyB;AACzB,MAAM,oBAAoB,GAAiF;IACzG,IAAI,EAAE,aAAa;IACnB,MAAM,EAAE,cAAc;IACtB,QAAQ,EAAE,iBAAiB;IAC3B,SAAS,EAAE,iBAAiB;CAC7B,CAAC;AAEF,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAElC,oFAAoF;AACpF,MAAM,UAAU,sBAAsB,CAAC,GAAY;IACjD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,MAAM,GAAG,GAAG;SACf,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;SAC1C,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACvC,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,mBAAmB,CAAC;AAClE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAAa,EACb,QAA+B;IAE/B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,KAAK,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC5C,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,QAAQ,CAAC,KAAK,CAAe,CAAC;IACvC,CAAC;IACD,OAAO,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,iCAAiC,CAAC,QAA+B;IACxE,MAAM,UAAU,GAAG,IAAI,GAAG,CAAS,MAAM,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC;IACtE,KAAK,MAAM,UAAU,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC;QAC9C,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QAC9B,KAAK,MAAM,KAAK,IAAI,UAAU,CAAC,OAAO,EAAE,CAAC;YACvC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,UAAU,CAAC,CAAC;AACzB,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAa,EAAE,QAA+B;IAC1E,oFAAoF;IACpF,iEAAiE;IACjE,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,IAAI,IAAwB,CAAC;IAC7B,IAAI,YAAY,GAAG,MAAM,CAAC,iBAAiB,CAAC;IAC5C,KAAK,MAAM,SAAS,IAAI,iCAAiC,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpE,MAAM,QAAQ,GAAG,8BAA8B,CAAC,UAAU,EAAE,SAAS,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC;QACxF,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,GAAG,YAAY,EAAE,CAAC;YACjD,IAAI,GAAG,SAAS,CAAC;YACjB,YAAY,GAAG,QAAQ,CAAC;QAC1B,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAiBD;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAAY,EACZ,QAA+B,EAC/B,OAAkC;IAElC,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,UAAU,CAAC;IACnD,MAAM,MAAM,GAAG,GAAG;SACf,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;SAC5B,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACvC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,mBAAmB,CAAC,CAAC,MAAM,CAAC;IAC1G,IAAI,aAAa,GAAG,CAAC,EAAE,CAAC;QACtB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,IAAI,UAAU,CAClB,WAAW,SAAS,2CAA2C,SAAS,0BAA0B,EAClG,SAAS,CAAC,KAAK,CAChB,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAiB,EAAE,CAAC;IAClC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,wBAAwB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACzD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,UAAU,GAAG,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;gBACzD,MAAM,IAAI,UAAU,CAClB,WAAW,SAAS,WAAW,KAAK,wDAClC,UAAU,CAAC,CAAC,CAAC,mBAAmB,UAAU,IAAI,CAAC,CAAC,CAAC,GACnD,EAAE,EACF,SAAS,CAAC,KAAK,CAChB,CAAC;YACJ,CAAC;YACD,QAAQ,CAAC,IAAI,CAAC,KAAmB,CAAC,CAAC;YACnC,SAAS;QACX,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC;AAChC,CAAC","debugId":"68b0f67b-4043-5b34-a8ed-39f5d6baea42"}

package/dist/core/search/bm25.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @module core/search/bm25
+ *
+ * Offline BM25 lexical retrieval (pm-75k9). Provides an Okapi BM25 ranker that
+ * scores the in-memory item corpus with no embedding service, vector store, or
+ * network dependency, so semantic/hybrid search degrades to a dense-quality
+ * lexical ranker — rather than the naive field-weighted scorer — in air-gapped,
+ * CI, and zero-setup environments.
+ *
+ * BM25 improves on raw term-frequency counting in three ways the legacy keyword
+ * scorer cannot: inverse document frequency down-weights terms common across the
+ * whole corpus, term-frequency saturation (`k1`) caps the contribution of a term
+ * repeated many times in one document, and length normalization (`b`) prevents
+ * long documents from dominating purely by size.
+ */
+import type { PmSettings } from "../../types/index.js";
+/**
+ * Default Okapi BM25 term-frequency saturation parameter. `1.2` is the widely
+ * used Lucene/Elasticsearch default: higher values reduce the diminishing
+ * returns of repeated terms more slowly (terms keep accruing weight), lower
+ * values saturate sooner.
+ */
+export declare const DEFAULT_BM25_K1 = 1.2;
+/**
+ * Default Okapi BM25 length-normalization parameter. `0.75` is the Lucene
+ * default: `0` disables length normalization entirely, `1` fully normalizes a
+ * document's score by its length relative to the corpus average.
+ */
+export declare const DEFAULT_BM25_B = 0.75;
+/**
+ * Resolved BM25 tuning parameters. Both are clamped to sane ranges by
+ * {@link resolveBm25Params} before scoring.
+ */
+export interface Bm25Params {
+    /** Term-frequency saturation (`k1`); finite and `>= 0`. */
+    k1: number;
+    /** Length normalization (`b`); finite and within `[0, 1]`. */
+    b: number;
+}
+/**
+ * One corpus document supplied to {@link buildBm25Index}: a stable id and the
+ * already-concatenated searchable text. Callers build the text from whichever
+ * fields they want indexed (typically the resolved `search.corpus_fields`).
+ */
+export interface Bm25Document {
+    id: string;
+    text: string;
+}
+/**
+ * Per-document statistics retained in a {@link Bm25Index}: the term-frequency
+ * map and the document length (total token count) used for length
+ * normalization.
+ */
+interface Bm25DocumentStats {
+    id: string;
+    termFrequencies: Map<string, number>;
+    length: number;
+}
+/**
+ * An immutable BM25 index built from a document set. Carries the per-document
+ * term frequencies, per-term document frequencies, corpus size, and average
+ * document length needed to score any query. Build once per query batch with
+ * {@link buildBm25Index}, then score with {@link scoreBm25Query}.
+ */
+export interface Bm25Index {
+    documents: Bm25DocumentStats[];
+    documentFrequency: Map<string, number>;
+    documentCount: number;
+    averageDocumentLength: number;
+}
+/**
+ * Tokenize a document/query string into BM25 terms. Shares
+ * {@link tokenizeAlphaNumeric} with the lexical scorer so the BM25 vocabulary is
+ * identical to the rest of search: lowercase, alphanumeric runs, no stop-word
+ * removal or stemming (kept deliberately simple and language-agnostic).
+ */
+export declare function tokenizeBm25(text: string): string[];
+/**
+ * Build a BM25 index from a corpus. Computes each document's term frequencies
+ * and length, the per-term document frequency, the corpus size, and the average
+ * document length. Empty documents (no tokens) are retained with length `0` so
+ * they can still be scored (they simply never match a query term). An empty
+ * corpus yields an index with `averageDocumentLength` `0`, which
+ * {@link scoreBm25Query} handles without dividing by zero.
+ */
+export declare function buildBm25Index(documents: Bm25Document[]): Bm25Index;
+/**
+ * Score every document in the index against a query and return an id → score
+ * map containing only documents with a strictly positive score (a document that
+ * matches no query term is omitted, mirroring the lexical scorer's "no match →
+ * no hit" contract). Query tokens are de-duplicated so a token repeated in the
+ * query does not multiply its own contribution. Returns an empty map for an
+ * empty index, an empty query, or a query whose terms appear in no document.
+ */
+export declare function scoreBm25Query(index: Bm25Index, queryTokens: string[], params: Bm25Params): Map<string, number>;
+/**
+ * Flatten a structured search-corpus record (the shape produced by
+ * `buildSearchCorpus`) into a single whitespace-joined string of its *values*
+ * only — field names/object keys are deliberately excluded so corpus-wide keys
+ * (`title`, `description`, …) never enter the BM25 vocabulary and skew IDF.
+ * Strings and numbers contribute their text; arrays and nested objects (tags,
+ * dependencies, the plan corpus) are walked recursively; everything else is
+ * dropped.
+ */
+export declare function flattenSearchCorpusText(corpus: Record<string, unknown>): string;
+/**
+ * Resolve the effective BM25 parameters from `settings.search.bm25`, applying
+ * {@link DEFAULT_BM25_K1}/{@link DEFAULT_BM25_B} when unset and clamping `k1` to
+ * `[0, 1000]` and `b` to `[0, 1]`. Tolerant of partial/invalid config: each
+ * knob is resolved independently so one bad value does not discard the other.
+ */
+export declare function resolveBm25Params(settings: Pick<PmSettings, "search"> | undefined): Bm25Params;
+export {};

package/dist/core/search/bm25.js

@@ -0,0 +1,178 @@
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="57c1eb74-63b5-5208-abe1-98da8308839d")}catch(e){}}();
+import { tokenizeAlphaNumeric } from "../shared/text-normalization.js";
+/**
+ * Default Okapi BM25 term-frequency saturation parameter. `1.2` is the widely
+ * used Lucene/Elasticsearch default: higher values reduce the diminishing
+ * returns of repeated terms more slowly (terms keep accruing weight), lower
+ * values saturate sooner.
+ */
+export const DEFAULT_BM25_K1 = 1.2;
+/**
+ * Default Okapi BM25 length-normalization parameter. `0.75` is the Lucene
+ * default: `0` disables length normalization entirely, `1` fully normalizes a
+ * document's score by its length relative to the corpus average.
+ */
+export const DEFAULT_BM25_B = 0.75;
+/**
+ * Tokenize a document/query string into BM25 terms. Shares
+ * {@link tokenizeAlphaNumeric} with the lexical scorer so the BM25 vocabulary is
+ * identical to the rest of search: lowercase, alphanumeric runs, no stop-word
+ * removal or stemming (kept deliberately simple and language-agnostic).
+ */
+export function tokenizeBm25(text) {
+    return tokenizeAlphaNumeric(text);
+}
+/**
+ * Count occurrences of each token in a token list.
+ */
+function buildTermFrequencies(tokens) {
+    const frequencies = new Map();
+    for (const token of tokens) {
+        frequencies.set(token, (frequencies.get(token) ?? 0) + 1);
+    }
+    return frequencies;
+}
+/**
+ * Build a BM25 index from a corpus. Computes each document's term frequencies
+ * and length, the per-term document frequency, the corpus size, and the average
+ * document length. Empty documents (no tokens) are retained with length `0` so
+ * they can still be scored (they simply never match a query term). An empty
+ * corpus yields an index with `averageDocumentLength` `0`, which
+ * {@link scoreBm25Query} handles without dividing by zero.
+ */
+export function buildBm25Index(documents) {
+    const stats = [];
+    const documentFrequency = new Map();
+    let totalLength = 0;
+    for (const document of documents) {
+        const tokens = tokenizeBm25(document.text);
+        const termFrequencies = buildTermFrequencies(tokens);
+        totalLength += tokens.length;
+        for (const term of termFrequencies.keys()) {
+            documentFrequency.set(term, (documentFrequency.get(term) ?? 0) + 1);
+        }
+        stats.push({ id: document.id, termFrequencies, length: tokens.length });
+    }
+    const documentCount = stats.length;
+    return {
+        documents: stats,
+        documentFrequency,
+        documentCount,
+        averageDocumentLength: documentCount > 0 ? totalLength / documentCount : 0,
+    };
+}
+/**
+ * Inverse document frequency for one term using the BM25 "plus-one" variant
+ * (`ln(1 + (N - n + 0.5) / (n + 0.5))`) used by Lucene. The `1 +` inside the
+ * logarithm keeps the IDF strictly non-negative even for a term that appears in
+ * every document, so a common term can never subtract from a document's score.
+ */
+function inverseDocumentFrequency(documentCount, termDocumentFrequency) {
+    return Math.log(1 + (documentCount - termDocumentFrequency + 0.5) / (termDocumentFrequency + 0.5));
+}
+/**
+ * Score every document in the index against a query and return an id → score
+ * map containing only documents with a strictly positive score (a document that
+ * matches no query term is omitted, mirroring the lexical scorer's "no match →
+ * no hit" contract). Query tokens are de-duplicated so a token repeated in the
+ * query does not multiply its own contribution. Returns an empty map for an
+ * empty index, an empty query, or a query whose terms appear in no document.
+ */
+export function scoreBm25Query(index, queryTokens, params) {
+    const scores = new Map();
+    // Empty corpus, or a corpus where every document is empty (avgdl 0): no term
+    // can match, so return early. Guarding here also guarantees a non-zero
+    // average document length below, keeping the length-normalization division
+    // safe without an unreachable fallback branch.
+    if (index.documentCount === 0 || index.averageDocumentLength === 0) {
+        return scores;
+    }
+    const distinctQueryTerms = [...new Set(queryTokens.filter((token) => token.length > 0))];
+    if (distinctQueryTerms.length === 0) {
+        return scores;
+    }
+    // Precompute the IDF for each query term once rather than per document.
+    const idfByTerm = new Map();
+    for (const term of distinctQueryTerms) {
+        const termDocumentFrequency = index.documentFrequency.get(term);
+        if (termDocumentFrequency === undefined) {
+            continue;
+        }
+        idfByTerm.set(term, inverseDocumentFrequency(index.documentCount, termDocumentFrequency));
+    }
+    if (idfByTerm.size === 0) {
+        return scores;
+    }
+    for (const document of index.documents) {
+        let score = 0;
+        for (const [term, idf] of idfByTerm) {
+            const termFrequency = document.termFrequencies.get(term);
+            if (termFrequency === undefined) {
+                continue;
+            }
+            const lengthNormalization = 1 - params.b + (params.b * document.length) / index.averageDocumentLength;
+            const denominator = termFrequency + params.k1 * lengthNormalization;
+            score += idf * ((termFrequency * (params.k1 + 1)) / denominator);
+        }
+        if (score > 0) {
+            scores.set(document.id, score);
+        }
+    }
+    return scores;
+}
+/**
+ * Coerce one persisted BM25 parameter to a finite number within `[min, max]`.
+ * A finite number is clamped to the range (preserving user intent — e.g.
+ * `k1=5000` becomes `1000` rather than being silently ignored); any non-number
+ * or non-finite value (string, `NaN`, `Infinity`, missing) falls back to
+ * `fallback` so a malformed `settings.json` can never crash or skew scoring.
+ */
+function resolveClampedParam(candidate, fallback, min, max) {
+    if (typeof candidate !== "number" || !Number.isFinite(candidate)) {
+        return fallback;
+    }
+    return Math.min(max, Math.max(min, candidate));
+}
+/**
+ * Flatten a structured search-corpus record (the shape produced by
+ * `buildSearchCorpus`) into a single whitespace-joined string of its *values*
+ * only — field names/object keys are deliberately excluded so corpus-wide keys
+ * (`title`, `description`, …) never enter the BM25 vocabulary and skew IDF.
+ * Strings and numbers contribute their text; arrays and nested objects (tags,
+ * dependencies, the plan corpus) are walked recursively; everything else is
+ * dropped.
+ */
+export function flattenSearchCorpusText(corpus) {
+    const collectValueText = (value) => {
+        if (typeof value === "string") {
+            return [value];
+        }
+        if (typeof value === "number") {
+            return [String(value)];
+        }
+        if (Array.isArray(value)) {
+            return value.flatMap(collectValueText);
+        }
+        if (typeof value === "object" && value !== null) {
+            return Object.values(value).flatMap(collectValueText);
+        }
+        return [];
+    };
+    return collectValueText(Object.values(corpus)).join(" ");
+}
+/**
+ * Resolve the effective BM25 parameters from `settings.search.bm25`, applying
+ * {@link DEFAULT_BM25_K1}/{@link DEFAULT_BM25_B} when unset and clamping `k1` to
+ * `[0, 1000]` and `b` to `[0, 1]`. Tolerant of partial/invalid config: each
+ * knob is resolved independently so one bad value does not discard the other.
+ */
+export function resolveBm25Params(settings) {
+    const bm25 = settings?.search?.bm25;
+    return {
+        k1: resolveClampedParam(bm25?.k1, DEFAULT_BM25_K1, 0, 1_000),
+        b: resolveClampedParam(bm25?.b, DEFAULT_BM25_B, 0, 1),
+    };
+}
+//# sourceMappingURL=bm25.js.map
+//# debugId=57c1eb74-63b5-5208-abe1-98da8308839d

package/dist/core/search/bm25.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bm25.js","sources":["core/search/bm25.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/search/bm25\n *\n * Offline BM25 lexical retrieval (pm-75k9). Provides an Okapi BM25 ranker that\n * scores the in-memory item corpus with no embedding service, vector store, or\n * network dependency, so semantic/hybrid search degrades to a dense-quality\n * lexical ranker — rather than the naive field-weighted scorer — in air-gapped,\n * CI, and zero-setup environments.\n *\n * BM25 improves on raw term-frequency counting in three ways the legacy keyword\n * scorer cannot: inverse document frequency down-weights terms common across the\n * whole corpus, term-frequency saturation (`k1`) caps the contribution of a term\n * repeated many times in one document, and length normalization (`b`) prevents\n * long documents from dominating purely by size.\n */\nimport type { PmSettings } from \"../../types/index.js\";\nimport { tokenizeAlphaNumeric } from \"../shared/text-normalization.js\";\n\n/**\n * Default Okapi BM25 term-frequency saturation parameter. `1.2` is the widely\n * used Lucene/Elasticsearch default: higher values reduce the diminishing\n * returns of repeated terms more slowly (terms keep accruing weight), lower\n * values saturate sooner.\n */\nexport const DEFAULT_BM25_K1 = 1.2;\n\n/**\n * Default Okapi BM25 length-normalization parameter. `0.75` is the Lucene\n * default: `0` disables length normalization entirely, `1` fully normalizes a\n * document's score by its length relative to the corpus average.\n */\nexport const DEFAULT_BM25_B = 0.75;\n\n/**\n * Resolved BM25 tuning parameters. Both are clamped to sane ranges by\n * {@link resolveBm25Params} before scoring.\n */\nexport interface Bm25Params {\n  /** Term-frequency saturation (`k1`); finite and `>= 0`. */\n  k1: number;\n  /** Length normalization (`b`); finite and within `[0, 1]`. */\n  b: number;\n}\n\n/**\n * One corpus document supplied to {@link buildBm25Index}: a stable id and the\n * already-concatenated searchable text. Callers build the text from whichever\n * fields they want indexed (typically the resolved `search.corpus_fields`).\n */\nexport interface Bm25Document {\n  id: string;\n  text: string;\n}\n\n/**\n * Per-document statistics retained in a {@link Bm25Index}: the term-frequency\n * map and the document length (total token count) used for length\n * normalization.\n */\ninterface Bm25DocumentStats {\n  id: string;\n  termFrequencies: Map<string, number>;\n  length: number;\n}\n\n/**\n * An immutable BM25 index built from a document set. Carries the per-document\n * term frequencies, per-term document frequencies, corpus size, and average\n * document length needed to score any query. Build once per query batch with\n * {@link buildBm25Index}, then score with {@link scoreBm25Query}.\n */\nexport interface Bm25Index {\n  documents: Bm25DocumentStats[];\n  documentFrequency: Map<string, number>;\n  documentCount: number;\n  averageDocumentLength: number;\n}\n\n/**\n * Tokenize a document/query string into BM25 terms. Shares\n * {@link tokenizeAlphaNumeric} with the lexical scorer so the BM25 vocabulary is\n * identical to the rest of search: lowercase, alphanumeric runs, no stop-word\n * removal or stemming (kept deliberately simple and language-agnostic).\n */\nexport function tokenizeBm25(text: string): string[] {\n  return tokenizeAlphaNumeric(text);\n}\n\n/**\n * Count occurrences of each token in a token list.\n */\nfunction buildTermFrequencies(tokens: string[]): Map<string, number> {\n  const frequencies = new Map<string, number>();\n  for (const token of tokens) {\n    frequencies.set(token, (frequencies.get(token) ?? 0) + 1);\n  }\n  return frequencies;\n}\n\n/**\n * Build a BM25 index from a corpus. Computes each document's term frequencies\n * and length, the per-term document frequency, the corpus size, and the average\n * document length. Empty documents (no tokens) are retained with length `0` so\n * they can still be scored (they simply never match a query term). An empty\n * corpus yields an index with `averageDocumentLength` `0`, which\n * {@link scoreBm25Query} handles without dividing by zero.\n */\nexport function buildBm25Index(documents: Bm25Document[]): Bm25Index {\n  const stats: Bm25DocumentStats[] = [];\n  const documentFrequency = new Map<string, number>();\n  let totalLength = 0;\n  for (const document of documents) {\n    const tokens = tokenizeBm25(document.text);\n    const termFrequencies = buildTermFrequencies(tokens);\n    totalLength += tokens.length;\n    for (const term of termFrequencies.keys()) {\n      documentFrequency.set(term, (documentFrequency.get(term) ?? 0) + 1);\n    }\n    stats.push({ id: document.id, termFrequencies, length: tokens.length });\n  }\n  const documentCount = stats.length;\n  return {\n    documents: stats,\n    documentFrequency,\n    documentCount,\n    averageDocumentLength: documentCount > 0 ? totalLength / documentCount : 0,\n  };\n}\n\n/**\n * Inverse document frequency for one term using the BM25 \"plus-one\" variant\n * (`ln(1 + (N - n + 0.5) / (n + 0.5))`) used by Lucene. The `1 +` inside the\n * logarithm keeps the IDF strictly non-negative even for a term that appears in\n * every document, so a common term can never subtract from a document's score.\n */\nfunction inverseDocumentFrequency(documentCount: number, termDocumentFrequency: number): number {\n  return Math.log(1 + (documentCount - termDocumentFrequency + 0.5) / (termDocumentFrequency + 0.5));\n}\n\n/**\n * Score every document in the index against a query and return an id → score\n * map containing only documents with a strictly positive score (a document that\n * matches no query term is omitted, mirroring the lexical scorer's \"no match →\n * no hit\" contract). Query tokens are de-duplicated so a token repeated in the\n * query does not multiply its own contribution. Returns an empty map for an\n * empty index, an empty query, or a query whose terms appear in no document.\n */\nexport function scoreBm25Query(index: Bm25Index, queryTokens: string[], params: Bm25Params): Map<string, number> {\n  const scores = new Map<string, number>();\n  // Empty corpus, or a corpus where every document is empty (avgdl 0): no term\n  // can match, so return early. Guarding here also guarantees a non-zero\n  // average document length below, keeping the length-normalization division\n  // safe without an unreachable fallback branch.\n  if (index.documentCount === 0 || index.averageDocumentLength === 0) {\n    return scores;\n  }\n  const distinctQueryTerms = [...new Set(queryTokens.filter((token) => token.length > 0))];\n  if (distinctQueryTerms.length === 0) {\n    return scores;\n  }\n  // Precompute the IDF for each query term once rather than per document.\n  const idfByTerm = new Map<string, number>();\n  for (const term of distinctQueryTerms) {\n    const termDocumentFrequency = index.documentFrequency.get(term);\n    if (termDocumentFrequency === undefined) {\n      continue;\n    }\n    idfByTerm.set(term, inverseDocumentFrequency(index.documentCount, termDocumentFrequency));\n  }\n  if (idfByTerm.size === 0) {\n    return scores;\n  }\n  for (const document of index.documents) {\n    let score = 0;\n    for (const [term, idf] of idfByTerm) {\n      const termFrequency = document.termFrequencies.get(term);\n      if (termFrequency === undefined) {\n        continue;\n      }\n      const lengthNormalization =\n        1 - params.b + (params.b * document.length) / index.averageDocumentLength;\n      const denominator = termFrequency + params.k1 * lengthNormalization;\n      score += idf * ((termFrequency * (params.k1 + 1)) / denominator);\n    }\n    if (score > 0) {\n      scores.set(document.id, score);\n    }\n  }\n  return scores;\n}\n\n/**\n * Coerce one persisted BM25 parameter to a finite number within `[min, max]`.\n * A finite number is clamped to the range (preserving user intent — e.g.\n * `k1=5000` becomes `1000` rather than being silently ignored); any non-number\n * or non-finite value (string, `NaN`, `Infinity`, missing) falls back to\n * `fallback` so a malformed `settings.json` can never crash or skew scoring.\n */\nfunction resolveClampedParam(candidate: unknown, fallback: number, min: number, max: number): number {\n  if (typeof candidate !== \"number\" || !Number.isFinite(candidate)) {\n    return fallback;\n  }\n  return Math.min(max, Math.max(min, candidate));\n}\n\n/**\n * Flatten a structured search-corpus record (the shape produced by\n * `buildSearchCorpus`) into a single whitespace-joined string of its *values*\n * only — field names/object keys are deliberately excluded so corpus-wide keys\n * (`title`, `description`, …) never enter the BM25 vocabulary and skew IDF.\n * Strings and numbers contribute their text; arrays and nested objects (tags,\n * dependencies, the plan corpus) are walked recursively; everything else is\n * dropped.\n */\nexport function flattenSearchCorpusText(corpus: Record<string, unknown>): string {\n  const collectValueText = (value: unknown): string[] => {\n    if (typeof value === \"string\") {\n      return [value];\n    }\n    if (typeof value === \"number\") {\n      return [String(value)];\n    }\n    if (Array.isArray(value)) {\n      return value.flatMap(collectValueText);\n    }\n    if (typeof value === \"object\" && value !== null) {\n      return Object.values(value).flatMap(collectValueText);\n    }\n    return [];\n  };\n  return collectValueText(Object.values(corpus)).join(\" \");\n}\n\n/**\n * Resolve the effective BM25 parameters from `settings.search.bm25`, applying\n * {@link DEFAULT_BM25_K1}/{@link DEFAULT_BM25_B} when unset and clamping `k1` to\n * `[0, 1000]` and `b` to `[0, 1]`. Tolerant of partial/invalid config: each\n * knob is resolved independently so one bad value does not discard the other.\n */\nexport function resolveBm25Params(settings: Pick<PmSettings, \"search\"> | undefined): Bm25Params {\n  const bm25 = (settings?.search as { bm25?: { k1?: unknown; b?: unknown } } | undefined)?.bm25;\n  return {\n    k1: resolveClampedParam(bm25?.k1, DEFAULT_BM25_K1, 0, 1_000),\n    b: resolveClampedParam(bm25?.b, DEFAULT_BM25_B, 0, 1),\n  };\n}\n"],"names":[],"mappings":"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","debugId":"57c1eb74-63b5-5208-abe1-98da8308839d"}

package/dist/core/search/eval.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @module core/search/eval
+ *
+ * Search relevance evaluation primitives (pm-u8n5). Implements the standard
+ * offline ranking metrics — nDCG@k, MRR@k, precision@k, recall@k — over a
+ * human-curated golden-query set, plus the loader/validator for that set. The
+ * `pm eval` command (src/cli/commands/eval.ts) runs each golden query through
+ * the live retrieval path and feeds the ranked ids here, so relevance
+ * regressions from corpus changes, hybrid-weight changes, or provider swaps are
+ * measurable and gateable in CI.
+ *
+ * Relevance is binary: an id is either in a query's `relevant_ids` set or it is
+ * not. This keeps the golden set cheap to curate while still supporting the
+ * graded-discount behavior of DCG (earlier hits are worth more).
+ */
+/**
+ * Retrieval mode a golden query is evaluated under. Mirrors the `pm search`
+ * mode surface; omitting it on a query defers to the eval run's default mode.
+ */
+export type EvalSearchMode = "keyword" | "semantic" | "hybrid";
+/** Default cutoff (`@k`) used for every metric when the caller does not override it. */
+export declare const DEFAULT_EVAL_K = 10;
+/**
+ * One curated golden query: the query text, the set of item ids considered
+ * relevant, an optional per-query retrieval mode override, and an optional
+ * human-readable description of the relevance intent.
+ */
+export interface EvalQuery {
+    query: string;
+    relevant_ids: string[];
+    mode?: EvalSearchMode;
+    description?: string;
+}
+/** A parsed, validated golden-query set. */
+export interface EvalQuerySet {
+    queries: EvalQuery[];
+}
+/**
+ * Thrown by {@link parseEvalQuerySet} when the raw golden-query payload is
+ * structurally invalid. Carries a precise, human-actionable message naming the
+ * offending query index/field so an author can fix the JSON directly.
+ */
+export declare class EvalQuerySetError extends Error {
+    /** Construct an error describing why a golden-query set failed validation. */
+    constructor(message: string);
+}
+/**
+ * Compute Discounted Cumulative Gain at cutoff `k` for an ordered list of binary
+ * relevance gains (`1` relevant, `0` not). Position `i` (1-based) contributes
+ * `gain / log2(i + 1)`, so a relevant hit ranked first is worth `1` and later
+ * hits are progressively discounted. Gains beyond `k` are ignored.
+ */
+export declare function dcgAtK(relevanceGains: number[], k: number): number;
+/**
+ * Normalized DCG at cutoff `k`: the ranking's DCG divided by the DCG of the
+ * ideal ranking (all relevant ids first). Returns `0` when the query has no
+ * relevant ids (the ideal DCG is `0` and the score is undefined), giving a
+ * stable lower bound for aggregation. Result is in `[0, 1]`.
+ */
+export declare function ndcgAtK(rankedIds: string[], relevantIds: ReadonlySet<string>, k: number): number;
+/**
+ * Reciprocal rank of the first relevant id within the top `k` results: `1/rank`
+ * (rank is 1-based), or `0` when no relevant id appears in the cutoff. Averaged
+ * across queries this is Mean Reciprocal Rank (MRR@k).
+ */
+export declare function reciprocalRankAtK(rankedIds: string[], relevantIds: ReadonlySet<string>, k: number): number;
+/**
+ * Precision at cutoff `k`: relevant ids retrieved in the top `k` divided by `k`.
+ * Returns `0` for a non-positive `k`.
+ */
+export declare function precisionAtK(rankedIds: string[], relevantIds: ReadonlySet<string>, k: number): number;
+/**
+ * Recall at cutoff `k`: relevant ids retrieved in the top `k` divided by the
+ * total number of relevant ids. Returns `0` when the query has no relevant ids.
+ */
+export declare function recallAtK(rankedIds: string[], relevantIds: ReadonlySet<string>, k: number): number;
+/** The four ranking metrics computed for a single query, plus match counts. */
+export interface QueryEvalMetrics {
+    ndcg: number;
+    mrr: number;
+    precision: number;
+    recall: number;
+    relevant_total: number;
+    retrieved_relevant: number;
+}
+/**
+ * Evaluate one ranking against its relevant-id set at cutoff `k`, returning all
+ * four metrics together so callers compute the document ranking once and read
+ * every score off the result.
+ */
+export declare function evaluateRanking(rankedIds: string[], relevantIds: ReadonlySet<string>, k: number): QueryEvalMetrics;
+/** Macro-averaged metrics across all evaluated queries. */
+export interface AggregateEvalMetrics {
+    ndcg: number;
+    mrr: number;
+    precision: number;
+    recall: number;
+    query_count: number;
+}
+/**
+ * Macro-average per-query metrics (each query weighted equally). Returns all
+ * zeros with `query_count: 0` for an empty input so the gate path has a stable
+ * shape to compare against.
+ */
+export declare function aggregateEvalMetrics(perQuery: QueryEvalMetrics[]): AggregateEvalMetrics;
+/**
+ * Parse and validate a raw golden-query payload (typically `JSON.parse` of
+ * `.agents/pm/search/eval-queries.json`). Accepts either a bare array of query
+ * entries or an object with a `queries` array. Throws {@link EvalQuerySetError}
+ * with a precise message when the payload is not an array/object, when
+ * `queries` is missing/not an array, when the set is empty, or when any entry
+ * fails {@link parseEvalQueryEntry}.
+ */
+export declare function parseEvalQuerySet(raw: unknown): EvalQuerySet;