heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/symptom-query.mjs

@@ -0,0 +1,146 @@
+/**
+ * symptom-query.mjs — turn a SYMPTOM SENTENCE into the small set of bounded
+ * queries `GET /api/search` can actually answer. Pure: no imports, no I/O, no
+ * console, so both the MCP tool and the console's own route suite can drive it.
+ *
+ * WHY THIS IS NOT "just pass the sentence through"
+ * ------------------------------------------------
+ * The console's ranked path is `websearch_to_tsquery('english', $q)`, and
+ * unquoted words in a websearch query are AND-ed. A real bug report —
+ *
+ *   "row-level security policies exist but are not enforced at runtime;
+ *    the database connection bypasses tenant isolation"
+ *
+ * — is ~12 content words AND-ed together, which matches NOTHING in any vault,
+ * then falls through to the trigram near-miss on `name`, which also matches
+ * nothing. The endpoint answers honestly ("searched, zero hits") and the agent
+ * concludes the symptom was never filed, files a duplicate, and the two
+ * existing specs stay invisible. That is [[HS-YFLS]] AC2.
+ *
+ * So a symptom search is a handful of ANGLES, not one query:
+ *
+ *   phrase   — the sentence verbatim (AND). Rarely hits; when it does, it is
+ *              the highest-precision answer there is, so it is asked first.
+ *   bigrams  — the adjacent salient pairs, quoted, OR-ed. "tenant isolation"
+ *              and "row-level security" are CONCEPTS; a quoted phrase makes
+ *              `ts_rank_cd` reward the document that contains the concept over
+ *              one that merely mentions both words a page apart.
+ *   terms    — every salient term, OR-ed. The recall floor. A document that
+ *              matches eight of the twelve terms outranks one that matches two
+ *              without any extra scoring on our side, because `ts_rank_cd`
+ *              already counts matched lexemes and their density.
+ *
+ * Nothing here is a reranker and nothing is semantic — the substrate is
+ * lexical by decision ([[retrieval-substrate-lexical-not-embeddings-gate-b-no]]).
+ */
+
+/**
+ * Words that carry no retrieval signal in a bug report. Deliberately larger
+ * than a generic English stoplist: the vocabulary of a SYMPTOM ("happens",
+ * "should", "instead", "error", "issue") is noise when every spec in the vault
+ * is about something going wrong.
+ */
+const STOPWORDS = new Set([
+  'a', 'an', 'the', 'and', 'or', 'but', 'not', 'nor', 'for', 'to', 'in', 'on', 'at', 'of',
+  'with', 'without', 'from', 'by', 'as', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+  'do', 'does', 'did', 'has', 'have', 'had', 'can', 'cannot', 'could', 'will', 'would',
+  'should', 'shall', 'may', 'might', 'must', 'this', 'that', 'these', 'those', 'it', 'its',
+  'we', 'our', 'you', 'your', 'they', 'them', 'their', 'there', 'here', 'when', 'where',
+  'what', 'which', 'who', 'whom', 'how', 'why', 'all', 'any', 'some', 'only', 'also',
+  'still', 'then', 'than', 'so', 'if', 'else', 'into', 'onto', 'out', 'up', 'down', 'over',
+  'under', 'again', 'more', 'most', 'much', 'very', 'just', 'now', 'get', 'gets', 'got',
+  // symptom filler — true of every bug, so it discriminates between none of them
+  'bug', 'issue', 'problem', 'error', 'fail', 'fails', 'failed', 'failing', 'broken',
+  'wrong', 'happens', 'happening', 'instead', 'expected', 'actual', 'repro', 'steps',
+  'seems', 'looks', 'like', 'never', 'always', 'sometimes', 'exist', 'exists',
+]);
+
+/** Minimum length for a token to count as salient (drops `is`, `an`, `ok`, `x`). */
+const MIN_TERM_LENGTH = 3;
+
+/** Hard ceiling on salient terms — a 400-word paste must not become a 400-term OR. */
+export const DEFAULT_MAX_TERMS = 12;
+
+/** Hard ceiling on quoted bigram phrases. */
+export const DEFAULT_MAX_BIGRAMS = 6;
+
+/**
+ * Split a symptom sentence into ordered, de-duplicated content terms.
+ * Hyphens and underscores are KEPT inside a word (`row-level`, `vault_id`,
+ * `HS-WRUQ`) because those are the highest-signal tokens a spec vault has;
+ * everything else becomes a separator.
+ */
+export function extractSymptomTerms(text, { maxTerms = DEFAULT_MAX_TERMS } = {}) {
+  if (typeof text !== 'string' || !text.trim()) return [];
+  const raw = text
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, ' ')
+    .split(' ')
+    .map((t) => t.replace(/^[-_]+|[-_]+$/g, ''))
+    .filter(Boolean);
+
+  const ordered = [];
+  const seen = new Set();
+  for (const token of raw) {
+    if (token.length < MIN_TERM_LENGTH) continue;
+    if (STOPWORDS.has(token)) continue;
+    if (/^\d+$/.test(token)) continue;
+    if (seen.has(token)) continue;
+    seen.add(token);
+    ordered.push(token);
+  }
+  if (ordered.length <= maxTerms) return ordered;
+
+  // Over the cap: keep the most SALIENT terms, then restore reading order so
+  // the bigram angle below still pairs words that were adjacent in the report.
+  // Saliency is length plus a bonus for a compound (`row-level`, `vault_id`) —
+  // a crude rarity proxy, but one that needs no corpus statistics and cannot
+  // go stale.
+  const salience = (t) => t.length + (/[-_]/.test(t) ? 4 : 0);
+  const keep = new Set(
+    [...ordered]
+      .sort((a, b) => salience(b) - salience(a) || ordered.indexOf(a) - ordered.indexOf(b))
+      .slice(0, maxTerms),
+  );
+  return ordered.filter((t) => keep.has(t));
+}
+
+/** `["tenant","isolation","neon"]` → `['"tenant isolation"', '"isolation neon"']`. */
+export function buildBigrams(terms, { maxBigrams = DEFAULT_MAX_BIGRAMS } = {}) {
+  const pairs = [];
+  for (let i = 0; i + 1 < terms.length && pairs.length < maxBigrams; i += 1) {
+    pairs.push(`${terms[i]} ${terms[i + 1]}`);
+  }
+  return pairs;
+}
+
+/**
+ * The angles to ask `GET /api/search`, most precise first.
+ *
+ * Returns `{ terms, queries: [{ label, q }] }`. Queries are de-duplicated by
+ * `q`, so a one-word symptom collapses to a single request rather than three
+ * identical ones. An input with no salient terms at all (punctuation, pure
+ * stopwords) yields `queries: []` — the caller must treat that as "nothing
+ * searchable was asked", never as "nothing is filed".
+ */
+export function buildSymptomQueries(text, { maxTerms = DEFAULT_MAX_TERMS, maxBigrams = DEFAULT_MAX_BIGRAMS } = {}) {
+  const phrase = typeof text === 'string' ? text.trim().replace(/\s+/g, ' ') : '';
+  const terms = extractSymptomTerms(phrase, { maxTerms });
+  const queries = [];
+  const pushed = new Set();
+  const push = (label, q) => {
+    if (!q || pushed.has(q)) return;
+    pushed.add(q);
+    queries.push({ label, q });
+  };
+
+  if (terms.length > 0) {
+    // Precision first: the sentence as written, AND-ed by websearch_to_tsquery.
+    if (phrase) push('phrase', phrase);
+    const bigrams = buildBigrams(terms, { maxBigrams });
+    if (bigrams.length > 0) push('bigrams', bigrams.map((b) => `"${b}"`).join(' or '));
+    push('terms', terms.join(' or '));
+  }
+
+  return { phrase, terms, queries };
+}

