Merge pull request #13 from konard/issue-12-13dbad4c3a6a

feat(app): export standalone Babel plugin for Next.js integration

Author: skulidropek

.github/workflows/check.yml

@@ -72,3 +72,23 @@ jobs:
       - name: Install dependencies
         uses: ./.github/actions/setup
       - run: pnpm lint:effect
+
+  e2e-nextjs:
+    name: E2E Next.js
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install dependencies
+        uses: ./.github/actions/setup
+      - name: Install Playwright browsers
+        run: pnpm --filter frontend-nextjs exec playwright install --with-deps chromium
+      - name: Run Next.js E2E tests
+        run: pnpm --filter frontend-nextjs test:e2e
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: nextjs-e2e-results
+          path: packages/frontend-nextjs/test-results/
+          retention-days: 7

packages/app/babel.cjs

@@ -0,0 +1,80 @@
+/**
+ * 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.
+// WHY: Babel configuration often requires CommonJS modules.
+// REF: issue-12
+// 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 = "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
+        }
+
+        // Skip if already has path attribute
+        if (attrExists(node, componentPathAttributeName, t)) {
+          return
+        }
+
+        // Compute relative path from root
+        const opts = state.opts || {}
+        const rootDir = opts.rootDir || state.cwd || process.cwd()
+        const relativeFilename = path.relative(rootDir, filename)
+
+        const { column, line } = node.loc.start
+        const value = formatComponentPathValue(relativeFilename, line, column)
+
+        node.attributes.push(
+          t.jsxAttribute(t.jsxIdentifier(componentPathAttributeName), t.stringLiteral(value))
+        )
+      }
+    }
+  }
+}

packages/app/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.23",
+  "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"
@@ -31,6 +43,8 @@
   "keywords": [
     "effect",
     "vite",
+    "babel",
+    "nextjs",
     "plugin",
     "tagger"
   ],

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

@@ -0,0 +1,153 @@
+import type { types as t, Visitor } from "@babel/core"
+
+import { componentPathAttributeName, formatComponentPathValue } from "./component-path.js"
+
+/**
+ * Context required for JSX tagging.
+ *
+ * @pure true
+ */
+export type JsxTaggerContext = {
+  /**
+   * Relative file path from the project root.
+   */
+  readonly relativeFilename: 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
+ */
+// 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: t.JSXOpeningElement, attrName: string, types: typeof t): boolean =>
+  node.attributes.some(
+    (attr) => types.isJSXAttribute(attr) && types.isJSXIdentifier(attr.name, { name: attrName })
+  )
+
+/**
+ * Creates a JSX attribute with the component path value.
+ *
+ * @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
+ * @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)
+// PURITY: CORE
+// EFFECT: n/a
+// INVARIANT: output format is always path:line:column
+// COMPLEXITY: O(1)/O(1)
+export const createPathAttribute = (
+  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))
+}
+
+/**
+ * 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.
+ * @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
+ * @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: t.JSXOpeningElement,
+  context: JsxTaggerContext,
+  types: typeof t
+): boolean => {
+  // Skip if no location info
+  if (node.loc === null || node.loc === undefined) {
+    return false
+  }
+
+  // Skip if already has path attribute (idempotency)
+  if (attrExists(node, componentPathAttributeName, types)) {
+    return false
+  }
+
+  const { column, line } = node.loc.start
+  const attr = createPathAttribute(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 = <TState>(
+  getContext: (state: TState) => JsxTaggerContext | null,
+  types: typeof t
+): Visitor<TState> => ({
+  JSXOpeningElement(nodePath, state) {
+    const context = getContext(state)
+    if (context === null) {
+      return
+    }
+    processJsxElement(nodePath.node, context, types)
+  }
+})

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

@@ -0,0 +1,68 @@
+/**
+ * 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: string,
+  absolutePath: string
+): Effect.Effect<string, never, Path> =>
+  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: string, absolutePath: string): string =>
+  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"

packages/app/src/index.ts

@@ -9,4 +9,12 @@
 // INVARIANT: exports remain stable for consumers
 // COMPLEXITY: O(1)/O(1)
 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"