codetrail-cli 1.4.1__py3-none-any.whl

codetrail/extract/__init__.py

@@ -0,0 +1,249 @@
+"""Extractors turn a target's files into facts (design section 5).
+
+An extractor sees one file at a time (`extract`), after being told once which files it will see (`prepare`), and
+then turns the references it found into relations against every entity known from all extractors (`resolve`).
+Per-file extraction keeps a later cache keyed by blob and extractor version possible without changing this interface.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass, field, replace
+from pathlib import Path, PurePosixPath
+from typing import Any, Protocol
+
+import yaml
+
+from codetrail.facts import Entity, Relation, RelationKind, Source
+
+
+@dataclass(frozen=True)
+class Reference:
+    """Something a file points at by name, which `resolve` turns into a relation if it can."""
+
+    source_id: str
+    kind: RelationKind
+    target: str
+    sources: tuple[Source, ...] = ()
+    attributes: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class FileFacts:
+    path: str
+    entities: tuple[Entity, ...] = ()
+    references: tuple[Reference, ...] = ()
+
+
+@dataclass(frozen=True)
+class Resolution:
+    relations: list[Relation]
+    unresolved: int = 0
+
+
+class Extractor(Protocol):
+    name: str
+    version: int
+
+    def handles(self, path: str) -> bool: ...
+
+    def prepare(self, paths: Sequence[str]) -> None: ...
+
+    def extract(self, path: str, content: bytes) -> FileFacts: ...
+
+    def resolve(self, files: Sequence[FileFacts], known: Mapping[str, Entity]) -> Resolution: ...
+
+
+@dataclass(frozen=True)
+class Extraction:
+    entities: list[Entity]
+    relations: list[Relation]
+    warnings: list[str]
+    unresolved: dict[str, int]
+    system: dict[str, int] = field(default_factory=dict)  # connections the system pass found, per rule
+
+
+DEFAULT_MAX_FILE_BYTES = 1_000_000
+URL_CREDENTIALS = re.compile(r"(://)[^/\s]*@")
+LOCAL_SPECIFIERS = ("npm:", "workspace:", "file:", "link:", "portal:", "patch:")
+
+
+def without_credentials(text: str) -> str:
+    """A specifier or URL without user or password: scheme://user:pass@host and user:pass@host:path."""
+    text = URL_CREDENTIALS.sub(r"\1", text)
+    authority = text.split("/", 1)[0]
+    if "://" not in text and "@" in authority and ":" in authority and not text.startswith(LOCAL_SPECIFIERS):
+        text = text[authority.rindex("@") + 1 :]
+    return text
+
+
+class _NoAliases(yaml.SafeLoader):
+    """safe_load, refusing YAML aliases, so a small file can't expand into an enormous one (a billion-laughs file).
+
+    YAML 1.1 base-60 integers (`1:30`) stay text, as YAML 1.2 reads them: their conversion takes quadratic time.
+    """
+
+    def compose_node(self, parent: Any, index: Any) -> Any:
+        if self.check_event(yaml.events.AliasEvent):
+            raise yaml.YAMLError("aliases are not read")
+        return super().compose_node(parent, index)
+
+    def construct_yaml_int(self, node: Any) -> Any:
+        value = self.construct_scalar(node)
+        return value if ":" in value else super().construct_yaml_int(node)
+
+
+_NoAliases.add_constructor("tag:yaml.org,2002:int", _NoAliases.construct_yaml_int)
+
+
+def load_yaml_without_aliases(text: str) -> tuple[yaml.Node | None, Any]:
+    """A target's YAML document, read in one pass: its node tree (for line numbers) and its data.
+
+    Raises yaml.YAMLError on an alias or a tag safe_load refuses, and other errors on malformed scalars or deep
+    nesting, so a caller must treat any exception as an unreadable file (the runner makes it a warning).
+    """
+    loader = _NoAliases(text)
+    try:
+        root = loader.get_single_node()
+        return root, loader.construct_document(root) if root is not None else None
+    finally:
+        loader.dispose()
+
+
+DEFAULT_MAX_ATTRIBUTE_CHARS = 300
+
+
+def run_extractors(
+    source: Path,
+    paths: Iterable[str],
+    extractors: Sequence[Extractor],
+    max_file_bytes: int = DEFAULT_MAX_FILE_BYTES,
+    max_attribute_chars: int = DEFAULT_MAX_ATTRIBUTE_CHARS,
+) -> Extraction:
+    """Runs every extractor over the listed files of `source`; nothing outside the list is read.
+
+    Files over `max_file_bytes` are skipped with a warning, and facts whose attributes aren't plain JSON become a
+    warning for their file, so no file can stall or break an update. Text attributes come from the target's files and
+    reach prompts and pages, so each is cut to `max_attribute_chars`, and a fact whose id is longer is skipped.
+    """
+    listed = sorted(paths)
+    warnings: list[str] = []
+    entities: dict[str, Entity] = {}
+    found: dict[str, list[FileFacts]] = {}
+    for extractor in extractors:
+        handled = [path for path in listed if extractor.handles(path)]
+        found[extractor.name] = []
+        try:
+            extractor.prepare(handled)
+        except Exception as error:  # one extractor's bad input never fails the update; its files are skipped
+            warnings.append(f"{extractor.name}: could not prepare ({type(error).__name__})")
+            continue
+        for path in handled:
+            file = source / PurePosixPath(path)
+            if file.stat().st_size > max_file_bytes:
+                warnings.append(f"{extractor.name}: {path}: skipped, larger than {max_file_bytes} bytes")
+                continue
+            try:
+                facts = extractor.extract(path, file.read_bytes())
+                for attributes in [entity.attributes for entity in facts.entities] + [
+                    reference.attributes for reference in facts.references
+                ]:
+                    json.dumps(dict(attributes))
+            except Exception as error:
+                warnings.append(f"{extractor.name}: {path}: could not be read ({type(error).__name__})")
+                continue
+            facts = _cut_attributes(facts, max_attribute_chars)
+            if any(len(entity.id) > max_attribute_chars for entity in facts.entities):
+                warnings.append(
+                    f"{extractor.name}: {path}: skipped a fact whose id is longer than {max_attribute_chars} characters"
+                )
+                facts = replace(facts, entities=tuple(e for e in facts.entities if len(e.id) <= max_attribute_chars))
+            found[extractor.name].append(facts)
+            for entity in facts.entities:
+                _merge(entities, entity, extractor.name, path, warnings)
+    relations: dict[tuple[str, str, str], Relation] = {}
+    unresolved: dict[str, int] = {}
+    for extractor in extractors:
+        try:
+            resolution = extractor.resolve(found[extractor.name], entities)
+        except Exception as error:  # its entities stay; only its relations are lost
+            warnings.append(f"{extractor.name}: could not resolve references ({type(error).__name__})")
+            continue
+        dangling = [r for r in resolution.relations if r.source_id not in entities or r.target_id not in entities]
+        for relation in resolution.relations:
+            if relation not in dangling:
+                relations.setdefault(relation.key, relation)
+        if resolution.unresolved or dangling:
+            unresolved[extractor.name] = resolution.unresolved + len(dangling)
+    return Extraction(
+        entities=sorted(entities.values(), key=lambda entity: entity.id),
+        relations=sorted(relations.values(), key=lambda relation: relation.key),
+        warnings=warnings,
+        unresolved=unresolved,
+    )
+
+
+def check_facts(
+    entities: Sequence[Entity], relations: Sequence[Relation], limit: int
+) -> tuple[list[Entity], list[Relation], list[str]]:
+    """The checks `run_extractors` applies, for facts made outside an extractor (the system pass, design 17.3).
+
+    Attributes must be plain JSON and are cut to `limit` characters; a fact whose id is longer is dropped, and so is
+    every relation whose ends are no longer both kept. Warnings name no content.
+    """
+    kept: list[Entity] = []
+    warnings: list[str] = []
+    for entity in entities:
+        try:
+            json.dumps(dict(entity.attributes))
+        except TypeError, ValueError:
+            warnings.append(f"system: a fact's attributes weren't plain data ({entity.kind})")
+            continue
+        if len(entity.id) > limit:
+            warnings.append(f"system: skipped a fact whose id is longer than {limit} characters ({entity.kind})")
+            continue
+        kept.append(replace(entity, attributes=_cut(entity.attributes, limit)))
+    ids = {entity.id for entity in kept}
+    related = []
+    for relation in relations:
+        try:
+            json.dumps(dict(relation.attributes))
+        except TypeError, ValueError:
+            continue
+        if relation.source_id in ids and relation.target_id in ids:
+            related.append(replace(relation, attributes=_cut(relation.attributes, limit)))
+    return kept, related, warnings
+
+
+def _cut(attributes: Mapping[str, Any], limit: int) -> dict[str, Any]:
+    def cut(value: Any) -> Any:
+        if isinstance(value, str) and len(value) > limit:
+            return value[: limit - 1] + "…"
+        return [cut(item) for item in value] if isinstance(value, list) else value
+
+    return {key: cut(value) for key, value in attributes.items()}
+
+
+def _cut_attributes(facts: FileFacts, limit: int) -> FileFacts:
+    def cut_all(attributes: Mapping[str, Any]) -> dict[str, Any]:
+        return _cut(attributes, limit)
+
+    return replace(
+        facts,
+        entities=tuple(replace(entity, attributes=cut_all(entity.attributes)) for entity in facts.entities),
+        references=tuple(replace(item, attributes=cut_all(item.attributes)) for item in facts.references),
+    )
+
+
+def _merge(entities: dict[str, Entity], entity: Entity, extractor: str, path: str, warnings: list[str]) -> None:
+    existing = entities.get(entity.id)
+    if existing is None:
+        entities[entity.id] = entity
+        return
+    if dict(existing.attributes) != dict(entity.attributes):
+        first = existing.sources[0].path if existing.sources else "another file"
+        warnings.append(f"{extractor}: {entity.id} has different attributes in {path}; kept {first}'s")
+    sources = existing.sources + tuple(source for source in entity.sources if source not in existing.sources)
+    entities[entity.id] = Entity(existing.id, existing.kind, existing.attributes, sources)

