@precedence-dev/instrument 0.1.0

package/dist/generate/unplugin.d.ts

@@ -0,0 +1,31 @@
+import { type Plan, type Skipped } from "./instrument";
+export interface PmInstrumentOptions {
+    /** the `copy events` export, a parsed plan, or a path to the JSON file */
+    plan: Plan | string;
+    /**
+     * "direct" (default): inject `track(…)` calls + the delegated-listener module.
+     * "runtime": inject `globalThis.__pm?.(id, …)` calls, stamp delegated elements,
+     *   and let `@precedence-dev/sdk` (installPrecedence) do the rest at runtime.
+     *   Toggling / renaming an event no longer needs a rebuild.
+     */
+    emit?: "direct" | "runtime";
+    /** direct mode: "<name> from <module>" adds the import; "<name>" assumes it's global.
+     *  default "console.log", every event logs "[pm] <name>", no import. */
+    track?: string;
+    /** direct mode: id for the delegated-listener module (import once at your app root; default "virtual:pm-tracking") */
+    virtualModuleId?: string;
+    /** per-file callback, wire drift / skips into your build log or fail the build */
+    onReport?: (r: {
+        file: string;
+        applied: number;
+        drift: number;
+        skipped: Skipped[];
+    }) => void;
+}
+export declare const unpluginPmInstrument: import("unplugin").UnpluginInstance<PmInstrumentOptions, boolean>;
+export declare const vitePlugin: (options: PmInstrumentOptions) => any;
+export declare const webpackPlugin: (options: PmInstrumentOptions) => WebpackPluginInstance;
+export declare const rollupPlugin: (options: PmInstrumentOptions) => any;
+export declare const rspackPlugin: (options: PmInstrumentOptions) => RspackPluginInstance;
+export declare const esbuildPlugin: (options: PmInstrumentOptions) => EsbuildPlugin;
+export declare const farmPlugin: (options: PmInstrumentOptions) => JsPlugin;

package/dist/generate/unplugin.js

