Skip to content

vp lint: allow configuring the type-aware backend (tsrs-lint) — pass options such as --runExternalCode and --fast from the lint config #3476

Description

@Q16solver

Summary

vp lint should let a project configure the type-aware backend it launches, tsrs-lint: pass it options or flags from vite.config.ts (and the vp lint command line), the same way the project already configures tsrs for its type check.

Motivation

Since 1.7, vp lint runs Oxlint's type-aware rules on the bundled tsrs-lint (it sets OXLINT_TSGOLINT_PATH itself). Oxlint launches the backend as <path> headless with no extra arguments, and neither the lint block nor vp lint has a way to add any. So nothing a project passes to tsrs as a flag can reach the lint run from the lint config:

  • Content mappers (--runExternalCode). A tsconfig declaring contentMappers (e.g. vize for .vue, or any Nuxt project's generated tsconfig that names one) makes every type-aware run fail. tsrs-lint headless accepts the flag itself (Usage: tsrs-lint headless [--fix] [--fix-suggestions] [--runExternalCode] [--debug timings]); only the wiring cannot ask for it.
  • Performance presets (--fast / TSRS_FAST). A project that runs tsrs --fast for its type check wants its lint on the same checker settings by statement, not by whatever default the bundled tsrs-lint ships (it turned the preset on in feat(lint): enable fast mode by default oxc-project/tsrs#989).
  • Anything else tsrs-lint grows — per-feature overrides, debug timings, memory tuning — has the same problem, and will keep having it while the only channel is the backend's own argv.

Today the only route is the environment variables tsrs-lint happens to read (TSRS_LINT_RUN_EXTERNAL_CODE, TSRS_FAST, …). They are undocumented in the lint guide, and to reach the editor's lint as well as the CLI they have to be assigned to process.env from inside the config file — a workaround, not a setting.

Proposal

A way to hand options to the type-aware backend from the lint config, forwarded by vp lint (and vp check, and the editor integration) as flags or environment. Either shape would cover it:

// typed, for the options vite-plus knows about
lint: {
  options: {
    typeAware: { runExternalCode: true, fast: true },
  },
},
// or an escape hatch passed through verbatim
lint: {
  options: {
    typeAware: true,
    typeAwareArgs: ["--runExternalCode"],
    typeAwareEnv: { TSRS_FAST: "1" },
  },
},

plus a matching CLI form (e.g. vp lint --type-aware-arg=--runExternalCode). Short of either, documenting the supported environment variables in the type-aware section of the lint guide would make the failure below discoverable from its error.

Reproduction (the content-mapper case)

package.json

{
  "name": "repro-vp-mapper",
  "private": true,
  "type": "module",
  "devDependencies": { "vite-plus": "1.7.0", "vize": "0.777.0", "vue": "3.5.45" }
}

tsconfig.json

{
  "compilerOptions": { "strict": true, "module": "esnext", "moduleResolution": "bundler", "target": "esnext", "noEmit": true },
  "contentMappers": [{ "package": "vize", "extensions": [".vue"] }],
  "include": ["src/**/*.ts", "src/**/*.vue"]
}

vite.config.ts

import { defineConfig } from "vite-plus";

export default defineConfig({
  lint: {
    options: { typeAware: true },
    rules: { "typescript/restrict-template-expressions": "error" },
  },
});

src/index.ts

const value = { a: 1 };
export const text = `${value}`;
  1. pnpm install

  2. pnpm exec vp lint src → exit 1, no type-aware diagnostics:

      x typescript(tsconfig-error): Invalid tsconfig
       ,-[tsconfig.json:3:3]
     3 |   "contentMappers": [{ "package": "vize", "extensions": [".vue"] }],
       :   ^^^^^^^^^^^^^^^^
      help: Content mappers require the '--runExternalCode' command line flag to be enabled.
    
  3. TSRS_LINT_RUN_EXTERNAL_CODE=1 pnpm exec vp lint src → typescript(restrict-template-expressions) reported as expected.

  4. Removing the contentMappers line also makes step 2 report the rule normally.

Reproduced three times out of three.

System info

  • vite-plus 1.7.0 (bundled tsrs 7.1.0-beta.tsrs2, oxlint 1.94.0)
  • vize 0.777.0
  • Node v26.13.1, macOS (arm64)

Activity

  1. added theissue type on Nov 17, 2026
  2. changed the title [-]`vp lint` type-aware fails with `tsconfig-error` on a tsconfig with `contentMappers`: no way to pass `--runExternalCode` to `tsrs-lint`[/-] [+]`vp lint` cannot configure the `tsrs-lint` type-aware backend: content-mapper projects fail with `tsconfig-error` (no `--runExternalCode`)[/+] on Nov 17, 2026
  3. changed the title [-]`vp lint` cannot configure the `tsrs-lint` type-aware backend: content-mapper projects fail with `tsconfig-error` (no `--runExternalCode`)[/-] [+]`vp lint`: allow configuring the type-aware backend (`tsrs-lint`) — pass options such as `--runExternalCode` and `--fast` from the lint config[/+] on Nov 17, 2026
  4. fengmk2 commented on Nov 17, 2026

    @fengmk2
    Member

    We need to refer to oxlint’s solution. @camc314

  5. voidzero-bot commented on Nov 17, 2026

    @voidzero-bot
    Contributor
    • Reproduced: Yes
    • Exploration: Yes — View branch
    • Unit Test: Yes — packages/cli/binding/src/cli/resolver.rs (lint_tracks_backend_env_vars_for_caching)
    • Priority: P2: Has Workaround. Type-aware linting fails for projects using tsconfig.json contentMappers because the bundled tsrs-lint backend is invoked without --runExternalCode, but the equivalent TSRS_LINT_RUN_EXTERNAL_CODE=1 environment variable already works around the failure.

    vp lint wires Oxlint to the bundled tsrs-lint backend via OXLINT_TSGOLINT_PATH, but it never documented or tracked the TSRS_LINT_RUN_EXTERNAL_CODE opt-in that tsrs-lint also reads. As a result, any project that declares a contentMappers entry in its tsconfig.json hits a typescript(tsconfig-error): Invalid tsconfig before any source diagnostics are reported.

    I found a potential fix for this issue. The branch documents TSRS_LINT_RUN_EXTERNAL_CODE in docs/guide/lint.md and adds it to the task-cache environment fingerprints in packages/cli/binding/src/cli/resolver.rs and packages/cli/binding/src/cli/handler.rs, so vp run lint and vp run check correctly invalidate cached results when the opt-in changes.

    Full Triage Report

    Triage Report: #3476

    Summary

    vp lint with type-aware rules enabled fails when tsconfig.json contains a contentMappers entry. Oxlint launches the bundled tsrs-lint backend in headless mode without --runExternalCode, so TSRS rejects the tsconfig as invalid. There is currently no documented/ configurable way in lint.options to pass --runExternalCode to the backend.

    Expected vs Actual

    • Expected: Type-aware linting runs, including content-mapper handling, and reports the configured typescript/restrict-template-expressions error.
    • Actual: Lint exits with a typescript(tsconfig-error) on tsconfig.json before any source diagnostics are reported.

    Environment

    • vite-plus / vp: v1.7.0 (local checkout): bundled oxlint v1.94.0, tsrs v7.1.0-beta.tsrs2
    • Node.js: v24.22.3
    • pnpm: v12.11.2
    • OS: Linux x64 (GitHub Actions runner)
    • Reproduction deps: vize@0.97.0, vue@3.5.13

    Reproduction Path

    Created a minimal project at /tmp/vite-plus-triage/gh-3476/repro with the files from the issue report.

    Trigger command

    cd /tmp/vite-plus-triage/gh-3476/repro
    pnpm exec vp lint src

    Trigger output

    ::error file=tsconfig.json,line=9,endLine=9,col=3,endColumn=19,title=typescript(tsconfig-error)::tsconfig.json:9:3: Invalid tsconfig
    
    Found 0 warnings and 1 error.
    Finished in 137ms on 1 file with 111 rules using 4 threads.
    exit=1
    

    Control command (remove contentMappers)

    cd /tmp/vite-plus-triage/gh-3476/repro
    pnpm exec vp lint src

    Control output

    ::warning file=src/index.ts,line=2,endLine=2,col=24,endColumn=29,title=typescript(no-base-to-string)::src/index.ts:2:24: 'value' will use Object's default stringification format ('[object Object]') when stringified.
    ::error file=src/index.ts,line=2,endLine=2,col=24,endColumn=29,title=typescript(restrict-template-expressions)::src/index.ts:2:24: Invalid type used in template literal expression.
    
    Found 1 warning and 1 error.
    Finished in 153ms on 1 file with 111 rules using 4 threads.
    exit=1
    

    Additional attempt

    Setting TSRS_LINT_RUN_EXTERNAL_CODE=1 changed the tsconfig error location but did not fully recover type-aware linting with the available vize version (column 35–41, the .vue extension in contentMappers). The original failure without the env var is consistent with the issue report.

    Result

    Reproduced. The current checkout of vite-plus still launches tsrs-lint without a way to forward --runExternalCode, causing typescript(tsconfig-error) as soon as contentMappers is present in tsconfig.json.

    Diagnosis

    Affected code path

    • packages/cli/src/resolve-lint.ts — resolves the oxlint binary and the environment passed to it.
    • packages/cli/binding/src/cli/resolver.rs — assembles the vp lint subprocess and records which env vars affect vp run caching.
    • node_modules/oxlint/dist/index.d.ts — OxlintOptions only exposes typeAware and typeCheck; there is no runExternalCode (or equivalent) option recognised by oxlint itself.

    Incorrect logic

    resolve-lint.ts sets only OXLINT_TSGOLINT_PATH (pointing at the bundled tsrs-lint) and CONFIG_METADATA_ENV when launching oxlint:

    // packages/cli/src/resolve-lint.ts:44-54
    return {
      binPath,
      envs: {
        ...DEFAULT_ENVS,
        OXLINT_TSGOLINT_PATH: tsrsLintPath,
        [CONFIG_METADATA_ENV]: '1',
      },
    };

    There is no code that:

    1. reads lint.options.runExternalCode (or any other opt-in) from vite.config.ts,
    2. translates it into TSRS_LINT_RUN_EXTERNAL_CODE=1 for the tsrs-lint backend, or
    3. exposes a CLI flag that would let users pass --runExternalCode to the backend.

    resolver.rs also only tracks OXLINT_TSGOLINT_PATH as a cache input for vp run; a config-driven TSRS_LINT_RUN_EXTERNAL_CODE would need to be tracked too.

    Why it causes the observed failure

    With typeAware: true oxlint executes the bundled tsrs-lint backend. That backend rejects a tsconfig.json containing contentMappers unless it is started with --runExternalCode (or the equivalent environment variable), because loading mapper packages means executing external project code.

    Since vp never signals the backend to enable external code, the tsconfig is reported as invalid and lint stops before checking source files. The control run (removing contentMappers) confirms type-aware rules would otherwise report the expected diagnostic.

    Evidence that env propagation works

    Running with TSRS_LINT_RUN_EXTERNAL_CODE=1 changed the reported error location in tsconfig.json (from the contentMappers key to the .vue extension inside it), proving the variable reaches the backend through vp -> oxlint -> tsrs-lint. With a compatible mapper package this is the reporter's workaround.

    Suggested fix approach

    1. Add support for a lint option that vp forwards as TSRS_LINT_RUN_EXTERNAL_CODE=1 when it resolves the lint command. Because OxlintOptions does not currently define a runExternalCode key, augment the type (module augmentation or a new Vite+ option namespace) and read the value before spawning oxlint.
    2. Make the Rust resolver read the same flag from the resolved universal config when caching vp lint inside vp run, and include TSRS_LINT_RUN_EXTERNAL_CODE in the cache_config.env list.
    3. As a short-term documentation mitigation, document the existing TSRS_LINT_RUN_EXTERNAL_CODE environment variable in the type-aware lint guide.

    Edge cases

    • Security: enabling runExternalCode executes project-installed mapper packages, so it should remain opt-in and not default to on.
    • Backend choice: the bundled backend used by vp is tsrs-lint. The Go oxlint-tsgolint backend may not honour the same env variable; vp always routes to tsrs-lint here.
    • Caching: a vp run lint cache must be invalidated when the opt-in changes, otherwise results from a run that enabled mappers could be reused without them.

    Confidence

    High. The failing path is limited to the env vars prepared in resolve-lint.ts, and the observed typescript(tsconfig-error) exactly matches the tsrs-lint help text from the issue.

    Verification

    Claim

    • Observed: vp lint src with lint.options.typeAware: true and tsconfig.json contentMappers exits with typescript(tsconfig-error): Invalid tsconfig.
    • Expected: A supported way to forward --runExternalCode to the tsrs-lint backend (e.g., a lint.options key) or documentation of the existing TSRS_LINT_RUN_EXTERNAL_CODE environment variable.

    Research

    • docs/guide/lint.md documents type-aware linting as using the bundled tsrs-lint backend, but does not mention contentMappers, --runExternalCode, or TSRS_LINT_RUN_EXTERNAL_CODE.
    • rfcs/check-command.md describes the OXLINT_TSGOLINT_PATH override and the vp check cache including that variable. It does not mention a way to pass backend arguments such as --runExternalCode.
    • packages/cli/src/resolve-lint.ts has a // TODO: provide envs inference API comment, indicating the env forwarding is known to be incomplete.
    • Git blame on packages/cli/src/resolve-lint.ts shows the env map has stayed focused on OXLINT_TSGOLINT_PATH and CONFIG_METADATA_ENV; no commit added a runExternalCode opt-in.
    • No prior issue or PR in voidzero-dev/vite-plus mentions runExternalCode or contentMappers.
    • CLI snapshot crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/check_oxlint_env only verifies OXLINT_TSGOLINT_PATH behaviour.

    Verdict

    bug

    Vite+ explicitly replaces the type-aware backend with tsrs-lint and documents type-aware linting as a supported feature. The inability to opt into tsrs-lint's --runExternalCode mode makes the integration fail for any project that uses tsconfig contentMappers, which is a supported tsrs feature. There is no documentation or code signal that this was intentionally left unsupported; the TODO in resolve-lint.ts and the undocumented env-variable workaround both point to an unfinished integration.

    Confidence

    high

    Fix

    Changed files

    • docs/guide/lint.md — documented TSRS_LINT_RUN_EXTERNAL_CODE in the Type-Aware Linting/Content Mappers section.
    • packages/cli/binding/src/cli/resolver.rs — added TSRS_LINT_RUN_EXTERNAL_CODE to the environment variables tracked for vp lint (and the lint phase of vp check) when computing task-cache fingerprints.
    • packages/cli/binding/src/cli/handler.rs — added TSRS_LINT_RUN_EXTERNAL_CODE to the tracked env list for the composite vp check command in task scripts.

    Rationale

    The reporter's first choice — a lint.options.runExternalCode key in vite.config.ts — is not viable without an upstream Oxlint change. Oxlint loads vite.config.ts to read the lint block and validates options against its own schema; adding an unknown key produces unknown field \runExternalCode`` before linting starts.

    The existing TSRS_LINT_RUN_EXTERNAL_CODE environment variable already reaches the bundled tsrs-lint backend through Oxlint. The minimal Vite+ change is therefore:

    1. Document the variable so the supported path is discoverable.
    2. Include it in the task runner's cache key so vp run lint / vp run check correctly invalidates cached results when the opt-in changes.

    Trying lint.options.runExternalCode (reverted)

    I implemented the config-key approach first, including type augmentation and config loading in packages/cli/src/resolve-lint.ts. A test run with runExternalCode: true in vite.config.ts immediately failed with:

      x Failed to parse oxlint configuration file.
        unknown field `runExternalCode`, expected one of `typeAware`, `typeCheck`, ...
    

    That confirmed the option must be introduced in Oxlint's schema before Vite+ can expose it in the lint block. I reverted all TypeScript/source changes and switched to the env-variable fix.

    Validation

    • pnpm -F vite-plus test --run resolve-lint.spec — passed (7 tests).
    • cargo test -p vite-plus-cli cli::resolver:: --release — passed (3 tests).
    • cargo clippy -p vite-plus-cli --release -- -D warnings — no warnings.
    • cargo fmt --all --check — clean after formatting.
    • Reproduction:
      • pnpm exec vp lint src still reports typescript(tsconfig-error) on contentMappers (expected without the env var).
      • TSRS_LINT_RUN_EXTERNAL_CODE=1 pnpm exec vp lint src reaches the backend (error column moves from the contentMappers key to the .vue extension, as it did in the reproduce step).
      • Removing contentMappers reports typescript(restrict-template-expressions) normally.

    Repro project after fix

    vite.config.ts:

    import { defineConfig } from "vite-plus";
    
    export default defineConfig({
      lint: {
        options: { typeAware: true },
        rules: { "typescript/restrict-template-expressions": "error" },
      },
    });

    Users now follow the docs and run:

    TSRS_LINT_RUN_EXTERNAL_CODE=1 vp lint

    Diff summary

    docs/guide/lint.md                       |  5 +++++
    packages/cli/binding/src/cli/handler.rs  |  5 ++++-
    packages/cli/binding/src/cli/resolver.rs | 31 ++++++++++++++++++++++++++++++-
    

    Skipped checks

    • Full vp check / just check / repository-wide snapshot suite were not run because the changed layer is the Rust CLI binding plus a documentation line; focused Rust tests, clippy, and fmt cover the code change, and the reproduction verifies end-to-end behavior.

    Commit message

    fix(cli): track TSRS_LINT_RUN_EXTERNAL_CODE for type-aware lint caching and document it

    This report was made by an LLM. The analysis may be wrong, and the potential fix might not work, but is intended as a starting point for exploring the issue.

    I've opened a pull request with this fix: #3477

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

Metadata

Metadata

Assignees

No one assigned

    Type

    Fields

    Priority

    None yet

    Effort

    None yet

    Target date

    None yet

    Start date

    None yet

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions