@oddkin/analyzer 0.0.0-stage → 1.0.0-beta.0

package/dist/extract.js

@@ -0,0 +1,1570 @@
+/**
+ * Static extraction over a TypeScript program. Never imports or executes analyzed modules.
+ * Contract: docs/architecture/metadata-and-analyzer.md §2.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, relative, resolve, sep } from 'node:path';
+import ts from 'typescript';
+import { createPublishedReader } from './published.js';
+import { styleMappingsOf, } from './style-mappings.js';
+const ODDKIN_CORE = /(?:[\\/]|^)(?:@oddkin[\\/]core|packages[\\/]core)[\\/]/;
+const ODDKIN_LAYOUT = /(?:[\\/]|^)(?:@oddkin[\\/]components|packages[\\/]components)[\\/](?:src|dist)[\\/]layout[\\/]/;
+const TAG_NAME = /^[a-z][a-z0-9._-]*-[a-z0-9._-]*$/;
+const DOC_TAGS = [
+    'a11y',
+    'keyboard',
+    'category',
+    'useFor',
+    'notFor',
+    'limitation',
+    'related',
+    'deprecated',
+    'since',
+    'replacement',
+    'migration',
+    'customization',
+    'previewRole',
+    'updated',
+];
+/** A real calendar date written `YYYY-MM-DD`. */
+const isDate = (value) => /^\d{4}-\d{2}-\d{2}$/.test(value) &&
+    !Number.isNaN(Date.parse(value)) &&
+    new Date(`${value}T00:00:00Z`).toISOString().startsWith(value);
+export function extract(program, root) {
+    const checker = program.getTypeChecker();
+    const diagnostics = [];
+    const components = new Map();
+    const registrations = [];
+    const recipes = [];
+    const models = [];
+    const definitions = new Map();
+    const exportsBySource = new Map();
+    const published = createPublishedReader();
+    const publishedComponents = new Map();
+    const templateSources = new Map();
+    const styleSources = new Map();
+    const rel = (file) => relative(root, file).split(sep).join('/');
+    const where = (node) => {
+        const source = node.getSourceFile();
+        const { line, character } = source.getLineAndCharacterOfPosition(node.getStart(source));
+        return { file: rel(source.fileName), line: line + 1, column: character + 1 };
+    };
+    const report = (code, node, message, suggestion, severity = 'warning') => diagnostics.push({
+        code,
+        severity,
+        message,
+        source: where(node),
+        ...(suggestion ? { suggestion } : {}),
+    });
+    const resolveSymbol = (node) => {
+        const symbol = checker.getSymbolAtLocation(node);
+        return symbol && symbol.flags & ts.SymbolFlags.Alias
+            ? checker.getAliasedSymbol(symbol)
+            : symbol;
+    };
+    const fromOddkinCore = (node, name) => {
+        const symbol = resolveSymbol(node);
+        return (!!symbol &&
+            symbol.name === name &&
+            !!symbol.declarations?.some((d) => ODDKIN_CORE.test(d.getSourceFile().fileName)));
+    };
+    // `defineLayoutRecipe` from core or from the Oddkin-bound `@oddkin/components/layout`.
+    const isRecipeDefinition = (node) => {
+        if (fromOddkinCore(node, 'defineLayoutRecipe'))
+            return true;
+        const symbol = resolveSymbol(node);
+        return (symbol?.name === 'defineLayoutRecipe' &&
+            !!symbol.declarations?.some((d) => ODDKIN_LAYOUT.test(d.getSourceFile().fileName)));
+    };
+    // Recipes are defined at module scope; a call inside a function is a wrapper or factory.
+    const insideFunction = (node) => {
+        for (let parent = node.parent; parent; parent = parent.parent)
+            if (ts.isFunctionLike(parent))
+                return true;
+        return false;
+    };
+    const isLibrarySource = (file) => !file.isDeclarationFile &&
+        !program.isSourceFileFromExternalLibrary(file) &&
+        !file.fileName.includes('/node_modules/');
+    const literal = (node) => {
+        if (!node)
+            return { known: false };
+        if (ts.isStringLiteralLike(node) || ts.isNumericLiteral(node))
+            return { known: true, value: node.getText() };
+        if (node.kind === ts.SyntaxKind.TrueKeyword ||
+            node.kind === ts.SyntaxKind.FalseKeyword ||
+            node.kind === ts.SyntaxKind.NullKeyword) {
+            return { known: true, value: node.getText() };
+        }
+        if (ts.isPrefixUnaryExpression(node) && ts.isNumericLiteral(node.operand))
+            return { known: true, value: node.getText() };
+        return { known: false };
+    };
+    const stringOf = (node) => node && ts.isStringLiteralLike(node) ? node.text : undefined;
+    const booleanOf = (node) => node?.kind === ts.SyntaxKind.TrueKeyword
+        ? true
+        : node?.kind === ts.SyntaxKind.FalseKeyword
+            ? false
+            : undefined;
+    const objectEntries = (node, owner) => {
+        const out = new Map();
+        for (const property of node.properties) {
+            if (ts.isPropertyAssignment(property) &&
+                (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name))) {
+                out.set(property.name.text, property.initializer);
+            }
+            else if (ts.isShorthandPropertyAssignment(property)) {
+                out.set(property.name.text, property.name);
+            }
+            else {
+                report('analyzer.dynamic.property', property, `${owner}: a spread or computed entry cannot be analyzed statically.`, 'Write each entry as a literal key: value.');
+            }
+        }
+        return out;
+    };
+    const docOf = (node) => {
+        const symbol = node.name
+            ? checker.getSymbolAtLocation(node.name)
+            : undefined;
+        const text = symbol
+            ? ts.displayPartsToString(symbol.getDocumentationComment(checker)).trim()
+            : '';
+        return text || undefined;
+    };
+    /** `@deprecated` and its companion tags in the JSDoc of a member or variable. */
+    const deprecationOf = (node) => {
+        const tags = node ? ts.getJSDocTags(node) : [];
+        const deprecated = tags.find((t) => t.tagName.text === 'deprecated');
+        if (!deprecated)
+            return undefined;
+        const text = (tag) => tag
+            ? (typeof tag.comment === 'string'
+                ? tag.comment
+                : (ts.getTextOfJSDocComment(tag.comment) ?? '')).trim() || undefined
+            : undefined;
+        const named = (name) => text(tags.find((t) => t.tagName.text === name));
+        const reason = text(deprecated);
+        const replacement = named('replacement');
+        const migration = named('migration');
+        return {
+            ...(reason ? { reason } : {}),
+            ...(replacement ? { replacement } : {}),
+            ...(migration ? { migration } : {}),
+            location: where(deprecated),
+        };
+    };
+    // ---- prop.* definitions ----
+    function properties(definitions, className) {
+        const out = [];
+        for (const [name, initializer] of objectEntries(definitions, `${className}.with()`)) {
+            const call = initializer;
+            const callee = ts.isCallExpression(call) && ts.isPropertyAccessExpression(call.expression)
+                ? call.expression
+                : undefined;
+            if (!callee || !ts.isCallExpression(call) || !fromOddkinCore(callee.expression, 'prop')) {
+                report('analyzer.dynamic.definition', initializer, `${className}.${name} is not a prop.*() call; its contract cannot be extracted.`, 'Define it inline, e.g. name: prop.string({ default: "…" }).');
+                continue;
+            }
+            const kind = callee.name.text;
+            const values = kind === 'enum' && call.arguments[0] && ts.isArrayLiteralExpression(call.arguments[0])
+                ? call.arguments[0].elements.map((e) => stringOf(e) ?? e.getText())
+                : undefined;
+            const optionsNode = kind === 'enum' ? call.arguments[1] : call.arguments[0];
+            const options = optionsNode && ts.isObjectLiteralExpression(optionsNode)
+                ? objectEntries(optionsNode, `${className}.${name}`)
+                : new Map();
+            if (optionsNode && !ts.isObjectLiteralExpression(optionsNode))
+                report('analyzer.dynamic.options', optionsNode, `${className}.${name}: options must be an object literal.`);
+            const attributeNode = options.get('attribute');
+            const propertyOnly = kind === 'object' ||
+                kind === 'array' ||
+                (kind === 'custom' && !options.has('fromAttribute'));
+            let attribute = propertyOnly
+                ? null
+                : name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+            if (attributeNode) {
+                if (attributeNode.kind === ts.SyntaxKind.FalseKeyword)
+                    attribute = null;
+                else if (stringOf(attributeNode) !== undefined)
+                    attribute = stringOf(attributeNode);
+                else
+                    report('analyzer.dynamic.attribute', attributeNode, `${className}.${name}: attribute must be a string literal or false.`);
+            }
+            const reflects = booleanOf(options.get('reflect')) ?? false;
+            const defaultNode = options.get('default');
+            const fallback = kind === 'boolean'
+                ? { known: true, value: 'false' }
+                : kind === 'array' && !defaultNode
+                    ? { known: true, value: '[]' }
+                    : defaultNode
+                        ? literal(defaultNode)
+                        : { known: true, value: 'undefined' };
+            if (defaultNode &&
+                !fallback.known &&
+                !ts.isArrowFunction(defaultNode) &&
+                !ts.isFunctionExpression(defaultNode)) {
+                report('analyzer.dynamic.value', defaultNode, `${className}.${name}: the default is computed; it is recorded as unknown.`);
+            }
+            const description = stringOf(options.get('description'));
+            const deprecated = deprecationOf(initializer.parent);
+            out.push({
+                name,
+                kind,
+                type: '',
+                attribute,
+                reflects,
+                default: fallback,
+                ...(values ? { values } : {}),
+                ...(description ? { description } : {}),
+                ...(deprecated ? { deprecated } : {}),
+            });
+        }
+        return out;
+    }
+    // ---- events ----
+    function eventFrom(expression, owner) {
+        let call = expression;
+        let variable;
+        if (ts.isIdentifier(call)) {
+            // Shorthand entries ({ countChange }) name the variable through the shorthand symbol.
+            const shorthand = ts.isShorthandPropertyAssignment(call.parent)
+                ? checker.getShorthandAssignmentValueSymbol(call.parent)
+                : undefined;
+            const symbol = shorthand ?? resolveSymbol(call);
+            const declaration = (symbol && symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol)?.valueDeclaration;
+            if (declaration && ts.isVariableDeclaration(declaration) && declaration.initializer) {
+                variable = declaration;
+                call = declaration.initializer;
+            }
+        }
+        if (!ts.isCallExpression(call) || !fromOddkinCore(call.expression, 'event')) {
+            report('analyzer.dynamic.event', expression, `${owner}: events must be defined with event<Detail>('name', { … }).`);
+            return undefined;
+        }
+        const name = stringOf(call.arguments[0]);
+        const init = call.arguments[1];
+        if (!name || !init || !ts.isObjectLiteralExpression(init)) {
+            report('analyzer.dynamic.event', call, `${owner}: the event name and options must be literals.`);
+            return undefined;
+        }
+        const options = objectEntries(init, `${owner} event`);
+        const typeArgument = call.typeArguments?.[0];
+        const detailType = typeArgument
+            ? checker.typeToString(checker.getTypeFromTypeNode(typeArgument))
+            : 'void';
+        const syncs = stringOf(options.get('syncs'));
+        const intentNode = options.get('intent');
+        const intentValue = stringOf(intentNode);
+        const intent = intentNode && (intentValue === 'user' || intentValue === 'notification')
+            ? { value: intentValue, source: where(intentNode) }
+            : undefined;
+        if (intentNode && !intent)
+            report('analyzer.dynamic.value', intentNode, `${owner} event "${name}": intent must be the literal 'user' or 'notification'; it is recorded as unknown.`);
+        const description = stringOf(options.get('description')) ?? (variable ? docOf(variable) : undefined);
+        const deprecated = deprecationOf(variable);
+        return {
+            name,
+            detailType,
+            bubbles: booleanOf(options.get('bubbles')) ?? false,
+            composed: booleanOf(options.get('composed')) ?? false,
+            cancelable: booleanOf(options.get('cancelable')) ?? false,
+            ...(syncs ? { syncs } : {}),
+            ...(intent ? { intent } : {}),
+            ...(description ? { description } : {}),
+            ...(deprecated ? { deprecated } : {}),
+        };
+    }
+    // ---- templates and styles ----
+    const templateText = (node) => ts.isNoSubstitutionTemplateLiteral(node)
+        ? node.text
+        : [node.head.text, ...node.templateSpans.map((s) => s.literal.text)].join('\u0000');
+    function scanTemplates(body, tag, visit) {
+        const walk = (node) => {
+            if (ts.isTaggedTemplateExpression(node) &&
+                ts.isIdentifier(node.tag) &&
+                (node.tag.text === tag ||
+                    (tag === 'html' && (node.tag.text === 'svg' || node.tag.text === 'composite')))) {
+                visit(templateText(node.template), node);
+            }
+            ts.forEachChild(node, walk);
+        };
+        walk(body);
+    }
+    const attributeValue = (attributes, name) => new RegExp(`(?:^|\\s)${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s"'>]+))`).exec(attributes);
+    /**
+     * CSS custom properties read with `var()` and tokens read with `var(--odd-…)` or `token()`.
+     * Private `--_*` properties are the element's own wiring, not a customization path.
+     */
+    function styleReads(node) {
+        const cssProperties = [];
+        const tokens = [];
+        scanTemplates(node, 'css', (text, template) => {
+            for (const match of text.matchAll(/var\(\s*(--[\w-]+)/g)) {
+                const variable = match[1];
+                if (variable.startsWith('--_'))
+                    continue;
+                (variable.startsWith('--odd-') ? tokens : cssProperties).push(variable);
+            }
+            const walk = (child) => {
+                if (ts.isCallExpression(child) &&
+                    ts.isIdentifier(child.expression) &&
+                    child.expression.text === 'token') {
+                    const name = stringOf(child.arguments[0]);
+                    if (name)
+                        tokens.push(name);
+                }
+                ts.forEachChild(child, walk);
+            };
+            walk(template);
+        });
+        return { cssProperties, tokens };
+    }
+    /** Slots and parts a template renders. */
+    function templateAnatomy(node) {
+        const found = { slots: new Set(), parts: new Set() };
+        scanTemplates(node, 'html', (text) => {
+            for (const match of text.matchAll(/<slot\b([^>]*)>/g)) {
+                const name = attributeValue(match[1] ?? '', 'name');
+                found.slots.add(name ? (name[1] ?? name[2] ?? name[3] ?? '') : '');
+            }
+            // A composite's role element (`<${roles.x}`) is a tag written as a substitution.
+            for (const match of text.matchAll(/<(?:[a-zA-Z][\w-]*\b|\u0000)([^>]*)>/g)) {
+                const part = attributeValue(match[1] ?? '', 'part');
+                for (const name of (part ? (part[1] ?? part[2] ?? part[3] ?? '') : '').split(/\s+/))
+                    if (name)
+                        found.parts.add(name);
+            }
+        });
+        return found;
+    }
+    /**
+     * Which of a component's parts each tag and class selects, read from every template in the
+     * template's file (helpers beside it render into the same shadow root).
+     */
+    function partSelectors(node, componentParts) {
+        const tags = new Map();
+        const classes = new Map();
+        const all = new Set();
+        const computedClass = new Set();
+        const add = (map, key, names) => map.set(key, [...new Set([...(map.get(key) ?? []), ...names])]);
+        const valueOf = (attributes, name) => {
+            const value = attributeValue(attributes, name);
+            return value ? (value[1] ?? value[2] ?? value[3] ?? '') : '';
+        };
+        scanTemplates(node.getSourceFile(), 'html', (text) => {
+            for (const match of text.matchAll(/<([a-zA-Z][\w-]*)\b([^>]*)>/g)) {
+                const attributes = match[2] ?? '';
+                const names = valueOf(attributes, 'part')
+                    .split(/\s+/)
+                    .filter((name) => componentParts.has(name));
+                if (!names.length)
+                    continue;
+                for (const name of names)
+                    all.add(name);
+                add(tags, match[1].toLowerCase(), names);
+                const classList = valueOf(attributes, 'class');
+                if (classList.includes('\u0000'))
+                    for (const name of names)
+                        computedClass.add(name);
+                for (const name of classList.split(/\s+/))
+                    if (name && !name.includes('\u0000'))
+                        add(classes, name, names);
+            }
+        });
+        return { tags, classes, all: [...all], computedClass: [...computedClass] };
+    }
+    /**
+     * A style source's CSS with each `token('name')` written as `token(name)`, each interpolated
+     * style source of this library (`${recipeStyles}`) as its own CSS, and any other substitution
+     * as `unknown()`: a css`` template or `unsafeCSS('…')`. `undefined` otherwise.
+     */
+    function tokenCss(node) {
+        if (ts.isCallExpression(node) &&
+            ts.isIdentifier(node.expression) &&
+            node.expression.text === 'unsafeCSS')
+            return stringOf(node.arguments[0]);
+        if (!ts.isTaggedTemplateExpression(node) ||
+            !ts.isIdentifier(node.tag) ||
+            node.tag.text !== 'css')
+            return undefined;
+        const template = node.template;
+        if (ts.isNoSubstitutionTemplateLiteral(template))
+            return template.text;
+        let text = template.head.text;
+        for (const span of template.templateSpans) {
+            const expression = span.expression;
+            const name = ts.isCallExpression(expression) &&
+                ts.isIdentifier(expression.expression) &&
+                expression.expression.text === 'token'
+                ? stringOf(expression.arguments[0])
+                : undefined;
+            const found = ts.isIdentifier(expression) ? initializerOf(expression) : undefined;
+            const inner = found ? tokenCss(found.node) : undefined;
+            text += (name ? `token(${name})` : (inner ?? 'unknown()')) + span.literal.text;
+        }
+        return text;
+    }
+    const sourceKey = (ref) => `${ref.file}#${ref.name}`;
+    /** Record an exported style source of the analyzed library. */
+    function recordStyles(ref, node) {
+        if (!styleSources.has(sourceKey(ref))) {
+            const css = tokenCss(node);
+            styleSources.set(sourceKey(ref), {
+                ref,
+                ...styleReads(node),
+                ...(css === undefined ? {} : { css }),
+            });
+        }
+    }
+    /** A section of another package's `oddkin.metadata.json` entry, by module path and name. */
+    function publishedSource(pkg, section, module, name) {
+        const entries = pkg.metadata?.[section];
+        return entries?.[`${module}#${name}`];
+    }
+    const publishedReads = (pkg, module, name) => {
+        const entry = publishedSource(pkg, 'styles', module, name);
+        return entry
+            ? {
+                cssProperties: entry.cssProperties ?? [],
+                tokens: entry.tokens ?? [],
+                ...(typeof entry.css === 'string' ? { css: entry.css } : {}),
+            }
+            : undefined;
+    };
+    // ---- classes ----
+    function heritage(node) {
+        return node.heritageClauses?.find((h) => h.token === ts.SyntaxKind.ExtendsKeyword)?.types[0]
+            ?.expression;
+    }
+    function classify(node) {
+        if (components.has(node))
+            return components.get(node);
+        components.set(node, null);
+        // Diagnostics raised for this class (after its base is resolved) can be covered by explicit metadata.
+        let diagnosticsBefore = diagnostics.length;
+        const expression = heritage(node);
+        if (!expression || !node.name)
+            return null;
+        const className = node.name.text;
+        let base = null;
+        let superclass;
+        let own = [];
+        const baseOf = (target) => {
+            if (fromOddkinCore(target, 'OddkinElement')) {
+                superclass = { name: 'OddkinElement', package: '@oddkin/core' };
+                return true;
+            }
+            const declaration = resolveSymbol(target)?.declarations?.find(ts.isClassDeclaration);
+            if (declaration && isLibrarySource(declaration.getSourceFile())) {
+                base = classify(declaration);
+                if (base)
+                    superclass = { name: base.name, file: base.file };
+                return !!base;
+            }
+            // An element class another package publishes: its contract comes from that package's CEM.
+            if (declaration?.getSourceFile().isDeclarationFile) {
+                base = publishedComponent(declaration, target);
+                if (base)
+                    superclass = { name: base.name, package: base.package };
+                return !!base;
+            }
+            return false;
+        };
+        if (ts.isCallExpression(expression) &&
+            ts.isPropertyAccessExpression(expression.expression) &&
+            expression.expression.name.text === 'with') {
+            if (!baseOf(expression.expression.expression))
+                return null;
+            diagnosticsBefore = diagnostics.length;
+            const definitions = expression.arguments[0];
+            if (definitions && ts.isObjectLiteralExpression(definitions))
+                own = properties(definitions, className);
+            else
+                report('analyzer.dynamic.definitions', expression, `${className}: with() needs an object literal of prop.*() definitions.`);
+        }
+        else if (!baseOf(expression))
+            return null;
+        else
+            diagnosticsBefore = diagnostics.length;
+        const instanceType = checker.getDeclaredTypeOfSymbol(checker.getSymbolAtLocation(node.name));
+        const typeOf = (name) => {
+            const symbol = instanceType.getProperty(name);
+            return symbol
+                ? checker.typeToString(checker.getTypeOfSymbolAtLocation(symbol, node))
+                : 'unknown';
+        };
+        own = own.map((p) => ({ ...p, type: typeOf(p.name) }));
+        const ref = { name: className, file: rel(node.getSourceFile().fileName) };
+        const inherit = (items, from) => (items ?? []).map((item) => item.inheritedFrom
+            ? item
+            : {
+                ...item,
+                inheritedFrom: {
+                    name: from.name,
+                    file: from.file,
+                    ...(from.package
+                        ? { package: from.package }
+                        : {}),
+                },
+            });
+        const parent = base;
+        const events = [];
+        const eventKeys = [];
+        const members = [];
+        const cssStates = new Map();
+        const slots = new Map();
+        const parts = new Map();
+        const cssProperties = new Map();
+        const tokenReads = new Map();
+        const styleNames = new Set();
+        const styleTokens = new Set();
+        const renderSlots = new Set();
+        const renderParts = new Set();
+        for (const member of node.members) {
+            const modifiers = ts.canHaveModifiers(member) ? (ts.getModifiers(member) ?? []) : [];
+            const isStatic = modifiers.some((m) => m.kind === ts.SyntaxKind.StaticKeyword);
+            const hidden = modifiers.some((m) => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword) ||
+                (member.name && ts.isPrivateIdentifier(member.name)) ||
+                ts.getJSDocTags(member).some((t) => t.tagName.text === 'internal');
+            const memberName = member.name && (ts.isIdentifier(member.name) || ts.isStringLiteral(member.name))
+                ? member.name.text
+                : undefined;
+            if (isStatic &&
+                memberName === 'events' &&
+                ts.isPropertyDeclaration(member) &&
+                member.initializer) {
+                if (ts.isObjectLiteralExpression(member.initializer)) {
+                    for (const [key, value] of objectEntries(member.initializer, `${className}.events`)) {
+                        const info = eventFrom(value, className);
+                        if (info) {
+                            events.push(info);
+                            eventKeys.push({ key, name: info.name, node: value });
+                        }
+                    }
+                }
+                else
+                    report('analyzer.dynamic.event', member.initializer, `${className}.events must be an object literal.`);
+            }
+            if (isStatic &&
+                memberName === 'styles' &&
+                ts.isPropertyDeclaration(member) &&
+                member.initializer) {
+                const read = styleReads(member.initializer);
+                for (const name of read.cssProperties) {
+                    cssProperties.set(name, { name });
+                    styleNames.add(name);
+                }
+                for (const token of read.tokens) {
+                    tokenReads.set(token, { token, readThrough: 'stylesheet' });
+                    styleTokens.add(token);
+                }
+            }
+            if (!isStatic && !hidden && memberName && !memberName.startsWith('_')) {
+                if ((ts.isGetAccessorDeclaration(member) || ts.isPropertyDeclaration(member)) &&
+                    memberName !== 'render') {
+                    const setter = node.members.some((m) => ts.isSetAccessorDeclaration(m) && m.name.getText() === memberName);
+                    const readonly = ts.isGetAccessorDeclaration(member)
+                        ? !setter
+                        : modifiers.some((m) => m.kind === ts.SyntaxKind.ReadonlyKeyword);
+                    const description = docOf(member);
+                    members.push({
+                        kind: 'field',
+                        name: memberName,
+                        type: typeOf(memberName),
+                        readonly,
+                        ...(description ? { description } : {}),
+                    });
+                }
+                else if (ts.isMethodDeclaration(member)) {
+                    const signature = checker.getSignatureFromDeclaration(member);
+                    const description = docOf(member);
+                    members.push({
+                        kind: 'method',
+                        name: memberName,
+                        type: signature ? checker.signatureToString(signature) : '',
+                        readonly: false,
+                        ...(description ? { description } : {}),
+                    });
+                }
+            }
+            if (memberName === 'render' && ts.isMethodDeclaration(member) && member.body) {
+                scanTemplates(member.body, 'html', (text) => {
+                    for (const match of text.matchAll(/<slot\b([^>]*)>/g)) {
+                        const name = attributeValue(match[1] ?? '', 'name');
+                        const slot = name ? (name[1] ?? name[2] ?? name[3] ?? '') : '';
+                        slots.set(slot, { name: slot });
+                        renderSlots.add(slot);
+                    }
+                    for (const match of text.matchAll(/<[a-zA-Z][\w-]*\b([^>]*)>/g)) {
+                        const part = attributeValue(match[1] ?? '', 'part');
+                        for (const name of (part ? (part[1] ?? part[2] ?? part[3] ?? '') : '')
+                            .split(/\s+/)
+                            .filter(Boolean)) {
+                            parts.set(name, { name });
+                            renderParts.add(name);
+                        }
+                    }
+                });
+            }
+        }
+        // Custom states set with this.setState('name', …) and token() references anywhere in the class.
+        // Events it emits (`this.emit(def)` or `emit(this, def)`) are compared with the declared ones.
+        const emitted = [];
+        const walk = (child) => {
+            if (ts.isCallExpression(child)) {
+                const callee = child.expression;
+                if (ts.isPropertyAccessExpression(callee) &&
+                    callee.expression.kind === ts.SyntaxKind.ThisKeyword &&
+                    callee.name.text === 'setState') {
+                    const state = stringOf(child.arguments[0]);
+                    if (state)
+                        cssStates.set(state, { name: state });
+                    else
+                        report('analyzer.dynamic.state', child, `${className}: setState() with a computed name cannot be documented.`);
+                }
+                if (ts.isIdentifier(callee) && callee.text === 'token') {
+                    const name = stringOf(child.arguments[0]);
+                    if (name)
+                        tokenReads.set(name, { token: name, readThrough: 'stylesheet' });
+                }
+                const definition = ts.isPropertyAccessExpression(callee) &&
+                    callee.expression.kind === ts.SyntaxKind.ThisKeyword &&
+                    callee.name.text === 'emit'
+                    ? child.arguments[0]
+                    : fromOddkinCore(callee, 'emit') &&
+                        child.arguments[0]?.kind === ts.SyntaxKind.ThisKeyword
+                        ? child.arguments[1]
+                        : undefined;
+                const variable = definition && ts.isIdentifier(definition)
+                    ? resolveSymbol(definition)?.valueDeclaration
+                    : undefined;
+                if (variable &&
+                    ts.isVariableDeclaration(variable) &&
+                    variable.initializer &&
+                    ts.isCallExpression(variable.initializer) &&
+                    fromOddkinCore(variable.initializer.expression, 'event')) {
+                    const name = stringOf(variable.initializer.arguments[0]);
+                    if (name)
+                        emitted.push({ name, node: child });
+                }
+            }
+            ts.forEachChild(child, walk);
+        };
+        walk(node);
+        const declaredEvents = new Set([...(parent?.events ?? []), ...events].map((e) => e.name));
+        // `_events` (ElementEvents<typeof Class>) types listeners by key, so keys must be the names.
+        if (node.members.some((m) => m.name && ts.isIdentifier(m.name) && m.name.text === '_events'))
+            for (const { key, name, node: value } of eventKeys)
+                if (key !== name)
+                    report('analyzer.event.key', value, `${className}.events key "${key}" differs from the event name "${name}", so typed listeners would expect "${key}".`, `Key the entry by the event name: '${name}': …`);
+        for (const { name, node: call } of emitted)
+            if (!declaredEvents.has(name))
+                report('analyzer.event.undeclared', call, `${className} emits "${name}" without declaring it in static events, so the published contract omits it.`, `Add the event definition to ${className}.events.`);
+        // JSDoc tags: CEM conventions (@slot, @csspart, @cssprop, @cssstate) and Oddkin tags.
+        const tags = {};
+        for (const tag of ts.getJSDocTags(node)) {
+            const tagName = tag.tagName.text;
+            const comment = (typeof tag.comment === 'string'
+                ? tag.comment
+                : (ts.getTextOfJSDocComment(tag.comment) ?? '')).trim();
+            const [first = '', ...restWords] = comment.split(/\s+/);
+            const rest = restWords.join(' ').replace(/^-\s*/, '');
+            const named = { name: first, ...(rest ? { description: rest } : {}) };
+            if (tagName === 'slot') {
+                slots.set(first === '-' ? '' : first, { ...named, name: first === '-' ? '' : first });
+                renderSlots.delete(first === '-' ? '' : first);
+            }
+            else if (tagName === 'csspart') {
+                parts.set(first, named);
+                renderParts.delete(first);
+            }
+            else if (tagName === 'cssprop' || tagName === 'cssproperty') {
+                cssProperties.set(first, named);
+                styleNames.delete(first);
+            }
+            else if (tagName === 'cssstate')
+                cssStates.set(first, named);
+            else if (DOC_TAGS.includes(tagName)) {
+                if (tagName === 'customization' && !/^[1-5]( [1-5])*$/.test(comment.replace(/\s+/g, ' ')))
+                    report('analyzer.tag.invalid', tag, `${className}: @customization lists supported ladder levels 1 to 5 ("${comment}"); the levels are recorded as unknown.`, 'Write the supported levels as numbers, e.g. @customization 1 2 3.');
+                if (tagName === 'updated' && !isDate(comment)) {
+                    report('analyzer.tag.invalid', tag, `${className}: @updated needs a calendar date written YYYY-MM-DD ("${comment}"); the page date comes from source history or is omitted.`, 'Write the date of the last meaningful change, e.g. @updated 2026-03-14.');
+                    continue;
+                }
+                (tags[tagName] ??= []).push({ value: comment, location: where(tag) });
+            }
+        }
+        const description = docOf(node);
+        const exported = !!ts.getModifiers(node)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+        const explicit = explicitMetadata(node, className, diagnosticsBefore);
+        const info = {
+            name: className,
+            file: ref.file,
+            location: where(node),
+            ...(description ? { description } : {}),
+            superclass: superclass,
+            properties: [...inherit(parent?.properties, parent), ...own],
+            // A class's own `static events` replaces its parent's at runtime, as any static field does.
+            events: events.length ? events : inherit(parent?.events, parent),
+            members: [
+                ...(parent?.members ?? []).filter((m) => !own.some((p) => p.name === m.name)),
+                ...members.filter((m) => !own.some((p) => p.name === m.name)),
+            ],
+            slots: [...(parent?.slots ?? []), ...slots.values()].filter((s, i, all) => all.findIndex((x) => x.name === s.name) === i),
+            parts: [...(parent?.parts ?? []), ...parts.values()].filter((s, i, all) => all.findIndex((x) => x.name === s.name) === i),
+            cssProperties: [...(parent?.cssProperties ?? []), ...cssProperties.values()].filter((s, i, all) => all.findIndex((x) => x.name === s.name) === i),
+            cssStates: [...(parent?.cssStates ?? []), ...cssStates.values()].filter((s, i, all) => all.findIndex((x) => x.name === s.name) === i),
+            // A documented component variable (`@cssprop --odd-button-radius`) is not a token read.
+            tokenReads: [...(parent?.tokenReads ?? []), ...tokenReads.values()].filter((s, i, all) => all.findIndex((x) => x.token === s.token) === i &&
+                !cssProperties.has(s.token) &&
+                !(parent?.cssProperties ?? []).some((c) => c.name === s.token)),
+            tags,
+            exported,
+            derived: {
+                slots: [...(parent?.derived?.slots ?? []), ...renderSlots],
+                parts: [...(parent?.derived?.parts ?? []), ...renderParts],
+                cssProperties: [...(parent?.derived?.cssProperties ?? []), ...styleNames],
+                tokens: [...(parent?.derived?.tokens ?? []), ...styleTokens],
+            },
+        };
+        /** True when the class's instance type derives from `HTMLElement`. */
+        function isElementClass(declaration) {
+            const symbol = declaration.name && checker.getSymbolAtLocation(declaration.name);
+            const pending = symbol ? [checker.getDeclaredTypeOfSymbol(symbol)] : [];
+            for (let depth = 0; pending.length && depth < 32; depth++) {
+                const type = pending.shift();
+                if (type.getSymbol()?.name === 'HTMLElement')
+                    return true;
+                if (type.isClassOrInterface())
+                    pending.push(...(checker.getBaseTypes(type) ?? []));
+                else if (type.isIntersection())
+                    pending.push(...type.types);
+            }
+            return false;
+        }
+        /**
+         * A component class published by another package, read from its `custom-elements.json`
+         * (members, attributes, events, slots, parts, CSS properties and states) and
+         * `oddkin.metadata.json` (token reads, sync pairs, and the template and style sources of its
+         * definition). The package's modules are never executed.
+         */
+        function publishedComponent(declaration, at) {
+            if (publishedComponents.has(declaration))
+                return publishedComponents.get(declaration) ?? null;
+            publishedComponents.set(declaration, null);
+            const file = declaration.getSourceFile().fileName;
+            const pkg = published(file);
+            if (!pkg || !declaration.name)
+                return null;
+            const name = declaration.name.text;
+            const module = pkg.moduleOf(file);
+            const cem = pkg.declaration(name, module);
+            if (!cem?.customElement) {
+                if (isElementClass(declaration))
+                    report('analyzer.published.missing', at, `${pkg.name} publishes no custom-elements.json declaration for ${name}; classes extending it are not documented.`, `Publish ${pkg.name} with its custom-elements.json (package.json "customElements").`);
+                return null;
+            }
+            const metadata = cem.tagName
+                ? (pkg.metadata?.['components']?.[`component:${cem.tagName}`] ?? undefined)
+                : undefined;
+            const from = { name, file: module, package: pkg.name };
+            const inherited = (value) => {
+                const ref = value;
+                return ref?.name
+                    ? { name: ref.name, file: ref.module ?? module, package: ref.package ?? pkg.name }
+                    : from;
+            };
+            const text = (value) => (typeof value === 'string' && value ? value : undefined);
+            const described = (item, description) => text(description) ? { ...item, description: text(description) } : item;
+            const named = (list) => (list ?? []).map((item) => described({ name: item.name }, item.description));
+            const syncPairs = (metadata?.['syncPairs'] ?? []);
+            const publishedIntents = (metadata?.['events'] ?? []);
+            const tag = cem.tagName;
+            const publishedDeprecations = (metadata?.['deprecations'] ?? []);
+            /** The publisher's deprecation: reason from CEM, replacement and migration from metadata. */
+            const deprecatedOf = (kind, name, value) => {
+                if (value === undefined || value === false)
+                    return {};
+                const entry = publishedDeprecations.find((d) => d.id === `${kind}:${tag}#${name}`);
+                // A member replacement is renamed with the derived tag, so keep only its name.
+                const replacement = entry?.replacement?.startsWith(`${kind}:${tag}#`)
+                    ? entry.replacement.slice(`${kind}:${tag}#`.length)
+                    : entry?.replacement;
+                return {
+                    deprecated: {
+                        ...(typeof value === 'string' && value ? { reason: value } : {}),
+                        ...(replacement ? { replacement } : {}),
+                        ...(entry?.migration ? { migration: entry.migration } : {}),
+                    },
+                };
+            };
+            const typeText = (member) => member['type']?.text;
+            const properties = [];
+            const members = [];
+            for (const member of cem.members ?? []) {
+                if (member['static'] ||
+                    member['privacy'] === 'private' ||
+                    member['privacy'] === 'protected')
+                    continue;
+                const memberName = member['name'];
+                if (member['kind'] === 'method') {
+                    members.push(described({ kind: 'method', name: memberName, type: '', readonly: false }, member['description']));
+                    continue;
+                }
+                if (member['kind'] !== 'field')
+                    continue;
+                // prop.*() fields carry an attribute or a known default; accessors and plain fields do not.
+                if (member['attribute'] !== undefined || member['default'] !== undefined) {
+                    properties.push(described({
+                        name: memberName,
+                        kind: 'published',
+                        type: typeText(member) ?? 'unknown',
+                        attribute: text(member['attribute']) ?? null,
+                        reflects: member['reflects'] === true,
+                        default: typeof member['default'] === 'string'
+                            ? { known: true, value: member['default'] }
+                            : { known: false },
+                        ...deprecatedOf('property', memberName, member['deprecated']),
+                        inheritedFrom: inherited(member['inheritedFrom']),
+                    }, member['description']));
+                }
+                else
+                    members.push(described({
+                        kind: 'field',
+                        name: memberName,
+                        type: typeText(member) ?? 'unknown',
+                        readonly: member['readonly'] === true,
+                    }, member['description']));
+            }
+            const events = (cem.events ?? []).map((event) => {
+                const type = typeText(event) ?? 'CustomEvent';
+                const detail = /^CustomEvent<(.*)>$/s.exec(type)?.[1];
+                const syncs = syncPairs.find((p) => p.event === event['name'])?.property;
+                // The publisher's declared intent; its source location belongs to that package.
+                const intent = publishedIntents.find((e) => e.event === `event:${tag}#${event['name']}`)?.intent?.value;
+                return described({
+                    name: event['name'],
+                    detailType: detail ?? 'void',
+                    bubbles: false,
+                    composed: false,
+                    cancelable: false,
+                    ...(syncs ? { syncs } : {}),
+                    ...(intent === 'user' || intent === 'notification'
+                        ? { intent: { value: intent } }
+                        : {}),
+                    ...deprecatedOf('event', event['name'], event['deprecated']),
+                    inheritedFrom: inherited(event['inheritedFrom']),
+                }, event['description']);
+            });
+            // What its definition's template and styles provide, so a recomposition can replace them.
+            const definition = metadata?.['definition'];
+            const anatomy = definition?.template
+                ? publishedSource(pkg, 'templates', definition.template.module, definition.template.name)
+                : undefined;
+            const reads = (definition?.styles ?? []).map((s) => publishedReads(pkg, s.module, s.name));
+            if ((definition?.template && !anatomy) || reads.some((r) => !r))
+                report('analyzer.published.sources', at, `${pkg.name} publishes no template or style facts for the definition of <${cem.tagName}>; facts its template and styles provide are kept when a definition replaces them.`, `Rebuild ${pkg.name} with a current @oddkin/analyzer.`, 'info');
+            const superclass = cem.superclass;
+            const info = {
+                name,
+                file: module,
+                package: pkg.name,
+                location: { file: `${pkg.name}/${module}`, line: 1, column: 1 },
+                superclass: {
+                    name: superclass?.name ?? 'OddkinElement',
+                    package: superclass?.package ?? pkg.name,
+                },
+                properties,
+                events,
+                members,
+                slots: named(cem.slots),
+                parts: named(cem.cssParts),
+                cssProperties: named(cem.cssProperties),
+                cssStates: named(cem.cssStates),
+                tokenReads: (metadata?.['tokenReads'] ?? []).map((t) => ({
+                    token: t.token,
+                    readThrough: 'stylesheet',
+                })),
+                tags: {},
+                exported: true,
+                derived: {
+                    slots: anatomy?.slots ?? [],
+                    parts: anatomy?.parts ?? [],
+                    cssProperties: reads.flatMap((r) => r?.cssProperties ?? []),
+                    tokens: reads.flatMap((r) => r?.tokens ?? []),
+                },
+            };
+            publishedComponents.set(declaration, info);
+            return info;
+        }
+        const merged = explicit ? mergeExplicit(info, explicit) : info;
+        components.set(node, merged);
+        return merged;
+    }
+    const LISTS = ['properties', 'events', 'slots', 'parts', 'cssProperties', 'cssStates'];
+    function explicitMetadata(node, className, diagnosticsBefore) {
+        const tag = ts.getJSDocTags(node).find((t) => t.tagName.text === 'oddkin-metadata');
+        if (!tag)
+            return undefined;
+        const comment = (typeof tag.comment === 'string' ? tag.comment : (ts.getTextOfJSDocComment(tag.comment) ?? '')).trim();
+        const absolutePath = resolve(dirname(node.getSourceFile().fileName), comment);
+        let data;
+        try {
+            data = JSON.parse(readFileSync(absolutePath, 'utf8'));
+        }
+        catch (error) {
+            report('analyzer.metadata.missing', tag, `${className}: cannot read explicit metadata "${comment}": ${error instanceof Error ? error.message : String(error)}.`, undefined, 'error');
+            return undefined;
+        }
+        const problems = typeof data !== 'object' || data === null || Array.isArray(data)
+            ? ['the file must contain an object']
+            : Object.entries(data).flatMap(([key, value]) => key === 'description'
+                ? typeof value === 'string'
+                    ? []
+                    : ['description must be a string']
+                : LISTS.includes(key)
+                    ? Array.isArray(value) &&
+                        value.every((v) => typeof v === 'object' &&
+                            v !== null &&
+                            typeof v.name === 'string')
+                        ? []
+                        : [`${key} must be an array of objects with a name`]
+                    : [`unknown key "${key}" (allowed: description, ${LISTS.join(', ')})`]);
+        if (problems.length) {
+            report('analyzer.metadata.invalid', tag, `${className}: explicit metadata ${comment}: ${problems.join('; ')}.`, undefined, 'error');
+            return undefined;
+        }
+        // Explicit metadata answers what static analysis could not: its dynamic warnings become info.
+        for (let i = diagnosticsBefore; i < diagnostics.length; i++) {
+            const d = diagnostics[i];
+            if (d.code.startsWith('analyzer.dynamic.'))
+                diagnostics[i] = {
+                    ...d,
+                    severity: 'info',
+                    message: `${d.message} Explicit metadata (${comment}) is merged for this class.`,
+                };
+        }
+        return { file: rel(absolutePath), data: data };
+    }
+    function mergeExplicit(info, explicit) {
+        const ids = [];
+        const merge = (list, key, idKind, normalize) => {
+            const authored = explicit.data[key] ?? [];
+            const out = [...list];
+            for (const raw of authored) {
+                const entry = normalize(raw);
+                const index = out.findIndex((x) => x.name === entry.name);
+                if (index >= 0)
+                    out[index] = entry;
+                else
+                    out.push(entry);
+                ids.push(`${idKind}#${entry.name}`);
+            }
+            return out;
+        };
+        const text = (raw, field) => typeof raw[field] === 'string' ? raw[field] : undefined;
+        const named = (raw) => ({
+            name: raw['name'],
+            ...(text(raw, 'description') ? { description: text(raw, 'description') } : {}),
+        });
+        const description = text(explicit.data, 'description');
+        return {
+            ...info,
+            ...(description ? { description } : {}),
+            properties: merge(info.properties, 'properties', 'property', (raw) => ({
+                name: raw['name'],
+                kind: 'authored',
+                type: text(raw, 'type') ?? 'unknown',
+                attribute: raw['attribute'] === null ? null : (text(raw, 'attribute') ?? null),
+                reflects: raw['reflects'] === true,
+                default: text(raw, 'default') !== undefined
+                    ? { known: true, value: text(raw, 'default') }
+                    : { known: false },
+                ...(text(raw, 'description') ? { description: text(raw, 'description') } : {}),
+            })),
+            events: merge(info.events, 'events', 'event', (raw) => ({
+                name: raw['name'],
+                detailType: text(raw, 'detailType') ?? 'void',
+                bubbles: raw['bubbles'] === true,
+                composed: raw['composed'] === true,
+                cancelable: raw['cancelable'] === true,
+                ...(text(raw, 'syncs') ? { syncs: text(raw, 'syncs') } : {}),
+                ...(text(raw, 'description') ? { description: text(raw, 'description') } : {}),
+            })),
+            slots: merge(info.slots, 'slots', 'slot', named),
+            parts: merge(info.parts, 'parts', 'part', named),
+            cssProperties: merge(info.cssProperties, 'cssProperties', 'cssprop', named),
+            cssStates: merge(info.cssStates, 'cssStates', 'state', named),
+            authored: { file: explicit.file, ids },
+        };
+    }
+    /** Follow an identifier (through imports) to the expression it is initialized with. */
+    function initializerOf(expression) {
+        if (!ts.isIdentifier(expression))
+            return { node: expression };
+        const declaration = resolveSymbol(expression)?.declarations?.[0];
+        if (!declaration)
+            return undefined;
+        const ref = { name: expression.text, file: rel(declaration.getSourceFile().fileName) };
+        if (ts.isVariableDeclaration(declaration) && declaration.initializer)
+            return {
+                node: declaration.initializer,
+                ref: { ...ref, name: declaration.name.text },
+            };
+        if (ts.isFunctionDeclaration(declaration) && declaration.name)
+            return { node: declaration, ref: { ...ref, name: declaration.name.text } };
+        return undefined;
+    }
+    function stylesFrom(expression, refs, nodes, reads, texts, owner) {
+        const found = initializerOf(expression);
+        if (!found) {
+            const published = publishedStyles(expression);
+            if (!published) {
+                report('analyzer.dynamic.definition', expression, `${owner}: styles cannot be resolved.`);
+                return;
+            }
+            refs.push(published.ref);
+            texts.push(published.reads?.css);
+            if (published.reads)
+                reads.push(published.reads);
+            else
+                report('analyzer.published.sources', expression, `${owner}: ${published.ref.package ?? published.ref.file} publishes no facts for ${published.ref.name}; what it reads is unknown.`, `Rebuild ${published.ref.package ?? published.ref.file} with a current @oddkin/analyzer.`, 'info');
+            return;
+        }
+        const node = found.node;
+        if (ts.isArrayLiteralExpression(node)) {
+            for (const element of node.elements) {
+                if (ts.isSpreadElement(element))
+                    report('analyzer.dynamic.definition', element, `${owner}: spread styles are not analyzed.`);
+                else
+                    stylesFrom(element, refs, nodes, reads, texts, owner);
+            }
+            return;
+        }
+        if (found.ref) {
+            refs.push(found.ref);
+            recordStyles(found.ref, node);
+        }
+        nodes.push(node);
+        texts.push(tokenCss(node));
+    }
+    /**
+     * Styles imported from another package (`import { hostStyles } from '@oddkin/components/styles'`)
+     * resolve to its declarations, which carry no CSS: they are recorded by specifier and name, and
+     * what they read comes from that package's published `styles` facts.
+     */
+    function publishedStyles(expression) {
+        if (!ts.isIdentifier(expression))
+            return undefined;
+        const declaration = resolveSymbol(expression)?.declarations?.[0];
+        if (!declaration?.getSourceFile().isDeclarationFile || !ts.isVariableDeclaration(declaration))
+            return undefined;
+        const specifier = checker
+            .getSymbolAtLocation(expression)
+            ?.declarations?.find(ts.isImportSpecifier);
+        const from = specifier?.parent.parent.parent.moduleSpecifier;
+        if (!specifier || !from || !ts.isStringLiteral(from) || from.text.startsWith('.'))
+            return undefined;
+        const file = declaration.getSourceFile().fileName;
+        const pkg = published(file);
+        // Recorded as the publisher's module path, the key of its published `styles` facts.
+        if (pkg && ts.isIdentifier(declaration.name)) {
+            const module = pkg.moduleOf(file);
+            const reads = publishedReads(pkg, module, declaration.name.text);
+            return {
+                ref: { name: declaration.name.text, file: module, package: pkg.name },
+                ...(reads ? { reads } : {}),
+            };
+        }
+        return {
+            ref: {
+                name: (specifier.propertyName ?? specifier.name).text,
+                file: from.text,
+                external: true,
+            },
+        };
+    }
+    const definitionRef = (call, ref) => ref ??
+        (ts.isVariableDeclaration(call.parent) && ts.isIdentifier(call.parent.name)
+            ? { name: call.parent.name.text, file: rel(call.getSourceFile().fileName) }
+            : undefined);
+    /**
+     * A definition published by another package (`ElementDefinition<Class>` in its declarations):
+     * its tag is the `HTMLElementTagNameMap` entry for that class in the class's declaration file.
+     * Declarations only; nothing is executed.
+     */
+    function publishedDefinitionTag(expression) {
+        return publishedDefinitionOf(expression)?.tag;
+    }
+    function publishedDefinitionOf(expression) {
+        const declaration = resolveSymbol(expression)?.declarations?.[0];
+        if (!declaration || !declaration.getSourceFile().isDeclarationFile)
+            return undefined;
+        if (!ts.isVariableDeclaration(declaration) || !declaration.type)
+            return undefined;
+        const type = declaration.type;
+        // Emitted declarations write `import("@oddkin/core/element").ElementDefinition<Class>`.
+        const typeName = ts.isTypeReferenceNode(type)
+            ? type.typeName
+            : ts.isImportTypeNode(type)
+                ? type.qualifier
+                : undefined;
+        const typeArguments = ts.isTypeReferenceNode(type) || ts.isImportTypeNode(type) ? type.typeArguments : undefined;
+        if (!typeName || typeArguments?.length !== 1)
+            return undefined;
+        if (!fromOddkinCore(typeName, 'ElementDefinition'))
+            return undefined;
+        const argument = typeArguments[0];
+        if (!argument || !ts.isTypeReferenceNode(argument))
+            return undefined;
+        const classSymbol = resolveSymbol(argument.typeName);
+        const classFile = classSymbol?.declarations?.[0]?.getSourceFile();
+        if (!classSymbol || !classFile)
+            return undefined;
+        let tag;
+        const visit = (node) => {
+            if (tag)
+                return;
+            if (ts.isInterfaceDeclaration(node) && node.name.text === 'HTMLElementTagNameMap') {
+                for (const member of node.members) {
+                    if (!ts.isPropertySignature(member) ||
+                        !member.type ||
+                        !ts.isTypeReferenceNode(member.type))
+                        continue;
+                    const name = ts.isStringLiteral(member.name) ? member.name.text : undefined;
+                    if (name && TAG_NAME.test(name) && resolveSymbol(member.type.typeName) === classSymbol)
+                        tag = name;
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(classFile);
+        const classNode = classSymbol.declarations?.find(ts.isClassDeclaration);
+        return tag && classNode ? { tag, classNode } : undefined;
+    }
+    /**
+     * Spreading a definition another package publishes: its tag and class come from declarations,
+     * and its template, styles, and dependencies from that package's `oddkin.metadata.json`.
+     */
+    function publishedDefinition(expression) {
+        const found = publishedDefinitionOf(expression);
+        if (!found?.classNode.name)
+            return undefined;
+        const file = found.classNode.getSourceFile().fileName;
+        const pkg = published(file);
+        if (!pkg)
+            return undefined;
+        const entry = pkg.metadata?.['components']?.[`component:${found.tag}`]?.definition;
+        if (!entry)
+            report('analyzer.published.sources', expression, `${pkg.name} publishes no definition facts for <${found.tag}>; its template and styles are unknown.`, `Rebuild ${pkg.name} with a current @oddkin/analyzer.`, 'info');
+        const refOf = (ref) => ({
+            name: ref.name,
+            file: ref.module,
+            package: pkg.name,
+        });
+        const reads = (entry?.styles ?? []).map((s) => publishedReads(pkg, s.module, s.name));
+        return {
+            external: true,
+            classNode: found.classNode,
+            info: {
+                tag: found.tag,
+                className: found.classNode.name.text,
+                classFile: pkg.moduleOf(file),
+                ...(entry?.template ? { template: refOf(entry.template) } : {}),
+                styles: (entry?.styles ?? []).map(refOf),
+                dependencies: Object.fromEntries(Object.entries(entry?.dependencies ?? {}).map(([role, id]) => [
+                    role,
+                    id.replace(/^component:/, ''),
+                ])),
+                location: where(expression),
+            },
+            ...(entry?.styles
+                ? {
+                    styleNodes: [],
+                    styleReads: reads.filter((r) => !!r),
+                    styleTexts: reads.map((r) => r?.css),
+                }
+                : {}),
+        };
+    }
+    /** Resolve an expression to a `compose()` definition, following imports and spreads. */
+    function definitionFrom(expression) {
+        const found = initializerOf(expression);
+        const call = found?.node;
+        if (!call ||
+            !ts.isCallExpression(call) ||
+            !ts.isIdentifier(call.expression) ||
+            !fromOddkinCore(call.expression, 'compose'))
+            return undefined;
+        if (definitions.has(call))
+            return definitions.get(call) ?? undefined;
+        definitions.set(call, null);
+        const init = call.arguments[0];
+        if (!init || !ts.isObjectLiteralExpression(init)) {
+            report('analyzer.dynamic.definition', call, 'compose() needs an object literal.');
+            return undefined;
+        }
+        let base;
+        let tag;
+        let classNode;
+        let template;
+        let styles;
+        let dependencies;
+        for (const property of init.properties) {
+            if (ts.isSpreadAssignment(property)) {
+                base = definitionFrom(property.expression) ?? publishedDefinition(property.expression);
+                if (!base) {
+                    report('analyzer.dynamic.definition', property, 'compose(): only a spread of another compose() definition can be analyzed.');
+                    continue;
+                }
+                tag = base.info.tag;
+                classNode = base.classNode;
+                // A published base has no template node: its template's facts arrive with its class.
+                template =
+                    base.templateNode || base.info.template
+                        ? {
+                            ...(base.templateNode ? { node: base.templateNode } : {}),
+                            ...(base.info.template ? { ref: base.info.template } : {}),
+                        }
+                        : undefined;
+                styles = base.styleNodes
+                    ? {
+                        refs: [...base.info.styles],
+                        nodes: [...base.styleNodes],
+                        reads: [...(base.styleReads ?? [])],
+                        texts: [...(base.styleTexts ?? [])],
+                    }
+                    : undefined;
+                dependencies = { ...base.info.dependencies };
+                continue;
+            }
+            const key = (ts.isPropertyAssignment(property) || ts.isShorthandPropertyAssignment(property)) &&
+                (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name))
+                ? property.name.text
+                : undefined;
+            const value = ts.isPropertyAssignment(property)
+                ? property.initializer
+                : ts.isShorthandPropertyAssignment(property)
+                    ? property.name
+                    : undefined;
+            if (!key || !value) {
+                report('analyzer.dynamic.definition', property, 'compose(): computed entries are not analyzed.');
+                continue;
+            }
+            if (key === 'name') {
+                tag = stringOf(value);
+                if (!tag || !TAG_NAME.test(tag))
+                    report('analyzer.dynamic.tagName', value, 'compose(): the name is computed or invalid; the definition cannot be documented.', "Use a string literal, e.g. name: 'my-element'.");
+            }
+            else if (key === 'element') {
+                classNode = resolveSymbol(value)?.declarations?.find(ts.isClassDeclaration);
+                if (!classNode)
+                    report('analyzer.dynamic.registration', value, 'compose(): the element class cannot be resolved.');
+            }
+            else if (key === 'template') {
+                const resolved = initializerOf(value);
+                if (resolved) {
+                    template = { node: resolved.node, ...(resolved.ref ? { ref: resolved.ref } : {}) };
+                    if (resolved.ref && !templateSources.has(sourceKey(resolved.ref))) {
+                        const anatomy = templateAnatomy(resolved.node);
+                        templateSources.set(sourceKey(resolved.ref), {
+                            ref: resolved.ref,
+                            slots: [...anatomy.slots],
+                            parts: [...anatomy.parts],
+                        });
+                    }
+                }
+                else
+                    report('analyzer.dynamic.definition', value, 'compose(): the template cannot be resolved.');
+            }
+            else if (key === 'styles') {
+                styles = { refs: [], nodes: [], reads: [], texts: [] };
+                stylesFrom(value, styles.refs, styles.nodes, styles.reads, styles.texts, `compose(${tag ?? ''})`);
+            }
+            else if (key === 'dependencies') {
+                dependencies = {};
+                if (ts.isObjectLiteralExpression(value)) {
+                    for (const entry of value.properties) {
+                        const role = ts.isPropertyAssignment(entry) || ts.isShorthandPropertyAssignment(entry)
+                            ? entry.name.getText().replace(/^['"]|['"]$/g, '')
+                            : undefined;
+                        const target = ts.isPropertyAssignment(entry)
+                            ? entry.initializer
+                            : ts.isShorthandPropertyAssignment(entry)
+                                ? entry.name
+                                : undefined;
+                        const dependency = target ? definitionFrom(target) : undefined;
+                        const external = !dependency && target ? publishedDefinitionTag(target) : undefined;
+                        if (role && dependency)
+                            dependencies[role] = dependency.info.tag;
+                        else if (role && external)
+                            dependencies[role] = external;
+                        else
+                            report('analyzer.dynamic.definition', entry, 'compose(): each dependency must be a compose() definition.');
+                    }
+                }
+                else
+                    report('analyzer.dynamic.definition', value, 'compose(): dependencies must be an object literal.');
+            }
+        }
+        if (!tag || !TAG_NAME.test(tag) || !classNode?.name)
+            return undefined;
+        if (base?.external && classNode === base.classNode) {
+            report('analyzer.dynamic.definition', call, `compose(${tag}): a definition recomposed from a published one needs its own element class.`, 'Pass element: class extends Base {} (one constructor per registered name).');
+            return undefined;
+        }
+        const variable = definitionRef(call, found?.ref);
+        const resolved = {
+            classNode,
+            ...(template?.node ? { templateNode: template.node } : {}),
+            ...(styles
+                ? { styleNodes: styles.nodes, styleReads: styles.reads, styleTexts: styles.texts }
+                : {}),
+            info: {
+                tag,
+                className: classNode.name.text,
+                classFile: rel(classNode.getSourceFile().fileName),
+                ...(variable ? { ref: variable } : {}),
+                ...(template?.ref ? { template: template.ref } : {}),
+                styles: styles?.refs ?? [],
+                dependencies: dependencies ?? {},
+                ...(base ? { extends: base.info.tag } : {}),
+                location: where(call),
+            },
+        };
+        definitions.set(call, resolved);
+        return resolved;
+    }
+    /** Apply a definition's template and styles to its class's facts (they replace render()/static styles). */
+    function overlay(info, resolved) {
+        const derived = info.derived ?? { slots: [], parts: [], cssProperties: [], tokens: [] };
+        let { slots, parts, cssProperties, tokenReads } = info;
+        // Names the new template or styles provide again keep their documentation.
+        const doc = (list, name) => list.find((item) => item.name === name) ?? { name };
+        if (resolved.templateNode) {
+            const found = templateAnatomy(resolved.templateNode);
+            slots = slots.filter((s) => !derived.slots.includes(s.name));
+            parts = parts.filter((s) => !derived.parts.includes(s.name));
+            for (const name of found.slots)
+                if (!slots.some((s) => s.name === name))
+                    slots = [...slots, doc(info.slots, name)];
+            for (const name of found.parts)
+                if (!parts.some((s) => s.name === name))
+                    parts = [...parts, doc(info.parts, name)];
+        }
+        if (resolved.styleNodes) {
+            cssProperties = cssProperties.filter((c) => !derived.cssProperties.includes(c.name));
+            tokenReads = tokenReads.filter((t) => !derived.tokens.includes(t.token));
+            for (const read of [...resolved.styleNodes.map(styleReads), ...(resolved.styleReads ?? [])]) {
+                for (const name of read.cssProperties)
+                    if (!cssProperties.some((c) => c.name === name))
+                        cssProperties = [...cssProperties, doc(info.cssProperties, name)];
+                for (const token of read.tokens)
+                    if (!tokenReads.some((t) => t.token === token))
+                        tokenReads = [...tokenReads, { token, readThrough: 'stylesheet' }];
+            }
+        }
+        tokenReads = tokenReads.filter((t) => !cssProperties.some((c) => c.name === t.token));
+        // Mappings need this library's template and every style source's text, in cascade order.
+        const texts = resolved.styleTexts ?? [];
+        const styleMappings = resolved.templateNode && texts.length && texts.every((t) => t !== undefined)
+            ? styleMappingsOf(texts.join('\n'), partSelectors(resolved.templateNode, new Set(parts.map((p) => p.name))))
+            : [];
+        return {
+            ...info,
+            slots,
+            parts,
+            cssProperties,
+            tokenReads,
+            ...(styleMappings.length ? { styleMappings } : {}),
+        };
+    }
+    // ---- module walk ----
+    for (const file of program.getSourceFiles()) {
+        if (!isLibrarySource(file))
+            continue;
+        const exportedNames = [];
+        const visit = (node) => {
+            if (ts.isClassDeclaration(node))
+                classify(node);
+            // Exported style sources are published with what they read, used by a definition or not.
+            if (ts.isVariableStatement(node) &&
+                ts.getModifiers(node)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) {
+                for (const declaration of node.declarationList.declarations) {
+                    const initializer = declaration.initializer;
+                    if (ts.isIdentifier(declaration.name) &&
+                        initializer &&
+                        ts.isTaggedTemplateExpression(initializer) &&
+                        fromOddkinCore(initializer.tag, 'css'))
+                        recordStyles({ name: declaration.name.text, file: rel(file.fileName) }, initializer);
+                }
+            }
+            if (ts.isCallExpression(node)) {
+                const callee = node.expression;
+                const isDefine = (ts.isIdentifier(callee) && fromOddkinCore(callee, 'define')) ||
+                    (ts.isPropertyAccessExpression(callee) &&
+                        callee.name.text === 'define' &&
+                        callee.expression.getText() === 'customElements');
+                if (ts.isIdentifier(callee) && fromOddkinCore(callee, 'compose'))
+                    definitionFrom(node);
+                const definitionArgument = isDefine && node.arguments[0] && !ts.isStringLiteralLike(node.arguments[0])
+                    ? node.arguments[0]
+                    : undefined;
+                const registered = definitionArgument ? definitionFrom(definitionArgument) : undefined;
+                if (isDefine && definitionArgument && node.arguments.length === 1) {
+                    if (!registered)
+                        report('analyzer.dynamic.registration', node, 'define(definition) needs a compose() definition the analyzer can resolve.', 'Export the definition as a const initialized with compose({ ... }).');
+                    else
+                        registrations.push({
+                            tag: registered.info.tag,
+                            className: registered.info.className,
+                            classFile: registered.info.classFile,
+                            file: rel(file.fileName),
+                            location: where(node),
+                            definition: registered.info,
+                        });
+                }
+                else if (isDefine) {
+                    const tag = stringOf(node.arguments[0]);
+                    const target = node.arguments[1];
+                    const declaration = target && resolveSymbol(target)?.declarations?.find(ts.isClassDeclaration);
+                    if (!tag || !TAG_NAME.test(tag))
+                        report('analyzer.dynamic.tagName', node, 'The tag name is computed or invalid; the registration cannot be documented.', "Call define('my-element', MyElement) with a string literal.");
+                    else if (!declaration?.name)
+                        report('analyzer.dynamic.registration', node, `<${tag}> is registered with a class the analyzer cannot resolve.`);
+                    else
+                        registrations.push({
+                            tag,
+                            className: declaration.name.text,
+                            classFile: rel(declaration.getSourceFile().fileName),
+                            file: rel(file.fileName),
+                            location: where(node),
+                        });
+                }
+                if (ts.isIdentifier(callee) && isRecipeDefinition(callee) && !insideFunction(node)) {
+                    const definition = node.arguments[0];
+                    if (definition && ts.isObjectLiteralExpression(definition)) {
+                        const entries = objectEntries(definition, 'defineLayoutRecipe');
+                        const name = stringOf(entries.get('name'));
+                        const regionsNode = entries.get('regions');
+                        const regions = {};
+                        if (regionsNode && ts.isObjectLiteralExpression(regionsNode)) {
+                            for (const [region, helper] of objectEntries(regionsNode, 'regions')) {
+                                const call = ts.isArrayLiteralExpression(helper) ? helper.elements[0] : helper;
+                                regions[region] =
+                                    call && ts.isCallExpression(call)
+                                        ? (call.expression.getText().split('.').pop() ?? 'custom')
+                                        : 'custom';
+                            }
+                        }
+                        const variantsNode = entries.get('variants');
+                        const variants = {};
+                        if (variantsNode && ts.isObjectLiteralExpression(variantsNode)) {
+                            for (const [attribute, values] of objectEntries(variantsNode, 'variants')) {
+                                variants[attribute] = ts.isObjectLiteralExpression(values)
+                                    ? [...objectEntries(values, attribute).keys()]
+                                    : [];
+                            }
+                        }
+                        const whenNode = entries.get('when');
+                        const conditions = whenNode && ts.isObjectLiteralExpression(whenNode)
+                            ? [...objectEntries(whenNode, 'when').keys()]
+                            : [];
+                        const partsNode = entries.get('parts');
+                        const parts = partsNode && ts.isArrayLiteralExpression(partsNode)
+                            ? partsNode.elements.map((e) => stringOf(e) ?? '').filter(Boolean)
+                            : [];
+                        const containerNode = entries.get('container');
+                        const container = containerNode && ts.isObjectLiteralExpression(containerNode)
+                            ? objectEntries(containerNode, 'container')
+                            : undefined;
+                        const containerName = stringOf(container?.get('name'));
+                        const containerSelector = stringOf(container?.get('selector'));
+                        if (!name)
+                            report('analyzer.dynamic.recipe', node, 'Recipes need a literal name to be documented.', "Add name: 'my-recipe'.");
+                        else {
+                            recipes.push({
+                                name,
+                                regions,
+                                variants,
+                                conditions,
+                                parts,
+                                ...(container
+                                    ? {
+                                        container: {
+                                            ...(containerSelector ? { selector: containerSelector } : {}),
+                                            ...(containerName ? { name: containerName } : {}),
+                                        },
+                                    }
+                                    : {}),
+                                location: where(node),
+                            });
+                        }
+                    }
+                    else
+                        report('analyzer.dynamic.recipe', node, 'defineLayoutRecipe needs an object literal.');
+                }
+                if (ts.isIdentifier(callee) && fromOddkinCore(callee, 'defineModel')) {
+                    const name = stringOf(node.arguments[0]);
+                    const definition = node.arguments[1];
+                    const entries = definition && ts.isObjectLiteralExpression(definition)
+                        ? objectEntries(definition, 'defineModel')
+                        : undefined;
+                    const versionNode = entries?.get('version');
+                    const version = versionNode && ts.isNumericLiteral(versionNode) ? Number(versionNode.text) : undefined;
+                    const kinds = [];
+                    const findUnion = (n) => {
+                        if (ts.isCallExpression(n) &&
+                            ts.isPropertyAccessExpression(n.expression) &&
+                            n.expression.name.text === 'union' &&
+                            n.arguments[1] &&
+                            ts.isObjectLiteralExpression(n.arguments[1])) {
+                            kinds.push(...objectEntries(n.arguments[1], 'union').keys());
+                        }
+                        ts.forEachChild(n, findUnion);
+                    };
+                    if (entries?.get('schema'))
+                        findUnion(entries.get('schema'));
+                    if (!name || version === undefined)
+                        report('analyzer.dynamic.model', node, 'defineModel needs a literal name and version to be documented.');
+                    else
+                        models.push({ name, version, kinds, location: where(node) });
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(file);
+        const moduleSymbol = checker.getSymbolAtLocation(file);
+        for (const symbol of moduleSymbol ? checker.getExportsOfModule(moduleSymbol) : [])
+            exportedNames.push(symbol.name);
+        exportsBySource.set(rel(file.fileName), exportedNames.sort());
+    }
+    // Definitions replace the facts their class derives from render() and static styles.
+    for (const registration of registrations) {
+        if (!registration.definition)
+            continue;
+        const resolved = [...definitions.values()].find((d) => d?.info === registration.definition);
+        const info = resolved && classify(resolved.classNode);
+        if (resolved && info)
+            components.set(resolved.classNode, overlay(info, resolved));
+    }
+    return {
+        components: [...components.values()].filter((c) => !!c),
+        registrations,
+        recipes,
+        models,
+        definitions: [...definitions.values()]
+            .filter((d) => !!d)
+            .map((d) => d.info)
+            .sort((a, b) => (a.tag < b.tag ? -1 : a.tag > b.tag ? 1 : 0)),
+        exports: exportsBySource,
+        sources: {
+            templates: [...templateSources.values()],
+            styles: [...styleSources.values()],
+        },
+        diagnostics,
+    };
+}
+/** Resolve a path relative to `root` into an absolute path (helper for callers). */
+export const absolute = (root, file) => resolve(root, file);
+//# sourceMappingURL=extract.js.map