@cldmv/fix-headers 1.0.0 → 1.1.1

package/README.md

@@ -10,7 +10,7 @@ Multi-language source header normalizer for Node.js projects.
 
 ## Features
 
-- Auto-detects project type by marker files (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `composer.json`)
+- Auto-detects project type by marker files (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `composer.json`) and YAML files (`.yaml`, `.yml`)
 - Auto-detects author and email from git config/commit history
 - Supports per-run overrides for every detected value
 - Supports folder inclusion and exclusion configuration
@@ -52,6 +52,9 @@ Common CLI options:
 
 - `--dry-run`
 - `--json`
+- `--sample-output`
+- `--force-author-update`
+- `--use-gpg-signer-author`
 - `--cwd <path>`
 - `--input <path>`
 - `--include-folder <path>` (repeatable)
@@ -83,11 +86,12 @@ Important options:
 - `cwd?: string` - start directory for project detection
 - `input?: string` - explicit single file or folder path to process
 - `dryRun?: boolean` - compute changes without writing files
+- `sampleOutput?: boolean` - include previous/new header sample text for changed files
 - `configFile?: string` - load JSON options from file (resolved from `cwd`)
 - `includeExtensions?: string[]` - file extensions to process
 - `enabledDetectors?: string[]` - detector ids to enable (defaults to all)
 - `disabledDetectors?: string[]` - detector ids to disable
-- `detectorSyntaxOverrides?: Record<string, { linePrefix?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string }>` - override detector comment syntax tokens
+- `detectorSyntaxOverrides?: Record<string, { linePrefix?: string, lineSeparator?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string }>` - override detector comment syntax tokens
 - `includeFolders?: string[]` - project-relative folders to scan
 - `excludeFolders?: string[]` - folder names or relative paths to exclude
 - `projectName?: string`
@@ -96,6 +100,8 @@ Important options:
 - `marker?: string | null`
 - `authorName?: string`
 - `authorEmail?: string`
+- `forceAuthorUpdate?: boolean` - force update `@Author`/`@Email` to detected or overridden current values
+- `useGpgSignerAuthor?: boolean` - use signed-commit UID (`%GS`) for detected `@Author` (includes signer comment when present)
 - `companyName?: string` (default: `Catalyzed Motivation Inc.`)
 - `copyrightStartYear?: number` (default: current year)
 
@@ -115,7 +121,8 @@ const result = await fixHeaders({
 			blockEnd: " */"
 		},
 		python: {
-			linePrefix: ";;"
+			linePrefix: ";;",
+			lineSeparator: " "
 		}
 	},
 	projectName: "@scope/my-package",
