@timmo001/oxlint-rules 0.3.5 → 0.4.0

package/README.md

@@ -5,12 +5,21 @@ Shared Oxlint plugins and configs built around the unchanged
 locally owned generic rules under `timmo` and Effect rules under
 `timmo-effect`.
 
-Oxlint's JavaScript plugin API is alpha. Consumers must keep `oxlint` and
-`@oxlint/plugins` on the exact peer versions declared by this package.
+This package targets the latest stable Oxlint toolchain. Oxlint's
+[JavaScript plugin API is alpha](https://oxc.rs/docs/guide/usage/linter/config.html)
+and is outside its semver guarantees, so each rules release declares the exact
+`oxlint` and `@oxlint/plugins` versions it has validated. Older toolchains and
+untested future versions are not part of the support contract.
 
 ## Install
 
-Install from npm with the package manager already used by the repository:
+Check the published rules package's `peerDependencies` against the official npm
+`latest` versions of `oxlint` and `@oxlint/plugins`. If they differ, a validated
+rules release is needed before upgrading. Do not bypass peer checks or override
+Vite Plus's bundled dependencies to make an unsupported version fit.
+
+Once the versions match, install from npm with the package manager already used
+by the repository:
 
 ```sh
 bun add --dev --exact @timmo001/oxlint-rules oxlint @oxlint/plugins
@@ -42,6 +51,11 @@ Both configs can be installed from JSR with its npm compatibility support.
 npmjs.org remains the default for package managers that resolve ordinary
 package names from `node_modules`.
 
+For type-aware linting, also pin the latest `oxlint-tsgolint` version that meets
+Oxlint's declared peer requirement and has passed the package check. Enable
+`options: { typeAware: true }` in the consumer's config. The shared configs do
+not enable type-aware linting themselves.
+
 ## Copy rules
 
 Copy a reviewed snapshot when a repository should own the rule source:
@@ -60,12 +74,20 @@ replace an existing destination unless `--force` is passed.
 ### `anti-slop` and `anti-slop-effect`
 
 See the upstream [rule documentation](https://github.com/dmmulroy/anti-slop#rules).
+The recommended configs disable
+`anti-slop/require-safety-comment-for-type-assertion` in favour of
+`timmo/prefer-types-over-assertions`. The upstream rule remains available for
+explicit use.
 
 ### `timmo`
 
 - `prefer-event-parameter-type`: reports assertions on a handler parameter's
   `target` or `currentTarget`. Express the target type in the function signature
   instead so every use sees the same contract.
+- `prefer-types-over-assertions`: reports non-`const` TypeScript assertions,
+  even when preceded by a `SAFETY:` comment. Type values where they enter the
+  code, for example in function parameters or a checked DOM lookup helper that
+  returns `null` when the element is missing or has the wrong type.
 
 ### `timmo-effect`
 
@@ -83,14 +105,16 @@ Initialise the upstream source and run the package checks:
 git submodule update --init --recursive
 mise run check
 mise run build
+mise run test:package
 npm pack --dry-run
-bunx jsr publish --dry-run
+bunx jsr@0.14.3 publish --dry-run --allow-dirty
 ```
 
 `bun run lint` builds the local plugins before linting all maintained code,
 including tests, tooling, the root config and packaged skill scripts. The root
-config extends the local `recommended-effect` source config, enabling every
-registered rule in `anti-slop`, `timmo`, `anti-slop-effect` and `timmo-effect`.
+config extends the local `recommended-effect` source config, enabling registered
+rules in `anti-slop`, `timmo`, `anti-slop-effect` and `timmo-effect` except for
+the upstream safety-comment requirement described above.
 Plugin imports resolve through this package's exports to the fresh `dist` build.
 
 Lint disables nested configs so the vendored submodule's config cannot override
@@ -98,6 +122,29 @@ the root exclusions. Generated output, vendored source and agent directories
 remain excluded. RuleTester fixture strings retain their intentional violations;
 the surrounding test code is linted with the full rule set.
 
+`mise run test:package` builds and packs once, then installs the tarball in an
+isolated consumer using the exact toolchain pins from `package.json` and strict
+peer checks. It verifies both recommended configs, diagnostics from all four
+shared namespaces, and valid and invalid type-aware examples. CI runs this
+through the existing package workflow's build step. It also requires matching,
+exact Oxlint development and peer versions.
+
+### Toolchain updates and releases
+
+Renovate's shared preset groups Oxlint, `@oxlint/plugins` and `oxlint-tsgolint`.
+The local rule keeps both development and peer dependencies pinned instead of
+widening peer ranges. For each update:
+
+1. Verify the official npm `latest` versions and Oxlint's tsgolint peer
+   requirement. Keep Oxlint and plugins on the same latest version and regenerate
+   the lockfile with the selected tsgolint version.
+2. Run the checks and package dry-runs above. Fix any API incompatibility before
+   accepting the new pins; do not disable rules or bypass peer failures.
+3. Review and merge the validated update. Consumers need a separately approved
+   version bump and release to receive the new peer contract. Publishing a
+   GitHub release triggers the existing npm and JSR workflows; both must succeed
+   before the update is available to consumers.
+
 Advance `vendor/anti-slop` only by updating its Git submodule commit. Keep its
 source and MIT licence unchanged, then run the full package checks so both
 upstream exports and composed configs are verified.

package/dist/cli.js

@@ -2604,11 +2604,38 @@ var preferEventParameterTypeRule = defineRule18({
   }
 });
 
