@openqa-cn/codexqa 0.1.4

package/README.md

@@ -0,0 +1,142 @@
+# @openqa-cn/codexqa
+
+把本地或远程代码仓库解析成可查询的符号图：查函数怎么实现、谁在调用它、改一处会影响谁，也能搜报错、看架构 Wiki、用自然语言问仓库，或打开网页界面浏览。
+
+需要 **Node.js >= 18**。当前已发布 **macOS Apple Silicon** 安装包。
+
+```bash
+npm install -g @openqa-cn/codexqa --registry https://registry.npmjs.org/
+codexqa --help
+```
+
+命令找不到时，把 npm 全局 bin 加进 PATH：`export PATH="$(npm prefix -g)/bin:$PATH"`。Windows 常见位置是 `%AppData%\npm`。
+
+---
+
+## 能做什么
+
+| 你想做的事 | 用什么 |
+|---|---|
+| 给仓库建索引 | `codexqa index` |
+| 看仓库有多大、什么语言 | `codexqa stats` / `query summary` |
+| 某个函数怎么实现、谁调用它 | `query symbols` → `source` / `edges` |
+| 改这里会影响谁 | `query reach` |
+| 两个符号有没有关系 | `query path` |
+| 搜报错、注释、字符串 | `search-index` 之后 `query search` |
+| 用自然语言问仓库 | `codexqa chat`（需配置 LLM） |
+| 看架构说明 | `wiki` + `wiki embed` 之后 `query wiki` |
+| 打开网页界面 | `codexqa serve --open` |
+
+数据在本机 `~/.codexqa/`。卸载 CLI 不会删索引和会话：`npm uninstall -g @openqa-cn/codexqa` 或 `codexqa uninstall`。
+
+---
+
+## 快速开始
+
+先给仓库建索引（本地目录或 git URL）：
+
+```bash
+codexqa index /path/to/repo
+codexqa index https://github.com/org/repo.git
+codexqa index https://github.com/org/repo.git -b main
+```
+
+默认增量更新；`--full` 强制全量。看已索引的仓库：
+
+```bash
+codexqa repos
+codexqa stats /path/to/repo
+```
+
+`codexqa repos` 里的 `repo_id`（如 `github.com/org/repo@main`）可以原样传给后面的命令。本地路径、统一标识、都可以。
+
+---
+
+## 查符号和调用关系
+
+```bash
+# 按名字 / 前缀 / 文件路径找符号
+codexqa query --repo /path/to/repo symbols --name parse_file
+codexqa query --repo /path/to/repo symbols --name-prefix Repo
+codexqa query --repo /path/to/repo symbols --file-contains db/src
+
+# 看实现、调用它的人、它调用了谁
+codexqa query --repo /path/to/repo source --id <uuid>
+codexqa query --repo /path/to/repo edges --id <uuid> --direction in
+codexqa query --repo /path/to/repo edges --id <uuid> --direction out
+
+# 影响面（默认向内）；追调用链请显式 --direction out
+codexqa query --repo /path/to/repo reach --id <uuid> --direction in
+codexqa query --repo /path/to/repo reach --id <uuid> --direction out --depth 2
+
+# 两个符号之间有没有路径
+codexqa query --repo /path/to/repo path --from <uuid> --to <uuid>
+
+# 仓库概览、看某个节点
+codexqa query --repo /path/to/repo summary
+codexqa inspect <node-id> --repo /path/to/repo
+```
+
+`query` 输出 JSON，方便脚本接着处理。人读可以用 `repos` / `stats` / `inspect`。
+
+---
+
+## 全文检索
+
+索引之后再跑一次即可，之后 `index` 会自动维护：
+
+```bash
+codexqa search-index /path/to/repo
+codexqa query --repo /path/to/repo search --query "verify_jwt"
+```
+
+适合搜报错文案、中文注释、字符串。没有全文索引时，先用 `symbols` 或 `files`。
+
+---
+
+## 对话和网页
+
+```bash
+# 终端里问仓库（交互，或 -m 问一句就退出）
+codexqa chat /path/to/repo
+codexqa chat /path/to/repo -m "支付重试逻辑在哪？"
+codexqa chat /path/to/repo --session <id>
+
+# 浏览器里看文件、符号图、Wiki，以及同一套对话
+codexqa serve --open
+```
+
+`chat` 和网页共用会话，可以互相续上。对话和 Wiki 需要在 `~/.codexqa/config.toml` 里配置 LLM（只做索引和查询不用配）：
+
+```toml
+[llm]
+base_url = "https://api.openai.com/v1"
+api_key  = "sk-..."
+model    = "gpt-4o-mini"
+```
+
+改完配置后执行 `codexqa restart`。
+
+架构 Wiki（可选，会调用 LLM）：
+
+```bash
+codexqa wiki /path/to/repo
+codexqa wiki embed /path/to/repo
+codexqa query --repo /path/to/repo wiki --query "重试逻辑在哪里处理"
+```
+
+Wiki 重新生成后必须再跑一次 `wiki embed`。Wiki 是路由提示，以源码为准。
+
+---
+
+## 常用维护
+
+```bash
+codexqa status              # daemon 是否在跑
+codexqa stop
+codexqa restart             # 改完配置后要重启才生效
+codexqa delete /path/to/repo
+codexqa session list
+```
+
+完整子命令见 `codexqa --help` 和 `codexqa query --help`。

