@unbrained/pm-cli 2026.7.5 → 2026.7.6

package/dist/cli-bundle/chunks/chunk-425E4QL5.js

@@ -0,0 +1,278 @@
+import {
+  runSearch
+} from "./chunk-3KTN6IBA.js";
+import {
+  PmCliError
+} from "./chunk-SHQY2IDC.js";
+import {
+  EXIT_CODE,
+  coercePositiveInteger,
+  getSettingsPath,
+  pathExists,
+  resolvePmRoot
+} from "./chunk-LK6XLOGP.js";
+
+// dist/cli/commands/eval.js
+import fs from "node:fs/promises";
+import path from "node:path";
+
+// dist/core/search/eval.js
+!(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 (e2) {
+  }
+})();
+var DEFAULT_EVAL_K = 10;
+var EvalQuerySetError = class extends Error {
+  /** Construct an error describing why a golden-query set failed validation. */
+  constructor(message) {
+    super(message);
+    this.name = "EvalQuerySetError";
+  }
+};
+var VALID_EVAL_MODES = /* @__PURE__ */ new Set(["keyword", "semantic", "hybrid"]);
+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;
+}
+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;
+}
+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;
+}
+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;
+}
+function precisionAtK(rankedIds, relevantIds, k) {
+  if (k <= 0) {
+    return 0;
+  }
+  return countRelevantInTopK(rankedIds, relevantIds, k) / k;
+}
+function recallAtK(rankedIds, relevantIds, k) {
+  if (relevantIds.size === 0) {
+    return 0;
+  }
+  return countRelevantInTopK(rankedIds, relevantIds, k) / relevantIds.size;
+}
+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)
+  };
+}
+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
+  };
+}
+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")) {
+    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 !== void 0 && (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 !== void 0 ? { mode: entry.mode } : {},
+    ...typeof entry.description === "string" && entry.description.trim().length > 0 ? { description: entry.description.trim() } : {}
+  };
+}
+function parseEvalQuerySet(raw) {
+  const rawQueries = Array.isArray(raw) ? raw : typeof raw === "object" && raw !== null ? raw.queries : void 0;
+  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))
+  };
+}
+
+// dist/cli/commands/eval.js
+!(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] = "fa1fece2-ddfb-537d-af39-fcd4ab8b5972");
+  } catch (e2) {
+  }
+})();
+var DEFAULT_EVAL_QUERIES_RELATIVE_PATH = path.join("search", "eval-queries.json");
+var VALID_EVAL_MODES2 = /* @__PURE__ */ new Set(["keyword", "semantic", "hybrid"]);
+function parseEvalMode(raw) {
+  if (raw === void 0) {
+    return "keyword";
+  }
+  const normalized = raw.trim().toLowerCase();
+  if (!VALID_EVAL_MODES2.has(normalized)) {
+    throw new PmCliError("Eval --mode must be one of keyword|semantic|hybrid", EXIT_CODE.USAGE);
+  }
+  return normalized;
+}
+function parseEvalK(raw) {
+  if (raw === void 0 || raw === "") {
+    return DEFAULT_EVAL_K;
+  }
+  const parsed = coercePositiveInteger(raw);
+  if (parsed === null) {
+    throw new PmCliError("Eval --k must be a positive integer", EXIT_CODE.USAGE);
+  }
+  return parsed;
+}
+function parseFailUnder(raw) {
+  if (raw === void 0 || raw === "") {
+    return void 0;
+  }
+  const parsed = typeof raw === "number" ? raw : Number(String(raw).trim());
+  if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+    throw new PmCliError("Eval --fail-under must be a number in the range [0, 1]", EXIT_CODE.USAGE);
+  }
+  return parsed;
+}
+function roundMetric(value) {
+  return Math.round(value * 1e4) / 1e4;
+}
+async function loadEvalQuerySet(queriesPath) {
+  let raw;
+  try {
+    raw = await fs.readFile(queriesPath, "utf8");
+  } catch {
+    throw new PmCliError(`Eval query set not found at ${queriesPath}`, EXIT_CODE.NOT_FOUND, {
+      examples: [
+        `echo '[{"query":"offline search","relevant_ids":["pm-75k9"]}]' > ` + queriesPath,
+        "pm eval --queries ./my-eval.json"
+      ],
+      nextSteps: [
+        "Create a git-tracked golden-query JSON file (an array of {query, relevant_ids, mode?} objects), then re-run pm eval."
+      ]
+    });
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new PmCliError(`Eval query set at ${queriesPath} is not valid JSON: ${error.message}`, EXIT_CODE.USAGE);
+  }
+  try {
+    return parseEvalQuerySet(parsed);
+  } catch (error) {
+    throw new PmCliError(error.message, EXIT_CODE.USAGE);
+  }
+}
+async function runEval(options, global2) {
+  const pmRoot = resolvePmRoot(process.cwd(), global2.path);
+  if (!await pathExists(getSettingsPath(pmRoot))) {
+    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
+  }
+  const k = parseEvalK(options.k);
+  const defaultMode = parseEvalMode(options.mode);
+  const failUnder = parseFailUnder(options.failUnder);
+  const queriesPath = options.queries ? path.resolve(process.cwd(), options.queries) : path.join(pmRoot, DEFAULT_EVAL_QUERIES_RELATIVE_PATH);
+  const querySet = await loadEvalQuerySet(queriesPath);
+  const reports = [];
+  const rawMetrics = [];
+  for (const evalQuery of querySet.queries) {
+    const mode = evalQuery.mode ?? defaultMode;
+    const searchResult = await runSearch(evalQuery.query, { mode, limit: String(k), fields: "id" }, global2);
+    const rankedIds = searchResult.items.map((item) => item.id).filter((id) => typeof id === "string");
+    const metrics = evaluateRanking(rankedIds, new Set(evalQuery.relevant_ids), k);
+    rawMetrics.push(metrics);
+    reports.push({
+      query: evalQuery.query,
+      mode,
+      relevant_total: metrics.relevant_total,
+      retrieved_relevant: metrics.retrieved_relevant,
+      ndcg: roundMetric(metrics.ndcg),
+      mrr: roundMetric(metrics.mrr),
+      precision: roundMetric(metrics.precision),
+      recall: roundMetric(metrics.recall)
+    });
+  }
+  const aggregate = aggregateEvalMetrics(rawMetrics);
+  const passed = failUnder === void 0 || aggregate.ndcg >= failUnder;
+  return {
+    k,
+    query_count: querySet.queries.length,
+    aggregate: {
+      ndcg: roundMetric(aggregate.ndcg),
+      mrr: roundMetric(aggregate.mrr),
+      precision: roundMetric(aggregate.precision),
+      recall: roundMetric(aggregate.recall)
+    },
+    queries: reports,
+    ...failUnder !== void 0 ? { fail_under: failUnder } : {},
+    passed
+  };
+}
+
+export {
+  DEFAULT_EVAL_QUERIES_RELATIVE_PATH,
+  runEval
+};
+//# sourceMappingURL=chunk-425E4QL5.js.map

