IF Commons GitHub

governance/config

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0009-repoctl-config FR-001

The configuration of a repository (commons repoctl 0009-repoctl-config FR-001 to FR-006): repoctl.config.ts at the repository's root says everything repoctl knows of the repository it operates, as typed data. defineConfig is the one way a configuration is written (it checks the shape and is the identity); parseConfig is the one way the host reads one (it makes every identity by its smart constructor and says every reason a configuration is wrong, at once). Nothing about any repository is in the host: the generators, the checks, the commit rules, the hygiene policy, the doctor's pins, the names of the variables and the optional verbs are all here.

import { defineConfig, parseConfig } from "./config.ts";
const input = defineConfig({
  repo: "app",
  commit: { identity: { name: "A B", email: "a@example.test" }, issue: { prefix: "Refs #", required: false }, trailers: ["issue"] },
});
parseConfig(input).kind; // "ok"

Source: commons/repoctl/src/governance/config.ts

13 of 50 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

governance.TrailerKindtypeno test imports it
type TrailerKind = "issue" | "impact" | "co-author" | "session";

The trailers a commit may carry, in the order a configuration lists them: the reference to an issue, the impact on a version, the line that credits the agent and the address of the session.

governance.TRAILER_KINDSconstno test imports it
const TRAILER_KINDS: readonly TrailerKind[]

Every trailer, in the order of the documentation.

governance.ForbiddenPathtypeno test imports it
type ForbiddenPath = { readonly glob: string; readonly why: string };

A path that must not be committed, by a glob from the repository's root, and the reason said to the person.

governance.SecretPatterntypeno test imports it
type SecretPattern = { readonly pattern: string; readonly label: string };

A text that looks like a secret: a regular expression's source and what it looks like.

governance.CommitPolicytypeno test imports it
type CommitPolicy = { /** The author and the committer of every commit. */ readonly identity: Identity; /** The re… (1309 characters)
type CommitPolicy = {
  /** The author and the committer of every commit. */
  readonly identity: Identity;
  /** The reference to an issue: the line is the prefix and the number (`Refs #` and `10` make `Refs #10`); `required` makes `--refs` mandatory. */
  readonly issue: { readonly prefix: string; readonly required: boolean };
  /** The trailers after the subject, in order. The line that credits the agent comes from `--co-author` or `REPOCTL_CO_AUTHOR` (else `coAuthor`), the session from `--session` or `CLAUDE_SESSION_URL`. */
  readonly trailers: readonly TrailerKind[];
  /** The line that credits the agent where neither the command line nor the environment gives one. */
  readonly coAuthor: string | undefined;
  /** The merge commits of the history that `repoctl hygiene` does not report though their author or committer is not the identity: hashes of at least seven lower-case hexadecimal characters, each a prefix of the hash it holds. History is never rewritten, so this is the list that only shrinks. */
  readonly heldMerges: readonly string[];
  readonly forbidden: {
    readonly paths: readonly ForbiddenPath[];
    /** Globs of paths that are allowed though a forbidden glob matches them. */
    readonly allow: readonly string[];
    readonly secrets: readonly SecretPattern[];
  };
};

The rules of repoctl commit.

