@mizen-labs/cli 0.0.0-stage → 0.1.0

package/dist/doctor/report.js

@@ -0,0 +1,94 @@
+import { isAbsolute, relative } from "node:path";
+import { plural, row, status as statusLine } from "../output.js";
+export function check(id, status, message, evidence = [], repair) {
+    return {
+        evidence,
+        id,
+        message,
+        status,
+        ...(repair && status !== "pass" ? { repair } : {}),
+    };
+}
+export function report(project, diagnostics) {
+    const errors = diagnostics.filter((item) => item.status === "error").length;
+    const unverified = diagnostics.filter((item) => item.status === "unverified").length;
+    let status = "healthy";
+    if (unverified) {
+        status = "incomplete";
+    }
+    if (errors) {
+        status = "failed";
+    }
+    return {
+        diagnostics,
+        project,
+        status,
+        summary: {
+            errors,
+            passed: diagnostics.length - errors - unverified,
+            unverified,
+        },
+    };
+}
+// Paths inside the app read relative to it; others stay absolute.
+function shown(path, base) {
+    if (!base) {
+        return path;
+    }
+    const inside = relative(base, path);
+    return inside && !inside.startsWith("..") && !isAbsolute(inside)
+        ? inside
+        : path;
+}
+/** A finding as a status headline with its check, evidence, and fix. */
+export function formatDiagnostic(style, item, base = null) {
+    return [
+        statusLine(style, item.status === "error" ? "fail" : "warn", item.message),
+        row("Check", item.id),
+        ...(item.evidence.length
+            ? [
+                row("Evidence", item.evidence.map((path) => shown(path, base))),
+            ]
+            : []),
+        ...(item.repair ? [row("Next step", item.repair)] : []),
+        "",
+    ];
+}
+/** The closing line: the outcome, then the counts. */
+export function summaryLine(style, result) {
+    const { errors, passed, unverified } = result.summary;
+    if (errors) {
+        return statusLine(style, "fail", `Found ${plural(errors, "error")}. ${unverified} unverified, ${passed} passed.`);
+    }
+    if (unverified) {
+        return statusLine(style, "warn", `Couldn't verify ${plural(unverified, "check")}. ${passed} passed.`);
+    }
+    return statusLine(style, "pass", `Healthy. ${plural(passed, "check")} passed.`);
+}
+// Each passing check's id beside its message, in one aligned column.
+function passedRows(passed) {
+    const width = Math.max(...passed.map((item) => item.id.length)) + 2;
+    return passed.map((item) => `  ${item.id.padEnd(width)}${item.message}`);
+}
+export function formatReport(style, result) {
+    const findings = result.diagnostics.filter((item) => item.status !== "pass");
+    const passed = result.diagnostics.filter((item) => item.status === "pass");
+    return [
+        row("Project", result.project ?? "Not found"),
+        "",
+        ...findings.flatMap((item) => formatDiagnostic(style, item, result.project)),
+        ...(passed.length ? [style.bold("Passed"), ...passedRows(passed), ""] : []),
+        summaryLine(style, result),
+    ].join("\n");
+}
+/** A diagnostic as an error block's rows, and in full for machines. */
+export function diagnosticDetail(item) {
+    const rows = [
+        ["Check", item.id],
+        ...(item.evidence.length
+            ? [["Evidence", item.evidence.join("\n")]]
+            : []),
+        ...(item.repair ? [["Next step", item.repair]] : []),
+    ];
+    return { data: { diagnostic: item }, rows };
+}

package/dist/doctor/setup.js

