RFC: Add parser-level scene analysis API for editor tooling

[luochen211]

Background

I previously opened PR #969 to add a parser-level scene analysis API. The PR was closed with a reminder to read the contribution guide, which asks contributors to open an Issue and discuss the design before starting larger features. This issue is intended to follow that process before submitting a new implementation PR.

Problem

Editor and tooling code need structured information from WebGAL scene scripts, including labels, scene references, choices, assets, variables, command summaries, and lightweight diagnostics. Today, this kind of analysis is easy to duplicate in downstream tools such as WebGAL Terre. Duplicated parsing logic can drift from the real parser behavior and makes future editor features harder to maintain.

Proposal

Add a parser-level scene analysis API that can be reused by the engine, editor, and external tooling. A possible API shape is:

SceneParser.analyze(options?: SceneAnalyzerOptions): SceneAnalysisResult
analyzeScene(scene: IScene, options?: SceneAnalyzerOptions): SceneAnalysisResult

The result would include:

• defined labels and duplicate-label diagnostics
• label and scene references
• choices and their target scenes
• assets grouped by type
• variable reads, writes, and conditions
• command usage summaries
• warnings for missing labels, unknown scenes, empty choices/assets, and simple unreachable-flow hints

Design notes

The analyzer should consume the parser's existing IScene / ISentence output rather than re-parsing raw script text. This keeps analysis behavior aligned with the parser and avoids maintaining a second script parser in editor code.

Some robustness points from the previous review should be handled in the new design:

• avoid module-level global regex state for variable extraction
• avoid regex patterns that can cause excessive backtracking when stripping string literals
• do not flag lines after conditional terminal commands such as changeScene -when=... as definitely unreachable
• resolve known scene paths consistently with or without a leading slash
• avoid reporting line 0 for assets that do not carry an explicit line number

Testing plan

A PR for this should include focused tests for the public API, for example:

• duplicate and missing label diagnostics
• scene references from changeScene, callScene, and choices
• variable extraction from setVar, if, and -when arguments
• conditional terminal commands not producing false unreachable warnings
• leading-slash scene resolution
• asset warning line-number fallback

Expected local checks:

cd packages/parser && yarn vitest run parser.test.ts
cd packages/parser && yarn build-ci

Related work

• Previous PR: feat: add scene analysis API #969
• WebGAL Terre editor-side companion PR that should depend on this parser API: feat: add scene insight model for editor WebGAL_Terre#617