enforce-cpg 0.2.0__py3-none-any.whl

enforce_cpg/LICENSE

@@ -0,0 +1,85 @@
+Attribution Assurance License (AAL)
+
+Copyright (c) 2026 tommyz4
+https://github.com/tommyz4/enforce-cpg
+
+The following is the full, official text of the Open Source Initiative (OSI)
+approved Attribution Assurance License (SPDX identifier: AAL), as published
+at https://opensource.org/license/aal, with the license's own attribution
+fields filled in for this project: Author = tommyz4; Professional
+Identification = enforce-cpg maintainer; URL = https://github.com/tommyz4/enforce-cpg.
+
+--------------------------------------------------------------------------
+
+Copyright (c) 2026 tommyz4
+
+tommyz4, enforce-cpg maintainer * https://github.com/tommyz4/enforce-cpg
+
+"enforce-cpg: Code Property Graph MCP server for DayZ Enforce Script"
+
+All Rights Reserved
+
+ATTRIBUTION ASSURANCE LICENSE (adapted from the original BSD license)
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the conditions below are met.
+
+These conditions require a modest attribution to tommyz4 (the "Author"), who
+hopes that its promotional value may help justify the thousands of dollars in
+otherwise billable time invested in writing this and other freely available,
+open-source software.
+
+1. Redistributions of source code, in whole or part and with or without
+modification (the "Code"), must prominently display this GPG-signed text in
+verifiable form.
+
+2. Redistributions of the Code in binary form must be accompanied by this
+GPG-signed text in any documentation and, each time the resulting executable
+program or a program dependent thereon is launched, a prominent display
+(e.g., splash screen or banner text) of the Author's attribution
+information, which includes:
+
+(a) Name ("tommyz4"),
+
+(b) Professional identification ("enforce-cpg maintainer"), and
+
+(c) URL ("https://github.com/tommyz4/enforce-cpg").
+
+3. Neither the name nor any trademark of the Author may be used to endorse
+or promote products derived from this software without specific prior
+written permission.
+
+4. Users are entirely responsible, to the exclusion of the Author and any
+other persons, for compliance with
+
+(1) regulations set by owners or administrators of employed equipment,
+
+(2) licensing terms of any other software, and
+
+(3) local regulations regarding use, including those regarding import,
+export, and use of encryption software.
+
+THIS FREE SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
+EVENT SHALL THE AUTHOR OR ANY CONTRIBUTOR BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, EFFECTS OF UNAUTHORIZED OR MALICIOUS NETWORK
+ACCESS; PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+--End of License
+
+Originally written by Edwin A. Suominen for licensing his PRIVARIA secure
+networking software (see www.privaria.org). The author, who is not an
+attorney, places this license template into the public domain along with a
+complete disclaimer of any warranty or responsibility for its content or
+legal efficacy. You may use or modify the language freely, but entirely at
+your own risk.
+
+--------------------------------------------------------------------------
+
+Source: https://opensource.org/license/aal (fetched 2026-07-24).

enforce_cpg/NOTICE

@@ -0,0 +1,9 @@
+enforce-cpg
+Copyright (c) 2026 tommyz4
+https://github.com/tommyz4/enforce-cpg
+
+This product includes software developed by tommyz4.
+Licensed under the Attribution Assurance License (AAL).
+
+Attribution Notice (must be displayed per AAL clause):
+  enforce-cpg — © 2026 tommyz4 — https://github.com/tommyz4/enforce-cpg

enforce_cpg/__init__.py

@@ -0,0 +1,12 @@
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("enforce-cpg")
+except PackageNotFoundError:  # not installed (e.g. running from a raw source tree)
+    __version__ = "0.0.0+unknown"
+
+ATTRIBUTION = (
+    "enforce-cpg — © 2026 tommyz4 — "
+    "https://github.com/tommyz4/enforce-cpg (AAL)"
+)

enforce_cpg/cli.py

