@polymerix-labs/facts-extract

Analyze a project directory and write a FactsBundle JSON file — one entry per supported source file.

The native CLI for your platform is installed automatically (same pattern as esbuild); nothing is downloaded at runtime.

Install

npm install @polymerix-labs/facts-extract

Supported platforms

| OS | Arch | Package | |----|------|---------| | Linux | x64 | @polymerix-labs/facts-extract-linux-x64 | | Linux | arm64 | @polymerix-labs/facts-extract-linux-arm64 | | macOS | x64 (Intel) | @polymerix-labs/facts-extract-darwin-x64 | | macOS | arm64 (Apple Silicon) | @polymerix-labs/facts-extract-darwin-arm64 | | Windows | x64 | @polymerix-labs/facts-extract-win32-x64 |

Usage

Resolve the binary path (spawn it yourself)

const { binaryPath } = require("@polymerix-labs/facts-extract");
const { spawnSync } = require("child_process");

const out = spawnSync(binaryPath, ["--repo-root", "/abs/path/to/project"], {
  encoding: "utf8",
});
const bundle = JSON.parse(out.stdout); // FactsBundle

Run as a CLI

npx @polymerix-labs/facts-extract --repo-root /abs/path/to/project -o bundle.json

Flags

| Flag | Effet | |------|-------| | --repo-root <PATH> | Absolute path to the repository root (required) | | --output, -o <FILE> | Write the FactsBundle JSON to a file (default: stdout) | | --verbose | Real-time logs on stderr | | --progress | Progress bar on stderr during the parallel parse pass |

Exit codes: 0 success, 1 usage error, 2 repo not found, 3 extraction/serialize error.

Output

The CLI writes a FactsBundle JSON (schema_version, repo_root, and a files array). Each file entry includes:

| Field | What it contains | |-------|------------------| | entry | File path, language, extension | | 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.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 1).