flamerjs 0.0.0-stage → 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sagittarius
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,190 @@
-# Temporary Holding Version
+# Flamer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**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)
+
+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.
+
+## Why Flamer?
+
+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.
+
+## Features
+
+- **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 scanning:** files are walked once and content is read once.
+
+## Requirements
+
+- Node.js 18 or newer
+- npm
+
+## Quick start
+
+Run Flamer from a checkout:
+
+```bash
+npm ci
+npm run build
+node dist/cli.js .
+```
+
+After publishing, install the CLI globally:
+
+```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
+```
+
+Analyze another repository:
+
+```bash
+node dist/cli.js /path/to/repository --format summary
+```
+
+## CLI
+
+```text
+node dist/cli.js [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                                                             |
+
+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.
+
+## Example report
+
+```json
+{
+  "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.
+
+## Development
+
+```bash
+npm ci
+npm run dev             # rebuild on source changes
+npm test                # run the test suite
+npm run lint
+npm run format:check
+npm run build
+```
+
+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**.
+
+## 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.
+
+Analyzers are intentionally factual and conservative. A finding should identify
+something actionable rather than merely express a preference.
+
+## Scope and non-goals
+
+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.
+
+## Contributing
+
+See [CONTRIBUTING.md](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.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).