@vmz/vmz 0.0.1 → 0.0.3

package/dist/document-check.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Build DocumentManifest + run / --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 / --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 };
+}
+/**
+ *: 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; strict mode 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,
+            });
+        }
+    }
+    // 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,8 @@
+/**
+ * `vmz document` / `vmz docs` CLI .
+ */
+/**
+ * @param {string[]} argv
+ * @returns {Promise<number>}
+ */
+export declare function cmdDocument(argv: any): Promise<0 | 1>;

package/dist/document-cmd.js

@@ -0,0 +1,146 @@
+// @ts-nocheck
+/**
+ * `vmz document` / `vmz docs` CLI .
+ */
+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
+
+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 — 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;
+};