@unbrained/pm-cli 2026.6.24 → 2026.7.1

package/packages/pm-search-advanced/extensions/search-advanced/index.js

@@ -1,258 +0,0 @@
-import { runAdvancedReindexPackage, runAdvancedSearchPackage } from "./runtime.js";
-
-export const manifest = {
-  name: "builtin-search-advanced",
-  version: "0.1.0",
-  entry: "./index.js",
-  priority: 0,
-  capabilities: ["commands", "schema", "search"],
-};
-
-export const SEARCH_ADVANCED_LOCAL_PROVIDER = "search-advanced-local";
-
-const SEARCH_FIELD_WEIGHTS = { title: 3, tags: 2, description: 1 };
-
-function tokenizeSearchText(value) {
-  // Unicode-aware: keep letters/numbers from any script (é, ü, CJK, Cyrillic, ...)
-  // so the provider works for non-English/multilingual corpora.
-  return value.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
-}
-
-function scoreDocumentForQuery(queryTokens, document) {
-  const metadata = document?.metadata;
-  // A non-string id would crash hits.sort()'s localeCompare; treat as unscoreable.
-  if (!metadata || typeof metadata.id !== "string") {
-    return { score: 0, matched_fields: [] };
-  }
-  const fields = [
-    { field: "title", tokens: tokenizeSearchText(typeof metadata.title === "string" ? metadata.title : "") },
-    {
-      field: "tags",
-      tokens: Array.isArray(metadata.tags)
-        ? metadata.tags.flatMap((tag) => (tag == null ? [] : tokenizeSearchText(String(tag))))
-        : [],
-    },
-    {
-      field: "description",
-      tokens: tokenizeSearchText(typeof metadata.description === "string" ? metadata.description : ""),
-    },
-  ];
-  let score = 0;
-  const matched = [];
-  for (const { field, tokens } of fields) {
-    const available = new Set(tokens);
-    let fieldMatches = 0;
-    for (const queryToken of queryTokens) {
-      if (available.has(queryToken)) {
-        fieldMatches += 1;
-      }
-    }
-    if (fieldMatches > 0) {
-      score += fieldMatches * SEARCH_FIELD_WEIGHTS[field];
-      matched.push(field);
-    }
-  }
-  return { score, matched_fields: matched };
-}
-
-export function searchAdvancedLocalProvider() {
-  return {
-    name: SEARCH_ADVANCED_LOCAL_PROVIDER,
-    query(context) {
-      const queryTokens = tokenizeSearchText(context.query);
-      if (queryTokens.length === 0) {
-        return [];
-      }
-      const hits = [];
-      for (const document of context.documents) {
-        const { score, matched_fields } = scoreDocumentForQuery(queryTokens, document);
-        if (score > 0) {
-          hits.push({ id: document.metadata.id, score, matched_fields });
-        }
-      }
-      return hits.sort((left, right) => right.score - left.score || left.id.localeCompare(right.id));
-    },
-  };
-}
-
-const searchAdvancedFlags = [
-  {
-    long: "--mode",
-    value_name: "value",
-    value_type: "string",
-    description: "Search mode override: keyword|semantic|hybrid.",
-  },
-  {
-    long: "--semantic",
-    value_type: "boolean",
-    description: "Alias for --mode semantic.",
-  },
-  {
-    long: "--hybrid",
-    value_type: "boolean",
-    description: "Alias for --mode hybrid.",
-  },
-  {
-    long: "--include-linked",
-    value_type: "boolean",
-    description: "Include linked docs/files/tests corpus in lexical scoring.",
-  },
-  {
-    long: "--include_linked",
-    value_type: "boolean",
-    description: "Alias for --include-linked.",
-  },
-  {
-    long: "--title-exact",
-    value_type: "boolean",
-    description: "Require exact title phrase matching before scoring.",
-  },
-  {
-    long: "--title_exact",
-    value_type: "boolean",
-    description: "Alias for --title-exact.",
-  },
-  {
-    long: "--phrase-exact",
-    value_type: "boolean",
-    description: "Require exact phrase match across searchable document fields.",
-  },
-  {
-    long: "--phrase_exact",
-    value_type: "boolean",
-    description: "Alias for --phrase-exact.",
-  },
-  {
-    long: "--type",
-    value_name: "value",
-    value_type: "string",
-    description: "Filter by item type.",
-  },
-  {
-    long: "--tag",
-    value_name: "value",
-    value_type: "string",
-    description: "Filter by tag.",
-  },
-  {
-    long: "--priority",
-    value_name: "value",
-    value_type: "string",
-    description: "Filter by priority.",
-  },
-  {
-    long: "--deadline-before",
-    value_name: "date",
-    value_type: "string",
-    description: "Filter to items with deadlines before a date.",
-  },
-  {
-    long: "--deadline_before",
-    value_name: "date",
-    value_type: "string",
-    description: "Alias for --deadline-before.",
-  },
-  {
-    long: "--deadline-after",
-    value_name: "date",
-    value_type: "string",
-    description: "Filter to items with deadlines after a date.",
-  },
-  {
-    long: "--deadline_after",
-    value_name: "date",
-    value_type: "string",
-    description: "Alias for --deadline-after.",
-  },
-  {
-    long: "--limit",
-    value_name: "count",
-    value_type: "string",
-    description: "Limit the number of search results.",
-  },
-  {
-    long: "--fields",
-    value_name: "list",
-    value_type: "string",
-    description: "Return only selected result fields.",
-  },
-  {
-    long: "--compact",
-    value_type: "boolean",
-    description: "Return compact token-efficient search results.",
-  },
-  {
-    long: "--full",
-    value_type: "boolean",
-    description: "Return full search results.",
-  },
-];
-
-const reindexFlags = [
-  {
-    long: "--mode",
-    value_name: "value",
-    value_type: "string",
-    description: "Reindex mode: keyword|semantic|hybrid.",
-  },
-  {
-    long: "--full",
-    value_type: "boolean",
-    description:
-      "Force full semantic/hybrid embedding rebuild; by default semantic/hybrid reindex only embeds stale items.",
-  },
-  {
-    long: "--progress",
-    value_type: "boolean",
-    description: "Emit non-interactive progress lines to stderr.",
-  },
-  {
-    long: "--eval",
-    value_type: "boolean",
-    description: "Run golden-query relevance eval and append nDCG@5 summary output.",
-  },
-  {
-    long: "--eval-fixtures",
-    value_name: "path",
-    value_type: "string",
-    description: "Path to reindex eval fixtures JSON (default: tests/search-eval/golden-queries.json).",
-  },
-  {
-    long: "--eval_fixtures",
-    value_name: "path",
-    value_type: "string",
-    description: "Alias for --eval-fixtures.",
-  },
-];
-
-function searchAdvancedCommand() {
-  return {
-    name: "search-advanced",
-    action: "search-advanced",
-    description: "Enable optional semantic and hybrid search modes via package runtime.",
-    arguments: [{ name: "keywords", required: true, variadic: true, description: "Query tokens." }],
-    run: async (context) => runAdvancedSearchPackage(context.args, context.options, context.global),
-  };
-}
-
-function reindexCommand() {
-  return {
-    name: "reindex",
-    action: "reindex",
-    description: "Rebuild search artifacts for keyword, semantic, and hybrid modes.",
-    flags: [...reindexFlags],
-    run: async (context) => runAdvancedReindexPackage(context.options, context.global),
-  };
-}
-
-export function activate(api) {
-  api.registerFlags("search-advanced", [...searchAdvancedFlags]);
-  api.registerCommand(searchAdvancedCommand());
-  api.registerCommand(reindexCommand());
-  api.registerSearchProvider(searchAdvancedLocalProvider());
-}
-
-export default {
-  manifest,
-  activate,
-};

