@cldmv/fix-headers 1.0.0 → 1.1.1

package/types/src/core/fix-headers.d.mts

@@ -4,52 +4,23 @@
  */
 /**
  * Fixes headers in a project using auto-detected metadata unless overridden.
- * @param {{
- *  cwd?: string,
- *  input?: string,
- *  dryRun?: boolean,
- *  configFile?: string,
- *  enabledDetectors?: string[],
- *  disabledDetectors?: string[],
- *  detectorSyntaxOverrides?: Record<string, { linePrefix?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string }>,
- *  includeFolders?: string[],
- *  excludeFolders?: string[],
- *  includeExtensions?: string[],
- *  projectName?: string,
- *  language?: string,
- *  projectRoot?: string,
- *  marker?: string | null,
- *  authorName?: string,
- *  authorEmail?: string,
- *  companyName?: string,
- *  copyrightStartYear?: number
- * }} [options={}] - Runtime options.
- * @returns {Promise<{
- *  metadata: {
- *   projectName: string,
- *   language: string,
- *   projectRoot: string,
- *   marker: string | null,
- *   authorName: string,
- *   authorEmail: string,
- *   companyName: string,
- *   copyrightStartYear: number
- *  },
- *  filesScanned: number,
- *  filesUpdated: number,
- *  dryRun: boolean,
- *  changes: Array<{file: string, changed: boolean}>
- * }>} Process report.
+ * @param {FixHeadersOptions} [options={}] - Runtime options.
+ * @returns {Promise<FixHeadersResult>} Process report.
  */
