veridge 0.1.0__py3-none-any.whl

veridge/__init__.py

@@ -0,0 +1,20 @@
+"""Veridge — the always-fresh, low-token map of a whole project.
+
+Veridge indexes a project read-only into a typed graph that unifies four layers most
+tools keep apart:
+
+* **documents** (with references — including plain path mentions written in prose),
+* **code** down to the *symbol* (functions/classes), via pluggable parsers,
+* **decisions** (ADR / RFC / D-XXX ids found in docs), and
+* **sessions** (git commits and the files they touched).
+
+It then *ranks* the graph with PageRank, so queries can return the **minimal relevant
+subgraph within a token budget** — the cheap, accurate context an AI assistant needs to
+orient itself, and a map a human can read. The core has zero runtime dependencies.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

veridge/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m veridge`` as an alias for the ``veridge`` CLI."""
+
+from __future__ import annotations
+
+from veridge.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

veridge/budget.py

@@ -0,0 +1,59 @@
+"""Token budgeting: turn a ranking into the *most* context that fits a token ceiling.
+
+The point of Veridge is to hand an assistant the **minimal relevant slice** of a project,
+not the whole thing. Given a ranked list of node ids and a token budget, we greedily admit
+the highest-ranked nodes whose compact rows still fit. Token cost uses the standard ~4
+chars/token heuristic on the *compact row* an assistant would actually read — ids, kinds,
+sizes and edge counts, never file contents.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from veridge.model import Graph, Kind
+
+
+def estimate_tokens(text: str) -> int:
+    return max(1, round(len(text) / 4))
+
+
+def node_row(graph: Graph, nid: str) -> dict[str, Any]:
+    """A compact, contents-free row for one node (what an assistant reads)."""
+    n = graph.nodes[nid]
+    row: dict[str, Any] = {"id": n.id, "kind": n.kind.value}
+    if n.category:
+        row["cat"] = n.category.value
+    if n.kind is Kind.FILE:
+        row["size"] = int(n.meta.get("size", 0))
+    if n.kind is Kind.SYMBOL and n.meta.get("line"):
+        row["line"] = n.meta["line"]
+    row["deg"] = graph.degree(nid)
+    return row
+
+
+def _row_cost(row: dict[str, Any]) -> int:
+    # Approximate the serialized footprint the assistant pays for.
+    return estimate_tokens(",".join(f"{k}={v}" for k, v in row.items()))
+
+
+def select_within_budget(
+    graph: Graph, ranked_ids: list[str], budget_tokens: int,
+) -> tuple[list[dict[str, Any]], int]:
+    """Admit ranked nodes (best first) until the token budget is exhausted.
+
+    Returns ``(rows, used_tokens)``. Always returns at least the single best node, even if it
+    alone exceeds the budget, so a query never comes back empty.
+    """
+    rows: list[dict[str, Any]] = []
+    used = 0
+    for nid in ranked_ids:
+        if nid not in graph.nodes:
+            continue
+        row = node_row(graph, nid)
+        cost = _row_cost(row)
+        if rows and used + cost > budget_tokens:
+            break
+        rows.append(row)
+        used += cost
+    return rows, used

veridge/classify.py

@@ -0,0 +1,63 @@
+"""Classify a file into a (Kind.FILE, Category) from its path — generic and language-agnostic.
+
+Unlike a project-specific taxonomy, the rules here key on widely shared conventions
+(extensions, well-known names) so they work out of the box on any repository. They are
+intentionally simple and tunable.
+"""
+
+from __future__ import annotations
+
+import os
+
+from veridge.model import Category
+
+_CODE_EXTS = {
+    ".py", ".js", ".ts", ".tsx", ".jsx", ".mjs", ".cjs",
+    ".go", ".rs", ".java", ".kt", ".c", ".cc", ".cpp", ".h", ".hpp",
+    ".rb", ".php", ".cs", ".swift", ".scala", ".lua",
+    ".ps1", ".psm1", ".sh", ".bash", ".sql",
+}
+_DATA_EXTS = {
+    ".db", ".sqlite", ".sqlite3", ".duckdb", ".parquet", ".csv", ".tsv",
+    ".jsonl", ".ndjson",
+}
+_CONFIG_EXTS = {
+    ".toml", ".ini", ".cfg", ".conf", ".yaml", ".yml", ".env", ".json",
+    ".xml", ".properties",
+}
+_DOC_EXTS = {".md", ".markdown", ".rst", ".txt", ".pdf", ".html", ".htm", ".docx", ".adoc"}
+
+_STRUCTURE_NAMES = {
+    "readme", "readme.md", "readme.rst", "index.md", "architecture.md",
+    "changelog.md", "contributing.md", "license", "license.md", "authors", "notice",
+}
+_CONFIG_NAMES = {
+    ".gitignore", ".veridgeignore", "dockerfile", "makefile", "caddyfile",
+    ".editorconfig",
+}
+
+
+def _ext(name: str) -> str:
+    return os.path.splitext(name)[1].lower()
+
+
+def classify(rel_posix: str) -> Category:
+    """Return the Category for a file given its POSIX relative path."""
+    name = rel_posix.rsplit("/", 1)[-1]
+    low = name.lower()
+    ext = _ext(low)
+    parts = [p.lower() for p in rel_posix.split("/")]
+
+    if "memory" in parts or low.startswith("memory."):
+        return Category.MEMORY
+    if ext in _DATA_EXTS:
+        return Category.DATA
+    if ext in _CODE_EXTS:
+        return Category.CODE
+    if ext in _CONFIG_EXTS or low in _CONFIG_NAMES:
+        return Category.CONFIG
+    if low in _STRUCTURE_NAMES:
+        return Category.STRUCTURE
+    if ext in _DOC_EXTS or ext == "":
+        return Category.DOC
+    return Category.CONFIG

veridge/cli.py

@@ -0,0 +1,276 @@
+"""Command line: build, map, find, neighbors, focus, gate, stats.
+
+Read-only on your sources: commands only read the project and write derived files under
+``.veridge/``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from veridge import __version__, query, store
+from veridge.freshness import build_manifest, evaluate, index
+from veridge.model import Graph
+
+
+def _human(n: int) -> str:
+    f = float(n)
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if f < 1024 or unit == "TB":
+            return f"{f:.0f} {unit}" if unit == "B" else f"{f:.1f} {unit}"
+        f /= 1024
+    return f"{f:.1f} TB"
+
+
+def _load_or_build(path: str) -> Graph:
+    return store.load_graph(path) or index(path)[0]
+
+
+def cmd_build(args: argparse.Namespace) -> int:
+    g, m = index(args.path)
+    store.save(args.path, g, m)
+    c = g.counts()
+    print(f"built '{g.project}': {len(g.nodes)} nodes, {len(g.edges)} edges")
+    print("  nodes:", c["nodes"])
+    print("  edges:", c["edges"])
+    print(f"  store: {store.store_dir(args.path)}")
+    return 0
+
+
+def cmd_stats(args: argparse.Namespace) -> int:
+    g = _load_or_build(args.path)
+    c = g.counts()
+    print(f"'{g.project}': {len(g.nodes)} nodes, {len(g.edges)} edges")
+    for k, v in sorted(c["nodes"].items()):
+        print(f"  {k:9} {v}")
+    for k, v in sorted(c["edges"].items()):
+        print(f"  -{k:8} {v}")
+    return 0
+
+
+def cmd_map(args: argparse.Namespace) -> int:
+    m = query.project_map(_load_or_build(args.path))
+    if args.json:
+        print(json.dumps(m, ensure_ascii=False, indent=2))
+        return 0
+    print(f"{m['project']}: {m['files']} files · {m['symbols']} symbols · "
+          f"{m['areas']} areas · {m['edges']} edges · {_human(m['size'])}")
+    print("by area:")
+    for a in m["by_area"]:
+        print(f"  {a['area']:16} {a['files']:4} files  {_human(a['size']):>9}  "
+              f"[{', '.join(a['top_cats'])}]")
+    print("by layer:")
+    for ly in m["by_layer"]:
+        print(f"  {ly['layer']:11} {ly['files']:4} files  {_human(ly['size']):>9}")
+    print("most important (PageRank):")
+    for x in m["most_important"]:
+        print(f"  {x['score']:.4f}  {x['id']}  ({x['kind']})")
+    print(f"orphans: {m['orphans']} · broken refs: {m['broken_refs']}")
+    return 0
+
+
+def cmd_find(args: argparse.Namespace) -> int:
+    res = query.find(_load_or_build(args.path), args.query)
+    for r in res:
+        print(f"  {r['kind']:8} {r['id']}")
+    print(f"({len(res)} matches)")
+    return 0
+
+
+def cmd_neighbors(args: argparse.Namespace) -> int:
+    n = query.neighbors(_load_or_build(args.path), args.node)
+    if n is None:
+        print(f"node not found: {args.node}", file=sys.stderr)
+        return 1
+    print(f"{n['id']} ({n['kind']}) · {_human(n['size'])}")
+    if n["description"]:
+        print(f"  {n['description']}")
+    if n["broken_refs"]:
+        print(f"  broken refs: {n['broken_refs']}")
+    print(f"  outgoing ({len(n['outgoing'])}):")
+    for o in n["outgoing"]:
+        print(f"    -{o['edge']}-> {o['id']} ({o['kind']})")
+    print(f"  incoming ({len(n['incoming'])}):")
+    for o in n["incoming"]:
+        print(f"    <-{o['edge']}- {o['id']} ({o['kind']})")
+    return 0
+
+
+def cmd_focus(args: argparse.Namespace) -> int:
+    res = query.focus(_load_or_build(args.path), args.query, budget_tokens=args.budget)
+    if args.json:
+        print(json.dumps(res, ensure_ascii=False, indent=2))
+        return 0
+    if not res["nodes"]:
+        print(res.get("note", "no matches"))
+        return 0
+    print(f"focus '{res['query']}' · {len(res['nodes'])} nodes · "
+          f"~{res['used_tokens']}/{res['budget_tokens']} tokens")
+    print(f"  seeds: {', '.join(res['seeds'])}")
+    for r in res["nodes"]:
+        extra = f" ({r['cat']})" if r.get("cat") else ""
+        print(f"  {r.get('score', 0):.4f}  {r['id']}{extra}  [{r['kind']}, deg {r['deg']}]")
+    return 0
+
+
+def cmd_impact(args: argparse.Namespace) -> int:
+    seed_ids = None
+    query_str = args.seed or ""
+    proj = args.path
+    if args.diff:
+        # In --diff mode there is no seed, so a lone positional is the project path.
+        if args.seed and args.path == ".":
+            proj = args.seed
+        from veridge.sessions import git_changed_files
+        seed_ids = git_changed_files(proj)
+        query_str = "git diff (HEAD)"
+        if not seed_ids:
+            print("no changed files vs HEAD (or not a git repository)")
+            return 0
+    elif not args.seed:
+        print("provide a seed (file/symbol) or use --diff", file=sys.stderr)
+        return 2
+    g = _load_or_build(proj)
+    direction = "dependencies" if args.deps else "dependents"
+    res = query.impact(g, query_str, seed_ids=seed_ids, budget_tokens=args.budget,
+                       hops=args.hops, direction=direction)
+    if args.json:
+        print(json.dumps(res, ensure_ascii=False, indent=2))
+        return 0
+    verb = "depends on" if args.deps else "affected by"
+    print(f"impact ({direction}) of '{res['query']}' · {res['total_affected']} {verb}")
+    if res["seeds"]:
+        print(f"  seeds: {', '.join(res['seeds'])}")
+    if not res["nodes"]:
+        print(f"  {res.get('note', 'nothing found')}")
+        return 0
+    print(f"  showing {len(res['nodes'])} · ~{res['used_tokens']}/{res['budget_tokens']} tokens")
+    for r in res["nodes"]:
+        extra = f" ({r['cat']})" if r.get("cat") else ""
+        print(f"  {r.get('score', 0):.4f}  d{r.get('dist', '?')}  {r['id']}{extra}  [{r['kind']}]")
+    return 0
+
+
+def cmd_why(args: argparse.Namespace) -> int:
+    res = query.why(_load_or_build(args.path), args.a, args.b)
+    if args.json:
+        print(json.dumps(res, ensure_ascii=False, indent=2))
+        return 0
+    if not res["found"]:
+        print(res.get("note", "no path"))
+        return 1
+    path = res["path"]
+    print(f"why: {res['a']} -> {res['b']} · {res['length']} hops")
+    print(f"  {path[0]['id']} ({path[0]['kind']})")
+    for step in path[1:]:
+        connector = f"--{step['edge']}-->" if step["dir"] == "->" else f"<--{step['edge']}--"
+        print(f"    {connector} {step['id']} ({step['kind']})")
+    return 0
+
+
+def cmd_tour(args: argparse.Namespace) -> int:
+    res = query.tour(_load_or_build(args.path), budget_tokens=args.budget)
+    if args.json:
+        print(json.dumps(res, ensure_ascii=False, indent=2))
+        return 0
+    print(f"tour of '{res['project']}' · {len(res['stops'])}/{res['total_files']} stops · "
+          f"~{res['used_tokens']}/{res['budget_tokens']} tokens")
+    print("(read top to bottom: dependencies before the files that use them)")
+    for s in res["stops"]:
+        print(f"  {s['step']:2}. {s['id']}  [{s['layer']}]")
+        if s["uses"]:
+            print(f"        uses: {', '.join(s['uses'])}")
+        if s["used_by"]:
+            print(f"        used by: {', '.join(s['used_by'])}")
+    return 0
+
+
+def cmd_gate(args: argparse.Namespace) -> int:
+    g = store.load_graph(args.path)
+    old = store.load_manifest(args.path)
+    if g is None or old is None:
+        print("no graph found — run 'veridge build' first", file=sys.stderr)
+        return 2
+    rep = evaluate(g, old, build_manifest(args.path))
+    print(rep.summary())
+    print("OK: fresh and clean" if rep.ok else "DRIFT: rebuild and/or fix the issues above")
+    return 0 if rep.ok else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    # Print UTF-8 regardless of the console's locale (Windows defaults to cp1252, which
+    # would mangle the '·' separators). Best-effort: ignore if the stream can't reconfigure.
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")  # type: ignore[union-attr]
+        except (AttributeError, ValueError):
+            pass
+
+    parser = argparse.ArgumentParser(
+        prog="veridge", description="Veridge — the always-fresh, low-token map of a project.")
+    parser.add_argument("--version", action="version", version=f"veridge {__version__}")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    for name, fn, help_text in [
+        ("build", cmd_build, "index the project -> .veridge/graph.json"),
+        ("stats", cmd_stats, "counts by node/edge type"),
+        ("gate", cmd_gate, "anti-drift check (broken refs, stale files, orphans)"),
+    ]:
+        sp = sub.add_parser(name, help=help_text)
+        sp.add_argument("path", nargs="?", default=".", help="project root (default: .)")
+        sp.set_defaults(func=fn)
+
+    sp = sub.add_parser("map", help="compact project digest (PageRank-ranked)")
+    sp.add_argument("path", nargs="?", default=".", help="project root (default: .)")
+    sp.add_argument("--json", action="store_true", help="emit JSON")
+    sp.set_defaults(func=cmd_map)
+
+    sp = sub.add_parser("find", help="find nodes by name/path substring")
+    sp.add_argument("query", help="substring to search for")
+    sp.add_argument("path", nargs="?", default=".", help="project root (default: .)")
+    sp.set_defaults(func=cmd_find)
+
+    sp = sub.add_parser("neighbors", help="a node and its connections")
+    sp.add_argument("node", help="node id")
+    sp.add_argument("path", nargs="?", default=".", help="project root (default: .)")
+    sp.set_defaults(func=cmd_neighbors)
+
+    sp = sub.add_parser("focus", help="minimal relevant subgraph for a task, within a budget")
+    sp.add_argument("query", help="a task description, a file path, or a symbol name")
+    sp.add_argument("path", nargs="?", default=".", help="project root (default: .)")
+    sp.add_argument("--budget", type=int, default=1500, help="token budget (default: 1500)")
+    sp.add_argument("--json", action="store_true", help="emit JSON")
+    sp.set_defaults(func=cmd_focus)
+
+    sp = sub.add_parser("impact", help="blast-radius: what a change to a file/symbol affects")
+    sp.add_argument("seed", nargs="?", help="a file path or symbol name (omit with --diff)")
+    sp.add_argument("path", nargs="?", default=".", help="project root (default: .)")
+    sp.add_argument("--diff", action="store_true", help="seed from files changed vs git HEAD")
+    sp.add_argument("--deps", action="store_true",
+                    help="invert: what the seed depends ON, not what depends on it")
+    sp.add_argument("--hops", type=int, default=None, help="max propagation distance")
+    sp.add_argument("--budget", type=int, default=1500, help="token budget (default: 1500)")
+    sp.add_argument("--json", action="store_true", help="emit JSON")
+    sp.set_defaults(func=cmd_impact)
+
+    sp = sub.add_parser("why", help="shortest typed path between two nodes")
+    sp.add_argument("a", help="first node (id, path, or name)")
+    sp.add_argument("b", help="second node (id, path, or name)")
+    sp.add_argument("path", nargs="?", default=".", help="project root (default: .)")
+    sp.add_argument("--json", action="store_true", help="emit JSON")
+    sp.set_defaults(func=cmd_why)
+
+    sp = sub.add_parser("tour", help="dependency-ordered reading tour of the key files")
+    sp.add_argument("path", nargs="?", default=".", help="project root (default: .)")
+    sp.add_argument("--budget", type=int, default=2000, help="token budget (default: 2000)")
+    sp.add_argument("--json", action="store_true", help="emit JSON")
+    sp.set_defaults(func=cmd_tour)
+
+    args = parser.parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

