@sheplu/editorconfig 0.8.7 → 0.10.0

package/README.md

@@ -4,8 +4,8 @@ A small CLI to manage a **consistent `.editorconfig`** across your projects.
 
 - ✅ Generate a sane default `.editorconfig` in seconds
 - ✅ Check if your existing file matches the target setup
-- 🔜 Propose updates (with confirmation) instead of blindly overwriting
-- 🔜 Compare your file against the recommended template
+- ✅ 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)
 
 ## Why?
 
@@ -49,8 +49,8 @@ npx @sheplu/editorconfig --mode=write
 This will:
 
 - Create a `.editorconfig` file if it doesn’t exist
-- (Current behavior) Write the default template
-- (Future behavior) Ask before overwriting an existing file
+- Write the default template
+- Ask before overwriting an existing file (or fail in non-interactive contexts unless `--overwrite` is passed)
 
 ## Current Features
 
@@ -62,6 +62,23 @@ npx @sheplu/editorconfig --mode=write
 
 Creates a base `.editorconfig` file in the current directory.
 
+If a `.editorconfig` already exists at the target path, the CLI will:
+
+- Prompt for confirmation in an interactive terminal (`y` / `yes` to overwrite, anything else keeps the file).
+- Exit non-zero in non-interactive contexts (CI, redirected stdin) so a script never silently destroys an existing config.
+
+Pass `--overwrite` (or `-o`) to bypass the prompt and force a rewrite:
+
+```bash
+npx @sheplu/editorconfig --mode=write --overwrite
+```
+
+You can also point at a custom path:
+
+```bash
+npx @sheplu/editorconfig --mode=write --path=path/to/.editorconfig
+```
+
 Typical content (example):
 
 ```ini
@@ -96,6 +113,36 @@ This command will:
   - `0` if everything matches
   - `1` if differences are found
 
+### `--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.
+
+The flag accepts either a local path or an `https://` URL:
+
+```bash
+# local file
+npx @sheplu/editorconfig --mode=write --template=./team.editorconfig
+
+# remote URL
+npx @sheplu/editorconfig --mode=check --template=https://raw.githubusercontent.com/example/team-config/main/.editorconfig
+```
+
+The custom template must follow the same semantics as the built-ins:
+
+- Use only known section headers (`[*]`, `[*.md]`, `[*.{js,jsx,...}]`, etc.). Unknown headers (like `[*.proto]`) are rejected.
+- Include `root = true` in the preamble whenever the template redefines `[*]`.
+- Each header may appear at most once.
+
+URL fetching is constrained for safety: `https://` only (`http://` is rejected before any network call), redirects must stay on https (max 5 hops), 10-second timeout, 1 MB response cap. Templates are fetched on every invocation — there is no local cache.
+
+### `--help`
+
+```bash
+npx @sheplu/editorconfig --help
+```
+
+Prints the full usage, the available commands, and every supported option.
+
 ## Planned / Upcoming Features
 
 ### 1. Interactive update / replace
@@ -115,10 +162,27 @@ npx @sheplu/editorconfig --mode=diff
 - [ ] Add diff logic and `diff` command
 - [ ] Add interactive `fix` / `update` command
 - [ ] Expose presets or configuration options
