@precedence-dev/instrument 0.1.0

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Precedence
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -0,0 +1,109 @@
+# @precedence-dev/instrument
+
+Splices tracking calls into your source (or your build, via a bundler plugin)
+from a **plan** — a list of exact anchors (file, structural id, condition
+fingerprint) that [`@precedence-dev/cli`](https://github.com/precedence-dev/core)
+already resolved. This package does not decide *what* to track or *where* — it
+only knows how to turn an already-decided anchor into a concrete, safe code
+edit and apply it.
+
+FSL-1.1-ALv2 (converts to Apache-2.0 two years after each release), like the rest
+of Precedence. It's split from the analysis engine so
+you can audit the part that touches your source on its own — every edit
+primitive is additive, every emitted call is fire-and-forget, and the tests
+actually run the generated code to prove it.
+
+## Use
+
+```
+# dry-run: print the diff, touch nothing
+precedence-instrument --plan plan.json --dir src --track "track from @/lib/analytics"
+
+# apply it (refuses on a dirty git tree, so the injection lands in its own commit)
+precedence-instrument --plan plan.json --dir src --track "track from @/lib/analytics" --apply
+
+# CI: fail the build if the committed source has drifted from the plan
+precedence-instrument --plan plan.json --dir src --track track --check
+```
+
+`--plan` is the events export from the picker (`@precedence-dev/sdk`) or the viewer
+(`@precedence-dev/viewer`). `--dir` is repeatable. `-h` prints every flag.
+
+## Emit modes
+
+| `--emit` | injected call | change an event without a rebuild? |
+| --- | --- | --- |
+| `direct` (default) | `track("event_name", { pm_id, ...props })`, baked in; adds the `--track` import | no — it's all in the source |
+| `runtime` | `globalThis.__pm?.("<anchor id>", { ...in-scope props })`, no import | yes — enable/disable, rename, retarget, change the discriminator, narrow props: all plan edits |
+
+`runtime` mode needs [`@precedence-dev/sdk`](https://github.com/precedence-dev/sdk)'s
+`installPrecedence` called once at your app root — it maps the anchor id back to
+the event name, adds `pm_id`, layers on the plan's static props, and catches the
+clicks on synthetic anchors (which `runtime` mode only stamps with `data-precedence-id`,
+no listener). In `direct` mode the delegated listener is generated instead —
+`--runtime <file>` writes it, import it once at the app root.
+
+## Debug a live event: `--explain`
+
+Every emitted event carries `pm_id` (the structural anchor id). Copy one from
+the dashboard and run:
+
+```
+precedence-instrument --plan plan.json --dir src --explain "src/Checkout.tsx#Checkout::form|onSubmit|result_ok"
+precedence-instrument --plan plan.json --dir src --explain "<pm_id>" --json   # structured
+```
+
+It doesn't instrument anything — it traces the id back to its exact fire site
+and reports, per property, the **structural** reasons a value can arrive null
+(out of scope here → baked `undefined`; the branch fires precisely when the
+value is absent; an ambient store that can be empty; a nullable hop in the
+accessor path; a state/data-hook binding that starts empty). It can't see
+runtime data quality — an API that returned null shows as "resolves".
+
+## What it actually does — and doesn't
+
+- Every edit primitive (`block-prepend`, `wrap-expr`, `synthesize-else`,
+  `split-and`) is purely additive: it inserts new code, it never rewrites or
+  restructures anything that was already there. See `src/generate/instrument.ts`.
+- Every emitted call is wrapped so it can never affect the surrounding control
+  flow, even if it throws or its returned promise rejects — `safeStatement`/
+  `safeExpr` in the same file. This is a provable property, not an assumption:
+  see the `fire-and-forget:` checks in `test/invariants.mjs`, which actually
+  *run* the generated code with a throwing and a rejecting `track()` and
+  assert nothing else breaks.
+- It never invents an anchor. If a plan's anchor doesn't resolve against the
+  current source (renamed, moved, deleted), it's reported `skipped` with a
+  precise reason — never silently guessed.
+- Two delivery paths, same resolver: `instrument()` (the CLI codemod, writes
+  to disk) and `instrumentFile()` (the bundler transform in
+  `src/generate/unplugin.ts`, source never touches disk — the tracking calls
+  exist only in the built bundle).
+
+## Depending on `@precedence-dev/cli`
+
+`instrument()` re-runs `@precedence-dev/cli`'s `analyze()` so it derives every id and
+fingerprint the exact same way the scan did. `package.json` depends on
+`@precedence-dev/cli` as a normal semver dependency.
+
+## Structure
+
+```
+src/
+├── generate/
+│   ├── instrument.ts   the resolver + edit primitives + safety wrapping
+│   ├── unplugin.ts      the bundler-plugin delivery path
+│   ├── explain.ts       trace a fired event's pm_id back to its source
+│   └── cli.ts           the precedence-instrument binary
+├── discover.ts          resolve --dir/--files/--changed-since to a file list
+└── util.ts              (tiny, no analysis logic — see below)
+```
+
+`discover.ts` and `util.ts` are intentionally duplicated from `@precedence-dev/cli`'s
+own copies rather than imported: they're plain fs/git utilities with no
+analysis logic in them, so keeping them local avoids a cross-package
+dependency for plain fs/git helpers. The one thing to
+keep in sync by hand is `--changed-since` / `--dir` semantics: run the scan and
+the instrument step over the same file set, or an anchor the scan produced can
+land outside what instrument looked at and read as `skipped`. `@precedence-dev/cli`'s
+`analyze()` — the id + fingerprint derivation, which *is* shared — is bit-for-bit
+identical between the two; only the file-list front differs.

package/bin/precedence-instrument.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// Thin entry point. The real CLI is TypeScript in src/, compiled to dist/.
+"use strict";
+try {
+  require("../dist/generate/cli.js");
+} catch (err) {
+  if (err && err.code === "MODULE_NOT_FOUND" && /dist[\\/]generate/.test(String(err.message))) {
+    process.stderr.write("@precedence-dev/instrument is not built yet - run `npm run build` first.\n");
+    process.exit(2);
+  }
+  throw err;
+}

package/dist/discover.d.ts

@@ -0,0 +1,10 @@
+export interface DiscoverInput {
+    paths?: string[];
+    files?: string[];
+    changedSince?: string;
+}
+export interface DiscoverResult {
+    files: string[];
+    errors: string[];
+}
+export declare function discoverSources(input: DiscoverInput): DiscoverResult;

package/dist/discover.js

@@ -0,0 +1,95 @@
+"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.discoverSources = discoverSources;
+/**
+ * Resolve CLI-style inputs (dirs / files / a git ref) to a sorted file list.
+ *
+ * Duplicated from @precedence-dev/cli's own copy rather than imported from it: this
+ * is a plain fs/git utility with no analysis logic in it, so keeping it local
+ * keeps this package importable without pulling in the whole engine.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const util_1 = require("./util");
+const SOURCE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".cts", ".mts", ".cjs", ".mjs"];
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", "out", "coverage"]);
+const isSource = (f) => SOURCE_EXTENSIONS.includes(path.extname(f).toLowerCase());
+function walkDir(dir, out) {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (e.isDirectory()) {
+            if (!SKIP_DIRS.has(e.name))
+                walkDir(path.join(dir, e.name), out);
+        }
+        else if (isSource(e.name))
+            out.push(path.join(dir, e.name));
+    }
+}
+function discoverSources(input) {
+    const set = new Set();
+    const errors = [];
+    for (const p of input.paths ?? []) {
+        if (!fs.existsSync(p)) {
+            errors.push(`path not found: ${p}`);
+            continue;
+        }
+        if (fs.statSync(p).isDirectory()) {
+            const found = [];
+            walkDir(p, found);
+            found.forEach((f) => set.add(path.resolve(f)));
+        }
+        else
+            set.add(path.resolve(p));
+    }
+    for (const f of input.files ?? []) {
+        if (fs.existsSync(f))
+            set.add(path.resolve(f));
+        else
+            errors.push(`file not found: ${f}`);
+    }
+    if (input.changedSince) {
+        try {
+            (0, child_process_1.execFileSync)("git", ["diff", "--name-only", input.changedSince], { encoding: "utf8" })
+                .split("\n").map((s) => s.trim())
+                .filter((f) => f && isSource(f) && fs.existsSync(f))
+                .forEach((f) => set.add(path.resolve(f)));
+        }
+        catch (e) {
+            errors.push(`--changed-since ${input.changedSince} failed: ${(0, util_1.errMsg)(e)}`);
+        }
+    }
+    return { files: [...set].sort(), errors };
+}

package/dist/generate/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};