@sheplu/editorconfig 0.10.0 → 0.11.0

package/README.md

@@ -6,6 +6,7 @@ A small CLI to manage a **consistent `.editorconfig`** across your projects.
 - ✅ Check if your existing file matches the target setup
 - ✅ Confirm before overwriting an existing `.editorconfig` (or pass `--overwrite` to skip the prompt)
 - ✅ Override the built-in template with a team-shared file via `--template` (local path or `https://` URL)
+- ✅ Validate every `.editorconfig` in a monorepo at once with `--recursive`
 
 ## Why?
 
@@ -113,6 +114,48 @@ This command will:
   - `0` if everything matches
   - `1` if differences are found
 
+### `--recursive` (monorepo check)
+
+```bash
+npx @sheplu/editorconfig --mode=check --recursive
+```
+
+Walks the current directory (or the directory passed via `--path`) and validates **every** `.editorconfig` it finds. Useful for monorepos where a top-level file sets defaults and sub-packages add narrower overrides.
+
+How files are classified:
+
+- The shortest-path `.editorconfig` in each subtree is treated as the **root** and validated with the same rules as `--mode=check` (must declare `root = true`, must have `[*]`, sections must match the canonical template).
+- Deeper `.editorconfig` files are treated as **children**. Children must NOT declare `root = true`, may omit `[*]`, and may legitimately override individual keys.
+- Sibling subtrees with no shared ancestor `.editorconfig` are each validated as their own root.
+
+Cross-file checks emitted on top of per-file validation:
+
+- `child-root` — a child declared `root = true` (**fail**).
+- `redundant` — a child redeclares a parent key/value verbatim (**warn**).
+- `contradiction` — a child reuses the same header as its root (e.g. both `[*]`) with a different value (**warn**). Different globs like child `[*.js]` overriding root `[*]` are silent — they are legitimate per spec.
+
+Skipped during the walk: `node_modules`, `.git`, `dist`, `build`, `coverage`, `.next`, `.cache`, and symlinked directories.
+
+Flag interactions in recursive mode:
+
+- `--path` becomes the start directory for the walk (default: cwd).
+- `--languages` is enforced on the root file only — children may add or omit language sections freely.
+- `--template` overrides apply to the root section comparison.
+- `--strict` fails on unknown headers in any file.
+
+Exit codes: `0` on pass (warnings allowed), `1` if any file fails or any cross-file failure (e.g. child-root) is detected.
+
+```bash
+# Validate everything under cwd
+npx @sheplu/editorconfig --mode=check --recursive
+
+# Validate only one subtree
+npx @sheplu/editorconfig --mode=check --recursive --path=./packages/web
+
+# CI: enforce js/md sections on the root, anywhere else may add what they need
+npx @sheplu/editorconfig --mode=check --recursive --languages=js,md
+```
+
 ### `--template` (custom team template)
 
 Both `write` and `check` accept a `--template` (or `-t`) flag pointing at a custom `.editorconfig`-syntax file. Sections in that file override the built-in defaults; languages it doesn't redefine still come from the built-ins. This lets a team host a single source of truth and reference it from every repo.
@@ -178,6 +221,7 @@ Run them with:
 npm test                  # everything
 npm run test:unit         # unit only — runs in ~50ms
 npm run test:integration  # integration only — spawns the CLI
