workq-mcp 0.1.0 → 0.1.1

package/lib/natural-git.mjs

@@ -0,0 +1,370 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const IGNORE_DIRS = new Set([
+  ".git",
+  ".next",
+  ".turbo",
+  ".workq",
+  ".gstack",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "output",
+  "playwright-report",
+  "test-results"
+]);
+
+const TEXT_EXTENSIONS = new Set([
+  ".bash",
+  ".c",
+  ".cc",
+  ".cjs",
+  ".cpp",
+  ".cs",
+  ".css",
+  ".go",
+  ".h",
+  ".hpp",
+  ".html",
+  ".java",
+  ".js",
+  ".json",
+  ".jsx",
+  ".kt",
+  ".mjs",
+  ".php",
+  ".py",
+  ".rb",
+  ".rs",
+  ".sh",
+  ".sql",
+  ".swift",
+  ".toml",
+  ".ts",
+  ".tsx",
+  ".xml",
+  ".yaml",
+  ".yml"
+]);
+
+const SECRET_LINE = /(api[_-]?key|secret|token|password|passwd|github_pat|ghp_|sk-[a-z0-9])/i;
+const MAX_FILE_BYTES = 420_000;
+const MAX_FILES = 700;
+
+function normalizePath(filePath) {
+  return filePath.split(path.sep).join("/");
+}
+
+function safeRead(filePath) {
+  try {
+    const stat = fs.statSync(filePath);
+    if (!stat.isFile() || stat.size > MAX_FILE_BYTES) return "";
+    return fs.readFileSync(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function shouldIgnoreDirectory(name) {
+  return IGNORE_DIRS.has(name) || /^\.workq[-_]/.test(name);
+}
+
+function walkRepository(rootDir) {
+  const files = [];
+  const stack = [rootDir];
+  while (stack.length && files.length < MAX_FILES) {
+    const current = stack.pop();
+    let entries = [];
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    entries.sort((a, b) => b.name.localeCompare(a.name));
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      const relativePath = normalizePath(path.relative(rootDir, fullPath));
+      if (entry.isDirectory()) {
+        if (!shouldIgnoreDirectory(entry.name)) stack.push(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const extension = path.extname(entry.name).toLowerCase();
+      if (!TEXT_EXTENSIONS.has(extension)) continue;
+      files.push(relativePath);
+      if (files.length >= MAX_FILES) break;
+    }
+  }
+  return files.sort();
+}
+
+function languageForExtension(extension) {
+  const map = {
+    ".bash": "Shell",
+    ".c": "C",
+    ".cc": "C++",
+    ".cjs": "CommonJS",
+    ".cpp": "C++",
+    ".cs": "C#",
+    ".css": "CSS",
+    ".go": "Go",
+    ".h": "C/C++ header",
+    ".hpp": "C++ header",
+    ".html": "HTML",
+    ".java": "Java",
+    ".js": "JavaScript",
+    ".json": "JSON",
+    ".jsx": "React JSX",
+    ".kt": "Kotlin",
+    ".mjs": "JavaScript module",
+    ".php": "PHP",
+    ".py": "Python",
+    ".rb": "Ruby",
+    ".rs": "Rust",
+    ".sh": "Shell",
+    ".sql": "SQL",
+    ".swift": "Swift",
+    ".toml": "TOML",
+    ".ts": "TypeScript",
+    ".tsx": "React TSX",
+    ".xml": "XML",
+    ".yaml": "YAML",
+    ".yml": "YAML"
+  };
+  return map[extension] ?? extension.replace(".", "").toUpperCase();
+}
+
+function docPathForSource(sourcePath) {
+  return `natural-git/code/${sourcePath.replace(/\//g, "__")}.md`;
+}
+
+function cleanLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed || SECRET_LINE.test(trimmed)) return "";
+  return trimmed;
+}
+
+function compact(value, maxLength = 220) {
+  const normalized = String(value ?? "").replace(/\s+/g, " ").trim();
+  if (normalized.length <= maxLength) return normalized;
+  return `${normalized.slice(0, maxLength - 3).trim()}...`;
+}
+
+function lineKind(line) {
+  if (/^(\/\/|#|\/\*|\*|<!--)/.test(line)) return "comment";
+  if (/^(import\s|from\s+|const\s+\w+\s*=\s*require\(|require\(|#include|using\s+|use\s+)/.test(line)) return "import";
+  if (/^(export\s|module\.exports|exports\.)/.test(line)) return "export";
+  if (/^(?:async\s+)?function\s+|^(?:export\s+)?(?:const|let|var)\s+\w+\s*=.*=>|^def\s+|^function\s+/.test(line)) return "function";
+  if (/^class\s+|^(?:export\s+)?class\s+|^(?:public\s+)?(?:final\s+)?class\s+/.test(line)) return "class";
+  if (/\bif\s*\(|^if\s+|^elif\s+|\belse\s+if\s*\(/.test(line)) return "if";
+  if (/\bfor\s*\(|^for\s+|\bwhile\s*\(|^while\s+/.test(line)) return "loop";
+  if (/\bswitch\s*\(|^match\s+/.test(line)) return "switch";
+  if (/\bcatch\s*\(|^except\s+/.test(line)) return "catch";
+  if (/^return\b/.test(line)) return "return";
+  if (/^throw\b|^raise\b/.test(line)) return "throw";
+  if (/^(const|let|var)\s+\w+\s*=|^[A-Za-z_$][\w$]*\s*=/.test(line)) return "assignment";
+  if (/\b(app|router)\.(get|post|put|patch|delete|use)\s*\(/i.test(line)) return "route";
+  if (/\.addEventListener\(/.test(line)) return "event";
+  if (/^SELECT\b|^INSERT\b|^UPDATE\b|^DELETE\b|^CREATE\b|^ALTER\b/i.test(line)) return "sql";
+  if (/^\{|\}|\]|\[|,$/.test(line)) return "structure";
+  return "statement";
+}
+
+function naturalSentenceForLine(line, lineNumber) {
+  const cleaned = cleanLine(line);
+  if (!cleaned) return "";
+  const text = compact(cleaned);
+  const kind = lineKind(cleaned);
+  if (kind === "comment") return `- ${lineNumber}행: 주석 \`${text}\`은 코드 작성자가 남긴 설명 또는 메모이다.`;
+  if (kind === "import") return `- ${lineNumber}행: \`${text}\` 구문으로 외부 모듈, 표준 라이브러리, 또는 다른 파일의 기능을 가져온다.`;
+  if (kind === "export") return `- ${lineNumber}행: \`${text}\` 구문으로 이 파일의 값을 다른 파일에서 사용할 수 있게 공개한다.`;
+  if (kind === "function") return `- ${lineNumber}행: \`${text}\` 형태의 함수 또는 콜백을 정의한다.`;
+  if (kind === "class") return `- ${lineNumber}행: \`${text}\` 형태의 클래스를 정의해 관련 상태와 동작을 객체 단위로 묶는다.`;
+  if (kind === "if") return `- ${lineNumber}행: 만약 \`${compact(cleaned.replace(/^else\s+/, ""))}\` 조건이 참이면 이어지는 블록의 동작을 실행한다.`;
+  if (kind === "loop") return `- ${lineNumber}행: \`${text}\` 반복 조건에 따라 여러 값 또는 여러 시도에 같은 처리를 반복한다.`;
+  if (kind === "switch") return `- ${lineNumber}행: \`${text}\` 값에 따라 여러 분기 중 하나의 흐름을 선택한다.`;
+  if (kind === "catch") return `- ${lineNumber}행: \`${text}\` 예외 흐름을 받아 실패 처리, 로깅, 복구 중 하나를 수행한다.`;
+  if (kind === "return") return `- ${lineNumber}행: \`${text}\` 값을 호출자에게 반환하고 현재 함수의 결과로 삼는다.`;
+  if (kind === "throw") return `- ${lineNumber}행: \`${text}\` 오류를 발생시켜 정상 흐름을 중단하고 실패 흐름으로 이동한다.`;
+  if (kind === "assignment") return `- ${lineNumber}행: \`${text}\` 값을 변수, 상수, 객체 속성, 또는 상태에 대입한다.`;
+  if (kind === "route") return `- ${lineNumber}행: \`${text}\` HTTP 라우트 또는 미들웨어를 등록해 요청이 들어왔을 때 실행될 처리를 연결한다.`;
+  if (kind === "event") return `- ${lineNumber}행: \`${text}\` 사용자 또는 브라우저 이벤트가 발생했을 때 실행될 동작을 연결한다.`;
+  if (kind === "sql") return `- ${lineNumber}행: \`${text}\` SQL 명령으로 데이터 조회, 생성, 수정, 삭제, 또는 스키마 변경을 수행한다.`;
+  if (kind === "structure") return `- ${lineNumber}행: \`${text}\` 문법 구조를 열거나 닫아 객체, 배열, 블록, 또는 설정 항목의 범위를 정한다.`;
+  return `- ${lineNumber}행: \`${text}\` 문장을 실행해 현재 파일의 동작, 설정, 화면, 데이터 처리 중 일부를 구성한다.`;
+}
+
+function extractStructure(lines) {
+  const functions = [];
+  const variables = [];
+  const conditions = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = cleanLine(lines[index]);
+    if (!line) continue;
+    const lineNumber = index + 1;
+    const fn = line.match(/(?:async\s+)?function\s+([A-Za-z_$][\w$]*)|def\s+([A-Za-z_][\w]*)|(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?\([^)]*\)\s*=>/);
+    if (fn) functions.push({ line: lineNumber, name: fn[1] || fn[2] || fn[3], signature: compact(line) });
+    const variable = line.match(/^(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/);
+    if (variable) variables.push({ line: lineNumber, name: variable[1], signature: compact(line) });
+    if (/\bif\s*\(|^if\s+|^elif\s+|\belse\s+if\s*\(|\bfor\s*\(|^for\s+|\bwhile\s*\(|^while\s+|\bcatch\s*\(|^except\s+/.test(line)) {
+      conditions.push({ line: lineNumber, signature: compact(line) });
+    }
+  }
+  return { functions, variables, conditions };
+}
+
+function packageJsonDoc(content) {
+  try {
+    const parsed = JSON.parse(content);
+    const scripts = Object.entries(parsed.scripts ?? {});
+    const deps = Object.keys(parsed.dependencies ?? {});
+    const devDeps = Object.keys(parsed.devDependencies ?? {});
+    return [
+      "## package.json 해석",
+      `- 패키지 이름: ${parsed.name ?? "정의 없음"}`,
+      scripts.length ? "### 실행 스크립트" : "",
+      ...scripts.map(([name, command]) => `- \`${name}\`: \`${command}\` 명령을 실행한다.`),
+      deps.length ? "### 런타임 의존성" : "",
+      deps.length ? `- ${deps.join(", ")}` : "",
+      devDeps.length ? "### 개발 의존성" : "",
+      devDeps.length ? `- ${devDeps.join(", ")}` : ""
+    ].filter(Boolean).join("\n");
+  } catch {
+    return "";
+  }
+}
+
+function sourceFileToDoc(file) {
+  const structure = extractStructure(file.lines);
+  const lineSpec = file.lines.map((line, index) => naturalSentenceForLine(line, index + 1)).filter(Boolean);
+  const purpose =
+    file.path === "package.json"
+      ? "패키지 이름, 실행 스크립트, 의존성, Node 런타임 조건을 정의한다."
+      : file.extension === ".css"
+        ? "화면 요소의 레이아웃, 색상, 반응형 배치, 상호작용 상태를 정의한다."
+        : file.extension === ".html"
+          ? "브라우저에 표시되는 정적 화면 구조와 연결된 스크립트/스타일 진입점을 정의한다."
+          : structure.functions.length
+            ? "함수 단위로 데이터를 계산하거나 화면/파일/네트워크 동작을 수행한다."
+            : "레포 동작을 구성하는 설정, 데이터, 또는 보조 텍스트를 제공한다.";
+  return [
+    `# ${file.path}`,
+    "",
+    "## 자연어 명세",
+    `이 파일은 ${file.language} 파일이다. ${purpose}`,
+    "",
+    "## 파일 정보",
+    `- 원본 경로: \`${file.path}\``,
+    `- 언어/형식: ${file.language}`,
+    `- 총 라인 수: ${file.lines.length}`,
+    `- 감지된 함수/메서드: ${structure.functions.length}개`,
+    `- 감지된 조건/반복/예외 흐름: ${structure.conditions.length}개`,
+    "",
+    structure.functions.length ? "## 함수와 메서드" : "",
+    ...structure.functions.map((item) => `- ${item.line}행: \`${item.name}\` 함수는 \`${item.signature}\` 형태로 정의된다.`),
+    "",
+    structure.variables.length ? "## 주요 변수와 상수" : "",
+    ...structure.variables.map((item) => `- ${item.line}행: \`${item.name}\` 값은 \`${item.signature}\` 구문으로 정의된다.`),
+    "",
+    structure.conditions.length ? "## 조건, 반복, 예외 흐름" : "",
+    ...structure.conditions.map((item) => `- ${item.line}행: 만약 또는 반복 조건 \`${item.signature}\`에 따라 실행 흐름이 달라진다.`),
+    "",
+    file.path === "package.json" ? packageJsonDoc(file.content) : "",
+    "",
+    "## 라인별 자연어 실행 흐름",
+    "이 섹션은 코드의 각 의미 있는 라인을 자연어 명세로 해석한다.",
+    ...lineSpec,
+    "",
+    "## 검증 관점",
+    "- 이 파일의 자연어 명세는 코드의 현재 구조를 해석한 것이다.",
+    "- 라인별 자연어 실행 흐름은 원본 코드의 의미 있는 모든 라인을 대상으로 한다.",
+    "- 제품 의도와 코드가 다를 수 있으므로, 코드에서 관찰된 동작은 승인된 제품 의도가 아니라 검증 근거로 취급한다.",
+    "- 리포트 분류 시 이 문서의 함수, 조건, 라우트, 이벤트 설명을 근거로 실제 구현 여부를 판단한다."
+  ].filter((line, index, array) => line || array[index - 1]).join("\n");
+}
+
+function overviewDoc({ projectKey, projectName, repository, root, sourceFiles }) {
+  const byLanguage = new Map();
+  for (const file of sourceFiles) byLanguage.set(file.language, (byLanguage.get(file.language) ?? 0) + 1);
+  return [
+    `# ${projectKey} 자연어 git 명세`,
+    "",
+    "## 의미",
+    "이 명세는 레포에 존재하는 코드 파일을 사람이 읽을 수 있는 자연어로 해석한 것이다. 함수, 변수, 조건, 반복, 라우트, 이벤트, 설정 파일, 의미 있는 코드 라인을 Markdown 문서로 풀어 쓰며, Work Q v2에서는 이 자연어 문서를 기준으로 리포트와 코드 변경을 판단한다.",
+    "",
+    "## 프로젝트",
+    `- 프로젝트 키: ${projectKey}`,
+    `- 프로젝트 이름: ${projectName || projectKey}`,
+    `- 레포: ${repository ? `${repository.owner}/${repository.repo}` : "연결된 레포 없음"}`,
+    `- 로컬 분석 경로: \`${root}\``,
+    `- 분석된 코드/설정 파일: ${sourceFiles.length}개`,
+    "",
+    "## 언어별 파일 수",
+    ...Array.from(byLanguage.entries()).map(([language, count]) => `- ${language}: ${count}개`),
+    "",
+    "## 운영 규칙",
+    "- 자연어 문서는 코드에서 관찰한 구조를 설명한다.",
+    "- 각 코드 파일 문서는 `라인별 자연어 실행 흐름` 섹션을 포함해야 한다.",
+    "- 코드의 현재 동작이 곧 제품 의도라는 뜻은 아니다.",
+    "- 오너가 자연어 커밋으로 승인한 내용만 다음 코드 변경의 기준이 된다.",
+    "- 코드가 바뀌면 이 자연어 git 명세도 다시 분석하거나 수정해야 한다."
+  ].join("\n");
+}
+
+function indexDoc(sourceFiles) {
+  return [
+    "# 코드 파일 자연어 색인",
+    "",
+    "이 문서는 분석된 파일과 각 파일의 자연어 명세 문서를 연결한다.",
+    "",
+    ...sourceFiles.map((file) => `- \`${file.path}\` -> \`${docPathForSource(file.path)}\``)
+  ].join("\n");
+}
+
+export function generateNaturalGitDocs({ localPath, projectKey, projectName = "", repository = null }) {
+  const root = path.resolve(localPath);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    throw new Error(`Local repository path does not exist or is not a directory: ${localPath}`);
+  }
+  const relativePaths = walkRepository(root);
+  const sourceFiles = relativePaths
+    .map((relativePath) => {
+      const extension = path.extname(relativePath).toLowerCase();
+      const absolutePath = path.join(root, relativePath);
+      const content = safeRead(absolutePath);
+      if (!content.trim()) return null;
+      return {
+        path: relativePath,
+        extension,
+        language: languageForExtension(extension),
+        content,
+        lines: content.split(/\r?\n/)
+      };
+    })
+    .filter(Boolean);
+  const docs = [
+    {
+      path: "natural-git/README.md",
+      title: "자연어 git 명세 개요",
+      content: overviewDoc({ projectKey, projectName, repository, root, sourceFiles })
+    },
+    {
+      path: "natural-git/code-index.md",
+      title: "코드 파일 자연어 색인",
+      content: indexDoc(sourceFiles)
+    },
+    ...sourceFiles.map((file) => ({
+      path: docPathForSource(file.path),
+      title: file.path,
+      content: sourceFileToDoc(file)
+    }))
+  ];
+  return {
+    root,
+    files_scanned: relativePaths.length,
+    code_files: sourceFiles.length,
+    docs
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workq-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Work Q MCP stdio bridge and local repository connection CLI.",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   },
   "files": [
     "bin/",
+    "lib/",
     "README.md"
   ],
   "engines": {