@vmz/vmz 0.0.1 → 0.0.2

package/dist/plugin-host.js

@@ -0,0 +1,370 @@
+// @ts-nocheck
+/**
+ * Plugin protocol v1 helpers (N3) + typed config loading.
+ * Design: 瑙勫垝璁捐/vmz/14-Node-NAPI涓庢彃浠跺涓?md
+ */
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createJiti } from 'jiti';
+import { PLUGIN_PROTOCOL as PLUGIN_PROTOCOL_PKG, contentHash, defineConfig, definePlugin } from '@vmz/plugin';
+import { log } from './log.js';
+import { resolveWorkspacePackages } from './packages.js';
+export { contentHash, defineConfig, definePlugin };
+export const PLUGIN_PROTOCOL = PLUGIN_PROTOCOL_PKG;
+const CONFIG_NAMES = ['vmz.config.ts', 'vmz.config.mts', 'vmz.config.mjs', 'vmz.config.js'];
+const ROOT_PLUGIN_NAMES = ['vmz.plugin.ts', 'vmz.plugin.mts', 'vmz.plugin.mjs', 'vmz.plugin.js'];
+/**
+ * @param {string} full
+ * @returns {Promise<any>}
+ */
+export async function importMaybeTs(full) {
+    const ext = path.extname(full).toLowerCase();
+    if (ext === '.ts' || ext === '.mts') {
+        const jiti = createJiti(import.meta.url, {
+            interopDefault: true,
+            moduleCache: false,
+        });
+        return jiti(full);
+    }
+    const mod = await import(pathToFileURL(full).href);
+    return mod.default ?? mod;
+}
+/**
+ * Load `vmz.config.*` from project root (+ optional root `vmz.plugin.*`).
+ * @param {string} project
+ * @returns {Promise<{ plugins: import('@vmz/plugin').VmzPlugin[], engines: import('@vmz/plugin').VmzEngines, path: string | null, pluginPath: string | null }>}
+ */
+export async function loadVmzConfig(project) {
+    /** @type {import('@vmz/plugin').VmzPlugin[]} */
+    const plugins = [];
+    /** @type {import('@vmz/plugin').VmzEngines} */
+    let engines = {};
+    /** @type {string | null} */
+    let configPath = null;
+    /** @type {string | null} */
+    let pluginPath = null;
+    for (const name of CONFIG_NAMES) {
+        const full = path.join(project, name);
+        if (!existsSync(full))
+            continue;
+        configPath = full;
+        const cfg = await importMaybeTs(full);
+        const raw = cfg?.plugins ?? [];
+        engines = cfg?.engines && typeof cfg.engines === 'object' ? { ...cfg.engines } : {};
+        for (const entry of raw) {
+            plugins.push(await resolvePluginEntry(project, entry));
+        }
+        break;
+    }
+    for (const name of ROOT_PLUGIN_NAMES) {
+        const full = path.join(project, name);
+        if (!existsSync(full))
+            continue;
+        pluginPath = full;
+        plugins.push(await resolvePluginEntry(project, full));
+        break;
+    }
+    return { plugins, engines, path: configPath, pluginPath };
+}
+/**
+ * @param {string} project
+ * @param {string | import('@vmz/plugin').VmzPlugin | Promise<import('@vmz/plugin').VmzPlugin>} entry
+ */
+async function resolvePluginEntry(project, entry) {
+    let value = entry;
+    if (typeof value === 'string') {
+        const resolved = path.isAbsolute(value) ? value : path.join(project, value);
+        value = await importMaybeTs(resolved);
+        if (value && typeof value === 'object' && 'default' in value && value.default) {
+            value = value.default;
+        }
+    }
+    value = await value;
+    if (value?.manifest && (value.contribute || value.manifest.stages))
+        return value;
+    if (value?.name && value?.stages)
+        return definePlugin(value);
+    throw new Error(`invalid vmz plugin entry: ${String(entry)}`);
+}
+/**
+ * Collect + apply contribution batches for the given stages onto a Workspace.
+ * @param {import('../index.js').Workspace} workspace
+ * @param {import('@vmz/plugin').VmzPlugin[]} plugins
+ * @param {{ project: string, outDir: string, stages?: string[], engines?: import('@vmz/plugin').VmzEngines }} opts
+ */
+export async function applyPlugins(workspace, plugins, opts) {
+    const stages = opts.stages ?? ['workspace_resolve', 'source_adapter', 'analyzer', 'target'];
+    const packages = resolveWorkspacePackages(opts.project);
+    const engines = opts.engines ?? {};
+    /** @type {import('../index.js').ApplyContributionsReport[]} */
+    const reports = [];
+    /** @type {{ code: Set<string>, math: Set<string>, markdown: Set<string> }} */
+    const registered = {
+        code: new Set(),
+        math: new Set(),
+        markdown: new Set(),
+    };
+    for (const stage of stages) {
+        for (const plugin of plugins) {
+            if (!plugin.manifest.stages.includes(stage))
+                continue;
+            if (!plugin.contribute)
+                continue;
+            const ctx = {
+                project: opts.project,
+                outDir: opts.outDir,
+                stage,
+                protocol: PLUGIN_PROTOCOL,
+                packages,
+                engines,
+            };
+            const raw = await plugin.contribute(ctx);
+            const batches = Array.isArray(raw) ? raw : [raw];
+            for (const batch of batches) {
+                if (!batch || (batch.stage && batch.stage !== stage)) {
+                    if (batch?.stage && batch.stage !== stage)
+                        continue;
+                }
+                for (const item of batch.items ?? []) {
+                    noteEngineRegistration(registered, item);
+                }
+                const payload = {
+                    pluginName: plugin.manifest.name,
+                    pluginVersion: plugin.manifest.version,
+                    protocol: plugin.manifest.protocol ?? PLUGIN_PROTOCOL,
+                    stage: batch.stage ?? stage,
+                    cacheKey: batch.cacheKey ?? `${plugin.manifest.name}@${plugin.manifest.version}:${stage}`,
+                    deterministic: batch.deterministic ?? plugin.manifest.deterministic ?? true,
+                    items: (batch.items ?? []).map(normalizeItem),
+                };
+                const report = workspace.applyPluginContributions(payload);
+                reports.push(report);
+                if (report.rejected?.length) {
+                    for (const r of report.rejected) {
+                        log.warn(`plugin reject ${r.plugin}::${r.itemId}: ${r.reason}`);
+                    }
+                }
+                else {
+                    log.info(`plugin ${plugin.manifest.name} stage=${stage} accepted=${report.accepted}`);
+                }
+            }
+        }
+    }
+    if (registered.math.size || registered.code.size) {
+        const facadeReports = await materializeEngineFacades(workspace, opts.project, engines, registered);
+        reports.push(...facadeReports);
+    }
+    return reports;
+}
+/**
+ * Only math/code/markdown register interchangeable engines (see design doc 23 §1.1).
+ * @param {{ code: Set<string>, math: Set<string>, markdown: Set<string> }} registered
+ * @param {any} item
+ */
+function noteEngineRegistration(registered, item) {
+    const engine = item?.engine;
+    if (!engine || typeof engine !== 'string')
+        return;
+    const kind = item.engineKind ?? item.engine_kind;
+    if (kind === 'math')
+        registered.math.add(engine);
+    else if (kind === 'code')
+        registered.code.add(engine);
+    else if (kind === 'markdown')
+        registered.markdown.add(engine);
+}
+/**
+ * Host-generated facades from registered engines + config defaults.
+ * @param {import('../index.js').Workspace} workspace
+ * @param {string} project
+ * @param {import('@vmz/plugin').VmzEngines} engines
+ * @param {{ code: Set<string>, math: Set<string>, markdown: Set<string> }} registered
+ */
+async function materializeEngineFacades(workspace, project, engines, registered) {
+    /** @type {import('../index.js').ApplyContributionsReport[]} */
+    const reports = [];
+    const items = [];
+    if (registered.math.size) {
+        const defaultMath = pickDefault(engines.math, registered.math, 'katex');
+        const content = buildMathFacade(defaultMath, [...registered.math]);
+        items.push(sourceItem('facade-math', 'src/components/Math.vmz', content));
+    }
+    if (registered.code.size) {
+        const defaultCode = pickDefault(engines.code, registered.code, 'shiki');
+        const content = buildCodeFacade(defaultCode, [...registered.code]);
+        items.push(sourceItem('facade-code', 'src/components/Code.vmz', content));
+    }
+    if (registered.markdown.size) {
+        const defaultMd = pickDefault(engines.markdown, registered.markdown, 'markdown-it');
+        const content = buildMarkdownFacade(defaultMd, [...registered.markdown]);
+        items.push(sourceItem('facade-markdown', 'src/components/Markdown.vmz', content));
+    }
+    if (!items.length)
+        return reports;
+    const cacheKey = [
+        'engine-facades',
+        [...registered.math].sort().join(','),
+        [...registered.code].sort().join(','),
+        [...registered.markdown].sort().join(','),
+        engines.math ?? '',
+        engines.code ?? '',
+        engines.markdown ?? '',
+    ].join('|');
+    const report = workspace.applyPluginContributions({
+        pluginName: 'vmz:engine-facades',
+        pluginVersion: '0.1.0',
+        protocol: PLUGIN_PROTOCOL,
+        stage: 'workspace_resolve',
+        cacheKey,
+        deterministic: true,
+        items: items.map(normalizeItem),
+    });
+    reports.push(report);
+    if (report.rejected?.length) {
+        for (const r of report.rejected) {
+            log.warn(`plugin reject ${r.plugin}::${r.itemId}: ${r.reason}`);
+        }
+    }
+    else {
+        log.info(`plugin vmz:engine-facades stage=workspace_resolve accepted=${report.accepted}`);
+    }
+    return reports;
+}
+/**
+ * @param {string | undefined} configured
+ * @param {Set<string>} registered
+ * @param {string} preferred
+ */
+function pickDefault(configured, registered, preferred) {
+    if (configured && registered.has(configured))
+        return configured;
+    if (registered.has(preferred))
+        return preferred;
+    return [...registered][0];
+}
+/** @param {string} id @param {string} path @param {string} content */
+function sourceItem(id, path, content) {
+    return {
+        id,
+        kind: 'source',
+        path,
+        content,
+        contentHash: contentHash(content),
+        materialize: true,
+    };
+}
+/**
+ * @param {string} defaultEngine
+ * @param {string[]} engines
+ */
+function buildMathFacade(defaultEngine, engines) {
+    const defaultLit = JSON.stringify(defaultEngine);
+    const branches = engines
+        .map((eng, i) => {
+        const tag = engineToTag(eng);
+        const kw = i === 0 ? 'if' : 'else-if';
+        const engLit = JSON.stringify(eng);
+        return `  <${tag} ${kw}={(engine || ${defaultLit}) === ${engLit}} tex={tex} display={display} />`;
+    })
+        .join('\n');
+    return `<template>
+${branches}
+</template>
+
+<script client>
+export default class Math {
+  public tex: string = '';
+  public display: boolean = false;
+  public engine: string | null = null;
+}
+</script>
+`;
+}
+/**
+ * @param {string} defaultEngine
+ * @param {string[]} engines
+ */
+function buildCodeFacade(defaultEngine, engines) {
+    const defaultLit = JSON.stringify(defaultEngine);
+    const branches = engines
+        .map((eng, i) => {
+        const tag = engineToTag(eng);
+        const kw = i === 0 ? 'if' : 'else-if';
+        const engLit = JSON.stringify(eng);
+        return `  <${tag} ${kw}={(engine || ${defaultLit}) === ${engLit}} code={code} lang={lang} theme={theme} />`;
+    })
+        .join('\n');
+    return `<template>
+${branches}
+</template>
+
+<script client>
+export default class Code {
+  public code: string = '';
+  public lang: string = 'text';
+  public theme: string | null = null;
+  public engine: string | null = null;
+}
+</script>
+`;
+}
+/**
+ * @param {string} defaultEngine
+ * @param {string[]} engines
+ */
+function buildMarkdownFacade(defaultEngine, engines) {
+    const defaultLit = JSON.stringify(defaultEngine);
+    const branches = engines
+        .map((eng, i) => {
+        const tag = engineToTag(eng);
+        const kw = i === 0 ? 'if' : 'else-if';
+        const engLit = JSON.stringify(eng);
+        return `  <${tag} ${kw}={(engine || ${defaultLit}) === ${engLit}} source={source} />`;
+    })
+        .join('\n');
+    return `<template>
+${branches}
+</template>
+
+<script client>
+export default class Markdown {
+  public source: string = '';
+  public engine: string | null = null;
+}
+</script>
+`;
+}
+/** @param {string} engine */
+function engineToTag(engine) {
+    const map = {
+        katex: 'Katex',
+        mathjax: 'Mathjax',
+        shiki: 'Shiki',
+        'markdown-it': 'MarkdownIt',
+    };
+    if (map[engine])
+        return map[engine];
+    return engine
+        .split(/[-_]/)
+        .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+        .join('');
+}
+/** @param {any} item */
+function normalizeItem(item) {
+    return {
+        id: item.id,
+        kind: item.kind,
+        path: item.path,
+        content: item.content,
+        contentHash: item.contentHash ?? item.content_hash,
+        materialize: item.materialize,
+        severity: item.severity,
+        message: item.message,
+        code: item.code,
+        targetId: item.targetId ?? item.target_id,
+        targetKind: item.targetKind ?? item.target_kind ?? item.type,
+        manifestJson: item.manifestJson ?? item.manifest_json ?? (item.manifest != null ? JSON.stringify(item.manifest) : undefined),
+        detail: item.detail,
+    };
+}