+npm run test:coverage.    # coverage with 95% threshold
 npm run lint              # oxlint
 ```
 

package/index.js

@@ -1,267 +1,11 @@
 #!/usr/bin/env node
 
-import { existsSync, writeFileSync } from "node:fs";
-import { createInterface } from 'node:readline';
-import { parseArgs } from 'node:util';
-import {
-	ALIASES,
-	AVAILABLE_LANGUAGES,
-	composeEditorConfig,
-	EMPTY_OVERRIDES,
-} from './src/templates/index.js';
-import { loadCustomTemplate } from './src/templates/custom-template.js';
-import { compareEditorConfig, NO_LANGUAGE_FILTER, runCheck } from './src/check.js';
-import { logger } from './src/utils/logger.js';
+import { compareEditorConfig } from './src/check.js';
+import { parseCliArgs, printHelp } from './src/cli/options.js';
+import { dispatchValues } from './src/cli/dispatch.js';
+import { createEditorConfig } from './src/cli/write-flow.js';
 
-export { compareEditorConfig };
-
-export function createEditorConfig(path = '.editorconfig', languages = [], overrides = EMPTY_OVERRIDES) {
-	writeFileSync(path, composeEditorConfig(languages, overrides), 'utf8');
-};
-
-export const options = {
-	mode: {
-		type: 'string',
-		short: 'm',
-	},
-	path: {
-		type: 'string',
-		short: 'p',
-	},
-	languages: {
-		type: 'string',
-		short: 'l',
-	},
-	help: {
-		type: 'boolean',
-		short: 'h',
-	},
-	overwrite: {
-		type: 'boolean',
-		short: 'o',
-	},
-	strict: {
-		type: 'boolean',
-		short: 's',
-	},
-	template: {
-		type: 'string',
-		short: 't',
-	},
-};
-
-export const NOT_PROVIDED = Symbol('languages-not-provided');
-
-export function parseLanguages(raw) {
-	if (typeof raw !== 'string') {
-		return NOT_PROVIDED;
-	}
-	return raw
-		.split(',')
-		.map((token) => token.trim().toLowerCase())
-		.filter((token) => token.length > 0);
-}
-
-function formatAliasList() {
-	const grouped = new Map();
-	for (const [alias, target] of Object.entries(ALIASES)) {
-		const list = grouped.get(target) ?? [];
-		list.push(alias);
-		grouped.set(target, list);
-	}
-	return [...grouped.entries()]
-		.map(([target, aliases]) => `${aliases.join(', ')} -> ${target}`)
-		.join('; ');
-}
-
-export function printHelp() {
-	logger.log(`Usage: editorconfig --mode=<command> [--path=<path>] [--languages=<list>] [--template=<path|url>]
-
-Commands:
-  write    Create a .editorconfig file with the selected language sections
-  check    Validate per-section against the canonical templates
-
-Options:
-  -m, --mode       Command to run (write | check)
-  -p, --path       Path to the .editorconfig file (default: .editorconfig)
-  -l, --languages  Comma-separated language sections (write: which to emit; check: required set)
-  -o, --overwrite  Overwrite an existing .editorconfig without confirmation
-  -s, --strict     Treat unknown section headers as failures (check only)
-  -t, --template   Path or https URL to a custom .editorconfig-syntax file whose sections override the built-in ones
-  -h, --help       Show this help message
-
-Languages: ${AVAILABLE_LANGUAGES.join(', ')}
-Aliases:   ${formatAliasList()}
-
-Examples:
-  editorconfig --mode=write --languages=js,md
-  editorconfig --mode=write --languages=         # base only
-  editorconfig --mode=write                       # interactive in TTY, base only otherwise
-  editorconfig --mode=check                       # validate sections present in the file
-  editorconfig --mode=check --languages=js,md    # require exactly base + js + md
-  editorconfig --mode=check --strict             # fail on any unknown section header
-  editorconfig --mode=write --template=./team.editorconfig
-  editorconfig --mode=check --template=./team.editorconfig
-  editorconfig --mode=check --template=https://team.example.com/.editorconfig`);
-};
-
-function resolvePromptAnswer(answer) {
-	const tokens = answer
-		.split(',')
-		.map((token) => token.trim().toLowerCase())
-		.filter((token) => token.length > 0);
-	return tokens.map((token) => {
-		const asNumber = Number.parseInt(token, 10);
-		if (Number.isInteger(asNumber) && asNumber >= 1 && asNumber <= AVAILABLE_LANGUAGES.length) {
-			return AVAILABLE_LANGUAGES[asNumber - 1];
-		}
-		return token;
-	});
-}
-
-function promptLanguages() {
-	return new Promise((resolve) => {
-		const rl = createInterface({ input: process.stdin, output: process.stdout });
-		const numbered = AVAILABLE_LANGUAGES
-			.map((name, index) => `  ${index + 1}. ${name}`)
-			.join('\n');
-		logger.log(`Available language sections:\n${numbered}`);
-		rl.question('Languages? [comma-separated names or indices, blank=base only] ', (answer) => {
-			rl.close();
-			resolve(resolvePromptAnswer(answer));
-		});
-	});
-}
-
-function resolveLanguages(parsedLanguages) {
-	if (parsedLanguages !== NOT_PROVIDED) {
-		return Promise.resolve(parsedLanguages);
-	}
-	if (process.stdin.isTTY) {
-		return promptLanguages();
-	}
-	return Promise.resolve([]);
-}
-
-function confirmOverwrite(path) {
-	return new Promise((resolve) => {
-		const rl = createInterface({ input: process.stdin, output: process.stdout });
-		rl.question(`\`${path}\` already exists. Overwrite? [y/N] `, (answer) => {
-			rl.close();
-			resolve(/^y(es)?$/iu.test(answer.trim()));
-		});
-	});
-}
-
-async function handleExistingTarget(path, languages, overrides) {
-	if (!process.stdin.isTTY) {
-		logger.error(`\`${path}\` already exists. Use --overwrite to replace it.`);
-		process.exitCode = 1;
-		return;
-	}
-	const confirmed = await confirmOverwrite(path);
-	if (confirmed) {
-		createEditorConfig(path, languages, overrides);
-	}
-	else {
-		logger.log(`Skipped: \`${path}\` was not modified.`);
-	}
-}
-
-async function runWrite({ path, overwrite, parsedLanguages, overrides }) {
-	const languages = await resolveLanguages(parsedLanguages);
-	if (!existsSync(path) || overwrite) {
-		createEditorConfig(path, languages, overrides);
-		return;
-	}
-	await handleExistingTarget(path, languages, overrides);
-}
-
-function dispatchCheck({ path, languages, strict, overrides }) {
-	let filter = languages;
-	if (filter === NOT_PROVIDED) {
-		filter = NO_LANGUAGE_FILTER;
-	}
-	try {
-		runCheck({ path, parsedLanguages: filter, strict, overrides });
-	}
-	catch (error) {
-		logger.error(error.message);
-		process.exitCode = 1;
-	}
-}
-
-async function dispatchWrite({ path, overwrite, languages, overrides }) {
-	try {
-		await runWrite({ path, overwrite, parsedLanguages: languages, overrides });
-	}
-	catch (error) {
-		logger.error(error.message);
-		process.exitCode = 1;
-	}
-}
-
-async function runCommand({ mode, path, overwrite, languages, strict, overrides }) {
-	if (mode === 'write') {
-		await dispatchWrite({ path, overwrite, languages, overrides });
-		return;
-	}
-	if (mode === 'check') {
-		dispatchCheck({ path, languages, strict, overrides });
-		return;
-	}
-	logger.error('invalid command');
-	process.exitCode = 1;
-}
-
-function formatCliError(error) {
-	if (error.code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION') {
-		return `${error.message.split('.')[0]}. See --help.`;
-	}
-	return error.message;
-}
-
-function parseCliArgs(args) {
-	try {
-		return parseArgs({ args, options });
-	}
-	catch (error) {
-		logger.error(formatCliError(error));
-		process.exitCode = 1;
-		return false;
-	}
-}
-
-const OVERRIDES_FAILED = Symbol('overrides-failed');
-
-async function resolveOverrides(templateValue) {
-	if (typeof templateValue !== 'string') {
-		return EMPTY_OVERRIDES;
-	}
-	try {
-		return await loadCustomTemplate(templateValue);
-	}
-	catch (error) {
-		logger.error(error.message);
-		process.exitCode = 1;
-		return OVERRIDES_FAILED;
-	}
-}
-
-async function dispatchValues(values) {
-	const overrides = await resolveOverrides(values.template);
-	if (overrides === OVERRIDES_FAILED) {
-		return;
-	}
-	await runCommand({
-		mode: values.mode,
-		path: values.path || '.editorconfig',
-		overwrite: values.overwrite,
-		languages: parseLanguages(values.languages),
-		strict: values.strict,
-		overrides,
-	});
-}
+export { compareEditorConfig, createEditorConfig };
 
 async function main() {
 	const parsed = parseCliArgs(process.argv.slice(2));
@@ -276,11 +20,5 @@ async function main() {
 };
 
 if (process.argv[1] === import.meta.filename) {
-	try {
-		await main();
-	}
-	catch (error) {
-		logger.error(error.message);
-		process.exitCode = 1;
-	}
+	await main();
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@sheplu/editorconfig",
-	"version": "0.10.0",
-	"description": "",
+	"version": "0.11.0",
+	"description": "CLI to generate and validate a consistent .editorconfig across your projects",
 	"main": "index.js",
 	"files": [
 		"index.js",
@@ -10,6 +10,7 @@
 	"scripts": {
 		"lint": "oxlint",
 		"test": "node --test",
+		"test:coverage": "node --test --experimental-test-coverage --test-coverage-lines=95 --test-coverage-branches=95 --test-coverage-functions=95",
 		"test:unit": "node --test 'test/unit/*.test.js'",
 		"test:integration": "node --test 'test/integration/*.test.js'"
 	},
@@ -40,6 +41,6 @@
 	"homepage": "https://github.com/sheplu/editorconfig#readme",
 	"devDependencies": {
 		"node-pty": "1.0.0",
-		"oxlint": "^1.65.0"
+		"oxlint": "^1.67.0"
 	}
 }

package/src/cascade.js

@@ -0,0 +1,119 @@
+import { dirname, sep } from 'node:path';
+
+function depthOf(path) {
+	return path.split(sep).length;
+}
+
+function isAncestorDir(ancestor, descendant) {
+	return descendant.startsWith(`${ancestor}${sep}`);
+}
+
+function comparePaths(left, right) {
+	const dl = depthOf(left);
+	const dr = depthOf(right);
+	if (dl !== dr) {
+		return dl - dr;
+	}
+	return left.localeCompare(right);
+}
+
+function findClosestAncestor(trees, dir) {
+	return trees.find((tree) => isAncestorDir(dirname(tree.root), dir)) ?? false;
+}
+
+export function classify(paths) {
+	const sorted = paths.toSorted(comparePaths);
+	const trees = [];
+	for (const path of sorted) {
+		const ancestor = findClosestAncestor(trees, dirname(path));
+		if (ancestor) {
+			ancestor.children.push(path);
+		}
+		else {
+			trees.push({ root: path, children: [] });
+		}
+	}
+	return trees;
+}
+
+function buildSectionMap(parsed) {
+	const map = new Map();
+	for (const section of parsed.sections) {
+		if (!map.has(section.header)) {
+			map.set(section.header, new Map());
+		}
+		const target = map.get(section.header);
+		for (const [key, value] of section.body) {
+			target.set(key, value);
+		}
+	}
+	return map;
+}
+
+function diffKey({ childPath, header, key, childValue, rootValue }) {
+	if (rootValue === childValue) {
+		return {
+			kind: 'redundant',
+			severity: 'warn',
+			file: childPath,
+			header,
+			key,
+			value: childValue,
+		};
+	}
+	return {
+		kind: 'contradiction',
+		severity: 'warn',
+		file: childPath,
+		header,
+		key,
+		rootValue,
+		childValue,
+	};
+}
+
+function compareChildKeys({ childPath, header, childBody, rootSections }) {
+	const rootSameHeader = rootSections.get(header);
+	if (!rootSameHeader) {
+		return [];
+	}
+	const issues = [];
+	for (const [key, value] of childBody) {
+		if (rootSameHeader.has(key)) {
+			issues.push(diffKey({
+				childPath,
+				header,
+				key,
+				childValue: value,
+				rootValue: rootSameHeader.get(key),
+			}));
+		}
+	}
+	return issues;
+}
+
+function compareKeyIssues(left, right) {
+	if (left.header !== right.header) {
+		return left.header.localeCompare(right.header);
+	}
+	return left.key.localeCompare(right.key);
+}
+
+function collectKeyIssues({ rootParsed, childParsed, childPath }) {
+	const rootSections = buildSectionMap(rootParsed);
+	const childSections = buildSectionMap(childParsed);
+	const issues = [];
+	for (const [header, childBody] of childSections) {
+		issues.push(...compareChildKeys({ childPath, header, childBody, rootSections }));
+	}
+	return issues.toSorted(compareKeyIssues);
+}
+
+export function crossFileIssues({ rootParsed, childParsed, childPath }) {
+	const issues = [];
+	if (childParsed.hasRoot) {
+		issues.push({ kind: 'child-root', severity: 'fail', file: childPath });
+	}
+	issues.push(...collectKeyIssues({ rootParsed, childParsed, childPath }));
+	return issues;
+}

package/src/check-recursive.js

@@ -0,0 +1,209 @@
+import { existsSync, statSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { discoverEditorConfigs } from './discover.js';
+import { classify, crossFileIssues } from './cascade.js';
+import {
+	compareEditorConfigForRole,
+	NO_LANGUAGE_FILTER,
+	printReport,
+	reportIsFailing,
+	summarizeReport,
+} from './check.js';
+import { logger } from './utils/logger.js';
+
+function resolveStartDir(rawPath) {
+	const abs = resolve(rawPath);
+	if (!existsSync(abs)) {
+		throw new Error(`'${rawPath}' does not exist`);
+	}
+	const stats = statSync(abs);
+	if (stats.isDirectory()) {
+		return abs;
+	}
+	const dir = dirname(abs);
+	logger.warn(`--recursive expects a directory; using '${dir}' instead of '${rawPath}'.`);
+	return dir;
+}
+
+function displayPath(absPath, startDir) {
+	return relative(startDir, absPath);
+}
+
+function formatChildRoot(where) {
+	return `  ❌ ${where} declares 'root = true' (forbidden in child)`;
+}
+
+function formatRedundant(issue, where) {
+	return `  ⚠️  ${where} ${issue.header} ${issue.key} = ${issue.value} (redundant — same as root)`;
+}
+
+function formatContradiction(issue, where) {
+	return `  ⚠️  ${where} ${issue.header} ${issue.key} = ${issue.childValue} (contradicts root ${issue.header} ${issue.key} = ${issue.rootValue})`;
+}
+
+function formatCrossFileIssue(issue, startDir) {
+	const where = displayPath(issue.file, startDir);
+	if (issue.kind === 'child-root') {
+		return formatChildRoot(where);
+	}
+	if (issue.kind === 'redundant') {
+		return formatRedundant(issue, where);
+	}
+	return formatContradiction(issue, where);
+}
+
+function buildEntry({ path, role, parsedLanguages, overrides }) {
+	return {
+		path,
+		role,
+		report: compareEditorConfigForRole({ path, parsedLanguages, overrides, role }),
+	};
+}
+
+function buildFileEntries(tree, parsedLanguages, overrides) {
+	const entries = [buildEntry({ path: tree.root, role: 'root', parsedLanguages, overrides })];
+	for (const child of tree.children) {
+		entries.push(buildEntry({
+			path: child,
+			role: 'child',
+			parsedLanguages: NO_LANGUAGE_FILTER,
+			overrides,
+		}));
+	}
+	return entries;
+}
+
+function collectCrossIssues(rootEntry, childEntries) {
+	const issues = [];
+	for (const child of childEntries) {
+		issues.push(...crossFileIssues({
+			rootParsed: rootEntry.report.parsed,
+			childParsed: child.report.parsed,
+			childPath: child.path,
+		}));
+	}
+	return issues;
+}
+
+function printFileBlock(entry, startDir) {
+	const label = `[${entry.role}]`;
+	printReport(displayPath(entry.path, startDir), entry.report, { label });
+}
+
+function printCrossFileBlock(issues, startDir) {
+	if (issues.length === 0) {
+		return;
+	}
+	logger.log('Cross-file warnings');
+	logger.log('');
+	for (const issue of issues) {
+		logger.log(formatCrossFileIssue(issue, startDir));
+	}
+	logger.log('');
+}
+
+function aggregateCounts(entries, strict) {
+	const totals = { matched: 0, failed: 0, unknown: 0, filesFailed: 0 };
+	for (const entry of entries) {
+		const counts = summarizeReport(entry.report);
+		totals.matched += counts.matched;
+		totals.failed += counts.failed;
+		totals.unknown += counts.unknown;
+		if (reportIsFailing(entry.report, strict)) {
+			totals.filesFailed += 1;
+		}
+	}
+	return totals;
+}
+
+function pluralize(count, singular) {
+	if (count === 1) {
+		return singular;
+	}
+	return `${singular}s`;
+}
+
+function buildSummaryParts({ fileCount, counts, warnings, crossFailures, strict }) {
+	const parts = [`${fileCount} ${pluralize(fileCount, 'file')} checked`];
+	if (counts.filesFailed > 0) {
+		parts.push(`${counts.filesFailed} failed`);
+	}
+	if (crossFailures > 0) {
+		parts.push(`${crossFailures} cross-file ${pluralize(crossFailures, 'failure')}`);
+	}
+	if (warnings > 0) {
+		parts.push(`${warnings} ${pluralize(warnings, 'warning')}`);
+	}
+	if (counts.unknown > 0 && !strict) {
+		parts.push(`${counts.unknown} unknown ${pluralize(counts.unknown, 'header')} ignored`);
+	}
+	return parts;
+}
+
+function summaryHead(passed) {
+	if (passed) {
+		return '✅ PASS';
+	}
+	return '❌ FAIL';
+}
+
+function formatGlobalSummary({ entries, crossIssues, strict }) {
+	const counts = aggregateCounts(entries, strict);
+	const warnings = crossIssues.filter((issue) => issue.severity === 'warn').length;
+	const crossFailures = crossIssues.filter((issue) => issue.severity === 'fail').length;
+	const passed = counts.filesFailed === 0 && crossFailures === 0;
+	const parts = buildSummaryParts({
+		fileCount: entries.length,
+		counts,
+		warnings,
+		crossFailures,
+		strict,
+	});
+	return { line: `${summaryHead(passed)} — ${parts.join('; ')}`, failed: !passed };
+}
+
+function processTree({ tree, parsedLanguages, overrides, startDir }) {
+	const entries = buildFileEntries(tree, parsedLanguages, overrides);
+	const [rootEntry, ...childEntries] = entries;
+	const crossIssues = collectCrossIssues(rootEntry, childEntries);
+	for (const entry of entries) {
+		printFileBlock(entry, startDir);
+	}
+	return { entries, crossIssues };
+}
+
+function gatherAll({ trees, parsedLanguages, overrides, startDir }) {
+	const allEntries = [];
+	const allCrossIssues = [];
+	for (const tree of trees) {
+		const { entries, crossIssues } = processTree({ tree, parsedLanguages, overrides, startDir });
+		allEntries.push(...entries);
+		allCrossIssues.push(...crossIssues);
+	}
+	return { allEntries, allCrossIssues };
+}
+
+function reportAndExit({ allEntries, allCrossIssues, strict, startDir }) {
+	printCrossFileBlock(allCrossIssues, startDir);
+	const summary = formatGlobalSummary({ entries: allEntries, crossIssues: allCrossIssues, strict });
+	logger.log(summary.line);
+	if (summary.failed) {
+		process.exitCode = 1;
+	}
+}
+
+export function runCheckRecursive({ startDir: rawStart, parsedLanguages, strict, overrides }) {
+	const startDir = resolveStartDir(rawStart);
+	const paths = discoverEditorConfigs(startDir);
+	if (paths.length === 0) {
+		logger.log(`No .editorconfig files found under ${startDir}`);
+		return;
+	}
+	const { allEntries, allCrossIssues } = gatherAll({
+		trees: classify(paths),
+		parsedLanguages,
+		overrides,
+		startDir,
+	});
+	reportAndExit({ allEntries, allCrossIssues, strict, startDir });
+}

package/src/check.js

@@ -18,6 +18,7 @@ const STATUS_GLYPH = {
 	mismatch: '❌',
 	missing: '❌',
 	'no-root': '❌',
+	'child-root-forbidden': '❌',
 	unknown: '⚠️ ',
 };
 
@@ -26,9 +27,12 @@ const STATUS_DETAIL = {
 	mismatch: 'section body does not match',
 	missing: 'missing',
 	'no-root': "missing 'root = true' before sections",
+	'child-root-forbidden': "child file must not declare 'root = true'",
 	unknown: 'unknown header (not validated)',
 };
 
+const FAILING_STATUSES = new Set(['mismatch', 'missing', 'no-root', 'child-root-forbidden']);
+
 function languageForHeader(header) {
 	if (header === BASE_SECTION_HEADER) {
 		return 'base';
@@ -36,11 +40,14 @@ function languageForHeader(header) {
 	return headerToLanguage(header);
 }
 
-function checkSection(section, overrides) {
+function checkSection(section, overrides, role) {
 	const language = languageForHeader(section.header);
 	if (!language) {
 		return { header: section.header, status: 'unknown' };
 	}
+	if (role === 'child') {
+		return { header: section.header, status: 'match' };
+	}
 	const expected = expectedBodyForLanguage(language, overrides);
 	const { ok } = compareSection(section.body, expected);
 	if (ok) {
@@ -54,8 +61,8 @@ function buildExpectedHeaders(parsedLanguages) {
 	return [BASE_SECTION_HEADER, ...resolved.map((name) => languageToHeader(name))];
 }
 
-function buildResults({ parsedLanguages, parsed, overrides }) {
-	const results = parsed.sections.map((section) => checkSection(section, overrides));
+function buildResults({ parsedLanguages, parsed, overrides, role }) {
+	const results = parsed.sections.map((section) => checkSection(section, overrides, role));
 	if (parsedLanguages !== NO_LANGUAGE_FILTER) {
 		const present = new Set(parsed.sections.map((section) => section.header));
 		const expectedHeaders = buildExpectedHeaders(parsedLanguages);
@@ -68,7 +75,7 @@ function buildResults({ parsedLanguages, parsed, overrides }) {
 	return results;
 }
 
-function buildBaseIssues(parsed) {
+function buildRootBaseIssues(parsed) {
 	const issues = [];
 	const hasBase = parsed.sections.some((section) => section.header === BASE_SECTION_HEADER);
 	if (!hasBase) {
@@ -80,14 +87,47 @@ function buildBaseIssues(parsed) {
 	return issues;
 }
 
-export function compareEditorConfig(path = '.editorconfig', parsedLanguages = NO_LANGUAGE_FILTER, overrides = EMPTY_OVERRIDES) {
+function buildChildBaseIssues(parsed) {
+	if (parsed.hasRoot) {
+		return [{ header: BASE_SECTION_HEADER, status: 'child-root-forbidden' }];
+	}
+	return [];
+}
+
+function buildBaseIssuesForRole(parsed, role) {
+	if (role === 'child') {
+		return buildChildBaseIssues(parsed);
+	}
+	return buildRootBaseIssues(parsed);
+}
+
+export function compareEditorConfigForRole({
+	path,
+	parsedLanguages = NO_LANGUAGE_FILTER,
+	overrides = EMPTY_OVERRIDES,
+	role = 'root',
+}) {
 	if (!existsSync(path)) {
 		throw new Error(`'${path}' does not exist`);
 	}
 	const text = readFileSync(path, 'utf8');
 	const parsed = parseSections(text);
-	const baseIssues = buildBaseIssues(parsed);
-	const results = buildResults({ parsedLanguages, parsed, overrides });
+	const baseIssues = buildBaseIssuesForRole(parsed, role);
+	let effectiveLanguages = parsedLanguages;
+	if (role === 'child') {
+		effectiveLanguages = NO_LANGUAGE_FILTER;
+	}
+	const results = buildResults({ parsedLanguages: effectiveLanguages, parsed, overrides, role });
+	return { baseIssues, results, parsed };
+}
+
+export function compareEditorConfig(path = '.editorconfig', parsedLanguages = NO_LANGUAGE_FILTER, overrides = EMPTY_OVERRIDES) {
+	const { baseIssues, results } = compareEditorConfigForRole({
+		path,
+		parsedLanguages,
+		overrides,
+		role: 'root',
+	});
 	return { baseIssues, results };
 }
 
@@ -101,15 +141,20 @@ function formatLine({ header, status }) {
 }
 
 export function reportIsFailing({ baseIssues, results }, strict) {
-	const failing = [...baseIssues, ...results].some((entry) =>
-		entry.status === 'mismatch' || entry.status === 'missing' || entry.status === 'no-root',
-	);
+	const failing = [...baseIssues, ...results].some((entry) => FAILING_STATUSES.has(entry.status));
 	const hasUnknown = results.some((entry) => entry.status === 'unknown');
 	return failing || (strict && hasUnknown);
 }
 
-function printReport(path, report) {
-	logger.log(`Checking ${path}`);
+function buildHeading(displayPath, label) {
+	if (label) {
+		return `Checking ${displayPath} ${label}`;
+	}
+	return `Checking ${displayPath}`;
+}
+
+export function printReport(displayPath, report, { label } = {}) {
+	logger.log(buildHeading(displayPath, label));
 	logger.log('');
 	for (const issue of report.baseIssues) {
 		logger.log(formatLine(issue));
@@ -120,13 +165,11 @@ function printReport(path, report) {
 	logger.log('');
 }
 
-function summarize(report) {
+export function summarizeReport(report) {
 	const lines = [...report.baseIssues, ...report.results];
 	const total = lines.length;
 	const matched = lines.filter((entry) => entry.status === 'match').length;
-	const failed = lines.filter((entry) =>
-		entry.status === 'mismatch' || entry.status === 'missing' || entry.status === 'no-root',
-	).length;
+	const failed = lines.filter((entry) => FAILING_STATUSES.has(entry.status)).length;
 	const unknown = lines.filter((entry) => entry.status === 'unknown').length;
 	return { total, matched, failed, unknown };
 }
@@ -158,7 +201,7 @@ function formatPassSummary({ matched, unknown }) {
 }
 
 function formatSummary(report, isFailure) {
-	const counts = summarize(report);
+	const counts = summarizeReport(report);
 	if (isFailure) {
 		return formatFailureSummary(counts);
 	}

package/src/cli/dispatch.js

@@ -0,0 +1,99 @@
+import { EMPTY_OVERRIDES } from '../templates/index.js';
+import { loadCustomTemplate } from '../templates/custom-template.js';
+import { NO_LANGUAGE_FILTER, runCheck } from '../check.js';
+import { runCheckRecursive } from '../check-recursive.js';
+import { logger } from '../utils/logger.js';
+import { NOT_PROVIDED, parseLanguages } from './options.js';
+import { runWrite } from './write-flow.js';
+
+const OVERRIDES_FAILED = Symbol('overrides-failed');
+
+async function resolveOverrides(templateValue) {
+	if (typeof templateValue !== 'string') {
+		return EMPTY_OVERRIDES;
+	}
+	try {
+		return await loadCustomTemplate(templateValue);
+	}
+	catch (error) {
+		logger.error(error.message);
+		process.exitCode = 1;
+		return OVERRIDES_FAILED;
+	}
+}
+
+function resolveCheckPath(values) {
+	if (typeof values.path === 'string' && values.path.length > 0) {
+		return values.path;
+	}
+	if (values.recursive) {
+		return process.cwd();
+	}
+	return '.editorconfig';
+}
+
+function dispatchCheck({ path, languages, strict, overrides, recursive }) {
+	let filter = languages;
+	if (filter === NOT_PROVIDED) {
+		filter = NO_LANGUAGE_FILTER;
+	}
+	try {
+		if (recursive) {
+			runCheckRecursive({ startDir: path, parsedLanguages: filter, strict, overrides });
+			return;
+		}
+		runCheck({ path, parsedLanguages: filter, strict, overrides });
+	}
+	catch (error) {
+		logger.error(error.message);
+		process.exitCode = 1;
+	}
+}
+
+async function dispatchWrite({ path, overwrite, languages, overrides }) {
+	try {
+		await runWrite({ path, overwrite, parsedLanguages: languages, overrides });
+	}
+	catch (error) {
+		logger.error(error.message);
+		process.exitCode = 1;
+	}
+}
+
+async function handleWrite({ path, overwrite, languages, overrides, recursive }) {
+	if (recursive) {
+		logger.error('--recursive (-r) is only supported with --mode=check');
+		process.exitCode = 1;
+		return;
+	}
+	await dispatchWrite({ path, overwrite, languages, overrides });
+}
+
+async function runCommand({ mode, path, overwrite, languages, strict, overrides, recursive }) {
+	if (mode === 'write') {
+		await handleWrite({ path, overwrite, languages, overrides, recursive });
+		return;
+	}
+	if (mode === 'check') {
+		dispatchCheck({ path, languages, strict, overrides, recursive });
+		return;
+	}
+	logger.error('invalid command');
+	process.exitCode = 1;
+}
+
+export async function dispatchValues(values) {
+	const overrides = await resolveOverrides(values.template);
+	if (overrides === OVERRIDES_FAILED) {
+		return;
+	}
+	await runCommand({
+		mode: values.mode,
+		path: resolveCheckPath(values),
+		overwrite: values.overwrite,
+		languages: parseLanguages(values.languages),
+		strict: values.strict,
+		overrides,
+		recursive: Boolean(values.recursive),
+	});
+}

package/src/cli/options.js

@@ -0,0 +1,89 @@
+import { parseArgs } from 'node:util';
+import {
+	ALIASES,
+	AVAILABLE_LANGUAGES,
+} from '../templates/index.js';
+import { logger } from '../utils/logger.js';
+
+export const options = {
+	mode: { type: 'string', short: 'm' },
+	path: { type: 'string', short: 'p' },
+	languages: { type: 'string', short: 'l' },
+	help: { type: 'boolean', short: 'h' },
+	overwrite: { type: 'boolean', short: 'o' },
+	strict: { type: 'boolean', short: 's' },
+	template: { type: 'string', short: 't' },
+	recursive: { type: 'boolean', short: 'r' },
+};
+
+export const NOT_PROVIDED = Symbol('languages-not-provided');
+
+export function parseLanguages(raw) {
+	if (typeof raw !== 'string') {
+		return NOT_PROVIDED;
+	}
+	return raw
+		.split(',')
+		.map((token) => token.trim().toLowerCase())
+		.filter((token) => token.length > 0);
+}
+
+function formatAliasList() {
+	const grouped = new Map();
+	for (const [alias, target] of Object.entries(ALIASES)) {
+		const list = grouped.get(target) ?? [];
+		list.push(alias);
+		grouped.set(target, list);
+	}
+	return [...grouped.entries()]
+		.map(([target, aliases]) => `${aliases.join(', ')} -> ${target}`)
+		.join('; ');
+}
+
+export function printHelp() {
+	logger.log(`Usage: editorconfig --mode=<command> [--path=<path>] [--languages=<list>] [--template=<path|url>] [--recursive]
+
+Commands:
+  write    Create a .editorconfig file with the selected language sections
+  check    Validate per-section against the canonical templates
+
+Options:
+  -m, --mode       Command to run (write | check)
+  -p, --path       Path to the .editorconfig file, or start directory when used with --recursive (default: .editorconfig / cwd)
+  -l, --languages  Comma-separated language sections (write: which to emit; check: required set; recursive: enforced on root only)
+  -o, --overwrite  Overwrite an existing .editorconfig without confirmation
+  -s, --strict     Treat unknown section headers as failures (check only)
+  -t, --template   Path or https URL to a custom .editorconfig-syntax file whose sections override the built-in ones
+  -r, --recursive  Check only. Walk the start directory and validate every .editorconfig (root + children) with cascade checks
+  -h, --help       Show this help message
+
+Languages: ${AVAILABLE_LANGUAGES.join(', ')}
+Aliases:   ${formatAliasList()}
+
+Examples:
+  editorconfig --mode=write --languages=js,md
+  editorconfig --mode=write                       # interactive in TTY, base only otherwise
+  editorconfig --mode=check --languages=js,md    # require exactly base + js + md
+  editorconfig --mode=check --strict             # fail on any unknown section header
+  editorconfig --mode=check --recursive          # validate every .editorconfig under cwd (monorepo)
+  editorconfig --mode=check --template=./team.editorconfig
+  editorconfig --mode=check --template=https://team.example.com/.editorconfig`);
+};
+
+function formatCliError(error) {
+	if (error.code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION') {
+		return `${error.message.split('.')[0]}. See --help.`;
+	}
+	return error.message;
+}
+
+export function parseCliArgs(args) {
+	try {
+		return parseArgs({ args, options });
+	}
+	catch (error) {
+		logger.error(formatCliError(error));
+		process.exitCode = 1;
+		return false;
+	}
+}

package/src/cli/write-flow.js

@@ -0,0 +1,85 @@
+import { existsSync, writeFileSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import {
+	AVAILABLE_LANGUAGES,
+	composeEditorConfig,
+	EMPTY_OVERRIDES,
+} from '../templates/index.js';
+import { logger } from '../utils/logger.js';
+import { NOT_PROVIDED } from './options.js';
+
+export function createEditorConfig(path = '.editorconfig', languages = [], overrides = EMPTY_OVERRIDES) {
+	writeFileSync(path, composeEditorConfig(languages, overrides), 'utf8');
+};
+
+function resolvePromptAnswer(answer) {
+	const tokens = answer
+		.split(',')
+		.map((token) => token.trim().toLowerCase())
+		.filter((token) => token.length > 0);
+	return tokens.map((token) => {
+		const asNumber = Number.parseInt(token, 10);
+		if (Number.isInteger(asNumber) && asNumber >= 1 && asNumber <= AVAILABLE_LANGUAGES.length) {
+			return AVAILABLE_LANGUAGES[asNumber - 1];
+		}
+		return token;
+	});
+}
+
+function promptLanguages() {
+	return new Promise((resolve) => {
+		const rl = createInterface({ input: process.stdin, output: process.stdout });
+		const numbered = AVAILABLE_LANGUAGES
+			.map((name, index) => `  ${index + 1}. ${name}`)
+			.join('\n');
+		logger.log(`Available language sections:\n${numbered}`);
+		rl.question('Languages? [comma-separated names or indices, blank=base only] ', (answer) => {
+			rl.close();
+			resolve(resolvePromptAnswer(answer));
+		});
+	});
+}
+
+function resolveLanguages(parsedLanguages) {
+	if (parsedLanguages !== NOT_PROVIDED) {
+		return Promise.resolve(parsedLanguages);
+	}
+	if (process.stdin.isTTY) {
+		return promptLanguages();
+	}
+	return Promise.resolve([]);
+}
+
+function confirmOverwrite(path) {
+	return new Promise((resolve) => {
+		const rl = createInterface({ input: process.stdin, output: process.stdout });
+		rl.question(`\`${path}\` already exists. Overwrite? [y/N] `, (answer) => {
+			rl.close();
+			resolve(/^y(es)?$/iu.test(answer.trim()));
+		});
+	});
+}
+
+async function handleExistingTarget(path, languages, overrides) {
+	if (!process.stdin.isTTY) {
+		logger.error(`\`${path}\` already exists. Use --overwrite to replace it.`);
+		process.exitCode = 1;
+		return;
+	}
+	const confirmed = await confirmOverwrite(path);
+	if (confirmed) {
+		createEditorConfig(path, languages, overrides);
+	}
+	else {
+		logger.log(`Skipped: \`${path}\` was not modified.`);
+	}
+}
+
+export async function runWrite({ path, overwrite, parsedLanguages, overrides }) {
+	const languages = await resolveLanguages(parsedLanguages);
+	if (!existsSync(path) || overwrite) {
+		createEditorConfig(path, languages, overrides);
+		return;
+	}
+	await handleExistingTarget(path, languages, overrides);
+}

package/src/discover.js

@@ -0,0 +1,66 @@
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { logger } from './utils/logger.js';
+
+export const IGNORED_DIRS = new Set([
+	'node_modules',
+	'.git',
+	'dist',
+	'build',
+	'coverage',
+	'.next',
+	'.cache',
+]);
+
+const EDITORCONFIG_NAME = '.editorconfig';
+
+function readDir(dir) {
+	try {
+		return readdirSync(dir, { withFileTypes: true });
+	}
+	catch (error) {
+		if (error.code === 'EACCES' || error.code === 'EPERM') {
+			logger.warn(`Skipping unreadable directory: ${dir}`);
+			return [];
+		}
+		throw error;
+	}
+}
+
+function classifyEntry(entry) {
+	if (entry.isSymbolicLink()) {
+		return 'skip';
+	}
+	if (entry.isDirectory()) {
+		if (IGNORED_DIRS.has(entry.name)) {
+			return 'skip';
+		}
+		return 'descend';
+	}
+	if (entry.isFile() && entry.name === EDITORCONFIG_NAME) {
+		return 'collect';
+	}
+	return 'skip';
+}
+
+function processDir(dir, stack, found) {
+	for (const entry of readDir(dir)) {
+		const full = join(dir, entry.name);
+		const action = classifyEntry(entry);
+		if (action === 'descend') {
+			stack.push(full);
+		}
+		else if (action === 'collect') {
+			found.push(full);
+		}
+	}
+}
+
+export function discoverEditorConfigs(startDir) {
+	const found = [];
+	const stack = [startDir];
+	while (stack.length > 0) {
+		processDir(stack.pop(), stack, found);
+	}
+	return found.toSorted();
+}