es-guard 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Max Kayander
+
+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,198 @@
+# ES-Guard
+
+[![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.
+
+## 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
+
+## Installation
+
+### Global Installation
+
+```bash
+npm install -g es-guard
+```
+
+### Local Installation
+
+```bash
+npm install --save-dev es-guard
+```
+
+### From Source
+
+```bash
+git clone https://github.com/mkayander/es-guard.git
+cd es-guard
+npm install
+npm run build
+```
+
+## Usage
+
+### Command Line
+
+```bash
+# Basic usage with defaults (auto-determined browsers)
+es-guard
+
+# Check specific directory
+es-guard build
+
+# Specify target ES version (year format)
+es-guard -t 2020 build
+
+# Specify target ES version (numeric format)
+es-guard -t 11 build
+
+# Use latest ES version
+es-guard -t latest build
+
+# Specify custom browser targets
+es-guard --browsers "> 0.5%, last 2 versions, Firefox ESR, not dead" dist
+
+# Show help
+es-guard --help
+
+# Show version
+es-guard --version
+```
+
+### Programmatic Usage
+
+```typescript
+import { checkCompatibility } from "es-guard";
+
+// With auto-determined browsers
+const violations = await checkCompatibility({
+  dir: "dist",
+  target: "2015",
+});
+
+// With custom browsers
+const violations = await checkCompatibility({
+  dir: "dist",
+  target: "2015",
+  browsers: "> 1%, last 2 versions, not dead, ie 11",
+});
+```
+
+### GitHub Actions
+
+```yaml
+name: Check Compatibility
+on: [push, pull_request]
+
+jobs:
+  compatibility:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: "18"
+      - run: npm install
+      - run: npm run build
+      - run: npx es-guard -t 2015 dist
+```
+
+## Configuration
+
+### 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       |
+
+### ES Target Versions
+
+The `target` parameter accepts multiple formats:
+
+- **Year format**: `2015`, `2016`, `2017`, etc.
+- **Numeric format**: `6` (ES2015), `7` (ES2016), `11` (ES2020), etc.
+- **Latest**: `latest` for the most recent ES version
+
+### Browser Targets
+
+The `browsers` parameter uses the same format as Browserslist. If not specified, browsers will be 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:
+
+- `> 1%, last 2 versions, not dead, ie 11` - Modern browsers + IE11
+- `> 0.5%, last 2 versions, Firefox ESR, not dead` - Broader support
+- `defaults` - Default Browserslist targets
+- `last 1 version` - Latest version of each browser
+
+## Development
+
+### Setup
+
+```bash
+npm install
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Development Mode
+
+```bash
+npm run dev
+```
+
+### Testing
+
+```bash
+npm test
+npm run test:run
+```
+
+### Linting
+
+```bash
+npm run lint
+```
+
+## Publishing to NPM
+
+1. Update the version in `package.json`
+2. Update the repository URL in `package.json`
+3. Build the project: `npm run build`
+4. Publish: `npm publish`
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Run the linter: `npm run lint`
+6. Submit a pull request
+
+## Support
+
+- 📖 [Documentation](https://github.com/mkayander/es-guard#readme)
+- 🐛 [Issues](https://github.com/mkayander/es-guard/issues)
+- 💬 [Discussions](https://github.com/mkayander/es-guard/discussions)

package/dist/cli.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import * as fs from "fs";
+import packageJson from "../package.json" with { type: "json" };
+import { checkCompatibility } from "./lib/checkCompatiblity.js";
+import { getBrowserTargetsFromString } from "./lib/getBrowserTargets.js";
+const version = packageJson.version;
+// Create the main program
+const program = new Command();
+// Configure the program
+program
+    .name("es-guard")
+    .description("JavaScript Compatibility Checker - Check if your JavaScript code is compatible with target environments")
+    .version(version)
+    .argument("[directory]", "Directory to scan for JavaScript files", "dist")
+    .option("-t, --target <version>", "Target ES version (2015, 2016, 2017, etc. or 6, 7, 8, etc. or 'latest')", "2015")
+    .option("-b, --browsers <targets>", "Browser targets for compatibility checking (optional: auto-determined from target)")
+    .addHelpText("after", `
+
+Examples:
+  es-guard                           # Check 'dist' directory with ES2015 (auto-determined browsers)
+  es-guard build                     # Check 'build' directory with ES2015 (auto-determined browsers)
+  es-guard -t 2020 build             # Check 'build' directory with ES2020 (auto-determined browsers)
+  es-guard -t 6 build                # Check 'build' directory with ES6 (auto-determined browsers)
+  es-guard -t latest build           # Check 'build' directory with latest ES (auto-determined browsers)
+  es-guard --target 2017 --browsers "> 0.5%, last 2 versions" dist
+
+Browser targets use Browserslist format:
+  - If not specified, browsers will be auto-determined from the ES target version
+  - "> 1%, last 2 versions, not dead, ie 11" (for ES2015/ES6)
+  - "> 1%, last 2 versions, not dead, not ie 11" (for ES2016-2017/ES7-8)
+  - "> 1%, last 2 versions, not dead, not ie 11, not op_mini all" (for ES2018-2019/ES9-10)
+  - "> 1%, last 2 versions, not dead, not ie 11, not op_mini all, not android < 67" (for ES2020+/ES11+)
+
+Exit codes:
+  0 - No compatibility issues found
+  1 - Compatibility issues found or error occurred
+`);
+// Add validation for the target option
+program.hook("preAction", (thisCommand) => {
+    const options = thisCommand.opts();
+    const target = options.target;
+    // Validate ES target format - accept year format (YYYY), numeric format (N), or "latest"
+    if (!/^\d{4}$/.test(target) && !/^\d+$/.test(target) && target !== "latest") {
+        console.error(`Error: Invalid ES target: "${target}". Expected format: YYYY (e.g., 2015, 2020), numeric (e.g., 6, 11), or "latest"`);
+        process.exit(1);
+    }
+});
+// Main action
+program.action(async (directory, options) => {
+    try {
+        // Validate directory exists
+        if (!fs.existsSync(directory)) {
+            console.error(`Error: Directory "${directory}" does not exist`);
+            process.exit(1);
+        }
+        const stat = fs.statSync(directory);
+        if (!stat.isDirectory()) {
+            console.error(`Error: "${directory}" is not a directory`);
+            process.exit(1);
+        }
+        // Determine browser targets
+        const browserTargets = options.browsers || getBrowserTargetsFromString(options.target);
+        console.log(`🔍 ES-Guard v${version}`);
+        console.log(`📁 Scanning directory: ${directory}`);
+        console.log(`🎯 Target ES version: ${options.target}`);
+        console.log(`🌐 Browser targets: ${browserTargets}${options.browsers ? "" : " (auto-determined)"}`);
+        console.log("");
+        const violations = await checkCompatibility({
+            dir: directory,
+            target: options.target,
+            browsers: browserTargets,
+        });
+        if (violations.length > 0) {
+            console.error(`❌ Found ${violations.length} file(s) with compatibility issues:`);
+            for (const violation of violations) {
+                console.error(`\n📄 ${violation.file}:`);
+                for (const message of violation.messages) {
+                    console.error(`   ${message.line}:${message.column} - ${message.message} (${message.ruleId})`);
+                }
+            }
+            process.exit(1);
+        }
+        else {
+            console.log("✅ No compatibility issues found!");
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`❌ Error: ${message}`);
+        process.exit(1);
+    }
+});
+// Parse command line arguments
+program.parse();

package/dist/lib/checkCompatiblity.js

@@ -0,0 +1,34 @@
+import { ESLint } from "eslint";
+import { createESLintConfig } from "./createESLintConfig.js";
+import { walkDir } from "./walkDir.js";
+export const checkCompatibility = async (config) => {
+    const jsFiles = walkDir(config.dir);
+    if (jsFiles.length === 0) {
+        console.log(`No JavaScript files found in directory: ${config.dir}`);
+        return [];
+    }
+    const eslint = new ESLint(createESLintConfig(config.target, config.browsers));
+    const violations = [];
+    for (const file of jsFiles) {
+        try {
+            const results = await eslint.lintFiles([file]);
+            if (Array.isArray(results)) {
+                for (const result of results) {
+                    if (result.messages.length > 0) {
+                        violations.push({
+                            file: result.filePath,
+                            messages: result.messages,
+                        });
+                    }
+                }
+            }
+            else {
+                console.warn(`Warning: ESLint did not return an array for file ${file}.`, results);
+            }
+        }
+        catch (error) {
+            console.warn(`Warning: Could not lint file ${file}:`, error);
+        }
+    }
+    return violations;
+};

package/dist/lib/createESLintConfig.js

@@ -0,0 +1,36 @@
+import compat from "eslint-plugin-compat";
+import { getBrowserTargetsFromString, parseEcmaVersion } from "./getBrowserTargets.js";
+import { isValidEcmaVersion } from "./isValidEcmaVersion.js";
+const getEcmaVersion = (target) => {
+    const ecmaVersion = parseEcmaVersion(target);
+    if (!isValidEcmaVersion(ecmaVersion)) {
+        throw new Error(`Invalid ECMAScript version: ${ecmaVersion}. Target year ${target} is not supported.`);
+    }
+    return ecmaVersion;
+};
+export const createESLintConfig = (target, browsers) => {
+    // Convert target year to ECMAScript version number using the validation function
+    const ecmaVersion = getEcmaVersion(target);
+    // Use provided browsers or auto-determine from target
+    const browserTargets = browsers || getBrowserTargetsFromString(target);
+    return {
+        overrideConfigFile: true,
+        overrideConfig: [
+            {
+                plugins: {
+                    compat,
+                },
+                rules: {
+                    "compat/compat": "error",
+                },
+                languageOptions: {
+                    ecmaVersion: ecmaVersion,
+                    sourceType: "module",
+                },
+                settings: {
+                    browsers: browserTargets,
+                },
+            },
+        ],
+    };
+};

package/dist/lib/getBrowserTargets.js

@@ -0,0 +1,79 @@
+/**
+ * Converts a string target to Linter.EcmaVersion type.
+ * Handles year format (2015), numeric format (6), and "latest".
+ * Returns null for unknown values to indicate they should use default.
+ */
+export const parseEcmaVersion = (target) => {
+    // Handle "latest"
+    if (target === "latest") {
+        return "latest";
+    }
+    const num = parseInt(target);
+    // Handle year format (2015, 2016, etc.)
+    if (num >= 2015 && num <= 2026) {
+        return num;
+    }
+    // Handle numeric format (3, 5, 6, 7, etc.)
+    if (num >= 3 && num <= 17) {
+        return num;
+    }
+    // For unknown values, return null to indicate default should be used
+    return null;
+};
+/**
+ * Maps ES target versions to appropriate browser targets for compatibility checking.
+ * This provides sensible defaults based on when ES features were widely supported.
+ */
+export const getBrowserTargets = (target) => {
+    switch (target) {
+        // Legacy versions
+        case 3:
+            return "> 0.1%, ie 6";
+        case 5:
+            return "> 0.5%, ie 8";
+        // ES2015 (ES6) - Conservative targets including IE11
+        case 6:
+        case 2015:
+            return "> 1%, last 2 versions, not dead, ie 11";
+        // ES2016-2017 (ES7-8) - Drop IE11 but keep other older browsers
+        case 7:
+        case 8:
+        case 2016:
+        case 2017:
+            return "> 1%, last 2 versions, not dead, not ie 11";
+        // ES2018-2019 (ES9-10) - More modern browsers
+        case 9:
+        case 10:
+        case 2018:
+        case 2019:
+            return "> 1%, last 2 versions, not dead, not ie 11, not op_mini all";
+        // ES2020+ (ES11+) - Latest browsers with good modern JS support
+        case 11:
+        case 12:
+        case 13:
+        case 14:
+        case 15:
+        case 16:
+        case 17:
+        case 2020:
+        case 2021:
+        case 2022:
+        case 2023:
+        case 2024:
+        case 2025:
+        case 2026:
+        case "latest":
+            return "> 1%, last 2 versions, not dead, not ie 11, not op_mini all, not android < 67";
+        // Default fallback for unknown versions
+        default:
+            return "> 1%, last 2 versions, not dead";
+    }
+};
+/**
+ * Convenience function that combines parsing and browser target determination.
+ * Accepts string input and returns appropriate browser targets.
+ */
+export const getBrowserTargetsFromString = (target) => {
+    const ecmaVersion = parseEcmaVersion(target);
+    return getBrowserTargets(ecmaVersion);
+};

package/dist/lib/isValidEcmaVersion.js

@@ -0,0 +1,13 @@
+const validVersions = new Set([
+    3, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025,
+    2026,
+]);
+export const isValidEcmaVersion = (ecmaVersion) => {
+    if (!ecmaVersion) {
+        return false;
+    }
+    if (typeof ecmaVersion === "string") {
+        return ecmaVersion === "latest";
+    }
+    return validVersions.has(ecmaVersion);
+};

package/dist/lib/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/validateConfig.js

@@ -0,0 +1,9 @@
+import * as fs from "fs";
+export const validateConfig = (config) => {
+    if (!fs.existsSync(config.dir)) {
+        throw new Error(`Output directory "${config.dir}" does not exist. Please build the project first.`);
+    }
+    if (!config.target) {
+        throw new Error("Target ES version is required");
+    }
+};

package/dist/lib/walkDir.js

@@ -0,0 +1,22 @@
+import * as fs from "fs";
+import * as path from "path";
+export const walkDir = (dir) => {
+    const files = [];
+    try {
+        const entries = fs.readdirSync(dir);
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry);
+            const stat = fs.statSync(fullPath);
+            if (stat.isDirectory()) {
+                files.push(...walkDir(fullPath));
+            }
+            else if (fullPath.endsWith(".js")) {
+                files.push(fullPath);
+            }
+        }
+    }
+    catch (error) {
+        console.warn(`Warning: Could not read directory ${dir}:`, error);
+    }
+    return files;
+};

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "es-guard",
+  "version": "1.0.0",
+  "description": "A tool to check JavaScript compatibility with target environments",
+  "type": "module",
+  "main": "dist/cli.js",
+  "bin": {
+    "es-guard": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js",
+    "test": "npm run build && vitest",
+    "test:run": "npm run build && vitest run",
+    "coverage": "vitest run --coverage",
+    "coverage:check": "vitest run --coverage --reporter=verbose",
+    "lint": "eslint src/**/*.ts",
+    "lint:check": "eslint src/**/*.ts --max-warnings 0",
+    "format": "prettier --write src/**/*.ts",
+    "format:check": "prettier --check src/**/*.ts",
+    "clean": "rimraf dist",
+    "prepublishOnly": "npm run clean && npm run build && npm run coverage:check",
+    "semantic-release": "semantic-release"
+  },
+  "keywords": [
+    "javascript",
+    "compatibility",
+    "eslint",
+    "browser-support",
+    "es2015",
+    "es2016",
+    "es2017",
+    "es2018",
+    "es2019",
+    "es2020"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@actions/core": "^1.11.1",
+    "commander": "^14.0.0",
+    "eslint": "^9.30.1",
+    "eslint-plugin-compat": "^6.0.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.30.1",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/eslint": "^9.6.1",
+    "@types/node": "^20.19.4",
+    "@typescript-eslint/eslint-plugin": "^8.35.1",
+    "@typescript-eslint/parser": "^8.35.1",
+    "@vitest/coverage-v8": "^3.2.4",
+    "prettier": "^3.6.2",
+    "rimraf": "^6.0.1",
+    "semantic-release": "^24.2.6",
+    "typescript": "5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mkayander/es-guard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mkayander/es-guard/issues"
+  },
+  "homepage": "https://github.com/mkayander/es-guard#readme",
+  "packageManager": "pnpm@10.12.4+sha512.5ea8b0deed94ed68691c9bad4c955492705c5eeb8a87ef86bc62c74a26b037b08ff9570f108b2e4dbd1dd1a9186fea925e527f141c648e85af45631074680184"
+}