gritpack-searchlib 0.1.1

# 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

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

## Example

```rust,no_run
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

Copyright Alexander R. Croft

Licensed under GPL-3.0-or-later.

See `LICENSE` for the full license text.