README.md

README.md is a file in GovLab Stats. 92 lines of code and 0 definitions.

<!-- Auto-generated 2026-09-29T00:22Z v6 -->

# @govlab/stats

<!-- concern:overview -->

## Purpose

A generator in the gate's build stage. One filesystem walk classifies each file by role and provenance, separating authored source from generated and ingested content before anything is counted. On top of that walk sits one analyzer or loader per measurable surface:

- taxonomy conformance and vocabulary use, judged by the gate's own filename parser for each governed root
- application entry points, from the directories holding an entry document
- the internal package graph, from the `workspaces` globs
- the active rule set, from the `@govlab/quality/config` adapters
- per-stage pass or fail, from the most recent recorded gate run

Reporters render the collected facts as tables into one generated document, which carries no authored prose.
<!-- /concern:overview -->

<!-- concern:use -->

## When to use

- Adding a measurable surface to the census, as a new analyzer or loader plus its reporter.
- Reading what the workspace contains, instead of what a document claims it contains.
- Checking taxonomy conformance before or after a reshape, where the conformant share per governed root is the baseline.

## When NOT to use

- Enforcing anything. A threshold belongs in a lint rule or a pipeline validator, which report at the offending line.
- Answering a question about one member's internals that the member can answer itself.
- Deciding whether a name makes sense. The tooling counts and cross-checks, and it does not reason about a vocabulary.

<!-- /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 member resolved through the root `package.json` workspaces glob `govlab.root/govlab.*`. One `npm install` at the repo root is the whole setup. It declares `@govlab/argv`, `@govlab/canonical-write`, `@govlab/pipeline`, `@govlab/quality`, `@ssot/govlab` and `@ssot/paths`, and holds no third-party dependency of its own. There is no build step, and `npm run codebase:stats` runs `runtime/entrypoints/metric.entrypoint.ts`.

## Quick start

```sh EXAMPLE: Regenerate the codebase census
npm run codebase:stats
```

```ts EXAMPLE: Add a measured surface as a loader plus its reporter
import { absolutePath } from "@ssot/paths";

export interface StyleStats {
    files: number;
}

export const collectStyles = function collectStyles(): StyleStats {
    const root = absolutePath("app.root");
    return { files: countStylesUnder(root) };
};
```

<!-- /concern:install -->

<!-- concern:api -->

## API

The package exposes no public API.
<!-- /concern:api -->

<!-- concern:config -->

## Configuration

No config file and no tunable thresholds. Every root resolves through `@ssot/paths`. The governed roots and their vocabularies come from `@ssot/govlab`'s taxonomy manifest, the active tool configuration from the `@govlab/quality/config` adapters, and the gate outcome from the pipeline report artifact. The one output location is `doc-arch/generated/codebase-stats.project.generated.md`.
<!-- /concern:config -->

<!-- concern:deps -->

## Dependencies

- `@govlab/argv`
- `@govlab/canonical-write`
- `@govlab/pipeline`
- `@govlab/quality`
- `@ssot/govlab`
- `@ssot/paths`

<!-- /concern:deps -->

<!-- concern:ai-context -->

## AI context

- Every fact is derived: workspace members from the `workspaces` globs, the governed roots and vocabularies from the gate's taxonomy manifest, application entry points from any directory holding an entry document, and tool metrics from the config adapters the tools run with. A literal path or tool name in an analyzer is a defect.
- The entry point resolves one exclusion set and passes it to every walk, so no two surfaces skip different folders.
- Generated and ingested content is excluded from every authored aggregate and reported as its own single metric.
- A file is conformant exactly when the gate's `parseFilename` accepts it under its own root, so the census and the gate cannot disagree.
- The pipeline report artifact is written on every exit path, fail-fast included, so a present artifact is not a passing one. Read `ok`, and expect a short step list when a fail-fast run halted early.
- The output document carries no authored prose. State the shape in a table column and let the number derive again.

<!-- /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** — build-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 census step from the verify orchestrator and the `codebase:stats` script from the root `package.json`.
- Delete `doc-arch/generated/codebase-stats.project.generated.md`.
- Remove `govlab.root/govlab.stats/`, its `containers` entry in `.govlab/shared/configs/taxonomy.config.ts` and its tests under `codebase.testing/test.govlab/stats/`.

<!-- /concern:disposal -->

<!-- concern:metrics -->

---

stable · 0 exports · 6 deps · 0 principles · 3 concepts
<!-- /concern:metrics -->