@prover-coder-ai/component-tagger 1.0.22 → 1.0.25

package/README.md

@@ -1,17 +1,32 @@
 # @prover-coder-ai/component-tagger
 
-Vite plugin that adds a single `path` attribute to every JSX opening tag.
+Vite and Babel plugin that adds a `data-path` attribute to every JSX opening tag, enabling component source location tracking.
 
-Example output:
+## Example output
 
 ```html
-<h1 path="src/App.tsx:22:4">Hello</h1>
+<h1 data-path="src/App.tsx:22:4">Hello</h1>
 ```
 
 Format: `<relative-file-path>:<line>:<column>`
 
+## Features
+
+- ✅ **Idempotent**: adds `data-path` only if it doesn't already exist
+- ✅ **HTML5 compliant**: uses standard `data-*` attributes
+- ✅ **Configurable**: customize the attribute name via options
+- ✅ **Dual plugin support**: works with both Vite and Babel
+
+## Installation
+
+```bash
+npm install @prover-coder-ai/component-tagger
+```
+
 ## Usage
 
+### Vite Plugin
+
 ```ts
 import { defineConfig, type PluginOption } from "vite"
 import { componentTagger } from "@prover-coder-ai/component-tagger"
@@ -23,3 +38,84 @@ export default defineConfig(({ mode }) => {
   return { plugins }
 })
 ```
+
+**With custom attribute name:**
+
+```ts
+const plugins = [
+  isDevelopment && componentTagger({ attributeName: "data-component-path" })
+].filter(Boolean) as PluginOption[]
+```
+
+### Babel Plugin (e.g., Next.js)
+
+Add to your `.babelrc`:
+
+```json
+{
+  "presets": ["next/babel"],
+  "env": {
+    "development": {
+      "plugins": ["@prover-coder-ai/component-tagger/babel"]
+    }
+  }
+}
+```
+
+**With options:**
+
+```json
+{
+  "presets": ["next/babel"],
+  "env": {
+    "development": {
+      "plugins": [
+        [
+          "@prover-coder-ai/component-tagger/babel",
+          {
+            "rootDir": "/custom/root",
+            "attributeName": "data-component-path"
+          }
+        ]
+      ]
+    }
+  }
+}
+```
+
+## Options
+
+### Vite Plugin Options
+
+```ts
+type ComponentTaggerOptions = {
+  /**
+   * Name of the attribute to add to JSX elements.
+   * @default "data-path"
+   */
+  attributeName?: string
+}
+```
+
+### Babel Plugin Options
+
+```ts
+type ComponentTaggerBabelPluginOptions = {
+  /**
+   * Root directory for computing relative paths.
+   * @default process.cwd()
+   */
+  rootDir?: string
+  /**
+   * Name of the attribute to add to JSX elements.
+   * @default "data-path"
+   */
+  attributeName?: string
+}
+```
+
+## Behavior Guarantees
+
+- **Idempotency**: If `data-path` (or custom attribute) already exists on an element, no duplicate is added
+- **Default attribute**: `data-path` is used when no `attributeName` is specified
+- **Standard compliance**: Uses HTML5 `data-*` custom attributes by default

package/babel.cjs

@@ -0,0 +1,81 @@
+/**
+ * CommonJS entry point for the component-tagger Babel plugin.
+ *
+ * This file provides a CommonJS-compatible wrapper for the Babel plugin,
+ * allowing it to be used with Next.js and other tools that require CJS modules.
+ *
+ * @example
+ * // .babelrc
+ * {
+ *   "presets": ["next/babel"],
+ *   "plugins": ["@prover-coder-ai/component-tagger/babel"]
+ * }
+ */
+// CHANGE: provide CommonJS entry point for Babel plugin with configurable attributeName.
+// WHY: Babel configuration often requires CommonJS modules; support custom attribute names.
+// REF: issue-12, issue-14
+// FORMAT THEOREM: forall require: require(babel.cjs) -> PluginFactory
+// PURITY: SHELL
+// EFFECT: n/a
+// INVARIANT: exports match Babel plugin signature
+// COMPLEXITY: O(1)/O(1)
+
+const path = require("node:path")
+
+const componentPathAttributeName = "data-path"
+const jsxFilePattern = /\.(tsx|jsx)(\?.*)?$/u
+
+const isJsxFile = (id) => jsxFilePattern.test(id)
+
+const formatComponentPathValue = (relativeFilename, line, column) =>
+  `${relativeFilename}:${line}:${column}`
+
+const attrExists = (node, attrName, t) =>
+  node.attributes.some(
+    (attr) => t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name, { name: attrName })
+  )
+
+module.exports = function componentTaggerBabelPlugin({ types: t }) {
+  return {
+    name: "component-path-babel-tagger",
+    visitor: {
+      JSXOpeningElement(nodePath, state) {
+        const { node } = nodePath
+        const filename = state.filename
+
+        // Skip if no filename
+        if (filename === undefined) {
+          return
+        }
+
+        // Skip if no location info
+        if (node.loc === null || node.loc === undefined) {
+          return
+        }
+
+        // Skip if not a JSX/TSX file
+        if (!isJsxFile(filename)) {
+          return
+        }
+
+        // Compute relative path from root and get attribute name
+        const opts = state.opts || {}
+        const rootDir = opts.rootDir || state.cwd || process.cwd()
+        const attributeName = opts.attributeName || componentPathAttributeName
+        const relativeFilename = path.relative(rootDir, filename)
+
+        // Skip if already has the specified attribute (idempotency)
+        if (attrExists(node, attributeName, t)) {
+          return
+        }
+
+        const { column, line } = node.loc.start
+        const value = formatComponentPathValue(relativeFilename, line, column)
+
+        node.attributes.push(
+          t.jsxAttribute(t.jsxIdentifier(attributeName), t.stringLiteral(value))
+        )
+      }
+    }
+  }
+}

