eyecite-ts 0.1.0 → 0.2.0

package/README.md

@@ -1,17 +1,18 @@
 # eyecite-ts
 
-TypeScript legal citation extraction library - port of Python [eyecite](https://github.com/freelawproject/eyecite).
+TypeScript legal citation extraction library — port of Python [eyecite](https://github.com/freelawproject/eyecite).
 
-Extract, validate, annotate, and resolve legal citations from court opinions and legal documents with zero runtime dependencies and a <50KB bundle size.
+Extract, resolve, and annotate legal citations from court opinions and legal documents with zero runtime dependencies.
 
 ## Features
 
 - **Full citation extraction**: Case citations, statutes, journal articles, neutral citations, public laws, federal register
 - **Short-form resolution**: Id./Ibid., supra, and short-form case citations resolved to their full antecedents
-- **Reporter database**: 1235 reporters with variant matching and confidence scoring
-- **Citation annotation**: HTML/Markdown markup with auto-escape and position tracking
-- **Bundle optimization**: Tree-shakeable exports, lazy-loaded data, separate entry points
-- **TypeScript native**: Discriminated unions, strict types, full IntelliSense
+- **Reporter database**: 1,200+ reporters with variant matching and confidence scoring
+- **Citation annotation**: HTML markup with auto-escape XSS protection and position tracking
+- **Bundle optimization**: Tree-shakeable exports, lazy-loaded reporter data, separate entry points
+- **TypeScript native**: Discriminated unions, conditional types, type guards, full IntelliSense
+- **Zero dependencies**: No runtime dependencies, 4.4KB gzipped core bundle
 
 ## Installation
 
@@ -36,13 +37,13 @@ console.log(citations[0])
 //   court: '9th Cir.',
 //   year: 2020,
 //   confidence: 0.85,
-//   span: { originalStart: 4, originalEnd: 48 }
+//   span: { originalStart: 4, originalEnd: 48, cleanStart: 4, cleanEnd: 48 }
 // }
 ```
 
 ## Citation Extraction
 
-### Basic Usage
+### Multiple Citation Types
 
 ```typescript
 import { extractCitations } from 'eyecite-ts'
@@ -70,7 +71,8 @@ const citations = await extractCitationsAsync(text)
 ### Custom Patterns
 
 ```typescript
-import { extractCitations, casePatterns } from 'eyecite-ts'
+import { extractCitations } from 'eyecite-ts'
+import { casePatterns } from 'eyecite-ts'
 
 // Extract only case citations
 const citations = extractCitations(text, {
@@ -81,17 +83,17 @@ const citations = extractCitations(text, {
 ### Custom Cleaners
 
 ```typescript
-import { extractCitations, stripHtmlTags } from 'eyecite-ts'
+import { extractCitations, cleanText } from 'eyecite-ts'
 
-// Use only HTML stripping, skip Unicode normalization
+// Use only HTML stripping
 const citations = extractCitations(html, {
-  cleaners: [stripHtmlTags]
+  cleaners: [(text) => text.replace(/<[^>]+>/g, '')]
 })
 ```
 
 ## Resolving Short-Form Citations
 
-Short-form citations (Id., supra, short-form case) refer to earlier citations in the document. The resolution engine automatically links them to their full antecedents.
+Short-form citations (Id., supra, short-form case) refer to earlier citations in the document. The resolution engine links them to their full antecedents.
 
 ### Convenience API
 
@@ -105,16 +107,11 @@ const text = `
   500 F.2d at 140.
 `
 
-// Convenience: extract + resolve in one call
 const citations = extractCitations(text, { resolve: true })
 
 // citations[1] is Id. citation
 console.log(citations[1].resolution)
-// {
-//   resolvedTo: 0,  // Points to Smith v. Jones (index 0)
-//   confidence: 1.0,
-//   warnings: []
-// }
+// { resolvedTo: 0, confidence: 1.0 }
 ```
 
 ### Power-User API
@@ -122,15 +119,13 @@ console.log(citations[1].resolution)
 ```typescript
 import { extractCitations, resolveCitations } from 'eyecite-ts'
 
-// Step 1: Extract citations
 const citations = extractCitations(text)
 
-// Step 2: Resolve short-form citations
 const resolved = resolveCitations(citations, text, {
-  scopeStrategy: 'paragraph',      // Only resolve within paragraphs
-  fuzzyPartyMatching: true,        // Enable fuzzy supra matching
-  partyMatchThreshold: 0.8,        // Similarity threshold (0-1)
-  reportUnresolved: true           // Report failure reasons
+  scopeStrategy: 'paragraph',
+  fuzzyPartyMatching: true,
+  partyMatchThreshold: 0.8,
+  reportUnresolved: true
 })
 ```
 
@@ -153,125 +148,91 @@ const resolved = resolveCitations(citations, text, {
 ```typescript
 const text = 'Smith v. Jones, 500 F.2d 123. Id. at 125.'
 const citations = extractCitations(text, { resolve: true })
-
-// citations[1].resolution.resolvedTo === 0 (points to Smith v. Jones)
+// citations[1].resolution.resolvedTo === 0
 ```
 
 **Supra citations:**
 
 ```typescript
-const text = 'Smith v. Jones, 500 F.2d 123. See also Smith, supra, at 130.'
+const text = 'Smith v. Jones, 500 F.2d 123. Smith, supra, at 130.'
 const citations = extractCitations(text, { resolve: true })
-
 // citations[1].resolution.resolvedTo === 0 (party name matches "Smith")
 ```
 
 **Short-form case citations:**
 
 ```typescript
-const text = 'Brown v. Board, 347 U.S. 483 (1954). See 347 U.S. at 495.'
+const text = 'Brown v. Board, 347 U.S. 483. See 347 U.S. at 495.'
 const citations = extractCitations(text, { resolve: true })
-
 // citations[1].resolution.resolvedTo === 0 (volume/reporter matches)
 ```
 
-### Handling Unresolved Citations
+**Unresolved citations:**
 
 ```typescript
 const text = 'Id. at 100.' // Orphan Id. with no preceding citation
-
 const citations = extractCitations(text, { resolve: true })
-
-console.log(citations[0].resolution)
-// {
-//   resolvedTo: undefined,
-//   failureReason: 'No preceding full citation found',
-//   confidence: 0,
-//   warnings: []
-// }
-```
-
-To suppress unresolved warnings:
-
-```typescript
-const citations = extractCitations(text, {
-  resolve: true,
-  resolutionOptions: {
-    reportUnresolved: false  // Omits resolution field for unresolved citations
-  }
-})
-```
-
-## Citation Validation
-
-Validate case citations against the reporters database:
-
-```typescript
-import { validateCitation } from 'eyecite-ts/data'
-
-// Returns citations with adjusted confidence scores
-const validated = await validateCitation(citations)
-
-// Confidence adjustments:
-// - +0.2 boost for reporter match
-// - -0.3 penalty for reporter mismatch
-// - -0.1 penalty for ambiguous reporter
+// citations[0].resolution.failureReason === 'No preceding full case citation found'
 ```
 
 ## Citation Annotation
 
-Add HTML/Markdown markup to citations:
+Add HTML markup to citations in text:
 
 ```typescript
 import { annotate } from 'eyecite-ts/annotate'
+import { extractCitations } from 'eyecite-ts'
+
+const text = 'See Smith v. Jones, 500 F.2d 123 (2020).'
+const citations = extractCitations(text)
 
-// Template mode (simple)
-const html = annotate(
-  text,
-  citations,
-  '<a href="{{url}}">{{text}}</a>'
-)
+// Template mode
+const result = annotate(text, citations, {
+  template: { before: '<cite>', after: '</cite>' }
+})
+// result.text === 'See Smith v. Jones, <cite>500 F.2d 123</cite> (2020).'
 
 // Callback mode (full control)
-const html = annotate(text, citations, (citation, text) => {
-  const url = `https://example.com/${citation.volume}/${citation.reporter}/${citation.page}`
-  return `<a href="${url}">${text}</a>`
+const result2 = annotate(text, citations, {
+  callback: (citation, surrounding) => {
+    if (citation.type === 'case') {
+      return `<a href="/cases/${citation.volume}">${citation.matchedText}</a>`
+    }
+    return citation.matchedText
+  }
 })
 ```
 
 Auto-escape is enabled by default for XSS protection:
 
 ```typescript
-// User input is automatically escaped
-const html = annotate(text, citations, '<a>{{text}}</a>', {
-  autoEscape: true  // default
+const result = annotate(text, citations, {
+  template: { before: '<cite>', after: '</cite>' },
+  autoEscape: true  // default — escapes &, <, >, ", ', /
 })
 ```
 
-## Bundle Size
-
-Core library is optimized for tree-shaking:
-
-- **Core extraction**: 2.5 KB gzipped
-- **Reporter database**: 88.5 KB gzipped (lazy-loaded)
-- **Annotation**: 0.5 KB gzipped
+## Reporter Validation
 
-Import only what you need:
+Validate case citations against the reporters database:
 
 ```typescript
-// Tree-shakeable imports
-import { extractCitations } from 'eyecite-ts'           // Core only
-import { validateCitation } from 'eyecite-ts/data'      // Core + data
-import { annotate } from 'eyecite-ts/annotate'          // Core + annotate
+import { extractWithValidation } from 'eyecite-ts'
+
+const validated = await extractWithValidation(text, { validate: true })
+// Confidence adjustments:
+//   +0.2 boost for reporter match
+//   -0.3 penalty for unknown reporter
+//   -0.1 per extra match for ambiguous reporter
 ```
 
-## Citation Types
+## Type System
 
-All citation types are exported with full TypeScript types:
+All citation types use a discriminated union on the `type` field:
 
 ```typescript
 import type {
-  Citation,
+  Citation,           // Union of all 9 types
   FullCaseCitation,
   StatuteCitation,
   JournalCitation,
@@ -280,24 +241,69 @@ import type {
   FederalRegisterCitation,
   IdCitation,
   SupraCitation,
-  ShortFormCaseCitation
+  ShortFormCaseCitation,
+  CitationOfType,     // Extract subtype: CitationOfType<'case'> = FullCaseCitation
+  ExtractorMap,       // Maps FullCitationType keys to citation subtypes
+  FullCitation,       // Union of full citation types
+  ShortFormCitation,  // Union of short-form types
 } from 'eyecite-ts'
+```
 
-// Discriminated union - switch on type
-citations.forEach(citation => {
-  switch (citation.type) {
-    case 'case':
-      console.log(citation.reporter)  // FullCaseCitation
-      break
-    case 'statute':
-      console.log(citation.title)     // StatuteCitation
-      break
-    case 'id':
-      console.log(citation.pincite)   // IdCitation
-      break
-    // etc.
-  }
-})
+### Type Guards
+
+```typescript
+import {
+  isFullCitation,
+  isShortFormCitation,
+  isCaseCitation,
+  isCitationType,
+  assertUnreachable
+} from 'eyecite-ts'
+
+// Specific guards
+if (isFullCitation(citation)) {
+  // citation: FullCitation
+}
+
+// Generic guard — narrows to any specific type
+if (isCitationType(citation, 'statute')) {
+  // citation: StatuteCitation
+}
+
+// Exhaustiveness check in switch statements
+switch (citation.type) {
+  case 'case': /* ... */ break
+  case 'statute': /* ... */ break
+  // ... all 9 types ...
+  default: assertUnreachable(citation.type)
+}
+```
+
+### Resolved Citation Types
+
+`ResolvedCitation` uses a conditional type — `resolution` is only meaningfully present on short-form citations:
+
+```typescript
+import type { ResolvedCitation } from 'eyecite-ts'
+
+// On short-form citations: resolution: ResolutionResult | undefined
+// On full citations: resolution?: undefined
+```
+
+## Bundle Size
+
+Three entry points for optimal tree-shaking:
+
+| Entry Point | Import | Gzipped |
+|------------|--------|---------|
+| Core extraction | `eyecite-ts` | 4.4 KB |
+| Annotation | `eyecite-ts/annotate` | 0.5 KB |
+| Reporter data | `eyecite-ts/data` | 88.5 KB (lazy-loaded) |
+
+```typescript
+import { extractCitations } from 'eyecite-ts'           // Core only
+import { annotate } from 'eyecite-ts/annotate'           // Annotation
+import { loadReporters } from 'eyecite-ts/data'          // Reporter database
 ```
 
 ## Architecture
@@ -307,28 +313,26 @@ Citation extraction follows a 4-stage pipeline:
 1. **Clean**: Remove HTML, normalize Unicode, fix smart quotes
 2. **Tokenize**: Apply regex patterns to find citation candidates
 3. **Extract**: Parse metadata (volume, reporter, page, etc.)
-4. **Translate**: Map positions from cleaned text → original text
+4. **Resolve** (optional): Link short-form citations to antecedents
 
-All positions (spans) track both cleaned and original text offsets.
+All positions (spans) track both cleaned and original text offsets via `TransformationMap`.
 
 See [ARCHITECTURE.md](ARCHITECTURE.md) for details.
 
 ## Development
 
 ```bash
-# Install dependencies
-npm install
-
-# Run tests
-npm test
-
-# Type checking
-npm run typecheck
-
-# Build
-npm run build
+npm install          # Install dependencies
+npm test             # Run tests (vitest, watch mode)
+npx vitest run       # Run tests once
+npm run typecheck    # Type-check with tsc
+npm run build        # Build (ESM + CJS + DTS)
+npm run lint         # Lint with Biome
+npm run format       # Format with Biome
 ```
 
+304 tests, 97% statement coverage, 91% branch coverage.
+
 ## License
 
 MIT

package/dist/annotate/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":[],"sources":["../../src/annotate/annotate.ts"],"sourcesContent":["import type { Citation } from '../types/citation'\nimport type { AnnotationOptions, AnnotationResult } from './types'\n\n/**\n * Annotate citations in text with custom markup.\n *\n * Supports two modes:\n * - **Template mode**: Simple before/after wrapping (set `options.template`)\n * - **Callback mode**: Custom logic with full citation context (set `options.callback`)\n *\n * Citations are processed in reverse order to avoid position shifts invalidating\n * subsequent annotations. Position tracking maps original positions to new positions\n * after markup insertion.\n *\n * @param text - Original or cleaned text to annotate\n * @param citations - Citations to mark up (from extraction pipeline)\n * @param options - Annotation configuration\n * @returns Annotated text with position mapping\n *\n * @example Template mode\n * ```typescript\n * const result = annotate(text, citations, {\n *   template: { before: '<cite>', after: '</cite>' }\n * })\n * // Result: \"See <cite>500 F.2d 123</cite>\"\n * ```\n *\n * @example Callback mode\n * ```typescript\n * const result = annotate(text, citations, {\n *   callback: (citation) => {\n *     if (citation.type === 'case') {\n *       return `<a href=\"/cases/${citation.volume}\">${citation.matchedText}</a>`\n *     }\n *     return citation.matchedText\n *   }\n * })\n * ```\n *\n * @example Position tracking\n * ```typescript\n * const result = annotate(text, citations, { template: { before: '<mark>', after: '</mark>' } })\n * // result.positionMap tracks how positions shifted\n * const originalPos = 10\n * const newPos = result.positionMap.get(originalPos)\n * ```\n */\nexport function annotate(\n  text: string,\n  citations: Citation[],\n  options: AnnotationOptions = {}\n): AnnotationResult {\n  const {\n    useCleanText = false,\n    autoEscape = true,  // Secure by default\n    template,\n    callback,\n  } = options\n\n  // Sort reverse to avoid position shifts invalidating subsequent annotations\n  const sorted = [...citations].sort((a, b) => {\n    const aPos = useCleanText ? a.span.cleanStart : a.span.originalStart\n    const bPos = useCleanText ? b.span.cleanStart : b.span.originalStart\n    return bPos - aPos  // Reverse for backward iteration\n  })\n\n  let result = text\n  const positionMap = new Map<number, number>()\n\n  for (const citation of sorted) {\n    const start = useCleanText ? citation.span.cleanStart : citation.span.originalStart\n    const end = useCleanText ? citation.span.cleanEnd : citation.span.originalEnd\n\n    let markup = ''\n\n    if (callback) {\n      // Callback mode: developer provides full logic\n      const surrounding = text.substring(\n        Math.max(0, start - 30),\n        Math.min(text.length, end + 30)\n      )\n      markup = callback(citation, surrounding)\n    } else if (template) {\n      // Template mode: simple before/after wrapping\n      const citationText = result.substring(start, end)\n      const escaped = autoEscape ? escapeHtmlEntities(citationText) : citationText\n      markup = template.before + escaped + template.after\n    } else {\n      // No annotation specified\n      continue\n    }\n\n    // Insert annotation (working backwards preserves positions for later citations)\n    result = result.slice(0, start) + markup + result.slice(end)\n\n    // Track original position to new position (before this annotation was added)\n    positionMap.set(start, start)\n  }\n\n  return { text: result, positionMap, skipped: [] }\n}\n\n/**\n * Escape HTML entities to prevent XSS injection.\n *\n * Converts special HTML characters to their entity equivalents:\n * - `&` → `&amp;`\n * - `<` → `&lt;`\n * - `>` → `&gt;`\n * - `\"` → `&quot;`\n * - `'` → `&#39;`\n * - `/` → `&#x2F;`\n *\n * @param text - Text to escape\n * @returns Escaped text safe for HTML insertion\n */\nfunction escapeHtmlEntities(text: string): string {\n  const map: Record<string, string> = {\n    '&': '&amp;',\n    '<': '&lt;',\n    '>': '&gt;',\n    '\"': '&quot;',\n    \"'\": '&#39;',\n    '/': '&#x2F;',\n  }\n  return text.replace(/[&<>\"'\\/]/g, (char) => map[char])\n}\n"],"mappings":"mEA+CA,SAAgB,EACd,EACA,EACA,EAA6B,EAAE,CACb,CAClB,GAAM,CACJ,eAAe,GACf,aAAa,GACb,WACA,YACE,EAGE,EAAS,CAAC,GAAG,EAAU,CAAC,MAAM,EAAG,IAAM,CAC3C,IAAM,EAAO,EAAe,EAAE,KAAK,WAAa,EAAE,KAAK,cAEvD,OADa,EAAe,EAAE,KAAK,WAAa,EAAE,KAAK,eACzC,GACd,CAEE,EAAS,EACP,EAAc,IAAI,IAExB,IAAK,IAAM,KAAY,EAAQ,CAC7B,IAAM,EAAQ,EAAe,EAAS,KAAK,WAAa,EAAS,KAAK,cAChE,EAAM,EAAe,EAAS,KAAK,SAAW,EAAS,KAAK,YAE9D,EAAS,GAEb,GAAI,EAMF,EAAS,EAAS,EAJE,EAAK,UACvB,KAAK,IAAI,EAAG,EAAQ,GAAG,CACvB,KAAK,IAAI,EAAK,OAAQ,EAAM,GAAG,CAChC,CACuC,SAC/B,EAAU,CAEnB,IAAM,EAAe,EAAO,UAAU,EAAO,EAAI,CAC3C,EAAU,EAAa,EAAmB,EAAa,CAAG,EAChE,EAAS,EAAS,OAAS,EAAU,EAAS,WAG9C,SAIF,EAAS,EAAO,MAAM,EAAG,EAAM,CAAG,EAAS,EAAO,MAAM,EAAI,CAG5D,EAAY,IAAI,EAAO,EAAM,CAG/B,MAAO,CAAE,KAAM,EAAQ,cAAa,QAAS,EAAE,CAAE,CAiBnD,SAAS,EAAmB,EAAsB,CAChD,IAAM,EAA8B,CAClC,IAAK,QACL,IAAK,OACL,IAAK,OACL,IAAK,SACL,IAAK,QACL,IAAK,SACN,CACD,OAAO,EAAK,QAAQ,aAAe,GAAS,EAAI,GAAM"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../../src/annotate/annotate.ts"],"sourcesContent":["import type { Citation } from '../types/citation'\nimport type { AnnotationOptions, AnnotationResult } from './types'\n\n/**\n * Annotate citations in text with custom markup.\n *\n * Supports two modes:\n * - **Template mode**: Simple before/after wrapping (set `options.template`)\n * - **Callback mode**: Custom logic with full citation context (set `options.callback`)\n *\n * Citations are processed in reverse order to avoid position shifts invalidating\n * subsequent annotations. Position tracking maps original positions to new positions\n * after markup insertion.\n *\n * @param text - Original or cleaned text to annotate\n * @param citations - Citations to mark up (from extraction pipeline)\n * @param options - Annotation configuration\n * @returns Annotated text with position mapping\n *\n * @example Template mode\n * ```typescript\n * const result = annotate(text, citations, {\n *   template: { before: '<cite>', after: '</cite>' }\n * })\n * // Result: \"See <cite>500 F.2d 123</cite>\"\n * ```\n *\n * @example Callback mode\n * ```typescript\n * const result = annotate(text, citations, {\n *   callback: (citation) => {\n *     if (citation.type === 'case') {\n *       return `<a href=\"/cases/${citation.volume}\">${citation.matchedText}</a>`\n *     }\n *     return citation.matchedText\n *   }\n * })\n * ```\n *\n * @example Position tracking\n * ```typescript\n * const result = annotate(text, citations, { template: { before: '<mark>', after: '</mark>' } })\n * // result.positionMap tracks how positions shifted\n * const originalPos = 10\n * const newPos = result.positionMap.get(originalPos)\n * ```\n */\nexport function annotate<C extends Citation = Citation>(\n  text: string,\n  citations: C[],\n  options: AnnotationOptions<C> = {}\n): AnnotationResult {\n  const {\n    useCleanText = false,\n    autoEscape = true,  // Secure by default\n    template,\n    callback,\n  } = options\n\n  // Sort reverse to avoid position shifts invalidating subsequent annotations\n  const sorted = [...citations].sort((a, b) => {\n    const aPos = useCleanText ? a.span.cleanStart : a.span.originalStart\n    const bPos = useCleanText ? b.span.cleanStart : b.span.originalStart\n    return bPos - aPos  // Reverse for backward iteration\n  })\n\n  let result = text\n  const positionMap = new Map<number, number>()\n\n  for (const citation of sorted) {\n    const start = useCleanText ? citation.span.cleanStart : citation.span.originalStart\n    const end = useCleanText ? citation.span.cleanEnd : citation.span.originalEnd\n\n    let markup = ''\n\n    if (callback) {\n      // Callback mode: developer provides full logic\n      const surrounding = text.substring(\n        Math.max(0, start - 30),\n        Math.min(text.length, end + 30)\n      )\n      markup = callback(citation, surrounding)\n    } else if (template) {\n      // Template mode: simple before/after wrapping\n      const citationText = result.substring(start, end)\n      const escaped = autoEscape ? escapeHtmlEntities(citationText) : citationText\n      markup = template.before + escaped + template.after\n    } else {\n      // No annotation specified\n      continue\n    }\n\n    // Insert annotation (working backwards preserves positions for later citations)\n    result = result.slice(0, start) + markup + result.slice(end)\n\n    // Track original position to new position (before this annotation was added)\n    positionMap.set(start, start)\n  }\n\n  return { text: result, positionMap, skipped: [] }\n}\n\n/**\n * Escape HTML entities to prevent XSS injection.\n *\n * Converts special HTML characters to their entity equivalents:\n * - `&` → `&amp;`\n * - `<` → `&lt;`\n * - `>` → `&gt;`\n * - `\"` → `&quot;`\n * - `'` → `&#39;`\n * - `/` → `&#x2F;`\n *\n * @param text - Text to escape\n * @returns Escaped text safe for HTML insertion\n */\nfunction escapeHtmlEntities(text: string): string {\n  const map: Record<string, string> = {\n    '&': '&amp;',\n    '<': '&lt;',\n    '>': '&gt;',\n    '\"': '&quot;',\n    \"'\": '&#39;',\n    '/': '&#x2F;',\n  }\n  return text.replace(/[&<>\"'\\/]/g, (char) => map[char])\n}\n"],"mappings":"mEA+CA,SAAgB,EACd,EACA,EACA,EAAgC,EAAE,CAChB,CAClB,GAAM,CACJ,eAAe,GACf,aAAa,GACb,WACA,YACE,EAGE,EAAS,CAAC,GAAG,EAAU,CAAC,MAAM,EAAG,IAAM,CAC3C,IAAM,EAAO,EAAe,EAAE,KAAK,WAAa,EAAE,KAAK,cAEvD,OADa,EAAe,EAAE,KAAK,WAAa,EAAE,KAAK,eACzC,GACd,CAEE,EAAS,EACP,EAAc,IAAI,IAExB,IAAK,IAAM,KAAY,EAAQ,CAC7B,IAAM,EAAQ,EAAe,EAAS,KAAK,WAAa,EAAS,KAAK,cAChE,EAAM,EAAe,EAAS,KAAK,SAAW,EAAS,KAAK,YAE9D,EAAS,GAEb,GAAI,EAMF,EAAS,EAAS,EAJE,EAAK,UACvB,KAAK,IAAI,EAAG,EAAQ,GAAG,CACvB,KAAK,IAAI,EAAK,OAAQ,EAAM,GAAG,CAChC,CACuC,SAC/B,EAAU,CAEnB,IAAM,EAAe,EAAO,UAAU,EAAO,EAAI,CAC3C,EAAU,EAAa,EAAmB,EAAa,CAAG,EAChE,EAAS,EAAS,OAAS,EAAU,EAAS,WAG9C,SAIF,EAAS,EAAO,MAAM,EAAG,EAAM,CAAG,EAAS,EAAO,MAAM,EAAI,CAG5D,EAAY,IAAI,EAAO,EAAM,CAG/B,MAAO,CAAE,KAAM,EAAQ,cAAa,QAAS,EAAE,CAAE,CAiBnD,SAAS,EAAmB,EAAsB,CAChD,IAAM,EAA8B,CAClC,IAAK,QACL,IAAK,OACL,IAAK,OACL,IAAK,SACL,IAAK,QACL,IAAK,SACN,CACD,OAAO,EAAK,QAAQ,aAAe,GAAS,EAAI,GAAM"}

package/dist/annotate/index.d.cts

@@ -1,4 +1,4 @@
-import { t as Citation } from "../citation-BcY5zzWb.cjs";
+import { t as Citation } from "../citation-BhJJj_AZ.cjs";
 
 //#region src/annotate/types.d.ts
 /**
@@ -27,7 +27,7 @@ import { t as Citation } from "../citation-BcY5zzWb.cjs";
 * })
 * ```
 */
-interface AnnotationOptions {
+interface AnnotationOptions<C extends Citation = Citation> {
   /**
   * Apply annotations to cleaned text (true) or original text (false).
   *
@@ -65,7 +65,7 @@ interface AnnotationOptions {
   * @param surrounding - Text around the citation (for context-aware markup)
   * @returns Complete markup string (replaces citation.matchedText)
   */
-  callback?: (citation: Citation, surrounding: string) => string;
+  callback?: (citation: C, surrounding: string) => string;
   /**
   * Template mode: simple before/after markup strings.
   *
@@ -157,7 +157,7 @@ interface AnnotationResult {
 * const newPos = result.positionMap.get(originalPos)
 * ```
 */
-declare function annotate(text: string, citations: Citation[], options?: AnnotationOptions): AnnotationResult;
+declare function annotate<C extends Citation = Citation>(text: string, citations: C[], options?: AnnotationOptions<C>): AnnotationResult;
 //#endregion
 export { AnnotationOptions, AnnotationResult, annotate };
 //# sourceMappingURL=index.d.cts.map

package/dist/annotate/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/annotate/types.ts","../../src/annotate/annotate.ts"],"mappings":";;;;;AA4BA;;;;;;;;;;;;;;;AAoEA;;;;;;;;;UApEiB,iBAAA;EA0FN;;;;ACvEX;;;;EDVE,YAAA;;;;;;;;;;;;;;;;;;EAmBA,UAAA;;;;;;;;;;;EAYA,QAAA,IAAY,QAAA,EAAU,QAAA,EAAU,WAAA;;;;;;;;;;;;;;;;EAiBhC,QAAA;+CAEE,MAAA;IAEA,KAAA;EAAA;AAAA;;;;UAOa,gBAAA;;;;EAIf,IAAA;;;;;;;;;EAUA,WAAA,EAAa,GAAA;;;;;;;EAQb,OAAA,EAAS,QAAA;AAAA;;;;AA1FX;;;;;;;;;;;;;;;AAoEA;;;;;;;;;;;;;;ACjDA;;;;;;;;;;;;;;iBAAgB,QAAA,CACd,IAAA,UACA,SAAA,EAAW,QAAA,IACX,OAAA,GAAS,iBAAA,GACR,gBAAA"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/annotate/types.ts","../../src/annotate/annotate.ts"],"mappings":";;;;;AA4BA;;;;;;;;;;;;;;;;;;;;;;AAoEA;;UApEiB,iBAAA,WAA4B,QAAA,GAAW,QAAA;EA0F7C;;;;;;;;EAjFT,YAAA;;;ACUF;;;;;;;;;;;;;;;EDSE,UAAA;;;;;;;;;;;EAYA,QAAA,IAAY,QAAA,EAAU,CAAA,EAAG,WAAA;;;;;;;;;;;;;;;;EAiBzB,QAAA;+CAEE,MAAA;IAEA,KAAA;EAAA;AAAA;;;;UAOa,gBAAA;;;;EAIf,IAAA;;;;;;;;;EAUA,WAAA,EAAa,GAAA;;;;;;;EAQb,OAAA,EAAS,QAAA;AAAA;;;;AA1FX;;;;;;;;;;;;;;;;;;;;;;AAoEA;;;;;;;;;;;;;;ACjDA;;;;;;;iBAAgB,QAAA,WAAmB,QAAA,GAAW,QAAA,CAAA,CAC5C,IAAA,UACA,SAAA,EAAW,CAAA,IACX,OAAA,GAAS,iBAAA,CAAkB,CAAA,IAC1B,gBAAA"}

package/dist/annotate/index.d.mts

@@ -1,4 +1,4 @@
-import { t as Citation } from "../citation-8_GvfEuj.mjs";
+import { t as Citation } from "../citation-FJ10UFM7.mjs";
 
 //#region src/annotate/types.d.ts
 /**
@@ -27,7 +27,7 @@ import { t as Citation } from "../citation-8_GvfEuj.mjs";
 * })
 * ```
 */
-interface AnnotationOptions {
+interface AnnotationOptions<C extends Citation = Citation> {
   /**
   * Apply annotations to cleaned text (true) or original text (false).
   *
@@ -65,7 +65,7 @@ interface AnnotationOptions {
   * @param surrounding - Text around the citation (for context-aware markup)
   * @returns Complete markup string (replaces citation.matchedText)
   */
-  callback?: (citation: Citation, surrounding: string) => string;
+  callback?: (citation: C, surrounding: string) => string;
   /**
   * Template mode: simple before/after markup strings.
   *
@@ -157,7 +157,7 @@ interface AnnotationResult {
 * const newPos = result.positionMap.get(originalPos)
 * ```
 */
-declare function annotate(text: string, citations: Citation[], options?: AnnotationOptions): AnnotationResult;
+declare function annotate<C extends Citation = Citation>(text: string, citations: C[], options?: AnnotationOptions<C>): AnnotationResult;
 //#endregion
 export { AnnotationOptions, AnnotationResult, annotate };
 //# sourceMappingURL=index.d.mts.map

package/dist/annotate/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/annotate/types.ts","../../src/annotate/annotate.ts"],"mappings":";;;;;AA4BA;;;;;;;;;;;;;;;AAoEA;;;;;;;;;UApEiB,iBAAA;EA0FN;;;;ACvEX;;;;EDVE,YAAA;;;;;;;;;;;;;;;;;;EAmBA,UAAA;;;;;;;;;;;EAYA,QAAA,IAAY,QAAA,EAAU,QAAA,EAAU,WAAA;;;;;;;;;;;;;;;;EAiBhC,QAAA;+CAEE,MAAA;IAEA,KAAA;EAAA;AAAA;;;;UAOa,gBAAA;;;;EAIf,IAAA;;;;;;;;;EAUA,WAAA,EAAa,GAAA;;;;;;;EAQb,OAAA,EAAS,QAAA;AAAA;;;;AA1FX;;;;;;;;;;;;;;;AAoEA;;;;;;;;;;;;;;ACjDA;;;;;;;;;;;;;;iBAAgB,QAAA,CACd,IAAA,UACA,SAAA,EAAW,QAAA,IACX,OAAA,GAAS,iBAAA,GACR,gBAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/annotate/types.ts","../../src/annotate/annotate.ts"],"mappings":";;;;;AA4BA;;;;;;;;;;;;;;;;;;;;;;AAoEA;;UApEiB,iBAAA,WAA4B,QAAA,GAAW,QAAA;EA0F7C;;;;;;;;EAjFT,YAAA;;;ACUF;;;;;;;;;;;;;;;EDSE,UAAA;;;;;;;;;;;EAYA,QAAA,IAAY,QAAA,EAAU,CAAA,EAAG,WAAA;;;;;;;;;;;;;;;;EAiBzB,QAAA;+CAEE,MAAA;IAEA,KAAA;EAAA;AAAA;;;;UAOa,gBAAA;;;;EAIf,IAAA;;;;;;;;;EAUA,WAAA,EAAa,GAAA;;;;;;;EAQb,OAAA,EAAS,QAAA;AAAA;;;;AA1FX;;;;;;;;;;;;;;;;;;;;;;AAoEA;;;;;;;;;;;;;;ACjDA;;;;;;;iBAAgB,QAAA,WAAmB,QAAA,GAAW,QAAA,CAAA,CAC5C,IAAA,UACA,SAAA,EAAW,CAAA,IACX,OAAA,GAAS,iBAAA,CAAkB,CAAA,IAC1B,gBAAA"}

package/dist/annotate/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../src/annotate/annotate.ts"],"sourcesContent":["import type { Citation } from '../types/citation'\nimport type { AnnotationOptions, AnnotationResult } from './types'\n\n/**\n * Annotate citations in text with custom markup.\n *\n * Supports two modes:\n * - **Template mode**: Simple before/after wrapping (set `options.template`)\n * - **Callback mode**: Custom logic with full citation context (set `options.callback`)\n *\n * Citations are processed in reverse order to avoid position shifts invalidating\n * subsequent annotations. Position tracking maps original positions to new positions\n * after markup insertion.\n *\n * @param text - Original or cleaned text to annotate\n * @param citations - Citations to mark up (from extraction pipeline)\n * @param options - Annotation configuration\n * @returns Annotated text with position mapping\n *\n * @example Template mode\n * ```typescript\n * const result = annotate(text, citations, {\n *   template: { before: '<cite>', after: '</cite>' }\n * })\n * // Result: \"See <cite>500 F.2d 123</cite>\"\n * ```\n *\n * @example Callback mode\n * ```typescript\n * const result = annotate(text, citations, {\n *   callback: (citation) => {\n *     if (citation.type === 'case') {\n *       return `<a href=\"/cases/${citation.volume}\">${citation.matchedText}</a>`\n *     }\n *     return citation.matchedText\n *   }\n * })\n * ```\n *\n * @example Position tracking\n * ```typescript\n * const result = annotate(text, citations, { template: { before: '<mark>', after: '</mark>' } })\n * // result.positionMap tracks how positions shifted\n * const originalPos = 10\n * const newPos = result.positionMap.get(originalPos)\n * ```\n */\nexport function annotate(\n  text: string,\n  citations: Citation[],\n  options: AnnotationOptions = {}\n): AnnotationResult {\n  const {\n    useCleanText = false,\n    autoEscape = true,  // Secure by default\n    template,\n    callback,\n  } = options\n\n  // Sort reverse to avoid position shifts invalidating subsequent annotations\n  const sorted = [...citations].sort((a, b) => {\n    const aPos = useCleanText ? a.span.cleanStart : a.span.originalStart\n    const bPos = useCleanText ? b.span.cleanStart : b.span.originalStart\n    return bPos - aPos  // Reverse for backward iteration\n  })\n\n  let result = text\n  const positionMap = new Map<number, number>()\n\n  for (const citation of sorted) {\n    const start = useCleanText ? citation.span.cleanStart : citation.span.originalStart\n    const end = useCleanText ? citation.span.cleanEnd : citation.span.originalEnd\n\n    let markup = ''\n\n    if (callback) {\n      // Callback mode: developer provides full logic\n      const surrounding = text.substring(\n        Math.max(0, start - 30),\n        Math.min(text.length, end + 30)\n      )\n      markup = callback(citation, surrounding)\n    } else if (template) {\n      // Template mode: simple before/after wrapping\n      const citationText = result.substring(start, end)\n      const escaped = autoEscape ? escapeHtmlEntities(citationText) : citationText\n      markup = template.before + escaped + template.after\n    } else {\n      // No annotation specified\n      continue\n    }\n\n    // Insert annotation (working backwards preserves positions for later citations)\n    result = result.slice(0, start) + markup + result.slice(end)\n\n    // Track original position to new position (before this annotation was added)\n    positionMap.set(start, start)\n  }\n\n  return { text: result, positionMap, skipped: [] }\n}\n\n/**\n * Escape HTML entities to prevent XSS injection.\n *\n * Converts special HTML characters to their entity equivalents:\n * - `&` → `&amp;`\n * - `<` → `&lt;`\n * - `>` → `&gt;`\n * - `\"` → `&quot;`\n * - `'` → `&#39;`\n * - `/` → `&#x2F;`\n *\n * @param text - Text to escape\n * @returns Escaped text safe for HTML insertion\n */\nfunction escapeHtmlEntities(text: string): string {\n  const map: Record<string, string> = {\n    '&': '&amp;',\n    '<': '&lt;',\n    '>': '&gt;',\n    '\"': '&quot;',\n    \"'\": '&#39;',\n    '/': '&#x2F;',\n  }\n  return text.replace(/[&<>\"'\\/]/g, (char) => map[char])\n}\n"],"mappings":"AA+CA,SAAgB,EACd,EACA,EACA,EAA6B,EAAE,CACb,CAClB,GAAM,CACJ,eAAe,GACf,aAAa,GACb,WACA,YACE,EAGE,EAAS,CAAC,GAAG,EAAU,CAAC,MAAM,EAAG,IAAM,CAC3C,IAAM,EAAO,EAAe,EAAE,KAAK,WAAa,EAAE,KAAK,cAEvD,OADa,EAAe,EAAE,KAAK,WAAa,EAAE,KAAK,eACzC,GACd,CAEE,EAAS,EACP,EAAc,IAAI,IAExB,IAAK,IAAM,KAAY,EAAQ,CAC7B,IAAM,EAAQ,EAAe,EAAS,KAAK,WAAa,EAAS,KAAK,cAChE,EAAM,EAAe,EAAS,KAAK,SAAW,EAAS,KAAK,YAE9D,EAAS,GAEb,GAAI,EAMF,EAAS,EAAS,EAJE,EAAK,UACvB,KAAK,IAAI,EAAG,EAAQ,GAAG,CACvB,KAAK,IAAI,EAAK,OAAQ,EAAM,GAAG,CAChC,CACuC,SAC/B,EAAU,CAEnB,IAAM,EAAe,EAAO,UAAU,EAAO,EAAI,CAC3C,EAAU,EAAa,EAAmB,EAAa,CAAG,EAChE,EAAS,EAAS,OAAS,EAAU,EAAS,WAG9C,SAIF,EAAS,EAAO,MAAM,EAAG,EAAM,CAAG,EAAS,EAAO,MAAM,EAAI,CAG5D,EAAY,IAAI,EAAO,EAAM,CAG/B,MAAO,CAAE,KAAM,EAAQ,cAAa,QAAS,EAAE,CAAE,CAiBnD,SAAS,EAAmB,EAAsB,CAChD,IAAM,EAA8B,CAClC,IAAK,QACL,IAAK,OACL,IAAK,OACL,IAAK,SACL,IAAK,QACL,IAAK,SACN,CACD,OAAO,EAAK,QAAQ,aAAe,GAAS,EAAI,GAAM"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/annotate/annotate.ts"],"sourcesContent":["import type { Citation } from '../types/citation'\nimport type { AnnotationOptions, AnnotationResult } from './types'\n\n/**\n * Annotate citations in text with custom markup.\n *\n * Supports two modes:\n * - **Template mode**: Simple before/after wrapping (set `options.template`)\n * - **Callback mode**: Custom logic with full citation context (set `options.callback`)\n *\n * Citations are processed in reverse order to avoid position shifts invalidating\n * subsequent annotations. Position tracking maps original positions to new positions\n * after markup insertion.\n *\n * @param text - Original or cleaned text to annotate\n * @param citations - Citations to mark up (from extraction pipeline)\n * @param options - Annotation configuration\n * @returns Annotated text with position mapping\n *\n * @example Template mode\n * ```typescript\n * const result = annotate(text, citations, {\n *   template: { before: '<cite>', after: '</cite>' }\n * })\n * // Result: \"See <cite>500 F.2d 123</cite>\"\n * ```\n *\n * @example Callback mode\n * ```typescript\n * const result = annotate(text, citations, {\n *   callback: (citation) => {\n *     if (citation.type === 'case') {\n *       return `<a href=\"/cases/${citation.volume}\">${citation.matchedText}</a>`\n *     }\n *     return citation.matchedText\n *   }\n * })\n * ```\n *\n * @example Position tracking\n * ```typescript\n * const result = annotate(text, citations, { template: { before: '<mark>', after: '</mark>' } })\n * // result.positionMap tracks how positions shifted\n * const originalPos = 10\n * const newPos = result.positionMap.get(originalPos)\n * ```\n */\nexport function annotate<C extends Citation = Citation>(\n  text: string,\n  citations: C[],\n  options: AnnotationOptions<C> = {}\n): AnnotationResult {\n  const {\n    useCleanText = false,\n    autoEscape = true,  // Secure by default\n    template,\n    callback,\n  } = options\n\n  // Sort reverse to avoid position shifts invalidating subsequent annotations\n  const sorted = [...citations].sort((a, b) => {\n    const aPos = useCleanText ? a.span.cleanStart : a.span.originalStart\n    const bPos = useCleanText ? b.span.cleanStart : b.span.originalStart\n    return bPos - aPos  // Reverse for backward iteration\n  })\n\n  let result = text\n  const positionMap = new Map<number, number>()\n\n  for (const citation of sorted) {\n    const start = useCleanText ? citation.span.cleanStart : citation.span.originalStart\n    const end = useCleanText ? citation.span.cleanEnd : citation.span.originalEnd\n\n    let markup = ''\n\n    if (callback) {\n      // Callback mode: developer provides full logic\n      const surrounding = text.substring(\n        Math.max(0, start - 30),\n        Math.min(text.length, end + 30)\n      )\n      markup = callback(citation, surrounding)\n    } else if (template) {\n      // Template mode: simple before/after wrapping\n      const citationText = result.substring(start, end)\n      const escaped = autoEscape ? escapeHtmlEntities(citationText) : citationText\n      markup = template.before + escaped + template.after\n    } else {\n      // No annotation specified\n      continue\n    }\n\n    // Insert annotation (working backwards preserves positions for later citations)\n    result = result.slice(0, start) + markup + result.slice(end)\n\n    // Track original position to new position (before this annotation was added)\n    positionMap.set(start, start)\n  }\n\n  return { text: result, positionMap, skipped: [] }\n}\n\n/**\n * Escape HTML entities to prevent XSS injection.\n *\n * Converts special HTML characters to their entity equivalents:\n * - `&` → `&amp;`\n * - `<` → `&lt;`\n * - `>` → `&gt;`\n * - `\"` → `&quot;`\n * - `'` → `&#39;`\n * - `/` → `&#x2F;`\n *\n * @param text - Text to escape\n * @returns Escaped text safe for HTML insertion\n */\nfunction escapeHtmlEntities(text: string): string {\n  const map: Record<string, string> = {\n    '&': '&amp;',\n    '<': '&lt;',\n    '>': '&gt;',\n    '\"': '&quot;',\n    \"'\": '&#39;',\n    '/': '&#x2F;',\n  }\n  return text.replace(/[&<>\"'\\/]/g, (char) => map[char])\n}\n"],"mappings":"AA+CA,SAAgB,EACd,EACA,EACA,EAAgC,EAAE,CAChB,CAClB,GAAM,CACJ,eAAe,GACf,aAAa,GACb,WACA,YACE,EAGE,EAAS,CAAC,GAAG,EAAU,CAAC,MAAM,EAAG,IAAM,CAC3C,IAAM,EAAO,EAAe,EAAE,KAAK,WAAa,EAAE,KAAK,cAEvD,OADa,EAAe,EAAE,KAAK,WAAa,EAAE,KAAK,eACzC,GACd,CAEE,EAAS,EACP,EAAc,IAAI,IAExB,IAAK,IAAM,KAAY,EAAQ,CAC7B,IAAM,EAAQ,EAAe,EAAS,KAAK,WAAa,EAAS,KAAK,cAChE,EAAM,EAAe,EAAS,KAAK,SAAW,EAAS,KAAK,YAE9D,EAAS,GAEb,GAAI,EAMF,EAAS,EAAS,EAJE,EAAK,UACvB,KAAK,IAAI,EAAG,EAAQ,GAAG,CACvB,KAAK,IAAI,EAAK,OAAQ,EAAM,GAAG,CAChC,CACuC,SAC/B,EAAU,CAEnB,IAAM,EAAe,EAAO,UAAU,EAAO,EAAI,CAC3C,EAAU,EAAa,EAAmB,EAAa,CAAG,EAChE,EAAS,EAAS,OAAS,EAAU,EAAS,WAG9C,SAIF,EAAS,EAAO,MAAM,EAAG,EAAM,CAAG,EAAS,EAAO,MAAM,EAAI,CAG5D,EAAY,IAAI,EAAO,EAAM,CAG/B,MAAO,CAAE,KAAM,EAAQ,cAAa,QAAS,EAAE,CAAE,CAiBnD,SAAS,EAAmB,EAAsB,CAChD,IAAM,EAA8B,CAClC,IAAK,QACL,IAAK,OACL,IAAK,OACL,IAAK,SACL,IAAK,QACL,IAAK,SACN,CACD,OAAO,EAAK,QAAQ,aAAe,GAAS,EAAI,GAAM"}

package/dist/{citation-8_GvfEuj.d.mts → citation-BhJJj_AZ.d.cts}

@@ -281,6 +281,36 @@ interface ShortFormCaseCitation extends CitationBase {
 * }
 */
 type Citation = FullCaseCitation | StatuteCitation | JournalCitation | NeutralCitation | PublicLawCitation | FederalRegisterCitation | IdCitation | SupraCitation | ShortFormCaseCitation;
+/**
+* Citation type discriminators grouped by category.
+*/
+type FullCitationType = "case" | "statute" | "journal" | "neutral" | "publicLaw" | "federalRegister";
+type ShortFormCitationType = "id" | "supra" | "shortFormCase";
+/**
+* Union of all full citation types (not short-form references).
+*/
+type FullCitation = FullCaseCitation | StatuteCitation | JournalCitation | NeutralCitation | PublicLawCitation | FederalRegisterCitation;
+/**
+* Union of all short-form citation types (Id., supra, short-form case).
+*/
+type ShortFormCitation = IdCitation | SupraCitation | ShortFormCaseCitation;
+/**
+* Extract the Citation subtype for a given type discriminator.
+*
+* @example
+* ```typescript
+* type CaseCit = CitationOfType<'case'>  // FullCaseCitation
+* type IdCit = CitationOfType<'id'>      // IdCitation
+* ```
+*/
+type CitationOfType<T extends CitationType> = Extract<Citation, {
+  type: T;
+}>;
+/**
+* Maps each full citation type to its concrete Citation subtype.
+* Useful for generic code building custom extraction pipelines.
+*/
+type ExtractorMap = { [K in FullCitationType]: CitationOfType<K> };
 //#endregion
-export { FullCaseCitation as a, NeutralCitation as c, StatuteCitation as d, SupraCitation as f, FederalRegisterCitation as i, PublicLawCitation as l, TransformationMap as m, CitationBase as n, IdCitation as o, Span as p, CitationType as r, JournalCitation as s, Citation as t, ShortFormCaseCitation as u };
-//# sourceMappingURL=citation-8_GvfEuj.d.mts.map
+export { StatuteCitation as _, ExtractorMap as a, Span as b, FullCitation as c, JournalCitation as d, NeutralCitation as f, ShortFormCitationType as g, ShortFormCitation as h, CitationType as i, FullCitationType as l, ShortFormCaseCitation as m, CitationBase as n, FederalRegisterCitation as o, PublicLawCitation as p, CitationOfType as r, FullCaseCitation as s, Citation as t, IdCitation as u, SupraCitation as v, TransformationMap as x, Warning as y };
+//# sourceMappingURL=citation-BhJJj_AZ.d.cts.map

package/dist/{citation-8_GvfEuj.d.mts.map → citation-BhJJj_AZ.d.cts.map}

@@ -1 +1 @@
-{"version":3,"file":"citation-8_GvfEuj.d.mts","names":[],"sources":["../src/types/span.ts","../src/types/citation.ts"],"mappings":";;AAiBA;;;;;;;;;;AAoBA;;;;;;UApBiB,IAAA;;EAEf,UAAA;EAuBiB;EApBjB,QAAA;;EAGA,aAAA;ECpBF;EDuBE,WAAA;AAAA;;;AClBF;;;;UD2BiB,iBAAA;;EAEf,eAAA,EAAiB,GAAA;;EAGjB,eAAA,EAAiB,GAAA;AAAA;;;AAzBnB;;;AAAA,KCZY,YAAA;;;;UAKK,OAAA;;EAEf,KAAA;EDyBF;ECvBE,OAAA;;EAEA,QAAA;IAAY,KAAA;IAAe,GAAA;EAAA;;EAE3B,OAAA;AAAA;;;;UAMe,YAAA;EAnBL;EAqBV,IAAA;EArBU;EAwBV,IAAA,EAAM,IAAA;EAnBR;;;;;;;EA4BE,UAAA;;EAGA,WAAA;;EAGA,aAAA;EApBF;EAuBE,eAAA;;EAGA,QAAA,GAAW,OAAA;AAAA;;;;;;;UASI,gBAAA,SAAyB,YAAA;EACxC,IAAA;EACA,MAAA;EACA,QAAA;EACA,IAAA;EACA,OAAA;EACA,KAAA;EACA,IAAA;;EAGA,kBAAA;;EAGA,iBAAA,GAAoB,KAAA;IAClB,MAAA;IACA,QAAA;IACA,IAAA;EAAA;;EAIF,MAAA;;EAGA,aAAA;;EAGA,iBAAA;;;;;;EAOA,IAAA;IACE,GAAA;IACA,MAAA;MAAW,IAAA;MAAc,KAAA;MAAgB,GAAA;IAAA;EAAA;;;;;EAO3C,uBAAA,GAA0B,KAAA;IACxB,MAAA;IACA,QAAA;IACA,IAAA;IACA,UAAA;IACA,MAAA;EAAA;AAAA;;;;;;UASa,eAAA,SAAwB,YAAA;EACvC,IAAA;EACA,KAAA;EACA,IAAA;EACA,OAAA;AAAA;;;;;;;;;UAWe,eAAA,SAAwB,YAAA;EACvC,IAAA;;EAEA,MAAA;EAcA;EAZA,KAAA;EAuBe;EArBf,MAAA;EAqBuC;EAnBvC,OAAA;;EAEA,YAAA;;EAEA,IAAA;;EAEA,OAAA;EA+BF;EA7BE,IAAA;AAAA;;;;;;;;;UAWe,eAAA,SAAwB,YAAA;EACvC,IAAA;;EAEA,IAAA;;EAEA,KAAA;;EAEA,cAAA;AAAA;;;AA6CF;;;;;;UAlCiB,iBAAA,SAA0B,YAAA;EACzC,IAAA;EAmCA;EAjCA,QAAA;EA0Ce;EAxCf,SAAA;EAwCqC;EAtCrC,KAAA;AAAA;;;;;AAoDF;;;;UAzCiB,uBAAA,SAAgC,YAAA;EAC/C,IAAA;;EAEA,MAAA;;EAEA,IAAA;;EAEA,IAAA;AAAA;;;;;;;UASe,UAAA,SAAmB,YAAA;EAClC,IAAA;EACA,OAAA;AAAA;;;;;;;UASe,aAAA,SAAsB,YAAA;EACrC,IAAA;;EAEA,SAAA;;EAEA,OAAA;AAAA;;;;;;;UASe,qBAAA,SAA8B,YAAA;EAC7C,IAAA;EACA,MAAA;EACA,QAAA;EACA,IAAA;EACA,OAAA;AAAA;;;;;;;;;;;;;;;;;;KAoBU,QAAA,GACR,gBAAA,GACA,eAAA,GACA,eAAA,GACA,eAAA,GACA,iBAAA,GACA,uBAAA,GACA,UAAA,GACA,aAAA,GACA,qBAAA"}
+{"version":3,"file":"citation-BhJJj_AZ.d.cts","names":[],"sources":["../src/types/span.ts","../src/types/citation.ts"],"mappings":";;AAiBA;;;;;;;;;;AAoBA;;;;;;UApBiB,IAAA;;EAEf,UAAA;EAuBiB;EApBjB,QAAA;;EAGA,aAAA;ECpBF;EDuBE,WAAA;AAAA;;;AClBF;;;;UD2BiB,iBAAA;;EAEf,eAAA,EAAiB,GAAA;;EAGjB,eAAA,EAAiB,GAAA;AAAA;;;AAzBnB;;;AAAA,KCZY,YAAA;;;;UAKK,OAAA;;EAEf,KAAA;EDyBF;ECvBE,OAAA;;EAEA,QAAA;IAAY,KAAA;IAAe,GAAA;EAAA;;EAE3B,OAAA;AAAA;;;;UAMe,YAAA;EAnBL;EAqBV,IAAA;EArBU;EAwBV,IAAA,EAAM,IAAA;EAnBR;;;;;;;EA4BE,UAAA;;EAGA,WAAA;;EAGA,aAAA;EApBF;EAuBE,eAAA;;EAGA,QAAA,GAAW,OAAA;AAAA;;;;;;;UASI,gBAAA,SAAyB,YAAA;EACxC,IAAA;EACA,MAAA;EACA,QAAA;EACA,IAAA;EACA,OAAA;EACA,KAAA;EACA,IAAA;;EAGA,kBAAA;;EAGA,iBAAA,GAAoB,KAAA;IAClB,MAAA;IACA,QAAA;IACA,IAAA;EAAA;;EAIF,MAAA;;EAGA,aAAA;;EAGA,iBAAA;;;;;;EAOA,IAAA;IACE,GAAA;IACA,MAAA;MAAW,IAAA;MAAc,KAAA;MAAgB,GAAA;IAAA;EAAA;;;;;EAO3C,uBAAA,GAA0B,KAAA;IACxB,MAAA;IACA,QAAA;IACA,IAAA;IACA,UAAA;IACA,MAAA;EAAA;AAAA;;;;;;UASa,eAAA,SAAwB,YAAA;EACvC,IAAA;EACA,KAAA;EACA,IAAA;EACA,OAAA;AAAA;;;;;;;;;UAWe,eAAA,SAAwB,YAAA;EACvC,IAAA;;EAEA,MAAA;EAcA;EAZA,KAAA;EAuBe;EArBf,MAAA;EAqBuC;EAnBvC,OAAA;;EAEA,YAAA;;EAEA,IAAA;;EAEA,OAAA;EA+BF;EA7BE,IAAA;AAAA;;;;;;;;;UAWe,eAAA,SAAwB,YAAA;EACvC,IAAA;;EAEA,IAAA;;EAEA,KAAA;;EAEA,cAAA;AAAA;;;AA6CF;;;;;;UAlCiB,iBAAA,SAA0B,YAAA;EACzC,IAAA;EAmCA;EAjCA,QAAA;EA0Ce;EAxCf,SAAA;EAwCqC;EAtCrC,KAAA;AAAA;;;;;AAoDF;;;;UAzCiB,uBAAA,SAAgC,YAAA;EAC/C,IAAA;;EAEA,MAAA;;EAEA,IAAA;;EAEA,IAAA;AAAA;;;;;;;UASe,UAAA,SAAmB,YAAA;EAClC,IAAA;EACA,OAAA;AAAA;;;;;;;UASe,aAAA,SAAsB,YAAA;EACrC,IAAA;;EAEA,SAAA;;EAEA,OAAA;AAAA;;AAgDF;;;;;UAvCiB,qBAAA,SAA8B,YAAA;EAC7C,IAAA;EACA,MAAA;EACA,QAAA;EACA,IAAA;EACA,OAAA;AAAA;;;;;;;;;;;;;;;;;;KAoBU,QAAA,GACR,gBAAA,GACA,eAAA,GACA,eAAA,GACA,eAAA,GACA,iBAAA,GACA,uBAAA,GACA,UAAA,GACA,aAAA,GACA,qBAAA;;;;KAKQ,gBAAA;AAAA,KACA,qBAAA;;;;KAKA,YAAA,GAAe,gBAAA,GAAmB,eAAA,GAAkB,eAAA,GAAkB,eAAA,GAAkB,iBAAA,GAAoB,uBAAA;;;;KAK5G,iBAAA,GAAoB,UAAA,GAAa,aAAA,GAAgB,qBAAA;;;;;;;;;;KAWjD,cAAA,WAAyB,YAAA,IAAgB,OAAA,CAAQ,QAAA;EAAY,IAAA,EAAM,CAAA;AAAA;;;;;KAMnE,YAAA,WACJ,gBAAA,GAAmB,cAAA,CAAe,CAAA"}

package/dist/{citation-BcY5zzWb.d.cts → citation-FJ10UFM7.d.mts}

@@ -281,6 +281,36 @@ interface ShortFormCaseCitation extends CitationBase {
 * }
 */
 type Citation = FullCaseCitation | StatuteCitation | JournalCitation | NeutralCitation | PublicLawCitation | FederalRegisterCitation | IdCitation | SupraCitation | ShortFormCaseCitation;
+/**
+* Citation type discriminators grouped by category.
+*/
+type FullCitationType = "case" | "statute" | "journal" | "neutral" | "publicLaw" | "federalRegister";
+type ShortFormCitationType = "id" | "supra" | "shortFormCase";
+/**
+* Union of all full citation types (not short-form references).
+*/
+type FullCitation = FullCaseCitation | StatuteCitation | JournalCitation | NeutralCitation | PublicLawCitation | FederalRegisterCitation;
+/**
+* Union of all short-form citation types (Id., supra, short-form case).
+*/
+type ShortFormCitation = IdCitation | SupraCitation | ShortFormCaseCitation;
+/**
+* Extract the Citation subtype for a given type discriminator.
+*
+* @example
+* ```typescript
+* type CaseCit = CitationOfType<'case'>  // FullCaseCitation
+* type IdCit = CitationOfType<'id'>      // IdCitation
+* ```
+*/
+type CitationOfType<T extends CitationType> = Extract<Citation, {
+  type: T;
+}>;
+/**
+* Maps each full citation type to its concrete Citation subtype.
+* Useful for generic code building custom extraction pipelines.
+*/
+type ExtractorMap = { [K in FullCitationType]: CitationOfType<K> };
 //#endregion
-export { FullCaseCitation as a, NeutralCitation as c, StatuteCitation as d, SupraCitation as f, FederalRegisterCitation as i, PublicLawCitation as l, TransformationMap as m, CitationBase as n, IdCitation as o, Span as p, CitationType as r, JournalCitation as s, Citation as t, ShortFormCaseCitation as u };
-//# sourceMappingURL=citation-BcY5zzWb.d.cts.map
+export { StatuteCitation as _, ExtractorMap as a, Span as b, FullCitation as c, JournalCitation as d, NeutralCitation as f, ShortFormCitationType as g, ShortFormCitation as h, CitationType as i, FullCitationType as l, ShortFormCaseCitation as m, CitationBase as n, FederalRegisterCitation as o, PublicLawCitation as p, CitationOfType as r, FullCaseCitation as s, Citation as t, IdCitation as u, SupraCitation as v, TransformationMap as x, Warning as y };
+//# sourceMappingURL=citation-FJ10UFM7.d.mts.map

package/dist/{citation-BcY5zzWb.d.cts.map → citation-FJ10UFM7.d.mts.map}

@@ -1 +1 @@
-{"version":3,"file":"citation-BcY5zzWb.d.cts","names":[],"sources":["../src/types/span.ts","../src/types/citation.ts"],"mappings":";;AAiBA;;;;;;;;;;AAoBA;;;;;;UApBiB,IAAA;;EAEf,UAAA;EAuBiB;EApBjB,QAAA;;EAGA,aAAA;ECpBF;EDuBE,WAAA;AAAA;;;AClBF;;;;UD2BiB,iBAAA;;EAEf,eAAA,EAAiB,GAAA;;EAGjB,eAAA,EAAiB,GAAA;AAAA;;;AAzBnB;;;AAAA,KCZY,YAAA;;;;UAKK,OAAA;;EAEf,KAAA;EDyBF;ECvBE,OAAA;;EAEA,QAAA;IAAY,KAAA;IAAe,GAAA;EAAA;;EAE3B,OAAA;AAAA;;;;UAMe,YAAA;EAnBL;EAqBV,IAAA;EArBU;EAwBV,IAAA,EAAM,IAAA;EAnBR;;;;;;;EA4BE,UAAA;;EAGA,WAAA;;EAGA,aAAA;EApBF;EAuBE,eAAA;;EAGA,QAAA,GAAW,OAAA;AAAA;;;;;;;UASI,gBAAA,SAAyB,YAAA;EACxC,IAAA;EACA,MAAA;EACA,QAAA;EACA,IAAA;EACA,OAAA;EACA,KAAA;EACA,IAAA;;EAGA,kBAAA;;EAGA,iBAAA,GAAoB,KAAA;IAClB,MAAA;IACA,QAAA;IACA,IAAA;EAAA;;EAIF,MAAA;;EAGA,aAAA;;EAGA,iBAAA;;;;;;EAOA,IAAA;IACE,GAAA;IACA,MAAA;MAAW,IAAA;MAAc,KAAA;MAAgB,GAAA;IAAA;EAAA;;;;;EAO3C,uBAAA,GAA0B,KAAA;IACxB,MAAA;IACA,QAAA;IACA,IAAA;IACA,UAAA;IACA,MAAA;EAAA;AAAA;;;;;;UASa,eAAA,SAAwB,YAAA;EACvC,IAAA;EACA,KAAA;EACA,IAAA;EACA,OAAA;AAAA;;;;;;;;;UAWe,eAAA,SAAwB,YAAA;EACvC,IAAA;;EAEA,MAAA;EAcA;EAZA,KAAA;EAuBe;EArBf,MAAA;EAqBuC;EAnBvC,OAAA;;EAEA,YAAA;;EAEA,IAAA;;EAEA,OAAA;EA+BF;EA7BE,IAAA;AAAA;;;;;;;;;UAWe,eAAA,SAAwB,YAAA;EACvC,IAAA;;EAEA,IAAA;;EAEA,KAAA;;EAEA,cAAA;AAAA;;;AA6CF;;;;;;UAlCiB,iBAAA,SAA0B,YAAA;EACzC,IAAA;EAmCA;EAjCA,QAAA;EA0Ce;EAxCf,SAAA;EAwCqC;EAtCrC,KAAA;AAAA;;;;;AAoDF;;;;UAzCiB,uBAAA,SAAgC,YAAA;EAC/C,IAAA;;EAEA,MAAA;;EAEA,IAAA;;EAEA,IAAA;AAAA;;;;;;;UASe,UAAA,SAAmB,YAAA;EAClC,IAAA;EACA,OAAA;AAAA;;;;;;;UASe,aAAA,SAAsB,YAAA;EACrC,IAAA;;EAEA,SAAA;;EAEA,OAAA;AAAA;;;;;;;UASe,qBAAA,SAA8B,YAAA;EAC7C,IAAA;EACA,MAAA;EACA,QAAA;EACA,IAAA;EACA,OAAA;AAAA;;;;;;;;;;;;;;;;;;KAoBU,QAAA,GACR,gBAAA,GACA,eAAA,GACA,eAAA,GACA,eAAA,GACA,iBAAA,GACA,uBAAA,GACA,UAAA,GACA,aAAA,GACA,qBAAA"}
+{"version":3,"file":"citation-FJ10UFM7.d.mts","names":[],"sources":["../src/types/span.ts","../src/types/citation.ts"],"mappings":";;AAiBA;;;;;;;;;;AAoBA;;;;;;UApBiB,IAAA;;EAEf,UAAA;EAuBiB;EApBjB,QAAA;;EAGA,aAAA;ECpBF;EDuBE,WAAA;AAAA;;;AClBF;;;;UD2BiB,iBAAA;;EAEf,eAAA,EAAiB,GAAA;;EAGjB,eAAA,EAAiB,GAAA;AAAA;;;AAzBnB;;;AAAA,KCZY,YAAA;;;;UAKK,OAAA;;EAEf,KAAA;EDyBF;ECvBE,OAAA;;EAEA,QAAA;IAAY,KAAA;IAAe,GAAA;EAAA;;EAE3B,OAAA;AAAA;;;;UAMe,YAAA;EAnBL;EAqBV,IAAA;EArBU;EAwBV,IAAA,EAAM,IAAA;EAnBR;;;;;;;EA4BE,UAAA;;EAGA,WAAA;;EAGA,aAAA;EApBF;EAuBE,eAAA;;EAGA,QAAA,GAAW,OAAA;AAAA;;;;;;;UASI,gBAAA,SAAyB,YAAA;EACxC,IAAA;EACA,MAAA;EACA,QAAA;EACA,IAAA;EACA,OAAA;EACA,KAAA;EACA,IAAA;;EAGA,kBAAA;;EAGA,iBAAA,GAAoB,KAAA;IAClB,MAAA;IACA,QAAA;IACA,IAAA;EAAA;;EAIF,MAAA;;EAGA,aAAA;;EAGA,iBAAA;;;;;;EAOA,IAAA;IACE,GAAA;IACA,MAAA;MAAW,IAAA;MAAc,KAAA;MAAgB,GAAA;IAAA;EAAA;;;;;EAO3C,uBAAA,GAA0B,KAAA;IACxB,MAAA;IACA,QAAA;IACA,IAAA;IACA,UAAA;IACA,MAAA;EAAA;AAAA;;;;;;UASa,eAAA,SAAwB,YAAA;EACvC,IAAA;EACA,KAAA;EACA,IAAA;EACA,OAAA;AAAA;;;;;;;;;UAWe,eAAA,SAAwB,YAAA;EACvC,IAAA;;EAEA,MAAA;EAcA;EAZA,KAAA;EAuBe;EArBf,MAAA;EAqBuC;EAnBvC,OAAA;;EAEA,YAAA;;EAEA,IAAA;;EAEA,OAAA;EA+BF;EA7BE,IAAA;AAAA;;;;;;;;;UAWe,eAAA,SAAwB,YAAA;EACvC,IAAA;;EAEA,IAAA;;EAEA,KAAA;;EAEA,cAAA;AAAA;;;AA6CF;;;;;;UAlCiB,iBAAA,SAA0B,YAAA;EACzC,IAAA;EAmCA;EAjCA,QAAA;EA0Ce;EAxCf,SAAA;EAwCqC;EAtCrC,KAAA;AAAA;;;;;AAoDF;;;;UAzCiB,uBAAA,SAAgC,YAAA;EAC/C,IAAA;;EAEA,MAAA;;EAEA,IAAA;;EAEA,IAAA;AAAA;;;;;;;UASe,UAAA,SAAmB,YAAA;EAClC,IAAA;EACA,OAAA;AAAA;;;;;;;UASe,aAAA,SAAsB,YAAA;EACrC,IAAA;;EAEA,SAAA;;EAEA,OAAA;AAAA;;AAgDF;;;;;UAvCiB,qBAAA,SAA8B,YAAA;EAC7C,IAAA;EACA,MAAA;EACA,QAAA;EACA,IAAA;EACA,OAAA;AAAA;;;;;;;;;;;;;;;;;;KAoBU,QAAA,GACR,gBAAA,GACA,eAAA,GACA,eAAA,GACA,eAAA,GACA,iBAAA,GACA,uBAAA,GACA,UAAA,GACA,aAAA,GACA,qBAAA;;;;KAKQ,gBAAA;AAAA,KACA,qBAAA;;;;KAKA,YAAA,GAAe,gBAAA,GAAmB,eAAA,GAAkB,eAAA,GAAkB,eAAA,GAAkB,iBAAA,GAAoB,uBAAA;;;;KAK5G,iBAAA,GAAoB,UAAA,GAAa,aAAA,GAAgB,qBAAA;;;;;;;;;;KAWjD,cAAA,WAAyB,YAAA,IAAgB,OAAA,CAAQ,QAAA;EAAY,IAAA,EAAM,CAAA;AAAA;;;;;KAMnE,YAAA,WACJ,gBAAA,GAAmB,cAAA,CAAe,CAAA"}