macaly-tagger 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 macaly-tagger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,220 @@
+# Macaly Tagger
+
+A webpack loader that adds location metadata to JSX elements for development debugging. This loader automatically injects `data-macaly-loc` and `data-macaly-name` attributes into your JSX elements, making it easy to trace elements back to their source code location.
+
+## Features
+
+- 🎯 **Precise location tracking**: Shows exact file, line, and column for each JSX element
+- 🚀 **Zero runtime overhead**: Only runs in development mode
+- 🔧 **Easy integration**: Simple webpack configuration
+- 📦 **TypeScript support**: Works with both `.jsx` and `.tsx` files
+- 🚫 **Smart filtering**: Automatically excludes `node_modules`
+
+## Installation
+
+```bash
+npm install --save-dev macaly-tagger
+```
+
+The loader has the following dependencies that will be installed automatically:
+
+- `@babel/parser`
+- `magic-string`
+- `estree-walker`
+
+## Usage
+
+### Next.js Setup
+
+Configure your `next.config.js`:
+
+```js
+const path = require("path");
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  webpack: (config, { dev, isServer }) => {
+    // Only apply in development
+    if (dev) {
+      config.module.rules.unshift({
+        test: /\.(jsx|tsx)$/,
+        exclude: /node_modules/,
+        use: [
+          {
+            loader: "macaly-tagger",
+          },
+        ],
+        enforce: "pre", // Run before other loaders
+      });
+    }
+
+    return config;
+  },
+};
+
+module.exports = nextConfig;
+```
+
+### Webpack Setup
+
+For custom webpack configurations:
+
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.(jsx|tsx)$/,
+        exclude: /node_modules/,
+        use: [
+          {
+            loader: "macaly-tagger",
+          },
+        ],
+        enforce: "pre",
+      },
+      // ... other rules
+    ],
+  },
+};
+```
+
+### Vite Setup
+
+For Vite projects, you'll need a Vite plugin wrapper (not included in this package).
+
+## Example
+
+### Input JSX:
+
+```jsx
+export default function TestComponent() {
+  return (
+    <div className="container">
+      <h1>Hello Macaly!</h1>
+      <button onClick={() => console.log("clicked")}>Click me</button>
+      <MyLib.SpecialButton />
+    </div>
+  );
+}
+```
+
+### Output HTML (in browser):
+
+```html
+<div
+  data-macaly-loc="components/TestComponent.jsx:3:4"
+  data-macaly-name="div"
+  class="container"
+>
+  <h1 data-macaly-loc="components/TestComponent.jsx:4:6" data-macaly-name="h1">
+    Hello Macaly!
+  </h1>
+  <button
+    data-macaly-loc="components/TestComponent.jsx:5:6"
+    data-macaly-name="button"
+  >
+    Click me
+  </button>
+  <button
+    data-macaly-loc="components/TestComponent.jsx:8:6"
+    data-macaly-name="MyLib.SpecialButton"
+  >
+    Special
+  </button>
+</div>
+```
+
+## How It Works
+
+The loader:
+
+1. **Parses JSX/TSX files** using Babel parser
+2. **Walks the AST** to find JSX opening elements
+3. **Adds location attributes** with file path, line, and column information
+4. **Preserves source maps** for debugging
+5. **Skips already tagged elements** to avoid duplicates
+
+## Configuration
+
+The loader works out of the box with no configuration needed. It automatically:
+
+- Processes only `.jsx` and `.tsx` files
+- Excludes `node_modules` directory
+- Runs only in development mode (when configured properly)
+- Handles both regular JSX elements (`<div>`) and member expressions (`<MyLib.Button>`)
+
+## Attributes Added
+
+For each JSX element, the loader adds:
+
+- `data-macaly-loc`: File path, line, and column (e.g., `"components/Button.jsx:15:8"`)
+- `data-macaly-name`: Component/element name (e.g., `"button"` or `"MyLib.Button"`)
+
+## Browser DevTools Integration
+
+Once installed, you can:
+
+1. Open browser DevTools
+2. Inspect any element
+3. See the `data-macaly-loc` attribute to find the exact source location
+4. Use browser extensions or custom scripts to jump to source code
+
+## Troubleshooting
+
+### Not seeing attributes?
+
+1. **Check console for errors**: Look for `[macaly-tagger]` warnings in the browser console
+2. **Verify development mode**: Ensure the loader only runs in development (`dev && !isServer` for Next.js)
+3. **Check file extensions**: Only `.jsx` and `.tsx` files are processed
+
+### Build errors?
+
+1. **Install dependencies**: Ensure all peer dependencies are installed
+2. **Check webpack version**: Requires webpack >= 4.0.0
+3. **Verify loader path**: Make sure the loader is correctly referenced
+
+### Performance issues?
+
+The loader is optimized for development:
+
+- Only processes JSX/TSX files
+- Excludes node_modules automatically
+- Uses efficient AST walking
+- Includes source map support
+
+### Enable debug logging
+
+Add a console log to see which files are being processed:
+
+```js
+// In your webpack config
+{
+  loader: 'macaly-tagger',
+  options: {
+    debug: true // If you implement options support
+  }
+}
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Changelog
+
+### 1.0.0
+
+- Initial release
+- Support for JSX and TSX files
+- Location tracking with file, line, and column
+- Member expression support (e.g., `MyLib.Button`)
+- Source map preservation

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { default } from './macaly-tagger-loader';
+export type { MacalyTaggerLoaderOptions } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,YAAY,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = void 0;
+var macaly_tagger_loader_1 = require("./macaly-tagger-loader");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(macaly_tagger_loader_1).default; } });

package/dist/macaly-tagger-loader.d.ts

@@ -0,0 +1,4 @@
+import type { MacalyTaggerLoader } from './types';
+declare const macalyTaggerLoader: MacalyTaggerLoader;
+export default macalyTaggerLoader;
+//# sourceMappingURL=macaly-tagger-loader.d.ts.map

package/dist/macaly-tagger-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"macaly-tagger-loader.d.ts","sourceRoot":"","sources":["../src/macaly-tagger-loader.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAInB,MAAM,SAAS,CAAC;AAuFjB,QAAA,MAAM,kBAAkB,EAAE,kBAmIzB,CAAC;AAEF,eAAe,kBAAkB,CAAC"}

package/dist/macaly-tagger-loader.js

@@ -0,0 +1,191 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const parser_1 = require("@babel/parser");
+const magic_string_1 = __importDefault(require("magic-string"));
+const path = __importStar(require("path"));
+const estree_walker_1 = require("estree-walker");
+const VALID_EXTENSIONS = new Set(['.jsx', '.tsx']);
+function getMemberExpressionName(memberExpression) {
+    if (memberExpression.type === 'JSXIdentifier') {
+        return memberExpression.name;
+    }
+    if (memberExpression.type === 'JSXMemberExpression') {
+        const object = getMemberExpressionName(memberExpression.object);
+        const property = memberExpression.property.name;
+        return object ? `${object}.${property}` : null;
+    }
+    return null;
+}
+function isElementAlreadyTagged(attributes) {
+    return (attributes?.some((attr) => attr.type === 'JSXAttribute' &&
+        attr.name?.type === 'JSXIdentifier' &&
+        attr.name.name === 'data-macaly-loc') ?? false);
+}
+function getJSXElementInfo(node) {
+    let tagName;
+    let insertPosition;
+    if (node.name?.type === 'JSXIdentifier') {
+        tagName = node.name.name;
+        insertPosition = node.name.end ?? 0;
+    }
+    else if (node.name?.type === 'JSXMemberExpression') {
+        const name = getMemberExpressionName(node.name);
+        if (!name)
+            return null;
+        tagName = name;
+        insertPosition = node.name.end ?? 0;
+    }
+    else {
+        console.log('[macaly-tagger] Unsupported JSX element type:', node.name?.type);
+        return null;
+    }
+    if (!tagName || insertPosition === 0) {
+        console.log('[macaly-tagger] Missing tagName or insertPosition:', { tagName, insertPosition });
+        return null;
+    }
+    const loc = node.loc?.start;
+    if (!loc) {
+        console.log('[macaly-tagger] No location info for element:', tagName);
+        return null;
+    }
+    return {
+        tagName,
+        insertPosition,
+        location: loc,
+    };
+}
+const macalyTaggerLoader = function (code) {
+    console.log('[macaly-tagger] Loader called with:', this.resourcePath);
+    const callback = this.async();
+    const options = this.getOptions() || {};
+    if (!callback) {
+        throw new Error('[macaly-tagger] Async callback not available');
+    }
+    const transform = async () => {
+        try {
+            if (!VALID_EXTENSIONS.has(path.extname(this.resourcePath)) ||
+                this.resourcePath.includes('node_modules')) {
+                if (options.debug) {
+                    console.log('[macaly-tagger] Skipping file:', this.resourcePath);
+                }
+                return null;
+            }
+            if (options.debug) {
+                console.log('[macaly-tagger] Processing file:', this.resourcePath);
+            }
+            const ast = (0, parser_1.parse)(code, {
+                sourceType: 'module',
+                plugins: ['jsx', 'typescript'],
+                sourceFilename: this.resourcePath,
+            });
+            const ms = new magic_string_1.default(code);
+            const fileRelative = path.relative(this.rootContext || process.cwd(), this.resourcePath);
+            let transformCount = 0;
+            if (options.debug) {
+                console.log('[macaly-tagger] File relative path:', fileRelative);
+            }
+            (0, estree_walker_1.walk)(ast, {
+                enter: (node) => {
+                    try {
+                        if (node.type !== 'JSXOpeningElement')
+                            return;
+                        const jsxNode = node;
+                        if (options.debug) {
+                            console.log('[macaly-tagger] Found JSX element:', jsxNode.name?.type);
+                        }
+                        if (isElementAlreadyTagged(jsxNode.attributes)) {
+                            if (options.debug) {
+                                console.log('[macaly-tagger] Element already tagged');
+                            }
+                            return;
+                        }
+                        const elementInfo = getJSXElementInfo(jsxNode);
+                        if (!elementInfo)
+                            return;
+                        const { tagName, insertPosition, location } = elementInfo;
+                        const macalyLoc = `${fileRelative}:${location.line}:${location.column}`;
+                        if (options.debug) {
+                            console.log('[macaly-tagger] Adding attributes to:', tagName, 'at', macalyLoc);
+                        }
+                        ms.appendLeft(insertPosition, ` data-macaly-loc="${macalyLoc}" data-macaly-name="${tagName}"`);
+                        transformCount++;
+                    }
+                    catch (error) {
+                        console.warn(`[macaly-tagger] Warning: Failed to process JSX node in ${this.resourcePath}:`, error);
+                    }
+                },
+            });
+            if (options.debug) {
+                console.log('[macaly-tagger] Transform count:', transformCount);
+            }
+            if (transformCount === 0) {
+                if (options.debug) {
+                    console.log('[macaly-tagger] No transformations made for:', fileRelative);
+                }
+                return null;
+            }
+            const transformedCode = ms.toString();
+            if (options.debug) {
+                console.log('[macaly-tagger] Successfully transformed:', fileRelative, 'with', transformCount, 'changes');
+            }
+            return {
+                code: transformedCode,
+                map: ms.generateMap({ hires: true }),
+            };
+        }
+        catch (error) {
+            console.warn(`[macaly-tagger] Warning: Failed to transform ${this.resourcePath}:`, error);
+            return null;
+        }
+    };
+    transform()
+        .then((result) => {
+        if (result) {
+            callback(null, result.code, result.map);
+        }
+        else {
+            callback(null, code);
+        }
+    })
+        .catch((err) => {
+        console.error(`[macaly-tagger] ERROR in ${this.resourcePath}:`, err);
+        callback(null, code);
+    });
+};
+exports.default = macalyTaggerLoader;

package/dist/types.d.ts

@@ -0,0 +1,19 @@
+import { LoaderDefinitionFunction } from 'webpack';
+export interface MacalyTaggerLoaderOptions {
+    debug?: boolean;
+}
+export interface SourceLocation {
+    line: number;
+    column: number;
+}
+export interface JSXElementInfo {
+    tagName: string;
+    insertPosition: number;
+    location: SourceLocation;
+}
+export interface TransformResult {
+    code: string;
+    map: any;
+}
+export type MacalyTaggerLoader = LoaderDefinitionFunction<MacalyTaggerLoaderOptions>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAEnD,MAAM,WAAW,yBAAyB;IACxC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,GAAG,CAAC;CACV;AAED,MAAM,MAAM,kBAAkB,GAAG,wBAAwB,CAAC,yBAAyB,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "macaly-tagger",
+  "version": "1.0.0",
+  "description": "A webpack loader that adds location metadata to JSX elements for development debugging",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "module": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:watch": "tsc -p tsconfig.build.json --watch",
+    "clean": "rimraf dist",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "lint": "eslint src --ext .ts,.tsx",
+    "lint:fix": "eslint src --ext .ts,.tsx --fix",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx}\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "npm run clean && npm run build && npm run test && npm run lint",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "webpack",
+    "loader",
+    "jsx",
+    "tsx",
+    "react",
+    "nextjs",
+    "debugging",
+    "development",
+    "typescript",
+    "babel"
+  ],
+  "author": {
+    "name": "Macaly",
+    "email": "hi@macaly.com",
+    "url": "https://macaly.com"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@babel/parser": "^7.24.0",
+    "magic-string": "^0.30.0",
+    "estree-walker": "^2.0.2"
+  },
+  "devDependencies": {
+    "@babel/types": "^7.24.0",
+    "@types/estree": "^1.0.5",
+    "@types/node": "^20.11.30",
+    "@typescript-eslint/eslint-plugin": "^7.3.1",
+    "@typescript-eslint/parser": "^7.3.1",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.1.3",
+    "vitest": "^1.4.0",
+    "prettier": "^3.2.5",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.4.2"
+  },
+  "peerDependencies": {
+    "webpack": ">=4.0.0"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/langtail/macaly-tagger.git"
+  },
+  "bugs": {
+    "url": "https://github.com/langtail/macaly-tagger/issues"
+  },
+  "homepage": "https://github.com/langtail/macaly-tagger#readme"
+}