@geraldmaron/construct 1.0.0 → 1.0.2

package/lib/engine/fuser-rrf.mjs

@@ -0,0 +1,62 @@
+/**
+ * lib/engine/fuser-rrf.mjs — Reciprocal Rank Fusion (RRF) Fuser plugin.
+ *
+ * Combines multiple ranked lists into a single ranking using:
+ *
+ *     RRF(d) = Σ 1 / (k + rank_i(d))
+ *
+ * where rank_i(d) is the 1-based position of document d in the i-th ranker's
+ * output (or treated as if d were past the end of the list when absent), and
+ * k is a smoothing constant (60 by default, the value used in the original
+ * Cormack et al. 2009 paper and in production search systems like
+ * Elasticsearch/Vespa).
+ *
+ * RRF is corpus-agnostic — only ranks matter, not raw scores — so it avoids
+ * the correctness asymmetry that affects weighted-sum fusion when one ranker
+ * (e.g. BM25) only scores a top-K window: chunks outside that window would
+ * contribute 0 from that ranker even when they scored high on the other.
+ *
+ * Plugin contract (Fuser):
+ *   meta: { id, k }
+ *   fuse(rankedLists, opts) → ranked[]
+ *
+ * `rankedLists` is either an array of arrays (each pre-sorted, highest-first)
+ * or a Record<channelName, ranked[]>. Both shapes are supported so legacy
+ * callers using the weighted-sum default can swap in RRF without rewriting
+ * their call site.
+ */
+
+const DEFAULT_K = 60;
+
+function toLists(input) {
+  if (Array.isArray(input)) return input;
+  if (input && typeof input === 'object') return Object.values(input);
+  return [];
+}
+
+export function create({ k = DEFAULT_K } = {}) {
+  return {
+    meta: { id: 'rrf', k },
+    fuse(rankedLists, opts = {}) {
+      const kEff = opts.k ?? k;
+      const lists = toLists(rankedLists);
+      const merged = new Map();
+
+      for (const list of lists) {
+        if (!Array.isArray(list)) continue;
+        for (let rank = 0; rank < list.length; rank++) {
+          const doc = list[rank];
+          if (!doc?.id) continue;
+          const contribution = 1 / (kEff + rank + 1);
+          const prev = merged.get(doc.id) || { ...doc, score: 0 };
+          prev.score = (prev.score || 0) + contribution;
+          merged.set(doc.id, prev);
+        }
+      }
+
+      return [...merged.values()].sort((a, b) => b.score - a.score);
+    },
+  };
+}
+
+export default create;

package/lib/engine/index.mjs

@@ -0,0 +1,37 @@
+/**
+ * lib/engine/index.mjs — Public entry point for the Construct retrieval engine.
+ *
+ * Single import surface for callers that need plugin-resolved layers
+ * (Embedder, Chunker, Indexer, Fuser, Reranker, Compressor). Resolution is
+ * cached per (rootDir) — engines are reusable across calls in the same process,
+ * so we avoid re-loading ONNX models or re-reading plugins.json on every query.
+ *
+ * Use `getEngine({ rootDir })` to fetch the cached engine. `resetEngine()`
+ * forces a re-resolution (useful for tests and `construct doctor` after a
+ * plugin config change).
+ */
+
+import { resolveEngine, describeEngine } from './registry.mjs';
+import { LAYERS, assertContract, checkContract } from './contracts.mjs';
+
+const CACHE = new Map();
+
+/**
+ * Return the resolved engine for a project root. Cached per rootDir.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.rootDir]
+ * @returns {Promise<{ layers, sources, errors }>}
+ */
+export async function getEngine({ rootDir = process.cwd() } = {}) {
+  if (!CACHE.has(rootDir)) {
+    CACHE.set(rootDir, resolveEngine({ rootDir }));
+  }
+  return CACHE.get(rootDir);
+}
+
+export function resetEngine() {
+  CACHE.clear();
+}
+
+export { describeEngine, LAYERS, assertContract, checkContract };

package/lib/engine/registry.mjs

