@wix/origami-lint 0.0.0-stage → 1.34.1

package/dist/rules/bindings.js

@@ -0,0 +1,673 @@
+import { RUNTIME_ONLY_BUILDERS, RESERVED_ATTRIBUTES, RESERVED_ENTRY_KEYS, RUNTIME_PACKAGE, SHARED_COMP_ID, bare, getAttribute, getExpression, getKey, getName, getProperties, getProperty, isStructure, ownerOf, } from "../rules-api/index.js";
+import { defineRule } from "./define-rule.js";
+/** The converter's reserved sources (identity.ts `isReservedRegistry`) and the DM's own `document`: no fn()/ctx() names. */
+const RESERVED_FOR_BINDINGS = ['runtime', 'interactReact', 'interact', 'motionPresets', 'menu', 'document', 'core'];
+/** The keys of a `bindings` object. */
+const BINDINGS_KEYS = ['props', 'visibility', 'states'];
+const VISIBILITY_KEYS = ['collapsed', 'hidden'];
+const REMOVED = 'removed';
+const CTX_OPTIONS = ['from', 'placeholder'];
+const STATE_OPTIONS = ['kind', 'id', 'pseudoClass'];
+const BINDINGS_LIST = 'BindingsList';
+const STATIC_PREFIX = 'Static.';
+const PLACES = {
+    prop: { name: "a prop's binding", builders: ['ctx', 'fn', 'raw'], literals: false },
+    fnArg: { name: 'an `fn()` argument', builders: ['ctx', 'fn', 'raw'], literals: true },
+    isBinding: { name: "`is()`'s binding", builders: ['ctx', 'fn'], literals: false },
+    condition: { name: 'a condition', builders: ['is', 'all', 'ctx', 'fn', 'raw'], literals: true },
+    allItem: { name: 'an `all()` item', builders: ['is', 'ctx', 'fn', 'raw'], literals: true },
+    statesItem: { name: 'a `states` item', builders: ['state', 'raw'], literals: false },
+};
+const PLAIN = 'a string, number or true / false';
+export default defineRule({
+    name: 'bindings',
+    editors: ['studio2'],
+    callbacks: {
+        JSXElement: checkJSXElementBindings,
+        CallExpression: checkCallExpressionImports,
+    },
+});
+// ── the callbacks' steps ──
+/** An element in the structure: a `<Remove>`, or a component and its elementProps entries. */
+function checkJSXElementBindings(input) {
+    const { node, rulesApi } = input;
+    const at = { input, owner: ownerOf(node) };
+    if (isRemoveInStructure(node, rulesApi))
+        return checkRemoveCondition(at);
+    if (!rulesApi.getComponent(node))
+        return;
+    checkComponentBindings(at);
+    for (const entry of getElementPropsEntries(node))
+        checkEntryBindings(at, entry);
+}
+/** A `<Remove>`: its `when` condition, and the component it wraps. */
+function checkRemoveCondition(at) {
+    const when = removeWhen(at);
+    if (when)
+        condition(at, when, '`when`', true);
+    removeTarget(at);
+}
+/** A component's builders, its `states` and `bindings`, and the props it binds as data attributes. */
+function checkComponentBindings(at) {
+    const { node } = at.input;
+    builderInPlace(at);
+    statesAttribute(at, getAttribute(node, 'states'));
+    bindingsAttribute(at, getAttribute(node, 'bindings'));
+    if (!hasData(node))
+        return;
+    boundPropOnce(at);
+    for (const [name, , value] of boundAttributes(node))
+        prop(at, name, value, true);
+}
+/** One elementProps entry: its `bindings`, and the keys it binds. */
+function checkEntryBindings(at, entry) {
+    const object = getObject(entry.value);
+    const key = getKey(entry);
+    if (!object || key === null)
+        return;
+    const entryAt = { input: at.input, owner: `${at.owner}'s elementProps entry \`${key}\`` };
+    const bindings = getProperty(object, 'bindings');
+    if (bindings)
+        bindingsValue(entryAt, bindings.value, true);
+    entryPropBoundOnce(entryAt, object);
+    for (const [key, property] of boundEntryKeys(object))
+        prop(entryAt, key, property.value, true);
+}
+/** A builder call in a structure attribute: it is imported, and so are the names it uses. */
+function checkCallExpressionImports(input) {
+    if (input.node.callee.type !== 'Identifier' || !isInStructureAttribute(input.node))
+        return;
+    if (!isBuilderImported(input, input.node.callee))
+        return;
+    const ctxHook = bindingNameImported(input, input.node.callee.name);
+    if (ctxHook)
+        ctxSourceHasName(input, ctxHook);
+}
+/** Each builder's own row: the shape of its call, a key written twice in it. */
+const ROW_OF_BUILDER = { all: 'CONV-decode.ts:196', ctx: 'CONV-astValue.ts:276', fn: 'CONV-astValue.ts:287', is: 'CONV-decode.ts:172', raw: 'CONV-decode.ts:28', state: 'CONV-decode.ts:145' };
+const tracked = (message, row) => `${message.slice(0, -1)} (tracker ${row}).`;
+const say = ({ input }, node, message, row) => input.report({ loc: node.loc, message: tracked(message, row) });
+const textOf = ({ input }, node) => input.context.sourceCode.getText(node);
+const describeIn = (at, node) => describe(node, (part) => textOf(at, part));
+function removeWhen(at) {
+    const { node } = at.input;
+    const when = getAttribute(node, 'when');
+    if (!when) {
+        say(at, node.openingElement.name, `${at.owner} needs \`when={…}\`: the condition that removes the component it wraps.`, 'CONV-parseJsx.ts:1113');
+        return null;
+    }
+    const value = getExpression(when);
+    const what = when.value ? `\`${at.input.context.sourceCode.getText(when.value)}\`` : 'empty';
+    if (!value)
+        say(at, when, `\`when\` on ${at.owner} is ${what}. Write the condition in braces: \`when={…}\`.`, 'CONV-parseJsx.ts:1113');
+    return value;
+}
+function removeTarget(at) {
+    const { node, rulesApi } = at.input;
+    for (const component of wrappedComponents(node, rulesApi)) {
+        const bindings = getAttribute(component, 'bindings');
+        const value = bindings && getExpression(bindings);
+        if (!value || builderOf(value, rulesApi) !== 'raw')
+            continue;
+        const item = getObject(value.arguments[0]);
+        const target = `${at.owner} wraps ${ownerOf(component)}, whose \`bindings\` are \`raw()\``;
+        if (!item || stringValue(getProperty(item, 'type')?.value) !== BINDINGS_LIST) {
+            say(at, value, `${target} of an item that isn't \`{ type: '${BINDINGS_LIST}', … }\`. Write the bindings as an object, or set ${REMOVED} in a ${BINDINGS_LIST} item instead of using \`<Remove>\`.`, 'CONV-decode.ts:296');
+        }
+        else if (setsRemoved(item)) {
+            say(at, value, `${target} of an item that already sets \`features.visibility.${REMOVED}\`. Keep only one of them.`, 'CONV-decode.ts:280');
+        }
+    }
+}
+function builderInPlace(at) {
+    const { node, rulesApi } = at.input;
+    for (const [call, where] of misplacedBuilders(node, rulesApi)) {
+        say(at, call, `\`${builderOf(call, rulesApi)}()\` on ${at.owner} is inside ${where}, where the import reads only plain values. Write a builder as the whole value of a data attribute (\`label={ctx(…)}\`) or of an elementProps entry key (\`navbar: { label: ctx(…) }\`), or in \`bindings\`.`, 'CONV-astValue.ts:98');
+    }
+}
+function boundPropOnce(at) {
+    const { node, rulesApi } = at.input;
+    const bindings = getAttribute(node, 'bindings');
+    const props = getBindingsProps(bindings && getExpression(bindings), rulesApi);
+    if (!props)
+        return;
+    for (const [name, attribute] of boundAttributes(node)) {
+        const where = props.raw ? `bindings={raw({ properties: { ${name} } })}` : `bindings={{ props: { ${name} } }}`;
+        if (props.names.has(name))
+            say(at, attribute, `${at.owner} binds \`${name}\` twice: in \`${name}={…}\` and in \`${where}\`. Keep one.`, 'CONV-parseJsx.ts:753');
+    }
+}
+function entryPropBoundOnce(at, entry) {
+    const props = getBindingsProps(getProperty(entry, 'bindings')?.value, at.input.rulesApi);
+    if (!props)
+        return;
+    for (const [key, property] of boundEntryKeys(entry)) {
+        const where = props.raw ? `bindings: raw({ properties: { ${key} } })` : `bindings.props.${key}`;
+        if (props.names.has(key))
+            say(at, property, `${at.owner} binds \`${key}\` twice: in \`${key}: …\` and in its \`${where}\`. Keep one.`, 'CONV-parseJsx.ts:753');
+    }
+}
+function bindingsAttribute(at, attribute) {
+    if (!attribute)
+        return;
+    const value = getExpression(attribute);
+    if (value)
+        bindingsValue(at, value);
+    else
+        say(at, attribute, notBindings(at, attribute.value ? `\`${at.input.context.sourceCode.getText(attribute.value)}\`` : 'empty'), 'CONV-parseJsx.ts:700');
+}
+const notBindings = (at, what) => `\`bindings\` on ${at.owner} is ${what}. Write an object in place, \`bindings={{ props: {…}, visibility: {…}, states: {…} }}\`, or \`raw({…})\`.`;
+function bindingsValue(at, node, isEntry = false) {
+    const value = bare(node);
+    if (value.type === 'ObjectExpression')
+        return bindingsObject(at, value, isEntry);
+    const builder = builderOf(value, at.input.rulesApi);
+    if (builder === 'raw') {
+        const [item] = value.arguments;
+        if (hasDuplicateKey(at, value, 'raw') || !isRawWrittenOut(at, value))
+            return;
+        const object = bare(item);
+        if (!isEntry && setsRemoved(object))
+            say(at, value, `${at.owner} sets \`features.visibility.${REMOVED}\` in its \`raw()\` bindings. Move the condition out, and wrap the component in \`<Remove when={…}>\`.`, 'CONV-decode.ts:280');
+        const propertyMap = getProperty(object, 'properties');
+        const properties = getObject(propertyMap?.value);
+        if (propertyMap && !properties)
+            say(at, propertyMap.value, `The \`properties\` in \`raw()\` bindings on ${at.owner} isn't an object. Write a prop map of typed bindings: \`properties: { label: { type: 'ContextBinding', … } }\`.`, 'CONV-decode.ts:252');
+        for (const property of properties ? getProperties(properties) : []) {
+            if (isStaticItem(property.value))
+                say(at, property.value, fixedValue(at, getKey(property)), 'CONV-decode.ts:252');
+        }
+    }
+    else if (builder) {
+        say(at, value, `\`bindings\` on ${at.owner} is a \`${builder}()\` call. Write an object and put the call under props, visibility or states, or use \`raw({…})\`.`, 'CONV-decode.ts:263');
+    }
+    else if (!isCallByName(value)) {
+        say(at, value, notBindings(at, describeIn(at, value)), 'CONV-parseJsx.ts:700');
+    }
+}
+function bindingsObject(at, bindings, isEntry) {
+    for (const property of bindings.properties) {
+        const what = property.type === 'SpreadElement' ? `a spread (\`${textOf(at, property)}\`)`
+            : property.computed ? 'a computed key'
+                : property.key.type === 'Literal' && typeof property.key.value === 'string' ? `the quoted key \`${textOf(at, property.key)}\``
+                    : property.key.type !== 'Identifier' ? `the key \`${textOf(at, property.key)}\``
+                        : BINDINGS_KEYS.includes(property.key.name) ? null
+                            : `the key \`${property.key.name}\``;
+        if (what)
+            say(at, property, `\`bindings\` on ${at.owner} has ${what}. Use only the keys props, visibility and states, written as plain names.`, 'CONV-parseJsx.ts:708');
+        else
+            section(at, property.key.name, property.value, isEntry);
+    }
+}
+function section(at, name, node, isEntry) {
+    const fix = `Write an object of \`key: value\` entries: \`${name}: { label: … }\`.`;
+    const value = bare(node);
+    if (value.type !== 'ObjectExpression')
+        return say(at, value, `\`bindings.${name}\` on ${at.owner} isn't an object. ${fix}`, 'CONV-parseJsx.ts:669');
+    for (const property of value.properties) {
+        const problem = property.type === 'SpreadElement' ? 'has a spread'
+            : property.computed ? 'has a computed key'
+                : property.kind !== 'init' || property.method ? 'has a getter, setter or method'
+                    : property.key.type === 'Literal' && typeof property.key.value === 'number' ? `has the number key ${property.key.value}`
+                        : getKey(property) === '__proto__' ? 'has the key `__proto__`'
+                            : getKey(property) === null ? `has the key \`${textOf(at, property.key)}\``
+                                : null;
+        if (problem) {
+            say(at, property, `\`bindings.${name}\` on ${at.owner} ${problem}. ${fix}`, 'CONV-parseJsx.ts:669');
+            continue;
+        }
+        const key = getKey(property);
+        const where = `\`bindings.${name}.${key}\``;
+        if (name === 'props')
+            prop(at, key, property.value, false);
+        else if (name === 'visibility' && key === REMOVED && !isEntry)
+            say(at, property, `${at.owner} sets \`visibility.${REMOVED}\` in its \`bindings\`. Move the condition out, and wrap the component in \`<Remove when={…}>\`.`, 'CONV-decode.ts:280');
+        else if (name === 'visibility' && key !== REMOVED && !VISIBILITY_KEYS.includes(key))
+            say(at, property, `\`bindings.visibility\` on ${at.owner} has the key \`${key}\`. Use \`collapsed\` or \`hidden\`.`, 'CONV-decode.ts:221');
+        else
+            condition(at, property.value, where);
+    }
+}
+function prop(at, name, node, placeholderAllowed) {
+    const value = bare(node);
+    if (value.type === 'ArrayExpression')
+        return say(at, value, `\`bindings.props.${name}\` on ${at.owner} is an array. Bind the prop to one value: \`ctx()\`, \`fn()\` or \`raw()\`.`, 'CONV-decode.ts:209');
+    if (isPlain(value) || rawOnly(value) || isStaticRaw(at, value))
+        return say(at, value, fixedValue(at, name), 'CONV-decode.ts:252');
+    binding(at, value, 'prop', placeholderAllowed);
+}
+const fixedValue = (at, name) => `\`${name}\` on ${at.owner} is bound to a fixed value. Write it as the attribute \`${name}=…\`, or as an \`fn()\` argument.`;
+function isStaticRaw(at, value) {
+    if (builderOf(value, at.input.rulesApi) !== 'raw')
+        return false;
+    const [item, ...extra] = value.arguments;
+    return Boolean(item) && extra.length === 0 && !nonLiteralIn(item) && isStaticItem(item);
+}
+function condition(at, node, where, inRemove = false) {
+    const value = bare(node);
+    if (value.type !== 'ArrayExpression')
+        return binding(at, value, 'condition');
+    if (inRemove || value.elements.length > 0) {
+        const spread = hasHoleOrSpread(value);
+        say(at, value, `${where} on ${at.owner} is ${spread ? 'a list with a spread or an empty place' : 'a list'}. Write one condition, or \`all(a, b, …)\`.`, spread ? 'CONV-parseJsx.ts:655' : 'CONV-decode.ts:190');
+    }
+}
+function binding(at, node, place, placeholderAllowed = false) {
+    const value = bare(node);
+    const { name } = PLACES[place];
+    if (isCallByName(value)) {
+        const builder = builderOf(value, at.input.rulesApi);
+        if (!builder)
+            return;
+        if (!PLACES[place].builders.includes(builder))
+            return wrongPlace(at, value, `\`${builder}()\``, place);
+        return call(at, value, builder, place, placeholderAllowed);
+    }
+    if (isPlain(value)) {
+        if (!PLACES[place].literals)
+            wrongPlace(at, value, 'a literal', place);
+        return;
+    }
+    const raw = rawOnly(value);
+    if (raw && place === 'statesItem')
+        return wrongPlace(at, value, raw, place);
+    if (raw)
+        return say(at, value, `${capitalize(name)} on ${at.owner} is ${raw}. Write ${PLAIN}, or wrap it in \`raw()\`.`, 'CONV-decode.ts:86');
+    say(at, value, `${capitalize(name)} on ${at.owner} is ${describeIn(at, value)}. Write it out. ${hintFor(place)}`, 'CONV-decode.ts:86');
+}
+const wrongPlace = (at, node, what, place) => say(at, node, `${capitalize(what)} can't be ${PLACES[place].name} on ${at.owner}. ${hintFor(place)}`, place === 'statesItem' ? 'CONV-decode.ts:132' : 'CONV-decode.ts:126');
+function call(at, node, builder, place, placeholderAllowed) {
+    if (node.arguments.some((argument) => argument.type === 'SpreadElement')) {
+        return say(at, node, `\`${builder}()\` on ${at.owner} spreads its arguments. Write each argument out.`, 'CONV-astValue.ts:310');
+    }
+    if (hasDuplicateKey(at, node, builder))
+        return;
+    if (builder === 'ctx')
+        ctxCall(at, node, placeholderAllowed);
+    else if (builder === 'fn')
+        fnCall(at, node, placeholderAllowed);
+    else if (builder === 'is')
+        isCall(at, node);
+    else if (builder === 'all')
+        allCall(at, node, place);
+    else if (builder === 'raw')
+        isRawWrittenOut(at, node);
+    else
+        stateCall(at, node);
+}
+function hasDuplicateKey(at, node, builder) {
+    const twice = node.arguments.map(duplicateKeyIn).find(Boolean);
+    if (twice)
+        say(at, twice, `\`${builder}()\` on ${at.owner} has the key \`${getKey(twice)}\` twice. Keep one.`, ROW_OF_BUILDER[builder]);
+    return Boolean(twice);
+}
+function ctxCall(at, node, placeholderAllowed) {
+    const [path, options, ...extra] = node.arguments;
+    const object = options && getObject(options);
+    const keys = object?.properties.map((property) => (property.type === 'Property' && !property.computed ? getKey(property) : null)) ?? [];
+    const unknown = keys.find((key) => key === null || !CTX_OPTIONS.includes(key));
+    const problem = stringValue(path) === null ? 'has no path string first'
+        : extra.length > 0 ? 'has more than two arguments'
+            : !options ? 'has no `{ from }` options'
+                : !object ? "has options that aren't an object"
+                    : unknown !== undefined ? (unknown === null ? "has an option that isn't `key: value`" : `has the option \`${unknown}\``)
+                        : !keys.includes('from') ? 'has no `from`'
+                            : keys.includes('placeholder') && !placeholderAllowed ? 'has a placeholder: only a whole attribute value, or an elementProps entry value, has one'
+                                : null;
+    if (problem)
+        return say(at, node, `\`ctx()\` on ${at.owner} ${problem}. Write \`ctx('item.path', { from: useX })\`.`, 'CONV-astValue.ts:276');
+    const placeholder = object && getProperty(object, 'placeholder');
+    if (placeholder)
+        placeholderValue(at, placeholder.value);
+}
+function fnCall(at, node, placeholderAllowed) {
+    const [, ...rest] = node.arguments;
+    if (node.arguments.length === 0)
+        return say(at, node, `\`fn()\` on ${at.owner} has no arguments. Write the imported function first: \`fn(numberToText, …)\`.`, 'CONV-astValue.ts:287');
+    const last = rest.at(-1);
+    const options = placeholderAllowed && last ? getObject(last) : null;
+    const placeholder = options && options.properties.length === 1 ? getProperty(options, 'placeholder') : undefined;
+    for (const argument of rest) {
+        if (argument === last && placeholder)
+            placeholderValue(at, placeholder.value);
+        else
+            binding(at, argument, 'fnArg');
+    }
+}
+function placeholderValue(at, node) {
+    const value = bare(node);
+    if (!isPlain(value))
+        say(at, value, `The placeholder on ${at.owner} is ${rawOnly(value) ?? describeIn(at, value)}. Write ${PLAIN}.`, 'CONV-parseJsx.ts:729');
+}
+function isCall(at, node) {
+    const fix = 'Write `is(<ctx() or fn()>, <string or true / false>)`.';
+    if (node.arguments.length !== 2)
+        return say(at, node, `\`is()\` on ${at.owner} has ${node.arguments.length} argument${node.arguments.length === 1 ? '' : 's'}. ${fix}`, 'CONV-decode.ts:172');
+    const [binded, compared] = node.arguments.map((argument) => bare(argument));
+    if (isPlain(binded) || rawOnly(binded) || builderOf(binded, at.input.rulesApi) === 'raw')
+        say(at, binded, `\`is()\` on ${at.owner} compares ${isCallByName(binded) ? '`raw()`' : 'a literal'}, not a binding. ${fix}`, 'CONV-decode.ts:172');
+    else
+        binding(at, binded, 'isBinding');
+    const isStringOrBoolean = compared.type === 'Literal' && ['string', 'boolean'].includes(typeof compared.value);
+    if (!isStringOrBoolean)
+        say(at, compared, `\`is()\` on ${at.owner} compares to ${rawOnly(compared) ?? describeIn(at, compared)}. ${fix}`, 'CONV-decode.ts:172');
+}
+function allCall(at, node, place) {
+    const count = node.arguments.length;
+    if (place === 'condition' && count < 2)
+        say(at, node, `\`all()\` on ${at.owner} has ${count} condition${count === 1 ? '' : 's'}. Give it two or more, or write the one condition without \`all()\`.`, 'CONV-decode.ts:196');
+    for (const argument of node.arguments)
+        binding(at, argument, 'allItem');
+}
+function isRawWrittenOut(at, node) {
+    const [item, ...extra] = node.arguments;
+    if (!item || extra.length > 0) {
+        say(at, node, `\`raw()\` on ${at.owner} has ${node.arguments.length} arguments. Write one item: \`raw({ type: …, … })\`.`, 'CONV-decode.ts:28');
+        return false;
+    }
+    const value = bare(item);
+    if (value.type === 'CallExpression') {
+        say(at, value, `\`raw()\` on ${at.owner} wraps a call (\`${textOf(at, value)}\`). Write the item out as an object, or use the builder without \`raw()\`.`, 'CONV-decode.ts:28');
+        return false;
+    }
+    if (value.type !== 'ObjectExpression') {
+        say(at, value, `\`raw()\` on ${at.owner} wraps ${rawOnly(value) ?? describeIn(at, value)}, not an object. Write one item: \`raw({ type: …, … })\`.`, 'CONV-decode.ts:28');
+        return false;
+    }
+    const found = nonLiteralIn(value);
+    if (found)
+        say(at, found, `\`raw()\` on ${at.owner} holds ${describeIn(at, found)}. Write its item out with literal values.`, 'CONV-decode.ts:28');
+    return !found;
+}
+function stateCall(at, node) {
+    const [nameNode, options, ...extra] = node.arguments;
+    const name = stringValue(nameNode);
+    const object = options && getObject(options);
+    const keys = object ? getProperties(object).map(getKey) : [];
+    const unknown = keys.find((key) => key !== null && !STATE_OPTIONS.includes(key));
+    const problem = name === null ? 'has no name string first'
+        : extra.length > 0 ? 'has more than two arguments'
+            : !object || object.properties.length !== keys.length ? "has no options object, or one that isn't all `key: value`"
+                : unknown !== undefined ? `has the option \`${unknown}\``
+                    : null;
+    if (problem)
+        return say(at, node, `\`state()\` on ${at.owner} ${problem}. Write \`state('hover', { kind: 'hover', id: 'state-1' })\` (pseudoClass is optional).`, 'CONV-decode.ts:145');
+    const found = nonLiteralIn(object);
+    if (found)
+        return say(at, found, `\`state()\` on ${at.owner} holds ${describeIn(at, found)}. Write its options out with literal values.`, 'CONV-decode.ts:145');
+    if (stringValue(getProperty(object, 'kind')?.value) === null)
+        return say(at, node, `\`state()\` on ${at.owner} has no \`kind\` string. Write \`state('hover', { kind: 'hover', id: 'state-1' })\` (pseudoClass is optional).`, 'CONV-decode.ts:145');
+    if (stringValue(getProperty(object, 'id')?.value) === null)
+        say(at, node, `\`state('${name}')\` on ${at.owner} has no \`id\` string. Add \`id: '…'\` to its options.`, 'CONV-decode.ts:142');
+}
+function statesAttribute(at, attribute) {
+    if (!attribute)
+        return;
+    const value = getExpression(attribute);
+    if (value?.type === 'ArrayExpression' && !hasHoleOrSpread(value)) {
+        for (const item of value.elements)
+            binding(at, item, 'statesItem');
+        return;
+    }
+    const what = value?.type === 'ArrayExpression' ? 'a list with a spread or an empty place' : value ? describeIn(at, value) : 'not a `{…}` value';
+    say(at, attribute, `\`states\` on ${at.owner} is ${what}. Write a list of \`state()\` or \`raw()\` calls: \`states={[state('hover', {…})]}\`.`, 'CONV-parseJsx.ts:641');
+}
+/** Only RUNTIME_ONLY_BUILDERS: other runtime names (`Remove(…)`) pass the converter's parse, then its decode has no case for them. */
+function isBuilderImported({ rulesApi, report }, callee) {
+    const found = rulesApi.getImport(callee);
+    if (found?.kind === 'runtime' && found.imported === callee.name && RUNTIME_ONLY_BUILDERS.includes(callee.name))
+        return true;
+    const builder = found?.kind === 'runtime' ? found.imported : callee.name;
+    report({
+        loc: callee.loc,
+        message: tracked(RUNTIME_ONLY_BUILDERS.includes(builder)
+            ? `\`${callee.name}(…)\` isn't the builder \`${builder}\` from ${RUNTIME_PACKAGE}. Import it under its own name, \`import { ${builder} } from '${RUNTIME_PACKAGE}'\`, and call it as \`${builder}(…)\`.`
+            : `\`${callee.name}(…)\` isn't a builder. In an attribute, only the builders of ${RUNTIME_PACKAGE} are called (${RUNTIME_ONLY_BUILDERS.join(', ')}); write a literal value, or one of them.`, 'CONV-astValue.ts:296'),
+    });
+    return false;
+}
+function bindingNameImported({ node, rulesApi, report, context }, builder) {
+    const [first, second] = node.arguments;
+    const options = builder === 'ctx' ? getObject(second) : null;
+    const named = builder === 'fn' ? first : options ? getProperty(options, 'from')?.value : undefined;
+    if (!named)
+        return null;
+    const value = bare(named);
+    const what = builder === 'fn' ? "fn()'s function" : "ctx()'s `from` hook";
+    if (value.type !== 'Identifier') {
+        report({ loc: value.loc, message: tracked(`${what} is \`${context.sourceCode.getText(value)}\`. Write an imported name: \`fn(numberToText, …)\`, \`{ from: useProduct }\`.`, 'CONV-astValue.ts:227') });
+        return null;
+    }
+    const found = rulesApi.getImport(value);
+    const problem = !found
+        ? [`${what} \`${value.name}\` isn't imported. Import it by name from its library: the function's library, or the context's app.`, 'CONV-astValue.ts:227']
+        : found.kind && RESERVED_FOR_BINDINGS.includes(found.kind)
+            ? [`${what} \`${value.name}\` comes from ${found.source}, which holds no functions or contexts. Import it from its own library: the function's library, or the context's app.`, 'CONV-astValue.ts:230']
+            : found.imported === '*'
+                ? [`${what} \`${value.name}\` is a namespace (\`import * as ${value.name}\`). Import the ${builder === 'fn' ? 'function' : 'hook'} itself by name: \`import { name } from '${found.source}'\`.`, 'CONV-astValue.ts:227']
+                : null;
+    if (problem)
+        report({ loc: value.loc, message: tracked(...problem) });
+    return found && !problem && builder === 'ctx' ? { hook: value, source: found.source } : null;
+}
+function ctxSourceHasName({ report }, { hook, source }) {
+    if (source.indexOf('/') !== source.length - 1)
+        return;
+    report({ loc: hook.loc, message: tracked(`ctx()'s \`from\` hook \`${hook.name}\` is imported from '${source}', which has no context name after the \`/\`. Write '<componentType>/<contextName>'.`, 'CONV-decode.ts:100') });
+}
+// ── reading the code ──
+function getObject(source) {
+    if (!source)
+        return null;
+    const value = source.type === 'JSXAttribute' ? getExpression(source) : bare(source);
+    return value?.type === 'ObjectExpression' ? value : null;
+}
+function getElementPropsEntries(element) {
+    return getEntries(getObject(getAttribute(element, 'elementProps')));
+}
+function getEntries(elementProps) {
+    if (!elementProps)
+        return [];
+    return getProperties(elementProps).flatMap((entry) => {
+        const entryObject = getObject(entry.value);
+        return [entry, ...getEntries(getObject(entryObject ? getProperty(entryObject, 'elementProps')?.value : undefined))];
+    });
+}
+/** null for a call that isn't a builder: isBuilderImported reports it. */
+function builderOf(node, rulesApi) {
+    if (node.type !== 'CallExpression' || node.callee.type !== 'Identifier')
+        return null;
+    const found = rulesApi.getImport(node.callee);
+    return found?.kind === 'runtime' && RUNTIME_ONLY_BUILDERS.includes(found.imported) ? found.imported : null;
+}
+const isCallByName = (node) => node.type === 'CallExpression' && node.callee.type === 'Identifier';
+function isPlain(node) {
+    if (node.type === 'UnaryExpression')
+        return node.operator === '-' && node.argument.type === 'Literal' && typeof node.argument.value === 'number';
+    return node.type === 'Literal' && ['string', 'number', 'boolean'].includes(typeof node.value);
+}
+function rawOnly(node) {
+    if (node.type === 'Literal' && node.value === null && node.raw === 'null')
+        return 'null';
+    if (node.type === 'ObjectExpression')
+        return 'an object';
+    if (node.type === 'ArrayExpression')
+        return 'an array';
+    return null;
+}
+const hasHoleOrSpread = (node) => node.type === 'ArrayExpression' && node.elements.some((element) => element === null || element.type === 'SpreadElement');
+function describe(node, getText) {
+    if (node.type === 'Identifier')
+        return `the variable \`${node.name}\``;
+    if (node.type === 'SpreadElement')
+        return `a spread (\`${getText(node)}\`)`;
+    if (node.type === 'TemplateLiteral')
+        return `a template string (\`${getText(node)}\`)`;
+    if (node.type === 'ArrayExpression')
+        return 'an array';
+    if (node.type === 'Property' && node.key.type === 'Literal' && typeof node.key.value === 'number')
+        return `the number key \`${node.key.value}\``;
+    return `\`${getText(node)}\``;
+}
+function nonLiteralIn(node) {
+    if (node === null)
+        return null;
+    const value = bare(node);
+    if (isPlain(value) || rawOnly(value) === 'null')
+        return null;
+    if (value.type === 'ArrayExpression')
+        return value.elements.includes(null) ? value : value.elements.map(nonLiteralIn).find(Boolean) ?? null;
+    if (value.type !== 'ObjectExpression')
+        return value;
+    for (const property of value.properties) {
+        if (property.type !== 'Property' || property.computed || property.kind !== 'init' || property.method || getKey(property) === null)
+            return property;
+        const found = nonLiteralIn(property.value);
+        if (found)
+            return found;
+    }
+    return null;
+}
+const capitalize = (text) => text[0].toUpperCase() + text.slice(1);
+const hintFor = (place) => {
+    const { builders, literals } = PLACES[place];
+    const calls = builders.map((builder) => `\`${builder}()\``);
+    return `Write ${literals ? `${calls.join(', ')}, or a string, number or true / false` : `${calls.slice(0, -1).join(', ')}${calls.length > 1 ? ' or ' : ''}${calls.at(-1)}`}.`;
+};
+function isRemoveInStructure(element, rulesApi) {
+    if (rulesApi.getType(element) !== 'remove')
+        return false;
+    return rulesApi.getComponent(element) !== null || wrappedComponents(element, rulesApi).length > 0;
+}
+/** Through an `<Interaction>` too: it hands the `<Remove>` condition on to the component it wraps. */
+const wrappedComponents = (element, rulesApi) => rulesApi.getChildren(element).flatMap((child) => {
+    if (child.type !== 'JSXElement')
+        return [];
+    if (rulesApi.getType(child) === 'interaction')
+        return wrappedComponents(child, rulesApi);
+    return rulesApi.getComponent(child) ? [child] : [];
+});
+/** The import reads data attributes only on a component with `type=`. */
+const hasData = (element) => getAttribute(element, 'type') !== undefined;
+/** Not the component's data: the converter's reserved attributes, `sharedCompId`, and `states`, which bindings still reads. */
+const isReserved = (name) => RESERVED_ATTRIBUTES.includes(name) || name === SHARED_COMP_ID || name === 'states';
+function boundAttributes(element) {
+    return element.openingElement.attributes.flatMap((attribute) => {
+        if (attribute.type !== 'JSXAttribute' || isReserved(getName(attribute)))
+            return [];
+        const value = getExpression(attribute);
+        return value?.type === 'CallExpression' ? [[getName(attribute), attribute, value]] : [];
+    });
+}
+function boundEntryKeys(entry) {
+    return getProperties(entry).flatMap((property) => {
+        const key = getKey(property);
+        return key !== null && !RESERVED_ENTRY_KEYS.includes(key) && bare(property.value).type === 'CallExpression' ? [[key, property]] : [];
+    });
+}
+function getBindingsProps(node, rulesApi) {
+    const value = node && bare(node);
+    if (!value)
+        return null;
+    const raw = builderOf(value, rulesApi) === 'raw';
+    const bindings = getObject(raw ? value.arguments[0] : value);
+    const props = bindings && getObject(getProperty(bindings, raw ? 'properties' : 'props')?.value);
+    return props ? { names: new Set(getProperties(props).map(getKey).filter((key) => key !== null)), raw } : null;
+}
+/** The import stores a prop's binding as an item: one with no string type, or a Static.* type, is a fixed value. */
+function isStaticItem(node) {
+    const item = getObject(node);
+    const type = item && stringValue(getProperty(item, 'type')?.value);
+    return !type || type.startsWith(STATIC_PREFIX);
+}
+function duplicateKeyIn(node) {
+    if (node === null)
+        return null;
+    const value = bare(node);
+    if (value.type === 'ArrayExpression')
+        return value.elements.map(duplicateKeyIn).find(Boolean) ?? null;
+    if (value.type !== 'ObjectExpression')
+        return null;
+    const seen = new Set();
+    for (const property of getProperties(value)) {
+        const key = getKey(property);
+        if (key !== null && seen.has(key))
+            return property;
+        if (key !== null)
+            seen.add(key);
+        const found = duplicateKeyIn(property.value);
+        if (found)
+            return found;
+    }
+    return null;
+}
+function setsRemoved(item) {
+    let object = item;
+    for (const key of ['features', 'visibility'])
+        object = object && getObject(getProperty(object, key)?.value);
+    return Boolean(object && getProperty(object, REMOVED));
+}
+function stringValue(node) {
+    const value = node && bare(node);
+    return value?.type === 'Literal' && typeof value.value === 'string' ? value.value : null;
+}
+function misplacedBuilders(element, rulesApi) {
+    return element.openingElement.attributes.flatMap((attribute) => {
+        if (attribute.type !== 'JSXAttribute')
+            return [];
+        const name = getName(attribute);
+        const value = getExpression(attribute);
+        if (!value || name === 'bindings' || name === 'states')
+            return [];
+        if (name === 'elementProps')
+            return entryBuilders(value, rulesApi, '`elementProps`');
+        if (!isReserved(name) && builderOf(value, rulesApi))
+            return [];
+        return buildersIn(value, rulesApi).map((call) => [call, `\`${name}\``]);
+    });
+}
+function entryBuilders(elementProps, rulesApi, where) {
+    const map = getObject(elementProps);
+    if (!map)
+        return buildersIn(elementProps, rulesApi).map((call) => [call, where]);
+    return getProperties(map).flatMap((entry) => {
+        if (getKey(entry) === null)
+            return [];
+        const name = `${where} entry \`${getKey(entry)}\``;
+        const object = getObject(entry.value);
+        if (!object)
+            return buildersIn(entry.value, rulesApi).map((call) => [call, name]);
+        return getProperties(object).flatMap((property) => {
+            const key = getKey(property);
+            if (key === null || key === 'bindings' || key === 'slots')
+                return [];
+            if (key === 'elementProps')
+                return entryBuilders(property.value, rulesApi, `${name}'s \`elementProps\``);
+            if (!RESERVED_ENTRY_KEYS.includes(key) && builderOf(property.value, rulesApi))
+                return [];
+            return buildersIn(property.value, rulesApi).map((call) => [call, `${name}'s \`${key}\``]);
+        });
+    });
+}
+function buildersIn(node, rulesApi) {
+    if (!node || typeof node !== 'object' || !('type' in node))
+        return [];
+    const value = node;
+    // Functions have their own scope; nested JSX is checked by its own callback.
+    if (value.type === 'ArrowFunctionExpression' || value.type === 'FunctionExpression' || value.type === 'JSXElement' || value.type === 'JSXFragment')
+        return [];
+    if (value.type === 'CallExpression' && builderOf(value, rulesApi))
+        return [value];
+    return Object.entries(value).flatMap(([key, child]) => key === 'parent' ? []
+        : Array.isArray(child) ? child.flatMap((item) => buildersIn(item, rulesApi)) : buildersIn(child, rulesApi));
+}
+function isInStructureAttribute(node) {
+    let inAttribute = false;
+    for (let up = node.parent; up.type !== 'Program'; up = up.parent) {
+        if (up.type === 'JSXAttribute')
+            inAttribute = true;
+        if (up.type === 'ArrowFunctionExpression' || up.type === 'FunctionExpression')
+            return inAttribute && isStructure(up);
+    }
+    return false;
+}