-- [ ] Add tests and CI examples
 
 Additional properties can be found on the [editorconfig wiki](https://github.com/editorconfig/editorconfig/wiki/editorconfig-properties).
 
+## Tests
+
+Tests live under `test/` and are split by scope:
+
+- `test/unit/` — fast, in-process tests of exported functions (no spawning, no I/O beyond a tmp dir).
+- `test/integration/` — full CLI runs. The interactive prompt path is exercised in a real pseudoterminal via [`node-pty`](https://github.com/microsoft/node-pty); the rest go through `child_process.spawnSync` with a closed stdin.
+
+Run them with:
+
+```bash
+npm test                  # everything
+npm run test:unit         # unit only — runs in ~50ms
+npm run test:integration  # integration only — spawns the CLI
+npm run lint              # oxlint
+```
+
+CI runs lint, audit, and the full suite on every PR across Node 24 / 26.
+
 ## Documentation
 
 [Editorconfig documentation](https://github.com/editorconfig/editorconfig/wiki/editorconfig-properties)

package/index.js

@@ -1,60 +1,286 @@
 #!/usr/bin/env node
 
-import { readFileSync, writeFileSync } from "node:fs";
+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';
 
-const editorconfigContent = `root = true
-
-[*]
-indent_style = tab
-indent_size = 4
-tab_width = 4
-end_of_line = lf
-charset = utf-8
-spelling_language = en
-trim_trailing_whitespace = true
-insert_final_newline = true
-quote_type = single
-spaces_around_operators = true
-`;
-
-export function createEditorConfig(path = '.editorconfig') {
-	writeFileSync(path, editorconfigContent, 'utf8');
+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 function compareEditorConfig(path = '.editorconfig') {
-	const file = readFileSync(path).toString();
-	if (editorconfigContent === file) {
-		console.log('✅ Editorconfig is matching the expected configuration')
+export const NOT_PROVIDED = Symbol('languages-not-provided');
+
+export function parseLanguages(raw) {
+	if (typeof raw !== 'string') {
+		return NOT_PROVIDED;
 	}
-	else {
-		console.log('❌ Editorconfig is not matching the expected configuration');
+	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 main() {
-	const args = process.argv.slice(2);
-	const options = {
-		mode: {
-			type: 'string',
-			short: 'm',
-		},
-		path: {
-			type: 'string',
-			short: 'p',
-		},
-	};
-	const { values } = parseArgs({ args, options });
-	const path = values.path || '.editorconfig'
-	if (values.mode === 'write') {
-		createEditorConfig(path);
-	}
-	else if (values.mode === 'check') {
-		compareEditorConfig(path);
+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 {
-		console.error('invalid commande');
+		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,
+	});
+}
+
+async function main() {
+	const parsed = parseCliArgs(process.argv.slice(2));
+	if (!parsed) {
+		return;
+	}
+	if (parsed.values.help) {
+		printHelp();
+		return;
+	}
+	await dispatchValues(parsed.values);
 };
 
-main();
+if (process.argv[1] === import.meta.filename) {
+	try {
+		await main();
+	}
+	catch (error) {
+		logger.error(error.message);
+		process.exitCode = 1;
+	}
+}

package/package.json

@@ -1,10 +1,17 @@
 {
 	"name": "@sheplu/editorconfig",
-	"version": "0.8.7",
+	"version": "0.10.0",
 	"description": "",
 	"main": "index.js",
+	"files": [
+		"index.js",
+		"src/"
+	],
 	"scripts": {
-		"test": "echo \"Error: no test specified\" && exit 1"
+		"lint": "oxlint",
+		"test": "node --test",
+		"test:unit": "node --test 'test/unit/*.test.js'",
+		"test:integration": "node --test 'test/integration/*.test.js'"
 	},
 	"bin": {
 		"@sheplu/editorconfig": "index.js"
@@ -24,8 +31,15 @@
 	"author": "Jean Burellier",
 	"license": "MIT",
 	"type": "module",
+	"engines": {
+		"node": ">=24"
+	},
 	"bugs": {
 		"url": "https://github.com/sheplu/editorconfig/issues"
 	},
-	"homepage": "https://github.com/sheplu/editorconfig#readme"
+	"homepage": "https://github.com/sheplu/editorconfig#readme",
+	"devDependencies": {
+		"node-pty": "1.0.0",
+		"oxlint": "^1.65.0"
+	}
 }

package/src/check.js

@@ -0,0 +1,176 @@
+import { existsSync, readFileSync } from 'node:fs';
+import {
+	BASE_SECTION_HEADER,
+	compareSection,
+	EMPTY_OVERRIDES,
+	expectedBodyForLanguage,
+	headerToLanguage,
+	languageToHeader,
+	parseSections,
+	resolveLanguageNames,
+} from './templates/index.js';
+import { logger } from './utils/logger.js';
+
+export const NO_LANGUAGE_FILTER = Symbol('check-no-language-filter');
+
+const STATUS_GLYPH = {
+	match: '✅',
+	mismatch: '❌',
+	missing: '❌',
+	'no-root': '❌',
+	unknown: '⚠️ ',
+};
+
+const STATUS_DETAIL = {
+	match: '',
+	mismatch: 'section body does not match',
+	missing: 'missing',
+	'no-root': "missing 'root = true' before sections",
+	unknown: 'unknown header (not validated)',
+};
+
+function languageForHeader(header) {
+	if (header === BASE_SECTION_HEADER) {
+		return 'base';
+	}
+	return headerToLanguage(header);
+}
+
+function checkSection(section, overrides) {
+	const language = languageForHeader(section.header);
+	if (!language) {
+		return { header: section.header, status: 'unknown' };
+	}
+	const expected = expectedBodyForLanguage(language, overrides);
+	const { ok } = compareSection(section.body, expected);
+	if (ok) {
+		return { header: section.header, status: 'match' };
+	}
+	return { header: section.header, status: 'mismatch' };
+}
+
+function buildExpectedHeaders(parsedLanguages) {
+	const resolved = resolveLanguageNames(parsedLanguages);
+	return [BASE_SECTION_HEADER, ...resolved.map((name) => languageToHeader(name))];
+}
+
+function buildResults({ parsedLanguages, parsed, overrides }) {
+	const results = parsed.sections.map((section) => checkSection(section, overrides));
+	if (parsedLanguages !== NO_LANGUAGE_FILTER) {
+		const present = new Set(parsed.sections.map((section) => section.header));
+		const expectedHeaders = buildExpectedHeaders(parsedLanguages);
+		for (const header of expectedHeaders) {
+			if (!present.has(header)) {
+				results.push({ header, status: 'missing' });
+			}
+		}
+	}
+	return results;
+}
+
+function buildBaseIssues(parsed) {
+	const issues = [];
+	const hasBase = parsed.sections.some((section) => section.header === BASE_SECTION_HEADER);
+	if (!hasBase) {
+		issues.push({ header: BASE_SECTION_HEADER, status: 'missing' });
+	}
+	else if (!parsed.hasRoot) {
+		issues.push({ header: BASE_SECTION_HEADER, status: 'no-root' });
+	}
+	return issues;
+}
+
+export function compareEditorConfig(path = '.editorconfig', parsedLanguages = NO_LANGUAGE_FILTER, overrides = EMPTY_OVERRIDES) {
+	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 });
+	return { baseIssues, results };
+}
+
+function formatLine({ header, status }) {
+	const glyph = STATUS_GLYPH[status];
+	const detail = STATUS_DETAIL[status];
+	if (detail) {
+		return `  ${glyph} ${header} ${detail}`;
+	}
+	return `  ${glyph} ${header}`;
+}
+
+export function reportIsFailing({ baseIssues, results }, strict) {
+	const failing = [...baseIssues, ...results].some((entry) =>
+		entry.status === 'mismatch' || entry.status === 'missing' || entry.status === 'no-root',
+	);
+	const hasUnknown = results.some((entry) => entry.status === 'unknown');
+	return failing || (strict && hasUnknown);
+}
+
+function printReport(path, report) {
+	logger.log(`Checking ${path}`);
+	logger.log('');
+	for (const issue of report.baseIssues) {
+		logger.log(formatLine(issue));
+	}
+	for (const entry of report.results) {
+		logger.log(formatLine(entry));
+	}
+	logger.log('');
+}
+
+function summarize(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 unknown = lines.filter((entry) => entry.status === 'unknown').length;
+	return { total, matched, failed, unknown };
+}
+
+function pluralize(count, singular) {
+	if (count === 1) {
+		return singular;
+	}
+	return `${singular}s`;
+}
+
+function formatFailureSummary({ total, failed, unknown }) {
+	const reasons = [];
+	if (failed > 0) {
+		reasons.push(`${failed} of ${total} ${pluralize(total, 'section')} did not match`);
+	}
+	if (unknown > 0) {
+		reasons.push(`${unknown} unknown ${pluralize(unknown, 'header')}`);
+	}
+	return `❌ FAIL — ${reasons.join('; ')}`;
+}
+
+function formatPassSummary({ matched, unknown }) {
+	const matchedLabel = `${matched} ${pluralize(matched, 'section')} matched`;
+	if (unknown > 0) {
+		return `✅ PASS — ${matchedLabel} (${unknown} unknown ${pluralize(unknown, 'header')} ignored)`;
+	}
+	return `✅ PASS — ${matchedLabel}`;
+}
+
+function formatSummary(report, isFailure) {
+	const counts = summarize(report);
+	if (isFailure) {
+		return formatFailureSummary(counts);
+	}
+	return formatPassSummary(counts);
+}
+
+export function runCheck({ path, parsedLanguages, strict, overrides }) {
+	const report = compareEditorConfig(path, parsedLanguages, overrides);
+	printReport(path, report);
+	const failed = reportIsFailing(report, strict);
+	logger.log(formatSummary(report, failed));
+	if (failed) {
+		process.exitCode = 1;
+	}
+}

package/{.editorconfig → src/templates/base.js}

@@ -1,4 +1,4 @@
-root = true
+export const base = `root = true
 
 [*]
 indent_style = tab
@@ -11,3 +11,4 @@ trim_trailing_whitespace = true
 insert_final_newline = true
 quote_type = single
 spaces_around_operators = true
+`;

package/src/templates/css.js

@@ -0,0 +1,4 @@
+export const css = `[*.{css,scss,sass,less}]
+indent_style = space
+indent_size = 2
+`;