yay-layer 1.0.0-rc.1

package/src/specdiff.js

@@ -0,0 +1,69 @@
+'use strict';
+// Compute what changed in a Cell's SPEC versus its last committed (HEAD) version,
+// so the phone can show a real diff before the human approves. Read-only + best-
+// effort: outside a git repo, or for a brand-new/unchanged spec, it returns null.
+
+const path = require('path');
+const { MARK_BEGIN, MARK_END } = require('./util');
+
+// Readable spec-field lines for a cell from raw file content (strips the // or # lead).
+function specLinesFromContent(content, cellId) {
+  const lines = String(content).split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const b = lines[i].match(MARK_BEGIN);
+    if (b && b[1] === cellId) {
+      const out = [];
+      for (let j = i + 1; j < lines.length; j++) {
+        if (MARK_END.test(lines[j])) return out;
+        out.push(lines[j].replace(/^\s*\/\/+\s?/, '').replace(/^\s*#\s?/, '').replace(/\s+$/, ''));
+      }
+      return out;
+    }
+  }
+  return null; // cell not present in this version (i.e. it's new)
+}
+
+// Same, from the manifest cell's `normalized` block (markers + inner lines).
+function normalizedToSpecLines(normalized) {
+  return String(normalized || '').split('\n')
+    .filter((l) => !MARK_BEGIN.test(l) && !MARK_END.test(l))
+    .map((l) => l.replace(/^\s*\/\/+\s?/, '').replace(/^\s*#\s?/, '').replace(/\s+$/, ''));
+}
+
+// The committed (HEAD) content of a file, or null if not in git / not tracked.
+// Uses git's own `--show-prefix` (repo-root → file's dir) instead of path.relative,
+// which would break when the toplevel resolves symlinks (e.g. macOS /var → /private/var).
+function gitHeadContent(root, absFile) {
+  try {
+    const cp = require('child_process'), opt = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] };
+    const dir = path.dirname(absFile), base = path.basename(absFile);
+    const prefix = cp.execFileSync('git', ['-C', dir, 'rev-parse', '--show-prefix'], opt).trim();
+    return cp.execFileSync('git', ['-C', dir, 'show', 'HEAD:' + prefix + base], opt);
+  } catch (_) { return null; }
+}
+
+// Minimal LCS line diff → [{t:' '|'-'|'+', text}]; null if identical or no previous.
+function lineDiff(oldL, newL) {
+  if (!oldL) return null;
+  const a = oldL, b = newL, n = a.length, m = b.length;
+  const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+  for (let i = n - 1; i >= 0; i--) for (let j = m - 1; j >= 0; j--) dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+  const out = []; let i = 0, j = 0;
+  while (i < n && j < m) { if (a[i] === b[j]) { out.push({ t: ' ', text: a[i] }); i++; j++; } else if (dp[i + 1][j] >= dp[i][j + 1]) out.push({ t: '-', text: a[i++] }); else out.push({ t: '+', text: b[j++] }); }
+  while (i < n) out.push({ t: '-', text: a[i++] });
+  while (j < m) out.push({ t: '+', text: b[j++] });
+  return out.some((d) => d.t !== ' ') ? out : null;
+}
+
+// The change to a cell's spec vs its last committed version (for phone review).
+function specDiffForCell(root, cell) {
+  try {
+    const head = gitHeadContent(root, path.resolve(root, cell.file));
+    if (head == null) return null;
+    // manifest cells carry the block as `specBlock` (extract calls it `normalized`).
+    const current = normalizedToSpecLines(cell.specBlock || cell.normalized);
+    return lineDiff(specLinesFromContent(head, cell.id), current);
+  } catch (_) { return null; }
+}
+
+module.exports = { specLinesFromContent, normalizedToSpecLines, gitHeadContent, lineDiff, specDiffForCell };

package/src/tags.js

@@ -0,0 +1,67 @@
+'use strict';
+// Brief TAGS — a small, project-chosen vocabulary that every Brief is tagged with, so the
+// history of what was built can be sorted by concern over time. Neutral by default in the
+// sense that the pool is the project's choice; once a pool is set, tagging is required on
+// each Brief (Standard §5). Tags ride inside the signed Brief, so they are attributed and
+// tamper-evident like the rest of the approval.
+const fs = require('fs');
+const path = require('path');
+
+// Six curated, mutually distinct starter sets. Pick one at `yay init`; switch or extend
+// later with `yay tags`. The `tags` list is the authoritative active pool once chosen.
+const TAG_SETS = [
+  { id: 'technical', name: 'Technical / code type', desc: 'By the kind of code — HTML, CSS, API, Database…',
+    tags: ['HTML', 'CSS', 'JavaScript', 'Frontend', 'Backend', 'API', 'Database', 'Auth', 'Validation', 'Testing', 'Config', 'Build', 'DevOps', 'Utilities'] },
+  { id: 'responsibility', name: 'Responsibility', desc: 'By what the code is responsible for — UI, State, Security…',
+    tags: ['UI', 'State', 'Events', 'Routing', 'Business Logic', 'Data Access', 'API', 'Persistence', 'Security', 'Error Handling', 'Logging', 'Caching', 'Performance', 'Testing', 'Config', 'Infrastructure'] },
+  { id: 'component', name: 'Component kind', desc: 'By the kind of unit — Component, Service, Model, Worker…',
+    tags: ['Component', 'Hook', 'Service', 'Controller', 'Model', 'Repository', 'Middleware', 'Validator', 'Serializer', 'Adapter', 'Provider', 'Factory', 'Utility', 'Worker', 'Job', 'Command', 'Event', 'Listener', 'Test', 'Fixture'] },
+  { id: 'layer', name: 'Layer', desc: 'By architectural layer — Presentation, Domain, Data, Infra…',
+    tags: ['Presentation', 'Interaction', 'Application', 'Domain', 'Service', 'Integration', 'Data Access', 'Persistence', 'Infrastructure', 'Security'] },
+  { id: 'area', name: 'App area', desc: 'By where it lives in the product — Header, Settings, Auth…',
+    tags: ['App Shell', 'Header', 'Navigation', 'Sidebar', 'Toolbar', 'Main Content', 'Dashboard', 'Page', 'Form', 'Modal', 'Search', 'Notifications', 'Profile', 'Settings', 'Auth', 'Admin', 'Footer', 'Onboarding'] },
+  { id: 'product', name: 'Product system', desc: 'By product subsystem — Experience, Identity, Data, Integration…',
+    tags: ['Experience', 'Navigation', 'Interaction', 'Content', 'Application', 'Domain', 'Identity', 'Data', 'Communication', 'Integration', 'Background Jobs', 'Observability', 'Infrastructure'] },
+];
+const setById = (id) => TAG_SETS.find((s) => s.id === id) || null;
+
+// "Custom" isn't a preset — it seeds blank placeholders the user relabels afterwards
+// (in the Dashboard Tags tab, or by editing .yaylayer/tags.json directly).
+const CUSTOM_SEED = ['Custom 1', 'Custom 2', 'Custom 3', 'Custom 4'];
+
+function tagsPath(p) { return path.join(path.dirname(p.config), 'tags.json'); }
+function loadTags(p) {
+  try { const o = JSON.parse(fs.readFileSync(tagsPath(p), 'utf8')); return (o && Array.isArray(o.tags)) ? o : null; }
+  catch (_) { return null; }
+}
+function saveTags(p, obj) { fs.writeFileSync(tagsPath(p), JSON.stringify(obj, null, 2) + '\n'); }
+
+// Case/space-insensitive match; returns the pool's canonical casing when a tag is in-pool.
+const norm = (t) => String(t == null ? '' : t).trim().toLowerCase().replace(/\s+/g, ' ');
+function canonicalTag(pool, t) { const n = norm(t); const hit = (pool || []).find((x) => norm(x) === n); return hit || String(t).trim(); }
+function isKnown(pool, t) { const n = norm(t); return (pool || []).some((x) => norm(x) === n); }
+// Parse a comma/space separated tag string into a de-duped, canonical list.
+function parseTags(pool, raw) {
+  const seen = new Set(); const out = [];
+  String(raw || '').split(/[,\n]/).map((s) => s.trim()).filter(Boolean).forEach((t) => {
+    const c = canonicalTag(pool, t); const k = norm(c);
+    if (!seen.has(k)) { seen.add(k); out.push(c); }
+  });
+  return out;
+}
+function unknownTags(pool, tags) { return (tags || []).filter((t) => !isKnown(pool, t)); }
+
+// Is the tag plan FINISHED — ready to tag signed Briefs with? A finished plan has no
+// unrelabeled "Custom N" placeholders and at least MIN_PLAN_TAGS unique tags. The AI
+// picks a Brief's tags FROM the human's plan, so an unfinished plan poisons every
+// downstream choice — signing is refused until the plan is finished.
+const MIN_PLAN_TAGS = 5;
+const isPlaceholder = (t) => /^custom\s*\d+$/i.test(String(t || '').trim());
+function planStatus(tagCfg) {
+  if (!tagCfg || !Array.isArray(tagCfg.tags)) return { exists: false, ok: false, placeholders: [], unique: 0 };
+  const placeholders = tagCfg.tags.filter(isPlaceholder);
+  const unique = new Set(tagCfg.tags.filter((t) => !isPlaceholder(t)).map(norm)).size;
+  return { exists: true, ok: placeholders.length === 0 && unique >= MIN_PLAN_TAGS, placeholders, unique };
+}
+
+module.exports = { TAG_SETS, setById, CUSTOM_SEED, MIN_PLAN_TAGS, tagsPath, loadTags, saveTags, canonicalTag, isKnown, parseTags, unknownTags, norm, isPlaceholder, planStatus };

package/src/testrun.js

@@ -0,0 +1,41 @@
+'use strict';
+// Run the PROJECT's own test suite (not the per-Cell prover) so the dashboard and
+// the gate can show a full picture: Cell colours + prover + your real tests.
+// Best-effort + bounded; command resolution prefers an explicit setting.
+
+const fs = require('fs');
+const path = require('path');
+const cp = require('child_process');
+
+// The command to run: --test flag > config.test > package.json "test" script.
+function resolveTestCmd(root, config, flags) {
+  if (flags && flags.test && flags.test !== true) return String(flags.test);
+  if (config && config.test) return String(config.test);
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    const t = pkg.scripts && pkg.scripts.test;
+    if (t && !/no test specified/i.test(t)) return 'npm test'; // real test script present
+  } catch (_) {}
+  return null;
+}
+
+// Run `cmd` in the repo root, capturing combined output + exit code (bounded).
+function runTests(root, cmd, timeoutMs) {
+  return new Promise((resolve) => {
+    if (!cmd) return resolve({ configured: false, cmd: null, ok: false, code: null, output: 'No test command configured. Add a "test" script to package.json, set "test" in .yaylayer/config.json, or pass --test "…".', ms: 0 });
+    const started = Date.now();
+    cp.exec(cmd, { cwd: root, timeout: timeoutMs || 300000, maxBuffer: 8 * 1024 * 1024, windowsHide: true }, (err, stdout, stderr) => {
+      const combined = ((stdout || '') + (stderr || ''));
+      resolve({
+        configured: true, cmd,
+        ok: !err,
+        code: err ? (err.code == null ? 1 : err.code) : 0,
+        timedOut: !!(err && err.killed),
+        output: combined.slice(-20000) || (err ? String(err.message) : ''),
+        ms: Date.now() - started,
+      });
+    });
+  });
+}
+
+module.exports = { resolveTestCmd, runTests };

package/src/util.js

@@ -0,0 +1,234 @@
+'use strict';
+// Shared helpers: paths, canonical JSON, file walking, terminal color, marker constants.
+
+const fs = require('fs');
+const path = require('path');
+
+// The unique comment markers that delimit a YayLayer spec block.
+// `YAY` = "this is YayLayer"; the id (e.g. C-040) names the Cell.
+const MARK_BEGIN = /∷YAY⟨\s*([A-Za-z0-9._-]+)\s*⟩/;
+const MARK_END = /∷YAY-END⟨\s*([A-Za-z0-9._-]+)\s*⟩/;
+
+const YAY_DIR = '.yaylayer';
+const CONFIG = 'config.json';
+const LOCK = 'lock.json';
+const KEYS = 'keys';
+
+function repoRoot(start) {
+  let dir = path.resolve(start || process.cwd());
+  for (;;) {
+    if (fs.existsSync(path.join(dir, YAY_DIR)) || fs.existsSync(path.join(dir, '.git'))) return dir;
+    const up = path.dirname(dir);
+    if (up === dir) return path.resolve(start || process.cwd());
+    dir = up;
+  }
+}
+
+const paths = (root) => ({
+  root,
+  yay: path.join(root, YAY_DIR),
+  config: path.join(root, YAY_DIR, CONFIG),
+  lock: path.join(root, YAY_DIR, LOCK),
+  keys: path.join(root, YAY_DIR, KEYS),
+});
+
+function readJSON(file, fallback) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (_) { return fallback; }
+}
+
+function writeJSON(file, obj) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(obj, null, 2) + '\n');
+}
+
+// Deterministic serialization so a hash/signature is stable regardless of key order.
+function canonical(obj) {
+  if (obj === null || typeof obj !== 'object') return JSON.stringify(obj);
+  if (Array.isArray(obj)) return '[' + obj.map(canonical).join(',') + ']';
+  const keys = Object.keys(obj).sort();
+  return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonical(obj[k])).join(',') + '}';
+}
+
+// A roster entry is one identity that may hold several keys (local + phone …).
+// Normalize any stored shape to a flat list of base64 public keys.
+//   legacy string  → ["pub"]
+//   ["pub", …]     → as-is
+//   [{pub,kind,…}] → [pub, …]
+function pubKeysOf(entry) {
+  if (!entry) return [];
+  if (typeof entry === 'string') return [entry];
+  if (Array.isArray(entry)) return entry.map((k) => (typeof k === 'string' ? k : k && k.pub)).filter(Boolean);
+  if (entry.pub) return [entry.pub];
+  return [];
+}
+
+const SKIP_DIRS = new Set(['node_modules', '.git', '.yaylayer', 'docs', 'dist', 'build', 'coverage']);
+// Every extension we scan for spec blocks. Spec fields are comment-agnostic (see
+// extract.parseSpec), so any of these can carry a spec block. Verification depth
+// then depends on the language's tier (see below).
+const CODE_EXT = new Set([
+  // JS/TS — fully analyzed + behaviourally proven
+  '.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx',
+  // brace-family (C-style) — spec-mirror + sign + gate + map, capped at Yellow
+  '.cs', '.sol', '.rs', '.go', '.java', '.c', '.h', '.cpp', '.cc', '.cxx', '.hpp', '.hh',
+  '.kt', '.kts', '.swift', '.php', '.scala', '.dart', '.pl', '.pm', '.sh', '.bash',
+  // indentation-scoped
+  '.py', '.pyw',
+  // def…end-scoped
+  '.rb', '.ex', '.exs',
+  // shallow (marker blocks only, no unit analysis)
+  '.css', '.html',
+]);
+
+// Body-delimiting FAMILY for a file — selects how the unit body is grabbed:
+//   js    → JS/TS declaration + brace matcher (full analysis + proof)
+//   brace → generic C-family brace matcher (Go, Java, C/C++, Kotlin, Swift, …)
+//   python→ indentation
+//   ruby  → def…end (Ruby, Elixir)
+//   css/html/other → shallow (no unit body)
+const BRACE_EXT = new Set(['.cs', '.sol', '.rs', '.go', '.java', '.c', '.h', '.cpp', '.cc', '.cxx', '.hpp', '.hh', '.kt', '.kts', '.swift', '.php', '.scala', '.dart', '.pl', '.pm', '.sh', '.bash']);
+function langOf(file) {
+  const e = path.extname(String(file)).toLowerCase();
+  if (['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx'].includes(e)) return 'js';
+  if (e === '.py' || e === '.pyw') return 'python';
+  if (e === '.rb' || e === '.ex' || e === '.exs') return 'ruby';
+  if (BRACE_EXT.has(e)) return 'brace';
+  if (e === '.css') return 'css';
+  if (e === '.html') return 'html';
+  return 'other';
+}
+// The SPECIFIC language (not the body-grabbing family) — so per-language effect nets and the
+// Ruby/PHP provers can tell php/solidity/rust/csharp apart (all family 'brace') and ruby apart
+// from elixir (both family 'ruby'). Family selects how a unit body is grabbed; this selects
+// which language's effect idioms to police.
+const LANG_NAME = {
+  '.js': 'js', '.jsx': 'js', '.mjs': 'js', '.cjs': 'js', '.ts': 'ts', '.tsx': 'ts',
+  '.py': 'python', '.pyw': 'python', '.rb': 'ruby', '.ex': 'elixir', '.exs': 'elixir',
+  '.php': 'php', '.sol': 'solidity', '.rs': 'rust', '.cs': 'csharp', '.go': 'go', '.java': 'java',
+  '.c': 'c', '.h': 'c', '.cpp': 'cpp', '.cc': 'cpp', '.cxx': 'cpp', '.hpp': 'cpp', '.hh': 'cpp',
+  '.kt': 'kotlin', '.kts': 'kotlin', '.swift': 'swift', '.scala': 'scala', '.dart': 'dart',
+  '.pl': 'perl', '.pm': 'perl', '.sh': 'shell', '.bash': 'shell',
+};
+function langNameOf(file) { return LANG_NAME[path.extname(String(file)).toLowerCase()] || 'other'; }
+// Normalise a language STRING (a cell's extension-derived lang, or a `lang:` spec override) to the
+// canonical name the effect nets / provers key on — so 'rb'|'ruby', 'cs'|'c#'|'csharp' all agree.
+function normLangName(l) {
+  l = String(l || '').toLowerCase().trim();
+  const m = { jsx: 'js', mjs: 'js', cjs: 'js', tsx: 'ts', py: 'python', pyw: 'python', rb: 'ruby', sol: 'solidity', rs: 'rust', cs: 'csharp', 'c#': 'csharp' };
+  return m[l] || l;
+}
+// The comment lead used when `yay adopt` scaffolds a block: '#' for hash-comment
+// languages, '//' otherwise. (Reading is comment-agnostic; only writing needs this.)
+const HASH_EXT = new Set(['.py', '.pyw', '.rb', '.ex', '.exs', '.pl', '.pm', '.sh', '.bash']);
+function commentLeadOf(file) { return HASH_EXT.has(path.extname(String(file)).toLowerCase()) ? '#' : '//'; }
+
+// The only languages YayLayer currently analyzes (AST) and can behaviourally
+// prove. Everything else is signed-but-unverified. `lang` here is the manifest's
+// per-Cell value (a file extension slice like 'ts', or a spec `lang:` override).
+const JS_LANGS = new Set(['js', 'jsx', 'mjs', 'cjs', 'ts', 'tsx', 'javascript', 'typescript']);
+function isJsLang(l) { return JS_LANGS.has(String(l || '').toLowerCase()); }
+
+function walk(dir, out = []) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return out; }
+  for (const e of entries) {
+    if (e.name.startsWith('.') && e.name !== '.') continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (!SKIP_DIRS.has(e.name)) walk(full, out);
+    } else if (CODE_EXT.has(path.extname(e.name))) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+// Minimal ANSI color (auto-disabled when not a TTY or NO_COLOR set).
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
+const c = {
+  green: paint('32'), yellow: paint('33'), red: paint('31'),
+  gray: paint('90'), bold: paint('1'), accent: paint('35'), dim: paint('2'),
+  pink: paint('95'),
+};
+
+// State → glyph + colorizer, used across verify/map output.
+// PINK = code with NO formal specification at all — untracked, never described
+// or signed. The most dangerous state: unknown territory where silent bugs hide.
+const STATE = {
+  GREEN: { glyph: '●', color: c.green, label: 'GREEN' },
+  YELLOW: { glyph: '●', color: c.yellow, label: 'YELLOW' },
+  RED: { glyph: '●', color: c.red, label: 'RED' },
+  UNSIGNED: { glyph: '○', color: c.gray, label: 'UNSIGNED' },
+  PINK: { glyph: '◆', color: c.pink, label: 'PINK' },
+};
+
+// Top-level IMPERATIVE code in a non-JS file (Python/Ruby) — the "sneak a DO-THIS line
+// at module scope" shape that runs at import time. JS gets this from the AST; non-JS
+// langs had no equivalent, so a bare `os.system(...)` at column 0 slipped past the Pink
+// net entirely. Conservative on purpose (mirrors JS looseTopLevel): flag indent-0 bare
+// CALLS (`foo(` / `foo.bar(`) and control-flow starters, but skip declarations, imports,
+// comments, spec markers, the `if __name__` main-guard, and assignments (module
+// constants/wiring — same carve-out JS makes). Returns 1-based line numbers.
+// A NARROW, high-confidence set of "runs a dangerous side effect AT IMPORT" tokens —
+// network exfiltration + process execution. Used ONLY to un-exempt a top-level
+// ASSIGNMENT (`const X = …`, `X = …`), which is otherwise treated as a module constant.
+// Deliberately excludes ubiquitous benign wiring (require, document/window, Date.now)
+// so a normal codebase isn't drowned in false Pinks: the target is `LEAK = fetch(evil)`
+// / `X = requests.get(url)` at module scope, not every constant. (Distinct from the
+// broad purity net in verify.js, which polices effects INSIDE a Cell's body.)
+const LOADTIME_JS = [/\bfetch\s*\(/, /\bXMLHttpRequest\b/, /\baxios\b/, /\bWebSocket\b/, /\bnavigator\s*\.\s*sendBeacon\b/, /\.\s*exec(?:Sync|File|FileSync)?\s*\(/, /\.\s*spawn(?:Sync)?\s*\(/, /\bchild_process\b/, /\bimport\s*\(/];
+const LOADTIME_PY = [/\brequests\s*\./, /\burllib\b/, /\bhttpx\s*\./, /\bsocket\s*\./, /\bos\s*\.\s*system\s*\(/, /\bos\s*\.\s*popen\s*\(/, /\bsubprocess\s*\./, /\b__import__\s*\(/, /\beval\s*\(/, /\bexec\s*\(/];
+function hasLoadTimeEffect(text, family) {
+  const set = /^py/.test(String(family || '')) ? LOADTIME_PY : LOADTIME_JS;
+  const s = String(text || '');
+  return set.some((re) => re.test(s));
+}
+
+// Top-level (executable-at-load) statements in a PHP file — used ONLY by the PHP prover as a
+// safety gate (never eval a file that runs code outside function/class bodies). Conservative: at
+// brace-depth 0, anything that isn't a declaration / tag / comment is flagged, so we refuse to
+// prove rather than risk executing top-level side effects. (Not wired into the gate's Pink net —
+// that stays family-based; this is opt-in via family 'php' from the adapter.)
+function loosePhp(lines) {
+  const out = []; let depth = 0;
+  const DECL = /^(?:<\?php|<\?=|<\?|\?>|namespace\b|use\b|declare\b|abstract\b|final\b|interface\b|trait\b|enum\b|class\b|function\b|const\b|require\b|require_once\b|include\b|include_once\b|\/\/|#|\/\*|\*)/;
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i]; const t = raw.trim();
+    if (t && depth <= 0 && !DECL.test(t) && !/∷YAY/.test(t) && t !== '{' && t !== '}') out.push(i + 1);
+    depth += (raw.match(/\{/g) || []).length - (raw.match(/\}/g) || []).length;
+    if (depth < 0) depth = 0;
+  }
+  return out;
+}
+function looseTopLevelNonJs(lines, family) {
+  if (family === 'php') return loosePhp(lines);
+  if (family !== 'python' && family !== 'ruby') return [];
+  const out = [];
+  const CALL = /^[A-Za-z_$][\w$]*(?:\s*\.\s*[A-Za-z_$][\w$]*)*\s*\(/;
+  const CTRL = /^(?:if|for|while|with|try|unless|begin|case|loop)\b/;
+  const DECL = /^(?:def|class|async|module|import|from|require|require_relative|include|extend|attr_[a-z]+|@|#|"""|''')/;
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    if (/^\s/.test(raw)) continue;            // indented → inside some block
+    const t = raw.trim();
+    if (!t) continue;
+    if (/∷YAY/.test(t) || DECL.test(t)) continue;
+    if (/^if\s+__name__/.test(t)) continue;   // standard Python entry guard (dead on import)
+    const eq = t.search(/[^=!<>]=[^=]/);       // a real single '=' (assignment), not ==/!=/<=/>=
+    const par = t.indexOf('(');
+    if (eq >= 0 && (par < 0 || eq < par)) {    // assignment → module constant/wiring…
+      if (hasLoadTimeEffect(t, family)) out.push(i + 1); // …UNLESS its RHS exfiltrates/execs at import
+      continue;
+    }
+    if (CALL.test(t) || CTRL.test(t)) out.push(i + 1);
+  }
+  return out;
+}
+
+module.exports = {
+  MARK_BEGIN, MARK_END, YAY_DIR,
+  repoRoot, paths, readJSON, writeJSON, canonical, pubKeysOf, walk, c, STATE,
+  langOf, langNameOf, normLangName, isJsLang, commentLeadOf, looseTopLevelNonJs, hasLoadTimeEffect,
+};