css-noop-checker: Instructions file for Codex

AI Agent Instructions

Human contributors: see CONTRIBUTING.md for the full contributor guide.

This file provides context for AI coding agents (Cursor, Copilot, Windsurf, etc.) working in this repository.

Project Structure

src/
  rules/           Detection rules + engine, registry, context, types
  sidebar/         DevTools sidebar React UI (see src/sidebar/ for details)
  devtools.ts      Extension entrypoint — creates the sidebar pane
e2e/
  helpers/         Playwright extraction helpers (shared with MCP server)
  integration/     Browser integration tests against examples/test.html
mcp-server/        Standalone MCP server (separate package.json, pnpm workspace)
examples/
  test.html        Test cases for all rules — used by both manual testing and e2e
public/
  manifest.json    Chrome extension manifest (MV3)

Adding a New Rule

This is the most common type of contribution. Follow these steps:

1. Create the rule file

Add src/rules/<target>-no-<qualifier>.ts. The filename is the rule ID.

Rule IDs follow Stylelint's thing-no-qualifier convention (e.g. inline-no-dimensions, container-no-gap).

import type { RuleContext, Warning } from './types.ts';
import { registerRule } from './registry.ts';

registerRule({
  id: '<target>-no-<qualifier>',
  label: '<short human-readable description>',
  requiredProperties: ['<css-prop-1>', '<css-prop-2>'],
  // requiredParentProperties: [],  // optional, if parent styles are needed
  check(ctx: RuleContext): Warning[] {
    // Return warnings for properties that have no effect
    return [];
  },
});

2. Register in engine.ts

Add a side-effect import at the top of src/rules/engine.ts (keep alphabetical order):

import './<target>-no-<qualifier>.ts';

3. Add test cases to examples/test.html

Add both "should warn" and "should NOT warn" cases. Sections are ordered alphabetically by rule ID.

<!-- should warn -->
<div class="case expect-warn" data-rule="<rule-id>">
  <div class="label label-warn"><rule-id> warn: description</div>
  <div data-target style="...">example</div>
</div>

<!-- should NOT warn -->
<div class="case expect-ok" data-rule="<rule-id>">
  <div class="label label-ok"><rule-id> ok: description</div>
  <div data-target style="...">example</div>
</div>