ops-wiki-agent-kit 0.1.0

package/.github/skills/source-code-to-spec-tools/scripts/source_lookup.py

@@ -0,0 +1,360 @@
+#!/usr/bin/env python3
+import sys
+
+sys.dont_write_bytecode = True
+
+import argparse
+import fnmatch
+import json
+import os
+import re
+from pathlib import Path
+
+
+def configure_stdio():
+    for stream_name in ("stdout", "stderr"):
+        stream = getattr(sys, stream_name, None)
+        reconfigure = getattr(stream, "reconfigure", None)
+        if callable(reconfigure):
+            reconfigure(encoding="utf-8")
+
+
+DEFAULT_EXCLUDE_DIRS = {
+    ".git",
+    ".hg",
+    ".svn",
+    ".idea",
+    ".vscode",
+    "__pycache__",
+    "bin",
+    "build",
+    "coverage",
+    "dist",
+    "node_modules",
+    "target",
+}
+
+DEFAULT_TEXT_EXTENSIONS = {
+    ".aspx",
+    ".bat",
+    ".c",
+    ".cfg",
+    ".conf",
+    ".cpp",
+    ".cs",
+    ".css",
+    ".csv",
+    ".env",
+    ".gradle",
+    ".groovy",
+    ".h",
+    ".html",
+    ".ini",
+    ".java",
+    ".js",
+    ".json",
+    ".jsp",
+    ".jsx",
+    ".kt",
+    ".md",
+    ".php",
+    ".properties",
+    ".ps1",
+    ".py",
+    ".rb",
+    ".razor",
+    ".sql",
+    ".ts",
+    ".tsx",
+    ".txt",
+    ".vb",
+    ".vue",
+    ".xml",
+    ".yaml",
+    ".yml",
+}
+
+
+def normalize_text(value):
+    return "" if value is None else str(value)
+
+
+def should_skip_dir(path, exclude_dirs):
+    return any(part in exclude_dirs for part in path.parts)
+
+
+def matches_any_glob(relative_path, patterns):
+    if not patterns:
+        return True
+    value = relative_path.as_posix()
+    return any(fnmatch.fnmatch(value, pattern) for pattern in patterns)
+
+
+def is_probably_text(path):
+    if path.suffix.lower() in DEFAULT_TEXT_EXTENSIONS:
+        return True
+    try:
+        with path.open("rb") as handle:
+            chunk = handle.read(2048)
+    except OSError:
+        return False
+    return b"\x00" not in chunk
+
+
+def read_text(path):
+    encodings = ("utf-8-sig", "utf-8", "cp950", "latin-1")
+    last_error = None
+    for encoding in encodings:
+        try:
+            return path.read_text(encoding=encoding), encoding
+        except UnicodeDecodeError as exc:
+            last_error = exc
+        except OSError as exc:
+            raise exc
+    raise last_error
+
+
+def iter_candidate_files(root, include_patterns, exclude_patterns, exclude_dirs):
+    for current_root, dirnames, filenames in os.walk(root):
+        dirnames[:] = [dirname for dirname in dirnames if dirname not in exclude_dirs]
+        current_path = Path(current_root)
+        for filename in filenames:
+            path = current_path / filename
+            if not path.is_file():
+                continue
+            relative_path = path.relative_to(root)
+            if not matches_any_glob(relative_path, include_patterns):
+                continue
+            if exclude_patterns and matches_any_glob(relative_path, exclude_patterns):
+                continue
+            if is_probably_text(path):
+                yield path, relative_path
+
+
+def compile_matchers(handles, regex_mode, ignore_case):
+    flags = re.IGNORECASE if ignore_case else 0
+    matchers = []
+    for handle in handles:
+        if regex_mode:
+            pattern = re.compile(handle, flags)
+            matchers.append((handle, pattern))
+        else:
+            pattern = re.compile(re.escape(handle), flags)
+            matchers.append((handle, pattern))
+    return matchers
+
+
+def file_has_all_handles(text, matchers):
+    return all(pattern.search(text) for _, pattern in matchers)
+
+
+def format_relative_path(relative_path):
+    return relative_path.as_posix()
+
+
+def build_evidence_ref(relative_path, line, matched_handles, kind, symbol):
+    symbol_value = symbol or ", ".join(matched_handles)
+    return {
+        "path": format_relative_path(relative_path),
+        "line": line,
+        "symbol": symbol_value,
+        "kind": kind,
+    }
+
+
+def search_file(path, relative_path, matchers, context, mode, evidence_options):
+    try:
+        text, encoding = read_text(path)
+    except OSError as exc:
+        return [], {"path": format_relative_path(relative_path), "error": str(exc)}
+
+    if mode == "all" and not file_has_all_handles(text, matchers):
+        return [], None
+
+    lines = text.splitlines()
+    matches = []
+    for line_index, line in enumerate(lines, 1):
+        matched_handles = [label for label, pattern in matchers if pattern.search(line)]
+        if not matched_handles:
+            continue
+        start = max(1, line_index - context)
+        end = min(len(lines), line_index + context)
+        evidence_ref = build_evidence_ref(
+            relative_path,
+            line_index,
+            matched_handles,
+            evidence_options["kind"],
+            evidence_options["symbol"],
+        )
+        matches.append(
+            {
+                "path": format_relative_path(relative_path),
+                "line": line_index,
+                "handles": matched_handles,
+                "evidence_ref": evidence_ref,
+                "text": line.strip(),
+                "context": [
+                    {
+                        "line": number,
+                        "text": lines[number - 1].rstrip(),
+                    }
+                    for number in range(start, end + 1)
+                ],
+                "encoding": encoding,
+            }
+        )
+    return matches, None
+
+
+def search(args):
+    root = Path(args.root).resolve()
+    if not root.exists():
+        raise SystemExit(f"Root not found: {root}")
+    if not args.handle:
+        raise SystemExit("At least one --handle is required.")
+
+    include_patterns = args.include or []
+    exclude_patterns = args.exclude or []
+    exclude_dirs = set(DEFAULT_EXCLUDE_DIRS)
+    exclude_dirs.update(args.exclude_dir or [])
+    matchers = compile_matchers(args.handle, args.regex, args.ignore_case)
+    evidence_options = {
+        "kind": args.evidence_kind,
+        "symbol": args.evidence_symbol,
+    }
+
+    matches = []
+    errors = []
+    files_scanned = 0
+    files_with_matches = set()
+    for path, relative_path in iter_candidate_files(root, include_patterns, exclude_patterns, exclude_dirs):
+        files_scanned += 1
+        file_matches, error = search_file(path, relative_path, matchers, args.context, args.mode, evidence_options)
+        if error:
+            errors.append(error)
+            continue
+        if file_matches:
+            files_with_matches.add(format_relative_path(relative_path))
+            matches.extend(file_matches)
+            if len(matches) >= args.max_results:
+                matches = matches[: args.max_results]
+                break
+
+    return {
+        "root": str(root),
+        "handles": args.handle,
+        "mode": args.mode,
+        "regex": args.regex,
+        "ignore_case": args.ignore_case,
+        "files_scanned": files_scanned,
+        "files_with_matches": len(files_with_matches),
+        "match_count": len(matches),
+        "matches": matches,
+        "evidence_refs": [item["evidence_ref"] for item in matches],
+        "errors": errors,
+    }
+
+
+def markdown_escape(value):
+    return normalize_text(value).replace("|", "\\|")
+
+
+def render_markdown(payload):
+    rows = []
+    for item in payload["matches"]:
+        rows.append(
+            {
+                "path": item["path"],
+                "line": str(item["line"]),
+                "handles": ", ".join(item["handles"]),
+                "text": item["text"],
+            }
+        )
+    if not rows:
+        return "(no matches)"
+    columns = ["path", "line", "handles", "text"]
+    lines = []
+    lines.append("| " + " | ".join(columns) + " |")
+    lines.append("| " + " | ".join("---" for _ in columns) + " |")
+    for row in rows:
+        lines.append("| " + " | ".join(markdown_escape(row[column]) for column in columns) + " |")
+    return "\n".join(lines)
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        description="Search source code handles and return reusable evidence refs with path and line numbers."
+    )
+    parser.add_argument("--root", default=".", help="Source root to scan.")
+    parser.add_argument("--handle", action="append", help="Literal string or regex to search. Repeatable.")
+    parser.add_argument("--regex", action="store_true", help="Treat --handle values as regular expressions.")
+    parser.add_argument("--ignore-case", action="store_true")
+    parser.add_argument(
+        "--mode",
+        choices=("any", "all"),
+        default="any",
+        help="any returns lines matching any handle; all only returns matches from files containing every handle.",
+    )
+    parser.add_argument("--include", action="append", help="Glob relative to root, e.g. **/*.java. Repeatable.")
+    parser.add_argument("--exclude", action="append", help="File glob relative to root. Repeatable.")
+    parser.add_argument("--exclude-dir", action="append", help="Directory name to skip. Repeatable.")
+    parser.add_argument("--context", type=int, default=0, help="Context lines before and after each match.")
+    parser.add_argument("--max-results", type=int, default=100)
+    parser.add_argument("--output", choices=("json", "markdown"), default="json")
+    parser.add_argument(
+        "--evidence-kind",
+        choices=(
+            "entrypoint",
+            "route",
+            "handler",
+            "class",
+            "method",
+            "SQL",
+            "table",
+            "config",
+            "job",
+            "procedure",
+            "routine",
+            "file",
+            "test",
+            "runtime_metadata",
+            "generated_doc",
+            "external_contract",
+            "other",
+        ),
+        default="other",
+        help="EvidenceRef kind assigned to matches.",
+    )
+    parser.add_argument(
+        "--evidence-confidence",
+        choices=("high", "medium", "low"),
+        default=None,
+        help=argparse.SUPPRESS,
+    )
+    parser.add_argument(
+        "--evidence-reason",
+        default=None,
+        help=argparse.SUPPRESS,
+    )
+    parser.add_argument(
+        "--evidence-symbol",
+        help="EvidenceRef symbol override. Defaults to the matched handle list.",
+    )
+    return parser
+
+
+def main():
+    configure_stdio()
+    args = build_parser().parse_args()
+    payload = search(args)
+    if args.output == "json":
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    else:
+        print(render_markdown(payload))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except BrokenPipeError:
+        sys.exit(1)