@cldmv/fix-headers

Multi-language source header normalizer for Node.js projects.

@cldmv/fix-headers scans project files, auto-detects project metadata (language, root, project name, git author/email), and inserts or updates standard file headers.

Features

• Auto-detects project type by marker files (package.json, pyproject.toml, Cargo.toml, go.mod, composer.json) and YAML files (.yaml, .yml)
• 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

npm i @cldmv/fix-headers

Usage

ESM

import fixHeaders from "@cldmv/fix-headers";

const result = await fixHeaders({ dryRun: true });

CLI

After install, use the package binary:

fix-headers --dry-run --include-folder src --exclude-folder dist

Local development usage:

npm run cli -- --dry-run --json

Common CLI options:

• --dry-run
• --json
• --sample-output
• --force-author-update
• --use-gpg-signer-author
• --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

const fixHeaders = require("@cldmv/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
• sampleOutput?: boolean - include previous/new header sample text for changed 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, lineSeparator?: 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
• company?: string - appends to @Author as Name <Company>
• forceAuthorUpdate?: boolean - force update @Author/@Email to detected or overridden current values
• useGpgSignerAuthor?: boolean - use signed-commit UID (%GS) for detected @Author (includes signer comment when present)
• companyName?: string (default: Catalyzed Motivation Inc.)
• copyrightStartYear?: number (default: current year)

Example:

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: ";;",
			lineSeparator: " "
		}
	},
	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.
• With sampleOutput enabled, each changed file includes previousValue, newValue, and detectedValues in results.

License

Apache-2.0