@cliwant/mcp-sam-gov 0.2.1 → 1.0.0

package/dist/far.d.ts

@@ -0,0 +1,170 @@
+/**
+ * FAR / DFARS clause lookup (keyless) — the authoritative clause text + its
+ * prescription, from the eCFR **versioner full** endpoint.
+ *
+ * Why this exists (and why NOT `ecfr_search`)
+ * -------------------------------------------
+ * The shipped full-text `ecfr_search` mis-ranks EXACT clause numbers: a bare
+ * `52.212-4` query returns GSAM **552**.212-4 above the real FAR 52.212-4
+ * (doc-09 §1.2). A proposal writer needs the AUTHORITATIVE clause text AND the
+ * rule that says WHEN it applies ("As prescribed in …") — the exact pair. The
+ * clean path is the versioner full endpoint, which `src/ecfr.ts` does not call:
+ *
+ *   GET /api/versioner/v1/full/{date}/title-48.xml?section={clause}
+ *
+ * keyless, HTTP 200 (~40 KB XML) for a real clause, clean HTTP 404
+ * `{"error":"No matching content found."}` for an absent one. Title 48 = FAR.
+ * `{date}` defaults to Title 48 `up_to_date_as_of` (from listTitles, cached).
+ *
+ * TRUTHFULNESS invariants (a reviewer WILL try to break these):
+ *   - A DOWN/failing eCFR service must NEVER read as "clause not found": only a
+ *     genuine HTTP 404 maps to `not_found`; any other fetch error propagates
+ *     with fetchWithRetry's classification (retryable 5xx/network/etc.).
+ *   - A genuinely-absent clause is `not_found` (retryable:false), NEVER a fake
+ *     empty clause. Clause text is never silently dropped or fabricated.
+ *   - A prescription-section fetch failure is NON-FATAL: `prescription:null` +
+ *     disclosed in `_meta.notes`; it never crashes the clause result.
+ *   - `farOverhaulRisk` carries NO fabricated FAR-case numbers/dates — only the
+ *     fixed structural caveat + the real authoritative-list / deviation URLs.
+ *
+ * Self-contained: imports `getText` from ./datasource.js (the shared XML/text
+ * fetch port, ADR-0013) + ToolErrorCarrier from ./errors.js, memoize from
+ * ./cache.js, listTitles from ./ecfr.js, and withMeta from ./meta.js — the
+ * versioner XML parse lives here (ecfr.ts's stripHtml is private and stays
+ * private).
+ */
+/** The regulation family a clause number belongs to (from its prefix). */
+type Regulation = "FAR" | "DFARS" | "GSAM" | "other";
+/**
+ * The RFO (Revolutionary FAR Overhaul) currency caveat — an ALWAYS-PRESENT
+ * structural flag, NOT a per-clause claim. eCFR reflects the CODIFIED FAR only;
+ * the RFO is replacing FAR parts via agency class deviations that may not appear
+ * in eCFR, so a clause can be current in the CFR yet operationally superseded.
+ *
+ * This is the HONEST design (doc-09 §3 baked unverified FAR-case numbers/dates
+ * as [가설] — those go stale/wrong). We ship the never-stale-wrong version: no
+ * fabricated specifics, only the fixed caveat + the real authoritative-list and
+ * deviation URLs (all VERIFIED HTTP 200, 2026-07-04). `appliesTo` scopes the
+ * caveat to the clause's own regulation family.
+ */
+declare function buildFarOverhaulRisk(regulation: Regulation): {
+    note: string;
+    authoritativeList: string;
+    deviationSources: string[];
+    appliesTo: Regulation;
+};
+export declare function farClauseLookup(args: {
+    clauseNumber: string;
+    includePrescription?: boolean;
+    asOfDate?: string;
+}): Promise<import("./meta.js").MetaBundle<{
+    clauseNumber: string;
+    kind: "clause" | "provision";
+    regulation: Regulation;
+    heading: string | null;
+    revision: string | null;
+    text: string;
+    prescribedIn: string | null;
+    prescription: {
+        section: string;
+        heading: string | null;
+        text: string;
+    } | null;
+    ecfrUrl: string;
+    asOfDate: string;
+    titleUpToDateAsOf: string | null;
+    titleLatestAmendedOn: string | null;
+    isCurrent: boolean;
+    farOverhaulRisk: {
+        note: string;
+        authoritativeList: string;
+        deviationSources: string[];
+        appliesTo: Regulation;
+    };
+}>>;
+/** One resolved matrix row: farClauseLookup's honest fields + a gate flag. */
+type MatrixRow = {
+    clauseNumber: string;
+    kind: "clause" | "provision";
+    regulation: Regulation;
+    heading: string | null;
+    revision: string | null;
+    prescribedIn: string | null;
+    prescription: {
+        section: string;
+        heading: string | null;
+        text: string;
+    } | null;
+    text: string;
+    ecfrUrl: string;
+    farOverhaulRisk: ReturnType<typeof buildFarOverhaulRisk>;
+    /** The eligibility-gate label (from GATE_MAP), or null when not a mapped gate. */
+    gate: string | null;
+};
+/** A clause that did not resolve, with a disclosed reason. */
+type UnresolvedClause = {
+    clauseNumber: string;
+    reason: string;
+};
+export declare function farComplianceMatrix(args: {
+    clauses: string[];
+    asOfDate?: string;
+    includePrescription?: boolean;
+    flagGates?: boolean;
+}): Promise<import("./meta.js").MetaBundle<{
+    asOfDate: string;
+    rows: MatrixRow[];
+    unresolved: UnresolvedClause[];
+    errored: UnresolvedClause[];
+    summary: {
+        total: number;
+        resolved: number;
+        unresolved: number;
+        errored: number;
+        far: number;
+        dfars: number;
+        gsam: number;
+        other: number;
+        gates: number;
+    };
+}>>;
+/** Which regulation family a far_search scope targets. */
+type FarSearchScope = "far" | "dfars" | "both";
+/** One far_search result row. */
+type FarSearchRow = {
+    regulation: Regulation;
+    type: string;
+    /** The FAR/DFARS part as a number (null if unparseable), for partsOnly. */
+    part: number | null;
+    section: string;
+    headingPath: string;
+    excerpt: string;
+    score: number;
+    ecfrUrl: string;
+    effectiveOn: string;
+    endsOn: string | null;
+    /** endsOn==null ⇒ the CURRENT (in-force) version; false ⇒ a kept historical. */
+    isCurrent: boolean;
+};
+export declare function farSearch(args: {
+    query: string;
+    scope?: FarSearchScope;
+    dedupeVersions?: boolean;
+    partsOnly?: number[];
+    perPage?: number;
+}): Promise<import("./meta.js").MetaBundle<{
+    query: string;
+    scope: FarSearchScope;
+    rows: FarSearchRow[];
+    returned: number;
+    distinctSections: number;
+    titleUpToDateAsOf: string | null;
+    farOverhaulRisk: {
+        note: string;
+        authoritativeList: string;
+        deviationSources: string[];
+        appliesTo: Regulation;
+    };
+}>>;
+export {};
+//# sourceMappingURL=far.d.ts.map

