@cldmv/fix-headers 1.0.0

package/src/utils/fs.mjs

@@ -0,0 +1,125 @@
+import { access, readdir, readFile, stat } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+/**
+ * @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 async function pathExists(filePath) {
+	try {
+		await access(filePath, fsConstants.F_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * 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 async function findProjectRoot(startDir, markerFiles) {
+	let currentDir = resolve(startDir);
+
+	while (true) {
+		for (const marker of markerFiles) {
+			const markerPath = join(currentDir, marker);
+			if (await pathExists(markerPath)) {
+				return { root: currentDir, marker };
+			}
+		}
+
+		const parent = dirname(currentDir);
+		if (parent === currentDir) {
+			return null;
+		}
+
+		currentDir = parent;
+	}
+}
+
+/**
+ * Reads UTF-8 file content if it exists.
+ * @param {string} filePath - File path.
+ * @returns {Promise<string | null>} File content or null when missing.
+ */
+export async function readTextIfExists(filePath) {
+	if (!(await pathExists(filePath))) {
+		return null;
+	}
+
+	return readFile(filePath, "utf8");
+}
+
+/**
+ * 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 async function walkFiles(dirPath, options) {
+	const files = [];
+	const entries = await readdir(dirPath, { withFileTypes: true });
+
+	for (const entry of entries) {
+		const fullPath = join(dirPath, entry.name);
+
+		if (entry.isDirectory() && options.ignoreFolders.has(entry.name)) {
+			continue;
+		}
+
+		if (entry.isDirectory() && options.shouldSkipDirectory?.(fullPath, entry.name) === true) {
+			continue;
+		}
+
+		if (entry.isDirectory()) {
+			const nested = await walkFiles(fullPath, options);
+			files.push(...nested);
+			continue;
+		}
+
+		if (!entry.isFile()) {
+			continue;
+		}
+
+		const extensionStart = entry.name.lastIndexOf(".");
+		if (extensionStart === -1) {
+			continue;
+		}
+
+		const extension = entry.name.slice(extensionStart).toLowerCase();
+		if (options.allowedExtensions.has(extension)) {
+			files.push(fullPath);
+		}
+	}
+
+	return files;
+}
+
+/**
+ * Gets creation-like and modified timestamps from filesystem stats.
+ * @param {string} filePath - Absolute file path.
+ * @returns {Promise<{createdAt: Date, updatedAt: Date}>} Date pair.
+ */
+export async function readFileDates(filePath) {
+	const fileStats = await stat(filePath);
+	const createdAt = fileStats.birthtimeMs > 0 ? fileStats.birthtime : fileStats.mtime;
+
+	return {
+		createdAt,
+		updatedAt: fileStats.mtime
+	};
+}

package/src/utils/git.mjs

