@cleya/contributor-react-navigation 0.0.0-stage → 1.0.0-next.0

package/README.md

@@ -1,3 +1,137 @@
-# Temporary Holding Version
+# @cleya/contributor-react-navigation
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Indexes a React Navigation app so you can ask **which screens exist, what renders
+each one, and which screen can reach which other**.
+
+It reads the source, not the running app: no instrumentation, no navigation
+container, nothing to add to the project being indexed.
+
+## What it writes
+
+```
+(Route)-[:SERVES]->(Screen)-[:RENDERS]->(Symbol)
+(Screen)-[:NAVIGATES_TO]->(Route)
+(Screen)-[:GATED_BY]->(Predicate)
+```
+
+| Node | One per |
+| --- | --- |
+| `Route` | destination name — `"Settings"` |
+| `Screen` | *registration* of a route — the same route registered in two navigators is two screens |
+| `Predicate` | named mount condition — a guard, or a feature flag read in the component |
+| `Symbol` | code symbol rendering the screen. Written by the code indexer, joined here. |
+
+`Route` and `Screen` are separate on purpose: a route registered twice keeps two
+positions, two guards and two components, which a single node would flatten.
+
+## Use
+
+```bash
+bun add @cleya/contributor-react-navigation @cleya/region-navigation @cleya/region-trace
+```
+
+```ts
+// cleya.config.ts
+import { defineConfig, defineContributorGroup, defineProjectConfig } from "@cleya/config";
+import { tsScipContributor } from "@cleya/contributor-ts-scip";
+import { reactNavigationContributor } from "@cleya/contributor-react-navigation";
+import { regionNavigation } from "@cleya/region-navigation";
+import { regionTrace } from "@cleya/region-trace";
+
+export default defineConfig({
+	projectSettings: { db: "./.cleya/graph.lbug" },
+	projects: [
+		defineProjectConfig({
+			id: "my-app",
+			scope: { root: "/abs/path/to/app", globs: ["src/**/*.ts", "src/**/*.tsx"] },
+			contributorGroups: [
+				defineContributorGroup({
+					region: regionTrace,
+					members: [tsScipContributor()],
+				}),
+				defineContributorGroup({
+					region: regionNavigation,
+					members: [reactNavigationContributor()],
+				}),
+			],
+		}),
+	],
+});
+```
+
+```bash
+cleya index
+```
+
+## Ask it things
+
+```cypher
+-- every screen, and what renders it
+MATCH (r:Route)-[:SERVES]->(s:Screen)
+RETURN r.name AS route, s.graph AS navigator, s.component AS component
+ORDER BY route
+
+-- where can I get to from the settings screen, and by clicking what
+MATCH (:Route {name: "Settings"})-[:SERVES]->(:Screen)-[n:NAVIGATES_TO]->(target:Route)
+RETURN target.name, n.trigger, n.label, n.file, n.line
+
+-- screens nothing navigates to: dead ends, or entry points
+MATCH (r:Route)-[:SERVES]->(s:Screen)
+WHERE NOT (:Screen)-[:NAVIGATES_TO]->(r)
+RETURN r.name
+
+-- what does this feature flag gate?
+MATCH (s:Screen)-[:GATED_BY]->(p:Predicate {name: "canUseTravel"})
+RETURN s.route
+```
+
+## Is the graph complete?
+
+That is the question this plugin takes seriously, because the honest answer is
+often "no". Every run prints a coverage report:
+
+```
+[react-navigation] couverture des appels `navigate` : 1503/1711 (88 %)
+  208 sans arête : 12+ hors registre · 61 avec motif d'URL · 135 opaques
+  cible lisible mais absente du registre — inscription probablement ratée :
+    src/pages/Search.tsx:88  ROUTES.SEARCH_ADVANCED
+[react-navigation] 214 routes / 231 screens / 229 rendered / …
+```
+
+The denominator matters more than the count. A plugin that finds nothing reports
+zero edges, and zero looks exactly like "this app has no navigation" — so the
+report always says how many navigation-shaped sites it *saw*, and gives the
+address of the ones it could not use.
+
+If a run comes back `partial`, read the diagnostics before reading the graph.
+
+## A project that does not look like the defaults
+
+The core is the React Navigation API and needs no configuration. Anything the
+project invented — its own navigation helpers, its own registry keys, screens
+named by URL rather than by name — is a **dialect**, and it is configured:
+
+```ts
+reactNavigationContributor({
+	// `goToOffer(id)` navigates; group 1 is the route name
+	helperCalls: [/goTo(\w+)\s*\(/g],
+	// the app navigates by URL, and only the linking config relates the two
+	routeAliasFiles: ["navigation/linkingConfig.ts"],
+})
+```
+
+
+## Requirements
+
+- Runs **after** a code contributor such as `@cleya/contributor-ts-scip`, in the same
+  project. Screens link to the symbols it declares; without them the plugin
+  refuses to run rather than write a graph with no components.
+- `typescript` is a peer dependency: route names are resolved by the compiler,
+  using the project's own version.
+- No `tsconfig.json` is not fatal — resolution falls back to enums and constant
+  paths, and literal route names are still found.
+
+## Further
+
+- `CLAUDE.md` — architecture, invariants, module map. Lives alongside the
+  source, not in the published package.

