@cldmv/fix-headers 1.0.0

package/README.md

@@ -0,0 +1,157 @@
+# fix-headers
+
+Multi-language source header normalizer for Node.js projects.
+
+`fix-headers` scans project files, auto-detects project metadata (language, root, project name, git author/email), and inserts or updates standard file headers.
+
+[![npm version]][npm_version_url] [![npm downloads]][npm_downloads_url] <!-- [![GitHub release]][github_release_url] -->[![GitHub downloads]][github_downloads_url] [![Last commit]][last_commit_url] <!-- [![Release date]][release_date_url] -->[![npm last update]][npm_last_update_url] [![Coverage]][coverage_url]
+
+[![Contributors]][contributors_url] [![Sponsor shinrai]][sponsor_url]
+
+## Features
+
+- Auto-detects project type by marker files (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `composer.json`)
+- Auto-detects author and email from git config/commit history
+- Supports per-run overrides for every detected value
+- Supports folder inclusion and exclusion configuration
+- Supports detector-based monorepo scanning with nearest config resolution per file
+- Supports per-detector syntax overrides for line and block comment tokens
+- Supports both ESM and CJS consumers
+
+## Install
+
+```bash
+npm i fix-headers
+```
+
+## Usage
+
+### ESM
+
+```js
+import fixHeaders from "fix-headers";
+
+const result = await fixHeaders({ dryRun: true });
+```
+
+## CLI
+
+After install, use the package binary:
+
+```bash
+fix-headers --dry-run --include-folder src --exclude-folder dist
+```
+
+Local development usage:
+
+```bash
+npm run cli -- --dry-run --json
+```
+
+Common CLI options:
+
+- `--dry-run`
+- `--json`
+- `--cwd <path>`
+- `--input <path>`
+- `--include-folder <path>` (repeatable)
+- `--exclude-folder <path>` (repeatable)
+- `--include-extension <ext>` (repeatable)
+- `--enable-detector <id>` / `--disable-detector <id>` (repeatable)
+- `--project-name <name>`
+- `--author-name <name>` / `--author-email <email>`
+- `--company-name <name>`
+- `--copyright-start-year <year>`
+- `--config <json-file>`
+
+### CommonJS
+
+```js
+const fixHeaders = require("fix-headers");
+
+const result = await fixHeaders({ dryRun: true });
+```
+
+## API
+
+### `fixHeaders(options?)`
+
+Runs header normalization. Project/language/author/email metadata is auto-detected internally on each run.
+
+Important options:
+
+- `cwd?: string` - start directory for project detection
+- `input?: string` - explicit single file or folder path to process
+- `dryRun?: boolean` - compute changes without writing files
+- `configFile?: string` - load JSON options from file (resolved from `cwd`)
+- `includeExtensions?: string[]` - file extensions to process
+- `enabledDetectors?: string[]` - detector ids to enable (defaults to all)
+- `disabledDetectors?: string[]` - detector ids to disable
+- `detectorSyntaxOverrides?: Record<string, { linePrefix?: string, blockStart?: string, blockLinePrefix?: string, blockEnd?: string }>` - override detector comment syntax tokens
+- `includeFolders?: string[]` - project-relative folders to scan
+- `excludeFolders?: string[]` - folder names or relative paths to exclude
+- `projectName?: string`
+- `language?: string`
+- `projectRoot?: string`
+- `marker?: string | null`
+- `authorName?: string`
+- `authorEmail?: string`
+- `companyName?: string` (default: `Catalyzed Motivation Inc.`)
+- `copyrightStartYear?: number` (default: current year)
+
+Example:
+
+```js
+const result = await fixHeaders({
+	cwd: process.cwd(),
+	dryRun: false,
+	configFile: "fix-headers.config.json",
+	includeFolders: ["src", "scripts"],
+	excludeFolders: ["src/generated", "dist"],
+	detectorSyntaxOverrides: {
+		node: {
+			blockStart: "/*",
+			blockLinePrefix: " * ",
+			blockEnd: " */"
+		},
+		python: {
+			linePrefix: ";;"
+		}
+	},
+	projectName: "@scope/my-package",
+	companyName: "Catalyzed Motivation Inc.",
+	copyrightStartYear: 2013
+});
+```
+
+## Notes
+
+- `excludeFolders` supports both folder-name and nested path matching.
+- For monorepos, each file resolves metadata from the closest detector config in its parent tree.
+
+## License
+
+Apache-2.0
+
+<!-- Badge definitions -->
+<!-- [github release]: https://img.shields.io/github/v/release/CLDMV/fix-headers?style=for-the-badge&logo=github&logoColor=white&labelColor=181717 -->
+<!-- [github_release_url]: https://github.com/CLDMV/fix-headers/releases -->
+<!-- [release date]: https://img.shields.io/github/release-date/CLDMV/fix-headers?style=for-the-badge&logo=github&logoColor=white&labelColor=181717 -->
+<!-- [release_date_url]: https://github.com/CLDMV/fix-headers/releases -->
+
+[npm version]: https://img.shields.io/npm/v/%40cldmv%2Ffix-headers.svg?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837
+[npm_version_url]: https://www.npmjs.com/package/@cldmv/fix-headers
+[npm downloads]: https://img.shields.io/npm/dm/%40cldmv%2Ffix-headers.svg?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837
+[npm_downloads_url]: https://www.npmjs.com/package/@cldmv/fix-headers
+[github downloads]: https://img.shields.io/github/downloads/CLDMV/fix-headers/total?style=for-the-badge&logo=github&logoColor=white&labelColor=181717
+[github_downloads_url]: https://github.com/CLDMV/fix-headers/releases
+[last commit]: https://img.shields.io/github/last-commit/CLDMV/fix-headers?style=for-the-badge&logo=github&logoColor=white&labelColor=181717
+[last_commit_url]: https://github.com/CLDMV/fix-headers/commits
+[npm last update]: https://img.shields.io/npm/last-update/%40cldmv%2Ffix-headers?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837
+[npm_last_update_url]: https://www.npmjs.com/package/@cldmv/fix-headers
+[coverage]: https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FCLDMV%2Ffix-headers%2Fbadges%2Fcoverage.json&style=for-the-badge&logo=vitest&logoColor=white
+[coverage_url]: https://github.com/CLDMV/fix-headers/blob/badges/coverage.json
+[contributors]: https://img.shields.io/github/contributors/CLDMV/fix-headers.svg?style=for-the-badge&logo=github&logoColor=white&labelColor=181717
+[contributors_url]: https://github.com/CLDMV/fix-headers/graphs/contributors
+[sponsor shinrai]: https://img.shields.io/github/sponsors/shinrai?style=for-the-badge&logo=githubsponsors&logoColor=white&labelColor=EA4AAA&label=Sponsor
+[sponsor_url]: https://github.com/sponsors/shinrai

