fix(linting): single-export-per-file false positives on @fusionelement pattern

Fixes #5185

- Barrel exemption (index.ts/.tsx/.mts/.cts) now always applies, even when
  options.match overrides the matcher.
- A companion const/let (e.g. a tag string) that only parameterizes an
  export default class no longer counts as a competing export.

Author: odinr

.changeset/lint-rules_single-export-per-file-fusionelement.md

@@ -0,0 +1,8 @@
+---
+"@equinor/fusion-framework-lint-rules": patch
+---
+
+Fixed `single-export-per-file` false positives on the `@fusionElement` custom-element registration pattern:
+
+- Barrel files (`index.ts`, `index.tsx`, `index.mts`, `index.cts`) now stay exempt from the rule even when a repo's config overrides `options.match` — previously only the default (unconfigured) matcher included the barrel exemption.
+- A companion top-level `const`/`let` that only parameterizes an `export default class ... {}` (e.g. a `tag` string used by `@fusionElement(tag)`) no longer counts as a competing export.

packages/linting/rules/src/__tests__/single-export-per-file.test.ts

@@ -116,6 +116,36 @@ export function bar() {}
     // '.generated.ts' isn't in the exclude list, but the custom fn exempts it
     expect(lint(source, '/src/fixture.generated.ts', rule)).toHaveLength(0);
   });
+
+  it('passes: index.ts stays exempt even when options.match overrides the matcher', () => {
+    const rule = singleExportPerFile({ match: { exclude: ['barrel.ts'] } });
+    const source = `
+export function foo() {}
+export function bar() {}
+`;
+    expect(lint(source, '/src/index.ts', rule)).toHaveLength(0);
+  });
+
+  it('passes: export class Foo + export default Foo (default re-export, not a 2nd export)', () => {
+    const source = `
+export class Foo {}
+export default Foo;
+`;
+    expect(lint(source)).toHaveLength(0);
+  });
+
+  it('passes: companion const + export default class (fusionElement registration pattern)', () => {
+    const source = `
+import { fusionElement } from '@equinor/fusion-wc-core';
+import ButtonElement from './ButtonElement';
+
+export const tag = 'fwc-button';
+
+@fusionElement(tag)
+export default class _ extends ButtonElement {}
+`;
+    expect(lint(source)).toHaveLength(0);
+  });
 });
 
 // ── Failing cases ─────────────────────────────────────────────────────────────
@@ -151,4 +181,17 @@ export const DEFAULT_OPTIONS = {};
     expect(diags).toHaveLength(1);
     expect(diags[0]?.message).toContain('DEFAULT_OPTIONS');
   });
+
+  it('fails: companion const + export default class + a genuinely competing export', () => {
+    const source = `
+export const tag = 'fwc-button';
+export function helper() {}
+
+export default class _ {}
+`;
+    // the const is exempted, but 'helper' still genuinely competes with the default class
+    const diags = lint(source);
+    expect(diags).toHaveLength(1);
+    expect(diags[0]?.message).toContain('_');
+  });
 });

packages/linting/rules/src/single-export-per-file/index.ts

@@ -4,6 +4,7 @@ import type {
   Severity,
   RuleDef,
   LintContext,
+  MatcherFn,
 } from '@equinor/fusion-framework-lint-core';
 import { createMatcher, resolveMatch } from '@equinor/fusion-framework-lint-core';
 import { tsParser } from '../ts-parser.js';
