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

package/dist/react-navigation.types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * What a project invented and React Navigation does not name.
+ *
+ * Every axis left unset falls back to a default. The axes with no default —
+ * `helperCalls`, `predicates` — stay empty rather than being guessed: a wrong
+ * default manufactures a plausible graph, whereas an empty axis shows up in the
+ * match counts.
+ */
+export interface ReactNavigationDialect {
+    /** Project-specific helpers that build a route. **Group 1 = route name.** */
+    helperCalls?: RegExp[];
+    /** Object keys carrying a literal route name (`screen: "Offer"`). */
+    configKeys?: string[];
+    /** JSX props and object keys carrying the user-visible label. */
+    labelProps?: string[];
+    /** Keys of registry entries in array form. */
+    registryEntry?: {
+        name: string;
+        component: string;
+    };
+    /** Mount-guard key in the static API (`if: useIsSignedIn`). */
+    guardKey?: string;
+    /** Predicates read from the component. **Group 1 = predicate name.** */
+    predicates?: Array<{
+        kind: string;
+        pattern: RegExp;
+    }>;
+    /** Path fragments to skip. */
+    exclude?: string[];
+    /** Depth of the closure used to attribute a call site to a screen. */
+    closureDepth?: number;
+    /** Graph name derived from the navigator's path. */
+    graphLabel?: (path: string) => string;
+    /**
+     * `linking` configuration files mapping screen -> URL path.
+     *
+     * A project that navigates by URL (`navigate(ROUTES.SETTINGS_PROFILE)`)
+     * never names the screen at the call site: the link between the two lives
+     * only in that configuration. Without it, zero edges.
+     */
+    routeAliasFiles?: string[];
+}

package/dist/registrations.d.ts

@@ -0,0 +1,95 @@
+import type { Domain } from "@cleya/domain";
+import { type Census } from "./census";
+import type { Dialect } from "./dialect";
+import { type Resolve } from "./route-names";
+import type { RegistryLiteral } from "./type-index";
+/**
+ * `withAuthProtection(BookingDetails)` -> `BookingDetails`.
+ *
+ * Registries wrap screens in HOCs; the first identifier is the wrapper, which
+ * would make every guarded route point at the same component.
+ *
+ * A namespace import is not a component: the code graph does not declare its
+ * members, so keeping the first segment would point forty-seven mounts at the
+ * same non-existent symbol. The last segment is kept instead.
+ *
+ * @example
+ * unwrapComponent("withOnyx(HomeScreen)");                            // "HomeScreen"
+ * unwrapComponent("React.memo(withOnyx(HomeScreen))");                // "HomeScreen"
+ * unwrapComponent("ModalStackNavigators.SettingsModalStackNavigator");// "SettingsModalStackNavigator"
+ * unwrapComponent(`lazy(() => require("./X").default)`);              // "lazy" — nothing to descend into
+ * unwrapComponent("123");                                             // null
+ */
+export declare const unwrapComponent: (expr: string) => string | null;
+/** One screen registration, as read from a registry or a JSX tag. */
+export interface Registration {
+    route: string;
+    line: number;
+    shape: Domain.Region.Navigation.ScreenShape;
+    /**
+     * The component rendered: an identifier from the file, or
+     * `module:<specifier>` when the registry loads it lazily
+     * (`() => require("…").default`). The two resolve differently — through the
+     * graph for the first, through the module path for the second — hence the
+     * distinction carried here.
+     */
+    component: string | null;
+    guard: string | null;
+    hasOptions: boolean;
+    /** Navigator named by the enclosing declaration, when a file holds several. */
+    graph?: string;
+}
+/**
+ * Lazy loaders declared in the file:
+ * `const loadSettings = () => require("…/InitialSettingsPage").default`.
+ *
+ * `getComponent={loadSettings}` does not name a component, it names the loader.
+ * Without this table the screen is registered with no component — hence no
+ * closure, hence no outgoing edge at all. Eighteen `AuthScreens` screens depend
+ * on it, the home screen among them.
+ *
+ * @example
+ * const src = `const loadSettings = () => require("./Settings").default;`;
+ * lazyLoaders(src, stripNoise(src)).get("loadSettings"); // "./Settings"
+ */
+export declare const lazyLoaders: (src: string, blanked: string) => Map<string, string>;
+/**
+ * Registrations read from a `screens: {…}` block or an array-form registry.
+ *
+ * @example
+ * fromRegistries(src, stripNoise(src), dialect, "Nav.tsx", resolve);
+ * // [{ route: "Home", shape: "static-config", component: "HomePage", … }]
+ */
+export declare const fromRegistries: (src: string, blanked: string, d: Dialect, file: string, resolve: Resolve) => Registration[];
+/**
+ * The registries typing designated, whatever their spelling.
+ *
+ * `createXNavigator({ [SCREENS.A]: () => require("…") })` and
+ * `const CENTRAL_PANE_SCREENS = {…} satisfies Screens` are the same thing: an
+ * object whose keys name routes and whose values render components.
+ * Distinguishing them used to demand two dialect axes and two regular
+ * expressions written per project; the type says it without being asked.
+ *
+ * One difference remains, but it is structural and the AST carries it: an
+ * object passed as a call argument produces a navigator, which the receiving
+ * declaration names — a project may place forty of them in one file, which
+ * rules out naming the graph after the path.
+ *
+ * @example
+ * fromRegistryLiterals(src, blanked, dialect, "Nav.tsx", resolve, types.registryLiterals("Nav.tsx"));
+ * // [{ route: "Travel_MyTrips", shape: "factory-arg", graph: "TravelNavigator", … }]
+ */
+export declare const fromRegistryLiterals: (src: string, blanked: string, d: Dialect, file: string, resolve: Resolve, registries: RegistryLiteral[]) => Registration[];
+/**
+ * `<Stack.Screen name="Route" component={Comp} />`, brace-balanced so an
+ * `options={() => …}` arrow cannot end the tag early.
+ *
+ * Records into `census` every `<Screen>` tag whose name does not resolve: such
+ * a tag is a lost screen, not an uninteresting one.
+ *
+ * @example
+ * fromJsx(src, stripNoise(src), dialect, "Nav.tsx", resolve, census);
+ * // [{ route: "Home", shape: "inline-jsx", component: "HomePage", … }]
+ * census.jsxMissed; // ["Nav.tsx:12  name={SCREENS.UNKNOWN}"]
+ */
+export declare const fromJsx: (src: string, blanked: string, d: Dialect, file: string, resolve: Resolve, census: Census) => Registration[];

