@frmwrkd/snag-anchor 0.1.0

package/dist/index.js

@@ -0,0 +1,90 @@
+/**
+ * `@frmwrkd/snag-anchor` — the unplugin that stamps `data-snag="path:line:col"` onto
+ * DOM elements at build time.
+ *
+ * ```html
+ * <button data-snag="src/checkout/PromoField.tsx:42:7" data-snag-cmp="PromoField">
+ * ```
+ *
+ * Two attributes, self-contained — **no global registry, no indirection**
+ * (doc 02 §2.1). This matters because only `data-*` attributes cross the
+ * ISOLATED-world boundary: expando properties the page attaches to DOM nodes
+ * (`__reactFiber$*`, `__svelte_meta`) are invisible to an ISOLATED content
+ * script. Tier 0 is therefore the only resolution path with no `postMessage`
+ * round trip — one `getAttribute` and you're done.
+ *
+ * ```ts
+ * // vite.config.ts
+ * import snagAnchor from '@frmwrkd/snag-anchor/vite';
+ * export default defineConfig({ plugins: [snagAnchor()] });
+ * ```
+ */
+import { createUnplugin } from 'unplugin';
+import { createDevtoolsJsonMiddleware, DEVTOOLS_JSON_PATH } from './devtools-json.js';
+import { resolveOptions } from './options.js';
+import { transformSource } from './transform.js';
+export const ANCHOR_ATTRIBUTE = 'data-snag';
+export const COMPONENT_ATTRIBUTE = 'data-snag-cmp';
+export { createFilter, DEFAULT_ATTRIBUTE, DEFAULT_COMPONENT_ATTRIBUTE, DEFAULT_EXCLUDE, DEFAULT_INCLUDE, isProductionEnv, normaliseId, resolveMode, resolveOptions, } from './options.js';
+export { findGitRoot, resolveRoot, toPosix, toRepoRelative } from './root.js';
+export { buildAttributes, escapeAttributeValue, renderAttributes } from './stamp.js';
+export { transformSource, stampContextFor } from './transform.js';
+export { default as snagAnchorBabelPlugin, stampJsx } from './babel/plugin.js';
+export { resolveComponentName } from './babel/component-name.js';
+export { stampVue, sfcComponentName } from './vue/transform.js';
+export { createDevtoolsJsonMiddleware, devtoolsJson, devtoolsWorkspaceUuid, DEVTOOLS_JSON_PATH, uuidV5, } from './devtools-json.js';
+export const unpluginFactory = (rawOptions) => {
+    const userOptions = rawOptions ?? {};
+    let options = resolveOptions(userOptions);
+    const attachDevtoolsJson = (server) => {
+        if (!options.devtoolsJson)
+            return;
+        // Registered unmounted on purpose — see `createDevtoolsJsonMiddleware`.
+        server.middlewares.use(createDevtoolsJsonMiddleware(options.root));
+    };
+    return {
+        name: 'snag-anchor',
+        // `pre` so the stamp lands in the source *before* the framework plugin
+        // compiles it: `@vitejs/plugin-vue` must see a `.vue` file that already
+        // carries the attributes, and the React plugin must still see real JSX.
+        enforce: 'pre',
+        transformInclude(id) {
+            return options.mode !== 'off' && options.filter(id);
+        },
+        transform(code, id) {
+            const result = transformSource(code, id, options);
+            if (result === null)
+                return null;
+            return { code: result.code, map: result.map };
+        },
+        vite: {
+            configResolved(config) {
+                // Fail closed: if Vite says this is a production build we believe it,
+                // even when NODE_ENV was never set. `forceProduction` can only ever
+                // reduce what is emitted (doc 02 §2.3).
+                options = resolveOptions(userOptions, {
+                    cwd: config.root ?? process.cwd(),
+                    forceProduction: config.isProduction === true,
+                });
+            },
+            configureServer(server) {
+                attachDevtoolsJson(server);
+            },
+            configurePreviewServer(server) {
+                attachDevtoolsJson(server);
+            },
+        },
+    };
+};
+export const unplugin = createUnplugin(unpluginFactory);
+export default unplugin;
+/**
+ * `emitRepoMap` (doc 02 §2.3, "run @frmwrkd/snag-repomap after build") is accepted and
+ * carried on `ResolvedAnchorOptions`, but nothing is wired to it yet:
+ * `@frmwrkd/snag-repomap` is milestone M3 and is not a dependency of this package. The
+ * option exists so a user's config does not have to change when it lands.
+ */
+export const EMIT_REPO_MAP_IS_WIRED = false;
+/** Re-exported so integrators can assert the endpoint without importing the module path. */
+export const DEVTOOLS_JSON_ENDPOINT = DEVTOOLS_JSON_PATH;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/loader.cjs

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+let modulePromise;
+function loadAnchor() {
+    modulePromise ??= import('./index.js');
+    return modulePromise;
+}
+function readOptions(context) {
+    let raw;
+    try {
+        raw = typeof context.getOptions === 'function' ? context.getOptions() : context.query;
+    }
+    catch {
+        raw = undefined;
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return {};
+    return raw;
+}
+function snagAnchorLoader(source) {
+    const callback = this.async();
+    if (typeof this.cacheable === 'function')
+        this.cacheable(true);
+    const resourcePath = this.resourcePath ?? this.resource ?? '';
+    const options = readOptions(this);
+    const emitWarning = this.emitWarning?.bind(this);
+    loadAnchor()
+        .then((anchor) => {
+        const resolved = anchor.resolveOptions(options);
+        const result = anchor.transformSource(source, resourcePath, resolved);
+        if (result === null) {
+            callback(null, source);
+            return;
+        }
+        callback(null, result.code, result.map);
+    })
+        .catch((error) => {
+        const reason = error instanceof Error ? error : new Error(String(error));
+        emitWarning?.(new Error(`[snag-anchor] skipped ${resourcePath}: ${reason.message}`));
+        callback(null, source);
+    });
+}
+module.exports = snagAnchorLoader;
+//# sourceMappingURL=loader.cjs.map

package/dist/loader.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.cjs","sourceRoot":"","sources":["../src/loader.cts"],"names":[],"mappings":";;AA8DA,IAAI,aAAgD,CAAC;AAErD,SAAS,UAAU;IACjB,aAAa,KAAK,MAAM,CAAC,YAAY,CAAC,CAAC;IACvC,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,SAAS,WAAW,CAAC,OAA6B;IAChD,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,OAAO,OAAO,CAAC,UAAU,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;IACxF,CAAC;IAAC,MAAM,CAAC;QACP,GAAG,GAAG,SAAS,CAAC;IAClB,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAC7E,OAAO,GAAoB,CAAC;AAC9B,CAAC;AAED,SAAS,gBAAgB,CAA6B,MAAc;IAClE,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;IAC9B,IAAI,OAAO,IAAI,CAAC,SAAS,KAAK,UAAU;QAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAE/D,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;IAC9D,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAEjD,UAAU,EAAE;SACT,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;QACf,MAAM,QAAQ,GAAG,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QAChD,MAAM,MAAM,GAAG,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,CAAC,CAAC;QACtE,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACvB,OAAO;QACT,CAAC;QACD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1C,CAAC,CAAC;SACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QACxB,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACzE,WAAW,EAAE,CAAC,IAAI,KAAK,CAAC,yBAAyB,YAAY,KAAK,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QACrF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACzB,CAAC,CAAC,CAAC;AACP,CAAC;AAED,MAAM,CAAC,OAAO,GAAG,gBAAgB,CAAC"}

package/dist/loader.d.cts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=loader.d.cts.map

package/dist/loader.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.cts","sourceRoot":"","sources":["../src/loader.cts"],"names":[],"mappings":""}

package/dist/magic-string.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `MagicString`, re-exported from a package we already depend on.
+ *
+ * Every transform in this package is a *splice*, never a re-print: we parse,
+ * work out where the attribute goes, and insert that one string. We never hand
+ * the file to a code generator. That matters for three reasons:
+ *
+ *  1. **Correctness.** Re-printing a `.tsx` file through `@babel/generator`
+ *     round-trips syntax this plugin has no business touching (decorators,
+ *     `satisfies`, whatever TypeScript ships next). A splice cannot corrupt
+ *     what it does not read.
+ *  2. **Line accuracy.** The whole product rests on the emitted line number
+ *     pointing at the element's opening tag *in the original file*. An
+ *     insertion that never contains a newline cannot move a line.
+ *  3. **Build overhead.** doc 02 §2.6 criterion 4 caps overhead at 8%. Parse +
+ *     splice is a fraction of parse + generate.
+ *
+ * `magic-string` itself is not a direct dependency of `@frmwrkd/snag-anchor` — it is
+ * re-exported by `@vue/compiler-sfc`, which is. It should be promoted to a
+ * direct dependency the next time the lockfile can be regenerated.
+ */
+export { MagicString } from '@vue/compiler-sfc';
+//# sourceMappingURL=magic-string.d.ts.map

package/dist/magic-string.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"magic-string.d.ts","sourceRoot":"","sources":["../src/magic-string.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/magic-string.js

@@ -0,0 +1,23 @@
+/**
+ * `MagicString`, re-exported from a package we already depend on.
+ *
+ * Every transform in this package is a *splice*, never a re-print: we parse,
+ * work out where the attribute goes, and insert that one string. We never hand
+ * the file to a code generator. That matters for three reasons:
+ *
+ *  1. **Correctness.** Re-printing a `.tsx` file through `@babel/generator`
+ *     round-trips syntax this plugin has no business touching (decorators,
+ *     `satisfies`, whatever TypeScript ships next). A splice cannot corrupt
+ *     what it does not read.
+ *  2. **Line accuracy.** The whole product rests on the emitted line number
+ *     pointing at the element's opening tag *in the original file*. An
+ *     insertion that never contains a newline cannot move a line.
+ *  3. **Build overhead.** doc 02 §2.6 criterion 4 caps overhead at 8%. Parse +
+ *     splice is a fraction of parse + generate.
+ *
+ * `magic-string` itself is not a direct dependency of `@frmwrkd/snag-anchor` — it is
+ * re-exported by `@vue/compiler-sfc`, which is. It should be promoted to a
+ * direct dependency the next time the lockfile can be regenerated.
+ */
+export { MagicString } from '@vue/compiler-sfc';
+//# sourceMappingURL=magic-string.js.map

package/dist/magic-string.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"magic-string.js","sourceRoot":"","sources":["../src/magic-string.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/nuxt.d.ts

@@ -0,0 +1,14 @@
+import type { AnchorOptions } from './options.js';
+interface PluginContainer {
+    plugins?: unknown[] | undefined;
+}
+interface NuxtLike {
+    options: {
+        vite?: PluginContainer | undefined;
+    };
+    hook(name: 'vite:extendConfig', fn: (config: PluginContainer) => void): void;
+    hook(name: 'webpack:config', fn: (configs: PluginContainer[]) => void): void;
+}
+export default function snagAnchorNuxtModule(options: AnchorOptions | undefined, nuxt: NuxtLike): void;
+export {};
+//# sourceMappingURL=nuxt.d.ts.map

package/dist/nuxt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nuxt.d.ts","sourceRoot":"","sources":["../src/nuxt.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAKlD,UAAU,eAAe;IACvB,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,SAAS,CAAC;CACjC;AAED,UAAU,QAAQ;IAChB,OAAO,EAAE;QAAE,IAAI,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;KAAE,CAAC;IAChD,IAAI,CAAC,IAAI,EAAE,mBAAmB,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,GAAG,IAAI,CAAC;IAC7E,IAAI,CAAC,IAAI,EAAE,gBAAgB,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;CAC9E;AAED,MAAM,CAAC,OAAO,UAAU,oBAAoB,CAC1C,OAAO,EAAE,aAAa,GAAG,SAAS,EAClC,IAAI,EAAE,QAAQ,GACb,IAAI,CAYN"}

package/dist/nuxt.js

@@ -0,0 +1,29 @@
+/**
+ * Nuxt module.
+ *
+ * ```ts
+ * // nuxt.config.ts
+ * export default defineNuxtConfig({ modules: ['@frmwrkd/snag-anchor/nuxt'] });
+ * ```
+ *
+ * Written against Nuxt's hooks rather than `@nuxt/kit`'s `addVitePlugin` /
+ * `addWebpackPlugin`, so `@nuxt/kit` does not become a dependency of a package
+ * that most users install for React.
+ */
+import { createVitePlugin, createWebpackPlugin } from 'unplugin';
+import { unpluginFactory } from './index.js';
+const vitePlugin = createVitePlugin(unpluginFactory);
+const webpackPlugin = createWebpackPlugin(unpluginFactory);
+export default function snagAnchorNuxtModule(options, nuxt) {
+    nuxt.hook('vite:extendConfig', (config) => {
+        config.plugins ??= [];
+        config.plugins.push(vitePlugin(options));
+    });
+    nuxt.hook('webpack:config', (configs) => {
+        for (const config of configs) {
+            config.plugins ??= [];
+            config.plugins.push(webpackPlugin(options));
+        }
+    });
+}
+//# sourceMappingURL=nuxt.js.map

package/dist/nuxt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nuxt.js","sourceRoot":"","sources":["../src/nuxt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEjE,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG7C,MAAM,UAAU,GAAG,gBAAgB,CAAC,eAAe,CAAC,CAAC;AACrD,MAAM,aAAa,GAAG,mBAAmB,CAAC,eAAe,CAAC,CAAC;AAY3D,MAAM,CAAC,OAAO,UAAU,oBAAoB,CAC1C,OAAkC,EAClC,IAAc;IAEd,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,CAAC,MAAM,EAAE,EAAE;QACxC,MAAM,CAAC,OAAO,KAAK,EAAE,CAAC;QACtB,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC,OAAO,EAAE,EAAE;QACtC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,CAAC,OAAO,KAAK,EAAE,CAAC;YACtB,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/options.d.ts

@@ -0,0 +1,101 @@
+/** doc 02 §2.3. Field-for-field, including the defaults in the comments. */
+export interface AnchorOptions {
+    /** default: `process.env.NODE_ENV !== 'production'` */
+    enabled?: boolean;
+    /** default `'data-snag'` */
+    attribute?: string;
+    /** default `'data-snag-cmp'` */
+    componentAttribute?: string;
+    /** default: git root; paths are relative to this */
+    root?: string;
+    /** default `['**\/*.{jsx,tsx,vue}']` — Svelte needs no injection (§2.2) */
+    include?: string[];
+    /** default `['**\/node_modules/**','**\/*.test.*','**\/*.stories.*']` */
+    exclude?: string[];
+    /** default true — stamp DOM elements, not component tags */
+    intrinsicOnly?: boolean;
+    /** default true — run @frmwrkd/snag-repomap after build */
+    emitRepoMap?: boolean;
+    /** default true — serve the well-known project-root file */
+    devtoolsJson?: boolean;
+    /** `'minimal'` = component name only, no path */
+    production?: false | 'minimal';
+}
+export declare const DEFAULT_ATTRIBUTE = "data-snag";
+export declare const DEFAULT_COMPONENT_ATTRIBUTE = "data-snag-cmp";
+/**
+ * `.svelte` is deliberately absent. Svelte 5 already attaches
+ * `element.__svelte_meta = { loc: { file, line, column } }` in dev and resolver
+ * tier 1 reads it straight off the node — injecting there would be duplicated
+ * work that can only disagree with the framework. doc 02 §2.2.
+ */
+export declare const DEFAULT_INCLUDE: readonly string[];
+export declare const DEFAULT_EXCLUDE: readonly string[];
+export declare const DEFAULT_INTRINSIC_ONLY = true;
+export declare const DEFAULT_EMIT_REPO_MAP = true;
+export declare const DEFAULT_DEVTOOLS_JSON = true;
+export declare const DEFAULT_PRODUCTION: false | 'minimal';
+/**
+ * `'off'`     — emit nothing at all.
+ * `'full'`    — `data-snag="path:line:col"` + `data-snag-cmp="Name"`.
+ * `'minimal'` — `data-snag-cmp="Name"` only. Never a path.
+ */
+export type AnchorMode = 'off' | 'full' | 'minimal';
+export interface ResolvedAnchorOptions {
+    mode: AnchorMode;
+    enabled: boolean;
+    isProduction: boolean;
+    attribute: string;
+    componentAttribute: string;
+    /** Absolute and POSIX-normalised. */
+    root: string;
+    include: readonly string[];
+    exclude: readonly string[];
+    intrinsicOnly: boolean;
+    emitRepoMap: boolean;
+    devtoolsJson: boolean;
+    production: false | 'minimal';
+    /** `true` when this module id should be transformed. */
+    filter: (id: string) => boolean;
+}
+export interface ResolveOptionsContext {
+    /** Where root detection starts. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Injected for tests; defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+    /**
+     * Fail-closed override. Vite's `configResolved` reports `config.isProduction`
+     * independently of `NODE_ENV`; when the bundler says "this is production" we
+     * believe it even if `NODE_ENV` was never set. This can only ever *reduce*
+     * what is emitted.
+     */
+    forceProduction?: boolean;
+}
+export declare function isProductionEnv(env?: Record<string, string | undefined>): boolean;
+/**
+ * The whole production gate, in one place so it can be tested as a matrix.
+ *
+ * | NODE_ENV     | enabled     | production  | mode      |
+ * |--------------|-------------|-------------|-----------|
+ * | development  | (default)   | (default)   | full      |
+ * | production   | (default)   | (default)   | off       |
+ * | production   | (default)   | 'minimal'   | off       | ← `enabled` defaults false in prod
+ * | production   | true        | (default)   | off       |
+ * | production   | true        | 'minimal'   | minimal   |
+ * | development  | false       | anything    | off       |
+ */
+export declare function resolveMode(options: AnchorOptions, isProduction: boolean): AnchorMode;
+export declare function resolveOptions(options?: AnchorOptions, context?: ResolveOptionsContext): ResolvedAnchorOptions;
+/**
+ * Bundler module ids are not plain paths. Vite appends query strings
+ * (`/src/App.vue?vue&type=template&lang.js`), prefixes virtual modules with a
+ * NUL byte, and passes through `http:` ids for remote modules. Normalise to a
+ * bare POSIX filesystem path or return `null` for "this is not a file".
+ */
+export declare function normaliseId(id: string): string | null;
+/**
+ * `exclude` beats `include`, always. A `.stories.tsx` under a matching include
+ * glob is still excluded.
+ */
+export declare function createFilter(include: readonly string[], exclude: readonly string[]): (id: string) => boolean;
+//# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"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"}

package/dist/options.js

@@ -0,0 +1,122 @@
+/**
+ * `AnchorOptions` — doc 02 §2.3, verbatim, with the documented defaults.
+ *
+ * ## Production is opt-in and defaults off
+ *
+ * doc 02 §2.3: "Never emit full source paths to a public production build
+ * without the user explicitly choosing it." Emitting `src/checkout/Promo.tsx`
+ * into a public bundle is an information-disclosure bug — it publishes your
+ * directory layout, your internal component names, and (with a repo map) a
+ * decent sketch of your architecture, to anyone with DevTools.
+ *
+ * So the gate is deliberately two-layered:
+ *
+ *   - `enabled` defaults to `process.env.NODE_ENV !== 'production'`, which
+ *     switches the whole plugin off in a production build.
+ *   - Even with `enabled: true` forced on, a production build can only ever
+ *     reach `'minimal'` (component name, no path). The `production` option's
+ *     type is `false | 'minimal'` — there is no value that means "full paths in
+ *     production", by design.
+ */
+import picomatch from 'picomatch';
+import { resolveRoot, toPosix } from './root.js';
+export const DEFAULT_ATTRIBUTE = 'data-snag';
+export const DEFAULT_COMPONENT_ATTRIBUTE = 'data-snag-cmp';
+/**
+ * `.svelte` is deliberately absent. Svelte 5 already attaches
+ * `element.__svelte_meta = { loc: { file, line, column } }` in dev and resolver
+ * tier 1 reads it straight off the node — injecting there would be duplicated
+ * work that can only disagree with the framework. doc 02 §2.2.
+ */
+export const DEFAULT_INCLUDE = ['**/*.{jsx,tsx,vue}'];
+export const DEFAULT_EXCLUDE = [
+    '**/node_modules/**',
+    '**/*.test.*',
+    '**/*.stories.*',
+];
+export const DEFAULT_INTRINSIC_ONLY = true;
+export const DEFAULT_EMIT_REPO_MAP = true;
+export const DEFAULT_DEVTOOLS_JSON = true;
+export const DEFAULT_PRODUCTION = false;
+export function isProductionEnv(env = process.env) {
+    return env['NODE_ENV'] === 'production';
+}
+/**
+ * The whole production gate, in one place so it can be tested as a matrix.
+ *
+ * | NODE_ENV     | enabled     | production  | mode      |
+ * |--------------|-------------|-------------|-----------|
+ * | development  | (default)   | (default)   | full      |
+ * | production   | (default)   | (default)   | off       |
+ * | production   | (default)   | 'minimal'   | off       | ← `enabled` defaults false in prod
+ * | production   | true        | (default)   | off       |
+ * | production   | true        | 'minimal'   | minimal   |
+ * | development  | false       | anything    | off       |
+ */
+export function resolveMode(options, isProduction) {
+    const enabled = options.enabled ?? !isProduction;
+    if (!enabled)
+        return 'off';
+    if (isProduction)
+        return options.production === 'minimal' ? 'minimal' : 'off';
+    return 'full';
+}
+export function resolveOptions(options = {}, context = {}) {
+    const env = context.env ?? process.env;
+    const isProduction = context.forceProduction === true || isProductionEnv(env);
+    const include = options.include ?? DEFAULT_INCLUDE;
+    const exclude = options.exclude ?? DEFAULT_EXCLUDE;
+    return {
+        mode: resolveMode(options, isProduction),
+        enabled: options.enabled ?? !isProduction,
+        isProduction,
+        attribute: options.attribute ?? DEFAULT_ATTRIBUTE,
+        componentAttribute: options.componentAttribute ?? DEFAULT_COMPONENT_ATTRIBUTE,
+        root: resolveRoot(options.root, context.cwd ?? process.cwd()),
+        include,
+        exclude,
+        intrinsicOnly: options.intrinsicOnly ?? DEFAULT_INTRINSIC_ONLY,
+        emitRepoMap: options.emitRepoMap ?? DEFAULT_EMIT_REPO_MAP,
+        devtoolsJson: options.devtoolsJson ?? DEFAULT_DEVTOOLS_JSON,
+        production: options.production ?? DEFAULT_PRODUCTION,
+        filter: createFilter(include, exclude),
+    };
+}
+/**
+ * Bundler module ids are not plain paths. Vite appends query strings
+ * (`/src/App.vue?vue&type=template&lang.js`), prefixes virtual modules with a
+ * NUL byte, and passes through `http:` ids for remote modules. Normalise to a
+ * bare POSIX filesystem path or return `null` for "this is not a file".
+ */
+export function normaliseId(id) {
+    if (id === '')
+        return null;
+    // Rollup/Vite virtual module convention.
+    if (id.startsWith('\0') || id.includes('\0'))
+        return null;
+    // A real scheme (`http://`, `data:`), never a Windows drive letter (`C:/`).
+    if (/^[a-zA-Z][a-zA-Z\d+\-.]*:\/\//.test(id) || id.startsWith('data:'))
+        return null;
+    const queryAt = id.search(/[?#]/);
+    const bare = queryAt === -1 ? id : id.slice(0, queryAt);
+    if (bare === '')
+        return null;
+    return toPosix(bare);
+}
+/**
+ * `exclude` beats `include`, always. A `.stories.tsx` under a matching include
+ * glob is still excluded.
+ */
+export function createFilter(include, exclude) {
+    const isIncluded = include.length > 0 ? picomatch(include, { dot: true }) : () => false;
+    const isExcluded = exclude.length > 0 ? picomatch(exclude, { dot: true }) : () => false;
+    return (id) => {
+        const file = normaliseId(id);
+        if (file === null)
+            return false;
+        if (isExcluded(file))
+            return false;
+        return isIncluded(file);
+    };
+}
+//# sourceMappingURL=options.js.map

package/dist/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"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"}

package/dist/rollup.d.ts

@@ -0,0 +1,3 @@
+declare const _default: (options?: import("./options.js").AnchorOptions | undefined) => import("rollup").Plugin<any> | import("rollup").Plugin<any>[];
+export default _default;
+//# sourceMappingURL=rollup.d.ts.map

package/dist/rollup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollup.d.ts","sourceRoot":"","sources":["../src/rollup.ts"],"names":[],"mappings":";AAUA,wBAAmD"}

package/dist/rollup.js

@@ -0,0 +1,11 @@
+/**
+ * ```ts
+ * // rollup.config.js
+ * import snagAnchor from '@frmwrkd/snag-anchor/rollup';
+ * export default { plugins: [snagAnchor()] };
+ * ```
+ */
+import { createRollupPlugin } from 'unplugin';
+import { unpluginFactory } from './index.js';
+export default createRollupPlugin(unpluginFactory);
+//# sourceMappingURL=rollup.js.map

package/dist/rollup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollup.js","sourceRoot":"","sources":["../src/rollup.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C,eAAe,kBAAkB,CAAC,eAAe,CAAC,CAAC"}

package/dist/root.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Backslashes → forward slashes. Applied to every path this package emits.
+ *
+ * Note this is deliberately *not* `path.posix.normalize` — we do not want to
+ * collapse `..` segments or otherwise rewrite a path the caller gave us, only
+ * to make the separator identical on every platform.
+ */
+export declare function toPosix(p: string): string;
+/** Test seam — the caches are process-global and would otherwise leak between tests. */
+export declare function clearRootCaches(): void;
+/**
+ * Nearest ancestor directory containing `.git`.
+ *
+ * `.git` is tested with `existsSync`, not `isDirectory`, on purpose: in a git
+ * worktree or a submodule `.git` is a *file* containing a `gitdir:` pointer.
+ * Treating it as "not a repo" would push the root up to the parent checkout and
+ * every emitted path would gain a bogus prefix.
+ */
+export declare function findGitRoot(startDir: string): string | undefined;
+/** Nearest ancestor directory containing `package.json`. Fallback when there is no git repo. */
+export declare function findManifestDir(startDir: string): string | undefined;
+/**
+ * The project root every emitted path is relative to.
+ *
+ * Precedence: explicit `root` option → git root → nearest `package.json` →
+ * the working directory. Always absolute and always POSIX-normalised.
+ */
+export declare function resolveRoot(explicitRoot?: string, cwd?: string): string;
+/**
+ * `/Users/theo/dev/app/src/App.tsx` + root `/Users/theo/dev/app` →
+ * `src/App.tsx`.
+ *
+ * A file outside the root keeps its `../` prefix rather than being silently
+ * rewritten — `root + '/' + '../lib/x.tsx'` still resolves to the right file,
+ * and inventing a path is the one failure mode doc 00 §3 forbids outright.
+ */
+export declare function toRepoRelative(absoluteFile: string, root: string): string;
+//# sourceMappingURL=root.d.ts.map

package/dist/root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root.d.ts","sourceRoot":"","sources":["../src/root.ts"],"names":[],"mappings":"AAsBA;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzC;AAMD,wFAAwF;AACxF,wBAAgB,eAAe,IAAI,IAAI,CAGtC;AAoBD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEhE;AAED,gGAAgG;AAChG,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,GAAE,MAAsB,GAAG,MAAM,CAMtF;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKzE"}