helloloop 0.2.0 → 0.3.1

package/src/discovery.mjs

@@ -8,25 +8,130 @@ import {
   normalizeForRepo,
   pathExists,
   resolveAbsolute,
+  uniquePaths,
 } from "./discovery_paths.mjs";
 import {
   inferDocsForRepo,
   inferRepoFromDocs,
+  inspectWorkspaceDirectory,
   renderMissingDocsMessage,
   renderMissingRepoMessage,
 } from "./discovery_inference.mjs";
 
 export { findRepoRootFromPath } from "./discovery_paths.mjs";
 
+const CONFIDENCE_LABELS = {
+  high: "高",
+  medium: "中",
+  low: "低",
+};
+
+const REPO_SOURCE_META = {
+  explicit_flag: { label: "命令参数", confidence: "high" },
+  explicit_input: { label: "命令附带路径", confidence: "high" },
+  new_repo_input: { label: "命令附带路径", confidence: "high" },
+  interactive: { label: "交互确认", confidence: "high" },
+  interactive_new_repo: { label: "交互确认", confidence: "high" },
+  cwd_repo: { label: "当前目录", confidence: "medium" },
+  workspace_single_repo: { label: "工作区唯一候选项目", confidence: "medium" },
+  docs_ancestor: { label: "文档同树回溯", confidence: "medium" },
+  doc_path_hint: { label: "文档中的路径线索", confidence: "medium" },
+  doc_repo_name_hint: { label: "文档中的仓库名线索", confidence: "low" },
+};
+
+const DOCS_SOURCE_META = {
+  explicit_flag: { label: "命令参数", confidence: "high" },
+  explicit_input: { label: "命令附带路径", confidence: "high" },
+  interactive: { label: "交互确认", confidence: "high" },
+  cwd_docs: { label: "当前目录", confidence: "medium" },
+  workspace_single_doc: { label: "工作区唯一文档候选", confidence: "medium" },
+  existing_state: { label: "已有 .helloloop 配置", confidence: "medium" },
+  repo_docs: { label: "仓库 docs 目录", confidence: "medium" },
+};
+
+function pushBasis(basis, message) {
+  if (message && !basis.includes(message)) {
+    basis.push(message);
+  }
+}
+
+function repoSourceFromSelection(selectionSource, allowNewRepoRoot, repoRoot) {
+  if (selectionSource === "flag") {
+    return allowNewRepoRoot && repoRoot && !pathExists(repoRoot) ? "new_repo_input" : "explicit_flag";
+  }
+  if (selectionSource === "positional") {
+    return allowNewRepoRoot && repoRoot && !pathExists(repoRoot) ? "new_repo_input" : "explicit_input";
+  }
+  if (selectionSource === "interactive_new_repo") {
+    return "interactive_new_repo";
+  }
+  if (selectionSource === "interactive") {
+    return "interactive";
+  }
+  if (selectionSource === "workspace_single_repo") {
+    return "workspace_single_repo";
+  }
+  return "";
+}
+
+function docsSourceFromSelection(selectionSource) {
+  if (selectionSource === "flag") {
+    return "explicit_flag";
+  }
+  if (selectionSource === "positional") {
+    return "explicit_input";
+  }
+  if (selectionSource === "interactive") {
+    return "interactive";
+  }
+  if (selectionSource === "workspace_single_doc") {
+    return "workspace_single_doc";
+  }
+  return "";
+}
+
+function createResolution(kind, payload) {
+  const meta = kind === "repo" ? REPO_SOURCE_META : DOCS_SOURCE_META;
+  const selected = meta[payload.source] || { label: "自动判断", confidence: "medium" };
+  return {
+    ...payload,
+    sourceLabel: selected.label,
+    confidence: selected.confidence,
+    confidenceLabel: CONFIDENCE_LABELS[selected.confidence] || "中",
+    basis: Array.isArray(payload.basis) ? payload.basis.filter(Boolean) : [],
+  };
+}
+
+function createRepoResolution(repoRoot, source, basis) {
+  return createResolution("repo", {
+    source,
+    path: repoRoot,
+    exists: pathExists(repoRoot),
+    basis,
+  });
+}
+
+function createDocsResolution(docsEntries, source, basis) {
+  return createResolution("docs", {
+    source,
+    entries: docsEntries,
+    basis,
+  });
+}
+
 export function discoverWorkspace(options = {}) {
   const cwd = path.resolve(options.cwd || process.cwd());
   const configDirName = options.configDirName || ".helloloop";
+  const allowNewRepoRoot = Boolean(options.allowNewRepoRoot);
+  const selectionSources = options.selectionSources || {};
   const explicitRepoRoot = options.repoRoot ? resolveAbsolute(options.repoRoot, cwd) : "";
   const explicitDocsPath = options.docsPath ? resolveAbsolute(options.docsPath, cwd) : "";
   const explicitInputPath = options.inputPath ? resolveAbsolute(options.inputPath, cwd) : "";
 
   if (explicitRepoRoot && !pathExists(explicitRepoRoot)) {
-    return { ok: false, code: "missing_repo_path", message: `项目路径不存在：${explicitRepoRoot}` };
+    if (!allowNewRepoRoot) {
+      return { ok: false, code: "missing_repo_path", message: `项目路径不存在：${explicitRepoRoot}` };
+    }
   }
   if (explicitDocsPath && !pathExists(explicitDocsPath)) {
     return { ok: false, code: "missing_docs_path", message: `开发文档路径不存在：${explicitDocsPath}` };
@@ -36,6 +141,39 @@ export function discoverWorkspace(options = {}) {
   let docsEntries = explicitDocsPath ? [explicitDocsPath] : [];
   let docCandidates = [];
   let repoCandidates = [];
+  let workspaceRoot = "";
+  let docsDerivedFromWorkspace = false;
+  let repoSource = repoSourceFromSelection(selectionSources.repo, allowNewRepoRoot, explicitRepoRoot);
+  let docsSource = docsSourceFromSelection(selectionSources.docs);
+  const repoBasis = [];
+  const docsBasis = [];
+
+  if (explicitRepoRoot && !repoSource) {
+    repoSource = allowNewRepoRoot && !pathExists(explicitRepoRoot) ? "new_repo_input" : "explicit_input";
+  }
+  if (explicitDocsPath && !docsSource) {
+    docsSource = "explicit_input";
+  }
+
+  if (repoSource === "explicit_flag") {
+    pushBasis(repoBasis, "目标项目来自命令参数 `--repo`。");
+  } else if (repoSource === "explicit_input") {
+    pushBasis(repoBasis, "目标项目来自命令中显式提供的路径。");
+  } else if (repoSource === "new_repo_input") {
+    pushBasis(repoBasis, "目标项目来自显式提供的项目路径；该目录当前不存在，将按新项目创建。");
+  } else if (repoSource === "interactive_new_repo") {
+    pushBasis(repoBasis, "目标项目由用户在确认流程中指定；该目录当前不存在，将按新项目创建。");
+  } else if (repoSource === "interactive") {
+    pushBasis(repoBasis, "目标项目由用户在确认流程中手动指定。");
+  }
+
+  if (docsSource === "explicit_flag") {
+    pushBasis(docsBasis, "开发文档来自命令参数 `--docs`。");
+  } else if (docsSource === "explicit_input") {
+    pushBasis(docsBasis, "开发文档来自命令中显式提供的路径。");
+  } else if (docsSource === "interactive") {
+    pushBasis(docsBasis, "开发文档由用户在确认流程中手动指定。");
+  }
 
   if (!repoRoot && !docsEntries.length) {
     const classified = classifyExplicitPath(explicitInputPath);
@@ -44,9 +182,16 @@ export function discoverWorkspace(options = {}) {
     }
     if (classified.kind === "docs") {
       docsEntries = [classified.absolutePath];
+      docsSource = "explicit_input";
+      pushBasis(docsBasis, "开发文档来自命令中传入的单一路径。");
     }
     if (classified.kind === "repo") {
       repoRoot = classified.absolutePath;
+      repoSource = "explicit_input";
+      pushBasis(repoBasis, "目标项目来自命令中传入的单一路径。");
+    }
+    if (classified.kind === "workspace" || classified.kind === "directory") {
+      workspaceRoot = classified.absolutePath;
     }
   }
 
@@ -54,17 +199,75 @@ export function discoverWorkspace(options = {}) {
     const cwdRepoRoot = findRepoRootFromPath(cwd);
     if (cwdRepoRoot) {
       repoRoot = cwdRepoRoot;
-    } else if (classifyExplicitPath(cwd).kind === "docs") {
-      docsEntries = [cwd];
-    } else if (looksLikeProjectRoot(cwd)) {
-      repoRoot = cwd;
+      repoSource = "cwd_repo";
+      pushBasis(repoBasis, "当前终端目录已经位于一个项目仓库内。");
+    } else {
+      const cwdClassified = classifyExplicitPath(cwd);
+      if (cwdClassified.kind === "docs") {
+        docsEntries = [cwdClassified.absolutePath];
+        docsSource = "cwd_docs";
+        pushBasis(docsBasis, "当前终端目录本身就是开发文档目录或文件。");
+      } else if (cwdClassified.kind === "repo") {
+        repoRoot = cwdClassified.absolutePath;
+        repoSource = "cwd_repo";
+        pushBasis(repoBasis, "当前终端目录本身就是项目仓库。");
+      } else if (cwdClassified.kind === "workspace" || cwdClassified.kind === "directory") {
+        workspaceRoot = cwdClassified.absolutePath;
+      } else if (looksLikeProjectRoot(cwd)) {
+        repoRoot = cwd;
+        repoSource = "cwd_repo";
+        pushBasis(repoBasis, "当前终端目录具备项目仓库特征。");
+      }
+    }
+  }
+
+  if (!repoRoot && !docsEntries.length && workspaceRoot) {
+    const workspace = inspectWorkspaceDirectory(workspaceRoot);
+    docCandidates = workspace.docCandidates;
+    repoCandidates = workspace.repoCandidates;
+
+    if (workspace.docsEntries.length === 1) {
+      docsEntries = workspace.docsEntries;
+      docsDerivedFromWorkspace = true;
+      docsSource = "workspace_single_doc";
+      pushBasis(docsBasis, "工作区扫描后只发现一个顶层开发文档入口。");
+    }
+
+    if (workspace.repoCandidates.length === 1) {
+      repoRoot = workspace.repoCandidates[0];
+      repoSource = "workspace_single_repo";
+      pushBasis(repoBasis, "工作区扫描后只发现一个顶层项目候选目录。");
     }
   }
 
   if (!repoRoot && docsEntries.length) {
+    if (docsDerivedFromWorkspace && repoCandidates.length > 1) {
+      return {
+        ok: false,
+        code: "missing_repo",
+        message: renderMissingRepoMessage(docsEntries, repoCandidates),
+        docsEntries,
+        docCandidates,
+        repoCandidates,
+        workspaceRoot,
+      };
+    }
+
     const inferred = inferRepoFromDocs(docsEntries, cwd);
     repoRoot = inferred.repoRoot;
-    repoCandidates = inferred.candidates;
+    repoCandidates = uniquePaths([...repoCandidates, ...inferred.candidates]);
+    if (repoRoot) {
+      if (inferred.source === "ancestor") {
+        repoSource = "docs_ancestor";
+        pushBasis(repoBasis, "开发文档位于该仓库目录树内，已回溯到真实项目根目录。");
+      } else if (inferred.source === "doc_path_hint") {
+        repoSource = "doc_path_hint";
+        pushBasis(repoBasis, "开发文档内容中出现了指向该仓库的实际路径线索。");
+      } else if (inferred.source === "doc_repo_name_hint") {
+        repoSource = "doc_repo_name_hint";
+        pushBasis(repoBasis, "开发文档内容中出现了与该仓库名称一致的线索。");
+      }
+    }
   }
 
   if (!repoRoot) {
@@ -72,16 +275,35 @@ export function discoverWorkspace(options = {}) {
       ok: false,
       code: "missing_repo",
       message: renderMissingRepoMessage(docsEntries, repoCandidates),
+      docsEntries,
+      docCandidates,
+      repoCandidates,
+      workspaceRoot,
     };
   }
 
-  repoRoot = findRepoRootFromPath(repoRoot) || repoRoot;
+  const normalizedRepoRoot = findRepoRootFromPath(repoRoot) || repoRoot;
+  if (normalizedRepoRoot !== repoRoot) {
+    pushBasis(repoBasis, "已自动回溯到项目仓库根目录。");
+  }
+  repoRoot = normalizedRepoRoot;
   docsEntries = docsEntries.map((entry) => normalizeForRepo(repoRoot, entry));
 
   if (!docsEntries.length) {
     const inferred = inferDocsForRepo(repoRoot, cwd, configDirName);
     docsEntries = inferred.docsEntries;
     docCandidates = inferred.candidates;
+    if (docsEntries.length) {
+      docsSource = inferred.source || docsSource;
+      if (inferred.source === "existing_state") {
+        pushBasis(docsBasis, "已复用 `.helloloop/project.json` 中记录的 requiredDocs。");
+      } else if (inferred.source === "cwd") {
+        docsSource = "cwd_docs";
+        pushBasis(docsBasis, "当前终端目录本身就是开发文档目录或文件。");
+      } else if (inferred.source === "repo_docs") {
+        pushBasis(docsBasis, "已使用目标仓库中的 `docs/` 目录作为默认开发文档入口。");
+      }
+    }
   }
 
   if (!docsEntries.length) {
@@ -89,8 +311,12 @@ export function discoverWorkspace(options = {}) {
       ok: false,
       code: "missing_docs",
       repoRoot,
-      message: renderMissingDocsMessage(repoRoot),
+      message: renderMissingDocsMessage(repoRoot, docCandidates),
       candidates: docCandidates,
+      docsEntries,
+      docCandidates,
+      repoCandidates,
+      workspaceRoot,
     };
   }
 
@@ -100,7 +326,11 @@ export function discoverWorkspace(options = {}) {
       ok: false,
       code: "invalid_docs",
       repoRoot,
-      message: renderMissingDocsMessage(repoRoot),
+      message: renderMissingDocsMessage(repoRoot, docCandidates),
+      docsEntries,
+      docCandidates,
+      repoCandidates,
+      workspaceRoot,
     };
   }
 
@@ -109,6 +339,10 @@ export function discoverWorkspace(options = {}) {
     repoRoot,
     docsEntries,
     resolvedDocs,
+    resolution: {
+      repo: createRepoResolution(repoRoot, repoSource || "cwd_repo", repoBasis),
+      docs: createDocsResolution(docsEntries, docsSource || "repo_docs", docsBasis),
+    },
   };
 }
 

package/src/discovery_inference.mjs

@@ -4,10 +4,12 @@ import path from "node:path";
 import { readJson } from "./common.mjs";
 import { expandDocumentEntries } from "./doc_loader.mjs";
 import {
+  findPreferredRepoRootFromPath,
   findRepoRootFromPath,
   isDocFile,
   isDocsDirectory,
-  looksLikeProjectRoot,
+  listDocFilesInDirectory,
+  listProjectCandidatesInDirectory,
   normalizeForRepo,
   pathExists,
   resolveAbsolute,
@@ -48,7 +50,7 @@ function readDocPreview(docEntries, cwd) {
 }
 
 function normalizePathHint(rawValue) {
-  const trimmed = String(rawValue || "").trim().replace(/^["'`(<\[]+|[>"'`)\].,;:]+$/g, "");
+  const trimmed = String(rawValue || "").trim().replace(/^[:"'`(<\[：]+|[>"'`)\].,;:：]+$/g, "");
   if (/^\/[A-Za-z]:[\\/]/.test(trimmed)) {
     return trimmed.slice(1);
   }
@@ -59,7 +61,7 @@ function extractPathHintsFromText(text) {
   const hints = new Set();
   const normalizedText = String(text || "");
   const windowsMatches = normalizedText.match(/\/?[A-Za-z]:[\\/][^\s"'`<>()\]]+/g) || [];
-  const posixMatches = normalizedText.match(/(?:^|[\s("'`])\/[^\s"'`<>()\]]+/g) || [];
+  const posixMatches = normalizedText.match(/(?:^|[\s("'`:：])\/(?!\/)[^\s"'`<>()\]]+/g) || [];
 
   for (const rawMatch of [...windowsMatches, ...posixMatches]) {
     const normalized = normalizePathHint(rawMatch);
@@ -86,15 +88,52 @@ function extractRepoNameHintsFromText(text) {
   return [...hints];
 }
 
-function listNearbyProjectCandidates(searchRoot) {
-  if (!pathExists(searchRoot) || !fs.statSync(searchRoot).isDirectory()) {
+function formatCandidates(title, candidates) {
+  if (!Array.isArray(candidates) || !candidates.length) {
     return [];
   }
 
-  return fs.readdirSync(searchRoot, { withFileTypes: true })
+  return [
+    title,
+    ...candidates.map((item, index) => `${index + 1}. ${path.basename(item)} — ${item.replaceAll("\\", "/")}`),
+  ];
+}
+
+export function inspectWorkspaceDirectory(directoryPath) {
+  if (!pathExists(directoryPath) || !fs.statSync(directoryPath).isDirectory()) {
+    return {
+      docCandidates: [],
+      docsEntries: [],
+      repoCandidates: [],
+      topLevelDirectories: [],
+      topLevelDocFiles: [],
+    };
+  }
+
+  const topLevelEntries = fs.readdirSync(directoryPath, { withFileTypes: true });
+  const namedDocsDirectories = topLevelEntries
+    .filter((entry) => (
+      entry.isDirectory()
+      && ["doc", "docs", "documentation"].includes(entry.name.toLowerCase())
+    ))
+    .map((entry) => path.join(directoryPath, entry.name))
+    .filter((candidate) => isDocsDirectory(candidate));
+
+  const topLevelDocFiles = listDocFilesInDirectory(directoryPath)
+    .filter((candidate) => path.basename(candidate).toLowerCase() !== "agents.md");
+  const docCandidates = uniquePaths([...topLevelDocFiles, ...namedDocsDirectories]);
+  const topLevelDirectories = topLevelEntries
     .filter((entry) => entry.isDirectory())
-    .map((entry) => path.join(searchRoot, entry.name))
-    .filter((directoryPath) => looksLikeProjectRoot(directoryPath));
+    .map((entry) => path.join(directoryPath, entry.name));
+
+  const repoCandidates = uniquePaths(listProjectCandidatesInDirectory(directoryPath));
+  return {
+    docCandidates,
+    docsEntries: docCandidates.length === 1 ? [docCandidates[0]] : [],
+    repoCandidates,
+    topLevelDirectories,
+    topLevelDocFiles,
+  };
 }
 
 export function inferRepoFromDocs(docEntries, cwd) {
@@ -117,7 +156,7 @@ export function inferRepoFromDocs(docEntries, cwd) {
     .map((item) => resolveAbsolute(item, cwd))
     .filter((candidate) => pathExists(candidate))
     .map((candidate) => (fs.statSync(candidate).isDirectory() ? candidate : path.dirname(candidate)))
-    .map((candidate) => findRepoRootFromPath(candidate) || (looksLikeProjectRoot(candidate) ? candidate : ""))
+    .map((candidate) => findPreferredRepoRootFromPath(candidate))
     .filter(Boolean);
 
   const uniquePathCandidates = uniquePaths(pathHintCandidates);
@@ -136,11 +175,15 @@ export function inferRepoFromDocs(docEntries, cwd) {
         ? absolutePath
         : path.dirname(absolutePath);
       const parent = path.dirname(directory);
-      return [directory, parent, path.dirname(parent)];
+      const roots = [directory, parent];
+      if (["doc", "docs", "documentation"].includes(path.basename(directory).toLowerCase())) {
+        roots.push(path.dirname(parent));
+      }
+      return roots;
     }),
   );
   const nearbyCandidates = uniquePaths(
-    searchRoots.flatMap((searchRoot) => listNearbyProjectCandidates(searchRoot)),
+    searchRoots.flatMap((searchRoot) => listProjectCandidatesInDirectory(searchRoot)),
   );
   const namedCandidates = nearbyCandidates.filter((directoryPath) => (
     repoNameHints.includes(path.basename(directoryPath).toLowerCase())
@@ -156,7 +199,7 @@ export function inferRepoFromDocs(docEntries, cwd) {
 
   return {
     repoRoot: "",
-    candidates: uniquePaths([...uniquePathCandidates, ...namedCandidates]),
+    candidates: uniquePaths([...uniquePathCandidates, ...namedCandidates, ...nearbyCandidates]),
     source: "",
   };
 }
@@ -203,18 +246,19 @@ export function inferDocsForRepo(repoRoot, cwd, configDirName) {
 export function renderMissingRepoMessage(docEntries, candidates) {
   return [
     "无法自动确定要开发的项目仓库路径。",
-    docEntries.length ? `已找到开发文档：${docEntries.join(", ")}` : "",
-    candidates.length > 1 ? `本地发现多个候选项目：${candidates.map((item) => path.basename(item)).join(", ")}` : "",
-    "请补充项目仓库路径后重试，例如：",
+    docEntries.length ? `已找到开发文档：${docEntries.map((item) => item.replaceAll("\\", "/")).join("，")}` : "",
+    ...formatCandidates("候选项目：", candidates),
+    "可重新运行 `npx helloloop` 后按提示选择，或显式补充项目路径，例如：",
     "npx helloloop --repo <PROJECT_ROOT>",
   ].filter(Boolean).join("\n");
 }
 
-export function renderMissingDocsMessage(repoRoot) {
+export function renderMissingDocsMessage(repoRoot, candidates = []) {
   return [
     "无法自动确定开发文档位置。",
-    `已找到项目仓库：${repoRoot}`,
-    "请补充开发文档路径后重试，例如：",
+    `已找到项目仓库：${repoRoot.replaceAll("\\", "/")}`,
+    ...formatCandidates("候选开发文档：", candidates),
+    "可重新运行 `npx helloloop` 后按提示选择，或显式补充开发文档路径，例如：",
     "npx helloloop --docs <DOCS_PATH>",
   ].join("\n");
 }

package/src/discovery_paths.mjs

@@ -36,15 +36,80 @@ const PROJECT_DIR_MARKERS = [
   "tests",
 ];
 
-function directoryContainsDocs(directoryPath) {
+const IGNORED_PROJECT_SEGMENTS = new Set([
+  ".cache",
+  ".git",
+  ".next",
+  ".nuxt",
+  ".pnpm",
+  ".turbo",
+  ".venv",
+  ".yarn",
+  "__pycache__",
+  "build",
+  "cache",
+  "coverage",
+  "dist",
+  "node_modules",
+  "out",
+  "target",
+  "temp",
+  "tmp",
+  "vendor",
+  "venv",
+]);
+
+function listImmediateDirectories(directoryPath) {
   if (!pathExists(directoryPath) || !fs.statSync(directoryPath).isDirectory()) {
-    return false;
+    return [];
   }
 
-  const entries = fs.readdirSync(directoryPath, { withFileTypes: true });
-  return entries.some((entry) => (
-    entry.isFile() && DOC_FILE_SUFFIX.has(path.extname(entry.name).toLowerCase())
-  ));
+  return fs.readdirSync(directoryPath, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(directoryPath, entry.name));
+}
+
+function hasProjectMarker(directoryPath) {
+  return PROJECT_MARKERS.some((name) => pathExists(path.join(directoryPath, name)));
+}
+
+function looksLikeStrongProjectRoot(directoryPath) {
+  return pathExists(directoryPath)
+    && fs.statSync(directoryPath).isDirectory()
+    && hasProjectMarker(directoryPath);
+}
+
+export function listDocFilesInDirectory(directoryPath) {
+  if (!pathExists(directoryPath) || !fs.statSync(directoryPath).isDirectory()) {
+    return [];
+  }
+
+  return fs.readdirSync(directoryPath, { withFileTypes: true })
+    .filter((entry) => (
+      entry.isFile() && DOC_FILE_SUFFIX.has(path.extname(entry.name).toLowerCase())
+    ))
+    .map((entry) => path.join(directoryPath, entry.name));
+}
+
+function directoryContainsDocs(directoryPath) {
+  return listDocFilesInDirectory(directoryPath).length > 0;
+}
+
+function hasIgnoredProjectBasename(targetPath) {
+  return IGNORED_PROJECT_SEGMENTS.has(path.basename(targetPath).toLowerCase());
+}
+
+function choosePreferredCandidate(candidates, directory) {
+  return candidates.find((candidate) => {
+    const relativeToLeaf = path.relative(candidate, directory);
+    return relativeToLeaf
+      .split(/[\\/]+/)
+      .filter(Boolean)
+      .some((segment) => IGNORED_PROJECT_SEGMENTS.has(segment.toLowerCase()));
+  })
+    || candidates.find((candidate) => !hasIgnoredProjectBasename(candidate))
+    || candidates[0]
+    || "";
 }
 
 function walkUpDirectories(startPath) {
@@ -86,13 +151,37 @@ export function looksLikeProjectRoot(directoryPath) {
     return false;
   }
 
-  if (PROJECT_MARKERS.some((name) => pathExists(path.join(directoryPath, name)))) {
+  if (hasProjectMarker(directoryPath)) {
     return true;
   }
 
   return PROJECT_DIR_MARKERS.some((name) => pathExists(path.join(directoryPath, name)));
 }
 
+export function listProjectCandidatesInDirectory(searchRoot) {
+  return listImmediateDirectories(searchRoot)
+    .filter((directoryPath) => (
+      looksLikeProjectRoot(directoryPath) && !hasIgnoredProjectBasename(directoryPath)
+    ));
+}
+
+export function looksLikeWorkspaceDirectory(directoryPath) {
+  if (!pathExists(directoryPath) || !fs.statSync(directoryPath).isDirectory()) {
+    return false;
+  }
+
+  const repoCandidates = listProjectCandidatesInDirectory(directoryPath);
+  if (!repoCandidates.length) {
+    return false;
+  }
+
+  const hasLooseDocs = directoryContainsDocs(directoryPath)
+    || listImmediateDirectories(directoryPath)
+      .some((childPath) => DOC_DIR_NAMES.has(path.basename(childPath).toLowerCase()));
+
+  return repoCandidates.length > 1 || hasLooseDocs;
+}
+
 export function isDocsDirectory(directoryPath) {
   if (!pathExists(directoryPath) || !fs.statSync(directoryPath).isDirectory()) {
     return false;
@@ -103,6 +192,10 @@ export function isDocsDirectory(directoryPath) {
     return true;
   }
 
+  if (looksLikeWorkspaceDirectory(directoryPath)) {
+    return false;
+  }
+
   return directoryContainsDocs(directoryPath) && !looksLikeProjectRoot(directoryPath);
 }
 
@@ -124,6 +217,39 @@ export function findRepoRootFromPath(startPath) {
   return "";
 }
 
+export function findPreferredRepoRootFromPath(startPath) {
+  if (!pathExists(startPath)) {
+    return "";
+  }
+
+  const directory = fs.statSync(startPath).isDirectory()
+    ? startPath
+    : path.dirname(startPath);
+  const strongCandidates = [];
+  const weakCandidates = [];
+
+  for (const current of walkUpDirectories(directory)) {
+    if (pathExists(path.join(current, ".git"))) {
+      return current;
+    }
+
+    if (looksLikeStrongProjectRoot(current)) {
+      strongCandidates.push(current);
+      continue;
+    }
+
+    if (looksLikeProjectRoot(current)) {
+      weakCandidates.push(current);
+    }
+  }
+
+  if (strongCandidates.length) {
+    return choosePreferredCandidate(strongCandidates, directory);
+  }
+
+  return choosePreferredCandidate(weakCandidates, directory);
+}
+
 export function normalizeForRepo(repoRoot, targetPath) {
   const relative = path.relative(repoRoot, targetPath);
   if (relative && !relative.startsWith("..") && !path.isAbsolute(relative)) {
@@ -159,7 +285,16 @@ export function classifyExplicitPath(inputPath) {
   }
 
   if (fs.statSync(inputPath).isDirectory()) {
-    return { kind: "repo", absolutePath: inputPath };
+    const repoRoot = findRepoRootFromPath(inputPath);
+    if (repoRoot) {
+      return { kind: "repo", absolutePath: repoRoot };
+    }
+
+    if (looksLikeWorkspaceDirectory(inputPath)) {
+      return { kind: "workspace", absolutePath: inputPath };
+    }
+
+    return { kind: "directory", absolutePath: inputPath };
   }
 
   return { kind: "unsupported", absolutePath: inputPath };