@shidesheng0218/dsh-plugin-lint 0.1.0 → 0.4.0

package/scripts/probe-boot.mjs

@@ -1,57 +1,123 @@
 #!/usr/bin/env node
-/**
- * Probe one plugin's host half.
- *
- *   node scripts/probe-boot.mjs <npm-package|path> [...] [--tools] [--dsh <version>] [--keep]
- *
- * Without --dsh the installed desktop app is used, which is the fastest path on
- * this machine. With --dsh <version> the CLI comes from npm and runs under plain
- * node, which is how the matrix runs on Linux CI and how a plugin author can run
- * the same probe locally.
- *
- * See docs/10-m4-verification.md and docs/11-m4-capability-probe.md for the
- * method and the failure taxonomy.
- */
-import { fileURLToPath } from 'node:url';
-import { probePackage, resolveDsh, startStub } from './lib/probe.mjs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { downloadArtifact, resolveArtifact } from '../src/probe/artifact-resolver.js';
+import { resolveDsh, startStub } from '../src/probe/dsh-adapter.js';
+import { createProbeEnvironment } from '../src/probe/environment.js';
+import { probePackage } from '../src/probe/probe.js';
+
+const USAGE = [
+  'dsh-plugin-probe — isolated host-half probe for DeepSeek Harness plugins',
+  '',
+  'Usage',
+  '  dsh-plugin-probe <npm-package|path> [...] [options]',
+  '',
+  'Options',
+  '  --dsh <version>       use @deepseek-ai/dsh at an exact npm version (required for the Docker backend)',
+  '  --mode <mode>         headless, web, or both (default: headless)',
+  '  --cache <dir>         cache root for DSH installs and temporary environments (default: system temp)',
+  '  --tools               capture tool inventory through the isolated stub',
+  '  --audit               include the static capability inventory',
+  '  --keep                accepted for CLI compatibility; isolation is always destroyed',
+  '  --unsafe-host         run the desktop DSH without isolation; results remain self-reported',
+  '  -h, --help            show this message',
+  '',
+  'There is no silent host fallback: the Docker backend requires --dsh <version>,',
+  'and the desktop DSH can only be probed with --unsafe-host.',
+  '',
+  'Exit codes: 0 all observations completed · 2 an infrastructure error occurred',
+].join('\n');
 
 const argv = process.argv.slice(2);
+if (argv.includes('-h') || argv.includes('--help')) {
+  console.log(USAGE);
+  process.exit(0);
+}
 const argOf = (name, fallback) => {
-  const i = argv.indexOf(name);
-  return i >= 0 ? argv[i + 1] : fallback;
+  const index = argv.indexOf(name);
+  return index >= 0 ? argv[index + 1] : fallback;
 };
 const keep = argv.includes('--keep');
 const withTools = argv.includes('--tools');
+const withAudit = argv.includes('--audit');
+const backend = argv.includes('--unsafe-host') ? 'host-unsafe' : 'auto';
 const dshVersion = argOf('--dsh', undefined);
 const modeArg = argOf('--mode', 'headless');
-// 'both' expands the same way the matrix runner expands it, so one flag means one
-// thing across the tool.
+if (!['headless', 'web', 'both'].includes(modeArg)) {
+  console.error('dsh-plugin-probe: --mode must be headless, web, or both');
+  process.exit(2);
+}
 const modes = modeArg === 'both' ? ['headless', 'web'] : [modeArg];
-const VALUE_FLAGS = ['--dsh', '--mode', '--cache'];
-const packages = argv.filter((a, i) => !a.startsWith('--') && !VALUE_FLAGS.includes(argv[i - 1]));
+const valueFlags = ['--dsh', '--mode', '--cache'];
+const packages = argv.filter((arg, index) => !arg.startsWith('--') && !valueFlags.includes(argv[index - 1]));
 if (packages.length === 0) {
-  console.error('usage: node scripts/probe-boot.mjs <npm-package|path> [...] [--tools] [--dsh <version>] [--keep]');
+  console.error(USAGE);
   process.exit(2);
 }
 
