@cldmv/fix-headers 1.0.0

package/src/core/fix-headers.mjs

@@ -0,0 +1,210 @@
+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 { readFileDates } from "../utils/fs.mjs";
+import { getGitCreationDate, getGitLastModifiedDate } from "../utils/git.mjs";
+import { toDatePayload } from "../utils/time.mjs";
+
+/**
+ * @typedef {{
+ *  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
+ * }} FixHeadersOptions
+ */
+
+/**
+ * @typedef {{
+ *  metadata: {
+ *   projectName: string,
+ *   language: string,
+ *   projectRoot: string,
+ *   marker: string | null,
+ *   authorName: string,
+ *   authorEmail: string,
+ *   companyName: string,
+ *   copyrightStartYear: number
+ *  },
+ *  detectedProjects: string[],
+ *  filesScanned: number,
+ *  filesUpdated: number,
+ *  dryRun: boolean,
+ *  changes: Array<{file: string, changed: boolean}>
+ * }} FixHeadersResult
+ */
+
+/**
+ * Resolves runtime options including optional JSON config file loading.
+ * @param {FixHeadersOptions} options - Runtime options.
+ * @returns {Promise<FixHeadersOptions>} Effective runtime options.
+ */
+async function resolveRuntimeOptions(options) {
+	const configFile = typeof options.configFile === "string" && options.configFile.trim().length > 0 ? options.configFile.trim() : null;
+
+	if (!configFile) {
+		return options;
+	}
+
+	const baseCwd = typeof options.cwd === "string" && options.cwd.length > 0 ? options.cwd : process.cwd();
+	const absoluteConfigPath = resolve(baseCwd, configFile);
+	const raw = await readFile(absoluteConfigPath, "utf8");
+	const parsed = JSON.parse(raw);
+
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error(`Config file must contain a JSON object: ${configFile}`);
+	}
+
+	const merged = {
+		...parsed,
+		...options
+	};
+
+	delete merged.configFile;
+	/** @type {FixHeadersOptions} */
+	const output = merged;
+	return output;
+}
+
+/**
+ * @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 {FixHeadersOptions} [options={}] - Runtime options.
+ * @returns {Promise<FixHeadersResult>} Process report.
+ */
+export async function fixHeaders(options = {}) {
+	const effectiveOptions = await resolveRuntimeOptions(options);
+	const scanRoot = resolve(effectiveOptions.projectRoot || effectiveOptions.cwd || process.cwd());
+	const metadata = await resolveProjectMetadata({
+		...effectiveOptions,
+		cwd: scanRoot
+	});
+	const dryRun = effectiveOptions.dryRun === true;
+
+	let files = [];
+	if (typeof effectiveOptions.input === "string" && effectiveOptions.input.trim().length > 0) {
+		const inputPath = resolve(scanRoot, effectiveOptions.input);
+		const targetStats = await stat(inputPath).catch(() => null);
+		if (!targetStats) {
+			throw new Error(`Input path does not exist: ${effectiveOptions.input}`);
+		}
+
+		if (targetStats.isFile()) {
+			files = [inputPath];
+		} else if (targetStats.isDirectory()) {
+			files = await discoverFiles({
+				projectRoot: inputPath,
+				language: metadata.language,
+				enabledDetectors: effectiveOptions.enabledDetectors,
+				disabledDetectors: effectiveOptions.disabledDetectors,
+				includeFolders: effectiveOptions.includeFolders,
+				excludeFolders: effectiveOptions.excludeFolders,
+				includeExtensions: effectiveOptions.includeExtensions
+			});
+		} else {
+			throw new Error(`Input path must be a file or directory: ${effectiveOptions.input}`);
+		}
+	} else {
+		files = await discoverFiles({
+			projectRoot: scanRoot,
+			language: metadata.language,
+			enabledDetectors: effectiveOptions.enabledDetectors,
+			disabledDetectors: effectiveOptions.disabledDetectors,
+			includeFolders: effectiveOptions.includeFolders,
+			excludeFolders: effectiveOptions.excludeFolders,
+			includeExtensions: effectiveOptions.includeExtensions
+		});
+	}
+
+	const currentYear = new Date().getFullYear();
+	const changes = [];
+	const detectedProjects = new Set();
+	let filesUpdated = 0;
+
+	for (const filePath of files) {
+		const fileMetadata = await resolveProjectMetadata({
+			...effectiveOptions,
+			cwd: scanRoot,
+			targetFilePath: filePath
+		});
+
+		detectedProjects.add(`${fileMetadata.language}:${fileMetadata.projectRoot}`);
+		const relativePath = relative(scanRoot, filePath);
+		const original = await readFile(filePath, "utf8");
+		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 header = 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,
+			authorName: fileMetadata.authorName,
+			authorEmail: fileMetadata.authorEmail,
+			createdAt,
+			lastModifiedAt,
+			copyrightStartYear: fileMetadata.copyrightStartYear,
+			companyName: fileMetadata.companyName,
+			currentYear
+		});
+
+		const replacement = replaceOrInsertHeader(original, header, filePath, {
+			language: fileMetadata.language,
+			enabledDetectors: effectiveOptions.enabledDetectors,
+			disabledDetectors: effectiveOptions.disabledDetectors,
+			detectorSyntaxOverrides: effectiveOptions.detectorSyntaxOverrides
+		});
+		changes.push({ file: relativePath, changed: replacement.changed });
+
+		if (!replacement.changed) {
+			continue;
+		}
+
+		filesUpdated += 1;
+		if (!dryRun) {
+			await writeFile(filePath, replacement.nextContent, "utf8");
+		}
+	}
+
+	return {
+		metadata,
+		detectedProjects: Array.from(detectedProjects),
+		filesScanned: files.length,
+		filesUpdated,
+		dryRun,
+		changes
+	};
+}

