feat(repl): analyze each loaded file as a workspace document of its own

[devin-ai-integration]

What and why

Files loaded from the command line (-validate, -satisfy, -check, -run, …) or by %load were joined into the transcript document (<repl>, with a synthetic <repl>.kerml for KerML files) and analyzed as one text. That buffer had semantics of its own: a root-level import in one file served every other file, and two files declaring the same root package were reported as a duplicate. The editor, the corpus gates and the pilot tools analyze the same files through model.Workspace, one document per file, and report the opposite — unresolved reference: Real in the file that does not import it, and no duplicate.

Each loaded file is now a workspace document under its own name, indexed together with the others and analyzed on its own; typed submissions still form the one joined transcript document. Concretely, in internal/repl:

Session.openDocuments()      opens <repl> for the typed text (loaded files masked out) and one
                             document per loaded file, and removes documents of dropped snippets
Session.symbolIndex()        adds every session document to one index, expands wildcards once,
                             takes back documents that went (idxDocs)
Session.locatedDocs()        every session document with its base offset in the joined buffer
Session.sessionMembers()     []Member{Node, Offset, scope}: top-level members of every document,
                             in buffer order, offsets translated to the joined buffer
Session.diagnostics()        transcript + per-file diagnostics, offsets translated, sorted
Result.Members               []ast.Node -> []Member (loaded documents have offsets of their own)

Readers of s.ws.Document(docName) that assumed every declaration lived in <repl> — %calc, %sweep, %analyze, %print, the compound-expression path of %eval, promptScope, symbolsInLoadOrder (%view) — now go through hasDeclarations() / sessionDocs() / sessionMembers() / rootScopeOf(sym); nothing re-joins the files behind the scenes. %print can print a declaration of any loaded file rather than only of <repl>/<repl>.kerml. %save is unchanged: it writes each snippet's own text back.

Two user-visible changes for multi-file loads, both the behavior model.Workspace already had:

• A root-level import in one file no longer serves the other files, nor — after %load a.sysml — the text typed at the prompt. Root packages remain reachable through the global namespace as before, and the prompt still evaluates in the last namespace declared, which may be one a loaded file declares.
• Two files declaring package A are two root namespaces of that name, not a duplicate; a reference to A resolves to the declaration in the file whose name sorts first — the order the workspace gives documents, whatever order the files were given in on the command line (TestRepeatedRootPackageResolvesByDocumentNameNotLoadOrder pins both orders).

The compound-expression path of %eval parses the expression appended to the transcript with the loaded files masked out (as the transcript document has them), so a loaded file's text can no longer fail the parse of a prompt expression; the expression is still evaluated in promptScope().

This is the first of two PRs: the parallel batch pipeline over these documents (parallel parse, one index and one wildcard expansion per batch, a worker pool with a private passes.Context per worker, diagnostics in document order, a workers setting, the -split-planes generator mode and the measurements) follows in #312. Merge order: this PR first, then #312.

Existing internal/repl tests were examined individually; none asserted the import leak or the duplicate, so none was changed. TestTargetlessPseudoViewSpansLoadedDocuments and TestLoadFilesSummaryMatchesLoadingEachFile failed during the migration and were fixed in the code (symbolsInLoadOrder sorting by buffer offset; Result.ownMembers filtering by the buffer offset), not in the tests.

Known behaviour

Two prompt evaluation rules predate this change and are kept as they are (documented under "Known behaviour" in the loading section of docs/guide/04-repl.md); both are open to change. A prompt expression evaluates in the last namespace declared (promptScope), so when a loaded file declares it, the expression sees that file's root imports although a typed declaration does not — %eval 1.5 as Real resolves after loading private import ScalarValues::*; package A { … } while a typed attribute y : Real; reports Real unresolved; the alternative is a fallback to the transcript's own root. A qualified command argument (%eval A::y, %print A::y) goes through the single index-based lookupSymbol, which holds every document's declarations, so with two loaded package A it reaches the second A's member that a model reference or a compound expression cannot; the alternatives are a resolver-based lookup for the evaluating commands, or rejecting a root that resolves ambiguously. Both were already so on develop (the second for a .kerml/.sysml pair); per-file loading makes them reachable with any two files.

Specification basis

