flamerjs 0.1.5 → 1.0.0

package/README.md

@@ -2,10 +2,13 @@
 
 **A fast sanity checker for AI-assisted codebases.**
 
-[![CI](https://github.com/dummy3ye/flamer/actions/workflows/ci.yml/badge.svg)](https://github.com/dummy3ye/flamer/actions/workflows/ci.yml)
-[![codecov](https://codecov.io/gh/dummy3ye/flamer/branch/master/graph/badge.svg)](https://codecov.io/gh/dummy3ye/flamer)
-[![npm](https://img.shields.io/npm/v/flamerjs)](https://www.npmjs.com/package/flamerjs)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/dummy3ye/flamer/ci.yml?branch=master&style=for-the-badge&label=CI&labelColor=101418&color=9ccbfb)](https://github.com/dummy3ye/flamer/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/codecov/c/github/dummy3ye/flamer?style=for-the-badge&label=coverage&labelColor=101418&color=b9c8da)](https://codecov.io/gh/dummy3ye/flamer)
+[![npm](https://img.shields.io/npm/v/flamerjs?style=for-the-badge&labelColor=101418&color=d3bfe6)](https://www.npmjs.com/package/flamerjs)<br>
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge&labelColor=101418&color=d3bfe6)](LICENSE)
+[![GitHub last commit](https://img.shields.io/github/last-commit/dummy3ye/flamer?style=for-the-badge&labelColor=101418&color=9ccbfb)](https://github.com/dummy3ye/flamer/commits/master)
+[![GitHub Repo stars](https://img.shields.io/github/stars/dummy3ye/flamer?style=for-the-badge&labelColor=101418&color=b9c8da)](https://github.com/dummy3ye/flamer/stargazers)
+[![GitHub repo size](https://img.shields.io/github/repo-size/dummy3ye/flamer?style=for-the-badge&labelColor=101418&color=d3bfe6)](https://github.com/dummy3ye/flamer)
 
 Flamer scans a repository for the common mistakes that appear when software is
 assembled quickly with AI or other “vibe coding” workflows: unfinished
@@ -49,68 +52,79 @@ can be used locally, in pull requests, or in CI.
   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.
 
 ## 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.
+
 ## Quick start
 
-Run Flamer from a checkout:
+Run the published CLI without installing it permanently:
 
 ```bash
-npm ci
-npm run build
-node dist/cli.js .
+npx flamerjs .
 ```
 
-After publishing, install the CLI globally:
+For a project-local installation, add Flamer as a development dependency:
+
+```bash
+npm install --save-dev flamerjs
+npx flamerjs .
+```
+
+Or install it globally if you use it across repositories:
 
 ```bash
 npm install --global flamerjs
 flamerjs .
 ```
 
-During development, `npm run dev` watches and rebuilds `dist/cli.js`.
 The default output is a colorized terminal summary when run interactively.
 Use `--format json` for automation and machine-readable output.
 
 For a human-readable report:
 
 ```bash
-node dist/cli.js . --format summary
+flamerjs . --format summary
 ```
 
 Analyze another repository:
 
 ```bash
-node dist/cli.js /path/to/repository --format summary
+flamerjs /path/to/repository --format summary
 ```
 
 ## CLI
 
 ```text
-node dist/cli.js [path] [options]
+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 <typescript\|native\|auto>` | Select the scan engine; TypeScript is the default                             |
+| `--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
@@ -142,25 +156,51 @@ Findings are sorted by severity. Credential values are always redacted.
 
 ## Development
 
+Clone the repository when you want to contribute or work on the scanner itself:
+
 ```bash
 npm ci
-npm run dev             # rebuild on source changes
+npm run dev             # watch and rebuild dist/cli.js
 npm test                # run the test suite
 npm run lint
 npm run format:check
 npm run build
 ```
 
+To run the local build directly:
+
+```bash
+node dist/cli.js .
+```
+
 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
+
+Flamer includes an experimental Rust worker for native file metrics. It is
+disabled by default and does not change findings:
+
+```bash
+npm run native:build
+node dist/cli.js . --engine native
+```
+
+Use `--engine auto` to fall back to TypeScript when the worker is unavailable.
+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.
+
 ## 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. Optionally collect native file metrics through the versioned worker protocol.
+5. Sort findings and emit JSON or a concise summary.
 
 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
@@ -2901,6 +2901,42 @@ var ANALYZERS = [
   { id: "systems", label: "Rust / Go / C / C++ / C# / Zig", fn: analyze6 }
 ];
 
+// src/native.ts
+import { spawnSync } 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;
+  try {
+    response = JSON.parse(result.stdout);
+  } 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");
+  }
+  if (!response.ok) {
+    throw new Error(response.errors.map((error) => `${error.path}: ${error.message}`).join("; "));
+  }
+  return response;
+}
+
 // src/cli.ts
 var SPEC_VERSION = 1;
 function parseArgs(argv) {
@@ -2918,6 +2954,7 @@ function parseArgs(argv) {
     listLanguages: false,
     help: false,
     color: null,
+    engine: "typescript",
     ignoreDirs: []
   };
   for (let i = 0; i < argv.length; i++) {
@@ -2963,6 +3000,14 @@ function parseArgs(argv) {
       case "--no-color":
         opts.color = false;
         break;
+      case "--engine":
+        opts.engine = argv[++i] || "typescript";
+        if (!["typescript", "native", "auto"].includes(opts.engine)) {
+          process.stderr.write(`invalid engine: ${opts.engine}
+`);
+          process.exit(2);
+        }
+        break;
       case "--list-languages":
         opts.listLanguages = true;
         break;
@@ -3004,6 +3049,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)
   --list-languages           print the supported language table
   -h, --help                 show this help
 `);
@@ -3023,7 +3070,7 @@ ${allExtensions().length} file extensions recognized.
 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 +3208,37 @@ function run2(opts) {
       analyzers: analyzerResults
     }
   };
+  if (opts.engine !== "typescript") {
+    try {
+      const native = runNativeMetrics(
+        root,
+        scopedFiles.map((file) => file.rel)
+      );
+      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 };
+    }
+  }
   let exitCode = 0;
   if (opts.failOn && report.metadata.worst && rank(report.metadata.worst) <= rank(opts.failOn)) {
     exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flamerjs",
-  "version": "0.1.5",
+  "version": "1.0.0",
   "description": "Language-agnostic code health auditor that walks a repository once and reports what is wrong with it",
   "license": "MIT",
   "type": "module",
@@ -25,6 +25,8 @@
   "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",
     "prepublishOnly": "npm run lint && npm run build && npm test",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",