governance.HygienePolicytypeno test imports it
type HygienePolicy = { /** The scope of the packages that are the family's (`@scope/`). */ readonly scope: string; … (798 characters)
type HygienePolicy = {
  /** The scope of the packages that are the family's (`@scope/`). */
  readonly scope: string;
  /** Fragments (lower case) of a Git dependency's specifier that name the family's own repository. */
  readonly gitSources: readonly string[];
  /** A folder name that a `file:` or `link:` dependency or a relative import must not go through. */
  readonly pathSegment: string;
  /** The file whose presence says this repository is the family's own, where the path, import and vendored findings are not made. */
  readonly sourceMarker: string;
  /** Allowances: globs of dependency paths that may be linked, and package names that may be carried by a folder of the repository. */
  readonly allow: { readonly paths: readonly string[]; readonly packages: readonly string[] };
};

The policy of repoctl hygiene: how a repository may consume the packages of a family.

governance.DoctorPolicytypeno test imports it
type DoctorPolicy = { /** The least major version of Node, or none where the repository has no rule. */ readonly min… (636 characters)
type DoctorPolicy = {
  /** The least major version of Node, or none where the repository has no rule. */
  readonly minNode: number | undefined;
  /** The file (from the root) that pins the version of Bun and the variable in it, or none. */
  readonly bunPin: { readonly file: string; readonly variable: string } | undefined;
  /** The folder (from the root) under which the libraries are linked, and the program that links them, or none. */
  readonly links: { readonly folder: string; readonly fix: readonly string[] } | undefined;
  /** What to run to install the dependencies, said in the finding. */
  readonly install: string;
};

What repoctl doctor checks of a checkout besides Git and the generated files.

governance.LibrariesSettingstypeno test imports it
type LibrariesSettings = { /** The folder (from the root) whose subfolders are the libraries, each with a `library.ts`… (1318 characters)
type LibrariesSettings = {
  /** The folder (from the root) whose subfolders are the libraries, each with a `library.ts` manifest. */
  readonly folder: string;
  /** The program that judges the specification kit of a library: the words `{kit}` and `{level}` are replaced by its folder and level. */
  readonly specKit: { readonly format: readonly string[]; readonly rules: readonly string[] } | undefined;
  /** Whether a source that says a library's version in a constant is checked against the manifest. */
  readonly versionConstants: boolean;
  /** Whether every package a library imports is declared in its manifest (a library job installs only its own folder). */
  readonly declaredDependencies: boolean;
  /** The program that links the libraries under the folder before a verb imports one, or none. */
  readonly linker: readonly string[] | undefined;
  /** The source (from the root) that classifies each library by role, which `new library` edits to add the new one; none where the repository has no such file. */
  readonly roleFile: string | undefined;
  /** The configuration of the documentation site (from the root), which lists the spec kit of every library and which `new library` edits to add the new one's; none where the repository has no such file. */
  readonly docsFile: string | undefined;
};

The settings of the verbs that know a family of libraries (status, release, new library, prove).

governance.Capabilitiestypeno test imports it
type Capabilities = { /** `release plan`, `release apply` and `release publish`: only for a repository with library ma… (646 characters)
type Capabilities = {
  /** `release plan`, `release apply` and `release publish`: only for a repository with library manifests. */
  readonly release: boolean;
  /** `new library`. */
  readonly newLibrary: boolean;
  /** `query`: questions of the libraries, specifications and requirements in SQL. */
  readonly query: boolean;
  /** `ci step`: one step of a pipeline under the build policy, its findings kept and its status never red (commons 0038-build-policy). */
  readonly ci: boolean;
  /** `status` of the packages. */
  readonly status: boolean;
  /** `prove`, the proof of a change by its blast radius. */
  readonly prove: boolean;
};

The optional verbs a repository turns on.

governance.DocsSettingstypeno test imports it
type DocsSettings = { readonly config: string; readonly out: string; readonly generator: string | undefined };

The documentation generator's settings: its configuration file and the folder the site is built into, from the root, and the module (from the root) that is the generator where it is a source of the repository and not an installed package.

governance.Configtypeno test imports it
type Config = { readonly repo: string; /** The variable that says which tier the host holds, and the one that says a… (565 characters)
type Config = {
  readonly repo: string;
  /** The variable that says which tier the host holds, and the one that says a tool server may only read. */
  readonly tierVariable: VariableName;
  readonly readOnlyVariable: VariableName;
  readonly commit: CommitPolicy;
  readonly generators: readonly Generator[];
  readonly checks: readonly Check[];
  readonly capabilities: Capabilities;
  readonly libraries: LibrariesSettings | undefined;
  readonly hygiene: HygienePolicy | undefined;
  readonly doctor: DoctorPolicy;
  readonly docs: DocsSettings | undefined;
};

A configuration, as the host reads it: every identity made, every default filled.

governance.StepInputtypeno test imports it
type StepInput = readonly string[] | StepFunction;

A program or a typed function, as a configuration writes it.

governance.GeneratorInputtypeno test imports it
type GeneratorInput = {
  readonly id: string;
  readonly summary?: string;
  readonly command: StepInput;
  readonly check?: StepInput;
  readonly inputs?: readonly string[];
  readonly outputs: readonly string[];
  readonly after?: readonly string[];
  readonly mixed?: readonly string[];
};

A generator, as a configuration writes it: the check is the program with --check added where it is not given.

governance.CheckInputtypeno test imports it
type CheckInput = { readonly id: string; readonly summary?: string; readonly command: StepInput; readonly code?: ProblemCode };

A check, as a configuration writes it.

governance.ConfigInputtypeno test imports it
type ConfigInput = { readonly repo: string; readonly tierVariable?: string; readonly readOnlyVariable?: string; … (1460 characters)
type ConfigInput = {
  readonly repo: string;
  readonly tierVariable?: string;
  readonly readOnlyVariable?: string;
  readonly commit: {
    readonly identity: Identity;
    readonly issue?: { readonly prefix: string; readonly required?: boolean };
    readonly trailers?: readonly TrailerKind[];
    readonly coAuthor?: string;
    readonly heldMerges?: readonly string[];
    readonly forbidden?: { readonly paths?: readonly ForbiddenPath[]; readonly allow?: readonly string[]; readonly secrets?: readonly SecretPattern[] };
  };
  readonly generators?: readonly GeneratorInput[];
  readonly checks?: readonly CheckInput[];
  readonly capabilities?: Partial<Capabilities>;
  readonly libraries?: { readonly folder: string; readonly specKit?: LibrariesSettings["specKit"]; readonly versionConstants?: boolean; readonly declaredDependencies?: boolean; readonly linker?: readonly string[]; readonly roleFile?: string; readonly docsFile?: string };
  readonly hygiene?: { readonly scope: string; readonly gitSources?: readonly string[]; readonly pathSegment?: string; readonly sourceMarker?: string; readonly allow?: { readonly paths?: readonly string[]; readonly packages?: readonly string[] } };
  readonly doctor?: { readonly minNode?: number; readonly bunPin?: DoctorPolicy["bunPin"]; readonly links?: DoctorPolicy["links"]; readonly install?: string };
  readonly docs?: { readonly config?: string; readonly out?: string; readonly generator?: string };
};

A configuration as it is written in repoctl.config.ts: what it leaves out has the default the documentation says.

governance.CAPABILITY_NAMESconstno test imports it
const CAPABILITY_NAMES: readonly (keyof Capabilities)[]

The names of the optional verbs a configuration turns on with a flag.

governance.CONFIG_FILEconstno test imports it
const CONFIG_FILE: "repoctl.config.ts"

The name of the file a repository keeps its configuration in, at its root.

governance.DEFAULT_TIER_VARIABLEconstno test imports it
const DEFAULT_TIER_VARIABLE: "REPOCTL_TIER"

The variable that fixes the tier the host holds, where a configuration does not name another.

governance.DEFAULT_READ_ONLY_VARIABLEconstno test imports it
const DEFAULT_READ_ONLY_VARIABLE: "REPOCTL_READ_ONLY"

The variable that says the key of a tool server may only read, where a configuration does not name another.

governance.DEFAULT_FORBIDDEN_PATHSconstno test imports it
const DEFAULT_FORBIDDEN_PATHS: readonly ForbiddenPath[]

The paths no repository commits: the local folder of an agent, installed packages, files that hold secrets. A configuration spreads or replaces it.

governance.DEFAULT_ALLOWED_PATHSconstno test imports it
const DEFAULT_ALLOWED_PATHS: readonly string[]

The environment files that are examples and are committed.

governance.DEFAULT_SECRET_PATTERNSconstno test imports it
const DEFAULT_SECRET_PATTERNS: readonly SecretPattern[]

The texts that look like secrets: the keys and tokens of the common services.

governance.defineConfigfunctionno test imports it
function defineConfig(input: ConfigInput): ConfigInput

A configuration, written: the identity that checks its shape.

governance.parseConfigfunctionno test imports it
function parseConfig(input: ConfigInput): Result<Config, readonly string[]>

The configuration as the host reads it, or every reason it is wrong.

governance.enabledVerbsfunctionno test imports it
function enabledVerbs(config: Config): readonly VerbId[]

The verbs a configuration turns on besides the ones every repository has (check, sync, merge, commit, doctor): each capability adds its own.

CONFIG_FILEconstno test imports it
const CONFIG_FILE: "repoctl.config.ts"

The name of the file a repository keeps its configuration in, at its root.

DEFAULT_ALLOWED_PATHSconst
const DEFAULT_ALLOWED_PATHS: readonly string[]

The environment files that are examples and are committed.

Imported by 15 tests of the run (15 passed, 0 failed): the library's results

DEFAULT_FORBIDDEN_PATHSconst
const DEFAULT_FORBIDDEN_PATHS: readonly ForbiddenPath[]

The paths no repository commits: the local folder of an agent, installed packages, files that hold secrets. A configuration spreads or replaces it.

Imported by 15 tests of the run (15 passed, 0 failed): the library's results

DEFAULT_SECRET_PATTERNSconst
const DEFAULT_SECRET_PATTERNS: readonly SecretPattern[]

The texts that look like secrets: the keys and tokens of the common services.

Imported by 15 tests of the run (15 passed, 0 failed): the library's results

defineConfigfunction
function defineConfig(input: ConfigInput): ConfigInput

A configuration, written: the identity that checks its shape.

Imported by 3 tests of the run (3 passed, 0 failed): the library's results

parseConfigfunction
function parseConfig(input: ConfigInput): Result<Config, readonly string[]>

The configuration as the host reads it, or every reason it is wrong.

Imported by 3 tests of the run (3 passed, 0 failed): the library's results

Capabilitiestypeno test imports it
type Capabilities = { /** `release plan`, `release apply` and `release publish`: only for a repository with library ma… (646 characters)
type Capabilities = {
  /** `release plan`, `release apply` and `release publish`: only for a repository with library manifests. */
  readonly release: boolean;
  /** `new library`. */
  readonly newLibrary: boolean;
  /** `query`: questions of the libraries, specifications and requirements in SQL. */
  readonly query: boolean;
  /** `ci step`: one step of a pipeline under the build policy, its findings kept and its status never red (commons 0038-build-policy). */
  readonly ci: boolean;
  /** `status` of the packages. */
  readonly status: boolean;
  /** `prove`, the proof of a change by its blast radius. */
  readonly prove: boolean;
};

The optional verbs a repository turns on.

CheckInputtypeno test imports it
type CheckInput = { readonly id: string; readonly summary?: string; readonly command: StepInput; readonly code?: ProblemCode };

A check, as a configuration writes it.

CommitPolicytype
type CommitPolicy = { /** The author and the committer of every commit. */ readonly identity: Identity; /** The re… (1309 characters)
type CommitPolicy = {
  /** The author and the committer of every commit. */
  readonly identity: Identity;
  /** The reference to an issue: the line is the prefix and the number (`Refs #` and `10` make `Refs #10`); `required` makes `--refs` mandatory. */
  readonly issue: { readonly prefix: string; readonly required: boolean };
  /** The trailers after the subject, in order. The line that credits the agent comes from `--co-author` or `REPOCTL_CO_AUTHOR` (else `coAuthor`), the session from `--session` or `CLAUDE_SESSION_URL`. */
  readonly trailers: readonly TrailerKind[];
  /** The line that credits the agent where neither the command line nor the environment gives one. */
  readonly coAuthor: string | undefined;
  /** The merge commits of the history that `repoctl hygiene` does not report though their author or committer is not the identity: hashes of at least seven lower-case hexadecimal characters, each a prefix of the hash it holds. History is never rewritten, so this is the list that only shrinks. */
  readonly heldMerges: readonly string[];
  readonly forbidden: {
    readonly paths: readonly ForbiddenPath[];
    /** Globs of paths that are allowed though a forbidden glob matches them. */
    readonly allow: readonly string[];
    readonly secrets: readonly SecretPattern[];
  };
};

The rules of repoctl commit.

Imported by 15 tests of the run (15 passed, 0 failed): the library's results

Configtype
type Config = { readonly repo: string; /** The variable that says which tier the host holds, and the one that says a… (565 characters)
type Config = {
  readonly repo: string;
  /** The variable that says which tier the host holds, and the one that says a tool server may only read. */
  readonly tierVariable: VariableName;
  readonly readOnlyVariable: VariableName;
  readonly commit: CommitPolicy;
  readonly generators: readonly Generator[];
  readonly checks: readonly Check[];
  readonly capabilities: Capabilities;
  readonly libraries: LibrariesSettings | undefined;
  readonly hygiene: HygienePolicy | undefined;
  readonly doctor: DoctorPolicy;
  readonly docs: DocsSettings | undefined;
};

A configuration, as the host reads it: every identity made, every default filled.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

ConfigInputtype
type ConfigInput = { readonly repo: string; readonly tierVariable?: string; readonly readOnlyVariable?: string; … (1460 characters)
type ConfigInput = {
  readonly repo: string;
  readonly tierVariable?: string;
  readonly readOnlyVariable?: string;
  readonly commit: {
    readonly identity: Identity;
    readonly issue?: { readonly prefix: string; readonly required?: boolean };
    readonly trailers?: readonly TrailerKind[];
    readonly coAuthor?: string;
    readonly heldMerges?: readonly string[];
    readonly forbidden?: { readonly paths?: readonly ForbiddenPath[]; readonly allow?: readonly string[]; readonly secrets?: readonly SecretPattern[] };
  };
  readonly generators?: readonly GeneratorInput[];
  readonly checks?: readonly CheckInput[];
  readonly capabilities?: Partial<Capabilities>;
  readonly libraries?: { readonly folder: string; readonly specKit?: LibrariesSettings["specKit"]; readonly versionConstants?: boolean; readonly declaredDependencies?: boolean; readonly linker?: readonly string[]; readonly roleFile?: string; readonly docsFile?: string };
  readonly hygiene?: { readonly scope: string; readonly gitSources?: readonly string[]; readonly pathSegment?: string; readonly sourceMarker?: string; readonly allow?: { readonly paths?: readonly string[]; readonly packages?: readonly string[] } };
  readonly doctor?: { readonly minNode?: number; readonly bunPin?: DoctorPolicy["bunPin"]; readonly links?: DoctorPolicy["links"]; readonly install?: string };
  readonly docs?: { readonly config?: string; readonly out?: string; readonly generator?: string };
};

A configuration as it is written in repoctl.config.ts: what it leaves out has the default the documentation says.

Imported by 3 tests of the run (3 passed, 0 failed): the library's results

DocsSettingstypeno test imports it
type DocsSettings = { readonly config: string; readonly out: string; readonly generator: string | undefined };

The documentation generator's settings: its configuration file and the folder the site is built into, from the root, and the module (from the root) that is the generator where it is a source of the repository and not an installed package.

DoctorPolicytype
type DoctorPolicy = { /** The least major version of Node, or none where the repository has no rule. */ readonly min… (636 characters)
type DoctorPolicy = {
  /** The least major version of Node, or none where the repository has no rule. */
  readonly minNode: number | undefined;
  /** The file (from the root) that pins the version of Bun and the variable in it, or none. */
  readonly bunPin: { readonly file: string; readonly variable: string } | undefined;
  /** The folder (from the root) under which the libraries are linked, and the program that links them, or none. */
  readonly links: { readonly folder: string; readonly fix: readonly string[] } | undefined;
  /** What to run to install the dependencies, said in the finding. */
  readonly install: string;
};

What repoctl doctor checks of a checkout besides Git and the generated files.

Imported by 15 tests of the run (15 passed, 0 failed): the library's results

ForbiddenPathtypeno test imports it
type ForbiddenPath = { readonly glob: string; readonly why: string };

A path that must not be committed, by a glob from the repository's root, and the reason said to the person.

GeneratorInputtypeno test imports it
type GeneratorInput = {
  readonly id: string;
  readonly summary?: string;
  readonly command: StepInput;
  readonly check?: StepInput;
  readonly inputs?: readonly string[];
  readonly outputs: readonly string[];
  readonly after?: readonly string[];
  readonly mixed?: readonly string[];
};

A generator, as a configuration writes it: the check is the program with --check added where it is not given.

HygienePolicytype
type HygienePolicy = { /** The scope of the packages that are the family's (`@scope/`). */ readonly scope: string; … (798 characters)
type HygienePolicy = {
  /** The scope of the packages that are the family's (`@scope/`). */
  readonly scope: string;
  /** Fragments (lower case) of a Git dependency's specifier that name the family's own repository. */
  readonly gitSources: readonly string[];
  /** A folder name that a `file:` or `link:` dependency or a relative import must not go through. */
  readonly pathSegment: string;
  /** The file whose presence says this repository is the family's own, where the path, import and vendored findings are not made. */
  readonly sourceMarker: string;
  /** Allowances: globs of dependency paths that may be linked, and package names that may be carried by a folder of the repository. */
  readonly allow: { readonly paths: readonly string[]; readonly packages: readonly string[] };
};

The policy of repoctl hygiene: how a repository may consume the packages of a family.

Imported by 7 tests of the run (7 passed, 0 failed): the library's results

LibrariesSettingstypeno test imports it
type LibrariesSettings = { /** The folder (from the root) whose subfolders are the libraries, each with a `library.ts`… (1318 characters)
type LibrariesSettings = {
  /** The folder (from the root) whose subfolders are the libraries, each with a `library.ts` manifest. */
  readonly folder: string;
  /** The program that judges the specification kit of a library: the words `{kit}` and `{level}` are replaced by its folder and level. */
  readonly specKit: { readonly format: readonly string[]; readonly rules: readonly string[] } | undefined;
  /** Whether a source that says a library's version in a constant is checked against the manifest. */
  readonly versionConstants: boolean;
  /** Whether every package a library imports is declared in its manifest (a library job installs only its own folder). */
  readonly declaredDependencies: boolean;
  /** The program that links the libraries under the folder before a verb imports one, or none. */
  readonly linker: readonly string[] | undefined;
  /** The source (from the root) that classifies each library by role, which `new library` edits to add the new one; none where the repository has no such file. */
  readonly roleFile: string | undefined;
  /** The configuration of the documentation site (from the root), which lists the spec kit of every library and which `new library` edits to add the new one's; none where the repository has no such file. */
  readonly docsFile: string | undefined;
};

The settings of the verbs that know a family of libraries (status, release, new library, prove).

SecretPatterntypeno test imports it
type SecretPattern = { readonly pattern: string; readonly label: string };

A text that looks like a secret: a regular expression's source and what it looks like.

StepInputtypeno test imports it
type StepInput = readonly string[] | StepFunction;

A program or a typed function, as a configuration writes it.

TrailerKindtypeno test imports it
type TrailerKind = "issue" | "impact" | "co-author" | "session";

The trailers a commit may carry, in the order a configuration lists them: the reference to an issue, the impact on a version, the line that credits the agent and the address of the session.

TRAILER_KINDSconstno test imports it
const TRAILER_KINDS: readonly TrailerKind[]

Every trailer, in the order of the documentation.

CAPABILITY_NAMESconstno test imports it
const CAPABILITY_NAMES: readonly (keyof Capabilities)[]

The names of the optional verbs a configuration turns on with a flag.

DEFAULT_TIER_VARIABLEconst
const DEFAULT_TIER_VARIABLE: "REPOCTL_TIER"

The variable that fixes the tier the host holds, where a configuration does not name another.

Imported by 3 tests of the run (3 passed, 0 failed): the library's results

DEFAULT_READ_ONLY_VARIABLEconst
const DEFAULT_READ_ONLY_VARIABLE: "REPOCTL_READ_ONLY"

The variable that says the key of a tool server may only read, where a configuration does not name another.

Imported by 3 tests of the run (3 passed, 0 failed): the library's results

enabledVerbsfunction
function enabledVerbs(config: Config): readonly VerbId[]

The verbs a configuration turns on besides the ones every repository has (check, sync, merge, commit, doctor): each capability adds its own.

Imported by 3 tests of the run (3 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.