Refactor Location tracking to be an offset-based Locatable model

[TwitchBronBron]

Implements #1843.

Tokens and AST nodes now carry their position as startPosition / endPosition / sourceInfo (a SourceInfo shared by everything from the same parse) instead of a location: Location object tree. util.getLocation(item) builds a line/character Location on demand.

Compatibility: location and range stay on tokens and nodes as deprecated accessors, computed on every read. With #1928 they can also be assigned, Token declares location again, and the create* functions accept a Location or a Locatable. bslint v1 compiles and runs unchanged against it. Diagnostics accept a Locatable and resolve it to a Location only when diagnostics are read.

Review commit by commit

1. Types and producers. Adds Locatable / SourceInfo. The lexer emits offsets and builds linePositions as it scans. Node constructors use util.setBounds() instead of createBoundingLocation(). Creators copy position from an existing Locatable.
2. Readers. Mostly x.location → util.getLocation(x).
3. Transpile and sourcemaps. TranspileState handles both shapes, since XML tokens still use location.
4. Tests. Adds a testLocatable() helper for hand-built parser tokens.

Phases 1–3 don't compile on their own. Later commits are review fixes and the stacked follow-ups (#1865–#1881).

Notes

• The XML/SG side (SGToken, SGElement) is unchanged and still uses Location.
• An end position maps to the line of the last character, so a token ending in a newline keeps its old (L, c+1) end.
• Node bounds are computed once in the constructor. util.setBounds() takes arrays for large lists (spreading 100k+ statements overflowed the stack).
• finalizeClone no longer copies the original's location; clones rebuild it from their cloned tokens.
• Removed: util.createBoundingLocationFromTokens(). TypeChainEntry's location option is now locatable.
• Not included: the location-override WeakMap, the sourcemap last-hit cache, and moving position lookups like getTokenAt to offset comparisons. These can be follow-ups.
• No heap or perf benchmarks have been run yet.

🤖 Generated with Claude Code

[markwpearce]

Can younpm run benchmark:scenarios do get some data on those projects ? feel free to add any local to you projects too in benchmarks/scenarios/projects.local.json (it's gitignored,
see projects.local.example.json):

• name: "big-app"
• path:
• bsconfig: the bsconfig I normally build with
• set "install": true if plugins like bslint/rooibos need their npm deps
• editFiles: pick a widely-used utility file for "shared" and a single
  component's script for "leaf"

[markwpearce]

I ran the scenario benchmarks -- finding an overall ~25% heap memory reduction with this!

[markwpearce]

Scenario benchmarks: this branch vs v1 (bc06b96)

npm run benchmark:scenarios -- run --bsc <v1 build> local --runs 3, best of 3.

Diagnostics are identical to v1 on these four projects, and edits restore cleanly:

project	load	validate	heap	peak RSS	re-validate (shared/leaf, body/api)
roku-googlephotos	-7%	0%	-27% (38.8 → 28.3MB)	-14%	+1 / 0 / -1 / -3%
jellyfin-roku	-11%	-3%	-25% (258 → 195MB)	-22%	-3 / -8 / -8 / -5%
jellyrock	-15%	-2%	-27% (337 → 245MB)	-19%	+1 / +2 / -7 / -6%
jellyfin-fork	-14%	+6%	-15% (285 → 241MB)	-10%	-10 / -5 / +7 / -7%

Heap is consistently down and load is faster. Validate and re-validate times are within run-to-run noise.

Breaks rooibos

The two rooibos projects report different diagnostics, so I'm leaving their timings out:

• brighterscript-game-engine: 467 → 1318 diagnostics
• Unamed OTT App: 276 → 493 diagnostics. It also ends up with fewer files and scopes on this branch (1410 → 1367 files, 363 → 320 scopes), which I haven't traced yet.

The new diagnostics are the same on both:

• RBS2212 General error : Cannot read properties of undefined (reading 'range')
• Duplicate identifier '_' (1175 of them on game-engine)

The throw is in rooibos-roku 6.0.0-alpha.55, dist/lib/rooibos/TestSuiteBuilder.js:158 (createTestCases):

const lineNumber = statement.func.location.range.start.line;

Stack: createTestCases ← processClassMethod ← processClass ← addSuiteIfValid ← processFile ← RooibosPlugin.afterProvideFile.

The Duplicate identifier '_' errors come from the same throw. Rooibos tests are written as function _(), and createTestCases renames each one to a unique rooiboos_test_case_<hash>_<n>. That rename comes after line 158, so every test method keeps the name _.

Other places in rooibos that read .location.range and will hit the same problem:

• Annotation.js:205
• TestGroup.js:80,235
• TestSuite.js:112
• utils/Diagnostics.js:13-21 (every rooibos diagnostic position)
• CodeCoverageProcessor.js (10 places, only reached with code coverage on)

So node.location / token.location going away is a breaking plugin API change. The options are to keep a lazy location getter on nodes and tokens (built via util.getLocation()) for compatibility, or to update rooibos (and probably bslint) alongside this PR.

[TwitchBronBron]

Looking really good so far! I haven't even reviewed this yet, so will try and do that early next week. But I'm thinking we might be able to get some similar gains with similar techniques acrouss the codebase. flattening certain things that don't need to be so nested.

I'm totally happy with this being a huge breaking change, it's well worth it.

[markwpearce]

Consider adding getters and setters for location & range - allows this not to be so huge a breaking change.

AstNode

/**
 * @deprecated use `util.getLocation(node)`. Computed on every read
 */
public get location(): Location | undefined {
    return util.getLocation(this);
}
public set location(value: Location | undefined) {
    util.setLocation(this, value);
}

/**
 * @deprecated use `util.getLocation(node)?.range`
 */
public get range(): Range | undefined {
    return util.getLocation(this)?.range;
}

Token.ts

const tokenPrototype = {
    get location() { return util.getLocation(this); },
    set location(value) { util.setLocation(this, value); }
};
export function createTokenObject(): Token {
    return Object.create(tokenPrototype);
}

--- I'll just make a PR on flatten-locations

[rokucommunity-bot]

Hey there! I just built a new temporary npm package based on 3d97ee7. You can download it here or install it by running the following command:

npm install https://github.com/rokucommunity/brighterscript/releases/download/v0.0.0-packages/brighterscript-1.0.0-alpha.57-flatten-locations.20261016193811.tgz