|
|
|
@@ -0,0 +1,723 @@
|
|
|
|
|
/**
|
|
|
|
|
* `GET /api/steps` — what happens from here: a screen, a handler or any
|
|
|
|
|
* symbol as the ANCHOR, and everything it sets in motion drawn as typed steps.
|
|
|
|
|
*
|
|
|
|
|
* The Screens view (`screens.ts`) is already a picture of steps with one step
|
|
|
|
|
* type: it folds `HomeScreen → ItemsGrid → ItemCard → openObjectDetail` into
|
|
|
|
|
* one arrow labelled with its condition, because the reader wants the
|
|
|
|
|
* transition, not the plumbing. This endpoint keeps that fold and widens the
|
|
|
|
|
* set of things worth a box. Walking FORWARD from the anchor over calls,
|
|
|
|
|
* renders, handler bindings and navigations, a node is a step when it is:
|
|
|
|
|
*
|
|
|
|
|
* - a **screen** (a route reached over a `navigates` edge),
|
|
|
|
|
* - a **trigger** — a function wired as a value (`onPress={handleX}`,
|
|
|
|
|
* `addListener('x', handleX)`), the user's or the platform's way in,
|
|
|
|
|
* - a **bridge** call — the language changes under the call, JS → native
|
|
|
|
|
* (the React Native bridge resolver's edges, or any family crossing),
|
|
|
|
|
* - a native **event** landing back in JS (`sendEvent(withName:)` → the
|
|
|
|
|
* listener, via the RN event channel),
|
|
|
|
|
* - a **store** action — a function in a store file, the state it writes,
|
|
|
|
|
* - an **effect** — a call that leaves the index into the network, storage,
|
|
|
|
|
* the device or telemetry, drawn as its own box beside the function that
|
|
|
|
|
* makes it.
|
|
|
|
|
*
|
|
|
|
|
* Everything else — hooks, helpers, services, the components between a
|
|
|
|
|
* screen and its handlers — is `via`: listed on the link, never a box. The
|
|
|
|
|
* branch conditions along the folded chain join into the link's `when`, read
|
|
|
|
|
* from the source at request time exactly as the Screens view reads them.
|
|
|
|
|
*
|
|
|
|
|
* The picture is finite because it is ANCHORED and CAPPED, not because the
|
|
|
|
|
* graph is small: a bounded depth in steps, a bounded fan-out per node, a
|
|
|
|
|
* bounded number of nodes folded per step, and hubs and shared chrome (a top
|
|
|
|
|
* bar rendered on ten screens) are dead ends rather than paths. Every cap
|
|
|
|
|
* that fired is reported on the step it fired at, so a short picture never
|
|
|
|
|
* reads as "nothing else happens here".
|
|
|
|
|
*
|
|
|
|
|
* Read from the graph at request time, never cached: the `when` labels and
|
|
|
|
|
* the effect sites are read from the source as it stands.
|
|
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
import type CodeGraph from '../../index';
|
|
|
|
|
import type { Edge, Language, Node, UnresolvedReference } from '../../types';
|
|
|
|
|
import { badRequest, intParam, notFound } from './respond';
|
|
|
|
|
import { createWhenReader } from './when';
|
|
|
|
|
import { HUB_THRESHOLD, UNCERTAIN_BELOW, toNodeRef, type WireNodeRef } from './wire';
|
|
|
|
|
|
|
|
|
|
// =============================================================================
|
|
|
|
|
// Wire shapes
|
|
|
|
|
// =============================================================================
|
|
|
|
|
|
|
|
|
|
export type WireStepKind = 'anchor' | 'screen' | 'trigger' | 'bridge' | 'event' | 'store' | 'effect';
|
|
|
|
|
|
|
|
|
|
export type WireStepLinkKind = 'calls' | 'navigates' | 'handler' | 'bridge' | 'event' | 'store' | 'effect';
|
|
|
|
|
|
|
|
|
|
export interface WireStepSite {
|
|
|
|
|
file: string;
|
|
|
|
|
line: number;
|
|
|
|
|
/** `push /capture`, `calls`, `client.post` — what the site does, in a word or two. */
|
|
|
|
|
text: string;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
export interface WireStep {
|
|
|
|
|
/** The node's id, or `effect:<function id>:<api>` for a call leaving the index. */
|
|
|
|
|
id: string;
|
|
|
|
|
kind: WireStepKind;
|
|
|
|
|
/** The step the picture starts from. A screen anchor keeps `kind: 'screen'`. */
|
|
|
|
|
anchor: boolean;
|
|
|
|
|
/** Null only for an effect, which is a call site rather than a symbol. */
|
|
|
|
|
node: WireNodeRef | null;
|
|
|
|
|
/** `/capture/review`, `handleApproveAllImages`, `client.post`. */
|
|
|
|
|
label: string;
|
|
|
|
|
/** The component for a screen, the file for a symbol, the category and caller for an effect. */
|
|
|
|
|
sub: string;
|
|
|
|
|
/** Steps from the anchor: the row. */
|
|
|
|
|
depth: number;
|
|
|
|
|
/**
|
|
|
|
|
* Why the walk did not go on from this step, when it did not: a cap it hit
|
|
|
|
|
* (`depth`, `fan-out`, `folded`, `steps`), or `screen` — another screen is
|
|
|
|
|
* a chapter of its own, drawn but not entered unless `through` asks.
|
|
|
|
|
*/
|
|
|
|
|
cut: 'depth' | 'fan-out' | 'folded' | 'steps' | 'screen' | 'component' | null;
|
|
|
|
|
/** The event name a native event step arrived on (`onZipComplete`) — the first, when several land here. */
|
|
|
|
|
event?: string;
|
|
|
|
|
/** Every event that lands on this step, in the order the walk met them. */
|
|
|
|
|
events?: string[];
|
|
|
|
|
/** For a screen: its path and the component that renders it. */
|
|
|
|
|
screen?: { path: string; component: WireNodeRef | null };
|
|
|
|
|
/**
|
|
|
|
|
* For an effect: the calls one function makes into one category — `api` is
|
|
|
|
|
* the first, `apis` all of them — and the function that makes them.
|
|
|
|
|
*/
|
|
|
|
|
effect?: { api: string; apis: string[]; category: string; by: WireNodeRef; line: number };
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
export interface WireStepLink {
|
|
|
|
|
id: string;
|
|
|
|
|
from: string;
|
|
|
|
|
to: string;
|
|
|
|
|
kind: WireStepLinkKind;
|
|
|
|
|
/** The symbols folded between the two steps, in order. */
|
|
|
|
|
via: WireNodeRef[];
|
|
|
|
|
/** Conditions along the whole chain, joined; '' when unconditional. */
|
|
|
|
|
when: string;
|
|
|
|
|
/** How the last hop was established when it was not a plain call — `via rn-event-channel · registered at file:line`. */
|
|
|
|
|
label: string;
|
|
|
|
|
synthesized: boolean;
|
|
|
|
|
uncertain: boolean;
|
|
|
|
|
sites: WireStepSite[];
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
export interface WireStepsPayload {
|
|
|
|
|
anchor: WireNodeRef;
|
|
|
|
|
/** Other symbols that share the anchor's name, when it was given by name. */
|
|
|
|
|
ambiguous: WireNodeRef[];
|
|
|
|
|
steps: WireStep[];
|
|
|
|
|
links: WireStepLink[];
|
|
|
|
|
depth: number;
|
|
|
|
|
limit: number;
|
|
|
|
|
/** Screens reached from the anchor were entered rather than drawn as boundaries. */
|
|
|
|
|
through: boolean;
|
|
|
|
|
truncated: {
|
|
|
|
|
/** Steps not added because the picture reached `limit`. */
|
|
|
|
|
steps: number;
|
|
|
|
|
/** Folded walks that stopped at a hub (fan-in ≥ the hub threshold). */
|
|
|
|
|
hubs: number;
|
|
|
|
|
/** Folded walks that stopped at shared chrome (a component rendered by several screens). */
|
|
|
|
|
chrome: number;
|
|
|
|
|
};
|
|
|
|
|
index: { lastIndexedAt: number | null; edges: number; files: number };
|
|
|
|
|
timing: { elapsedMs: number };
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// =============================================================================
|
|
|
|
|
// Caps
|
|
|
|
|
// =============================================================================
|
|
|
|
|
|
|
|
|
|
export const DEFAULT_DEPTH = 8;
|
|
|
|
|
export const MAX_DEPTH = 14;
|
|
|
|
|
export const DEFAULT_LIMIT = 120;
|
|
|
|
|
export const MAX_LIMIT = 400;
|
|
|
|
|
/** Nodes folded while exploring from ONE step before the walk stops. */
|
|
|
|
|
const MAX_FOLDED_PER_STEP = 300;
|
|
|
|
|
/** Hops of folded plumbing between two steps. */
|
|
|
|
|
const MAX_FOLD_DEPTH = 7;
|
|
|
|
|
/** Outgoing edges followed from one node; past this the node is a god function and the rest is announced. */
|
|
|
|
|
const MAX_FANOUT = 80;
|
|
|
|
|
/** Unresolved-reference scans (for effects) per request. */
|
|
|
|
|
const MAX_EFFECT_SCANS = 800;
|
|
|
|
|
/** Call sites labelled with conditions per request. */
|
|
|
|
|
const MAX_WHEN_SITES = 800;
|
|
|
|
|
/**
|
|
|
|
|
* A component rendered by this many distinct parents is chrome (a top bar, a
|
|
|
|
|
* button), not a screen's own behaviour. Higher than the Screens view's 3: that
|
|
|
|
|
* one attributes navigations, where three screens sharing a link is already
|
|
|
|
|
* chrome; this one decides what to WALK INTO, and a capture component shared
|
|
|
|
|
* by three capture flows is the screen's whole body.
|
|
|
|
|
*/
|
|
|
|
|
const SHARED_CHROME_MIN = 5;
|
|
|
|
|
|
|
|
|
|
/** Edges walked forward. `contains` only function → function (a hook's handlers); `references` only function-as-value. */
|
|
|
|
|
const WALK_KINDS: Edge['kind'][] = ['calls', 'instantiates', 'navigates', 'references', 'contains'];
|
|
|
|
|
|
|
|
|
|
// =============================================================================
|
|
|
|
|
// Classification
|
|
|
|
|
// =============================================================================
|
|
|
|
|
|
|
|
|
|
const JS_FAMILY: ReadonlySet<Language> = new Set<Language>(['javascript', 'typescript', 'tsx', 'jsx']);
|
|
|
|
|
const NATIVE_FAMILY: ReadonlySet<Language> = new Set<Language>(['swift', 'objc', 'java', 'kotlin']);
|
|
|
|
|
|
|
|
|
|
/** JS → native is a bridge call; native → JS is an event. Anything else is one family. */
|
|
|
|
|
export function crossing(from: Language, to: Language): 'bridge' | 'event' | null {
|
|
|
|
|
if (JS_FAMILY.has(from) && NATIVE_FAMILY.has(to)) return 'bridge';
|
|
|
|
|
if (NATIVE_FAMILY.has(from) && JS_FAMILY.has(to)) return 'event';
|
|
|
|
|
return null;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* A file that holds state: a store, a slice, a reducer. The graph has no
|
|
|
|
|
* "store" kind — a Zustand action is an ordinary function node — so the file
|
|
|
|
|
* is the evidence, and the legend says so.
|
|
|
|
|
*/
|
|
|
|
|
export const STORE_FILE = /(?:^|\/)(?:stores?|storage|state|slices?|reducers?)\/|\.(?:store|storage|slice|reducer)\.[cm]?[jt]sx?$/i;
|
|
|
|
|
|
|
|
|
|
export function isStoreFile(file: string): boolean {
|
|
|
|
|
return STORE_FILE.test(file.replace(/\\/g, '/'));
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Calls that leave the index and change something outside the process. A
|
|
|
|
|
* curated table, deliberately: "any call into a package" is every `Date` and
|
|
|
|
|
* `Math.max`, and a box for each would bury the ones that matter. Matched on
|
|
|
|
|
* the reference text as written at the call.
|
|
|
|
|
*/
|
|
|
|
|
export const EFFECTS: ReadonlyArray<{ category: string; test: RegExp }> = [
|
|
|
|
|
{
|
|
|
|
|
category: 'network',
|
|
|
|
|
test: /^(?:fetch|axios|ky|got|superagent|XMLHttpRequest|WebSocket)$|^(?:axios|api|client|http|https|httpClient|apiClient|instance|request|agent|graphql|apollo|supabase)\.(?:get|post|put|patch|delete|head|request|query|mutate|rpc|invoke)$|^URLSession(?:\.|$)|^(?:Alamofire|AF)\.|\.(?:dataTask|uploadTask|downloadTask)$/,
|
|
|
|
|
},
|
|
|
|
|
{
|
|
|
|
|
category: 'storage',
|
|
|
|
|
test: /^(?:AsyncStorage|SecureStore|MMKV|localStorage|sessionStorage|indexedDB|UserDefaults|Keychain|KeychainAccess|FileSystem|RNFS|FileManager|fs|fsp)\b/,
|
|
|
|
|
},
|
|
|
|
|
{
|
|
|
|
|
category: 'device',
|
|
|
|
|
test: /^(?:Linking|Share|Clipboard|Notifications|Camera|ImagePicker|MediaLibrary|Haptics|Alert|Vibration|Location|Geolocation|Permissions|UIApplication|AVCaptureSession|AVAudioSession|CLLocationManager|UNUserNotificationCenter)\b/,
|
|
|
|
|
},
|
|
|
|
|
{
|
|
|
|
|
category: 'telemetry',
|
|
|
|
|
test: /^(?:DdRum|DdLogs|DdTrace|DdSdkReactNative|CustomerIO|Sentry|Bugsnag|analytics|Analytics|crashlytics|Crashlytics|mixpanel|Mixpanel|amplitude|Amplitude|posthog|PostHog|LDClient|ldClient)\b/,
|
|
|
|
|
},
|
|
|
|
|
];
|
|
|
|
|
|
|
|
|
|
export function effectCategory(referenceName: string): string | null {
|
|
|
|
|
for (const e of EFFECTS) if (e.test.test(referenceName)) return e.category;
|
|
|
|
|
return null;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// =============================================================================
|
|
|
|
|
// The endpoint
|
|
|
|
|
// =============================================================================
|
|
|
|
|
|
|
|
|
|
interface Fold {
|
|
|
|
|
node: Node;
|
|
|
|
|
/** [first folded node, …, this node]; empty for the step's own root. */
|
|
|
|
|
chain: Node[];
|
|
|
|
|
whens: string[];
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
interface StepRecord extends WireStep {
|
|
|
|
|
/** Where exploration from this step begins: a screen's component, otherwise the node itself. */
|
|
|
|
|
root: Node | null;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
export async function buildSteps(cg: CodeGraph, projectRoot: string, query: URLSearchParams): Promise<WireStepsPayload> {
|
|
|
|
|
const started = Date.now();
|
|
|
|
|
const depthCap = intParam(query, 'depth', { min: 1, max: MAX_DEPTH, default: DEFAULT_DEPTH });
|
|
|
|
|
const limit = intParam(query, 'limit', { min: 20, max: MAX_LIMIT, default: DEFAULT_LIMIT });
|
|
|
|
|
const through = query.get('through') === '1';
|
|
|
|
|
const stats = cg.getStats();
|
|
|
|
|
const index = { lastIndexedAt: cg.getLastIndexedAt() ?? null, edges: stats.edgeCount, files: stats.fileCount };
|
|
|
|
|
|
|
|
|
|
const { anchor, ambiguous } = resolveAnchor(cg, query);
|
|
|
|
|
|
|
|
|
|
// Route → the component it renders, and the routes by id.
|
|
|
|
|
const routes = cg.getNodesByKind('route');
|
|
|
|
|
const renders = routes.length === 0 ? [] : cg.getOutgoingEdgesFrom(routes.map((r) => r.id), ['calls', 'instantiates']);
|
|
|
|
|
const componentOf = new Map<string, Node>();
|
|
|
|
|
if (renders.length > 0) {
|
|
|
|
|
const components = cg.getNodesByIds(renders.map((e) => e.target));
|
|
|
|
|
for (const edge of renders) {
|
|
|
|
|
const c = components.get(edge.target);
|
|
|
|
|
if (c && !componentOf.has(edge.source)) componentOf.set(edge.source, c);
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
const readWhen = createWhenReader(cg, projectRoot, MAX_WHEN_SITES);
|
|
|
|
|
const whenAt = (caller: Node, site: { line?: number; column?: number }) => readWhen(caller, site);
|
|
|
|
|
|
|
|
|
|
const steps = new Map<string, StepRecord>();
|
|
|
|
|
const links = new Map<string, WireStepLink>();
|
|
|
|
|
const truncated = { steps: 0, hubs: 0, chrome: 0 };
|
|
|
|
|
let effectScans = 0;
|
|
|
|
|
const fanIn = new Map<string, number>();
|
|
|
|
|
const chromeParents = new Map<string, number>();
|
|
|
|
|
const fileScopeRefs = new Map<string, Edge[]>();
|
|
|
|
|
|
|
|
|
|
const stepFor = (node: Node, kind: WireStepKind, depth: number, extra: Partial<WireStep> = {}): StepRecord | null => {
|
|
|
|
|
const existing = steps.get(node.id);
|
|
|
|
|
if (existing) {
|
|
|
|
|
// A listener the screen registers is a handler when first met, and the
|
|
|
|
|
// native event's landing when the walk arrives from the other side —
|
|
|
|
|
// the second is the fuller fact, and it names the event.
|
|
|
|
|
if (existing.kind === 'trigger' && kind === 'event') {
|
|
|
|
|
existing.kind = 'event';
|
|
|
|
|
if (extra.event) existing.event = extra.event;
|
|
|
|
|
}
|
|
|
|
|
if (kind === 'event' && extra.event) {
|
|
|
|
|
existing.events = existing.events ?? (existing.event ? [existing.event] : []);
|
|
|
|
|
if (!existing.events.includes(extra.event)) existing.events.push(extra.event);
|
|
|
|
|
}
|
|
|
|
|
return existing;
|
|
|
|
|
}
|
|
|
|
|
if (steps.size >= limit) {
|
|
|
|
|
truncated.steps++;
|
|
|
|
|
return null;
|
|
|
|
|
}
|
|
|
|
|
const isRoute = node.kind === 'route';
|
|
|
|
|
const record: StepRecord = {
|
|
|
|
|
id: node.id,
|
|
|
|
|
kind: isRoute ? 'screen' : kind,
|
|
|
|
|
anchor: false,
|
|
|
|
|
node: toNodeRef(node),
|
|
|
|
|
label: isRoute ? node.name : node.name,
|
|
|
|
|
sub: isRoute ? (componentOf.get(node.id)?.name ?? posix(node.filePath)) : posix(node.filePath),
|
|
|
|
|
depth,
|
|
|
|
|
cut: null,
|
|
|
|
|
...extra,
|
|
|
|
|
root: isRoute ? (componentOf.get(node.id) ?? null) : node,
|
|
|
|
|
};
|
|
|
|
|
if (kind === 'event' && extra.event) record.events = [extra.event];
|
|
|
|
|
if (isRoute) record.screen = { path: node.name, component: componentOf.has(node.id) ? toNodeRef(componentOf.get(node.id)!) : null };
|
|
|
|
|
steps.set(node.id, record);
|
|
|
|
|
return record;
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
// One box per (function, category): `uploadARCapture` makes one network
|
|
|
|
|
// call, three storage calls and three telemetry calls — three boxes, each
|
|
|
|
|
// listing its calls, not seven.
|
|
|
|
|
const effectStep = (by: Node, ref: { referenceName: string; line: number }, category: string, depth: number): StepRecord | null => {
|
|
|
|
|
const id = `effect:${by.id}:${category}`;
|
|
|
|
|
const existing = steps.get(id);
|
|
|
|
|
if (existing) {
|
|
|
|
|
const apis = existing.effect!.apis;
|
|
|
|
|
if (!apis.includes(ref.referenceName)) {
|
|
|
|
|
apis.push(ref.referenceName);
|
|
|
|
|
existing.label = `${apis[0]} +${apis.length - 1}`;
|
|
|
|
|
}
|
|
|
|
|
return existing;
|
|
|
|
|
}
|
|
|
|
|
if (steps.size >= limit) {
|
|
|
|
|
truncated.steps++;
|
|
|
|
|
return null;
|
|
|
|
|
}
|
|
|
|
|
const record: StepRecord = {
|
|
|
|
|
id,
|
|
|
|
|
kind: 'effect',
|
|
|
|
|
anchor: false,
|
|
|
|
|
node: null,
|
|
|
|
|
label: ref.referenceName,
|
|
|
|
|
sub: `${category} · ${by.name}`,
|
|
|
|
|
depth,
|
|
|
|
|
cut: null,
|
|
|
|
|
effect: { api: ref.referenceName, apis: [ref.referenceName], category, by: toNodeRef(by), line: ref.line },
|
|
|
|
|
root: null,
|
|
|
|
|
};
|
|
|
|
|
steps.set(id, record);
|
|
|
|
|
return record;
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
const link = (
|
|
|
|
|
from: StepRecord,
|
|
|
|
|
to: StepRecord,
|
|
|
|
|
kind: WireStepLinkKind,
|
|
|
|
|
chain: Node[],
|
|
|
|
|
whens: string[],
|
|
|
|
|
site: WireStepSite,
|
|
|
|
|
edge: Edge | null
|
|
|
|
|
): void => {
|
|
|
|
|
const meta = (edge?.metadata ?? {}) as Record<string, unknown>;
|
|
|
|
|
const synthesized = edge?.provenance === 'heuristic';
|
|
|
|
|
const confidence = typeof meta.confidence === 'number' ? meta.confidence : null;
|
|
|
|
|
const via = chain.map(toNodeRef);
|
|
|
|
|
const viaKey = via.map((v) => v.id).join('>');
|
|
|
|
|
const id = `${from.id} ${to.id} ${viaKey}`;
|
|
|
|
|
const when = whens.filter((w, i) => w && whens.indexOf(w) === i).join(' && ');
|
|
|
|
|
const existing = links.get(id);
|
|
|
|
|
if (existing) {
|
|
|
|
|
if (!existing.sites.some((s) => s.file === site.file && s.line === site.line)) existing.sites.push(site);
|
|
|
|
|
if (when !== existing.when) {
|
|
|
|
|
if (!when || !existing.when) existing.when = '';
|
|
|
|
|
else if (!existing.when.split(' || ').includes(when)) existing.when = `${existing.when} || ${when}`;
|
|
|
|
|
}
|
|
|
|
|
return;
|
|
|
|
|
}
|
|
|
|
|
links.set(id, {
|
|
|
|
|
id,
|
|
|
|
|
from: from.id,
|
|
|
|
|
to: to.id,
|
|
|
|
|
kind,
|
|
|
|
|
via,
|
|
|
|
|
when,
|
|
|
|
|
label: hopLabel(meta, synthesized),
|
|
|
|
|
synthesized,
|
|
|
|
|
uncertain: confidence !== null && confidence < UNCERTAIN_BELOW,
|
|
|
|
|
sites: [site],
|
|
|
|
|
});
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
// The anchor: a screen keeps its kind and explores from its component.
|
|
|
|
|
const first = stepFor(anchor, 'anchor', 0)!;
|
|
|
|
|
first.anchor = true;
|
|
|
|
|
const queue: StepRecord[] = [first];
|
|
|
|
|
/** Steps whose exploration has been queued — each is explored once, from the first row it appears on. */
|
|
|
|
|
const explored = new Set<string>([first.id]);
|
|
|
|
|
|
|
|
|
|
while (queue.length > 0) {
|
|
|
|
|
const step = queue.shift()!;
|
|
|
|
|
if (step.root === null) continue;
|
|
|
|
|
// Another screen is a chapter of its own: the Screens view draws the way
|
|
|
|
|
// between screens, and a picture that walked on through Home would be the
|
|
|
|
|
// whole app. Drawn as a boundary, entered on request.
|
|
|
|
|
if (step.kind === 'screen' && !step.anchor && !through) {
|
|
|
|
|
step.cut = 'screen';
|
|
|
|
|
continue;
|
|
|
|
|
}
|
|
|
|
|
// A native event that lands in a COMPONENT — the capture overlay taking
|
|
|
|
|
// `onCaptureProgress` — lands on another screen's body: its picture is
|
|
|
|
|
// that screen's, not this one's. A boundary too, entered on request.
|
|
|
|
|
if (step.kind === 'event' && !step.anchor && !through && looksLikeComponent(step.root)) {
|
|
|
|
|
step.cut = 'component';
|
|
|
|
|
continue;
|
|
|
|
|
}
|
|
|
|
|
if (step.depth >= depthCap) {
|
|
|
|
|
// Something to explore, and no room in the picture for it.
|
|
|
|
|
if (cg.getOutgoingEdgesFrom([step.root.id], WALK_KINDS).length > 0) step.cut = 'depth';
|
|
|
|
|
continue;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Breadth-first through the plumbing until the next steps.
|
|
|
|
|
const visited = new Set<string>([step.root.id]);
|
|
|
|
|
let frontier: Fold[] = [{ node: step.root, chain: [], whens: [] }];
|
|
|
|
|
for (let hop = 0; hop <= MAX_FOLD_DEPTH && frontier.length > 0; hop++) {
|
|
|
|
|
const next: Fold[] = [];
|
|
|
|
|
const ids = frontier.map((f) => f.node.id);
|
|
|
|
|
const outgoing = cg.getOutgoingEdgesFrom(ids, WALK_KINDS);
|
|
|
|
|
const bySource = new Map<string, Edge[]>();
|
|
|
|
|
for (const e of outgoing) {
|
|
|
|
|
const list = bySource.get(e.source) ?? [];
|
|
|
|
|
list.push(e);
|
|
|
|
|
bySource.set(e.source, list);
|
|
|
|
|
}
|
|
|
|
|
// `const Memoized = memo(CaptureComponent)`: the wrapper is a component
|
|
|
|
|
// node with no edges of its own — the inner component is referenced
|
|
|
|
|
// from the FILE scope, at the wrapper's line. Lend the wrapper those
|
|
|
|
|
// references, so the screen that renders `<Memoized/>` walks on into
|
|
|
|
|
// what the component does.
|
|
|
|
|
for (const fold of frontier) {
|
|
|
|
|
if (fold.node.kind !== 'component' || (bySource.get(fold.node.id)?.length ?? 0) > 0) continue;
|
|
|
|
|
for (const e of fileScopeFnRefsWithin(cg, fold.node, fileScopeRefs)) {
|
|
|
|
|
const list = bySource.get(fold.node.id) ?? [];
|
|
|
|
|
list.push({ ...e, source: fold.node.id });
|
|
|
|
|
bySource.set(fold.node.id, list);
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
const targetIds = new Set<string>();
|
|
|
|
|
for (const list of bySource.values()) for (const e of list) targetIds.add(e.target);
|
|
|
|
|
const targets = targetIds.size === 0 ? new Map<string, Node>() : cg.getNodesByIds([...targetIds]);
|
|
|
|
|
// Hubs and chrome are judged on the nodes about to be entered.
|
|
|
|
|
const unknownFanIn = [...targetIds].filter((id) => !fanIn.has(id));
|
|
|
|
|
if (unknownFanIn.length > 0) for (const [id, n] of cg.getFanIn(unknownFanIn)) fanIn.set(id, n);
|
|
|
|
|
|
|
|
|
|
for (const fold of frontier) {
|
|
|
|
|
// Effects made by this node, folded or not.
|
|
|
|
|
if (effectScans < MAX_EFFECT_SCANS) {
|
|
|
|
|
effectScans++;
|
|
|
|
|
let refs: UnresolvedReference[] = [];
|
|
|
|
|
try {
|
|
|
|
|
refs = cg.getUnresolvedReferencesFrom(fold.node.id);
|
|
|
|
|
} catch {
|
|
|
|
|
refs = [];
|
|
|
|
|
}
|
|
|
|
|
for (const ref of [...refs].sort((a, b) => a.line - b.line || a.column - b.column)) {
|
|
|
|
|
if (ref.referenceKind !== 'calls' && ref.referenceKind !== 'instantiates') continue;
|
|
|
|
|
const category = effectCategory(ref.referenceName);
|
|
|
|
|
if (category === null) continue;
|
|
|
|
|
const target = effectStep(fold.node, ref, category, step.depth + 1);
|
|
|
|
|
if (target === null) continue;
|
|
|
|
|
const when = await whenAt(fold.node, { line: ref.line, column: ref.column });
|
|
|
|
|
link(step, target, 'effect', fold.chain, [...fold.whens, when], { file: posix(fold.node.filePath), line: ref.line, text: ref.referenceName }, null);
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
let edges = (bySource.get(fold.node.id) ?? []).slice();
|
|
|
|
|
edges = edges.filter((e) => {
|
|
|
|
|
const meta = (e.metadata ?? {}) as Record<string, unknown>;
|
|
|
|
|
if (e.kind === 'references') return meta.fnRef === true;
|
|
|
|
|
if (e.kind === 'contains') {
|
|
|
|
|
const t = targets.get(e.target);
|
|
|
|
|
return (fold.node.kind === 'function' || fold.node.kind === 'method') && !!t && (t.kind === 'function' || t.kind === 'method');
|
|
|
|
|
}
|
|
|
|
|
return true;
|
|
|
|
|
});
|
|
|
|
|
edges.sort((a, b) => (a.line ?? 0) - (b.line ?? 0) || a.target.localeCompare(b.target));
|
|
|
|
|
if (edges.length > MAX_FANOUT) {
|
|
|
|
|
step.cut = 'fan-out';
|
|
|
|
|
edges = edges.slice(0, MAX_FANOUT);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Two passes: first every edge that arrives at a step, then the rest —
|
|
|
|
|
// so a node that IS a step (a handler wired to a tap) is never also
|
|
|
|
|
// folded as plumbing by the `contains` edge from the same component.
|
|
|
|
|
interface Arrival {
|
|
|
|
|
e: Edge;
|
|
|
|
|
target: Node;
|
|
|
|
|
meta: Record<string, unknown>;
|
|
|
|
|
site: WireStepSite;
|
|
|
|
|
kind: WireStepKind | null;
|
|
|
|
|
linkKind: WireStepLinkKind;
|
|
|
|
|
extra: Partial<WireStep>;
|
|
|
|
|
}
|
|
|
|
|
const arrivals: Arrival[] = [];
|
|
|
|
|
for (const e of edges) {
|
|
|
|
|
const target = targets.get(e.target);
|
|
|
|
|
if (!target || target.kind === 'file' || target.id === fold.node.id) continue;
|
|
|
|
|
const meta = (e.metadata ?? {}) as Record<string, unknown>;
|
|
|
|
|
const site: WireStepSite = {
|
|
|
|
|
file: posix(fold.node.filePath),
|
|
|
|
|
line: e.line ?? fold.node.startLine,
|
|
|
|
|
text: siteText(e, meta, target),
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
// What kind of step, if any, this edge arrives at.
|
|
|
|
|
let kind: WireStepKind | null = null;
|
|
|
|
|
let linkKind: WireStepLinkKind = 'calls';
|
|
|
|
|
const extra: Partial<WireStep> = {};
|
|
|
|
|
if (target.kind === 'route') {
|
|
|
|
|
kind = 'screen';
|
|
|
|
|
linkKind = 'navigates';
|
|
|
|
|
} else {
|
|
|
|
|
// A language change under the code is a step only on evidence: a
|
|
|
|
|
// bridge resolver's edge (`bridge`, or a framework resolution), or
|
|
|
|
|
// a synthesized channel's. A plain name-matched call across the
|
|
|
|
|
// families (`arr.flat()` landing on a Swift `flat`) is noise, and
|
|
|
|
|
// is neither drawn nor walked.
|
|
|
|
|
const cross = crossing(fold.node.language, target.language);
|
|
|
|
|
const evidenced = e.provenance === 'heuristic' || meta.bridge === 'react-native' || meta.resolvedBy === 'framework';
|
|
|
|
|
if (cross !== null && !evidenced) continue;
|
|
|
|
|
if (cross === 'event') {
|
|
|
|
|
kind = 'event';
|
|
|
|
|
linkKind = 'event';
|
|
|
|
|
if (typeof meta.event === 'string') extra.event = meta.event;
|
|
|
|
|
} else if (cross === 'bridge') {
|
|
|
|
|
kind = 'bridge';
|
|
|
|
|
linkKind = 'bridge';
|
|
|
|
|
} else if (e.kind === 'references' && meta.fnRef === true && !looksLikeComponent(target)) {
|
|
|
|
|
// A function passed as a value is a handler — unless it is a
|
|
|
|
|
// component (`memo(CaptureComponent)`, `component={Home}`),
|
|
|
|
|
// which is a render hop and folds like one.
|
|
|
|
|
kind = 'trigger';
|
|
|
|
|
linkKind = 'handler';
|
|
|
|
|
} else if (
|
|
|
|
|
(target.kind === 'function' || target.kind === 'method') &&
|
|
|
|
|
isStoreFile(target.filePath) &&
|
|
|
|
|
!isStoreFile(fold.node.filePath)
|
|
|
|
|
) {
|
|
|
|
|
kind = 'store';
|
|
|
|
|
linkKind = 'store';
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
arrivals.push({ e, target, meta, site, kind, linkKind, extra });
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
for (const a of arrivals) {
|
|
|
|
|
if (a.kind === null) continue;
|
|
|
|
|
const to = stepFor(a.target, a.kind, step.depth + 1, a.extra);
|
|
|
|
|
if (to === null) continue;
|
|
|
|
|
const when = await whenAt(fold.node, { line: a.e.line, column: a.e.column });
|
|
|
|
|
link(step, to, a.linkKind, fold.chain, [...fold.whens, when], a.site, a.e);
|
|
|
|
|
if (to.root !== null && !explored.has(to.id)) {
|
|
|
|
|
explored.add(to.id);
|
|
|
|
|
queue.push(to);
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
for (const a of arrivals) {
|
|
|
|
|
if (a.kind !== null) continue;
|
|
|
|
|
const { e, target, meta } = a;
|
|
|
|
|
|
|
|
|
|
// A call through a VALUE the effect table knows — `client.post` on
|
|
|
|
|
// the axios instance the project made itself resolves to the
|
|
|
|
|
// `client` constant, not to anything outside the index. The call
|
|
|
|
|
// text is the evidence: the call is the effect, the constant is not
|
|
|
|
|
// a place to walk into.
|
|
|
|
|
if (e.kind === 'calls' && (target.kind === 'constant' || target.kind === 'variable')) {
|
|
|
|
|
const api = typeof meta.refName === 'string' ? meta.refName : null;
|
|
|
|
|
const category = api === null ? null : effectCategory(api);
|
|
|
|
|
if (api !== null && category !== null) {
|
|
|
|
|
const to = effectStep(fold.node, { referenceName: api, line: e.line ?? fold.node.startLine }, category, step.depth + 1);
|
|
|
|
|
if (to === null) continue;
|
|
|
|
|
const when = await whenAt(fold.node, { line: e.line, column: e.column });
|
|
|
|
|
link(step, to, 'effect', fold.chain, [...fold.whens, when], { file: posix(fold.node.filePath), line: e.line ?? fold.node.startLine, text: api }, null);
|
|
|
|
|
continue;
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Already a step, reached here by a plain call: a link, not a fold.
|
|
|
|
|
const known = steps.get(target.id);
|
|
|
|
|
if (known) {
|
|
|
|
|
if (known.id !== step.id) {
|
|
|
|
|
const when = await whenAt(fold.node, { line: e.line, column: e.column });
|
|
|
|
|
link(step, known, 'calls', fold.chain, [...fold.whens, when], a.site, e);
|
|
|
|
|
}
|
|
|
|
|
continue;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Plumbing: fold it and keep walking, unless it is a dead end.
|
|
|
|
|
if (visited.has(target.id)) continue;
|
|
|
|
|
if ((fanIn.get(target.id) ?? 0) >= HUB_THRESHOLD) {
|
|
|
|
|
truncated.hubs++;
|
|
|
|
|
continue;
|
|
|
|
|
}
|
|
|
|
|
if (meta.synthesizedBy === 'jsx-render' && isSharedChrome(cg, target, chromeParents)) {
|
|
|
|
|
truncated.chrome++;
|
|
|
|
|
continue;
|
|
|
|
|
}
|
|
|
|
|
if (visited.size >= MAX_FOLDED_PER_STEP) {
|
|
|
|
|
step.cut = step.cut ?? 'folded';
|
|
|
|
|
continue;
|
|
|
|
|
}
|
|
|
|
|
visited.add(target.id);
|
|
|
|
|
const when = await whenAt(fold.node, { line: e.line, column: e.column });
|
|
|
|
|
next.push({ node: target, chain: [...fold.chain, target], whens: [...fold.whens, when] });
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
frontier = next;
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
const ordered = [...steps.values()].sort((a, b) => a.depth - b.depth || a.label.localeCompare(b.label) || a.id.localeCompare(b.id));
|
|
|
|
|
return {
|
|
|
|
|
anchor: toNodeRef(anchor),
|
|
|
|
|
ambiguous,
|
|
|
|
|
steps: ordered.map(({ root: _root, ...step }) => step),
|
|
|
|
|
links: [...links.values()].sort((a, b) => a.id.localeCompare(b.id)),
|
|
|
|
|
depth: depthCap,
|
|
|
|
|
limit,
|
|
|
|
|
through,
|
|
|
|
|
truncated,
|
|
|
|
|
index,
|
|
|
|
|
timing: { elapsedMs: Date.now() - started },
|
|
|
|
|
};
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// =============================================================================
|
|
|
|
|
// Helpers
|
|
|
|
|
// =============================================================================
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* The anchor: `anchor=<id>`, or `symbol=<name>` resolved to the most
|
|
|
|
|
* screen-like symbol of that name — a route first, then a component or
|
|
|
|
|
* function, then a method — with the rest reported as `ambiguous`.
|
|
|
|
|
*/
|
|
|
|
|
function resolveAnchor(cg: CodeGraph, query: URLSearchParams): { anchor: Node; ambiguous: WireNodeRef[] } {
|
|
|
|
|
const id = query.get('anchor');
|
|
|
|
|
if (id !== null && id.trim() !== '') {
|
|
|
|
|
const node = cg.getNode(id);
|
|
|
|
|
if (!node) throw notFound(`No symbol with id "${id}" in this index.`, 'It may have moved in a re-index; open it from search or the Screens view.');
|
|
|
|
|
return { anchor: node, ambiguous: [] };
|
|
|
|
|
}
|
|
|
|
|
const name = query.get('symbol');
|
|
|
|
|
if (name === null || name.trim() === '') throw badRequest('Give the picture an anchor: ?anchor=<node id> or ?symbol=<name>.');
|
|
|
|
|
const rank: Record<string, number> = { route: 0, component: 1, function: 2, method: 3, class: 4, constant: 5, variable: 6 };
|
|
|
|
|
const matches = cg
|
|
|
|
|
.getNodesByName(name.trim())
|
|
|
|
|
.filter((n) => n.kind !== 'file' && n.kind !== 'import' && n.kind !== 'export')
|
|
|
|
|
.sort((a, b) => (rank[a.kind] ?? 9) - (rank[b.kind] ?? 9) || a.filePath.localeCompare(b.filePath) || a.startLine - b.startLine);
|
|
|
|
|
const anchor = matches[0];
|
|
|
|
|
if (!anchor) throw notFound(`Nothing in this index is named "${name}".`, 'Try the search box; names are matched exactly.');
|
|
|
|
|
return { anchor, ambiguous: matches.slice(1, 9).map(toNodeRef) };
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** How many distinct parents render this node as a JSX child. Memoised per request. */
|
|
|
|
|
function renderParents(cg: CodeGraph, node: Node, memo: Map<string, number>): number {
|
|
|
|
|
let parents = memo.get(node.id);
|
|
|
|
|
if (parents === undefined) {
|
|
|
|
|
const incoming = cg.getIncomingEdgesTo([node.id], ['calls']);
|
|
|
|
|
const sources = new Set<string>();
|
|
|
|
|
for (const e of incoming) {
|
|
|
|
|
if ((e.metadata as Record<string, unknown> | undefined)?.synthesizedBy === 'jsx-render') sources.add(e.source);
|
|
|
|
|
}
|
|
|
|
|
parents = sources.size;
|
|
|
|
|
memo.set(node.id, parents);
|
|
|
|
|
}
|
|
|
|
|
return parents;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** A component rendered by several distinct parents is chrome. */
|
|
|
|
|
function isSharedChrome(cg: CodeGraph, component: Node, memo: Map<string, number>): boolean {
|
|
|
|
|
return renderParents(cg, component, memo) >= SHARED_CHROME_MIN;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** A React component, by the convention that names one: a PascalCase function in a JS-family file. */
|
|
|
|
|
function looksLikeComponent(node: Node): boolean {
|
|
|
|
|
if (node.kind === 'component') return true;
|
|
|
|
|
if (node.kind !== 'function') return false;
|
|
|
|
|
return JS_FAMILY.has(node.language) && /^[A-Z]/.test(node.name);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Function-as-value references made at a file's top level within a node's
|
|
|
|
|
* lines — what `const Memoized = memo(CaptureComponent)` leaves behind: the
|
|
|
|
|
* reference belongs to the file scope, the wrapper node spans the line.
|
|
|
|
|
*/
|
|
|
|
|
function fileScopeFnRefsWithin(cg: CodeGraph, node: Node, memo: Map<string, Edge[]>): Edge[] {
|
|
|
|
|
let refs = memo.get(node.filePath);
|
|
|
|
|
if (refs === undefined) {
|
|
|
|
|
const file = cg.getNodesInFile(node.filePath).find((n) => n.kind === 'file');
|
|
|
|
|
refs = file
|
|
|
|
|
? cg.getOutgoingEdgesFrom([file.id], ['references']).filter((e) => (e.metadata as Record<string, unknown> | undefined)?.fnRef === true)
|
|
|
|
|
: [];
|
|
|
|
|
memo.set(node.filePath, refs);
|
|
|
|
|
}
|
|
|
|
|
return refs.filter((e) => typeof e.line === 'number' && e.line >= node.startLine && e.line <= node.endLine);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** `push /capture`, `renders <Button>`, `via rn-event-channel`, `calls`. */
|
|
|
|
|
function siteText(edge: Edge, meta: Record<string, unknown>, target: Node): string {
|
|
|
|
|
if (edge.kind === 'navigates') {
|
|
|
|
|
const method = edge.provenance === 'heuristic' ? 'returns' : typeof meta.navMethod === 'string' ? meta.navMethod : 'push';
|
|
|
|
|
return `${method} ${typeof meta.href === 'string' ? meta.href : target.name}`;
|
|
|
|
|
}
|
|
|
|
|
if (meta.synthesizedBy === 'jsx-render') return `renders <${target.name}>`;
|
|
|
|
|
if (edge.kind === 'references') return `passes ${target.name}`;
|
|
|
|
|
if (edge.kind === 'contains') return `defines ${target.name}`;
|
|
|
|
|
if (edge.kind === 'instantiates') return `new ${target.name}`;
|
|
|
|
|
if (meta.bridge === 'react-native') return `bridge ${typeof meta.module === 'string' ? meta.module + '.' : ''}${target.name}`;
|
|
|
|
|
if (typeof meta.synthesizedBy === 'string') return `via ${meta.synthesizedBy}`;
|
|
|
|
|
return `calls ${target.name}`;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** The words on a hop that was not a plain call — the Flow strip's connector label, in short. */
|
|
|
|
|
function hopLabel(meta: Record<string, unknown>, synthesized: boolean): string {
|
|
|
|
|
const parts: string[] = [];
|
|
|
|
|
if (typeof meta.synthesizedBy === 'string') parts.push(`via ${meta.synthesizedBy}`);
|
|
|
|
|
else if (synthesized) parts.push('inferred');
|
|
|
|
|
if (typeof meta.event === 'string') parts.push(`event ${meta.event}`);
|
|
|
|
|
if (meta.bridge === 'react-native') parts.push(`React Native bridge${typeof meta.module === 'string' ? ` · ${meta.module}` : ''}`);
|
|
|
|
|
if (typeof meta.registeredAt === 'string') parts.push(`registered at ${meta.registeredAt}`);
|
|
|
|
|
return parts.join(' · ');
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
function posix(p: string): string {
|
|
|
|
|
return p.replace(/\\/g, '/');
|
|
|
|
|
}
|
Colby McHenry