DecisionLint

Lint the questions you send to a decision model: TypeSafe's Jev, OpenAI's Decisions API, and every platform that serves either shape, from OpenRouter and Vercel AI Gateway to a llama.cpp on your own machine. DecisionLint reads them out of your JSON and your code, and reports the ones written in a way that is measured to produce bad answers. Linting makes no API calls and needs no key. One optional command asks the model itself to check a file, using your own key, at whichever platform you send it to.

By the author of the LE tools.

Install

• VS Code: search for DecisionLint in the Extensions view, or run ext install nolindnaidoo.decisionlint.

• Cursor, VSCodium and other editors that use Open VSX: the same name, nolindnaidoo.decisionlint.

• Command line: npx decisionlint. Nothing to install first.

• MCP server, for an agent host: npx -y decisionlint-mcp.

Related MCP server: jev-agent-mcp

At a glance

• Lints as you type in JSON, JavaScript, TypeScript, Python, Rust and Go.

• Fixes on the lightbulb for the mechanical mistakes, and a way to silence a finding you disagree with.

• The same rules in CI, from a command line, and for AI agents, from an MCP server. One settings file covers all three.

• Every platform, one set of rules. TypeSafe's /v1/systemone shape and OpenAI's /v1/decisions shape, predicate, choices and levels, are read into the same rules, and the AI SDK's decide() call for either. The limits a request is held to are the platform's own, read from the model id's spelling, a URL in the file or a target setting: Vercel's 255 choices, LiteLLM's 128 questions, none where a platform publishes none.

• Two optional commands that use your own key: one asks the model whether your questions have problems a text pattern cannot see, and one re-sends a question with its layout changed to see whether the answer holds. Both go to the platform the model id names, or to an endpoint you set, a local llama.cpp included.

A request like this one looks fine and has three problems:

{
  "model": "jev-latest",
  "state": "My parcel came three days late and the lid is cracked.",
  "questions": {
    "team": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": { "billing": "Charges and refunds", "delivery": "Late or damaged parcels" }
    },
    "late": { "type": "noul", "instructions": "Did more than two parcels arrive late?" }
  }
}

What it catches

Jev and Luna guarantee the type of the answer, not the answer. A badly formed question still comes back with a confident-looking number. These rules catch the mistakes that can be read from the text.

Each finding links to its own page, with an example that is flagged, one that is not, how to fix it and how to silence it. Each page links on to the TypeSafe documentation the rule comes from.

Where it looks

• JSON and JSONC request bodies, in TypeSafe's shape or OpenAI's.

• Object literals in JavaScript and TypeScript, including requests passed inline to client.systemOne(...) and client.decisions.create(...), and the Vercel AI SDK's decide({ questions }) for either vendor, with the model id inside typeSafeAi.decisionModel('...') read as the model.

• noul(), choice() and score() calls in files that use @typesafe-ai/sdk.

• Python: dicts, Noul(...), Choice(...) and Score(...) from typesafe_sdk, from LangChain's langchain_typesafe with its NoulCriteria(...), or from a library that wraps either, and requests passed to system_one(...) or client.decisions.create(...).

• Rust: the JSON inside json!, structs and enum variants named for a question type, and ::noul(...) style constructors.

• Go: maps with string keys, structs with a Type field, structs named for a question type, and OpenAI's Go SDK, openai.DecisionNewParams{...} with its OfPredicate, OfChoice and OfScore questions.

• A request pasted as JSON into a string, in any of these languages.

• Any other language: have your program write the request it sends to a .jev.json file and open that. Every check runs on it, and nothing in it is built at runtime, so nothing is skipped.

• jev/ask rules in an oxlint-plugin-jev config.

OpenAI's Decisions API

OpenAI's Decisions API, model gpt-6-luna, asks the same kind of question as Jev in a different shape. DecisionLint reads it from 0.5.0. What that covers, exactly:

