@zhhoceanfly/protoview 0.0.0-stage → 0.1.3

package/README.md

@@ -1,3 +1,51 @@
-# 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.
+# @zhhoceanfly/protoview
+
+ProtoView Client **CLI**：在浏览器里调试 gRPC / HTTP / SSE / WebSocket。适合 Rider 等无法安装 VS Code 扩展的 IDE。
+
+与 [Open VSX 扩展](https://open-vsx.org/extension/zoceanfly/protoview) 共用同一套 Client 页面与调用逻辑。
+
+## 安装
+
+```bash
+npm i -g @zhhoceanfly/protoview
+# 或
+npx @zhhoceanfly/protoview
+```
+
+需要 **Node.js 18+**。Git 来源需本机已安装 `git`。
+
+## 用法
+
+```bash
+protoview                       # 扫描当前目录 .proto，打开浏览器
+protoview --proto ./api         # 指定目录
+protoview --git https://github.com/org/repo.git --branch main
+protoview --port 3920 --no-open
+```
+
+默认地址：`http://127.0.0.1:3920/`
+
+环境配置保存在工作区目录下的 `.protoview/environments.json`。
+
+## 仓库内开发
+
+在 ProtoView 仓库根目录：
+
+```bash
+npm run dev:cli
+npm run dev:cli -- --proto ./api --port 3920
+```
+
+改 `client/` 后刷新浏览器；改 TypeScript 会自动编译并重启服务。正式发布仍用 `npm run build:cli`。
+
+## 与扩展的差异
+
+| | VS Code / Cursor 扩展 | 本 CLI |
+| --- | --- | --- |
+| Client 调试 | 有 | 有 |
+| 侧边栏 / 语言服务 | 有 | 无 |
+| 链路导入导出 | 系统对话框 | 浏览器下载 / 选文件 |
+
+## License
+
+MIT

package/bin/protoview.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+"use strict";
+require("../dist/cli.js");

package/dist/cli.js

@@ -0,0 +1,115 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const path = __importStar(require("path"));
+const server_1 = require("./server");
+function parseArgs(argv) {
+    const args = {
+        proto: process.cwd(),
+        git: "",
+        branch: "main",
+        port: 3920,
+        open: true,
+        showGoogle: false,
+        help: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "-h" || a === "--help")
+            args.help = true;
+        else if (a === "--proto" || a === "-p")
+            args.proto = path.resolve(argv[++i] || ".");
+        else if (a === "--git" || a === "-g")
+            args.git = argv[++i] || "";
+        else if (a === "--branch" || a === "-b")
+            args.branch = argv[++i] || "main";
+        else if (a === "--port")
+            args.port = Math.max(1, Number(argv[++i] || 3920) || 3920);
+        else if (a === "--no-open")
+            args.open = false;
+        else if (a === "--show-google")
+            args.showGoogle = true;
+        else if (!a.startsWith("-"))
+            args.proto = path.resolve(a);
+    }
+    return args;
+}
+function printHelp() {
+    console.log(`ProtoView Client CLI
+
+Usage:
+  protoview [options] [dir]
+
+Options:
+  --proto, -p <dir>     Scan .proto under directory (default: cwd)
+  --git, -g <url>       Use Git repo as proto source (clone to temp dir)
+  --branch, -b <name>   Git branch (default: main)
+  --port <n>            HTTP port (default: 3920)
+  --no-open             Do not open browser
+  --show-google         Include google.* packages in tree
+  -h, --help            Show help
+
+Examples:
+  protoview
+  protoview --proto ./api
+  protoview --git https://github.com/org/repo.git --branch main
+`);
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        printHelp();
+        return;
+    }
+    const publicDir = process.env.PROTOVIEW_PUBLIC_DIR
+        ? path.resolve(process.env.PROTOVIEW_PUBLIC_DIR)
+        : path.join(__dirname, "..", "public");
+    if (process.env.PROTOVIEW_DEV === "1") {
+        console.log(`[protoview] DEV publicDir=${publicDir}`);
+    }
+    await (0, server_1.startServer)({
+        publicDir,
+        workspaceRoot: args.proto,
+        port: args.port,
+        openBrowser: args.open,
+        showGoogle: args.showGoogle,
+        gitUrl: args.git,
+        gitBranch: args.branch,
+    });
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/dist/core/catalog.js

