nudge-ui 0.2.0

package/dist/compiler/ast.d.ts

@@ -0,0 +1,18 @@
+/** The subset of Babel nodes needed by the host-neutral compiler. */
+export type SyntaxNode = {
+    type: string;
+    [key: string]: unknown;
+};
+/** Node keys that never hold children worth visiting. */
+export declare const SKIP_KEYS: Set<string>;
+export declare function isNode(value: unknown): value is SyntaxNode;
+/** Visit every child node with the property name it was reached through. */
+export declare function forEachChild(node: SyntaxNode, visit: (child: SyntaxNode, key: string) => void): void;
+export declare function childNodes(node: SyntaxNode): SyntaxNode[];
+export declare function identifier(node: unknown): string | null;
+/** Dotted name for a JSX element name: `A`, `A.B`, `A.B.C`. */
+export declare function jsxMemberName(node: unknown): string | null;
+/** Dotted name for an identifier expression or a JSX element name. */
+export declare function elementName(node: unknown): string | null;
+/** Parse module source, returning `null` when the source is not parseable. */
+export declare function parseModule(code: string): SyntaxNode | null;

package/dist/compiler/ast.js

@@ -0,0 +1,75 @@
+import { parse } from "@babel/parser";
+/** Node keys that never hold children worth visiting. */
+export const SKIP_KEYS = new Set([
+    "type",
+    "loc",
+    "range",
+    "start",
+    "end",
+    "extra",
+    "leadingComments",
+    "trailingComments",
+    "innerComments",
+]);
+export function isNode(value) {
+    return typeof value === "object" && value !== null && typeof Reflect.get(value, "type") === "string";
+}
+/** Visit every child node with the property name it was reached through. */
+export function forEachChild(node, visit) {
+    for (const [key, value] of Object.entries(node)) {
+        if (SKIP_KEYS.has(key))
+            continue;
+        if (isNode(value)) {
+            visit(value, key);
+            continue;
+        }
+        if (!Array.isArray(value))
+            continue;
+        for (const child of value) {
+            if (isNode(child))
+                visit(child, key);
+        }
+    }
+}
+export function childNodes(node) {
+    const children = [];
+    forEachChild(node, (child) => children.push(child));
+    return children;
+}
+export function identifier(node) {
+    if (!isNode(node) || (node.type !== "Identifier" && node.type !== "StringLiteral"))
+        return null;
+    return typeof node.name === "string" ? node.name : typeof node.value === "string" ? node.value : null;
+}
+/** Dotted name for a JSX element name: `A`, `A.B`, `A.B.C`. */
+export function jsxMemberName(node) {
+    if (!isNode(node))
+        return null;
+    if (node.type === "JSXIdentifier")
+        return typeof node.name === "string" ? node.name : null;
+    if (node.type !== "JSXMemberExpression")
+        return null;
+    const object = jsxMemberName(node.object);
+    const property = jsxMemberName(node.property);
+    return object && property ? `${object}.${property}` : null;
+}
+/** Dotted name for an identifier expression or a JSX element name. */
+export function elementName(node) {
+    if (!isNode(node))
+        return null;
+    if (node.type === "Identifier")
+        return typeof node.name === "string" ? node.name : null;
+    return jsxMemberName(node);
+}
+/** Parse module source, returning `null` when the source is not parseable. */
+export function parseModule(code) {
+    try {
+        return parse(code, {
+            sourceType: "module",
+            plugins: ["jsx", "typescript"],
+        });
+    }
+    catch {
+        return null;
+    }
+}

package/dist/compiler/componentContractTypes.d.ts

@@ -0,0 +1,19 @@
+export type ComponentPropValue = string | number | boolean;
+export interface ComponentPropContract {
+    name: string;
+    /**
+     * `text` is deliberately separate from a select. Text edits are allowed to
+     * choose an arbitrary string at runtime, while select controls are bounded
+     * by their contract options.
+     */
+    control: "select" | "boolean" | "text";
+    options: ComponentPropValue[];
+    optional: boolean;
+}
+export interface ComponentContract {
+    componentId: string;
+    name: string;
+    file: string;
+    props: ComponentPropContract[];
+    provenance: "typescript" | "package-manifest";
+}

