@facilis.dev/analyze 0.0.0-stage → 0.1.0

package/dist/passes/screen-preview.js

@@ -0,0 +1,159 @@
+/**
+ * Bounded static page structure for the page inspector: JSX sections nested one inside the
+ * other, with component identifiers resolved through the module graph.
+ *
+ * This is not a rendering. It deliberately stops at explicit limits (depth, node count,
+ * component cycles) and marks conditional/map branches as dynamic; anything outside the
+ * bounded subset is omitted rather than guessed.
+ */
+import { asNode, nodeArray, unwrapExpression } from "../ast/node.js";
+import { elementName, isSectionIntrinsic, jsxAttributeValue, jsxAttributes, jsxChildren, jsxElementValue, } from "./jsx.js";
+import { canExpand, componentExpression, firstComponentName, lineRef, resolveComponent, returnedExpression, } from "./screen-components.js";
+const MAX_NODES = 60;
+const MAX_DEPTH = 4;
+/** Build the bounded static structure for one page. */
+export function buildPagePreview(input) {
+    const { graph, pagePath } = input;
+    const nodes = [];
+    const active = new Set();
+    let truncated = false;
+    const addNode = (parentId, name, kind, file, source, dynamic) => {
+        if (nodes.length >= MAX_NODES) {
+            truncated = true;
+            return null;
+        }
+        const id = "p" + nodes.length;
+        nodes.push({ id, parentId, name, kind, file, source, dynamic });
+        return id;
+    };
+    const appendChildren = (node, originFile, parentId, depth, dynamic, outletChild) => {
+        for (const child of jsxChildren(node)) {
+            if (child.type === "JSXExpressionContainer") {
+                appendExpression(asNode(child.expression), originFile, parentId, depth, dynamic, outletChild);
+            }
+            else if (child.type === "JSXElement" || child.type === "JSXFragment") {
+                appendJsx(child, originFile, parentId, depth, dynamic, outletChild);
+            }
+        }
+    };
+    const appendJsx = (node, originFile, parentId, depth, dynamic, outletChild) => {
+        if (node.type === "JSXFragment") {
+            appendChildren(node, originFile, parentId, depth, dynamic, outletChild);
+            return;
+        }
+        const name = elementName(node);
+        if (name === null)
+            return;
+        if (name === "Outlet") {
+            if (outletChild !== null)
+                appendRoot(outletChild, parentId, depth, dynamic);
+            else
+                addNode(parentId, "Outlet", "slot", null, lineRef(graph, originFile, node), dynamic);
+            return;
+        }
+        const intrinsic = name[0] !== undefined && name[0] === name[0].toLowerCase();
+        if (intrinsic) {
+            if (!isSectionIntrinsic(name)) {
+                appendChildren(node, originFile, parentId, depth, dynamic, outletChild);
+                return;
+            }
+            const id = addNode(parentId, name, "intrinsic", null, lineRef(graph, originFile, node), dynamic);
+            if (id !== null)
+                appendChildren(node, originFile, id, depth + 1, dynamic, outletChild);
+            return;
+        }
+        const ref = resolveComponent(graph, originFile, name);
+        const id = addNode(parentId, name, "component", ref?.file ?? null, lineRef(graph, originFile, node), dynamic);
+        if (id === null)
+            return;
+        // JSX-valued props are real sections too (AuthShell footer, Page actions, ...).
+        for (const attribute of jsxAttributes(node)) {
+            if (attribute.type !== "JSXAttribute")
+                continue;
+            const value = jsxElementValue(jsxAttributeValue(attribute));
+            if (value === undefined)
+                continue;
+            const attributeName = asNode(attribute.name);
+            const slotName = attributeName !== undefined && typeof attributeName.name === "string"
+                ? attributeName.name
+                : "slot";
+            const slotId = addNode(id, slotName, "slot", null, lineRef(graph, originFile, node), dynamic);
+            if (slotId !== null)
+                appendJsx(value, originFile, slotId, depth + 1, dynamic, null);
+        }
+        // The component's own JSX children are its content slot; keep them visible even when the
+        // component definition is expanded (its `{children}` expression is not JSX we can splice).
+        appendChildren(node, originFile, id, depth + 1, dynamic, null);
+        const expand = ref !== null && canExpand(ref.file) && depth < MAX_DEPTH;
+        if (!expand)
+            return;
+        const key = ref.file + "#" + ref.name;
+        const expression = active.has(key) ? undefined : componentExpression(graph, ref.file, ref.name);
+        if (expression === undefined)
+            return;
+        active.add(key);
+        appendExpression(expression, ref.file, id, depth + 1, dynamic, outletChild);
+        active.delete(key);
+    };
+    const appendExpression = (node, originFile, parentId, depth, dynamic, outletChild) => {
+        if (node === undefined)
+            return;
+        const expression = unwrapExpression(node) ?? node;
+        if (expression.type === "JSXElement" || expression.type === "JSXFragment") {
+            appendJsx(expression, originFile, parentId, depth, dynamic, outletChild);
+            return;
+        }
+        if (expression.type === "ConditionalExpression") {
+            appendExpression(asNode(expression.consequent), originFile, parentId, depth, true, outletChild);
+            appendExpression(asNode(expression.alternate), originFile, parentId, depth, true, outletChild);
+            return;
+        }
+        if (expression.type === "LogicalExpression") {
+            appendExpression(asNode(expression.right), originFile, parentId, depth, true, outletChild);
+            return;
+        }
+        if (expression.type === "ArrayExpression") {
+            for (const element of nodeArray(expression, "elements")) {
+                appendExpression(element, originFile, parentId, depth, dynamic, outletChild);
+            }
+            return;
+        }
+        if (expression.type === "CallExpression") {
+            const callee = asNode(expression.callee);
+            const property = callee === undefined || callee.type !== "MemberExpression"
+                ? undefined
+                : asNode(callee.property);
+            if (property !== undefined && typeof property.name === "string" && property.name === "map") {
+                const callback = nodeArray(expression, "arguments")[0];
+                const body = callback === undefined ? undefined : asNode(callback.body);
+                const returned = body === undefined
+                    ? undefined
+                    : body.type === "BlockStatement"
+                        ? returnedExpression(body)
+                        : body;
+                appendExpression(returned, originFile, parentId, depth, true, outletChild);
+            }
+        }
+    };
+    const appendRoot = (root, parentId, depth, dynamic) => {
+        if (root === null)
+            return;
+        appendExpression(root.element, root.originFile, parentId, depth, dynamic, root.outletChild);
+    };
+    if (input.root !== null) {
+        appendRoot(input.root, null, 0, false);
+    }
+    else if (input.pageName !== null) {
+        const file = graph.file(pagePath);
+        if (file !== undefined) {
+            const id = addNode(null, input.pageName, "component", pagePath, lineRef(graph, pagePath, file.program), false);
+            const expression = id === null ? undefined : componentExpression(graph, pagePath, input.pageName);
+            if (id !== null && expression !== undefined)
+                appendExpression(expression, pagePath, id, 1, false, null);
+        }
+    }
+    return { routePaths: input.routePaths, nodes, truncated };
+}
+export function pageComponentName(graph, pagePath) {
+    return firstComponentName(graph, pagePath);
+}

