yay-layer 1.0.0-rc.1

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "yay-layer",
+  "version": "1.0.0-rc.1",
+  "description": "A protocol for provable, signed AI code. Approved blueprints first, an inspector that checks the build matches, and it can't ship until it passes.",
+  "keywords": [
+    "ai",
+    "verification",
+    "provenance",
+    "attestation",
+    "code-signing",
+    "spec-first",
+    "vibe-coding"
+  ],
+  "author": "L.J Bergman <contact@yaylayer.com>",
+  "license": "MIT",
+  "homepage": "https://yaylayer.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jonas-developer/yay-layer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jonas-developer/yay-layer/issues"
+  },
+  "type": "commonjs",
+  "bin": {
+    "yay": "bin/yay.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "yay": "node bin/yay.js",
+    "test": "node test/run.js",
+    "test:smoke": "node test/smoke.js",
+    "confirm": "node test/confirm.js",
+    "example": "node bin/yay.js verify --dir examples"
+  },
+  "files": [
+    "bin",
+    "src",
+    "standard/STANDARD.md",
+    "CONSTITUTION.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@babel/parser": "^7.29.8",
+    "qrcode-terminal": "^0.12.0"
+  },
+  "optionalDependencies": {
+    "@babel/core": "^7.29.7",
+    "@babel/plugin-transform-react-jsx": "^7.29.7",
+    "@babel/plugin-transform-typescript": "^7.29.7"
+  }
+}

package/src/adopt.js

