eslint-plugin-audience

ESLint rules that make a declaration's intended audience machine-readable and enforceable. A JSDoc tag on the declaration says who may use it. Importing it into a file whose allowed audiences do not intersect the declared ones is a lint error.

/**
 * @for batch
 */
export class RebuildSearchIndexUseCase { ... }

'RebuildSearchIndexUseCase' is for [batch]; this file allows [corporate, any-user].

Setup

pnpm add -D eslint-plugin-audience

Requirements

• ESLint ^10 with flat config
• @typescript-eslint/parser ^8 with type information enabled (projectService: true or project) for enforce-audience. declare-audience is syntactic and needs no type information.

The plugin contains no glob or path logic and no fixed vocabulary. Which files each rule applies to, the tag name, and the audience values all come from your flat config.

Rules

audience/declare-audience

Requires every exported declaration in the files it is scoped to, of the kinds listed in targets, to carry the audience tag with values from a configured vocabulary. Catches missing tags and typos. Direct export, export default, and export { X } of a local declaration are all covered. Purely syntactic. Needs no type information.

| Option | Type | Default | Description | | --- | --- | --- | --- | | tag | string | "for" | JSDoc tag name (without @). | | values | string[] | required | The audience vocabulary. Any other value is reported. | | targets | ("class" \| "function" \| "variable" \| "interface" \| "type" \| "enum")[] | ["class"] | Which exported declaration kinds must carry the tag. | | namePattern | string | all names | Regex. Only exported declarations whose name matches must carry the tag. Applies to every kind in targets. |

Two forms fall outside the rule. export { X } from "./other" is tagged in the file that declares X. export const { a } = obj has no one declaration for a tag to describe.

One JSDoc comment covers every name in the statement:

/** @for corporate */
export const FIRST = 1, SECOND = 2;

Message ids: missingTag, emptyTag, unknownAudience.

A tag may declare several audiences, separated by commas and/or whitespace, on the same line as the tag:

/** @for corporate, self-service */
export class SharedUseCase {}

audience/enforce-audience

For every value imported in the files it is scoped to, resolves the symbol through the TypeScript checker, following alias and re-export chains to the original declaration, so barrel files cannot launder a tagged symbol. If the declaration carries the tag, at least one declared audience must be in the file's allow list. Symbols without the tag are ignored, so third-party imports are not noise. Requires type information.

| Option | Type | Default | Description | | --- | --- | --- | --- | | tag | string | "for" | JSDoc tag name (without @). Must match declare-audience. | | allow | string[] | required | Audiences this file's app may use. | | checkTypeImports | boolean | false | Also check import type and inline type specifiers. Off by default because a type cannot be instantiated or injected. |

Message id: forbiddenAudience.

Namespace imports (import * as ns) are not checked.

Configuration

Scoping is done with flat-config files blocks: one block per app expresses that app's allowlist. Spread audience.configs.recommended into each block that needs a rule. The block's own rules key replaces the preset's entries.

The preset turns both rules on but supplies no options, and both rules require options. So a block that spreads the preset without configuring the rules it enables fails at config load instead of silently checking nothing:

Error: Key "rules": Key "audience/declare-audience": Value [] should NOT have fewer than 1 items.

That is also why the preset is spread per scoped block rather than once globally: an unscoped spread arms declare-audience on every file, including ones only the enforce-audience blocks configure, and the config fails to load.

// eslint.config.mjs
import { defineConfig } from "eslint/config";
import audience from "eslint-plugin-audience";

export default defineConfig([
  // ...your parser setup with projectService enabled...
  {
    ...audience.configs.recommended,
    files: ["libs/**/use-cases/**/*.ts"],
    rules: {
      "audience/declare-audience": [
        "error",
        {
          tag: "for",
          values: ["corporate", "self-service", "public", "batch", "any-user"],
          targets: ["class"],
          namePattern: "UseCase$",
        },
      ],
    },
  },
  {
    ...audience.configs.recommended,
    files: ["apps/self-service-gateway/**"],
    rules: {
      "audience/enforce-audience": [
        "error",
        { tag: "for", allow: ["self-service", "public", "any-user"] },
      ],
    },
  },
  {
    ...audience.configs.recommended,
    files: ["apps/corporate-gateway/**"],
    rules: {
      "audience/enforce-audience": [
        "error",
        { tag: "for", allow: ["corporate", "any-user"] },
      ],
    },
  },
  {
    ...audience.configs.recommended,
    files: ["apps/*-worker/**"],
    rules: {
      "audience/enforce-audience": [
        "error",
        { tag: "for", allow: ["batch"] },
      ],
    },
  },
]);

Files no block matches, such as apps/*-e2e/**, are never registered with the plugin and are not checked.

Notes

• Enforcement checks direct imports only. In codebases where wiring requires importing the class (for example NestJS with explicit @Inject(SomeClass) tokens and no decorator metadata), this is sufficient to catch miswiring.
• Audiences are compared by intersection: an import is allowed if any declared audience appears in the file's allow list.

Local development

pnpm install
pnpm test
pnpm build

To try the built plugin in another project before publishing, add to that project's package.json:

{
  "devDependencies": {
    "eslint-plugin-audience": "file:/path/to/this/repo"
  }
}

Then pnpm install in that project. After changes here, run pnpm build, then pnpm install again in the target project.

License

GPL-2.0-only