codetrail/extract/adr.py

@@ -0,0 +1,98 @@
+"""The adr extractor: decisions, their status, and what supersedes what (design section 5.2).
+
+A decision needs a number, from a heading such as `# 0023. Title` or a file name such as `0023-title.md`; files
+without one (an index, a template) are skipped. Its status comes from a `Status:` line or the first line under a
+`## Status` heading. The body stays text for Claude to read; only this metadata becomes facts.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from pathlib import PurePosixPath
+
+from pathspec import GitIgnoreSpec
+
+from codetrail.extract import FileFacts, Reference, Resolution
+from codetrail.facts import Entity, EntityKind, Relation, RelationKind, Source
+
+# Lines are right-stripped before matching, so no lazy group meets trailing whitespace (no quadratic backtracking).
+HEADING = re.compile(r"^#\s+(?:ADR[- ]?)?(\d+)[.:]?\s+(.+)$", re.IGNORECASE)
+FILE_NUMBER = re.compile(r"^(\d+)[-_]")
+STATUS_LINE = re.compile(r"^(?:[-*]\s*)?\**status\**\s*:\s*\**\s*(.+)$", re.IGNORECASE)
+DATE_LINE = re.compile(r"^(?:[-*]\s*)?\**date\**\s*:\s*\**\s*(\d{4}-\d{2}-\d{2})", re.IGNORECASE)
+SUPERSEDED_BY = re.compile(r"superseded\s+by\s+(?:ADR[- ]?)?(\d+)", re.IGNORECASE)
+
+
+def decision_id(number: str) -> str:
+    return f"decision:ADR-{int(number):04d}"
+
+
+class AdrExtractor:
+    name = "adr"
+    version = 1
+
+    def __init__(self, globs: Sequence[str]) -> None:
+        self._spec = GitIgnoreSpec.from_lines(globs)
+
+    def handles(self, path: str) -> bool:
+        return path.endswith(".md") and self._spec.match_file(path)
+
+    def prepare(self, paths: Sequence[str]) -> None:
+        return None
+
+    def extract(self, path: str, content: bytes) -> FileFacts:
+        lines = [line.rstrip() for line in content.decode("utf-8", "replace").splitlines()]
+        number, title = None, None
+        for line in lines:
+            heading = HEADING.match(line)
+            if heading:
+                number, title = heading.group(1), heading.group(2)
+                break
+        if number is None:
+            from_name = FILE_NUMBER.match(PurePosixPath(path).name)
+            if from_name is None:
+                return FileFacts(path)
+            number = from_name.group(1)
+            title = next(
+                (line.lstrip("# ").strip() for line in lines if line.startswith("# ")), PurePosixPath(path).stem
+            )
+        status_text, date = _status(lines), _date(lines)
+        attributes = {"number": f"{int(number):04d}", "title": title or "", "path": path}
+        if status_text:
+            attributes["status"] = re.split(r"[\s(]", status_text.strip().lower(), maxsplit=1)[0]
+        if date:
+            attributes["date"] = date
+        identity = decision_id(number)
+        references = []
+        superseded = SUPERSEDED_BY.search(status_text or "")
+        if superseded:
+            references.append(Reference(decision_id(superseded.group(1)), RelationKind.SUPERSEDES, identity,
+                                        (Source(path),)))  # fmt: skip
+        return FileFacts(path, (Entity(identity, EntityKind.DECISION, attributes, (Source(path),)),), tuple(references))
+
+    def resolve(self, files: Sequence[FileFacts], known: Mapping[str, Entity]) -> Resolution:
+        relations = [
+            Relation(reference.source_id, reference.kind, reference.target, {}, reference.sources)
+            for file in files
+            for reference in file.references
+        ]
+        return Resolution(relations)
+
+
+def _status(lines: list[str]) -> str | None:
+    for index, line in enumerate(lines):
+        match = STATUS_LINE.match(line.strip())
+        if match:
+            return match.group(1)
+        if re.match(r"^#{2,}\s*status\s*$", line.strip(), re.IGNORECASE):
+            return next((following.strip() for following in lines[index + 1 :] if following.strip()), None)
+    return None
+
+
+def _date(lines: list[str]) -> str | None:
+    for line in lines:
+        match = DATE_LINE.match(line.strip())
+        if match:
+            return match.group(1)
+    return None

codetrail/extract/github_actions.py

@@ -0,0 +1,140 @@
+"""The github_actions extractor: deploy evidence from GitHub Actions workflows, and nothing else (design 17.2).
+
+Workflows are read with a SafeLoader that refuses aliases. Each step that deploys (a known command, or a known deploy
+action) becomes a `deployment` fact with its kind, its target name when one is given, the folder it runs in and its
+line, which comes from the parser. Step text, `env` values and `secrets.*` references are never recorded: only the
+kind, a plain target name, a job id in GitHub's grammar and a folder of plain path segments.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from pathlib import PurePosixPath
+from typing import Any
+
+import yaml
+
+from codetrail.extract import FileFacts, Resolution, load_yaml_without_aliases
+from codetrail.facts import Entity, EntityKind, Relation, Source
+
+# Only plain names reach a fact, so nothing secret-shaped, templated or instruction-like does.
+PLAIN_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9-]{0,62}")
+JOB_ID = re.compile(r"[A-Za-z_][A-Za-z0-9_-]{0,99}")
+SEGMENT = re.compile(r"[A-Za-z0-9._-]+")
+COMMANDS = [
+    ("cloudflare", re.compile(r"\bwrangler(?:@[\w.^~-]+)?\s+(?:deploy|publish)\b")),
+    (
+        "google_cloud",
+        re.compile(r"\bgcloud\s+run\s+(?:deploy|services\s+replace|jobs\s+deploy)\s+(?P<target>[^\s\\]+)?"),
+    ),
+    ("terraform", re.compile(r"\bterraform\s+apply\b")),
+    ("fly", re.compile(r"\bfly(?:ctl)?\s+deploy\b")),
+    ("npm_script", re.compile(r"\b(?:npm\s+run|pnpm\s+run|yarn(?:\s+run)?)\s+deploy\b")),  # `pnpm deploy` copies files
+]
+ACTIONS = {
+    "cloudflare/wrangler-action": "cloudflare",
+    "google-github-actions/deploy-cloudrun": "google_cloud",
+    "superfly/flyctl-actions": "fly",
+}
+
+
+class GitHubActionsExtractor:
+    name = "github_actions"
+    version = 1
+
+    def __init__(self, max_steps: int = 5000) -> None:
+        self._max_steps = max_steps
+
+    def handles(self, path: str) -> bool:
+        return path.startswith(".github/workflows/") and path.endswith((".yml", ".yaml")) and path.count("/") == 2
+
+    def prepare(self, paths: Sequence[str]) -> None:
+        pass
+
+    def extract(self, path: str, content: bytes) -> FileFacts:
+        root, data = load_yaml_without_aliases(content.decode("utf-8"))
+        jobs = data.get("jobs") if isinstance(data, dict) else None
+        if not isinstance(jobs, dict) or root is None:
+            return FileFacts(path)
+        lines = _step_lines(root)
+        entities: list[Entity] = []
+        visited = 0
+        for job_name, job in jobs.items():
+            if not isinstance(job_name, str) or not JOB_ID.fullmatch(job_name):
+                continue  # GitHub's job-id grammar; anything else isn't a job, and its text never reaches a fact
+            if not isinstance(job, dict) or not isinstance(job.get("steps"), list):
+                continue
+            defaults = job.get("defaults")
+            run_defaults = defaults.get("run") if isinstance(defaults, dict) else None
+            job_folder = _folder(run_defaults.get("working-directory")) if isinstance(run_defaults, dict) else ""
+            for index, step in enumerate(job["steps"]):
+                visited += 1
+                if visited > self._max_steps:
+                    return FileFacts(path, tuple(entities))
+                found = _deploy(step) if isinstance(step, dict) else None
+                if found is None:
+                    continue
+                kind, target = found
+                folder = _folder(step.get("working-directory")) if "working-directory" in step else job_folder
+                attributes: dict[str, Any] = {"kind": kind, "job": job_name}
+                if folder is not None:  # an unusable folder is no folder: no arrow is drawn on a guess
+                    attributes["folder"] = folder
+                if target and PLAIN_NAME.fullmatch(target):
+                    attributes["target"] = target
+                line = lines.get((job_name, index))
+                entities.append(Entity(f"deployment:{path}#{job_name}/{index}", EntityKind.DEPLOYMENT, attributes,
+                                       (Source(path, line, line) if line else Source(path),)))  # fmt: skip
+        return FileFacts(path, tuple(entities))
+
+    def resolve(self, files: Sequence[FileFacts], known: Mapping[str, Any]) -> Resolution:
+        return Resolution(list[Relation]())
+
+
+def _step_lines(root: yaml.Node) -> dict[tuple[str, int], int]:
+    """Each step's line, from the parser's own positions: exact, and one pass over the document."""
+    lines: dict[tuple[str, int], int] = {}
+    jobs = _value(root, "jobs")
+    if not isinstance(jobs, yaml.MappingNode):
+        return lines
+    for key, job in jobs.value:
+        steps = _value(job, "steps")
+        if isinstance(key, yaml.ScalarNode) and isinstance(steps, yaml.SequenceNode):
+            for index, step in enumerate(steps.value):
+                lines[(str(key.value), index)] = step.start_mark.line + 1
+    return lines
+
+
+def _value(node: yaml.Node, name: str) -> yaml.Node | None:
+    if not isinstance(node, yaml.MappingNode):
+        return None
+    return next((value for key, value in node.value if isinstance(key, yaml.ScalarNode) and key.value == name), None)
+
+
+def _folder(value: Any) -> str | None:
+    """A working directory as a repository folder ("" is the root), or None unless every part is a plain segment."""
+    if value is None:
+        return ""
+    if not isinstance(value, str) or value.startswith("/"):
+        return None
+    parts = [part for part in PurePosixPath(value).parts if part != "."]
+    if any(part == ".." or not SEGMENT.fullmatch(part) for part in parts):
+        return None  # templated, escaping, or not a plain folder name
+    return "/".join(parts)
+
+
+def _deploy(step: Mapping[str, Any]) -> tuple[str, str | None] | None:
+    uses = step.get("uses")
+    if isinstance(uses, str):
+        action = uses.split("@", 1)[0]
+        if action in ACTIONS:
+            settings = step.get("with") if isinstance(step.get("with"), dict) else {}
+            target = settings.get("service") if isinstance(settings, dict) else None
+            return ACTIONS[action], target if isinstance(target, str) else None
+    run = step.get("run")
+    if isinstance(run, str):
+        for kind, pattern in COMMANDS:
+            match = pattern.search(run)
+            if match:
+                return kind, match.groupdict().get("target")
+    return None

