labre-mcp 0.1.0

package/dist/lib/owm/svg-bbox-parser.mjs

@@ -0,0 +1,251 @@
+// Extract approximate bounding boxes from a cli-owm-rendered SVG so the
+// chain pipeline (`verify-layout`) can run collision detection in pixel
+// space.
+//
+// The parser is deliberately tightly-scoped to the SVG shape that
+// cli-owm emits today (verified by inspection 2026-05-06). It does NOT
+// aim for general SVG support — that is a non-goal. The contract is:
+// "given a cli-owm SVG and the set of known component names, return
+// bboxes for every component, label and anchor we recognise; plus the
+// dependency edges and the canvas dimensions". Any decoration (axes,
+// title, gradient stops, dash patterns) is filtered out by name
+// matching: anything whose `<text>` content is not in `knownNames` is
+// ignored. This is more robust than heuristic geometry filtering
+// because chain titles or future axis labels cannot accidentally creep
+// in.
+//
+// Text bbox estimation uses a constant char-width approximation
+// (`LABEL_CHAR_WIDTH = 7px` at the cli-owm default 14px font), which
+// over-estimates narrow glyphs (`i`, `l`, `.`) and under-estimates
+// wide ones (`m`, `w`). The over-estimation bias is intentional: a
+// false-positive collision is worth less correction work than a
+// false-negative that lets two labels overlap in the rendered map.
+// Future work could bind `node-canvas` or `opentype.js` to measure
+// glyphs against the actual font without changing this module's
+// public API.
+// ─── Constants ──────────────────────────────────────────────────────────
+/** Approximate pixel width of one character at the cli-owm default 14px
+ *  font (Helvetica Neue / Arial). Empirical, slightly over-estimates. */
+export const LABEL_CHAR_WIDTH = 7;
+/** Approximate text bbox height — cap height + descent at 14px font. */
+export const LABEL_HEIGHT = 16;
+/** Default `r` attribute used by cli-owm for component circles. */
+export const COMPONENT_RADIUS = 5;
+/** Tolerance (px) used when matching `<line>` endpoints to known
+ *  component centres. cli-owm emits coordinates with floating-point
+ *  rounding noise (e.g. `30.00000000000003`), so an exact match would
+ *  miss legitimate edges. */
+export const ENDPOINT_MATCH_TOLERANCE = 0.5;
+/** Phase boundary ratios inside the visible map area, matching the
+ *  OWM canonical Genesis|Custom-Built|Product|Commodity divisions
+ *  (verified by inspection of cli-owm's `<g id="valueChain">` 2026-05-06). */
+export const PHASE_AXIS_RATIOS = [0.175, 0.40, 0.70];
+// ─── SVG slicing ────────────────────────────────────────────────────────
+/** Strip out every `<g id="valueChain">…</g>`, `<g id="Evolution">…</g>`
+ *  and `<defs>…</defs>` block. These groups only contain axis
+ *  decorations and gradient definitions — never component content. */
+function stripDecorationGroups(svg) {
+    const blockRegexes = [
+        /<defs\b[\s\S]*?<\/defs>/g,
+        /<g\s+id="valueChain"[^>]*>[\s\S]*?<\/g>/g,
+        /<g\s+id="Evolution"[^>]*>[\s\S]*?<\/g>/g,
+    ];
+    return blockRegexes.reduce((acc, rx) => acc.replace(rx, ''), svg);
+}
+// ─── Token regexes ─────────────────────────────────────────────────────
+const CIRCLE_RX = /<circle\s+([^>/]+)\/?>/g;
+const TEXT_RX = /<text\s+([^>]+)>([\s\S]*?)<\/text>/g;
+const LINE_RX = /<line\s+([^>/]+)\/?>/g;
+const ATTR_RX = /(\w[\w-]*)\s*=\s*"([^"]*)"/g;
+function readAttrs(s) {
+    const out = {};
+    ATTR_RX.lastIndex = 0;
+    let m;
+    while ((m = ATTR_RX.exec(s)) !== null)
+        out[m[1]] = m[2];
+    return out;
+}
+function num(s) {
+    if (s === undefined)
+        return NaN;
+    const n = parseFloat(s);
+    return Number.isFinite(n) ? n : NaN;
+}
+function decodeText(raw) {
+    // cli-owm emits straight ASCII content for component names; honour
+    // the small set of XML entities we might encounter in user-supplied
+    // names.
+    return raw
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'");
+}
+// ─── Bbox builders ─────────────────────────────────────────────────────
+function circleBbox(cx, cy, r) {
+    return { x: cx - r, y: cy - r, width: 2 * r, height: 2 * r };
+}
+function textBbox(x, y, anchor, content) {
+    const width = Math.max(1, content.length) * LABEL_CHAR_WIDTH;
+    // SVG `<text>` `y` is the baseline; the visual top is roughly one
+    // line-height above. We give a 2px descent below the baseline so
+    // the bbox covers descenders of glyphs like `g`, `p`, `y`.
+    const top = y - (LABEL_HEIGHT - 2);
+    const left = anchor === 'middle' ? x - width / 2
+        : anchor === 'end' ? x - width
+            : /* start */ x;
+    return { x: left, y: top, width, height: LABEL_HEIGHT };
+}
+// ─── Canvas + edges + items extraction ─────────────────────────────────
+function extractCanvas(svg) {
+    // Read width/height from the root `<svg ...>` opening tag only —
+    // any nested `<svg>` (rare, but safe to ignore) wouldn't be the
+    // canvas reference.
+    const closeIdx = svg.indexOf('>');
+    if (closeIdx < 0)
+        return { width: 0, height: 0 };
+    const head = svg.slice(0, closeIdx + 1);
+    const w = head.match(/\bwidth="([^"]+)"/);
+    const h = head.match(/\bheight="([^"]+)"/);
+    return {
+        width: w ? Math.max(0, num(w[1]) || 0) : 0,
+        height: h ? Math.max(0, num(h[1]) || 0) : 0,
+    };
+}
+/** Locate the `<rect id="fillArea">` and return its bbox. cli-owm
+ *  emits this rect with the visible map dimensions (typically the same
+ *  as the DSL `size [w, h]` directive when forwarded by our adapter).
+ *  Falls back to `(0, 0, canvas.width, canvas.height)` if the rect
+ *  isn't present in the SVG (defensive — older cli-owm versions or
+ *  custom themes might omit it). */
+function extractMapArea(svg, canvas) {
+    const rectMatch = svg.match(/<rect\b[^>]*\bid="fillArea"[^>]*\/?>/);
+    if (rectMatch) {
+        const attrs = readAttrs(rectMatch[0].slice(0, -1)); // strip trailing >
+        const x = num(attrs.x), y = num(attrs.y);
+        const width = num(attrs.width), height = num(attrs.height);
+        if (Number.isFinite(x) && Number.isFinite(y)
+            && Number.isFinite(width) && Number.isFinite(height)
+            && width > 0 && height > 0) {
+            return { x, y, width, height };
+        }
+    }
+    return { x: 0, y: 0, width: canvas.width, height: canvas.height };
+}
+/** Pixel X coordinates of the three OWM phase boundaries inside the
+ *  map area. Returns an empty array when the map area is undefined
+ *  (width <= 0). */
+function computePhaseAxes(mapArea) {
+    if (mapArea.width <= 0)
+        return [];
+    return PHASE_AXIS_RATIOS.map(r => mapArea.x + r * mapArea.width);
+}
+/** Walk `<circle>` and `<text>` tokens in document order and pair each
+ *  circle with its following matching label. Anchors are emitted
+ *  directly from middle-anchored `<text>` tokens. Also records the
+ *  endpoint position for each named component/anchor so edges can be
+ *  resolved later. */
+function parseItemsAndPositions(svg, knownNames) {
+    const stripped = stripDecorationGroups(svg);
+    const items = [];
+    const positions = [];
+    CIRCLE_RX.lastIndex = 0;
+    TEXT_RX.lastIndex = 0;
+    let circleMatch = CIRCLE_RX.exec(stripped);
+    let textMatch = TEXT_RX.exec(stripped);
+    let pendingCircle = null;
+    while (circleMatch !== null || textMatch !== null) {
+        const useCircle = textMatch === null ||
+            (circleMatch !== null && circleMatch.index < textMatch.index);
+        if (useCircle && circleMatch !== null) {
+            const attrs = readAttrs(circleMatch[1]);
+            const cx = num(attrs.cx), cy = num(attrs.cy), r = num(attrs.r);
+            if (Number.isFinite(cx) && Number.isFinite(cy) && Number.isFinite(r)) {
+                pendingCircle = { cx, cy, r, index: circleMatch.index };
+            }
+            circleMatch = CIRCLE_RX.exec(stripped);
+            continue;
+        }
+        if (textMatch !== null) {
+            const attrs = readAttrs(textMatch[1]);
+            const x = num(attrs.x), y = num(attrs.y);
+            const anchor = attrs['text-anchor'] ?? 'start';
+            const name = decodeText(textMatch[2]).trim();
+            if (knownNames.has(name) && Number.isFinite(x) && Number.isFinite(y)) {
+                const lbl = textBbox(x, y, anchor, name);
+                if (anchor === 'middle') {
+                    items.push({ name, kind: 'anchor', bbox: lbl });
+                    positions.push({ name, x, y });
+                    pendingCircle = null;
+                }
+                else if (pendingCircle !== null) {
+                    items.push({ name, kind: 'component', bbox: circleBbox(pendingCircle.cx, pendingCircle.cy, pendingCircle.r) });
+                    items.push({ name, kind: 'label', bbox: lbl });
+                    positions.push({ name, x: pendingCircle.cx, y: pendingCircle.cy });
+                    pendingCircle = null;
+                }
+                // else: orphan text — silently drop (decoration we don't recognise)
+            }
+            textMatch = TEXT_RX.exec(stripped);
+        }
+    }
+    return { items, positions };
+}
+function matchEndpoint(x, y, positions) {
+    for (const p of positions) {
+        if (Math.abs(p.x - x) < ENDPOINT_MATCH_TOLERANCE
+            && Math.abs(p.y - y) < ENDPOINT_MATCH_TOLERANCE) {
+            return p.name;
+        }
+    }
+    return null;
+}
+/** Extract `<line>` elements at the top level (decoration groups are
+ *  already stripped) and resolve each endpoint to a component name via
+ *  `positions`. Lines whose endpoints don't match any known
+ *  component are silently dropped — cli-owm sometimes emits ancillary
+ *  lines (accelerator markers, baselines) that look like edges but
+ *  don't connect named nodes. */
+function extractEdges(svg, positions) {
+    const stripped = stripDecorationGroups(svg);
+    const out = [];
+    LINE_RX.lastIndex = 0;
+    let m;
+    while ((m = LINE_RX.exec(stripped)) !== null) {
+        const a = readAttrs(m[1]);
+        const x1 = num(a.x1), y1 = num(a.y1), x2 = num(a.x2), y2 = num(a.y2);
+        if (![x1, y1, x2, y2].every(Number.isFinite))
+            continue;
+        const from = matchEndpoint(x1, y1, positions);
+        const to = matchEndpoint(x2, y2, positions);
+        if (from !== null && to !== null && from !== to) {
+            out.push({ from, to, x1, y1, x2, y2 });
+        }
+    }
+    return out;
+}
+// ─── Public API ─────────────────────────────────────────────────────────
+/**
+ * Parse a cli-owm SVG into a flat geometry report plus its edges and
+ * canvas dimensions. Only elements whose text content is in
+ * `knownNames` survive the filter — this is by design (see file-level
+ * comment).
+ */
+export function parseSvgGeometry(svg, knownNames) {
+    const canvas = extractCanvas(svg);
+    const mapArea = extractMapArea(svg, canvas);
+    const phaseAxes = computePhaseAxes(mapArea);
+    const { items, positions } = parseItemsAndPositions(svg, knownNames);
+    const edges = extractEdges(svg, positions);
+    return { items, edges, canvas, mapArea, phaseAxes };
+}
+/**
+ * Backward-compatible alias for the V2 API. Equivalent to
+ * `parseSvgGeometry(...).items`. Existing callers that only need
+ * rect-rect collision detection keep working unchanged.
+ */
+export function parseSvgToBboxes(svg, knownNames) {
+    return parseSvgGeometry(svg, knownNames).items;
+}
+//# sourceMappingURL=svg-bbox-parser.mjs.map

