Skip to content

Pay down the effect-lint warn tier (remaining rules after the 0.6.0 adoption) #436

Closed as not planned

Description

@thomasfosterau

The tooling-standard PR moves @mpsuesser/oxlint-plugin-effect to 0.6.0 and clears the warn-tier rules it can clear safely. Those rules are back at the preset's error; their sites and before-to-after counts are listed in the PR. This issue tracks the rules that stay at warn in vite.config.ts (the staged-rollout block). Each one is too large to fix in one PR, or blocked by a published name or signature.

Rule of the block (AGENTS.md → Common pitfalls): fix any new site, and when a rule reaches zero, delete its warn line so it is back at error. Work one rule per PR, smallest first. Get the current list with vp lint 2>&1 | grep 'effect(<rule>)'.

Counts are from vp lint on the PR head. Each row lists the files with the most sites.

Rule Sites Top files
require-safety-comment-for-type-assertion 813 src/Endpoint.ts 106, src/Resource.ts 84, src/Endpoint.test.ts 76, src/Atomic.ts 44
casting-awareness 626 src/Endpoint.ts 81, src/Resource.ts 70, src/Endpoint.test.ts 49, src/Filter.semantics.test.ts 36
prefer-option-over-null 489 src/Endpoint.ts 42, src/Handlers.ts 41, src/Client.ts 34, src/Resource.ts 31
avoid-native-object-helpers 326 src/Endpoint.test.ts 25, src/Query.filter.test.ts 24, src/Resource.ts 20, src/Resource.test.ts 20
avoid-non-null-assertion 237 src/Endpoint.test.ts 58, src/internal/filter.ts 26, src/Conformance.test.ts 20, examples/northwind/handlers.ts 15
imperative-loops 207 src/Filter.semantics.test.ts 22, src/Handlers.ts 17, src/internal/filter.ts 17, src/Resource.ts 14
avoid-any 141 src/Endpoint.test.ts 20, src/Atomic.test.ts 18, src/Resource.ts 16, src/Endpoint.ts 10
effect-run-in-body 122 src/ResourceHandlers.test.ts 19, src/Endpoint.test.ts 18, src/Client.test.ts 14, src/Idempotency.test.ts 14
no-unsafe-dictionary-type 105 src/Endpoint.ts 20, src/Assemble.ts 10, src/Conformance.test.ts 9, src/Client.ts 8
no-chained-type-assertions 104 src/Resource.ts 16, src/Endpoint.ts 10, src/Atomic.ts 9, test/idempotency.types.ts 8
no-barrel-imports 88 examples/github/errors.ts 1, src/Include.test.ts 1, examples/github/resources.ts 1, src/Lid.test.ts 1
no-runtime-typeof 82 src/internal/conformance/spec.ts 8, src/Resource.ts 6, src/Filter.semantics.test.ts 6, src/Atomic.ts 5
use-clock-service 71 examples/github/handlers.ts 13, examples/northwind/handlers.ts 12, src/Resource.test.ts 6, examples/northwind/test/northwind.test.ts 5
prefer-effect-is 70 src/internal/conformance/spec.ts 8, src/Atomic.ts 5, src/Resource.ts 5, src/Assemble.ts 5
avoid-direct-json 69 src/internal/conformance/spec.ts 11, src/Endpoint.test.ts 7, src/Idempotency.test.ts 6, src/Client.test.ts 5
no-known-value-widening 66 src/Atomic.ts 9, src/Endpoint.ts 9, src/Document.ts 7, src/FlatQuery.ts 4
prefer-arr-sort 62 src/Query.test.ts 9, examples/github/test/github.test.ts 7, examples/northwind/test/northwind.test.ts 7, test/entry-points.test.ts 6
avoid-direct-tag-checks 60 src/Query.filter.test.ts 21, src/Conformance.test.ts 7, src/Resource.ts 6, src/Conformance.sort.test.ts 4
avoid-untagged-errors 58 src/Resource.ts 12, src/ServerErrors.test.ts 6, src/Include.ts 5, examples/blog/handlers.ts 4
no-conditional-empty-object-spread 57 src/Atomic.ts 9, src/Handlers.ts 9, src/Endpoint.ts 8, src/Assemble.ts 7
avoid-ts-ignore 55 src/Endpoint.ts 20, src/Resource.filter.test.ts 9, src/Resource.test.ts 6, src/Filter.test.ts 5
no-unknown-parameters 42 src/internal/conformance/spec.ts 6, src/Endpoint.test.ts 4, src/internal/filter.ts 3, src/Query.ts 2
avoid-object-type 39 src/Query.ts 14, src/Endpoint.ts 10, src/Resource.ts 5, src/Handlers.ts 5
no-shape-in-symbol-names 38 src/Handlers.ts 10, test/resource-transforms.types.ts 9, src/Atomic.ts 6, src/Group.flat.test.ts 6
no-unknown-returns 8 src/Resource.ts 3, src/Assemble.ts 3, src/Endpoint.ts 1, src/Idempotency.ts 1
require-schema-type-alias 4 src/Query.ts 2, src/Idempotency.ts 2
no-object-parameters 1 src/ApiError.ts 1

