cg-code-graph 0.10.1__py3-none-any.whl

codegraph/core/fsutil.py

@@ -0,0 +1,61 @@
+"""File discovery helpers that never abort on odd entries (dangling symlinks, links out of the repo, races).
+
+A dangling symlink (e.g. a committed link to a file on the author's machine) is skipped with a warning by
+discovery, and hashed by its link target in cache fingerprints, so one bad entry never stops a language."""
+from __future__ import annotations
+
+import hashlib
+import os
+import sys
+
+_warned: set[str] = set()
+
+
+def is_real_file(path: str | os.PathLike) -> bool:
+    """True for a readable regular file (following symlinks); False for dangling links, dirs, sockets..."""
+    try:
+        return os.path.isfile(path)
+    except OSError:
+        return False
+
+
+def warn_skip(path: str | os.PathLike, why: str = "dangling symlink") -> None:
+    p = str(path)
+    if p not in _warned:
+        _warned.add(p)
+        print(f"codegraph: skipping {p}: {why}", file=sys.stderr)
+
+
+def keep_file(path: str | os.PathLike) -> bool:
+    """Discovery filter: real files pass; a broken entry is reported once and skipped."""
+    if is_real_file(path):
+        return True
+    if os.path.islink(path):
+        warn_skip(path)
+    return False
+
+
+# Bumped whenever the cache key scheme changes: every extractor / SCIP cache key includes it, so entries written by
+# an older cg are never reused (TS and Dart drop them on the next write, the SCIP cache prunes them).
+# 2: keys hash file content (was size + mtime, which returned stale facts after a same-size edit with a restored mtime).
+CACHE_VERSION = 3
+
+
+def content_key(path: str | os.PathLike) -> str:
+    """'size|blake2b of the bytes' for cache fingerprints. Content, not mtime: an edit that keeps the size and the old
+    mtime must still invalidate. A dangling symlink hashes as 'link|<target>', anything else unreadable by a marker."""
+    if is_real_file(path):          # regular files only: never open a FIFO or device found in the tree
+        try:
+            h = hashlib.blake2b(digest_size=16)
+            n = 0
+            with open(path, "rb") as fh:
+                for chunk in iter(lambda: fh.read(1 << 20), b""):
+                    h.update(chunk)
+                    n += len(chunk)
+            return f"{n}|{h.hexdigest()}"
+        except OSError:
+            return "unreadable"
+    try:
+        return f"link|{os.readlink(path)}"
+    except OSError:
+        return "missing" if not os.path.lexists(path) else "special"

codegraph/core/generated.py

