@cejel/cejel 0.7.0-rc.1 → 0.7.0-rc.2

package/README.md

@@ -24,8 +24,13 @@ jobs:
       - uses: BargLabs/cejel/action@v1
 ```
 
+Keep `fetch-depth: 0`. `actions/checkout` makes a shallow clone by default, and a shallow clone is
+"Unrated: shallow clone", with no score and no verdict, under every rubric, the default included,
+until the full history is checked out. A directory with no `.git` (an uploaded snapshot or an
+archive) is "Unrated: no git history" under every rubric.
+
 Or run it once from a shell: `npx @cejel/cejel@latest .` More on the Action under
-[GitHub Action](#github-action).
+[GitHub Action](#github-action). To read what comes out, see [Reading the result](#reading-the-result).
 
 Cejel (*"SEH-jel"*) — a trust certificate for your codebase.
 
@@ -75,6 +80,48 @@ untouched holdout, every preregistered gate to pass, and a separately recorded p
 The [defect-class census](docs/defect-class-census.md) publishes the coverage-breadth
 boundary—which defect classes any shipped rule targets—and is explicitly not a recall claim.
 
+## Reading the result
+
+The first page of `certificate.html` (and the block printed after the verdict in the terminal)
+answers four questions in plain words, built only from `report.json`:
+
+- **What holds:** the measured areas the report labels Verified, or Info (one label below, listed
+  as "Partly holds"), each with its score out of 4 and the strongest measurement it saw, for
+  example "Rated Verified, at 1.0 out of 4". Only a score of 4.0 is called the top score. A label
+  and a score are set separately, so a Verified area can have a low score; each area's card in the
+  certificate compares the two. An area Cejel did not examine, or examined with no measurement, is
+  never listed here. When the list is empty, one sentence says why: no overall result, no area
+  labelled Verified or Info, or both.
+- **What is wrong:** every critical and warning-level finding, most serious first, naming the file
+  or area and what is wrong, and every area labelled Critical or Warning that has no critical or
+  warning finding of its own, with its score ("Scored 2.2 out of 4, with no single finding of its own"). A score made
+  up of several measurements is given with its number and level, for example "give 3.1 out of 4,
+  which Cejel counts as a warning".
+- **What is not known:** what the report records it could not establish, from these fields: an
+  overall result it withheld, with its reason restated from a fixed table (a reason the table does
+  not know reads "Cejel could not rate the source here; see the certificate below"); areas that do
+  not apply, have no measurement, or have no score while a finding stands; areas Cejel could not
+  fully read (named in the report's skipped-content summary or by a scan or history limitation),
+  listed as "not read" with the cause the report ties to that area: files that could not be read,
+  Git LFS pointers, files left out under Cejel's size limit or rules, a scan limitation, or a
+  shallow clone; each scan and history limitation, reworded into plain words; files it did not
+  read; a label moved by imported evidence; and each limit a check recorded on what it examined.
+  Anything the report does not record is not listed, so an empty list does not mean nothing is
+  unknown.
+- **What to check next:** one line for each wrong or not-known item, taken from a fixed table of
+  reviewed sentences. The line for an area not read, and for a scan limitation, follows its own
+  cause: `git lfs pull` for Git LFS pointers, making files readable only where they could not be
+  read, and no fix for a size limit or rule. An item with no table entry points to the section of
+  the certificate that holds it.
+
+The first page also says what the result does not cover: Cejel reads files and history and does
+not run the code or its tests. Under a prospective rubric such as
+`witan-rubric-v27-prospective-2026-10-19`, the first page opens, above the verdict line, with the
+same notice the certificate's header carries: the rubric is not calibrated, and its results carry
+no precision or recall claim. Every line links to its source further down; the certificate below
+the first page holds the evidence, unchanged apart from the anchors those links point to.
+`summary.json` carries the same lists under `plainSummary`.
+
 ## Install
 
 No account, no key, no signup.
@@ -116,7 +163,7 @@ if (-not $expected -or $actual -ne $expected.ToLowerInvariant()) {
 ```
 
 > **Windows signing status:** `cejel-Windows-x86_64.exe` is intentionally unsigned in