package/dist/cli-bundle/chunks/chunk-425E4QL5.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../../cli/commands/eval.ts", "../../../../../../../../core/search/eval.ts"],
+  "sourcesContent": ["/**\n * @module cli/commands/eval\n *\n * Implements the `pm eval` command surface (pm-u8n5): a search-relevance\n * evaluation runner that scores a human-curated golden-query set against the\n * live retrieval path and reports nDCG@k, MRR@k, precision@k, and recall@k per\n * query plus the macro average. With `--fail-under` it doubles as a CI gate so\n * relevance regressions — from corpus changes, hybrid-weight changes, or\n * provider swaps (including the offline BM25 provider, pm-75k9) — fail the build\n * instead of silently degrading retrieval quality.\n */\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport {\n  aggregateEvalMetrics,\n  DEFAULT_EVAL_K,\n  evaluateRanking,\n  parseEvalQuerySet,\n  type EvalSearchMode,\n  type QueryEvalMetrics,\n} from \"../../core/search/eval.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { coercePositiveInteger } from \"../../core/shared/primitives.js\";\nimport { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { runSearch } from \"./search.js\";\n\n/**\n * Relative location (under the pm root) of the default golden-query set. A\n * git-tracked, human-curated file so relevance ground truth lives alongside the\n * tracker it evaluates.\n */\nexport const DEFAULT_EVAL_QUERIES_RELATIVE_PATH = path.join(\"search\", \"eval-queries.json\");\n\n/**\n * Documents the eval command options payload exchanged by command, SDK, and package integrations.\n */\nexport interface EvalOptions {\n  /** Default retrieval mode for queries that do not set their own (keyword|semantic|hybrid). */\n  mode?: string;\n  /** Metric cutoff (`@k`); positive integer, defaults to {@link DEFAULT_EVAL_K}. */\n  k?: string | number;\n  /** Gate threshold: exit non-zero when the aggregate nDCG@k falls below this `[0,1]` value. */\n  failUnder?: string | number;\n  /** Override path to the golden-query JSON file (defaults to `<pmRoot>/search/eval-queries.json`). */\n  queries?: string;\n  /** Output format override: json|toon. */\n  format?: string;\n}\n\n/** Per-query relevance report row emitted by {@link runEval}. */\nexport interface EvalQueryReport {\n  query: string;\n  mode: EvalSearchMode;\n  relevant_total: number;\n  retrieved_relevant: number;\n  ndcg: number;\n  mrr: number;\n  precision: number;\n  recall: number;\n}\n\n/**\n * Documents the eval result payload exchanged by command, SDK, and package integrations.\n */\nexport interface EvalResult {\n  k: number;\n  query_count: number;\n  aggregate: {\n    ndcg: number;\n    mrr: number;\n    precision: number;\n    recall: number;\n  };\n  queries: EvalQueryReport[];\n  /** Present only when `--fail-under` was supplied. */\n  fail_under?: number;\n  /** Whether the aggregate nDCG met the gate (always true when no gate is set). */\n  passed: boolean;\n}\n\nconst VALID_EVAL_MODES: ReadonlySet<string> = new Set<EvalSearchMode>([\"keyword\", \"semantic\", \"hybrid\"]);\n\nfunction parseEvalMode(raw: string | undefined): EvalSearchMode {\n  if (raw === undefined) {\n    return \"keyword\";\n  }\n  const normalized = raw.trim().toLowerCase();\n  if (!VALID_EVAL_MODES.has(normalized)) {\n    throw new PmCliError(\"Eval --mode must be one of keyword|semantic|hybrid\", EXIT_CODE.USAGE);\n  }\n  return normalized as EvalSearchMode;\n}\n\nfunction parseEvalK(raw: string | number | undefined): number {\n  if (raw === undefined || raw === \"\") {\n    return DEFAULT_EVAL_K;\n  }\n  const parsed = coercePositiveInteger(raw);\n  if (parsed === null) {\n    throw new PmCliError(\"Eval --k must be a positive integer\", EXIT_CODE.USAGE);\n  }\n  return parsed;\n}\n\nfunction parseFailUnder(raw: string | number | undefined): number | undefined {\n  if (raw === undefined || raw === \"\") {\n    return undefined;\n  }\n  const parsed = typeof raw === \"number\" ? raw : Number(String(raw).trim());\n  if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {\n    throw new PmCliError(\"Eval --fail-under must be a number in the range [0, 1]\", EXIT_CODE.USAGE);\n  }\n  return parsed;\n}\n\n/** Round a metric to four decimals to keep the JSON output compact and stable. */\nfunction roundMetric(value: number): number {\n  return Math.round(value * 10_000) / 10_000;\n}\n\nasync function loadEvalQuerySet(queriesPath: string): Promise<ReturnType<typeof parseEvalQuerySet>> {\n  let raw: string;\n  try {\n    raw = await fs.readFile(queriesPath, \"utf8\");\n  } catch {\n    throw new PmCliError(`Eval query set not found at ${queriesPath}`, EXIT_CODE.NOT_FOUND, {\n      examples: [\n        'echo \\'[{\"query\":\"offline search\",\"relevant_ids\":[\"pm-75k9\"]}]\\' > ' + queriesPath,\n        \"pm eval --queries ./my-eval.json\",\n      ],\n      nextSteps: [\n        \"Create a git-tracked golden-query JSON file (an array of {query, relevant_ids, mode?} objects), then re-run pm eval.\",\n      ],\n    });\n  }\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw);\n  } catch (error: unknown) {\n    // JSON.parse only ever throws a SyntaxError (an Error subclass).\n    throw new PmCliError(\n      `Eval query set at ${queriesPath} is not valid JSON: ${(error as Error).message}`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  try {\n    return parseEvalQuerySet(parsed);\n  } catch (error: unknown) {\n    // parseEvalQuerySet only ever throws EvalQuerySetError (an Error subclass\n    // with a precise, author-actionable message) — surface it as a usage error.\n    throw new PmCliError((error as Error).message, EXIT_CODE.USAGE);\n  }\n}\n\n/**\n * Run the search-relevance evaluation (pm-u8n5). Loads the golden-query set\n * (default `<pmRoot>/search/eval-queries.json`, overridable via `--queries`),\n * runs each query through {@link runSearch} at the resolved mode, scores the\n * returned ranking with the nDCG/MRR/precision/recall metrics, and macro-averages\n * across queries. When `--fail-under` is supplied, `passed` reflects whether the\n * aggregate nDCG@k cleared the threshold; the CLI layer maps a failed gate to a\n * non-zero exit code.\n */\nexport async function runEval(options: EvalOptions, global: GlobalOptions): Promise<EvalResult> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);\n  }\n  const k = parseEvalK(options.k);\n  const defaultMode = parseEvalMode(options.mode);\n  const failUnder = parseFailUnder(options.failUnder);\n  const queriesPath = options.queries\n    ? path.resolve(process.cwd(), options.queries)\n    : path.join(pmRoot, DEFAULT_EVAL_QUERIES_RELATIVE_PATH);\n  const querySet = await loadEvalQuerySet(queriesPath);\n\n  const reports: EvalQueryReport[] = [];\n  // Aggregate and gate on the UNROUNDED metrics; rounding is applied only to the\n  // emitted report values so display precision never flips a --fail-under decision.\n  const rawMetrics: QueryEvalMetrics[] = [];\n  for (const evalQuery of querySet.queries) {\n    const mode = evalQuery.mode ?? defaultMode;\n    const searchResult = await runSearch(\n      evalQuery.query,\n      { mode, limit: String(k), fields: \"id\" },\n      global,\n    );\n    const rankedIds = searchResult.items\n      .map((item) => (item as { id?: unknown }).id)\n      .filter((id): id is string => typeof id === \"string\");\n    const metrics = evaluateRanking(rankedIds, new Set(evalQuery.relevant_ids), k);\n    rawMetrics.push(metrics);\n    reports.push({\n      query: evalQuery.query,\n      mode,\n      relevant_total: metrics.relevant_total,\n      retrieved_relevant: metrics.retrieved_relevant,\n      ndcg: roundMetric(metrics.ndcg),\n      mrr: roundMetric(metrics.mrr),\n      precision: roundMetric(metrics.precision),\n      recall: roundMetric(metrics.recall),\n    });\n  }\n\n  const aggregate = aggregateEvalMetrics(rawMetrics);\n  const passed = failUnder === undefined || aggregate.ndcg >= failUnder;\n  return {\n    k,\n    query_count: querySet.queries.length,\n    aggregate: {\n      ndcg: roundMetric(aggregate.ndcg),\n      mrr: roundMetric(aggregate.mrr),\n      precision: roundMetric(aggregate.precision),\n      recall: roundMetric(aggregate.recall),\n    },\n    queries: reports,\n    ...(failUnder !== undefined ? { fail_under: failUnder } : {}),\n    passed,\n  };\n}\n", "/**\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"],
+  "mappings": "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",
+  "names": ["VALID_EVAL_MODES", "global"]
+}

