@appright/funnelshift 0.0.0-stage → 0.15.0

package/dist/cli/extract.js

@@ -0,0 +1,253 @@
+import { parse } from '@babel/parser';
+import { STEP_ROLES } from '../nav.js';
+export function literal(n) {
+    if (n?.type === 'StringLiteral')
+        return n.value;
+    if (n?.type === 'TemplateLiteral' && n.expressions.length === 0)
+        return n.quasis[0].value.cooked;
+    return null;
+}
+export function walk(node, visit) {
+    if (!node || typeof node.type !== 'string')
+        return;
+    visit(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 => walk(c, visit));
+        else if (v && typeof v === 'object')
+            walk(v, visit);
+    }
+}
+// `.ts` must not get the jsx plugin: `<T>x` casts are valid there and would not parse.
+function plugins(path) {
+    if (/\.tsx$/.test(path))
+        return ['typescript', 'jsx'];
+    if (/\.ts$/.test(path))
+        return ['typescript'];
+    return ['jsx'];
+}
+export function parseSource(f) {
+    try {
+        return parse(f.code, { sourceType: 'module', plugins: plugins(f.path) });
+    }
+    catch (e) {
+        throw new Error(`${f.path}: cannot parse: ${e.message}`);
+    }
+}
+// Every t('key', 'default') in the funnel's code, so the admin can show and edit all texts (spec §5).
+export function extractContent(files) {
+    const found = new Map();
+    for (const f of files) {
+        const ast = parseSource(f);
+        walk(ast.program, n => {
+            if (n.type !== 'CallExpression' || n.callee?.type !== 'Identifier' || n.callee.name !== 't')
+                return;
+            const key = literal(n.arguments[0]), def = literal(n.arguments[1]);
+            if (key === null || def === null)
+                throw new Error(`${f.path}:${n.loc?.start.line}: t() key and default must be string literals`);
+            const prev = found.get(key);
+            if (prev && prev.default !== def)
+                throw new Error(`t('${key}') has two defaults: ${prev.path} and ${f.path}`);
+            found.set(key, { key, default: def, path: f.path });
+        });
+    }
+    return [...found.values()].map(({ key, default: d }) => ({ key, default: d })).sort((a, b) => a.key.localeCompare(b.key));
+}
+const unwrap = (n) => (n && ['TSAsExpression', 'TSSatisfiesExpression', 'TSNonNullExpression', 'ParenthesizedExpression'].includes(n.type) ? unwrap(n.expression) : n);
+const isCall = (n, name) => n?.type === 'CallExpression' && n.callee?.type === 'Identifier' && n.callee.name === name;
+// The answer keys a step's `when` reads, when its code tells them: an arrow or function whose one parameter is only ever read as
+// `a.key`, `a?.key` or `a['key']`, or is destructured with literal keys and no rest; no parameter reads none. Anything else (the
+// parameter passed on or spread, a computed key, a function declared elsewhere) gives null: the step is conditional, its keys unknown.
+export function whenKeys(fn) {
+    fn = unwrap(fn);
+    if (fn?.type !== 'ArrowFunctionExpression' && fn?.type !== 'FunctionExpression')
+        return null;
+    if (fn.params.length === 0)
+        return [];
+    if (fn.params.length > 1)
+        return null;
+    let p = fn.params[0];
+    if (p.type === 'AssignmentPattern')
+        p = p.left;
+    const keys = [];
+    const add = (k) => { if (!keys.includes(k))
+        keys.push(k); };
+    if (p.type === 'ObjectPattern') {
+        for (const prop of p.properties) {
+            if (prop.type !== 'ObjectProperty')
+                return null; // a rest element takes every key
+            const k = prop.computed ? literal(prop.key) : prop.key.type === 'Identifier' ? prop.key.name : literal(prop.key);
+            if (k === null)
+                return null;
+            add(k);
+        }
+        return keys;
+    }
+    if (p.type !== 'Identifier')
+        return null;
+    const name = p.name;
+    let ok = true;
+    // every other mention of the parameter in the body is a use we cannot follow; a property or key that merely has its name is not
+    const visit = (node, parent, field) => {
+        if (!ok || !node || typeof node.type !== 'string')
+            return;
+        if ((node.type === 'MemberExpression' || node.type === 'OptionalMemberExpression') && node.object?.type === 'Identifier' && node.object.name === name) {
+            const k = node.computed ? literal(node.property) : node.property.type === 'Identifier' ? node.property.name : null;
+            if (k === null)
+                ok = false;
+            else
+                add(k);
+            return;
+        }
+        if (node.type === 'Identifier' && node.name === name) {
+            const propName = (parent?.type === 'MemberExpression' || parent?.type === 'OptionalMemberExpression') && field === 'property' && !parent.computed;
+            const objKey = parent?.type === 'ObjectProperty' && field === 'key' && !parent.computed && !parent.shorthand;
+            if (!propName && !objKey)
+                ok = false;
+            return;
+        }
+        for (const k of Object.keys(node)) {
+            if (k === 'loc' || k === 'start' || k === 'end' || k === 'typeAnnotation' || k === 'returnType' || k === 'typeParameters')
+                continue;
+            const v = node[k];
+            if (Array.isArray(v))
+                v.forEach(c => visit(c, node, k));
+            else if (v && typeof v === 'object')
+                visit(v, node, k);
+        }
+    };
+    visit(fn.body, fn, 'body');
+    return ok ? keys : null;
+}
+// Steps (id, optional role, sensitive: true when the step is marked) in screen order, read statically from `defineFunnel({ steps: [...] })` (the manifest's `steps`, which the server uses to
+// order the report and find the lead and paywall steps). An element is `defineStep({ id: '...' })` or an identifier declared as `const x = defineStep({...})` in the
+// same file; anything else (imports, spreads, computed ids) is an error with file:line, never a guess.
+export function extractSteps(files) {
+    const funnels = [];
+    for (const f of files) {
+        const program = parseSource(f).program;
+        walk(program, n => { if (isCall(n, 'defineFunnel'))
+            funnels.push({ f, program, call: n }); });
+    }
+    if (funnels.length === 0)
+        throw new Error('no defineFunnel({ ... }) found in the funnel');
+    if (funnels.length > 1) {
+        const where = funnels.map(x => `${x.f.path}:${x.call.loc?.start.line}`).join(', ');
+        throw new Error(`defineFunnel() is called more than once (${where}); a funnel has exactly one`);
+    }
+    const { f, program, call } = funnels[0];
+    const at = (n) => `${f.path}:${n?.loc?.start.line ?? call.loc?.start.line}`;
+    const decls = new Map();
+    for (const st of program.body) {
+        const d = st.type === 'ExportNamedDeclaration' ? st.declaration : st;
+        if (d?.type !== 'VariableDeclaration')
+            continue;
+        for (const v of d.declarations)
+            if (v.id?.type === 'Identifier' && v.init)
+                decls.set(v.id.name, v);
+    }
+    // Follow `steps` / a step through identifiers declared in this file.
+    const resolve = (n, what) => {
+        const seen = new Set();
+        for (let cur = unwrap(n);; cur = unwrap(cur)) {
+            if (cur?.type !== 'Identifier')
+                return cur;
+            const decl = decls.get(cur.name);
+            if (!decl || seen.has(cur.name)) {
+                throw new Error(`${at(cur)}: ${what} '${cur.name}' is not declared in this file; imported steps are not supported, define every step as ` +
+                    `const ${cur.name} = defineStep({ ... }) in the funnel's index file`);
+            }
+            seen.add(cur.name);
+            cur = decl.init;
+        }
+    };
+    const arg = unwrap(call.arguments[0]);
+    const prop = arg?.type === 'ObjectExpression' && arg.properties.find((p) => p.type === 'ObjectProperty' && !p.computed && (p.key.name === 'steps' || p.key.value === 'steps'));
+    if (!prop)
+        throw new Error(`${at(call)}: defineFunnel() needs an object with a literal \`steps: [...]\` property`);
+    const list = resolve(prop.value, 'steps array');
+    if (list?.type !== 'ArrayExpression')
+        throw new Error(`${at(prop)}: \`steps\` must be an array literal of defineStep(...) calls`);
+    const seen = new Map();
+    const steps = list.elements.map((el) => {
+        if (!el || el.type === 'SpreadElement')
+            throw new Error(`${at(el ?? list)}: steps cannot contain spreads or holes; list each defineStep(...)`);
+        const step = resolve(el, 'step');
+        if (!isCall(step, 'defineStep'))
+            throw new Error(`${at(step)}: every element of \`steps\` must be defineStep({ id: '...' }) or a const declared with it`);
+        const o = unwrap(step.arguments[0]);
+        const idProp = o?.type === 'ObjectExpression' && o.properties.find((p) => p.type === 'ObjectProperty' && !p.computed && (p.key.name === 'id' || p.key.value === 'id'));
+        const id = idProp ? literal(unwrap(idProp.value)) : null;
+        if (id === null)
+            throw new Error(`${at(idProp ?? step)}: defineStep() id must be a string literal`);
+        const line = (idProp ?? step).loc?.start.line;
+        if (seen.has(id))
+            throw new Error(`${at(idProp ?? step)}: duplicate step id '${id}' (first used on line ${seen.get(id)}); step ids must be unique`);
+        seen.set(id, line);
+        const option = (name) => o.properties.find((p) => p.type === 'ObjectProperty' && !p.computed && (p.key.name === name || p.key.value === name));
+        const out = { id };
+        const roleProp = option('role');
+        if (roleProp) {
+            const role = literal(unwrap(roleProp.value));
+            if (role === null)
+                throw new Error(`${at(roleProp)}: defineStep() role must be 'lead', 'paywall' or 'landing' (a string literal)`);
+            if (!STEP_ROLES.includes(role)) {
+                throw new Error(`${at(roleProp)}: defineStep() role '${role}' is unknown; role must be 'lead', 'paywall' or 'landing'`);
+            }
+            out.role = role;
+        }
+        // sensitive only marks the step in the admin; the manifest carries it so the server can say so (steps_order).
+        const sensProp = option('sensitive');
+        if (sensProp) {
+            const v = unwrap(sensProp.value);
+            if (v?.type !== 'BooleanLiteral')
+                throw new Error(`${at(sensProp)}: defineStep() sensitive must be true or false (a literal)`);
+            if (v.value)
+                out.sensitive = true;
+        }
+        // when: the step is shown only to some visitors (the admin draws the ways around it before any traffic); when_keys are the
+        // answers it depends on, only when its code tells them reliably (whenKeys).
+        const whenProp = option('when');
+        const whenVal = whenProp && unwrap(whenProp.value);
+        if (whenVal && whenVal.type !== 'NullLiteral' && !(whenVal.type === 'Identifier' && whenVal.name === 'undefined')) {
+            out.conditional = true;
+            const keys = whenKeys(whenProp.value);
+            if (keys?.length)
+                out.when_keys = keys;
+        }
+        return out;
+    });
+    // The landing is the funnel's first screen, and there is one of it: landing_views and the prerender read it as such.
+    const landings = steps.map((s, i) => ({ s, i })).filter(x => x.s.role === 'landing');
+    if (landings.length > 1)
+        throw new Error(`${at(call)}: more than one step has role: 'landing' (${landings.map(x => x.s.id).join(', ')}); a funnel has one landing`);
+    if (landings.length === 1 && landings[0].i !== 0) {
+        throw new Error(`${at(call)}: the step '${landings[0].s.id}' has role: 'landing' but is not the first step; the landing is the first step of the funnel`);
+    }
+    return steps;
+}
+// `prerender: true` in the object given to defineFunnel (kit 0.11.0): draw the landing step into index.html at build time. A
+// literal true or false only; anything else is an error, never a guess. Absent: false.
+export function extractPrerender(files) {
+    for (const f of files) {
+        let found = null;
+        walk(parseSource(f).program, n => {
+            if (!isCall(n, 'defineFunnel'))
+                return;
+            const arg = unwrap(n.arguments[0]);
+            const prop = arg?.type === 'ObjectExpression' && arg.properties.find((p) => p.type === 'ObjectProperty' && !p.computed && (p.key.name === 'prerender' || p.key.value === 'prerender'));
+            if (!prop)
+                return;
+            const v = unwrap(prop.value);
+            if (v?.type !== 'BooleanLiteral')
+                throw new Error(`${f.path}:${prop.loc?.start.line}: defineFunnel() prerender must be true or false (a literal)`);
+            found = v.value;
+        });
+        if (found !== null)
+            return found;
+    }
+    return false;
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+import { buildFunnel } from './build.js';
+import { runUpload } from './upload.js';
+import { runInit } from './init.js';
+import { arg as argArg, flag, opt as optArg } from './args.js';
+import { join } from 'node:path';
+const argv = process.argv;
+const arg = (n) => argArg(argv, n);
+const opt = (n) => optArg(argv, n);
+const git = (c) => { try {
+    return execSync(`git ${c}`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+}
+catch {
+    return 'unknown';
+} };
+const commit = process.env.GITHUB_SHA || git('rev-parse HEAD');
+const branch = process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME || git('rev-parse --abbrev-ref HEAD');
+async function main() {
+    const cmd = process.argv[2];
+    if (cmd === 'init') {
+        for (const l of runInit({ project: arg('project'), dir: opt('dir') ?? process.cwd(), force: flag(argv, 'force') }))
+            console.log(l);
+        return;
+    }
+    if (cmd !== 'build' && cmd !== 'upload')
+        throw new Error('usage: funnel-kit init --project <slug> [--dir <path>] [--force] | build|upload --funnel <slug> [--api <url>] [--project <slug>]');
+    const funnel = arg('funnel');
+    if (cmd === 'build') {
+        console.log(await buildFunnel(process.cwd(), funnel, { commit, branch }));
+    }
+    else {
+        const lines = await runUpload({ dir: join(process.cwd(), 'dist', funnel), funnel, commit, branch, env: process.env, api: opt('api'), project: opt('project') });
+        for (const l of lines)
+            console.log(l);
+    }
+}
+main().catch(e => { console.error(e.message); process.exit(1); });

package/dist/cli/init.d.ts

@@ -0,0 +1,5 @@
+export declare function runInit(o: {
+    project: string;
+    dir: string;
+    force: boolean;
+}): string[];

package/dist/cli/init.js

@@ -0,0 +1,67 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// The template ships inside the package: kit/templates/init, the same distance from src/cli and dist/cli.
+const templateDir = fileURLToPath(new URL('../../templates/init/', import.meta.url));
+const kitVersion = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
+const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
+// npm never packs a file named .gitignore, so the template calls it gitignore. *.tmpl files get {{project}} and {{kit_version}} filled in.
+const RENAME = { gitignore: '.gitignore' };
+function files(dir) {
+    return readdirSync(dir).sort().flatMap(n => {
+        const p = join(dir, n);
+        return statSync(p).isDirectory() ? files(p) : [p];
+    });
+}
+export function runInit(o) {
+    if (!SLUG.test(o.project))
+        throw new Error(`--project "${o.project}" is not a valid slug: lowercase letters, digits and hyphens, up to 64 characters, starting with a letter or digit`);
+    const dir = resolve(o.dir);
+    if (existsSync(dir)) {
+        if (!statSync(dir).isDirectory())
+            throw new Error(`${dir} is not a folder`);
+        const busy = readdirSync(dir).filter(n => n !== '.git');
+        if (busy.length && !o.force)
+            throw new Error(`${dir} is not empty (${busy.slice(0, 3).join(', ')}${busy.length > 3 ? ', …' : ''}). Run init in an empty folder (--dir <folder>); --force writes over the template files and needs the project owner's consent`);
+    }
+    // Everything is read and filled in before the first byte is written.
+    const out = files(templateDir).map(src => {
+        const rel = relative(templateDir, src);
+        const base = basename(rel);
+        const name = RENAME[base] ? join(dirname(rel), RENAME[base]) : rel.replace(/\.tmpl$/, '');
+        let text = readFileSync(src, 'utf8');
+        if (rel.endsWith('.tmpl'))
+            text = text.replaceAll('{{project}}', o.project).replaceAll('{{kit_version}}', kitVersion);
+        return { path: join(dir, name), text };
+    });
+    // Writing through a link could change a file outside the folder: refuse any symlink (also a dangling one) on the way to a target.
+    for (const f of out) {
+        let p = dir;
+        for (const seg of relative(dir, f.path).split(/[\\/]/)) {
+            p = join(p, seg);
+            let link = false;
+            try {
+                link = lstatSync(p).isSymbolicLink();
+            }
+            catch {
+                break;
+            } // does not exist yet: nothing below it can be a link
+            if (link)
+                throw new Error(`${p} is a symlink; init does not write through symlinks. Remove it or use another folder`);
+        }
+    }
+    for (const f of out) {
+        mkdirSync(dirname(f.path), { recursive: true });
+        writeFileSync(f.path, f.text);
+    }
+    const here = resolve(process.cwd()) === dir;
+    return [
+        `Created the funnel-kit project "${o.project}" in ${dir}`,
+        'Next:',
+        ...(here ? [] : [`  cd ${dir}`]),
+        '  npm install',
+        '  export FUNNELS_TOKEN=<project token from the owner>',
+        '  npx funnel-kit build --funnel welcome',
+        '  npx funnel-kit upload --funnel welcome',
+    ];
+}

package/dist/cli/lint.d.ts

@@ -0,0 +1,25 @@
+export type LintError = {
+    file: string;
+    line: number;
+    rule: 'text-outside-t' | 'placeholder' | 'event-name' | 'answer-key';
+    message: string;
+};
+export type LintWarning = {
+    file: string;
+    line: number;
+    rule: 'answer-without-label' | 'click-without-name' | 'track-answers' | 'skip-answers-unset' | 'event-name' | 'answer-key' | 'parse-error';
+    message: string;
+};
+export declare function check(files: {
+    path: string;
+    code: string;
+}[]): {
+    errors: LintError[];
+    warnings: LintWarning[];
+};
+export declare function lint(files: {
+    path: string;
+    code: string;
+}[]): LintError[];
+export declare function formatLint(errors: LintError[]): string;
+export declare function formatWarnings(warnings: LintWarning[]): string;