@unbrained/pm-cli 2026.6.19 → 2026.6.20

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;

package/dist/core/search/eval.js

@@ -0,0 +1,217 @@
+/**
+ * @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).
+ */
+/** Default cutoff (`@k`) used for every metric when the caller does not override it. */
+
+!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]="4ed89138-1775-503e-a08f-7e94a0bd24eb")}catch(e){}}();
+export const DEFAULT_EVAL_K = 10;
+/**
+ * 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 class EvalQuerySetError extends Error {
+    /** Construct an error describing why a golden-query set failed validation. */
+    constructor(message) {
+        super(message);
+        this.name = "EvalQuerySetError";
+    }
+}
+const VALID_EVAL_MODES = new Set(["keyword", "semantic", "hybrid"]);
+/**
+ * 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 function dcgAtK(relevanceGains, k) {
+    let dcg = 0;
+    const limit = Math.min(k, relevanceGains.length);
+    for (let index = 0; index < limit; index += 1) {
+        dcg += relevanceGains[index] / Math.log2(index + 2);
+    }
+    return dcg;
+}
+/**
+ * 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 function ndcgAtK(rankedIds, relevantIds, k) {
+    if (relevantIds.size === 0) {
+        return 0;
+    }
+    const gains = rankedIds.map((id) => (relevantIds.has(id) ? 1 : 0));
+    const dcg = dcgAtK(gains, k);
+    const idealGains = Array.from({ length: relevantIds.size }, () => 1);
+    const idealDcg = dcgAtK(idealGains, k);
+    return idealDcg === 0 ? 0 : dcg / idealDcg;
+}
+/**
+ * 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 function reciprocalRankAtK(rankedIds, relevantIds, k) {
+    const limit = Math.min(k, rankedIds.length);
+    for (let index = 0; index < limit; index += 1) {
+        if (relevantIds.has(rankedIds[index])) {
+            return 1 / (index + 1);
+        }
+    }
+    return 0;
+}
+/**
+ * Count relevant ids within the top `k` results (shared by precision and
+ * recall).
+ */
+function countRelevantInTopK(rankedIds, relevantIds, k) {
+    const limit = Math.min(k, rankedIds.length);
+    let hits = 0;
+    for (let index = 0; index < limit; index += 1) {
+        if (relevantIds.has(rankedIds[index])) {
+            hits += 1;
+        }
+    }
+    return hits;
+}
+/**
+ * Precision at cutoff `k`: relevant ids retrieved in the top `k` divided by `k`.
+ * Returns `0` for a non-positive `k`.
+ */
+export function precisionAtK(rankedIds, relevantIds, k) {
+    if (k <= 0) {
+        return 0;
+    }
+    return countRelevantInTopK(rankedIds, relevantIds, k) / k;
+}
+/**
+ * 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 function recallAtK(rankedIds, relevantIds, k) {
+    if (relevantIds.size === 0) {
+        return 0;
+    }
+    return countRelevantInTopK(rankedIds, relevantIds, k) / relevantIds.size;
+}
+/**
+ * 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 function evaluateRanking(rankedIds, relevantIds, k) {
+    return {
+        ndcg: ndcgAtK(rankedIds, relevantIds, k),
+        mrr: reciprocalRankAtK(rankedIds, relevantIds, k),
+        precision: precisionAtK(rankedIds, relevantIds, k),
+        recall: recallAtK(rankedIds, relevantIds, k),
+        relevant_total: relevantIds.size,
+        retrieved_relevant: countRelevantInTopK(rankedIds, relevantIds, k),
+    };
+}
+/**
+ * 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 function aggregateEvalMetrics(perQuery) {
+    const queryCount = perQuery.length;
+    if (queryCount === 0) {
+        return { ndcg: 0, mrr: 0, precision: 0, recall: 0, query_count: 0 };
+    }
+    const sum = perQuery.reduce((accumulator, metrics) => ({
+        ndcg: accumulator.ndcg + metrics.ndcg,
+        mrr: accumulator.mrr + metrics.mrr,
+        precision: accumulator.precision + metrics.precision,
+        recall: accumulator.recall + metrics.recall,
+    }), { ndcg: 0, mrr: 0, precision: 0, recall: 0 });
+    return {
+        ndcg: sum.ndcg / queryCount,
+        mrr: sum.mrr / queryCount,
+        precision: sum.precision / queryCount,
+        recall: sum.recall / queryCount,
+        query_count: queryCount,
+    };
+}
+/**
+ * Validate one raw golden-query entry, returning a typed {@link EvalQuery}.
+ * Throws {@link EvalQuerySetError} (with the entry index) for a missing/empty
+ * `query`, a `relevant_ids` that is not a non-empty string array, or an invalid
+ * `mode`. `relevant_ids` are trimmed and de-duplicated; `description` is kept
+ * only when it is a non-empty string.
+ */
+function parseEvalQueryEntry(raw, index) {
+    if (typeof raw !== "object" || raw === null) {
+        throw new EvalQuerySetError(`Eval query at index ${index} must be an object`);
+    }
+    const entry = raw;
+    const query = typeof entry.query === "string" ? entry.query.trim() : "";
+    if (query.length === 0) {
+        throw new EvalQuerySetError(`Eval query at index ${index} must have a non-empty "query" string`);
+    }
+    if (!Array.isArray(entry.relevant_ids)) {
+        throw new EvalQuerySetError(`Eval query at index ${index} must have a "relevant_ids" array`);
+    }
+    if (entry.relevant_ids.some((value) => typeof value !== "string")) {
+        // Reject (rather than silently drop) non-string members: malformed golden
+        // data must fail loudly so it can never quietly change relevance judgments.
+        throw new EvalQuerySetError(`Eval query at index ${index} must have a "relevant_ids" array of strings`);
+    }
+    const relevantIds = [
+        ...new Set(entry.relevant_ids.map((value) => value.trim()).filter((value) => value.length > 0)),
+    ];
+    if (relevantIds.length === 0) {
+        throw new EvalQuerySetError(`Eval query at index ${index} must list at least one relevant id`);
+    }
+    if (entry.mode !== undefined && (typeof entry.mode !== "string" || !VALID_EVAL_MODES.has(entry.mode))) {
+        throw new EvalQuerySetError(`Eval query at index ${index} has an invalid mode (expected keyword|semantic|hybrid)`);
+    }
+    return {
+        query,
+        relevant_ids: relevantIds,
+        ...(entry.mode !== undefined ? { mode: entry.mode } : {}),
+        ...(typeof entry.description === "string" && entry.description.trim().length > 0
+            ? { description: entry.description.trim() }
+            : {}),
+    };
+}
+/**
+ * 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 function parseEvalQuerySet(raw) {
+    const rawQueries = Array.isArray(raw)
+        ? raw
+        : typeof raw === "object" && raw !== null
+            ? raw.queries
+            : undefined;
+    if (!Array.isArray(rawQueries)) {
+        throw new EvalQuerySetError('Eval query set must be an array of queries or an object with a "queries" array');
+    }
+    if (rawQueries.length === 0) {
+        throw new EvalQuerySetError("Eval query set must contain at least one query");
+    }
+    return {
+        queries: rawQueries.map((entry, index) => parseEvalQueryEntry(entry, index)),
+    };
+}
+//# sourceMappingURL=eval.js.map
+//# debugId=4ed89138-1775-503e-a08f-7e94a0bd24eb

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

@@ -0,0 +1 @@
+{"version":3,"file":"eval.js","sources":["core/search/eval.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/search/eval\n *\n * Search relevance evaluation primitives (pm-u8n5). Implements the standard\n * offline ranking metrics — nDCG@k, MRR@k, precision@k, recall@k — over a\n * human-curated golden-query set, plus the loader/validator for that set. The\n * `pm eval` command (src/cli/commands/eval.ts) runs each golden query through\n * the live retrieval path and feeds the ranked ids here, so relevance\n * regressions from corpus changes, hybrid-weight changes, or provider swaps are\n * measurable and gateable in CI.\n *\n * Relevance is binary: an id is either in a query's `relevant_ids` set or it is\n * not. This keeps the golden set cheap to curate while still supporting the\n * graded-discount behavior of DCG (earlier hits are worth more).\n */\n\n/**\n * Retrieval mode a golden query is evaluated under. Mirrors the `pm search`\n * mode surface; omitting it on a query defers to the eval run's default mode.\n */\nexport type EvalSearchMode = \"keyword\" | \"semantic\" | \"hybrid\";\n\n/** Default cutoff (`@k`) used for every metric when the caller does not override it. */\nexport const DEFAULT_EVAL_K = 10;\n\n/**\n * One curated golden query: the query text, the set of item ids considered\n * relevant, an optional per-query retrieval mode override, and an optional\n * human-readable description of the relevance intent.\n */\nexport interface EvalQuery {\n  query: string;\n  relevant_ids: string[];\n  mode?: EvalSearchMode;\n  description?: string;\n}\n\n/** A parsed, validated golden-query set. */\nexport interface EvalQuerySet {\n  queries: EvalQuery[];\n}\n\n/**\n * Thrown by {@link parseEvalQuerySet} when the raw golden-query payload is\n * structurally invalid. Carries a precise, human-actionable message naming the\n * offending query index/field so an author can fix the JSON directly.\n */\nexport class EvalQuerySetError extends Error {\n  /** Construct an error describing why a golden-query set failed validation. */\n  constructor(message: string) {\n    super(message);\n    this.name = \"EvalQuerySetError\";\n  }\n}\n\nconst VALID_EVAL_MODES: ReadonlySet<string> = new Set<EvalSearchMode>([\"keyword\", \"semantic\", \"hybrid\"]);\n\n/**\n * Compute Discounted Cumulative Gain at cutoff `k` for an ordered list of binary\n * relevance gains (`1` relevant, `0` not). Position `i` (1-based) contributes\n * `gain / log2(i + 1)`, so a relevant hit ranked first is worth `1` and later\n * hits are progressively discounted. Gains beyond `k` are ignored.\n */\nexport function dcgAtK(relevanceGains: number[], k: number): number {\n  let dcg = 0;\n  const limit = Math.min(k, relevanceGains.length);\n  for (let index = 0; index < limit; index += 1) {\n    dcg += relevanceGains[index] / Math.log2(index + 2);\n  }\n  return dcg;\n}\n\n/**\n * Normalized DCG at cutoff `k`: the ranking's DCG divided by the DCG of the\n * ideal ranking (all relevant ids first). Returns `0` when the query has no\n * relevant ids (the ideal DCG is `0` and the score is undefined), giving a\n * stable lower bound for aggregation. Result is in `[0, 1]`.\n */\nexport function ndcgAtK(rankedIds: string[], relevantIds: ReadonlySet<string>, k: number): number {\n  if (relevantIds.size === 0) {\n    return 0;\n  }\n  const gains = rankedIds.map((id) => (relevantIds.has(id) ? 1 : 0));\n  const dcg = dcgAtK(gains, k);\n  const idealGains = Array.from({ length: relevantIds.size }, () => 1);\n  const idealDcg = dcgAtK(idealGains, k);\n  return idealDcg === 0 ? 0 : dcg / idealDcg;\n}\n\n/**\n * Reciprocal rank of the first relevant id within the top `k` results: `1/rank`\n * (rank is 1-based), or `0` when no relevant id appears in the cutoff. Averaged\n * across queries this is Mean Reciprocal Rank (MRR@k).\n */\nexport function reciprocalRankAtK(rankedIds: string[], relevantIds: ReadonlySet<string>, k: number): number {\n  const limit = Math.min(k, rankedIds.length);\n  for (let index = 0; index < limit; index += 1) {\n    if (relevantIds.has(rankedIds[index])) {\n      return 1 / (index + 1);\n    }\n  }\n  return 0;\n}\n\n/**\n * Count relevant ids within the top `k` results (shared by precision and\n * recall).\n */\nfunction countRelevantInTopK(rankedIds: string[], relevantIds: ReadonlySet<string>, k: number): number {\n  const limit = Math.min(k, rankedIds.length);\n  let hits = 0;\n  for (let index = 0; index < limit; index += 1) {\n    if (relevantIds.has(rankedIds[index])) {\n      hits += 1;\n    }\n  }\n  return hits;\n}\n\n/**\n * Precision at cutoff `k`: relevant ids retrieved in the top `k` divided by `k`.\n * Returns `0` for a non-positive `k`.\n */\nexport function precisionAtK(rankedIds: string[], relevantIds: ReadonlySet<string>, k: number): number {\n  if (k <= 0) {\n    return 0;\n  }\n  return countRelevantInTopK(rankedIds, relevantIds, k) / k;\n}\n\n/**\n * Recall at cutoff `k`: relevant ids retrieved in the top `k` divided by the\n * total number of relevant ids. Returns `0` when the query has no relevant ids.\n */\nexport function recallAtK(rankedIds: string[], relevantIds: ReadonlySet<string>, k: number): number {\n  if (relevantIds.size === 0) {\n    return 0;\n  }\n  return countRelevantInTopK(rankedIds, relevantIds, k) / relevantIds.size;\n}\n\n/** The four ranking metrics computed for a single query, plus match counts. */\nexport interface QueryEvalMetrics {\n  ndcg: number;\n  mrr: number;\n  precision: number;\n  recall: number;\n  relevant_total: number;\n  retrieved_relevant: number;\n}\n\n/**\n * Evaluate one ranking against its relevant-id set at cutoff `k`, returning all\n * four metrics together so callers compute the document ranking once and read\n * every score off the result.\n */\nexport function evaluateRanking(rankedIds: string[], relevantIds: ReadonlySet<string>, k: number): QueryEvalMetrics {\n  return {\n    ndcg: ndcgAtK(rankedIds, relevantIds, k),\n    mrr: reciprocalRankAtK(rankedIds, relevantIds, k),\n    precision: precisionAtK(rankedIds, relevantIds, k),\n    recall: recallAtK(rankedIds, relevantIds, k),\n    relevant_total: relevantIds.size,\n    retrieved_relevant: countRelevantInTopK(rankedIds, relevantIds, k),\n  };\n}\n\n/** Macro-averaged metrics across all evaluated queries. */\nexport interface AggregateEvalMetrics {\n  ndcg: number;\n  mrr: number;\n  precision: number;\n  recall: number;\n  query_count: number;\n}\n\n/**\n * Macro-average per-query metrics (each query weighted equally). Returns all\n * zeros with `query_count: 0` for an empty input so the gate path has a stable\n * shape to compare against.\n */\nexport function aggregateEvalMetrics(perQuery: QueryEvalMetrics[]): AggregateEvalMetrics {\n  const queryCount = perQuery.length;\n  if (queryCount === 0) {\n    return { ndcg: 0, mrr: 0, precision: 0, recall: 0, query_count: 0 };\n  }\n  const sum = perQuery.reduce(\n    (accumulator, metrics) => ({\n      ndcg: accumulator.ndcg + metrics.ndcg,\n      mrr: accumulator.mrr + metrics.mrr,\n      precision: accumulator.precision + metrics.precision,\n      recall: accumulator.recall + metrics.recall,\n    }),\n    { ndcg: 0, mrr: 0, precision: 0, recall: 0 },\n  );\n  return {\n    ndcg: sum.ndcg / queryCount,\n    mrr: sum.mrr / queryCount,\n    precision: sum.precision / queryCount,\n    recall: sum.recall / queryCount,\n    query_count: queryCount,\n  };\n}\n\n/**\n * Validate one raw golden-query entry, returning a typed {@link EvalQuery}.\n * Throws {@link EvalQuerySetError} (with the entry index) for a missing/empty\n * `query`, a `relevant_ids` that is not a non-empty string array, or an invalid\n * `mode`. `relevant_ids` are trimmed and de-duplicated; `description` is kept\n * only when it is a non-empty string.\n */\nfunction parseEvalQueryEntry(raw: unknown, index: number): EvalQuery {\n  if (typeof raw !== \"object\" || raw === null) {\n    throw new EvalQuerySetError(`Eval query at index ${index} must be an object`);\n  }\n  const entry = raw as { query?: unknown; relevant_ids?: unknown; mode?: unknown; description?: unknown };\n  const query = typeof entry.query === \"string\" ? entry.query.trim() : \"\";\n  if (query.length === 0) {\n    throw new EvalQuerySetError(`Eval query at index ${index} must have a non-empty \"query\" string`);\n  }\n  if (!Array.isArray(entry.relevant_ids)) {\n    throw new EvalQuerySetError(`Eval query at index ${index} must have a \"relevant_ids\" array`);\n  }\n  if (entry.relevant_ids.some((value) => typeof value !== \"string\")) {\n    // Reject (rather than silently drop) non-string members: malformed golden\n    // data must fail loudly so it can never quietly change relevance judgments.\n    throw new EvalQuerySetError(`Eval query at index ${index} must have a \"relevant_ids\" array of strings`);\n  }\n  const relevantIds = [\n    ...new Set((entry.relevant_ids as string[]).map((value) => value.trim()).filter((value) => value.length > 0)),\n  ];\n  if (relevantIds.length === 0) {\n    throw new EvalQuerySetError(`Eval query at index ${index} must list at least one relevant id`);\n  }\n  if (entry.mode !== undefined && (typeof entry.mode !== \"string\" || !VALID_EVAL_MODES.has(entry.mode))) {\n    throw new EvalQuerySetError(`Eval query at index ${index} has an invalid mode (expected keyword|semantic|hybrid)`);\n  }\n  return {\n    query,\n    relevant_ids: relevantIds,\n    ...(entry.mode !== undefined ? { mode: entry.mode as EvalSearchMode } : {}),\n    ...(typeof entry.description === \"string\" && entry.description.trim().length > 0\n      ? { description: entry.description.trim() }\n      : {}),\n  };\n}\n\n/**\n * Parse and validate a raw golden-query payload (typically `JSON.parse` of\n * `.agents/pm/search/eval-queries.json`). Accepts either a bare array of query\n * entries or an object with a `queries` array. Throws {@link EvalQuerySetError}\n * with a precise message when the payload is not an array/object, when\n * `queries` is missing/not an array, when the set is empty, or when any entry\n * fails {@link parseEvalQueryEntry}.\n */\nexport function parseEvalQuerySet(raw: unknown): EvalQuerySet {\n  const rawQueries = Array.isArray(raw)\n    ? raw\n    : typeof raw === \"object\" && raw !== null\n      ? (raw as { queries?: unknown }).queries\n      : undefined;\n  if (!Array.isArray(rawQueries)) {\n    throw new EvalQuerySetError('Eval query set must be an array of queries or an object with a \"queries\" array');\n  }\n  if (rawQueries.length === 0) {\n    throw new EvalQuerySetError(\"Eval query set must contain at least one query\");\n  }\n  return {\n    queries: rawQueries.map((entry, index) => parseEvalQueryEntry(entry, index)),\n  };\n}\n"],"names":[],"mappings":"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","debugId":"4ed89138-1775-503e-a08f-7e94a0bd24eb"}

