@vmz/vmz 0.0.0 → 0.0.2

package/dist/document-schema.js

@@ -0,0 +1,88 @@
+// @ts-nocheck
+/**
+ * Document D0 Contract — schema constants & diagnostic codes.
+ * Design: 规划设计/vmz/19 §2.3 · D0
+ *
+ * Not a Doc IR: this is a filesystem/manifest projection only.
+ */
+/** @typedef {{ pageKey: string, locale: string }} PageIdentity */
+/** @typedef {{
+ *   identity: PageIdentity,
+ *   sourcePath: string,
+ *   route?: string | null,
+ *   anchors?: string[],
+ * }} PageRecord */
+/** @typedef {{
+ *   id: string,
+ *   sourceRoot: string,
+ *   pageKeys: string[],
+ * }} DocumentCollection */
+/** @typedef {{
+ *   collectionId: string,
+ *   routeBase: string,
+ *   mode: 'integrated' | 'standalone',
+ * }} DocumentMount */
+/** @typedef {{
+ *   code: string,
+ *   severity: 'error' | 'warning',
+ *   message: string,
+ *   path?: string,
+ * }} DocumentDiagnostic */
+/** @typedef {{
+ *   schema: typeof DOCUMENT_MANIFEST_SCHEMA,
+ *   root: string,
+ *   defaultLocale: string | null,
+ *   locales: string[],
+ *   localeLabels: Record<string, string>,
+ *   collections: DocumentCollection[],
+ *   mounts: DocumentMount[],
+ *   pages: PageRecord[],
+ *   diagnostics: DocumentDiagnostic[],
+ * }} DocumentManifest */
+export const DOCUMENT_MANIFEST_SCHEMA = 'vmz.document.manifest.v0';
+/** Static page view fragment (D1) — not a Doc IR. */
+export const DOCUMENT_VIEW_SCHEMA = 'vmz.document.view.v0';
+/** D2 evidence projection (fences + API refs) — not a Doc IR. */
+export const DOCUMENT_EVIDENCE_SCHEMA = 'vmz.document.evidence.v0';
+/** D3 search index (SearchRecord[]) — not a Doc IR. */
+export const DOCUMENT_SEARCH_SCHEMA = 'vmz.document.search.v0';
+/** D3 island-only resume plan for search/playground — not a Doc IR. */
+export const DOCUMENT_ISLANDS_SCHEMA = 'vmz.document.islands.v0';
+/** Top-level non-locale reserved names under /documents */
+export const DOCUMENT_RESERVED_TOP = new Set(['package.json', 'documents.config.ts', 'documents.config.json', 'documents.config.js', 'public']);
+/** Known locale aliases → canonical key (lowercase, hyphen). */
+export const LOCALE_ALIASES = {
+    'zh-cn': 'zh-hans',
+    'zh-sg': 'zh-hans',
+    'zh-tw': 'zh-hant',
+    'zh-hk': 'zh-hant',
+    'zh-mo': 'zh-hant',
+};
+export const DIAG = {
+    LOCALE_INVALID: 'document::locale::invalid',
+    LOCALE_CASE: 'document::locale::case',
+    LOCALE_SEPARATOR: 'document::locale::separator',
+    LOCALE_CONFLICT: 'document::locale::conflict',
+    LOCALE_MISSING_DEFAULT: 'document::locale::missing_default',
+    LOCALE_MISSING_PAGE: 'document::locale::missing_page',
+    LOCALE_ORPHAN_PAGE: 'document::locale::orphan_page',
+    LAYOUT_ILLEGAL_TOP: 'document::layout::illegal_top',
+    LAYOUT_MISSING_DOCUMENTS: 'document::layout::missing_documents',
+    CONFIG_MISSING: 'document::config::missing',
+    CONFIG_INVALID: 'document::config::invalid',
+    CONFIG_DEFAULT_LOCALE: 'document::config::default_locale',
+    FALLBACK_SILENT: 'document::fallback::silent_forbidden',
+    PAGE_DUPLICATE: 'document::page::duplicate',
+    LINK_BROKEN: 'document::link::broken',
+    LINK_AMBIGUOUS: 'document::link::ambiguous',
+    ANCHOR_MISSING: 'document::anchor::missing',
+    ANCHOR_DUPLICATE: 'document::anchor::duplicate',
+    ROUTE_DUPLICATE: 'document::route::duplicate',
+    NAV_EMPTY: 'document::nav::empty',
+    FENCE_CHECK: 'document::fence::check_failed',
+    FENCE_UNSUPPORTED: 'document::fence::unsupported',
+    FENCE_SOURCE_MISSING: 'document::fence::source_missing',
+    FENCE_RUN_FAILED: 'document::fence::run_failed',
+    API_MISSING: 'document::api::missing',
+    API_AMBIGUOUS: 'document::api::ambiguous',
+};

