eslint-rule-development

Fiori ESLint Rule Developer

Add a new ESLint rule to @sap-ux/eslint-plugin-fiori-tools following the established patterns in the monorepo.

⚡ Efficiency rules — read before doing anything

1. Use the Read tool directly — never Bash cat or spawn Explore subagents for file reading
2. Read everything in one parallel batch — each fast path lists the exact files; read them all at once in a single turn
3. Run only the new test file during development — not the full package suite:

   NODE_OPTIONS="--experimental-vm-modules" npx jest --testPathPatterns="sap-[rule-name]" --no-coverage

Step 1 — Identify the rule type, then read the reference file

Infer from the request:

• Rule name — sap-[kebab-case-name] pattern
• OData version — V2 only, V4 only, or both
• Page scope — which page types to check. Default: all page types (list report, object page, etc.) unless the spec explicitly restricts the scope. Do not limit to one page type based on the examples in the spec.
• Auto-fix — yes/no
• Severity — error or warn. Rules in recommended-for-s4hana MUST be warn.

OData version determines the linker file — always follow the stated version:

Read the matching reference file immediately, then read all the files it lists in a single parallel batch. If the rule spans multiple types (e.g. annotations + manifest, or manifest + flex changes), read all matching reference files and combine their templates and access patterns.

Steps 2–10: Implementation Checklist

Step 2 — Add diagnostic constant (annotation, manifest JSON, and flex change rules only; skip for JS/TS rules)

In packages/eslint-plugin-fiori-tools/src/language/diagnostics.ts:

export const MY_RULE = 'sap-my-new-rule';
 
export interface MyRuleDiagnostic {
    type: typeof MY_RULE;
    // ... fields from the reference file's "Required diagnostic fields" table
}
 
// Add MyRuleDiagnostic to the Diagnostic union at the bottom

Step 3 — Implement the rule

Use the template from the reference file for your rule type.

Code quality requirements for every new or modified function:

• JSDoc — add a JSDoc block (@param, @returns) to every new function. When modifying an existing function, update its JSDoc to reflect any signature or behaviour changes.
• Cognitive complexity ≤ 15 — enforced by sonarjs/cognitive-complexity. If a function exceeds 15, extract branches or loops into well-named helper functions until the complexity falls within the limit. Do not inline complex logic in a single function to avoid this.
• Backtick code indicators in messages — in rule warning messages, wrap all code-like values in backticks: property names, annotation names, property values, entity names, and any other identifier that appears verbatim in source. Plain prose words stay unquoted.

  // ✅ Correct — code values in backticks
  message: "The `UI.LineItem` annotation is missing the required `Criticality` property."

Step 4 — Register the rule

src/rules/index.ts — add import + entry (alphabetical order):

import sapMyNewRule from './sap-my-new-rule.js';
// ...
[MY_RULE]: sapMyNewRule,

src/index.ts — add to fioriLanguageConfig rules (Fiori language rules) or baseFioriToolsRules (JS/TS rules):

'@sap-ux/fiori-tools/sap-my-new-rule': 'warn',

If the rule should also apply to S/4HANA projects, add it to the recommended-for-s4hana config in src/index.ts as well. Rules in this config must use 'warn' severity:

// In the recommended-for-s4hana config rules object:
'@sap-ux/fiori-tools/sap-my-new-rule': 'warn',

Step 5 — Write tests

Use the test template from the reference file; run only the new test file (see efficiency rules at the top).

Always check message, never messageId, in errors arrays. When a rule message contains interpolated data (e.g. {{tableType}}), checking only messageId would accept any value for that placeholder and miss regressions. Use the fully resolved string instead:

// ✅ Correct — verifies the interpolated value
errors: [
    {
        message:
            '"TreeTable" is not supported in the flexible column layout with a draft-enabled service.'
    }
]
 
// ❌ Wrong — does not verify the data interpolated into the message
errors: [{ messageId: 'sap-my-new-rule' }]

If tests show 0 errors when violations are expected, check the debug checklist at the bottom of the reference file.

Step 6 — Write documentation

Create packages/eslint-plugin-fiori-tools/docs/rules/sap-[rule-name].md. Read packages/eslint-plugin-fiori-tools/docs/rules/TEMPLATE.md for structure. Key sections:

• H1 title — one sentence describing the rule, with the rule ID in parentheses
• Intro paragraph — 2–3 sentences: what it detects, why it was introduced (motivation belongs here, not in a separate H2), and what to do instead
• ## Rule Details — how the rule works; warning message; "The following patterns are considered warnings:" + "The following patterns are not considered warnings" code examples
• ### How to Fix — steps to remediate (omit if obvious from the examples)
• ## False Positives — optional; include only if the rule can produce false positives
• ## Bug Report — use this exact text:

  ## Bug Report
   
  If you detect an issue with the check, open a [GitHub issue](https://github.com/SAP/open-ux-tools/issues).
• ## Further Reading — optional; only include if you have a real, verifiable URL

Step 7 — Update README

In packages/eslint-plugin-fiori-tools/README.md, do two things:

1. Add your new rule at the top of the rules table with new in the version column:

   |  new  | [sap-my-new-rule](docs/rules/sap-my-new-rule.md) | Short description | | ✅ |

2. Backfill any pending new versions: if any rows still show new from prior rule additions that have since been released, look up each rule's release version in packages/eslint-plugin-fiori-tools/CHANGELOG.md and replace new with that version. After this cleanup, your newly added rule should be the only row showing new.

Step 8 — Run full quality gates (once)

Run lint:fix to auto-fix ESLint errors and apply Prettier formatting across all modified files, then verify no issues remain:

# Fix lint errors and apply Prettier formatting
pnpm --filter @sap-ux/eslint-plugin-fiori-tools lint:fix
 
# Verify no remaining issues
pnpm --filter @sap-ux/eslint-plugin-fiori-tools lint

If lint reports errors after lint:fix:

• sonarjs/cognitive-complexity — resolve per the cognitive complexity guidance in Step 3.
• prettier/prettier — a formatting issue could not be auto-fixed. Apply the suggested change manually (usually a line that is too long or a multiline expression that needs restructuring).
• @typescript-eslint/no-unsafe-* — replace any casts or untyped values with proper interfaces or unknown + type guards.

Do not proceed to Step 9 until pnpm lint exits with code 0.

Then confirm all tests still pass:

pnpm --filter @sap-ux/eslint-plugin-fiori-tools test

Step 9 — Create changeset

pnpm cset

Select @sap-ux/eslint-plugin-fiori-tools, choose minor for new rules:

FEAT: add sap-my-new-rule rule for [short description]

Step 10 — Report

Summarize what was done:

• Rule name and type — rule ID and which type (annotation / manifest JSON / flex change / JS/TS)
• Files created — rule implementation, test file, doc file
• Files modified — diagnostics.ts, rules/index.ts, src/index.ts, README.md
• Test results — number of valid and invalid cases, all passing
• Changeset — package, bump type (minor), summary line

Quick Reference: Key Files

check() context access by rule type