oxlint-plugin-vize 0.303.0 → 0.306.0

package/README.md

@@ -13,6 +13,7 @@ This package lets Oxlint execute Patina through Vize's native binding while stil
 - Runs Vize Patina rules inside Oxlint as `vize/*` diagnostics, so Vue-specific findings can live beside Oxlint core rules in one command.
 - Keeps Oxlint's existing rules and built-in `vue` plugin active. The bridge adds Vize rules; it does not replace `eqeqeq`, `no-console`, or your existing `vue/*` setup.
 - Ships preset rule maps for JS/TS Oxlint configs: `configs.recommended`, `configs.essential`, `configs.ecosystem`, `configs.opinionated`, `configs.nuxt`, `configs.all`, and type-aware opt-in variants.
+- Ships `createVizeLintConfig()` for the Vite+ `lint` block in `vite.config.ts`, which is the only Oxlint configuration `vp lint` and `vp check` read.
 - Supports runtime settings through `settings.vize`, including `locale`, `preset`, and `helpLevel`.
 - Provides the `oxlint-vize` CLI wrapper, which runs Oxlint with a scriptless-SFC workaround and rewrites temporary paths back to the original `.vue` files.
 - Resolves Vize native bindings through platform-specific optional dependencies, so published installs do not need a separate `@vizejs/native` package.
@@ -46,6 +47,67 @@ vp install -D oxlint oxlint-plugin-vize
 
 ## Usage
 
