es-guard 1.2.0 → 1.3.0

package/README.md

@@ -2,16 +2,16 @@
 
 [![codecov](https://codecov.io/gh/mkayander/es-guard/branch/main/graph/badge.svg)](https://codecov.io/gh/mkayander/es-guard)
 
-A TypeScript-based tool to check JavaScript compatibility with target environments using ESLint.
+A powerful TypeScript-based tool that ensures your JavaScript code is compatible with target environments using ESLint.
 
 ## Features
 
-- 🔍 **ES Version Compatibility**: Check if your JavaScript code is compatible with specific ES versions (ES2015, ES2016, ES2017, etc.)
-- 🌐 **Browser Compatibility**: Verify browser support using eslint-plugin-compat
-- 🎯 **Auto Browser Detection**: Automatically determine browser targets from ES version (optional)
-- 📁 **Directory Scanning**: Automatically scan directories for JavaScript files
-- 🎯 **GitHub Actions Ready**: Works seamlessly with GitHub Actions
-- 📦 **NPM Package**: Install globally or use as a dependency
+- 🔍 **ES Version Validation**: Verify your JavaScript code compatibility with specific ES versions (ES2015, ES2016, ES2017, and beyond)
+- 🌐 **Browser Support Verification**: Validate browser compatibility using eslint-plugin-compat
+- 🎯 **Smart Browser Detection**: Automatically determine browser targets from ES version (optional)
+- 📁 **Comprehensive Directory Scanning**: Effortlessly scan directories for JavaScript files
+- 🚀 **GitHub Actions Integration**: Seamlessly integrate with GitHub Actions workflows
+- 📦 **Flexible Installation**: Install globally or use as a project dependency
 
 ## Installation
 
@@ -38,13 +38,13 @@ npm run build
 
 ## Usage
 
-### Command Line
+### Command Line Interface
 
 ```bash
-# Basic usage with defaults (auto-determined browsers)
+# Basic usage with auto-detected browsers
 es-guard
 
-# Check specific directory
+# Validate specific directory
 es-guard build
 
 # Specify target ES version (year format)
@@ -59,10 +59,10 @@ es-guard -t latest build
 # Specify custom browser targets
 es-guard --browsers "> 0.5%, last 2 versions, Firefox ESR, not dead" dist
 
-# Show help
+# Display help information
 es-guard --help
 
-# Show version
+# Show version information
 es-guard --version
 ```
 
@@ -71,13 +71,13 @@ es-guard --version
 ```typescript
 import { checkCompatibility } from "es-guard";
 
-// With auto-determined browsers
+// With auto-detected browsers
 const violations = await checkCompatibility({
   dir: "dist",
   target: "2015",
 });
 
-// With custom browsers
+// With custom browser specifications
 const violations = await checkCompatibility({
   dir: "dist",
   target: "2015",
@@ -85,10 +85,10 @@ const violations = await checkCompatibility({
 });
 ```
 
-### GitHub Actions
+### GitHub Actions Integration
 
 ```yaml
-name: Check Compatibility
+name: Validate Compatibility
 on: [push, pull_request]
 
 jobs:
@@ -108,15 +108,15 @@ jobs:
 
 ### Parameters
 
-| Parameter  | Description                                | Default                     | Required |
-| ---------- | ------------------------------------------ | --------------------------- | -------- |
-| `path`     | Directory to scan for JavaScript files     | `dist`                      | No       |
-| `target`   | Target ES version                          | `2015`                      | Yes      |
-| `browsers` | Browser targets for compatibility checking | Auto-determined from target | No       |
+| Parameter  | Description                                | Default                   | Required |
+| ---------- | ------------------------------------------ | ------------------------- | -------- |
+| `path`     | Directory to scan for JavaScript files     | `dist`                    | No       |
+| `target`   | Target ES version                          | `2015`                    | Yes      |
+| `browsers` | Browser targets for compatibility checking | Auto-detected from target | No       |
 
 ### ES Target Versions
 
-The `target` parameter accepts multiple formats:
+The `target` parameter supports multiple formats:
 
 - **Year format**: `2015`, `2016`, `2017`, etc.
 - **Numeric format**: `6` (ES2015), `7` (ES2016), `11` (ES2020), etc.
@@ -124,17 +124,17 @@ The `target` parameter accepts multiple formats:
 
 ### Browser Targets
 
-The `browsers` parameter uses the same format as Browserslist. If not specified, browsers will be automatically determined based on the ES target:
+The `browsers` parameter follows the Browserslist format. When not specified, browsers are automatically determined based on the ES target:
 
 - **ES2015/ES6**: `> 1%, last 2 versions, not dead, ie 11`
 - **ES2016-2017/ES7-8**: `> 1%, last 2 versions, not dead, not ie 11`
 - **ES2018-2019/ES9-10**: `> 1%, last 2 versions, not dead, not ie 11, not op_mini all`
 - **ES2020+/ES11+**: `> 1%, last 2 versions, not dead, not ie 11, not op_mini all, not android < 67`
 
-Custom browser targets examples:
+Custom browser target examples:
 
-- `> 1%, last 2 versions, not dead, ie 11` - Modern browsers + IE11
-- `> 0.5%, last 2 versions, Firefox ESR, not dead` - Broader support
+- `> 1%, last 2 versions, not dead, ie 11` - Modern browsers with IE11 support
+- `> 0.5%, last 2 versions, Firefox ESR, not dead` - Broader browser support
 - `defaults` - Default Browserslist targets
 - `last 1 version` - Latest version of each browser
 
@@ -186,8 +186,8 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 1. Fork the repository
 2. Create a feature branch
-3. Make your changes
-4. Add tests if applicable
+3. Implement your changes
+4. Add tests where applicable
 5. Run the linter: `npm run lint`
 6. Submit a pull request
 

package/dist/lib/detectTarget.js

@@ -1,6 +1,28 @@
 import * as fs from "fs";
 import * as path from "path";
 // Shared utilities for ES version parsing and conversion
+const CONFIG_FILE_NAMES = [
+    "package.json",
+    ".browserslistrc",
+    ".browserslist",
+    "tsconfig.json",
+    "babel.config.js",
+    "babel.config.cjs",
+    "babel.config.mjs",
+    ".babelrc",
+    "vite.config.js",
+    "vite.config.ts",
+    "vite.config.cjs",
+    "vite.config.mjs",
+    "webpack.config.js",
+    "webpack.config.ts",
+    "webpack.config.cjs",
+    "webpack.config.mjs",
+    "next.config.js",
+    "next.config.ts",
+    "next.config.cjs",
+    "next.config.mjs",
+];
 /**
  * Parse ES version from string (e.g., "es6", "es2020", "ES2015")
  * Returns the year as a string, or null if not found
@@ -53,11 +75,42 @@ const readJsonFile = (filePath) => {
     const content = fs.readFileSync(filePath, "utf-8");
     return JSON.parse(content);
 };
+/**
+ * Helper to read text file safely
+ */
+const readTextFile = (filePath) => {
+    return fs.readFileSync(filePath, "utf-8");
+};
+/**
+ * Helper to safely evaluate JavaScript files (for config files)
+ */
+const evaluateJsFile = (filePath) => {
+    const content = readTextFile(filePath);
+    // Create a safe evaluation context
+    const module = { exports: {} };
+    const require = (id) => {
+        if (id === "path")
+            return path;
+        if (id === "fs")
+            return fs;
+        throw new Error(`Cannot require '${id}' in config evaluation`);
+    };
+    try {
+        // Use Function constructor to create a safe evaluation environment
+        const fn = new Function("module", "exports", "require", "path", "fs", "__dirname", content);
+        fn(module, module.exports, require, path, fs, path.dirname(filePath));
+        return module.exports;
+    }
+    catch (error) {
+        console.warn(`Error evaluating ${filePath}:`, error);
+        return null;
+    }
+};
 /**
  * Type guard for package.json structure
  */
 const isPackageJson = (obj) => {
-    return typeof obj === "object" && obj !== null && "browserslist" in obj;
+    return typeof obj === "object" && obj !== null;
 };
 /**
  * Type guard for tsconfig.json structure
@@ -72,57 +125,121 @@ const isBabelRc = (obj) => {
     return typeof obj === "object" && obj !== null && "presets" in obj;
 };
 /**
- * Helper to read text file safely
+ * Type guard for vite config structure
  */
-const readTextFile = (filePath) => {
-    return fs.readFileSync(filePath, "utf-8");
+const isViteConfig = (obj) => {
+    return typeof obj === "object" && obj !== null;
 };
 /**
- * Detects ES target from common frontend project configuration files.
+ * Type guard for webpack config structure
+ */
+const isWebpackConfig = (obj) => {
+    return typeof obj === "object" && obj !== null;
+};
+/**
+ * Type guard for next.js config structure
+ */
+const isNextConfig = (obj) => {
+    return typeof obj === "object" && obj !== null;
+};
+/**
+ * Get parser function for a given config file
+ */
+const getParser = (filename) => {
+    switch (true) {
+        case filename === "package.json":
+            return parsePackageJson;
+        case filename === ".browserslistrc":
+        case filename === ".browserslist":
+            return parseBrowserslistFile;
+        case filename === "tsconfig.json":
+            return parseTsConfig;
+        case filename === ".babelrc":
+            return parseBabelRc;
+        case filename.startsWith("babel.config"):
+            return parseBabelConfig;
+        case filename.startsWith("vite.config"):
+            return parseViteConfig;
+        case filename.startsWith("webpack.config"):
+            return parseWebpackConfig;
+        case filename.startsWith("next.config"):
+            return parseNextConfig;
+        default:
+            return null;
+    }
+};
+/**
+ * Get all possible config file names for detection
+ */
+const getConfigFileNames = () => {
+    return CONFIG_FILE_NAMES;
+};
+/**
+ * Detects both ES target and output directory from common frontend project configuration files.
  * Searches in order of preference: package.json, .browserslistrc/.browserslist, tsconfig.json, babel.config.js, .babelrc, vite.config.js, webpack.config.js
- * Returns an object with the detected target and the source file name, or null if not found
+ * Returns an object with detected target and output directory information
  */
-export const detectTarget = (cwd = process.cwd()) => {
-    const configFiles = [
-        { name: "package.json", parser: parsePackageJson },
-        { name: ".browserslistrc", parser: parseBrowserslistFile },
-        { name: ".browserslist", parser: parseBrowserslistFile },
-        { name: "tsconfig.json", parser: parseTsConfig },
-        { name: "babel.config.js", parser: parseBabelConfig },
-        { name: ".babelrc", parser: parseBabelRc },
-        { name: "vite.config.js", parser: parseViteConfig },
-        { name: "vite.config.ts", parser: parseViteConfig },
-        { name: "webpack.config.js", parser: parseWebpackConfig },
-        { name: "webpack.config.ts", parser: parseWebpackConfig },
-    ];
-    for (const config of configFiles) {
-        const filePath = path.join(cwd, config.name);
+export const detectTargetAndOutput = (cwd = process.cwd()) => {
+    const configFileNames = getConfigFileNames();
+    const result = {};
+    for (const filename of configFileNames) {
+        const filePath = path.join(cwd, filename);
         if (fs.existsSync(filePath)) {
+            const parser = getParser(filename);
+            if (!parser) {
+                console.warn(`No parser found for ${filename}`);
+                continue;
+            }
             try {
-                const target = config.parser(filePath);
-                if (target) {
-                    return { target, source: config.name };
+                const detection = parser(filePath);
+                // Update target if found and not already set
+                if (detection.target && !result.target) {
+                    result.target = detection.target;
+                    result.targetSource = filename;
+                }
+                // Update output directory if found and not already set
+                if (detection.outputDir && !result.outputDir) {
+                    result.outputDir = detection.outputDir;
+                    result.outputSource = filename;
+                }
+                // If we found both target and output directory, we can stop searching
+                if (result.target && result.outputDir) {
+                    break;
                 }
             }
             catch (error) {
-                console.warn(`Error parsing ${config.name}:`, error);
-                // Continue to next config file if parsing fails
+                console.warn(`Error parsing ${filename}:`, error);
                 continue;
             }
         }
     }
-    return null;
+    return result;
+};
+/**
+ * Legacy function for backward compatibility - detects only ES target
+ */
+export const detectTarget = (cwd = process.cwd()) => {
+    const result = detectTargetAndOutput(cwd);
+    return result.target ? { target: result.target, source: result.targetSource } : null;
 };
 /**
- * Parse package.json for ES target in browserslist
+ * Legacy function for backward compatibility - detects only output directory
+ */
+export const detectOutputDir = (cwd = process.cwd()) => {
+    const result = detectTargetAndOutput(cwd);
+    return result.outputDir ? { outputDir: result.outputDir, source: result.outputSource } : null;
+};
+/**
+ * Parse package.json for both target and output directory
  */
 const parsePackageJson = (filePath) => {
     const pkg = readJsonFile(filePath);
     if (!isPackageJson(pkg)) {
         console.warn(`Warning: ${filePath} does not look like a valid package.json (missing or invalid browserslist field).`);
-        return null;
+        return {};
     }
-    // Check for browserslist field
+    const result = {};
+    // Check for browserslist field for target
     if (pkg.browserslist) {
         const browserslist = Array.isArray(pkg.browserslist) ? pkg.browserslist : [pkg.browserslist];
         // Look for ES target in browserslist
@@ -130,32 +247,52 @@ const parsePackageJson = (filePath) => {
             if (typeof browser === "string") {
                 const target = parseESVersion(browser);
                 if (target) {
-                    return target;
+                    result.target = target;
+                    break;
                 }
             }
         }
     }
-    // Note: engines.node is for development/build tools, not client-side targets
-    // So we don't use it for auto-detection
-    return null;
+    // Check for output directory hints
+    if (pkg.dist) {
+        result.outputDir = pkg.dist;
+    }
+    else if (pkg.build) {
+        result.outputDir = pkg.build;
+    }
+    else if (pkg.main && pkg.main.startsWith("./dist/")) {
+        result.outputDir = "dist";
+    }
+    else if (pkg.dependencies?.next || pkg.devDependencies?.next) {
+        // Next.js apps default to .next directory
+        result.outputDir = ".next/static";
+    }
+    return result;
 };
 /**
- * Parse tsconfig.json for target
+ * Parse tsconfig.json for both target and output directory
  */
 const parseTsConfig = (filePath) => {
     const config = readJsonFile(filePath);
     if (!isTsConfig(config)) {
         console.warn(`Warning: ${filePath} does not look like a valid tsconfig.json (missing or invalid compilerOptions field).`);
-        return null;
+        return {};
     }
+    const result = {};
     if (config.compilerOptions?.target) {
         const target = config.compilerOptions.target;
-        return TARGET_MAP[target] || null;
+        const mappedTarget = TARGET_MAP[target];
+        if (mappedTarget) {
+            result.target = mappedTarget;
+        }
     }
-    return null;
+    if (config.compilerOptions?.outDir) {
+        result.outputDir = config.compilerOptions.outDir;
+    }
+    return result;
 };
 /**
- * Parse babel.config.js for preset-env target
+ * Parse babel.config.js for target
  */
 const parseBabelConfig = (filePath) => {
     const content = readTextFile(filePath);
@@ -167,19 +304,22 @@ const parseBabelConfig = (filePath) => {
         const browsersMatch = targetsStr.match(/browsers.*?\[(.*?)\]/);
         if (browsersMatch) {
             const browsers = browsersMatch[1];
-            return parseESVersion(browsers);
+            const target = parseESVersion(browsers);
+            if (target) {
+                return { target };
+            }
         }
     }
-    return null;
+    return {};
 };
 /**
- * Parse .babelrc for preset-env target
+ * Parse .babelrc for target
  */
 const parseBabelRc = (filePath) => {
     const config = readJsonFile(filePath);
     if (!isBabelRc(config)) {
         console.warn(`Warning: ${filePath} does not look like a valid .babelrc (missing or invalid presets field).`);
-        return null;
+        return {};
     }
     if (config.presets) {
         for (const preset of config.presets) {
@@ -190,40 +330,61 @@ const parseBabelRc = (filePath) => {
                     for (const browser of browsers) {
                         const target = parseESVersion(browser);
                         if (target) {
-                            return target;
+                            return { target };
                         }
                     }
                 }
             }
         }
     }
-    return null;
+    return {};
 };
 /**
- * Parse vite.config.js/ts for target
+ * Parse vite.config.js/ts for both target and output directory
  */
 const parseViteConfig = (filePath) => {
     const content = readTextFile(filePath);
-    // Look for esbuild target - more flexible pattern
+    const config = evaluateJsFile(filePath);
+    const result = {};
+    // Look for esbuild target
     const esbuildMatch = content.match(/esbuild\s*:\s*\{[^}]*target\s*:\s*['"`]([^'"`]+)['"`]/s);
     if (esbuildMatch) {
         const target = esbuildMatch[1];
-        return TARGET_MAP[target] || null;
+        const mappedTarget = TARGET_MAP[target];
+        if (mappedTarget) {
+            result.target = mappedTarget;
+        }
     }
-    return null;
+    // Look for output directory
+    if (isViteConfig(config) && config.build?.outDir) {
+        result.outputDir = config.build.outDir;
+    }
+    return result;
 };
 /**
- * Parse webpack.config.js/ts for target
+ * Parse webpack.config.js/ts for both target and output directory
  */
 const parseWebpackConfig = (filePath) => {
     const content = readTextFile(filePath);
+    const config = evaluateJsFile(filePath);
+    const result = {};
     // Look for target configuration
     const targetMatch = content.match(/target.*?['"`]([^'"`]+)['"`]/);
     if (targetMatch) {
         const target = targetMatch[1];
-        return TARGET_MAP[target] || null;
+        const mappedTarget = TARGET_MAP[target];
+        if (mappedTarget) {
+            result.target = mappedTarget;
+        }
     }
-    return null;
+    // Look for output directory
+    if (isWebpackConfig(config) && config.output?.path) {
+        // Extract just the directory name from the path
+        const outputPath = config.output.path;
+        const dirName = path.basename(outputPath);
+        result.outputDir = dirName;
+    }
+    return result;
 };
 /**
  * Parse .browserslistrc or .browserslist file for ES target
@@ -237,8 +398,27 @@ const parseBrowserslistFile = (filePath) => {
     for (const browser of lines) {
         const target = parseESVersion(browser);
         if (target) {
-            return target;
+            return { target };
         }
     }
-    return null;
+    return {};
+};
+/**
+ * Parse next.config.js/ts/cjs/mjs for output directory
+ */
+const parseNextConfig = (filePath) => {
+    const config = evaluateJsFile(filePath);
+    if (!isNextConfig(config)) {
+        return {};
+    }
+    const result = {};
+    // Next.js uses .next as default output directory
+    if (config.distDir) {
+        result.outputDir = config.distDir;
+    }
+    else {
+        // Default Next.js output directory
+        result.outputDir = ".next";
+    }
+    return result;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "es-guard",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "A tool to check JavaScript compatibility with target environments",
   "type": "module",
   "main": "dist/cli.js",