gx-code-agent 0.0.0-stage → 0.1.0

package/src/application/verifyWorkflow.js

@@ -0,0 +1,142 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { readJson } from "../store/localStore.js";
+import { stripKeepBlockContents } from "../domain/keepBlocks.js";
+
+const IGNORED_DIRS = new Set(["node_modules", ".git", "target", "build", "dist", "out", ".gx"]);
+const GENERATED_MARKERS = ["@generated GX-CODE", "[CN01-GENERATED]"];
+
+/**
+ * 递归收集目录下的文件。
+ *
+ * @param {string} dir
+ * @param {string[]} output
+ */
+function collectFiles(dir, output) {
+  if (!fs.existsSync(dir)) {
+    return;
+  }
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (IGNORED_DIRS.has(entry.name)) {
+      continue;
+    }
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      collectFiles(full, output);
+    } else if (entry.isFile()) {
+      output.push(full);
+    }
+  }
+}
+
+/**
+ * 检测 manifest 目录下带生成标记但未登记的文件。
+ *
+ * @param {string} dir
+ * @param {Set<string>} expected
+ * @returns {string[]}
+ */
+function findExtraGeneratedFiles(dir, expected) {
+  const directories = new Set();
+  for (const relative of expected) {
+    const parent = path.posix.dirname(relative);
+    if (parent && parent !== ".") {
+      directories.add(path.join(dir, parent));
+    }
+  }
+  const files = [];
+  for (const directory of directories) {
+    collectFiles(directory, files);
+  }
+  const extra = [];
+  for (const file of files) {
+    const relative = path.relative(dir, file).split(path.sep).join("/");
+    if (expected.has(relative)) {
+      continue;
+    }
+    const content = fs.readFileSync(file, "utf8");
+    if (GENERATED_MARKERS.some((marker) => content.includes(marker))) {
+      extra.push(relative);
+    }
+  }
+  return [...new Set(extra)].sort();
+}
+
+/**
+ * 计算文件 SHA-256；文件不存在时返回 null。
+ *
+ * @param {string} file
+ * @returns {string | null}
+ */
+function fileSha256(file) {
+  if (!fs.existsSync(file)) {
+    return null;
+  }
+  return createHash("sha256").update(stripKeepBlockContents(fs.readFileSync(file, "utf8"))).digest("hex");
+}
+
+/**
+ * 校验 manifest 与实际文件是否一致。
+ *
+ * @param {{ dir: string, manifestPath?: string }} input
+ * @returns {{ ok: boolean, drifted: string[], missing: string[], extra: string[], coverage: object }}
+ */
+export function verifyWorkflow({ dir, manifestPath = ".gx/manifest.json" }) {
+  const manifestFile = path.isAbsolute(manifestPath) ? manifestPath : path.join(dir, manifestPath);
+  const manifest = readJson(manifestFile, null);
+
+  if (!manifest || !Array.isArray(manifest.files)) {
+    return {
+      ok: true,
+      drifted: [],
+      missing: [],
+      extra: [],
+      coverage: {
+        status: "unknown",
+        facets: {
+          manifest: { available: false, reason: "manifest 不存在或格式不合法" },
+          files: { available: false, reason: "没有可校验的文件清单" },
+          compilation: { available: false, reason: "未执行编译" }
+        }
+      }
+    };
+  }
+
+  const drifted = [];
+  const missing = [];
+  for (const entry of manifest.files) {
+    if (!entry || typeof entry.path !== "string" || typeof entry.sha256 !== "string") {
+      continue;
+    }
+    const file = path.isAbsolute(entry.path) ? entry.path : path.join(dir, entry.path);
+    const actual = fileSha256(file);
+    if (actual === null) {
+      missing.push(entry.path);
+    } else if (actual !== entry.sha256) {
+      drifted.push(entry.path);
+    }
+  }
+
+  const expected = new Set(manifest.files
+    .filter((entry) => entry && typeof entry.path === "string")
+    .map((entry) => entry.path.replace(/\\/gu, "/")));
+  const extra = findExtraGeneratedFiles(dir, expected);
+
+  return {
+    ok: drifted.length === 0 && missing.length === 0 && extra.length === 0,
+    drifted,
+    missing,
+    extra,
+    coverage: {
+      status: "complete",
+      facets: {
+        manifest: { available: true },
+        files: { available: true },
+        extra_files: { available: true },
+        compilation: { available: false, reason: "未执行编译" }
+      }
+    }
+  };
+}

