@g3nomaly/analyze 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,95 @@
+Copyright (c) 2026 G3NTs - G3nomaly
+
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# @g3nomaly/analyze
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`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
+
+```sh
+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](https://bun.sh) 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
+
+```sh
+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`.
+
+```ts
+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.
+
+```sh
+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`](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.