@@ -0,0 +1,107 @@
+import { join } from "node:path";
+import { viteSetupChecks } from "../vite/doctor.js";
+import { readOptional } from "./files.js";
+import { check } from "./report.js";
+import { documentFunction, imports, isNode, jsxName, literal, literalTrue, nameOf, nodes, parseSource, property, staticArrayContains, staticConfig, } from "./syntax.js";
+async function sourceAt(project, candidates) {
+    const found = (await Promise.all(candidates.map(async (candidate) => {
+        const path = join(project, candidate);
+        const source = await readOptional(path);
+        return source === null ? null : { path, source };
+    }))).filter((item) => item !== null);
+    return found.length === 1 ? found[0] : null;
+}
+async function configCheck(project, framework) {
+    const prefix = framework === "next" ? "next.config" : "vite.config";
+    const file = await sourceAt(project, ["js", "mjs", "cjs", "ts", "mts", "cts"].map((extension) => `${prefix}.${extension}`));
+    const repair = framework === "next"
+        ? 'Include "@mizen-labs/ui" in transpilePackages.'
+        : 'Include "@mizen-labs/ui" in ssr.noExternal.';
+    if (!file) {
+        return check("setup.bundling", "unverified", "No single supported framework configuration was found.", [], repair);
+    }
+    let ast;
+    try {
+        ast = parseSource(file.source);
+    }
+    catch {
+        return check("setup.bundling", "unverified", "The configuration could not be parsed; it was not executed.", [file.path], "Check its syntax and verify the Mizen bundling setting manually.");
+    }
+    const config = staticConfig(ast);
+    const value = framework === "next"
+        ? property(config, "transpilePackages")
+        : property(property(config, "ssr"), "noExternal");
+    const present = framework === "start" && literalTrue(value)
+        ? true
+        : staticArrayContains(value, "@mizen-labs/ui");
+    return check("setup.bundling", present === true ? "pass" : "unverified", present === true
+        ? "The static configuration includes Mizen in framework bundling."
+        : "Bundling could not be verified. Computed, wrapped, or absent settings require manual review.", [file.path], repair);
+}
+function aliases(ast, exported) {
+    return imports(ast)
+        .filter((node) => ["@mizen-labs/ui/theme", "@mizen-labs/ui"].includes(literal(node.source) ?? ""))
+        .flatMap((node) => (Array.isArray(node.specifiers) ? node.specifiers : []))
+        .filter((node) => isNode(node) &&
+        node.importKind !== "type" &&
+        nameOf(node.imported) === exported)
+        .map((node) => (isNode(node) ? nameOf(node.local) : null))
+        .filter((name) => name !== null);
+}
+function themeCheck(ast, path, document) {
+    const scripts = aliases(ast, "ThemeScript");
+    const providers = aliases(ast, "ThemeProvider");
+    const heads = nodes(document).filter((node) => jsxName(node) === "head");
+    const bodies = nodes(document).filter((node) => jsxName(node) === "body");
+    const scriptInHead = heads.some((head) => nodes(head).some((node) => scripts.includes(jsxName(node) ?? "")));
+    const providerInBody = bodies.some((body) => nodes(body).some((node) => providers.includes(jsxName(node) ?? "")));
+    // Presence is evidence of syntax, not proof of runtime rendering or first paint.
+    return check("setup.theme", scriptInHead && providerInBody ? "pass" : "unverified", scriptInHead && providerInBody
+        ? "Root syntax contains ThemeScript in head and ThemeProvider in body; runtime behavior still needs a browser check."
+        : "Root theme bootstrap is not statically verified. It may be delegated to another component.", [path], "Render ThemeScript before body content and ThemeProvider around the app. Verify first paint and hydration in a browser.");
+}
+function stylesheetCheck(ast, path) {
+    const cssImports = imports(ast).filter((node) => literal(node.source) === "@mizen-labs/ui/styles.css");
+    const direct = cssImports.some((node) => Array.isArray(node.specifiers) && node.specifiers.length === 0);
+    const urlBindings = imports(ast)
+        .filter((node) => literal(node.source) === "@mizen-labs/ui/styles.css?url")
+        .flatMap((node) => (Array.isArray(node.specifiers) ? node.specifiers : []))
+        .map((node) => (isNode(node) ? nameOf(node.local) : null))
+        .filter((name) => name !== null);
+    const link = nodes(ast).some((node) => urlBindings.includes(nameOf(property(node, "href")) ?? "") &&
+        literal(property(node, "rel")) === "stylesheet");
+    const present = direct || link;
+    return check("setup.stylesheet", present ? "pass" : "unverified", present
+        ? "Root syntax declares Mizen's compiled stylesheet. Verify delivery in a browser."
+        : "No direct stylesheet import or URL/link declaration was verified. Indirect CSS or custom extraction may supply it.", [path], "Import @mizen-labs/ui/styles.css at the app root, or verify your equivalent CSS pipeline manually.");
+}
+export async function setupChecks(project, framework) {
+    if (framework === "vite") {
+        return viteSetupChecks(project);
+    }
+    const candidates = framework === "next"
+        ? ["app/layout", "src/app/layout"]
+        : ["src/routes/__root", "app/routes/__root"];
+    const root = await sourceAt(project, candidates.flatMap((path) => ["tsx", "jsx", "ts", "js"].map((extension) => `${path}.${extension}`)));
+    const config = await configCheck(project, framework);
+    if (!root) {
+        return [
+            config,
+            check("setup.root", "unverified", "No single conventional root layout was found.", [], "Use Next App Router or review the custom Start root configuration manually."),
+        ];
+    }
+    try {
+        const ast = parseSource(root.source);
+        return [
+            config,
+            stylesheetCheck(ast, root.path),
+            themeCheck(ast, root.path, documentFunction(ast, framework)),
+        ];
+    }
+    catch {
+        return [
+            config,
+            check("setup.root", "unverified", "The root module could not be parsed; it was not executed.", [root.path], "Check root module syntax and verify styles and theme setup manually."),
+        ];
+    }
+}

