CQA

Description

CQA is a TypeScript-focused code quality analyzer for projects that want stronger structure around types, JSDoc, imports, and a few safety-oriented code patterns.

It walks the TypeScript program for the project root you point it at, reads tsconfig.json, applies the configured rule set, and prints human-readable issue summaries or machine-readable output. It also includes a small set of autofix flows for selected rules so you can clean up common issues without editing every file by hand.

The tool is designed for codebases that want:

• consistent type declarations in a dedicated types/ area
• fewer anonymous or inline types in signatures
• stronger exported API documentation
• stricter handling of inferred variables and nullable unions
• optional SARIF or JSON output for CI and automation

The package is a CLI. After build, it exposes the cqa/cqa-ts command from the compiled dist output.

Install and Run

Requirements

• Node.js 20 or newer
• A TypeScript project with a valid tsconfig.json
• Preferably also a cqa.config.json

Install

npm install cqa-ts
npx cqa init

Build

The package compiles TypeScript to dist before use:

npm run build

Run locally

Run the analyzer against the current project root:

npx cqa .

You can also point it at a different root directory by modifying the JSON settings file.

Mode selection

The CLI supports three analysis modes:

• default mode: reports the configured default rule severities
• warnings mode: broadens enforcement to warning-level output
• strict mode: treats the strict preset as the active policy

Examples:

npx cqa . --warnings
npx cqa . --strict
npx cqa . --preset=ci
npx cqa . --preset=onboard

Output formats

You can change how results are emitted:

npx cqa . --json
npx cqa . --output cqa-report.json
npx cqa . --sarif cqa.sarif.json

• --json prints structured JSON to stdout
• --output writes a JSON issue report to a file
• --sarif writes a SARIF report suitable for CI and security tooling

Autofix flows

The analyzer can apply targeted fixes for a few rule families:

npx cqa . --fix-jsdoc
npx cqa . --fix-basic-types
npx cqa . --fix-explicit-types
npx cqa . --fix-narrow-types
npx cqa . --fix-nullable

Fix mode forces the run into the strict fixer preset, regardless of the selected mode or preset.

Available fixers:

• --fix-jsdoc inserts basic JSDoc stubs for exported functions and variables that are missing documentation
• --fix-basic-types adds obvious primitive annotations for simple inferred variables
• --fix-explicit-types adds explicit annotations for non-basic inferred variables when the type can be represented safely
• --fix-narrow-types turns unsafe JSON-like inferred payloads into guarded, narrowed code with validator inserts
• --fix-nullable replaces T | null unions with a shared Nullable<T> type and adds the import when needed [Note that this does introduce the Nullable<T> type into a types/ file if it doesn't exist]

Advanced JSDoc expansion is also available through:

npx cqa . --fix-jsdoc --fix-jsdoc-fill

That mode attempts to infer parameter names and emit @param stubs.

Pack / Create / Update

Pack

Build the package first, then create a tarball:

npm run build
npm pack

npm pack uses the files listed in package.json, which currently include:

• dist
• README.md
• LICENSE

The package already defines a prepack script, so npm pack will rebuild automatically before packaging.

Create

To create a new local installation for development, use one of these approaches:

npm install
npm run build

or, if you want the cqa command available globally on your machine while you iterate:

npm link

If you are creating a new project configuration, start by running npx cqa init and adjusting it for your repository layout.

The most important fields are:

• codeRoot: the folder to scan inside the repository
• settings: rule severities
• ignore: path substrings to skip
• presets: named rule bundles such as onboard, ci, strict, and warnings
• rules.clientOnlyImports: client-side import guards for server code

Update

When you change source code, rules, or configuration:

1. edit the relevant src/**/*.ts files or cqa.config.json
2. rerun npm run build
3. rerun npx cqa . against the target project
4. if you changed packaging metadata, rerun npm pack

If you are preparing a release version update, use the standard npm versioning flow:

npm version patch
npm version minor
npm version major

Then rebuild and repack so the generated dist output and tarball match the new version.

Features

Analysis

CQA builds a TypeScript program from the target project's tsconfig.json and analyzes source files in the configured root. It ignores common build and dependency directories such as node_modules, dist, build, .next, .git, .vercel, and coverage.

It can report issues for:

• type declarations outside the types/ area
• inline parameter and return types in functions
• inline object types in signatures
• missing JSDoc on exported APIs
• implicit return types on exported functions
• explicit type requirements for inferred variables
• duplicate or structurally redundant types
• union and utility types used outside the designated types area
• inline unions that already exist in /types
• any usage
• unsafe as unknown as casts
• client-only imports in server files
• console.log
• debugger
• nested or redundant type structures

Presets

The built-in presets are:

• onboard
• ci
• strict
• warnings

These presets adjust rule severities so you can use the same analyzer in a gentle onboarding mode, in CI, or in a much stricter enforcement setup.

Configuration

The analyzer reads cqa.config.json and supports:

• project-level rule settings
• path ignores
• named presets
• client-only import rules
• explicit type blacklists for files and type names

Reporting

CQA can emit:

• terminal summaries with file and rule counts
• machine-readable JSON
• SARIF for external tooling and code scanning pipelines

Autofix helpers

The fixer layer can insert:

• JSDoc scaffolding
• basic primitive type annotations
• explicit inferred types when they can be safely resolved
• Nullable<T> replacements for T | null
• narrow validators and guards for selected JSON-like payloads

Project conventions

The repository is published as an ES module package and exposes a cqa binary via package.json. The current package metadata targets Node.js 20 or newer and ships the compiled dist output rather than raw sources.

License

MIT License. See LICENSE for the full text.