From 6af2082666127a5fa9b5f759bf3842715e611676 Mon Sep 17 00:00:00 2001
From: alyldas <alyldas@ya.ru>
Date: Wed, 1 Jul 2026 16:45:29 +0300
Subject: [PATCH] Add shared scanner contract aliases

---
 README.md               | 11 +++++++++
 src/contracts.ts        |  4 ++++
 src/index.ts            |  3 +++
 tests/contracts.spec.ts | 50 ++++++++++++++++++++++++++++++++++++++++-
 4 files changed, 67 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 651bb9d..3314789 100644
--- a/README.md
+++ b/README.md
@@ -41,6 +41,7 @@ import {
   createTextPipeline,
   lowerNfkc,
   type AllocationAwareRangeScanner,
+  type ScanInput,
   type TextCensor,
   type TextRangeScanner,
 } from "@textfilters/core";
@@ -77,6 +78,7 @@ const allocationAwareScanner: AllocationAwareRangeScanner = {
 
 const prepared = createPreparedText("a.b");
 const hasRange = allocationAwareScanner.check(prepared);
+const sharedInput: ScanInput = prepared;
 ```
 
 ## API
@@ -106,6 +108,10 @@ const hasRange = allocationAwareScanner.check(prepared);
 - `maskCodePointRanges(codePoints, ranges, maskChar)`
 - `maskCodePointRangesPreservingLength(codePoints, ranges, maskChar)`
 - `censorCodePointRanges(codePoints, ranges, maskChar)`
+- `ScanInput`
+- `ScanHints`
+- `ScanResult`
+- `TextRange`
 
 ### Public Input Normalization
 
@@ -165,6 +171,11 @@ registered scanners. They are intentionally generic; URL, email, phone,
 profanity, spam, and future packages keep their own package-specific detection
 logic.
 
+`ScanInput`, `ScanHints`, and `ScanResult` are short shared aliases for the
+allocation-aware prepared input, reusable text hints, and pipeline scan result
+shape. The longer `PreparedText`, `TextHints`, and
+`TextRangePipelineScanResult` names remain supported for existing callers.
+
 `AllocationAwareRangeScanner` separates a cheap pre-scan `check()` gate from
 sink-based `scan()`. A true `check()` result means the scanner is eligible to
 scan the prepared input; it is not itself proof that a range exists.
diff --git a/src/contracts.ts b/src/contracts.ts
index ec4b622..04bbab3 100644
--- a/src/contracts.ts
+++ b/src/contracts.ts
@@ -135,6 +135,10 @@ export interface TextRangePipelineScanResult {
   readonly scanResults: readonly TextRangeScanResult[];
 }
 
+export type ScanHints = TextHints;
+export type ScanInput = PreparedText;
+export type ScanResult = TextRangePipelineScanResult;
+
 export interface TextRangePipelineCensorResult {
   readonly text: string;
   readonly ranges: readonly TextCodePointRange[];
diff --git a/src/index.ts b/src/index.ts
index ef1067e..0f77ffe 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -6,6 +6,9 @@ export type {
   PreparedText,
   RangeMatch,
   RangeMatchSink,
+  ScanHints,
+  ScanInput,
+  ScanResult,
   TextCensor,
   TextCodePointRange,
   TextGuard,
diff --git a/tests/contracts.spec.ts b/tests/contracts.spec.ts
index 11c6509..fa7a581 100644
--- a/tests/contracts.spec.ts
+++ b/tests/contracts.spec.ts
@@ -1,5 +1,13 @@
 import { describe, expect, it } from "vitest";
-import type { TextCensor, TextGuard, TextGuardResult } from "../src/index.js";
+import type {
+  ScanHints,
+  ScanInput,
+  ScanResult,
+  TextCensor,
+  TextGuard,
+  TextGuardResult,
+  TextRange,
+} from "../src/index.js";
 
 describe("textfilters core contracts", () => {
   it("allows censors and guards to share stable shapes", () => {
@@ -19,4 +27,44 @@ describe("textfilters core contracts", () => {
     expect(censor.censor("secret")).toBe("******");
     expect(guard.check({ text: "value" })).toEqual(result);
   });
+
+  it("exposes short scanner contract aliases for shared scanner work", () => {
+    const range: TextRange = [1, 3];
+    const hints: ScanHints = {
+      textLength: 3,
+      codePointLength: 3,
+      isEmpty: false,
+      hasAsciiOnly: true,
+      hasNonAscii: false,
+      hasDigit: false,
+      digitCount: 0,
+      hasAsciiLetter: true,
+      hasWhitespace: false,
+      hasPunctuation: false,
+      punctuationCount: 0,
+      hasAtSign: false,
+      hasDot: false,
+      hasSlash: false,
+      hasColon: false,
+      hasPlus: false,
+    };
+    const input: ScanInput = {
+      text: "abc",
+      codePoints: ["a", "b", "c"],
+      hints,
+    };
+    const result: ScanResult = {
+      text: input.text,
+      codePoints: input.codePoints,
+      ranges: [range],
+      scanResults: [{ ranges: [range] }],
+    };
+
+    expect(result).toEqual({
+      text: "abc",
+      codePoints: ["a", "b", "c"],
+      ranges: [[1, 3]],
+      scanResults: [{ ranges: [[1, 3]] }],
+    });
+  });
 });