@co-engram/core 0.1.0 → 0.1.1

package/dist/merge/driver-llm.js

@@ -0,0 +1,174 @@
+/**
+ * Driver-side LLM client bootstrap (spec §5.1).
+ *
+ * 问题:host (claude-code-mcp / openclaw-plugin) 启动时已经构造了 LlmClient 实例,
+ * 但 git merge driver 是 git 直接 spawn 的独立进程,host 无法注入对象引用。
+ *
+ * 解决:host 把 LLM 配置(endpoint / apiKey / model)序列化到
+ * `~/.co-engram/llm-config.json`,driver 启动时读出来用 fetch 构造 HTTP client。
+ *
+ * 协议选 OpenAI-compatible(/chat/completions) —— 最通用:
+ *   - OpenAI / Azure / 通义 / 智谱 / DeepSeek / 月之暗面 / ollama 原生支持
+ *   - Anthropic 也有 OpenAI 兼容端点(https://api.anthropic.com/v1/openai/v1)
+ *
+ * @module @co-engram/core/merge
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpdir, homedir } from "node:os";
+/** 文件名(相对于 dataRoot/.co-engram/) */
+const CONFIG_FILENAME = "llm-config.json";
+/**
+ * 解析 config 文件路径。
+ *
+ * 优先级:
+ *   1. `$CO_ENGRAM_LLM_CONFIG`(绝对路径,测试用)
+ *   2. `$HOME/.co-engram/llm-config.json`(默认)
+ *   3. 退化:OS tmpdir(不推荐,仅当 HOME 缺失时)
+ */
+export function resolveLlmConfigPath() {
+    const override = process.env.CO_ENGRAM_LLM_CONFIG;
+    if (override)
+        return override;
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? homedir();
+    if (home)
+        return join(home, ".co-engram", CONFIG_FILENAME);
+    return join(tmpdir(), ".co-engram", CONFIG_FILENAME);
+}
+/**
+ * 写 LLM 配置到磁盘(host 启动时调用)。
+ *
+ * 不抛错 —— 写失败只警告,host 不应因 LLM 配置写盘失败而崩溃。
+ */
+export function writeLlmClientConfig(config) {
+    try {
+        const path = resolveLlmConfigPath();
+        mkdirSync(dirname(path), { recursive: true });
+        const full = {
+            ...config,
+            writtenAt: new Date().toISOString(),
+        };
+        writeFileSync(path, JSON.stringify(full, null, 2), "utf8");
+        return { ok: true, path };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: e instanceof Error ? e.message : String(e),
+        };
+    }
+}
+/**
+ * 读 LLM 配置(driver 启动时调用)。
+ *
+ * 不抛错 —— 读失败/文件缺失都返回 undefined,driver 退化为 no-LLM 模式。
+ */
+export function readLlmClientConfig() {
+    try {
+        const path = resolveLlmConfigPath();
+        if (!existsSync(path))
+            return undefined;
+        const raw = readFileSync(path, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.endpoint !== "string" ||
+            typeof parsed.apiKey !== "string" ||
+            typeof parsed.model !== "string") {
+            return undefined;
+        }
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 删除 LLM 配置(uninstall 时调用)。
+ *
+ * 用于 host 完全卸载 merge driver 时清理敏感数据。
+ * 失败不抛错,只返回 status。
+ */
+export function clearLlmClientConfig() {
+    try {
+        const path = resolveLlmConfigPath();
+        if (!existsSync(path))
+            return { ok: true, path };
+        rmSync(path, { force: true });
+        return { ok: true, path };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: e instanceof Error ? e.message : String(e),
+        };
+    }
+}
+/**
+ * 把任意 endpoint 规范化为完整 chat completions URL。
+ *
+ * - 已是 /chat/completions 结尾 → 不变
+ * - 是 base URL(如 https://api.openai.com/v1)→ 自动追加 /chat/completions
+ */
+function normalizeEndpoint(endpoint) {
+    const trimmed = endpoint.replace(/\/+$/, "");
+    if (/\/chat\/completions$/.test(trimmed))
+        return trimmed;
+    return `${trimmed}/chat/completions`;
+}
+/**
+ * 创建 OpenAI-compatible HTTP LlmClient(基于 fetch)。
+ *
+ * 任何抛错都让调用方(LlmArbiter)捕获并降级到 escalate。
+ */
+export function createHttpLlmClient(config) {
+    const endpoint = normalizeEndpoint(config.endpoint);
+    return {
+        async complete(prompt, opts = {}) {
+            const headers = {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${config.apiKey}`,
+                ...(config.headers ?? {}),
+            };
+            const body = {
+                model: config.model,
+                temperature: opts.temperature ?? 0.1,
+                max_tokens: opts.maxTokens ?? 300,
+                messages: [{ role: "user", content: prompt }],
+            };
+            const resp = await fetch(endpoint, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(opts.timeoutMs ?? 15_000),
+            });
+            if (!resp.ok) {
+                const text = await resp.text();
+                throw new Error(`LLM call failed (${resp.status}): ${text.slice(0, 200)}`);
+            }
+            const json = (await resp.json());
+            const choice = json.choices?.[0]?.message;
+            // reasoning 模型 fallback:某些 endpoint 把内容塞到 reasoning_content
+            const content = choice?.content ?? choice?.reasoning_content ?? "";
+            if (!content) {
+                throw new Error("LLM returned empty content");
+            }
+            return content;
+        },
+    };
+}
+/**
+ * Driver 启动时的便捷入口:读 config + 构造 client。
+ *
+ * 失败返回 null,driver 退化为 no-LLM 模式(机械规则解决不了的冲突 → marker)。
+ */
+export function createDriverLlmClient() {
+    const config = readLlmClientConfig();
+    if (!config)
+        return null;
+    try {
+        return { client: createHttpLlmClient(config), config };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=driver-llm.js.map

package/dist/merge/driver-llm.js.map

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

package/dist/merge/driver-main.d.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * Git merge driver CLI entry.
+ *
+ * Git invokes: `node driver.js %O %A %B %L %P`
+ *   %O = base (common ancestor)        argv[2]
+ *   %A = ours (also the output target)  argv[3]
+ *   %B = theirs                         argv[4]
+ *   %L = conflict marker size           argv[5]
+ *   %P = repo-relative path             argv[6]
+ *
+ * Routing:
+ *   - isEngramFile(content) → mergeEngramFile
+ *   - synapse path (starts with 'synapses/' + ends '.yaml') → mergeSynapseFile
+ *   - everything else → transparent git merge-file fallback
+ *
+ * Behavior:
+ *   - Escalation → write conflict markers + exit 1.
+ *   - Any thrown error → write conflict markers + exit 1.
+ *
+ * @module @co-engram/core/merge
+ */
+import { DRIVER_BUNDLE_VERSION } from "./version.js";
+export declare function runDriver(argv: string[]): Promise<{
+    exitCode: number;
+    stderr?: string;
+}>;
+export { DRIVER_BUNDLE_VERSION };
+//# sourceMappingURL=driver-main.d.ts.map

package/dist/merge/driver-main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver-main.d.ts","sourceRoot":"","sources":["../../src/merge/driver-main.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;GAoBG;AASH,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAqBrD,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC,CAoHD;AAoGD,OAAO,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/merge/driver-main.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+/**
+ * Git merge driver CLI entry.
+ *
+ * Git invokes: `node driver.js %O %A %B %L %P`
+ *   %O = base (common ancestor)        argv[2]
+ *   %A = ours (also the output target)  argv[3]
+ *   %B = theirs                         argv[4]
+ *   %L = conflict marker size           argv[5]
+ *   %P = repo-relative path             argv[6]
+ *
+ * Routing:
+ *   - isEngramFile(content) → mergeEngramFile
+ *   - synapse path (starts with 'synapses/' + ends '.yaml') → mergeSynapseFile
+ *   - everything else → transparent git merge-file fallback
+ *
+ * Behavior:
+ *   - Escalation → write conflict markers + exit 1.
+ *   - Any thrown error → write conflict markers + exit 1.
+ *
+ * @module @co-engram/core/merge
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { isEngramFile } from "../storage/engram-store.js";
+import { mergeEngramFile } from "./merge-engram.js";
+import { mergeSynapseFile, mergeSynapseFileAsync } from "./synapse-merger.js";
+import { findDataRoot } from "./data-root.js";
+import { AuditLog } from "../observability/audit-log.js";
+import { DRIVER_BUNDLE_VERSION } from "./version.js";
+import { LlmArbiter } from "./llm-arbiter.js";
+import { createDriverLlmClient } from "./driver-llm.js";
+const isMain = typeof require !== "undefined" &&
+    require.main &&
+    typeof __filename !== "undefined" &&
+    require.main.filename === __filename;
+const USAGE = "usage: co-engram-merge-driver %O %A %B %L %P";
+/** Heuristic: synapse files live under synapses/ and have .yaml extension. */
+function isSynapsePath(relPath) {
+    const normalized = relPath.replace(/\\/g, "/");
+    return normalized.startsWith("synapses/") && normalized.endsWith(".yaml");
+}
+export async function runDriver(argv) {
+    const args = argv.slice(2);
+    if (args.length < 5) {
+        return { exitCode: 1, stderr: USAGE };
+    }
+    const [baseP, oursP, theirsP, markerSizeStr, pathArg] = args;
+    const markerSize = parseInt(markerSizeStr, 10) || 7;
+    let baseRaw, oursRaw, theirsRaw;
+    try {
+        baseRaw = readFileSync(baseP, "utf8");
+        oursRaw = readFileSync(oursP, "utf8");
+        theirsRaw = readFileSync(theirsP, "utf8");
+    }
+    catch (e) {
+        return {
+            exitCode: 1,
+            stderr: `co-engram-merge-driver: failed to read input files: ${e instanceof Error ? e.message : String(e)}`,
+        };
+    }
+    // Route: engram vs synapse vs non-engram
+    const isEngram = isEngramFile(oursRaw) || isEngramFile(baseRaw) || isEngramFile(theirsRaw);
+    if (!isEngram && isSynapsePath(pathArg)) {
+        return await runSynapseMerge({
+            baseP,
+            oursP,
+            baseRaw,
+            oursRaw,
+            theirsRaw,
+            pathArg,
+        });
+    }
+    if (!isEngram) {
+        // Transparent fallback: let git merge-file do its thing
+        const result = spawnSync("git", [
+            "merge-file",
+            "-p",
+            `--marker-size=${markerSize}`,
+            oursP,
+            baseP,
+            theirsP,
+        ], { encoding: "utf8" });
+        if (typeof result.stdout === "string") {
+            writeFileSync(oursP, result.stdout, "utf8");
+        }
+        // exit status: 0 = clean, >0 = conflict count, null = error
+        return { exitCode: result.status ?? 1 };
+    }
+    // Engram merge
+    let dataRoot = null;
+    try {
+        dataRoot = findDataRoot(oursP);
+    }
+    catch {
+        dataRoot = null;
+    }
+    const auditLog = dataRoot ? new AuditLog(dataRoot) : undefined;
+    // Construct LLM arbiter if config available (Layer B, spec §5.6)
+    const llmBootstrap = createDriverLlmClient();
+    const llmArbiter = llmBootstrap
+        ? new LlmArbiter({
+            client: llmBootstrap.client,
+            auditLog,
+            providerName: llmBootstrap.config.model,
+        })
+        : undefined;
+    try {
+        const result = await mergeEngramFile({
+            baseRaw,
+            oursRaw,
+            theirsRaw,
+            relPath: pathArg,
+            dataRoot: dataRoot ?? undefined,
+            auditLog,
+            llmArbiter,
+        });
+        writeFileSync(oursP, result.mergedContent, "utf8");
+        if (result.escalated) {
+            auditLog?.append({
+                actor: "system",
+                action: "merge_conflict_escalated",
+                metadata: {
+                    path: pathArg,
+                    reason: result.strategy,
+                },
+            });
+            return { exitCode: 1 };
+        }
+        return { exitCode: 0 };
+    }
+    catch (e) {
+        return handleDriverError(e, {
+            oursP,
+            oursRaw,
+            theirsRaw,
+            pathArg,
+            auditLog,
+        });
+    }
+}
+async function runSynapseMerge(params) {
+    const { oursP, baseRaw, oursRaw, theirsRaw, pathArg } = params;
+    let dataRoot = null;
+    try {
+        dataRoot = findDataRoot(params.baseP);
+    }
+    catch {
+        dataRoot = null;
+    }
+    const auditLog = dataRoot ? new AuditLog(dataRoot) : undefined;
+    // Construct LLM arbiter if config available (Layer B)
+    const llmBootstrap = createDriverLlmClient();
+    const llmArbiter = llmBootstrap
+        ? new LlmArbiter({
+            client: llmBootstrap.client,
+            auditLog,
+            providerName: llmBootstrap.config.model,
+        })
+        : undefined;
+    try {
+        const result = llmArbiter
+            ? await mergeSynapseFileAsync({
+                baseRaw,
+                oursRaw,
+                theirsRaw,
+                arbiter: llmArbiter,
+                path: pathArg,
+            })
+            : mergeSynapseFile({ baseRaw, oursRaw, theirsRaw });
+        writeFileSync(oursP, result.mergedContent, "utf8");
+        if (result.escalated) {
+            auditLog?.append({
+                actor: "system",
+                action: "merge_conflict_escalated",
+                metadata: { path: pathArg, reason: result.strategy },
+            });
+            return { exitCode: 1 };
+        }
+        auditLog?.append({
+            actor: "system",
+            action: "merge_resolved",
+            metadata: {
+                path: pathArg,
+                reason: result.strategy,
+            },
+        });
+        return { exitCode: 0 };
+    }
+    catch (e) {
+        return handleDriverError(e, {
+            oursP,
+            oursRaw,
+            theirsRaw,
+            pathArg,
+            auditLog,
+        });
+    }
+}
+function handleDriverError(e, params) {
+    const { oursP, oursRaw, theirsRaw, pathArg, auditLog } = params;
+    const msg = e instanceof Error ? e.message : String(e);
+    const wrapped = `<<<<<<< ours\n${oursRaw}\n=======\n${theirsRaw}\n>>>>>>> theirs\n`;
+    writeFileSync(oursP, wrapped, "utf8");
+    auditLog?.append({
+        actor: "system",
+        action: "merge_conflict_escalated",
+        metadata: { path: pathArg, reason: `driver-error: ${msg}` },
+    });
+    return { exitCode: 1, stderr: `co-engram-merge-driver: ${msg}` };
+}
+// Entry point (CJS-compatible after esbuild bundle).
+if (isMain) {
+    runDriver(process.argv).then(({ exitCode }) => {
+        process.exitCode = exitCode;
+    });
+}
+// Re-export for introspection by the bundle
+export { DRIVER_BUNDLE_VERSION };
+//# sourceMappingURL=driver-main.js.map

package/dist/merge/driver-main.js.map

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

package/dist/merge/evidence-union.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Evidence union algorithm (spec §6.2).
+ *
+ * Evidence is append-only — both sides' additions should be preserved.
+ *
+ * Dedupe key: `${description}::${addedBy}`. When the same person adds the
+ * same description multiple times, keep the entry with the latest addedAt.
+ *
+ * Contradictory evidence ("because X" vs "because not X") produces
+ * DIFFERENT keys, so both are preserved — caller (LLM arbiter) decides.
+ *
+ * @module @co-engram/core/merge
+ */
+import type { SynapseEvidence } from "../types/synapse.js";
+/**
+ * Compute the dedupe key for an evidence entry.
+ *
+ * Spec §6.4 edge case: if addedBy is missing (legacy data), the key
+ * degenerates to `${description}::` so we still dedupe by description alone.
+ */
+export declare function evidenceKey(e: SynapseEvidence): string;
+/**
+ * Merge three evidence arrays via spec §6.2 union algorithm:
+ *
+ *   1. Compute oursAdded = diffByDescAndAuthor(ours, base)
+ *   2. Compute theirsAdded = diffByDescAndAuthor(theirs, base)
+ *   3. all = [...base, ...oursAdded, ...theirsAdded]
+ *   4. dedupe: same key → keep latest addedAt
+ */
+export declare function mergeEvidence(params: {
+    base: readonly SynapseEvidence[];
+    ours: readonly SynapseEvidence[];
+    theirs: readonly SynapseEvidence[];
+}): SynapseEvidence[];
+//# sourceMappingURL=evidence-union.d.ts.map

package/dist/merge/evidence-union.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-union.d.ts","sourceRoot":"","sources":["../../src/merge/evidence-union.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CAEtD;AAsCD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,IAAI,EAAE,SAAS,eAAe,EAAE,CAAC;IACjC,IAAI,EAAE,SAAS,eAAe,EAAE,CAAC;IACjC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;CACpC,GAAG,eAAe,EAAE,CA2BpB"}

package/dist/merge/evidence-union.js

@@ -0,0 +1,88 @@
+/**
+ * Evidence union algorithm (spec §6.2).
+ *
+ * Evidence is append-only — both sides' additions should be preserved.
+ *
+ * Dedupe key: `${description}::${addedBy}`. When the same person adds the
+ * same description multiple times, keep the entry with the latest addedAt.
+ *
+ * Contradictory evidence ("because X" vs "because not X") produces
+ * DIFFERENT keys, so both are preserved — caller (LLM arbiter) decides.
+ *
+ * @module @co-engram/core/merge
+ */
+/**
+ * Compute the dedupe key for an evidence entry.
+ *
+ * Spec §6.4 edge case: if addedBy is missing (legacy data), the key
+ * degenerates to `${description}::` so we still dedupe by description alone.
+ */
+export function evidenceKey(e) {
+    return `${e.description}::${e.addedBy ?? ""}`;
+}
+/**
+ * Diff `next` against `prev` by evidence key, returning only entries
+ * that are new (not present in prev, or present but with older addedAt).
+ */
+function diffByDescAndAuthor(next, prev) {
+    const prevMap = new Map();
+    for (const e of prev)
+        prevMap.set(evidenceKey(e), e);
+    const added = [];
+    for (const e of next) {
+        const existing = prevMap.get(evidenceKey(e));
+        if (!existing) {
+            added.push(e);
+        }
+        else if ((e.addedAt ?? "") > (existing.addedAt ?? "") &&
+            // Don't emit if value is otherwise identical (avoid no-op writes)
+            !evidenceEqual(e, existing)) {
+            added.push(e);
+        }
+    }
+    return added;
+}
+function evidenceEqual(a, b) {
+    return (a.description === b.description &&
+        a.addedBy === b.addedBy &&
+        a.addedAt === b.addedAt &&
+        a.source === b.source &&
+        a.confidence === b.confidence);
+}
+/**
+ * Merge three evidence arrays via spec §6.2 union algorithm:
+ *
+ *   1. Compute oursAdded = diffByDescAndAuthor(ours, base)
+ *   2. Compute theirsAdded = diffByDescAndAuthor(theirs, base)
+ *   3. all = [...base, ...oursAdded, ...theirsAdded]
+ *   4. dedupe: same key → keep latest addedAt
+ */
+export function mergeEvidence(params) {
+    const { base, ours, theirs } = params;
+    const oursAdded = diffByDescAndAuthor(ours, base);
+    const theirsAdded = diffByDescAndAuthor(theirs, base);
+    const all = [...base, ...oursAdded, ...theirsAdded];
+    const byKey = new Map();
+    for (const e of all) {
+        const key = evidenceKey(e);
+        const existing = byKey.get(key);
+        if (!existing) {
+            byKey.set(key, e);
+            continue;
+        }
+        // Same key → keep entry with newer addedAt (or first-seen if tie)
+        if ((e.addedAt ?? "") > (existing.addedAt ?? "")) {
+            byKey.set(key, e);
+        }
+    }
+    // Sort for stable output: by addedAt ascending, then description, then key.
+    // This decouples result order from input order (spec §6.4 — field-order
+    // differences between serializers must not produce false conflicts).
+    return Array.from(byKey.values()).sort((a, b) => {
+        const byTime = (a.addedAt ?? "").localeCompare(b.addedAt ?? "");
+        if (byTime !== 0)
+            return byTime;
+        return evidenceKey(a).localeCompare(evidenceKey(b));
+    });
+}
+//# sourceMappingURL=evidence-union.js.map

package/dist/merge/evidence-union.js.map

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

package/dist/merge/frontmatter-rules.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Frontmatter 字段分类 + 单字段合并规则
+ *
+ * 字段语义分类见 spec §4.2。每种分类有独立的合并规则。
+ * updatedAt_arbitrated 字段不在此处处理(由 arbitration.ts 接管)。
+ *
+ * @module @co-engram/core/merge
+ */
+export type FieldClass = "immutable" | "additive" | "max" | "updatedAt_arbitrated" | "recomputed" | "legacy_derived";
+export declare function classifyField(fieldName: string): FieldClass;
+export interface SimpleMergeResult {
+    readonly value: unknown;
+    readonly changed: boolean;
+}
+export declare class ImmutableViolationError extends Error {
+    readonly fieldName: string;
+    readonly base: unknown;
+    readonly ours: unknown;
+    readonly theirs: unknown;
+    constructor(fieldName: string, base: unknown, ours: unknown, theirs: unknown);
+}
+export declare function mergeImmutableField(params: {
+    base: unknown;
+    ours: unknown;
+    theirs: unknown;
+    fieldName: string;
+}): SimpleMergeResult;
+export declare function mergeAdditiveField(params: {
+    base: number | undefined;
+    ours: number | undefined;
+    theirs: number | undefined;
+}): SimpleMergeResult;
+export declare function mergeMaxField(params: {
+    base: number | string;
+    ours: number | string;
+    theirs: number | string;
+}): SimpleMergeResult;
+//# sourceMappingURL=frontmatter-rules.d.ts.map

package/dist/merge/frontmatter-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter-rules.d.ts","sourceRoot":"","sources":["../../src/merge/frontmatter-rules.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,UAAU,GAClB,WAAW,GACX,UAAU,GACV,KAAK,GACL,sBAAsB,GACtB,YAAY,GACZ,gBAAgB,CAAC;AAuBrB,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,CAO3D;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,qBAAa,uBAAwB,SAAQ,KAAK;aAE9B,SAAS,EAAE,MAAM;aACjB,IAAI,EAAE,OAAO;aACb,IAAI,EAAE,OAAO;aACb,MAAM,EAAE,OAAO;gBAHf,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,OAAO;CAOlC;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,iBAAiB,CAMpB;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B,GAAG,iBAAiB,CAOpB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB,GAAG,iBAAiB,CAKpB"}