@rm-industries/oxlint-plugin-headstamp 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RM Industries
+
+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,345 @@
-# Temporary Holding Version
+# Headstamp
 
-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.
+An oxlint-first plugin that validates templated source headers and inserts missing
+ones safely. Supports JavaScript, TypeScript, JSX, and TSX.
+
+Supports complete literal templates and named, single-line placeholders with regex
+validation, safe repair of invalid fields, and incomplete scaffolds requiring human
+input.
+
+## Requirements
+
+- Node.js 22.18+ on the 22.x line, or Node.js 24+.
+- The Node-based oxlint package, version `^1.88.0` (1.88.0 or later within 1.x).
+
+Headstamp uses oxlint's `createOnce` API with a `Program` visitor. JavaScript plugins
+are still an alpha oxlint feature. CI verifies the lockfile's exact versions,
+currently oxlint 1.93.0. No benchmarked performance improvement is claimed.
+
+Development and peer dependencies use caret ranges. The committed lockfile and
+`npm ci` keep installs reproducible; dependency updates must pass the same checks.
+
+## Tested source formats
+
+Real CLI tests verify `.js`, `.mjs`, `.cjs`, `.ts`, `.mts`, `.cts`, `.jsx`, and
+`.tsx`, using module, CommonJS, typed, and JSX syntax as appropriate. For every
+extension, tests require missing-header diagnostics, exact header insertion,
+valid-header acceptance, unchanged source bodies, and repeated-fix convergence.
+They also cover LF/CRLF, BOM-only and shebang-only prefixes, and mixed-file
+configuration overrides, disabled rules, and ignores.
+
+Use oxlint's existing file discovery, overrides, and ignores; Headstamp adds no
+file selector or parser. Physical-file headers in Vue, Svelte, and Astro are
+deferred on oxlint 1.88.0: scriptless files do not invoke the plugin, and scripts
+expose separate source/edit regions. Enabling the rule there can insert per-script
+banners rather than one physical-file header. Exclude those formats with oxlint
+overrides/ignores when enforcing physical headers. See the [framework investigation](docs/framework-upstream-research.md)
+for separate decisions, reproducible CLI probes, and pinned upstream references.
+
+## Install
+
+```sh
+npm install --save-dev @rm-industries/oxlint-plugin-headstamp oxlint@^1.88.0
+```
+
+## Configure
+
+In your existing `oxlint.config.ts`:
+
+```ts
+import type { HeaderOptions } from '@rm-industries/oxlint-plugin-headstamp';
+import { defineConfig } from 'oxlint';
+
+const header = {
+  template: `/*
+ * Copyright {{years}} {{owner}}
+ */`,
+  values: {
+    years: {
+      pattern: '\\d{4}(?:-\\d{4})?',
+      replacement: String(new Date().getUTCFullYear()),
+    },
+    owner: { pattern: 'Acme', replacement: 'Acme' },
+  },
+} satisfies HeaderOptions;
+
+export default defineConfig({
+  jsPlugins: [{ name: 'headstamp', specifier: '@rm-industries/oxlint-plugin-headstamp' }],
+  overrides: [
+    {
+      files: ['src/**/*.{js,ts,jsx,tsx}'],
+      rules: { 'headstamp/header': ['error', header] },
+    },
+  ],
+});
+```
+
+Use ordinary oxlint overrides and ignores to choose files. To store the template in
+`HEADER.txt`, read it in configuration code:
+
+```ts
+import { readFileSync } from 'node:fs';
+
+const header = {
+  template: readFileSync(new URL('./HEADER.txt', import.meta.url), 'utf8'),
+} satisfies HeaderOptions;
+```
+
+Text files contain the same comment template, including placeholders; their
+extension has no meaning to Headstamp. Keep the `values` map alongside the template
+property when reading from a file. Configuration can compute replacement values or
+import shared options, but the rule receives strings, not executable functions.
+JSON oxlint configuration also works with inline template and value strings.
+
+## SPDX header example
+
+Use this in `oxlint.config.ts`. Change `MIT` and `Acme` to your project's
+license identifier and copyright holder.
+
+```ts
+import { defineConfig } from 'oxlint';
+
+const year = String(new Date().getUTCFullYear());
+
+export default defineConfig({
+  jsPlugins: [{ name: 'headstamp', specifier: '@rm-industries/oxlint-plugin-headstamp' }],
+  overrides: [
+    {
+      files: ['src/**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+      rules: {
+        'headstamp/header': [
+          'error',
+          {
+            template: '// SPDX-License-Identifier: {{license}}\n// SPDX-FileCopyrightText: {{years}} Acme',
+            values: {
+              license: { pattern: 'MIT', replacement: 'MIT' },
+              years: { pattern: '\\d{4}(?:-\\d{4})?', replacement: year },
+            },
+          },
+        ],
+      },
+    },
+  ],
+});
+```
+
+With `oxlint --fix`, a missing header gets the configured license and year.
+An existing header with the wrong license identifier can be repaired without
+changing a valid year or year range.
+
+### Optional Git-derived year
+
+To use the latest commit's year as the default, replace the `year` declaration
+above with this snippet. This runs Git once when the config loads. It uses the
+same year for every file; it does not infer per-file history. If Git is missing
+or the checkout has no commits, it falls back to the current UTC year.
+
+```ts
+import { spawnSync } from 'node:child_process';
+
+const commitDate = spawnSync('git', ['log', '-1', '--format=%cs'], {
+  cwd: new URL('.', import.meta.url),
+  encoding: 'utf8',
+  timeout: 10000,
+});
+const gitYear = commitDate.status === 0 ? /^(\d{4})-/.exec(commitDate.stdout)?.[1] : undefined;
+const year = gitYear ?? String(new Date().getUTCFullYear());
+```
+
+## Placeholders
+
+Use `{{name}}` and define each name once in `values`, with a regex `pattern` string
+and a literal `replacement` string. Names use `[A-Za-z_][A-Za-z0-9_]*`. Repeated,
+undefined, or malformed placeholders and unused definitions are configuration errors.
+
+Patterns must match the entire field value. Existing `2020` and `2020-2024` years
+remain valid with the example above, even when the generated replacement is `2026`.
+Regex capture groups and backreferences are local to each pattern. Replacement
+strings are inserted literally, including dollar signs and backslashes.
+
+Placeholders capture single-line values and require literal text between them. A
+separator may occur inside a value if the patterns identify exactly one valid split.
+Multiple valid splits produce a diagnostic without autofix. A configuration whose
+otherwise-valid generated header has ambiguous field boundaries is rejected.
+
+Invalid existing fields are reported by name when their boundaries are clear.
+`--fix` replaces a field only when its configured replacement matches the entire
+pattern, preserving every valid field, including historical years and ranges. If a
+replacement fails its pattern, existing text in that field remains unchanged; other
+safe fields may still be repaired. A repair is refused if it would make boundaries
+ambiguous, reinterpret another field, or break the comment. Literal text identifies
+the header structure; changed wording or ambiguous extraction requires manual review.
+
+Replacements may intentionally fail their pattern; this is not a configuration error.
+They must still be single-line and preserve the complete comment. Missing-header
+generation uses replacement strings, while validation uses field patterns.
+
+## Incomplete scaffolds
+
+A field can require human input by providing an intentionally invalid replacement:
+
+```ts
+const header = {
+  template: '// Owner: {{owner}}\n// Description: {{description}}',
+  values: {
+    owner: { pattern: 'Acme', replacement: 'Acme' },
+    description: { pattern: '\\S.{9,}', replacement: '' },
+  },
+} satisfies HeaderOptions;
+```
+
+The description must start with a non-whitespace character and contain at least ten
+characters. Running `oxlint --fix` on a file without a header inserts:
+
+```ts
+// Owner: Acme
+// Description:
+
+export {};
+```
+
+The generated description line retains the template’s space after the colon.
+Successful insertion still leaves a lint error for `description`, so the CLI exits
+unsuccessfully. Fill in a valid description, then lint again to pass. An invalid
+nonempty replacement such as `TODO` works the same way.
+
+Repeated fixes preserve the scaffold and keep reporting the incomplete field
+without offering a no-op edit. Existing unfinished text such as `WIP` is preserved
+rather than reset to the replacement. Other independently safe repairs, such as
+correcting the owner, still apply while the description remains incomplete. Valid
+fields, including historical years, stay unchanged. Ambiguous field boundaries
+still require manual review.
+
+## Permitted leading comments
+
+Use `allowedLeadingComments` to preserve explicitly permitted directives or pragmas
+before the required header:
+
+```ts
+const header = {
+  template: '/* Acme */',
+  allowedLeadingComments: ['// @ts-check', { pattern: '/\\*\\* @jest-environment [\\s\\S]*?\\*/' }],
+} satisfies HeaderOptions;
+```
+
+The default is an empty allowlist. Entries are complete literal comments or objects
+with a regex `pattern` string. Patterns match the entire comment, including its
+delimiters, with no flags; use explicit multiline expressions when needed. Literal
+and source CRLF are normalized to LF for matching, while original prefix bytes are
+preserved. Malformed literals, regexes, or option shapes are configuration errors.
+
+A matching unit is one block comment or a consecutive `//` group. Headstamp never
+splits a group to accept only some of its lines. Separate an existing line-comment
+prefix and line-comment header with a blank line. Insertion adds the newline(s)
+needed to keep these groups separate on subsequent runs.
+
+Only the opening prefix after any BOM/shebang is considered. The required header
+takes precedence over a matching allowlist entry, including when its fields need
+repair. An ambiguous header remains diagnostic-only. Unknown comments stop the
+search without autofix; source code ends the prefix, and later comments are not
+searched for a header.
+
+Permitted comments are never generated, repaired, or reordered. Their text and
+spacing are preserved, including whitespace before an existing or inserted header.
+Insertion adds a separator only when needed. Prefix-only files receive a header
+with one final newline. Source indentation, historical fields, and unfinished
+human input remain protected, and repeated fixes converge.
+
+The allowlist does not change spacing before the header; `blankLinesAfter` controls
+only the boundary after it.
+This rule preserves source LF/CRLF; it does not read EditorConfig or convert the
+rest of a file's line endings.
+
+## Spacing after the header
+
+Set `blankLinesAfter` to the exact number of empty lines required before subsequent
+content. It defaults to `1`; values must be nonnegative safe integers.
+
+```ts
+const header = {
+  template: '/* Acme */',
+  blankLinesAfter: 0,
+} satisfies HeaderOptions;
+```
+
+Zero places source on the following line without an empty line. A value of `3`
+requires three empty lines. Fixes add missing or remove excess lines, preserving
+source indentation and LF/CRLF. Empty and header-only files always end with one
+final newline, regardless of the configured count. Prefix spacing stays unchanged.
+
+A zero count cannot safely join a `//` header to following `//` documentation:
+that would merge separate comment groups on the next lint run. Headstamp reports
+this conflict without changing that separator. Use a block header or at least one
+blank line. Independently safe field repairs still apply.
+
+Spacing fixes can also apply while required scaffold fields are incomplete. The
+unfinished text and its lint errors remain until valid human input is supplied.
+Repeated fixes converge and do not offer no-op edits.
+
+## Header behavior
+
+- Templates contain exactly one complete `/* ... */` comment or consecutive `//`
+  lines. Include the delimiters and desired internal whitespace. Trailing template
+  newlines are ignored; LF and CRLF templates match either source convention.
+- Literal header text must match exactly, including internal whitespace. Placeholder
+  values must match their patterns. Recognized invalid fields may be repaired as
+  described above. Changed literal text or an unrecognized opening comment produces
+  a diagnostic without autofix.
+  Consecutive opening `//` lines form one comment group: an extra line in that group
+  requires manual review.
+- `oxlint --fix` inserts a missing header after any shebang and permitted opening
+  comments, preserving a BOM, source code, and separate later comments.
+- Headers get exactly `blankLinesAfter` empty lines before subsequent content
+  (default `1`) when the edit preserves separate comment groups. Indentation of
+  subsequent content is retained. Without a permitted prefix, leading whitespace
+  before the header is removed; prefix spacing is preserved when present.
+- Empty, whitespace-only, and header-only files end with the header and exactly one
+  final newline. They do not receive an empty trailing paragraph.
+- Edits use the first LF or CRLF convention present in the source, defaulting to LF
+  when none exists. They do not rewrite the rest of the file.
+- Repeated fixes converge and never offer an edit that makes no change.
+- Invalid options or malformed templates fail rather than inserting source code
+  from an invalid template.
+
+Oxlint 1.88.0 rejects a BOM immediately followed by a shebang during parsing, before
+plugins run. BOM-only and shebang-only inputs are supported and tested separately;
+Headstamp cannot fix a file that oxlint cannot parse.
+
+## Development
+
+```sh
+npm run typecheck
+npm run test:rule
+npm test
+npm run lint
+npm run format:check
+```
+
+Run `npm run format` to apply Oxfmt formatting across the repository. EditorConfig
+sets UTF-8, LF, final newlines, two-space indentation, and a 120-column target.
+The typed Oxfmt config adds single quotes, trailing commas, and import/package
+sorting. Generated files and local state are excluded through the Toptal-generated
+Git ignore rules and the project's additional exclusions.
+
+GitHub Actions checks formatting and lint on pull requests and pushes to the main
+branch. A Node 22.18, 24, and 26 matrix runs strict typechecking, the package build,
+all tests, and package-content inspection. CI checks formatting without rewriting
+files. Publishing a GitHub release triggers a separate npm release workflow after
+those same checks; manual release-workflow runs prepare an artifact without
+publishing. See [RELEASING.md](RELEASING.md) for bootstrap, trusted-publisher setup,
+and version/tag requirements.
+
+Tests use oxlint's public rule-testing API and real CLI runs. CLI tests exercise
+TypeScript configuration and exported types, external templates, supported source
+languages, overrides/ignores, distinct configurations, and repeated fixes.
+Placeholder tests cover historical values, whole-value matching, literal replacement
+characters, malformed configuration, ambiguity, and source preservation.
+
+Implementation and tests are written in TypeScript. Both test commands strictly
+typecheck source and tests, then run the TypeScript tests with Node's built-in type
+stripping. The full suite builds the package first for CLI integration. Only plugin
+source is emitted to the package; tests are never included in the build output.
+
+Package output is ESM JavaScript plus TypeScript declarations. Build artifacts and
+development-only files are excluded from the published package surface; inspect it
+without publishing with `npm pack --dry-run`.

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import type { RuleTester } from 'oxlint/plugins-dev';
+export type { HeaderOptions, HeaderValue } from './template.ts';
+type Rule = Parameters<RuleTester['run']>[1];
+declare const plugin: {
+    meta: {
+        name: string;
+    };
+    rules: {
+        header: Rule;
+    };
+};
+export default plugin;