• Read. A /v1/decisions request body, client.decisions.create(...) in TypeScript and Python, and the Vercel AI SDK's decide(). A predicate is read as a Noul, choices: [{ value, description }] as a Choice's options and levels: [{ label, description }] as a Score's levels, into the same rules.

• Checked. Every rule with evidence behind it: the missing fallback option, a description that only repeats its name, terse instructions, degree levels, duplicates, counting, an undefined boundary and the rest. Findings name Luna. OpenAI's own guide asks for the same things.

• Held back. DEC002 and DEC003 check a platform's published limits, and OpenAI publishes none, so a request bound for OpenAI gets neither. One bound for a gateway that does, such as Vercel's, gets both. DEC001 is about Jev's moving aliases, and OpenAI has one model id.

• Shape mistakes are reported in OpenAI's own field names: choices written as a map or as bare names, a Choice with no choices, a Score with no levels. A mistyped predicate is fixed on the lightbulb. The reshape fix is Jev-only.

• Asking Luna. Run Ask Luna About This File, or pass --ask-platform openai, with an OpenAI key. The next section says how.

• Measured on Jev, not yet on Luna. Every default in these rules was set by measuring what the defect costs jev-1.13.0. Luna has not been measured, so on a Luna question they are the same rules with Jev's defaults, and every finding from asking Luna says its cutoff was set on Jev. The request sent to Luna follows OpenAI's API reference and has not yet been run against the live API. Both wait on a key.

Every platform

Jev and Luna are two of the models, and TypeSafe and OpenAI two of the places a request can go. Microsoft, Liquid AI and Cloudflare serve their own models in TypeSafe's shape. OpenRouter, Vercel AI Gateway, LiteLLM and LLM Gateway forward to any of them, in either shape. llama.cpp, vLLM and Ollaya run open models on your own machine. DecisionLint reads the two shapes, so every one of them is covered by the same rules. What differs between them is held in one table, src/lint/targets.ts, with the page each fact was read from:

Three things follow from the table:

• The limits a request is held to are its platform's. The platform is read from the model id where its spelling says, from the one platform a URL in the file names, or from target in decisionlint.json or decisionlint.target for a project that sends everything to one place. A platform that publishes no limit gets no finding for it. Nothing says where a request goes: a TypeSafe-shaped question keeps TypeSafe's limits, and any other shape keeps none.

• A floating alias is caught in every spelling, and pinned in the spelling the platform documents: jev-latest to jev-1.13.0, ~typesafe/jev-latest to typesafe/jev-1.13.

• A check with the model goes to the platform the id names, with the key in that platform's variable. A spelling that names no host, such as openai/gpt-6-luna-decisions, which every gateway writes, is refused rather than guessed at, until you set the endpoint. The next two sections say how.

"Open Jev" is not one of these. It is a name used by at least nine unrelated projects that reimplement /v1/systemone; the one llama.cpp serves is ggml-org/OpenJev-GGUF. Each is reached as an endpoint you set.

Ask a model about a file

Rules DEC301 to DEC312 are not part of linting. They run only when you run one of the Ask commands, or pass --ask on the command line. Each sends every question in the file to a decision model and asks it about problems a text pattern cannot see: options that overlap, an option whose name contradicts its description, criteria about the wrong thing, a Choice that should be a Score, two questions that ask the same thing, a question that needs another question's answer.

There is one command per platform, and each has its own key:

1. Give it the platform's key, in any of three ways. Run its Set ... API Key command and paste the key, which stores it in your operating system keychain. Or type it into Settings under decisionlint.ask.keys, by the platform's id, which can only be set in your user settings and is left out of Settings Sync. Or put it in the environment variable the platform names, in the environment VS Code runs in.

2. Open a file with questions and run the platform's Ask command.

The model each command sends is decisionlint.ask.models, by platform. The TypeSafe default is the version the checks' cutoffs were set on, and a finding from any other model, Luna included, says so until that model is measured the same way. The probe asks Jev at TypeSafe, with the TypeSafe key and model.