@@ -128,6 +135,7 @@ const result = await fixHeaders({
 
 - `excludeFolders` supports both folder-name and nested path matching.
 - For monorepos, each file resolves metadata from the closest detector config in its parent tree.
+- With `sampleOutput` enabled, each changed file includes `previousValue`, `newValue`, and `detectedValues` in results.
 
 ## License
 

package/index.cjs

@@ -2,13 +2,13 @@
  *	@Project: @cldmv/fix-headers
  *	@Filename: /index.cjs
  *	@Date: 2026-03-01 13:29:45 -08:00 (1772400585)
- *	@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 16:29:36 -08:00 (1772411376)
+ *	@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.
  */
 
 /**

package/index.mjs

@@ -1,3 +1,16 @@
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /index.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 ESM shim for the fix-headers package API.
  * @module fix-headers/esm-shim

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cldmv/fix-headers",
-	"version": "1.0.0",
+	"version": "1.1.1",
 	"description": "Multi-language project header normalizer with auto-detection and override support.",
 	"type": "module",
 	"main": "./index.cjs",

package/src/cli.mjs

@@ -1,8 +1,21 @@
 #!/usr/bin/env node
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /src/cli.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 { readFile } from "node:fs/promises";
+import { realpathSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import fixHeaders from "./fix-header.mjs";
 
 /**
@@ -10,7 +23,7 @@ import fixHeaders from "./fix-header.mjs";
  * @module fix-headers/cli
  */
 
-const HELP_TEXT = `fix-headers CLI\n\nUsage:\n  fix-headers [options]\n\nOptions:\n  -h, --help                         Show help\n      --dry-run                      Compute changes without writing files\n      --json                         Print JSON output\n      --cwd <path>                   Working directory for project detection\n      --input <path>                 Single file or folder input\n      --include-folder <path>        Include folder (repeatable)\n      --exclude-folder <path>        Exclude folder name/path (repeatable)\n      --include-extension <ext>      Include extension (repeatable)\n      --enable-detector <id>         Enable only specific detector (repeatable)\n      --disable-detector <id>        Disable detector by id (repeatable)\n      --project-name <name>          Override project name\n      --language <id>                Override language id\n      --project-root <path>          Override project root\n      --marker <name|null>           Override marker filename\n      --author-name <name>           Override author name\n      --author-email <email>         Override author email\n      --company-name <name>          Override company name\n      --copyright-start-year <year>  Override copyright start year\n      --config <path>                Load JSON options file\n\nExamples:\n  fix-headers --dry-run --include-folder src\n  fix-headers --project-name @scope/pkg --company-name "Catalyzed Motivation Inc."\n`;
+const HELP_TEXT = `fix-headers CLI\n\nUsage:\n  fix-headers [options]\n\nOptions:\n  -h, --help                         Show help\n      --dry-run                      Compute changes without writing files\n      --json                         Print JSON output\n      --verbose                      Print updated file paths in summary mode\n      --sample-output                Show previous/new header sample for changed files\n      --force-author-update          Always update @Author/@Email to detected/current values\n      --use-gpg-signer-author        Use signed-commit UID (%GS) for detected @Author\n      --cwd <path>                   Working directory for project detection\n      --input <path>                 Single file or folder input\n      --include-folder <path>        Include folder (repeatable)\n      --exclude-folder <path>        Exclude folder name/path (repeatable)\n      --include-extension <ext>      Include extension (repeatable)\n      --enable-detector <id>         Enable only specific detector (repeatable)\n      --disable-detector <id>        Disable detector by id (repeatable)\n      --project-name <name>          Override project name\n      --language <id>                Override language id\n      --project-root <path>          Override project root\n      --marker <name|null>           Override marker filename\n      --author-name <name>           Override author name\n      --author-email <email>         Override author email\n      --company-name <name>          Override company name\n      --copyright-start-year <year>  Override copyright start year\n      --config <path>                Load JSON options file\n\nExamples:\n  fix-headers --dry-run --include-folder src\n  fix-headers --project-name @scope/pkg --company-name "Catalyzed Motivation Inc."\n`;
 
 /**
  * Converts CLI flag token to camelCase key.
@@ -65,10 +78,26 @@ export function parseCliArgs(argv) {
 			control.json = true;
 			continue;
 		}
+		if (arg === "--verbose") {
+			options.verbose = true;
+			continue;
+		}
 		if (arg === "--dry-run") {
 			options.dryRun = true;
 			continue;
 		}
+		if (arg === "--sample-output") {
+			options.sampleOutput = true;
+			continue;
+		}
+		if (arg === "--force-author-update") {
+			options.forceAuthorUpdate = true;
+			continue;
+		}
+		if (arg === "--use-gpg-signer-author") {
+			options.useGpgSignerAuthor = true;
+			continue;
+		}
 		if (!arg.startsWith("--")) {
 			throw new Error(`Unexpected argument: ${arg}`);
 		}
@@ -82,7 +111,7 @@ export function parseCliArgs(argv) {
 			index += 1;
 			const key = multiMap[flag];
 			const list = Array.isArray(options[key]) ? options[key] : [];
-			options[key] = [...list, value];
+			options[key] = Array.from(new Set([...list, value]));
 			continue;
 		}
 
@@ -147,6 +176,58 @@ export async function applyConfigFile(options) {
 	return output;
 }
 
+/**
+ * Prints per-file previous/new header samples when available.
+ * @param {(message: string) => void} stdout - Standard output writer.
+ * @param {unknown} result - Runner result object.
+ * @returns {void}
+ */
+function printSampleOutput(stdout, result) {
+	if (!result || typeof result !== "object") {
+		return;
+	}
+
+	const report =
+		/** @type {{changes?: Array<{file?: string, changed?: boolean, sample?: { previousValue?: string | null, newValue?: string, detectedValues?: Record<string, unknown> }}>}} */ (
+			result
+		);
+	const changes = Array.isArray(report.changes) ? report.changes : [];
+	for (const change of changes) {
+		if (!change || change.changed !== true || !change.sample || typeof change.sample.newValue !== "string") {
+			continue;
+		}
+
+		stdout(`sample: ${change.file || "<unknown-file>"}`);
+		stdout("previous:");
+		stdout(change.sample.previousValue === null ? "(none)" : String(change.sample.previousValue));
+		stdout("new:");
+		stdout(change.sample.newValue);
+		if (change.sample.detectedValues && typeof change.sample.detectedValues === "object") {
+			stdout("detected-values:");
+			stdout(JSON.stringify(change.sample.detectedValues, null, 2));
+		}
+	}
+}
+
+/**
+ * Prints changed file paths from result payload.
+ * @param {(message: string) => void} stdout - Standard output writer.
+ * @param {unknown} result - Runner result object.
+ * @returns {void}
+ */
+function printChangedFiles(stdout, result) {
+	if (!result || typeof result !== "object") {
+		return;
+	}
+
+	const report = /** @type {{changes?: Array<{file?: string, changed?: boolean}>}} */ (result);
+	const changes = Array.isArray(report.changes) ? report.changes : [];
+	const updatedFiles = changes.filter((change) => change && change.changed === true).map((change) => change.file || "<unknown-file>");
+	for (const file of updatedFiles) {
+		stdout(`updated: ${file}`);
+	}
+}
+
 /**
  * Executes CLI flow and returns process-like exit code.
  * @param {string[]} argv - CLI arguments.
@@ -182,7 +263,19 @@ export async function runCli(argv, deps = {}) {
 			stdout(
 				`fix-headers complete: scanned=${report.filesScanned ?? 0}, updated=${report.filesUpdated ?? 0}, dryRun=${report.dryRun === true}`
 			);
+			if (finalOptions.verbose === true) {
+				printChangedFiles(stdout, result);
+			}
+			if (finalOptions.sampleOutput === true) {
+				printSampleOutput(stdout, result);
+			}
 		} else {
+			if (finalOptions.verbose === true) {
+				printChangedFiles(stdout, result);
+			}
+			if (finalOptions.sampleOutput === true) {
+				printSampleOutput(stdout, result);
+			}
 			stdout("fix-headers complete");
 		}
 		return 0;
@@ -201,7 +294,16 @@ export async function runCli(argv, deps = {}) {
  * @returns {boolean} Whether the entrypoint branch was executed.
  */
 export function runCliAsMain(argv = process.argv, moduleUrl = import.meta.url, executor = runCli) {
-	const isMain = argv[1] && moduleUrl === pathToFileURL(argv[1]).href;
+	let isMain = false;
+	if (argv[1]) {
+		try {
+			const argvRealPath = realpathSync(argv[1]);
+			const moduleRealPath = realpathSync(fileURLToPath(moduleUrl));
+			isMain = argvRealPath === moduleRealPath;
+		} catch {
+			isMain = moduleUrl === pathToFileURL(argv[1]).href;
+		}
+	}
 	if (!isMain) {
 		return false;
 	}

package/src/constants.mjs

@@ -1,3 +1,16 @@
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /src/constants.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 Shared constants for project/language detection and header defaults.
  * @module fix-headers/constants

package/src/core/file-discovery.mjs

@@ -1,3 +1,16 @@
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /src/core/file-discovery.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 { join, relative, resolve } from "node:path";
 import { DEFAULT_IGNORE_FOLDERS } from "../constants.mjs";
 import { getAllowedExtensions } from "../detectors/index.mjs";

package/src/core/fix-headers.mjs

@@ -1,9 +1,22 @@
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /src/core/fix-headers.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 { readFile, stat, writeFile } from "node:fs/promises";
 import { relative, resolve } from "node:path";
 import { discoverFiles } from "./file-discovery.mjs";
 import { resolveProjectMetadata } from "../detect/project.mjs";
 import { buildHeader } from "../header/template.mjs";
-import { replaceOrInsertHeader } from "../header/parser.mjs";
+import { findProjectHeader, replaceOrInsertHeader } from "../header/parser.mjs";
 import { readFileDates } from "../utils/fs.mjs";
 import { getGitCreationDate, getGitLastModifiedDate } from "../utils/git.mjs";
 import { toDatePayload } from "../utils/time.mjs";
@@ -14,9 +27,12 @@ import { toDatePayload } from "../utils/time.mjs";
  *  input?: string,
  *  dryRun?: boolean,
  *  configFile?: string,
+ *  sampleOutput?: boolean,
+ *  forceAuthorUpdate?: boolean,
+ *  useGpgSignerAuthor?: boolean,
  *  enabledDetectors?: string[],
  *  disabledDetectors?: string[],
- *  detectorSyntaxOverrides?: Record<string, { linePrefix?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string }>,
+ *  detectorSyntaxOverrides?: Record<string, { linePrefix?: string, lineSeparator?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string }>,
  *  includeFolders?: string[],
  *  excludeFolders?: string[],
  *  includeExtensions?: string[],
@@ -47,7 +63,20 @@ import { toDatePayload } from "../utils/time.mjs";
  *  filesScanned: number,
  *  filesUpdated: number,
  *  dryRun: boolean,
- *  changes: Array<{file: string, changed: boolean}>
+ *  changes: Array<{file: string, changed: boolean, sample?: { previousValue: string | null, newValue: string, detectedValues?: {
+ *   projectName: string,
+ *   language: string,
+ *   projectRoot: string,
+ *   marker: string | null,
+ *   authorName: string,
+ *   authorEmail: string,
+ *   companyName: string,
+ *   copyrightStartYear: number,
+ *   createdAtSource: string,
+ *   lastModifiedAtSource: string,
+ *   createdAt: {date: string, timestamp: number},
+ *   lastModifiedAt: {date: string, timestamp: number}
+ *  } }}>
  * }} FixHeadersResult
  */
 
@@ -83,6 +112,65 @@ async function resolveRuntimeOptions(options) {
 	return output;
 }
 
+/**
+ * Extracts original author identity from an existing header block.
+ * @param {string} headerText - Existing header content.
+ * @returns {{ authorName?: string, authorEmail?: string }} Parsed identity values.
+ */
+function extractHeaderAuthorIdentity(headerText) {
+	const authorMatch = headerText.match(/@Author:\s*(.+)$/m);
+	const emailMatch = headerText.match(/@Email:\s*<([^>\n]+)>/m);
+
+	return {
+		authorName: authorMatch?.[1]?.trim(),
+		authorEmail: emailMatch?.[1]?.trim()
+	};
+}
+
+/**
+ * Extracts original created-at payload from an existing header block.
+ * @param {string} headerText - Existing header content.
+ * @returns {{date: string, timestamp: number} | null} Parsed created-at value.
+ */
+function extractHeaderCreatedAt(headerText) {
+	const dateMatch = headerText.match(/@Date:\s*(.+?)\s*\((\d+)\)$/m);
+	if (!dateMatch || !dateMatch[1] || !dateMatch[2]) {
+		return null;
+	}
+
+	const timestamp = Number.parseInt(dateMatch[2], 10);
+	if (Number.isNaN(timestamp)) {
+		return null;
+	}
+
+	return {
+		date: dateMatch[1].trim(),
+		timestamp
+	};
+}
+
+/**
+ * Extracts original last-modified payload from an existing header block.
+ * @param {string} headerText - Existing header content.
+ * @returns {{date: string, timestamp: number} | null} Parsed last-modified value.
+ */
+function extractHeaderLastModifiedAt(headerText) {
+	const modifiedMatch = headerText.match(/@Last modified time:\s*(.+?)\s*\((\d+)\)$/m);
+	if (!modifiedMatch || !modifiedMatch[1] || !modifiedMatch[2]) {
+		return null;
+	}
+
+	const timestamp = Number.parseInt(modifiedMatch[2], 10);
+	if (Number.isNaN(timestamp)) {
+		return null;
+	}
+
+	return {
+		date: modifiedMatch[1].trim(),
+		timestamp
+	};
+}
+
 /**
  * @fileoverview Main header-fixing engine with auto-detection and override support.
  * @module fix-headers/core/fix-headers
@@ -138,6 +226,7 @@ export async function fixHeaders(options = {}) {
 	}
 
 	const currentYear = new Date().getFullYear();
+	/** @type {FixHeadersResult["changes"]} */
 	const changes = [];
 	const detectedProjects = new Set();
 	let filesUpdated = 0;
@@ -152,16 +241,33 @@ export async function fixHeaders(options = {}) {
 		detectedProjects.add(`${fileMetadata.language}:${fileMetadata.projectRoot}`);
 		const relativePath = relative(scanRoot, filePath);
 		const original = await readFile(filePath, "utf8");
+		const existingHeader = findProjectHeader(original, filePath, {
+			language: fileMetadata.language,
+			enabledDetectors: effectiveOptions.enabledDetectors,
+			disabledDetectors: effectiveOptions.disabledDetectors,
+			detectorSyntaxOverrides: effectiveOptions.detectorSyntaxOverrides
+		});
+		const existingHeaderText = existingHeader ? original.slice(existingHeader.start, existingHeader.end) : "";
+		const existingIdentity = existingHeaderText.length > 0 ? extractHeaderAuthorIdentity(existingHeaderText) : {};
+		const existingCreatedAt = existingHeaderText.length > 0 ? extractHeaderCreatedAt(existingHeaderText) : null;
+		const existingLastModifiedAt = existingHeaderText.length > 0 ? extractHeaderLastModifiedAt(existingHeaderText) : null;
 		const filesystemDates = await readFileDates(filePath);
 
 		const metadataRelativePath = relative(fileMetadata.projectRoot, filePath);
 		const gitCreated = await getGitCreationDate(fileMetadata.projectRoot, metadataRelativePath);
 		const gitLastUpdated = await getGitLastModifiedDate(fileMetadata.projectRoot, metadataRelativePath);
 
-		const createdAt = gitCreated || toDatePayload(filesystemDates.createdAt);
-		const lastModifiedAt = gitLastUpdated || toDatePayload(filesystemDates.updatedAt);
+		const createdAtSource = existingCreatedAt ? "existing-header" : gitCreated ? "git-created" : "filesystem-created";
+		const comparisonLastModifiedAtSource = existingLastModifiedAt
+			? "existing-header"
+			: gitLastUpdated
+				? "git-last-modified"
+				: "filesystem-updated";
+		const createdAt = existingCreatedAt || gitCreated || toDatePayload(filesystemDates.createdAt);
+		const comparisonLastModifiedAt = existingLastModifiedAt || gitLastUpdated || toDatePayload(filesystemDates.updatedAt);
+		const shouldForceAuthorUpdate = effectiveOptions.forceAuthorUpdate === true;
 
-		const header = buildHeader({
+		const comparisonHeader = buildHeader({
 			absoluteFilePath: filePath,
 			language: fileMetadata.language,
 			syntaxOptions: {
@@ -172,22 +278,90 @@ export async function fixHeaders(options = {}) {
 			},
 			projectRoot: fileMetadata.projectRoot,
 			projectName: fileMetadata.projectName,
+			createdByName: shouldForceAuthorUpdate ? fileMetadata.authorName : existingIdentity.authorName || fileMetadata.authorName,
+			createdByEmail: shouldForceAuthorUpdate ? fileMetadata.authorEmail : existingIdentity.authorEmail || fileMetadata.authorEmail,
+			lastModifiedByName: fileMetadata.authorName,
+			lastModifiedByEmail: fileMetadata.authorEmail,
 			authorName: fileMetadata.authorName,
 			authorEmail: fileMetadata.authorEmail,
 			createdAt,
-			lastModifiedAt,
+			lastModifiedAt: comparisonLastModifiedAt,
 			copyrightStartYear: fileMetadata.copyrightStartYear,
 			companyName: fileMetadata.companyName,
 			currentYear
 		});
 
-		const replacement = replaceOrInsertHeader(original, header, filePath, {
+		const comparisonReplacement = replaceOrInsertHeader(original, comparisonHeader, filePath, {
 			language: fileMetadata.language,
 			enabledDetectors: effectiveOptions.enabledDetectors,
 			disabledDetectors: effectiveOptions.disabledDetectors,
 			detectorSyntaxOverrides: effectiveOptions.detectorSyntaxOverrides
 		});
-		changes.push({ file: relativePath, changed: replacement.changed });
+		const needsUpdate = comparisonReplacement.changed;
+		const finalLastModifiedAt = needsUpdate ? toDatePayload(new Date()) : comparisonLastModifiedAt;
+		const lastModifiedAtSource = needsUpdate ? "current-time-on-change" : comparisonLastModifiedAtSource;
+
+		const header = needsUpdate
+			? buildHeader({
+					absoluteFilePath: filePath,
+					language: fileMetadata.language,
+					syntaxOptions: {
+						language: fileMetadata.language,
+						enabledDetectors: effectiveOptions.enabledDetectors,
+						disabledDetectors: effectiveOptions.disabledDetectors,
+						detectorSyntaxOverrides: effectiveOptions.detectorSyntaxOverrides
+					},
+					projectRoot: fileMetadata.projectRoot,
+					projectName: fileMetadata.projectName,
+					createdByName: shouldForceAuthorUpdate ? fileMetadata.authorName : existingIdentity.authorName || fileMetadata.authorName,
+					createdByEmail: shouldForceAuthorUpdate ? fileMetadata.authorEmail : existingIdentity.authorEmail || fileMetadata.authorEmail,
+					lastModifiedByName: fileMetadata.authorName,
+					lastModifiedByEmail: fileMetadata.authorEmail,
+					authorName: fileMetadata.authorName,
+					authorEmail: fileMetadata.authorEmail,
+					createdAt,
+					lastModifiedAt: finalLastModifiedAt,
+					copyrightStartYear: fileMetadata.copyrightStartYear,
+					companyName: fileMetadata.companyName,
+					currentYear
+				})
+			: comparisonHeader;
+
+		const replacement = needsUpdate
+			? replaceOrInsertHeader(original, header, filePath, {
+					language: fileMetadata.language,
+					enabledDetectors: effectiveOptions.enabledDetectors,
+					disabledDetectors: effectiveOptions.disabledDetectors,
+					detectorSyntaxOverrides: effectiveOptions.detectorSyntaxOverrides
+				})
+			: comparisonReplacement;
+		const changeEntry = {
+			file: relativePath,
+			changed: replacement.changed
+		};
+
+		if (effectiveOptions.sampleOutput === true && replacement.changed) {
+			changeEntry.sample = {
+				previousValue: existingHeaderText.length > 0 ? existingHeaderText.trimEnd() : null,
+				newValue: header,
+				detectedValues: {
+					projectName: fileMetadata.projectName,
+					language: fileMetadata.language,
+					projectRoot: fileMetadata.projectRoot,
+					marker: fileMetadata.marker,
+					authorName: fileMetadata.authorName,
+					authorEmail: fileMetadata.authorEmail,
+					companyName: fileMetadata.companyName,
+					copyrightStartYear: fileMetadata.copyrightStartYear,
+					createdAtSource,
+					lastModifiedAtSource,
+					createdAt,
+					lastModifiedAt: finalLastModifiedAt
+				}
+			};
+		}
+
+		changes.push(changeEntry);
 
 		if (!replacement.changed) {
 			continue;

package/src/detect/project.mjs

@@ -2,26 +2,13 @@
  *	@Project: @cldmv/fix-headers
  *	@Filename: /src/detect/project.mjs
  *	@Date: 2026-03-01 13:32:57 -08:00 (1772400777)
- *	@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 16:29:34 -08:00 (1772411374)
+ *	@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.
- */
-
-/**
- *	@Project: @cldmv/fix-headers
- *	@Filename: /src/detect/project.mjs
- *	@Date: 2026-03-01 13:32:57 -08:00 (1772400777)
- *	@Author: Nate Hyson <CLDMV>
- *	@Email: <Shinrai@users.noreply.github.com>
- *	-----
- *	@Last modified by: Nate Hyson <CLDMV> (Shinrai@users.noreply.github.com)
- *	@Last modified time: 2026-03-01 16:27:47 -08:00 (1772411267)
- *	-----
- *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ *	@Copyright: Copyright (c) 2026-2026 Catalyzed Motivation Inc. All rights reserved.
  */
 
 import { dirname, extname, join, resolve } from "node:path";
@@ -136,6 +123,7 @@ export async function detectProjectFromMarkers(cwd, options = {}) {
  *  language?: string,
  *  projectRoot?: string,
  *  marker?: string | null,
+ *  useGpgSignerAuthor?: boolean,
  *  authorName?: string,
  *  authorEmail?: string,
  *  companyName?: string,
@@ -159,7 +147,9 @@ export async function resolveProjectMetadata(options = {}) {
 	const detectFrom = options.targetFilePath ? dirname(cwd) : cwd;
 	const preferredExtension = options.targetFilePath ? extname(cwd).toLowerCase() : "";
 	const detected = await detectProjectFromMarkers(detectFrom, { detectors, preferredExtension });
-	const gitAuthor = await detectGitAuthor(detected.rootDir);
+	const gitAuthor = await detectGitAuthor(detected.rootDir, {
+		useGpgSignerAuthor: options.useGpgSignerAuthor === true
+	});
 	const currentYear = new Date().getFullYear();
 
 	return {

package/src/detectors/css.mjs

@@ -1,3 +1,16 @@
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /src/detectors/css.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/go.mjs

@@ -1,3 +1,16 @@
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /src/detectors/go.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/html.mjs

@@ -1,3 +1,16 @@
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /src/detectors/html.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";