package/vendor/heyspex-mcp/test-helpers.mjs

@@ -2,9 +2,120 @@
  * Shared test helpers for the vendor MCP round-trip suites.
  */
 
-import { cpSync, existsSync, mkdirSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
+import { resetActiveConfigCache } from './vault-resolve.mjs';
+
+/**
+ * A hermetic `{ account, vault }` scope for tests that drive the REAL console
+ * transport ([[HS-MVG4-WW9R-TASK-mcp-and-hs-name-account-vault-on-every]]).
+ *
+ * Since invariant 2 the transport refuses LOCALLY (no fetch) when the cwd
+ * resolves to an unregistered root or the machine has no configured account.
+ * A test that hits a stand-in console through `consoleFetch` with the default
+ * header resolvers therefore depends on the machine it runs on — registered
+ * here, unregistered on CI — unless it pins both facts. This helper pins them:
+ *
+ *   - a temp HOME (`HOME` + `USERPROFILE`, what `os.homedir()` reads) holding
+ *     `~/.heyspex/registry.json` with the roots the test names,
+ *   - `HS_ACCOUNT_ID` (tier 1 of session-owner.mjs) as the configured account,
+ *   - optionally `HEYSPEX_VAULT_ROOT` pointed at a registered root,
+ *   - `CLAUDE_PROJECT_DIR` (the resolver's cwd base) pointed at that root —
+ *     or at the temp home when none is given — so the resolver's walk starts
+ *     inside the fixture and never climbs through the ambient checkout. The
+ *     walk (tier 2) outranks `HEYSPEX_VAULT_ROOT` (tier 3, [[HS-VVNQ]]), so a
+ *     satellite pin in the repo the suite is run FROM (heyspex-app's own
+ *     `.mcp.json` since 2026-10-10) would otherwise silently replace the
+ *     root a test pinned, and the machine's registry pointer (tier 4) would
+ *     otherwise answer for a test that pinned nothing.
+ *
+ * `registerRoot(root)` adds a row for a root a test mints later (its own temp
+ * vault) and resets the memoized resolver so the next request sees it. Call
+ * `restore()` in `after`/`afterEach`. Nothing here touches the real profile.
+ *
+ * Row ids are UUIDs (what the console mints): the wire gate treats a non-UUID
+ * registry id as a legacy slug and looks for the repo's heyspex.yaml
+ * `vault_id` instead — a slug row with no marker is refused, by design.
+ *
+ * @param {{ accountId?: string, vaultId?: string, repoRootAbs?: string, activeVaultId?: string | null }} [opts]
+ *   `repoRootAbs`: register this root as `vaultId` and set `HEYSPEX_VAULT_ROOT` to it.
+ *   `activeVaultId`: the registry's active pointer (defaults to `vaultId` when a root is registered).
+ */
+export function installScopedConsoleEnv({
+  accountId = 'acct_test',
+  vaultId = randomUUID(),
+  repoRootAbs,
+  activeVaultId,
+} = {}) {
+  const ENV_KEYS = ['HOME', 'USERPROFILE', 'HS_ACCOUNT_ID', 'HEYSPEX_VAULT_ROOT', 'CLAUDE_PROJECT_DIR', 'HEYSPEX_MCP_TOKEN'];
+  const saved = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
+  const home = mkdtempSync(join(tmpdir(), 'hs-scoped-home-'));
+  // The registry lives under the HeySpex home: HEYSPEX_HOME when a test set one, else the scoped HOME.
+  const registryHome = process.env.HEYSPEX_HOME?.trim() || home;
+  const registryDir = join(registryHome, '.heyspex');
+  mkdirSync(registryDir, { recursive: true });
+  const registryPath = join(registryDir, 'registry.json');
+  // Registry schema v2 (HS-RXLG): the pointer is the signed-in account's row.
+  const registry = {
+    schema_version: 2,
+    current_account_id: accountId,
+    accounts: {
+      [accountId]: {
+        active_vault_id: activeVaultId ?? (repoRootAbs ? vaultId : null),
+        active_workspace_id: null,
+      },
+    },
+    workspaces: [],
+    vaults: [],
+  };
+  const flush = () => {
+    writeFileSync(registryPath, JSON.stringify(registry, null, 2));
+    resetActiveConfigCache();
+  };
+
+  const registerRoot = (root, id) => {
+    const rowId = id ?? randomUUID();
+    registry.vaults = registry.vaults.filter((v) => v.id !== rowId && v.repo_root_abs !== root);
+    registry.vaults.push({ id: rowId, repo_root_abs: root, account_id: accountId });
+    flush();
+    return rowId;
+  };
+
+  process.env.HOME = home;
+  process.env.USERPROFILE = home;
+  process.env.HS_ACCOUNT_ID = accountId;
+  // The scoped registry row is bound to this account (machine-local binding), so the
+  // machine must hold a sign-in for it; an env bearer stands in for the credentials file.
+  process.env.HEYSPEX_MCP_TOKEN ||= 'hsmcp_scoped_test_token';
+  // Fence the resolver's walk inside the fixture (see the doc comment above).
+  process.env.CLAUDE_PROJECT_DIR = repoRootAbs ?? home;
+  if (repoRootAbs) {
+    registerRoot(repoRootAbs, vaultId);
+    process.env.HEYSPEX_VAULT_ROOT = repoRootAbs;
+  } else {
+    flush();
+  }
+
+  return {
+    home,
+    accountId,
+    vaultId,
+    registryPath,
+    registerRoot,
+    restore() {
+      for (const k of ENV_KEYS) {
+        if (saved[k] === undefined) delete process.env[k];
+        else process.env[k] = saved[k];
+      }
+      resetActiveConfigCache();
+      rmSync(home, { recursive: true, force: true });
+    },
+  };
+}
+
 /**
  * Mirror into a temp vault every real-repo file that
  * `scripts/validate-vault-ids.mjs` needs to run in isolation.
@@ -19,6 +130,13 @@ import { join } from 'node:path';
  * id-suffix-shape rule, compiled from protocol frontmatter), so that file must be
  * mirrored too or the engine import dangles.
  *
+ * Post repo-split, `scripts/lib/resolve-validate-root.mjs` (copied wholesale as
+ * part of `scripts/`) also imports `vendor/heyspex-mcp/vault-resolve.mjs` by a
+ * relative path OUTSIDE `scripts/` — that file must be mirrored too, or the
+ * copied validator dangles with MODULE_NOT_FOUND the moment it computes its
+ * own default root. `vault-resolve.mjs` itself has no further local-file
+ * imports (node builtins only), so this is a single extra copy, not a chain.
+ *
  * Single source of truth: the next dependency the validator grows is a one-line
  * add here, not a silent breakage in every round-trip test.
  *
@@ -28,6 +146,10 @@ import { join } from 'node:path';
 export function mirrorValidatorDeps(repoRoot, root) {
   cpSync(join(repoRoot, 'scripts'), join(root, 'scripts'), { recursive: true });
 
+  const vaultResolveRel = join('vendor', 'heyspex-mcp', 'vault-resolve.mjs');
+  mkdirSync(join(root, 'vendor', 'heyspex-mcp'), { recursive: true });
+  cpSync(join(repoRoot, vaultResolveRel), join(root, vaultResolveRel));
+
   const indexerRel = join('spex-console', 'src', 'lib', 'indexer');
   mkdirSync(join(root, indexerRel), { recursive: true });
   for (const file of [