Merge branch 'main' into issue-18-fe8f089190c9

Resolved conflicts:
- packages/app/src/core/component-path.ts: kept both normalizeModuleId function and updated data-path attribute comment
- packages/app/src/shell/component-tagger.ts: merged imports to include both normalizeModuleId and componentPathAttributeName

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: konard

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

packages/app/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))
         )
       }
     }

packages/app/src/core/component-path.ts

@@ -29,17 +29,17 @@ export const normalizeModuleId = (id: string): string => {
   return queryIndex === -1 ? id : id.slice(0, queryIndex)
 }
 
-// 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.
@@ -53,7 +53,7 @@ export const componentPathAttributeName = "path"
  */
 // CHANGE: centralize JSX file detection as a pure predicate.
 // WHY: keep file filtering in the functional core for testability.
-// 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 id in ModuleId: isJsxFile(id) -> matches(id, jsxFilePattern)
@@ -77,7 +77,7 @@ export const isJsxFile = (id: string): boolean => jsxFilePattern.test(id)
  */
 // CHANGE: provide a pure formatter for component location payloads.
 // WHY: reuse a single, deterministic encoding for UI 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"
+// QUOTE(TZ): "Сам компонент должен быть в текущем app но вот что бы его протестировать надо создать ещё один проект который наш текущий апп будет подключать"
 // REF: user-2026-01-14-frontend-consumer
 // SOURCE: n/a
 // FORMAT THEOREM: forall p,l,c: formatComponentPathValue(p,l,c) = concat(p, ":", l, ":", c)

packages/app/src/core/jsx-tagger.ts

@@ -1,6 +1,6 @@
 import type { types as t, Visitor } from "@babel/core"
 
-import { componentPathAttributeName, formatComponentPathValue } from "./component-path.js"
+import { formatComponentPathValue } from "./component-path.js"
 
 /**
  * Context required for JSX tagging.
@@ -12,6 +12,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
 }
 
 /**
@@ -41,32 +45,34 @@ export const attrExists = (node: t.JSXOpeningElement, attrName: string, types: 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.
  * @param types - Babel types module.
  * @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 = (
+  attributeName: string,
   relativeFilename: string,
   line: number,
   column: number,
   types: typeof t
 ): t.JSXAttribute => {
   const value = formatComponentPathValue(relativeFilename, line, column)
-  return types.jsxAttribute(types.jsxIdentifier(componentPathAttributeName), types.stringLiteral(value))
+  return types.jsxAttribute(types.jsxIdentifier(attributeName), types.stringLiteral(value))
 }
 
 /**
@@ -76,12 +82,12 @@ export const createPathAttribute = (
  * 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.
@@ -103,13 +109,13 @@ export const processJsxElement = (
     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

packages/app/src/index.ts

@@ -22,4 +22,4 @@ export {
   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"

packages/app/src/shell/babel-plugin.ts

@@ -1,6 +1,6 @@
 import { type PluginObj, types as t } from "@babel/core"
 
-import { isJsxFile } from "../core/component-path.js"
+import { componentPathAttributeName, isJsxFile } from "../core/component-path.js"
 import { createJsxTaggerVisitor, type JsxTaggerContext } from "../core/jsx-tagger.js"
 import { computeRelativePath } from "../core/path-service.js"
 
@@ -13,6 +13,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 = {
@@ -31,14 +36,14 @@ type BabelState = {
  * @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: BabelState): JsxTaggerContext | null => {
   const filename = state.filename
@@ -54,10 +59,11 @@ const getContextFromState = (state: BabelState): JsxTaggerContext | 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)
+  const attributeName = state.opts?.attributeName ?? componentPathAttributeName
 
-  return { relativeFilename }
+  return { relativeFilename, attributeName }
 }
 
 /**