@@ -43,10 +44,54 @@ function isValueExport(node: Node): boolean {
 }
 
 /**
- * Basename patterns exempted from this rule by default when `options.match`
- * is not provided. Barrel files legitimately re-export many symbols.
- * If `options.match` overrides this, the implementer must re-add any of
- * these patterns they still want exempted — the default list is not merged in.
+ * Returns `true` when a value export is `export default class ... {}` — the
+ * `@fusionElement` custom-element registration pattern's defining statement.
+ *
+ * @param node - A value-exporting `export_statement` AST node.
+ * @returns `true` if the statement is a default class export.
+ */
+function isDefaultClassExport(node: Node): boolean {
+  // A default export has a `default` keyword child
+  const hasDefaultKeyword = node.children.some((c) => c.type === 'default');
+  // ...and its declaration child is a class
+  const hasClassChild = node.children.some((c) => c.type === 'class_declaration');
+  return hasDefaultKeyword && hasClassChild;
+}
+
+/**
+ * Returns `true` when a value export is a top-level `const`/`let`/`var`
+ * declaration (as opposed to a function/class declaration).
+ *
+ * @param node - A value-exporting `export_statement` AST node.
+ * @returns `true` if the statement declares a const/let/var binding.
+ */
+function isConstOrLetExport(node: Node): boolean {
+  // const/let use lexical_declaration, var uses variable_declaration
+  return node.children.some((c) => c.type === 'lexical_declaration' || c.type === 'variable_declaration');
+}
+
+/**
+ * Filters `exports` down to the set that actually competes for the
+ * one-symbol budget: when a default class export (the `@fusionElement`
+ * registration pattern) is present, its companion const/let declarations
+ * (e.g. a `tag` string) are dropped since they only parameterize it.
+ *
+ * @param exports - All top-level value exports collected from a file.
+ * @returns The subset of `exports` that count toward the rule's limit.
+ */
+function competingExports(exports: readonly Node[]): Node[] {
+  // Whether the file has the @fusionElement default class registration pattern
+  const hasDefaultClassExport = exports.some(isDefaultClassExport);
+  // No default class export means every export competes as-is
+  if (!hasDefaultClassExport) return [...exports];
+  // Drop const/let companions so only the default class export remains
+  return exports.filter((node) => !isConstOrLetExport(node));
+}
+
+/**
+ * Basename patterns exempted from this rule, always applied in addition to
+ * any `options.match` override. Barrel files legitimately re-export many
+ * symbols, so they stay exempt regardless of how callers configure matching.
  */
 const DEFAULT_EXCLUDE = ['index.ts', 'index.tsx', 'index.mts', 'index.cts'];
 
@@ -57,15 +102,20 @@ const DEFAULT_EXCLUDE = ['index.ts', 'index.tsx', 'index.mts', 'index.cts'];
  * @returns A configured `Rule` instance.
  */
 export const singleExportPerFile: RuleDef = (options = {}) => {
-  const match = resolveMatch(options.match) ?? createMatcher([], DEFAULT_EXCLUDE);
+  const barrelMatch = createMatcher([], DEFAULT_EXCLUDE);
+  const overrideMatch = resolveMatch(options.match);
+  // Barrel files stay exempt even when `options.match` overrides the default matcher
+  const match: MatcherFn = overrideMatch
+    ? (filePath) => barrelMatch(filePath) && overrideMatch(filePath)
+    : barrelMatch;
 
   return {
     id: RULE_ID,
     defaultSeverity: DEFAULT_SEVERITY,
     /**
-     * Barrel files (`index.ts`, etc.) are exempt by default. Delegates to
+     * Barrel files (`index.ts`, etc.) are always exempt. Delegates to
      * `match` so the engine skips calling `check` for them entirely, and
-     * callers can override the matching strategy via `options.match`.
+     * callers can further narrow (not widen) matching via `options.match`.
      * @inheritdoc Rule.match
      */
     match,
@@ -76,13 +126,15 @@ export const singleExportPerFile: RuleDef = (options = {}) => {
       // Guard: tsParser.parse returns null for empty or unparseable source
       if (!tree) return [];
 
-      const valueExports: Node[] = [];
+      const allExports: Node[] = [];
       // Collect all top-level value export statements
       for (const child of tree.rootNode.children) {
         // Collect each top-level child that is a value export
-        if (isValueExport(child)) valueExports.push(child);
+        if (isValueExport(child)) allExports.push(child);
       }
 
+      const valueExports = competingExports(allExports);
+
       // Only flag when more than one value export exists
       if (valueExports.length <= 1) return [];