diff --git a/scripts/verify/architecture-guard-baselines.json b/scripts/verify/architecture-guard-baselines.json index f35233f4b6..ac8a63863a 100644 --- a/scripts/verify/architecture-guard-baselines.json +++ b/scripts/verify/architecture-guard-baselines.json @@ -502,5 +502,18 @@ "src/ghidra/extensions/GhidraExtensions.ts": 1, "src/ghidra/extensions/nativeaot/NativeAotReport.ts": 1, "src/javascript/analysis/JavaScriptAnalysisWorkerSchemas.ts": 2 + }, + "local-limit-error-class": { + "src/artifacts/apple/InterfaceBuilderDecodeBudget.ts": 1, + "src/browser/WebSourceMapFetcher.ts": 1, + "src/captures/parseFieldDiscovery.ts": 1, + "src/domain/analysisView/EnvironmentStateExtraction.ts": 1, + "src/domain/native/nativeAotPe.ts": 1, + "src/firmware/devicetree/DevicetreeParser.ts": 1, + "src/native/elf/ElfNoteParser.ts": 1, + "src/process/OwnedMcpStdioTransport.ts": 1, + "src/signals/SigrokRecordingProvider.ts": 1, + "src/signals/parseDecoderDiscovery.ts": 1, + "src/v8/V8CodeCache.errors.ts": 1 } } diff --git a/scripts/verify/architecture-guards.mjs b/scripts/verify/architecture-guards.mjs index 4d648bf311..2fe82b20a2 100644 --- a/scripts/verify/architecture-guards.mjs +++ b/scripts/verify/architecture-guards.mjs @@ -9,6 +9,7 @@ import { } from "./counted-baseline.mjs"; import { localCompletenessEnumCount } from "./completeness-enum-guard.mjs"; import { countKeyedFirstMatches } from "./keyed-first-match.mjs"; +import { localLimitErrorClassCount } from "./limit-class-guard.mjs"; // Architecture guards for the strict-identity / best-effort-inference split. // - Composite dedup keys must not NUL-join variable-length or free-form @@ -328,6 +329,17 @@ checkCounted( ["src/domain/analysisErrorCore.ts"], ); +// A limit a parser stopped at is a ParseFailureError<"limit"> (decodeLimit in +// src/domain/parseFailure); a refusal is an AnalysisRefusal. A local limit +// class on plain Error hides the limit's name and maximum from both. +checkCounted( + "local limit class extending plain Error (use decodeLimit from src/domain/parseFailure or an AnalysisRefusal)", + "local-limit-error-class", + files, + localLimitErrorClassCount, + [], +); + // A deadline is a monotonic budget owned by `Deadline` in src/domain/deadline; // a wall-clock sum moves with clock changes and has no finalize phase. The // remaining copy converts a monotonic budget for a browser page, which can diff --git a/scripts/verify/limit-class-guard.d.mts b/scripts/verify/limit-class-guard.d.mts new file mode 100644 index 0000000000..2aa7a7d9d4 --- /dev/null +++ b/scripts/verify/limit-class-guard.d.mts @@ -0,0 +1 @@ +export function localLimitErrorClassCount(content: string): number; diff --git a/scripts/verify/limit-class-guard.mjs b/scripts/verify/limit-class-guard.mjs new file mode 100644 index 0000000000..1a39b39e2b --- /dev/null +++ b/scripts/verify/limit-class-guard.mjs @@ -0,0 +1,10 @@ +// Counts local limit classes declared on plain Error: a class whose name has +// Limit, Budget, Exhausted or Exceeded and that extends Error directly. Type +// parameters and line breaks between tokens are allowed, as a formatter or a +// generic declaration may write them. +const localLimitClass = + /\bclass\s+\w*(?:Limit|Budget|Exhausted|Exceeded)\w*\s*(?:<[^{]*?>)?\s*extends\s+Error\b/gu; + +/** @param {string} content */ +export const localLimitErrorClassCount = (content) => + content.match(localLimitClass)?.length ?? 0; diff --git a/src/gpu/GpuInventory.ts b/src/gpu/GpuInventory.ts index 4574a179c1..2725ba83ee 100644 --- a/src/gpu/GpuInventory.ts +++ b/src/gpu/GpuInventory.ts @@ -21,7 +21,7 @@ import type { import { BinaryFormatFailure, BinaryResourceFailure, - BinaryStringReadLimitFailure, + isBinaryStringReadLimit, } from "../native/metadata/BinaryContainer.js"; import { readElfSectionDirectory, @@ -288,19 +288,14 @@ export class GpuInventory { } #retainFailure(row: GpuObject, cause: unknown): void { if (cause instanceof GpuReportCapacityFailure) throw cause; - if ( - !(cause instanceof BinaryFormatFailure) && - !(cause instanceof BinaryResourceFailure) && - !(cause instanceof BinaryStringReadLimitFailure) - ) - throw cause; - row.inspection = - cause instanceof BinaryResourceFailure || - cause instanceof BinaryStringReadLimitFailure - ? "capacity" - : cause.kind === "unsupported" - ? "unsupported" - : "malformed"; + const capacity = + cause instanceof BinaryResourceFailure || isBinaryStringReadLimit(cause); + if (!capacity && !(cause instanceof BinaryFormatFailure)) throw cause; + row.inspection = capacity + ? "capacity" + : cause.kind === "unsupported" + ? "unsupported" + : "malformed"; this.#objectLimitations(row, [cause.message]); } async #payload( diff --git a/src/native/android/AndroidJniLibrary.ts b/src/native/android/AndroidJniLibrary.ts index 874582873c..b1359ed531 100644 --- a/src/native/android/AndroidJniLibrary.ts +++ b/src/native/android/AndroidJniLibrary.ts @@ -15,7 +15,7 @@ import { BinaryFormatFailure, BinaryMappingFailure, BinaryResourceFailure, - BinaryStringReadLimitFailure, + isBinaryStringReadLimit, createFileMappingIndex, } from "../metadata/BinaryContainer.js"; import { @@ -303,11 +303,11 @@ export const inspectAndroidJniLibrary = async ( if (cause instanceof BinaryMappingFailure) { if (cause.reason !== "unmapped") throw cause; stringWork += scanned ? allowance + 1 : 1; - } else if (cause instanceof BinaryStringReadLimitFailure) { + } else if (isBinaryStringReadLimit(cause)) { stringWork += allowance + 1; tablesStatus = "partial"; unknowns.add( - `Some JNI candidate strings exceeded the ${cause.maximumBytes}-byte NUL-termination read allowance; omitted entries remain unknown`, + `Some JNI candidate strings exceeded the ${String(cause.failure.limit.maximum)}-byte NUL-termination read allowance; omitted entries remain unknown`, ); } else if (cause instanceof BinaryFormatFailure) { // Unterminated source bytes also consume their actual scan allowance. diff --git a/src/native/exports/NativeExportParser.ts b/src/native/exports/NativeExportParser.ts index 783a639c80..708f890bb7 100644 --- a/src/native/exports/NativeExportParser.ts +++ b/src/native/exports/NativeExportParser.ts @@ -3,7 +3,7 @@ import { BinaryReader, BinaryResourceFailure, isBinaryFormatOrStringLimitFailure, - type BinaryStringReadLimitFailure, + type BinaryStringReadLimit, mappedFileOffset, imageFileMappings, readMappedCString, @@ -409,7 +409,7 @@ const createVersionNameReader = () => { const decodedNames = new Map< string, | { readonly value: DecodedElfString | null } - | { readonly failure: BinaryFormatFailure | BinaryStringReadLimitFailure } + | { readonly failure: BinaryFormatFailure | BinaryStringReadLimit } >(); let cacheBytes = 0; const chargeCache = (bytes: number): void => { diff --git a/src/native/metadata/BinaryContainer.test.ts b/src/native/metadata/BinaryContainer.test.ts index 677bfff8e4..d9c161f6a1 100644 --- a/src/native/metadata/BinaryContainer.test.ts +++ b/src/native/metadata/BinaryContainer.test.ts @@ -8,7 +8,7 @@ import { BinaryFormatFailure, BinaryMappingFailure, BinaryReader, - BinaryStringReadLimitFailure, + isBinaryStringReadLimit, createFileMappingIndex, mappedFileOffset, readMappedCString, @@ -47,8 +47,10 @@ it("distinguishes a mapped string read allowance from malformed bytes", () => { } catch (cause) { failure = cause; } - expect(failure).toBeInstanceOf(BinaryStringReadLimitFailure); - expect(failure).toMatchObject({ maximumBytes: 3 }); + expect(isBinaryStringReadLimit(failure)).toBe(true); + expect(failure).toMatchObject({ + failure: { kind: "limit", limit: { maximum: 3 } }, + }); expect(index.readCString(bytes, 100n, bytes.length).toString()).toBe( "long-name", ); diff --git a/src/native/metadata/BinaryContainer.ts b/src/native/metadata/BinaryContainer.ts index 2347806cc2..21faf80481 100644 --- a/src/native/metadata/BinaryContainer.ts +++ b/src/native/metadata/BinaryContainer.ts @@ -4,7 +4,7 @@ import { type ZeroFillMapping, } from "../../domain/virtualFileMapping.js"; import type { PeDataDirectory } from "../../domain/peOptionalHeader.js"; -import { ParseFailureError } from "../../domain/parseFailure.js"; +import { decodeLimit, ParseFailureError } from "../../domain/parseFailure.js"; /** Native container facts a format failure can name. */ interface BinaryFormatFailureFacts { @@ -67,22 +67,35 @@ export class BinaryResourceFailure extends ParseFailureError<"limit"> { } } -/** A bounded read could not establish termination; it does not prove invalid text. */ -export class BinaryStringReadLimitFailure extends Error { - constructor(readonly maximumBytes: number) { - super( - `String termination was not established within its ${String(maximumBytes)}-byte read allowance`, - ); - this.name = "BinaryStringReadLimitFailure"; - } -} +/** Limit name of the fixed per-string NUL-termination read allowance. */ +const STRING_READ_LIMIT = "string-read-bytes"; + +/** A string read stopped at its allowance; this does not prove invalid text. */ +export type BinaryStringReadLimit = ParseFailureError<"limit">; + +/** A bounded read could not establish termination within `maximumBytes`. */ +export const binaryStringReadLimit = ( + maximumBytes: number, +): BinaryStringReadLimit => + decodeLimit( + "native-binary", + `String termination was not established within its ${String(maximumBytes)}-byte read allowance`, + { name: STRING_READ_LIMIT, maximum: maximumBytes }, + ); + +/** Whether a cause is a string read that stopped at its allowance. */ +export const isBinaryStringReadLimit = ( + cause: unknown, +): cause is BinaryStringReadLimit => + cause instanceof ParseFailureError && + cause.failure.kind === "limit" && + cause.failure.limit.name === STRING_READ_LIMIT; /** Recognized format failures and bounded string-read failures. */ export const isBinaryFormatOrStringLimitFailure = ( cause: unknown, -): cause is BinaryFormatFailure | BinaryStringReadLimitFailure => - cause instanceof BinaryFormatFailure || - cause instanceof BinaryStringReadLimitFailure; +): cause is BinaryFormatFailure | BinaryStringReadLimit => + cause instanceof BinaryFormatFailure || isBinaryStringReadLimit(cause); /** Native loader region facts; language-specific fallback selection belongs to consumers. */ export interface LoadRegion { @@ -591,7 +604,7 @@ const readMappedString = ( chunks.push(chunk); length += size; } - throw new BinaryStringReadLimitFailure(maximumBytes); + throw binaryStringReadLimit(maximumBytes); }; /** Recognize a wholly zero-filled span while refusing even partial file aliases. */ diff --git a/src/native/metadata/ElfStringTable.test.ts b/src/native/metadata/ElfStringTable.test.ts index 11a25d70ad..250f877955 100644 --- a/src/native/metadata/ElfStringTable.test.ts +++ b/src/native/metadata/ElfStringTable.test.ts @@ -1,7 +1,7 @@ import { expect, it } from "vitest"; import { BinaryFormatFailure, - BinaryStringReadLimitFailure, + isBinaryStringReadLimit, } from "./BinaryContainer.js"; import { readElfStringBytes } from "./ElfStringTable.js"; @@ -36,9 +36,11 @@ it.each([65_536, 70_000])( } catch (cause) { failure = cause; } - expect(failure).toBeInstanceOf(BinaryStringReadLimitFailure); + expect(isBinaryStringReadLimit(failure)).toBe(true); expect(failure).not.toBeInstanceOf(BinaryFormatFailure); - expect(failure).toMatchObject({ maximumBytes: 65_536 }); + expect(failure).toMatchObject({ + failure: { kind: "limit", limit: { maximum: 65_536 } }, + }); }, ); @@ -47,9 +49,6 @@ it.each([3, 65_536])( (size) => { const table = Buffer.alloc(size, 0x61); expect(() => readElfStringBytes(table, 0)).toThrow(BinaryFormatFailure); - expect(() => readElfStringBytes(table, 0)).not.toThrow( - BinaryStringReadLimitFailure, - ); }, ); @@ -57,7 +56,4 @@ it.each([-1, 1])("keeps an out-of-table offset %i malformed", (offset) => { expect(() => readElfStringBytes(Buffer.from([0]), offset)).toThrow( BinaryFormatFailure, ); - expect(() => readElfStringBytes(Buffer.from([0]), offset)).not.toThrow( - BinaryStringReadLimitFailure, - ); }); diff --git a/src/native/metadata/ElfStringTable.ts b/src/native/metadata/ElfStringTable.ts index 5386bd84cd..44d434cadf 100644 --- a/src/native/metadata/ElfStringTable.ts +++ b/src/native/metadata/ElfStringTable.ts @@ -1,7 +1,7 @@ import { observeElfStringTableEntry } from "../../domain/elfStringTable.js"; import { BinaryFormatFailure, - BinaryStringReadLimitFailure, + binaryStringReadLimit, } from "./BinaryContainer.js"; /** Read exact string-table bytes; ELF does not prescribe a character encoding. */ @@ -14,7 +14,7 @@ export const readElfStringBytes = (bytes: Buffer, offset: number): Buffer => { ); if (observed.state === "truncated") { if (offset + observed.examinedBytes < bytes.length) - throw new BinaryStringReadLimitFailure(observed.examinedBytes); + throw binaryStringReadLimit(observed.examinedBytes); throw new BinaryFormatFailure( "malformed", "ELF string is unterminated inside its string table", diff --git a/tests/evaluation/limitClassGuard.test.ts b/tests/evaluation/limitClassGuard.test.ts new file mode 100644 index 0000000000..bd0a5424ee --- /dev/null +++ b/tests/evaluation/limitClassGuard.test.ts @@ -0,0 +1,35 @@ +import { expect, it } from "vitest"; +import { localLimitErrorClassCount } from "../../scripts/verify/limit-class-guard.mjs"; + +it("counts plain-Error limit classes in every layout", () => { + expect( + localLimitErrorClassCount("class ProbeLimitFailure extends Error {}"), + ).toBe(1); + expect( + localLimitErrorClassCount( + "export class ProbeBudgetError extends Error {}", + ), + ).toBe(1); + expect( + localLimitErrorClassCount( + "class ProbeExhausted>\n extends Error {}", + ), + ).toBe(1); + expect( + localLimitErrorClassCount("class ProbeExceeded\n extends Error {}"), + ).toBe(1); +}); + +it("ignores classes on the shared owners and unrelated names", () => { + expect( + localLimitErrorClassCount( + 'class ProbeLimit extends ParseFailureError<"limit"> {}', + ), + ).toBe(0); + expect(localLimitErrorClassCount("class ProbeFailure extends Error {}")).toBe( + 0, + ); + expect( + localLimitErrorClassCount("class ProbeLimit extends ErrorBase {}"), + ).toBe(0); +});