New Rule: `no-meta-schema-mismatch`

[bmish]

no-meta-schema-mismatch would report statically provable inconsistencies between a rule’s meta.schema, meta.defaultOptions, and its implementation.

PR #648 separates schema analysis into:

• no-incorrect-meta-schema: objective defects intrinsic to the schema.
• no-incomplete-meta-schema: opinionated completeness improvements.

no-meta-schema-mismatch would cover the third category: schemas that are valid internally but disagree with the defaults or implementation.

ESLint validates configured options against meta.schema, but it does not prove that the implementation and defaults agree with that schema. These problems may remain hidden until a user supplies a particular option, and may result in dead behavior or runtime errors.

Candidate checks

• Invalid default options: statically known meta.defaultOptions values are rejected by meta.schema.
• Unreachable option positions: the implementation reads or destructures context.options[n], but the schema cannot permit that position.
• Impossible option properties: the implementation reads a property that cannot exist under a statically resolvable closed object schema.
• Excluded option values: the implementation explicitly handles a literal value that the schema cannot accept.

For example:

module.exports = {
  meta: {
    schema: [{ type: 'string' }],
    defaultOptions: [123],
  },
  create(context) {
    const secondOption = context.options[1];
    // Neither the numeric default nor the second option agrees with the schema.
  },
};

Relationship to existing rules

Existing rules validate individual pieces of rule metadata, while no-meta-schema-mismatch would validate the relationships between them:

• require-meta-schema owns schema presence and type, and already reports any context.options usage when the schema permits no options. no-meta-schema-mismatch would handle more specific implementation mismatches when a non-empty schema exists.
• require-meta-default-options owns whether meta.defaultOptions exists and has the required basic structure. no-meta-schema-mismatch would check whether the default values themselves are accepted by meta.schema.
• no-meta-schema-default disallows the JSON Schema default keyword in favor of meta.defaultOptions; it does not compare defaults with the schema.
• require-meta-schema-description requires descriptions for rule options; it does not check schema behavior or implementation consistency.
• no-incorrect-meta-schema would report defects intrinsic to the schema, while no-incomplete-meta-schema would report opinionated completeness improvements. no-meta-schema-mismatch would be limited to cross-artifact mismatches.

Whether to fold these checks into existing rules

The invalid-default-options check could reasonably be added to require-meta-default-options, and the no-options case for unreachable accesses already belongs to require-meta-schema. However, the broader implementation checks do not fit either rule’s current responsibility.

Keeping the cross-artifact checks in no-meta-schema-mismatch has a few advantages:

• It keeps presence and basic-shape rules separate from semantic consistency checks.
• It avoids adding new diagnostics directly to existing recommended rules.
• It gives all schema/default/implementation consistency checks one configurable home.

If the proposal were narrowed to validating only meta.defaultOptions against meta.schema, extending require-meta-default-options would likely be preferable to adding a new rule. With the broader implementation-consistency scope proposed here, a separate rule is clearer.

Safety and scope

no-meta-schema-mismatch should report only mismatches it can prove statically. It should fail open for dynamic schemas, computed option access, unresolved references, or complex implementation flows.

It should not attempt to infer arbitrary types from implementation behavior—for example, assuming an option is an array because the implementation calls .map(). Such checks would be heuristic and could be considered separately as opt-in checks.

Each check should be individually configurable through a named checks option so future checks can be introduced default-off.

no-meta-schema-mismatch should initially be unrecommended. After corpus testing confirms that its default checks are objective and low-noise, it could be considered for recommended.