package/index.cjs

@@ -0,0 +1,39 @@
+/**
+ *	@Project: @cldmv/fix-headers
+ *	@Filename: /index.cjs
+ *	@Date: 2026-03-01 13:29:45 -08:00 (1772400585)
+ *	@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:36 -08:00 (1772411376)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
+
+/**
+ * @fileoverview CJS shim for consuming the ESM-based fix-headers module.
+ * @module fix-headers/cjs-shim
+ */
+
+"use strict";
+
+/**
+ * Loads the ESM module implementation.
+ * @returns {Promise<import("./index.mjs")>} Loaded ESM module.
+ */
+function loadEsmModule() {
+	return import("./index.mjs");
+}
+
+/**
+ * Runs header normalization with auto-detection and override options.
+ * @param {Record<string, unknown>} [options] - Runtime options.
+ * @returns {Promise<unknown>} Header update report.
+ */
+async function fixHeaders(options) {
+	const mod = await loadEsmModule();
+	return mod.default(options);
+}
+
+module.exports = fixHeaders;

package/index.mjs

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview ESM shim for the fix-headers package API.
+ * @module fix-headers/esm-shim
+ */
+
+export * from "./src/fix-header.mjs";
+export { default } from "./src/fix-header.mjs";

package/package.json

@@ -0,0 +1,56 @@
+{
+	"name": "@cldmv/fix-headers",
+	"version": "1.0.0",
+	"description": "Multi-language project header normalizer with auto-detection and override support.",
+	"type": "module",
+	"main": "./index.cjs",
+	"module": "./index.mjs",
+	"types": "./types/index.d.mts",
+	"files": [
+		"index.mjs",
+		"index.cjs",
+		"src/",
+		"types/"
+	],
+	"exports": {
+		".": {
+			"types": "./types/index.d.mts",
+			"import": "./index.mjs",
+			"require": "./index.cjs"
+		}
+	},
+	"bin": {
+		"fix-headers": "./src/cli.mjs"
+	},
+	"scripts": {
+		"test": "vitest run --config .configs/vitest.config.mjs",
+		"test:watch": "vitest --config .configs/vitest.config.mjs",
+		"ci:coverage": "vitest run --coverage --reporter=dot --maxWorkers=1 --config .configs/vitest.ci.config.mjs",
+		"types:build": "tsc -p .configs/tsconfig.json --noCheck",
+		"types:check": "tsc -p .configs/tsconfig.json --noEmit",
+		"test:coverage": "vitest run --config .configs/vitest.config.mjs --coverage",
+		"cli": "node ./src/cli.mjs"
+	},
+	"keywords": [
+		"headers",
+		"copyright",
+		"automation",
+		"node-module"
+	],
+	"peerDependencies": {
+		"vitest": ">=1.0.0"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"license": "Apache-2.0",
+	"devDependencies": {
+		"@types/node": "^25.3.0",
+		"typescript": "^5.9.3",
+		"@vitest/coverage-v8": "^3.2.4",
+		"vitest": "^3.2.4"
+	}
+}

package/src/cli.mjs

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import fixHeaders from "./fix-header.mjs";
+
+/**
+ * @fileoverview CLI entry point for running fix-headers from terminal commands.
+ * @module fix-headers/cli
+ */
+
+const HELP_TEXT = `fix-headers CLI\n\nUsage:\n  fix-headers [options]\n\nOptions:\n  -h, --help                         Show help\n      --dry-run                      Compute changes without writing files\n      --json                         Print JSON output\n      --cwd <path>                   Working directory for project detection\n      --input <path>                 Single file or folder input\n      --include-folder <path>        Include folder (repeatable)\n      --exclude-folder <path>        Exclude folder name/path (repeatable)\n      --include-extension <ext>      Include extension (repeatable)\n      --enable-detector <id>         Enable only specific detector (repeatable)\n      --disable-detector <id>        Disable detector by id (repeatable)\n      --project-name <name>          Override project name\n      --language <id>                Override language id\n      --project-root <path>          Override project root\n      --marker <name|null>           Override marker filename\n      --author-name <name>           Override author name\n      --author-email <email>         Override author email\n      --company-name <name>          Override company name\n      --copyright-start-year <year>  Override copyright start year\n      --config <path>                Load JSON options file\n\nExamples:\n  fix-headers --dry-run --include-folder src\n  fix-headers --project-name @scope/pkg --company-name "Catalyzed Motivation Inc."\n`;
+
+/**
+ * Converts CLI flag token to camelCase key.
+ * @param {string} token - CLI token without leading dashes.
+ * @returns {string} CamelCase key.
+ */
+function toCamelCase(token) {
+	return token.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+
+/**
+ * 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) {
+	/** @type {Record<string, unknown>} */
+	const options = {};
+	const control = { help: false, json: false };
+	const multiMap = {
+		"include-folder": "includeFolders",
+		"exclude-folder": "excludeFolders",
+		"include-extension": "includeExtensions",
+		"enable-detector": "enabledDetectors",
+		"disable-detector": "disabledDetectors"
+	};
+	const scalarMap = {
+		cwd: "cwd",
+		input: "input",
+		"project-name": "projectName",
+		language: "language",
+		"project-root": "projectRoot",
+		marker: "marker",
+		"author-name": "authorName",
+		"author-email": "authorEmail",
+		"company-name": "companyName",
+		"copyright-start-year": "copyrightStartYear",
+		config: "config"
+	};
+
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (arg === "-h" || arg === "--help") {
+			control.help = true;
+			continue;
+		}
+		if (arg === "--json") {
+			control.json = true;
+			continue;
+		}
+		if (arg === "--dry-run") {
+			options.dryRun = true;
+			continue;
+		}
+		if (!arg.startsWith("--")) {
+			throw new Error(`Unexpected argument: ${arg}`);
+		}
+
+		const flag = arg.slice(2);
+		if (multiMap[flag]) {
+			const value = argv[index + 1];
+			if (!value || value.startsWith("--")) {
+				throw new Error(`Missing value for --${flag}`);
+			}
+			index += 1;
+			const key = multiMap[flag];
+			const list = Array.isArray(options[key]) ? options[key] : [];
+			options[key] = [...list, value];
+			continue;
+		}
+
+		if (scalarMap[flag]) {
+			const value = argv[index + 1];
+			if (!value || value.startsWith("--")) {
+				throw new Error(`Missing value for --${flag}`);
+			}
+			index += 1;
+			const key = scalarMap[flag];
+			if (key === "copyrightStartYear") {
+				options[key] = Number.parseInt(value, 10);
+				if (Number.isNaN(options[key])) {
+					throw new Error(`Invalid number for --${flag}: ${value}`);
+				}
+			} else if (key === "marker" && value === "null") {
+				options[key] = null;
+			} else {
+				options[key] = value;
+			}
+			continue;
+		}
+
+		const camelKey = toCamelCase(flag);
+		const value = argv[index + 1];
+		if (!value || value.startsWith("--")) {
+			throw new Error(`Unknown or malformed flag: --${flag}`);
+		}
+		index += 1;
+		options[camelKey] = value;
+	}
+
+	return {
+		options,
+		help: control.help,
+		json: control.json
+	};
+}
+
+/**
+ * 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 async function applyConfigFile(options) {
+	if (typeof options.config !== "string" || options.config.trim().length === 0) {
+		return options;
+	}
+
+	const baseDir = typeof options.cwd === "string" && options.cwd.length > 0 ? options.cwd : process.cwd();
+	const configPath = isAbsolute(options.config) ? options.config : join(baseDir, options.config);
+	const raw = await readFile(configPath, "utf8");
+	const parsed = JSON.parse(raw);
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error("Config file must contain a JSON object");
+	}
+
+	const merged = { ...parsed, ...options };
+	delete merged.config;
+	/** @type {Record<string, unknown>} */
+	const output = merged;
+	return output;
+}
+
+/**
+ * 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 async function runCli(argv, deps = {}) {
+	const runner = deps.runner || fixHeaders;
+	const stdout = deps.stdout || console.log;
+	const stderr = deps.stderr || console.error;
+
+	try {
+		const parsed = parseCliArgs(argv);
+		if (parsed.help) {
+			stdout(HELP_TEXT);
+			return 0;
+		}
+
+		const finalOptions = await applyConfigFile(parsed.options);
+		const result = await runner(finalOptions);
+
+		if (parsed.json) {
+			stdout(JSON.stringify(result, null, 2));
+			return 0;
+		}
+
+		if (result && typeof result === "object") {
+			const report = /** @type {{filesScanned?: number, filesUpdated?: number, dryRun?: boolean}} */ (result);
+			stdout(
+				`fix-headers complete: scanned=${report.filesScanned ?? 0}, updated=${report.filesUpdated ?? 0}, dryRun=${report.dryRun === true}`
+			);
+		} else {
+			stdout("fix-headers complete");
+		}
+		return 0;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		stderr(`fix-headers failed: ${message}`);
+		return 1;
+	}
+}
+
+/**
+ * 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 = process.argv, moduleUrl = import.meta.url, executor = runCli) {
+	const isMain = argv[1] && moduleUrl === pathToFileURL(argv[1]).href;
+	if (!isMain) {
+		return false;
+	}
+
+	executor(argv.slice(2)).then((code) => {
+		process.exitCode = code;
+	});
+
+	return true;
+}
+
+runCliAsMain();

package/src/constants.mjs

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Shared constants for project/language detection and header defaults.
+ * @module fix-headers/constants
+ */
+
+export { DETECTOR_PROFILES, getAllowedExtensions, getEnabledDetectors } from "./detectors/index.mjs";
+
+/** @type {string} */
+export const DEFAULT_COMPANY_NAME = "Catalyzed Motivation Inc.";
+
+/** @type {number} */
+export const DEFAULT_MAX_HEADER_SCAN_LINES = 40;
+
+/** @type {Set<string>} */
+export const DEFAULT_IGNORE_FOLDERS = new Set([".git", "node_modules", "dist", "build", "coverage", "tmp", ".next", ".turbo"]);