@@ -0,0 +1,181 @@
+'use strict';
+// `yay adopt` — retrofit: insert DRAFT, unsigned spec blocks above every named
+// unit (function, method, arrow-prop, class method — at any nesting depth) that
+// doesn't have one yet, using the AST analyzer. Falls back to a shallow top-level
+// regex for files the parser can't handle (rare — severe syntax errors only).
+//
+// Deriving real `intent` prose from behaviour needs an LLM (roadmap); this wires
+// up the structure, ids, indentation and a purity guess.
+
+const fs = require('fs');
+const path = require('path');
+const { walk, repoRoot, MARK_BEGIN, langOf, commentLeadOf } = require('./util');
+const { analyze, nearestUnitAfter } = require('./analyze');
+const { extractFile } = require('./extract');
+const IDS = require('./ids');
+
+const JS_LIKE = /\.(js|jsx|mjs|cjs|ts|tsx)$/;
+const ADOPT_FAMILIES = new Set(['js', 'brace', 'python', 'ruby']); // langs `yay adopt` can scaffold
+// Purity GUESS per language family (drafts only — the human prunes; verify re-checks).
+const EFFECT = /\blocalStorage\b|\bconsole\s*\.|\bfetch\s*\(|\bprocess\s*\.|\bdocument\b|\bwindow\b|\bfs\s*\.|\bMath\.random\b|\bDate\.now\b/;
+const EFFECT_PY = /\bprint\s*\(|\binput\s*\(|\bopen\s*\(|\bos\s*\.|\bsys\s*\.|\bsubprocess\s*\.|\bsocket\s*\.|\brequests\s*\.|\burllib\b|\brandom\s*\.|\btime\s*\.\s*time\s*\(|\bdatetime\b.*\bnow\s*\(|^\s*global\s+[A-Za-z_]/m;
+const EFFECT_RB = /\bputs\b|\bgets\b|\bFile\s*\.|\bIO\s*\.|\b\$std(out|in|err)\b|\brand\b|\bTime\s*\.\s*now\b|\bNet::|\bsystem\s*\(/;
+function effectGuess(lang, body) {
+  const l = String(lang || '').toLowerCase();
+  const re = /^py(thon)?w?$/.test(l) ? EFFECT_PY : /^(rb|ruby|ex|exs)$/.test(l) ? EFFECT_RB : EFFECT;
+  return re.test(body || '');
+}
+const TOP_FN = /^(?:export\s+)?(?:async\s+)?function\s+([A-Za-z0-9_$]+)|^(?:export\s+)?(?:const|let|var)\s+([A-Za-z0-9_$]+)\s*=\s*(?:async\s*)?\(/;
+
+function existingIds(root) {
+  const ids = new Set();
+  for (const f of walk(root)) {
+    let t; try { t = fs.readFileSync(f, 'utf8'); } catch (_) { continue; }
+    let m; const re = new RegExp(MARK_BEGIN.source, 'g');
+    while ((m = re.exec(t))) ids.add(m[1]);
+  }
+  return ids;
+}
+// With a per-contributor `shard`, new ids are C-<shard>-<n>, monotonic and never reused (see ids.js)
+// so parallel branches never collide. Without one, the legacy flat C-NNN scheme (single-writer repos).
+function nextId(ids, shard) {
+  if (shard) return IDS.nextCellId(shard, ids);
+  let n = 1;
+  for (;;) { const id = 'C-' + String(n).padStart(3, '0'); if (!ids.has(id)) { ids.add(id); return id; } n++; }
+}
+
+function draftBlock(id, name, lang, body, indent, lead) {
+  const pure = effectGuess(lang, body) ? 'no' : 'yes';
+  const p = indent || '';
+  const cc = lead || '//'; // comment lead: '#' for Python, '//' elsewhere
+  return [
+    `${p}${cc}∷YAY⟨${id}⟩ v0  DERIVED — unconfirmed, not human-reviewed`,
+    `${p}${cc}  unit:    ${name}`,
+    `${p}${cc}  lang:    ${lang}`,
+    `${p}${cc}  intent:  TODO — describe what this does in one sentence [inferred]`,
+    `${p}${cc}  pure:    ${pure}`,
+    `${p}${cc}  in:      TODO`,
+    `${p}${cc}  out:     TODO`,
+    `${p}${cc}∷YAY-END⟨${id}⟩`,
+  ].join('\n');
+}
+
+// Conservative, keyword-led declaration patterns per body-FAMILY: indent in group 1,
+// unit name in group 2. Same safety stance as manifest's untracked scan — anchored on
+// declaration keywords or an access modifier, never control-flow, so `yay adopt` can't
+// scaffold a bogus unit. Families with no safe pattern here are simply not scaffolded.
+const ADOPT_PATS = {
+  python: [/^(\s*)(?:async\s+)?def\s+([A-Za-z_][A-Za-z0-9_]*)/],
+  ruby: [/^(\s*)(?:def|defp)\s+(?:self\.)?([A-Za-z_][A-Za-z0-9_?!]*)/],
+  brace: [
+    /^(\s*)(?:pub\s+|export\s+|public\s+|private\s+|protected\s+|internal\s+|static\s+|final\s+|open\s+|override\s+|async\s+)*(?:fn|func|fun|function|sub)\s+([A-Za-z_][A-Za-z0-9_]*)/,
+    /^(\s*)(?:public|private|protected|internal)(?:\s+(?:static|virtual|override|sealed|abstract|async|partial|new|readonly|unsafe|extern|final))*\s+[A-Za-z_][A-Za-z0-9_<>[\],.?]*\s+([A-Za-z_][A-Za-z0-9_]*)\s*(?:<[^>]*>)?\s*\(/,
+  ],
+};
+
+// Retrofit a non-JS file: insert a DRAFT block above each un-specced unit, using the
+// language's comment lead. Skips units already governed by a spec block.
+function adoptFileLang(file, ids, dry, fam, shard) {
+  const pats = ADOPT_PATS[fam];
+  if (!pats) return 0;
+  const lead = commentLeadOf(file);
+  const langStr = path.extname(file).slice(1);
+  const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/);
+  const covered = new Set();
+  for (const c of extractFile(file)) { if (!c.malformed && c.unitName) covered.add(c.unitName); }
+  const out = [];
+  let added = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const t = lines[i].trim();
+    const isComment = t.startsWith('//') || t.startsWith('#') || t.startsWith('/*') || t.startsWith('*');
+    const prev = lines[i - 1] || '';
+    if (!isComment && !/∷YAY-END|∷YAY⟨/.test(prev)) {
+      for (const pat of pats) {
+        const m = lines[i].match(pat);
+        if (!m) continue;
+        const indent = m[1] || '';
+        const name = m[2];
+        if (name && !covered.has(name)) {
+          out.push(draftBlock(nextId(ids, shard), name, langStr, lines.slice(i, i + 25).join('\n'), indent, lead));
+          covered.add(name);
+          added++;
+        }
+        break; // first matching pattern wins for this line
+      }
+    }
+    out.push(lines[i]);
+  }
+  if (added && !dry) fs.writeFileSync(file, out.join('\n'));
+  return added;
+}
+
+function adoptFile(file, ids, dry, shard) {
+  const fam = langOf(file);
+  if (fam !== 'js') return adoptFileLang(file, ids, dry, fam, shard); // brace / python / ruby
+  const lang = path.extname(file).slice(1);
+  const code = fs.readFileSync(file, 'utf8');
+  const lines = code.split(/\r?\n/);
+  const ana = analyze(code);
+  if (!ana.ok) return adoptFileRegex(file, ids, dry, lines, lang, shard); // unparseable (rare)
+
+  // Units already governed by an existing Cell (skip those).
+  const covered = new Set();
+  for (const c of extractFile(file)) {
+    if (c.malformed) continue;
+    const u = nearestUnitAfter(ana.units, c.endLine);
+    if (u) covered.add(u.startLine);
+  }
+
+  const inserts = [];
+  for (const u of ana.units) {
+    if (covered.has(u.startLine)) continue;
+    const indent = (lines[u.startLine - 1].match(/^\s*/) || [''])[0];
+    const body = lines.slice(u.startLine - 1, u.endLine).join('\n');
+    inserts.push({ line: u.startLine, text: draftBlock(nextId(ids, shard), u.name, lang, body, indent) });
+  }
+  if (!inserts.length) return 0;
+  if (!dry) {
+    inserts.sort((a, b) => b.line - a.line); // bottom-to-top keeps line numbers valid
+    const out = lines.slice();
+    for (const ins of inserts) out.splice(ins.line - 1, 0, ins.text);
+    fs.writeFileSync(file, out.join('\n'));
+  }
+  return inserts.length;
+}
+
+// Shallow fallback for files the parser cannot handle.
+function adoptFileRegex(file, ids, dry, lines, lang, shard) {
+  const out = [];
+  let added = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(TOP_FN);
+    const prev = lines[i - 1] || '';
+    if (m && !/∷YAY-END|∷YAY⟨/.test(prev)) {
+      const name = m[1] || m[2];
+      const indent = (lines[i].match(/^\s*/) || [''])[0];
+      out.push(draftBlock(nextId(ids, shard), name, lang, lines.slice(i, i + 25).join('\n'), indent));
+      added++;
+    }
+    out.push(lines[i]);
+  }
+  if (added && !dry) fs.writeFileSync(file, out.join('\n'));
+  return added;
+}
+
+function adopt(targetDir, { dry = false, shard = null, ledgerIds = [] } = {}) {
+  const root = repoRoot(targetDir);
+  const ids = existingIds(root);
+  // Seed with every id the ledger has ever recorded so a deleted-but-once-signed id is never reused.
+  for (const id of ledgerIds) ids.add(id);
+  const files = walk(path.resolve(targetDir || root)).filter((f) => ADOPT_FAMILIES.has(langOf(f)));
+  const report = [];
+  let total = 0;
+  for (const f of files) {
+    let n = 0;
+    try { n = adoptFile(f, ids, dry, shard); } catch (_) { continue; }
+    if (n) { report.push({ file: path.relative(root, f), added: n }); total += n; }
+  }
+  return { total, report, dry };
+}
+
+module.exports = { adopt };

package/src/adversary.js

@@ -0,0 +1,119 @@
+'use strict';
+// Spec-only adversary — the independent-author layer, done right.
+//
+// The LLM sees ONLY a Cell's spec (never the code) and PROPOSES adversarial INPUTS
+// most likely to violate `ensures`. It does NOT judge. YayLayer's own deterministic
+// checker (the prover's) then runs the REAL function on each proposed input and
+// evaluates the real `ensures`. So a "break" is machine-confirmed — the LLM can't
+// produce a false positive from a bad mock or a wrong expectation; at worst it
+// proposes weak inputs and nothing breaks. Restricted to pure, ensures-bearing Cells
+// (effectful/render Cells are honestly skipped — they need a code-aware/effect test).
+
+const fs = require('fs');
+const path = require('path');
+const { runSource, parseIn, buildChecker, buildEffectChecker, show, ensuresHint } = require('./prove');
+const plan = require('./plan');
+
+const SYSTEM = [
+  'You are an adversarial INPUT generator in a verification system.',
+  'You are given ONLY the formal SPEC of one function — never its source code.',
+  'Propose the input tuples MOST LIKELY to make the function violate its `ensures` postcondition.',
+  '- Every tuple MUST be valid per the `in:` declaration (right arity and types). Do not use out-of-type values.',
+  '- Hunt domain corners the spec does NOT forbid: zero, negative, empty, boundary, very large, duplicates, unordered, extreme ratios, near-equal, etc.',
+  '- You do NOT assert or judge. Return ONLY a JSON array of argument-arrays, e.g. [[0,0],[-1,5],[1000000,1]]. No prose, no code, no comments.',
+].join('\n');
+
+// The spec shown to the model — spec fields ONLY, never the code.
+function specText(cell) {
+  const s = cell.spec || {};
+  const L = ['unit: ' + (cell.unitName || '')];
+  if (s.intent) L.push('intent: ' + s.intent);
+  if (s.in) L.push('in: ' + s.in);
+  if (s.out) L.push('out: ' + s.out);
+  if (s.pure) L.push('pure: ' + s.pure);
+  if (s.records) L.push('records: ' + s.records + '   (this param is instrumented by the harness — pass {} for it; ensures is checked against its recorded calls/sets)');
+  if (s.ensures) L.push('ensures: ' + s.ensures);
+  if (s.throws) L.push('throws: ' + s.throws);
+  return L.join('\n');
+}
+
+function extractJSON(t) {
+  t = String(t || '').trim();
+  const f = t.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (f) t = f[1].trim();
+  const a = t.indexOf('['), b = t.lastIndexOf(']');
+  if (a >= 0 && b > a) t = t.slice(a, b + 1);
+  try { const j = JSON.parse(t); return Array.isArray(j) ? j : []; } catch (_) { return []; }
+}
+
+function eligible(cell) {
+  const s = cell.spec || {};
+  const isLeaf = !(cell.contains && cell.contains.length);
+  const pure = /^yes\b/i.test(s.pure || '');
+  const records = !!(s.records && String(s.records).trim());
+  return isLeaf && cell.unitFound && /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(cell.unitName || '') && !!s.ensures && (pure || records);
+}
+function skipReason(cell) {
+  const s = cell.spec || {};
+  if (cell.contains && cell.contains.length) return 'container Cell (composition, not code)';
+  if (!cell.unitFound) return 'no code unit found below the spec';
+  if (!s.ensures) return 'no machine-checkable `ensures` to judge against';
+  if (!/^yes\b/i.test(s.pure || '') && !(s.records && String(s.records).trim())) return 'has effects — declare the effect surface with `records: <param>` and assert on its trace, so effects become probeable';
+  return 'not adversary-testable';
+}
+
+function fmtArgs(params, A) { return '(' + A.map((v, i) => (params[i] || ('arg' + i)) + '=' + show(v)).join(', ') + ')'; }
+
+// Run the REAL function on the proposed inputs and judge with the real `ensures`.
+function judge(source, cell, tuples) {
+  const base = runSource(source, [cell.unitName]);
+  if (base.error || typeof base.fns[cell.unitName] !== 'function') return { status: 'skip', reason: 'unit not callable in isolation' };
+  const params = parseIn(cell.spec).map((p) => p.name);
+  const records = cell.spec.records && String(cell.spec.records).trim();
+  let checker;
+  try { checker = records ? buildEffectChecker(base.ctx, params, records, cell.spec.ensures) : buildChecker(base.ctx, params, cell.spec.ensures); }
+  catch (e) { return { status: 'skip', reason: 'ensures not machine-checkable — ' + ensuresHint(cell.spec.ensures) + ' (strengthen the spec, then re-sign)' }; }
+  if (!Array.isArray(tuples) || !tuples.length) return { status: 'survived', note: 'no candidate inputs proposed' };
+  const throwsDeclared = !!(cell.spec && cell.spec.throws);
+  const fmt = (A) => '(' + params.map((n, i) => (n === records ? n + '=<recorded>' : n + '=' + show(A[i]))).join(', ') + ')';
+  for (const A of tuples) {
+    if (!Array.isArray(A)) continue;
+    const snap = fmt(A); // format BEFORE the checker instruments/mutates the records slot
+    let r;
+    try { r = checker(base.fns[cell.unitName], A); }
+    catch (e) {
+      if (throwsDeclared) continue; // may be an expected throw — don't judge without an oracle
+      return { status: 'broke', counterexample: 'threw on ' + snap + ' — ' + String((e && e.message) || e).slice(0, 160) };
+    }
+    if (r && r.ok === false) return { status: 'broke', counterexample: 'ensures failed for ' + snap + (records ? '' : ' → out=' + show(r.out)) };
+  }
+  return { status: 'survived' };
+}
+
+// auth: provider config (resolvePlanAuth). opts.cells = id filter; opts.chat = fake LLM for tests.
+async function adversaryManifest(manifest, auth, opts) {
+  opts = opts || {};
+  const chat = opts.chat || plan.chat;
+  const out = {};
+  const byFile = {};
+  for (const id of Object.keys(manifest.cells)) {
+    const c = manifest.cells[id];
+    if (opts.cells && opts.cells.indexOf(id) < 0) continue;
+    if (!eligible(c)) { if (opts.cells) out[id] = { status: 'skip', reason: skipReason(c) }; continue; }
+    (byFile[c.file] = byFile[c.file] || []).push(c);
+  }
+  for (const file of Object.keys(byFile)) {
+    let source; try { source = fs.readFileSync(path.join(manifest.root, file), 'utf8'); }
+    catch (_) { for (const c of byFile[file]) out[c.id] = { status: 'skip', reason: 'file unreadable' }; continue; }
+    for (const c of byFile[file]) {
+      let tuples;
+      try { tuples = extractJSON(await chat(SYSTEM, specText(c), auth)); }
+      catch (e) { out[c.id] = { status: 'error', reason: 'LLM error: ' + (e && e.message ? e.message : String(e)) }; continue; }
+      out[c.id] = judge(source, c, tuples);
+      out[c.id].tried = Array.isArray(tuples) ? tuples.length : 0;
+    }
+  }
+  return out;
+}
+
+module.exports = { adversaryManifest, specText, extractJSON, eligible, skipReason, judge, SYSTEM };

package/src/analyze.js

@@ -0,0 +1,270 @@
+'use strict';
+// AST-based analyzer for JS / TypeScript / JSX / TSX (@babel/parser with the
+// `estree` plugin). Enumerates every NAMED executable unit —
+// function declaration, function expression assigned to a name, arrow-prop,
+// object method, class method/getter/setter — at ANY nesting depth. This is
+// what lets YayLayer see units inside IIFEs, objects and classes (the old regex
+// only saw top-level `function name(`).
+//
+// A "unit" is a named block that does a job. Anonymous inline callbacks
+// (arr.map(x => …), event handlers) are considered part of their enclosing unit,
+// not separate units. Also flags top-level imperative code that runs at load.
+
+const babel = require('@babel/parser');
+const { hasLoadTimeEffect } = require('./util');
+
+// One parser for JS, TypeScript, JSX and TSX. The `estree` plugin makes the AST
+// ESTree-shaped (Literal / Property / MethodDefinition) so the walker below is
+// standard. errorRecovery keeps a partial tree on odd syntax instead of failing.
+const PLUGINS = ['estree', 'typescript', 'jsx', 'decorators-legacy'];
+function parse(code) {
+  try {
+    return babel.parse(code, {
+      sourceType: 'unambiguous', errorRecovery: true,
+      allowReturnOutsideFunction: true, allowImportExportEverywhere: true,
+      plugins: PLUGINS,
+    }).program;
+  } catch (_) { return null; }
+}
+
+function keyName(key) {
+  if (!key) return null;
+  if (key.type === 'Identifier') return key.name;
+  if (key.type === 'Literal') return String(key.value);
+  if (key.type === 'PrivateIdentifier') return '#' + key.name;
+  return null;
+}
+function memberName(node) {
+  if (!node) return null;
+  if (node.type === 'Identifier') return node.name;
+  if (node.type === 'MemberExpression') {
+    const obj = memberName(node.object);
+    const prop = node.computed ? null : keyName(node.property);
+    return prop ? (obj ? obj + '.' + prop : prop) : obj;
+  }
+  return null;
+}
+function className(ancestors) {
+  for (let i = ancestors.length - 1; i >= 0; i--) {
+    const a = ancestors[i];
+    if (a.type === 'ClassDeclaration' || a.type === 'ClassExpression') return a.id ? a.id.name : 'class';
+  }
+  return null;
+}
+
+// Derive a name + kind for a function node from its surrounding context.
+function nameFn(node, ancestors) {
+  const parent = ancestors[ancestors.length - 1];
+  if (node.type === 'FunctionDeclaration' && node.id) return { name: node.id.name, kind: 'function' };
+  if (!parent) return null;
+  const arrowKind = node.type === 'ArrowFunctionExpression' ? 'arrow' : 'function';
+  switch (parent.type) {
+    case 'VariableDeclarator':
+      return parent.id && parent.id.name ? { name: parent.id.name, kind: arrowKind } : null;
+    case 'AssignmentExpression': {
+      const n = memberName(parent.left);
+      return n ? { name: n, kind: arrowKind } : null;
+    }
+    case 'Property': {
+      const n = keyName(parent.key);
+      return n ? { name: n, kind: node.type === 'ArrowFunctionExpression' ? 'arrow' : 'method' } : null;
+    }
+    case 'MethodDefinition': {
+      const n = keyName(parent.key);
+      if (!n) return null;
+      const cls = className(ancestors);
+      const k = parent.kind && parent.kind !== 'method' ? parent.kind : 'method';
+      return { name: (cls ? cls + '.' : '') + n, kind: k };
+    }
+    case 'PropertyDefinition': { // class field: foo = () => {}
+      const n = keyName(parent.key);
+      if (!n) return null;
+      const cls = className(ancestors);
+      return { name: (cls ? cls + '.' : '') + n, kind: 'arrow' };
+    }
+    default:
+      return null; // anonymous — belongs to the enclosing unit
+  }
+}
+
+function walk(node, ancestors, visit) {
+  if (!node || typeof node.type !== 'string') return;
+  visit(node, ancestors);
+  const next = ancestors.concat(node);
+  for (const key of Object.keys(node)) {
+    if (key === 'loc' || key === 'start' || key === 'end' || key === 'range') continue;
+    const child = node[key];
+    if (Array.isArray(child)) { for (const c of child) walk(c, next, visit); }
+    else walk(child, next, visit);
+  }
+}
+
+// The nearest lexical class / object-literal a unit lives in (for real nesting).
+function containerOf(ancestors) {
+  for (let i = ancestors.length - 1; i >= 0; i--) {
+    const a = ancestors[i];
+    if (a.type === 'ClassDeclaration' || a.type === 'ClassExpression') return a.id ? a.id.name : 'class';
+    if (a.type === 'VariableDeclarator' && a.id && a.id.type === 'Identifier' && a.init && a.init.type === 'ObjectExpression') return a.id.name;
+  }
+  return null;
+}
+
+function objectPublicNames(objExpr, out) {
+  if (!objExpr || objExpr.type !== 'ObjectExpression') return;
+  for (const p of objExpr.properties || []) {
+    if (p.type !== 'Property') continue;
+    if (p.value && p.value.type === 'Identifier') out.add(p.value.name); // { getDB: getDB }
+    const k = keyName(p.key); if (k) out.add(k);                          // { getDB() {} } / { getDB }
+  }
+}
+
+// The namespace this module exposes (global.X / window.X / module.exports / return)
+// and the set of unit names that are part of its PUBLIC api.
+function namespaceOf(ast) {
+  const objByVar = {};
+  walk(ast, [], (node) => {
+    if (node.type === 'VariableDeclarator' && node.id && node.id.type === 'Identifier' && node.init && node.init.type === 'ObjectExpression') objByVar[node.id.name] = node.init;
+  });
+  let name = null; const publicNames = new Set();
+  const consider = (exposeName, val) => {
+    let obj = null;
+    if (val && val.type === 'ObjectExpression') obj = val;
+    else if (val && val.type === 'Identifier' && objByVar[val.name]) obj = objByVar[val.name];
+    if (!obj) return;
+    if (exposeName && !name) name = exposeName;
+    objectPublicNames(obj, publicNames);
+  };
+  walk(ast, [], (node) => {
+    if (node.type === 'AssignmentExpression' && node.left && node.left.type === 'MemberExpression' && !node.left.computed) {
+      const o = node.left.object; const prop = keyName(node.left.property);
+      if (o.type === 'Identifier' && (o.name === 'global' || o.name === 'window' || o.name === 'globalThis') && prop) consider(prop, node.right);
+      else if (o.type === 'Identifier' && o.name === 'module' && prop === 'exports') consider(null, node.right);
+    } else if (node.type === 'ReturnStatement' && node.argument) {
+      consider(null, node.argument);
+    } else if (node.type === 'ExportNamedDeclaration') { // ES modules
+      const d = node.declaration;
+      if (d && d.id && d.id.name) publicNames.add(d.id.name);
+      if (d && d.declarations) for (const v of d.declarations) if (v.id && v.id.name) publicNames.add(v.id.name);
+      for (const s of node.specifiers || []) if (s.local && s.local.name) publicNames.add(s.local.name);
+    } else if (node.type === 'ExportDefaultDeclaration') {
+      if (node.declaration && node.declaration.id && node.declaration.id.name) publicNames.add(node.declaration.id.name);
+    }
+  });
+  return { name, publicNames };
+}
+
+const FN_TYPES = new Set(['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression']);
+
+function isIIFE(node) {
+  if (node.type !== 'ExpressionStatement') return false;
+  let e = node.expression;
+  while (e && (e.type === 'UnaryExpression' || e.type === 'AwaitExpression')) e = e.argument;
+  return !!(e && e.type === 'CallExpression' && e.callee && FN_TYPES.has(e.callee.type));
+}
+function isDirective(node) {
+  return node.type === 'ExpressionStatement' && node.expression &&
+    node.expression.type === 'Literal' && typeof node.expression.value === 'string';
+}
+function looseTopLevel(ast, code) {
+  // Always-skip: definitions, imports/exports, empty. (A function/class DEFINITION that
+  // contains fetch is fine — it isn't executed at load; it's handled as a unit elsewhere.)
+  const SKIP = new Set(['FunctionDeclaration', 'ClassDeclaration',
+    'ImportDeclaration', 'ExportDefaultDeclaration', 'ExportAllDeclaration', 'EmptyStatement']);
+  // Wiring that's exempt UNLESS its right-hand side runs an exfil/exec effect at import
+  // (`const LEAK = fetch(evil)`, `X = require('cp').execSync(...)`): declarations, named
+  // exports (which wrap a declaration), and bare assignments (module.exports = …, X = Y).
+  const out = [];
+  for (const node of ast.body) {
+    if (SKIP.has(node.type) || isDirective(node) || isIIFE(node)) continue;
+    const isDecl = node.type === 'VariableDeclaration' || node.type === 'ExportNamedDeclaration';
+    const isAssign = node.type === 'ExpressionStatement' && node.expression && node.expression.type === 'AssignmentExpression';
+    if (isDecl || isAssign) {
+      if (code && node.start != null && node.end != null && hasLoadTimeEffect(code.slice(node.start, node.end), 'js')) out.push(node.loc.start.line);
+      continue;
+    }
+    out.push(node.loc.start.line);
+  }
+  return out;
+}
+
+// Returns { ok, units:[{name,kind,startLine,endLine}], loose:[line,…] }.
+// ok:false means the file could not be parsed (e.g. TypeScript) — caller degrades.
+function calleeName(callee) {
+  if (!callee) return null;
+  if (callee.type === 'Identifier') return callee.name;
+  if (callee.type === 'MemberExpression' && !callee.computed) return keyName(callee.property);
+  return null;
+}
+
+function analyze(code) {
+  const ast = parse(code);
+  if (!ast) return { ok: false, units: [], loose: [], calls: [], bindings: [], namespace: { name: null, publicNames: new Set() } };
+  const units = [];
+  const seen = new Set();
+  const calls = new Set(); // short callee names used anywhere in the file → for the call graph
+  const unitByNode = new Map(); // function AST node → its unit record (for unit-level calls)
+  walk(ast, [], (node, ancestors) => {
+    if (node.type === 'CallExpression') {
+      const cn = calleeName(node.callee);
+      // A DIRECT call `foo(...)` (bare identifier) is resolvable to a definition;
+      // a member call `obj.foo(...)` is a method and can't be resolved statically.
+      const direct = node.callee && node.callee.type === 'Identifier' ? node.callee.name : null;
+      if (cn) {
+        calls.add(cn);
+        // Attribute this call to the innermost named unit that encloses it, so we
+        // get a UNIT-level call graph (who calls whom), not just a file-level one.
+        for (let i = ancestors.length - 1; i >= 0; i--) {
+          const rec = unitByNode.get(ancestors[i]);
+          if (rec) { rec.callsOut.add(cn); if (direct) rec.callsDirect.add(direct); break; }
+        }
+      }
+      return;
+    }
+    if (!FN_TYPES.has(node.type)) return;
+    const named = nameFn(node, ancestors);
+    if (!named) return;
+    const key = named.name + '@' + node.loc.start.line;
+    if (seen.has(key)) return;
+    seen.add(key);
+    const rec = { name: named.name, kind: named.kind, startLine: node.loc.start.line, endLine: node.loc.end.line, container: containerOf(ancestors), callsOut: new Set(), callsDirect: new Set() };
+    units.push(rec);
+    unitByNode.set(node, rec); // pre-order: a unit is recorded before we descend into its body
+  });
+  units.sort((a, b) => a.startLine - b.startLine);
+  for (const u of units) { u.callsOut = [...u.callsOut]; u.callsDirect = [...u.callsDirect]; }
+  return { ok: true, units, loose: looseTopLevel(ast, code), calls: [...calls], bindings: collectBindings(ast), namespace: namespaceOf(ast) };
+}
+
+// Every name BOUND anywhere in the file (function/class ids, variable declarators,
+// params — incl. destructured — imports, catch params). Used to decide whether a
+// direct call resolves to something defined (vs a dangling reference / typo).
+function collectBindings(ast) {
+  const b = new Set();
+  const addPat = (p) => {
+    if (!p) return;
+    if (p.type === 'Identifier') b.add(p.name);
+    else if (p.type === 'ObjectPattern') (p.properties || []).forEach((pr) => addPat(pr.value || pr.argument));
+    else if (p.type === 'ArrayPattern') (p.elements || []).forEach(addPat);
+    else if (p.type === 'AssignmentPattern') addPat(p.left);
+    else if (p.type === 'RestElement') addPat(p.argument);
+  };
+  walk(ast, [], (node) => {
+    if (node.type === 'FunctionDeclaration' || node.type === 'FunctionExpression' || node.type === 'ArrowFunctionExpression') { if (node.id) b.add(node.id.name); (node.params || []).forEach(addPat); }
+    else if (node.type === 'ClassDeclaration' || node.type === 'ClassExpression') { if (node.id) b.add(node.id.name); }
+    else if (node.type === 'VariableDeclarator') addPat(node.id);
+    else if (node.type === 'ImportDefaultSpecifier' || node.type === 'ImportNamespaceSpecifier' || node.type === 'ImportSpecifier') { if (node.local) b.add(node.local.name); }
+    else if (node.type === 'CatchClause') addPat(node.param);
+  });
+  return [...b];
+}
+
+// The unit a Cell governs = the nearest unit starting just after the marker.
+function nearestUnitAfter(units, afterLine, gap = 6) {
+  for (const u of units) { // units are sorted ascending by startLine
+    if (u.startLine > afterLine && u.startLine - afterLine <= gap) return u;
+    if (u.startLine > afterLine + gap) break;
+  }
+  return null;
+}
+
+module.exports = { analyze, nearestUnitAfter };