package/dist/explain-cmd.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @param {string[]} argv
+ * @returns {number}
+ */
+export declare function cmdExplain(argv: any): 0 | 1;

package/dist/explain-cmd.js

@@ -0,0 +1,123 @@
+// @ts-nocheck
+/**
+ * `vmz explain` — DX causal explain queries (doc 21).
+ *
+ * @param {string[]} argv args after `explain`
+ */
+import { createWorkspace } from './index.js';
+import { log } from './log.js';
+import { resolveWorkspaceDirs } from './resolve.js';
+/**
+ * @param {string[]} argv
+ * @returns {number}
+ */
+export function cmdExplain(argv) {
+    const args = parse(argv);
+    if (args.help || args._[0] === 'help') {
+        printHelp();
+        return 0;
+    }
+    let target;
+    let pathArg = '.';
+    if (args._[0] === 'style') {
+        const node = args._[1];
+        if (!node) {
+            log.error('usage: vmz explain style <node> [path]');
+            return 1;
+        }
+        target = `style:${node}`;
+        pathArg = args._[2] ?? args.path ?? '.';
+    }
+    else if (args._[0]) {
+        target = String(args._[0]);
+        pathArg = args._[1] ?? args.path ?? '.';
+    }
+    else if (args.target) {
+        target = String(args.target);
+        pathArg = args.path ?? '.';
+    }
+    else {
+        printHelp();
+        return 1;
+    }
+    const { project, outDir } = resolveWorkspaceDirs({
+        path: String(pathArg),
+        outDir: args['out-dir'] ?? 'dist',
+    });
+    const ws = createWorkspace({ root: project, outDir });
+    if (typeof ws.explain !== 'function') {
+        log.error('Workspace.explain unavailable (rebuild N-API)');
+        return 1;
+    }
+    const raw = ws.explain(target);
+    if (args.json) {
+        console.log(raw);
+        return 0;
+    }
+    let doc;
+    try {
+        doc = JSON.parse(raw);
+    }
+    catch {
+        console.log(raw);
+        return 0;
+    }
+    console.log(`explain kind=${doc.kind} target=${doc.target}`);
+    if (doc.notes)
+        console.log(`notes: ${doc.notes}`);
+    const chain = Array.isArray(doc.chain) ? doc.chain : [];
+    for (const e of chain) {
+        const from = e.from ? `${e.from.kind}:${e.from.id}` : '?';
+        const to = e.to ? `${e.to.kind}:${e.to.id}` : '?';
+        console.log(`  ${from} -> ${to}  (${e.reason})`);
+    }
+    if (chain.length === 0) {
+        console.log('  (empty chain)');
+    }
+    return 0;
+}
+function printHelp() {
+    console.log(`vmz explain — causal explain (DX)
+
+Usage:
+  vmz explain style <node> [path]   Style Theme / style:tw / global styles
+  vmz explain <target> [path]       Generic Workspace.explain target
+
+Style nodes:
+  bg-action | colors.action | --vmz-colors-action
+  designs/styles/index.scss
+
+Options:
+  --json                 Print raw ExplainDocument JSON
+  --out-dir, -o <dir>    Dist directory (default: dist)
+`);
+}
+/**
+ * @param {string[]} argv
+ */
+function parse(argv) {
+    /** @type {Record<string, string | boolean> & { _: string[] }} */
+    const out = { _: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const eq = a.indexOf('=');
+            if (eq !== -1) {
+                out[a.slice(2, eq)] = a.slice(eq + 1);
+                continue;
+            }
+            const key = a.slice(2);
+            const next = argv[i + 1];
+            if (next && !next.startsWith('-') && key !== 'json' && key !== 'help') {
+                out[key] = next;
+                i += 1;
+            }
+            else {
+                out[key] = true;
+            }
+            continue;
+        }
+        out._.push(a);
+    }
+    return out;
+}