package/dist/core/component-path.d.ts

@@ -1,4 +1,4 @@
-export declare const componentPathAttributeName = "path";
+export declare const componentPathAttributeName = "data-path";
 /**
  * Checks whether the Vite id represents a JSX or TSX module.
  *

package/dist/core/component-path.js

@@ -1,15 +1,15 @@
 const jsxFilePattern = /\.(tsx|jsx)(\?.*)?$/u;
-// CHANGE: define canonical attribute name for component path tagging.
-// WHY: reduce metadata to a single attribute while keeping full source location.
-// QUOTE(TZ): "\u0421\u0430\u043c \u043a\u043e\u043c\u043f\u043e\u043d\u0435\u043d\u0442 \u0434\u043e\u043b\u0436\u0435\u043d \u0431\u044b\u0442\u044c \u0432 \u0442\u0435\u043a\u0443\u0449\u0435\u043c app \u043d\u043e \u0432\u043e\u0442 \u0447\u0442\u043e \u0431\u044b \u0435\u0433\u043e \u043f\u0440\u043e\u0442\u0435\u0441\u0442\u0438\u0440\u043e\u0432\u0430\u0442\u044c \u043d\u0430\u0434\u043e \u0441\u043e\u0437\u0434\u0430\u0442\u044c \u0435\u0449\u0451 \u043e\u0434\u0438\u043d \u043f\u0440\u043e\u0435\u043a\u0442 \u043a\u043e\u0442\u043e\u0440\u044b\u0439 \u043d\u0430\u0448 \u0442\u0435\u043a\u0443\u0449\u0438\u0439 \u0430\u043f\u043f \u0431\u0443\u0434\u0435\u0442 \u043f\u043e\u0434\u043a\u043b\u044e\u0447\u0430\u0442\u044c"
-// REF: user-2026-01-14-frontend-consumer
-// SOURCE: n/a
-// FORMAT THEOREM: forall a in AttributeName: a = "path"
+// CHANGE: rename attribute from "path" to "data-path" for HTML5 compliance.
+// WHY: data-* attributes are standard HTML5 custom data attributes, improving compatibility.
+// QUOTE(issue-14): "Rename attribute path → data-path (breaking change)"
+// REF: issue-14
+// SOURCE: https://html.spec.whatwg.org/multipage/dom.html#custom-data-attribute
+// FORMAT THEOREM: forall a in AttributeName: a = "data-path"
 // PURITY: CORE
 // EFFECT: n/a
 // INVARIANT: attribute name remains stable across transforms
 // COMPLEXITY: O(1)/O(1)
-export const componentPathAttributeName = "path";
+export const componentPathAttributeName = "data-path";
 /**
  * Checks whether the Vite id represents a JSX or TSX module.
  *

package/dist/core/jsx-tagger.d.ts

@@ -0,0 +1,75 @@
+import type { types as t, Visitor } from "@babel/core";
+/**
+ * Context required for JSX tagging.
+ *
+ * @pure true
+ */
+export type JsxTaggerContext = {
+    /**
+     * Relative file path from the project root.
+     */
+    readonly relativeFilename: string;
+    /**
+     * Name of the attribute to add (defaults to "data-path").
+     */
+    readonly attributeName: string;
+};
+/**
+ * Checks if a JSX attribute with the given name already exists on the element.
+ *
+ * @param node - JSX opening element to check.
+ * @param attrName - Name of the attribute to look for.
+ * @returns true if attribute exists, false otherwise.
+ *
+ * @pure true
+ * @invariant returns true iff attribute with exact name exists
+ * @complexity O(n) where n = number of attributes
+ */
+export declare const attrExists: (node: t.JSXOpeningElement, attrName: string, types: typeof t) => boolean;
+/**
+ * Creates a JSX attribute with the component path value.
+ *
+ * @param attributeName - Name of the attribute to create.
+ * @param relativeFilename - Relative path to the file.
+ * @param line - 1-based line number.
+ * @param column - 0-based column number.
+ * @param types - Babel types module.
+ * @returns JSX attribute node with the path value.
+ *
+ * @pure true
+ * @invariant attribute name matches the provided attributeName parameter
+ * @complexity O(1)
+ */
+export declare const createPathAttribute: (attributeName: string, relativeFilename: string, line: number, column: number, types: typeof t) => t.JSXAttribute;
+/**
+ * Processes a single JSX opening element and adds path attribute if needed.
+ *
+ * This is the unified business logic for tagging JSX elements with source location.
+ * Both the Vite plugin and standalone Babel plugin use this function.
+ *
+ * @param node - JSX opening element to process.
+ * @param context - Tagging context with relative filename and attribute name.
+ * @param types - Babel types module.
+ * @returns true if attribute was added, false if skipped.
+ *
+ * @pure false (mutates node)
+ * @invariant each JSX element has at most one instance of the specified attribute after processing
+ * @complexity O(n) where n = number of existing attributes
+ */
+export declare const processJsxElement: (node: t.JSXOpeningElement, context: JsxTaggerContext, types: typeof t) => boolean;
+/**
+ * Creates a Babel visitor for JSX elements that uses the unified tagging logic.
+ *
+ * This is the shared visitor factory used by both:
+ * - Vite plugin (componentTagger) - passes relative filename directly
+ * - Standalone Babel plugin - computes relative filename from state
+ *
+ * @param getContext - Function to extract context from Babel state.
+ * @param types - Babel types module.
+ * @returns Babel visitor object for JSXOpeningElement.
+ *
+ * @pure true (returns immutable visitor object)
+ * @invariant visitor applies processJsxElement to all JSX opening elements
+ * @complexity O(1) for visitor creation
+ */
+export declare const createJsxTaggerVisitor: <TState>(getContext: (state: TState) => JsxTaggerContext | null, types: typeof t) => Visitor<TState>;

