building-standards-act-mcp 0.2.0 → 0.4.0

package/README.md

@@ -15,10 +15,12 @@ AI の建築法規回答に含まれるハルシネーションを、条文原
 - **法令検索** — キーワードで法令を横断検索
 - **法令全文取得** — 法令全体のテキストを取得
 - **告示取得** — 建築基準法が技術基準を委任している告示を国土交通省の告示データベース（PDF）から取得
-- **主要法令プリセット** — 建築基準法・消防法・都市計画法ほか 115 法令の law_id をプリセット（全 11 章カバー）
+- **主要法令プリセット** — 建築基準法・消防法・都市計画法ほか 115 法令の law_id をプリセット登録済み
 - **プリセット検証** — `validate_presets` ツールでプリセットの有効性をランタイム検証
 - **略称対応** — 「建基法」「都計法」「消防法」等の略称で指定可能
-- **キャッシュ** — 検索 30 分・法令データ 24 時間の TTL キャッシュ
+- **キャッシュ** — 検索 30 分・法令データ 24 時間の TTL キャッシュ（永続化オプションあり）
+- **API 耐障害性** — 自動リトライ（exponential backoff）+ サーキットブレーカー
+- **運用可視化** — 構造化 JSON ログ + 使用量メトリクス（`get_metrics` ツール）
 
 ## セットアップ
 
@@ -73,14 +75,19 @@ npm run build
 
 ## MCP ツール
 
-| ツール              | 説明                                                                            |
-| ------------------- | ------------------------------------------------------------------------------- |
-| `get_law`           | 条番号を指定して法令の条文を取得する。略称・正式名称のいずれでも指定可能        |
-| `get_full_law`      | 法令の全文を取得する。条番号を指定せず法令全体のテキストを返す                  |
-| `search_law`        | キーワードで建築関連法令を横断検索する。プリセット法令と e-Gov API の両方を検索 |
-| `get_kokuji`        | 建築基準法が技術基準を委任している告示の全文を取得する                          |
-| `validate_presets`  | プリセット法令の law_id が e-Gov API で有効かを一括検証する                     |
-| `check_law_updates` | 法令の改正状況を e-Gov API で確認する（単体/バッチ/改正履歴表示に対応）         |
+| ツール              | 説明                                                                                        |
+| ------------------- | ------------------------------------------------------------------------------------------- |
+| `get_law`           | 条番号を指定して法令の条文を取得する。略称・正式名称のいずれでも指定可能                    |
+| `get_full_law`      | 法令の全文を取得する。条番号を指定せず法令全体のテキストを返す                              |
+| `search_law`        | キーワードで建築関連法令を横断検索する。プリセット法令と e-Gov API の両方を検索             |
+| `get_kokuji`        | 建築基準法が技術基準を委任している告示の全文を取得する                                      |
+| `validate_presets`  | プリセット法令の law_id が e-Gov API で有効かを一括検証する                                 |
+| `check_law_updates` | 法令の改正状況を e-Gov API で確認する（単体/バッチ/改正履歴表示に対応）                     |
+| `get_laws_batch`    | 複数の法令・条文を一括取得する（最大20件、同一法令は1回のAPI呼び出しで効率処理）            |
+| `verify_citation`   | AIの回答に含まれる法令引用を検証する（条文存在確認・テキスト照合、最大10件）                |
+| `suggest_related`   | 指定した条文の関連法令・委任先・同法令内参照を自動抽出して提案する                          |
+| `analyze_article`   | 条文の構造解析メタデータ（項数・号数・参照統計・プレビュー）をJSON形式で返す                |
+| `get_metrics`       | サーバーの使用量メトリクスを返す（ツール呼び出し回数・APIリクエスト数・キャッシュヒット率） |
 
 ### パラメータ
 
@@ -124,6 +131,36 @@ npm run build
 | `group`        | 章グループ（バッチチェック、省略時は全章） | `1章`        |
 | `show_history` | 改正履歴の詳細を表示（`law_name` 指定時）  | `true`       |
 