-> 0.6.8 and may trigger Microsoft SmartScreen. The release build removes Node's inherited
+> 0.6.11 and may trigger Microsoft SmartScreen. The release build removes Node's inherited
 > signature before SEA injection and fails unless Windows reports the result as `NotSigned`;
 > it does not ship an invalid signature. Before running it, verify `SHA256SUMS` and the
 > GitHub build-provenance attestation. Each binary also has an attached SPDX SBOM (the packages
@@ -140,9 +187,10 @@ docker run --rm --network=none -v "$PWD:/w" -w /w -v "$PWD/cejel:/cejel:ro" debi
 npx @cejel/cejel@latest .
 ```
 
-> **Distribution note:** Cejel `0.6.8` is the coordinated release version for npm,
-> standalone binaries, Docker/OCI, GitHub Action, Homebrew, and MCP Registry. A GitLab CI
-> template and Code Quality export live in [`docs/gitlab-ci.md`](./docs/gitlab-ci.md).
+> **Distribution note:** Cejel `0.6.11` is the coordinated release version for npm,
+> standalone binaries, Docker/OCI, GitHub Action, Homebrew, and MCP Registry. On GitLab, use the
+> CI/CD Catalog component `gitlab.com/barglabs/cejel/cejel@0.6.11`; it, the include template and
+> the Code Quality export are documented in [`docs/gitlab-ci.md`](./docs/gitlab-ci.md).
 
 `npx` can reuse a stale cached package. Force the current npm release with the `@latest`
 specifier above, and check the version that will run before comparing certificates:
@@ -181,17 +229,34 @@ The npm package is scoped as `@cejel/cejel`; its executable remains the short co
     min-score: "2.5"   # optional: fail the build below this
 ```
 
-`actions/checkout` fetches one commit by default, so clone in full with `fetch-depth: 0`. On a
-shallow clone the criteria that read commit history see only the commits it holds: A2's scans of
-earlier commits for `.env` files and credentials read only those, and B2 withholds its
-pull-request merge ratio, or abstains where nothing else is left to score it on, saying why in its
-note. The certificate says so under "History limitations".
-Under the opt-in prospective v27 rubric (`--rubric-pin witan-rubric-v27-prospective-2026-10-19`;
-v17 remains the default), A2 abstains on a shallow clone unless a confirmed critical secret finding
-stands, including where it would otherwise be marked not applicable, since that decision also rests
-on earlier commits. That abstention is left out of the composite, but the verdict is capped at the
-band the composite reaches with it counted as 0.
-A2 also abstains under v27 on any clone where one of its reads of earlier commits failed:
+`actions/checkout` fetches one commit by default, so clone in full with `fetch-depth: 0`. Under
+every rubric, the calibrated default included, a shallow clone gets no composite score and no
+verdict until the full history is checked out. The scan abstains (`insufficient_source`), still
+reads and shows each criterion, and says what to do: run `git fetch --unshallow` (or check out with
+full history, for example `fetch-depth: 0` in `actions/checkout`), then scan again. The
+certificate, the badge and the Action's `verdict` output read "Unrated: shallow clone", and the
+Action's `limited` output is `true`. With `--min-score` an abstained scan fails the check, as any
+abstention does, and the message says how to fetch the history. If git cannot report the depth (git
+is not installed, or cannot open the repository), Cejel reads it from the repository's `.git`
+files; if those do not settle it either, the scan abstains the same way as "Unrated: history depth
+unknown". Among the criteria shown on a shallow clone, A2's scans of earlier commits for `.env`
+files and credentials read only the commits it holds, so A2 abstains unless a confirmed critical
+secret finding stands, including where it would otherwise be marked not applicable, since that
+decision also rests on earlier commits; B2 withholds its pull-request merge ratio, or abstains
+where nothing else is left to score it on, saying why in its note. The certificate says so under
+"History limitations". Until 2 November 2026 this held only under the opt-in prospective v27
+rubric (`--rubric-pin witan-rubric-v27-prospective-2026-10-19`; v17 remains the default), and the
+default rubric scored a shallow clone, on which A2 could not see a secret committed and later
+deleted. A complete clone is scored exactly as before.
+
+A directory that is not a git repository gets no composite score and no verdict under every
+rubric, v27 included: "Unrated: no git history". That covers a directory with no `.git`, a
+tarball, an archive export of a commit, and every snapshot uploaded to the HTTP or remote-MCP
+server. A2 abstains, since no commit history was read, unless a confirmed critical secret finding
+stands on the files. Scan a git clone with full history; an uploaded snapshot or archive carries no
+history.
+
+On a clone that is not shallow, A2 abstains under v27 where one of its reads of earlier commits failed:
 for example on a partial clone made with `--filter`, which `fetch-depth: 0` and no `filter` avoid,
 or where a read stops at one of Cejel's own limits: an output limit or the history secret scan's
 cap of 5,000 historical files, which happen on some large complete histories and which a re-scan
@@ -227,16 +292,16 @@ gh attestation verify ./cejel-Windows-x86_64.exe -R BargLabs/cejel
 This is cryptographically signed provenance. It is distinct from Apple Developer ID or
 Microsoft Authenticode code-signing.
 
-**Docker / OCI.** The current container release is `0.6.8`:
+**Docker / OCI.** The current container release is `0.6.11`:
 
 ```bash
-docker run --rm -i -v "$PWD:/workspace:ro" ghcr.io/barglabs/cejel:0.6.8
+docker run --rm -i -v "$PWD:/workspace:ro" ghcr.io/barglabs/cejel:0.6.11
 ```
 
 The image defaults to `cejel-mcp` over stdio. To use the CLI instead:
 
 ```bash
-docker run --rm -v "$PWD:/workspace:ro" --entrypoint cejel ghcr.io/barglabs/cejel:0.6.8 .
+docker run --rm -v "$PWD:/workspace:ro" --entrypoint cejel ghcr.io/barglabs/cejel:0.6.11 .
 ```
 
 The OCI image carries an SBOM of its base-image packages, maximum-mode build provenance, and a
@@ -345,8 +410,8 @@ prints that boundary on every successful verification.
 - `--rubric-pin <version>` — Explicit opt-in only: pin an alternate rubric instead of the
   calibrated public default. It
   accepts the calibrated version or any published prospective rubric
-  (`witan-rubric-v18-prospective-*` through `v26`) and fails closed, naming what was accepted, on
-  anything else. `v26` (`witan-rubric-v26-prospective-2026-10-14`) is prospective and uncalibrated:
+  (`witan-rubric-v18-prospective-*` through `v27`) and fails closed, naming what was accepted, on
+  anything else. The GitHub Action takes the same value as its optional `rubric-pin` input. `v26` (`witan-rubric-v26-prospective-2026-10-14`) is prospective and uncalibrated:
   it is the next calibration candidate, inherits v25 complete, inherits neither v23 nor v24, and
   today scores exactly as v25 does. `v25` is prospective and uncalibrated: it inherits v22 and adds only credit for a
   health or readiness route declared inline in an application file (see "What counts as a health or
@@ -503,11 +568,50 @@ secrets.
     min-score: '2.5' # optional; omit to never fail the check
 ```
 
-Check out with `fetch-depth: 0`: the default depth of 1 truncates the history A2 and B2 read, and
-the certificate then lists a history limitation. On a shallow clone A2's scans of earlier commits
-read only the commits present and B2 withholds its pull-request merge ratio, each with its reason;
-under the opt-in `witan-rubric-v27-prospective-2026-10-19` rubric, A2 abstains and the verdict is
-capped where A2 could not be read.
+Check out with `fetch-depth: 0`. The default depth of 1 is a shallow clone, and under every
+rubric, the default included, a shallow checkout gets no composite score and no verdict: the step
+summary, the badge and the `verdict` output read "Unrated: shallow clone", the `limited` output is
+`true` and `limitations` names the cause, and the scan says to run `git fetch --unshallow` (or check
+out with full history, for example `fetch-depth: 0` in `actions/checkout`), then scan again. On a
+shallow clone A2's scans of earlier commits read only the commits present and B2 withholds its
+pull-request merge ratio, each with its reason. A `repo-path` that is not a git repository is
+"Unrated: no git history" under every rubric. The Action does not pin a rubric, so it scores under
+the default.
+
+| Output | What it holds |
+|---|---|
+| `score` | The overall score (0.0–4.0), or empty when Cejel abstains. |
+| `verdict` | The verdict label, or the abstention label (`Insufficient source`, `Insufficient evidence`, `Unrated: shallow clone`, `Unrated: history depth unknown`, `Unrated: no git history`). |
+| `limited` | `true` when scan limitations qualify the result, or when the verdict is Unrated; otherwise `false`. |
+| `limitation-count` | How many limitations qualify the certificate, counting an Unrated verdict as one. |
+| `limitations` | A JSON array of the limitation messages; an Unrated verdict adds one naming its cause. |
+| `artifact-dir` | Where this run's report artifacts were exported. |
+
+| Input | Default | What it does |
+|---|---|---|
+| `repo-path` | the checkout (`$GITHUB_WORKSPACE`) | Path to the repository to score. |
+| `min-score` | empty: never fail | Fails the step below this overall score (0–4), or when Cejel abstains. |
+| `out-dir` | `.cejel` | Empty destination for this run's report artifacts. |
+| `rubric-pin` | empty: the calibrated default | Explicit opt-in only: the same value as the CLI's `--rubric-pin`. An unknown id fails the step with the CLI's message. |
+
+The scoring step is offline whatever the inputs; it never fetches history. To opt in to the
+prospective v27 rubric, pin it and check out in full with `fetch-depth: 0`: v27 reads the commit
+history, so a shallow checkout gets no full v27 result, as under the default. v17 remains the
+calibrated default.
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0 # full history: A2 and B2 read commit history
+- uses: BargLabs/cejel/action@v1
+  with:
+    rubric-pin: witan-rubric-v27-prospective-2026-10-19
+```
+
+A prospective pin carries no precision/recall claim, and the certificate states that plainly
+whenever one is used. Leave `rubric-pin` empty for the calibrated result every default scan
+produces: an empty input passes no `--rubric-pin`, so the scan, the report and the outputs are
+the same as without the input.
 
 ## Use with Claude
 
@@ -630,7 +734,7 @@ The OCI image is an alternative when Docker is the preferred execution boundary.
 the host path with the repository OpenClaw should allow Cejel to read:
 
 ```bash
-npx -y openclaw@latest mcp set cejel-oci '{"command":"docker","args":["run","--rm","-i","-v","/absolute/path/to/repo:/workspace:ro","ghcr.io/barglabs/cejel:0.6.8"]}'
+npx -y openclaw@latest mcp set cejel-oci '{"command":"docker","args":["run","--rm","-i","-v","/absolute/path/to/repo:/workspace:ro","ghcr.io/barglabs/cejel:0.6.11"]}'
 npx -y openclaw@latest mcp doctor cejel-oci --probe
 ```
 

package/dist/calibration/llm-detector.js

@@ -5,11 +5,11 @@ import {
   deriveProductIdentity,
   runCejelScan,
   serializeWitanReport
-} from "../chunk-SNRQAKKE.js";
+} from "../chunk-G6AN4EDL.js";
 import {
   listCejelLlmPackFiles
-} from "../chunk-UMGZWGOI.js";
-import "../chunk-D7MWEPPX.js";
+} from "../chunk-RRPQHEBU.js";
+import "../chunk-2UMHJ23V.js";
 import {
   external_exports
 } from "../chunk-AMVP7L26.js";
