eyecite-ts 0.1.0

package/dist/annotate/index.mjs.map

@@ -0,0 +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"}

package/dist/citation-8_GvfEuj.d.mts

@@ -0,0 +1,286 @@
+//#region src/types/span.d.ts
+/**
+* Represents a text span with positions tracked through transformations.
+*
+* During text cleaning (HTML removal, whitespace normalization), positions
+* shift. Span tracks BOTH cleaned positions (for parsing) and original
+* positions (for user-facing results).
+*
+* @example
+* const original = "Smith v. Doe, 500 F.2d 123 (2020)"
+* // After cleaning, positions may shift
+* const span: Span = {
+*   cleanStart: 14,  // Position in cleaned text
+*   cleanEnd: 27,
+*   originalStart: 14,  // Position in original text
+*   originalEnd: 27
+* }
+*/
+interface Span {
+  /** Start position in cleaned/tokenized text (used during parsing) */
+  cleanStart: number;
+  /** End position in cleaned/tokenized text (used during parsing) */
+  cleanEnd: number;
+  /** Start position in original input text (returned to user) */
+  originalStart: number;
+  /** End position in original input text (returned to user) */
+  originalEnd: number;
+}
+/**
+* Maps positions between cleaned and original text.
+*
+* Built during text transformation to track how character positions shift
+* when HTML entities are removed, whitespace is normalized, etc.
+*/
+interface TransformationMap {
+  /** Maps cleaned text position to original text position */
+  cleanToOriginal: Map<number, number>;
+  /** Maps original text position to cleaned text position */
+  originalToClean: Map<number, number>;
+}
+//#endregion
+//#region src/types/citation.d.ts
+/**
+* Citation type discriminator for type-safe pattern matching.
+*/
+type CitationType = "case" | "statute" | "journal" | "neutral" | "publicLaw" | "federalRegister" | "id" | "supra" | "shortFormCase";
+/**
+* Warning generated during citation parsing.
+*/
+interface Warning {
+  /** Severity level */
+  level: "error" | "warning" | "info";
+  /** Description of the issue */
+  message: string;
+  /** Position of the problematic region */
+  position: {
+    start: number;
+    end: number;
+  };
+  /** Additional context about the warning */
+  context?: string;
+}
+/**
+* Base fields shared by all citation types.
+*/
+interface CitationBase {
+  /** Original matched text */
+  text: string;
+  /** Position span in document (originalStart/End point to original text) */
+  span: Span;
+  /**
+  * Confidence score indicating match certainty (0-1).
+  * - 1.0: Certain match (e.g., exact reporter abbreviation in reporters-db)
+  * - 0.8-0.99: High confidence (e.g., common pattern, missing pincite)
+  * - 0.5-0.79: Medium confidence (e.g., ambiguous reporter abbreviation)
+  * - <0.5: Low confidence (e.g., unusual formatting)
+  */
+  confidence: number;
+  /** Exact substring matched from the original text */
+  matchedText: string;
+  /** Time spent processing this citation (milliseconds) */
+  processTimeMs: number;
+  /** Number of regex patterns checked before match */
+  patternsChecked: number;
+  /** Warnings for malformed or ambiguous regions */
+  warnings?: Warning[];
+}
+/**
+* Full case citation (volume-reporter-page format).
+*
+* @example "500 F.2d 123"
+* @example "410 U.S. 113, 115"
+*/
+interface FullCaseCitation extends CitationBase {
+  type: "case";
+  volume: number;
+  reporter: string;
+  page: number;
+  pincite?: number;
+  court?: string;
+  year?: number;
+  /** Normalized reporter abbreviation from reporters-db (e.g., "F.2d" vs "F. 2d") */
+  normalizedReporter?: string;
+  /** Parallel citations for same case in different reporters */
+  parallelCitations?: Array<{
+    volume: number;
+    reporter: string;
+    page: number;
+  }>;
+  /** Citation signal (introductory phrase) */
+  signal?: "see" | "see also" | "cf" | "but see" | "compare";
+  /** Parenthetical explanation following the citation */
+  parenthetical?: string;
+  /** Subsequent procedural history (e.g., "aff'd", "rev'd", "cert. denied") */
+  subsequentHistory?: string;
+  /**
+  * Date information in multiple formats.
+  * - iso: ISO 8601 format (YYYY-MM-DD or YYYY-MM-DDTHH:mm:ssZ)
+  * - parsed: Structured date components
+  */
+  date?: {
+    iso: string;
+    parsed?: {
+      year: number;
+      month?: number;
+      day?: number;
+    };
+  };
+  /**
+  * Alternative interpretations for ambiguous citations.
+  * Used when reporter abbreviation matches multiple reporters or format is unclear.
+  */
+  possibleInterpretations?: Array<{
+    volume: number;
+    reporter: string;
+    page: number;
+    confidence: number;
+    reason: string;
+  }>;
+}
+/**
+* Statute citation (U.S. Code, state codes, etc.).
+*
+* @example "42 U.S.C. § 1983"
+*/
+interface StatuteCitation extends CitationBase {
+  type: "statute";
+  title?: number;
+  code: string;
+  section: string;
+}
+/**
+* Journal citation (law review, legal periodical).
+*
+* Format: [Author,] [Title,] Volume Journal Page [, Pincite] [(Year)]
+*
+* @example "100 Harv. L. Rev. 1234"
+* @example "Jane Doe, Article Title, 75 Yale L.J. 456, 460 (2020)"
+*/
+interface JournalCitation extends CitationBase {
+  type: "journal";
+  /** Author name (if extracted) */
+  author?: string;
+  /** Article title (if extracted) */
+  title?: string;
+  /** Volume number */
+  volume?: number;
+  /** Full journal name */
+  journal: string;
+  /** Standard journal abbreviation (e.g., "Harv. L. Rev.") */
+  abbreviation: string;
+  /** Starting page of article */
+  page?: number;
+  /** Specific page reference */
+  pincite?: number;
+  /** Publication year */
+  year?: number;
+}
+/**
+* Neutral citation (vendor-neutral format).
+*
+* Format: Year Court DocumentNumber
+*
+* @example "2020 WL 123456" (Westlaw)
+* @example "2020 U.S. LEXIS 456" (Lexis)
+*/
+interface NeutralCitation extends CitationBase {
+  type: "neutral";
+  /** Year of decision */
+  year: number;
+  /** Court identifier (e.g., "WL", "U.S. LEXIS") */
+  court: string;
+  /** Document number */
+  documentNumber: string;
+}
+/**
+* Public law citation (federal legislation).
+*
+* Format: Pub. L. No. Congress-LawNumber
+*
+* @example "Pub. L. No. 116-283"
+* @example "Pub. L. 117-58 (Infrastructure Investment and Jobs Act)"
+*/
+interface PublicLawCitation extends CitationBase {
+  type: "publicLaw";
+  /** Congress number (e.g., 116) */
+  congress: number;
+  /** Law number within that Congress */
+  lawNumber: number;
+  /** Optional bill title extracted from nearby text */
+  title?: string;
+}
+/**
+* Federal Register citation.
+*
+* Format: Volume Fed. Reg. Page
+*
+* @example "85 Fed. Reg. 12345"
+* @example "86 Fed. Reg. 56789 (Jan. 15, 2021)"
+*/
+interface FederalRegisterCitation extends CitationBase {
+  type: "federalRegister";
+  /** Federal Register volume */
+  volume: number;
+  /** Page number */
+  page: number;
+  /** Publication year (if extracted) */
+  year?: number;
+}
+/**
+* Id. citation (refers to immediately preceding citation).
+*
+* @example "Id."
+* @example "Id. at 125"
+*/
+interface IdCitation extends CitationBase {
+  type: "id";
+  pincite?: number;
+}
+/**
+* Supra citation (refers to earlier citation by party name).
+*
+* @example "Smith, supra"
+* @example "Smith, supra, at 460"
+*/
+interface SupraCitation extends CitationBase {
+  type: "supra";
+  /** Party name extracted from citation text */
+  partyName: string;
+  /** Specific page reference */
+  pincite?: number;
+}
+/**
+* Short-form case citation (abbreviated reference to earlier full citation).
+* Distinguished from full case by lack of case name.
+*
+* @example "500 F.2d at 125" (refers to earlier full citation at different page)
+*/
+interface ShortFormCaseCitation extends CitationBase {
+  type: "shortFormCase";
+  volume: number;
+  reporter: string;
+  page?: number;
+  pincite?: number;
+}
+/**
+* Union type of all citation types.
+*
+* Use type guards via discriminated union:
+* @example
+* if (citation.type === "case") {
+*   console.log(citation.volume) // TypeScript knows this exists
+* }
+* @example
+* switch (citation.type) {
+*   case "journal":
+*     return citation.abbreviation // Type-safe access
+*   case "neutral":
+*     return citation.court
+*   // ...
+* }
+*/
+type Citation = FullCaseCitation | StatuteCitation | JournalCitation | NeutralCitation | PublicLawCitation | FederalRegisterCitation | IdCitation | SupraCitation | ShortFormCaseCitation;
+//#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

package/dist/citation-8_GvfEuj.d.mts.map

@@ -0,0 +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"}

package/dist/citation-BcY5zzWb.d.cts

@@ -0,0 +1,286 @@
+//#region src/types/span.d.ts
+/**
+* Represents a text span with positions tracked through transformations.
+*
+* During text cleaning (HTML removal, whitespace normalization), positions
+* shift. Span tracks BOTH cleaned positions (for parsing) and original
+* positions (for user-facing results).
+*
+* @example
+* const original = "Smith v. Doe, 500 F.2d 123 (2020)"
+* // After cleaning, positions may shift
+* const span: Span = {
+*   cleanStart: 14,  // Position in cleaned text
+*   cleanEnd: 27,
+*   originalStart: 14,  // Position in original text
+*   originalEnd: 27
+* }
+*/
+interface Span {
+  /** Start position in cleaned/tokenized text (used during parsing) */
+  cleanStart: number;
+  /** End position in cleaned/tokenized text (used during parsing) */
+  cleanEnd: number;
+  /** Start position in original input text (returned to user) */
+  originalStart: number;
+  /** End position in original input text (returned to user) */
+  originalEnd: number;
+}
+/**
+* Maps positions between cleaned and original text.
+*
+* Built during text transformation to track how character positions shift
+* when HTML entities are removed, whitespace is normalized, etc.
+*/
+interface TransformationMap {
+  /** Maps cleaned text position to original text position */
+  cleanToOriginal: Map<number, number>;
+  /** Maps original text position to cleaned text position */
+  originalToClean: Map<number, number>;
+}
+//#endregion
+//#region src/types/citation.d.ts
+/**
+* Citation type discriminator for type-safe pattern matching.
+*/
+type CitationType = "case" | "statute" | "journal" | "neutral" | "publicLaw" | "federalRegister" | "id" | "supra" | "shortFormCase";
+/**
+* Warning generated during citation parsing.
+*/
+interface Warning {
+  /** Severity level */
+  level: "error" | "warning" | "info";
+  /** Description of the issue */
+  message: string;
+  /** Position of the problematic region */
+  position: {
+    start: number;
+    end: number;
+  };
+  /** Additional context about the warning */
+  context?: string;
+}
+/**
+* Base fields shared by all citation types.
+*/
+interface CitationBase {
+  /** Original matched text */
+  text: string;
+  /** Position span in document (originalStart/End point to original text) */
+  span: Span;
+  /**
+  * Confidence score indicating match certainty (0-1).
+  * - 1.0: Certain match (e.g., exact reporter abbreviation in reporters-db)
+  * - 0.8-0.99: High confidence (e.g., common pattern, missing pincite)
+  * - 0.5-0.79: Medium confidence (e.g., ambiguous reporter abbreviation)
+  * - <0.5: Low confidence (e.g., unusual formatting)
+  */
+  confidence: number;
+  /** Exact substring matched from the original text */
+  matchedText: string;
+  /** Time spent processing this citation (milliseconds) */
+  processTimeMs: number;
+  /** Number of regex patterns checked before match */
+  patternsChecked: number;
+  /** Warnings for malformed or ambiguous regions */
+  warnings?: Warning[];
+}
+/**
+* Full case citation (volume-reporter-page format).
+*
+* @example "500 F.2d 123"
+* @example "410 U.S. 113, 115"
+*/
+interface FullCaseCitation extends CitationBase {
+  type: "case";
+  volume: number;
+  reporter: string;
+  page: number;
+  pincite?: number;
+  court?: string;
+  year?: number;
+  /** Normalized reporter abbreviation from reporters-db (e.g., "F.2d" vs "F. 2d") */
+  normalizedReporter?: string;
+  /** Parallel citations for same case in different reporters */
+  parallelCitations?: Array<{
+    volume: number;
+    reporter: string;
+    page: number;
+  }>;
+  /** Citation signal (introductory phrase) */
+  signal?: "see" | "see also" | "cf" | "but see" | "compare";
+  /** Parenthetical explanation following the citation */
+  parenthetical?: string;
+  /** Subsequent procedural history (e.g., "aff'd", "rev'd", "cert. denied") */
+  subsequentHistory?: string;
+  /**
+  * Date information in multiple formats.
+  * - iso: ISO 8601 format (YYYY-MM-DD or YYYY-MM-DDTHH:mm:ssZ)
+  * - parsed: Structured date components
+  */
+  date?: {
+    iso: string;
+    parsed?: {
+      year: number;
+      month?: number;
+      day?: number;
+    };
+  };
+  /**
+  * Alternative interpretations for ambiguous citations.
+  * Used when reporter abbreviation matches multiple reporters or format is unclear.
+  */
+  possibleInterpretations?: Array<{
+    volume: number;
+    reporter: string;
+    page: number;
+    confidence: number;
+    reason: string;
+  }>;
+}
+/**
+* Statute citation (U.S. Code, state codes, etc.).
+*
+* @example "42 U.S.C. § 1983"
+*/
+interface StatuteCitation extends CitationBase {
+  type: "statute";
+  title?: number;
+  code: string;
+  section: string;
+}
+/**
+* Journal citation (law review, legal periodical).
+*
+* Format: [Author,] [Title,] Volume Journal Page [, Pincite] [(Year)]
+*
+* @example "100 Harv. L. Rev. 1234"
+* @example "Jane Doe, Article Title, 75 Yale L.J. 456, 460 (2020)"
+*/
+interface JournalCitation extends CitationBase {
+  type: "journal";
+  /** Author name (if extracted) */
+  author?: string;
+  /** Article title (if extracted) */
+  title?: string;
+  /** Volume number */
+  volume?: number;
+  /** Full journal name */
+  journal: string;
+  /** Standard journal abbreviation (e.g., "Harv. L. Rev.") */
+  abbreviation: string;
+  /** Starting page of article */
+  page?: number;
+  /** Specific page reference */
+  pincite?: number;
+  /** Publication year */
+  year?: number;
+}
+/**
+* Neutral citation (vendor-neutral format).
+*
+* Format: Year Court DocumentNumber
+*
+* @example "2020 WL 123456" (Westlaw)
+* @example "2020 U.S. LEXIS 456" (Lexis)
+*/
+interface NeutralCitation extends CitationBase {
+  type: "neutral";
+  /** Year of decision */
+  year: number;
+  /** Court identifier (e.g., "WL", "U.S. LEXIS") */
+  court: string;
+  /** Document number */
+  documentNumber: string;
+}
+/**
+* Public law citation (federal legislation).
+*
+* Format: Pub. L. No. Congress-LawNumber
+*
+* @example "Pub. L. No. 116-283"
+* @example "Pub. L. 117-58 (Infrastructure Investment and Jobs Act)"
+*/
+interface PublicLawCitation extends CitationBase {
+  type: "publicLaw";
+  /** Congress number (e.g., 116) */
+  congress: number;
+  /** Law number within that Congress */
+  lawNumber: number;
+  /** Optional bill title extracted from nearby text */
+  title?: string;
+}
+/**
+* Federal Register citation.
+*
+* Format: Volume Fed. Reg. Page
+*
+* @example "85 Fed. Reg. 12345"
+* @example "86 Fed. Reg. 56789 (Jan. 15, 2021)"
+*/
+interface FederalRegisterCitation extends CitationBase {
+  type: "federalRegister";
+  /** Federal Register volume */
+  volume: number;
+  /** Page number */
+  page: number;
+  /** Publication year (if extracted) */
+  year?: number;
+}
+/**
+* Id. citation (refers to immediately preceding citation).
+*
+* @example "Id."
+* @example "Id. at 125"
+*/
+interface IdCitation extends CitationBase {
+  type: "id";
+  pincite?: number;
+}
+/**
+* Supra citation (refers to earlier citation by party name).
+*
+* @example "Smith, supra"
+* @example "Smith, supra, at 460"
+*/
+interface SupraCitation extends CitationBase {
+  type: "supra";
+  /** Party name extracted from citation text */
+  partyName: string;
+  /** Specific page reference */
+  pincite?: number;
+}
+/**
+* Short-form case citation (abbreviated reference to earlier full citation).
+* Distinguished from full case by lack of case name.
+*
+* @example "500 F.2d at 125" (refers to earlier full citation at different page)
+*/
+interface ShortFormCaseCitation extends CitationBase {
+  type: "shortFormCase";
+  volume: number;
+  reporter: string;
+  page?: number;
+  pincite?: number;
+}
+/**
+* Union type of all citation types.
+*
+* Use type guards via discriminated union:
+* @example
+* if (citation.type === "case") {
+*   console.log(citation.volume) // TypeScript knows this exists
+* }
+* @example
+* switch (citation.type) {
+*   case "journal":
+*     return citation.abbreviation // Type-safe access
+*   case "neutral":
+*     return citation.court
+*   // ...
+* }
+*/
+type Citation = FullCaseCitation | StatuteCitation | JournalCitation | NeutralCitation | PublicLawCitation | FederalRegisterCitation | IdCitation | SupraCitation | ShortFormCaseCitation;
+//#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

