@cejel/cejel 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
 # cejel
 
-[![npm version](https://img.shields.io/npm/v/cejel.svg)](https://www.npmjs.com/package/cejel)
+[![release](https://img.shields.io/github/v/release/BargLabs/cejel)](https://github.com/BargLabs/cejel/releases/latest)
 [![license: AGPL-3.0-only](https://img.shields.io/badge/license-AGPL--3.0--only-blue.svg)](./LICENSE)
 
 Cejel (*"SEH-jel"*) — a trust certificate for your codebase.
@@ -8,8 +8,8 @@ Cejel (*"SEH-jel"*) — a trust certificate for your codebase.
 Free, offline, no-signup CLI that scores the engineering signals that tell you whether to
 trust a repo — tests, secrets, isolation, claim-vs-reality, CI/audit discipline — and prints
 a trust certificate + badge. Especially valuable when AI wrote a lot of the code: that's
-exactly when you can't eyeball trust. Built on a deterministic, no-LLM
-scoring core — the free path makes zero network calls and requires no account.
+exactly when you can't eyeball trust. Built on a deterministic, no-LLM scoring core — the
+free path makes zero network calls and requires no account.
 
 Cejel is not another point scanner competing with the one you already run — it's the open,
 portable, offline trust certificate that aggregates them. Pipe in SARIF-compatible output
@@ -20,57 +20,60 @@ certificate + badge over all of them. See "Aggregate your scanners" below.
 > monorepo — the ten-product studio it was built inside — which it currently scores
 > 3.1/4.0 ("Conditional"). We score ourselves before asking you to score yourself.
 
-## Leaderboard
-
-This repo ships the [Cejel OSS trust leaderboard](./leaderboard/leaderboard.md): the whole
-corpus scored and published in the open — elite OSS projects, Cejel itself, and the private
-studio monorepo Cejel was built inside — with a per-repository evidence report for every
-row under [`leaderboard/reports/`](./leaderboard/reports/). The board is also hosted at
-[cejel.dev](https://cejel.dev). Same deterministic rubric as `npx cejel .`; nobody is
-exempt, including us.
-
-### Redaction policy
-
-A path is published exactly when the reader can check it. Every public repository on the
-board cites full evidence paths and line numbers, everywhere, in every artifact — a
-certificate whose evidence you cannot open is not evidence. The two private-repository
-entries (this monorepo's own transparency entry, and Cejel's own source sub-package inside
-it) never cite a source path, anywhere, in any field or format — but the finding itself, its
-dimension, status, score, and content hash always survive; only the location is withheld,
-marked uniformly as "path withheld — private repository". Redaction removes a location, never
-a fact: a private repository failing its own check still shows up on its certificate, by
-name. The B1 and B5 rubric dimensions are substrate-only (they measure signals specific to
-this monorepo's own internal process, not applicable to any external repository) and are
-excluded from the ranking for every repository, including ours — the same fairness rule
-either way: nobody is scored on a dimension nobody else can have.
-
-### Known false positives (fixed before publishing)
-
-Calibrating a rubric against real, elite repositories surfaces mistakes; the record is part
-of the trust claim, not something to bury. Two dimensions produced a punitive score for the
-*absence* of a ratable surface rather than a real weakness, and both are fixed:
-Django was flagged critical on dependency hygiene for using version ranges instead of exact
-pins — normal, deliberate practice for a library, not an app; the rubric now scores
-dependency hygiene against archetype-appropriate norms. OSSF Scorecard — Google's own
-supply-chain security auditing tool — was flagged critical on audit-trail completeness for
-publishing release notes via GitHub Releases instead of a committed `CHANGELOG.md`; a
-repository with no ratable audit surface now returns "insufficient data" (excluded from the
-composite) instead of a punitive score. The board also publishes a measured-coverage
-indicator per row: a score reflects only its *measured* dimensions, and a row scored on fewer
-than half of its applicable dimensions is shown as unranked rather than ordered against
-better-evidenced rows.
+## Install
 
-## Usage
+No account, no key, no signup.
+
+**Single-file binary.** One file. No Node, no npm, no `node_modules`, nothing installed.
+
+```bash
+curl -fsSL https://github.com/BargLabs/cejel/releases/latest/download/cejel-$(uname -s)-$(uname -m) -o cejel
+chmod +x cejel
+./cejel .
+```
+
+**Don't take the offline claim on trust — check it.** Turn your network off, then run the
+binary. It will score your repository and write you a certificate anyway. That is the whole
+product, and you can falsify it in ten seconds:
+
+```bash
+# with Wi-Fi off, or:
+docker run --rm --network=none -v "$PWD:/w" -w /w -v "$PWD/cejel:/cejel:ro" debian:stable-slim /cejel .
+```
 
-Run it with whichever package manager you already have — no install, no signup. All of
-these pull the same `cejel` package from the npm registry:
+**npm.**
 
 ```bash
-npx cejel .          # npm
-pnpm dlx cejel .     # pnpm
-yarn dlx cejel .     # yarn
-bunx cejel .         # bun
-deno run -A npm:cejel .   # deno
+npx @cejel/cejel .
+```
+
+> **On the name.** npm rejects the unscoped `cejel` package name as too similar to an
+> existing package (`level`). The published package is the scoped `@cejel/cejel`.
+
+**GitHub Action** — score every PR and publish the badge:
+
+```yaml
+- uses: BargLabs/cejel/action@v1
+  with:
+    min-score: "2.5"   # optional: fail the build below this
+```
+
+**From source** — it is AGPL and it runs offline, so reading it is rather the point:
+
+```bash
+git clone https://github.com/BargLabs/cejel && cd cejel
+pnpm install && pnpm build
+node dist/index.js .
+```
+
+Released binaries: `cejel-Darwin-arm64`, `cejel-Linux-x86_64`. A Homebrew tap and the
+remaining architectures are in progress; they are not listed here because they do not exist
+yet.
+
+## Usage
+
+```bash
+./cejel .
 ```
 
 Scores the current directory with sensible defaults: no flags, no signup, fully offline.
@@ -85,13 +88,42 @@ Prints a concise terminal certificate and writes to `.cejel/`:
 ### Flags
 
 - `<path>` — repo to score (default: current directory)
-- `--out-dir <dir>` — where to write report/certificate/badge files (default: `.cejel`)
+- `--out <dir>` — where to write report/certificate/badge files (default: `.cejel`;
+  `--out-dir` remains available as a compatibility alias)
 - `--min-score <n>` — exit non-zero if the overall score is below `n` (0–4); used by the
   GitHub Action's optional threshold gate
 - `--ingest <file|glob>` — fold another scanner's output into the score (repeatable). Accepts
   SARIF, OpenSSF Scorecard JSON, or the generic Cejel external-signal shape — format is
   auto-detected. See "Aggregate your scanners" below.
 - `--quiet` — suppress the terminal certificate (files are still written)
+- `-h`, `--help` — print usage and exit successfully
+- `-v`, `--version` — print the version derived from the package manifest and exit successfully
+
+## Supported languages
+
+Cejel reads a repository's file tree, not its bytecode — it needs to recognise a file's
+source extension to say anything about it. It does not support every language, and it says so
+honestly rather than guessing:
+
+- **Deeply modelled** — JS/TS, Python: test detection, coverage, and claim-vs-reality checks
+  are tuned specifically for these ecosystems.
+- **Partially modelled** — Go, Rust, Java, Ruby, PHP, C#, C/C++, Swift, Kotlin, Dart, Elixir,
+  Scala: recognised as source and scored on the language-agnostic dimensions (CI discipline,
+  dependency hygiene, audit trail, secrets), but without ecosystem-specific test-framework
+  tuning.
+- **Recognised but unmodelled** — shell, R, Lua, Julia, Haskell, Terraform, SQL, Perl, OCaml,
+  Clojure, Erlang, Nim, Zig, F#, Groovy: counted as source so a repo isn't misread as empty,
+  but with the least ecosystem-specific tuning of the three tiers.
+- **Not yet recognised** — other ecosystems, including COBOL, Fortran, and MATLAB. Cejel does
+  not score these as "source" at all: a repository with zero
+  recognised-extension files gets the `unrecognised_ecosystem` archetype, an explicit
+  `insufficient_data` status, and **no verdict** — never a confident numeric score, and never
+  the word "Unverified" for the sole reason that cejel cannot read the language. The
+  certificate states plainly which of the 11 dimensions were and were not measured.
+
+This list will grow. It will never be "any codebase" — that claim is a promise the parser
+cannot keep, and an honest support matrix is worth more than a marketing line the code
+contradicts on the first unsupported repository someone runs it against.
 
 ## Aggregate your scanners
 
@@ -101,7 +133,7 @@ Cejel folds those findings into the same rubric-scored, offline trust certificat
 contributing tools shown in the certificate and report as provenance:
 
 ```bash
-npx cejel . --ingest munatrust.sarif --ingest scorecard.json
+./cejel . --ingest munatrust.sarif --ingest scorecard.json
 ```
 
 Or drop files in `.cejel/inputs/` and they're picked up automatically, no flag needed:
@@ -109,7 +141,7 @@ Or drop files in `.cejel/inputs/` and they're picked up automatically, no flag n
 ```bash
 mkdir -p .cejel/inputs
 cp munatrust-results.sarif .cejel/inputs/
-npx cejel .
+./cejel .
 ```
 
 External findings only ever adjust a dimension score *downward*, and by a bounded amount —
@@ -176,7 +208,7 @@ a configurable `min-score` threshold. The scoring step makes no network calls an
 secrets.
 
 ```yaml
-- uses: BargLabs/cejel/action@main
+- uses: BargLabs/cejel/action@v1
   with:
     min-score: '2.5' # optional; omit to never fail the check
 ```
@@ -195,7 +227,7 @@ Add it to an MCP client config:
   "mcpServers": {
     "cejel": {
       "command": "npx",
-      "args": ["-y", "--package=cejel", "cejel-mcp"]
+      "args": ["-y", "--package=@cejel/cejel", "cejel-mcp"]
     }
   }
 }
@@ -206,18 +238,19 @@ The server exposes one tool and two resources:
 - `scan` — input `{ path, format? }`; scores the repository at `path` and returns the trust
   cert as JSON (`format: "summary"`, the default, is the compact digest; `format: "json"` is
   the full report, identical to the CLI's `report.json`).
-- `cejel://last-scan/certificate.html` and `cejel://last-scan/badge.svg` — the HTML
-  certificate and SVG badge for the most recent scan.
+- `cejel-cejel://last-scan/certificate.html` and `cejel-cejel://last-scan/badge.svg` — the
+  HTML certificate and SVG badge for the most recent scan (the URI scheme derives from the
+  npm package name, `@cejel/cejel` → `cejel-cejel`).
 
 Like the CLI, scoring over MCP is fully offline: no network calls, no telemetry, no signup,
 and the server writes no files.
 
 ## What "offline" means here
 
-Scoring a repo — `npx cejel .` itself, and the Action's scoring step — makes zero network
-calls: no telemetry, no signup, no model call. Fetching the `cejel` package the first time
-(like any npm-distributed CLI, including this Action's own dependency install) does need
-network; that's a one-time install cost, not part of the scoring guarantee.
+Scoring a repo — `cejel .` itself, and the Action's scoring step — makes zero network
+calls: no telemetry, no signup, no model call. Fetching the `@cejel/cejel` package the
+first time (like any npm-distributed CLI, including this Action's own dependency install)
+does need network; that's a one-time install cost, not part of the scoring guarantee.
 
 ## The public leaderboard: what we redact, what we exclude, and where we were wrong
 
@@ -236,19 +269,20 @@ enforced structurally — the public artifacts are built from filtered data rath
 rendered and then scrubbed — and a build that would emit a private path fails rather than
 publishes.
 
-**What we exclude from ranking.** Two of the eleven dimensions — B1 (dispatch trace
-completeness) and B5 (verified learning trace) — measure signals that only exist inside the
-agent substrate Cejel was built in. No external repository can produce them. They are
-therefore **excluded from the ranking for every repository, including ours**: we do not
-score you on something you cannot have, and we do not award ourselves points for something
-you cannot contest. You will still see them defined in the rubric source, because the rubric
-is the published standard and hiding two of its dimensions would make it incomplete. Where a
-dimension does not apply to a repository, the certificate says *not applicable* rather than
-quietly scoring it zero.
-
-**Where we were wrong.** Calibrating this rubric against real repositories surfaced four
-errors in our own tool, all found before publication and all fixed. We list them because a
-scoring tool that has never been wrong is a scoring tool that has not been checked:
+**What we exclude from ranking.** The v3 repository scanner does not evaluate B1 (dispatch
+trace completeness) or B5 (verified learning trace) for repository inputs, including ours:
+both are always *not applicable* in a repository certificate. They remain defined in the
+rubric for structured substrate evidence, but that evidence is not accepted by this scanner.
+The ranking excludes both dimensions fail-closed, including when it reads a legacy or
+separately produced structured report. We neither score you on evidence the public scanner
+cannot collect nor award ourselves points for evidence you cannot contest.
+
+**Where we were wrong.** Calibrating this rubric against real repositories — and running the
+board itself like a stranger would — surfaced the errors below in our own tool, every one found
+by us and every one fixed. The list is its own count; we do not keep a tally in this sentence,
+because a number typed by hand beside a list that grows is exactly the kind of unchecked claim
+this tool exists to catch. We publish them because a scoring tool that has never been wrong is a
+scoring tool that has not been checked:
 
 - **Django, scored a false critical on dependency hygiene.** We applied application-shaped
   expectations to a library. Archetype now gates the dimension.
@@ -267,11 +301,45 @@ scoring tool that has never been wrong is a scoring tool that has not been check
   the *shape* (a cron-scheduled workflow that runs the verification suite, and whether its
   results are durably published or only handed to an ephemeral CI artifact); our own internal
   nightly QA workflow is one recognized instance of that shape, not its definition.
-
-Every one of these was a false alarm produced by *us*, about *other people's code*, and we
-would rather you knew that than discovered it. If you believe the board scores your
-repository wrongly, open an issue — a rubric that cannot be corrected in public has no
-business being published in public.
+- **Our board and our own certificates disagreed on four repositories' headline scores by
+  0.1** — two coherent bases (the board's fair cross-repo ranking basis, and each
+  certificate's own-dimension basis), one word, "Overall", printed on both. We found it on
+  launch day and fixed it: "Overall" is now byte-identical everywhere it appears — board,
+  certificate, badge, report, and JSON — and the ranking basis, where it genuinely differs,
+  has its own separate, explicitly labeled column instead of borrowing the same name.
+- **Our own row used a scoring path nobody else could run.** The board generator could add
+  internal collectors after the public scan, so its reassuring collector blacklist was not
+  the invariant it claimed to be. Rubric v3 removes that second path: every corpus row now
+  passes through the same sealed public scorer, every external source is pinned to a commit,
+  and a required guard re-scores every row and compares score, verdict, coverage, and
+  evidence. The honest correction moved Alfred's Code score from 2.5 to 2.4 and A5 from 2.9
+  to 2.4. It is less flattering and more trustworthy.
+- **Version 0.1.1 rejected `--help` and `--version` as unknown flags, and read `-h` as a
+  directory path.** Version 0.1.2 handles both aliases before positional-path parsing and
+  derives its printed version from the package manifest.
+- **We reported a timing side-channel in our own test fixtures.** Pointed at its own
+  repository, Cejel's secret-handling dimension flagged a "non-constant-time secret
+  comparison" — in string literals inside a test file, the deliberately-insecure example code
+  that exists to prove the detector fires. It read a *file*, not a comparison, and reported a
+  vulnerability in the test written to catch that vulnerability. Two sub-rules of the same
+  dimension held two different private notions of what "production code" meant, and the one
+  that had none was the louder. Version 0.1.3 gives every rule one shared, derived answer to
+  that question, and reports the real line of a real match or nothing at all.
+- **We fixed the COBOL false-verdict, shipped it, and it was still broken.** An earlier release
+  corrected a repository written in a language we cannot read being scored anyway. The fixture
+  that proved the fix contained COBOL and nothing else. The first real COBOL repository we
+  pointed it at — AWS's mainframe credit-card demo — carried nine incidental shell scripts
+  among 329 files, and those nine were enough to short-circuit the abstention path entirely:
+  a 99%-COBOL codebase was scored on its deploy scripts and drew a confident `0.0`,
+  "Unverified". Every real legacy repository has a deploy script, so the fix that passed every
+  test was unreachable for essentially all of them. Recognised source must now be *dominant*,
+  not merely present. **A fixture cleaner than reality proves nothing.**
+
+Every one was a trust failure produced by *us* — false alarms about other people's code,
+silent omissions, inconsistent presentation, or a home-only scoring path — and we would
+rather you knew that than discovered it. If you believe the board scores your repository
+wrongly, open an issue — a rubric that cannot be corrected in public has no business being
+published in public.
 
 **No rubric change re-scores you silently.** Every change to scoring behavior requires a
 `WITAN_RUBRIC_VERSION` bump and a corpus-wide before/after delta published in