flamerjs 1.0.0 → 1.1.0

package/README.md

@@ -51,18 +51,22 @@ can be used locally, in pull requests, or in CI.
 - **Language-aware checks:** JavaScript/TypeScript, Python, Rust, Go, C/C++,
   C#, Zig, SQL, notebooks, and additional language profiles.
 - **Stable JSON output:** suitable for CI annotations and other automation.
-- **Single-pass scanning:** files are walked once and content is read once.
-- **Optional native workers:** Rust and C++ workers for isolated file metrics,
-  with TypeScript remaining the default engine.
+- **Single-pass TypeScript scanning:** the repository is walked once and
+  content is collected once before analyzers run.
+- **Coordinated native workers:** Rust handles shared file metrics and
+  Rust-specific checks, while C++ handles C/C++ checks; TypeScript remains the
+  source of truth and fallback path.
 
 ## Requirements
 
 - Node.js 18 or newer
 - npm
 
-The default TypeScript engine needs only Node.js and npm. Native mode additionally
-requires Rust/Cargo for the Rust worker or a C++17 compiler and CMake for the
-C++ worker.
+The default TypeScript engine needs only Node.js and npm. The published package
+also declares optional, platform-specific native packages containing both
+workers, so a compatible npm install gets full mode automatically. Building
+workers from this repository requires Rust/Cargo and a C++17 compiler with
+CMake.
 
 ## Quick start
 
@@ -107,24 +111,24 @@ flamerjs /path/to/repository --format summary
 flamerjs [path] [options]
 ```
 
-| Option                                | Description                                                                   |
-| ------------------------------------- | ----------------------------------------------------------------------------- |
-| `--package, --scope <name>`           | Analyze only a named sub-project                                              |
-| `--path <dir>`                        | Set the repository root; defaults to the current directory                    |
-| `--format <json\|summary>`            | Select JSON or human-readable output; summary is the default                  |
-| `--out <file>`                        | Also write the JSON report to a file                                          |
-| `--fail-on <SEVERITY>`                | Exit with status 1 at or above `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, or `INFO` |
-| `--max-files <n>`                     | Limit the number of files scanned                                             |
-| `--commit-limit <n>`                  | Limit commits inspected by Git checks                                         |
-| `--no-git`                            | Skip Git analysis                                                             |
-| `--no-lockfile-warning`               | Suppress the missing-lockfile suggestion                                      |
-| `--ignore-dir <name>`                 | Ignore an additional directory name; repeatable                               |
-| `--quiet`                             | Suppress the human summary                                                    |
-| `--color`                             | Force ANSI colors                                                             |
-| `--no-color`                          | Disable ANSI colors                                                           |
-| `--engine <typescript\|native\|auto>` | Select the scan engine; TypeScript is the default                             |
-| `--list-languages`                    | List recognized language profiles                                             |
-| `--help`                              | Show command help                                                             |
+| Option                                  | Description                                                                   |
+| --------------------------------------- | ----------------------------------------------------------------------------- |
+| `--package, --scope <name>`             | Analyze only a named sub-project                                              |
+| `--path <dir>`                          | Set the repository root; defaults to the current directory                    |
+| `--format <json\|summary>`              | Select JSON or human-readable output; summary is the default                  |
+| `--out <file>`                          | Also write the JSON report to a file                                          |
+| `--fail-on <SEVERITY>`                  | Exit with status 1 at or above `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, or `INFO` |
+| `--max-files <n>`                       | Limit the number of files scanned                                             |
+| `--commit-limit <n>`                    | Limit commits inspected by Git checks                                         |
+| `--no-git`                              | Skip Git analysis                                                             |
+| `--no-lockfile-warning`                 | Suppress the missing-lockfile suggestion                                      |
+| `--ignore-dir <name>`                   | Ignore an additional directory name; repeatable                               |
+| `--quiet`                               | Suppress the human summary                                                    |
+| `--color`                               | Force ANSI colors                                                             |
+| `--no-color`                            | Disable ANSI colors                                                           |
+| `--engine <all\|typescript\|rust\|cpp>` | Run all engines (default) or select one engine                                |
+| `--list-languages`                      | List recognized language profiles                                             |
+| `--help`                                | Show command help                                                             |
 
 Exit status `0` means the scan completed; findings may still exist. Status `1`
 means `--fail-on` was reached, and status `2` indicates invalid usage or a
@@ -177,30 +181,57 @@ The project uses Node.js and npm as its supported development toolchain.
 `package-lock.json` is the canonical dependency lockfile.
 The current test suite contains **175 tests**.
 
-### Optional native engine
+### Native engine
 
-Flamer includes an experimental Rust worker for native file metrics. It is
-disabled by default and does not change findings:
+Flamer runs all three components by default: TypeScript analyzers plus the Rust
+and C++ native workers. They do different work and run concurrently:
+
+- TypeScript walks the repository, runs the generic analyzers, and produces the
+  report.
+- Rust computes shared metrics for all selected files and checks Rust files for
+  `.unwrap()` usage.
+- C++ checks only C and C++ files for native-language issues such as
+  `#include <bits/stdc++.h>`.
 
 ```bash
-npm run native:build
-node dist/cli.js . --engine native
+npm run native:build:all
+node dist/cli.js .
 ```
 
