@vmz/vmz 0.0.1 → 0.0.2

package/dist/document-cmd.js

@@ -0,0 +1,147 @@
+// @ts-nocheck
+/**
+ * `vmz document` / `vmz docs` CLI (D0 check · D1 build).
+ * Design: 规划设计/vmz/19 §1 · §8
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildDocuments } from './document-build.js';
+import { checkDocuments, manifestHasErrors } from './document-check.js';
+import { enrichDocumentContent } from './document-enrich.js';
+import { enrichDocumentEvidence } from './document-evidence.js';
+import { resolveMarkdownEngine } from './document-markdown.js';
+import { createWorkspace } from './index.js';
+import { log } from './log.js';
+import { parseArgs } from './cli.js';
+function printDocumentHelp() {
+    console.log(`vmz document — project /documents domain (D0–D3)
+
+Usage:
+  vmz document check [project]   Check locale tree + links/anchors + fence/API evidence
+  vmz document build [project]   Static HTML + view + evidence + search/islands + /designs CSS
+  vmz docs check|build […]       Alias of document
+
+Options:
+  --root <dir>     Project root (default: . or positional path)
+  --out <dir>      Build output (default: <project>/dist/documents)
+  --strict         Fail on missing/orphan translations & require defaultLocale
+  --json [file]    Emit DocumentManifest JSON to stdout or file
+`);
+}
+/**
+ * @param {string[]} argv
+ * @returns {Promise<number>}
+ */
+export async function cmdDocument(argv) {
+    const [sub, ...rest] = argv;
+    if (!sub) {
+        if (process.stdout.isTTY) {
+            printDocumentHelp();
+            return 0;
+        }
+        log.error('vmz document requires a subcommand in non-interactive/CI contexts');
+        printDocumentHelp();
+        return 1;
+    }
+    if (sub === 'help' || sub === '-h' || sub === '--help') {
+        printDocumentHelp();
+        return 0;
+    }
+    if (sub.startsWith('-')) {
+        log.error('vmz document requires a subcommand (check|build)');
+        printDocumentHelp();
+        return 1;
+    }
+    const args = parseArgs(rest);
+    switch (sub) {
+        case 'check':
+            return cmdDocumentCheck(args);
+        case 'build':
+            return cmdDocumentBuild(args);
+        case 'dev':
+        case 'serve':
+        case 'test':
+        case 'clean':
+            log.error(`vmz document ${sub} is not implemented yet`);
+            return 1;
+        default:
+            log.error(`unknown document subcommand \`${sub}\``);
+            printDocumentHelp();
+            return 1;
+    }
+}
+/** @param {Record<string, string | boolean> & { _: string[] }} args */
+async function cmdDocumentCheck(args) {
+    const project = (typeof args.root === 'string' && args.root) || (typeof args._[0] === 'string' && args._[0]) || '.';
+    const projectRoot = path.resolve(project);
+    const strict = Boolean(args.strict);
+    const manifest = checkDocuments({ projectRoot, strict });
+    try {
+        const engine = await resolveMarkdownEngine({});
+        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;
+    }
+    catch (e) {
+        log.warn(`document check: markdown/evidence unavailable (${e.message}); skipping enrich`);
+    }
+    const jsonOut = args.json;
+    if (jsonOut) {
+        const text = JSON.stringify(manifest, null, 2);
+        if (typeof jsonOut === 'string') {
+            fs.writeFileSync(jsonOut, text + '\n', 'utf8');
+            log.info(`wrote ${jsonOut}`);
+        }
+        else {
+            console.log(text);
+        }
+    }
+    else {
+        for (const d of manifest.diagnostics) {
+            const loc = d.path ? ` (${d.path})` : '';
+            if (d.severity === 'error')
+                log.error(`${d.code}: ${d.message}${loc}`);
+            else
+                console.warn(`vmz warn ${d.code}: ${d.message}${loc}`);
+        }
+        log.info(`document check: locales=${manifest.locales.join(',') || '(none)'} pages=${manifest.pages.length} defaultLocale=${manifest.defaultLocale ?? '(none)'}`);
+    }
+    return manifestHasErrors(manifest) ? 1 : 0;
+}
+/** @param {Record<string, string | boolean> & { _: string[] }} args */
+async function cmdDocumentBuild(args) {
+    const project = (typeof args.root === 'string' && args.root) || (typeof args._[0] === 'string' && args._[0]) || '.';
+    const projectRoot = path.resolve(project);
+    const outDir = (typeof args.out === 'string' && args.out) || path.join(projectRoot, 'dist', 'documents');
+    const strict = Boolean(args.strict);
+    let result;
+    try {
+        result = await buildDocuments({ projectRoot, outDir, strict });
+    }
+    catch (e) {
+        log.error(`document build failed: ${e.message || e}`);
+        return 1;
+    }
+    for (const d of result.manifest.diagnostics || []) {
+        const loc = d.path ? ` (${d.path})` : '';
+        if (d.severity === 'error')
+            log.error(`${d.code}: ${d.message}${loc}`);
+        else
+            console.warn(`vmz warn ${d.code}: ${d.message}${loc}`);
+    }
+    if (!result.ok) {
+        log.error('document build aborted due to diagnostics');
+        return 1;
+    }
+    log.info(`document build: pages=${result.pages.length} out=${path.relative(process.cwd(), result.outDir) || '.'} designs=${result.manifest.build?.designsCss ?? '(none)'}`);
+    return 0;
+}