package/src/detect/project.mjs

@@ -0,0 +1,175 @@
+/**
+ *	@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:29:34 -08:00 (1772411374)
+ *	-----
+ *	@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.
+ */
+
+import { dirname, extname, join, resolve } from "node:path";
+import { DEFAULT_COMPANY_NAME } from "../constants.mjs";
+import { getEnabledDetectors } from "../detectors/index.mjs";
+import { readTextIfExists } from "../utils/fs.mjs";
+import { detectGitAuthor } from "../utils/git.mjs";
+
+/**
+ * @fileoverview Auto-detects project metadata from known language markers and git config.
+ * @module fix-headers/detect/project
+ */
+
+async function findClosestDetectorMatch(startPath, detectors, preferredExtension = "") {
+	const extension = typeof preferredExtension === "string" ? preferredExtension.trim().toLowerCase() : "";
+	const extensionMatched =
+		extension.length > 0
+			? detectors.filter((detector) => Array.isArray(detector.extensions) && detector.extensions.includes(extension))
+			: [];
+	const detectorsToSearch = extensionMatched.length > 0 ? extensionMatched : detectors;
+
+	const matches = await Promise.all(
+		detectorsToSearch.map(async (detector) => {
+			if (typeof detector.findNearestConfig !== "function") {
+				return null;
+			}
+
+			const located = await detector.findNearestConfig(startPath);
+			if (!located) {
+				return null;
+			}
+
+			return {
+				detector,
+				root: located.root,
+				marker: located.marker
+			};
+		})
+	);
+
+	const validMatches = matches.filter((item) => item !== null);
+	if (validMatches.length === 0) {
+		return null;
+	}
+
+	let closest = validMatches[0];
+	for (const candidate of validMatches.slice(1)) {
+		if (candidate.root.length > closest.root.length) {
+			closest = candidate;
+			continue;
+		}
+
+		if (candidate.root.length === closest.root.length) {
+			const candidatePriority = Number.isFinite(candidate.detector.priority) ? candidate.detector.priority : 0;
+			const closestPriority = Number.isFinite(closest.detector.priority) ? closest.detector.priority : 0;
+			if (candidatePriority > closestPriority) {
+				closest = candidate;
+			}
+		}
+	}
+
+	return closest;
+}
+
+/**
+ * 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 async function detectProjectFromMarkers(cwd, options = {}) {
+	const detectors = Array.isArray(options.detectors) ? options.detectors : getEnabledDetectors(options);
+	const located = await findClosestDetectorMatch(cwd, detectors, options.preferredExtension);
+
+	if (located) {
+		const markerPath = join(located.root, located.marker);
+		const markerContent = (await readTextIfExists(markerPath)) || "";
+		const rootDirName = located.root.split("/").filter(Boolean).at(-1) || "project";
+		const projectName = located.detector.parseProjectName(located.marker, markerContent, rootDirName);
+
+		return {
+			language: located.detector.id,
+			rootDir: located.root,
+			marker: located.marker,
+			projectName
+		};
+	}
+
+	const fallbackRoot = resolve(cwd);
+	const fallbackName = fallbackRoot.split("/").filter(Boolean).at(-1) || "project";
+	return {
+		language: "unknown",
+		rootDir: fallbackRoot,
+		marker: null,
+		projectName: fallbackName
+	};
+}
+
+/**
+ * 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 async function resolveProjectMetadata(options = {}) {
+	const basePath = options.targetFilePath || options.cwd || process.cwd();
+	const cwd = resolve(basePath);
+	const detectors = getEnabledDetectors(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 currentYear = new Date().getFullYear();
+
+	return {
+		projectName: options.projectName || detected.projectName,
+		language: options.language || detected.language,
+		projectRoot: options.projectRoot || detected.rootDir,
+		marker: options.marker === undefined ? detected.marker : options.marker,
+		authorName: options.authorName || gitAuthor.authorName || "Unknown Author",
+		authorEmail: options.authorEmail || gitAuthor.authorEmail || "unknown@example.com",
+		companyName: options.companyName || DEFAULT_COMPANY_NAME,
+		copyrightStartYear: Number.isInteger(options.copyrightStartYear) ? Number(options.copyrightStartYear) : currentYear
+	};
+}

package/src/detectors/css.mjs

@@ -0,0 +1,54 @@
+import { extname } from "node:path";
+import { findNearestMarker } from "./shared.mjs";
+
+/**
+ * @fileoverview CSS detector implementation.
+ * @module fix-headers/detectors/css
+ */
+
+const markers = ["package.json", "postcss.config.js", "postcss.config.cjs", "postcss.config.mjs"];
+const extensions = [".css"];
+
+/**
+ * Parses CSS project name from marker context.
+ * @param {string} rootDirName - Fallback directory name.
+ * @returns {string} Project name.
+ */
+function parseCssProjectName(rootDirName) {
+	return rootDirName;
+}
+
+/**
+ * Resolves block comment syntax for CSS files.
+ * @param {string} filePath - File path.
+ * @returns {{kind: "block", blockStart: string, blockLinePrefix: string, blockEnd: string} | null} Syntax descriptor.
+ */
+function resolveCssCommentSyntax(filePath) {
+	const extension = extname(filePath).toLowerCase();
+	if (extensions.includes(extension)) {
+		return {
+			kind: "block",
+			blockStart: "/*",
+			blockLinePrefix: " *\t",
+			blockEnd: " */"
+		};
+	}
+	return null;
+}
+
+export const detector = {
+	id: "css",
+	priority: 70,
+	markers,
+	extensions,
+	enabledByDefault: true,
+	findNearestConfig(startPath) {
+		return findNearestMarker(startPath, markers);
+	},
+	parseProjectName(_marker, _markerContent, rootDirName) {
+		return parseCssProjectName(rootDirName);
+	},
+	resolveCommentSyntax(filePath) {
+		return resolveCssCommentSyntax(filePath);
+	}
+};

