knott 0.1.0__py3-none-any.whl

knott/__init__.py

@@ -0,0 +1,26 @@
+"""Knott: a local, file-first knowledge layer for AI agents."""
+
+from knott.api import Knott, version
+from knott.errors import (
+    ConfigError,
+    KnottError,
+    PathNotFoundError,
+    PathOutsideVaultError,
+    VaultNotFoundError,
+)
+from knott.models import InitResult, Issue, SchemaInfo, Stats, ValidationResult
+
+__all__ = [
+    "ConfigError",
+    "InitResult",
+    "Issue",
+    "Knott",
+    "KnottError",
+    "PathNotFoundError",
+    "PathOutsideVaultError",
+    "SchemaInfo",
+    "Stats",
+    "ValidationResult",
+    "VaultNotFoundError",
+    "version",
+]

knott/_values.py

@@ -0,0 +1,50 @@
+"""Describing constructed YAML values in messages."""
+
+from __future__ import annotations
+
+import datetime as dt
+from typing import Any
+
+# Boolean spellings accepted as written; YAML 1.1 also reads yes/no/on/off as booleans.
+BOOLEAN_SPELLINGS = frozenset({"true", "True", "TRUE", "false", "False", "FALSE"})
+
+
+def kind(value: Any) -> str:
+    """Human name for the YAML kind of a constructed value (exact types, no subclasses)."""
+    if value is None:
+        return "null"
+    names: dict[type, str] = {
+        bool: "boolean",
+        int: "integer",
+        float: "number",
+        str: "string",
+        dt.datetime: "datetime",
+        dt.date: "date",
+        list: "list",
+        dict: "mapping",
+    }
+    return names.get(type(value), type(value).__name__)
+
+
+_MAX_SHOWN = 80
+
+
+def show(value: Any, raw: str | None = None) -> str:
+    """Render a value in backticks, preferring its source text when known."""
+    if raw is not None:
+        return f"`{_truncate(raw)}`"
+    if isinstance(value, list):
+        return "`[]`" if not value else f"`[…]` ({len(value)} items)"
+    if isinstance(value, dict):
+        return "`{}`" if not value else f"`{{…}}` ({len(value)} keys)"
+    if value is None:
+        return "`null`"
+    if type(value) is bool:
+        return "`true`" if value else "`false`"
+    if isinstance(value, dt.date):
+        return f"`{value.isoformat()}`"
+    return f"`{_truncate(str(value))}`"
+
+
+def _truncate(text: str) -> str:
+    return text if len(text) <= _MAX_SHOWN else text[: _MAX_SHOWN - 1] + "…"

knott/_yaml.py

