flamerjs 0.1.6 → 1.1.0

package/README.md

@@ -51,13 +51,23 @@ 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.
+- **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. 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
 
 Run the published CLI without installing it permanently:
@@ -101,23 +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                                                           |
-| `--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
@@ -170,12 +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**.
 
+### Native engine
+
+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:all
+node dist/cli.js .
+```
+
+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. 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

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { writeFileSync, existsSync as existsSync3 } from "fs";
+import { writeFileSync, existsSync as existsSync4 } from "fs";
 import { resolve, basename } from "path";
 
 // src/util/fs.ts
@@ -353,7 +353,8 @@ var CATEGORIES = [
   "structure",
   "git",
   "error",
-  "unfinished"
+  "unfinished",
+  "native"
 ];
 function rank(severity) {
   const r = RANK[String(severity).toUpperCase()];
@@ -2901,6 +2902,82 @@ var ANALYZERS = [
   { id: "systems", label: "Rust / Go / C / C++ / C# / Zig", fn: analyze6 }
 ];
 
+// src/native.ts
+import { spawn } from "child_process";
+import { existsSync as existsSync3 } from "fs";
+import { join as join6 } from "path";
+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 {
+    return require2.resolve(`${packageName}/${worker}`);
+  } catch {
+    return null;
+  }
+}
+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`)
+    );
+  }
+  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
 var SPEC_VERSION = 1;
 function parseArgs(argv) {
@@ -2918,6 +2995,7 @@ function parseArgs(argv) {
     listLanguages: false,
     help: false,
     color: null,
+    engine: "all",
     ignoreDirs: []
   };
   for (let i = 0; i < argv.length; i++) {
@@ -2963,6 +3041,14 @@ function parseArgs(argv) {
       case "--no-color":
         opts.color = false;
         break;
+      case "--engine":
+        opts.engine = argv[++i] || "all";
+        if (!["all", "typescript", "rust", "cpp"].includes(opts.engine)) {
+          process.stderr.write(`invalid engine: ${opts.engine}
+`);
+          process.exit(2);
+        }
+        break;
       case "--list-languages":
         opts.listLanguages = true;
         break;
@@ -3004,6 +3090,8 @@ Options:
   --quiet                    suppress the human summary
   --color                    force ANSI colors
   --no-color                 disable ANSI colors
+  --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
 `);
@@ -3020,10 +3108,10 @@ function printLanguages() {
 ${allExtensions().length} file extensions recognized.
 `);
 }
-function run2(opts) {
+async function run2(opts) {
   const started = Date.now();
   const root = opts.root;
-  if (!existsSync3(root) || !isDir(root)) {
+  if (!existsSync4(root) || !isDir(root)) {
     const err = {
       specVersion: SPEC_VERSION,
       tool: "flamer",
@@ -3161,6 +3249,54 @@ function run2(opts) {
       analyzers: analyzerResults
     }
   };
+  if (opts.engine !== "typescript") {
+    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.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)) {
     exitCode = 1;
@@ -3284,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 {
@@ -3305,4 +3441,4 @@ function main() {
   }
   process.exitCode = exitCode;
 }
-main();
+void main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flamerjs",
-  "version": "0.1.6",
+  "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,9 +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": "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",