Leyman

File format ​

ts
// @generated-signature v1:3f9a0c5e8b1d2f47a6c9e0b3d5f71824 Generated file. Do not edit outside of manual sections.
export class 
AutoGenerated
 {
    // @manual-start value
    static readonly 
VALUE
 = 123;
    // @manual-end value
}

Anything that follows these rules can be verified, whichever tool wrote it.

Signature token ​

@generated-signature v1: followed by 32 lowercase hex characters.

  • It must appear exactly once, anywhere in the file. A second one is malformed (duplicate-signature), and a version other than v1 is malformed (unsupported-version).
  • sign() inserts it as the first line, in the file's comment syntax, unless the text already has one. After a #! shebang or <?xml declaration, it goes on the second line, since those must stay first. In Markdown (or any file with <!-- --> comments) that starts with --- front matter, it goes after the closing ---.
  • A generator with its own header can put the token there with signatureToken(), which has a placeholder hash for sign() to fill in.

Manual sections ​

A line containing @manual-start <id>, and a later line containing @manual-end <id>. The body is every line in between.

  • The marker must be at the start of the line, or after whitespace. The rest of the line is free, so any comment syntax works, including ones with an end like <!-- @manual-start id -->.
  • Ids are letters, digits, _, . and -, and unique per file.
  • Sections don't nest.

Markers that break these rules make the file malformed, with one of the reasons duplicate-section, invalid-section-id, nested-section, unclosed-section or unopened-section.

Hash ​

SHA-256 of the file, truncated to its first 128 bits, after:

  1. normalizing \r\n to \n;
  2. replacing the token's hash with zeros;
  3. removing every section's body. The marker lines stay, so adding, removing or renaming a section changes the hash.

v1 versions this algorithm, so it can change without making existing files ambiguous.

Manifest ​

A JSON file recording generated files, for files that can't carry a token, like JSON. populate-files writes it, and the manifest helpers read and check it.

json
{
  "version": 1,
  "files": {
    "schema.json": { "hash": "v1:48ceef79954dd3f12f934fd8b208a896" },
    "types.ts": {
      "signature": "inline",
      "inputs": { "generator": "genever@1.4.0", "./types.json": "v1:91612d6a27e9d7e72e322fb4090c46ec" }
    }
  }
}
  • files keys are paths relative to the manifest's directory, with / separators, sorted.
  • hash is the file's contentHash: v1: and the first 128 bits of the SHA-256 of its content, with \r\n normalized to \n. Manual sections are not left out, so a file with manual sections must be signed inline.
  • signature: "inline" means the file carries its own token, which is checked instead.
  • inputs is optional, and free for the generator: usually hashes of what produced the file. This package doesn't interpret it.