@quolu/lattice 0.70.0 → 0.71.1

package/sensor/dist/file-limits.d.ts

@@ -0,0 +1,40 @@
+import * as fs from 'fs';
+/**
+ * Largest source file LatticeSensor will parse or read during resolution. Generated
+ * bundles, minified sources, and dependency archives above this limit provide no
+ * useful symbols; 1 MB covers essentially all hand-written source.
+ */
+export declare const MAX_SOURCE_FILE_SIZE_BYTES: number;
+/**
+ * What stands in for the content of a file over MAX_SOURCE_FILE_SIZE_BYTES. Such a file is
+ * never parsed, so its bytes are never needed — reading them only to hash and
+ * discard cost multi-GB RSS spikes on committed video/blob fixtures and could
+ * fail outright with `Invalid string length` (#1910). The stamp is a function
+ * of size alone: change detection compares it to the stored hash, so a
+ * same-size rewrite of an oversize file is not a change (nothing about it is
+ * indexed), while crossing the limit in either direction is.
+ */
+export declare function oversizeStamp(size: number): string;
+/**
+ * The text whose hash the index stores for a file of `size` bytes: its content
+ * within the limit, the size stamp over it. Anything that checks a file on disk
+ * against its stored `contentHash` has to hash this, or every unchanged file
+ * over the limit reads as drifted. `content` is only read within the limit.
+ */
+export declare function indexedHashInput(size: number, content: () => string): string;
+/** A source file's stats, and its bytes when they are within the limit (null = oversize). */
+export interface BoundedSource {
+    stats: fs.Stats;
+    bytes: Buffer | null;
+}
+/**
+ * Read a source file without ever holding more than the limit plus one byte.
+ * A stat before the read is not enough: the file can grow between the stat
+ * and the read (a log, a download, a build output being written), so the
+ * descriptor is re-checked after opening and the read itself stops one byte
+ * past the limit. Returns `bytes: null` for an oversize file.
+ */
+export declare function readBoundedSource(file: string): Promise<BoundedSource>;
+/** Synchronous {@link readBoundedSource}. */
+export declare function readBoundedSourceSync(file: string): BoundedSource;
+//# sourceMappingURL=file-limits.d.ts.map

package/sensor/dist/file-limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-limits.d.ts","sourceRoot":"","sources":["../src/file-limits.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AAGzB;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,QAAc,CAAC;AAEtD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,MAAM,GAAG,MAAM,CAE5E;AAED,6FAA6F;AAC7F,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAQD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA2B5E;AAED,6CAA6C;AAC7C,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CA2BjE"}

package/sensor/dist/file-limits.js

