@polymerix-labs/facts-extract 0.16.1 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +163 -15
  3. package/package.json +17 -9
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Polymerix Labs
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,10 +1,20 @@
1
+ <div align="center">
2
+
1
3
  # @polymerix-labs/facts-extract
2
4
 
3
- Analyze a project directory and write a **FactsBundle** JSON file — one entry per
4
- supported source file.
5
+ Local CLI that walks a repository and emits **FactsBundle** JSON.
6
+
7
+ [![npm](https://img.shields.io/npm/v/@polymerix-labs/facts-extract.svg)](https://www.npmjs.com/package/@polymerix-labs/facts-extract)
8
+ [![npm downloads](https://img.shields.io/npm/dm/@polymerix-labs/facts-extract.svg)](https://www.npmjs.com/package/@polymerix-labs/facts-extract)
9
+ [![Node](https://img.shields.io/node/v/@polymerix-labs/facts-extract.svg)](https://www.npmjs.com/package/@polymerix-labs/facts-extract)
10
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
11
+ [![GitHub Release](https://img.shields.io/github/v/release/polymerix-labs/facts-extract)](https://github.com/polymerix-labs/facts-extract/releases)
12
+
13
+ </div>
5
14
 
6
- The native CLI for your platform is installed automatically (same pattern as `esbuild`);
7
- nothing is downloaded at runtime.
15
+ 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.
16
+
17
+ The native CLI for your platform is installed automatically (same pattern as `esbuild`).
8
18
 
9
19
  ## Install
10
20
 
@@ -12,6 +22,61 @@ nothing is downloaded at runtime.
12
22
  npm install @polymerix-labs/facts-extract
13
23
  ```
14
24
 
25
+ Requires **Node.js 16+**. Platform binaries are also attached to [GitHub Releases](https://github.com/polymerix-labs/facts-extract/releases).
26
+
27
+ ## Languages
28
+
29
+ Every programming language below is parsed with tree-sitter. Facts are collected **as written**. Call targets, inheritance graphs, and include graphs are **not** resolved.
30
+
31
+ | | Parse | Imports | Symbols | Calls as written | Exports | Linked specifiers |
32
+ |---|:---:|:---:|:---:|:---:|:---:|:---:|
33
+ | **Java** `.java` | ✓ | ✓ | ✓ | ✓ | — | — |
34
+ | **Kotlin** `.kt` `.kts` | ✓ | ✓ | ✓ | ✓ | — | — |
35
+ | **TypeScript** `.ts` `.tsx` `.mts` `.cts` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
36
+ | **JavaScript** `.js` `.jsx` `.mjs` `.cjs` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
37
+ | **Python** `.py` `.pyi` | ✓ | ✓ | ✓ | ✓ | — | — |
38
+ | **Go** `.go` | ✓ | ✓ | ✓ | ✓ | — | — |
39
+ | **Rust** `.rs` | ✓ | ✓ | ✓ | ✓ | — | — |
40
+ | **C#** `.cs` | ✓ | ✓ | ✓ | ✓ | — | — |
41
+ | **C** `.c` `.h` | ✓ | ✓ | ✓ | ✓ | — | — |
42
+ | **C++** `.cpp` `.cc` `.cxx` `.hpp` `.hh` `.hxx` | ✓ | ✓ | ✓ | ✓ | — | — |
43
+ | **Swift** `.swift` | ✓ | ✓ | ✓ | ✓ | — | — |
44
+ | **Ruby** `.rb` | ✓ | ✓ | ✓ | ✓ | — | — |
45
+ | **PHP** `.php` | ✓ | ✓ | ✓ | ✓ | — | — |
46
+ | **Scala** `.scala` | ✓ | ✓ | ✓ | ✓ | — | — |
47
+ | **Groovy** `.groovy` | ✓ | ✓ | ✓ | ✓ | — | — |
48
+ | **Lua** `.lua` | ✓ | ✓ | ✓ | ✓ | — | — |
49
+ | **Elixir** `.ex` `.exs` | ✓ | ✓ | ✓ | ✓ | — | — |
50
+ | **Julia** `.jl` | ✓ | ✓ | ✓ | ✓ | — | — |
51
+ | **Zig** `.zig` | ✓ | ✓ | ✓ | ✓ | — | — |
52
+ | **Bash** `.sh` `.bash` | ✓ | ✓ | ✓ | ✓ | — | — |
53
+ | **PowerShell** `.ps1` `.psm1` | ✓ | ✓ | ✓ | ✓ | — | — |
54
+ | **SQL** `.sql` | ✓ | — | ✓ | — | — | — |
55
+ | **MSBuild** `.csproj` `.sln` | ✓ | ✓ | — | — | — | — |
56
+ | **Cargo** `Cargo.toml` | ✓ | ✓ | — | — | — | — |
57
+ | **npm** `package.json` | ✓ | ✓ | — | — | — | — |
58
+
59
+ **What the columns mean**
60
+
61
+ | Column | Meaning |
62
+ |--------|---------|
63
+ | Parse | Tree-sitter CST for that file |
64
+ | Imports | `import` / `use` / `#include` / `require` / `source` as written |
65
+ | Symbols | Classes, functions, methods, fields, … with names and source positions |
66
+ | Calls as written | Call / type / inherit mentions collected, not bound to a target |
67
+ | Exports | ES `export` / re-export (TypeScript and JavaScript only) |
68
+ | Linked specifiers | TS/JS import paths rewritten to repo module ids (`tsconfig` paths, barrels) |
69
+
70
+ **Limits**
71
+
72
+ - **C / C++** — `#include` paths are imports. No include graph, no macros, no overload resolution. `.h` is C unless the file looks like C++.
73
+ - **Python** — relative imports are turned into repo paths at extract time. No `super()` MRO.
74
+ - **Go** — no embedding promotion.
75
+ - **Rust** — no trait coherence.
76
+ - **C#** — no extension methods.
77
+ - **SQL** — tables / columns / functions as symbols. No invented `CALL` resolution.
78
+ - **`.csproj` / `.sln` / `Cargo.toml` / `package.json`** — dependency edges only. No symbols, no calls.
79
+
15
80
  ## Supported platforms
16
81
 
17
82
  | OS | Arch | Package |
@@ -36,27 +101,37 @@ const out = spawnSync(binaryPath, ["--repo-root", "/abs/path/to/project"], {
36
101
  const bundle = JSON.parse(out.stdout); // FactsBundle
37
102
  ```
38
103
 
39
- ### Run as a CLI
104
+ ### Full repository
40
105
 
41
106
  ```bash
42
107
  npx @polymerix-labs/facts-extract --repo-root /abs/path/to/project -o bundle.json
43
108
  ```
44
109
 
45
- ### Single file (incremental sync)
110
+ ### One file
46
111
 
47
112
  ```bash
48
113
  npx @polymerix-labs/facts-extract --repo-root /abs/path/to/project --file src/Foo.java
49
114
  ```
50
115
 
51
- Stdout is one **FactsFileEntry** JSON (`entry`, `facts`, `content_fingerprint`) suitable for per-file upload to the sync API.
116
+ Stdout is one **FactsFileEntry** JSON (`entry`, `facts`, `content_fingerprint`).
117
+
118
+ ### Subset of files
119
+
120
+ ```bash
121
+ npx @polymerix-labs/facts-extract --repo-root /abs/path/to/project --files src/A.ts,src/B.ts
122
+ ```
52
123
 
53
124
  ## Flags
54
125
 
55
- | Flag | Effet |
56
- |------|-------|
126
+ | Flag | Effect |
127
+ |------|--------|
57
128
  | `--repo-root <PATH>` | Absolute path to the repository root (required) |
58
- | `--file <REL_PATH>` | Extract one repo-relative file as a **FactsFileEntry** JSON (incremental sync) |
59
- | `--output, -o <FILE>` | Write the FactsBundle JSON to a file (default: stdout) |
129
+ | `--file <REL_PATH>` | Extract one repo-relative file as a FactsFileEntry JSON |
130
+ | `--files <A,B,...>` | Extract only these repo-relative files as a partial FactsBundle |
131
+ | `--list` | Walk only: emit the discovered file listing JSON, without parsing |
132
+ | `--scan` | Walk and blake3-hash every file's raw content, without parsing |
133
+ | `--stream` | Full extraction as NDJSON on stdout (header, one FactsFileEntry per file, then an end line) |
134
+ | `--output, -o <FILE>` | Write JSON to a file (default: stdout) |
60
135
  | `--verbose` | Real-time logs on stderr |
61
136
  | `--progress` | Progress bar on stderr during the parallel parse pass |
62
137
 
@@ -64,8 +139,7 @@ Exit codes: `0` success, `1` usage error, `2` repo not found, `3` extraction/ser
64
139
 
65
140
  ## Output
66
141
 
67
- The CLI writes a **FactsBundle** JSON (`schema_version`, `repo_root`, and a `files` array).
68
- Each file entry includes:
142
+ The CLI writes a **FactsBundle** JSON (`schema_version`, `repo_root`, and a `files` array). Each file entry includes:
69
143
 
70
144
  | Field | What it contains |
71
145
  |-------|------------------|
@@ -73,8 +147,82 @@ Each file entry includes:
73
147
  | `facts.imports` | Import declarations as written in source |
74
148
  | `facts.exports` | Export / re-export declarations (JS/TS) |
75
149
  | `facts.symbols` | Classes, methods, functions, fields… with names, types, signatures, and source positions |
76
- | `facts.refs` | Calls, type uses, inheritance, annotations — collected as written, not yet resolved to targets |
150
+ | `facts.refs` | Calls, type uses, inheritance, annotations — collected as written, not resolved to targets |
77
151
  | `facts.local_bindings` | Local variables and their declared or inferred types |
78
152
  | `facts.has_syntax_errors` | Whether the file had parse errors |
79
153
 
80
- The bundle format is versioned by `FACTS_SCHEMA_VERSION` (currently `2`). Per-file entries include a `content_fingerprint` for incremental sync.
154
+ The bundle format is versioned (`schema_version` is currently `4`).
155
+
156
+ ### Example
157
+
158
+ Given `src/Greeter.java`:
159
+
160
+ ```java
161
+ package demo;
162
+
163
+ public class Greeter {
164
+ public void hello() {
165
+ System.out.println("hi");
166
+ }
167
+ }
168
+ ```
169
+
170
+ `facts-extract --file src/Greeter.java` writes one file entry (pretty-printed here; the CLI emits compact JSON):
171
+
172
+ ```json
173
+ {
174
+ "entry": {
175
+ "absolute_path": "/abs/path/to/project/src/Greeter.java",
176
+ "relative_path": "src/Greeter.java",
177
+ "filename": "Greeter.java",
178
+ "extension": ".java",
179
+ "language": "java"
180
+ },
181
+ "facts": {
182
+ "package": "demo",
183
+ "symbols": [
184
+ {
185
+ "kind": "Class",
186
+ "name": "Greeter",
187
+ "fqn": "demo.Greeter",
188
+ "visibility": "Public",
189
+ "modifiers": ["public"],
190
+ "decl_span": [15, 105, 3, 0, 7, 1],
191
+ "name_span": [28, 35, 3, 13, 3, 20],
192
+ "signature": "public class Greeter"
193
+ },
194
+ {
195
+ "kind": "Method",
196
+ "name": "hello",
197
+ "fqn": "demo.Greeter.hello",
198
+ "visibility": "Public",
199
+ "modifiers": ["public"],
200
+ "return_type": "void",
201
+ "parent": 0,
202
+ "decl_span": [42, 103, 4, 4, 6, 5],
203
+ "name_span": [54, 59, 4, 16, 4, 21],
204
+ "signature": "public void hello()"
205
+ }
206
+ ],
207
+ "refs": [
208
+ {
209
+ "kind": "Call",
210
+ "name": "println",
211
+ "qualifier": "System.out",
212
+ "arity": 1,
213
+ "arg_types": ["String"],
214
+ "from": 1,
215
+ "span": [72, 96, 5, 8, 5, 32]
216
+ }
217
+ ]
218
+ },
219
+ "content_fingerprint": "f09d5fa0dad7d794",
220
+ "content_hash": "8e80ece5b5e240b915e8c1583ce99ac8699bec807fe6a3bdcb3d9495407c978e"
221
+ }
222
+ ```
223
+
224
+ `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": [ ... ] }`.
225
+
226
+ ## License
227
+
228
+ MIT. See [LICENSE](LICENSE).
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@polymerix-labs/facts-extract",
3
- "version": "0.16.1",
4
- "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.",
3
+ "version": "0.17.0",
4
+ "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.",
5
5
  "keywords": [
6
6
  "polymerix",
7
7
  "facts",
@@ -9,7 +9,14 @@
9
9
  "code-analysis",
10
10
  "parser"
11
11
  ],
12
- "homepage": "https://gitlab.com/polymerix/parser",
12
+ "homepage": "https://github.com/polymerix-labs/facts-extract#readme",
13
+ "repository": {
14
+ "type": "git",
15
+ "url": "git+https://github.com/polymerix-labs/facts-extract.git"
16
+ },
17
+ "bugs": {
18
+ "url": "https://github.com/polymerix-labs/facts-extract/issues"
19
+ },
13
20
  "publishConfig": {
14
21
  "access": "public",
15
22
  "registry": "https://registry.npmjs.org/"
@@ -22,16 +29,17 @@
22
29
  },
23
30
  "files": [
24
31
  "index.js",
25
- "bin.js"
32
+ "bin.js",
33
+ "LICENSE"
26
34
  ],
27
35
  "engines": {
28
36
  "node": ">=16"
29
37
  },
30
38
  "optionalDependencies": {
31
- "@polymerix-labs/facts-extract-linux-x64": "0.16.1",
32
- "@polymerix-labs/facts-extract-linux-arm64": "0.16.1",
33
- "@polymerix-labs/facts-extract-darwin-x64": "0.16.1",
34
- "@polymerix-labs/facts-extract-darwin-arm64": "0.16.1",
35
- "@polymerix-labs/facts-extract-win32-x64": "0.16.1"
39
+ "@polymerix-labs/facts-extract-linux-x64": "0.17.0",
40
+ "@polymerix-labs/facts-extract-linux-arm64": "0.17.0",
41
+ "@polymerix-labs/facts-extract-darwin-x64": "0.17.0",
42
+ "@polymerix-labs/facts-extract-darwin-arm64": "0.17.0",
43
+ "@polymerix-labs/facts-extract-win32-x64": "0.17.0"
36
44
  }
37
45
  }