logical.Dependencytypeno test imports ittype Dependency = { readonly name: string; readonly spec: string };A dependency a package.json declares: its name and what it asks for.
The hygiene of a repository that consumes commons (commons repoctl 0007-repoctl-hygiene FR-002, FR-003; 0009-repoctl-config FR-005; commons 0036-distribution FR-001, FR-002, FR-010, FR-011, FR-013): a pure function from the facts of a repository (its package.json files, its lockfiles, what is installed, the relative imports of its sources) to the findings of the rule that commons reaches a repository only as a published package. Nothing here reads a file: hygiene-facts.ts gathers the facts through the ports, and the verb draws the findings.
A finding is one of six, each with its code: a dependency by Git on the repository of commons (E-HYGIENE-GIT), a file: or link: dependency into a path that has a segment commons (E-HYGIENE-PATH), a relative import into such a path (E-HYGIENE-IMPORT), a vendored copy (E-HYGIENE-VENDORED), two installed copies of one library at different versions (E-HYGIENE-DUPLICATE) and, as a warning, a dependency that is not an exact version (E-HYGIENE-RANGE). In the repository of commons itself the packages under commons/ are its own, so the three findings about paths and copies are not made there.
import { hygiene } from "./hygiene.ts";
const policy = { scope: "@acme/", gitSources: ["acme/platform"], pathSegment: "platform", sourceMarker: "", allow: { paths: [], packages: [] } };
hygiene({ repository: "consumer", packages: [], locks: [], installed: new Map(), folders: [], imports: [], workspaces: [] }, policy); // []logical.Dependencytypeno test imports ittype Dependency = { readonly name: string; readonly spec: string };A dependency a package.json declares: its name and what it asks for.
logical.PackageFactstypeno test imports ittype PackageFacts = { readonly path: string; readonly name: string | undefined; readonly dependencies: readonly Dependency[] };A package.json of the repository: its path from the root, its name and its dependencies (of every section).
logical.Copytypeno test imports ittype Copy = { readonly version: string; readonly where: string };One installed copy of a package: its version and where it is (a path from the root, or a key of the lockfile).
logical.LockFactstypeno test imports ittype LockFacts =
| { readonly kind: "read"; readonly file: string; readonly copies: ReadonlyMap<string, readonly Copy[]> }
| { readonly kind: "unreadable"; readonly file: string; readonly why: string };What reading a lockfile gave: the copies of each package of commons it holds, or why it could not be read.
logical.ImportFacttypeno test imports ittype ImportFact = { readonly file: string; readonly specifier: string };A relative import of a source: the file and the specifier as written.
logical.Repositorytypeno test imports ittype Repository = "source" | "consumer";Whose repository it is: the repository the family's packages are made in (the policy's source marker is there), or a repository that consumes them.
logical.TreeFactstypeno test imports ittype TreeFacts = {
readonly folder: string;
readonly locks: readonly LockFacts[];
readonly installed: ReadonlyMap<string, readonly Copy[]>;
};The lockfiles and the installed copies of one folder that holds a package.json (a folder of its own is one tree: the copies of two folders are never one install). folder is a path from the root, "" for the root itself.
logical.HygieneFactstypeno test imports ittype HygieneFacts = {
readonly repository: Repository;
readonly packages: readonly PackageFacts[];
/** One entry f… (809 characters)type HygieneFacts = {
readonly repository: Repository;
readonly packages: readonly PackageFacts[];
/** One entry for each lockfile found at the root (`bun.lock`, `package-lock.json`); none where there is none. */
readonly locks: readonly LockFacts[];
/** The copies found in the `node_modules` of the root, by package. */
readonly installed: ReadonlyMap<string, readonly Copy[]>;
/** The same for each other folder that holds a `package.json`, nested ones included (never a folder under `node_modules`, `dist` or `.git`); each is an install of its own. */
readonly folders: readonly TreeFacts[];
readonly imports: readonly ImportFact[];
/** The globs of the workspaces the root `package.json` declares: the packages of the repository itself. */
readonly workspaces: readonly string[];
};Everything the check reads of a repository.
logical.HygieneFindingtypeno test imports ittype HygieneFinding = Finding & { readonly path: string };A finding of the check, with the path it was found at.
logical.isExactVersionfunctionno test imports itfunction isExactVersion(spec: string): booleanWhether a version specifier is an exact version.
logical.isGitOfFamilyfunctionno test imports itfunction isGitOfFamily(policy: HygienePolicy, spec: string): booleanWhether a dependency specifier is a dependency by Git on the family's own repository (a fragment of the policy's gitSources is in it).
logical.pathOffunctionno test imports itfunction pathOf(spec: string): string | undefinedThe kind of a path dependency: file: or link: and the path, or nothing where the specifier is none.
logical.intoFamilyfunctionno test imports itfunction intoFamily(policy: HygienePolicy, path: string): booleanWhether a path goes through the policy's folder name and the folder holds something: the name is a segment and is not the last. A policy with no folder name has no such path.
logical.hygienefunctionno test imports itfunction hygiene(facts: HygieneFacts, policy: HygienePolicy): readonly HygieneFinding[]The findings of a repository, in the order of the codes and then of the paths.
logical.hygieneFailsfunctionno test imports itfunction hygieneFails(findings: readonly Finding[]): booleanWhether any finding fails the run: a warning alone does not.
logical.countsOffunctionno test imports itfunction countsOf(findings: readonly Finding[]): { readonly failures: number; readonly warnings: number; }The counts of a run: failures and warnings.
Dependencytypeno test imports ittype Dependency = { readonly name: string; readonly spec: string };A dependency a package.json declares: its name and what it asks for.
PackageFactstypeno test imports ittype PackageFacts = { readonly path: string; readonly name: string | undefined; readonly dependencies: readonly Dependency[] };A package.json of the repository: its path from the root, its name and its dependencies (of every section).
Copytypeno test imports ittype Copy = { readonly version: string; readonly where: string };One installed copy of a package: its version and where it is (a path from the root, or a key of the lockfile).
LockFactstypeno test imports ittype LockFacts =
| { readonly kind: "read"; readonly file: string; readonly copies: ReadonlyMap<string, readonly Copy[]> }
| { readonly kind: "unreadable"; readonly file: string; readonly why: string };What reading a lockfile gave: the copies of each package of commons it holds, or why it could not be read.
ImportFacttypeno test imports ittype ImportFact = { readonly file: string; readonly specifier: string };A relative import of a source: the file and the specifier as written.
Repositorytypeno test imports ittype Repository = "source" | "consumer";Whose repository it is: the repository the family's packages are made in (the policy's source marker is there), or a repository that consumes them.
TreeFactstypeno test imports ittype TreeFacts = {
readonly folder: string;
readonly locks: readonly LockFacts[];
readonly installed: ReadonlyMap<string, readonly Copy[]>;
};The lockfiles and the installed copies of one folder that holds a package.json (a folder of its own is one tree: the copies of two folders are never one install). folder is a path from the root, "" for the root itself.
HygieneFactstypetype HygieneFacts = {
readonly repository: Repository;
readonly packages: readonly PackageFacts[];
/** One entry f… (809 characters)type HygieneFacts = {
readonly repository: Repository;
readonly packages: readonly PackageFacts[];
/** One entry for each lockfile found at the root (`bun.lock`, `package-lock.json`); none where there is none. */
readonly locks: readonly LockFacts[];
/** The copies found in the `node_modules` of the root, by package. */
readonly installed: ReadonlyMap<string, readonly Copy[]>;
/** The same for each other folder that holds a `package.json`, nested ones included (never a folder under `node_modules`, `dist` or `.git`); each is an install of its own. */
readonly folders: readonly TreeFacts[];
readonly imports: readonly ImportFact[];
/** The globs of the workspaces the root `package.json` declares: the packages of the repository itself. */
readonly workspaces: readonly string[];
};Everything the check reads of a repository.
HygieneFindingtypeno test imports ittype HygieneFinding = Finding & { readonly path: string };A finding of the check, with the path it was found at.
isExactVersionfunctionfunction isExactVersion(spec: string): booleanWhether a version specifier is an exact version.
isGitOfFamilyfunctionfunction isGitOfFamily(policy: HygienePolicy, spec: string): booleanWhether a dependency specifier is a dependency by Git on the family's own repository (a fragment of the policy's gitSources is in it).
pathOffunctionno test imports itfunction pathOf(spec: string): string | undefinedThe kind of a path dependency: file: or link: and the path, or nothing where the specifier is none.
intoFamilyfunctionfunction intoFamily(policy: HygienePolicy, path: string): booleanWhether a path goes through the policy's folder name and the folder holds something: the name is a segment and is not the last. A policy with no folder name has no such path.
hygienefunctionfunction hygiene(facts: HygieneFacts, policy: HygienePolicy): readonly HygieneFinding[]The findings of a repository, in the order of the codes and then of the paths.
hygieneFailsfunctionfunction hygieneFails(findings: readonly Finding[]): booleanWhether any finding fails the run: a warning alone does not.
countsOffunctionfunction countsOf(findings: readonly Finding[]): { readonly failures: number; readonly warnings: number; }The counts of a run: failures and warnings.