package/dist/lib/owm/svg-bbox-parser.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"svg-bbox-parser.mjs","sourceRoot":"","sources":["../../../src/lib/owm/svg-bbox-parser.mts"],"names":[],"mappings":"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"}

package/dist/lib/patent/bigquery-client.d.mts

@@ -0,0 +1,124 @@
+import type { BigQueryClientConfig, BigQueryClientOptions } from '../../types/patent.mjs';
+/**
+ * Default BigQuery configuration values.
+ * Tuned for the Google Patents Public Dataset with conservative billing limits.
+ *
+ * @type {Readonly<BigQueryConfig>}
+ */
+export declare const DEFAULTS: Readonly<{
+    /** Google Patents Public Dataset — the primary data source for patent CPC data. */
+    dataset: "patents-public-data";
+    /** BigQuery job location — US for the public patents dataset. */
+    location: "US";
+    /** Maximum bytes billed per query (200 GB). Public dataset free tier is 1 TB/month. */
+    maxBytesBilled: string;
+    /** Query timeout in milliseconds (30 seconds). */
+    timeoutMs: 30000;
+    /** OAuth scopes — read-only access is sufficient for patent queries. */
+    scopes: string[];
+}>;
+/**
+ * BigQuery client configuration.
+ *
+ * @typedef {Object} BigQueryConfig
+ * @property {string}   projectId     - GCP project ID
+ * @property {string}   [keyFilename] - Path to service account JSON key file
+ * @property {string}   dataset       - BigQuery dataset name
+ * @property {string}   location      - BigQuery job location
+ * @property {string}   maxBytesBilled - Maximum bytes billed per query (string for BQ API)
+ * @property {number}   timeoutMs     - Query timeout in milliseconds
+ * @property {string[]} scopes        - OAuth scopes for authentication
+ */
+/**
+ * Validated and resolved configuration ready for BigQuery client instantiation.
+ *
+ * @typedef {Object} ResolvedConfig
+ * @property {string}   projectId      - Validated GCP project ID
+ * @property {string}   [keyFilename]  - Resolved path to credentials file (if set)
+ * @property {string}   dataset        - Dataset name
+ * @property {string}   location       - Job location
+ * @property {string}   maxBytesBilled - Max bytes as string
+ * @property {number}   timeoutMs      - Query timeout in ms
+ * @property {string[]} scopes         - OAuth scopes
+ */
+/**
+ * Resolve BigQuery configuration from explicit options + environment variables + defaults.
+ *
+ * Resolution priority (highest to lowest):
+ *   1. Explicit options passed to the function
+ *   2. Environment variables (BIGQUERY_PROJECT_ID, GOOGLE_APPLICATION_CREDENTIALS, etc.)
+ *   3. Built-in defaults from DEFAULTS
+ *
+ * @param {Partial<BigQueryConfig>} [options={}] - Explicit config overrides
+ * @returns {ResolvedConfig} Fully resolved configuration
+ * @throws {Error} If BIGQUERY_PROJECT_ID is missing from both options and env
+ */
+export declare function resolveConfig(options?: BigQueryClientOptions): BigQueryClientConfig;
+/**
+ * Validate a resolved BigQuery configuration.
+ * Returns a list of issues (empty if config is valid).
+ *
+ * @param {ResolvedConfig} config - Configuration to validate
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export declare function validateConfig(config: BigQueryClientConfig): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Create or retrieve a BigQuery client instance for the given configuration.
+ *
+ * Uses a singleton pool keyed by projectId: if a client already exists for
+ * the project, it is reused. This avoids redundant authentication handshakes
+ * and connection setup when multiple queries target the same project.
+ *
+ * The client is lazily created on first call and cached for the process lifetime
+ * (or until destroyClient() is called).
+ *
+ * @param {ResolvedConfig} config - Resolved BigQuery configuration
+ * @returns {Promise<Object>} BigQuery client instance (from @google-cloud/bigquery)
+ * @throws {Error} If @google-cloud/bigquery is not installed
+ * @throws {Error} If configuration is invalid
+ */
+export declare function getClient(config?: BigQueryClientConfig | BigQueryClientOptions): Promise<any>;
+/**
+ * Destroy (remove from pool) the BigQuery client for a given project.
+ * Use this for graceful shutdown or to force re-authentication.
+ *
+ * @param {string} projectId - GCP project ID whose client to destroy
+ * @returns {boolean} true if a client was removed, false if none existed
+ */
+export declare function destroyClient(projectId: string): boolean;
+/**
+ * Destroy all pooled BigQuery clients.
+ * Call this during process shutdown to release all resources.
+ */
+export declare function destroyAllClients(): void;
+/**
+ * Get the current number of pooled clients (for monitoring/testing).
+ * @returns {number}
+ */
+export declare function poolSize(): number;
+/**
+ * Default query options derived from configuration.
+ * Used by BigQueryPatentSource to run parameterized queries with consistent
+ * billing and timeout controls.
+ *
+ * @param {ResolvedConfig} config - Resolved BigQuery configuration
+ * @returns {Object} Base query options for BigQuery .query() calls
+ */
+export declare function defaultQueryOptions(config: BigQueryClientConfig): Record<string, unknown>;
+/**
+ * Check whether the required environment variables are set for BigQuery access.
+ * Returns a diagnostic object (does not throw) — useful for health checks and
+ * graceful degradation in the strategy pipeline.
+ *
+ * @returns {{ ready: boolean, projectId: string|null, hasCredentials: boolean, missing: string[] }}
+ */
+export declare function checkEnvironment(): {
+    ready: boolean;
+    projectId: string | null;
+    hasCredentials: boolean;
+    missing: string[];
+};
+//# sourceMappingURL=bigquery-client.d.mts.map

package/dist/lib/patent/bigquery-client.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bigquery-client.d.mts","sourceRoot":"","sources":["../../../src/lib/patent/bigquery-client.mts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AA0B1F;;;;;GAKG;AACH,eAAO,MAAM,QAAQ;IACnB,mFAAmF;;IAGnF,iEAAiE;;IAGjE,uFAAuF;;IAGvF,kDAAkD;;IAGlD,wEAAwE;;EAExE,CAAC;AAIH;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;GAWG;AAIH;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,qBAA0B,GAAG,oBAAoB,CAsDvF;AAID;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAiDjG;AAaD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,SAAS,CAAC,MAAM,GAAE,oBAAoB,GAAG,qBAA0B,gBA+CxF;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,WAE9C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,SAEhC;AAED;;;GAGG;AACH,wBAAgB,QAAQ,WAEvB;AAID;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzF;AAID;;;;;;GAMG;AACH,wBAAgB,gBAAgB;;;;;EAgB/B"}