Module graph 

Persisted graph and fragment data structures.

Structs

AdmissionExpectations

What one admission call checks a candidate against.

AdmittedFacts

A candidate that passed every admission check, still carrying its original bytes unchanged – the one field publication ever writes.

AlsoIn

Represents AlsoIn.

Candidate

Represents Candidate.

Def

Represents Def.

EdgeEnd

One end of an imported edge.

EdgesByKind

Represents EdgesByKind.

FragDef

Field order is significant: id, name, namespace, kind, line, methods, then the member-fact additions in that exact order – properties, fields, methodReturns – and after those extensionMethods, appended LAST. Each is omitted entirely when empty, so a type declaring none of them serializes exactly as it did before those additions.

FragExtensionMethod

One extensionMethods entry. Serialized field order (name, thisType, arityMin, arityMax, thisArgs) is significant, and serde emits struct fields in declaration order. The two arity halves are NOT optional: they joined the schema with the v6 cache rename, so no fragment this reader can meet is missing them. arity_max is signed because -1 is the unbounded-params sentinel.

FragFact

One declared type fact: the type NAME, plus its top-level type-argument descriptors when the declaration carried any. Field order (type, args) is significant, and args is omitted when absent.

FragLambdaSlot

One untyped lambda parameter’s callee slot (see extract.rs’s LambdaSlot).

FragName

One declared member, with the line its own NAME token sits on. Field order (name, kind, line, owner) is significant, and owner is omitted when empty – which is how a markup or resource key, owned by no C# type, serializes with three fields.

FragRef

Represents FragRef.

FragRegistration

One two-type-argument DI service registration a file’s invocations record – see extract::RegistrationRecord.

Fragment

Represents Fragment.

FragmentCacheEntry

Represents FragmentCacheEntry.

Graph

Represents Graph.

GraphFile

One file that contributes a graph fragment: C# (defs, refs, member names), markup (x:Class/x:Name, .resw keys – names only) or TS/JS (imports, exported declarations, call/JSX/dispatch references).

GraphName

One row of the full name index. Field order (name, kind, file, line, owner) is significant; owner carries the declaring type’s def id for a member and is omitted for a type, an enum member, and every markup or resource key.

GraphUnit

One .csproj project as graph.json persists it.

HeuristicByTier

heuristic_edge_count split by the tier that emitted each edge, in the fixed key order every tier-keyed output uses (ext, then guess).

ImportRecord

One joined edge from the export.

ImportedEdges

The validated artifact import-edges writes and impact reads.

IncompleteUnit

One unit a structurally valid but declared-incomplete artifact could not fully process, with the compiler’s own per-unit reason.

OrderedMap

Represents OrderedMap.

Percent1

Represents Percent1.

Profile

The requested compilation profile: target, configuration and platform.

Provenance

The export’s provenance: who produced it, in which format version, and the digest an importer keys equality on. Carried once in the envelope, never per record.

Stats

Represents Stats.

Enums

AnyFragment

The two shapes a cached fragment can have. Each rel is keyed to whichever shape the file’s grammar produced; the ts: 1 tag is what tells them apart, on disk and at the resolver’s door. Untagged, and TS FIRST: a C#/markup fragment carries no ts key (so the TS arm always fails on it) and a TS fragment carries no usings (so the C# arm always fails on it) – the discrimination is total in both directions, never a first-match-wins guess.

Coverage

Whether an admitted artifact reports clean, complete coverage or a qualified partial one. Never conflated with a RefusalReason: a structurally valid, declared-incomplete artifact is admitted, not refused.

Edge

The guess tag, appended LAST on every edge kind that can carry it. heuristic: true is set only on an edge a heuristic tier emitted and never writes heuristic: false, so this side pairs skip_serializing_if with default: absent == precise, and a precise edge’s bytes are exactly what they were before the tag existed. Only the resolver’s heuristic tiers set it today (both uses-member), but the flag lives on all three targeted kinds because the query layer’s heuristic adjacency is kind-keyed, so a future tier tagging a uses-type edge needs no schema change.

FragUsing

Represents FragUsing.

HeuristicTier

Which heuristic tier emitted a guess.

PublishError

Why admit_and_publish did not produce an admitted, published artifact: either the candidate itself was refused, or admission’s own atomic write failed. The two are kept apart because only the first is a RefusalReason a caller might match on by token; the second is an ordinary filesystem failure.

RebuildOutcome

Represents RebuildOutcome.

RefusalReason

Why a candidate compiler-facts artifact was refused.

Constants

COMPILER_FACTS_ARTIFACT_SCHEMA_VERSION

This artifact’s own schema version (distinct from contractVersion, the producer’s own wire-shape version, the same split graph::imports::IMPORTED_EDGES_SCHEMA_VERSION / IMPORTED_EDGES_ARTIFACT_SCHEMA_VERSION already draws). The shipped engine now writes 2 (per-reference occurrence facts, an additive top- level occurrences key). Nothing in this admission path branches on the literal for equality – parse_header reads artifactSchemaVersion for presence/shape only – but the constant’s name promises the artifact’s schema version, so it is kept equal to what the shipped engine actually writes rather than left to name a version nothing emits.

COMPILER_FACTS_CONTRACT_VERSION

The wire-contract version this admission path was built for. Also the literal that names the artifact file (compiler-facts-v<N>.json).

COMPILER_FACTS_FORMAT

The export format compiler-facts admission accepts.

DEFAULT_OUTPUT_CAP