+Which file you configure depends on which command you run.
+
+| Command                 | Reads                                |
+| ----------------------- | ------------------------------------ |
+| `vp lint`, `vp check`   | the `lint` block in `vite.config.ts` |
+| `oxlint`, `oxlint-vize` | `.oxlintrc.json` (or `-c <path>`)    |
+
+> [!IMPORTANT]
+> Vite+ never reads `.oxlintrc.json`. A `.oxlintrc.json` carrying `jsPlugins` and `vize/*` rules
+> looks configured, but `vp lint` ignores the file, so Oxlint never sees a `vize/*` rule id and
+> reports **zero** Vize diagnostics while exiting `0`. `vp lint --init` does not migrate an existing
+> `.oxlintrc.json` either: it writes a fresh `lint` block and leaves the old file in place.
+> If you use `vp lint`, configure the `lint` block.
+
+### With `vp lint` (Vite+)
+
+`createVizeLintConfig()` returns the whole `lint` block, so the `jsPlugins` entry cannot go missing:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite-plus";
+import { createVizeLintConfig } from "oxlint-plugin-vize";
+
+export default defineConfig({
+  lint: createVizeLintConfig({
+    preset: "essential",
+    rules: {
+      "no-console": "warn",
+    },
+    settings: {
+      helpLevel: "short",
+    },
+  }),
+});
+```
+
+`preset` drives both the emitted rule map and `settings.vize.preset`, so the two can never disagree.
+That matters because the bridge silently drops any `vize/*` rule outside the active preset: listing
+`vize/ecosystem/router-link-require-to` while the active preset is `general-recommended` reports
+nothing at all. `createVizeLintConfig` throws for that case, and for unknown `vize/*` ids, instead of
+leaving you with a config that looks enabled and reports nothing. Use `preset: "incremental"` when
+you want only the rules you list, and `preset: "all"` for every bundle at once.
+
+The emitted block always enables Oxlint's built-in `vue` plugin. Pass `plugins` to keep the rest of
+your project's plugin list; they are merged with `vue`, never replaced, because narrowing the list
+would silently drop everything those plugins report. A `create-vue` project keeps its generated set
+like this:
+
+```ts
+export default defineConfig({
+  lint: {
+    ...createVizeLintConfig({
+      plugins: ["eslint", "typescript", "unicorn", "oxc"],
+    }),
+    ignorePatterns: ["dist/**"],
+  },
+});
+```
+
+### With `oxlint` or `oxlint-vize`
+
 Enable Oxlint's built-in `vue` plugin as well as this JS plugin:
 
 ```json

package/dist/index.d.mts

@@ -4,7 +4,15 @@ import * as _$_oxlint_plugins0 from "@oxlint/plugins";
 declare const _default: _$_oxlint_plugins0.Plugin;
 //#endregion
 //#region src/model.d.ts
+type HelpLevel = "none" | "short" | "full";
 type PatinaPreset = "general-recommended" | "essential" | "ecosystem" | "incremental" | "opinionated" | "nuxt";
+interface PatinaSettings {
+  locale?: string;
+  helpLevel?: HelpLevel;
+  preset?: PatinaPreset;
+  typeAware?: boolean;
+  corsaPath?: string;
+}
 //#endregion
 //#region src/configs.d.ts
 type OxlintRuleSeverity = "error" | "warn";
@@ -27,4 +35,97 @@ declare const configs: {
   readonly recommendedWithTypeAware: OxlintRuleConfig;
 };
 //#endregion
-export { type OxlintRuleConfig, type OxlintRuleSeverity, type VizeRuleConfigOptions, configs, createVizeRuleConfig, _default as default };
+//#region src/vite-plus.d.ts
+/**
+ * Bare specifier Oxlint uses to load this bridge as a JS plugin.
+ *
+ * Vite+ hands the `lint` block to Oxlint unchanged, so the same specifier works
+ * in `vite.config.ts` and in a hand-written `.oxlintrc.json`.
+ */
+declare const VIZE_JS_PLUGIN_SPECIFIER = "oxlint-plugin-vize";
+/**
+ * Rule bundles `createVizeLintConfig` accepts.
+ *
+ * `"all"` and `"incremental"` both disable preset gating in the bridge, which is
+ * what makes them usable: `"all"` needs every bundle's rules to run at once, and
+ * `"incremental"` needs only the rules the caller lists to run.
+ */
+type VizeLintPreset = PatinaPreset | "all";
+interface VizeLintConfigOptions {
+  /**
+   * Include Vize's unstable `vize/type/*` rules in the preset rule map. Off by
+   * default, matching `createVizeRuleConfig`.
+   */
+  includeTypeAware?: boolean;
+  /**
+   * Built-in Oxlint plugins to keep enabled alongside `vue`.
+   *
+   * The emitted block always lists `vue`, and narrowing a project's plugin list
+   * would silently drop the diagnostics those plugins produce, so anything passed
+   * here is merged rather than replaced. A `create-vue` project, for example,
+   * needs `["eslint", "typescript", "unicorn", "oxc"]` carried over.
+   */
+  plugins?: readonly string[];
+  /**
+   * Rule bundle to enable. Defaults to `"general-recommended"`, the bridge's own
+   * default. `"incremental"` emits no preset rules, so only `rules` run.
+   */
+  preset?: VizeLintPreset;
+  /**
+   * Extra Oxlint rules merged after the preset rules. Core Oxlint rule ids pass
+   * through untouched; `vize/*` ids are validated against the rules the native
+   * bridge registers and against the resolved preset.
+   */
+  rules?: OxlintRuleConfig;
+  /**
+   * Patina runtime settings forwarded through `settings.vize`. `preset` is
+   * intentionally absent: it is derived from `options.preset` so the rule map and
+   * the bridge's runtime gate can never disagree.
+   */
+  settings?: Omit<PatinaSettings, "preset">;
+}
+interface VizeLintConfig {
+  jsPlugins: string[];
+  plugins: string[];
+  rules: OxlintRuleConfig;
+  settings: {
+    vize: PatinaSettings;
+  };
+}
+/**
+ * Builds the Oxlint configuration block that runs Patina through this bridge.
+ *
+ * Vite+ (`vp lint` / `vp check`) reads its Oxlint configuration from the `lint`
+ * key of `vite.config.ts` and never reads `.oxlintrc.json`. Wiring the bridge by
+ * hand therefore has a silent failure mode: a `.oxlintrc.json` carrying
+ * `jsPlugins` and `vize/*` rules looks configured, Vite+ ignores the file, Oxlint
+ * never sees a `vize/*` rule id, and `vp lint` reports zero Vize diagnostics
+ * while exiting `0`. Spreading this object into `lint` removes the chance to get
+ * that wrong:
+ *
+ * ```ts
+ * import { defineConfig } from "vite-plus";
+ * import { createVizeLintConfig } from "oxlint-plugin-vize";
+ *
+ * export default defineConfig({
+ *   lint: createVizeLintConfig({ preset: "essential" }),
+ * });
+ * ```
+ *
+ * Both validations below exist because the bridge's normal failure modes are
+ * silent rather than loud:
+ *
+ * - An unknown `vize/*` id only produces Oxlint's
+ *   `Rule '...' not found in plugin 'vize'` error when Oxlint actually reads the
+ *   config. A typo in a config Oxlint never reads reports nothing at all.
+ * - A `vize/*` id that is outside the active preset is dropped by the bridge's
+ *   runtime preset gate (`plugin.ts`), so it stays listed in `rules` and reports
+ *   nothing. `preset: "incremental"` is the supported way to run an arbitrary
+ *   subset.
+ *
+ * @throws {Error} When `options.rules` names a `vize/*` id the native bridge does
+ *   not register, or one the resolved preset would silently suppress.
+ */
+declare function createVizeLintConfig(options?: VizeLintConfigOptions): VizeLintConfig;
+//#endregion
+export { type OxlintRuleConfig, type OxlintRuleSeverity, VIZE_JS_PLUGIN_SPECIFIER, type VizeLintConfig, type VizeLintConfigOptions, type VizeLintPreset, type VizeRuleConfigOptions, configs, createVizeLintConfig, createVizeRuleConfig, _default as default };

