@vmz/vmz 0.1.14 → 0.1.16

package/dist/author-input.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Degrade author JSON5/JSON text to a plain object via Rust (not a semantic plan API).
+ * @param {string} source
+ * @returns {any}
+ */
+export declare function parseAuthorInput(source: any): any;
+/**
+ * @param {string} projectRoot
+ */
+export declare function loadLocalePlan(projectRoot: any): any;
+/**
+ * @param {string} projectRoot
+ */
+export declare function loadDocumentRoutePlan(projectRoot: any): any;
+/**
+ * Map Rust ReportedDiagnostic rows into host `{ code, severity, message, path }` rows.
+ * @param {Array<{ code?: string, severity?: string, message?: string, path?: string }>} rows
+ */
+export declare function mapPlanDiagnostics(rows: any): any;

package/dist/author-input.js

@@ -0,0 +1,52 @@
+// @ts-nocheck
+/**
+ * Author declaration input via Rust N-API (no JS JSON5 package).
+ *
+ * Locale/document policy: loadLocalePlan / loadDocumentRoutePlan.
+ * Catalogs / transitional tables: parseAuthorInput → Rust degrade → JSON.parse.
+ */
+import { requireNativeAddon } from './native-addon.js';
+/**
+ * Degrade author JSON5/JSON text to a plain object via Rust (not a semantic plan API).
+ * @param {string} source
+ * @returns {any}
+ */
+export function parseAuthorInput(source) {
+    const native = requireNativeAddon();
+    if (typeof native.authorJson5ToCanonicalJson !== 'function') {
+        throw new Error('native missing authorJson5ToCanonicalJson — run `pnpm napi:build`');
+    }
+    return JSON.parse(native.authorJson5ToCanonicalJson(String(source)));
+}
+/**
+ * @param {string} projectRoot
+ */
+export function loadLocalePlan(projectRoot) {
+    const native = requireNativeAddon();
+    if (typeof native.loadLocalePlan !== 'function') {
+        throw new Error('native missing loadLocalePlan — run `pnpm napi:build`');
+    }
+    return JSON.parse(native.loadLocalePlan(String(projectRoot)));
+}
+/**
+ * @param {string} projectRoot
+ */
+export function loadDocumentRoutePlan(projectRoot) {
+    const native = requireNativeAddon();
+    if (typeof native.loadDocumentRoutePlan !== 'function') {
+        throw new Error('native missing loadDocumentRoutePlan — run `pnpm napi:build`');
+    }
+    return JSON.parse(native.loadDocumentRoutePlan(String(projectRoot)));
+}
+/**
+ * Map Rust ReportedDiagnostic rows into host `{ code, severity, message, path }` rows.
+ * @param {Array<{ code?: string, severity?: string, message?: string, path?: string }>} rows
+ */
+export function mapPlanDiagnostics(rows) {
+    return (rows || []).map((d) => ({
+        code: d.code || 'vmz::unknown',
+        severity: d.severity === 'advice' ? 'warning' : d.severity || 'error',
+        message: d.message || '',
+        path: d.path || undefined,
+    }));
+}

package/dist/document-build.d.ts