package/dist/index.js

@@ -0,0 +1,166 @@
+import { prepareHeader } from './template.js';
+const header = {
+    meta: {
+        type: 'layout',
+        fixable: 'code',
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    template: { type: 'string' },
+                    blankLinesAfter: { type: 'integer', minimum: 0, maximum: Number.MAX_SAFE_INTEGER },
+                    allowedLeadingComments: {
+                        type: 'array',
+                        items: {
+                            anyOf: [
+                                { type: 'string' },
+                                {
+                                    type: 'object',
+                                    properties: { pattern: { type: 'string' } },
+                                    required: ['pattern'],
+                                    additionalProperties: false,
+                                },
+                            ],
+                        },
+                    },
+                    values: {
+                        type: 'object',
+                        additionalProperties: {
+                            type: 'object',
+                            properties: { pattern: { type: 'string' }, replacement: { type: 'string' } },
+                            required: ['pattern', 'replacement'],
+                            additionalProperties: false,
+                        },
+                    },
+                },
+                required: ['template'],
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            missing: 'Missing required header.',
+            mismatch: 'Opening comment does not match the required header; review it manually.',
+            spacing: 'Normalize spacing around the required header.',
+            unsafeSpacing: 'Zero blank lines would merge the header with following line comments; use a block header or at least one blank line.',
+            invalidValue: 'Header field(s) {{fields}} do not match their patterns.',
+        },
+    },
+    createOnce(context) {
+        const templates = new Map();
+        return {
+            Program(node) {
+                const hasOneOptionsArgument = context.options.length === 1;
+                if (!hasOneOptionsArgument)
+                    throw new Error('Headstamp requires exactly one options object.');
+                const optionsKey = JSON.stringify(context.options);
+                let prepared = templates.get(optionsKey);
+                if (prepared === undefined) {
+                    prepared = prepareHeader(context.options[0]);
+                    templates.set(optionsKey, prepared);
+                }
+                let headerText = prepared.rendered;
+                let invalidFields = [];
+                let hasFieldRepairs = false;
+                const source = context.sourceCode;
+                const text = source.text;
+                const eol = /\r\n|\n/.exec(text)?.[0] ?? '\n';
+                const shebang = /^#![^\r\n]*(?:\r\n|\n|$)/.exec(text)?.[0] ?? '';
+                let anchor = shebang.length;
+                let start = anchor + /^\s*/.exec(text.slice(anchor))[0].length;
+                const comments = source.getAllComments();
+                let commentIndex = comments.findIndex((comment) => comment.range[0] === start);
+                let first = commentIndex < 0 ? undefined : comments[commentIndex];
+                let end = anchor;
+                let hasLeadingComments = false;
+                let prefixWhitespace = '';
+                let lastLeadingCommentIsLine = false;
+                while (first) {
+                    end = first.range[1];
+                    if (first.type === 'Line') {
+                        for (let nextIndex = commentIndex + 1; nextIndex < comments.length; nextIndex++) {
+                            const comment = comments[nextIndex];
+                            const isLineComment = comment.type === 'Line';
+                            const followsOnNextLine = /^(?:\r\n|\n)[\t ]*$/.test(text.slice(end, comment.range[0]));
+                            if (!isLineComment || !followsOnNextLine)
+                                break;
+                            end = comment.range[1];
+                            commentIndex = nextIndex;
+                        }
+                    }
+                    headerText = text.slice(start, end).replace(/\r\n/g, '\n');
+                    const inspection = prepared.inspect(headerText);
+                    if (inspection === null && prepared.isAllowedLeadingComment(headerText)) {
+                        hasLeadingComments = true;
+                        lastLeadingCommentIsLine = first.type === 'Line';
+                        prefixWhitespace = /^\s*/.exec(text.slice(end))[0];
+                        anchor = end + prefixWhitespace.length;
+                        start = anchor;
+                        end = anchor;
+                        first = comments[++commentIndex];
+                        if (first?.range[0] !== start)
+                            first = undefined;
+                        headerText = prepared.rendered;
+                        continue;
+                    }
+                    if (inspection === null || inspection === 'ambiguous') {
+                        context.report({ node, messageId: 'mismatch' });
+                        return;
+                    }
+                    invalidFields = inspection.invalidFields;
+                    hasFieldRepairs = inspection.repaired !== headerText;
+                    headerText = inspection.repaired;
+                    break;
+                }
+                const whitespace = /^\s*/.exec(text.slice(end))[0];
+                const contentStart = end + whitespace.length;
+                const hasContent = contentStart < text.length;
+                const sourceWhitespace = hasLeadingComments && !first ? prefixWhitespace : whitespace;
+                const indent = hasContent ? sourceWhitespace.slice(sourceWhitespace.lastIndexOf('\n') + 1) : '';
+                const needsShebangNewline = shebang.length > 0 && !shebang.endsWith('\n');
+                let prefix = needsShebangNewline ? eol : '';
+                if (hasLeadingComments && !first) {
+                    // A blank line prevents two line-comment groups from merging on the next lint run.
+                    const needsLineGroupBoundary = lastLeadingCommentIsLine && headerText.startsWith('//');
+                    const requiredNewlines = needsLineGroupBoundary ? 2 : 1;
+                    const existingNewlines = prefixWhitespace.match(/\n/g)?.length ?? 0;
+                    prefix = eol.repeat(Math.max(0, requiredNewlines - existingNewlines));
+                }
+                const wouldMergeLineGroups = first?.type === 'Line' && prepared.blankLinesAfter === 0 && text.startsWith('//', contentStart);
+                if (wouldMergeLineGroups)
+                    context.report({ node, messageId: 'unsafeSpacing' });
+                const separator = wouldMergeLineGroups
+                    ? whitespace
+                    : eol + (hasContent ? eol.repeat(prepared.blankLinesAfter) + indent : '');
+                const replacement = prefix + headerText.replace(/\n/g, eol) + separator;
+                let remainingInvalidFields = prepared.invalidReplacementFields;
+                if (first) {
+                    remainingInvalidFields = hasFieldRepairs
+                        ? invalidFields.filter((name) => prepared.invalidReplacementFields.includes(name))
+                        : invalidFields;
+                }
+                const repairedFields = invalidFields.filter((name) => !remainingInvalidFields.includes(name));
+                const hasChanges = text.slice(anchor, contentStart) !== replacement;
+                if (hasChanges) {
+                    let messageId = first ? 'spacing' : 'missing';
+                    if (repairedFields.length > 0)
+                        messageId = 'invalidValue';
+                    context.report({
+                        node,
+                        messageId,
+                        data: { fields: repairedFields.join(', ') },
+                        fix: (fixer) => fixer.replaceTextRange([anchor, contentStart], replacement),
+                    });
+                }
+                // Oxlint removes fixed diagnostics without re-linting; retain errors needing human input.
+                if (remainingInvalidFields.length > 0) {
+                    context.report({ node, messageId: 'invalidValue', data: { fields: remainingInvalidFields.join(', ') } });
+                }
+            },
+        };
+    },
+};
+const plugin = {
+    meta: { name: '@rm-industries/oxlint-plugin-headstamp' },
+    rules: { header },
+};
+export default plugin;

