@g3nomaly/analyze

analyze turns a repository into one self-contained HTML documentation site. The site has five sections: Skills, Docs, Code, Database and Tasks. The same linked model can be queried from the terminal and, through a typed API, from hooks.

The site works offline. It opens from file:// and inside a sandboxed iframe, and it needs no server, no GPU and no model at runtime.

Usage

cd ~/code/my-repo
bunx @g3nomaly/analyze create_docs

This writes analyze_out/index.html in the repository, and the query commands keep their scan cache in analyze_out/ as well. Add it to .gitignore. The one other file analyze writes is .analyzeignore, once, when the repository has none.

What it skips

.analyzeignore at the repository root lists what the scan skips, on top of .gitignore, with the same patterns: name/ skips a directory anywhere, /name only at the root, *.ext a file anywhere. analyze creates it with node_modules/, dist/, build/, out/, target/, vendor/, coverage/, data/ and the like when it is absent. Edit it to change what is skipped. --exclude adds patterns for one run.

analyze needs Bun 1.2.21 or newer.

What it reads

| Section | Read from | |---|---| | Skills | Every SKILL.md inside the directory of an AI tool (.claude, .codex, .cursor, .gemini, .agents, .windsurf, .opencode) and the files beside it. A SKILL.md elsewhere is a doc | | Docs | Markdown. glossary.md is read as terms, decisions.md as decisions | | Code | Classes and functions in 13 languages through tree-sitter, with their doc comments. JSON, TOML and YAML files, OpenAPI documents and JSON Schemas among them | | Database | .sql files. A file that creates tables becomes a schema diagram, any other a query catalog. No database is ever opened | | Tasks | The plans, phases and tasks that task-manager keeps, in skills.settings.filetreeRoot of .g3n.config.json (default docs/task-manager) | | Packages | A directory with a package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, build.gradle, composer.json, .csproj, .gemspec or Gemfile is shown as a package: an app, a library or a workspace |

Every page, entry, parameter and field is a node of one graph. Edges connect a type to where it is used, a term to the text that uses it, a decision to the code it affects, a table to its foreign keys and queries, and a task to the code, docs and decisions it names and to the tasks it depends on. One registry in src/model/registry.ts defines every kind of node and edge.

Querying

g3n-analyze search how are routes chosen     # by words and by meaning
g3n-analyze show choose_route                # one page or entry in full
g3n-analyze refs Sailing --kind term         # what it links to, and what links to it
g3n-analyze list --kind task                 # every task with its status
g3n-analyze show TASK-002 --json             # a task, as JSON

Output is markdown, or JSON with --json. --from analyze_out/index.html queries a built site without the repository. g3n-analyze --help lists every option, node kind, section and edge kind.

From hooks

The same queries are a typed library API. A function never prints. Warnings go to onWarning, and errors are thrown as OptionsError, QueryError or SourceError.

import { refs, search, show } from '@g3nomaly/analyze';

const hits = await search({ repo: '/home/me/app', query: 'route price', limit: 5 });
const task = await show({ repo: '/home/me/app', target: 'TASK-002' });
const callers = await refs({ repo: '/home/me/app', target: 'choose_route', incoming: true, edges: ['names'] });

createDocs, search, show, refs and list take the options of the CLI as fields.

Development

Run every command from this directory.

bun run build              # web app, CLI and library into dist/
bun run typecheck
bun test                   # unit tests
bun run test:integration   # builds first
bun run analyze -- --help  # the CLI from source, after one build

The web primitives in src/web/components/shadcn/ are installed with the g3nui CLI of @g3nomaly/ui. The reasons behind the design are in decisions.md.

License

Elastic License 2.0. The word embedding table in assets/embedding/ was computed from all-MiniLM-L6-v2 (Apache-2.0) and potion (MIT). Its notice and licenses are kept beside it.