package/dist/core/jsx-tagger.js

@@ -0,0 +1,118 @@
+import { formatComponentPathValue } from "./component-path.js";
+/**
+ * Checks if a JSX attribute with the given name already exists on the element.
+ *
+ * @param node - JSX opening element to check.
+ * @param attrName - Name of the attribute to look for.
+ * @returns true if attribute exists, false otherwise.
+ *
+ * @pure true
+ * @invariant returns true iff attribute with exact name exists
+ * @complexity O(n) where n = number of attributes
+ */
+// CHANGE: extract attribute existence check as a pure utility.
+// WHY: enable reuse across Vite and Babel plugin implementations.
+// REF: issue-12 (unified interface request)
+// FORMAT THEOREM: ∀ node, name: attrExists(node, name) ↔ ∃ attr ∈ node.attributes: attr.name = name
+// PURITY: CORE
+// EFFECT: n/a
+// INVARIANT: predicate is deterministic for fixed inputs
+// COMPLEXITY: O(n)/O(1)
+export const attrExists = (node, attrName, types) => node.attributes.some((attr) => types.isJSXAttribute(attr) && types.isJSXIdentifier(attr.name, { name: attrName }));
+/**
+ * Creates a JSX attribute with the component path value.
+ *
+ * @param attributeName - Name of the attribute to create.
+ * @param relativeFilename - Relative path to the file.
+ * @param line - 1-based line number.
+ * @param column - 0-based column number.
+ * @param types - Babel types module.
+ * @returns JSX attribute node with the path value.
+ *
+ * @pure true
+ * @invariant attribute name matches the provided attributeName parameter
+ * @complexity O(1)
+ */
+// CHANGE: add attributeName parameter for configurable attribute names.
+// WHY: support customizable attribute names while maintaining default "data-path".
+// REF: issue-14 (add attributeName option)
+// FORMAT THEOREM: ∀ n, f, l, c: createPathAttribute(n, f, l, c) = JSXAttribute(n, f:l:c)
+// PURITY: CORE
+// EFFECT: n/a
+// INVARIANT: output format is always path:line:column with configurable attribute name
+// COMPLEXITY: O(1)/O(1)
+export const createPathAttribute = (attributeName, relativeFilename, line, column, types) => {
+    const value = formatComponentPathValue(relativeFilename, line, column);
+    return types.jsxAttribute(types.jsxIdentifier(attributeName), types.stringLiteral(value));
+};
+/**
+ * Processes a single JSX opening element and adds path attribute if needed.
+ *
+ * This is the unified business logic for tagging JSX elements with source location.
+ * Both the Vite plugin and standalone Babel plugin use this function.
+ *
+ * @param node - JSX opening element to process.
+ * @param context - Tagging context with relative filename and attribute name.
+ * @param types - Babel types module.
+ * @returns true if attribute was added, false if skipped.
+ *
+ * @pure false (mutates node)
+ * @invariant each JSX element has at most one instance of the specified attribute after processing
+ * @complexity O(n) where n = number of existing attributes
+ */
+// CHANGE: extract unified JSX element processing logic.
+// WHY: satisfy user request for single business logic shared by Vite and Babel.
+// QUOTE(TZ): "А ты можешь сделать что бы бизнес логика оставалось одной? Ну типо переиспользуй код с vite версии на babel"
+// REF: issue-12-comment (unified interface request)
+// FORMAT THEOREM: ∀ jsx ∈ JSXOpeningElement: processElement(jsx) → tagged(jsx) ∨ skipped(jsx)
+// PURITY: SHELL (mutates AST)
+// EFFECT: AST mutation
+// INVARIANT: idempotent - processing same element twice produces same result
+// COMPLEXITY: O(n)/O(1)
+export const processJsxElement = (node, context, types) => {
+    // Skip if no location info
+    if (node.loc === null || node.loc === undefined) {
+        return false;
+    }
+    // Skip if already has the specified attribute (idempotency)
+    if (attrExists(node, context.attributeName, types)) {
+        return false;
+    }
+    const { column, line } = node.loc.start;
+    const attr = createPathAttribute(context.attributeName, context.relativeFilename, line, column, types);
+    node.attributes.push(attr);
+    return true;
+};
+/**
+ * Creates a Babel visitor for JSX elements that uses the unified tagging logic.
+ *
+ * This is the shared visitor factory used by both:
+ * - Vite plugin (componentTagger) - passes relative filename directly
+ * - Standalone Babel plugin - computes relative filename from state
+ *
+ * @param getContext - Function to extract context from Babel state.
+ * @param types - Babel types module.
+ * @returns Babel visitor object for JSXOpeningElement.
+ *
+ * @pure true (returns immutable visitor object)
+ * @invariant visitor applies processJsxElement to all JSX opening elements
+ * @complexity O(1) for visitor creation
+ */
+// CHANGE: create shared visitor factory for both plugin types.
+// WHY: single unified interface as requested by user.
+// QUOTE(TZ): "Сделай единный интерфейс для этого"
+// REF: issue-12-comment (unified interface request)
+// FORMAT THEOREM: ∀ visitor = createVisitor(ctx): visitor processes all JSX elements uniformly
+// PURITY: CORE
+// EFFECT: n/a (visitor application has effects)
+// INVARIANT: visitor behavior is consistent across plugin implementations
+// COMPLEXITY: O(1)/O(1)
+export const createJsxTaggerVisitor = (getContext, types) => ({
+    JSXOpeningElement(nodePath, state) {
+        const context = getContext(state);
+        if (context === null) {
+            return;
+        }
+        processJsxElement(nodePath.node, context, types);
+    }
+});