package/dist/far.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"far.d.ts","sourceRoot":"","sources":["../src/far.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAUH,0EAA0E;AAC1E,KAAK,UAAU,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAiFrD;;;;;;;;;;;GAWG;AACH,iBAAS,oBAAoB,CAAC,UAAU,EAAE,UAAU;;;;;EAYnD;AAkED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;;;;;;;;;iBAmIgB,MAAM;iBAAW,MAAM,GAAG,IAAI;cAAQ,MAAM;;;;;;;;;;;;;IAsF5D;AA8CD,8EAA8E;AAC9E,KAAK,SAAS,GAAG;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,QAAQ,GAAG,WAAW,CAAC;IAC7B,UAAU,EAAE,UAAU,CAAC;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EACR;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GACzD,IAAI,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC;IACzD,kFAAkF;IAClF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB,CAAC;AAEF,8DAA8D;AAC9D,KAAK,gBAAgB,GAAG;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AA6BjE,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;;;;;;;;;;;;;;;;IAmLA;AA4BD,0DAA0D;AAC1D,KAAK,cAAc,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,CAAC;AAQ/C,iCAAiC;AACjC,KAAK,YAAY,GAAG;IAClB,UAAU,EAAE,UAAU,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,gFAAgF;IAChF,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAmFF,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;;;;;;;;;;;;;IAsJA"}