nudge-ui 0.2.0

package/dist/compiler/componentPolicyResolution.js

@@ -0,0 +1,388 @@
+import { childNodes, identifier, isNode, jsxMemberName, parseModule, } from "./ast.js";
+import { stripModuleExtension } from "./sourcePaths.js";
+/** Merge a host's protocol additions over a shared compatibility catalog. */
+export function mergeComponentModuleProtocols(defaults, overrides) {
+    if (!overrides)
+        return defaults;
+    const merged = { ...defaults };
+    for (const [source, override] of Object.entries(overrides)) {
+        if (!override)
+            continue;
+        const fallback = defaults[source];
+        merged[source] = {
+            ...fallback,
+            ...override,
+            exports: {
+                ...fallback?.exports,
+                ...override.exports,
+            },
+        };
+    }
+    return merged;
+}
+/** A resolution failure that carries only the reason a host reports. */
+function unresolved(code) {
+    return { resolved: false, code };
+}
+const MAX_REEXPORT_DEPTH = 24;
+/**
+ * Analyses are a pure function of module source, so a content-addressed cache
+ * is correct across HMR without host-specific invalidation: an edited file
+ * simply misses and is re-analysed, while every unchanged re-export target
+ * skips its parse. Without this, policy resolution reparses every reachable
+ * module on every transform.
+ */
+const ANALYSIS_CACHE_LIMIT = 128;
+const analysisCache = new Map();
+function analyseModuleSource(code) {
+    const cached = analysisCache.get(code);
+    if (cached !== undefined)
+        return cached;
+    const ast = parseModule(code);
+    const analysis = ast ? analyseModule(ast) : null;
+    if (analysisCache.size >= ANALYSIS_CACHE_LIMIT) {
+        const oldest = analysisCache.keys().next();
+        if (!oldest.done)
+            analysisCache.delete(oldest.value);
+    }
+    analysisCache.set(code, analysis);
+    return analysis;
+}
+/**
+ * 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 async function resolveHostComponentPolicy(code, importer, adapter, options = {}) {
+    const analysis = analyseModuleSource(code);
+    if (!analysis) {
+        return { components: {}, diagnostics: [] };
+    }
+    const components = {};
+    const diagnostics = [];
+    const tracer = createTracer(adapter, options);
+    for (const componentName of analysis.importedJsxNames) {
+        const reference = importedReference(componentName, analysis.imports);
+        if (!reference)
+            continue;
+        const result = await tracer.request(reference.source, reference.exportName, importer);
+        if (result.resolved) {
+            components[componentName] = result.protocol;
+            continue;
+        }
+        diagnostics.push({
+            code: result.code,
+            componentName,
+            source: reference.source,
+            exportName: reference.exportName,
+        });
+    }
+    return { components, diagnostics };
+}
+/** Depth-first pre-order traversal of every node in a tree. */
+function visit(node, callback) {
+    callback(node);
+    for (const child of childNodes(node))
+        visit(child, callback);
+}
+function analyseModule(ast) {
+    const program = isNode(ast.program) ? ast.program : ast;
+    const imports = new Map();
+    const declarations = new Map();
+    const exports = new Map();
+    const exportAll = [];
+    for (const statement of program.body ?? []) {
+        if (statement.type === "ImportDeclaration") {
+            recordImports(statement, imports);
+            continue;
+        }
+        recordDeclaration(statement, declarations);
+        if (statement.type === "ExportDefaultDeclaration") {
+            const declaration = statement.declaration;
+            if (isNode(declaration)) {
+                const localName = identifier(declaration);
+                exports.set("default", localName
+                    ? { kind: "local", localName }
+                    : { kind: "definition", node: declaration });
+            }
+            continue;
+        }
+        if (statement.type === "ExportAllDeclaration") {
+            const source = isNode(statement.source) ? String(statement.source.value ?? "") : "";
+            if (source)
+                exportAll.push(source);
+            continue;
+        }
+        if (statement.type !== "ExportNamedDeclaration")
+            continue;
+        const source = isNode(statement.source) ? String(statement.source.value ?? "") : null;
+        const declaration = isNode(statement.declaration) ? statement.declaration : null;
+        if (declaration) {
+            recordDeclaration(declaration, declarations);
+            for (const name of declaredNames(declaration)) {
+                exports.set(name, { kind: "local", localName: name });
+            }
+        }
+        for (const specifier of statement.specifiers ?? []) {
+            const exportedName = identifier(specifier.exported);
+            const localName = identifier(specifier.local);
+            if (!exportedName || !localName)
+                continue;
+            exports.set(exportedName, source
+                ? { kind: "request", source, exportName: localName }
+                : { kind: "local", localName });
+        }
+    }
+    return {
+        imports,
+        declarations,
+        exports,
+        exportAll,
+        importedJsxNames: collectImportedJsxNames(ast, imports),
+    };
+}
+function recordImports(statement, imports) {
+    if (statement.importKind === "type" || !isNode(statement.source))
+        return;
+    const source = String(statement.source.value ?? "");
+    for (const specifier of statement.specifiers ?? []) {
+        if (specifier.importKind === "type")
+            continue;
+        const localName = identifier(specifier.local);
+        if (!localName)
+            continue;
+        imports.set(localName, {
+            source,
+            exportName: specifier.type === "ImportDefaultSpecifier" ? "default" : identifier(specifier.imported) ?? "*",
+            namespace: specifier.type === "ImportNamespaceSpecifier",
+        });
+    }
+}
+function recordDeclaration(statement, declarations) {
+    if (statement.type === "FunctionDeclaration" || statement.type === "ClassDeclaration") {
+        const name = identifier(statement.id);
+        if (name)
+            declarations.set(name, statement);
+        return;
+    }
+    if (statement.type !== "VariableDeclaration")
+        return;
+    for (const declaration of statement.declarations ?? []) {
+        const name = identifier(declaration.id);
+        if (name)
+            declarations.set(name, declaration);
+    }
+}
+function declaredNames(declaration) {
+    if (declaration.type === "FunctionDeclaration" || declaration.type === "ClassDeclaration") {
+        const name = identifier(declaration.id);
+        return name ? [name] : [];
+    }
+    if (declaration.type !== "VariableDeclaration")
+        return [];
+    return (declaration.declarations ?? [])
+        .map((item) => identifier(item.id))
+        .filter((name) => name !== null);
+}
+function collectImportedJsxNames(ast, imports) {
+    const names = new Set();
+    visit(ast, (node) => {
+        if (node.type !== "JSXOpeningElement")
+            return;
+        const name = jsxMemberName(node.name);
+        const root = name?.split(".")[0];
+        if (name && root && /^[A-Z]/.test(root) && imports.has(root))
+            names.add(name);
+    });
+    return [...names].sort();
+}
+function importedReference(componentName, imports) {
+    const [root, ...members] = componentName.split(".");
+    const binding = root ? imports.get(root) : undefined;
+    if (!binding)
+        return null;
+    const exportName = binding.namespace
+        ? members.join(".")
+        : [binding.exportName, ...members].filter(Boolean).join(".");
+    if (!exportName || exportName === "*")
+        return null;
+    return { source: binding.source, exportName };
+}
+/**
+ * Trace authored imports to the protocol of the component they name.
+ *
+ * The tracer closes over the host Adapter and the protocol catalog, so each
+ * step carries only its request, the module it sits in, and its trace state.
+ */
+function createTracer(adapter, options) {
+    async function request(source, exportName, importer, state) {
+        const declared = declaredProtocol(source, exportName, options);
+        if (declared)
+            return resolvedProtocol(source, exportName, declared);
+        if (state.depth >= MAX_REEXPORT_DEPTH)
+            return unresolved("component-export-unresolved");
+        let resolvedId;
+        try {
+            resolvedId = await adapter.resolve(source, importer);
+        }
+        catch {
+            resolvedId = null;
+        }
+        if (!resolvedId)
+            return unresolved("component-import-unresolved");
+        if (!adapter.isProjectSource(resolvedId))
+            return unresolved("component-protocol-unknown");
+        const canonicalSource = stripModuleExtension(adapter.sourcePath(resolvedId));
+        const canonicalProtocol = declaredProtocol(canonicalSource, exportName, options);
+        if (canonicalProtocol)
+            return resolvedProtocol(canonicalSource, exportName, canonicalProtocol);
+        const visitKey = `${resolvedId}\0${exportName}`;
+        if (state.visited.has(visitKey))
+            return unresolved("component-export-unresolved");
+        const moduleSource = await adapter.read(resolvedId);
+        if (moduleSource === null)
+            return unresolved("component-export-unresolved");
+        const analysis = analyseModuleSource(moduleSource);
+        if (!analysis)
+            return unresolved("component-export-unresolved");
+        return resolveExport({ analysis, moduleId: resolvedId, canonicalSource }, exportName, { visited: new Set(state.visited).add(visitKey), depth: state.depth + 1 });
+    }
+    async function resolveExport(module, exportName, state) {
+        const target = module.analysis.exports.get(exportName);
+        if (target?.kind === "request") {
+            return request(target.source, target.exportName, module.moduleId, state);
+        }
+        if (target?.kind === "definition") {
+            return followReference(expressionReference(target.node, module.analysis.imports), module, exportName, state);
+        }
+        if (target?.kind === "local") {
+            return resolveLocal(module, target.localName, exportName, state);
+        }
+        const candidates = [];
+        for (const source of module.analysis.exportAll) {
+            const candidate = await request(source, exportName, module.moduleId, state);
+            if (candidate.resolved)
+                candidates.push(candidate);
+        }
+        if (candidates.length === 1)
+            return candidates[0];
+        return unresolved("component-export-unresolved");
+    }
+    async function resolveLocal(module, localName, exportedName, state) {
+        const imported = module.analysis.imports.get(localName);
+        if (imported && !imported.namespace) {
+            return request(imported.source, imported.exportName, module.moduleId, state);
+        }
+        const declaration = module.analysis.declarations.get(localName);
+        if (!declaration)
+            return unresolved("component-export-unresolved");
+        if (declaration.type !== "VariableDeclarator") {
+            return projectProtocol(module.canonicalSource, exportedName);
+        }
+        return followReference(expressionReference(declaration.init, module.analysis.imports), module, exportedName, state);
+    }
+    function followReference(reference, module, exportedName, state) {
+        if (!reference)
+            return projectProtocol(module.canonicalSource, exportedName);
+        if (reference.kind === "local") {
+            return resolveLocal(module, reference.localName, exportedName, state);
+        }
+        return request(reference.source, reference.exportName, module.moduleId, state);
+    }
+    return {
+        /** Resolve one authored import to the protocol of the component it names. */
+        request: (source, exportName, importer) => request(source, exportName, importer, { visited: new Set(), depth: 0 }),
+    };
+}
+function expressionReference(expression, imports) {
+    let current = isNode(expression) ? expression : null;
+    while (current && ["TSAsExpression", "TSTypeAssertion", "TSNonNullExpression"].includes(current.type)) {
+        current = isNode(current.expression) ? current.expression : null;
+    }
+    if (!current)
+        return null;
+    if (current.type === "Identifier") {
+        const name = identifier(current);
+        if (!name)
+            return null;
+        const imported = imports.get(name);
+        return imported && !imported.namespace
+            ? { kind: "request", source: imported.source, exportName: imported.exportName }
+            : { kind: "local", localName: name };
+    }
+    if (current.type !== "MemberExpression")
+        return null;
+    const object = identifier(current.object);
+    const property = identifier(current.property);
+    const imported = object ? imports.get(object) : undefined;
+    if (!imported || !property)
+        return null;
+    return {
+        kind: "request",
+        source: imported.source,
+        exportName: imported.namespace ? property : `${imported.exportName}.${property}`,
+    };
+}
+function declaredProtocol(source, exportName, options) {
+    const moduleProtocol = options.moduleProtocols?.[source];
+    const normalizedExportName = exportName.replace(/^default\./, "");
+    const protocol = moduleProtocol?.exports?.[exportName]
+        ?? moduleProtocol?.exports?.[normalizedExportName]
+        ?? moduleProtocol?.default;
+    if (protocol)
+        return protocol;
+    return options.compatibleComponentImports?.[source]?.includes(exportName) === true
+        ? { wrap: true }
+        : null;
+}
+function resolvedProtocol(source, exportName, protocol) {
+    return {
+        resolved: true,
+        protocol: {
+            ...protocol,
+            componentId: `${stripModuleExtension(source)}#${exportName}`,
+        },
+    };
+}
+/**
+ * Default protocol for a component that resolves to project-owned source.
+ *
+ * The inspected codebase owns the definition, so replacing the element type is
+ * safe and its authored `children` may be traversed. Named JSX props stay
+ * opaque: only a host-declared protocol can promise that a named slot renders
+ * its contents.
+ */
+function projectProtocol(source, exportName) {
+    return resolvedProtocol(source, exportName, { wrap: true, slots: { children: "rendered" } });
+}
+/**
+ * Roll per-component diagnostics up so a host emits one warning per package
+ * instead of one per skipped export.
+ */
+export function groupComponentPolicyDiagnostics(diagnostics, maxNames = 5) {
+    const groups = new Map();
+    for (const diagnostic of diagnostics) {
+        const key = `${diagnostic.code}\0${diagnostic.source}`;
+        const group = groups.get(key);
+        if (group)
+            group.push(diagnostic);
+        else
+            groups.set(key, [diagnostic]);
+    }
+    return [...groups].map(([key, group]) => ({
+        key,
+        source: group[0].source,
+        componentNames: group.slice(0, maxNames).map((diagnostic) => diagnostic.componentName),
+        total: group.length,
+    }));
+}
+/** Host-facing warning text for one grouped diagnostic. */
+export function formatComponentPolicyWarning(grouped, location, hint = "Add componentProtocols metadata to opt in compatible package exports.") {
+    const names = grouped.componentNames.join(", ");
+    const remainder = grouped.total > grouped.componentNames.length
+        ? ` and ${grouped.total - grouped.componentNames.length} more`
+        : "";
+    return `[nudge-ui] Semantic instrumentation skipped ${grouped.source} in ${location} `
+        + `(${names}${remainder}). ${hint}`;
+}

package/dist/compiler/index.d.ts

@@ -0,0 +1,9 @@
+/** Host-neutral source compilers used by framework adapters. */
+export * from "./reactIdentity.js";
+export * from "./componentInstrumentation.js";
+export * from "./componentPolicyResolution.js";
+export * from "./reactComponentProtocols.js";
+export * from "./componentContractTypes.js";
+export * from "./componentContracts.js";
+export * from "./packageComponentContracts.js";
+export { relativePath } from "./sourcePaths.js";

package/dist/compiler/index.js

@@ -0,0 +1,9 @@
+/** Host-neutral source compilers used by framework adapters. */
+export * from "./reactIdentity.js";
+export * from "./componentInstrumentation.js";
+export * from "./componentPolicyResolution.js";
+export * from "./reactComponentProtocols.js";
+export * from "./componentContractTypes.js";
+export * from "./componentContracts.js";
+export * from "./packageComponentContracts.js";
+export { relativePath } from "./sourcePaths.js";

package/dist/compiler/packageComponentContracts.d.ts

@@ -0,0 +1,32 @@
+import ts from "typescript";
+import type { ComponentContract } from "./componentContractTypes.js";
+/**
+ * Identifies a package import from the host module that uses it.
+ *
+ * The host path is intentional: TypeScript uses it as the resolution anchor,
+ * so the same module specifier can resolve to a different installed package in
+ * each application. The returned contract identity always uses the import
+ * specifier, never an absolute node_modules path.
+ */
+export interface PackageContractContext {
+    hostFile: string;
+    moduleSpecifier: string;
+    compilerOptions?: ts.CompilerOptions;
+}
+export interface PackageContractCatalogContext {
+    hostFile: string;
+    moduleSpecifiers: readonly string[];
+    compilerOptions?: ts.CompilerOptions;
+}
+/** Returns bare modules whose imported bindings are rendered as JSX. */
+export declare function collectPackageComponentModules(code: string, fileName: string): string[];
+/**
+ * Extracts scalar controls from component exports in an installed package.
+ *
+ * It follows TypeScript's resolved module graph, including barrel re-exports
+ * and declaration-file aliases, rather than trying to parse one declaration
+ * file in isolation.
+ */
+export declare function extractPackageComponentContracts(context: PackageContractContext): ComponentContract[];
+/** Extracts several package modules through one declaration-only program. */
+export declare function extractPackageComponentContractCatalog(context: PackageContractCatalogContext): ComponentContract[];