Flamer

A fast sanity checker for AI-assisted codebases.

Flamer scans a repository for the common mistakes that appear when software is assembled quickly with AI or other “vibe coding” workflows: unfinished implementation, broken project wiring, missing tests, inconsistent tooling, repository hygiene problems, and maintainability traps.

It is designed to answer:

What is obviously unfinished, disconnected, inconsistent, or likely to break in this repository?

Flamer is not a deep security scanner. It includes a small credential check so accidentally committed keys are not ignored; injection, authentication, cryptography, infrastructure security, and supply-chain analysis belong in a dedicated security tool.

AI-generated code can look complete while still containing:

• placeholder implementations and empty error handlers;
• routes, scripts, or configuration that do not connect;
• tests that exist but provide little confidence;
• duplicate, generated, oversized, or abandoned files;
• dependency and runtime configuration that differs between environments.

Flamer turns these signals into a prioritized, machine-readable report that can be used locally, in pull requests, or in CI.

• Unfinished implementation: explicit “not implemented” paths and empty error handlers.
• Project health: missing README, license, CI, environment templates, editor configuration, and ecosystem scaffolding.
• Testing signals: test presence and source-to-test balance by language.
• Dependency hygiene: lockfiles, version constraints, and manifest checks.
• Repository hygiene: conflict markers, work-item markers, missing newlines, mixed line endings, generated/vendor bloat, and deep paths.
• 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 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.

• 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.

Run the published CLI without installing it permanently:

npx flamerjs .

For a project-local installation, add Flamer as a development dependency:

npm install --save-dev flamerjs
npx flamerjs .

Or install it globally if you use it across repositories:

npm install --global flamerjs
flamerjs .

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:

flamerjs . --format summary

Analyze another repository:

flamerjs /path/to/repository --format summary

flamerjs [path] [options]

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 missing path.

{
  "project": {
    "name": "example-app",
    "kind": ["node"],
    "layout": "single"
  },
  "findings": [
    {
      "category": "unfinished",
      "severity": "HIGH",
      "title": "2 source file(s) contain unfinished implementation",
      "detail": "Not-implemented errors and empty error handlers were detected.",
      "files": ["src/api.ts", "src/jobs.ts"],
      "count": 2
    }
  ]
}

Findings are sorted by severity. Credential values are always redacted.

Clone the repository when you want to contribute or work on the scanner itself:

npm ci
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:

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.

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>.

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.

See docs/ARCHITECTURE.md for the runtime layers, worker protocol, engine selection, and native development workflow.

For the source installation path:

curl -fsSL https://raw.githubusercontent.com/dummy3ye/flamer/master/scripts/install.sh | sh

The npm package uses optional native packages when they are published for the current platform; if npm skips them, TypeScript fallback is automatic. To install the CLI plus standalone Rust and C++ release workers on Unix-like systems:

FLAMER_VERSION=1.1.3 \
  sh -c 'curl -fsSL https://raw.githubusercontent.com/dummy3ye/flamer/master/scripts/install.sh | sh -s -- native'
flamer .

On Windows, run scripts/install.ps1 from the repository or download it from the tagged source tree. Both installers verify SHA-256 checksums and place the two workers in the Flamer native cache.

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. 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.

Flamer focuses on codebase completeness and engineering health, not penetration testing. It does not attempt to prove that an application is secure, correct, performant, or production-ready. Static signals always need human review, especially when a project uses deliberate stubs, generated code, or unusual architecture.

See CONTRIBUTING.md for the development workflow and guidelines for adding analyzers, language profiles, and tests.

When adding a check:

1. Prefer a high-confidence signal with a concrete fix.
2. Add a focused regression test.
3. Keep false positives low and explain unavoidable uncertainty.
4. Update the README when user-visible behavior changes.

This project is licensed under the MIT License.