@@ -0,0 +1,97 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * @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 async function runGit(cwd, args) {
+	try {
+		const { stdout } = await execFileAsync("git", args, { cwd });
+		const value = stdout.trim();
+		return value.length > 0 ? value : null;
+	} catch {
+		return 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 async function detectGitAuthor(cwd) {
+	let authorName = await runGit(cwd, ["config", "--get", "user.name"]);
+	let authorEmail = await runGit(cwd, ["config", "--get", "user.email"]);
+
+	if (!authorName || !authorEmail) {
+		const fallback = await runGit(cwd, ["log", "-1", "--format=%an|%ae"]);
+		if (fallback) {
+			const [fallbackName, fallbackEmail] = fallback.split("|");
+			authorName = authorName || fallbackName || null;
+			authorEmail = authorEmail || fallbackEmail || null;
+		}
+	}
+
+	return { authorName, authorEmail };
+}
+
+/**
+ * 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 async function getGitCreationDate(cwd, filePath) {
+	const output = await runGit(cwd, ["log", "--follow", "--format=%aI|%at", "--reverse", "--", filePath]);
+	if (!output) {
+		return null;
+	}
+
+	const firstLine = output.split("\n")[0];
+	const [date, timestampText] = firstLine.split("|");
+	if (!date || !timestampText) {
+		return null;
+	}
+
+	const timestamp = Number.parseInt(timestampText, 10);
+	if (Number.isNaN(timestamp)) {
+		return null;
+	}
+
+	return { date, timestamp };
+}
+
+/**
+ * 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 async function getGitLastModifiedDate(cwd, filePath) {
+	const output = await runGit(cwd, ["log", "-1", "--format=%aI|%at", "--", filePath]);
+	if (!output) {
+		return null;
+	}
+
+	const [date, timestampText] = output.split("|");
+	if (!date || !timestampText) {
+		return null;
+	}
+
+	const timestamp = Number.parseInt(timestampText, 10);
+	if (Number.isNaN(timestamp)) {
+		return null;
+	}
+
+	return { date, timestamp };
+}

package/src/utils/time.mjs

@@ -0,0 +1,31 @@
+/**
+ * @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) {
+	const pad = (value) => String(value).padStart(2, "0");
+	const tzOffset = -date.getTimezoneOffset();
+	const sign = tzOffset >= 0 ? "+" : "-";
+	const tzHours = pad(Math.floor(Math.abs(tzOffset) / 60));
+	const tzMinutes = pad(Math.abs(tzOffset) % 60);
+
+	return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())} ${sign}${tzHours}:${tzMinutes}`;
+}
+
+/**
+ * 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 = new Date()) {
+	return {
+		date: formatDateWithTimezone(date),
+		timestamp: Math.floor(date.getTime() / 1000)
+	};
+}

package/types/index.d.mts

@@ -0,0 +1,2 @@
+export * from "./src/fix-header.mjs";
+export { default } from "./src/fix-header.mjs";

package/types/src/cli.d.mts

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * Parses CLI arguments into fixHeaders options and control flags.
+ * @param {string[]} argv - Process argument vector without node/script items.
+ * @returns {{
+ *  options: Record<string, unknown>,
+ *  help: boolean,
+ *  json: boolean
+ * }} Parsed CLI payload.
+ */
+export function parseCliArgs(argv: string[]): {
+    options: Record<string, unknown>;
+    help: boolean;
+    json: boolean;
+};
+/**
+ * Loads extra options from a JSON config file.
+ * @param {Record<string, unknown>} options - Current options object.
+ * @returns {Promise<Record<string, unknown>>} Merged options object.
+ */
+export function applyConfigFile(options: Record<string, unknown>): Promise<Record<string, unknown>>;
+/**
+ * Executes CLI flow and returns process-like exit code.
+ * @param {string[]} argv - CLI arguments.
+ * @param {{
+ *  runner?: (options: Record<string, unknown>) => Promise<unknown>,
+ *  stdout?: (message: string) => void,
+ *  stderr?: (message: string) => void
+ * }} [deps={}] - Dependency overrides for tests.
+ * @returns {Promise<number>} Exit code.
+ */
+export function runCli(argv: string[], deps?: {
+    runner?: (options: Record<string, unknown>) => Promise<unknown>;
+    stdout?: (message: string) => void;
+    stderr?: (message: string) => void;
+}): Promise<number>;
+/**
+ * Executes CLI flow when the module is the process entrypoint.
+ * @param {string[]} [argv=process.argv] - Process argument vector.
+ * @param {string} [moduleUrl=import.meta.url] - Current module URL.
+ * @param {(args: string[]) => Promise<number>} [executor=runCli] - CLI executor.
+ * @returns {boolean} Whether the entrypoint branch was executed.
+ */
+export function runCliAsMain(argv?: string[], moduleUrl?: string, executor?: (args: string[]) => Promise<number>): boolean;

package/types/src/constants.d.mts

@@ -0,0 +1,7 @@
+/** @type {string} */
+export const DEFAULT_COMPANY_NAME: string;
+/** @type {number} */
+export const DEFAULT_MAX_HEADER_SCAN_LINES: number;
+/** @type {Set<string>} */
+export const DEFAULT_IGNORE_FOLDERS: Set<string>;
+export { DETECTOR_PROFILES, getAllowedExtensions, getEnabledDetectors } from "./detectors/index.mjs";

package/types/src/core/file-discovery.d.mts

@@ -0,0 +1,22 @@
+/**
+ * Discovers source files for processing.
+ * @param {{
+ *  projectRoot: string,
+ *  language?: string,
+ *  includeExtensions?: string[],
+ *  enabledDetectors?: string[],
+ *  disabledDetectors?: string[],
+ *  includeFolders?: string[],
+ *  excludeFolders?: string[]
+ * }} options - File discovery options.
+ * @returns {Promise<string[]>} Absolute file paths.
+ */
+export function discoverFiles(options: {
+    projectRoot: string;
+    language?: string;
+    includeExtensions?: string[];
+    enabledDetectors?: string[];
+    disabledDetectors?: string[];
+    includeFolders?: string[];
+    excludeFolders?: string[];
+}): Promise<string[]>;

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

@@ -0,0 +1,86 @@
+/**
+ * @fileoverview Main header-fixing engine with auto-detection and override support.
+ * @module fix-headers/core/fix-headers
+ */
+/**
+ * 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.
+ */
+export function fixHeaders(options?: {
+    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;
+}): 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;
+    }>;
+}>;

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