package/src/domain/canonicalJson.js

@@ -0,0 +1,72 @@
+/**
+ * 稳定 JSON 序列化。
+ *
+ * 规则与契约文档一致：
+ * - 对象 key 按 Unicode code point 排序；
+ * - 丢弃值为 undefined 的字段；
+ * - 数组保持原顺序；
+ * - 不接受函数、symbol、BigInt、NaN、Infinity；
+ * - 字符串不做 Unicode 归一化。
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function canonicalJson(value) {
+  return JSON.stringify(canonicalize(value));
+}
+
+/**
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+export function canonicalize(value) {
+  if (value === null) {
+    return null;
+  }
+  const type = typeof value;
+  if (type === "string" || type === "boolean") {
+    return value;
+  }
+  if (type === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError("Canonical JSON 不接受 NaN / Infinity");
+    }
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => canonicalize(item));
+  }
+  if (type === "object") {
+    /** @type {Record<string, unknown>} */
+    const output = {};
+    const keys = Object.keys(value).sort(compareCodePoints);
+    for (const key of keys) {
+      const item = /** @type {Record<string, unknown>} */ (value)[key];
+      if (item !== undefined) {
+        output[key] = canonicalize(item);
+      }
+    }
+    return output;
+  }
+  throw new TypeError(`Canonical JSON 不支持的类型：${type}`);
+}
+
+/**
+ * 按 Unicode code point 比较，避免 UTF-16 code unit 顺序带来的差异。
+ *
+ * @param {string} left
+ * @param {string} right
+ * @returns {number}
+ */
+export function compareCodePoints(left, right) {
+  const a = Array.from(left);
+  const b = Array.from(right);
+  const length = Math.min(a.length, b.length);
+  for (let i = 0; i < length; i += 1) {
+    const diff = a[i].codePointAt(0) - b[i].codePointAt(0);
+    if (diff !== 0) {
+      return diff;
+    }
+  }
+  return a.length - b.length;
+}

package/src/domain/chunker.js

