@precedence-dev/instrument 0.1.0

package/dist/generate/instrument.js

@@ -0,0 +1,665 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PM_ID_KEY = void 0;
+exports.planFiles = planFiles;
+exports.safeStatement = safeStatement;
+exports.reanchor = reanchor;
+exports.instrument = instrument;
+exports.instrumentFile = instrumentFile;
+exports.planDelegations = planDelegations;
+exports.buildDelegatedModule = buildDelegatedModule;
+/**
+ * The instrumenter core. Given the analysed source + a tracking plan (the events
+ * a PM defined in the picker / viewer), work out where a `track(…)` call goes
+ * and splice it in.
+ *
+ * Two entry points share one resolver:
+ *   instrument(inputs, plan, opts)        multi-file: the CLI codemod (writes to disk)
+ *   instrumentFile(code, id, plan, opts)  one module: the bundler transform (src/generate/unplugin.ts)
+ *
+ * It re-runs the same `@precedence-dev/cli` `analyze()` the catalog is built from,
+ * so every id / `InjectSite` / fingerprint is produced by one code path — this
+ * package never re-derives that analysis itself, it only asks the (private)
+ * analysis engine to reproduce it and applies the resulting edits. Edits go
+ * through MagicString, so callers get a sourcemap.
+ *
+ * Three outcomes per anchor, not two:
+ *   applied         id resolved, fingerprint matches
+ *   applied+drift   id resolved but the handler changed since the plan; injected, with a warning
+ *   skipped         id does not resolve; the message says precisely what is missing
+ */
+const ts = __importStar(require("typescript"));
+const magic_string_1 = __importDefault(require("magic-string"));
+const build_1 = require("@precedence-dev/cli/build");
+const ast_1 = require("@precedence-dev/cli/ast");
+const parse_1 = require("@precedence-dev/cli/parse");
+/** where a handler's own `track(...)` call goes, from its body shape. */
+function handlerSite(body, synthetic) {
+    if (synthetic)
+        return { kind: "delegated" };
+    if (body && ts.isBlock(body))
+        return { kind: "block-prepend", block: body };
+    if (body)
+        return { kind: "wrap-expr", expr: body };
+    return { kind: "none" };
+}
+/** index every branch (recursively) under one element by its structural id. */
+function indexBranches(map, L, el, bs) {
+    for (const b of bs) {
+        map.set(b.id, {
+            id: b.id, file: (0, build_1.norm)(L.file), line: b.anchorLine || el.line + 1, sf: L.sf,
+            element: el.tag, site: b.site, fingerprint: b.fingerprint, elementNode: el.scopeNode,
+        });
+        indexBranches(map, L, el, b.children || []);
+    }
+}
+function attachIndex(loaded) {
+    const map = new Map();
+    for (const L of loaded) {
+        for (const el of L.elements) {
+            for (const h of el.handlers) {
+                const an = L.handlers.get(h);
+                if (!an)
+                    continue;
+                map.set(h.actionId, {
+                    id: h.actionId, file: (0, build_1.norm)(L.file), line: el.line + 1, sf: L.sf,
+                    element: el.tag, autoAttrs: h.autoProps || [], fingerprint: h.fingerprint,
+                    elementNode: el.scopeNode,
+                    site: handlerSite(h.body, h.synthetic),
+                });
+                indexBranches(map, L, el, an.branches);
+            }
+        }
+    }
+    return map;
+}
+/** the id shape the previous (positional) catalog produced, `…tsx:12:5|…` */
+function isPositionalId(id) {
+    return /:\d+:\d+(\||$)/.test(id.split("|")[0]);
+}
+/** the source-file portion of an anchor id, `src/x.tsx#Comp::slot|…` → `src/x.tsx` */
+function anchorFile(id) {
+    return (0, build_1.norm)(id.split(/[#|]/)[0]);
+}
+/** every distinct source file a plan references */
+function planFiles(plan) {
+    const set = new Set();
+    for (const ev of plan.events)
+        for (const a of ev.anchors) {
+            const f = anchorFile(a.id);
+            if (f && !/:\d+:\d+/.test(f))
+                set.add(f);
+        }
+    return [...set];
+}
+/** which plan file (if any) a bundler module id corresponds to */
+function matchPlanFile(id, plan) {
+    const clean = (0, build_1.norm)(id.split("?")[0]);
+    for (const f of planFiles(plan))
+        if (clean === f || clean.endsWith("/" + f))
+            return f;
+    return null;
+}
+/** why an id failed to resolve, walk the structural id as far as the source allows */
+function diagnoseMiss(id, loaded, index) {
+    const [refPart, event, path] = id.split("|");
+    const m = refPart.match(/^(.+)#([^#]*)::(.+)$/);
+    if (!m)
+        return "unrecognised anchor id; re-export the plan from the picker";
+    const [, file, comp, slot] = m;
+    const L = loaded.find((x) => (0, build_1.norm)(x.file) === (0, build_1.norm)(file) || (0, build_1.norm)(x.file).endsWith("/" + (0, build_1.norm)(file)));
+    if (!L)
+        return `file "${file}" was not among the scanned sources`;
+    const comps = [...new Set(L.elements.map((e) => e.component || "_"))];
+    if (!comps.includes(comp))
+        return `component "${comp}" not in ${file} (has: ${comps.join(", ")}); if it was renamed, \`precedence-instrument --reanchor\` can repair the plan`;
+    const slots = L.elements.filter((e) => (e.component || "_") === comp).map((e) => e.ref.split("::")[1]);
+    if (!slots.includes(slot))
+        return `element "${slot}" not in <${comp}> (has: ${slots.join(", ") || "none"})`;
+    const elem = L.elements.find((e) => e.ref === refPart || (0, build_1.norm)(e.ref).endsWith("/" + refPart));
+    if (elem && !elem.handlers.some((h) => h.name === event))
+        return `no "${event}" handler on ${slot} (has: ${elem.handlers.map((h) => h.name).join(", ") || "none"})`;
+    if (path) {
+        const prefix = `${refPart}|${event}|`;
+        const sibs = [...index.keys()].filter((k) => k.startsWith(prefix)).map((k) => k.slice(prefix.length));
+        return `branch "${path}" not found (handler has: ${sibs.join(", ") || "no branches"})`;
+    }
+    return "attach point not found; the catalog is stale, regenerate it";
+}
+/* -------------------------------------------------------------- the call */
+function obj(parts) {
+    return parts.length ? `, { ${parts.join(", ")} }` : "";
+}
+/** the nearest enclosing component function of a node */
+function nearestComponent(node) {
+    for (let n = node?.parent; n; n = n.parent) {
+        if (ts.isFunctionDeclaration(n) && n.name && /^[A-Z]/.test(n.name.text))
+            return n;
+        if ((ts.isArrowFunction(n) || ts.isFunctionExpression(n)) && ts.isVariableDeclaration(n.parent)
+            && ts.isIdentifier(n.parent.name) && /^[A-Z]/.test(n.parent.name.text))
+            return n;
+    }
+    return null;
+}
+/** resolve a context field to an expression, using a binding the component
+ *  already has. No auto-hoist: if the hook is not bound, warn and emit undefined. */
+function resolveContextAccessor(ap, via, out, evName) {
+    const comp = nearestComponent(ap.elementNode);
+    if (!comp)
+        return `undefined /* no component around this anchor */`;
+    let bare = null;
+    let destructured = false;
+    const head = via.path.split(".")[0];
+    (function w(n) {
+        if (ts.isVariableDeclaration(n) && n.initializer && ts.isCallExpression(n.initializer)
+            && ts.isIdentifier(n.initializer.expression) && n.initializer.expression.text === via.hook) {
+            if (ts.isIdentifier(n.name))
+                bare = n.name.text;
+            else if (ts.isObjectBindingPattern(n.name)) {
+                destructured = destructured || n.name.elements.some((e) => {
+                    const k = e.propertyName && ts.isIdentifier(e.propertyName) ? e.propertyName.text
+                        : ts.isIdentifier(e.name) ? e.name.text : "";
+                    return k === head;
+                });
+            }
+        }
+        ts.forEachChild(n, w);
+    })(comp);
+    if (destructured)
+        return via.path; // `isAuthed` already in scope
+    if (bare)
+        return `${bare}.${via.path}`; // `auth.isAuthed`
+    out.warnings.push({
+        event: evName, id: ap.id,
+        detail: `"${via.path}" needs \`${via.hook}()\` bound in the component, add \`const _ = ${via.hook}()\` there, or drop the prop`,
+    });
+    return `undefined /* ${via.hook}() not bound in this component */`;
+}
+/** how to render one property in the call object */
+function propPart(p, ev, anchor) {
+    const stat = anchor.staticProps || {};
+    if (p in stat)
+        return `${p}: ${JSON.stringify(stat[p])}`;
+    const acc = ev.accessors && ev.accessors[p];
+    if (typeof acc === "string")
+        return acc === p ? p : `${p}: ${acc}`;
+    if ((anchor.missingProps || []).includes(p))
+        return `${p}: undefined /* not in scope here */`;
+    return p; // shorthand, the picker checked it resolves
+}
+/** every emitted event carries the anchor id under this key, so a value seen in
+ *  the dashboard can be traced back to the exact fire site (file/component/branch). */
+exports.PM_ID_KEY = "pm_id";
+/** direct mode: `track("event_name", { pm_id: "<id>", …everything baked in })` */
+function directCall(fnName, ev, anchor) {
+    const seen = new Set();
+    const parts = [...new Set(ev.properties)].map((p) => { seen.add(p); return propPart(p, ev, anchor); });
+    Object.keys(anchor.staticProps || {}).forEach((k) => { if (!seen.has(k))
+        parts.push(`${k}: ${JSON.stringify((anchor.staticProps || {})[k])}`); });
+    if (!seen.has(exports.PM_ID_KEY) && !(exports.PM_ID_KEY in (anchor.staticProps || {})))
+        parts.unshift(`${exports.PM_ID_KEY}: ${JSON.stringify(anchor.id)}`);
+    return `${fnName}(${JSON.stringify(ev.name)}${obj(parts)})`;
+}
+/** runtime mode: `globalThis.__pm?.("<id>", { …in-scope + ambient props })`.
+ *  the id is arg 1 — the runtime layers it onto the payload as `pm_id` at emit
+ *  time, along with static / discriminator props from the plan. */
+function runtimeCall(g, ev, anchor) {
+    const skip = new Set([...Object.keys(anchor.staticProps || {}), ...(anchor.missingProps || [])]);
+    const parts = [...new Set(ev.properties)].filter((p) => !skip.has(p)).map((p) => propPart(p, ev, anchor));
+    return `${g}?.(${JSON.stringify(anchor.id)}${obj(parts)})`;
+}
+function emitCall(ev, anchor, opts, fnName) {
+    return opts.emit === "runtime"
+        ? runtimeCall(opts.emitGlobal || "globalThis.__pm", ev, anchor)
+        : directCall(fnName, ev, anchor);
+}
+function indentAt(sf, pos) {
+    const lineStart = sf.text.lastIndexOf("\n", pos - 1) + 1;
+    return (sf.text.slice(lineStart, pos).match(/^\s*/) || [""])[0];
+}
+function enclosingStatement(n) {
+    let x = n;
+    while (x.parent && !ts.isStatement(x))
+        x = x.parent;
+    return x;
+}
+function assertNever(x) {
+    throw new Error("unhandled inject site: " + JSON.stringify(x));
+}
+/**
+ * Wrap the raw tracking call so it can never affect the surrounding control
+ * flow: a synchronous throw is caught and swallowed, and if it returns a
+ * thenable, a rejection is swallowed too — fire-and-forget, provably, not just
+ * assumed. This try/catch only ever wraps code we just inserted, never
+ * anything that existed before it, so — unlike wrapping a customer's own
+ * existing logic in a new try/catch — it cannot change what any pre-existing
+ * code does; there is no prior behavior here to disturb.
+ */
+// exported for direct unit tests (test/invariants.mjs) — the fire-and-forget
+// guarantee is checked by actually running the wrapped text, not by pattern
+// matching the source of a full instrument() call.
+function safeStatement(call) {
+    // Promise.resolve covers void / Promise / thenable clients and, unlike `.catch`
+    // on an inferred `void`, type-checks in a strict consumer project.
+    return `try { void Promise.resolve(${call}).catch(() => {}); } catch (__pmE) {}`;
+}
+/** the same guard, as a single expression — for sites where `call` has to sit
+ *  inside a larger expression (a comma operator) rather than stand alone. */
+function safeExpr(call) {
+    return `(() => { ${safeStatement(call)} })()`;
+}
+/** the one place a syntactic context meets an AST edit; total over InjectSite,
+ *  so a new branch shape is a compile error here until it's handled. */
+function planEdit(site, call, sf) {
+    switch (site.kind) {
+        case "block-prepend": {
+            const open = site.block.getStart(sf) + 1;
+            const ind = site.block.statements.length
+                ? indentAt(sf, site.block.statements[0].getStart(sf))
+                : indentAt(sf, site.block.getStart(sf)) + "  ";
+            return [{ start: open, end: open, text: `\n${ind}${safeStatement(call)}` }];
+        }
+        case "before-stmt": {
+            const start = site.stmt.getStart(sf);
+            const ind = indentAt(sf, start);
+            return [{ start, end: start, text: `${safeStatement(call)}\n${ind}` }];
+        }
+        case "synthesize-else": {
+            const then = site.ifStmt.thenStatement;
+            const ind = indentAt(sf, site.ifStmt.getStart(sf));
+            return [{ start: then.getEnd(), end: then.getEnd(), text: ` else {\n${ind}  ${safeStatement(call)}\n${ind}}` }];
+        }
+        case "split-and": {
+            const bin = site.expr;
+            const stmt = enclosingStatement(bin);
+            const parts = (0, ast_1.flattenLogical)(bin, "&&");
+            const guards = parts.slice(0, -1).map((p) => p.getText(sf)).join(" && ");
+            const effect = parts[parts.length - 1].getText(sf);
+            const ind = indentAt(sf, stmt.getStart(sf));
+            return [{
+                    start: stmt.getStart(sf), end: stmt.getEnd(),
+                    text: `if (${guards}) {\n${ind}  ${safeStatement(call)}\n${ind}  ${effect};\n${ind}}`,
+                }];
+        }
+        case "wrap-expr": {
+            const t = site.expr.getText(sf);
+            return [{ start: site.expr.getStart(sf), end: site.expr.getEnd(), text: `(${safeExpr(call)}, ${t})` }];
+        }
+        case "delegated":
+        case "none":
+            return [];
+        default:
+            return assertNever(site);
+    }
+}
+function parseTrack(track) {
+    const m = track.match(/^\s*([A-Za-z_$][\w$]*)\s+from\s+(.+?)\s*$/);
+    if (!m)
+        return { fnName: track.trim() || "track", importLine: "", spec: "" };
+    const spec = m[2].replace(/^['"]|['"]$/g, "");
+    return { fnName: m[1], importLine: `import { ${m[1]} } from ${JSON.stringify(spec)};\n`, spec };
+}
+/** add `import { track } from "spec"` unless the file already has it */
+function addImport(s, code, track) {
+    const { fnName, spec } = parseTrack(track);
+    if (!spec)
+        return;
+    const re = new RegExp(`import\\s*\\{[^}]*\\b${fnName}\\b[^}]*\\}\\s*from\\s*['"]${spec.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}['"]`);
+    if (re.test(code))
+        return;
+    const line = `import { ${fnName} } from ${JSON.stringify(spec)};`;
+    // after the last `import … "spec";` (spans multi-line lists, matches side-effect imports)
+    const lastImp = [...code.matchAll(/^import\b[\s\S]*?['"][^'"]*['"]\s*;?/gm)].pop();
+    if (lastImp && lastImp.index != null)
+        s.appendLeft(lastImp.index + lastImp[0].length, "\n" + line);
+    else
+        s.prepend(line + "\n");
+}
+/** apply edits to one file via MagicString → { code, map } */
+function render(code, edits, id, opts) {
+    const s = new magic_string_1.default(code);
+    for (const e of edits) {
+        if (e.start === e.end)
+            s.appendLeft(e.start, e.text);
+        else
+            s.overwrite(e.start, e.end, e.text);
+    }
+    // direct mode needs the `track` import, unless the only edits are `data-precedence-id`
+    // stamps. runtime mode calls a global, so it never needs one.
+    if (opts.emit !== "runtime" && edits.some((e) => e.kind !== "stamp"))
+        addImport(s, code, opts.track || "track");
+    return {
+        code: s.toString(),
+        map: s.generateMap({ source: id, hires: true, includeContent: true }),
+    };
+}
+/** resolve + verify + plan-edit one anchor, appending its results to `out`. */
+function collectAnchor(a, ev, index, loaded, opts, fnName, out) {
+    const ap = resolveAnchor(a, ev, index, loaded, out, opts);
+    if (!ap)
+        return;
+    const drifted = recordDrift(a, ap, ev, out);
+    const evR = ev.accessors ? resolveEventAccessors(ev, ap, out) : ev;
+    const call = emitCall(evR, a, opts, fnName);
+    if (ap.site.kind === "delegated")
+        applyDelegated(a, ev, ap, out);
+    else
+        applyInlineEdit(a, ev, ap, call, drifted, out);
+}
+/** resolve + verify + plan-edit every plan anchor (optionally just one file's) */
+function collect(plan, index, loaded, opts, fnName, onlyFile) {
+    const out = { byFile: new Map(), applied: [], skipped: [], warnings: [], delegated: [] };
+    for (const ev of plan.events) {
+        for (const a of ev.anchors) {
+            if (!onlyFile || anchorFile(a.id) === onlyFile) {
+                collectAnchor(a, ev, index, loaded, opts, fnName, out);
+            }
+        }
+    }
+    return out;
+}
+/** an anchor id, exactly or by ref tail, or null after pushing a precise `skipped`.
+ *  No fuzzy matching: a dead id means the code the PM pointed at moved on, and
+ *  that's for a human (`--reanchor` for a rename, the picker for a real refactor). */
+const CONTINUATION_KEY = /^(RESOLVED|REJECTED|SETTLED)$/;
+function resolveAnchor(a, ev, index, loaded, out, opts) {
+    const ap = index.get(a.id) || resolveLoosely(a.id, index);
+    if (ap)
+        return ap;
+    const isContinuation = CONTINUATION_KEY.test(a.fingerprint?.conditionKey || "")
+        || /\|(resolved|rejected|settled)$/.test(a.id);
+    out.skipped.push({
+        event: ev.name, id: a.id,
+        reason: isPositionalId(a.id)
+            ? "plan uses old positional ids; re-export from the picker against a current catalog"
+            : isContinuation && !opts.types
+                ? "continuation outcome (the callback edge rule) — re-run with --types so the callback classification is reproduced"
+                : diagnoseMiss(a.id, loaded, index),
+    });
+    return null;
+}
+/** warn when the branch's condition changed since the plan was authored.
+ *  returns `true` if this anchor is drifted, else `undefined` (never `false`). */
+function recordDrift(a, ap, ev, out) {
+    const fp = a.fingerprint;
+    if (fp && fp.conditionKey && ap.fingerprint.conditionKey && fp.conditionKey !== ap.fingerprint.conditionKey) {
+        out.warnings.push({ event: ev.name, id: a.id, detail: `branch condition changed since the plan: "${fp.conditionKey}" → "${ap.fingerprint.conditionKey}"; verify ${ap.file}:${ap.line}` });
+    }
+    return out.warnings.some((w) => w.id === a.id) || undefined;
+}
+/** resolve this event's context-field accessors against the anchor's component -> plain exprs */
+function resolveEventAccessors(ev, ap, out) {
+    return {
+        ...ev,
+        accessors: Object.fromEntries(Object.entries(ev.accessors).map(([p, acc]) => [p, typeof acc === "string" ? acc : resolveContextAccessor(ap, acc, out, ev.name)])),
+    };
+}
+/** a synthetic (link / bare-button) anchor: one delegated-listener row + a
+ *  `data-precedence-id="<id>"` stamp so the listener can identify the element at runtime. */
+function applyDelegated(a, ev, ap, out) {
+    const statKeys = new Set(Object.keys(a.staticProps || {}));
+    out.delegated.push({
+        event: ev.name, element: ap.element, ref: ap.id, // the structural id, the runtime join key
+        attrs: (ap.autoAttrs && ap.autoAttrs.length ? ap.autoAttrs : (ev.properties || [])).filter((p) => !statKeys.has(p)),
+        props: a.staticProps || {},
+    });
+    const en = ap.elementNode;
+    if (!en || !(ts.isJsxOpeningElement(en) || ts.isJsxSelfClosingElement(en)))
+        return;
+    const already = en.attributes.properties.some((p) => ts.isJsxAttribute(p) && p.name.getText() === "data-precedence-id");
+    if (already)
+        return;
+    const at = en.tagName.getEnd();
+    const list = out.byFile.get(ap.file) || [];
+    list.push({ start: at, end: at, text: ` data-precedence-id=${JSON.stringify(ap.id)}`, kind: "stamp" });
+    out.byFile.set(ap.file, list);
+}
+/** true when a previous run already spliced this anchor's call into the file.
+ *  Direct mode writes `pm_id: "<id>"`, runtime mode passes the id as arg 1, and
+ *  the anchor id is globally unique, so a substring hit is a safe "already done".
+ *  An inserting codemod needs this: unlike a pattern-replacing one, an insert
+ *  doesn't stop matching on the next pass (cf. addImport's regex guard,
+ *  applyDelegated's data-precedence-id check, create-react-app eject's git check). */
+function alreadyInjected(sf, anchorId) {
+    return sf.text.includes(JSON.stringify(anchorId));
+}
+/** an outcome anchor: splice the `track(...)` call at the branch's inject site */
+function applyInlineEdit(a, ev, ap, call, drifted, out) {
+    if (alreadyInjected(ap.sf, a.id)) {
+        out.applied.push({ event: ev.name, file: ap.file, line: ap.line, mode: ap.site.kind, call, drifted, unchanged: true });
+        return;
+    }
+    const edits = planEdit(ap.site, call, ap.sf);
+    if (!edits.length) {
+        out.skipped.push({ event: ev.name, id: a.id, reason: `no concrete injection point (site "${ap.site.kind}")` });
+        return;
+    }
+    const list = out.byFile.get(ap.file) || [];
+    list.push(...edits);
+    out.byFile.set(ap.file, list);
+    out.applied.push({
+        event: ev.name, file: ap.file, mode: ap.site.kind, call,
+        line: ap.sf.getLineAndCharacterOfPosition(edits[0].start).line + 1,
+        drifted,
+    });
+}
+/** a plan built against `--dir foo` carries `foo/x.tsx#…`; the same file scanned
+ *  another way is `x.tsx#…`. Fall back to a UNIQUE match on the `#Comp::slot|…`
+ *  tail (the part that doesn't depend on the scan root). */
+function resolveLoosely(id, index) {
+    const hash = id.indexOf("#");
+    if (hash < 0)
+        return null;
+    const tail = id.slice(hash);
+    const hits = [];
+    for (const [k, ap] of index)
+        if (k.endsWith(tail))
+            hits.push(ap);
+    return hits.length === 1 ? hits[0] : null;
+}
+function dedupeAPs(index) {
+    return [...new Map([...index.values()].map((ap) => [ap.id, ap])).values()];
+}
+/** the id is a fast path; the fingerprint is the real anchor. `conditionKey` is
+ *  syntax-normalised (core/logic), so it holds through a component rename, a
+ *  variable rename, or any refactor that preserves the branch's logic. UNIQUE
+ *  match on (same file + same event + same conditionKey) or nothing; a guess
+ *  is reported as ambiguous, never applied. */
+function resolveByFingerprint(a, all) {
+    const fp = a.fingerprint;
+    if (!fp || !fp.conditionKey || !fp.handler)
+        return null;
+    const file = anchorFile(a.id);
+    const cands = all.filter((ap) => anchorFile(ap.id) === file &&
+        ap.fingerprint.handler === fp.handler &&
+        ap.fingerprint.conditionKey === fp.conditionKey);
+    if (cands.length === 1)
+        return { ap: cands[0], ambiguous: [] };
+    if (cands.length > 1)
+        return { ap: cands[0], ambiguous: cands };
+    return null;
+}
+/**
+ * Repair a plan whose ids stopped resolving. The usual cause is a component
+ * rename (`#CheckoutFlow::` → `#Checkout::`), which shifts every id under it.
+ *
+ * `conditionKey` is syntax-normalised (core/logic), so a rename (of the
+ * component, or of a variable in the condition) does not change it. Each broken
+ * anchor is re-pointed to the UNIQUE current branch in the same file with the
+ * same `handler` + `conditionKey`. Anything ambiguous or unmatched is reported,
+ * never guessed. Writes a new plan for human review, never touches source.
+ */
+function reanchor(inputs, plan, opts = {}) {
+    const { loaded } = (0, build_1.analyze)(inputs, { types: opts.types, tsconfig: opts.tsconfig });
+    const index = attachIndex(loaded);
+    const all = dedupeAPs(index);
+    const res = { plan: { events: [] }, repointed: [], unresolved: [], clean: 0 };
+    for (const ev of plan.events) {
+        const anchors = ev.anchors.map((a) => {
+            if (index.get(a.id) || resolveLoosely(a.id, index)) {
+                res.clean++;
+                return a;
+            }
+            const hit = resolveByFingerprint(a, all);
+            if (hit && !hit.ambiguous.length) {
+                res.repointed.push({
+                    event: ev.name, from: a.id, to: hit.ap.id,
+                    why: `${a.fingerprint?.handler} · ${a.fingerprint?.conditionKey}`,
+                });
+                return { ...a, id: hit.ap.id, fingerprint: hit.ap.fingerprint };
+            }
+            res.unresolved.push({
+                event: ev.name, id: a.id,
+                reason: hit
+                    ? `${hit.ambiguous.length} branches match the fingerprint, can't choose (${hit.ambiguous.map((c) => c.id).join(", ")})`
+                    : a.fingerprint?.conditionKey
+                        ? "no current branch has this event + condition; the logic was removed or changed"
+                        : "plan anchor has no fingerprint to match on; re-export from the picker",
+            });
+            return a;
+        });
+        res.plan.events.push({ ...ev, anchors });
+    }
+    return res;
+}
+/* -------------------------------------------------------------- entry points */
+/** multi-file, the CLI codemod. Returns before/after per changed file. */
+function instrument(inputs, plan, opts) {
+    const { loaded } = (0, build_1.analyze)(inputs, { types: opts.types, tsconfig: opts.tsconfig });
+    const index = attachIndex(loaded);
+    const { fnName } = parseTrack(opts.track || "console.log");
+    const c = collect(plan, index, loaded, opts, fnName);
+    const src = new Map(loaded.map((L) => [(0, build_1.norm)(L.file), L.sf.text]));
+    const res = {
+        files: [], applied: c.applied, skipped: c.skipped, warnings: c.warnings, delegated: c.delegated,
+    };
+    for (const [file, edits] of c.byFile) {
+        const before = src.get(file) || "";
+        const r = render(before, edits, file, opts);
+        // never hand back a file the injection just made unparseable. Report it as a
+        // skip so --check fails and the CLI exits non-zero (the invariants suite
+        // asserts clean output; this is the same check at runtime).
+        const bad = (0, parse_1.parseErrors)((0, parse_1.parseFile)(r.code, file));
+        if (bad.length) {
+            res.skipped.push({
+                event: c.applied.find((x) => x.file === file)?.event ?? "(file)",
+                id: file,
+                reason: `injection produced ${bad.length} syntax error(s); ${file} left unchanged`,
+            });
+            res.applied = res.applied.filter((x) => x.file !== file);
+            continue;
+        }
+        res.files.push({ file, before, after: r.code, map: r.map });
+    }
+    // direct mode ships a generated PM_DELEGATED module; runtime mode uses @precedence-dev/sdk
+    if (opts.emit !== "runtime" && res.delegated.length) {
+        res.runtimeModule = buildDelegatedModule(res.delegated, opts.track || "track");
+    }
+    return res;
+}
+/** one module, the bundler transform hook. null = the plan has nothing here. */
+function instrumentFile(code, id, plan, opts) {
+    const planFile = matchPlanFile(id, plan);
+    if (!planFile)
+        return null;
+    const { loaded } = (0, build_1.analyze)([{ file: planFile, abs: id, source: code }], { types: opts.types, tsconfig: opts.tsconfig });
+    if (!loaded.length)
+        return { file: planFile, code, map: null, applied: [], warnings: [], skipped: [], delegated: [] };
+    const index = attachIndex(loaded);
+    const { fnName } = parseTrack(opts.track || "console.log");
+    const c = collect(plan, index, loaded, opts, fnName, planFile);
+    const edits = c.byFile.get((0, build_1.norm)(planFile)) || [...c.byFile.values()][0] || [];
+    const r = edits.length ? render(code, edits, id, opts) : { code, map: null };
+    return {
+        file: planFile, code: r.code, map: r.map,
+        applied: c.applied, warnings: c.warnings, skipped: c.skipped, delegated: c.delegated,
+    };
+}
+/** the delegated (synthetic) anchors in a plan, straight from the plan, no
+ *  analysis needed, so a bundler can build the runtime module before it has
+ *  transformed every file. */
+function planDelegations(plan) {
+    const out = [];
+    for (const ev of plan.events) {
+        for (const a of ev.anchors) {
+            if (a.inject !== "delegated-listener")
+                continue;
+            const statKeys = new Set(Object.keys(a.staticProps || {}));
+            out.push({
+                event: ev.name, element: a.element || "",
+                ref: a.id, // the structural id, matches what the transform stamps as data-precedence-id
+                attrs: (ev.properties || []).filter((p) => !statKeys.has(p)),
+                props: a.staticProps || {},
+            });
+        }
+    }
+    return out;
+}
+/** one document-level listener for every synthetic (link / bare-button) anchor,
+ *  keyed on the `data-precedence-id="<structural id>"` the transform stamps onto the
+ *  same element, one string, produced by one code path, so it can't drift. */
+function buildDelegatedModule(dels, track) {
+    const { fnName, importLine } = parseTrack(track);
+    const rows = dels.map((d) => {
+        const readers = d.attrs.map((a) => {
+            const dom = a === "label" ? "getAttribute('aria-label')"
+                : a === "track_id" ? "getAttribute('data-track')"
+                    : "getAttribute(" + JSON.stringify(a) + ")";
+            return `${JSON.stringify(a)}: el.${dom}`;
+        });
+        const stat = Object.entries(d.props).map(([k, v]) => `${JSON.stringify(k)}: ${JSON.stringify(v)}`);
+        const idPart = `${JSON.stringify(exports.PM_ID_KEY)}: ${JSON.stringify(d.ref)}`;
+        return `  ${JSON.stringify(d.ref)}: { name: ${JSON.stringify(d.event)}, props: (el: Element): Record<string, unknown> => ({ ${[idPart].concat(readers, stat).join(", ")} }) },`;
+    });
+    return `${importLine}// generated by precedence-instrument, needs data-precedence-id stamps in the production build
+type PmDelegated = { name: string; props: (el: Element) => Record<string, unknown> };
+const PM_DELEGATED: Record<string, PmDelegated> = {
+${rows.join("\n")}
+};
+if (typeof document !== "undefined") {
+  document.addEventListener("click", (e) => {
+    const el = (e.target instanceof Element) ? e.target.closest("[data-precedence-id]") : null;
+    if (!el) return;
+    const id = el.getAttribute("data-precedence-id");
+    const hit = id ? PM_DELEGATED[id] : undefined;
+    if (hit) { try { void Promise.resolve(${fnName}(hit.name, hit.props(el))).catch(() => {}); } catch (__pmE) {} }
+  }, true);
+}
+`;
+}