+// src/generic/rules/prefer-types-over-assertions.ts
+import { defineRule as defineRule19 } from "@oxlint/plugins";
+var preferTypesOverAssertionsRule = defineRule19({
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Prefer typing a value at its source over a TypeScript type assertion."
+    },
+    messages: {
+      avoidAssertion: "Type this value at its source, such as a function parameter or DOM lookup, instead of asserting it here. A SAFETY comment is not a fix."
+    }
+  },
+  create(context) {
+    const checkAssertion = (node) => {
+      if (node.typeAnnotation.type === "TSTypeReference" && node.typeAnnotation.typeName.type === "Identifier" && node.typeAnnotation.typeName.name === "const") {
+        return;
+      }
+      context.report({ node, messageId: "avoidAssertion" });
+    };
+    return {
+      TSAsExpression: checkAssertion,
+      TSTypeAssertion: checkAssertion
+    };
+  }
+});
+
 // src/generic/index.ts
 var timmoPlugin = eslintCompatPlugin2({
   meta: { name: "timmo" },
   rules: {
-    "prefer-event-parameter-type": preferEventParameterTypeRule
+    "prefer-event-parameter-type": preferEventParameterTypeRule,
+    "prefer-types-over-assertions": preferTypesOverAssertionsRule
   }
 });
 var generic_default = timmoPlugin;
@@ -2629,7 +2656,8 @@ var recommended = defineConfig({
   ],
   rules: {
     ...enablePluginRules("anti-slop", src_default),
-    ...enablePluginRules("timmo", generic_default)
+    ...enablePluginRules("timmo", generic_default),
+    "anti-slop/require-safety-comment-for-type-assertion": "off"
   }
 });
 var recommended_default = recommended;
@@ -2638,7 +2666,7 @@ var recommended_default = recommended;
 import { eslintCompatPlugin as eslintCompatPlugin3 } from "@oxlint/plugins";
 
 // src/effect/rules/no-try-catch-in-effect-generators.ts