package/dist/document-designs.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @param {string} projectRoot
+ * @returns {{ css: string, source: string | null, href: string | null }}
+ */
+export declare function resolveDocumentDesignsCss(projectRoot: any): {
+    css: string;
+    source: string;
+    href: string;
+};

package/dist/document-designs.js

@@ -0,0 +1,126 @@
+// @ts-nocheck
+/**
+ * Document D1 — wire project `/designs` into static document assets.
+ * Prefer compiled `vmz-designs.css` / `vmz.css`; else emit a minimal token CSS.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * @param {string} projectRoot
+ * @returns {{ css: string, source: string | null, href: string | null }}
+ */
+export function resolveDocumentDesignsCss(projectRoot) {
+    const designsDir = path.join(projectRoot, 'designs');
+    if (!fs.existsSync(designsDir) || !fs.statSync(designsDir).isDirectory()) {
+        return { css: '', source: null, href: null };
+    }
+    /** @type {string[]} */
+    const parts = [];
+    /** @type {string[]} */
+    const sources = [];
+    // Layout first so @import (fonts) stays at stylesheet top; theme tokens follow.
+    const layoutCandidates = [path.join(designsDir, 'document', 'chrome.css'), path.join(designsDir, 'styles', 'document.css')];
+    for (const p of layoutCandidates) {
+        if (!fs.existsSync(p))
+            continue;
+        parts.push(fs.readFileSync(p, 'utf8'));
+        sources.push(path.relative(projectRoot, p).replace(/\\/g, '/'));
+        break;
+    }
+    const distCandidates = [path.join(projectRoot, 'dist', 'vmz-designs.css'), path.join(projectRoot, 'dist', 'vmz.css')];
+    for (const p of distCandidates) {
+        if (fs.existsSync(p)) {
+            parts.push(fs.readFileSync(p, 'utf8'));
+            sources.push(path.relative(projectRoot, p).replace(/\\/g, '/'));
+            break;
+        }
+    }
+    if (parts.length) {
+        return {
+            css: parts.join('\n\n'),
+            source: sources.join('+'),
+            href: 'assets/vmz-designs.css',
+        };
+    }
+    const styleCandidates = [path.join(designsDir, 'styles', 'index.css')];
+    for (const p of styleCandidates) {
+        if (fs.existsSync(p)) {
+            return {
+                css: fs.readFileSync(p, 'utf8'),
+                source: path.relative(projectRoot, p).replace(/\\/g, '/'),
+                href: 'assets/vmz-designs.css',
+            };
+        }
+    }
+    const emitted = emitMinimalDesignsCss(designsDir);
+    if (emitted) {
+        return { css: emitted, source: 'designs/', href: 'assets/vmz-designs.css' };
+    }
+    return { css: '', source: 'designs/', href: null };
+}
+/** @param {string} designsDir */
+function emitMinimalDesignsCss(designsDir) {
+    /** @type {Record<string, string>} */
+    const vars = {};
+    const tokenDir = path.join(designsDir, 'tokens');
+    if (fs.existsSync(tokenDir)) {
+        walkJson(tokenDir, (obj, prefix) => flattenTokens(obj, prefix, vars));
+    }
+    const themeJson = path.join(designsDir, 'theme.json');
+    if (fs.existsSync(themeJson)) {
+        try {
+            flattenTokens(JSON.parse(fs.readFileSync(themeJson, 'utf8')), '', vars);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    const keys = Object.keys(vars).sort();
+    if (!keys.length) {
+        // Presence of /designs still warrants a readable baseline sheet.
+        return `/* vmz.document designs baseline */\n:root { color-scheme: light; }\nbody { font-family: system-ui, sans-serif; line-height: 1.5; margin: 0; }\nmain { max-width: 48rem; margin: 0 auto; padding: 1.5rem; }\nnav { padding: 1rem 1.5rem; border-bottom: 1px solid #ddd; }\n`;
+    }
+    const lines = keys.map((k) => `  ${cssVar(k)}: ${vars[k]};`);
+    return `/* vmz.document designs from /designs */\n:root {\n${lines.join('\n')}\n}\nbody { font-family: var(--font-sans, system-ui, sans-serif); line-height: 1.5; margin: 0; color: var(--color-fg, #111); background: var(--color-bg, #fff); }\nmain { max-width: 48rem; margin: 0 auto; padding: 1.5rem; }\nnav { padding: 1rem 1.5rem; border-bottom: 1px solid var(--color-border, #ddd); }\n`;
+}
+function cssVar(key) {
+    const name = String(key)
+        .replace(/[^a-zA-Z0-9_-]+/g, '-')
+        .replace(/^-|-$/g, '');
+    return `--${name}`;
+}
+function flattenTokens(obj, prefix, out) {
+    if (obj == null || typeof obj !== 'object' || Array.isArray(obj))
+        return;
+    for (const [k, v] of Object.entries(obj)) {
+        const key = prefix ? `${prefix}-${k}` : k;
+        if (v != null && typeof v === 'object' && !Array.isArray(v)) {
+            if ('value' in v && (typeof v.value === 'string' || typeof v.value === 'number')) {
+                out[key] = String(v.value);
+            }
+            else {
+                flattenTokens(v, key, out);
+            }
+        }
+        else if (typeof v === 'string' || typeof v === 'number') {
+            out[key] = String(v);
+        }
+    }
+}
+function walkJson(dir, fn) {
+    if (!fs.existsSync(dir))
+        return;
+    for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, ent.name);
+        if (ent.isDirectory())
+            walkJson(full, fn);
+        else if (ent.isFile() && ent.name.endsWith('.json')) {
+            try {
+                fn(JSON.parse(fs.readFileSync(full, 'utf8')), '');
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+}

package/dist/document-enrich.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @param {string} routeBase e.g. /docs
+ * @param {string} locale
+ * @param {string} pageKey
+ */
+export declare function pageRoute(routeBase: any, locale: any, pageKey: any): string;
+/**
+ * Static file path relative to out dir (posix).
+ * @param {string} routeBase
+ * @param {string} locale
+ * @param {string} pageKey
+ */
+export declare function pageHtmlRel(routeBase: any, locale: any, pageKey: any): string;
+/**
+ * @param {import('./document-schema.js').DocumentManifest} manifest
+ * @param {{ analyzeMarkdown: Function, projectRoot: string, designsCssHref?: string | null }} ctx
+ */
+export declare function enrichDocumentContent(manifest: any, ctx: any): {
+    byId: Map<any, any>;
+    navByLocale: {};
+    diagnostics: any[];
+    routeBase: any;
+};

package/dist/document-enrich.js

@@ -0,0 +1,234 @@
+// @ts-nocheck
+/**
+ * Document D1 — enrich manifest with routes, anchors, nav; diagnose links.
+ * Design: 规划设计/vmz/19 §5–6
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { DIAG } from './document-schema.js';
+/**
+ * @param {string} routeBase e.g. /docs
+ * @param {string} locale
+ * @param {string} pageKey
+ */
+export function pageRoute(routeBase, locale, pageKey) {
+    const base = String(routeBase || '/').replace(/\/$/, '') || '';
+    const key = pageKey === 'index' ? '' : pageKey.replace(/\\/g, '/');
+    const parts = [base.replace(/^\//, ''), locale, key].filter((p) => p !== '');
+    return '/' + parts.join('/');
+}
+/**
+ * Static file path relative to out dir (posix).
+ * @param {string} routeBase
+ * @param {string} locale
+ * @param {string} pageKey
+ */
+export function pageHtmlRel(routeBase, locale, pageKey) {
+    const base = String(routeBase || '/')
+        .replace(/^\//, '')
+        .replace(/\/$/, '');
+    const file = pageKey === 'index' ? 'index.html' : `${pageKey.replace(/\\/g, '/')}.html`;
+    return [base, locale, file].filter(Boolean).join('/');
+}
+/**
+ * @param {import('./document-schema.js').DocumentManifest} manifest
+ * @param {{ analyzeMarkdown: Function, projectRoot: string, designsCssHref?: string | null }} ctx
+ */
+export function enrichDocumentContent(manifest, ctx) {
+    const routeBase = manifest.mounts?.[0]?.routeBase || '/docs';
+    /** @type {Map<string, { html: string, headings: any[], links: any[], title: string, route: string, anchors: string[] }>} */
+    const byId = new Map();
+    /** @type {import('./document-schema.js').DocumentDiagnostic[]} */
+    const diagnostics = [...(manifest.diagnostics || [])];
+    /** @type {Map<string, string>} */
+    const routeOwners = 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 analyzed = ctx.analyzeMarkdown(source);
+        const route = pageRoute(routeBase, page.identity.locale, page.identity.pageKey);
+        const anchors = analyzed.headings.map((h) => h.id);
+        const title = analyzed.headings.find((h) => h.level === 1)?.text || analyzed.headings[0]?.text || page.identity.pageKey;
+        // Duplicate anchors on page
+        const seen = new Set();
+        for (const id of anchors) {
+            if (seen.has(id)) {
+                diagnostics.push({
+                    code: DIAG.ANCHOR_DUPLICATE,
+                    severity: 'error',
+                    message: `duplicate anchor #${id} on ${page.identity.locale}/${page.identity.pageKey}`,
+                    path: page.sourcePath,
+                });
+            }
+            seen.add(id);
+        }
+        if (routeOwners.has(route)) {
+            diagnostics.push({
+                code: DIAG.ROUTE_DUPLICATE,
+                severity: 'error',
+                message: `duplicate route ${route} (also ${routeOwners.get(route)})`,
+                path: page.sourcePath,
+            });
+        }
+        else {
+            routeOwners.set(route, `${page.identity.locale}:${page.identity.pageKey}`);
+        }
+        page.route = route;
+        page.anchors = anchors;
+        page.title = title;
+        byId.set(`${page.identity.locale}:${page.identity.pageKey}`, {
+            html: analyzed.html,
+            headings: analyzed.headings,
+            links: analyzed.links,
+            title,
+            route,
+            anchors,
+        });
+    }
+    // Nav per locale (directory order: pageKey sorted)
+    /** @type {Record<string, Array<{ pageKey: string, title: string, href: string }>>} */
+    const navByLocale = {};
+    for (const loc of manifest.locales) {
+        const pages = manifest.pages
+            .filter((p) => p.identity.locale === loc)
+            .slice()
+            .sort((a, b) => a.identity.pageKey.localeCompare(b.identity.pageKey));
+        navByLocale[loc] = pages.map((p) => ({
+            pageKey: p.identity.pageKey,
+            title: p.title || p.identity.pageKey,
+            href: p.route,
+        }));
+    }
+    // Link checks
+    const pageKeySet = new Map(); // locale -> Set pageKey
+    for (const p of manifest.pages) {
+        const set = pageKeySet.get(p.identity.locale) || new Set();
+        set.add(p.identity.pageKey);
+        pageKeySet.set(p.identity.locale, set);
+    }
+    for (const page of manifest.pages) {
+        const info = byId.get(`${page.identity.locale}:${page.identity.pageKey}`);
+        if (!info)
+            continue;
+        for (const link of info.links) {
+            const href = String(link.href || '').trim();
+            if (!href || href.startsWith('mailto:') || href.startsWith('http://') || href.startsWith('https://')) {
+                continue;
+            }
+            // D2 API refs are resolved by evidence, not as page links.
+            if (href.startsWith('vmz-api:') || href.startsWith('api:')) {
+                continue;
+            }
+            if (href.startsWith('#')) {
+                const id = href.slice(1);
+                if (!info.anchors.includes(id)) {
+                    diagnostics.push({
+                        code: DIAG.LINK_BROKEN,
+                        severity: 'error',
+                        message: `broken anchor ${href} on ${page.identity.locale}/${page.identity.pageKey}`,
+                        path: page.sourcePath,
+                    });
+                }
+                continue;
+            }
+            const resolved = resolveDocHref(href, page.identity.pageKey, page.identity.locale, routeBase, pageKeySet);
+            if (!resolved.ok) {
+                diagnostics.push({
+                    code: DIAG.LINK_BROKEN,
+                    severity: 'error',
+                    message: `broken link ${JSON.stringify(href)}: ${resolved.reason}`,
+                    path: page.sourcePath,
+                });
+            }
+            else if (resolved.anchor) {
+                const target = byId.get(`${resolved.locale}:${resolved.pageKey}`);
+                const anchors = target?.anchors || [];
+                if (!anchors.includes(resolved.anchor)) {
+                    diagnostics.push({
+                        code: DIAG.LINK_BROKEN,
+                        severity: 'error',
+                        message: `broken link ${JSON.stringify(href)}: missing anchor #${resolved.anchor}`,
+                        path: page.sourcePath,
+                    });
+                }
+            }
+        }
+    }
+    return { byId, navByLocale, diagnostics, routeBase };
+}
+/**
+ * @param {string} href
+ * @param {string} fromPageKey
+ * @param {string} locale
+ * @param {string} routeBase
+ * @param {Map<string, Set<string>>} pageKeySet
+ */
+function resolveDocHref(href, fromPageKey, locale, routeBase, pageKeySet) {
+    let pathPart = href;
+    let anchor = null;
+    const hash = href.indexOf('#');
+    if (hash >= 0) {
+        pathPart = href.slice(0, hash);
+        anchor = href.slice(hash + 1);
+    }
+    pathPart = pathPart.replace(/\.md$/i, '').replace(/\\/g, '/');
+    if (pathPart.startsWith('/')) {
+        // Absolute site path under mount: /docs/zh-hans/guide/install
+        const want = pathPart.replace(/\/$/, '') || '/';
+        const prefix = pageRoute(routeBase, locale, 'index').replace(/\/$/, '');
+        // Accept full route or locale-relative
+        for (const [loc, keys] of pageKeySet) {
+            for (const pk of keys) {
+                const r = pageRoute(routeBase, loc, pk).replace(/\/$/, '');
+                if (r === want || want.endsWith(`/${loc}/${pk === 'index' ? '' : pk}`.replace(/\/$/, ''))) {
+                    return { ok: true, locale: loc, pageKey: pk, anchor, anchors: [] };
+                }
+            }
+        }
+        // Still ok if matches any known route shape for this locale
+        const keys = pageKeySet.get(locale) || new Set();
+        const stripped = want.replace(new RegExp(`^${escapeRe(routeBase.replace(/\/$/, ''))}/${escapeRe(locale)}/?`), '');
+        const pk = stripped === '' ? 'index' : stripped;
+        if (keys.has(pk))
+            return { ok: true, locale, pageKey: pk, anchor, anchors: [] };
+        return { ok: false, reason: 'unknown route' };
+    }
+    // Relative to current page directory
+    const fromDir = pageKeyDir(fromPageKey);
+    const joined = path.posix.normalize(path.posix.join(fromDir || '.', pathPart));
+    let pk = joined === '.' || joined === '' ? 'index' : joined.replace(/^\.\//, '');
+    pk = normalizePageKey(pk);
+    const keys = pageKeySet.get(locale) || new Set();
+    if (!keys.has(pk)) {
+        return { ok: false, reason: `no PageKey ${pk} in ${locale}` };
+    }
+    return { ok: true, locale, pageKey: pk, anchor, anchors: [] };
+}
+/**
+ * Directory used for relative Markdown links.
+ * `index` → repo root; bare `guide` (from guide/index.md) → `guide`;
+ * `guide/install` → `guide`.
+ */
+function pageKeyDir(pageKey) {
+    if (!pageKey || pageKey === 'index')
+        return '';
+    if (!pageKey.includes('/'))
+        return pageKey;
+    return pageKey.slice(0, pageKey.lastIndexOf('/'));
+}
+/** Strip trailing `/index` so guide/index.md links resolve to PageKey `guide`. */
+function normalizePageKey(pageKey) {
+    let pk = String(pageKey || '')
+        .replace(/\\/g, '/')
+        .replace(/\/+$/, '');
+    if (pk.endsWith('/index')) {
+        pk = pk.slice(0, -'/index'.length);
+    }
+    else if (pk === 'index') {
+        return 'index';
+    }
+    return pk === '' || pk === '.' ? 'index' : pk;
+}
+function escapeRe(s) {
+    return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/document-evidence.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @param {string} info
+ * @returns {{ lang: string, run: string | null, source: string | null, playground: boolean }}
+ */
+export declare function parseFenceInfo(info: any): {
+    lang: string;
+    run: any;
+    source: any;
+    playground: boolean;
+};
+/**
+ * @param {string} href
+ * @returns {string | null} symbol query (chunkId or name)
+ */
+export declare function parseApiHref(href: any): string;
+/**
+ * @param {string} projectRoot
+ * @returns {Array<{ chunkId: string, name: string, path: string, capabilities: string[], programPath: string }>}
+ */
+export declare function loadProgramApiIndex(projectRoot: any): any[];
+/**
+ * Resolve API symbol against Program Graph index.
+ * @param {ReturnType<typeof loadProgramApiIndex>} index
+ * @param {string} query
+ */
+export declare function resolveApiSymbol(index: any, query: any): {
+    status: string;
+    matches: any;
+};
+/**
+ * @param {import('./document-schema.js').DocumentManifest} manifest
+ * @param {{
+ *   analyzeMarkdown: Function,
+ *   projectRoot: string,
+ *   createWorkspace?: Function,
+ *   ensureProgramGraph?: boolean,
+ * }} ctx
+ */
+export declare function enrichDocumentEvidence(manifest: any, ctx: any): Promise<{
+    diagnostics: any[];
+    evidence: {
+        schema: string;
+        fences: any[];
+        apiRefs: any[];
+        testSelections: any[];
+        status: string;
+    };
+}>;
+/** Lazy note: callers pass `createWorkspace` from `./index.js` (see document-cmd / document-build). */