Skip to content

Commit bf33ffa

Browse files
BioPhotonmatejchalk
BioPhoton
and
matejchalk
authored
feat(plugin-typescript): adjust logic (#975)
**This PR includes:** - docs - plugin exports - demo usage - @matejchalk any idea how we can use it best on our code? **Followup:** - #974 --------- Co-authored-by: Matěj Chalk <34691111+matejchalk@users.noreply.github.com>
1 parent b03db63 commit bf33ffa

File tree

8 files changed

+383
-0
lines changed

8 files changed

+383
-0
lines changed

‎code-pushup.config.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import {
66
jsDocsCoreConfig,
77
jsPackagesCoreConfig,
88
lighthouseCoreConfig,
9+
typescriptPluginConfigNx,
910
} from './code-pushup.preset.js';
1011
import type { CoreConfig } from './packages/models/src/index.js';
1112
import { mergeConfigs } from './packages/utils/src/index.js';
@@ -39,6 +40,9 @@ export default mergeConfigs(
3940
await lighthouseCoreConfig(
4041
'https://github.com/code-pushup/cli?tab=readme-ov-file#code-pushup-cli/',
4142
),
43+
await typescriptPluginConfigNx({
44+
tsconfig: 'packages/cli/tsconfig.lib.json',
45+
}),
4246
await eslintCoreConfigNx(),
4347
jsDocsCoreConfig([
4448
'packages/**/src/**/*.ts',

‎code-pushup.preset.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,11 @@ import { filterGroupsByOnlyAudits } from './packages/plugin-jsdocs/src/lib/utils
2121
import lighthousePlugin, {
2222
lighthouseGroupRef,
2323
} from './packages/plugin-lighthouse/src/index.js';
24+
import {
25+
type TypescriptPluginOptions,
26+
getCategories,
27+
typescriptPlugin,
28+
} from './packages/plugin-typescript/src/index.js';
2429

2530
export const jsPackagesCategories: CategoryConfig[] = [
2631
{
@@ -168,6 +173,13 @@ export const eslintCoreConfigNx = async (
168173
};
169174
};
170175

176+
export const typescriptPluginConfigNx = async (
177+
options?: TypescriptPluginOptions,
178+
): Promise<CoreConfig> => ({
179+
plugins: [await typescriptPlugin(options)],
180+
categories: getCategories(),
181+
});
182+
171183
export const coverageCoreConfigNx = async (
172184
projectName?: string,
173185
): Promise<CoreConfig> => {

‎packages/plugin-typescript/README.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# @code-pushup/typescript-plugin
2+
3+
[![npm](https://img.shields.io/npm/v/%40code-pushup%2Ftypescript-plugin.svg)](https://www.npmjs.com/package/@code-pushup/typescript-plugin)
4+
[![downloads](https://img.shields.io/npm/dm/%40code-pushup%2Ftypescript-plugin)](https://npmtrends.com/@code-pushup/typescript-plugin)
5+
[![dependencies](https://img.shields.io/librariesio/release/npm/%40code-pushup/typescript-plugin)](https://www.npmjs.com/package/@code-pushup/typescript-plugin?activeTab=dependencies)
6+
7+
🕵️ **Code PushUp plugin for measuring TypeScript quality with compiler diagnostics.** 🔥
8+
9+
This plugin allows you to **incrementally adopt strict compilation flags in TypeScript projects**.
10+
It analyzes your codebase using the TypeScript compiler to detect potential issues and configuration problems.
11+
12+
TypeScript compiler diagnostics are mapped to Code PushUp audits in the following way:
13+
14+
- `value`: The number of issues found for a specific TypeScript configuration option (e.g. 3)
15+
- `displayValue`: The number of issues found (e.g. "3 issues")
16+
- `score`: Binary scoring - 1 if no issues are found, 0 if any issues exist
17+
- Issues are mapped to audit details, containing:
18+
- Source file location
19+
- Error message from TypeScript compiler
20+
- Code reference where the issue was found
21+
22+
## Getting started
23+
24+
1. If you haven't already, install [@code-pushup/cli](../cli/README.md) and create a configuration file.
25+
26+
2. Install as a dev dependency with your package manager:
27+
28+
```sh
29+
npm install --save-dev @code-pushup/typescript-plugin
30+
```
31+
32+
```sh
33+
yarn add --dev @code-pushup/typescript-plugin
34+
```
35+
36+
```sh
37+
pnpm add --save-dev @code-pushup/typescript-plugin
38+
```
39+
40+
3. Add this plugin to the `plugins` array in your Code PushUp CLI config file (e.g. `code-pushup.config.ts`).
41+
42+
By default, a root `tsconfig.json` is used to compile your codebase. Based on those compiler options, the plugin will generate audits.
43+
44+
```ts
45+
import typescriptPlugin from '@code-pushup/typescript-plugin';
46+
47+
export default {
48+
// ...
49+
plugins: [
50+
// ...
51+
await typescriptPlugin(),
52+
],
53+
};
54+
```
55+
56+
4. Run the CLI with `npx code-pushup collect` and view or upload the report (refer to [CLI docs](../cli/README.md)).
57+
58+
## About TypeScript checks
59+
60+
The TypeScript plugin analyzes your codebase using the TypeScript compiler to identify potential issues and enforce best practices.
61+
It helps ensure type safety and maintainability of your TypeScript code.
62+
63+
The plugin provides multiple audits grouped into different sets:
64+
65+
- _Semantic Errors_: `semantic-errors` - Errors that occur during type checking and type inference
66+
- _Syntax Errors_: `syntax-errors` - Errors that occur during parsing and lexing of TypeScript source code
67+
- _Configuration Errors_: `configuration-errors` - Errors that occur when parsing TypeScript configuration files
68+
- _Declaration and Language Service Errors_: `declaration-and-language-service-errors` - Errors that occur during TypeScript language service operations
69+
- _Internal Errors_: `internal-errors` - Errors that occur during TypeScript internal operations
70+
- _No Implicit Any Errors_: `no-implicit-any-errors` - Errors related to `noImplicitAny` compiler option
71+
- _Unknown Codes_: `unknown-codes` - Errors that do not match any known TypeScript error code
72+
73+
Each audit:
74+
75+
- Checks for specific TypeScript compiler errors and warnings
76+
- Provides a score based on the number of issues found
77+
- Includes detailed error messages and locations
78+
79+
Each set is also available as group in the plugin. See more under [Audits and Groups](./docs/audits-and-groups.md).
80+
81+
## Plugin architecture
82+
83+
### Plugin configuration specification
84+
85+
The plugin accepts the following parameters:
86+
87+
| Option | Type | Default | Description |
88+
| ---------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
89+
| tsconfig | string | `tsconfig.json` | A string that defines the path to your `tsconfig.json` file |
90+
| 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 |
91+
92+
#### `tsconfig`
93+
94+
Optional parameter. The `tsconfig` option accepts a string that defines the path to your config file and defaults to `tsconfig.json`.
95+
96+
```js
97+
await typescriptPlugin({
98+
tsconfig: './tsconfig.json',
99+
});
100+
```
101+
102+
#### `onlyAudits`
103+
104+
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:
105+
106+
```js
107+
await typescriptPlugin({
108+
onlyAudits: ['no-implicit-any'],
109+
});
110+
```
111+
112+
### Optionally set up categories
113+
114+
Reference audits (or groups) which you wish to include in custom categories (use `npx code-pushup print-config` to list audits and groups).
115+
116+
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).
117+
118+
```ts
119+
// ...
120+
categories: [
121+
{
122+
slug: 'typescript',
123+
title: 'TypeScript',
124+
refs: [
125+
{
126+
type: 'audit',
127+
plugin: 'typescript',
128+
slug: 'semantic-errors',
129+
weight: 2,
130+
},
131+
{
132+
type: 'audit',
133+
plugin: 'typescript',
134+
slug: 'syntax-errors',
135+
weight: 1,
136+
},
137+
// ...
138+
],
139+
},
140+
// ...
141+
];
142+
```
143+
144+
Also groups can be used:
145+
146+
```ts
147+
// ...
148+
categories: [
149+
{
150+
slug: 'typescript',
151+
title: 'TypeScript',
152+
refs: [
153+
{
154+
slug: 'language-and-environment',
155+
weight: 1,
156+
type: 'group',
157+
plugin: 'typescript',
158+
},
159+
// ...
160+
],
161+
},
162+
// ...
163+
];
164+
```

‎packages/plugin-typescript/docs/audits-and-groups.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# 📚 Audits and Groups
2+
3+
The TypeScript plugin analyzes your codebase using the TypeScript compiler to identify potential issues and enforce best practices.
4+
5+
---
6+
7+
## 🛡️ Audits Overview
8+
9+
The plugin manages issues through structured audits and groups. Each audit targets a specific type of error, ensuring comprehensive analysis.
10+
11+
| **Audit** | **Slug** |
12+
| ------------------------------------------- | ----------------------------------------- |
13+
| **Semantic Errors** | `semantic-errors` |
14+
| **Syntax Errors** | `syntax-errors` |
15+
| **Configuration Errors** | `configuration-errors` |
16+
| **Declaration and Language Service Errors** | `declaration-and-language-service-errors` |
17+
| **Internal Errors** | `internal-errors` |
18+
| **No Implicit Any Errors** | `no-implicit-any-errors` |
19+
| **Unknown Codes** | `unknown-codes` |
20+
21+
---
22+
23+
### Semantic Errors - `semantic-errors`
24+
25+
Errors that occur during type checking and type inference.
26+
27+
- **Slug:** `semantic-errors`
28+
- **Title:** Semantic Errors
29+
- **Description:** Errors that occur during type checking and type inference.
30+
- **Scoring:** The score is based on the number of issues found.
31+
- **Value:** The value is the number of issues found.
32+
- **Display Value:** The display value is the number of issues found.
33+
34+
#### Issues
35+
36+
| Severity | Message | Source file | Line(s) |
37+
| :--------: | :----------------------------------------------------------------------------------- | :------------------------------------------------------------------------ | :-----: |
38+
| 🚨 _error_ | TS2307: Cannot find module './non-existent' or its corresponding type declarations. | [`path/to/module-resolution.ts`](../path/to/module-resolution.ts) | 2 |
39+
| 🚨 _error_ | TS2349: This expression is not callable.<br /> Type 'Number' has no call signatures. | [`path/to/strict-function-types.ts`](../path/to/strict-function-types.ts) | 3 |
40+
| 🚨 _error_ | TS2304: Cannot find name 'NonExistentType'. | [`path/to/cannot-find-module.ts`](../path/to/cannot-find-module.ts) | 1 |
41+
42+
---
43+
44+
### Syntax Errors - `syntax-errors`
45+
46+
Errors that occur during parsing and lexing of TypeScript source code.
47+
48+
- **Slug:** `syntax-errors`
49+
- **Title:** Syntax Errors
50+
- **Description:** Errors that occur during parsing and lexing of TypeScript source code.
51+
- **Scoring:** The score is based on the number of issues found.
52+
- **Value:** The value is the number of issues found.
53+
- **Display Value:** The display value is the number of issues found.
54+
55+
#### Issues
56+
57+
| Severity | Message | Source file | Line(s) |
58+
| :--------: | :------------------------------------ | :------------------------------------------------------ | :-----: |
59+
| 🚨 _error_ | TS1136: Property assignment expected. | [`path/to/syntax-error.ts`](../path/to/syntax-error.ts) | 1 |
60+
61+
---
62+
63+
### Configuration Errors - `configuration-errors`
64+
65+
Errors that occur when parsing TypeScript configuration files.
66+
67+
- **Slug:** `configuration-errors`
68+
- **Title:** Configuration Errors
69+
- **Description:** Errors that occur when parsing TypeScript configuration files.
70+
- **Scoring:** The score is based on the number of issues found.
71+
- **Value:** The value is the number of issues found.
72+
- **Display Value:** The display value is the number of issues found.
73+
74+
#### Issues
75+
76+
| Severity | Message | Source file | Line(s) |
77+
| :--------: | :----------------------------------------- | :-------------------------------------------------- | :-----: |
78+
| 🚨 _error_ | TS5023: Unknown compiler option 'invalid'. | [`path/to/tsconfig.json`](../path/to/tsconfig.json) | 1 |
79+
80+
---
81+
82+
### Declaration and Language Service Errors - `declaration-and-language-service-errors`
83+
84+
Errors that occur during TypeScript language service operations.
85+
86+
- **Slug:** `declaration-and-language-service-errors`
87+
- **Title:** Declaration and Language Service Errors
88+
- **Description:** Errors that occur during TypeScript language service operations.
89+
- **Scoring:** The score is based on the number of issues found.
90+
- **Value:** The value is the number of issues found.
91+
- **Display Value:** The display value is the number of issues found.
92+
93+
#### Issues
94+
95+
| Severity | Message | Source file | Line(s) |
96+
| :--------: | :------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------ | :-----: |
97+
| 🚨 _error_ | TS4112: This member cannot have an 'override' modifier because its containing class 'Standalone' does not extend another class. | [`path/to/incorrect-modifier.ts`](../path/to/incorrect-modifier.ts) | 2 |
98+
99+
---
100+
101+
### Internal Errors - `internal-errors`
102+
103+
Errors that occur during TypeScript internal operations.
104+
105+
- **Slug:** `internal-errors`
106+
- **Title:** Internal Errors
107+
- **Description:** Errors that occur during TypeScript internal operations.
108+
- **Scoring:** The score is based on the number of issues found.
109+
- **Value:** The value is the number of issues found.
110+
- **Display Value:** The display value is the number of issues found.
111+
112+
#### Issues
113+
114+
| Severity | Message | Source file | Line(s) |
115+
| :--------: | :------------------------------- | :---------------------------------------------------------- | :-----: |
116+
| 🚨 _error_ | TS9001: Internal compiler error. | [`path/to/internal-error.ts`](../path/to/internal-error.ts) | 4 |
117+
118+
---
119+
120+
### No Implicit Any Errors - `no-implicit-any-errors`
121+
122+
Errors related to no implicit any compiler option.
123+
124+
- **Slug:** `no-implicit-any-errors`
125+
- **Title:** No Implicit Any Errors
126+
- **Description:** Errors related to no implicit any compiler option.
127+
- **Scoring:** The score is based on the number of issues found.
128+
- **Value:** The value is the number of issues found.
129+
- **Display Value:** The display value is the number of issues found.
130+
131+
#### Issues
132+
133+
| Severity | Message | Source file | Line(s) |
134+
| :--------: | :-------------------------------------------------- | :------------------------------------------------------ | :-----: |
135+
| 🚨 _error_ | TS7006: Parameter 'x' implicitly has an 'any' type. | [`path/to/implicit-any.ts`](../path/to/implicit-any.ts) | 5 |
136+
137+
---
138+
139+
### Unknown Codes - `unknown-codes`
140+
141+
Errors that do not match any known TypeScript error code.
142+
143+
- **Slug:** `unknown-codes`
144+
- **Title:** Unknown Codes
145+
- **Description:** Errors that do not match any known TypeScript error code.
146+
- **Scoring:** The score is based on the number of issues found.
147+
- **Value:** The value is the number of issues found.
148+
- **Display Value:** The display value is the number of issues found.
149+
150+
#### Issues
151+
152+
| Severity | Message | Source file | Line(s) |
153+
| :--------: | :-------------------------------------- | :-------------------------------------------------------- | :-----: |
154+
| 🚨 _error_ | TS9999: Unknown error code encountered. | [`path/to/unknown-error.ts`](../path/to/unknown-error.ts) | 6 |
155+
156+
---
157+
158+
## 📂 Groups Overview
159+
160+
| **Group** | **Slug** |
161+
| ----------------- | ------------------ |
162+
| **Problems** | `problems` |
163+
| **Configuration** | `ts-configuration` |
164+
| **Miscellaneous** | `miscellaneous` |
165+
166+
### Problems - `problems`
167+
168+
- **Description:** Syntax, semantic, and internal compiler errors are critical for identifying and preventing bugs.
169+
- **References:**
170+
- Syntax Errors (`syntax-errors`)
171+
- Semantic Errors (`semantic-errors`)
172+
- No Implicit Any Errors (`no-implicit-any-errors`)
173+
174+
### Configuration - `ts-configuration`
175+
176+
- **Description:** Ensures correct TypeScript project setup, minimizing risks from misconfiguration.
177+
- **References:**
178+
- Configuration Errors (`configuration-errors`)
179+
180+
### Miscellaneous - `miscellaneous`
181+
182+
- **Description:** Informational errors that may not impact development directly but are helpful for deeper insights.
183+
- **References:**
184+
- Unknown Codes (`unknown-codes`)
185+
- Internal Errors (`internal-errors`)
186+
- Declaration and Language Service Errors (`declaration-and-language-service-errors`)

0 commit comments

Comments
 (0)