package/dist/compiler/componentContractTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/compiler/componentContracts.d.ts

@@ -0,0 +1,2 @@
+import type { ComponentContract } from "./componentContractTypes.js";
+export declare function extractComponentContracts(code: string, file: string): ComponentContract[];

package/dist/compiler/componentContracts.js

@@ -0,0 +1,260 @@
+import { parse } from "@babel/parser";
+function isNode(value) {
+    return typeof value === "object"
+        && value !== null
+        && typeof value.type === "string";
+}
+function nodeName(node) {
+    if (!node)
+        return null;
+    if (node.type === "Identifier" || node.type === "JSXIdentifier") {
+        return typeof node.name === "string" ? node.name : null;
+    }
+    if (node.type === "TSQualifiedName") {
+        const left = nodeName(node.left);
+        const right = nodeName(node.right);
+        return left && right ? `${left}.${right}` : null;
+    }
+    if (node.type === "MemberExpression" || node.type === "OptionalMemberExpression") {
+        const object = nodeName(node.object);
+        const property = nodeName(node.property);
+        return object && property ? `${object}.${property}` : null;
+    }
+    return null;
+}
+function unwrapTypeAnnotation(node) {
+    if (!node)
+        return null;
+    return node.type === "TSTypeAnnotation"
+        ? node.typeAnnotation ?? null
+        : node;
+}
+function literalValue(node) {
+    if (node.type === "TSLiteralType") {
+        return isNode(node.literal) ? literalValue(node.literal) : null;
+    }
+    if (node.type === "StringLiteral" || node.type === "NumericLiteral" || node.type === "BooleanLiteral") {
+        const value = node.value;
+        return typeof value === "string" || typeof value === "number" || typeof value === "boolean"
+            ? value
+            : null;
+    }
+    return null;
+}
+/**
+ * These are the names that a component contract can confidently describe as
+ * visible copy. The runtime still requires the current value to be a string
+ * equal to the rendered text before offering an inline binding.
+ */
+const STRUCTURAL_TEXT_PROPS = new Set([
+    "id",
+    "className",
+    "href",
+    "src",
+    "role",
+    "style",
+]);
+function isStructuralTextProp(name) {
+    return STRUCTURAL_TEXT_PROPS.has(name)
+        || name.startsWith("data")
+        || name.startsWith("aria");
+}
+function isReactNodeType(node) {
+    if (node.type !== "TSTypeReference")
+        return false;
+    return ["ReactNode", "React.ReactNode", "React.ReactChild", "React.ReactText"]
+        .includes(nodeName(node.typeName) ?? "");
+}
+function isTextType(node) {
+    return node.type === "TSStringKeyword" || isReactNodeType(node);
+}
+function propertyContract(member) {
+    if (member.type !== "TSPropertySignature")
+        return null;
+    const name = nodeName(member.key);
+    const typeNode = unwrapTypeAnnotation(member.typeAnnotation);
+    if (!name || !typeNode)
+        return null;
+    // Project contracts recognize all runtime string props. Structural and
+    // implementation names are excluded here; package manifests can still
+    // explicitly publish a text control for a project-specific visible prop.
+    if (!isStructuralTextProp(name) && isTextType(typeNode)) {
+        return {
+            name,
+            control: "text",
+            options: [],
+            optional: member.optional === true,
+        };
+    }
+    if (typeNode.type === "TSBooleanKeyword") {
+        return {
+            name,
+            control: "boolean",
+            options: [false, true],
+            optional: member.optional === true,
+        };
+    }
+    if (typeNode.type !== "TSUnionType")
+        return null;
+    const values = (typeNode.types ?? [])
+        .map(literalValue)
+        .filter((value) => value !== null);
+    const members = typeNode.types ?? [];
+    if (values.length < 2 || values.length !== members.length)
+        return null;
+    const primitive = typeof values[0];
+    if (!values.every((value) => typeof value === primitive))
+        return null;
+    return {
+        name,
+        control: "select",
+        options: values,
+        optional: member.optional === true,
+    };
+}
+function membersForType(node, declarations, seen = new Set()) {
+    if (!node)
+        return [];
+    if (node.type === "TSTypeLiteral")
+        return node.members ?? [];
+    if (node.type === "TSInterfaceBody")
+        return node.body ?? [];
+    if (node.type === "TSIntersectionType") {
+        return (node.types ?? []).flatMap((part) => membersForType(part, declarations, seen));
+    }
+    if (node.type === "TSTypeReference") {
+        const name = nodeName(node.typeName);
+        if (!name || seen.has(name))
+            return [];
+        const declaration = declarations.get(name);
+        if (!declaration)
+            return [];
+        seen.add(name);
+        if (declaration.type === "TSInterfaceDeclaration") {
+            return membersForType(declaration.body, declarations, seen);
+        }
+        if (declaration.type === "TSTypeAliasDeclaration") {
+            return membersForType(declaration.typeAnnotation, declarations, seen);
+        }
+    }
+    return [];
+}
+function propsTypeFromParam(param) {
+    if (!param)
+        return null;
+    if (param.type === "AssignmentPattern")
+        return propsTypeFromParam(param.left);
+    return unwrapTypeAnnotation(param.typeAnnotation);
+}
+function propsTypeFromVariableId(id) {
+    const annotation = unwrapTypeAnnotation(id.typeAnnotation);
+    if (!annotation || annotation.type !== "TSTypeReference")
+        return null;
+    const typeName = nodeName(annotation.typeName);
+    if (typeName !== "React.FC" && typeName !== "FC" && typeName !== "React.FunctionComponent"
+        && typeName !== "FunctionComponent")
+        return null;
+    const params = annotation.typeParameters;
+    return params?.params?.[0] ?? null;
+}
+function componentInitializer(node) {
+    if (node.type === "ArrowFunctionExpression" || node.type === "FunctionExpression") {
+        return { functionNode: node, propsType: null };
+    }
+    if (node.type !== "CallExpression")
+        return null;
+    const wrapperName = nodeName(node.callee)?.split(".").at(-1);
+    if (wrapperName !== "memo" && wrapperName !== "forwardRef")
+        return null;
+    const argument = (node.arguments ?? [])[0];
+    if (!argument)
+        return null;
+    const inner = componentInitializer(argument);
+    if (!inner)
+        return null;
+    if (wrapperName !== "forwardRef")
+        return inner;
+    const typeParameters = (node.typeParameters
+        ?? node.typeArguments)?.params ?? [];
+    return {
+        functionNode: inner.functionNode,
+        propsType: inner.propsType ?? typeParameters[1] ?? null,
+    };
+}
+function componentContract(name, propsType, declarations, file) {
+    if (!/^[A-Z]/.test(name))
+        return null;
+    const props = membersForType(propsType, declarations)
+        .map(propertyContract)
+        .filter((prop) => prop !== null);
+    if (props.length === 0)
+        return null;
+    return {
+        componentId: `${file.replace(/\.(?:d\.)?[cm]?[jt]sx?$/, "")}#${name}`,
+        name,
+        file,
+        props,
+        provenance: "typescript",
+    };
+}
+function unwrapExport(node) {
+    if (node.type === "ExportNamedDeclaration" || node.type === "ExportDefaultDeclaration") {
+        return isNode(node.declaration) ? node.declaration : node;
+    }
+    return node;
+}
+export function extractComponentContracts(code, file) {
+    let ast;
+    try {
+        ast = parse(code, {
+            sourceType: "module",
+            plugins: ["jsx", "typescript"],
+        });
+    }
+    catch {
+        return [];
+    }
+    const program = ast.program;
+    const body = program?.body ?? [];
+    const declarations = new Map();
+    for (const statement of body) {
+        const node = unwrapExport(statement);
+        if (node.type !== "TSInterfaceDeclaration" && node.type !== "TSTypeAliasDeclaration")
+            continue;
+        const name = nodeName(node.id);
+        if (name)
+            declarations.set(name, node);
+    }
+    const contracts = [];
+    for (const statement of body) {
+        const node = unwrapExport(statement);
+        if (node.type === "FunctionDeclaration") {
+            const name = nodeName(node.id);
+            const param = (node.params ?? [])[0];
+            const contract = name
+                ? componentContract(name, propsTypeFromParam(param), declarations, file)
+                : null;
+            if (contract)
+                contracts.push(contract);
+            continue;
+        }
+        if (node.type !== "VariableDeclaration")
+            continue;
+        for (const declaration of node.declarations ?? []) {
+            const id = declaration.id;
+            const init = declaration.init;
+            const name = id ? nodeName(id) : null;
+            const initializer = init ? componentInitializer(init) : null;
+            if (!id || !initializer || !name)
+                continue;
+            const param = (initializer.functionNode.params ?? [])[0];
+            const propsType = propsTypeFromParam(param)
+                ?? initializer.propsType
+                ?? propsTypeFromVariableId(id);
+            const contract = componentContract(name, propsType, declarations, file);
+            if (contract)
+                contracts.push(contract);
+        }
+    }
+    return contracts;
+}