-Use `--engine auto` to fall back to TypeScript when the worker is unavailable.
+Native findings are merged into the TypeScript report only after all requested
+native jobs succeed. If a native binary is unavailable or fails, the default
+`all` mode falls back to a pure TypeScript report. Use `--engine typescript` for
+a native-free scan, or `--engine rust` / `--engine cpp` to require one specific
+worker; explicit native modes return an error when their worker fails.
 The native protocol and worker details are documented in
 [`native/core/README.md`](native/core/README.md).
 
 See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the runtime layers,
 worker protocol, engine selection, and native development workflow.
 
+For the source installation path:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/dummy3ye/flamer/master/scripts/install.sh | sh
+```
+
+Platform-specific native release binaries are not bundled in the current npm
+package yet. The npm package uses optional native packages when they are
+published for the current platform; if npm skips them, TypeScript fallback is
+automatic. The installer's `native` path is reserved for standalone releases
+that attach those assets.
+
 ## How it works
 
 1. Detect the repository layout, languages, and ecosystems.
 2. Walk the tree once and collect file metadata and content-derived signals.
 3. Run isolated analyzers against the collected records.
-4. Optionally collect native file metrics through the versioned worker protocol.
-5. Sort findings and emit JSON or a concise summary.
+4. Run the requested native jobs through the versioned JSONL protocol. Native
+   jobs receive non-overlapping responsibilities and return metrics or
+   language-specific findings.
+5. Merge successful native findings, sort everything, and emit JSON or a
+   concise summary. In default `all` mode, any native failure returns to the
+   TypeScript-only result.
 
 Analyzers are intentionally factual and conservative. A finding should identify
 something actionable rather than merely express a preference.

package/dist/cli.js

@@ -353,7 +353,8 @@ var CATEGORIES = [
   "structure",
   "git",
   "error",
-  "unfinished"
+  "unfinished",
+  "native"
 ];
 function rank(severity) {
   const r = RANK[String(severity).toUpperCase()];
@@ -2902,39 +2903,79 @@ var ANALYZERS = [
 ];
 
 // src/native.ts
-import { spawnSync } from "child_process";
+import { spawn } from "child_process";
 import { existsSync as existsSync3 } from "fs";
 import { join as join6 } from "path";
-function nativeWorkerPath(root) {
-  const configured = process.env.FLAMER_CORE;
-  if (configured) return configured;
-  return join6(root, "native", "core", "rust", "target", "release", "flamer-core");
-}
-function runNativeMetrics(root, files) {
-  const worker = nativeWorkerPath(root);
-  if (!existsSync3(worker)) {
-    throw new Error(`native worker not found at ${worker}; run npm run native:build`);
-  }
-  const request = JSON.stringify({ protocol: 1, operation: "file_metrics", root, files });
-  const result = spawnSync(worker, { input: `${request}
-`, encoding: "utf8", timeout: 3e4 });
-  if (result.error) throw new Error(`native worker failed: ${result.error.message}`);
-  if (result.status !== 0) {
-    throw new Error(`native worker exited with status ${result.status}: ${result.stderr.trim()}`);
-  }
-  let response;
+import { createRequire } from "module";
+var require2 = createRequire(import.meta.url);
+function nativePackageName() {
+  const platform = `${process.platform}-${process.arch}`;
+  const supported = /* @__PURE__ */ new Set(["linux-x64", "darwin-x64", "darwin-arm64", "win32-x64"]);
+  return supported.has(platform) ? `@dummy3ye/flamer-native-${platform}` : null;
+}
+function packagedWorkerPath(worker) {
+  const packageName = nativePackageName();
+  if (!packageName) return null;
   try {
-    response = JSON.parse(result.stdout);
+    return require2.resolve(`${packageName}/${worker}`);
   } catch {
-    throw new Error("native worker returned invalid JSON");
-  }
-  if (response.protocol !== 1 || response.operation !== "file_metrics") {
-    throw new Error("native worker returned an incompatible response");
+    return null;
   }
-  if (!response.ok) {
-    throw new Error(response.errors.map((error) => `${error.path}: ${error.message}`).join("; "));
+}
+function nativeWorkerPath(root, worker) {
+  const configured = worker === "rust" ? process.env.FLAMER_RUST_CORE : process.env.FLAMER_CPP_CORE;
+  if (configured) return configured;
+  if (process.env.FLAMER_CORE && worker === "rust") return process.env.FLAMER_CORE;
+  const packaged = packagedWorkerPath(worker);
+  if (packaged) return packaged;
+  return worker === "rust" ? join6(root, "native", "core", "rust", "target", "release", "flamer-core") : join6(root, "native", "core", "cpp", "build", "flamer-core-cpp");
+}
+function runNativeWorker(root, files, worker, operation = "file_metrics") {
+  const executable = nativeWorkerPath(root, worker);
+  if (!existsSync3(executable)) {
+    return Promise.reject(
+      new Error(`${worker} worker not found at ${executable}; build the native workers first`)
+    );
   }
-  return response;
+  const request = JSON.stringify({ protocol: 1, operation, root, files });
+  return new Promise((resolve2, reject) => {
+    const child = spawn(executable, { stdio: ["pipe", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    const timeout = setTimeout(() => {
+      child.kill();
+      reject(new Error(`${worker} worker timed out`));
+    }, 3e4);
+    child.stdout.on("data", (chunk) => stdout += chunk);
+    child.stderr.on("data", (chunk) => stderr += chunk);
+    child.on("error", (error) => {
+      clearTimeout(timeout);
+      reject(new Error(`${worker} worker failed: ${error.message}`));
+    });
+    child.on("close", (status) => {
+      clearTimeout(timeout);
+      if (status !== 0) {
+        reject(new Error(`${worker} worker exited with status ${status}: ${stderr.trim()}`));
+        return;
+      }
+      try {
+        const response = JSON.parse(stdout);
+        if (response.protocol !== 1 || response.operation !== operation) {
+          throw new Error(`${worker} worker returned an incompatible response`);
+        }
+        if (!response.ok) {
+          throw new Error(
+            response.errors.map((error) => `${error.path}: ${error.message}`).join("; ")
+          );
+        }
+        resolve2(response);
+      } catch (error) {
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+    child.stdin.end(`${request}
+`);
+  });
 }
 
 // src/cli.ts
@@ -2954,7 +2995,7 @@ function parseArgs(argv) {
     listLanguages: false,
     help: false,
     color: null,
-    engine: "typescript",
+    engine: "all",
     ignoreDirs: []
   };
   for (let i = 0; i < argv.length; i++) {
@@ -3001,8 +3042,8 @@ function parseArgs(argv) {
         opts.color = false;
         break;
       case "--engine":
-        opts.engine = argv[++i] || "typescript";
-        if (!["typescript", "native", "auto"].includes(opts.engine)) {
+        opts.engine = argv[++i] || "all";
+        if (!["all", "typescript", "rust", "cpp"].includes(opts.engine)) {
           process.stderr.write(`invalid engine: ${opts.engine}
 `);
           process.exit(2);
@@ -3049,8 +3090,8 @@ Options:
   --quiet                    suppress the human summary
   --color                    force ANSI colors
   --no-color                 disable ANSI colors
-  --engine <typescript|native|auto>
-                            choose the scan engine (default: typescript)
+  --engine <all|typescript|rust|cpp>
+                            all runs TypeScript, Rust, and C++ (default: all)
   --list-languages           print the supported language table
   -h, --help                 show this help
 `);
