toiljs 0.0.11 → 0.0.14

package/src/cli/diagnostics.ts

@@ -0,0 +1,421 @@
+/**
+ * Pure diagnostics for `toiljs doctor`. Every check is a pure function that takes already-gathered
+ * facts (versions, parsed package data, file contents, scanned routes) and returns a {@link Check}.
+ * Kept IO-free so it can be unit-tested in isolation; the file reads, config load, and rendering
+ * live in `doctor.ts`. Mirrors the pure/IO split of `validate.ts` and `features.ts`.
+ */
+import { type Preprocessor } from './features.js';
+
+export type CheckStatus = 'pass' | 'warn' | 'fail';
+
+/** One diagnostic result: a labelled outcome with an optional detail and a fix hint. */
+export interface Check {
+    readonly id: string;
+    readonly label: string;
+    readonly status: CheckStatus;
+    readonly detail?: string;
+    readonly fix?: string;
+}
+
+/** A titled group of related checks (Environment, Project, ...). */
+export interface CheckGroup {
+    readonly title: string;
+    readonly checks: Check[];
+}
+
+/** Tallied counts across all groups. */
+export interface DoctorSummary {
+    readonly pass: number;
+    readonly warn: number;
+    readonly fail: number;
+}
+
+/** Parses a version string's leading `x.y.z` into a numeric tuple (missing parts default to 0). */
+function parseVersion(v: string): [number, number, number] {
+    const m = /(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(v);
+    if (!m) return [0, 0, 0];
+    return [Number(m[1]), Number(m[2] ?? 0), Number(m[3] ?? 0)];
+}
+
+/**
+ * Whether `version` meets a simple minimum `range` (`>=x.y.z` or a bare `x.y.z`). toiljs's peer
+ * ranges are all `>=`, so a full semver resolver is unnecessary; a declared range like `^19.2.6` is
+ * compared by its floor.
+ */
+export function satisfiesMin(version: string, range: string): boolean {
+    const [a, b, c] = parseVersion(version);
+    const [x, y, z] = parseVersion(range);
+    if (a !== x) return a > x;
+    if (b !== y) return b > y;
+    return c >= z;
+}
+
+// --- Environment ----------------------------------------------------------------------------------
+
+export function checkNode(current: string, requiredRange: string): Check {
+    const ok = satisfiesMin(current, requiredRange);
+    return {
+        id: 'node',
+        label: 'Node.js',
+        status: ok ? 'pass' : 'fail',
+        detail: `${current} (requires ${requiredRange})`,
+        fix: ok ? undefined : `Upgrade Node to ${requiredRange}.`,
+    };
+}
+
+export function checkPeer(name: string, installed: string | null, range: string): Check {
+    if (installed === null) {
+        return {
+            id: `peer:${name}`,
+            label: name,
+            status: 'fail',
+            detail: `not installed (requires ${range})`,
+            fix: `Install ${name}@"${range}".`,
+        };
+    }
+    const ok = satisfiesMin(installed, range);
+    return {
+        id: `peer:${name}`,
+        label: name,
+        status: ok ? 'pass' : 'warn',
+        detail: `${installed} (requires ${range})`,
+        fix: ok ? undefined : `Update ${name} to ${range}.`,
+    };
+}
+
+export function checkPackageManager(lockfiles: readonly string[]): Check {
+    if (lockfiles.length === 0) {
+        return {
+            id: 'pm',
+            label: 'Package manager',
+            status: 'warn',
+            detail: 'no lockfile found',
+            fix: 'Run an install (npm/pnpm/yarn/bun) to create a lockfile.',
+        };
+    }
+    return { id: 'pm', label: 'Package manager', status: 'pass', detail: lockfiles.join(', ') };
+}
+
+export function checkToiljsInstalled(version: string | null): Check {
+    return version
+        ? { id: 'toiljs', label: 'toiljs', status: 'pass', detail: version }
+        : {
+              id: 'toiljs',
+              label: 'toiljs',
+              status: 'fail',
+              detail: 'not a dependency of this project',
+              fix: 'Add toiljs to dependencies, or run from the project root with --root.',
+          };
+}
+
+// --- Project + routing ----------------------------------------------------------------------------
+
+export function checkDir(id: string, label: string, exists: boolean, fix: string): Check {
+    return exists
+        ? { id, label, status: 'pass' }
+        : { id, label, status: 'fail', detail: 'missing', fix };
+}
+
+/**
+ * Whether the app entry calls `mount(...)` with a `slots` argument. Without it, parallel and
+ * intercepting routes are silently dropped (a real bug we shipped a fix for). Heuristic, regex-based.
+ */
+export function checkMountSlots(entrySource: string | null): Check {
+    const label = 'App entry mount()';
+    if (entrySource === null) {
+        return {
+            id: 'mount',
+            label,
+            status: 'warn',
+            detail: 'entry file not found',
+            fix: 'Ensure client/toil.tsx calls Toil.mount(...).',
+        };
+    }
+    const call = /\bmount\s*\(([^)]*)\)/.exec(entrySource);
+    if (!call) {
+        return {
+            id: 'mount',
+            label,
+            status: 'warn',
+            detail: 'no mount() call found',
+            fix: 'Call Toil.mount(routes, layout, notFound, globalError, slots).',
+        };
+    }
+    const hasSlots = /\bslots\b/.test(call[1]);
+    return hasSlots
+        ? { id: 'mount', label, status: 'pass', detail: 'passes slots' }
+        : {
+              id: 'mount',
+              label,
+              status: 'warn',
+              detail: 'mount() is missing the slots argument',
+              fix: 'Pass slots last: mount(routes, layout, notFound, globalError, slots). Without it, parallel and intercepting routes are ignored.',
+          };
+}
+
+export function checkRootElement(indexHtml: string | null): Check {
+    const label = 'index.html mount target';
+    if (indexHtml === null) {
+        return {
+            id: 'root-el',
+            label,
+            status: 'fail',
+            detail: 'index.html not found',
+            fix: 'Add public/index.html with <div id="root"></div>.',
+        };
+    }
+    const ok = /id\s*=\s*["']root["']/.test(indexHtml);
+    return ok
+        ? { id: 'root-el', label, status: 'pass' }
+        : {
+              id: 'root-el',
+              label,
+              status: 'fail',
+              detail: 'no element with id="root"',
+              fix: 'Add <div id="root"></div> to public/index.html.',
+          };
+}
+
+export function checkRoutesPresent(routeCount: number): Check {
+    return routeCount > 0
+        ? {
+              id: 'routes',
+              label: 'Routes',
+              status: 'pass',
+              detail: `${routeCount} route${routeCount === 1 ? '' : 's'}`,
+          }
+        : {
+              id: 'routes',
+              label: 'Routes',
+              status: 'fail',
+              detail: 'no routes found',
+              fix: 'Add a page, e.g. client/routes/index.tsx.',
+          };
+}
+
+export function checkDuplicatePatterns(patterns: readonly string[]): Check {
+    const seen = new Set<string>();
+    const dupes = new Set<string>();
+    for (const p of patterns) {
+        if (seen.has(p)) dupes.add(p);
+        else seen.add(p);
+    }
+    return dupes.size === 0
+        ? { id: 'route-dupes', label: 'Unique route patterns', status: 'pass' }
+        : {
+              id: 'route-dupes',
+              label: 'Unique route patterns',
+              status: 'warn',
+              detail: `duplicate: ${[...dupes].join(', ')}`,
+              fix: 'Two route files map to the same URL; rename or remove one.',
+          };
+}
+
+/** A source file scanned for broken asset references. */
+export interface SourceFile {
+    readonly path: string;
+    readonly source: string;
+}
+
+/** A relative asset reference that will 404 on a nested route. */
+export interface AssetIssue {
+    readonly file: string;
+    readonly line: number;
+    readonly value: string;
+}
+
+/** Whether a `src`/`href` string value is a root-relative asset path that breaks on nested routes. */
+function isBrokenRelativeAsset(value: string): boolean {
+    if (value === '') return false;
+    if (value.startsWith('/')) return false; // root-absolute, resolves the same everywhere
+    if (/^[a-z][a-z0-9+.-]*:/i.test(value)) return false; // http:, https:, data:, mailto:, ...
+    if (value.startsWith('#') || value.startsWith('?')) return false;
+    // Only flag asset-looking values (a real file extension), to avoid false positives on app routes.
+    return /\.(svgz?|png|jpe?g|gif|webp|avif|ico|css|m?js|woff2?|ttf|otf|eot|mp4|webm|json)$/i.test(
+        value,
+    );
+}
+
+/** Finds string-literal `src=`/`href=` attributes pointing at broken relative asset paths. */
+export function findRelativeAssets(files: readonly SourceFile[]): AssetIssue[] {
+    const issues: AssetIssue[] = [];
+    const attr = /\b(?:src|href)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+    for (const file of files) {
+        const lines = file.source.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            attr.lastIndex = 0;
+            let m: RegExpExecArray | null;
+            while ((m = attr.exec(lines[i])) !== null) {
+                const value = m[1] ?? m[2] ?? '';
+                if (isBrokenRelativeAsset(value)) {
+                    issues.push({ file: file.path, line: i + 1, value });
+                }
+            }
+        }
+    }
+    return issues;
+}
+
+export function checkRelativeAssets(issues: readonly AssetIssue[]): Check {
+    if (issues.length === 0) return { id: 'rel-assets', label: 'Asset paths', status: 'pass' };
+    const shown = issues
+        .slice(0, 5)
+        .map((i) => `${i.file}:${String(i.line)} "${i.value}"`)
+        .join('; ');
+    const more = issues.length > 5 ? `, and ${String(issues.length - 5)} more` : '';
+    return {
+        id: 'rel-assets',
+        label: 'Asset paths',
+        status: 'warn',
+        detail: `${String(issues.length)} relative reference(s): ${shown}${more}`,
+        fix: 'Use a root-absolute path (e.g. "/images/logo.svg") or import the asset; relative paths 404 on nested routes.',
+    };
+}
+
+// --- Config + assets ------------------------------------------------------------------------------
+
+export function checkConfigLoads(loaded: boolean, error?: string): Check {
+    return loaded
+        ? { id: 'config', label: 'toil.config loads', status: 'pass' }
+        : {
+              id: 'config',
+              label: 'toil.config loads',
+              status: 'fail',
+              detail: error ?? 'failed to load',
+              fix: 'Fix the error in your toil.config.* so dev/build can read it.',
+          };
+}
+
+export function checkBasePath(base: string): Check {
+    const ok = base === '/' || (base.startsWith('/') && base.endsWith('/'));
+    return ok
+        ? { id: 'base', label: 'Base path', status: 'pass', detail: base }
+        : {
+              id: 'base',
+              label: 'Base path',
+              status: 'warn',
+              detail: `"${base}"`,
+              fix: 'A non-root base should start and end with "/" (e.g. "/app/").',
+          };
+}
+
+export function checkSeoUrl(seoConfigured: boolean, hasUrl: boolean): Check {
+    if (!seoConfigured) {
+        return {
+            id: 'seo-url',
+            label: 'SEO site url',
+            status: 'pass',
+            detail: 'SEO not configured',
+        };
+    }
+    return hasUrl
+        ? { id: 'seo-url', label: 'SEO site url', status: 'pass' }
+        : {
+              id: 'seo-url',
+              label: 'SEO site url',
+              status: 'warn',
+              detail: 'seo is set without a url',
+              fix: 'Set client.seo.url so sitemap.xml and canonical links are absolute.',
+          };
+}
+
+/** Facts about the project's styling setup, derived by the orchestrator. */
+export interface StylingFacts {
+    readonly preprocessorImported: Preprocessor | null;
+    readonly preprocessorInstalled: boolean;
+    readonly tailwindImported: boolean;
+    readonly tailwindInstalled: boolean;
+}
+
+export function checkStyling(f: StylingFacts): Check {
+    const label = 'Styling';
+    if (f.preprocessorImported && f.preprocessorImported !== 'css' && !f.preprocessorInstalled) {
+        return {
+            id: 'styling',
+            label,
+            status: 'fail',
+            detail: `${f.preprocessorImported} stylesheet imported but ${f.preprocessorImported} is not installed`,
+            fix: `Install ${f.preprocessorImported}, or run toiljs configure.`,
+        };
+    }
+    if (f.tailwindImported && !f.tailwindInstalled) {
+        return {
+            id: 'styling',
+            label,
+            status: 'fail',
+            detail: 'Tailwind entry imported but @tailwindcss/vite is not installed',
+            fix: 'Run toiljs configure --tailwind, or install @tailwindcss/vite.',
+        };
+    }
+    return { id: 'styling', label, status: 'pass' };
+}
+
+// --- Server / WASM --------------------------------------------------------------------------------
+
+export function checkToilconfig(present: boolean): Check {
+    return present
+        ? { id: 'toilconfig', label: 'Server target (toilconfig.json)', status: 'pass' }
+        : {
+              id: 'toilconfig',
+              label: 'Server target (toilconfig.json)',
+              status: 'warn',
+              detail: 'no toilconfig.json (no WebAssembly server)',
+              fix: 'Add toilconfig.json + a server/ entry if you want a WASM backend.',
+          };
+}
+
+export function checkServerEntry(missing: readonly string[]): Check {
+    return missing.length === 0
+        ? { id: 'server-entry', label: 'Server entries', status: 'pass' }
+        : {
+              id: 'server-entry',
+              label: 'Server entries',
+              status: 'fail',
+              detail: `missing: ${missing.join(', ')}`,
+              fix: 'Create the entry file(s) listed in toilconfig.json "entries", or update them.',
+          };
+}
+
+export function checkToilscriptInstalled(installed: boolean): Check {
+    return installed
+        ? { id: 'toilscript', label: 'toilscript compiler', status: 'pass' }
+        : {
+              id: 'toilscript',
+              label: 'toilscript compiler',
+              status: 'warn',
+              detail: 'toilconfig.json present but toilscript is not installed',
+              fix: 'Install toilscript to compile the server to WebAssembly.',
+          };
+}
+
+export function checkWasmBuilt(exists: boolean): Check {
+    return exists
+        ? { id: 'wasm', label: 'Server build', status: 'pass' }
+        : {
+              id: 'wasm',
+              label: 'Server build',
+              status: 'warn',
+              detail: 'no compiled .wasm found',
+              fix: 'Run your server build (toilscript) before toiljs start.',
+          };
+}
+
+// --- Summary --------------------------------------------------------------------------------------
+
+export function summarize(groups: readonly CheckGroup[]): DoctorSummary {
+    let pass = 0;
+    let warn = 0;
+    let fail = 0;
+    for (const group of groups) {
+        for (const check of group.checks) {
+            if (check.status === 'pass') pass++;
+            else if (check.status === 'warn') warn++;
+            else fail++;
+        }
+    }
+    return { pass, warn, fail };
+}
+
+export function hasFailures(summary: DoctorSummary): boolean {
+    return summary.fail > 0;
+}