package/dist/compiler/componentInstrumentation.d.ts

@@ -0,0 +1,32 @@
+import { type SyntaxNode } from "./ast.js";
+export type { SyntaxNode } from "./ast.js";
+export interface ComponentInstrumentationOptions {
+    /**
+     * Package exports whose element type can be replaced by a semantic preview
+     * wrapper. Keys are exact import specifiers; values are exported names
+     * (`default` for a default import). Discovery of a prop contract does not
+     * imply compatibility. Prefer `hostPolicy` when the host can resolve import
+     * provenance and rendered slots.
+     */
+    compatibleComponentImports?: Readonly<Record<string, readonly string[]>>;
+    /** Data-only import provenance and slot semantics resolved by the host Adapter. */
+    hostPolicy?: import("./componentPolicyResolution.js").HostComponentPolicy;
+}
+export interface ComponentBinding {
+    source: string;
+    exportName: string | null;
+    namespace: boolean;
+}
+export interface ComponentInstrumentationPolicy {
+    bindings: Map<string, ComponentBinding>;
+    canWrap(componentName: string): boolean;
+    rendersChildren(componentName: string): boolean;
+    rendersProp(componentName: string, prop: string): boolean;
+    componentId(componentName: string): string | null;
+}
+/**
+ * Classify bindings before editing JSX. Unknown and shadowed bindings are
+ * deliberately excluded: losing a semantic control is safer than changing an
+ * application's component protocol. Rendered DOM identity is independent.
+ */
+export declare function createComponentInstrumentationPolicy(ast: SyntaxNode, options: ComponentInstrumentationOptions): ComponentInstrumentationPolicy;

