secondbrain-py 0.2.1__py3-none-any.whl

brain/vault/links.py

@@ -0,0 +1,260 @@
+"""Wiki-link parser for Markdown vault notes.
+
+Pure parsing: input is a Markdown body string (frontmatter already stripped by
+the caller), output is a list of :class:`ParsedLink` in document order. The
+parser recognizes Obsidian-style ``[[wiki]]`` and ``![[embed]]`` markers plus
+the brain-specific ``[[brain:<id>]]`` and ``[[<source>:<external>]]`` forms.
+
+Skipped contexts (silently — these are not links):
+
+- Fenced code blocks (`` ``` ... ``` `` or ``~~~ ... ~~~``).
+- Inline code spans delimited by backticks.
+- Indented code blocks (4+ leading spaces, with no preceding non-blank line).
+- Wiki-link openings preceded by a backslash escape (``\\[[X]]``).
+- Empty ``[[]]`` openers (no error, just ignored).
+
+The parser is intentionally conservative: when in doubt about whether a
+``[[...]]`` is "really" a link, it skips. Callers can rely on the result list
+being safe to materialize into the ``links``/``unresolved_links`` tables
+without producing false positives.
+"""
+import re
+from dataclasses import dataclass
+from typing import Literal
+
+# Source kinds the parser recognizes in ``[[<source>:<external_id>]]`` form.
+# ``brain`` is reserved for direct document-id lookup; other identifiers are
+# routed to the ``sources`` table.
+_SOURCE_KINDS: frozenset[str] = frozenset({"krisp", "slack", "gmail", "manual"})
+
+# Bracket inside a wiki-link must not contain another ``]]``. Allowing nested
+# brackets would conflict with Markdown reference-style links and is not part
+# of the Obsidian format we conform to.
+_WIKI_LINK_RE = re.compile(r"\[\[(?P<inner>[^\[\]]*?)\]\]")
+
+_FENCE_RE = re.compile(r"^(?P<fence>`{3,}|~{3,})")
+
+
+@dataclass(frozen=True)
+class ParsedLink:
+    """One parsed ``[[...]]`` occurrence from a Markdown body.
+
+    Field semantics map 1:1 onto the spec's resolution table — see the table
+    in ``docs/specs/2026-04-28-vault-model-design.md``. The parser does not
+    resolve the link; it only classifies the surface syntax. Resolution
+    against the DB is :func:`brain.vault.resolver.resolve_link`'s job.
+
+    ``raw`` is the literal substring as it appeared in the document,
+    including the surrounding ``[[ ]]`` (or ``![[ ]]`` for embeds). Useful
+    for round-tripping into ``links.link_text`` so renderers can match the
+    original wording exactly.
+    """
+
+    raw: str
+    kind: Literal["wiki", "embed"]
+    target_type: Literal["title", "doc-id", "source-external"]
+    target_value: str
+    target_source: str | None
+    display_text: str | None
+    heading: str | None
+
+
+def parse_wiki_links(text: str) -> list[ParsedLink]:
+    """Return every wiki-link found in ``text`` in document order.
+
+    The returned list is positional — callers can rely on the order matching
+    the order links appear in the body, which makes diagnostics ("link #3
+    on line 47 is dangling") straightforward.
+
+    Returns an empty list for any input that contains no parseable links
+    (including the empty string and bodies consisting entirely of code).
+    """
+    return [link for link, _start, _end in iter_wiki_links_with_spans(text)]
+
+
+def iter_wiki_links_with_spans(
+    text: str,
+) -> list[tuple[ParsedLink, int, int]]:
+    """Same as :func:`parse_wiki_links`, but each entry carries source spans.
+
+    Each tuple is ``(parsed, start, end)`` where ``text[start:end]`` is the
+    exact byte range the link occupies in the original ``text``. Embeds
+    (``![[...]]``) include the leading ``!`` in the span so callers that
+    rewrite in place don't have to detect it again.
+
+    Spans are non-overlapping and yielded in document order. The
+    :func:`_strip_uncodelike_regions` pass that powers code-fence skipping
+    is length-preserving, so offsets from the regex over the masked text map
+    1:1 onto the original — that's what makes rewriting safe even when a
+    later region of the document contains the same ``[[X]]`` inside a code
+    fence (it's silently skipped, not rewritten).
+    """
+    parseable = _strip_uncodelike_regions(text)
+    out: list[tuple[ParsedLink, int, int]] = []
+    for match in _WIKI_LINK_RE.finditer(parseable):
+        inner = match.group("inner")
+        if not inner.strip():
+            # ``[[]]`` and ``[[   ]]`` are silently ignored — Obsidian treats
+            # them as user typos rather than markup.
+            continue
+        # Detect ``![[...]]`` embeds: look at the character immediately
+        # before the opener.
+        start = match.start()
+        end = match.end()
+        is_embed = start > 0 and parseable[start - 1] == "!"
+        # Reject ``\[[X]]`` (backslash-escaped) — the ``\`` makes it literal text.
+        # An odd number of backslashes immediately preceding the opener escapes
+        # it; an even number means the user wrote ``\\`` (literal backslash)
+        # before a real link.
+        escape_index = start - 1
+        if is_embed:
+            escape_index -= 1
+        backslash_run = 0
+        while escape_index >= 0 and parseable[escape_index] == "\\":
+            backslash_run += 1
+            escape_index -= 1
+        if backslash_run % 2 == 1:
+            continue
+
+        raw = ("![[" if is_embed else "[[") + inner + "]]"
+        link = _classify(raw, inner, embed=is_embed)
+        if link is not None:
+            span_start = start - 1 if is_embed else start
+            out.append((link, span_start, end))
+    return out
+
+
+def _classify(raw: str, inner: str, *, embed: bool) -> ParsedLink | None:
+    """Turn ``inner`` (the text between ``[[`` and ``]]``) into a ParsedLink.
+
+    Splits on the first ``|`` for the optional display alias, then on ``#``
+    for an optional heading, then on ``:`` to detect explicit prefixes
+    (``brain:`` / ``<source>:``). Returns ``None`` only on degenerate inputs
+    that survived the empty-check above (e.g. a lone ``|`` with no target);
+    the caller drops them silently.
+    """
+    target_part, _, display = inner.partition("|")
+    target_part = target_part.strip()
+    display_text = display.strip() if display else None
+    if not target_part:
+        return None
+
+    target_value, _, heading_part = target_part.partition("#")
+    target_value = target_value.strip()
+    heading = heading_part.strip() if heading_part else None
+    if not target_value:
+        return None
+
+    # Explicit ``<prefix>:<rest>`` form. Only a small set of known prefixes
+    # win; arbitrary ``foo:bar`` is treated as a title (Obsidian allows
+    # colons in note titles, so we don't claim them by default).
+    prefix, sep, rest = target_value.partition(":")
+    prefix = prefix.strip()
+    rest = rest.strip()
+    kind: Literal["wiki", "embed"] = "embed" if embed else "wiki"
+    if sep and rest:
+        if prefix == "brain":
+            return ParsedLink(
+                raw=raw,
+                kind=kind,
+                target_type="doc-id",
+                target_value=rest,
+                target_source=None,
+                display_text=display_text,
+                heading=heading,
+            )
+        if prefix in _SOURCE_KINDS:
+            return ParsedLink(
+                raw=raw,
+                kind=kind,
+                target_type="source-external",
+                target_value=rest,
+                target_source=prefix,
+                display_text=display_text,
+                heading=heading,
+            )
+
+    return ParsedLink(
+        raw=raw,
+        kind=kind,
+        target_type="title",
+        target_value=target_value,
+        target_source=None,
+        display_text=display_text,
+        heading=heading,
+    )
+
+
+def _strip_uncodelike_regions(text: str) -> str:
+    """Replace fenced/inline/indented code regions with spaces, length-preserving.
+
+    Length-preserving so positional information (``match.start()``) over the
+    returned string still maps onto the original — useful for future
+    line/column diagnostics, even though Phase 2 doesn't surface them yet.
+    All other characters are left intact, so the regex scan only sees text
+    that's actually eligible to contain a link.
+    """
+    out_chars: list[str] = []
+    in_fence = False
+    fence_marker = ""
+    lines = text.splitlines(keepends=True)
+    for line in lines:
+        stripped = line.lstrip()
+        if in_fence:
+            if stripped.startswith(fence_marker):
+                in_fence = False
+                fence_marker = ""
+            out_chars.append(_blank_keep_newline(line))
+            continue
+        match = _FENCE_RE.match(stripped)
+        if match:
+            in_fence = True
+            fence_marker = match.group("fence")[0] * 3
+            out_chars.append(_blank_keep_newline(line))
+            continue
+        # Indented code block (4+ leading spaces or a tab) — only when the
+        # block is structurally a code block; for our purposes, treating any
+        # 4+-space indent as code is conservative-but-safe (a real list item
+        # at 4 spaces is rare in this corpus and a false negative on a link
+        # there is acceptable).
+        if line.startswith("    ") or line.startswith("\t"):
+            out_chars.append(_blank_keep_newline(line))
+            continue
+        out_chars.append(_strip_inline_code(line))
+    return "".join(out_chars)
+
+
+def _blank_keep_newline(line: str) -> str:
+    """Replace every non-newline character in ``line`` with a space.
+
+    Keeps offsets stable for downstream regex matching while ensuring no
+    bracket-like characters survive to be mistaken for a link.
+    """
+    return "".join(" " if ch != "\n" else "\n" for ch in line)
+
+
+def _strip_inline_code(line: str) -> str:
+    """Replace inline code spans (``` `…` ```) in ``line`` with spaces.
+
+    Only single-backtick spans are handled — Markdown allows multi-backtick
+    spans to escape inner backticks, but in practice vault notes don't mix
+    those with wiki-links, and the cost of a false negative (a missed link)
+    is much lower than a false positive (materializing a code-fragment as a
+    link).
+    """
+    out: list[str] = []
+    in_code = False
+    for ch in line:
+        if ch == "`":
+            out.append(" ")
+            in_code = not in_code
+            continue
+        if in_code and ch != "\n":
+            out.append(" ")
+        else:
+            out.append(ch)
+    # If the line ends with an unmatched opening backtick, treat the rest as
+    # text — this branch is naturally handled by the loop above (``in_code``
+    # leaks to the next line, but ``_strip_uncodelike_regions`` resets state
+    # per-line, so an unbalanced inline opener is forgiving).
+    return "".join(out)

brain/vault/note_builder.py

@@ -0,0 +1,211 @@
+"""Standalone builder for vault-tier notes: render frontmatter, write, and sync.
+
+Extracted from ``brain.cli`` so callers (e.g. the tacit-knowledge elicitation
+session loop) can author vault notes WITHOUT importing the Typer CLI — which
+would create an import cycle (``cli`` already imports ``brain.vault``).
+
+The heavy collaborators (``sync_one_file`` and ``make_embedder``) are imported
+lazily inside the functions on purpose: importing them at module load would
+re-enter the ``brain.ingest`` package while it is only partially initialized
+(``brain.ingest`` imports ``brain.vault.export``, which imports this package),
+raising ``ImportError``. The module-level imports below are all cycle-safe
+leaves.
+"""
+from __future__ import annotations
+
+import uuid
+from datetime import date as date_cls
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import yaml
+
+from ..errors import VaultNoteSyncError
+from ..tags import normalize_tags
+from .frontmatter import dump_frontmatter, parse_frontmatter
+from .slug import slugify
+from .templates import render_template
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    import psycopg
+
+    from ..config import Config
+    from ..ingest import Embedder
+
+
+def _build_embedder(cfg: Config) -> Embedder:
+    """Build the configured embedder. Indirected so tests can substitute a fake.
+
+    Returns the :class:`Embedder` Protocol — callers should not depend on the
+    concrete backend. The ``make_embedder`` import is deferred to avoid a
+    load-time import cycle (see the module docstring).
+    """
+    from ..embeddings import make_embedder
+
+    return make_embedder(cfg)
+
+
+def _build_note_text(
+    template_text: str,
+    *,
+    title: str,
+    tags: list[str],
+    today: date_cls,
+    now: datetime,
+    body: str | None = None,
+) -> tuple[str, str]:
+    """Render a template + force the brain-canonical frontmatter fields.
+
+    Returns ``(file_text, document_id)``. The template's body is preserved
+    verbatim unless ``body`` is provided, in which case the rendered template's
+    body is replaced by ``body`` (used when a caller supplies authored content
+    instead of letting the user fill the template in ``$EDITOR``). Only the
+    frontmatter is rewritten so the brain-managed fields (``id``, ``title``,
+    ``created``, ``updated``, ``kind``, ``tags``) are authoritative regardless
+    of what the template author wrote.
+
+    A user-template ``title:`` line is intentionally ignored — the caller's
+    ``title`` argument wins. That's the contract: if you wanted the template
+    to control title, you'd be using a daily template (which derives title
+    from the date passed in via ``vars``).
+    """
+    rendered = render_template(
+        template_text,
+        {
+            "title": title,
+            "date": today.isoformat(),
+            "datetime": now.isoformat(timespec="seconds"),
+            "slug": slugify(title),
+        },
+    )
+
+    # Try to parse the rendered template's frontmatter; if it's malformed or
+    # missing entirely, build a fresh header. Either way the brain-canonical
+    # fields are forced — the template's body is what we preserve.
+    try:
+        existing_fields, parsed_body = parse_frontmatter(rendered)
+    except (ValueError, yaml.YAMLError):
+        # Per the spec's risk: a malformed template shouldn't crash. Fall
+        # back to a fresh frontmatter + the raw rendered text as the body.
+        existing_fields = {}
+        parsed_body = rendered
+
+    note_body = parsed_body if body is None else body
+
+    document_id = str(uuid.uuid4())
+    iso_now = now.isoformat(timespec="seconds")
+    fields: dict[str, Any] = dict(existing_fields)
+    # Brain-managed fields override the template's choices in a fixed order
+    # so frontmatter ordering is stable across runs.
+    fields["id"] = document_id
+    fields["title"] = title
+    fields["created"] = iso_now
+    fields["updated"] = iso_now
+    fields["kind"] = "vault"
+    if tags:
+        fields["tags"] = list(tags)
+    elif "tags" not in fields:
+        fields["tags"] = []
+
+    return dump_frontmatter(fields, note_body), document_id
+
+
+def _unique_target(base_dir: Path, slug: str) -> Path:
+    """Return a non-existing ``<base_dir>/<slug>.md`` path, suffixing on collision.
+
+    ``brain note new`` guards against collisions before delegating here, but the
+    elicitation ``_codify`` path calls :func:`create_vault_note` directly. Without
+    this guard a draft whose title slugifies to an existing note's slug would
+    silently overwrite that note (data loss). On collision we append ``-2``,
+    ``-3``, … until a free path is found so the existing note is never clobbered.
+    """
+    target = base_dir / f"{slug}.md"
+    if not target.exists():
+        return target
+    suffix = 2
+    while True:
+        candidate = base_dir / f"{slug}-{suffix}.md"
+        if not candidate.exists():
+            return candidate
+        suffix += 1
+
+
+def create_vault_note(
+    conn: psycopg.Connection[Any],
+    *,
+    cfg: Config,
+    vault_path: Path,
+    title: str,
+    body: str | None = None,
+    tags: Sequence[str] = (),
+    template: str = "note",
+    folder: str = "",
+    embedder: Embedder | None = None,
+) -> str:
+    """Author a vault-tier note: render, write to disk, sync, return its id.
+
+    Resolves ``<vault>/_templates/<template>.md``, renders it (forcing the
+    brain-canonical frontmatter) with ``body`` substituted for the template's
+    placeholder body when provided, writes the file under ``vault_path`` (in
+    ``folder`` if given), then runs a single-file sync so the note is indexed
+    as ``kind='vault'`` (the tier ``sync_one_file`` infers for any file outside
+    ``_ingested/``).
+
+    ``embedder`` lets a caller inject a pre-built embedder (``brain note new``
+    passes the one it built so test fakes wired onto
+    ``brain.cli._build_embedder`` still apply); when ``None`` the configured
+    embedder is built from ``cfg``.
+
+    Raises :class:`~brain.errors.VaultNoteSyncError` if the template is missing
+    or the sync reports per-file errors (the file is left on disk on a sync
+    error). Returns the generated ``document_id``.
+    """
+    from .sync import sync_one_file
+
+    template_path = vault_path / "_templates" / f"{template}.md"
+    if not template_path.is_file():
+        raise VaultNoteSyncError(
+            [(template_path, f"template {template!r} not found")]
+        )
+    template_text = template_path.read_text(encoding="utf-8")
+
+    now = datetime.now()
+    today = now.date()
+    file_text, document_id = _build_note_text(
+        template_text,
+        title=title,
+        tags=normalize_tags(list(tags)),
+        today=today,
+        now=now,
+        body=body,
+    )
+
+    base_dir = vault_path / folder if folder else vault_path
+    # Path-traversal guard: a ``folder`` containing ``..`` segments or an
+    # absolute path would resolve outside the vault root and author files in an
+    # arbitrary filesystem location. Reject before any mkdir / write so nothing
+    # is created on violation.
+    vault_root_resolved = vault_path.resolve()
+    base_dir_resolved = base_dir.resolve()
+    if not base_dir_resolved.is_relative_to(vault_root_resolved):
+        raise VaultNoteSyncError(
+            [(base_dir, f"folder {folder!r} escapes the vault root")]
+        )
+    base_dir.mkdir(parents=True, exist_ok=True)
+    target = _unique_target(base_dir, slugify(title))
+    target.write_text(file_text, encoding="utf-8")
+
+    active_embedder = embedder if embedder is not None else _build_embedder(cfg)
+    report = sync_one_file(
+        conn,
+        embedder=active_embedder,
+        vault_path=vault_path,
+        file_path=target,
+        owner_participants=cfg.owner_participants,
+    )
+    if report.errors:
+        raise VaultNoteSyncError(report.errors)
+    return document_id

brain/vault/paths.py

@@ -0,0 +1,55 @@
+"""Shared path / wiki-link helpers used by the vault renderers.
+
+Both helpers are pure (no I/O, no DB) and small. Three rendering surfaces
+hand-rolled the same logic before this module existed:
+
+- :mod:`brain.wiki.build_homepage` — recent-rail bullet renderer
+- :mod:`brain.wiki.build_people` — People Hub per-person + index pages
+- :mod:`brain.vault.daily_index` — daily-notes index renderer
+
+Centralizing here means a future change (say, switching to ``.markdown``
+extension support) flips one place rather than three.
+"""
+from pathlib import PurePosixPath
+
+
+def strip_md_extension(path: str) -> str:
+    """Return ``path`` with a trailing ``.md`` removed, POSIX-style.
+
+    ``documents.vault_path`` and the equivalent on-disk relative paths are
+    stored as forward-slash POSIX strings; we keep the same shape so wiki
+    links round-trip on Windows hosts too. Inputs without a trailing
+    ``.md`` are returned unchanged (after the POSIX normalization), so
+    callers can pipe path-form strings through unconditionally.
+
+    Used by every renderer that emits ``[[<vault-path-no-md>|<title>]]``
+    so wiki-links match what
+    :func:`brain.vault.resolver._resolve_by_vault_path` looks for. Empty
+    input yields ``'.'`` (because ``PurePosixPath('').as_posix() == '.'``);
+    the renderers guard for that separately if they care, and the
+    contract is pinned by ``tests/test_vault_paths.py::test_empty_input``.
+    """
+    posix = PurePosixPath(path).as_posix()
+    if posix.endswith(".md"):
+        return posix[:-3]
+    return posix
+
+
+def safe_wikilink_alias(title: str) -> str:
+    """Strip ``[`` / ``]`` from a wiki-link alias slot.
+
+    Quartz's wiki-link regex defines the alias slot as ``[^\\[\\]\\#]``;
+    any ``[`` or ``]`` inside an alias makes the whole ``[[...]]`` fail
+    to match and emit as raw text. Doc titles in the brain corpus
+    routinely contain bracketed prefixes — ``Re: [External] Re: ...``
+    from forwarded Gmail, ``[2026-04] Plenty sync notes`` from manual
+    notes — so we swap brackets for parens in the alias slot only. The
+    wiki-link target is :data:`documents.vault_path`, which never
+    contains these characters by construction.
+
+    Returns the title unchanged when no replacement is needed (cheap
+    early-out for the common case).
+    """
+    if "[" not in title and "]" not in title:
+        return title
+    return title.replace("[", "(").replace("]", ")")