@polymerix-labs/facts-extract 0.7.4

package/README.md

@@ -0,0 +1,61 @@
+# @polymerix-labs/facts-extract
+
+Native **Polymerix front extractor**. It walks a repository and emits a `FactsBundle` JSON
+(faithful, language-neutral facts produced with tree-sitter). It carries **no business logic**
+(no semantic resolution, no graph assembly), so it is safe to ship to client machines.
+
+The matching native binary is installed automatically for your platform via an optional
+dependency (the same pattern as `esbuild`): nothing is downloaded at runtime.
+
+## Install
+
+```bash
+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)
+
+```js
+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
+
+```bash
+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
+
+A `FactsBundle` JSON (the front to back transport contract), versioned by
+`FACTS_SCHEMA_VERSION`. Feed it to the back (`facts-build`) to produce a `graph.json`. See the
+[Polymerix parser repository](https://gitlab.com/polymerix/parser) for the bundle format.

package/bin.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+"use strict";
+
+// CLI shim: forwards every argument to the native `facts-extract` binary and propagates its
+// exit code. Lets consumers run `npx @polymerix-labs/facts-extract --repo-root <dir>` directly.
+
+const { spawnSync } = require("child_process");
+const { binaryPath } = require("./index.js");
+
+const result = spawnSync(binaryPath, process.argv.slice(2), { stdio: "inherit" });
+
+if (result.error) {
+  console.error(`facts-extract: failed to launch binary: ${result.error.message}`);
+  process.exit(1);
+}
+
+// Mirror signal-terminated children with the conventional 128 + signal code.
+if (result.signal) {
+  process.exit(1);
+}
+
+process.exit(result.status === null ? 1 : result.status);

package/index.js

@@ -0,0 +1,54 @@
+"use strict";
+
+// Resolves the path to the native `facts-extract` binary for the current platform.
+//
+// Each supported platform ships as its own package (e.g. `@polymerix-labs/facts-extract-darwin-arm64`)
+// declared as an optional dependency of this wrapper. npm installs only the one matching the
+// host's `os`/`cpu`, so exactly one of them is present at runtime; we resolve its binary here.
+
+const os = require("os");
+
+// Maps Node's `${platform}-${arch}` to the platform package suffix. The keys mirror
+// `process.platform` + `process.arch` for a trivial, direct lookup.
+const SUPPORTED = {
+  "linux-x64": "linux-x64",
+  "linux-arm64": "linux-arm64",
+  "darwin-x64": "darwin-x64",
+  "darwin-arm64": "darwin-arm64",
+  "win32-x64": "win32-x64",
+};
+
+/** Returns the `${platform}-${arch}` key for the current host. */
+function platformKey() {
+  return `${process.platform}-${process.arch}`;
+}
+
+/** Resolves the absolute path to the native binary, throwing a clear error if unsupported. */
+function resolveBinaryPath() {
+  const key = platformKey();
+  const suffix = SUPPORTED[key];
+  if (!suffix) {
+    throw new Error(
+      `@polymerix-labs/facts-extract: unsupported platform "${key}". ` +
+        `Supported: ${Object.keys(SUPPORTED).join(", ")}.`
+    );
+  }
+
+  const binName = process.platform === "win32" ? "facts-extract.exe" : "facts-extract";
+  const pkg = `@polymerix-labs/facts-extract-${suffix}/${binName}`;
+
+  try {
+    return require.resolve(pkg);
+  } catch (err) {
+    throw new Error(
+      `@polymerix-labs/facts-extract: the native package for "${key}" is not installed. ` +
+        `If you disabled optional dependencies, re-install with them enabled. ` +
+        `(host: ${os.type()} ${os.release()})\nCause: ${err.message}`
+    );
+  }
+}
+
+/** Absolute path to the native `facts-extract` executable for this platform. */
+const binaryPath = resolveBinaryPath();
+
+module.exports = { binaryPath, resolveBinaryPath, platformKey };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@polymerix-labs/facts-extract",
+  "version": "0.7.4",
+  "description": "Polymerix front extractor: walk a repository and emit a FactsBundle JSON (tree-sitter only, no business logic). Ships the native binary per platform.",
+  "keywords": [
+    "polymerix",
+    "facts",
+    "tree-sitter",
+    "code-analysis",
+    "parser"
+  ],
+  "homepage": "https://gitlab.com/polymerix/parser",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/polymerix/parser.git",
+    "directory": "npm/facts-extract"
+  },
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "index.js",
+  "bin": {
+    "facts-extract": "bin.js"
+  },
+  "files": [
+    "index.js",
+    "bin.js"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "optionalDependencies": {
+    "@polymerix-labs/facts-extract-linux-x64": "0.7.4",
+    "@polymerix-labs/facts-extract-linux-arm64": "0.7.4",
+    "@polymerix-labs/facts-extract-darwin-x64": "0.7.4",
+    "@polymerix-labs/facts-extract-darwin-arm64": "0.7.4",
+    "@polymerix-labs/facts-extract-win32-x64": "0.7.4"
+  }
+}