ldx 1.0.0 → 1.0.2

package/README.md

@@ -1,3 +1,229 @@
-# ldx - logging developer experience
-transform command outputs to custom logs
+# LDX - Logging Developer Experience
 
+A lightweight tool to enhance your development workflow by processing command output with customizable transformations.
+
+## Features
+
+- **Custom static transformations**: Define string patterns in your command output and replace them with custom messages.
+
+- **Custom dynamic transformations**: Supports function-based transformations
+
+- **Easy Integration**: Works seamlessly with any command-line tool or script.
+
+- **Developer-Friendly**: Improves readability and reduces noise in logs.
+
+## Installation
+
+To install LDX globally, run:
+
+```bash
+pnpm install -g ldx
+```
+
+Alternatively, you can install it locally in your project:
+
+```bash
+pnpm install --save-dev ldx
+```
+
+## Usage
+
+### 1. Create a Configuration File
+
+Create a `ldx.config.js` file in your project's root directory. This file defines the patterns and transformations for your command output.
+
+Example:
+
+```js
+module.exports = {
+  // Simple string replacement
+  "Test match 1": "✅ Test match 1 processed",
+
+  // Function-based processing
+  "Function match": (line) => `Processed: ${line}`,
+};
+```
+
+### 2. Run Commands with LDX
+
+Use LDX to run your commands and transform their output:
+
+```bash
+ldx <your-command>
+```
+
+For example:
+
+```bash
+ldx pnpm run dev
+```
+
+## Configuration Options
+
+### String Matching
+
+```js
+module.exports = {
+  "String contained in output line": "Replacement text for the entire line"
+}
+```
+
+### Function Processing
+
+```js
+module.exports = {
+  "String contained in output line": (line) => {
+    // Custom processing logic
+    return `Formatted: ${line}`;
+  }
+}
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+
+## Error Handling
+
+LDX provides clear error messages for common issues:
+
+### Missing Configuration File
+
+If `ldx.config.js` is not found in your project root:
+
+```text
+Oops, no ldx.config.js file found!
+```
+
+**Solution**: Create a `ldx.config.js` file in your project root. You can copy `ldx.config.example.js` as a starting point.
+
+### Invalid Configuration
+
+If your configuration has invalid values:
+
+```text
+LDX: Configuration error - Invalid value type for key "myKey". Expected string or function, got number.
+```
+
+**Solution**: Ensure all configuration values are either strings or functions.
+
+### Empty Configuration
+
+If your configuration object is empty:
+
+```text
+LDX: Configuration error - Configuration cannot be empty.
+```
+
+**Solution**: Add at least one pattern-transformation pair to your configuration.
+
+### Command Not Found
+
+If the command you're trying to run doesn't exist:
+
+```text
+Error executing command: Failed to start command: spawn xyz ENOENT
+```
+
+**Solution**: Verify the command exists and is in your PATH.
+
+### Function Processing Errors
+
+If a transformer function throws an error, LDX will:
+
+1. Log a warning: `LDX: provided function errored: <error message>`
+2. Output the original unprocessed line (to prevent data loss)
+
+**Solution**: Add try-catch blocks in your transformer functions for graceful error handling.
+
+## Testing
+
+Run tests with:
+
+```bash
+pnpm test
+```
+
+## Usage examples
+
+### Basic Usage
+
+```bash
+ldx echo "Testing LDX tool"
+```
+
+### With package manager scripts
+
+```bash
+ldx pnpm run dev
+```
+
+### With complex commands
+
+```bash
+ldx docker-compose up
+```
+
+## Development
+
+1. Clone the repository
+
+2. Install dependencies:
+
+   ```bash
+   pnpm i
+   ```
+
+3. Make changes
+
+4. Run tests:
+
+   ```bash
+   pnpm test
+   ```
+
+## Releasing
+
+This project uses [standard-version](https://github.com/conventional-changelog/standard-version) for automated versioning and changelog generation based on [Conventional Commits](https://www.conventionalcommits.org/).
+
+### Commit Message Format
+
+```text
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`, `build`
+
+Examples:
+
+```bash
+git commit -m "feat: add support for regex patterns"
+git commit -m "fix: handle empty lines in output"
+git commit -m "docs: update configuration examples"
+```
+
+### Creating a Release
+
+```bash
+# Automatic version bump based on commits (recommended)
+pnpm release
+
+# Specific version bumps
+pnpm release:patch  # 1.0.2 -> 1.0.3
+pnpm release:minor  # 1.0.2 -> 1.1.0
+pnpm release:major  # 1.0.2 -> 2.0.0
+```
+
+After running the release command:
+
+```bash
+git push --follow-tags origin main && npm publish
+```
+
+## Contributing
+
+Contributions are welcome! Please open issues or pull requests in this repo.

package/ldx.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+
+const { resolve } = require("node:path");
+const { spawn } = require("child_process");
+
+// Load configuration
+const project = resolve(process.cwd(), "ldx.config.js");
+let config;
+try {
+  config = require(project);
+} catch (e) {
+  console.error("Oops, no ldx.config.js file found!");
+  process.exit(1);
+}
+
+// Validate configuration
+function validateConfig(cfg) {
+  if (!cfg || typeof cfg !== "object" || Array.isArray(cfg)) {
+    return { valid: false, error: "Configuration must be a non-null object." };
+  }
+
+  const entries = Object.entries(cfg);
+  if (entries.length === 0) {
+    return { valid: false, error: "Configuration cannot be empty." };
+  }
+
+  for (const [key, value] of entries) {
+    if (typeof value !== "string" && typeof value !== "function") {
+      return {
+        valid: false,
+        error: `Invalid value type for key "${key}". Expected string or function, got ${typeof value}.`,
+      };
+    }
+  }
+
+  return { valid: true };
+}
+
+const validation = validateConfig(config);
+if (!validation.valid) {
+  console.error(`LDX: Configuration error - ${validation.error}`);
+  process.exit(1);
+}
+
+console.log(
+  "Thank you for using LDX! Collaborate or report issues at https://github.com/leog/ldx \n"
+);
+
+// Function to execute the command and process output
+function executeAndProcessCommand() {
+  return new Promise((resolve, reject) => {
+    const command = process.argv.slice(2);
+    if (command.length === 0) {
+      reject(new Error("No command provided."));
+      return;
+    }
+
+    const child = spawn(command[0], command.slice(1));
+
+    // Handle spawn errors (e.g., command not found)
+    child.on("error", (error) => {
+      reject(new Error(`Failed to start command: ${error.message}`));
+    });
+
+    // Handle stdout
+    if (child.stdout) {
+      child.stdout.on("data", (data) => {
+        const lines = data.toString().split("\n");
+        lines.forEach((line) => {
+          const processedLine = processOutput(line);
+          if (processedLine) {
+            console.log(processedLine); // Output the processed line
+          }
+        });
+      });
+    }
+
+    // Handle stderr
+    if (child.stderr) {
+      child.stderr.on("data", (data) => {
+        const lines = data.toString().split("\n");
+        lines.forEach((line) => {
+          const processedLine = processOutput(line);
+          if (processedLine) {
+            console.error(processedLine); // Output processed error line to stderr
+          } else if (line.trim()) {
+            console.error(line); // Pass through unmatched non-empty lines
+          }
+        });
+      });
+    }
+
+    // Handle process exit
+    child.on("close", (code) => {
+      if (code !== 0) {
+        reject(new Error(`Command failed with exit code ${code}`));
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+
+// Function to process each line of output
+function processOutput(line) {
+  // Check static matches first (O(n) lookup, but optimized for small n)
+  const match = Object.entries(config).find(([key]) => line.includes(key));
+
+  if (match) {
+    const [key, value] = match;
+
+    // Handle string values
+    if (typeof value === "string") {
+      return value;
+    }
+
+    // Handle function values
+    if (typeof value === "function") {
+      try {
+        return value(line);
+      } catch (e) {
+        console.warn("LDX: provided function errored: ", e.message);
+        return line; // Return original line on error to prevent data loss
+      }
+    }
+
+    // Handle invalid configurations
+    console.warn(
+      `Invalid configuration for key: ${key}. Expected string or function.`
+    );
+  }
+
+  // No match found
+  return undefined;
+}
+
+// Export functions for testing
+module.exports = {
+  processOutput,
+  executeAndProcessCommand,
+  validateConfig,
+};
+
+// Execute the command if this script is run directly
+/* v8 ignore start */
+if (require.main === module) {
+  // Main execution
+  executeAndProcessCommand()
+    .then(() => console.log("Command executed successfully."))
+    .catch((error) => console.error("Error executing command:", error));
+}
+/* v8 ignore end */

package/package.json

@@ -1,12 +1,49 @@
 {
   "name": "ldx",
-  "version": "1.0.0",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "version": "1.0.2",
+  "main": "ldx.js",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "ldx": "ldx.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leog/ldx.git"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "description": ""
+  "keywords": [
+    "transform",
+    "output",
+    "logging",
+    "developer",
+    "experience",
+    "dx"
+  ],
+  "files": [
+    "package.json",
+    "ldx.js",
+    "README.md"
+  ],
+  "author": {
+    "name": "Leo Giovanetti",
+    "email": "hello@leog.me",
+    "url": "https://x.com/leog"
+  },
+  "license": "Apache-2.0",
+  "description": "Enhancing logging developer experience",
+  "devDependencies": {
+    "@vitest/coverage-v8": "3.0.9",
+    "mock-require": "^3.0.3",
+    "standard-version": "^9.5.0",
+    "vitest": "^3.0.9"
+  },
+  "scripts": {
+    "test": "vitest --coverage",
+    "release": "standard-version",
+    "release:minor": "standard-version --release-as minor",
+    "release:major": "standard-version --release-as major",
+    "release:patch": "standard-version --release-as patch",
+    "release:first": "standard-version --first-release"
+  }
 }