session-orchestrator 3.16.0

package/scripts/lib/language-mappers/typescript.mjs

@@ -0,0 +1,433 @@
+/**
+ * language-mappers/typescript.mjs — Semantic slice extractor for TypeScript/JS.
+ *
+ * Uses @babel/parser (lazy import) to parse the file into an AST and walk
+ * top-level declarations.  Emits SemanticSlice records for:
+ *   function  — FunctionDeclaration
+ *   class     — ClassDeclaration (+ nested method slices)
+ *   interface — TSInterfaceDeclaration
+ *   type      — TSTypeAliasDeclaration
+ *   export    — ExportNamedDeclaration without an inner declaration
+ *
+ * Part of the Clawpatch Borrow Cluster (issue #416).
+ */
+
+// ---------------------------------------------------------------------------
+// Types (JSDoc only — no runtime overhead)
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {{
+ *   kind: 'function'|'class'|'interface'|'type'|'export'|'section';
+ *   name: string;
+ *   file: string;
+ *   line: number;
+ *   endLine: number;
+ *   exported: boolean;
+ *   isNested: boolean;
+ *   fidelity: 'regex'|'ast';
+ *   params?: string[];
+ *   doc?: string;
+ *   source?: string;
+ * }} SemanticSlice
+ */
+
+// All slices produced by this mapper carry fidelity:'ast' (#474 MED-3) —
+// they come from a real @babel/parser AST walk, not regex matching.
+const FIDELITY = /** @type {'ast'} */ ('ast');
+
+// ---------------------------------------------------------------------------
+// Babel parser options
+// ---------------------------------------------------------------------------
+
+const BABEL_OPTIONS = {
+  sourceType: 'module',
+  strictMode: false,
+  plugins: [
+    'typescript',
+    'jsx',
+    'decorators-legacy',
+    'classProperties',
+    'classStaticBlock',
+    'exportDefaultFrom',
+    'importMeta',
+  ],
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract parameter names from a Babel FunctionDeclaration / FunctionExpression
+ * params array.  Returns an array of identifier name strings (skips patterns).
+ *
+ * @param {Array<object>} params
+ * @returns {string[]}
+ */
+function extractParamNames(params) {
+  return params.flatMap((p) => {
+    if (p.type === 'Identifier') return [p.name];
+    if (p.type === 'AssignmentPattern' && p.left?.type === 'Identifier') return [p.left.name];
+    if (p.type === 'RestElement' && p.argument?.type === 'Identifier')
+      return [`...${p.argument.name}`];
+    if (p.type === 'TSParameterProperty' && p.parameter?.type === 'Identifier')
+      return [p.parameter.name];
+    return [];
+  });
+}
+
+/**
+ * Extract a leading comment string from the node's `leadingComments` if present.
+ *
+ * @param {object} node
+ * @returns {string|undefined}
+ */
+function extractDoc(node) {
+  const comments = node.leadingComments;
+  if (!Array.isArray(comments) || comments.length === 0) return undefined;
+  const last = comments[comments.length - 1];
+  if (!last) return undefined;
+  const raw = last.value ?? '';
+  // Strip leading * characters (JSDoc style) and trim
+  return raw
+    .split('\n')
+    .map((l) => l.replace(/^\s*\*\s?/, '').trim())
+    .filter(Boolean)
+    .join(' ')
+    .trim() || undefined;
+}
+
+/**
+ * Safe node location accessor — returns {startLine, endLine} or {1, 1} on miss.
+ *
+ * @param {object} node
+ * @returns {{ startLine: number; endLine: number }}
+ */
+function nodeLoc(node) {
+  const start = node?.loc?.start?.line ?? 1;
+  const end = node?.loc?.end?.line ?? start;
+  return { startLine: start, endLine: end };
+}
+
+// ---------------------------------------------------------------------------
+// AST walker
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk a single statement and emit SemanticSlice records into `out`.
+ *
+ * @param {object} stmt       AST statement node
+ * @param {string} filePath   Source file path
+ * @param {boolean} exported  Whether this stmt is inside an ExportDeclaration
+ * @param {SemanticSlice[]} out
+ */
+function walkStatement(stmt, filePath, exported, out) {
+  if (!stmt || typeof stmt !== 'object') return;
+
+  switch (stmt.type) {
+    case 'ExportNamedDeclaration': {
+      const inner = stmt.declaration;
+      if (inner) {
+        // Has a nested declaration — delegate but mark as exported
+        walkStatement(inner, filePath, true, out);
+      } else {
+        // Re-export or `export { foo }` without a declaration.
+        // Note: `export * as ns from 'x'` lands here too (ExportNamespaceSpecifier).
+        const { startLine, endLine } = nodeLoc(stmt);
+        const source = stmt.source?.value;
+        // Collect specifier names
+        const names = (stmt.specifiers ?? []).map((s) => s.exported?.name ?? s.local?.name ?? '?');
+        if (names.length > 0) {
+          for (const name of names) {
+            out.push({
+              kind: 'export',
+              name,
+              file: filePath,
+              line: startLine,
+              endLine,
+              exported: true,
+              isNested: false,
+              fidelity: FIDELITY,
+              ...(source !== undefined ? { source } : {}),
+            });
+          }
+        } else {
+          // Empty specifiers with a source (rare: `export {} from 'x'`)
+          out.push({
+            kind: 'export',
+            name: source ?? '<re-export>',
+            file: filePath,
+            line: startLine,
+            endLine,
+            exported: true,
+            isNested: false,
+            fidelity: FIDELITY,
+            ...(source !== undefined ? { source } : {}),
+          });
+        }
+      }
+      break;
+    }
+
+    case 'ExportAllDeclaration': {
+      // `export * from './x'`            → stmt.exported = null, name '*'
+      // `export * as ns from './x'`      → stmt.exported = { name: 'ns' }
+      const { startLine, endLine } = nodeLoc(stmt);
+      out.push({
+        kind: 'export',
+        name: stmt.exported?.name ?? '*',
+        file: filePath,
+        line: startLine,
+        endLine,
+        exported: true,
+        isNested: false,
+        fidelity: FIDELITY,
+        source: stmt.source?.value ?? '<unknown>',
+      });
+      break;
+    }
+
+    case 'ExportDefaultDeclaration': {
+      const inner = stmt.declaration;
+      const { startLine, endLine } = nodeLoc(stmt);
+      if (inner && (inner.type === 'FunctionDeclaration' || inner.type === 'FunctionExpression')) {
+        const name = inner.id?.name ?? '<default>';
+        out.push({
+          kind: 'function',
+          name,
+          file: filePath,
+          line: startLine,
+          endLine,
+          exported: true,
+          isNested: false,
+          fidelity: FIDELITY,
+          params: extractParamNames(inner.params ?? []),
+          doc: extractDoc(stmt),
+        });
+      } else if (inner && (inner.type === 'ClassDeclaration' || inner.type === 'ClassExpression')) {
+        const name = inner.id?.name ?? '<default>';
+        out.push({
+          kind: 'class',
+          name,
+          file: filePath,
+          line: startLine,
+          endLine,
+          exported: true,
+          isNested: false,
+          fidelity: FIDELITY,
+          params: extractClassMethods(inner),
+          doc: extractDoc(stmt),
+        });
+        walkClassMethods(inner, filePath, out);
+      } else {
+        // Arrow function, expression, etc.
+        const innerName =
+          inner?.id?.name ?? (inner?.type === 'ArrowFunctionExpression' ? '<arrow>' : '<default>');
+        out.push({
+          kind: 'export',
+          name: innerName,
+          file: filePath,
+          line: startLine,
+          endLine,
+          exported: true,
+          isNested: false,
+          fidelity: FIDELITY,
+          doc: extractDoc(stmt),
+        });
+      }
+      break;
+    }
+
+    case 'FunctionDeclaration': {
+      if (!stmt.id) break; // anonymous
+      const { startLine, endLine } = nodeLoc(stmt);
+      out.push({
+        kind: 'function',
+        name: stmt.id.name,
+        file: filePath,
+        line: startLine,
+        endLine,
+        exported,
+        isNested: false,
+        fidelity: FIDELITY,
+        params: extractParamNames(stmt.params ?? []),
+        doc: extractDoc(stmt),
+      });
+      break;
+    }
+
+    case 'ClassDeclaration': {
+      if (!stmt.id) break;
+      const { startLine, endLine } = nodeLoc(stmt);
+      out.push({
+        kind: 'class',
+        name: stmt.id.name,
+        file: filePath,
+        line: startLine,
+        endLine,
+        exported,
+        isNested: false,
+        fidelity: FIDELITY,
+        params: extractClassMethods(stmt),
+        doc: extractDoc(stmt),
+      });
+      walkClassMethods(stmt, filePath, out);
+      break;
+    }
+
+    case 'TSInterfaceDeclaration': {
+      const { startLine, endLine } = nodeLoc(stmt);
+      const name = stmt.id?.name ?? '<interface>';
+      out.push({
+        kind: 'interface',
+        name,
+        file: filePath,
+        line: startLine,
+        endLine,
+        exported,
+        isNested: false,
+        fidelity: FIDELITY,
+        doc: extractDoc(stmt),
+      });
+      break;
+    }
+
+    case 'TSTypeAliasDeclaration': {
+      const { startLine, endLine } = nodeLoc(stmt);
+      const name = stmt.id?.name ?? '<type>';
+      out.push({
+        kind: 'type',
+        name,
+        file: filePath,
+        line: startLine,
+        endLine,
+        exported,
+        isNested: false,
+        fidelity: FIDELITY,
+        doc: extractDoc(stmt),
+      });
+      break;
+    }
+
+    // Variable declarations: const foo = () => {} or const foo = function() {}
+    case 'VariableDeclaration': {
+      for (const decl of stmt.declarations ?? []) {
+        if (!decl.id || decl.id.type !== 'Identifier') continue;
+        const init = decl.init;
+        if (!init) continue;
+        if (
+          init.type === 'ArrowFunctionExpression' ||
+          init.type === 'FunctionExpression'
+        ) {
+          const { startLine, endLine } = nodeLoc(stmt);
+          out.push({
+            kind: 'function',
+            name: decl.id.name,
+            file: filePath,
+            line: startLine,
+            endLine,
+            exported,
+            isNested: false,
+            fidelity: FIDELITY,
+            params: extractParamNames(init.params ?? []),
+            doc: extractDoc(stmt),
+          });
+        }
+      }
+      break;
+    }
+
+    default:
+      break;
+  }
+}
+
+/**
+ * Extract method names from a ClassDeclaration body.
+ *
+ * @param {object} classNode
+ * @returns {string[]}
+ */
+function extractClassMethods(classNode) {
+  const body = classNode?.body?.body ?? [];
+  return body
+    .filter((m) => m.type === 'ClassMethod' || m.type === 'ClassPrivateMethod')
+    .map((m) => {
+      if (m.key?.type === 'Identifier') return m.key.name;
+      if (m.key?.type === 'StringLiteral') return m.key.value;
+      return '<method>';
+    });
+}
+
+/**
+ * Walk class body and emit nested method slices.
+ *
+ * @param {object} classNode
+ * @param {string} filePath
+ * @param {SemanticSlice[]} out
+ */
+function walkClassMethods(classNode, filePath, out) {
+  const body = classNode?.body?.body ?? [];
+  for (const member of body) {
+    if (member.type !== 'ClassMethod' && member.type !== 'ClassPrivateMethod') continue;
+    const { startLine, endLine } = nodeLoc(member);
+    let name;
+    if (member.key?.type === 'Identifier') {
+      name = member.key.name;
+    } else if (member.key?.type === 'StringLiteral') {
+      name = member.key.value;
+    } else {
+      name = '<method>';
+    }
+    out.push({
+      kind: 'function',
+      name,
+      file: filePath,
+      line: startLine,
+      endLine,
+      exported: false,
+      isNested: true,
+      fidelity: FIDELITY,
+      params: extractParamNames(member.params ?? []),
+      doc: extractDoc(member),
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract semantic slices from TypeScript/JavaScript source.
+ *
+ * @param {string} filePath  Source file path (used only for the slice `file` field).
+ * @param {string} content   Raw source text.
+ * @returns {Promise<SemanticSlice[]>}
+ */
+export async function extractTypeScriptSlices(filePath, content) {
+  if (!content.trim()) return [];
+
+  const { parse } = await import('@babel/parser');
+
+  let ast;
+  try {
+    ast = parse(content, BABEL_OPTIONS);
+  } catch (err) {
+    throw new Error(
+      `extractTypeScriptSlices: parse error in '${filePath}': ${err.message}`,
+      { cause: err },
+    );
+  }
+
+  const body = ast?.program?.body ?? [];
+  /** @type {SemanticSlice[]} */
+  const slices = [];
+
+  for (const stmt of body) {
+    walkStatement(stmt, filePath, false, slices);
+  }
+
+  return slices;
+}

package/scripts/lib/learnings/expiry-sweep.mjs

@@ -0,0 +1,164 @@
+/**
+ * learnings/expiry-sweep.mjs — mechanical expiry/archive sweep for learnings.jsonl.
+ *
+ * Epic #723 B4. Fleet audit found expired-resident learnings accumulating in
+ * 6+ repos (Vault: 70% expired) because nothing MECHANICALLY moves expired
+ * entries out of the active store — `memory-cleanup-soft-limit` and the
+ * `evolve` confidence-decay pass both operate on the live store but never
+ * relocate anything. This module is the missing mechanical sweep: it
+ * partitions `learnings.jsonl` into KEEP (still active, or too-recently
+ * expired to move yet) and ARCHIVE (expired past the grace window), appends
+ * the archive candidates to an append-only sidecar, then rewrites the store
+ * with only the KEEP set.
+ *
+ * Design constraints (deliberate, do not "simplify" away):
+ *   - NEVER deletes data. Archive is append-only; the store rewrite is the
+ *     ONLY destructive step, and it reuses `rewriteLearnings()` from io.mjs
+ *     (#721), which itself snapshots a `.bak-<ISO>` backup before the atomic
+ *     rename — the same safety net that protects every other bulk rewrite.
+ *   - Grace period (default 14 days): an entry that JUST expired stays in the
+ *     active store for `graceDays` more days. This absorbs two things: (a)
+ *     TTL edge-noise near the boundary, and (b) a window for /evolve's
+ *     confidence-reinforcement pass to re-stamp `expires_at` before the entry
+ *     is moved out from under it. Without the grace window, a recurring
+ *     learning could ping-pong between store and archive on every sweep.
+ *   - Crash-safe ordering: the archive APPEND happens before the store
+ *     REWRITE. A crash between the two steps leaves the entry in BOTH places
+ *     (harmless — the archive is append-only and never de-duplicated on
+ *     read) rather than in NEITHER (data loss, if the rewrite completed but
+ *     the archive append had not yet happened).
+ *   - KEEP-batch validated BEFORE the archive append: a `rewriteLearnings(...,
+ *     { dryRun: true })` probe validates the KEEP set (throws on an
+ *     invalid-but-parseable record) with zero disk writes. Without this
+ *     probe, an invalid KEEP record would survive `readLearnings()` only to
+ *     blow up the REAL rewrite AFTER the archive append had already landed —
+ *     on a repeated `--apply` run that duplicates the archive append every
+ *     time while the store is never actually pruned.
+ *   - Read/normalize is delegated to `readLearnings()`; the destructive
+ *     rewrite is delegated to `rewriteLearnings()`. This file does not
+ *     implement its own JSONL writer for the store — see io.mjs #721
+ *     (the incident that destroyed 107 live learnings via a bespoke writer
+ *     with no backup/dry-run safety net).
+ *
+ * Sibling-module import convention (learnings.mjs barrel doc): import
+ * directly from `./io.mjs`, never from `../learnings.mjs`, to preserve the
+ * acyclic dependency graph.
+ */
+
+import { existsSync } from 'node:fs';
+import { mkdir, appendFile } from 'node:fs/promises';
+import path from 'node:path';
+import { readLearnings, rewriteLearnings } from './io.mjs';
+
+const MS_PER_DAY = 86_400_000;
+const DEFAULT_GRACE_DAYS = 14;
+
+/**
+ * Sweep expired learnings out of `filePath` into `archivePath`.
+ *
+ * Partition rule (relative to `now`):
+ *   - KEEP:    `expires_at` unparseable/absent, OR not yet expired, OR expired
+ *              but within `graceDays` of expiry (grace window).
+ *   - ARCHIVE: `expires_at` parseable AND expired AND
+ *              `expiresMs + graceDays*86400000 < now` (grace window elapsed).
+ *
+ * @param {object} opts
+ * @param {string} opts.filePath - absolute/relative path to the active learnings.jsonl
+ * @param {string} opts.archivePath - absolute/relative path to the append-only archive sidecar
+ * @param {Date|number} [opts.now] - injectable clock; defaults to `Date.now()`
+ * @param {boolean} [opts.dryRun=true] - when true, computes counts but writes nothing
+ * @param {number} [opts.graceDays=14] - days past expiry before an entry is archived
+ * @returns {Promise<{scanned: number, kept: number, archived: number, dryRun: boolean, archivePath: string}>}
+ *   Never throws on a missing store — returns the zeroed shape instead. Both
+ *   `filePath` and `archivePath` are required; a missing/invalid `filePath`
+ *   throws a plain `Error` (programmer error, not a runtime data condition).
+ */
+export async function sweepExpiredLearnings({
+  filePath,
+  archivePath,
+  now,
+  dryRun = true,
+  graceDays = DEFAULT_GRACE_DAYS,
+} = {}) {
+  if (typeof filePath !== 'string' || filePath.length === 0) {
+    throw new Error('sweepExpiredLearnings: filePath is required');
+  }
+  if (typeof archivePath !== 'string' || archivePath.length === 0) {
+    throw new Error('sweepExpiredLearnings: archivePath is required');
+  }
+
+  if (!existsSync(filePath)) {
+    return { scanned: 0, kept: 0, archived: 0, dryRun, archivePath };
+  }
+
+  const nowMs =
+    now instanceof Date ? now.getTime() : typeof now === 'number' ? now : Date.now();
+  const graceMs =
+    (Number.isFinite(graceDays) && graceDays >= 0 ? graceDays : DEFAULT_GRACE_DAYS) * MS_PER_DAY;
+
+  const { entries } = await readLearnings(filePath);
+
+  const keep = [];
+  const archiveCandidates = [];
+
+  for (const entry of entries) {
+    const expiresMs = typeof entry?.expires_at === 'string' ? Date.parse(entry.expires_at) : NaN;
+    const isExpired = Number.isFinite(expiresMs) && expiresMs <= nowMs;
+    if (!isExpired) {
+      keep.push(entry);
+      continue;
+    }
+    // Expired — but does it clear the grace window?
+    if (expiresMs + graceMs < nowMs) {
+      archiveCandidates.push(entry);
+    } else {
+      keep.push(entry);
+    }
+  }
+
+  if (dryRun) {
+    return {
+      scanned: entries.length,
+      kept: keep.length,
+      archived: archiveCandidates.length,
+      dryRun: true,
+      archivePath,
+    };
+  }
+
+  // Validate the KEEP batch BEFORE the archive append (dry-run rewrite: throws
+  // on a bad record, writes nothing). Without this, an invalid-but-parseable
+  // KEEP record survives readLearnings() but blows up rewriteLearnings() later
+  // — AFTER the archive append already landed. On a repeated --apply run that
+  // duplicates the archive append every time (never de-duplicated on read)
+  // while the store is never actually pruned. Validating first means a bad
+  // record throws here, before anything on disk has been touched.
+  await rewriteLearnings(filePath, keep, { dryRun: true });
+
+  // Crash-safe ordering: archive append FIRST. A duplicate re-append after a
+  // crash is harmless (append-only, never de-duplicated on read); the reverse
+  // order risks losing an archive-worthy entry if the process dies after the
+  // store rewrite but before the archive write.
+  if (archiveCandidates.length > 0) {
+    const nowIso = new Date(nowMs).toISOString();
+    const body =
+      archiveCandidates
+        .map((e) => JSON.stringify({ ...e, _archived_at: nowIso, _archive_reason: 'expired' }))
+        .join('\n') + '\n';
+    await mkdir(path.dirname(archivePath), { recursive: true });
+    await appendFile(archivePath, body, 'utf8');
+  }
+
+  // Re-validates (cheap, idempotent) and snapshots a `.bak-<ISO>` backup of
+  // the current store before the atomic rename (io.mjs #721). The KEEP batch
+  // already passed the dry-run probe above, so this call cannot throw here.
+  await rewriteLearnings(filePath, keep, { dryRun: false });
+
+  return {
+    scanned: entries.length,
+    kept: keep.length,
+    archived: archiveCandidates.length,
+    dryRun: false,
+    archivePath,
+  };
+}

package/scripts/lib/learnings/filters.mjs

@@ -0,0 +1,43 @@
+/**
+ * learnings/filters.mjs — filtering helpers for learnings entries.
+ *
+ * Extracted from scripts/lib/learnings.mjs (issue #358).
+ * Depends on normalizeLearning from the schema layer in the parent module.
+ */
+
+import { normalizeLearning } from './schema.mjs';
+
+// ---------------------------------------------------------------------------
+// Filtering helpers (used by C3 export + /evolve hardware-pattern queries)
+// ---------------------------------------------------------------------------
+
+/**
+ * Filter learnings by scope. Returns a new array.
+ * @param {object[]} entries
+ * @param {string|string[]} scope
+ * @returns {object[]}
+ */
+export function filterByScope(entries, scope) {
+  const scopes = Array.isArray(scope) ? scope : [scope];
+  return entries.filter((e) => scopes.includes(normalizeLearning(e).scope));
+}
+
+/**
+ * Filter learnings by host_class. Returns a new array.
+ * @param {object[]} entries
+ * @param {string} hostClass
+ * @returns {object[]}
+ */
+export function filterByHostClass(entries, hostClass) {
+  return entries.filter((e) => normalizeLearning(e).host_class === hostClass);
+}
+
+/**
+ * Filter learnings by type.
+ * @param {object[]} entries
+ * @param {string} type
+ * @returns {object[]}
+ */
+export function filterByType(entries, type) {
+  return entries.filter((e) => e.type === type);
+}