README.md
README.md is a file in GovLab Quality. 137 lines of code and 0 definitions.
<!-- Auto-generated 2026-09-29T00:21Z v8 -->
# @govlab/quality
<!-- concern:overview -->
## Purpose
The single code-quality module for the workspace, spanning every face of one concern. Rules: the custom `eslint` and `stylelint` plugins, and the `context-lint` gates. Catalog: the ecosystem quality-rule catalog, the concern emitters (`emitEslintConfig`, `emitStylelintConfig`, `emitPrettierConfig`) that resolve one `qualityMaster.concerns` map into every tool's rules, and the install registry that maps each tool to its package, plugin namespace, and config target. Engine: the language-agnostic engine that resolves a canonical policy into a per-ecosystem check plan and a machine-derived verdict. Config: the consumer-config framework that loads one `govlab.config` and adapts each section into its face. Install: the one-command installer for the hardened tool and plugin chain per ecosystem. Run: the meta-linter runner that detects a project's ecosystems, assembles each tool's config in memory, runs the tools themselves, and reports in one shape.
<!-- /concern:overview -->
<!-- concern:use -->
## When to use
- You want one command that lints a whole codebase across every ecosystem it contains, with each tool's config built from one `govlab.config`.
- You want a single source of truth for quality rules, thresholds, and tool wiring, with per-rule opt-out through a concern map.
- You want to drop a governed quality baseline into a new codebase by copying one module and running one install command.
## When NOT to use
- As a general-purpose task runner. It detects, configures and runs quality tools, nothing more.
- When a project wants each linter configured by hand in its own native config file instead of from one central source.
<!-- /concern:use -->
<!-- concern:charts -->
## Architecture charts
The structure, logical-flow and dependency diagrams derived from the source AST live in [_code.info.generated/mermaid-charts.generated.md](./_code.info.generated/mermaid-charts.generated.md).
<!-- /concern:charts -->
<!-- concern:install -->
## Install
A private workspace package resolved through the root `package.json` `workspaces` glob `govlab.root/govlab.*`. One `npm install` at the root hoists its dependencies into the single root `node_modules`. The `govlab` bin runs as `npx govlab <concern>` or through the root `lint`, `format` and `deps:check` scripts. Extend it without editing the package through `.govlab/rules/<name>.mjs` files.
## Quick start
```sh EXAMPLE: Lint every detected ecosystem from one config
npx govlab lint
```
```sh EXAMPLE: Install the hardened tool chain for named ecosystems
npx govlab install typescript javascript go
```
<!-- /concern:install -->
<!-- concern:api -->
## API
- `const configs: { … }`
- `const configs: { … }`
- `interface ConfigSection`
- `interface ContentPolicyConfig`
- `function createQualityRelations(options?: QualityRelationsOptions): QualityRelations`
- `default export`
- `default export`
- `default export`
- `function defineConfigSection(section: ConfigSection): ConfigSection`
- `function defineGovlabConfig<T extends GovlabConfig>(config: T): T`
- `function docsConfig(config: GovlabConfig): ResolvedDocsConfig`
- `interface DocsConfig`
- `interface EslintScopeConfig`
- `function excludeMatcher(root: string, tool?: string): Promise<PathExclusion>`
- `interface ExtensionsConfig`
- `interface GainConfig`
- `interface GovlabConfig`
- `function govlabEslintConfig(consumerRoot?: string): Promise<Linter.Config[]>`
- `function govlabEslintSettings(config: GovlabConfig): GovlabEslintSettings`
- `interface GovlabEslintSettings`
- `function govlabHtmlhintConfig(consumerRoot?: string): Promise<{ rules: Record<string, unknown>; ignore: string[]; }>`
- `function govlabJscpdConfig(consumerRoot?: string): Promise<Record<string, unknown>>`
- `function govlabKnipConfig(consumerRoot?: string): Promise<Record<string, unknown>>`
- `function govlabMeta(spec: GovlabRuleSpec): Rule.RuleMetaData`
- `function govlabOxlintConfig(consumerRoot?: string): Promise<Record<string, unknown>>`
- `function govlabOxlintFixConfig(consumerRoot?: string): Promise<Record<string, unknown>>`
- `function govlabPrettierConfig(consumerRoot?: string): Promise<Record<string, unknown>>`
- `function govlabPrettierIgnore(consumerRoot?: string): Promise<string[]>`
- `interface GovlabRuleSpec`
- `function govlabStylelintConfig(consumerRoot?: string): Promise<Record<string, unknown>>`
- `function govlabYamllintConfig(consumerRoot?: string): Promise<{ command: string; config: Record<string, unknown>; }>`
- `interface HarnessDocProfile`
- `interface HarnessDocsConfig`
- `interface HostPolicyConfig`
- `function isExcludedPath(relPath: string, markers: readonly string[]): boolean`
- `function loadGovlabConfig(root: string): Promise<GovlabConfig>`
- `function masterExclude(config: GovlabConfig): string[]`
- `function masterExcludeMarkers(config: GovlabConfig, tool?: string): string[]`
- `const meta: GovlabStylelintMeta[]`
- `interface OxlintConfig`
- `function pathExclusion(root: string, markers: readonly string[]): PathExclusion`
- `enum PathExclusion`
- `function qualityEngineConfig(config: GovlabConfig): ResolvedQualityEngineConfig`
- `interface QualityEngineConfig`
- `interface QualitySectionConfig`
- `function registeredSections(): ConfigSection[]`
- `function resolveConfigInDir(dir: string): string | null`
- `interface ResolvedDocsConfig`
- `interface ResolvedQualityEngineConfig`
- `const rules: Record<string, Rule.RuleModule>`
- `const rules: Record<string, Rule.RuleModule>`
- `function validateConfig(config: Record<string, unknown>): string[]`
- `function withMasterExclude(config: GovlabConfig, own: string[]): string[]`
<!-- /concern:api -->
<!-- concern:config -->
## Configuration
Every value comes from one `govlab.config.{ts,js,mjs}`: `quality.concerns` is the cross-ecosystem concept-to-value map, and each tool's own section carries its single-rule config. The runner reads that config through the module's own config face, so no per-tool config file is required.
<!-- /concern:config -->
<!-- concern:deps -->
## Dependencies
- `@govlab/argv`
- `@govlab/canonical-write`
- `@govlab/code-parse`
- `@govlab/constants`
- `@govlab/content-fingerprint`
- `@govlab/context`
- `@ssot/paths`
<!-- /concern:deps -->
<!-- concern:ai-context -->
## AI context
- The one code-quality module: rules, catalog, engine, config, installer, and runner for every quality ecosystem, all resolving from one `govlab.config`.
- The meta-linter runner detects a project's ecosystems from its root files, builds each tool's config in memory through the module's config adapters, runs JavaScript tools through their Node APIs and other tools through subprocess, and normalizes every result into one finding shape.
- A consolidated module shaped by the concern taxonomy: authored data and derived outputs under `configuration/`, the rules, producers, steps, emitters, adapters and the rest of the logic under `core/`, and every command under `runtime/entrypoints/`. The barrel plus subpath exports present one name for the whole quality domain.
- Standing this package up takes one `npm install` at the workspace root and invokes its own bins, never a host script. There is no build step, and the `govlab` bin runs as `npx govlab <concern>`.
- Detect and install the toolchain: run `govlab list` to detect the consumer's ecosystems, then `govlab install <ecosystem>` to add each ecosystem's hardened tool-and-plugin chain to the consumer root.
- Author one `govlab.config.{ts,js,mjs}` wherever the consumer prefers. The runner detects it by its unique name in the project root, a `config` folder or a `.govlab` folder. `quality.concerns` carries the cross-ecosystem dimensions and each tool's own section carries single-rule config. Authoring is optional to run the linter but required to activate the scoped rules and the concern tuning.
- Migrate an existing linter config by lookup, never by guessing. Resolve each rule in the consumer's current config against this package's bundled catalog (`@govlab/quality/relations` over `configuration/quality/generated/all-rules.generated.json`, whose rules carry their canonical concepts, and the per-source files under `configuration/catalog/`). A rule that maps to a concept becomes a `qualityMaster.concerns` entry, and a tool-specific rule goes in that tool's own section. A rule that resolves to no mapping goes to the developer for a decision and is never dropped without a word.
- Extend without editing the package, with rule code kept apart from rule management.
- Rule code: a consumer authors its own eslint or stylelint rule plugins, holding new rules that are not in the catalog, against the tool's plugin contract. They live in `.govlab/rules/<name>.mjs` files, either project-local or, when `extensions.global` is set, in the home directory for every project. Each file default-exports `{ tool, plugins }`, where an eslint `plugins` is a namespace-to-plugin map and a stylelint `plugins` is a plugin array. The runner discovers and registers them, so their rules become available. A namespace that shadows a core one is rejected, which avoids a plugin-redefinition crash.
- Rule management: the consumer decides in `govlab.config`, through `eslint.rules` and `stylelint.rules`, whether any rule, custom or from the catalog, is enabled, tuned or disabled. Those sections merge last, so the consumer's config always wins. The consumer never edits vendored source, and the package's own catalog-driven rules stay intact unless the consumer tunes them.
- Verify the migration behaviorally: run `govlab <concern> --reporter json` and reconcile the findings against the intent of the existing config, so a dropped rule surfaces before it ships.
- Wiring the linter into the consumer's pre-push or CI gate is a deployment decision. Recommend it and surface it for the developer's approval, never wire it unilaterally.
<!-- /concern:ai-context -->
<!-- concern:domains -->
## Domains
This package serves these software domains, which `_manifest.json` declares in `domains` from the two-tier software-domain vocabulary (`meta → sub`):
- **developer-tooling** — linting-quality
<!-- /concern:domains -->
<!-- concern:quality-governance -->
## Quality governance
The canonical quality catalog resolves the quality concepts that govern this package. `_manifest.json` declares them in `governedBy`, and a lint package derives them from the concepts its own rules enforce. Each maps to the custom lint rules that enforce it:
- **duplicate-code** — _complexity_
- **separation-of-concerns** — _complexity_
- **type-safety** — _correctness_
<!-- /concern:quality-governance -->
<!-- concern:disposal -->
## Disposal
- Remove the package directory `govlab.root/govlab.quality/` and every `npx govlab` script from the root `package.json`.
- Remove every import site in consumers and the config-file delegates that call the adapters.
- Remove the pipeline wiring in the consumer's verification and pre-push gate that invokes the module's bins.
<!-- /concern:disposal -->
<!-- concern:metrics -->
---
stable · 53 exports · 7 deps · 0 principles · 3 concepts
<!-- /concern:metrics -->