package/dist/ast.d.ts

@@ -0,0 +1,64 @@
+/**
+ * What sets a navigation off, as a reader of the screen would name it.
+ *
+ * Both fields are `""` when nothing carries the site — a route named at module
+ * level, outside any handler or tag. Empty is a fact, not a failure: it says the
+ * position is reachable by no interaction, which is what tells a spurious edge
+ * from a real one.
+ */
+export interface SiteContext {
+    /** The trigger: JSX tag, handler, or declaration carrying the site. */
+    trigger: string;
+    /** The user-visible label, when the site sits inside a JSX tag. */
+    label: string;
+}
+/**
+ * The three syntactic questions a pattern cannot answer, over one parsed file.
+ *
+ * Every offset passed to these methods must be a position *inside* the file the
+ * index was built from; offsets from another file silently describe whatever
+ * node happens to sit there. Positions are byte offsets into the original
+ * source, not line/column, and not the blanked copy the patterns scan.
+ *
+ * The index holds its `SourceFile` for its whole lifetime — it is meant to live
+ * as long as the extraction of one file and be dropped, not cached across a run.
+ */
+export interface AstIndex {
+    /** Is the position inside a type? Then it never runs. */
+    typeOnly(offset: number): boolean;
+    /** What carries this position, and under which label. */
+    context(offset: number, labelProps: string[]): SiteContext;
+    /**
+     * Identity of the literal carrying this position — its node's start.
+     *
+     * Two patterns often see the same string from two angles:
+     *
+     *   navigateTo={{ screen: "SignupMethods" }}
+     *   ^^^^^^^^^^ declarative-link pattern   ^^^^^^ config-key pattern
+     *
+     * When the expression spans two lines, deduplicating by line number takes
+     * them for two navigations. The node is the same either way: it is the only
+     * identity that does not depend on how the code is laid out.
+     */
+    literalAt(offset: number): number;
+}
+/**
+ * Parse one file and answer positional questions about it.
+ *
+ * `path` is used only to pick the parser dialect — `.tsx` enables JSX, anything
+ * else does not — so a mislabelled path silently reads `<Tag/>` as a comparison.
+ * Parsing never throws: TypeScript recovers from syntax errors and yields a
+ * partial tree, so a broken file degrades to wrong answers rather than a crash.
+ *
+ * @example
+ * const src = `export type Props = { navigateTo: { screen: "VenueMap" } };`;
+ * astIndex("a.ts", src).typeOnly(src.indexOf(`"VenueMap"`)); // true — an annotation
+ *
+ * const run = `const go = () => ({ screen: "VenueMap" });`;
+ * astIndex("a.ts", run).typeOnly(run.indexOf(`"VenueMap"`)); // false — a value
+ *
+ * const jsx = `const C = () => <Touchable.Link wording="Voir" onPress={() => navigate("Home")} />;`;
+ * astIndex("a.tsx", jsx).context(jsx.indexOf(`"Home"`), ["wording"]);
+ * // { trigger: "Touchable.Link", label: "Voir" }
+ */
+export declare const astIndex: (path: string, src: string) => AstIndex;