@@ -3067,7 +3108,7 @@ function printLanguages() {
 ${allExtensions().length} file extensions recognized.
 `);
 }
-function run2(opts) {
+async function run2(opts) {
   const started = Date.now();
   const root = opts.root;
   if (!existsSync4(root) || !isDir(root)) {
@@ -3209,35 +3250,52 @@ function run2(opts) {
     }
   };
   if (opts.engine !== "typescript") {
-    try {
-      const native = runNativeMetrics(
-        root,
-        scopedFiles.map((file) => file.rel)
+    const allFiles = scopedFiles.map((file) => file.rel);
+    const cppFiles = scopedFiles.filter((file) => ["c", "cpp"].includes(file.lang)).map((file) => file.rel);
+    const rustFiles = scopedFiles.filter((file) => file.lang === "rust").map((file) => file.rel);
+    const jobs = opts.engine === "all" ? [
+      ["rust", "file_metrics", allFiles],
+      ["rust", "rust_analysis", rustFiles],
+      ["cpp", "cpp_analysis", cppFiles]
+    ] : opts.engine === "rust" ? [
+      ["rust", "file_metrics", allFiles],
+      ["rust", "rust_analysis", rustFiles]
+    ] : [["cpp", "cpp_analysis", cppFiles]];
+    const nativeResults = {};
+    const failures = [];
+    const nativeFindings = [];
+    await Promise.all(
+      jobs.map(async ([worker, operation, files2]) => {
+        if (!files2.length && operation !== "file_metrics") return;
+        try {
+          const native = await runNativeWorker(root, files2, worker, operation);
+          nativeResults[`${worker}:${operation}`] = {
+            files: native.metrics.files,
+            bytes: native.metrics.bytes,
+            lines: native.metrics.lines,
+            durationMs: native.duration_ms
+          };
+          nativeFindings.push(...native.findings || []);
+        } catch (error) {
+          failures.push(error?.message || String(error));
+        }
+      })
+    );
+    if (failures.length && opts.engine !== "all") {
+      findings.push(
+        finding({
+          category: "error",
+          severity: "CRITICAL",
+          title: "Native engine failed",
+          detail: failures.join("; ")
+        })
       );
-      report.metadata.native = {
-        engine: "rust",
-        files: native.metrics.files,
-        bytes: native.metrics.bytes,
-        lines: native.metrics.lines,
-        durationMs: native.duration_ms
-      };
-    } catch (error) {
-      const message = error?.message || String(error);
-      if (opts.engine === "native") {
-        findings.push(
-          finding({
-            category: "error",
-            severity: "CRITICAL",
-            title: "Native engine failed",
-            detail: message
-          })
-        );
-        report.findings = sortFindings(findings);
-        report.metadata.native = { engine: "rust", error: message };
-        return { report, exitCode: 2 };
-      }
-      report.metadata.native = { engine: "typescript", fallback: message };
+      report.findings = sortFindings(findings);
+      report.metadata.native = { engine: opts.engine, errors: failures };
+      return { report, exitCode: 2 };
     }
+    if (!failures.length) findings.push(...nativeFindings);
+    report.metadata.native = failures.length ? { engine: "typescript", fallback: failures, workers: nativeResults } : { engine: opts.engine, workers: nativeResults };
   }
   let exitCode = 0;
   if (opts.failOn && report.metadata.worst && rank(report.metadata.worst) <= rank(opts.failOn)) {
@@ -3362,11 +3420,11 @@ for (const stream of [process.stdout, process.stderr]) {
     throw err;
   });
 }
-function main() {
+async function main() {
   const opts = parseArgs(process.argv.slice(2));
   if (opts.help) return printHelp();
   if (opts.listLanguages) return printLanguages();
-  const { report, exitCode } = run2(opts);
+  const { report, exitCode } = await run2(opts);
   const json = JSON.stringify(report, null, 2);
   if (opts.out) {
     try {
@@ -3383,4 +3441,4 @@ function main() {
   }
   process.exitCode = exitCode;
 }
-main();
+void main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flamerjs",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Language-agnostic code health auditor that walks a repository once and reports what is wrong with it",
   "license": "MIT",
   "type": "module",
@@ -22,11 +22,20 @@
   "files": [
     "dist"
   ],
+  "optionalDependencies": {
+    "@dummy3ye/flamer-native-darwin-arm64": "1.1.1",
+    "@dummy3ye/flamer-native-darwin-x64": "1.1.1",
+    "@dummy3ye/flamer-native-linux-x64": "1.1.1",
+    "@dummy3ye/flamer-native-win32-x64": "1.1.1"
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "native:build": "cargo build --release --manifest-path native/core/rust/Cargo.toml",
-    "native:test": "cargo test --manifest-path native/core/rust/Cargo.toml",
+    "native:build": "sh scripts/native-build.sh",
+    "native:test": "sh scripts/native-test.sh",
+    "native:build:cpp": "sh scripts/native-build-cpp.sh",
+    "native:build:all": "sh scripts/native-build.sh",
+    "native:package": "node scripts/package-native.mjs",
     "prepublishOnly": "npm run lint && npm run build && npm test",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",