+#### `get_laws_batch`
+
+| パラメータ | 説明                                                                   | 例  |
+| ---------- | ---------------------------------------------------------------------- | --- |
+| `requests` | 取得対象の配列。各要素に `law_name`, `article_number`, `format` を指定 | —   |
+
+#### `verify_citation`
+
+| パラメータ  | 説明                                                                            | 例  |
+| ----------- | ------------------------------------------------------------------------------- | --- |
+| `citations` | 検証対象の配列。各要素に `law_name`, `article_number`, `claimed_text`（省略可） | —   |
+
+#### `suggest_related`
+
+| パラメータ       | 説明                         | 例           |
+| ---------------- | ---------------------------- | ------------ |
+| `law_name`       | 法令名（正式名称または略称） | `建築基準法` |
+| `article_number` | 条文番号                     | `第20条`     |
+
+#### `analyze_article`
+
+| パラメータ       | 説明                         | 例           |
+| ---------------- | ---------------------------- | ------------ |
+| `law_name`       | 法令名（正式名称または略称） | `建築基準法` |
+| `article_number` | 条文番号                     | `第20条`     |
+
+#### `get_metrics`
+
+パラメータなし。サーバー起動後の稼働時間・ツール呼び出し回数・API リクエスト数・キャッシュヒット率を返す。
+
 ## 使用例
 
 ### 条文取得
@@ -172,7 +209,7 @@ npm run build
 
 ## 対応法令一覧（115 法令）
 
-### 第1章 総則（4 法令）
+### 総則（4 法令）
 
 | 法令名             | 略称                 |
 | ------------------ | -------------------- |
@@ -181,7 +218,7 @@ npm run build
 | 建築基準法施行規則 | 建基規則             |
 | 民法               | —                    |
 
-### 第2章 手続関連規定（6 法令）
+### 手続関連規定（6 法令）
 
 | 法令名           | 略称         |
 | ---------------- | ------------ |
@@ -192,7 +229,7 @@ npm run build
 | 建設業法施行令   | —            |
 | 建設業法施行規則 | —            |
 
-### 第3章 集団規定・街づくり規定（13 法令）
+### 集団規定・街づくり（13 法令）
 
 | 法令名                                             | 略称                   |
 | -------------------------------------------------- | ---------------------- |
@@ -210,7 +247,7 @@ npm run build
 | 国土利用計画法                                     | 国土利用計画法, 国土法 |
 | 都市計画法施行規則                                 | 都計規則               |
 
-### 第4章 防火規定・耐火規定（4 法令）
+### 防火・耐火規定（4 法令）
 
 | 法令名                   | 略称       |
 | ------------------------ | ---------- |
@@ -219,7 +256,7 @@ npm run build
 | 消防法施行規則           | 消防規則   |
 | 危険物の規制に関する規則 | 危険物規則 |
 
-### 第5章 構造規定（7 法令）
+### 構造規定（7 法令）
 
 | 法令名                                     | 略称                   |
 | ------------------------------------------ | ---------------------- |
@@ -231,7 +268,7 @@ npm run build
 | 建築物の耐震改修の促進に関する法律施行令   | 耐震改修促進法施行令   |
 | 建築物の耐震改修の促進に関する法律施行規則 | 耐震改修促進法施行規則 |
 
-### 第6章 建築材料（3 法令）
+### 建築材料（3 法令）
 
 | 法令名           | 略称                   |
 | ---------------- | ---------------------- |
@@ -239,7 +276,7 @@ npm run build
 | 製造物責任法     | PL法, 製造物責任法     |
 | 石綿障害予防規則 | 石綿則, アスベスト規則 |
 
-### 第7章 設備関連規定（5 法令）
+### 設備関連規定（5 法令）
 
 | 法令名                     | 略称             |
 | -------------------------- | ---------------- |
@@ -249,7 +286,7 @@ npm run build
 | 浄化槽法施行令             | —                |
 | 環境省関係浄化槽法施行規則 | 浄化槽法施行規則 |
 
-### 第8章 その他（5 法令）
+### その他（5 法令）
 
 | 法令名                                         | 略称               |
 | ---------------------------------------------- | ------------------ |
@@ -259,7 +296,7 @@ npm run build
 | 不動産の鑑定評価に関する法律                   | 不動産鑑定法       |
 | 住宅宿泊事業法                                 | 民泊新法           |
 
-### 第9章 建築基準関係規定・建築関連法令（52 法令）
+### 建築基準関係規定・建築関連法令（52 法令）
 
 <details>
 <summary>法令一覧を表示</summary>
@@ -321,7 +358,7 @@ npm run build
 
 </details>
 
-### 第10章 省エネ法・住宅関連法（13 法令）
+### 省エネ・住宅関連法（13 法令）
 
 | 法令名                                                             | 略称                   |
 | ------------------------------------------------------------------ | ---------------------- |
@@ -339,7 +376,7 @@ npm run build
 | 長期優良住宅の普及の促進に関する法律施行規則                       | 長期優良住宅法施行規則 |
 | 建築物のエネルギー消費性能の向上等に関する法律施行規則             | 建築物省エネ法施行規則 |
 