For a platform you host, a llama.cpp, vLLM, LiteLLM or Ollaya, set decisionlint.ask.endpoint to the full URL it listens at, decisionlint.ask.endpointModel to the model id it serves, and decisionlint.ask.endpointShape to typesafe or openai when the path does not end in /systemone or /decisions. Then run Ask the Model at My Endpoint. It sends the endpoint key if you set one, else the key in TYPESAFE_API_KEY or OPENAI_API_KEY, whichever the shape's SDK reads, or no key when there is none, which is how a local llama.cpp is reached. The endpoint can only be set in your user settings, so a repository cannot point your key at a host of its choosing.

What to know before you run it:

• It uses your key and your credits. One request per question and one more per request body, about 800 input tokens each. At TypeSafe's published price that is roughly three thousandths of a cent per question, and at OpenAI's about a hundredth of a cent.

• Only questions are sent: type, instructions, criteria and ids. Your state is not, unless you turn on decisionlint.ask.sendState. With that on, a state written out in the file is sent too, and two more checks run: does the state hold what each question asks about, and does it carry text that gives orders to its reader.

• A question with a part built at runtime is not sent. The summary says how many were held back.

• A run sends at most decisionlint.ask.maxCalls requests, 25 by default.

• It is disabled in an untrusted workspace. Run Workspaces: Manage Workspace Trust and trust the folder to turn it on.

• Findings disappear when you edit the file, because they were about the old text. Editing or closing the file during a check stops the check.

• Each finding shows the probability Jev gave it. Treat it as an argument with a number attached, not a verdict.

Turn on decisionlint.ask.confirm and it first tells you how many requests it will make, roughly how many tokens and what that costs, and waits for a yes. It is off by default: running the command is the decision to send.

Project settings

Put a decisionlint.json in your project and the editor and the command line both read it, so what you see while writing is what CI reports.

{
  "rules": { "DEC004": "error", "DEC112": "off" },
  "fallbackOptions": ["other", "none", "unsure"],
  "ignore": ["DEC004:department"],
  "exclude": ["fixtures", "**/*.generated.ts"]
}

exclude lists files and folders not to lint, relative to the settings file. ** crosses folders, * stays inside one, and a name with no slash matches at any depth. The editor and the command line leave out the same files.

The nearest file wins, looking from the linted file upward, so a folder can have its own. Where one applies, it replaces the rules, fallbackOptions and ignore settings in the editor. If it cannot be read, nothing is linted and the status bar says why. A key it does not know is an error, so a typo cannot quietly leave a rule on.

To silence one finding, use the lightbulb: Disable DEC004 for this line or for this file writes the comment for you. Strict JSON has no comments, so there a finding is silenced with ignore.

Command line

The same linting runs outside the editor, for CI and for any editor that is not VS Code.

One version for the editor and CI

Install it in the project, as you would any linter:

npm install --save-dev decisionlint

The editor then lints with that copy, not the one the extension carries, so what you see while typing is what npx decisionlint reports in CI. The version changes when package.json does, and for everyone at once. The status bar shows project 0.5.2 while a project's copy is in use.

With nothing installed the extension lints with its own copy, with no setup.

It also uses its own copy, and the status bar says project has 0.2.0 with the reason in its tooltip, when the project's copy cannot be used:

• the workspace is not trusted, because loading the copy runs code from it

• the copy is older than 0.3.0, the first version an editor can load

• the copy fails to load, or does not read that kind of file

When the copy's package.json cannot be read there is no version to show, so the status bar says project copy unreadable, again with the reason in its tooltip.

The Ask commands and the probe always run the extension's own code, whatever the project installs.

npx decisionlint src/                 # a directory, searched for files it reads
npx decisionlint request.jev.json     # one file
npx decisionlint --format github .    # annotations on a pull request

It exits 0 when the run passes, 1 when a finding fails it, and 2 when it could not do what was asked: an unknown option, a missing path, or nothing to read. Errors always fail a run. Warnings fail it only past --max-warnings.

