@precedence-dev/instrument 0.1.0

package/dist/generate/explain.js

@@ -0,0 +1,428 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.explain = explain;
+/**
+ * `precedence-instrument --explain <pm_id>` — the reverse direction of the pipeline.
+ *
+ * Every emitted event carries `pm_id` (the structural anchor id). Given one seen
+ * in the analytics dashboard, this traces it back to the exact fire site and
+ * says, per property, whether and when the value can arrive null.
+ *
+ * Static analysis only. It enumerates the STRUCTURAL reasons a value is absent:
+ *   · out of lexical scope at this site   → instrumenter bakes `undefined`
+ *   · the branch fires precisely when the value is absent (`!user` branch)
+ *   · read from an ambient store that can legitimately be empty
+ *       (localStorage before first write / private mode; context outside Provider)
+ *   · a nullable hop in the accessor path (`a?.b?.c`)
+ *   · a state / data-hook binding that starts empty
+ * It CANNOT know runtime data quality — the API returned null, the user genuinely
+ * had none, a race cleared it. Those show up as "resolves" here.
+ */
+const ts = __importStar(require("typescript"));
+const build_1 = require("@precedence-dev/cli/build");
+const scope_sources_1 = require("@precedence-dev/cli/scope-sources");
+const conditions_1 = require("@precedence-dev/cli/conditions");
+const ast_1 = require("@precedence-dev/cli/ast");
+const EMPTY_SCOPE = { data: new Set(), fn: new Set() };
+function explain(inputs, plan, id) {
+    const { loaded } = (0, build_1.analyze)(inputs);
+    const hit = locate(loaded, id);
+    if (!hit)
+        return { id, resolved: false, reason: whyMiss(loaded, id), props: [] };
+    const { L, el, branch, scope } = hit;
+    const ev = eventFor(plan, id);
+    const anchor = anchorFor(plan, id);
+    const ambient = new Map((0, scope_sources_1.collectAmbient)(loaded.map((x) => x.sf)).map((a) => [a.name, a]));
+    const comp = nearestFn(el.scopeNode);
+    const facts = branch ? requiredFacts(branch.condModel) : [];
+    const selected = ev
+        ? uniq([...(ev.properties || []), ...Object.keys(ev.accessors || {})])
+        : [];
+    const cx = { ev, anchor, ambient, scope, facts, comp, sfs: loaded.map((x) => x.sf) };
+    const props = selected.map((p) => classify(p, cx));
+    return {
+        id,
+        resolved: true,
+        event: ev?.name,
+        file: (0, build_1.norm)(L.file),
+        line: branch?.anchorLine || el.line + 1,
+        component: el.component || undefined,
+        element: el.tag,
+        firesWhen: branch ? (0, conditions_1.combinedLabel)(branch.condModel) : "the handler runs",
+        props,
+    };
+}
+function locateInElement(L, el, id) {
+    for (const h of el.handlers) {
+        if (h.actionId === id) {
+            return { L, el, handlerName: h.name, scope: L.elementScope.get(el) || EMPTY_SCOPE };
+        }
+        const an = L.handlers.get(h);
+        const b = an && findBranch(an.branches, id);
+        if (b)
+            return { L, el, handlerName: h.name, branch: b, scope: b.scope || L.elementScope.get(el) || EMPTY_SCOPE };
+    }
+    return null;
+}
+function locate(loaded, id) {
+    for (const L of loaded) {
+        for (const el of L.elements) {
+            const hit = locateInElement(L, el, id);
+            if (hit)
+                return hit;
+        }
+    }
+    return null;
+}
+function findBranch(bs, id) {
+    for (const b of bs) {
+        if (b.id === id)
+            return b;
+        const c = findBranch(b.children || [], id);
+        if (c)
+            return c;
+    }
+    return null;
+}
+function eventFor(plan, id) {
+    return plan.events.find((e) => e.anchors.some((a) => a.id === id));
+}
+function anchorFor(plan, id) {
+    for (const e of plan.events)
+        for (const a of e.anchors)
+            if (a.id === id)
+                return a;
+    return undefined;
+}
+/** a short reason the id didn't resolve — the file / component / slot as far as it goes */
+function whyMiss(loaded, id) {
+    const m = id.split("|")[0].match(/^(.+)#([^#]*)::(.+)$/);
+    if (!m)
+        return "unrecognised id — copy it from the dashboard's pm_id property verbatim";
+    const [, file, comp] = 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}" is not among the scanned sources — point --dir at it`;
+    const comps = [...new Set(L.elements.map((e) => e.component || "_"))];
+    if (!comps.includes(comp))
+        return `component "${comp}" is gone from ${file} (now: ${comps.join(", ")}); it was renamed or refactored — the events on it need re-picking`;
+    return `the element/branch this id points at is gone from <${comp}>; the code moved on since the plan was authored`;
+}
+/** flatten a cumulative branch condition into the atoms that must hold (or must
+ *  not) for the branch to run. Pushes `!` to the leaves; atoms under an `||`
+ *  come back `optional` (the branch may run satisfying a different disjunct). */
+function requiredFacts(m) {
+    const out = [];
+    (function go(node, neg, optional) {
+        if (!node)
+            return;
+        if (node.kind === "atom") {
+            out.push({ expr: node.expr, text: node.text, neg, optional });
+            return;
+        }
+        if (node.kind === "not")
+            return go(node.inner, !neg, optional);
+        if (node.kind === "all") {
+            // ¬(a ∧ b) ≡ ¬a ∨ ¬b — negation turns the children into disjuncts
+            for (const c of node.clauses)
+                go(c, neg, optional || neg);
+            return;
+        }
+        // "any": a ∨ b (each optional);  ¬(a ∨ b) ≡ ¬a ∧ ¬b (each required)
+        for (const c of node.clauses)
+            go(c, neg, optional || !neg);
+    })(m, false, false);
+    return out;
+}
+/**
+ * Structural nullability verdict for one selected property, tried in order:
+ * the picker's own out-of-scope flag, a React-context accessor, an ambient
+ * store, the branch condition, plain out-of-scope, then softer path/hook hints.
+ */
+function classify(p, cx) {
+    const acc = cx.ev?.accessors?.[p];
+    const selPath = refPath(typeof acc === "string" ? acc : p);
+    const root = selPath.split(/[.[(]/)[0];
+    const verdict = classifyMissingProp(p, cx) ??
+        classifyContextAccessor(p, acc, cx) ??
+        classifyAmbientStore(p, acc, cx) ??
+        (root ? condVerdict(selPath, root, p, cx.facts) : null) ??
+        classifyOutOfScope(p, acc, root, cx);
+    if (verdict)
+        return verdict;
+    const reasons = softNullabilityReasons(p, acc, selPath, root, cx);
+    if (reasons.length)
+        return { prop: p, verdict: "maybe-null", reasons };
+    return mk(p, "resolves", `in scope here with no structural reason to be null — a null here would be runtime data (the source returned null / the user had none).`);
+}
+/** 1 — the picker already resolved this as out-of-scope at this site */
+function classifyMissingProp(p, cx) {
+    if (!(cx.anchor?.missingProps || []).includes(p))
+        return null;
+    return mk(p, "always-null", `not in scope where this event fires — the instrumenter emits \`${p}: undefined\`, so every event from this id has \`${p}\` null.`);
+}
+/** 2 — a React context accessor (`{ hook, context, path }`) */
+function classifyContextAccessor(p, acc, cx) {
+    if (!acc || typeof acc !== "object" || !acc.hook)
+        return null;
+    const reasons = [
+        `read from \`${acc.hook}()\` React context (field \`${acc.path}\`). Null for any subtree rendered outside its Provider, and on the first render before the Provider commits a value.`,
+    ];
+    if (contextDefaultIsNullish(cx.sfs, acc.context)) {
+        reasons.push(`\`createContext(${acc.context})\` has no real default — outside the Provider the context value itself is null/undefined.`);
+    }
+    return { prop: p, verdict: "maybe-null", reasons };
+}
+/** 3 — an ambient store accessor (localStorage / sessionStorage) */
+function classifyAmbientStore(p, acc, cx) {
+    const amb = cx.ambient.get(p);
+    const accStr = typeof acc === "string" ? acc : amb?.accessor;
+    if (!accStr || !/\b(local|session)Storage\b/.test(accStr))
+        return null;
+    const store = /sessionStorage/.test(accStr) ? "sessionStorage" : "localStorage";
+    const key = (accStr.match(/Storage\.getItem\(\s*["'`]([^"'`]+)/) || [])[1] || p;
+    const fb = (accStr.match(/\|\|\s*("(?:[^"\\]|\\.)*"|'[^']*'|`[^`]*`|\{\s*\}|\[\s*\]|null|undefined|-?\d[\d.]*)/) || [])[1];
+    // JSON.parse("null") is null; strip the quotes and judge the payload
+    const fbInner = (fb || "").replace(/^["'`]|["'`]$/g, "");
+    const realFallback = !!fb && fbInner !== "null" && fbInner !== "undefined" && fbInner !== "";
+    const reasons = realFallback
+        ? [`reads \`${store}['${key}']\`, falling back to \`${fb}\` when unset — so a new user gets that fallback, not null.`]
+        : [`reads \`${store}['${key}']\` with no real fallback — null before the key is ever written (new user, right after logout, after the user clears site data), and always null where storage is blocked (Safari private mode, strict cookie settings).`];
+    if (amb?.identity)
+        reasons.push(`flagged identity/PII — confirm you want it on every event.`);
+    return { prop: p, verdict: realFallback ? "resolves" : "maybe-null", reasons };
+}
+/** 5 — not a lexical binding visible here at all */
+function classifyOutOfScope(p, acc, root, cx) {
+    const known = cx.scope.data.has(root) || cx.scope.fn.has(root);
+    if (!root || known || cx.ambient.get(p) || acc !== undefined || isGlobalish(root))
+        return null;
+    return mk(p, "always-null", `\`${root}\` is not visible where this event fires — the instrumenter will emit \`${p}: undefined\`.`);
+}
+/** 6 + 7 — softer signals: an optional hop in the path, or a hook binding that starts empty */
+function softNullabilityReasons(p, acc, selPath, root, cx) {
+    const reasons = [];
+    if (typeof acc === "string" && acc.includes("?.")) {
+        reasons.push(`the accessor \`${acc}\` chains through optional (\`?.\`) hops — null whenever a hop before the last is null at click time.`);
+    }
+    else if (selPath.includes(".")) {
+        reasons.push(`\`${p}\` reads a nested path (\`${selPath}\`) — null if an intermediate object is null when the event fires.`);
+    }
+    if (root && cx.comp) {
+        const init = bindingInit(cx.comp, root);
+        if (init)
+            reasons.push(init);
+    }
+    return reasons;
+}
+function mk(prop, verdict, reason) {
+    return { prop, verdict, reasons: [reason] };
+}
+/** does a required (non-optional) fact pin `selPath` absent or present? */
+function condVerdict(selPath, root, prop, facts) {
+    for (const f of facts) {
+        if (f.optional || !f.expr)
+            continue;
+        const v = factVerdict((0, ast_1.unwrapParen)(f.expr), f, selPath, root, prop);
+        if (v)
+            return v;
+    }
+    return null;
+}
+/** one required fact → a verdict, or null if it says nothing about `selPath`. */
+function factVerdict(e, f, selPath, root, prop) {
+    // x == null / x === undefined / x != null …
+    if (ts.isBinaryExpression(e))
+        return binaryFactVerdict(e, f, selPath, root, prop);
+    // bare truthiness: `user`, `!user`, `user.team`, `!user.team`
+    if (!ts.isIdentifier(e) && !ts.isPropertyAccessExpression(e) && !ts.isElementAccessExpression(e))
+        return null;
+    const fp = refPath((0, ast_1.txt)(e));
+    if (f.neg) {
+        // `!fp` must hold → fp is falsy. Absent for selPath only if fp is a prefix of it.
+        return isPrefix(fp, selPath) ? branchAbsent(prop, fp) : null;
+    }
+    // `fp` is truthy → every object on the way to fp is present.
+    return isPrefix(fp, selPath) || isPrefix(selPath, fp) ? branchPresent(prop, minPath(fp, selPath)) : null;
+}
+function binaryFactVerdict(e, f, selPath, root, prop) {
+    const l = refPath((0, ast_1.txt)(e.left)), r = refPath((0, ast_1.txt)(e.right));
+    const nullSide = /^(null|undefined)$/;
+    const refSide = nullSide.test(l) ? r : nullSide.test(r) ? l : "";
+    const nullCmp = nullComparisonVerdict(e.operatorToken.kind, f, refSide, selPath, prop);
+    if (nullCmp)
+        return nullCmp;
+    // a member comparison — `user.status === "x"` — proves `user` is present
+    if (!f.neg && (isPrefix(root, l) || isPrefix(root, r)) && (l.includes(".") || r.includes(".")))
+        return branchPresent(prop, root);
+    return null;
+}
+/** `x == null` / `x === undefined` / `x != null` against `selPath` (or a prefix). */
+function nullComparisonVerdict(op, f, refSide, selPath, prop) {
+    if (!refSide || !isPrefix(refSide, selPath))
+        return null;
+    const eq = op === ts.SyntaxKind.EqualsEqualsEqualsToken || op === ts.SyntaxKind.EqualsEqualsToken;
+    const ne = op === ts.SyntaxKind.ExclamationEqualsEqualsToken || op === ts.SyntaxKind.ExclamationEqualsToken;
+    if ((eq && !f.neg) || (ne && f.neg))
+        return branchAbsent(prop, refSide);
+    if ((ne && !f.neg) || (eq && f.neg))
+        return branchPresent(prop, refSide);
+    return null;
+}
+function branchAbsent(prop, path) {
+    return mk(prop, "null-in-this-branch", `this branch fires precisely when \`${path}\` is falsy/absent — so \`${prop}\` is null here by construction. This is the empty-state path; if you don't want those events, drop this branch from the plan.`);
+}
+function branchPresent(prop, path) {
+    return mk(prop, "present-in-this-branch", `the branch condition guarantees \`${path}\` is present here — \`${prop}\` won't be null from this fire site (a null would be genuine runtime data).`);
+}
+/* -------------------------------------------------------------- ast probes */
+function nearestFn(node) {
+    for (let n = node; n; n = n.parent)
+        if ((0, ast_1.isFn)(n))
+            return n;
+    return undefined;
+}
+/** callee name of a call expression: `foo(...)` → "foo", `a.foo(...)` → "foo", else "" */
+function calleeName(expr) {
+    if (ts.isIdentifier(expr))
+        return expr.text;
+    if (ts.isPropertyAccessExpression(expr))
+        return expr.name.text;
+    return "";
+}
+const NULLISH_KIND = new Set([ts.SyntaxKind.NullKeyword, ts.SyntaxKind.UndefinedKeyword]);
+const DATA_HOOK_RE = /(useQuery|useSuspenseQuery|useSWR|useSWRImmutable|useLazyQuery|useInfiniteQuery|useMutation|useFetch|useAsync)/;
+/** absent, `null`, `undefined`, or the identifier `undefined` */
+function isNullishArg(a0) {
+    return !a0 || NULLISH_KIND.has(a0.kind) || (0, ast_1.txt)(a0) === "undefined";
+}
+/** the narrower `useRef` test: absent or literal `null` only */
+function isNullArg(a0) {
+    return !a0 || a0.kind === ts.SyntaxKind.NullKeyword;
+}
+/** `const { data: x } = useQuery()` — the renamed-`data` destructuring case */
+function bindsDataField(nameNode, name) {
+    return ts.isObjectBindingPattern(nameNode)
+        && nameNode.elements.some((el) => bindKey(el) === "data" && localName(el) === name);
+}
+/** one `const … = hook(…)` declaration → why `name` can start empty, or null */
+function hookInitMessage(n, name) {
+    if (!n.initializer || !ts.isCallExpression(n.initializer))
+        return null;
+    const callee = calleeName(n.initializer.expression);
+    const args = n.initializer.arguments;
+    const binds = declBinds(n.name, name);
+    if (binds && callee === "useState" && isNullishArg(args[0])) {
+        return `\`${name}\` is \`useState(${args[0] ? (0, ast_1.txt)(args[0]) : ""})\` — null until its setter runs, so events that fire before then carry null.`;
+    }
+    if (binds && callee === "useRef" && isNullArg(args[0])) {
+        return `\`${name}\` is a \`useRef(null)\` — \`.current\` is null until the ref attaches.`;
+    }
+    if ((binds || bindsDataField(n.name, name)) && DATA_HOOK_RE.test(callee)) {
+        return `\`${name}\` comes from \`${callee}(…)\` — undefined until the request resolves, and again while it re-fetches or after an error.`;
+    }
+    return null;
+}
+/** the initializer story for a `const x = …` / `const [x] = …` / `const {x} = …`
+ *  inside the component, when it starts empty. null if nothing notable. */
+function bindingInit(comp, name) {
+    let msg = null;
+    (function w(n) {
+        if (msg)
+            return;
+        if (ts.isVariableDeclaration(n))
+            msg = hookInitMessage(n, name);
+        ts.forEachChild(n, w);
+    })(comp);
+    return msg;
+}
+function declBinds(nameNode, name) {
+    if (ts.isIdentifier(nameNode))
+        return nameNode.text === name;
+    if (ts.isArrayBindingPattern(nameNode))
+        return nameNode.elements.some((el) => !ts.isOmittedExpression(el) && ts.isIdentifier(el.name) && el.name.text === name);
+    if (ts.isObjectBindingPattern(nameNode))
+        return nameNode.elements.some((el) => localName(el) === name);
+    return false;
+}
+function bindKey(el) {
+    return el.propertyName && ts.isIdentifier(el.propertyName) ? el.propertyName.text
+        : ts.isIdentifier(el.name) ? el.name.text : "";
+}
+function localName(el) {
+    return ts.isIdentifier(el.name) ? el.name.text : "";
+}
+/** was `createContext` for `ctxVar` called with no meaningful default? */
+function contextDefaultIsNullish(sfs, ctxVar) {
+    for (const sf of sfs) {
+        let hit = null;
+        (function w(n) {
+            if (hit !== null)
+                return;
+            if (ts.isVariableDeclaration(n) && ts.isIdentifier(n.name) && n.name.text === ctxVar
+                && n.initializer && ts.isCallExpression(n.initializer)) {
+                if (calleeName(n.initializer.expression) === "createContext") {
+                    const a0 = n.initializer.arguments[0];
+                    hit = !a0 || a0.kind === ts.SyntaxKind.NullKeyword || (0, ast_1.txt)(a0) === "undefined"
+                        || (ts.isAsExpression(a0) && a0.expression.kind === ts.SyntaxKind.NullKeyword);
+                }
+            }
+            ts.forEachChild(n, w);
+        })(sf);
+        if (hit !== null)
+            return hit;
+    }
+    return false;
+}
+/* -------------------------------------------------------------- path utils */
+/** dotted path with `?.` collapsed and whitespace stripped: `a?.b .c` → `a.b.c` */
+function refPath(s) {
+    return (s || "").replace(/\?\./g, ".").replace(/\s+/g, "").replace(/!$/, "");
+}
+/** is `a` the same path as `b`, or a proper prefix at a `.` boundary? */
+function isPrefix(a, b) {
+    return a === b || b.startsWith(a + ".") || b.startsWith(a + "[");
+}
+function minPath(a, b) {
+    return a.length <= b.length ? a : b;
+}
+const GLOBALISH = new Set(["window", "document", "navigator", "location", "console", "Math", "JSON", "Date", "localStorage", "sessionStorage", "process", "globalThis"]);
+function isGlobalish(root) {
+    return GLOBALISH.has(root);
+}
+function uniq(a) {
+    return [...new Set(a)];
+}

package/dist/generate/instrument.d.ts

@@ -0,0 +1,165 @@
+import type { BuildInput } from "@precedence-dev/cli/build";
+import type { Fingerprint } from "@precedence-dev/cli/types";
+export interface PlanAnchor {
+    id: string;
+    file?: string;
+    /** element line, only needed for delegated (synthetic) anchors */
+    line?: number;
+    element?: string;
+    inject?: string;
+    staticProps?: Record<string, string>;
+    missingProps?: string[];
+    /** captured at author time, the instrumenter verifies it still holds */
+    fingerprint?: Partial<Fingerprint>;
+}
+export interface PlanEvent {
+    name: string;
+    /** the viewer's human-written event definition; carried through untouched */
+    description?: string;
+    properties: string[];
+    outcomeProp?: string;
+    /** ambient props → how to read them: an inline expr (localStorage), or a
+     *  React context field the instrumenter resolves against the component */
+    accessors?: Record<string, string | {
+        hook: string;
+        context: string;
+        path: string;
+    }>;
+    anchors: PlanAnchor[];
+}
+export interface Plan {
+    events: PlanEvent[];
+}
+export interface InstrumentOpts {
+    /**
+     * "direct" (default): inject `track("event_name", { props })` + an import.
+     *   Self-contained, readable, no runtime dependency. To change anything → rebuild.
+     * "runtime": inject `globalThis.__pm?.("<anchor id>", { props })`, no import,
+     *   no static/discriminator props baked in. `@precedence-dev/sdk` (installPrecedence)
+     *   looks the id up in the fetched plan and shapes the event. Toggle / rename /
+     *   static values / prop narrowing become plan edits, no rebuild.
+     */
+    emit?: "direct" | "runtime";
+    /** direct mode only: "<name> from <module>" adds an import; "<name>" assumes global */
+    track?: string;
+    /** runtime mode: the global to call (default "globalThis.__pm") */
+    emitGlobal?: string;
+    /**
+     * resolve declared types via the TS checker. REQUIRED to instrument callback-edge-rule
+     * `continuation` anchors (`mutate(x, { onSuccess })`, `p.then(f, g)`) — the
+     * classification that produced them needs the checker, so the branch tree is
+     * only reproduced here when this is on. Same catalog build path (`analyze`).
+     */
+    types?: boolean;
+    /** explicit tsconfig.json for `types` (else the nearest one is used) */
+    tsconfig?: string;
+}
+interface Applied {
+    event: string;
+    file: string;
+    line: number;
+    mode: string;
+    call: string;
+    drifted?: boolean;
+    unchanged?: boolean;
+}
+export interface Skipped {
+    event: string;
+    id?: string;
+    reason: string;
+}
+interface Warning {
+    event: string;
+    id: string;
+    detail: string;
+}
+export interface Delegation {
+    event: string;
+    element: string;
+    ref: string;
+    attrs: string[];
+    props: Record<string, string>;
+}
+export interface InstrumentResult {
+    files: {
+        file: string;
+        before: string;
+        after: string;
+        map?: unknown;
+    }[];
+    applied: Applied[];
+    skipped: Skipped[];
+    /** id resolved, but the code moved on since the plan, injected anyway, verify */
+    warnings: Warning[];
+    delegated: Delegation[];
+    /** a delegated click/navigate listener for every synthetic anchor, needs
+     *  `data-precedence-id` stamps in the production build (browser/stamp-loader.js) */
+    runtimeModule?: string;
+}
+/** what a single-module transform returns; null when the plan has nothing here */
+export interface FileInstrumentResult {
+    file: string;
+    code: string;
+    map: unknown | null;
+    applied: Applied[];
+    warnings: Warning[];
+    skipped: Skipped[];
+    delegated: Delegation[];
+}
+/** every distinct source file a plan references */
+export declare function planFiles(plan: Plan): string[];
+/** 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). */
+export declare const PM_ID_KEY = "pm_id";
+/**
+ * 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.
+ */
+export declare function safeStatement(call: string): string;
+export interface ReanchorResult {
+    plan: Plan;
+    repointed: {
+        event: string;
+        from: string;
+        to: string;
+        why: string;
+    }[];
+    unresolved: {
+        event: string;
+        id: string;
+        reason: string;
+    }[];
+    clean: number;
+}
+/**
+ * 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.
+ */
+export declare function reanchor(inputs: BuildInput[], plan: Plan, opts?: {
+    types?: boolean;
+    tsconfig?: string;
+}): ReanchorResult;
+/** multi-file, the CLI codemod. Returns before/after per changed file. */
+export declare function instrument(inputs: BuildInput[], plan: Plan, opts: InstrumentOpts): InstrumentResult;
+/** one module, the bundler transform hook. null = the plan has nothing here. */
+export declare function instrumentFile(code: string, id: string, plan: Plan, opts: InstrumentOpts): FileInstrumentResult | null;
+/** 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. */
+export declare function planDelegations(plan: Plan): Delegation[];
+/** 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. */
+export declare function buildDelegatedModule(dels: Delegation[], track: string): string;
+export {};