@appright/funnelshift 0.0.0-stage → 0.15.0

package/dist/cli/lint.js

@@ -0,0 +1,535 @@
+import { literal, parseSource, walk } from './extract.js';
+// Only the funnel's own code is checked (the paths build passes are relative to the repo root). The text rules apply to the
+// screens; the event rules also to the project's server functions.
+const norm = (path) => path.replace(/\\/g, '/');
+const inScope = (path) => /^(funnels|components)\//.test(norm(path));
+const inEventScope = (path) => /^(funnels|components|functions)\//.test(norm(path));
+const hasLetter = (s) => /\p{L}/u.test(s);
+// Attributes whose string value is shown or read aloud to the visitor; className, id, href, src, role, data-* and the like are not text.
+const TEXT_ATTRS = new Set(['alt', 'aria-label', 'title', 'placeholder']);
+// Props of the kit's Hero that hold visible text. `title` is also a generic text attribute above, which already reports it.
+const HERO_TEXT_PROPS = ['title', 'subtitle', 'highlight', 'cta'];
+// Content of these elements is code, not copy.
+const CODE_TAGS = new Set(['style', 'script']);
+// Case matters except for lorem ipsum: "Todo lo que necesitas", "Exxon" and "XXL size" are real copy, TODO / TBD / XX masks are not.
+const PLACEHOLDER = [/lorem ipsum/i, /\bTODO\b/, /\bTBD\b/, /\$?\bX{2,}(?:[,.]X{2,})*\b/];
+const unwrap = (n) => (n && ['TSAsExpression', 'TSSatisfiesExpression', 'TSNonNullExpression', 'ParenthesizedExpression'].includes(n.type) ? unwrap(n.expression) : n);
+// String pieces an expression can render as text: a literal, or a literal in a branch (`a ? 'Yes' : 'No'`, `ok && 'Done'`).
+function literals(e) {
+    e = unwrap(e);
+    switch (e?.type) {
+        case 'StringLiteral': return [e];
+        case 'TemplateLiteral': return [e];
+        case 'ConditionalExpression': return [...literals(e.consequent), ...literals(e.alternate)];
+        case 'LogicalExpression': return [...literals(e.left), ...literals(e.right)];
+        default: return [];
+    }
+}
+const textOf = (n) => n.type === 'TemplateLiteral' ? n.quasis.map((q) => q.value.cooked ?? '').join(' ') : n.value;
+const clip = (s) => { const one = s.trim().replace(/\s+/g, ' '); return one.length > 40 ? one.slice(0, 40) + '…' : one; };
+const tag = (el) => el.openingElement?.name?.name ?? '';
+// Hand-written copy that bypasses t() cannot be edited in the admin and shows up untranslated, and a placeholder default
+// that reaches a live funnel is visible to visitors; build refuses both with the file and line.
+function textRules(program, add) {
+    const text = (n, shown) => add(n, 'text-outside-t', `text "${clip(shown)}" must go through t('key', 'default')`);
+    // `const OPTIONS = [...]` next to the funnel: Choice options are often kept there, so look one step behind an identifier.
+    const consts = new Map();
+    walk(program, n => { if (n.type === 'VariableDeclarator' && n.id?.type === 'Identifier' && n.init)
+        consts.set(n.id.name, n.init); });
+    const propName = (a) => (a.name?.type === 'JSXIdentifier' ? a.name.name : '');
+    // The kit's blocks take their copy as props: a literal there bypasses t() just like JSX text does.
+    const blockProps = (el) => {
+        const name = tag(el);
+        for (const a of el.openingElement?.attributes ?? []) {
+            if (a.type !== 'JSXAttribute' || !a.value)
+                continue;
+            const v = a.value;
+            const exprs = v.type === 'JSXExpressionContainer' ? v.expression : v;
+            if (name === 'Hero' && HERO_TEXT_PROPS.includes(propName(a)) && !TEXT_ATTRS.has(propName(a))) {
+                for (const l of literals(exprs))
+                    if (hasLetter(textOf(l)))
+                        add(l, 'text-outside-t', `Hero ${propName(a)}="${clip(textOf(l))}" must go through t('key', 'default')`);
+            }
+            else if ((name === 'Choice' || name === 'MultiChoice') && propName(a) === 'options') {
+                let list = unwrap(exprs);
+                if (list?.type === 'Identifier')
+                    list = unwrap(consts.get(list.name));
+                if (list?.type !== 'ArrayExpression')
+                    continue;
+                for (const item of list.elements) {
+                    const o = unwrap(item);
+                    if (o?.type !== 'ObjectExpression')
+                        continue;
+                    for (const p of o.properties) {
+                        if (p.type !== 'ObjectProperty' || p.computed || (p.key.name ?? p.key.value) !== 'label')
+                            continue;
+                        for (const l of literals(p.value))
+                            if (hasLetter(textOf(l)))
+                                add(l, 'text-outside-t', `${name} option label "${clip(textOf(l))}" must go through t('key', 'default')`);
+                    }
+                }
+            }
+        }
+    };
+    walk(program, n => {
+        if (n.type === 'JSXElement')
+            blockProps(n);
+        if (n.type === 'JSXElement' || n.type === 'JSXFragment') {
+            if (n.type === 'JSXElement' && CODE_TAGS.has(tag(n)))
+                return;
+            for (const c of n.children) {
+                if (c.type === 'JSXText') {
+                    const raw = c.extra?.raw ?? c.value;
+                    if (c.value.trim() && hasLetter(c.value)) {
+                        // Point at the first non-blank line of the text, not at the whitespace before it.
+                        const lead = raw.slice(0, raw.length - raw.trimStart().length);
+                        text({ loc: { start: { line: c.loc.start.line + (lead.match(/\n/g)?.length ?? 0), column: 0 } } }, c.value);
+                    }
+                }
+                else if (c.type === 'JSXExpressionContainer') {
+                    for (const l of literals(c.expression))
+                        if (hasLetter(textOf(l)))
+                            text(l, textOf(l));
+                }
+            }
+        }
+        else if (n.type === 'JSXAttribute' && n.name.type === 'JSXIdentifier' && TEXT_ATTRS.has(n.name.name) && n.value) {
+            const v = n.value;
+            const ls = v.type === 'StringLiteral' ? [v] : v.type === 'JSXExpressionContainer' ? literals(v.expression) : [];
+            for (const l of ls)
+                if (hasLetter(textOf(l)))
+                    add(l, 'text-outside-t', `${n.name.name}="${clip(textOf(l))}" must go through t('key', 'default')`);
+        }
+        else if (n.type === 'CallExpression' && n.callee?.type === 'Identifier' && n.callee.name === 't') {
+            const def = literal(n.arguments[1]);
+            if (def === null)
+                return; // extractContent reports non-literal arguments
+            if (PLACEHOLDER.some(re => re.test(def)))
+                add(n, 'placeholder', `default "${clip(def)}" is a placeholder; write the real text`);
+            const vars = unwrap(n.arguments[2]);
+            // Keys we can read; a spread or computed key means we cannot know what is passed, so such calls are not judged.
+            let known = new Set();
+            if (vars === undefined)
+                known = new Set();
+            else if (vars.type !== 'ObjectExpression')
+                known = null;
+            else
+                for (const p of vars.properties) {
+                    if (p.type !== 'ObjectProperty' && p.type !== 'ObjectMethod') {
+                        known = null;
+                        break;
+                    }
+                    if (p.computed) {
+                        known = null;
+                        break;
+                    }
+                    known.add(p.key.name ?? String(p.key.value));
+                }
+            if (known) {
+                const missing = [...new Set([...def.matchAll(/\{\{(\w+)\}\}/g)].map(m => m[1]))].filter(k => !known.has(k));
+                for (const k of missing)
+                    add(n, 'placeholder', `default has {{${k}}} but this t() call passes no vars.${k}`);
+            }
+        }
+    });
+}
+// The findings of every file in the order given, each file's sorted by position. Errors fail the build; warnings are printed
+// and the build goes on (spec "all events" §7: a false alarm is fine as a warning, never as an error).
+export function check(files) {
+    const errors = [];
+    const warnings = [];
+    const parsed = [];
+    for (const f of files) {
+        if (!inScope(f.path) && !inEventScope(f.path))
+            continue;
+        try {
+            parsed.push({ f, program: parseSource(f).program });
+        }
+        catch (e) {
+            // The screens must parse (content and steps are read from them); a server file is checked only for event names.
+            if (inScope(f.path))
+                throw e;
+            warnings.push({ file: f.path, line: 1, rule: 'parse-error', message: `cannot read the file, its event names were not checked: ${clip(e.message)}` });
+        }
+    }
+    // Keys some step never sends (skipAnswers anywhere in the funnel): they need no text.
+    const skipped = new Set(parsed.flatMap(p => skippedKeys(p.program)));
+    for (const { f, program } of parsed) {
+        const errs = [];
+        const warns = [];
+        const at = (n) => ({ file: f.path, line: n.loc.start.line, col: n.loc.start.column });
+        if (inScope(f.path))
+            textRules(program, (n, rule, message) => errs.push({ ...at(n), rule, message }));
+        if (inEventScope(f.path))
+            eventRules(program, skipped, (n, rule, message) => errs.push({ ...at(n), rule, message }), (n, rule, message) => warns.push({ ...at(n), rule, message }));
+        const byPos = (a, b) => a.line - b.line || a.col - b.col;
+        errors.push(...errs.sort(byPos).map(({ col: _c, ...e }) => e));
+        warnings.push(...warns.sort(byPos).map(({ col: _c, ...e }) => e));
+    }
+    return { errors, warnings };
+}
+export function lint(files) {
+    return check(files).errors;
+}
+// The kit under its name (@appright/funnelshift) and its name before 0.15.0.
+const KITS = new Set(['@appright/funnelshift', '@appright/funnel-kit']);
+// The kit's rule for an event name, a prop name and so for answer_<key> (answers.ts PROP_KEY, functions.ts FUNCTION_NAME).
+const NAME = /^[a-z][a-z0-9_]{0,63}$/;
+const KIT_BLOCKS = new Set(['Hero', 'Choice', 'MultiChoice', 'Cta']);
+// Blocks that hand the option text to set() by themselves (offer.ts), and the props where that happens.
+const LABELLED = new Set(['Choice', 'MultiChoice']);
+const LABELLED_PROPS = new Set(['onChange', 'onPick']);
+// Fields whose value is what the person typed: no other text to send.
+const TEXT_FIELDS = new Set(['input', 'textarea']);
+const NUMERIC_FNS = new Set(['Number', 'parseInt', 'parseFloat', 'Boolean']);
+const STRING_METHODS = new Set(['trim', 'trimStart', 'trimEnd', 'toLowerCase', 'toUpperCase', 'slice', 'normalize']);
+const PLAIN_MEMBERS = new Set(['length', 'checked', 'valueAsNumber']);
+const answerKeyOk = (k) => k !== '' && NAME.test('answer_' + k) && !k.endsWith('_truncated');
+const isFn = (n) => ['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression', 'ObjectMethod'].includes(n?.type);
+const propKey = (p) => (p?.type === 'ObjectProperty' || p?.type === 'ObjectMethod') && !p.computed ? (p.key.name ?? p.key.value ?? null) : null;
+const isMember = (c, prop) => c?.type === 'MemberExpression' && !c.computed && c.property?.name === prop;
+const jsxName = (el) => el?.name?.type === 'JSXIdentifier' ? el.name.name : '';
+// The literal keys of every skipAnswers in a file: `skipAnswers: [...]` or `x.skipAnswers = [...]`, also through a const
+// array of the same file.
+function skippedKeys(program) {
+    const consts = new Map();
+    walk(program, n => { if (n.type === 'VariableDeclarator' && n.id?.type === 'Identifier' && n.init)
+        consts.set(n.id.name, n.init); });
+    const out = [];
+    const add = (v) => {
+        v = unwrap(v);
+        if (v?.type === 'Identifier')
+            v = unwrap(consts.get(v.name));
+        if (v?.type === 'ArrayExpression')
+            for (const e of v.elements) {
+                const k = literal(e);
+                if (k !== null)
+                    out.push(k);
+            }
+    };
+    walk(program, n => {
+        if (n.type === 'ObjectProperty' && propKey(n) === 'skipAnswers')
+            add(n.value);
+        if (n.type === 'AssignmentExpression' && isMember(n.left, 'skipAnswers'))
+            add(n.right);
+    });
+    return out;
+}
+// walk with the chain of ancestors (outermost first), for rules that depend on where a call sits.
+function walkUp(node, visit, up = []) {
+    if (!node || typeof node.type !== 'string')
+        return;
+    visit(node, up);
+    up.push(node);
+    for (const k of Object.keys(node)) {
+        if (k === 'loc' || k === 'start' || k === 'end')
+            continue;
+        const v = node[k];
+        if (Array.isArray(v))
+            v.forEach(c => walkUp(c, visit, up));
+        else if (v && typeof v === 'object')
+            walkUp(v, visit, up);
+    }
+    up.pop();
+}
+// A value that needs no text: a literal, a number or a yes/no, or what the person typed into a field.
+function plainValue(v) {
+    v = unwrap(v);
+    if (!v)
+        return true;
+    switch (v.type) {
+        case 'StringLiteral':
+        case 'NumericLiteral':
+        case 'BooleanLiteral':
+        case 'NullLiteral':
+        case 'BigIntLiteral':
+        case 'UnaryExpression': return true;
+        case 'TemplateLiteral': return v.expressions.length === 0;
+        case 'Identifier': return v.name === 'undefined';
+        case 'ArrayExpression': return v.elements.every((e) => e && plainValue(e));
+        case 'BinaryExpression': return v.operator !== '+' || (plainValue(v.left) && plainValue(v.right));
+        case 'ConditionalExpression': return plainValue(v.consequent) && plainValue(v.alternate);
+        case 'MemberExpression': return (!v.computed && PLAIN_MEMBERS.has(v.property?.name)) || typedText(v);
+        case 'CallExpression':
+            if (v.callee?.type === 'Identifier' && NUMERIC_FNS.has(v.callee.name))
+                return true;
+            if (v.callee?.type === 'MemberExpression' && v.callee.object?.type === 'Identifier' && v.callee.object.name === 'Math')
+                return true;
+            return typedText(v);
+    }
+    return false;
+}
+// e.target.value / e.currentTarget.value, also trimmed or lower-cased.
+function typedText(v) {
+    v = unwrap(v);
+    if (v?.type === 'CallExpression' && v.callee?.type === 'MemberExpression' && !v.callee.computed && STRING_METHODS.has(v.callee.property?.name))
+        return typedText(v.callee.object);
+    return isMember(v, 'value') && (isMember(v.object, 'target') || isMember(v.object, 'currentTarget'));
+}
+// Text that keeps a click's name stable: a literal, or t() (its key names the click), also in branches.
+function stableText(e) {
+    e = unwrap(e);
+    switch (e?.type) {
+        case 'StringLiteral': return true;
+        case 'TemplateLiteral': return e.expressions.length === 0;
+        case 'CallExpression': return e.callee?.type === 'Identifier' && e.callee.name === 't';
+        case 'ConditionalExpression': return stableText(e.consequent) && stableText(e.alternate);
+        case 'LogicalExpression': return e.operator === '&&' ? stableText(e.right) : stableText(e.left) && stableText(e.right);
+    }
+    return false;
+}
+// The identifiers a declaration pattern binds.
+function boundIds(p) {
+    switch (p?.type) {
+        case 'Identifier': return [p];
+        case 'ObjectPattern': return p.properties.flatMap((q) => boundIds(q.type === 'RestElement' ? q.argument : q.value));
+        case 'ArrayPattern': return p.elements.flatMap((e) => boundIds(e));
+        case 'AssignmentPattern': return boundIds(p.left);
+        case 'RestElement': return boundIds(p.argument);
+        case 'TSParameterProperty': return boundIds(p.parameter);
+    }
+    return [];
+}
+function eventRules(program, skipped, err, warn) {
+    const useNames = new Set(['useFunnel']);
+    const kitUse = new Set(); // the import specifiers' local nodes of the kit's useFunnel
+    const role = new Map(); // binding identifier node -> what it is
+    const weak = new Set(); // bindings whose role comes from something only possibly the kit's: never sure
+    for (const st of program.body) {
+        if (st.type !== 'ImportDeclaration' || !KITS.has(String(st.source.value)))
+            continue;
+        for (const s of st.specifiers) {
+            if (s.type !== 'ImportSpecifier')
+                continue;
+            const imported = s.imported.name ?? s.imported.value;
+            if (imported === 'track')
+                role.set(s.local, 'track');
+            if (imported === 'useFunnel') {
+                useNames.add(s.local.name);
+                kitUse.add(s.local);
+            }
+        }
+    }
+    // { set, track: tr } = useFunnel() or a handler's ({ track }) parameter; weak when the source is only maybe the kit's.
+    const pick = (pattern, want, isWeak = false) => {
+        if (pattern?.type !== 'ObjectPattern')
+            return;
+        for (const p of pattern.properties) {
+            const k = propKey(p);
+            const v = p.value?.type === 'AssignmentPattern' ? p.value.left : p.value;
+            if (k && want[k] && v?.type === 'Identifier') {
+                role.set(v, want[k]);
+                if (isWeak)
+                    weak.add(v);
+            }
+        }
+    };
+    const fns = new Map();
+    const decls = new Map(); // name -> every binding identifier of that name in the file
+    const declare = (ids) => { for (const id of ids)
+        decls.set(id.name, [...(decls.get(id.name) ?? []), id]); };
+    walk(program, n => {
+        if (n.type === 'FunctionDeclaration' && n.id)
+            fns.set(n.id.name, n);
+        if (n.type === 'VariableDeclarator' && n.id?.type === 'Identifier' && isFn(unwrap(n.init)))
+            fns.set(n.id.name, unwrap(n.init));
+        if (n.type === 'VariableDeclarator')
+            declare(boundIds(n.id));
+        if (isFn(n) || n.type === 'ClassMethod' || n.type === 'ClassPrivateMethod')
+            declare(n.params.flatMap(boundIds));
+        if ((n.type === 'FunctionDeclaration' || n.type === 'FunctionExpression' || n.type === 'ClassDeclaration' || n.type === 'ClassExpression') && n.id)
+            declare([n.id]);
+        if (n.type === 'ImportSpecifier' || n.type === 'ImportDefaultSpecifier' || n.type === 'ImportNamespaceSpecifier')
+            declare([n.local]);
+        if (n.type === 'CatchClause' && n.param)
+            declare(boundIds(n.param));
+    });
+    // useFunnel() is surely the kit's only when its name is bound by nothing but the kit import; a local useFunnel, one from
+    // another module or a shadowed alias is only maybe.
+    const isUse = (n) => {
+        n = unwrap(n);
+        if (n?.type !== 'CallExpression' || n.callee?.type !== 'Identifier' || !useNames.has(n.callee.name))
+            return null;
+        const ds = decls.get(n.callee.name) ?? [];
+        return ds.length && ds.every(d => kitUse.has(d)) ? 'sure' : 'maybe';
+    };
+    walk(program, n => {
+        const use = n.type === 'VariableDeclarator' ? isUse(n.init) : null;
+        if (use) {
+            if (n.id.type === 'Identifier') {
+                role.set(n.id, 'funnel');
+                if (use === 'maybe')
+                    weak.add(n.id);
+            }
+            else
+                pick(n.id, { set: 'set', track: 'track' }, use === 'maybe');
+        }
+        if (n.type === 'CallExpression' && n.callee?.type === 'Identifier' && n.callee.name === 'defineFunctions' && unwrap(n.arguments[0])?.type === 'ObjectExpression') {
+            for (const p of unwrap(n.arguments[0]).properties) {
+                const v = p.type === 'ObjectMethod' ? p : unwrap(p.value);
+                const fn = isFn(v) ? v : v?.type === 'Identifier' ? fns.get(v.name) : null;
+                const ctx = fn?.params?.[1];
+                if (ctx?.type === 'Identifier')
+                    role.set(ctx, 'ctx');
+                else
+                    pick(ctx, { track: 'ctxTrack' });
+            }
+        }
+    });
+    // How sure it is that `name` is a binding of this role: every declaration has it, or only some (or `ctx` by its name).
+    const certainty = (name, r) => {
+        const ds = decls.get(name) ?? [];
+        const n = ds.filter(d => role.get(d) === r).length;
+        if (n && n === ds.length)
+            return ds.some(d => weak.has(d)) ? 'maybe' : 'sure';
+        return n || (r === 'ctx' && name === 'ctx') ? 'maybe' : null;
+    };
+    walk(program, n => {
+        // const { track } = ctx: as sure as that ctx is.
+        const c = n.type === 'VariableDeclarator' && unwrap(n.init)?.type === 'Identifier' ? certainty(unwrap(n.init).name, 'ctx') : null;
+        if (c)
+            pick(n.id, { track: 'ctxTrack' }, c !== 'sure');
+    });
+    const viaFunnel = (o) => isUse(o) ?? (o?.type === 'Identifier' ? certainty(o.name, 'funnel') : null);
+    const setCall = (c) => {
+        if (c.type !== 'CallExpression')
+            return null;
+        if (c.callee?.type === 'Identifier')
+            return certainty(c.callee.name, 'set');
+        return isMember(c.callee, 'set') ? viaFunnel(c.callee.object) : null;
+    };
+    // Which track: the browser's (a $ name is taken) or a function's ctx.track (a $ name is dropped), and how sure.
+    const trackCall = (c) => {
+        if (c.type !== 'CallExpression')
+            return null;
+        if (c.callee?.type === 'Identifier') {
+            const b = certainty(c.callee.name, 'track'), sv = certainty(c.callee.name, 'ctxTrack');
+            if (sv)
+                return { server: true, c: b ? 'maybe' : sv };
+            return b ? { server: false, c: b } : null;
+        }
+        if (!isMember(c.callee, 'track'))
+            return null;
+        const o = c.callee.object;
+        const b = viaFunnel(o), sv = o?.type === 'Identifier' ? certainty(o.name, 'ctx') : null;
+        if (sv)
+            return { server: true, c: b ? 'maybe' : sv };
+        return b ? { server: false, c: b } : null;
+    };
+    const isSet = (c) => setCall(c) !== null;
+    const badKey = (n, k, sure, why = '') => (sure ? err : warn)(n, 'answer-key', `answer key "${clip(k)}": answer_ + key must match ${NAME.source} and not end in _truncated, or the answer is not sent` +
+        (sure ? '; or list the key in skipAnswers if it is a service flag' : why));
+    // The answer keys a step component sets, following the components it draws from this file; null when that cannot be known
+    // (a key that is not a literal, a component from another file).
+    const keysSet = (fn, seen) => {
+        const keys = new Set();
+        let unknown = false;
+        walk(fn.body, n => {
+            if (isSet(n)) {
+                const k = literal(n.arguments[0]);
+                if (k === null)
+                    unknown = true;
+                else
+                    keys.add(k);
+            }
+            if (n.type === 'JSXOpeningElement' && /^[A-Z]/.test(jsxName(n)) && !KIT_BLOCKS.has(jsxName(n))) {
+                const sub = fns.get(jsxName(n));
+                if (!sub) {
+                    unknown = true;
+                    return;
+                }
+                if (seen.has(sub))
+                    return;
+                seen.add(sub);
+                const more = keysSet(sub, seen);
+                if (!more)
+                    unknown = true;
+                else
+                    more.forEach(k => keys.add(k));
+            }
+        });
+        return unknown ? null : keys;
+    };
+    const maybe = ' (if this call is not the funnel\'s, ignore)';
+    walkUp(program, (n, up) => {
+        const tr = trackCall(n);
+        if (tr) {
+            const name = literal(n.arguments[0]);
+            if (name === null || NAME.test(name))
+                return;
+            // The browser's tracker takes $name (the kit's own events); ctx.track drops it.
+            const kits = /^\$[a-z][a-z0-9_]{0,63}$/.test(name);
+            const sure = tr.c === 'sure' && (tr.server || !kits);
+            (sure ? err : warn)(n, 'event-name', kits
+                ? `event name "${clip(name)}": names with $ are reserved for the kit's own events; use ${NAME.source}${tr.server ? ', or the event is dropped' : ''}`
+                : `event name "${clip(name)}" must match ${NAME.source}, or the event is dropped${sure ? '' : maybe}`);
+        }
+        else if (isSet(n)) {
+            const key = literal(n.arguments[0]);
+            if (key !== null && !answerKeyOk(key)) {
+                const skip = skipped.has(key);
+                badKey(n, key, setCall(n) === 'sure' && !skip, skip ? ' (it is in skipAnswers: if every step that sets it leaves it out, ignore)' : setCall(n) === 'sure' ? '' : maybe);
+                return;
+            }
+            if (n.arguments.length >= 3 || plainValue(n.arguments[1]) || (key !== null && skipped.has(key)))
+                return;
+            // Inside Choice/MultiChoice onChange the block passes the option text itself; inside a text field the value is the text.
+            for (let i = up.length - 1; i > 0; i--) {
+                if (up[i].type !== 'JSXAttribute' || up[i - 1].type !== 'JSXOpeningElement')
+                    continue;
+                const el = jsxName(up[i - 1]);
+                if ((LABELLED.has(el) && LABELLED_PROPS.has(up[i].name?.name)) || TEXT_FIELDS.has(el))
+                    return;
+            }
+            const shown = key === null ? 'set(…)' : `set('${clip(key)}', …)`;
+            warn(n, 'answer-without-label', `${shown} has no text the person saw: pass it third, set(key, value, label); free text, numbers and yes/no need none`);
+        }
+        else if (n.type === 'JSXElement' && ['button', 'a'].includes(jsxName(n.openingElement))) {
+            const attrs = n.openingElement.attributes;
+            if (attrs.some((a) => a.type === 'JSXSpreadAttribute' || a.name?.name === 'data-track'))
+                return;
+            const kids = n.children.filter((c) => !(c.type === 'JSXText' && !c.value.trim()) && !(c.type === 'JSXExpressionContainer' && c.expression.type === 'JSXEmptyExpression'));
+            if (!kids.length || kids.some((c) => c.type !== 'JSXExpressionContainer') || kids.every((c) => stableText(c.expression)))
+                return;
+            const el = jsxName(n.openingElement);
+            warn(n, 'click-without-name', `<${el}> shows a text built at runtime, so its clicks are named <${el}>#<number>: add data-track="name" (not needed if the text is a t() text)`);
+        }
+        else if (n.type === 'ObjectExpression') {
+            const prop = (k) => n.properties.find((p) => propKey(p) === k);
+            const track = prop('trackAnswers');
+            if (track) {
+                warn(track, 'track-answers', 'trackAnswers is obsolete since kit 0.4: every answer is sent, the list filters nothing; remove it (skipAnswers leaves a key out)');
+                const list = unwrap(track.value);
+                if (list?.type === 'ArrayExpression')
+                    for (const e of list.elements) {
+                        const k = literal(e);
+                        if (k !== null && !answerKeyOk(k))
+                            badKey(e, k, false, ' (trackAnswers filters nothing; remove it)');
+                    }
+            }
+            const skip = prop('skipAnswers'), comp = unwrap(prop('component')?.value);
+            const list = unwrap(skip?.value);
+            const fn = comp?.type === 'Identifier' ? fns.get(comp.name) : null;
+            if (list?.type !== 'ArrayExpression' || !fn)
+                return;
+            const keys = keysSet(fn, new Set([fn]));
+            if (!keys)
+                return;
+            for (const e of list.elements) {
+                const k = literal(e);
+                if (k !== null && !keys.has(k))
+                    warn(e, 'skip-answers-unset', `skipAnswers lists "${clip(k)}", but this step never sets it: a typo leaves the real key in the answers`);
+            }
+        }
+    });
+}
+// One line per finding, `path:line rule message`, then the count.
+export function formatLint(errors) {
+    const lines = errors.map(e => `${e.file}:${e.line} ${e.rule} ${e.message}`);
+    return [...lines, `${errors.length} problem${errors.length === 1 ? '' : 's'} found, the build was not made`].join('\n');
+}
+// One line per warning, `path:line warning rule message`, then the count.
+export function formatWarnings(warnings) {
+    const lines = warnings.map(w => `${w.file}:${w.line} warning ${w.rule} ${w.message}`);
+    return [...lines, `${warnings.length} warning${warnings.length === 1 ? '' : 's'}, the build goes on`].join('\n');
+}

