@cldmv/fix-headers 1.0.0 → 1.1.1

package/src/detectors/index.mjs

@@ -2,13 +2,13 @@
  *	@Project: @cldmv/fix-headers
  *	@Filename: /src/detectors/index.mjs
  *	@Date: 2026-03-01 16:34:41 -08:00 (1772411681)
- *	@Author: Nate Hyson <CLDMV>
+ *	@Author: Nate Corcoran <CLDMV>
  *	@Email: <Shinrai@users.noreply.github.com>
  *	-----
- *	@Last modified by: Nate Hyson <CLDMV> (Shinrai@users.noreply.github.com)
- *	@Last modified time: 2026-03-01 17:57:59 -08:00 (1772416679)
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-03-01T17:59:32-08:00 (1772416772)
  *	-----
- *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ *	@Copyright: Copyright (c) 2026-2026 Catalyzed Motivation Inc. All rights reserved.
  */
 
 import { readdir } from "node:fs/promises";
@@ -29,7 +29,8 @@ import { dirname, join } from "node:path";
  *  enabledByDefault: boolean,
  *  findNearestConfig: (startPath: string) => Promise<{root: string, marker: string} | null>,
  *  parseProjectName: (marker: string, markerContent: string, rootDirName: string) => string,
- *  resolveCommentSyntax: (filePath: string) => ({kind: "block" | "line" | "html", linePrefix?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string} | null),
+ *  resolveCommentSyntax: (filePath: string) => ({kind: "block" | "line" | "html", linePrefix?: string, lineSeparator?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string} | null),
+ *  resolvePreservedPrefix?: (filePath: string, content: string) => string,
  *  priority?: number
  * }} DetectorProfile
  */