@@ -0,0 +1,146 @@
+/**
+ * lib/engine/registry.mjs — Plugin resolver for the Construct retrieval engine.
+ *
+ * Resolution order (last-write wins):
+ *   1. Built-in defaults (lib/engine/defaults.mjs)
+ *   2. ~/.construct/plugins.json   (operator-level overrides)
+ *   3. <project>/.cx/plugins.json  (repo-level overrides)
+ *   4. CONSTRUCT_PLUGIN_<LAYER> environment variables (one-off overrides)
+ *
+ * Plugin entry shape (in plugins.json):
+ *   { "layer": "embedder", "package": "github:user/repo#sha", "options": {} }
+ *
+ * `package` is one of:
+ *   - bare module name resolved via standard Node ESM resolution
+ *   - absolute path to a local module
+ *   - "github:owner/repo#ref" string (resolved via npm/yarn — caller installs out of band)
+ *
+ * Failures (load error, contract mismatch) fall back to the default impl for
+ * that layer and are surfaced via construct doctor / hook telemetry.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { LAYERS, assertContract } from './contracts.mjs';
+import { loadDefaults } from './defaults.mjs';
+
+const ENV_PREFIX = 'CONSTRUCT_PLUGIN_';
+
+function readJsonIfExists(path) {
+  try {
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Build the layered list of override entries from disk and env. Later entries
+// take precedence per layer.
+
+function gatherOverrides(rootDir) {
+  const overrides = [];
+
+  const userConfig = readJsonIfExists(join(homedir(), '.construct', 'plugins.json'));
+  if (userConfig?.plugins) overrides.push(...userConfig.plugins);
+
+  const projectConfig = readJsonIfExists(join(rootDir, '.cx', 'plugins.json'));
+  if (projectConfig?.plugins) overrides.push(...projectConfig.plugins);
+
+  for (const layer of LAYERS) {
+    const envKey = `${ENV_PREFIX}${layer.toUpperCase()}`;
+    if (process.env[envKey]) {
+      overrides.push({ layer, package: process.env[envKey], options: {} });
+    }
+  }
+
+  return overrides;
+}
+
+async function importPlugin(pkg, rootDir) {
+  if (typeof pkg !== 'string' || !pkg) {
+    throw new Error(`plugin package must be a non-empty string`);
+  }
+
+  if (pkg.startsWith('github:')) {
+    throw new Error(
+      `github: plugin spec '${pkg}' is not auto-installed. Install via 'npm install ${pkg}' first, then reference by package name.`
+    );
+  }
+
+  if (isAbsolute(pkg) || pkg.startsWith('./') || pkg.startsWith('../')) {
+    const abs = isAbsolute(pkg) ? pkg : resolve(rootDir, pkg);
+    return import(pathToFileURL(abs).href);
+  }
+
+  return import(pkg);
+}
+
+async function tryLoadOverride(entry, rootDir) {
+  const { layer, package: pkg, options = {} } = entry || {};
+  if (!LAYERS.includes(layer)) {
+    return { ok: false, layer, error: `unknown layer: ${layer}` };
+  }
+  try {
+    const mod = await importPlugin(pkg, rootDir);
+    const factory = mod?.create || mod?.default;
+    if (typeof factory !== 'function') {
+      return { ok: false, layer, error: `plugin '${pkg}' must export 'create' or default factory` };
+    }
+    const plugin = await factory(options);
+    assertContract(layer, plugin);
+    return { ok: true, layer, plugin, source: pkg };
+  } catch (err) {
+    return { ok: false, layer, error: `plugin '${pkg}' failed: ${err.message}` };
+  }
+}
+
+/**
+ * Resolve every layer to an active plugin.
+ *
+ * @param {object} opts
+ * @param {string} [opts.rootDir]
+ * @returns {Promise<{
+ *   layers: Record<string, object>,
+ *   sources: Record<string, string>,
+ *   errors: Array<{ layer: string, error: string }>,
+ * }>}
+ */
+export async function resolveEngine({ rootDir = process.cwd() } = {}) {
+  const defaults = await loadDefaults();
+  const layers = { ...defaults };
+  const sources = Object.fromEntries(LAYERS.map((l) => [l, 'default']));
+  const errors = [];
+
+  for (const layer of LAYERS) {
+    assertContract(layer, layers[layer]);
+  }
+
+  for (const entry of gatherOverrides(rootDir)) {
+    const result = await tryLoadOverride(entry, rootDir);
+    if (result.ok) {
+      layers[result.layer] = result.plugin;
+      sources[result.layer] = result.source;
+    } else {
+      errors.push({ layer: result.layer, error: result.error });
+    }
+  }
+
+  return { layers, sources, errors };
+}
+
+/**
+ * Diagnostic summary for `construct doctor` — does not throw.
+ */
+export async function describeEngine({ rootDir = process.cwd() } = {}) {
+  const { layers, sources, errors } = await resolveEngine({ rootDir });
+  const summary = LAYERS.map((layer) => ({
+    layer,
+    id: layers[layer]?.meta?.id || '(missing)',
+    source: sources[layer],
+    capabilities: { ...layers[layer]?.meta },
+  }));
+  return { summary, errors };
+}