package/dist/core/sentry/instrument.d.ts

@@ -29,6 +29,17 @@ declare function isKnownNoisyConsoleBreadcrumb(breadcrumb: {
     category?: string;
     message?: string;
 }): boolean;
+/**
+ * Resolves the Sentry performance-tracing sample rate, honouring the standard
+ * `SENTRY_TRACES_SAMPLE_RATE` env var when it parses to a fraction in `[0, 1]`.
+ *
+ * The default (20%) keeps span volume modest for a low-frequency developer CLI
+ * while leaving an operational lever for full-trace performance debugging
+ * (`SENTRY_TRACES_SAMPLE_RATE=1`) or fully disabling traces (`=0`). Unset,
+ * non-numeric, or out-of-range values fall back to the default with no
+ * behaviour change for existing installs.
+ */
+declare function resolveTracesSampleRate(): number;
 /**
  * Implements ensure sentry init for the public runtime surface of this module.
  */
@@ -44,6 +55,9 @@ export declare const _testOnly: {
     isKnownNoisyConsoleBreadcrumb: typeof isKnownNoisyConsoleBreadcrumb;
     scrubString: typeof scrubString;
     scrubEventData: typeof scrubEventData;
+    resolveTracesSampleRate: typeof resolveTracesSampleRate;
+    KNOWN_NOISY_CONSOLE_MESSAGE_PATTERNS: readonly ["[starter-extension] activating", "[starter-extension] all 8 capabilities registered.", "[starter-extension] commands:", "[starter] preflight check for workspace", "[starter] output_format service override active", "[pm-ext-ts-starter] activating", "[pm-ext-ts-starter] all capabilities registered.", "run `pm init` first to initialise a pm workspace"];
+    MAX_KNOWN_NOISY_CONSOLE_MESSAGE_PATTERNS: number;
     resetSentryStateForTests(): void;
 };
 export {};