KerML 8.2.3.3 and 8.2.4: a root-level import surfaces its names in the importing document's own root namespace (docs/project/spec-compliance.md, row "A root-level import X::* surfaces its names in the importing document's own root namespace"). KerML 8.2.3.5: two root namespaces of the same name are neither an ambiguity nor a duplicate, and resolution uses the first declaration (docs/project/pilot-xpect.md, "The global namespace…", item 1; TestNameResolutionPassResolvesARepeatedTopLevelNameToTheFirst). No compliance row moves; the command line converges on what those rows already certify for the workspace.

How it was verified

New in internal/repl/filedocs_test.go:

• TestLoadedFilesDoNotShareRootImports — a.sysml with private import ScalarValues::*;, b.sysml using Real: the command line reports unresolved reference: Real in b.sysml, and its diagnostics equal model.Workspace's over the same files.
• TestLoadedFilesDeclaringOneRootPackageAreNotDuplicates — two package A files plus a file referencing A::X (first declaration) and A::Y (second): no duplicate, A::X resolves, diagnostics equal the workspace's.
• TestPromptDoesNotSeeALoadedFilesRootImports — after %load a.sysml, typed text still reaches A but not a bare Real.
• TestCommandLineLoadMatchesWorkspace — every multi-file directory under testdata/, examples/ and the four OMG corpus roots (examples/sysml-v2-training, examples/pilot-corpora/{kerml-examples,sysml-examples,sysml-validation}) run through the command-line load and through model.Workspace yields the same diagnostics. All four fail on develop.

Gates, all run locally:

gofmt -l .                       (nothing)
go build ./...                   ok
go vet ./...                     ok
go test ./...                    ok
go test -race ./...              ok
OPENSYSML_REQUIRE_TRAINING_CORPUS=1 OPENSYSML_REQUIRE_PILOT_CORPORA=1 \
  go test -count=1 ./internal/core/model -run 'TestTrainingExamples|TestPilotCorpora'   ok
make docs-check                  ok
make docs-counts                 (test-function count moved by the four new tests; README.md and
                                 docs/project/spec-compliance.md regenerated)

training_examples_expected.txt is unchanged and empty; no pilot ratchet moved.

By hand: sysml -validate a.sysml b.sysml on the import case (unresolved reference: Real in b.sysml, exit 2) and on the same-name-package case (clean; the existing note that A is opened by more than one loaded file still prints), and %load of several files followed by %print, %view, %eval of a compound expression and %save (each file's text written back verbatim). The REPL's own name lookup (%print A, %view A) still reports a root name two loaded files declare as ambiguous, as it did before; model resolution (A::X) takes the first declaration.

Checklist

• make test and make lint pass locally
• Tests added or updated for the change
• Documentation extended where it already covers the surface (docs/reference/cli.md "Multiple Files", docs/guide/04-repl.md loading section)
• Changelog entry added as changes/unreleased/per-file-documents.changed.md, not as an edit to CHANGELOG.md
• baselines regenerated and make docs-counts run if a gate count moved
• No internal work-item labels in the body, docs, or changelog

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[devin-ai-integration]

Devin Review found 1 new potential issue.

1 flag not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)

[devin-ai-integration]

🟡 Transcript-name file drops declarations

A loaded file named <repl> shares openDocuments' transcript key. The next load or prompt submission overwrites one document, making valid declarations unreachable.

Learn more

The workspace identifies documents by name. The transcript always uses <repl>, while loaded files now use their path directly. A user can create a file literally named <repl> and load it with %load "<repl>". On the next submission, openDocuments opens both sources under the same key, so the second open replaces the first.

Example: Load %load "<repl>", then type package Typed { part def A; }. The loaded file's later open replaces the transcript document, so Typed::A no longer resolves.

Recommended fix: Give loaded documents collision-free internal workspace keys while retaining their original paths for diagnostics and display. Apply the mapping consistently to snippets, symbol DocName values, index entries, lookups, source registration, and document removal.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Same finding as the earlier thread on these lines (#309 (comment)): confirmed, reachable only through a SourceFile.Name that is the literal string <repl> (every loader passes the path the file was read from; standard input is <stdin>), so on the command line it takes a file literally named <repl> in the working directory.

Closing it changes the SourceFile contract rather than the per-file migration, so it stays open for a maintainer decision between (1) documenting <repl> as the transcript's reserved name, (2) refusing a load under that name at LoadPaths/SubmitFiles, or (3) keying loaded documents apart from their names with a display name mapped back everywhere sym.DocName is shown (%explain, the debuggers, file:line:col). Left unresolved until then.