Scanner catalog

Scan is the structural safety stage of the Jane pipeline. It runs before normalization, before parsing, and before validation, and its only job is to detect values that are structurally dangerous, malformed, or suspicious.

Scan rules are:

• Automatically selected based on structural type.
• Executed in order, exactly as defined in the registry.
• Non‑mutating (scan never changes the value).
• Event‑emitting, producing warnings or errors.
• Policy‑interpreted, not rule‑interpreted.

Scan never interprets meaning, never coerces, and never normalizes. It simply answers: Is this value structurally safe to process?

How Scan Works

1. Structural type is detected: Jane determines the structural type (string, number, array, object, etc.) using the same taxonomy used by normalization and parsing.

2. Global rules run first: The all category applies to every value: all: [scanForSentinels].

   These rules detect hazards that are independent of type.

3. Type‑specific rules run from the registry: scanRuleRegistry[structuralType].

4. Rules emit events

   Each scan rule may emit:

   • info events
   • warn events
   • error events
   • fatal events

   Scan rules never mutate the value. They only report structural hazards.

5. Policy interprets the events

   Policy decides whether:

   • The pipeline continues.
   • The pipeline is rejected.
   • The pipeline is marked for review.

   Scan itself never rejects anything — policy does.

Scan Rules by Structural Type

Each subsection below lists the scan rules for that type, in order, and links to relevant validators that operate on the same type. This helps developers understand how scan and validation complement each other.

Global Scan Rules (all)

Rules:

• scanForSentinels

Detects sentinel values used to represent special states (e.g., __undefined__, __deleted__). This rule protects against accidental or malicious sentinel injection.

String Scan Rules

Rules (in order):

• stringIsLong
• stringHasUnsafeUnicode
• stringHasWhitespaceEdges

These rules detect:

• Excessively long strings.
• Unsafe or invisible Unicode sequences.
• Leading or trailing whitespace that may indicate formatting issues.

Number Scan Rules

Rules (in order):

• numberIsInfinite
• numberIsNaN
• numberIsTooLarge
• numberIsUnsafeInteger

These rules detect:

• Infinity and -Infinity
• NaN
• Numbers outside safe operational ranges.
• Integers outside JavaScript’s safe integer range.

Boolean Scan Rules

Rules: (none)

Booleans are structurally safe and require no scanning.

Array Scan Rules

Rules (in order):

• arrayIsLarge
• arrayIsDeep
• arrayIsHeterogeneous

These rules detect:

• Arrays that are too large to safely process
• Deeply nested arrays that may cause recursion hazards
• Arrays with mixed element types (often a sign of malformed input)

Object Scan Rules

Rules (in order):

• objectIsDeep
• objectHasCircularReferences
• objectHasManyKeys

These rules detect:

• Deeply nested objects.
• Circular references.
• Objects with excessive key counts.

These hazards can cause stack overflows, runaway recursion, or performance issues.

Date Scan Rules

Rules (in order):

• dateIsInvalid
• dateIsBeforeEpoch
• dateIsFarFuture

These rules detect:

• Invalid Date objects.
• Dates before Unix epoch.
• Dates far beyond reasonable ranges.

Unknown Scan Rules

Rules:

• unknownNotScannable

This rule emits an event indicating that the value cannot be structurally analyzed.

This is not an error — policy decides what to do with it.

BigInt Scan Rules

Rules (in order):

• bigintIsLarge
• bigintNotSafe

These rules detect:

• Bigint exceeding safe operational bit lengths.
• Bigint outside acceptable ranges.

Example: Array Depth Scan Rule

A representative scan rule:

export const arrayIsDeep: ScanRule = (value, path) => {
    if (!Array.isArray(value)) return [];

    const depth = computeDepth(value);
    if (depth <= 20) return [];

    return [
        scanEvent(
            'warn',
            'array.too.deep',
            path,
            `Array nesting depth is ${depth}, which exceeds safe limits.`,
            'Deeply nested arrays may cause recursion hazards.',
            { depth }
        )
    ];
};

This illustrates the scan contract:

• Detect a structural hazard.
• Emit a structured event.
• Never mutate the value.

Summary

Scan is:

• Automatic
• Type‑driven
• Ordered
• Non‑mutating
• Event‑emitting
• Policy‑interpreted

It ensures that every pipeline begins with a structurally safe value before normalization, parsing, or validation occur.