feat(reachability): extend opt-in library-mode to all parsers + CLI

#117's library-mode (seed the exported public API so a library with no main/
route/CLI entry point isn't blacked out) lived only in the Python path
(core/parser_adapter). The other six parsers run as subprocesses with their own
reachability copy, so a C/JS/etc. library still collapsed: tree-sitter's C core
pruned 661 -> 24 (all wasm), the public ts_parser_* API never seeded.

Centralize _library_seed_ids into utilities/agentic_enhancer.library_seed_ids
(now handles both is_exported snake_case on disk and isExported camelCase from
the pipelines' in-memory normalize). Thread an opt-in library_mode through all
4 parallel surfaces for each of the 6 subprocess parsers (parse dispatch ->
_parse_<lang> subprocess cmd -> test_pipeline --library-mode argparse -> union
library_seed_ids into entry_points before the BFS), plus scan_repository and the
'openant parse' / 'openant scan' CLI flags. Union-only: never drops a
structurally detected entry point, so app scans are unaffected.

Verified end-to-end on tree-sitter C: without the flag the blackout warning
fires (24/661); with --library-mode, 352 public-API seeds -> 550 reachable, the
parser core (parser.c/lexer.c/stack.c/subtree.c/query.c/node.c) now analysable.

Tests: 8 new (library_seed_ids both casings + name heuristic); #117 Python path
unchanged (6 green).

Author: gadievron

libs/openant-core/core/parser_adapter.py

@@ -114,17 +114,17 @@ def parse_repository(
     if language == "python":
         result = _parse_python(repo_path, output_dir, processing_level, skip_tests, name, library_mode)
     elif language == "javascript":
-        result = _parse_javascript(repo_path, output_dir, processing_level, skip_tests, name)
+        result = _parse_javascript(repo_path, output_dir, processing_level, skip_tests, name, library_mode)
     elif language == "go":
-        result = _parse_go(repo_path, output_dir, processing_level, skip_tests, name)
+        result = _parse_go(repo_path, output_dir, processing_level, skip_tests, name, library_mode)
     elif language == "c":
-        result = _parse_c(repo_path, output_dir, processing_level, skip_tests, name)
+        result = _parse_c(repo_path, output_dir, processing_level, skip_tests, name, library_mode)
     elif language == "ruby":
-        result = _parse_ruby(repo_path, output_dir, processing_level, skip_tests, name)
+        result = _parse_ruby(repo_path, output_dir, processing_level, skip_tests, name, library_mode)
     elif language == "php":
-        result = _parse_php(repo_path, output_dir, processing_level, skip_tests, name)
+        result = _parse_php(repo_path, output_dir, processing_level, skip_tests, name, library_mode)
     elif language == "zig":
-        result = _parse_zig(repo_path, output_dir, processing_level, skip_tests, name)
+        result = _parse_zig(repo_path, output_dir, processing_level, skip_tests, name, library_mode)
     else:
         raise ValueError(f"Unsupported language: {language}")
 
@@ -192,26 +192,10 @@ def _maybe_apply_diff_filter(
 # Reachability filter (shared by Python path; JS/Go handle it internally)
 # ---------------------------------------------------------------------------
 
-def _library_seed_ids(functions: dict) -> "set[str]":
-    """Public-API seed set for library-mode reachability.
-
-    A pure library exposes no main/route/CLI entry point, so the structural
-    detector finds nothing and the whole library is filtered out (0 reachable).
-    In library-mode the *public surface* IS the entry surface: seed every
-    exported/public function and let the forward BFS pull in its callees.
-
-    Public = exported AND not name-private. ``is_exported`` is honoured when the
-    parser provides it (C/Go/JS — excludes ``static``/unexported); for parsers
-    without the field (python/ruby/php) it defaults True and the name heuristic
-    (leading underscore = private) decides. The bias is intentionally toward
-    over-seeding (more reachable = more analysed), never under-seeding.
-    """
-    seeds: set[str] = set()
-    for func_id, fd in functions.items():
-        name = (fd.get("name") or func_id.rsplit(":", 1)[-1]).split(".")[-1]
-        if fd.get("is_exported", True) and not name.startswith("_"):
-            seeds.add(func_id)
-    return seeds
+# library_seed_ids is now shared in utilities/agentic_enhancer/entry_point_detector.py
+# so every parser pipeline (not just Python) can seed the public API. It is loaded
+# below via the same importlib path as EntryPointDetector to dodge the heavy
+# utilities/__init__ imports.
 
 
 def apply_reachability_filter(
@@ -263,6 +247,7 @@ def _load_module(name, filename):
     _ra = _load_module("reachability_analyzer", "reachability_analyzer.py")
     EntryPointDetector = _epd.EntryPointDetector
     blackout_warning = _epd.blackout_warning
+    library_seed_ids = _epd.library_seed_ids
     ReachabilityAnalyzer = _ra.ReachabilityAnalyzer
 
     call_graph_path = os.path.join(output_dir, "call_graph.json")
@@ -290,7 +275,7 @@ def _load_module(name, filename):
     # never demotes a structurally-detected app entry point, so an app scan with
     # the flag on can only gain reachable units, never lose one.
     if library_mode:
-        entry_points = entry_points | _library_seed_ids(functions)
+        entry_points = entry_points | library_seed_ids(functions)
 
     units = dataset.get("units", [])
     original_count = len(units)
@@ -544,7 +529,7 @@ def _file_lock(lock_path: Path):
         f.close()
 
 
-def _parse_javascript(repo_path: str, output_dir: str, processing_level: str, skip_tests: bool = True, name: str = None) -> ParseResult:
+def _parse_javascript(repo_path: str, output_dir: str, processing_level: str, skip_tests: bool = True, name: str = None, library_mode: bool = False) -> ParseResult:
     """Invoke the JavaScript/TypeScript parser.
 
     The JS parser is a PipelineTest class that runs Node.js subprocesses.
@@ -568,6 +553,8 @@ def _parse_javascript(repo_path: str, output_dir: str, processing_level: str, sk
         cmd.extend(["--name", name])
     if skip_tests:
         cmd.append("--skip-tests")
+    if library_mode:
+        cmd.append("--library-mode")
 
     result = subprocess.run(
         cmd,
@@ -603,7 +590,7 @@ def _parse_javascript(repo_path: str, output_dir: str, processing_level: str, sk
 # Go parser
 # ---------------------------------------------------------------------------
 
-def _parse_go(repo_path: str, output_dir: str, processing_level: str, skip_tests: bool = True, name: str = None) -> ParseResult:
+def _parse_go(repo_path: str, output_dir: str, processing_level: str, skip_tests: bool = True, name: str = None, library_mode: bool = False) -> ParseResult:
     """Invoke the Go parser.
 
     The Go parser is a PipelineTest class that calls a compiled Go binary.
@@ -624,6 +611,8 @@ def _parse_go(repo_path: str, output_dir: str, processing_level: str, skip_tests
         cmd.extend(["--name", name])
     if skip_tests:
         cmd.append("--skip-tests")
+    if library_mode:
+        cmd.append("--library-mode")
 
     result = subprocess.run(
         cmd,
@@ -659,7 +648,7 @@ def _parse_go(repo_path: str, output_dir: str, processing_level: str, skip_tests
 # C/C++ parser
 # ---------------------------------------------------------------------------
 
-def _parse_c(repo_path: str, output_dir: str, processing_level: str, skip_tests: bool = True, name: str = None) -> ParseResult:
+def _parse_c(repo_path: str, output_dir: str, processing_level: str, skip_tests: bool = True, name: str = None, library_mode: bool = False) -> ParseResult:
     """Invoke the C/C++ parser.
 
     The C parser uses tree-sitter for function extraction and call graph
@@ -682,6 +671,8 @@ def _parse_c(repo_path: str, output_dir: str, processing_level: str, skip_tests:
         cmd.extend(["--name", name])
     if skip_tests:
         cmd.append("--skip-tests")
+    if library_mode:
+        cmd.append("--library-mode")
 
     result = subprocess.run(
         cmd,
@@ -718,7 +709,7 @@ def _parse_c(repo_path: str, output_dir: str, processing_level: str, skip_tests:
 # Ruby parser
 # ---------------------------------------------------------------------------
 
-def _parse_ruby(repo_path: str, output_dir: str, processing_level: str, skip_tests: bool = True, name: str = None) -> ParseResult:
+def _parse_ruby(repo_path: str, output_dir: str, processing_level: str, skip_tests: bool = True, name: str = None, library_mode: bool = False) -> ParseResult:
     """Invoke the Ruby parser.
 
     The Ruby parser uses tree-sitter for function extraction and call graph
@@ -741,6 +732,8 @@ def _parse_ruby(repo_path: str, output_dir: str, processing_level: str, skip_tes
         cmd.extend(["--name", name])
     if skip_tests:
         cmd.append("--skip-tests")
+    if library_mode:
+        cmd.append("--library-mode")
 
     result = subprocess.run(
         cmd,
@@ -777,7 +770,7 @@ def _parse_ruby(repo_path: str, output_dir: str, processing_level: str, skip_tes
 # PHP parser
 # ---------------------------------------------------------------------------
 
-def _parse_php(repo_path: str, output_dir: str, processing_level: str, skip_tests: bool = True, name: str = None) -> ParseResult:
+def _parse_php(repo_path: str, output_dir: str, processing_level: str, skip_tests: bool = True, name: str = None, library_mode: bool = False) -> ParseResult:
     """Invoke the PHP parser.
 
     The PHP parser uses tree-sitter for function extraction and call graph
@@ -800,6 +793,8 @@ def _parse_php(repo_path: str, output_dir: str, processing_level: str, skip_test
         cmd.extend(["--name", name])
     if skip_tests:
         cmd.append("--skip-tests")
+    if library_mode:
+        cmd.append("--library-mode")
 
     result = subprocess.run(
         cmd,
@@ -836,7 +831,7 @@ def _parse_php(repo_path: str, output_dir: str, processing_level: str, skip_test
 # Zig parser
 # ---------------------------------------------------------------------------
 
-def _parse_zig(repo_path: str, output_dir: str, processing_level: str, skip_tests: bool = True, name: str = None) -> ParseResult:
+def _parse_zig(repo_path: str, output_dir: str, processing_level: str, skip_tests: bool = True, name: str = None, library_mode: bool = False) -> ParseResult:
     """Invoke the Zig parser.
 
     The Zig parser uses tree-sitter for function extraction and call graph
@@ -859,6 +854,8 @@ def _parse_zig(repo_path: str, output_dir: str, processing_level: str, skip_test
         cmd.extend(["--name", name])
     if skip_tests:
         cmd.append("--skip-tests")
+    if library_mode:
+        cmd.append("--library-mode")
 
     result = subprocess.run(
         cmd,

libs/openant-core/core/scanner.py

@@ -62,6 +62,7 @@ def scan_repository(
     diff_manifest: str | None = None,
     llm_reachability: bool = False,
     llm_reachability_max_code_bytes: int = 1500,
+    library_mode: bool = False,
 ) -> ScanResult:
     """Scan a repository for vulnerabilities.
 
@@ -154,6 +155,7 @@ def _step_label(name: str) -> str:
             processing_level=effective_parse_level,
             skip_tests=skip_tests,
             diff_manifest=diff_manifest,
+            library_mode=library_mode,
         )
 
         ctx.summary = {

libs/openant-core/openant/cli.py

@@ -75,6 +75,7 @@ def cmd_scan(args):
             repo_url=getattr(args, "repo_url", None),
             commit_sha=getattr(args, "commit_sha", None),
             diff_manifest=getattr(args, "diff_manifest", None),
+            library_mode=getattr(args, "library_mode", False),
             llm_reachability=getattr(args, "llm_reachability", False),
             llm_reachability_max_code_bytes=getattr(
                 args, "llm_reachability_max_code_bytes", 1500
@@ -128,6 +129,7 @@ def cmd_parse(args):
                 skip_tests=not args.no_skip_tests,
                 name=getattr(args, "name", None),
                 diff_manifest=getattr(args, "diff_manifest", None),
+                library_mode=getattr(args, "library_mode", False),
             )
 
             ctx.summary = {
@@ -983,6 +985,8 @@ def main():
     scan_p.add_argument("--dynamic-test", action="store_true",
                         help="Enable Docker-isolated dynamic testing (off by default)")
     scan_p.add_argument("--no-skip-tests", action="store_true", help="Include test files in parsing (default: tests are skipped)")
+    scan_p.add_argument("--library-mode", action="store_true",
+                        help="Seed the exported public API as entry points (for libraries with no main/route/CLI entry point)")
     scan_p.add_argument("--limit", type=int, help="Max units to analyze")
     scan_p.add_argument("--model", choices=["opus", "sonnet"], default="opus", help="Model (default: opus)")
     scan_p.add_argument("--workers", type=int, default=8,
@@ -1037,6 +1041,8 @@ def main():
         help="Processing level (default: reachable)",
     )
     parse_p.add_argument("--no-skip-tests", action="store_true", help="Include test files in parsing (default: tests are skipped)")
+    parse_p.add_argument("--library-mode", action="store_true",
+                         help="Seed the exported public API as entry points (for libraries with no main/route/CLI entry point)")
     parse_p.add_argument("--name", help="Dataset name (default: derived from repo path)")
     parse_p.add_argument("--diff-manifest", help="Path to diff_manifest.json; tags units with diff_selected")
     parse_p.set_defaults(func=cmd_parse)

libs/openant-core/parsers/c/test_pipeline.py

@@ -48,7 +48,7 @@
 sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
 from utilities.file_io import open_utf8, read_json, run_utf8, write_json
 from utilities.context_enhancer import ContextEnhancer
-from utilities.agentic_enhancer import EntryPointDetector, ReachabilityAnalyzer, blackout_warning
+from utilities.agentic_enhancer import EntryPointDetector, ReachabilityAnalyzer, blackout_warning, library_seed_ids
 
 # Local imports
 from repository_scanner import RepositoryScanner
@@ -87,7 +87,8 @@ def __init__(
         processing_level: ProcessingLevel = ProcessingLevel.ALL,
         skip_tests: bool = False,
         depth: int = 3,
-        name: str = None
+        name: str = None,
+        library_mode: bool = False
     ):
         self.repo_path = os.path.abspath(repo_path)
         self.output_dir = output_dir or os.path.join(os.path.dirname(__file__), 'test_output')
@@ -98,6 +99,7 @@ def __init__(
         self.skip_tests = skip_tests
         self.depth = depth
         self.dataset_name = name
+        self.library_mode = library_mode
 
         # Pipeline artifacts
         self.scan_results_file = None
@@ -292,6 +294,13 @@ def apply_reachability_filter(self) -> bool:
             detector = EntryPointDetector(normalized_functions, call_graph)
             self.entry_points = detector.detect_entry_points()
 
+            # Library-mode: a library's entry surface is its exported public API,
+            # which carries no main/route/CLI marker. Seed it so the BFS reaches
+            # the core instead of blacking out. Union-only — never drops a
+            # structurally-detected entry point.
+            if self.library_mode:
+                self.entry_points = self.entry_points | library_seed_ids(normalized_functions)
+
             # Build reachability
             reachability = ReachabilityAnalyzer(
                 functions=normalized_functions,
@@ -1020,6 +1029,11 @@ def main():
         default=None,
         help='Dataset name (default: derived from repo path)'
     )
+    parser.add_argument(
+        '--library-mode',
+        action='store_true',
+        help='Seed the exported public API as entry points (for libraries with no main/route/CLI)'
+    )
 
     args = parser.parse_args()
 
@@ -1041,7 +1055,8 @@ def main():
         processing_level=processing_level,
         skip_tests=args.skip_tests,
         depth=args.depth,
-        name=args.name
+        name=args.name,
+        library_mode=args.library_mode
     )
     results = pipeline.run_full_pipeline()
 

libs/openant-core/parsers/go/test_pipeline.py

@@ -121,7 +121,7 @@ def _stdout_supports_unicode() -> bool:
 # Add parent directory to path for utilities import
 sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
 from utilities.context_enhancer import ContextEnhancer
-from utilities.agentic_enhancer import EntryPointDetector, ReachabilityAnalyzer, blackout_warning
+from utilities.agentic_enhancer import EntryPointDetector, ReachabilityAnalyzer, blackout_warning, library_seed_ids
 
 
 class ProcessingLevel(Enum):
@@ -152,7 +152,8 @@ def __init__(
         processing_level: ProcessingLevel = ProcessingLevel.ALL,
         skip_tests: bool = False,
         depth: int = 3,
-        name: str = None
+        name: str = None,
+        library_mode: bool = False
     ):
         self.repo_path = os.path.abspath(repo_path)
         self.output_dir = output_dir or os.path.join(os.path.dirname(__file__), 'test_output')
@@ -163,6 +164,7 @@ def __init__(
         self.skip_tests = skip_tests
         self.depth = depth
         self.dataset_name = name
+        self.library_mode = library_mode
 
         # Go parser binary location
         self.go_parser = os.path.join(self.parser_dir, 'go_parser', 'go_parser')
@@ -433,6 +435,11 @@ def apply_reachability_filter(self) -> bool:
             detector = EntryPointDetector(normalized_functions, call_graph)
             self.entry_points = detector.detect_entry_points()
 
+            # Library-mode: seed the exported public API (a library has no
+            # main/route/CLI marker). Union-only — never drops a real entry point.
+            if self.library_mode:
+                self.entry_points = self.entry_points | library_seed_ids(normalized_functions)
+
             # Build reachability analyzer
             reachability = ReachabilityAnalyzer(
                 functions=normalized_functions,
@@ -1198,6 +1205,11 @@ def main():
         default=None,
         help='Dataset name (default: derived from repo path)'
     )
+    parser.add_argument(
+        '--library-mode',
+        action='store_true',
+        help='Seed the exported public API as entry points (for libraries with no main/route/CLI)'
+    )
 
     args = parser.parse_args()
 
@@ -1220,7 +1232,8 @@ def main():
         processing_level=processing_level,
         skip_tests=args.skip_tests,
         depth=args.depth,
-        name=args.name
+        name=args.name,
+        library_mode=args.library_mode
     )
     results = pipeline.run_full_pipeline()