@@ -0,0 +1,147 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_SOURCE_FILE_SIZE_BYTES = void 0;
+exports.oversizeStamp = oversizeStamp;
+exports.indexedHashInput = indexedHashInput;
+exports.readBoundedSource = readBoundedSource;
+exports.readBoundedSourceSync = readBoundedSourceSync;
+const fs = __importStar(require("fs"));
+const fsp = __importStar(require("fs/promises"));
+/**
+ * Largest source file LatticeSensor will parse or read during resolution. Generated
+ * bundles, minified sources, and dependency archives above this limit provide no
+ * useful symbols; 1 MB covers essentially all hand-written source.
+ */
+exports.MAX_SOURCE_FILE_SIZE_BYTES = 1024 * 1024;
+/**
+ * What stands in for the content of a file over MAX_SOURCE_FILE_SIZE_BYTES. Such a file is
+ * never parsed, so its bytes are never needed — reading them only to hash and
+ * discard cost multi-GB RSS spikes on committed video/blob fixtures and could
+ * fail outright with `Invalid string length` (#1910). The stamp is a function
+ * of size alone: change detection compares it to the stored hash, so a
+ * same-size rewrite of an oversize file is not a change (nothing about it is
+ * indexed), while crossing the limit in either direction is.
+ */
+function oversizeStamp(size) {
+    return `latticeSensor:oversize:${size}`;
+}
+/**
+ * The text whose hash the index stores for a file of `size` bytes: its content
+ * within the limit, the size stamp over it. Anything that checks a file on disk
+ * against its stored `contentHash` has to hash this, or every unchanged file
+ * over the limit reads as drifted. `content` is only read within the limit.
+ */
+function indexedHashInput(size, content) {
+    return size > exports.MAX_SOURCE_FILE_SIZE_BYTES ? oversizeStamp(size) : content();
+}
+const READ_CHUNK_BYTES = 64 * 1024;
+function assertRegularFile(stats) {
+    if (!stats.isFile())
+        throw new Error('Source path is not a regular file');
+}
+/**
+ * Read a source file without ever holding more than the limit plus one byte.
+ * A stat before the read is not enough: the file can grow between the stat
+ * and the read (a log, a download, a build output being written), so the
+ * descriptor is re-checked after opening and the read itself stops one byte
+ * past the limit. Returns `bytes: null` for an oversize file.
+ */
+async function readBoundedSource(file) {
+    const initial = await fsp.stat(file);
+    assertRegularFile(initial);
+    if (initial.size > exports.MAX_SOURCE_FILE_SIZE_BYTES)
+        return { stats: initial, bytes: null };
+    const handle = await fsp.open(file, 'r');
+    try {
+        let stats = await handle.stat();
+        assertRegularFile(stats);
+        if (stats.size > exports.MAX_SOURCE_FILE_SIZE_BYTES)
+            return { stats, bytes: null };
+        const chunks = [];
+        let size = 0;
+        while (size <= exports.MAX_SOURCE_FILE_SIZE_BYTES) {
+            const chunk = Buffer.allocUnsafe(Math.min(READ_CHUNK_BYTES, exports.MAX_SOURCE_FILE_SIZE_BYTES + 1 - size));
+            const { bytesRead } = await handle.read(chunk, 0, chunk.length, size);
+            if (!bytesRead)
+                break;
+            chunks.push(chunk.subarray(0, bytesRead));
+            size += bytesRead;
+        }
+        stats = await handle.stat();
+        if (size > exports.MAX_SOURCE_FILE_SIZE_BYTES || stats.size > exports.MAX_SOURCE_FILE_SIZE_BYTES) {
+            stats.size = Math.max(size, stats.size);
+            return { stats, bytes: null };
+        }
+        return { stats, bytes: Buffer.concat(chunks, size) };
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Synchronous {@link readBoundedSource}. */
+function readBoundedSourceSync(file) {
+    const initial = fs.statSync(file);
+    assertRegularFile(initial);
+    if (initial.size > exports.MAX_SOURCE_FILE_SIZE_BYTES)
+        return { stats: initial, bytes: null };
+    const fd = fs.openSync(file, 'r');
+    try {
+        let stats = fs.fstatSync(fd);
+        assertRegularFile(stats);
+        if (stats.size > exports.MAX_SOURCE_FILE_SIZE_BYTES)
+            return { stats, bytes: null };
+        const chunks = [];
+        let size = 0;
+        while (size <= exports.MAX_SOURCE_FILE_SIZE_BYTES) {
+            const chunk = Buffer.allocUnsafe(Math.min(READ_CHUNK_BYTES, exports.MAX_SOURCE_FILE_SIZE_BYTES + 1 - size));
+            const bytesRead = fs.readSync(fd, chunk, 0, chunk.length, size);
+            if (!bytesRead)
+                break;
+            chunks.push(chunk.subarray(0, bytesRead));
+            size += bytesRead;
+        }
+        stats = fs.fstatSync(fd);
+        if (size > exports.MAX_SOURCE_FILE_SIZE_BYTES || stats.size > exports.MAX_SOURCE_FILE_SIZE_BYTES) {
+            stats.size = Math.max(size, stats.size);
+            return { stats, bytes: null };
+        }
+        return { stats, bytes: Buffer.concat(chunks, size) };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+//# sourceMappingURL=file-limits.js.map

package/sensor/dist/file-limits.js.map

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

package/sensor/dist/graph/branch-guards.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Branch guards — the conditions under which a call site runs.
+ *
+ * An edge says `handlePress → openObjectDetail`. What a reader wants to know
+ * is that it happens **when `isCollected`** and **not while `isUploading`**:
+ *
+ *   if (isUploading) return            ← early-return guard: !isUploading
+ *   if (isCollected) {                 ← if: isCollected
+ *     openObjectDetail(item)           ← the call site
+ *
+ * This module derives that from the AST at query time. Given a file, its
+ * language and a call site (line, column), it walks from the innermost node at
+ * that position up to the enclosing function boundary and records every
+ * branch it passes through: `if` / `else` / `else if`, the arms of a ternary,
+ * `switch` cases, the right side of `&&` / `||`, a `catch`, and — at each
+ * statement block on the way — the early exits that precede the site
+ * (`if (x) return`, Swift `guard x else { return }`).
+ *
+ * Nothing is stored in the index. The viewer and `lattice_sensor_explore` already
+ * re-read source per request (drift checks, source windows, highlighting), the
+ * grammars are loaded in both processes, and a file parses in about a
+ * millisecond — so labels are computed where they are shown, from the source
+ * as it is now, and the index schema and the native kernel are untouched. A
+ * small LRU keeps the last few parsed trees so a Symbol view that asks about
+ * forty call sites in one file parses it once.
+ *
+ * Only what the AST states is reported. Loops are not conditions and are not
+ * listed; a condition that cannot be read (a language without rules here, a
+ * file that will not parse) yields no label rather than a wrong one.
+ */
+import type { Node as SyntaxNode } from 'web-tree-sitter';
+import type { Language } from '../types';
+export type GuardForm = 'if' | 'else' | 'ternary' | 'case' | 'guard' | 'and' | 'or' | 'catch';
+/** How an arm leaves the flow: back to the caller, or by an error. */
+export type GuardExit = 'return' | 'throw' | 'exit';
+export interface BranchGuard {
+    /** The condition's source, whitespace-collapsed, outer parens dropped, capped in length. */
+    text: string;
+    /** The site runs when the condition is FALSE (an else arm, an early-return guard, `||`). */
+    negated: boolean;
+    form: GuardForm;
+    /** Line of the condition (1-based). */
+    line: number;
+    /**
+     * Where the branching construct starts, `line:column` (1-based line, 0-based
+     * column) — the identity of the FORK rather than of the arm: the `if` an
+     * `if` guard and its `else` guard both come from, the `switch` every one of
+     * its cases comes from, the `try` a `catch` belongs to. Two guards with the
+     * same `branch` are arms of one decision, which is what a reader of the code
+     * in its own order needs and a joined condition string cannot say.
+     * '' when the walk could not place it.
+     */
+    branch: string;
+    /** How the arm the site is IN leaves, when it always does — `return`, `throw`. */
+    armExit?: GuardExit;
+    /** For an early exit (`form: 'guard'`), how the arm that was NOT taken leaves. */
+    exit?: GuardExit;
+}
+/** Languages with walk rules below. Others yield no guards (never a wrong one). */
+export declare function supportsBranchGuards(language: Language | string | undefined | null): boolean;
+/**
+ * The label a rail or a flow connector prints: the conditions in execution
+ * order, joined with `&&`, each negated one written as `!x`. Empty when the
+ * site is unconditional.
+ */
+export declare function guardLabel(guards: readonly BranchGuard[]): string;
+/**
+ * Files above this size are not parsed for labels. A 300 KB source file costs
+ * tens of milliseconds to parse, and a Symbol view is budgeted at 100 ms end
+ * to end; a call site in such a file simply shows no `when`.
+ */
+export declare const MAX_PARSE_BYTES: number;
+export interface CallSite {
+    line: number;
+    /** 0-based; null/undefined = the first non-blank column of the line. */
+    column?: number | null;
+    /**
+     * The callee's last segment, when known (`json` for `res.status(201).json(…)`):
+     * a position at the start of a chain sits on the innermost call, and the
+     * climb continues to the call that is actually this one.
+     */
+    callee?: string;
+}
+export declare function siteKey(site: CallSite): string;
+/**
+ * Guards for many call sites in one file, keyed by {@link siteKey}. The file
+ * is parsed once (and cached across requests until it changes on disk). A
+ * language without rules, or a file that cannot be read or parsed, yields an
+ * empty map.
+ */
+export declare function guardsForFile(absPath: string, language: Language, sites: readonly CallSite[]): Promise<Map<string, BranchGuard[]>>;
+/**
+ * Synchronous twin of {@link guardsForFile} for callers that cannot await
+ * (the explore text builder). It only serves languages whose grammar is
+ * ALREADY loaded — see {@link warmBranchGuardGrammars} — and yields an empty
+ * map otherwise, never a wrong label.
+ */
+export declare function guardsForFileSync(absPath: string, language: Language, sites: readonly CallSite[]): Map<string, BranchGuard[]>;
+/** The languages with rules here — what {@link warmBranchGuardGrammars} loads. */
+export declare const BRANCH_GUARD_LANGUAGES: readonly Language[];
+/**
+ * The arguments a call site passes, as written, abbreviated to what a reader
+ * scans for: a string literal whole (a storage key, a URL, a message), a name
+ * whole, an object as its keys (`{ email, password }`), an array as `[…]`, a
+ * function as `() => …`, a nested call as `f(…)`. The conditions say WHEN a
+ * step runs; this says WITH WHAT — `SecureStore.setItemAsync('userEmail',
+ * values.email)` is a different fact from `SecureStore.setItemAsync`.
+ *
+ * Keyed by {@link siteKey} like the guards, read from the same cached tree.
+ * A site that is not inside a call, or a language without rules, is absent.
+ */
+export declare function callArgumentsForFile(absPath: string, language: Language, sites: readonly CallSite[]): Promise<Map<string, string>>;
+/** {@link callArgumentsForFile} over source text — the test surface. */
+export declare function callArgumentsInSource(source: string, language: Language, line: number, column: number | null): Promise<string | null>;
+export declare function callArgumentsInTree(root: SyntaxNode, source: string, line: number, column: number | null): string | null;
+/** One call site, both halves: what is called, as written, and what it is passed. */
+export interface CallSiteText {
+    /**
+     * The callee as written, normalised: `prisma.article.findFirst`,
+     * `this.owners.findById().orElseThrow`, `res.status().json` — member
+     * chains kept whole (the index keeps only the last segment of a deep
+     * chain), argument lists emptied, `await`/`new` dropped, `?.` as `.`.
+     */
+    callee: string;
+    /** The argument list, abbreviated as {@link callArgumentsForFile} says. */
+    args: string;
+    /** The same arguments one by one — a registration site's middleware chain is `argList.slice(1, -1)`. */
+    argList: string[];
+    /** A status code written as an object property in the arguments (`{ status: 201 }`), which the abbreviation to keys would hide. */
+    status?: number;
+    /** Where the call starts and ends in the source (1-based lines) — the span another site may be written inside. */
+    span?: {
+        start: {
+            line: number;
+            column: number;
+        };
+        end: {
+            line: number;
+            column: number;
+        };
+    };
+    /**
+     * The call this one is written inside the arguments of — `res.json` for the
+     * `generateToken(…)` in `res.json({ token: generateToken(…) })` — normalised
+     * like `callee`. Absent at the top of a statement, and never reaching out of
+     * the function or block the call is in.
+     */
+    within?: string;
+}
+export declare function callSiteInTree(root: SyntaxNode, source: string, line: number, column: number | null, want?: string): CallSiteText | null;
+/** Both halves of every site, keyed by {@link siteKey}, from one cached tree. */
+export declare function callSitesForFile(absPath: string, language: Language, sites: readonly CallSite[]): Promise<Map<string, CallSiteText>>;
+/** {@link callSitesForFile} over source text — the test surface. */
+export declare function callSiteInSource(source: string, language: Language, line: number, column: number | null): Promise<CallSiteText | null>;
+/**
+ * What binds a call site to an event, when something does — the answer to
+ * "at what point does this run": the JSX attribute the site sits under
+ * (`onPress` of `<Button>`), the `on*` option it is written in (`onSubmit`
+ * of `useFormik({…})`), or the runs-later call it is an argument of
+ * (`useEffect`, `setTimeout`, `addListener('x')`, `.then`).
+ */
+export interface SiteTrigger {
+    /**
+     * `prop` / `option` / `callback` are read at the site (below). `request`
+     * (a route: `name` the verb, `of` the path), `decorator` (`@Process('email')`:
+     * `name` the decorator, `of` its literal argument) and `load` (a page's own
+     * load-time work) are set by the Steps endpoint from the registration
+     * site, not read from the tree.
+     */
+    kind: 'prop' | 'option' | 'callback' | 'request' | 'decorator' | 'load';
+    /** `onPress`, `onSubmit`, `useEffect`, `addListener`, `POST`, `Process`. */
+    name: string;
+    /** `Button` for a prop, `useFormik` for an option, the first string argument for a callback; null when unknown. */
+    of: string | null;
+    /** What runs before it fires — the middleware / guard chain at the registration site, in order. */
+    after?: string[];
+}
+export declare function triggersForFile(absPath: string, language: Language, sites: readonly CallSite[]): Promise<Map<string, SiteTrigger>>;
+/** {@link triggersForFile} over source text — the test surface. */
+export declare function triggerInSource(source: string, language: Language, line: number, column: number | null): Promise<SiteTrigger | null>;
+export declare function triggerInTree(root: SyntaxNode, source: string, line: number, column: number | null): SiteTrigger | null;
+/** Load the grammars {@link guardsForFileSync} needs; a no-op once loaded, never throws. */
+export declare function warmBranchGuardGrammars(only?: readonly Language[]): Promise<void>;
+/** Guards for one site in source text — the test seam; production reads files. */
+export declare function guardsInSource(source: string, language: Language, line: number, column?: number | null): Promise<BranchGuard[]>;
+/** Loops for one site in source text — the test seam; production reads files. */
+export declare function loopsInSource(source: string, language: Language, line: number, column?: number | null): Promise<SiteLoop[]>;
+/** A loop a site is written inside: its header as written, and where the loop starts. */
+export interface SiteLoop {
+    /** `const item of items`, `i = 0; i < n; i++`, `queue.length > 0` — the header, without its keyword. */
+    text: string;
+    /** `each` for a `for` / `foreach` / `for … in`, `while` for a `while` / `do` / `repeat`. */
+    kind: 'each' | 'while';
+    /** Where the loop starts, `line:column` — the same identity a guard's `branch` carries. */
+    branch: string;
+}
+/**
+ * The loops a site is written inside, outermost first — what tells a reading in
+ * the code's order that a run of calls happens once PER ITEM rather than once.
+ * The climb is the guards' climb (the same boundaries, the same transparent
+ * inline functions), so a callback's body is read in its own function and a
+ * `.forEach` body under the loop it is written in.
+ */
+export declare function loopsInTree(root: SyntaxNode, source: string, language: Language, line: number, column: number | null): SiteLoop[];
+/** Loops for many sites in one file, keyed by {@link siteKey}. */
+export declare function loopsForFile(absPath: string, language: Language, sites: readonly CallSite[]): Promise<Map<string, SiteLoop[]>>;
+/**
+ * The walk. `line` is 1-based, `column` 0-based (null → first non-blank).
+ * Returns the guards outermost first — execution order, the way a reader
+ * would list them.
+ */
+export declare function guardsInTree(root: SyntaxNode, source: string, language: Language, line: number, column: number | null): BranchGuard[];
+/**
+ * The decorators / annotations / attributes on the definition at a line, and
+ * on the class that holds it: `UseGuards(AuthGuard('jwt'))`,
+ * `PreAuthorize("hasRole('ADMIN')")`, `HttpPost("items")`, `Process('email')`.
+ * Text as written, without the `@` or the brackets, whitespace collapsed,
+ * capped. The index keeps no decorators, so they are read here at request
+ * time like the guards.
+ */
+/**
+ * A `return` a definition makes itself — never one inside a lambda, a local
+ * function or a nested / anonymous class — with what it returns, as written.
+ * `value` is the string a same-class constant holds, when the expression is
+ * a bare name that declares one: Spring MVC handlers return
+ * `VIEWS_OWNER_CREATE_OR_UPDATE_FORM`, and the view is its value.
+ */
+export interface ReturnSite {
+    line: number;
+    column: number;
+    expression: string;
+    value?: string;
+}
+export declare function returnsForFile(absPath: string, language: Language, line: number): Promise<ReturnSite[]>;
+/** {@link returnsForFile} over source text — the test surface. */
+export declare function returnsInSource(source: string, language: Language, line: number): Promise<ReturnSite[]>;
+export declare function returnsInTree(root: SyntaxNode, line: number): ReturnSite[];
+export interface DefinitionDecorators {
+    own: string[];
+    /** The enclosing class's, when the definition is a member. */
+    class: string[];
+}
+export declare function decoratorsForFile(absPath: string, language: Language, lines: readonly number[]): Promise<Map<number, DefinitionDecorators>>;
+/** {@link decoratorsForFile} over source text — the test surface. */
+export declare function decoratorsInSource(source: string, language: Language, line: number): Promise<DefinitionDecorators | null>;
+export declare function decoratorsInTree(root: SyntaxNode, source: string, line: number): DefinitionDecorators | null;
+/**
+ * The declared types of a class's members, read from the tree: the
+ * constructor's parameter properties (`private readonly usersService:
+ * UsersService`), its fields (`private final OwnerRepository owners`,
+ * `val owners: OwnerRepository`, `private readonly IRepo _repo`), its typed
+ * properties. The index keeps no type for these, and a member call the
+ * extractor kept only the last segment of (`this.usersService.findByEmail`
+ * → `findByEmail`) resolves by name alone; the declared type is what says
+ * where it really goes, and whether it leaves the index.
+ *
+ * Keyed by member name, the type as written without generics'
+ * arguments (`Repository<Cat>` → `Repository<Cat>` is kept whole; callers
+ * strip what they need).
+ */
+export declare function memberTypesForFile(absPath: string, language: Language, line: number): Promise<Map<string, string>>;
+/** {@link memberTypesForFile} over source text — the test surface. */
+export declare function memberTypesInSource(source: string, language: Language, line: number): Promise<Map<string, string>>;
+export declare function memberTypesInTree(root: SyntaxNode, source: string, line: number): Map<string, string>;
+//# sourceMappingURL=branch-guards.d.ts.map

package/sensor/dist/graph/branch-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-guards.d.ts","sourceRoot":"","sources":["../../src/graph/branch-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EAAE,IAAI,IAAI,UAAU,EAAQ,MAAM,iBAAiB,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAOzC,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC;AAE9F,sEAAsE;AACtE,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;AAEpD,MAAM,WAAW,WAAW;IAC1B,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAC;IACb,4FAA4F;IAC5F,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,SAAS,CAAC;IAChB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,kFAAkF;IAClF,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAOD,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAE5F;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAEjE;AAgFD;;;;GAIG;AACH,eAAO,MAAM,eAAe,QAAa,CAAC;AAsD1C,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAE9C;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,SAAS,QAAQ,EAAE,GACzB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC,CAWrC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,SAAS,QAAQ,EAAE,GACzB,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,CA+B5B;AAED,kFAAkF;AAClF,eAAO,MAAM,sBAAsB,EAAE,SAAS,QAAQ,EAcrD,CAAC;AA8DF;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,SAAS,QAAQ,EAAE,GACzB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAY9B;AAED,wEAAwE;AACxE,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,IAAI,GACpB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASxB;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,IAAI,GACpB,MAAM,GAAG,IAAI,CAEf;AAED,qFAAqF;AACrF,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,wGAAwG;IACxG,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,mIAAmI;IACnI,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kHAAkH;IAClH,IAAI,CAAC,EAAE;QAAE,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,GAAG,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;IAC1F;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAiED,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CA8BxI;AAsDD,iFAAiF;AACjF,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,SAAS,QAAQ,EAAE,GACzB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAYpC;AAED,oEAAoE;AACpE,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,IAAI,GACpB,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAS9B;AAoGD;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC;IACxE,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,mHAAmH;IACnH,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,mGAAmG;IACnG,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AA6BD,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,SAAS,QAAQ,EAAE,GACzB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAYnC;AAED,mEAAmE;AACnE,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,IAAI,GACpB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAS7B;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,WAAW,GAAG,IAAI,CAwDvH;AAiCD,4FAA4F;AAC5F,wBAAsB,uBAAuB,CAAC,IAAI,CAAC,EAAE,SAAS,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAQvF;AAED,kFAAkF;AAClF,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,MAAM,GAAG,IAAW,GAC3B,OAAO,CAAC,WAAW,EAAE,CAAC,CASxB;AAED,iFAAiF;AACjF,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,GAAG,IAAW,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CASvI;AAED,yFAAyF;AACzF,MAAM,WAAW,QAAQ;IACvB,wGAAwG;IACxG,IAAI,EAAE,MAAM,CAAC;IACb,4FAA4F;IAC5F,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,2FAA2F;IAC3F,MAAM,EAAE,MAAM,CAAC;CAChB;AAmBD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,QAAQ,EAAE,CAiCjI;AAED,kEAAkE;AAClE,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,CAUpI;AAgBD;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,IAAI,GACpB,WAAW,EAAE,CA0Cf;AAy7BD;;;;;;;GAOG;AACH;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAkBD,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAK7G;AAED,kEAAkE;AAClE,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAS7G;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,CA6C1E;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,8DAA8D;IAC9D,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAoBD,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAW5C;AAED,qEAAqE;AACrE,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAS/H;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAqB5G;AAuCD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAMxH;AAED,sEAAsE;AACtE,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CASxH;AAID,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CA+ErG"}