workq-mcp 0.1.1 → 0.1.2

package/lib/natural-git.mjs

@@ -152,48 +152,138 @@ function compact(value, maxLength = 220) {
   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 unique(values, limit = 40) {
+  return Array.from(new Set(values.filter(Boolean))).slice(0, limit);
 }
 
-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}\` 문장을 실행해 현재 파일의 동작, 설정, 화면, 데이터 처리 중 일부를 구성한다.`;
+const NATURAL_SPEC_FORMAT_COMMENT = "<!-- workq-natural-spec-format: feature-v2 -->";
+
+function stripTags(value) {
+  return value.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim();
+}
+
+function extractVisibleTexts(file) {
+  const texts = [];
+  const markupContent = file.content.replace(/<script\b[\s\S]*?<\/script>/gi, "").replace(/<style\b[\s\S]*?<\/style>/gi, "");
+  if (file.extension === ".html") {
+    for (const match of file.content.matchAll(/<title[^>]*>([\s\S]*?)<\/title>/gi)) texts.push(stripTags(match[1]));
+    for (const match of markupContent.matchAll(/>([^<>{}][^<>{}]{1,80})</g)) texts.push(stripTags(match[1]));
+  }
+  for (const match of file.content.matchAll(/\b(?:textContent|innerText|placeholder|aria-label|title)\s*=\s*["'`]([^"'`]{1,100})["'`]/g)) {
+    texts.push(stripTags(match[1]));
+  }
+  for (const match of file.content.matchAll(/<button[^>]*>([\s\S]{1,160}?)<\/button>/gi)) {
+    texts.push(stripTags(match[1]));
+  }
+  return unique(texts.map((item) => compact(item, 100)).filter((item) => item && !/^[{}()[\];,.]+$/.test(item)), 18);
+}
+
+function extractDesignFacts(file) {
+  if (![".css", ".html", ".tsx", ".jsx"].includes(file.extension)) return [];
+  const facts = [];
+  const colors = unique(Array.from(file.content.matchAll(/#[0-9a-fA-F]{3,8}|rgba?\([^)]+\)|hsla?\([^)]+\)/g)).map((match) => match[0]), 10);
+  const gradients = unique(Array.from(file.content.matchAll(/linear-gradient\([^)]+\)/g)).map((match) => match[0]), 6);
+  const radii = unique(Array.from(file.content.matchAll(/border-radius\s*:\s*([^;]+);/g)).map((match) => match[1].trim()), 6);
+  const shadows = unique(Array.from(file.content.matchAll(/box-shadow\s*:\s*([^;]+);/g)).map((match) => match[1].trim()), 6);
+  const layout = [];
+  if (/display\s*:\s*grid/.test(file.content)) layout.push("grid");
+  if (/display\s*:\s*flex/.test(file.content)) layout.push("flex");
+  if (/min-height\s*:\s*100vh/.test(file.content)) layout.push("full viewport height");
+  if (/justify-content\s*:\s*center|align-items\s*:\s*center/.test(file.content)) layout.push("centered alignment");
+  if (colors.length) facts.push(`색상 팔레트는 ${colors.join(", ")} 값을 포함한다.`);
+  if (gradients.length) facts.push(`그라데이션 배경/강조는 ${gradients.join(", ")} 형태를 사용한다.`);
+  if (layout.length) facts.push(`레이아웃은 ${unique(layout).join(", ")} 배치를 사용한다.`);
+  if (radii.length) facts.push(`둥근 모서리 값은 ${radii.join(", ")} 등이 관찰된다.`);
+  if (shadows.length) facts.push(`그림자 표현은 ${shadows.slice(0, 3).join(", ")} 값을 사용한다.`);
+  if (/@keyframes\s+([A-Za-z0-9_-]+)/.test(file.content)) {
+    facts.push(`애니메이션은 ${unique(Array.from(file.content.matchAll(/@keyframes\s+([A-Za-z0-9_-]+)/g)).map((match) => match[1])).join(", ")} keyframes를 사용한다.`);
+  }
+  return facts;
+}
+
+function extractDataModelFacts(file) {
+  const facts = [];
+  const schemaMatch = file.content.match(/new\s+mongoose\.Schema\s*\(\s*\{([\s\S]*?)\}\s*\)/m);
+  if (schemaMatch) {
+    const fields = [];
+    for (const match of schemaMatch[1].matchAll(/^\s*([A-Za-z_$][\w$]*)\s*:\s*([^,\n]+)/gm)) {
+      fields.push(`${match[1]}(${compact(match[2], 80)})`);
+    }
+    facts.push(fields.length ? `이 파일은 데이터 모델 스키마를 정의하며 필드는 ${fields.join(", ")} 이다.` : "이 파일은 데이터 모델 스키마를 정의한다.");
+  }
+  if (file.path === "package.json") {
+    const packageDoc = packageJsonDoc(file.content).split(/\r?\n/).filter((line) => line.startsWith("- `") || line.startsWith("- 패키지 이름"));
+    facts.push(...packageDoc.slice(0, 12));
+  }
+  return facts;
+}
+
+function extractEnvironmentFacts(file) {
+  const envVars = unique(
+    Array.from(file.content.matchAll(/process\.env(?:\.([A-Za-z_][A-Za-z0-9_]*)|\[["'`]([^"'`]+)["'`]\])/g)).map((match) => match[1] || match[2]),
+    18
+  );
+  const facts = [];
+  if (!envVars.length && !/get(DataDir|DbDir|WorkDir|AppUrl)|isMcpConfigured|getMiniAiConfig|isGithubCrudConfigured|requireEnv/.test(file.content)) return facts;
+  if (envVars.length) facts.push(`환경 변수 ${envVars.map((item) => `\`${item}\``).join(", ")} 값을 읽어 런타임 설정을 결정한다.`);
+  if (/getDataDir|getDbDir|getWorkDir/.test(file.content)) facts.push("데이터 저장 위치, SQLite DB 위치, 작업 파일 위치를 환경 변수와 기본값으로 분리한다.");
+  if (/getAppUrl/.test(file.content)) facts.push("앱 외부 URL은 환경 변수로 지정하고, 없으면 로컬 개발 URL을 기본값으로 사용한다.");
+  if (/isMcpConfigured|WORKQ_MCP_TOKEN/.test(file.content)) facts.push("MCP 토큰 설정 여부를 판단해 로컬 에이전트 연결 가능 상태를 구분한다.");
+  if (/getMiniAiConfig|isMiniAiConfigured|WORKQ_MINI_AI/.test(file.content)) facts.push("Mini AI endpoint, model, API key 설정을 하나의 구성값으로 묶어 triage 사용 가능 여부를 판단한다.");
+  if (/isGithubCrudConfigured|WORKQ_GITHUB_TOKEN/.test(file.content)) facts.push("GitHub CRUD token 존재 여부로 GitHub 작업 자동화 가능성을 판단한다.");
+  if (/requireEnv/.test(file.content)) facts.push("필수 환경 변수가 없으면 조용히 진행하지 않고 명시적인 설정 오류를 발생시킨다.");
+  return unique(facts, 10);
+}
+
+function extractFunctionalFacts(file, structure) {
+  const facts = [];
+  const environmentFacts = extractEnvironmentFacts(file);
+  const visibleTexts = extractVisibleTexts(file);
+  const conditionSummaries = structure.conditions
+    .map((item) => item.expression ?? item.signature ?? "")
+    .filter((item) => item && item.length <= 180 && !/[<>]/.test(item))
+    .slice(0, 10);
+  facts.push(...environmentFacts);
+  if (visibleTexts.length) facts.push(`사용자에게 보이는 주요 문구는 ${visibleTexts.map((item) => `"${item}"`).join(", ")} 이다.`);
+  if (structure.events.length) {
+    facts.push(`사용자 이벤트는 ${structure.events.map((item) => `${item.target}의 ${item.event}`).join(", ")} 흐름을 처리한다.`);
+  }
+  if (!environmentFacts.length && structure.functions.length) {
+    facts.push(`내부 동작 단위는 ${structure.functions.slice(0, 8).map((item) => `${item.name}()`).join(", ")} 등이며, 세부 구현 근거는 코드 근거 섹션에서 추적한다.`);
+  }
+  if (structure.routes.length) {
+    facts.push(`네트워크/라우트 흐름은 ${structure.routes.slice(0, 8).map((item) => `${item.kind} ${item.expression}`).join(", ")} 로 연결된다.`);
+  }
+  if (!environmentFacts.length && conditionSummaries.length) {
+    facts.push(`분기와 반복은 ${conditionSummaries.join("; ")} 조건을 기준으로 동작한다.`);
+  }
+  if (/\bfor\s*\(\s*let\s+([A-Za-z_$][\w$]*)\s*=\s*(\d+)\s*;\s*\1\s*<=\s*(\d+)/.test(file.content)) {
+    const loop = file.content.match(/\bfor\s*\(\s*let\s+([A-Za-z_$][\w$]*)\s*=\s*(\d+)\s*;\s*\1\s*<=\s*(\d+)/);
+    facts.push(`반복문은 ${loop[2]}부터 ${loop[3]}까지의 선택지 또는 결과 행을 자동 생성한다.`);
+  }
+  if (/document\.createElement\(["']button["']\)/.test(file.content)) facts.push("버튼 요소를 코드에서 자동 생성한다.");
+  if (/classList\.add\(["']active["']\)|classList\.remove\(["']active["']\)/.test(file.content)) facts.push("선택 상태는 active 클래스로 표시하고 이전 선택은 해제한다.");
+  if (/innerHTML\s*=/.test(file.content)) facts.push("사용자 선택 이후 결과 영역의 HTML을 새 내용으로 교체한다.");
+  return facts;
+}
+
+function buildVerificationFacts(file, structure) {
+  const facts = [];
+  if (extractVisibleTexts(file).length) facts.push("화면에 노출되는 문구와 버튼이 의도한 사용자 흐름을 설명하는지 확인한다.");
+  if (structure.events.length) facts.push("사용자 이벤트 실행 후 화면 상태와 데이터가 기대값으로 바뀌는지 확인한다.");
+  if (structure.conditions.length) facts.push("반복/조건의 경계값과 예외 흐름을 테스트한다.");
+  if (extractDataModelFacts(file).length) facts.push("저장되는 필드 이름, 타입, 필수 여부가 실제 데이터와 맞는지 확인한다.");
+  if (!facts.length) facts.push("이 파일이 제공하는 설정 또는 보조 로직이 연결된 기능에서 실제로 사용되는지 확인한다.");
+  return facts;
+}
+
+function sourceEvidenceFacts(file, structure) {
+  const evidence = [];
+  if (structure.functions.length) evidence.push(`함수/메서드: ${structure.functions.slice(0, 12).map((item) => `${item.name}(${item.line}행)`).join(", ")}`);
+  if (structure.variables.length) evidence.push(`주요 값: ${structure.variables.slice(0, 12).map((item) => `${item.name}(${item.line}행)`).join(", ")}`);
+  if (structure.events.length) evidence.push(`이벤트: ${structure.events.slice(0, 12).map((item) => `${item.event}(${item.line}행)`).join(", ")}`);
+  if (structure.selectors.length) evidence.push(`스타일 선택자: ${structure.selectors.slice(0, 12).join(", ")}`);
+  return evidence;
 }
 
 function extractStructure(lines) {
@@ -237,11 +327,20 @@ function packageJsonDoc(content) {
 }
 
 function sourceFileToDoc(file) {
-  const structure = extractStructure(file.lines);
-  const lineSpec = file.lines.map((line, index) => naturalSentenceForLine(line, index + 1)).filter(Boolean);
+  const structure = {
+    imports: [],
+    exports: [],
+    classes: [],
+    routes: [],
+    events: [],
+    selectors: [],
+    ...extractStructure(file.lines)
+  };
   const purpose =
     file.path === "package.json"
       ? "패키지 이름, 실행 스크립트, 의존성, Node 런타임 조건을 정의한다."
+      : extractEnvironmentFacts(file).length
+        ? "런타임 환경 변수와 기본값을 해석해 저장소, URL, MCP, Mini AI, GitHub 연결 상태를 결정한다."
       : file.extension === ".css"
         ? "화면 요소의 레이아웃, 색상, 반응형 배치, 상호작용 상태를 정의한다."
         : file.extension === ".html"
@@ -249,39 +348,50 @@ function sourceFileToDoc(file) {
           : structure.functions.length
             ? "함수 단위로 데이터를 계산하거나 화면/파일/네트워크 동작을 수행한다."
             : "레포 동작을 구성하는 설정, 데이터, 또는 보조 텍스트를 제공한다.";
+  const dataModelFacts = extractDataModelFacts(file);
+  const functionalFacts = extractFunctionalFacts(file, structure);
+  const designFacts = extractDesignFacts(file);
+  const verificationFacts = buildVerificationFacts(file, structure);
+  const evidenceFacts = sourceEvidenceFacts(file, structure);
+  const coreRules = unique(
+    [
+      ...dataModelFacts,
+      ...extractEnvironmentFacts(file),
+      ...functionalFacts.filter((item) => /반복문|선택 상태|자동 생성|결과 영역|라우트|네트워크|분기/.test(item))
+    ],
+    12
+  );
   return [
     `# ${file.path}`,
+    NATURAL_SPEC_FORMAT_COMMENT,
     "",
-    "## 자연어 명세",
-    `이 파일은 ${file.language} 파일이다. ${purpose}`,
+    "## 기능 중심 자연어 명세",
+    `이 파일은 ${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}\` 형태로 정의된다.`),
+    functionalFacts.length ? "## 사용자 기능과 동작" : "",
+    ...functionalFacts.map((item) => `- ${item}`),
     "",
-    structure.variables.length ? "## 주요 변수와 상수" : "",
-    ...structure.variables.map((item) => `- ${item.line}행: \`${item.name}\` 값은 \`${item.signature}\` 구문으로 정의된다.`),
+    coreRules.length ? "## 핵심 규칙" : "",
+    ...coreRules.map((item) => `- ${item}`),
     "",
-    structure.conditions.length ? "## 조건, 반복, 예외 흐름" : "",
-    ...structure.conditions.map((item) => `- ${item.line}행: 만약 또는 반복 조건 \`${item.signature}\`에 따라 실행 흐름이 달라진다.`),
+    designFacts.length ? "## 화면과 디자인 명세" : "",
+    ...designFacts.map((item) => `- ${item}`),
     "",
-    file.path === "package.json" ? packageJsonDoc(file.content) : "",
+    dataModelFacts.length && file.path !== "package.json" ? "## 데이터와 상태" : "",
+    ...(file.path !== "package.json" ? dataModelFacts.map((item) => `- ${item}`) : []),
     "",
-    "## 라인별 자연어 실행 흐름",
-    "이 섹션은 코드의 각 의미 있는 라인을 자연어 명세로 해석한다.",
-    ...lineSpec,
+    evidenceFacts.length ? "## 코드 근거" : "",
+    ...evidenceFacts.map((item) => `- ${item}`),
     "",
     "## 검증 관점",
-    "- 이 파일의 자연어 명세는 코드의 현재 구조를 해석한 것이다.",
-    "- 라인별 자연어 실행 흐름은 원본 코드의 의미 있는 모든 라인을 대상으로 한다.",
+    ...verificationFacts.map((item) => `- ${item}`),
     "- 제품 의도와 코드가 다를 수 있으므로, 코드에서 관찰된 동작은 승인된 제품 의도가 아니라 검증 근거로 취급한다.",
-    "- 리포트 분류 시 이 문서의 함수, 조건, 라우트, 이벤트 설명을 근거로 실제 구현 여부를 판단한다."
+    "- 리포트 분류 시 이 문서는 기능 존재, 화면 동작, 입력/출력, 핵심 규칙의 근거로 사용한다."
   ].filter((line, index, array) => line || array[index - 1]).join("\n");
 }
 
@@ -290,9 +400,10 @@ function overviewDoc({ projectKey, projectName, repository, root, sourceFiles })
   for (const file of sourceFiles) byLanguage.set(file.language, (byLanguage.get(file.language) ?? 0) + 1);
   return [
     `# ${projectKey} 자연어 git 명세`,
+    NATURAL_SPEC_FORMAT_COMMENT,
     "",
     "## 의미",
-    "이 명세는 레포에 존재하는 코드 파일을 사람이 읽을 수 있는 자연어로 해석한 것이다. 함수, 변수, 조건, 반복, 라우트, 이벤트, 설정 파일, 의미 있는 코드 라인을 Markdown 문서로 풀어 쓰며, Work Q v2에서는 이 자연어 문서를 기준으로 리포트와 코드 변경을 판단한다.",
+    "이 명세는 레포에 존재하는 코드 파일을 제품 기능, 사용자 동작, 입력/출력, 화면/디자인, 데이터 규칙 중심의 자연어 Markdown 문서로 해석한 것이다. Work Q v2에서는 이 자연어 문서를 기준으로 리포트와 코드 변경을 판단한다.",
     "",
     "## 프로젝트",
     `- 프로젝트 키: ${projectKey}`,
@@ -305,8 +416,8 @@ function overviewDoc({ projectKey, projectName, repository, root, sourceFiles })
     ...Array.from(byLanguage.entries()).map(([language, count]) => `- ${language}: ${count}개`),
     "",
     "## 운영 규칙",
-    "- 자연어 문서는 코드에서 관찰한 구조를 설명한다.",
-    "- 각 코드 파일 문서는 `라인별 자연어 실행 흐름` 섹션을 포함해야 한다.",
+    "- 자연어 문서는 코드에서 관찰한 제품 기능과 검증 가능한 동작을 설명한다.",
+    "- 각 코드 파일 문서는 라인별 번역이 아니라 기능, 규칙, 화면, 데이터, 검증 관점 중심으로 작성한다.",
     "- 코드의 현재 동작이 곧 제품 의도라는 뜻은 아니다.",
     "- 오너가 자연어 커밋으로 승인한 내용만 다음 코드 변경의 기준이 된다.",
     "- 코드가 바뀌면 이 자연어 git 명세도 다시 분석하거나 수정해야 한다."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workq-mcp",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Work Q MCP stdio bridge and local repository connection CLI.",
   "type": "module",
   "bin": {