package/dist/route-names.d.ts

@@ -0,0 +1,135 @@
+import { type Attr } from "./blank";
+/**
+ * Collect string enum members into the name table.
+ *
+ * Numeric members are skipped: only a string member designates a route name.
+ *
+ * @example
+ * const names = new Map<string, string>();
+ * const src = `enum Screens { HOME = "home", PROFILE = "profile" }`;
+ * collectEnums(src, stripNoise(src), names);
+ * names.get("Screens.HOME"); // "home"
+ * // `enum Mixed { A = 1, B = "b" }` contributes only "Mixed.B"
+ */
+export declare const collectEnums: (src: string, blanked: string, into: Map<string, string>) => void;
+/**
+ * Name table: enum members and constant paths, mixed together.
+ *
+ * Both answer the same question — which route does this symbol designate — and
+ * a project may use both. One table, therefore one resolution downstream.
+ */
+export type Names = Map<string, string>;
+/**
+ * A leading `IDENT.PATH` reference — at least one dot, so a bare identifier
+ * does not match. Anchored: it reads what an expression *starts* with, which is
+ * the constant, the rest being accessors.
+ */
+export declare const REF_PATH: RegExp;
+/**
+ * Resolve a reference through the table, tail segment by tail segment.
+ *
+ * **Fallback.** The nominal resolver is the TypeChecker (`./type-index`); this
+ * one only serves projects offering no usable TypeScript program, and enums,
+ * which `collectEnums` picks up without configuration.
+ *
+ * The site almost never writes the bare path: `ROUTES.SETTINGS.route`,
+ * `ROUTES.SEARCH_ROOT.getRoute(…)` — the constant is the prefix, the rest is
+ * an accessor.
+ *
+ * @example
+ * const names = new Map([["ROUTES.SETTINGS", "Settings"]]);
+ * resolveRef(names, "ROUTES.SETTINGS.getRoute"); // "Settings" — trailing accessor dropped
+ * resolveRef(names, "ROUTES.SETTINGS");          // "Settings"
+ * resolveRef(names, "OTHER");                    // null
+ */
+export declare const resolveRef: (names: Names, ref: string) => string | null;
+/**
+ * "Which route does this piece of code name?", asked once.
+ *
+ * All three families of site — registry key, JSX attribute, call argument — go
+ * through here. The range designates the expression in the file; the text only
+ * serves the table fallback.
+ *
+ * @example
+ * // The checker first, the table as a fallback — the order is a hierarchy of
+ * // evidence, not a preference.
+ * const resolve: Resolve = (file, start, end, text) =>
+ *   types?.literalIn(file, start, end) ?? resolveRef(names, text);
+ */
+export type Resolve = (file: string, start: number, end: number, text: string) => string | null;
+/**
+ * The fate of a censused site.
+ *
+ * The three failures do not call for the same work, and conflating them under
+ * "unresolved" would send you looking in the wrong place:
+ *   `unknown` — readable target the registry ignores: a missed registration
+ *   `pattern` — no literal, but a known URL pattern: joinable, later
+ *   `dynamic` — opaque: irreducible, to be documented as such
+ */
+export type Verdict = "resolved" | "unknown" | "pattern" | "dynamic";
+/**
+ * Classifies a censused site into a {@link Verdict}.
+ *
+ * Separate from {@link Resolve} on purpose: resolving answers "which route",
+ * classifying answers "why did this one produce nothing", and the census must
+ * not feed its own counters back into the dialect report.
+ *
+ * @example
+ * classify("a.ts", start, end, "ROUTES.X"); // "unknown" — readable, not registered
+ * classify("a.ts", start, end, "url(id)");  // "pattern" — a URL shape, joinable later
+ */
+export type Classify = (file: string, start: number, end: number, text: string) => Verdict;
+/**
+ * The route named by a registry key.
+ *
+ * Two cases in one field: the literal key (`Home:`), which *is* the route name,
+ * and the expression (`[SCREENS.TRAVEL.MY_TRIPS]:`), which designates it. The
+ * fallback to `key` covers the first: a key that does not resolve is still a
+ * valid route name, and that is the majority convention.
+ *
+ * A dotted key that does not resolve returns `null` rather than the raw text —
+ * `SCREENS.TRAVEL.MY_TRIPS` is a reference, and taking it for a route name
+ * would register a route nobody can navigate to.
+ *
+ * @example
+ * const resolve = () => null;
+ * keyRoute("Home", 0, "a.ts", resolve);            // "Home" — a plain key is its own name
+ * keyRoute("SCREENS.HOME", 0, "a.ts", resolve);    // null — unresolved reference
+ */
+export declare const keyRoute: (key: string, keyAt: number, file: string, resolve: Resolve) => string | null;
+/**
+ * The route name carried by an attribute: literal, or expression to resolve.
+ *
+ * @example
+ * routeNameOf({ literal: "Home", expr: null, at: null }, "a.tsx", 0, resolve);  // "Home"
+ * routeNameOf({ literal: null, expr: null, at: null }, "a.tsx", 0, resolve);    // null
+ */
+export declare const routeNameOf: (value: Attr, file: string, base: number, resolve: Resolve) => string | null;
+/**
+ * Recursive walk of the `linking` configuration.
+ *
+ * An entry whose value contains `screens:` is a nested navigator: its value
+ * carries its children's entries, and harvesting URL constants there would
+ * attach them all to the navigator instead of the screen. So we descend rather
+ * than read.
+ *
+ * @example
+ * const aliases: Names = new Map();
+ * collectAliases(src, stripNoise(src), objStart, "config.ts", resolve, aliases, 0);
+ * aliases.get("settings/profile"); // "Settings_Profile" — URL keyed to its screen
+ */
+export declare const collectAliases: (src: string, blanked: string, objStart: number, file: string, resolve: Resolve, into: Names, depth: number) => void;
+/**
+ * Nested symbol: more than one segment after the file path.
+ *
+ * `component={Comp}` names a top-level binding — an import or a declaration of
+ * the file. An enum member, on the other hand, carries a five-segment id
+ * (`…|AppNavigationNames|HighlightScreen`) and happens to be the homonym of the
+ * component it names. Keeping it as a candidate points `RENDERS` at the member
+ * instead of the screen.
+ *
+ * @example
+ * isNested("ws|internal|a.ts|Comp");             // false — a top-level binding
+ * isNested("ws|internal|a.ts|Names|HomeScreen"); // true — an enum member
+ */
+export declare const isNested: (id: string) => boolean;

