@taocompany/magic-grid-mcp 0.0.0-stage → 0.14.1

package/dist/validate/validateUsage.js

@@ -0,0 +1,342 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { collectSourceFiles } from '../scan/collectSourceFiles.js';
+import { findMagicGridBlocks, findStyleImports, } from '../scan/parseMagicGrid.js';
+import { checkPropTypeLiteral } from './propTypeLiteral.js';
+const RESERVED_COL_KEYS = new Set([
+    '__tree__',
+    '__index__',
+    '__selection__',
+    '__expand__',
+    '__group__',
+]);
+export function validateMagicGridUsage(resolved, options) {
+    const { manifest, source, manifestPath } = resolved;
+    const propNames = new Set(manifest.props.map((p) => p.name));
+    const emitNames = new Set((manifest.emits ?? []).map((e) => e.name));
+    const columnDefNames = new Set(manifest.columnDef.map((c) => c.name));
+    const propMistakes = new Map(manifest.commonMistakes.filter((m) => m.kind === 'prop').map((m) => [m.wrong, m.right]));
+    const errors = [];
+    const unchecked = [];
+    let checkable = 0;
+    let checked = 0;
+    const files = options.paths.flatMap((p) => collectSourceFiles(path.resolve(options.cwd ?? process.cwd(), p)));
+    for (const file of files) {
+        const rel = path.relative(options.cwd ?? process.cwd(), file);
+        const sourceText = fs.readFileSync(file, 'utf8');
+        checkCssImports(rel, sourceText, errors);
+        checkWrongSubpath(rel, sourceText, errors);
+        const blocks = findMagicGridBlocks(file, sourceText);
+        for (const block of blocks) {
+            const literalProps = new Map();
+            for (const attr of block.attrs) {
+                if (attr.name.startsWith('@')) {
+                    checkable++;
+                    const emitName = attr.name.slice(1);
+                    if (!emitNames.has(emitName)) {
+                        errors.push({
+                            file: rel,
+                            line: attr.line,
+                            rule: 'unknown-emit',
+                            severity: 'error',
+                            message: `未知 emit「@${emitName}」，不在 manifest 的 ${emitNames.size} 个事件内`,
+                        });
+                    }
+                    checked++;
+                    continue;
+                }
+                if (propMistakes.has(attr.name)) {
+                    const right = propMistakes.get(attr.name);
+                    errors.push({
+                        file: rel,
+                        line: attr.line,
+                        rule: 'wrong-field-name',
+                        severity: 'error',
+                        message: `${attr.name} 不是本库的 prop，应为 ${right}`,
+                        fix: { kind: 'rename-attr', from: attr.name, to: right },
+                    });
+                    checked++;
+                    continue;
+                }
+                if (attr.isBinding) {
+                    unchecked.push({
+                        reason: 'binding-not-literal',
+                        at: `${rel}:${attr.line}`,
+                        detail: `${attr.raw} 无法静态校验`,
+                    });
+                    continue;
+                }
+                if (checkPropTypeLiteral(rel, attr, errors)) {
+                    checked++;
+                    if (typeof attr.literalValue === 'string' || typeof attr.literalValue === 'boolean') {
+                        literalProps.set(resolvePropName(attr.name), attr);
+                    }
+                    continue;
+                }
+                if (attr.name === 'data' && attr.raw.includes('reactive(')) {
+                    errors.push({
+                        file: rel,
+                        line: attr.line,
+                        rule: 'reactive-data',
+                        severity: 'warning',
+                        message: 'data 不应传入 reactive() 深代理，请使用普通数组/对象',
+                    });
+                    checked++;
+                    continue;
+                }
+                if (attr.name === 'columns' && typeof attr.literalValue === 'string') {
+                    checkColumnsLiteral(rel, attr, columnDefNames, errors, unchecked);
+                    checked++;
+                    literalProps.set(resolvePropName(attr.name), attr);
+                    continue;
+                }
+                checkable++;
+                const propKey = resolvePropName(attr.name);
+                if (!propNames.has(propKey) && !isVueSpecialAttr(attr.name)) {
+                    errors.push({
+                        file: rel,
+                        line: attr.line,
+                        rule: 'unknown-prop',
+                        severity: 'error',
+                        message: `未知 prop「${attr.name}」，不在 manifest 的 ${propNames.size} 个运行时 props 内`,
+                    });
+                }
+                checked++;
+                if (typeof attr.literalValue === 'string' || typeof attr.literalValue === 'boolean') {
+                    literalProps.set(resolvePropName(attr.name), attr);
+                }
+            }
+            checkTreeRules(rel, block.line, literalProps, block.attrs, errors);
+        }
+        checkScriptHeuristics(rel, sourceText, errors, unchecked);
+    }
+    const coverage = checkable === 0 ? 1 : Math.min(1, checked / checkable);
+    const score = scoreResult(errors);
+    return {
+        libraryVersion: manifest.libraryVersion,
+        source,
+        manifestPath,
+        errors,
+        unchecked,
+        coverage,
+        score,
+    };
+}
+const VUE_SPECIAL_ATTRS = new Set([
+    'ref',
+    'key',
+    'class',
+    'style',
+    'is',
+]);
+function isVueSpecialAttr(name) {
+    return (name.startsWith('v-') ||
+        name.startsWith('@') ||
+        name.startsWith('#') ||
+        VUE_SPECIAL_ATTRS.has(name));
+}
+function resolvePropName(name) {
+    return name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+function checkCssImports(file, source, errors) {
+    const imports = findStyleImports(source);
+    const tokens = imports.find((i) => i.path.endsWith('tokens.css'));
+    const style = imports.find((i) => i.path.endsWith('style.css'));
+    if (style && !tokens) {
+        errors.push({
+            file,
+            line: style.line,
+            rule: 'missing-tokens-css',
+            severity: 'error',
+            message: '缺少 @taocompany/magic-grid/tokens.css，请先于 style.css 引入',
+            fix: { kind: 'add-import', to: '@taocompany/magic-grid/tokens.css' },
+        });
+    }
+    if (tokens && style && tokens.line > style.line) {
+        errors.push({
+            file,
+            line: style.line,
+            rule: 'css-order',
+            severity: 'error',
+            message: '应先引入 tokens.css，再引入 style.css',
+            fix: { kind: 'reorder-css' },
+        });
+    }
+}
+function checkWrongSubpath(file, source, errors) {
+    const wrong = /@taocompany\/magic-grid\/types\/(?!core|validation)/g;
+    let match;
+    const lines = source.split('\n');
+    while ((match = wrong.exec(source)) !== null) {
+        const line = source.slice(0, match.index).split('\n').length;
+        errors.push({
+            file,
+            line,
+            rule: 'wrong-subpath',
+            severity: 'error',
+            message: `子路径拼写错误：${match[0]}，类型请用 @taocompany/magic-grid/types/core`,
+            fix: { kind: 'fix-subpath', to: '@taocompany/magic-grid/types/core' },
+        });
+        void lines;
+    }
+}
+function checkColumnsLiteral(file, attr, columnDefNames, errors, unchecked) {
+    const value = attr.literalValue;
+    if (typeof value !== 'string' || !value.trim().startsWith('[')) {
+        unchecked.push({
+            reason: 'binding-not-literal',
+            at: `${file}:${attr.line}`,
+            detail: 'columns 非字面量数组，无法静态校验 ColumnDef',
+        });
+        return;
+    }
+    try {
+        const columns = new Function(`return (${value})`)();
+        if (!Array.isArray(columns)) {
+            return;
+        }
+        const keys = new Map();
+        const colMistakes = new Map([
+            ['field', 'prop'],
+            ['headerName', 'label'],
+            ['colId', 'key'],
+            ['valueFormatter', 'formatter'],
+        ]);
+        for (const col of columns) {
+            if (!col || typeof col !== 'object') {
+                continue;
+            }
+            for (const [wrong, right] of colMistakes) {
+                if (wrong in col) {
+                    errors.push({
+                        file,
+                        line: attr.line,
+                        rule: 'wrong-field-name',
+                        severity: 'error',
+                        message: `ColumnDef 字段 ${wrong} 应改为 ${right}`,
+                        fix: { kind: 'rename-field', from: wrong, to: right },
+                    });
+                }
+            }
+            for (const key of Object.keys(col)) {
+                if (columnDefNames.size > 0 && !columnDefNames.has(key) && !colMistakes.has(key)) {
+                    errors.push({
+                        file,
+                        line: attr.line,
+                        rule: 'columndef-unknown-field',
+                        severity: 'error',
+                        message: `ColumnDef 未知字段「${key}」`,
+                    });
+                }
+            }
+            const id = String(col.key ?? col.prop ?? '');
+            if (!col.prop && !col.key) {
+                errors.push({
+                    file,
+                    line: attr.line,
+                    rule: 'columndef-missing-key',
+                    severity: 'error',
+                    message: 'ColumnDef 需要 prop 或 key',
+                });
+            }
+            else if (id) {
+                keys.set(id, (keys.get(id) ?? 0) + 1);
+                if (RESERVED_COL_KEYS.has(id)) {
+                    errors.push({
+                        file,
+                        line: attr.line,
+                        rule: 'columndef-reserved-colid',
+                        severity: 'error',
+                        message: `列 key/prop 不能使用保留值 ${id}`,
+                    });
+                }
+            }
+        }
+        for (const [key, count] of keys) {
+            if (count > 1) {
+                errors.push({
+                    file,
+                    line: attr.line,
+                    rule: 'columndef-duplicate-key',
+                    severity: 'error',
+                    message: `重复的列 key/prop：${key}`,
+                });
+            }
+        }
+    }
+    catch {
+        unchecked.push({
+            reason: 'parse-error',
+            at: `${file}:${attr.line}`,
+            detail: 'columns 字面量无法解析为数组',
+        });
+    }
+}
+function checkTreeRules(file, blockLine, props, attrs, errors) {
+    const tree = props.get('tree');
+    const rowGrouping = props.get('rowGrouping');
+    const treeLazy = props.get('treeLazyLoad');
+    const getDataPath = props.get('getDataPath') ??
+        attrs.find((a) => resolvePropName(a.name) === 'getDataPath');
+    const loadTree = props.get('loadTreeChildren') ??
+        attrs.find((a) => resolvePropName(a.name) === 'loadTreeChildren');
+    const truthy = (attr) => attr?.literalValue === true || attr?.literalValue === 'true';
+    if (truthy(tree) && !getDataPath) {
+        errors.push({
+            file,
+            line: blockLine,
+            rule: 'tree-requires-getdatapath',
+            severity: 'error',
+            message: 'tree: true 时必须提供 getDataPath',
+        });
+    }
+    if (truthy(tree) && truthy(rowGrouping)) {
+        errors.push({
+            file,
+            line: blockLine,
+            rule: 'tree-vs-rowgrouping',
+            severity: 'error',
+            message: 'tree 与 rowGrouping 不能同时为 true',
+        });
+    }
+    if (truthy(treeLazy) && !loadTree) {
+        errors.push({
+            file,
+            line: blockLine,
+            rule: 'tree-lazy-requires-loader',
+            severity: 'error',
+            message: 'treeLazyLoad: true 时必须提供 loadTreeChildren',
+        });
+    }
+}
+function checkScriptHeuristics(file, source, errors, unchecked) {
+    const hasMove = /\b(moveRow|moveRows|moveUp|moveDown)\s*\(/.test(source);
+    const hasSortFilter = /\bsetSortModel\b/.test(source) ||
+        /\bsetFilterModel\b/.test(source) ||
+        /:defaultSort\b/.test(source) ||
+        /:sortable\s*=\s*["']?true/.test(source) ||
+        /:filterable\s*=\s*["']?true/.test(source);
+    if (hasMove && hasSortFilter) {
+        errors.push({
+            file,
+            line: 1,
+            rule: 'move-under-sort-filter',
+            severity: 'warning',
+            message: '检测到 move* 与排序/筛选启用信号；排序或筛选激活时 move* 可能静默失败（启发式）',
+        });
+        unchecked.push({
+            reason: 'behavior-out-of-scope',
+            at: file,
+            detail: 'move-under-sort-filter 为 script 启发式，未命中场景见 unchecked',
+        });
+    }
+}
+function scoreResult(errors) {
+    if (errors.some((e) => e.severity === 'error')) {
+        return 'fail';
+    }
+    if (errors.some((e) => e.severity === 'warning')) {
+        return 'pass-with-warnings';
+    }
+    return 'pass';
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@taocompany/magic-grid-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.14.1",
+  "description": "CLI and MCP tools for validating @taocompany/magic-grid usage",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "bin": {
+    "magic-grid-mcp": "./bin/magic-grid-mcp.js",
+    "mgc": "./bin/mgc.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:run": "vitest run"
+  },
+  "peerDependencies": {
+    "@taocompany/magic-grid": "0.14.1"
+  },
+  "peerDependenciesMeta": {
+    "@taocompany/magic-grid": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.12.0",
+    "@vue/compiler-sfc": "^3.5.40",
+    "zod": "3.24.0"
+  },
+  "devDependencies": {
+    "@taocompany/magic-grid": "workspace:*",
+    "@types/node": "^22.15.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.