Code librarian stdlib

import "std/code_librarian" exposes the typed code-graph + Cypher surface that ships behind the hostlib_code_index_* builtin family (issue #2434, PR #2441) as a single ergonomic API. Consumers — Burin Code, headless TUI workflows, future personas — call one library instead of stitching outputs from many primitives.

The library never rebuilds the index on its own. Drive hostlib_code_index_rebuild({root: <path>}) first (or the lifecycle equivalent), then talk to the librarian.

Functions

Function	Returns	Wraps
`code_librarian_query(cypher)`	`LibrarianCypherResult`	`hostlib_code_index_cypher`
`code_librarian_outline(path, depth = 1)`	`LibrarianOutline`	`path_to_id` + `outline_get` + `imports_for` + `importers_of`
`code_librarian_who_calls(symbol, max_hops = 2)`	`list<LibrarianCallSite>`	`hostlib_code_index_cypher` (canned `<-[:CALLS]-` query)
`code_librarian_what_imports(path)`	`list<LibrarianImport>`	`hostlib_code_index_importers_of`
`code_librarian_recent_changes(since_seq = 0)`	`list<LibrarianFileChange>`	`hostlib_code_index_changes_since`
`code_librarian_freshness(path)`	`LibrarianFreshness`	`hostlib_code_index_freshness`
`code_librarian_branch_overlay(branch)`	`LibrarianOverlay`	`hostlib_code_index_branch_overlay`

The Cypher executor that backs code_librarian_query and code_librarian_who_calls is documented at crates/harn-hostlib/src/code_index/cypher.rs. Supported clauses: MATCH, WHERE, RETURN, alias projections (RETURN expr AS name), single-edge and variable-length traversal up to depth 4.

Worked example: who calls this function?

import "std/code_librarian"

pipeline default() {
  let _ = hostlib_code_index_rebuild(
    {root: "crates/harn-hostlib/tests/fixtures/code_index_queries/corpus"},
  )

  let callers: list<LibrarianCallSite> = code_librarian_who_calls("fetchUser")
  __io_println("fetchUser has " + to_string(len(callers)) + " call sites:")
  for c in callers {
    __io_println("  " + c.path)
  }
}

Running this against the ground-truth corpus prints:

fetchUser has 2 call sites:
  src/auth.ts
  src/router.ts

The full walk-through lives at examples/code_librarian_explore.harn.

Defaults and limitations

depth on code_librarian_outline is reserved for upcoming graph-aware traversal. Today only the immediate outline is returned regardless of the passed value; the type signature stays stable so consumers don't have to rewrite calls when richer traversal lands.
max_hops on code_librarian_who_calls is reserved for the upcoming transitive <-[:CALLS*1..N]- query shape. Today only direct callers are returned.
code_librarian_recent_changes takes a monotonic version sequence number (since_seq) because Harn has no native Duration primitive yet. Pair with hostlib_code_index_current_seq({}) to checkpoint and resume.
The library does not rebuild the index; consumers must call hostlib_code_index_rebuild before the first query (and after large workspace mutations) themselves.

Code librarian stdlib

Functions

Worked example: who calls this function?

Defaults and limitations

See also