@@ -0,0 +1,93 @@
+"""enforce-cpg CLI: index / find-symbol / overview / audit / mod-surface / doctor / ingest."""
+
+import argparse
+import json
+from pathlib import Path
+
+from . import ATTRIBUTION, __version__, query
+from .config import load_config
+from .index import build_index
+from .store import Store
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="enforce-cpg")
+    p.add_argument("--version", action="store_true")
+    sub = p.add_subparsers(dest="cmd")
+
+    pi = sub.add_parser("index")
+    pi.add_argument("--config", default="enforce-cpg.toml")
+    pi.add_argument("--full", action="store_true")
+
+    pr = sub.add_parser("reindex")
+    pr.add_argument("--config", default="enforce-cpg.toml")
+    pr.add_argument("--full", action="store_true")
+
+    pf = sub.add_parser("find-symbol")
+    pf.add_argument("name")
+    pf.add_argument("--kind")
+    pf.add_argument("--config", default="enforce-cpg.toml")
+
+    po = sub.add_parser("overview")
+    po.add_argument("--file")
+    po.add_argument("--class", dest="cls")
+    po.add_argument("--config", default="enforce-cpg.toml")
+
+    pa = sub.add_parser("audit")
+    pa.add_argument("--config", default="enforce-cpg.toml")
+
+    pm = sub.add_parser("mod-surface")
+    pm.add_argument("--source", required=True)
+    pm.add_argument("--config", default="enforce-cpg.toml")
+
+    pd = sub.add_parser("doctor")
+    pd.add_argument("--config", default="enforce-cpg.toml")
+    pd.add_argument("--json", action="store_true", help="Emit the raw report as JSON.")
+
+    pin = sub.add_parser("ingest")
+    pin.add_argument("input", help="A .pbo file or an already-extracted source directory.")
+    pin.add_argument("--name", required=True)
+    pin.add_argument("--kind", choices=["core", "mod"], required=True)
+    pin.add_argument("--after", help="Insert after this existing source (load order).")
+    pin.add_argument("--config", default="enforce-cpg.toml")
+
+    args = p.parse_args(argv)
+    if args.version:
+        print(f"enforce-cpg {__version__}\n{ATTRIBUTION}")
+        return 0
+    if args.cmd == "index":
+        cfg = load_config(Path(args.config))
+        print(ATTRIBUTION)
+        print(json.dumps(build_index(cfg, full=args.full)))
+        return 0
+    if args.cmd == "reindex":
+        cfg = load_config(Path(args.config))
+        print(ATTRIBUTION)
+        print(json.dumps(build_index(cfg, full=args.full)))
+        return 0
+    if args.cmd == "doctor":
+        from . import doctor
+        cfg = load_config(Path(args.config))
+        report = doctor.run(cfg)
+        print(json.dumps(report, indent=2) if args.json else doctor.format_report(report))
+        return 0
+    if args.cmd == "ingest":
+        from . import ingest as ingest_mod
+        res = ingest_mod.ingest(args.config, args.input, args.name, args.kind, args.after)
+        print(json.dumps(res, indent=2))
+        return 0
+    if args.cmd in ("find-symbol", "overview", "audit", "mod-surface"):
+        cfg = load_config(Path(args.config))
+        st = Store(cfg.db_path)
+        if args.cmd == "find-symbol":
+            result = query.find_symbol(st, args.name, args.kind)
+        elif args.cmd == "overview":
+            result = query.get_overview(st, file=args.file, cls=args.cls)
+        elif args.cmd == "audit":
+            result = query.audit_overrides(st)
+        else:
+            result = query.mod_surface(st, args.source)
+        print(json.dumps(result, indent=2))
+        return 0
+    p.print_help()
+    return 1

enforce_cpg/config.py

@@ -0,0 +1,34 @@
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Source:
+    name: str
+    kind: str
+    path: Path
+    load_order: int
+
+
+@dataclass(frozen=True)
+class Config:
+    name: str
+    db_path: Path
+    sources: list[Source]
+    exclude: list[str] = field(default_factory=list)
+
+
+def load_config(path: Path) -> Config:
+    data = tomllib.loads(Path(path).read_text())
+    project = data.get("project", {})
+    sources = [
+        Source(s["name"], s.get("kind", "mod"), Path(s["path"]), i)
+        for i, s in enumerate(data.get("sources", []))
+    ]
+    return Config(
+        name=project.get("name", "unnamed"),
+        db_path=Path(project.get("db_path", ".enforce-cpg/index.db")),
+        sources=sources,
+        exclude=list(project.get("exclude", [])),
+    )

enforce_cpg/discovery.py

@@ -0,0 +1,46 @@
+import fnmatch
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from .config import Source
+
+_LAYER_RE = re.compile(r"^([1-5])_(\w+)$")
+
+# Directory names that never contain Enforce Script and whose stray *.c files
+# (vendored C extensions, tooling) would otherwise become noise diagnostics.
+_DEFAULT_EXCLUDE_DIRS = (
+    ".venv", "venv", "node_modules", ".git", ".svn", "__pycache__", ".enforce-cpg",
+)
+
+
+@dataclass(frozen=True)
+class FileEntry:
+    path: Path
+    source_name: str
+    layer: int
+    layer_name: str
+
+
+def _layer_for(path: Path, root: Path) -> tuple[int, str]:
+    for part in path.relative_to(root).parts:
+        m = _LAYER_RE.match(part)
+        if m:
+            return int(m.group(1)), part
+    return 0, ""
+
+
+def discover(sources: list[Source], exclude: list[str] = ()) -> list[FileEntry]:
+    """Find every ``*.c`` under each source root, skipping any file whose path
+    passes through an excluded directory. ``_DEFAULT_EXCLUDE_DIRS`` is always
+    applied; ``exclude`` adds project-configured dir-name globs on top."""
+    patterns = _DEFAULT_EXCLUDE_DIRS + tuple(exclude)
+    entries: list[FileEntry] = []
+    for src in sources:
+        for c in sorted(src.path.rglob("*.c")):
+            dir_parts = c.relative_to(src.path).parts[:-1]
+            if any(fnmatch.fnmatch(part, pat) for part in dir_parts for pat in patterns):
+                continue
+            layer, layer_name = _layer_for(c, src.path)
+            entries.append(FileEntry(c, src.name, layer, layer_name))
+    return entries

