flamerjs 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -0,0 +1,141 @@
+# Changelog
+
+All notable changes to flamer are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-10-24
+
+### Added
+
+- Rust and C++ native workers under `native/core` for coordinated native
+  processing.
+- Versioned JSONL worker protocol with TypeScript integration through
+  `--engine all|typescript|rust|cpp`.
+- Dedicated native Rust and C++ build/test workflows.
+- Architecture documentation covering runtime layers, protocol, and fallback
+  behavior.
+
+### Fixed
+
+- Native execution failures are explicit for targeted workers and safely fall
+  back to TypeScript in the default `all` mode.
+
+## [1.1.1] - 2026-10-24
+
+### Fixed
+
+- Align the main npm package and native worker package versions.
+- Publish all supported Linux, macOS, and Windows x64/arm64 native packages.
+- Include the changelog and architecture documentation in the npm tarball.
+
+## [1.1.0] - 2026-10-24
+
+### Added
+
+- Optional platform-specific npm packages containing both native workers.
+- Release automation for Linux x64, macOS x64/arm64, and Windows x64 native
+  packages.
+- A native package builder and explicit Rust/C++ build-phase output.
+- `scripts/install.sh` with npm installation and guarded native release-asset
+  installation paths.
+- The default `flamer .` execution coordinates TypeScript, Rust, and C++
+  together, with pure TypeScript fallback when native workers are unavailable.
+- Rust owns shared file metrics and Rust-specific checks; C++ owns C/C++-specific
+  checks, so the workers no longer perform the same analysis.
+
+### Fixed
+
+- CI now builds before tests that execute the bundled CLI.
+- Node 18 builds use a compatible pinned tsup release.
+- Conventional Commit validation accepts the `ci` type.
+
+- Dedicated Codecov coverage reporting and CodeQL analysis workflows.
+
+## [0.1.6] - 2026-10-24
+
+### Fixed
+
+- Updated the README Quick Start to use the published `flamerjs` package with
+  `npx`, local installation, and global installation examples.
+- Updated CLI examples to use the published `flamerjs` command while retaining
+  the source checkout workflow for contributors.
+
+## [0.1.5] - 2026-10-24
+
+### Added
+
+- Human-readable terminal output is now the default CLI mode, with severity
+  grouping, clean scan summaries, and TTY-aware ANSI colors.
+- `--color` and `--no-color` flags for controlling terminal colors.
+- High-confidence detection for explicit not-implemented errors and empty
+  error handlers.
+- npm packaging metadata, a `flamerjs` command alias, and automated publishing
+  to npm and GitHub Packages on version tags.
+
+### Fixed
+
+- README and CI test-count checks now follow the current TypeScript test suite.
+- CLI, contributor, and agent documentation now matches the `src/` and `dist/`
+  project layout.
+
+### Removed
+
+- Bun as a project development dependency and lockfile.
+- JSON as the default interactive output mode; JSON remains available with
+  `--format json`.
+
+## [0.1.0] - 2026-10-02
+
+First public release.
+
+### Added
+
+- Single-pass tree scanner covering 25 languages across 70 file extensions:
+  JavaScript, TypeScript, Python, Rust, Go, C, C++, C#, Java, Kotlin, Scala,
+  Terraform, HCL, Docker, SQL, Ruby, PHP, Shell, PowerShell, Haskell, Elixir,
+  Lua, R, Solidity, Swift, Dart, Zig, and Jupyter notebooks.
+- Eight analyzers, each isolated so one throwing does not stop the rest:
+  `universal`, `notebooks`, `scaffolding`, `testing`, `git`, `node`, `python`,
+  `systems`.
+- Redacted credential detection for 14 credential shapes, with test and fixture
+  paths exempt so a repository's own fake secrets are not reported.
+- Adaptive bloat detection with per-language baselines, so a large generated
+  file is not scored as though a human wrote every line.
+- Per-language test coverage ratios, so a mostly-Terraform repository is not
+  graded as though it were all application code.
+- The roast persona in `SKILL.md`, including a confirmation gate, an audit mode
+  that drops the character, and an instruction to defer deep security analysis
+  to the `poison` skill when it is installed.
+- JSON output by default with a human-readable `--format summary`.
+
+### Performance
+
+Measured on a 3.0 GB monorepo of 98,161 files, 71,150 of them source:
+**3.60s before, 2.10s after**, with byte-identical findings.
+
+- Newline discovery uses `indexOf` rather than a per-character `charCodeAt`
+  loop. Measured 3.7x faster on a 525 MB corpus; `split` measured slower than
+  both while also allocating an array of every line.
+- The credential scanner gates 13 of its 14 patterns behind a literal substring
+  test, so the regex engine never runs against a file that cannot contain that
+  shape of credential. The assignment pattern is intentionally left ungated
+  because its names match case insensitively and an incomplete gate would be a
+  silently dropped rule.
+- Line numbers for a credential finding are resolved by binary search over a
+  lazily built offset table. The previous approach sliced and split the text
+  once per match, which is up to 280 times on a single file.
+
+### Notes
+
+- Zero runtime dependencies. Node 18 or newer, no install step.
+- `poison` is a separate project. Flamer does not import it, and the handoff is
+  a runtime capability check in `SKILL.md` rather than a code dependency.
+
+[Unreleased]: https://github.com/dummy3ye/flamer/compare/v1.1.1...HEAD
+[1.1.1]: https://github.com/dummy3ye/flamer/releases/tag/v1.1.1
+[1.1.0]: https://github.com/dummy3ye/flamer/releases/tag/v1.1.0
+[1.0.0]: https://github.com/dummy3ye/flamer/releases/tag/v1.0.0
+[0.1.6]: https://github.com/dummy3ye/flamer/releases/tag/v0.1.6
+[0.1.5]: https://github.com/dummy3ye/flamer/releases/tag/v0.1.5
+[0.1.0]: https://github.com/OWNER/flamer/releases/tag/v0.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,86 @@ 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",
+    "linux-arm64",
+    "darwin-x64",
+    "darwin-arm64",
+    "win32-x64",
+    "win32-arm64"
+  ]);
+  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 +3002,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 +3049,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 +3097,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 +3115,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 +3257,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 +3427,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 +3448,4 @@ function main() {
   }
   process.exitCode = exitCode;
 }