package/dist/core/path-service.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Path service utilities using Effect-TS.
+ *
+ * PURITY: SHELL (uses Effect for file system operations)
+ * PURPOSE: Centralize Effect-based path operations to avoid code duplication.
+ */
+import { Path } from "@effect/platform/Path";
+import { Effect } from "effect";
+/**
+ * Computes relative path using Effect's Path service.
+ *
+ * @param rootDir - Root directory for relative path calculation.
+ * @param absolutePath - Absolute file path to convert.
+ * @returns Effect that produces relative path string.
+ *
+ * @pure false
+ * @effect Path service access
+ * @invariant result is a valid relative path
+ * @complexity O(n)/O(1) where n = path length
+ */
+export declare const relativeFromRoot: (rootDir: string, absolutePath: string) => Effect.Effect<string, never, Path>;
+/**
+ * Synchronously computes relative path using Effect's Path service.
+ *
+ * @param rootDir - Root directory for relative path calculation.
+ * @param absolutePath - Absolute file path to convert.
+ * @returns Relative path string.
+ *
+ * @pure false
+ * @effect Path service access (synchronous)
+ * @invariant result is a valid relative path
+ * @complexity O(n)/O(1) where n = path length
+ */
+export declare const computeRelativePath: (rootDir: string, absolutePath: string) => string;
+/**
+ * Re-export NodePathLayer for plugins that need to provide it explicitly.
+ */
+export { layer as NodePathLayer } from "@effect/platform-node/NodePath";

package/dist/core/path-service.js

@@ -0,0 +1,55 @@
+/**
+ * Path service utilities using Effect-TS.
+ *
+ * PURITY: SHELL (uses Effect for file system operations)
+ * PURPOSE: Centralize Effect-based path operations to avoid code duplication.
+ */
+import { layer as NodePathLayer } from "@effect/platform-node/NodePath";
+import { Path } from "@effect/platform/Path";
+import { Effect, pipe } from "effect";
+/**
+ * Computes relative path using Effect's Path service.
+ *
+ * @param rootDir - Root directory for relative path calculation.
+ * @param absolutePath - Absolute file path to convert.
+ * @returns Effect that produces relative path string.
+ *
+ * @pure false
+ * @effect Path service access
+ * @invariant result is a valid relative path
+ * @complexity O(n)/O(1) where n = path length
+ */
+// CHANGE: extract common path calculation logic from both plugins.
+// WHY: eliminate code duplication detected by vibecode-linter.
+// REF: lint error DUPLICATE #1
+// FORMAT THEOREM: ∀ (root, path): relativePath(root, path) = Path.relative(root, path)
+// PURITY: SHELL
+// EFFECT: Effect<string, never, Path>
+// INVARIANT: always returns a valid relative path for valid inputs
+// COMPLEXITY: O(n)/O(1)
+export const relativeFromRoot = (rootDir, absolutePath) => pipe(Path, Effect.map((pathService) => pathService.relative(rootDir, absolutePath)));
+/**
+ * Synchronously computes relative path using Effect's Path service.
+ *
+ * @param rootDir - Root directory for relative path calculation.
+ * @param absolutePath - Absolute file path to convert.
+ * @returns Relative path string.
+ *
+ * @pure false
+ * @effect Path service access (synchronous)
+ * @invariant result is a valid relative path
+ * @complexity O(n)/O(1) where n = path length
+ */
+// CHANGE: provide synchronous variant for Babel plugin (which requires sync operations).
+// WHY: Babel plugins must operate synchronously; Effect.runSync bridges Effect-style code.
+// REF: babel-plugin.ts:65-71
+// FORMAT THEOREM: ∀ (root, path): computeRelativePath(root, path) = runSync(relativePath(root, path))
+// PURITY: SHELL
+// EFFECT: Path service (executed synchronously)
+// INVARIANT: always returns a valid string for valid inputs
+// COMPLEXITY: O(n)/O(1)
+export const computeRelativePath = (rootDir, absolutePath) => pipe(relativeFromRoot(rootDir, absolutePath), Effect.provide(NodePathLayer), Effect.runSync);
+/**
+ * Re-export NodePathLayer for plugins that need to provide it explicitly.
+ */
+export { layer as NodePathLayer } from "@effect/platform-node/NodePath";