enforce_cpg/doctor.py

@@ -0,0 +1,103 @@
+"""Setup + index-health report (issue #8).
+
+``run(cfg)`` returns a structured report the CLI and MCP tool render: which
+sources resolved and their live parse coverage, whether a vanilla (core) source
+is configured, a diagnostics breakdown, and the unresolved-reference hotspots
+that usually mean a source still needs ingesting. Read-only; never raises on a
+bad file (parse failures are counted, not propagated).
+"""
+
+from collections import Counter
+from pathlib import Path
+
+from .config import Config
+from .discovery import discover
+from .parser import parse
+from .store import Store
+
+
+def _parse_coverage(entries) -> tuple[int, int]:
+    ok = err = 0
+    for e in entries:
+        try:
+            if parse(e.path.read_bytes()).root_node.has_error:
+                err += 1
+            else:
+                ok += 1
+        except Exception:  # noqa: BLE001 — coverage probe must never crash
+            err += 1
+    return ok, err
+
+
+def run(cfg: Config) -> dict:
+    report: dict = {"project": cfg.name, "warnings": [], "sources": [], "index": {}}
+
+    if not any(s.kind == "core" for s in cfg.sources):
+        report["warnings"].append(
+            "No core (vanilla) source configured — inheritance/override chains "
+            "will dangle at base classes. Extract the game's scripts.pbo and add "
+            'a [[sources]] kind="core" entry (see docs/vanilla-extraction.md).'
+        )
+
+    for s in cfg.sources:
+        entries = discover([s], cfg.exclude)
+        ok, err = _parse_coverage(entries)
+        total = ok + err
+        report["sources"].append({
+            "name": s.name,
+            "kind": s.kind,
+            "path": str(s.path),
+            "resolved": s.path.exists(),
+            "load_order": s.load_order,
+            "files": total,
+            "parse_ok": ok,
+            "parse_rate": round(ok / total, 4) if total else None,
+        })
+
+    db = Path(cfg.db_path)
+    if not db.exists():
+        report["index"] = {"indexed": False,
+                           "note": "not indexed yet — run `enforce-cpg index --full`"}
+        return report
+
+    store = Store(cfg.db_path)
+    diags = store.diagnostics()
+    raws: Counter = Counter()
+    for e in store.edges():
+        if e.dst_id is None:
+            raw = e.attrs.get("raw")
+            if raw:
+                raws[raw] += 1
+    report["index"] = {
+        "indexed": True,
+        "nodes": len(store.nodes()),
+        "diagnostics": dict(Counter(d["kind"] for d in diags)),
+        "diagnostic_files_top": [f for f, _ in Counter(d["file"] for d in diags).most_common(10)],
+        "unresolved_top": raws.most_common(10),
+    }
+    return report
+
+
+def format_report(report: dict) -> str:
+    """Human-readable summary of ``run``'s dict for the CLI."""
+    lines = [f"enforce-cpg doctor — project '{report['project']}'", ""]
+    for w in report["warnings"]:
+        lines.append(f"  ⚠ {w}")
+    if report["warnings"]:
+        lines.append("")
+    lines.append("Sources (load order):")
+    for s in report["sources"]:
+        rate = "n/a" if s["parse_rate"] is None else f"{s['parse_rate']:.1%}"
+        mark = "ok" if s["resolved"] else "MISSING"
+        lines.append(f"  [{s['load_order']}] {s['name']} ({s['kind']}) — {mark}, "
+                     f"{s['files']} files, parse {rate}")
+    idx = report["index"]
+    lines.append("")
+    if not idx.get("indexed"):
+        lines.append(f"Index: {idx['note']}")
+    else:
+        lines.append(f"Index: {idx['nodes']} nodes; diagnostics {idx['diagnostics']}")
+        if idx["unresolved_top"]:
+            top = ", ".join(f"{n}×{c}" for n, c in idx["unresolved_top"][:5])
+            lines.append(f"  Top unresolved refs (ingest a source that defines these?): {top}")
+    return "\n".join(lines)