IF Commons GitHub

logical/hygiene

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0007-repoctl-hygiene FR-002

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); // []

Source: commons/repoctl/src/logical/hygiene.ts

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

logical.Dependencytypeno test imports it
type Dependency = { readonly name: string; readonly spec: string };

A dependency a package.json declares: its name and what it asks for.

logical.PackageFactstypeno test imports it
type 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 it
type 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 it
type 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 it
type ImportFact = { readonly file: string; readonly specifier: string };

A relative import of a source: the file and the specifier as written.

logical.Repositorytypeno test imports it
type 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 it
type 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 it
type 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 it
type HygieneFinding = Finding & { readonly path: string };

A finding of the check, with the path it was found at.

logical.isExactVersionfunctionno test imports it
function isExactVersion(spec: string): boolean

Whether a version specifier is an exact version.

logical.isGitOfFamilyfunctionno test imports it
function isGitOfFamily(policy: HygienePolicy, spec: string): boolean

Whether 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 it
function pathOf(spec: string): string | undefined

The kind of a path dependency: file: or link: and the path, or nothing where the specifier is none.

logical.intoFamilyfunctionno test imports it
function intoFamily(policy: HygienePolicy, path: string): boolean

Whether 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 it
function 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 it
function hygieneFails(findings: readonly Finding[]): boolean

Whether any finding fails the run: a warning alone does not.

logical.countsOffunctionno test imports it
function countsOf(findings: readonly Finding[]): { readonly failures: number; readonly warnings: number; }

The counts of a run: failures and warnings.

Dependencytypeno test imports it
type Dependency = { readonly name: string; readonly spec: string };

A dependency a package.json declares: its name and what it asks for.

PackageFactstypeno test imports it
type 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 it
type 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 it
type 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 it
type ImportFact = { readonly file: string; readonly specifier: string };

A relative import of a source: the file and the specifier as written.

Repositorytypeno test imports it
type 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 it
type 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.

HygieneFactstype
type 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.

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

HygieneFindingtypeno test imports it
type HygieneFinding = Finding & { readonly path: string };

A finding of the check, with the path it was found at.

isExactVersionfunction
function isExactVersion(spec: string): boolean

Whether a version specifier is an exact version.

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

isGitOfFamilyfunction
function isGitOfFamily(policy: HygienePolicy, spec: string): boolean

Whether a dependency specifier is a dependency by Git on the family's own repository (a fragment of the policy's gitSources is in it).

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

pathOffunctionno test imports it
function pathOf(spec: string): string | undefined

The kind of a path dependency: file: or link: and the path, or nothing where the specifier is none.

intoFamilyfunction
function intoFamily(policy: HygienePolicy, path: string): boolean

Whether 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.

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

hygienefunction
function hygiene(facts: HygieneFacts, policy: HygienePolicy): readonly HygieneFinding[]

The findings of a repository, in the order of the codes and then of the paths.

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

hygieneFailsfunction
function hygieneFails(findings: readonly Finding[]): boolean

Whether any finding fails the run: a warning alone does not.

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

countsOffunction
function countsOf(findings: readonly Finding[]): { readonly failures: number; readonly warnings: number; }

The counts of a run: failures and warnings.

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

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