package/dist/index.d.ts

@@ -1,2 +1,4 @@
 export { componentPathAttributeName, formatComponentPathValue, isJsxFile } from "./core/component-path.js";
-export { componentTagger } from "./shell/component-tagger.js";
+export { attrExists, createJsxTaggerVisitor, createPathAttribute, type JsxTaggerContext, processJsxElement } from "./core/jsx-tagger.js";
+export { componentTaggerBabelPlugin, type ComponentTaggerBabelPluginOptions } from "./shell/babel-plugin.js";
+export { componentTagger, type ComponentTaggerOptions } from "./shell/component-tagger.js";

package/dist/index.js

@@ -9,4 +9,6 @@
 // INVARIANT: exports remain stable for consumers
 // COMPLEXITY: O(1)/O(1)
 export { componentPathAttributeName, formatComponentPathValue, isJsxFile } from "./core/component-path.js";
+export { attrExists, createJsxTaggerVisitor, createPathAttribute, processJsxElement } from "./core/jsx-tagger.js";
+export { componentTaggerBabelPlugin } from "./shell/babel-plugin.js";
 export { componentTagger } from "./shell/component-tagger.js";

package/dist/shell/babel-plugin.d.ts

@@ -0,0 +1,64 @@
+import { type PluginObj } from "@babel/core";
+/**
+ * Options for the component path Babel plugin.
+ */
+export type ComponentTaggerBabelPluginOptions = {
+    /**
+     * Root directory for computing relative paths.
+     * Defaults to process.cwd().
+     */
+    readonly rootDir?: string;
+    /**
+     * Name of the attribute to add to JSX elements.
+     * Defaults to "data-path".
+     */
+    readonly attributeName?: string;
+};
+type BabelState = {
+    readonly filename?: string;
+    readonly cwd?: string;
+    readonly opts?: ComponentTaggerBabelPluginOptions;
+};
+/**
+ * Creates a Babel plugin that injects component path attributes into JSX elements.
+ *
+ * This plugin is designed to be used standalone with build tools that support
+ * Babel plugins directly (e.g., Next.js via .babelrc).
+ *
+ * Uses the unified JSX tagger core that is shared with the Vite plugin,
+ * ensuring consistent behavior across both build tools.
+ *
+ * @returns Babel plugin object
+ *
+ * @pure false
+ * @effect Babel AST transformation
+ * @invariant JSX elements are tagged with path attribute containing file:line:column
+ * @complexity O(n) where n = number of JSX elements
+ *
+ * @example
+ * // .babelrc or babel.config.js
+ * {
+ *   "plugins": ["@prover-coder-ai/component-tagger/babel"]
+ * }
+ *
+ * @example
+ * // Next.js .babelrc with options
+ * {
+ *   "presets": ["next/babel"],
+ *   "env": {
+ *     "development": {
+ *       "plugins": [
+ *         ["@prover-coder-ai/component-tagger/babel", { "rootDir": "/custom/root" }]
+ *       ]
+ *     }
+ *   }
+ * }
+ */
+export declare const componentTaggerBabelPlugin: () => PluginObj<BabelState>;
+/**
+ * Default export for Babel plugin resolution.
+ *
+ * Babel resolves plugins by looking for a default export function that
+ * returns a plugin object when called.
+ */
+export default componentTaggerBabelPlugin;

package/dist/shell/babel-plugin.js

