@precedence-dev/instrument 0.1.0

package/dist/generate/cli.js

@@ -0,0 +1,368 @@
+#!/usr/bin/env node
+"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 });
+/**
+ * precedence-instrument, CI transform. Splice tracking calls into the source from a
+ * plan (the events a PM defined in the picker / viewer "copy events" export).
+ *
+ *   precedence-instrument --plan plan.json --dir src --track "track from @/lib/analytics"
+ *   precedence-instrument --plan plan.json --dir src --track track --apply
+ *   precedence-instrument --plan plan.json --dir src --track track --check   # CI: fail if drifted
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const discover_1 = require("../discover");
+const util_1 = require("../util");
+const instrument_1 = require("./instrument");
+const explain_1 = require("./explain");
+const HELP = `precedence-instrument, splice tracking calls into the source from a plan
+
+USAGE
+  precedence-instrument --plan plan.json --dir src --track "<name> from <module>"
+
+OPTIONS
+  --plan <file>      the events export from the picker / viewer  (required)
+  --dir <path>       source dir to scan (repeatable)              (required)
+  --track <spec>     direct mode: "track from @/lib/analytics" -> adds an import
+                     "track"                     -> assume it's already in scope / global
+                     (default: console.log, every event logs "[pm] <name>", no import)
+  --emit <mode>      "direct" (default): track("name", { props }) baked in
+                     "runtime": globalThis.__pm?.("<id>", { props }), toggle/rename
+                       become plan edits; needs @precedence-dev/sdk at the app root
+  --types            resolve declared types via the TS checker (needs a tsconfig).
+                     Required for callback-edge-rule continuation anchors (mutate onSuccess/
+                     onError, .then(f,g)).
+  --tsconfig <path>  explicit tsconfig.json for --types
+  --apply            write the changes to disk       (default: dry-run diff to stdout)
+                     refuses if git has uncommitted changes, so the injection
+                     stays reviewable in a diff
+  --allow-dirty      let --apply run against a dirty git tree anyway
+  --out-dir <dir>    write changed files here instead of in place
+  --runtime <file>   write the delegated click/navigate listener here (for synthetic anchors)
+  --check            exit 1 if any file would change  (for CI verification)
+  --json             machine-readable report to stdout
+  --reanchor         don't instrument, repair a plan whose ids stopped resolving
+                     (e.g. a component was renamed) by matching on fingerprint,
+                     write the fixed plan to --out for review
+  --out <file>       where --reanchor writes the repaired plan (default: <plan>.reanchored.json)
+  --explain <pm_id>  don't instrument, trace one pm_id (as seen in the dashboard)
+                     back to its fire site and report, per property, when it can
+                     arrive null. Pair with --json for the structured report.
+  -h, --help
+
+EXIT
+  0  nothing to do / applied / reanchor clean
+  1  --check and files would change  /  bad plan  /  reanchor left anchors unresolved
+  2  bad usage
+`;
+function fail(m) { process.stderr.write(`error: ${m}\n\n${HELP}`); process.exit(2); }
+const OPTIONS = new Map([
+    ["--plan", (o, next) => { o.plan = next(); }],
+    ["--dir", (o, next) => { o.paths.push(next()); }],
+    ["--track", (o, next) => { o.track = next(); }],
+    ["--emit", (o, next) => {
+            const v = next();
+            if (v !== "direct" && v !== "runtime")
+                fail("--emit must be direct|runtime");
+            o.emit = v;
+        }],
+    ["--apply", (o) => { o.apply = true; }],
+    ["--allow-dirty", (o) => { o.allowDirty = true; }],
+    ["--types", (o) => { o.types = true; }],
+    ["--tsconfig", (o, next) => { o.tsconfig = next(); }],
+    ["--check", (o) => { o.check = true; }],
+    ["--out-dir", (o, next) => { o.outDir = next(); }],
+    ["--runtime", (o, next) => { o.runtime = next(); }],
+    ["--json", (o) => { o.json = true; }],
+    ["--reanchor", (o) => { o.reanchor = true; }],
+    ["--out", (o, next) => { o.out = next(); }],
+    ["--explain", (o, next) => { o.explain = next(); }],
+]);
+function parseArgs(argv) {
+    const o = { plan: "", paths: [], track: "", emit: "direct", apply: false, allowDirty: false, check: false, types: false, tsconfig: "", outDir: "", json: false, runtime: "", reanchor: false, out: "", explain: "" };
+    const cur = { i: 0 };
+    const next = (a) => { const v = argv[++cur.i]; if (v === undefined)
+        fail(`missing value for ${a}`); return v; };
+    for (cur.i = 0; cur.i < argv.length; cur.i++) {
+        const a = argv[cur.i];
+        if (a === "-h" || a === "--help") {
+            process.stdout.write(HELP);
+            process.exit(0);
+        }
+        const handler = OPTIONS.get(a);
+        if (handler)
+            handler(o, () => next(a));
+        else if (a.startsWith("--"))
+            fail(`unknown option: ${a}`);
+        else
+            o.paths.push(a);
+    }
+    if (!o.plan)
+        fail("--plan is required");
+    if (!o.paths.length)
+        fail("--dir is required");
+    // --track optional now: direct mode defaults to console.log (in instrument.ts)
+    return o;
+}
+/** fill an LCS length table, `dp[i][j]` = LCS of `A[i:]` and `B[j:]`. */
+function lcsTable(A, B) {
+    const 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]);
+        }
+    }
+    return dp;
+}
+/** walk the LCS table into a flat context/-/+ op list. */
+function diffOps(A, B) {
+    const dp = lcsTable(A, B);
+    const ops = [];
+    let i = 0, j = 0;
+    while (i < A.length && j < B.length) {
+        if (A[i] === B[j]) {
+            ops.push({ t: " ", s: A[i] });
+            i++;
+            j++;
+        }
+        else if (dp[i + 1][j] >= dp[i][j + 1]) {
+            ops.push({ t: "-", s: A[i] });
+            i++;
+        }
+        else {
+            ops.push({ t: "+", s: B[j] });
+            j++;
+        }
+    }
+    while (i < A.length)
+        ops.push({ t: "-", s: A[i++] });
+    while (j < B.length)
+        ops.push({ t: "+", s: B[j++] });
+    return ops;
+}
+/** extend a hunk forward from `start` until 2+ trailing context lines. */
+function hunkEnd(ops, start) {
+    let end = start, ctx = 0;
+    while (end < ops.length && (ops[end].t !== " " || ctx < 2 || (ops[end + 1] && ops[end + 1].t !== " "))) {
+        ctx = ops[end].t === " " ? ctx + 1 : 0;
+        end++;
+    }
+    return end;
+}
+/** LCS line diff → unified-ish output with 2 lines of context per hunk */
+function unifiedDiff(file, a, b) {
+    const ops = diffOps(a.split("\n"), b.split("\n"));
+    const out = [`--- a/${file}`, `+++ b/${file}`];
+    let k = 0;
+    while (k < ops.length) {
+        if (ops[k].t === " ") {
+            k++;
+            continue;
+        }
+        const from = Math.max(0, k - 2);
+        const end = hunkEnd(ops, k);
+        out.push("@@");
+        for (let x = from; x < end && x < ops.length; x++)
+            out.push(ops[x].t + ops[x].s);
+        k = end;
+    }
+    return out.join("\n");
+}
+/** `git status --porcelain`, trimmed. "" on any failure (not a repo, no git on
+ *  PATH) — like create-react-app's eject, only block when we can positively see
+ *  uncommitted work. */
+function gitDirty() {
+    try {
+        return (0, child_process_1.execFileSync)("git", ["status", "--porcelain"], { encoding: "utf8", stdio: ["pipe", "pipe", "ignore"] }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * --apply rewrites source in place; keep it reviewable by refusing on a dirty
+ * tree (a bad run is then always one `git checkout` away). --out-dir writes
+ * elsewhere, so it's exempt; --allow-dirty opts out.
+ */
+function guardCleanTree(o) {
+    if (!o.apply || o.allowDirty)
+        return;
+    const dirty = gitDirty();
+    if (!dirty)
+        return;
+    process.stderr.write("error: --apply rewrites your source, but git has uncommitted changes:\n\n" +
+        `${dirty.split("\n").map((l) => `  ${l}`).join("\n")}\n\n` +
+        "Commit or stash them first so the injection lands in its own diff, or pass --allow-dirty.\n");
+    process.exit(1);
+}
+function loadPlan(planPath) {
+    let plan;
+    try {
+        plan = JSON.parse(fs.readFileSync(planPath, "utf8"));
+    }
+    catch (e) {
+        process.stderr.write(`error: cannot read plan ${planPath}: ${(0, util_1.errMsg)(e)}\n`);
+        process.exit(1);
+    }
+    if (!plan || !Array.isArray(plan.events)) {
+        process.stderr.write(`error: ${planPath} has no "events" array\n`);
+        process.exit(1);
+    }
+    return plan;
+}
+function readInputs(paths) {
+    const { files, errors } = (0, discover_1.discoverSources)({ paths });
+    errors.forEach((e) => process.stderr.write(`warn: ${e}\n`));
+    const cwd = process.cwd();
+    return files.map((f) => ({
+        file: path.relative(cwd, f) || f, abs: f, source: fs.readFileSync(f, "utf8"),
+    }));
+}
+function printTextReport(r) {
+    const added = r.applied.filter((x) => !x.unchanged);
+    const unchanged = r.applied.length - added.length;
+    r.applied.forEach((x) => process.stdout.write(`  ${x.unchanged ? "=" : x.drifted ? "±" : "+"} ${x.event}  ${x.file}:${x.line}  [${x.mode}]${x.unchanged ? "  already instrumented" : `  ${x.call}`}\n`));
+    r.delegated.forEach((x) => process.stdout.write(`  ~ ${x.event}  <${x.element}> @ ${x.ref}  → delegated listener\n`));
+    r.warnings.forEach((x) => process.stderr.write(`  ! ${x.event}  drift: ${x.detail}\n`));
+    r.skipped.forEach((x) => process.stderr.write(`  - ${x.event}  skipped: ${x.reason}${x.id ? `  (${x.id})` : ""}\n`));
+    process.stdout.write(`\n${added.length} call(s) in ${r.files.length} file(s)${unchanged ? `, ${unchanged} already in place` : ""}, ${r.delegated.length} delegated, ${r.warnings.length} drift, ${r.skipped.length} skipped\n`);
+}
+function emitRuntimeModule(r, o) {
+    if (o.runtime && r.runtimeModule) {
+        fs.mkdirSync(path.dirname(path.resolve(o.runtime)), { recursive: true });
+        fs.writeFileSync(o.runtime, r.runtimeModule);
+        process.stdout.write(`  wrote ${o.runtime}  (${r.delegated.length} delegated event(s), import it once at your app root)\n`);
+    }
+    else if (r.runtimeModule && !o.json) {
+        process.stdout.write(`\n--- delegated listener (pass --runtime <file> to write it) ---\n${r.runtimeModule}\n`);
+    }
+}
+function writeChanges(r, o) {
+    const changed = r.files.filter((f) => f.before !== f.after);
+    if (o.apply || o.outDir) {
+        changed.forEach((f) => {
+            const dest = o.outDir ? path.join(o.outDir, f.file) : path.resolve(f.file);
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            fs.writeFileSync(dest, f.after);
+            process.stdout.write(`  wrote ${dest}\n`);
+        });
+    }
+    else if (!o.json) {
+        changed.forEach((f) => process.stdout.write("\n" + unifiedDiff(f.file, f.before, f.after) + "\n"));
+        if (changed.length)
+            process.stdout.write("\n(dry run, pass --apply to write)\n");
+    }
+}
+function main() {
+    const o = parseArgs(process.argv.slice(2));
+    guardCleanTree(o);
+    const plan = loadPlan(o.plan);
+    const inputs = readInputs(o.paths);
+    if (o.reanchor) {
+        doReanchor(inputs, plan, o);
+        return;
+    }
+    if (o.explain) {
+        doExplain(inputs, plan, o);
+        return;
+    }
+    const r = (0, instrument_1.instrument)(inputs, plan, {
+        track: o.track, emit: o.emit, types: o.types, tsconfig: o.tsconfig || undefined,
+    });
+    if (o.json)
+        process.stdout.write(JSON.stringify(r, null, 2) + "\n");
+    else
+        printTextReport(r);
+    const changed = r.files.filter((f) => f.before !== f.after);
+    // --check: the committed instrumented tree is out of date, OR the plan no
+    // longer resolves cleanly against the source, both are CI failures.
+    if (o.check)
+        process.exit(changed.length || r.skipped.length ? 1 : 0);
+    emitRuntimeModule(r, o);
+    writeChanges(r, o);
+}
+const VERDICT_MARK = {
+    "always-null": "✗ always null",
+    "null-in-this-branch": "✗ null here",
+    "present-in-this-branch": "✓ present",
+    "maybe-null": "⚠ may be null",
+    "resolves": "· ok",
+};
+function doExplain(inputs, plan, o) {
+    const r = (0, explain_1.explain)(inputs, plan, o.explain);
+    if (o.json) {
+        process.stdout.write(JSON.stringify(r, null, 2) + "\n");
+        process.exit(r.resolved ? 0 : 1);
+    }
+    if (!r.resolved) {
+        process.stderr.write(`  ✗ ${o.explain}\n      ${r.reason}\n`);
+        process.exit(1);
+    }
+    process.stdout.write(`  ${r.event}   ${r.file}:${r.line}   <${r.element}> in ${r.component || "(module)"}\n`);
+    process.stdout.write(`  fires ${r.firesWhen}\n\n`);
+    if (!r.props.length)
+        process.stdout.write(`  (no properties selected for this event)\n`);
+    for (const p of r.props) {
+        process.stdout.write(`  ${VERDICT_MARK[p.verdict]}  ${p.prop}\n`);
+        for (const why of p.reasons)
+            process.stdout.write(`       ${why}\n`);
+    }
+    process.exit(0);
+}
+function doReanchor(inputs, plan, o) {
+    const r = (0, instrument_1.reanchor)(inputs, plan, { types: o.types, tsconfig: o.tsconfig || undefined });
+    const dest = o.out || o.plan.replace(/\.json$/, "") + ".reanchored.json";
+    if (o.json) {
+        process.stdout.write(JSON.stringify(r, null, 2) + "\n");
+    }
+    else {
+        r.repointed.forEach((x) => process.stdout.write(`  → ${x.event}\n      ${x.from}\n      ${x.to}   (${x.why})\n`));
+        r.unresolved.forEach((x) => process.stderr.write(`  ✗ ${x.event}  ${x.id}\n      ${x.reason}\n`));
+        process.stdout.write(`\n${r.clean} already fine, ${r.repointed.length} re-pointed, ${r.unresolved.length} unresolved\n`);
+    }
+    if (r.repointed.length) {
+        fs.writeFileSync(dest, JSON.stringify(r.plan, null, 2) + "\n");
+        if (!o.json)
+            process.stdout.write(`\n  wrote ${dest}, review the id changes, then replace your plan\n`);
+    }
+    else if (!o.json) {
+        process.stdout.write(r.unresolved.length ? "\n  nothing could be re-pointed automatically\n" : "\n  plan is clean, nothing to do\n");
+    }
+    process.exit(r.unresolved.length ? 1 : 0);
+}
+main();

package/dist/generate/explain.d.ts

@@ -0,0 +1,21 @@
+import type { BuildInput } from "@precedence-dev/cli/build";
+import type { Plan } from "./instrument";
+export type Verdict = "always-null" | "null-in-this-branch" | "present-in-this-branch" | "maybe-null" | "resolves";
+export interface PropExplain {
+    prop: string;
+    verdict: Verdict;
+    reasons: string[];
+}
+export interface ExplainReport {
+    id: string;
+    resolved: boolean;
+    reason?: string;
+    event?: string;
+    file?: string;
+    line?: number;
+    component?: string;
+    element?: string;
+    firesWhen?: string;
+    props: PropExplain[];
+}
+export declare function explain(inputs: BuildInput[], plan: Plan, id: string): ExplainReport;