The summary line always says how many questions could not be read in full and names any file skipped for its size and any folder or file it could not read. It does not follow linked folders. It does not run the checks that ask Jev, and it never uses the network, unless you pass --ask.

In CI and before a commit

On GitHub, the action annotates a pull request:

- uses: nolindnaidoo/decisionlint@v1.0.0
  with:
    paths: src

For GitHub code scanning, write SARIF and upload it:

- run: npx decisionlint --format sarif src > decisionlint.sarif
  continue-on-error: true
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: decisionlint.sarif

--format junit writes the XML that Jenkins, GitLab and most test reporters read. Only an error is a failed case there, since only an error fails a run.

With pre-commit:

- repo: https://github.com/nolindnaidoo/decisionlint
  rev: v1.0.0
  hooks:
    - id: decisionlint

Asking a model

--ask runs the checks that ask a decision model, DEC301 to DEC312, after the linting. It is the only option that uses the network, and nothing in a settings file can turn it on.

npx decisionlint --ask-plan src/                    # what it would send. No key, nothing sent
TYPESAFE_API_KEY=... npx decisionlint --ask src/    # send it

• --ask-platform names where it goes: typesafe, openai, openrouter, vercel, llmgateway or liquid, each with a default model in its own spelling and its own key variable, TYPESAFE_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, AI_GATEWAY_API_KEY, LLM_GATEWAY_API_KEY or LIQUID_API_KEY. Without it, --ask-model with a platform's spelling, ~typesafe/jev-latest for OpenRouter, sends there, and a bare id goes to its vendor. The key is read from that variable and from nowhere else, and is never printed.

• --ask-endpoint, or DECISIONLINT_ASK_ENDPOINT, sends to a platform you host, with --ask-shape where the path does not say which shape it takes. A spelling that names no host, such as openai/gpt-6-luna-decisions, is refused without it, with nothing sent.

• A question with a part built at runtime is never sent. The summary counts the ones held back.

• State is not sent unless you add --ask-send-state.

• --ask-max-calls is a limit for the whole run. A run that needs more exits 2, so a job cannot pass after checking part of a project.

• A rejected key, a failed request or a run you stop also exits 2, and says how many requests were answered of how many were planned.

• These findings are warnings or less by default, so they fail a run only when --rule raises one or --max-warnings is passed.

For AI agents

The same program is an MCP server, so an agent that writes Jev or OpenAI Decisions questions can lint what it wrote and fix it before you see it. The tool descriptions and the server's instructions name both vendors and all three request shapes, so an agent knows to call it for any of them.

Agents running inside VS Code get it with no setup: the extension offers the server to the editor, which starts it when an agent calls a tool. For any other client, point it at the server package:

{
  "mcpServers": {
    "decisionlint": { "command": "npx", "args": ["-y", "decisionlint-mcp"] }
  }
}

A project that already pins decisionlint for CI has the same server behind npx decisionlint --mcp. The package with no flag is the one to give a client, because decisionlint started bare is a linter that exits, not a server.

It offers eight tools. lint_text lints a request or source code passed as text and lint_paths lints files on disk, with each finding carrying the edit that would mend it. fix_text returns the text with the safe fixes applied and the report of what is left, and writes nothing. list_rules lists every rule with what it means, and explain_rule returns a rule's own page, with an example that is flagged and one that is not. Those send nothing and need no key.

The other three are the editor's Ask commands and Probe for an agent. ask_model asks Jev, or Luna with model: gpt-6-luna, to check the questions in text or in files, and returns the lint report with the model's findings added. plan_ask says what that would send, and sends nothing. probe_question sends one question with its layout varied and reports whether the answer held. The two that send use your key and cost money, and their descriptions tell an agent to call them only when you ask. The key is read from TYPESAFE_API_KEY or OPENAI_API_KEY in the environment the client started the server with, or from .env.local or .env in the directory it started it in, and never from a tool argument, so no key lands in an agent's transcript. Every tool answers as structured content beside the text, and none writes a file.