package/lib/engine/reranker-mmr.mjs

@@ -0,0 +1,90 @@
+/**
+ * lib/engine/reranker-mmr.mjs — Maximal Marginal Relevance (MMR) Reranker plugin.
+ *
+ * Re-orders a fused candidate list to balance relevance against diversity:
+ *
+ *     MMR(d) = λ · sim(d, q) − (1 − λ) · max_{d'∈S} sim(d, d')
+ *
+ * where S is the set of already-selected docs. λ defaults to 0.7 — favoring
+ * relevance, but enough diversity weight to drop near-duplicates. λ=1 gives
+ * pure relevance ranking; λ=0 gives pure novelty.
+ *
+ * Two similarity sources are supported on the candidate objects:
+ *   - `embedding` (Array | Float32Array) — cosine similarity to the query
+ *     embedding (passed via opts.queryEmbedding) and to other candidates'
+ *     embeddings. Highest fidelity.
+ *   - text fallback — Jaccard similarity over tokenized title+body when no
+ *     embedding is available. Path for callers not yet on the engine surface.
+ *
+ * The function returns at most `topK` items in MMR order with a `.mmrScore`
+ * field added. Callers using this purely for deduplication can pass
+ * `topK = candidates.length` to keep all items but reorder for diversity.
+ */
+
+import { tokenize, cosineSimilarity } from '../storage/embeddings.mjs';
+
+function jaccard(a, b) {
+  if (!a || !b) return 0;
+  const setA = new Set(tokenize(`${a.title || ''} ${a.body || ''}`));
+  const setB = new Set(tokenize(`${b.title || ''} ${b.body || ''}`));
+  if (setA.size === 0 || setB.size === 0) return 0;
+  let intersect = 0;
+  for (const t of setA) if (setB.has(t)) intersect++;
+  return intersect / (setA.size + setB.size - intersect);
+}
+
+function similarity(a, b) {
+  if (a?.embedding && b?.embedding) {
+    return cosineSimilarity(a.embedding, b.embedding);
+  }
+  return jaccard(a, b);
+}
+
+function relevance(candidate, queryEmbedding) {
+  if (queryEmbedding && candidate?.embedding) {
+    return cosineSimilarity(queryEmbedding, candidate.embedding);
+  }
+  return candidate?.score ?? 0;
+}
+
+export function create({ lambda = 0.7 } = {}) {
+  return {
+    meta: { id: 'mmr', lambda },
+    async rerank(query, candidates, opts = {}) {
+      if (!Array.isArray(candidates) || candidates.length === 0) return [];
+      const lambdaEff = opts.lambda ?? lambda;
+      const topK = opts.topK ?? candidates.length;
+      const queryEmbedding = opts.queryEmbedding || null;
+
+      const remaining = [...candidates];
+      const selected = [];
+
+      while (selected.length < topK && remaining.length > 0) {
+        let bestIndex = 0;
+        let bestScore = -Infinity;
+
+        for (let i = 0; i < remaining.length; i++) {
+          const cand = remaining[i];
+          const rel = relevance(cand, queryEmbedding);
+          let maxSim = 0;
+          for (const sel of selected) {
+            const s = similarity(cand, sel);
+            if (s > maxSim) maxSim = s;
+          }
+          const score = lambdaEff * rel - (1 - lambdaEff) * maxSim;
+          if (score > bestScore) {
+            bestScore = score;
+            bestIndex = i;
+          }
+        }
+
+        const [chosen] = remaining.splice(bestIndex, 1);
+        selected.push({ ...chosen, mmrScore: bestScore });
+      }
+
+      return selected;
+    },
+  };
+}
+
+export default create;

package/lib/engine/tokens.mjs

@@ -0,0 +1,77 @@
+/**
+ * lib/engine/tokens.mjs — Accurate token counting with a graceful fallback.
+ *
+ * Wraps the `tiktoken` package when it's installed and reachable; otherwise
+ * falls back to the conventional `chars/4` approximation that the codebase
+ * has used historically. Operators that care about precise budgets should
+ * `npm install tiktoken` and the wrapper will pick it up automatically.
+ *
+ * The module is intentionally async-first: tiktoken's encoder loads its
+ * BPE table lazily, so the surface stays uniform whether tiktoken is present
+ * or not. Synchronous estimation is available via `estimateChars`.
+ *
+ * The module is the C6 pin-point for the rebuild plan: callers that enforce
+ * a token budget should call `countTokens(text)` and fail closed if the
+ * resulting count exceeds the budget. Without tiktoken, the count is an
+ * estimate; we don't lie about that — the returned object includes a
+ * `mode: 'tiktoken' | 'estimate'` field so callers can decide whether the
+ * approximation is acceptable for their use case.
+ */
+
+let encoderPromise = null;
+let encoderUnavailable = false;
+
+const APPROX_CHARS_PER_TOKEN = 4;
+
+/**
+ * Synchronous estimator. Always succeeds, never as accurate as tiktoken.
+ *
+ * @param {string} text
+ * @returns {number} estimated token count
+ */
+export function estimateChars(text) {
+  return Math.ceil(String(text || '').length / APPROX_CHARS_PER_TOKEN);
+}
+
+async function getEncoder() {
+  if (encoderUnavailable) return null;
+  if (encoderPromise) return encoderPromise;
+  encoderPromise = (async () => {
+    try {
+      const mod = await import('tiktoken');
+      const enc = (mod.encoding_for_model || mod.default?.encoding_for_model)?.('gpt-4o-mini')
+        ?? (mod.get_encoding || mod.default?.get_encoding)?.('cl100k_base');
+      if (!enc) throw new Error('tiktoken module did not expose a recognised factory');
+      return enc;
+    } catch {
+      encoderUnavailable = true;
+      return null;
+    }
+  })();
+  return encoderPromise;
+}
+
+/**
+ * Async accurate counter. Returns `{ tokens, mode }`.
+ *
+ * @param {string} text
+ * @returns {Promise<{ tokens: number, mode: 'tiktoken' | 'estimate' }>}
+ */
+export async function countTokens(text) {
+  const enc = await getEncoder();
+  if (!enc) return { tokens: estimateChars(text), mode: 'estimate' };
+  try {
+    const ids = enc.encode(String(text || ''));
+    return { tokens: ids.length, mode: 'tiktoken' };
+  } catch {
+    return { tokens: estimateChars(text), mode: 'estimate' };
+  }
+}
+
+/**
+ * Drop the cached encoder — test hook for re-running after toggling availability.
+ */
+export function _resetEncoderForTests() {
+  encoderPromise = null;
+  encoderUnavailable = false;
+}

package/lib/entity-store.mjs

@@ -0,0 +1,280 @@
+/**
+ * lib/entity-store.mjs — Entity tracking for the observation store.
+ *
+ * Tracks recurring entities (components, services, APIs, dependencies)
+ * that specialists encounter across sessions. Links entities to
+ * observations for "what do we know about X?" queries.
+ *
+ * Storage: .cx/observations/entities.json — flat JSON array.
+ *          .cx/observations/entity-vectors.json — vector index for semantic search.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { cosineSimilarity, rankByBm25 } from './storage/embeddings.mjs';
+import { embedSync as embedText } from './storage/embeddings-legacy.mjs';
+import { withFileLockSync } from './storage/file-lock.mjs';
+
+const OBS_DIR = '.cx/observations';
+const ENTITIES_FILE = 'entities.json';
+const ENTITY_VECTORS_FILE = 'entity-vectors.json';
+const MAX_ENTITIES = 500;
+const MAX_SUMMARY = 500;
+const MAX_OBSERVATIONS_PER_ENTITY = 50;
+const MAX_RELATED = 20;
+
+const VALID_TYPES = new Set([
+  'component', 'service', 'dependency', 'api', 'concept', 'file-group',
+]);
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function entitiesPath(rootDir) {
+  return path.join(rootDir, OBS_DIR, ENTITIES_FILE);
+}
+
+function entityVectorsPath(rootDir) {
+  return path.join(rootDir, OBS_DIR, ENTITY_VECTORS_FILE);
+}
+
+function readEntityVectors(rootDir) {
+  const p = entityVectorsPath(rootDir);
+  if (!fs.existsSync(p)) return [];
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return []; }
+}
+
+function writeEntityVectors(rootDir, records) {
+  ensureDir(path.join(rootDir, OBS_DIR));
+  const target = entityVectorsPath(rootDir);
+  withFileLockSync(target, () => {
+    fs.writeFileSync(target, JSON.stringify(records.slice(0, MAX_ENTITIES), null, 2) + '\n');
+  });
+}
+
+function buildEntitySearchText(entity) {
+  return [entity.name, entity.summary, entity.type].filter(Boolean).join(' ');
+}
+
+function upsertEntityVector(rootDir, entity) {
+  const text = buildEntitySearchText(entity);
+  if (!text) return;
+  const embedding = embedText(text);
+  const vectors = readEntityVectors(rootDir);
+  const idx = vectors.findIndex((v) => v.name === entity.name);
+  const record = { name: entity.name, embedding, type: entity.type || null, project: entity.project || null };
+  if (idx >= 0) vectors[idx] = record;
+  else vectors.unshift(record);
+  writeEntityVectors(rootDir, vectors);
+}
+
+function clamp(str, max) {
+  if (!str || str.length <= max) return str || null;
+  return str.slice(0, max - 1) + '\u2026';
+}
+
+function readEntities(rootDir) {
+  const p = entitiesPath(rootDir);
+  if (!fs.existsSync(p)) return [];
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return [];
+  }
+}
+
+function writeEntities(rootDir, entities) {
+  ensureDir(path.join(rootDir, OBS_DIR));
+  const trimmed = entities.slice(0, MAX_ENTITIES);
+  const target = entitiesPath(rootDir);
+  withFileLockSync(target, () => {
+    fs.writeFileSync(target, JSON.stringify(trimmed, null, 2) + '\n');
+  });
+}
+
+/**
+ * Create or update an entity. If an entity with the same name exists,
+ * its summary and type are updated; observations are merged.
+ */
+export function createEntity(rootDir, {
+  name = '',
+  type = 'concept',
+  summary = '',
+  project = null,
+  observationIds = [],
+} = {}) {
+  if (!name) return null;
+
+  const entities = readEntities(rootDir);
+  const effectiveType = VALID_TYPES.has(type) ? type : 'concept';
+  const now = new Date().toISOString();
+  const normalizedName = String(name).trim().toLowerCase();
+
+  const existing = entities.find((e) => e.name === normalizedName);
+
+  if (existing) {
+    existing.type = effectiveType;
+    existing.summary = clamp(String(summary || existing.summary), MAX_SUMMARY);
+    existing.lastSeen = now;
+    if (project) existing.project = String(project);
+
+    const ids = new Set(existing.observations || []);
+    for (const id of observationIds) ids.add(String(id));
+    existing.observations = [...ids].slice(0, MAX_OBSERVATIONS_PER_ENTITY);
+
+    writeEntities(rootDir, entities);
+    upsertEntityVector(rootDir, existing);
+    return existing;
+  }
+
+  const entity = {
+    name: normalizedName,
+    type: effectiveType,
+    summary: clamp(String(summary), MAX_SUMMARY),
+    observations: (Array.isArray(observationIds) ? observationIds : [])
+      .map(String)
+      .slice(0, MAX_OBSERVATIONS_PER_ENTITY),
+    relatedEntities: [],
+    project: project ? String(project) : null,
+    lastSeen: now,
+    createdAt: now,
+  };
+
+  entities.unshift(entity);
+  writeEntities(rootDir, entities);
+  upsertEntityVector(rootDir, entity);
+  return entity;
+}
+
+/**
+ * Link an observation ID to an existing entity.
+ */
+export function addObservationToEntity(rootDir, entityName, observationId) {
+  const entities = readEntities(rootDir);
+  const normalizedName = String(entityName).trim().toLowerCase();
+  const entity = entities.find((e) => e.name === normalizedName);
+  if (!entity) return null;
+
+  const ids = new Set(entity.observations || []);
+  ids.add(String(observationId));
+  entity.observations = [...ids].slice(0, MAX_OBSERVATIONS_PER_ENTITY);
+  entity.lastSeen = new Date().toISOString();
+
+  writeEntities(rootDir, entities);
+  return entity;
+}
+
+/**
+ * Add a related entity link (bidirectional).
+ */
+export function addRelatedEntity(rootDir, entityNameA, entityNameB) {
+  const entities = readEntities(rootDir);
+  const nameA = String(entityNameA).trim().toLowerCase();
+  const nameB = String(entityNameB).trim().toLowerCase();
+  if (nameA === nameB) return null;
+
+  const entityA = entities.find((e) => e.name === nameA);
+  const entityB = entities.find((e) => e.name === nameB);
+
+  if (entityA) {
+    const related = new Set(entityA.relatedEntities || []);
+    related.add(nameB);
+    entityA.relatedEntities = [...related].slice(0, MAX_RELATED);
+  }
+  if (entityB) {
+    const related = new Set(entityB.relatedEntities || []);
+    related.add(nameA);
+    entityB.relatedEntities = [...related].slice(0, MAX_RELATED);
+  }
+
+  writeEntities(rootDir, entities);
+  return { a: entityA, b: entityB };
+}
+
+/**
+ * Search entities by keyword in name, summary, or type.
+ */
+export function searchEntities(rootDir, query, { type = null, project = null } = {}) {
+  if (!query) return [];
+  const lower = String(query).toLowerCase();
+
+  let entities = readEntities(rootDir);
+  if (type) entities = entities.filter((e) => e.type === type);
+  if (project) entities = entities.filter((e) => e.project === project);
+
+  const vectors = readEntityVectors(rootDir);
+  if (vectors.length === 0) {
+    return entities.filter((e) =>
+      (e.name && e.name.includes(lower)) ||
+      (e.summary && e.summary.toLowerCase().includes(lower)) ||
+      (e.type && e.type.includes(lower)),
+    );
+  }
+
+  const queryEmbedding = embedText(String(query));
+  const filteredVectors = vectors.filter((v) =>
+    (!type || v.type === type) && (!project || v.project === project)
+  );
+
+  const cosineScored = filteredVectors
+    .map((v) => ({ name: v.name, score: cosineSimilarity(queryEmbedding, v.embedding || []) }))
+    .filter(({ score }) => score > 0.05);
+
+  const candidateNames = new Set(cosineScored.map((v) => v.name));
+  for (const e of entities) {
+    if ((e.name && e.name.includes(lower)) ||
+        (e.summary && e.summary.toLowerCase().includes(lower)) ||
+        (e.type && e.type.includes(lower))) {
+      candidateNames.add(e.name);
+    }
+  }
+
+  const candidates = [...candidateNames]
+    .map((name) => entities.find((e) => e.name === name))
+    .filter(Boolean)
+    .map((e) => ({ ...e, text: buildEntitySearchText(e) }));
+
+  const bm25Scored = rankByBm25(candidates, query, { limit: 20 });
+  const bm25Max = bm25Scored[0]?.score || 1;
+
+  const scoreMap = new Map();
+  for (const { name, score } of cosineScored) scoreMap.set(name, score);
+  for (const item of bm25Scored) {
+    const prev = scoreMap.get(item.name) || 0;
+    scoreMap.set(item.name, Math.max(prev, Math.min(item.score / bm25Max, 1)));
+  }
+
+  return [...scoreMap.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .map(([name]) => entities.find((e) => e.name === name))
+    .filter(Boolean);
+}
+
+/**
+ * Get a single entity by name.
+ */
+export function getEntity(rootDir, name) {
+  const normalizedName = String(name).trim().toLowerCase();
+  const entities = readEntities(rootDir);
+  return entities.find((e) => e.name === normalizedName) || null;
+}
+
+/**
+ * List all entities with optional filters.
+ */
+export function listEntities(rootDir, { type = null, project = null, limit = 50 } = {}) {
+  let entities = readEntities(rootDir);
+  if (type) entities = entities.filter((e) => e.type === type);
+  if (project) entities = entities.filter((e) => e.project === project);
+  return entities.slice(0, limit);
+}
+
+/**
+ * Count entities.
+ */
+export function countEntities(rootDir, { type = null, project = null } = {}) {
+  let entities = readEntities(rootDir);
+  if (type) entities = entities.filter((e) => e.type === type);
+  if (project) entities = entities.filter((e) => e.project === project);
+  return entities.length;
+}