@vmz/vmz 0.0.1 → 0.0.2

package/dist/document-build.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @param {{ projectRoot: string, outDir?: string, strict?: boolean, engines?: { markdown?: string } }} opts
+ */
+export declare function buildDocuments(opts: any): Promise<{
+    ok: boolean;
+    manifest: {
+        schema: string;
+        root: string;
+        defaultLocale: any;
+        locales: any[];
+        localeLabels: {};
+        collections: any[];
+        mounts: any[];
+        pages: {
+            identity: any;
+            sourcePath: any;
+            route: any;
+            anchors: any[];
+        }[];
+        diagnostics: any[];
+    };
+    outDir: string;
+    pages: any[];
+    search?: undefined;
+    islands?: undefined;
+} | {
+    ok: boolean;
+    manifest: {
+        schema: string;
+        evidence: {
+            schema: string;
+            fences: any[];
+            apiRefs: any[];
+            testSelections: any[];
+            status: string;
+        };
+        search: {
+            schema: string;
+            status: string;
+            version: any;
+            records: any[];
+        };
+        islands: {
+            schema: string;
+            hydrate: string;
+            fullPageHydrate: boolean;
+            islands: {
+                name: string;
+                kind: string;
+                resume: string;
+                index: any;
+            }[];
+            status: string;
+        };
+        build: {
+            engine: any;
+            outDir: string;
+            designs: string;
+            designsCss: any;
+            pages: any[];
+            evidence: string;
+            search: string;
+            islands: string;
+        };
+        root: string;
+        defaultLocale: any;
+        locales: any[];
+        localeLabels: {};
+        collections: any[];
+        mounts: any[];
+        pages: {
+            identity: any;
+            sourcePath: any;
+            route: any;
+            anchors: any[];
+        }[];
+        diagnostics: any[];
+    };
+    outDir: string;
+    pages: any[];
+    search: {
+        schema: string;
+        status: string;
+        version: any;
+        records: any[];
+    };
+    islands: {
+        schema: string;
+        hydrate: string;
+        fullPageHydrate: boolean;
+        islands: {
+            name: string;
+            kind: string;
+            resume: string;
+            index: any;
+        }[];
+        status: string;
+    };
+}>;

package/dist/document-build.js