@@ -0,0 +1,103 @@
+import { types as t } from "@babel/core";
+import { componentPathAttributeName, isJsxFile } from "../core/component-path.js";
+import { createJsxTaggerVisitor } from "../core/jsx-tagger.js";
+import { computeRelativePath } from "../core/path-service.js";
+/**
+ * Creates context for JSX tagging from Babel state.
+ *
+ * @param state - Babel plugin state containing filename and options.
+ * @returns JsxTaggerContext or null if context cannot be created.
+ *
+ * @pure true
+ * @invariant returns null when filename is undefined or not a JSX file
+ * @complexity O(n) where n = path length
+ */
+// CHANGE: add support for configurable attributeName from options.
+// WHY: enable unified visitor to work with Babel state and custom attribute names.
+// QUOTE(issue-14): "Add option attributeName (default: data-path) for both plugins"
+// REF: issue-14
+// FORMAT THEOREM: ∀ state: getContext(state) = context ↔ isValidState(state)
+// PURITY: CORE
+// EFFECT: n/a
+// INVARIANT: context contains valid relative path and attribute name
+// COMPLEXITY: O(n)/O(1)
+const getContextFromState = (state) => {
+    const filename = state.filename;
+    // Skip if no filename
+    if (filename === undefined) {
+        return null;
+    }
+    // Skip if not a JSX/TSX file
+    if (!isJsxFile(filename)) {
+        return null;
+    }
+    // Compute relative path from root using Effect's Path service
+    const rootDir = state.opts?.rootDir ?? state.cwd ?? process.cwd();
+    const relativeFilename = computeRelativePath(rootDir, filename);
+    const attributeName = state.opts?.attributeName ?? componentPathAttributeName;
+    return { relativeFilename, attributeName };
+};
+/**
+ * Creates a Babel plugin that injects component path attributes into JSX elements.
+ *
+ * This plugin is designed to be used standalone with build tools that support
+ * Babel plugins directly (e.g., Next.js via .babelrc).
+ *
+ * Uses the unified JSX tagger core that is shared with the Vite plugin,
+ * ensuring consistent behavior across both build tools.
+ *
+ * @returns Babel plugin object
+ *
+ * @pure false
+ * @effect Babel AST transformation
+ * @invariant JSX elements are tagged with path attribute containing file:line:column
+ * @complexity O(n) where n = number of JSX elements
+ *
+ * @example
+ * // .babelrc or babel.config.js
+ * {
+ *   "plugins": ["@prover-coder-ai/component-tagger/babel"]
+ * }
+ *
+ * @example
+ * // Next.js .babelrc with options
+ * {
+ *   "presets": ["next/babel"],
+ *   "env": {
+ *     "development": {
+ *       "plugins": [
+ *         ["@prover-coder-ai/component-tagger/babel", { "rootDir": "/custom/root" }]
+ *       ]
+ *     }
+ *   }
+ * }
+ */
+// CHANGE: use unified JSX tagger visitor from core module.
+// WHY: share business logic between Vite and Babel plugins as requested.
+// QUOTE(TZ): "А ты можешь сделать что бы бизнес логика оставалось одной? Ну типо переиспользуй код с vite версии на babel. Сделай единный интерфейс для этого"
+// REF: issue-12-comment (unified interface request)
+// SOURCE: https://babeljs.io/docs/plugins
+// FORMAT THEOREM: forall jsx in JSXOpeningElement: transform(jsx) -> tagged(jsx, path)
+// PURITY: SHELL
+// EFFECT: Babel AST mutation
+// INVARIANT: each JSX opening element has at most one path attribute
+// COMPLEXITY: O(n)/O(1)
+export const componentTaggerBabelPlugin = () => ({
+    name: "component-path-babel-tagger",
+    visitor: createJsxTaggerVisitor(getContextFromState, t)
+});
+/**
+ * Default export for Babel plugin resolution.
+ *
+ * Babel resolves plugins by looking for a default export function that
+ * returns a plugin object when called.
+ */
+// CHANGE: provide default export for standard Babel plugin resolution.
+// WHY: Babel expects plugins to be functions that return plugin objects.
+// REF: issue-12
+// FORMAT THEOREM: forall babel: require(plugin) -> callable -> PluginObj
+// PURITY: SHELL
+// EFFECT: n/a
+// INVARIANT: default export matches Babel plugin signature
+// COMPLEXITY: O(1)/O(1)
+export default componentTaggerBabelPlugin;

package/dist/shell/component-tagger.d.ts

@@ -1,7 +1,18 @@
 import type { PluginOption } from "vite";
+/**
+ * Options for the component tagger Vite plugin.
+ */
+export type ComponentTaggerOptions = {
+    /**
+     * Name of the attribute to add to JSX elements.
+     * Defaults to "data-path".
+     */
+    readonly attributeName?: string;
+};
 /**
  * Creates a Vite plugin that injects a single component-path data attribute.
  *
+ * @param options - Configuration options for the plugin.
  * @returns Vite PluginOption for pre-transform tagging.
  *
  * @pure false
@@ -10,4 +21,4 @@ import type { PluginOption } from "vite";
  * @complexity O(n) time / O(1) space per JSX module
  * @throws Never - errors are typed and surfaced by Effect
  */
-export declare const componentTagger: () => PluginOption;
+export declare const componentTagger: (options?: ComponentTaggerOptions) => PluginOption;

package/dist/shell/component-tagger.js

@@ -1,8 +1,8 @@
 import { transformAsync, types as t } from "@babel/core";
-import { layer as NodePathLayer } from "@effect/platform-node/NodePath";
-import { Path } from "@effect/platform/Path";
 import { Effect, pipe } from "effect";