package/dist/refactor-cmd.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `vmz refactor` — X1 RouteId/field safe rename (plan + atomic apply).
+ */
+/**
+ * @param {string[]} argv args after `refactor`
+ * @returns {Promise<number>}
+ */
+export declare function cmdRefactor(argv: any): Promise<0 | 1>;

package/dist/refactor-cmd.js

@@ -0,0 +1,156 @@
+// @ts-nocheck
+/**
+ * `vmz refactor` — X1 RouteId/field safe rename (plan + atomic apply).
+ */
+import { createWorkspace } from './index.js';
+import { log } from './log.js';
+import { resolveWorkspaceDirs } from './resolve.js';
+/**
+ * @param {string[]} argv args after `refactor`
+ * @returns {Promise<number>}
+ */
+export async function cmdRefactor(argv) {
+    const [sub, ...rest] = argv;
+    if (!sub || sub === 'help' || sub === '-h' || sub === '--help') {
+        printRefactorHelp();
+        return 0;
+    }
+    if (sub === 'rename') {
+        return cmdRename(rest);
+    }
+    log.error(`unknown refactor subcommand \`${sub}\``);
+    printRefactorHelp();
+    return 1;
+}
+function printRefactorHelp() {
+    console.log(`vmz refactor — workspace edit plans (X1)
+
+Usage:
+  vmz refactor rename --kind <route_id|field|method|component|capability> --from <id> --to <id> [path]
+                      [--scope <chunk>] [--json] [--apply] [--explain]
+
+Notes:
+  Returns WorkspaceEditPlan (\`vmz.dx.workspace_edit.v0\`).
+  route_id / field emit proven TextEdits; --apply writes atomically when status=ready.
+`);
+}
+/**
+ * @param {string[]} argv
+ */
+function parseRefactorArgs(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('-')) {
+                out[key] = next;
+                i += 1;
+            }
+            else {
+                out[key] = true;
+            }
+            continue;
+        }
+        out._.push(a);
+    }
+    return out;
+}
+/**
+ * @param {string[]} argv
+ */
+function cmdRename(argv) {
+    const args = parseRefactorArgs(argv);
+    const kind = typeof args.kind === 'string' ? args.kind : '';
+    const from = typeof args.from === 'string' ? args.from : '';
+    const to = typeof args.to === 'string' ? args.to : '';
+    const scope = typeof args.scope === 'string' ? args.scope : undefined;
+    const wantJson = args.json === true || typeof args.json === 'string';
+    const wantApply = args.apply === true;
+    const wantExplain = args.explain === true;
+    if (!kind || !from || !to) {
+        log.error('rename requires --kind, --from, and --to');
+        printRefactorHelp();
+        return 1;
+    }
+    const pathArg = args._[0] ?? '.';
+    const { project, outDir } = resolveWorkspaceDirs({
+        path: pathArg,
+        outDir: typeof args['out-dir'] === 'string' ? args['out-dir'] : undefined,
+    });
+    const intent = {
+        schema: 'vmz.dx.rename.v0',
+        kind,
+        from,
+        to,
+        ...(scope ? { scope } : {}),
+    };
+    const ws = createWorkspace({ root: project, outDir });
+    try {
+        if (typeof ws.planRename !== 'function') {
+            log.error('planRename missing on Workspace — rebuild native (`pnpm napi:build`)');
+            return 1;
+        }
+        let planRaw = ws.planRename(JSON.stringify(intent));
+        let plan;
+        try {
+            plan = JSON.parse(planRaw);
+        }
+        catch (e) {
+            log.error(`plan_rename not JSON: ${e}`);
+            return 1;
+        }
+        if (wantApply) {
+            if (typeof ws.applyWorkspaceEdit !== 'function') {
+                log.error('applyWorkspaceEdit missing — rebuild native (`pnpm napi:build`)');
+                return 1;
+            }
+            planRaw = ws.applyWorkspaceEdit(planRaw);
+            try {
+                plan = JSON.parse(planRaw);
+            }
+            catch (e) {
+                log.error(`apply_workspace_edit not JSON: ${e}`);
+                return 1;
+            }
+        }
+        if (wantExplain && typeof ws.explainRenameChain === 'function') {
+            const explainRaw = ws.explainRenameChain(JSON.stringify(intent));
+            if (wantJson) {
+                console.log(JSON.stringify({ plan, explain: JSON.parse(explainRaw) }, null, 2));
+                return plan.status === 'rejected' ? 1 : 0;
+            }
+            const explain = JSON.parse(explainRaw);
+            log.info(`explain chain edges=${(explain.chain || []).length}`);
+        }
+        if (wantJson) {
+            console.log(JSON.stringify(plan, null, 2));
+        }
+        else {
+            log.info(`rename ${kind} \`${from}\` → \`${to}\` → ${plan.status}`);
+            for (const p of plan.preconditions || []) {
+                console.log(`  precondition: ${p}`);
+            }
+            for (const e of plan.edits || []) {
+                console.log(`  edit ${e.path} @${e.start}..${e.end} → ${JSON.stringify(e.newText)}`);
+            }
+            for (const d of plan.diagnostics || []) {
+                console.log(`  ${d.severity || 'info'}: ${d.message}`);
+            }
+            if ((plan.edits || []).length === 0) {
+                console.log('  edits: (none)');
+            }
+        }
+        return plan.status === 'rejected' ? 1 : 0;
+    }
+    finally {
+        ws.dispose();
+    }
+}