-import { defineRule as defineRule19 } from "@oxlint/plugins";
+import { defineRule as defineRule20 } from "@oxlint/plugins";
 function resolveVariable2(sourceCode, identifier) {
   let scope = sourceCode.getScope(identifier);
   while (scope) {
@@ -2704,7 +2732,7 @@ function isRecognisedEffectGenerator(sourceCode, owner) {
   const factoryCall = parent.callee;
   return factoryCall.type === "CallExpression" && isEffectMethod(sourceCode, factoryCall.callee, "fn");
 }
-var noTryCatchInEffectGeneratorsRule = defineRule19({
+var noTryCatchInEffectGeneratorsRule = defineRule20({
   meta: {
     type: "problem",
     docs: {
@@ -2742,7 +2770,7 @@ var effect_default = timmoEffectPlugin;
 import { eslintCompatPlugin as eslintCompatPlugin4 } from "@oxlint/plugins";
 
 // vendor/anti-slop/src/effect/rules/no-manual-effect-error-tag.ts
-import { defineRule as defineRule20 } from "@oxlint/plugins";
+import { defineRule as defineRule21 } from "@oxlint/plugins";
 
 // vendor/anti-slop/src/effect/shared/tagged-values.ts
 var equalityOperators = new Set(["==", "===", "!=", "!=="]);
@@ -2789,7 +2817,7 @@ var isMatchPatternObject = (node) => {
 };
 
 // vendor/anti-slop/src/effect/rules/no-manual-effect-error-tag.ts
-var noManualEffectErrorTagRule = defineRule20({
+var noManualEffectErrorTagRule = defineRule21({
   meta: {
     type: "problem",
     docs: {
@@ -2826,8 +2854,8 @@ var noManualEffectErrorTagRule = defineRule20({
 });
 
 // vendor/anti-slop/src/effect/rules/no-manual-tag-comparison.ts
-import { defineRule as defineRule21 } from "@oxlint/plugins";
-var noManualTagComparisonRule = defineRule21({
+import { defineRule as defineRule22 } from "@oxlint/plugins";
+var noManualTagComparisonRule = defineRule22({
   meta: {
     type: "problem",
     docs: {
@@ -2857,8 +2885,8 @@ var noManualTagComparisonRule = defineRule21({
 });
 
 // vendor/anti-slop/src/effect/rules/no-manual-tagged-construction.ts
-import { defineRule as defineRule22 } from "@oxlint/plugins";
-var noManualTaggedConstructionRule = defineRule22({
+import { defineRule as defineRule23 } from "@oxlint/plugins";
+var noManualTaggedConstructionRule = defineRule23({
   meta: {
     type: "problem",
     docs: {
@@ -2883,7 +2911,7 @@ var noManualTaggedConstructionRule = defineRule22({
 });
 
 // vendor/anti-slop/src/effect/rules/no-service-constructor-imports.ts
-import { defineRule as defineRule23 } from "@oxlint/plugins";
+import { defineRule as defineRule24 } from "@oxlint/plugins";
 var SERVICE_CONSTRUCTOR_NAME = /^make[A-Z]/u;
 var TEST_FILE = /\.(?:test|spec)\.[cm]?[jt]sx?$/u;
 function isProjectLocalImport(source) {
@@ -2894,7 +2922,7 @@ function getImportedName(specifier) {
     return specifier.imported.name;
   return specifier.imported.value;
 }
-var noServiceConstructorImportsRule = defineRule23({
+var noServiceConstructorImportsRule = defineRule24({
   meta: {
     type: "problem",
     docs: {
@@ -2928,9 +2956,9 @@ var noServiceConstructorImportsRule = defineRule23({
 });
 
 // vendor/anti-slop/src/effect/rules/prefer-effect-match.ts
-import { defineRule as defineRule24 } from "@oxlint/plugins";
+import { defineRule as defineRule25 } from "@oxlint/plugins";
 var equalityOperators2 = new Set(["==", "===", "!=", "!=="]);
-var preferEffectMatchRule = defineRule24({
+var preferEffectMatchRule = defineRule25({
   meta: {
     type: "problem",
     docs: {

package/dist/configs/recommended-effect.js

@@ -2957,11 +2957,38 @@ var preferEventParameterTypeRule = defineRule24({
   }
 });
 
+// src/generic/rules/prefer-types-over-assertions.ts
+import { defineRule as defineRule25 } from "@oxlint/plugins";
+var preferTypesOverAssertionsRule = defineRule25({
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Prefer typing a value at its source over a TypeScript type assertion."
+    },
+    messages: {
+      avoidAssertion: "Type this value at its source, such as a function parameter or DOM lookup, instead of asserting it here. A SAFETY comment is not a fix."
+    }
+  },
+  create(context) {
+    const checkAssertion = (node) => {
+      if (node.typeAnnotation.type === "TSTypeReference" && node.typeAnnotation.typeName.type === "Identifier" && node.typeAnnotation.typeName.name === "const") {
+        return;
+      }
+      context.report({ node, messageId: "avoidAssertion" });
+    };
+    return {
+      TSAsExpression: checkAssertion,
+      TSTypeAssertion: checkAssertion
+    };
+  }
+});
+
 // src/generic/index.ts
 var timmoPlugin = eslintCompatPlugin4({
   meta: { name: "timmo" },
   rules: {
-    "prefer-event-parameter-type": preferEventParameterTypeRule
+    "prefer-event-parameter-type": preferEventParameterTypeRule,
+    "prefer-types-over-assertions": preferTypesOverAssertionsRule
   }
 });
 var generic_default = timmoPlugin;
@@ -2977,7 +3004,8 @@ var recommended = defineConfig({
   ],
   rules: {
     ...enablePluginRules("anti-slop", src_default),
-    ...enablePluginRules("timmo", generic_default)
+    ...enablePluginRules("timmo", generic_default),
+    "anti-slop/require-safety-comment-for-type-assertion": "off"
   }
 });
 var recommended_default = recommended;

package/dist/configs/recommended.js

@@ -2599,11 +2599,38 @@ var preferEventParameterTypeRule = defineRule18({
   }
 });
 
+// src/generic/rules/prefer-types-over-assertions.ts
+import { defineRule as defineRule19 } from "@oxlint/plugins";
+var preferTypesOverAssertionsRule = defineRule19({
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Prefer typing a value at its source over a TypeScript type assertion."
+    },
+    messages: {
+      avoidAssertion: "Type this value at its source, such as a function parameter or DOM lookup, instead of asserting it here. A SAFETY comment is not a fix."
+    }
+  },
+  create(context) {
+    const checkAssertion = (node) => {
+      if (node.typeAnnotation.type === "TSTypeReference" && node.typeAnnotation.typeName.type === "Identifier" && node.typeAnnotation.typeName.name === "const") {
+        return;
+      }
+      context.report({ node, messageId: "avoidAssertion" });
+    };
+    return {
+      TSAsExpression: checkAssertion,
+      TSTypeAssertion: checkAssertion
+    };
+  }
+});
+
 // src/generic/index.ts
 var timmoPlugin = eslintCompatPlugin2({
   meta: { name: "timmo" },
   rules: {
-    "prefer-event-parameter-type": preferEventParameterTypeRule
+    "prefer-event-parameter-type": preferEventParameterTypeRule,
+    "prefer-types-over-assertions": preferTypesOverAssertionsRule
   }
 });
 var generic_default = timmoPlugin;
@@ -2624,7 +2651,8 @@ var recommended = defineConfig({
   ],
   rules: {
     ...enablePluginRules("anti-slop", src_default),
-    ...enablePluginRules("timmo", generic_default)
+    ...enablePluginRules("timmo", generic_default),
+    "anti-slop/require-safety-comment-for-type-assertion": "off"
   }
 });
 var recommended_default = recommended;

package/dist/generic/index.js

@@ -57,11 +57,38 @@ var preferEventParameterTypeRule = defineRule({
   }
 });
 
+// src/generic/rules/prefer-types-over-assertions.ts
+import { defineRule as defineRule2 } from "@oxlint/plugins";
+var preferTypesOverAssertionsRule = defineRule2({
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Prefer typing a value at its source over a TypeScript type assertion."
+    },
+    messages: {
+      avoidAssertion: "Type this value at its source, such as a function parameter or DOM lookup, instead of asserting it here. A SAFETY comment is not a fix."
+    }
+  },
+  create(context) {
+    const checkAssertion = (node) => {
+      if (node.typeAnnotation.type === "TSTypeReference" && node.typeAnnotation.typeName.type === "Identifier" && node.typeAnnotation.typeName.name === "const") {
+        return;
+      }
+      context.report({ node, messageId: "avoidAssertion" });
+    };
+    return {
+      TSAsExpression: checkAssertion,
+      TSTypeAssertion: checkAssertion
+    };
+  }
+});
+
 // src/generic/index.ts
 var timmoPlugin = eslintCompatPlugin({
   meta: { name: "timmo" },
   rules: {
-    "prefer-event-parameter-type": preferEventParameterTypeRule
+    "prefer-event-parameter-type": preferEventParameterTypeRule,
+    "prefer-types-over-assertions": preferTypesOverAssertionsRule
   }
 });
 var generic_default = timmoPlugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timmo001/oxlint-rules",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "Shared Oxlint plugins and configs with optional Effect rules.",
   "type": "module",
   "license": "Apache-2.0",
@@ -42,16 +42,18 @@
     "lint": "bun run build && oxlint --disable-nested-config .",
     "skills:validate": "bunx skills-ref validate skills/install-timmo-oxlint-rules && bunx skills-ref validate skills/add-oxlint-rule && bunx skills-ref validate skills/release-oxlint-rules",
     "test": "node --experimental-strip-types scripts/test.ts",
+    "test:package": "node --experimental-strip-types scripts/test-package.ts",
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@oxlint/plugins": "1.83.0",
-    "oxlint": "1.83.0"
+    "@oxlint/plugins": "1.86.0",
+    "oxlint": "1.86.0"
   },
   "devDependencies": {
-    "@oxlint/plugins": "1.83.0",
+    "@oxlint/plugins": "1.86.0",
     "@types/bun": "^1.3.14",
-    "oxlint": "1.83.0",
+    "oxlint": "1.86.0",
+    "oxlint-tsgolint": "7.0.2003",
     "prettier": "^3.9.5",
     "skills-ref": "0.1.5",
     "typescript": "^7.0.0"

package/skills/install-timmo-oxlint-rules/SKILL.md

@@ -14,8 +14,12 @@ description: >-
    instructions, and normal checks. Use the current working directory unless
    the user names another target.
 3. Preserve existing ignores, overrides, plugins, and repository-owned rules.
-   Confirm `oxlint` and `@oxlint/plugins` use the same exact version supported
-   by the selected package version.
+   Verify the official npm `latest` versions of `oxlint` and `@oxlint/plugins`.
+   They must match each other and the exact peers of the selected rules release.
+   Support is latest-only: if the published peer contract has not caught up,
+   report the pending rules release instead of widening peers or bypassing
+   package-manager failures. Do not force upgrades of Vite Plus's transitive
+   dependencies or assume its bundled plugins satisfy this contract.
 
 ## Package
 
@@ -28,6 +32,10 @@ description: >-
    instead only when `effect` is a direct dependency or the user explicitly
    requests it.
 4. Keep dependency and config edits visible. Do not delegate them to a script.
+5. For type-aware linting, explicitly pin the latest `oxlint-tsgolint` that
+   satisfies Oxlint's peer requirement and was validated with the rules release.
+   Enable `options.typeAware` in the target config and verify type-aware linting
+   alongside the shared rules.
 
 ## Copy rules
 

package/skills/release-oxlint-rules/SKILL.md

@@ -17,22 +17,34 @@ description: >-
    its release exists. Resolve the next version from the requested major,
    minor, patch, or exact version. Ask only when the release level is missing.
    Do not add a `v` prefix when the repository's existing tags omit it.
-3. Update the version in `package.json` and `jsr.json`. Before committing, run
-   `mise run check`, `mise run build`, `npm pack --dry-run`, and
+3. Verify official npm `latest` metadata for `oxlint`, `@oxlint/plugins` and
+   `oxlint-tsgolint`. Support is latest-only: keep Oxlint and plugins on the same
+   latest version, pin their development and peer dependencies exactly, and
+   select the latest tsgolint satisfying Oxlint's peer requirement. Regenerate
+   `bun.lock`. The shared Renovate preset groups this toolchain; the local rule
+   keeps peers pinned. Resolve compatibility failures before releasing, without
+   widening peers, disabling rules or forcing transitive dependency upgrades.
+4. Update the version in `package.json` and `jsr.json` only when a version bump
+   is requested. Before committing, run `mise run check`, `mise run build`,
+   `mise run test:package`, `npm pack --dry-run`, and
    `bunx jsr@0.14.3 publish --dry-run --allow-dirty`. The dirty-tree flag is
-   required because the intended version bump is not committed yet.
-4. Treat a direct request to create or publish the release as authorisation for
+   required because the intended changes are not committed yet. The package
+   check installs packed output with strict peers and verifies both recommended
+   configs, actual shared-rule diagnostics and type-aware linting.
+5. Treat a direct request to create or publish the release as authorisation for
    its version commit, push, and GitHub release. Follow the active environment's
    guarded commit and push workflow, committing only the release metadata with
    `Release Oxlint rules <version>`. A request to prepare or plan a release does
    not authorise publication.
-5. Resolve the target only after the push with `git rev-parse HEAD`. Pass the
+6. Resolve the target only after the push with `git rev-parse HEAD`. Pass the
    resulting full 40-character SHA as the `--target` value when running
    `gh release create`. Never pass an abbreviated SHA as `target_commitish`.
-6. Create the release before resolving workflow targets because publication is
+7. Create the release before resolving workflow targets because publication is
    triggered by the `release.published` event. Watch only the release commit's
    exact workflow runs and require both `Publish to npm` and `Publish to JSR` to
    succeed.
-7. Report the release URL, version commit, validation results, and npm and JSR
+8. Report the release URL, version commit, validation results, and npm and JSR
    publication conclusions. Do not report the release as complete while either
-   publication job is pending or failed.
+   publication job is pending or failed. A merged toolchain update alone does
+   not deliver its peer contract to consumers; preparation ends with publication
+   pending until a version bump and release are approved.

package/src/generic/index.ts

@@ -1,11 +1,13 @@
 import { eslintCompatPlugin } from "@oxlint/plugins";
 
 import { preferEventParameterTypeRule } from "./rules/prefer-event-parameter-type.ts";
+import { preferTypesOverAssertionsRule } from "./rules/prefer-types-over-assertions.ts";
 
 const timmoPlugin = eslintCompatPlugin({
   meta: { name: "timmo" },
   rules: {
     "prefer-event-parameter-type": preferEventParameterTypeRule,
+    "prefer-types-over-assertions": preferTypesOverAssertionsRule,
   },
 });
 

package/src/generic/rules/prefer-types-over-assertions.ts

@@ -0,0 +1,38 @@
+import { defineRule } from "@oxlint/plugins";
+
+import type { ESTree } from "@oxlint/plugins";
+
+type TypeAssertion = ESTree.TSAsExpression | ESTree.TSTypeAssertion;
+
+/** Prefer typing values at their source over asserting them at use sites. */
+export const preferTypesOverAssertionsRule = defineRule({
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Prefer typing a value at its source over a TypeScript type assertion.",
+    },
+    messages: {
+      avoidAssertion:
+        "Type this value at its source, such as a function parameter or DOM lookup, instead of asserting it here. A SAFETY comment is not a fix.",
+    },
+  },
+  create(context) {
+    const checkAssertion = (node: TypeAssertion) => {
+      if (
+        node.typeAnnotation.type === "TSTypeReference" &&
+        node.typeAnnotation.typeName.type === "Identifier" &&
+        node.typeAnnotation.typeName.name === "const"
+      ) {
+        return;
+      }
+
+      context.report({ node, messageId: "avoidAssertion" });
+    };
+
+    return {
+      TSAsExpression: checkAssertion,
+      TSTypeAssertion: checkAssertion,
+    };
+  },
+});