-import { componentPathAttributeName, formatComponentPathValue, isJsxFile } from "../core/component-path.js";
+import { componentPathAttributeName, isJsxFile } from "../core/component-path.js";
+import { createJsxTaggerVisitor } from "../core/jsx-tagger.js";
+import { NodePathLayer, relativeFromRoot } from "../core/path-service.js";
 class ComponentTaggerError extends Error {
     cause;
     _tag = "ComponentTaggerError";
@@ -15,18 +15,6 @@ const stripQuery = (id) => {
     const queryIndex = id.indexOf("?");
     return queryIndex === -1 ? id : id.slice(0, queryIndex);
 };
-// CHANGE: compute relative paths from the resolved Vite root instead of process.cwd().
-// WHY: keep component paths stable across monorepos and custom Vite roots.
-// QUOTE(TZ): "Сам компонент должен быть в текущем app но вот что бы его протестировать надо создать ещё один проект который наш текущий апп будет подключать"
-// REF: user-2026-01-14-frontend-consumer
-// SOURCE: n/a
-// FORMAT THEOREM: forall p in Path: relative(root, p) = r -> resolve(root, r) = p
-// PURITY: SHELL
-// EFFECT: Effect<string, never, Path>
-// INVARIANT: output is deterministic for a fixed root
-// COMPLEXITY: O(n)/O(1)
-const relativeFromRoot = (rootDir, absolutePath) => pipe(Path, Effect.map((pathService) => pathService.relative(rootDir, absolutePath)));
-const attrExists = (node, attrName) => node.attributes.some((attr) => t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name, { name: attrName }));
 const toViteResult = (result) => {
     if (result === null || result.code === null || result.code === undefined) {
         return null;
@@ -37,33 +25,13 @@ const toViteResult = (result) => {
         map: result.map ?? null
     };
 };
-// CHANGE: inject a single path attribute into JSX opening elements.
-// WHY: remove redundant metadata while preserving the full source location payload.
-// QUOTE(TZ): "\u0421\u0430\u043c \u043a\u043e\u043c\u043f\u043e\u043d\u0435\u043d\u0442 \u0434\u043e\u043b\u0436\u0435\u043d \u0431\u044b\u0442\u044c \u0432 \u0442\u0435\u043a\u0443\u0449\u0435\u043c app \u043d\u043e \u0432\u043e\u0442 \u0447\u0442\u043e \u0431\u044b \u0435\u0433\u043e \u043f\u0440\u043e\u0442\u0435\u0441\u0442\u0438\u0440\u043e\u0432\u0430\u0442\u044c \u043d\u0430\u0434\u043e \u0441\u043e\u0437\u0434\u0430\u0442\u044c \u0435\u0449\u0451 \u043e\u0434\u0438\u043d \u043f\u0440\u043e\u0435\u043a\u0442 \u043a\u043e\u0442\u043e\u0440\u044b\u0439 \u043d\u0430\u0448 \u0442\u0435\u043a\u0443\u0449\u0438\u0439 \u0430\u043f\u043f \u0431\u0443\u0434\u0435\u0442 \u043f\u043e\u0434\u043a\u043b\u044e\u0447\u0430\u0442\u044c"
-// REF: user-2026-01-14-frontend-consumer
-// SOURCE: n/a
-// FORMAT THEOREM: forall f in JSXOpeningElement: rendered(f) -> annotated(f)
-// PURITY: SHELL
-// EFFECT: Effect<ViteTransformResult | null, ComponentTaggerError, Path>
-// INVARIANT: each JSX opening element has at most one path attribute
-// COMPLEXITY: O(n)/O(1), n = number of JSX elements
-const makeBabelTagger = (relativeFilename) => ({
-    name: "component-path-babel-tagger",
-    visitor: {
-        JSXOpeningElement(openPath) {
-            const { node } = openPath;
-            if (node.loc === null || node.loc === undefined) {
-                return;
-            }
-            if (attrExists(node, componentPathAttributeName)) {
-                return;
-            }
-            const { column, line } = node.loc.start;
-            const value = formatComponentPathValue(relativeFilename, line, column);
-            node.attributes.push(t.jsxAttribute(t.jsxIdentifier(componentPathAttributeName), t.stringLiteral(value)));
-        }
-    }
-});
+const makeBabelTagger = (relativeFilename, attributeName) => {
+    const context = { relativeFilename, attributeName };
+    return {
+        name: "component-path-babel-tagger",
+        visitor: createJsxTaggerVisitor(() => context, t)
+    };
+};
 /**
  * Builds a Vite transform result with a single component-path attribute per JSX element.
  *
@@ -78,7 +46,7 @@ const makeBabelTagger = (relativeFilename) => ({
  */
 // CHANGE: wrap Babel transform in Effect for typed errors and controlled effects.
 // WHY: satisfy the shell-only effect boundary while avoiding async/await.
-// QUOTE(TZ): "\u0421\u0430\u043c \u043a\u043e\u043c\u043f\u043e\u043d\u0435\u043d\u0442 \u0434\u043e\u043b\u0436\u0435\u043d \u0431\u044b\u0442\u044c \u0432 \u0442\u0435\u043a\u0443\u0449\u0435\u043c app \u043d\u043e \u0432\u043e\u0442 \u0447\u0442\u043e \u0431\u044b \u0435\u0433\u043e \u043f\u0440\u043e\u0442\u0435\u0441\u0442\u0438\u0440\u043e\u0432\u0430\u0442\u044c \u043d\u0430\u0434\u043e \u0441\u043e\u0437\u0434\u0430\u0442\u044c \u0435\u0449\u0451 \u043e\u0434\u0438\u043d \u043f\u0440\u043e\u0435\u043a\u0442 \u043a\u043e\u0442\u043e\u0440\u044b\u0439 \u043d\u0430\u0448 \u0442\u0435\u043a\u0443\u0449\u0438\u0439 \u0430\u043f\u043f \u0431\u0443\u0434\u0435\u0442 \u043f\u043e\u0434\u043a\u043b\u044e\u0447\u0430\u0442\u044c"
+// QUOTE(TZ): "Сам компонент должен быть в текущем app но вот что бы его протестировать надо создать ещё один проект который наш текущий апп будет подключать"
 // REF: user-2026-01-14-frontend-consumer
 // SOURCE: n/a
 // FORMAT THEOREM: forall c in Code: transform(c) = r -> r is tagged or null
@@ -86,7 +54,7 @@ const makeBabelTagger = (relativeFilename) => ({
 // EFFECT: Effect<ViteTransformResult | null, ComponentTaggerError, never>
 // INVARIANT: errors are surfaced as ComponentTaggerError only
 // COMPLEXITY: O(n)/O(1)
-const runTransform = (code, id, rootDir) => {
+const runTransform = (code, id, rootDir, attributeName) => {
     const cleanId = stripQuery(id);
     return pipe(relativeFromRoot(rootDir, cleanId), Effect.flatMap((relative) => Effect.tryPromise({
         try: () => transformAsync(code, {
@@ -97,7 +65,7 @@ const runTransform = (code, id, rootDir) => {
                 sourceType: "module",
                 plugins: ["typescript", "jsx", "decorators-legacy"]
             },
-            plugins: [makeBabelTagger(relative)],
+            plugins: [makeBabelTagger(relative, attributeName)],
             sourceMaps: true
         }),
         catch: (cause) => {
@@ -109,6 +77,7 @@ const runTransform = (code, id, rootDir) => {
 /**
  * Creates a Vite plugin that injects a single component-path data attribute.
  *
+ * @param options - Configuration options for the plugin.
  * @returns Vite PluginOption for pre-transform tagging.
  *
  * @pure false
@@ -117,17 +86,18 @@ const runTransform = (code, id, rootDir) => {
  * @complexity O(n) time / O(1) space per JSX module
  * @throws Never - errors are typed and surfaced by Effect
  */
-// CHANGE: expose a Vite plugin that tags JSX with only path.
-// WHY: reduce attribute noise while keeping full path metadata.
-// QUOTE(TZ): "\u0421\u0430\u043c \u043a\u043e\u043c\u043f\u043e\u043d\u0435\u043d\u0442 \u0434\u043e\u043b\u0436\u0435\u043d \u0431\u044b\u0442\u044c \u0432 \u0442\u0435\u043a\u0443\u0449\u0435\u043c app \u043d\u043e \u0432\u043e\u0442 \u0447\u0442\u043e \u0431\u044b \u0435\u0433\u043e \u043f\u0440\u043e\u0442\u0435\u0441\u0442\u0438\u0440\u043e\u0432\u0430\u0442\u044c \u043d\u0430\u0434\u043e \u0441\u043e\u0437\u0434\u0430\u0442\u044c \u0435\u0449\u0451 \u043e\u0434\u0438\u043d \u043f\u0440\u043e\u0435\u043a\u0442 \u043a\u043e\u0442\u043e\u0440\u044b\u0439 \u043d\u0430\u0448 \u0442\u0435\u043a\u0443\u0449\u0438\u0439 \u0430\u043f\u043f \u0431\u0443\u0434\u0435\u0442 \u043f\u043e\u0434\u043a\u043b\u044e\u0447\u0430\u0442\u044c"
-// REF: user-2026-01-14-frontend-consumer
+// CHANGE: add attributeName option with default "data-path".
+// WHY: support customizable attribute names while maintaining backwards compatibility.
+// QUOTE(issue-14): "Add option attributeName (default: data-path) for both plugins"
+// REF: issue-14
 // SOURCE: n/a
-// FORMAT THEOREM: forall id: isJsxFile(id) -> transform(id) adds component-path
+// FORMAT THEOREM: forall id: isJsxFile(id) -> transform(id) adds specified attribute
 // PURITY: SHELL
 // EFFECT: Effect<ViteTransformResult | null, ComponentTaggerError, never>
-// INVARIANT: no duplicate path attributes
+// INVARIANT: no duplicate attributes with the same name
 // COMPLEXITY: O(n)/O(1)
-export const componentTagger = () => {
+export const componentTagger = (options) => {
+    const attributeName = options?.attributeName ?? componentPathAttributeName;
     let resolvedRoot = process.cwd();
     return {
         name: "component-path-tagger",
@@ -140,7 +110,7 @@ export const componentTagger = () => {
             if (!isJsxFile(id)) {
                 return null;
             }
-            return Effect.runPromise(pipe(runTransform(code, id, resolvedRoot), Effect.provide(NodePathLayer)));
+            return Effect.runPromise(pipe(runTransform(code, id, resolvedRoot, attributeName), Effect.provide(NodePathLayer)));
         }
     };
 };

package/package.json

@@ -1,11 +1,23 @@
 {
   "name": "@prover-coder-ai/component-tagger",
-  "version": "1.0.22",
-  "description": "Component tagger Vite plugin for JSX metadata",
+  "version": "1.0.25",
+  "description": "Component tagger Vite plugin and Babel plugin for JSX metadata",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./babel": {
+      "types": "./dist/shell/babel-plugin.d.ts",
+      "require": "./babel.cjs",
+      "import": "./dist/shell/babel-plugin.js"
+    }
+  },
   "files": [
-    "dist"
+    "dist",
+    "babel.cjs"
   ],
   "directories": {
     "doc": "doc"
@@ -17,6 +29,8 @@
   "keywords": [
     "effect",
     "vite",
+    "babel",
+    "nextjs",
     "plugin",
     "tagger"
   ],