@polymerix-labs/facts-extract 0.15.0 → 0.17.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Polymerix Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,10 +1,20 @@
+<div align="center">
+
 # @polymerix-labs/facts-extract
 
-Analyze a project directory and write a **FactsBundle** JSON file — one entry per
-supported source file.
+Local CLI that walks a repository and emits **FactsBundle** JSON.
+
+[![npm](https://img.shields.io/npm/v/@polymerix-labs/facts-extract.svg)](https://www.npmjs.com/package/@polymerix-labs/facts-extract)
+[![npm downloads](https://img.shields.io/npm/dm/@polymerix-labs/facts-extract.svg)](https://www.npmjs.com/package/@polymerix-labs/facts-extract)
+[![Node](https://img.shields.io/node/v/@polymerix-labs/facts-extract.svg)](https://www.npmjs.com/package/@polymerix-labs/facts-extract)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![GitHub Release](https://img.shields.io/github/v/release/polymerix-labs/facts-extract)](https://github.com/polymerix-labs/facts-extract/releases)
+
+</div>
 
-The native CLI for your platform is installed automatically (same pattern as `esbuild`);
-nothing is downloaded at runtime.
+Walk a repository and write a **FactsBundle** JSON file — one entry per supported source file. Parsing is local (tree-sitter); nothing is uploaded and nothing is downloaded at runtime.
+
+The native CLI for your platform is installed automatically (same pattern as `esbuild`).
 
 ## Install
 
@@ -12,6 +22,61 @@ nothing is downloaded at runtime.
 npm install @polymerix-labs/facts-extract
 ```
 
+Requires **Node.js 16+**. Platform binaries are also attached to [GitHub Releases](https://github.com/polymerix-labs/facts-extract/releases).
+
+## Languages
+
+Every programming language below is parsed with tree-sitter. Facts are collected **as written**. Call targets, inheritance graphs, and include graphs are **not** resolved.
+
+| | Parse | Imports | Symbols | Calls as written | Exports | Linked specifiers |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|
+| **Java** `.java` | ✓ | ✓ | ✓ | ✓ | — | — |
+| **Kotlin** `.kt` `.kts` | ✓ | ✓ | ✓ | ✓ | — | — |
+| **TypeScript** `.ts` `.tsx` `.mts` `.cts` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **JavaScript** `.js` `.jsx` `.mjs` `.cjs` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Python** `.py` `.pyi` | ✓ | ✓ | ✓ | ✓ | — | — |
+| **Go** `.go` | ✓ | ✓ | ✓ | ✓ | — | — |
+| **Rust** `.rs` | ✓ | ✓ | ✓ | ✓ | — | — |
+| **C#** `.cs` | ✓ | ✓ | ✓ | ✓ | — | — |
+| **C** `.c` `.h` | ✓ | ✓ | ✓ | ✓ | — | — |
+| **C++** `.cpp` `.cc` `.cxx` `.hpp` `.hh` `.hxx` | ✓ | ✓ | ✓ | ✓ | — | — |
+| **Swift** `.swift` | ✓ | ✓ | ✓ | ✓ | — | — |
+| **Ruby** `.rb` | ✓ | ✓ | ✓ | ✓ | — | — |
+| **PHP** `.php` | ✓ | ✓ | ✓ | ✓ | — | — |
+| **Scala** `.scala` | ✓ | ✓ | ✓ | ✓ | — | — |
+| **Groovy** `.groovy` | ✓ | ✓ | ✓ | ✓ | — | — |
+| **Lua** `.lua` | ✓ | ✓ | ✓ | ✓ | — | — |
+| **Elixir** `.ex` `.exs` | ✓ | ✓ | ✓ | ✓ | — | — |
+| **Julia** `.jl` | ✓ | ✓ | ✓ | ✓ | — | — |
+| **Zig** `.zig` | ✓ | ✓ | ✓ | ✓ | — | — |
+| **Bash** `.sh` `.bash` | ✓ | ✓ | ✓ | ✓ | — | — |
+| **PowerShell** `.ps1` `.psm1` | ✓ | ✓ | ✓ | ✓ | — | — |
+| **SQL** `.sql` | ✓ | — | ✓ | — | — | — |
+| **MSBuild** `.csproj` `.sln` | ✓ | ✓ | — | — | — | — |
+| **Cargo** `Cargo.toml` | ✓ | ✓ | — | — | — | — |
+| **npm** `package.json` | ✓ | ✓ | — | — | — | — |
+
+**What the columns mean**
+
+| Column | Meaning |
+|--------|---------|
+| Parse | Tree-sitter CST for that file |
+| Imports | `import` / `use` / `#include` / `require` / `source` as written |
+| Symbols | Classes, functions, methods, fields, … with names and source positions |
+| Calls as written | Call / type / inherit mentions collected, not bound to a target |
+| Exports | ES `export` / re-export (TypeScript and JavaScript only) |
+| Linked specifiers | TS/JS import paths rewritten to repo module ids (`tsconfig` paths, barrels) |
+
+**Limits**
+
+- **C / C++** — `#include` paths are imports. No include graph, no macros, no overload resolution. `.h` is C unless the file looks like C++.
+- **Python** — relative imports are turned into repo paths at extract time. No `super()` MRO.
+- **Go** — no embedding promotion.
+- **Rust** — no trait coherence.
+- **C#** — no extension methods.
+- **SQL** — tables / columns / functions as symbols. No invented `CALL` resolution.
+- **`.csproj` / `.sln` / `Cargo.toml` / `package.json`** — dependency edges only. No symbols, no calls.
+
 ## Supported platforms
 
 | OS | Arch | Package |
@@ -36,27 +101,37 @@ const out = spawnSync(binaryPath, ["--repo-root", "/abs/path/to/project"], {
 const bundle = JSON.parse(out.stdout); // FactsBundle
 ```
 
-### Run as a CLI
+### Full repository
 
 ```bash
 npx @polymerix-labs/facts-extract --repo-root /abs/path/to/project -o bundle.json
 ```
 
-### Single file (incremental sync)
+### One file
 
 ```bash
 npx @polymerix-labs/facts-extract --repo-root /abs/path/to/project --file src/Foo.java
 ```
 
-Stdout is one **FactsFileEntry** JSON (`entry`, `facts`, `content_fingerprint`) suitable for per-file upload to the sync API.
+Stdout is one **FactsFileEntry** JSON (`entry`, `facts`, `content_fingerprint`).
+
+### Subset of files
+
+```bash
+npx @polymerix-labs/facts-extract --repo-root /abs/path/to/project --files src/A.ts,src/B.ts
+```
 
 ## Flags
 
-| Flag | Effet |
-|------|-------|
+| Flag | Effect |
+|------|--------|
 | `--repo-root <PATH>` | Absolute path to the repository root (required) |
-| `--file <REL_PATH>` | Extract one repo-relative file as a **FactsFileEntry** JSON (incremental sync) |
-| `--output, -o <FILE>` | Write the FactsBundle JSON to a file (default: stdout) |
+| `--file <REL_PATH>` | Extract one repo-relative file as a FactsFileEntry JSON |
+| `--files <A,B,...>` | Extract only these repo-relative files as a partial FactsBundle |
+| `--list` | Walk only: emit the discovered file listing JSON, without parsing |
+| `--scan` | Walk and blake3-hash every file's raw content, without parsing |
+| `--stream` | Full extraction as NDJSON on stdout (header, one FactsFileEntry per file, then an end line) |
+| `--output, -o <FILE>` | Write JSON to a file (default: stdout) |
 | `--verbose` | Real-time logs on stderr |
 | `--progress` | Progress bar on stderr during the parallel parse pass |
 
@@ -64,8 +139,7 @@ Exit codes: `0` success, `1` usage error, `2` repo not found, `3` extraction/ser
 
 ## Output
 
-The CLI writes a **FactsBundle** JSON (`schema_version`, `repo_root`, and a `files` array).
-Each file entry includes:
+The CLI writes a **FactsBundle** JSON (`schema_version`, `repo_root`, and a `files` array). Each file entry includes:
 
 | Field | What it contains |
 |-------|------------------|
@@ -73,8 +147,82 @@ Each file entry includes:
 | `facts.imports` | Import declarations as written in source |
 | `facts.exports` | Export / re-export declarations (JS/TS) |
 | `facts.symbols` | Classes, methods, functions, fields… with names, types, signatures, and source positions |
-| `facts.refs` | Calls, type uses, inheritance, annotations — collected as written, not yet resolved to targets |
+| `facts.refs` | Calls, type uses, inheritance, annotations — collected as written, not resolved to targets |
 | `facts.local_bindings` | Local variables and their declared or inferred types |
 | `facts.has_syntax_errors` | Whether the file had parse errors |
 
-The bundle format is versioned by `FACTS_SCHEMA_VERSION` (currently `2`). Per-file entries include a `content_fingerprint` for incremental sync.
+The bundle format is versioned (`schema_version` is currently `4`).
+
+### Example
+
+Given `src/Greeter.java`:
+
+```java
+package demo;
+
+public class Greeter {
+    public void hello() {
+        System.out.println("hi");
+    }
+}
+```
+
+`facts-extract --file src/Greeter.java` writes one file entry (pretty-printed here; the CLI emits compact JSON):
+
+```json
+{
+  "entry": {
+    "absolute_path": "/abs/path/to/project/src/Greeter.java",
+    "relative_path": "src/Greeter.java",
+    "filename": "Greeter.java",
+    "extension": ".java",
+    "language": "java"
+  },
+  "facts": {
+    "package": "demo",
+    "symbols": [
+      {
+        "kind": "Class",
+        "name": "Greeter",
+        "fqn": "demo.Greeter",
+        "visibility": "Public",
+        "modifiers": ["public"],
+        "decl_span": [15, 105, 3, 0, 7, 1],
+        "name_span": [28, 35, 3, 13, 3, 20],
+        "signature": "public class Greeter"
+      },
+      {
+        "kind": "Method",
+        "name": "hello",
+        "fqn": "demo.Greeter.hello",
+        "visibility": "Public",
+        "modifiers": ["public"],
+        "return_type": "void",
+        "parent": 0,
+        "decl_span": [42, 103, 4, 4, 6, 5],
+        "name_span": [54, 59, 4, 16, 4, 21],
+        "signature": "public void hello()"
+      }
+    ],
+    "refs": [
+      {
+        "kind": "Call",
+        "name": "println",
+        "qualifier": "System.out",
+        "arity": 1,
+        "arg_types": ["String"],
+        "from": 1,
+        "span": [72, 96, 5, 8, 5, 32]
+      }
+    ]
+  },
+  "content_fingerprint": "f09d5fa0dad7d794",
+  "content_hash": "8e80ece5b5e240b915e8c1583ce99ac8699bec807fe6a3bdcb3d9495407c978e"
+}
+```
+
+`println` is recorded as written (`qualifier` + `name`). It is not resolved to a target. Spans are `[start_byte, end_byte, start_line, start_col, end_line, end_col]`. `from` is the index of the enclosing symbol (`hello`). A full-repo run wraps entries like this in a FactsBundle: `{ "schema_version": 4, "repo_root": "...", "files": [ ... ] }`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@polymerix-labs/facts-extract",
-  "version": "0.15.0",
-  "description": "Analyze a project directory and output structured JSON describing its source files (symbols, imports, and code references). Installs the native CLI for your OS.",
+  "version": "0.17.0",
+  "description": "Local CLI that walks a repository and emits FactsBundle JSON (symbols, imports, and references as written in source). Installs the native binary for your OS.",
   "keywords": [
     "polymerix",
     "facts",
@@ -9,7 +9,14 @@
     "code-analysis",
     "parser"
   ],
-  "homepage": "https://gitlab.com/polymerix/parser",
+  "homepage": "https://github.com/polymerix-labs/facts-extract#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/polymerix-labs/facts-extract.git"
+  },
+  "bugs": {
+    "url": "https://github.com/polymerix-labs/facts-extract/issues"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -22,16 +29,17 @@
   },
   "files": [
     "index.js",
-    "bin.js"
+    "bin.js",
+    "LICENSE"
   ],
   "engines": {
     "node": ">=16"
   },
   "optionalDependencies": {
-    "@polymerix-labs/facts-extract-linux-x64": "0.15.0",
-    "@polymerix-labs/facts-extract-linux-arm64": "0.15.0",
-    "@polymerix-labs/facts-extract-darwin-x64": "0.15.0",
-    "@polymerix-labs/facts-extract-darwin-arm64": "0.15.0",
-    "@polymerix-labs/facts-extract-win32-x64": "0.15.0"
+    "@polymerix-labs/facts-extract-linux-x64": "0.17.0",
+    "@polymerix-labs/facts-extract-linux-arm64": "0.17.0",
+    "@polymerix-labs/facts-extract-darwin-x64": "0.17.0",
+    "@polymerix-labs/facts-extract-darwin-arm64": "0.17.0",
+    "@polymerix-labs/facts-extract-win32-x64": "0.17.0"
   }
 }