feat: .repokgignore loading + precedence tests + README (2/2) (#40)

- code.load_ignore(repo): <repo>/.repokgignore, one glob per line,
  # comments and blank lines skipped — same semantics as --exclude,
  committed so the whole team shares it
- CLI unions ignore-file patterns with --exclude flags (deduped) for
  scan and generate; no flags needed once the file is committed
- end-to-end precedence test: scan on a git-init'd tree with both
  sources, asserting kg.json patterns/counts and pruned modules
- README: 'Excluding paths' section + roadmap checkbox

Closes #4.

Author: NehharShah

README.md

@@ -72,7 +72,31 @@ timeline eras, and gotchas alongside the deterministic structure.
 | `repokg check [path]` | Exit 1 if the knowledge graph is stale vs `HEAD` (CI-friendly) |
 
 Flags: `--out DIR` (default `<repo>/.repokg`), `--md FILE` (default `<repo>/KNOWLEDGE_GRAPH.md`),
-`--no-github`, `--pr-limit N`, `--diff`, `--json`.
+`--exclude PATTERN` (repeatable), `--no-github`, `--pr-limit N`, `--diff`, `--json`.
+
+### Excluding paths
+
+Common noise (`node_modules`, `.git`, build output, …) is skipped automatically.
+For repo-specific noise — fixtures, snapshots, vendored trees, generated docs —
+add globs on the command line or in a committed `.repokgignore` at the repo root:
+
+```sh
+repokg scan --exclude '*fixtures' --exclude 'docs/gen'
+```
+
+```
+# .repokgignore — one glob per line, same semantics as --exclude
+*fixtures
+*.snap
+packages/*/gen
+```
+
+Patterns are matched (`fnmatch`) against repo-relative paths; matching
+directories are pruned wholesale and matching files dropped, so modules, import
+edges, and ops all inherit the exclusion. `*` crosses `/`: `*fixtures` matches
+at any depth, `fixtures` only at the root. CLI patterns and `.repokgignore` are
+unioned. Exclusions are never silent — `scan` prints what it dropped, `kg.json`
+records the patterns and counts, and `repokg audit` carries an uncertainty note.
 
 ## Honesty layer
 
@@ -157,7 +181,7 @@ schema — everything else stays deterministic and reproducible.
 
 - [x] Rust import graph
 - [x] Java / Kotlin import graphs
-- [ ] `--exclude` glob patterns
+- [x] `--exclude` glob patterns + `.repokgignore`
 - [ ] `llms.txt` emission alongside KNOWLEDGE_GRAPH.md
 - [x] tsconfig `paths` alias + workspace package resolution
 - [ ] PyPI release + prebuilt GitHub Action

src/repokg/cli.py

@@ -164,7 +164,9 @@ def main(argv=None):
     ap.add_argument("--exclude", action="append", default=[], metavar="PATTERN",
                     help="glob matched against repo-relative paths; matching "
                          "dirs are pruned, matching files dropped (repeatable; "
-                         "`*` crosses `/`, so '*fixtures' matches any depth)")
+                         "`*` crosses `/`, so '*fixtures' matches any depth). "
+                         "Unioned with <repo>/.repokgignore (one glob per "
+                         "line, # comments)")
     ap.add_argument("--no-github", action="store_true", help="skip gh PR lookup")
     ap.add_argument("--pr-limit", type=int, default=1000, help="max PRs to fetch (default 1000)")
     ap.add_argument("--diff", action="store_true",
@@ -182,10 +184,12 @@ def main(argv=None):
         return 2
     out = args.out or os.path.join(repo, ".repokg")
     md = args.md or os.path.join(repo, "KNOWLEDGE_GRAPH.md")
+    # union of CLI flags and the committed ignore file, deduped
+    exclude = list(dict.fromkeys(args.exclude + code.load_ignore(repo)))
 
     try:
         if args.command == "scan":
-            scan(repo, out, args.no_github, args.pr_limit, args.exclude)
+            scan(repo, out, args.no_github, args.pr_limit, exclude)
         elif args.command == "prompts":
             write_prompts(repo, out, md)
         elif args.command == "render":
@@ -199,7 +203,7 @@ def main(argv=None):
         elif args.command == "check":
             return check(repo, out, md)
         else:  # generate
-            scan(repo, out, args.no_github, args.pr_limit, args.exclude)
+            scan(repo, out, args.no_github, args.pr_limit, exclude)
             write_prompts(repo, out, md)
             return render(out, md)
     except RuntimeError as e:

src/repokg/code.py

@@ -39,6 +39,23 @@
 MAX_FILE_BYTES = 2_000_000
 
 
+IGNORE_FILE = ".repokgignore"
+
+
+def load_ignore(repo):
+    """Patterns from <repo>/.repokgignore: one glob per line, # comments.
+
+    Same semantics as --exclude; committed so the whole team shares it.
+    """
+    try:
+        with open(os.path.join(repo, IGNORE_FILE), encoding="utf-8") as f:
+            lines = f.read().splitlines()
+    except OSError:
+        return []
+    stripped = (ln.strip() for ln in lines)
+    return [ln for ln in stripped if ln and not ln.startswith("#")]
+
+
 def _excluded(rel, exclude):
     return any(fnmatch.fnmatch(rel, pat) for pat in exclude)
 

tests/test_exclude.py

@@ -1,8 +1,12 @@
+import contextlib
+import io
+import json
 import os
+import subprocess
 import tempfile
 import unittest
 
-from repokg.code import walk
+from repokg.code import load_ignore, walk
 from repokg.findings import build
 
 
@@ -97,5 +101,52 @@ def test_no_note_without_exclude_key(self):
         self.assertFalse([n for n in notes if "invisible" in n])
 
 
+class TestRepokgIgnore(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.repo = self.tmp.name
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def test_missing_file_is_empty(self):
+        self.assertEqual(load_ignore(self.repo), [])
+
+    def test_comments_and_blanks_skipped(self):
+        write(self.repo, ".repokgignore",
+              "# vendored trees\n"
+              "*fixtures\n"
+              "\n"
+              "  docs/gen  \n"
+              "   \n"
+              "# eof\n")
+        self.assertEqual(load_ignore(self.repo), ["*fixtures", "docs/gen"])
+
+    def test_ignore_file_patterns_prune_walk(self):
+        write(self.repo, ".repokgignore", "*fixtures\n")
+        write(self.repo, "src/app.py")
+        write(self.repo, "src/fixtures/big.py")
+        seen = {rel for rel, _ in walk(self.repo, load_ignore(self.repo))}
+        self.assertIn("src", seen)
+        self.assertNotIn("src/fixtures", seen)
+
+    def test_scan_unions_cli_and_ignore_file(self):
+        from repokg.cli import main
+        subprocess.run(["git", "init", "-q", self.repo], check=True)
+        write(self.repo, "src/app.py")
+        write(self.repo, "src/fixtures/big.py")
+        # *.snap in both places: union must dedupe
+        write(self.repo, ".repokgignore", "# vendored\n*fixtures\n*.snap\n")
+        with contextlib.redirect_stdout(io.StringIO()) as buf:
+            rc = main(["scan", self.repo, "--no-github", "--exclude", "*.snap"])
+        self.assertEqual(rc, 0)
+        with open(os.path.join(self.repo, ".repokg", "kg.json")) as f:
+            kg = json.load(f)
+        self.assertEqual(kg["exclude"]["patterns"], ["*.snap", "*fixtures"])
+        self.assertEqual(kg["exclude"]["dirs"], 1)
+        self.assertNotIn("src/fixtures", [m["path"] for m in kg["modules"]])
+        self.assertIn("excluded 1 dirs", buf.getvalue())
+
+
 if __name__ == "__main__":
     unittest.main()