workq-mcp 0.1.5 → 0.1.6

package/README.md

@@ -67,9 +67,14 @@ cd /Users/jin/code/lotto
 workq natural-git --project-key LOTTO
 ```
 
-This command reads the local repository, creates `natural-git/README.md`,
-`natural-git/code-index.md`, and one `natural-git/code/*.md` document per
-code/config file, then imports those docs into the Work Q v2 natural-spec repo.
+This command reads the local repository and creates a hierarchical natural-spec
+repo: `natural-git/README.md`, `natural-git/source-index.md`, and feature
+directories such as `natural-git/features/.../README.md`,
+`natural-git/features/.../rules.md`, and
+`natural-git/features/.../verification.md`. API, CLI, runtime, data, and test
+evidence are grouped under `interfaces/`, `operations/`, `data/`, and
+`verification/`. The generated docs are then imported into the Work Q v2
+natural-spec repo.
 After that, open Work Q v2 and run `자연어 커밋 -> 명세 머지 -> 커밋 승인·Agent 큐`.
 Work Q creates a queued MCP work packet from the accepted natural commit. Your
 desktop Codex/Claude agent should claim that task, update the local repository,

package/lib/natural-git.mjs

@@ -136,10 +136,6 @@ function languageForExtension(extension) {
   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 "";
@@ -158,6 +154,31 @@ function unique(values, limit = 40) {
 
 const NATURAL_SPEC_FORMAT_COMMENT = "<!-- workq-natural-spec-format: feature-v2 -->";
 
+function slugSegment(value, fallback = "spec") {
+  return (
+    String(value ?? "")
+      .toLowerCase()
+      .replace(/\.[a-z0-9]+$/i, "")
+      .replace(/[^a-z0-9가-힣]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 72) || fallback
+  );
+}
+
+function sourcePathSlug(sourcePath) {
+  return slugSegment(sourcePath.replace(/\.[^.]+$/i, ""), "source");
+}
+
+function isTestFile(file) {
+  const normalized = file.path.toLowerCase();
+  const basename = path.basename(normalized);
+  return (
+    /(^|\/)(tests?|e2e|__tests__|spec)\//.test(normalized) ||
+    /\.(spec|test)\.[cm]?[jt]sx?$/.test(normalized) ||
+    /^test[_-]/.test(basename)
+  );
+}
+
 function stripTags(value) {
   return value.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim();
 }
@@ -178,6 +199,11 @@ function extractVisibleTexts(file) {
   return unique(texts.map((item) => compact(item, 100)).filter((item) => item && !/^[{}()[\];,.]+$/.test(item)), 18);
 }
 
+function primaryVisibleTitle(file) {
+  const texts = extractVisibleTexts(file);
+  return texts.find((item) => item.length >= 2 && item.length <= 40) ?? "";
+}
+
 function extractDesignFacts(file) {
   if (![".css", ".html", ".tsx", ".jsx"].includes(file.extension)) return [];
   const facts = [];
@@ -235,6 +261,63 @@ function isCliEntryFile(file) {
   );
 }
 
+function isApiOrServerFile(file) {
+  const normalized = file.path.toLowerCase();
+  return (
+    /(^|\/)(api|routes?|server|controllers?)\//.test(normalized) ||
+    /(^|\/)(server|route|router|api)\.[cm]?[jt]sx?$/.test(normalized) ||
+    /\b(app|router)\.(get|post|put|patch|delete|use)\s*\(/i.test(file.content)
+  );
+}
+
+function isDataModelFile(file) {
+  const normalized = file.path.toLowerCase();
+  return (
+    /(^|\/)(models?|schemas?|entities|migrations?)\//.test(normalized) ||
+    /(model|schema|entity)\.[cm]?[jt]sx?$/.test(normalized) ||
+    /new\s+mongoose\.Schema\s*\(/.test(file.content)
+  );
+}
+
+function isConfigurationFile(file) {
+  const normalized = file.path.toLowerCase();
+  const basename = path.basename(normalized);
+  return (
+    file.path === "package.json" ||
+    isEnvironmentConfigFile(file) ||
+    /(^|\/)(config|configs|scripts?|ci|\.github)\//.test(normalized) ||
+    /^(package-lock|pnpm-lock|yarn|tsconfig|next\.config|vite\.config|playwright\.config|dockerfile)/.test(basename)
+  );
+}
+
+function isUserFacingFile(file) {
+  const normalized = file.path.toLowerCase();
+  return (
+    [".html", ".css", ".jsx", ".tsx"].includes(file.extension) ||
+    extractVisibleTexts(file).length > 0 ||
+    /(^|\/)(app|pages|components|ui|views|screens)\//.test(normalized)
+  );
+}
+
+function hasImplementationLogic(file) {
+  return /(?:function\s+[A-Za-z_$][\w$]*|def\s+[A-Za-z_][\w]*|=>|\bfor\s*\(|\bif\s*\()/.test(file.content);
+}
+
+function specDirectoryForSource(file) {
+  if (isTestFile(file)) return `natural-git/verification/e2e/${sourcePathSlug(file.path)}`;
+  if (isCliEntryFile(file)) return `natural-git/interfaces/cli/${/\bworkq\s+/.test(file.content) ? "workq-cli" : sourcePathSlug(file.path)}`;
+  if (isApiOrServerFile(file)) return `natural-git/interfaces/api/${sourcePathSlug(file.path)}`;
+  if (isDataModelFile(file)) return `natural-git/data/models/${sourcePathSlug(file.path)}`;
+  if (isConfigurationFile(file)) {
+    if (file.path === "package.json") return "natural-git/operations/runtime/project-runtime";
+    if (isEnvironmentConfigFile(file)) return "natural-git/operations/runtime/runtime-environment";
+    return `natural-git/operations/configuration/${sourcePathSlug(file.path)}`;
+  }
+  if (isUserFacingFile(file)) return `natural-git/features/${slugSegment(primaryVisibleTitle(file) || file.path, sourcePathSlug(file.path))}`;
+  if (hasImplementationLogic(file)) return `natural-git/features/${sourcePathSlug(file.path)}`;
+  return `natural-git/supporting/${sourcePathSlug(file.path)}`;
+}
+
 function extractCliFacts(file) {
   if (!isCliEntryFile(file)) return [];
   const facts = [];
@@ -360,7 +443,113 @@ function packageJsonDoc(content) {
   }
 }
 
+function humanizeTestTitle(title) {
+  const normalized = title.replace(/\s+/g, " ").trim();
+  const known = [
+    [/regenerates legacy line-by-line natural specs on import/i, "예전 line-by-line 자연어 명세를 가져오면 기능 중심 명세로 재생성되는지 검증한다."],
+    [/registers a repo and turns its code into natural-language git specs/i, "새 프로젝트를 연결하고 로컬 코드 저장소를 자연어 명세 저장소로 변환하는 전체 흐름을 검증한다."],
+    [/bug report to desktop agent MCP completion flow/i, "버그 리포트가 MCP 작업 큐로 전달되고 데스크톱 에이전트 완료 처리까지 이어지는지 검증한다."],
+    [/project selector persists/i, "화면 새로고침 뒤에도 사용자가 선택한 프로젝트가 유지되는지 검증한다."],
+    [/clipboard/i, "사용자가 클립보드나 첨부 입력으로 리포트 근거를 남길 수 있는지 검증한다."],
+    [/natural specs/i, "자연어 명세 생성과 반영 흐름을 검증한다."],
+    [/local repository analyzer/i, "로컬 레포 분석기가 제품 기능과 유즈케이스를 추출하는지 검증한다."]
+  ];
+  const match = known.find(([pattern]) => pattern.test(normalized));
+  if (match) return match[1];
+  return `"${normalized}" 시나리오가 사용자 관점의 기대 동작을 만족하는지 검증한다.`;
+}
+
+function extractTestScenarios(file) {
+  const scenarios = [];
+  for (const match of file.content.matchAll(/\b(?:test|it)\s*\(\s*["'`]([^"'`]{3,180})["'`]/g)) {
+    scenarios.push(humanizeTestTitle(match[1]));
+  }
+  return unique(scenarios, 16);
+}
+
+function extractApiInteractions(file) {
+  const endpoints = [];
+  for (const match of file.content.matchAll(/\brequest\.(get|post|put|patch|delete)\s*\(\s*["'`]([^"'`]+)["'`]/g)) {
+    endpoints.push(`${match[1].toUpperCase()} ${match[2]}`);
+  }
+  for (const match of file.content.matchAll(/\bfetch\s*\(\s*["'`]([^"'`]+)["'`]/g)) {
+    endpoints.push(`FETCH ${match[1]}`);
+  }
+  return unique(endpoints, 20);
+}
+
+function extractMcpToolNames(file) {
+  const tools = [];
+  for (const match of file.content.matchAll(/\bname\s*:\s*["'`](workq_[^"'`]+)["'`]/g)) {
+    tools.push(match[1]);
+  }
+  return unique(tools, 20);
+}
+
+function testFileTitle(file) {
+  if (/v2/i.test(file.path)) return "Work Q v2 자연어 명세 저장소 검증 시나리오";
+  if (/smoke/i.test(file.path)) return "운영 스모크 검증 시나리오";
+  if (/analy/i.test(file.path)) return "레포 분석과 자연어 명세 생성 검증 시나리오";
+  return "제품 검증 시나리오 명세";
+}
+
+function testFileToDoc(file) {
+  const scenarios = extractTestScenarios(file);
+  const endpoints = extractApiInteractions(file);
+  const mcpTools = extractMcpToolNames(file);
+  const inferred = [];
+  if (/\/api\/auth\/login/.test(file.content)) inferred.push("오너가 테스트 계정으로 로그인한다.");
+  if (/connect-project/.test(file.content)) inferred.push("사용자가 프로젝트 키, 레포, 로컬 경로를 등록한다.");
+  if (/workq_import_natural_git_specs/.test(file.content)) inferred.push("로컬 MCP가 생성한 자연어 명세 문서를 Work Q에 업로드한다.");
+  if (/\/api\/v2\/spec-git\/commit/.test(file.content)) inferred.push("사용자가 자연어 명세 변경을 커밋으로 승인한다.");
+  if (/\/api\/v2\/spec-git\/merge/.test(file.content)) inferred.push("Work Q가 자연어 커밋을 머지 가능한 상태인지 검사한다.");
+  if (/\/api\/v2\/spec-git\/deploy/.test(file.content)) inferred.push("승인된 자연어 커밋이 MCP Agent 작업 큐로 전달된다.");
+  if (/workq_get_work_packet/.test(file.content)) inferred.push("데스크톱 에이전트가 작업 패킷을 받아 실제 코드 작업 기준을 확인한다.");
+  if (/workq_finish_task/.test(file.content)) inferred.push("에이전트가 작업 완료 후 검증 결과를 Work Q에 남긴다.");
+  return [
+    `# ${testFileTitle(file)}`,
+    NATURAL_SPEC_FORMAT_COMMENT,
+    "",
+    "## 기능 중심 자연어 명세",
+    "이 명세는 제품 기능 자체가 아니라, 사용자가 기대하는 Work Q 흐름이 실제로 동작하는지 확인하는 검증 시나리오를 정의한다.",
+    "",
+    "## 검증하는 사용자 흐름",
+    ...unique([...scenarios, ...inferred], 20).map((item) => `- ${item}`),
+    "",
+    endpoints.length ? "## 사용되는 웹 API" : "",
+    ...endpoints.map((item) => `- ${item}`),
+    "",
+    mcpTools.length ? "## 사용되는 MCP 작업" : "",
+    ...mcpTools.map((item) => `- ${item}`),
+    "",
+    "## 핵심 규칙",
+    "- 테스트 코드는 제품 명세가 아니라 명세와 구현이 맞는지 확인하는 검증 근거로만 사용한다.",
+    "- 자연어 명세, 커밋, 머지, Agent 큐, 완료 처리 중 하나라도 끊기면 제품 흐름은 통과한 것으로 보지 않는다.",
+    "- 검증 시나리오의 기대값은 사용자가 보는 상태와 MCP Agent가 받는 작업 기준을 함께 확인해야 한다.",
+    "",
+    "## 검증 관점",
+    "- 화면에 표시되는 명세 경로와 편집 내용이 실제 자연어 git 저장소 상태와 일치하는지 확인한다.",
+    "- API 응답, MCP 응답, 화면 표시가 같은 프로젝트 키와 같은 자연어 커밋을 가리키는지 확인한다.",
+    "- 이 문서는 리포트 분류 시 구현 완료 여부와 회귀 여부를 판단하는 검증 증거로 사용한다."
+  ].filter((line, index, array) => line || array[index - 1]).join("\n");
+}
+
+function titleForSourceFile(file) {
+  if (isTestFile(file)) return testFileTitle(file);
+  if (isCliEntryFile(file)) return "Work Q CLI 기능명세";
+  if (file.path === "package.json") return "프로젝트 실행 환경 기능명세";
+  const titleText = primaryVisibleTitle(file);
+  if (titleText && file.extension === ".html") return `${titleText} 기능명세`;
+  if (extractEnvironmentFacts(file).length) return "런타임 환경 설정 기능명세";
+  if (extractDataModelFacts(file).length) return "데이터 모델 기능명세";
+  if (file.extension === ".css") return "화면 디자인 기능명세";
+  if (isApiOrServerFile(file)) return "서버 API 기능명세";
+  if (hasImplementationLogic(file)) return `${sourcePathSlug(file.path).replace(/-/g, " ")} 기능명세`;
+  return "보조 기능명세";
+}
+
 function sourceFileToDoc(file) {
+  if (isTestFile(file)) return testFileToDoc(file);
   const structure = {
     imports: [],
     exports: [],
@@ -399,20 +588,7 @@ function sourceFileToDoc(file) {
     ],
     12
   );
-  const titleText = extractVisibleTexts(file)[0];
-  const title = isCliEntryFile(file)
-    ? "Work Q CLI 기능명세"
-    : file.path === "package.json"
-      ? "프로젝트 실행 환경 기능명세"
-      : titleText && file.extension === ".html"
-        ? `${titleText} 기능명세`
-        : extractEnvironmentFacts(file).length
-          ? "런타임 환경 설정 기능명세"
-          : dataModelFacts.length
-            ? "데이터 모델 기능명세"
-            : file.extension === ".css"
-              ? "화면 디자인 기능명세"
-              : `${file.path} 기능명세`;
+  const title = titleForSourceFile(file);
   return [
     `# ${title}`,
     NATURAL_SPEC_FORMAT_COMMENT,
@@ -439,6 +615,83 @@ function sourceFileToDoc(file) {
   ].filter((line, index, array) => line || array[index - 1]).join("\n");
 }
 
+function sourceFileRulesDoc(file) {
+  const structure = {
+    imports: [],
+    exports: [],
+    classes: [],
+    routes: [],
+    events: [],
+    selectors: [],
+    ...extractStructure(file.lines)
+  };
+  const dataModelFacts = extractDataModelFacts(file);
+  const functionalFacts = extractFunctionalFacts(file, structure);
+  const cliRules = extractCliRules(file);
+  const environmentFacts = extractEnvironmentFacts(file);
+  const designFacts = extractDesignFacts(file);
+  const rules = unique([...dataModelFacts, ...cliRules, ...environmentFacts, ...functionalFacts, ...designFacts], 30);
+  return [
+    `# ${titleForSourceFile(file)} - 규칙`,
+    NATURAL_SPEC_FORMAT_COMMENT,
+    "",
+    "## 핵심 규칙",
+    ...(rules.length ? rules.map((item) => `- ${item}`) : ["- 이 기능은 연결된 상위 명세의 기대 동작을 보조한다."]),
+    "",
+    "## 판단 기준",
+    "- 리포트가 이 규칙과 다르게 동작한다고 주장하고 실제 구현도 다르면 버그 후보로 본다.",
+    "- 기대 동작은 있지만 이 규칙에 없으면 기획부재 또는 명세추가 후보로 본다.",
+    "- 서로 다른 규칙이 동시에 만족될 수 없으면 기능충돌 후보로 본다."
+  ].join("\n");
+}
+
+function sourceFileVerificationDoc(file) {
+  const structure = {
+    imports: [],
+    exports: [],
+    classes: [],
+    routes: [],
+    events: [],
+    selectors: [],
+    ...extractStructure(file.lines)
+  };
+  const verificationFacts = isTestFile(file) ? extractTestScenarios(file) : buildVerificationFacts(file, structure);
+  return [
+    `# ${titleForSourceFile(file)} - 검증`,
+    NATURAL_SPEC_FORMAT_COMMENT,
+    "",
+    "## 검증해야 할 것",
+    ...verificationFacts.map((item) => `- ${item}`),
+    "",
+    "## 완료 기준",
+    "- 관련 화면, API, MCP 응답, 또는 데이터 상태가 이 명세의 기대 동작과 일치한다.",
+    "- 자동 테스트가 있으면 통과 결과를 Work Q 작업 완료 기록에 남긴다.",
+    "- 자동 테스트가 없으면 수동 검증 방법과 남은 위험을 Work Q에 남긴다."
+  ].join("\n");
+}
+
+function sourceFileToDocs(file) {
+  const directory = specDirectoryForSource(file);
+  const title = titleForSourceFile(file);
+  return [
+    {
+      path: `${directory}/README.md`,
+      title,
+      content: sourceFileToDoc(file)
+    },
+    {
+      path: `${directory}/rules.md`,
+      title: `${title} 규칙`,
+      content: sourceFileRulesDoc(file)
+    },
+    {
+      path: `${directory}/verification.md`,
+      title: `${title} 검증`,
+      content: sourceFileVerificationDoc(file)
+    }
+  ];
+}
+
 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);
@@ -459,6 +712,14 @@ function overviewDoc({ projectKey, projectName, repository, root, sourceFiles })
     "## 언어별 파일 수",
     ...Array.from(byLanguage.entries()).map(([language, count]) => `- ${language}: ${count}개`),
     "",
+    "## 디렉토리 구조",
+    "- `natural-git/features/`: 사용자가 직접 경험하는 화면과 기능 명세",
+    "- `natural-git/interfaces/`: CLI, API, 외부 연결처럼 기능이 드나드는 접점 명세",
+    "- `natural-git/data/`: 데이터 모델과 저장 규칙 명세",
+    "- `natural-git/operations/`: 실행 환경, 설정, 배포/운영 조건 명세",
+    "- `natural-git/verification/`: 기능이 실제로 동작하는지 확인하는 검증 시나리오 명세",
+    "- 각 기능 디렉토리는 `README.md`, `rules.md`, `verification.md`로 나뉘어 개요, 판단 규칙, 검증 기준을 따로 관리한다.",
+    "",
     "## 운영 규칙",
     "- 자연어 문서는 코드에서 관찰한 제품 기능과 검증 가능한 동작을 설명한다.",
     "- 각 코드 파일 문서는 라인별 번역이 아니라 기능, 규칙, 화면, 데이터, 검증 관점 중심으로 작성한다.",
@@ -470,11 +731,11 @@ function overviewDoc({ projectKey, projectName, repository, root, sourceFiles })
 
 function indexDoc(sourceFiles) {
   return [
-    "# 코드 파일 자연어 색인",
+    "# 자연어 명세 색인",
     "",
-    "이 문서는 분석된 파일과 각 파일의 자연어 명세 문서를 연결한다.",
+    "이 문서는 분석된 파일과 계층형 자연어 명세 디렉토리를 연결한다. 사용자는 보통 이 색인보다 각 기능 디렉토리의 README, rules, verification 문서를 읽는다.",
     "",
-    ...sourceFiles.map((file) => `- \`${file.path}\` -> \`${docPathForSource(file.path)}\``)
+    ...sourceFiles.map((file) => `- \`${file.path}\` -> \`${specDirectoryForSource(file)}/\``)
   ].join("\n");
 }
 
@@ -506,15 +767,11 @@ export function generateNaturalGitDocs({ localPath, projectKey, projectName = ""
       content: overviewDoc({ projectKey, projectName, repository, root, sourceFiles })
     },
     {
-      path: "natural-git/code-index.md",
-      title: "코드 파일 자연어 색인",
+      path: "natural-git/source-index.md",
+      title: "자연어 명세 색인",
       content: indexDoc(sourceFiles)
     },
-    ...sourceFiles.map((file) => ({
-      path: docPathForSource(file.path),
-      title: file.path,
-      content: sourceFileToDoc(file)
-    }))
+    ...sourceFiles.flatMap((file) => sourceFileToDocs(file))
   ];
   return {
     root,

package/package.json

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