@vmz/vmz 0.0.1 → 0.0.3

package/dist/locale-tooling.js

@@ -0,0 +1,357 @@
+// @ts-nocheck
+/**
+ * Locale tooling: explain · diff · extract · pseudo · cross-host conformance.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { DIAG_LOCALE_CONFORMANCE_DIVERGENCE, DIAG_LOCALE_EXPLAIN_UNKNOWN, DIAG_LOCALE_HARDCODED_TEXT, DIAG_LOCALE_PSEUDO_PRODUCTION_FORBIDDEN, DIAG_MESSAGE_DYNAMIC_ID_UNBOUNDED, FORMATTER_DATA_VERSION, LOCALE_CONFORMANCE_SCHEMA, LOCALE_DIFF_SCHEMA, LOCALE_EXPLAIN_SCHEMA, LOCALE_EXTRACT_SCHEMA, LOCALE_PSEUDO_SCHEMA, } from './locale-schema.js';
+import { resolveMessageVariant } from './locale-runtime.js';
+import { assertHostMessageInvariant, buildLocaleDeliveryResolution } from './locale-delivery.js';
+/**
+ * Explain one MessageId: definition, params, variants, fallback, delivery reachability.
+ * @param {{
+ * messageId: string,
+ * locale?: string|null,
+ * deliveryId?: string|null,
+ * checkReport: any,
+ * }} input
+ */
+export function explainLocaleMessage(input) {
+    /** @type {any[]} */
+    const diagnostics = [];
+    const messages = input.checkReport?.messageCatalog?.messages || [];
+    const node = messages.find((m) => m.messageId === input.messageId);
+    if (!node) {
+        diagnostics.push({
+            code: DIAG_LOCALE_EXPLAIN_UNKNOWN,
+            severity: 'error',
+            message: `unknown MessageId ${input.messageId}`,
+        });
+        return {
+            schema: LOCALE_EXPLAIN_SCHEMA,
+            status: 'failed',
+            messageId: input.messageId,
+            diagnostics,
+        };
+    }
+    const defaultLocale = input.checkReport?.manifest?.defaultLocale;
+    const requested = input.locale || defaultLocale;
+    const fallback = input.checkReport?.manifest?.fallback || {};
+    const resolution = resolveMessageVariant({
+        messageId: input.messageId,
+        requestedLocale: requested,
+        variants: node.variants,
+        fallback,
+    });
+    const base = node.variants?.[defaultLocale] || Object.values(node.variants || {})[0];
+    const deliveryId = input.deliveryId || 'delivery.web';
+    const delivery = buildLocaleDeliveryResolution({
+        host: 'web',
+        applicationId: 'app.locales',
+        deliveryId,
+        supportedLocales: (input.checkReport?.manifest?.locales || []).map((l) => l.id),
+        defaultLocale,
+        fallback,
+        messages,
+        reachableMessageIds: [input.messageId],
+        bundledLocales: [defaultLocale],
+    });
+    const inChunk = (delivery.lazyLocaleChunks || []).concat(delivery.bundledChunks || []).some((c) => c.messageIds?.includes(input.messageId));
+    return {
+        schema: LOCALE_EXPLAIN_SCHEMA,
+        status: 'ready',
+        messageId: input.messageId,
+        catalogId: node.catalogId,
+        params: base?.params || [],
+        variants: Object.fromEntries(Object.entries(node.variants || {}).map(([loc, v]) => [loc, { template: v.template, path: v.path, params: v.params }])),
+        requestedLocale: requested,
+        resolvedLocale: resolution.resolvedLocale,
+        fallbackPath: resolution.fallbackPath,
+        formatterDataVersion: FORMATTER_DATA_VERSION,
+        delivery: {
+            deliveryId,
+            reachable: inChunk,
+            catalogHash: delivery.messageCatalogHashes?.[resolution.resolvedLocale || defaultLocale] || null,
+            bundledLocales: delivery.bundledLocales,
+        },
+        diagnostics,
+    };
+}
+/**
+ * Diff two locales' catalogs.
+ * @param {{
+ * baseLocale: string,
+ * targetLocale: string,
+ * messages: Array<{ messageId: string, variants: Record<string, { template: string, params?: any[] }> }>,
+ * }} input
+ */
+export function diffLocaleCatalogs(input) {
+    const base = input.baseLocale;
+    const target = input.targetLocale;
+    /** @type {any[]} */
+    const missingInTarget = [];
+    /** @type {any[]} */
+    const missingInBase = [];
+    /** @type {any[]} */
+    const changed = [];
+    /** @type {any[]} */
+    const paramMismatches = [];
+    const ids = new Set();
+    for (const m of input.messages || [])
+        ids.add(m.messageId);
+    for (const messageId of [...ids].sort()) {
+        const node = (input.messages || []).find((m) => m.messageId === messageId);
+        const bv = node?.variants?.[base];
+        const tv = node?.variants?.[target];
+        if (bv && !tv)
+            missingInTarget.push(messageId);
+        else if (!bv && tv)
+            missingInBase.push(messageId);
+        else if (bv && tv) {
+            if (bv.template !== tv.template) {
+                changed.push({ messageId, base: bv.template, target: tv.template });
+            }
+            const bp = JSON.stringify(bv.params || []);
+            const tp = JSON.stringify(tv.params || []);
+            if (bp !== tp) {
+                paramMismatches.push({ messageId, baseParams: bv.params || [], targetParams: tv.params || [] });
+            }
+        }
+    }
+    return {
+        schema: LOCALE_DIFF_SCHEMA,
+        status: 'ready',
+        baseLocale: base,
+        targetLocale: target,
+        missingInTarget,
+        missingInBase,
+        changed,
+        paramMismatches,
+        summary: {
+            missingInTarget: missingInTarget.length,
+            missingInBase: missingInBase.length,
+            changed: changed.length,
+            paramMismatches: paramMismatches.length,
+        },
+    };
+}
+/**
+ * Scan source for likely hardcoded UI text sinks (extract --check).
+ * Does not auto-generate MessageIds.
+ * @param {string} projectRoot
+ * @param {{ check?: boolean }} [opts]
+ */
+export function extractHardcodedText(projectRoot, opts = {}) {
+    /** @type {any[]} */
+    const findings = [];
+    /** @type {any[]} */
+    const diagnostics = [];
+    const srcRoot = path.join(projectRoot, 'src');
+    if (!fs.existsSync(srcRoot)) {
+        return {
+            schema: LOCALE_EXTRACT_SCHEMA,
+            status: 'ready',
+            findings: [],
+            diagnostics: [],
+        };
+    }
+    /** @type {string[]} */
+    const files = [];
+    const walk = (dir) => {
+        for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+            const p = path.join(dir, ent.name);
+            if (ent.isDirectory()) {
+                if (ent.name === 'node_modules' || ent.name === 'dist')
+                    continue;
+                walk(p);
+            }
+            else if (/\.(vmz|ts|tsx|js|jsx)$/.test(ent.name)) {
+                files.push(p);
+            }
+        }
+    };
+    walk(srcRoot);
+    // CJK or long quoted Latin UI-ish literals outside #locales imports.
+    const cjkRe = /['"`]([^'"`]*[\u4e00-\u9fff][^'"`]*)['"`]/g;
+    const uiLatinRe = /['"`]([A-Z][A-Za-z0-9 ,.!?]{8,})['"`]/g;
+    const dynamicIdRe = /(?<![A-Za-z0-9_$])(?:t|translate|i18n)\(\s*([^'")]+)\s*\)/g;
+    for (const fileAbs of files) {
+        const text = fs.readFileSync(fileAbs, 'utf8');
+        const rel = path.relative(projectRoot, fileAbs).replace(/\\/g, '/');
+        // Skip files that only re-export locales types.
+        if (rel.includes('locales-types'))
+            continue;
+        let m;
+        cjkRe.lastIndex = 0;
+        while ((m = cjkRe.exec(text))) {
+            const lit = m[1];
+            // Allow import paths / comments-ish short tokens
+            if (lit.includes('#locales/') || lit.includes('locales/'))
+                continue;
+            // Require a letter (Latin or CJK). Avoid `\W` without `u` — CJK is `\W` in ASCII mode.
+            if (!/\p{L}/u.test(lit))
+                continue;
+            findings.push({
+                path: rel,
+                kind: 'cjk_literal',
+                text: lit,
+                suggestion: 'Move UI copy into /locales catalog and import from #locales/*',
+            });
+            diagnostics.push({
+                code: DIAG_LOCALE_HARDCODED_TEXT,
+                severity: opts.check ? 'error' : 'warning',
+                message: `suspected hardcoded text ${JSON.stringify(lit)} in ${rel}`,
+                path: rel,
+            });
+        }
+        uiLatinRe.lastIndex = 0;
+        while ((m = uiLatinRe.exec(text))) {
+            const lit = m[1];
+            if (/^(http|https|application\/|text\/)/i.test(lit))
+                continue;
+            if (lit.includes('#locales/'))
+                continue;
+            findings.push({
+                path: rel,
+                kind: 'ui_literal',
+                text: lit,
+                suggestion: 'Prefer #locales/* MessageId over hardcoded UI English',
+            });
+            diagnostics.push({
+                code: DIAG_LOCALE_HARDCODED_TEXT,
+                severity: 'warning',
+                message: `suspected hardcoded UI string ${JSON.stringify(lit)} in ${rel}`,
+                path: rel,
+            });
+        }
+        dynamicIdRe.lastIndex = 0;
+        while ((m = dynamicIdRe.exec(text))) {
+            const arg = m[1].trim();
+            if (!/^['"`]/.test(arg)) {
+                diagnostics.push({
+                    code: DIAG_MESSAGE_DYNAMIC_ID_UNBOUNDED,
+                    severity: 'error',
+                    message: `dynamic message id ${arg} is unbounded; use typed #locales/* exports`,
+                    path: rel,
+                });
+            }
+        }
+    }
+    const hasErrors = diagnostics.some((d) => d.severity === 'error');
+    return {
+        schema: LOCALE_EXTRACT_SCHEMA,
+        status: hasErrors ? 'failed' : 'ready',
+        findings,
+        diagnostics,
+    };
+}
+/**
+ * Pseudo-localize a source locale for layout/overflow testing.
+ * Preserves ICU placeholders; marks provenance — never a production fallback.
+ * @param {{
+ * sourceLocale: string,
+ * messages: Array<{ messageId: string, variants: Record<string, { template: string }> }>,
+ * production?: boolean,
+ * }} input
+ */
+export function pseudoLocalizeCatalog(input) {
+    /** @type {any[]} */
+    const diagnostics = [];
+    if (input.production) {
+        diagnostics.push({
+            code: DIAG_LOCALE_PSEUDO_PRODUCTION_FORBIDDEN,
+            severity: 'error',
+            message: 'pseudo locale must not be used as production fallback',
+        });
+    }
+    /** @type {Record<string, string>} */
+    const catalog = {};
+    for (const m of input.messages || []) {
+        const src = m.variants?.[input.sourceLocale]?.template;
+        if (src == null)
+            continue;
+        // Expand length ~30% with accented padding while keeping {placeholders}.
+        const parts = String(src).split(/(\{[^}]+\})/g);
+        const out = parts
+            .map((p) => {
+            if (p.startsWith('{') && p.endsWith('}'))
+                return p;
+            const stretched = p.replace(/[A-Za-z]/g, (ch) => `${ch}\u0301`);
+            return stretched + (p.trim() ? '·' : '');
+        })
+            .join('');
+        catalog[m.messageId] = `[!! ${out} !!]`;
+    }
+    return {
+        schema: LOCALE_PSEUDO_SCHEMA,
+        status: diagnostics.length ? 'failed' : 'ready',
+        sourceLocale: input.sourceLocale,
+        pseudoLocale: `pseudo-${input.sourceLocale}`,
+        provenance: 'dev-test-only',
+        catalog,
+        diagnostics,
+    };
+}
+/**
+ * Cross-host conformance: same MessageId set + catalog hashes + formatter version.
+ * @param {{
+ * manifest: any,
+ * messages: any[],
+ * routeIds?: string[],
+ * }} input
+ */
+export function checkLocaleConformance(input) {
+    /** @type {any[]} */
+    const diagnostics = [];
+    const supported = (input.manifest?.locales || []).map((l) => l.id);
+    const defaultLocale = input.manifest?.defaultLocale;
+    const messages = input.messages || [];
+    const common = {
+        applicationId: 'app.locales-fixture',
+        planVersion: 'plan.v0',
+        supportedLocales: supported,
+        defaultLocale,
+        fallback: input.manifest?.fallback || {},
+        messages,
+        reachableMessageIds: messages.map((m) => m.messageId),
+        bundledLocales: [defaultLocale],
+    };
+    const web = buildLocaleDeliveryResolution({ ...common, host: 'web', deliveryId: 'delivery.web' });
+    const mini = buildLocaleDeliveryResolution({ ...common, host: 'mini', deliveryId: 'delivery.mini' });
+    const native = buildLocaleDeliveryResolution({
+        ...common,
+        host: 'native',
+        deliveryId: 'delivery.native',
+    });
+    diagnostics.push(...web.diagnostics, ...mini.diagnostics, ...native.diagnostics);
+    const inv = assertHostMessageInvariant([web, mini, native]);
+    if (!inv.ok) {
+        for (const d of inv.diagnostics) {
+            diagnostics.push({
+                code: DIAG_LOCALE_CONFORMANCE_DIVERGENCE,
+                severity: 'error',
+                message: d.message,
+            });
+        }
+    }
+    // RouteId surface: stable ids must not embed LocaleId.
+    for (const routeId of input.routeIds || []) {
+        if (supported.some((loc) => routeId.includes(loc))) {
+            diagnostics.push({
+                code: DIAG_LOCALE_CONFORMANCE_DIVERGENCE,
+                severity: 'error',
+                message: `RouteId ${routeId} must not embed LocaleId`,
+            });
+        }
+    }
+    const hasErrors = diagnostics.some((d) => d.severity === 'error');
+    return {
+        schema: LOCALE_CONFORMANCE_SCHEMA,
+        status: hasErrors ? 'failed' : 'ready',
+        hosts: ['web', 'mini', 'native'],
+        formatterDataVersion: FORMATTER_DATA_VERSION,
+        messageIds: messages.map((m) => m.messageId).sort(),
+        catalogHashes: web.messageCatalogHashes,
+        diagnostics,
+    };
+}

package/dist/log.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Unified CLI logging / diagnostics .
+ */
+export declare const log: {
+    /** @param {...unknown} args */
+    info(...args: any[]): void;
+    /** @param {...unknown} args */
+    warn(...args: any[]): void;
+    /** @param {...unknown} args */
+    error(...args: any[]): void;
+    /** @param {{ severity: string, path: string, message: string }} d */
+    diagnostic(d: any): void;
+    /**
+     * @param {Array<{ severity: string, path: string, message: string }>} diagnostics
+     * @param {{ denyWarnings?: boolean }} [opts]
+     * @returns {number} failing count (errors, and warnings if denyWarnings)
+     */
+    diagnostics(diagnostics: any, opts?: {}): number;
+};

package/dist/log.js

@@ -0,0 +1,42 @@
+// @ts-nocheck
+/**
+ * Unified CLI logging / diagnostics .
+ */
+/** @param {string} level */
+function stamp(level) {
+    return `vmz ${level}`;
+}
+export const log = {
+    /** @param {...unknown} args */
+    info(...args) {
+        console.error(stamp('info'), ...args);
+    },
+    /** @param {...unknown} args */
+    warn(...args) {
+        console.error(stamp('warn'), ...args);
+    },
+    /** @param {...unknown} args */
+    error(...args) {
+        console.error(stamp('error'), ...args);
+    },
+    /** @param {{ severity: string, path: string, message: string }} d */
+    diagnostic(d) {
+        console.error(`${d.severity}: ${d.path}: ${d.message}`);
+    },
+    /**
+     * @param {Array<{ severity: string, path: string, message: string }>} diagnostics
+     * @param {{ denyWarnings?: boolean }} [opts]
+     * @returns {number} failing count (errors, and warnings if denyWarnings)
+     */
+    diagnostics(diagnostics, opts = {}) {
+        let failing = 0;
+        for (const d of diagnostics ?? []) {
+            this.diagnostic(d);
+            if (d.severity === 'error')
+                failing += 1;
+            else if (opts.denyWarnings && d.severity === 'warning')
+                failing += 1;
+        }
+        return failing;
+    },
+};

package/dist/packages.d.ts

@@ -0,0 +1,26 @@
+/**
+ * npm / pnpm workspace package resolution helpers (session).
+ */
+/**
+ * @typedef {object} ResolvedPackage
+ * @property {string} name
+ * @property {string} root
+ * @property {boolean} [private]
+ * @property {boolean} hasSrc
+ * @property {string} [version]
+ */
+/**
+ * Resolve workspace packages under a project (package.json workspaces or pnpm-workspace.yaml).
+ * Does not invent VMZ semantics — only filesystem / npm layout facts for plugins.
+ *
+ * @param {string} project
+ * @returns {ResolvedPackage[]}
+ */
+export declare function resolveWorkspacePackages(project: any): any[];
+/**
+ * Resolve a package name to an absolute root (workspace first, then node_modules).
+ * @param {string} project
+ * @param {string} name
+ * @returns {string | null}
+ */
+export declare function resolvePackageRoot(project: any, name: any): any;

package/dist/packages.js

@@ -0,0 +1,146 @@
+// @ts-nocheck
+/**
+ * npm / pnpm workspace package resolution helpers (session).
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * @typedef {object} ResolvedPackage
+ * @property {string} name
+ * @property {string} root
+ * @property {boolean} [private]
+ * @property {boolean} hasSrc
+ * @property {string} [version]
+ */
+/**
+ * Resolve workspace packages under a project (package.json workspaces or pnpm-workspace.yaml).
+ * Does not invent VMZ semantics — only filesystem / npm layout facts for plugins.
+ *
+ * @param {string} project
+ * @returns {ResolvedPackage[]}
+ */
+export function resolveWorkspacePackages(project) {
+    const root = path.resolve(project);
+    const patterns = readWorkspacePatterns(root);
+    /** @type {Map<string, ResolvedPackage>} */
+    const out = new Map();
+    // Always include the project itself when it has package.json.
+    const self = readPkg(root);
+    if (self)
+        out.set(self.root, self);
+    for (const pattern of patterns) {
+        for (const dir of expandWorkspacePattern(root, pattern)) {
+            const pkg = readPkg(dir);
+            if (pkg)
+                out.set(pkg.root, pkg);
+        }
+    }
+    return [...out.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Resolve a package name to an absolute root (workspace first, then node_modules).
+ * @param {string} project
+ * @param {string} name
+ * @returns {string | null}
+ */
+export function resolvePackageRoot(project, name) {
+    const hit = resolveWorkspacePackages(project).find((p) => p.name === name);
+    if (hit)
+        return hit.root;
+    const nm = path.join(path.resolve(project), 'node_modules', ...name.split('/'));
+    if (existsSync(path.join(nm, 'package.json')))
+        return nm;
+    return null;
+}
+/**
+ * @param {string} root
+ * @returns {string[]}
+ */
+function readWorkspacePatterns(root) {
+    const patterns = [];
+    const pkgPath = path.join(root, 'package.json');
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+            const ws = pkg.workspaces;
+            if (Array.isArray(ws))
+                patterns.push(...ws);
+            else if (ws && Array.isArray(ws.packages))
+                patterns.push(...ws.packages);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    const pnpm = path.join(root, 'pnpm-workspace.yaml');
+    if (existsSync(pnpm)) {
+        try {
+            const text = readFileSync(pnpm, 'utf8');
+            for (const line of text.split(/\r?\n/)) {
+                const m = line.match(/^\s*-\s*['"]?([^'"]+)['"]?\s*$/);
+                if (m)
+                    patterns.push(m[1]);
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    return [...new Set(patterns)];
+}
+/**
+ * Minimal glob: supports `packages/*`, `examples/*`, exact dirs. No `**`.
+ * @param {string} root
+ * @param {string} pattern
+ */
+function expandWorkspacePattern(root, pattern) {
+    const cleaned = pattern.replace(/\\/g, '/').replace(/\/$/, '');
+    if (!cleaned.includes('*')) {
+        const dir = path.join(root, cleaned);
+        return existsSync(dir) ? [dir] : [];
+    }
+    const star = cleaned.indexOf('*');
+    const prefix = cleaned.slice(0, star).replace(/\/$/, '');
+    const suffix = cleaned.slice(star + 1); // e.g. "" or "/*" — we only support one *
+    if (suffix.includes('*'))
+        return [];
+    const base = path.join(root, prefix);
+    if (!existsSync(base))
+        return [];
+    /** @type {string[]} */
+    const dirs = [];
+    for (const name of readdirSync(base, { withFileTypes: true })) {
+        if (!name.isDirectory())
+            continue;
+        const dir = path.join(base, name.name);
+        if (suffix && !existsSync(path.join(dir, suffix.replace(/^\//, '')))) {
+            // suffix after * is path remainder like `/foo` — rare; skip strict check
+        }
+        dirs.push(dir);
+    }
+    return dirs;
+}
+/**
+ * @param {string} dir
+ * @returns {ResolvedPackage | null}
+ */
+function readPkg(dir) {
+    const pkgPath = path.join(dir, 'package.json');
+    if (!existsSync(pkgPath))
+        return null;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        if (!pkg.name)
+            return null;
+        return {
+            name: pkg.name,
+            root: dir,
+            private: Boolean(pkg.private),
+            hasSrc: existsSync(path.join(dir, 'src')),
+            version: typeof pkg.version === 'string' ? pkg.version : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/plugin-host.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Plugin protocol v1 helpers + typed config loading.
+ */
+import { contentHash, defineConfig, definePlugin } from '@vmz/plugin';
+export { contentHash, defineConfig, definePlugin };
+export declare const PLUGIN_PROTOCOL = "0.1.0";
+/**
+ * @param {string} full
+ * @returns {Promise<any>}
+ */
+export declare function importMaybeTs(full: any): Promise<any>;
+/**
+ * Load `vmz.config.*` from project root (+ optional root `vmz.plugin.*`).
+ * @param {string} project
+ * @returns {Promise<{ plugins: import('@vmz/plugin').VmzPlugin[], engines: import('@vmz/plugin').VmzEngines, path: string | null, pluginPath: string | null }>}
+ */
+export declare function loadVmzConfig(project: any): Promise<{
+    plugins: any[];
+    engines: {};
+    path: any;
+    pluginPath: any;
+}>;
+/**
+ * Collect + apply contribution batches for the given stages onto a Workspace.
+ * @param {import('../index.js').Workspace} workspace
+ * @param {import('@vmz/plugin').VmzPlugin[]} plugins
+ * @param {{ project: string, outDir: string, stages?: string[], engines?: import('@vmz/plugin').VmzEngines }} opts
+ */
+export declare function applyPlugins(workspace: any, plugins: any, opts: any): Promise<any[]>;