It is listed on the MCP registry as io.github.nolindnaidoo/decisionlint, for a client that installs servers from there.

Probe a question

Put the cursor in a question and run DecisionLint: Probe the Jev Question at the Cursor. It sends that question against the state written beside it, three times as written and then with the layout changed: options reversed, option names hidden, levels reversed, criteria removed. A report opens showing whether the answer moved.

If the answer changes when only the order of the options changes, the question is not deciding it. If three identical requests disagree, the input is too close to call.

It needs the state written out in the file, it sends that state, and it costs five or six requests.

Nothing else in this extension uses the network. On the command line, only --ask does.

What it will not tell you

• Whether a well-formed question is right on your data. That needs labeled examples and calls to Jev.

• Anything about a value it cannot see. A question built from variables is reported as unreadable and counted in the status bar. A file is never shown as clean while part of it went unread.

• Everything about wording. DEC101 to DEC112 are heuristics over English text. A rule is on only where a badly written question cost answers or confidence against Jev, in our runs or in someone else's, and it stays on only while it is right on at least 9 of 10 of its findings on public code it was not tuned against. Four that describe failure modes in TypeSafe's docs, DEC104, DEC107, DEC108 and DEC111, did not fail on jev-1.13.0 and are off. Switch any of them on in decisionlint.rules. Two more were removed in 0.4.0 for being wrong every time they fired.

• Anything about a question that is not in English.

• What a lone object lacks. A { type, instructions } outside a questions map may be a template or half of a builder, so a missing criteria is only reported inside a request.

DEC004 is informational because the advice behind it is conditional: add a fallback when the options might not cover every input. It fires on 9 of the 11 Choice examples in TypeSafe's own docs. If your options are exhaustive, turn it off for that question.

Suppressing a finding

In code:

// decisionlint-disable-next-line DEC004
const side = { type: 'choice', instructions: 'Heads or tails?', criteria: { heads: null, tails: null } };

decisionlint-disable-line covers the same line and decisionlint-disable the whole file. Leave the code off to silence every rule.

A comment that silences nothing is reported as DEC010, so one left behind after its finding was fixed cannot hide a new finding later.

What was written for JevLint-LE still works: a jevlint-le-disable comment, and the JEV codes in a comment, in rules or in ignore, are read for ever. Every finding is written with the DEC code.

Fixing

Some findings can be mended without a decision from you: a Noul criteria key written yes where the API takes true, a mistyped question type, criteria in the wrong shape. npx decisionlint --fix writes those, and the summary of any run says how many it would mend.

In the editor, fix on save does the same:

{ "editor.codeActionsOnSave": { "source.fixAll.decisionlint": "explicit" } }

Adding a fallback option and pinning a model change what a working request does, so they are never written for you. They stay on the lightbulb.

JSON has no comments, so use the setting:

{ "decisionlint.ignore": ["DEC004:side"] }

Keyboard shortcuts

Every command can be given a shortcut. Open Keyboard Shortcuts, search for DecisionLint, and press the keys you want on any command in the list. None is bound out of the box, so nothing here can collide with a shortcut you already use.

Or write them into keybindings.json. The keys here are only an example:

[
  { "key": "ctrl+alt+j", "command": "decisionlint.lintFile", "when": "editorTextFocus" },
  { "key": "ctrl+alt+k", "command": "decisionlint.askJev", "when": "editorTextFocus" }
]

The Ask commands and the probe send requests with your key, so pick keys for them you will not press by accident.

Settings

Development

bun install
bun run typecheck && bun run lint && bun run test
bun run build
bun run test:integration   # real VS Code against samples/
bun run package            # release/decisionlint-<version>.vsix
bun run test:e2e-vsix      # the packaged VSIX in a clean profile

AGENTS.md is the engineering standard. SPEC.md is what the product is and what is planned. samples/ is a workspace with planted mistakes, used by bun run test:integration, which drives a real VS Code.

License

MIT