eslint-plugin-baseline-js 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 eslint-plugin-baseline-js contributors
+
+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,132 @@
+<div align="center">
+
+# eslint-plugin-baseline-js
+
+![baseline](./docs/assets/baseline-wordmark-dark.svg)
+
+Enforce the JavaScript Baseline (`widely` / `newly` / `year`) with a single ESLint rule powered by web‑features.
+This plugin delegates detection to eslint-plugin-es-x and ESLint core (plus a few small gap‑filling rules) and reports with one consistent Baseline message.
+
+<a href="https://github.com/3ru/eslint-plugin-baseline-js/actions/workflows/ci.yml">
+  <img alt="CI" src="https://img.shields.io/github/actions/workflow/status/3ru/eslint-plugin-baseline-js/ci.yml?label=CI&logo=github" />
+</a>
+<a href="https://github.com/3ru/eslint-plugin-baseline-js/actions/workflows/release.yml">
+  <img alt="Release" src="https://img.shields.io/github/actions/workflow/status/3ru/eslint-plugin-baseline-js/release.yml?label=release&logo=github" />
+</a>
+<img alt="License" src="https://img.shields.io/badge/license-MIT-blue" />
+
+</div>
+
+> [!WARNING]
+> Alpha testing: Behavior and options may change.
+> Questions or ideas? Please open an [issue](https://github.com/3ru/eslint-plugin-baseline-js/issues)
+
+
+## Install
+
+- npm: `npm i -D eslint-plugin-baseline-js`
+- pnpm: `pnpm add -D eslint-plugin-baseline-js`
+- yarn: `yarn add -D eslint-plugin-baseline-js`
+
+Recommended
+- ESLint >= 8.57 (Flat Config)
+
+## Quick Start (Flat Config)
+
+```js
+// eslint.config.js
+import baselineJs from "eslint-plugin-baseline-js";
+
+export default [
+  {
+    files: ["**/*.{js,ts,jsx,tsx}"],
+    plugins: { "baseline-js": baselineJs },
+    rules: {
+      // Allow only "widely available" Baseline features
+      "baseline-js/use-baseline": ["error", { baseline: "widely" }],
+    },
+  },
+];
+```
+
+## Common Configurations
+
+```js
+// Newly available (more permissive)
+'baseline-js/use-baseline': ['warn', { baseline: 'newly' }];
+
+// Year-based – allow features that became Baseline in or before 2020
+'baseline-js/use-baseline': ['error', { baseline: 2020 }];
+
+// Ignore knobs for pragmatic adoption
+'baseline-js/use-baseline': [
+  'error',
+  {
+    baseline: 2018,
+    // Skip specific web-features by ID (or regex as '/.../')
+    ignoreFeatures: ['nullish-coalescing', '/^optional-/'],
+    // Skip reports produced on certain ESTree node types
+    ignoreNodeTypes: ['WithStatement', '/Expression$/'],
+  },
+];
+
+// Turn off in tests or generated folders (ESLint standard overrides)
+export default [
+  { /* project defaults ... */ },
+  {
+    files: ['**/*.test.*', 'coverage/**'],
+    rules: { 'baseline-js/use-baseline': 'off' },
+  },
+];
+```
+
+## What Gets Reported?
+
+> Features from web‑features (group: `"javascript"`) that exceed your configured Baseline.
+
+| Baseline setting | Reports when...                     |
+| ---------------- | ----------------------------------- |
+| `"widely"`       | the feature is not in Baseline “high” |
+| `"newly"`        | the feature is marked as limited (`false`) |
+| `year` (number)  | the feature’s Baseline year is greater than `year` |
+
+## How It Works
+
+1. Data → `scripts/build-features.mjs`
+   - Extracts the minimal JavaScript subset from [`web‑features`](https://github.com/web-platform-dx/web-features) into `src/baseline/features.ts`.
+2. Mapping → `src/baseline/mapping.mjs`
+   - Maps web‑features IDs to underlying rules (prefer `eslint-plugin-es-x` / ESLint core; custom rules only when necessary).
+3. Resolution → `src/baseline/resolve.ts`
+   - Classifies “beyond baseline” by bucket (`high/low/false → widely/newly/limited`) or year.
+
+## Coverage
+
+We publish a generated coverage report that lists all JavaScript features from web‑features
+and shows which ones are currently mapped by this plugin.
+
+- Report: [docs/coverage.md](docs/coverage.md)
+- Regenerate locally: `pnpm gen:coverage`
+  - The release workflow also regenerates and commits this file.
+
+## Options (rule)
+
+| Option                 | Type                      | Default    | Description |
+| ---------------------- | ------------------------- | ---------- | ----------- |
+| `baseline`             | `widely`, `newly`, `number`, `widely` | Baseline level or year (alias: `available`). |
+| `ignoreFeatures`       | `string[]`                | —          | Skip specific web‑features by ID (supports regex `/.../`). |
+| `ignoreNodeTypes`      | `string[]`                | —          | Suppress reports by ESTree `node.type` (supports regex `/.../`). |
+
+## Baseline for HTML and CSS
+
+Baseline works best when HTML, CSS, and JS all align. For markup and styles, enable the "use-baseline" rules from these ESLint plugins:
+
+- ESLint for CSS: https://github.com/eslint/css
+- HTML ESLint: https://github.com/yeonjuan/html-eslint
+
+## Branding Note (Baseline)
+
+The Baseline name and logos are Google trademarks. Logo assets are licensed under CC BY‑ND 4.0. If you use Baseline logos alongside this plugin, please follow the [official guidelines](https://web-platform-dx.github.io/web-features/name-and-logo-usage-guidelines/) and do not imply sponsorship, affiliation, or endorsement by Google. We embed the official Baseline icons via their published URLs (unmodified).
+
+## License
+
+MIT