Provenance collapses to the entry schema on `@zenstackhq/language` >= 3.8.0 (Langium 4 `CstNode` rename): one-line fix, plus a question about project status

[matijaboban]

Hi @sheldonj, and thanks for building this and putting it out under MIT. We generate a 1345-page reference site from a ZModel schema with it, and one of the things we rely on it for is looking up where a given model or enum is actually declared.

I'm combining two things in one issue: a fix I think is worth having whatever happens next, and a question about where the project stands that I'd rather ask than guess at.

The symptom

After moving to ZenStack 3.9.0, every generated page attributes its declaration to the merged entry schema instead of the file it was written in:

- **Defined in:** `enums/account__level.zmodel`
+ **Defined in:** `schema.zmodel`

For us that is 1343 declarations across 1345 pages. Provenance only; no model, field, type or attribute changed.

The cause

It's a Langium rename rather than anything to do with import merging. In getSourceFilePath:

const cstDocument = node.$cstNode?.root?.element?.$document?.uri?.fsPath;
if (cstDocument) return cstDocument;
let root = node;
while (root.$container) root = root.$container;
return root.$document?.uri?.fsPath;

CstNode.element became CstNode.astNode in Langium 4. The first lookup is therefore always undefined, so the function falls through to the container walk below it, and that walk resolves to the entry document. The fallback is doing exactly what it was written to do; it just isn't a fallback any more, it's the only path.

Langium 4.2.4's CstNode (lib/syntax-tree.d.ts) has no element member at all:

/** The AST node created from this CST node */
readonly astNode: AstNode;

Where the boundary is

The transitive bump lands on one specific release: @zenstackhq/language moved Langium at 3.8.0.

@zenstackhq/language	langium
3.3.3 – 3.7.2	3.5.0
3.8.0 and later	4.2.4

That also explains why CI here is green. package.json declares the peer range as >=3.0.0 but pins ^3.3.3 in devDependencies, so the suite runs against Langium 3.5.0, where .element is still correct. Nothing in the current matrix reaches Langium 4. The open dependabot PR on the zenstack group (#12) moves 3.4.5 to 3.4.6, which stays on Langium 3.5.0.

Worth saying plainly: you already wrote the test that catches this. test/integration/multifile.test.ts asserts exactly the right property —

expect(userDocument).toContain('models.zmodel');
expect(roleDocument).toContain('enums.zmodel');
expect(tsDocument).toContain('mixins.zmodel');

On Langium 4 all three of those resolve to schema.zmodel, so that test should go red the moment the dev dependency crosses 3.8.0. No new test needed; the existing one just can't see the regression at the pinned version. (The single-file snapshot test looks unaffected, since it generates from an inline schema and redacts the schema filename.)

The fix

One line, and backwards compatible with Langium 3:

const cstDocument = (node.$cstNode?.root?.astNode ?? node.$cstNode?.root?.element)?.$document?.uri?.fsPath;

I verified this by running it rather than by reading it. On a two-file repro (schema.zmodel importing ./models/thing, with one model and one enum in the partial), both provenance lines on both generated pages change from schema.zmodel to models/thing.zmodel. On our real schema the same change reverts all 1343 lines to their authoring partials, symmetrically (2686 insertions, 2686 deletions), with nothing else in the diff.

The question

We're carrying this locally as a patch against 0.2.1, so nothing is blocked on our side and there's no urgency here.

What I mainly wanted to ask is where the project stands. I can see #16 and #19 have been open since March and April. Rather than adding another PR to that queue and assuming it helps, I'd rather ask:

• Is this still something you're actively maintaining, or is it closer to "works, not currently being developed"? Either answer is completely reasonable; knowing which just helps us decide whether to keep carrying patches locally.
• If help would be welcome, is there a shape that would actually suit you? A PR for this one fix, some issue triage, or something more ongoing like a co-maintainer.
• Given what's already open, would you rather have a fix like this as its own small PR, or folded in with something else?

Happy to open the PR whenever it's useful, and equally happy to leave it if you'd rather not take contributions right now. It's your project and your call. Either way, thanks for the plugin; it's done real work for us.