The default stdout byte cap a local engine run is held to before it is killed and refused as output-bounded. 256 MiB comfortably exceeds any fixture this crate ships while still bounding an adversarial or corrupted engine’s memory cost.

DEFAULT_TIMEOUT

The default wall-clock budget a local engine run is given before it is killed and refused as engine-timeout. Generous because a Roslyn/MSBuild load is the dominant cost this crate has never measured before; tighten once real cold/warm figures exist.

EXPECTED_CONTEXT_SCHEMA_VERSION

The compilation-context envelope version this admission path recognises. A candidate embedding any other version is refused without this module ever parsing the envelope’s internal shape.

EXPECTED_DEPENDENCY_FINGERPRINT

The sha256 digest of tools/scout-semantic/packages.lock.json as of the engine build this admission path expects. Recompute (shasum -a 256 tools/scout-semantic/packages.lock.json) and update this constant whenever that lock file changes.

EXPECTED_ENGINE_REVISION

The engine-protocol revision this admission path expects. Distinct from super::artifact::COMPILER_FACTS_CONTRACT_VERSION: this names the engine’s own analysis behaviour, the contract names the wire shape. Bump together with a corresponding change on the engine side. “2” means the engine this admission path expects can emit occurrence facts.

EXPECTED_PRODUCER_NAME

The producer name this admission path accepts. Keeps the contract additive and producer-tagged: a later outcome that adds or substitutes a producer format changes this constant (and the token it is compared under), never the admission path itself.

GRAPH_SCHEMA_VERSION

The version stamped into every graph.json this build writes, and the one rebuild_graph demands before it reuses an artifact it did not just produce.

IMPORTED_EDGES_FORMAT

The export format import-edges accepts.

IMPORTED_EDGES_SCHEMA_VERSION

The export schema version import-edges accepts.

IMPORTED_EDGE_KINDS

The closed set of edge kinds a record may carry. Fixed by the producer’s own contract – adding a kind here is out of scope for the importer.

SCOUT_COMPILER_ENGINE

The engine locator environment variable: the path to the engine executable compiler-facts run spawns. Read only from this module, with no default and no download – a missing engine exits non-zero with one line and leaves any already-admitted artifact untouched. Named distinctly from the unrelated, unshipped SCOUT_SEMANTIC_TOOL locator a different design note proposes for a different, still-unbuilt cache, so the two invocation paths can never be confused once both exist.

Functions

admit

Admits or refuses a candidate compiler-facts artifact.

admit_and_publish

Admits candidate_bytes and, on success, publishes it atomically as this checkout’s compiler-facts artifact – the one place both run and import converge, the concrete mechanism behind “one admission path for both producers.” On any refusal, no write occurs and whatever artifact already existed is untouched.

compiler_facts_json_path

Path to the compiler-facts artifact for root, beside graph.json. The contract version is part of the filename, so a future contract bump writes a new file rather than overwriting this one – a v2-only reader is inert to a stale v1 file by construction.

expectations_for

Builds the expectations a compiler-facts run/import admits against, for the checkout at root and the profile the caller requested.

fragment_from_extraction

Build a graph fragment from this crate’s extractor output. Extraction.purpose has no fragment counterpart – the fragment is graph-only.

graph_json_path

Path to the graph artifact (graph.json) for root.

imported_edges_json_path

Path to the imported-edges artifact for root, beside graph.json under the same graph directory.

index_is_stale

Whether the fragments index is stale for the given graph files (any mtime mismatch, or a differing file count).

locate_engine

Locates the engine executable from SCOUT_COMPILER_ENGINE, or None when the variable is unset or empty.

markup_fragment

Markup and resource files never reach the extractor: a line scan reads them instead (see markup.rs). They still get a fragment even when they declare nothing, because the fragments index is what tells map whether the graph’s input set changed, and a file missing from it reads as a permanent mismatch. usings is always empty: XAML has no using-directive equivalent, and the xmlns: prefix declarations that stand in for one are already resolved into fully-qualified ref names by the scan.

parse_imported_edges

Parses and validates a cross-repo edge export.

project_units_path

Path to the project-model staleness sidecar for root.

read_compiler_facts

Reads this checkout’s admitted compiler-facts artifact, or None when absent or unreadable – the same fail-open convention graph::read_graph/graph::read_imported_edges already follow, since this artifact is auxiliary and its absence is the ordinary “no engine ever ran here” state, not an error.

read_fragments_index

Read the fragments index (rel -> mtime). Used for the per-file reuse decision, independent of the graph rebuild.

read_graph

Reads and deserializes the repository graph, returning None on failure.

read_imported_edges

Reads the imported-edges artifact for root, or None when absent or unreadable.

rebuild_graph

fresh_fragments: fragments this run’s extractor produced for files that needed reparsing (the same set that got a fresh purpose signature in the real devscout map flow – mapcmd::map_repo assembles it). changed: from the caller’s own indexIsStale-equivalent check against csFiles, passed in rather than recomputed so the unchanged path never opens any graph file. model: the repo’s discovered .csproj projects, or None when it declares none – serialized into graph.units and mirrored into the project_units_path staleness sidecar. The caller is expected to have already folded project::sidecar_differs into changed; this function only writes the sidecar, it never decides on it.

run_engine

Runs command to completion, capturing stdout under output_cap bytes and timeout wall-clock time. command’s stdin is closed and stderr is discarded – only stdout carries the candidate artifact bytes.

write_imported_edges

Writes the imported-edges artifact for root, atomically.