package/dist/blank.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Blank out comments and string bodies **while preserving offsets**, so that
+ * walking braces is safe.
+ *
+ * The returned copy has exactly the length of the source: an index found on it
+ * designates the same character in the original. That is what lets us search
+ * for structure on the blanked text and read the value from the source.
+ *
+ * @example
+ * stripNoise('const a = "{";'); // 'const a =    ;' — the brace no longer counts
+ * stripNoise("x // y");         // 'x     ' — the comment becomes blanks
+ * stripNoise("x // y").length;  // 6 — the length never changes
+ *
+ * A block comment is blanked the same way, delimiters included.
+ */
+export declare const stripNoise: (src: string) => string;
+/**
+ * Line number of an offset, **zero-based**.
+ *
+ * @example
+ * lineAt("a\nb\nc", 4); // 2 — not 3: the first line is line 0
+ */
+export declare const lineAt: (src: string, index: number) => number;
+/**
+ * Brace depth at this offset. Read it on the blanked copy: a brace inside a
+ * string would throw the count off.
+ *
+ * @example
+ * depthAt("a{b{c}d}e", 4); // 2
+ * depthAt("a{b{c}d}e", 8); // 0 — everything is closed again
+ */
+export declare const depthAt: (blanked: string, index: number) => number;
+/**
+ * An attribute's value, and *where it is*.
+ *
+ * `at` is the index of the expression within the attribute text: the
+ * type-based resolver designates a node by its range, not by its text — two
+ * attributes may carry the same expression and not name the same thing.
+ */
+export interface Attr {
+    literal: string | null;
+    expr: string | null;
+    at: number | null;
+}
+/**
+ * Value of a **top-level** JSX attribute: `name="X"` → literal `X`,
+ * `name={Expr}` → expression `Expr`.
+ *
+ * Depth is everything:
+ *
+ *   <Tab.Screen name="Search" options={{ tabBarIcon: () => <Icon name="images" /> }} />
+ *
+ * holds two `name=`. A regex search over the tag returns the last one — the
+ * icon's name — and registers one phantom route per tab. So only attributes at
+ * depth zero within the tag are accepted.
+ *
+ * @example
+ * const attrs = ` name="Search" options={{ tabBarIcon: () => <Icon name="images" /> }}`;
+ * topLevelAttr(attrs, stripNoise(attrs), "name").literal; // "Search", not "images"
+ * topLevelAttr(" name={SCREENS.HOME}", …, "name");        // { literal: null, expr: "SCREENS.HOME", at: 7 }
+ * topLevelAttr(" component={X}", …, "name");              // { literal: null, expr: null, at: null }
+ */
+export declare const topLevelAttr: (attrsSrc: string, attrsBlanked: string, attr: string) => Attr;
+/**
+ * Bounds of `const <symbol> = …`, anchored on the `=`.
+ *
+ * Anchoring on `=` is not a detail: a type annotation such as
+ * `const rootScreens: RouteConfig[] = [...]` would otherwise capture its own
+ * brackets.
+ *
+ * @example
+ * spanOf(stripNoise("const a = { x: 1 };"), "a"); // [10, 18]
+ * spanOf(stripNoise("const a = 1;"), "a");        // null — neither object nor array
+ * spanOf(stripNoise("const b = {};"), "a");       // null — no such symbol
+ */
+export declare const spanOf: (blanked: string, symbol: string) => [number, number] | null;
+/** One object entry found at depth 1, with its four bounds. */
+export interface ObjectKey {
+    key: string;
+    at: number;
+    keyAt: number;
+    valueAt: number;
+    valueEnd: number;
+}
+/**
+ * An object's direct keys, literal and computed alike.
+ *
+ * `at` locates the entry — that is the line we report; `keyAt` locates the
+ * key *expression*, which is not the same thing once it is computed:
+ * `[SCREENS.X]` starts one character further along, and that is the bound the
+ * checker expects.
+ *
+ * @example
+ * const src = stripNoise("const r = { Home: A, [SCREENS.X]: B };");
+ * keysAtDepth1(src, src.indexOf("{")).map((k) => k.key); // ["Home", "SCREENS.X"]
+ */
+export declare const keysAtDepth1: (blanked: string, objStart: number) => ObjectKey[];

package/dist/census.d.ts

@@ -0,0 +1,43 @@
+/**
+ * What the contributor saw and could not use.
+ *
+ * An axis that never matches returns zero, and zero looks like "this project
+ * has none". That is the costliest mistake for whoever is discovering a
+ * codebase: the graph looks complete when it is amputated. The census gives the
+ * **denominator** — the sites shaped like a navigation that produced nothing —
+ * along with the means to go and look: file, line, expression.
+ */
+export interface Census {
+    jsxTags: number;
+    jsxMissed: string[];
+    callsSeen: number;
+    callsResolved: number;
+    /** Target readable but unknown to the registry: a registration probably missed. */
+    unknown: string[];
+    /** No literal, but the type carries a URL pattern: recoverable by pattern join. */
+    patterned: string[];
+    patternedCount: number;
+    /** Opaque: irreducible, but it has to be counted. */
+    dynamic: string[];
+}
+/**
+ * An empty census, every counter at zero.
+ *
+ * @example
+ * const census = newCensus();
+ * census.callsSeen;      // 0
+ * census.jsxMissed;      // [] — samples accumulate through `sample`
+ */
+export declare const newCensus: () => Census;
+/**
+ * Record an example, up to a fixed cap.
+ *
+ * Silently ignores anything past the cap — the caller keeps the real magnitude
+ * in its own counter, so a sample list is an address book, not a measure.
+ *
+ * @example
+ * const into: string[] = [];
+ * for (let i = 0; i < 10; i++) sample(into, `line ${i}`);
+ * into.length; // 5 — capped, and the first five are the ones kept
+ */
+export declare const sample: (into: string[], line: string) => void;

package/dist/collect.d.ts

@@ -0,0 +1,113 @@
+import type { SourceModel } from "@cleya/config";
+import type { Domain } from "@cleya/domain";
+import { type Census } from "./census";
+import { type Counters, type Dialect } from "./dialect";
+import type { GraphReader } from "./graph-reader";
+import { type Registration } from "./registrations";
+/** What `collect` needs. No connection, no Cypher. */
+export interface CollectDeps {
+    source: SourceModel;
+    projectRoot: string;
+    graph: GraphReader;
+    /**
+     * First segment of every id built, per the recipes on
+     * `Domain.Region.Navigation`, so the model is ready to load as-is.
+     */
+    workspace: string;
+}
+/** One screen registration, resolved and ready to write. */
+export interface ScreenRecord {
+    /** `"$workspace|$graph|$route"` */
+    id: string;
+    route: string;
+    graph: string;
+    file: string;
+    line: number;
+    shape: Registration["shape"];
+    guard: string;
+    hasOptions: boolean;
+    /** Component symbol id, or `""` when none could be resolved. */
+    component: string;
+}
+/** One navigation edge, already attributed, deduplicated and weighted. */
+export interface NavEdge {
+    screen: string;
+    route: string;
+    kind: Domain.Region.Navigation.Kind;
+    via: Domain.Region.Navigation.Via;
+    file: string;
+    line: number;
+    trigger: string;
+    label: string;
+    own: boolean;
+    owners: number;
+}
+/**
+ * Everything the extraction learned but could not turn into an edge, plus the
+ * counts a run is judged by. Feeds the log and the diagnostics, never the graph.
+ */
+export interface CollectReport {
+    counters: Counters;
+    census: Census;
+    duplicates: string[];
+    unlinked: string[];
+    mounts: string[];
+    ambiguous: string[];
+    multi: string[];
+    orphanCalls: number;
+    borrowed: number;
+    factoryFiles: number;
+    callSites: number;
+    rendered: number;
+    gates: number;
+    typeIndex: {
+        sourceFiles: number;
+        buildMs: number;
+    } | null;
+    adjacencySize: number;
+}
+/** The whole result of an extraction, before anything is written. */
+export interface NavigationModel {
+    /** `id` is `"$workspace|$name"`. */
+    routes: Array<{
+        id: string;
+        name: string;
+        registrations: number;
+    }>;
+    screens: ScreenRecord[];
+    renders: Array<{
+        screen: string;
+        symbol: string;
+    }>;
+    /** `id` is `"$workspace|$kind|$name"`. */
+    predicates: Array<{
+        id: string;
+        name: string;
+        kind: string;
+    }>;
+    gates: Array<{
+        screen: string;
+        predicate: string;
+    }>;
+    edges: NavEdge[];
+    report: CollectReport;
+}
+/**
+ * Read the project and work out its navigation graph.
+ *
+ * Four passes: read every in-scope file, find the registrations, find the call
+ * sites, then attribute each call site to the screens whose component closure
+ * reaches it. Nothing is written — the result is a value, which is what makes
+ * every decision here assertable without a database.
+ *
+ * Degrades rather than fails when the project offers no usable TypeScript
+ * program: `createTypeIndex` returns `null` and resolution falls back to the
+ * name tables, so literal route names are still found.
+ *
+ * @example
+ * const model = await collect({ source, projectRoot, graph, workspace: "app" }, dialect);
+ * model.routes.map((r) => r.name);  // ["Home", "Away"]
+ * model.edges.length;               // navigations attributed to a screen
+ * model.report.census.callsSeen;    // denominator: navigate() calls, edge or not
+ */
+export declare const collect: (deps: CollectDeps, d: Dialect) => Promise<NavigationModel>;

