@getrefino/onboarding 0.1.0-rc.1

package/dist/graph.js

@@ -0,0 +1,299 @@
+/**
+ * Source graph: parse files with the TypeScript compiler, resolve local
+ * imports, discover routes per framework, and compute which files belong
+ * to which route (or are shared chrome).
+ */
+import { dirname, join, resolve } from "node:path";
+import ts from "typescript";
+import { exists, isDirectory, isFile, readJson, readText, rel, walkFiles } from "./fs.js";
+const PAGE_EXTENSIONS = ["tsx", "jsx", "ts", "js"];
+function findWithExtensions(base) {
+    for (const ext of PAGE_EXTENSIONS) {
+        const candidate = `${base}.${ext}`;
+        if (isFile(candidate))
+            return candidate;
+    }
+    return null;
+}
+function nextAppRoutes(appDir, routesDir) {
+    const routes = [];
+    const layouts = [];
+    const dir = join(appDir, routesDir);
+    for (const file of walkFiles(dir)) {
+        const relative = rel(dir, file);
+        const segments = relative.split("/");
+        const name = segments.pop();
+        const match = name.match(/^(page|layout|template|not-found|error|loading|default)\.(tsx|jsx|ts|js)$/);
+        if (!match)
+            continue;
+        const kind = match[1];
+        const urlSegments = segments
+            .filter((segment) => !segment.startsWith("(") && !segment.startsWith("@") && !segment.startsWith("_"))
+            .map((segment) => segment);
+        const path = `/${urlSegments.join("/")}`.replace(/\/+/g, "/");
+        if (kind === "page")
+            routes.push({ path: path === "" ? "/" : path, file: rel(appDir, file) });
+        else if (kind === "layout" || kind === "template")
+            layouts.push(rel(appDir, file));
+    }
+    routes.sort((a, b) => (a.path === "/" ? -1 : b.path === "/" ? 1 : a.path.localeCompare(b.path)));
+    return { routes, layouts };
+}
+function nextPagesRoutes(appDir, routesDir) {
+    const routes = [];
+    const layouts = [];
+    const dir = join(appDir, routesDir);
+    for (const file of walkFiles(dir)) {
+        const relative = rel(dir, file);
+        if (relative.startsWith("api/"))
+            continue;
+        const withoutExt = relative.replace(/\.(tsx|jsx|ts|js)$/, "");
+        const name = withoutExt.split("/").pop();
+        if (name === "_app" || name === "_document") {
+            if (name === "_app")
+                layouts.push(rel(appDir, file));
+            continue;
+        }
+        if (name.startsWith("_"))
+            continue;
+        const path = `/${withoutExt.replace(/(^|\/)index$/, "")}`.replace(/\/+/g, "/") || "/";
+        routes.push({ path: path === "" ? "/" : path, file: rel(appDir, file) });
+    }
+    routes.sort((a, b) => (a.path === "/" ? -1 : b.path === "/" ? 1 : a.path.localeCompare(b.path)));
+    return { routes, layouts };
+}
+function findEntry(appDir, sourceDir) {
+    const bases = ["main", "index", "App", "app"];
+    for (const base of bases) {
+        const found = findWithExtensions(join(appDir, sourceDir, base));
+        if (found)
+            return found;
+    }
+    return null;
+}
+/** Parse a file once; JSX is enabled for every extension so .js files with JSX work. */
+export function parseSource(file, text) {
+    const kind = file.endsWith(".ts") ? ts.ScriptKind.TS : file.endsWith(".js") || file.endsWith(".mjs") || file.endsWith(".cjs") ? ts.ScriptKind.JSX : file.endsWith(".jsx") ? ts.ScriptKind.JSX : ts.ScriptKind.TSX;
+    return ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, kind);
+}
+export function readPathAliases(appDir) {
+    const configPath = ["tsconfig.json", "jsconfig.json"].map((name) => join(appDir, name)).find((path) => isFile(path));
+    const config = configPath ? readJson(configPath) : null;
+    const baseUrl = resolve(appDir, config?.compilerOptions?.baseUrl ?? ".");
+    const paths = config?.compilerOptions?.paths ?? {};
+    return { baseUrl, paths };
+}
+export function resolveImport(fromFile, specifier, appDir, aliases) {
+    let target = null;
+    if (specifier.startsWith(".")) {
+        target = resolve(dirname(fromFile), specifier);
+    }
+    else {
+        for (const [pattern, targets] of Object.entries(aliases.paths)) {
+            const prefix = pattern.replace(/\*$/, "");
+            if (!specifier.startsWith(prefix))
+                continue;
+            const rest = specifier.slice(prefix.length);
+            const first = targets[0];
+            if (!first)
+                continue;
+            target = resolve(aliases.baseUrl, first.replace(/\*$/, "") + rest);
+            break;
+        }
+        if (!target && (specifier.startsWith("@/") || specifier.startsWith("~/"))) {
+            const rest = specifier.slice(2);
+            const srcCandidate = resolve(appDir, "src", rest);
+            target = exists(resolve(appDir, "src")) && (findWithExtensions(srcCandidate) || isDirectory(srcCandidate)) ? srcCandidate : resolve(appDir, rest);
+        }
+    }
+    if (!target)
+        return null;
+    if (isFile(target))
+        return target;
+    return findWithExtensions(target) ?? findWithExtensions(join(target, "index"));
+}
+export function localImports(source, file, appDir, aliases) {
+    const results = [];
+    const visit = (node) => {
+        let specifier = null;
+        if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier))
+            specifier = node.moduleSpecifier.text;
+        else if (ts.isExportDeclaration(node) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier))
+            specifier = node.moduleSpecifier.text;
+        else if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && node.arguments[0] && ts.isStringLiteral(node.arguments[0]))
+            specifier = node.arguments[0].text;
+        if (specifier) {
+            const resolved = resolveImport(file, specifier, appDir, aliases);
+            if (resolved && resolved.startsWith(appDir) && !resolved.includes("/node_modules/"))
+                results.push(resolved);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return results;
+}
+function containsJsx(source) {
+    let found = false;
+    const visit = (node) => {
+        if (found)
+            return;
+        if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) {
+            found = true;
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return found;
+}
+/** Files reachable from a start file through local imports, including itself. */
+export function reachableFiles(start, appDir, aliases, cache, options = {}) {
+    const seen = new Set();
+    const stack = [start];
+    while (stack.length > 0) {
+        const file = stack.pop();
+        if (seen.has(file))
+            continue;
+        let entry = cache.get(file);
+        if (!entry) {
+            const text = readText(file);
+            const source = text ? parseSource(file, text) : null;
+            entry = { imports: source ? localImports(source, file, appDir, aliases) : [], jsx: source ? containsJsx(source) : false };
+            cache.set(file, entry);
+        }
+        if (options.renderTreeOnly && file !== start && !entry.jsx)
+            continue;
+        seen.add(file);
+        for (const next of entry.imports)
+            if (!seen.has(next))
+                stack.push(next);
+    }
+    return seen;
+}
+/** react-router: map <Route path="/x" element={<Foo/>}> to the component's file. */
+function reactRouterRoutes(entry, appDir, aliases) {
+    const cache = new Map();
+    const files = reachableFiles(entry, appDir, aliases, cache);
+    const routes = [];
+    for (const file of files) {
+        const text = readText(file);
+        if (!text || !text.includes("Route"))
+            continue;
+        const source = parseSource(file, text);
+        const importedFrom = new Map();
+        for (const statement of source.statements) {
+            if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier))
+                continue;
+            const clause = statement.importClause;
+            const resolved = resolveImport(file, statement.moduleSpecifier.text, appDir, aliases);
+            if (!clause || !resolved)
+                continue;
+            if (clause.name)
+                importedFrom.set(clause.name.text, resolved);
+            if (clause.namedBindings && ts.isNamedImports(clause.namedBindings)) {
+                for (const element of clause.namedBindings.elements)
+                    importedFrom.set(element.name.text, resolved);
+            }
+        }
+        const visit = (node) => {
+            if ((ts.isJsxSelfClosingElement(node) || ts.isJsxOpeningElement(node)) && ts.isIdentifier(node.tagName) && node.tagName.text === "Route") {
+                let path = null;
+                let component = null;
+                let index = false;
+                for (const attr of node.attributes.properties) {
+                    if (!ts.isJsxAttribute(attr) || !ts.isIdentifier(attr.name))
+                        continue;
+                    const name = attr.name.text;
+                    if (name === "path" && attr.initializer && ts.isStringLiteral(attr.initializer))
+                        path = attr.initializer.text;
+                    if (name === "index")
+                        index = true;
+                    if ((name === "element" || name === "Component" || name === "component") && attr.initializer && ts.isJsxExpression(attr.initializer) && attr.initializer.expression) {
+                        const expression = attr.initializer.expression;
+                        if (ts.isJsxSelfClosingElement(expression) && ts.isIdentifier(expression.tagName))
+                            component = expression.tagName.text;
+                        else if (ts.isJsxElement(expression) && ts.isIdentifier(expression.openingElement.tagName))
+                            component = expression.openingElement.tagName.text;
+                        else if (ts.isIdentifier(expression))
+                            component = expression.text;
+                    }
+                }
+                if (index && !path)
+                    path = "/";
+                if (path && component) {
+                    const target = importedFrom.get(component);
+                    routes.push({ path: path.startsWith("/") ? path : `/${path}`, file: rel(appDir, target ?? file) });
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(source);
+    }
+    routes.sort((a, b) => (a.path === "/" ? -1 : b.path === "/" ? 1 : a.path.localeCompare(b.path)));
+    return routes;
+}
+export function discoverRoutes(appDir, framework, sourceDir) {
+    if (framework === "next") {
+        const appRoutesDir = ["app", "src/app"].find((dir) => isDirectory(join(appDir, dir)));
+        const pagesRoutesDir = ["pages", "src/pages"].find((dir) => isDirectory(join(appDir, dir)));
+        if (appRoutesDir) {
+            const { routes, layouts } = nextAppRoutes(appDir, appRoutesDir);
+            return { router: "next-app", routesDir: appRoutesDir, routes, layouts, entry: null };
+        }
+        if (pagesRoutesDir) {
+            const { routes, layouts } = nextPagesRoutes(appDir, pagesRoutesDir);
+            return { router: "next-pages", routesDir: pagesRoutesDir, routes, layouts, entry: null };
+        }
+        return { router: "unknown", routesDir: null, routes: [], layouts: [], entry: null };
+    }
+    if (framework === "vite-react" || framework === "react") {
+        const entry = findEntry(appDir, sourceDir);
+        if (!entry)
+            return { router: "unknown", routesDir: null, routes: [], layouts: [], entry: null };
+        const aliases = readPathAliases(appDir);
+        const pkg = readJson(join(appDir, "package.json"));
+        const usesRouter = Boolean(pkg?.dependencies?.["react-router"] || pkg?.dependencies?.["react-router-dom"] || pkg?.devDependencies?.["react-router-dom"]);
+        if (usesRouter) {
+            const routes = reactRouterRoutes(entry, appDir, aliases);
+            if (routes.length > 0)
+                return { router: "react-router", routesDir: null, routes, layouts: [rel(appDir, entry)], entry: rel(appDir, entry) };
+        }
+        const appFile = findWithExtensions(join(appDir, sourceDir, "App")) ?? entry;
+        return { router: "single-page", routesDir: null, routes: [{ path: "/", file: rel(appDir, appFile) }], layouts: [], entry: rel(appDir, entry) };
+    }
+    return { router: "unknown", routesDir: null, routes: [], layouts: [], entry: null };
+}
+/** Compute which route(s) each source file belongs to, and which files are shared chrome. */
+export function computeFileScopes(appDir, routes, layouts) {
+    const aliases = readPathAliases(appDir);
+    const cache = new Map();
+    const byFile = new Map();
+    const shared = new Set();
+    const routeFiles = new Set(routes.map((route) => resolve(appDir, route.file)));
+    const layoutFiles = new Set(layouts.map((layout) => resolve(appDir, layout)));
+    for (const layout of layoutFiles) {
+        for (const file of reachableFiles(layout, appDir, aliases, cache, { renderTreeOnly: true })) {
+            // A layout's import graph includes the page files it wraps only on
+            // Pages Router (_app imports nothing); route files never count as shared.
+            if (!routeFiles.has(file))
+                shared.add(file);
+        }
+    }
+    for (const route of routes) {
+        const start = resolve(appDir, route.file);
+        for (const file of reachableFiles(start, appDir, aliases, cache, { renderTreeOnly: true })) {
+            if (layoutFiles.has(file))
+                continue;
+            let set = byFile.get(file);
+            if (!set)
+                byFile.set(file, (set = new Set()));
+            set.add(route.path);
+        }
+    }
+    const fromLayouts = new Set(shared);
+    for (const [file, set] of byFile) {
+        if (set.size > 1 && !routeFiles.has(file))
+            shared.add(file);
+    }
+    return { byFile, shared, fromLayouts };
+}

package/dist/ids.d.ts

@@ -0,0 +1,20 @@
+import type { RawCandidate } from "./scan.js";
+export interface ProposedId {
+    readonly raw: RawCandidate;
+    readonly id: string | null;
+    readonly idReason: string | null;
+    readonly review: boolean;
+}
+export declare function camel(words: readonly string[]): string;
+export declare function slugFromText(text: string, maxWords?: number): string;
+/** Last meaningful segment of a site path: "/features/privacy" -> "privacy", "/#how-it-works" -> "howItWorks", "/" -> "home". */
+export declare function pathSegment(path: string): string;
+export declare function componentSegment(component: string | null): string | null;
+export declare function routeSegment(route: string | null, scope: string): string;
+/** Map component names to the native element they stand in for. */
+export declare function normalizeElement(element: string | null): string;
+/**
+ * Assign IDs to all candidates, resolving collisions semantically where
+ * possible (second CTA -> secondaryCta) and flagging the rest for review.
+ */
+export declare function proposeIds(candidates: readonly RawCandidate[]): ProposedId[];