rcf-lite 0.27.0 → 0.28.1

package/src/feedback/destination.js

@@ -0,0 +1,455 @@
+// Feedback destination resolver (TAC-4106-feedback-destination,
+// ADR-4104-destination-on-library). Slice 3 (FBS-182): given a pending
+// entry plus the project's manifest and library registry, work out
+// which GitHub repo the finding should be filed against and whether it
+// is public or private. The resolver is pure: no i/o, no network,
+// nothing that would slow preview or submit down to disk speed.
+//
+// Resolution order (design section 3.3):
+//   1. --kind core                        -> CORE_REPO (public)
+//   2. --kind blueprint, no libraryPrefix -> library-slug inference
+//      (AC-15801-4 / design amendment R5a): if the applied slug is
+//      owned by exactly one registered library that resolves to a
+//      destination (issuesRepo or derivable sourceRef), route there
+//      with source: 'library-slug-inference'; if two or more libraries
+//      own the slug and resolve, return unresolved with reason
+//      'ambiguous-library-slug' and a candidates[] array of prefixes;
+//      otherwise fall through to CORE_REPO (shelf; public).
+//   3. --kind blueprint, libraryPrefix    -> registry entry issuesRepo
+//                                            (declared destination wins;
+//                                            visibility from the entry)
+//   4. registry entry with no issuesRepo  -> derive from sourceRef when
+//                                            it parses as
+//                                            git+https://github.com/OWNER/REPO(.git)#ref
+//                                            (marked derived: true;
+//                                            visibility defaults to
+//                                            public unless the entry
+//                                            already asserted private)
+//   5. anything else                      -> unresolved (reason names
+//                                            the why, publisherContact
+//                                            carries the registry
+//                                            contact when known)
+//
+// The CORE_REPO constant is derived from packages/rcf-lite/package.json
+// bugs.url. Because a resolver call is on the hot path of preview and
+// submit, and because reading package.json every call is wasteful and
+// hard to test in isolation, the value is cached at module load time.
+// A dedicated `resolveCoreRepo()` helper (also exported) does the
+// parse; consumers with their own package.json can call it directly
+// and the resolver's CORE_REPO getter reads through it.
+
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve as resolvePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+// packages/rcf-lite/src/feedback -> packages/rcf-lite/package.json.
+const PACKAGE_JSON_PATH = resolvePath(here, '..', '..', 'package.json');
+const CORE_REPO_FALLBACK = 'Stravica/rcf-lite';
+
+/**
+ * The Stravica/rcf-lite constant that every core-kind entry and every
+ * shelf-blueprint entry routes to. Sourced from
+ * `packages/rcf-lite/package.json:bugs.url` at module load so a rename
+ * only ripples through one file; a matching unit test pins the constant
+ * to the package.json value at test time so a drift is caught in CI.
+ *
+ * @type {string}
+ */
+export let CORE_REPO = CORE_REPO_FALLBACK;
+
+/** Guard against double-init during test loops. */
+let coreRepoInitialised = false;
+
+/**
+ * Parse `bugs.url` from a package.json object and return `OWNER/REPO`.
+ * Accepts the trailing `/issues`, an `.git` suffix and either the
+ * string or the object shape npm allows on `bugs`.
+ *
+ * @param {object | undefined | null} pkg
+ * @returns {string | null}
+ */
+export function parseBugsRepo(pkg) {
+  if (pkg == null) return null;
+  const bugs = typeof pkg.bugs === 'string' ? pkg.bugs : pkg?.bugs?.url;
+  if (typeof bugs !== 'string' || bugs.length === 0) return null;
+  const withIssues = bugs.match(/github\.com\/([^/]+)\/([^/#?]+?)(?:\.git)?\/issues\/?(?:[/?#].*)?$/i);
+  if (withIssues) return `${withIssues[1]}/${withIssues[2]}`;
+  const bare = bugs.match(/github\.com\/([^/]+)\/([^/#?]+?)(?:\.git)?\/?$/i);
+  if (bare) return `${bare[1]}/${bare[2]}`;
+  return null;
+}
+
+/**
+ * Read `packages/rcf-lite/package.json` and populate `CORE_REPO`. Safe
+ * to call more than once; a failed read leaves the fallback in place.
+ * The resolver auto-inits on first `resolve()` call, so most callers
+ * never touch this directly; tests call it to force a fresh read.
+ *
+ * @returns {Promise<string>}
+ */
+export async function initCoreRepo() {
+  try {
+    const text = await readFile(PACKAGE_JSON_PATH, 'utf8');
+    const pkg = JSON.parse(text);
+    const parsed = parseBugsRepo(pkg);
+    if (parsed) CORE_REPO = parsed;
+  } catch {
+    // Missing or unreadable package.json leaves the fallback active.
+    // A dedicated test pins the value in CI so this branch never ships.
+  }
+  coreRepoInitialised = true;
+  return CORE_REPO;
+}
+
+/**
+ * Parse a git sourceRef of the shape `git+https://github.com/OWNER/REPO(.git)#ref`
+ * (or `git+ssh://git@github.com:OWNER/REPO.git#ref`, the two shapes
+ * `library add` accepts) into `OWNER/REPO`. Anything else returns null;
+ * the resolver treats that as "cannot derive", not as an error.
+ *
+ * @param {string} sourceRef
+ * @returns {string | null}
+ */
+export function parseGithubSource(sourceRef) {
+  if (typeof sourceRef !== 'string' || sourceRef.length === 0) return null;
+  // git+https://github.com/OWNER/REPO(.git)(#ref)
+  const https = sourceRef.match(/^git\+https?:\/\/github\.com\/([^/]+)\/([^/#?]+?)(?:\.git)?(?:#.*)?$/i);
+  if (https) return `${https[1]}/${https[2]}`;
+  // git+ssh://git@github.com:OWNER/REPO.git(#ref) or git+ssh://git@github.com/OWNER/REPO.git(#ref)
+  const ssh = sourceRef.match(/^git\+ssh:\/\/git@github\.com[:\/]([^/]+)\/([^/#?]+?)(?:\.git)?(?:#.*)?$/i);
+  if (ssh) return `${ssh[1]}/${ssh[2]}`;
+  return null;
+}
+
+/**
+ * Look up a blueprint record on `manifest.blueprints[]` by ref. Accepts
+ * the shelf slug (`security-auth-magic-link`), the prefix:slug form
+ * (`wsd:std-error-envelope`) and the effective slug already stamped
+ * onto the record (`wsd-std-error-envelope`).
+ *
+ * F-slice-3-01: a QUALIFIED ref (`prefix:slug`) must resolve to a
+ * record whose libraryPrefix matches the qualifier. Falling back to
+ * an unqualified shelf record on slug collision would route a
+ * private WSD finding to the public Stravica/rcf-lite repo. The
+ * matcher therefore has two passes: first, any record whose stamped
+ * effectiveSlug OR (slug + libraryPrefix) matches the qualifier
+ * wins; only when the ref is unqualified do bare-slug matches apply.
+ *
+ * @param {object | null | undefined} manifest
+ * @param {string} ref
+ * @returns {object | null}
+ */
+export function findBlueprintRecord(manifest, ref) {
+  const list = Array.isArray(manifest?.blueprints) ? manifest.blueprints : [];
+  if (typeof ref !== 'string' || ref.length === 0) return null;
+
+  // Qualified `prefix:slug` (and the equivalent `prefix-slug`
+  // effective-slug shape) must NEVER match a shelf record whose
+  // libraryPrefix does not equal the qualifier. F-slice-3-01: a
+  // qualified WSD ref must not fall back to a public shelf record
+  // on slug collision.
+  if (ref.includes(':')) {
+    const [pre, slug] = ref.split(':');
+    if (pre && slug) {
+      const effective = `${pre}-${slug}`;
+      for (const r of list) {
+        if (!r || typeof r !== 'object') continue;
+        if (r.libraryPrefix !== pre) continue;
+        const candidates = recordCandidates(r);
+        if (candidates.includes(ref) || candidates.includes(effective) || candidates.includes(slug)) return r;
+      }
+      return null;
+    }
+  }
+
+  // Unqualified ref: match by any candidate. A record with a
+  // libraryPrefix still matches, but only through its stamped
+  // canonical effective slug (`libraryPrefix-slug`) - never through
+  // a bare, unqualified slug that could collide with a shelf record.
+  for (const r of list) {
+    if (!r || typeof r !== 'object') continue;
+    const isQualifiedRecord = typeof r.libraryPrefix === 'string' && r.libraryPrefix.length > 0;
+    if (isQualifiedRecord) {
+      const canonical = recordEffectiveSlug(r);
+      if (canonical && ref === canonical) return r;
+      continue;
+    }
+    const candidates = recordCandidates(r);
+    if (candidates.includes(ref)) return r;
+  }
+  return null;
+}
+
+/**
+ * The candidate name set stamped on a manifest record: any of
+ * effectiveSlug, slug, name that are non-empty strings.
+ *
+ * @param {object} record
+ * @returns {string[]}
+ */
+function recordCandidates(record) {
+  return [record.effectiveSlug, record.slug, record.name].filter(
+    (s) => typeof s === 'string' && s.length > 0,
+  );
+}
+
+/**
+ * The canonical effective slug for a qualified manifest record. If
+ * the record already carries `effectiveSlug`, that wins; otherwise
+ * synthesise it from `libraryPrefix` + `slug` (either the slug is
+ * already prefixed, or we prepend the prefix).
+ *
+ * @param {object} record
+ * @returns {string | null}
+ */
+function recordEffectiveSlug(record) {
+  if (typeof record.effectiveSlug === 'string' && record.effectiveSlug.length > 0) return record.effectiveSlug;
+  const pre = typeof record.libraryPrefix === 'string' ? record.libraryPrefix : '';
+  const slug = typeof record.slug === 'string' ? record.slug : '';
+  if (!pre || !slug) return null;
+  return slug.startsWith(`${pre}-`) ? slug : `${pre}-${slug}`;
+}
+
+/**
+ * @typedef {object} Destination
+ * @property {string | null} repo         OWNER/REPO or null when unresolved
+ * @property {'public' | 'private' | 'unresolved'} visibility
+ * @property {'core' | 'shelf' | 'library'} kind
+ * @property {boolean} derived            true when repo came from sourceRef derivation
+ * @property {string} [reason]            filled on unresolved: 'no-issues-field' | 'no-github-source' | 'no-libraryprefix-record' | 'unknown-target' | 'ambiguous-library-slug'
+ * @property {string[]} [candidates]      filled on unresolved with reason 'ambiguous-library-slug': sorted library prefixes owning the slug
+ * @property {string} [publisherContact]  registry entry's publisher.contact (bundle uses it)
+ * @property {string} [source]            'library-manifest' | 'sourceRef-derivation' | 'package-bugs-url' | 'shelf-constant' | 'library-slug-inference'
+ */
+
+/**
+ * Resolve one entry to its destination shape. Pure over the inputs.
+ *
+ * @param {object} entry                 a feedback entry (design §4.1)
+ * @param {object} [context]
+ * @param {object} [context.manifest]    parsed rcf/manifest.json
+ * @param {object} [context.registry]    parsed rcf/blueprint-libraries.json
+ * @returns {Promise<Destination>}
+ */
+export async function resolve(entry, context = {}) {
+  if (!coreRepoInitialised) await initCoreRepo();
+  const manifest = context.manifest ?? null;
+  const registry = context.registry ?? { libraries: [] };
+  const kind = entry?.kind;
+
+  if (kind === 'core') {
+    return {
+      repo: CORE_REPO,
+      visibility: 'public',
+      kind: 'core',
+      derived: false,
+      source: 'package-bugs-url',
+    };
+  }
+  if (kind !== 'blueprint') {
+    return {
+      repo: null,
+      visibility: 'unresolved',
+      kind: 'library',
+      derived: false,
+      reason: 'unknown-target',
+    };
+  }
+
+  const ref = entry?.target?.ref;
+  const record = findBlueprintRecord(manifest, ref);
+  if (!record) {
+    return {
+      repo: null,
+      visibility: 'unresolved',
+      kind: 'library',
+      derived: false,
+      reason: 'unknown-target',
+    };
+  }
+
+  const libraryPrefix = record.libraryPrefix ?? entry?.target?.libraryPrefix ?? null;
+
+  // Shelf blueprint (no libraryPrefix on the manifest record). Before
+  // falling through to the shelf constant, cross-check the registry:
+  // if exactly one registered library owns a blueprint with the applied
+  // slug AND that library resolves to a destination, route to that
+  // library so a bare-slug apply of a library-shared name still lands
+  // on the library owner's repo (design amendment R5, AC-15801-4).
+  if (!libraryPrefix) {
+    const inferred = inferLibraryFromSlug(record, registry);
+    if (inferred.kind === 'single') {
+      return inferred.destination;
+    }
+    if (inferred.kind === 'ambiguous') {
+      return {
+        repo: null,
+        visibility: 'unresolved',
+        kind: 'library',
+        derived: false,
+        reason: 'ambiguous-library-slug',
+        candidates: inferred.candidates,
+      };
+    }
+    return {
+      repo: CORE_REPO,
+      visibility: 'public',
+      kind: 'shelf',
+      derived: false,
+      source: 'package-bugs-url',
+    };
+  }
+
+  const libEntry = findLibraryEntry(registry, libraryPrefix);
+  if (!libEntry) {
+    return {
+      repo: null,
+      visibility: 'unresolved',
+      kind: 'library',
+      derived: false,
+      reason: 'no-libraryprefix-record',
+    };
+  }
+
+  const contact = typeof libEntry?.publisher?.contact === 'string'
+    ? libEntry.publisher.contact
+    : undefined;
+
+  // Declared destination wins.
+  if (typeof libEntry.issuesRepo === 'string' && libEntry.issuesRepo.length > 0) {
+    const declaredVisibility = libEntry.issuesVisibility === 'private' ? 'private'
+      : libEntry.issuesVisibility === 'public' ? 'public'
+        : 'public';
+    return {
+      repo: libEntry.issuesRepo,
+      visibility: declaredVisibility,
+      kind: 'library',
+      derived: false,
+      source: 'library-manifest',
+      ...(contact ? { publisherContact: contact } : {}),
+    };
+  }
+
+  // Fallback: derive from sourceRef when it parses as a github URL.
+  const derived = parseGithubSource(libEntry.sourceRef ?? '');
+  if (derived) {
+    return {
+      repo: derived,
+      visibility: 'public',
+      kind: 'library',
+      derived: true,
+      source: 'sourceRef-derivation',
+      ...(contact ? { publisherContact: contact } : {}),
+    };
+  }
+
+  // Neither declared nor derivable: unresolved.
+  return {
+    repo: null,
+    visibility: 'unresolved',
+    kind: 'library',
+    derived: false,
+    reason: libEntry.sourceRef ? 'no-github-source' : 'no-issues-field',
+    ...(contact ? { publisherContact: contact } : {}),
+  };
+}
+
+/**
+ * Enumerate every registered library and flag the ones the resolver
+ * cannot produce a destination for (no issues field and no derivable
+ * github source). Doctor's `feedback-destinations` check consumes this;
+ * the shape is `{ libraryPrefix, reason, publisherContact? }`.
+ *
+ * @param {object} registry
+ * @returns {Array<{ libraryPrefix: string, reason: 'no-issues-field' | 'no-github-source', publisherContact?: string }>}
+ */
+export function listUnresolvedLibraries(registry) {
+  const out = [];
+  const libs = Array.isArray(registry?.libraries) ? registry.libraries : [];
+  for (const lib of libs) {
+    if (typeof lib?.libraryPrefix !== 'string') continue;
+    if (typeof lib.issuesRepo === 'string' && lib.issuesRepo.length > 0) continue;
+    const derived = parseGithubSource(lib.sourceRef ?? '');
+    if (derived) continue;
+    const contact = typeof lib?.publisher?.contact === 'string' ? lib.publisher.contact : undefined;
+    out.push({
+      libraryPrefix: lib.libraryPrefix,
+      reason: lib.sourceRef ? 'no-github-source' : 'no-issues-field',
+      ...(contact ? { publisherContact: contact } : {}),
+    });
+  }
+  return out;
+}
+
+function findLibraryEntry(registry, libraryPrefix) {
+  const libs = Array.isArray(registry?.libraries) ? registry.libraries : [];
+  return libs.find((l) => l?.libraryPrefix === libraryPrefix) ?? null;
+}
+
+/**
+ * AC-15801-4 / design amendment R5a: given a manifest record with no
+ * libraryPrefix, cross-check the registry to see whether the applied
+ * slug is owned by exactly one registered library that resolves to a
+ * destination. Returns:
+ *   { kind: 'none' }                                 no library owns the slug (or none resolve)
+ *   { kind: 'single', destination }                  exactly one library owns the slug and resolves
+ *   { kind: 'ambiguous', candidates: string[] }      two or more libraries own the slug and resolve
+ *
+ * The resolver only calls this on the shelf-constant fall-through
+ * branch, so it never overrides an existing libraryPrefix resolution.
+ *
+ * @param {object} record                              manifest.blueprints[] record
+ * @param {object | null | undefined} registry         parsed rcf/blueprint-libraries.json
+ */
+function inferLibraryFromSlug(record, registry) {
+  const slug = typeof record?.slug === 'string' ? record.slug : null;
+  if (!slug) return { kind: 'none' };
+  const libs = Array.isArray(registry?.libraries) ? registry.libraries : [];
+  const owners = [];
+  for (const lib of libs) {
+    if (!lib || typeof lib !== 'object') continue;
+    if (typeof lib.libraryPrefix !== 'string' || lib.libraryPrefix.length === 0) continue;
+    const bps = Array.isArray(lib.blueprints) ? lib.blueprints : [];
+    const owns = bps.some((b) => b && typeof b.slug === 'string' && b.slug === slug);
+    if (!owns) continue;
+    const declared = typeof lib.issuesRepo === 'string' && lib.issuesRepo.length > 0 ? lib.issuesRepo : null;
+    const derivedRepo = declared ? null : parseGithubSource(lib.sourceRef ?? '');
+    if (!declared && !derivedRepo) continue;
+    const contact = typeof lib?.publisher?.contact === 'string' ? lib.publisher.contact : undefined;
+    owners.push({ lib, declared, derivedRepo, contact });
+  }
+  if (owners.length === 0) return { kind: 'none' };
+  if (owners.length === 1) {
+    const [o] = owners;
+    if (o.declared) {
+      const declaredVisibility = o.lib.issuesVisibility === 'private' ? 'private'
+        : o.lib.issuesVisibility === 'public' ? 'public'
+          : 'public';
+      return {
+        kind: 'single',
+        destination: {
+          repo: o.declared,
+          visibility: declaredVisibility,
+          kind: 'library',
+          derived: false,
+          source: 'library-slug-inference',
+          ...(o.contact ? { publisherContact: o.contact } : {}),
+        },
+      };
+    }
+    return {
+      kind: 'single',
+      destination: {
+        repo: o.derivedRepo,
+        visibility: 'public',
+        kind: 'library',
+        derived: true,
+        source: 'library-slug-inference',
+        ...(o.contact ? { publisherContact: o.contact } : {}),
+      },
+    };
+  }
+  const candidates = owners.map((o) => o.lib.libraryPrefix).sort();
+  return { kind: 'ambiguous', candidates };
+}

package/src/feedback/fingerprint.js

@@ -0,0 +1,132 @@
+// Feedback fingerprint (TAC-4104-feedback-fingerprint, ADR-4102).
+// Deterministic 12-hex fingerprint per entry that keys the same-defect
+// fold when the submit path (slice 4) files issues.
+//
+// Canonical input (design section 6):
+//   sha-256("<kind>|<targetKey>|<anchor>|<symptomClass>") -> first 12 hex
+// where
+//   - targetKey is the effective slug for blueprints (no version) or
+//     the verb path for core; a target that came in as
+//     `prefix:slug` is normalised to `prefix-slug`.
+//   - anchor is upper-cased, or `-` when absent.
+//   - symptomClass is one of the closed enum.
+//
+// Fallback (when the entry has no anchor): the canonical input becomes
+//   sha-256("<kind>|<targetKey>|<symptomClass>|<normalisedTitle>")
+// where normalisedTitle is the first eight tokens of the title
+// lower-cased, punctuation stripped and stop-words removed.
+//
+// Blueprint version is not part of the fingerprint (§6, §9) so a
+// defect that persists across versions folds into one issue with the
+// versions in the comments.
+
+import { createHash } from 'node:crypto';
+
+/** Length of the truncated fingerprint (hex chars). */
+export const FINGERPRINT_HEX_LEN = 12;
+
+/** Cheap English stop-word list used by the fallback title tokeniser. */
+const STOP_WORDS = new Set([
+  'a', 'an', 'the', 'and', 'or', 'but', 'if', 'of', 'in', 'on', 'at',
+  'to', 'for', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+  'it', 'this', 'that', 'these', 'those', 'as', 'by', 'with', 'from',
+  'into', 'over', 'under', 'up', 'down', 'not', 'no', 'do', 'does',
+  'did', 'has', 'have', 'had',
+]);
+
+/**
+ * Compute an entry fingerprint. Accepts the entry shape written by
+ * `rcf feedback add` (see src/feedback/store.js FeedbackEntry) and
+ * emits a 12-hex string keyed on the fields listed above.
+ *
+ * @param {object} entry
+ * @returns {string} 12 lower-case hex chars
+ */
+export function fingerprint(entry) {
+  const input = fingerprintInput(entry);
+  return createHash('sha256').update(input, 'utf8').digest('hex').slice(0, FINGERPRINT_HEX_LEN);
+}
+
+/**
+ * Return the exact canonical string that hashes to the fingerprint.
+ * Exposed for the disclosure line on `preview` and for the test
+ * corpus, so a maintainer can reproduce the value by hand.
+ *
+ * @param {object} entry
+ * @returns {string}
+ */
+export function fingerprintInput(entry) {
+  const kind = String(entry?.kind ?? '').toLowerCase();
+  const targetKey = deriveTargetKey(entry);
+  const anchor = normaliseAnchor(entry?.anchor);
+  const symptomClass = String(entry?.symptomClass ?? 'other');
+  if (anchor === '-') {
+    const normalisedTitle = normaliseTitle(entry?.title ?? '');
+    return `${kind}|${targetKey}|${symptomClass}|${normalisedTitle}`;
+  }
+  return `${kind}|${targetKey}|${anchor}|${symptomClass}`;
+}
+
+/**
+ * Derive the targetKey portion of the canonical input.
+ *
+ *   blueprint: effectiveSlug from the entry.target if present, else
+ *              a normalised form of the ref (`wsd:std-error-envelope`
+ *              becomes `wsd-std-error-envelope`; already-dashed
+ *              refs pass through unchanged).
+ *   core:      the verb path from entry.target.ref, lower-cased with
+ *              whitespace collapsed to single spaces.
+ *
+ * @param {object} entry
+ * @returns {string}
+ */
+export function deriveTargetKey(entry) {
+  const t = entry?.target ?? {};
+  const kind = String(entry?.kind ?? '').toLowerCase();
+  if (kind === 'blueprint') {
+    if (typeof t.effectiveSlug === 'string' && t.effectiveSlug.length > 0) {
+      return t.effectiveSlug;
+    }
+    const ref = String(t.ref ?? '');
+    if (ref.includes(':')) return ref.replace(':', '-');
+    return ref;
+  }
+  const ref = String(t.ref ?? '');
+  return ref.trim().replace(/\s+/g, ' ').toLowerCase();
+}
+
+/**
+ * Normalise the anchor: upper-case, trim; return `-` when the value
+ * is nullish, empty or whitespace-only.
+ *
+ * @param {string | null | undefined} anchor
+ * @returns {string}
+ */
+export function normaliseAnchor(anchor) {
+  if (anchor == null) return '-';
+  const trimmed = String(anchor).trim();
+  if (trimmed === '') return '-';
+  return trimmed.toUpperCase();
+}
+
+/**
+ * Normalise a title for the fallback fingerprint: lower-case, strip
+ * punctuation, remove stop-words, keep the first eight remaining
+ * tokens joined by single spaces.
+ *
+ * @param {string} title
+ * @returns {string}
+ */
+export function normaliseTitle(title) {
+  // F-slice-2-11: normalise every non-ASCII dash variant (em, en,
+  // figure, horizontal bar, hyphen, non-breaking hyphen, minus) to
+  // an ASCII hyphen first, then strip ALL punctuation including
+  // ASCII hyphens. "probe-fails" and its em-dash sibling
+  // "probe—fails" then hash the same.
+  const dashNormalised = String(title ?? '').replace(/[‐-―−-]/g, ' ');
+  const lowered = dashNormalised.toLowerCase();
+  const cleaned = lowered.replace(/[^a-z0-9\s]/g, ' ').replace(/\s+/g, ' ').trim();
+  if (cleaned === '') return '';
+  const tokens = cleaned.split(' ').filter((t) => t.length > 0 && !STOP_WORDS.has(t));
+  return tokens.slice(0, 8).join(' ');
+}