@@ -0,0 +1,493 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isWellKnownPackage = isWellKnownPackage;
+exports.buildCatalog = buildCatalog;
+exports.findSymbolAt = findSymbolAt;
+exports.findDefinitionAt = findDefinitionAt;
+const parser_1 = require("./parser");
+const SERVICE_RANK = {
+    ApiService: 0,
+    PublicService: 1,
+    InternalService: 2,
+};
+function isWellKnownPackage(name) {
+    return name === "google" || name.startsWith("google.");
+}
+function buildCatalog(files, errors = []) {
+    const byFile = new Map(files.map((file) => [normalize(file.path), file]));
+    const messagesByPkg = new Map();
+    const enumsByPkg = new Map();
+    for (const file of files) {
+        for (const message of (0, parser_1.flattenMessages)(file.messages)) {
+            push(messagesByPkg, file.package, { message, file });
+        }
+        for (const item of (0, parser_1.flattenEnums)(file.messages, file.enums)) {
+            push(enumsByPkg, file.package, { item, file });
+        }
+    }
+    const hits = new Map();
+    const addHit = (hit) => {
+        const key = `${hit.package}|${hit.fullName}`;
+        const list = hits.get(key) ?? [];
+        list.push(hit);
+        hits.set(key, list);
+    };
+    const draftMessages = [];
+    const draftEnums = [];
+    for (const [pkg, list] of messagesByPkg) {
+        const names = countNames(list.map((item) => item.message.fullName));
+        for (const { message, file } of list) {
+            const id = symbolId("msg", pkg, message.fullName, file.relPath, names.get(message.fullName) > 1);
+            addHit({ kind: "message", id, package: pkg, fullName: message.fullName, file: file.path });
+            draftMessages.push({
+                id,
+                package: pkg,
+                name: message.name,
+                fullName: message.fullName,
+                comment: message.comment,
+                file: file.path,
+                relPath: file.relPath,
+                line: message.loc.line,
+                endLine: message.loc.endLine,
+                fields: [],
+                nested: [
+                    ...message.nestedMessages.map((nested) => ({
+                        id: "",
+                        kind: "message",
+                        name: nested.fullName,
+                        comment: nested.comment,
+                    })),
+                    ...message.nestedEnums.map((nested) => ({
+                        id: "",
+                        kind: "enum",
+                        name: nested.fullName,
+                        comment: nested.comment,
+                    })),
+                ],
+                usages: [],
+            });
+        }
+    }
+    for (const [pkg, list] of enumsByPkg) {
+        const names = countNames(list.map((item) => item.item.fullName));
+        for (const { item, file } of list) {
+            const id = symbolId("enum", pkg, item.fullName, file.relPath, names.get(item.fullName) > 1);
+            addHit({ kind: "enum", id, package: pkg, fullName: item.fullName, file: file.path });
+            draftEnums.push({
+                id,
+                package: pkg,
+                name: item.name,
+                fullName: item.fullName,
+                comment: item.comment,
+                file: file.path,
+                relPath: file.relPath,
+                line: item.loc.line,
+                endLine: item.loc.endLine,
+                values: item.values.map((value) => ({
+                    name: value.name,
+                    number: value.number,
+                    comment: value.comment,
+                    line: value.loc.line,
+                })),
+                usages: [],
+            });
+        }
+    }
+    const messageById = new Map(draftMessages.map((item) => [item.id, item]));
+    const enumById = new Map(draftEnums.map((item) => [item.id, item]));
+    const resolve = (from, typeName, scope = "") => {
+        const raw = typeName.replace(/^\./, "");
+        if (!raw || (0, parser_1.isScalar)(raw) || raw.startsWith("map<"))
+            return undefined;
+        const parts = raw.split(".");
+        const pick = (list) => {
+            if (!list?.length)
+                return undefined;
+            return (list.find((hit) => normalize(hit.file) === normalize(from.path)) ??
+                list.find((hit) => imported(from, hit.file, files, byFile)) ??
+                list[0]);
+        };
+        if (scope && !typeName.startsWith(".")) {
+            const chain = scope.split(".");
+            for (let i = chain.length; i >= 1; i--) {
+                const nestedName = `${chain.slice(0, i).join(".")}.${raw}`;
+                const nested = pick(hits.get(`${from.package}|${nestedName}`));
+                if (nested)
+                    return nested;
+            }
+        }
+        const direct = pick(hits.get(`${from.package}|${raw}`));
+        if (direct)
+            return direct;
+        if (parts.length >= 2) {
+            for (let i = 1; i < parts.length; i++) {
+                const pkg = parts.slice(0, i).join(".");
+                const rest = parts.slice(i).join(".");
+                const found = pick(hits.get(`${pkg}|${rest}`));
+                if (found)
+                    return found;
+            }
+        }
+        for (const spec of from.imports) {
+            const importedFile = resolveImport(from, spec, files, byFile);
+            if (!importedFile)
+                continue;
+            const found = pick(hits.get(`${importedFile.package}|${raw}`))
+                ?? (parts.length >= 2 ? pick(hits.get(`${importedFile.package}|${parts[parts.length - 1]}`)) : undefined);
+            if (found && found.package === importedFile.package)
+                return found;
+        }
+        const short = parts[parts.length - 1];
+        const global = [...hits.values()].flat().filter((hit) => hit.fullName === short || hit.fullName.endsWith(`.${short}`));
+        const unique = new Map(global.map((hit) => [hit.id, hit]));
+        if (unique.size === 1)
+            return [...unique.values()][0];
+        return undefined;
+    };
+    const linkType = (from, typeName, scope = "") => {
+        const hit = resolve(from, typeName, scope);
+        return { text: typeName.replace(/^\./, ""), navId: hit?.id };
+    };
+    const toField = (from, field, scope, oneof) => ({
+        name: field.name,
+        number: field.number,
+        comment: field.comment,
+        line: field.loc.line,
+        file: from.path,
+        prefix: field.repeated ? "repeated" : field.optional ? "optional" : "",
+        key: field.mapKey ? linkType(from, field.mapKey, scope) : undefined,
+        value: linkType(from, field.mapValue ?? field.typeName, scope),
+        oneof,
+    });
+    const fileOfMessage = new Map();
+    for (const [pkg, list] of messagesByPkg) {
+        const names = countNames(list.map((item) => item.message.fullName));
+        for (const { message, file } of list) {
+            const id = symbolId("msg", pkg, message.fullName, file.relPath, names.get(message.fullName) > 1);
+            fileOfMessage.set(id, file);
+            const view = messageById.get(id);
+            if (!view)
+                continue;
+            view.fields = message.members.flatMap((member) => (member.kind === "field"
+                ? [toField(file, member.field, message.fullName)]
+                : member.oneof.fields.map((field) => toField(file, field, message.fullName, member.oneof.name))));
+            view.nested = view.nested.map((nested) => {
+                const hit = resolve(file, nested.name) ?? resolve(file, `${pkg}.${nested.name}`);
+                return { ...nested, id: hit?.id ?? "" };
+            });
+        }
+    }
+    const packages = new Map();
+    const ensurePkg = (name) => {
+        let pkg = packages.get(name);
+        if (!pkg) {
+            pkg = {
+                name,
+                id: `pkg:${name}`,
+                files: [],
+                services: [],
+                messages: [],
+                enums: [],
+                wellKnown: isWellKnownPackage(name),
+            };
+            packages.set(name, pkg);
+        }
+        return pkg;
+    };
+    for (const file of files) {
+        const pkg = ensurePkg(file.package);
+        pkg.files.push({ relPath: file.relPath, path: file.path });
+    }
+    for (const message of draftMessages)
+        ensurePkg(message.package).messages.push(message);
+    for (const item of draftEnums)
+        ensurePkg(item.package).enums.push(item);
+    const services = [];
+    const rpcs = [];
+    for (const file of files) {
+        const serviceNames = countNames(file.services.map((service) => service.name));
+        for (const service of file.services) {
+            const serviceId = symbolId("svc", file.package, service.name, file.relPath, (serviceNames.get(service.name) ?? 1) > 1 || sameServiceElsewhere(files, file, service));
+            const view = {
+                id: serviceId,
+                package: file.package,
+                name: service.name,
+                comment: service.comment,
+                file: file.path,
+                relPath: file.relPath,
+                line: service.loc.line,
+                endLine: service.loc.endLine,
+                rpcs: [],
+            };
+            for (const rpc of service.rpcs) {
+                const request = linkType(file, rpc.request);
+                const response = linkType(file, rpc.response);
+                const rpcView = {
+                    id: `${serviceId}:${rpc.name}:${rpc.loc.line}`,
+                    package: file.package,
+                    serviceId,
+                    service: service.name,
+                    name: rpc.name,
+                    comment: rpc.comment,
+                    file: file.path,
+                    relPath: file.relPath,
+                    line: rpc.loc.line,
+                    endLine: rpc.loc.endLine,
+                    request,
+                    response,
+                    requestStream: rpc.requestStream,
+                    responseStream: rpc.responseStream,
+                    httpVerb: rpc.httpVerb,
+                    httpPath: rpc.httpPath,
+                    httpBody: rpc.httpBody,
+                    timeout: rpc.timeout,
+                    auth: rpc.auth,
+                    closed: rpc.closed,
+                    badges: rpc.badges,
+                    source: rpc.source,
+                    requestMessageId: request.navId,
+                    responseMessageId: response.navId,
+                };
+                view.rpcs.push(rpcView);
+                rpcs.push(rpcView);
+                addUsage(messageById, request.navId, {
+                    navId: rpcView.id,
+                    label: `${service.name}.${rpc.name}`,
+                    detail: "请求",
+                });
+                addUsage(messageById, response.navId, {
+                    navId: rpcView.id,
+                    label: `${service.name}.${rpc.name}`,
+                    detail: "响应",
+                });
+            }
+            services.push(view);
+            ensurePkg(file.package).services.push(view);
+        }
+    }
+    for (const message of draftMessages) {
+        const file = fileOfMessage.get(message.id);
+        if (!file)
+            continue;
+        for (const field of message.fields) {
+            for (const type of [field.key, field.value]) {
+                if (!type?.navId)
+                    continue;
+                const usage = {
+                    navId: message.id,
+                    label: `${message.fullName}.${field.name}`,
+                    detail: "字段",
+                };
+                addUsage(messageById, type.navId, usage);
+                addUsage(enumById, type.navId, usage);
+            }
+        }
+    }
+    for (const pkg of packages.values()) {
+        pkg.files.sort((a, b) => a.relPath.localeCompare(b.relPath));
+        pkg.services.sort(compareService);
+        pkg.messages.sort((a, b) => a.fullName.localeCompare(b.fullName));
+        pkg.enums.sort((a, b) => a.fullName.localeCompare(b.fullName));
+    }
+    const byId = new Map();
+    const packageList = [...packages.values()].sort(comparePackage);
+    for (const pkg of packageList) {
+        byId.set(pkg.id, pkg);
+        for (const service of pkg.services) {
+            byId.set(service.id, service);
+            for (const rpc of service.rpcs)
+                byId.set(rpc.id, rpc);
+        }
+        for (const message of pkg.messages)
+            byId.set(message.id, message);
+        for (const item of pkg.enums)
+            byId.set(item.id, item);
+    }
+    return { packages: packageList, byId, errors };
+}
+function findSymbolAt(catalog, filePath, line) {
+    const target = normalize(filePath);
+    let best;
+    const consider = (id, file, start, end) => {
+        if (normalize(file) !== target || line < start || line > end)
+            return;
+        const span = Math.max(0, end - start);
+        if (!best || span < best.span)
+            best = { id, span };
+    };
+    for (const item of catalog.byId.values()) {
+        if ("messages" in item && "services" in item)
+            continue;
+        if ("fields" in item) {
+            consider(item.id, item.file, item.line, item.endLine);
+        }
+        else if ("values" in item) {
+            consider(item.id, item.file, item.line, item.endLine);
+        }
+        else if ("rpcs" in item) {
+            consider(item.id, item.file, item.line, item.endLine);
+            for (const rpc of item.rpcs)
+                consider(rpc.id, rpc.file, rpc.line, rpc.endLine);
+        }
+    }
+    return best?.id;
+}
+/** Resolve go-to-definition for the identifier under cursor (type / rpc / service / enum). */
+function findDefinitionAt(catalog, filePath, line, word) {
+    const token = word.replace(/^\./, "").trim();
+    if (!token)
+        return undefined;
+    const filePkg = packageOfFile(catalog, filePath);
+    for (const pkg of catalog.packages) {
+        for (const message of pkg.messages) {
+            for (const field of message.fields) {
+                if (normalize(message.file) !== normalize(filePath) || field.line !== line)
+                    continue;
+                for (const linked of [field.value, field.key]) {
+                    if (!linked?.navId)
+                        continue;
+                    if (linked.text === token || linked.text.endsWith(`.${token}`) || token.endsWith(`.${linked.text}`)) {
+                        const hit = catalog.byId.get(linked.navId);
+                        if (hit && "line" in hit && "file" in hit)
+                            return { file: hit.file, line: hit.line };
+                    }
+                }
+            }
+        }
+        for (const service of pkg.services) {
+            for (const rpc of service.rpcs) {
+                if (normalize(rpc.file) !== normalize(filePath) || line < rpc.line || line > rpc.endLine)
+                    continue;
+                for (const linked of [rpc.request, rpc.response]) {
+                    if (!linked.navId)
+                        continue;
+                    if (linked.text === token || linked.text.endsWith(`.${token}`)) {
+                        const hit = catalog.byId.get(linked.navId);
+                        if (hit && "line" in hit && "file" in hit)
+                            return { file: hit.file, line: hit.line };
+                    }
+                }
+                if (rpc.name === token)
+                    return { file: rpc.file, line: rpc.line };
+            }
+            if (service.name === token && normalize(service.file) === normalize(filePath)) {
+                return { file: service.file, line: service.line };
+            }
+        }
+    }
+    const candidates = [];
+    for (const item of catalog.byId.values()) {
+        if ("messages" in item && "services" in item)
+            continue;
+        if (!("name" in item) || !("file" in item) || !("line" in item))
+            continue;
+        const name = "fullName" in item && typeof item.fullName === "string" ? item.fullName : item.name;
+        if (item.name !== token && name !== token && !name.endsWith(`.${token}`))
+            continue;
+        let score = 0;
+        if (item.name === token)
+            score += 2;
+        if ("package" in item && item.package === filePkg)
+            score += 3;
+        if (normalize(item.file) === normalize(filePath))
+            score += 1;
+        candidates.push({ loc: { file: item.file, line: item.line }, score });
+    }
+    candidates.sort((a, b) => b.score - a.score);
+    if (candidates[0])
+        return candidates[0].loc;
+    const enclosing = findSymbolAt(catalog, filePath, line);
+    if (!enclosing)
+        return undefined;
+    const hit = catalog.byId.get(enclosing);
+    if (hit && "file" in hit && "line" in hit)
+        return { file: hit.file, line: hit.line };
+    return undefined;
+}
+function packageOfFile(catalog, filePath) {
+    const target = normalize(filePath);
+    for (const pkg of catalog.packages) {
+        if (pkg.files.some((file) => normalize(file.path) === target))
+            return pkg.name;
+        for (const service of pkg.services) {
+            if (normalize(service.file) === target)
+                return pkg.name;
+        }
+    }
+    return undefined;
+}
+function addUsage(map, id, usage) {
+    if (!id)
+        return;
+    const target = map.get(id);
+    if (!target)
+        return;
+    if (target.usages.some((item) => item.navId === usage.navId && item.detail === usage.detail && item.label === usage.label)) {
+        return;
+    }
+    target.usages.push(usage);
+}
+function symbolId(kind, pkg, name, relPath, collision) {
+    const base = `${kind}:${pkg}:${name}`;
+    return collision ? `${base}:${relPath.replace(/\\/g, "/")}` : base;
+}
+function countNames(names) {
+    const map = new Map();
+    for (const name of names)
+        map.set(name, (map.get(name) ?? 0) + 1);
+    return map;
+}
+function sameServiceElsewhere(files, file, service) {
+    return files.some((other) => other !== file && other.package === file.package && other.services.some((item) => item.name === service.name));
+}
+function resolveImport(from, spec, files, byFile) {
+    const norm = spec.replace(/\\/g, "/");
+    const fromDir = from.path.replace(/\\/g, "/").split("/").slice(0, -1).join("/");
+    const joined = normalizePath(`${fromDir}/${norm}`);
+    const direct = byFile.get(normalize(joined));
+    if (direct)
+        return direct;
+    const matches = files.filter((file) => {
+        const rel = file.path.replace(/\\/g, "/");
+        return rel.endsWith(`/${norm}`) || rel.endsWith(norm);
+    });
+    if (matches.length === 1)
+        return matches[0];
+    return matches.find((file) => file.path.replace(/\\/g, "/").endsWith(`/${norm}`));
+}
+function imported(from, targetPath, files, byFile) {
+    return from.imports.some((spec) => {
+        const file = resolveImport(from, spec, files, byFile);
+        return file ? normalize(file.path) === normalize(targetPath) : false;
+    });
+}
+function compareService(a, b) {
+    const rank = (SERVICE_RANK[a.name] ?? 9) - (SERVICE_RANK[b.name] ?? 9);
+    if (rank !== 0)
+        return rank;
+    return a.name.localeCompare(b.name) || a.relPath.localeCompare(b.relPath);
+}
+function comparePackage(a, b) {
+    if (a.wellKnown !== b.wellKnown)
+        return a.wellKnown ? 1 : -1;
+    return a.name.localeCompare(b.name);
+}
+function push(map, key, value) {
+    const list = map.get(key) ?? [];
+    list.push(value);
+    map.set(key, list);
+}
+function normalize(filePath) {
+    return filePath.replace(/\\/g, "/").toLowerCase();
+}
+function normalizePath(filePath) {
+    const parts = [];
+    for (const part of filePath.replace(/\\/g, "/").split("/")) {
+        if (part === "..")
+            parts.pop();
+        else if (part && part !== ".")
+            parts.push(part);
+    }
+    return parts.join("/");
+}
+//# sourceMappingURL=catalog.js.map