package/dist/doctor/syntax.js

@@ -0,0 +1,148 @@
+import { parse } from "@babel/parser";
+export function isNode(value) {
+    return (!!value &&
+        typeof value === "object" &&
+        "type" in value &&
+        typeof value.type === "string");
+}
+export function nodes(value) {
+    if (Array.isArray(value)) {
+        return value.flatMap(nodes);
+    }
+    if (!isNode(value)) {
+        return [];
+    }
+    return [value, ...Object.values(value).flatMap(nodes)];
+}
+export function parseSource(source) {
+    return parse(source, {
+        attachComment: false,
+        plugins: ["jsx", "typescript"],
+        sourceType: "unambiguous",
+    });
+}
+export function literal(node) {
+    return isNode(node) &&
+        node.type === "StringLiteral" &&
+        typeof node.value === "string"
+        ? node.value
+        : null;
+}
+export function nameOf(node) {
+    if (!isNode(node)) {
+        return null;
+    }
+    if (typeof node.name === "string") {
+        return node.name;
+    }
+    return literal(node);
+}
+function unwrap(node) {
+    if (!isNode(node)) {
+        return node;
+    }
+    if (["TSAsExpression", "TSSatisfiesExpression", "TSNonNullExpression"].includes(node.type)) {
+        return unwrap(node.expression);
+    }
+    return node;
+}
+export function staticConfig(ast) {
+    const exported = nodes(ast).find((node) => node.type === "ExportDefaultDeclaration");
+    if (!exported) {
+        return null;
+    }
+    let value = unwrap(exported.declaration);
+    if (isNode(value) && value.type === "CallExpression") {
+        value = viteConfigArgument(ast, value);
+    }
+    if (isNode(value) && value.type === "Identifier") {
+        const identifier = value.name;
+        if (nodes(ast).filter((node) => node.type === "Identifier" && node.name === identifier).length !== 2) {
+            return null;
+        }
+        const variable = nodes(ast).find((node) => node.type === "VariableDeclarator" && nameOf(node.id) === identifier);
+        value = unwrap(variable?.init);
+    }
+    return isNode(value) && value.type === "ObjectExpression" ? value : null;
+}
+export function property(object, key) {
+    if (!isNode(object) ||
+        object.type !== "ObjectExpression" ||
+        !Array.isArray(object.properties)) {
+        return null;
+    }
+    // Any spread or computed key can override a literal property at runtime.
+    if (object.properties.some((item) => !(isNode(item) && ["ObjectProperty", "ObjectMethod"].includes(item.type)) || item.computed)) {
+        return null;
+    }
+    const found = object.properties.filter((item) => isNode(item) && nameOf(item.key) === key);
+    if (found.length !== 1) {
+        return null;
+    }
+    const selected = found[0];
+    return selected.type === "ObjectProperty" ? selected.value : null;
+}
+export function staticArrayContains(value, expected) {
+    if (!isNode(value) ||
+        value.type !== "ArrayExpression" ||
+        !Array.isArray(value.elements)) {
+        return null;
+    }
+    const strings = value.elements.map(literal);
+    if (strings.some((item) => item === null)) {
+        return null;
+    }
+    return strings.includes(expected);
+}
+export function imports(ast) {
+    return nodes(ast).filter((node) => node.type === "ImportDeclaration" && node.importKind !== "type");
+}
+export function jsxName(node) {
+    return isNode(node) &&
+        node.type === "JSXElement" &&
+        isNode(node.openingElement)
+        ? nameOf(node.openingElement.name)
+        : null;
+}
+function viteConfigArgument(ast, call) {
+    const allowed = imports(ast)
+        .filter((node) => literal(node.source) === "vite")
+        .flatMap((node) => (Array.isArray(node.specifiers) ? node.specifiers : []))
+        .filter((node) => isNode(node) && nameOf(node.imported) === "defineConfig")
+        .map((node) => (isNode(node) ? nameOf(node.local) : null));
+    if (!(allowed.includes(nameOf(call.callee)) && Array.isArray(call.arguments)) ||
+        call.arguments.length !== 1) {
+        return null;
+    }
+    return unwrap(call.arguments[0]);
+}
+function topLevelFunction(ast, name) {
+    if (!(isNode(ast.program) && Array.isArray(ast.program.body))) {
+        return null;
+    }
+    return (ast.program.body.find((node) => isNode(node) &&
+        node.type === "FunctionDeclaration" &&
+        nameOf(node.id) === name) ?? null);
+}
+export function documentFunction(ast, framework) {
+    if (framework === "next") {
+        const exported = nodes(ast).find((node) => node.type === "ExportDefaultDeclaration");
+        const value = exported?.declaration;
+        if (isNode(value) && value.type === "FunctionDeclaration") {
+            return value;
+        }
+        return topLevelFunction(ast, nameOf(value));
+    }
+    const routeImports = imports(ast)
+        .filter((node) => literal(node.source) === "@tanstack/react-router")
+        .flatMap((node) => (Array.isArray(node.specifiers) ? node.specifiers : []))
+        .filter((node) => isNode(node) && nameOf(node.imported) === "createRootRoute")
+        .map((node) => (isNode(node) ? nameOf(node.local) : null));
+    const route = nodes(ast).find((node) => node.type === "CallExpression" &&
+        routeImports.includes(nameOf(node.callee)));
+    const config = route && Array.isArray(route.arguments) ? route.arguments[0] : null;
+    return topLevelFunction(ast, nameOf(property(config, "shellComponent")));
+}
+export function literalTrue(value) {
+    return (isNode(value) && value.type === "BooleanLiteral" && value.value === true);
+}