-main();
+void main();

package/docs/ARCHITECTURE.md

@@ -0,0 +1,175 @@
+# Flamer architecture
+
+Flamer is a Node.js CLI with a coordinated native execution layer. TypeScript
+owns the public interface, repository traversal, generic analyzers, findings,
+fallback behavior, and report format. Rust and C++ run together as specialized
+workers with non-overlapping responsibilities. Native findings are validated
+and merged into the TypeScript report; they are not alternative scanners.
+
+## Runtime layers
+
+```text
+CLI (src/cli.ts)
+  ├─ argument parsing and terminal/JSON output
+  ├─ repository detection and scope selection
+  ├─ TypeScript scanner and analyzers
+  └─ native worker adapter (src/native.ts)
+       ├─ Rust worker: native/core/rust
+       │    ├─ shared file metrics
+       │    └─ Rust-specific analysis
+       └─ C++ worker: native/core/cpp
+            └─ C/C++-specific analysis
+```
+
+### TypeScript layer
+
+The TypeScript CLI is the default and source of truth. `src/scan.ts` walks and
+reads files once, `src/detect.ts` builds project profiles, and registered
+analyzers turn the collected context into findings. This path works with the
+published npm package and does not require Rust, C++, Cargo, or CMake.
+
+### Native layer
+
+The native layer is intentionally separate from generic analyzer logic. Rust
+receives all selected files for shared byte/newline metrics and receives Rust
+files for Rust-specific checks. C++ receives only C and C++ files for
+C/C++-specific checks. These jobs run concurrently in `all` mode, so no worker
+repeats another worker's language analysis.
+
+Rust is built from `native/core/rust/Cargo.toml` and exposes a reusable library
+plus a thin JSONL binary. C++ is built with CMake from
+`native/core/cpp/CMakeLists.txt` and exposes a public header, analyzer
+implementation, and protocol executable.
+
+The current native checks are deliberately small but real: Rust reports
+`.unwrap()` usage and C++ reports the non-portable
+`#include <bits/stdc++.h>` include. Additional expensive, language-specific
+work can be added without moving report ownership out of TypeScript.
+
+## Engine selection
+
+The CLI accepts:
+
+| Engine       | Behavior                                                                                                                              |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `all`        | Default; runs TypeScript, Rust, and C++ together. Falls back to the TypeScript-only report if any native job is unavailable or fails. |
+| `typescript` | Runs only the TypeScript implementation.                                                                                              |
+| `rust`       | Runs TypeScript plus Rust metrics and Rust analysis; fails if Rust is unavailable.                                                    |
+| `cpp`        | Runs TypeScript plus C++ analysis; fails if C++ is unavailable.                                                                       |
+
+The workers can be overridden with `FLAMER_RUST_CORE` and `FLAMER_CPP_CORE`:
+
+```bash
+FLAMER_RUST_CORE="$PWD/native/core/rust/target/release/flamer-core" \
+FLAMER_CPP_CORE="$PWD/native/core/cpp/build/flamer-core-cpp" \
+  node dist/cli.js .
+```
+
+## Worker protocol
+
+Workers communicate over newline-delimited JSON (JSONL):
+
+```json
+{ "protocol": 1, "operation": "file_metrics", "root": ".", "files": ["README.md"] }
+```
+
+Each request produces exactly one response on stdout. The operation determines
+the worker contract:
+
+| Worker | Operation       | Input files        | Responsibility                           |
+| ------ | --------------- | ------------------ | ---------------------------------------- |
+| Rust   | `file_metrics`  | all selected files | byte, newline, and readable-file metrics |
+| Rust   | `rust_analysis` | Rust files         | Rust-specific findings                   |
+| C++    | `cpp_analysis`  | C/C++ files        | C/C++-specific findings                  |
+
+Example response:
+
+```json
+{
+  "protocol": 1,
+  "ok": true,
+  "operation": "file_metrics",
+  "metrics": { "files": 1, "bytes": 1234, "lines": 42 },
+  "errors": [],
+  "duration_ms": 1
+}
+```
+
+Stdout is reserved for protocol messages. Diagnostics belong on stderr.
+Unknown protocol versions, operations, malformed responses, non-zero exits, and
+timeouts are errors. The TypeScript adapter validates the response before using
+it.
+
+## Build and test
+
+```bash
+npm test
+npm run native:build
+npm run native:test
+```
+
+The individual projects can also be built directly:
+
+```bash
+cargo build --release --manifest-path native/core/rust/Cargo.toml
+cmake -S native/core/cpp -B native/core/cpp/build -DCMAKE_BUILD_TYPE=Release
+cmake --build native/core/cpp/build --config Release
+```
+
+The npm native scripts validate that Cargo and CMake are installed and return
+an actionable error when either toolchain is missing. The C++ CMake project
+also exports `compile_commands.json` and contains a protocol smoke test.
+
+Native builds are checked independently in the Native Rust and Native C++
+GitHub Actions workflows. Compiled output is ignored and is not committed.
+
+## Release and installation roadmap
+
+The npm package remains the required installation:
+
+```bash
+npm install --global flamerjs
+```
+
+`flamerjs` declares platform-specific native packages under the publisher scope
+as optional
+dependencies. npm installs only the package matching the host OS and CPU:
+
+```text
+flamerjs
+└── @dummy3ye/flamer-native-linux-x64
+    ├── bin/flamer-core
+    └── bin/flamer-core-cpp
+```
+
+At runtime `src/native.ts` resolves both workers from that package. If npm
+skips the optional package, the package is unavailable for the platform, or a
+worker cannot start, default `all` mode falls back to TypeScript. The source
+build command creates the same package shape:
+
+```bash
+npm run native:build:all
+npm run native:package -- linux-x64
+```
+
+The release workflow must build and publish both workers for each supported
+OS/architecture package before that platform is advertised as native-enabled.
+The standalone installer and release archives can use the same worker
+artifacts.
+
+The eventual bundled release keeps the TypeScript CLI as the orchestration
+layer and packages both Rust and C++ workers. They are not alternatives:
+standard execution starts both, while the explicit engine flags are for
+debugging, benchmarking, and degraded environments.
+
+## Design constraints
+
+- Keep npm installation functional with Node.js alone; native packages remain
+  optional.
+- Keep findings and report semantics in TypeScript.
+- Keep workers deterministic and communicate only through the versioned
+  protocol; stdout is protocol-only and diagnostics use stderr.
+- Keep native execution fallback-safe until platform packaging and release
+  binaries are mature.
+- Do not duplicate generic analyzer work in native workers.
+- Add a benchmark before moving more work out of the TypeScript scanner.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flamerjs",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Language-agnostic code health auditor that walks a repository once and reports what is wrong with it",
   "license": "MIT",
   "type": "module",
@@ -20,13 +20,28 @@
     "flamerjs": "./dist/cli.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "docs/ARCHITECTURE.md"
   ],
+  "optionalDependencies": {
+    "@dummy3ye/flamer-native-darwin-arm64": "1.1.1",
+    "@dummy3ye/flamer-native-darwin-x64": "1.1.1",
+    "@dummy3ye/flamer-native-linux-arm64": "1.1.1",
+    "@dummy3ye/flamer-native-linux-x64": "1.1.1",
+    "@dummy3ye/flamer-native-win32-arm64": "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",