-const cacheRoot = argOf('--cache', fileURLToPath(new URL('../.matrix-cache', import.meta.url)));
-const dsh = await resolveDsh(dshVersion, cacheRoot);
-const stub = withTools ? await startStub() : undefined;
-console.log('probing with ' + dsh.id + (withTools ? ' + stub provider' : ''));
+const cacheRoot = argOf('--cache', process.env.DSH_PROBE_CACHE || join(tmpdir(), 'dsh-plugin-lint-cache'));
+let dsh;
+try {
+  dsh = dshVersion
+    ? { id: 'npm:' + dshVersion, kind: 'npm', version: dshVersion, extraArgs: [] }
+    : await resolveDsh(undefined, cacheRoot);
+} catch (error) {
+  console.error((error.code || 'PROBE_FAILED') + ': ' + (error.message || 'The DSH runtime could not be resolved.'));
+  process.exit(2);
+}
+if (dsh.kind === 'desktop' && backend !== 'host-unsafe') {
+  console.error('dsh-plugin-probe: the desktop DSH can only be probed with --unsafe-host '
+    + '(no container isolation), or pass --dsh <npm-version> to use the Docker backend.');
+  process.exit(2);
+}
+console.log('probing with ' + dsh.id + ' [' + backend + ']' + (withTools ? ' + isolated stub' : ''));
 
 const results = [];
