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

package/dist/utils/ensureConfigStructure.d.ts

@@ -1,4 +1,6 @@
 import { type TSESTree } from '@typescript-eslint/types';
+import { ESLINT_CONFIG_FILENAMES, type LayoutDiagnosis, LINT_MODULE_FILENAMES } from './layoutDiagnosis';
+import { offerMigration } from './offerMigration';
 export interface ConfigStructureViolation {
     line: number;
     column: number;
@@ -8,8 +10,7 @@ export interface ValidateProgramStructureOptions {
     isInsiderImportSource?: (source: string, configPath: string) => boolean;
     expectedCallee?: string;
 }
-export declare const LINT_MODULE_FILENAMES: readonly string[];
-export declare const ESLINT_CONFIG_FILENAMES: readonly string[];
+export { ESLINT_CONFIG_FILENAMES, LINT_MODULE_FILENAMES };
 export declare function defaultIsInsiderImportSource(source: string, configPath: string): boolean;
 export declare function validateProgramStructure(program: TSESTree.Program, configPath?: string, options?: ValidateProgramStructureOptions): ConfigStructureViolation[];
 export declare function validateLintModuleStructure(program: TSESTree.Program, configPath?: string, options?: ValidateProgramStructureOptions): ConfigStructureViolation[];
@@ -28,5 +29,8 @@ export declare function captureConsumerConfigDir(configPath: string | null): voi
  * getConsumerConfigDir(); // '/repo'
  */
 export declare function getConsumerConfigDir(): string;
-export declare function ensureConfigStructure(overridePath?: string | null): void;
-export {};
+export interface RunValidationDeps {
+    diagnose?: (directory: string) => LayoutDiagnosis;
+    offer?: typeof offerMigration;
+}
+export declare function ensureConfigStructure(overridePath?: string | null, deps?: RunValidationDeps): void;

package/dist/utils/ensureOxlintConfig.d.ts

@@ -1,4 +1,5 @@
-export declare const OXLINT_CONFIG_FILENAMES: readonly string[];
+import { OXLINT_CONFIG_FILENAMES } from './layoutDiagnosis';
+export { OXLINT_CONFIG_FILENAMES };
 /**
  * Fails when the consumer enabled the ESLint-side oxlint suppression without a sibling oxlint
  * config to run the suppressed rules. Resolved against the directory

package/dist/utils/layoutDiagnosis.d.ts

@@ -0,0 +1,63 @@
+export declare const LINT_MODULE_FILENAMES: readonly string[];
+export declare const ESLINT_CONFIG_FILENAMES: readonly string[];
+export declare const OXLINT_CONFIG_FILENAMES: readonly string[];
+export declare const OPT_OUT_ENV = "INSIDER_SKIP_CONFIG_VALIDATION";
+export declare const MIGRATE_COMMAND = "npx @useinsider/eslint-config migrate";
+export declare const SCAFFOLD_COMMAND = "npx @useinsider/eslint-config";
+export declare const INSIDER_IMPORT_SOURCE = "@useinsider/eslint-config";
+export declare const TARGET_CALLEE_NAME = "useInsider";
+export declare const ESLINT_RENDERER_NAME = "useInsiderESLint";
+export declare const OXC_RENDERER_NAME = "useInsiderOXC";
+export declare const RENDERER_EXPORT = "export const { useInsiderESLint, useInsiderOXC } = useInsider({ ... })";
+export declare const EXPECTED_LAYOUT: string;
+export type LayoutCase = 'complete' | 'noConfig' | 'partial' | 'unmigratedV3';
+export interface LayoutDiagnosis {
+    kind: LayoutCase;
+    directory: string;
+    lintModule: string | null;
+    eslintConfig: string | null;
+    oxlintConfig: string | null;
+    missing: string[];
+    autoMigratable: boolean;
+}
+export interface DiagnoseLayoutOptions {
+    fileExists?: (path: string) => boolean;
+    readSource?: (path: string) => string;
+}
+/**
+ * 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
+ */
+export declare function isV3EslintConfigSource(source: string): boolean;
+/**
+ * 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()
+ */
+export declare function diagnoseLayout(directory: string, options?: DiagnoseLayoutOptions): LayoutDiagnosis;
+/**
+ * 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
+ */
+export declare function lintModuleSpecifier(directory: string, fileExists?: (path: string) => boolean): string;
+export interface LayoutGuidanceInput {
+    headline: string;
+    diagnosis: LayoutDiagnosis;
+    detail?: readonly string[];
+}
+/**
+ * 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 });
+ */
+export declare function formatLayoutGuidance(input: LayoutGuidanceInput): string;

package/dist/utils/offerMigration.d.ts

@@ -0,0 +1,42 @@
+import { type LayoutDiagnosis } from './layoutDiagnosis';
+export type LintHost = 'eslint' | 'oxlint' | 'unknown';
+/**
+ * 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'
+ */
+export declare function detectLintHost(argv?: readonly string[]): LintHost;
+export type OfferSkipReason = 'already-offered' | 'cli-not-found' | 'host-is-oxlint' | 'no-tty' | 'running-in-ci' | 'running-under-test' | 'suppressed';
+export interface MigrationOfferResult {
+    offered: boolean;
+    skipReason?: OfferSkipReason;
+    accepted?: boolean;
+}
+export interface MigrationOfferDeps {
+    env?: NodeJS.ProcessEnv;
+    argv?: readonly string[];
+    interactive?: boolean;
+    resolveCliEntry?: () => string | null;
+    runCli?: (entry: string, args: readonly string[], cwd: string, env: NodeJS.ProcessEnv) => number;
+    warn?: (message: string) => void;
+}
+/**
+ * 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'
+ */
+export declare function resolveCliEntry(startDir?: string): string | null;
+/**
+ * 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
+ */
+export declare function offerMigration(diagnosis: LayoutDiagnosis, deps?: MigrationOfferDeps): MigrationOfferResult;
+/** Clears the once-per-process latch {@link offerMigration} keeps, so a suite can exercise it twice. */
+export declare function resetMigrationOffer(): void;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@useinsider/eslint-config",
     "type": "module",
-    "version": "4.0.0-beta.1",
+    "version": "4.0.0-beta.2",
     "description": "A collection of ESLint configurations provided by @useinsider, offering support for various environments including Vanilla JS, TypeScript, and framework-specific setups such as Vue 3.",
     "keywords": [
         "useinsider",