@@ -0,0 +1,151 @@
+"""Safe YAML loading that also records source line numbers.
+
+Internal module: PyYAML nodes never leave it. Callers get plain Python data
+plus a map from key paths to line numbers and raw scalar text.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+import yaml
+
+KeyPath = tuple[str | int, ...]
+
+# Upper bound on nodes after alias expansion. Real frontmatter and schemas are
+# tiny; this only stops alias bombs (including via `<<` merge keys).
+MAX_EXPANDED_NODES = 100_000
+_STR_TAG = "tag:yaml.org,2002:str"
+
+_MARKDOWN_LINK_LINE = re.compile(r"\[[^\]]*\]\([^)]*\)")
+
+
+@dataclass(frozen=True)
+class Loc:
+    """Where a value sits in its source text.
+
+    ``line`` is 0-based within the parsed YAML text: the line of the mapping key
+    for mapping entries, or of the item itself for sequence items.
+    ``raw`` is the scalar's source text, when the value is a scalar.
+    """
+
+    line: int
+    raw: str | None
+
+
+@dataclass(frozen=True)
+class YamlDocument:
+    data: Any
+    locs: dict[KeyPath, Loc]
+
+
+class YamlParseError(Exception):
+    def __init__(self, message: str, line: int | None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.line = line  # 0-based within the parsed text, when known
+
+
+def load(text: str) -> YamlDocument:
+    """Parse one YAML document with ``SafeLoader``. Raises ``YamlParseError``."""
+    try:
+        loader = yaml.SafeLoader(text)
+    except yaml.reader.ReaderError as exc:
+        reader_line = text.count("\n", 0, exc.position)
+        raise YamlParseError(f"invalid YAML: {exc.reason}", reader_line) from exc
+    try:
+        node = loader.get_single_node()
+        if node is not None:
+            _check_expansion(node)
+        data = loader.construct_document(node) if node is not None else None
+    except yaml.MarkedYAMLError as exc:
+        mark = exc.problem_mark or exc.context_mark
+        line = mark.line if mark is not None else None
+        raise YamlParseError(_describe(exc, text, line), line) from exc
+    except yaml.YAMLError as exc:
+        raise YamlParseError(str(exc), None) from exc
+    except ValueError as exc:  # e.g. an impossible date such as 2026-13-45
+        raise YamlParseError(f"invalid value: {exc}", None) from exc
+    except RecursionError:
+        raise YamlParseError("invalid YAML: nesting is too deep", None) from None
+    except YamlParseError:
+        raise
+    except Exception as exc:  # PyYAML constructors can fail oddly, e.g. `!!bool nope`
+        raise YamlParseError(f"invalid YAML value: {exc!r}", None) from exc
+    finally:
+        loader.dispose()
+    locs: dict[KeyPath, Loc] = {}
+    if node is not None:
+        try:
+            _collect(node, (), locs)
+        except RecursionError:
+            raise YamlParseError("invalid YAML: nesting is too deep", None) from None
+    return YamlDocument(data=data, locs=locs)
+
+
+def _describe(exc: yaml.MarkedYAMLError, text: str, line: int | None) -> str:
+    parts = [p for p in (exc.context, exc.problem) if p]
+    message = "invalid YAML: " + ", ".join(parts) if parts else "invalid YAML"
+    lines = text.split("\n")
+    candidates = [line, line - 1] if line is not None else []
+    for candidate in candidates:
+        if 0 <= candidate < len(lines) and _MARKDOWN_LINK_LINE.search(lines[candidate]):
+            message += '; a Markdown link must be quoted in YAML, e.g. key: "[label](path.md)"'
+            break
+    return message
+
+
+def _check_expansion(root: yaml.Node) -> None:
+    """Reject documents whose alias expansion would be huge or recursive."""
+    sizes: dict[int, int] = {}
+    in_progress: set[int] = set()
+
+    def size(node: yaml.Node) -> int:
+        key = id(node)
+        if key in sizes:
+            return sizes[key]
+        if key in in_progress:
+            raise YamlParseError("invalid YAML: recursive alias", node.start_mark.line)
+        in_progress.add(key)
+        total = 1
+        if isinstance(node, yaml.MappingNode):
+            for key_node, value_node in node.value:
+                total += size(key_node) + size(value_node)
+                if total > MAX_EXPANDED_NODES:
+                    break
+        elif isinstance(node, yaml.SequenceNode):
+            for item in node.value:
+                total += size(item)
+                if total > MAX_EXPANDED_NODES:
+                    break
+        in_progress.discard(key)
+        if total > MAX_EXPANDED_NODES:
+            raise YamlParseError(
+                "invalid YAML: aliases expand to too many values", node.start_mark.line
+            )
+        sizes[key] = total
+        return total
+
+    size(root)
+
+
+def _collect(node: yaml.Node, path: KeyPath, locs: dict[KeyPath, Loc]) -> None:
+    # Walks aliased nodes once per path, so aliased fields get full metadata.
+    # Safe because _check_expansion already bounded the expanded size.
+    if isinstance(node, yaml.MappingNode):
+        for key_node, value_node in node.value:
+            # Only string keys: a boolean `true:` must not share locs with `"true":`.
+            if not isinstance(key_node, yaml.ScalarNode) or key_node.tag != _STR_TAG:
+                continue
+            child = (*path, key_node.value)
+            raw = value_node.value if isinstance(value_node, yaml.ScalarNode) else None
+            locs[child] = Loc(key_node.start_mark.line, raw)
+            _collect(value_node, child, locs)
+    elif isinstance(node, yaml.SequenceNode):
+        for index, item in enumerate(node.value):
+            child = (*path, index)
+            raw = item.value if isinstance(item, yaml.ScalarNode) else None
+            locs[child] = Loc(item.start_mark.line, raw)
+            _collect(item, child, locs)

knott/api.py

@@ -0,0 +1,197 @@
+"""The Knott API. The CLI is a thin adapter over this module."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Sequence
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _dist_version
+from pathlib import Path
+
+from knott import _yaml
+from knott.errors import ConfigError, PathNotFoundError, PathOutsideVaultError
+from knott.models import InitResult, Issue, SchemaInfo, Stats, ValidationResult
+from knott.schema.loader import SCHEMAS_DIR, load_schemas
+from knott.schema.validator import validate_entity
+from knott.vault.discovery import KNOTT_DIR, find_vault_root, iter_markdown
+from knott.vault.entity import MarkdownFile, read_markdown
+from knott.vault.links import ResolvedReference, resolve_reference
+
+CONFIG_FILE = Path(KNOTT_DIR) / "config.yaml"
+
+
+def version() -> str:
+    """The installed Knott version."""
+    try:
+        return _dist_version("knott")
+    except PackageNotFoundError:  # running from a source tree without install
+        return "0.0.0"
+
+
+class Knott:
+    """A Knott vault on disk."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = root
+
+    @classmethod
+    def open(cls, path: str | Path = ".") -> Knott:
+        """Open the vault containing ``path``, walking up to the nearest ``.knott/``.
+
+        Raises ``VaultNotFoundError``, ``PathNotFoundError`` or ``ConfigError``.
+        """
+        start = Path(path)
+        if not start.exists():
+            raise PathNotFoundError(f"path does not exist: {path}")
+        vault = cls(find_vault_root(start))
+        vault._check_config()
+        return vault
+
+    @staticmethod
+    def init(path: str | Path = ".") -> InitResult:
+        """Create ``.knott/schemas/`` and ``.knott/config.yaml`` in ``path``.
+
+        Changes nothing if ``.knott/`` already exists.
+        """
+        root = Path(path)
+        if not root.is_dir():
+            raise PathNotFoundError(f"directory does not exist: {path}")
+        knott_dir = root / KNOTT_DIR
+        if knott_dir.exists():
+            return InitResult(root=str(root.resolve()), created=False)
+        (root / SCHEMAS_DIR).mkdir(parents=True)
+        (root / CONFIG_FILE).write_text(f"knott_version: {version()}\n", encoding="utf-8")
+        return InitResult(root=str(root.resolve()), created=True)
+
+    def types(self) -> list[str]:
+        """Discovered type names, sorted. Schemas with errors may be missing."""
+        return [info.type for info in self.schemas()]
+
+    def schemas(self) -> list[SchemaInfo]:
+        """Discovered types with their description and schema file, sorted by type."""
+        registry, _ = load_schemas(self.root)
+        return [
+            SchemaInfo(type=s.type, description=s.description, path=s.path)
+            for _, s in sorted(registry.items())
+        ]
+
+    def schema_issues(self) -> list[Issue]:
+        """Problems found while loading schemas, sorted."""
+        _, issues = load_schemas(self.root)
+        return _sorted(issues)
+
+    def validate(self, paths: Sequence[str | Path] | None = None) -> ValidationResult:
+        """Validate all schemas, and entities (all, or those within ``paths``).
+
+        Relative ``paths`` are resolved against the vault root. Validation problems
+        are returned as data; only usage errors raise.
+        """
+        schemas, issues = load_schemas(self.root)
+        files: dict[str, MarkdownFile] = {}
+
+        def lookup(rel_path: str) -> MarkdownFile:
+            parsed = files.get(rel_path)
+            if parsed is None:
+                parsed = read_markdown(self.root / rel_path, rel_path)
+                files[rel_path] = parsed
+            return parsed
+
+        def resolve(source: str, reference: str) -> ResolvedReference:
+            return resolve_reference(self.root, source, reference)
+
+        all_markdown = iter_markdown(self.root)
+        if paths is None:
+            in_scope = all_markdown
+        else:
+            in_scope, scope_issues = self._scope(paths, all_markdown)
+            issues.extend(scope_issues)
+
+        entities = 0
+        relations = 0
+        for rel_path in in_scope:
+            parsed = lookup(rel_path)
+            if parsed.error is not None:
+                issues.append(
+                    Issue(
+                        code="entity-invalid-frontmatter",
+                        path=rel_path,
+                        line=parsed.error_line,
+                        message=parsed.error,
+                    )
+                )
+                continue
+            if not parsed.is_entity:
+                continue
+            entities += 1
+            report = validate_entity(parsed, schemas, resolve, lookup)
+            issues.extend(report.issues)
+            relations += report.relations
+
+        stats = Stats(schemas=len(schemas), entities=entities, relations=relations)
+        return ValidationResult(issues=_sorted(issues), stats=stats)
+
+    def _scope(
+        self,
+        paths: Sequence[str | Path],
+        all_markdown: list[str],
+    ) -> tuple[list[str], list[Issue]]:
+        selected: set[str] = set()
+        issues: list[Issue] = []
+        for given in paths:
+            candidate = Path(given)
+            if not candidate.is_absolute():
+                candidate = self.root / candidate
+            if not candidate.exists():
+                raise PathNotFoundError(f"path does not exist: {given}")
+            # Resolve symlinks in the parent only, so a symlinked file keeps its own path.
+            absolute = Path(os.path.abspath(candidate))
+            absolute = absolute.parent.resolve() / absolute.name
+            try:
+                rel = absolute.relative_to(self.root)
+            except ValueError:
+                raise PathOutsideVaultError(
+                    f"path is outside the vault {self.root}: {given}"
+                ) from None
+            rel_posix = rel.as_posix()
+            if absolute.is_dir():
+                prefix = "" if rel_posix == "." else rel_posix + "/"
+                selected.update(p for p in all_markdown if p.startswith(prefix))
+                continue
+            parsed = read_markdown(absolute, rel_posix) if rel_posix.endswith(".md") else None
+            if parsed is not None and (parsed.is_entity or parsed.error is not None):
+                selected.add(rel_posix)
+            else:
+                issues.append(
+                    Issue(
+                        code="not-an-entity",
+                        path=rel_posix,
+                        message=(
+                            "not a Knott entity: expected a Markdown file whose YAML "
+                            "frontmatter has a `type` key"
+                        ),
+                    )
+                )
+        return sorted(selected), issues
+
+    def _check_config(self) -> None:
+        config = self.root / CONFIG_FILE
+        if not config.exists():
+            return
+        try:
+            text = config.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError) as exc:
+            raise ConfigError(f"cannot read {CONFIG_FILE.as_posix()}: {exc}") from exc
+        try:
+            data = _yaml.load(text).data
+        except _yaml.YamlParseError as exc:
+            where = f":{exc.line + 1}" if exc.line is not None else ""
+            raise ConfigError(f"malformed {CONFIG_FILE.as_posix()}{where}: {exc.message}") from exc
+        if data is not None and not isinstance(data, dict):
+            raise ConfigError(f"malformed {CONFIG_FILE.as_posix()}: expected a YAML mapping")
+
+
+def _sorted(issues: list[Issue]) -> list[Issue]:
+    return sorted(
+        issues,
+        key=lambda i: (i.path, i.line or 0, i.field or "", i.code, i.message),
+    )

knott/cli.py

@@ -0,0 +1,140 @@
+"""Command-line interface: a thin adapter over ``knott.api``."""
+
+from __future__ import annotations
+
+import json
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from knott.api import Knott, version
+from knott.errors import KnottError
+from knott.models import Issue, ValidationResult
+
+app = typer.Typer(
+    name="knott",
+    help="Knott: typed Markdown entities, schemas, and semantic relations.",
+    add_completion=False,
+    no_args_is_help=True,
+    pretty_exceptions_enable=False,
+)
+
+EXIT_INVALID = 1
+EXIT_USAGE = 2
+
+
+class OutputFormat(StrEnum):
+    TEXT = "text"
+    JSON = "json"
+
+
+def _fail(error: KnottError) -> typer.Exit:
+    typer.echo(f"error: {error}", err=True)
+    return typer.Exit(EXIT_USAGE)
+
+
+def _plural(count: int, singular: str, plural: str) -> str:
+    return f"{count} {singular if count == 1 else plural}"
+
+
+def format_issue(issue: Issue) -> str:
+    location = issue.path if issue.line is None else f"{issue.path}:{issue.line}"
+    header = f"✗ {location}" + (f"  {issue.field}" if issue.field else "")
+    body = "\n".join(f"  {line}" for line in issue.message.splitlines())
+    return f"{header}\n{body}"
+
+
+def format_result(result: ValidationResult) -> str:
+    if result.ok:
+        stats = result.stats
+        return "\n".join(
+            [
+                f"✓ {_plural(stats.schemas, 'schema', 'schemas')}",
+                f"✓ {_plural(stats.entities, 'entity', 'entities')}",
+                f"✓ {_plural(stats.relations, 'relation', 'relations')}",
+                "✓ vault is valid",
+            ]
+        )
+    blocks = [format_issue(issue) for issue in result.issues]
+    summary = _plural(len(result.issues), "validation error", "validation errors")
+    return "\n\n".join([*blocks, summary])
+
+
+@app.command()
+def init(
+    path: Annotated[
+        Path, typer.Argument(help="Directory to initialize (default: current directory).")
+    ] = Path("."),
+) -> None:
+    """Create .knott/schemas/ and .knott/config.yaml."""
+    try:
+        result = Knott.init(path)
+    except KnottError as error:
+        raise _fail(error) from None
+    if result.created:
+        typer.echo(f"Initialized Knott vault in {result.root}")
+    else:
+        typer.echo(f"Knott vault already initialized in {result.root}")
+
+
+@app.command()
+def validate(
+    paths: Annotated[
+        list[Path] | None,
+        typer.Argument(help="Entity files or directories to check (default: the whole vault)."),
+    ] = None,
+    output: Annotated[
+        OutputFormat, typer.Option("--format", help="Output format.")
+    ] = OutputFormat.TEXT,
+) -> None:
+    """Validate schemas and entities."""
+    try:
+        start = paths[0] if paths else Path(".")
+        vault = Knott.open(start if start.exists() else Path("."))
+        result = vault.validate([p.absolute() for p in paths] if paths else None)
+    except KnottError as error:
+        raise _fail(error) from None
+    if output is OutputFormat.JSON:
+        payload = {
+            "ok": result.ok,
+            "stats": result.stats.model_dump(),
+            "issues": [issue.model_dump() for issue in result.issues],
+        }
+        typer.echo(json.dumps(payload, indent=2, ensure_ascii=False))
+    else:
+        typer.echo(format_result(result))
+    if not result.ok:
+        raise typer.Exit(EXIT_INVALID)
+
+
+@app.command()
+def types(
+    verbose: Annotated[
+        bool, typer.Option("--verbose", "-v", help="Show each type's schema file and description.")
+    ] = False,
+) -> None:
+    """List discovered entity types."""
+    try:
+        vault = Knott.open(".")
+    except KnottError as error:
+        raise _fail(error) from None
+    for info in vault.schemas():
+        if verbose:
+            typer.echo(f"{info.type}  ({info.path})")
+            if info.description:
+                for line in info.description.strip().splitlines():
+                    typer.echo(f"  {line}")
+        else:
+            typer.echo(info.type)
+    issues = vault.schema_issues()
+    if issues:
+        typer.echo("\n\n".join(format_issue(issue) for issue in issues), err=True)
+        raise typer.Exit(EXIT_INVALID)
+
+
+@app.command("version")
+def version_command() -> None:
+    """Print the installed Knott version."""
+    typer.echo(version())

knott/errors.py

@@ -0,0 +1,26 @@
+"""Exceptions for conditions that stop a run (CLI exit code 2).
+
+Validation problems are never raised; they are returned as ``Issue`` data.
+"""
+
+from __future__ import annotations
+
+
+class KnottError(Exception):
+    """Base class for usage and configuration errors."""
+
+
+class VaultNotFoundError(KnottError):
+    """No directory containing ``.knott/`` was found."""
+
+
+class ConfigError(KnottError):
+    """``.knott/config.yaml`` is unreadable or malformed."""
+
+
+class PathNotFoundError(KnottError):
+    """A path argument does not exist."""
+
+
+class PathOutsideVaultError(KnottError):
+    """A path argument lies outside the vault root."""

knott/models.py

@@ -0,0 +1,50 @@
+"""Public result types. All plain data."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class _Frozen(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class Issue(_Frozen):
+    """One validation problem."""
+
+    code: str
+    path: str
+    """Vault-relative POSIX path of the file with the problem."""
+    line: int | None = None
+    """1-based line number, when known."""
+    field: str | None = None
+    message: str
+
+
+class Stats(_Frozen):
+    schemas: int = 0
+    entities: int = 0
+    relations: int = 0
+
+
+class ValidationResult(_Frozen):
+    issues: list[Issue]
+    stats: Stats
+
+    @property
+    def ok(self) -> bool:
+        return not self.issues
+
+
+class SchemaInfo(_Frozen):
+    """A discovered entity type."""
+
+    type: str
+    description: str | None
+    path: str
+    """Vault-relative path of the schema file."""
+
+
+class InitResult(_Frozen):
+    root: str
+    created: bool