IF Commons GitHub

affected

What a change affects (commons 0027-commons-libraries FR-019 to FR-022): the files a library's checks read, taken from its package and its sources, and the libraries that a list of changed files affects, so that CI runs what changed and nothing else.

bun commons/libraries/src/affected.ts --base origin/main the libraries a change since the merge base with origin/main affects, as {"include":[{"name","folder","verify"}]} bun commons/libraries/src/affected.ts --files a.ts,b/c.ts the same for a list of files (paths from the repository's root) bun commons/libraries/src/affected.ts --all every library bun commons/libraries/src/affected.ts --inputs data the folders and files the library data reads, one a line other flags: --repo DIR (the repository, the working folder by default)

A library depends on another folder of commons where its package.json names it by path (link:, file: or workspace:), and what it reads of it is what its sources import from the package (the exports of the dependency say which file each import is), what its scripts run by a path to another folder (bun ../libraries/src/check.ts), and everything those files import by a relative path, followed file by file. An import that no entry of exports names takes the whole dependency. The library's inputs are also commons/tools/**, .github/actions/**, its own workflow and its own folder. A library is affected where a changed file is among its inputs, or where a library it depends on is affected. Nothing is run and nothing is written; the result is the same for the same files.

import { affectedBy } from "./affected.ts";
affectedBy(".", ["commons/data/engine/api.ts"]).map((l) => l.name); // ["data"]

Spec: 0001-libraries FR-003

Source: commons/libraries/src/affected.ts

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

Inputstypeno test imports it
type Inputs = { /** The paths of the library's inputs: `commons/<name>/` and each folder (`commons/core/src/**`) or fi… (784 characters)
type Inputs = {
  /** The paths of the library's inputs: `commons/<name>/` and each folder (`commons/core/src/**`) or file the library takes from another. */
  readonly paths: readonly string[];
  /** The folders of commons that the library depends on through its package. */
  readonly dependsOn: readonly string[];
  /** Every file of another folder that it reads, from the repository's root, in order. */
  readonly files: readonly string[];
  /** The libraries whose package its sources import by name: what its types and its tests read, which its scripts do not add. */
  readonly imports: readonly string[];
  /** The paths its types and its tests read: its folder and what its imports reach (no tool its scripts run, no workflow). */
  readonly codePaths: readonly string[];
};

What a library reads: its folder, the folders and files it takes from others, what it depends on, and the files it imports one by one.

SHAREDconstno test imports it
const SHARED: readonly ["commons/tools/**", ".github/actions/**"]

The folders whose change is every library's change: the tools that check a library and the action that installs Bun.

inputsOffunction
function inputsOf(repo: string, name: string): Inputs

What the library name reads (FR-020).

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

matchesfunction
function matches(paths: readonly string[], file: string): boolean

Whether a path of the repository is among the paths of an input: dir/** is the folder and what is under it, anything else the file.

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

everyLibraryfunctionno test imports it
function everyLibrary(repo: string): readonly (Library & { readonly folder: string; })[]

Every library of the repository, with its folder.

Reachtypeno test imports it
type Reach = "verify" | "code";

What a change reaches: verify, everything the library's verify reads (its scripts' tools, the shared tools, its workflow: what CI runs), or code, what its types and its tests read (its folder and the packages its sources import, which is what the development loop runs).

affectedByfunction
function affectedBy(repo: string, changed: readonly string[], reach?: Reach): readonly (Library & { readonly folder: string; })[]

The libraries that a list of changed files affects (FR-021): those with a changed file among their inputs, and those that depend on one of these, in order of their names.

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

changedSincefunction
function changedSince(repo: string, base: string): Promise<readonly string[] | undefined>

The files changed since the merge base of base and the head, the working tree's tracked and new files included; undefined where Git cannot say.

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

matrixOffunction
function matrixOf(libs: readonly (Library & { readonly folder: string; })[]): string

The matrix a workflow reads: {"include":[{"name","folder","verify"}]}.

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

mainfunction
function main(argv: readonly string[]): Promise<number>

The command line. Returns the exit status: 0, or 2 for a usage error.

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

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