-export function fixHeaders(options?: {
+export function fixHeaders(options?: FixHeadersOptions): Promise<FixHeadersResult>;
+export type FixHeadersOptions = {
     cwd?: string;
     input?: string;
     dryRun?: boolean;
     configFile?: string;
+    sampleOutput?: boolean;
+    forceAuthorUpdate?: boolean;
+    useGpgSignerAuthor?: boolean;
     enabledDetectors?: string[];
     disabledDetectors?: string[];
     detectorSyntaxOverrides?: Record<string, {
         linePrefix?: string;
+        lineSeparator?: string;
         blockStart?: string;
         blockLinePrefix?: string;
         blockEnd?: string;
@@ -65,7 +36,8 @@ export function fixHeaders(options?: {
     authorEmail?: string;
     companyName?: string;
     copyrightStartYear?: number;
-}): Promise<{
+};
+export type FixHeadersResult = {
     metadata: {
         projectName: string;
         language: string;
@@ -76,11 +48,36 @@ export function fixHeaders(options?: {
         companyName: string;
         copyrightStartYear: number;
     };
+    detectedProjects: string[];
     filesScanned: number;
     filesUpdated: number;
     dryRun: 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;
+                };
+            };
+        };
     }>;
-}>;
+};

package/types/src/detect/project.d.mts

@@ -40,6 +40,7 @@ export function detectProjectFromMarkers(cwd: string, options?: {
  *  language?: string,
  *  projectRoot?: string,
  *  marker?: string | null,
+ *  useGpgSignerAuthor?: boolean,
  *  authorName?: string,
  *  authorEmail?: string,
  *  companyName?: string,
@@ -65,6 +66,7 @@ export function resolveProjectMetadata(options?: {
     language?: string;
     projectRoot?: string;
     marker?: string | null;
+    useGpgSignerAuthor?: boolean;
     authorName?: string;
     authorEmail?: string;
     companyName?: string;

package/types/src/detectors/index.d.mts

@@ -26,8 +26,8 @@ export function getDetectorById(id: string): (typeof DETECTOR_PROFILES)[number]
 /**
  * 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: string, options?: {
     language?: string;
@@ -35,6 +35,7 @@ export function getCommentSyntaxForFile(filePath: string, options?: {
     disabledDetectors?: string[];
     detectorSyntaxOverrides?: Record<string, {
         linePrefix?: string;
+        lineSeparator?: string;
         blockStart?: string;
         blockLinePrefix?: string;
         blockEnd?: string;
@@ -42,11 +43,25 @@ export function getCommentSyntaxForFile(filePath: string, options?: {
 }): {
     kind: "block" | "line" | "html";
     linePrefix?: string;
+    lineSeparator?: string;
     blockStart?: string;
     blockLinePrefix?: string;
     blockEnd?: string;
 };
-export const DETECTOR_PROFILES: {
+/**
+ * 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: string, content: string, options?: {
+    language?: string;
+    enabledDetectors?: string[];
+    disabledDetectors?: string[];
+}): string;
+export const DETECTOR_PROFILES: DetectorProfile[];
+export type DetectorProfile = {
     id: string;
     markers: string[];
     extensions: string[];
@@ -56,11 +71,14 @@ export const DETECTOR_PROFILES: {
         marker: string;
     } | null>;
     parseProjectName: (marker: string, markerContent: string, rootDirName: string) => string;
-    resolveCommentSyntax: (filePath: string) => {
+    resolveCommentSyntax: (filePath: string) => ({
         kind: "block" | "line" | "html";
         linePrefix?: string;
+        lineSeparator?: string;
         blockStart?: string;
         blockLinePrefix?: string;
         blockEnd?: string;
-    } | null;
-}[];
+    } | null);
+    resolvePreservedPrefix?: (filePath: string, content: string) => string;
+    priority?: number;
+};

package/types/src/detectors/node.d.mts

@@ -9,6 +9,7 @@ export namespace detector {
         marker: string;
     }>;
     export function parseProjectName(_marker: any, markerContent: any, rootDirName: any): string;
+    export function resolvePreservedPrefix(filePath: any, content: any): string;
     export function resolveCommentSyntax(filePath: any): {
         kind: "block";
         blockStart: string;

package/types/src/detectors/python.d.mts

@@ -9,6 +9,7 @@ export namespace detector {
         marker: string;
     }>;
     export function parseProjectName(_marker: any, markerContent: any, rootDirName: any): string;
+    export function resolvePreservedPrefix(filePath: any, content: any): string;
     export function resolveCommentSyntax(filePath: any): {
         kind: string;
         linePrefix: string;

package/types/src/detectors/yaml.d.mts

@@ -0,0 +1,23 @@
+export namespace detector {
+    export let id: string;
+    export let priority: number;
+    export { markers };
+    export { extensions };
+    export let enabledByDefault: boolean;
+    export function findNearestConfig(startPath: any): Promise<{
+        root: string;
+        marker: string;
+    }>;
+    export function parseProjectName(marker: any, markerContent: any, rootDirName: any): string;
+    export function resolveCommentSyntax(filePath: any): {
+        kind: "line";
+        linePrefix: string;
+    };
+}
+/**
+ * @fileoverview YAML detector implementation.
+ * @module fix-headers/detectors/yaml
+ */
+declare const markers: string[];
+declare const extensions: string[];
+export {};

package/types/src/header/parser.d.mts

@@ -2,7 +2,7 @@
  * 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, 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 {{start: number, end: number} | null} Header location.
  */
 export function findProjectHeader(content: string, filePath?: string, syntaxOptions?: {
@@ -11,6 +11,7 @@ export function findProjectHeader(content: string, filePath?: string, syntaxOpti
     disabledDetectors?: string[];
     detectorSyntaxOverrides?: Record<string, {
         linePrefix?: string;
+        lineSeparator?: string;
         blockStart?: string;
         blockLinePrefix?: string;
         blockEnd?: string;
@@ -24,7 +25,7 @@ export function findProjectHeader(content: string, filePath?: string, syntaxOpti
  * @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: string, newHeader: string, filePath?: string, syntaxOptions?: {
@@ -33,6 +34,7 @@ export function replaceOrInsertHeader(content: string, newHeader: string, filePa
     disabledDetectors?: string[];
     detectorSyntaxOverrides?: Record<string, {
         linePrefix?: string;
+        lineSeparator?: string;
         blockStart?: string;
         blockLinePrefix?: string;
         blockEnd?: string;

package/types/src/header/syntax.d.mts

@@ -6,6 +6,7 @@
  * @typedef {{
  *  kind: "block" | "line" | "html",
  *  linePrefix?: string,
+ *  lineSeparator?: string,
  *  blockStart?: string,
  *  blockLinePrefix?: string,
  *  blockEnd?: string
@@ -14,7 +15,7 @@
 /**
  * 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: string, options?: {
@@ -23,6 +24,7 @@ export function getHeaderSyntaxForFile(filePath: string, options?: {
     disabledDetectors?: string[];
     detectorSyntaxOverrides?: Record<string, {
         linePrefix?: string;
+        lineSeparator?: string;
         blockStart?: string;
         blockLinePrefix?: string;
         blockEnd?: string;
@@ -38,6 +40,7 @@ export function renderHeaderLines(syntax: HeaderSyntax, lines: string[]): string
 export type HeaderSyntax = {
     kind: "block" | "line" | "html";
     linePrefix?: string;
+    lineSeparator?: string;
     blockStart?: string;
     blockLinePrefix?: string;
     blockEnd?: string;

package/types/src/header/template.d.mts

@@ -7,8 +7,12 @@
  * @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,
@@ -29,12 +33,17 @@ export function buildHeader(data: {
         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;

package/types/src/utils/git.d.mts

@@ -12,9 +12,12 @@ export function runGit(cwd: string, args: string[]): Promise<string | null>;
 /**
  * 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 function detectGitAuthor(cwd: string): Promise<{
+export function detectGitAuthor(cwd: string, options?: {
+    useGpgSignerAuthor?: boolean;
+}): Promise<{
     authorName: string | null;
     authorEmail: string | null;
 }>;

package/types/src/utils/time.d.mts

@@ -1,3 +1,15 @@
+/**
+ *	@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