@useinsider/eslint-config 4.0.0-beta.1 → 4.0.0-beta.3

package/dist/main.cjs

@@ -10,6 +10,7 @@ let node_module = require("node:module");
 let node_path = require("node:path");
 let node_url = require("node:url");
 let _typescript_eslint_types = require("@typescript-eslint/types");
+let node_child_process = require("node:child_process");
 let _antfu_install_pkg = require("@antfu/install-pkg");
 let semver = require("semver");
 semver = require_oxlintOwnership.__toESM(semver, 1);
@@ -212,14 +213,7 @@ function buildOxlintConfig(blocks, ignores) {
 	};
 }
 //#endregion
-//#region src/utils/ensureConfigStructure.ts
-var ANCHOR_FILE_REGEX = /(?:insider\.lint|eslint\.config)\.[mc]?[jt]s(?:$|\?)/;
-var OPT_OUT_ENV$1 = "INSIDER_SKIP_CONFIG_VALIDATION";
-var FILE_URL_PREFIX = "file://";
-var TARGET_CALLEE_NAME = "useInsider";
-var ESLINT_RENDERER_NAME = "useInsiderESLint";
-var OXC_RENDERER_NAME = "useInsiderOXC";
-var INSIDER_IMPORT_SOURCE = "@useinsider/eslint-config";
+//#region src/utils/layoutDiagnosis.ts
 var MODULE_EXTENSIONS = [
 	"ts",
 	"mts",
@@ -228,9 +222,332 @@ var MODULE_EXTENSIONS = [
 	"mjs",
 	"cjs"
 ];
-var RENDERER_EXPORT = `export const ${`{ ${ESLINT_RENDERER_NAME}, ${OXC_RENDERER_NAME} }`} = ${TARGET_CALLEE_NAME}({ ... })`;
 var LINT_MODULE_FILENAMES = MODULE_EXTENSIONS.map((ext) => `insider.lint.${ext}`);
 var ESLINT_CONFIG_FILENAMES = MODULE_EXTENSIONS.map((ext) => `eslint.config.${ext}`);
+var OXLINT_CONFIG_FILENAMES = ["oxlint.config.ts", "oxlint.config.mts"];
+var OPT_OUT_ENV = "INSIDER_SKIP_CONFIG_VALIDATION";
+var MIGRATE_COMMAND = "npx @useinsider/eslint-config migrate";
+var SCAFFOLD_COMMAND = "npx @useinsider/eslint-config";
+var INSIDER_IMPORT_SOURCE = "@useinsider/eslint-config";
+var TARGET_CALLEE_NAME = "useInsider";
+var ESLINT_RENDERER_NAME = "useInsiderESLint";
+var OXC_RENDERER_NAME = "useInsiderOXC";
+var RENDERER_EXPORT = `export const ${`{ ${ESLINT_RENDERER_NAME}, ${OXC_RENDERER_NAME} }`} = ${TARGET_CALLEE_NAME}({ ... })`;
+var EXPECTED_LAYOUT = [
+	"Expected layout (three sibling files):",
+	"",
+	"  // insider.lint.ts",
+	`  import { ${TARGET_CALLEE_NAME} } from '${INSIDER_IMPORT_SOURCE}';`,
+	"",
+	`  ${RENDERER_EXPORT};`,
+	"",
+	"  // eslint.config.ts",
+	`  import { ${ESLINT_RENDERER_NAME} } from './insider.lint.ts';`,
+	"",
+	`  export default ${ESLINT_RENDERER_NAME}();`,
+	"",
+	"  // oxlint.config.ts",
+	`  import { ${OXC_RENDERER_NAME} } from './insider.lint.ts';`,
+	"",
+	`  export default await ${OXC_RENDERER_NAME}();`
+].join("\n");
+function findSibling(directory, filenames, fileExists) {
+	return filenames.find((filename) => fileExists((0, node_path.join)(directory, filename))) ?? null;
+}
+var lazyRequire$1 = (0, node_module.createRequire)({}.url);
+function parseProgram(source) {
+	try {
+		const { parse } = lazyRequire$1("@typescript-eslint/parser");
+		return parse(source, {
+			sourceType: "module",
+			range: true,
+			loc: true
+		});
+	} catch {
+		return null;
+	}
+}
+function collectUseInsiderAliases(program) {
+	const aliases = /* @__PURE__ */ new Set();
+	program.body.forEach((node) => {
+		if (node.type !== _typescript_eslint_types.AST_NODE_TYPES.ImportDeclaration) return;
+		node.specifiers.forEach((specifier) => {
+			if (specifier.type === _typescript_eslint_types.AST_NODE_TYPES.ImportSpecifier && specifier.imported.type === _typescript_eslint_types.AST_NODE_TYPES.Identifier && specifier.imported.name === "useInsider") aliases.add(specifier.local.name);
+		});
+	});
+	return aliases;
+}
+function callsAny(node, aliases) {
+	if (!node || typeof node !== "object") return false;
+	if (Array.isArray(node)) return node.some((child) => callsAny(child, aliases));
+	const candidate = node;
+	if (candidate.type === _typescript_eslint_types.AST_NODE_TYPES.CallExpression) {
+		const { callee } = candidate;
+		if (callee.type === _typescript_eslint_types.AST_NODE_TYPES.Identifier && aliases.has(callee.name)) return true;
+	}
+	return Object.entries(node).some(([key, value]) => key !== "parent" && callsAny(value, aliases));
+}
+/**
+* Whether a flat-config source is still the removed v3 shape: it imports `useInsider` and calls it
+* itself, instead of importing a renderer from a sibling `insider.lint.*` module. Both the plain
+* `export default useInsider({...})` form and the spread form are recognized.
+* @example
+* isV3EslintConfigSource("import { useInsider } from '@useinsider/eslint-config';\nexport default useInsider({});");
+* // true
+*/
+function isV3EslintConfigSource(source) {
+	const program = parseProgram(source);
+	if (!program) return false;
+	const aliases = collectUseInsiderAliases(program);
+	if (aliases.size === 0) return false;
+	return program.body.some((node) => callsAny(node, aliases));
+}
+function classify(lintModule, eslintConfig, oxlintConfig, eslintConfigIsV3) {
+	if (lintModule && eslintConfig && oxlintConfig) return "complete";
+	if (!lintModule && !eslintConfig && !oxlintConfig) return "noConfig";
+	if (!lintModule && eslintConfig && eslintConfigIsV3) return "unmigratedV3";
+	return "partial";
+}
+/**
+* What of the three-file layout is on disk in a directory, and which of the four guidance branches
+* applies. `unmigratedV3` is the only branch the in-lint migration offer acts on, because it is the
+* only one {@link import('../cli/migrate').runMigrate} can actually rewrite.
+* @example
+* diagnoseLayout('/repo').kind; // 'unmigratedV3' when eslint.config.js still calls useInsider()
+*/
+function diagnoseLayout(directory, options = {}) {
+	const fileExists = options.fileExists ?? node_fs.existsSync;
+	const readSource = options.readSource ?? ((path) => (0, node_fs.readFileSync)(path, "utf8"));
+	const lintModule = findSibling(directory, LINT_MODULE_FILENAMES, fileExists);
+	const eslintConfig = findSibling(directory, ESLINT_CONFIG_FILENAMES, fileExists);
+	const oxlintConfig = findSibling(directory, OXLINT_CONFIG_FILENAMES, fileExists);
+	let eslintConfigIsV3 = false;
+	if (eslintConfig && !lintModule) try {
+		eslintConfigIsV3 = isV3EslintConfigSource(readSource((0, node_path.join)(directory, eslintConfig)));
+	} catch {
+		eslintConfigIsV3 = false;
+	}
+	const kind = classify(lintModule, eslintConfig, oxlintConfig, eslintConfigIsV3);
+	return {
+		kind,
+		directory,
+		lintModule,
+		eslintConfig,
+		oxlintConfig,
+		missing: [
+			lintModule ? null : "insider.lint.ts",
+			eslintConfig ? null : "eslint.config.ts",
+			oxlintConfig ? null : "oxlint.config.ts"
+		].filter((name) => name !== null),
+		autoMigratable: kind === "unmigratedV3"
+	};
+}
+/**
+* Import specifier for the consumer's lint module, naming the extension that is actually on disk so
+* the suggested snippet resolves as printed.
+* @example
+* lintModuleSpecifier('/repo'); // './insider.lint.mts' when that is the file present
+*/
+function lintModuleSpecifier(directory, fileExists = node_fs.existsSync) {
+	return `./${findSibling(directory, LINT_MODULE_FILENAMES, fileExists) ?? "insider.lint.ts"}`;
+}
+function inventoryLines(diagnosis) {
+	const v3Note = diagnosis.kind === "unmigratedV3" ? " (still calls `useInsider()` itself)" : "";
+	return [
+		diagnosis.lintModule ? `  present: ${diagnosis.lintModule}` : "  MISSING: insider.lint.{ts,mts}",
+		diagnosis.eslintConfig ? `  present: ${diagnosis.eslintConfig}${v3Note}` : "  MISSING: eslint.config.{ts,mts}",
+		diagnosis.oxlintConfig ? `  present: ${diagnosis.oxlintConfig}` : `  MISSING: ${OXLINT_CONFIG_FILENAMES.join(" or ")}`
+	];
+}
+function guidanceBody(diagnosis) {
+	if (diagnosis.kind === "complete") return [
+		`All three files are already here, so there is nothing to migrate — ${TARGET_CALLEE_NAME}() was`,
+		`reached from somewhere other than ${diagnosis.lintModule ?? LINT_MODULE_FILENAMES[0]}. Only the`,
+		"lint module may call it; the two configs import the renderers it exports."
+	];
+	if (diagnosis.kind === "unmigratedV3") return [
+		"`useInsider()` no longer returns a flat-config array, so the config it is called from has",
+		"to become a module both linters can import. The migration does that rewrite for you:",
+		"",
+		`  ${MIGRATE_COMMAND}`
+	];
+	if (diagnosis.kind === "noConfig") return [
+		"There is no linter configuration here yet. Scaffold the three-file layout:",
+		"",
+		`  ${SCAFFOLD_COMMAND}`
+	];
+	return [
+		`The layout is incomplete — missing ${diagnosis.missing.join(", ")}.`,
+		"Add the missing file, or let the migration regenerate the whole layout:",
+		"",
+		`  ${MIGRATE_COMMAND}`
+	];
+}
+function detailLines(detail) {
+	if (!detail || detail.length === 0) return [];
+	return ["", ...detail];
+}
+/**
+* The consumer-facing failure text: a site-specific headline, then the branch that matches what is
+* on disk, then the layout dump, then the bypass. The command to run always comes before the dump,
+* because a consumer who reads only the first screen still has to be told about `migrate`.
+* @example
+* formatLayoutGuidance({ headline: 'no `insider.lint.*` module found in /repo.', diagnosis });
+*/
+function formatLayoutGuidance(input) {
+	return [
+		`@useinsider/eslint-config: ${input.headline}`,
+		"",
+		...inventoryLines(input.diagnosis),
+		"",
+		...guidanceBody(input.diagnosis),
+		...detailLines(input.detail),
+		"",
+		EXPECTED_LAYOUT,
+		"",
+		`Emergency bypass: set ${OPT_OUT_ENV}=true (do not commit).`
+	].join("\n");
+}
+//#endregion
+//#region src/utils/offerMigration.ts
+var PACKAGE_NAME = "@useinsider/eslint-config";
+var CLI_RELATIVE_PATH = "dist/cli.cjs";
+var NO_PROMPT_ENV = "INSIDER_NO_PROMPT";
+var IN_FLIGHT_ENV = "INSIDER_MIGRATION_IN_PROGRESS";
+var MIGRATE_FROM_LINT_ARGS = ["migrate", "--from-lint"];
+var BINARY_EXTENSIONS = /\.[mc]?js$/u;
+function binaryName(argument) {
+	return (0, node_path.basename)(argument).replace(BINARY_EXTENSIONS, "");
+}
+/**
+* Which linter is hosting the current process. oxlint evaluates `oxlint.config.ts` inside the Node
+* process that runs its own `bin/oxlint` wrapper, so `useInsider()` genuinely executes under both
+* binaries and the two have to be told apart before anything is written to stdout.
+* @example
+* detectLintHost(['node', '/app/node_modules/oxlint/bin/oxlint', '.']); // 'oxlint'
+*/
+function detectLintHost(argv = process.argv) {
+	const names = argv.slice(1).map(binaryName);
+	if (names.includes("oxlint")) return "oxlint";
+	if (names.includes("eslint")) return "eslint";
+	return "unknown";
+}
+function defaultInteractive() {
+	return Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+}
+function skipReasonFor(env, argv, interactive) {
+	if (env[IN_FLIGHT_ENV] === "true") return "already-offered";
+	if (env.VITEST || env.NODE_ENV === "test") return "running-under-test";
+	if (env["INSIDER_SKIP_CONFIG_VALIDATION"] === "true" || env[NO_PROMPT_ENV] === "true") return "suppressed";
+	if (env.CI) return "running-in-ci";
+	if (detectLintHost(argv) === "oxlint") return "host-is-oxlint";
+	if (!interactive) return "no-tty";
+	return null;
+}
+function manifestNameAt(directory) {
+	const manifestPath = (0, node_path.join)(directory, "package.json");
+	if (!(0, node_fs.existsSync)(manifestPath)) return null;
+	try {
+		return JSON.parse((0, node_fs.readFileSync)(manifestPath, "utf8")).name ?? null;
+	} catch {
+		return null;
+	}
+}
+function packageRootFrom(startDir) {
+	let current = startDir;
+	for (let depth = 0; depth < 10; depth += 1) {
+		if (manifestNameAt(current) === PACKAGE_NAME) return current;
+		const parent = (0, node_path.dirname)(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+	return null;
+}
+/**
+* Absolute path to this package's own built CLI, or `null` when it is not on disk. Resolved by
+* walking up from `startDir` — this module's own directory by default — rather than through
+* `require.resolve`, so it works from `dist/` and from `src/` alike.
+* @example
+* resolveCliEntry(); // '/app/node_modules/@useinsider/eslint-config/dist/cli.cjs'
+*/
+function resolveCliEntry(startDir) {
+	const root = packageRootFrom(startDir ?? (0, node_path.dirname)((0, node_url.fileURLToPath)({}.url)));
+	if (!root) return null;
+	const entry = (0, node_path.resolve)(root, CLI_RELATIVE_PATH);
+	return (0, node_fs.existsSync)(entry) ? entry : null;
+}
+function defaultRunCli(entry, args, cwd, env) {
+	const result = (0, node_child_process.spawnSync)(process.execPath, [entry, ...args], {
+		cwd,
+		env,
+		stdio: "inherit"
+	});
+	if (result.error) return 1;
+	return result.status ?? 1;
+}
+function defaultWarn(message) {
+	console.error(message);
+}
+function outdatedNotice(diagnosis) {
+	const config = diagnosis.eslintConfig ?? "eslint.config.*";
+	return [
+		`@useinsider/eslint-config: ${config} still uses the v3 single-file layout.`,
+		`  ${(0, node_path.join)(diagnosis.directory, config)} calls \`useInsider()\` itself, and`,
+		`  ${diagnosis.missing.join(" and ")} ${diagnosis.missing.length === 1 ? "is" : "are"} missing.`,
+		"",
+		"Starting the guided migration. It shows every change before applying it.",
+		`Skip it with ${NO_PROMPT_ENV}=true.`,
+		""
+	].join("\n");
+}
+var offerAttempted = false;
+function withDefaults(deps) {
+	return {
+		env: deps.env ?? process.env,
+		argv: deps.argv ?? process.argv,
+		interactive: deps.interactive ?? defaultInteractive(),
+		resolveCliEntry: deps.resolveCliEntry ?? resolveCliEntry,
+		runCli: deps.runCli ?? defaultRunCli,
+		warn: deps.warn ?? defaultWarn
+	};
+}
+/**
+* Offers the guided migration for an outdated layout and runs it when the consumer accepts. Declines
+* silently — returning a skip reason instead of prompting — whenever writing to stdout would be
+* wrong: under oxlint, in CI, without a TTY, or when already inside a migration.
+* @example
+* offerMigration(diagnoseLayout('/repo')).accepted; // true after the consumer confirmed
+*/
+function offerMigration(diagnosis, deps = {}) {
+	const resolved = withDefaults(deps);
+	if (offerAttempted) return {
+		offered: false,
+		skipReason: "already-offered"
+	};
+	const skipReason = skipReasonFor(resolved.env, resolved.argv, resolved.interactive);
+	if (skipReason) return {
+		offered: false,
+		skipReason
+	};
+	const entry = resolved.resolveCliEntry();
+	if (!entry) return {
+		offered: false,
+		skipReason: "cli-not-found"
+	};
+	offerAttempted = true;
+	resolved.warn(outdatedNotice(diagnosis));
+	return {
+		offered: true,
+		accepted: resolved.runCli(entry, MIGRATE_FROM_LINT_ARGS, diagnosis.directory, {
+			...resolved.env,
+			[IN_FLIGHT_ENV]: "true"
+		}) === 0
+	};
+}
+//#endregion
+//#region src/utils/ensureConfigStructure.ts
+var ANCHOR_FILE_REGEX = /(?:insider\.lint|eslint\.config)\.[mc]?[jt]s(?:$|\?)/;
+var FILE_URL_PREFIX = "file://";
 var bypassWarnEmitted = false;
 function computeSelfModulePath() {
 	const raw = (0, node_url.fileURLToPath)({}.url);
@@ -245,7 +562,7 @@ function isPathSpecifier(source) {
 	return source.startsWith(".") || source.startsWith("/");
 }
 function defaultIsInsiderImportSource(source, configPath) {
-	if (source === INSIDER_IMPORT_SOURCE) return true;
+	if (source === "@useinsider/eslint-config") return true;
 	if (!configPath || !isPathSpecifier(source)) return false;
 	try {
 		const absolute = (0, node_path.resolve)((0, node_path.dirname)(configPath), source);
@@ -341,7 +658,7 @@ function validateProgramStructure(program, configPath = "", options = {}) {
 	const insiderBindings = /* @__PURE__ */ new Set();
 	const resolver = options.isInsiderImportSource ?? defaultIsInsiderImportSource;
 	const isInsiderSource = (source) => resolver(source, configPath);
-	const expectedCallee = options.expectedCallee ?? ESLINT_RENDERER_NAME;
+	const expectedCallee = options.expectedCallee ?? "useInsiderESLint";
 	let exportSeen = false;
 	program.body.forEach((node) => {
 		if (node.type === _typescript_eslint_types.AST_NODE_TYPES.ImportDeclaration) collectInsiderBindings(node, insiderBindings, isInsiderSource);
@@ -357,7 +674,7 @@ function validateProgramStructure(program, configPath = "", options = {}) {
 	if (!exportSeen) violations.push({
 		line: 1,
 		column: 0,
-		reason: `Missing \`export default ${options.expectedCallee ?? ESLINT_RENDERER_NAME}()\`.`
+		reason: `Missing \`export default ${options.expectedCallee ?? "useInsiderESLint"}()\`.`
 	});
 	return violations;
 }
@@ -521,24 +838,6 @@ function captureConsumerConfigDir(configPath) {
 function getConsumerConfigDir() {
 	return consumerConfigDir ?? process.cwd();
 }
-var EXPECTED_LAYOUT = [
-	"Expected layout (three sibling files):",
-	"",
-	"  // insider.lint.ts",
-	"  import { useInsider } from '@useinsider/eslint-config';",
-	"",
-	`  ${RENDERER_EXPORT};`,
-	"",
-	"  // eslint.config.ts",
-	`  import { ${ESLINT_RENDERER_NAME} } from './insider.lint.ts';`,
-	"",
-	`  export default ${ESLINT_RENDERER_NAME}();`,
-	"",
-	"  // oxlint.config.ts",
-	`  import { ${OXC_RENDERER_NAME} } from './insider.lint.ts';`,
-	"",
-	`  export default await ${OXC_RENDERER_NAME}();`
-].join("\n");
 function formatReport(configPath, violations) {
 	const header = ["@useinsider/eslint-config: protected configuration structure violated in:", `  ${configPath}`].join("\n");
 	const lines = violations.map((violation) => `  - [${violation.line}:${violation.column}] ${violation.reason}`);
@@ -549,7 +848,7 @@ function formatReport(configPath, violations) {
 		"",
 		EXPECTED_LAYOUT,
 		"",
-		`Emergency bypass: set ${OPT_OUT_ENV$1}=true (do not commit).`
+		`Emergency bypass: set ${OPT_OUT_ENV}=true (do not commit).`
 	].join("\n");
 	return `${header}\n${lines.join("\n")}\n${footer}`;
 }
@@ -599,46 +898,48 @@ function validateFile(filePath, validator, options) {
 	if (violations.length === 0) return;
 	fail(formatReport(filePath, violations));
 }
-function runValidation(anchorPath) {
-	if (!anchorPath) fail([
-		"@useinsider/eslint-config: unable to locate the consumer `insider.lint.*` module for structure validation.",
-		"",
-		EXPECTED_LAYOUT,
-		"",
-		`If this is an unexpected environment, set ${OPT_OUT_ENV$1}=true (do not commit).`
-	].join("\n"));
+var MIGRATED_EXIT_NOTICE = [
+	"@useinsider/eslint-config: migration finished.",
+	"",
+	"Re-run your lint command. This process already loaded the old configuration, so continuing now",
+	"would lint against a config that no longer exists on disk."
+].join("\n");
+var DECLINED_DETAIL = ["The guided migration was not completed, so nothing was written."];
+function failWithGuidance(headline, diagnosis, detail) {
+	return fail(formatLayoutGuidance({
+		headline,
+		diagnosis,
+		detail
+	}));
+}
+function handleOutdatedLayout(headline, diagnosis, offer) {
+	if (!diagnosis.autoMigratable) return failWithGuidance(headline, diagnosis);
+	const outcome = offer(diagnosis);
+	if (!outcome.offered) return failWithGuidance(headline, diagnosis);
+	if (!outcome.accepted) return failWithGuidance(headline, diagnosis, DECLINED_DETAIL);
+	return fail(MIGRATED_EXIT_NOTICE);
+}
+function runValidation(anchorPath, deps = {}) {
+	const diagnose = deps.diagnose ?? ((directory) => diagnoseLayout(directory));
+	const offer = deps.offer ?? offerMigration;
+	if (!anchorPath) handleOutdatedLayout("unable to locate the consumer `insider.lint.*` module for structure validation.", diagnose(process.cwd()), offer);
 	const directory = (0, node_path.dirname)((0, node_path.resolve)(anchorPath));
 	const lintModulePath = resolveSibling(directory, LINT_MODULE_FILENAMES);
-	if (!lintModulePath) fail([
-		`@useinsider/eslint-config: no \`insider.lint.*\` module found in ${directory}.`,
-		"",
-		`\`${TARGET_CALLEE_NAME}()\` now returns the two renderers instead of a flat-config array,`,
-		"so the config it is called from must be a module both linters can import.",
-		"",
-		EXPECTED_LAYOUT,
-		"",
-		`Emergency bypass: set ${OPT_OUT_ENV$1}=true (do not commit).`
-	].join("\n"));
+	if (!lintModulePath) handleOutdatedLayout(`no \`insider.lint.*\` module found in ${directory}.`, diagnose(directory), offer);
 	validateFile(lintModulePath, validateLintModuleStructure, {});
 	const eslintConfigPath = resolveSibling(directory, ESLINT_CONFIG_FILENAMES);
-	if (!eslintConfigPath) fail([
-		`@useinsider/eslint-config: no \`eslint.config.*\` file found in ${directory}.`,
-		"",
-		EXPECTED_LAYOUT,
-		"",
-		`Emergency bypass: set ${OPT_OUT_ENV$1}=true (do not commit).`
-	].join("\n"));
+	if (!eslintConfigPath) failWithGuidance(`no \`eslint.config.*\` file found in ${directory}.`, diagnose(directory), [`\`${TARGET_CALLEE_NAME}()\` returns renderers, not a flat-config array, so ESLint still`, `needs a config file whose default export is \`${ESLINT_RENDERER_NAME}()\`.`]);
 	validateFile(eslintConfigPath, validateProgramStructure, { expectedCallee: ESLINT_RENDERER_NAME });
 }
-function ensureConfigStructure(overridePath) {
+function ensureConfigStructure(overridePath, deps = {}) {
 	const configPath = overridePath === void 0 ? getConsumerConfigPath() : overridePath;
 	captureConsumerConfigDir(configPath);
-	if (process.env[OPT_OUT_ENV$1] === "true") {
+	if (process.env["INSIDER_SKIP_CONFIG_VALIDATION"] === "true") {
 		emitBypassWarning();
 		return;
 	}
 	try {
-		runValidation(configPath);
+		runValidation(configPath, deps);
 	} catch (error) {
 		if (error instanceof ConfigStructureExit) return;
 		throw error;
@@ -762,6 +1063,14 @@ function clonePreset(preset) {
 function isScopeName(key) {
 	return Object.keys(scopeMap).includes(key);
 }
+/**
+* Every scope name `useInsider()` accepts, for error messages that have to spell the options out.
+* @example
+* scopeNames().includes('typescriptNode'); // true
+*/
+function scopeNames() {
+	return Object.keys(scopeMap);
+}
 function applyCommonEntryFields(block, entry) {
 	if (entry.ignores && entry.ignores.length > 0) block.ignores = [...entry.ignores];
 	if (entry.globals) {
@@ -881,31 +1190,27 @@ function silenceDependencyWarning(input) {
 }
 //#endregion
 //#region src/utils/ensureOxlintConfig.ts
-var OPT_OUT_ENV = "INSIDER_SKIP_CONFIG_VALIDATION";
-var OXLINT_CONFIG_FILENAMES = ["oxlint.config.ts", "oxlint.config.mts"];
-function lintModuleSpecifier(directory) {
-	return `./${LINT_MODULE_FILENAMES.find((filename) => (0, node_fs.existsSync)((0, node_path.join)(directory, filename))) ?? "insider.lint.ts"}`;
-}
 function formatMessage(directory) {
-	return [
-		"@useinsider/eslint-config: no oxlint config found in",
-		`  ${directory}`,
-		"",
-		"useInsiderESLint() turns off every rule oxlint owns, so running ESLint alone would silently",
-		"drop those checks. Create the sibling oxlint config:",
-		"",
-		"  // oxlint.config.ts",
-		`  import { useInsiderOXC } from '${lintModuleSpecifier(directory)}';`,
-		"",
-		"  export default await useInsiderOXC();",
-		"",
-		"and run both linters:",
-		"",
-		"  \"lint\": \"oxlint --disable-nested-config && eslint .\"",
-		"",
-		`Expected one of: ${OXLINT_CONFIG_FILENAMES.join(", ")}.`,
-		`Emergency bypass: set ${OPT_OUT_ENV}=true (do not commit).`
-	].join("\n");
+	return formatLayoutGuidance({
+		headline: `no oxlint config found in ${directory}.`,
+		diagnosis: diagnoseLayout(directory),
+		detail: [
+			"useInsiderESLint() turns off every rule oxlint owns, so running ESLint alone would silently",
+			"drop those checks. Create the sibling oxlint config:",
+			"",
+			"  // oxlint.config.ts",
+			`  import { useInsiderOXC } from '${lintModuleSpecifier(directory)}';`,
+			"",
+			"  export default await useInsiderOXC();",
+			"",
+			"and run both linters:",
+			"",
+			"  \"lint\": \"oxlint --disable-nested-config && eslint .\"",
+			"",
+			`oxlint discovers only ${OXLINT_CONFIG_FILENAMES.join(" and ")} — any other extension is`,
+			"ignored without a word."
+		]
+	});
 }
 /**
 * Fails when the consumer enabled the ESLint-side oxlint suppression without a sibling oxlint
@@ -915,7 +1220,7 @@ function formatMessage(directory) {
 * ensureOxlintConfig(); // throws unless oxlint.config.{ts,mts} sits beside insider.lint.*
 */
 function ensureOxlintConfig(directory = getConsumerConfigDir()) {
-	if (process.env[OPT_OUT_ENV] === "true") return;
+	if (process.env["INSIDER_SKIP_CONFIG_VALIDATION"] === "true") return;
 	if (OXLINT_CONFIG_FILENAMES.some((filename) => (0, node_fs.existsSync)((0, node_path.join)(directory, filename)))) return;
 	throw new Error(formatMessage(directory));
 }
@@ -980,6 +1285,11 @@ function assertNoRemovedKeys(config) {
 	const details = used.map((key) => `  - \`${key}\`: ${removedKeys.get(key)}`).join("\n");
 	throw new Error(`@useinsider/eslint-config: removed option(s) passed to useInsider():\n${details}`);
 }
+function assertNoUnknownKeys(config) {
+	const unknown = Object.keys(config).filter((key) => !reservedKeys.has(key) && !removedKeys.has(key) && !isScopeName(key));
+	if (unknown.length === 0) return;
+	throw new Error(`@useinsider/eslint-config: unknown option(s) passed to useInsider(): ${unknown.join(", ")}.\n  Scopes: ${scopeNames().join(", ")}\n  Other options: ${[...reservedKeys].join(", ")}`);
+}
 function isProcessableScopeKey(key) {
 	return !reservedKeys.has(key) && isScopeName(key);
 }
@@ -1032,6 +1342,7 @@ async function renderOxlint(config) {
 }
 function useInsider(config) {
 	assertNoRemovedKeys(config);
+	assertNoUnknownKeys(config);
 	ensureConfigStructure();
 	return {
 		useInsiderESLint: () => renderEslint(config),