@reticlehq/babel-plugin 3.2.0 → 3.4.0

package/README.md

@@ -23,4 +23,6 @@ export default defineConfig({
 module.exports = { plugins: [require('@reticlehq/babel-plugin').default] };
 ```
 
-After this, `reticle_inspect` returns `component.source = { file, line, column }`. Only host elements (`<div>`, `<button>`, …) are stamped; components are left untouched. Apache-2.0.
+After this, `reticle_look { action: "element" }` returns `component.source = { file, line, column }`. Only host elements (`<div>`, `<button>`, …) are stamped; components are left untouched.
+
+**Opting one file out:** a file whose first non-empty line is `// @reticle-ignore` (or `/* @reticle-ignore */`) is not stamped at all. Whole file, first line — the reasons to opt out are file-shaped, and a marker that works from anywhere is a marker nobody can find. Apache-2.0.

package/dist/ignore.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Is this file opted out of source stamping?
+ *
+ * True when the FIRST non-empty line is a comment carrying `@reticle-ignore` — the line form, the
+ * block form, or the HTML form a `.svelte` file needs because it has no line for a `//` before its
+ * markup. Position is strict: a license header on line 1 and the marker on line 2 is not an opt-out,
+ * so the rule can be checked at a glance and documented in one sentence. The word is strict too:
+ * the comment's whole content must BE the marker, so `@reticle-ignore-next-line` is not this.
+ *
+ * Shared by the Babel plugin (which covers Vite, `@reticlehq/next` and direct Babel users) and the
+ * Vite plugin (which also owns the Svelte stamper), so there is one reading of the marker. The
+ * marker string itself is a core constant for the same reason (#853).
+ */
+export declare function isSourceStampingIgnored(code: string): boolean;

package/dist/ignore.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSourceStampingIgnored = isSourceStampingIgnored;
+const source_constants_1 = require("@reticlehq/core/source-constants");
+/**
+ * Is this file opted out of source stamping?
+ *
+ * True when the FIRST non-empty line is a comment carrying `@reticle-ignore` — the line form, the
+ * block form, or the HTML form a `.svelte` file needs because it has no line for a `//` before its
+ * markup. Position is strict: a license header on line 1 and the marker on line 2 is not an opt-out,
+ * so the rule can be checked at a glance and documented in one sentence. The word is strict too:
+ * the comment's whole content must BE the marker, so `@reticle-ignore-next-line` is not this.
+ *
+ * Shared by the Babel plugin (which covers Vite, `@reticlehq/next` and direct Babel users) and the
+ * Vite plugin (which also owns the Svelte stamper), so there is one reading of the marker. The
+ * marker string itself is a core constant for the same reason (#853).
+ */
+function isSourceStampingIgnored(code) {
+    const line = firstNonEmptyLine(code);
+    if (line === undefined)
+        return false;
+    const content = commentContent(line);
+    return content === source_constants_1.RETICLE_IGNORE_MARKER;
+}
+function firstNonEmptyLine(code) {
+    for (const raw of code.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line.length > 0)
+            return line;
+    }
+    return undefined;
+}
+/** The text inside a one-line comment, trimmed — or undefined when the line is not one. */
+function commentContent(line) {
+    if (line.startsWith('//'))
+        return line.slice(2).trim();
+    if (line.startsWith('/*') && line.endsWith('*/'))
+        return line.slice(2, -2).trim();
+    if (line.startsWith('<!--') && line.endsWith('-->'))
+        return line.slice(4, -3).trim();
+    return undefined;
+}

package/dist/index.js

@@ -2,7 +2,10 @@
 const node_path_1 = require("node:path");
 const source_constants_1 = require("@reticlehq/core/source-constants");
 const dom_tags_js_1 = require("./dom-tags.js");
+const ignore_js_1 = require("./ignore.js");
 const SOURCE_ATTR = source_constants_1.DATA_RETICLE_SOURCE_ATTR;
+/** Per-file plugin state key: this file carries `@reticle-ignore` on its first non-empty line. */
+const IGNORED = 'reticleIgnored';
 /**
  * Stamps `data-reticle-source="relativeFile:line:col"` on every JSX host element (lowercase
  * tag). @reticlehq/react reads it to map a DOM node back to its source — needed on React 19,
@@ -18,7 +21,15 @@ function reticleSourcePlugin({ types: t }) {
     return {
         name: 'reticle-source',
         visitor: {
+            // Decided once per FILE, on the file's own text, and kept on the per-file `state` — never on
+            // the plugin instance, which Babel reuses across every file in a build. A plugin-level flag
+            // set by one opted-out file would switch stamping off for everything after it.
+            Program(_path, state) {
+                state.set(IGNORED, (0, ignore_js_1.isSourceStampingIgnored)(state.file.code));
+            },
             JSXOpeningElement(path, state) {
+                if (true === state.get(IGNORED))
+                    return;
                 const node = path.node;
                 // Host elements only (e.g. <div>, <button>) — skip components (<App />).
                 if (node.name.type !== 'JSXIdentifier')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/babel-plugin",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Babel plugin that stamps data-reticle-source=\"file:line:col\" on JSX host elements so @reticlehq/react can map a DOM node to its source (works on React 19, which dropped _debugSource).",
   "type": "commonjs",
   "license": "Apache-2.0",
@@ -27,6 +27,11 @@
       "types": "./dist/index.d.ts",
       "require": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./ignore": {
+      "types": "./dist/ignore.d.ts",
+      "require": "./dist/ignore.js",
+      "default": "./dist/ignore.js"
     }
   },
   "files": [
@@ -35,7 +40,7 @@
     "NOTICE"
   ],
   "dependencies": {
-    "@reticlehq/core": "3.2.0"
+    "@reticlehq/core": "3.4.0"
   },
   "peerDependencies": {
     "@babel/core": "^7"