package/dist/doctor/workspace-config.js

@@ -0,0 +1,210 @@
+import { lstat, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, join, posix, relative, resolve, sep, } from "node:path";
+import glob from "fast-glob";
+import { minimatch } from "minimatch";
+import { parseDocument } from "yaml";
+import { exists, manifestAt, readOptional } from "./files.js";
+import { check } from "./report.js";
+export class WorkspaceConfigError extends Error {
+    diagnostic;
+    constructor(diagnostic) {
+        super(diagnostic.message);
+        this.diagnostic = diagnostic;
+    }
+}
+function invalid(path, message) {
+    throw new WorkspaceConfigError(check("workspace.config", "error", message, [path], "Repair the workspace declaration, then rerun mizen doctor --workspace."));
+}
+function targetError(path, message) {
+    throw new WorkspaceConfigError(check("workspace.target", "error", message, [path], "Use --cwd with a declared workspace root, or run mizen doctor --cwd <APP_DIR> without --workspace."));
+}
+function patterns(value, path) {
+    if (!(Array.isArray(value) &&
+        value.every((item) => typeof item === "string" && item.trim().length > 0))) {
+        return invalid(path, "Workspace packages must be an array of nonempty path patterns.");
+    }
+    return value;
+}
+function npmPatterns(value, path) {
+    if (value && typeof value === "object" && "packages" in value) {
+        return patterns(value.packages, path);
+    }
+    return patterns(value, path);
+}
+async function yamlPatterns(path) {
+    const source = await readOptional(path);
+    if (source === null) {
+        return invalid(path, "The workspace declaration disappeared during discovery.");
+    }
+    const document = parseDocument(source);
+    if (document.errors.length || document.warnings.length) {
+        return invalid(path, "The pnpm workspace YAML is invalid or contains unsupported tags.");
+    }
+    const value = yamlValue(document, path);
+    if (value === null) {
+        return null;
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        return invalid(path, "The pnpm workspace declaration must be a mapping.");
+    }
+    return "packages" in value ? patterns(value.packages, path) : null;
+}
+export async function hasPnpmWorkspacePackages(project) {
+    const path = join(project, "pnpm-workspace.yaml");
+    return (await exists(path)) && (await yamlPatterns(path)) !== null;
+}
+function yamlValue(document, path) {
+    try {
+        return document.toJS();
+    }
+    catch {
+        return invalid(path, "The workspace YAML aliases could not be resolved safely.");
+    }
+}
+async function declaration(project) {
+    const yaml = join(project, "pnpm-workspace.yaml");
+    if (await exists(yaml)) {
+        return {
+            kind: "pnpm",
+            patterns: (await yamlPatterns(yaml)) ?? [],
+            project,
+            source: yaml,
+        };
+    }
+    try {
+        const manifest = await manifestAt(join(project, "package.json"));
+        if (manifest?.workspaces !== undefined) {
+            return {
+                kind: "npm",
+                patterns: npmPatterns(manifest.workspaces, join(project, "package.json")),
+                project,
+                source: join(project, "package.json"),
+            };
+        }
+    }
+    catch (error) {
+        if (error instanceof WorkspaceConfigError) {
+            throw error;
+        }
+        // A malformed member must not hide its enclosing workspace.
+    }
+    return null;
+}
+export async function findWorkspace(cwd) {
+    let directory;
+    try {
+        directory = await realpath(resolve(cwd));
+        if (!(await lstat(directory)).isDirectory()) {
+            return targetError(directory, "Select an existing workspace directory with --cwd.");
+        }
+    }
+    catch {
+        return targetError(resolve(cwd), "The requested workspace directory is unavailable.");
+    }
+    return findDeclaration(directory, resolve(cwd));
+}
+async function findDeclaration(directory, requested) {
+    const workspace = await declaration(directory);
+    if (workspace) {
+        return workspace;
+    }
+    const parent = dirname(directory);
+    return parent === directory
+        ? targetError(requested, "No pnpm-workspace.yaml or package.json workspaces declaration was found.")
+        : findDeclaration(parent, requested);
+}
+const NEGATION = /^!+/u;
+const LEADING_SLASH = /^\.?\/+/u;
+const DRIVE = /^[a-z]:\//iu;
+const PARENT_SEGMENT = /(?:^|[/({|,])\.\.(?=\/|[)}|,]|$)/u;
+const GROUPED_ABSOLUTE = /[({|,](?:\/|[a-z]:\/)/iu;
+function normalize(pattern, kind) {
+    const prefix = pattern.match(NEGATION)?.[0] ?? "";
+    let value = pattern.slice(prefix.length).replaceAll("\\", "/");
+    if (kind === "npm") {
+        value = value.replace(LEADING_SLASH, "");
+    }
+    return { negative: prefix.length % 2 === 1, value: posix.normalize(value) };
+}
+function outside(value) {
+    return (isAbsolute(value) ||
+        DRIVE.test(value) ||
+        PARENT_SEGMENT.test(value) ||
+        GROUPED_ABSOLUTE.test(value) ||
+        value === ".." ||
+        value.startsWith("../"));
+}
+async function declarationWarnings(workspace) {
+    if (workspace.kind !== "pnpm") {
+        return [];
+    }
+    const path = join(workspace.project, "package.json");
+    try {
+        const manifest = await manifestAt(path);
+        if (manifest?.workspaces === undefined) {
+            return [];
+        }
+        const npm = npmPatterns(manifest.workspaces, path).map((pattern) => normalize(pattern, "npm"));
+        const pnpm = workspace.patterns.map((pattern) => normalize(pattern, "pnpm"));
+        if (JSON.stringify(npm) === JSON.stringify(pnpm)) {
+            return [];
+        }
+    }
+    catch {
+        // Member inspection separately reports an invalid root manifest.
+        return [
+            check("workspace.declarations", "unverified", "The package.json workspace declaration cannot be compared with pnpm's declaration.", [path, workspace.source], "Align the declarations. pnpm-workspace.yaml controls this discovery."),
+        ];
+    }
+    return [
+        check("workspace.declarations", "unverified", "Workspace declarations differ; pnpm-workspace.yaml controls discovery.", [path, workspace.source], "Align package.json workspaces with the pnpm packages declaration."),
+    ];
+}
+export async function workspaceMembers(workspace) {
+    const include = [];
+    let exclude = [];
+    const diagnostics = await declarationWarnings(workspace);
+    for (const pattern of workspace.patterns) {
+        const { negative, value } = normalize(pattern, workspace.kind);
+        if (outside(value) || value.includes("${")) {
+            diagnostics.push(check("workspace.pattern", "unverified", `Discovery cannot verify this external or environment-dependent pattern: ${pattern}`, [workspace.source], "Inspect the affected app explicitly with mizen doctor --cwd <APP_DIR>."));
+            continue;
+        }
+        if (negative) {
+            exclude.push(value);
+        }
+        else {
+            // npm lets a later positive pattern override a matching earlier exclusion.
+            if (workspace.kind === "npm") {
+                exclude = exclude.filter((ignored) => !minimatch(value, ignored));
+            }
+            include.push(value);
+        }
+    }
+    const entries = include.length
+        ? await glob(include, {
+            cwd: workspace.project,
+            followSymbolicLinks: false,
+            ignore: ["**/node_modules/**", "**/.git/**", ...exclude],
+            objectMode: true,
+            onlyFiles: false,
+            unique: true,
+        })
+        : [];
+    const directories = entries
+        .filter((entry) => entry.dirent.isDirectory() || entry.dirent.isSymbolicLink())
+        .map((entry) => resolve(workspace.project, entry.path));
+    return {
+        diagnostics,
+        projects: [...new Set([workspace.project, ...directories])].sort((a, b) => a.localeCompare(b, "en")),
+    };
+}
+export async function linkedProject(project) {
+    const actual = await realpath(project);
+    return process.platform === "win32"
+        ? actual.toLowerCase() !== project.toLowerCase()
+        : actual !== project;
+}
+export function memberPath(root, project) {
+    return relative(root, project).split(sep).join("/") || ".";
+}