@prover-coder-ai/component-tagger 1.0.24 → 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

@@ -11,9 +11,9 @@
  *   "plugins": ["@prover-coder-ai/component-tagger/babel"]
  * }
  */
-// CHANGE: provide CommonJS entry point for Babel plugin.
-// WHY: Babel configuration often requires CommonJS modules.
-// REF: issue-12
+// 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
@@ -22,7 +22,7 @@
 
 const path = require("node:path")
 
-const componentPathAttributeName = "path"
+const componentPathAttributeName = "data-path"
 const jsxFilePattern = /\.(tsx|jsx)(\?.*)?$/u
 
 const isJsxFile = (id) => jsxFilePattern.test(id)
@@ -58,21 +58,22 @@ module.exports = function componentTaggerBabelPlugin({ types: t }) {
           return
         }
 
-        // Skip if already has path attribute
-        if (attrExists(node, componentPathAttributeName, t)) {
-          return
-        }
-
-        // Compute relative path from root
+        // 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(componentPathAttributeName), t.stringLiteral(value))
+          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

@@ -9,6 +9,10 @@ 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.
@@ -25,6 +29,7 @@ export declare const attrExists: (node: t.JSXOpeningElement, attrName: string, t
 /**
  * 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.
@@ -32,10 +37,10 @@ export declare const attrExists: (node: t.JSXOpeningElement, attrName: string, t
  * @returns JSX attribute node with the path value.
  *
  * @pure true
- * @invariant attribute name is always componentPathAttributeName
+ * @invariant attribute name matches the provided attributeName parameter
  * @complexity O(1)
  */
-export declare const createPathAttribute: (relativeFilename: string, line: number, column: number, types: typeof t) => t.JSXAttribute;
+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.
  *
@@ -43,12 +48,12 @@ export declare const createPathAttribute: (relativeFilename: string, line: numbe
  * 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.
+ * @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 path attribute after processing
+ * @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;

package/dist/core/jsx-tagger.js

@@ -1,4 +1,4 @@
-import { componentPathAttributeName, formatComponentPathValue } from "./component-path.js";
+import { formatComponentPathValue } from "./component-path.js";
 /**
  * Checks if a JSX attribute with the given name already exists on the element.
  *
@@ -22,6 +22,7 @@ export const attrExists = (node, attrName, types) => node.attributes.some((attr)
 /**
  * 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.
@@ -29,20 +30,20 @@ export const attrExists = (node, attrName, types) => node.attributes.some((attr)
  * @returns JSX attribute node with the path value.
  *
  * @pure true
- * @invariant attribute name is always componentPathAttributeName
+ * @invariant attribute name matches the provided attributeName parameter
  * @complexity O(1)
  */
-// CHANGE: extract attribute creation as a pure factory.
-// WHY: single point for attribute creation ensures consistency.
-// REF: issue-12 (unified interface request)
-// FORMAT THEOREM: ∀ f, l, c: createPathAttribute(f, l, c) = JSXAttribute(path, f:l:c)
+// 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
+// INVARIANT: output format is always path:line:column with configurable attribute name
 // COMPLEXITY: O(1)/O(1)
-export const createPathAttribute = (relativeFilename, line, column, types) => {
+export const createPathAttribute = (attributeName, relativeFilename, line, column, types) => {
     const value = formatComponentPathValue(relativeFilename, line, column);
-    return types.jsxAttribute(types.jsxIdentifier(componentPathAttributeName), types.stringLiteral(value));
+    return types.jsxAttribute(types.jsxIdentifier(attributeName), types.stringLiteral(value));
 };
 /**
  * Processes a single JSX opening element and adds path attribute if needed.
@@ -51,12 +52,12 @@ export const createPathAttribute = (relativeFilename, line, column, types) => {
  * 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.
+ * @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 path attribute after processing
+ * @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.
@@ -73,12 +74,12 @@ export const processJsxElement = (node, context, types) => {
     if (node.loc === null || node.loc === undefined) {
         return false;
     }
-    // Skip if already has path attribute (idempotency)
-    if (attrExists(node, componentPathAttributeName, types)) {
+    // 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.relativeFilename, line, column, types);
+    const attr = createPathAttribute(context.attributeName, context.relativeFilename, line, column, types);
     node.attributes.push(attr);
     return true;
 };

package/dist/index.d.ts

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

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

@@ -8,6 +8,11 @@ export type ComponentTaggerBabelPluginOptions = {
      * 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;

package/dist/shell/babel-plugin.js

@@ -1,5 +1,5 @@
 import { types as t } from "@babel/core";
-import { isJsxFile } from "../core/component-path.js";
+import { componentPathAttributeName, isJsxFile } from "../core/component-path.js";
 import { createJsxTaggerVisitor } from "../core/jsx-tagger.js";
 import { computeRelativePath } from "../core/path-service.js";
 /**
@@ -12,14 +12,14 @@ import { computeRelativePath } from "../core/path-service.js";
  * @invariant returns null when filename is undefined or not a JSX file
  * @complexity O(n) where n = path length
  */
-// CHANGE: extract context creation for standalone Babel plugin.
-// WHY: enable unified visitor to work with Babel state.
-// QUOTE(TZ): "А ты можешь сделать что бы бизнес логика оставалось одной?"
-// REF: issue-12-comment (unified interface request)
+// 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
+// INVARIANT: context contains valid relative path and attribute name
 // COMPLEXITY: O(n)/O(1)
 const getContextFromState = (state) => {
     const filename = state.filename;
@@ -32,9 +32,10 @@ const getContextFromState = (state) => {
         return null;
     }
     // Compute relative path from root using Effect's Path service
-    const rootDir = state.opts?.rootDir ?? state.cwd ?? "";
+    const rootDir = state.opts?.rootDir ?? state.cwd ?? process.cwd();
     const relativeFilename = computeRelativePath(rootDir, filename);
-    return { relativeFilename };
+    const attributeName = state.opts?.attributeName ?? componentPathAttributeName;
+    return { relativeFilename, attributeName };
 };
 /**
  * Creates a Babel plugin that injects component path attributes into JSX elements.

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,6 +1,6 @@
 import { transformAsync, types as t } from "@babel/core";
 import { Effect, pipe } from "effect";
-import { 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 {
@@ -25,8 +25,8 @@ const toViteResult = (result) => {
         map: result.map ?? null
     };
 };
-const makeBabelTagger = (relativeFilename) => {
-    const context = { relativeFilename };
+const makeBabelTagger = (relativeFilename, attributeName) => {
+    const context = { relativeFilename, attributeName };
     return {
         name: "component-path-babel-tagger",
         visitor: createJsxTaggerVisitor(() => context, t)
@@ -54,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, {
@@ -65,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) => {
@@ -77,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
@@ -85,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): "Сам компонент должен быть в текущем app но вот что бы его протестировать надо создать ещё один проект который наш текущий апп будет подключать"
-// 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",
@@ -108,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,6 +1,6 @@
 {
   "name": "@prover-coder-ai/component-tagger",
-  "version": "1.0.24",
+  "version": "1.0.25",
   "description": "Component tagger Vite plugin and Babel plugin for JSX metadata",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",