@cldmv/fix-headers 1.0.0

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

@@ -0,0 +1,25 @@
+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): any;
+    export function resolveCommentSyntax(filePath: any): {
+        kind: "block";
+        blockStart: string;
+        blockLinePrefix: string;
+        blockEnd: string;
+    };
+}
+/**
+ * @fileoverview PHP detector implementation.
+ * @module fix-headers/detectors/php
+ */
+declare const markers: string[];
+declare const extensions: string[];
+export {};

package/types/src/detectors/python.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: string;
+        linePrefix: string;
+    };
+}
+/**
+ * @fileoverview Python detector implementation.
+ * @module fix-headers/detectors/python
+ */
+declare const markers: string[];
+declare const extensions: string[];
+export {};

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

@@ -0,0 +1,25 @@
+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): any;
+    export function resolveCommentSyntax(filePath: any): {
+        kind: "block";
+        blockStart: string;
+        blockLinePrefix: string;
+        blockEnd: string;
+    };
+}
+/**
+ * @fileoverview Rust detector implementation.
+ * @module fix-headers/detectors/rust
+ */
+declare const markers: string[];
+declare const extensions: string[];
+export {};

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

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Shared detector helpers for nearest marker search.
+ * @module fix-headers/detectors/shared
+ */
+/**
+ * Finds the closest marker file by walking up parent directories.
+ * @param {string} startPath - Starting directory or file path.
+ * @param {string[]} markers - Marker filenames to search.
+ * @returns {Promise<{root: string, marker: string} | null>} Closest located marker.
+ */
+export function findNearestMarker(startPath: string, markers: string[]): Promise<{
+    root: string;
+    marker: string;
+} | null>;

