Skip to main content

@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​

FileBeadExports
src/functions.tsCC-1.1discoverFunctions, functionAt, cyclomaticComplexity, cognitiveComplexity, types FunctionInfo, FunctionKind, Position
src/coverage.tsCC-1.2parseCoverage, functionCoverage, crap, CoverageReport, FileCoverage
src/report.tsCC-1.3normaliseStrykerReport, QualityReport, parseQualityReport, Mutant, MutantStatus, tupleKey, joinTrustedList, assignStableIds, aggregate, MAX_MUTANTS, MAX_SNIPPET_CHARS, MAX_REPORT_GZIP_BYTES, MAX_COVERAGE_ITEMS
src/gate.tsCC-1.4evaluateGate, types FunctionMetrics, GateThresholds, GateCode, GateFinding, GateResult, Intent
src/static.tsCC-1.5checkStatic, scanFile, fileRole, globToRegExp, types Files, FileRole, FileScan, StaticCode, StaticFinding, StaticInput
src/analysis.tsCC-2.1buildAnalysis, AnalysisOutput, parseAnalysisOutput, chunkCacheKey, treeSha256, inMutateScope, MAX_ANALYSIS_FILES, MAX_ANALYSIS_FUNCTIONS, MAX_ANALYSIS_GZIP_BYTES
src/rewrites.tsCC-3.2drawControls, 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)​

CodeName
function a() { function b() {} }a, a>b
class member, constructor, accessorC.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 apiapi.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 classdefault
any other anonymous functionanon#<n>, counted per parent
overloadsthe implementation only; bodiless signatures, abstract and declare members are skipped
a repeated name in one filesuffix ~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)​

CountedNot 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)​

IncrementConstructs
+1 plus the nesting levelif (not else if), ?:, switch, for, for-in, for-of, while, do, catch
+1 without nestingelse 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 callname(...) 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 statusStored status
Killedkilled
Survivedsurvived
NoCoverageno_coverage
Timeouttimeout
CompileErrorcompile_error
RuntimeErrorruntime_error
Ignoredignored
Pendingpending

QualityReport limits​

QualityReport is a strict zod schema (unknown keys refused):

LimitConstantValue
Mutants per reportMAX_MUTANTS5,000
Characters per original or replacementMAX_SNIPPET_CHARS4,096
Killer files per mutant(schema)500
Gzipped reportMAX_REPORT_GZIP_BYTES128 KiB (report_too_large)
JSON text before gzip is measured(internal)8 MiB
Statements, and branches, of the one covered fileMAX_COVERAGE_ITEMS20,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.

CodeBlockingWhen
survivors_roseyesdelta-judged function: head survivors greater than base survivors
score_fellyesdelta-judged function: head kill ratio below base kill ratio
below_thresholdyesthreshold-judged function: mutation score below thresholds.mutationScore
crap_overyesthreshold-judged function: CRAP (with credited coverage) above thresholds.crap
crap_credit_deniednocoverage rose but the function's score is below the threshold, so the old coverage is used
package_score_fellyessummed kills over summed mutants fell (skipped when the base has no mutants)
complexity_capyesremediation 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).

KeyType and boundsDefault
mutatearray of globs, at least 1(required)
supportarray of globs[]
thresholds.mutationScorenumber 0..100 (percent)70
thresholds.crappositive number30
thresholds.complexityGrowthPctnumber 0..100010
chunkTimeoutMspositive integer, at most 840,000600,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.

RuleCodeDetects
1directive_addedan added Stryker, v8, c8 or istanbul directive comment, counted per file (regex: stryker disable/restore, v8/c8/istanbul ignore)
2test_skip_addedAST: .skip, .only, .todo, skipIf, runIf, fails, also it['skip'], on it, test, describe, suite, bench
3test_removeda deleted test file, or a base test identity (file plus nested describe titles plus title; only string-literal titles count) missing at head
4mutation_runtime_reference__stryker, STRYKER, activeMutant
5code_moved_out_of_scopea 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
6quality_support_changeda 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)
7mutant_count_changedan unchanged file whose trusted mutant count differs between base and head

File roles (fileRole)​

RolePattern (first match wins)
test\.(test|spec)\.[cm]?[jt]sx?$
configvitest/vite config, vitest.workspace/vitest.projects, tsconfig*.json, eslint.config.*, .eslintrc*, or a *setup* source file
supportthe policy's support globs, or default: under test/, tests/, __tests__/, fixture/, fixtures/, or src/testing/
source\.[cm]?[jt]sx?$
otheranything 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: discoverFunctions of each in-scope file with the sha256 of the function's source text (the sourceSha256 that decides "changed" in the gate).
  • mutants: the trusted mutant list as Mutants; a mutant of an out-of-scope file throws.
  • chunks: one chunk per file with trusted mutants. There is no line-range split yet (marked shortcut in analysis.ts); the lines field exists in every schema but buildAnalysis never sets it.
  • cacheInputs: treeSha256 of the package and of every transitive workspace: 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:

  1. the comment-only control: CONTROL_COMMENT (/* crucible control */ ) inserted at the first mutated span;
  2. two rewrites of distinct kinds drawn with seed. The first rewrite is a structural kind whenever one applies (every kind except extra-parens and rename-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-comparisona < b to b > a (both operands free of side effects)
negate-comparisona < b to !(a >= b), a === b to !(a !== b)
swap-commutativea === b to b === a; also !==, ==, !=, *, &, |, ^ (operands free of side effects)
expand-compoundx += e to x = x + (e) for a plain identifier x
invert-ifif (c) A else B to if (!(c)) { B } else { A }
rename-locala const or let declared once in the function, all uses in its block scope, not exported
extra-parensa 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.md
  • packages/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)