IF Commons GitHub

render

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0003-host FR-003

Generated files (commons 0003-host FR-003, FR-004, FR-007, FR-008): a template is a TypeScript function from data to a list of GeneratedFiles, and a generated file is made only here, so that its path is a RepoPath inside the root, its name carries .auto. (a Git hook, whose name Git fixes and which lives in .ergonex/hooks/, is the one exception), its header names its generator and says it is not to be edited, and its bytes are the same for the same data on every operating system: UTF-8 with no byte-order mark, LF line endings and one final newline.

There is no template language here: no parser, no eval, no new Function and no interpolation of data into code; a file's body is text a template built, or JSON a template built as a value, which generated writes with the header as its first member (_generated). A path that holds .., is absolute or names a drive is refused by repoPath before any file exists. Two files whose paths are one after Unicode normalization and case folding are both refused and named (0002-workspace-model FR-011), and a file inside a repository's working tree is refused (FR-008).

Source: commons/ergonex/src/render.ts

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

checkFilesfunction
function checkFiles(files: readonly GeneratedFile[], repositories: readonly string[]): Result<readonly GeneratedFile[], readonly GenerateError[]>

A set of files checked together: two whose paths are one after folding are refused (each naming the other), and so is one inside the working tree of a repository of the workspace (repositories are their paths below the root). The files are returned in the order of their paths, folded, so that the same data gives the same order.

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

describeGenerateErrorfunctionno test imports it
function describeGenerateError(e: GenerateError): string

A refusal as one sentence.

FileBodytypeno test imports it
type FileBody =
  | { readonly format: "json"; readonly value: JsonObject }
  | { readonly format: "markdown"; readonly text: string }
  | { readonly format: "yaml"; readonly text: string }
  | { readonly format: "gitconfig"; readonly text: string }
  | { readonly format: "envrc"; readonly text: string }
  | { readonly format: "sh"; readonly text: string };

What a template gives of a file's body, by its format; the header is added by generated.

FileModetypeno test imports it
type FileMode = "0644" | "0755";

The mode of a generated file: 0644, or 0755 for a script.

fileDigestfunctionno test imports it
function fileDigest(file: GeneratedFile): Promise<Sha256>

The SHA-256 of a generated file's bytes.

GeneratedFiletypeno test imports it
type GeneratedFile = {
  /** Its path below the root, with `/` between segments. */
  readonly path: RepoPath;
  /** Its bytes as text: header included, LF only, one final newline. */
  readonly content: string;
  readonly mode: FileMode;
  /** The generator the header names, such as `ergonex templates/agents`. */
  readonly generator: string;
};

A file a template makes (ergonex:GeneratedFile).

generatedfunction
function generated(path: string, body: FileBody, options: { readonly generator: string; readonly mode?: FileMode | undefined; }): Result<GeneratedFile, GenerateError>

A generated file: its path checked, its name checked to carry .auto. (a hook in .ergonex/hooks/ excepted), its header added, its bytes normalized. The same arguments give the same bytes.

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

generatedPathfunctionno test imports it
function generatedPath(path: string): Result<RepoPath, GenerateError>

A path as a generated file's: portable segments, never absolute, never .., never a drive.

GenerateErrortypeno test imports it
type GenerateError = | { readonly kind: "bad-path"; readonly path: string; readonly reason: string; … (511 characters)
type GenerateError =
  | {
      readonly kind: "bad-path";
      readonly path: string;
      readonly reason: string;
    }
  | { readonly kind: "not-auto"; readonly path: string }
  | {
      readonly kind: "collision";
      readonly path: string;
      readonly other: string;
    }
  | {
      readonly kind: "inside-repository";
      readonly path: string;
      readonly repository: string;
    }
  | {
      readonly kind: "bad-data";
      readonly what: string;
      readonly reason: string;
    };

Why a file was refused.

HOOKS_FOLDERconstno test imports it
const HOOKS_FOLDER: ".ergonex/hooks"

The folder of the hooks, below the root.

headerTextfunction
function headerText(generator: string): string

The text of the header of a generated file: what made it, and that it is not to be edited.

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

isAutoNamefunctionno test imports it
function isAutoName(name: string): boolean

Whether a file name carries .auto. (AGENTS.auto.md) or ends in .auto (.envrc.auto).

normalizeTextfunctionno test imports it
function normalizeText(text: string): string

Text as a generated file keeps it: LF line endings, no byte-order mark, exactly one final newline.

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