package/bin/codexqa.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// src/index.ts
+var { spawn } = require("node:child_process");
+var { argv, stderr, exit, platform, arch } = require("node:process");
+var PLATFORM_MAP = {
+  darwin: { arm64: "darwin-arm64", x64: "darwin-x64" },
+  linux: { arm64: "linux-arm64", x64: "linux-x64" },
+  win32: { x64: "win32-x64" }
+};
+function fail(msg) {
+  stderr.write(msg);
+  exit(1);
+  throw new Error("unreachable");
+}
+function resolveBinary() {
+  const suffix = PLATFORM_MAP[platform]?.[arch];
+  if (!suffix) {
+    fail(`codexqa: unsupported platform ${platform}-${arch}
+`);
+  }
+  const pkg = `@openqa-cn/codexqa-${suffix}`;
+  const binName = platform === "win32" ? "bin/codexqa.exe" : "bin/codexqa";
+  try {
+    return require.resolve(`${pkg}/${binName}`);
+  } catch {
+    fail(`codexqa: platform package ${pkg} not installed.
+` + `  try: npm install -g @openqa-cn/codexqa
+`);
+  }
+}
+var child = spawn(resolveBinary(), argv.slice(2), { stdio: "inherit" });
+child.on("exit", (code) => exit(code ?? 1));
+child.on("error", (err) => {
+  stderr.write(`codexqa: failed to launch binary: ${err.message}
+`);
+  exit(1);
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@openqa-cn/codexqa",
+  "version": "0.1.4",
+  "description": "把代码仓库解析成可查询的符号图：查实现、追调用、搜报错、看架构，也能对话或打开网页界面。",
+  "bin": {
+    "codexqa": "bin/codexqa.js"
+  },
+  "files": [
+    "bin"
+  ],
+  "optionalDependencies": {
+    "@openqa-cn/codexqa-darwin-arm64": "0.1.3",
+    "@openqa-cn/codexqa-darwin-x64": "0.1.3",
+    "@openqa-cn/codexqa-linux-x64": "0.1.3",
+    "@openqa-cn/codexqa-win32-x64": "0.1.3"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --format=cjs --target=node --outfile bin/codexqa.js && node -e \"const fs=require('fs');const p='bin/codexqa.js';const s=fs.readFileSync(p,'utf8');const out=s.replace(/^(#!.*\\n)+/,'');fs.writeFileSync(p,'#!/usr/bin/env node\\n'+out)\"",
+    "prepublishOnly": "bun run build",
+    "dev": "bun run src/index.ts",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "typescript": "^6.0",
+    "@types/bun": "latest",
+    "@types/node": "^22"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}