Metadata-Version: 2.4
Name: falsework
Version: 0.1.0
Summary: Find fabricated code (AI slop): results never computed, checks that cannot fail, stubs shipped as real.
Author: FIRME AI CORPORATION
License: Apache-2.0
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Security
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Dynamic: license-file

# FALSEWORK

**Find AI slop: code that looks finished but reports results it never computed.**

AI coding tools write code that compiles, passes a glance, and quietly fakes the hard part: a latency "measurement"
that is a random number, a signature check that returns `True` when it crashes, a benchmark that prints PASSED no
matter what. FALSEWORK finds those patterns, deterministically. No model, no network, no account: it reads your code
on your machine and tells you the file, the line and why.

```
pip install falsework
falsework scan .                      # human-readable
falsework scan src --json             # machine-readable
falsework scan . --sarif out.sarif    # GitHub code scanning
```

```
CRITICAL try_it/slop.py:7  rng_fabrication
         Random number returned as the result of `measure_latency_ms` -- the value it presents as a computation
         or measurement is built from a random draw and constants only.
         > return random.uniform(8.0, 12.0)

FALSEWORK grade: STUB  (1/1 files analysed; CRITICAL 2, HIGH 0, MEDIUM 1, LOW 1)
```

Try it on the two files in `try_it/`: `slop.py` (fabricated) and `real.py` (honest).

## What it looks for
- **Fabricated results:** values presented as measurements or computations that come from a random draw or a constant.
- **Checks that cannot fail:** verifiers that return `True` on every path, or when they crash (`error_grants_access`).
- **Claims written as literals:** "PASSED", "verified", `{"status": "success"}` with nothing computed before them.
- **Stubs shipped as real:** placeholder routes, mocks in production paths, swallowed import errors that make a
  feature silently do nothing.
- **Route/engine mismatches:** an API route calling a method that does not exist on its own engine class.
- JavaScript/TypeScript: the same families, with JS-specific checks.

## Grades
| Grade | Meaning |
|---|---|
| **STUB** | at least one CRITICAL finding: something reports a result it never computed |
| **PARTIAL** | HIGH or MEDIUM findings |
| **REAL** | none of these checks fired. **Not** proof that every result is computed. |
| **UNKNOWN** | nothing could be analysed. Never reported as REAL. |

Exit code: `0` nothing at or above `--fail-on` (default `HIGH`), `1` findings, `2` usage error, `3` nothing analysed.
Test files are skipped; files under `examples/`, `docs/` and similar folders are reported but not counted.

## Honest limits
FALSEWORK is heuristic. Determinism means the same code always gets the same answer, not that the answer is always
right: it can flag legitimate code (seeded simulations, deliberate test doubles) and it misses fabrication it has no
pattern for. Every check came from a real defect found in the CAIN-42 codebase; review each finding before acting.

## Proving, not just finding
FALSEWORK finds suspicious code. **PROOFLOOP**, from the same team, goes further for security bugs: it runs the attack
in a sandbox to prove the bug is real, proves a fix holds, and signs a record anyone can verify with the open-source
`proofloop-verify` package. See https://cainstudio.online.

## Licence
Apache-2.0. Copyright 2026 FIRME AI CORPORATION. "FALSEWORK", "PROOFLOOP" and "CAIN-42" are names of FIRME AI
CORPORATION and are not licensed by the Apache licence. Contributions under the Developer Certificate of Origin; see
CONTRIBUTING.md.
