# gleamdoc

Sparse, terminal-first documentation lookup for Gleam packages, inspired by
[`zigdoc`](https://github.com/rockorager/zigdoc).

Gleamdoc reads compiler-generated package interfaces for the current project
and all locally downloaded dependencies. It supports exact public symbol
lookup, including custom type variants, package-qualified lookup, ranked text
and signature search, source locations, and machine-readable JSON output.

```sh
gleamdoc gleam/list
gleamdoc gleam/list.map
gleamdoc gleam_stdlib:gleam/list.map
gleamdoc search "decode json"
gleamdoc packages
gleamdoc index
gleamdoc --version
```

Queries use `<module>.<symbol>` for values, types, and custom type variants. An
exact module name lists that module's public members. Prefix a query with
`<package>:` when two dependencies expose the same module name.

Signatures fully qualify non-prelude named types as
`<package>:<module>.<type>`. Prelude types such as `String`, `List`, and
`Result` retain their short names.

## Flags

```sh
gleamdoc gleam/list.map --json
gleamdoc gleam/list.map --package=gleam_stdlib
gleamdoc gleamdoc/interface.lookup --no-deps
gleamdoc search map --limit=10
gleamdoc search decode --package=gleam_json --json
gleamdoc search decode --kind=fn
gleamdoc search external --target=erlang
gleamdoc packages --no-deps
gleamdoc index --package=gleam_json
gleamdoc index --no-deps
```

- `--json` emits structured records instead of terminal text.
- `--package=NAME` restricts lookup or search to one package.
- `--no-deps` restricts the command to the current project.
- `--limit=N` bounds search results and defaults to 50.
- `--kind=KIND` restricts search to `module`, `fn`, `const`, `type`, `variant`,
  or `alias` entries.
- `--target=TARGET` restricts search to functions and constants that support
  `erlang` or `javascript`.

Run `gleamdoc index` after downloading or changing dependencies, or after
changing the current project's public interface. Lookup, search, and package
listing commands only read validated files under `build/gleamdoc`; they do not
run the Gleam compiler or dependency resolver. A missing or stale cache is an
error that tells you to run the index command.

`gleamdoc index --no-deps` only indexes the current project.
`gleamdoc index --package=NAME` indexes the current project and the selected
dependency. Package-qualified lookups and `--package=NAME` searches likewise
load only that dependency's cache.

Successful commands exit with status 0. Invalid arguments, indexing failures,
unknown packages, missing symbols, and empty searches exit with status 1.

Human-readable output uses color when written to a terminal. Set `NO_COLOR` or
redirect the output to disable ANSI styling.

JSON output is wrapped in an envelope with `"schema_version": 1` and a
`"results"` array. Errors use the same envelope and include an `"error"` field.

An example agent guide for new Gleam projects is available at
[`templates/AGENTS.md`](templates/AGENTS.md). It documents a Gleam workflow that
uses Gleamdoc for API discovery.

Lookup output includes the source file and declaration line when the package's
source is available locally:

```text
source: build/packages/gleam_stdlib/src/gleam/list.gleam:352
```

Search uses weighted ranking. Exact symbol names rank first, followed by name
prefixes and partial names, module matches, signature matches, and finally
documentation matches. All query terms must match somewhere in the
package-qualified name, signature, or documentation.

Dependency interfaces are generated by `gleamdoc index` from the packages
already present in `build/packages`. The indexer stages each package with the
project's locked manifest and local package directory, then runs
`gleam export package-interface`. Interfaces are cached under
`build/gleamdoc/packages` and regenerated when package source or configuration
changes. Temporary staging directories are removed when indexing finishes or
fails.

With a valid `manifest.toml` and populated `build/packages`, dependency exports
can run using those local files. Unlike normal query commands, however,
`gleamdoc index` invokes the Gleam build tool, so any dependency resolution or
download behavior is controlled by the installed Gleam version.

## Install

Build a standalone Erlang escript:

```sh
make build
./gleamdoc gleam/list.map
```

Install it to `~/.local/bin`:

```sh
make install
```

Use `PREFIX` or `BINDIR` to choose another location:

```sh
make install PREFIX=/usr/local
make install BINDIR="$HOME/bin"
```

## Development

```sh
gleam run -- --help
make test
```

The small process-launch and exit-status FFI boundary currently targets
Erlang. Indexing, cache validation, staging, and source lookup are implemented
in Gleam.