package/dist/cli-bundle/chunks/chunk-45FYNUFJ.js

@@ -0,0 +1,38 @@
+
+!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]="9c123f79-efa7-5fa3-84b5-aa8c5ab9e979")}catch(e){}}();
+import {
+  parseAnnotationTextInput,
+  runAnnotationCommand
+} from "./chunk-EKFNL33R.js";
+import {
+  createStdinTokenResolver
+} from "./chunk-IWVU4C2F.js";
+
+// dist/cli/commands/learnings.js
+async function runLearnings(id, options, global) {
+  const stdinResolver = createStdinTokenResolver();
+  const addInput = options.add === void 0 ? void 0 : await stdinResolver.resolveValue(options.add, "--add");
+  return runAnnotationCommand(id, options, global, {
+    // addInput is defined whenever options.add is defined (see resolveValue), so the cast is safe.
+    input: options.add === void 0 ? { mode: "list" } : { mode: "add", value: addInput, emptyFlag: "--add" },
+    collectionKey: "learnings",
+    op: "learning_add",
+    parseText: (raw) => parseAnnotationTextInput(raw),
+    allowAuditBypass: Boolean(options.allowAuditLearning || options.allowAuditComment),
+    conflictGuidance: {
+      required: "For append-only learning audits on another owner's item, prefer --allow-audit-learning (legacy alias: --allow-audit-comment) before considering --force.",
+      examples: ['pm learnings pm-a1b2 --add "audit learning" --author "reviewer" --allow-audit-learning'],
+      nextSteps: [
+        "Retry with --allow-audit-learning (or legacy --allow-audit-comment) for append-only learning audits that do not mutate item metadata beyond learnings.",
+        "Use --force only when an ownership override is explicitly approved."
+      ]
+    }
+  });
+}
+
+export {
+  runLearnings
+};
+//# sourceMappingURL=chunk-45FYNUFJ.js.map
+
+//# debugId=9c123f79-efa7-5fa3-84b5-aa8c5ab9e979

package/dist/cli-bundle/chunks/chunk-45FYNUFJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../cli/commands/learnings.ts"],"sourcesContent":["/**\n * @module cli/commands/learnings\n *\n * Implements the pm learnings command surface and its agent-facing runtime behavior.\n */\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { createStdinTokenResolver } from \"../../core/item/parse.js\";\nimport type { LogNote } from \"../../types/index.js\";\nimport { parseAnnotationTextInput, runAnnotationCommand } from \"./annotation-command.js\";\n\n/**\n * Documents the learnings command options payload exchanged by command, SDK, and package integrations.\n */\nexport interface LearningsCommandOptions {\n  add?: string;\n  limit?: string;\n  author?: string;\n  message?: string;\n  allowAuditLearning?: boolean;\n  allowAuditComment?: boolean;\n  force?: boolean;\n}\n\n/**\n * Documents the learnings result payload exchanged by command, SDK, and package integrations.\n */\nexport interface LearningsResult {\n  id: string;\n  learnings: LogNote[];\n  count: number;\n}\n\n/**\n * Implements run learnings for the public runtime surface of this module.\n */\nexport async function runLearnings(\n  id: string,\n  options: LearningsCommandOptions,\n  global: GlobalOptions,\n): Promise<LearningsResult> {\n  const stdinResolver = createStdinTokenResolver();\n  const addInput = options.add === undefined ? undefined : await stdinResolver.resolveValue(options.add, \"--add\");\n\n  return runAnnotationCommand<\"learnings\", LogNote>(id, options, global, {\n    // addInput is defined whenever options.add is defined (see resolveValue), so the cast is safe.\n    input: options.add === undefined ? { mode: \"list\" } : { mode: \"add\", value: addInput as string, emptyFlag: \"--add\" },\n    collectionKey: \"learnings\",\n    op: \"learning_add\",\n    parseText: (raw) => parseAnnotationTextInput(raw),\n    allowAuditBypass: Boolean(options.allowAuditLearning || options.allowAuditComment),\n    conflictGuidance: {\n      required:\n        \"For append-only learning audits on another owner's item, prefer --allow-audit-learning (legacy alias: --allow-audit-comment) before considering --force.\",\n      examples: ['pm learnings pm-a1b2 --add \"audit learning\" --author \"reviewer\" --allow-audit-learning'],\n      nextSteps: [\n        \"Retry with --allow-audit-learning (or legacy --allow-audit-comment) for append-only learning audits that do not mutate item metadata beyond learnings.\",\n        \"Use --force only when an ownership override is explicitly approved.\",\n      ],\n    },\n  });\n}\n"],"names":[],"mappings":";;;;;;;;;;;AAmCA,eAAsB,aACpB,IACA,SACA,QAAqB;AAErB,QAAM,gBAAgB,yBAAwB;AAC9C,QAAM,WAAW,QAAQ,QAAQ,SAAY,SAAY,MAAM,cAAc,aAAa,QAAQ,KAAK,OAAO;AAE9G,SAAO,qBAA2C,IAAI,SAAS,QAAQ;;IAErE,OAAO,QAAQ,QAAQ,SAAY,EAAE,MAAM,OAAM,IAAK,EAAE,MAAM,OAAO,OAAO,UAAoB,WAAW,QAAO;IAClH,eAAe;IACf,IAAI;IACJ,WAAW,CAAC,QAAQ,yBAAyB,GAAG;IAChD,kBAAkB,QAAQ,QAAQ,sBAAsB,QAAQ,iBAAiB;IACjF,kBAAkB;MAChB,UACE;MACF,UAAU,CAAC,wFAAwF;MACnG,WAAW;QACT;QACA;;;GAGL;AACH","debugId":"9c123f79-efa7-5fa3-84b5-aa8c5ab9e979"}