dorfl 0.0.0 → 0.1.0

package/dist/format.js

@@ -0,0 +1,256 @@
+import { formatDuplicateWarnings } from './ledger-lint.js';
+import { categoriseItems, summariseGroups, CATEGORY_ORDER, CATEGORY_LABELS, } from './categorise.js';
+/**
+ * Human label for the two autonomy axes. `humanOnly` is reported first when both
+ * are set, so the REASON an agent is gated is always visible and distinct from
+ * `needsAnswers`.
+ */
+export function gateLabel(humanOnly, needsAnswers) {
+    if (humanOnly === true) {
+        return 'human-only';
+    }
+    if (needsAnswers === true) {
+        return 'needs-answers';
+    }
+    return 'undeclared';
+}
+/** A short description of the `blockedBy` readiness for one item. */
+function readinessLabel(item) {
+    if (item.blockedBy.length === 0) {
+        return 'deps: satisfied (none)';
+    }
+    if (item.eligibility.blockedBy.satisfied) {
+        return `deps: satisfied (${item.blockedBy.join(', ')})`;
+    }
+    return `deps: waiting on ${item.eligibility.blockedBy.missing.join(', ')}`;
+}
+/** Ready items get a filled marker, blocked ones an open one. */
+function readinessMarker(entry) {
+    return entry.ready ? '*' : 'o';
+}
+function formatItem(entry) {
+    return `      ${readinessMarker(entry)} ${entry.item.slug}   ${readinessLabel(entry.item)}`;
+}
+/** Render one repo's three labelled groups; empty groups show `(none)`. */
+function formatRepo(path, groups) {
+    const lines = [];
+    lines.push(`  ${path}`);
+    lines.push('');
+    for (const category of CATEGORY_ORDER) {
+        lines.push(`    ${CATEGORY_LABELS[category]}:`);
+        const entries = groups[category];
+        if (entries.length === 0) {
+            lines.push('      (none)');
+        }
+        else {
+            for (const entry of entries) {
+                lines.push(formatItem(entry));
+            }
+        }
+    }
+    lines.push('');
+    return lines;
+}
+function pluralRepos(n) {
+    return n === 1 ? 'repo' : 'repos';
+}
+function pluralItems(n) {
+    return n === 1 ? 'item' : 'items';
+}
+/**
+ * The divergence-vs-arbiter line for the cwd-local section, using the
+ * `main-divergence-guard` framing: local `main` AHEAD of `<arbiter>/main` means
+ * UNPUSHED commits (the local working tree is more authoritative than the
+ * arbiter for those); BEHIND means the arbiter has commits the local tree lacks.
+ * When the fetch failed it says so (the divergence reflects last-known).
+ */
+function cwdDivergenceLine(arbiter) {
+    const freshness = arbiter.fetched
+        ? 'fetched just now'
+        : 'FETCH FAILED — last-known (offline)';
+    const { ahead, behind, remote } = arbiter;
+    if (ahead === 0 && behind === 0) {
+        return `      in sync with ${remote}/main (${freshness}).`;
+    }
+    const parts = [];
+    if (ahead > 0) {
+        parts.push(`${ahead} commit${ahead === 1 ? '' : 's'} ahead (unpushed)`);
+    }
+    if (behind > 0) {
+        parts.push(`${behind} commit${behind === 1 ? '' : 's'} behind`);
+    }
+    return `      local main is ${parts.join(', ')} vs ${remote}/main (${freshness}).`;
+}
+/**
+ * Render the CWD-LOCAL section of `scan`/`status` (the `scan-status-read-cwd-repo`
+ * task): a DISTINCT, separately-counted block for the CURRENT repo, read from
+ * the LOCAL WORKING TREE (NOT the registry's bare mirror ref). Returns `[]` when
+ * the cwd does NOT participate (no local section). The section LABELS its source
+ * + freshness, shows the divergence-vs-arbiter (`main-divergence-guard` framing),
+ * and — when the cwd participates but is NOT registered — teaches
+ * self-registration instead of the dead-end "No participating repos found".
+ *
+ * The counts here are the cwd's OWN (never merged into the registry total — the
+ * consistency rule): the two reads have different freshness + storage models.
+ */
+/**
+ * Render ONE held per-item lock entry (action × state + reason/questions) as
+ * indented lines, the SHARED renderer for the in-flight lock surface on BOTH the
+ * registry view (`formatStatus`) and the cwd section (`formatCwdSection`), so the
+ * two substrates present a held/stuck item identically (NOT a forked renderer). An
+ * `active` hold reads as `in-progress`; a `stuck` hold as `needs-attention` and
+ * carries its (possibly multi-line) reason + any surfaced questions.
+ */
+export function formatLockEntryLines(entry, indent) {
+    const lines = [];
+    const view = entry.state === 'stuck' ? 'needs-attention' : 'in-progress';
+    lines.push(`${indent}${entry.entry}   (${entry.action}/${entry.state} = ${view})`);
+    if (entry.state === 'stuck') {
+        const reason = entry.reason && entry.reason !== ''
+            ? entry.reason
+            : '(no reason recorded)';
+        const reasonLines = reason.split('\n');
+        lines.push(`${indent}  reason: ${reasonLines[0]}`);
+        for (const extra of reasonLines.slice(1)) {
+            lines.push(`${indent}    ${extra}`);
+        }
+        if (entry.questions && entry.questions.length > 0) {
+            lines.push(`${indent}  questions:`);
+            for (const q of entry.questions) {
+                lines.push(`${indent}    - ${q}`);
+            }
+        }
+    }
+    return lines;
+}
+export function formatCwdSection(section) {
+    if (!section.participating || section.repo === undefined) {
+        return [];
+    }
+    const lines = [];
+    const dedup = section.alsoRegistered === true ? ' (also registered)' : '';
+    lines.push('This repo (local working tree):');
+    lines.push(`  ${section.path}${dedup}`);
+    lines.push('  source: local working tree (may be ahead of / behind the arbiter) — ' +
+        'distinct from the registry view below (arbiter main, fetched).');
+    // Fetch-first divergence-vs-arbiter (or a no-arbiter note).
+    if (section.arbiter !== undefined) {
+        lines.push(cwdDivergenceLine(section.arbiter));
+    }
+    else {
+        lines.push('      no arbiter remote configured — divergence vs arbiter unknown.');
+    }
+    const total = section.totalItems ?? 0;
+    // Self-registration hint when the cwd participates but is NOT registered.
+    if (section.alsoRegistered !== true) {
+        lines.push('');
+        lines.push(`  This repo participates (${total} backlog ${pluralItems(total)}) but is ` +
+            'NOT registered — `run`/`scan` across machines won’t see it until ' +
+            '`dorfl remote add . --local` (or `remote add <its-url>`).');
+    }
+    // The cwd's grouped backlog — the SAME who-can-take-it grouping the registry
+    // view uses, but read from the working tree and counted SEPARATELY.
+    const groups = categoriseItems(section.repo.items);
+    lines.push('');
+    for (const category of CATEGORY_ORDER) {
+        lines.push(`    ${CATEGORY_LABELS[category]}:`);
+        const entries = groups[category];
+        if (entries.length === 0) {
+            lines.push('      (none)');
+        }
+        else {
+            for (const entry of entries) {
+                lines.push(formatItem(entry));
+            }
+        }
+    }
+    // The PER-ITEM LOCK in-flight SURFACE for the cwd (prd
+    // `ledger-status-per-item-lock-refs` US #8): held (`active` = in-progress) and
+    // `stuck` (= needs-attention) lock entries + their reasons. This is what keeps a
+    // held/stuck cwd item from vanishing: the held-slug subtraction removes it from
+    // the buckets above, so without THIS block it would be invisible (the regression
+    // this fixes). Symmetric with the registry view's `In-flight locks` block (same
+    // `refs/dorfl/lock/*` source, same primitive); rendered HERE inside the cwd
+    // section so it stays the cwd's OWN, separately-counted surface. Empty ⇒ no
+    // block (a calm repo adds no lines).
+    const lockHeld = section.repo.lockHeld ?? [];
+    if (lockHeld.length > 0) {
+        lines.push('');
+        lines.push('    In progress / stuck (lock held — refs/dorfl/lock/*):');
+        for (const entry of lockHeld) {
+            lines.push(...formatLockEntryLines(entry, '      '));
+        }
+    }
+    lines.push('');
+    lines.push(`  Local total: ${total} ${pluralItems(total)} ` +
+        `(${section.totalEligible ?? 0} eligible) — this repo only, NOT merged with ` +
+        'the registry total below.');
+    return lines;
+}
+/**
+ * Render the cross-repo queue as a human decision dashboard: under each repo,
+ * every backlog item is grouped by who-can-take-it (Agent-claimable now /
+ * Human-only / Blocked), with empty groups shown as `(none)`. Within a group,
+ * ready (deps-satisfied) items sort above blocked ones.
+ *
+ * The set of groups shown is INDEPENDENT of `autoBuild`; only the eligibility
+ * *verdict* line reflects the policy (`report.totalEligible` counts an
+ * agent-claimable item only when `autoBuild` is on).
+ */
+export function formatReport(report, cwd) {
+    const lines = [];
+    // The cwd-local section (the `scan-status-read-cwd-repo` task): a DISTINCT,
+    // separately-counted block for the CURRENT repo, ABOVE the registry view.
+    const cwdLines = cwd !== undefined ? formatCwdSection(cwd) : [];
+    if (cwdLines.length > 0) {
+        lines.push(...cwdLines);
+        lines.push('');
+    }
+    // De-dup: when the cwd is ALSO registered, drop its registry row (shown once,
+    // above, marked "(also registered)") so the same repo never appears twice.
+    const registryRepos = cwd?.alsoRegistered === true && cwd.registeredMirrorPath !== undefined
+        ? report.repos.filter((r) => r.path !== cwd.registeredMirrorPath)
+        : report.repos;
+    if (registryRepos.length === 0) {
+        // If the cwd participates we already rendered its local section above (no
+        // dead-end). Otherwise keep the existing empty-state.
+        if (cwdLines.length === 0) {
+            lines.push('No participating repos found.');
+            lines.push('(A repo participates iff its work/ tree has lifecycle content in any ' +
+                'pool: tasks/ready, tasks/backlog, prds/proposed, prds/ready, ' +
+                'notes/observations, or questions.)');
+        }
+        else {
+            lines.push('Registered repos: (none) — nothing registered in the registry yet.');
+        }
+        return lines.join('\n').replace(/\n+$/, '');
+    }
+    lines.push('Registered repos (registry — arbiter main, fetched):');
+    lines.push('');
+    const allGroups = [];
+    for (const repo of registryRepos) {
+        const groups = categoriseItems(repo.items);
+        allGroups.push(groups);
+        lines.push(...formatRepo(repo.path, groups));
+        // The one-slug-one-folder LINT (prd `ledger-integrity` story 3): WARN LOUDLY
+        // when any slug in this repo's ledger resides in >1 status folder (a corrupt
+        // ledger — never a silent pass). Clean ledgers add no lines.
+        const warnings = formatDuplicateWarnings(repo.ledgerDuplicates ?? []);
+        if (warnings.length > 0) {
+            lines.push(...warnings.map((w) => `  ${w}`));
+            lines.push('');
+        }
+    }
+    const s = summariseGroups(allGroups);
+    const repoCount = registryRepos.length;
+    const registryItems = registryRepos.reduce((n, r) => n + r.items.length, 0);
+    const registryEligible = registryRepos.reduce((n, r) => n + r.items.filter((i) => i.eligibility.eligible).length, 0);
+    lines.push(`Registry summary: ${registryItems} item(s) across ${repoCount} ${pluralRepos(repoCount)} — ` +
+        `${s.agentClaimable} agent-claimable, ${s.humanOnly} human-only, ` +
+        `${s.needsAnswers} needs-answers, ${s.blocked} blocked ` +
+        `(${s.ready} ready).`);
+    lines.push(`Runner verdict: ${registryEligible}/${registryItems} item(s) eligible now ` +
+        `(under the current --auto-build policy).`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=format.js.map

package/dist/format.js.map

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

package/dist/frontmatter.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Minimal, dependency-free parser for the small subset of YAML frontmatter the
+ * `work/` contract uses: top-level scalar keys and string lists (inline `[a, b]`
+ * or block `- a` form). It deliberately does NOT implement general YAML — only
+ * what `work/` task frontmatter needs (slug, humanOnly, blockedBy, ...).
+ */
+/**
+ * **Origin-trust PROVENANCE** (task `untrusted-origin-forces-build-propose`).
+ * How a prd/task was BORN and the AUTHOR-TRUST verdict at birth, stamped so the
+ * signal SURVIVES the prd/task merge boundary (a landed-on-`main` artifact would
+ * otherwise erase how it was created — the laundering gap).
+ *
+ * - `origin` — `human` (the default / unset: a human authored it locally; a local
+ *   intake with no `--origin-trust` is ALSO this) | `issue` (the CI intake
+ *   front-door stamped it from a public issue).
+ * - `originTrust` — `trusted` | `untrusted`, the `author_association` verdict at
+ *   birth (only meaningful when `origin: issue`). UNSET ⇒ `trusted` (the normal
+ *   human path; ZERO behaviour change). `untrusted` forces the task's BUILD
+ *   transition to `propose` so a human reviews the becomes-code change (an
+ *   explicit `--merge` still overrides — the operator is present).
+ *
+ * `intake.ts` does NOT resolve the trust verdict itself (the `intake.ts` ~L296
+ * boundary: trust is CI's POLICY); the CI shell passes it IN via `--origin-trust`.
+ */
+export type Origin = 'human' | 'issue';
+export type OriginTrust = 'trusted' | 'untrusted';
+export interface Frontmatter {
+    /**
+     * How the artifact was BORN (`human`|`issue`). `undefined` when omitted
+     * (⇒ `human`/trusted: the normal local-author path, no behaviour change).
+     * Stamped `issue` by the CI intake front-door so the becomes-code checkpoint is
+     * not laundered at the merge boundary.
+     */
+    origin: Origin | undefined;
+    /**
+     * The author-trust verdict at birth (`trusted`|`untrusted`); only meaningful
+     * when `origin: issue`. `undefined` when omitted (⇒ `trusted`: the normal path,
+     * zero behaviour change). An `untrusted` task forces its BUILD transition to
+     * `propose` (overridable by an explicit `--merge`).
+     */
+    originTrust: OriginTrust | undefined;
+    /** Content-derived slug id (frontmatter `slug:`). */
+    slug: string | undefined;
+    /**
+     * Source SPEC slug (frontmatter `spec:`); the spec lives at
+     * `work/specs/ready/<spec>.md`. The `spec` vocabulary name for the parent-spec
+     * pointer (prd `prd-to-spec-vocabulary-cutover-and-migration-command`). This is
+     * the EXPAND-step ADDITION beside {@link prd}: `parseFrontmatter` populates BOTH
+     * from EITHER the `spec:` OR the `prd:` key with the SAME value, so a caller
+     * reading either sees the parent-spec slug. The migrate batches move `fm.prd`
+     * reads onto `fm.spec` one at a time; the contract task removes `prd`.
+     */
+    spec: string | undefined;
+    /**
+     * Source spec slug (frontmatter `prd:`); the spec lives at
+     * `work/specs/ready/<prd>.md`. The LEGACY vocabulary name for the parent-spec
+     * pointer, kept BESIDE {@link spec} through the expand→migrate→contract cutover
+     * (prd `prd-to-spec-vocabulary-cutover-and-migration-command`) so every existing
+     * `fm.prd` reader keeps working; populated from EITHER the `spec:` or `prd:` key.
+     */
+    prd: string | undefined;
+    /**
+     * The GitHub issue number an `intake`-emitted artifact was transformed from
+     * (frontmatter `issue:`). Parsed so the `issue: N` intake writes is
+     * MACHINE-READABLE — the close JOB (`runner-in-ci`'s) reaches it to resolve the
+     * issue from folder + field state. Carried on EITHER:
+     *
+     * - a **prd** (`intake`'s prd outcome) — a fanned task reaches it via
+     *   `task.prd: → work/prds/ready/<prd>.md → prd issue:` (the number lives
+     *   ONLY on the prd, never duplicated across the N fanned tasks); OR
+     * - a **lone task** (`intake`'s TASK outcome, no `prd:`) — the provider-agnostic
+     *   closure link for a task that closes its own issue directly (replaces the old
+     *   GitHub-only `Fixes #N` body line, which is now a deferred optimisation).
+     *
+     * INVARIANT — one closure path per task: a task uses `issue:` XOR `prd:`, never
+     * both. Either it closes its own issue directly (`issue:`) or it contributes to a
+     * prd that closes the issue (`prd:` → prd `issue:`). This is NOT enforced by a
+     * throwing validator (there is no frontmatter-validation layer): intake never
+     * emits both — its task / prd dispatch branches are mutually exclusive — so only
+     * a human hand-edit could produce both, and the precedence rule (`prd:` wins,
+     * `issue:` ignored) is the future close-job's concern (see {@link
+     * resolveClosingIssue}), degrading a typo to "use the prd's number" rather than
+     * crashing. `undefined` when omitted (every non-intake prd and most tasks).
+     */
+    issue: number | undefined;
+    /**
+     * Autonomy gate axis 1 (DECIDED). `true` when the item declares itself
+     * human-only (a human must drive it regardless of how complete the spec is);
+     * `undefined` when omitted (undeclared — most items). Present on both tasks
+     * and prds.
+     */
+    humanOnly: boolean | undefined;
+    /**
+     * Autonomy gate axis 2 (DISCOVERED). `true` when the item has unresolved
+     * questions blocking autonomous progress (the open questions live in the body);
+     * `undefined` when omitted. Orthogonal to `humanOnly`; present on both tasks
+     * and prds.
+     */
+    needsAnswers: boolean | undefined;
+    /**
+     * The triage SETTLED marker (US #30). A non-empty `triaged:` value (e.g.
+     * `keep` / `duplicate`) means a human (or the conservative auto-disposition)
+     * has SETTLED this observation, so it DROPS OUT of the triage candidate pool
+     * and is never re-asked. `undefined` when omitted (an UNTRIAGED observation,
+     * still in the pool). Carried so the lifecycle-pool enumeration
+     * (`advance-autopick-lifecycle-pools`) can exclude settled observations from
+     * the triage selection.
+     */
+    triaged: string | undefined;
+    /** Slugs this item is blocked by; `[]` when omitted or empty. */
+    blockedBy: string[];
+    /**
+     * Prd-only: slugs of prds that must already be TASKED before this prd may be
+     * tasked (resolved against `work/prds/tasked/` residence, NOT `done/`). `[]` when
+     * omitted or empty. Parsed here so the auto-tasker can read it; enforcement
+     * lives in the `auto-slice` capability, not in eligibility.
+     */
+    taskedAfter: string[];
+    /**
+     * The per-item override layer for the `promptGuidance` NUDGE namespace
+     * (task `prompt-guidance-testfirst-item-override`, prd US #5). A task or
+     * prd may carry one or more `promptGuidance.<member>: true | false`
+     * frontmatter lines to OVERRIDE the resolved repo policy for THAT ITEM only.
+     * Each member is `undefined` when omitted (⇒ inherit the next layer down in
+     * the precedence chain: per-task > per-prd > repo-resolved). The override
+     * is honoured at the prompt-assembly seam (`prompt.ts`); it never affects
+     * the `verify` gate.
+     *
+     * Parsed from the DOTTED scalar form `promptGuidance.testFirst: true`
+     * (single-line, mirroring the flat shape `humanOnly`/`needsAnswers` use at the
+     * item level). A mistyped value (e.g. `"yes"`) reads as `undefined`, the same
+     * silent-on-malformed behaviour the existing `humanOnly` parsing has — no
+     * silent coerce to true/false.
+     */
+    promptGuidance: {
+        testFirst: boolean | undefined;
+    };
+}
+/**
+ * Set (or clear) the top-level `needsAnswers:` frontmatter marker on a `work/`
+ * markdown document, returning the new content. Used by the tasker review→edit
+ * LOOP's verdict sink (`slicer-review-edit-loop`) to emit a specific uncertain
+ * candidate task as `needsAnswers: true` (open questions block autonomous build;
+ * a human must answer them). If a `needsAnswers:` line already exists it is
+ * REPLACED (idempotent); otherwise it is appended as the last line inside the
+ * frontmatter fence. A document with NO frontmatter fence gets one PREPENDED (see
+ * {@link setFrontmatterMarker}) — observations are born fence-less (the
+ * `capture-signal` skill writes prose), so the tooling-owned `needsAnswers` axis
+ * MUST be settable on them rather than silently dropped.
+ */
+export declare function setNeedsAnswersMarker(content: string, value: boolean): string;
+/**
+ * Set (or replace) a top-level scalar `<key>: <value>` frontmatter marker on a
+ * `work/` markdown document, returning the new content. The generalised form of
+ * {@link setNeedsAnswersMarker} the advance APPLY rung uses to stamp a
+ * `triaged: keep` marker (US #30) on an item a human answered "keep" — so a
+ * settled observation drops out of the candidate pool and is never re-asked. If a
+ * `<key>:` line already exists it is REPLACED (idempotent); otherwise it is
+ * appended as the last line inside the frontmatter fence.
+ *
+ * A document with NO frontmatter fence gets ONE PREPENDED carrying just this
+ * marker (`---\n<key>: <value>\n---\n\n<body>`). This is the load-bearing fix for
+ * `sidecar-without-needsAnswers`: observations are routinely created fence-less
+ * (the `capture-signal` skill writes free-form prose), and the OLD behaviour
+ * silently returned the body UNCHANGED — so `persistSurfacedQuestions` wrote the
+ * sidecar while the `needsAnswers:true` flag it believed it set was discarded,
+ * tearing the `needsAnswers ⟺ active sidecar` invariant a later tick refused to
+ * classify. These markers (`needsAnswers`, `triaged`) are tooling-owned axes, not
+ * prose, so the tool is entitled to introduce the fence it needs.
+ *
+ * The ONE remaining return-unchanged case is a MALFORMED doc that opens a fence
+ * (`---\n`) but never closes it: rewriting that risks corrupting hand-authored
+ * content, so it is left untouched (a degenerate input no writer produces).
+ */
+export declare function setFrontmatterMarker(content: string, key: string, value: string): string;
+/**
+ * PROPAGATE the origin-trust PROVENANCE (`origin` + `originTrust`) from a SOURCE
+ * artifact (a prd) onto a TARGET artifact's content (an emitted task), returning
+ * the new content (task `untrusted-origin-forces-build-propose`). The tasker
+ * calls this so a task born from an untrusted-origin prd carries the stamp the
+ * BUILD transition reads. IDEMPOTENT: each present source field is written via
+ * {@link setFrontmatterMarker} (replace-or-append). When the source has NO `origin`
+ * (a human/local-authored prd ⇒ trusted), the target is returned UNCHANGED — the
+ * normal path is never stamped (zero behaviour change). When a stamp IS applied to
+ * a fence-less target, {@link setFrontmatterMarker} now prepends a fence to carry
+ * it (tasks the tasker emits always have a fence, so this is the defensive path).
+ */
+export declare function propagateOrigin(source: Pick<Frontmatter, 'origin' | 'originTrust'>, targetContent: string): string;
+export declare function parseFrontmatter(content: string): Frontmatter;
+/**
+ * Resolve, from a parsed artifact's frontmatter, HOW it closes its source issue:
+ * the `prd:` hop or the lone-task `issue:` field. A PURE helper for the FUTURE
+ * CI close-job (`runner-in-ci`'s) — it is NOT wired into intake or any reader
+ * today; it merely pins the one-closure-path PRECEDENCE in one place.
+ *
+ * Encodes the invariant: a task uses `issue:` XOR `prd:`. When (only a human
+ * hand-edit could) BOTH are present, `prd:` WINS — the close-job hops to the prd's
+ * `issue:` and IGNORES the task's own `issue:` (the fanned-prd path is the
+ * authoritative one; a lone `issue:` on a `prd:`-bearing task is a contradiction
+ * that degrades to "use the prd" rather than crashing).
+ *
+ * Returns:
+ * - `{via: 'spec', spec}` when a `spec:` is present (hop to the spec's `issue:`; the
+ *   caller resolves the spec file to read its number);
+ * - `{via: 'issue', issue}` when only a lone-task `issue:` is present;
+ * - `undefined` when neither is present (no closure path).
+ */
+export declare function resolveClosingIssue(frontmatter: Pick<Frontmatter, 'spec' | 'issue'>): {
+    via: 'spec';
+    spec: string;
+} | {
+    via: 'issue';
+    issue: number;
+} | undefined;
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AACvC,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,WAAW,CAAC;AAElD,MAAM,WAAW,WAAW;IAC3B;;;;;OAKG;IACH,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B;;;;;OAKG;IACH,WAAW,EAAE,WAAW,GAAG,SAAS,CAAC;IACrC,qDAAqD;IACrD,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB;;;;;;;;OAQG;IACH,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB;;;;;;OAMG;IACH,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B;;;;;OAKG;IACH,SAAS,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/B;;;;;OAKG;IACH,YAAY,EAAE,OAAO,GAAG,SAAS,CAAC;IAClC;;;;;;;;OAQG;IACH,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,iEAAiE;IACjE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB;;;;;OAKG;IACH,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;;;;;;;;;;;OAeG;IACH,cAAc,EAAE;QAAC,SAAS,EAAE,OAAO,GAAG,SAAS,CAAA;KAAC,CAAC;CACjD;AA6FD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAE7E;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GACX,MAAM,CAyBR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC9B,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,QAAQ,GAAG,aAAa,CAAC,EACnD,aAAa,EAAE,MAAM,GACnB,MAAM,CAYR;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CA6H7D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAClC,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,GAC9C;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAAG;IAAC,GAAG,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,GAAG,SAAS,CAQzE"}