@nomercy-entertainment/eslint-plugin-player

The player trio (core, video, music) shares one code standard. This plugin makes the mechanical parts of that standard enforceable, so a violation fails lint at write time instead of surfacing in review weeks later. It encodes only the rules that a machine can judge without guessing. Naming intent, comment usefulness, and architecture stay with the code-quality reviewer.

Compatibility

These rules target the v2 player trio (the 2.0.x line of nomercy-player-core, nomercy-video-player, and nomercy-music-player). This package keeps its own version line rather than matching the trio, because the rules evolve on their own cadence: a version bump here means a rule changed, not that the player did. Pin it independently and read this note for the player line it tracks.

Rules

Every rule ships in the recommended preset at error.

| Rule | Catches | |------|---------| | player/no-single-letter-ident | Single-letter parameter and variable names. Allows x y z (maths) and i j k (loops). Covers interface method signatures and overloads, not just implementations. | | player/no-compat-vocab | The v1 factory names, the *StateToken types, the PlayerCore class, and compat markers in comments (@deprecated, "compatible alias", v1-compat). The v2 classes NMVideoPlayer and NMMusicPlayer stay allowed. | | player/no-history-comments | Bug-number history, spec citations (§), and naked TODO/FIXME with no issue reference. | | player/no-object-literal-cast | { ... } as SomeType. Type the object at construction instead. as const is exempt. | | player/no-unknown-cast | x as unknown as T with no adjacent comment. A short justification on the same line or the line above keeps a structurally forced cast legal. | | player/no-raw-player-bus | this.player.on/once/off/emit(...) inside a plugin. Bypasses scoping and auto-dispose; use the plugin's own this.on/once/off/emit. Only fires inside a class that extends Plugin — core mixins are untouched. | | player/no-raw-timers-in-plugin | Raw setTimeout/setInterval/requestAnimationFrame/addEventListener and new ResizeObserver/MutationObserver/IntersectionObserver/PerformanceObserver inside a plugin. No auto-cleanup; use this.timeout/interval/frame/listen and this.lifecycle.observe(new ResizeObserver(...)). | | player/no-raw-throw-in-plugin | throw new Error(...) (and other raw error ctors) inside a plugin. Skips the structured error surface; use this.throw({...}) or this.report({...}). Re-throwing a caught value is allowed. | | player/no-raw-fetch-in-plugin | The global fetch (bare, window.fetch, globalThis.fetch) inside a plugin. Sends no auth and never aborts on dispose; use this.fetch(url, options?) which runs the player's auth pipeline and aborts on teardown. A public URL that must not carry auth takes an eslint-disable with a reason. | | player/plugin-id-required | A concrete class extending Plugin with no own static id. Inheriting the base default 'plugin' collides and breaks storage/mount namespacing. abstract intermediate bases are exempt. |

Wiring

The trio configs consume it from the sibling package:

import player from '../eslint-plugin-player/index.js';

export default antfu({ /* ... */ }, {
  files: ['src/**/*.ts'],
  plugins: { player },
  rules: {
    'player/no-single-letter-ident': 'error',
    'player/no-compat-vocab': 'error',
    'player/no-history-comments': 'error',
    'player/no-object-literal-cast': 'error',
    'player/no-unknown-cast': 'error',
    'player/no-raw-player-bus': 'error',
    'player/no-raw-timers-in-plugin': 'error',
    'player/no-raw-throw-in-plugin': 'error',
    'player/no-raw-fetch-in-plugin': 'error',
    'player/plugin-id-required': 'error',
  },
}, {
  files: ['src/**/*.test.ts', 'src/__tests__/**/*.ts'],
  rules: {
    'player/no-object-literal-cast': 'off',
    'player/no-unknown-cast': 'off',
    'player/no-raw-throw-in-plugin': 'off',
    'player/no-raw-timers-in-plugin': 'off',
    'player/no-raw-player-bus': 'off',
    'player/no-raw-fetch-in-plugin': 'off',
    'player/plugin-id-required': 'off',
  },
});

Test files relax the two cast rules (mock construction legitimately casts) and the boundary rules (test-fixture plugins throw raw errors, use raw timers, fetch, and build ad-hoc plugin classes to drive the real paths).

The boundary rules

no-raw-player-bus, no-raw-timers-in-plugin, no-raw-throw-in-plugin, and no-raw-fetch-in-plugin are the mechanical half of the this-versus-this.player boundary: a plugin extends this and reaches the player through this.player, but its own lifecycle helpers (this.on, this.timeout, this.throw, this.fetch, this.lifecycle.observe, ...) are the sanctioned surface because they scope, auth, and auto-clean. Reaching past them to the raw player bus, raw timers or observers, a raw throw, or the global fetch leaks a listener/observer, drops an error off the structured path, or sends an unauthenticated request that never aborts on teardown. All fire only inside a class that extends Plugin, so core mixins — where this already is the player — never trigger them. A genuinely-needed exception (a third-party emitter that is not an EventTarget, a deliberate re-emit of a dynamically-named player event, a public URL that must not carry auth) takes an eslint-disable-next-line with a one-line reason, the same escape hatch no-unknown-cast uses.

Cross-file checks

Two things eslint cannot see (it lints one file at a time) ship as scripts for CI:

| Script | Asserts | |--------|---------| | scripts/check-package-exports.mjs | Every exports target resolves to a real file, and no subpath reaches into src/. | | scripts/check-duplicate-symbols.mjs | No exported constant, type, or enum is byte-identical in both video and music. Identical bodies are shared code that belongs in core. |

npm run check:exports
npm run check:duplicates

Tests

npm install
npm test