Background
Following #163, Runner.render(source:originalPath:) made originalPath optional
(String? = nil) so a developer can render a bare string of SyntaxKit DSL without inventing
a path. originalPath is purely a diagnostic label — it feeds the #sourceLocation(file:)
directive in WrappedSource and the stderr path-rewrite in processFile; nothing is opened,
and the output cache keys off the source bytes (not the path), so the label never affects
caching or the rendered output.
When originalPath is nil, processFile currently falls back to a hardcoded literal:
// Runner.processFile
let absoluteInputPath =
originalPath.map { URL(fileURLWithPath: $0).standardizedFileURL.path }
?? "source.swift"
This works and is covered by tests, but the fallback was chosen quickly and deserves a
second look.
Questions to revisit
- Magic string.
"source.swift" is an inline literal. Should it be a named constant
(e.g. WrappedSource.defaultOriginalPath, its semantic owner) so the label has one home
and is discoverable? (An earlier attempt to add this constant was deferred in favor of just
making the parameter optional.)
- Best fallback behavior. Options when no path is given:
- Synthetic filename label — current (
"source.swift"), so diagnostics read
source.swift:3:5: error: ….
- A clearly-synthetic marker like
"<source>" / "<in-memory>" (signals "not a real
file", but verify #sourceLocation + any downstream tooling tolerate angle brackets).
- Omit
#sourceLocation entirely for anonymous snippets — most "honest", but then
diagnostics reference the internal temp wrapper (Input.wrapped.swift) with wrapper-
relative line numbers, which is likely worse for users.
- Label collisions. Two distinct anonymous snippets both report
source.swift in their
diagnostics. Harmless today (no cache collision — keyed on source bytes), but worth a note
in the docs, or an optional caller-supplied label could disambiguate.
- Batch parity. The batch entry point
render(sources: [RenderInput]) requires a
RenderInput.url. Should there be an ergonomic path for rendering a batch of anonymous
in-memory snippets too (optional/derived identifiers), or is that out of scope?
Acceptance
Decide and document the intended behavior for the no-path case; if a named constant or a
different fallback is chosen, update Runner.processFile / WrappedSource and the tests
(RunnerRenderFailureTests, RunnerBatchRenderTests) accordingly.
Context: implemented on branch feature/163-filesystem-free-render.
Background
Following #163,
Runner.render(source:originalPath:)madeoriginalPathoptional(
String? = nil) so a developer can render a bare string of SyntaxKit DSL without inventinga path.
originalPathis purely a diagnostic label — it feeds the#sourceLocation(file:)directive in
WrappedSourceand the stderr path-rewrite inprocessFile; nothing is opened,and the output cache keys off the source bytes (not the path), so the label never affects
caching or the rendered output.
When
originalPathisnil,processFilecurrently falls back to a hardcoded literal:This works and is covered by tests, but the fallback was chosen quickly and deserves a
second look.
Questions to revisit
"source.swift"is an inline literal. Should it be a named constant(e.g.
WrappedSource.defaultOriginalPath, its semantic owner) so the label has one homeand is discoverable? (An earlier attempt to add this constant was deferred in favor of just
making the parameter optional.)
"source.swift"), so diagnostics readsource.swift:3:5: error: …."<source>"/"<in-memory>"(signals "not a realfile", but verify
#sourceLocation+ any downstream tooling tolerate angle brackets).#sourceLocationentirely for anonymous snippets — most "honest", but thendiagnostics reference the internal temp wrapper (
Input.wrapped.swift) with wrapper-relative line numbers, which is likely worse for users.
source.swiftin theirdiagnostics. Harmless today (no cache collision — keyed on source bytes), but worth a note
in the docs, or an optional caller-supplied label could disambiguate.
render(sources: [RenderInput])requires aRenderInput.url. Should there be an ergonomic path for rendering a batch of anonymousin-memory snippets too (optional/derived identifiers), or is that out of scope?
Acceptance
Decide and document the intended behavior for the no-path case; if a named constant or a
different fallback is chosen, update
Runner.processFile/WrappedSourceand the tests(
RunnerRenderFailureTests,RunnerBatchRenderTests) accordingly.Context: implemented on branch
feature/163-filesystem-free-render.