package/dist/passes/screens.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Static screen facts for the project graph: route-table paths, a bounded component preview
+ * per page and explicit page-to-page navigation links.
+ *
+ * Only explicit client navigation counts (react-router `Link`, `NavLink`, `useNavigate`).
+ * Guards and `<Navigate>` redirects are intentionally out of scope for the graph: they are
+ * conditional control flow, not a link the page declares.
+ */
+import type { ModuleGraph } from "../module-graph.js";
+import type { PageFact, ScreenFacts } from "../types.js";
+/** Build route paths, page previews and explicit page links from the project snapshot. */
+export declare function buildScreens(graph: ModuleGraph, pages: readonly PageFact[]): ScreenFacts;

package/dist/passes/screens.js

@@ -0,0 +1,278 @@
+/**
+ * Static screen facts for the project graph: route-table paths, a bounded component preview
+ * per page and explicit page-to-page navigation links.
+ *
+ * Only explicit client navigation counts (react-router `Link`, `NavLink`, `useNavigate`).
+ * Guards and `<Navigate>` redirects are intentionally out of scope for the graph: they are
+ * conditional control flow, not a link the page declares.
+ */
+import { asNode, nodeArray, unwrapExpression } from "../ast/node.js";
+import { walk } from "../ast/walk.js";
+import { evaluateStatic } from "../static-eval.js";
+import { elementName, jsxAttribute, jsxAttributeValue } from "./jsx.js";
+import { buildRouteTable } from "./route-table.js";
+import { buildPagePreview, pageComponentName } from "./screen-preview.js";
+function resolvePage(graph, originFile, name) {
+    const local = name.includes(".") ? name.slice(0, name.indexOf(".")) : name;
+    const binding = graph.resolveBinding(originFile, local);
+    if (binding === null)
+        return null;
+    const file = graph.file(binding.file);
+    return file !== undefined && file.path.startsWith("src/pages/") ? file.path : null;
+}
+/** First component in a route element that resolves to a file under src/pages/. */
+function pagePathOfElement(graph, originFile, element) {
+    let found = null;
+    walk(element, (node) => {
+        if (found !== null || node.type !== "JSXElement")
+            return;
+        const name = elementName(node);
+        if (name === null || name[0] === name[0]?.toLowerCase())
+            return;
+        found = resolvePage(graph, originFile, name);
+    });
+    return found;
+}
+function appFileOf(graph) {
+    const direct = graph.file("src/app.tsx");
+    if (direct !== undefined)
+        return direct;
+    for (const file of graph.files.values()) {
+        if (!file.path.startsWith("src/"))
+            continue;
+        if (buildRouteTable(graph, file).length > 0)
+            return file;
+    }
+    return null;
+}
+/** Only page/layout/app components own page links; providers and guards are shared chrome. */
+function isLinkSourceFile(file) {
+    if (file.startsWith("src/components/ui/"))
+        return false;
+    return (file.startsWith("src/pages/") ||
+        file.startsWith("src/layouts/") ||
+        file.startsWith("src/components/"));
+}
+function routesByPage(graph, appFile, entries) {
+    const byPage = new Map();
+    entries.forEach((entry, index) => {
+        if (entry.element === null)
+            return;
+        const pagePath = pagePathOfElement(graph, appFile.path, entry.element);
+        if (pagePath === null)
+            return;
+        const list = byPage.get(pagePath) ?? [];
+        list.push({ index, path: entry.path });
+        byPage.set(pagePath, list);
+    });
+    return byPage;
+}
+function previewRoot(entries, pageEntry, appPath) {
+    let root = null;
+    let current = pageEntry;
+    while (current !== null) {
+        const entry = entries[current];
+        if (entry === undefined)
+            break;
+        if (entry.element !== null) {
+            root = { element: entry.element, originFile: appPath, outletChild: root };
+        }
+        current = entry.parentIndex;
+    }
+    return root;
+}
+function pathSegments(path) {
+    return path.split("/").filter(Boolean);
+}
+function pathMatches(pattern, target) {
+    if (pattern === target)
+        return true;
+    if (pattern === "*")
+        return false;
+    const patternParts = pathSegments(pattern);
+    const targetParts = pathSegments(target);
+    if (patternParts.length !== targetParts.length)
+        return false;
+    return patternParts.every((part, index) => {
+        if (part === "*")
+            return true;
+        if (part.startsWith(":") || (part.startsWith("{") && part.endsWith("}")))
+            return true;
+        return part === targetParts[index];
+    });
+}
+function targetPathOf(node, graph, file) {
+    if (node === undefined)
+        return null;
+    const evaluated = evaluateStatic(node, { graph, file: file.path });
+    if (!evaluated.ok)
+        return null;
+    const value = evaluated.value;
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "object" && value !== null && "pathname" in value) {
+        const pathname = value.pathname;
+        return typeof pathname === "string" ? pathname : null;
+    }
+    return null;
+}
+function stripLocation(path) {
+    const cut = path.search(/[?#]/);
+    return cut === -1 ? path : path.slice(0, cut);
+}
+function linkBindings(file) {
+    const links = new Map();
+    const useNavigate = new Set();
+    for (const imported of file.module.imports) {
+        if (imported.specifier !== "react-router-dom")
+            continue;
+        if (imported.imported === "Link")
+            links.set(imported.local, "link");
+        if (imported.imported === "NavLink")
+            links.set(imported.local, "navlink");
+        if (imported.imported === "useNavigate")
+            useNavigate.add(imported.local);
+    }
+    const navigate = new Set();
+    if (useNavigate.size === 0)
+        return { links, navigate };
+    walk(file.program, (node) => {
+        if (node.type !== "VariableDeclarator")
+            return;
+        const id = asNode(node.id);
+        const init = unwrapExpression(asNode(node.init));
+        if (id === undefined || typeof id.name !== "string" || init === undefined)
+            return;
+        if (init.type !== "CallExpression")
+            return;
+        const callee = unwrapExpression(init.callee);
+        if (callee?.type === "Identifier" &&
+            useNavigate.has(typeof callee.name === "string" ? callee.name : "")) {
+            navigate.add(id.name);
+        }
+    });
+    return { links, navigate };
+}
+function linksInFile(graph, file) {
+    const bindings = linkBindings(file);
+    if (bindings.links.size === 0 && bindings.navigate.size === 0)
+        return [];
+    const found = [];
+    walk(file.program, (node) => {
+        if (node.type === "JSXElement") {
+            const name = elementName(node);
+            const kind = name === null ? undefined : bindings.links.get(name);
+            if (kind === undefined)
+                return;
+            const value = jsxAttributeValue(jsxAttribute(node, "to"));
+            const to = targetPathOf(value, graph, file);
+            if (to !== null) {
+                found.push({ to, kind, source: lineOf(file, node) });
+            }
+            return;
+        }
+        if (node.type !== "CallExpression")
+            return;
+        const callee = unwrapExpression(node.callee);
+        if (callee?.type !== "Identifier" || typeof callee.name !== "string")
+            return;
+        if (!bindings.navigate.has(callee.name))
+            return;
+        const to = targetPathOf(nodeArray(node, "arguments")[0], graph, file);
+        if (to !== null)
+            found.push({ to, kind: "navigate", source: lineOf(file, node) });
+    });
+    return found;
+}
+function lineOf(file, node) {
+    const offset = typeof node.start === "number" ? node.start : 0;
+    let line = 1;
+    for (let index = 0; index < offset && index < file.source.length; index += 1) {
+        if (file.source.charCodeAt(index) === 10)
+            line += 1;
+    }
+    return { file: file.path, line };
+}
+/** Build route paths, page previews and explicit page links from the project snapshot. */
+export function buildScreens(graph, pages) {
+    const appFile = appFileOf(graph);
+    const entries = appFile === null ? [] : buildRouteTable(graph, appFile);
+    const byPage = appFile === null ? new Map() : routesByPage(graph, appFile, entries);
+    const pathToPage = new Map();
+    for (const entry of entries) {
+        if (entry.element === null || appFile === null)
+            continue;
+        const pagePath = pagePathOfElement(graph, appFile.path, entry.element);
+        if (pagePath !== null && !pathToPage.has(entry.path))
+            pathToPage.set(entry.path, pagePath);
+    }
+    const resolveTarget = (target) => {
+        const path = stripLocation(target);
+        if (!path.startsWith("/") && path !== "*")
+            return null;
+        const exact = pathToPage.get(path);
+        if (exact !== undefined)
+            return exact;
+        for (const entry of entries) {
+            if (!pathMatches(entry.path, path))
+                continue;
+            if (entry.element === null || appFile === null)
+                continue;
+            const pagePath = pagePathOfElement(graph, appFile.path, entry.element);
+            if (pagePath !== null)
+                return pagePath;
+        }
+        return null;
+    };
+    const previews = {};
+    for (const page of pages) {
+        if (page.kind !== "page")
+            continue;
+        const pageRoutes = byPage.get(page.path) ?? [];
+        const first = pageRoutes[0];
+        const root = appFile === null || first === undefined
+            ? null
+            : previewRoot(entries, first.index, appFile.path);
+        previews[page.path] = buildPagePreview({
+            graph,
+            pagePath: page.path,
+            root,
+            pageName: root === null ? pageComponentName(graph, page.path) : null,
+            routePaths: pageRoutes.map((entry) => entry.path),
+        });
+    }
+    const links = [];
+    const seen = new Set();
+    for (const page of pages) {
+        if (page.kind !== "page")
+            continue;
+        const preview = previews[page.path];
+        const files = new Set([page.path]);
+        for (const node of preview?.nodes ?? []) {
+            if (node.file !== null && isLinkSourceFile(node.file))
+                files.add(node.file);
+        }
+        for (const filePath of files) {
+            const file = graph.file(filePath);
+            if (file === undefined)
+                continue;
+            for (const link of linksInFile(graph, file)) {
+                const target = resolveTarget(link.to);
+                if (target === null || target === page.path)
+                    continue;
+                const key = page.path + "\u0000" + target + "\u0000" + link.kind + "\u0000" + link.to;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                links.push({
+                    from: page.path,
+                    to: target,
+                    toPath: stripLocation(link.to),
+                    kind: link.kind,
+                    source: link.source,
+                });
+            }
+        }
+    }
+    return { previews, links };
+}

package/dist/passes/static-read.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Helpers shared by the analyzer passes: the static object reader (§4 of the AST DSL
+ * contract) and deterministic diagnostic ordering.
+ *
+ * The reader is deliberately partial: every property is evaluated on its own so one computed
+ * value cannot hide its siblings. It never executes project code and it never defaults an
+ * unreadable value - the caller decides whether the unknown is a security error.
+ */
+import { type AstNode } from "../ast/node.js";
+import type { ProjectFile } from "../module-graph.js";
+import { type StaticContext } from "../static-eval.js";
+import type { Diagnostic, SourceRef, UnknownFact } from "../types.js";
+export interface StaticField {
+    readonly value: unknown;
+    readonly ok: boolean;
+    readonly node: AstNode | undefined;
+    /** Why the value is not static; null when ok. */
+    readonly reason: string | null;
+}
+export interface StaticObject {
+    readonly fields: ReadonlyMap<string, StaticField>;
+    readonly unknown: readonly UnknownFact[];
+}
+export interface StaticReadOptions {
+    /** Diagnostic/unknown code recorded for constructs outside the static subset. */
+    readonly code: string;
+    /** Whether a field that fails to evaluate is reported (sections re-read for detail). */
+    readonly report: boolean;
+}
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function projectPath(root: string, path: string): string;
+/** Project-relative path with the graph root stripped (the opposite of projectPath). */
+export declare function relativePath(root: string, path: string): string;
+export declare function refOf(context: StaticContext, node: AstNode | undefined): SourceRef;
+/** Partial, non-executing reader for object literals in the static subset. */
+export declare function readStaticObject(node: AstNode | undefined, context: StaticContext, options: StaticReadOptions): StaticObject;
+/**
+ * The default export, unwrapped and resolved through a same-file const or a
+ * `export { handler as default }` statement.
+ */
+export declare function defaultExportExpression(file: ProjectFile): AstNode | undefined;
+/** A top-level function/class declaration by name (localInitializer covers variables only). */
+export declare function findDeclaration(program: AstNode, name: string): AstNode | undefined;
+/** True when the module declares the name itself: a local shadow invalidates an import. */
+export declare function isLocallyDeclared(file: ProjectFile, name: string): boolean;
+/** Stable diagnostic order (file, line, code, message) so snapshots never flap. */
+export declare function sortDiagnostics(diagnostics: readonly Diagnostic[]): Diagnostic[];

package/dist/passes/static-read.js

@@ -0,0 +1,151 @@
+/**
+ * Helpers shared by the analyzer passes: the static object reader (§4 of the AST DSL
+ * contract) and deterministic diagnostic ordering.
+ *
+ * The reader is deliberately partial: every property is evaluated on its own so one computed
+ * value cannot hide its siblings. It never executes project code and it never defaults an
+ * unreadable value - the caller decides whether the unknown is a security error.
+ */
+import { identifierName, objectEntries, propertyName, propertyValue, unwrapExpression, } from "../ast/node.js";
+import { declarationNames, defaultExportDeclaration, localInitializer } from "../module-info.js";
+import { sourceRef } from "../source.js";
+import { evaluateStatic } from "../static-eval.js";
+const MAX_RESOLVE_DEPTH = 8;
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function projectPath(root, path) {
+    return root.length === 0 ? path : root + "/" + path;
+}
+/** Project-relative path with the graph root stripped (the opposite of projectPath). */
+export function relativePath(root, path) {
+    return root.length === 0 || !path.startsWith(root + "/") ? path : path.slice(root.length + 1);
+}
+export function refOf(context, node) {
+    const file = context.graph.file(context.file);
+    const offset = node !== undefined && typeof node.start === "number" ? node.start : 0;
+    return sourceRef(context.file, file?.source ?? "", offset);
+}
+function objectLiteral(node, context, depth = 0) {
+    if (node === undefined || depth > MAX_RESOLVE_DEPTH)
+        return undefined;
+    const unwrapped = unwrapExpression(node);
+    if (unwrapped === undefined)
+        return undefined;
+    if (unwrapped.type === "ObjectExpression")
+        return unwrapped;
+    const file = context.graph.file(context.file);
+    const name = identifierName(unwrapped);
+    if (file === undefined || name === undefined)
+        return undefined;
+    return objectLiteral(localInitializer(file.program, name), context, depth + 1);
+}
+/** Partial, non-executing reader for object literals in the static subset. */
+export function readStaticObject(node, context, options) {
+    const fields = new Map();
+    const unknown = [];
+    if (node === undefined)
+        return { fields, unknown };
+    const record = (reason, at, structural) => {
+        if (structural || options.report) {
+            unknown.push({ code: options.code, reason, source: refOf(context, at) });
+        }
+    };
+    const literal = objectLiteral(node, context);
+    if (literal !== undefined) {
+        for (const entry of objectEntries(literal)) {
+            if (entry.type === "SpreadElement") {
+                record("spread in an object literal cannot be read statically", entry, true);
+                continue;
+            }
+            const key = propertyName(entry);
+            if (key === undefined) {
+                record("computed object key cannot be read statically", entry, true);
+                continue;
+            }
+            const valueNode = propertyValue(entry);
+            const evaluated = evaluateStatic(valueNode, context);
+            if (evaluated.ok) {
+                fields.set(key, { value: evaluated.value, ok: true, node: valueNode, reason: null });
+            }
+            else {
+                fields.set(key, { value: undefined, ok: false, node: valueNode, reason: evaluated.reason });
+                record(evaluated.reason, valueNode ?? entry, false);
+            }
+        }
+        return { fields, unknown };
+    }
+    const evaluated = evaluateStatic(node, context);
+    if (evaluated.ok && isRecord(evaluated.value)) {
+        for (const [key, value] of Object.entries(evaluated.value)) {
+            fields.set(key, { value, ok: true, node: undefined, reason: null });
+        }
+        return { fields, unknown };
+    }
+    record(evaluated.ok ? "value is not an object" : evaluated.reason, node, true);
+    return { fields, unknown };
+}
+/**
+ * The default export, unwrapped and resolved through a same-file const or a
+ * `export { handler as default }` statement.
+ */
+export function defaultExportExpression(file) {
+    const declaration = defaultExportDeclaration(file.program);
+    if (declaration !== undefined) {
+        const unwrapped = unwrapExpression(declaration);
+        const name = unwrapped?.type === "Identifier" ? identifierName(unwrapped) : undefined;
+        return name === undefined ? unwrapped : unwrapExpression(localInitializer(file.program, name));
+    }
+    const entry = file.module.exports.find((item) => item.exported === "default" && item.local !== null);
+    if (entry === undefined || entry.local === null)
+        return undefined;
+    return unwrapExpression(localInitializer(file.program, entry.local));
+}
+/** A top-level function/class declaration by name (localInitializer covers variables only). */
+export function findDeclaration(program, name) {
+    for (const raw of Array.isArray(program.body) ? program.body : []) {
+        if (typeof raw !== "object" || raw === null)
+            continue;
+        const statement = raw;
+        const declaration = statement.type === "ExportNamedDeclaration" &&
+            statement.declaration !== null &&
+            typeof statement.declaration === "object"
+            ? statement.declaration
+            : statement;
+        if ((declaration.type === "FunctionDeclaration" || declaration.type === "ClassDeclaration") &&
+            identifierName(declaration.id) === name) {
+            return declaration;
+        }
+    }
+    return undefined;
+}
+/** True when the module declares the name itself: a local shadow invalidates an import. */
+export function isLocallyDeclared(file, name) {
+    const body = Array.isArray(file.program.body) ? file.program.body : [];
+    for (const raw of body) {
+        if (typeof raw !== "object" || raw === null)
+            continue;
+        const statement = raw;
+        const declaration = statement.type === "ExportNamedDeclaration" &&
+            statement.declaration !== null &&
+            typeof statement.declaration === "object"
+            ? statement.declaration
+            : statement;
+        if (declarationNames(declaration).includes(name))
+            return true;
+    }
+    return false;
+}
+/** Stable diagnostic order (file, line, code, message) so snapshots never flap. */
+export function sortDiagnostics(diagnostics) {
+    return [...diagnostics].toSorted((left, right) => {
+        const fileOrder = (left.source?.file ?? "").localeCompare(right.source?.file ?? "");
+        if (fileOrder !== 0)
+            return fileOrder;
+        const lineOrder = (left.source?.line ?? 0) - (right.source?.line ?? 0);
+        if (lineOrder !== 0)
+            return lineOrder;
+        const codeOrder = left.code.localeCompare(right.code);
+        return codeOrder !== 0 ? codeOrder : left.message.localeCompare(right.message);
+    });
+}

package/dist/passes/views.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `db/views/**` -> ViewFacts (D-157, SPEC §11.2).
+ *
+ * A view is declared one per file with `defineView({ name, columns, query, tables?,
+ * permission? })` from @facilis.dev/db (D-097/D-098). The route-relations pass resolves a view
+ * object used in `from(...)` to this fact, so a route declares the view's SQL name in
+ * `dbTables` instead of its base tables. D-160 adds the view nodes and their edges to the
+ * project graph; this pass stays facts-only.
+ *
+ * The declaration is read through the bounded static subset; an unreadable name/tables/
+ * permission is an explicit unknown, never a guessed value.
+ */
+import type { ModuleGraph } from "../module-graph.js";
+import type { Diagnostic, ViewFact } from "../types.js";
+export interface ViewScan {
+    readonly views: readonly ViewFact[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+/** Read `db/views/**` into view facts. */
+export declare function buildViewFacts(graph: ModuleGraph): ViewScan;