@cejel/cejel 0.1.3 → 0.1.5

package/README.md

@@ -20,6 +20,10 @@ 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.
 
+The reusable Barg Labs listing mark is kept at [`brand/barg-icon.png`](./brand/barg-icon.png)
+for directories and registries that accept a custom image. GitHub Actions Marketplace uses
+GitHub's predefined `action.yml` branding icons instead.
+
 ## Install
 
 No account, no key, no signup.
@@ -27,7 +31,15 @@ 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
+asset="cejel-$(uname -s)-$(uname -m)"
+curl -fsSL "https://github.com/BargLabs/cejel/releases/latest/download/$asset" -o "$asset"
+curl -fsSL https://github.com/BargLabs/cejel/releases/latest/download/SHA256SUMS -o SHA256SUMS
+if command -v sha256sum >/dev/null; then
+  grep "  $asset$" SHA256SUMS | sha256sum -c -
+else
+  grep "  $asset$" SHA256SUMS | shasum -a 256 -c -
+fi
+mv "$asset" cejel
 chmod +x cejel
 ./cejel .
 ```
@@ -47,8 +59,7 @@ docker run --rm --network=none -v "$PWD:/w" -w /w -v "$PWD/cejel:/cejel:ro" debi
 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`.
+The npm package is scoped as `@cejel/cejel`; its executable remains the short command `cejel`.
 
 **GitHub Action** — score every PR and publish the badge:
 
@@ -66,9 +77,52 @@ 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.
+Released binaries: `cejel-Darwin-arm64`, `cejel-Darwin-x86_64`, `cejel-Linux-aarch64`, and
+`cejel-Linux-x86_64`. The release also carries `SHA256SUMS`; each binary is executed against
+the source build and with networking denied before attachment.
+
+## 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). Every score on this board is produced by the same sealed
+public scorer used by `npx @cejel/cejel .` — check out the source commit printed in the
+report, run the tool, and you will get this number. A required guard does exactly that for
+every corpus row and compares score, verdict, measured coverage, and evidence. No private
+domain collector contributes to any published score, ours included; nobody is exempt.
+
+### 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 v3 repository scanner marks B1 and B5 not applicable for every repository,
+including ours; it does not accept structured substrate evidence for them. They remain
+defined for other rubric inputs, while the repository ranking excludes them fail-closed.
+Nobody is scored on evidence the public scanner cannot collect.
+
+### 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.
 
 ## Usage
 
@@ -79,19 +133,28 @@ yet.
 Scores the current directory with sensible defaults: no flags, no signup, fully offline.
 Prints a concise terminal certificate and writes to `.cejel/`:
 
-- `report.json` — the full structured report
+- `report.json` — the full structured report; scored runs carry numeric headline scores and a
+  score-band `verdict`, while abstained runs carry `null` scores and `verdict: "insufficient_source"`
+- `attestation.json` — an unsigned in-toto statement binding the report digest, repository
+  revision, rubric, and scored-or-abstained outcome; ready for an external signer
 - `certificate.html` — a self-contained HTML certificate (no external assets)
 - `badge.json` — a [shields.io endpoint](https://shields.io/badges/endpoint-badge) payload
 - `badge.svg` — a static, self-contained trust-score badge
 - `summary.json` — a compact digest (score, verdict, top findings)
 
+The attestation is deliberately explicit about its assurance level: Cejel creates the
+statement, but it does not pretend to be an independent signer. Until a customer, reviewer,
+or provenance system signs it, `assurance.status` is `unsigned` and `issuer` is
+`self-generated`. An abstained scan carries only the refusal reason, never a numeric score.
+
 ### Flags
 
 - `<path>` — repo to score (default: current directory)
 - `--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
+- `--min-score <n>` — exit non-zero if the overall score is below `n` (0–4), or if Cejel
+  abstains and therefore cannot evaluate the threshold; 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.
@@ -117,9 +180,10 @@ honestly rather than guessing:
 - **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.
+  `insufficient_data` criterion status, `null` headline scores, and an explicit machine verdict
+  of `insufficient_source` — never a numeric score-band verdict, 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
@@ -238,9 +302,9 @@ 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-cejel://last-scan/certificate.html` and `cejel-cejel://last-scan/badge.svg` — the
+- `cejel://last-scan/certificate.html` and `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`).
+  npm package name).
 
 Like the CLI, scoring over MCP is fully offline: no network calls, no telemetry, no signup,
 and the server writes no files.
@@ -252,6 +316,20 @@ calls: no telemetry, no signup, no model call. Fetching the `@cejel/cejel` packa
 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.
 
+## Help validate Cejel
+
+Cejel does not collect telemetry. External validation is therefore opt-in and inspectable:
+
+- [Report a calibration result](https://github.com/BargLabs/cejel/issues/new?template=calibration.yml)
+  when a score, finding, evidence pointer, or refusal is wrong. The form asks permission before
+  a correction is added to the public error ledger.
+- [Join a pack design-partner pilot](https://github.com/BargLabs/cejel/issues/new?template=pack-interest.yml)
+  for the Quant or Healthcare Pack. Both remain pilot surfaces until their domain-specific
+  calibration gates pass.
+
+Submit only public or redacted evidence. Never put credentials, proprietary strategy code,
+patient data, or protected health information in a GitHub issue.
+
 ## The public leaderboard: what we redact, what we exclude, and where we were wrong
 
 We publish a trust board scoring a corpus of well-known open-source repositories alongside