This document provides an overview of the automated code quality infrastructure in the TypeScript repository. It covers three primary systems: code formatting with dprint, code coverage measurement and reporting, and security scanning with CodeQL. These systems work together to ensure code consistency, track test coverage, and identify security vulnerabilities before code reaches production.
For specific details about each system's configuration and usage, see:
For information about how these tools are integrated into the CI pipeline, see Main CI Pipeline. </old_str> <new_str> For specific details about each system's configuration and usage, see:
For information about how these tools are integrated into the CI pipeline, see Main CI Pipeline.
The TypeScript repository enforces code quality through four automated systems that run in CI, with some also available locally:
| System | Tool | Configuration File(s) | Purpose |
|---|---|---|---|
| Formatting | dprint | .dprint.jsonc | Enforces consistent code style across TypeScript, JSON, and YAML files |
| Linting | ESLint + typescript-eslint + custom rules | scripts/eslint/ | Catches code-pattern issues, enforces naming conventions, detects unused code |
| Unused exports | Knip | (project-level config) | Identifies unused exports and dead code across the codebase |
| Coverage | c8 + monocart + Codecov | .c8rc.json, .github/codecov.yml | Measures test coverage and tracks changes in PRs |
| Security | CodeQL | .github/workflows/codeql.yml, .github/codeql/codeql-configuration.yml | Scans for security vulnerabilities |
| Supply chain | OpenSSF Scorecard | .github/workflows/scorecard.yml | Checks supply-chain security posture |
Each system contributes to the code quality gates enforced by CI before code can be merged.
Sources: .dprint.jsonc1-61 .c8rc.json1-8 .github/codecov.yml1-15 .github/workflows/codeql.yml1-74 .github/workflows/scorecard.yml1-60 package.json41-84
The following diagram maps each CI job to its tool, config file, and reporting destination.
Code Quality Systems — CI Jobs, Tools, and Config Files
Sources: .github/workflows/ci.yml166-210 .github/workflows/codeql.yml1-74 .github/workflows/scorecard.yml1-60 .dprint.jsonc1-61 .c8rc.json1-8 .github/codecov.yml1-15
ESLint is the primary linter, configured with typescript-eslint for type-aware rules. The repository also maintains a set of custom ESLint rules in scripts/eslint/rules/:
| Rule File | Purpose |
|---|---|
argument-trivia.cjs | Requires boolean arguments to be annotated with parameter name comments |
debug-assert.cjs | Enforces correct argument types to Debug.assert |
jsdoc-format.cjs | Validates @internal tag placement and JSDoc formatting |
no-in-operator.cjs | Bans the in operator (unsafe with Object.prototype modifications) |
no-keywords.cjs | Bans TypeScript keywords as variable/parameter names |
only-arrow-functions.cjs | Restricts use of traditional function expressions |
js-extensions.cjs | Enforces .js extensions on import paths |
Custom rules are tested separately in the misc CI job via hereby run-eslint-rules-tests, which runs mocha against scripts/eslint/tests.
Sources: scripts/eslint/rules/argument-trivia.cjs1-10 scripts/eslint/rules/debug-assert.cjs1-10 scripts/eslint/rules/jsdoc-format.cjs1-30 scripts/eslint/rules/no-in-operator.cjs1-15 scripts/eslint/rules/no-keywords.cjs1-15 scripts/eslint/rules/only-arrow-functions.cjs1-15 .github/workflows/ci.yml333-347
The knip job in ci.yml runs npm run knip (which executes hereby knip) to detect unused exports, files, and dependencies across the codebase. This is a separate CI job that runs on every PR and push to main or release-* branches.
Sources: .github/workflows/ci.yml179-191 package.json99
The .dprint.jsonc file configures the dprint formatter with language-specific rules:
| Setting | Value | Purpose |
|---|---|---|
indentWidth | 4 | Consistent indentation across files |
lineWidth | 1000 | Maximum line length before wrapping |
typescript.newLineKind | "crlf" | Windows-style line endings for TypeScript files |
typescript.semiColons | "always" | Require semicolons |
typescript.quoteStyle | "preferDouble" | Prefer double quotes for strings |
typescript.trailingCommas | "onlyMultiLine" | Add trailing commas only in multi-line expressions |
The configuration excludes several directories from formatting: node_modules, coverage, lib, built, tests, internal, and generated files .dprint.jsonc40-52
Sources: .dprint.jsonc3-31 .dprint.jsonc40-52
The .c8rc.json file configures c8 to measure code coverage:
Coverage collection works by setting the NODE_V8_COVERAGE environment variable to a temp directory before running tests, then running c8 report --experimental-monocart after. The --experimental-monocart flag enables monocart-coverage-reports for additional report formats. Coverage is collected from src/** and built/local/**.
Sources: .c8rc.json1-8 scripts/build/tests.mjs144-158
The .github/codecov.yml file configures the Codecov service integration:
| Setting | Value | Purpose |
|---|---|---|
comment | false | Disable automatic PR comments from Codecov bot |
coverage.precision | 5 | Report coverage to 5 decimal places |
status.patch.informational | true | Patch coverage check is informational only |
status.project.informational | true | Project coverage check is informational only |
github_checks.annotations | false | Disable line-by-line annotations |
Both patch and project coverage checks are informational, so they do not block PRs from merging. The upload uses OIDC authentication (use_oidc: true) when not running from a forked PR .github/workflows/ci.yml160-164
The coverage job runs on a self-hosted 1ES pool rather than ubuntu-latest because coverage collection is CPU-intensive .github/workflows/ci.yml135-138
Sources: .github/codecov.yml1-15 .github/workflows/ci.yml132-165
The following diagram shows how code quality checks are executed locally and in CI.
Code Quality Checks — Execution Sequence
Sources: .github/workflows/ci.yml166-210 .github/workflows/codeql.yml43-73 scripts/build/tests.mjs144-158 .c8rc.json1-8
Developers interact with code quality tools through the hereby task runner and npm scripts:
| Command | What it runs | Config read |
|---|---|---|
npm run format / hereby format | dprint fmt — reformats all files in place | .dprint.jsonc |
npx dprint check | Checks formatting without modifying files | .dprint.jsonc |
npm run lint / hereby lint | ESLint over src/ and scripts/ | ESLint config |
npm run knip / hereby knip | Knip unused exports scan | Knip config |
npm test -- --coverage | Tests with NODE_V8_COVERAGE + c8 report | .c8rc.json |
Sources: package.json89-102 .dprint.jsonc1-61 .c8rc.json1-8 scripts/build/tests.mjs44-60
In the CI pipeline (see Main CI Pipeline), each quality system runs as a separate job in ci.yml or its own workflow file:
| Job / Workflow | Tool | Trigger | Blocking |
|---|---|---|---|
format (ci.yml) | dprint | Every PR/push | Yes |
lint (ci.yml) | ESLint + custom rules | Every PR/push | Yes |
knip (ci.yml) | Knip | Every PR/push | Yes |
coverage (ci.yml) | c8 + monocart + Codecov | PR/push (not merge queue) | Informational only |
CodeQL-Build (codeql.yml) | CodeQL | PR/push + weekly schedule | Yes (security-events) |
analysis (scorecard.yml) | OpenSSF Scorecard | Push to main + weekly | Informational |
All of format, lint, knip are listed in the required job's needs array, so they block merging. Coverage is not in required .github/workflows/ci.yml416-438
Sources: .github/workflows/ci.yml166-438 .github/workflows/codeql.yml3-22 .github/workflows/scorecard.yml1-60 .github/codecov.yml6-11
The CodeQL security scanning workflow (codeql.yml) runs in three contexts:
main and release-* branches .github/workflows/codeql.yml4-7main and release-* branches .github/workflows/codeql.yml8-11cron: '30 1 * * 0') .github/workflows/codeql.yml22The CodeQL-Build job only runs on github.repository == 'microsoft/TypeScript' to prevent accidental execution on forks .github/workflows/codeql.yml37
The workflow consists of three steps:
github/codeql-action/init — initializes CodeQL with .github/codeql/codeql-configuration.yml .github/workflows/codeql.yml48-51github/codeql-action/autobuild — automatically builds the project .github/workflows/codeql.yml58-59github/codeql-action/analyze — performs analysis and uploads SARIF results to GitHub's Security tab .github/workflows/codeql.yml72-73The job requires security-events: write permission .github/workflows/codeql.yml39-41
The scorecard.yml workflow runs the ossf/scorecard-action to evaluate supply-chain security posture. It triggers on:
branch_protection_rule eventscron: '19 15 * * 4')mainResults are uploaded as SARIF to GitHub's code-scanning dashboard and published to the OpenSSF REST API to generate a public badge .github/workflows/scorecard.yml37-58
Sources: .github/workflows/codeql.yml1-74 .github/workflows/scorecard.yml1-60
The c8 tool generates reports in multiple formats simultaneously, controlled by .c8rc.json:
| Format | Consumer | Purpose |
|---|---|---|
lcovonly | Local developers / CI artifacts | LCOV format for tools like genhtml |
cobertura | CI systems | XML format parseable by many CI tools |
v8 | Debug/analysis | V8 engine native text format |
v8-json | Programmatic access | JSON dump of raw V8 coverage data |
codecov | Codecov service | JSON optimized for Codecov ingestion |
The mergeAsync: true option merges coverage data from parallel test workers before generating reports .c8rc.json6
The codecov-action upload step in CI reads coverage/codecov.json specifically .github/workflows/ci.yml160-164
Sources: .c8rc.json1-8 .github/workflows/ci.yml155-165
Each quality system defines its own exclusion patterns.
Files and directories excluded from formatting .dprint.jsonc40-52:
| Pattern | Reason |
|---|---|
**/.git | Git internal files |
**/node_modules | Dependencies |
**/*-lock.json | Lock files (e.g., package-lock.json) |
coverage/** | Generated coverage reports |
lib/** | LKG (Last Known Good) built library files |
built/** | Build output |
tests/** | Test case files |
internal/** | Internal tooling |
**/*.generated.* | Auto-generated source files |
**/_namespaces/** | Namespace barrel files |
Coverage includes src/** and built/local/**; excludes **/node_modules/** .c8rc.json3-5
Sources: .dprint.jsonc40-52 .c8rc.json3-5
The dprint formatter supports three languages through plugins .dprint.jsonc55-59:
typescript-0.93.4.wasm pluginjson-0.19.4.wasm pluging-plane/pretty_yaml-v0.5.0.wasm pluginEach plugin is loaded from https://plugins.dprint.dev/ and versioned independently. When updating TypeScript plugin version, the corresponding version in package.json must also be updated .dprint.jsonc54
The YAML plugin has special configuration with 2-space indentation and single quotes preferred .dprint.jsonc32-35
Sources: .dprint.jsonc32-59
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.