generated-signature 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jacob Ley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,269 @@
-# Temporary Holding Version
+<div style="text-align:center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# generated-signature
+Sign generated files so hand edits are detected, while keeping manual sections editable.
+
+[![npm package](https://badge.fury.io/js/generated-signature.svg)](https://www.npmjs.com/package/generated-signature)
+[![License](https://img.shields.io/npm/l/generated-signature.svg)](https://github.com/JacobLey/leyman/blob/main/tools/generated-signature/generated-signature/LICENSE)
+
+</div>
+
+Guides and the full reference are on the [docs site](https://jacobley.github.io/leyman/generated-signature/).
+
+- **Offline check**: `verify()` needs only the file, not the generator, so it is cheap enough for a lint rule or a pre-commit hook.
+- **Manual sections**: mark regions a person may edit. Their content is left out of the signature and carried over when the file is regenerated.
+- **Any text format**: markers own whole lines, so verification doesn't need to know the comment syntax. Helpers render markers for common file types.
+- **ESLint rule**: `generated-signature/eslint` reports hand-edited files in the editor.
+- **Zero dependencies**: only `node:crypto`. `eslint` is an optional peer, for the ESLint entry point only.
+
+Files that can't hold comments (like JSON) are recorded in a [manifest](#manifest) instead. Not a freshness check: a valid signature means nobody edited the file, not that regenerating it would produce the same output.
+
+## Contents
+
+- [Install](#install)
+- [Example](#example)
+- [Usage](#usage)
+  - [File format](#file-format)
+- [API](#api)
+  - [sign](#signtext-options)
+  - [signatureToken](#signaturetoken)
+  - [verify](#verifytext)
+  - [manualSection](#manualsectionoptions)
+  - [mergeSections](#mergesectionsparams)
+  - [parseSections](#parsesectionstext)
+  - [commentStyle](#commentstylefilepath)
+  - [Manifest](#manifest)
+  - [Errors](#errors)
+- [ESLint rules](#eslint-rules)
+  - [generated-signature/valid](#generated-signaturevalid)
+- [Compared to alternatives](#compared-to-alternatives)
+- [Also See](#also-see)
+
+## Install
+
+```sh
+npm i generated-signature
+```
+
+## Example
+
+```ts
+import { manualSection, mergeSections, sign, verify } from 'generated-signature';
+
+const generated = `export class AutoGenerated {
+${manualSection({ id: 'value', body: 'static readonly VALUE = 123;', indent: '    ', filePath: 'foo.ts' })}
+
+    add(input: number): number {
+        return input + AutoGenerated.VALUE;
+    }
+}
+`;
+
+// First write: insert a signature line.
+let text = sign(generated, { filePath: 'foo.ts' });
+
+verify(text); // { status: 'valid' }
+verify(text.replace('123', '456')); // { status: 'valid' }, inside a manual section
+verify(text.replace('input +', 'input -')); // { status: 'invalid' }
+
+// Regenerating: keep what people wrote in manual sections.
+const existing = text.replace('123', '456');
+const { text: merged, orphans } = mergeSections({ generated, existing });
+text = sign(merged, { filePath: 'foo.ts' }); // VALUE is still 456
+```
+
+## Usage
+
+`generated-signature` is an ESM module. It must be `import`ed. To load from a CJS module, use dynamic import: `const { verify } = await import('generated-signature');`.
+
+A generator renders its output (with `manualSection()` for editable regions), merges in the existing file's sections with `mergeSections()`, and signs the result with `sign()`. Anything can then call `verify()` on the file to find out whether someone edited it outside the manual sections.
+
+[`populate-files`](https://www.npmjs.com/package/populate-files) is the intended writer, but the package works on plain strings and has no opinion on how files are written.
+
+### File format
+
+```ts
+// @generated-signature v1:3f9a0c… Generated file. Do not edit outside of manual sections.
+export class AutoGenerated {
+    // @manual-start value
+    static readonly VALUE = 123;
+    // @manual-end value
+}
+```
+
+- **Signature token**: `@generated-signature v1:` followed by 32 lowercase hex characters. It must appear exactly once, anywhere in the file. `sign()` inserts it as the first line (after a shebang or XML declaration) unless the text already has one, so a generator with its own header can place it there with [`signatureToken()`](#signaturetoken).
+- **Manual sections**: a line containing `@manual-start <id>` and a later line containing `@manual-end <id>`. Ids are letters, digits, `_`, `.` and `-`, unique per file. Sections do not nest. The marker must be at the start of the line or after whitespace.
+- **Hash**: SHA-256 (first 128 bits) of the file with `\r\n` normalized to `\n`, the token's hash replaced by zeros, and every section body removed. The marker lines are hashed, so adding, removing or renaming a section is detected. `v1` versions this algorithm.
+
+## API
+
+### `sign(text, options?)`
+
+Fills in the signature token's hash, inserting a signature line first if the text has none.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `text` | `string` | Required. Generated file content. |
+| `options` | `object` | Required only when `text` has no token. See below. |
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `filePath` / `comment` | `string` / `CommentStyle` | — | Required. Comment syntax for the inserted line, either looked up from a file name (see [`commentStyle`](#commentstylefilepath)) or given directly. |
+| `message` | `string` | `'Generated file. Do not edit outside of manual sections.'` | Text after the token on the inserted line. |
+
+**Returns** `string`: the signed text. Signing is idempotent, and preserves `\r\n` line breaks.
+
+**Throws** `GeneratedSignatureMalformedError` for a duplicate or unsupported token, or malformed sections. `GeneratedSignatureCommentStyleError` when a line must be inserted and `filePath` has no known comment syntax. `TypeError` when a line must be inserted and no options are given.
+
+---
+
+### `signatureToken()`
+
+**Returns** `string`: a token with a placeholder hash. Generators with their own header put it there, and `sign()` fills in the hash instead of inserting a line:
+
+```ts
+sign(`// AUTO-BARREL ${signatureToken()}\nexport * from './foo.js';\n`);
+```
+
+---
+
+### `verify(text)`
+
+Checks the file's signature.
+
+**Returns** `VerifyResult`, discriminated on `status`:
+
+| `status` | Meaning |
+|----------|---------|
+| `'valid'` | Signed, and unchanged outside manual sections. |
+| `'invalid'` | Signed, but changed outside manual sections. |
+| `'unsigned'` | No signature token. |
+| `'malformed'` | Has an `error: GeneratedSignatureMalformedError` explaining what can't be read. |
+
+Never throws for any input string.
+
+---
+
+### `manualSection(options)`
+
+Renders a manual section for a generator to embed.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `id` | `string` | — | Required. Section id. |
+| `body` | `string` | `''` | Default content, until someone edits it. A trailing line break is ignored. |
+| `indent` | `string` | `''` | Prefixed to both markers and every non-blank body line. |
+| `filePath` / `comment` | | — | Required. Comment syntax, as for [`sign`](#signtext-options). |
+
+**Returns** `string`: the start marker, body and end marker lines, without a trailing line break.
+
+**Throws** `GeneratedSignatureSectionIdError` for an invalid id. `GeneratedSignatureCommentStyleError` for an unknown file type.
+
+---
+
+### `mergeSections(params)`
+
+Carries manual sections from an existing file into freshly generated text, matched by id.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `generated` | `string` | Required. New generator output, with default section bodies. |
+| `existing` | `string` | Required. Current file content. |
+
+**Returns** `{ text: string, orphans: readonly string[] }`. `text` is `generated` with each section's body taken from `existing` when it has the same id. `orphans` lists ids that only `existing` has and whose body isn't blank: dropping them would lose someone's edits, so callers should usually fail on them.
+
+**Throws** `GeneratedSignatureMalformedError` if either text's sections are malformed.
+
+---
+
+### `parseSections(text)`
+
+**Returns** `ReadonlyMap<string, ManualSection>` in file order, where `ManualSection` is `{ id, body, startLine, endLine }`. `body` is everything between the marker lines, including its final line break. Lines are 1-indexed.
+
+**Throws** `GeneratedSignatureMalformedError` if markers are unbalanced, nested, duplicated or have an invalid id.
+
+---
+
+### `commentStyle(filePath)`
+
+**Returns** the line comment syntax for a file, as `CommentStyle` (`{ start: string, end?: string }`), looked up by extension or file name (`Dockerfile`, `.gitignore`, …). `null` if unknown, or for formats without comments like `.json`.
+
+---
+
+### Manifest
+
+A JSON file recording generated files that don't carry their own token, e.g. JSON. [`populate-files`](https://www.npmjs.com/package/populate-files) writes it; these helpers read and check it.
+
+```json
+{
+  "version": 1,
+  "files": {
+    "schema.json": { "hash": "v1:…" },
+    "types.ts": { "signature": "inline", "inputs": { "generator": "genever@1.4.0" } }
+  }
+}
+```
+
+- Paths are relative to the manifest's directory, with `/` separators.
+- `hash` is the [`contentHash`](#contenthashcontent) of the file. `signature: "inline"` means the file carries its own token, which is checked instead.
+- `inputs` is optional: hashes of what produced the file, written and checked by the generator. This package doesn't interpret it.
+
+| Function | Description |
+|----------|-------------|
+| <a id="contenthashcontent"></a>`contentHash(content: string \| Uint8Array): string` | `v1:` and 32 hex characters of SHA-256. `\r\n` counts as `\n`, also in bytes. Manual sections are **not** excluded, so a file with manual sections should be signed inline. |
+| `verifyManifestEntry(content, entry): VerifyResult` | `valid` or `invalid` for a `hash` entry; [`verify()`](#verifytext)'s result for an `inline` entry. |
+| `parseManifest(text): Manifest` | Parses and validates. Throws `GeneratedSignatureManifestError` if the text is not a valid manifest. |
+| `serializeManifest(files): string` | Manifest text, with paths and inputs sorted so the output doesn't depend on write order. |
+
+---
+
+### Errors
+
+All errors extend the abstract `GeneratedSignatureError`.
+
+| Error | Properties | Thrown when |
+|-------|------------|-------------|
+| `GeneratedSignatureMalformedError` | `reason: MalformedReason`, `line: number` | A token or manual section can't be interpreted. `reason` is one of `'duplicate-section'`, `'duplicate-signature'`, `'invalid-section-id'`, `'nested-section'`, `'unclosed-section'`, `'unopened-section'`, `'unsupported-version'`. |
+| `GeneratedSignatureCommentStyleError` | `filePath: string` | No comment syntax is known for a file. |
+| `GeneratedSignatureSectionIdError` | `id: string` | `manualSection()` gets an invalid id. |
+| `GeneratedSignatureManifestError` | | `parseManifest()` gets text that is not a valid manifest. |
+
+## ESLint rules
+
+The plugin is a separate entry point, so importing `generated-signature` never loads it, and `eslint` is only needed when you use it:
+
+```js
+// eslint.config.js
+import generatedSignature from 'generated-signature/eslint';
+
+export default [generatedSignature.configs.recommended];
+```
+
+`configs.recommended` registers the plugin (namespace `generated-signature`) and turns on every rule below as an error.
+
+### `generated-signature/valid`
+
+Reports a file whose signature doesn't match (it was edited outside its manual sections), or whose token or manual sections are malformed. Unsigned files are ignored. There is no autofix: re-signing would just approve the edit. Regenerate the file instead, or move the change into a manual section.
+
+```ts
+// @generated-signature v1:… Generated file. Do not edit outside of manual sections.
+export const generated = 2; // ❌ edited by hand
+// @manual-start custom
+export const custom = 2; // ✅ manual sections may be edited
+// @manual-end custom
+```
+
+ESLint only lints the files it is configured for. To check every signed file whatever its type, call [`verify()`](#verifytext) on it.
+
+## Compared to alternatives
+
+| | Signature | Manual sections | Language |
+|---|---|---|---|
+| `generated-signature` | Yes | Yes | Any text format, JS API |
+| Meta's SignedSource / `@partially-generated` | Yes | Yes | Internal tooling, Hack/JS, not a general library |
+| [cog](https://nedbatchelder.com/code/cog/) `--checksum` | Yes | Inverse: generated regions in a handwritten file | Python |
+| Go's `// Code generated ... DO NOT EDIT.` | No, a convention only | No | Go |
+
+## Also See
+
+- [`populate-files`](https://www.npmjs.com/package/populate-files): writes generated files and keeps them in sync

package/dist/eslint/plugin.d.ts

@@ -0,0 +1,22 @@
+import type { ESLint, Linter } from 'eslint';
+import { valid } from './rules/valid.js';
+declare const NAMESPACE = "generated-signature";
+interface GeneratedSignaturePlugin extends ESLint.Plugin {
+    meta: {
+        name: string;
+        namespace: typeof NAMESPACE;
+    };
+    rules: {
+        valid: typeof valid;
+    };
+    configs: {
+        recommended: Linter.Config;
+    };
+}
+/**
+ * ESLint plugin, from the `generated-signature/eslint` entry point so the main entry point never
+ * loads it. `eslint` is only used for types.
+ */
+declare const plugin: GeneratedSignaturePlugin;
+export default plugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/eslint/plugin.js

@@ -0,0 +1,24 @@
+import { valid } from './rules/valid.js';
+const NAMESPACE = 'generated-signature';
+const plugin = {
+    meta: {
+        name: 'generated-signature/eslint',
+        namespace: NAMESPACE
+    },
+    rules: {
+        valid
+    },
+    configs: {
+        recommended: {
+            rules: {
+                [`${NAMESPACE}/valid`]: 'error'
+            }
+        }
+    }
+};
+plugin.configs.recommended.plugins = {
+    [NAMESPACE]: plugin
+};
+export default plugin;
+
+//# sourceMappingURL=plugin.js.map

package/dist/eslint/rules/valid.d.ts

@@ -0,0 +1,6 @@
+import type { Rule } from 'eslint';
+/**
+ * Report generated files that were edited outside of their manual sections.
+ */
+export declare const valid: Rule.RuleModule;
+//# sourceMappingURL=valid.d.ts.map

package/dist/eslint/rules/valid.js

@@ -0,0 +1,45 @@
+import { verify } from '../../lib/signature.js';
+export const valid = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow editing generated files outside of their manual sections',
+            url: 'https://jacobley.github.io/leyman/generated-signature/guides/eslint#generated-signature-valid'
+        },
+        messages: {
+            invalid: 'Generated file was edited outside of its manual sections. Regenerate it instead.',
+            malformed: 'Generated file is malformed: {{ reason }}.'
+        },
+        schema: []
+    },
+    create: (context)=>({
+            Program: ()=>{
+                const { sourceCode } = context;
+                const result = verify(sourceCode.text);
+                if (result.status === 'invalid') {
+                    const index = Math.max(sourceCode.text.indexOf('@generated-signature'), 0);
+                    const start = sourceCode.getLocFromIndex(index);
+                    context.report({
+                        loc: {
+                            start,
+                            end: start
+                        },
+                        messageId: 'invalid'
+                    });
+                } else if (result.status === 'malformed') {
+                    context.report({
+                        loc: {
+                            line: result.error.line,
+                            column: 0
+                        },
+                        messageId: 'malformed',
+                        data: {
+                            reason: result.error.reason
+                        }
+                    });
+                }
+            }
+        })
+};
+
+//# sourceMappingURL=valid.js.map

package/dist/generated-signature.d.ts

@@ -0,0 +1,12 @@
+export type { CommentOptions, CommentStyle } from './lib/comment-style.js';
+export type { MalformedReason } from './lib/errors.js';
+export type { Manifest, ManifestEntry, ManifestInputs } from './lib/manifest.js';
+export type { ManualSectionOptions, MergeResult } from './lib/merge.js';
+export type { ManualSection } from './lib/sections.js';
+export type { SignOptions, VerifyResult } from './lib/signature.js';
+export { commentStyle } from './lib/comment-style.js';
+export { GeneratedSignatureCommentStyleError, GeneratedSignatureError, GeneratedSignatureMalformedError, GeneratedSignatureManifestError, GeneratedSignatureSectionIdError, } from './lib/errors.js';
+export { contentHash, parseManifest, serializeManifest, verifyManifestEntry, } from './lib/manifest.js';
+export { manualSection, mergeSections, parseSections } from './lib/merge.js';
+export { sign, signatureToken, verify } from './lib/signature.js';
+//# sourceMappingURL=generated-signature.d.ts.map

package/dist/generated-signature.js

@@ -0,0 +1,7 @@
+export { commentStyle } from './lib/comment-style.js';
+export { GeneratedSignatureCommentStyleError, GeneratedSignatureError, GeneratedSignatureMalformedError, GeneratedSignatureManifestError, GeneratedSignatureSectionIdError } from './lib/errors.js';
+export { contentHash, parseManifest, serializeManifest, verifyManifestEntry } from './lib/manifest.js';
+export { manualSection, mergeSections, parseSections } from './lib/merge.js';
+export { sign, signatureToken, verify } from './lib/signature.js';
+
+//# sourceMappingURL=generated-signature.js.map

package/dist/lib/comment-style.d.ts

@@ -0,0 +1,19 @@
+export interface CommentStyle {
+    readonly start: string;
+    readonly end?: string;
+}
+export type CommentOptions = {
+    readonly comment: CommentStyle;
+} | {
+    readonly filePath: string;
+};
+/**
+ * Look up the line comment syntax for a file, based on its name.
+ *
+ * @param filePath - path (or name) of the file
+ * @returns comment style, or `null` if unknown (or the format has no comments, like JSON)
+ */
+export declare const commentStyle: (filePath: string) => CommentStyle | null;
+export declare const resolveCommentStyle: (options: CommentOptions) => CommentStyle;
+export declare const renderComment: (style: CommentStyle, text: string) => string;
+//# sourceMappingURL=comment-style.d.ts.map

package/dist/lib/comment-style.js

@@ -0,0 +1,132 @@
+import Path from 'node:path';
+import { GeneratedSignatureCommentStyleError } from './errors.js';
+const slashes = {
+    start: '//'
+};
+const hash = {
+    start: '#'
+};
+const block = {
+    start: '/*',
+    end: '*/'
+};
+const markup = {
+    start: '<!--',
+    end: '-->'
+};
+const dashes = {
+    start: '--'
+};
+const byExtension = new Map([
+    ...[
+        '.c',
+        '.cc',
+        '.cjs',
+        '.cpp',
+        '.cs',
+        '.cts',
+        '.go',
+        '.h',
+        '.hpp',
+        '.java',
+        '.js',
+        '.json5',
+        '.jsonc',
+        '.jsx',
+        '.kt',
+        '.less',
+        '.mjs',
+        '.mts',
+        '.rs',
+        '.scss',
+        '.swift',
+        '.ts',
+        '.tsx'
+    ].map((ext)=>[
+            ext,
+            slashes
+        ]),
+    ...[
+        '.bash',
+        '.cfg',
+        '.conf',
+        '.env',
+        '.ini',
+        '.pl',
+        '.properties',
+        '.py',
+        '.r',
+        '.rb',
+        '.sh',
+        '.toml',
+        '.yaml',
+        '.yml',
+        '.zsh'
+    ].map((ext)=>[
+            ext,
+            hash
+        ]),
+    [
+        '.css',
+        block
+    ],
+    ...[
+        '.htm',
+        '.html',
+        '.md',
+        '.mdx',
+        '.svg',
+        '.vue',
+        '.xml'
+    ].map((ext)=>[
+            ext,
+            markup
+        ]),
+    ...[
+        '.hs',
+        '.lua',
+        '.sql'
+    ].map((ext)=>[
+            ext,
+            dashes
+        ])
+]);
+const byFileName = new Map([
+    [
+        '.gitattributes',
+        hash
+    ],
+    [
+        '.gitignore',
+        hash
+    ],
+    [
+        '.npmignore',
+        hash
+    ],
+    [
+        'Dockerfile',
+        hash
+    ],
+    [
+        'Makefile',
+        hash
+    ]
+]);
+export const commentStyle = (filePath)=>{
+    const base = Path.basename(filePath);
+    return byFileName.get(base) ?? byExtension.get(Path.extname(base).toLowerCase()) ?? byFileName.get(base.split('.', 1)[0]) ?? null;
+};
+export const resolveCommentStyle = (options)=>{
+    if ('comment' in options) {
+        return options.comment;
+    }
+    const style = commentStyle(options.filePath);
+    if (style === null) {
+        throw new GeneratedSignatureCommentStyleError(options.filePath);
+    }
+    return style;
+};
+export const renderComment = (style, text)=>style.end === undefined ? `${style.start} ${text}` : `${style.start} ${text} ${style.end}`;
+
+//# sourceMappingURL=comment-style.js.map

package/dist/lib/errors.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Base class of every error thrown by this package.
+ *
+ * All instances of this error will be of a subclass with a more specific failure reason.
+ */
+export declare abstract class GeneratedSignatureError extends Error {
+}
+export type MalformedReason = 'duplicate-section' | 'duplicate-signature' | 'invalid-section-id' | 'nested-section' | 'unclosed-section' | 'unopened-section' | 'unsupported-version';
+/**
+ * The file's signature token or manual section markers can't be interpreted.
+ */
+export declare class GeneratedSignatureMalformedError extends GeneratedSignatureError {
+    readonly reason: MalformedReason;
+    /**
+     * 1-indexed line of the offending marker or token.
+     */
+    readonly line: number;
+    constructor({ reason, line, detail, }: {
+        reason: MalformedReason;
+        line: number;
+        detail: string;
+    });
+}
+/**
+ * A signature line has to be inserted, but no comment syntax is known for the file.
+ */
+export declare class GeneratedSignatureCommentStyleError extends GeneratedSignatureError {
+    readonly filePath: string;
+    constructor(filePath: string);
+}
+/**
+ * A manual section id can't be used in a marker.
+ */
+export declare class GeneratedSignatureSectionIdError extends GeneratedSignatureError {
+    readonly id: string;
+    constructor(id: string);
+}
+/**
+ * A manifest file can't be read.
+ */
+export declare class GeneratedSignatureManifestError extends GeneratedSignatureError {
+    constructor(detail: string, options?: ErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/lib/errors.js

@@ -0,0 +1,36 @@
+export class GeneratedSignatureError extends Error {
+}
+export class GeneratedSignatureMalformedError extends GeneratedSignatureError {
+    reason;
+    line;
+    constructor({ reason, line, detail }){
+        super(`Malformed generated file (${reason}) at line ${line}: ${detail}`);
+        this.name = 'GeneratedSignatureMalformedError';
+        this.reason = reason;
+        this.line = line;
+    }
+}
+export class GeneratedSignatureCommentStyleError extends GeneratedSignatureError {
+    filePath;
+    constructor(filePath){
+        super(`No known comment syntax for ${filePath}, pass a comment style explicitly`);
+        this.name = 'GeneratedSignatureCommentStyleError';
+        this.filePath = filePath;
+    }
+}
+export class GeneratedSignatureSectionIdError extends GeneratedSignatureError {
+    id;
+    constructor(id){
+        super(`Invalid manual section id "${id}", only letters, digits, "_", "." and "-" allowed`);
+        this.name = 'GeneratedSignatureSectionIdError';
+        this.id = id;
+    }
+}
+export class GeneratedSignatureManifestError extends GeneratedSignatureError {
+    constructor(detail, options){
+        super(`Invalid generated-signature manifest: ${detail}`, options);
+        this.name = 'GeneratedSignatureManifestError';
+    }
+}
+
+//# sourceMappingURL=errors.js.map

package/dist/lib/manifest.d.ts

@@ -0,0 +1,63 @@
+import type { VerifyResult } from './signature.js';
+declare const VERSION = 1;
+/**
+ * Hashes of what produced a file, e.g. `{ "generator": "genever@1.0.0", "./user.json": "v1:…" }`.
+ * Opaque to this package: the generator decides what to record, and how to check it.
+ */
+export type ManifestInputs = Readonly<Record<string, string>>;
+export type ManifestEntry = {
+    /**
+     * {@link contentHash} of the file.
+     */
+    readonly hash: string;
+    readonly inputs?: ManifestInputs;
+} | {
+    /**
+     * The file carries its own signature token, which is checked instead of a hash.
+     */
+    readonly signature: 'inline';
+    readonly inputs?: ManifestInputs;
+};
+export interface Manifest {
+    readonly version: typeof VERSION;
+    /**
+     * Entries by path relative to the manifest's directory, with `/` separators.
+     */
+    readonly files: Readonly<Record<string, ManifestEntry>>;
+}
+/**
+ * Hash a file's content, for a manifest entry.
+ *
+ * `\r\n` counts as `\n` (also in binary content), so a checkout with `core.autocrlf` still matches.
+ * Unlike an inline signature, manual sections are not excluded.
+ *
+ * @param content - file content
+ * @returns `v1:` followed by 32 hex characters
+ */
+export declare const contentHash: (content: string | Uint8Array) => string;
+/**
+ * Check a file against its manifest entry.
+ *
+ * @param content - file content
+ * @param entry - the file's manifest entry
+ * @returns `valid` or `invalid` for a hash entry, the inline signature's result otherwise
+ */
+export declare const verifyManifestEntry: (content: string | Uint8Array, entry: ManifestEntry) => VerifyResult;
+/**
+ * Parse and validate a manifest.
+ *
+ * @param text - manifest file content
+ * @returns the validated manifest object
+ * @throws {GeneratedSignatureManifestError} if the text is not a valid manifest
+ */
+export declare const parseManifest: (text: string) => Manifest;
+/**
+ * Serialize a manifest deterministically: file paths and inputs are sorted, so regenerating in
+ * a different order produces the same text.
+ *
+ * @param files - entries by path relative to the manifest's directory
+ * @returns manifest file content
+ */
+export declare const serializeManifest: (files: Readonly<Record<string, ManifestEntry>>) => string;
+export {};
+//# sourceMappingURL=manifest.d.ts.map

package/dist/lib/manifest.js

@@ -0,0 +1,88 @@
+import { createHash } from 'node:crypto';
+import { GeneratedSignatureManifestError } from './errors.js';
+import { verify } from './signature.js';
+const VERSION = 1;
+const HASH_PREFIX = 'v1:';
+const HASH_LENGTH = 32;
+const CR = 0x0d;
+const LF = 0x0a;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const normalizeLineBreaks = (bytes)=>{
+    const result = new Uint8Array(bytes.length);
+    let length = 0;
+    for (const [i, byte] of bytes.entries()){
+        if (byte === CR && bytes[i + 1] === LF) {
+            continue;
+        }
+        result[length] = byte;
+        length++;
+    }
+    return result.subarray(0, length);
+};
+export const contentHash = (content)=>{
+    const bytes = typeof content === 'string' ? encoder.encode(content) : content;
+    return HASH_PREFIX + createHash('sha256').update(normalizeLineBreaks(bytes)).digest('hex').slice(0, HASH_LENGTH);
+};
+export const verifyManifestEntry = (content, entry)=>{
+    if ('signature' in entry) {
+        return verify(typeof content === 'string' ? content : decoder.decode(content));
+    }
+    return {
+        status: contentHash(content) === entry.hash ? 'valid' : 'invalid'
+    };
+};
+const isStringRecord = (value)=>typeof value === 'object' && value !== null && !Array.isArray(value) && Object.values(value).every((item)=>typeof item === 'string');
+const isEntry = (value)=>{
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const { hash, signature, inputs, ...rest } = value;
+    return Object.keys(rest).length === 0 && (inputs === undefined || isStringRecord(inputs)) && typeof hash === 'string' !== (signature === 'inline') && (hash === undefined || typeof hash === 'string') && (signature === undefined || signature === 'inline');
+};
+export const parseManifest = (text)=>{
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    } catch (err) {
+        throw new GeneratedSignatureManifestError('not valid JSON', {
+            cause: err
+        });
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new GeneratedSignatureManifestError('not an object');
+    }
+    const { version, files } = parsed;
+    if (version !== VERSION) {
+        throw new GeneratedSignatureManifestError(`unsupported version ${String(version)}`);
+    }
+    if (typeof files !== 'object' || files === null || Array.isArray(files)) {
+        throw new GeneratedSignatureManifestError('files is not an object');
+    }
+    for (const [path, entry] of Object.entries(files)){
+        if (!isEntry(entry)) {
+            throw new GeneratedSignatureManifestError(`invalid entry for ${path}`);
+        }
+    }
+    return {
+        version,
+        files: files
+    };
+};
+const sortKeys = (record)=>Object.fromEntries(Object.entries(record).toSorted(([a], [b])=>a < b ? -1 : 1));
+export const serializeManifest = (files)=>{
+    const sortedFiles = Object.fromEntries(Object.entries(sortKeys(files)).map(([path, entry])=>[
+            path,
+            entry.inputs ? {
+                ...entry,
+                inputs: sortKeys(entry.inputs)
+            } : entry
+        ]));
+    const manifest = {
+        version: VERSION,
+        files: sortedFiles
+    };
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+};
+
+//# sourceMappingURL=manifest.js.map

package/dist/lib/merge.d.ts

@@ -0,0 +1,57 @@
+import type { CommentOptions } from './comment-style.js';
+import type { ManualSection } from './sections.js';
+/**
+ * Find the manual sections in a file.
+ *
+ * @param text - file content
+ * @returns sections by id, in file order
+ * @throws {GeneratedSignatureMalformedError} if markers are unbalanced, nested or duplicated
+ */
+export declare const parseSections: (text: string) => ReadonlyMap<string, ManualSection>;
+export interface MergeResult {
+    /**
+     * Generated text, with each section body taken from the existing file when it has a section
+     * with the same id.
+     */
+    readonly text: string;
+    /**
+     * Ids of sections in the existing file that the generated text no longer has, and whose
+     * body isn't blank. Dropping them would lose someone's edits.
+     */
+    readonly orphans: readonly string[];
+}
+/**
+ * Carry manual edits from an existing file over into freshly generated text.
+ *
+ * Sections are matched by id, not position, so the generator can add, remove or reorder them.
+ *
+ * @param params - texts to merge
+ * @param params.generated - new generator output, with default section bodies
+ * @param params.existing - current file content
+ * @returns merged text and orphaned section ids
+ * @throws {GeneratedSignatureMalformedError} if either text's sections are malformed
+ */
+export declare const mergeSections: ({ generated, existing, }: {
+    generated: string;
+    existing: string;
+}) => MergeResult;
+export type ManualSectionOptions = CommentOptions & {
+    readonly id: string;
+    /**
+     * Default content, used until someone edits it.
+     */
+    readonly body?: string;
+    /**
+     * Prefixed to the markers and each non-blank body line.
+     */
+    readonly indent?: string;
+};
+/**
+ * Render a manual section, for a generator to embed in its output.
+ *
+ * @param options - section id, default body, and comment syntax
+ * @returns marker lines around the body, without a trailing line break
+ * @throws {GeneratedSignatureSectionIdError} if the id is not valid
+ */
+export declare const manualSection: ({ id, body, indent, ...options }: ManualSectionOptions) => string;
+//# sourceMappingURL=merge.d.ts.map

package/dist/lib/merge.js

@@ -0,0 +1,35 @@
+import { renderComment, resolveCommentStyle } from './comment-style.js';
+import { GeneratedSignatureSectionIdError } from './errors.js';
+import { isValidSectionId, replaceBodies, scanSections } from './sections.js';
+export const parseSections = (text)=>new Map(scanSections(text).map(({ id, body, startLine, endLine })=>[
+            id,
+            {
+                id,
+                body,
+                startLine,
+                endLine
+            }
+        ]));
+export const mergeSections = ({ generated, existing })=>{
+    const existingSections = parseSections(existing);
+    const generatedSections = scanSections(generated);
+    const generatedIds = new Set(generatedSections.map(({ id })=>id));
+    return {
+        text: replaceBodies(generated, generatedSections, (section)=>existingSections.get(section.id)?.body ?? section.body),
+        orphans: existingSections.values().filter(({ id, body })=>!generatedIds.has(id) && body.trim() !== '').map(({ id })=>id).toArray()
+    };
+};
+export const manualSection = ({ id, body = '', indent = '', ...options })=>{
+    if (!isValidSectionId(id)) {
+        throw new GeneratedSignatureSectionIdError(id);
+    }
+    const style = resolveCommentStyle(options);
+    const lines = body === '' ? [] : body.replace(/\n$/u, '').split('\n');
+    return [
+        renderComment(style, `@manual-start ${id}`),
+        ...lines,
+        renderComment(style, `@manual-end ${id}`)
+    ].map((line)=>line.trim() === '' ? line : indent + line).join('\n');
+};
+
+//# sourceMappingURL=merge.js.map

package/dist/lib/sections.d.ts

@@ -0,0 +1,42 @@
+export interface ManualSection {
+    readonly id: string;
+    /**
+     * Everything between the marker lines, including the final line break (empty if none).
+     */
+    readonly body: string;
+    /**
+     * 1-indexed line of the start marker.
+     */
+    readonly startLine: number;
+    /**
+     * 1-indexed line of the end marker.
+     */
+    readonly endLine: number;
+}
+export interface ScannedSection extends ManualSection {
+    /**
+     * Offsets into the scanned text, `body === text.slice(bodyStart, bodyEnd)`.
+     */
+    readonly bodyStart: number;
+    readonly bodyEnd: number;
+}
+export declare const isValidSectionId: (id: string) => boolean;
+/**
+ * Find all manual sections in a text. Markers own their whole line, so the comment syntax
+ * around them doesn't matter.
+ *
+ * @param text - file content
+ * @returns sections, in file order
+ * @throws {GeneratedSignatureMalformedError} if markers are unbalanced, nested or duplicated
+ */
+export declare const scanSections: (text: string) => ScannedSection[];
+/**
+ * Replace the body of each section, working backwards so earlier offsets stay valid.
+ *
+ * @param text - text the sections were scanned from
+ * @param sections - scanned sections of `text`
+ * @param getBody - new body for a section
+ * @returns text with bodies replaced
+ */
+export declare const replaceBodies: (text: string, sections: readonly ScannedSection[], getBody: (section: ScannedSection) => string) => string;
+//# sourceMappingURL=sections.d.ts.map

package/dist/lib/sections.js

@@ -0,0 +1,84 @@
+import { GeneratedSignatureMalformedError } from './errors.js';
+const markerPattern = /(?:^|\s)@manual-(?<kind>start|end)\b(?:\s+(?<id>\S+))?/u;
+const idPattern = /^[\w.-]+$/u;
+export const isValidSectionId = (id)=>idPattern.test(id);
+export const scanSections = (text)=>{
+    const sections = [];
+    const seen = new Set();
+    let open = null;
+    let lineStart = 0;
+    let lineNumber = 0;
+    while(lineStart < text.length){
+        lineNumber++;
+        const newline = text.indexOf('\n', lineStart);
+        const lineEnd = newline === -1 ? text.length : newline + 1;
+        const match = markerPattern.exec(text.slice(lineStart, lineEnd));
+        if (match) {
+            const { kind, id = '' } = match.groups;
+            if (!isValidSectionId(id)) {
+                throw new GeneratedSignatureMalformedError({
+                    reason: 'invalid-section-id',
+                    line: lineNumber,
+                    detail: `"${id}" must match ${idPattern}`
+                });
+            }
+            if (kind === 'start') {
+                if (open) {
+                    throw new GeneratedSignatureMalformedError({
+                        reason: 'nested-section',
+                        line: lineNumber,
+                        detail: `"${id}" starts inside "${open.id}"`
+                    });
+                }
+                if (seen.has(id)) {
+                    throw new GeneratedSignatureMalformedError({
+                        reason: 'duplicate-section',
+                        line: lineNumber,
+                        detail: `"${id}" is already defined`
+                    });
+                }
+                open = {
+                    id,
+                    line: lineNumber,
+                    bodyStart: lineEnd
+                };
+            } else {
+                if (open?.id !== id) {
+                    throw new GeneratedSignatureMalformedError({
+                        reason: 'unopened-section',
+                        line: lineNumber,
+                        detail: open ? `"${id}" ends while "${open.id}" is open` : `"${id}" ends without a start`
+                    });
+                }
+                sections.push({
+                    id,
+                    body: text.slice(open.bodyStart, lineStart),
+                    startLine: open.line,
+                    endLine: lineNumber,
+                    bodyStart: open.bodyStart,
+                    bodyEnd: lineStart
+                });
+                seen.add(id);
+                open = null;
+            }
+        }
+        lineStart = lineEnd;
+    }
+    if (open) {
+        throw new GeneratedSignatureMalformedError({
+            reason: 'unclosed-section',
+            line: open.line,
+            detail: `"${open.id}" has no end`
+        });
+    }
+    return sections;
+};
+export const replaceBodies = (text, sections, getBody)=>{
+    let result = text;
+    for (const section of sections.toReversed()){
+        result = result.slice(0, section.bodyStart) + getBody(section) + result.slice(section.bodyEnd);
+    }
+    return result;
+};
+
+//# sourceMappingURL=sections.js.map

package/dist/lib/signature.d.ts

@@ -0,0 +1,55 @@
+import type { CommentOptions } from './comment-style.js';
+import { GeneratedSignatureMalformedError } from './errors.js';
+export type SignOptions = CommentOptions & {
+    /**
+     * Text after the token in an inserted signature line.
+     */
+    readonly message?: string;
+};
+/**
+ * An unsigned signature token, for generators that place it themselves (e.g. inside their own
+ * header comment). `sign()` fills in its hash.
+ *
+ * @returns token with a placeholder hash
+ */
+export declare const signatureToken: () => string;
+/**
+ * Sign a generated file.
+ *
+ * If the text already contains a signature token (e.g. a previous signature, or one the
+ * generator placed itself), its hash is replaced. Otherwise a signature line is inserted at the
+ * top of the file, using the comment syntax from `options`.
+ *
+ * @param text - generated file content
+ * @param options - comment syntax and message, required only if the text has no token yet
+ * @returns signed text
+ * @throws {GeneratedSignatureMalformedError} if the token or manual sections are malformed
+ * @throws {GeneratedSignatureCommentStyleError} if a line must be inserted for an unknown file type
+ */
+export declare const sign: (text: string, options?: SignOptions) => string;
+export type VerifyResult = {
+    /**
+     * The file has no signature token.
+     */
+    readonly status: 'unsigned';
+} | {
+    /**
+     * The token's hash does not match, so content outside manual sections was edited.
+     */
+    readonly status: 'invalid';
+} | {
+    readonly status: 'malformed';
+    readonly error: GeneratedSignatureMalformedError;
+} | {
+    readonly status: 'valid';
+};
+/**
+ * Check a file's signature. Only needs the file itself, not the generator that wrote it.
+ *
+ * Does not check that the file is up to date with its generator's inputs.
+ *
+ * @param text - file content
+ * @returns verification status
+ */
+export declare const verify: (text: string) => VerifyResult;
+//# sourceMappingURL=signature.d.ts.map

package/dist/lib/signature.js

@@ -0,0 +1,85 @@
+import { createHash } from 'node:crypto';
+import { renderComment, resolveCommentStyle } from './comment-style.js';
+import { GeneratedSignatureMalformedError } from './errors.js';
+import { replaceBodies, scanSections } from './sections.js';
+const VERSION = '1';
+const HASH_LENGTH = 32;
+const PLACEHOLDER = '0'.repeat(HASH_LENGTH);
+const TOKEN_NAME = '@generated-signature';
+const tokenPattern = new RegExp(String.raw`${TOKEN_NAME} v(?<version>\d+):(?<hash>[\da-f]{${HASH_LENGTH}})`, 'gu');
+const DEFAULT_MESSAGE = 'Generated file. Do not edit outside of manual sections.';
+const lineOf = (text, offset)=>text.slice(0, offset).split('\n').length;
+const findToken = (text)=>{
+    const [first, second] = text.matchAll(tokenPattern);
+    if (!first) {
+        return null;
+    }
+    if (second) {
+        throw new GeneratedSignatureMalformedError({
+            reason: 'duplicate-signature',
+            line: lineOf(text, second.index),
+            detail: `signature already defined at line ${lineOf(text, first.index)}`
+        });
+    }
+    const { version = '', hash = '' } = first.groups;
+    if (version !== VERSION) {
+        throw new GeneratedSignatureMalformedError({
+            reason: 'unsupported-version',
+            line: lineOf(text, first.index),
+            detail: `v${version} is not supported, expected v${VERSION}`
+        });
+    }
+    return {
+        hash,
+        hashStart: first.index + first[0].length - HASH_LENGTH
+    };
+};
+const replaceHash = (text, token, hash)=>text.slice(0, token.hashStart) + hash + text.slice(token.hashStart + HASH_LENGTH);
+const computeHash = (text)=>{
+    const normalized = text.replaceAll('\r\n', '\n');
+    const token = findToken(normalized);
+    const withPlaceholder = replaceHash(normalized, token, PLACEHOLDER);
+    const hashable = replaceBodies(withPlaceholder, scanSections(withPlaceholder), ()=>'');
+    return createHash('sha256').update(hashable).digest('hex').slice(0, HASH_LENGTH);
+};
+export const signatureToken = ()=>`${TOKEN_NAME} v${VERSION}:${PLACEHOLDER}`;
+const insertHeader = (text, options)=>{
+    const style = resolveCommentStyle(options);
+    const lineBreak = text.includes('\r\n') ? '\r\n' : '\n';
+    const header = renderComment(style, `${signatureToken()} ${options.message ?? DEFAULT_MESSAGE}`) + lineBreak;
+    if (text.startsWith('#!') || text.startsWith('<?xml')) {
+        const firstLineEnd = text.indexOf('\n');
+        return firstLineEnd === -1 ? text + lineBreak + header : text.slice(0, firstLineEnd + 1) + header + text.slice(firstLineEnd + 1);
+    }
+    return header + text;
+};
+export const sign = (text, options)=>{
+    let withToken = text;
+    if (findToken(text) === null) {
+        if (!options) {
+            throw new TypeError('Text has no signature token, provide `comment` or `filePath`');
+        }
+        withToken = insertHeader(text, options);
+    }
+    return replaceHash(withToken, findToken(withToken), computeHash(withToken));
+};
+export const verify = (text)=>{
+    try {
+        const token = findToken(text.replaceAll('\r\n', '\n'));
+        if (token === null) {
+            return {
+                status: 'unsigned'
+            };
+        }
+        return {
+            status: computeHash(text) === token.hash ? 'valid' : 'invalid'
+        };
+    } catch (err) {
+        return {
+            status: 'malformed',
+            error: err
+        };
+    }
+};
+
+//# sourceMappingURL=signature.js.map

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "generated-signature",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Sign generated files so hand edits are detected, while keeping manual sections editable",
+  "engines": {
+    "node": ">=24"
+  },
+  "type": "module",
+  "author": "JacobLey",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JacobLey/leyman.git",
+    "directory": "tools/generated-signature/generated-signature"
+  },
+  "homepage": "https://github.com/JacobLey/leyman/tree/main/tools/generated-signature/generated-signature#readme",
+  "bugs": {
+    "url": "https://github.com/JacobLey/leyman/issues"
+  },
+  "keywords": [
+    "codegen",
+    "generated",
+    "signature",
+    "checksum",
+    "eslint",
+    "eslintplugin"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/generated-signature.js",
+    "./eslint": "./dist/eslint/plugin.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "!dist/tsconfig.tsbuildinfo"
+  ],
+  "peerDependencies": {
+    "eslint": "^10.12.0"
+  },
+  "peerDependenciesMeta": {
+    "eslint": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.14",
+    "@leyman/eslint-config": "^0.0.1",
+    "@leyman/expect": "^0.0.1",
+    "@swc/cli": "^0.8.1",
+    "@swc/core": "^1.16.2",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^24.19.0",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "c8": "^12.0.0",
+    "eslint": "^10.12.0",
+    "expect-type": "^1.4.0",
+    "mocha": "^12.0.2",
+    "mocha-chain": "^1.0.1",
+    "typescript": "npm:@typescript/typescript6@^6.0.2"
+  },
+  "imports": {
+    "#internal/*": "./dist/*"
+  }
 }