package/dist/compiler/componentInstrumentation.js

@@ -0,0 +1,140 @@
+import { childNodes, identifier, isNode } from "./ast.js";
+/**
+ * Classify bindings before editing JSX. Unknown and shadowed bindings are
+ * deliberately excluded: losing a semantic control is safer than changing an
+ * application's component protocol. Rendered DOM identity is independent.
+ */
+export function createComponentInstrumentationPolicy(ast, options) {
+    const bindings = new Map();
+    const locals = new Set();
+    const seen = new Set();
+    const ambiguous = new Set();
+    const record = (name, local = false) => {
+        if (!name)
+            return;
+        if (seen.has(name))
+            ambiguous.add(name);
+        seen.add(name);
+        if (local)
+            locals.add(name);
+    };
+    const recordPattern = (pattern) => {
+        if (!isNode(pattern))
+            return;
+        if (pattern.type === "Identifier") {
+            record(identifier(pattern));
+        }
+        else if (pattern.type === "RestElement") {
+            recordPattern(pattern.argument);
+        }
+        else if (pattern.type === "AssignmentPattern") {
+            recordPattern(pattern.left);
+        }
+        else if (pattern.type === "ObjectPattern") {
+            for (const property of pattern.properties ?? []) {
+                recordPattern(property.type === "RestElement" ? property.argument : property.value);
+            }
+        }
+        else if (pattern.type === "ArrayPattern") {
+            for (const element of pattern.elements ?? [])
+                recordPattern(element);
+        }
+    };
+    const program = isNode(ast.program) ? ast.program : ast;
+    for (const statement of program.body ?? []) {
+        if (statement.type !== "ImportDeclaration" || !isNode(statement.source))
+            continue;
+        if (statement.importKind === "type")
+            continue;
+        const source = String(statement.source.value ?? "");
+        for (const specifier of statement.specifiers ?? []) {
+            if (specifier.importKind === "type")
+                continue;
+            const local = identifier(specifier.local);
+            if (!local)
+                continue;
+            record(local);
+            bindings.set(local, {
+                source,
+                exportName: specifier.type === "ImportDefaultSpecifier" ? "default" : identifier(specifier.imported),
+                namespace: specifier.type === "ImportNamespaceSpecifier",
+            });
+        }
+    }
+    const imported = (name) => {
+        const [root, ...members] = name.split(".");
+        const binding = root ? bindings.get(root) : undefined;
+        if (!binding || ambiguous.has(root))
+            return null;
+        const exportName = binding.namespace
+            ? members.join(".")
+            : [binding.exportName, ...members].filter(Boolean).join(".");
+        return { source: binding.source, exportName };
+    };
+    const isLocalDefinition = (value) => {
+        if (!isNode(value))
+            return false;
+        return [
+            "ArrowFunctionExpression",
+            "FunctionExpression",
+            "ClassExpression",
+            "CallExpression",
+            "TaggedTemplateExpression",
+        ].includes(value.type);
+    };
+    const visit = (node) => {
+        if (node.type === "ImportDeclaration")
+            return;
+        if (node.type === "FunctionDeclaration" || node.type === "ClassDeclaration")
+            record(identifier(node.id), true);
+        if (node.type === "VariableDeclarator") {
+            if (isNode(node.id) && node.id.type === "Identifier")
+                record(identifier(node.id), isLocalDefinition(node.init));
+            else
+                recordPattern(node.id);
+        }
+        if (Array.isArray(node.params))
+            node.params.forEach(recordPattern);
+        if (node.type === "CatchClause")
+            recordPattern(node.param);
+        childNodes(node).forEach(visit);
+    };
+    visit(program);
+    // A definition authored in this module is project-owned by construction: no
+    // host resolution applies, and its JSX children are authored here rather
+    // than handed to an opaque third-party interface.
+    const isProjectLocalComponent = (componentName) => {
+        const [root, ...members] = componentName.split(".");
+        if (!root || ambiguous.has(root))
+            return false;
+        return members.length === 0 && imported(componentName) === null && locals.has(root);
+    };
+    return {
+        bindings,
+        canWrap(componentName) {
+            const binding = imported(componentName);
+            if (!binding)
+                return isProjectLocalComponent(componentName);
+            const resolved = options.hostPolicy?.components[componentName];
+            if (resolved)
+                return resolved.wrap;
+            // No host policy: this is the direct-compiler path, where a package
+            // export is only compatible when the caller names it explicitly. The
+            // host-resolved policy traces re-exports and namespace members, so this
+            // fallback deliberately matches on the authored import alone.
+            return options.compatibleComponentImports?.[binding.source]?.includes(binding.exportName) === true;
+        },
+        rendersChildren(componentName) {
+            const resolved = options.hostPolicy?.components[componentName];
+            if (resolved)
+                return resolved.slots?.children === "rendered";
+            return isProjectLocalComponent(componentName);
+        },
+        rendersProp(componentName, prop) {
+            return options.hostPolicy?.components[componentName]?.slots?.[prop] === "rendered";
+        },
+        componentId(componentName) {
+            return options.hostPolicy?.components[componentName]?.componentId ?? null;
+        },
+    };
+}