package/dist/type-index.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The compiler's answers about one project, queried by source range.
+ *
+ * Ranges are byte offsets into the file as it sits on disk at build time. The
+ * index is a snapshot: a file edited after `createTypeIndex` returns will be
+ * answered against its old contents, so an extraction pass must not outlive the
+ * read that fed it.
+ *
+ * A range naming no file the program knows — outside the `tsconfig` scope, or
+ * spelled differently from the compiler's own path — yields `null` rather than
+ * throwing. Absence therefore means two things at once, "not a literal" and "not
+ * in the program", and callers that need to tell them apart must check
+ * `sourceFiles` first.
+ *
+ * Holding this index holds the whole TypeScript program — about 2 GB on a large
+ * repository. Release it as soon as extraction ends.
+ */
+export interface TypeIndex {
+    /**
+     * The string literal carried by the expression spanning `[start, end)`.
+     *
+     * A range is given rather than a position: the site is found by a pattern,
+     * which knows the bounds of the captured text but not the shape of the tree
+     * beneath it. The range designates the node without having to name it.
+     */
+    literalIn(file: string, start: number, end: number): string | null;
+    /**
+     * The URL pattern, when the expression has no literal but a *template* type:
+     * `ROUTES.SEARCH_REPORT.getRoute(id)` has type
+     * `` `search/view/${string}` ``.
+     *
+     * Not yet used to build edges — it is measured, so that "unresolved" splits
+     * into "computed, but I know the URL shape" and "opaque". The two do not call
+     * for the same work, and conflating them would make something reducible look
+     * irreducible.
+     */
+    patternIn(file: string, start: number, end: number): string[] | null;
+    /**
+     * The object literals in this file that *are* a screen registry.
+     *
+     * Recognised by their typed shape, not by their name nor by what surrounds
+     * them: every key resolves to a string literal, and the values are callable.
+     * That holds for a factory's argument as much as for a `const` walked thirty
+     * lines further down — two spellings that used to demand two dialect axes,
+     * and that are only one thing.
+     *
+     * The neighbouring `SIDEBAR_TO_SPLIT` has exactly the same *syntactic shape*
+     * and excludes itself: its values are navigator names, hence strings, hence
+     * nothing to mount.
+     */
+    registryLiterals(file: string): RegistryLiteral[];
+    readonly sourceFiles: number;
+    readonly buildMs: number;
+}
+/**
+ * An object literal the checker recognises as a screen registry.
+ *
+ * `start` is the offset of the opening brace and `end` the offset just past the
+ * closing one, so `src.slice(start, end)` is the literal itself — the form a key
+ * walk expects.
+ *
+ * Recognition is by typed shape, never by name: an object whose keys all resolve
+ * to string literals and whose values are callable. A lookup table of navigator
+ * *names* has the same syntax and is excluded, because its values are strings
+ * and a string mounts nothing.
+ */
+export interface RegistryLiteral {
+    /** Position of the opening brace, ready for a key walk. */
+    start: number;
+    end: number;
+    /**
+     * The object is a call's argument.
+     *
+     * Not a detail of shape: the call *produces* the navigator, so the
+     * declaration receiving it names it. An object declared on its own is only a
+     * list of screens mounted elsewhere — its name names no navigator.
+     */
+    viaCall: boolean;
+}
+/**
+ * Build the index, or return `null` when the project offers no way to.
+ *
+ * Returning `null` rather than throwing: a project without a `tsconfig.json`,
+ * or whose dependencies are not installed, must keep indexing through the
+ * tables — degraded, not broken. The caller reports the fallback.
+ *
+ * @example
+ * const index = createTypeIndex(root, ["navigator.ts", "screens.ts"]);
+ * index?.literalIn("navigator.ts", start, end); // "Travel_MyTrips"
+ * createTypeIndex("/no-tsconfig-here", []);     // null — degrade, do not throw
+ */
+export declare const createTypeIndex: (projectRoot: string, files: string[]) => TypeIndex | null;

