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 — link to GitHub issues
• ## Further Reading — optional; only include if you have a real, verifiable URL