gritpack-searchlib

Compiler-facing resolver and grammar integration surface for Gritpack.

gritpack-searchlib is the Rust library intended for compiler, language-server, and other language-tooling integrations. It exposes three public surfaces:

gritpack_searchlib::build
gritpack_searchlib::grammar
gritpack_searchlib::resolver

Integration Model

The intended consumer is a compiler, language server, build tool, or package-aware indexer that needs two things:

the authoritative set of dependency-managed files that participate in analysis
optional grammar-aware narrowing over that file set for faster name resolution

The important contract is:

participating files are the correctness baseline
grammar-aware resolver queries are narrowing optimizations over that baseline

If a narrowing answer is non-authoritative, the caller must fall back to the broader participating-file set.

What It Is For

Use this crate when you want to:

publish grammar specifications and external-driver payloads into an existing Gritpack project snapshot
open a read-only resolver over that compiled snapshot
query authoritative participating files for dependency-managed source trees
narrow candidate files with grammar-aware query families when the snapshot can answer them authoritatively

This is the library handoff surface for compiler and toolchain integrators. It is separate from the gritpack command-line client package used inside this workspace.

Public Modules

`build`

Write-side helpers for publishing grammar specifications and external-driver payloads into an existing Gritpack project snapshot.

Use this when your compiler already knows how to extract names and wants Gritpack to compile that information into its resolver cache.

`grammar`

Build-side grammar model types.

Use this module to define:

which files participate in indexing
how logical names are extracted
how namespaces are segmented and normalized
when misses can be treated as authoritative

`resolver`

Read-only query access over a compiled Gritpack project snapshot.

Use this module to:

open a resolver from a project root
enumerate authoritative participating files
query grammar-aware candidate files
inspect snapshot freshness and reuse fingerprints

Typical Workflow

Install or otherwise prepare a Gritpack project snapshot.
Define one or more GrammarSpec values in gritpack_searchlib::grammar.
Publish grammar data with gritpack_searchlib::build::persist_project_grammar_data.
Open gritpack_searchlib::resolver::LoadedProjectResolver.
Start from participating_files(...).
Use files_for_query(...) only when you have a logical name and want a narrower candidate set.

Example

use gritpack_searchlib::grammar::GrammarId;
use gritpack_searchlib::resolver::{
  LoadedProjectResolver, ModuleQuery, PackageScope, ParticipatingFileQuery,
  QuerySelection, ReferenceQuery,
};

# async fn demo() -> Result<(), gritpack_searchlib::CliError> {
let resolver = LoadedProjectResolver::open(std::path::Path::new("/workspace/project")).await?;

let participating = resolver.participating_files(&ParticipatingFileQuery {
  package_scope: PackageScope::AnyDependency,
});

let grammar = GrammarId {
  dialect: "lumen/1.0.0".to_string(),
  name: "modules".to_string(),
  version: 1,
};

let candidates = resolver.files_for_query(
  &grammar,
  &ReferenceQuery::Modules(vec![ModuleQuery {
    package_scope: PackageScope::AnyDependency,
    name: "demo::thing".to_string(),
  }]),
)?;

if let Some(QuerySelection::Files(selection)) = candidates {
  if selection.authoritative {
    for path in selection.file_paths {
      println!("candidate={path}");
    }
  }
}

# let _ = participating;
# Ok(())
# }

Documentation

crates.io page: package overview and quick-start material
docs.rs page: crate API docs with module-level examples

Start with the resolver module if you are consuming Gritpack from a compiler. Start with the grammar module if you are defining a language-specific index model.

License

Licensed under GPL-3.0-or-later.

See LICENSE for the full license text.

gritpack-searchlib 0.1.1