IF Commons GitHub

governance/generators

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-repoctl-governance FR-005

The generators of a repository, declared in its configuration as data (commons repoctl 0002-repoctl-governance FR-005; 0009-repoctl-config FR-003): each is a program (or a typed function) that makes files from sources and checks that they are what it makes, with the globs of what it reads and of what it writes and the generators it declares to come after. repoctl sync runs them in the order those facts give, repoctl merge knows a generated file by them and repoctl check runs each one's check.

import type { Generator } from "./generators.ts";
const g: Pick<Generator, "outputs"> = { outputs: ["README.md"] };
g.outputs; // ["README.md"]

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

0 of 12 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.StepRuntypeno test imports it
type StepRun = { readonly code: number; readonly stdout: string; readonly stderr: string };

How a step ended: the status (0 it is as it should be, 1 it is not, anything else it could not run) and what it said.

governance.StepContexttypeno test imports it
type StepContext = { readonly repo: string };

What a typed step is given: the repository's root, as an absolute path.

governance.StepFunctiontypeno test imports it
type StepFunction = (context: StepContext) => Promise<StepRun>;

A step that is a typed function in the configuration, in place of a program.

governance.Steptypeno test imports it
type Step = { readonly kind: "program"; readonly argv: readonly string[] } | { readonly kind: "function"; readonly call: StepFunction; readonly label: string };

A step: the argument vector of a program run from the repository's root (no shell between), or a typed function.

governance.Generatortypeno test imports it
type Generator = { readonly id: StepId; readonly summary: string; /** Makes the files. */ readonly run: Step; … (896 characters)
type Generator = {
  readonly id: StepId;
  readonly summary: string;
  /** Makes the files. */
  readonly run: Step;
  /** Writes nothing and ends with 0 where the files are what `run` makes and with 1 where they are not. */
  readonly check: Step;
  /** What it reads, as globs from the repository's root (`*` is one segment's characters, `**` any number of segments). */
  readonly inputs: readonly string[];
  /** What it writes, as globs from the repository's root. */
  readonly outputs: readonly string[];
  /** The generators it comes after, besides those whose outputs it reads. */
  readonly after: readonly StepId[];
  /** The outputs (globs, a subset of `outputs`) that also hold text a person wrote and that the generator leaves as it finds it, so that a merge keeps the lines of both sides of them before it makes the generated part again. */
  readonly mixed: readonly string[];
};

A generator: what it is, how it makes its files and checks them, and what it reads and writes.

governance.stepTextfunctionno test imports it
function stepText(step: Step): string

The command that makes a step's files again, as a person types it.

Generatortypeno test imports it
type Generator = { readonly id: StepId; readonly summary: string; /** Makes the files. */ readonly run: Step; … (896 characters)
type Generator = {
  readonly id: StepId;
  readonly summary: string;
  /** Makes the files. */
  readonly run: Step;
  /** Writes nothing and ends with 0 where the files are what `run` makes and with 1 where they are not. */
  readonly check: Step;
  /** What it reads, as globs from the repository's root (`*` is one segment's characters, `**` any number of segments). */
  readonly inputs: readonly string[];
  /** What it writes, as globs from the repository's root. */
  readonly outputs: readonly string[];
  /** The generators it comes after, besides those whose outputs it reads. */
  readonly after: readonly StepId[];
  /** The outputs (globs, a subset of `outputs`) that also hold text a person wrote and that the generator leaves as it finds it, so that a merge keeps the lines of both sides of them before it makes the generated part again. */
  readonly mixed: readonly string[];
};

A generator: what it is, how it makes its files and checks them, and what it reads and writes.

Steptypeno test imports it
type Step = { readonly kind: "program"; readonly argv: readonly string[] } | { readonly kind: "function"; readonly call: StepFunction; readonly label: string };

A step: the argument vector of a program run from the repository's root (no shell between), or a typed function.

StepContexttypeno test imports it
type StepContext = { readonly repo: string };

What a typed step is given: the repository's root, as an absolute path.

StepFunctiontypeno test imports it
type StepFunction = (context: StepContext) => Promise<StepRun>;

A step that is a typed function in the configuration, in place of a program.

StepRuntypeno test imports it
type StepRun = { readonly code: number; readonly stdout: string; readonly stderr: string };

How a step ended: the status (0 it is as it should be, 1 it is not, anything else it could not run) and what it said.

stepTextfunctionno test imports it
function stepText(step: Step): string

The command that makes a step's files again, as a person types it.

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