Total: 4040 warnings.

Rules blocked by the published API

  • require-schema-type-alias (4 sites). Idempotency.Headers / HeadersRequired and Query.FilterWireValue / FilterRest are already published as interface X extends Schema.…<…> {}, the schema's own type. The rule accepts only a same-named type alias of .Type, so satisfying it would change a published type. It needs a decision, a rename or a breaking change.
  • no-object-parameters (1 site). ApiError.toDocument(error: object) accepts any value a framework hook caught and throws at runtime on a non-ApiError value. Narrowing the parameter is a breaking change.
  • Naming rules (no-shape-in-symbol-names): the sites in src/*.ts exports are published names. Only the private and test sites can be renamed without a major.
  • casting-awareness stays at warn by design, as an awareness prompt (see its comment), and is not counted as debt.

Small enough for one PR each

no-unknown-returns: the JSON walkers in Assemble.ts / Idempotency.ts and the annotation lookups in Resource.ts need a named JSON value type. Then avoid-object-type, no-unknown-parameters and avoid-ts-ignore in sources (the @ts-expect-error markers on effect's ErrorNoStream guard may have to stay; see src/Endpoint.ts).


Generated by Claude Code

Activity

  1. thomasfosterau commented on Oct 22, 2026

    @thomasfosterau
    OwnerAuthor

    avoid-object-type is blocked by published signatures. I'm leaving its warn line in place and skipping it in this pass.

    There are 39 sites on trunk (e5af8ce). Nine of them are the = {} default of a type parameter in a published generic:

    Site Parameter
    src/Resource.ts:1196 Resource.Resource<…, Rels extends Relationships = {}>
    src/Resource.ts:1345 Resource.Parameter<…, Rels = {}>
    src/Resource.ts:2760 Resource.make<…, const Rels = {}>
    src/Resource.ts:3266, :3267 Resource.extend<…, ExtraAttributes = {}, ExtraRels = {}>
    src/ApiError.ts:271 ApiError.make()<Tag, Fields = {}>
    src/FlatQuery.ts:439 FlatQuery.listInput<Fields = {}>
    src/Group.ts:162 Group.resource<…, Endpoints = {}>
    src/Endpoint.ts:3609 Endpoint.resource<…, Endpoints = {}>

    None of them has a fix that leaves the published types alone:

    • The rule's suggested Record<string, never> changes what the types mean. keyof the default becomes string instead of never, and an intersection X & Record<string, never> turns every member of X into never. Every mapped or conditional type keyed on Rels, Fields or Endpoints would change for a consumer who omits the argument.
    • unknown does not satisfy the constraints (Relationships, Schema.Struct.Fields, EndpointsOption<…>).
    • A named empty type (interface NoRelationships {}) would have to be exported, because consumers' declaration emit must be able to name it (bug: declaration emit still fails for an endpoint over a resource defined in another file (TS2883) #385). That is a new published name, and it would appear in consumers' inferred types in place of {}.

    The other 30 sites can be fixed without a published change. They are mostly the {} identity in conditional intersections (Query.NestedFields / FlatList, the Handlers document types, Endpoint's ConfigObject), where unknown is the identity. Some of those are inside exported types, though, so the emitted .d.ts text would change even though the resolved types stay the same. Both rewrites, X & {} → X & unknown and Simplify's trailing & {}, need a check under typecheck:dist and the declaration-emit test.

    Decision needed: how should the nine published defaults be handled?

    1. Keep {} and add a per-line // oxlint-disable-next-line effect/avoid-object-type -- <reason> at each site. This leaves no published change, then fix the other 30 and flip the rule to error.
    2. Export named empty types (for example Resource.NoRelationships, Schema.Struct.Fields-shaped NoFields) and use them as the defaults. This adds published names; minor bump.
    3. Leave the rule at warn for good, like casting-awareness, and update the comment in vite.config.ts.

    I'm going on to no-unknown-parameters.


    Generated by Claude Code

  2. thomasfosterau commented on Oct 22, 2026

    @thomasfosterau
    OwnerAuthor

    no-unknown-parameters is blocked by two published signatures. I'm leaving its warn line in place and stopping this pass here.

    There are 48 sites on trunk (e5af8ce). The table at the top said about 42. Two of them are published functions whose unknown parameter is the contract: each one is the parser at the boundary that the rule asks for.

    Site Signature Why the input is unknown
    src/ServerErrors.ts:409 ServerErrors.fromTaggedError: (error: unknown) => Option<JsonapiError> Classifies any value a handler failed with; anything else is None (see its @example).
    src/Client.ts:611 Client.decodeErrorDocument(body: unknown): Option<ErrorDocument> Decodes an arbitrary response body; HTML, truncated or empty bodies are None (see its @example).

    Narrowing either parameter is a breaking change. The rule's only exemptions are a parameter named cause and a type-predicate subject. Renaming error → cause would dodge the rule on fromTaggedError without changing its type, but it changes the published declaration and does nothing for decodeErrorDocument.

    The other 46 sites are internal or test code:

    • 14 are in src/internal/conformance/*. These are response-body readers (resourcesOf, errorObjectsOf, includableOf, labelsOf, …), so typing them means deciding what they take. Schema.Json fits a JSON.parse result.
    • 11 are in *.test.ts.
    • The rest are in src/ helpers.

    #481 already clears 5 of the 48 as a side effect (Endpoint.pick's fallback, Assemble.wireRelationshipLinks / toWireValue, Idempotency.canonicalValue). A PR for this rule should build on it.

    Decision needed: what should happen to the two published parsers?

    1. Add a per-line // oxlint-disable-next-line effect/no-unknown-parameters -- boundary parser at each one, fix the other 46, and flip the rule to error.
    2. Change the signatures in a major.
    3. Ask upstream (@mpsuesser/oxlint-plugin-effect) for an option that exempts named boundary parsers.

    With avoid-object-type also blocked (see the comment above), this pass ends with only no-unknown-returns done (#481).


    Generated by Claude Code

  3. thomasfosterau commented on Oct 22, 2026

    @thomasfosterau
    OwnerAuthor

    Owner decision: break the signatures. avoid-object-type and no-unknown-parameters both go to zero, including their published sites:

    • the = {} type-parameter defaults on published generics (Resource.Resource, Resource.make, Resource.extend, …);
    • the published boundary parsers that take unknown (ServerErrors.fromTaggedError, …).

    Each rule gets its own PR, which deletes the rule's warn line and carries a major changeset that names every changed published signature and gives a migration note.


    Generated by Claude Code

  4. thomasfosterau commented on Oct 29, 2026

    @thomasfosterau
    OwnerAuthor

    Owner decision (2026-10-29, relayed from the coordinator session): break the published API for the three remaining blocked rules, and take all three to error.

    • no-object-parameters. ApiError.toDocument takes ApiError.Any instead of object.
    • require-schema-type-alias. Idempotency.Headers / HeadersRequired and Query.FilterWireValue / FilterRest become same-named type aliases.
    • no-shape-in-symbol-names. Rename the published names it flags. The old names stay for one minor release as deprecated aliases.

    All of this ships under one major changeset with a migration note. The work is split into reviewable PRs, roughly one per rule. They come after the avoid-ts-ignore slice (#519) and the no-conditional-empty-object-spread slice.

    casting-awareness stays at warn by design.


    Generated by Claude Code

  5. thomasfosterau commented on Oct 29, 2026

    @thomasfosterau
    OwnerAuthor

    Status after this round (2026-10-29): five more rules are back at error, each from its own merged PR.

    Rule PR How
    avoid-ts-ignore #519 The 34 compile-time negative assertions in the colocated tests moved to test/rejected-calls.types.ts. src/Endpoint.ts keeps its directives on effect's unprovable ErrorNoStream guard, under a file-scoped override that says why: the guard is a deferred conditional type that effect does not export, so no local type can prove it.
    no-conditional-empty-object-spread #520 An internal definedMember(key, value) helper replaces every site.
    no-object-parameters #522 ApiError.toDocument takes the new ApiError.Any. ApiError.TypeId and ApiError.isApiError are new.
    require-schema-type-alias #523 The four names are now typeof X.Type, and the schema types moved to *Schema names.
    no-shape-in-symbol-names #524 Atomic.*OperationShape became *OperationTarget. The old names remain as deprecated aliases. Removing them is #525.

    Each breaking slice shipped its own minor changeset marked Breaking rather than a single major one. The package is pre-1.0, and #506 records the minor-for-breaking rule.

    Still at warn are the large-count rules: require-safety-comment-for-type-assertion, prefer-option-over-null, avoid-native-object-helpers, avoid-non-null-assertion, imperative-loops, avoid-any, effect-run-in-body, no-chained-type-assertions, no-barrel-imports, no-unsafe-dictionary-type, no-runtime-typeof, use-clock-service, prefer-effect-is, avoid-direct-json, no-known-value-widening, prefer-arr-sort, avoid-direct-tag-checks and avoid-untagged-errors. casting-awareness stays at warn by design.


    Generated by Claude Code

  6. thomasfosterau commented on Nov 7, 2026

    @thomasfosterau
    OwnerAuthor

    Parked: superseded by #533. #533 says it "supersedes the per-rule pay-down list in #436". Every rule still at warn from this issue's table is in #533's table, with counts taken after the @enfect/oxlint swap (#532), and the decisions recorded here (break the published signatures, casting-awareness stays at warn) still apply. The last blocked item from here, removing the deprecated Atomic.*OperationShape aliases (#525), is PR #560.

    Recommendation: close this issue in favour of #533 once #560 merges. Nothing else is tracked only here.


    Generated by Claude Code

  7. thomasfosterau commented on Nov 12, 2026

    @thomasfosterau
    OwnerAuthor

    Closing as superseded by #533 (owner decision 2026-11-11: close if done).

    Evidence: #560 (removing the deprecated Atomic.*OperationShape aliases, the last item tracked only here) is merged. Every rule still at warn from this issue's table is listed, with current counts, in #533. The decisions recorded here still apply there: break published signatures where a rule needs it, as minor changesets on 0.x.

    The casting-awareness exemption recorded here is overtaken by the owner's newer family-wide rule (lint to zero, every rule at error), which #533 now tracks.


    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions