agent-sanitizer 2.60.3 → 2.61.1

package/types/layer1.d.mts

@@ -53,16 +53,24 @@ export function isBenignAnsiKinds(kinds: readonly string[] | Set<string>): boole
 /**
  * True when the SGR sequences in `text` do more than style visible text — the
  * question a consumer must answer before PRESERVING escapes rather than
- * stripping them. Two arms, both model-sees/human-sees divergences:
+ * stripping them. Three arms, all model-sees/human-sees divergences:
  *
- *   1. CONCEAL is on while text that would otherwise render goes by, or the text
- *      ENDS concealed (hiding its own tail, and everything the terminal prints
- *      afterwards). Only SGR moves that state (see {@link sgrConcealState}) — a
- *      cursor move or an erase leaves a terminal exactly as concealed as it was.
- *   2. {@link SGR_RUN_THRESHOLD} sequences with nothing that renders between
+ *   1. CONCEAL is on while text that would otherwise render goes by. Only SGR
+ *      moves that state (see {@link sgrRendition}) — a cursor move or an erase
+ *      leaves a terminal exactly as concealed as it was.
+ *   2. The foreground is the background while a glyph goes by (`ESC[30;40m`):
+ *      concealment by colour, judged only where the match is unambiguous (see
+ *      {@link foregroundMatchesBackground}). Block Elements are the one
+ *      exception judged across the whole text rather than per glyph (see
+ *      {@link drawsSecondBlockElement}).
+ *   3. {@link SGR_RUN_THRESHOLD} sequences with nothing that renders between
  *      them: the run puts no glyph on the screen, so it carries data rather than
  *      styling.
  *
+ * Either still in force when the text ENDS is a refusal too: rendition
+ * outlives its bytes, so a file ending in `ESC[8m` blanks whatever the terminal
+ * prints after it.
+ *
  * What it does NOT claim: a message spread thinly through legitimately coloured
  * text — one sequence per line, say — is indistinguishable from styling, and
  * this answers no for it. That is the same bargain the invisible layer's
@@ -85,6 +93,26 @@ export function sgrCarriesPayload(text: string): boolean;
  * @returns {boolean}
  */
 export function isBenignAnsi(text: string): boolean;
+/**
+ * True when the escapes in `text` may be let through: every removed kind is
+ * inert ({@link isBenignAnsiKinds}) AND the SGR is just styling
+ * ({@link sgrCarriesPayload}). THE answer for every surface that preserves
+ * escapes, so `ESC[8m` cannot be inert to one and hiding text in another.
+ * @param {string} text  the raw text, as a terminal would receive it
+ * @param {Iterable<string>} [kinds]  the {@link TOKEN_KIND}s a strip of `text`
+ *   removed, when the caller already has them; defaults to Layer 1's
+ * @returns {boolean}
+ */
+export function escapesPreservable(text: string, kinds?: Iterable<string>): boolean;
+/**
+ * Remove every complete ANSI sequence and then every raw control introducer
+ * left over. The output holds no introducer, so no later pass can find an
+ * escape in it: a fixed point by construction.
+ * @param {string} text
+ * @param {Set<string>} [kinds]  collects the {@link TOKEN_KIND} of every removal
+ * @returns {string}
+ */
+export function stripTerminalFully(text: string, kinds?: Set<string>): string;
 /**
  * Layer 1: ANSI + invisible-char strip with a result guaranteed free of every
  * raw ANSI control introducer (7-bit ESC U+001B and the whole 8-bit C1 control
@@ -103,9 +131,10 @@ export function isBenignAnsi(text: string): boolean;
  *
  * The residual sweep runs only once the composition is STABLE, because sweeping
  * an introducer early destroys the sequence a later ANSI pass would have removed
- * whole, promoting a hidden control to visible text. A final UNCONDITIONAL sweep
- * follows the loop so the no-raw-introducer guarantee does not depend on the
- * pass bound.
+ * whole, promoting a hidden control to visible text. A composition that has not
+ * converged within the pass bound falls back to a carve-out-free strip whose
+ * output holds no invisible and no introducer, so both the no-raw-introducer
+ * guarantee and idempotence hold whatever the bound.
  *
  * `deAnsi` is the ANSI strip of the ORIGINAL text (invisible runs intact), the
  * scope a LONG_RUN payload check needs — not an intermediate of the loop.
@@ -187,3 +216,4 @@ export const INERT_ANSI_NOTE: string;
  * threshold and sits well above what a real emitter chains.
  */
 export const SGR_RUN_THRESHOLD: 10;
+export type SgrRendition = import("./ansi.mjs").SgrRendition;

package/types/src/ansi.d.mts

@@ -49,15 +49,12 @@ export function isCancelledOrphan(text: string, token: AnsiToken): boolean;
  */
 export function scanAnsi(text: string): AnsiToken[];
 /**
- * The CONCEAL state after the SGR token `token` is applied to a terminal already
- * in state `concealed` — the state in which a terminal renders what follows as
- * blank while its bytes stay readable to anything reading the file.
+ * The rendition after the SGR token `token` is applied to a terminal already in
+ * `state`.
  *
- * A TRANSITION, not a property of the token: conceal is terminal state that
+ * A TRANSITION, not a property of the token: rendition is terminal state that
  * outlives the sequence that set it, so `ESC[8m` followed by `ESC[31m` is still
- * concealed — a per-token predicate would read the second token as "no conceal
- * here" and lose the state. Only `8` (set), `28` (reveal) and `0` (reset all)
- * move it, and the token's parameters are applied in order, so a later reveal or
+ * concealed. The token's parameters are applied in order, so a later reveal or
  * reset in the SAME token cancels an earlier `8`: `ESC[8;28;31m` renders red and
  * visible.
  *
@@ -65,18 +62,26 @@ export function scanAnsi(text: string): AnsiToken[];
  * the digit. `38`/`48`/`58` take their colour arguments from the parameters that
  * FOLLOW them in the semicolon form, so `ESC[38;5;8m` is bright-black foreground
  * and its `8` is a palette index; a parameter carrying its arguments as ITU T.416
- * sub-parameters (`38:5:8`) is self-contained, so only its head counts and
- * nothing after it is consumed. A colour-space selector T.416 gives no argument
- * count for is malformed, and a terminal that ignores the colour form still
- * applies what follows it, so the scan CONTINUES from the next parameter rather
- * than consuming arguments it cannot size — reading one parameter too many costs
- * a token shape no emitter produces, while stopping there would hand
- * `ESC[38;9;8m` a pass.
+ * sub-parameters (`38:5:8`) is self-contained, so nothing after it is consumed.
+ * A colour-space selector T.416 gives no argument count for is malformed, and a
+ * terminal that ignores the colour form still applies what follows it, so the
+ * scan CONTINUES from the next parameter rather than consuming arguments it
+ * cannot size — stopping there would hand `ESC[38;9;8m` a pass.
  * @param {string} token  a token {@link scanAnsi} classified {@link TOKEN_KIND.SGR}
- * @param {boolean} concealed  the state before this token
+ * @param {Readonly<SgrRendition>} state  the rendition before this token
+ * @returns {SgrRendition}
+ */
+export function sgrRendition(token: string, state: Readonly<SgrRendition>): SgrRendition;
+/**
+ * True when text drawn in `rendition` is invisible to a human because its
+ * foreground IS its background (`ESC[30;40m`, `ESC[38;5;7;48;5;7m`). Only an
+ * unambiguous match counts: a default colour is unknown, so it matches nothing,
+ * and BOLD over a basic colour is drawn brighter by many terminals, so
+ * `ESC[1;30;40m` is not called hidden — the precision direction.
+ * @param {Readonly<SgrRendition>} rendition
  * @returns {boolean}
  */
-export function sgrConcealState(token: string, concealed: boolean): boolean;
+export function foregroundMatchesBackground({ bold, fg, bg }: Readonly<SgrRendition>): boolean;
 /**
  * The ONE ANSI grammar: the raw control-introducer charset and the tokenizer
  * every consumer scans with.
@@ -170,6 +175,17 @@ export const TOKEN_KIND: Readonly<{
      */
     ORPHAN_C1: "orphan-c1-introducer";
 }>;
+/**
+ * What a terminal's graphic rendition looks like after an SGR token: whether
+ * CONCEAL is on, whether BOLD is (which many terminals render as a brighter
+ * foreground), and the foreground/background colour as a comparable key — `i<n>`
+ * for a palette index (`31` and `38;5;1` are both `i1`), `rgb:<r>,<g>,<b>` for
+ * direct colour, `null` for the default or a colour this reader cannot size.
+ * @typedef {{ concealed: boolean, bold: boolean, fg: string | null, bg: string | null }} SgrRendition
+ */
+/** The rendition of a terminal no SGR has touched (and of `ESC[0m`).
+ * @type {Readonly<SgrRendition>} */
+export const DEFAULT_RENDITION: Readonly<SgrRendition>;
 export type AnsiToken = {
     /**
      * Index of the introducer.
@@ -184,3 +200,16 @@ export type AnsiToken = {
      */
     kind: string;
 };
+/**
+ * What a terminal's graphic rendition looks like after an SGR token: whether
+ * CONCEAL is on, whether BOLD is (which many terminals render as a brighter
+ * foreground), and the foreground/background colour as a comparable key — `i<n>`
+ * for a palette index (`31` and `38;5;1` are both `i1`), `rgb:<r>,<g>,<b>` for
+ * direct colour, `null` for the default or a colour this reader cannot size.
+ */
+export type SgrRendition = {
+    concealed: boolean;
+    bold: boolean;
+    fg: string | null;
+    bg: string | null;
+};

package/types/src/cf-charset.d.mts

@@ -1,14 +1,14 @@
 /**
- * GENERATED by scripts/gen-invisible-charset.mjs from Node's Unicode data
- * (\p{Cf}, Unicode 17.0) — DO NOT EDIT.
+ * GENERATED by scripts/gen-invisible-charset.mjs from the pinned UCD
+ * (General_Category=Cf, Unicode 17.0.0) — DO NOT EDIT.
  *
  * The general-category Cf code points, PINNED at generation time. invisible.mjs
- * strips exactly this set instead of testing \p{Cf} live, and the Python port
+ * strips exactly this set instead of asking the runtime for Cf, and the Python port
  * reads the SAME set from data/invisible-charset.json's `cf_codepoints`, so both
  * layers strip an identical Cf set regardless of each runtime's own Unicode
  * version. Regenerate with `node scripts/gen-invisible-charset.mjs`;
- * test/invisible-charset.test.mjs fails if this drifts from Node's \p{Cf}.
+ * test/invisible-charset.test.mjs fails if this drifts from the pinned UCD.
  */
-export const UNICODE_VERSION: "17.0";
+export const UNICODE_VERSION: "17.0.0";
 /** @type {readonly number[]} Sorted ascending. */
 export const CF_CODEPOINTS: readonly number[];

package/types/src/instructions.d.mts

@@ -14,9 +14,13 @@ export function decodeRun(run: string): {
     decoded: string;
 };
 /**
- * Scan a file's text for hidden-Unicode injection. Reports each long invisible
+ * Scan a file's text for hidden-Unicode injection. Reports each payload long
  * run (with its decoded payload) plus a single scattered-chars finding when the
- * non-run invisible count crosses the threshold-evasion floor.
+ * effective invisible count outside those runs crosses the threshold-evasion
+ * floor.
+ *
+ * Whether there is anything to report is {@link payloadVerdict}'s call, the
+ * one every other surface makes.
  * @param {string} content
  * @returns {Array<{ line: number | null, charCount: number, method: string, decoded: string }>}
  *   `line` is the 1-based line of a long-run finding, or `null` for the

package/types/src/invisible.d.mts

@@ -68,11 +68,13 @@ export function describeStripped(invisFound: string[], deAnsi: string): string;
  */
 export function countPayloadInvisible(text: string): number;
 /**
- * The `text` with every carve-out-PRESERVABLE invisible (joiners/selectors/tags/
- * blank fillers doing real rendering work) replaced by a space, leaving only the
- * PAYLOAD invisibles in place. The LONG_RUN injection probe runs over this so a
- * legitimate emoji/flag/variation sequence never trips the "possible injection
- * payload" marker (alert fatigue), while a genuine hidden run still surfaces.
+ * The `text` with every visible character and every carve-out-PRESERVABLE
+ * invisible (joiners/selectors/tags/blank fillers doing real rendering work)
+ * replaced by spaces — one per UTF-16 unit, so the view is index-aligned with
+ * `text` — leaving only the PAYLOAD invisibles in place. The LONG_RUN injection
+ * probe runs over this so a legitimate emoji/flag/variation sequence never trips
+ * the "possible injection payload" marker (alert fatigue), while a genuine
+ * hidden run still surfaces.
  * @param {string} text
  * @returns {string}
  */
@@ -143,6 +145,25 @@ export function countEffectiveInvisible(text: string): number;
  * @returns {boolean}
  */
 export function isIncidentalInvisible(text: string): boolean;
+/**
+ * THE decision whether `text` carries a payload-capable invisible channel: a
+ * payload LONG RUN, or {@link SCATTERED_THRESHOLD} or more effective payload
+ * invisibles. Every gate reads this one verdict, so a Persian paragraph cannot
+ * be a payload to one and clean to another. It stops at the first run, so an
+ * 8 MB field of short runs costs one record.
+ * @param {string} text  the text a consumer acts on, ANSI-stripped where its
+ *   surface can carry escapes (a sequence can hide invisibles)
+ * @returns {{ firstRun: { index: number, text: string, charCount: number } | null, invisibleCount: number, payloadCapable: boolean }}
+ */
+export function payloadVerdict(text: string): {
+    firstRun: {
+        index: number;
+        text: string;
+        charCount: number;
+    } | null;
+    invisibleCount: number;
+    payloadCapable: boolean;
+};
 /**
  * Strip payload-capable invisible chars and report which categories were
  * removed. A single leading U+FEFF (BOM) is preserved as a legitimate marker;
@@ -155,11 +176,17 @@ export function isIncidentalInvisible(text: string): boolean;
  * decide whether a leading BOM is genuinely leading: an interior BOM that an
  * ANSI-strip left at index 0 of `text` (e.g. `ESC[m + interior U+FEFF`) must NOT be treated as a
  * legitimate leading marker. Defaults to `text` for the common single-arg call.
+ *
+ * `carveOut: false` strips EVERY payload-capable invisible, preserved ones
+ * included — the monotone fallback for a composition that fails to converge.
  * @param {string} text
  * @param {string} [originalText]
+ * @param {{ carveOut?: boolean }} [options]
  * @returns {{ cleaned: string, found: string[] }}
  */
-export function stripInvisibleWithReport(text: string, originalText?: string): {
+export function stripInvisibleWithReport(text: string, originalText?: string, { carveOut }?: {
+    carveOut?: boolean;
+}): {
     cleaned: string;
     found: string[];
 };
@@ -215,3 +242,31 @@ export const TOTAL_PRESERVED_BLANK_BUDGET: 16;
 export const PRESERVED_BLANK_PER_ANCHOR: 2;
 export const LINGUISTIC_SCRIPTS: string[];
 export { BRAHMIC_CONSONANT_RANGES } from "./joining-type.mjs";
+export type CarveEntry = {
+    body: string;
+    cps: Int32Array;
+    analysis: ReturnType<typeof analyzeCarve>;
+    strip: {
+        cleaned: string;
+        found: string[];
+        removed: number;
+    } | null;
+    removed: number | null;
+};
+/**
+ * Per-invisible carve-out analysis, shared by carveStrip and
+ * countPayloadInvisible: for each code point, its CODE_* class (CODE_VISIBLE
+ * when visible) and its preserve KIND_* (KIND_NONE when the char is payload).
+ * Everything invisible that is NOT preserve-eligible is payload; the scatter
+ * floor counts only that, so meaningful joiners/selectors never push honest
+ * prose over the threshold.
+ * @param {Int32Array} cps
+ * @returns {{ codes: Uint8Array, kind: Uint8Array, invisible: Int32Array, payloadInvis: number, visibleLen: number }}
+ */
+declare function analyzeCarve(cps: Int32Array): {
+    codes: Uint8Array;
+    kind: Uint8Array;
+    invisible: Int32Array;
+    payloadInvis: number;
+    visibleLen: number;
+};

package/types/src/joining-type.d.mts

@@ -15,13 +15,16 @@ export function isVirama(cp: number): boolean;
 /**
  * True when `cp` is a Brahmic consonant — the only base a virama attaches to,
  * and therefore the only base after which a ZWJ/ZWNJ is a real conjunct
- * request rather than a zero-width payload.
+ * request rather than a zero-width payload. A binary search, like
+ * `lookup`: the spans are sorted and disjoint, and the carve analysis asks
+ * this of every visible code point of a long document, where a scan of all the
+ * spans per code point was the dominant cost.
  * @param {number} cp
  * @returns {boolean}
  */
 export function isBrahmicConsonant(cp: number): boolean;
 /**
- * GENERATED by scripts/gen-joining-type.mjs from ucd-full@17.0.0 — DO NOT EDIT.
+ * GENERATED by scripts/gen-joining-type.mjs from the pinned UCD 17.0.0 — DO NOT EDIT.
  *
  * Unicode Joining_Type, Indic virama and Brahmic consonant range tables backing
  * the ZWNJ/ZWJ carve-out in invisible.mjs. Regenerate with `pnpm gen:joining-type`;

package/types/src/standardized-variants.d.mts

@@ -1,6 +1,6 @@
 /**
- * True when `base` followed by `selector` (a U+FE00–U+FE0D code point) is a
- * registered standardized variation sequence.
+ * True when `base` followed by `selector` is a registered standardized
+ * variation sequence.
  * @param {number} base
  * @param {number} selector
  * @returns {boolean}
@@ -10,12 +10,12 @@ export function isStandardizedVariant(base: number, selector: number): boolean;
  * GENERATED by scripts/gen-standardized-variants.mjs from UCD
  * StandardizedVariants.txt (Unicode 17.0.0) — DO NOT EDIT.
  *
- * Registered standardized variation sequences: a base code point followed by a
- * variation selector in U+FE00–U+FE0D. invisible.mjs preserves such a selector
- * only when the immediately preceding base appears here; every other FE00–FE0D
- * selector is stripped as a hidden-payload byte. Regenerate with
- * `node scripts/gen-standardized-variants.mjs`; test/invisible-charset.test.mjs
- * fails if this drifts from the pinned UCD slice.
+ * Registered standardized variation sequences: a base code point followed by the
+ * variation selector the UCD registers for it. invisible.mjs preserves such a
+ * selector only when the immediately preceding base appears here; every other
+ * one is stripped as a hidden-payload byte. Regenerate with
+ * `node scripts/gen-standardized-variants.mjs`;
+ * test/invisible-charset.test.mjs fails if this drifts from the pinned UCD.
  */
 export const UNICODE_VERSION: "17.0.0";
 /** @type {Array<[number, number]>} [base, selector], sorted by base then selector. */

package/types/src/unicode-properties.d.mts

@@ -0,0 +1,29 @@
+/**
+ * True when `cp` lies in one of `spans` (sorted, non-overlapping). A negative
+ * `cp` — the "no neighbour" sentinel — lies in none.
+ * @param {ReadonlyArray<readonly [number, number]>} spans
+ * @param {number} cp
+ * @returns {boolean}
+ */
+export function inSpans(spans: ReadonlyArray<readonly [number, number]>, cp: number): boolean;
+/**
+ * GENERATED by scripts/gen-unicode-properties.mjs from the pinned UCD 17.0.0 — DO NOT EDIT.
+ *
+ * The Unicode properties src/invisible.mjs's carve-out reads, PINNED so the
+ * carve-out answers the same on every Node whatever its ICU's Unicode version.
+ * Regenerate with `node scripts/gen-unicode-properties.mjs`;
+ * test/unicode-properties.test.mjs fails if this drifts from the pinned package.
+ */
+export const UNICODE_VERSION: "17.0.0";
+/** @type {ReadonlyArray<readonly [number, number]>} */
+export const EXTENDED_PICTOGRAPHIC: ReadonlyArray<readonly [number, number]>;
+/** @type {ReadonlyArray<readonly [number, number]>} */
+export const EMOJI_MODIFIER: ReadonlyArray<readonly [number, number]>;
+/** @type {ReadonlyArray<readonly [number, number]>} */
+export const EMOJI_TEXT_DEFAULT: ReadonlyArray<readonly [number, number]>;
+/** @type {ReadonlyArray<readonly [number, number]>} */
+export const UNIFIED_IDEOGRAPH: ReadonlyArray<readonly [number, number]>;
+/** @type {ReadonlyArray<readonly [number, number]>} */
+export const SCRIPT_BRAILLE: ReadonlyArray<readonly [number, number]>;
+/** @type {ReadonlyArray<readonly [number, number]>} */
+export const SCRIPT_HANGUL: ReadonlyArray<readonly [number, number]>;

package/types/standardized-variants.d.mts

@@ -1,6 +1,6 @@
 /**
- * True when `base` followed by `selector` (a U+FE00–U+FE0D code point) is a
- * registered standardized variation sequence.
+ * True when `base` followed by `selector` is a registered standardized
+ * variation sequence.
  * @param {number} base
  * @param {number} selector
  * @returns {boolean}
@@ -10,12 +10,12 @@ export function isStandardizedVariant(base: number, selector: number): boolean;
  * GENERATED by scripts/gen-standardized-variants.mjs from UCD
  * StandardizedVariants.txt (Unicode 17.0.0) — DO NOT EDIT.
  *
- * Registered standardized variation sequences: a base code point followed by a
- * variation selector in U+FE00–U+FE0D. invisible.mjs preserves such a selector
- * only when the immediately preceding base appears here; every other FE00–FE0D
- * selector is stripped as a hidden-payload byte. Regenerate with
- * `node scripts/gen-standardized-variants.mjs`; test/invisible-charset.test.mjs
- * fails if this drifts from the pinned UCD slice.
+ * Registered standardized variation sequences: a base code point followed by the
+ * variation selector the UCD registers for it. invisible.mjs preserves such a
+ * selector only when the immediately preceding base appears here; every other
+ * one is stripped as a hidden-payload byte. Regenerate with
+ * `node scripts/gen-standardized-variants.mjs`;
+ * test/invisible-charset.test.mjs fails if this drifts from the pinned UCD.
  */
 export const UNICODE_VERSION: "17.0.0";
 /** @type {Array<[number, number]>} [base, selector], sorted by base then selector. */

package/types/unicode-properties.d.mts

@@ -0,0 +1,29 @@
+/**
+ * True when `cp` lies in one of `spans` (sorted, non-overlapping). A negative
+ * `cp` — the "no neighbour" sentinel — lies in none.
+ * @param {ReadonlyArray<readonly [number, number]>} spans
+ * @param {number} cp
+ * @returns {boolean}
+ */
+export function inSpans(spans: ReadonlyArray<readonly [number, number]>, cp: number): boolean;
+/**
+ * GENERATED by scripts/gen-unicode-properties.mjs from the pinned UCD 17.0.0 — DO NOT EDIT.
+ *
+ * The Unicode properties src/invisible.mjs's carve-out reads, PINNED so the
+ * carve-out answers the same on every Node whatever its ICU's Unicode version.
+ * Regenerate with `node scripts/gen-unicode-properties.mjs`;
+ * test/unicode-properties.test.mjs fails if this drifts from the pinned package.
+ */
+export const UNICODE_VERSION: "17.0.0";
+/** @type {ReadonlyArray<readonly [number, number]>} */
+export const EXTENDED_PICTOGRAPHIC: ReadonlyArray<readonly [number, number]>;
+/** @type {ReadonlyArray<readonly [number, number]>} */
+export const EMOJI_MODIFIER: ReadonlyArray<readonly [number, number]>;
+/** @type {ReadonlyArray<readonly [number, number]>} */
+export const EMOJI_TEXT_DEFAULT: ReadonlyArray<readonly [number, number]>;
+/** @type {ReadonlyArray<readonly [number, number]>} */
+export const UNIFIED_IDEOGRAPH: ReadonlyArray<readonly [number, number]>;
+/** @type {ReadonlyArray<readonly [number, number]>} */
+export const SCRIPT_BRAILLE: ReadonlyArray<readonly [number, number]>;
+/** @type {ReadonlyArray<readonly [number, number]>} */
+export const SCRIPT_HANGUL: ReadonlyArray<readonly [number, number]>;