package/dist/dialect.d.ts

@@ -0,0 +1,58 @@
+import type { ReactNavigationDialect } from "./react-navigation.types";
+/**
+ * Defaults.
+ *
+ * Empty where no universal convention exists — `helperCalls` and `predicates`.
+ * A wrong default is worse than a missing one: it manufactures a plausible
+ * graph, whereas an empty axis shows up in the match counts. The other axes
+ * have a default because React Navigation itself names them.
+ */
+declare const DEFAULTS: {
+    helperCalls: RegExp[];
+    configKeys: string[];
+    labelProps: string[];
+    registryEntry: {
+        name: string;
+        component: string;
+    };
+    guardKey: string;
+    predicates: Array<{
+        kind: string;
+        pattern: RegExp;
+    }>;
+    exclude: string[];
+    routeAliasFiles: string[];
+    closureDepth: number;
+    graphLabel: (path: string) => string;
+};
+/** A dialect with every axis resolved, ready for the extraction to read. */
+export type Dialect = typeof DEFAULTS & {
+    /** Axes set explicitly: never matching one is an error, not a choice. */
+    configured: Set<string>;
+};
+/**
+ * Resolve a partial dialect into a complete one, validating its patterns.
+ *
+ * Throws when a supplied pattern is not global or captures nothing — at
+ * configuration load time, not midway through an indexing run.
+ *
+ * @example
+ * resolveDialect({}).configured.size;               // 0 — everything defaulted
+ * resolveDialect({ closureDepth: 3 }).closureDepth; // 3
+ * resolveDialect({ helperCalls: [/nav/g] });        // throws — no capture group
+ */
+export declare const resolveDialect: (dialect?: ReactNavigationDialect) => Dialect;
+/** Match count per axis: a pattern that never fires has to be visible. */
+export type Counters = Record<string, number>;
+/**
+ * Increment an axis counter.
+ *
+ * @example
+ * const counters: Counters = {};
+ * bump(counters, "types");    // { types: 1 }
+ * bump(counters, "types", 5); // { types: 6 } — an absent axis starts at 0
+ */
+export declare const bump: (counters: Counters, axis: string, n?: number) => void;
+/** Recognises a file mounting a navigator: `createXNavigator(` or `<`. */
+export declare const FACTORY: RegExp;
+export {};

package/dist/graph-reader.d.ts

@@ -0,0 +1,55 @@
+import type { Domain } from "@cleya/domain";
+/** A symbol reachable from a navigator file, as a component candidate. */
+export type SymbolRow = {
+    file: string;
+    name: string;
+    symbolId: string;
+};
+/** A top-level declaration of a page file, with its kind. */
+export type DeclaredRow = SymbolRow & {
+    type: string;
+};
+/**
+ * Everything the extraction reads from the code graph, and nothing more.
+ *
+ * Four reads, all scoped to one workspace. They are a port rather than a
+ * client because `collect` is where the contributor's judgement lives, and
+ * judgement that issues Cypher can only be tested against a database. A fake
+ * here is four array literals.
+ *
+ * This is not a general graph API: each method exists because one specific step
+ * of the extraction needs exactly that shape.
+ */
+export interface GraphReader {
+    /**
+     * `USES` adjacency for the workspace, source symbol id -> target symbol ids.
+     *
+     * Loaded whole rather than walked lazily: the closure visits it repeatedly
+     * and per-query round trips dominated the run.
+     */
+    adjacency(): Promise<Map<string, string[]>>;
+    /**
+     * Symbols declared by these files, plus the symbols those declarations use.
+     *
+     * Both halves matter: a navigator may declare its screens itself, or import
+     * them. Matching by name over this set is what avoids re-implementing module
+     * resolution.
+     */
+    componentCandidates(files: string[]): Promise<SymbolRow[]>;
+    /** Every indexed file path of the workspace, for module-specifier resolution. */
+    filePaths(): Promise<string[]>;
+    /** Top-level declarations of these files, to find a page's main symbol. */
+    declaredSymbols(files: string[]): Promise<DeclaredRow[]>;
+}
+/**
+ * The production reader: one Cypher query per method over the trace region,
+ * scoped to the files `workspace` indexed. A symbol used across workspaces
+ * (an `external|…` one) still appears as a `USES` target.
+ *
+ * @example
+ * const reader = cypherReader(ctx.db, ctx.workspace);
+ * (await reader.adjacency()).size;                       // symbols with at least one USES edge
+ * await reader.componentCandidates(["Navigator.tsx"]); // [{ file, name, symbolId }, …]
+ * await reader.componentCandidates([]);                // [] — no query issued
+ */
+export declare const cypherReader: (db: Domain.Db.ReadClient, workspace: string) => GraphReader;