package/dist/citation-BcY5zzWb.d.cts.map

@@ -0,0 +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"}

package/dist/data/index.cjs

@@ -0,0 +1,2 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=null;async function t(){if(e)return e;let t=await import(`../../data/reporters.json`,{assert:{type:`json`}}),n=new Map,r=[],i=t.default||t;for(let[e,t]of Object.entries(i))for(let e of t){r.push(e);for(let t of Object.keys(e.editions)){let r=t.toLowerCase();n.has(r)||n.set(r,[]),n.get(r).push(e)}for(let[t,r]of Object.entries(e.variations||{})){let r=t.toLowerCase();n.has(r)||n.set(r,[]),n.get(r).push(e)}}return e={byAbbreviation:n,all:r},e}function n(){return e}async function r(e){return(await t()).byAbbreviation.get(e.toLowerCase())??[]}exports.findReportersByAbbreviation=r,exports.getReportersSync=n,exports.loadReporters=t;
+//# sourceMappingURL=index.cjs.map

package/dist/data/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../../src/data/reporters.ts"],"sourcesContent":["/**\n * Reporter database integration for citation validation\n *\n * This module provides lazy-loadable access to the reporters-db database,\n * containing 1200+ court reporters with variant forms. The library works\n * in degraded mode (pattern-based extraction only) if reporters are not loaded.\n *\n * @example\n * // Degraded mode: extraction works without reporter data\n * const citations = await extract(text)\n *\n * @example\n * // Full mode: load reporters for validation\n * await loadReporters()\n * const citations = await extract(text)  // Now with reporter validation\n */\n\n/**\n * Edition entry from reporters-db\n *\n * Represents a specific edition of a reporter with start/end dates.\n */\nexport interface ReporterEdition {\n  /** Start date in ISO 8601 format */\n  start: string | null\n  /** End date in ISO 8601 format (null if ongoing) */\n  end: string | null\n}\n\n/**\n * Reporter entry from reporters-db\n *\n * Represents a single court reporter with all metadata needed for\n * citation validation and enrichment.\n *\n * Note: The reporters-db structure has the actual data; this interface\n * represents it flexibly to handle all variations in the JSON.\n */\nexport interface ReporterEntry {\n  /** Full reporter name (e.g., \"Federal Reporter\") */\n  name: string\n  /** Citation type: state, federal, specialty, neutral, state_regional, etc. */\n  cite_type: string\n  /** Editions keyed by abbreviation (e.g., {\"F.2d\": {...}, \"F.3d\": {...}}) */\n  editions: Record<string, ReporterEdition>\n  /** Variant forms mapped to canonical form (e.g., {\"F. 2d\": \"F.2d\"}) */\n  variations?: Record<string, string | undefined>\n  /** MLZ jurisdiction identifiers (optional) */\n  mlz_jurisdiction?: string[]\n  /** Publisher (optional) */\n  publisher?: string\n  /** Notes (optional) */\n  notes?: string\n}\n\n/**\n * In-memory reporter database with fast O(1) lookup\n *\n * Uses Map-based indexing for case-insensitive abbreviation lookup.\n * All variant forms are indexed to support fuzzy matching.\n */\nexport interface ReportersDatabase {\n  /** Fast O(1) lookup by abbreviation (lowercase normalized keys) */\n  byAbbreviation: Map<string, ReporterEntry[]>\n  /** All reporters (for iteration/filtering) */\n  all: ReporterEntry[]\n}\n\n/**\n * Cached database instance (null until loadReporters() called)\n */\nlet cached: ReportersDatabase | null = null\n\n/**\n * Load reporter database asynchronously with lazy loading\n *\n * Dynamic import prevents loading 1200+ reporters until explicitly requested.\n * Result is cached after first load for subsequent calls.\n *\n * @returns Promise resolving to indexed reporter database\n *\n * @example\n * const db = await loadReporters()\n * const reporters = db.byAbbreviation.get('f.2d')  // Fast O(1) lookup\n */\nexport async function loadReporters(): Promise<ReportersDatabase> {\n  if (cached) return cached\n\n  // Dynamic import prevents loading until requested (keeps core bundle small)\n  const data = await import(\"../../data/reporters.json\", {\n    assert: { type: \"json\" },\n  })\n\n  const byAbbreviation = new Map<string, ReporterEntry[]>()\n  const all: ReporterEntry[] = []\n\n  // reporters.json structure: { \"A.\": [...], \"F.2d\": [...], ... }\n  const reportersData = (data.default || data) as Record<\n    string,\n    ReporterEntry[]\n  >\n\n  // Build fast lookup index with lowercase normalization\n  for (const [canonicalAbbr, reporters] of Object.entries(reportersData)) {\n    for (const reporter of reporters) {\n      all.push(reporter)\n\n      // Index by all edition abbreviations\n      for (const editionAbbr of Object.keys(reporter.editions)) {\n        const key = editionAbbr.toLowerCase()\n        if (!byAbbreviation.has(key)) {\n          byAbbreviation.set(key, [])\n        }\n        byAbbreviation.get(key)!.push(reporter)\n      }\n\n      // Index all variations for fuzzy matching\n      for (const [variant, canonical] of Object.entries(\n        reporter.variations || {},\n      )) {\n        const variantKey = variant.toLowerCase()\n        if (!byAbbreviation.has(variantKey)) {\n          byAbbreviation.set(variantKey, [])\n        }\n        byAbbreviation.get(variantKey)!.push(reporter)\n      }\n    }\n  }\n\n  cached = {\n    byAbbreviation,\n    all,\n  }\n  return cached\n}\n\n/**\n * Get cached reporter database synchronously (degraded mode support)\n *\n * Returns null if reporters not loaded yet. This enables the library to\n * work in degraded mode without reporter validation.\n *\n * @returns Cached database or null if not loaded\n *\n * @example\n * const db = getReportersSync()\n * if (db) {\n *   // Full mode: validate citations\n * } else {\n *   // Degraded mode: extract without validation\n * }\n */\nexport function getReportersSync(): ReportersDatabase | null {\n  return cached\n}\n\n/**\n * Find reporters by abbreviation (case-insensitive)\n *\n * Loads reporter database if not already loaded. Returns all reporters\n * matching the abbreviation (including variant forms).\n *\n * @param abbr - Reporter abbreviation to look up\n * @returns Promise resolving to matching reporters (empty array if none)\n *\n * @example\n * const reporters = await findReportersByAbbreviation('F.2d')\n * // [{ abbreviation: 'F.2d', name: 'Federal Reporter, Second Series', ... }]\n *\n * @example\n * const unknown = await findReportersByAbbreviation('NONEXISTENT')\n * // [] (empty array, not error)\n */\nexport async function findReportersByAbbreviation(\n  abbr: string,\n): Promise<ReporterEntry[]> {\n  const db = await loadReporters()\n  return db.byAbbreviation.get(abbr.toLowerCase()) ?? []\n}\n"],"mappings":"mEAuEA,IAAI,EAAmC,KAcvC,eAAsB,GAA4C,CAChE,GAAI,EAAQ,OAAO,EAGnB,IAAM,EAAO,MAAM,OAAO,4BAA6B,CACrD,OAAQ,CAAE,KAAM,OAAQ,CACzB,EAEK,EAAiB,IAAI,IACrB,EAAuB,EAAE,CAGzB,EAAiB,EAAK,SAAW,EAMvC,IAAK,GAAM,CAAC,EAAe,KAAc,OAAO,QAAQ,EAAc,CACpE,IAAK,IAAM,KAAY,EAAW,CAChC,EAAI,KAAK,EAAS,CAGlB,IAAK,IAAM,KAAe,OAAO,KAAK,EAAS,SAAS,CAAE,CACxD,IAAM,EAAM,EAAY,aAAa,CAChC,EAAe,IAAI,EAAI,EAC1B,EAAe,IAAI,EAAK,EAAE,CAAC,CAE7B,EAAe,IAAI,EAAI,CAAE,KAAK,EAAS,CAIzC,IAAK,GAAM,CAAC,EAAS,KAAc,OAAO,QACxC,EAAS,YAAc,EAAE,CAC1B,CAAE,CACD,IAAM,EAAa,EAAQ,aAAa,CACnC,EAAe,IAAI,EAAW,EACjC,EAAe,IAAI,EAAY,EAAE,CAAC,CAEpC,EAAe,IAAI,EAAW,CAAE,KAAK,EAAS,EASpD,MAJA,GAAS,CACP,iBACA,MACD,CACM,EAmBT,SAAgB,GAA6C,CAC3D,OAAO,EAoBT,eAAsB,EACpB,EAC0B,CAE1B,OADW,MAAM,GAAe,EACtB,eAAe,IAAI,EAAK,aAAa,CAAC,EAAI,EAAE"}