-### 第11章 既存建築物関連（3 法令）
+### 既存建築物関連（3 法令）
 
 | 法令名                                     | 略称             |
 | ------------------------------------------ | ---------------- |
@@ -368,6 +405,30 @@ e-Gov API は告示を収録していないため、`get_kokuji` は国土交通
 - `check_law_updates` ツールで法令の改正状況を確認できます（e-Gov API のリビジョン履歴を参照）
 - 法令改正による `law_id` の無効化リスクは低い（`law_id` は法令番号ベースの固有識別子）
 
+## 環境変数
+
+| 変数                     | 説明                                              | デフォルト                   |
+| ------------------------ | ------------------------------------------------- | ---------------------------- |
+| `BUILDING_LAW_CACHE`     | キャッシュモード（`memory` / `file`）             | `memory`                     |
+| `BUILDING_LAW_CACHE_DIR` | ファイルキャッシュの保存先ディレクトリ            | `~/.cache/building-law-mcp/` |
+| `BUILDING_LAW_LOG_LEVEL` | ログレベル（`debug` / `info` / `warn` / `error`） | `info`                       |
+
+### 永続キャッシュの有効化
+
+```json
+{
+  "mcpServers": {
+    "building-law": {
+      "command": "npx",
+      "args": ["-y", "building-law-mcp"],
+      "env": {
+        "BUILDING_LAW_CACHE": "file"
+      }
+    }
+  }
+}
+```
+
 ## 技術仕様
 
 | 項目                         | 値                               |

