scriptoria 0.9.0__tar.gz → 0.11.0__tar.gz

{scriptoria-0.9.0 → scriptoria-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: scriptoria
-Version: 0.9.0
+Version: 0.11.0
 Summary: Deterministic scriptorium-keeper (the `scrip` CLI): staleness, provenance integrity, and fact queries for an agent-compiled knowledge base
 Project-URL: Homepage, https://github.com/coredipper/scriptorium
 Project-URL: Changelog, https://github.com/coredipper/scriptorium/blob/main/CHANGELOG.md
@@ -51,6 +51,7 @@ uv run --project scrip scrip --help
 
 | Command | What it does |
 |---|---|
+| `scrip init [DIR]` | Create the root skeleton — `vault/{raw,facts,wiki}/` plus the `.kb/` cache and its manifest — in `DIR` (default: the current directory). Idempotent in an existing root; refuses to nest a new instance inside one. |
 | `scrip status` | Report `STALE` / `OK` / `UNCOMPILED` artifacts from the dependency graph. `--no-cache` recomputes from files; `--rebuild-manifest` regenerates the cache. |
 | `scrip verify` | Check every provenance anchor still resolves to text in its source; check referenced sources exist and `claim_id`s are unique. Fails on `BROKEN` and `AMBIGUOUS` by default; `--allow-ambiguous` downgrades `AMBIGUOUS` to a warning. |
 | `scrip query [claims\|entities\|edges\|contradictions\|reconciliations]` | Structured query over `vault/facts/*.ndjson` via DuckDB. `--sql "<duckdb>"`, `--where`, `--limit`. |
@@ -67,7 +68,8 @@ uv run --project scrip scrip --help
 | `scrip pageindex search "<question>" [--source raw/<slug>]` | Search cached PageIndex sections, returning only snippets mapped back to canonical `vault/raw/` text. |
 | `scrip watch` / `scrip unlock` | Watch vault health in a poll loop; clear a stale advisory write lock. |
 
-Every command accepts `--root DIR` and `--json`.
+Every command accepts `--root DIR` and `--json` (`init` takes its target as a
+positional path instead of `--root`).
 
 The optional `scrip-harness` package adds the model-bearing commands, including
 `scrip-harness answer "<question>"`, which gathers evidence with these primitives

{scriptoria-0.9.0 → scriptoria-0.11.0}/README.md

@@ -20,6 +20,7 @@ uv run --project scrip scrip --help
 
 | Command | What it does |
 |---|---|
+| `scrip init [DIR]` | Create the root skeleton — `vault/{raw,facts,wiki}/` plus the `.kb/` cache and its manifest — in `DIR` (default: the current directory). Idempotent in an existing root; refuses to nest a new instance inside one. |
 | `scrip status` | Report `STALE` / `OK` / `UNCOMPILED` artifacts from the dependency graph. `--no-cache` recomputes from files; `--rebuild-manifest` regenerates the cache. |
 | `scrip verify` | Check every provenance anchor still resolves to text in its source; check referenced sources exist and `claim_id`s are unique. Fails on `BROKEN` and `AMBIGUOUS` by default; `--allow-ambiguous` downgrades `AMBIGUOUS` to a warning. |
 | `scrip query [claims\|entities\|edges\|contradictions\|reconciliations]` | Structured query over `vault/facts/*.ndjson` via DuckDB. `--sql "<duckdb>"`, `--where`, `--limit`. |
@@ -36,7 +37,8 @@ uv run --project scrip scrip --help
 | `scrip pageindex search "<question>" [--source raw/<slug>]` | Search cached PageIndex sections, returning only snippets mapped back to canonical `vault/raw/` text. |
 | `scrip watch` / `scrip unlock` | Watch vault health in a poll loop; clear a stale advisory write lock. |
 
-Every command accepts `--root DIR` and `--json`.
+Every command accepts `--root DIR` and `--json` (`init` takes its target as a
+positional path instead of `--root`).
 
 The optional `scrip-harness` package adds the model-bearing commands, including
 `scrip-harness answer "<question>"`, which gathers evidence with these primitives

{scriptoria-0.9.0 → scriptoria-0.11.0}/pyproject.toml

@@ -2,7 +2,7 @@
 # Distribution name on PyPI is `scriptoria` (scrip/scriptorium were taken); the
 # CLI command and the import package both remain `scrip`.
 name = "scriptoria"
-version = "0.9.0"
+version = "0.11.0"
 description = "Deterministic scriptorium-keeper (the `scrip` CLI): staleness, provenance integrity, and fact queries for an agent-compiled knowledge base"
 readme = "README.md"
 requires-python = ">=3.10"

{scriptoria-0.9.0 → scriptoria-0.11.0}/src/scrip/__init__.py

@@ -13,7 +13,7 @@ from __future__ import annotations
 
 from pathlib import Path
 
-__version__ = "0.9.0"
+__version__ = "0.11.0"
 
 # --- canonical vault layout ------------------------------------------------
 # ``root`` is the repo/instance root: the directory containing ``vault/``.

{scriptoria-0.9.0 → scriptoria-0.11.0}/src/scrip/blocks.py

@@ -38,43 +38,45 @@ def split_blocks(text: str) -> list[dict]:
     # Use splitlines(keepends=True): its boundary set (form feed, NEL, U+2028/9,
     # …) is part of the deterministic segmentation contract — io.StringIO only
     # splits on \r/\n and would re-hash existing blocks that contain those chars.
-    ranges: list[list[int]] = []  # [start, end] per block
-    cur: list[int] | None = None
+    # Emit blocks in a single pass: a running [cur_start, cur_end] paragraph is
+    # flushed at each boundary, so no intermediate `ranges` list is allocated.
+    out: list[dict] = []
+    seen: dict[str, int] = {}
+
+    def emit(s: int, e: int) -> None:
+        slice_text = text[s:e]
+        out.append(
+            {
+                "block_id": _block_id(slice_text, seen),
+                "span": [s, e],
+                "hash": hashing.sha256_text(slice_text),
+            }
+        )
+
+    cur_start: int | None = None
+    cur_end = 0
     start = 0
 
     for line in text.splitlines(keepends=True):
         end = start + len(line)
         if _is_blank(line):
-            if cur is not None:
-                ranges.append(cur)
-                cur = None
+            if cur_start is not None:
+                emit(cur_start, cur_end)
+                cur_start = None
         elif _is_heading(line):
-            if cur is not None:
-                ranges.append(cur)
-                cur = None
-            ranges.append([start, end])  # a heading is its own block
+            if cur_start is not None:
+                emit(cur_start, cur_end)
+                cur_start = None
+            emit(start, end)  # a heading is its own block
         else:
-            if cur is None:
-                cur = [start, end]
-            else:
-                cur[1] = end
+            if cur_start is None:
+                cur_start = start
+            cur_end = end
         start = end
 
-    if cur is not None:
-        ranges.append(cur)
+    if cur_start is not None:
+        emit(cur_start, cur_end)
 
-    out: list[dict] = []
-    seen: dict[str, int] = {}
-    for s, e in ranges:
-        slice_text = text[s:e]
-        block_id = _block_id(slice_text, seen)
-        out.append(
-            {
-                "block_id": block_id,
-                "span": [s, e],
-                "hash": hashing.sha256_text(slice_text),
-            }
-        )
     return out
 
 

{scriptoria-0.9.0 → scriptoria-0.11.0}/src/scrip/cli.py

@@ -1,7 +1,7 @@
 """Command-line entry point for ``scrip``.
 
-Dispatches to the four subcommands. Logic modules (``graph``, ``anchors``,
-``query``) are imported lazily inside handlers so ``scrip --help`` works even
+Dispatches to the subcommands. Logic modules (``graph``, ``anchors``,
+``query``, ``neighbors``) are imported lazily inside handlers so ``scrip --help`` works even
 before those modules exist, and so importing the CLI never pulls in DuckDB
 unless a query is actually run.
 """
@@ -35,12 +35,20 @@ def _safe_slug(slug: str, what: str = "slug") -> str:
 # --------------------------------------------------------------------------- #
 # Root resolution
 # --------------------------------------------------------------------------- #
+def _looks_like_root(cand: Path) -> bool:
+    """True if ``cand`` looks like a scriptorium instance root: a directory
+    containing ``vault/`` plus either ``SPEC.md`` or ``.kb/``."""
+    return (cand / "vault").is_dir() and (
+        (cand / "SPEC.md").exists() or (cand / ".kb").is_dir()
+    )
+
+
 def resolve_root(root_arg: str | None) -> Path:
     """Return the scriptorium root.
 
     With ``--root`` the path is used verbatim (must be a directory). Otherwise we
-    walk up from the cwd for the nearest ancestor that looks like an instance: a
-    directory containing ``vault/`` plus either ``SPEC.md`` or ``.kb/``.
+    walk up from the cwd for the nearest ancestor that looks like an instance
+    (see :func:`_looks_like_root`).
     """
     if root_arg:
         root = Path(root_arg).expanduser().resolve()
@@ -50,13 +58,12 @@ def resolve_root(root_arg: str | None) -> Path:
 
     cur = Path.cwd().resolve()
     for cand in (cur, *cur.parents):
-        if (cand / "vault").is_dir() and (
-            (cand / "SPEC.md").exists() or (cand / ".kb").is_dir()
-        ):
+        if _looks_like_root(cand):
             return cand
     raise errors.UsageError(
         "could not locate a scriptorium root (looked for a parent with vault/ and "
-        "SPEC.md or .kb/). Pass --root explicitly."
+        "SPEC.md or .kb/). Run `scrip init` to start one here, or pass --root "
+        "explicitly."
     )
 
 
@@ -68,6 +75,58 @@ def _emit(payload: dict) -> None:
 # --------------------------------------------------------------------------- #
 # Subcommand handlers  ->  return an int exit code
 # --------------------------------------------------------------------------- #
+def cmd_init(args: argparse.Namespace) -> int:
+    from . import graph, manifest_path
+
+    target = Path(args.path or ".").expanduser().resolve()
+    if target.exists() and not target.is_dir():
+        raise errors.UsageError(f"init target is not a directory: {target}")
+    if _looks_like_root(target):
+        if args.json:
+            _emit({"root": str(target), "status": "exists", "created": []})
+        else:
+            print(f"already a scriptorium root: {target} (nothing to do)")
+        return 0
+    # Refuse to create a nested instance: an inner vault/ would shadow the outer
+    # root for every command run beneath it (resolve_root stops at the nearest
+    # ancestor).
+    for cand in target.parents:
+        if _looks_like_root(cand):
+            raise errors.UsageError(
+                f"refusing to create a nested scriptorium: {target} is inside the "
+                f"root at {cand}. Run `scrip init` at that root, or pick a "
+                f"directory outside it."
+            )
+
+    created: list[str] = []
+    for rel in ("vault/raw", "vault/facts", "vault/wiki", ".kb"):
+        d = target / rel
+        if d.is_dir():
+            continue
+        if d.exists():
+            raise errors.UsageError(
+                f"cannot create {rel}/: a file already exists at {d}"
+            )
+        d.mkdir(parents=True, exist_ok=True)
+        created.append(rel + "/")
+    # Same as `scrip status --rebuild-manifest`: scan the (empty) vault and write
+    # the .kb/manifest.json cache, so the instance starts warm and detectable.
+    graph.compute_status(target, rebuild=True)
+    created.append(str(manifest_path(target).relative_to(target)))
+
+    if args.json:
+        _emit({"root": str(target), "status": "initialized", "created": created})
+    else:
+        print(f"initialized scriptorium root at {target}")
+        for c in created:
+            print(f"  + {c}")
+        print(
+            "  next: add a source (`scrip ingest <url|file>`), compile a page "
+            "(`scrip new` + `scrip anchor` + `scrip stamp`), then `scrip verify`"
+        )
+    return 0
+
+
 def cmd_status(args: argparse.Namespace) -> int:
     from . import graph
 
@@ -197,6 +256,25 @@ def cmd_query(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_neighbors(args: argparse.Namespace) -> int:
+    from . import neighbors
+
+    root = resolve_root(args.root)
+    result = neighbors.neighborhood(
+        root,
+        args.node,
+        depth=args.depth,
+        kinds=args.kind,
+        direction=args.direction,
+        limit=args.limit,
+    )
+    if args.json:
+        _emit(result)
+    else:
+        neighbors.print_neighborhood(result)
+    return 0
+
+
 def cmd_index(args: argparse.Namespace) -> int:
     from . import embeddings
 
@@ -460,12 +538,13 @@ def cmd_fact_add(args: argparse.Namespace) -> int:
     root = resolve_root(args.root)
     if args.file:
         try:
-            text = Path(args.file).read_text(encoding="utf-8")
+            with Path(args.file).open(encoding="utf-8", newline="\n") as f:
+                proposals = facts.parse_ndjson(f)
         except OSError as e:
             raise errors.UsageError(f"cannot read --file: {e}") from e
     else:
-        text = sys.stdin.read()
-    result = facts.add(root, args.table, facts.parse_ndjson(text))
+        proposals = facts.parse_ndjson(sys.stdin)
+    result = facts.add(root, args.table, proposals)
     if args.json:
         _emit(result)
     else:
@@ -555,6 +634,21 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("--version", action="version", version=f"scrip {__version__}")
     sub = p.add_subparsers(dest="command", required=True, metavar="<command>")
 
+    pinit = sub.add_parser(
+        "init",
+        help="create the root skeleton (vault/{raw,facts,wiki}/ + .kb/ cache) and its manifest",
+    )
+    pinit.add_argument(
+        "path",
+        nargs="?",
+        metavar="DIR",
+        help="directory to initialize (default: current directory; created if absent)",
+    )
+    pinit.add_argument(
+        "--json", action="store_true", help="machine-readable JSON output"
+    )
+    pinit.set_defaults(func=cmd_init)
+
     ps = sub.add_parser(
         "status",
         parents=[common],
@@ -631,6 +725,25 @@ def build_parser() -> argparse.ArgumentParser:
     pq.add_argument("--limit", type=int, help="row limit for a named query")
     pq.set_defaults(func=cmd_query)
 
+    pn = sub.add_parser(
+        "neighbors",
+        parents=[common],
+        help="show one node's edges within N hops of facts/graph.ndjson",
+    )
+    pn.add_argument("node", help="an entity id (entity/<slug>) or any edge src/dst id")
+    pn.add_argument("--depth", type=int, default=1, help="hops to walk, 1-3 (default 1)")
+    pn.add_argument(
+        "--kind", action="append", help="only follow edges of this kind (repeatable)"
+    )
+    pn.add_argument(
+        "--direction",
+        choices=["both", "out", "in"],
+        default="both",
+        help="follow outgoing, incoming, or both (default both)",
+    )
+    pn.add_argument("--limit", type=int, default=50, help="max edges shown (default 50)")
+    pn.set_defaults(func=cmd_neighbors)
+
     pi = sub.add_parser(
         "index",
         parents=[common],

{scriptoria-0.9.0 → scriptoria-0.11.0}/src/scrip/facts.py

@@ -21,7 +21,7 @@ from __future__ import annotations
 
 import json
 import re
-from collections.abc import Iterator
+from collections.abc import Iterable, Iterator
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -91,15 +91,18 @@ def _iter_lf_lines(text: str) -> Iterator[str]:
         start = end + 1
 
 
-def parse_ndjson(text: str) -> list[dict]:
-    """Parse proposed records (one JSON object per line). Malformed input is a
+def parse_ndjson(source: str | Iterable[str]) -> list[dict]:
+    """Parse proposed records (one JSON object per line). ``source`` is the whole
+    input as a string, or an iterable of lines such as a file opened with
+    ``newline="\n"`` (streamed, never read whole). Malformed input is a
     :class:`DataError` with its line number; an empty input is a usage error."""
     records: list[dict] = []
     # Split on "\n" only, not str.splitlines(): NDJSON records are newline-
     # delimited and may legally contain U+2028/U+2029/NEL inside a JSON string,
     # which splitlines() would wrongly treat as record breaks. trailing \r (from
     # \r\n) and the trailing empty element from a final newline are dropped below.
-    for lineno, raw_line in enumerate(_iter_lf_lines(text), start=1):
+    lines = _iter_lf_lines(source) if isinstance(source, str) else source
+    for lineno, raw_line in enumerate(lines, start=1):
         line = raw_line.strip()
         if not line:
             continue
@@ -412,10 +415,7 @@ def _load_meta(root: Path) -> dict:
 
 def _write_meta(root: Path, data: dict, new_sources: list[str]) -> None:
     derived = list(data.get("derived-from") or [])
-    for sid in new_sources:
-        if sid not in derived:
-            derived.append(sid)
-    data["derived-from"] = derived
+    data["derived-from"] = list(dict.fromkeys(derived + new_sources))
     # Drop the stamp on EVERY append: with an unchanged derived-from the
     # recomputed input-hash would still match the stored one, and status would
     # report OK over facts nobody has blessed. Removing input-hash forces STALE
@@ -596,12 +596,12 @@ def add(root: Path, table: str, proposals: list[dict]) -> dict:
                 if not ends_with_newline:
                     f.write("\n")
                 f.write(payload)
-            new_sources: list[str] = []
+            new_sources_dict: dict[str, None] = {}
             if table in ("claims", "edges"):
                 for rec in appended:
                     sid = rec.get("source_id")  # cited edges carry one; bare edges don't
-                    if sid and sid not in new_sources:
-                        new_sources.append(sid)
-            _write_meta(root, meta, new_sources)
+                    if sid:
+                        new_sources_dict[sid] = None
+            _write_meta(root, meta, list(new_sources_dict.keys()))
 
     return {"table": table, "appended": appended, "skipped": skipped, "failures": []}

scriptoria-0.11.0/src/scrip/neighbors.py

@@ -0,0 +1,166 @@
+"""Focused neighborhood views over ``facts/graph.ndjson``.
+
+``scrip query edges`` dumps the whole edge list; past a few dozen edges that is
+the usual unreadable hairball. This module answers the narrower question "what
+is connected to this one node, within N hops?" — deterministic, read-only, and
+read through the same DuckDB lens as ``scrip query`` so the two cannot drift.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from pathlib import Path
+
+from . import facts_dir
+from . import query as query_mod
+from .errors import DataError, UsageError
+
+MAX_DEPTH = 3
+DIRECTIONS = ("both", "out", "in")
+
+
+def _has_rows(path: Path) -> bool:
+    if not path.exists():
+        return False
+    with path.open(encoding="utf-8") as f:
+        return any(line.strip() for line in f)
+
+
+def _load(root: Path, name: str, fname: str) -> list[dict]:
+    # An absent or empty table is simply no rows: DuckDB has no view for it.
+    if not _has_rows(facts_dir(root) / fname):
+        return []
+    _, rows = query_mod.run(root, name=name)
+    return rows
+
+
+def _node_summary(node: str, entity: dict | None) -> dict:
+    out: dict = {"id": node}
+    if entity:
+        out["name"] = entity.get("name")
+        out["kind"] = entity.get("kind")
+    return out
+
+
+def neighborhood(
+    root: Path,
+    node: str,
+    *,
+    depth: int = 1,
+    kinds: list[str] | None = None,
+    direction: str = "both",
+    limit: int = 50,
+) -> dict:
+    """Return the edges within ``depth`` hops of ``node`` and the nodes they touch
+    (entity name/kind when the node is an entity, else id only).
+
+    Walks breadth-first; each edge is reported once, at the hop it is first
+    reached. Order is deterministic: by hop, then ``src``, ``dst``, ``kind``.
+    ``truncated`` is true when ``limit`` cut edges off."""
+    if not 1 <= depth <= MAX_DEPTH:
+        raise UsageError(f"--depth must be between 1 and {MAX_DEPTH}")
+    if direction not in DIRECTIONS:
+        raise UsageError(f"--direction must be one of: {', '.join(DIRECTIONS)}")
+    if limit < 1:
+        raise UsageError("--limit must be at least 1")
+
+    entities = _load(root, "entities", "entities.ndjson")
+    edges = _load(root, "edges", "graph.ndjson")
+    entity_by_id = {
+        str(e["entity_id"]): e for e in entities if isinstance(e.get("entity_id"), str)
+    }
+    wanted = set(kinds) if kinds else None
+
+    out_adj: dict[str, list[int]] = {}
+    in_adj: dict[str, list[int]] = {}
+    known = set(entity_by_id)
+    for i, e in enumerate(edges):
+        src, dst = str(e.get("src") or ""), str(e.get("dst") or "")
+        known.update((src, dst))
+        if wanted is not None and e.get("kind") not in wanted:
+            continue
+        out_adj.setdefault(src, []).append(i)
+        in_adj.setdefault(dst, []).append(i)
+    if node not in known:
+        raise DataError(f"no such node: {node}")
+
+    seen_edges: set[int] = set()
+    found: list[tuple[int, int]] = []  # (hop, edge index)
+    visited = {node}
+    frontier: deque[tuple[str, int]] = deque([(node, 0)])
+    while frontier:
+        cur, hop = frontier.popleft()
+        if hop == depth:
+            continue
+        steps: list[tuple[int, str]] = []
+        if direction in ("both", "out"):
+            steps += [(i, str(edges[i].get("dst") or "")) for i in out_adj.get(cur, [])]
+        if direction in ("both", "in"):
+            steps += [(i, str(edges[i].get("src") or "")) for i in in_adj.get(cur, [])]
+        for i, other in steps:
+            if i not in seen_edges:
+                seen_edges.add(i)
+                found.append((hop + 1, i))
+            if other not in visited:
+                visited.add(other)
+                frontier.append((other, hop + 1))
+
+    def _key(item: tuple[int, int]) -> tuple:
+        hop, i = item
+        e = edges[i]
+        return (hop, str(e.get("src") or ""), str(e.get("dst") or ""), str(e.get("kind") or ""))
+
+    found.sort(key=_key)
+    truncated = len(found) > limit
+    found = found[:limit]
+
+    out_edges: list[dict] = []
+    touched = {node}
+    for hop, i in found:
+        e = edges[i]
+        rec = {"src": e.get("src"), "dst": e.get("dst"), "kind": e.get("kind"), "hop": hop}
+        for key in ("source_id", "anchor"):
+            if e.get(key):
+                rec[key] = e[key]
+        out_edges.append(rec)
+        touched.update((str(rec["src"]), str(rec["dst"])))
+
+    return {
+        "root": node,
+        "depth": depth,
+        "nodes": [_node_summary(n, entity_by_id.get(n)) for n in sorted(touched)],
+        "edges": out_edges,
+        "truncated": truncated,
+    }
+
+
+def print_neighborhood(result: dict) -> None:
+    names = {n["id"]: n for n in result["nodes"]}
+    root = result["root"]
+
+    def _label(node: str) -> str:
+        ent = names.get(node, {})
+        bits = [ent.get("name") or "", f"({ent['kind']})" if ent.get("kind") else ""]
+        return " ".join(b for b in bits if b)
+
+    print(f"{root}  {_label(root)}".rstrip())
+    rows = []
+    for e in result["edges"]:
+        src, dst = str(e["src"]), str(e["dst"])
+        if src == root:
+            arrow, other = "->", dst
+        elif dst == root:
+            arrow, other = "<-", src
+        else:
+            arrow, other = f"{src} ->", dst
+        cite = f"  [cited {e['source_id']}#{e['anchor']}]" if e.get("anchor") else ""
+        indent = "  " * e["hop"]
+        rows.append(f"{indent}{arrow} {e['kind']}  {other}  {_label(other)}".rstrip() + cite)
+    for line in rows:
+        print(line)
+    n_edges, n_nodes = len(result["edges"]), len(result["nodes"])
+    more = " (truncated; raise --limit)" if result["truncated"] else ""
+    print(
+        f"{n_edges} edge{'s' if n_edges != 1 else ''}, "
+        f"{n_nodes} node{'s' if n_nodes != 1 else ''} (depth {result['depth']}){more}"
+    )

{scriptoria-0.9.0 → scriptoria-0.11.0}/tests/test_fact_cmd.py

@@ -47,32 +47,32 @@ def _run_add(kb, text, *extra):
     return cli.main(["fact", "add", "--file", str(p), "--root", str(kb.root), *extra])
 
 
-def _claims_lines(kb):
-    p = kb.root / "vault" / "facts" / "claims.ndjson"
+def _read_ndjson(p):
+    # Split on "\n" only: splitlines() also breaks on U+2028/U+2029/NEL, which
+    # are legal inside JSON strings and would split one record into fragments.
     if not p.exists():
         return []
-    return [json.loads(s) for s in p.read_text(encoding="utf-8").splitlines() if s.strip()]
+    return [json.loads(s) for s in p.read_text(encoding="utf-8").split("\n") if s.strip()]
+
+
+def _claims_lines(kb):
+    p = kb.root / "vault" / "facts" / "claims.ndjson"
+    return _read_ndjson(p)
 
 
 def _recs_lines(kb):
     p = kb.root / "vault" / "facts" / "reconciliations.ndjson"
-    if not p.exists():
-        return []
-    return [json.loads(s) for s in p.read_text(encoding="utf-8").splitlines() if s.strip()]
+    return _read_ndjson(p)
 
 
 def _graph_lines(kb):
     p = kb.root / "vault" / "facts" / "graph.ndjson"
-    if not p.exists():
-        return []
-    return [json.loads(s) for s in p.read_text(encoding="utf-8").splitlines() if s.strip()]
+    return _read_ndjson(p)
 
 
 def _entities_lines(kb):
     p = kb.root / "vault" / "facts" / "entities.ndjson"
-    if not p.exists():
-        return []
-    return [json.loads(s) for s in p.read_text(encoding="utf-8").splitlines() if s.strip()]
+    return _read_ndjson(p)
 
 
 def _write_ontology(kb, text):
@@ -240,6 +240,20 @@ def test_fact_add_reads_stdin(kb, monkeypatch):
     assert len(_claims_lines(kb)) == 1
 
 
+def test_fact_add_file_streams_crlf_and_u2028(kb):
+    # --file is streamed with newline="\n": CRLF endings are stripped and a raw
+    # U+2028 inside a JSON string does not split the record.
+    kb.add_raw("s", SRC)
+    text = _ndjson(
+        _claim("The quick brown fox jumps over the lazy dog.", object="a\u2028b"),
+        _claim("Caching answers beats recomputing them."),
+    ).replace("\n", "\r\n")
+    assert "\u2028" in text
+    rc = _run_add(kb, text)
+    assert rc == 0
+    assert [c["object"] for c in _claims_lines(kb)] == ["a\u2028b", "o"]
+
+
 def test_fact_add_json_reports_appended_records(kb, capsys):
     kb.add_raw("s", SRC)
     rc = _run_add(
@@ -513,7 +527,7 @@ def test_fact_add_entities_appends_and_conflicts(kb, capsys):
     rc = _run_add(kb, _ndjson(ent), "--table", "entities")
     assert rc == 0
     lines = (kb.root / "vault" / "facts" / "entities.ndjson").read_text(encoding="utf-8")
-    assert json.loads(lines.splitlines()[0])["entity_id"] == "entity/duckdb"
+    assert json.loads(lines.split("\n")[0])["entity_id"] == "entity/duckdb"
 
     # identical record is skipped; a conflicting one (same id, new name) fails
     assert _run_add(kb, _ndjson(ent), "--table", "entities") == 0
@@ -523,7 +537,7 @@ def test_fact_add_entities_appends_and_conflicts(kb, capsys):
     assert rc == 1
     [failure] = json.loads(capsys.readouterr().out)["failures"]
     assert failure["status"] == "ID_CONFLICT"
-    assert len(lines.splitlines()) == 1  # nothing else was appended
+    assert lines.count("\n") == 1  # nothing else was appended
 
 
 def test_fact_add_entities_accept_optional_uri_metadata(kb):
@@ -618,7 +632,7 @@ def test_fact_add_edges_appends_and_skips_duplicates(kb):
     assert _run_add(kb, _ndjson(edge), "--table", "edges") == 0
     assert _run_add(kb, _ndjson(edge), "--table", "edges") == 0
     lines = (kb.root / "vault" / "facts" / "graph.ndjson").read_text(encoding="utf-8")
-    assert len(lines.splitlines()) == 1
+    assert lines.count("\n") == 1
 
 
 # --------------------------------------------------------------------------- #

{scriptoria-0.9.0 → scriptoria-0.11.0}/tests/test_facts.py

@@ -1,3 +1,5 @@
+import io
+
 import pytest
 from scrip.errors import DataError, UsageError
 
@@ -46,3 +48,12 @@ def test_parse_ndjson_reports_line_number_on_bad_json():
 def test_parse_ndjson_empty_is_usage_error():
     with pytest.raises(UsageError):
         facts.parse_ndjson("  \n  \n")
+
+
+def test_parse_ndjson_accepts_line_iterable():
+    # A file opened with newline="\n" yields lines split on "\n" only, so
+    # U+2028 inside a string and \r\n endings parse the same as the str path.
+    text = '{"a": "x\u2028y"}\r\n\r\n{"b": 2}\n'
+    expected = facts.parse_ndjson(text)
+    assert facts.parse_ndjson(io.StringIO(text, newline="\n")) == expected
+    assert expected == [{"a": "x\u2028y"}, {"b": 2}]

scriptoria-0.11.0/tests/test_init_cmd.py

@@ -0,0 +1,102 @@
+"""`scrip init` — create the root skeleton (vault/ layers + .kb/ cache) so a new
+instance starts detectable and green. Idempotent in an existing root; refuses to
+nest a new instance inside an existing one."""
+
+import json
+
+from scrip import cli, manifest_path
+
+
+def test_init_creates_skeleton_and_manifest(tmp_path, capsys):
+    root = tmp_path / "kb"
+    assert cli.main(["init", str(root)]) == 0
+    for rel in ("vault/raw", "vault/facts", "vault/wiki", ".kb"):
+        assert (root / rel).is_dir()
+    # same effect as `scrip status --rebuild-manifest`: the cache exists
+    assert manifest_path(root).exists()
+    out = capsys.readouterr().out
+    assert f"initialized scriptorium root at {root}" in out
+    assert "scrip ingest" in out  # next-steps hint: ingest -> compile -> verify
+    assert "scrip verify" in out
+
+
+def test_init_defaults_to_cwd(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    assert cli.main(["init"]) == 0
+    assert (tmp_path / "vault" / "raw").is_dir()
+    assert (tmp_path / ".kb").is_dir()
+
+
+def test_init_then_commands_resolve_root_without_flags(tmp_path, monkeypatch):
+    """The dogfooding gap this command closes: after init, `scrip status` and
+    `scrip verify` run green from inside the new root with no --root."""
+    root = tmp_path / "kb"
+    assert cli.main(["init", str(root)]) == 0
+    monkeypatch.chdir(root)
+    assert cli.main(["status"]) == 0
+    assert cli.main(["verify"]) == 0
+
+
+def test_init_existing_root_is_noop(tmp_path, capsys):
+    root = tmp_path / "kb"
+    assert cli.main(["init", str(root)]) == 0
+    manifest_before = manifest_path(root).read_text(encoding="utf-8")
+    capsys.readouterr()
+    assert cli.main(["init", str(root)]) == 0
+    out = capsys.readouterr().out
+    assert f"already a scriptorium root: {root}" in out
+    # a true no-op: the manifest was not rewritten
+    assert manifest_path(root).read_text(encoding="utf-8") == manifest_before
+
+
+def test_init_detects_spec_marker_root_as_existing(kb, capsys):
+    """A root marked by SPEC.md (no .kb/ needed) counts as already initialized."""
+    assert cli.main(["init", str(kb.root)]) == 0
+    assert "already a scriptorium root" in capsys.readouterr().out
+
+
+def test_init_inside_existing_root_refused_exit_2(tmp_path):
+    root = tmp_path / "kb"
+    assert cli.main(["init", str(root)]) == 0
+    nested = root / "vault" / "raw" / "sub"
+    assert cli.main(["init", str(nested)]) == 2
+    # nothing was created for the refused nested instance
+    assert not nested.exists()
+
+
+def test_init_target_is_a_file_exit_2(tmp_path):
+    f = tmp_path / "notes.md"
+    f.write_text("hi\n", encoding="utf-8")
+    assert cli.main(["init", str(f)]) == 2
+
+
+def test_init_fills_in_missing_layers(tmp_path):
+    """A partial layout (vault/ alone is not a detectable root) is completed
+    rather than refused."""
+    root = tmp_path / "kb"
+    (root / "vault" / "raw").mkdir(parents=True)
+    assert cli.main(["init", str(root)]) == 0
+    for rel in ("vault/facts", "vault/wiki", ".kb"):
+        assert (root / rel).is_dir()
+
+
+def test_init_layer_path_is_a_file_refused_exit_2(tmp_path):
+    """A file squatting a layer path is refused cleanly (exit 2), not an
+    uncaught FileExistsError mapped to the internal-error exit code."""
+    root = tmp_path / "kb"
+    (root / "vault").mkdir(parents=True)
+    (root / "vault" / "facts").write_text("oops\n", encoding="utf-8")
+    assert cli.main(["init", str(root)]) == 2
+
+
+def test_init_json_shape(tmp_path, capsys):
+    root = tmp_path / "kb"
+    assert cli.main(["init", "--json", str(root)]) == 0
+    data = json.loads(capsys.readouterr().out)
+    assert set(data) == {"root", "status", "created"}
+    assert data["status"] == "initialized"
+    assert ".kb/manifest.json" in data["created"]
+    assert cli.main(["init", "--json", str(root)]) == 0
+    data = json.loads(capsys.readouterr().out)
+    assert data["status"] == "exists"
+    assert data["created"] == []

scriptoria-0.11.0/tests/test_neighbors_cmd.py

@@ -0,0 +1,139 @@
+"""`scrip neighbors` — a focused, read-only view of one node's edges within N hops
+of facts/graph.ndjson, instead of the whole-graph dump of `scrip query edges`."""
+
+import json
+
+from scrip import cli, neighbors
+
+
+def _write(kb, fname, rows):
+    p = kb.root / "vault" / "facts" / fname
+    p.write_text("".join(json.dumps(r, ensure_ascii=False) + "\n" for r in rows), encoding="utf-8")
+
+
+def _ent(slug, name=None, kind="system"):
+    return {"entity_id": f"entity/{slug}", "name": name or slug.title(), "kind": kind}
+
+
+def _edge(src, dst, kind="depends-on", **kw):
+    return {"src": f"entity/{src}", "dst": f"entity/{dst}", "kind": kind, **kw}
+
+
+def _graph(kb):
+    # a -> b -> c -> d, plus x -> a (incoming), a -alt-> e, and a cycle c -> a.
+    _write(kb, "entities.ndjson", [_ent(s) for s in "abcdex"])
+    _write(
+        kb,
+        "graph.ndjson",
+        [
+            _edge("a", "b"),
+            _edge("b", "c"),
+            _edge("c", "d"),
+            _edge("x", "a", "part-of"),
+            _edge("a", "e", "alternative-to"),
+            _edge("c", "a"),
+        ],
+    )
+
+
+def _pairs(result):
+    return [(e["src"], e["dst"], e["kind"]) for e in result["edges"]]
+
+
+def test_depth_one_both_directions(kb):
+    _graph(kb)
+    r = neighbors.neighborhood(kb.root, "entity/a")
+    assert r["root"] == "entity/a" and r["depth"] == 1 and r["truncated"] is False
+    assert _pairs(r) == [
+        ("entity/a", "entity/b", "depends-on"),
+        ("entity/a", "entity/e", "alternative-to"),
+        ("entity/c", "entity/a", "depends-on"),
+        ("entity/x", "entity/a", "part-of"),
+    ]
+    assert all(e["hop"] == 1 for e in r["edges"])
+    assert [n["id"] for n in r["nodes"]] == [
+        "entity/a", "entity/b", "entity/c", "entity/e", "entity/x",
+    ]
+
+
+def test_depth_two_reaches_second_hop_and_cycle_terminates(kb):
+    _graph(kb)
+    r = neighbors.neighborhood(kb.root, "entity/a", depth=2, direction="out")
+    assert _pairs(r) == [
+        ("entity/a", "entity/b", "depends-on"),
+        ("entity/a", "entity/e", "alternative-to"),
+        ("entity/b", "entity/c", "depends-on"),
+    ]
+    assert [e["hop"] for e in r["edges"]] == [1, 1, 2]
+    # depth 3 closes the c -> a cycle and reaches d, each edge once
+    r3 = neighbors.neighborhood(kb.root, "entity/a", depth=3, direction="out")
+    assert len(_pairs(r3)) == len(set(_pairs(r3))) == 5
+
+
+def test_kind_filter_and_direction_in(kb):
+    _graph(kb)
+    r = neighbors.neighborhood(kb.root, "entity/a", kinds=["part-of"])
+    assert _pairs(r) == [("entity/x", "entity/a", "part-of")]
+    r_in = neighbors.neighborhood(kb.root, "entity/a", direction="in")
+    assert {e["dst"] for e in r_in["edges"]} == {"entity/a"}
+
+
+def test_limit_sets_truncated(kb):
+    _graph(kb)
+    r = neighbors.neighborhood(kb.root, "entity/a", limit=2)
+    assert len(r["edges"]) == 2 and r["truncated"] is True
+
+
+def test_cited_edge_and_non_entity_node(kb):
+    _write(kb, "entities.ndjson", [_ent("a")])
+    _write(
+        kb,
+        "graph.ndjson",
+        [{"src": "entity/a", "dst": "raw/paper", "kind": "cites",
+          "source_id": "raw/paper", "anchor": "qh:ab|loc:0|len:5"}],
+    )
+    r = neighbors.neighborhood(kb.root, "raw/paper")
+    [edge] = r["edges"]
+    assert edge["anchor"] == "qh:ab|loc:0|len:5"
+    assert {"id": "raw/paper"} in r["nodes"]  # not an entity: id only
+
+
+def test_entity_without_edges(kb):
+    _write(kb, "entities.ndjson", [_ent("lonely")])
+    r = neighbors.neighborhood(kb.root, "entity/lonely")
+    assert r["edges"] == [] and [n["id"] for n in r["nodes"]] == ["entity/lonely"]
+
+
+def test_cli_unknown_node_is_data_error(kb, capsys):
+    _graph(kb)
+    assert cli.main(["neighbors", "entity/nope", "--root", str(kb.root)]) == 3
+    assert "no such node: entity/nope" in capsys.readouterr().err
+
+
+def test_cli_empty_facts_is_data_error(kb):
+    assert cli.main(["neighbors", "entity/a", "--root", str(kb.root)]) == 3
+
+
+def test_cli_depth_out_of_range_is_usage_error(kb):
+    _graph(kb)
+    assert cli.main(["neighbors", "entity/a", "--depth", "4", "--root", str(kb.root)]) == 2
+
+
+def test_cli_json_is_stable(kb, capsys):
+    _graph(kb)
+    args = ["neighbors", "entity/a", "--depth", "2", "--json", "--root", str(kb.root)]
+    assert cli.main(args) == 0
+    first = json.loads(capsys.readouterr().out)
+    assert cli.main(args) == 0
+    assert json.loads(capsys.readouterr().out) == first
+    assert set(first) == {"root", "depth", "nodes", "edges", "truncated"}
+
+
+def test_cli_text_output(kb, capsys):
+    _graph(kb)
+    assert cli.main(["neighbors", "entity/a", "--root", str(kb.root)]) == 0
+    out = capsys.readouterr().out.splitlines()
+    assert out[0] == "entity/a  A (system)"
+    assert "  -> depends-on  entity/b  B (system)" in out
+    assert "  <- part-of  entity/x  X (system)" in out
+    assert out[-1] == "4 edges, 5 nodes (depth 1)"

{scriptoria-0.9.0 → scriptoria-0.11.0}/uv.lock

@@ -1141,7 +1141,7 @@ wheels = [
 
 [[package]]
 name = "scriptoria"
-version = "0.9.0"
+version = "0.11.0"
 source = { editable = "." }
 dependencies = [
     { name = "duckdb" },