Merge branch 'main' into issue-19-793570d5e6b2

Resolved conflicts by combining changes:
- Kept babelPluginName constant from issue-19
- Accepted attribute rename from "path" to "data-path" from main
- Accepted normalizeModuleId function from main
- Accepted configurable attributeName option from main
- Removed ViteBabelState type as it's not used (issue-19 goal)

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/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @prover-coder-ai/component-tagger
 
+## 1.0.25
+
+### Patch Changes
+
+- chore: automated version bump
+
 ## 1.0.24
 
 ### Patch Changes

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
@@ -23,7 +23,7 @@
 const path = require("node:path")
 
 const babelPluginName = "component-path-babel-tagger"
-const componentPathAttributeName = "path"
+const componentPathAttributeName = "data-path"
 const jsxFilePattern = /\.(tsx|jsx)(\?.*)?$/u
 
 const isJsxFile = (id) => jsxFilePattern.test(id)
@@ -59,21 +59,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/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",

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

@@ -12,17 +12,46 @@ const jsxFilePattern = /\.(tsx|jsx)(\?.*)?$/u
 // COMPLEXITY: O(1)/O(1)
 export const babelPluginName = "component-path-babel-tagger"
 
-// 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
+/**
+ * Normalizes a module ID by stripping query parameters.
+ *
+ * Vite and other bundlers may append query parameters to module IDs
+ * (e.g., "src/App.tsx?import" or "src/App.tsx?v=123"). This function
+ * returns the clean file path without query string.
+ *
+ * @param id - Module ID (may include query parameters).
+ * @returns Clean path without query string.
+ *
+ * @pure true
+ * @invariant ∀ id: normalizeModuleId(id) does not contain '?'
+ * @complexity O(n) time / O(1) space where n = |id|
+ */
+// CHANGE: centralize query stripping as a pure function in core.
+// WHY: unify module ID normalization in one place as requested in issue #18.
+// QUOTE(ТЗ): "Вынести stripQuery() (или normalizeModuleId()) в core, использовать в Vite и (при желании) в isJsxFile."
+// REF: REQ-18 (issue #18)
 // SOURCE: n/a
-// FORMAT THEOREM: forall a in AttributeName: a = "path"
+// FORMAT THEOREM: ∀ id: normalizeModuleId(id) = id.split('?')[0]
+// PURITY: CORE
+// EFFECT: n/a
+// INVARIANT: result contains no query string
+// COMPLEXITY: O(n)/O(1)
+export const normalizeModuleId = (id: string): string => {
+  const queryIndex = id.indexOf("?")
+  return queryIndex === -1 ? id : id.slice(0, queryIndex)
+}
+
+// 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.
@@ -36,7 +65,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)
@@ -60,7 +89,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

@@ -8,7 +8,12 @@
 // EFFECT: n/a
 // INVARIANT: exports remain stable for consumers
 // COMPLEXITY: O(1)/O(1)
-export { componentPathAttributeName, formatComponentPathValue, isJsxFile } from "./core/component-path.js"
+export {
+  componentPathAttributeName,
+  formatComponentPathValue,
+  isJsxFile,
+  normalizeModuleId
+} from "./core/component-path.js"
 export {
   attrExists,
   createJsxTaggerVisitor,
@@ -17,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"