package/package.json

@@ -1,6 +1,38 @@
 {
-  "name": "@cleya/contributor-react-navigation",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@cleya/contributor-react-navigation",
+	"description": "Indexes React Navigation screens, routes and navigation edges",
+	"cleya": {
+		"category": "contributor"
+	},
+	"version": "1.0.0-next.0",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/react-navigation.index.d.ts",
+			"default": "./dist/react-navigation.index.js"
+		}
+	},
+	"types": "./dist/react-navigation.index.d.ts",
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "bun build ./src/react-navigation.index.ts --outdir dist --target bun --external @cleya/config --external @cleya/domain --external @cleya/region-navigation --external typescript && bunx tsc -p tsconfig.build.json"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"peerDependencies": {
+		"@cleya/config": "1.0.0-next.0",
+		"@cleya/domain": "1.0.0-next.0",
+		"@cleya/region-navigation": "1.0.0-next.0",
+		"typescript": "^5"
+	},
+	"devDependencies": {
+		"@cleya/config": "1.0.0-next.0",
+		"@cleya/core": "0.1.2-next.0",
+		"@cleya/domain": "1.0.0-next.0",
+		"@cleya/region-navigation": "1.0.0-next.0",
+		"@cleya/region-trace": "1.0.0-next.0"
+	}
+}