@@ -4855,8 +4855,27 @@ var CejelLlmPackStatusSchema = external_exports.enum([
   "assessed_with_limitations",
   "not_applicable"
 ]);
+var CEJEL_LLM_EVIDENCE_PATH_MAX = 700;
+var CEJEL_LLM_OVER_LIMIT_EVIDENCE = Object.freeze({
+  path: ".",
+  line: null,
+  label: `Path longer than the artifact's ${CEJEL_LLM_EVIDENCE_PATH_MAX}-character limit; not cited`
+});
+function cejelLlmOverLimitPathsLimitation(count) {
+  const one = count === 1;
+  return `Cejel did not cite ${count} repository ${one ? "path" : "paths"} because ${one ? "it is" : "they are"} longer than the artifact's ${CEJEL_LLM_EVIDENCE_PATH_MAX}-character path limit. Every finding that cited ${one ? "it" : "one"} is kept, with its rule, severity, confidence and summary, anchored on the repository ('.') instead. No path is shortened, since a shortened path would name a file that does not exist.`;
+}
+function fitCejelLlmFindingPaths(findings) {
+  const dropped = /* @__PURE__ */ new Set();
+  const fitted = findings.map((finding5) => {
+    if (finding5.evidence.path.length <= CEJEL_LLM_EVIDENCE_PATH_MAX) return finding5;
+    dropped.add(finding5.evidence.path);
+    return { ...finding5, evidence: { ...CEJEL_LLM_OVER_LIMIT_EVIDENCE } };
+  });
+  return dropped.size === 0 ? { findings, droppedPaths: 0 } : { findings: fitted, droppedPaths: dropped.size };
+}
 var CejelLlmEvidenceSchema = external_exports.object({
-  path: external_exports.string().min(1).max(700).refine(
+  path: external_exports.string().min(1).max(CEJEL_LLM_EVIDENCE_PATH_MAX).refine(
     (path) => !path.startsWith("/") && !/^[A-Za-z]:[\\/]/.test(path) && !path.split(/[\\/]/).some((member) => member === ".."),
     { message: "Evidence paths must be repository-relative and cannot traverse parents." }
   ),
@@ -5112,7 +5131,7 @@ function collectCejelLlmPack(repoPath, repoFiles) {
     (rule) => (rule.id === "LLM-AGY-002" ? sourceFiles.filter((file) => isPythonSource(file)) : pythonLlmFiles).flatMap((file) => rule.detect(file))
   );
   const applicable = javascriptLlmFiles.length > 0 || pythonLlmFiles.length > 0 || actionSurfaceFiles.length > 0 || hasEvaluationSurface || pythonLineageFindings.length > 0 || pythonRuleFindings.length > 0;
-  const findings = applicable ? [
+  const detectedFindings = applicable ? [
     ...CEJEL_LLM_V1_RULES.flatMap(
       (rule) => (rule.id === "LLM-IOH-001" ? javascriptUnsafeSinkFiles : javascriptLlmFiles).flatMap((file) => rule.detect(file))
     ),
@@ -5129,6 +5148,7 @@ function collectCejelLlmPack(repoPath, repoFiles) {
     // evidence that an unrelated metrics writer is an LLM evaluation.
     ...detectCejelLlmEvaluationRules(sourceFiles)
   ] : [];
+  const { findings, droppedPaths } = fitCejelLlmFindingPaths(detectedFindings);
   const ruleResults = CEJEL_LLM_ENABLED_RULE_IDS.map((ruleId) => {
     const ruleFindings = findings.filter((finding5) => finding5.ruleId === ruleId);
     const confidence = RULE_CONFIDENCE.get(ruleId) ?? "low";
@@ -5182,7 +5202,7 @@ function collectCejelLlmPack(repoPath, repoFiles) {
     ...pythonLlmFiles.map((file) => file.path),
     ...actionSurfaceFiles.map((file) => file.path),
     ...evaluationSurfaceFiles.map((file) => file.path),
-    ...findings.map((finding5) => finding5.evidence.path)
+    ...detectedFindings.map((finding5) => finding5.evidence.path)
   ]);
   const integrationSet = new Set(integrations);
   if (actionSurfaceFiles.length > 0) integrationSet.add("Model-facing tool registration");
@@ -5209,7 +5229,8 @@ function collectCejelLlmPack(repoPath, repoFiles) {
         "Alpha coverage is limited to fixture-backed JavaScript, TypeScript, and Python source patterns in files up to 1 MB.",
         "Rules use bounded, observable source patterns and do not claim whole-program data-flow analysis.",
         "Action-governance and evaluation-hygiene rules require one of the explicitly supported complete local JavaScript, TypeScript, or Python evidence paths.",
-        "No model-quality, factuality, prompt-injection-resistance, or general hallucination rate is measured."
+        "No model-quality, factuality, prompt-injection-resistance, or general hallucination rate is measured.",
+        ...droppedPaths > 0 ? [cejelLlmOverLimitPathsLimitation(droppedPaths)] : []
       ]
     },
     notes: applicable ? "Static LLM application-integrity alpha; findings require calibration before public release." : "No supported LLM application surface was detected; LLM controls were not scored."

package/dist/{chunk-D7MWEPPX.js → chunk-2UMHJ23V.js}

@@ -89,17 +89,21 @@ function isGitMetadataEntry(path) {
   }
 }
 function hasVisibleGitMetadata(repoPath) {
+  return findVisibleGitMetadata(repoPath) !== void 0;
+}
+function findVisibleGitMetadata(repoPath) {
   let current;
   try {
     current = realpathSync(repoPath);
   } catch {
-    return false;
+    return void 0;
   }
   for (; ; ) {
-    if (discoveryCeiling !== void 0 && current === discoveryCeiling) return false;
-    if (isGitMetadataEntry(join(current, ".git"))) return true;
+    if (discoveryCeiling !== void 0 && current === discoveryCeiling) return void 0;
+    const entry = join(current, ".git");
+    if (isGitMetadataEntry(entry)) return entry;
     const parent = dirname(current);
-    if (parent === current) return false;
+    if (parent === current) return void 0;
     current = parent;
   }
 }
@@ -211,6 +215,7 @@ export {
   GIT_EXEC_MAX_BUFFER_BYTES,
   GIT_EXEC_TIMEOUT_MS,
   hasVisibleGitMetadata,
+  findVisibleGitMetadata,
   execGit,
   isExpectedGitAbsence,
   describeGitFailure