package/dist/nav-calls.d.ts

@@ -0,0 +1,93 @@
+import type { Domain } from "@cleya/domain";
+import { type Census } from "./census";
+import { type Counters, type Dialect } from "./dialect";
+import { type Classify, type Resolve } from "./route-names";
+/** One navigation call site: who navigates, to which route, under which label. */
+export interface CallSite {
+    route: string;
+    file: string;
+    line: number;
+    kind: Domain.Region.Navigation.Kind;
+    via: Domain.Region.Navigation.Via;
+    /** Trigger id: link component, config symbol, or enclosing function. */
+    trigger: string;
+    /** User-visible label, when the trigger carries one. */
+    label: string;
+}
+/**
+ * Call patterns: the core first, then the dialect.
+ *
+ * The core is the React Navigation API, identical everywhere. The last two axes
+ * — config keys and project helpers — depend entirely on the project's
+ * conventions: they carry 94 % of the edges on one repository and zero
+ * elsewhere without configuration.
+ *
+ * @example
+ * callPatterns(resolveDialect({})).length;                  // core patterns only
+ * callPatterns(resolveDialect({ helperCalls: [/go\((\w+)\)/g] }));
+ * // …plus one entry whose axis is "helperCalls", so a silent helper is visible
+ */
+export declare const callPatterns: (d: Dialect) => Array<{
+    re: RegExp;
+    kind: Domain.Region.Navigation.Kind;
+    via: Domain.Region.Navigation.Via;
+    axis: string;
+    ref?: true;
+}>;
+/**
+ * Past this many variants, a union of patterns no longer discriminates.
+ *
+ * A conditional navigation aims at two or three targets; a union carrying
+ * dozens is the project's sum type, arrived at through an `as Route`.
+ */
+export declare const PATTERN_LIMIT = 8;
+/**
+ * Targets named somewhere other than right after the call.
+ *
+ * The `callPatterns` patterns require the literal glued to `navigate(`. Two
+ * forms escape them, and both are real navigations:
+ *
+ *   reset({ routes: [{ name: "Bookings" }] })   the stack rebuilt in one go
+ *   navigate(cond ? "A" : "B")                  the target chosen at runtime
+ *
+ * The argument list is delimited by balancing parens, then two precise patterns
+ * are applied inside it. Precise, and not "every string in the region": a
+ * region overruns as soon as a paren sits inside a string, and the sweep then
+ * brings back neighbouring `case "Profile":`. The graph filters unknown names,
+ * but it cannot tell a real route name quoted in the wrong place from a target.
+ *
+ * @example
+ * spreadTargets(src, blanked, new Set(["Home", "Away"]));
+ * // navigate(x ? "Home" : "Away") → two entries, one per branch
+ */
+export declare const spreadTargets: (src: string, blanked: string, routeNames: Set<string>) => Array<{
+    route: string;
+    index: number;
+    kind: Domain.Region.Navigation.Kind;
+}>;
+/**
+ * Every navigation call site in one file, plus what the census learned from it.
+ *
+ * Mutates `counters` and `census` rather than returning them: both aggregate
+ * across the whole run, and threading them back through every file would make
+ * the caller reassemble what it already owns.
+ *
+ * @example
+ * const sites = callSitesIn(src, stripNoise(src), "a.tsx", routeNames, dialect,
+ *                           resolve, counters, census, classify);
+ * sites.map((s) => s.route);   // ["Home"] — `navigate("Home")`
+ * // A literal inside a type annotation yields nothing: it never runs.
+ * // A ternary yields two sites, one per branch.
+ */
+export declare const callSitesIn: (src: string, blanked: string, path: string, routeNames: Set<string>, d: Dialect, resolve: Resolve, counters: Counters, census: Census, classify: Classify) => CallSite[];
+/**
+ * Symbol ids are `{workspace}|{scope}|{path}|{name}` — the file is segment 2.
+ *
+ * Returns `""` rather than throwing on a malformed id: the ids come from the
+ * code graph, and one bad row must not abort a run.
+ *
+ * @example
+ * fileOfSymbolId("ws|internal|src/Home.tsx|Home"); // "src/Home.tsx"
+ * fileOfSymbolId("not-an-id");                     // "" — no segment 2
+ */
+export declare const fileOfSymbolId: (id: string) => string;