@agentforge/quality-core
packages/quality-core is the pure analysis library of CodeCrucible (plan phase 1, beads CC-1.1 to CC-1.5, CC-2.1,
CC-3.2). It reads TypeScript source and report JSON and returns plain data. It runs no tests, no Docker, no Temporal, no
database, no network and no model, and the same input always gives the same output.
src/ may import only typescript, zod, node:crypto, node:zlib and its own files; an ESLint rule in
packages/quality-core/eslint.config.js enforces that.
The library is used in three places:
Module map
| File | Bead | Exports |
|---|---|---|
src/functions.ts | CC-1.1 | discoverFunctions, functionAt, cyclomaticComplexity, cognitiveComplexity, types FunctionInfo, FunctionKind, Position |
src/coverage.ts | CC-1.2 | parseCoverage, functionCoverage, crap, CoverageReport, FileCoverage |
src/report.ts | CC-1.3 | normaliseStrykerReport, QualityReport, parseQualityReport, Mutant, MutantStatus, tupleKey, joinTrustedList, assignStableIds, aggregate, MAX_MUTANTS, MAX_SNIPPET_CHARS, MAX_REPORT_GZIP_BYTES, MAX_COVERAGE_ITEMS |
src/gate.ts | CC-1.4 | evaluateGate, types FunctionMetrics, GateThresholds, GateCode, GateFinding, GateResult, Intent |
src/static.ts | CC-1.5 | checkStatic, scanFile, fileRole, globToRegExp, types Files, FileRole, FileScan, StaticCode, StaticFinding, StaticInput |
src/analysis.ts | CC-2.1 | buildAnalysis, AnalysisOutput, parseAnalysisOutput, chunkCacheKey, treeSha256, inMutateScope, MAX_ANALYSIS_FILES, MAX_ANALYSIS_FUNCTIONS, MAX_ANALYSIS_GZIP_BYTES |
src/rewrites.ts | CC-3.2 | drawControls, rewriteSites, applyEdits, seededRandom, CONTROL_COMMENT, REWRITE_KINDS |
Function discovery (CC-1.1)
discoverFunctions(fileName, sourceText) parses one file with the TypeScript compiler API and returns a <module>
entry (top-level code, whole-file span) followed by every function with a body, in source order: declarations, methods,
constructors, getters, setters, arrow functions and function expressions. The FunctionKind values are module,
function, method, constructor, getter, setter, arrow, function-expression.
Spans use 1-based lines and 1-based columns with an exclusive end, the convention of Stryker report locations.
functionAt(functions, position) returns the innermost function containing a position.
Qualified names (plan 4.6)
| Code | Name |
|---|---|
function a() { function b() {} } | a, a>b |
| class member, constructor, accessor | C.m, C.constructor, C.get x, C.set x |
const f = () => {}, x.f = function () {}, class field f = () => {} | f (C.f for the field) |
const api = { run() {} }, nested { inner: { go: () => 1 } } under api | api.run, api.inner.go |
anonymous callback, argument i of a call or new | <parent>>cb@<callee>#<i>; <parent> is <module> at top level; <callee> is the identifier or the last property name |
export default () => {} or an unnamed default function or class | default |
| any other anonymous function | anon#<n>, counted per parent |
| overloads | the implementation only; bodiless signatures, abstract and declare members are skipped |
| a repeated name in one file | suffix ~2, ~3, ... in source order |
Complexity rules (CC-1.1)
Each function is measured over its own parameters and body. A nested function is excluded from its parent and measured as its own entry, so it adds neither complexity nor nesting to the parent. SonarSource counts lambdas into the enclosing method; this package does not, because each callback gets its own CRAP and mutation score.
Cyclomatic (McCabe, decision points + 1)
| Counted | Not counted |
|---|---|
if, ?:, for, for-in, for-of, while, do, each non-default case, catch, each &&, ||, ??, &&=, ||=, ??= | else, default, try, finally, optional chaining ?. |
Cognitive (SonarSource white paper, subset)
| Increment | Constructs |
|---|---|
| +1 plus the nesting level | if (not else if), ?:, switch, for, for-in, for-of, while, do, catch |
| +1 without nesting | else if, else, a labelled break or continue |
| +1 per run of identical logical operators | &&, ||, ?? in a flattened expression, looking through parentheses; a negation or a call starts a new expression |
| +1 per direct recursive call | name(...) or this.name(...); indirect recursion is not counted |
Nesting rises inside the branches of if/else, ?:, switch, loop bodies and catch blocks.
test/fixtures/complexity.ts.txt holds the 20 hand-computed functions of acceptance criterion AC1, including the white
paper's sumOfPrimes (7), getWords (1), the try/catch example (9) and the logical-operator example (4). Bead .110
(open) notes that cognitive complexity covers a SonarSource subset only.
Coverage and CRAP (CC-1.2)
parseCoverage(json) validates the istanbul-style coverage-final.json that
vitest run --coverage --coverage.reporter=json writes with the v8 provider. Extra keys such as fnMap are ignored; a
malformed report throws.
functionCoverage(fileCoverage, functions) assigns each statement and each branch arm to the innermost function
containing its start. Istanbul columns are 0-based and are converted.
coverage = (covered statements + covered branch arms) / (statements + branch arms)
a function with no items gets 0
crap(C, cov) = C^2 * (1 - cov)^3 + C
C = cyclomatic complexity
cov = coverage in [0, 1]; out-of-range input throws RangeError
Fixtures: the main fixture is hand-made in the istanbul format. test/fixtures/real-v8/ holds a real Vitest 5.1.0 v8
report, trimmed to agent-core/src/limits.ts, with the null end columns v8-to-istanbul writes; it was generated from
docs/spikes/quality.
Coverage is computed in the test container, which is untrusted. The exec worker caps it with the mutation results
(capCoverage in apps/worker/src/quality/exec-activities.ts):
capped = min(reported, 1 - (no_coverage mutants / all mutants of the function))
A function with no mutants keeps the reported value. Full coverage that no mutant contradicts is unverifiable at this point; CRAP credit still needs the function's mutation score (gate step 8, below).
Report schema, trusted-list join, stable ids, aggregation (CC-1.3)
normaliseStrykerReport(raw)
Turns a Stryker JSON report (files[].mutants[], testFiles) into a QualityReport. Per mutant it keeps the tuple
(package-relative file, start and end line/column, mutator, replacement), the original text cut from the file's source
by span, the status in snake_case and killedBy as sorted test files. Stryker ids, coveredBy and source text are
dropped: ids differ between a package-wide and a one-file run (S1 measured 35, 36 against 0, 1). A malformed
report, a location outside the source or an unknown test id throws.
| Stryker status | Stored status |
|---|---|
Killed | killed |
Survived | survived |
NoCoverage | no_coverage |
Timeout | timeout |
CompileError | compile_error |
RuntimeError | runtime_error |
Ignored | ignored |
Pending | pending |
QualityReport limits
QualityReport is a strict zod schema (unknown keys refused):
| Limit | Constant | Value |
|---|---|---|
| Mutants per report | MAX_MUTANTS | 5,000 |
| Characters per original or replacement | MAX_SNIPPET_CHARS | 4,096 |
| Killer files per mutant | (schema) | 500 |
| Gzipped report | MAX_REPORT_GZIP_BYTES | 128 KiB (report_too_large) |
| JSON text before gzip is measured | (internal) | 8 MiB |
| Statements, and branches, of the one covered file | MAX_COVERAGE_ITEMS | 20,000 |
parseQualityReport(text) refuses text whose gzip exceeds 128 KiB with a RangeError('report_too_large').
The join
tupleKey(m) is the join key: (file, start line/column, end line/column, mutator, replacement). Stryker ids are never
used. joinTrustedList(trusted, real) returns matched, onlyInList, onlyInReal and mutants (the whole list with
missing entries as survived and no killers).
Stable ids
assignStableIds(mutants, sources) sets each mutant's function (innermost, functionAt) and
stableId = sha256(JSON [file, function, mutator, original, replacement, ordinal])
The ordinal counts only mutants with the same (mutator, original, replacement) in that function, in position order.
Lines and columns are not hashed, so blank lines or a statement added elsewhere keep ids. A mutant whose original text
encloses the edit (for example the BlockStatement of the edited body) gets a new id by design. AC2 checks: 10 blank
lines above a function change 0 ids; a statement inserted inside the function changes 0 ids of the other mutants; two
identical expressions get distinct ids.
Aggregation
aggregate(records) gives counts (total, killed, survived, noCoverage, timeout, other) and
mutation score = (killed + timeout) / all mutants
per (file, function) and per file, sorted. other is compile_error, runtime_error, ignored and pending.
Gate evaluator (CC-1.4)
evaluateGate({ intent, thresholds, base, head }) implements plan 4.3 steps 4 and 8. Input rows are FunctionMetrics:
file, name, sourceHash, cyclomatic, coverage (in [0, 1]), killed (includes timeouts), survived. It returns
passed:remediation, passed:feature or failed plus findings.
| Code | Blocking | When |
|---|---|---|
survivors_rose | yes | delta-judged function: head survivors greater than base survivors |
score_fell | yes | delta-judged function: head kill ratio below base kill ratio |
below_threshold | yes | threshold-judged function: mutation score below thresholds.mutationScore |
crap_over | yes | threshold-judged function: CRAP (with credited coverage) above thresholds.crap |
crap_credit_denied | no | coverage rose but the function's score is below the threshold, so the old coverage is used |
package_score_fell | yes | summed kills over summed mutants fell (skipped when the base has no mutants) |
complexity_cap | yes | remediation only: summed cyclomatic of changed files rose by more than complexityGrowthPct percent (skipped when the base sum is 0) |
Comparisons use integer ratios (ratioLess(a, b, c, d) compares a/b < c/d by cross-multiplication; an empty side scores
1). The thresholds are validated: mutationScore in 0..100, complexityGrowthPct in 0..1000, coverage in [0, 1],
cyclomatic at least 1; anything else throws RangeError.
QualityPolicy (operator)
The only place thresholds, globs and timeouts live. It is the optional quality key of FactoryRepoPolicy in
packages/agent-types/src/factory.ts, loaded from FACTORY_POLICY_DIR/<repo name>.json. Strict: an unknown key is a
startup error. Absent means CodeCrucible is off for that repo (admission refuses not_enabled).
| Key | Type and bounds | Default |
|---|---|---|
mutate | array of globs, at least 1 | (required) |
support | array of globs | [] |
thresholds.mutationScore | number 0..100 (percent) | 70 |
thresholds.crap | positive number | 30 |
thresholds.complexityGrowthPct | number 0..1000 | 10 |
chunkTimeoutMs | positive integer, at most 840,000 | 600,000 |
protectedBranch | ^(?!-)(?!.*\.\.)[A-Za-z0-9._/-]{1,255}$ | main |
Static checks (CC-1.5)
checkStatic({ base, head, mutate, support?, mutantCounts? }) (plan 4.2) takes trees as package-relative path to text
and returns blocking findings, sorted. Every v1 static finding is blocking.
| Rule | Code | Detects |
|---|---|---|
| 1 | directive_added | an added Stryker, v8, c8 or istanbul directive comment, counted per file (regex: stryker disable/restore, v8/c8/istanbul ignore) |
| 2 | test_skip_added | AST: .skip, .only, .todo, skipIf, runIf, fails, also it['skip'], on it, test, describe, suite, bench |
| 3 | test_removed | a deleted test file, or a base test identity (file plus nested describe titles plus title; only string-literal titles count) missing at head |
| 4 | mutation_runtime_reference | __stryker, STRYKER, activeMutant |
| 5 | code_moved_out_of_scope | a base function gone from its in-scope file whose body (from the first {, whitespace-insensitive, at least 20 characters) appears in an out-of-scope head file |
| 6 | quality_support_changed | a changed or deleted pre-existing support file; any vitest, vite, tsconfig, eslint config or setup file; a newly added config or setup file (a new fixture file is fine) |
| 7 | mutant_count_changed | an unchanged file whose trusted mutant count differs between base and head |
File roles (fileRole)
| Role | Pattern (first match wins) |
|---|---|
test | \.(test|spec)\.[cm]?[jt]sx?$ |
config | vitest/vite config, vitest.workspace/vitest.projects, tsconfig*.json, eslint.config.*, .eslintrc*, or a *setup* source file |
support | the policy's support globs, or default: under test/, tests/, __tests__/, fixture/, fixtures/, or src/testing/ |
source | \.[cm]?[jt]sx?$ |
other | anything else |
globToRegExp: ** crosses directories, * and ? do not. inMutateScope follows Stryker mutate semantics: in
scope if a plain glob matches and no ! glob does.
test/static.test.ts holds the 16 fixtures of AC9: 14 blocking, 2 clean.
Stated limits (README): rules 1, 2 and 4 are tripwires (t['sk'+'ip'], dynamic titles and describe.each([]) pass
them; verify step 2 and the re-kill defend); a function renamed and also edited when moved is not matched; the
non-blocking review finding for a 30 percent fall in trusted mutants (plan 4.4) is not implemented.
Analysis out file (CC-2.1)
buildAnalysis({ package, mutate, support, files, listReport, dependencies }) builds analysis.json
(AnalysisOutput, strict zod), the out file of the analysis container (apps/worker/quality-image/analyze.mjs), from
one package tree (package-relative path to bytes) and the raw Stryker report of the host-only list run.
files: every package file with its sha256, rule-6 role, mutate scope, tamper scan (directive, skip and mutation-runtime counts) and static test identities (scanFile).functions:discoverFunctionsof each in-scope file with the sha256 of the function's source text (thesourceSha256that decides "changed" in the gate).mutants: the trusted mutant list asMutants; a mutant of an out-of-scope file throws.chunks: one chunk per file with trusted mutants. There is no line-range split yet (markedshortcutinanalysis.ts); thelinesfield exists in every schema butbuildAnalysisnever sets it.cacheInputs:treeSha256of the package and of every transitiveworkspace:dependency directory.treeSha256= sha256 of the JSON of sorted (path, content sha256) pairs.
chunkCacheKey({ cacheInputs, chunk, imageDigest, configSha256 }) =
sha256(JSON [packageTreeSha256, [[dep name, dep treeSha256]...], [file, lines.start or null, lines.end or null], imageDigest, configSha256]).
parseAnalysisOutput(text) refuses text above 8 MiB or above 1 MiB gzipped (analysis_too_large) and any schema
violation. The test container's mutation.json (run.mjs) is a QualityReport, read with parseQualityReport.
Control rewrites (CC-3.2)
Verify step 7 runs three controls per function that has a credit candidate: behaviour-preserving edits a test should
not notice. drawControls({ file, source, qualifiedName, targets, seed }) returns:
- the comment-only control:
CONTROL_COMMENT(/* crucible control */) inserted at the first mutated span; - two rewrites of distinct kinds drawn with
seed. The first rewrite is a structural kind whenever one applies (every kind exceptextra-parensandrename-local), so a token stream that ignores parentheses and names still changes.
Sites overlapping a mutated span in targets are preferred. A kind with no site, or whose every site adds a syntax error
on re-parse, is skipped and another drawn; fewer than two rewrites sets limited (finding controls_limited).
seededRandom(seed) is sha256(seed + ":" + i) read as a 32-bit fraction, so a draw is reproducible from the recorded
seed. The exec worker passes a fresh host seed (randomBytes(16)) per call and records it after the run.
rewriteSites(file, source, qualifiedName) lists every site by AST span; applyEdits applies one.
Kind (REWRITE_KINDS) | Rewrite |
|---|---|
flip-comparison | a < b to b > a (both operands free of side effects) |
negate-comparison | a < b to !(a >= b), a === b to !(a !== b) |
swap-commutative | a === b to b === a; also !==, ==, !=, *, &, |, ^ (operands free of side effects) |
expand-compound | x += e to x = x + (e) for a plain identifier x |
invert-if | if (c) A else B to if (!(c)) { B } else { A } |
rename-local | a const or let declared once in the function, all uses in its block scope, not exported |
extra-parens | a binary expression (not a comma) wrapped in parentheses |
empty-statement | ; before the closing brace of the function body (the S1 spike's code control) |
Stated limit: !(a >= b) differs from a < b when an operand is NaN or undefined; a test that pins exactly that case
at a mutated comparison gets control_killed.
Sources
packages/quality-core/README.mdpackages/quality-core/src/index.ts,functions.ts,coverage.ts(crap,functionCoverage),report.ts(MAX_*,STATUS_BY_STRYKER,Mutant,QualityReport,tupleKey),gate.ts(evaluateGate,ratioLess),static.ts(fileRole,globToRegExp,DIRECTIVE,RUNTIME,SUPPORT_DEFAULT),analysis.ts(buildAnalysis,chunkCacheKey,treeSha256,parseAnalysisOutput),rewrites.ts(CONTROL_COMMENT,seededRandom,drawControls)packages/agent-types/src/factory.ts(QualityPolicy,FactoryRepoPolicy.quality)apps/worker/src/quality/exec-activities.ts(capCoverage,buildChunkReport)docs/p2-findings.md("CodeCrucible Phase 0 spikes", S1)docs/sessions/2026-11-16-codecrucible-build/FOLLOWUPS.md(bead.110).omc/plans/codecrucible-mutant-hunter.md(sections 4.2, 4.3, 4.6)