README.md
README.md is a file in GovLab Constants. 138 lines of code and 0 definitions.
<!-- Auto-generated 2026-10-04T19:44Z v11 -->
# @govlab/constants
<!-- concern:overview -->
## Purpose
A dependency-free package holding the vocabularies that cross a member boundary. The ontology constants name each collection face (`ARCH_FACE`, `REASON_FACE` and their peers), the separator a face-qualified reference splits on, and each relation id an ontology edge carries. The character constants list the letters, digits and whitespace a scanner tests against, and the character predicates answer membership through a set lookup, so no consumer writes a regex. The word constants hold the British-to-American spelling table the word codemod and the site search both read.
<!-- /concern:overview -->
<!-- concern:use -->
## When to use
- Two or more members agree on the same closed set of strings, and duplicating it would let the copies drift.
- A scanner needs to test whether a character is a letter, a digit, whitespace or part of an identifier.
- A member builds or splits a face-qualified ontology reference, or names an ontology relation.
## When NOT to use
- A constant only one member reads. It stays in that member's own constants folder.
- A tunable a consumer should be able to override. It belongs in `.govlab/govlab.config.ts`, not in a shipped closed set.
- Behavior beyond a membership test. The predicates are the only functions here.
<!-- /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 repo root links it. It has no build step and no runtime dependency, so importing `@govlab/constants` is the whole integration.
## Quick start
```ts EXAMPLE: Split a face-qualified reference and test a character
import { FACE_SEPARATOR, ONTOLOGY_FACES, isDigit } from "@govlab/constants";
const [face] = "architecture:single-source-of-truth".split(FACE_SEPARATOR);
ONTOLOGY_FACES.has(face ?? "");
isDigit("7");
```
```ts EXAMPLE: Read the spelling table
import { AMERICAN_WORDS } from "@govlab/constants";
AMERICAN_WORDS["behaviour"];
```
<!-- /concern:install -->
<!-- concern:api -->
## API
- `const ALGO_DOMAIN_FACE: "algorithms-domain"`
- `const ALGO_FACE: "algorithms"`
- `const AMERICAN_WORDS: Readonly<Record<string, string>>` — each British spelling mapped to its American form. `IZE_STEMS` and `IZE_SUFFIXES` cover the -ise family by rule instead of by word.
- `function americanOf(word: string): string`
- `const ARCH_CATEGORY_FACE: "architecture-category"`
- `const ARCH_FACE: "architecture"`
- `const AXIS_RELATION: "axis"`
- `const CATEGORY_RELATION: "category"`
- `const COMPOSED_BY_RELATION: "composed-by"`
- `const COMPOSES_RELATION: "composes"`
- `const CONFLICTS_WITH_RELATION: "conflicts-with"`
- `const CONTRACT_RELATION: "contract"`
- `const CONTRACTS_RELATION: "contracts"`
- `const DERIVED_BY_RELATION: "derived-by"`
- `const DETECTS_RELATION: "detects"`
- `const DIGITS: readonly string[]`
- `const ENABLES_RELATION: "enables"`
- `function everyChar(text: string, test: (char: string) => boolean): boolean`
- `const FACE_SEPARATOR: ":"` — the character that separates a face from the record id in a qualified reference.
- `const FORCE_FACE: "force"`
- `const GROUNDED_BY_RELATION: "grounded-by"`
- `const GROUNDS_RELATION: "grounds"`
- `function identifierParts(token: string): readonly string[]`
- `function isAlpha(char: string): boolean`
- `function isDigit(char: string): boolean`
- `function isIdentifierChar(char: string): boolean` — true for a single letter, digit or joiner, and false for anything longer than one character.
- `function isLowerAlpha(char: string): boolean`
- `function isUpperAlpha(char: string): boolean`
- `function isWhitespace(char: string): boolean`
- `const IZE_STEMS: readonly string[]`
- `const IZE_SUFFIXES: Readonly<Record<string, string>>`
- `const KIND_FACE: "kind"`
- `const LAYER_FACE: "layer"`
- `const LEX_CATEGORY_FACE: "lexicon-category"`
- `const LEX_FACE: "lexicon"`
- `const LOWER_ALPHA: readonly string[]`
- `function normalizeWord(word: string): string`
- `const ONTOLOGY_FACES: ReadonlySet<string>` — every declared face, the set a reference prefix is checked against.
- `const PAG_FACE: "pag"`
- `const PLURAL_IES: readonly [string, string]`
- `const PLURAL_KEPT_AFTER: ReadonlySet<string>`
- `const PLURAL_MINIMUM_LENGTH: 4`
- `const PLURAL_SUFFIX: "s"`
- `const PRINCIPLE_RELATION: "principle"`
- `const REASON_FACE: "reasoning"`
- `const REFACTORED_BY_RELATION: "refactored-by"`
- `const REFACTORS_RELATION: "refactors"`
- `const REFERENCED_BY_RELATION: "referenced-by"`
- `const REINFORCES_RELATION: "reinforces"`
- `const RELATION_FACE: "relation"`
- `const REQUIRES_RELATION: "requires"`
- `const SPELLING_PREFIXES: readonly string[]`
- `const STAGE_FACE: "stage"`
- `const STAGE_RELATION: "stage"`
- `const TENSION_FACE: "tension"`
- `const TENSIONS_RELATION: "tensions"`
- `const TENSIONS_WITH_RELATION: "tensions-with"`
- `const TERM_RELATION: "term"`
- `const UPPER_ALPHA: readonly string[]`
- `const VIOLATED_BY_RELATION: "violated-by"`
- `const VIOLATES_RELATION: "violates"`
- `const VOCABULARY_FACE: "vocabulary"`
- `const WHITESPACE: readonly string[]`
<!-- /concern:api -->
<!-- concern:config -->
## Configuration
None. The package exposes no options and reads no config.
<!-- /concern:config -->
<!-- concern:deps -->
## Dependencies
The package is a leaf with no runtime dependencies.
<!-- /concern:deps -->
<!-- concern:ai-context -->
## AI context
- Import by the specifier `@govlab/constants`, never by relative path. Inside the package, a file reaches another through its `#configuration/*` and `#core/*` imports map.
- The constants live in `configuration/constants/` and the predicates in `core/predicates/`, so a constant file carries no function.
- These are closed vocabularies, and adding an entry to make a check pass is banned. Add a word that names something that exists, or rename the thing.
<!-- /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
- **platform** — utilities
<!-- /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:
- **immutability** — _best-practice_
- **duplicate-code** — _complexity_
- **separation-of-concerns** — _complexity_
<!-- /concern:quality-governance -->
<!-- concern:disposal -->
## Disposal
- Move each vocabulary into the member that owns it, and point every other reader at that member's specifier.
- Drop `@govlab/constants` from every package's `dependencies`.
- Remove `govlab.root/govlab.constants/`, its `containers` entry in `.govlab/shared/configs/taxonomy.config.ts` and its tests under `codebase.testing/test.govlab/constants/`.
<!-- /concern:disposal -->
<!-- concern:metrics -->
---
stable · 63 exports · 0 deps · 0 principles · 3 concepts
<!-- /concern:metrics -->