Skip to content

Revisit the anonymous-snippet diagnostic label in Runner.render(source:) #164

@leogdion

Description

@leogdion

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:
    1. Synthetic filename label — current ("source.swift"), so diagnostics read
      source.swift:3:5: error: ….
    2. A clearly-synthetic marker like "<source>" / "<in-memory>" (signals "not a real
      file", but verify #sourceLocation + any downstream tooling tolerate angle brackets).
    3. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    apiAPI integrationenhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions