mosaix-format 1.2.1__tar.gz

mosaix_format-1.2.1/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: mosaix-format
+Version: 1.2.1
+Summary: Python library for the Mosaix Format
+Author-email: Andrea Fiorino <andrea@alfagomma.dev>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# mosaix
+
+Python library for the [Mosaix Format](https://mosaix.io) — stdlib only, no dependencies.
+
+## Install (editable)
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```python
+from mosaix import parse_note, validate_vault, VaultGraph
+
+note = parse_note("path/to/note.md")
+print(note.title, note.id)
+
+report = validate_vault("path/to/vault")
+print(report.conformant, len(report.errors))
+
+g = VaultGraph("path/to/vault")
+print(g.orphans())
+print(g.components())
+```
+
+## CLI
+
+```bash
+mosaix check <vault_dir>
+mosaix check <vault_dir> --json
+mosaix check <vault_dir> --check-rev --exclude=exports
+```
+
+Exit codes: `0` clean · `1` errors · `2` warnings only.
+
+## Modules
+
+| Module | Purpose |
+|---|---|
+| `parser.py` | `parse_note(path) → Note` |
+| `validator.py` | `validate_note(note)`, `validate_vault(path) → Report` |
+| `crud.py` | `create_note()`, `update_frontmatter()`, `delete_note()` (raises) |
+| `graph.py` | `VaultGraph`: orphans, broken_links, components |
+| `_yaml.py` | Minimal YAML parser (internal, extracted from audit_reference.py) |
+| `cli.py` | `mosaix check` entry point |
+
+## License
+
+MIT © 2026 Andrea Fiorino

mosaix_format-1.2.1/README.md

@@ -0,0 +1,50 @@
+# mosaix
+
+Python library for the [Mosaix Format](https://mosaix.io) — stdlib only, no dependencies.
+
+## Install (editable)
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```python
+from mosaix import parse_note, validate_vault, VaultGraph
+
+note = parse_note("path/to/note.md")
+print(note.title, note.id)
+
+report = validate_vault("path/to/vault")
+print(report.conformant, len(report.errors))
+
+g = VaultGraph("path/to/vault")
+print(g.orphans())
+print(g.components())
+```
+
+## CLI
+
+```bash
+mosaix check <vault_dir>
+mosaix check <vault_dir> --json
+mosaix check <vault_dir> --check-rev --exclude=exports
+```
+
+Exit codes: `0` clean · `1` errors · `2` warnings only.
+
+## Modules
+
+| Module | Purpose |
+|---|---|
+| `parser.py` | `parse_note(path) → Note` |
+| `validator.py` | `validate_note(note)`, `validate_vault(path) → Report` |
+| `crud.py` | `create_note()`, `update_frontmatter()`, `delete_note()` (raises) |
+| `graph.py` | `VaultGraph`: orphans, broken_links, components |
+| `_yaml.py` | Minimal YAML parser (internal, extracted from audit_reference.py) |
+| `cli.py` | `mosaix check` entry point |
+
+## License
+
+MIT © 2026 Andrea Fiorino

mosaix_format-1.2.1/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=42"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mosaix-format"
+version = "1.2.1"
+description = "Python library for the Mosaix Format"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Andrea Fiorino", email = "andrea@alfagomma.dev" }]
+
+[project.scripts]
+mosaix = "mosaix.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

mosaix_format-1.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mosaix_format-1.2.1/src/mosaix/__init__.py

@@ -0,0 +1,12 @@
+"""mosaix — Python library for the Mosaix Format."""
+from .parser import Entity, Relation, Note, parse_note
+from .validator import Issue, Report, validate_note, validate_vault
+from .crud import create_note, update_frontmatter, delete_note
+from .graph import VaultGraph
+
+__all__ = [
+    "Entity", "Relation", "Note", "parse_note",
+    "Issue", "Report", "validate_note", "validate_vault",
+    "create_note", "update_frontmatter", "delete_note",
+    "VaultGraph",
+]

mosaix_format-1.2.1/src/mosaix/_yaml.py

@@ -0,0 +1,145 @@
+"""Minimal YAML subset for Mosaix frontmatter — stdlib only.
+
+Extracted from audit_reference.py. Handles the flat scalar + list structures
+that appear in Mosaix CORE keys; does not support full YAML.
+"""
+from __future__ import annotations
+
+ITEM_ALIASES = {"nome": "name", "tipo": "type", "da": "from", "a": "to"}
+VALUE_ALIASES = {
+    "persona": "person", "azienda": "company", "prodotto": "product", "progetto": "project",
+    "strumento": "tool", "luogo": "place", "documento": "document", "evento": "event",
+    "sintesi": "synthesis",
+    "ok": "sourced", "confermare": "to-confirm", "superato": "superseded",
+}
+KEY_ALIASES = {
+    "titolo": "title", "aggiornato": "updated", "riassunto": "summary", "parole_chiave": "keywords",
+    "mcp_entita": "entities", "mcp_relazioni": "relations", "mcp_collegamenti": "links", "mcp_rev": "rev",
+    "mcp_frammenti": "fragments", "mcp_pool": "pool", "mcp_layout": "layout",
+    "tipo": "type", "stato": "status",
+}
+
+
+def _scalar(s: str):
+    s = s.strip()
+    if not s:
+        return ""
+    if (s[0] == s[-1]) and s[0] in "\"'":
+        return s[1:-1]
+    if s.startswith("[") and s.endswith("]"):
+        inner = s[1:-1].strip()
+        if not inner:
+            return []
+        items, depth, cur, quote = [], 0, "", ""
+        for ch in inner:
+            if quote:
+                if ch == quote:
+                    quote = ""
+            elif ch in "\"'" and not cur.strip():
+                quote = ch
+            elif ch in "{[":
+                depth += 1
+            elif ch in "}]":
+                depth -= 1
+            if ch == "," and depth == 0 and not quote:
+                items.append(_scalar(cur))
+                cur = ""
+            else:
+                cur += ch
+        items.append(_scalar(cur))
+        return items
+    if s.startswith("{") and s.endswith("}"):
+        d = {}
+        for part in s[1:-1].split(","):
+            if ":" in part:
+                k, v = part.split(":", 1)
+                d[k.strip()] = _scalar(v)
+        return d
+    return s
+
+
+def parse_frontmatter(text: str) -> tuple[dict | None, str]:
+    """Return (frontmatter_dict | None, body_str)."""
+    if not text.startswith("---"):
+        return None, text
+    end = text.find("\n---", 3)
+    if end < 0:
+        return None, text
+    block = text[3:end].strip("\n")
+    body = text[end + 4:]
+    fm: dict = {}
+    key = None
+    lines = block.splitlines()
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        if not line.strip() or line.lstrip().startswith("#"):
+            i += 1
+            continue
+        if not line.startswith((" ", "\t")) and ":" in line:
+            key, _, val = line.partition(":")
+            key = key.strip()
+            val = val.strip()
+            if val == "" or val in ("|", ">"):
+                fm[key] = [] if val == "" else ""
+            else:
+                fm[key] = _scalar(val)
+        elif key is not None and line.lstrip().startswith("- "):
+            item = line.lstrip()[2:].strip()
+            if not isinstance(fm.get(key), list):
+                fm[key] = []
+            if item.startswith("{"):
+                fm[key].append(_scalar(item))
+            elif ":" in item and not item.startswith(("\"", "'", "[")):
+                d: dict = {}
+                k, _, v = item.partition(":")
+                d[k.strip()] = _scalar(v)
+                j = i + 1
+                while j < len(lines) and lines[j].startswith((" ", "\t")) and not lines[j].lstrip().startswith("- ") and ":" in lines[j]:
+                    k2, _, v2 = lines[j].strip().partition(":")
+                    d[k2.strip()] = _scalar(v2)
+                    j += 1
+                fm[key].append(d)
+                i = j
+                continue
+            else:
+                fm[key].append(_scalar(item))
+        elif key is not None and isinstance(fm.get(key), str):
+            fm[key] = (fm[key] + " " + line.strip()).strip()
+        i += 1
+    return fm, body
+
+
+def _canon_items(items: list) -> list:
+    out = []
+    for it in items or []:
+        if isinstance(it, dict):
+            d = {ITEM_ALIASES.get(k, k): v for k, v in it.items()}
+            if "type" in d:
+                t = str(d["type"]).lower()
+                d["type"] = VALUE_ALIASES.get(t, t)
+            out.append(d)
+        else:
+            out.append(it)
+    return out
+
+
+def normalise(fm: dict, extra_key_aliases: dict | None = None) -> dict:
+    """Map aliased keys/values to canonical Mosaix vocabulary."""
+    aliases = dict(KEY_ALIASES)
+    if extra_key_aliases:
+        aliases.update(extra_key_aliases)
+    out: dict = {}
+    for k, v in fm.items():
+        canon = aliases.get(k, k)
+        if canon in out and canon != k:
+            continue
+        out[canon] = v
+    for k in ("entities", "relations"):
+        if isinstance(out.get(k), list):
+            out[k] = _canon_items(out[k])
+    for k in ("type", "status"):
+        if k in out and isinstance(out[k], str):
+            v2 = out[k].lower()
+            out[k] = VALUE_ALIASES.get(v2, v2)
+    return out

mosaix_format-1.2.1/src/mosaix/cli.py

@@ -0,0 +1,64 @@
+"""CLI: mosaix check <vault> [--json] [--check-rev] [--verbose]"""
+from __future__ import annotations
+
+import argparse
+import json as _json
+import sys
+from pathlib import Path
+
+from .validator import validate_vault
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="mosaix", description="Mosaix Format tools")
+    sub = parser.add_subparsers(dest="command")
+
+    check = sub.add_parser("check", help="Validate a vault")
+    check.add_argument("vault", type=Path)
+    check.add_argument("--json", action="store_true", help="Output JSON")
+    check.add_argument("--check-rev", action="store_true", help="Check rev digest")
+    check.add_argument("--verbose", action="store_true", help="Show all issues")
+    check.add_argument(
+        "--exclude",
+        default="",
+        metavar="PATHS",
+        help="Comma-separated path prefixes to exclude",
+    )
+
+    args = parser.parse_args()
+    if args.command is None:
+        parser.print_help()
+        sys.exit(0)
+
+    # command == "check"
+    vault = args.vault.resolve()
+    exclude = tuple(x.strip() for x in args.exclude.split(",") if x.strip())
+    report = validate_vault(vault, check_rev=args.check_rev, exclude=exclude)
+
+    if args.json:
+        data = {
+            "vault": str(vault),
+            "errors": [{"code": i.code, "message": i.message, "path": i.path} for i in report.errors],
+            "warnings": [{"code": i.code, "message": i.message, "path": i.path} for i in report.warnings],
+            "conformant": report.conformant,
+        }
+        print(_json.dumps(data, ensure_ascii=False, indent=2))
+    else:
+        status = "CONFORMANT" if report.conformant else "NOT CONFORMANT"
+        print(f"Mosaix audit — {vault}")
+        print(f"errors: {len(report.errors)}  warnings: {len(report.warnings)}  {status}")
+        for issue in report.errors:
+            print(f"  E  [{issue.code}] {issue.message}")
+        if args.verbose or not report.errors:
+            for issue in report.warnings:
+                print(f"  W  [{issue.code}] {issue.message}")
+
+    if report.errors:
+        sys.exit(1)
+    if report.warnings:
+        sys.exit(2)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

mosaix_format-1.2.1/src/mosaix/crud.py

@@ -0,0 +1,76 @@
+"""CRUD operations for Mosaix notes — stdlib only."""
+from __future__ import annotations
+
+import secrets
+import time
+from pathlib import Path
+from typing import Any
+
+from ._yaml import parse_frontmatter
+
+_CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+
+def _generate_ulid() -> str:
+    """Generate a ULID: 48-bit ms timestamp + 80-bit random, Crockford Base32."""
+    ts = int(time.time() * 1000) & 0xFFFFFFFFFFFF  # 48 bits
+    rand = secrets.randbits(80)
+    chars = [_CROCKFORD[(ts >> s) & 0x1F] for s in range(45, -1, -5)]
+    chars += [_CROCKFORD[(rand >> s) & 0x1F] for s in range(75, -1, -5)]
+    return "".join(chars)
+
+
+def create_note(path: Path | str, frontmatter: dict[str, Any], body: str = "") -> Path:
+    """Write a new Mosaix note. Auto-generates id (ULID) if absent. Raises FileExistsError if it already exists."""
+    path = Path(path)
+    if path.exists():
+        raise FileExistsError(path)
+    fm = dict(frontmatter)
+    if not fm.get("id"):
+        fm["id"] = _generate_ulid()
+    fm_block = _serialise_frontmatter(fm)
+    path.write_text(f"---\n{fm_block}---\n{body}", encoding="utf-8")
+    return path
+
+
+def update_frontmatter(path: Path | str, changes: dict[str, Any]) -> None:
+    """Rewrite only the frontmatter of a note, leaving the body byte-identical."""
+    path = Path(path)
+    text = path.read_text(encoding="utf-8")
+    fm_raw, body = parse_frontmatter(text)
+    if fm_raw is None:
+        raise ValueError(f"{path}: note has no frontmatter")
+    fm_raw.update(changes)
+    fm_block = _serialise_frontmatter(fm_raw)
+    # body from parse_frontmatter already starts with \n (the separator after ---)
+    path.write_text(f"---\n{fm_block}---{body}", encoding="utf-8")
+
+
+def delete_note(path: Path | str) -> None:  # noqa: ARG001
+    raise NotImplementedError("Use supersede, don't delete (R7)")
+
+
+# ---------- internal serialiser ----------
+
+def _serialise_frontmatter(fm: dict[str, Any]) -> str:
+    lines = []
+    for k, v in fm.items():
+        if isinstance(v, list):
+            if not v:
+                lines.append(f"{k}:")
+            else:
+                lines.append(f"{k}:")
+                for item in v:
+                    if isinstance(item, dict):
+                        pairs = ", ".join(f"{ik}: {iv}" for ik, iv in item.items())
+                        lines.append(f"  - {{{pairs}}}")
+                    else:
+                        lines.append(f"  - {item}")
+        elif v is None:
+            lines.append(f"{k}:")
+        else:
+            sv = str(v)
+            if any(c in sv for c in (':', '#', '[', ']', '{', '}')):
+                sv = f'"{sv}"'
+            lines.append(f"{k}: {sv}")
+    return "\n".join(lines) + "\n"

mosaix_format-1.2.1/src/mosaix/graph.py

@@ -0,0 +1,145 @@
+"""VaultGraph: orphans, broken_links, connected components — stdlib only."""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from ._yaml import parse_frontmatter, normalise
+
+WIKILINK = re.compile(r"(?<!!)\[\[([^\]|#]+)(?:#[^\]|]*)?(?:\|[^\]]*)?\]\]")
+ULID_RE = re.compile(r"^[0-7][0-9A-HJKMNP-TV-Z]{25}$")
+EXCLUDED_DIRS = {"_inbox", "_private", ".obsidian", ".git", "node_modules", ".trash", "__pycache__", ".vault-ingest"}
+
+META_NAMES = {"conventions", "metodo e convenzioni", "claude", "readme", "taxonomy", "tag index", "tassonomia", "indice tag"}
+META_DIRS = {"_meta", "99-meta", "meta"}
+LEDGER_NAMES = {"open questions", "assunzioni da confermare", "domande aperte"}
+MOC_NAMES = {"home", "00-index", "index", "00-indice", "indice"}
+
+
+class VaultGraph:
+    """Directed link graph over a Mosaix vault."""
+
+    def __init__(self, vault: Path | str) -> None:
+        self.vault = Path(vault)
+        self._stems: dict[str, Path] = {}         # stem → path
+        self._id_to_stem: dict[str, str] = {}     # ULID id → stem
+        self._edges: dict[str, set[str]] = {}     # stem → {stem, ...} (outgoing)
+        self._incoming: dict[str, set[str]] = {}  # stem → {stem, ...}
+        self._types: dict[str, str | None] = {}   # stem → type field
+        self._build()
+
+    def _build(self) -> None:
+        files: list[tuple[Path, str]] = []
+        for p in self.vault.rglob("*.md"):
+            rel_parts = p.relative_to(self.vault).parts
+            if any(part in EXCLUDED_DIRS for part in rel_parts[:-1]):
+                continue
+            self._stems[p.stem] = p
+            files.append((p, p.stem))
+
+        for p, stem in files:
+            text = p.read_text(encoding="utf-8", errors="replace")
+            fm_raw, body = parse_frontmatter(text)
+            fm = normalise(fm_raw) if fm_raw else {}
+            if isinstance(fm.get("id"), str):
+                self._id_to_stem[fm["id"]] = stem
+            self._types[stem] = (fm.get("type") or None)
+            self._edges.setdefault(stem, set())
+            self._incoming.setdefault(stem, set())
+
+        for p, stem in files:
+            text = p.read_text(encoding="utf-8", errors="replace")
+            fm_raw, body = parse_frontmatter(text)
+            fm = normalise(fm_raw) if fm_raw else {}
+
+            # wikilinks in body
+            for target in WIKILINK.findall(body):
+                t = target.strip().split("/")[-1]
+                if t in self._stems:
+                    self._edges[stem].add(t)
+                    self._incoming.setdefault(t, set()).add(stem)
+
+            # frontmatter links
+            for link in fm.get("links", []) or []:
+                t = str(link).strip()
+                if ULID_RE.match(t) and t in self._id_to_stem:
+                    dest = self._id_to_stem[t]
+                elif t in self._stems:
+                    dest = t
+                else:
+                    continue
+                self._edges[stem].add(dest)
+                self._incoming.setdefault(dest, set()).add(stem)
+
+    # ------------------------------------------------------------------
+
+    def _is_structural(self, stem: str) -> bool:
+        """Return True if the note is a MOC, meta note, or ledger (excluded from orphan check)."""
+        s = stem.lower()
+        if s in META_NAMES or s in LEDGER_NAMES or s in MOC_NAMES:
+            return True
+        path = self._stems[stem]
+        if path.parent.name.lower() in META_DIRS:
+            return True
+        typ = (self._types.get(stem) or "").lower()
+        if typ in {"moc", "meta", "ledger"}:
+            return True
+        return False
+
+    def orphans(self) -> list[Path]:
+        """Notes with no incoming links, excluding MOC, meta, and ledger notes."""
+        return [
+            self._stems[s]
+            for s in self._stems
+            if not self._incoming.get(s) and not self._is_structural(s)
+        ]
+
+    def broken_links(self) -> list[tuple[Path, str]]:
+        """(source_path, target_stem) pairs where target_stem is not in the vault."""
+        broken = []
+        for p in self.vault.rglob("*.md"):
+            rel_parts = p.relative_to(self.vault).parts
+            if any(part in EXCLUDED_DIRS for part in rel_parts[:-1]):
+                continue
+            text = p.read_text(encoding="utf-8", errors="replace")
+            _, body = parse_frontmatter(text)
+            for target in WIKILINK.findall(body):
+                t = target.strip().split("/")[-1]
+                if "." not in t and t not in self._stems:
+                    broken.append((p, target.strip()))
+        return broken
+
+    def components(self) -> list[list[Path]]:
+        """Connected components (undirected). Returns list of groups, largest first."""
+        undirected: dict[str, set[str]] = {s: set() for s in self._stems}
+        for src, dests in self._edges.items():
+            for d in dests:
+                undirected[src].add(d)
+                undirected.setdefault(d, set()).add(src)
+
+        visited: set[str] = set()
+        groups: list[list[Path]] = []
+        for stem in self._stems:
+            if stem in visited:
+                continue
+            stack = [stem]
+            component: list[Path] = []
+            while stack:
+                node = stack.pop()
+                if node in visited:
+                    continue
+                visited.add(node)
+                if node in self._stems:
+                    component.append(self._stems[node])
+                for nbr in undirected.get(node, set()):
+                    if nbr not in visited:
+                        stack.append(nbr)
+            groups.append(component)
+        groups.sort(key=len, reverse=True)
+        return groups
+
+    def note_count(self) -> int:
+        return len(self._stems)
+
+    def edge_count(self) -> int:
+        return sum(len(dests) for dests in self._edges.values())

mosaix_format-1.2.1/src/mosaix/parser.py

@@ -0,0 +1,86 @@
+"""parse_note(path) → Note dataclass."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from ._yaml import parse_frontmatter, normalise
+
+
+@dataclass
+class Entity:
+    name: str
+    type: str
+
+
+@dataclass
+class Relation:
+    from_: str  # 'from' is a Python keyword
+    type: str
+    to: str
+
+
+@dataclass
+class Note:
+    path: Path
+    title: str
+    id: str | None
+    updated: str | None
+    tags: list[str]
+    summary: str | None
+    keywords: list[str]
+    entities: list[Entity]
+    relations: list[Relation]
+    links: list[str]
+    rev: str | None
+    body: str
+    frontmatter_raw: dict | None = field(repr=False)
+
+    @property
+    def frontmatter(self) -> dict:
+        return self.frontmatter_raw or {}
+
+
+def _to_entity(d: Any) -> Entity:
+    if isinstance(d, dict):
+        return Entity(name=str(d.get("name", "")), type=str(d.get("type", "")))
+    return Entity(name=str(d), type="")
+
+
+def _to_relation(d: Any) -> Relation:
+    if isinstance(d, dict):
+        return Relation(
+            from_=str(d.get("from", d.get("from_", ""))),
+            type=str(d.get("type", "")),
+            to=str(d.get("to", "")),
+        )
+    return Relation(from_="", type=str(d), to="")
+
+
+def parse_note(path: Path | str) -> Note:
+    """Parse a single Mosaix-format markdown file into a Note."""
+    path = Path(path)
+    text = path.read_text(encoding="utf-8", errors="replace")
+    fm_raw, body = parse_frontmatter(text)
+    fm = normalise(fm_raw) if fm_raw is not None else {}
+
+    def _list(key: str) -> list:
+        v = fm.get(key)
+        return v if isinstance(v, list) else ([] if v is None else [v])
+
+    return Note(
+        path=path,
+        title=str(fm.get("title", path.stem)),
+        id=fm.get("id") or None,
+        updated=fm.get("updated") or None,
+        tags=_list("tags"),
+        summary=fm.get("summary") or None,
+        keywords=_list("keywords"),
+        entities=[_to_entity(e) for e in _list("entities")],
+        relations=[_to_relation(r) for r in _list("relations")],
+        links=[str(x) for x in _list("links")],
+        rev=fm.get("rev") or None,
+        body=body,
+        frontmatter_raw=fm_raw,
+    )

mosaix_format-1.2.1/src/mosaix/validator.py

@@ -0,0 +1,307 @@
+"""validate_note(note) and validate_vault(path) → Report."""
+from __future__ import annotations
+
+import hashlib
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ._yaml import parse_frontmatter, normalise
+
+CORE_KEYS = ("title", "updated", "tags", "summary", "keywords", "rev")
+ENTITY_TYPES = {"person", "company", "product", "project", "tool", "place", "document", "event"}
+ULID_RE = re.compile(r"^[0-7][0-9A-HJKMNP-TV-Z]{25}$")
+WIKILINK = re.compile(r"(?<!!)\[\[([^\]|#]+)(?:#[^\]|]*)?(?:\|[^\]]*)?\]\]")
+EMBED = re.compile(r"!\[\[([^\]|#]+)(?:#[^\]|]*)?(?:\|[^\]]*)?\]\]")
+BODY_TAG = re.compile(r"(?<![\w/&])#((?![0-9A-Fa-f]{3,8}\b)[A-Za-z][A-Za-z0-9_/\-]*)")
+RELIABILITY_MARKERS = ("✅", "⚠️", "🟢", "🟡", "❌", "status:", "sourced", "to-confirm",
+                       "da fonte", "da confermare", "affidabilita", "affidabilità")
+EXCLUDED_DIRS = {"_inbox", "_private", ".obsidian", ".git", "node_modules", ".trash", "__pycache__", ".vault-ingest"}
+META_NAMES = {"conventions", "metodo e convenzioni", "claude", "readme", "taxonomy", "tag index", "tassonomia", "indice tag"}
+META_DIRS = {"_meta", "99-meta", "meta"}
+LEDGER_NAMES = {"open questions", "assunzioni da confermare", "domande aperte"}
+MOC_NAMES = {"home", "00-index", "index", "00-indice", "indice"}
+
+
+@dataclass
+class Issue:
+    code: str
+    message: str
+    path: str | None = None
+
+
+@dataclass
+class Report:
+    errors: list[Issue] = field(default_factory=list)
+    warnings: list[Issue] = field(default_factory=list)
+
+    @property
+    def conformant(self) -> bool:
+        return not self.errors
+
+    @property
+    def is_conformant(self) -> bool:
+        return not self.errors
+
+    def _e(self, code: str, path: str | None, **kw: object) -> None:
+        msg = _MESSAGES_E.get(code, code)
+        try:
+            msg = msg.format(**kw)
+        except (KeyError, IndexError):
+            pass
+        self.errors.append(Issue(code=code, message=msg, path=path))
+
+    def _w(self, code: str, path: str | None, **kw: object) -> None:
+        msg = _MESSAGES_W.get(code, code)
+        try:
+            msg = msg.format(**kw)
+        except (KeyError, IndexError):
+            pass
+        self.warnings.append(Issue(code=code, message=msg, path=path))
+
+
+_MESSAGES_E: dict[str, str] = {
+    "E001": "{rel}: no frontmatter",
+    "E002": "{rel}: missing `{key}`",
+    "E003": "{rel}: summary length {len} (120–240)",
+    "E004": "{rel}: keywords count {count} (6–8)",
+    "E005": "{rel}: entity type `{type}` not allowed",
+    "E006": "{rel}: broken link [[{target}]]",
+    "E007": "{rel}: orphan (no incoming link)",
+    "E008": "{rel}: links id `{ulid}` does not resolve to any note",
+    "E009": "{rel}: links target `{target}` does not exist",
+    "E010": "{rel}: document with {count} fragments (≥2)",
+    "E011": "{rel}: fragment `{fragment}` does not exist",
+    "E012": "vault: no MOC note (type: moc, or Home/00-Index)",
+    "E013": "vault: no meta note (§5.4)",
+    "E014": "vault: no open-questions ledger (§5.3)",
+    "E015": "vault: entities coverage {n}/{total} = {pct} (<80%)",
+}
+_MESSAGES_W: dict[str, str] = {
+    "W001": "{rel}: {count} entities (>12); is this one question? (R1)",
+    "W002": "{rel}: relation type `{type}` not in relation_types",
+    "W003": "{rel}: missing `id` (required from v2.0; generate a ULID)",
+    "W004": "{rel}: `id` is not a valid ULID: `{value}`",
+    "W005": "{rel}: tag #{tag} not declared in meta note",
+    "W006": "meta note declares no tags: taxonomy check skipped",
+    "W007": "{rel}: no reliability marker",
+    "W008": "{rel}: rev may be stale (hint only)",
+}
+
+
+def validate_note(note, *, entity_types: set[str] | None = None) -> Report:
+    """Validate a single Note against Mosaix rules. Returns a Report."""
+    from .parser import Note  # local to avoid circular at module level
+    report = Report()
+    rel = str(note.path)
+    et = entity_types or ENTITY_TYPES
+
+    if note.frontmatter_raw is None:
+        report._e("E001", rel, rel=rel)
+        return report
+
+    fm = normalise(note.frontmatter_raw)
+
+    for k in CORE_KEYS:
+        if k == "title":
+            continue
+        if not fm.get(k) and fm.get(k) != 0:
+            report._e("E002", rel, rel=rel, key=k)
+
+    s = str(fm.get("summary", ""))
+    if s and not (120 <= len(s) <= 240):
+        report._e("E003", rel, rel=rel, len=len(s))
+
+    kw = fm.get("keywords", [])
+    if isinstance(kw, list) and kw and not (6 <= len(kw) <= 8):
+        report._e("E004", rel, rel=rel, count=len(kw))
+
+    ents = fm.get("entities", [])
+    if isinstance(ents, list):
+        for e in ents:
+            if isinstance(e, dict) and str(e.get("type", "")).lower() not in et:
+                report._e("E005", rel, rel=rel, type=e.get("type"))
+
+    note_id = fm.get("id")
+    if not note_id:
+        report._w("W003", rel, rel=rel)
+    elif not ULID_RE.match(str(note_id)):
+        report._w("W004", rel, rel=rel, value=note_id)
+
+    text = (note.frontmatter_raw or {})
+    body_and_fm = note.body + " " + " ".join(f"{k}:{v}" for k, v in fm.items())
+    if not any(m in body_and_fm for m in RELIABILITY_MARKERS):
+        report._w("W007", rel, rel=rel)
+
+    return report
+
+
+def validate_vault(path: Path | str, *, check_rev: bool = False, exclude: tuple[str, ...] = ()) -> Report:
+    """Validate an entire vault directory. Wraps audit() logic."""
+    from collections import defaultdict
+    vault = Path(path)
+    report = Report()
+    notes: dict[str, dict] = {}
+    all_md: dict[str, Path] = {}
+
+    files = []
+    for p in vault.rglob("*.md"):
+        rel_parts = p.relative_to(vault).parts
+        rel = "/".join(rel_parts)
+        all_md.setdefault(p.stem, p)
+        if any(part in EXCLUDED_DIRS for part in rel_parts[:-1]):
+            continue
+        if any(rel.startswith(x) for x in exclude):
+            continue
+        files.append((p, rel_parts, rel))
+
+    meta_decl: dict = {}
+    for p, rel_parts, rel in files:
+        is_meta = p.stem.lower() in META_NAMES or any(part.lower() in META_DIRS for part in rel_parts[:-1])
+        if not is_meta:
+            continue
+        fm, _ = parse_frontmatter(p.read_text(encoding="utf-8", errors="replace"))
+        if fm and "mosaix" in fm:
+            meta_decl = fm
+            break
+
+    extra_aliases = meta_decl.get("aliases") if isinstance(meta_decl.get("aliases"), dict) else {}
+    entity_types = set(ENTITY_TYPES) | {str(t).lower() for t in (meta_decl.get("entity_types") or [])}
+    payload = tuple(str(x) for x in (meta_decl.get("payload") or []))
+    relation_types = {str(t).lower() for t in (meta_decl.get("relation_types") or [])}
+
+    for p, rel_parts, rel in files:
+        if any(rel.startswith(x) for x in payload):
+            continue
+        text = p.read_text(encoding="utf-8", errors="replace")
+        fm, body = parse_frontmatter(text)
+        if fm is not None:
+            fm = normalise(fm, extra_aliases)
+        is_meta = p.stem.lower() in META_NAMES or any(part.lower() in META_DIRS for part in rel_parts[:-1])
+        notes[p.stem] = {"path": p, "fm": fm, "body": body, "rel": rel, "is_meta": is_meta}
+
+    id_to_stem: dict[str, str] = {}
+    for name, n in notes.items():
+        if n["fm"] and isinstance(n["fm"].get("id"), str):
+            id_to_stem[n["fm"]["id"]] = name
+
+    incoming: dict[str, int] = defaultdict(int)
+    declared_tags: set[str] = {str(t) for t in (meta_decl.get("tags") or [])}
+    has_moc = has_meta = has_ledger = False
+    entity_count = 0
+
+    for name, n in notes.items():
+        fm, body, rel = n["fm"], n["body"], n["rel"]
+        low = name.lower()
+        if n["is_meta"]:
+            has_meta = True
+            declared_tags |= set(BODY_TAG.findall(body))
+            declared_tags |= set(re.findall(r"`#([A-Za-z0-9_/\-]+)`", body))
+        if low in LEDGER_NAMES:
+            has_ledger = True
+
+        for target in set(WIKILINK.findall(body)) | set(EMBED.findall(body)):
+            t = target.strip().split("/")[-1]
+            if t in all_md:
+                incoming[t] += 1
+            elif "." not in t:
+                report._e("E006", rel, rel=rel, target=target)
+
+        if fm is None:
+            report._e("E001", rel, rel=rel)
+            continue
+
+        ntype = str(fm.get("type", "")).lower()
+        if ntype == "moc" or "moc" in low or low in MOC_NAMES:
+            has_moc = True
+
+        for k in CORE_KEYS:
+            if k == "title":
+                continue
+            if not fm.get(k) and fm.get(k) != 0:
+                report._e("E002", rel, rel=rel, key=k)
+
+        s = str(fm.get("summary", ""))
+        if s and not (120 <= len(s) <= 240):
+            report._e("E003", rel, rel=rel, len=len(s))
+        kw = fm.get("keywords", [])
+        if isinstance(kw, list) and kw and not (6 <= len(kw) <= 8):
+            report._e("E004", rel, rel=rel, count=len(kw))
+
+        ents = fm.get("entities", [])
+        if isinstance(ents, list) and ents:
+            entity_count += 1
+            if len(ents) > 12 and ntype != "moc" and not n["is_meta"]:
+                report._w("W001", rel, rel=rel, count=len(ents))
+            for e in ents:
+                if isinstance(e, dict) and str(e.get("type", "")).lower() not in entity_types:
+                    report._e("E005", rel, rel=rel, type=e.get("type"))
+
+        if relation_types:
+            for r in fm.get("relations", []) or []:
+                if isinstance(r, dict) and str(r.get("type", "")).lower() not in relation_types:
+                    report._w("W002", rel, rel=rel, type=r.get("type"))
+
+        note_id = fm.get("id")
+        if not note_id:
+            report._w("W003", rel, rel=rel)
+        elif not ULID_RE.match(str(note_id)):
+            report._w("W004", rel, rel=rel, value=note_id)
+
+        for target in fm.get("links", []) or []:
+            t = str(target).strip()
+            if ULID_RE.match(t):
+                if t in id_to_stem:
+                    incoming[id_to_stem[t]] += 1
+                else:
+                    report._e("E008", rel, rel=rel, ulid=t)
+            elif t in all_md:
+                incoming[t] += 1
+            else:
+                report._e("E009", rel, rel=rel, target=t)
+
+        if ntype == "document":
+            frags = fm.get("fragments", []) or []
+            if len(frags) < 2:
+                report._e("E010", rel, rel=rel, count=len(frags))
+            for f in frags:
+                if str(f) not in all_md:
+                    report._e("E011", rel, rel=rel, fragment=f)
+
+        if n["is_meta"]:
+            declared_tags |= {str(t) for t in (fm.get("tags", []) or [])}
+        n["tags"] = set(BODY_TAG.findall(body)) | {str(t) for t in (fm.get("tags", []) or [])}
+
+        body_and_fm = body + " " + " ".join(f"{k}:{v}" for k, v in fm.items())
+        if not any(m in body_and_fm for m in RELIABILITY_MARKERS):
+            report._w("W007", rel, rel=rel)
+
+        if check_rev and fm.get("rev"):
+            digest = hashlib.sha256(body.strip().encode("utf-8")).hexdigest()[:12]
+            if digest != str(fm["rev"]):
+                report._w("W008", rel, rel=rel)
+
+    for name, n in notes.items():
+        low = name.lower()
+        if incoming.get(name, 0) == 0 and not n["is_meta"] and low not in LEDGER_NAMES and "moc" not in low and low not in MOC_NAMES:
+            report._e("E007", n["rel"], rel=n["rel"])
+
+    if declared_tags:
+        for name, n in notes.items():
+            for t in n.get("tags", set()):
+                if t not in declared_tags and not t.startswith(("type/", "status/", "tipo/", "stato/")):
+                    report._w("W005", n["rel"], rel=n["rel"], tag=t)
+    else:
+        report._w("W006", None)
+
+    if not has_moc:
+        report._e("E012", None)
+    if not has_meta:
+        report._e("E013", None)
+    if not has_ledger:
+        report._e("E014", None)
+    if notes and entity_count / len(notes) < 0.80:
+        report._e("E015", None, n=entity_count, total=len(notes), pct=f"{entity_count/len(notes):.0%}")
+
+    return report

mosaix_format-1.2.1/src/mosaix_format.egg-info/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: mosaix-format
+Version: 1.2.1
+Summary: Python library for the Mosaix Format
+Author-email: Andrea Fiorino <andrea@alfagomma.dev>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# mosaix
+
+Python library for the [Mosaix Format](https://mosaix.io) — stdlib only, no dependencies.
+
+## Install (editable)
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```python
+from mosaix import parse_note, validate_vault, VaultGraph
+
+note = parse_note("path/to/note.md")
+print(note.title, note.id)
+
+report = validate_vault("path/to/vault")
+print(report.conformant, len(report.errors))
+
+g = VaultGraph("path/to/vault")
+print(g.orphans())
+print(g.components())
+```
+
+## CLI
+
+```bash
+mosaix check <vault_dir>
+mosaix check <vault_dir> --json
+mosaix check <vault_dir> --check-rev --exclude=exports
+```
+
+Exit codes: `0` clean · `1` errors · `2` warnings only.
+
+## Modules
+
+| Module | Purpose |
+|---|---|
+| `parser.py` | `parse_note(path) → Note` |
+| `validator.py` | `validate_note(note)`, `validate_vault(path) → Report` |
+| `crud.py` | `create_note()`, `update_frontmatter()`, `delete_note()` (raises) |
+| `graph.py` | `VaultGraph`: orphans, broken_links, components |
+| `_yaml.py` | Minimal YAML parser (internal, extracted from audit_reference.py) |
+| `cli.py` | `mosaix check` entry point |
+
+## License
+
+MIT © 2026 Andrea Fiorino

mosaix_format-1.2.1/src/mosaix_format.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+src/mosaix/__init__.py
+src/mosaix/_yaml.py
+src/mosaix/cli.py
+src/mosaix/crud.py
+src/mosaix/graph.py
+src/mosaix/parser.py
+src/mosaix/validator.py
+src/mosaix_format.egg-info/PKG-INFO
+src/mosaix_format.egg-info/SOURCES.txt
+src/mosaix_format.egg-info/dependency_links.txt
+src/mosaix_format.egg-info/entry_points.txt
+src/mosaix_format.egg-info/top_level.txt
+tests/test_crud_graph.py
+tests/test_parser.py
+tests/test_validator.py

mosaix_format-1.2.1/src/mosaix_format.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mosaix_format-1.2.1/src/mosaix_format.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mosaix = mosaix.cli:main

mosaix_format-1.2.1/src/mosaix_format.egg-info/top_level.txt

@@ -0,0 +1 @@
+mosaix

mosaix_format-1.2.1/tests/test_crud_graph.py

@@ -0,0 +1,142 @@
+"""Tests for mosaix.crud and mosaix.graph."""
+from __future__ import annotations
+
+import hashlib
+import re
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from mosaix import parse_note, create_note, update_frontmatter, delete_note, VaultGraph
+
+ULID_RE = re.compile(r"^[0-7][0-9A-HJKMNP-TV-Z]{25}$")
+
+# Conformance fixtures live two directories above mosaix-py
+CONFORMANCE = Path(__file__).parent.parent.parent / "tests" / "conformance"
+VALID_VAULT = CONFORMANCE / "valid"
+ORPHAN_VAULT = CONFORMANCE / "edge-cases" / "e007_orphan_vault"
+
+
+# ---------- CRUD tests ----------
+
+def test_create_note_generates_ulid(tmp_path):
+    p = tmp_path / "note.md"
+    fm = {
+        "title": "Test",
+        "updated": "2026-09-09",
+        "tags": ["test"],
+        "summary": "x" * 120,
+        "keywords": ["a", "b", "c", "d", "e", "f"],
+        "rev": "abc123",
+    }
+    create_note(p, fm)
+    note = parse_note(p)
+    assert note.id is not None, "id should have been auto-generated"
+    assert ULID_RE.match(note.id), f"id {note.id!r} is not a valid ULID"
+
+
+def test_create_note_preserves_explicit_id(tmp_path):
+    p = tmp_path / "note.md"
+    explicit = "01JZZZZZZZZZZZZZZZZZZZZZZA"
+    create_note(p, {"title": "T", "id": explicit})
+    note = parse_note(p)
+    assert note.id == explicit
+
+
+def test_create_note_frontmatter_round_trip(tmp_path):
+    p = tmp_path / "note.md"
+    fm = {
+        "title": "Round Trip",
+        "updated": "2026-09-09",
+        "tags": ["alpha", "beta"],
+        "summary": "y" * 130,
+        "keywords": ["k1", "k2", "k3", "k4", "k5", "k6"],
+        "rev": "deadbeef",
+    }
+    create_note(p, fm, body="Hello world.\n")
+    note = parse_note(p)
+    assert note.title == "Round Trip"
+    assert note.tags == ["alpha", "beta"]
+    assert len(note.keywords) == 6
+    assert ULID_RE.match(note.id)
+
+
+def test_update_frontmatter_body_byte_identical(tmp_path):
+    p = tmp_path / "note.md"
+    body = "Hello\nworld\n\nParagraph with special chars: €, ñ, 日本語.\n"
+    create_note(p, {"title": "Body Test", "rev": "000"}, body=body)
+
+    # Body string as parse_frontmatter returns it (what update_frontmatter preserves)
+    note_before = parse_note(p)
+    h_before = hashlib.sha256(note_before.body.encode("utf-8")).hexdigest()
+
+    update_frontmatter(p, {"rev": "111", "status": "sourced"})
+
+    note_after = parse_note(p)
+    h_after = hashlib.sha256(note_after.body.encode("utf-8")).hexdigest()
+
+    assert h_before == h_after, "body changed after update_frontmatter"
+
+
+def test_update_frontmatter_changes_applied(tmp_path):
+    p = tmp_path / "note.md"
+    create_note(p, {"title": "Old", "rev": "aaa"})
+    update_frontmatter(p, {"title": "New", "rev": "bbb"})
+    note = parse_note(p)
+    assert note.title == "New"
+
+
+def test_delete_note_raises(tmp_path):
+    p = tmp_path / "del.md"
+    with pytest.raises(NotImplementedError):
+        delete_note(p)
+
+
+# ---------- Graph tests ----------
+
+def test_valid_vault_zero_orphans():
+    assert VALID_VAULT.exists(), f"missing fixture: {VALID_VAULT}"
+    g = VaultGraph(VALID_VAULT)
+    orphans = g.orphans()
+    assert orphans == [], f"unexpected orphans: {[o.name for o in orphans]}"
+
+
+def test_valid_vault_zero_broken_links():
+    assert VALID_VAULT.exists(), f"missing fixture: {VALID_VAULT}"
+    g = VaultGraph(VALID_VAULT)
+    broken = g.broken_links()
+    assert broken == [], f"unexpected broken links: {broken}"
+
+
+def test_orphan_vault_detects_orphan():
+    assert ORPHAN_VAULT.exists(), f"missing fixture: {ORPHAN_VAULT}"
+    g = VaultGraph(ORPHAN_VAULT)
+    orphans = g.orphans()
+    stems = {o.stem for o in orphans}
+    assert "orphan_note" in stems, f"orphan_note not detected; got: {stems}"
+
+
+def test_orphan_vault_excludes_structural():
+    """MOC, meta, and ledger notes must not appear in orphans()."""
+    assert ORPHAN_VAULT.exists(), f"missing fixture: {ORPHAN_VAULT}"
+    g = VaultGraph(ORPHAN_VAULT)
+    orphan_stems = {o.stem for o in g.orphans()}
+    assert "moc" not in orphan_stems
+    assert "conventions" not in orphan_stems
+    assert "open questions" not in orphan_stems
+
+
+def test_graph_note_and_edge_count():
+    assert VALID_VAULT.exists(), f"missing fixture: {VALID_VAULT}"
+    g = VaultGraph(VALID_VAULT)
+    assert g.note_count() > 0
+    assert g.edge_count() > 0
+
+
+def test_graph_components_non_empty():
+    assert VALID_VAULT.exists(), f"missing fixture: {VALID_VAULT}"
+    g = VaultGraph(VALID_VAULT)
+    comps = g.components()
+    assert len(comps) > 0
+    assert all(len(c) > 0 for c in comps)

mosaix_format-1.2.1/tests/test_parser.py

@@ -0,0 +1,72 @@
+"""Smoke tests for mosaix.parser."""
+import textwrap
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from mosaix import parse_note, Note
+
+
+SAMPLE = textwrap.dedent("""\
+    ---
+    title: Test Note
+    id: 01JZZZZZZZZZZZZZZZZZZZZZZA
+    updated: "2026-09-09"
+    tags: [test, mosaix]
+    summary: This is a test summary that must be between 120 and 240 characters long, so here is some additional padding text to make it reach the minimum.
+    keywords: [alpha, beta, gamma, delta, epsilon, zeta]
+    rev: abc123def456
+    ---
+    Body content here.
+""")
+
+
+def _write_tmp(content: str) -> Path:
+    tmp = tempfile.NamedTemporaryFile(suffix=".md", delete=False, mode="w", encoding="utf-8")
+    tmp.write(content)
+    tmp.close()
+    return Path(tmp.name)
+
+
+def test_parse_returns_note():
+    p = _write_tmp(SAMPLE)
+    note = parse_note(p)
+    assert isinstance(note, Note)
+    p.unlink()
+
+
+def test_parse_title():
+    p = _write_tmp(SAMPLE)
+    note = parse_note(p)
+    assert note.title == "Test Note"
+    p.unlink()
+
+
+def test_parse_id():
+    p = _write_tmp(SAMPLE)
+    note = parse_note(p)
+    assert note.id == "01JZZZZZZZZZZZZZZZZZZZZZZA"
+    p.unlink()
+
+
+def test_parse_keywords():
+    p = _write_tmp(SAMPLE)
+    note = parse_note(p)
+    assert len(note.keywords) == 6
+    p.unlink()
+
+
+def test_parse_no_frontmatter():
+    p = _write_tmp("Just body text, no frontmatter.")
+    note = parse_note(p)
+    assert note.frontmatter_raw is None
+    assert note.body == "Just body text, no frontmatter."
+    p.unlink()
+
+
+def test_parse_body():
+    p = _write_tmp(SAMPLE)
+    note = parse_note(p)
+    assert "Body content here" in note.body
+    p.unlink()

mosaix_format-1.2.1/tests/test_validator.py

@@ -0,0 +1,12 @@
+"""Conformance test: validate_vault on the canonical valid corpus."""
+from pathlib import Path
+
+from mosaix import validate_vault
+
+VALID_VAULT = Path(__file__).parent.parent.parent / "tests" / "conformance" / "valid"
+
+
+def test_valid_vault_is_conformant():
+    report = validate_vault(VALID_VAULT)
+    errors = [f"{i.code}: {i.message}" for i in report.errors]
+    assert report.is_conformant, f"Unexpected errors:\n" + "\n".join(errors)