package/dist/index.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createServer } from "./server.js";
+import { logger } from "./lib/logger.js";
 const server = createServer();
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error("building-law-mcp Server running on stdio");
+    logger.info("server started", { transport: "stdio" });
 }
 main().catch((error) => {
     console.error("Fatal error:", error);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;AAE9B,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,0CAA0C,CAAC,CAAC;AAC5D,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;AAE9B,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC;AACxD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/lib/article-analyzer.d.ts

@@ -0,0 +1,5 @@
+import type { ArticleAnalysis } from "./types.js";
+/**
+ * Analyze a single article and return structured metadata.
+ */
+export declare function analyzeArticle(lawName: string, articleNumber: string): Promise<ArticleAnalysis>;

package/dist/lib/article-analyzer.js

@@ -0,0 +1,106 @@
+import { getLawData } from "./egov-client.js";
+import { parseArticleStructured } from "./egov-parser.js";
+import { LawRegistry } from "./law-registry.js";
+const registry = new LawRegistry();
+const PREVIEW_LENGTH = 100;
+/**
+ * Remove parentheses from caption text.
+ * "（構造耐力）" → "構造耐力"
+ */
+function stripParentheses(caption) {
+    return caption.replace(/^[（(]/, "").replace(/[）)]$/, "");
+}
+/**
+ * Count total characters in a structured article.
+ */
+function countCharacters(article) {
+    let count = 0;
+    for (const para of article.paragraphs) {
+        count += para.paragraph_sentence.length;
+        for (const item of para.items) {
+            count += item.item_sentence.length;
+            for (const sub of item.subitems) {
+                count += countSubitemChars(sub);
+            }
+        }
+    }
+    return count;
+}
+function countSubitemChars(sub) {
+    let count = sub.subitem_sentence.length;
+    for (const child of sub.subitems) {
+        count += countSubitemChars(child);
+    }
+    return count;
+}
+/**
+ * Count total subitems recursively.
+ */
+function countSubitems(article) {
+    let count = 0;
+    for (const para of article.paragraphs) {
+        for (const item of para.items) {
+            count += countSubitemsRecursive(item.subitems);
+        }
+    }
+    return count;
+}
+function countSubitemsRecursive(subs) {
+    let count = subs.length;
+    for (const sub of subs) {
+        count += countSubitemsRecursive(sub.subitems);
+    }
+    return count;
+}
+/**
+ * Analyze a single article and return structured metadata.
+ */
+export async function analyzeArticle(lawName, articleNumber) {
+    const preset = registry.findByName(lawName);
+    if (!preset) {
+        throw new Error(`法令「${lawName}」がプリセットに見つかりませんでした。`);
+    }
+    const lawData = await getLawData(preset.law_id);
+    const article = parseArticleStructured(lawData.law_full_text, articleNumber);
+    if (!article) {
+        throw new Error(`${preset.title}に第${articleNumber}条が見つかりませんでした。`);
+    }
+    const itemCount = article.paragraphs.reduce((sum, p) => sum + p.items.length, 0);
+    const refs = article.references ?? [];
+    const crossLawRefs = refs.filter((r) => r.ref_type === "cross_law");
+    const referencedLaws = [
+        ...new Set(crossLawRefs
+            .map((r) => r.target_law)
+            .filter((l) => l !== undefined)),
+    ];
+    return {
+        law_name: preset.title,
+        law_num: preset.law_num,
+        article_num: article.article_num,
+        article_title: article.article_title,
+        caption: stripParentheses(article.article_caption),
+        structure: {
+            paragraph_count: article.paragraphs.length,
+            item_count: itemCount,
+            subitem_count: countSubitems(article),
+            total_characters: countCharacters(article),
+        },
+        paragraph_summaries: article.paragraphs.map((p) => ({
+            paragraph_num: p.paragraph_num,
+            preview: p.paragraph_sentence.length > PREVIEW_LENGTH
+                ? p.paragraph_sentence.slice(0, PREVIEW_LENGTH) + "…"
+                : p.paragraph_sentence,
+            item_count: p.items.length,
+        })),
+        reference_summary: {
+            total: refs.length,
+            cross_law: crossLawRefs.length,
+            same_law: refs.filter((r) => r.ref_type === "same_law").length,
+            relative: refs.filter((r) => r.ref_type === "relative").length,
+            delegation: refs.filter((r) => r.ref_type === "delegation").length,
+            referenced_laws: referencedLaws,
+        },
+        structured_data: article,
+    };
+}
+//# sourceMappingURL=article-analyzer.js.map

package/dist/lib/article-analyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"article-analyzer.js","sourceRoot":"","sources":["../../src/lib/article-analyzer.ts"],"names":[],"mappings":"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"}

package/dist/lib/cache.d.ts

@@ -1,4 +1,18 @@
-export declare class TTLCache<T> {
+/**
+ * Common cache interface shared by all cache implementations.
+ */
+export interface ICache<T> {
+    get(key: string): T | undefined;
+    set(key: string, value: T, ttl_ms?: number): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    readonly size: number;
+}
+/**
+ * In-memory TTL cache. Entries expire after a configurable duration.
+ */
+export declare class TTLCache<T> implements ICache<T> {
     private readonly store;
     private readonly default_ttl_ms;
     constructor(default_ttl_ms?: number);
@@ -9,3 +23,28 @@ export declare class TTLCache<T> {
     clear(): void;
     get size(): number;
 }
+/**
+ * File-based TTL cache. Entries persist across server restarts.
+ * Each key is stored as an individual JSON file under
+ * `~/.cache/building-law-mcp/{name}/{hash}.json`.
+ */
+export declare class FileCache<T> implements ICache<T> {
+    private readonly dir;
+    private readonly default_ttl_ms;
+    constructor(name: string, default_ttl_ms?: number);
+    private keyToPath;
+    get(key: string): T | undefined;
+    set(key: string, value: T, ttl_ms?: number): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    get size(): number;
+}
+/**
+ * Factory function to create a cache instance based on the
+ * `BUILDING_LAW_CACHE` environment variable.
+ *
+ * - `"memory"` (default): in-memory TTLCache
+ * - `"file"`: file-based FileCache that persists across restarts
+ */
+export declare function createCache<T>(name: string, ttl_ms: number): ICache<T>;

package/dist/lib/cache.js

@@ -1,3 +1,10 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import * as crypto from "node:crypto";
+/**
+ * In-memory TTL cache. Entries expire after a configurable duration.
+ */
 export class TTLCache {
     store = new Map();
     default_ttl_ms;
@@ -41,4 +48,124 @@ export class TTLCache {
         return this.store.size;
     }
 }
+const DEFAULT_CACHE_DIR = path.join(os.homedir(), ".cache", "building-law-mcp");
+/**
+ * File-based TTL cache. Entries persist across server restarts.
+ * Each key is stored as an individual JSON file under
+ * `~/.cache/building-law-mcp/{name}/{hash}.json`.
+ */
+export class FileCache {
+    dir;
+    default_ttl_ms;
+    constructor(name, default_ttl_ms = 30 * 60 * 1000) {
+        this.default_ttl_ms = default_ttl_ms;
+        const cacheBase = process.env.BUILDING_LAW_CACHE_DIR ?? DEFAULT_CACHE_DIR;
+        this.dir = path.join(cacheBase, name);
+        fs.mkdirSync(this.dir, { recursive: true });
+    }
+    keyToPath(key) {
+        const hash = crypto.createHash("md5").update(key).digest("hex");
+        return path.join(this.dir, `${hash}.json`);
+    }
+    get(key) {
+        const filePath = this.keyToPath(key);
+        try {
+            const raw = fs.readFileSync(filePath, "utf-8");
+            const entry = JSON.parse(raw);
+            if (Date.now() > entry.expires_at) {
+                try {
+                    fs.unlinkSync(filePath);
+                }
+                catch {
+                    // ignore cleanup failure
+                }
+                return undefined;
+            }
+            return entry.value;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    set(key, value, ttl_ms) {
+        const ttl = ttl_ms ?? this.default_ttl_ms;
+        const entry = { value, expires_at: Date.now() + ttl };
+        fs.writeFileSync(this.keyToPath(key), JSON.stringify(entry), "utf-8");
+    }
+    has(key) {
+        return this.get(key) !== undefined;
+    }
+    delete(key) {
+        try {
+            fs.unlinkSync(this.keyToPath(key));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    clear() {
+        try {
+            const files = fs.readdirSync(this.dir);
+            for (const file of files) {
+                if (file.endsWith(".json")) {
+                    try {
+                        fs.unlinkSync(path.join(this.dir, file));
+                    }
+                    catch {
+                        // ignore individual file cleanup failure
+                    }
+                }
+            }
+        }
+        catch {
+            // directory might not exist
+        }
+    }
+    get size() {
+        try {
+            const files = fs.readdirSync(this.dir).filter((f) => f.endsWith(".json"));
+            let count = 0;
+            for (const file of files) {
+                const filePath = path.join(this.dir, file);
+                try {
+                    const raw = fs.readFileSync(filePath, "utf-8");
+                    const entry = JSON.parse(raw);
+                    if (Date.now() <= entry.expires_at) {
+                        count++;
+                    }
+                    else {
+                        try {
+                            fs.unlinkSync(filePath);
+                        }
+                        catch {
+                            // ignore cleanup failure
+                        }
+                    }
+                }
+                catch {
+                    // corrupted file, skip
+                }
+            }
+            return count;
+        }
+        catch {
+            return 0;
+        }
+    }
+}
+/**
+ * Factory function to create a cache instance based on the
+ * `BUILDING_LAW_CACHE` environment variable.
+ *
+ * - `"memory"` (default): in-memory TTLCache
+ * - `"file"`: file-based FileCache that persists across restarts
+ */
+export function createCache(name, ttl_ms) {
+    const mode = process.env.BUILDING_LAW_CACHE ?? "memory";
+    if (mode === "file") {
+        return new FileCache(name, ttl_ms);
+    }
+    return new TTLCache(ttl_ms);
+}
 //# sourceMappingURL=cache.js.map

package/dist/lib/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/lib/cache.ts"],"names":[],"mappings":"AAKA,MAAM,OAAO,QAAQ;IACF,KAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;IACzC,cAAc,CAAS;IAExC,YAAY,iBAAyB,EAAE,GAAG,EAAE,GAAG,IAAI;QACjD,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;IACvC,CAAC;IAED,GAAG,CAAC,GAAW;QACb,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,UAAU,EAAE,CAAC;YAClC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,KAAQ,EAAE,MAAe;QACxC,MAAM,GAAG,GAAG,MAAM,IAAI,IAAI,CAAC,cAAc,CAAC;QAC1C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;YAClB,KAAK;YACL,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG;SAC7B,CAAC,CAAC;IACL,CAAC;IAED,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;IACrC,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED,IAAI,IAAI;QACN,8BAA8B;QAC9B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACtC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,UAAU,EAAE,CAAC;gBAClC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;CACF"}
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/lib/cache.ts"],"names":[],"mappings":"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"}

package/dist/lib/citation-verifier.d.ts

@@ -0,0 +1,14 @@
+import type { CitationVerification } from "./types.js";
+/**
+ * Normalize text for comparison: collapse whitespace, remove formatting artifacts.
+ */
+export declare function normalizeText(text: string): string;
+/**
+ * Calculate match score between claimed text and actual text.
+ * Returns a value between 0.0 and 1.0.
+ */
+export declare function calculateMatchScore(claimed: string, actual: string): number;
+/**
+ * Verify a single citation against the actual law text.
+ */
+export declare function verifyCitation(lawName: string, articleNumber: string, claimedText?: string): Promise<CitationVerification>;