IF Commons GitHub

physical/dialect/types

Written to: 3 requirements: 3 proved, 0 partly, 0 failing, 0 with no test recorded. 0004-archon-dialects FR-001, 0004-archon-dialects FR-002, 0004-archon-dialects FR-006

The port of a dialect: the whole of what Archon knows of a tool. A dialect says what it can guarantee, as data, renders an order and a plan to files, and gives the steps its tool needs to carry the plan out. What it renders is generated, and the digest of what it rendered does not depend on the order the files were made in.

import { GENERATED_MARK, isGenerated, renderHeader } from "./types.ts";
isGenerated(`${renderHeader("yaml")}\n- hosts: all`); // true

Source: commons/archon/src/physical/dialect/types.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.

PlanGuaranteetypeno test imports it
type PlanGuarantee = "faithful" | "partial" | "none";

How faithful the plan of a tool is: faithful shows what would change, partial shows some of it and none shows nothing (the tool has no check mode).

Guaranteestype
type Guarantees = { /** The kinds of resource it can carry out. */ readonly kinds: readonly ResourceKindId[]; /** … (421 characters)
type Guarantees = {
  /** The kinds of resource it can carry out. */
  readonly kinds: readonly ResourceKindId[];
  /** The classes of subject it can reach. */
  readonly subjects: readonly SubjectClass[];
  readonly plan: PlanGuarantee;
  /** Whether applying twice changes nothing the second time has been shown by its conformance suite. */
  readonly idempotence: "proven" | "unproven";
  readonly destroy: boolean;
};

What a dialect says it can do, as data.

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

Renderedtypeno test imports it
type Rendered = { readonly files: ReadonlyMap<string, string>; readonly digest: Sha256 };

What a dialect rendered: files by path, and the digest of all of them.

DialectSteptypeno test imports it
type DialectStep = { /** The requirements it carries out. */ readonly covers: readonly RequirementId[]; readonly s… (515 characters)
type DialectStep = {
  /** The requirements it carries out. */
  readonly covers: readonly RequirementId[];
  readonly summary: string;
  /** The argument vector that does it: it names the digest of what was rendered. */
  readonly apply: readonly string[];
  /** The argument vector that looks and changes nothing; none where the tool has no check mode. */
  readonly check: readonly string[] | undefined;
  /** The exit status of the check that means something would change. */
  readonly changedExit?: number;
};

One step the tool needs, for the executor of headless.

Dialecttype
type Dialect = { readonly id: DialectId; /** The tool, and the version the dialect pins. */ readonly tool: { reado… (505 characters)
type Dialect = {
  readonly id: DialectId;
  /** The tool, and the version the dialect pins. */
  readonly tool: { readonly name: string; readonly version: string };
  readonly guarantees: Guarantees;
  /** Renders an order and its plan to files, or says why it cannot. */
  readonly render: (order: Order, plan: Plan) => Promise<Result<Rendered, readonly string[]>>;
  /** The steps the tool needs to carry the plan out. */
  readonly steps: (plan: Plan, rendered: Rendered) => readonly DialectStep[];
};

A dialect.

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

GENERATED_MARKconst
const GENERATED_MARK: "GENERATED by archon; do not edit"

The sentence every generated file carries.

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

FileKindtypeno test imports it
type FileKind = "yaml" | "shell" | "hcl" | "text" | "json";

The kinds of file a dialect renders.

renderHeaderfunction
function renderHeader(kind: FileKind): string

The line that says a file is generated, for a kind of file: a comment where the kind has comments, and a member _generated for JSON.

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

isGeneratedfunction
function isGenerated(text: string): boolean

Whether a file says it is generated: the mark is in its first lines.

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

renderedOffunction
function renderedOf(files: ReadonlyMap<string, string>): Promise<Result<Rendered, readonly string[]>>

What a set of files is, with the digest of them in the order of their paths.

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

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