package/dist/cli/upload.d.ts

@@ -0,0 +1,29 @@
+export declare function uploadBuild(o: {
+    dir: string;
+    api: string;
+    project: string;
+    funnel: string;
+    commit: string;
+    branch: string;
+    token: string;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    build_id: string;
+    preview_url?: string;
+    functions_deployed?: boolean;
+}>;
+export declare function uploadLines(r: {
+    build_id: string;
+    preview_url?: string;
+    functions_deployed?: boolean;
+}): string[];
+export declare function runUpload(o: {
+    dir: string;
+    funnel: string;
+    commit: string;
+    branch: string;
+    env: Record<string, string | undefined>;
+    api?: string;
+    project?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<string[]>;

package/dist/cli/upload.js

@@ -0,0 +1,90 @@
+import { create } from 'tar';
+import { lstatSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+const MAX_ARTIFACT = 50 << 20; // the server's limit
+// Regular files only, as relative paths with "/" (what the server accepts). A symlink in the build is an error: the server
+// would reject the whole artifact, so fail here with the file name instead.
+function files(root, rel = '') {
+    return readdirSync(join(root, rel)).sort().flatMap(n => {
+        const r = rel ? `${rel}/${n}` : n;
+        const st = lstatSync(join(root, r));
+        if (st.isSymbolicLink())
+            throw new Error(`symlink in build dir: ${r}`);
+        if (st.isDirectory())
+            return files(root, r);
+        if (st.isFile())
+            return [r];
+        throw new Error(`not a regular file in build dir: ${r}`);
+    });
+}
+export async function uploadBuild(o) {
+    const list = files(o.dir);
+    for (const need of ['index.html', 'manifest.json']) {
+        if (!list.includes(need))
+            throw new Error(`${need} is missing in ${o.dir} (run funnel-kit build first)`);
+    }
+    const chunks = [];
+    const stream = create({ gzip: true, cwd: o.dir, portable: true, noDirRecurse: true }, list);
+    for await (const c of stream)
+        chunks.push(Buffer.from(c));
+    const art = Buffer.concat(chunks);
+    if (art.length > MAX_ARTIFACT)
+        throw new Error(`artifact is ${art.length} bytes, the limit is ${MAX_ARTIFACT}`);
+    const form = new FormData();
+    for (const k of ['project', 'funnel', 'commit', 'branch'])
+        form.set(k, o[k]);
+    form.set('artifact', new Blob([art], { type: 'application/gzip' }), 'build.tgz');
+    const r = await (o.fetchImpl ?? fetch)(`${o.api.replace(/\/+$/, '')}/api/builds`, { method: 'POST', body: form, headers: { Authorization: `Bearer ${o.token}` } });
+    const text = await r.text();
+    // 201: new build, 200: the identical build already exists; both carry the id.
+    if (r.status !== 201 && r.status !== 200)
+        throw new Error(`upload failed: ${r.status} ${text}`);
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch { /* handled below */ }
+    const id = body?.build_id;
+    if (typeof id !== 'string' || !id)
+        throw new Error(`upload answered ${r.status} without build_id`);
+    return { build_id: id, preview_url: typeof body.preview_url === 'string' ? body.preview_url : undefined,
+        // Only for a build with functions: whether the server got them onto the edge right away (it retries by itself if not).
+        functions_deployed: typeof body.functions_deployed === 'boolean' ? body.functions_deployed : undefined };
+}
+const HEX32 = /^[0-9a-f]{32}$/;
+// https only (plain http just for a local dev server), one token without whitespace or control characters: the line is read by
+// people and by agents, and a server that returns anything else must not get to put it in their output.
+const SAFE_URL = /^(https:\/\/[^\s\x00-\x1f\x7f]+|http:\/\/localhost(:\d+)?([/?#][^\s\x00-\x1f\x7f]*)?)$/;
+// The lines `upload` prints (functions_deployed only for a build with functions). The id is checked and an invalid one is an error; a preview url that fails the check is left
+// out (get_preview gives a fresh link), and the guide says so.
+export function uploadLines(r) {
+    if (!HEX32.test(r.build_id))
+        throw new Error('upload answered with a build_id that is not 32 hex characters; nothing was printed');
+    const lines = [`build_id=${r.build_id}`];
+    if (r.preview_url && SAFE_URL.test(r.preview_url))
+        lines.push(`preview_url=${r.preview_url}`);
+    if (r.functions_deployed !== undefined)
+        lines.push(`functions_deployed=${r.functions_deployed}`);
+    return lines;
+}
+async function projectOfToken(api, token, fetchImpl) {
+    const r = await fetchImpl(`${api.replace(/\/+$/, '')}/api/v1/project`, { headers: { Authorization: `Bearer ${token}` } });
+    const slug = r.status === 200 ? (await r.json().catch(() => null))?.slug : undefined;
+    if (typeof slug !== 'string' || !slug)
+        throw new Error(`cannot find the project of the token (${r.status}); pass --project <slug>`);
+    return slug;
+}
+// Everything `funnel-kit upload` does, with the environment and the options passed in: token from FUNNELS_TOKEN (else the CI's
+// FUNNELS_DEPLOY_TOKEN), address from --api or FUNNELS_API_URL, project from --project, FUNNELS_PROJECT or the token itself.
+export async function runUpload(o) {
+    const token = o.env.FUNNELS_TOKEN || o.env.FUNNELS_DEPLOY_TOKEN;
+    if (!token)
+        throw new Error('FUNNELS_TOKEN is not set');
+    const api = o.api || o.env.FUNNELS_API_URL;
+    if (!api)
+        throw new Error('the service address is not set: use FUNNELS_API_URL or --api <url>');
+    const fetchImpl = o.fetchImpl ?? fetch;
+    const project = o.project || o.env.FUNNELS_PROJECT || await projectOfToken(api, token, fetchImpl);
+    const res = await uploadBuild({ dir: o.dir, api, project, funnel: o.funnel, commit: o.commit, branch: o.branch, token, fetchImpl });
+    return uploadLines(res);
+}

package/dist/clicks.d.ts

@@ -0,0 +1,7 @@
+export type ClickOptions = {
+    stepId: () => string;
+    track: (name: string, props: Record<string, unknown>, stepId: string) => void;
+    keyOf: (text: string) => string | null;
+    now?: () => number;
+};
+export declare function installClicks(root: HTMLElement, o: ClickOptions): () => void;