veridge/freshness.py

@@ -0,0 +1,145 @@
+"""Content-hash freshness, the single-walk ``index`` entry point, and the anti-drift gate.
+
+Text source/docs up to a cap are content-hashed with newline normalisation (precise and
+stable across a CRLF/LF flip); data, binaries and large files use a cheap ``size+mtime``
+signature so indexing stays light on data-heavy projects. The manifest is a small
+``{path: hash}`` map; diffing it against the current tree tells the gate whether the map is
+still in sync.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from veridge.indexer import build_graph
+from veridge.model import EdgeType, Graph, Kind
+from veridge.walk import iter_files
+
+_CHUNK = 65536
+_NORMALIZE_CAP = 8_000_000
+_CONTENT_HASH_CAP = 1_000_000
+_TEXT_HASH_EXTS = {
+    ".md", ".markdown", ".rst", ".txt", ".py", ".js", ".ts", ".tsx", ".jsx", ".mjs", ".cjs",
+    ".toml", ".ini", ".cfg", ".conf", ".yaml", ".yml", ".html", ".htm", ".css", ".sql",
+    ".ps1", ".psm1", ".sh", ".bash", ".go", ".rs", ".java", ".c", ".cc", ".cpp", ".h",
+    ".hpp", ".rb", ".php", ".cs", ".adoc",
+}
+
+
+def _ext(name: str) -> str:
+    return os.path.splitext(name)[1].lower()
+
+
+def file_hash(path: Path, *, normalize_newlines: bool = False) -> str:
+    h = hashlib.blake2b(digest_size=16)
+    if normalize_newlines and path.stat().st_size <= _NORMALIZE_CAP:
+        data = path.read_bytes().replace(b"\r\n", b"\n").replace(b"\r", b"\n")
+        h.update(data)
+    else:
+        with open(path, "rb") as f:
+            for chunk in iter(lambda: f.read(_CHUNK), b""):
+                h.update(chunk)
+    return h.hexdigest()
+
+
+def _hash_rel(root: Path, rel: str) -> str | None:
+    p = root / rel
+    try:
+        st = p.stat()
+    except OSError:
+        return None
+    if _ext(rel) in _TEXT_HASH_EXTS and st.st_size <= _CONTENT_HASH_CAP:
+        try:
+            return file_hash(p, normalize_newlines=True)
+        except OSError:
+            return None
+    return f"s{st.st_size}:m{int(st.st_mtime)}"
+
+
+def build_manifest(root: str | os.PathLike[str]) -> dict[str, str]:
+    root_p = Path(root).resolve()
+    out: dict[str, str] = {}
+    for rel in iter_files(root_p):
+        hv = _hash_rel(root_p, rel)
+        if hv is not None:
+            out[rel] = hv
+    return out
+
+
+def index(root: str | os.PathLike[str]) -> tuple[Graph, dict[str, str]]:
+    """Build the graph and the manifest from one directory walk."""
+    root_p = Path(root).resolve()
+    rels = iter_files(root_p)
+    graph = build_graph(root_p, _rels=rels)
+    manifest = {rel: hv for rel in rels if (hv := _hash_rel(root_p, rel)) is not None}
+    return graph, manifest
+
+
+def diff_manifest(old: dict[str, str], new: dict[str, str]) -> dict[str, list[str]]:
+    old_k, new_k = set(old), set(new)
+    return {
+        "added": sorted(new_k - old_k),
+        "removed": sorted(old_k - new_k),
+        "changed": sorted(k for k in (old_k & new_k) if old[k] != new[k]),
+    }
+
+
+# -- the gate ---------------------------------------------------------------
+@dataclass
+class GateReport:
+    broken: list[tuple[str, str]] = field(default_factory=list)
+    stale: dict[str, list[str]] = field(
+        default_factory=lambda: {"added": [], "removed": [], "changed": []})
+    orphans: list[str] = field(default_factory=list)
+
+    @property
+    def stale_count(self) -> int:
+        return sum(len(v) for v in self.stale.values())
+
+    @property
+    def ok(self) -> bool:
+        return not self.broken and self.stale_count == 0
+
+    def summary(self) -> str:
+        a, r, c = self.stale["added"], self.stale["removed"], self.stale["changed"]
+        lines = [
+            f"broken references: {len(self.broken)}",
+            f"stale files: {self.stale_count} (+{len(a)} / -{len(r)} / ~{len(c)})",
+            f"orphans: {len(self.orphans)} (info)",
+        ]
+        for src, tgt in self.broken[:20]:
+            lines.append(f"  [broken] {src} -> {tgt}")
+        return "\n".join(lines)
+
+
+def find_broken(graph: Graph) -> list[tuple[str, str]]:
+    out: list[tuple[str, str]] = []
+    for n in graph.nodes.values():
+        for t in n.meta.get("broken_refs", []):
+            out.append((n.id, t))
+    return sorted(out)
+
+
+def find_orphans(graph: Graph) -> list[str]:
+    """File nodes connected by nothing but their area edge."""
+    out: list[str] = []
+    for n in graph.nodes.values():
+        if n.kind is not Kind.FILE:
+            continue
+        knowledge = any(
+            e.type is not EdgeType.BELONGS_TO
+            for e in graph.out_edges(n.id) + graph.in_edges(n.id)
+        )
+        if not knowledge:
+            out.append(n.id)
+    return sorted(out)
+
+
+def evaluate(graph: Graph, old_manifest: dict[str, str] | None,
+             new_manifest: dict[str, str]) -> GateReport:
+    stale = (diff_manifest(old_manifest, new_manifest) if old_manifest is not None
+             else {"added": [], "removed": [], "changed": []})
+    return GateReport(broken=find_broken(graph), stale=stale, orphans=find_orphans(graph))

veridge/ignore.py

@@ -0,0 +1,61 @@
+"""What the indexer skips: derived/vendor directories, binary noise, and user patterns.
+
+A project may add a ``.veridgeignore`` at its root — one glob per line, ``#`` comments
+allowed — matched against the POSIX relative path (case-sensitive, identical on every OS).
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+from pathlib import Path
+
+DEFAULT_IGNORE_DIRS: frozenset[str] = frozenset({
+    ".git", ".hg", ".svn", ".veridge",
+    "__pycache__", ".pytest_cache", ".ruff_cache", ".mypy_cache", ".cache",
+    ".venv", "venv", "env", "node_modules", "site-packages",
+    "dist", "build", ".eggs", ".tox", ".next", ".nuxt", "target",
+    ".idea", ".vscode",
+})
+
+DEFAULT_IGNORE_FILES: frozenset[str] = frozenset({
+    ".DS_Store", "Thumbs.db", ".veridgeignore",
+    "package-lock.json", "poetry.lock", "yarn.lock", "pnpm-lock.yaml",
+})
+
+DEFAULT_IGNORE_EXTS: frozenset[str] = frozenset({
+    ".pyc", ".pyo", ".pyd",
+    ".png", ".jpg", ".jpeg", ".gif", ".ico", ".webp", ".bmp",
+    ".woff", ".woff2", ".ttf", ".eot",
+    ".zip", ".gz", ".tar", ".7z", ".rar",
+    ".exe", ".dll", ".so", ".dylib", ".bin", ".o", ".a",
+    ".lock",
+})
+
+
+def load_ignore_patterns(root: Path) -> list[str]:
+    f = root / ".veridgeignore"
+    if not f.is_file():
+        return []
+    out: list[str] = []
+    for line in f.read_text(encoding="utf-8", errors="ignore").splitlines():
+        s = line.strip()
+        if s and not s.startswith("#"):
+            out.append(s)
+    return out
+
+
+def is_ignored_dir(name: str) -> bool:
+    return name in DEFAULT_IGNORE_DIRS or name.endswith(".egg-info")
+
+
+def is_ignored_file(rel_posix: str, name: str, patterns: list[str]) -> bool:
+    if name in DEFAULT_IGNORE_FILES:
+        return True
+    ext = os.path.splitext(name)[1].lower()
+    if ext in DEFAULT_IGNORE_EXTS:
+        return True
+    for pat in patterns:
+        if fnmatch.fnmatchcase(rel_posix, pat) or fnmatch.fnmatchcase(name, pat):
+            return True
+    return False