+let failures = 0;
 for (const name of packages) {
-  for (const mode of modes) {
-  const cell = await probePackage({ target: name, dsh, stub: mode === 'web' ? undefined : stub, tools: withTools, keep, mode });
-  results.push({ package: name, mode, ...cell });
-  console.log(cell.status.padEnd(16) + name + ' [' + mode + ']  (' + cell.durationMs + ' ms)');
-  for (const e of cell.entries) console.log('                 ' + e.id + ': ' + e.reason);
-  if (cell.tools && !cell.tools.error) {
-    console.log('                 tools ' + cell.tools.baseline + ' -> ' + cell.tools.total
-      + (cell.tools.added.length ? '  +' + cell.tools.added.length + ': ' + cell.tools.added.join(', ') : '  (none)'));
-    console.log('                 system prompt ' + cell.systemPrompt.baselineChars + ' -> ' + cell.systemPrompt.chars + ' chars');
-  }
+  try {
+    let artifact = await resolveArtifact(name);
+    if (!artifact.local) artifact = await downloadArtifact(artifact);
+    for (const mode of modes) {
+      const environment = await createProbeEnvironment({
+        backend,
+        workDir: cacheRoot,
+        dshDir: dsh.kind === 'npm' && dsh.version !== 'desktop' ? join(cacheRoot, 'dsh', dsh.version) : undefined,
+      });
+      const stub = withTools && mode !== 'web' && backend === 'host-unsafe' ? await startStub() : undefined;
+      try {
+        const observation = await probePackage({ artifact, dsh, environment, stub, tools: withTools, keep, composition: mode, audit: withAudit });
+        results.push({ package: name, mode, ...observation });
+        if (observation.outcome === 'error') {
+          failures += 1;
+          console.error(`${observation.error.code}: ${observation.error.message}`);
+          continue;
+        }
+        console.log(observation.status.padEnd(16) + name + ' [' + mode + ']  (' + observation.durationMs + ' ms)');
+        for (const entry of observation.entries) console.log('                 ' + entry.id + ': ' + entry.reason);
+        if (observation.tools && !observation.tools.error) {
+          console.log('                 tools ' + observation.tools.baseline + ' -> ' + observation.tools.total
+            + (observation.tools.added.length ? '  +' + observation.tools.added.length + ': ' + observation.tools.added.join(', ') : '  (none)'));
+          console.log('                 system prompt ' + observation.systemPrompt.baselineChars + ' -> ' + observation.systemPrompt.chars + ' chars');
+        }
+        if (observation.audit) {
+          console.log('                 audit: ' + observation.audit.observed.length + ' capabilities observed');
+          for (const item of observation.audit.observed) {
+            console.log('                   ' + item.capability + '  (' + item.sites + ' site' + (item.sites === 1 ? '' : 's') + ', first: ' + item.first.file + ')');
+          }
+        }
+      } finally {
+        if (stub) stub.server.close();
+      }
+    }
+  } catch (error) {
+    failures += 1;
+    const code = error.code || 'PROBE_FAILED';
+    const message = code === 'PROBE_FAILED' ? 'The probe could not complete.' : error.message;
+    console.error(`${code}: ${message}`);
+    results.push({ package: name, outcome: 'error', error: { code, message } });
   }
 }
-if (stub) stub.server.close();
+
 console.log('\n' + JSON.stringify(results, null, 2));
+process.exitCode = failures > 0 ? 2 : 0;

package/src/composition.js

@@ -0,0 +1 @@
+export * from './experimental/conflicts.js';

package/src/core/baseline.js

@@ -0,0 +1,98 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { sha256, stableStringify } from '../shared/hash.js';
+import { EVENT_CATALOG, RULES } from './rules.js';
+
+export const BASELINE_SCHEMA_VERSION = 1;
+
+/** Evidence strings can move with formatting; keep the stable part only. */
+export function normalizeEvidence(value) {
+  return String(value ?? '').replace(/\s+/g, ' ').trim();
+}
+
+/** A fingerprint deliberately excludes the line number. */
+export function fingerprint(finding) {
+  return 'sha256:' + sha256(stableStringify({
+    rule: finding.rule,
+    file: finding.file || 'package.json',
+    evidence: normalizeEvidence(finding.evidence),
+  }));
+}
+
+export function rulesetIdentity() {
+  return {
+    hash: sha256(stableStringify(RULES.map((rule) => ({ id: rule.id, level: rule.level })))),
+    rules: RULES.map((rule) => rule.id),
+    eventCatalog: { harvestedAt: EVENT_CATALOG.harvestedAt, dshVersions: EVENT_CATALOG.dshVersions },
+  };
+}
+
+export function createBaseline(reports, { generatedAt = new Date().toISOString() } = {}) {
+  const seen = new Set();
+  const findings = [];
+  for (const report of reports) {
+    for (const finding of report.findings) {
+      const print = fingerprint(finding);
+      if (seen.has(print)) continue;
+      seen.add(print);
+      findings.push({
+        fingerprint: print,
+        rule: finding.rule,
+        level: finding.level,
+        file: finding.file || 'package.json',
+        evidence: normalizeEvidence(finding.evidence),
+      });
+    }
+  }
+  return {
+    schemaVersion: BASELINE_SCHEMA_VERSION,
+    generatedAt,
+    ruleset: rulesetIdentity(),
+    findings,
+  };
+}
+
+export function readBaseline(path) {
+  const value = JSON.parse(readFileSync(path, 'utf8'));
+  if (!value || value.schemaVersion !== BASELINE_SCHEMA_VERSION || !Array.isArray(value.findings)) {
+    throw new Error('not a dsh-plugin-lint baseline: ' + path);
+  }
+  for (const entry of value.findings) {
+    if (typeof entry.fingerprint !== 'string' || typeof entry.rule !== 'string') {
+      throw new Error('baseline entry is missing fingerprint/rule: ' + path);
+    }
+  }
+  return value;
+}
+
+export function writeBaseline(path, baseline) {
+  writeFileSync(path, JSON.stringify(baseline, null, 2) + '\n');
+}
+
+/** Filter baseline fingerprints out of each report and recompute its summary. */
+export function applyBaseline(reports, baseline, { path } = {}) {
+  const known = new Set(baseline.findings.map((entry) => entry.fingerprint));
+  let suppressed = 0;
+  const filtered = reports.map((report) => {
+    const findings = [];
+    for (const finding of report.findings) {
+      if (known.has(fingerprint(finding))) suppressed += 1;
+      else findings.push(finding);
+    }
+    const summary = { error: 0, warn: 0, info: 0 };
+    for (const finding of findings) summary[finding.level] += 1;
+    return { ...report, findings, summary, baseline: { suppressed: report.findings.length - findings.length, path: path || null } };
+  });
+  return { reports: filtered, suppressed };
+}
+
+/** Keep only baseline entries that still occur in the current run. */
+export function pruneBaseline(baseline, reports, { generatedAt = baseline.generatedAt } = {}) {
+  const current = new Set();
+  for (const report of reports) for (const finding of report.findings) current.add(fingerprint(finding));
+  return {
+    ...baseline,
+    generatedAt,
+    ruleset: rulesetIdentity(),
+    findings: baseline.findings.filter((entry) => current.has(entry.fingerprint)),
+  };
+}

package/src/core/changed.js

@@ -0,0 +1,41 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+
+/** Files changed against `ref` (default HEAD) or staged in the index. */
+export function changedFiles({ cwd = process.cwd(), ref, staged = false } = {}) {
+  const args = ['diff', '--name-only', '--diff-filter=ACMR'];
+  if (staged) args.push('--cached');
+  args.push(ref || 'HEAD');
+  const output = execFileSync('git', args, { cwd, encoding: 'utf8' });
+  return output.split('\n').map((line) => line.trim()).filter(Boolean);
+}
+
+/**
+ * Map changed files to the nearest enclosing package.json. Deleted files map
+ * to their former directory; files outside any package are ignored.
+ */
+export function packageRoots(files, cwd = process.cwd()) {
+  const base = resolve(cwd);
+  const roots = new Set();
+  for (const file of files) {
+    let dir = resolve(base, file);
+    try {
+      if (!statSync(dir).isDirectory()) dir = dirname(dir);
+    } catch {
+      dir = dirname(dir);
+    }
+    while (true) {
+      const rel = relative(base, dir);
+      if (rel.startsWith('..') || isAbsolute(rel)) break;
+      if (existsSync(join(dir, 'package.json'))) {
+        roots.add(dir);
+        break;
+      }
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+  return [...roots].sort();
+}

package/src/core/load.js

@@ -0,0 +1,145 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { maskSource } from './mask.js';
+import { globToRegExp } from './packlist.js';
+
+/** Directories that never hold shipped plugin code. */
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.github', '.husky', '.dsh-testkit', 'coverage', 'fixtures',
+  'test', 'tests', '__tests__', '__snapshots__', 'dist-test',
+]);
+
+/** Guard rails so one huge vendored file cannot stall a run. */
+const MAX_FILE_BYTES = 3 * 1024 * 1024;
+const MAX_FILES = 3000;
+
+export function loadPackage(dir, options = {}) {
+  const manifestPath = join(dir, 'package.json');
+  if (!existsSync(manifestPath)) throw new Error('not a package directory (no package.json): ' + dir);
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+
+  const norm = (p) => (p === undefined ? undefined : String(p).replace(/^\.\//, ''));
+  // Node resolves an undeclared package entry to index.js, so the fallback is
+  // correct for resolution — but "nothing was declared" is not the same as
+  // "index.js was declared and is missing". A static asset package (measured:
+  // @deepseek-ai/dsh-web-frontend exports only ./dist/*) has no host entry at all,
+  // and flagging it would be a false positive.
+  // Node resolves exports["."] before main; the loader imports the package by
+  // name and follows the same order. Keeping main first made a stale main an
+  // error even when exports["."] was the entry that actually loaded.
+  const mainEntry = firstString(manifest.main);
+  const declaredHost = exportTarget(manifest.exports, '.') || mainEntry;
+  const entries = {
+    host: norm(declaredHost || 'index.js'),
+    // A configuration-only bundle (dsh.bundle) needs no host entry at all
+    // (references/mcp-bundle.md): only exports["."]/main make the host file
+    // mandatory, and only they may turn a missing index.js into an E3 error.
+    hostDeclared: Boolean(declaredHost),
+    main: norm(mainEntry),
+    mainDeclared: Boolean(mainEntry),
+    // The browser half resolves only a string or a string default; import and
+    // require conditions are Node-only and the client registry rejects them.
+    client: norm(clientExportTarget(manifest.exports, './client') || (manifest.dsh && manifest.dsh.client ? 'client.js' : undefined)),
+    patch: norm(manifest.dsh && manifest.dsh.bundle ? firstString(manifest.dsh.bundle.patch) : undefined),
+    icon: norm(firstString(manifest.icon)),
+    localeDir: existsSync(join(dir, 'locale')) ? 'locale' : undefined,
+  };
+
+  const jsFiles = [];
+  const authorPhase = options.phase === 'author';
+  collect(dir, dir, jsFiles, authorPhase);
+
+  return {
+    dir,
+    manifest,
+    manifestPath,
+    phase: options.phase || 'publish',
+    buildScripts: Boolean(manifest.scripts && (manifest.scripts.build || manifest.scripts.prepack || manifest.scripts.prepare)),
+    entries,
+    jsFiles,
+    files: Array.isArray(manifest.files) ? manifest.files : undefined,
+    exists: (rel) => rel !== undefined && existsSync(join(dir, rel)),
+    text: (rel) => (existsSync(join(dir, rel)) ? readFileSync(join(dir, rel), 'utf8') : undefined),
+    json: (rel) => {
+      const t = existsSync(join(dir, rel)) ? readFileSync(join(dir, rel), 'utf8') : undefined;
+      if (t === undefined) return undefined;
+      try { return JSON.parse(t); } catch { return undefined; }
+    },
+  };
+}
+
+/** Artifacts a build step produces; an author-phase run may legitimately lack them. */
+export function isBuildOutput(rel) {
+  const value = String(rel || '').replace(/^\.\//, '');
+  return /^(lib|dist|build|out)\//.test(value) || /\.(js|mjs|cjs|jsx)$/.test(value);
+}
+
+function collect(root, current, out, authorPhase = false) {
+  const pattern = authorPhase ? /\.(js|mjs|cjs|jsx|ts|tsx|mts|cts)$/ : /\.(js|mjs|cjs|jsx)$/;
+  let names;
+  try { names = readdirSync(current, { withFileTypes: true }); } catch { return; }
+  for (const dirent of names) {
+    const abs = join(current, dirent.name);
+    if (dirent.isDirectory()) {
+      if (SKIP_DIRS.has(dirent.name)) continue;
+      collect(root, abs, out, authorPhase);
+      continue;
+    }
+    if (!pattern.test(dirent.name)) continue;
+    let size = 0;
+    try { size = statSync(abs).size; } catch { continue; }
+    if (size > MAX_FILE_BYTES) continue;
+    if (out.length >= MAX_FILES) return;
+    const text = readFileSync(abs, 'utf8');
+    const rel = relative(root, abs).split(sep).join('/');
+    const { masked, structural, strings, lineStarts } = maskSource(text);
+    out.push({ path: rel, text, masked, structural, strings, lineStarts, bytes: size });
+  }
+}
+
+function firstString(value) {
+  return typeof value === 'string' && value !== '' ? value : undefined;
+}
+
+/** Resolve an exports subpath to a file path, accepting the Node entry forms. */
+export function exportTarget(exportsField, subpath) {
+  if (exportsField === undefined || exportsField === null) return undefined;
+  if (typeof exportsField === 'string') return subpath === '.' ? exportsField : undefined;
+  const entry = exportsField[subpath];
+  if (entry === undefined) return undefined;
+  if (typeof entry === 'string') return entry;
+  if (entry && typeof entry === 'object') return firstString(entry.default) || firstString(entry.import) || firstString(entry.require);
+  return undefined;
+}
+
+/**
+ * Resolve the browser client entry the way the host's ClientModuleRegistry does:
+ * a string, or an object with a string `default`. import/require are Node-only
+ * conditions and are rejected by the client resolver.
+ */
+export function clientExportTarget(exportsField, subpath = './client') {
+  if (exportsField === undefined || exportsField === null) return undefined;
+  if (typeof exportsField === 'string') return subpath === '.' ? exportsField : undefined;
+  const entry = exportsField[subpath];
+  if (entry === undefined) return undefined;
+  if (typeof entry === 'string') return entry;
+  if (entry && typeof entry === 'object') return firstString(entry.default);
+  return undefined;
+}
+
+export function filesCover(files, relPath) {
+  if (files === undefined || files.length === 0) return true;
+  relPath = String(relPath).replace(/^\.\//, '');
+  let covered = false;
+  for (const raw of files) {
+    let pattern = String(raw).trim().replace(/^\.\//, '').replace(/\/+$/, '');
+    const negated = pattern.startsWith('!');
+    if (negated) pattern = pattern.slice(1);
+    if (!pattern) continue;
+    const matches = pattern === relPath
+      || relPath.startsWith(pattern + '/')
+      || ((pattern.includes('*') || pattern.includes('?') || pattern.includes('[')) && globToRegExp(pattern).test(relPath));
+    if (matches) covered = !negated;
+  }
+  return covered;
+}

package/src/core/mask.js

@@ -0,0 +1,207 @@
+/**
+ * Comment- and string-aware scanner.
+ *
+ * Rules must never match text inside a comment (real plugins document the very
+ * patterns we look for, e.g. "this listener returns next()"). Two views:
+ *
+ *   masked     comments blanked, string literals INTACT — for matching quoted
+ *              event names and reading literal values with exact line numbers.
+ *   structural masked AND string interiors blanked — for brace-depth analysis.
+ */
+
+const BACKTICK = '\u0060';
+
+/** @returns {{ masked: string, structural: string, strings: Array<{value:string,start:number,end:number,line:number}>, lineStarts: number[] }} */
+export function maskSource(text) {
+  const maskedChars = text.split('');
+  const structuralChars = text.slice().split('');
+  const strings = [];
+  const lineStarts = [0];
+  for (let k = 0; k < text.length; k++) if (text[k] === '\n') lineStarts.push(k + 1);
+
+  const NL = '\n';
+  const SP = ' ';
+  const blank = (from, to, chars) => {
+    for (let k = from; k < to; k++) if (chars[k] !== NL) chars[k] = SP;
+  };
+  // A '/' starts a regex only where a value may begin; otherwise it is division.
+  // Two cases the naive "previous character" test gets wrong:
+  //   a++ / b   - the first slash is division, and treating it as a regex would
+  //               swallow the following "//" comment into the masked view.
+  //   return /re/ - the previous character is a letter, but a keyword allows a
+  //               regex here.
+  const REGEX_KEYWORDS = /(?:^|[^\w$])(?:return|typeof|instanceof|case|delete|void|throw|new|in|of|do|else|yield|await)$/;
+  const regexAllowed = (idx) => {
+    let k = idx - 1;
+    while (k >= 0 && (maskedChars[k] === SP || maskedChars[k] === NL || maskedChars[k] === '\t')) k -= 1;
+    if (k < 0) return true;
+    const prev = maskedChars[k];
+    if ('(,=:[!&|?{};+-*%<>~^'.indexOf(prev) >= 0) {
+      if ((prev === '+' || prev === '-') && maskedChars[k - 1] === prev) return false;
+      return true;
+    }
+    if (!/[\w$]/.test(prev)) return false;
+    let wordStart = k;
+    while (wordStart >= 0 && /[\w$]/.test(maskedChars[wordStart])) wordStart -= 1;
+    return REGEX_KEYWORDS.test(maskedChars.slice(wordStart + 1, k + 1).join(''));
+  };
+
+  let i = 0;
+  const n = text.length;
+  while (i < n) {
+    const c = text[i];
+    const next = text[i + 1];
+
+    if (c === '/' && next === '/') {
+      const from = i;
+      while (i < n && text[i] !== NL) i++;
+      blank(from, i, maskedChars);
+      blank(from, i, structuralChars);
+      continue;
+    }
+    if (c === '/' && next === '*') {
+      const from = i;
+      i += 2;
+      while (i < n && !(text[i] === '*' && text[i + 1] === '/')) i++;
+      i = Math.min(n, i + 2);
+      blank(from, i, maskedChars);
+      blank(from, i, structuralChars);
+      continue;
+    }
+
+    // The literal delimiter itself, not a boolean: the closing delimiter must
+    // compare equal to it.
+    const quote = c === '"' ? '"' : c === "'" ? "'" : c === BACKTICK ? BACKTICK : undefined;
+    if (quote !== undefined) {
+      const from = i;
+      i += 1;
+      const contentFrom = i;
+      while (i < n) {
+        if (text[i] === '\\') { i += 2; continue; }
+        if (text[i] === quote) break;
+        if (text[i] === NL && quote !== BACKTICK) break; // unterminated literal
+        i += 1;
+      }
+      const contentTo = Math.min(i, n);
+      const end = Math.min(i + 1, n);
+      strings.push({ value: text.slice(contentFrom, contentTo), start: from, end, line: lineOfIndex(lineStarts, from) });
+      blank(contentFrom, contentTo, structuralChars);
+      i = end;
+      continue;
+    }
+
+    if (c === '/' && regexAllowed(i)) {
+      const from = i;
+      i += 1;
+      let inClass = false;
+      while (i < n) {
+        if (text[i] === '\\') { i += 2; continue; }
+        if (text[i] === '[') inClass = true;
+        else if (text[i] === ']') inClass = false;
+        else if (text[i] === '/' && !inClass) { i += 1; break; }
+        else if (text[i] === NL) break;
+        i += 1;
+      }
+      // A regex body is data, not code: braces and quotes inside it must not
+      // reach the structural view, and a literal "session.append(" inside it
+      // must not look like a call site.
+      blank(from, i, maskedChars);
+      blank(from, i, structuralChars);
+      continue;
+    }
+    i += 1;
+  }
+  return { masked: maskedChars.join(''), structural: structuralChars.join(''), strings, lineStarts };
+}
+
+export function lineOfIndex(lineStarts, index) {
+  let lo = 0;
+  let hi = lineStarts.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (lineStarts[mid] <= index) lo = mid;
+    else hi = mid - 1;
+  }
+  return lo + 1;
+}
+
+/** The first string literal starting at or after \`from\` within \`window\` characters. */
+export function stringAfter(strings, from, window) {
+  for (const s of strings) {
+    if (s.start >= from) return s.start - from <= window ? s : undefined;
+  }
+  return undefined;
+}
+
+/** Literal types passed to Session.append(type, data). */
+export function appendCallSites(masked, strings) {
+  const out = [];
+  // Session receivers the host exposes: bare `session`, ctx.session,
+  // agent.session and this.session. A property named `session` on an unrelated
+  // object (formData.session) is not a Session, so only these names count.
+  const re = /(?<![\w$.])(?:(?:ctx|agent|this)\s*\.\s*)?session\s*\.\s*append\s*\(\s*/g;
+  let m;
+  while ((m = re.exec(masked)) !== null) {
+    if (insideString(strings, m.index)) continue;
+    const s = stringAt(strings, m.index + m[0].length);
+    if (!s) continue;
+    if (s.value.includes('${')) continue;
+    out.push({ type: s.value, index: s.start, line: s.line });
+  }
+  return out;
+}
+
+/** True when `index` falls inside a string literal (where the text is data). */
+function insideString(strings, index) {
+  let lo = 0;
+  let hi = strings.length - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    const s = strings[mid];
+    if (index < s.start) hi = mid - 1;
+    else if (index >= s.end) lo = mid + 1;
+    else return true;
+  }
+  return false;
+}
+
+/** The string literal whose opening quote is exactly at `index`, if any. */
+function stringAt(strings, index) {
+  let lo = 0;
+  let hi = strings.length - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    const s = strings[mid];
+    if (s.start < index) lo = mid + 1;
+    else if (s.start > index) hi = mid - 1;
+    else return s;
+  }
+  return undefined;
+}
+
+/** The balanced brace block that starts at or after `index`, on the structural view. */
+export function blockAfter(structural, index) {
+  const open = structural.indexOf('{', index);
+  if (open < 0) return undefined;
+  let depth = 0;
+  for (let i = open; i < structural.length; i++) {
+    const c = structural[i];
+    if (c === '{') depth += 1;
+    else if (c === '}') {
+      depth -= 1;
+      if (depth === 0) return { start: open, end: i + 1, body: structural.slice(open + 1, i) };
+    }
+  }
+  return undefined;
+}
+
+/** Brace depth at a character index, computed on the structural view. */
+export function braceDepthAt(structural, index) {
+  let depth = 0;
+  for (let k = 0; k < index && k < structural.length; k++) {
+    const c = structural[k];
+    if (c === '{' || c === '(' || c === '[') depth += 1;
+    else if (c === '}' || c === ')' || c === ']') depth -= 1;
+  }
+  return depth;
+}