feat(linting): add require-property-tsdoc rule (#5189)

* feat(linting): add require-property-tsdoc rule

Adds a new fusion-lint rule requiring TSDoc comments on class field
declarations, including Lit @Property()/@State() decorated fields.
Private (accessibility modifier or #name) and static fields are
exempt. Supports a classScope option ('all' | 'exported') to limit
enforcement to exported classes. Included in the recommended preset.

* docs: add missing TSDoc on class fields flagged by require-property-tsdoc

Full-repo fusion-lint sweep after adding the new rule surfaced 13
pre-existing class fields without TSDoc. Documented each.

* fix(linting): support decorated get/set accessors in require-property-tsdoc

A decorated accessor's decorator is a sibling of the method_definition in
class_body, not nested inside it like a field's decorator is, so the
existing anchor logic and the public_field_definition-only node check both
missed it. Decorated get/set pairs (e.g. Lit's @Property()-decorated
getters) are now checked the same as decorated fields; undecorated
accessors remain out of scope.

Author: odinr

.changeset/require-property-tsdoc-doc-fixes.md

@@ -0,0 +1,13 @@
+---
+"@equinor/fusion-framework-cookbook-app-react-router": patch
+"@equinor/fusion-framework-module-app": patch
+"@equinor/fusion-framework-module-analytics": patch
+"@equinor/fusion-framework-module-azure-identity": patch
+"@equinor/fusion-framework-module-bookmark": patch
+"@equinor/fusion-framework-module-feature-flag": patch
+"@equinor/fusion-framework-module-http": patch
+"@equinor/fusion-framework-module-services": patch
+"@equinor/fusion-query": patch
+---
+
+Added missing TSDoc comments on class fields flagged by the new `require-property-tsdoc` fusion-lint rule.

.changeset/require-property-tsdoc.md

@@ -0,0 +1,6 @@
+---
+"@equinor/fusion-framework-lint-rules": minor
+"@equinor/fusion-framework-lint-config": minor
+---
+
+Add `require-property-tsdoc` rule: requires class field (property) declarations — including Lit's `@property()` / `@state()` decorated fields — to have a preceding TSDoc block comment. `private`/`#name` and `static` fields are exempt. Included in the `recommended` rule preset.

cookbooks/app-react-router/src/api/Api.ts

@@ -21,8 +21,11 @@ interface IHttpProvider {
  * Uses React Query for caching and request deduplication
  */
 export class Api {
+  /** Product-related API client. */
   readonly product: ProductApi;
+  /** People-related API client. */
   readonly people: PeopleApi;
+  /** User-related API client. */
   readonly user: UserApi;
 
   /**

packages/linting/config/src/recommended-rules.ts

@@ -15,6 +15,7 @@ import {
   singleExportPerFile,
   requireComponentTsDoc,
   requireHookTsDoc,
+  requirePropertyTsDoc,
   filenameConvention,
 } from '@equinor/fusion-framework-lint-rules';
 
@@ -41,5 +42,6 @@ export const recommendedRules: Rule[] = [
   singleExportPerFile(),
   requireComponentTsDoc(),
   requireHookTsDoc(),
+  requirePropertyTsDoc(),
   filenameConvention(),
 ];

packages/linting/rules/src/__tests__/require-property-tsdoc.test.ts

@@ -0,0 +1,168 @@
+import { describe, it, expect } from 'vitest';
+import { requirePropertyTsDoc } from '../require-property-tsdoc/index.js';
+import type { Diagnostic, Rule } from '@equinor/fusion-framework-lint-core';
+
+function lint(
+  source: string,
+  file = 'fixture.ts',
+  rule: Rule = requirePropertyTsDoc(),
+): Diagnostic[] {
+  // mirror the engine: skip `check` entirely when `match` opts the file out
+  if (rule.match && !rule.match(file)) return [];
+  return rule.check(source, { filePath: file });
+}
+
+describe('require-property-tsdoc — passing', () => {
+  it('passes: documented public field', () => {
+    const source = `
+class MyButton {
+  /** The visual color variant to render. */
+  color = 'primary';
+}
+`;
+    expect(lint(source)).toHaveLength(0);
+  });
+
+  it('passes: documented decorated field', () => {
+    const source = `
+class MyButton {
+  /** The visual color variant to render. */
+  @property({ type: String })
+  color = 'primary';
+}
+`;
+    expect(lint(source)).toHaveLength(0);
+  });
+
+  it('passes: private modifier field without TSDoc', () => {
+    const source = `
+class MyButton {
+  private internalState = 1;
+}
+`;
+    expect(lint(source)).toHaveLength(0);
+  });
+
+  it('passes: #private field without TSDoc', () => {
+    const source = `
+class MyButton {
+  #internalState = 1;
+}
+`;
+    expect(lint(source)).toHaveLength(0);
+  });
+
+  it('passes: static field without TSDoc', () => {
+    const source = `
+class MyButton {
+  static styles = [];
+}
+`;
+    expect(lint(source)).toHaveLength(0);
+  });
+
+  it('passes: field in non-exported class when classScope is "exported"', () => {
+    const rule = requirePropertyTsDoc({ classScope: 'exported' });
+    const source = `
+class MyButton {
+  color = 'primary';
+}
+`;
+    expect(lint(source, 'fixture.ts', rule)).toHaveLength(0);
+  });
+
+  it('passes: documented decorated getter accessor', () => {
+    const source = `
+class MyButton {
+  /**
+   * @deprecated use \`variant="contained"\` instead.
+   * @returns true when \`variant\` is \`contained\`
+   */
+  @property({ type: Boolean, reflect: true })
+  get raised(): boolean {
+    return this.variant === 'contained';
+  }
+}
+`;
+    expect(lint(source)).toHaveLength(0);
+  });
+
+  it('passes: undecorated getter accessor without TSDoc', () => {
+    const source = `
+class MyButton {
+  get raised(): boolean {
+    return this.variant === 'contained';
+  }
+}
+`;
+    expect(lint(source)).toHaveLength(0);
+  });
+});
+
+describe('require-property-tsdoc — failing', () => {
+  it('fails: undocumented public field', () => {
+    const source = `
+class MyButton {
+  color = 'primary';
+}
+`;
+    const diagnostics = lint(source);
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].message).toContain("'color'");
+  });
+
+  it('fails: undocumented decorated field', () => {
+    const source = `
+class MyButton {
+  @property({ type: String })
+  color = 'primary';
+}
+`;
+    const diagnostics = lint(source);
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].message).toContain("'color'");
+  });
+
+  it('fails: undocumented protected field', () => {
+    const source = `
+class MyButton {
+  protected color = 'primary';
+}
+`;
+    expect(lint(source)).toHaveLength(1);
+  });
+
+  it('fails: undocumented field in exported class when classScope is "exported"', () => {
+    const rule = requirePropertyTsDoc({ classScope: 'exported' });
+    const source = `
+export class MyButton {
+  color = 'primary';
+}
+`;
+    expect(lint(source, 'fixture.ts', rule)).toHaveLength(1);
+  });
+
+  it('fails: non-TSDoc comment does not satisfy the rule', () => {
+    const source = `
+class MyButton {
+  // just a regular comment
+  color = 'primary';
+}
+`;
+    expect(lint(source)).toHaveLength(1);
+  });
+
+  it('fails: undocumented decorated getter accessor', () => {
+    const source = `
+class MyButton {
+  @property({ type: Boolean, reflect: true })
+  get raised(): boolean {
+    return this.variant === 'contained';
+  }
+}
+`;
+    const diagnostics = lint(source);
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].message).toContain("'raised'");
+  });
+});

packages/linting/rules/src/index.ts

@@ -16,4 +16,6 @@ export { noSeparateExport } from './no-separate-export/index.js';
 export { singleExportPerFile } from './single-export-per-file/index.js';
 export { requireComponentTsDoc } from './require-component-tsdoc/index.js';
 export { requireHookTsDoc } from './require-hook-tsdoc/index.js';
+export { requirePropertyTsDoc } from './require-property-tsdoc/index.js';
+export type { RequirePropertyTsDocOptions } from './require-property-tsdoc/index.js';
 export { filenameConvention } from './filename-convention/index.js';