@facilis.dev/analyze 0.0.0-stage → 0.1.1

package/dist/passes/schema-relations.d.ts

@@ -0,0 +1,8 @@
+import type { ModuleGraph, ProjectFile } from "../module-graph.js";
+import type { Diagnostic, RelationFact } from "../types.js";
+import { type TableLookup } from "./schema-foreign-keys.js";
+export interface RelationScan {
+    readonly relations: readonly RelationFact[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+export declare function buildRelationFacts(graph: ModuleGraph, files: readonly ProjectFile[], lookup: TableLookup): RelationScan;

package/dist/passes/schema-relations.js

@@ -0,0 +1,182 @@
+import { callArguments, identifierName, memberName, nodeArray, objectEntries, propertyName, propertyValue, unwrapExpression, } from "../ast/node.js";
+import { callbackExpression, createDslResolver, nodeRef, schemaDiagnostics, schemaUnknown, topLevelDeclarators, } from "./schema-dsl.js";
+import { resolveTableBinding } from "./schema-foreign-keys.js";
+/** Map the callback's destructured `one`/`many` helpers to their local names. */
+function helperBindings(callback) {
+    const fn = unwrapExpression(callback);
+    if (fn === undefined)
+        return null;
+    if (fn.type !== "ArrowFunctionExpression" && fn.type !== "FunctionExpression")
+        return null;
+    const param = unwrapExpression(nodeArray(fn, "params")[0]);
+    if (param?.type !== "ObjectPattern")
+        return null;
+    const one = new Set();
+    const many = new Set();
+    for (const property of objectEntries(param)) {
+        if (property.type === "SpreadElement")
+            continue;
+        const key = propertyName(property);
+        const local = identifierName(propertyValue(property));
+        if (local === undefined)
+            continue;
+        if (key === "one")
+            one.add(local);
+        if (key === "many")
+            many.add(local);
+    }
+    return { one, many };
+}
+function readColumnList(options, file, unknowns) {
+    const empty = { fields: [], references: [] };
+    if (options === undefined)
+        return empty;
+    const node = unwrapExpression(options);
+    if (node?.type !== "ObjectExpression") {
+        unknowns.push(schemaUnknown("relation options are not an object literal", nodeRef(file, options)));
+        return empty;
+    }
+    const readList = (key) => {
+        const property = objectEntries(node).find((entry) => propertyName(entry) === key);
+        if (property === undefined)
+            return [];
+        const value = unwrapExpression(propertyValue(property));
+        if (value?.type !== "ArrayExpression") {
+            unknowns.push(schemaUnknown("relation " + key + " is not an array literal", nodeRef(file, property)));
+            return [];
+        }
+        const columns = [];
+        for (const element of nodeArray(value, "elements")) {
+            const item = unwrapExpression(element);
+            const name = item?.type === "MemberExpression" ? memberName(item) : identifierName(item);
+            if (name === undefined) {
+                unknowns.push(schemaUnknown("relation " + key + " entry is not a column reference", nodeRef(file, item)));
+                continue;
+            }
+            columns.push(name);
+        }
+        return columns;
+    };
+    return { fields: readList("fields"), references: readList("references") };
+}
+function readRelationEntry(input) {
+    const { entry, from, graph, file, lookup, helpers } = input;
+    const unknowns = [];
+    const value = unwrapExpression(propertyValue(entry));
+    const source = nodeRef(file, entry);
+    if (value?.type !== "CallExpression") {
+        return {
+            relation: null,
+            diagnostics: schemaDiagnostics([
+                schemaUnknown("relations() entry is not a one()/many() call", source),
+            ]),
+        };
+    }
+    const calleeLocal = identifierName(unwrapExpression(value.callee));
+    const cardinality = calleeLocal !== undefined && helpers.one.has(calleeLocal)
+        ? "one"
+        : calleeLocal !== undefined && helpers.many.has(calleeLocal)
+            ? "many"
+            : null;
+    if (cardinality === null) {
+        return {
+            relation: null,
+            diagnostics: schemaDiagnostics([
+                schemaUnknown("relations() entry is not a one()/many() call", source),
+            ]),
+        };
+    }
+    const args = callArguments(value);
+    const targetLocal = identifierName(unwrapExpression(args[0]));
+    const targetTable = targetLocal === undefined ? null : resolveTableBinding(graph, file.path, targetLocal, lookup);
+    if (targetTable === null) {
+        unknowns.push(schemaUnknown("relation target table is not resolvable statically", source));
+    }
+    const columns = readColumnList(args[1], file, unknowns);
+    const relation = {
+        from,
+        to: targetTable ?? targetLocal ?? "unknown",
+        cardinality,
+        fields: columns.fields,
+        references: columns.references,
+        source,
+        unknown: unknowns,
+    };
+    return { relation, diagnostics: schemaDiagnostics(unknowns) };
+}
+function readRelations(input) {
+    const { graph, file, call, lookup } = input;
+    const source = nodeRef(file, call);
+    const args = callArguments(call);
+    const fromLocal = identifierName(unwrapExpression(args[0]));
+    const fromTable = fromLocal === undefined ? null : resolveTableBinding(graph, file.path, fromLocal, lookup);
+    const from = fromTable ?? fromLocal ?? "unknown";
+    const callback = args[1];
+    const body = callbackExpression(callback);
+    const helpers = helperBindings(callback);
+    if (body?.type !== "ObjectExpression" || helpers === null) {
+        return {
+            relations: [],
+            diagnostics: schemaDiagnostics([
+                schemaUnknown("relations() callback is not a destructured one/many callback", source),
+            ]),
+        };
+    }
+    const relations = [];
+    const diagnostics = [];
+    if (fromTable === null) {
+        const unknown = schemaUnknown("relation source table is not resolvable statically", source);
+        diagnostics.push(...schemaDiagnostics([unknown]));
+    }
+    for (const entry of objectEntries(body)) {
+        if (propertyName(entry) === undefined) {
+            diagnostics.push(...schemaDiagnostics([
+                schemaUnknown("computed relation key is outside the DSL", nodeRef(file, entry)),
+            ]));
+            continue;
+        }
+        const result = readRelationEntry({ entry, from, graph, file, lookup, helpers });
+        if (result.relation !== null)
+            relations.push(result.relation);
+        diagnostics.push(...result.diagnostics);
+    }
+    return { relations, diagnostics };
+}
+export function buildRelationFacts(graph, files, lookup) {
+    const relations = [];
+    const diagnostics = [];
+    for (const file of files) {
+        const resolver = createDslResolver(graph, file);
+        for (const declarator of topLevelDeclarators(file.program)) {
+            const call = unwrapExpression(declarator.init);
+            if (call?.type !== "CallExpression")
+                continue;
+            const symbol = resolver(call.callee);
+            if (symbol?.pkg !== "drizzle-orm" || symbol.name !== "relations")
+                continue;
+            const scan = readRelations({ graph, file, call, lookup });
+            relations.push(...scan.relations);
+            diagnostics.push(...scan.diagnostics);
+        }
+    }
+    return { relations: dedupeRelations(relations), diagnostics };
+}
+/** Duplicate declarations (e.g. split files) must not duplicate edges. */
+function dedupeRelations(relations) {
+    const seen = new Set();
+    const out = [];
+    for (const relation of relations) {
+        const key = [
+            relation.from,
+            relation.to,
+            relation.cardinality,
+            relation.fields.join(","),
+            relation.references.join(","),
+        ].join("|");
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(relation);
+    }
+    return out;
+}

package/dist/passes/schema-scope.d.ts

@@ -0,0 +1,7 @@
+import type { ColumnFact, ConfigFacts, ScopeFact } from "../types.js";
+export interface ScopedColumn {
+    readonly column: ColumnFact;
+    readonly tenant: boolean;
+}
+/** Tenant scope wins over owner scope: both can be declared on the same table. */
+export declare function scopeOf(columns: readonly ScopedColumn[], config: ConfigFacts): ScopeFact | null;

package/dist/passes/schema-scope.js

@@ -0,0 +1,20 @@
+function normalized(value) {
+    return value.replaceAll("_", "").replaceAll("-", "").toLowerCase();
+}
+function matchesConfig(column, names) {
+    const property = normalized(column.property);
+    const sqlName = normalized(column.name);
+    return names.some((candidate) => {
+        const value = normalized(candidate);
+        return value === property || value === sqlName;
+    });
+}
+/** Tenant scope wins over owner scope: both can be declared on the same table. */
+export function scopeOf(columns, config) {
+    const tenant = columns.find((entry) => entry.tenant) ??
+        columns.find((entry) => matchesConfig(entry.column, config.tenantColumns));
+    if (tenant !== undefined)
+        return { column: tenant.column.property, kind: "tenant" };
+    const owner = columns.find((entry) => matchesConfig(entry.column, config.ownerColumns));
+    return owner === undefined ? null : { column: owner.column.property, kind: "owner" };
+}

package/dist/passes/schema-tables.d.ts

@@ -0,0 +1,13 @@
+import type { ModuleGraph, ProjectFile } from "../module-graph.js";
+import type { ConfigFacts, Diagnostic, TableFact } from "../types.js";
+import { type ColumnReference } from "./schema-columns.js";
+export interface TableDraft {
+    readonly fact: TableFact;
+    readonly binding: string | null;
+    readonly references: readonly ColumnReference[];
+}
+export interface TableScan {
+    readonly drafts: readonly TableDraft[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+export declare function collectTableDrafts(graph: ModuleGraph, file: ProjectFile, config: ConfigFacts): TableScan;

package/dist/passes/schema-tables.js

@@ -0,0 +1,149 @@
+import { callArguments, identifierName, memberName, objectEntries, propertyName, propertyValue, unwrapExpression, } from "../ast/node.js";
+import { diagnostic } from "../diagnostics.js";
+import { staticString } from "../static-eval.js";
+import { buildColumnFact } from "./schema-columns.js";
+import { scopeOf } from "./schema-scope.js";
+import { createDslResolver, nodeRef, schemaDiagnostics, schemaUnknown, topLevelDeclarators, } from "./schema-dsl.js";
+import { buildPolicyFacts } from "./schema-policies.js";
+/** Local `pgEnum("name", values)` consts; a column built from one is a known enum builder. */
+function collectEnumBindings(file, resolver, graph) {
+    const enums = new Map();
+    for (const declarator of topLevelDeclarators(file.program)) {
+        const binding = identifierName(declarator.id);
+        const init = unwrapExpression(declarator.init);
+        if (binding === undefined || init?.type !== "CallExpression")
+            continue;
+        const symbol = resolver(init.callee);
+        if (symbol?.pkg !== "pg-core" || symbol.name !== "pgEnum")
+            continue;
+        const name = staticString(callArguments(init)[0], { graph, file: file.path });
+        enums.set(binding, name.ok ? name.value : binding);
+    }
+    return enums;
+}
+/** The `pgTable` call inside `pgTable(...).enableRLS()`, plus the chain methods after it. */
+function findTableCall(init, resolver) {
+    let current = unwrapExpression(init);
+    const methods = [];
+    let guard = 0;
+    while (current?.type === "CallExpression" && guard < 32) {
+        guard += 1;
+        const callee = unwrapExpression(current.callee);
+        if (callee === undefined)
+            return null;
+        if (callee.type === "MemberExpression") {
+            const name = memberName(callee);
+            if (name === undefined)
+                return null;
+            methods.unshift(name);
+            current = unwrapExpression(callee.object);
+            continue;
+        }
+        const symbol = resolver(callee);
+        if (symbol?.pkg !== "pg-core" || symbol.name !== "pgTable")
+            return null;
+        return { call: current, methods };
+    }
+    return null;
+}
+function buildTableDraft(input) {
+    const { graph, file, resolver, enums, config, binding, tableCall } = input;
+    const source = nodeRef(file, tableCall.call);
+    const args = callArguments(tableCall.call);
+    const unknowns = [];
+    const diagnostics = [];
+    const nameResult = staticString(args[0], { graph, file: file.path });
+    let name;
+    if (nameResult.ok && nameResult.value.length > 0) {
+        name = nameResult.value;
+    }
+    else {
+        name = binding ?? "unknown";
+        unknowns.push(schemaUnknown('table name of "' + name + '" is not a static string', source));
+    }
+    const columns = [];
+    const references = [];
+    const columnsArgument = unwrapExpression(args[1]);
+    if (columnsArgument?.type !== "ObjectExpression") {
+        unknowns.push(schemaUnknown('columns of table "' + name + '" are not an object literal', source));
+    }
+    else {
+        for (const entry of objectEntries(columnsArgument)) {
+            if (entry.type === "SpreadElement") {
+                unknowns.push(schemaUnknown('spread columns in table "' + name + '" are outside the DSL', nodeRef(file, entry)));
+                continue;
+            }
+            const property = propertyName(entry);
+            if (property === undefined) {
+                unknowns.push(schemaUnknown('computed column key in table "' + name + '" is outside the DSL', nodeRef(file, entry)));
+                continue;
+            }
+            const result = buildColumnFact({
+                property,
+                expression: propertyValue(entry),
+                propertyNode: entry,
+                file,
+                graph,
+                resolver,
+                enums,
+            });
+            diagnostics.push(...result.diagnostics);
+            if (result.reference !== null) {
+                references.push({ column: property, target: result.reference });
+            }
+            columns.push({ column: result.column, tenant: result.tenant });
+        }
+    }
+    const policyScan = buildPolicyFacts({
+        extras: args[2],
+        file,
+        graph,
+        resolver,
+    });
+    diagnostics.push(...policyScan.diagnostics);
+    const rlsEnabled = tableCall.methods.includes("enableRLS");
+    const scope = scopeOf(columns, config);
+    const fact = {
+        name,
+        binding,
+        columns: columns.map((entry) => entry.column),
+        primaryKey: columns
+            .filter((entry) => entry.column.primaryKey)
+            .map((entry) => entry.column.property),
+        foreignKeys: [],
+        policies: policyScan.policies,
+        rlsEnabled,
+        scope,
+        source,
+        unknown: unknowns,
+    };
+    diagnostics.push(...schemaDiagnostics(unknowns));
+    if (scope !== null && (!rlsEnabled || policyScan.policies.length === 0)) {
+        diagnostics.push(diagnostic("rls-on-scoped-table", "error", 'scoped table "' + name + '" must call .enableRLS() and declare a policy', source));
+    }
+    return { draft: { fact, binding, references }, diagnostics };
+}
+export function collectTableDrafts(graph, file, config) {
+    const resolver = createDslResolver(graph, file);
+    const enums = collectEnumBindings(file, resolver, graph);
+    const drafts = [];
+    const diagnostics = [];
+    for (const declarator of topLevelDeclarators(file.program)) {
+        const binding = identifierName(declarator.id) ?? null;
+        const tableCall = findTableCall(declarator.init, resolver);
+        if (tableCall === null)
+            continue;
+        const result = buildTableDraft({
+            graph,
+            file,
+            resolver,
+            enums,
+            config,
+            binding,
+            tableCall,
+        });
+        drafts.push(result.draft);
+        diagnostics.push(...result.diagnostics);
+    }
+    return { drafts, diagnostics };
+}

package/dist/passes/schema.d.ts

@@ -0,0 +1,9 @@
+import type { ModuleGraph } from "../module-graph.js";
+import type { ConfigFacts, Diagnostic, RelationFact, TableFact } from "../types.js";
+export interface SchemaResult {
+    readonly tables: readonly TableFact[];
+    readonly relations: readonly RelationFact[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+/** Interpret the Drizzle DSL under `db/**`, including framework tables reached by re-export. */
+export declare function buildSchemaFacts(graph: ModuleGraph, config: ConfigFacts): SchemaResult;

package/dist/passes/schema.js

@@ -0,0 +1,55 @@
+import { isSchemaFile } from "./schema-dsl.js";
+import { collectFileLinkDrafts } from "./schema-file-links.js";
+import { buildTableLookup, finalizeTables, withFrameworkTables } from "./schema-foreign-keys.js";
+import { collectTableDrafts } from "./schema-tables.js";
+import { collectReExportedDrafts } from "./schema-re-exports.js";
+import { buildRelationFacts } from "./schema-relations.js";
+function schemaFiles(graph) {
+    return [...graph.files.values()]
+        .filter((file) => isSchemaFile(graph, file.path))
+        .toSorted((left, right) => left.path.localeCompare(right.path));
+}
+/** Tables declared twice (invalid TS, but analyzable) keep the first declaration. */
+function dedupeDrafts(drafts) {
+    const seen = new Set();
+    const out = [];
+    for (const draft of drafts) {
+        if (seen.has(draft.fact.name))
+            continue;
+        seen.add(draft.fact.name);
+        out.push(draft);
+    }
+    return out;
+}
+/** Interpret the Drizzle DSL under `db/**`, including framework tables reached by re-export. */
+export function buildSchemaFacts(graph, config) {
+    const files = schemaFiles(graph);
+    const collected = [];
+    const externalTables = [];
+    const diagnostics = [];
+    for (const file of files) {
+        const scan = collectTableDrafts(graph, file, config);
+        collected.push(...scan.drafts);
+        diagnostics.push(...scan.diagnostics);
+        // Generated link tables follow the file's own declarations, which is their source order:
+        // `const todoFiles = fileLinks(todos, ...)` comes after the `todos` it references.
+        const links = collectFileLinkDrafts(graph, file, scan.drafts);
+        collected.push(...links.drafts);
+        externalTables.push(...links.externalTables);
+        diagnostics.push(...links.diagnostics);
+    }
+    const seenNames = new Set(collected.map((draft) => draft.fact.name));
+    const visitedFiles = new Set(files.map((file) => file.path));
+    for (const file of files) {
+        const scan = collectReExportedDrafts(graph, file, config, seenNames, visitedFiles);
+        collected.push(...scan.drafts);
+        diagnostics.push(...scan.diagnostics);
+    }
+    const drafts = dedupeDrafts(collected);
+    const lookup = withFrameworkTables(buildTableLookup(drafts), externalTables);
+    const finalized = finalizeTables(graph, drafts, lookup);
+    diagnostics.push(...finalized.diagnostics);
+    const relations = buildRelationFacts(graph, files, lookup);
+    diagnostics.push(...relations.diagnostics);
+    return { tables: finalized.tables, relations: relations.relations, diagnostics };
+}

package/dist/passes/screen-components.d.ts

@@ -0,0 +1,22 @@
+/**
+ * JSX component resolution for the static page preview: find a component's returned
+ * expression and resolve a JSX name to a project file through the module graph.
+ *
+ * The resolver is deliberately one level deep per call; the preview builder owns the depth,
+ * cycle and node budgets.
+ */
+import { type AstNode } from "../ast/node.js";
+import type { ModuleGraph } from "../module-graph.js";
+export interface ComponentRef {
+    readonly file: string;
+    readonly name: string;
+}
+export declare function lineRef(graph: ModuleGraph, file: string, node: AstNode): {
+    file: string;
+    line: number;
+};
+export declare function returnedExpression(body: AstNode): AstNode | undefined;
+export declare function componentExpression(graph: ModuleGraph, filePath: string, name: string): AstNode | undefined;
+export declare function resolveComponent(graph: ModuleGraph, originFile: string, name: string): ComponentRef | null;
+export declare function firstComponentName(graph: ModuleGraph, filePath: string): string | null;
+export declare function canExpand(file: string): boolean;

package/dist/passes/screen-components.js

@@ -0,0 +1,143 @@
+/**
+ * JSX component resolution for the static page preview: find a component's returned
+ * expression and resolve a JSX name to a project file through the module graph.
+ *
+ * The resolver is deliberately one level deep per call; the preview builder owns the depth,
+ * cycle and node budgets.
+ */
+import { asNode, nodeArray } from "../ast/node.js";
+import { defaultExportDeclaration } from "../module-info.js";
+import { sourceRef } from "../source.js";
+export function lineRef(graph, file, node) {
+    const source = graph.file(file)?.source;
+    return source === undefined
+        ? { file, line: 1 }
+        : sourceRef(file, source, typeof node.start === "number" ? node.start : 0);
+}
+function componentDeclaration(program, name) {
+    const wanted = name === "default" ? null : name;
+    for (const statement of nodeArray(program, "body")) {
+        const declaration = statement.type === "ExportNamedDeclaration" || statement.type === "ExportDefaultDeclaration"
+            ? asNode(statement.declaration)
+            : statement;
+        if (declaration === undefined)
+            continue;
+        if (declaration.type === "FunctionDeclaration") {
+            const id = asNode(declaration.id);
+            if (id !== undefined &&
+                typeof id.name === "string" &&
+                (wanted === null || id.name === wanted)) {
+                return declaration;
+            }
+        }
+        if (declaration.type !== "VariableDeclaration")
+            continue;
+        for (const item of nodeArray(declaration, "declarations")) {
+            const id = asNode(item.id);
+            const init = asNode(item.init);
+            if (id === undefined || init === undefined)
+                continue;
+            if (typeof id.name !== "string" || (wanted !== null && id.name !== wanted))
+                continue;
+            if (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression")
+                return init;
+        }
+    }
+    if (name === "default")
+        return defaultExportDeclaration(program);
+    return undefined;
+}
+export function returnedExpression(body) {
+    if (body.type === "BlockStatement") {
+        for (const statement of nodeArray(body, "body")) {
+            const found = returnedExpression(statement);
+            if (found !== undefined)
+                return found;
+        }
+        return undefined;
+    }
+    if (body.type === "ReturnStatement")
+        return asNode(body.argument);
+    if (body.type === "IfStatement") {
+        const consequent = asNode(body.consequent);
+        const alternate = asNode(body.alternate);
+        return ((consequent === undefined ? undefined : returnedExpression(consequent)) ??
+            (alternate === undefined ? undefined : returnedExpression(alternate)));
+    }
+    if (body.type === "TryStatement") {
+        const block = asNode(body.block);
+        const handler = asNode(body.handler);
+        const finalizer = asNode(body.finalizer);
+        const handlerBody = handler === undefined ? undefined : asNode(handler.body);
+        return ((block === undefined ? undefined : returnedExpression(block)) ??
+            (handlerBody === undefined ? undefined : returnedExpression(handlerBody)) ??
+            (finalizer === undefined ? undefined : returnedExpression(finalizer)));
+    }
+    return undefined;
+}
+export function componentExpression(graph, filePath, name) {
+    const file = graph.file(filePath);
+    if (file === undefined)
+        return undefined;
+    const declaration = componentDeclaration(file.program, name);
+    if (declaration === undefined)
+        return undefined;
+    if (declaration.type === "ArrowFunctionExpression") {
+        const body = asNode(declaration.body);
+        return body === undefined
+            ? undefined
+            : body.type === "BlockStatement"
+                ? returnedExpression(body)
+                : body;
+    }
+    if (declaration.type === "FunctionDeclaration" || declaration.type === "FunctionExpression") {
+        const body = asNode(declaration.body);
+        return body === undefined ? undefined : returnedExpression(body);
+    }
+    return declaration;
+}
+export function resolveComponent(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);
+    if (file === undefined)
+        return null;
+    return { file: file.path, name: binding.name };
+}
+export function firstComponentName(graph, filePath) {
+    const file = graph.file(filePath);
+    if (file === undefined)
+        return null;
+    for (const statement of nodeArray(file.program, "body")) {
+        const declaration = statement.type === "ExportNamedDeclaration" || statement.type === "ExportDefaultDeclaration"
+            ? asNode(statement.declaration)
+            : statement;
+        if (declaration === undefined)
+            continue;
+        if (declaration.type === "FunctionDeclaration") {
+            const id = asNode(declaration.id);
+            if (id !== undefined && typeof id.name === "string")
+                return id.name;
+        }
+        if (declaration.type !== "VariableDeclaration")
+            continue;
+        for (const item of nodeArray(declaration, "declarations")) {
+            const id = asNode(item.id);
+            const init = asNode(item.init);
+            if (id === undefined || init === undefined || typeof id.name !== "string")
+                continue;
+            if (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression")
+                return id.name;
+        }
+    }
+    return null;
+}
+export function canExpand(file) {
+    if (file.startsWith("src/components/ui/"))
+        return false;
+    return (file.startsWith("src/pages/") ||
+        file.startsWith("src/layouts/") ||
+        file.startsWith("src/components/"));
+}

package/dist/passes/screen-intrinsics.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Which intrinsic JSX elements the page preview draws, and which copy they carry.
+ *
+ * Sections are the page's layout skeleton and are always drawn; content intrinsics are the
+ * copy-bearing blocks and controls that make the schematic page readable (D-170). Layout-only
+ * wrappers such as `<div>` are flattened, and a copy-bearing text element with no readable copy
+ * is flattened too, so the preview never draws empty boxes for spacing wrappers.
+ */
+import type { AstNode } from "../ast/node.js";
+import { type JsxTextFields } from "./jsx-text.js";
+/** What a drawable intrinsic contributes: its copy and whether it spends the content budget. */
+export interface IntrinsicPlan {
+    /** Content intrinsics have their own node budget and only draw when they carry something. */
+    readonly content: boolean;
+    readonly fields: JsxTextFields | undefined;
+}
+/** Classify one intrinsic element, or null when it is flattened into its parent. */
+export declare function planIntrinsic(node: AstNode, name: string): IntrinsicPlan | null;

package/dist/passes/screen-intrinsics.js

@@ -0,0 +1,21 @@
+/**
+ * Which intrinsic JSX elements the page preview draws, and which copy they carry.
+ *
+ * Sections are the page's layout skeleton and are always drawn; content intrinsics are the
+ * copy-bearing blocks and controls that make the schematic page readable (D-170). Layout-only
+ * wrappers such as `<div>` are flattened, and a copy-bearing text element with no readable copy
+ * is flattened too, so the preview never draws empty boxes for spacing wrappers.
+ */
+import { isContentIntrinsic, isRoleIntrinsic, isSectionIntrinsic } from "./jsx.js";
+import { jsxContentFields, jsxTextFields } from "./jsx-text.js";
+/** Classify one intrinsic element, or null when it is flattened into its parent. */
+export function planIntrinsic(node, name) {
+    const section = isSectionIntrinsic(name);
+    if (!section && !isContentIntrinsic(name))
+        return null;
+    const fields = section ? jsxTextFields(node) : jsxContentFields(node, name);
+    // A control or media element is a visible block even without copy; a bare span is not.
+    if (!section && fields === undefined && !isRoleIntrinsic(name))
+        return null;
+    return { content: !section, fields };
+}