@quolu/lattice 0.69.5 → 0.71.0

package/sensor/dist/ui-server/api/map.d.ts

@@ -0,0 +1,256 @@
+/**
+ * `GET /api/map` — the repository at module granularity.
+ *
+ * The Map answers "what is in here and how is it organised" without anybody
+ * having drawn a diagram: modules are directories, the arrows between them are
+ * the edges the index already holds, and the vertical order falls out of the
+ * dependency direction (design spec §3.6). This module produces the *data*;
+ * the layering, cycle-breaking and geometry are pure functions in the viewer
+ * (`ui/src/lib/map-model.ts`), so toggling tests or selecting a module never
+ * costs a round-trip.
+ *
+ * Three decisions shape the payload, and all three are about not lying:
+ *
+ * **A module is a directory, not a guess.** `moduleIdFor` maps each indexed
+ * file to the first {@link MapQuery.depth} path segments under the chosen root.
+ * A file sitting loose in the root gets folded into one `(root files)` box —
+ * except a façade (`index.ts`, `lib.rs`, `__init__.py`), which is its own box
+ * because it is the thing everything else imports. No clustering, no
+ * heuristics about "what belongs together": if two files are in the same
+ * directory the repository already said they belong together.
+ *
+ * **Weight counts edges; layering counts *declared* edges.** A link's `count`
+ * is every confident cross-module edge behind it, which is what the reader
+ * sees as thickness. Its `declared` count is the subset resolved through an
+ * import, a qualified name, an inheritance clause or a typed receiver — and
+ * that is what the layout layers on. The difference is not academic: on this
+ * repository, bare name matching resolves calls to `run`, `push` and `finish`
+ * across unrelated directories, and layering on raw counts puts the storage
+ * layer directly under the CLI. Layering on declared edges reproduces the
+ * pipeline the project's own docs describe.
+ *
+ * **Nothing is dropped silently.** Uncertain edges (confidence below
+ * {@link UNCERTAIN_BELOW}) are excluded from every count, and how many were
+ * excluded rides on the payload so the side panel can say so.
+ */
+import type { LatticeSensor } from '../../index';
+import type { EdgeKind, Language } from '../../types';
+import { type WireList } from './wire';
+/**
+ * The edge kinds that count as "module A reaches into module B".
+ *
+ * `contains` is absent on purpose — a file containing its own symbols is not a
+ * dependency, and including it would make every module depend on itself.
+ */
+export declare const MAP_EDGE_KINDS: readonly EdgeKind[];
+/** Id of the bucket loose files fall into. Deliberately not a real directory name. */
+export declare function rootFilesId(root: string): string;
+export interface WireMapModule {
+    /** Directory path, or the `(root files)` bucket, or a façade file's own path. */
+    id: string;
+    /**
+     * What the box says: the id, with a folder chain the repository never forks
+     * in written `first/…/last` — Maven's `src/main/java/…/petclinic/owner`
+     * rather than all seven segments. Equal to `id` everywhere else.
+     */
+    label: string;
+    files: number;
+    symbols: number;
+    /** File count by language, most files first. */
+    languages: Array<{
+        language: Language;
+        files: number;
+    }>;
+    /** More than half its files are tests — drawn dashed, hidden by default. */
+    test: boolean;
+    /**
+     * How many of its files are tool-generated. A module whose files are ALL
+     * generated is drawn in ink-4 (design spec §2.6): code nobody wrote by hand
+     * and nobody deletes by hand.
+     */
+    generated: number;
+    /** Which of {@link fileList}'s entries are generated, so a row can dim too. */
+    generatedFiles: string[];
+    /** True when this box is a single file kept out of the root bucket (a façade). */
+    facade: boolean;
+    /** Its files, capped — what the side panel lists when the module is selected. */
+    fileList: WireList<string>;
+    /**
+     * What a change in here reaches: files OUTSIDE this module holding a direct,
+     * confident reference into one of its files, and how many modules those
+     * files span.
+     *
+     * DIRECT, deliberately. The transitive closure was measured first and it is
+     * useless on a real repository: any dependency cycle — and a mobile app had
+     * nine mutual pairs — saturates it, so every module comes out reaching
+     * nearly every file (139–282 of 377, a flat 2× spread that says nothing but
+     * "this repo has cycles"). The direct count on the same repository spreads
+     * 0–127 and names the modules a reader would name by hand: the shared types
+     * at the top, the CLI at zero.
+     *
+     * The counts are FILES, not symbols: a module is a set of files, and "94
+     * files would have to be re-read if this changed" is a claim the index can
+     * stand behind. It is a floor on blast radius, not the whole of it — a
+     * symbol-level answer for one symbol is what the Symbol view is for.
+     */
+    dependents: {
+        files: number;
+        modules: number;
+    };
+}
+export interface WireMapLink {
+    source: string;
+    target: string;
+    /** Every confident cross-module edge behind this link. Drives thickness. */
+    count: number;
+    /**
+     * The subset resolved through an import, a qualified name, an inheritance
+     * clause or a typed receiver. Drives the layering — see the module header.
+     */
+    declared: number;
+    /** `count` broken down by edge kind, biggest first. */
+    byKind: Array<{
+        kind: EdgeKind;
+        count: number;
+    }>;
+    /**
+     * The busiest symbol pairs behind the link, at most
+     * {@link TOP_PAIRS_PER_LINK}, declared ones first.
+     */
+    topPairs: Array<{
+        from: string;
+        to: string;
+        count: number;
+        declared: number;
+    }>;
+}
+export interface WireMapCycle {
+    /** How many files are in the component. `files` may be shorter. */
+    size: number;
+    /** The files, capped — a 200-file knot is a fact, not a list anybody reads. */
+    files: string[];
+    /** The modules the cycle passes through, deduped in order. */
+    modules: string[];
+}
+export interface WireMapPayload {
+    root: string;
+    depth: number;
+    /** Every root the selector may offer, this index's own directories. */
+    roots: Array<{
+        root: string;
+        label: string;
+        files: number;
+    }>;
+    modules: WireMapModule[];
+    links: WireMapLink[];
+    /**
+     * File-level circular dependencies — the strongly connected components of
+     * the file graph, which is what `findCircularDependencies` reports, computed
+     * from one query so it stays affordable on a large index.
+     */
+    cycles: {
+        total: number;
+        shown: number;
+        truncated: boolean;
+        items: WireMapCycle[];
+    };
+    excluded: {
+        /** Cross-module edges left out for being name-only guesses. */
+        uncertainEdges: number;
+        /** The confidence floor applied. */
+        confidenceBelow: number;
+    };
+    index: {
+        lastIndexedAt: number | null;
+        edges: number;
+        files: number;
+    };
+    /** How long the aggregation took, and whether this answer came from the cache. */
+    timing: {
+        elapsedMs: number;
+        cached: boolean;
+    };
+}
+export interface MapQuery {
+    root: string;
+    depth: number;
+}
+/** Strip a trailing slash and any leading `./`, so `src/` and `src` are one root. */
+export declare function normalizeRoot(raw: string | undefined): string;
+/**
+ * Directories a module boundary never falls on: exactly one subdirectory and
+ * no file of their own. A Maven project keeps every line of Java under
+ * `src/main/java/org/springframework/samples/petclinic/`, and the first four
+ * of those folders split nothing — cutting at any of them draws the whole
+ * program as one box, and no depth the reader can pick gets past them. Such a
+ * folder joins the level below it, so depth counts folders that fork.
+ *
+ * Read from every indexed file, tests included, so a module's id does not
+ * change when the reader toggles tests. The repository root is never one.
+ */
+export declare function passThroughDirs(paths: Iterable<string>): Set<string>;
+/**
+ * Which module a file belongs to, or `null` when it is outside the root.
+ *
+ * `depth` levels under the root name the module — a level being a folder and
+ * the {@link passThroughDirs} that follow it (without them, one level per
+ * folder). A file with fewer levels than that is loose in the root: a façade
+ * keeps its own box, everything else joins the `(root files)` bucket.
+ */
+export declare function moduleIdFor(filePath: string, root: string, depth: number, passThrough?: ReadonlySet<string>): {
+    id: string;
+    facade: boolean;
+    label: string;
+} | null;
+/**
+ * The root the map opens on: the directory holding the most non-test symbols.
+ *
+ * A repository's source almost always lives under one directory (`src`, `lib`,
+ * `pkg`, `app`), and opening there is what keeps the default map about the
+ * program rather than about its tests, scripts and sibling packages. The
+ * fallback is the repository root, which is correct for a flat project.
+ *
+ * A directory only wins if it holds a clear majority of the symbols — anything
+ * less and the honest answer is "this repository has no single source root".
+ */
+export declare function pickDefaultRoot(files: ReadonlyArray<{
+    path: string;
+    symbols: number;
+    test: boolean;
+}>): string;
+/**
+ * How many segments name a module, when the reader has not said.
+ *
+ * Depth is not a property of the reader's taste, it is a property of the
+ * repository: one level under the root is the right grouping for a project
+ * whose directories ARE its modules, and the wrong one for the very common
+ * shape where every line of the program lives under a single `src/`. Drawing
+ * that project at depth 1 produces the map this rule exists to prevent — a box
+ * labelled `src`, holding two thirds of the code, with nothing to say about it.
+ *
+ * So: take the shallowest depth that is neither dominated by one box worth
+ * opening nor too small to be a picture; stop before a deeper one becomes a
+ * crowd; and never go past the last level the directory tree actually has.
+ *
+ * The walk does NOT stop at the first depth that fails to add boxes. A repo
+ * packaged as `frontend/src/...` plateaus at two boxes for two levels running
+ * before the third splits it, and a rule that gave up on the plateau would
+ * draw exactly the picture this function exists to avoid.
+ */
+export declare function pickDefaultDepth(files: ReadonlyArray<{
+    path: string;
+    symbols: number;
+    test: boolean;
+}>, root: string, passThrough?: ReadonlySet<string>): number;
+export declare function resetMapCache(): void;
+/**
+ * `null` for either field means "nobody said" — the answer picks. Absence has
+ * to survive parsing: a depth defaulted to 1 here is indistinguishable from a
+ * reader who asked for 1, and {@link pickDefaultDepth} would never run.
+ */
+export declare function parseMapQuery(query: URLSearchParams): {
+    root: string | null;
+    depth: number | null;
+};
+export declare function buildMap(cg: LatticeSensor, projectRoot: string, query: URLSearchParams): WireMapPayload;
+//# sourceMappingURL=map.d.ts.map

package/sensor/dist/ui-server/api/map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map.d.ts","sourceRoot":"","sources":["../../../src/ui-server/api/map.ts"],"names":[],"mappings":"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"}