OriginLens — Trace Variable Origins in VS Code

OriginLens is a local static-analysis extension that shows which assignments can reach a Python, JavaScript, or TypeScript variable at the exact point where it is used.

Why OriginLens?

Following a variable through branches, loops, and reassignments can turn a small debugging question—“where did this value come from?”—into a long manual search. Find All References shows every occurrence, but it does not tell you which assignments can actually reach the use you are inspecting.

OriginLens performs intraprocedural reaching-definitions analysis in the VS Code extension host. Hover a local-variable read to see its possible origins, or run OriginLens: Trace Variable Origin to choose an origin and jump directly to it. When available, OriginLens includes conservative path conditions such as enabled or not (enabled).

Features

• Finds the local assignments and parameters that may reach a variable use.
• Distinguishes definite, possible, parameter, and loop-carried origins.
• Shows best-effort control-flow conditions for branches, loops, catches, and switch cases.
• Provides clickable source links in hovers.
• Opens a Quick Pick for choosing and navigating to a specific origin.
• Handles lexical shadowing and keeps nested function bindings separate.
• Supports optional, cursor-focused inline origin-count hints.
• Caches analysis by document version and invalidates it after edits.
• Runs locally without telemetry, remote analysis, or an AI service.

Supported languages

OriginLens activates for these VS Code language IDs:

Supported Python constructs include parameters, plain and annotated assignments, augmented assignments, tuple/list destructuring, if/elif/else, for, while, break, continue, return, try/except/else/finally, with, and assignment expressions in if conditions.

Supported JavaScript and TypeScript constructs include parameters, let/const/var, direct and compound assignments, object/array destructuring, if/else, switch, for, for...of, for...in, while, do, break, continue, return, try/catch/finally, normal functions, methods, and arrow functions.

Examples

Python

def price_for(user, discount):
    price = user.base_price

    if user.is_premium:
        price = price * 0.8

    if discount:
        price = apply_discount(price, discount)

    return price  # Hover over price to inspect its possible origins.

TypeScript

function valueFor(enabled: boolean): number {
  let value = 10;

  if (enabled) {
    value = 20;
  }

  return value; // Paths: not (enabled) for 10, enabled for 20.
}

See OriginLens in action

Hover over a variable

The hover lists the reaching source line, certainty, and any conservative path conditions or analysis notes.

Trace Variable Origin

Run OriginLens: Trace Variable Origin with the cursor on a variable read. Choose an origin from the Quick Pick to navigate to its assignment.

Installation

VS Code Marketplace

1. Open the Extensions view in VS Code (Ctrl+Shift+X on Windows/Linux or Cmd+Shift+X on macOS).
2. Search for OriginLens.
3. Select Install.

You can also install it from a terminal:

code --install-extension originlens.originlens

VSIX

Download a release VSIX, then run Extensions: Install from VSIX... from the Command Palette and select the file. Alternatively:

code --install-extension ./originlens-0.1.0.vsix

Reload VS Code if prompted. OriginLens activates when you open a supported source file.

Commands

Open the Command Palette and run:

Inline hints are disabled by default and annotate only the variable at the current cursor or an explicitly traced variable.

Settings

The timeout is a reporting budget for synchronous document analysis; it does not forcibly interrupt a parser call.

Privacy

OriginLens analyzes source code entirely inside the local VS Code extension host. It makes no network requests, sends no telemetry, uses no AI service, and does not log source text. The VS Code test downloader and VSIX packaging tools are development-only.

Known limitations

OriginLens is intentionally focused on local, intraprocedural data flow:

• Property reads and writes, dynamic indexing, imports across a project, and values inside called functions are not resolved.
• Reflection, monkey patching, eval, and Python exec are not modeled.
• Closure captures not defined in the analyzed function may appear as unsupported or non-local origins.
• Exception flow and JavaScript switch fallthrough are conservative.
• finally handling does not fully rewrite every abrupt return, throw, break, or continue path.
• Python comprehensions, pattern matching, global, nonlocal, generators, async control flow, and multiple with targets are not fully specialized.
• Labeled JavaScript break/continue and generators are not specialized.
• Assignment expressions are modeled precisely in Python if conditions, but not in every expression context.
• Path conditions are readable explanations, not symbolic proofs that a condition is sufficient at runtime.

See Known limitations for the complete precision notes and Architecture for implementation details.

Development

Development requires Node.js 20 or newer and npm.

npm install
npm run compile
npm run bundle

Press F5 or use the included Run OriginLens Extension launch configuration to open an Extension Development Host. During development, npm run watch watches TypeScript and npm run bundle:watch watches the extension bundle.

See the development guide for more detail.

Testing

Run the complete validation suite before submitting changes:

npm run check
npm run lint
npm run format:check
npm run test:unit
npm run test:extension

The extension-host suite requires a graphical session and downloads VS Code 1.105.1 into .vscode-test on first use. A generated-branch performance check is also available:

npm run benchmark

Benchmark results are intended as a local regression signal, not a cross-machine guarantee.

Packaging

Build a production bundle and package the extension as a VSIX:

npm run package

The package lifecycle runs the type checker and linter, creates a minified production bundle, and invokes vsce. The resulting originlens-0.1.0.vsix can be installed with Extensions: Install from VSIX... or the code --install-extension command shown above.

Contributing

Contributions are welcome. Keep changes focused, add observable tests for semantic behavior, and update the limitation notes whenever analysis precision changes. Read CONTRIBUTING.md before opening a change.

License

OriginLens is available under the MIT License.