eyecite-ts 0.5.0 → 0.6.0

package/dist/{citation-Cymq3pJ-.d.cts → citation-By8QXtGC.d.cts}

@@ -1,3 +1,34 @@
+//#region src/extract/pincite.d.ts
+/**
+* Structured pincite information parsed from citation text.
+*/
+interface PinciteInfo {
+  /** Primary page number */
+  page: number;
+  /** End page for ranges: "570-75" → 575 */
+  endPage?: number;
+  /** Footnote number: "570 n.3" → 3 */
+  footnote?: number;
+  /** True if this is a page range */
+  isRange: boolean;
+  /** Original text before parsing */
+  raw: string;
+}
+/**
+* Parse a pincite string into structured components.
+*
+* Handles simple pages, ranges (with abbreviated end pages),
+* footnote references, and "at" prefixes.
+*
+* @example
+* parsePincite("570")       // { page: 570, isRange: false, raw: "570" }
+* parsePincite("570-75")    // { page: 570, endPage: 575, isRange: true, raw: "570-75" }
+* parsePincite("570 n.3")   // { page: 570, footnote: 3, isRange: false, raw: "570 n.3" }
+*
+* @returns Parsed pincite info, or null if unparseable
+*/
+declare function parsePincite(raw: string): PinciteInfo | null;
+//#endregion
 //#region src/types/span.d.ts
 /**
 * Represents a text span with positions tracked through transformations.
@@ -43,7 +74,7 @@ interface TransformationMap {
 /**
 * Citation type discriminator for type-safe pattern matching.
 */
-type CitationType = "case" | "statute" | "journal" | "neutral" | "publicLaw" | "federalRegister" | "statutesAtLarge" | "id" | "supra" | "shortFormCase";
+type CitationType = "case" | "statute" | "journal" | "neutral" | "publicLaw" | "federalRegister" | "statutesAtLarge" | "constitutional" | "id" | "supra" | "shortFormCase";
 /**
 * Warning generated during citation parsing.
 */
