@samyrai/eslint-plugin-component-contracts

ESLint plugin for enforcing component-first JSX authoring with policy-driven component contracts.

Install

yarn add -D @samyrai/eslint-plugin-component-contracts

or

npm install -D @samyrai/eslint-plugin-component-contracts

Flat Config Usage

import { createComponentContractsConfig } from '@samyrai/eslint-plugin-component-contracts/config';

export default [
  ...createComponentContractsConfig({
    files: ['src/**/*.{ts,tsx,js,jsx}'],
    configPath: 'component-contracts.config.json',
    catalogPath: 'component-catalog.json',
    policyProfile: 'migration-default',
    minSuggestionConfidence: 0.75,
  }),
];

Preset Variants

import { flat } from '@samyrai/eslint-plugin-component-contracts/config';

export default [
  ...flat['recommended-warn'],
  // ...flat['recommended-error'],
  // ...flat['no-new-violations'],
];

Rules

• contracts/no-raw-html-in-features
• contracts/no-primitives-imports
• contracts/prefer-component-mapping
• contracts/no-layout-classes-on-box
• contracts/no-raw-motion-div-in-components
• contracts/no-typography-classes-on-layout-primitives
• contracts/prefer-semantic-layout-primitives
• contracts/prefer-text-component

Config Notes

• Config schema is v5 (breaking). Canonical fields only; legacy aliases were removed.
• zones.profiles[].priority is supported. Higher priority wins; on ties, the later profile wins.
• Primitive matcher canonical fields:
  • matchImportedNames
  • allowInZones
• Optional safe autofix target for no-primitives-imports:
  • primitiveImportRule.rewrite.barrelImportPath
  • Fixes apply only when imported names are statically resolvable from the barrel exports.

Schemas

• @samyrai/eslint-plugin-component-contracts/schemas/component-contracts.config.schema.json
• @samyrai/eslint-plugin-component-contracts/schemas/component-catalog.schema.json
• @samyrai/eslint-plugin-component-contracts/schemas/mapping-overrides.schema.json

Docs

• Architecture: https://github.com/SamyRai/html-to-components/blob/main/docs/architecture.md
• Implementation: https://github.com/SamyRai/html-to-components/blob/main/docs/component-contracts-implementation.md

ESLint 10 Stack Notes

• Verified maintained/supported pairings for ESLint 10:
  • @eslint-react/eslint-plugin (React + hooks + DOM/Web API strict presets)
  • eslint-plugin-unicorn
  • eslint-plugin-tailwindcss (flat/recommended runtime validated with ESLint 10)
• eslint-plugin-jsx-a11y does not currently declare ESLint 10 peer support, so strict a11y in this stack should come from @eslint-react DOM safety rules until official support lands.