package/src/detectors/go.mjs

@@ -0,0 +1,52 @@
+import { extname } from "node:path";
+import { findNearestMarker } from "./shared.mjs";
+
+/**
+ * @fileoverview Go detector implementation.
+ * @module fix-headers/detectors/go
+ */
+
+const markers = ["go.mod"];
+const extensions = [".go"];
+
+/**
+ * Resolves Go comment syntax.
+ * @param {string} filePath - File path.
+ * @returns {{kind: "block", blockStart: string, blockLinePrefix: string, blockEnd: string} | null} Syntax descriptor.
+ */
+function resolveGoCommentSyntax(filePath) {
+	const extension = extname(filePath).toLowerCase();
+	if (extensions.includes(extension)) {
+		return {
+			kind: "block",
+			blockStart: "/**",
+			blockLinePrefix: " *\t",
+			blockEnd: " */"
+		};
+	}
+	return null;
+}
+
+export const detector = {
+	id: "go",
+	priority: 80,
+	markers,
+	extensions,
+	enabledByDefault: true,
+	findNearestConfig(startPath) {
+		return findNearestMarker(startPath, markers);
+	},
+	parseProjectName(_marker, markerContent, rootDirName) {
+		const moduleMatch = markerContent.match(/^module\s+(.+)$/m);
+		if (moduleMatch?.[1]) {
+			const value = moduleMatch[1].trim();
+			if (value.length > 0) {
+				return value;
+			}
+		}
+		return rootDirName;
+	},
+	resolveCommentSyntax(filePath) {
+		return resolveGoCommentSyntax(filePath);
+	}
+};

package/src/detectors/html.mjs

@@ -0,0 +1,54 @@
+import { extname } from "node:path";
+import { findNearestMarker } from "./shared.mjs";
+
+/**
+ * @fileoverview HTML detector implementation.
+ * @module fix-headers/detectors/html
+ */
+
+const markers = ["index.html", "vite.config.js", "vite.config.mjs", "next.config.js", "next.config.mjs"];
+const extensions = [".html", ".htm"];
+
+/**
+ * Parses HTML project name from marker context.
+ * @param {string} rootDirName - Fallback directory name.
+ * @returns {string} Project name.
+ */
+function parseHtmlProjectName(rootDirName) {
+	return rootDirName;
+}
+
+/**
+ * Resolves HTML comment syntax for HTML-like files.
+ * @param {string} filePath - File path.
+ * @returns {{kind: "html", blockStart: string, blockLinePrefix: string, blockEnd: string} | null} Syntax descriptor.
+ */
+function resolveHtmlCommentSyntax(filePath) {
+	const extension = extname(filePath).toLowerCase();
+	if (extensions.includes(extension)) {
+		return {
+			kind: "html",
+			blockStart: "<!--",
+			blockLinePrefix: "\t",
+			blockEnd: "-->"
+		};
+	}
+	return null;
+}
+
+export const detector = {
+	id: "html",
+	priority: 70,
+	markers,
+	extensions,
+	enabledByDefault: true,
+	findNearestConfig(startPath) {
+		return findNearestMarker(startPath, markers);
+	},
+	parseProjectName(_marker, _markerContent, rootDirName) {
+		return parseHtmlProjectName(rootDirName);
+	},
+	resolveCommentSyntax(filePath) {
+		return resolveHtmlCommentSyntax(filePath);
+	}
+};