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-configFR-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.
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.
type CommitPolicy = {
/** The author and the committer of every commit. */
readonly identity: Identity;
/** The re…(1309 characters)
typeCommitPolicy= {
/** The author and the committer of every commit. */readonlyidentity:Identity;
/** The reference to an issue: the line is the prefix and the number (`Refs #` and `10` make `Refs #10`); `required` makes `--refs` mandatory. */readonlyissue: { readonlyprefix:string; readonlyrequired: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`. */readonlytrailers:readonlyTrailerKind[];
/** The line that credits the agent where neither the command line nor the environment gives one. */readonlycoAuthor: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. */readonlyheldMerges:readonlystring[];
readonlyforbidden: {
readonlypaths:readonlyForbiddenPath[];
/** Globs of paths that are allowed though a forbidden glob matches them. */readonlyallow:readonlystring[];
readonlysecrets:readonlySecretPattern[];
};
};
type HygienePolicy = {
/** The scope of the packages that are the family's (`@scope/`). */
readonly scope: string;
…(798 characters)
typeHygienePolicy= {
/** The scope of the packages that are the family's (`@scope/`). */readonlyscope:string;
/** Fragments (lower case) of a Git dependency's specifier that name the family's own repository. */readonlygitSources:readonlystring[];
/** A folder name that a `file:` or `link:` dependency or a relative import must not go through. */readonlypathSegment:string;
/** The file whose presence says this repository is the family's own, where the path, import and vendored findings are not made. */readonlysourceMarker:string;
/** Allowances: globs of dependency paths that may be linked, and package names that may be carried by a folder of the repository. */readonlyallow: { readonlypaths:readonlystring[]; readonlypackages:readonlystring[] };
};
The policy of repoctl hygiene: how a repository may consume the packages of a family.
type DoctorPolicy = {
/** The least major version of Node, or none where the repository has no rule. */
readonly min…(636 characters)
typeDoctorPolicy= {
/** The least major version of Node, or none where the repository has no rule. */readonlyminNode:number|undefined;
/** The file (from the root) that pins the version of Bun and the variable in it, or none. */readonlybunPin: { readonlyfile:string; readonlyvariable:string } |undefined;
/** The folder (from the root) under which the libraries are linked, and the program that links them, or none. */readonlylinks: { readonlyfolder:string; readonlyfix:readonlystring[] } |undefined;
/** What to run to install the dependencies, said in the finding. */readonlyinstall:string;
};
What repoctl doctor checks of a checkout besides Git and the generated files.
type LibrariesSettings = {
/** The folder (from the root) whose subfolders are the libraries, each with a `library.ts`…(1318 characters)
typeLibrariesSettings= {
/** The folder (from the root) whose subfolders are the libraries, each with a `library.ts` manifest. */readonlyfolder:string;
/** The program that judges the specification kit of a library: the words `{kit}` and `{level}` are replaced by its folder and level. */readonlyspecKit: { readonlyformat:readonlystring[]; readonlyrules:readonlystring[] } |undefined;
/** Whether a source that says a library's version in a constant is checked against the manifest. */readonlyversionConstants:boolean;
/** Whether every package a library imports is declared in its manifest (a library job installs only its own folder). */readonlydeclaredDependencies:boolean;
/** The program that links the libraries under the folder before a verb imports one, or none. */readonlylinker:readonlystring[] |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. */readonlyroleFile: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. */readonlydocsFile:string|undefined;
};
The settings of the verbs that know a family of libraries (status, release, new library, prove).
type Capabilities = {
/** `release plan`, `release apply` and `release publish`: only for a repository with library ma…(646 characters)
typeCapabilities= {
/** `release plan`, `release apply` and `release publish`: only for a repository with library manifests. */readonlyrelease:boolean;
/** `new library`. */readonlynewLibrary:boolean;
/** `query`: questions of the libraries, specifications and requirements in SQL. */readonlyquery:boolean;
/** `ci step`: one step of a pipeline under the build policy, its findings kept and its status never red (commons 0038-build-policy). */readonlyci:boolean;
/** `status` of the packages. */readonlystatus:boolean;
/** `prove`, the proof of a change by its blast radius. */readonlyprove:boolean;
};
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.
type Config = {
readonly repo: string;
/** The variable that says which tier the host holds, and the one that says a…(565 characters)
typeConfig= {
readonlyrepo:string;
/** The variable that says which tier the host holds, and the one that says a tool server may only read. */readonlytierVariable:VariableName;
readonlyreadOnlyVariable:VariableName;
readonlycommit:CommitPolicy;
readonlygenerators:readonlyGenerator[];
readonlychecks:readonlyCheck[];
readonlycapabilities:Capabilities;
readonlylibraries:LibrariesSettings|undefined;
readonlyhygiene:HygienePolicy|undefined;
readonlydoctor:DoctorPolicy;
readonlydocs:DocsSettings|undefined;
};
A configuration, as the host reads it: every identity made, every default filled.
type Capabilities = {
/** `release plan`, `release apply` and `release publish`: only for a repository with library ma…(646 characters)
typeCapabilities= {
/** `release plan`, `release apply` and `release publish`: only for a repository with library manifests. */readonlyrelease:boolean;
/** `new library`. */readonlynewLibrary:boolean;
/** `query`: questions of the libraries, specifications and requirements in SQL. */readonlyquery:boolean;
/** `ci step`: one step of a pipeline under the build policy, its findings kept and its status never red (commons 0038-build-policy). */readonlyci:boolean;
/** `status` of the packages. */readonlystatus:boolean;
/** `prove`, the proof of a change by its blast radius. */readonlyprove:boolean;
};
type CommitPolicy = {
/** The author and the committer of every commit. */
readonly identity: Identity;
/** The re…(1309 characters)
typeCommitPolicy= {
/** The author and the committer of every commit. */readonlyidentity:Identity;
/** The reference to an issue: the line is the prefix and the number (`Refs #` and `10` make `Refs #10`); `required` makes `--refs` mandatory. */readonlyissue: { readonlyprefix:string; readonlyrequired: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`. */readonlytrailers:readonlyTrailerKind[];
/** The line that credits the agent where neither the command line nor the environment gives one. */readonlycoAuthor: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. */readonlyheldMerges:readonlystring[];
readonlyforbidden: {
readonlypaths:readonlyForbiddenPath[];
/** Globs of paths that are allowed though a forbidden glob matches them. */readonlyallow:readonlystring[];
readonlysecrets:readonlySecretPattern[];
};
};
type Config = {
readonly repo: string;
/** The variable that says which tier the host holds, and the one that says a…(565 characters)
typeConfig= {
readonlyrepo:string;
/** The variable that says which tier the host holds, and the one that says a tool server may only read. */readonlytierVariable:VariableName;
readonlyreadOnlyVariable:VariableName;
readonlycommit:CommitPolicy;
readonlygenerators:readonlyGenerator[];
readonlychecks:readonlyCheck[];
readonlycapabilities:Capabilities;
readonlylibraries:LibrariesSettings|undefined;
readonlyhygiene:HygienePolicy|undefined;
readonlydoctor:DoctorPolicy;
readonlydocs:DocsSettings|undefined;
};
A configuration, as the host reads it: every identity made, every default filled.
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.
type DoctorPolicy = {
/** The least major version of Node, or none where the repository has no rule. */
readonly min…(636 characters)
typeDoctorPolicy= {
/** The least major version of Node, or none where the repository has no rule. */readonlyminNode:number|undefined;
/** The file (from the root) that pins the version of Bun and the variable in it, or none. */readonlybunPin: { readonlyfile:string; readonlyvariable:string } |undefined;
/** The folder (from the root) under which the libraries are linked, and the program that links them, or none. */readonlylinks: { readonlyfolder:string; readonlyfix:readonlystring[] } |undefined;
/** What to run to install the dependencies, said in the finding. */readonlyinstall:string;
};
What repoctl doctor checks of a checkout besides Git and the generated files.
type HygienePolicy = {
/** The scope of the packages that are the family's (`@scope/`). */
readonly scope: string;
…(798 characters)
typeHygienePolicy= {
/** The scope of the packages that are the family's (`@scope/`). */readonlyscope:string;
/** Fragments (lower case) of a Git dependency's specifier that name the family's own repository. */readonlygitSources:readonlystring[];
/** A folder name that a `file:` or `link:` dependency or a relative import must not go through. */readonlypathSegment:string;
/** The file whose presence says this repository is the family's own, where the path, import and vendored findings are not made. */readonlysourceMarker:string;
/** Allowances: globs of dependency paths that may be linked, and package names that may be carried by a folder of the repository. */readonlyallow: { readonlypaths:readonlystring[]; readonlypackages:readonlystring[] };
};
The policy of repoctl hygiene: how a repository may consume the packages of a family.
type LibrariesSettings = {
/** The folder (from the root) whose subfolders are the libraries, each with a `library.ts`…(1318 characters)
typeLibrariesSettings= {
/** The folder (from the root) whose subfolders are the libraries, each with a `library.ts` manifest. */readonlyfolder:string;
/** The program that judges the specification kit of a library: the words `{kit}` and `{level}` are replaced by its folder and level. */readonlyspecKit: { readonlyformat:readonlystring[]; readonlyrules:readonlystring[] } |undefined;
/** Whether a source that says a library's version in a constant is checked against the manifest. */readonlyversionConstants:boolean;
/** Whether every package a library imports is declared in its manifest (a library job installs only its own folder). */readonlydeclaredDependencies:boolean;
/** The program that links the libraries under the folder before a verb imports one, or none. */readonlylinker:readonlystring[] |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. */readonlyroleFile: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. */readonlydocsFile:string|undefined;
};
The settings of the verbs that know a family of libraries (status, release, new library, prove).
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.