package/dist/index.mjs

@@ -623,4 +623,100 @@ if (import.meta.vitest) {
 	});
 }
 //#endregion
-export { configs, createVizeRuleConfig, plugin_default as default };
+//#region src/vite-plus.ts
+/**
+* Bare specifier Oxlint uses to load this bridge as a JS plugin.
+*
+* Vite+ hands the `lint` block to Oxlint unchanged, so the same specifier works
+* in `vite.config.ts` and in a hand-written `.oxlintrc.json`.
+*/
+const VIZE_JS_PLUGIN_SPECIFIER = "oxlint-plugin-vize";
+const VIZE_RULE_PREFIX = "vize/";
+/**
+* Builds the Oxlint configuration block that runs Patina through this bridge.
+*
+* Vite+ (`vp lint` / `vp check`) reads its Oxlint configuration from the `lint`
+* key of `vite.config.ts` and never reads `.oxlintrc.json`. Wiring the bridge by
+* hand therefore has a silent failure mode: a `.oxlintrc.json` carrying
+* `jsPlugins` and `vize/*` rules looks configured, Vite+ ignores the file, Oxlint
+* never sees a `vize/*` rule id, and `vp lint` reports zero Vize diagnostics
+* while exiting `0`. Spreading this object into `lint` removes the chance to get
+* that wrong:
+*
+* ```ts
+* import { defineConfig } from "vite-plus";
+* import { createVizeLintConfig } from "oxlint-plugin-vize";
+*
+* export default defineConfig({
+*   lint: createVizeLintConfig({ preset: "essential" }),
+* });
+* ```
+*
+* Both validations below exist because the bridge's normal failure modes are
+* silent rather than loud:
+*
+* - An unknown `vize/*` id only produces Oxlint's
+*   `Rule '...' not found in plugin 'vize'` error when Oxlint actually reads the
+*   config. A typo in a config Oxlint never reads reports nothing at all.
+* - A `vize/*` id that is outside the active preset is dropped by the bridge's
+*   runtime preset gate (`plugin.ts`), so it stays listed in `rules` and reports
+*   nothing. `preset: "incremental"` is the supported way to run an arbitrary
+*   subset.
+*
+* @throws {Error} When `options.rules` names a `vize/*` id the native bridge does
+*   not register, or one the resolved preset would silently suppress.
+*/
+function createVizeLintConfig(options = {}) {
+	const preset = options.preset ?? "general-recommended";
+	const extraRules = options.rules ?? {};
+	assertUsableVizeRules(extraRules, preset);
+	return {
+		jsPlugins: [VIZE_JS_PLUGIN_SPECIFIER],
+		plugins: [...new Set(["vue", ...options.plugins ?? []])],
+		rules: {
+			...createPresetRules(preset, options.includeTypeAware),
+			...extraRules
+		},
+		settings: { vize: {
+			...options.settings,
+			preset: toRuntimePreset(preset)
+		} }
+	};
+}
+function createPresetRules(preset, includeTypeAware) {
+	return preset === "incremental" ? {} : createVizeRuleConfig({
+		includeTypeAware,
+		preset
+	});
+}
+/**
+* Maps a rule bundle to the `settings.vize.preset` the bridge must run with.
+*
+* `"all"` becomes `"incremental"` because the bridge gates each rule on preset
+* membership; gating an all-bundles rule map by any single preset would suppress
+* the rules that only belong to the other bundles.
+*/
+function toRuntimePreset(preset) {
+	return preset === "all" ? "incremental" : preset;
+}
+function assertUsableVizeRules(rules, preset) {
+	const ruleMetaById = new Map(getPatinaRules().map((ruleMeta) => [`${VIZE_RULE_PREFIX}${ruleMeta.name}`, ruleMeta]));
+	const configuredIds = Object.keys(rules).filter((ruleId) => ruleId.startsWith(VIZE_RULE_PREFIX)).sort();
+	const unknownIds = configuredIds.filter((ruleId) => !ruleMetaById.has(ruleId));
+	if (unknownIds.length > 0) throw new Error(`Unknown Vize rule ${pluralizeIds(unknownIds)}: ${unknownIds.join(", ")}. Check the id against the rules oxlint-plugin-vize registers.`);
+	const runtimePreset = toRuntimePreset(preset);
+	const suppressedIds = configuredIds.filter((ruleId) => isSuppressedByPreset(ruleMetaById.get(ruleId), runtimePreset));
+	if (suppressedIds.length > 0) throw new Error(`Vize rule ${pluralizeIds(suppressedIds)} outside the "${preset}" preset: ${suppressedIds.join(", ")}. Use preset: "incremental" to run an explicit rule subset, or pick the preset that owns these rules.`);
+}
+/**
+* Mirrors the runtime gate in `plugin.ts`: rules with no preset membership are
+* never gated, and `"incremental"` skips gating entirely.
+*/
+function isSuppressedByPreset(ruleMeta, runtimePreset) {
+	return ruleMeta.presets.length > 0 && runtimePreset !== "incremental" && !ruleMeta.presets.includes(runtimePreset);
+}
+function pluralizeIds(ids) {
+	return ids.length === 1 ? "id" : "ids";
+}
+//#endregion
+export { VIZE_JS_PLUGIN_SPECIFIER, configs, createVizeLintConfig, createVizeRuleConfig, plugin_default as default };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxlint-plugin-vize",
-  "version": "0.303.0",
+  "version": "0.306.0",
   "description": "Oxlint JS plugin bridge for Vize Patina",
   "keywords": [
     "lint",
@@ -44,21 +44,21 @@
   "devDependencies": {
     "@tsdown/css": "0.22.0",
     "@types/node": "25.9.2",
-    "@vizejs/native": "0.303.0",
+    "@vizejs/native": "0.306.0",
     "tsdown": "0.22.0",
     "typescript": "6.0.3",
     "vite": "npm:@voidzero-dev/vite-plus-core@0.1.21",
     "vite-plus": "0.1.21"
   },
   "optionalDependencies": {
-    "@vizejs/native-darwin-arm64": "0.303.0",
-    "@vizejs/native-darwin-x64": "0.303.0",
-    "@vizejs/native-linux-arm64-gnu": "0.303.0",
-    "@vizejs/native-linux-arm64-musl": "0.303.0",
-    "@vizejs/native-linux-x64-gnu": "0.303.0",
-    "@vizejs/native-linux-x64-musl": "0.303.0",
-    "@vizejs/native-win32-arm64-msvc": "0.303.0",
-    "@vizejs/native-win32-x64-msvc": "0.303.0"
+    "@vizejs/native-darwin-arm64": "0.306.0",
+    "@vizejs/native-darwin-x64": "0.306.0",
+    "@vizejs/native-linux-arm64-gnu": "0.306.0",
+    "@vizejs/native-linux-arm64-musl": "0.306.0",
+    "@vizejs/native-linux-x64-gnu": "0.306.0",
+    "@vizejs/native-linux-x64-musl": "0.306.0",
+    "@vizejs/native-win32-arm64-msvc": "0.306.0",
+    "@vizejs/native-win32-x64-msvc": "0.306.0"
   },
   "engines": {
     "node": "^22 || >= 24"