@cldmv/fix-headers 1.0.0

package/src/detectors/index.mjs

@@ -0,0 +1,160 @@
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /src/detectors/index.mjs
+ *	@Date: 2026-03-01 16:34:41 -08:00 (1772411681)
+ *	@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 17:57:59 -08:00 (1772416679)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
+
+import { readdir } from "node:fs/promises";
+import { extname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { dirname, join } from "node:path";
+
+/**
+ * @fileoverview Detector registry and shared selector helpers.
+ * @module fix-headers/detectors
+ */
+
+/**
+ * @typedef {{
+ *  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),
+ *  priority?: number
+ * }} DetectorProfile
+ */
+
+/**
+ * Loads detector modules from the current directory.
+ * @returns {Promise<DetectorProfile[]>} Loaded detectors.
+ */
+async function loadDetectorsFromDirectory() {
+	const directoryPath = dirname(fileURLToPath(import.meta.url));
+	const files = await readdir(directoryPath);
+	const detectorFiles = files
+		.filter((fileName) => fileName.endsWith(".mjs"))
+		.filter((fileName) => fileName !== "index.mjs" && fileName !== "shared.mjs")
+		.sort((left, right) => left.localeCompare(right));
+
+	const modules = await Promise.all(
+		detectorFiles.map((fileName) => {
+			const fileUrl = pathToFileURL(join(directoryPath, fileName)).href;
+			return import(fileUrl);
+		})
+	);
+
+	return modules.map((moduleExports) => moduleExports.detector).filter((entry) => entry && typeof entry.id === "string");
+}
+
+export const DETECTOR_PROFILES = await loadDetectorsFromDirectory();
+
+/** @type {Map<string, typeof DETECTOR_PROFILES[number]>} */
+const detectorMap = new Map(DETECTOR_PROFILES.map((detector) => [detector.id, detector]));
+
+/**
+ * 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.
+ */
+function applySyntaxOverride(syntax, override) {
+	if (!override || typeof override !== "object") {
+		return syntax;
+	}
+
+	if (syntax.kind === "line") {
+		return {
+			...syntax,
+			linePrefix: typeof override.linePrefix === "string" && override.linePrefix.length > 0 ? override.linePrefix : syntax.linePrefix
+		};
+	}
+
+	return {
+		...syntax,
+		blockStart: typeof override.blockStart === "string" && override.blockStart.length > 0 ? override.blockStart : syntax.blockStart,
+		blockLinePrefix:
+			typeof override.blockLinePrefix === "string" && override.blockLinePrefix.length > 0
+				? override.blockLinePrefix
+				: syntax.blockLinePrefix,
+		blockEnd: typeof override.blockEnd === "string" && override.blockEnd.length > 0 ? override.blockEnd : syntax.blockEnd
+	};
+}
+
+/**
+ * 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 = {}) {
+	const explicitEnabled = new Set(Array.isArray(options.enabledDetectors) ? options.enabledDetectors : []);
+	const explicitDisabled = new Set(Array.isArray(options.disabledDetectors) ? options.disabledDetectors : []);
+
+	return DETECTOR_PROFILES.filter((detector) => {
+		if (explicitEnabled.size > 0) {
+			return explicitEnabled.has(detector.id);
+		}
+
+		if (explicitDisabled.has(detector.id)) {
+			return false;
+		}
+
+		return detector.enabledByDefault;
+	});
+}
+
+/**
+ * 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 = {}) {
+	if (Array.isArray(options.includeExtensions) && options.includeExtensions.length > 0) {
+		return new Set(options.includeExtensions.map((extension) => extension.toLowerCase()));
+	}
+
+	const detectors = getEnabledDetectors(options);
+	return new Set(detectors.flatMap((detector) => detector.extensions));
+}
+
+/**
+ * Gets a detector by id.
+ * @param {string} id - Detector id.
+ * @returns {typeof DETECTOR_PROFILES[number] | undefined} Detector.
+ */
+export function getDetectorById(id) {
+	return detectorMap.get(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.
+ */
+export function getCommentSyntaxForFile(filePath, options = {}) {
+	const extension = extname(filePath).toLowerCase();
+	const detectors = getEnabledDetectors(options);
+	for (const detector of detectors) {
+		if (!detector.extensions.includes(extension)) {
+			continue;
+		}
+		const resolved = detector.resolveCommentSyntax(filePath);
+		if (resolved) {
+			const overrides =
+				options.detectorSyntaxOverrides && typeof options.detectorSyntaxOverrides === "object" ? options.detectorSyntaxOverrides : {};
+			return applySyntaxOverride(resolved, overrides[detector.id]);
+		}
+	}
+
+	return { kind: "block", blockStart: "/**", blockLinePrefix: " *\t", blockEnd: " */" };
+}

package/src/detectors/node.mjs

@@ -0,0 +1,63 @@
+import { extname } from "node:path";
+import { findNearestMarker } from "./shared.mjs";
+
+/**
+ * @fileoverview Node.js detector implementation.
+ * @module fix-headers/detectors/node
+ */
+
+const markers = ["package.json"];
+const extensions = [".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx", ".jsonv", ".jsonc", ".json5"];
+
+/**
+ * Parses Node project name from package marker content.
+ * @param {string} markerContent - Marker file content.
+ * @param {string} rootDirName - Fallback root directory name.
+ * @returns {string} Project name.
+ */
+function parseNodeProjectName(markerContent, 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 Node-handled file extensions.
+ * @param {string} filePath - File path.
+ * @returns {{kind: "block", blockStart: string, blockLinePrefix: string, blockEnd: string} | null} Syntax descriptor.
+ */
+function resolveNodeCommentSyntax(filePath) {
+	const extension = extname(filePath).toLowerCase();
+	if (extensions.includes(extension)) {
+		return {
+			kind: "block",
+			blockStart: "/**",
+			blockLinePrefix: " *\t",
+			blockEnd: " */"
+		};
+	}
+	return null;
+}
+
+export const detector = {
+	id: "node",
+	priority: 100,
+	markers,
+	extensions,
+	enabledByDefault: true,
+	findNearestConfig(startPath) {
+		return findNearestMarker(startPath, markers);
+	},
+	parseProjectName(_marker, markerContent, rootDirName) {
+		return parseNodeProjectName(markerContent, rootDirName);
+	},
+	resolveCommentSyntax(filePath) {
+		return resolveNodeCommentSyntax(filePath);
+	}
+};

package/src/detectors/php.mjs

@@ -0,0 +1,53 @@
+import { extname } from "node:path";
+import { findNearestMarker } from "./shared.mjs";
+
+/**
+ * @fileoverview PHP detector implementation.
+ * @module fix-headers/detectors/php
+ */
+
+const markers = ["composer.json"];
+const extensions = [".php"];
+
+/**
+ * Resolves PHP comment syntax.
+ * @param {string} filePath - File path.
+ * @returns {{kind: "block", blockStart: string, blockLinePrefix: string, blockEnd: string} | null} Syntax descriptor.
+ */
+function resolvePhpCommentSyntax(filePath) {
+	const extension = extname(filePath).toLowerCase();
+	if (extensions.includes(extension)) {
+		return {
+			kind: "block",
+			blockStart: "/**",
+			blockLinePrefix: " *\t",
+			blockEnd: " */"
+		};
+	}
+	return null;
+}
+
+export const detector = {
+	id: "php",
+	priority: 80,
+	markers,
+	extensions,
+	enabledByDefault: true,
+	findNearestConfig(startPath) {
+		return findNearestMarker(startPath, markers);
+	},
+	parseProjectName(_marker, markerContent, 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;
+		}
+	},
+	resolveCommentSyntax(filePath) {
+		return resolvePhpCommentSyntax(filePath);
+	}
+};

package/src/detectors/python.mjs

@@ -0,0 +1,48 @@
+import { extname } from "node:path";
+import { findNearestMarker } from "./shared.mjs";
+
+/**
+ * @fileoverview Python detector implementation.
+ * @module fix-headers/detectors/python
+ */
+
+const markers = ["pyproject.toml", "setup.py", "requirements.txt"];
+const extensions = [".py"];
+
+/**
+ * Parses Python project name from pyproject marker content when possible.
+ * @param {string} markerContent - Marker content.
+ * @param {string} rootDirName - Fallback root directory name.
+ * @returns {string} Project name.
+ */
+function parsePythonProjectName(markerContent, rootDirName) {
+	const pyprojectMatch = markerContent.match(/^name\s*=\s*["']([^"']+)["']/m);
+	if (pyprojectMatch?.[1]) {
+		return pyprojectMatch[1];
+	}
+	return rootDirName;
+}
+
+export const detector = {
+	id: "python",
+	priority: 80,
+	markers,
+	extensions,
+	enabledByDefault: true,
+	findNearestConfig(startPath) {
+		return findNearestMarker(startPath, markers);
+	},
+	parseProjectName(_marker, markerContent, rootDirName) {
+		return parsePythonProjectName(markerContent, rootDirName);
+	},
+	resolveCommentSyntax(filePath) {
+		const extension = extname(filePath).toLowerCase();
+		if (extensions.includes(extension)) {
+			return {
+				kind: "line",
+				linePrefix: "#"
+			};
+		}
+		return null;
+	}
+};

package/src/detectors/rust.mjs

@@ -0,0 +1,49 @@
+import { extname } from "node:path";
+import { findNearestMarker } from "./shared.mjs";
+
+/**
+ * @fileoverview Rust detector implementation.
+ * @module fix-headers/detectors/rust
+ */
+
+const markers = ["Cargo.toml"];
+const extensions = [".rs"];
+
+/**
+ * Resolves Rust comment syntax.
+ * @param {string} filePath - File path.
+ * @returns {{kind: "block", blockStart: string, blockLinePrefix: string, blockEnd: string} | null} Syntax descriptor.
+ */
+function resolveRustCommentSyntax(filePath) {
+	const extension = extname(filePath).toLowerCase();
+	if (extensions.includes(extension)) {
+		return {
+			kind: "block",
+			blockStart: "/**",
+			blockLinePrefix: " *\t",
+			blockEnd: " */"
+		};
+	}
+	return null;
+}
+
+export const detector = {
+	id: "rust",
+	priority: 80,
+	markers,
+	extensions,
+	enabledByDefault: true,
+	findNearestConfig(startPath) {
+		return findNearestMarker(startPath, markers);
+	},
+	parseProjectName(_marker, markerContent, rootDirName) {
+		const cargoNameMatch = markerContent.match(/^name\s*=\s*["']([^"']+)["']/m);
+		if (cargoNameMatch?.[1]) {
+			return cargoNameMatch[1];
+		}
+		return rootDirName;
+	},
+	resolveCommentSyntax(filePath) {
+		return resolveRustCommentSyntax(filePath);
+	}
+};

package/src/detectors/shared.mjs

@@ -0,0 +1,32 @@
+import { dirname, join, resolve } from "node:path";
+import { pathExists } from "../utils/fs.mjs";
+
+/**
+ * @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 async function findNearestMarker(startPath, markers) {
+	let currentDir = resolve(startPath);
+
+	while (true) {
+		for (const marker of markers) {
+			const markerPath = join(currentDir, marker);
+			if (await pathExists(markerPath)) {
+				return { root: currentDir, marker };
+			}
+		}
+
+		const parent = dirname(currentDir);
+		if (parent === currentDir) {
+			return null;
+		}
+		currentDir = parent;
+	}
+}

package/src/fix-header.mjs

@@ -0,0 +1,30 @@
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /src/fix-header.mjs
+ *	@Date: 2026-03-01 13:34:00 -08:00 (1772400840)
+ *	@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 14:39:14 -08:00 (1772404754)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
+
+import { fixHeaders as fixHeadersCore } from "./core/fix-headers.mjs";
+
+/**
+ * @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) {
+	return fixHeadersCore(options);
+}
+
+export default fixHeaders;

package/src/header/parser.mjs

@@ -0,0 +1,76 @@
+import { DEFAULT_MAX_HEADER_SCAN_LINES } from "../constants.mjs";
+import { getHeaderSyntaxForFile } from "./syntax.mjs";
+
+/**
+ * @fileoverview Header parser utilities for extracting and replacing top-of-file headers.
+ * @module fix-headers/header/parser
+ */
+
+/**
+ * Escapes special regex characters in literal text.
+ * @param {string} text - Literal text.
+ * @returns {string} Regex-safe text.
+ */
+function escapeRegex(text) {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * 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, filePath = "", syntaxOptions = {}) {
+	const scanLines = content.split("\n").slice(0, DEFAULT_MAX_HEADER_SCAN_LINES).join("\n");
+	const syntax = getHeaderSyntaxForFile(filePath, syntaxOptions);
+
+	let match = null;
+	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") {
+		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*`));
+	}
+
+	if (!match) {
+		return null;
+	}
+
+	if (!match[0].includes("@Project:")) {
+		return null;
+	}
+
+	return {
+		start: 0,
+		end: match[0].length
+	};
+}
+
+/**
+ * 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, newHeader, filePath = "", syntaxOptions = {}) {
+	const existing = findProjectHeader(content, filePath, syntaxOptions);
+	if (!existing) {
+		const nextContent = `${newHeader}\n\n${content.replace(/^\n+/, "")}`;
+		return { nextContent, changed: nextContent !== content };
+	}
+
+	const before = content.slice(0, existing.start);
+	const after = content.slice(existing.end).replace(/^\n+/, "");
+	const nextContent = `${before}${newHeader}\n\n${after}`;
+	return { nextContent, changed: nextContent !== content };
+}

package/src/header/syntax.mjs

@@ -0,0 +1,54 @@
+import { extname } from "node:path";
+import { getCommentSyntaxForFile } from "../detectors/index.mjs";
+
+/**
+ * @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, options = {}) {
+	const extension = extname(filePath).toLowerCase();
+	if (extension.length === 0) {
+		return { kind: "block", blockStart: "/**", blockLinePrefix: " *\t", blockEnd: " */" };
+	}
+
+	return getCommentSyntaxForFile(filePath, options);
+}
+
+/**
+ * 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, lines) {
+	if (syntax.kind === "line") {
+		return lines.map((line) => `${syntax.linePrefix || "#"}\t${line}`).join("\n");
+	}
+
+	const blockStart = syntax.blockStart || (syntax.kind === "html" ? "<!--" : "/**");
+	const blockLinePrefix = syntax.blockLinePrefix || (syntax.kind === "html" ? "\t" : " *\t");
+	const blockEnd = syntax.blockEnd || (syntax.kind === "html" ? "-->" : " */");
+
+	if (syntax.kind === "html") {
+		return `${blockStart}\n${lines.map((line) => `${blockLinePrefix}${line}`).join("\n")}\n${blockEnd}`;
+	}
+
+	return `${blockStart}\n${lines.map((line) => `${blockLinePrefix}${line}`).join("\n")}\n${blockEnd}`;
+}

package/src/header/template.mjs

@@ -0,0 +1,44 @@
+import { relative } from "node:path";
+import { getHeaderSyntaxForFile, renderHeaderLines } from "./syntax.mjs";
+
+/**
+ * @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) {
+	const relativePath = `/${relative(data.projectRoot, data.absoluteFilePath).replace(/\\/g, "/")}`;
+	const syntax = getHeaderSyntaxForFile(data.absoluteFilePath, data.syntaxOptions || { language: data.language });
+	const headerLines = [
+		`@Project: ${data.projectName}`,
+		`@Filename: ${relativePath}`,
+		`@Date: ${data.createdAt.date} (${data.createdAt.timestamp})`,
+		`@Author: ${data.authorName}`,
+		`@Email: <${data.authorEmail}>`,
+		"-----",
+		`@Last modified by: ${data.authorName} (${data.authorEmail})`,
+		`@Last modified time: ${data.lastModifiedAt.date} (${data.lastModifiedAt.timestamp})`,
+		"-----",
+		`@Copyright: Copyright (c) ${data.copyrightStartYear}-${data.currentYear} ${data.companyName}. All rights reserved.`
+	];
+
+	return renderHeaderLines(syntax, headerLines);
+}