generated-signature 0.1.0 → 0.1.2

package/README.md

@@ -8,7 +8,7 @@ Sign generated files so hand edits are detected, while keeping manual sections e
 
 </div>
 
-Guides and the full reference are on the [docs site](https://jacobley.github.io/leyman/generated-signature/).
+Guides and the full reference are on the [docs site](https://jacobley.github.io/leyman/packages/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.
@@ -91,7 +91,7 @@ export class AutoGenerated {
 }
 ```
 
-- **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).
+- **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, an XML declaration, or Markdown front matter) 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.
 

package/dist/eslint/rules/valid.js

@@ -4,7 +4,7 @@ export const valid = {
         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'
+            url: 'https://jacobley.github.io/leyman/packages/generated-signature/guides/eslint#generated-signature-valid'
         },
         messages: {
             invalid: 'Generated file was edited outside of its manual sections. Regenerate it instead.',

package/dist/lib/manifest.js

@@ -59,14 +59,16 @@ export const parseManifest = (text)=>{
     if (typeof files !== 'object' || files === null || Array.isArray(files)) {
         throw new GeneratedSignatureManifestError('files is not an object');
     }
+    const entries = {};
     for (const [path, entry] of Object.entries(files)){
         if (!isEntry(entry)) {
             throw new GeneratedSignatureManifestError(`invalid entry for ${path}`);
         }
+        entries[path] = entry;
     }
     return {
         version,
-        files: files
+        files: entries
     };
 };
 const sortKeys = (record)=>Object.fromEntries(Object.entries(record).toSorted(([a], [b])=>a < b ? -1 : 1));

package/dist/lib/merge.d.ts

@@ -1,5 +1,8 @@
 import type { CommentOptions } from './comment-style.js';
 import type { ManualSection } from './sections.js';
+/**
+ * @import { GeneratedSignatureMalformedError } from './errors.js'
+ */
 /**
  * Find the manual sections in a file.
  *

package/dist/lib/merge.js

@@ -24,7 +24,7 @@ export const manualSection = ({ id, body = '', indent = '', ...options })=>{
         throw new GeneratedSignatureSectionIdError(id);
     }
     const style = resolveCommentStyle(options);
-    const lines = body === '' ? [] : body.replace(/\n$/u, '').split('\n');
+    const lines = body === '' ? [] : body.replace(/\n$/v, '').split('\n');
     return [
         renderComment(style, `@manual-start ${id}`),
         ...lines,

package/dist/lib/sections.js

@@ -1,6 +1,6 @@
 import { GeneratedSignatureMalformedError } from './errors.js';
-const markerPattern = /(?:^|\s)@manual-(?<kind>start|end)\b(?:\s+(?<id>\S+))?/u;
-const idPattern = /^[\w.-]+$/u;
+const markerPattern = /(?:^|\s)@manual-(?<kind>end|start)\b(?:\s+(?<id>\S+))?/v;
+const idPattern = /^[\w\-.]+$/v;
 export const isValidSectionId = (id)=>idPattern.test(id);
 export const scanSections = (text)=>{
     const sections = [];

package/dist/lib/signature.js

@@ -6,10 +6,11 @@ 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 tokenPattern = new RegExp(String.raw`${TOKEN_NAME} v(?<version>\d+):(?<hash>[\da-f]{${HASH_LENGTH}})`, 'gv');
 const DEFAULT_MESSAGE = 'Generated file. Do not edit outside of manual sections.';
+const renderToken = (hash)=>`${TOKEN_NAME} v${VERSION}:${hash}`;
 const lineOf = (text, offset)=>text.slice(0, offset).split('\n').length;
-const findToken = (text)=>{
+const findHash = (text)=>{
     const [first, second] = text.matchAll(tokenPattern);
     if (!first) {
         return null;
@@ -29,20 +30,14 @@ const findToken = (text)=>{
             detail: `v${version} is not supported, expected v${VERSION}`
         });
     }
-    return {
-        hash,
-        hashStart: first.index + first[0].length - HASH_LENGTH
-    };
+    return hash;
 };
-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 withPlaceholder = text.replaceAll('\r\n', '\n').replaceAll(tokenPattern, ()=>renderToken(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}`;
+export const signatureToken = ()=>renderToken(PLACEHOLDER);
 const insertHeader = (text, options)=>{
     const style = resolveCommentStyle(options);
     const lineBreak = text.includes('\r\n') ? '\r\n' : '\n';
@@ -51,28 +46,34 @@ const insertHeader = (text, options)=>{
         const firstLineEnd = text.indexOf('\n');
         return firstLineEnd === -1 ? text + lineBreak + header : text.slice(0, firstLineEnd + 1) + header + text.slice(firstLineEnd + 1);
     }
+    const frontMatter = style.start === '<!--' ? /^---\r?\n(?:[^\n]*\n)*?---\r?(?:\n|$)/v.exec(text) : null;
+    if (frontMatter) {
+        const [fenced] = frontMatter;
+        return fenced.endsWith('\n') ? fenced + header + text.slice(fenced.length) : fenced + lineBreak + header;
+    }
     return header + text;
 };
 export const sign = (text, options)=>{
     let withToken = text;
-    if (findToken(text) === null) {
+    if (findHash(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));
+    const hash = computeHash(withToken);
+    return withToken.replaceAll(tokenPattern, ()=>renderToken(hash));
 };
 export const verify = (text)=>{
     try {
-        const token = findToken(text.replaceAll('\r\n', '\n'));
-        if (token === null) {
+        const hash = findHash(text.replaceAll('\r\n', '\n'));
+        if (hash === null) {
             return {
                 status: 'unsigned'
             };
         }
         return {
-            status: computeHash(text) === token.hash ? 'valid' : 'invalid'
+            status: computeHash(text) === hash ? 'valid' : 'invalid'
         };
     } catch (err) {
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "generated-signature",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Sign generated files so hand edits are detected, while keeping manual sections editable",
   "engines": {
     "node": ">=24"