package/packages/pm-search-advanced/extensions/search-advanced/runtime.js

@@ -1,361 +0,0 @@
-import { readFile } from "node:fs/promises";
-import path from "node:path";
-import { pathToFileURL } from "node:url";
-
-const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
-const DEFAULT_EVAL_FIXTURES_PATH = path.join("tests", "search-eval", "golden-queries.json");
-const DEFAULT_EVAL_MIN_NDCG_AT_5 = 0.7;
-const EVAL_RANK_CUTOFF = 5;
-const VALID_EVAL_SEARCH_MODES = new Set(["keyword", "semantic", "hybrid"]);
-
-const sdk = await loadSearchSdkModule();
-const {
-  EXIT_CODE,
-  PmCliError,
-  runSearch,
-  runReindex,
-  readStringOption,
-  readBooleanOption,
-} = sdk;
-
-async function loadSearchSdkModule() {
-  const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
-  if (typeof envRoot !== "string" || envRoot.trim().length === 0) {
-    throw new Error(
-      `builtin-search-advanced requires ${PM_PACKAGE_ROOT_ENV} to locate core SDK runtime exports.`,
-    );
-  }
-  const modulePath = path.join(path.resolve(envRoot.trim()), "dist", "sdk", "runtime.js");
-  try {
-    const loaded = await import(pathToFileURL(modulePath).href);
-    if (
-      typeof loaded.runSearch === "function" &&
-      typeof loaded.runReindex === "function" &&
-      typeof loaded.PmCliError === "function" &&
-      typeof loaded.readStringOption === "function" &&
-      typeof loaded.readBooleanOption === "function" &&
-      typeof loaded.EXIT_CODE === "object" &&
-      loaded.EXIT_CODE !== null
-    ) {
-      return loaded;
-    }
-  } catch {
-    // Fall through to deterministic failure message below.
-  }
-  throw new Error(
-    `builtin-search-advanced failed to load SDK runtime exports from ${modulePath}.`,
-  );
-}
-
-const SEARCH_VALUE_FLAGS = new Set([
-  "--mode",
-  "--type",
-  "--tag",
-  "--priority",
-  "--deadline-before",
-  "--deadline_before",
-  "--deadline-after",
-  "--deadline_after",
-  "--limit",
-  "--fields",
-]);
-
-const SEARCH_BOOLEAN_FLAGS = new Set([
-  "--semantic",
-  "--hybrid",
-  "--include-linked",
-  "--include_linked",
-  "--title-exact",
-  "--title_exact",
-  "--phrase-exact",
-  "--phrase_exact",
-  "--compact",
-  "--full",
-  "--json",
-]);
-
-function stripSearchOptionTokens(args) {
-  const queryTokens = [];
-  for (let index = 0; index < args.length; index += 1) {
-    const token = args[index]?.trim() ?? "";
-    const equalsIndex = token.indexOf("=");
-    const flagName = equalsIndex > 0 ? token.slice(0, equalsIndex) : token;
-    if (SEARCH_VALUE_FLAGS.has(flagName)) {
-      if (equalsIndex < 0) {
-        index += 1;
-      }
-      continue;
-    }
-    if (SEARCH_BOOLEAN_FLAGS.has(flagName)) {
-      continue;
-    }
-    if (token.length > 0) {
-      queryTokens.push(token);
-    }
-  }
-  return queryTokens;
-}
-
-function resolveSearchQuery(args) {
-  const query = stripSearchOptionTokens(args).join(" ");
-  if (query.length === 0) {
-    throw new PmCliError("Search query must not be empty", EXIT_CODE.USAGE);
-  }
-  return query;
-}
-
-function normalizeAdvancedSearchOptions(rawOptions, args) {
-  const fields = readStringOption(rawOptions, "fields");
-  const compactRequested = readBooleanOption(rawOptions, "compact") === true;
-  const fullRequested = readBooleanOption(rawOptions, "full") === true;
-  const defaultCompact = !compactRequested && !fullRequested && fields === undefined;
-  const explicitMode = readStringOption(rawOptions, "mode");
-  const argFlags = new Set(args.map((value) => value?.trim() ?? ""));
-  const mode =
-    explicitMode ??
-    (readBooleanOption(rawOptions, "semantic") === true || argFlags.has("--semantic")
-      ? "semantic"
-      : readBooleanOption(rawOptions, "hybrid") === true || argFlags.has("--hybrid")
-        ? "hybrid"
-        : "keyword");
-  return {
-    mode,
-    includeLinked: readBooleanOption(rawOptions, "includeLinked", ["include_linked"]) === true ? true : undefined,
-    titleExact: readBooleanOption(rawOptions, "titleExact", ["title_exact"]) === true ? true : undefined,
-    phraseExact: readBooleanOption(rawOptions, "phraseExact", ["phrase_exact"]) === true ? true : undefined,
-    type: readStringOption(rawOptions, "type"),
-    tag: readStringOption(rawOptions, "tag"),
-    priority: readStringOption(rawOptions, "priority"),
-    deadlineBefore: readStringOption(rawOptions, "deadlineBefore", ["deadline_before"]),
-    deadlineAfter: readStringOption(rawOptions, "deadlineAfter", ["deadline_after"]),
-    limit: readStringOption(rawOptions, "limit"),
-    fields,
-    compact: compactRequested || defaultCompact ? true : undefined,
-    full: fullRequested ? true : undefined,
-  };
-}
-
-function normalizeReindexOptions(rawOptions) {
-  return {
-    mode: readStringOption(rawOptions, "mode"),
-    full: readBooleanOption(rawOptions, "full") === true ? true : undefined,
-    progress: readBooleanOption(rawOptions, "progress") === true ? true : undefined,
-  };
-}
-
-function normalizeEvalFixturePath(rawPath) {
-  const candidate = typeof rawPath === "string" ? rawPath : DEFAULT_EVAL_FIXTURES_PATH;
-  return path.resolve(process.cwd(), candidate);
-}
-
-function normalizeReindexRuntimeOptions(rawOptions) {
-  const reindex = normalizeReindexOptions(rawOptions);
-  const evalEnabled = readBooleanOption(rawOptions, "eval") === true;
-  const evalFixturePath = readStringOption(rawOptions, "evalFixtures", ["eval_fixtures"]);
-  if (!evalEnabled) {
-    if (typeof evalFixturePath === "string" && evalFixturePath.trim().length > 0) {
-      throw new PmCliError("`--eval-fixtures` requires `--eval`.", EXIT_CODE.USAGE);
-    }
-    return { reindex };
-  }
-  return {
-    reindex,
-    eval: {
-      fixturesPath: normalizeEvalFixturePath(evalFixturePath),
-    },
-  };
-}
-
-function toScoreAtRank(relevance, rankIndex) {
-  if (relevance <= 0) {
-    return 0;
-  }
-  return (2 ** relevance - 1) / Math.log2(rankIndex + 2);
-}
-
-function roundMetric(value) {
-  return Math.round(value * 10_000) / 10_000;
-}
-
-function toCompactExpectedIds(value, fixtureLabel, fixturesPath) {
-  if (!Array.isArray(value) || value.length === 0) {
-    throw new PmCliError(
-      `Reindex eval fixture ${fixtureLabel} in ${fixturesPath} must provide a non-empty expected_top_ids array.`,
-      EXIT_CODE.USAGE,
-    );
-  }
-  const expectedIds = value
-    .filter((entry) => typeof entry === "string")
-    .map((entry) => entry.trim())
-    .filter((entry) => entry.length > 0);
-  if (expectedIds.length === 0) {
-    throw new PmCliError(
-      `Reindex eval fixture ${fixtureLabel} in ${fixturesPath} must provide at least one non-empty expected_top_ids value.`,
-      EXIT_CODE.USAGE,
-    );
-  }
-  return [...new Set(expectedIds)];
-}
-
-function normalizeFixtureMode(rawMode, fixtureLabel, fixturesPath) {
-  if (rawMode === undefined) {
-    return "keyword";
-  }
-  const normalized = typeof rawMode === "string" ? rawMode.trim().toLowerCase() : "";
-  if (VALID_EVAL_SEARCH_MODES.has(normalized)) {
-    return normalized;
-  }
-  throw new PmCliError(
-    `Reindex eval fixture ${fixtureLabel} in ${fixturesPath} has unsupported mode "${String(rawMode)}". Expected keyword|semantic|hybrid.`,
-    EXIT_CODE.USAGE,
-  );
-}
-
-function normalizeFixtureThreshold(rawValue, fixtureLabel, fixturesPath) {
-  if (rawValue === undefined) {
-    return DEFAULT_EVAL_MIN_NDCG_AT_5;
-  }
-  const parsed = typeof rawValue === "number" ? rawValue : Number.NaN;
-  if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
-    throw new PmCliError(
-      `Reindex eval fixture ${fixtureLabel} in ${fixturesPath} has invalid min_ndcg_at_5; expected a number between 0 and 1.`,
-      EXIT_CODE.USAGE,
-    );
-  }
-  return parsed;
-}
-
-function normalizeFixtureEntry(rawFixture, index, fixturesPath) {
-  if (!rawFixture || typeof rawFixture !== "object") {
-    throw new PmCliError(
-      `Reindex eval fixture at index ${index + 1} in ${fixturesPath} must be an object.`,
-      EXIT_CODE.USAGE,
-    );
-  }
-  const rawQuery = typeof rawFixture.query === "string" ? rawFixture.query.trim() : "";
-  if (rawQuery.length === 0) {
-    throw new PmCliError(
-      `Reindex eval fixture at index ${index + 1} in ${fixturesPath} must provide a non-empty query.`,
-      EXIT_CODE.USAGE,
-    );
-  }
-  const fallbackName = `fixture-${index + 1}`;
-  const fixtureName =
-    typeof rawFixture.name === "string" && rawFixture.name.trim().length > 0 ? rawFixture.name.trim() : fallbackName;
-  return {
-    name: fixtureName,
-    query: rawQuery,
-    mode: normalizeFixtureMode(rawFixture.mode, fixtureName, fixturesPath),
-    expected_top_ids: toCompactExpectedIds(rawFixture.expected_top_ids, fixtureName, fixturesPath),
-    min_ndcg_at_5: normalizeFixtureThreshold(rawFixture.min_ndcg_at_5, fixtureName, fixturesPath),
-  };
-}
-
-function normalizeFixtureCollection(parsed, fixturesPath) {
-  const parsedObject = parsed && typeof parsed === "object" ? parsed : null;
-  const candidateFixtures = Array.isArray(parsed)
-    ? parsed
-    : parsedObject && Array.isArray(parsedObject.fixtures)
-      ? parsedObject.fixtures
-      : null;
-  if (!candidateFixtures) {
-    throw new PmCliError(
-      `Reindex eval fixtures at ${fixturesPath} must be an array or an object with a fixtures array.`,
-      EXIT_CODE.USAGE,
-    );
-  }
-  if (candidateFixtures.length === 0) {
-    throw new PmCliError(`Reindex eval fixtures at ${fixturesPath} must contain at least one fixture.`, EXIT_CODE.USAGE);
-  }
-  return candidateFixtures.map((entry, index) => normalizeFixtureEntry(entry, index, fixturesPath));
-}
-
-async function loadEvalFixtures(fixturesPath) {
-  let rawText = "";
-  try {
-    rawText = await readFile(fixturesPath, "utf8");
-  } catch {
-    throw new PmCliError(`Unable to read reindex eval fixtures at ${fixturesPath}.`, EXIT_CODE.USAGE);
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(rawText);
-  } catch {
-    throw new PmCliError(`Reindex eval fixtures at ${fixturesPath} must be valid JSON.`, EXIT_CODE.USAGE);
-  }
-  return normalizeFixtureCollection(parsed, fixturesPath);
-}
-
-function computeNdcgAt5(actualIds, expectedIds) {
-  const expectedTop = expectedIds.slice(0, EVAL_RANK_CUTOFF);
-  const relevanceById = new Map();
-  for (let index = 0; index < expectedTop.length; index += 1) {
-    relevanceById.set(expectedTop[index], expectedTop.length - index);
-  }
-  const dcg = actualIds.slice(0, EVAL_RANK_CUTOFF).reduce((sum, id, index) => {
-    const relevance = relevanceById.get(id) ?? 0;
-    return sum + toScoreAtRank(relevance, index);
-  }, 0);
-  const idealDcg = expectedTop.reduce((sum, _id, index) => sum + toScoreAtRank(expectedTop.length - index, index), 0);
-  return dcg / idealDcg;
-}
-
-async function runFixtureEvaluation(fixture, global) {
-  const searchResult = await runSearch(
-    fixture.query,
-    {
-      mode: fixture.mode,
-      limit: String(EVAL_RANK_CUTOFF),
-      fields: "id,score",
-    },
-    global,
-  );
-  const actualTopIds = searchResult.items.map((item) => item.id).slice(0, EVAL_RANK_CUTOFF);
-  const ndcgAt5 = roundMetric(computeNdcgAt5(actualTopIds, fixture.expected_top_ids));
-  const minNdcgAt5 = roundMetric(fixture.min_ndcg_at_5);
-  return {
-    fixture: fixture.name,
-    query: fixture.query,
-    requested_mode: fixture.mode,
-    resolved_mode: searchResult.mode,
-    expected_top_ids: fixture.expected_top_ids,
-    actual_top_ids: actualTopIds,
-    ndcg_at_5: ndcgAt5,
-    min_ndcg_at_5: minNdcgAt5,
-    passed: ndcgAt5 >= minNdcgAt5,
-    warnings: searchResult.warnings ?? [],
-  };
-}
-
-async function runReindexEvaluation(fixturesPath, global) {
-  const fixtures = await loadEvalFixtures(fixturesPath);
-  const results = await Promise.all(fixtures.map((fixture) => runFixtureEvaluation(fixture, global)));
-  const passCount = results.filter((result) => result.passed).length;
-  const averageNdcg = roundMetric(results.reduce((sum, result) => sum + result.ndcg_at_5, 0) / results.length);
-  return {
-    enabled: true,
-    fixtures_path: fixturesPath,
-    k: EVAL_RANK_CUTOFF,
-    fixture_count: results.length,
-    pass_count: passCount,
-    fail_count: results.length - passCount,
-    average_ndcg_at_5: averageNdcg,
-    passed: passCount === results.length,
-    results,
-    evaluated_at: new Date().toISOString(),
-  };
-}
-
-export async function runAdvancedSearchPackage(args, rawOptions, global) {
-  return runSearch(resolveSearchQuery(args), normalizeAdvancedSearchOptions(rawOptions, args), global);
-}
-
-export async function runAdvancedReindexPackage(rawOptions, global) {
-  const options = normalizeReindexRuntimeOptions(rawOptions);
-  const reindexResult = await runReindex(options.reindex, global);
-  if (!options.eval) {
-    return reindexResult;
-  }
-  const evalSummary = await runReindexEvaluation(options.eval.fixturesPath, global);
-  return { ...reindexResult, eval: evalSummary };
-}