@vmz/vmz 0.1.17 → 0.1.18

package/dist/document-build.js

@@ -1,4 +1,3 @@
-// @ts-nocheck
 /**
  * Document Static + Interactive artifacts.
  */
@@ -16,9 +15,6 @@ import { DOCUMENT_VIEW_SCHEMA } from './document-schema.js';
 import { createWorkspace } from './index.js';
 import { requireNativeAddon } from './native-addon.js';
 import { writePrettyJsonFile } from './pretty-json.js';
-/**
- * @param {{ projectRoot: string, outDir?: string, appDistDir?: 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'));
@@ -42,7 +38,6 @@ export async function buildDocuments(opts) {
     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);
@@ -72,7 +67,6 @@ export async function buildDocuments(opts) {
     }
     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);
@@ -82,7 +76,6 @@ export async function buildDocuments(opts) {
     }
     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}`;
@@ -111,7 +104,7 @@ export async function buildDocuments(opts) {
             playgroundShellHtml: shells.playgroundHtml,
         });
         let compiledLayoutHtml = null;
-        if (useCompiledShell) {
+        if (useCompiledShell && appDistDir) {
             compiledLayoutHtml = await renderCompiledDocumentLayout(appDistDir, page.identity.locale, slotHtml);
         }
         const view = {
@@ -180,10 +173,6 @@ export async function buildDocuments(opts) {
     writePrettyJsonFile(path.join(outDir, 'document.islands.json'), islands);
     return { ok: true, manifest: manifestOut, outDir, pages: written, search, islands };
 }
-/**
- * @param {{ appDistDir?: string }} opts
- * @param {string} outDir
- */
 function resolveAppDistDir(opts, outDir) {
     if (opts.appDistDir) {
         const p = path.resolve(opts.appDistDir);
@@ -191,10 +180,8 @@ function resolveAppDistDir(opts, outDir) {
     }
     return fs.existsSync(path.join(outDir, 'vmz-dom.js')) ? outDir : null;
 }
-/**
- * Document main column + sidebar (injected into DocumentLayout slot).
- */
-function buildDocumentSlotHtml({ nav, bodyHtml, headings, htmlRel, route, routing, searchShellHtml = '', playgroundShellHtml = '' }) {
+/** Document main column + sidebar (injected into DocumentLayout slot). */
+function buildDocumentSlotHtml({ nav, bodyHtml, headings, htmlRel, route, routing, searchShellHtml = '', playgroundShellHtml = '', }) {
     const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
     const navItems = nav
         .map((n) => {
@@ -232,17 +219,15 @@ function renderStaticHtml({ title, locale, route, nav, bodyHtml, headings, desig
     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 (useCompiledShell) {
         cssHrefs.push('/vmz.css');
     }
     if (designsHref)
         cssHrefs.push(useCompiledShell ? `/${designsHref}` : prefix + designsHref);
-    /** @type {string} */
     let bodyInner;
     if (useCompiledShell) {
-        bodyInner = compiledLayoutHtml;
+        bodyInner = compiledLayoutHtml || '';
     }
     else {
         const navItems = nav

package/dist/document-check.d.ts

@@ -4,60 +4,37 @@
  * Author documents config is parsed by Rust DocumentRoutePlan; TS only
  * merges filesystem scan (pageKeys) and coverage diagnostics.
  */
-/**
- * Resolve project documents root.
- * @param {string} projectRoot
- */
-export declare function resolveDocumentsRoot(projectRoot: any): string;
-/**
- * Load normalized DocumentRoutePlan from Rust (author JSON5/JSON/declaration).
- * @param {string} projectRoot
- */
-export declare function loadDocumentsRoutePlan(projectRoot: any): any;
+import { type DocumentRoutePlan } from './author-input.js';
+import { type DocumentDiagnostic, type DocumentManifest } from './document-schema.js';
+export interface DocumentsConfigShape {
+    defaultLocale?: string;
+    locales: Record<string, {
+        label: unknown;
+    }>;
+    collections: Record<string, {
+        source: string;
+        mount: string;
+    }>;
+    fallback?: boolean;
+}
+export interface LoadDocumentsConfigResult {
+    config: DocumentsConfigShape | null;
+    diagnostics: DocumentDiagnostic[];
+    configPath: string | null;
+    plan: DocumentRoutePlan;
+}
+export interface CheckDocumentsOpts {
+    projectRoot: string;
+    strict?: boolean;
+}
+/** Resolve project documents root. */
+export declare function resolveDocumentsRoot(projectRoot: string): string;
+/** Load normalized DocumentRoutePlan from Rust (author JSON5/JSON/declaration). */
+export declare function loadDocumentsRoutePlan(projectRoot: string): DocumentRoutePlan;
 /**
  * @deprecated Prefer loadDocumentsRoutePlan(projectRoot). Kept for call sites that
  * only need the plan-shaped config fields.
- * @param {string} documentsRoot
- */
-export declare function loadDocumentsConfig(documentsRoot: any): {
-    config: {
-        defaultLocale: any;
-        locales: {
-            [k: string]: {
-                label: unknown;
-            };
-        };
-        collections: {
-            [k: string]: any;
-        };
-    };
-    diagnostics: any;
-    configPath: string;
-    plan: any;
-};
-/**
- * @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: any;
-    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;
+export declare function loadDocumentsConfig(documentsRoot: string): LoadDocumentsConfigResult;
+export declare function checkDocuments(opts: CheckDocumentsOpts): DocumentManifest;
+export declare function manifestHasErrors(manifest: DocumentManifest): boolean;

package/dist/document-check.js

@@ -1,4 +1,3 @@
-// @ts-nocheck
 /**
  * Build DocumentManifest + run / --strict checks.
  *
@@ -8,62 +7,47 @@
 import path from 'node:path';
 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
- */
+import { DIAG, DOCUMENT_MANIFEST_SCHEMA, } from './document-schema.js';
+/** Resolve project documents root. */
 export function resolveDocumentsRoot(projectRoot) {
     return path.resolve(projectRoot, 'documents');
 }
-/**
- * Load normalized DocumentRoutePlan from Rust (author JSON5/JSON/declaration).
- * @param {string} projectRoot
- */
+/** Load normalized DocumentRoutePlan from Rust (author JSON5/JSON/declaration). */
 export function loadDocumentsRoutePlan(projectRoot) {
     return loadDocumentRoutePlan(projectRoot);
 }
 /**
  * @deprecated Prefer loadDocumentsRoutePlan(projectRoot). Kept for call sites that
  * only need the plan-shaped config fields.
- * @param {string} documentsRoot
  */
 export function loadDocumentsConfig(documentsRoot) {
     const projectRoot = path.dirname(documentsRoot);
     const plan = loadDocumentRoutePlan(projectRoot);
-    const diagnostics = mapPlanDiagnostics(plan.diagnostics);
+    const diagnostics = toDocumentDiagnostics(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 };
     }
-    /** @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 }])),
+        collections: Object.fromEntries((plan.collections || []).map((c) => [c.id, { source: c.sourceRoot || '.', mount: c.routeBase || '/docs' }])),
     };
     if (plan.silentFallbackRequested) {
         config.fallback = true;
     }
     return { config, diagnostics, configPath, plan };
 }
-/**
- * @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 plan = loadDocumentRoutePlan(projectRoot);
-    diagnostics.push(...mapPlanDiagnostics(plan.diagnostics));
+    diagnostics.push(...toDocumentDiagnostics(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) {
@@ -77,12 +61,9 @@ export function checkDocuments(opts) {
             });
         }
     }
-    /** @type {Record<string, string>} */
     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 = [];
     for (const c of plan.collections || []) {
         const sourceRoot = c.sourceRoot || '.';
@@ -182,7 +163,6 @@ export function checkDocuments(opts) {
             }
         }
     }
-    /** @type {import('./document-schema.js').PageRecord[]} */
     const pages = scanned.pages.map((p) => ({
         identity: p.identity,
         sourcePath: p.sourcePath,
@@ -201,9 +181,14 @@ export function checkDocuments(opts) {
         diagnostics,
     };
 }
-/**
- * @param {import('./document-schema.js').DocumentManifest} manifest
- */
 export function manifestHasErrors(manifest) {
     return (manifest.diagnostics || []).some((d) => d.severity === 'error');
 }
+function toDocumentDiagnostics(rows) {
+    return rows.map((d) => ({
+        code: d.code,
+        severity: d.severity === 'warning' || d.severity === 'advice' ? 'warning' : 'error',
+        message: d.message,
+        path: d.path,
+    }));
+}

package/dist/document-cmd.d.ts

@@ -1,8 +1,5 @@
 /**
- * `vmz document` / `vmz docs` CLI .
+ * `vmz document` / `vmz docs` — registered on `@vmz/commander`.
  */
-/**
- * @param {string[]} argv
- * @returns {Promise<number>}
- */
-export declare function cmdDocument(argv: any): Promise<0 | 1>;
+import type { Command } from '@vmz/commander';
+export declare function registerDocumentCommands(parent: Command): void;

package/dist/document-cmd.js

@@ -1,6 +1,5 @@
-// @ts-nocheck
 /**
- * `vmz document` / `vmz docs` CLI .
+ * `vmz document` / `vmz docs` — registered on `@vmz/commander`.
  */
 import path from 'node:path';
 import { buildDocuments } from './document-build.js';
@@ -10,66 +9,16 @@ 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';
 import { emitPrettyJson } from './pretty-json.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
-`);
+export function registerDocumentCommands(parent) {
+    const withOpts = (cmd) => cmd
+        .option('--root <dir>', 'cli.opt.root')
+        .option('--out <dir>', 'cli.opt.out')
+        .option('--strict', 'cli.opt.strict')
+        .option('--json [file]', 'cli.opt.json');
+    withOpts(parent.command('check', 'cli.cmd.document.check')).action((options) => cmdDocumentCheck(options));
+    withOpts(parent.command('build', 'cli.cmd.document.build')).action((options) => cmdDocumentBuild(options));
 }
-/**
- * @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);
@@ -91,25 +40,21 @@ async function cmdDocumentCheck(args) {
         manifest.evidence = evidence.evidence;
     }
     catch (e) {
-        log.warn(`document check: markdown/evidence unavailable (${e.message}); skipping enrich`);
+        const msg = e instanceof Error ? e.message : String(e);
+        log.warn(`document check: markdown/evidence unavailable (${msg}); skipping enrich`);
     }
     const jsonOut = args.json;
     if (jsonOut) {
-        emitPrettyJson(jsonOut, manifest, { logWrote: (p) => log.info(`wrote ${p}`) });
+        emitPrettyJson(typeof jsonOut === 'string' ? jsonOut : true, manifest, {
+            logWrote: (p) => log.info(`wrote ${p}`),
+        });
     }
     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.diagnostics(manifest.diagnostics ?? []);
         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);
@@ -120,18 +65,13 @@ async function cmdDocumentBuild(args) {
         result = await buildDocuments({ projectRoot, outDir, strict });
     }
     catch (e) {
-        log.error(`document build failed: ${e.message || e}`);
+        const msg = e instanceof Error ? e.message : String(e);
+        log.error(`document build failed: ${msg}`);
         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}`);
-    }
+    log.diagnostics(result.manifest.diagnostics || []);
     if (!result.ok) {
-        log.error('document build aborted due to diagnostics');
+        log.errorId('cli.err.document_build_aborted');
         return 1;
     }
     log.info(`document build: pages=${result.pages.length} out=${path.relative(process.cwd(), result.outDir) || '.'} designs=${result.manifest.build?.designsCss ?? '(none)'}`);

package/dist/document-designs.d.ts

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

package/dist/document-designs.js

@@ -1,22 +1,15 @@
-// @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')];
@@ -58,9 +51,7 @@ export function resolveDocumentDesignsCss(projectRoot) {
     }
     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)) {
@@ -94,15 +85,11 @@ function cssVar(key) {
         .replace(/^-|-$/g, '');
     return `--${name}`;
 }
-/**
- * Style Theme entries (`key.path` + `value`) → `vmz-*` CSS vars (same naming as application compile).
- * @param {unknown} obj
- * @param {Record<string, string>} out
- */
+/** Style Theme entries (`key.path` + `value`) → `vmz-*` CSS vars (same naming as application compile). */
 function collectStyleThemeEntries(obj, out) {
     if (obj == null || typeof obj !== 'object' || Array.isArray(obj))
         return;
-    const entries = /** @type {{ key?: { path?: unknown }, value?: unknown }[]} */ ( /** @type {{ entries?: unknown }} */(obj).entries);
+    const entries = obj.entries;
     if (!Array.isArray(entries))
         return;
     for (const e of entries) {

package/dist/document-enrich.d.ts

@@ -1,24 +1,52 @@
-/**
- * @param {string} routeBase e.g. /docs
- * @param {string} locale
- * @param {string} pageKey
- * @param {{ strategy?: string }} [routing]
- */
-export declare function pageRoute(routeBase: any, locale: any, pageKey: any, routing?: {}): 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;
-};
+import { type DocumentDiagnostic, type DocumentManifest } from './document-schema.js';
+export interface DocumentRoutingStrategy {
+    strategy?: string;
+}
+export interface DocumentHeading {
+    id: string;
+    level: number;
+    text: string;
+}
+export interface DocumentLink {
+    href?: string;
+}
+export interface AnalyzedMarkdown {
+    html: string;
+    headings: DocumentHeading[];
+    links?: DocumentLink[];
+    fences?: Array<{
+        info?: string;
+        content?: string;
+        lineStart?: number;
+        lineEnd?: number;
+    }>;
+}
+export interface EnrichedPageInfo {
+    html: string;
+    headings: DocumentHeading[];
+    links: DocumentLink[];
+    title: string;
+    route: string;
+    anchors: string[];
+}
+export interface DocumentNavItem {
+    pageKey: string;
+    title: string;
+    href: string;
+}
+export interface EnrichDocumentContentCtx {
+    analyzeMarkdown: (source: string) => AnalyzedMarkdown;
+    projectRoot: string;
+    designsCssHref?: string | null;
+    routing?: DocumentRoutingStrategy;
+}
+export interface EnrichDocumentContentResult {
+    byId: Map<string, EnrichedPageInfo>;
+    navByLocale: Record<string, DocumentNavItem[]>;
+    diagnostics: DocumentDiagnostic[];
+    routeBase: string;
+}
+export declare function pageRoute(routeBase: string, locale: string, pageKey: string, routing?: DocumentRoutingStrategy): string;
+/** Static file path relative to out dir (posix). */
+export declare function pageHtmlRel(routeBase: string, locale: string, pageKey: string): string;
+export declare function enrichDocumentContent(manifest: DocumentManifest, ctx: EnrichDocumentContentCtx): EnrichDocumentContentResult;