package/dist/template.d.ts

@@ -0,0 +1,22 @@
+export interface HeaderValue {
+    pattern: string;
+    replacement: string;
+}
+export interface HeaderOptions {
+    template: string;
+    values?: Record<string, HeaderValue>;
+    allowedLeadingComments?: Array<string | {
+        pattern: string;
+    }>;
+    blankLinesAfter?: number;
+}
+export declare function prepareHeader(options: unknown): {
+    rendered: string;
+    blankLinesAfter: number;
+    inspect: (comment: string) => {
+        invalidFields: string[];
+        repaired: string;
+    } | 'ambiguous' | null;
+    invalidReplacementFields: string[];
+    isAllowedLeadingComment: (comment: string) => boolean;
+};

package/dist/template.js

@@ -0,0 +1,191 @@
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isCompleteComment(text) {
+    const isBlockComment = text.length >= 4 && text.startsWith('/*') && text.indexOf('*/') === text.length - 2;
+    const isLineCommentGroup = text.split('\n').every((line) => line.startsWith('//'));
+    const hasSupportedCommentStyle = isBlockComment || isLineCommentGroup;
+    const hasUnsupportedLineEndings = /[\r\u2028\u2029]/.test(text);
+    return hasSupportedCommentStyle && !hasUnsupportedLineEndings;
+}
+function fullValuePattern(pattern) {
+    const expression = new RegExp(pattern);
+    return new RegExp(`^(?:${expression.source})$`);
+}
+function matchValues(comment, parts, fields, checkPatterns) {
+    if (!comment.startsWith(parts[0]))
+        return null;
+    const memo = new Map();
+    function visit(index, start) {
+        if (index === fields.length)
+            return { count: start === comment.length ? 1 : 0, values: [] };
+        const key = `${index}:${start}`;
+        const cached = memo.get(key);
+        if (cached)
+            return cached;
+        const field = fields[index];
+        const delimiter = parts[index + 1];
+        const nextLineBreak = comment.slice(start).search(/[\r\n\u2028\u2029]/);
+        const lineEnd = nextLineBreak < 0 ? comment.length : start + nextLineBreak;
+        let end = delimiter.length === 0 ? comment.length : comment.indexOf(delimiter, start);
+        const result = { count: 0, values: [] };
+        while (end >= 0 && end <= lineEnd) {
+            const value = comment.slice(start, end);
+            const isAllowedValue = !checkPatterns || field.pattern.test(value);
+            if (isAllowedValue) {
+                const tail = visit(index + 1, end + delimiter.length);
+                if (tail.count > 0) {
+                    if (result.count === 0)
+                        result.values = [value, ...tail.values];
+                    result.count += tail.count;
+                    // Two matches already prove ambiguity; do not enumerate further splits.
+                    if (result.count >= 2)
+                        break;
+                }
+            }
+            end = delimiter.length === 0 ? -1 : comment.indexOf(delimiter, end + 1);
+        }
+        memo.set(key, result);
+        return result;
+    }
+    const result = visit(0, parts[0].length);
+    if (result.count === 0)
+        return null;
+    return result.count === 1 ? result.values : 'ambiguous';
+}
+export function prepareHeader(options) {
+    if (!isRecord(options))
+        throw new Error('Headstamp requires a template string and optional values map.');
+    const configuredTemplate = options.template;
+    const hasTemplateString = typeof configuredTemplate === 'string';
+    const hasKnownOptions = Object.keys(options).every((key) => key === 'template' || key === 'values' || key === 'allowedLeadingComments' || key === 'blankLinesAfter');
+    if (!hasTemplateString || !hasKnownOptions)
+        throw new Error('Headstamp requires a template string and optional values map.');
+    const blankLinesAfter = options.blankLinesAfter === undefined ? 1 : options.blankLinesAfter;
+    const hasValidBlankLineCount = typeof blankLinesAfter === 'number' && Number.isSafeInteger(blankLinesAfter) && blankLinesAfter >= 0;
+    if (!hasValidBlankLineCount)
+        throw new Error('Headstamp blankLinesAfter must be a nonnegative safe integer.');
+    const leadingComments = options.allowedLeadingComments === undefined ? [] : options.allowedLeadingComments;
+    if (!Array.isArray(leadingComments))
+        throw new Error('Headstamp allowedLeadingComments must be an array.');
+    const allowedLeadingComments = leadingComments.map((comment) => {
+        if (typeof comment === 'string') {
+            const normalized = comment.replace(/\r\n/g, '\n').replace(/\n+$/, '');
+            if (!isCompleteComment(normalized))
+                throw new Error('Headstamp permitted literals must be complete comments.');
+            return normalized;
+        }
+        if (!isRecord(comment))
+            throw new Error('Headstamp permitted comments require a literal comment or pattern string.');
+        const pattern = comment.pattern;
+        const hasPatternString = typeof pattern === 'string';
+        const hasOnlyPattern = Object.keys(comment).length === 1;
+        if (!hasPatternString || !hasOnlyPattern)
+            throw new Error('Headstamp permitted comments require a literal comment or pattern string.');
+        try {
+            return fullValuePattern(pattern);
+        }
+        catch {
+            throw new Error('Headstamp permitted comment has an invalid regex.');
+        }
+    });
+    const values = options.values === undefined ? {} : options.values;
+    if (!isRecord(values))
+        throw new Error('Headstamp values must be an object.');
+    const template = configuredTemplate.replace(/\r\n/g, '\n').replace(/\n+$/, '');
+    if (!isCompleteComment(template))
+        throw new Error('Headstamp template must be one complete block comment or consecutive // comments using LF or CRLF.');
+    const parts = [];
+    const fields = [];
+    const names = new Set();
+    let cursor = 0;
+    for (const match of template.matchAll(/\{\{([A-Za-z_]\w*)\}\}/g)) {
+        const name = match[1];
+        const literal = template.slice(cursor, match.index);
+        const isAdjacentPlaceholder = fields.length > 0 && literal.length === 0;
+        if (isAdjacentPlaceholder)
+            throw new Error('Headstamp placeholders must be separated by literal text.');
+        if (names.has(name))
+            throw new Error(`Headstamp placeholder "${name}" must occur once.`);
+        if (!Object.hasOwn(values, name))
+            throw new Error(`Headstamp placeholder "${name}" has no definition.`);
+        const definition = values[name];
+        if (!isRecord(definition))
+            throw new Error(`Headstamp placeholder "${name}" requires pattern and replacement strings.`);
+        const pattern = definition.pattern;
+        const replacement = definition.replacement;
+        const hasPatternString = typeof pattern === 'string';
+        const hasReplacementString = typeof replacement === 'string';
+        const hasOnlyValueProperties = Object.keys(definition).length === 2;
+        if (!hasPatternString || !hasReplacementString || !hasOnlyValueProperties)
+            throw new Error(`Headstamp placeholder "${name}" requires pattern and replacement strings.`);
+        const hasMultilineReplacement = /[\r\n\u2028\u2029]/.test(replacement);
+        if (hasMultilineReplacement)
+            throw new Error(`Headstamp placeholder "${name}" replacement must be single-line.`);
+        let validator;
+        try {
+            validator = fullValuePattern(pattern);
+        }
+        catch {
+            throw new Error(`Headstamp placeholder "${name}" has an invalid regex.`);
+        }
+        parts.push(literal);
+        fields.push({ name, pattern: validator, replacement });
+        names.add(name);
+        cursor = match.index + match[0].length;
+    }
+    parts.push(template.slice(cursor));
+    const hasMalformedPlaceholder = parts.some((part) => part.includes('{{') || part.includes('}}'));
+    if (hasMalformedPlaceholder)
+        throw new Error('Headstamp placeholders must use {{name}} with an identifier name.');
+    if (Object.keys(values).length !== fields.length)
+        throw new Error('Headstamp values must define exactly the template placeholders.');
+    function render(fieldValues) {
+        let comment = parts[0];
+        for (const [index, value] of fieldValues.entries())
+            comment += value + parts[index + 1];
+        return comment;
+    }
+    const rendered = render(fields.map((field) => field.replacement));
+    if (!isCompleteComment(rendered))
+        throw new Error('Headstamp replacement values must preserve the complete comment.');
+    function inspect(comment) {
+        if (fields.length === 0)
+            return comment === template ? { invalidFields: [], repaired: comment } : null;
+        const values = matchValues(comment, parts, fields, true) ?? matchValues(comment, parts, fields, false);
+        if (values === null || values === 'ambiguous')
+            return values;
+        const invalidFields = [];
+        const repairedValues = values.map((value, index) => {
+            const field = fields[index];
+            if (field.pattern.test(value))
+                return value;
+            invalidFields.push(field.name);
+            const hasValidReplacement = field.pattern.test(field.replacement);
+            return hasValidReplacement ? field.replacement : value;
+        });
+        const repaired = render(repairedValues);
+        if (repaired === comment)
+            return { invalidFields, repaired };
+        const resultingValues = matchValues(repaired, parts, fields, true) ?? matchValues(repaired, parts, fields, false);
+        const preservesFieldBoundaries = resultingValues !== null &&
+            resultingValues !== 'ambiguous' &&
+            resultingValues.every((value, index) => value === repairedValues[index]);
+        const hasSafeRepair = isCompleteComment(repaired) && preservesFieldBoundaries;
+        return { invalidFields, repaired: hasSafeRepair ? repaired : comment };
+    }
+    const invalidReplacementFields = fields
+        .filter((field) => !field.pattern.test(field.replacement))
+        .map((field) => field.name);
+    const replacementsMatchPatterns = invalidReplacementFields.length === 0;
+    const hasAmbiguousGeneratedHeader = replacementsMatchPatterns && inspect(rendered) === 'ambiguous';
+    if (hasAmbiguousGeneratedHeader)
+        throw new Error('Headstamp generated header has ambiguous placeholder boundaries.');
+    return {
+        rendered,
+        blankLinesAfter,
+        inspect,
+        invalidReplacementFields,
+        isAllowedLeadingComment: (comment) => allowedLeadingComments.some((allowed) => typeof allowed === 'string' ? allowed === comment : allowed.test(comment)),
+    };
+}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@rm-industries/oxlint-plugin-headstamp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Oxlint-first header templates, regex validation, and safe insertion.",
+  "keywords": [
+    "autofix",
+    "copyright-header",
+    "file-header",
+    "header-template",
+    "javascript",
+    "license-header",
+    "oxlint",
+    "oxlint-plugin",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rm-industries/headstamp.git"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --project tsconfig.test.json",
+    "test": "npm run typecheck && npm run build && node --test test/*.test.ts",
+    "test:rule": "npm run typecheck && node --test test/header.test.ts",
+    "lint": "oxlint src test scripts oxfmt.config.ts",
+    "prepack": "npm run build",
+    "format:check": "oxfmt --check .",
+    "format": "oxfmt --write ."
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "oxfmt": "^0.78.0",
+    "oxlint": "^1.93.0",
+    "typescript": "^7.0.2"
+  },
+  "peerDependencies": {
+    "oxlint": "^1.88.0"
+  },
+  "engines": {
+    "node": "^22.18.0 || >=24.0.0"
+  }
+}