@code-pushup/typescript-plugin

🕵️ Code PushUp plugin for measuring TypeScript quality with compiler diagnostics. 🔥

This plugin allows you to incrementally adopt strict compilation flags in TypeScript projects. It analyzes your codebase using the TypeScript compiler to detect potential issues and configuration problems.

TypeScript compiler diagnostics are mapped to Code PushUp audits in the following way:

• value: The number of issues found for a specific TypeScript configuration option (e.g. 3)
• displayValue: The number of issues found (e.g. "3 issues")
• score: Binary scoring - 1 if no issues are found, 0 if any issues exist
• Issues are mapped to audit details, containing:
  • Source file location
  • Error message from TypeScript compiler
  • Code reference where the issue was found

Getting started

1. If you haven't already, install @code-pushup/cli and create a configuration file.

2. Install as a dev dependency with your package manager:

   npm install --save-dev @code-pushup/typescript-plugin

   yarn add --dev @code-pushup/typescript-plugin

   pnpm add --save-dev @code-pushup/typescript-plugin

3. Add this plugin to the plugins array in your Code PushUp CLI config file (e.g. code-pushup.config.ts).

   By default, a root tsconfig.json is used to compile your codebase. Based on those compiler options, the plugin will generate audits.

   import typescriptPlugin from '@code-pushup/typescript-plugin';
   
   export default {
     // ...
     plugins: [
       // ...
       typescriptPlugin(),
     ],
   };

4. Run the CLI with npx code-pushup collect and view or upload the report (refer to CLI docs).

About TypeScript checks

The TypeScript plugin analyzes your codebase using the TypeScript compiler to identify potential issues and enforce best practices. It helps ensure type safety and maintainability of your TypeScript code.

The plugin provides multiple audits grouped into different sets:

• Semantic Errors: semantic-errors - Errors that occur during type checking and type inference
• Syntax Errors: syntax-errors - Errors that occur during parsing and lexing of TypeScript source code
• Configuration Errors: configuration-errors - Errors that occur when parsing TypeScript configuration files
• Declaration and Language Service Errors: declaration-and-language-service-errors - Errors that occur during TypeScript language service operations
• Internal Errors: internal-errors - Errors that occur during TypeScript internal operations
• No Implicit Any Errors: no-implicit-any-errors - Errors related to noImplicitAny compiler option
• Unknown Codes: unknown-codes - Errors that do not match any known TypeScript error code

Each audit:

• Checks for specific TypeScript compiler errors and warnings
• Provides a score based on the number of issues found
• Includes detailed error messages and locations

Each set is also available as group in the plugin. See more under Audits and Groups.

Plugin architecture

Plugin configuration specification

The plugin accepts the following parameters:

| Option | Type | Default | Description | | ---------- | ------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | tsconfig | string | string[] | tsconfig.json | Path(s) to your tsconfig.json file(s) | | onlyAudits | string[] | undefined | An array of audit slugs to specify which documentation types you want to measure. Only the specified audits will be included in the results |

tsconfig

Optional parameter. The tsconfig option accepts a path or an array of paths to your config files. Defaults to tsconfig.json.

typescriptPlugin({
  tsconfig: './tsconfig.json',
});

You can also provide multiple tsconfigs to combine results from different configurations (e.g., separate configs for source and test files):

typescriptPlugin({
  tsconfig: ['./tsconfig.lib.json', './tsconfig.spec.json'],
});

If you're using an Nx monorepo, a helper function is provided to auto-discover tsconfigs from all projects:

import typescriptPlugin, { tsconfigFromAllNxProjects } from '@code-pushup/typescript-plugin';

export default {
  plugins: [
    await typescriptPlugin({
      tsconfig: await tsconfigFromAllNxProjects(),
    }),
  ],
};

You can exclude specific projects by name:

await tsconfigFromAllNxProjects({ exclude: ['my-app-e2e'] });

onlyAudits

The onlyAudits option allows you to specify which documentation types you want to measure. Only the specified audits will be included in the results. All audits are included by default. Example:

typescriptPlugin({
  onlyAudits: ['no-implicit-any'],
});

Optionally set up categories

Reference audits (or groups) which you wish to include in custom categories (use npx code-pushup print-config to list audits and groups).

Assign weights based on what influence each TypeScript checks should have on the overall category score (assign weight 0 to only include as extra info, without influencing category score).

// ...
categories: [
  {
    slug: 'typescript',
    title: 'TypeScript',
    refs: [
      {
        type: 'audit',
        plugin: 'typescript',
        slug: 'semantic-errors',
        weight: 2,
      },
      {
        type: 'audit',
        plugin: 'typescript',
        slug: 'syntax-errors',
        weight: 1,
      },
      // ...
    ],
  },
  // ...
];

Also groups can be used:

// ...
categories: [
  {
    slug: 'typescript',
    title: 'TypeScript',
    refs: [
      {
        slug: 'problems',
        weight: 1,
        type: 'group',
        plugin: 'typescript',
      },
      // ...
    ],
  },
  // ...
];