package/src/core/file-discovery.mjs

@@ -0,0 +1,133 @@
+import { join, relative, resolve } from "node:path";
+import { DEFAULT_IGNORE_FOLDERS } from "../constants.mjs";
+import { getAllowedExtensions } from "../detectors/index.mjs";
+import { walkFiles } from "../utils/fs.mjs";
+
+/**
+ * @fileoverview Resolves candidate source files for header updates based on language and options.
+ * @module fix-headers/core/file-discovery
+ */
+
+/**
+ * Resolves extension set from enabled detectors and optional override.
+ * @param {{
+ *  includeExtensions?: string[],
+ *  enabledDetectors?: string[],
+ *  disabledDetectors?: string[]
+ * }} options - Extension options.
+ * @returns {Set<string>} Effective extension set.
+ */
+function resolveExtensions(options) {
+	return getAllowedExtensions(options);
+}
+
+const DEFAULT_IGNORED_FOLDERS = new Set(DEFAULT_IGNORE_FOLDERS);
+
+/**
+ * Normalizes a user-provided folder path to a project-relative value.
+ * @param {string} folderPath - Folder path string.
+ * @returns {string} Normalized path.
+ */
+function normalizeFolderPath(folderPath) {
+	return folderPath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "").replace(/\/+$/, "");
+}
+
+/**
+ * Determines include roots from explicit include folders.
+ * @param {string[] | undefined} includeFolders - Include folder option.
+ * @returns {string[]} Effective include roots.
+ */
+function resolveIncludeFolders(includeFolders) {
+	if (Array.isArray(includeFolders) && includeFolders.length > 0) {
+		return includeFolders;
+	}
+
+	return [];
+}
+
+/**
+ * Builds a directory exclusion matcher from path and folder-name lists.
+ * @param {string} projectRoot - Project root path.
+ * @param {string[] | undefined} excludeFolders - Folder exclusions.
+ * @returns {(targetPath: string, targetName: string) => boolean} Exclusion predicate.
+ */
+function buildExclusionMatcher(projectRoot, excludeFolders) {
+	if (!Array.isArray(excludeFolders) || excludeFolders.length === 0) {
+		return () => false;
+	}
+
+	const absoluteRoot = resolve(projectRoot);
+	const pathExclusions = [];
+	const nameExclusions = new Set();
+
+	for (const entry of excludeFolders) {
+		if (typeof entry !== "string") {
+			continue;
+		}
+
+		const normalized = normalizeFolderPath(entry);
+		if (normalized.length === 0) {
+			continue;
+		}
+
+		if (normalized.includes("/")) {
+			pathExclusions.push(resolve(absoluteRoot, normalized));
+			continue;
+		}
+
+		nameExclusions.add(normalized);
+	}
+
+	return (targetPath, targetName) => {
+		if (nameExclusions.has(targetName)) {
+			return true;
+		}
+
+		for (const excludedPath of pathExclusions) {
+			if (targetPath === excludedPath || targetPath.startsWith(`${excludedPath}/`)) {
+				return true;
+			}
+		}
+
+		const relPath = normalizeFolderPath(relative(absoluteRoot, targetPath));
+		return pathExclusions.some((excludedPath) => {
+			const relExcluded = normalizeFolderPath(relative(absoluteRoot, excludedPath));
+			return relPath === relExcluded || relPath.startsWith(`${relExcluded}/`);
+		});
+	};
+}
+
+/**
+ * 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 async function discoverFiles(options) {
+	const allowedExtensions = resolveExtensions(options);
+	const includeFolders = resolveIncludeFolders(options.includeFolders);
+	const excludeFolders = Array.isArray(options.excludeFolders) ? options.excludeFolders : [];
+	const exclusionMatcher = buildExclusionMatcher(options.projectRoot, excludeFolders);
+
+	const roots =
+		includeFolders.length > 0 ? includeFolders.map((relativePath) => join(options.projectRoot, relativePath)) : [options.projectRoot];
+
+	const files = [];
+	for (const rootPath of roots) {
+		const discovered = await walkFiles(rootPath, {
+			allowedExtensions,
+			ignoreFolders: DEFAULT_IGNORED_FOLDERS,
+			shouldSkipDirectory: exclusionMatcher
+		});
+		files.push(...discovered);
+	}
+
+	return files.filter((filePath) => !exclusionMatcher(filePath, filePath.split("/").at(-1) || ""));
+}