@@ -0,0 +1,274 @@
+// @ts-nocheck
+/**
+ * Document D1 Static + D3 Interactive artifacts.
+ * Design: 规划设计/vmz/19 §5–6 · D1/D3
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { checkDocuments, manifestHasErrors } from './document-check.js';
+import { resolveDocumentDesignsCss } from './document-designs.js';
+import { enrichDocumentContent, pageHtmlRel } from './document-enrich.js';
+import { enrichDocumentEvidence } from './document-evidence.js';
+import { artifactHrefFromHtml, buildDocumentIslands, buildDocumentSearch, collectFenceBodies, renderIslandShellsHtml, } from './document-interactive.js';
+import { resolveMarkdownEngine } from './document-markdown.js';
+import { DOCUMENT_VIEW_SCHEMA } from './document-schema.js';
+import { createWorkspace } from './index.js';
+/**
+ * @param {{ projectRoot: string, outDir?: string, strict?: boolean, engines?: { markdown?: string } }} opts
+ */
+export async function buildDocuments(opts) {
+    const projectRoot = path.resolve(opts.projectRoot);
+    const outDir = path.resolve(opts.outDir || path.join(projectRoot, 'dist', 'documents'));
+    const strict = Boolean(opts.strict);
+    const manifest = checkDocuments({ projectRoot, strict });
+    const engine = await resolveMarkdownEngine({ engines: opts.engines, projectRoot });
+    const enriched = enrichDocumentContent(manifest, {
+        analyzeMarkdown: engine.analyzeMarkdown,
+        projectRoot,
+    });
+    manifest.diagnostics = enriched.diagnostics;
+    const evidence = await enrichDocumentEvidence(manifest, {
+        analyzeMarkdown: engine.analyzeMarkdown,
+        projectRoot,
+        createWorkspace,
+    });
+    manifest.diagnostics = evidence.diagnostics;
+    manifest.evidence = evidence.evidence;
+    if (manifestHasErrors(manifest)) {
+        return { ok: false, manifest, outDir, pages: [] };
+    }
+    /** @type {Map<string, any>} */
+    const analyzedByPageId = new Map();
+    for (const page of manifest.pages) {
+        const abs = path.isAbsolute(page.sourcePath) ? page.sourcePath : path.join(manifest.root, page.sourcePath);
+        const source = fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : '';
+        const id = `${page.identity.locale}:${page.identity.pageKey}`;
+        analyzedByPageId.set(id, engine.analyzeMarkdown(source));
+    }
+    const fenceBodies = collectFenceBodies(analyzedByPageId, manifest.pages);
+    const search = buildDocumentSearch({
+        manifest,
+        enriched,
+        evidence: evidence.evidence,
+        version: null,
+    });
+    const islands = buildDocumentIslands({
+        evidence: evidence.evidence,
+        searchHref: 'document.search.json',
+        fenceBodies,
+    });
+    manifest.search = search;
+    manifest.islands = islands;
+    const hostChrome = resolveHostSiteChrome(projectRoot);
+    const useHostShell = Boolean(hostChrome) && (manifest.mounts || []).some((m) => m.mode === 'integrated');
+    fs.mkdirSync(outDir, { recursive: true });
+    const designs = resolveDocumentDesignsCss(projectRoot);
+    /** @type {string | null} */
+    let designsHref = null;
+    if (designs.css && designs.href) {
+        const cssPath = path.join(outDir, designs.href);
+        fs.mkdirSync(path.dirname(cssPath), { recursive: true });
+        fs.writeFileSync(cssPath, designs.css, 'utf8');
+        designsHref = designs.href;
+    }
+    const viewsDir = path.join(outDir, 'views');
+    fs.mkdirSync(viewsDir, { recursive: true });
+    /** @type {Array<{ route: string, htmlPath: string, viewPath: string }>} */
+    const written = [];
+    for (const page of manifest.pages) {
+        const id = `${page.identity.locale}:${page.identity.pageKey}`;
+        const info = enriched.byId.get(id);
+        if (!info)
+            continue;
+        const nav = enriched.navByLocale[page.identity.locale] || [];
+        const htmlRel = pageHtmlRel(enriched.routeBase, page.identity.locale, page.identity.pageKey);
+        const htmlAbs = path.join(outDir, htmlRel);
+        fs.mkdirSync(path.dirname(htmlAbs), { recursive: true });
+        const searchIndexHref = artifactHrefFromHtml(htmlRel, 'document.search.json');
+        const shells = renderIslandShellsHtml({
+            islands,
+            searchIndexHref,
+            pageKey: page.identity.pageKey,
+            locale: page.identity.locale,
+        });
+        const view = {
+            schema: DOCUMENT_VIEW_SCHEMA,
+            pageKey: page.identity.pageKey,
+            locale: page.identity.locale,
+            route: info.route,
+            title: info.title,
+            headings: info.headings,
+            nav,
+            bodyKind: 'html',
+            html: info.html,
+            designsCss: designsHref,
+            noJsReadable: true,
+            hydrate: 'island-only',
+            hostShell: useHostShell,
+            islands: ['DocumentSearch'].concat((islands.islands || [])
+                .filter((isl) => isl.kind === 'playground' &&
+                isl.fence?.locale === page.identity.locale &&
+                isl.fence?.pageKey === page.identity.pageKey)
+                .map((isl) => isl.name)),
+        };
+        const viewRel = path.posix.join('views', page.identity.locale, `${page.identity.pageKey === 'index' ? 'index' : page.identity.pageKey}.view.json`);
+        const viewAbs = path.join(outDir, viewRel);
+        fs.mkdirSync(path.dirname(viewAbs), { recursive: true });
+        fs.writeFileSync(viewAbs, JSON.stringify(view, null, 2) + '\n', 'utf8');
+        const html = renderStaticHtml({
+            title: info.title,
+            locale: page.identity.locale,
+            route: info.route,
+            nav,
+            bodyHtml: info.html,
+            headings: info.headings,
+            designsHref,
+            htmlRel,
+            searchShellHtml: shells.searchHtml,
+            playgroundShellHtml: shells.playgroundHtml,
+            hostChrome: useHostShell ? hostChrome : null,
+        });
+        fs.writeFileSync(htmlAbs, html, 'utf8');
+        written.push({ route: info.route, htmlPath: htmlRel, viewPath: viewRel });
+    }
+    const manifestOut = {
+        ...manifest,
+        schema: manifest.schema,
+        evidence: evidence.evidence,
+        search,
+        islands,
+        build: {
+            engine: engine.engine,
+            outDir: path.relative(projectRoot, outDir).replace(/\\/g, '/') || '.',
+            designs: designs.source,
+            designsCss: designsHref,
+            pages: written,
+            evidence: 'document.evidence.json',
+            search: 'document.search.json',
+            islands: 'document.islands.json',
+        },
+    };
+    fs.writeFileSync(path.join(outDir, 'document.manifest.json'), JSON.stringify(manifestOut, null, 2) + '\n', 'utf8');
+    fs.writeFileSync(path.join(outDir, 'document.evidence.json'), JSON.stringify(evidence.evidence, null, 2) + '\n', 'utf8');
+    fs.writeFileSync(path.join(outDir, 'document.search.json'), JSON.stringify(search, null, 2) + '\n', 'utf8');
+    fs.writeFileSync(path.join(outDir, 'document.islands.json'), JSON.stringify(islands, null, 2) + '\n', 'utf8');
+    return { ok: true, manifest: manifestOut, outDir, pages: written, search, islands };
+}
+/**
+ * No-JS readable static HTML: nav + main landmarks, Island shells without scripts.
+ * Integrated mounts reuse host SiteHeader/SiteFooter templates when present.
+ */
+function renderStaticHtml({ title, locale, route, nav, bodyHtml, headings, designsHref, htmlRel, searchShellHtml = '', playgroundShellHtml = '', hostChrome = null, }) {
+    const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+    const depth = htmlRel.split('/').length - 1;
+    const prefix = depth > 0 ? '../'.repeat(depth) : './';
+    /** @type {string[]} */
+    const cssHrefs = [];
+    if (hostChrome) {
+        // Same application stylesheet as landing pages (header/footer chrome).
+        cssHrefs.push(`${prefix}vmz.css`);
+    }
+    if (designsHref)
+        cssHrefs.push(prefix + designsHref);
+    const cssLink = cssHrefs.map((href) => `  <link rel="stylesheet" href="${esc(href)}" />`).join('\n') + (cssHrefs.length ? '\n' : '');
+    const navItems = nav
+        .map((n) => {
+        const href = relativeHref(htmlRel, n.href, route);
+        const current = n.href === route ? ' aria-current="page"' : '';
+        return `      <li><a href="${esc(href)}"${current}>${esc(n.title)}</a></li>`;
+    })
+        .join('\n');
+    const toc = headings.length > 1
+        ? `<nav aria-label="On this page" class="toc">\n    <ol>\n${headings
+            .map((h) => `      <li class="h${h.level}"><a href="#${esc(h.id)}">${esc(h.text)}</a></li>`)
+            .join('\n')}\n    </ol>\n  </nav>\n`
+        : '';
+    const docsNav = `  <nav aria-label="Documents" class="doc-subnav">
+    <ul>
+${navItems}
+    </ul>
+  </nav>`;
+    if (hostChrome) {
+        const header = hostChrome.header.replace(/(<a\s+href="\/d\/?")([^>]*>文档<\/a>)/, '$1 aria-current="page"$2');
+        return `<!DOCTYPE html>
+<html lang="${esc(locale)}">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${esc(title)}</title>
+${cssLink}</head>
+<body data-vmz-hydrate="island-only">
+  <div class="site site--docs">
+  <a class="skip-link" href="#main">Skip to content</a>
+${header}
+${docsNav}
+${searchShellHtml}
+  <div class="doc-body">
+  ${toc}<main id="main">
+${bodyHtml}
+${playgroundShellHtml}
+  </main>
+  </div>
+${hostChrome.footer}
+  </div>
+</body>
+</html>
+`;
+    }
+    return `<!DOCTYPE html>
+<html lang="${esc(locale)}">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${esc(title)}</title>
+${cssLink}</head>
+<body data-vmz-hydrate="island-only">
+  <a class="skip-link" href="#main">Skip to content</a>
+${docsNav}
+${searchShellHtml}
+  ${toc}<main id="main">
+${bodyHtml}
+${playgroundShellHtml}
+  </main>
+</body>
+</html>
+`;
+}
+/**
+ * Integrated DocumentMount: reuse host SiteHeader / SiteFooter .vmz templates.
+ * @param {string} projectRoot
+ * @returns {{ header: string, footer: string } | null}
+ */
+function resolveHostSiteChrome(projectRoot) {
+    const headerPath = path.join(projectRoot, 'src', 'components', 'SiteHeader.vmz');
+    const footerPath = path.join(projectRoot, 'src', 'components', 'SiteFooter.vmz');
+    if (!fs.existsSync(headerPath) || !fs.existsSync(footerPath))
+        return null;
+    const header = extractVmzTemplateHtml(headerPath);
+    const footer = extractVmzTemplateHtml(footerPath);
+    if (!header || !footer)
+        return null;
+    return { header, footer };
+}
+/** @param {string} filePath */
+function extractVmzTemplateHtml(filePath) {
+    const src = fs.readFileSync(filePath, 'utf8');
+    const m = src.match(/<template>([\s\S]*?)<\/template>/);
+    return m ? m[1].trim() : '';
+}
+function relativeHref(fromHtmlRel, toRoute, _fromRoute) {
+    const toParts = String(toRoute).replace(/^\//, '').split('/').filter(Boolean);
+    let toRel;
+    if (toParts.length <= 2) {
+        toRel = [...toParts, 'index.html'].join('/');
+    }
+    else {
+        const file = toParts.slice(2).join('/') + '.html';
+        toRel = [...toParts.slice(0, 2), file].join('/');
+    }
+    const fromDir = path.posix.dirname(fromHtmlRel.replace(/\\/g, '/'));
+    let rel = path.posix.relative(fromDir, toRel);
+    if (!rel.startsWith('.') && !rel.startsWith('/'))
+        rel = './' + rel;
+    return rel || './index.html';
+}

package/dist/document-check.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Build DocumentManifest + run D0 / --strict checks.
+ */
+/**
+ * Resolve project documents root.
+ * @param {string} projectRoot
+ */
+export declare function resolveDocumentsRoot(projectRoot: any): string;
+/**
+ * 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 }}
+ */
+export declare function loadDocumentsConfig(documentsRoot: any): {
+    config: any;
+    diagnostics: any[];
+    configPath: string;
+};
+/**
+ * @param {object} opts
+ * @param {string} opts.projectRoot
+ * @param {boolean} [opts.strict]
+ * @returns {import('./document-schema.js').DocumentManifest}
+ */
+export declare function checkDocuments(opts: any): {
+    schema: string;
+    root: string;
+    defaultLocale: any;
+    locales: any[];
+    localeLabels: {};
+    collections: any[];
+    mounts: any[];
+    pages: {
+        identity: any;
+        sourcePath: any;
+        route: any;
+        anchors: any[];
+    }[];
+    diagnostics: any[];
+};
+/**
+ * @param {import('./document-schema.js').DocumentManifest} manifest
+ */
+export declare function manifestHasErrors(manifest: any): any;

package/dist/document-check.js

@@ -0,0 +1,246 @@
+// @ts-nocheck
+/**
+ * Build DocumentManifest + run D0 / --strict checks.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { DIAG, DOCUMENT_MANIFEST_SCHEMA } from './document-schema.js';
+import { scanDocumentsTree } from './document-scan.js';
+/**
+ * Resolve project documents root.
+ * @param {string} projectRoot
+ */
+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 }}
+ */
+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 };
+}
+/**
+ * D0: only declaration objects — no arbitrary hooks.
+ * @param {string} raw
+ * @param {string} filename
+ */
+function parseConfigSource(raw, filename) {
+    if (filename.endsWith('.json')) {
+        return JSON.parse(raw);
+    }
+    // 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)');
+    }
+    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);
+}
+/**
+ * @param {object} opts
+ * @param {string} opts.projectRoot
+ * @param {boolean} [opts.strict]
+ * @returns {import('./document-schema.js').DocumentManifest}
+ */
+export function checkDocuments(opts) {
+    const projectRoot = path.resolve(opts.projectRoot);
+    const documentsRoot = resolveDocumentsRoot(projectRoot);
+    const strict = Boolean(opts.strict);
+    /** @type {import('./document-schema.js').DocumentDiagnostic[]} */
+    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; D0 requires defaultLocale + locales for strict coverage checks',
+            path: documentsRoot,
+        });
+    }
+    /** @type {Record<string, string>} */
+    const localeLabels = {};
+    let 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',
+                });
+            }
+        }
+    }
+    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) {
+        if (!diskLocales.has(defaultLocale)) {
+            diagnostics.push({
+                code: DIAG.LOCALE_MISSING_DEFAULT,
+                severity: 'error',
+                message: `defaultLocale ${JSON.stringify(defaultLocale)} has no directory under documents/`,
+                path: configPath || documentsRoot,
+            });
+        }
+        if (configLocales.length && !configLocales.includes(defaultLocale)) {
+            diagnostics.push({
+                code: DIAG.CONFIG_DEFAULT_LOCALE,
+                severity: 'error',
+                message: `defaultLocale ${JSON.stringify(defaultLocale)} not listed in config.locales`,
+                path: configPath || documentsRoot,
+            });
+        }
+    }
+    else if (strict) {
+        diagnostics.push({
+            code: DIAG.CONFIG_DEFAULT_LOCALE,
+            severity: 'error',
+            message: 'defaultLocale is required under --strict',
+            path: configPath || documentsRoot,
+        });
+    }
+    for (const loc of configLocales) {
+        if (!diskLocales.has(loc)) {
+            diagnostics.push({
+                code: DIAG.LOCALE_MISSING_DEFAULT,
+                severity: 'error',
+                message: `config.locales entry ${JSON.stringify(loc)} has no documents/${loc}/ directory`,
+                path: configPath || documentsRoot,
+            });
+        }
+    }
+    // D0: 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();
+        for (const p of scanned.pages) {
+            const set = byLocale.get(p.identity.locale) || new Set();
+            set.add(p.identity.pageKey);
+            byLocale.set(p.identity.locale, set);
+        }
+        const baseline = byLocale.get(defaultLocale) || new Set();
+        for (const loc of scanned.locales) {
+            if (loc === defaultLocale)
+                continue;
+            const keys = byLocale.get(loc) || new Set();
+            for (const pk of baseline) {
+                if (!keys.has(pk)) {
+                    diagnostics.push({
+                        code: DIAG.LOCALE_MISSING_PAGE,
+                        severity: strict ? 'error' : 'warning',
+                        message: `missing translation: locale ${loc} lacks PageKey ${JSON.stringify(pk)} (present in ${defaultLocale})`,
+                        path: `documents/${loc}`,
+                    });
+                }
+            }
+            for (const pk of keys) {
+                if (!baseline.has(pk)) {
+                    diagnostics.push({
+                        code: DIAG.LOCALE_ORPHAN_PAGE,
+                        severity: strict ? 'error' : 'warning',
+                        message: `orphan page: locale ${loc} has PageKey ${JSON.stringify(pk)} missing from defaultLocale ${defaultLocale}`,
+                        path: `documents/${loc}/${pk}.md`,
+                    });
+                }
+            }
+        }
+    }
+    /** @type {import('./document-schema.js').PageRecord[]} */
+    const pages = scanned.pages.map((p) => ({
+        identity: p.identity,
+        sourcePath: p.sourcePath,
+        route: null,
+        anchors: [],
+    }));
+    return {
+        schema: DOCUMENT_MANIFEST_SCHEMA,
+        root: documentsRoot,
+        defaultLocale,
+        locales: scanned.locales,
+        localeLabels,
+        collections,
+        mounts,
+        pages,
+        diagnostics,
+    };
+}
+/**
+ * @param {import('./document-schema.js').DocumentManifest} manifest
+ */
+export function manifestHasErrors(manifest) {
+    return (manifest.diagnostics || []).some((d) => d.severity === 'error');
+}

package/dist/document-cmd.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `vmz document` / `vmz docs` CLI (D0 check · D1 build).
+ * Design: 规划设计/vmz/19 §1 · §8
+ */
+/**
+ * @param {string[]} argv
+ * @returns {Promise<number>}
+ */
+export declare function cmdDocument(argv: any): Promise<0 | 1>;