package/dist/resolve.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared project path resolution for the Node CLI host (N2).
+ * Design: `规划设计/vmz/14-Node-NAPI与插件宿主.md`
+ */
+/**
+ * @param {string} startDir
+ * @returns {string | null}
+ */
+export declare function findPackageJson(startDir: any): string;
+/**
+ * Resolve project root + out dir from CLI args / cwd.
+ * Prefers an explicit path; otherwise walks up for package.json with `src/`.
+ *
+ * @param {{ cwd?: string, path?: string, outDir?: string }} opts
+ */
+export declare function resolveWorkspaceDirs(opts?: {}): {
+    project: string;
+    outDir: any;
+    cwd: any;
+};
+/**
+ * @param {string} projectRoot
+ * @returns {{ name?: string, private?: boolean } | null}
+ */
+export declare function readPackageMeta(projectRoot: any): any;

package/dist/resolve.js

@@ -0,0 +1,56 @@
+// @ts-nocheck
+/**
+ * Shared project path resolution for the Node CLI host (N2).
+ * Design: `规划设计/vmz/14-Node-NAPI与插件宿主.md`
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * @param {string} startDir
+ * @returns {string | null}
+ */
+export function findPackageJson(startDir) {
+    let dir = path.resolve(startDir);
+    for (;;) {
+        const candidate = path.join(dir, 'package.json');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Resolve project root + out dir from CLI args / cwd.
+ * Prefers an explicit path; otherwise walks up for package.json with `src/`.
+ *
+ * @param {{ cwd?: string, path?: string, outDir?: string }} opts
+ */
+export function resolveWorkspaceDirs(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const input = path.resolve(cwd, opts.path ?? '.');
+    let project = input;
+    if (!existsSync(path.join(project, 'src')) && !existsSync(path.join(project, 'package.json'))) {
+        const pkg = findPackageJson(cwd);
+        if (pkg)
+            project = path.dirname(pkg);
+    }
+    const outDir = opts.outDir ? (path.isAbsolute(opts.outDir) ? opts.outDir : path.join(project, opts.outDir)) : path.join(project, 'dist');
+    return { project, outDir, cwd };
+}
+/**
+ * @param {string} projectRoot
+ * @returns {{ name?: string, private?: boolean } | null}
+ */
+export function readPackageMeta(projectRoot) {
+    const pkgPath = path.join(projectRoot, 'package.json');
+    if (!existsSync(pkgPath))
+        return null;
+    try {
+        return JSON.parse(readFileSync(pkgPath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/test-cmd.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `vmz test` command 鈥?discovery / build / filter / TestReport orchestration.
+ * Semantics live in `@vmz/test`.
+ */
+/**
+ * @param {Record<string, string | boolean> & { _: string[] }} args
+ * @returns {Promise<number>}
+ */
+export declare function cmdTest(args: any): Promise<0 | 1 | 2>;