codetrail/extract/openapi.py

@@ -0,0 +1,101 @@
+"""The openapi extractor: an OpenAPI document's routes, its schemas, and what uses what (design section 5.2).
+
+Only local references (`#/components/schemas/<name>`) become relations; a remote or file `$ref` is never followed.
+Documents are walked iteratively, to a fixed depth, so no nesting can exhaust the stack. YAML aliases are refused:
+they let a few hundred bytes stand for an unbounded tree (or a loop), and OpenAPI documents don't need them.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator, Mapping, Sequence
+from pathlib import PurePosixPath
+from typing import Any
+
+from pathspec import GitIgnoreSpec
+
+from codetrail.extract import FileFacts, Reference, Resolution, load_yaml_without_aliases
+from codetrail.facts import Entity, EntityKind, Relation, RelationKind, Source
+
+METHODS = ("get", "put", "post", "delete", "patch", "head", "options", "trace")
+SCHEMA_REF = "#/components/schemas/"
+MAX_DEPTH = 64
+
+
+def local_refs(value: Any) -> Iterator[str]:
+    """The schema names of every local $ref inside `value`, walked iteratively to MAX_DEPTH."""
+    stack: list[tuple[Any, int]] = [(value, 0)]
+    while stack:
+        node, depth = stack.pop()
+        if depth > MAX_DEPTH:
+            continue
+        if isinstance(node, Mapping):
+            ref = node.get("$ref")
+            if isinstance(ref, str) and ref.startswith(SCHEMA_REF):
+                yield ref.removeprefix(SCHEMA_REF)
+            stack.extend((child, depth + 1) for child in node.values())
+        elif isinstance(node, list):
+            stack.extend((child, depth + 1) for child in node)
+
+
+def _text(value: Any) -> str:
+    return value if isinstance(value, str) else ""
+
+
+class OpenApiExtractor:
+    name = "openapi"
+    version = 1
+
+    def __init__(self, globs: Sequence[str]) -> None:
+        self._spec = GitIgnoreSpec.from_lines(globs)
+
+    def handles(self, path: str) -> bool:
+        return PurePosixPath(path).suffix in (".json", ".yaml", ".yml") and self._spec.match_file(path)
+
+    def prepare(self, paths: Sequence[str]) -> None:
+        return None
+
+    def extract(self, path: str, content: bytes) -> FileFacts:
+        text = content.decode("utf-8")
+        document = json.loads(text) if path.endswith(".json") else load_yaml_without_aliases(text)[1]
+        if not isinstance(document, Mapping) or not ("openapi" in document or "swagger" in document):
+            return FileFacts(path)
+        entities: list[Entity] = []
+        references: list[Reference] = []
+        source = (Source(path),)
+        for route_path, operations in (document.get("paths") or {}).items():
+            if not isinstance(operations, Mapping):
+                continue
+            for method, operation in operations.items():
+                if method not in METHODS or not isinstance(operation, Mapping):
+                    continue
+                route_id = f"route:{method.upper()} {route_path}"
+                attributes = {
+                    "method": method.upper(), "path": str(route_path),
+                    "operation_id": _text(operation.get("operationId")), "summary": _text(operation.get("summary")),
+                    "tags": [str(tag) for tag in operation.get("tags", []) if isinstance(tag, str)], "document": path,
+                }  # fmt: skip
+                entities.append(Entity(route_id, EntityKind.ROUTE, attributes, source))
+                for name in sorted(set(local_refs(operation))):
+                    references.append(Reference(route_id, RelationKind.USES_SCHEMA, f"schema:{name}", source))
+        schemas = ((document.get("components") or {}).get("schemas")) or {}
+        for name, schema in schemas.items():
+            schema_id = f"schema:{name}"
+            properties = schema.get("properties", {}) if isinstance(schema, Mapping) else {}
+            attributes = {"document": path, "properties": sorted(str(key) for key in properties)[:50]}
+            entities.append(Entity(schema_id, EntityKind.SCHEMA, attributes, source))
+            for referenced in sorted(set(local_refs(schema)) - {str(name)}):
+                references.append(Reference(schema_id, RelationKind.REFERENCES, f"schema:{referenced}", source))
+        return FileFacts(path, tuple(entities), tuple(references))
+
+    def resolve(self, files: Sequence[FileFacts], known: Mapping[str, Entity]) -> Resolution:
+        relations, unresolved = [], 0
+        for file in files:
+            for reference in file.references:
+                if reference.target in known:
+                    relations.append(
+                        Relation(reference.source_id, reference.kind, reference.target, {}, reference.sources)
+                    )
+                else:
+                    unresolved += 1
+        return Resolution(relations, unresolved)