@@ -0,0 +1,575 @@
+"""Generated, copied and vendored files: one classifier for every language plugin and the coverage scan.
+
+A file nobody edits by hand gets a classification (`generated`, `copied` or `vendored`) and the reason it was
+recognised, from (first match wins, in this order):
+
+  1. the project's `.cg.yaml`: `generated.keep` (never classified), `generated.paths`, `generated.vendored`
+  2. `.gitattributes` at any depth: `linguist-generated` / `linguist-vendored`, with git's precedence (a deeper file and
+     a later line win; `-attr` / `attr=false` marks a file as hand-written, `!attr` returns it to detection)
+  3. copy targets: Capacitor's `webDir` copied into `android/app/src/main/assets/public/` and `ios/App/App/public/`
+     (plus the `capacitor.config.json` / `capacitor.plugins.json` copies and the Cordova plugin projects that
+     `cap sync` writes), Cordova's `www/` copied into `platforms/<platform>/www/`; each copied file maps back to its
+     source (`copy_of`)
+  4. files listed in `.openapi-generator/FILES` (OpenAPI Generator output)
+  5. framework build output and generator file names (codegraph/presets/common.yaml `generated`): `.nuxt/`, `.next/`,
+     `*.g.dart`, `*_pb2.py`, `*.pb.go`, `GeneratedPluginRegistrant.java` ...
+  6. a generator banner in the file's leading comment block: `@generated`, `Code generated ... DO NOT EDIT.`,
+     `GENERATED CODE - DO NOT MODIFY BY HAND`, `<auto-generated>`, `This file is automatically generated`, protoc /
+     gRPC and OpenAPI Generator / Swagger Codegen banners, Sourcery / SwiftGen / swift-openapi-generator / Mockolo
+
+By default these files are kept out of the graph (every walk asks `PathRules.excluded`, and a final pass drops nodes
+whose file is classified) and `cg coverage` lists them by reason. Files that serve as resolution input (Nuxt's
+`.nuxt/` types, `*.g.dart` JSON keys) are still read by their plugin. With `cg index --include-generated` (or
+`generated.include: true`) they are indexed and every node from them carries `attrs.generated`."""
+from __future__ import annotations
+
+import fnmatch
+import json
+import os
+import re
+from collections import Counter
+from pathlib import Path
+
+from .. import presets
+
+GENERATED, COPIED, VENDORED = "generated", "copied", "vendored"
+HEADER_BYTES = 4096           # the leading comment block is read from the first 4 KB of a file
+MAX_PATHS = 500               # file paths stored per reason in the index stats (counts are always exact)
+SHOW_PATHS = 5
+
+# generator banners, matched in comment lines of the file's leading comment block
+HEADER_MARKERS: tuple[tuple[str, re.Pattern], ...] = (
+    ("@generated header", re.compile(r"(^|[\s*/#(\"'])@generated\b")),
+    ("'Code generated ... DO NOT EDIT.' header", re.compile(r"\bCode generated\b.*\bDO NOT EDIT\b", re.I)),
+    ("'GENERATED CODE - DO NOT MODIFY BY HAND' header", re.compile(r"GENERATED CODE\s*-\s*DO NOT MODIFY BY HAND", re.I)),
+    ("<auto-generated> header", re.compile(r"<auto-generated\b", re.I)),
+    ("protoc / gRPC banner", re.compile(r"\bgenerated by\b.*\b(protocol buffer compiler|protoc|grpc)\b", re.I)),
+    ("OpenAPI Generator banner", re.compile(r"\bauto[- ]?generated by (the )?(OpenAPI[- ]Generator|Swagger[- ]Codegen)"
+                                            r"|\bGenerated by:? https?://(openapi-generator\.tech|github\.com/swagger-api/swagger-codegen)", re.I)),
+    # Swift generators (#100): Sourcery templates, SwiftGen assets / strings, swift-openapi-generator, Mockolo mocks
+    ("Sourcery banner", re.compile(r"\bGenerated using Sourcery\b")),
+    ("SwiftGen banner", re.compile(r"\bGenerated using SwiftGen\b")),
+    ("swift-openapi-generator banner", re.compile(r"\bGenerated by swift-openapi-generator\b")),
+    ("Mockolo banner", re.compile(r"@Generated by Mockolo\b")),
+    ("'automatically generated' header", re.compile(r"\b(this|the) (file|code|class|module|source) (is|was|has been) "
+                                                    r"(automatically|auto)[- ]?generated\b", re.I)),
+)
+COMMENT_LEADERS = ("//", "#", "/*", "*", "<!--", "--", ";", "(*", "{-")
+SOURCE_EXTS: frozenset[str] = frozenset()      # filled from coverage on first use (all source extensions)
+
+CAPACITOR_CONFIGS = ("capacitor.config.ts", "capacitor.config.js", "capacitor.config.json", "capacitor.config.mts")
+# where `npx cap copy` / `cap sync` writes, relative to the Capacitor app directory
+CAPACITOR_COPY_TARGETS = ("android/app/src/main/assets/public", "ios/App/App/public")
+CAPACITOR_SYNC_FILES = ("android/app/src/main/assets/capacitor.config.json", "android/app/src/main/assets/capacitor.plugins.json",
+                        "android/app/src/main/res/xml/config.xml", "ios/App/App/capacitor.config.json", "ios/App/App/config.xml")
+CAPACITOR_SYNC_DIRS = ("android/capacitor-cordova-android-plugins", "ios/capacitor-cordova-ios-plugins")
+
+
+def _source_exts() -> frozenset[str]:
+    global SOURCE_EXTS
+    if not SOURCE_EXTS:
+        from ..coverage import SUPPORTED, UNSUPPORTED
+        SOURCE_EXTS = frozenset({e for v in SUPPORTED.values() for e in v} | set(UNSUPPORTED)
+                                | {".java", ".kt", ".swift", ".m", ".mm", ".h", ".go", ".cs"})
+    return SOURCE_EXTS
+
+
+def header_marker(path: str | os.PathLike) -> str | None:
+    """Reason of the first generator banner in the file's leading comment block, None without one. Only comment lines
+    before the first line of code count, so a string or docstring that mentions a banner does not."""
+    try:
+        with open(path, "rb") as fh:
+            head = fh.read(HEADER_BYTES)
+    except OSError:
+        return None
+    if not head:
+        return None
+    text = head.decode("utf-8", "replace")
+    if text.startswith("\ufeff"):
+        text = text[1:]
+    in_block = None
+    for i, raw in enumerate(text.splitlines()):
+        line = raw.strip()
+        if not line:
+            continue
+        if i == 0 and line.startswith("#!"):
+            continue
+        if in_block:
+            comment = True
+            if in_block in line:
+                in_block = None
+        else:
+            low = line.lower()
+            comment = low.startswith(COMMENT_LEADERS)
+            if line.startswith("/*") and "*/" not in line[2:]:
+                in_block = "*/"
+            elif line.startswith("<!--") and "-->" not in line[4:]:
+                in_block = "-->"
+            elif line.startswith("{-") and "-}" not in line[2:]:
+                in_block = "-}"
+            elif line.startswith("(*") and "*)" not in line[2:]:
+                in_block = "*)"
+        if not comment:
+            # `package foo;` / `<?php` / `import` ... ends the header; PHP's opening tag is still part of it
+            if line.startswith("<?php") or line == "<?":
+                continue
+            return None
+        for reason, rx in HEADER_MARKERS:
+            if rx.search(line):
+                return reason
+    return None
+
+
+# ------------------------------------------------------------------------------------------- .gitattributes
+def _attr_regex(pattern: str) -> re.Pattern:
+    """gitattributes pattern -> regex over the path relative to the .gitattributes directory (git semantics: no
+    recursive match below a matched directory; use `dir/**`)."""
+    from .paths import glob_regex
+    return re.compile(glob_regex(pattern, below=False))
+
+
+def parse_gitattributes(text: str) -> list[tuple[re.Pattern, str, bool | None]]:
+    """(pattern regex, 'generated' | 'vendored', True / False / None) per linguist attribute of each line."""
+    out = []
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or line.startswith("[attr]"):
+            continue
+        parts = line.split()
+        pat, attrs = parts[0], parts[1:]
+        if pat.startswith('"'):
+            continue                       # quoted patterns (C-style escapes): rare, not read
+        if pat.endswith("/"):
+            continue                       # a directory pattern never matches files in an attributes file
+        rx = None
+        for a in attrs:
+            val: bool | None
+            name = a
+            if a.startswith("-"):
+                name, val = a[1:], False
+            elif a.startswith("!"):
+                name, val = a[1:], None
+            elif "=" in a:
+                name, v = a.split("=", 1)
+                val = v.strip().lower() not in ("false", "0", "no", "off")
+            else:
+                val = True
+            kind = {"linguist-generated": GENERATED, "linguist-vendored": VENDORED}.get(name)
+            if kind:
+                rx = rx or _attr_regex(pat)
+                out.append((rx, kind, val))
+    return out
+
+
+# ------------------------------------------------------------------------------------------- copy targets
+_WEBDIR_RE = re.compile(r"""\bwebDir\s*:\s*(['"`])([^'"`]+)\1""")
+
+
+def capacitor_web_dir(cfg_file: Path) -> str | None:
+    try:
+        text = cfg_file.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+    if cfg_file.suffix == ".json":
+        try:
+            v = (json.loads(text) or {}).get("webDir")
+        except (ValueError, AttributeError):
+            v = None
+    else:
+        m = _WEBDIR_RE.search(text)
+        v = m.group(2) if m else None
+    if not isinstance(v, str) or not v.strip():
+        return None
+    v = v.strip().replace("\\", "/").strip("/")
+    if v.startswith("./"):
+        v = v[2:]
+    return v or None
+
+
+def _ignored_by(dir_: Path, name: str) -> bool:
+    """`name` (a directory of `dir_`) is listed in `dir_/.gitignore` (plain names only: `dist`, `/dist`, `dist/`)."""
+    try:
+        lines = (dir_ / ".gitignore").read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        return False
+    return any(ln.strip().strip("/") == name for ln in lines if ln.strip() and not ln.startswith("#"))
+
+
+def _bundler_output(dir_: Path, name: str) -> str | None:
+    """The bundler config of `dir_` that writes into `name` (Angular's angular.json outputPath), else None."""
+    try:
+        text = (dir_ / "angular.json").read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+    rx = r'"outputPath"\s*:\s*(?:\{[^}]*?"base"\s*:\s*)?"(?:\./)?' + re.escape(name) + r'(?:/[^"]*)?"'
+    return "angular.json outputPath" if re.search(rx, text) else None
+
+
+class Hit(dict):
+    """{"kind": generated | copied | vendored, "reason": ..., optionally "copy_of": source path, "test": True}."""
+
+
+# test folders and test-target directories (#100): a generated file there runs as a test or test support (Sourcery's
+# preview / accessibility test lists, generated test stubs), so by default it stays in the graph as test code, with
+# attrs.generated; only generated non-test sources leave it. `.cg.yaml` generated.paths still excludes anything.
+TEST_DIR = re.compile(r"(?:^|/)(?:tests?|Tests?|__tests__|specs?|androidTest|testFixtures|integrationTest|unitTest|"
+                      r"[^/]*(?:Tests|UITests))/")
+
+
+def _testy(rel: str, h: "Hit | None") -> "Hit | None":
+    if h is not None and h.get("kind") == GENERATED and not h["reason"].startswith(".cg.yaml") and TEST_DIR.search(rel):
+        h = Hit(h, test=True)
+    return h
+
+
+class Classifier:
+    """Classification of one project's files (see the module docstring). `scan(rel, abs)` classifies a file the
+    coverage scan walks (reads its header); `lookup(rel)` answers for any repo-relative path from what the scan
+    recorded plus the path rules."""
+
+    def __init__(self, root: str | Path, cfg: dict | None = None, include: bool = False):
+        from .paths import glob_regex
+        self.root = Path(root)
+        cfg = cfg or {}
+        g = cfg.get("generated") or {}
+        self.include = bool(include or g.get("include"))
+        self.keep = re.compile("|".join(f"(?:{glob_regex(p)})" for p in g["keep"])) if g.get("keep") else None
+        self.user: list[tuple[re.Pattern, Hit]] = []
+        for key, kind in (("paths", GENERATED), ("vendored", VENDORED)):
+            for p in g.get(key) or []:
+                self.user.append((re.compile(glob_regex(p)), Hit(kind=kind, reason=f".cg.yaml generated.{key}")))
+        pre = presets.values("common", "generated", default={}) or {}
+        self.build_dirs: dict[str, str] = dict(pre.get("build_dirs") or {})
+        self.file_globs: list[tuple[str, str]] = list((pre.get("files") or {}).items())
+        self.tool_paths = [(re.compile(glob_regex(g)), r) for g, r in (pre.get("paths") or {}).items()]
+        self._exact_names = {n: r for n, r in self.file_globs if not any(c in n for c in "*?[")}
+        self._name_globs = [(n, r) for n, r in self.file_globs if any(c in n for c in "*?[")]
+        self.attrs: list[tuple[str, list]] = []          # (base dir, rules) in walk order (parents first)
+        self.copies: list[dict] = []                     # {"target", "source", "via", "kind"}
+        self.listed: dict[str, str] = {}                 # rel -> reason (.openapi-generator/FILES)
+        self.files: dict[str, Hit] = {}                  # classified files the scan saw
+        self.pruned: dict[str, str] = {}                 # build output directories the scan did not descend into
+        self._cache: dict[str, Hit | None] = {}
+
+    # -------------------------------------------------- per directory (called by the scan, parents first)
+    def visit_dir(self, rel_dir: str, dp: str, dns: list[str], fns: list[str]) -> None:
+        names = set(fns)
+        if ".gitattributes" in names:
+            try:
+                txt = Path(dp, ".gitattributes").read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                txt = ""
+            rules = parse_gitattributes(txt)
+            if rules:
+                self.attrs.append((rel_dir, rules))
+        pre = f"{rel_dir}/" if rel_dir else ""
+        for cf in CAPACITOR_CONFIGS:
+            if cf in names:
+                web = capacitor_web_dir(Path(dp, cf))
+                src = f"{pre}{web}" if web else None
+                via = f"Capacitor webDir {web!r} ({pre}{cf})" if web else f"Capacitor ({pre}{cf})"
+                for t in CAPACITOR_COPY_TARGETS:
+                    self.copies.append({"target": pre + t, "source": src, "via": via, "kind": COPIED,
+                                        "reason": f"copy of {web}/ (Capacitor webDir)" if web else "Capacitor web asset copy"})
+                for t in CAPACITOR_SYNC_DIRS:
+                    self.copies.append({"target": pre + t, "source": None, "via": f"Capacitor sync ({pre}{cf})",
+                                        "kind": GENERATED, "reason": "Capacitor sync output"})
+                for f in CAPACITOR_SYNC_FILES:
+                    self.listed[pre + f] = "Capacitor sync output"
+                why = None
+                if web and _ignored_by(Path(dp), web.split("/")[0]):
+                    why = f"listed in {pre}.gitignore"
+                elif web:
+                    why = _bundler_output(Path(dp), web)
+                if why:
+                    self.copies.append({"target": pre + web, "source": None, "via": f"Capacitor webDir, {why}",
+                                        "kind": GENERATED, "reason": "web build output (Capacitor webDir)"})
+                break
+        if "config.xml" in names and "www" in dns and "platforms" in dns:
+            try:
+                is_cordova = "<widget" in Path(dp, "config.xml").read_text(encoding="utf-8", errors="replace")[:4096]
+            except OSError:
+                is_cordova = False
+            if is_cordova:
+                for plat in sorted(os.listdir(os.path.join(dp, "platforms"))):
+                    for www in ("www", "app/src/main/assets/www", "platform_www"):
+                        if os.path.isdir(os.path.join(dp, "platforms", plat, www)):
+                            self.copies.append({"target": f"{pre}platforms/{plat}/{www}", "source": f"{pre}www",
+                                                "via": f"Cordova ({pre}config.xml)", "kind": COPIED,
+                                                "reason": "copy of www/ (Cordova platform)"})
+        if ".openapi-generator" in dns and os.path.isfile(os.path.join(dp, ".openapi-generator", "FILES")):
+            try:
+                for ln in Path(dp, ".openapi-generator", "FILES").read_text(encoding="utf-8", errors="replace").splitlines():
+                    ln = ln.strip().strip("/")
+                    if ln and not ln.startswith("#") and ".." not in ln.split("/"):
+                        self.listed.setdefault(pre + ln, "OpenAPI Generator (.openapi-generator/FILES)")
+            except OSError:
+                pass
+
+    def skipped_dir(self, rel: str, name: str) -> None:
+        """The scan does not descend into `rel`: recorded when it is a framework build output directory."""
+        r = self.build_dirs.get(name)
+        if r:
+            self.pruned.setdefault(rel, r)
+
+    # -------------------------------------------------- classification
+    def _attr(self, rel: str) -> Hit | None | bool:
+        """Hit from .gitattributes, False when a linguist attribute marks the file as hand-written, None otherwise."""
+        state: dict[str, bool | None] = {}
+        for base, rules in self.attrs:
+            if base and not rel.startswith(base + "/"):
+                continue
+            sub = rel[len(base) + 1:] if base else rel
+            for rx, kind, val in rules:
+                if rx.match(sub):
+                    state[kind] = val
+        if state.get(VENDORED):
+            return Hit(kind=VENDORED, reason="linguist-vendored (.gitattributes)")
+        if state.get(GENERATED):
+            return Hit(kind=GENERATED, reason="linguist-generated (.gitattributes)")
+        if state.get(GENERATED) is False or state.get(VENDORED) is False:
+            return False
+        return None
+
+    def _copy(self, rel: str) -> Hit | None:
+        best = None
+        for c in self.copies:
+            t = c["target"]
+            if rel == t or rel.startswith(t + "/"):
+                if best is None or len(t) > len(best["target"]):
+                    best = c
+        if best is None:
+            return None
+        h = Hit(kind=best["kind"], reason=best["reason"])
+        if best["source"] and rel != best["target"]:
+            h["copy_of"] = best["source"] + rel[len(best["target"]):]
+        return h
+
+    def _path_rule(self, rel: str) -> Hit | None:
+        parts = rel.split("/")
+        for p in parts[:-1]:
+            # hidden framework directories at any depth; `dist/` / `build/` are only reported (every walk skips them by
+            # name, and a source package can be named `build`)
+            r = self.build_dirs.get(p) if p.startswith(".") else None
+            if r:
+                return Hit(kind=GENERATED, reason=r)
+        for rx, r in self.tool_paths:
+            if rx.match(rel):
+                return Hit(kind=GENERATED, reason=r)
+        name = parts[-1]
+        r = self._exact_names.get(name)
+        if r is None:
+            for g, rr in self._name_globs:
+                if fnmatch.fnmatchcase(name, g):
+                    r = rr
+                    break
+        return Hit(kind=GENERATED, reason=r) if r else None
+
+    def rules_hit(self, rel: str) -> Hit | None:
+        """Classification from everything but the file header (cheap; no file read)."""
+        if self.keep and self.keep.match(rel):
+            return None
+        for rx, h in self.user:
+            if rx.match(rel):
+                return h
+        a = self._attr(rel)
+        if a is False:
+            return None
+        if a:
+            return _testy(rel, a)
+        h = self._copy(rel)
+        if h:
+            return h
+        if rel in self.listed:
+            return _testy(rel, Hit(kind=GENERATED, reason=self.listed[rel]))
+        h = self._path_rule(rel)
+        # build output directories (.nuxt/, .next/ ...) are never test code
+        return h if h is None or h["reason"] in self.build_dirs.values() else _testy(rel, h)
+
+    def scan(self, rel: str, abs_path: str) -> Hit | None:
+        """Classify one file the coverage scan walks: the path rules, then the header of a source file."""
+        h = self.rules_hit(rel)
+        if h is None and not (self.keep and self.keep.match(rel)) and self._attr(rel) is not False:
+            ext = os.path.splitext(rel)[1].lower()
+            if ext in _source_exts():
+                r = header_marker(abs_path)
+                if r:
+                    h = _testy(rel, Hit(kind=GENERATED, reason=r))
+        if h is not None:
+            self.files[rel] = h
+        return h
+
+    def lookup(self, rel: str) -> Hit | None:
+        """Classification of a repo-relative path: what the scan recorded, else the path rules."""
+        h = self.files.get(rel)
+        if h is not None:
+            return h
+        if rel not in self._cache:
+            self._cache[rel] = self.rules_hit(rel)
+        return self._cache[rel]
+
+    def drops(self, h: Hit | None) -> bool:
+        """A classified file the default mode leaves out of the graph (a generated test file stays in)."""
+        return h is not None and not self.include and not h.get("test")
+
+    def excludes(self, rel: str) -> bool:
+        return self.drops(self.lookup(rel))
+
+    def dir_excluded(self, rel_dir: str) -> bool:
+        """A directory every file of which is classified (a copy target, a build output directory, a user glob)."""
+        if self.include or (self.keep and self.keep.match(rel_dir + "/")):
+            return False
+        if any(rx.match(rel_dir + "/") for rx, _ in self.user):
+            return True
+        if any(rel_dir == c["target"] or rel_dir.startswith(c["target"] + "/") for c in self.copies):
+            return True
+        name = rel_dir.rsplit("/", 1)[-1]
+        return name.startswith(".") and name in self.build_dirs
+
+    def dir_regexes(self) -> list[str]:
+        """JavaScript-compatible regexes of the directories excluded as a whole (copy targets, Capacitor sync output,
+        .cg.yaml generated globs); framework build directories are left to each extractor (Nuxt reads `.nuxt/`)."""
+        if self.include:
+            return []
+        out = [f"(?:^{re.escape(c['target'])}(?:/.*)?$)" for c in self.copies]
+        if not self.keep:       # with keep globs the scan's explicit file list carries the .cg.yaml rules
+            out += [f"(?:{rx.pattern})" for rx, _ in self.user]
+        return out
+
+    # -------------------------------------------------- reporting
+    def summary(self) -> dict:
+        """The coverage entry: counts by reason and kind, sample paths per reason, copy targets, build directories."""
+        by_reason, by_kind, kept = Counter(), Counter(), Counter()
+        paths: dict[str, list[str]] = {}
+        kept_paths: dict[str, list[str]] = {}
+        for rel in sorted(self.files):
+            h = self.files[rel]
+            if h.get("test") and not self.include:
+                kept[h["reason"]] += 1
+                kp = kept_paths.setdefault(h["reason"], [])
+                if len(kp) < MAX_PATHS:
+                    kp.append(rel)
+                continue
+            by_reason[h["reason"]] += 1
+            by_kind[h["kind"]] += 1
+            ps = paths.setdefault(h["reason"], [])
+            if len(ps) < MAX_PATHS:
+                ps.append(rel)
+        copies = []
+        for c in self.copies:
+            n = sum(1 for rel in self.files if rel == c["target"] or rel.startswith(c["target"] + "/"))
+            if n:
+                copies.append({"target": c["target"], "source": c["source"], "via": c["via"], "files": n, "reason": c["reason"]})
+        out = {"mode": "indexed" if self.include else "excluded", "files": sum(by_reason.values()),
+               "by_reason": dict(by_reason.most_common()), "by_kind": dict(by_kind.most_common()), "paths": paths}
+        if copies:
+            out["copies"] = copies
+        if kept:
+            out["tests_kept"] = {"files": sum(kept.values()), "by_reason": dict(kept.most_common()), "paths": kept_paths}
+        if self.pruned:
+            out["build_dirs"] = dict(sorted(self.pruned.items())[:MAX_PATHS])
+        return out
+
+
+def for_project(project) -> Classifier | None:
+    return (getattr(project, "options", None) or {}).get("generated")
+
+
+def summary_text(g: dict | None) -> str:
+    """'generated: 412 files excluded (copy of dist/ (Capacitor webDir) 380, linguist-generated 21, @generated header 11)'."""
+    if not g or not (g.get("files") or g.get("build_dirs") or g.get("tests_kept")):
+        return ""
+    parts = ", ".join(f"{r} {n}" for r, n in (g.get("by_reason") or {}).items())
+    s = f"generated: {g['files']} file{'s' if g['files'] != 1 else ''} {g.get('mode', 'excluded')}" + (f" ({parts})" if parts else "")
+    tk = g.get("tests_kept") or {}
+    if tk.get("files"):
+        s += f"; {tk['files']} generated test file{'s' if tk['files'] != 1 else ''} indexed as tests"
+    if g.get("build_dirs"):
+        s += f"; build output not scanned: {', '.join(d + '/' for d in list(g['build_dirs'])[:4])}" + (
+            f" … +{len(g['build_dirs']) - 4}" if len(g["build_dirs"]) > 4 else "")
+    return s
+
+
+def detail_lines(g: dict | None, all_files: bool = False, indent: str = "  ") -> list[str]:
+    if not g or not (g.get("files") or g.get("build_dirs") or g.get("tests_kept")):
+        return []
+    out = [indent + summary_text(g)]
+    for c in g.get("copies") or []:
+        what = f"a copy of {c['source']}/" if c.get("source") else c.get("reason", "generated")
+        out.append(f"{indent}  {c['target']}/ ({c['files']} file{'s' if c['files'] != 1 else ''}) is {what} [{c['via']}]")
+    for reason, ps in (g.get("paths") or {}).items():
+        n = (g.get("by_reason") or {}).get(reason, len(ps))
+        show = ps if all_files else ps[:SHOW_PATHS]
+        more = n - len(show)
+        out.append(f"{indent}  {reason}: " + ", ".join(show) + (f" … +{more} more (--all-files)" if more > 0 else ""))
+    tk = g.get("tests_kept") or {}
+    for reason, ps in (tk.get("paths") or {}).items():
+        n = (tk.get("by_reason") or {}).get(reason, len(ps))
+        show = ps if all_files else ps[:SHOW_PATHS]
+        more = n - len(show)
+        out.append(f"{indent}  {reason}, indexed as test code: " + ", ".join(show)
+                   + (f" … +{more} more (--all-files)" if more > 0 else ""))
+    return out
+
+
+def apply(builder, clf: Classifier) -> dict:
+    """Final pass over the graph: nodes whose file is classified leave the graph with their edges (default), or carry
+    `attrs.generated` (included); an included copy gets a COPY_OF edge to the module node of its source file."""
+    from .plugin import gc_paused
+    by_file: dict[str, Hit | None] = {}
+    drop: set[str] = set()
+    tagged = 0
+    copies = []
+    with gc_paused():
+        for nid, n in builder.nodes.items():
+            f = n.file
+            if not f:
+                continue
+            h = by_file.get(f, 0)
+            if h == 0:
+                h = by_file[f] = clf.lookup(f)
+            if h is None:
+                continue
+            if clf.include or h.get("test"):
+                n.attrs = {**(n.attrs or {}), "generated": dict(h)}
+                tagged += 1
+                if h.get("copy_of") and n.kind == "module":
+                    copies.append((nid, n.file, h["copy_of"]))
+            else:
+                drop.add(nid)
+        edges_dropped = 0
+        if drop:
+            for nid in drop:
+                del builder.nodes[nid]
+            dead = [k for k, e in builder.edges.items() if e.src in drop or e.dst in drop]
+            for k in dead:
+                del builder.edges[k]
+            edges_dropped = len(dead)
+    linked = 0
+    if copies:
+        mods = {n.file: nid for nid, n in builder.nodes.items() if n.kind == "module" and n.file}
+        for nid, f, src in copies:
+            dst = mods.get(src)
+            if dst and dst != nid:
+                builder.add_edge(nid, dst, "COPY_OF", file=f, line=1)
+                linked += 1
+    with_nodes = sum(1 for h in by_file.values() if h)
+    out = {**classified_counts(clf), "mode": "indexed" if clf.include else "excluded"}
+    if clf.include:
+        out.update(files_with_nodes=with_nodes, nodes_labelled=tagged, copy_of_edges=linked)
+    else:
+        out.update(files_with_dropped_nodes=with_nodes, nodes_dropped=len(drop), edges_dropped=edges_dropped)
+    return out
+
+
+def classified_counts(clf: Classifier) -> dict:
+    """The files the classifier labelled (the up-front scan, the same list `cg coverage` shows): the total, per
+    language (coverage language keys; `other` for non-source files) and per reason / kind."""
+    from ..coverage import UNSUPPORTED, _lang_of_file
+    by_lang, by_reason, by_kind = Counter(), Counter(), Counter()
+    for rel, h in clf.files.items():
+        by_lang[_lang_of_file(rel) or UNSUPPORTED.get(os.path.splitext(rel)[1].lower()) or "other"] += 1
+        by_reason[h["reason"]] += 1
+        by_kind[h["kind"]] += 1
+    return {"files": len(clf.files), "by_language": dict(by_lang.most_common()), "by_reason": dict(by_reason.most_common()),
+            "by_kind": dict(by_kind.most_common())}