@@ -0,0 +1,81 @@
+/**
+ * Detects project root and language by scanning known marker files.
+ * @param {string} cwd - Starting working directory.
+ * @param {{ detectors?: { id: string, extensions: string[], priority?: number, findNearestConfig: (path: string) => Promise<{ root: string, marker: string } | null>, parseProjectName: (marker: string, content: string, rootDirName: string) => string }[], enabledDetectors?: string[], disabledDetectors?: string[], preferredExtension?: string }} [options={}] - Detection options.
+ * @returns {Promise<{
+ *  language: string,
+ *  rootDir: string,
+ *  marker: string | null,
+ *  projectName: string
+ * }>} Detection result.
+ */
+export function detectProjectFromMarkers(cwd: string, options?: {
+    detectors?: {
+        id: string;
+        extensions: string[];
+        priority?: number;
+        findNearestConfig: (path: string) => Promise<{
+            root: string;
+            marker: string;
+        } | null>;
+        parseProjectName: (marker: string, content: string, rootDirName: string) => string;
+    }[];
+    enabledDetectors?: string[];
+    disabledDetectors?: string[];
+    preferredExtension?: string;
+}): Promise<{
+    language: string;
+    rootDir: string;
+    marker: string | null;
+    projectName: string;
+}>;
+/**
+ * Resolves project metadata with override support for every auto-detected field.
+ * @param {{
+ *  cwd?: string,
+ *  targetFilePath?: string,
+ *  enabledDetectors?: string[],
+ *  disabledDetectors?: string[],
+ *  projectName?: string,
+ *  language?: string,
+ *  projectRoot?: string,
+ *  marker?: string | null,
+ *  authorName?: string,
+ *  authorEmail?: string,
+ *  companyName?: string,
+ *  copyrightStartYear?: number
+ * }} [options={}] - Detection options and overrides.
+ * @returns {Promise<{
+ *  projectName: string,
+ *  language: string,
+ *  projectRoot: string,
+ *  marker: string | null,
+ *  authorName: string,
+ *  authorEmail: string,
+ *  companyName: string,
+ *  copyrightStartYear: number
+ * }>} Final metadata.
+ */
+export function resolveProjectMetadata(options?: {
+    cwd?: string;
+    targetFilePath?: string;
+    enabledDetectors?: string[];
+    disabledDetectors?: string[];
+    projectName?: string;
+    language?: string;
+    projectRoot?: string;
+    marker?: string | null;
+    authorName?: string;
+    authorEmail?: string;
+    companyName?: string;
+    copyrightStartYear?: number;
+}): Promise<{
+    projectName: string;
+    language: string;
+    projectRoot: string;
+    marker: string | null;
+    authorName: string;
+    authorEmail: string;
+    companyName: string;
+    copyrightStartYear: number;
+}>;

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

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

package/types/src/detectors/html.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): string;
+    export function resolveCommentSyntax(filePath: any): {
+        kind: "html";
+        blockStart: string;
+        blockLinePrefix: string;
+        blockEnd: string;
+    };
+}
+/**
+ * @fileoverview HTML detector implementation.
+ * @module fix-headers/detectors/html
+ */
+declare const markers: string[];
+declare const extensions: string[];
+export {};

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

@@ -0,0 +1,66 @@
+/**
+ * Gets enabled detector profiles based on include/exclude options.
+ * @param {{ enabledDetectors?: string[], disabledDetectors?: string[] }} [options={}] - Runtime options.
+ * @returns {typeof DETECTOR_PROFILES} Enabled detector list.
+ */
+export function getEnabledDetectors(options?: {
+    enabledDetectors?: string[];
+    disabledDetectors?: string[];
+}): typeof DETECTOR_PROFILES;
+/**
+ * Gets allowed file extensions for enabled detectors.
+ * @param {{ enabledDetectors?: string[], disabledDetectors?: string[], includeExtensions?: string[] }} [options={}] - Runtime options.
+ * @returns {Set<string>} Allowed extensions.
+ */
+export function getAllowedExtensions(options?: {
+    enabledDetectors?: string[];
+    disabledDetectors?: string[];
+    includeExtensions?: string[];
+}): Set<string>;
+/**
+ * Gets a detector by id.
+ * @param {string} id - Detector id.
+ * @returns {typeof DETECTOR_PROFILES[number] | undefined} Detector.
+ */
+export function getDetectorById(id: string): (typeof DETECTOR_PROFILES)[number] | undefined;
+/**
+ * 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.
+ */
+export function getCommentSyntaxForFile(filePath: string, options?: {
+    language?: string;
+    enabledDetectors?: string[];
+    disabledDetectors?: string[];
+    detectorSyntaxOverrides?: Record<string, {
+        linePrefix?: string;
+        blockStart?: string;
+        blockLinePrefix?: string;
+        blockEnd?: string;
+    }>;
+}): {
+    kind: "block" | "line" | "html";
+    linePrefix?: string;
+    blockStart?: string;
+    blockLinePrefix?: string;
+    blockEnd?: string;
+};
+export const DETECTOR_PROFILES: {
+    id: string;
+    markers: string[];
+    extensions: string[];
+    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;
+}[];

package/types/src/detectors/node.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): string;
+    export function resolveCommentSyntax(filePath: any): {
+        kind: "block";
+        blockStart: string;
+        blockLinePrefix: string;
+        blockEnd: string;
+    };
+}
+/**
+ * @fileoverview Node.js detector implementation.
+ * @module fix-headers/detectors/node
+ */
+declare const markers: string[];
+declare const extensions: string[];
+export {};