session-orchestrator 3.16.0

package/scripts/lib/issue-close-strip-labels.mjs

@@ -0,0 +1,161 @@
+/**
+ * issue-close-strip-labels.mjs
+ *
+ * Auto-strips `status:*` workflow labels from an issue before it is closed.
+ * A closed issue carrying `status:in-progress` or `status:ready` is misleading
+ * because close already implies the work is done.
+ *
+ * Design notes:
+ *   - Stdlib only. Shells out via `execFileSync` (argv-array form — no shell
+ *     interpolation, safe for label values with special chars).
+ *   - Fetches current labels via JSON output, filters for `status:*`, runs the
+ *     strip only when at least one match is found (idempotent no-op otherwise).
+ *   - Returns the array of stripped label names (empty array = no-op).
+ *   - Never throws — all errors are caught and returned as `{ stripped: [],
+ *     error: string }` so callers can log and proceed with close unblocked.
+ *   - Supports GitLab (`glab`) and GitHub (`gh`). VCS is a required param.
+ *
+ * Usage (from session-end Phase 5 issue-close loop):
+ *
+ *   import { stripStatusLabels } from '${PLUGIN_ROOT}/scripts/lib/issue-close-strip-labels.mjs';
+ *
+ *   const { stripped, error } = await stripStatusLabels({ issueId: 42, vcs: 'gitlab' });
+ *   if (error) console.warn(`⚠ label strip failed for #${issueId}: ${error}`);
+ *   else if (stripped.length) console.log(`Stripped ${stripped.join(', ')} from #${issueId}`);
+ *   // then close the issue with glab/gh as usual
+ *
+ * Auto-created by `scripts/lib/issue-close-strip-labels.mjs` (#308).
+ */
+
+import { execFileSync } from 'node:child_process';
+
+/** Regex that matches any `status:*` label name. */
+const STATUS_LABEL_RE = /^status:/;
+
+/**
+ * Run a CLI command and return { ok, stdout, stderr }. Never throws.
+ *
+ * @param {string} cmd
+ * @param {string[]} args
+ * @returns {{ ok: boolean, stdout: string, stderr: string }}
+ */
+function runCli(cmd, args) {
+  try {
+    const stdout = execFileSync(cmd, args, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return { ok: true, stdout: String(stdout ?? ''), stderr: '' };
+  } catch (err) {
+    const stderr =
+      err && err.stderr ? String(err.stderr) : err && err.message ? String(err.message) : 'unknown error';
+    const stdout = err && err.stdout ? String(err.stdout) : '';
+    return { ok: false, stdout, stderr };
+  }
+}
+
+/**
+ * Fetch the label names currently applied to an issue.
+ *
+ * @param {{ issueId: number | string, vcs: 'gitlab' | 'github' }} opts
+ * @returns {{ ok: boolean, labels: string[], stderr: string }}
+ */
+function fetchLabels({ issueId, vcs }) {
+  const id = String(issueId);
+
+  if (vcs === 'github') {
+    // `gh issue view <NUMBER> --json labels` returns { labels: [{name, ...}] }
+    const res = runCli('gh', ['issue', 'view', id, '--json', 'labels']);
+    if (!res.ok) return { ok: false, labels: [], stderr: res.stderr };
+    let parsed;
+    try {
+      parsed = JSON.parse(res.stdout);
+    } catch (e) {
+      return { ok: false, labels: [], stderr: `JSON parse failed: ${e && e.message ? e.message : String(e)}` };
+    }
+    const labels = Array.isArray(parsed?.labels)
+      ? parsed.labels.map((l) => (typeof l?.name === 'string' ? l.name : String(l))).filter(Boolean)
+      : [];
+    return { ok: true, labels, stderr: '' };
+  }
+
+  // Default: gitlab via glab.
+  // `glab issue view <IID> --output json` returns an issue object with a `labels` array.
+  const res = runCli('glab', ['issue', 'view', id, '--output', 'json']);
+  if (!res.ok) return { ok: false, labels: [], stderr: res.stderr };
+  let parsed;
+  try {
+    parsed = JSON.parse(res.stdout);
+  } catch (e) {
+    return { ok: false, labels: [], stderr: `JSON parse failed: ${e && e.message ? e.message : String(e)}` };
+  }
+  // GitLab JSON shape: { labels: ["status:ready", "priority:high", ...] }
+  const labels = Array.isArray(parsed?.labels)
+    ? parsed.labels.map((l) => (typeof l === 'string' ? l : String(l))).filter(Boolean)
+    : [];
+  return { ok: true, labels, stderr: '' };
+}
+
+/**
+ * Strip all `status:*` labels from an issue.
+ *
+ * Returns the list of label names that were stripped. An empty array means the
+ * issue had no `status:*` labels (idempotent no-op — no CLI call is made for
+ * the strip step). Never throws.
+ *
+ * @param {{
+ *   issueId: number | string,
+ *   vcs?: 'gitlab' | 'github'
+ * }} opts
+ * @returns {Promise<{ stripped: string[], error?: string }>}
+ */
+export async function stripStatusLabels({ issueId, vcs = 'gitlab' } = {}) {
+  try {
+    const id = String(issueId ?? '').trim();
+    if (!id || id === 'undefined' || id === 'null') {
+      return { stripped: [], error: `invalid issueId: ${String(issueId)}` };
+    }
+
+    const vcsResolved = vcs === 'github' ? 'github' : 'gitlab';
+
+    // Step 1: fetch current labels.
+    const { ok, labels, stderr } = fetchLabels({ issueId: id, vcs: vcsResolved });
+    if (!ok) {
+      return { stripped: [], error: `failed to fetch labels: ${stderr}` };
+    }
+
+    // Step 2: filter to status:* only.
+    const toStrip = labels.filter((l) => STATUS_LABEL_RE.test(l));
+    if (toStrip.length === 0) {
+      // Idempotent no-op — no status labels present.
+      return { stripped: [] };
+    }
+
+    // Step 3: strip via CLI.
+    let stripRes;
+    if (vcsResolved === 'github') {
+      // `gh issue edit <NUMBER> --remove-label label1 --remove-label label2 ...`
+      const args = ['issue', 'edit', id];
+      for (const label of toStrip) {
+        args.push('--remove-label', label);
+      }
+      stripRes = runCli('gh', args);
+    } else {
+      // `glab issue update <IID> --unlabel label1,label2,...`
+      // glab accepts comma-separated list in a single --unlabel flag value.
+      stripRes = runCli('glab', ['issue', 'update', id, '--unlabel', toStrip.join(',')]);
+    }
+
+    if (!stripRes.ok) {
+      return {
+        stripped: [],
+        error: `label strip CLI failed: ${stripRes.stderr.trim() || 'unknown error'}`,
+      };
+    }
+
+    return { stripped: toStrip };
+  } catch (err) {
+    const msg = err && err.message ? String(err.message) : 'unknown error';
+    return { stripped: [], error: msg };
+  }
+}

package/scripts/lib/language-mappers/README.md

@@ -0,0 +1,57 @@
+# language-mappers
+
+Semantic slice extractors for the session-orchestrator discovery pipeline.
+
+## API
+
+### `extractSemanticSlices(filePath, content, options?): Promise<SemanticSlice[]>`
+
+Dispatches to the correct language mapper based on file extension (or an explicit `options.language` override).
+
+```js
+import { extractSemanticSlices } from './index.mjs';
+
+const slices = await extractSemanticSlices('src/utils.ts', sourceText);
+// [{ kind: 'function', name: 'formatDate', file: 'src/utils.ts', line: 3, endLine: 7, exported: true, isNested: false, params: ['date'] }]
+```
+
+### `languageFromPath(filePath): 'ts'|'js'|'md'|null`
+
+Derive the language key from a file path extension. Returns `null` for unsupported extensions.
+
+### `SLICE_KINDS`
+
+Frozen array of all valid `kind` values: `['function', 'class', 'interface', 'type', 'export', 'section']`.
+
+## SemanticSlice shape
+
+```ts
+interface SemanticSlice {
+  kind: 'function' | 'class' | 'interface' | 'type' | 'export' | 'section';
+  name: string;
+  file: string;
+  line: number;
+  endLine: number;
+  exported: boolean;
+  isNested: boolean;
+  params?: string[];   // TS: param names; class: method names; MD: [depth]
+  doc?: string;        // leading JSDoc comment text, if present
+}
+```
+
+## Phase 1 support
+
+| Extension | Language | Mapper |
+|-----------|----------|--------|
+| `.ts`, `.tsx` | TypeScript | `@babel/parser` |
+| `.js`, `.jsx`, `.mjs`, `.cjs` | JavaScript | `@babel/parser` |
+| `.md`, `.mdx` | Markdown | `remark` + `remark-parse` |
+
+## Phase 2 (filed as follow-up issue)
+
+- **Swift** — regex-based proto (`class`, `func`, `protocol`, `struct` declarations)
+- **Python** — regex-based proto (`def`, `class` declarations)
+
+## Integration
+
+Discovery probes consume this API in W4+ (not wired in Phase 1). The discovery pipeline calls `extractSemanticSlices` per file and passes the slice array to triage state for issue-matching.

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

@@ -0,0 +1,165 @@
+/**
+ * language-mappers/index.mjs — Entry point for semantic slice extraction.
+ *
+ * Dispatches to language-specific mappers based on file extension or an
+ * explicit `options.language` override.  Phase 1 supports TypeScript/JS and
+ * Markdown; Phase 2 will add Swift and Python (filed as follow-up issue).
+ *
+ * Part of the Clawpatch Borrow Cluster (issue #416).
+ *
+ * SemanticSlice shape (informational JSDoc — see typescript.mjs for the
+ * canonical typedef consumers should reference):
+ *
+ * @typedef {Object} SemanticSlice
+ * @property {'function'|'class'|'interface'|'type'|'export'|'section'} kind
+ * @property {string} name
+ * @property {string} file
+ * @property {number} line
+ * @property {number} endLine
+ * @property {boolean} exported
+ * @property {boolean} isNested
+ * @property {'regex'|'ast'} fidelity - parser fidelity discriminator (#474 MED-3).
+ *   'ast' for TypeScript/JS (@babel/parser) and Markdown (remark);
+ *   'regex' for Swift and Python (column-0 regex protos).
+ * @property {string[]} [params]
+ * @property {string} [doc]
+ * @property {string} [source]
+ */
+
+import path from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Every possible kind value that a SemanticSlice may carry.
+ * Consumers should treat this as a closed enum for Phase 1.
+ * @type {readonly string[]}
+ */
+export const SLICE_KINDS = Object.freeze([
+  'function',
+  'class',
+  'interface',
+  'type',
+  'export',
+  'section',
+]);
+
+/**
+ * Map from normalised file extension to language key.
+ * @type {Record<string, string>}
+ */
+const EXT_TO_LANG = {
+  '.ts': 'ts',
+  '.tsx': 'ts',
+  '.js': 'js',
+  '.jsx': 'js',
+  '.mjs': 'js',
+  '.cjs': 'js',
+  '.md': 'md',
+  '.mdx': 'md',
+  '.swift': 'swift',
+  '.py': 'py',
+};
+
+// ---------------------------------------------------------------------------
+// Public helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive the language key from a file path.
+ *
+ * @param {string} filePath
+ * @returns {'ts'|'js'|'md'|'swift'|'py'|null}
+ */
+export function languageFromPath(filePath) {
+  if (typeof filePath !== 'string') return null;
+  const ext = path.extname(filePath).toLowerCase();
+  return EXT_TO_LANG[ext] ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Core dispatcher (W3-Q2 MED-005: per-process mapper cache)
+// ---------------------------------------------------------------------------
+
+let tsMapperPromise = null;
+let mdMapperPromise = null;
+let swiftMapperPromise = null;
+let pyMapperPromise = null;
+
+function loadTsMapper() {
+  if (tsMapperPromise === null) {
+    tsMapperPromise = import('./typescript.mjs').then((m) => m.extractTypeScriptSlices);
+  }
+  return tsMapperPromise;
+}
+
+function loadMdMapper() {
+  if (mdMapperPromise === null) {
+    mdMapperPromise = import('./markdown.mjs').then((m) => m.extractMarkdownSlices);
+  }
+  return mdMapperPromise;
+}
+
+function loadSwiftMapper() {
+  if (swiftMapperPromise === null) {
+    swiftMapperPromise = import('./swift.mjs').then((m) => m.extractSwiftSlices);
+  }
+  return swiftMapperPromise;
+}
+
+function loadPyMapper() {
+  if (pyMapperPromise === null) {
+    pyMapperPromise = import('./python.mjs').then((m) => m.extractPythonSlices);
+  }
+  return pyMapperPromise;
+}
+
+/**
+ * Extract semantic slices from `content` for the file at `filePath`.
+ *
+ * @param {string} filePath   Relative or absolute path — used to derive language
+ *                            when `options.language` is not supplied.
+ * @param {string} content    Raw text content of the file.
+ * @param {{ language?: 'ts'|'js'|'md'|'swift'|'py' }} [options]
+ * @returns {Promise<import('./typescript.mjs').SemanticSlice[]>}
+ * @throws {Error} When language is unsupported or the underlying parser fails.
+ */
+export async function extractSemanticSlices(filePath, content, options = {}) {
+  if (typeof filePath !== 'string') {
+    throw new TypeError('extractSemanticSlices: filePath must be a string');
+  }
+  if (typeof content !== 'string') {
+    throw new TypeError('extractSemanticSlices: content must be a string');
+  }
+
+  const lang = options.language ?? languageFromPath(filePath);
+
+  if (lang === 'ts' || lang === 'js') {
+    const extract = await loadTsMapper();
+    return extract(filePath, content);
+  }
+
+  if (lang === 'md') {
+    const extract = await loadMdMapper();
+    return extract(filePath, content);
+  }
+
+  if (lang === 'swift') {
+    const extract = await loadSwiftMapper();
+    return extract(filePath, content);
+  }
+
+  if (lang === 'py') {
+    const extract = await loadPyMapper();
+    return extract(filePath, content);
+  }
+
+  // #474 LOW-9: derive supported-extensions list from EXT_TO_LANG to avoid
+  // drift when new extensions are added to the map.
+  throw new Error(
+    `extractSemanticSlices: unsupported language '${lang ?? 'unknown'}' for file '${filePath}'. ` +
+      `Supports: ${Object.keys(EXT_TO_LANG).join(', ')}.`,
+  );
+}

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

@@ -0,0 +1,149 @@
+/**
+ * language-mappers/markdown.mjs — Semantic slice extractor for Markdown files.
+ *
+ * Uses remark + remark-parse (lazy import) to parse the content into an mdast
+ * tree and emits `section` slices for each heading node.
+ *
+ * Section endLine: line of the NEXT heading of equal-or-lesser depth, or EOF.
+ * Headings whose depth indicates nesting (h3 inside h2) are still emitted as
+ * individual slices; their endLine is bounded by the next peer heading.
+ *
+ * Frontmatter (YAML `---` block) is NOT emitted as a section.
+ *
+ * Part of the Clawpatch Borrow Cluster (issue #416).
+ */
+
+// ---------------------------------------------------------------------------
+// Types (JSDoc only)
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {{
+ *   kind: 'section';
+ *   name: string;
+ *   file: string;
+ *   line: number;
+ *   endLine: number;
+ *   exported: boolean;
+ *   isNested: boolean;
+ *   fidelity: 'ast';
+ *   params: [number];   // [depth] — heading level 1-6
+ * }} SectionSlice
+ */
+
+// All slices produced by this mapper carry fidelity:'ast' (#474 MED-3) —
+// they come from a real remark mdast walk, not regex matching.
+const FIDELITY = /** @type {'ast'} */ ('ast');
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the plain-text value of an mdast node by concatenating all
+ * descendant text nodes.  Matches what mdast-util-to-string does.
+ *
+ * @param {object} node  mdast node
+ * @returns {string}
+ */
+async function nodeText(node) {
+  const { toString } = await import('mdast-util-to-string');
+  return toString(node);
+}
+
+/**
+ * Determine whether a node is YAML frontmatter (type 'yaml') created by
+ * remark-frontmatter.  Since we only use remark-parse (no remark-frontmatter),
+ * a leading `---` block is parsed as a ThematicBreak + Paragraph.  We detect
+ * it conservatively: if the first node is a thematic break (---) followed by
+ * a paragraph, it looks like front-matter — skip the thematic-break.
+ * In practice, remark-parse does NOT expose a yaml node unless remark-frontmatter
+ * is also loaded, so this helper is mostly defensive.
+ *
+ * @param {object} node
+ * @returns {boolean}
+ */
+function isFrontmatterNode(node) {
+  return node.type === 'yaml' || node.type === 'toml';
+}
+
+/**
+ * Return the 1-based line number of the last line of the document.
+ *
+ * @param {string} content
+ * @returns {number}
+ */
+function countLines(content) {
+  const lines = content.split('\n');
+  return lines.length;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract section slices from Markdown content.
+ *
+ * @param {string} filePath   Source file path (used only for the slice `file` field).
+ * @param {string} content    Raw Markdown text.
+ * @returns {Promise<SectionSlice[]>}
+ */
+export async function extractMarkdownSlices(filePath, content) {
+  if (!content.trim()) return [];
+
+  const { unified } = await import('unified');
+  const { default: remarkParse } = await import('remark-parse');
+
+  const processor = unified().use(remarkParse);
+  const tree = processor.parse(content);
+
+  const totalLines = countLines(content);
+
+  // Collect only heading nodes, in document order
+  /** @type {Array<{node: object; depth: number; line: number; text: string}>} */
+  const headings = [];
+
+  for (const node of tree.children ?? []) {
+    if (isFrontmatterNode(node)) continue;
+    if (node.type !== 'heading') continue;
+    const line = node.position?.start?.line ?? 1;
+    const text = await nodeText(node);
+    headings.push({ node, depth: node.depth, line, text });
+  }
+
+  if (headings.length === 0) return [];
+
+  /** @type {SectionSlice[]} */
+  const slices = [];
+
+  for (let i = 0; i < headings.length; i++) {
+    const { depth, line, text } = headings[i];
+
+    // endLine = line before the next heading of equal-or-lesser depth, or EOF
+    let endLine = totalLines;
+    for (let j = i + 1; j < headings.length; j++) {
+      if (headings[j].depth <= depth) {
+        // The next heading at the same or higher level ends this section
+        endLine = headings[j].line - 1;
+        break;
+      }
+    }
+    // Ensure endLine is at least the start line
+    if (endLine < line) endLine = line;
+
+    slices.push({
+      kind: 'section',
+      name: text,
+      file: filePath,
+      line,
+      endLine,
+      exported: true,
+      isNested: false,
+      fidelity: FIDELITY,
+      params: [depth],
+    });
+  }
+
+  return slices;
+}