package/dist/compiler/componentPolicyResolution.d.ts

@@ -0,0 +1,71 @@
+/** Whether replacing a JSX element type with the semantic boundary is safe. */
+export interface ComponentProtocol {
+    readonly wrap: boolean;
+    /**
+     * JSX-valued slots where the compiler may apply each descendant's resolved
+     * protocol. A component that resolves to project-owned source defaults to
+     * `wrap: true` with `children: "rendered"`; every other slot stays opaque
+     * until a host declares it.
+     */
+    readonly slots?: Readonly<Record<string, "rendered" | "opaque">>;
+}
+/** Component protocols exported by one canonical module specifier. */
+export interface ComponentModuleProtocol {
+    readonly default?: ComponentProtocol;
+    readonly exports?: Readonly<Record<string, ComponentProtocol>>;
+}
+export interface ComponentModuleProtocols {
+    readonly [source: string]: ComponentModuleProtocol | undefined;
+}
+/** Build-tool operations needed to resolve an authored import to its defining module. */
+export interface ComponentModuleAdapter {
+    resolve(specifier: string, importer: string): Promise<string | null>;
+    read(id: string): Promise<string | null>;
+    isProjectSource(id: string): boolean;
+    /** Stable, machine-independent path used by component contracts and callsite identity. */
+    sourcePath(id: string): string;
+}
+export interface ResolvedComponentProtocol extends ComponentProtocol {
+    readonly componentId: string;
+}
+export type ComponentPolicyDiagnosticCode = "component-import-unresolved" | "component-protocol-unknown" | "component-export-unresolved";
+export interface ComponentPolicyDiagnostic {
+    readonly code: ComponentPolicyDiagnosticCode;
+    readonly componentName: string;
+    readonly source: string;
+    readonly exportName: string;
+}
+/** Data-only policy consumed by the source compiler after a host resolves imports. */
+export interface HostComponentPolicy {
+    readonly components: Readonly<Record<string, ResolvedComponentProtocol>>;
+    readonly diagnostics: readonly ComponentPolicyDiagnostic[];
+}
+export interface ResolveHostComponentPolicyOptions {
+    readonly moduleProtocols?: ComponentModuleProtocols;
+    /** Backwards-compatible shorthand: these exports may be wrapped but expose no rendered slots. */
+    readonly compatibleComponentImports?: Readonly<Record<string, readonly string[]>>;
+}
+/** Merge a host's protocol additions over a shared compatibility catalog. */
+export declare function mergeComponentModuleProtocols(defaults: ComponentModuleProtocols, overrides: ComponentModuleProtocols | undefined): ComponentModuleProtocols;
+/**
+ * Resolve the imported JSX values used by one source file.
+ *
+ * The compiler owns syntax and re-export traversal. The host Adapter owns all
+ * build-tool resolution, source ownership, and stable path decisions.
+ */
+export declare function resolveHostComponentPolicy(code: string, importer: string, adapter: ComponentModuleAdapter, options?: ResolveHostComponentPolicyOptions): Promise<HostComponentPolicy>;
+/** One actionable message per diagnostic code and source. */
+export interface GroupedComponentPolicyDiagnostic {
+    /** Stable dedupe key for host-side "warn once" tracking. */
+    readonly key: string;
+    readonly source: string;
+    readonly componentNames: readonly string[];
+    readonly total: number;
+}
+/**
+ * Roll per-component diagnostics up so a host emits one warning per package
+ * instead of one per skipped export.
+ */
+export declare function groupComponentPolicyDiagnostics(diagnostics: readonly ComponentPolicyDiagnostic[], maxNames?: number): GroupedComponentPolicyDiagnostic[];
+/** Host-facing warning text for one grouped diagnostic. */
+export declare function formatComponentPolicyWarning(grouped: GroupedComponentPolicyDiagnostic, location: string, hint?: string): string;