@@ -61,6 +92,11 @@ interface Warning {
   context?: string;
 }
 /**
+* Introductory signal word classification for citation support level.
+* Based on Bluebook signal categories (Rule 1.2).
+*/
+type CitationSignal = "see" | "see also" | "see generally" | "cf" | "but see" | "but cf" | "compare" | "accord" | "contra";
+/**
 * Base fields shared by all citation types.
 */
 interface CitationBase {
@@ -84,6 +120,75 @@ interface CitationBase {
   patternsChecked: number;
   /** Warnings for malformed or ambiguous regions */
   warnings?: Warning[];
+  /** Introductory signal word (e.g., "see", "see also", "but see") */
+  signal?: CitationSignal;
+  /** Group ID for string citations sharing the same proposition */
+  stringCitationGroupId?: string;
+  /** Position within the string citation group (0-indexed) */
+  stringCitationIndex?: number;
+  /** Total number of citations in this string citation group */
+  stringCitationGroupSize?: number;
+  /** Whether this citation appears in a footnote (only populated when detectFootnotes enabled) */
+  inFootnote?: boolean;
+  /** Footnote number, if applicable (only populated when detectFootnotes enabled) */
+  footnoteNumber?: number;
+}
+/**
+* Court level and jurisdiction inferred from reporter series.
+* Populated independently of the parenthetical-extracted `court` field.
+*/
+interface CourtInference {
+  /** Court level classification */
+  level: "supreme" | "appellate" | "trial" | "unknown";
+  /** Jurisdiction classification */
+  jurisdiction: "federal" | "state" | "unknown";
+  /** 2-letter state code, only for state-specific reporters */
+  state?: string;
+  /** Confidence score 0.0-1.0 (1.0 for unambiguous, 0.7 for regional multi-state) */
+  confidence: number;
+}
+/**
+* Signal-word classification for explanatory parentheticals.
+* Based on the leading gerund/verb form in the parenthetical text.
+*/
+type ParentheticalType = "holding" | "finding" | "stating" | "noting" | "explaining" | "quoting" | "citing" | "discussing" | "describing" | "recognizing" | "applying" | "rejecting" | "adopting" | "requiring" | "other";
+/**
+* An extracted explanatory parenthetical from a case citation.
+*
+* @example
+* ```typescript
+* { text: "holding that X requires Y", type: "holding" }
+* { text: "citing Doe v. City for the same proposition", type: "citing" }
+* ```
+*/
+interface Parenthetical {
+  /** Full text content between the parentheses (excluding parens themselves) */
+  text: string;
+  /** Signal-word classification based on leading gerund */
+  type: ParentheticalType;
+}
+/**
+* Normalized subsequent history signal classification.
+* Maps variant spellings (aff'd, affirmed) to canonical forms.
+*/
+type HistorySignal = "affirmed" | "reversed" | "cert_denied" | "cert_granted" | "overruled" | "vacated" | "remanded" | "modified" | "abrogated" | "superseded" | "disapproved" | "questioned" | "distinguished" | "withdrawn" | "reinstated";
+/**
+* A single subsequent history entry from a case citation.
+*
+* @example
+* ```typescript
+* { signal: "affirmed", rawSignal: "aff'd", signalSpan: { ... }, order: 0 }
+* ```
+*/
+interface SubsequentHistoryEntry {
+  /** Normalized signal classification */
+  signal: HistorySignal;
+  /** Raw signal text as it appeared in the document */
+  rawSignal: string;
+  /** Position of the signal text in the document */
+  signalSpan: Span;
+  /** Order in the history chain (0-based) */
+  order: number;
 }
 /**
 * Full case citation (volume-reporter-page format).
@@ -98,7 +203,11 @@ interface FullCaseCitation extends CitationBase {
   /** Page number — optional for blank page placeholder citations (e.g., "___" or "---") */
   page?: number;
   pincite?: number;
+  /** Structured pincite information (page, range, footnote) */
+  pinciteInfo?: PinciteInfo;
   court?: string;
+  /** Normalized court string: spaces collapsed, trailing period ensured */
+  normalizedCourt?: string;
   year?: number;
   /** Normalized reporter abbreviation from reporters-db (e.g., "F.2d" vs "F. 2d") */
   normalizedReporter?: string;
@@ -116,12 +225,29 @@ interface FullCaseCitation extends CitationBase {
     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;
+  /**
+  * Explanatory parentheticals following the citation.
+  * Only populated when explanatory content is found (not court/year/disposition).
+  * @example [{ text: "holding that X requires Y", type: "holding" }]
+  */
+  parentheticals?: Parenthetical[];
+  /**
+  * Subsequent history entries for this citation.
+  * Each entry describes a procedural event (affirmed, reversed, etc.).
+  * Only populated on the parent (original) citation.
+  * @example [{ signal: "affirmed", rawSignal: "aff'd", signalSpan: {...}, order: 0 }]
+  */
+  subsequentHistoryEntries?: SubsequentHistoryEntry[];
+  /**
+  * Back-pointer indicating this citation is a subsequent history citation.
+  * `index` is the parent's position in the results array returned by
+  * `extractCitations()` — it becomes invalid if the array is filtered or reordered.
+  * @example { index: 0, signal: "affirmed" }
+  */
+  subsequentHistoryOf?: {
+    index: number;
+    signal: HistorySignal;
+  };
   /**
   * Date information in multiple formats.
   * - iso: ISO 8601 format (YYYY-MM-DD or YYYY-MM-DDTHH:mm:ssZ)
@@ -189,6 +315,18 @@ interface FullCaseCitation extends CitationBase {
   */
   proceduralPrefix?: string;
   /**
+  * Nominative (historical) reporter volume for early SCOTUS citations.
+  * Present only when citation includes a nominative parenthetical, e.g.,
+  * `67 U.S. (2 Black) 635` → nominativeVolume: 2
+  */
+  nominativeVolume?: number;
+  /**
+  * Nominative (historical) reporter abbreviation for early SCOTUS citations.
+  * Present only when citation includes a nominative parenthetical, e.g.,
+  * `67 U.S. (2 Black) 635` → nominativeReporter: "Black"
+  */
+  nominativeReporter?: string;
+  /**
   * True when page position contains a blank placeholder ("___" or "---").
   * Populated by Phase 5 (Blank Page support).
   * When true, page field will be undefined and confidence reduced to 0.8.
@@ -200,6 +338,13 @@ interface FullCaseCitation extends CitationBase {
   * @example "en banc", "per curiam"
   */
   disposition?: string;
+  /**
+  * Court level/jurisdiction inferred from reporter series.
+  * Always populated independently of the parenthetical `court` field.
+  * Uses a curated static lookup table — does not depend on the reporter DB
+  * to preserve tree-shaking of the `eyecite-ts/data` entry point.
+  */
+  inferredCourt?: CourtInference;
 }
 /**
 * Statute citation (U.S. Code, state codes, etc.).
@@ -314,6 +459,26 @@ interface StatutesAtLargeCitation extends CitationBase {
   year?: number;
 }
 /**
+* Constitutional citation (U.S. or state constitution).
+*
+* @example "U.S. Const. art. III, § 2"
+* @example "U.S. Const. amend. XIV, § 1"
+* @example "Cal. Const. art. I, § 7"
+*/
+interface ConstitutionalCitation extends CitationBase {
+  type: "constitutional";
+  /** Jurisdiction code: "US", 2-letter state code, or undefined for bare "Const." */
+  jurisdiction?: string;
+  /** Article number (parsed from Roman numerals) — mutually exclusive with amendment */
+  article?: number;
+  /** Amendment number (parsed from Roman numerals) — mutually exclusive with article */
+  amendment?: number;
+  /** Section identifier (string to handle non-numeric like "3-a") */
+  section?: string;
+  /** Clause number (always numeric) */
+  clause?: number;
+}
+/**
 * Id. citation (refers to immediately preceding citation).
 *
 * @example "Id."
@@ -366,16 +531,16 @@ interface ShortFormCaseCitation extends CitationBase {
 *   // ...
 * }
 */
-type Citation = FullCaseCitation | StatuteCitation | JournalCitation | NeutralCitation | PublicLawCitation | FederalRegisterCitation | StatutesAtLargeCitation | IdCitation | SupraCitation | ShortFormCaseCitation;
+type Citation = FullCaseCitation | StatuteCitation | JournalCitation | NeutralCitation | PublicLawCitation | FederalRegisterCitation | StatutesAtLargeCitation | ConstitutionalCitation | IdCitation | SupraCitation | ShortFormCaseCitation;
 /**
 * Citation type discriminators grouped by category.
 */
-type FullCitationType = "case" | "statute" | "journal" | "neutral" | "publicLaw" | "federalRegister" | "statutesAtLarge";
+type FullCitationType = "case" | "statute" | "journal" | "neutral" | "publicLaw" | "federalRegister" | "statutesAtLarge" | "constitutional";
 type ShortFormCitationType = "id" | "supra" | "shortFormCase";
 /**
 * Union of all full citation types (not short-form references).
 */
-type FullCitation = FullCaseCitation | StatuteCitation | JournalCitation | NeutralCitation | PublicLawCitation | FederalRegisterCitation | StatutesAtLargeCitation;
+type FullCitation = FullCaseCitation | StatuteCitation | JournalCitation | NeutralCitation | PublicLawCitation | FederalRegisterCitation | StatutesAtLargeCitation | ConstitutionalCitation;
 /**
 * Union of all short-form citation types (Id., supra, short-form case).
 */
@@ -398,5 +563,5 @@ type CitationOfType<T extends CitationType> = Extract<Citation, {
 */
 type ExtractorMap = { [K in FullCitationType]: CitationOfType<K> };
 //#endregion
-export { TransformationMap as S, StatuteCitation as _, ExtractorMap as a, Warning 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, StatutesAtLargeCitation as v, Span as x, SupraCitation as y };
-//# sourceMappingURL=citation-Cymq3pJ-.d.cts.map
+export { PinciteInfo as A, StatuteCitation as C, Warning as D, SupraCitation as E, Span as O, ShortFormCitationType as S, SubsequentHistoryEntry as T, Parenthetical as _, CitationType as a, ShortFormCaseCitation as b, ExtractorMap as c, FullCitation as d, FullCitationType as f, NeutralCitation as g, JournalCitation as h, CitationSignal as i, parsePincite as j, TransformationMap as k, FederalRegisterCitation as l, IdCitation as m, CitationBase as n, ConstitutionalCitation as o, HistorySignal as p, CitationOfType as r, CourtInference as s, Citation as t, FullCaseCitation as u, ParentheticalType as v, StatutesAtLargeCitation as w, ShortFormCitation as x, PublicLawCitation as y };
+//# sourceMappingURL=citation-By8QXtGC.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"citation-By8QXtGC.d.cts","names":[],"sources":["../src/extract/pincite.ts","../src/types/span.ts","../src/types/citation.ts"],"mappings":";;AAGA;;UAAiB,WAAA;EAAA;EAEf,IAAA;;EAEA,OAAA;;EAEA,QAAA;;EAEA,OAAA;EAsBF;EApBE,GAAA;AAAA;;;;;;ACIF;;;;;;;;iBDgBgB,YAAA,CAAa,GAAA,WAAc,WAAA;;;;AA9B3C;;;;;;;;;;;AA8BA;;;;;UChBiB,IAAA;;EAEf,UAAA;EAFF;EAKE,QAAA;;EAGA,aAAA;;EAGA,WAAA;AAAA;;;;AASF;;;UAAiB,iBAAA;;EAEf,eAAA,EAAiB,GAAA;;EAGjB,eAAA,EAAiB,GAAA;AAAA;;;ADvCnB;;;AAAA,KEEY,YAAA;;;;UAgBK,OAAA;;EAEf,KAAA;EFVA;EEYA,OAAA;EFQc;EENd,QAAA;IAAY,KAAA;IAAe,GAAA;EAAA;;EAE3B,OAAA;AAAA;;;;;KAOU,cAAA;;;;UAcK,YAAA;EDbjB;ECeE,IAAA;;EAGA,IAAA,EAAM,IAAA;;;;;;;;EASN,UAAA;;EAGA,WAAA;EA9DU;EAiEV,aAAA;EAjEU;EAoEV,eAAA;EApDF;EAuDE,QAAA,GAAW,OAAA;;EAGX,MAAA,GAAS,cAAA;;EAGT,qBAAA;;EAGA,mBAAA;;EAGA,uBAAA;;EAGA,UAAA;EAvDF;EA0DE,cAAA;AAAA;;;AA5CF;;UAmDiB,cAAA;;EAEf,KAAA;;EAEA,YAAA;EA1BS;EA4BT,KAAA;;EAEA,UAAA;AAAA;;;;;KAOU,iBAAA;;;;;;;;;;UA0BK,aAAA;EAzCA;EA2Cf,IAAA;EA3Ce;EA6Cf,IAAA,EAAM,iBAAA;AAAA;;;;;KAOI,aAAA;;;;;AAXZ;;;;UAoCiB,sBAAA;;EAEf,MAAA,EAAQ,aAAA;;EAER,SAAA;EA7BF;EA+BE,UAAA,EAAY,IAAA;;EAEZ,KAAA;AAAA;AARF;;;;;;AAAA,UAiBiB,gBAAA,SAAyB,YAAA;EACxC,IAAA;EACA,MAAA;EACA,QAAA;;EAEA,IAAA;EACA,OAAA;EANe;EAQf,WAAA,GARe,WAAA;EASf,KAAA;;EAEA,eAAA;EACA,IAAA;;EAGA,kBAAA;;;;;;;;EASA,OAAA;;EAGA,iBAAA,GAAoB,KAAA;IAClB,MAAA;IACA,QAAA;IACA,IAAA;EAAA;;;;;;EAQF,cAAA,GAAiB,aAAA;;;;;;;EAQjB,wBAAA,GAA2B,sBAAA;;;;;;;EAQ3B,mBAAA;IAAwB,KAAA;IAAe,MAAA,EAAQ,aAAA;EAAA;;;;;;EAO/C,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;EA+Fa;;;;;EAvFf,QAAA,GAAW,IAAA;;;;;;EAOX,QAAA;;;AA2GF;;;EApGE,SAAA;;;;;;EAOA,SAAA;;;;;;EAOA,mBAAA;EAkHF;;;;;EA3GE,mBAAA;;;;;;EAOA,gBAAA;EAsHe;;;;;EA/Gf,gBAAA;;;;;AAiIF;EA1HE,kBAAA;;;;;;EAOA,YAAA;;;;AA8HF;;EAvHE,WAAA;EAuH+C;;;;;;EA/G/C,aAAA,GAAgB,cAAA;AAAA;AAgIlB;;;;;;AAAA,UAvHiB,eAAA,SAAwB,YAAA;EACvC,IAAA;EACA,KAAA;EACA,IAAA;EACA,OAAA;;EAEA,UAAA;EAqIF;EAnIE,YAAA;;;;;;EAMA,OAAA;EA+HA;EA7HA,QAAA;AAAA;;;;;;;;;UAWe,eAAA,SAAwB,YAAA;EACvC,IAAA;;EAEA,MAAA;;EAEA,KAAA;;EAEA,MAAA;;EAEA,OAAA;;EAEA,YAAA;EAuJF;EArJE,IAAA;;EAEA,OAAA;;EAEA,IAAA;AAAA;;;;;;;;;UAWe,eAAA,SAAwB,YAAA;EACvC,IAAA;;EAEA,IAAA;;EAEA,KAAA;;EAEA,cAAA;AAAA;;;;;;AA+IF;;;UApIiB,iBAAA,SAA0B,YAAA;EACzC,IAAA;EA4IF;EA1IE,QAAA;;EAEA,SAAA;EAwIU;EAtIV,KAAA;AAAA;;;;;;;;;UAWe,uBAAA,SAAgC,YAAA;EAC/C,IAAA;EAuIE;EArIF,MAAA;;EAEA,IAAA;;EAEA,IAAA;AAAA;;UAIe,uBAAA,SAAgC,YAAA;EAC/C,IAAA;EA4HE;EA1HF,MAAA;EA+HU;EA7HV,IAAA;;EAEA,IAAA;AAAA;;;;;;;;UAUe,sBAAA,SAA+B,YAAA;EAC9C,IAAA;;EAEA,YAAA;;EAEA,OAAA;;EAEA,SAAA;EAqHmD;EAnHnD,OAAA;;EAEA,MAAA;AAAA;;;;;AAuHF;;UA9GiB,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,uBAAA,GACA,sBAAA,GACA,UAAA,GACA,aAAA,GACA,qBAAA;;;;KAKQ,gBAAA;AAAA,KASA,qBAAA;;;;KAKA,YAAA,GACR,gBAAA,GACA,eAAA,GACA,eAAA,GACA,eAAA,GACA,iBAAA,GACA,uBAAA,GACA,uBAAA,GACA,sBAAA;;;;KAKQ,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/data/index.cjs.map

@@ -1 +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":"iHAuEA,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,EAAgB,KAAc,OAAO,QAAQ,EAAc,CACrE,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,EAAE,KAAK,EAAS,CAIzC,IAAK,GAAM,CAAC,EAAS,KAAe,OAAO,QACzC,EAAS,YAAc,EAAE,CAC1B,CAAE,CACD,IAAM,EAAa,EAAQ,aAAa,CACnC,EAAe,IAAI,EAAW,EACjC,EAAe,IAAI,EAAY,EAAE,CAAC,CAEpC,EAAe,IAAI,EAAW,EAAE,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"}
+{"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<string, ReporterEntry[]>\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(reporter.variations || {})) {\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(abbr: string): Promise<ReporterEntry[]> {\n  const db = await loadReporters()\n  return db.byAbbreviation.get(abbr.toLowerCase()) ?? []\n}\n"],"mappings":"iHAuEA,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,EAGvC,IAAK,GAAM,CAAC,EAAgB,KAAc,OAAO,QAAQ,EAAc,CACrE,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,EAAE,KAAK,EAAS,CAIzC,IAAK,GAAM,CAAC,EAAS,KAAe,OAAO,QAAQ,EAAS,YAAc,EAAE,CAAC,CAAE,CAC7E,IAAM,EAAa,EAAQ,aAAa,CACnC,EAAe,IAAI,EAAW,EACjC,EAAe,IAAI,EAAY,EAAE,CAAC,CAEpC,EAAe,IAAI,EAAW,EAAE,KAAK,EAAS,EASpD,MAJA,GAAS,CACP,iBACA,MACD,CACM,EAmBT,SAAgB,GAA6C,CAC3D,OAAO,EAoBT,eAAsB,EAA4B,EAAwC,CAExF,OADW,MAAM,GAAe,EACtB,eAAe,IAAI,EAAK,aAAa,CAAC,EAAI,EAAE"}

package/dist/data/index.d.cts

@@ -1,3 +1,93 @@
+//#region src/data/knownCodes.d.ts
+/**
+* Known statutory code registry for abbreviated-code jurisdictions
+*
+* Provides a registry of state statutory codes that use abbreviated
+* citation forms (e.g., "R.C. § 1.01", "MCL 750.83"). Used by the
+* citation extractor to identify and normalize state statute citations.
+*/
+/**
+* A single entry in the known codes registry.
+*
+* PA has two entries (Pa.C.S. and P.S.) because it has two distinct
+* code families with separate abbreviation sets.
+*/
+interface CodeEntry {
+  /** Two-letter state abbreviation (e.g., "OH", "MI") */
+  jurisdiction: string;
+  /** Short canonical abbreviation used internally (e.g., "RC", "MCL") */
+  abbreviation: string;
+  /** All recognized text patterns that identify this code */
+  patterns: string[];
+  /** Citation family — determines which citation pattern family this belongs to */
+  family: "federal" | "named" | "abbreviated" | "chapterAct" | "prose";
+}
+/**
+* Registry of state statutory codes that use abbreviated citation forms.
+*
+* Covers 12 jurisdictions. Pennsylvania has two entries because it
+* maintains two distinct code families (Pa.C.S. and P.S.).
+*
+* Note: Short 2-letter patterns (GS, IC, PS, RC, FS) may produce false positives
+* in non-legal text (e.g., "GS 5" for government service grade). The extraction
+* layer mitigates this via confidence scoring — citations without a § symbol receive
+* lower confidence (0.85 vs 0.95). Consumers should filter by confidence threshold.
+*/
+declare const abbreviatedCodes: CodeEntry[];
+/**
+* Registry of state statutory codes that use named-code citation forms.
+*
+* Named-code jurisdictions identify their code by name in citations (e.g.,
+* "N.Y. Penal Law § 120.05", "Cal. Civ. Proc. Code § 437c"), rather than by
+* a standalone abbreviation. The jurisdiction prefix is handled by the
+* extraction layer; these patterns cover only the code name portion.
+*
+* Ordering note: within each jurisdiction, more specific patterns must come
+* before more general ones (e.g., "Civ. Proc." before "Civ.") so that
+* findNamedCode's longest-match wins correctly.
+*
+* Covers 7 jurisdictions: NY (21 entries), CA (29 entries), TX (29 entries),
+* MD (36 entries), VA (1 entry), AL (1 entry), MA (1 entry).
+*/
+declare const namedCodes: CodeEntry[];
+/**
+* Find a CodeEntry by jurisdiction and code name token.
+*
+* Lookup strategy: for each candidate entry in the given jurisdiction,
+* check whether the normalized codeName matches or starts with any of the
+* entry's patterns (case-insensitive). Returns the entry with the longest
+* matching pattern to prefer more specific codes over general ones
+* (e.g., "Civ. Proc." over "Civ.").
+*
+* @param jurisdiction - Two-letter state abbreviation (e.g., "CA", "NY")
+* @param codeName - The code name token to look up (e.g., "Penal", "Civ. Proc.")
+* @returns Matching CodeEntry, or undefined if not found
+*
+* @example
+* findNamedCode('NY', 'Penal')       // → NY PEN entry
+* findNamedCode('CA', 'Civ. Proc.')  // → CA CCP entry (not CA CIV)
+* findNamedCode('MD', 'Crim. Law')   // → MD gcr entry
+* findNamedCode('NY', 'Unknown')     // → undefined
+*/
+declare function findNamedCode(jurisdiction: string, codeName: string): CodeEntry | undefined;
+/**
+* Find a CodeEntry by an abbreviated text token.
+*
+* Lookup order:
+* 1. Exact case-insensitive match against all patterns
+* 2. Prefix match — returns the entry whose pattern is the longest
+*    prefix of `abbrevText` (handles tokens like "RCW" inside longer text)
+*
+* @param abbrevText - The abbreviation token to look up
+* @returns Matching CodeEntry, or undefined if not found
+*
+* @example
+* findAbbreviatedCode('R.C.')   // → OH entry
+* findAbbreviatedCode('MCL')    // → MI entry
+* findAbbreviatedCode('UNKNOWN') // → undefined
+*/
+declare function findAbbreviatedCode(abbrevText: string): CodeEntry | undefined;
+//#endregion
 //#region src/data/reporters.d.ts
 /**
 * Reporter database integration for citation validation
@@ -112,95 +202,5 @@ declare function getReportersSync(): ReportersDatabase | null;
 */
 declare function findReportersByAbbreviation(abbr: string): Promise<ReporterEntry[]>;
 //#endregion
-//#region src/data/knownCodes.d.ts
-/**
-* Known statutory code registry for abbreviated-code jurisdictions
-*
-* Provides a registry of state statutory codes that use abbreviated
-* citation forms (e.g., "R.C. § 1.01", "MCL 750.83"). Used by the
-* citation extractor to identify and normalize state statute citations.
-*/
-/**
-* A single entry in the known codes registry.
-*
-* PA has two entries (Pa.C.S. and P.S.) because it has two distinct
-* code families with separate abbreviation sets.
-*/
-interface CodeEntry {
-  /** Two-letter state abbreviation (e.g., "OH", "MI") */
-  jurisdiction: string;
-  /** Short canonical abbreviation used internally (e.g., "RC", "MCL") */
-  abbreviation: string;
-  /** All recognized text patterns that identify this code */
-  patterns: string[];
-  /** Citation family — determines which citation pattern family this belongs to */
-  family: "federal" | "named" | "abbreviated" | "chapterAct" | "prose";
-}
-/**
-* Registry of state statutory codes that use abbreviated citation forms.
-*
-* Covers 12 jurisdictions. Pennsylvania has two entries because it
-* maintains two distinct code families (Pa.C.S. and P.S.).
-*
-* Note: Short 2-letter patterns (GS, IC, PS, RC, FS) may produce false positives
-* in non-legal text (e.g., "GS 5" for government service grade). The extraction
-* layer mitigates this via confidence scoring — citations without a § symbol receive
-* lower confidence (0.85 vs 0.95). Consumers should filter by confidence threshold.
-*/
-declare const abbreviatedCodes: CodeEntry[];
-/**
-* Registry of state statutory codes that use named-code citation forms.
-*
-* Named-code jurisdictions identify their code by name in citations (e.g.,
-* "N.Y. Penal Law § 120.05", "Cal. Civ. Proc. Code § 437c"), rather than by
-* a standalone abbreviation. The jurisdiction prefix is handled by the
-* extraction layer; these patterns cover only the code name portion.
-*
-* Ordering note: within each jurisdiction, more specific patterns must come
-* before more general ones (e.g., "Civ. Proc." before "Civ.") so that
-* findNamedCode's longest-match wins correctly.
-*
-* Covers 7 jurisdictions: NY (21 entries), CA (29 entries), TX (29 entries),
-* MD (36 entries), VA (1 entry), AL (1 entry), MA (1 entry).
-*/
-declare const namedCodes: CodeEntry[];
-/**
-* Find a CodeEntry by jurisdiction and code name token.
-*
-* Lookup strategy: for each candidate entry in the given jurisdiction,
-* check whether the normalized codeName matches or starts with any of the
-* entry's patterns (case-insensitive). Returns the entry with the longest
-* matching pattern to prefer more specific codes over general ones
-* (e.g., "Civ. Proc." over "Civ.").
-*
-* @param jurisdiction - Two-letter state abbreviation (e.g., "CA", "NY")
-* @param codeName - The code name token to look up (e.g., "Penal", "Civ. Proc.")
-* @returns Matching CodeEntry, or undefined if not found
-*
-* @example
-* findNamedCode('NY', 'Penal')       // → NY PEN entry
-* findNamedCode('CA', 'Civ. Proc.')  // → CA CCP entry (not CA CIV)
-* findNamedCode('MD', 'Crim. Law')   // → MD gcr entry
-* findNamedCode('NY', 'Unknown')     // → undefined
-*/
-declare function findNamedCode(jurisdiction: string, codeName: string): CodeEntry | undefined;
-/**
-* Find a CodeEntry by an abbreviated text token.
-*
-* Lookup order:
-* 1. Exact case-insensitive match against all patterns
-* 2. Prefix match — returns the entry whose pattern is the longest
-*    prefix of `abbrevText` (handles tokens like "RCW" inside longer text)
-*
-* @param abbrevText - The abbreviation token to look up
-* @returns Matching CodeEntry, or undefined if not found
-*
-* @example
-* findAbbreviatedCode('R.C.')   // → OH entry
-* findAbbreviatedCode('MCL')    // → MI entry
-* findAbbreviatedCode('UNKNOWN') // → undefined
-*/
-declare function findAbbreviatedCode(abbrevText: string): CodeEntry | undefined;
-//#endregion
 export { CodeEntry, ReporterEdition, ReporterEntry, ReportersDatabase, abbreviatedCodes, findAbbreviatedCode, findNamedCode, findReportersByAbbreviation, getReportersSync, loadReporters, namedCodes };
 //# sourceMappingURL=index.d.cts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/data/reporters.ts","../../src/data/knownCodes.ts"],"mappings":";;AAsBA;;;;;AAgBA;;;;;;;;;;;;;;;UAhBiB,eAAA;;EAEf,KAAA;;EAEA,GAAA;AAAA;;;;;;;;;;UAYe,aAAA;;EAEf,IAAA;;EAEA,SAAA;EA2CF;EAzCE,QAAA,EAAU,MAAA,SAAe,eAAA;;EAEzB,UAAA,GAAa,MAAA;EAuCgC;EArC7C,gBAAA;EAwGc;EAtGd,SAAA;EAsGkC;EApGlC,KAAA;AAAA;;;;;;;UASe,iBAAA;EAkHN;EAhHT,cAAA,EAAgB,GAAA,SAAY,aAAA;;EAE5B,GAAA,EAAK,aAAA;AAAA;;;;;;;;;;AC7BP;;;iBDiDsB,aAAA,CAAA,GAAiB,OAAA,CAAQ,iBAAA;;ACyE/C;;;;;AAyuBA;;;;;;;;;AA8DA;iBD7yBgB,gBAAA,CAAA,GAAoB,iBAAA;;;;;;;;;;;;;;;;;;iBAqBd,2BAAA,CACpB,IAAA,WACC,OAAA,CAAQ,aAAA;;;;AAzJX;;;;;AAgBA;;;;;;;UCxBiB,SAAA;;EAEf,YAAA;;EAEA,YAAA;;EAEA,QAAA;;EAEA,MAAA;AAAA;;;;ADuCF;;;;;;;;cCzBa,gBAAA,EAAkB,SAAA;;;;;;;ADiD/B;;;;;AAmEA;;;;cCMa,UAAA,EAAY,SAAA;ADezB;;;;;;;;;;;;AC/JA;;;;;;;AD+JA,iBC0tBgB,aAAA,CAAc,YAAA,UAAsB,QAAA,WAAmB,SAAA;;;AAn2BvE;;;;;AA0HA;;;;;AAyuBA;;;;iBA8DgB,mBAAA,CAAoB,UAAA,WAAqB,SAAA"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/data/knownCodes.ts","../../src/data/reporters.ts"],"mappings":";;AAcA;;;;;;;;;;AAsBA;;UAtBiB,SAAA;EAsBc;EApB7B,YAAA;EAqIF;EAnIE,YAAA;;EAEA,QAAA;EAiIuB;EA/HvB,MAAA;AAAA;;;;;;;;AAs6BF;;;;cAx5Ba,gBAAA,EAAkB,SAAA;;;;ACd/B;;;;;AAgBA;;;;;;;cD+Ga,UAAA,EAAY,SAAA;;;;;;;;;;;;;ACxFzB;;;;;;;iBDi0BgB,aAAA,CAAc,YAAA,UAAsB,QAAA,WAAmB,SAAA;;;;;;;;ACzyBvE;;;;;AA8DA;;;;iBDyyBgB,mBAAA,CAAoB,UAAA,WAAqB,SAAA;;;;AA96BzD;;;;;;;;;;AAsBA;;;;;AAiHA;;;;;AAAA,UC/HiB,eAAA;EDw2BD;ECt2Bd,KAAA;EDs2BqE;ECp2BrE,GAAA;AAAA;;;;ADk6BF;;;;;;UCt5BiB,aAAA;;EAEf,IAAA;EAlBe;EAoBf,SAAA;EApBe;EAsBf,QAAA,EAAU,MAAA,SAAe,eAAA;EAN3B;EAQE,UAAA,GAAa,MAAA;;EAEb,gBAAA;;EAEA,SAAA;;EAEA,KAAA;AAAA;;;;;;;UASe,iBAAA;;EAEf,cAAA,EAAgB,GAAA,SAAY,aAAA;;EAE5B,GAAA,EAAK,aAAA;AAAA;;;;;;;;;;;;;iBAoBe,aAAA,CAAA,GAAiB,OAAA,CAAQ,iBAAA;;AAA/C;;;;;AA8DA;;;;;AAqBA;;;;;iBArBgB,gBAAA,CAAA,GAAoB,iBAAA;;;;;;;;;;;;;;;;;;iBAqBd,2BAAA,CAA4B,IAAA,WAAe,OAAA,CAAQ,aAAA"}