@getrefino/onboarding 0.1.0-rc.1

package/dist/dataflow.js

@@ -0,0 +1,333 @@
+/**
+ * Static data flow from a string literal to the screen.
+ *
+ * The scanner only reports a string when there is evidence in the source
+ * that it reaches a reader. Beyond literal JSX text that means following a
+ * few well-defined shapes: a constant interpolated into JSX, an array the
+ * file maps into elements, a record indexed then mapped, a prop a component
+ * renders, a default for such a prop, a conditional between two literals,
+ * and a state value a handler sets to a literal. Everything here is
+ * syntactic; nothing is executed and no type checker is used.
+ *
+ * The rule that keeps this conservative: start from a *render sink* (a JSX
+ * expression child, or a prop a component renders) and walk backwards to
+ * literals. Never start from a constant and guess that it might be shown.
+ */
+import ts from "typescript";
+import { isFile, readText, rel } from "./fs.js";
+import { parseSource, resolveImport } from "./graph.js";
+export function createDataflowContext(appDir, aliases) {
+    return { appDir, aliases, components: new Map() };
+}
+export function unwrap(expression) {
+    let current = expression;
+    while (ts.isAsExpression(current) ||
+        ts.isSatisfiesExpression(current) ||
+        ts.isParenthesizedExpression(current) ||
+        ts.isTypeAssertionExpression(current) ||
+        ts.isNonNullExpression(current)) {
+        current = current.expression;
+    }
+    return current;
+}
+export function literalText(expression) {
+    if (!expression)
+        return null;
+    const inner = unwrap(expression);
+    if (ts.isStringLiteral(inner) || ts.isNoSubstitutionTemplateLiteral(inner))
+        return inner.text;
+    return null;
+}
+function isFunctionLike(node) {
+    return ts.isFunctionDeclaration(node) || ts.isArrowFunction(node) || ts.isFunctionExpression(node);
+}
+/** Find the declaration of a component by name in a module. */
+function findComponent(sourceFile, name) {
+    let found = null;
+    const visit = (node) => {
+        if (found)
+            return;
+        if (ts.isFunctionDeclaration(node) && node.name?.text === name) {
+            found = node;
+            return;
+        }
+        if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === name && node.initializer) {
+            const initializer = unwrap(node.initializer);
+            if (isFunctionLike(initializer)) {
+                found = initializer;
+                return;
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return found;
+}
+/** Names bound by the component's first parameter, with any literal defaults. */
+function destructuredProps(fn) {
+    const props = new Map();
+    const parameter = fn.parameters[0];
+    if (!parameter || !ts.isObjectBindingPattern(parameter.name))
+        return props;
+    for (const element of parameter.name.elements) {
+        if (!ts.isIdentifier(element.name))
+            continue;
+        const propName = (element.propertyName && ts.isIdentifier(element.propertyName) ? element.propertyName : element.name).text;
+        const defaultText = element.initializer ? literalText(element.initializer) : null;
+        props.set(propName, { local: element.name.text, defaultText, defaultNode: element.initializer ?? null });
+    }
+    return props;
+}
+/** Is this identifier rendered as a JSX child somewhere inside the function? */
+function rendersAsChild(fn, local) {
+    let rendered = false;
+    const visit = (node) => {
+        if (rendered)
+            return;
+        if (ts.isJsxExpression(node) && node.expression && node.parent && (ts.isJsxElement(node.parent) || ts.isJsxFragment(node.parent))) {
+            const expression = unwrap(node.expression);
+            if (ts.isIdentifier(expression) && expression.text === local)
+                rendered = true;
+            // `{label ?? "Fallback"}` and `{label || "Fallback"}` still render the prop.
+            if (ts.isBinaryExpression(expression) && ts.isIdentifier(unwrap(expression.left)) && unwrap(expression.left).text === local)
+                rendered = true;
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(fn);
+    return rendered;
+}
+/** Is this identifier mapped into elements whose visible text is the item itself? */
+function rendersAsList(fn, local) {
+    let rendered = false;
+    const visit = (node) => {
+        if (rendered)
+            return;
+        if (ts.isCallExpression(node) &&
+            ts.isPropertyAccessExpression(node.expression) &&
+            node.expression.name.text === "map" &&
+            ts.isIdentifier(unwrap(node.expression.expression)) &&
+            unwrap(node.expression.expression).text === local) {
+            const callback = node.arguments[0];
+            if (callback && isFunctionLike(callback)) {
+                const parameter = callback.parameters[0]?.name;
+                if (parameter && ts.isIdentifier(parameter) && rendersAsChild(callback, parameter.text))
+                    rendered = true;
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(fn);
+    return rendered;
+}
+/** Which props of a component in this module render as visible text. */
+export function componentRenderInfo(sourceFile, file, name) {
+    const fn = findComponent(sourceFile, name);
+    if (!fn)
+        return null;
+    const props = new Map();
+    for (const [propName, binding] of destructuredProps(fn)) {
+        if (rendersAsChild(fn, binding.local))
+            props.set(propName, { role: "text", defaultText: binding.defaultText, defaultNode: binding.defaultNode });
+        else if (rendersAsList(fn, binding.local))
+            props.set(propName, { role: "list", defaultText: null, defaultNode: null });
+    }
+    return { props, sourceFile, file };
+}
+/** Where a JSX tag used in `sourceFile` is defined, following one local import. */
+export function resolveComponent(context, sourceFile, absoluteFile, tag) {
+    if (!/^[A-Z]/.test(tag) || tag.includes("."))
+        return null;
+    const cacheKey = `${absoluteFile}#${tag}`;
+    const cached = context.components.get(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    context.components.set(cacheKey, null); // guard against import cycles
+    let info = componentRenderInfo(sourceFile, rel(context.appDir, absoluteFile), tag);
+    if (!info) {
+        for (const statement of sourceFile.statements) {
+            if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || !statement.importClause || statement.importClause.isTypeOnly)
+                continue;
+            const bindings = statement.importClause.namedBindings;
+            let exported = null;
+            if (statement.importClause.name?.text === tag)
+                exported = "default";
+            if (bindings && ts.isNamedImports(bindings)) {
+                for (const element of bindings.elements) {
+                    if (element.name.text === tag)
+                        exported = (element.propertyName ?? element.name).text;
+                }
+            }
+            if (!exported)
+                continue;
+            const resolved = resolveImport(absoluteFile, statement.moduleSpecifier.text, context.appDir, context.aliases);
+            if (!resolved || resolved.includes("/node_modules/") || !isFile(resolved))
+                continue;
+            const text = readText(resolved);
+            if (!text)
+                continue;
+            const moduleSource = parseSource(resolved, text);
+            info = componentRenderInfo(moduleSource, rel(context.appDir, resolved), exported === "default" ? tag : exported);
+            if (info)
+                break;
+        }
+    }
+    context.components.set(cacheKey, info);
+    return info;
+}
+/** The nearest enclosing function, else the source file. */
+export function enclosingScope(node) {
+    let current = node.parent;
+    while (current && !ts.isSourceFile(current)) {
+        if (isFunctionLike(current))
+            return current;
+        current = current.parent;
+    }
+    return node.getSourceFile();
+}
+/** Find `const NAME = …` visible from `node`, searching inner scopes first. */
+export function findBinding(node, name) {
+    const scopes = [];
+    let current = node;
+    while (current) {
+        if (isFunctionLike(current) || ts.isSourceFile(current))
+            scopes.push(current);
+        current = current.parent;
+    }
+    for (const scope of scopes) {
+        let found = null;
+        const visit = (inner) => {
+            if (found)
+                return;
+            if (ts.isVariableDeclaration(inner) && ts.isIdentifier(inner.name) && inner.name.text === name && inner.initializer) {
+                found = inner;
+                return;
+            }
+            // Do not descend into nested functions; their locals are not in scope here.
+            if (inner !== scope && isFunctionLike(inner))
+                return;
+            ts.forEachChild(inner, visit);
+        };
+        ts.forEachChild(scope, visit);
+        if (found)
+            return found;
+    }
+    return null;
+}
+/** Elements of an array literal that are all plain string literals. */
+export function arrayOfStrings(expression) {
+    if (!expression)
+        return null;
+    const inner = unwrap(expression);
+    if (!ts.isArrayLiteralExpression(inner) || inner.elements.length === 0)
+        return null;
+    const elements = inner.elements.map((element) => unwrap(element));
+    return elements.every((element) => literalText(element) !== null) ? elements : null;
+}
+/** An object literal whose every value is an array of strings, keyed by property name. */
+export function recordOfStringArrays(expression) {
+    if (!expression)
+        return null;
+    const inner = unwrap(expression);
+    if (!ts.isObjectLiteralExpression(inner) || inner.properties.length === 0)
+        return null;
+    const record = new Map();
+    for (const property of inner.properties) {
+        if (!ts.isPropertyAssignment(property))
+            return null;
+        const key = ts.isIdentifier(property.name) || ts.isStringLiteral(property.name) ? property.name.text : null;
+        const elements = arrayOfStrings(property.initializer);
+        if (!key || !elements)
+            return null;
+        record.set(key, elements);
+    }
+    return record;
+}
+/**
+ * The literal a setter call actually assigns: the argument itself, or the
+ * fallback of `data.error ?? "Something went wrong."`, which is the string a
+ * reader sees whenever the other side supplies nothing.
+ */
+function assignedLiteral(expression) {
+    if (!expression)
+        return null;
+    const inner = unwrap(expression);
+    if (literalText(inner) !== null)
+        return inner;
+    if (ts.isBinaryExpression(inner) && (inner.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken || inner.operatorToken.kind === ts.SyntaxKind.BarBarToken)) {
+        const right = unwrap(inner.right);
+        if (literalText(right) !== null)
+            return right;
+    }
+    return null;
+}
+/**
+ * Literals a `useState` value can hold: its initializer and every literal
+ * passed to its setter. Only recognised for the exact
+ * `const [value, setValue] = useState(...)` shape.
+ */
+export function stateLiterals(scope, name) {
+    let setter = null;
+    let initial = null;
+    const findDeclaration = (node) => {
+        if (setter)
+            return;
+        if (ts.isVariableDeclaration(node) &&
+            ts.isArrayBindingPattern(node.name) &&
+            node.name.elements.length === 2 &&
+            node.initializer &&
+            ts.isCallExpression(node.initializer) &&
+            /^(useState|React\.useState)$/.test(node.initializer.expression.getText())) {
+            const [value, set] = node.name.elements;
+            if (value && ts.isBindingElement(value) && ts.isIdentifier(value.name) && value.name.text === name && set && ts.isBindingElement(set) && ts.isIdentifier(set.name)) {
+                setter = set.name.text;
+                initial = node.initializer.arguments[0] ?? null;
+            }
+        }
+        ts.forEachChild(node, findDeclaration);
+    };
+    ts.forEachChild(scope, findDeclaration);
+    if (!setter)
+        return null;
+    const literals = [];
+    const initialLiteral = assignedLiteral(initial ?? undefined);
+    if (initialLiteral)
+        literals.push(initialLiteral);
+    const collect = (node) => {
+        if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === setter) {
+            const assigned = assignedLiteral(node.arguments[0]);
+            if (assigned)
+                literals.push(assigned);
+        }
+        ts.forEachChild(node, collect);
+    };
+    ts.forEachChild(scope, collect);
+    return literals.length > 0 ? literals : null;
+}
+/** The callback of `<target>.map(cb)`, when the call maps `target`. */
+export function mapCallbackOf(node) {
+    if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression))
+        return null;
+    if (node.expression.name.text !== "map" && node.expression.name.text !== "flatMap")
+        return null;
+    const callback = node.arguments[0];
+    if (!callback || !isFunctionLike(callback))
+        return null;
+    return { target: unwrap(node.expression.expression), callback };
+}
+/** Does this callback render its first parameter directly as visible text? */
+export function callbackRendersItem(callback) {
+    const parameter = callback.parameters[0]?.name;
+    if (!parameter || !ts.isIdentifier(parameter))
+        return false;
+    return rendersAsChild(callback, parameter.text);
+}
+/** The object-literal field an identifier in a map callback refers to (`item.answer`). */
+export function fieldNameOf(expression, paramName, destructured) {
+    const inner = unwrap(expression);
+    if (paramName && ts.isPropertyAccessExpression(inner) && ts.isIdentifier(inner.expression) && inner.expression.text === paramName)
+        return inner.name.text;
+    if (ts.isIdentifier(inner) && destructured.has(inner.text))
+        return inner.text;
+    return null;
+}

package/dist/fs.d.ts

@@ -0,0 +1,20 @@
+export declare const IGNORED_DIRS: Set<string>;
+export declare const SOURCE_EXTENSIONS: string[];
+export declare function toPosix(path: string): string;
+export declare function rel(root: string, absolute: string): string;
+export declare function exists(path: string): boolean;
+export declare function isFile(path: string): boolean;
+export declare function isDirectory(path: string): boolean;
+export declare function readText(path: string): string | null;
+export declare function readJson<T = unknown>(path: string): T | null;
+/** Good enough for tsconfig-style JSON with comments and trailing commas. */
+export declare function stripJsonComments(text: string): string;
+export interface WalkOptions {
+    readonly extensions?: readonly string[];
+    readonly maxDepth?: number;
+    readonly ignore?: (relativePath: string, name: string) => boolean;
+}
+/** Recursively list files under `dir`, skipping build output and dependencies. */
+export declare function walkFiles(dir: string, options?: WalkOptions): string[];
+export declare function isTestOrStoryFile(relativePath: string): boolean;
+export declare function findUp(start: string, names: readonly string[], stopAt?: string): string | null;

package/dist/fs.js

@@ -0,0 +1,131 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+export const IGNORED_DIRS = new Set([
+    "node_modules",
+    ".git",
+    ".next",
+    ".nuxt",
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    ".turbo",
+    ".vercel",
+    ".netlify",
+    ".cache",
+    ".refino",
+    // A site onboarded before the Refino rename still has this directory.
+    ".inline-copy",
+    "storybook-static",
+    "__tests__",
+    "__mocks__",
+    "e2e",
+    "cypress",
+    "playwright",
+]);
+export const SOURCE_EXTENSIONS = [".tsx", ".ts", ".jsx", ".js", ".mjs", ".cjs"];
+export function toPosix(path) {
+    return path.split(sep).join("/");
+}
+export function rel(root, absolute) {
+    return toPosix(relative(root, absolute)) || ".";
+}
+export function exists(path) {
+    return existsSync(path);
+}
+export function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function readText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+export function readJson(path) {
+    const text = readText(path);
+    if (text === null)
+        return null;
+    try {
+        return JSON.parse(stripJsonComments(text));
+    }
+    catch {
+        return null;
+    }
+}
+/** Good enough for tsconfig-style JSON with comments and trailing commas. */
+export function stripJsonComments(text) {
+    return text
+        .replace(/\/\*[\s\S]*?\*\//g, "")
+        .replace(/^\s*\/\/.*$/gm, "")
+        .replace(/,(\s*[}\]])/g, "$1");
+}
+/** Recursively list files under `dir`, skipping build output and dependencies. */
+export function walkFiles(dir, options = {}) {
+    const extensions = options.extensions ?? SOURCE_EXTENSIONS;
+    const maxDepth = options.maxDepth ?? 12;
+    const results = [];
+    const visit = (current, depth) => {
+        if (depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(current);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries.sort()) {
+            const absolute = join(current, name);
+            const relPath = rel(dir, absolute);
+            if (options.ignore?.(relPath, name))
+                continue;
+            if (isDirectory(absolute)) {
+                if (IGNORED_DIRS.has(name) || name.startsWith("."))
+                    continue;
+                visit(absolute, depth + 1);
+            }
+            else if (extensions.some((ext) => name.endsWith(ext))) {
+                results.push(absolute);
+            }
+        }
+    };
+    visit(resolve(dir), 0);
+    return results;
+}
+const TEST_FILE_PATTERN = /(\.(test|spec|stories|story)\.[cm]?[jt]sx?$)|(^|\/)(tests?|__tests__|__mocks__|stories|fixtures)\//;
+export function isTestOrStoryFile(relativePath) {
+    return TEST_FILE_PATTERN.test(relativePath);
+}
+export function findUp(start, names, stopAt) {
+    let current = resolve(start);
+    for (let index = 0; index < 20; index += 1) {
+        for (const name of names) {
+            const candidate = join(current, name);
+            if (existsSync(candidate))
+                return candidate;
+        }
+        if (stopAt && resolve(stopAt) === current)
+            return null;
+        const parent = resolve(current, "..");
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+    return null;
+}

package/dist/graph.d.ts

@@ -0,0 +1,45 @@
+import ts from "typescript";
+import type { Framework, RouteInfo, Router } from "./types.js";
+export interface RouteDiscovery {
+    readonly router: Router;
+    readonly routesDir: string | null;
+    readonly routes: readonly RouteInfo[];
+    readonly layouts: readonly string[];
+    readonly entry: string | null;
+}
+/** Parse a file once; JSX is enabled for every extension so .js files with JSX work. */
+export declare function parseSource(file: string, text: string): ts.SourceFile;
+export interface PathAliases {
+    readonly baseUrl: string;
+    readonly paths: Readonly<Record<string, readonly string[]>>;
+}
+export declare function readPathAliases(appDir: string): PathAliases;
+export declare function resolveImport(fromFile: string, specifier: string, appDir: string, aliases: PathAliases): string | null;
+export declare function localImports(source: ts.SourceFile, file: string, appDir: string, aliases: PathAliases): string[];
+export interface ReachabilityEntry {
+    readonly imports: readonly string[];
+    readonly jsx: boolean;
+}
+export type ReachabilityCache = Map<string, ReachabilityEntry>;
+export interface ReachabilityOptions {
+    /**
+     * Follow the render tree only: a file is entered when it contains JSX (or is
+     * the start file). Data and helper modules are leaves, so a layout that
+     * imports a schema helper which imports a blog registry does not turn every
+     * post into shared chrome.
+     */
+    readonly renderTreeOnly?: boolean;
+}
+/** Files reachable from a start file through local imports, including itself. */
+export declare function reachableFiles(start: string, appDir: string, aliases: PathAliases, cache: ReachabilityCache, options?: ReachabilityOptions): Set<string>;
+export declare function discoverRoutes(appDir: string, framework: Framework, sourceDir: string): RouteDiscovery;
+export interface FileScopes {
+    /** absolute file -> route paths that reach it */
+    readonly byFile: ReadonlyMap<string, ReadonlySet<string>>;
+    /** absolute files reachable from a layout / app shell, or rendered by more than one route */
+    readonly shared: ReadonlySet<string>;
+    /** the subset of `shared` that a layout / app shell renders (true chrome) */
+    readonly fromLayouts: ReadonlySet<string>;
+}
+/** Compute which route(s) each source file belongs to, and which files are shared chrome. */
+export declare function computeFileScopes(appDir: string, routes: readonly RouteInfo[], layouts: readonly string[]): FileScopes;