@@ -0,0 +1,125 @@
+"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.farmPlugin = exports.esbuildPlugin = exports.rspackPlugin = exports.rollupPlugin = exports.webpackPlugin = exports.vitePlugin = exports.unpluginPmInstrument = void 0;
+/**
+ * precedence-instrument as a bundler transform, the production delivery path.
+ *
+ * One `transform` hook, adapted to Vite / webpack / Rollup / esbuild / Rspack by
+ * unplugin. Source files never change on disk; the `track(…)` calls exist only
+ * in the bundle, so instrumentation is idempotent and sourcemap-clean by
+ * construction, and CI reviews the plan diff, not a machine-rewritten tree.
+ *
+ * One implementation, six bundlers: per-module `transform(code, id)`, plan/config
+ * as the input.
+ *
+ *   // next.config.mjs
+ *   import { webpackPlugin as pmInstrument } from "@precedence-dev/instrument/unplugin";
+ *   const nextConfig = {
+ *     webpack(config) {
+ *       config.plugins.push(pmInstrument({
+ *         plan: "./tracking-plan.json",
+ *         track: "track from @/lib/analytics",
+ *       }));
+ *       return config;
+ *     },
+ *   };
+ *
+ *   // vite.config.ts
+ *   import { vitePlugin as pmInstrument } from "@precedence-dev/instrument/unplugin";
+ *   export default { plugins: [pmInstrument({ plan, track })] };
+ *
+ *   // app entry, ONCE, pulls in the delegated click listener for synthetic anchors
+ *   import "virtual:pm-tracking";
+ */
+const fs = __importStar(require("fs"));
+const unplugin_1 = require("unplugin");
+const instrument_1 = require("./instrument");
+const norm = (s) => s.replace(/\\/g, "/").split("?")[0];
+exports.unpluginPmInstrument = (0, unplugin_1.createUnplugin)((options) => {
+    const plan = typeof options.plan === "string"
+        ? JSON.parse(fs.readFileSync(options.plan, "utf8"))
+        : options.plan;
+    const opts = { track: options.track, emit: options.emit }; // track defaults to console.log in instrument.ts
+    const files = (0, instrument_1.planFiles)(plan);
+    const delegated = (0, instrument_1.planDelegations)(plan); // from the plan alone, no build ordering dependency
+    const VID = options.virtualModuleId || "virtual:pm-tracking";
+    const RESOLVED = "\0" + VID;
+    const touches = (id) => {
+        const c = norm(id);
+        return files.some((f) => c === f || c.endsWith("/" + f));
+    };
+    return {
+        name: "unplugin-precedence",
+        enforce: "pre", // run before the TS/JSX transpile, like the stamp loader
+        transformInclude(id) {
+            return touches(id);
+        },
+        transform(code, id) {
+            const r = (0, instrument_1.instrumentFile)(code, id, plan, opts);
+            if (!r)
+                return null;
+            options.onReport?.({ file: r.file, applied: r.applied.length, drift: r.warnings.length, skipped: r.skipped });
+            const warn = this.warn;
+            r.warnings.forEach((w) => warn?.(`precedence drift: ${w.detail}`));
+            r.skipped.forEach((s) => warn?.(`precedence skipped ${s.id ?? ""}: ${s.reason}`));
+            if (r.code === code)
+                return null; // nothing spliced or stamped
+            return r.map ? { code: r.code, map: r.map } : { code: r.code };
+        },
+        resolveId(id) {
+            return id === VID ? RESOLVED : null;
+        },
+        loadInclude(id) {
+            return id === RESOLVED;
+        },
+        load(id) {
+            if (id !== RESOLVED)
+                return null;
+            if (options.emit === "runtime") {
+                return "// runtime mode: import { installPrecedence } from '@precedence-dev/sdk' and call it at your app root instead of importing this\nexport {};\n";
+            }
+            return delegated.length
+                ? (0, instrument_1.buildDelegatedModule)(delegated, options.track || "track")
+                : "// precedence: no delegated (synthetic) anchors in the plan\nexport {};\n";
+        },
+    };
+});
+exports.vitePlugin = exports.unpluginPmInstrument.vite;
+exports.webpackPlugin = exports.unpluginPmInstrument.webpack;
+exports.rollupPlugin = exports.unpluginPmInstrument.rollup;
+exports.rspackPlugin = exports.unpluginPmInstrument.rspack;
+exports.esbuildPlugin = exports.unpluginPmInstrument.esbuild;
+exports.farmPlugin = exports.unpluginPmInstrument.farm;

package/dist/util.d.ts

@@ -0,0 +1,2 @@
+/** a readable message from a caught value */
+export declare function errMsg(e: unknown): string;

package/dist/util.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.errMsg = errMsg;
+/** a readable message from a caught value */
+function errMsg(e) {
+    return e instanceof Error ? e.message : String(e);
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@precedence-dev/instrument",
+  "version": "0.1.0",
+  "description": "Splice tracking calls into source (or a build) from a plan produced by Precedence's analysis engine. Source-available so anyone can read exactly what code it generates and where it puts it.",
+  "license": "FSL-1.1-ALv2",
+  "author": "Precedence",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/precedence-dev/instrument.git"
+  },
+  "homepage": "https://github.com/precedence-dev/instrument",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "precedence-instrument": "bin/precedence-instrument.js"
+  },
+  "main": "dist/generate/instrument.js",
+  "types": "dist/generate/instrument.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/generate/instrument.d.ts",
+      "default": "./dist/generate/instrument.js"
+    },
+    "./unplugin": {
+      "types": "./dist/generate/unplugin.d.ts",
+      "default": "./dist/generate/unplugin.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
+    "prepare": "npm run build",
+    "test": "npm run build && node --test \"test/**/*.test.mjs\" && node test/invariants.mjs"
+  },
+  "dependencies": {
+    "@precedence-dev/cli": "^0.1.0",
+    "magic-string": "^0.30.21",
+    "typescript": "^5.6.3",
+    "unplugin": "^2.3.11"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0"
+  }
+}