package/types/src/fix-header.d.mts

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Public module API exposing a single function for header updates.
+ * @module fix-headers
+ */
+/**
+ * Runs header fix-up using automatic metadata detection and optional overrides.
+ * @param {Parameters<typeof fixHeadersCore>[0]} [options] - Runtime options.
+ * @returns {ReturnType<typeof fixHeadersCore>} Update report.
+ */
+export function fixHeaders(options?: Parameters<typeof fixHeadersCore>[0]): ReturnType<typeof fixHeadersCore>;
+export default fixHeaders;
+import { fixHeaders as fixHeadersCore } from "./core/fix-headers.mjs";

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

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ * @returns {{start: number, end: number} | null} Header location.
+ */
+export function findProjectHeader(content: string, filePath?: string, syntaxOptions?: {
+    language?: string;
+    enabledDetectors?: string[];
+    disabledDetectors?: string[];
+    detectorSyntaxOverrides?: Record<string, {
+        linePrefix?: string;
+        blockStart?: string;
+        blockLinePrefix?: string;
+        blockEnd?: string;
+    }>;
+}): {
+    start: number;
+    end: number;
+} | null;
+/**
+ * Replaces or inserts a project header block.
+ * @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.
+ * @returns {{nextContent: string, changed: boolean}} Updated content result.
+ */
+export function replaceOrInsertHeader(content: string, newHeader: string, filePath?: string, syntaxOptions?: {
+    language?: string;
+    enabledDetectors?: string[];
+    disabledDetectors?: string[];
+    detectorSyntaxOverrides?: Record<string, {
+        linePrefix?: string;
+        blockStart?: string;
+        blockLinePrefix?: string;
+        blockEnd?: string;
+    }>;
+}): {
+    nextContent: string;
+    changed: boolean;
+};

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

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Header comment syntax helpers for mapping file extensions to comment styles.
+ * @module fix-headers/header/syntax
+ */
+/**
+ * @typedef {{
+ *  kind: "block" | "line" | "html",
+ *  linePrefix?: string,
+ *  blockStart?: string,
+ *  blockLinePrefix?: string,
+ *  blockEnd?: string
+ * }} HeaderSyntax
+ */
+/**
+ * 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.
+ * @returns {HeaderSyntax} Header syntax descriptor.
+ */
+export function getHeaderSyntaxForFile(filePath: string, options?: {
+    language?: string;
+    enabledDetectors?: string[];
+    disabledDetectors?: string[];
+    detectorSyntaxOverrides?: Record<string, {
+        linePrefix?: string;
+        blockStart?: string;
+        blockLinePrefix?: string;
+        blockEnd?: string;
+    }>;
+}): HeaderSyntax;
+/**
+ * Renders header body lines using a chosen syntax.
+ * @param {HeaderSyntax} syntax - Header syntax descriptor.
+ * @param {string[]} lines - Header lines without comment wrappers.
+ * @returns {string} Formatted header block.
+ */
+export function renderHeaderLines(syntax: HeaderSyntax, lines: string[]): string;
+export type HeaderSyntax = {
+    kind: "block" | "line" | "html";
+    linePrefix?: string;
+    blockStart?: string;
+    blockLinePrefix?: string;
+    blockEnd?: string;
+};

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

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview Header template builder used to generate normalized file headers.
+ * @module fix-headers/header/template
+ */
+/**
+ * Builds a normalized header block for a source file.
+ * @param {{
+ *  absoluteFilePath: string,
+ *  language?: string,
+ *  syntaxOptions?: { language?: string, enabledDetectors?: string[], disabledDetectors?: string[], detectorSyntaxOverrides?: Record<string, { linePrefix?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string }> },
+ *  projectRoot: string,
+ *  projectName: string,
+ *  authorName: string,
+ *  authorEmail: string,
+ *  createdAt: {date: string, timestamp: number},
+ *  lastModifiedAt: {date: string, timestamp: number},
+ *  copyrightStartYear: number,
+ *  companyName: string,
+ *  currentYear: number
+ * }} data - Header data.
+ * @returns {string} Header block text.
+ */
+export function buildHeader(data: {
+    absoluteFilePath: string;
+    language?: string;
+    syntaxOptions?: {
+        language?: string;
+        enabledDetectors?: string[];
+        disabledDetectors?: string[];
+        detectorSyntaxOverrides?: Record<string, {
+            linePrefix?: string;
+            blockStart?: string;
+            blockLinePrefix?: string;
+            blockEnd?: string;
+        }>;
+    };
+    projectRoot: string;
+    projectName: string;
+    authorName: string;
+    authorEmail: string;
+    createdAt: {
+        date: string;
+        timestamp: number;
+    };
+    lastModifiedAt: {
+        date: string;
+        timestamp: number;
+    };
+    copyrightStartYear: number;
+    companyName: string;
+    currentYear: number;
+}): string;

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

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview Filesystem helpers for project discovery and recursive scanning.
+ * @module fix-headers/utils/fs
+ */
+/**
+ * Checks whether a file exists and is readable.
+ * @param {string} filePath - Absolute or relative path.
+ * @returns {Promise<boolean>} True when the path exists.
+ */
+export function pathExists(filePath: string): Promise<boolean>;
+/**
+ * Finds a marker file by traversing upward from a directory.
+ * @param {string} startDir - Starting directory.
+ * @param {string[]} markerFiles - Candidate marker file names.
+ * @returns {Promise<{root: string, marker: string} | null>} First match with root path.
+ */
+export function findProjectRoot(startDir: string, markerFiles: string[]): Promise<{
+    root: string;
+    marker: string;
+} | null>;
+/**
+ * Reads UTF-8 file content if it exists.
+ * @param {string} filePath - File path.
+ * @returns {Promise<string | null>} File content or null when missing.
+ */
+export function readTextIfExists(filePath: string): Promise<string | null>;
+/**
+ * Recursively discovers files matching allowed extensions.
+ * @param {string} dirPath - Root directory to scan.
+ * @param {{
+ *  allowedExtensions: Set<string>,
+ *  ignoreFolders: Set<string>,
+ *  shouldSkipDirectory?: (directoryPath: string, directoryName: string) => boolean
+ * }} options - Scan options.
+ * @returns {Promise<string[]>} Matching file paths.
+ */
+export function walkFiles(dirPath: string, options: {
+    allowedExtensions: Set<string>;
+    ignoreFolders: Set<string>;
+    shouldSkipDirectory?: (directoryPath: string, directoryName: string) => boolean;
+}): Promise<string[]>;
+/**
+ * Gets creation-like and modified timestamps from filesystem stats.
+ * @param {string} filePath - Absolute file path.
+ * @returns {Promise<{createdAt: Date, updatedAt: Date}>} Date pair.
+ */
+export function readFileDates(filePath: string): Promise<{
+    createdAt: Date;
+    updatedAt: Date;
+}>;

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

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Git helpers for author identity and file history metadata.
+ * @module fix-headers/utils/git
+ */
+/**
+ * Runs a git command and returns trimmed stdout.
+ * @param {string} cwd - Working directory.
+ * @param {string[]} args - Git command arguments.
+ * @returns {Promise<string | null>} Trimmed stdout or null on failure.
+ */
+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.
+ * @returns {Promise<{authorName: string | null, authorEmail: string | null}>} Author information.
+ */
+export function detectGitAuthor(cwd: string): Promise<{
+    authorName: string | null;
+    authorEmail: string | null;
+}>;
+/**
+ * Gets a file's first commit date from git history.
+ * @param {string} cwd - Project directory.
+ * @param {string} filePath - Relative file path.
+ * @returns {Promise<{date: string, timestamp: number} | null>} Git creation date payload.
+ */
+export function getGitCreationDate(cwd: string, filePath: string): Promise<{
+    date: string;
+    timestamp: number;
+} | null>;
+/**
+ * Gets a file's latest commit date from git history.
+ * @param {string} cwd - Project directory.
+ * @param {string} filePath - Relative file path.
+ * @returns {Promise<{date: string, timestamp: number} | null>} Git last-modified payload.
+ */
+export function getGitLastModifiedDate(cwd: string, filePath: string): Promise<{
+    date: string;
+    timestamp: number;
+} | null>;

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

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Date/time helpers used for header timestamp formatting.
+ * @module fix-headers/utils/time
+ */
+/**
+ * Formats a date as `YYYY-MM-DD HH:mm:ss ±HH:MM`.
+ * @param {Date} date - Input date.
+ * @returns {string} Formatted date string.
+ */
+export function formatDateWithTimezone(date: Date): string;
+/**
+ * Returns a formatted date and unix timestamp.
+ * @param {Date} [date=new Date()] - Date value to format.
+ * @returns {{ date: string, timestamp: number }} Formatted datetime payload.
+ */
+export function toDatePayload(date?: Date): {
+    date: string;
+    timestamp: number;
+};