@@ -0,0 +1,297 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { scanJavaChunks } from "./javaAst.js";
+
+const IGNORED_DIRS = new Set(["node_modules", ".git", "target", "build", "dist", "out", ".gx"]);
+const DEFAULT_SOURCE_DIRS = ["src/main/java", "src"];
+const JAVA_EXTENSIONS = new Set([".java"]);
+const FRONTEND_EXTENSIONS = new Set([".vue", ".ts", ".tsx", ".js", ".jsx"]);
+
+function hash(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function lineAt(content, index) {
+  return content.slice(0, index).split("\n").length;
+}
+
+function findMatching(content, openIndex, open = "{", close = "}") {
+  let depth = 0;
+  let quote = null;
+  let escaped = false;
+  let lineComment = false;
+  let blockComment = false;
+  for (let i = openIndex; i < content.length; i += 1) {
+    const char = content[i];
+    const next = content[i + 1];
+    if (lineComment) {
+      if (char === "\n") lineComment = false;
+      continue;
+    }
+    if (blockComment) {
+      if (char === "*" && next === "/") {
+        blockComment = false;
+        i += 1;
+      }
+      continue;
+    }
+    if (quote) {
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === quote) quote = null;
+      continue;
+    }
+    if (char === "/" && next === "/") {
+      lineComment = true;
+      i += 1;
+      continue;
+    }
+    if (char === "/" && next === "*") {
+      blockComment = true;
+      i += 1;
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      continue;
+    }
+    if (char === open) depth += 1;
+    else if (char === close) {
+      depth -= 1;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+function truncate(value, limit = 8000) {
+  return value.length > limit ? `${value.slice(0, limit)}\n/* ...truncated... */` : value;
+}
+
+function inferLayer(filePath, className) {
+  const haystack = `${filePath} ${className ?? ""}`.toLowerCase();
+  if (haystack.includes("controller")) return "controller";
+  if (haystack.includes("repository") || haystack.includes("dao")) return "repository";
+  if (haystack.includes("serviceimpl") || haystack.includes("service")) return "service";
+  if (haystack.includes("entity") || haystack.includes("model")) return "entity";
+  if (haystack.includes("dto") || haystack.includes("vo")) return "dto";
+  if (haystack.includes("hook") || haystack.includes("extension") || haystack.includes("ext")) return "extension";
+  if (haystack.includes("vue") || haystack.endsWith(".vue")) return "frontend";
+  return "unknown";
+}
+
+function frameworkTags(filePath) {
+  const extension = path.extname(filePath).toLowerCase();
+  const tags = [];
+  if (extension === ".java") tags.push("java", "spring");
+  if (extension === ".vue") tags.push("vue");
+  if (extension === ".ts" || extension === ".tsx") tags.push("typescript");
+  if (extension === ".js" || extension === ".jsx") tags.push("javascript");
+  return tags;
+}
+
+function annotationsBefore(content, index) {
+  const lines = content.slice(0, index).split("\n");
+  const annotations = [];
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    const match = line.match(/^@([\w$.]+)/u);
+    if (match) {
+      annotations.unshift(match[1]);
+      continue;
+    }
+    if (line.endsWith("*") || line.startsWith("*") || line.startsWith("//")) continue;
+    break;
+  }
+  return annotations;
+}
+
+function makeChunk({ planId, projectId, filePath, content, startLine, endLine, granularity, signature,
+                     className, methodName, annotations, intent = null }) {
+  const body = truncate(content);
+  return {
+    chunkId: `ck_${hash(`${projectId}|${filePath}|${granularity}|${startLine}|${endLine}|${body}`).slice(0, 32)}`,
+    projectId,
+    planId,
+    modelId: null,
+    path: filePath,
+    startLine,
+    endLine,
+    granularity,
+    signature,
+    className: className ?? null,
+    methodName: methodName ?? null,
+    layer: inferLayer(filePath, className),
+    annotations,
+    frameworkTags: frameworkTags(filePath),
+    intent,
+    contentHash: hash(body),
+    content: body,
+    embedding: null
+  };
+}
+
+function chunkJava({ planId, projectId, filePath, content }) {
+  const chunks = [];
+  const classRegex = /\b(?:class|interface|enum|record)\s+([A-Za-z_$][\w$]*)[^{]*\{/gu;
+  let classCount = 0;
+  for (const match of content.matchAll(classRegex)) {
+    const className = match[1];
+    const open = content.indexOf("{", match.index);
+    const close = findMatching(content, open);
+    if (close < 0) continue;
+    classCount += 1;
+    chunks.push(makeChunk({ planId, projectId, filePath,
+      content: content.slice(match.index, close + 1),
+      startLine: lineAt(content, match.index), endLine: lineAt(content, close),
+      granularity: "class", signature: className, className,
+      annotations: annotationsBefore(content, match.index) }));
+
+    const bodyStart = open + 1;
+    const body = content.slice(bodyStart, close);
+    const methodRegex = /(?:^|\n)([ \t]*(?:@[\w$.]+(?:\([^)]*\))?[ \t]*\n)*[ \t]*(?:(?:public|protected|private|static|final|abstract|synchronized|default|native|transient|volatile)\s+)*(?:<[^>]+>\s*)?[\w$.<>\[\],?]+\s+([A-Za-z_$][\w$]*)\s*\([^)]*\)[^{;]*\{)/gu;
+    for (const method of body.matchAll(methodRegex)) {
+      const methodOpen = bodyStart + method.index + method[0].lastIndexOf("{");
+      const methodClose = findMatching(content, methodOpen);
+      if (methodClose < 0) continue;
+      const methodName = method[2];
+      if (methodName === className) continue;
+      const methodText = content.slice(bodyStart + method.index, methodClose + 1);
+      const methodAnnotations = [...method[1].matchAll(/@([\w$.]+)/gu)].map((item) => item[1]);
+      const signatureOffset = method[1].lastIndexOf(methodName);
+      chunks.push(makeChunk({ planId, projectId, filePath, content: methodText,
+        startLine: lineAt(content, bodyStart + method.index + Math.max(0, signatureOffset)),
+        endLine: lineAt(content, methodClose),
+        granularity: "method", signature: `${className}.${methodName}()`, className, methodName,
+        annotations: methodAnnotations }));
+    }
+  }
+  if (classCount === 0) {
+    chunks.push(makeChunk({ planId, projectId, filePath, content,
+      startLine: 1, endLine: content.split("\n").length, granularity: "file", signature: path.basename(filePath),
+      annotations: annotationsBefore(content, 0) }));
+  }
+  return chunks;
+}
+
+function chunkJavaAst({ planId, projectId, filePath, content, astChunks }) {
+  const lines = content.split("\n");
+  const chunks = [];
+  for (const node of astChunks) {
+    const startLine = node.startLine;
+    const endLine = node.endLine;
+    const body = lines.slice(startLine - 1, endLine).join("\n");
+    if (!body.trim()) {
+      continue;
+    }
+    if (node.kind === "class") {
+      chunks.push(makeChunk({ planId, projectId, filePath, content: body, startLine, endLine,
+        granularity: "class", signature: node.className, className: node.className,
+        methodName: null, annotations: node.annotations }));
+    }
+    else if (node.kind === "method") {
+      const simpleClass = (node.className || "").split(".").pop();
+      if (!simpleClass || node.methodName === simpleClass) {
+        continue;
+      }
+      chunks.push(makeChunk({ planId, projectId, filePath, content: body, startLine, endLine,
+        granularity: "method", signature: `${node.className}.${node.methodName}()`,
+        className: node.className, methodName: node.methodName, annotations: node.annotations }));
+    }
+  }
+  return chunks;
+}
+
+function chunkVue({ planId, projectId, filePath, content }) {
+  const chunks = [];
+  const script = /<script[^>]*>([\s\S]*?)<\/script>/u.exec(content);
+  if (script) {
+    const startLine = lineAt(content, script.index);
+    chunks.push(makeChunk({ planId, projectId, filePath, content: script[1],
+      startLine, endLine: startLine + script[1].split("\n").length - 1, granularity: "class",
+      signature: "script", className: "script", annotations: [] }));
+  }
+  const template = /<template[^>]*>([\s\S]*?)<\/template>/u.exec(content);
+  if (template) {
+    const startLine = lineAt(content, template.index);
+    chunks.push(makeChunk({ planId, projectId, filePath, content: template[1],
+      startLine, endLine: startLine + template[1].split("\n").length - 1, granularity: "file",
+      signature: "template", annotations: [] }));
+  }
+  if (chunks.length === 0) {
+    chunks.push(makeChunk({ planId, projectId, filePath, content, startLine: 1,
+      endLine: content.split("\n").length, granularity: "file", signature: path.basename(filePath),
+      annotations: [] }));
+  }
+  return chunks;
+}
+
+function collectFiles(dir, output) {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (IGNORED_DIRS.has(entry.name)) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) collectFiles(full, output);
+    else if (entry.isFile()) output.push(full);
+  }
+}
+
+/**
+ * 生成 Java / Vue 源码切片。
+ *
+ * @param {{ dir: string, planId: string, projectId?: string, sourceDirs?: string[] }} input
+ * @returns {{ chunks: object[], filesScanned: number, coverage: object }}
+ */
+export function buildChunks({ dir, planId, projectId, sourceDirs = DEFAULT_SOURCE_DIRS }) {
+  const files = [];
+  for (const sourceDir of sourceDirs) {
+    const full = path.isAbsolute(sourceDir) ? sourceDir : path.join(dir, sourceDir);
+    collectFiles(full, files);
+  }
+  const uniqueFiles = [...new Set(files)].filter((file) => {
+    const extension = path.extname(file).toLowerCase();
+    return JAVA_EXTENSIONS.has(extension) || FRONTEND_EXTENSIONS.has(extension);
+  });
+  const javaFiles = uniqueFiles.filter((file) => JAVA_EXTENSIONS.has(path.extname(file).toLowerCase()));
+  const ast = scanJavaChunks({ files: javaFiles });
+  const astByFile = new Map();
+  for (const node of ast.chunks) {
+    const key = path.resolve(node.file);
+    const list = astByFile.get(key) ?? [];
+    list.push(node);
+    astByFile.set(key, list);
+  }
+  const chunks = [];
+  for (const file of uniqueFiles) {
+    const content = fs.readFileSync(file, "utf8");
+    const filePath = path.relative(dir, file).split(path.sep).join("/");
+    const extension = path.extname(file).toLowerCase();
+    const input = { planId, projectId: projectId ?? planId, filePath, content };
+    if (JAVA_EXTENSIONS.has(extension)) {
+      const astChunks = astByFile.get(path.resolve(file)) ?? [];
+      chunks.push(...(ast.available && astChunks.length > 0
+        ? chunkJavaAst({ ...input, astChunks })
+        : chunkJava(input)));
+    }
+    else {
+      chunks.push(...chunkVue(input));
+    }
+  }
+  return {
+    chunks,
+    filesScanned: uniqueFiles.length,
+    coverage: {
+      status: "partial",
+      facets: {
+        source_files: { available: uniqueFiles.length > 0 },
+        chunking: { available: true, engine: ast.available ? "ast" : "regex" },
+        ast: ast.available ? { available: true, reason: null }
+          : { available: false, reason: ast.reason },
+        embedding: { available: false, reason: "CLI 不上传向量；平台上报时按内容自动向量化" }
+      }
+    }
+  };
+}

package/src/domain/digest.js

@@ -0,0 +1,60 @@
+import { createHash } from "node:crypto";
+
+import { canonicalJson } from "./canonicalJson.js";
+
+/**
+ * 计算字符串的 SHA-256 小写 hex。
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+export function sha256Hex(value) {
+  return createHash("sha256").update(value, "utf8").digest("hex");
+}
+
+/**
+ * 计算任意 JSON 值的 canonical SHA-256。
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function sha256Canonical(value) {
+  return sha256Hex(canonicalJson(value));
+}
+
+/**
+ * Evidence ID：`ev_` + canonical(Evidence without evidenceId) 的 SHA-256。
+ *
+ * @param {Record<string, unknown>} evidenceWithoutId
+ * @returns {string}
+ */
+export function buildEvidenceId(evidenceWithoutId) {
+  return `ev_${sha256Canonical(evidenceWithoutId)}`;
+}
+
+/**
+ * Unknown ID：`unk_` + canonical({domain, question, scope}) 的 SHA-256。
+ *
+ * 问题文本会先做空白归一化，保证同一问题不同排版得到同一 ID。
+ *
+ * @param {{ domain: string, question: string, scope: unknown }} input
+ * @returns {string}
+ */
+export function buildUnknownId(input) {
+  const question = input.question.replace(/\s+/gu, " ").trim();
+  return `unk_${sha256Canonical({
+    domain: input.domain.trim(),
+    question,
+    scope: input.scope
+  })}`;
+}
+
+/**
+ * Manifest hash：`manifestHash` 字段之外的 canonical JSON 摘要。
+ *
+ * @param {Record<string, unknown>} manifestWithoutHash
+ * @returns {string}
+ */
+export function buildManifestHash(manifestWithoutHash) {
+  return sha256Canonical(manifestWithoutHash);
+}