//! `parser` — read and write db.md markdown files.
//!
//! Parses the YAML frontmatter block, the markdown body, wiki-links, standard
//! markdown links, `##` sections, and the structured sections of the `DB.md`
//! config file. Also the atomic writer that round-trips a file while
//! preserving the operator-edited body verbatim and emitting frontmatter in
//! canonical key order.
//!
//! Strict on required fields, lenient on unknowns: any frontmatter key the
//! spec doesn't recognize is preserved in [`Frontmatter::extra`] as ambient
//! context and round-tripped untouched.
use std::collections::BTreeMap;
use std::path::{Path, PathBuf};
use chrono::{DateTime, FixedOffset};
use serde_norway::{Mapping, Value};
/// The two canonical layer folder names. A path is "content" / a wiki-link is
/// "full-path" only when it resolves under one of these.
const LAYER_DIRS: [&str; 2] = ["sources", "records"];
/// Errors produced while parsing a markdown file or the `DB.md` config.
#[derive(Debug, thiserror::Error)]
pub enum ParseError {
/// The frontmatter block was not valid YAML. Maps to validate code
/// `FM_MALFORMED_YAML`.
#[error("malformed YAML frontmatter in {file}: {source}")]
MalformedYaml {
/// The file whose frontmatter failed to parse.
file: PathBuf,
/// The underlying YAML error.
source: serde_norway::Error,
},
/// The file has no `---`-delimited frontmatter block at its very start.
#[error("missing frontmatter block in {file}")]
MissingFrontmatter {
/// The offending file.
file: PathBuf,
},
/// A required field was absent. Maps to validate code `FM_MISSING_TYPE`
/// (for `type`) and the per-type required-field codes.
#[error("missing required field '{key}' in {file}")]
MissingField {
/// The file missing the field.
file: PathBuf,
/// The required key.
key: String,
},
/// A timestamp field was not ISO-8601 / RFC3339. Maps to `FM_BAD_TIMESTAMP`.
#[error("bad timestamp in field '{key}' of {file}: {value}")]
BadTimestamp {
/// The file.
file: PathBuf,
/// The frontmatter key.
key: String,
/// The unparseable value.
value: String,
},
/// An I/O error reading the file.
#[error(transparent)]
Io(#[from] std::io::Error),
}
/// The parsed YAML frontmatter of a db.md file.
///
/// The universal-contract fields are typed accessors; everything else lands in
/// [`extra`](Frontmatter::extra) as ambient context (unknown-field passthrough)
/// and is round-tripped verbatim. The atomic writer re-emits keys in canonical
/// order: `type`, `id`, `created`, `updated`, `summary` first, then
/// type-specific fields, then `status` / `tags`.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct Frontmatter {
/// `type` — required on content files; the primary query key.
pub type_: Option<String>,
/// `meta-type` — records-only; the epistemic class `fact`/`operational`/
/// `conclusion`. Absent ⇒ `fact` (the effective default is applied by the
/// index/query layer for record-layer files; sources carry none).
pub meta_type: Option<String>,
/// `id` — optional; derived from the file path when absent.
pub id: Option<String>,
/// `created` — RFC3339; required and auto-set on content-file create.
pub created: Option<DateTime<FixedOffset>>,
/// `updated` — RFC3339; required and auto-maintained on content files.
pub updated: Option<DateTime<FixedOffset>>,
/// `summary` — the one-line catalog line; required on every content file.
pub summary: Option<String>,
/// `status` — optional lifecycle state.
pub status: Option<String>,
/// `tags` — optional flat list of short scalar labels.
pub tags: Vec<String>,
/// All other frontmatter keys (type-specific + custom), preserved verbatim
/// in insertion-stable sorted order. Wiki-link-valued fields keep their raw
/// YAML form here; [`Frontmatter::link_fields`] surfaces them as
/// [`WikiLink`]s.
pub extra: BTreeMap<String, Value>,
}
impl Frontmatter {
/// Parse a YAML frontmatter block (the text between the opening and closing
/// `---` fences, exclusive) into a [`Frontmatter`].
///
/// Lenient on unknown keys (they go to [`extra`](Frontmatter::extra));
/// returns [`ParseError::MalformedYaml`] only on YAML that doesn't parse.
pub fn parse(yaml: &str, file: &Path) -> Result<Self, ParseError> {
// An empty (or whitespace-only) frontmatter block is a valid, empty
// mapping — not a YAML error.
let value: Value = if yaml.trim().is_empty() {
Value::Mapping(Mapping::new())
} else {
serde_norway::from_str(yaml).map_err(|source| ParseError::MalformedYaml {
file: file.to_path_buf(),
source,
})?
};
// Top-level frontmatter must be a mapping. A scalar or sequence at the
// top level is malformed for our purposes; surface it as such.
let map = match value {
Value::Mapping(m) => m,
Value::Null => Mapping::new(),
other => {
// serde_norway::Error has no public constructor, so let the
// deserializer decide: a value that coerces to a Mapping (e.g. a
// YAML-tagged mapping `!tag\n k: v`, where the tag is ambient) is
// accepted as that mapping; a genuine scalar or sequence top
// level fails to coerce and IS the malformed case. (Using a
// match here, not `expect_err`, avoids a panic on the
// tagged-mapping case, which deserializes to a Mapping just
// fine.)
match serde_norway::from_value::<Mapping>(other) {
Ok(m) => m,
Err(source) => {
return Err(ParseError::MalformedYaml {
file: file.to_path_buf(),
source,
});
}
}
}
};
let mut fm = Frontmatter::default();
for (k, v) in map {
let key = match k.as_str() {
Some(s) => s.to_string(),
// Non-string keys (`2026:`, `true:`, `3.14:`) are unusual but
// valid YAML; per SPEC § "Unknown fields pass through" they must
// not be corrupted on re-emit. Stringify them through the YAML
// scalar emitter — `2026`, `true`, `3.14` — NOT the Rust `Debug`
// formatter (which produced `Number(2026)`, `Bool(true)`, …), so
// the key text survives. `extra` is `String`-keyed, so on the
// write side the key re-emits as a quoted-string key carrying that
// text (e.g. `'2026':`) — the type narrows from number to string,
// but the data is no longer destroyed and ordinary string keys are
// wholly unaffected.
None => yaml_scalar_key(&k),
};
match key.as_str() {
// Coerce scalar values rather than `v.as_str()` (which is None
// for Number/Bool/Null). A bare scalar that YAML reads as a
// non-string — `summary: 2026`, `id: 100`, `status: 0` — would
// otherwise be set to None AND dropped (it is a matched arm, so
// the raw value never reaches `extra`), and `to_yaml` then omits
// the None field, so `dbmd format` (read_file -> write_file)
// silently deletes the line from disk. `scalar_string` mirrors
// the coercion `validate`/`store` already apply to these fields,
// so a numeric/bool-looking scalar is preserved as its string
// form and round-trips instead of being destroyed.
//
// A sequence/mapping value on a universal key (`status: [a, b]`,
// a nested-mapping `summary:`) is NOT a valid scalar; rather than
// let the matched arm consume-and-drop it (silent data loss on
// the next re-emit), `scalar_string` returns None and we fall
// through to preserving the raw value in `extra` so `to_yaml`
// re-emits it verbatim. The universal accessors stay None (the
// value was never a valid scalar for that field), but the
// operator's bytes are never destroyed.
"type" => match scalar_string(&v) {
Some(s) => fm.type_ = Some(s),
None => {
fm.extra.insert(key, v);
}
},
"meta-type" => match scalar_string(&v) {
Some(s) => fm.meta_type = Some(s),
None => {
fm.extra.insert(key, v);
}
},
"id" => match scalar_string(&v) {
Some(s) => fm.id = Some(s),
None => {
fm.extra.insert(key, v);
}
},
"created" => fm.created = parse_timestamp(&v, "created", file)?,
"updated" => fm.updated = parse_timestamp(&v, "updated", file)?,
"summary" => match scalar_string(&v) {
Some(s) => fm.summary = Some(s),
None => {
fm.extra.insert(key, v);
}
},
"status" => match scalar_string(&v) {
Some(s) => fm.status = Some(s),
None => {
fm.extra.insert(key, v);
}
},
"tags" => match parse_tags_preserving(&v) {
Ok(tags) => fm.tags = tags,
// A `tags` value with a non-scalar item (`tags: [[vip]]`,
// `tags: [a, [b]]`) is preserved verbatim in `extra` rather
// than silently filtered down / erased on re-emit. The typed
// `tags` vec stays empty (no valid scalar list was present),
// so `to_yaml` won't ALSO emit a `tags:` from the vec.
Err(raw) => {
fm.extra.insert(key, raw);
}
},
_ => {
fm.extra.insert(key, v);
}
}
}
Ok(fm)
}
/// Serialize the frontmatter back to a YAML block (no `---` fences) in
/// canonical key order. Round-trips [`extra`](Frontmatter::extra) verbatim.
pub fn to_yaml(&self) -> String {
// Build an order-preserving mapping in canonical key order:
// type, meta-type, id, created, updated, summary (universal head)
// <type-specific extra, BTreeMap-sorted>
// status, tags (universal tail)
// serde_norway::Mapping preserves insertion order, so one serialize call
// emits the block in exactly this order with correct YAML quoting.
let mut map = Mapping::new();
if let Some(t) = &self.type_ {
map.insert(Value::String("type".into()), Value::String(t.clone()));
}
if let Some(mt) = &self.meta_type {
map.insert(Value::String("meta-type".into()), Value::String(mt.clone()));
}
if let Some(id) = &self.id {
map.insert(Value::String("id".into()), Value::String(id.clone()));
}
if let Some(created) = &self.created {
map.insert(
Value::String("created".into()),
Value::String(created.to_rfc3339()),
);
}
if let Some(updated) = &self.updated {
map.insert(
Value::String("updated".into()),
Value::String(updated.to_rfc3339()),
);
}
if let Some(summary) = &self.summary {
map.insert(
Value::String("summary".into()),
Value::String(summary.clone()),
);
}
// Type-specific + custom fields, in BTreeMap (sorted) order. Each value
// is canonicalized so a wiki-link round-trips to the form the writer and
// `dbmd validate` agree on — critically, the SPEC-canonical *unquoted*
// scalar `field: [[x]]` (which YAML parses to a nested `Seq[Seq[String]]`)
// is re-emitted as a quoted scalar `'[[x]]'` instead of the bracket-less
// block sequence `- - x` that a verbatim re-emit would produce and that
// destroys the link. See [`canonicalize_extra_value`].
for (k, v) in &self.extra {
map.insert(Value::String(k.clone()), canonicalize_extra_value(v));
}
if let Some(status) = &self.status {
map.insert(
Value::String("status".into()),
Value::String(status.clone()),
);
}
if !self.tags.is_empty() {
map.insert(
Value::String("tags".into()),
Value::Sequence(self.tags.iter().cloned().map(Value::String).collect()),
);
}
if map.is_empty() {
return String::new();
}
serde_norway::to_string(&Value::Mapping(map)).unwrap_or_default()
}
/// True if the file is content (under `sources/` or `records/`)
/// and not an `index.md`. Used by validate to decide which files require a
/// `summary`. Meta files (`DB.md`, `index.md`, `log.md`) return false.
pub fn is_content_file(path: &Path) -> bool {
// index.md is a meta file at every level, never content.
if path.file_name().and_then(|n| n.to_str()) == Some("index.md") {
return false;
}
// Content iff some path component is one of the two layer dirs. This
// works for both store-relative (`sources/emails/x.md`) and absolute
// (`/home/db/sources/emails/x.md`) paths. DB.md / log.md sit at the
// root, under no layer, so they fall through to false.
path.components().any(|c| {
c.as_os_str()
.to_str()
.is_some_and(|s| LAYER_DIRS.contains(&s))
})
}
/// Resolve the file's effective `id`: the explicit `id` field if present,
/// otherwise derived from the store-relative path (filename without `.md`).
pub fn effective_id(&self, store_relative_path: &Path) -> String {
if let Some(id) = &self.id {
if !id.is_empty() {
return id.clone();
}
}
// Derived id = filename without the `.md` extension.
store_relative_path
.file_stem()
.and_then(|s| s.to_str())
.unwrap_or_default()
.to_string()
}
/// The effective `meta-type` for a record: the declared value, or `fact`
/// when absent. Records only — sources carry no meta-type; callers apply
/// this only to record-layer files.
pub fn effective_meta_type(&self) -> &str {
self.meta_type.as_deref().unwrap_or("fact")
}
/// Read a single frontmatter key as a raw YAML [`Value`], looking in the
/// typed fields first and then [`extra`](Frontmatter::extra).
pub fn get(&self, key: &str) -> Option<Value> {
match key {
"type" => self.type_.clone().map(Value::String),
"meta-type" => self.meta_type.clone().map(Value::String),
"id" => self.id.clone().map(Value::String),
"created" => self.created.map(|d| Value::String(d.to_rfc3339())),
"updated" => self.updated.map(|d| Value::String(d.to_rfc3339())),
"summary" => self.summary.clone().map(Value::String),
"status" => self.status.clone().map(Value::String),
"tags" => {
if self.tags.is_empty() {
None
} else {
Some(Value::Sequence(
self.tags.iter().cloned().map(Value::String).collect(),
))
}
}
_ => self.extra.get(key).cloned(),
}
}
/// Set a single frontmatter key from a string value, routing universal-
/// contract keys to their typed fields and everything else to
/// [`extra`](Frontmatter::extra). Used by `dbmd fm set`.
pub fn set(&mut self, key: &str, value: &str) -> Result<(), ParseError> {
match key {
"type" => self.type_ = Some(value.to_string()),
"meta-type" => self.meta_type = Some(value.to_string()),
"id" => self.id = Some(value.to_string()),
"created" => {
self.created = Some(parse_rfc3339(value, "created", Path::new("<fm set>"))?)
}
"updated" => {
self.updated = Some(parse_rfc3339(value, "updated", Path::new("<fm set>"))?)
}
"summary" => self.summary = Some(value.to_string()),
"status" => self.status = Some(value.to_string()),
"tags" => {
// Accept either a YAML flow list (`[a, b]`) or a single scalar
// tag. Anything that parses to a sequence becomes the tag list;
// otherwise the whole string is one tag.
self.tags = match serde_norway::from_str::<Value>(value) {
Ok(Value::Sequence(seq)) => parse_tags(&Value::Sequence(seq)),
_ => vec![value.to_string()],
};
}
_ => {
// A custom / type-specific field. The value is a scalar string by
// default, but the spec's list-valued link fields (e.g.
// `meeting.attendees`, SPEC § Linking) must serialize as a YAML
// block sequence of quoted wiki-links — never the flow-form string
// `"[[[a]], [[b]]]"`, which `dbmd validate` rejects as
// `WIKI_LINK_FLOW_FORM_LIST`. When the value parses as a YAML
// sequence whose every item is a clean single wiki-link, store the
// canonical sequence so `to_yaml` emits block form. Everything else
// — plain text, and a single inline `[[x]]` (which YAML reads as a
// nested `Seq[Seq[String]]`, not a list of link strings) — stays a
// verbatim scalar string, preserving the prior behavior.
let stored = parse_link_list_value(value)
.unwrap_or_else(|| Value::String(value.to_string()));
self.extra.insert(key.to_string(), stored);
}
}
Ok(())
}
/// Extract every frontmatter field whose value is a wiki-link (scalar
/// inline form or a block-sequence list), pairing each with its key. The
/// validate engine checks these against `(link)` schema annotations.
pub fn link_fields(&self) -> Vec<(String, WikiLink)> {
let mut out = Vec::new();
// `summary` may carry navigational wiki-links (spec encourages it).
if let Some(summary) = &self.summary {
for link in extract_wiki_links(summary, Path::new("")) {
out.push(("summary".to_string(), link));
}
}
// Every type-specific / custom field: a scalar wiki-link or a list of
// wiki-links, in either the quoted (`"[[x]]"`) or the canonical unquoted
// (`[[x]]`) form. See [`links_in_field_value`] for the YAML shapes.
for (key, value) in &self.extra {
for link in links_in_field_value(value) {
out.push((key.clone(), link));
}
}
out
}
}
/// A wiki-link reference inside the store: `[[target]]` or `[[target|display]]`.
///
/// `target` is always recorded as written; [`is_full_path`](WikiLink::is_full_path)
/// flags whether it's a full store-relative path (the doctrine) versus a
/// short-form (a validation error).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct WikiLink {
/// The link target as written, without the `[[ ]]` and without `|display`.
pub target: String,
/// The optional `|display` text override.
pub display: Option<String>,
/// True when `target` is a full store-relative path (contains a `/` and
/// resolves under a known layer); false for short-form targets like
/// `sarah-chen` — which validate reports as `WIKI_LINK_SHORT_FORM`.
pub is_full_path: bool,
/// True when `target` carries a trailing `.md` extension — validate warns
/// `WIKI_LINK_HAS_EXTENSION`; the canonical writers emit the bare form.
pub has_md_extension: bool,
/// Where the link appears: `(file, line, col)`, 1-based line and column.
pub location: (PathBuf, u32, u32),
}
/// A standard markdown link `[text](url)` — an external reference, kept in a
/// stream separate from [`WikiLink`] so external targets are visible to the
/// toolkit without being conflated with in-store edges. Not graph-validated.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MarkdownLink {
/// The link text inside `[ ]`.
pub text: String,
/// The URL or path inside `( )`.
pub url: String,
/// Where the link appears: `(file, line, col)`, 1-based.
pub location: (PathBuf, u32, u32),
}
/// A `##`/`###` section of a markdown body: the heading text plus the byte
/// slice of the body it spans (heading line through the line before the next
/// heading of equal-or-shallower depth).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Section {
/// The heading text (without the leading `#`s).
pub heading: String,
/// Heading depth (number of leading `#`s).
pub level: u8,
/// The 1-based line where the heading appears.
pub line: u32,
/// The section body, from the heading line to the next sibling-or-shallower
/// heading (exclusive), as a slice of the original body.
pub body: String,
}
/// The parsed structured content of a store's `DB.md` config file.
///
/// All four parts are optional in the source; absent parts fall back to spec
/// defaults. Produced by [`parse_db_md`].
#[derive(Debug, Clone, Default, PartialEq)]
pub struct Config {
/// Body of the `## Agent instructions` section — free-form prose passed to
/// the agent's system prompt.
pub agent_instructions: Option<String>,
/// `## Policies` → `### Frozen pages`: store-relative paths the toolkit
/// refuses to write (`POLICY_FROZEN_PAGE`).
pub frozen_pages: Vec<PathBuf>,
/// `## Policies` → `### Ignored types`: type names the curator never
/// synthesizes (still readable as ambient context).
pub ignored_types: Vec<String>,
/// `## Schemas` → one entry per `### <type>` sub-section.
pub schemas: BTreeMap<String, Schema>,
}
impl Config {
/// The `### Frozen pages` entry that matches a store-relative `target`, if
/// any. The **single** frozen-page matcher every write surface must funnel
/// through so the policy is enforced identically on `write` / `fm set` /
/// `fm init` / `link` / `rename` / `format`.
///
/// Comparison is normalized so a policy line and a write target match
/// regardless of incidental spelling differences:
/// - `/` path separators on every OS,
/// - a single leading `./` dropped,
/// - a trailing `.md` dropped on **both** sides — `parse_db_md` stores
/// frozen entries verbatim, so an operator who writes the natural
/// extensionless spelling (`records/decisions/q1`) must protect the file
/// (`records/decisions/q1.md`) exactly as the `.md` spelling does.
///
/// Returns the matched config entry verbatim (its original spelling) so the
/// caller can name it in the `POLICY_FROZEN_PAGE` refusal.
pub fn frozen_match(&self, target: &Path) -> Option<PathBuf> {
let want = normalize_frozen_path(target);
self.frozen_pages
.iter()
.find(|frozen| {
let pat = normalize_frozen_path(frozen);
// A literal entry matches by exact normalized equality; an entry
// carrying a `*`/`**` glob matches by segment-wise glob so a
// pattern like `records/decisions/*` actually protects the
// concrete files under it instead of silently failing open.
if pat.contains('*') {
frozen_glob_matches(&pat, &want)
} else {
pat == want
}
})
.cloned()
}
/// True if `target` (store-relative) is a frozen page. Convenience wrapper
/// over [`Config::frozen_match`] for callers that only need presence.
pub fn is_frozen(&self, target: &Path) -> bool {
self.frozen_match(target).is_some()
}
}
/// Normalize a path for frozen-page comparison: `/` separators, a leading `./`
/// or `/` dropped, and a trailing `.md` dropped. Both the policy entry and the
/// write target pass through this before equality/glob, so the match is
/// separator-, `./`-, leading-`/`-, and `.md`-insensitive. Without the leading
/// `/` drop, an operator who wrote `/records/decisions/q1.md` normalized to a
/// path that never equals the target's `records/decisions/q1`, silently failing
/// the freeze OPEN.
fn normalize_frozen_path(p: &Path) -> String {
use std::path::Component;
// Keep only the `Normal` path segments, dropping `RootDir`/`Prefix` (a
// leading `/` or drive prefix) and `CurDir` (`.`). This is what makes a
// leading-slash entry (`/records/decisions/q1.md`) normalize to the same
// `records/decisions/q1` as the store-relative target, instead of the
// doubled-`//` prefix `Path::components` + naive join produced — which never
// equalled the target and silently failed the freeze OPEN.
let unix: String = p
.components()
.filter_map(|c| match c {
Component::Normal(s) => s.to_str(),
_ => None,
})
.collect::<Vec<_>>()
.join("/");
unix.strip_suffix(".md").unwrap_or(&unix).to_string()
}
/// Match a normalized frozen-page glob `pat` against a normalized target `path`,
/// segment by segment. `*` matches any run of characters *within a single path
/// segment* (never crossing `/`); `**` as a whole segment matches zero or more
/// whole segments. Both sides are already `normalize_frozen_path`-normalized, so
/// this only deals with `/`-joined segment text. Keeps the substrate dependency-
/// free (no glob crate) while making `records/decisions/*` actually freeze the
/// files beneath it instead of failing open.
fn frozen_glob_matches(pat: &str, path: &str) -> bool {
let pat_segs: Vec<&str> = pat.split('/').collect();
let path_segs: Vec<&str> = path.split('/').collect();
glob_segments(&pat_segs, &path_segs)
}
/// Recursive segment matcher for [`frozen_glob_matches`]. `**` consumes any
/// number of path segments; every other pattern segment must match exactly one
/// path segment (with `*` wildcards inside it).
fn glob_segments(pat: &[&str], path: &[&str]) -> bool {
match pat.split_first() {
None => path.is_empty(),
Some((&"**", rest_pat)) => {
// `**` matches zero segments here, or one-or-more by consuming a path
// segment and recursing on the same `**`.
if glob_segments(rest_pat, path) {
return true;
}
!path.is_empty() && glob_segments(pat, &path[1..])
}
Some((&first_pat, rest_pat)) => match path.split_first() {
Some((&first_path, rest_path)) => {
glob_segment_text(first_pat, first_path) && glob_segments(rest_pat, rest_path)
}
None => false,
},
}
}
/// Match a single glob segment against a single path segment. `*` matches any
/// run of characters within the segment; all other characters are literal.
fn glob_segment_text(pat: &str, seg: &str) -> bool {
if !pat.contains('*') {
return pat == seg;
}
// Split on `*` into literal fragments. The first fragment must be a prefix,
// the last a suffix, and the middle fragments must appear in order.
let parts: Vec<&str> = pat.split('*').collect();
let mut pos = 0usize;
for (idx, part) in parts.iter().enumerate() {
if part.is_empty() {
continue;
}
if idx == 0 {
// Leading literal must be a prefix.
if !seg[pos..].starts_with(part) {
return false;
}
pos += part.len();
} else if idx == parts.len() - 1 {
// Trailing literal must be a suffix at or after the current cursor.
return seg[pos..].ends_with(part);
} else {
// Interior literal: find it at or after the cursor.
match seg[pos..].find(part) {
Some(off) => pos += off + part.len(),
None => return false,
}
}
}
true
}
/// A user-declared type schema parsed from a `DB.md` `### <type>` sub-section.
/// The store's `## Schemas` is the **only** source of schema enforcement — the
/// toolkit ships no built-in or implicit per-type schema (see SPEC § Schemas).
#[derive(Debug, Clone, Default, PartialEq)]
pub struct Schema {
/// One [`FieldSpec`] per bulleted field line, in source order.
pub fields: Vec<FieldSpec>,
/// `- unique: <field>[, <field> …]` directives — each inner vec is one
/// uniqueness constraint over the listed field(s) (compound when >1). Two
/// records of this type whose listed values collide warn as
/// `DUP_UNIQUE_KEY`.
pub unique_keys: Vec<Vec<String>>,
/// `- summary_template: <template>` directive — the `{field}` interpolation
/// pattern `dbmd fm init` / `dbmd write` use to compose a default `summary`
/// for this type. `None` falls back to the body's first paragraph.
pub summary_template: Option<String>,
/// `- shard: by-date | flat` directive — whether records of this type are
/// date-sharded on disk (`records/<type>/<YYYY>/<MM>/…`) or kept flat.
/// `None` = no directive declared, so the store's built-in default for the
/// type applies ([`crate::store::Store::type_shards`]); `Some(true)` forces
/// date-sharding (e.g. a custom event type the toolkit has no built-in for);
/// `Some(false)` forces flat. This is the v0.2 generic-model way to declare
/// sharding — the toolkit ships no implicit per-type behavior beyond the
/// example-type defaults.
pub shard: Option<bool>,
}
/// One field declaration inside a [`Schema`]: `- <name> (<modifiers>)`.
///
/// Modifiers are comma-separated inside the parens; this captures the
/// recognized ones as typed fields and stashes anything unrecognized in
/// [`unknown_modifiers`](FieldSpec::unknown_modifiers) (surfaced as `Info`).
#[derive(Debug, Clone, Default, PartialEq)]
pub struct FieldSpec {
/// The field name.
pub name: String,
/// `required` modifier present.
pub required: bool,
/// The shape modifier (`string`/`int`/`bool`/`date`/`email`/`currency`/
/// `url`), if any.
pub shape: Option<Shape>,
/// `link to <prefix>/` — the store-relative prefix a wiki-link target must
/// start with. The trailing slash is required in the source syntax.
pub link_prefix: Option<PathBuf>,
/// `default <value>` — the value written when the field is absent.
pub default: Option<Value>,
/// `enum: <v1>, <v2>, ...` — the allowed values (must be the last modifier
/// on the line because of its own commas).
pub enum_values: Option<Vec<String>>,
/// Any modifiers not in the recognized vocabulary, preserved verbatim;
/// validate surfaces these as `Info`, never errors.
pub unknown_modifiers: Vec<String>,
}
/// A recognized shape modifier for a schema field. Validate enforces the
/// corresponding value shape (`SCHEMA_SHAPE_MISMATCH` on violation).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Shape {
/// Any scalar string.
String,
/// Integer.
Int,
/// Boolean.
Bool,
/// RFC3339 / ISO-8601 date.
Date,
/// `<local>@<domain>` email address.
Email,
/// A currency amount.
Currency,
/// A URL.
Url,
}
/// The result of splitting a raw file into its frontmatter block and body.
///
/// `body` is the verbatim remainder after the closing `---` fence — the writer
/// preserves it byte-for-byte so operator edits are never reflowed.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ParsedFile {
/// The raw frontmatter YAML (between the fences, exclusive of them).
pub frontmatter_yaml: String,
/// The verbatim body (everything after the closing `---`).
pub body: String,
}
/// Split a file's full text into its frontmatter block and body. The
/// frontmatter block must be the very first thing in the file, delimited by
/// `---` on its own line at start and end. Returns
/// [`ParseError::MissingFrontmatter`] if absent.
pub fn split_frontmatter(text: &str, file: &Path) -> Result<ParsedFile, ParseError> {
// Tolerate a single leading UTF-8 BOM (U+FEFF) before the opening fence,
// matching `store::frontmatter_block` and `index::extract_frontmatter_block`
// which already strip it. Without this, a BOM-prefixed file (common from
// Windows / exported markdown dropped into `sources/`) gets walked and
// indexed by `dbmd index` yet hard-fails every write/edit surface that
// routes through `read_file` (`fm get/set`, `format`, `link`, `write`). The
// BOM is dropped from the emitted body so the canonical writer never carries
// it forward.
let text = text.strip_prefix('\u{feff}').unwrap_or(text);
// The opening fence must be the very first line: `---`, no leading
// whitespace, nothing before it. Trailing whitespace on the fence line is
// tolerated via `trim_end()` (which strips spaces/tabs as well as CR/LF) so
// this matches `index::extract_frontmatter_block` and
// `validate::split_frontmatter`, both of which use `trim_end()`. Without this
// agreement a fence written `--- ` (a single trailing space — invisible in an
// editor, easily produced by hand edits or exporters) was indexed and
// validated clean by those scanners yet hard-failed every write/edit surface
// routed through `read_file` (`fm get/set`, `format`, `link`, `write`) — the
// same cross-scanner drift class already fixed for the UTF-8 BOM above.
let mut lines = text.split_inclusive('\n');
let first = lines.next().unwrap_or("");
if first.trim_end() != "---" {
return Err(ParseError::MissingFrontmatter {
file: file.to_path_buf(),
});
}
// Scan for the closing fence line. Track byte offsets so we can slice the
// YAML (between fences, exclusive) and the body (verbatim, after the
// closing fence's line terminator).
let opening_len = first.len();
let mut offset = opening_len;
for line in lines {
if line.trim_end() == "---" {
let yaml = &text[opening_len..offset];
let body_start = offset + line.len();
let body = &text[body_start..];
return Ok(ParsedFile {
frontmatter_yaml: yaml.to_string(),
body: body.to_string(),
});
}
offset += line.len();
}
// Opening fence present but no closing fence: malformed frontmatter block.
Err(ParseError::MissingFrontmatter {
file: file.to_path_buf(),
})
}
/// Read a file from disk and parse it into typed [`Frontmatter`] plus the
/// verbatim body string.
pub fn read_file(path: &Path) -> Result<(Frontmatter, String), ParseError> {
let text = std::fs::read_to_string(path)?;
let parsed = split_frontmatter(&text, path)?;
let fm = Frontmatter::parse(&parsed.frontmatter_yaml, path)?;
Ok((fm, parsed.body))
}
/// Atomically write a markdown file from frontmatter + body: emit the
/// frontmatter in canonical key order, then the body verbatim, via a
/// temp-file-rename so a reader never sees a half-written file. Preserves the
/// operator-edited body exactly as given.
pub fn write_file(path: &Path, frontmatter: &Frontmatter, body: &str) -> Result<(), ParseError> {
let contents = render_file(frontmatter, body);
// One durable, atomic write for all primary data (see `crate::fsx`):
// temp-file + fsync + rename + parent-fsync. Content records are primary
// data, so they get the durable path (unlike the rebuildable index).
crate::fsx::write_atomic(path, contents.as_bytes())?;
Ok(())
}
/// Atomically create a markdown file from frontmatter + body, refusing with
/// [`std::io::ErrorKind::AlreadyExists`] if the destination already exists.
///
/// This is the create-new sibling of [`write_file`]: same canonical rendering
/// and durable temp-file path, but backed by [`crate::fsx::write_atomic_new`] so
/// two concurrent creators for the same path cannot both succeed.
pub fn write_file_new(
path: &Path,
frontmatter: &Frontmatter,
body: &str,
) -> Result<(), ParseError> {
let contents = render_file(frontmatter, body);
crate::fsx::write_atomic_new(path, contents.as_bytes())?;
Ok(())
}
fn render_file(frontmatter: &Frontmatter, body: &str) -> String {
let yaml = frontmatter.to_yaml();
// `to_yaml` already terminates each block with a newline. Compose the file
// as: opening fence, frontmatter YAML, closing fence, then body verbatim.
let mut contents = String::with_capacity(yaml.len() + body.len() + 8);
contents.push_str("---\n");
contents.push_str(&yaml);
contents.push_str("---\n");
contents.push_str(body);
contents
}
/// Extract every wiki-link from a body (and inline frontmatter), returning the
/// structured [`WikiLink`] stream with short-form / `.md`-extension flags and
/// `(file, line, col)` locations set.
pub fn extract_wiki_links(body: &str, file: &Path) -> Vec<WikiLink> {
static RE: std::sync::OnceLock<regex::Regex> = std::sync::OnceLock::new();
let re = RE.get_or_init(|| {
// [[target]] or [[target|display]]; target/display exclude brackets and
// (for target) the `|` separator so nested forms don't over-match.
regex::Regex::new(r"\[\[([^\[\]|]+?)(?:\|([^\[\]]*))?\]\]").expect("valid wiki-link regex")
});
let mut out = Vec::new();
for (line_idx, line) in body.lines().enumerate() {
for caps in re.captures_iter(line) {
let whole = caps.get(0).expect("group 0 always present");
let target = caps.get(1).map(|m| m.as_str()).unwrap_or("").to_string();
let display = caps.get(2).map(|m| m.as_str().to_string());
out.push(WikiLink {
is_full_path: target_is_full_path(&target),
has_md_extension: target_has_md_extension(&target),
target,
display,
location: (
file.to_path_buf(),
(line_idx as u32) + 1,
char_column(line, whole.start()),
),
});
}
}
out
}
/// Extract every standard markdown link `[text](url)` from a body into a
/// separate stream, kept distinct from wiki-links.
pub fn extract_markdown_links(body: &str, file: &Path) -> Vec<MarkdownLink> {
static RE: std::sync::OnceLock<regex::Regex> = std::sync::OnceLock::new();
let re = RE.get_or_init(|| {
// [text](url). `text` excludes brackets so a wiki-link `[[x]]` (which
// has `]]`, not `](`) never matches; `url` excludes `)` and whitespace.
regex::Regex::new(r"\[([^\[\]]*)\]\(([^)\s]*)\)").expect("valid markdown-link regex")
});
let mut out = Vec::new();
for (line_idx, line) in body.lines().enumerate() {
for caps in re.captures_iter(line) {
let whole = caps.get(0).expect("group 0 always present");
out.push(MarkdownLink {
text: caps.get(1).map(|m| m.as_str()).unwrap_or("").to_string(),
url: caps.get(2).map(|m| m.as_str()).unwrap_or("").to_string(),
location: (
file.to_path_buf(),
(line_idx as u32) + 1,
char_column(line, whole.start()),
),
});
}
}
out
}
/// Detect the frontmatter wiki-link-list mis-encoding: a wiki-link *list*
/// written so YAML parses it as nested sequences instead of a clean list of
/// strings. Returns the offending keys so validate can emit
/// `WIKI_LINK_FLOW_FORM_LIST`.
///
/// The subtlety is that `[[x]]` is YAML for "a list containing `[x]`", so the
/// shapes nest:
///
/// - **Scalar inline** `company: [[records/x]]` → `Seq[ Seq[String] ]`
/// (double-nested). This is the spec's scalar wiki-link form — NOT flagged.
/// - **Flow list** `attendees: [[[a]], [[b]]]` → `Seq[ Seq[Seq[String]], … ]`
/// (triple-nested). The list mis-encoding — flagged.
/// - **Unquoted block list** (`- [[a]]` per line) → also triple-nested, so it
/// is flagged too; the canonical list form must quote each item
/// (`- "[[a]]"`), which parses to a clean `Seq[String, …]` and is NOT flagged.
///
/// So the discriminator is nesting depth: a *list* mis-encoding has at least one
/// item that is itself a sequence-of-sequences, whereas a scalar inline link's
/// single item is a sequence-of-scalars.
pub fn detect_flow_form_link_lists(frontmatter_yaml: &str) -> Vec<String> {
let value: Value = match serde_norway::from_str(frontmatter_yaml) {
Ok(v) => v,
// Malformed YAML is FM_MALFORMED_YAML's job, not ours; report nothing.
Err(_) => return Vec::new(),
};
let Value::Mapping(map) = value else {
return Vec::new();
};
let mut out = Vec::new();
for (k, v) in &map {
if let Value::Sequence(items) = v {
// Triple-nesting: some outer item is a sequence that itself holds a
// sequence. Scalar inline `[[x]]` is only double-nested, so it
// never matches.
let is_link_list = items.iter().any(|item| match item {
Value::Sequence(inner) => inner.iter().any(|x| matches!(x, Value::Sequence(_))),
_ => false,
});
if is_link_list {
if let Some(key) = k.as_str() {
out.push(key.to_string());
}
}
}
}
out
}
/// Extract the `##`/`###` sections of a markdown body into a flat list with
/// body slices.
pub fn extract_sections(body: &str) -> Vec<Section> {
// Keep each line's start so we can slice the body verbatim (exact newlines).
let lines: Vec<&str> = body.split_inclusive('\n').collect();
// First pass: classify heading levels (0 = not a heading), honoring fenced
// code blocks so a `## x` inside a ``` fence is not treated as a heading.
let mut levels: Vec<u8> = Vec::with_capacity(lines.len());
let mut fence: Option<(u8, usize)> = None;
for line in &lines {
let content = line.trim_end_matches(['\n', '\r']);
if let Some(f) = fence {
if is_closing_fence(content, f) {
fence = None;
}
levels.push(0);
continue;
}
if let Some(opened) = opening_fence(content) {
fence = Some(opened);
levels.push(0);
continue;
}
levels.push(heading_level(content));
}
// Second pass: emit `##`+ headings; each section body runs from its heading
// line to the next heading at an equal-or-shallower level (exclusive).
let mut sections = Vec::new();
for (i, &lvl) in levels.iter().enumerate() {
if lvl < 2 {
continue;
}
let heading_line = lines[i].trim_end_matches(['\n', '\r']);
let heading = heading_text(heading_line, lvl);
let mut end = lines.len();
for (j, &other) in levels.iter().enumerate().skip(i + 1) {
if other != 0 && other <= lvl {
end = j;
break;
}
}
sections.push(Section {
heading,
level: lvl,
line: (i + 1) as u32,
body: lines[i..end].concat(),
});
}
sections
}
/// Extract the `##`/`###` sections of a **whole file** (frontmatter + body),
/// returning each [`Section`] with `line` numbered against the *source file*,
/// not the body.
///
/// [`extract_sections`] numbers headings 1-based within the body it is handed —
/// the right frame for callers that already track the frontmatter offset
/// (`validate` adds `fm_end_line`). But the single-file views (`dbmd sections`,
/// `dbmd outline`) present `Section::line` as a source line an agent can jump to;
/// because every db.md file opens with a frontmatter block, the body-relative
/// number is off by the block's length (`opening fence + frontmatter lines +
/// closing fence`) for every file. This helper does the offset once, in the
/// parser, so those surfaces report true file lines. A file with no leading
/// frontmatter block is treated as all-body (offset 0), so the function never
/// fails just because a file lacks frontmatter.
pub fn extract_sections_in_file(text: &str) -> Vec<Section> {
// Tolerate a leading BOM the same way `split_frontmatter` does, so the line
// count and the body slice agree with the read path.
let text = text.strip_prefix('\u{feff}').unwrap_or(text);
// Find the body and how many source lines precede it. The body begins right
// after the closing fence; the number of lines consumed by the frontmatter
// block (both fences + the YAML between) is the offset to add to each
// body-relative heading line.
let (body, offset) = match split_frontmatter(text, Path::new("<sections>")) {
Ok(parsed) => {
// Lines before the body = total lines in `text` minus lines in body.
let total_lines = count_lines(text);
let body_lines = count_lines(&parsed.body);
(parsed.body, total_lines.saturating_sub(body_lines))
}
// No frontmatter block: the whole text is body, no offset.
Err(_) => (text.to_string(), 0),
};
let mut sections = extract_sections(&body);
for s in &mut sections {
s.line += offset;
}
sections
}
/// Count the number of lines a string spans for line-number offsetting: one line
/// per `\n`, plus one more for a final line with no trailing newline. An empty
/// string is zero lines.
fn count_lines(s: &str) -> u32 {
if s.is_empty() {
return 0;
}
let newlines = s.bytes().filter(|&b| b == b'\n').count() as u32;
if s.ends_with('\n') {
newlines
} else {
newlines + 1
}
}
/// Parse a store's `DB.md` file into a [`Config`]: the `## Agent instructions`
/// prose, `## Policies` (`### Frozen pages` + `### Ignored types`), and
/// `## Schemas` (`### <type>` field-bullet blocks). Unrecognized sections are
/// ignored; absent sections leave their [`Config`] fields at default.
pub fn parse_db_md(text: &str, file: &Path) -> Result<Config, ParseError> {
// The structured sections live in the body (after frontmatter). DB.md must
// still start with a valid `---` block (`type: db-md`); if it's missing we
// surface MissingFrontmatter like any other file.
let parsed = split_frontmatter(text, file)?;
let _frontmatter = Frontmatter::parse(&parsed.frontmatter_yaml, file)?;
let sections = extract_sections(&parsed.body);
let mut config = Config::default();
// Track which H2 region each H3 belongs to as we walk the flat list.
let mut current_h2: Option<String> = None;
for section in §ions {
match section.level {
2 => {
let name = section.heading.trim().to_ascii_lowercase();
current_h2 = Some(name.clone());
if name == "agent instructions" {
let prose = section_prose(§ion.body);
if !prose.is_empty() {
config.agent_instructions = Some(prose);
}
}
}
3 => {
let h2 = current_h2.as_deref().unwrap_or("");
let h3 = section.heading.trim().to_ascii_lowercase();
match (h2, h3.as_str()) {
("policies", "frozen pages") => {
config.frozen_pages = bullet_lines(§ion.body)
.into_iter()
.map(|b| PathBuf::from(extract_path_bullet(&b)))
.collect();
}
("policies", "ignored types") => {
config.ignored_types = bullet_lines(§ion.body)
.into_iter()
.flat_map(|b| extract_type_list_bullet(&b))
.collect();
}
("schemas", _) => {
// The H3 heading text (as written) is the type name.
let type_name = section.heading.trim().to_string();
let mut schema = Schema::default();
for b in bullet_lines(§ion.body) {
match parse_schema_bullet(&b) {
SchemaBullet::Field(f) => schema.fields.push(f),
SchemaBullet::Unique(k) if !k.is_empty() => {
schema.unique_keys.push(k)
}
SchemaBullet::SummaryTemplate(t) if !t.is_empty() => {
schema.summary_template = Some(t)
}
SchemaBullet::Shard(Some(b)) => schema.shard = Some(b),
// Empty `unique:`/`summary_template:`, or a `shard:`
// with an unrecognized value — ignored.
SchemaBullet::Unique(_)
| SchemaBullet::SummaryTemplate(_)
| SchemaBullet::Shard(None) => {}
}
}
config.schemas.insert(type_name, schema);
}
_ => {}
}
}
_ => {}
}
}
Ok(config)
}
/// One parsed bullet inside a `### <type>` schema block: an ordinary field, or a
/// reserved directive (`unique:` / `summary_template:` / `shard:`). The names
/// `unique`, `summary_template`, and `shard` are reserved and cannot be used as
/// field names.
#[derive(Debug)]
enum SchemaBullet {
/// An ordinary `- <name> (<modifiers>)` field.
Field(FieldSpec),
/// `- unique: <field>[, <field> …]` — a (possibly compound) uniqueness key.
Unique(Vec<String>),
/// `- summary_template: <template>` — the default-`summary` pattern.
SummaryTemplate(String),
/// `- shard: by-date | flat` — date-shard records of this type, or keep them
/// flat. `None` = an unrecognized value, ignored like an unknown modifier.
Shard(Option<bool>),
}
/// Classify one `## Schemas` bullet as a directive or a field. The directive
/// forms are `- unique: a, b, …` and `- summary_template: …`; the keyword check
/// guards against false positives — a field like `- status (enum: a, b)` has a
/// `(` before any `:`, so its head isn't a bare reserved keyword and it parses
/// as a [`FieldSpec`].
fn parse_schema_bullet(bullet_line: &str) -> SchemaBullet {
let line = bullet_line.trim();
let line = line
.strip_prefix("- ")
.or_else(|| line.strip_prefix("* "))
.or_else(|| line.strip_prefix("+ "))
.or_else(|| line.strip_prefix('-'))
.unwrap_or(line)
.trim();
if let Some((head, rest)) = line.split_once(':') {
match head.trim().to_ascii_lowercase().as_str() {
"unique" => {
let fields = rest
.split(',')
.map(|f| f.trim().to_string())
.filter(|f| !f.is_empty())
.collect();
return SchemaBullet::Unique(fields);
}
"summary_template" => {
return SchemaBullet::SummaryTemplate(rest.trim().to_string());
}
"shard" => {
// `by-date` (synonyms: date/sharded/true) enables date-sharding;
// `flat` (none/false) forces flat; anything else is ignored.
let v = match rest.trim().to_ascii_lowercase().as_str() {
"by-date" | "date" | "sharded" | "true" => Some(true),
"flat" | "none" | "false" => Some(false),
_ => None,
};
return SchemaBullet::Shard(v);
}
_ => {}
}
}
SchemaBullet::Field(parse_field_spec(bullet_line))
}
/// Parse a single `## Schemas` field-bullet line — `- <name> (<modifiers>)` —
/// into a [`FieldSpec`], capturing recognized modifiers and stashing the rest
/// in [`FieldSpec::unknown_modifiers`].
pub fn parse_field_spec(bullet_line: &str) -> FieldSpec {
// Strip the leading bullet marker (`- ` / `* ` / `+ `) and surrounding ws.
let line = bullet_line.trim();
let line = line
.strip_prefix("- ")
.or_else(|| line.strip_prefix("* "))
.or_else(|| line.strip_prefix("+ "))
.or_else(|| line.strip_prefix('-'))
.unwrap_or(line)
.trim();
// Split `<name> (<modifiers>)` — the canonical paren form — OR the natural
// mis-spelling `<name>: <modifiers>` (colon instead of parens). The two
// delimiters are interchangeable for the field head; whichever appears FIRST
// wins, so a paren form whose modifiers contain a colon (`status (enum: a,
// b)`) still parses by parens (the `(` precedes the `:`), while a bare
// `title: string, required` parses by colon instead of being swallowed whole
// into the field name with every modifier silently dropped.
let paren = line.find('(');
let colon = line.find(':');
// Choose the head delimiter. The paren form wins when its `(` precedes any
// `:` (so `status (enum: a, b)` parses by parens, the colon being inside the
// modifiers); otherwise a `:` before the paren — or with no paren at all —
// selects the colon form `<name>: <modifiers>`, the natural mis-spelling that
// must NOT be swallowed whole into the field name with every modifier lost.
let use_paren = matches!((paren, colon), (Some(p), c) if c.is_none_or(|c| p < c));
let (name, modifiers) = if use_paren {
let open = paren.expect("use_paren implies a paren");
let name = line[..open].trim().to_string();
let after = &line[open + 1..];
let mods = match after.rfind(')') {
Some(close) => &after[..close],
None => after, // tolerate a missing close paren
};
(name, mods.trim())
} else if let Some(c) = colon {
// Colon form: everything after the first colon is the modifier list,
// parsed identically to the parenthesized modifiers below.
let name = line[..c].trim().to_string();
(name, line[c + 1..].trim())
} else {
// Neither delimiter: a free-form optional field of any shape — name only.
(line.to_string(), "")
};
let mut spec = FieldSpec {
name,
..FieldSpec::default()
};
if modifiers.is_empty() {
return spec;
}
// Modifiers are comma-separated. `enum` and `default` are special: their own
// values may contain commas, so each is a *greedy* clause that runs from its
// keyword to the start of the next recognized greedy clause (or end of line).
// This lets `default North America, EMEA fallback` keep its comma and lets a
// `default …` written after an `enum …` still be recognized, instead of the
// value being truncated at the first comma or absorbed into the enum list.
let raw: Vec<&str> = modifiers.split(',').collect();
let mut i = 0;
while i < raw.len() {
let token = raw[i].trim();
if token.is_empty() {
i += 1;
continue;
}
let lower = token.to_ascii_lowercase();
if lower == "required" {
spec.required = true;
i += 1;
} else if let Some(shape) = shape_from_str(&lower) {
spec.shape = Some(shape);
i += 1;
} else if let Some(rest) = lower.strip_prefix("link to ") {
// The trailing slash is required in the source; store the prefix
// without it so `Path::starts_with` comparisons are clean.
let prefix = token["link to ".len()..].trim().trim_end_matches('/');
let _ = rest; // lowercase form only used for the keyword match
spec.link_prefix = Some(PathBuf::from(prefix));
i += 1;
} else if token.len() >= "default ".len() && lower.starts_with("default ") {
// Greedy `default <value>`: the value is this token (after the
// keyword) plus every following comma-token up to the next greedy
// clause, rejoined with the commas the split removed — so a comma
// inside the default value is preserved. Original case is kept.
let end = next_greedy_clause(&raw, i + 1);
let mut value = token["default ".len()..].to_string();
for tok in &raw[i + 1..end] {
value.push(',');
value.push_str(tok);
}
spec.default = Some(Value::String(value.trim().to_string()));
i = end;
} else if lower == "enum" || lower.starts_with("enum:") {
// Greedy `enum` (bare `enum, a, b` or `enum: a, b`): the values run
// from here to the next greedy clause (e.g. a trailing `default …`),
// NOT unconditionally to end-of-line — so a `default` after `enum` is
// parsed instead of swallowed as a bogus enum member.
let end = next_greedy_clause(&raw, i + 1);
// Rejoin this clause's tokens (trimmed so the `enum` head sits at the
// start), drop the leading `enum`/`enum:` head, then re-split the
// remainder into values.
let joined = raw[i..end].join(",");
let joined = joined.trim();
let after_kw = match joined.find(':') {
// `enum: a, b` — values follow the colon.
Some(colon) => &joined[colon + 1..],
// bare `enum, a, b` — values follow the keyword itself.
None => joined.get("enum".len()..).unwrap_or(""),
};
let values: Vec<String> = after_kw
.split(',')
.map(|v| v.trim().to_string())
.filter(|v| !v.is_empty())
.collect();
spec.enum_values = Some(values);
i = end;
} else {
// Unrecognized modifier — captured verbatim, surfaced as Info.
spec.unknown_modifiers.push(token.to_string());
i += 1;
}
}
spec
}
// ── Private helpers ─────────────────────────────────────────────────────────
/// Parse a frontmatter timestamp value into a `DateTime<FixedOffset>`. A `null`
/// is treated as absent; anything else must be an RFC3339 string.
fn parse_timestamp(
value: &Value,
key: &str,
file: &Path,
) -> Result<Option<DateTime<FixedOffset>>, ParseError> {
match value {
Value::Null => Ok(None),
Value::String(s) => parse_rfc3339(s, key, file).map(Some),
other => Err(ParseError::BadTimestamp {
file: file.to_path_buf(),
key: key.to_string(),
value: format!("{other:?}"),
}),
}
}
/// Parse an RFC3339 timestamp string, mapping failure to [`ParseError::BadTimestamp`].
fn parse_rfc3339(s: &str, key: &str, file: &Path) -> Result<DateTime<FixedOffset>, ParseError> {
DateTime::parse_from_rfc3339(s.trim()).map_err(|_| ParseError::BadTimestamp {
file: file.to_path_buf(),
key: key.to_string(),
value: s.to_string(),
})
}
/// Coerce a YAML scalar value to its string form for the universal-contract
/// fields (`type`/`id`/`summary`/`status`). Mirrors `validate::scalar_string`
/// and `store::yaml_scalar_string` so the four modules agree on one coercion
/// rule: a bare numeric/bool scalar (`id: 100`, `summary: 2026`, `status: 0`)
/// is preserved as its string form rather than being read as None and silently
/// dropped on the next `to_yaml` re-emit. Returns `None` only for genuinely
/// non-scalar values (sequences, mappings, null), which were never a valid
/// shape for these fields.
fn scalar_string(value: &Value) -> Option<String> {
match value {
Value::String(s) => Some(s.clone()),
Value::Number(n) => Some(n.to_string()),
Value::Bool(b) => Some(b.to_string()),
_ => None,
}
}
/// Read a `tags` value into a flat `Vec<String>`. Accepts a sequence of scalars
/// (the canonical form) or a single scalar (coerced to a one-element list).
fn parse_tags(value: &Value) -> Vec<String> {
match value {
Value::Sequence(items) => items
.iter()
.filter_map(|v| match v {
Value::String(s) => Some(s.clone()),
Value::Number(n) => Some(n.to_string()),
Value::Bool(b) => Some(b.to_string()),
_ => None,
})
.collect(),
Value::String(s) => vec![s.clone()],
_ => Vec::new(),
}
}
/// Read a `tags` value into a flat `Vec<String>` **without losing data**: a
/// sequence of clean scalars (the canonical form) or a single scalar coerce to a
/// string list. Any other shape — a sequence with a non-scalar item
/// (`tags: [[vip]]` → `Seq[Seq[String]]`, `tags: [a, [b]]`), or a mapping — is
/// rejected as `Err(value.clone())` so the caller preserves the raw value in
/// `extra` rather than silently filtering items out / erasing the field on the
/// next re-emit. This is the `tags` analog of routing a non-scalar universal
/// value to pass-through instead of the destroy path.
fn parse_tags_preserving(value: &Value) -> Result<Vec<String>, Value> {
match value {
Value::Sequence(items) => {
let mut out = Vec::with_capacity(items.len());
for item in items {
match item {
Value::String(s) => out.push(s.clone()),
Value::Number(n) => out.push(n.to_string()),
Value::Bool(b) => out.push(b.to_string()),
// A non-scalar item (nested sequence/mapping/null) means this
// is not a clean tag list; preserve the whole value verbatim.
_ => return Err(value.clone()),
}
}
Ok(out)
}
Value::String(s) => Ok(vec![s.clone()]),
Value::Number(n) => Ok(vec![n.to_string()]),
Value::Bool(b) => Ok(vec![b.to_string()]),
// A mapping / null `tags` value is not a list; preserve it verbatim.
_ => Err(value.clone()),
}
}
/// Render a non-string YAML mapping key as the scalar text YAML would emit for
/// it (`2026`, `true`, `3.14`, …), so a numeric/bool/float frontmatter key
/// preserves its key *text* on round-trip instead of being rewritten to its Rust
/// `Debug` form (`Number(2026)`, `Bool(true)`, `'Null'`). The key re-emits as a
/// string-typed key carrying the original text (`'2026':`) — the type narrows to
/// string, but the operator's data is no longer corrupted, and ordinary string
/// keys are wholly unaffected. Falls back to `Debug` only for a key shape that
/// cannot be a scalar (a sequence/mapping key — not expressible in our
/// `String`-keyed `extra`), which never occurs in practice.
fn yaml_scalar_key(key: &Value) -> String {
match key {
Value::String(s) => s.clone(),
Value::Number(n) => n.to_string(),
Value::Bool(b) => b.to_string(),
Value::Null => "null".to_string(),
// Non-scalar key: not representable as a plain `extra` string key; keep
// the defensive Debug form so nothing panics (unreachable in practice).
other => format!("{other:?}"),
}
}
/// Parse a single `[[target|display]]` string into a [`WikiLink`] with no
/// location, or `None` if the string is not a bare wiki-link. Used for
/// frontmatter-valued links where there is no body position to report.
fn parse_wiki_link_str(s: &str) -> Option<WikiLink> {
let s = s.trim();
let inner = s.strip_prefix("[[")?.strip_suffix("]]")?;
// Reject anything with further brackets (e.g. the nested flow-form item),
// which is not a clean single wiki-link.
if inner.contains('[') || inner.contains(']') {
return None;
}
let (target, display) = match inner.split_once('|') {
Some((t, d)) => (t.to_string(), Some(d.to_string())),
None => (inner.to_string(), None),
};
Some(WikiLink {
is_full_path: target_is_full_path(&target),
has_md_extension: target_has_md_extension(&target),
target,
display,
location: (PathBuf::new(), 0, 0),
})
}
/// Extract every wiki-link from a single frontmatter field value, accepting the
/// two canonical forms the spec defines (SPEC § Linking):
///
/// - a **scalar** wiki-link field, in either the quoted (`f: "[[x]]"`) or the
/// canonical unquoted inline (`f: [[x]]`) form, and
/// - a **list** field whose items are quoted wiki-link strings
/// (`- "[[x]]"`).
///
/// YAML eats the brackets of an unquoted `[[x]]`, leaving a flow-list-in-a-list,
/// so the parsed [`Value`] shapes are not what one would naively expect:
///
/// | source | parsed `Value` | here |
/// |--------------------------------|------------------------------------|------|
/// | `f: "[[x]]"` (quoted) | `String("[[x]]")` | link |
/// | `f: [[x]]` (unquoted) | `Seq[ Seq[String("x")] ]` | link |
/// | `f:`\n` - "[[x]]"`(quoted) | `Seq[ String("[[x]]"), … ]` | link |
/// | `f:`\n` - [[x]]` (unquoted) | `Seq[ Seq[Seq[String("x")]], … ]` | — |
///
/// The last row — an *unquoted list* — parses identically to the flow-form list
/// `f: [[a], [b]]` and is a mis-encoding the canonical writer never emits;
/// `dbmd validate` reports it as `WIKI_LINK_FLOW_FORM_LIST` (see
/// [`detect_flow_form_link_lists`]). It is deliberately NOT surfaced here, so an
/// edge enumerator only ever sees the valid canonical forms.
///
/// The unquoted scalar (`Seq[Seq[String]]`, one element) is told apart from a
/// plain one-item flow list (`f: [x]` → `Seq[String]`, one fewer nesting level)
/// by [`unquoted_inline_link`] requiring its argument to be a `Sequence`.
fn links_in_field_value(value: &Value) -> Vec<WikiLink> {
// Quoted scalar: `field: "[[x]]"`.
if let Value::String(s) = value {
return parse_wiki_link_str(s).into_iter().collect();
}
let Value::Sequence(items) = value else {
return Vec::new();
};
// Unquoted scalar inline form `field: [[x]]` → `Seq[ Seq[String(x)] ]`.
// (A quoted single-item list `["[[x]]"]` is `Seq[String]`, so its lone item
// is a `String`, not a `Sequence`, and falls through to the list path below.)
if items.len() == 1 {
if let Some(link) = unquoted_inline_link(&items[0]) {
return vec![link];
}
}
// Otherwise a list of quoted wiki-link strings; non-string items (the
// unquoted-list mis-encoding) are left for validate to flag.
items
.iter()
.filter_map(|item| parse_wiki_link_str(item.as_str()?))
.collect()
}
/// Canonicalize one `extra` frontmatter value for emission by [`Frontmatter::to_yaml`].
///
/// The read path ([`Frontmatter::parse`]) stores every unknown key's raw parsed
/// [`Value`] verbatim, so a SPEC-canonical *unquoted* inline scalar wiki-link
/// (`company: [[records/companies/northstar]]`) lands in `extra` as the nested
/// shape YAML produces for it — `Seq[ Seq[String("records/companies/northstar")] ]`.
/// Re-emitting that verbatim yields the block sequence
///
/// ```text
/// company:
/// - - records/companies/northstar
/// ```
///
/// which has lost the `[[ ]]` brackets entirely: the link is destroyed, and every
/// reader (validate, graph, backlinks) stops seeing the edge. This normalizes such
/// a value back into the canonical emitted form before it is written:
///
/// - a **scalar** wiki-link (quoted `String("[[x]]")` or unquoted `Seq[Seq[String]]`,
/// one element) → a quoted scalar `Value::String("[[x]]")`, which serde_norway emits
/// inline as `'[[x]]'` — the form the finding confirms survives a round-trip and
/// that [`links_in_field_value`] reads back as the same scalar link;
/// - a **list** of wiki-links (in any spelling [`links_in_field_value`] accepts) →
/// a block `Value::Sequence` of quoted-link strings (`- "[[x]]"`), matching the
/// `set` write-in path and the canonical list form;
/// - everything else → returned verbatim (the common no-op for non-link values).
///
/// `|display` is preserved in both link branches. This is the single point that
/// keeps all three curator-loop writers (`format`, `fm set`, `link`) from
/// corrupting a pre-existing canonical link, since they all funnel through
/// `to_yaml`.
fn canonicalize_extra_value(value: &Value) -> Value {
match value {
// Scalar wiki-link, quoted form: `field: "[[x]]"` → `String("[[x]]")`.
// Re-emit as a quoted scalar so it stays a string (never the brackets-as-
// YAML nested sequence). Non-link strings are returned untouched.
Value::String(s) => match parse_wiki_link_str(s) {
Some(link) => Value::String(wiki_link_literal(&link)),
None => value.clone(),
},
Value::Sequence(items) => {
// Scalar wiki-link, unquoted inline form: `field: [[x]]` parses to a
// one-element `Seq[ Seq[String(x)] ]`. Collapse back to the quoted
// scalar string so the link is preserved rather than block-emitted.
if items.len() == 1 {
if let Some(link) = unquoted_inline_link(&items[0]) {
return Value::String(wiki_link_literal(&link));
}
}
// List of wiki-links: re-emit as a block sequence of quoted-link
// strings, the canonical list form `to_yaml` renders block-style and
// `links_in_field_value` accepts. Only canonicalize when *every* item
// is a clean single wiki-link; a list with any non-link item is left
// verbatim so unrelated sequences (and the unquoted-list mis-encoding
// validate flags) are untouched.
let mut links = Vec::with_capacity(items.len());
for item in items {
match link_from_flow_list_item(item) {
Some(link) => links.push(link),
None => return value.clone(),
}
}
if links.is_empty() {
return value.clone();
}
Value::Sequence(
links
.iter()
.map(|l| Value::String(wiki_link_literal(l)))
.collect(),
)
}
// Mappings, scalars other than strings, nulls: nothing to canonicalize.
_ => value.clone(),
}
}
/// Render a [`WikiLink`] back to its `[[target]]` / `[[target|display]]` literal,
/// the inner form the canonical writer emits and `links_in_field_value` accepts.
fn wiki_link_literal(link: &WikiLink) -> String {
match &link.display {
Some(d) => format!("[[{}|{}]]", link.target, d),
None => format!("[[{}]]", link.target),
}
}
/// Recognize the inner token of an unquoted scalar `[[x]]`: after YAML strips the
/// outer brackets, the inner `[x]` is a single-element sequence `Seq[String(x)]`.
/// Reconstructs `[[x]]` (preserving any `|display`) and parses it, or returns
/// `None` when `v` is not that shape. Requiring a `Sequence` here is what keeps a
/// plain one-item flow list (`field: [x]` → `Seq[String]`, not `Seq[Seq[String]]`)
/// from being mistaken for a wiki-link.
fn unquoted_inline_link(v: &Value) -> Option<WikiLink> {
let Value::Sequence(items) = v else {
return None;
};
if items.len() != 1 {
return None;
}
let s = items[0].as_str()?;
// A clean unquoted wiki-link has no further brackets inside it.
if s.contains('[') || s.contains(']') {
return None;
}
parse_wiki_link_str(&format!("[[{s}]]"))
}
/// Decide whether a `dbmd fm set` / `--fm` value string is a **list of
/// wiki-links** that should be stored as a YAML block sequence, returning the
/// canonical `Value::Sequence` of quoted-link strings when so.
///
/// The value path of every write surface stringifies its argument; without this
/// a required list-of-links field (`meeting.attendees`) was unwritable in valid
/// form — passing `[[[a]], [[b]]]` stored a single scalar string that mis-parses
/// and trips `WIKI_LINK_FLOW_FORM_LIST` / `WIKI_LINK_BROKEN`. This recognizes the
/// two list spellings an agent naturally types and normalizes both to the block
/// form the canonical writer emits and `dbmd validate` accepts:
///
/// - flow list of quoted links — `["[[a]]", "[[b]]"]`
/// - flow list of unquoted links — `[[[a]], [[b]]]` (YAML: `Seq[Seq[String], …]`)
///
/// Returns `None` (⇒ caller stores a verbatim scalar string) for everything that
/// is not unambiguously a list of clean wiki-links — plain text, a single inline
/// `[[x]]` (YAML reads it as a one-item `Seq[Seq[String]]`, kept scalar so it
/// renders inline), an empty list, or a list with any non-link item. A single
/// link must stay scalar; only genuine multi-item-or-explicit lists become
/// sequences, matching `links_in_field_value`'s acceptance rule so writer and
/// validator never disagree.
fn parse_link_list_value(value: &str) -> Option<Value> {
let trimmed = value.trim();
// Only a YAML *flow sequence* literal is a list candidate; anything not
// wrapped in `[ … ]` is a scalar (a bare `[[x]]` is wrapped, and handled by
// the single-inline-link guard below).
if !(trimmed.starts_with('[') && trimmed.ends_with(']')) {
return None;
}
let Ok(Value::Sequence(items)) = serde_norway::from_str::<Value>(trimmed) else {
return None;
};
// A single inline `[[x]]` parses to `Seq[ Seq[String(x)] ]` (one item, itself
// a sequence) — that is the unquoted *scalar* form, not a list. Keep it scalar
// so it round-trips to the inline `field: [[x]]` rather than a one-item block
// list. `links_in_field_value` reads it back as a scalar link either way.
if items.len() == 1 && unquoted_inline_link(&items[0]).is_some() {
return None;
}
// Every item must resolve to exactly one clean wiki-link, in any of the flow
// spellings an agent types (see [`link_from_flow_list_item`]).
let mut links = Vec::with_capacity(items.len());
for item in &items {
links.push(link_from_flow_list_item(item)?);
}
if links.is_empty() {
return None;
}
// Normalize to a block sequence of quoted-link strings — the form `to_yaml`
// renders block-style and `links_in_field_value` accepts. `|display` is
// preserved.
let normalized = links
.iter()
.map(|l| Value::String(wiki_link_literal(l)))
.collect();
Some(Value::Sequence(normalized))
}
/// Recognize one clean wiki-link from a single **item** of a YAML flow sequence,
/// across the spellings an agent types for a list. After top-level flow parsing,
/// a list item arrives in one of:
///
/// - quoted — `"[[x]]"` ⇒ `String("[[x]]")`
/// - unquoted in a flow list — `[[x]]` inside `[…]` ⇒ `Seq[ Seq[String(x)] ]`
/// (one level deeper than a bare unquoted scalar, because the surrounding list
/// adds a wrapper); unwrap the single-element wrapper, then read the inline
/// `Seq[String(x)]` with [`unquoted_inline_link`].
///
/// Returns `None` for any item that is not exactly one clean wiki-link, so the
/// caller falls back to a scalar string and never fabricates a partial list.
fn link_from_flow_list_item(item: &Value) -> Option<WikiLink> {
match item {
Value::String(s) => parse_wiki_link_str(s),
Value::Sequence(inner) => {
// Unquoted list item `[[x]]` → `Seq[ Seq[String(x)] ]`: peel the lone
// wrapper to expose the inline-link shape `Seq[String(x)]`.
//
// Only this triple-nested shape is a wiki-link. We deliberately do
// NOT fall back to `unquoted_inline_link(item)` on the bare double
// nesting `Seq[String(x)]` (a plain one-element string list `[x]`):
// that fallback fabricated a wiki-link out of an ordinary nested
// string list — `groups: [[alpha], [beta]]` (data `[["alpha"],
// ["beta"]]`) was rewritten to `- '[[alpha]]'` / `- '[[beta]]'`,
// silently changing the field's type and manufacturing short-form
// links the tool then flags as `WIKI_LINK_SHORT_FORM`. An unknown
// nested string list must pass through verbatim (SPEC § "Unknown
// fields pass through").
if inner.len() == 1 {
if let Some(link) = unquoted_inline_link(&inner[0]) {
return Some(link);
}
}
None
}
_ => None,
}
}
/// A target is a full store-relative path when its first path segment is one of
/// the three canonical layer dirs and at least one `/` separator follows. A
/// trailing `.md` does not affect this classification.
fn target_is_full_path(target: &str) -> bool {
let target = target.trim();
match target.split_once('/') {
Some((head, _rest)) => LAYER_DIRS.contains(&head),
None => false,
}
}
/// True when the target carries a trailing `.md` extension (validate warns
/// `WIKI_LINK_HAS_EXTENSION`).
fn target_has_md_extension(target: &str) -> bool {
target.trim().ends_with(".md")
}
/// 1-based character (Unicode scalar) column of `byte_offset` within `line`.
fn char_column(line: &str, byte_offset: usize) -> u32 {
(line[..byte_offset].chars().count() as u32) + 1
}
/// Index of the first comma-token in `raw[from..]` that *starts a greedy
/// modifier clause* (`enum`, `enum:…`, or `default …`), or `raw.len()` when none
/// remain. Used to bound a greedy `default`/`enum` value so it stops at the next
/// such clause instead of either truncating at the first comma or swallowing a
/// following greedy clause whole.
fn next_greedy_clause(raw: &[&str], from: usize) -> usize {
let mut j = from;
while j < raw.len() {
let lower = raw[j].trim().to_ascii_lowercase();
if lower == "enum" || lower.starts_with("enum:") || lower.starts_with("default ") {
return j;
}
j += 1;
}
raw.len()
}
/// Map a lowercase shape keyword to its [`Shape`].
fn shape_from_str(s: &str) -> Option<Shape> {
match s {
"string" => Some(Shape::String),
"int" => Some(Shape::Int),
"bool" => Some(Shape::Bool),
"date" => Some(Shape::Date),
"email" => Some(Shape::Email),
"currency" => Some(Shape::Currency),
"url" => Some(Shape::Url),
_ => None,
}
}
/// The ATX heading level of a line (number of leading `#`), or 0 if not a
/// heading. Up to three leading spaces (CommonMark), requires a space/tab (or
/// end-of-line) after the `#` run, caps the run at six.
fn heading_level(line: &str) -> u8 {
let indent = line.len() - line.trim_start_matches(' ').len();
if indent > 3 {
return 0;
}
let rest = &line[indent..];
let hashes = rest.len() - rest.trim_start_matches('#').len();
if hashes == 0 || hashes > 6 {
return 0;
}
let after = &rest[hashes..];
if after.is_empty() || after.starts_with(' ') || after.starts_with('\t') {
hashes as u8
} else {
0
}
}
/// The heading text after the `#` run, trimmed, with a trailing ATX *closing*
/// `#` sequence removed per CommonMark (`## Title ##` → `Title`).
///
/// CommonMark only treats a trailing run of `#` as a closing sequence when it is
/// **preceded by a space or tab** (or the content is empty). A `#` that abuts the
/// preceding word is literal heading text: `## C#` → `C#`, `## F#` → `F#`,
/// `## issue-123#` → `issue-123#`. The old unconditional `trim_end_matches('#')`
/// stripped those, corrupting `dbmd sections`/`outline` heading text and — via
/// `parse_db_md` using the heading verbatim as the schema type key — silently
/// binding a `### c#` schema to `type: c` instead of `type: c#`.
fn heading_text(line: &str, level: u8) -> String {
let indent = line.len() - line.trim_start_matches(' ').len();
let after_hashes = &line[indent + level as usize..];
let trimmed = after_hashes.trim();
// Peel a trailing run of `#`. It is a closing sequence only if what precedes
// it (within `trimmed`) is empty or ends in a space/tab; otherwise the `#`s
// are literal content.
let without_hashes = trimmed.trim_end_matches('#');
if without_hashes.len() == trimmed.len() {
// No trailing `#` at all.
return trimmed.to_string();
}
if without_hashes.is_empty() || without_hashes.ends_with([' ', '\t']) {
// A genuine closing sequence (`## Title ##`, `## ##`): drop it and the
// whitespace before it.
without_hashes.trim_end().to_string()
} else {
// The `#` run abuts content (`## C#`): keep it as literal heading text.
trimmed.to_string()
}
}
/// If `line` opens a fenced code block, return `(fence byte, run length)`.
fn opening_fence(line: &str) -> Option<(u8, usize)> {
let indent = line.len() - line.trim_start_matches(' ').len();
if indent > 3 {
return None;
}
let rest = &line[indent..];
let byte = rest.bytes().next()?;
if byte != b'`' && byte != b'~' {
return None;
}
let run = rest.len() - rest.trim_start_matches(byte as char).len();
if run < 3 {
return None;
}
// A backtick fence's info string may not itself contain a backtick.
if byte == b'`' && rest[run..].contains('`') {
return None;
}
Some((byte, run))
}
/// True if `line` closes the currently open fence: same char, run at least as
/// long, nothing but trailing whitespace after.
fn is_closing_fence(line: &str, fence: (u8, usize)) -> bool {
let (byte, open_len) = fence;
let indent = line.len() - line.trim_start_matches(' ').len();
if indent > 3 {
return false;
}
let rest = &line[indent..];
let run = rest.len() - rest.trim_start_matches(byte as char).len();
if run < open_len {
return false;
}
rest[run..].trim().is_empty()
}
/// The prose body of a section: everything after the heading line, trimmed.
fn section_prose(section_body: &str) -> String {
match section_body.split_once('\n') {
Some((_heading, rest)) => rest.trim().to_string(),
None => String::new(),
}
}
/// The bullet lines (`-`/`*`/`+`) of a section body, excluding the heading
/// line, each returned with its leading whitespace trimmed.
fn bullet_lines(section_body: &str) -> Vec<String> {
section_body
.lines()
.skip(1) // the heading line
.map(str::trim)
.filter(|l| l.starts_with("- ") || l.starts_with("* ") || l.starts_with("+ "))
.map(|l| l.to_string())
.collect()
}
/// Cut a bullet's content at the first comment separator, returning only the
/// meaningful prefix. Recognizes the em-dash (` — `), en-dash (` – `), double-
/// hyphen (` -- `), and the plain single-ASCII-hyphen (` - `) spellings an
/// operator naturally types — without the single-hyphen form, a comment like
/// `records/decisions/q3.md - finalized` left the whole line (comment included)
/// as the frozen path, so the entry never matched and the freeze failed OPEN.
/// A store-relative path never contains a ` - ` (paths are `/`-joined, spaceless),
/// so this does not truncate legitimate path text.
fn strip_bullet_comment(content: &str) -> &str {
let mut cut = content.len();
for sep in [" — ", " -- ", " – ", " - "] {
if let Some(idx) = content.find(sep) {
cut = cut.min(idx);
}
}
content[..cut].trim()
}
/// Strip the leading bullet marker, returning the trimmed content after it.
fn bullet_content(bullet: &str) -> &str {
let t = bullet.trim();
t.strip_prefix("- ")
.or_else(|| t.strip_prefix("* "))
.or_else(|| t.strip_prefix("+ "))
.unwrap_or(t)
.trim()
}
/// Extract a store-relative path from a Frozen-pages bullet. The path may be
/// wrapped in backticks and followed by an em-dash comment.
fn extract_path_bullet(bullet: &str) -> String {
let content = bullet_content(bullet);
// Prefer a backtick-delimited span if present.
if let Some(start) = content.find('`') {
if let Some(end_rel) = content[start + 1..].find('`') {
return content[start + 1..start + 1 + end_rel].trim().to_string();
}
}
// Otherwise take the text up to a comment separator, stripping quotes.
strip_bullet_comment(content)
.trim_matches('"')
.trim_matches('\'')
.trim()
.to_string()
}
/// Extract a comma-separated type list from an Ignored-types bullet, stripping
/// backticks/quotes and any trailing em-dash comment.
fn extract_type_list_bullet(bullet: &str) -> Vec<String> {
let content = strip_bullet_comment(bullet_content(bullet));
content
.split(',')
.map(|t| {
t.trim()
.trim_matches('`')
.trim_matches('"')
.trim_matches('\'')
.trim()
.to_string()
})
.filter(|t| !t.is_empty())
.collect()
}
#[cfg(test)]
mod tests {
use super::*;
use std::path::Path;
use tempfile::tempdir;
// ── Config::frozen_match (the single write-surface policy matcher) ───────
#[test]
fn frozen_match_is_md_insensitive_both_directions() {
// A policy entry stored WITHOUT `.md` (the natural extensionless
// spelling `parse_db_md` keeps verbatim) must still match a `.md`
// write target — the regression every write surface had.
let cfg = Config {
frozen_pages: vec![PathBuf::from("records/decisions/q1")],
..Config::default()
};
assert_eq!(
cfg.frozen_match(Path::new("records/decisions/q1.md")),
Some(PathBuf::from("records/decisions/q1")),
"extensionless policy entry must freeze the .md file"
);
assert!(cfg.is_frozen(Path::new("records/decisions/q1.md")));
// The symmetric case: a policy entry WITH `.md` matches a bare target.
let cfg = Config {
frozen_pages: vec![PathBuf::from("records/decisions/q1.md")],
..Config::default()
};
assert_eq!(
cfg.frozen_match(Path::new("records/decisions/q1")),
Some(PathBuf::from("records/decisions/q1.md")),
);
// And the same-spelling cases still match.
assert!(cfg.is_frozen(Path::new("records/decisions/q1.md")));
}
#[test]
fn frozen_match_drops_leading_dot_slash() {
let cfg = Config {
frozen_pages: vec![PathBuf::from("records/decisions/q1.md")],
..Config::default()
};
assert!(cfg.is_frozen(Path::new("./records/decisions/q1.md")));
assert!(cfg.is_frozen(Path::new("./records/decisions/q1")));
}
#[test]
fn frozen_match_returns_none_for_unlisted_and_prefix_paths() {
let cfg = Config {
frozen_pages: vec![PathBuf::from("records/decisions/q1")],
..Config::default()
};
assert!(cfg
.frozen_match(Path::new("records/decisions/q2.md"))
.is_none());
// A prefix is not a match: `q1` must not freeze `q1-draft`.
assert!(cfg
.frozen_match(Path::new("records/decisions/q1-draft.md"))
.is_none());
assert!(!cfg.is_frozen(Path::new("records/decisions/q11.md")));
}
// ── split_frontmatter ───────────────────────────────────────────────────
#[test]
fn split_frontmatter_separates_yaml_and_verbatim_body() {
let text = "---\ntype: contact\nsummary: x\n---\n# Heading\n\nBody line.\n";
let p = split_frontmatter(text, Path::new("f.md")).unwrap();
assert_eq!(p.frontmatter_yaml, "type: contact\nsummary: x\n");
// Body is everything after the closing fence's newline, byte-for-byte.
assert_eq!(p.body, "# Heading\n\nBody line.\n");
}
#[test]
fn split_frontmatter_preserves_body_without_trailing_newline() {
let text = "---\ntype: x\n---\nno trailing newline";
let p = split_frontmatter(text, Path::new("f.md")).unwrap();
assert_eq!(p.body, "no trailing newline");
}
#[test]
fn split_frontmatter_empty_body_when_nothing_after_fence() {
let text = "---\ntype: x\n---\n";
let p = split_frontmatter(text, Path::new("f.md")).unwrap();
assert_eq!(p.body, "");
}
#[test]
fn split_frontmatter_missing_opening_fence_errors() {
let text = "# No frontmatter here\ntype: x\n";
let err = split_frontmatter(text, Path::new("f.md")).unwrap_err();
assert!(matches!(err, ParseError::MissingFrontmatter { .. }));
}
#[test]
fn split_frontmatter_leading_content_before_fence_rejected() {
// The opening fence must be the very first line; a blank line first is
// not allowed.
let text = "\n---\ntype: x\n---\nbody";
let err = split_frontmatter(text, Path::new("f.md")).unwrap_err();
assert!(matches!(err, ParseError::MissingFrontmatter { .. }));
}
#[test]
fn split_frontmatter_unterminated_block_errors() {
let text = "---\ntype: x\nsummary: y\n";
let err = split_frontmatter(text, Path::new("f.md")).unwrap_err();
assert!(matches!(err, ParseError::MissingFrontmatter { .. }));
}
// ── Frontmatter::parse ───────────────────────────────────────────────────
#[test]
fn parse_populates_typed_fields_and_routes_unknowns_to_extra() {
let yaml = "type: contact\nid: sarah-chen\nsummary: Director of Ops\nstatus: active\ntags: [vip, renewal]\nemail: sarah@northstar.io\nrole: Director";
let fm = Frontmatter::parse(yaml, Path::new("f.md")).unwrap();
assert_eq!(fm.type_.as_deref(), Some("contact"));
assert_eq!(fm.id.as_deref(), Some("sarah-chen"));
assert_eq!(fm.summary.as_deref(), Some("Director of Ops"));
assert_eq!(fm.status.as_deref(), Some("active"));
assert_eq!(fm.tags, vec!["vip".to_string(), "renewal".to_string()]);
// Type-specific fields are NOT promoted to typed slots.
assert!(fm.type_.is_some() && !fm.extra.contains_key("type"));
assert!(!fm.extra.contains_key("tags"));
assert_eq!(
fm.extra.get("email").and_then(|v| v.as_str()),
Some("sarah@northstar.io")
);
assert_eq!(
fm.extra.get("role").and_then(|v| v.as_str()),
Some("Director")
);
}
#[test]
fn parse_reads_rfc3339_timestamps() {
let yaml =
"type: email\ncreated: 2026-05-27T08:00:00-07:00\nupdated: 2026-05-28T09:30:00-07:00";
let fm = Frontmatter::parse(yaml, Path::new("f.md")).unwrap();
let created = fm.created.expect("created parsed");
// -07:00 offset is 7 * 3600 seconds west.
assert_eq!(created.offset().utc_minus_local(), 7 * 3600);
assert_eq!(created.to_rfc3339(), "2026-05-27T08:00:00-07:00");
assert!(fm.updated.is_some());
}
#[test]
fn parse_rejects_non_rfc3339_timestamp() {
// A date-only value is not a full RFC3339 timestamp; created/updated
// require the full form.
let yaml = "type: email\ncreated: 2026-05-27";
let err = Frontmatter::parse(yaml, Path::new("bad.md")).unwrap_err();
match err {
ParseError::BadTimestamp { key, value, .. } => {
assert_eq!(key, "created");
assert_eq!(value, "2026-05-27");
}
other => panic!("expected BadTimestamp, got {other:?}"),
}
}
#[test]
fn parse_malformed_yaml_errors() {
// Unclosed flow mapping is invalid YAML.
let yaml = "type: contact\n bad: : :\n- nope";
let err = Frontmatter::parse(yaml, Path::new("bad.md")).unwrap_err();
assert!(matches!(err, ParseError::MalformedYaml { .. }));
}
#[test]
fn frontmatter_with_yaml_tag_on_mapping_does_not_panic() {
// Regression: a YAML tag on the top-level mapping made the old
// `expect_err` path PANIC, because a tagged mapping deserializes to a
// `Mapping` just fine. It must now be handled — accepted as the inner
// mapping, never a panic.
let fm = Frontmatter::parse("!mytag\ntype: contact\nsummary: hi\n", Path::new("x.md"))
.expect("tagged-mapping frontmatter must parse, not panic");
assert_eq!(fm.type_.as_deref(), Some("contact"));
// A genuine scalar/sequence top level is still malformed (and still
// doesn't panic).
assert!(Frontmatter::parse("- a\n- b\n", Path::new("x.md")).is_err());
}
#[test]
fn parse_empty_block_is_empty_frontmatter() {
let fm = Frontmatter::parse("", Path::new("f.md")).unwrap();
assert_eq!(fm, Frontmatter::default());
}
#[test]
fn parse_scalar_top_level_is_malformed() {
// A bare scalar at the top level is not a frontmatter mapping.
let err = Frontmatter::parse("just a string", Path::new("f.md")).unwrap_err();
assert!(matches!(err, ParseError::MalformedYaml { .. }));
}
// ── to_yaml canonical order ──────────────────────────────────────────────
#[test]
fn to_yaml_emits_canonical_key_order() {
let mut fm = Frontmatter {
type_: Some("contact".into()),
id: Some("sarah-chen".into()),
summary: Some("Director of Ops".into()),
status: Some("active".into()),
tags: vec!["vip".into()],
created: Some(DateTime::parse_from_rfc3339("2026-05-27T08:00:00-07:00").unwrap()),
updated: Some(DateTime::parse_from_rfc3339("2026-05-28T09:30:00-07:00").unwrap()),
..Default::default()
};
// Two type-specific fields, inserted in NON-alphabetical order to prove
// the writer sorts them (BTreeMap) between the universal head and tail.
fm.extra
.insert("role".into(), Value::String("Director".into()));
fm.extra.insert(
"company".into(),
Value::String("[[records/companies/northstar]]".into()),
);
let yaml = fm.to_yaml();
let keys: Vec<&str> = yaml
.lines()
.filter(|l| !l.starts_with(['-', ' ']) && l.contains(':'))
.map(|l| l.split(':').next().unwrap())
.collect();
assert_eq!(
keys,
vec![
"type", "id", "created", "updated", "summary", // universal head
"company", "role", // type-specific, sorted
"status", // universal tail
"tags",
],
"canonical order violated; got:\n{yaml}"
);
// Timestamps round-trip as RFC3339 strings (YAML may quote them).
assert!(
yaml.contains("2026-05-27T08:00:00-07:00"),
"created timestamp missing; got:\n{yaml}"
);
// The value re-parses to the same instant regardless of quoting.
let reparsed = Frontmatter::parse(&yaml, Path::new("rt.md")).unwrap();
assert_eq!(reparsed.created, fm.created);
assert_eq!(reparsed.updated, fm.updated);
}
#[test]
fn to_yaml_omits_absent_optional_fields() {
let fm = Frontmatter {
type_: Some("note".into()),
..Default::default()
};
let yaml = fm.to_yaml();
assert!(yaml.contains("type: note"));
assert!(!yaml.contains("status"));
assert!(!yaml.contains("tags"));
assert!(!yaml.contains("summary"));
}
// ── Regression: non-string scalar universal fields round-trip (finding #1) ─
#[test]
fn regression_parse_preserves_non_string_scalar_universal_fields() {
// A hand/externally-authored file whose universal fields are bare
// scalars YAML reads as Number/Bool — `id: 100`, `summary: 2026`,
// `status: 0`, `type: 42` — must be PRESERVED as their string form, not
// read as None. Before the fix, `v.as_str()` returned None for these and
// the matched arm discarded the value entirely (never reaching `extra`).
let yaml = "type: 42\nid: 100\nsummary: 2026\nstatus: 0";
let fm = Frontmatter::parse(yaml, Path::new("x.md")).unwrap();
assert_eq!(fm.type_.as_deref(), Some("42"), "type scalar dropped");
assert_eq!(fm.id.as_deref(), Some("100"), "id scalar dropped");
assert_eq!(
fm.summary.as_deref(),
Some("2026"),
"summary scalar dropped"
);
assert_eq!(fm.status.as_deref(), Some("0"), "status scalar dropped");
// The values must surface through the public `get` accessor too.
assert_eq!(
fm.get("summary")
.and_then(|v| v.as_str().map(str::to_string)),
Some("2026".to_string())
);
}
#[test]
fn regression_format_round_trip_does_not_delete_numeric_frontmatter() {
// The exact finding-#1 trigger: `dbmd format` is read_file -> write_file.
// A file whose `id`/`summary`/`status` are bare numeric scalars must
// still carry those fields after the canonical re-emit. Before the fix,
// the lines were silently deleted from disk (only `type` survived).
let dir = tempdir().unwrap();
let path = dir.path().join("x.md");
let original = "---\ntype: contact\nid: 100\nsummary: 2026\nstatus: 0\n---\nbody\n";
std::fs::write(&path, original).unwrap();
// Re-emit through the canonical writer, exactly as `dbmd format` does.
let (fm, body) = read_file(&path).unwrap();
write_file(&path, &fm, &body).unwrap();
let after = std::fs::read_to_string(&path).unwrap();
// None of the four fields may vanish; they survive as string scalars.
let reparsed = Frontmatter::parse(
&split_frontmatter(&after, &path).unwrap().frontmatter_yaml,
&path,
)
.unwrap();
assert_eq!(reparsed.type_.as_deref(), Some("contact"));
assert_eq!(reparsed.id.as_deref(), Some("100"), "id deleted by format");
assert_eq!(
reparsed.summary.as_deref(),
Some("2026"),
"summary deleted by format"
);
assert_eq!(
reparsed.status.as_deref(),
Some("0"),
"status deleted by format"
);
// The body is preserved verbatim.
assert_eq!(body, "body\n");
}
// ── Regression: BOM-prefixed files parse like store/index (finding #19) ────
#[test]
fn regression_split_frontmatter_tolerates_leading_utf8_bom() {
// A BOM-prefixed file (EF BB BF + `---\n...`) is walked and indexed by
// `dbmd index` (store/index strip the BOM) but, before the fix, every
// write/edit surface routed through `read_file` hard-failed with
// MissingFrontmatter. `split_frontmatter` must now strip a single leading
// U+FEFF and emit a BOM-free body.
let text = "\u{feff}---\ntype: note\nsummary: x\n---\nbody\n";
let parsed = split_frontmatter(text, Path::new("note.md")).unwrap();
assert_eq!(parsed.frontmatter_yaml, "type: note\nsummary: x\n");
// Body never carries the BOM forward into the canonical writer.
assert_eq!(parsed.body, "body\n");
assert!(!parsed.body.starts_with('\u{feff}'));
}
#[test]
fn regression_read_file_parses_bom_prefixed_file() {
// End-to-end through the same `read_file` path `dbmd fm get/set`,
// `format`, `link`, and `write` use. Before the fix this returned
// Err(MissingFrontmatter) on a file the catalog had already indexed.
let dir = tempdir().unwrap();
let path = dir.path().join("note.md");
std::fs::write(&path, "\u{feff}---\ntype: note\nsummary: x\n---\nbody\n").unwrap();
let (fm, body) = read_file(&path).expect("BOM-prefixed file must parse");
assert_eq!(fm.type_.as_deref(), Some("note"));
assert_eq!(fm.summary.as_deref(), Some("x"));
assert_eq!(body, "body\n");
}
#[test]
fn to_yaml_preserves_unquoted_scalar_wiki_link_round_trip() {
// Regression (PRIMARY): the SPEC-canonical scalar wiki-link is the
// *unquoted* inline `company: [[records/companies/northstar]]`
// (SPEC § Linking, the worked `contact` example). YAML parses it to the
// nested `Seq[Seq[String]]` shape and `parse` stores that verbatim in
// `extra`. Before the fix, `to_yaml` re-emitted it block-style as
// company:
// - - records/companies/northstar
// — the `[[ ]]` brackets GONE — so a no-op re-emit (`dbmd format`, and
// any `fm set` / `link` write) silently destroyed the link.
let yaml = "type: contact\ncompany: [[records/companies/northstar]]";
let fm = Frontmatter::parse(yaml, Path::new("c.md")).unwrap();
// Sanity: it really parsed as the nested sequence, not a string.
assert!(fm.extra.get("company").and_then(|v| v.as_str()).is_none());
let out = fm.to_yaml();
// The link must survive as a quoted inline scalar — brackets intact, and
// never the bracket-less block sequence `- - records/...`.
assert!(
out.contains("[[records/companies/northstar]]"),
"canonical writer dropped the wiki-link brackets; got:\n{out}"
);
assert!(
!out.contains("- - "),
"canonical writer emitted a nested block sequence (link corrupted); got:\n{out}"
);
// And it round-trips: re-parsing the emitted YAML still surfaces exactly
// one link with the right target (the edge graph/backlinks rely on).
let reparsed = Frontmatter::parse(&out, Path::new("c.md")).unwrap();
let fields = reparsed.link_fields();
let links: Vec<(&str, &str, Option<&str>)> = fields
.iter()
.map(|(k, l)| (k.as_str(), l.target.as_str(), l.display.as_deref()))
.collect();
assert_eq!(
links,
vec![("company", "records/companies/northstar", None)]
);
// A second re-emit is a fixed point — no progressive corruption across
// repeated curator-loop writes.
assert_eq!(
reparsed.to_yaml(),
out,
"to_yaml is not idempotent on links"
);
}
#[test]
fn to_yaml_preserves_unquoted_scalar_link_with_display() {
// The `|display` segment must survive the unquoted-inline round-trip too.
let yaml = "type: contact\ncompany: [[records/companies/northstar|Northstar]]";
let fm = Frontmatter::parse(yaml, Path::new("c.md")).unwrap();
let out = fm.to_yaml();
assert!(
out.contains("[[records/companies/northstar|Northstar]]"),
"display segment lost on round-trip; got:\n{out}"
);
let reparsed = Frontmatter::parse(&out, Path::new("c.md")).unwrap();
let f = reparsed.link_fields();
assert_eq!(f.len(), 1);
assert_eq!(f[0].1.target, "records/companies/northstar");
assert_eq!(f[0].1.display.as_deref(), Some("Northstar"));
}
#[test]
fn to_yaml_does_not_mangle_link_list_or_plain_nested_sequence() {
// A genuine quoted block list of links round-trips as a clean string
// list — never collapsed to a scalar — and a plain nested sequence that
// is NOT a wiki-link is left exactly as written (no false conversion).
let yaml = "type: meeting\nattendees:\n - \"[[records/contacts/elena]]\"\n - \"[[records/contacts/sarah]]\"\nmatrix:\n - - 1\n - 2";
let fm = Frontmatter::parse(yaml, Path::new("m.md")).unwrap();
let out = fm.to_yaml();
// Both attendee links survive as quoted strings.
assert!(out.contains("[[records/contacts/elena]]"), "got:\n{out}");
assert!(out.contains("[[records/contacts/sarah]]"), "got:\n{out}");
let reparsed = Frontmatter::parse(&out, Path::new("m.md")).unwrap();
let fields = reparsed.link_fields();
let attendees: Vec<&str> = fields
.iter()
.filter(|(k, _)| k == "attendees")
.map(|(_, l)| l.target.as_str())
.collect();
assert_eq!(
attendees,
vec!["records/contacts/elena", "records/contacts/sarah"]
);
// The non-link nested sequence is preserved verbatim, not touched.
assert_eq!(reparsed.extra.get("matrix"), fm.extra.get("matrix"));
}
// ── read_file / write_file round-trip ────────────────────────────────────
#[test]
fn write_then_read_roundtrips_and_preserves_body_verbatim() {
let dir = tempdir().unwrap();
let path = dir.path().join("sources/emails/x.md");
let body = "# Subject\n\nHello,\n\nSee [[records/contacts/sarah-chen]].\n";
let mut fm = Frontmatter {
type_: Some("email".into()),
summary: Some("renewal note".into()),
created: Some(DateTime::parse_from_rfc3339("2026-05-27T08:00:00-07:00").unwrap()),
..Default::default()
};
fm.extra
.insert("from".into(), Value::String("elena@northstar.io".into()));
write_file(&path, &fm, body).unwrap();
let (read_fm, read_body) = read_file(&path).unwrap();
assert_eq!(read_body, body, "body must be preserved byte-for-byte");
assert_eq!(read_fm.type_.as_deref(), Some("email"));
assert_eq!(read_fm.summary.as_deref(), Some("renewal note"));
assert_eq!(
read_fm.extra.get("from").and_then(|v| v.as_str()),
Some("elena@northstar.io")
);
// The on-disk file starts with a fence and ends with the verbatim body.
let raw = std::fs::read_to_string(&path).unwrap();
assert!(raw.starts_with("---\n"));
assert!(raw.ends_with(body));
}
#[test]
fn roundtrip_modify_summary_then_write_changes_only_summary() {
let dir = tempdir().unwrap();
let path = dir.path().join("records/contacts/sarah.md");
let body = "Long-form operator notes about Sarah.\n";
let fm = Frontmatter {
type_: Some("contact".into()),
summary: Some("old summary".into()),
..Default::default()
};
write_file(&path, &fm, body).unwrap();
// Read → modify summary → write back.
let (mut fm2, body2) = read_file(&path).unwrap();
fm2.summary = Some("new summary".into());
write_file(&path, &fm2, &body2).unwrap();
let (fm3, body3) = read_file(&path).unwrap();
assert_eq!(fm3.summary.as_deref(), Some("new summary"));
assert_eq!(fm3.type_.as_deref(), Some("contact"));
assert_eq!(body3, body, "body unchanged across the round-trip");
}
#[test]
fn roundtrip_preserves_handwritten_unquoted_scalar_wiki_link_on_disk() {
// End-to-end analog of `dbmd format` on the verbatim SPEC worked example:
// a hand-written file carrying the canonical UNQUOTED scalar link
// `company: [[records/companies/northstar]]`, read from disk then written
// back unchanged. Before the fix this no-op re-emit rewrote the on-disk
// value to the bracket-less block sequence `company:\n- - records/...`,
// and every reader (validate/graph/backlinks) then lost the edge.
let dir = tempdir().unwrap();
let path = dir.path().join("records/contacts/sarah-chen.md");
let file = "---\ntype: contact\nid: sarah-chen\nsummary: Director of Ops\ncompany: [[records/companies/northstar]]\n---\n# Sarah Chen\n\nNotes.\n";
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::fs::write(&path, file).unwrap();
// Read → write back unchanged (the canonical no-op re-emit).
let (fm, body) = read_file(&path).unwrap();
write_file(&path, &fm, &body).unwrap();
// On-disk bytes still carry the bracketed link, never `- - records/...`.
let raw = std::fs::read_to_string(&path).unwrap();
assert!(
raw.contains("[[records/companies/northstar]]"),
"on-disk wiki-link brackets were destroyed; got:\n{raw}"
);
assert!(
!raw.contains("- - "),
"on-disk value became a nested block sequence; got:\n{raw}"
);
// And the edge is still readable after the round-trip.
let (fm2, _) = read_file(&path).unwrap();
let fields = fm2.link_fields();
let links: Vec<(&str, &str)> = fields
.iter()
.map(|(k, l)| (k.as_str(), l.target.as_str()))
.collect();
assert_eq!(links, vec![("company", "records/companies/northstar")]);
}
#[test]
fn write_file_does_not_leave_temp_files_behind() {
let dir = tempdir().unwrap();
let path = dir.path().join("records/x.md");
let fm = Frontmatter {
type_: Some("note".into()),
..Default::default()
};
write_file(&path, &fm, "body\n").unwrap();
// The directory should contain only the target file, no `.x.md.tmp.*`.
let entries: Vec<String> = std::fs::read_dir(path.parent().unwrap())
.unwrap()
.map(|e| e.unwrap().file_name().to_string_lossy().into_owned())
.collect();
assert_eq!(entries, vec!["x.md".to_string()]);
}
// ── is_content_file ──────────────────────────────────────────────────────
#[test]
fn is_content_file_recognizes_layers_and_excludes_meta() {
assert!(Frontmatter::is_content_file(Path::new(
"sources/emails/2026-05-22.md"
)));
assert!(Frontmatter::is_content_file(Path::new(
"records/contacts/sarah-chen.md"
)));
// A synthesis profile the agent authored lives under `records/` (the
// old `wiki/` layer is gone, so a `wiki/...` path is NOT content).
assert!(Frontmatter::is_content_file(Path::new(
"records/profiles/sarah-chen.md"
)));
assert!(!Frontmatter::is_content_file(Path::new(
"wiki/people/sarah-chen.md"
)));
// Absolute paths under a layer are still content.
assert!(Frontmatter::is_content_file(Path::new(
"/home/db/records/companies/northstar.md"
)));
// index.md at any level is meta.
assert!(!Frontmatter::is_content_file(Path::new(
"records/contacts/index.md"
)));
assert!(!Frontmatter::is_content_file(Path::new("index.md")));
// Root meta files.
assert!(!Frontmatter::is_content_file(Path::new("DB.md")));
assert!(!Frontmatter::is_content_file(Path::new("log.md")));
}
// ── effective_id ─────────────────────────────────────────────────────────
#[test]
fn effective_id_prefers_explicit_then_derives_from_path() {
let with_id = Frontmatter {
id: Some("explicit-id".into()),
..Default::default()
};
assert_eq!(
with_id.effective_id(Path::new("wiki/people/sarah-chen.md")),
"explicit-id"
);
let no_id = Frontmatter::default();
assert_eq!(
no_id.effective_id(Path::new("wiki/people/sarah-chen.md")),
"sarah-chen"
);
}
// ── get / set ────────────────────────────────────────────────────────────
#[test]
fn set_routes_universal_and_custom_keys() {
let mut fm = Frontmatter::default();
fm.set("type", "contact").unwrap();
fm.set("summary", "hi").unwrap();
fm.set("company", "[[records/companies/northstar]]")
.unwrap();
assert_eq!(fm.type_.as_deref(), Some("contact"));
assert_eq!(fm.summary.as_deref(), Some("hi"));
// Custom key landed in extra, not a typed slot.
assert_eq!(
fm.extra.get("company").and_then(|v| v.as_str()),
Some("[[records/companies/northstar]]")
);
// get reads from both typed fields and extra.
assert_eq!(
fm.get("type").and_then(|v| v.as_str().map(String::from)),
Some("contact".into())
);
assert_eq!(
fm.get("company").and_then(|v| v.as_str().map(String::from)),
Some("[[records/companies/northstar]]".into())
);
assert!(fm.get("nonexistent").is_none());
}
#[test]
fn set_timestamp_validates_rfc3339() {
let mut fm = Frontmatter::default();
fm.set("created", "2026-05-27T08:00:00-07:00").unwrap();
assert!(fm.created.is_some());
let err = fm.set("updated", "not-a-date").unwrap_err();
assert!(matches!(err, ParseError::BadTimestamp { .. }));
}
// ── extract_wiki_links ───────────────────────────────────────────────────
#[test]
fn extract_wiki_links_flags_full_path_short_form_and_extension() {
let body = "See [[records/contacts/sarah-chen]] and [[sarah-chen]].\nAlso [[records/profiles/sarah-chen.md|Sarah]].\n";
let links = extract_wiki_links(body, Path::new("doc.md"));
assert_eq!(links.len(), 3);
// Full path, no extension, no display.
assert_eq!(links[0].target, "records/contacts/sarah-chen");
assert!(links[0].is_full_path);
assert!(!links[0].has_md_extension);
assert_eq!(links[0].display, None);
assert_eq!(links[0].location.1, 1, "first link on line 1");
// Short form: not a full path.
assert_eq!(links[1].target, "sarah-chen");
assert!(!links[1].is_full_path, "bare target is short-form");
// Full path WITH .md extension and a display override on line 2.
assert_eq!(links[2].target, "records/profiles/sarah-chen.md");
assert!(links[2].is_full_path);
assert!(links[2].has_md_extension);
assert_eq!(links[2].display.as_deref(), Some("Sarah"));
assert_eq!(links[2].location.1, 2);
}
#[test]
fn extract_wiki_links_reports_1_based_column_counting_chars() {
// A multi-byte prefix (é is 2 bytes) must not skew the char column.
let body = "café [[records/x/y]]";
let links = extract_wiki_links(body, Path::new("d.md"));
assert_eq!(links.len(), 1);
// "café " is 5 chars, so the `[[` starts at char column 6 (1-based).
assert_eq!(links[0].location.2, 6);
}
#[test]
fn extract_wiki_links_ignores_a_lone_path_without_brackets() {
let links = extract_wiki_links(
"records/contacts/sarah-chen is not a link",
Path::new("d.md"),
);
assert!(links.is_empty());
}
// ── extract_markdown_links ───────────────────────────────────────────────
#[test]
fn extract_markdown_links_captures_external_and_not_wiki_links() {
let body =
"See [the thread](https://x.com/a) and [[records/contacts/sarah-chen]] internally.\n";
let md = extract_markdown_links(body, Path::new("d.md"));
assert_eq!(
md.len(),
1,
"wiki-link must not be captured as a markdown link"
);
assert_eq!(md[0].text, "the thread");
assert_eq!(md[0].url, "https://x.com/a");
assert_eq!(md[0].location.1, 1);
// And the wiki-link extractor must not pick up the markdown link.
let wl = extract_wiki_links(body, Path::new("d.md"));
assert_eq!(wl.len(), 1);
assert_eq!(wl[0].target, "records/contacts/sarah-chen");
}
// ── link_fields ──────────────────────────────────────────────────────────
#[test]
fn link_fields_extracts_scalar_list_and_summary_links() {
// The canonical list form quotes each item so YAML parses it as clean
// strings; a scalar field may be quoted OR written in the canonical
// unquoted inline form `company: [[x]]` (SPEC § Linking).
let yaml = "type: meeting\nsummary: with [[records/contacts/elena]]\ncompany: \"[[records/companies/northstar]]\"\nattendees:\n - \"[[records/contacts/elena]]\"\n - \"[[records/contacts/sarah]]\"\nnotes: just plain text";
let fm = Frontmatter::parse(yaml, Path::new("m.md")).unwrap();
// Sanity: company really did parse as a scalar string here.
assert!(fm.extra.get("company").and_then(|v| v.as_str()).is_some());
let fields = fm.link_fields();
// company (scalar) once, with the right target.
let company: Vec<&str> = fields
.iter()
.filter(|(k, _)| k == "company")
.map(|(_, l)| l.target.as_str())
.collect();
assert_eq!(company, vec!["records/companies/northstar"]);
// attendees (block list) twice.
let attendees: Vec<&str> = fields
.iter()
.filter(|(k, _)| k == "attendees")
.map(|(_, l)| l.target.as_str())
.collect();
assert_eq!(
attendees,
vec!["records/contacts/elena", "records/contacts/sarah"]
);
// summary link surfaced.
assert_eq!(fields.iter().filter(|(k, _)| k == "summary").count(), 1);
// Plain-text field is not a link.
assert_eq!(fields.iter().filter(|(k, _)| k == "notes").count(), 0);
}
#[test]
fn link_fields_surfaces_canonical_unquoted_scalar_link() {
// Regression: the canonical scalar wiki-link form is the *unquoted*
// inline `company: [[records/companies/northstar]]` (SPEC § Linking).
// YAML parses `[[x]]` as a flow-list-in-a-list (`Seq[Seq[String]]`), so
// a naive `as_str()`-only walk drops it. link_fields() must still
// surface exactly one link with the correct target.
let yaml = "type: meeting\ncompany: [[records/companies/northstar]]";
let fm = Frontmatter::parse(yaml, Path::new("m.md")).unwrap();
// Sanity: it really did parse as the nested sequence form, NOT a string.
assert!(fm.extra.get("company").and_then(|v| v.as_str()).is_none());
let fields = fm.link_fields();
let links: Vec<(&str, &str, Option<&str>)> = fields
.iter()
.map(|(k, l)| (k.as_str(), l.target.as_str(), l.display.as_deref()))
.collect();
assert_eq!(
links,
vec![("company", "records/companies/northstar", None)]
);
// The `|display` segment survives the unquoted inline form too.
let fm2 = Frontmatter::parse(
"type: meeting\ncompany: [[records/companies/northstar|Northstar]]",
Path::new("m.md"),
)
.unwrap();
let f2 = fm2.link_fields();
assert_eq!(f2.len(), 1);
assert_eq!(f2[0].0, "company");
assert_eq!(f2[0].1.target, "records/companies/northstar");
assert_eq!(f2[0].1.display.as_deref(), Some("Northstar"));
}
#[test]
fn link_fields_ignores_plain_one_item_flow_list() {
// A plain one-item flow list `aliases: [foo]` parses to `Seq[String]`
// — one nesting level shallower than an unquoted `[[foo]]` — and must
// NOT be mistaken for a wiki-link.
let yaml = "type: contact\naliases: [foo]";
let fm = Frontmatter::parse(yaml, Path::new("c.md")).unwrap();
assert_eq!(fm.link_fields(), Vec::new());
}
// ── detect_flow_form_link_lists ──────────────────────────────────────────
#[test]
fn detect_flow_form_flags_list_misencodings_not_scalars() {
// The flow-form list mis-encoding (triple-nested) IS flagged; a scalar
// inline wiki-link (double-nested) is NOT.
let bad = "attendees: [[[records/x]], [[records/y]]]\nscalar_inline: [[records/z]]";
let flagged = detect_flow_form_link_lists(bad);
assert_eq!(flagged, vec!["attendees".to_string()]);
// An UNquoted block list is also a mis-encoding (parses triple-nested).
let unquoted_block = "attendees:\n - [[records/x]]\n - [[records/y]]";
assert_eq!(
detect_flow_form_link_lists(unquoted_block),
vec!["attendees".to_string()]
);
// The canonical QUOTED block form parses to clean strings — NOT flagged.
let good = "attendees:\n - \"[[records/x]]\"\n - \"[[records/y]]\"";
assert!(detect_flow_form_link_lists(good).is_empty());
// A plain scalar list of strings is not flagged.
let plain = "tags: [a, b, c]";
assert!(detect_flow_form_link_lists(plain).is_empty());
}
// ── extract_sections ─────────────────────────────────────────────────────
#[test]
fn extract_sections_levels_nesting_and_boundaries() {
let body = "intro text\n## First\nalpha\n### Sub\nbeta\n## Second\ngamma\n";
let secs = extract_sections(body);
let headings: Vec<(&str, u8)> =
secs.iter().map(|s| (s.heading.as_str(), s.level)).collect();
assert_eq!(headings, vec![("First", 2), ("Sub", 3), ("Second", 2)]);
// "First" (H2) body extends through its H3 child, stopping at "Second".
let first = &secs[0];
assert!(first.body.contains("alpha"));
assert!(first.body.contains("### Sub"));
assert!(first.body.contains("beta"));
assert!(!first.body.contains("Second"));
// "Sub" (H3) stops at the next equal-or-shallower heading ("Second").
let sub = &secs[1];
assert!(sub.body.contains("beta"));
assert!(!sub.body.contains("gamma"));
// 1-based line numbers within the body.
assert_eq!(first.line, 2);
assert_eq!(secs[2].line, 6);
}
#[test]
fn extract_sections_ignores_headings_in_fenced_code() {
let body = "## Real\n```\n## Fake heading in code\n```\nafter\n";
let secs = extract_sections(body);
assert_eq!(secs.len(), 1);
assert_eq!(secs[0].heading, "Real");
// The fenced "## Fake" is part of Real's body, not its own section.
assert!(secs[0].body.contains("## Fake heading in code"));
}
// ── parse_field_spec ─────────────────────────────────────────────────────
#[test]
fn parse_field_spec_required_and_shape() {
let f = parse_field_spec("- email (required, email)");
assert_eq!(f.name, "email");
assert!(f.required);
assert_eq!(f.shape, Some(Shape::Email));
assert!(f.unknown_modifiers.is_empty());
}
#[test]
fn parse_field_spec_link_prefix_strips_trailing_slash() {
let f = parse_field_spec("- company (required, link to records/companies/)");
assert!(f.required);
assert_eq!(f.link_prefix, Some(PathBuf::from("records/companies")));
assert_eq!(f.shape, None);
}
#[test]
fn parse_field_spec_default_preserves_case_and_value() {
let f = parse_field_spec("- currency (default USD)");
assert_eq!(f.name, "currency");
assert_eq!(f.default, Some(Value::String("USD".into())));
}
#[test]
fn parse_field_spec_enum_captures_comma_list_as_last_modifier() {
let f = parse_field_spec("- status (required, enum: open, closed, pending)");
assert!(f.required);
assert_eq!(
f.enum_values,
Some(vec![
"open".to_string(),
"closed".to_string(),
"pending".to_string()
])
);
}
#[test]
fn parse_field_spec_bare_enum_keyword_is_not_itself_a_value() {
// `enum` with no colon: the values are the remaining tokens; the keyword
// itself must NOT leak in as an allowed value.
let f = parse_field_spec("- status (required, enum, open, closed)");
assert!(f.required);
assert_eq!(
f.enum_values,
Some(vec!["open".to_string(), "closed".to_string()])
);
}
#[test]
fn parse_field_spec_unknown_modifier_is_captured_not_errored() {
let f = parse_field_spec("- weird (required, frobnicate, string)");
assert!(f.required);
assert_eq!(f.shape, Some(Shape::String));
assert_eq!(f.unknown_modifiers, vec!["frobnicate".to_string()]);
}
#[test]
fn parse_field_spec_no_parens_is_freeform_optional() {
let f = parse_field_spec("- nickname");
assert_eq!(f.name, "nickname");
assert!(!f.required);
assert_eq!(f.shape, None);
assert!(f.link_prefix.is_none());
assert!(f.enum_values.is_none());
assert!(f.unknown_modifiers.is_empty());
}
// ── parse_schema_bullet (directives) ─────────────────────────────────────
#[test]
fn schema_bullet_unique_single_field() {
match parse_schema_bullet("- unique: email") {
SchemaBullet::Unique(fields) => assert_eq!(fields, vec!["email".to_string()]),
other => panic!("expected Unique, got {other:?}"),
}
}
#[test]
fn schema_bullet_unique_compound_trims_and_splits() {
match parse_schema_bullet("- unique: date, amount , vendor") {
SchemaBullet::Unique(fields) => assert_eq!(
fields,
vec![
"date".to_string(),
"amount".to_string(),
"vendor".to_string()
]
),
other => panic!("expected Unique, got {other:?}"),
}
}
#[test]
fn schema_bullet_summary_template_keeps_braces_and_inner_colons() {
match parse_schema_bullet("- summary_template: {role} at {company} (x: y)") {
SchemaBullet::SummaryTemplate(t) => assert_eq!(t, "{role} at {company} (x: y)"),
other => panic!("expected SummaryTemplate, got {other:?}"),
}
}
#[test]
fn schema_bullet_field_with_enum_modifier_is_not_a_directive() {
// A field whose modifiers contain a colon (`enum:`) parses as a field, not
// a directive — its head has a `(` before any `:`.
match parse_schema_bullet("- status (enum: open, closed)") {
SchemaBullet::Field(f) => {
assert_eq!(f.name, "status");
assert_eq!(
f.enum_values,
Some(vec!["open".to_string(), "closed".to_string()])
);
}
other => panic!("expected Field, got {other:?}"),
}
}
#[test]
fn parse_db_md_schema_captures_unique_and_summary_template() {
let db = "---\ntype: db-md\nscope: x\nowner: y\n---\n\n## Schemas\n\n### contact\n- email (required, email)\n- unique: email\n- summary_template: {role} at {company}\n";
let config = parse_db_md(db, Path::new("DB.md")).unwrap();
let s = config.schemas.get("contact").expect("contact schema");
assert_eq!(s.fields.len(), 1, "directives are not parsed as fields");
assert_eq!(s.unique_keys, vec![vec!["email".to_string()]]);
assert_eq!(s.summary_template.as_deref(), Some("{role} at {company}"));
}
#[test]
fn schema_bullet_shard_directive_parses_values() {
assert!(matches!(
parse_schema_bullet("- shard: by-date"),
SchemaBullet::Shard(Some(true))
));
assert!(matches!(
parse_schema_bullet("- shard: flat"),
SchemaBullet::Shard(Some(false))
));
// An unrecognized value is ignored (None), like an unknown modifier.
assert!(matches!(
parse_schema_bullet("- shard: weekly"),
SchemaBullet::Shard(None)
));
// A field whose name has a `(` before any `:` is still a field — the same
// guard that keeps `- status (enum: a, b)` a field, not a directive.
assert!(matches!(
parse_schema_bullet("- shardiness (string)"),
SchemaBullet::Field(_)
));
}
#[test]
fn parse_db_md_schema_captures_shard_directive() {
let db = "---\ntype: db-md\nscope: x\nowner: y\n---\n\n## Schemas\n\n### shipment\n- carrier (string)\n- shard: by-date\n\n### contact\n- shard: flat\n";
let config = parse_db_md(db, Path::new("DB.md")).unwrap();
let shipment = config.schemas.get("shipment").expect("shipment schema");
assert_eq!(shipment.shard, Some(true));
assert_eq!(
shipment.fields.len(),
1,
"`shard:` is a directive, not a field"
);
assert_eq!(config.schemas.get("contact").unwrap().shard, Some(false));
}
// ── parse_db_md ──────────────────────────────────────────────────────────
const CANONICAL_DB_MD: &str = "---\ntype: db-md\nscope: company\nowner: Sarah Chen\n---\n\n# Acme operations knowledge base\n\nCompany-scale institutional memory for Acme.\n\n## Agent instructions\n\nPrioritize creating `contact` records from new-sender emails. Use British English.\n\n## Policies\n\n### Frozen pages\n- `records/decisions/2026-q1-strategy.md` — finalized, do not modify.\n- `wiki/synthesis/2026-annual-plan.md` — signed-off plan.\n\n### Ignored types\n- `test`, `temp` — read but never synthesize.\n\n## Schemas\n\n### contact\n- name (required)\n- email (required, email)\n- company (required, link to records/companies/)\n- role (string)\n\n### expense\n- date (required, date)\n- amount (required)\n- currency (default USD)\n";
#[test]
fn parse_db_md_extracts_all_canonical_sections() {
let config = parse_db_md(CANONICAL_DB_MD, Path::new("DB.md")).unwrap();
// Agent instructions: free-form prose, heading line stripped.
let ai = config
.agent_instructions
.expect("agent instructions present");
assert!(ai.starts_with("Prioritize creating"));
assert!(!ai.contains("## Agent instructions"));
// Frozen pages: paths extracted from backticked bullets, comments dropped.
assert_eq!(
config.frozen_pages,
vec![
PathBuf::from("records/decisions/2026-q1-strategy.md"),
PathBuf::from("wiki/synthesis/2026-annual-plan.md"),
]
);
// Ignored types: comma list, backticks/comment stripped.
assert_eq!(
config.ignored_types,
vec!["test".to_string(), "temp".to_string()]
);
// Schemas: two types, each with its fields in source order.
assert_eq!(config.schemas.len(), 2);
let contact = config.schemas.get("contact").expect("contact schema");
let names: Vec<&str> = contact.fields.iter().map(|f| f.name.as_str()).collect();
assert_eq!(names, vec!["name", "email", "company", "role"]);
assert!(contact.fields[0].required); // name
assert_eq!(contact.fields[1].shape, Some(Shape::Email)); // email
assert_eq!(
contact.fields[2].link_prefix,
Some(PathBuf::from("records/companies"))
); // company
let expense = config.schemas.get("expense").expect("expense schema");
let cur = expense
.fields
.iter()
.find(|f| f.name == "currency")
.unwrap();
assert_eq!(cur.default, Some(Value::String("USD".into())));
}
#[test]
fn parse_db_md_handles_malformed_and_unknown_modifiers() {
// corpus-b shape: a `## Schemas` section with a malformed bullet, an
// unknown modifier, and bullets that appear with NO `### <type>`
// heading (so they belong to no schema and are dropped).
let text = "---\ntype: db-md\n---\n\n## Schemas\n- orphan (required)\n\n### ticket\n- priority (required, mystery, enum: low, high)\n- broken (\n";
let config = parse_db_md(text, Path::new("DB.md")).unwrap();
// The orphan bullet under `## Schemas` with no `### type` heading is not
// captured as a schema.
assert_eq!(config.schemas.len(), 1);
let ticket = config.schemas.get("ticket").expect("ticket schema");
assert_eq!(ticket.fields.len(), 2);
let priority = &ticket.fields[0];
assert!(priority.required);
assert_eq!(priority.unknown_modifiers, vec!["mystery".to_string()]);
assert_eq!(
priority.enum_values,
Some(vec!["low".to_string(), "high".to_string()])
);
// A bullet with an unclosed paren still yields a usable name.
let broken = &ticket.fields[1];
assert_eq!(broken.name, "broken");
}
#[test]
fn parse_db_md_missing_frontmatter_errors() {
let text = "# No frontmatter\n\n## Agent instructions\nhi\n";
let err = parse_db_md(text, Path::new("DB.md")).unwrap_err();
assert!(matches!(err, ParseError::MissingFrontmatter { .. }));
}
#[test]
fn parse_db_md_absent_sections_default_empty() {
let text = "---\ntype: db-md\n---\n\n# Title only\n";
let config = parse_db_md(text, Path::new("DB.md")).unwrap();
assert_eq!(config, Config::default());
}
// ── fm set / --fm list-valued link fields (meeting.attendees & friends) ──
/// `Frontmatter::set` is the value path every write surface (`fm set`,
/// `write --fm`) funnels through. A list-of-wiki-links value (the SPEC's
/// `meeting.attendees` shape) must serialize as a YAML **block sequence** of
/// quoted links — readable back by [`links_in_field_value`] and accepted by
/// `dbmd validate` — never the flow-form scalar string that trips
/// `WIKI_LINK_FLOW_FORM_LIST`. Both the unquoted (`[[[a]], [[b]]]`) and
/// quoted (`["[[a]]", "[[b]]"]`) spellings an agent types must normalize.
#[test]
fn set_list_of_wiki_links_becomes_block_sequence_both_spellings() {
for value in [
"[[[records/contacts/a]], [[records/contacts/b]]]",
r#"["[[records/contacts/a]]", "[[records/contacts/b]]"]"#,
] {
let mut fm = Frontmatter::default();
fm.set("attendees", value).unwrap();
// Stored as a 2-element sequence of clean quoted links.
let stored = fm.extra.get("attendees").expect("attendees set");
let Value::Sequence(items) = stored else {
panic!("attendees must be a Sequence, got {stored:?} for input {value}");
};
assert_eq!(items.len(), 2, "input {value}");
assert_eq!(items[0], Value::String("[[records/contacts/a]]".into()));
assert_eq!(items[1], Value::String("[[records/contacts/b]]".into()));
// The edge enumerator reads exactly the two links back (no stray
// bracket targets, the flow-form-string symptom).
let links: Vec<_> = links_in_field_value(stored)
.into_iter()
.map(|l| l.target)
.collect();
assert_eq!(
links,
vec!["records/contacts/a", "records/contacts/b"],
"input {value}"
);
// And the canonical writer renders it block-style, not as a scalar.
let yaml = fm.to_yaml();
assert!(
yaml.contains("attendees:\n"),
"expected block list in:\n{yaml}"
);
assert!(
!yaml.contains("attendees: '[["),
"must not be a flow-form scalar string in:\n{yaml}"
);
}
}
/// A *single* inline wiki-link stays a scalar string (renders inline
/// `field: [[x]]`), and a single link must never be widened to a one-item
/// list — preserving the common `contact.company` / `expense.vendor` shape.
#[test]
fn set_single_inline_wiki_link_stays_scalar() {
let mut fm = Frontmatter::default();
fm.set("company", "[[records/companies/tideform]]").unwrap();
assert_eq!(
fm.extra.get("company"),
Some(&Value::String("[[records/companies/tideform]]".into())),
);
// Still recognized as one link.
let links: Vec<_> = links_in_field_value(fm.extra.get("company").unwrap())
.into_iter()
.map(|l| l.target)
.collect();
assert_eq!(links, vec!["records/companies/tideform"]);
}
/// Plain text and a non-link flow list are left as verbatim scalar strings —
/// the list normalization only triggers when every item is a clean wiki-link.
#[test]
fn set_non_link_values_stay_scalar_strings() {
let mut fm = Frontmatter::default();
fm.set("location", "Video call (remote)").unwrap();
assert_eq!(
fm.extra.get("location"),
Some(&Value::String("Video call (remote)".into())),
);
// A flow list whose items are NOT wiki-links must not be reinterpreted as
// a link sequence; it stays the scalar string the agent passed.
fm.set("note", "[draft, wip]").unwrap();
assert_eq!(
fm.extra.get("note"),
Some(&Value::String("[draft, wip]".into()))
);
}
// ── Regression: non-string YAML keys round-trip (no Rust Debug corruption) ─
#[test]
fn regression_non_string_yaml_keys_keep_their_text_on_round_trip() {
// A numeric/bool/null/float frontmatter key is valid YAML and must NOT be
// rewritten to its Rust `Debug` form (`Number(2026)`, `Bool(true)`,
// `'Null'`). After the fix the key text survives (the key narrows to a
// string-typed key, but the operator's data is no longer corrupted).
let yaml = "type: note\n2026: planning notes\ntrue: yes-key\n3.14: f\n";
let fm = Frontmatter::parse(yaml, Path::new("x.md")).unwrap();
// Keys are stored as their scalar text, not the Debug string.
assert!(fm.extra.contains_key("2026"), "numeric key text lost");
assert!(fm.extra.contains_key("true"), "bool key text lost");
assert!(fm.extra.contains_key("3.14"), "float key text lost");
assert!(!fm.extra.keys().any(|k| k.starts_with("Number(")));
assert!(!fm.extra.keys().any(|k| k.starts_with("Bool(")));
// And a re-emit never produces the Debug forms on disk.
let out = fm.to_yaml();
assert!(!out.contains("Number("), "Debug-form key emitted:\n{out}");
assert!(!out.contains("Bool("), "Debug-form key emitted:\n{out}");
// The key text is still present (quoted, since it now reads as a string).
assert!(out.contains("2026"), "numeric key dropped:\n{out}");
assert!(out.contains("planning notes"), "value dropped:\n{out}");
}
// ── Regression: universal-key sequence/mapping values are preserved (#2) ───
#[test]
fn regression_universal_key_non_scalar_value_is_preserved_not_deleted() {
// A universal key carrying a sequence/mapping (`status: [active, draft]`)
// is not a valid scalar for that field. Before the fix, the matched arm
// consumed-and-dropped it (scalar_string -> None) and `to_yaml` then
// omitted the field — `dbmd format` silently DELETED it. It must now pass
// through `extra` and re-emit verbatim.
let yaml = "type: note\nstatus:\n - active\n - draft\nsummary:\n a: 1\n b: 2\n";
let fm = Frontmatter::parse(yaml, Path::new("x.md")).unwrap();
// The typed accessors stay None (no valid scalar), but the data lives in
// extra so nothing is lost.
assert!(fm.status.is_none());
assert!(fm.summary.is_none());
assert!(fm.extra.contains_key("status"), "status value destroyed");
assert!(fm.extra.contains_key("summary"), "summary value destroyed");
// A re-emit keeps both fields' data on disk.
let out = fm.to_yaml();
assert!(out.contains("status"), "status deleted on re-emit:\n{out}");
assert!(out.contains("active"), "status items deleted:\n{out}");
assert!(
out.contains("summary"),
"summary deleted on re-emit:\n{out}"
);
// Round-trips as a fixed point — repeated curator-loop writes don't lose
// the data.
let reparsed = Frontmatter::parse(&out, Path::new("x.md")).unwrap();
assert!(reparsed.extra.contains_key("status"));
assert!(reparsed.extra.contains_key("summary"));
}
// ── Regression: non-scalar tags items don't erase the tags field (#5) ──────
#[test]
fn regression_non_scalar_tags_value_is_preserved_not_erased() {
// `tags: [[vip]]` (an authoring slip — wiki-link brackets around a tag)
// parses to a nested sequence; before the fix `parse_tags` filtered the
// non-scalar item out and `to_yaml` then omitted the now-empty tags vec,
// silently DELETING the tags line. It must now survive the re-emit (the
// key data is preserved; the field is never dropped).
let yaml = "type: note\ntags: [[vip]]\n";
let fm = Frontmatter::parse(yaml, Path::new("x.md")).unwrap();
// The typed tags vec is empty (no clean scalar list), but the raw value
// is preserved in extra so nothing is destroyed.
assert!(fm.tags.is_empty());
assert!(fm.extra.contains_key("tags"), "tags value destroyed");
let out = fm.to_yaml();
assert!(out.contains("tags"), "tags deleted on re-emit:\n{out}");
// The `vip` text survives on disk in some form (never erased).
assert!(out.contains("vip"), "tag content erased:\n{out}");
// A clean tag list still parses to the typed vec (not regressed).
let clean =
Frontmatter::parse("type: note\ntags: [vip, renewal]\n", Path::new("x.md")).unwrap();
assert_eq!(clean.tags, vec!["vip".to_string(), "renewal".to_string()]);
assert!(!clean.extra.contains_key("tags"));
}
// ── Regression: plain nested string lists are NOT fabricated into links (#3) ─
#[test]
fn regression_plain_nested_string_list_is_not_turned_into_wiki_links() {
// `groups: [[alpha], [beta]]` is the data [["alpha"],["beta"]] — an
// unknown nested string list that must pass through verbatim. Before the
// fix, canonicalize_extra_value fabricated `- '[[alpha]]'` / `- '[[beta]]'`
// (short-form links the tool then flagged), changing the field's type.
let yaml = "type: note\ngroups: [[alpha], [beta]]\n";
let fm = Frontmatter::parse(yaml, Path::new("x.md")).unwrap();
let before = fm.extra.get("groups").cloned();
let out = fm.to_yaml();
// No fabricated wiki-link brackets in the emitted YAML.
assert!(!out.contains("[[alpha]]"), "fabricated a wiki-link:\n{out}");
assert!(!out.contains("[[beta]]"), "fabricated a wiki-link:\n{out}");
// The value is unchanged across the canonical re-emit.
let reparsed = Frontmatter::parse(&out, Path::new("x.md")).unwrap();
assert_eq!(
reparsed.extra.get("groups"),
before.as_ref(),
"nested string list mutated by canonicalize_extra_value"
);
// And it surfaces no links.
assert!(reparsed.link_fields().is_empty());
}
// ── Regression: fence-line trailing whitespace is tolerated (#4) ───────────
#[test]
fn regression_split_frontmatter_tolerates_trailing_whitespace_on_fences() {
// A fence written `--- ` (trailing space — invisible in editors) is
// indexed/validated clean by index.rs/validate.rs (both use `trim_end()`)
// but, before the fix, hard-failed every read/edit surface routed through
// `split_frontmatter`. All three must now agree.
let text = "--- \ntype: note\nsummary: x\n---\t\nbody\n";
let parsed = split_frontmatter(text, Path::new("f.md")).unwrap();
assert_eq!(parsed.frontmatter_yaml, "type: note\nsummary: x\n");
assert_eq!(parsed.body, "body\n");
// End to end through read_file's parse.
let fm = Frontmatter::parse(&parsed.frontmatter_yaml, Path::new("f.md")).unwrap();
assert_eq!(fm.type_.as_deref(), Some("note"));
}
// ── Regression: CommonMark trailing-'#' heading rule (#6) ──────────────────
#[test]
fn regression_heading_text_keeps_abutting_hash_drops_closing_sequence() {
// `## C#` → `C#` (the `#` abuts content, not a closing sequence).
assert_eq!(heading_text("## C#", 2), "C#");
assert_eq!(heading_text("## F#", 2), "F#");
assert_eq!(heading_text("## issue-123#", 2), "issue-123#");
// A genuine ATX closing sequence (space before the `#` run) is dropped.
assert_eq!(heading_text("## Title ##", 2), "Title");
assert_eq!(heading_text("## Title #", 2), "Title");
// All-hashes content collapses to empty.
assert_eq!(heading_text("## ##", 2), "");
// No trailing hashes — unchanged.
assert_eq!(heading_text("## Plain", 2), "Plain");
}
#[test]
fn regression_extract_sections_keeps_csharp_heading_and_schema_type_binds() {
// `dbmd sections` must report `C#`, not `C`.
let secs = extract_sections("## C#\nbody\n");
assert_eq!(secs.len(), 1);
assert_eq!(secs[0].heading, "C#");
// And a `### c#` schema must register under `c#`, not `c`.
let db = "---\ntype: db-md\n---\n\n## Schemas\n\n### c#\n- name (required)\n";
let config = parse_db_md(db, Path::new("DB.md")).unwrap();
assert!(
config.schemas.contains_key("c#"),
"schema bound to wrong key"
);
assert!(!config.schemas.contains_key("c"));
}
// ── Regression: section line numbers offset by the frontmatter block (#7) ──
#[test]
fn regression_extract_sections_in_file_reports_source_line_numbers() {
// A heading on file line 6 (after a 4-line frontmatter block + 1 body
// line) must be reported as L6, not the body-relative L2.
let text = "---\ntype: note\nsummary: x\n---\nbody line\n## Heading\nmore\n";
let secs = extract_sections_in_file(text);
assert_eq!(secs.len(), 1);
assert_eq!(secs[0].heading, "Heading");
assert_eq!(secs[0].line, 6, "section line not offset by frontmatter");
// The body-relative helper is unchanged (validate relies on that frame).
let body_secs = extract_sections("body line\n## Heading\nmore\n");
assert_eq!(body_secs[0].line, 2);
// No frontmatter: whole text is body, no offset.
let plain = extract_sections_in_file("## Top\nx\n## Next\n");
assert_eq!(plain[0].line, 1);
assert_eq!(plain[1].line, 3);
}
// ── Regression: colon-form schema field bullet parses modifiers (#8) ───────
#[test]
fn regression_colon_form_field_bullet_parses_modifiers() {
// `- title: string, required` is the natural mis-spelling of
// `- title (string, required)`; before the fix the whole text became the
// field name and every modifier was silently lost.
let f = parse_field_spec("- title: string, required");
assert_eq!(f.name, "title");
assert!(f.required, "required modifier lost on colon-form");
assert_eq!(f.shape, Some(Shape::String));
// Through the schema-bullet classifier (the real path), it is a Field.
match parse_schema_bullet("- title: string, required") {
SchemaBullet::Field(f) => {
assert_eq!(f.name, "title");
assert!(f.required);
assert_eq!(f.shape, Some(Shape::String));
}
other => panic!("expected Field, got {other:?}"),
}
// A paren form whose modifiers contain a colon still parses by parens.
let g = parse_field_spec("- status (enum: open, closed)");
assert_eq!(g.name, "status");
assert_eq!(
g.enum_values,
Some(vec!["open".to_string(), "closed".to_string()])
);
}
// ── Regression: comma inside a `default` value is preserved (#9) ───────────
#[test]
fn regression_default_value_preserves_internal_commas() {
let f = parse_field_spec("- title (default Director, Operations)");
assert_eq!(
f.default,
Some(Value::String("Director, Operations".into())),
"comma-bearing default truncated"
);
let g = parse_field_spec("- region (default North America, EMEA fallback)");
assert_eq!(
g.default,
Some(Value::String("North America, EMEA fallback".into()))
);
// A single-token default still works (no regression).
let h = parse_field_spec("- currency (default USD)");
assert_eq!(h.default, Some(Value::String("USD".into())));
}
// ── Regression: a `default` after `enum` is parsed, not swallowed (#10) ────
#[test]
fn regression_default_after_enum_is_parsed_not_an_enum_member() {
let f = parse_field_spec("- status (enum: open, closed, default open)");
assert_eq!(
f.enum_values,
Some(vec!["open".to_string(), "closed".to_string()]),
"`default open` leaked into the enum list"
);
assert_eq!(
f.default,
Some(Value::String("open".into())),
"default after enum was dropped"
);
// The bare `enum` keyword form, with a trailing default.
let g = parse_field_spec("- status (enum, open, closed, default open)");
assert_eq!(
g.enum_values,
Some(vec!["open".to_string(), "closed".to_string()])
);
assert_eq!(g.default, Some(Value::String("open".into())));
}
// ── Regression: frozen-page policy does not fail open (#11) ────────────────
#[test]
fn regression_frozen_match_handles_leading_slash() {
let cfg = Config {
frozen_pages: vec![PathBuf::from("/records/decisions/q1.md")],
..Config::default()
};
assert!(
cfg.is_frozen(Path::new("records/decisions/q1.md")),
"leading-slash entry failed open"
);
assert!(cfg.is_frozen(Path::new("records/decisions/q1")));
}
#[test]
fn regression_frozen_match_supports_globs() {
let cfg = Config {
frozen_pages: vec![PathBuf::from("records/decisions/*")],
..Config::default()
};
assert!(
cfg.is_frozen(Path::new("records/decisions/q1.md")),
"glob entry failed to protect a concrete file"
);
assert!(cfg.is_frozen(Path::new("records/decisions/q2.md")));
// The glob does not cross a `/` segment.
assert!(!cfg.is_frozen(Path::new("records/decisions/sub/q1.md")));
// `**` crosses segments.
let deep = Config {
frozen_pages: vec![PathBuf::from("records/**")],
..Config::default()
};
assert!(deep.is_frozen(Path::new("records/decisions/sub/q1.md")));
assert!(deep.is_frozen(Path::new("records/x.md")));
assert!(!deep.is_frozen(Path::new("wiki/x.md")));
// A `*.md`-style intra-segment glob.
let suffix = Config {
frozen_pages: vec![PathBuf::from("records/decisions/q*")],
..Config::default()
};
assert!(suffix.is_frozen(Path::new("records/decisions/q1.md")));
assert!(!suffix.is_frozen(Path::new("records/decisions/draft.md")));
}
#[test]
fn regression_frozen_entry_single_hyphen_comment_is_stripped() {
// `records/decisions/q3.md - finalized` (single ASCII hyphen comment, no
// backticks): the comment must be stripped so the entry is just the path.
let path = extract_path_bullet("- records/decisions/q3.md - finalized");
assert_eq!(path, "records/decisions/q3.md");
// End to end: such a bullet freezes the file.
let cfg = Config {
frozen_pages: vec![PathBuf::from(extract_path_bullet(
"- records/decisions/q3.md - finalized",
))],
..Config::default()
};
assert!(
cfg.is_frozen(Path::new("records/decisions/q3.md")),
"single-hyphen-comment entry failed open"
);
}
}