diff --git a/scripts/verify/advertised-schemas/tools/measure_build_task.json b/scripts/verify/advertised-schemas/tools/measure_build_task.json index 5fe911c7e0..fc2a390f55 100644 --- a/scripts/verify/advertised-schemas/tools/measure_build_task.json +++ b/scripts/verify/advertised-schemas/tools/measure_build_task.json @@ -1,7 +1,7 @@ { "schemas": { "input compact": "e7f4c82c15a6ce96", - "output compact": "d368534f377ef13b" + "output compact": "ab60debdc7b65c85" }, "patterns": { "input": ["^[0-9a-z]+(?:-[0-9a-z]+)*$", "^[^\\x00]*$"] diff --git a/scripts/verify/architecture-guards.mjs b/scripts/verify/architecture-guards.mjs index 1d486592a3..dcb2e2df7b 100644 --- a/scripts/verify/architecture-guards.mjs +++ b/scripts/verify/architecture-guards.mjs @@ -11,6 +11,12 @@ import { localCompletenessEnumCount } from "./completeness-enum-guard.mjs"; import { countKeyedFirstMatches } from "./keyed-first-match.mjs"; import { budgetArithmeticCount } from "./budget-arithmetic-guard.mjs"; import { localLimitErrorClassCount } from "./limit-class-guard.mjs"; +import { + isComparisonOrCountFile, + optionalFactDefaultCount, +} from "./optional-fact-default-guard.mjs"; +import { unmarkedMatchCount } from "./reason-marker.mjs"; +import { blankComments } from "./source-tokens.mjs"; import { cliTextGuardSelects, cliTextOutsideCliCount, @@ -46,19 +52,16 @@ const listFiles = async (dir) => { return output; }; -const stripComments = (content) => - content - .split("\n") - .filter((line) => !line.trimStart().startsWith("//")) - .join("\n") - .replace(/\/\*[\s\S]*?\*\//gu, ""); - const sources = await listFiles(join(root, "src")); const files = await Promise.all( - sources.map(async (path) => ({ - path: relative(root, path).split(sep).join("/"), - content: stripComments(await readFile(path, "utf8")), - })), + sources.map(async (path) => { + const source = await readFile(path, "utf8"); + return { + path: relative(root, path).split(sep).join("/"), + content: blankComments(source), + source, + }; + }), ); const failures = []; const check = (label, selected, pattern, allow = []) => { @@ -328,7 +331,7 @@ const checkCounted = (label, key, selected, pattern, owners) => { if (owners.includes(file.path)) continue; const count = typeof pattern === "function" - ? pattern(file.content, file.path) + ? pattern(file.content, file) : (file.content.match(pattern)?.length ?? 0); if (count > 0) counts.set(file.path, count); } @@ -355,6 +358,18 @@ const checkCounted = (label, key, selected, pattern, owners) => { ); }; +// Comparison, coverage and count code that reads an optional parsed fact with +// `?? 0`, `?? []` or `?? false` turns "not reported" into an observed zero, +// empty list or no. Keep the fact unknown (null with a limitation) instead. +checkCounted( + "optional fact defaulted to 0, [] or false in comparison or count code (keep it unknown)", + "optional-fact-default", + files.filter(({ path }) => isComparisonOrCountFile(path)), + // Exemption markers are comments, so this guard reads the unstripped source. + (_content, { source }) => optionalFactDefaultCount(source), + [], +); + // A provider failure's captured output comes from one owner, // capturedProviderOutput in src/process; local copies drift on byte counts // (retained or written) and on how output loss marks truncation. @@ -400,7 +415,7 @@ check( // src/domain/coverage.ts. A local enum that contains "complete" either copies // it or drops `unknown`, which forces an unknown producer to pick a side. checkCounted( - "local completeness enum (use coverageStatusSchema from src/domain/coverage)", + "local completeness enum (use coverageStatusSchema from src/domain/coverage, or mark a detail level, lifecycle state or domain vocabulary with `// detail-level:`, `// lifecycle-state:` or `// domain-vocabulary:` and its reason)", "local-completeness-enum", files, localCompletenessEnumCount, @@ -435,9 +450,11 @@ checkCounted( // src/domain/budget, which refuses malformed or oversized charges without // changing the remainder. Hand-written `remaining -=` / `retained +=` // arithmetic repeats that admission and drifts (charge-then-check, no -// safe-integer check). +// safe-integer check). A cursor, tally or retained length that is compared +// with a limit without being charged against it carries +// `// not-an-allowance: ` on its field declaration (#11408). checkCounted( - "hand-written budget arithmetic (use Budget from src/domain/budget)", + "hand-written budget arithmetic (use Budget from src/domain/budget, or mark a cursor or tally field with `// not-an-allowance: `)", "budget-arithmetic", files, budgetArithmeticCount, @@ -446,12 +463,21 @@ checkCounted( // A slice to a named maximum drops items; boundedList in src/domain/boundedList // keeps the count of what it dropped beside the retained items, so a consumer -// can say that more exist and how many. +// can say that more exist and how many. Two caps drop no evidence and carry a +// reason marker instead (#11411): `// generation-cap: ` limits what REA +// generates (suggested checks, guards) or the work spent finding it, and +// `// sample-cap: ` limits illustrative samples whose full totals the +// same result already reports. checkCounted( - "slice to a named maximum (use boundedList or BoundedListCollector from src/domain/boundedList so the omitted count travels with the items)", + "slice to a named maximum (use boundedList or BoundedListCollector from src/domain/boundedList so the omitted count travels with the items, or mark a generation or sample cap with its reason)", "constant-maximum-slice", files, - /\.slice\(\s*0\s*,\s*[A-Z][A-Z0-9_]*\s*\)/gu, + (_content, file) => + unmarkedMatchCount( + file.source, + /\.slice\(\s*0\s*,\s*[A-Z][A-Z0-9_]*\s*\)/gu, + ["generation-cap", "sample-cap"], + ), ["src/domain/boundedList.ts"], ); @@ -504,7 +530,7 @@ checkCounted( "inline error-to-message conversion (use errorMessage from src/kernel/errorMessage)", "inline-error-message", files, - (content, path) => + (content, { path }) => Math.max( 0, (content.match(inlineErrorMessage)?.length ?? 0) - @@ -887,7 +913,7 @@ const verifierScripts = await Promise.all( ) .map(async (path) => ({ path: `scripts/${path}`, - content: stripComments( + content: blankComments( await readFile(join(root, "scripts", path), "utf8"), ), })), diff --git a/scripts/verify/baselines/budget-arithmetic.json b/scripts/verify/baselines/budget-arithmetic.json deleted file mode 100644 index 85fd864a38..0000000000 --- a/scripts/verify/baselines/budget-arithmetic.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "src/kuna/KunaJsonStream.ts": 1, - "src/process/BoundedOutputExcerpt.ts": 1, - "src/process/ProviderProcess.ts": 1, - "src/resources/AsarHeader.ts": 1 -} diff --git a/scripts/verify/baselines/constant-maximum-slice.json b/scripts/verify/baselines/constant-maximum-slice.json index 505268ffaa..f20a4071ea 100644 --- a/scripts/verify/baselines/constant-maximum-slice.json +++ b/scripts/verify/baselines/constant-maximum-slice.json @@ -3,21 +3,5 @@ "src/apktool/ApktoolProvider.ts": 1, "src/application/environment/environmentReplay.ts": 1, "src/desktop/DesktopSessionObservations.ts": 1, - "src/domain/desktop/appTaskDraft.ts": 4, - "src/domain/desktop/appTaskDraftAdded.ts": 3, - "src/domain/desktop/appTaskDraftAlternatives.ts": 1, - "src/domain/desktop/appTaskDraftCounts.ts": 2, - "src/domain/desktop/appTaskDraftFileNotes.ts": 4, - "src/domain/desktop/appTaskDraftGuards.ts": 2, - "src/domain/desktop/appTaskDraftItems.ts": 1, - "src/domain/desktop/appTaskDraftJson.ts": 4, - "src/domain/desktop/appTaskDraftLineGuards.ts": 1, - "src/domain/desktop/appTaskDraftNamed.ts": 2, - "src/domain/desktop/appTaskDraftNested.ts": 2, - "src/domain/desktop/appTaskDraftNotes.ts": 1, - "src/domain/desktop/appTaskDraftText.ts": 1, - "src/domain/desktop/appTaskDraftValues.ts": 1, - "src/domain/desktop/memberPairing.ts": 1, - "src/domain/desktop/selectorCandidates.ts": 1, - "src/domain/releaseExposure.ts": 2 + "src/domain/desktop/appTaskDraft.ts": 2 } diff --git a/scripts/verify/baselines/local-completeness-enum.json b/scripts/verify/baselines/local-completeness-enum.json index 744d8f9dfd..fe5d8e9f1f 100644 --- a/scripts/verify/baselines/local-completeness-enum.json +++ b/scripts/verify/baselines/local-completeness-enum.json @@ -1,19 +1,10 @@ { - "src/contracts/cutterToolContracts.ts": 1, - "src/contracts/rizinDebugToolContracts.ts": 1, - "src/cutter/CutterBridgeClient.ts": 2, "src/domain/analysisView/browserScenarioViewSchemas.ts": 1, "src/domain/analysisView/goBinaryView.ts": 1, - "src/domain/analysisView/webNetworkCaptureView.ts": 1, "src/domain/artifactFormatMetadata.ts": 2, - "src/domain/commandObservation.ts": 2, "src/domain/evidenceRecordSummary.ts": 1, - "src/domain/gpu/gpuCodeObjects.ts": 1, - "src/domain/javascript/electronActiveObservation.ts": 1, "src/domain/javascript/javascriptExportShapeComparisonSchemas.ts": 1, "src/domain/javascript/javascriptRouteInventory.ts": 1, "src/domain/javascript/javascriptStaticCoverage.ts": 1, - "src/domain/sqlite/sqliteDatabase.ts": 1, - "src/domain/wasm/wasmArtifact.ts": 1, "src/domain/windows/ntfsMftAttributes.ts": 1 } diff --git a/scripts/verify/budget-arithmetic-guard.d.mts b/scripts/verify/budget-arithmetic-guard.d.mts index 1a603facc2..aeeaa90850 100644 --- a/scripts/verify/budget-arithmetic-guard.d.mts +++ b/scripts/verify/budget-arithmetic-guard.d.mts @@ -1 +1,4 @@ -export function budgetArithmeticCount(content: string): number; +export function budgetArithmeticCount( + content: string, + file?: { readonly source: string }, +): number; diff --git a/scripts/verify/budget-arithmetic-guard.mjs b/scripts/verify/budget-arithmetic-guard.mjs index 65ef0c0ce1..f8f25d7aaf 100644 --- a/scripts/verify/budget-arithmetic-guard.mjs +++ b/scripts/verify/budget-arithmetic-guard.mjs @@ -12,7 +12,21 @@ // `…allowance…`, `…budget…`, `…capacity…`): a hand-written allowance. // // Write cursors (`#arenaWriteOffset`) and observation tallies that are never -// compared with a limit are not allowances and are not counted. +// compared with a limit are not allowances and are not counted. A cursor or +// tally that is compared with a limit without being one (a scan position, an +// observed total, a ring buffer's retained length) is exempt when its field +// declaration carries `// not-an-allowance: ` (#11408). The exemption +// belongs to that field of that top-level class only. + +import { markedLineNumbers } from "./reason-marker.mjs"; + +const NOT_AN_ALLOWANCE = ["not-an-allowance"]; + +// A class member declaration at member depth (two-space indent, as formatted): +// `#field = 0;`, `private readonly field: number = 0;`. Deeper lines, such as +// object literal properties, are not class fields. +const memberDeclaration = + /^ {2}(?:(?:private|protected|public|readonly|static|declare)\s+)*(#?\w+)\s*[?!]?\s*[:=]/u; const namedAllowance = /this\.#?\w*(?:[Rr]emaining|[Rr]etained|[Uu]sed)\w*\s*[-+]=/gu; @@ -54,29 +68,72 @@ const topLevelClass = /^(?:export\s+)?(?:default\s+)?(?:abstract\s+)?class\s+(\w+)[^\n]*\{\n([\s\S]*?)^\}/gmu; /** Distinct limit-compared fields adjusted by hand within one scope. */ -const limitedFields = (scope) => { +const limitedFields = (scope, exempt) => { const limited = new Set(); for (const match of scope.matchAll(adjusted)) { const name = match[1] ?? match[2]; - if (isNamedAllowance(match[0]) || limited.has(name)) continue; + if (isNamedAllowance(match[0]) || limited.has(name) || exempt.has(name)) + continue; if (comparedWithLimit(scope, name)) limited.add(name); } return limited.size; }; -/** @param {string} content comment-stripped source */ -export const budgetArithmeticCount = (content) => { - let count = content.match(namedAllowance)?.length ?? 0; +const newlines = (text) => text.split("\n").length - 1; + +/** Per top-level class, the fields whose declaration carries a marker. */ +const exemptClassFields = (raw) => { + const marked = markedLineNumbers(raw, NOT_AN_ALLOWANCE); + const lines = raw.split("\n"); + const exempt = new Map(); + for (const match of raw.matchAll(topLevelClass)) { + const first = newlines(raw.slice(0, match.index)); + const last = first + newlines(match[0]); + const fields = new Set(); + for (let line = first + 1; line < last; line += 1) { + const name = marked.has(line) + ? memberDeclaration.exec(lines[line])?.[1] + : undefined; + if (name !== undefined) fields.add(name); + } + if (fields.size > 0) exempt.set(match[1], fields); + } + return exempt; +}; + +const fieldOf = (text) => /this\.(#?\w+)/u.exec(text)?.[1]; + +/** Named-allowance arithmetic in one scope, skipping its exempt fields. */ +const namedAllowances = (scope, exempt) => + [...scope.matchAll(namedAllowance)].filter( + (match) => !exempt.has(fieldOf(match[0])), + ).length; + +const NONE = new Set(); + +/** + * @param {string} content source with comments blanked (`blankComments`) + * @param {{ readonly source: string } | undefined} file the raw source, read + * for not-an-allowance markers + */ +export const budgetArithmeticCount = (content, file) => { + const exempt = + file === undefined ? new Map() : exemptClassFields(file.source); + let count = 0; let outside = content; for (const [whole, name, body] of content.matchAll(topLevelClass)) { outside = outside.replace(whole, ""); + const fields = exempt.get(name) ?? NONE; + count += namedAllowances(body, fields); if (name.endsWith("Budget")) { for (const match of body.matchAll(adjusted)) { - // Already counted as a named allowance. - if (isNamedAllowance(match[0])) continue; - if (comparedIn(body, match[1] ?? match[2])) count += 1; + const field = match[1] ?? match[2]; + // Named allowances are counted above. + if (isNamedAllowance(match[0]) || fields.has(field)) continue; + if (comparedIn(body, field)) count += 1; } - } else count += limitedFields(body); + } else count += limitedFields(body, fields); } - return count + limitedFields(outside); + // Markers exempt class fields only. + return count + namedAllowances(outside, NONE) + limitedFields(outside, NONE); }; diff --git a/scripts/verify/completeness-enum-guard.d.mts b/scripts/verify/completeness-enum-guard.d.mts index 825912cfb9..c56ffd07be 100644 --- a/scripts/verify/completeness-enum-guard.d.mts +++ b/scripts/verify/completeness-enum-guard.d.mts @@ -1 +1,5 @@ -export function localCompletenessEnumCount(content: string): number; +export const COMPLETENESS_ENUM_MARKERS: readonly string[]; +export function localCompletenessEnumCount( + content: string, + file?: { readonly source: string }, +): number; diff --git a/scripts/verify/completeness-enum-guard.mjs b/scripts/verify/completeness-enum-guard.mjs index 1b8eaf2083..daf62df82f 100644 --- a/scripts/verify/completeness-enum-guard.mjs +++ b/scripts/verify/completeness-enum-guard.mjs @@ -4,13 +4,39 @@ // counted. Whitespace, including line breaks, may separate `z`, `.enum(` and // `[`, so a formatter's chained layout (`z\n .enum([...])`) is counted like // the inline one. +// +// An enum whose "complete" is not coverage carries a reason marker on the line +// of its `z` (or in the comment run directly above it) (#11409): +// `// detail-level: ` for a caller-chosen amount of output, +// `// lifecycle-state: ` for how far a command, session or capture +// got, and `// domain-vocabulary: ` for a format's or tool's own +// states that are not an examined universe. + +import { unmarkedMatchCount } from "./reason-marker.mjs"; + const zodEnumLiterals = /\bz\s*\.\s*enum\s*\(\s*\[([^\]]*)\]/gu; -/** @param {string} content */ -export const localCompletenessEnumCount = (content) => { - let count = 0; - for (const [, literals] of content.matchAll(zodEnumLiterals)) - if (literals.includes('"complete"') && !literals.includes('"summary"')) - count += 1; - return count; -}; +export const COMPLETENESS_ENUM_MARKERS = [ + "detail-level", + "lifecycle-state", + "domain-vocabulary", +]; + +const isCompletenessVocabulary = ([, literals]) => + literals.includes('"complete"') && !literals.includes('"summary"'); + +/** + * @param {string} content source with comments blanked (`blankComments`) + * @param {{ readonly source: string } | undefined} file the raw source, read + * for reason markers + */ +export const localCompletenessEnumCount = (content, file) => + file === undefined + ? [...content.matchAll(zodEnumLiterals)].filter(isCompletenessVocabulary) + .length + : unmarkedMatchCount( + file.source, + zodEnumLiterals, + COMPLETENESS_ENUM_MARKERS, + isCompletenessVocabulary, + ); diff --git a/scripts/verify/optional-fact-default-guard.d.mts b/scripts/verify/optional-fact-default-guard.d.mts new file mode 100644 index 0000000000..c7dfbaad11 --- /dev/null +++ b/scripts/verify/optional-fact-default-guard.d.mts @@ -0,0 +1,2 @@ +export function isComparisonOrCountFile(path: string): boolean; +export function optionalFactDefaultCount(content: string): number; diff --git a/scripts/verify/optional-fact-default-guard.mjs b/scripts/verify/optional-fact-default-guard.mjs new file mode 100644 index 0000000000..33fc5b6963 --- /dev/null +++ b/scripts/verify/optional-fact-default-guard.mjs @@ -0,0 +1,154 @@ +// Counts optional parsed facts defaulted to an observed value in comparison, +// coverage and count code: a property read (`report.count`, +// `side?.omitted`) followed by `?? 0`, `?? []` or `?? false`, including the +// last link of a chain (`left.count ?? right.count ?? 0`). Map accumulators +// (`map.get(k) ?? []`) and indexed reads (`bytes[i] ?? 0`) end in a call or +// element read, not a property read, so they are not counted. +// +// A default that is legitimate (a request default such as a pagination +// offset, a library field that is optional by contract, or absence that is +// modelled elsewhere) carries a comment on the line before its expression, +// on that expression's first line, or on the default's line: +// `// optional-fact-default: `. +// +// The source is tokenized by source-tokens.mjs, so only executable +// expressions are counted and exemption markers are read only from comments. + +import { isReasonMarker } from "./reason-marker.mjs"; +import { tokenize } from "./source-tokens.mjs"; + +const comparisonOrCountFile = + /\/[^/]*(?:compar|diff|delta|reconcil|coverage|summar|count|match)[^/]*\.ts$/iu; + +/** @param {string} path */ +export const isComparisonOrCountFile = (path) => + comparisonOrCountFile.test(path); + +const kind = (token) => (token?.kind === "punct" ? token.text : undefined); + +const isPropertyRead = (tokens, end) => + tokens[end]?.kind === "id" && + (kind(tokens[end - 1]) === "." || kind(tokens[end - 1]) === "?."); + +const closers = { ")": "(", "]": "[", "}": "{" }; + +/** Index of the bracket that opens the group closed at `close`. */ +const matchingOpen = (tokens, close) => { + let depth = 0; + for (let at = close; at >= 0; at -= 1) { + const text = kind(tokens[at]); + if (text !== undefined && text in closers) depth += 1; + else if (text === "(" || text === "[" || text === "{") { + depth -= 1; + if (depth === 0) return at; + } + } + return undefined; +}; + +/** Ends a callee or object, so a following `(` or `[` is a call or element read. */ +const endsOperand = (token) => + (token?.kind === "id" && token.keyword !== true) || + kind(token) === ")" || + kind(token) === "]"; + +/** First token of the member, call and element chain ending at `end`. */ +const operandStart = (tokens, end) => { + let at = end; + for (;;) { + const text = kind(tokens[at]); + if (text === ")" || text === "]") { + const open = matchingOpen(tokens, at); + if (open === undefined) return at; + at = open; + } + const previous = tokens[at - 1]; + if ((kind(previous) === "." || kind(previous) === "?.") && at >= 2) at -= 2; + else if ( + (kind(tokens[at]) === "(" || kind(tokens[at]) === "[") && + endsOperand(previous) + ) + at -= 1; + else return at; + } +}; + +/** First token of the `??` chain whose last operand ends at `end`. */ +const chainStart = (tokens, end) => { + let at = operandStart(tokens, end); + while (kind(tokens[at - 1]) === "??" && at >= 2) + at = operandStart(tokens, at - 2); + return at; +}; + +const isObservedDefault = (tokens, at) => { + const token = tokens[at]; + if (token?.kind === "number" && token.text === "0") return at; + if (token?.kind === "id" && token.text === "false") return at; + if (kind(token) === "[" && kind(tokens[at + 1]) === "]") return at + 1; + return undefined; +}; + +// Tokens that end the `??` expression, so the literal is the whole right +// operand. Any other operator binds tighter (`?? 0 | mask`, `?? 0 + 1`) and +// makes the default a computed value. +const endsDefault = new Set([")", "]", "}", ",", ";", ":", "?", "??"]); + +const isWholeDefault = (tokens, last, lineOf) => { + const next = tokens[last + 1]; + if ( + next === undefined || + next.kind === "substitution-end" || + endsDefault.has(kind(next)) + ) + return true; + // A statement that ends without a semicolon continues on a later line. + return ( + next.kind !== "punct" && + !["as", "satisfies", "in", "instanceof"].includes(next.text) && + lineOf(next.start) > lineOf(tokens[last].start) + ); +}; + +/** @param {string} source unstripped source, comments included */ +export const optionalFactDefaultCount = (source) => { + const { tokens, comments } = tokenize(source); + const lineStarts = [0]; + for ( + let at = source.indexOf("\n"); + at !== -1; + at = source.indexOf("\n", at + 1) + ) + lineStarts.push(at + 1); + const lineOf = (offset) => { + let low = 0; + let high = lineStarts.length - 1; + while (low < high) { + const middle = (low + high + 1) >> 1; + if (lineStarts[middle] <= offset) low = middle; + else high = middle - 1; + } + return low; + }; + const exempt = new Set( + comments + // A marker without a reason does not exempt a default. + .filter(({ text }) => isReasonMarker(text, "optional-fact-default")) + .map(({ end }) => lineOf(end - 1)), + ); + let count = 0; + tokens.forEach((token, at) => { + if (kind(token) !== "??" || !isPropertyRead(tokens, at - 1)) return; + const last = isObservedDefault(tokens, at + 1); + if (last === undefined) return; + if (!isWholeDefault(tokens, last, lineOf)) return; + // A marker belongs to the expression it opens or ends: the line before + // the chain, its first line, or the default's line. A marker on a line in + // between explains a nested expression, not this default. + const start = lineOf(tokens[chainStart(tokens, at - 1)].start); + const end = lineOf(tokens[last].start); + if ([start - 1, start, end].some((line) => exempt.has(line))) return; + count += 1; + }); + return count; +}; diff --git a/scripts/verify/reason-marker.d.mts b/scripts/verify/reason-marker.d.mts new file mode 100644 index 0000000000..87a12d0712 --- /dev/null +++ b/scripts/verify/reason-marker.d.mts @@ -0,0 +1,11 @@ +export function unmarkedMatchCount( + raw: string, + pattern: RegExp, + names: readonly string[], + counts?: (match: RegExpMatchArray) => boolean, +): number; +export function markedLineNumbers( + raw: string, + names: readonly string[], +): Set; +export function isReasonMarker(comment: string, name: string): boolean; diff --git a/scripts/verify/reason-marker.mjs b/scripts/verify/reason-marker.mjs new file mode 100644 index 0000000000..b5a3510a1b --- /dev/null +++ b/scripts/verify/reason-marker.mjs @@ -0,0 +1,91 @@ +// Counts a guard's matches in source, skipping the ones a reason marker +// exempts. A marker is a line comment `// : ` with a non-empty +// reason, either trailing the matched line or in the run of whole-line +// comments directly above it. A marker without a reason exempts nothing, and +// marker text inside a block comment, a string, a template or a regular +// expression is not a marker. +// +// Comments come from source-tokens.mjs, which tells them apart from strings, +// templates (including `${…}` substitutions) and regular expressions. Matches +// are taken from the code with every comment blanked (newlines kept). + +import { blankComments, tokenize } from "./source-tokens.mjs"; + +const newlines = (text) => text.split("\n").length - 1; + +/** The code with comments blanked, and each line's `//` comment. */ +const scan = (raw) => { + const { comments } = tokenize(raw); + const lineComments = new Map(); + let last = 0; + let line = 0; + for (const { text, end } of comments) { + const start = end - text.length; + line += newlines(raw.slice(last, start)); + if (text.startsWith("//")) lineComments.set(line, text); + line += newlines(text); + last = end; + } + return { code: blankComments(raw, comments), lineComments }; +}; + +/** + * Whether a comment is a `// : ` marker with a non-empty reason. + * @param {string} comment + * @param {string} name + */ +export const isReasonMarker = (comment, name) => + new RegExp(`^//\\s*${name}:\\s*\\S`, "u").test(comment); + +const markerIn = (comment, names) => + comment !== undefined && names.some((name) => isReasonMarker(comment, name)); + +const exempted = ({ codeLines, lineComments }, index, names) => { + if (markerIn(lineComments.get(index), names)) return true; + for (let above = index - 1; above >= 0; above -= 1) { + const comment = lineComments.get(above); + if (comment === undefined || codeLines[above].trim() !== "") return false; + if (markerIn(comment, names)) return true; + } + return false; +}; + +/** + * The zero-based numbers of the code lines a marker exempts. + * @param {string} raw + * @param {readonly string[]} names + * @returns {Set} + */ +export const markedLineNumbers = (raw, names) => { + const { code, lineComments } = scan(raw); + const source = { codeLines: code.split("\n"), lineComments }; + const marked = new Set(); + source.codeLines.forEach((text, index) => { + if (text.trim() !== "" && exempted(source, index, names)) marked.add(index); + }); + return marked; +}; + +/** + * @param {string} raw + * @param {RegExp} pattern a global pattern + * @param {readonly string[]} names + * @param {(match: RegExpMatchArray) => boolean} [counts] which matches the + * guard counts at all; the rest are neither counted nor exempted + */ +export const unmarkedMatchCount = ( + raw, + pattern, + names, + counts = () => true, +) => { + const { code, lineComments } = scan(raw); + const source = { codeLines: code.split("\n"), lineComments }; + let count = 0; + for (const match of code.matchAll(pattern)) { + if (!counts(match)) continue; + const line = newlines(code.slice(0, match.index)); + if (!exempted(source, line, names)) count += 1; + } + return count; +}; diff --git a/scripts/verify/source-tokens.d.mts b/scripts/verify/source-tokens.d.mts new file mode 100644 index 0000000000..3de9b8268f --- /dev/null +++ b/scripts/verify/source-tokens.d.mts @@ -0,0 +1,25 @@ +export interface SourceToken { + readonly kind: string; + readonly text: string; + readonly start: number; + /** An expression keyword such as `return`, not a property name. */ + keyword?: true; + /** The `}` that closes a statement block rather than an object literal. */ + closesBlock?: true; + /** The `)` that closes a control head such as `if (…)`. */ + controlHead?: true; + /** Template text that opens a `${` substitution. */ + readonly opensSubstitution?: true; +} +export interface SourceComment { + readonly text: string; + readonly end: number; +} +export function blankComments( + source: string, + comments?: readonly SourceComment[], +): string; +export function tokenize(source: string): { + tokens: SourceToken[]; + comments: SourceComment[]; +}; diff --git a/scripts/verify/source-tokens.mjs b/scripts/verify/source-tokens.mjs new file mode 100644 index 0000000000..a8a7d509f5 --- /dev/null +++ b/scripts/verify/source-tokens.mjs @@ -0,0 +1,246 @@ +// Splits TypeScript source into code tokens and comments without loading a +// compiler (CI runs the architecture guards before installing dependencies). +// Strings, template text, regular expressions and comments are separate +// tokens, and template substitutions are tracked through nested `${…}` with a +// brace stack, so guards count only executable code and read markers only +// from comments. + +const identifier = /[\p{ID_Start}$_#][\p{ID_Continue}$‌‍]*/uy; +const number = + /(?:0[xXbBoO][\da-fA-F_]+|(?:\d[\d_]*(?:\.[\d_]*)?|\.\d[\d_]*)(?:[eE][+-]?\d+)?)n?/uy; +const punctuator = + /\?\?=|\?\?|\?\.(?!\d)|\.\.\.|=>|[!=]==?|[<>]=?|&&=?|\|\|=?|\*\*=?|[-+*%&|^/]=|\+\+|--|[{}()[\];,.<>+\-*/%&|^!~?:=@]/uy; + +// After these keywords an expression starts, so `/` opens a regular expression. +// A property name such as `row.return` is not a keyword. +const expressionKeywords = new Set([ + "await", + "case", + "delete", + "do", + "else", + "in", + "instanceof", + "new", + "of", + "return", + "throw", + "typeof", + "void", + "yield", +]); + +// A parenthesised head after these keywords ends where a statement starts. +const controlKeywords = new Set(["if", "while", "for", "with"]); + +// After a closing bracket, `++`, `--`, an operand or a complete template an +// expression has ended, so `/` divides. An expression starts after any other +// punctuator, an expression keyword, the `)` that closes a control head such +// as `if (…)`, and template text that opens a `${` substitution. +const regexAllowedAfter = (token) => + token === undefined || + token.opensSubstitution === true || + token.keyword === true || + token.closesBlock === true || + (token.kind === "punct" && token.controlHead === true) || + (token.kind === "punct" && !/^(?:[)\]}]|\+\+|--)$/u.test(token.text)); + +// A `{` opens a statement block at the start of a statement, after the `)` +// of a control or function head, an arrow, another brace or `;`, a block +// keyword, or a declaration name or return type (`class A {`, +// `function f(): T {`). Anywhere else it opens an object literal or type, +// whose `}` ends an operand, so a `/` after it divides. +const opensBlock = (previous) => + previous === undefined || + (previous.kind === "punct" && /^(?:[);{}]|=>)$/u.test(previous.text)) || + (previous.kind === "id" && + (previous.keyword !== true || + previous.text === "do" || + previous.text === "else")); + +/** + * End of a template's text from `at` (after a backtick or a substitution's + * `}`), and whether that text opens a `${` substitution. + */ +const templateEnd = (source, at, braces) => { + while (at < source.length) { + if (source[at] === "\\") at += 2; + else if (source[at] === "`") return { end: at + 1, opens: false }; + else if (source[at] === "$" && source[at + 1] === "{") { + braces.push("template"); + return { end: at + 2, opens: true }; + } else at += 1; + } + return { end: at, opens: false }; +}; + +/** End of a quoted string opened at `at`. */ +const quotedEnd = (source, at) => { + const quote = source[at]; + at += 1; + while (at < source.length && source[at] !== quote && source[at] !== "\n") + at += source[at] === "\\" ? 2 : 1; + return at + 1; +}; + +/** End of a regular expression literal (with flags) opened at `at`. */ +const regexEnd = (source, at) => { + at += 1; + let inClass = false; + while (at < source.length && source[at] !== "\n") { + const char = source[at]; + if (char === "\\") at += 1; + else if (char === "[") inClass = true; + else if (char === "]") inClass = false; + else if (char === "/" && !inClass) break; + at += 1; + } + identifier.lastIndex = at + 1; + return identifier.test(source) ? identifier.lastIndex : at + 1; +}; + +/** End of a comment opened at `at`, or undefined when none starts there. */ +const commentEnd = (source, at) => { + if (source[at] !== "/") return undefined; + if (source[at + 1] === "/") { + const end = source.indexOf("\n", at); + return end === -1 ? source.length : end; + } + if (source[at + 1] !== "*") return undefined; + const end = source.indexOf("*/", at + 2); + return end === -1 ? source.length : end + 2; +}; + +/** Whether a name after this token is a property name, not a keyword. */ +const isMemberAccess = (token) => + token?.kind === "punct" && (token.text === "." || token.text === "?."); + +const whitespace = /\s+/uy; +const isWhitespace = (char) => + char === " " || char === "\n" || char === "\t" || /\s/u.test(char); + +const wordPatterns = [ + ["id", identifier], + ["number", number], + ["punct", punctuator], +]; + +/** An identifier, number or punctuator token at `at`. */ +const wordToken = (source, at) => { + for (const [tokenKind, pattern] of wordPatterns) { + pattern.lastIndex = at; + if (pattern.test(source)) + return { + kind: tokenKind, + text: source.slice(at, pattern.lastIndex), + start: at, + }; + } + return undefined; +}; + +/** + * Scans source into code tokens and comments. The scanner reads only the last + * two tokens, so a caller that needs only comments keeps no more than those. + */ +const scan = (source, keepTokens) => { + /** @type {import("./source-tokens.d.mts").SourceToken[]} */ + const tokens = []; + // One entry per open `(`: whether it opens a control head. + const parens = []; + /** @type {{ text: string, end: number }[]} */ + const comments = []; + const braces = []; + let at = 0; + while (at < source.length) { + const char = source[at]; + const start = at; + const comment = commentEnd(source, at); + if (isWhitespace(char)) { + whitespace.lastIndex = at; + whitespace.test(source); + at = whitespace.lastIndex; + } else if (comment !== undefined) { + at = comment; + comments.push({ text: source.slice(start, at), end: at }); + } else if (char === "'" || char === '"') { + at = quotedEnd(source, at); + tokens.push({ kind: "string", text: "", start }); + } else if (char === "`" || (char === "}" && braces.at(-1) === "template")) { + if (char === "}") braces.pop(); + const text = templateEnd(source, at + 1, braces); + at = text.end; + // Template text after a substitution's `}` closes that substitution. + tokens.push({ + kind: char === "}" ? "substitution-end" : "string", + text: "", + start, + ...(text.opens ? { opensSubstitution: true } : {}), + }); + } else if (char === "/" && regexAllowedAfter(tokens.at(-1))) { + at = regexEnd(source, at); + tokens.push({ kind: "regex", text: "", start }); + } else { + const token = wordToken(source, at); + if (token === undefined) { + at += 1; + continue; + } + at = start + token.text.length; + if (token.text === "(") { + const previous = tokens.at(-1); + // `x.if(…)` and `x?.for(…)` are member calls, not control heads. + parens.push( + previous?.kind === "id" && + controlKeywords.has(previous.text) && + !isMemberAccess(tokens.at(-2)), + ); + } else if (token.text === ")" && parens.pop() === true) + token.controlHead = true; + else if ( + token.kind === "id" && + expressionKeywords.has(token.text) && + !isMemberAccess(tokens.at(-1)) + ) + token.keyword = true; + if (token.text === "{") + braces.push(opensBlock(tokens.at(-1)) ? "block" : "object"); + // After a statement block a new statement starts. + else if (token.text === "}" && braces.pop() === "block") + token.closesBlock = true; + tokens.push(token); + if (!keepTokens && tokens.length > 64) tokens.splice(0, 62); + } + } + return { tokens, comments }; +}; + +/** + * Splits TypeScript source into code tokens and comments. Template literals + * are tracked through nested `${…}` substitutions with a brace stack. + */ +export const tokenize = (source) => scan(source, true); + +/** + * The source with every comment replaced by spaces, keeping newlines, so + * offsets and line numbers still match the source. Strings, templates and + * regular expressions are kept, so `/*` or `//` inside them is not a comment. + * @param {string} source + * @param {readonly { text: string, end: number }[]} [comments] the source's + * comments, when the caller has already tokenized it + */ +export const blankComments = ( + source, + comments = scan(source, false).comments, +) => { + const parts = []; + let last = 0; + for (const { text, end } of comments) { + parts.push(source.slice(last, end - text.length)); + // One space per UTF-16 unit, so offsets after the comment stay the same. + parts.push(text.replace(/[^\n]+/gu, (run) => " ".repeat(run.length))); + last = end; + } + parts.push(source.slice(last)); + return parts.join(""); +}; diff --git a/src/application/artifacts/ArtifactComparisonEvidence.ts b/src/application/artifacts/ArtifactComparisonEvidence.ts index 252cdbe65b..583fc7be81 100644 --- a/src/application/artifacts/ArtifactComparisonEvidence.ts +++ b/src/application/artifacts/ArtifactComparisonEvidence.ts @@ -235,6 +235,7 @@ const artifactUnknownInput = ( const { status } = comparison; if (status === "unchanged") return undefined; const sourceIds = [...new Set([left.evidence_id, right.evidence_id])]; + // optional-fact-default: legacy absence names no side; content contradictions apply. const contradictingIds = comparison.integrity_mismatch_evidence_ids ?? []; const contentContradictions = status === "changed" && left.evidence_id !== right.evidence_id diff --git a/src/application/desktop/DesktopBuildSolves.test.ts b/src/application/desktop/DesktopBuildSolves.test.ts index fa54354ec7..dff748bcf2 100644 --- a/src/application/desktop/DesktopBuildSolves.test.ts +++ b/src/application/desktop/DesktopBuildSolves.test.ts @@ -114,6 +114,36 @@ describe("measureBuildTask's record of a bundle", () => { expect(calls).toHaveLength(3); }); + it("records an unknown total cost and still measures the bundle's next task", async () => { + const bundle = await bundleWith("add-eggs", "add-bread"); + const signal = new AbortController().signal; + const unpriced: Solver = async () => ({ ...passed, usd: null }); + const first = await measureBuildTask( + request(bundle, "add-eggs"), + unpriced, + signal, + ); + expect(first).toMatchObject({ + ok: true, + value: { usd: null, stopped: "cost_unknown" }, + }); + const recorded = JSON.parse( + await readFile(join(bundle, "difficulty.json"), "utf8"), + ) as { tasks: Record }; + expect(recorded.tasks["add-eggs"]?.usd).toBeNull(); + + // The saved record with an unknown cost is read back, not refused. + const second = await measureBuildTask( + request(bundle, "add-bread"), + counting().solver, + signal, + ); + expect(second.ok).toBe(true); + const readme = await readFile(join(bundle, "README.md"), "utf8"); + expect(readme).toContain("cost unknown."); + expect(readme).toContain("$1.50 in all."); + }); + it("keeps both records when two tasks of one bundle are measured at once", async () => { const bundle = await bundleWith("add-eggs", "add-bread"); const { solver } = counting(); diff --git a/src/application/desktop/DesktopBuildSolves.ts b/src/application/desktop/DesktopBuildSolves.ts index affbc55ebe..60f92864ab 100644 --- a/src/application/desktop/DesktopBuildSolves.ts +++ b/src/application/desktop/DesktopBuildSolves.ts @@ -122,7 +122,7 @@ const recordsSchema = z.looseObject({ passes: z.int(), k: z.int(), band: z.enum(["in_band", "too_easy", "too_hard", "undecided"]), - usd: z.number(), + usd: z.number().nullable(), }), ), }); diff --git a/src/application/environment/environmentCompare.ts b/src/application/environment/environmentCompare.ts index 67a6e1460c..d85c22453d 100644 --- a/src/application/environment/environmentCompare.ts +++ b/src/application/environment/environmentCompare.ts @@ -309,6 +309,7 @@ const stepOf = ( differences_total: outcome.differences.length, differences_omitted: omitted, differences_truncated: omitted > 0, + // optional-fact-default: with no matched call (tool null) no query was mapped. ignored_query: [...(call?.ignoredQuery ?? [])], }; }; diff --git a/src/application/environment/environmentCompareDiff.ts b/src/application/environment/environmentCompareDiff.ts index 9e596ef5fa..eb093c21f2 100644 --- a/src/application/environment/environmentCompareDiff.ts +++ b/src/application/environment/environmentCompareDiff.ts @@ -564,6 +564,7 @@ export const compareAnswers = ( scope: entity.scope, at: entity.at ?? "", identity: entity.identity === true, + // optional-fact-default: a caller-selected comparison option, not an observation. rules: entity.rules ?? [], }); if (live.status !== env.status) diff --git a/src/application/native/EnhancedNativeInvestigation.test.ts b/src/application/native/EnhancedNativeInvestigation.test.ts index edaba15b59..64227ce306 100644 --- a/src/application/native/EnhancedNativeInvestigation.test.ts +++ b/src/application/native/EnhancedNativeInvestigation.test.ts @@ -1102,3 +1102,39 @@ it("keeps a complete UI graph trace untruncated when no bound is reached", async ]), ); }); + +describe("native UI action archive coverage", () => { + it("keeps archive coverage unknown when the decoder did not report it", async () => { + const trace = async ( + coverage: z.input["coverage"], + ) => { + const result = await new EnhancedTools( + testAnalysis({}, { ...graph, coverage }), + ).execute("trace_native_ui_action", { action: "missing-selector" }); + if (!result.ok) throw result.error; + return nativeInvestigationTraceSchema + .parse(result.value) + .coverage.filter(({ facet }) => facet === "interface_builder_archives"); + }; + // One document was found but no archive_decode facet was reported. + expect(await trace([])).toEqual([ + { + facet: "interface_builder_archives", + status: "unknown", + reason: "archive_decode_coverage_not_reported", + examined: 1, + omitted: null, + }, + ]); + const reported = { + facet: "archive_decode", + status: "partial" as const, + reason: "archive_decode_failed", + examined: 2, + omitted: 1, + }; + expect(await trace([reported])).toEqual([ + { ...reported, facet: "interface_builder_archives" }, + ]); + }); +}); diff --git a/src/application/native/NativeUiActionTrace.ts b/src/application/native/NativeUiActionTrace.ts index 1244c62021..2bf69f1a0a 100644 --- a/src/application/native/NativeUiActionTrace.ts +++ b/src/application/native/NativeUiActionTrace.ts @@ -117,25 +117,27 @@ export const traceNativeUiAction = async ( const archiveDecode = decoded.data.graph.coverage.find( (facet) => facet.facet === "archive_decode", ); - const documentsFound = decoded.data.documents.length > 0; - coverage.push({ - facet: "interface_builder_archives", - status: - archiveDecode?.status === "partial" || - archiveDecode?.status === "complete" || - archiveDecode?.status === "unsupported" - ? archiveDecode.status - : documentsFound - ? "complete" - : "unsupported", - reason: - archiveDecode?.reason ?? - (documentsFound - ? null - : "no_compiled_interface_builder_archives_found"), - examined: archiveDecode?.examined ?? decoded.data.documents.length, - omitted: archiveDecode?.omitted ?? 0, - }); + coverage.push( + archiveDecode !== undefined + ? { ...archiveDecode, facet: "interface_builder_archives" } + : decoded.data.documents.length > 0 + ? // Documents were found but their decode coverage was not + // reported: how many archives decoded is unknown, not complete. + { + facet: "interface_builder_archives", + status: "unknown", + reason: "archive_decode_coverage_not_reported", + examined: decoded.data.documents.length, + omitted: null, + } + : { + facet: "interface_builder_archives", + status: "unsupported", + reason: "no_compiled_interface_builder_archives_found", + examined: 0, + omitted: 0, + }, + ); sourceGraphTruncated = graph.truncated; const bounded = boundUiGraph(graph, input.max_nodes, input.max_edges); graph = bounded.graph; diff --git a/src/application/wasm/WasmInterfaceComparisonService.ts b/src/application/wasm/WasmInterfaceComparisonService.ts index 8017bf4d73..dbe07bc507 100644 --- a/src/application/wasm/WasmInterfaceComparisonService.ts +++ b/src/application/wasm/WasmInterfaceComparisonService.ts @@ -138,6 +138,7 @@ export const compareWasmInterfaces = async ( ["left", left], ["right", right], ] as const) { + // optional-fact-default: an absent interface fails knownInventory, so every key is unknown. for (const entry of inspection.result.interface?.entries ?? []) { if (++work % 256 === 0) { await setImmediate(); diff --git a/src/artifacts/apple/InterfaceBuilderAnalysis.ts b/src/artifacts/apple/InterfaceBuilderAnalysis.ts index 29d4698a64..e88ae85948 100644 --- a/src/artifacts/apple/InterfaceBuilderAnalysis.ts +++ b/src/artifacts/apple/InterfaceBuilderAnalysis.ts @@ -558,7 +558,10 @@ const finalizeHierarchyCoverage = ( // it, so that cause keeps the reason the graph already named. // Only a facet with no other cause reports the omission. reason: facet.reason ?? "connection_unresolved", - omitted: facet.omitted + omittedConnection, + omitted: + facet.omitted === null + ? null + : facet.omitted + omittedConnection, } : facet; }), diff --git a/src/contracts/cutterToolContracts.ts b/src/contracts/cutterToolContracts.ts index 6a5e35b67b..6959ce7826 100644 --- a/src/contracts/cutterToolContracts.ts +++ b/src/contracts/cutterToolContracts.ts @@ -25,6 +25,7 @@ export const cutterCommandInputSchema = z.strictObject({ export const cutterCommandResultSchema = z.strictObject({ command: z.string(), output: jsonValueSchema.nullable(), + // lifecycle-state: how far the bridge command ran, not coverage of its output. execution_state: z.enum(["not_started", "complete", "failed", "unknown"]), error: z.string().nullable(), message: z.string().nullable(), diff --git a/src/contracts/desktopBuildMeasureContract.ts b/src/contracts/desktopBuildMeasureContract.ts index e6c82666c6..ded14bf937 100644 --- a/src/contracts/desktopBuildMeasureContract.ts +++ b/src/contracts/desktopBuildMeasureContract.ts @@ -91,7 +91,13 @@ export const MEASURE_BUILD_TASK_CONTRACT = { k: z.int().nonnegative().describe("The solves that finished."), passes: z.int().nonnegative(), unfinished: z.int().nonnegative(), - usd: z.number().nonnegative(), + usd: z + .number() + .nonnegative() + .nullable() + .describe( + "Total cost of the solves; null when a solve reported no cost.", + ), budget_usd: z.number().positive(), turns: z.array(z.int().nonnegative().nullable()), failures_per_check: z diff --git a/src/contracts/rizinDebugToolContracts.ts b/src/contracts/rizinDebugToolContracts.ts index a212eb3578..d90dbf9ec8 100644 --- a/src/contracts/rizinDebugToolContracts.ts +++ b/src/contracts/rizinDebugToolContracts.ts @@ -13,6 +13,7 @@ const commandResult = z.strictObject({ output_scope: z.literal("command_and_interleaved_session_output"), output_truncated: z.boolean(), output_invalid_utf8: z.literal(true).optional(), + // lifecycle-state: whether the debugger command finished, not coverage of its output. completion_status: z.enum(["complete", "unknown"]), backend: z.string().nullable(), }); diff --git a/src/cutter/CutterBridgeClient.ts b/src/cutter/CutterBridgeClient.ts index 4b853d1499..55037a56e7 100644 --- a/src/cutter/CutterBridgeClient.ts +++ b/src/cutter/CutterBridgeClient.ts @@ -87,6 +87,7 @@ const responseSchema = z.object({ identity_status: z.literal("partial").optional(), error: z.string().optional(), message: z.string().optional(), + // lifecycle-state: the bridge's report of how far the command ran. execution_state: z .enum(["not_started", "running", "complete", "failed", "unknown"]) .optional(), @@ -95,6 +96,7 @@ const responseSchema = z.object({ .array( z.object({ request_id: z.string().uuid(), + // lifecycle-state: how far each completed command ran. execution_state: z.enum(["not_started", "complete", "failed"]), }), ) diff --git a/src/domain/analysisView/analysisView.test.ts b/src/domain/analysisView/analysisView.test.ts index 2f0e21103d..5ec964ce39 100644 --- a/src/domain/analysisView/analysisView.test.ts +++ b/src/domain/analysisView/analysisView.test.ts @@ -200,7 +200,7 @@ it("keeps value-flow counts unknown when value flow is unrecorded or unavailable if (!unrecorded.ok) throw unrecorded.error; expect(analysisViewResultSchema.parse(unrecorded.value)).toMatchObject({ summary: { - value_flow: { available: false, truncated: false }, + value_flow: { available: false, truncated: null }, counts: flowCounts, }, unknowns: expect.arrayContaining(["native_value_flow was not recorded"]), diff --git a/src/domain/analysisView/analysisViewResult.ts b/src/domain/analysisView/analysisViewResult.ts index 0e9b0d52f2..2cd07ebfa7 100644 --- a/src/domain/analysisView/analysisViewResult.ts +++ b/src/domain/analysisView/analysisViewResult.ts @@ -1066,8 +1066,9 @@ export const nativeFunctionSummarySchema = z.strictObject({ available: z.boolean(), truncated: z .boolean() + .nullable() .describe( - "True only when value-flow is available and the provider truncated it; false when value-flow is unavailable (see available).", + "Whether the provider truncated available value-flow; null when value-flow is unavailable (see available).", ), }), facet_availability: functionFacetAvailabilitySchema diff --git a/src/domain/analysisView/nativeFunctionView.ts b/src/domain/analysisView/nativeFunctionView.ts index 31e8fc64bb..2747ea2ab1 100644 --- a/src/domain/analysisView/nativeFunctionView.ts +++ b/src/domain/analysisView/nativeFunctionView.ts @@ -158,7 +158,9 @@ const summarizeDossier = (dossier: FunctionDossier) => { }, value_flow: { available: flow !== undefined, - truncated: flow?.truncated ?? false, + // Unavailable value-flow examined nothing: whether it would be + // truncated is unknown, not false. + truncated: flow === undefined ? null : flow.truncated, }, facet_availability: dossier.facet_availability ?? null, counts: { diff --git a/src/domain/analysisView/webNetworkCaptureView.ts b/src/domain/analysisView/webNetworkCaptureView.ts index 89e653a271..485501bcc0 100644 --- a/src/domain/analysisView/webNetworkCaptureView.ts +++ b/src/domain/analysisView/webNetworkCaptureView.ts @@ -41,6 +41,7 @@ import { sha256Hex } from "../../kernel/sha256Hex.js"; /** Offsets page the parent's retained record order, preserving producer ordinals. */ export const captureViewRequestSchema = z.strictObject({ kind: z.literal("capture"), + // detail-level: how much of the capture the caller asks to see, not what was examined. detail: z.enum(["preview", "complete"]).default("preview"), offset: z.int().nonnegative().default(0), limit: z.int().positive().default(64), diff --git a/src/domain/artifactComparison.ts b/src/domain/artifactComparison.ts index 8a3827a6d9..2607ed297d 100644 --- a/src/domain/artifactComparison.ts +++ b/src/domain/artifactComparison.ts @@ -101,6 +101,7 @@ export const artifactComparisonResultSchema = z result.summary.changed > 0 || result.summary.unknown > 0 || result.summary.contradiction > 0 || + // optional-fact-default: an unchanged result may not retain any mismatch IDs. (result.integrity_mismatch_evidence_ids?.length ?? 0) > 0) ) context.addIssue({ diff --git a/src/domain/commandObservation.ts b/src/domain/commandObservation.ts index 806a97d469..2c29d91ac5 100644 --- a/src/domain/commandObservation.ts +++ b/src/domain/commandObservation.ts @@ -16,6 +16,7 @@ export const commandObservationSchema = z.strictObject({ * only when the capture reached it. */ output_limit: analysisParameterLimitSchema.exactOptional(), + // lifecycle-state: whether the provider process finished the command. completion_status: z .enum(["complete", "rejected", "unknown"]) .describe( @@ -53,6 +54,7 @@ export const gdbCommandResultSchema = z.strictObject({ output_truncated: z.boolean(), output_limits: z.array(gdbOutputLimitSchema).min(1).exactOptional(), output_invalid_utf8: z.literal(true).exactOptional(), + // lifecycle-state: whether GDB finished the command. completion_status: z.enum(["complete", "unknown"]), }); diff --git a/src/domain/comparisonEvidenceResult.ts b/src/domain/comparisonEvidenceResult.ts index 5ad2456870..1aa28e88c5 100644 --- a/src/domain/comparisonEvidenceResult.ts +++ b/src/domain/comparisonEvidenceResult.ts @@ -109,6 +109,7 @@ export function readComparisonResult( if (!parsed.ok) return parsed; const links = validateFindingLinks(evidence, [ ...parsed.value.changes.flatMap(({ evidence_links }) => evidence_links), + // optional-fact-default: only retained IDs are links to validate. ...(parsed.value.integrity_mismatch_evidence_ids ?? []), ]); if (!links.ok) return links; diff --git a/src/domain/desktop/appTaskDraft.ts b/src/domain/desktop/appTaskDraft.ts index 8fc4d0e544..f8d32d7232 100644 --- a/src/domain/desktop/appTaskDraft.ts +++ b/src/domain/desktop/appTaskDraft.ts @@ -352,6 +352,7 @@ const valueSuggestions = ( valuesCut: cut, // The count guard sits outside the cap, as for XML. guards: [ + // generation-cap: suggested checks an author picks among ...recordGuards(file, suggested.slice(0, MAX_SUGGESTIONS), ends, added), ...counts.guards, ], @@ -399,6 +400,7 @@ const suggestedChecks = ( : valueSuggestions(file, baseline, final, document); return { ...content, + // generation-cap: suggested checks an author picks among suggested: [...created, ...content.suggested].slice(0, MAX_SUGGESTIONS), }; }; diff --git a/src/domain/desktop/appTaskDraftAdded.ts b/src/domain/desktop/appTaskDraftAdded.ts index 4719b23136..aead5a3931 100644 --- a/src/domain/desktop/appTaskDraftAdded.ts +++ b/src/domain/desktop/appTaskDraftAdded.ts @@ -205,27 +205,30 @@ export const attributeChecks = ( ) && !isViewStateName(key), ); - return rankAttributes( - eligible.filter(({ key, value }) => - checkFits( - context, - `${pointer}/attributes/${escapeJsonPointerToken(key)}`, - value, + return ( + rankAttributes( + eligible.filter(({ key, value }) => + checkFits( + context, + `${pointer}/attributes/${escapeJsonPointerToken(key)}`, + value, + ), ), - ), - ) - .toSorted( - (left, right) => - usual(left.key, left.value) - usual(right.key, right.value), ) - .slice(0, MAX_ATTRIBUTE_CHECKS) - .map(({ key, value }) => - valueEqualsCheck( - file, - `${pointer}/attributes/${escapeJsonPointerToken(key)}`, - value, - ), - ); + .toSorted( + (left, right) => + usual(left.key, left.value) - usual(right.key, right.value), + ) + // generation-cap: suggested attribute checks + .slice(0, MAX_ATTRIBUTE_CHECKS) + .map(({ key, value }) => + valueEqualsCheck( + file, + `${pointer}/attributes/${escapeJsonPointerToken(key)}`, + value, + ), + ) + ); }; /** @@ -354,6 +357,7 @@ export const fieldChecks = ( } }); if (texts.length > 0) + // generation-cap: suggested field checks return [...new Set(texts)].slice(0, MAX_FIELD_CHECKS).map((value) => ({ kind: "text_contains" as const, file, @@ -450,10 +454,14 @@ export const recordChecks = ( const fields = fieldsOf(context, pointer, element, { nested: true }); // A record whose one field is the one its selector names it by, as a VYM branch its heading, is checked by that field. return ( - fields.length > 0 - ? fields - : fieldsOf(context, pointer, element, { nested: true, selector: true }) - ).slice(0, MAX_FIELD_CHECKS); + ( + fields.length > 0 + ? fields + : fieldsOf(context, pointer, element, { nested: true, selector: true }) + ) + // generation-cap: suggested field checks + .slice(0, MAX_FIELD_CHECKS) + ); }; /** Whether an element holds an identifier of its own among its descendants, as GnuCash's `` holds each split's ``, so its whole text holds ids a later save makes anew. */ diff --git a/src/domain/desktop/appTaskDraftAlternatives.ts b/src/domain/desktop/appTaskDraftAlternatives.ts index c0eee64aec..1e2ffa3883 100644 --- a/src/domain/desktop/appTaskDraftAlternatives.ts +++ b/src/domain/desktop/appTaskDraftAlternatives.ts @@ -90,6 +90,7 @@ export const alternativePointers = ( ] : [], ) + // generation-cap: alternative selectors offered for a check .slice(0, MAX_ALTERNATIVES); if (found.length > 0 || !tagOnly) return found; } diff --git a/src/domain/desktop/appTaskDraftCounts.ts b/src/domain/desktop/appTaskDraftCounts.ts index 6a8caceacc..b158874ae7 100644 --- a/src/domain/desktop/appTaskDraftCounts.ts +++ b/src/domain/desktop/appTaskDraftCounts.ts @@ -211,6 +211,7 @@ export const draftCounts = ( return seed !== end && Math.max(seed ?? 0, end ?? 0) > 1; }) .flatMap((counted) => countAt(context, counted, "final") ?? []) + // generation-cap: suggested count checks .slice(0, MAX_COUNTS); const edited = new Map(); for (const pointer of change.changed) { @@ -235,6 +236,7 @@ export const draftCounts = ( membersOf(ends.final, counted).length, ) .flatMap((counted) => countAt(context, counted, "baseline") ?? []) + // generation-cap: suggested count guards .slice(0, MAX_COUNT_GUARDS); return { checks, guards }; }; diff --git a/src/domain/desktop/appTaskDraftFileNotes.ts b/src/domain/desktop/appTaskDraftFileNotes.ts index cdabcbeb63..b5418228c5 100644 --- a/src/domain/desktop/appTaskDraftFileNotes.ts +++ b/src/domain/desktop/appTaskDraftFileNotes.ts @@ -40,6 +40,7 @@ export const generatedReferenceNotes = ( file, message: "Some array values refer to newly generated record IDs and cannot be checked exactly across runs; review the relationship manually.", + // sample-cap: example pointers; the file's change lists every pointer pointers: pointers.slice(0, MAX_LISTED), }, ]; @@ -85,6 +86,7 @@ const factNotes = (file: string, facts: NamedFacts): FileNote[] => { const home = `~/${file}`; const notes: FileNote[] = []; if (facts.positional > 0 || facts.changes === 0) { + // sample-cap: example elements; the file's change lists every pointer const elements = facts.positionalTags.slice(0, MAX_LISTED); notes.push({ code: "by_position", @@ -103,13 +105,14 @@ const factNotes = (file: string, facts: NamedFacts): FileNote[] => { message: `Every change in ${home} is view state, a renumbered id, a volatile value or a time the app stamps, not an edit: ${facts.flagged.length === 0 ? "no check is suggested" : "the suggested checks are those, kept so the draft is not empty"}. Save the edit the task is about, then capture again.`, ...(facts.flagged.length === 0 ? {} - : { pointers: facts.flagged.slice(0, MAX_LISTED) }), + : { pointers: facts.flagged.slice(0, MAX_LISTED) }), // sample-cap: example pointers; the file's change lists every pointer }); if (facts.long.length > 0) notes.push({ code: "long_text", file, message: `${String(facts.long.length)} value(s) in ${home} exceed the 2,000-character check limit, so whole-value checks were omitted; use a smaller check where supported.`, + // sample-cap: example pointers; the note states the full count pointers: facts.long.slice(0, MAX_LISTED), }); return notes; diff --git a/src/domain/desktop/appTaskDraftGuards.ts b/src/domain/desktop/appTaskDraftGuards.ts index 8f8d65791b..fad200ac0a 100644 --- a/src/domain/desktop/appTaskDraftGuards.ts +++ b/src/domain/desktop/appTaskDraftGuards.ts @@ -440,6 +440,7 @@ const guardsFor = (context: GuardContext, check: Suggestion): Suggestion[] => { const { siblings, all } = siblingsOf(context, step); const varies = variesAmong(all); const guards: Suggestion[] = []; + // generation-cap: siblings read while looking for a guard for (const sibling of siblings.slice(0, MAX_SIBLINGS_READ)) { if (guards.length === MAX_GUARDS_PER_CHECK) break; const guard = siblingGuard( @@ -485,7 +486,10 @@ export const draftGuards = ( guards.push(guard); } } - return guards - .toSorted((left, right) => placed(left) - placed(right)) - .slice(0, MAX_GUARDS); + return ( + guards + .toSorted((left, right) => placed(left) - placed(right)) + // generation-cap: suggested guards + .slice(0, MAX_GUARDS) + ); }; diff --git a/src/domain/desktop/appTaskDraftItems.ts b/src/domain/desktop/appTaskDraftItems.ts index c97fe008b1..3589f6c8f6 100644 --- a/src/domain/desktop/appTaskDraftItems.ts +++ b/src/domain/desktop/appTaskDraftItems.ts @@ -132,6 +132,7 @@ export const placedItemCheck = ( (left, right) => Math.abs(left.index - here) - Math.abs(right.index - here), ) + // generation-cap: nearby items kept to build a suggestion .slice(0, MAX_KEPT) .toSorted((left, right) => left.index - right.index) .map(({ text }) => ({ diff --git a/src/domain/desktop/appTaskDraftJson.ts b/src/domain/desktop/appTaskDraftJson.ts index efb4159c07..e4a8b57505 100644 --- a/src/domain/desktop/appTaskDraftJson.ts +++ b/src/domain/desktop/appTaskDraftJson.ts @@ -288,6 +288,7 @@ export const jsonCounts = ( return seed !== end && Math.max(seed ?? 0, end ?? 0) > 1; }) .map((counted) => countOf(file, counted, ends.final)) + // generation-cap: suggested count checks .slice(0, MAX_COUNTS); // Edits stop at the first guard, and each list is read once, however many records they touch. const guards: Suggestion[] = []; @@ -489,6 +490,7 @@ export const recordGuards = ( ? [] : [`${record.list}/${escapeJsonPointerToken(key)}`]; }) + // generation-cap: siblings read while looking for a guard .slice(0, MAX_SIBLINGS_READ); let found = 0; for (const member of siblings) { @@ -505,6 +507,7 @@ export const recordGuards = ( found += 1; } } + // generation-cap: suggested guards return guards.slice(0, MAX_GUARDS); }; @@ -548,6 +551,7 @@ export const positionalNotes = ( code: "by_position", file, message: `${String(pointers.length)} suggested check(s) of ~/${file} reach their value only by position, as nothing names the record they read: another save may order its array otherwise, so check the record by a value another way, such as a count.`, + // sample-cap: example pointers; the note states the full count and the file's change lists every pointer pointers: pointers.slice(0, MAX_LISTED), }, ]; diff --git a/src/domain/desktop/appTaskDraftLineGuards.ts b/src/domain/desktop/appTaskDraftLineGuards.ts index 481b2f34dc..35c257bffa 100644 --- a/src/domain/desktop/appTaskDraftLineGuards.ts +++ b/src/domain/desktop/appTaskDraftLineGuards.ts @@ -98,6 +98,7 @@ export const lineGuards = ( ({ index }) => Math.abs(index - at) <= NEIGHBOURHOOD, ); const lines = (siblings.length > 0 ? siblings : near) + // generation-cap: suggested line guards .slice(0, MAX_GUARD_LINES) .toSorted((left, right) => left.index - right.index) .map(({ line }) => line); diff --git a/src/domain/desktop/appTaskDraftNamed.ts b/src/domain/desktop/appTaskDraftNamed.ts index 6d78fa5b7f..1e5495c633 100644 --- a/src/domain/desktop/appTaskDraftNamed.ts +++ b/src/domain/desktop/appTaskDraftNamed.ts @@ -654,7 +654,7 @@ export const namedDraft = ( edited ? clean : options.document - ? flaggable.slice(0, MAX_FLAGGED) + ? flaggable.slice(0, MAX_FLAGGED) // generation-cap: suggested checks of flagged values : flaggable ).slice(0, options.limit.suggestions); const listed = [...change.added, ...change.changed, ...change.removed]; @@ -683,6 +683,7 @@ export const namedDraft = ( ), ), ] + // generation-cap: suggested guards .slice(0, MAX_GUARDS) .concat(counts.guards) : []; diff --git a/src/domain/desktop/appTaskDraftNested.ts b/src/domain/desktop/appTaskDraftNested.ts index 308e1cca6e..6047d6455c 100644 --- a/src/domain/desktop/appTaskDraftNested.ts +++ b/src/domain/desktop/appTaskDraftNested.ts @@ -219,34 +219,40 @@ export const nestedRecordChecks = ( item !== element && isXmlElement(item) && item.name === element.name, ); if (likes.length === 0) return []; - return recordListsOf(element) - .flatMap(({ steps, records }) => { - const cousins = cousinsOf(likes, steps, records[0]?.name ?? ""); - return records.flatMap((record) => { - const key = recordKey(record, records, cousins, context.chars); - if (key === undefined) return []; - const at = [pointer, ...steps, "children", key.segment].join("/"); - return checkedKeys(record, [...records, ...cousins], key.key) - .filter((name) => { - const value = record.attributes[name]; - return ( - typeof value === "string" && - checkFits( - context, - `${at}/attributes/${escapeJsonPointerToken(name)}`, - value, - ) - ); - }) - .slice(0, MAX_PER_RECORD) - .flatMap((name) => { - const field = `${at}/attributes/${escapeJsonPointerToken(name)}`; - const value = record.attributes[name]; - return context.named(field) && typeof value === "string" - ? [valueEqualsCheck(context.file, field, value)] - : []; - }); - }); - }) - .slice(0, MAX_NESTED_CHECKS); + return ( + recordListsOf(element) + .flatMap(({ steps, records }) => { + const cousins = cousinsOf(likes, steps, records[0]?.name ?? ""); + return records.flatMap((record) => { + const key = recordKey(record, records, cousins, context.chars); + if (key === undefined) return []; + const at = [pointer, ...steps, "children", key.segment].join("/"); + return ( + checkedKeys(record, [...records, ...cousins], key.key) + .filter((name) => { + const value = record.attributes[name]; + return ( + typeof value === "string" && + checkFits( + context, + `${at}/attributes/${escapeJsonPointerToken(name)}`, + value, + ) + ); + }) + // generation-cap: suggested checks per nested record + .slice(0, MAX_PER_RECORD) + .flatMap((name) => { + const field = `${at}/attributes/${escapeJsonPointerToken(name)}`; + const value = record.attributes[name]; + return context.named(field) && typeof value === "string" + ? [valueEqualsCheck(context.file, field, value)] + : []; + }) + ); + }); + }) + // generation-cap: suggested nested checks + .slice(0, MAX_NESTED_CHECKS) + ); }; diff --git a/src/domain/desktop/appTaskDraftNotes.ts b/src/domain/desktop/appTaskDraftNotes.ts index 368853be4f..766483d3d5 100644 --- a/src/domain/desktop/appTaskDraftNotes.ts +++ b/src/domain/desktop/appTaskDraftNotes.ts @@ -1,4 +1,5 @@ import { z } from "zod"; +import { boundedList } from "../boundedList.js"; import { changedStateFiles, type TaskDraftFile } from "./appTaskDraft.js"; import { FILE_NOTE_CODES, type FileNote } from "./appTaskDraftFileNotes.js"; @@ -226,8 +227,10 @@ export const draftNotes = ( message: `File identities changed or could not be compared between ${seed} and ${end}, but the captured values do not yield a draftable change. Inspect the files and write an appropriate check.`, }); if (changed.length > 0) { - const listed = changed.slice(0, MAX_NOTED_FILES); - const more = changed.length - listed.length; + const { items: listed, omitted: more } = boundedList( + changed, + MAX_NOTED_FILES, + ); notes.push({ code: "unowned_changes", message: `${String(changed.length)} file(s) changed between ${seed} and ${end}, none under the paths the export owns (${homeList(facts.owned) || "none"}), so data/get serves none of them: ${listed.map(({ file, role }) => `~/${file} (${role})`).join(", ")}${more === 0 ? "" : `, and ${String(more)} more`}. If one is the app's document or data, capture again naming it with ${STATE_PATH_INPUTS}.`, diff --git a/src/domain/desktop/appTaskDraftText.ts b/src/domain/desktop/appTaskDraftText.ts index 2b5da9b1ff..5c942b3e21 100644 --- a/src/domain/desktop/appTaskDraftText.ts +++ b/src/domain/desktop/appTaskDraftText.ts @@ -293,6 +293,7 @@ const outsideRuns = (pointer: string, ends: Ends): readonly Candidate[] => { identifier: false, })); } + // generation-cap: ancestor tags climbed to name an element return [current, ...[...passed.slice(1), named].slice(0, MAX_TAG_CLIMB)] .filter((element, index, all) => all.indexOf(element) === index) .map((element) => ({ element, pointer: element, identifier: false })); diff --git a/src/domain/desktop/appTaskDraftValues.ts b/src/domain/desktop/appTaskDraftValues.ts index 794574c045..951ce28684 100644 --- a/src/domain/desktop/appTaskDraftValues.ts +++ b/src/domain/desktop/appTaskDraftValues.ts @@ -336,6 +336,7 @@ const referencesOf = ( ...attributeReferences(resolve, value), ...recordListsOf(value) .flatMap(({ records }) => records) + // generation-cap: nested records read for references .slice(0, MAX_NESTED_RECORDS) .flatMap((record) => attributeReferences(resolve, record)), // A field holding another element's id as its text, as a split's ``. diff --git a/src/domain/desktop/memberPairing.ts b/src/domain/desktop/memberPairing.ts index 530ef8ba69..2b15b7fd52 100644 --- a/src/domain/desktop/memberPairing.ts +++ b/src/domain/desktop/memberPairing.ts @@ -142,6 +142,7 @@ const candidatesOf = ( ...identities.filter(({ key }) => !named(key)), ...pairable, ].map(condition), + // generation-cap: member pairs offered as selector conditions ...pairsOf(pairable.slice(0, MAX_PAIRED)), ...ranked.filter(({ tier }) => tier === 3).map(condition), ]; diff --git a/src/domain/desktop/selectorCandidates.ts b/src/domain/desktop/selectorCandidates.ts index 7a5a74751e..f0913d20e1 100644 --- a/src/domain/desktop/selectorCandidates.ts +++ b/src/domain/desktop/selectorCandidates.ts @@ -200,6 +200,7 @@ const partnersOf = (versions: readonly CountedVersion[]) => { for (const member of candidates) { const keys = member && unpaired.get(member.number); if (member === undefined || keys === undefined) continue; + // generation-cap: member pairs offered as selector conditions const paired = member.pairable.slice(0, MAX_PAIRED); for (const key of paired.filter((pairs) => keys.has(pairs))) { const byKey = partners.get(member.number) ?? new Map(); diff --git a/src/domain/desktop/taskDifficulty.test.ts b/src/domain/desktop/taskDifficulty.test.ts index 81dc822085..35b1f98249 100644 --- a/src/domain/desktop/taskDifficulty.test.ts +++ b/src/domain/desktop/taskDifficulty.test.ts @@ -138,6 +138,23 @@ describe("the difficulty record", () => { expect(record.solves).toHaveLength(6); }); + it("leaves the total cost unknown when a solve reported no cost", () => { + const record = difficultyRecord({ + model: "m", + agent: "claude-code", + solves: [pass, solve("passed", { usd: null })], + budgetUsd: 8, + stopped: "cost_unknown", + taskSha256: "ab".repeat(32), + versions: { rea: "6.8.0", agentenv: null }, + measuredAt: "2026-11-07T01:00:00.000Z", + }); + expect(record.usd).toBeNull(); + expect(difficultySection({ task: record })).toContain( + "passed 2 of 2, undecided, cost unknown.", + ); + }); + it("counts failures of checks named like an object's own members as plain numbers", () => { const record = difficultyRecord({ model: "m", diff --git a/src/domain/desktop/taskDifficulty.ts b/src/domain/desktop/taskDifficulty.ts index 24eb296b91..cdaa21db1b 100644 --- a/src/domain/desktop/taskDifficulty.ts +++ b/src/domain/desktop/taskDifficulty.ts @@ -67,9 +67,19 @@ const bandOf = (solves: readonly SolveRecord[]): Band => { return "undecided"; }; -/** The total cost of the solves, unknown costs as none. */ -const spent = (solves: readonly SolveRecord[]): number => - solves.reduce((total, solve) => total + (solve.usd ?? 0), 0); +/** The solves' costs, or null when any solve's cost is unknown. */ +const costs = (solves: readonly SolveRecord[]): number[] | null => { + const known: number[] = []; + for (const { usd } of solves) { + if (usd === null) return null; + known.push(usd); + } + return known; +}; + +/** The total cost of the solves, or null when any solve's cost is unknown. */ +const spent = (solves: readonly SolveRecord[]): number | null => + costs(solves)?.reduce((total, usd) => total + usd, 0) ?? null; /** * Whether to run another solve: not once the band is decided, after too many @@ -86,10 +96,10 @@ export const nextSolve = ( return { next: false, stopped: "decided" }; if (solves.filter((solve) => !finished(solve)).length > MAX_UNFINISHED) return { next: false, stopped: "unfinished" }; - if (solves.some((solve) => solve.usd === null)) - return { next: false, stopped: "cost_unknown" }; - const largest = Math.max(0, ...solves.map((solve) => solve.usd ?? 0)); - const projected = spent(solves) + largest; + const known = costs(solves); + if (known === null) return { next: false, stopped: "cost_unknown" }; + const projected = + known.reduce((total, usd) => total + usd, 0) + Math.max(0, ...known); const rounding = Number.EPSILON * Math.max(projected, budgetUsd) * (solves.length + 2); return projected - budgetUsd > rounding @@ -108,7 +118,8 @@ export type DifficultyRecord = { readonly k: number; readonly passes: number; readonly unfinished: number; - readonly usd: number; + /** Total cost, or null when a solve reported no cost. */ + readonly usd: number | null; readonly budget_usd: number; /** Each finished solve's turns, in order. */ readonly turns: (number | null)[]; @@ -132,6 +143,7 @@ export const difficultyRecord = (input: { readonly measuredAt: string; }): DifficultyRecord => { const done = input.solves.filter(finished); + const total = spent(input.solves); // A Map, so a check named like an object's own member, such as constructor, counts as any other. const failures = new Map(); for (const solve of done) @@ -146,7 +158,7 @@ export const difficultyRecord = (input: { k: done.length, passes: counts(input.solves).passes, unfinished: input.solves.length - done.length, - usd: cents(spent(input.solves)), + usd: total === null ? null : cents(total), budget_usd: input.budgetUsd, turns: done.map((solve) => solve.turns), failures_per_check: Object.fromEntries(failures), @@ -183,7 +195,7 @@ unless they pass none or all, and a task is in the band when it passes 1 to 3 of ${Object.entries(records) .map( ([name, record]) => - `- \`${name}\`: ${record.model} passed ${String(record.passes)} of ${String(record.k)}, ${BAND_WORDS[record.band]}, $${record.usd.toFixed(2)} in all.`, + `- \`${name}\`: ${record.model} passed ${String(record.passes)} of ${String(record.k)}, ${BAND_WORDS[record.band]}, ${record.usd === null ? "cost unknown" : `$${record.usd.toFixed(2)} in all`}.`, ) .join("\n")} `; diff --git a/src/domain/evidenceRecordSummary.ts b/src/domain/evidenceRecordSummary.ts index 02f4c214c9..103713cd67 100644 --- a/src/domain/evidenceRecordSummary.ts +++ b/src/domain/evidenceRecordSummary.ts @@ -241,6 +241,7 @@ export const selectEvidenceRecords = ( readonly limit?: number | undefined; } = {}, ): EvidenceRecordSelection => { + // optional-fact-default: a request default for paging, not an observed fact. const offset = page.offset ?? 0; const limit = page.limit ?? EVIDENCE_RECORD_SELECTION_LIMIT; const records: Evidence[] = []; @@ -346,23 +347,26 @@ export const inspectEvidenceLinks = ( ): EvidenceLinkInspection => { const traversal = options.traversal ?? "direct"; const linkStatus = options.linkStatus ?? "missing"; + // optional-fact-default: a request default for paging, not an observed fact. const offset = options.offset ?? 0; const limit = options.limit ?? EVIDENCE_LINK_INSPECTION_LIMIT; const retained = new Map( bundle.records.map((record) => [record.evidence_id, record]), ); const examined = new Set(); - const pending: string[] = []; + const pending: Evidence[] = []; for (const { evidence } of matchingEvidenceRecords(bundle, filters)) - pending.push(evidence.evidence_id); + pending.push(evidence); const matching = pending.length; while (pending.length > 0) { - const id = pending.pop(); - if (id === undefined || examined.has(id)) continue; - examined.add(id); + const record = pending.pop(); + if (record === undefined || examined.has(record.evidence_id)) continue; + examined.add(record.evidence_id); if (traversal === "direct") continue; - for (const link of retained.get(id)?.evidence_links ?? []) - if (retained.has(link) && !examined.has(link)) pending.push(link); + for (const link of record.evidence_links) { + const linked = retained.get(link); + if (linked !== undefined && !examined.has(link)) pending.push(linked); + } } const rows: EvidenceLinkInspection["rows"] = []; const counts = { total: 0, retained: 0, missing: 0 }; diff --git a/src/domain/functionCallCoverage.ts b/src/domain/functionCallCoverage.ts index ebbb6a3b8c..a677002f23 100644 --- a/src/domain/functionCallCoverage.ts +++ b/src/domain/functionCallCoverage.ts @@ -19,6 +19,7 @@ export const combineFunctionRelationshipCoverage = ( { direction: "callees" as const, coverage: callees }, ]; const diagnostics = uniqueSorted( + // optional-fact-default: descriptive caveats; discovery status carries completeness. reads.flatMap(({ coverage }) => coverage?.diagnostics ?? []), ); const discovery = { @@ -109,6 +110,7 @@ export const assessFunctionCallCoverage = ( dossier: Pick, ): FunctionCallCoverageAssessment => { const unresolvedCallCaveats = uniqueSorted( + // optional-fact-default: caveat text only; discoveryStatus carries completeness. (dossier.unresolved_calls ?? []).map( ({ address, reason }) => `Unresolved call at ${address}: ${reason}`, ), @@ -138,6 +140,7 @@ export const assessFunctionCallCoverage = ( ...unresolvedCallCaveats, ]), unresolvedCallCaveats, + // optional-fact-default: descriptive caveats; discoveryStatus carries completeness. diagnostics: uniqueSorted(coverage?.diagnostics ?? []), discoveryLimitations, discoveryStatus, diff --git a/src/domain/functionComparison.test.ts b/src/domain/functionComparison.test.ts index b495d970ea..de5ee14885 100644 --- a/src/domain/functionComparison.test.ts +++ b/src/domain/functionComparison.test.ts @@ -1292,6 +1292,26 @@ describe("function comparison Swift string literals", () => { stringsDimension("7", withLiterals("0x1000", []), "8", named), ).toMatchObject({ status: "changed" }); }); + + it("leaves a side's count unknown when its names cannot be placed in the function", () => { + const withString = (base: "0x1000" | "0x2000", value: string) => + functionDossierSchema.parse({ + ...dossier("return 0;", base), + referenced_strings: [ + { address: "0x9000", source_address: base, value }, + ], + }); + // A name read from below the procedure start has no function offset. + const unplaced = functionDossierSchema.parse({ + ...withString("0x1000", "before"), + referenced_names: [ + { address: "0x3000", value: "helper", source_address: "0x0800" }, + ], + }); + expect( + stringsDimension("9", unplaced, "a", withString("0x2000", "after")), + ).toMatchObject({ status: "changed", left_count: null, right_count: 1 }); + }); }); describe("function comparison partial Swift literal coverage", () => { diff --git a/src/domain/functionComparisonDimensions.ts b/src/domain/functionComparisonDimensions.ts index 64c1c96d2c..8ba35bb710 100644 --- a/src/domain/functionComparisonDimensions.ts +++ b/src/domain/functionComparisonDimensions.ts @@ -118,6 +118,7 @@ const facetLimitations = ( "strings_names", dossier.referenced_strings.length + dossier.referenced_names.length + + // optional-fact-default: swiftLiteralCoverage reports absence. (dossier.swift_string_literals?.length ?? 0), ], ], @@ -178,10 +179,9 @@ const compareText = ( }); const delta = changes.reduce( (summary, change) => ({ - added_lines: - summary.added_lines + (change.added ? (change.count ?? 0) : 0), + added_lines: summary.added_lines + (change.added ? change.count : 0), removed_lines: - summary.removed_lines + (change.removed ? (change.count ?? 0) : 0), + summary.removed_lines + (change.removed ? change.count : 0), hunks: summary.hunks + (change.added || change.removed ? 1 : 0), }), { added_lines: 0, removed_lines: 0, hunks: 0 }, @@ -358,8 +358,15 @@ const stringsAndNamesResult = ({ names_and_literals: rightNamesAndLiterals, }, ...context, - leftCount: leftStrings.length + (leftNamesAndLiterals?.length ?? 0), - rightCount: rightStrings.length + (rightNamesAndLiterals?.length ?? 0), + // Names that cannot be placed in the function leave the side's count unknown. + leftCount: + leftNamesAndLiterals === null + ? null + : leftStrings.length + leftNamesAndLiterals.length, + rightCount: + rightNamesAndLiterals === null + ? null + : rightStrings.length + rightNamesAndLiterals.length, textDelta: null, limitations, }); diff --git a/src/domain/functionComparisonNormalization.ts b/src/domain/functionComparisonNormalization.ts index 9a0d10ad93..8860563235 100644 --- a/src/domain/functionComparisonNormalization.ts +++ b/src/domain/functionComparisonNormalization.ts @@ -181,7 +181,8 @@ export const nameAndSwiftProjection = ( }), ), ...(includeSwiftLiterals - ? (snapshot.dossier.swift_string_literals ?? []) + ? // optional-fact-default: swiftLiteralCoverage reports an absent inventory. + (snapshot.dossier.swift_string_literals ?? []) : [] ).map( ({ @@ -242,6 +243,7 @@ export const swiftLiteralSitesConflict = ( export const swiftLiteralCoverage = ( snapshot: FunctionSnapshot, ): "absent" | "complete" | "partial" => + // optional-fact-default: absent omissions with present literals is complete. (snapshot.dossier.swift_string_literal_omissions ?? []).length > 0 ? "partial" : snapshot.dossier.swift_string_literals === undefined @@ -256,6 +258,7 @@ const swiftLiteralSites = (snapshot: FunctionSnapshot) => { }; // Keep the same literal facts the full strings_names projection compares. const values = new Map(); + // optional-fact-default: swiftLiteralCoverage reports an absent inventory. for (const literal of snapshot.dossier.swift_string_literals ?? []) { const key = site(literal.source_address, literal.registers); if (key === null) continue; diff --git a/src/domain/gpu/gpuCodeObjects.ts b/src/domain/gpu/gpuCodeObjects.ts index 42a1fc4026..7a05b0780d 100644 --- a/src/domain/gpu/gpuCodeObjects.ts +++ b/src/domain/gpu/gpuCodeObjects.ts @@ -75,6 +75,7 @@ export const gpuObjectSchema = z.strictObject({ raw_flags: z.string().nullable(), location: gpuLocationSchema, metadata_location: gpuLocationSchema, + // domain-vocabulary: how deeply one code object was decoded, including format outcomes. inspection: z.enum([ "inventory", "complete", diff --git a/src/domain/javascript/electronActiveObservation.ts b/src/domain/javascript/electronActiveObservation.ts index e7631e5786..82bf312ab0 100644 --- a/src/domain/javascript/electronActiveObservation.ts +++ b/src/domain/javascript/electronActiveObservation.ts @@ -175,6 +175,7 @@ export const electronActiveWindowSchema = z.strictObject({ }); const coverageSchema = z.strictObject({ + // lifecycle-state: how the observation session ended (attach, hook conflict, exit, cleanup). status: z.enum([ "complete", "partial_attach", diff --git a/src/domain/javascript/javascriptSemanticCoverage.ts b/src/domain/javascript/javascriptSemanticCoverage.ts index 81b4bee3e4..1f3be6a9ca 100644 --- a/src/domain/javascript/javascriptSemanticCoverage.ts +++ b/src/domain/javascript/javascriptSemanticCoverage.ts @@ -78,6 +78,7 @@ export const semanticCoverage = ( /** Read typed resource-limit classifications from any coverage state. */ export const semanticCoverageResourceLimits = ( coverage: JavaScriptSemanticCoverage, + // optional-fact-default: typed classifications only; the coverage state carries completeness. ): readonly JavaScriptSemanticResourceLimit[] => coverage.resourceLimits ?? []; /** Effective evaluator facts, rather than reconstructed default-only bounds. */ diff --git a/src/domain/javascript/javascriptStaticCoverage.test.ts b/src/domain/javascript/javascriptStaticCoverage.test.ts index 0f77fd74f8..884d1b24ac 100644 --- a/src/domain/javascript/javascriptStaticCoverage.test.ts +++ b/src/domain/javascript/javascriptStaticCoverage.test.ts @@ -43,6 +43,19 @@ it("distinguishes recovered syntax from unparseable source without inventing an }); }); +it("does not report complete parsing when the unknown-finding count is itself unknown", () => { + const complete = analyzeJavaScriptStaticSource( + "export const value = 1;", + ).analysis_coverage; + expect(javaScriptStaticParseStatus(complete)).toBe("complete"); + expect( + javaScriptStaticParseStatus({ + ...complete, + semantics: { ...complete.semantics, unknown_findings: null }, + }), + ).toBe("partial"); +}); + it("keeps framework applicability unknown without positive Electron evidence", () => { const ordinary = analyzeJavaScriptStaticSource("export const value = 1;"); expect(ordinary.parse_status).toBe("complete"); diff --git a/src/domain/javascript/javascriptStaticCoverage.ts b/src/domain/javascript/javascriptStaticCoverage.ts index 4f210da198..b27ee940b5 100644 --- a/src/domain/javascript/javascriptStaticCoverage.ts +++ b/src/domain/javascript/javascriptStaticCoverage.ts @@ -58,7 +58,8 @@ export const javaScriptStaticParseStatus = ( ? "failed" : coverage.syntax.status === "recovered" || coverage.examination.status === "not-examined" || - (coverage.semantics.unknown_findings ?? 0) > 0 || + // An unknown finding count cannot establish that none were found. + coverage.semantics.unknown_findings !== 0 || coverage.examination.semantic_resource_limits.includes( "alias-selections", ) diff --git a/src/domain/javascript/sourceToBundleComparison.ts b/src/domain/javascript/sourceToBundleComparison.ts index f956097ae7..9ca8c23b97 100644 --- a/src/domain/javascript/sourceToBundleComparison.ts +++ b/src/domain/javascript/sourceToBundleComparison.ts @@ -67,6 +67,7 @@ export const compareSourceToBundle = ( ...nodeIds, ...candidates .filter((candidate) => nodeIds.includes(candidate.current_node_id)) + // optional-fact-default: omitted without occurrence provenance, when the only represented node is the candidate's own, already in nodeIds. .flatMap((candidate) => candidate.representation_node_ids ?? []), ]), ); diff --git a/src/domain/managed/managedMemberComparisonCoverage.ts b/src/domain/managed/managedMemberComparisonCoverage.ts index 4c07415c18..0c3469cd94 100644 --- a/src/domain/managed/managedMemberComparisonCoverage.ts +++ b/src/domain/managed/managedMemberComparisonCoverage.ts @@ -278,7 +278,9 @@ export const comparisonLimitations = ( "At least one managed member observation did not examine ExportedType rows; its exported and forwarded types are unknown.", ); if ( + // optional-fact-default: null rows are reported as unknown by the limitation above. (left.exported_types?.length ?? 0) > 0 || + // optional-fact-default: null rows are reported as unknown by the limitation above. (right.exported_types?.length ?? 0) > 0 ) limitations.push( diff --git a/src/domain/native/nativeInvestigationGraph.ts b/src/domain/native/nativeInvestigationGraph.ts index a453fb8cfe..db9a26362e 100644 --- a/src/domain/native/nativeInvestigationGraph.ts +++ b/src/domain/native/nativeInvestigationGraph.ts @@ -1,5 +1,5 @@ import { z } from "zod"; -import { knownCoverageStatusSchema } from "../coverage.js"; +import { coverageStatusSchema } from "../coverage.js"; import { nativeMetadataEvidenceSchema, @@ -101,14 +101,18 @@ export type NativeInvestigationEdge = z.infer< /** Explicit inventory coverage so missing graph parts are not read as absent. */ export const nativeInvestigationCoverageSchema = z.strictObject({ facet: z.string().min(1), - status: z.enum([ - ...knownCoverageStatusSchema.options, - "unsupported", - "not_requested", - ]), + status: z + .enum([...coverageStatusSchema.options, "unsupported", "not_requested"]) + .describe( + "unknown when the producer could not tell how much of the facet it covered; omitted is then null.", + ), reason: z.string().nullable(), examined: z.int().nonnegative(), - omitted: z.int().nonnegative(), + omitted: z + .int() + .nonnegative() + .nullable() + .describe("Omitted items; null when the count is unknown."), }); export const nativeInvestigationProviderSchema = z.strictObject({ diff --git a/src/domain/process/processCaptureCoverage.ts b/src/domain/process/processCaptureCoverage.ts index 082dfac9f4..bd618a419d 100644 --- a/src/domain/process/processCaptureCoverage.ts +++ b/src/domain/process/processCaptureCoverage.ts @@ -130,7 +130,9 @@ export const hasCaptureTruncation = ( ): boolean => omitted(details.raw_terminal) || omitted(details.rendered_terminal) || + // optional-fact-default: absent without a normalized stream; raw retention is checked above. (details.normalized_terminal?.omitted_frames ?? 0) > 0 || + // optional-fact-default: TerminalRenderer omits the field when the count is zero. (details.rendered_terminal.unknown_size_frames ?? 0) > 0 || filesystemTruncated(details.filesystem_before) || filesystemTruncated(details.filesystem_after) || diff --git a/src/domain/process/processComparison.ts b/src/domain/process/processComparison.ts index 6b72113798..05a5459d9c 100644 --- a/src/domain/process/processComparison.ts +++ b/src/domain/process/processComparison.ts @@ -469,6 +469,7 @@ const explicitlyTimedSources = ( specification.events.flatMap((event) => includesCaptureLocalTiming( event.exact, + // optional-fact-default: a trace specification option, not an observation. new Set(event.ignore_fields ?? []), ) ? [event.source] diff --git a/src/domain/releaseExposure.ts b/src/domain/releaseExposure.ts index bf80520679..12637ebaf8 100644 --- a/src/domain/releaseExposure.ts +++ b/src/domain/releaseExposure.ts @@ -464,6 +464,7 @@ const boundSamples = (samples: readonly string[]): string[] => { const boundLocations = ( locations: readonly EvidenceLocation[], + // sample-cap: illustrative locations; observation.counts reports the totals ): EvidenceLocation[] => locations.slice(0, MAX_RELEASE_EXPOSURE_SAMPLES); const makeCheck = ( @@ -496,6 +497,7 @@ const findingLocations = ( fallback: string, ): EvidenceLocation[] => { const locations = [...new Set(paths.filter((path) => path.length > 0))] + // sample-cap: illustrative locations; observation.counts reports the totals .slice(0, MAX_RELEASE_EXPOSURE_SAMPLES) .map((path) => ({ kind: "artifact-path" as const, path })); return locations.length > 0 ? locations : targetLocation(fallback); diff --git a/src/domain/sqlite/sqliteDatabase.ts b/src/domain/sqlite/sqliteDatabase.ts index fb40acfa42..158d83305e 100644 --- a/src/domain/sqlite/sqliteDatabase.ts +++ b/src/domain/sqlite/sqliteDatabase.ts @@ -153,6 +153,7 @@ export const sqliteDatabaseSchema = z without_rowid: z.boolean(), strict: z.boolean(), column_count: nonnegative.nullable(), + // domain-vocabulary: whether column details were read, unsupported or not requested. columns_completeness: z.enum([ "complete", "unsupported", diff --git a/src/domain/wasm/wasmArtifact.ts b/src/domain/wasm/wasmArtifact.ts index 7a93001f5e..919d173678 100644 --- a/src/domain/wasm/wasmArtifact.ts +++ b/src/domain/wasm/wasmArtifact.ts @@ -131,6 +131,7 @@ export const wasmArtifactSchema = z interface: wasmInterfaceSchema.exactOptional(), imports: z.array(z.string()), exports: z.array(z.string()), + // domain-vocabulary: the state of the WebAssembly name section. debug_name_metadata: z .enum(["unknown", "not-present", "complete", "uninterpretable"]) .default("unknown"), diff --git a/src/domain/webCaptureDiff.ts b/src/domain/webCaptureDiff.ts index 12bab30070..e57d90a18b 100644 --- a/src/domain/webCaptureDiff.ts +++ b/src/domain/webCaptureDiff.ts @@ -789,6 +789,7 @@ const webSocketPayloadMaps = ( beforeGroup.connections.length !== afterGroup.connections.length ) continue; + // optional-fact-default: equal connection counts; with none there are no events to pair. const eventCount = beforeGroup.connections[0]?.events.length ?? 0; const comparableBytes = new Set(); const comparableShapes = new Set(); @@ -847,6 +848,7 @@ const webMcpDimension = ( ): Dimension => { const groups = (discovery: WebMcpDiscovery | null) => { const result = new Map(); + // optional-fact-default: null discovery fails webMcpComplete, so its values are unknown. for (const tool of discovery?.tools.items ?? []) { const identity = `webmcp_${digestCanonicalValue({ name: tool.name, diff --git a/src/hopper/HopperCallerReconciliation.ts b/src/hopper/HopperCallerReconciliation.ts index c4b6bed961..7397078001 100644 --- a/src/hopper/HopperCallerReconciliation.ts +++ b/src/hopper/HopperCallerReconciliation.ts @@ -495,10 +495,16 @@ export const reconcileHopperCallers = async ( } const addresses = new Set(instructions); addresses.add(target.address); - const selectedDestination = index.destinations.get(target.address); - const callers = new Map(selectedDestination?.callers ?? []); + // The index holds forward observations from the examined procedures only. A + // miss means none of them named the target: it adds no callers, and does + // not show there are none. Relationship coverage stays unknown, with the + // scan facts as its reason, whatever the index holds. + const selectedDestination: Destination = index.destinations.get( + target.address, + ) ?? { callers: new Map(), references: [] }; + const callers = new Map(selectedDestination.callers); const selectedReferences: Array<{ caller: Identity; edge: CompactEdge }> = []; - for (const item of selectedDestination?.references ?? []) { + for (const item of selectedDestination.references) { if (!addresses.has(item.edge.target_address)) continue; const source = item.edge.source_procedure === "caller" @@ -547,7 +553,7 @@ export const reconcileHopperCallers = async ( const compactReferences = selectedReferences.map(({ caller, edge }) => compactCallReference(caller, edge), ); - const inventoryCallers = selectedDestination?.callers ?? new Map(); + const inventoryCallers = selectedDestination.callers; const siteCallers = new Map(); for (const { caller } of selectedReferences) if ( @@ -659,9 +665,7 @@ export const reconcileHopperCallers = async ( native_result: retainedNativeResult, forward_observations: { target, - callee_inventory_callers: [ - ...(selectedDestination?.callers.values() ?? []), - ], + callee_inventory_callers: [...selectedDestination.callers.values()], call_site_callers: [...siteCallers.values()], call_references: compactReferences, provenance: diff --git a/src/kuna/KunaJsonStream.ts b/src/kuna/KunaJsonStream.ts index 5bbedca065..d6851a02b9 100644 --- a/src/kuna/KunaJsonStream.ts +++ b/src/kuna/KunaJsonStream.ts @@ -159,6 +159,7 @@ export abstract class KunaJsonDocumentReader extends Writable { /** Whether the scalar being assembled is a key. */ #inKey = false; /** The key or kept scalar assembled so far. */ + // not-an-allowance: the scalar being assembled; keys are capped at MAX_TOKEN_CODE_UNITS and kept values are charged through #charge. #text = ""; #rows = 0; #projectedBytes = 0; diff --git a/src/process/BoundedOutputExcerpt.ts b/src/process/BoundedOutputExcerpt.ts index d65d96ba7b..5f09119fd4 100644 --- a/src/process/BoundedOutputExcerpt.ts +++ b/src/process/BoundedOutputExcerpt.ts @@ -2,6 +2,7 @@ export class BoundedOutputExcerpt { #head: Buffer = Buffer.alloc(0); #tail: Buffer = Buffer.alloc(0); + // not-an-allowance: observed byte total, compared with the limit only to report truncation. #total = 0; readonly #headLimit: number; readonly #tailLimit: number; diff --git a/src/process/ProviderProcess.ts b/src/process/ProviderProcess.ts index 8930563254..be8496ec49 100644 --- a/src/process/ProviderProcess.ts +++ b/src/process/ProviderProcess.ts @@ -1058,6 +1058,7 @@ export class ProviderProcessSupervisor { class ProcessOutputCapture { readonly #chunks: Buffer[] = []; + // not-an-allowance: retained length of a tail buffer that drops its front past the limit instead of refusing input. #bytes = 0; /** Observed bytes before the first retained one, which tail retention dropped. */ #start = 0; diff --git a/src/resources/AsarHeader.ts b/src/resources/AsarHeader.ts index 421e3ac7ef..b3e0e51792 100644 --- a/src/resources/AsarHeader.ts +++ b/src/resources/AsarHeader.ts @@ -186,6 +186,7 @@ class AsarHeaderSignatureProbeImpl implements AsarHeaderSignatureProbe { readonly limit: number; readonly #fixed = Buffer.alloc(16); #fixedBytes = 0; + // not-an-allowance: scan position in the JSON header; reaching the probe limit stops the probe, it charges nothing. #scannedJsonBytes = 0; #extents: Omit | undefined; #stop: ProbeStop = { state: "pending" }; diff --git a/tests/boundary/mcp/analyzeFunctionDetail.test.ts b/tests/boundary/mcp/analyzeFunctionDetail.test.ts index c03b615173..e05dd46b83 100644 --- a/tests/boundary/mcp/analyzeFunctionDetail.test.ts +++ b/tests/boundary/mcp/analyzeFunctionDetail.test.ts @@ -263,7 +263,7 @@ it("keeps value-flow counts unknown in the default summary when the provider rec expect(evidence.normalized_result).toMatchObject({ kind: "summary", summary: { - value_flow: { available: false, truncated: false }, + value_flow: { available: false, truncated: null }, counts: { value_flow_operations: null, value_flow_def_use: null, diff --git a/tests/evaluation/budgetArithmeticGuard.test.ts b/tests/evaluation/budgetArithmeticGuard.test.ts index 254d6b9a39..835ba618c9 100644 --- a/tests/evaluation/budgetArithmeticGuard.test.ts +++ b/tests/evaluation/budgetArithmeticGuard.test.ts @@ -1,4 +1,4 @@ -import { expect, it } from "vitest"; +import { describe, expect, it } from "vitest"; import { budgetArithmeticCount } from "../../scripts/verify/budget-arithmetic-guard.mjs"; it("counts arithmetic on fields named for an allowance", () => { @@ -101,3 +101,110 @@ it.each([ ].join("\n"); expect(budgetArithmeticCount(reader)).toBe(1); }); + +describe("not-an-allowance markers", () => { + const reader = (declaration: readonly string[]) => + [ + "class Reader {", + ...declaration, + " read(size: number): void {", + " this.#seen += size;", + " if (this.#seen > LIMIT) this.#cut = true;", + " this.#remainingBytes -= size;", + " }", + "}", + ].join("\n"); + // The marker comments hold no field arithmetic, so the raw source serves as + // the comment-stripped content too. + const count = (source: string) => budgetArithmeticCount(source, { source }); + + it("exempts a field whose declaration carries a reasoned marker", () => { + expect( + count( + reader([ + " // not-an-allowance: observed total, compared only to report a cut.", + " #seen = 0;", + ]), + ), + ).toBe(1); + expect( + count( + reader([ + " #seen = 0; // not-an-allowance: observed total for the cut flag.", + ]), + ), + ).toBe(1); + }); + + it("exempts a named allowance field only by its own marker", () => { + expect( + count( + reader([ + " #seen = 0;", + " // not-an-allowance: write cursor named for history.", + " #remainingBytes = 0;", + ]), + ), + ).toBe(1); + }); + + it.each([ + [[" // not-an-allowance:", " #seen = 0;"]], + [[" // generation-cap: another guard's marker.", " #seen = 0;"]], + [ + [ + " /* not-an-allowance: block comments are not markers. */", + " #seen = 0;", + ], + ], + [ + [ + " // not-an-allowance: separated by code.", + " #other = 0;", + " #seen = 0;", + ], + ], + ])("does not exempt %j", (declaration) => { + expect(count(reader(declaration))).toBe(2); + }); +}); + +it("binds a marker to its own class field", () => { + const source = [ + "class Tally {", + " // not-an-allowance: observed total for the truncation flag.", + " #bytes = 0;", + " read(size: number): void {", + " this.#bytes += size;", + " if (this.#bytes > LIMIT) this.#cut = true;", + " }", + "}", + "class Allowance {", + " #bytes = 0;", + " read(size: number): void {", + " this.#bytes += size;", + " if (this.#bytes > LIMIT) throw failure();", + " }", + "}", + ].join("\n"); + expect(budgetArithmeticCount(source, { source })).toBe(1); +}); + +it("does not exempt a class field through a marked object property", () => { + const source = [ + "class Reader {", + " bytes = 0;", + " options(): object {", + " return {", + " // not-an-allowance: an option, not the field.", + " bytes: 0,", + " };", + " }", + " read(size: number): void {", + " this.bytes += size;", + " if (this.bytes > LIMIT) throw failure();", + " }", + "}", + ].join("\n"); + expect(budgetArithmeticCount(source, { source })).toBe(1); +}); diff --git a/tests/evaluation/completenessEnumGuard.test.ts b/tests/evaluation/completenessEnumGuard.test.ts index 11d58bf9ae..a15fdedc2c 100644 --- a/tests/evaluation/completenessEnumGuard.test.ts +++ b/tests/evaluation/completenessEnumGuard.test.ts @@ -28,3 +28,47 @@ it("does not count a detail level", () => { ), ).toBe(0); }); + +const marked = (source: string) => + localCompletenessEnumCount(source, { source }); + +it("exempts an enum marked with a reason for each non-coverage meaning", () => { + for (const name of ["detail-level", "lifecycle-state", "domain-vocabulary"]) + expect( + marked( + `// ${name}: not coverage.\nstate: z.enum(["complete", "failed"]),`, + ), + ).toBe(0); + expect( + marked( + '// lifecycle-state: how far it ran.\nstate: z\n .enum(["complete", "failed"]),', + ), + ).toBe(0); + expect( + marked('state: z.enum(["complete", "failed"]), // lifecycle-state: ran.'), + ).toBe(0); +}); + +it("still counts an unmarked, unreasoned or other-guard enum", () => { + expect(marked('state: z.enum(["complete", "partial"]),')).toBe(1); + expect( + marked('// lifecycle-state:\nstate: z.enum(["complete", "failed"]),'), + ).toBe(1); + expect( + marked( + '// generation-cap: another guard.\nstate: z.enum(["complete", "failed"]),', + ), + ).toBe(1); + expect( + marked( + '/* domain-vocabulary: block comment. */\nstate: z.enum(["complete", "x"]),', + ), + ).toBe(1); + // A marker on a summary-level enum leaves the uncounted enum uncounted and + // does not reach the next one. + expect( + marked( + '// detail-level: request.\ndetail: z.enum(["complete", "summary"]),\nstatus: z.enum(["complete", "partial"]),', + ), + ).toBe(1); +}); diff --git a/tests/evaluation/optionalFactDefaultGuard.test.ts b/tests/evaluation/optionalFactDefaultGuard.test.ts new file mode 100644 index 0000000000..c3bd61ed73 --- /dev/null +++ b/tests/evaluation/optionalFactDefaultGuard.test.ts @@ -0,0 +1,226 @@ +import { readFile } from "node:fs/promises"; +import { expect, it } from "vitest"; +import { + isComparisonOrCountFile, + optionalFactDefaultCount, +} from "../../scripts/verify/optional-fact-default-guard.mjs"; + +it("counts property reads defaulted to 0, [] or false in any layout", () => { + expect(optionalFactDefaultCount("const n = report.count ?? 0;")).toBe(1); + expect(optionalFactDefaultCount("side?.omitted_fields ?? 0")).toBe(1); + expect(optionalFactDefaultCount("const xs = result.items ?? [];")).toBe(1); + expect(optionalFactDefaultCount("flags.complete ?? false")).toBe(1); + expect(optionalFactDefaultCount("const n =\n report.count ??\n 0;\n")).toBe( + 1, + ); + expect(optionalFactDefaultCount("(left.exported_types?.length ?? 0)")).toBe( + 1, + ); + // The last link of a chain is the operand the default replaces. + expect(optionalFactDefaultCount("left.count ?? right.count ?? 0")).toBe(1); + expect( + optionalFactDefaultCount( + "// optional-fact-default: request default, not an observation\nconst n = left.count ??\n right.count ?? 0;", + ), + ).toBe(0); +}); + +it("ignores accumulators, indexed reads and other defaults", () => { + expect(optionalFactDefaultCount("counts.get(key) ?? 0")).toBe(0); + expect(optionalFactDefaultCount("bytes[offset] ?? 0")).toBe(0); + expect(optionalFactDefaultCount("report.count ?? 0.5")).toBe(0); + expect(optionalFactDefaultCount("report.count ?? 10")).toBe(0); + expect(optionalFactDefaultCount("report.count ?? null")).toBe(0); + expect(optionalFactDefaultCount("report.count ?? fallback.count")).toBe(0); +}); + +it("honours an exemption marker that gives a reason", () => { + expect( + optionalFactDefaultCount( + "// optional-fact-default: request default, not an observation\nconst offset = page.offset ?? 0;", + ), + ).toBe(0); + expect( + optionalFactDefaultCount( + "const offset = page.offset ?? 0; // optional-fact-default: request default, not observed", + ), + ).toBe(0); + expect( + optionalFactDefaultCount("// e.g. report.count ?? 0 hides unknown"), + ).toBe(0); + // A leading block comment does not hide live code after it. + expect( + optionalFactDefaultCount("/* paging note */ const n = report.count ?? 0;"), + ).toBe(1); + // A default inside a block comment without leading stars is not code. + expect( + optionalFactDefaultCount( + "/*\n report.count ?? 0 would hide unknown\n*/\nconst url = 'https://x';", + ), + ).toBe(0); + // `//` inside a string is not a comment. + expect( + optionalFactDefaultCount("const u = 'https://x'; const n = r.count ?? 0;"), + ).toBe(1); + // A bare marker, or one two lines above, does not exempt the default. + expect( + optionalFactDefaultCount( + "// optional-fact-default:\nconst offset = page.offset ?? 0;", + ), + ).toBe(1); + // Any non-empty reason exempts, as for the other reason markers. + expect( + optionalFactDefaultCount( + "// optional-fact-default: request option\nconst offset = page.offset ?? 0;", + ), + ).toBe(0); + expect( + optionalFactDefaultCount( + "// optional-fact-default: request default, not observed\n\nconst n = report.count ?? 0;", + ), + ).toBe(1); +}); + +it("counts executable defaults only, whatever strings and regular expressions hold", () => { + // Text in a string is not code. + expect(optionalFactDefaultCount('const example = "report.count ?? 0";')).toBe( + 0, + ); + expect(optionalFactDefaultCount("const t = `${a} report.count ?? 0`;")).toBe( + 0, + ); + // A regular expression holding `/*` or `//` does not hide the code after it. + expect( + optionalFactDefaultCount( + "const pattern = /[/*]/; const n = report.count ?? 0;", + ), + ).toBe(1); + expect( + optionalFactDefaultCount( + "const p = /a\\/\\//u; const n = report.count ?? 0;", + ), + ).toBe(1); + // A marker inside a string does not exempt the default. + expect( + optionalFactDefaultCount( + 'const s = "optional-fact-default: not a real reason"; const n = report.count ?? 0;', + ), + ).toBe(1); +}); + +it("tracks template substitutions and division", () => { + // A substitution starts an expression, so its `/` opens a regular + // expression whose `/*` does not hide the code after the template. + expect( + optionalFactDefaultCount( + "const s = `${/[/*]/.test(name)}`;\nconst n = report.count ?? 0;", + ), + ).toBe(1); + expect( + optionalFactDefaultCount( + "const s = `${a} and ${/[/*]/.test(b)}`;\nconst n = report.count ?? 0;", + ), + ).toBe(1); + // A complete template ends an operand, so `/` after it divides. + expect( + optionalFactDefaultCount( + "const r = `${a}` / 2; const n = report.count ?? 0; // /", + ), + ).toBe(1); + // A keyword-named property is an operand, so `/` after it divides. + for (const name of ["return", "typeof", "in", "yield"]) + expect( + optionalFactDefaultCount(`const r = row.${name} / (report.count ?? 0);`), + ).toBe(1); + expect( + optionalFactDefaultCount( + "const t = `${{ a: 1 }.a} x ?? 0`; const n = report.count ?? 0;", + ), + ).toBe(1); + expect( + optionalFactDefaultCount( + "const r = total / 2; const n = report.count ?? 0; // /", + ), + ).toBe(1); + // A keyword-named member call's `)` ends an operand, so `/` divides. + expect( + optionalFactDefaultCount( + "const ratio = policy.if(ready) / (report.count ?? 0);", + ), + ).toBe(1); + expect(optionalFactDefaultCount("const n = (report.count ?? 0) + 1;")).toBe( + 1, + ); + expect(optionalFactDefaultCount("const n = report.count ?? 0 + 1;")).toBe(0); + // A tighter operator makes the right operand a computed value. + expect( + optionalFactDefaultCount("const m = report.mask ?? 0 | fallbackMask;"), + ).toBe(0); + expect( + optionalFactDefaultCount("f(report.count ?? 0, other.items ?? [])"), + ).toBe(2); + expect( + optionalFactDefaultCount("const n = cond ? report.count ?? 0 : 1;"), + ).toBe(1); +}); + +it("counts defaults in template substitutions and after postfix updates", () => { + expect(optionalFactDefaultCount("const s = `${report.count ?? 0}`;")).toBe(1); + expect(optionalFactDefaultCount("const s = `${report.count ?? 0\n}`;")).toBe( + 1, + ); + expect( + optionalFactDefaultCount("const ratio = i++ / (report.count ?? 0);"), + ).toBe(1); + expect( + optionalFactDefaultCount("const ratio = i-- / (report.count ?? 0);"), + ).toBe(1); +}); + +it("does not let a nested expression's marker exempt an outer default", () => { + expect( + optionalFactDefaultCount( + "const n = build(\n // optional-fact-default: request default, not an observation\n options.offset ?? 0,\n).count ?? 0;", + ), + ).toBe(1); +}); + +it("exempts a default whose operand starts on an earlier line", () => { + expect( + optionalFactDefaultCount( + "// optional-fact-default: request default, not an observation\nconst offset = getOptions(\n request,\n).offset ?? 0;", + ), + ).toBe(0); + expect( + optionalFactDefaultCount( + "// optional-fact-default: request default, not an observation\nconst offset = pages[\n index\n]?.options.offset ?? 0;", + ), + ).toBe(0); + // Without a marker the same defaults count. + expect( + optionalFactDefaultCount( + "const offset = getOptions(\n request,\n).offset ?? 0;", + ), + ).toBe(1); +}); + +it("loads without installed dependencies, as CI runs it before npm ci", async () => { + const source = await readFile( + new URL( + "../../scripts/verify/optional-fact-default-guard.mjs", + import.meta.url, + ), + "utf8", + ); + expect(source).not.toMatch(/\bfrom\s+["'](?!node:|\.)/u); +}); + +it("selects comparison, coverage and count files only", () => { + expect(isComparisonOrCountFile("src/domain/artifactComparison.ts")).toBe( + true, + ); + expect( + isComparisonOrCountFile("src/domain/process/processCaptureCoverage.ts"), + ).toBe(true); + expect(isComparisonOrCountFile("src/domain/evidence.ts")).toBe(false); +}); diff --git a/tests/evaluation/reasonMarker.test.ts b/tests/evaluation/reasonMarker.test.ts new file mode 100644 index 0000000000..39f76b13a4 --- /dev/null +++ b/tests/evaluation/reasonMarker.test.ts @@ -0,0 +1,109 @@ +import { readFile } from "node:fs/promises"; +import { expect, it } from "vitest"; +import { unmarkedMatchCount } from "../../scripts/verify/reason-marker.mjs"; + +const slice = /\.slice\(\s*0\s*,\s*[A-Z][A-Z0-9_]*\s*\)/gu; +const names = ["generation-cap", "sample-cap"]; +const count = (raw: string) => unmarkedMatchCount(raw, slice, names); + +it("counts an unmarked slice", () => { + expect(count("const a = items.slice(0, MAX);")).toBe(1); +}); + +it("exempts a slice marked above or trailing with a reason", () => { + expect( + count("// generation-cap: suggested checks\nconst a = s.slice(0, MAX);"), + ).toBe(0); + expect( + count( + "// sample-cap: examples;\n// totals are reported\nconst a = s.slice(0, MAX);", + ), + ).toBe(0); + expect(count("const a = s.slice(0, MAX); // sample-cap: examples")).toBe(0); +}); + +it("does not exempt without a reason, an unknown name, or across code", () => { + expect(count("// generation-cap:\nconst a = s.slice(0, MAX);")).toBe(1); + expect(count("// display-cap: short\nconst a = s.slice(0, MAX);")).toBe(1); + expect( + count( + "// generation-cap: suggestions\nconst b = 1;\nconst a = s.slice(0, MAX);", + ), + ).toBe(1); + expect( + count( + "const a = s.slice(0, MAX); // generation-cap: x\nconst b = t.slice(0, MAX);", + ), + ).toBe(1); +}); + +it("ignores marker text in block comments and strings", () => { + expect( + count("const a = s.slice(0, MAX); /* // sample-cap: examples */"), + ).toBe(1); + expect( + count("/*\n// generation-cap: x\n*/\nconst a = s.slice(0, MAX);"), + ).toBe(1); + expect(count('const a = [s.slice(0, MAX), "// sample-cap: examples"];')).toBe( + 1, + ); +}); + +it("reads a reason with quotes and a marker after a string", () => { + expect( + count( + "const a = s.slice(0, MAX); // sample-cap: the file's change lists all", + ), + ).toBe(0); + expect( + count('const a = [s.slice(0, MAX), "//"]; // sample-cap: examples'), + ).toBe(0); +}); + +it("does not count slices inside comments", () => { + expect(count("// s.slice(0, MAX)\n/* t.slice(0, MAX) */")).toBe(0); +}); + +it("reads regular expressions and template substitutions as code", () => { + expect( + count('const re = /"/.test(v); const q = "//"; items.slice(0, MAX);'), + ).toBe(1); + expect( + count( + "const t = `${\n // generation-cap: suggestions\n s.slice(0, MAX)\n}`;", + ), + ).toBe(0); + expect(count("const t = `${/* s.slice(0, MAX) */ 1}`;")).toBe(0); + expect(count("const t = `${s.slice(0, MAX)}`;")).toBe(1); + // A regular expression opening a substitution does not hide later code. + expect( + count("const t = `${/[/*]/.test(v)}`;\nconst kept = items.slice(0, MAX);"), + ).toBe(1); +}); + +it("reads a regular expression after a control head as a statement", () => { + for (const keyword of ["if", "while", "for", "with"]) + expect( + count( + `${keyword} (ready) /[/*]/.test(value) && report(value);\nconst kept = items.slice(0, MAX);`, + ), + ).toBe(1); + // A call's closing parenthesis still ends an operand, so `/` divides. + expect(count("const half = size(a) / 2; /* items.slice(0, MAX) */")).toBe(0); + expect(count("const r = f(a) / g(b); items.slice(0, MAX);")).toBe(1); + // A keyword-named member call is a call: its `)` ends an operand. + for (const call of ["policy.if(ready)", "policy?.for(ready)"]) + expect(count(`const r = ${call} / (w.n); /* items.slice(0, MAX) */`)).toBe( + 0, + ); +}); + +it("loads without installed dependencies, as CI runs it before npm ci", async () => { + for (const module of ["reason-marker.mjs", "source-tokens.mjs"]) { + const source = await readFile( + new URL(`../../scripts/verify/${module}`, import.meta.url), + "utf8", + ); + expect(source).not.toMatch(/\bfrom\s+["'](?!node:|\.)/u); + } +}); diff --git a/tests/evaluation/sourceTokens.test.ts b/tests/evaluation/sourceTokens.test.ts new file mode 100644 index 0000000000..202bf407ae --- /dev/null +++ b/tests/evaluation/sourceTokens.test.ts @@ -0,0 +1,55 @@ +import { expect, it } from "vitest"; +import { blankComments } from "../../scripts/verify/source-tokens.mjs"; + +const cliText = /--pool-policy/gu; +const count = (source: string) => + [...blankComments(source).matchAll(cliText)].length; + +it("keeps code after a string that holds a comment opener", () => { + // Observed in #11477: a glob-like string hid the remediation text after it. + const source = [ + 'const missing = "No lib/*/libapp.so was found";', + 'const remediation = "(CLI --pool-policy JSON)";', + "/** The next budget. */", + "const again = `(CLI --pool-policy JSON)`;", + ].join("\n"); + expect(count(source)).toBe(2); +}); + +it("keeps code after a regular expression or template that holds one", () => { + expect(count('const g = /lib\\/*x/u; const r = "--pool-policy";')).toBe(1); + expect( + count('const t = `${/[/*]/.test(v)}`; const r = "--pool-policy";'), + ).toBe(1); +}); + +it("reads a regular expression after a statement block", () => { + for (const block of [ + "if (ready) {}", + "function f(): T {}", + "x => {}", + "else {}", + ]) + expect( + count( + `${block} /[/*]/.test(v); const r = "--pool-policy"; /* real comment */`, + ), + ).toBe(1); + // An object literal's `}` ends an operand, so `/` after it divides. + expect( + count( + 'const r = { n: 1 } / 2; const h = "--pool-policy"; const g = "a/b";', + ), + ).toBe(1); +}); + +it("blanks line and block comments in place", () => { + const source = + "/* --pool-policy 😀\n block */ const a = 1; // --pool-policy\n// --pool-policy\nconst b = 2;"; + const code = blankComments(source); + expect(code).toHaveLength(source.length); + expect(code.split("\n")).toHaveLength(source.split("\n").length); + expect(count(source)).toBe(0); + expect(code).toContain("const a = 1;"); + expect(code.split("\n")[3]).toBe("const b = 2;"); +});