Skip to content

source-navigation.md

Latest commit

 

History

History
59 lines (37 loc) · 5.33 KB

source-navigation.md

File metadata and controls

59 lines (37 loc) · 5.33 KB
Raw

Navigate Scarp names and references (v0.0.6-alpha.3)

Scarp alpha.6 introduces static, opt-in source intelligence. You can ask which identifiers are declared or used in an imported module without running the program. This is a compiler feature, not an LSP server, editor integration, automatic rename or an incremental cache.

This tutorial reuses the two-module project that already has an exact interpreter output fixture. The public answer binding is declared in src/lib/math.srp, then accessed via the math import alias in src/main.srp.

Run the commands

First install or build the exact pinned prerelease. From the course root:

scarp verify tutorials/module-inspection
scarp inspect modules --json tutorials/module-inspection
scarp inspect symbols --json tutorials/module-inspection
scarp inspect references --json tutorials/module-inspection
scarp launch tutorials/module-inspection

The two new inspect commands produce metadata on stdout. launch is the only command here that runs the ordinary statements and prints 42 followed by a newline, matching the project's fixture. There is no corresponding .stdout lesson for a JSON index.

Both inspect commands also accept tutorials/module-inspection/src/main.srp instead of the directory. They resolve the import and type-check the full source graph. File display labels may differ between paths and operating systems; avoid comparing raw JSON byte-for-byte across machines.

How to read the JSON

Both views use schema_version: 1, span_encoding: "utf-8-bytes", column_encoding: "unicode-scalar" and one-based line/column positions. The kind is "scarp.symbols" or "scarp.references". Expect:

  • files: discovered source-file IDs and display paths.
  • symbols: definitions and other named identities, such as the math alias and public answer. Some builtins have no source location.
  • references (reference view only): each use site's target symbol ID, use kind and source location.

A location.span is a half-open UTF-8 byte range, not a Unicode character count. Symbol IDs are only valid inside that one result. After editing a file or running inspection again, rebuild the index instead of caching IDs. The compiler checks imports, privacy and names; errors return nonzero with no partial JSON.

Why read-only matters

Try a disposable file with print(1 / 0);. inspect symbols --json FILE and inspect references --json FILE can succeed because they do not evaluate runtime arithmetic. exec FILE fails at runtime. Conversely, an unknown identifier fails inspection because static name resolution still applies. The CLI regression test checks these boundaries and the project/file consistency against the released compiler.

Exercise: inspect the two-module project, locate the answer declaration and the reference in the entrypoint, then compare the file and directory views while ignoring platform-specific display paths.

See the compiler's versioned index contract and Hindi companion guide. No general editor integration or browser-side Scarp execution is implied.

Advanced workshop: shadowing and named arguments

Continue with the source-navigation workshop and its website page. The two-file source is adapted from the tagged alpha.6 compiler example and retains the upstream exact output of 30 followed by a newline.

scarp verify tutorials/source-navigation
scarp inspect symbols --json tutorials/source-navigation
scarp inspect references --json tutorials/source-navigation
scarp inspect references --json tutorials/source-navigation/src/main.srp
scarp launch tutorials/source-navigation

The main source defines base twice, in separate scopes. The inner binding's initializer reads the outer base; total += base reads the inner one. The named argument value: points to the parameter of twice, and n: to the parameter of imported adjust. The imported private_seed remains private.

Try it: find both source-backed definitions and their references; predict the final output before calling launch. CI checks the actual compiler's source spans and reference relationships, not unstable IDs or a fabricated JSON fixture. A generated website page displays source and exact stdout without executing Scarp.

Follow the actual links in the browser

The workshop reference explorer highlights 11 authored symbol definitions and 20 use sites after the course build validates their locations. Select either base declaration to see its separate references, including a reference inside the other declaration's initializer. The UI works with keyboard-activated links, has a readable no-JavaScript anchor fallback and stores no browsing state. Its annotations are human-readable teaching data verified against the published alpha.6 compiler by CI; they are not live compiler JSON or a language server. The Scarp.project, .srp files and exact .stdout fixture remain authoritative.