@@ -8,7 +8,7 @@ export declare function buildDocuments(opts: any): Promise<{
         root: string;
         defaultLocale: any;
         locales: any[];
-        localeLabels: {};
+        localeLabels: any;
         collections: any[];
         mounts: any[];
         pages: {
@@ -66,7 +66,7 @@ export declare function buildDocuments(opts: any): Promise<{
         root: string;
         defaultLocale: any;
         locales: any[];
-        localeLabels: {};
+        localeLabels: any;
         collections: any[];
         mounts: any[];
         pages: {

package/dist/document-check.d.ts

@@ -1,5 +1,8 @@
 /**
  * Build DocumentManifest + run / --strict checks.
+ *
+ * Author documents config is parsed by Rust DocumentRoutePlan; TS only
+ * merges filesystem scan (pageKeys) and coverage diagnostics.
  */
 /**
  * Resolve project documents root.
@@ -7,14 +10,30 @@
  */
 export declare function resolveDocumentsRoot(projectRoot: any): string;
 /**
- * Parse documents.config.json or a JSON-compatible export-default .ts/.js.
+ * Load normalized DocumentRoutePlan from Rust (author JSON5/JSON/declaration).
+ * @param {string} projectRoot
+ */
+export declare function loadDocumentsRoutePlan(projectRoot: any): any;
+/**
+ * @deprecated Prefer loadDocumentsRoutePlan(projectRoot). Kept for call sites that
+ * only need the plan-shaped config fields.
  * @param {string} documentsRoot
- * @returns {{ config: Record<string, any> | null, diagnostics: any[], configPath: string | null }}
  */
 export declare function loadDocumentsConfig(documentsRoot: any): {
-    config: any;
-    diagnostics: any[];
+    config: {
+        defaultLocale: any;
+        locales: {
+            [k: string]: {
+                label: unknown;
+            };
+        };
+        collections: {
+            [k: string]: any;
+        };
+    };
+    diagnostics: any;
     configPath: string;
+    plan: any;
 };
 /**
  * @param {object} opts
@@ -27,7 +46,7 @@ export declare function checkDocuments(opts: any): {
     root: string;
     defaultLocale: any;
     locales: any[];
-    localeLabels: {};
+    localeLabels: any;
     collections: any[];
     mounts: any[];
     pages: {

package/dist/document-check.js

@@ -1,11 +1,14 @@
 // @ts-nocheck
 /**
  * Build DocumentManifest + run / --strict checks.
+ *
+ * Author documents config is parsed by Rust DocumentRoutePlan; TS only
+ * merges filesystem scan (pageKeys) and coverage diagnostics.
  */
-import fs from 'node:fs';
 import path from 'node:path';
-import { DIAG, DOCUMENT_MANIFEST_SCHEMA } from './document-schema.js';
+import { loadDocumentRoutePlan, mapPlanDiagnostics } from './author-input.js';
 import { scanDocumentsTree } from './document-scan.js';
+import { DIAG, DOCUMENT_MANIFEST_SCHEMA } from './document-schema.js';
 /**
  * Resolve project documents root.
  * @param {string} projectRoot
@@ -14,59 +17,36 @@ export function resolveDocumentsRoot(projectRoot) {
     return path.resolve(projectRoot, 'documents');
 }
 /**
- * Parse documents.config.json or a JSON-compatible export-default .ts/.js.
- * @param {string} documentsRoot
- * @returns {{ config: Record<string, any> | null, diagnostics: any[], configPath: string | null }}
+ * Load normalized DocumentRoutePlan from Rust (author JSON5/JSON/declaration).
+ * @param {string} projectRoot
  */
-export function loadDocumentsConfig(documentsRoot) {
-    /** @type {any[]} */
-    const diagnostics = [];
-    const candidates = ['documents.config.json', 'documents.config.ts', 'documents.config.js'];
-    for (const name of candidates) {
-        const p = path.join(documentsRoot, name);
-        if (!fs.existsSync(p))
-            continue;
-        try {
-            const raw = fs.readFileSync(p, 'utf8');
-            const config = parseConfigSource(raw, name);
-            return { config, diagnostics, configPath: p };
-        }
-        catch (e) {
-            diagnostics.push({
-                code: DIAG.CONFIG_INVALID,
-                severity: 'error',
-                message: `failed to parse ${name}: ${e instanceof Error ? e.message : String(e)}`,
-                path: p,
-            });
-            return { config: null, diagnostics, configPath: p };
-        }
-    }
-    return { config: null, diagnostics, configPath: null };
+export function loadDocumentsRoutePlan(projectRoot) {
+    return loadDocumentRoutePlan(projectRoot);
 }
 /**
- *: only declaration objects — no arbitrary hooks.
- * @param {string} raw
- * @param {string} filename
+ * @deprecated Prefer loadDocumentsRoutePlan(projectRoot). Kept for call sites that
+ * only need the plan-shaped config fields.
+ * @param {string} documentsRoot
  */
-function parseConfigSource(raw, filename) {
-    if (filename.endsWith('.json')) {
-        return JSON.parse(raw);
+export function loadDocumentsConfig(documentsRoot) {
+    const projectRoot = path.dirname(documentsRoot);
+    const plan = loadDocumentRoutePlan(projectRoot);
+    const diagnostics = mapPlanDiagnostics(plan.diagnostics);
+    const configPath = plan.sourcePath ? path.join(projectRoot, plan.sourcePath) : null;
+    const missing = diagnostics.some((d) => d.code === DIAG.CONFIG_MISSING);
+    if (missing) {
+        return { config: null, diagnostics, configPath, plan };
     }
-    // Strip line/block comments, then require `export default { ... }`
-    let s = raw.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
-    s = s.trim();
-    const m = s.match(/^export\s+default\s+([\s\S]*?);?\s*$/);
-    if (!m) {
-        throw new Error('expected `export default { ... }` (JSON-compatible declaration only)');
+    /** @type {Record<string, any>} */
+    const config = {
+        defaultLocale: plan.defaultLocale ?? undefined,
+        locales: Object.fromEntries(Object.entries(plan.localeLabels || {}).map(([id, label]) => [id, { label }])),
+        collections: Object.fromEntries((plan.collections || []).map((c) => [c.id, { source: c.sourceRoot, mount: c.routeBase }])),
+    };
+    if (plan.silentFallbackRequested) {
+        config.fallback = true;
     }
-    let body = m[1].trim();
-    // Quote bare keys: { defaultLocale: "x" } → { "defaultLocale": "x" }
-    body = body.replace(/([,{]\s*)([A-Za-z_][A-Za-z0-9_]*)\s*:/g, '$1"$2":');
-    // Single-quoted strings → JSON double-quoted
-    body = body.replace(/'([^'\\]*(?:\\.[^'\\]*)*)'/g, (_, inner) => JSON.stringify(inner.replace(/\\'/g, "'").replace(/\\"/g, '"').replace(/\\\\/g, '\\')));
-    // Trailing commas
-    body = body.replace(/,\s*([}\]])/g, '$1');
-    return JSON.parse(body);
+    return { config, diagnostics, configPath, plan };
 }
 /**
  * @param {object} opts
@@ -82,61 +62,53 @@ export function checkDocuments(opts) {
     const diagnostics = [];
     const scanned = scanDocumentsTree(documentsRoot);
     diagnostics.push(...scanned.diagnostics);
-    const { config, diagnostics: cfgDiags, configPath } = loadDocumentsConfig(documentsRoot);
-    diagnostics.push(...cfgDiags);
-    if (!config) {
-        diagnostics.push({
-            code: DIAG.CONFIG_MISSING,
-            severity: strict ? 'error' : 'warning',
-            message: 'documents.config.json|ts missing; strict mode requires defaultLocale + locales for strict coverage checks',
-            path: documentsRoot,
-        });
+    const plan = loadDocumentRoutePlan(projectRoot);
+    diagnostics.push(...mapPlanDiagnostics(plan.diagnostics));
+    const configMissing = (plan.diagnostics || []).some((d) => d.code === DIAG.CONFIG_MISSING);
+    const configPath = plan.sourcePath ? path.join(projectRoot, plan.sourcePath) : null;
+    if (configMissing && strict) {
+        // Plan already emitted warning; elevate message under --strict if needed.
+        if (!diagnostics.some((d) => d.code === DIAG.CONFIG_MISSING && d.severity === 'error')) {
+            diagnostics.push({
+                code: DIAG.CONFIG_MISSING,
+                severity: 'error',
+                message: 'documents.config.json|json5|ts|js missing; strict mode requires defaultLocale + locales for strict coverage checks',
+                path: documentsRoot,
+            });
+        }
     }
     /** @type {Record<string, string>} */
-    const localeLabels = {};
-    let defaultLocale = null;
+    const localeLabels = { ...(plan.localeLabels || {}) };
+    const defaultLocale = plan.defaultLocale || null;
     /** @type {import('./document-schema.js').DocumentCollection[]} */
     const collections = [];
     /** @type {import('./document-schema.js').DocumentMount[]} */
     const mounts = [];
-    if (config && typeof config === 'object') {
-        if (typeof config.defaultLocale === 'string') {
-            defaultLocale = config.defaultLocale;
-        }
-        if (config.locales && typeof config.locales === 'object') {
-            for (const [k, v] of Object.entries(config.locales)) {
-                localeLabels[k] = v && typeof v === 'object' && typeof v.label === 'string' ? v.label : k;
-            }
-        }
-        if (config.collections && typeof config.collections === 'object') {
-            for (const [id, c] of Object.entries(config.collections)) {
-                const sourceRoot = c && typeof c === 'object' && typeof c.source === 'string' ? c.source : '.';
-                const routeBase = c && typeof c === 'object' && typeof c.mount === 'string' ? c.mount : '/docs';
-                const pageKeys = [
-                    ...new Set(scanned.pages
-                        .filter((p) => {
-                        if (sourceRoot === '.' || sourceRoot === './')
-                            return true;
-                        const prefix = sourceRoot.replace(/^\.\//, '').replace(/\/$/, '');
-                        return p.identity.pageKey === prefix || p.identity.pageKey.startsWith(prefix + '/');
-                    })
-                        .map((p) => p.identity.pageKey)),
-                ].sort();
-                collections.push({ id, sourceRoot, pageKeys });
-                mounts.push({
-                    collectionId: id,
-                    routeBase,
-                    mode: routeBase === '/' ? 'standalone' : 'integrated',
-                });
-            }
-        }
+    for (const c of plan.collections || []) {
+        const sourceRoot = c.sourceRoot || '.';
+        const routeBase = c.routeBase || '/docs';
+        const pageKeys = [
+            ...new Set(scanned.pages
+                .filter((p) => {
+                if (sourceRoot === '.' || sourceRoot === './')
+                    return true;
+                const prefix = sourceRoot.replace(/^\.\//, '').replace(/\/$/, '');
+                return p.identity.pageKey === prefix || p.identity.pageKey.startsWith(`${prefix}/`);
+            })
+                .map((p) => p.identity.pageKey)),
+        ].sort();
+        collections.push({ id: c.id, sourceRoot, pageKeys });
+        mounts.push({
+            collectionId: c.id,
+            routeBase,
+            mode: routeBase === '/' ? 'standalone' : 'integrated',
+        });
     }
     if (collections.length === 0) {
         const pageKeys = [...new Set(scanned.pages.map((p) => p.identity.pageKey))].sort();
         collections.push({ id: 'default', sourceRoot: '.', pageKeys });
         mounts.push({ collectionId: 'default', routeBase: '/docs', mode: 'integrated' });
     }
-    // Config locales vs disk
     const diskLocales = new Set(scanned.locales);
     const configLocales = Object.keys(localeLabels);
     if (defaultLocale) {
@@ -175,15 +147,6 @@ export function checkDocuments(opts) {
             });
         }
     }
-    // no silent whole-page fallback by default
-    if (config && config.fallback === true) {
-        diagnostics.push({
-            code: DIAG.FALLBACK_SILENT,
-            severity: 'error',
-            message: 'silent whole-page fallback is forbidden; allow only explicit nav/metadata or per-page fallback',
-            path: configPath || documentsRoot,
-        });
-    }
     // Coverage: default locale PageKeys are baseline; other locales missing/orphan under --strict
     if (defaultLocale && diskLocales.has(defaultLocale)) {
         const byLocale = new Map();

package/dist/document-routing-config.d.ts

@@ -1,11 +1,15 @@
 /**
- * Project locale routing config for document mount (locales/locales.json5).
+ * Project locale routing — consume Rust LocalePlan (no author JSON5 in TS).
  */
 /**
  * @param {string} projectRoot
- * @returns {{ strategy?: string, defaultLocale?: string } | null}
+ * @returns {{ strategy?: string, defaultPrefix?: string, defaultLocale?: string } | null}
  */
-export declare function loadLocalesRouting(projectRoot: any): any;
+export declare function loadLocalesRouting(projectRoot: any): {
+    strategy: any;
+    defaultPrefix: any;
+    defaultLocale: any;
+};
 /**
  * @param {string} routeBase
  * @param {string} pageKey

package/dist/document-routing-config.js

@@ -1,32 +1,23 @@
 // @ts-nocheck
 /**
- * Project locale routing config for document mount (locales/locales.json5).
+ * Project locale routing — consume Rust LocalePlan (no author JSON5 in TS).
  */
-import fs from 'node:fs';
-import path from 'node:path';
+import { loadLocalePlan } from './author-input.js';
 /**
  * @param {string} projectRoot
- * @returns {{ strategy?: string, defaultLocale?: string } | null}
+ * @returns {{ strategy?: string, defaultPrefix?: string, defaultLocale?: string } | null}
  */
 export function loadLocalesRouting(projectRoot) {
-    const p = path.join(projectRoot, 'locales', 'locales.json5');
-    if (!fs.existsSync(p))
-        return null;
-    try {
-        const raw = fs.readFileSync(p, 'utf8');
-        let s = raw.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
-        const m = s.match(/routing\s*:\s*\{([\s\S]*?)\}/);
-        if (!m)
-            return null;
-        let block = `{${m[1]}}`;
-        block = block.replace(/([,{]\s*)([A-Za-z_][A-Za-z0-9_]*)\s*:/g, '$1"$2":');
-        block = block.replace(/'([^'\\]*(?:\\.[^'\\]*)*)'/g, (_, inner) => JSON.stringify(inner));
-        block = block.replace(/,\s*([}\]])/g, '$1');
-        return JSON.parse(block);
-    }
-    catch {
+    const plan = loadLocalePlan(projectRoot);
+    if (!plan || plan.diagnostics?.some((d) => d.code === 'vmz::locale::manifest_missing')) {
         return null;
     }
+    const routing = plan.routing || {};
+    return {
+        strategy: routing.strategy || 'prefix',
+        defaultPrefix: routing.defaultPrefix || 'include',
+        defaultLocale: plan.defaultLocale || undefined,
+    };
 }
 /**
  * @param {string} routeBase
@@ -36,5 +27,5 @@ export function docsRouteNone(routeBase, pageKey) {
     const base = String(routeBase || '/').replace(/\/$/, '') || '';
     const key = pageKey === 'index' ? '' : pageKey.replace(/\\/g, '/');
     const parts = [base.replace(/^\//, ''), key].filter((p) => p !== '');
-    return '/' + (parts.length ? parts.join('/') : '');
+    return `/${parts.length ? parts.join('/') : ''}`;
 }

package/dist/document-schema.js

@@ -48,7 +48,14 @@ export const DOCUMENT_SEARCH_SCHEMA = 'vmz.document.search.v0';
 /** Island-only resume plan for search/playground — not a Doc IR. */
 export const DOCUMENT_ISLANDS_SCHEMA = 'vmz.document.islands.v0';
 /** Top-level non-locale reserved names under /documents */
-export const DOCUMENT_RESERVED_TOP = new Set(['package.json', 'documents.config.ts', 'documents.config.json', 'documents.config.js', 'public']);
+export const DOCUMENT_RESERVED_TOP = new Set([
+    'package.json',
+    'documents.config.ts',
+    'documents.config.json',
+    'documents.config.json5',
+    'documents.config.js',
+    'public',
+]);
 /** Known locale aliases → canonical key (lowercase, hyphen). */
 export const LOCALE_ALIASES = {
     'zh-cn': 'zh-hans',

package/dist/locale-check.js

@@ -6,10 +6,10 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import JSON5 from 'json5';
+import { loadLocalePlan, mapPlanDiagnostics, parseAuthorInput } from './author-input.js';
+import { DIAG_CATALOG_CONFLICT, DIAG_CATALOG_PARSE, DIAG_DIR_MISSING, DIAG_DIR_ORPHAN, DIAG_ID_INVALID, DIAG_LAYOUT_ILLEGAL, DIAG_MANIFEST_MISSING, DIAG_MESSAGE_ARRAY_FORBIDDEN, DIAG_MESSAGE_HTML_FORBIDDEN, DIAG_MESSAGE_MISSING_DEFAULT, DIAG_MESSAGE_MISSING_VARIANT, DIAG_MESSAGE_PARAMETER_MISMATCH, DIAG_MESSAGE_SYNTAX_INVALID, DIAG_MESSAGE_UNUSED, LOCALE_CHECK_SCHEMA, LOCALE_ID_RE, LOCALE_MANIFEST_SCHEMA, LOCALE_RESERVED_TOP, LOCALE_TYPED_MODULE_SCHEMA, LOCALE_VIRTUAL_MODULE_PREFIX, MESSAGE_CATALOG_SCHEMA, MESSAGE_NODE_SCHEMA, } from './locale-schema.js';
 import { requireNativeAddon } from './native-addon.js';
 import { writePrettyJsonFile } from './pretty-json.js';
-import { DIAG_CATALOG_CONFLICT, DIAG_CATALOG_PARSE, DIAG_DEFAULT_MISSING, DIAG_DIR_MISSING, DIAG_DIR_ORPHAN, DIAG_FALLBACK_CYCLE, DIAG_FALLBACK_UNKNOWN, DIAG_ID_COLLISION, DIAG_ID_INVALID, DIAG_LAYOUT_ILLEGAL, DIAG_MANIFEST_MISSING, DIAG_MESSAGE_ARRAY_FORBIDDEN, DIAG_MESSAGE_HTML_FORBIDDEN, DIAG_MESSAGE_MISSING_DEFAULT, DIAG_MESSAGE_PARAMETER_MISMATCH, DIAG_MESSAGE_SYNTAX_INVALID, DIAG_MESSAGE_UNUSED, LOCALE_CHECK_SCHEMA, LOCALE_ID_RE, LOCALE_MANIFEST_SCHEMA, LOCALE_RESERVED_TOP, LOCALE_TYPED_MODULE_SCHEMA, LOCALE_VIRTUAL_MODULE_PREFIX, MESSAGE_CATALOG_SCHEMA, MESSAGE_NODE_SCHEMA, } from './locale-schema.js';
 /**
  * @param {string} literal
  */
@@ -248,124 +248,57 @@ export function checkLocales(opts) {
     const localesRoot = path.join(projectRoot, 'locales');
     /** @type {Array<{ code: string, severity: string, message: string, path?: string }>} */
     const diagnostics = [];
-    const manifestPathJson5 = path.join(localesRoot, 'locales.json5');
-    const manifestPathJson = path.join(localesRoot, 'locales.json');
-    const manifestPath = fs.existsSync(manifestPathJson5) ? manifestPathJson5 : fs.existsSync(manifestPathJson) ? manifestPathJson : null;
-    if (!fs.existsSync(localesRoot) || !manifestPath) {
-        // Discipline nudge: i18n is first-class — missing policy is never silent.
-        // Soft for now (warning); production profiles may elevate to error later.
-        diagnostics.push({
-            code: DIAG_MANIFEST_MISSING,
-            severity: 'warning',
-            message: 'locales/locales.json5 missing — declare LocaleId policy under /locales (native i18n, not an afterthought)',
-            path: 'locales/locales.json5',
-        });
-        return emptyReport(projectRoot, diagnostics);
-    }
-    /** @type {any} */
-    let rawManifest = null;
-    try {
-        rawManifest = JSON5.parse(fs.readFileSync(manifestPath, 'utf8'));
-    }
-    catch (e) {
-        diagnostics.push({
-            code: DIAG_CATALOG_PARSE,
-            severity: 'error',
-            message: `locales.json5 parse failed: ${e.message || e}`,
-            path: path.relative(projectRoot, manifestPath).replace(/\\/g, '/'),
-        });
+    const plan = loadLocalePlan(projectRoot);
+    diagnostics.push(...mapPlanDiagnostics(plan.diagnostics));
+    const missingManifest = (plan.diagnostics || []).some((d) => d.code === DIAG_MANIFEST_MISSING);
+    if (missingManifest || !plan.locales?.length) {
         return emptyReport(projectRoot, diagnostics);
     }
-    const localeEntries = Array.isArray(rawManifest.locales) ? rawManifest.locales : [];
+    const localeEntries = plan.locales || [];
     /** @type {string[]} */
-    const orderedIds = [];
+    const orderedIds = localeEntries.map((e) => e.id);
     /** @type {Set<string>} */
-    const seen = new Set();
-    for (const entry of localeEntries) {
-        const id = String(entry?.id || '');
-        const v = validateLocaleId(id);
-        if (!v.ok) {
-            diagnostics.push({
-                code: DIAG_ID_INVALID,
-                severity: 'error',
-                message: v.message,
-                path: path.relative(projectRoot, manifestPath).replace(/\\/g, '/'),
-            });
-            continue;
-        }
-        if (seen.has(id)) {
-            diagnostics.push({
-                code: DIAG_ID_COLLISION,
-                severity: 'error',
-                message: `duplicate LocaleId ${id} in locales[]`,
-                path: path.relative(projectRoot, manifestPath).replace(/\\/g, '/'),
-            });
-            continue;
-        }
-        seen.add(id);
-        orderedIds.push(id);
-    }
-    const defaultLocale = String(rawManifest.defaultLocale || '');
-    if (!defaultLocale || !seen.has(defaultLocale)) {
-        diagnostics.push({
-            code: DIAG_DEFAULT_MISSING,
-            severity: 'error',
-            message: `defaultLocale ${JSON.stringify(defaultLocale)} missing from locales[]`,
-            path: path.relative(projectRoot, manifestPath).replace(/\\/g, '/'),
-        });
-    }
-    const fallback = rawManifest.fallback && typeof rawManifest.fallback === 'object' ? rawManifest.fallback : {};
-    const fb = findFallbackCycles(fallback, seen);
-    for (const u of fb.unknown) {
-        diagnostics.push({
-            code: DIAG_FALLBACK_UNKNOWN,
-            severity: 'error',
-            message: `fallback references unknown LocaleId: ${u}`,
-            path: path.relative(projectRoot, manifestPath).replace(/\\/g, '/'),
-        });
-    }
-    for (const c of fb.cycles) {
-        diagnostics.push({
-            code: DIAG_FALLBACK_CYCLE,
-            severity: 'error',
-            message: `fallback cycle: ${c}`,
-            path: path.relative(projectRoot, manifestPath).replace(/\\/g, '/'),
-        });
-    }
+    const seen = new Set(orderedIds);
+    const defaultLocale = String(plan.defaultLocale || '');
+    const fallback = plan.fallback && typeof plan.fallback === 'object' ? plan.fallback : {};
+    const missingPolicy = plan.missing || 'error';
+    const routing = plan.routing || { strategy: 'prefix', defaultPrefix: 'include' };
     /** @type {string[]} */
     const diskLocales = [];
-    for (const ent of fs.readdirSync(localesRoot, { withFileTypes: true })) {
-        if (LOCALE_RESERVED_TOP.has(ent.name))
-            continue;
-        if (ent.isFile()) {
-            diagnostics.push({
-                code: DIAG_LAYOUT_ILLEGAL,
-                severity: 'error',
-                message: `illegal top-level file under /locales: ${ent.name} (only locales.json5 + LocaleId dirs)`,
-                path: `locales/${ent.name}`,
-            });
-            continue;
-        }
-        if (!ent.isDirectory())
-            continue;
-        const v = validateLocaleId(ent.name);
-        if (!v.ok) {
-            diagnostics.push({
-                code: DIAG_ID_INVALID,
-                severity: 'error',
-                message: `directory ${ent.name}: ${v.message}`,
-                path: `locales/${ent.name}`,
-            });
-            continue;
-        }
-        diskLocales.push(ent.name);
-        if (!seen.has(ent.name)) {
-            diagnostics.push({
-                code: DIAG_DIR_ORPHAN,
-                severity: 'error',
-                message: `locale directory ${ent.name} not listed in locales.json5 locales[]`,
-                path: `locales/${ent.name}`,
-            });
+    if (fs.existsSync(localesRoot)) {
+        for (const ent of fs.readdirSync(localesRoot, { withFileTypes: true })) {
+            if (LOCALE_RESERVED_TOP.has(ent.name))
+                continue;
+            if (ent.isFile()) {
+                diagnostics.push({
+                    code: DIAG_LAYOUT_ILLEGAL,
+                    severity: 'error',
+                    message: `illegal top-level file under /locales: ${ent.name} (only locales.json5 + LocaleId dirs)`,
+                    path: `locales/${ent.name}`,
+                });
+                continue;
+            }
+            if (!ent.isDirectory())
+                continue;
+            const v = validateLocaleId(ent.name);
+            if (!v.ok) {
+                diagnostics.push({
+                    code: DIAG_ID_INVALID,
+                    severity: 'error',
+                    message: `directory ${ent.name}: ${v.message}`,
+                    path: `locales/${ent.name}`,
+                });
+                continue;
+            }
+            diskLocales.push(ent.name);
+            if (!seen.has(ent.name)) {
+                diagnostics.push({
+                    code: DIAG_DIR_ORPHAN,
+                    severity: 'error',
+                    message: `locale directory ${ent.name} not listed in locales.json5 locales[]`,
+                    path: `locales/${ent.name}`,
+                });
+            }
         }
     }
     for (const id of orderedIds) {
@@ -404,7 +337,7 @@ export function checkLocales(opts) {
                     });
                     return;
                 }
-                parsed = JSON5.parse(text);
+                parsed = parseAuthorInput(text);
             }
             catch (e) {
                 diagnostics.push({
@@ -448,7 +381,6 @@ export function checkLocales(opts) {
             }
         });
     }
-    // Default locale must define every MessageId; param contracts must match across variants.
     for (const node of messages.values()) {
         if (defaultLocale && !node.variants[defaultLocale]) {
             diagnostics.push({
@@ -477,7 +409,7 @@ export function checkLocales(opts) {
                 if (!node.variants[loc] && loc !== defaultLocale) {
                     const edges = fallback[loc] || [];
                     const canFallback = edges.some((e) => node.variants[e]);
-                    if (!canFallback && rawManifest.missing !== 'warn') {
+                    if (!canFallback && missingPolicy !== 'warn') {
                         diagnostics.push({
                             code: DIAG_MESSAGE_MISSING_VARIANT,
                             severity: 'error',
@@ -488,7 +420,6 @@ export function checkLocales(opts) {
             }
         }
     }
-    // scan source for #locales/* imports / message references.
     const used = scanLocaleUsages(projectRoot);
     /** @type {any[]} */
     const typedModules = [];
@@ -559,12 +490,12 @@ export function checkLocales(opts) {
         localesRoot: path.relative(projectRoot, localesRoot).replace(/\\/g, '/') || 'locales',
         manifest: {
             schema: LOCALE_MANIFEST_SCHEMA,
-            schemaVersion: rawManifest.schemaVersion ?? 1,
+            schemaVersion: 1,
             defaultLocale,
             locales: localeEntries,
             fallback,
-            routing: rawManifest.routing || { strategy: 'prefix', defaultPrefix: 'include' },
-            missing: rawManifest.missing || 'error',
+            routing,
+            missing: missingPolicy,
         },
         catalogIds: catalogIds.sort(),
         messageCatalog: {
@@ -757,7 +688,7 @@ function rewriteLocaleImportsInDist(distDir) {
     const files = [];
     walkDistJs(distDir, (file) => files.push(file));
     for (const file of files) {
-        let text = fs.readFileSync(file, 'utf8');
+        const text = fs.readFileSync(file, 'utf8');
         if (!text.includes('#locales/'))
             continue;
         const fromDir = path.dirname(file);

package/dist/locale-cmd.js

@@ -4,7 +4,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import JSON5 from 'json5';
+import { parseAuthorInput } from './author-input.js';
 import { parseArgs } from './cli.js';
 import { checkLocales, emitLocaleTypedModules, localeHasErrors, planLocaleRename } from './locale-check.js';
 import { checkLocaleDelivery } from './locale-delivery.js';
@@ -192,7 +192,7 @@ function loadRoutesFixture(projectRoot) {
     const candidates = [path.join(projectRoot, 'locale-routes.json5'), path.join(projectRoot, 'locale-routes.json')];
     for (const p of candidates) {
         if (fs.existsSync(p)) {
-            return JSON5.parse(fs.readFileSync(p, 'utf8'));
+            return parseAuthorInput(fs.readFileSync(p, 'utf8'));
         }
     }
     return {
@@ -383,7 +383,7 @@ function cmdLocaleConformance(args) {
     const routesPath = path.join(projectRoot, 'locale-routes.json5');
     if (fs.existsSync(routesPath)) {
         try {
-            const routesFile = JSON5.parse(fs.readFileSync(routesPath, 'utf8'));
+            const routesFile = parseAuthorInput(fs.readFileSync(routesPath, 'utf8'));
             routeIds = (routesFile.routes || []).map((r) => r.routeId);
         }
         catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vmz/vmz",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "type": "module",
   "description": "VMZ Node toolchain — N-API workspace session + CLI (publish name @vmz/vmz)",
   "license": "MIT",
@@ -48,15 +48,14 @@
     }
   },
   "dependencies": {
-    "@vmz/core": "0.1.14",
-    "@vmz/plugin": "0.1.14",
-    "@vmz/protocol": "0.1.14",
-    "jiti": "^2.6.1",
-    "json5": "^2.2.3"
+    "@vmz/core": "0.1.16",
+    "@vmz/plugin": "0.1.16",
+    "@vmz/protocol": "0.1.16",
+    "jiti": "^2.6.1"
   },
   "peerDependencies": {
-    "@vmz/plugin-markdown-it": "0.1.14",
-    "@vmz/test": "0.1.14",
+    "@vmz/plugin-markdown-it": "0.1.16",
+    "@vmz/test": "0.1.16",
     "typescript": "^5.8.3"
   },
   "peerDependenciesMeta": {
@@ -90,12 +89,12 @@
     "cli"
   ],
   "optionalDependencies": {
-    "@vmz/vmz-win32-x64": "0.1.14",
-    "@vmz/vmz-win32-arm64": "0.1.14",
-    "@vmz/vmz-darwin-x64": "0.1.14",
-    "@vmz/vmz-darwin-arm64": "0.1.14",
-    "@vmz/vmz-linux-x64": "0.1.14",
-    "@vmz/vmz-linux-arm64": "0.1.14"
+    "@vmz/vmz-win32-x64": "0.1.16",
+    "@vmz/vmz-win32-arm64": "0.1.16",
+    "@vmz/vmz-darwin-x64": "0.1.16",
+    "@vmz/vmz-darwin-arm64": "0.1.16",
+    "@vmz/vmz-linux-x64": "0.1.16",
+    "@vmz/vmz-linux-arm64": "0.1.16"
   },
   "publishConfig": {
     "access": "public"