@@ -63,9 +64,9 @@ const detectorMap = new Map(DETECTOR_PROFILES.map((detector) => [detector.id, de
 
 /**
  * Applies runtime syntax overrides to a detector-provided syntax descriptor.
- * @param {{kind: "block" | "line" | "html", linePrefix?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string}} syntax - Base syntax descriptor.
- * @param {{ linePrefix?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string } | undefined} override - Override descriptor.
- * @returns {{kind: "block" | "line" | "html", linePrefix?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string}} Effective descriptor.
+ * @param {{kind: "block" | "line" | "html", linePrefix?: string, lineSeparator?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string}} syntax - Base syntax descriptor.
+ * @param {{ linePrefix?: string, lineSeparator?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string } | undefined} override - Override descriptor.
+ * @returns {{kind: "block" | "line" | "html", linePrefix?: string, lineSeparator?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string}} Effective descriptor.
  */
 function applySyntaxOverride(syntax, override) {
 	if (!override || typeof override !== "object") {
@@ -75,7 +76,8 @@ function applySyntaxOverride(syntax, override) {
 	if (syntax.kind === "line") {
 		return {
 			...syntax,
-			linePrefix: typeof override.linePrefix === "string" && override.linePrefix.length > 0 ? override.linePrefix : syntax.linePrefix
+			linePrefix: typeof override.linePrefix === "string" && override.linePrefix.length > 0 ? override.linePrefix : syntax.linePrefix,
+			lineSeparator: typeof override.lineSeparator === "string" ? override.lineSeparator : syntax.lineSeparator
 		};
 	}
 
@@ -138,8 +140,8 @@ export function getDetectorById(id) {
 /**
  * Resolves comment syntax for a file path using detector-specific templates.
  * @param {string} filePath - File path.
- * @param {{ language?: string, enabledDetectors?: string[], disabledDetectors?: string[], detectorSyntaxOverrides?: Record<string, { linePrefix?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string }> }} [options={}] - Runtime options.
- * @returns {{kind: "block" | "line" | "html", linePrefix?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string}} Syntax descriptor.
+ * @param {{ language?: string, enabledDetectors?: string[], disabledDetectors?: string[], detectorSyntaxOverrides?: Record<string, { linePrefix?: string, lineSeparator?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string }> }} [options={}] - Runtime options.
+ * @returns {{kind: "block" | "line" | "html", linePrefix?: string, lineSeparator?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string}} Syntax descriptor.
  */
 export function getCommentSyntaxForFile(filePath, options = {}) {
 	const extension = extname(filePath).toLowerCase();
@@ -158,3 +160,28 @@ export function getCommentSyntaxForFile(filePath, options = {}) {
 
 	return { kind: "block", blockStart: "/**", blockLinePrefix: " *\t", blockEnd: " */" };
 }
+
+/**
+ * Resolves detector-specific leading content that must be preserved above inserted headers.
+ * @param {string} filePath - File path.
+ * @param {string} content - Full file content.
+ * @param {{ language?: string, enabledDetectors?: string[], disabledDetectors?: string[] }} [options={}] - Runtime options.
+ * @returns {string} Preserved prefix (possibly empty).
+ */
+export function getPreservedPrefixForFile(filePath, content, options = {}) {
+	const extension = extname(filePath).toLowerCase();
+	const detectors = getEnabledDetectors(options);
+	for (const detector of detectors) {
+		if (!detector.extensions.includes(extension)) {
+			continue;
+		}
+
+		if (typeof detector.resolvePreservedPrefix === "function") {
+			return detector.resolvePreservedPrefix(filePath, content);
+		}
+
+		return "";
+	}
+
+	return "";
+}

package/src/detectors/node.mjs

@@ -1,3 +1,16 @@
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /src/detectors/node.mjs
+ *	@Date: 2026-03-01T17:59:32-08:00 (1772416772)
+ *	@Author: Nate Corcoran <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-03-01T17:59:32-08:00 (1772416772)
+ *	-----
+ *	@Copyright: Copyright (c) 2026-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
+
 import { extname } from "node:path";
 import { findNearestMarker } from "./shared.mjs";
 
@@ -45,6 +58,17 @@ function resolveNodeCommentSyntax(filePath) {
 	return null;
 }
 
+/**
+ * Resolves preserved leading prefix for Node files (for example: shebang line).
+ * @param {string} _filePath - File path.
+ * @param {string} content - File content.
+ * @returns {string} Preserved prefix.
+ */
+function resolveNodePreservedPrefix(_filePath, content) {
+	const shebangMatch = content.match(/^#!.*\b(node|bun|deno|tsx|ts-node)\b.*(?:\r?\n|$)/);
+	return shebangMatch ? shebangMatch[0] : "";
+}
+
 export const detector = {
 	id: "node",
 	priority: 100,
@@ -57,6 +81,9 @@ export const detector = {
 	parseProjectName(_marker, markerContent, rootDirName) {
 		return parseNodeProjectName(markerContent, rootDirName);
 	},
+	resolvePreservedPrefix(filePath, content) {
+		return resolveNodePreservedPrefix(filePath, content);
+	},
 	resolveCommentSyntax(filePath) {
 		return resolveNodeCommentSyntax(filePath);
 	}

package/src/detectors/php.mjs

@@ -1,3 +1,16 @@
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /src/detectors/php.mjs
+ *	@Date: 2026-03-01T17:59:32-08:00 (1772416772)
+ *	@Author: Nate Corcoran <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-03-01T17:59:32-08:00 (1772416772)
+ *	-----
+ *	@Copyright: Copyright (c) 2026-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
+
 import { extname } from "node:path";
 import { findNearestMarker } from "./shared.mjs";
 

package/src/detectors/python.mjs

@@ -1,3 +1,16 @@
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /src/detectors/python.mjs
+ *	@Date: 2026-03-01T17:59:32-08:00 (1772416772)
+ *	@Author: Nate Corcoran <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-03-01T17:59:32-08:00 (1772416772)
+ *	-----
+ *	@Copyright: Copyright (c) 2026-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
+
 import { extname } from "node:path";
 import { findNearestMarker } from "./shared.mjs";
 
@@ -23,6 +36,17 @@ function parsePythonProjectName(markerContent, rootDirName) {
 	return rootDirName;
 }
 
+/**
+ * Resolves preserved leading prefix for Python files (for example: shebang line).
+ * @param {string} _filePath - File path.
+ * @param {string} content - File content.
+ * @returns {string} Preserved prefix.
+ */
+function resolvePythonPreservedPrefix(_filePath, content) {
+	const shebangMatch = content.match(/^#!.*\bpython(?:\d+(?:\.\d+)*)?\b.*(?:\r?\n|$)/);
+	return shebangMatch ? shebangMatch[0] : "";
+}
+
 export const detector = {
 	id: "python",
 	priority: 80,
@@ -35,6 +59,9 @@ export const detector = {
 	parseProjectName(_marker, markerContent, rootDirName) {
 		return parsePythonProjectName(markerContent, rootDirName);
 	},
+	resolvePreservedPrefix(filePath, content) {
+		return resolvePythonPreservedPrefix(filePath, content);
+	},
 	resolveCommentSyntax(filePath) {
 		const extension = extname(filePath).toLowerCase();
 		if (extensions.includes(extension)) {

package/src/detectors/rust.mjs

@@ -1,3 +1,16 @@
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /src/detectors/rust.mjs
+ *	@Date: 2026-03-01T17:59:32-08:00 (1772416772)
+ *	@Author: Nate Corcoran <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-03-01T17:59:32-08:00 (1772416772)
+ *	-----
+ *	@Copyright: Copyright (c) 2026-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
+
 import { extname } from "node:path";
 import { findNearestMarker } from "./shared.mjs";
 

package/src/detectors/shared.mjs

@@ -1,3 +1,16 @@
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /src/detectors/shared.mjs
+ *	@Date: 2026-03-01T17:59:32-08:00 (1772416772)
+ *	@Author: Nate Corcoran <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-03-01T17:59:32-08:00 (1772416772)
+ *	-----
+ *	@Copyright: Copyright (c) 2026-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
+
 import { dirname, join, resolve } from "node:path";
 import { pathExists } from "../utils/fs.mjs";
 

package/src/detectors/yaml.mjs

@@ -0,0 +1,79 @@
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /src/detectors/yaml.mjs
+ *	@Date: 2026-03-01 18:28:31 -08:00 (1772418511)
+ *	@Author: Nate Corcoran <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-03-01 19:32:27 -08:00 (1772422347)
+ *	-----
+ *	@Copyright: Copyright (c) 2026-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
+
+import { extname } from "node:path";
+import { findNearestMarker } from "./shared.mjs";
+
+/**
+ * @fileoverview YAML detector implementation.
+ * @module fix-headers/detectors/yaml
+ */
+
+const markers = ["package.json", ".git"];
+const extensions = [".yaml", ".yml"];
+
+/**
+ * Parses YAML project name from nearest marker content when available.
+ * @param {string} marker - Marker filename.
+ * @param {string} markerContent - Marker content.
+ * @param {string} rootDirName - Fallback root directory name.
+ * @returns {string} Project name.
+ */
+function parseYamlProjectName(marker, markerContent, rootDirName) {
+	if (marker !== "package.json") {
+		return rootDirName;
+	}
+
+	try {
+		const parsed = JSON.parse(markerContent);
+		if (typeof parsed.name === "string" && parsed.name.trim().length > 0) {
+			return parsed.name.trim();
+		}
+		return rootDirName;
+	} catch {
+		return rootDirName;
+	}
+}
+
+/**
+ * Resolves comment syntax for YAML file extensions.
+ * @param {string} filePath - File path.
+ * @returns {{kind: "line", linePrefix: string} | null} Syntax descriptor.
+ */
+function resolveYamlCommentSyntax(filePath) {
+	const extension = extname(filePath).toLowerCase();
+	if (extensions.includes(extension)) {
+		return {
+			kind: "line",
+			linePrefix: "#"
+		};
+	}
+	return null;
+}
+
+export const detector = {
+	id: "yaml",
+	priority: 60,
+	markers,
+	extensions,
+	enabledByDefault: true,
+	findNearestConfig(startPath) {
+		return findNearestMarker(startPath, markers);
+	},
+	parseProjectName(marker, markerContent, rootDirName) {
+		return parseYamlProjectName(marker, markerContent, rootDirName);
+	},
+	resolveCommentSyntax(filePath) {
+		return resolveYamlCommentSyntax(filePath);
+	}
+};

package/src/fix-header.mjs

@@ -2,13 +2,13 @@
  *	@Project: @cldmv/fix-headers
  *	@Filename: /src/fix-header.mjs
  *	@Date: 2026-03-01 13:34:00 -08:00 (1772400840)
- *	@Author: Nate Hyson <CLDMV>
+ *	@Author: Nate Corcoran <CLDMV>
  *	@Email: <Shinrai@users.noreply.github.com>
  *	-----
- *	@Last modified by: Nate Hyson <CLDMV> (Shinrai@users.noreply.github.com)
- *	@Last modified time: 2026-03-01 14:39:14 -08:00 (1772404754)
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-03-01T17:59:32-08:00 (1772416772)
  *	-----
- *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ *	@Copyright: Copyright (c) 2026-2026 Catalyzed Motivation Inc. All rights reserved.
  */
 
 import { fixHeaders as fixHeadersCore } from "./core/fix-headers.mjs";

package/src/header/parser.mjs

@@ -1,4 +1,18 @@
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /src/header/parser.mjs
+ *	@Date: 2026-03-01T17:59:32-08:00 (1772416772)
+ *	@Author: Nate Corcoran <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-03-01T17:59:32-08:00 (1772416772)
+ *	-----
+ *	@Copyright: Copyright (c) 2026-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
+
 import { DEFAULT_MAX_HEADER_SCAN_LINES } from "../constants.mjs";
+import { getPreservedPrefixForFile } from "../detectors/index.mjs";
 import { getHeaderSyntaxForFile } from "./syntax.mjs";
 
 /**
@@ -16,41 +30,85 @@ function escapeRegex(text) {
 }
 
 /**
- * Finds the first top-level project header block in a file.
+ * Splits detector-defined preserved prefix from file content when present.
+ * @param {string} filePath - File path used for detector selection.
  * @param {string} content - File content.
- * @param {string} [filePath=""] - File path used for syntax selection.
- * @param {{ language?: string, enabledDetectors?: string[], disabledDetectors?: string[], detectorSyntaxOverrides?: Record<string, { linePrefix?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string }> }} [syntaxOptions={}] - Syntax resolution options.
- * @returns {{start: number, end: number} | null} Header location.
+ * @param {{ language?: string, enabledDetectors?: string[], disabledDetectors?: string[], detectorSyntaxOverrides?: Record<string, { linePrefix?: string, lineSeparator?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string }> }} [syntaxOptions={}] - Syntax/detector options.
+ * @returns {{prefix: string, body: string}} Shebang prefix and remaining body.
  */
-export function findProjectHeader(content, filePath = "", syntaxOptions = {}) {
-	const scanLines = content.split("\n").slice(0, DEFAULT_MAX_HEADER_SCAN_LINES).join("\n");
-	const syntax = getHeaderSyntaxForFile(filePath, syntaxOptions);
+function splitPreservedPrefix(filePath, content, syntaxOptions = {}) {
+	const prefix = getPreservedPrefixForFile(filePath, content, syntaxOptions);
+	if (prefix.length === 0) {
+		return { prefix: "", body: content };
+	}
+
+	return {
+		prefix,
+		body: content.slice(prefix.length)
+	};
+}
 
-	let match = null;
+/**
+ * Matches a top-of-content header block for a given syntax.
+ * @param {string} content - Content slice to match from start.
+ * @param {{kind: "block" | "line" | "html", linePrefix?: string, lineSeparator?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string}} syntax - Header syntax descriptor.
+ * @returns {RegExpMatchArray | null} Matched header segment.
+ */
+function matchHeaderSegment(content, syntax) {
 	if (syntax.kind === "html") {
 		const blockStart = escapeRegex(syntax.blockStart || "<!--");
 		const blockEnd = escapeRegex(syntax.blockEnd || "-->");
-		match = scanLines.match(new RegExp(`^${blockStart}[\\s\\S]*?${blockEnd}\\n*`));
-	} else if (syntax.kind === "line") {
+		return content.match(new RegExp(`^${blockStart}[\\s\\S]*?${blockEnd}\\n*`));
+	}
+
+	if (syntax.kind === "line") {
 		const linePrefix = escapeRegex(syntax.linePrefix || "#");
-		match = scanLines.match(new RegExp(`^(?:${linePrefix}.*\\n)+\\n*`));
-	} else {
-		const blockStart = escapeRegex(syntax.blockStart || "/**");
-		const blockEnd = escapeRegex(syntax.blockEnd || " */");
-		match = scanLines.match(new RegExp(`^${blockStart}[\\s\\S]*?${blockEnd}\\n*`));
+		return content.match(new RegExp(`^(?:${linePrefix}.*\\n)+\\n*`));
 	}
 
+	const blockStart = escapeRegex(syntax.blockStart || "/**");
+	const blockEnd = escapeRegex(syntax.blockEnd || " */");
+	return content.match(new RegExp(`^${blockStart}[\\s\\S]*?${blockEnd}\\n*`));
+}
+
+/**
+ * Finds the first top-level project header block in a file.
+ * @param {string} content - File content.
+ * @param {string} [filePath=""] - File path used for syntax selection.
+ * @param {{ language?: string, enabledDetectors?: string[], disabledDetectors?: string[], detectorSyntaxOverrides?: Record<string, { linePrefix?: string, lineSeparator?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string }> }} [syntaxOptions={}] - Syntax resolution options.
+ * @returns {{start: number, end: number} | null} Header location.
+ */
+export function findProjectHeader(content, filePath = "", syntaxOptions = {}) {
+	const { prefix, body } = splitPreservedPrefix(filePath, content, syntaxOptions);
+	const scanLines = body.split("\n").slice(0, DEFAULT_MAX_HEADER_SCAN_LINES).join("\n");
+	const syntax = getHeaderSyntaxForFile(filePath, syntaxOptions);
+	const match = matchHeaderSegment(scanLines, syntax);
+
 	if (!match) {
 		return null;
 	}
 
-	if (!match[0].includes("@Project:")) {
+	let offset = 0;
+	let end = 0;
+	while (true) {
+		const remaining = scanLines.slice(offset);
+		const segment = matchHeaderSegment(remaining, syntax);
+
+		if (!segment || !segment[0].includes("@Project:")) {
+			break;
+		}
+
+		offset += segment[0].length;
+		end = offset;
+	}
+
+	if (end === 0) {
 		return null;
 	}
 
 	return {
-		start: 0,
-		end: match[0].length
+		start: prefix.length,
+		end: prefix.length + end
 	};
 }
 
@@ -59,13 +117,14 @@ export function findProjectHeader(content, filePath = "", syntaxOptions = {}) {
  * @param {string} content - Original file content.
  * @param {string} newHeader - Generated header text.
  * @param {string} [filePath=""] - File path used for syntax selection.
- * @param {{ language?: string, enabledDetectors?: string[], disabledDetectors?: string[], detectorSyntaxOverrides?: Record<string, { linePrefix?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string }> }} [syntaxOptions={}] - Syntax resolution options.
+ * @param {{ language?: string, enabledDetectors?: string[], disabledDetectors?: string[], detectorSyntaxOverrides?: Record<string, { linePrefix?: string, lineSeparator?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string }> }} [syntaxOptions={}] - Syntax resolution options.
  * @returns {{nextContent: string, changed: boolean}} Updated content result.
  */
 export function replaceOrInsertHeader(content, newHeader, filePath = "", syntaxOptions = {}) {
 	const existing = findProjectHeader(content, filePath, syntaxOptions);
 	if (!existing) {
-		const nextContent = `${newHeader}\n\n${content.replace(/^\n+/, "")}`;
+		const { prefix, body } = splitPreservedPrefix(filePath, content, syntaxOptions);
+		const nextContent = `${prefix}${newHeader}\n\n${body.replace(/^\n+/, "")}`;
 		return { nextContent, changed: nextContent !== content };
 	}
 

package/src/header/syntax.mjs

@@ -1,3 +1,16 @@
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /src/header/syntax.mjs
+ *	@Date: 2026-03-01T17:59:32-08:00 (1772416772)
+ *	@Author: Nate Corcoran <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-03-01T17:59:32-08:00 (1772416772)
+ *	-----
+ *	@Copyright: Copyright (c) 2026-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
+
 import { extname } from "node:path";
 import { getCommentSyntaxForFile } from "../detectors/index.mjs";
 
@@ -10,6 +23,7 @@ import { getCommentSyntaxForFile } from "../detectors/index.mjs";
  * @typedef {{
  *  kind: "block" | "line" | "html",
  *  linePrefix?: string,
+ *  lineSeparator?: string,
  *  blockStart?: string,
  *  blockLinePrefix?: string,
  *  blockEnd?: string
@@ -19,7 +33,7 @@ import { getCommentSyntaxForFile } from "../detectors/index.mjs";
 /**
  * Resolves comment syntax for a file path based on extension.
  * @param {string} filePath - Absolute or relative file path.
- * @param {{ language?: string, enabledDetectors?: string[], disabledDetectors?: string[], detectorSyntaxOverrides?: Record<string, { linePrefix?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string }> }} [options={}] - Syntax resolution options.
+ * @param {{ language?: string, enabledDetectors?: string[], disabledDetectors?: string[], detectorSyntaxOverrides?: Record<string, { linePrefix?: string, lineSeparator?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string }> }} [options={}] - Syntax resolution options.
  * @returns {HeaderSyntax} Header syntax descriptor.
  */
 export function getHeaderSyntaxForFile(filePath, options = {}) {
@@ -39,7 +53,8 @@ export function getHeaderSyntaxForFile(filePath, options = {}) {
  */
 export function renderHeaderLines(syntax, lines) {
 	if (syntax.kind === "line") {
-		return lines.map((line) => `${syntax.linePrefix || "#"}\t${line}`).join("\n");
+		const lineSeparator = typeof syntax.lineSeparator === "string" ? syntax.lineSeparator : "\t";
+		return lines.map((line) => `${syntax.linePrefix || "#"}${lineSeparator}${line}`).join("\n");
 	}
 
 	const blockStart = syntax.blockStart || (syntax.kind === "html" ? "<!--" : "/**");

package/src/header/template.mjs

@@ -1,3 +1,16 @@
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /src/header/template.mjs
+ *	@Date: 2026-03-01T17:59:32-08:00 (1772416772)
+ *	@Author: Nate Corcoran <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-03-01T17:59:32-08:00 (1772416772)
+ *	-----
+ *	@Copyright: Copyright (c) 2026-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
+
 import { relative } from "node:path";
 import { getHeaderSyntaxForFile, renderHeaderLines } from "./syntax.mjs";
 
@@ -11,8 +24,12 @@ import { getHeaderSyntaxForFile, renderHeaderLines } from "./syntax.mjs";
  * @param {{
  *  absoluteFilePath: string,
  *  language?: string,
- *  syntaxOptions?: { language?: string, enabledDetectors?: string[], disabledDetectors?: string[], detectorSyntaxOverrides?: Record<string, { linePrefix?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string }> },
+ *  syntaxOptions?: { language?: string, enabledDetectors?: string[], disabledDetectors?: string[], detectorSyntaxOverrides?: Record<string, { linePrefix?: string, lineSeparator?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string }> },
  *  projectRoot: string,
+ *  createdByName?: string,
+ *  createdByEmail?: string,
+ *  lastModifiedByName?: string,
+ *  lastModifiedByEmail?: string,
  *  projectName: string,
  *  authorName: string,
  *  authorEmail: string,
@@ -27,17 +44,21 @@ import { getHeaderSyntaxForFile, renderHeaderLines } from "./syntax.mjs";
 export function buildHeader(data) {
 	const relativePath = `/${relative(data.projectRoot, data.absoluteFilePath).replace(/\\/g, "/")}`;
 	const syntax = getHeaderSyntaxForFile(data.absoluteFilePath, data.syntaxOptions || { language: data.language });
+	const createdByName = data.createdByName || data.authorName;
+	const createdByEmail = data.createdByEmail || data.authorEmail;
+	const lastModifiedByName = data.lastModifiedByName || data.authorName;
+	const lastModifiedByEmail = data.lastModifiedByEmail || data.authorEmail;
 	const headerLines = [
 		`@Project: ${data.projectName}`,
 		`@Filename: ${relativePath}`,
 		`@Date: ${data.createdAt.date} (${data.createdAt.timestamp})`,
-		`@Author: ${data.authorName}`,
-		`@Email: <${data.authorEmail}>`,
+		`@Author: ${createdByName}`,
+		`@Email: <${createdByEmail}>`,
 		"-----",
-		`@Last modified by: ${data.authorName} (${data.authorEmail})`,
+		`@Last modified by: ${lastModifiedByName} (${lastModifiedByEmail})`,
 		`@Last modified time: ${data.lastModifiedAt.date} (${data.lastModifiedAt.timestamp})`,
 		"-----",
-		`@Copyright: Copyright (c) ${data.copyrightStartYear}-${data.currentYear} ${data.companyName}. All rights reserved.`
+		`@Copyright: Copyright (c) ${data.copyrightStartYear}-${data.currentYear} ${data.companyName} All rights reserved.`
 	];
 
 	return renderHeaderLines(syntax, headerLines);

package/src/utils/fs.mjs

@@ -1,3 +1,16 @@
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /src/utils/fs.mjs
+ *	@Date: 2026-03-01T17:59:32-08:00 (1772416772)
+ *	@Author: Nate Corcoran <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-03-01T17:59:32-08:00 (1772416772)
+ *	-----
+ *	@Copyright: Copyright (c) 2026-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
+
 import { access, readdir, readFile, stat } from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
 import { dirname, join, resolve } from "node:path";

package/src/utils/git.mjs

@@ -1,3 +1,16 @@
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /src/utils/git.mjs
+ *	@Date: 2026-03-01T17:59:32-08:00 (1772416772)
+ *	@Author: Nate Corcoran <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-03-01T17:59:32-08:00 (1772416772)
+ *	-----
+ *	@Copyright: Copyright (c) 2026-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
+
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 
@@ -24,14 +37,39 @@ export async function runGit(cwd, args) {
 	}
 }
 
+/**
+ * Parses a signer UID string into author name and optional email.
+ * @param {string} signerUid - Raw signer UID (for example: "Name (Comment) <email@example.com>").
+ * @returns {{authorName: string | null, authorEmail: string | null}} Parsed signer identity.
+ */
+function parseSignerUid(signerUid) {
+	const trimmed = signerUid.trim();
+	if (trimmed.length === 0) {
+		return { authorName: null, authorEmail: null };
+	}
+
+	const emailMatch = trimmed.match(/<([^>\n]+)>\s*$/);
+	const authorEmail = emailMatch?.[1]?.trim() || null;
+	const authorName = (emailMatch ? trimmed.slice(0, emailMatch.index) : trimmed).trim() || null;
+
+	return { authorName, authorEmail };
+}
+
 /**
  * Detects git author name and email from config or commit history.
  * @param {string} cwd - Project directory.
+ * @param {{useGpgSignerAuthor?: boolean}} [options={}] - Detection options.
  * @returns {Promise<{authorName: string | null, authorEmail: string | null}>} Author information.
  */
-export async function detectGitAuthor(cwd) {
+export async function detectGitAuthor(cwd, options = {}) {
 	let authorName = await runGit(cwd, ["config", "--get", "user.name"]);
 	let authorEmail = await runGit(cwd, ["config", "--get", "user.email"]);
+	if (options.useGpgSignerAuthor === true) {
+		const signerUid = await runGit(cwd, ["log", "-1", "--format=%GS"]);
+		const signerIdentity = parseSignerUid(signerUid || "");
+		authorName = signerIdentity.authorName || authorName;
+		authorEmail = authorEmail || signerIdentity.authorEmail;
+	}
 
 	if (!authorName || !authorEmail) {
 		const fallback = await runGit(cwd, ["log", "-1", "--format=%an|%ae"]);

package/src/utils/time.mjs

@@ -1,3 +1,16 @@
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /src/utils/time.mjs
+ *	@Date: 2026-03-01T17:59:32-08:00 (1772416772)
+ *	@Author: Nate Corcoran <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-03-01T17:59:32-08:00 (1772416772)
+ *	-----
+ *	@Copyright: Copyright (c) 2026-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
+
 /**
  * @fileoverview Date/time helpers used for header timestamp formatting.
  * @module fix-headers/utils/time