Standardize module replacement data guidelines

[outslept]

This proposal introduces data guidelines following the mdn/browser-compat-data approach (https://github.com/mdn/browser-compat-data/tree/main/docs/data-guidelines) to standardize how module replacement data is recorded.

Files

docs/data-guidelines/overview (or index.md).md

# Data Guidelines

This folder contains guidelines to help you record module replacement data in a consistent and understandable way. It covers the project's requirements for how module replacements should be represented, including requirements that are not coded into the linter or schema.

This file contains general guidelines that apply to all replacement types. For guidelines that apply to specific types of data, check out their respective files within this folder:

- [Micro-utility replacements](./micro-utility.md)
- [Native replacements](./native.md)
- [Preferred replacements](./preferred.md)

## Choosing a replacement type

Use replacement types to reflect the **nature of the migration path** rather than the complexity of the original module.

The replacement type system provides a clear hierarchy for categorizing module replacements based on their migration characteristics. Use the most specific applicable type for recording replacement data.

### Type precedence

When a module could potentially fit multiple types, use this precedence order:

1. **`native` (Highest Priority):** If a module's functionality can be replaced by a **single, named, built-in API**, it **must** be categorized as `native`. This applies even if the replacement could be expressed as a simple one-liner.

2. **`simple` (micro-utility):** If a module cannot be categorized as `native` but its functionality can be replaced by a **short, self-contained JavaScript expression**, it should be categorized as `simple`.

3. **`documented` (preferred) (Lowest Priority):** If a module fits neither category above because its replacement requires **refactoring, API changes, or complex migration logic**, it should be categorized as `documented`.

### Runtime support requirements

Runtime support information is required for `native` types only:

- **`simple` & `documented`**: No runtime support needed (assumed universal)
- **`native`**: Must specify `nodeVersion` for Node.js support

## Choosing runtime versions

Use version numbers to reflect which **release line** (major or minor but not patch-level releases) first supported a feature, rather than absolute version numbers.

This project does not record absolute version numbers, such as Node.js 16.14.2; instead it records significant releases (such as Node.js 16.14.0). Use the earliest applicable release line for recording support for a given feature.

### Node.js versioning

For Node.js, use the exact semantic version format (`x.y.z`) of the earliest stable release that supports the feature:

Prefer Long-Term Support (LTS) version boundaries when the feature was introduced or stabilized in one.

## Module naming

Use the exact npm package name as it appears in the registry, including scope prefixes where applicable (e.g.):

- `"lodash"`
- `"@types/node"`
- `"@babel/core"`

## Behavioral equivalence standards

### For `simple` and `native` types

The replacement must cover the **primary, most common use case** of the original module. Perfect behavioral equivalence is not required if edge cases are obscure or rarely used.

If significant edge cases exist that are commonly encountered, they should be noted in the replacement text or the module should be recategorized as `documented`.

### For `documented` types

The replacement should provide equivalent or superior functionality, but may require API changes or refactoring. Breaking changes are acceptable and expected for this type.

## Removal of irrelevant entries

Entries can be removed from the project if they are considered irrelevant. An entry can be considered irrelevant if any of these conditions are met:

- The native replacement has been available in all active Node.js LTS versions for 2+ years
- The original module is abandoned, insecure, or has negligible ecosystem usage
- The replacement strategy is no longer considered best practice by the community
</details>

[outslept]

docs/data-guidelines/micro-utility.md

# Data guidelines for simple (micro-utility) replacements

This file contains guidelines specific to `type: "simple"` module replacements in the micro-utilities category.

## When to use `type: "simple"`

Use `type: "simple"` when a module's core functionality can be replaced by a **short, self-contained JavaScript expression**, even if the module handles obscure edge cases that the expression does not.

The goal of a `simple` replacement is to provide a "good enough" native alternative that covers the vast majority of common use cases, allowing developers to remove a dependency for everyday tasks.

This type is chosen only when a module cannot be categorized as `native`. Refer to the [main guidelines](./overview.md#type-precedence) for the rule of precedence.

### Criteria for `type: "simple"`

A module qualifies for this type when:

- It is not a polyfill for a single, named native API
- A native JavaScript expression can replace its **primary, most common use case**
- The replacement is simple, readable, and requires no additional dependencies
- The functionality is universally available across JavaScript runtimes

### Examples

- `is-windows`: Replaced by `process.platform === 'win32'`, which covers most cases but not specialized environments like Cygwin
- `is-string`: Replaced by `typeof str === 'string'`, which covers primitive strings but not `new String()` objects
- `split-lines`: Replaced by `str.split(/\r?\n/)`, which does not handle the `preserveNewlines` option

## Required fields for simple replacements

All `simple` entries must include the following fields:

- `type`: Must be `"simple"`
- `moduleName`: The exact npm package name
- `replacement`: An instructional string explaining the common-case replacement
- `category`: Must be `"micro-utilities"`

**Example:**

{
  "type": "simple",
  "moduleName": "is-windows",
  "replacement": "Use process.platform === 'win32'",
  "category": "micro-utilities"
}


## Field-specific guidelines

### `replacement`: Writing instructional text

The `replacement` text must be an instructional phrase starting with "Use". It should present the **most common, practical replacement**.

While the library might handle more edge cases, the `replacement` text should prioritize clarity and simplicity for the 99% use case. More complex, fully-equivalent replacements should be detailed in `documented` entries.

### Handling edge cases in `replacement`

For simple replacements, it is **not** required to provide a fully equivalent expression that covers every obscure edge case. The goal is to offer a pragmatic alternative.

However, if a very common and important edge case exists, it can be included:

- **Example:** `"Use v instanceof Date, or if cross-realm, use Object.prototype.toString.call(v) === '[object Date]'"`

Deciding whether an edge case is "common enough" is at the discretion of the maintainers. If the logic becomes too complex, the module should be categorized as `documented`.

## Runtime support

Simple replacements do not require `nodeVersion` fields, as they are assumed to work universally across JavaScript runtimes. The replacement expressions should use only standard JavaScript features available in all supported environments.

## What NOT to use `type: "simple"` for

### Fully equivalent but complex logic

Do not use `simple` if the only way to achieve full behavioral equivalence is with a complex, multi-part expression.

### Native API polyfills

Do not use `simple` for modules that are direct polyfills of a native API. These must be `type: "native"`.

### Runtime-specific functionality

Do not use `simple` for modules that depend on specific runtime features or APIs that are not universally available.

[outslept]

docs/data-guidelines/native.md

# Data guidelines for native replacements

This file contains guidelines specific to `type: "native"` module replacements.

## When to use `type: "native"`

Use `type: "native"` when a module's primary purpose is to polyfill or provide a named wrapper for a **single, specific, built-in API** in the JavaScript language or a JavaScript runtime.

If a module's functionality is provided by a native API, it **must** be categorized as `native`.

### Criteria for `type: "native"`

A module qualifies for this type when:

- It is a direct replacement for a named native feature (e.g., `object-assign` for `Object.assign`)
- The native API provides equivalent or superior functionality
- The native feature is stable in specific, verifiable versions of supported runtimes

### Examples

- `array-includes`: Replaced by the single API `Array.prototype.includes`

## Required fields for native replacements

All `native` entries must include the following fields:

- `type`: Must be `"native"`
- `moduleName`: The exact npm package name
- `replacement`: The canonical name of the native API
- `nodeVersion`: Node.js version when the feature became available
- `category`: Must be `"native"`
- `mdnPath`: A path to the relevant documentation (optional)

**Example:**

{
  "type": "native",
  "moduleName": "array-buffer-byte-length",
  "nodeVersion": "0.10.0",
  "replacement": "ArrayBuffer.prototype.byteLength",
  "mdnPath": "Global_Objects/ArrayBuffer/byteLength",
  "category": "native"
}

## Field-specific guidelines

### `replacement`: Naming the native API

The `replacement` text must be the **exact, canonical path** to the API. Do not add instructional words like "Use".

- **Static methods:** `Object.assign`, `Array.from`, `Buffer.isBuffer`
- **Instance methods:** `Array.prototype.includes`, `String.prototype.padStart`
- **Global functions/constructors:** `fetch`, `Promise`, `URL`

### `nodeVersion`: Specifying version support

The `nodeVersion` field must specify the earliest stable Node.js version that supports the feature.

- Use the exact semantic version format (`x.y.z`)
- Do not use ranges (`>=8.0.0`) or loose versions (`8.x`)
- Prefer Long-Term Support (LTS) version boundaries when the feature was introduced or stabilized
- Verify the version by checking official Node.js documentation changelogs

### `mdnPath`: Linking to documentation

Provide a direct link to the most relevant documentation page when available.

- **For standard JavaScript APIs:** Use the path relative to `https://developer.mozilla.org/docs/Web/JavaScript/Reference/`
  - Example: `"Global_Objects/Object/assign"`
- **For Node.js-specific APIs:** Use the path that best describes the API

## Runtime-specific considerations

### Universal JavaScript APIs

For APIs that are part of the JavaScript language specification (like `Object.assign`, `Array.prototype.includes`), the `nodeVersion` should reflect when Node.js first supported the feature.

### Node.js-specific APIs

For APIs that are specific to Node.js, specify the version when the API was introduced or stabilized.

[outslept]

docs/data-guidelines/preferred.md

# Data guidelines for documented (preferred) replacements

This file contains guidelines specific to `type: "documented"` module replacements in the preferred category.

## When to use `type: "documented"`

Use `type: "documented"` for modules where the migration path to a modern alternative is **non-trivial**. This type is the catch-all for any replacement that is too complex for `native` or `simple` types.

Refer to the [main guidelines](./overview.md#type-precedence) for the rule of precedence.

### Criteria for `type: "documented"`

A module qualifies for this type when the replacement involves one or more of the following:

- **Breaking API changes:** The replacement's API is significantly different (e.g., Promises vs. callbacks, different method names or signatures)
- **Complex logic:** A behaviorally identical native replacement would require complex, multi-line logic that is not suitable for a `simple` instruction
- **Conceptual shifts:** The migration involves changing the approach or design pattern (e.g., moving from a utility library like `lodash` to individual native methods)

### Examples

- `moment`: Migrating to a modern alternative like `Temporal` requires rewriting all date manipulations

## Required fields for documented replacements

All `documented` entries must include the following fields:

- `type`: Must be `"documented"`
- `moduleName`: The exact npm package name
- `docPath`: A path to the dedicated migration guide
- `category`: Must be `"preferred"`

**Example:**

{
  "type": "documented",
  "moduleName": "moment",
  "docPath": "moment-to-date-fns",
  "category": "preferred"
}

## Field-specific guidelines

### `docPath`: Linking to migration guides

The `docPath` field must be a relative path to the documentation file within the project, without the file extension.

## Documentation content requirements

When a `docPath` is provided, the corresponding migration document should be a comprehensive guide that includes:

... ?

## Runtime-specific considerations

### Cross-runtime compatibility

When the documented replacement works differently across runtimes, document these differences clearly in the migration guide.

### Runtime-specific alternatives

For modules that have different optimal replacements in different runtimes, choose the most universal approach or document the alternatives in the migration guide.