@ilya-lesikov/pi-pi 0.1.0

package/3p/pi-plannotator/packages/shared/resolve-file.ts

@@ -0,0 +1,509 @@
+/**
+ * Smart markdown file resolution.
+ *
+ * Resolves a user-provided path to an absolute file path using three strategies:
+ * 1. Exact path (absolute or relative to cwd)
+ * 2. Case-insensitive relative path search within project root
+ * 3. Case-insensitive bare filename search within project root
+ *
+ * Used by both the CLI (`plannotator annotate`) and the `/api/doc` endpoint.
+ */
+
+import { homedir } from "os";
+import { isAbsolute, join, resolve, win32 } from "path";
+import { existsSync, readdirSync, type Dirent } from "fs";
+
+const MARKDOWN_PATH_REGEX = /\.mdx?$/i;
+
+import { CODE_FILE_REGEX as CODE_FILE_BASENAME_REGEX } from "./code-file";
+export { CODE_FILE_REGEX, isCodeFilePath } from "./code-file";
+
+const WINDOWS_DRIVE_PATH_PATTERNS = [
+	/^\/cygdrive\/([a-zA-Z])\/(.+)$/,
+	/^\/([a-zA-Z])\/(.+)$/,
+];
+
+const IGNORED_DIRS = [
+	"node_modules/",
+	".git/",
+	"dist/",
+	"build/",
+	".next/",
+	"__pycache__/",
+	".obsidian/",
+	".trash/",
+];
+
+const CODE_IGNORED_DIRS = [
+	...IGNORED_DIRS,
+	".turbo/",
+	".cache/",
+	"target/",
+	"vendor/",
+	"coverage/",
+	".venv/",
+	".pytest_cache/",
+];
+
+export type ResolveResult =
+	| { kind: "found"; path: string }
+	| { kind: "not_found"; input: string }
+	| { kind: "ambiguous"; input: string; matches: string[] }
+	| { kind: "unavailable"; input: string };
+
+function normalizeSeparators(input: string): string {
+	return input.replace(/\\/g, "/");
+}
+
+function stripTrailingSlashes(input: string): string {
+	return input.replace(/\/+$/, "");
+}
+
+export function expandHomePath(input: string, home = homedir()): string {
+	if (input === "~") {
+		return home;
+	}
+
+	if (input.startsWith("~/") || input.startsWith("~\\")) {
+		return join(home, input.slice(2));
+	}
+
+	return input;
+}
+
+export function stripWrappingQuotes(input: string): string {
+	if (input.length < 2) {
+		return input;
+	}
+
+	const first = input[0];
+	const last = input[input.length - 1];
+	if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+		return input.slice(1, -1);
+	}
+
+	return input;
+}
+
+export function normalizeUserPathInput(
+	input: string,
+	platform = process.platform,
+): string {
+	const trimmedInput = input.trim();
+	const unquotedInput = stripWrappingQuotes(trimmedInput);
+	const expandedInput = expandHomePath(unquotedInput);
+
+	if (platform !== "win32") {
+		return expandedInput;
+	}
+
+	for (const pattern of WINDOWS_DRIVE_PATH_PATTERNS) {
+		const match = expandedInput.match(pattern);
+		if (!match) {
+			continue;
+		}
+
+		const [, driveLetter, rest] = match;
+		return `${driveLetter.toUpperCase()}:/${rest}`;
+	}
+
+	return expandedInput;
+}
+
+function isAbsoluteNormalizedUserPath(
+	input: string,
+	platform = process.platform,
+): boolean {
+	if (hasWindowsDriveLetter(input)) {
+		return true;
+	}
+
+	return platform === "win32"
+		? win32.isAbsolute(input)
+		: isAbsolute(input);
+}
+
+export function isAbsoluteUserPath(
+	input: string,
+	platform = process.platform,
+): boolean {
+	return isAbsoluteNormalizedUserPath(normalizeUserPathInput(input, platform), platform);
+}
+
+export function resolveUserPath(
+	input: string,
+	baseDir = process.cwd(),
+	platform = process.platform,
+): string {
+	const normalizedInput = normalizeUserPathInput(input, platform);
+	if (!normalizedInput) {
+		return "";
+	}
+	return isAbsoluteNormalizedUserPath(normalizedInput, platform)
+		? resolveAbsolutePath(normalizedInput, platform)
+		: resolve(baseDir, normalizedInput);
+}
+
+function normalizeComparablePath(input: string): string {
+	return stripTrailingSlashes(normalizeSeparators(resolveUserPath(input)));
+}
+
+export function isWithinProjectRoot(candidate: string, projectRoot: string): boolean {
+	const normalizedCandidate = normalizeComparablePath(candidate);
+	const normalizedProjectRoot = normalizeComparablePath(projectRoot);
+	return (
+		normalizedCandidate === normalizedProjectRoot ||
+		normalizedCandidate.startsWith(`${normalizedProjectRoot}/`)
+	);
+}
+
+function getLowercaseBasename(input: string): string {
+	const normalizedInput = normalizeSeparators(input);
+	return normalizedInput.split("/").pop()!.toLowerCase();
+}
+
+function getLookupKey(input: string, isBareFilename: boolean): string {
+	return isBareFilename ? getLowercaseBasename(input) : input.toLowerCase();
+}
+
+function resolveAbsolutePath(
+	input: string,
+	platform = process.platform,
+): string {
+	// Use win32.resolve for Windows paths regardless of reported platform
+	return platform === "win32" || hasWindowsDriveLetter(input)
+		? win32.resolve(input)
+		: resolve(input);
+}
+
+function isSearchableMarkdownPath(input: string): boolean {
+	return MARKDOWN_PATH_REGEX.test(input.trim());
+}
+
+/** Check if a path looks like a Windows absolute path (e.g. C:\ or C:/) */
+function hasWindowsDriveLetter(input: string): boolean {
+	return /^[a-zA-Z]:[/\\]/.test(input);
+}
+
+/** Cross-platform file existence check using Node fs (more reliable than Bun.file in compiled exes) */
+function fileExists(filePath: string): boolean {
+	try {
+		return existsSync(filePath);
+	} catch {
+		return false;
+	}
+}
+
+/** Recursively walk a directory collecting files matching `fileMatcher`, skipping ignored dirs. */
+function walkFiles(
+	dir: string,
+	root: string,
+	results: string[],
+	ignoredDirs: string[],
+	fileMatcher: (name: string) => boolean,
+): void {
+	const entries = readdirSync(dir, { withFileTypes: true }) as Dirent[];
+	for (const entry of entries) {
+		if (entry.isDirectory()) {
+			if (ignoredDirs.some((d) => d === entry.name + "/")) continue;
+			try {
+				walkFiles(join(dir, entry.name), root, results, ignoredDirs, fileMatcher);
+			} catch {
+				/* skip dirs we can't read */
+			}
+		} else if (entry.isFile() && fileMatcher(entry.name)) {
+			const relative = join(dir, entry.name)
+				.slice(root.length + 1)
+				.replace(/\\/g, "/");
+			results.push(relative);
+		}
+	}
+}
+
+function walkMarkdownFiles(dir: string, root: string, results: string[], ignoredDirs: string[]): void {
+	try {
+		walkFiles(dir, root, results, ignoredDirs, (name) => /\.mdx?$/i.test(name));
+	} catch {
+		/* fail soft for markdown — preserves existing behavior */
+	}
+}
+
+// --- Code-file resolution (async, cached) ---
+
+const FILE_LIST_CACHE_TTL_MS = 30_000;
+const fileListCache = new Map<
+	string,
+	{ promise: Promise<string[] | null>; startedAt: number }
+>();
+
+function fileListCacheKey(projectRoot: string, kind: string): string {
+	return `${projectRoot}|${kind}`;
+}
+
+function startCodeWalk(projectRoot: string): Promise<string[] | null> {
+	return Promise.resolve().then(() => {
+		try {
+			const results: string[] = [];
+			walkFiles(projectRoot, projectRoot, results, CODE_IGNORED_DIRS, (name) =>
+				CODE_FILE_BASENAME_REGEX.test(name),
+			);
+			return results;
+		} catch {
+			return null;
+		}
+	});
+}
+
+/**
+ * Trigger (or return the in-flight) walk of `projectRoot` for code files.
+ * Cached for `FILE_LIST_CACHE_TTL_MS`. Storing a Promise (not a value) makes
+ * concurrent callers piggyback on the same walk — first arrival wins.
+ *
+ * Returns `null` (wrapped in Promise) when the walk fails (perms, etc).
+ */
+export function warmFileListCache(
+	projectRoot: string,
+	kind: "code",
+): Promise<string[] | null> {
+	const key = fileListCacheKey(projectRoot, kind);
+	const entry = fileListCache.get(key);
+	if (entry && Date.now() - entry.startedAt < FILE_LIST_CACHE_TTL_MS) {
+		return entry.promise;
+	}
+	const promise = startCodeWalk(projectRoot);
+	fileListCache.set(key, { promise, startedAt: Date.now() });
+	return promise;
+}
+
+/**
+ * Resolve a code-file path within a project root.
+ *
+ * Strategies:
+ *   1. Absolute path → use as-is.
+ *   2. Exact relative from project root.
+ *   3. If `baseDir` provided, literal `<baseDir>/<input>` existence check —
+ *      lets out-of-tree linked docs resolve their own relative references
+ *      (e.g. `../script.ts` in `~/notes/foo.md` finds `~/script.ts`).
+ *   4. Case-insensitive suffix match against the cached file list:
+ *      - bare basename input → match any file with that basename;
+ *      - input with `/` → match files whose path equals or ends with `/<input>`
+ *        on a segment boundary (so `editor/App.tsx` matches `packages/editor/App.tsx`
+ *        but not `myeditor/App.tsx`).
+ *
+ * `..` segments in the input are honored: only `./` is stripped before suffix
+ * matching. `../foo.ts` without a `baseDir` correctly falls through to
+ * not_found rather than fabricating a match against `foo.ts` somewhere in cwd.
+ */
+export async function resolveCodeFile(
+	input: string,
+	projectRoot: string,
+	baseDir?: string,
+): Promise<ResolveResult> {
+	const originalInput = input.trim();
+	const unquotedInput = stripWrappingQuotes(originalInput);
+	const normalizedInput = normalizeUserPathInput(unquotedInput);
+	const searchInput = normalizeSeparators(normalizedInput);
+
+	if (!searchInput) {
+		return { kind: "not_found", input: originalInput };
+	}
+
+	if (isAbsoluteNormalizedUserPath(normalizedInput)) {
+		const absolutePath = resolveAbsolutePath(normalizedInput);
+		if (fileExists(absolutePath)) {
+			return { kind: "found", path: absolutePath };
+		}
+		return { kind: "not_found", input: originalInput };
+	}
+
+	const fromRoot = resolve(projectRoot, searchInput);
+	if (isWithinProjectRoot(fromRoot, projectRoot) && fileExists(fromRoot)) {
+		return { kind: "found", path: fromRoot };
+	}
+
+	if (baseDir) {
+		const fromBase = resolve(baseDir, searchInput);
+		if (fileExists(fromBase)) {
+			return { kind: "found", path: fromBase };
+		}
+	}
+
+	const fileList = await warmFileListCache(projectRoot, "code");
+	if (fileList === null) {
+		return { kind: "unavailable", input: originalInput };
+	}
+
+	// Strip leading `./` so suffix matching works on inputs like
+	// `./editor/App.tsx` — file list entries never carry that segment.
+	// `../` is intentionally NOT stripped: `..` is meaningful (escape parent),
+	// not noise. If we can't honor it via baseDir, the input has no
+	// suffix-match equivalent in the in-tree file list.
+	const cleanedInput = searchInput.replace(/^(?:\.\/)+/, "");
+	if (!cleanedInput || cleanedInput.startsWith("../")) {
+		return { kind: "not_found", input: originalInput };
+	}
+	const target = cleanedInput.toLowerCase();
+	const isBareFilename = !cleanedInput.includes("/");
+	const matches: string[] = [];
+
+	for (const f of fileList) {
+		const fl = f.toLowerCase();
+		if (isBareFilename) {
+			const base = fl.split("/").pop();
+			if (base === target) matches.push(resolve(projectRoot, f));
+		} else {
+			if (fl === target || fl.endsWith("/" + target)) {
+				matches.push(resolve(projectRoot, f));
+			}
+		}
+	}
+
+	if (matches.length === 1) {
+		return { kind: "found", path: matches[0] };
+	}
+	if (matches.length > 1) {
+		return { kind: "ambiguous", input: originalInput, matches };
+	}
+	return { kind: "not_found", input: originalInput };
+}
+
+/**
+ * Resolve a markdown file path within a project root.
+ *
+ * @param input - User-provided path (absolute, relative, or bare filename)
+ * @param projectRoot - Project root directory to search within
+ */
+function resolveMarkdownFileCore(
+	input: string,
+	projectRoot: string,
+): ResolveResult {
+	const normalizedInput = normalizeUserPathInput(input);
+	const searchInput = normalizeSeparators(normalizedInput);
+	const isBareFilename = !searchInput.includes("/");
+	const targetLookupKey = getLookupKey(searchInput, isBareFilename);
+
+	// Restrict to markdown files
+	if (!isSearchableMarkdownPath(normalizedInput)) {
+		return { kind: "not_found", input };
+	}
+
+	// 1. Absolute path — use as-is (no project root restriction;
+	//    the user explicitly typed the full path)
+	if (isAbsoluteNormalizedUserPath(normalizedInput)) {
+		const absolutePath = resolveAbsolutePath(normalizedInput);
+		if (fileExists(absolutePath)) {
+			return { kind: "found", path: absolutePath };
+		}
+		return { kind: "not_found", input };
+	}
+
+	// 2. Exact relative path from project root
+	const fromRoot = resolve(projectRoot, searchInput);
+	if (isWithinProjectRoot(fromRoot, projectRoot) && fileExists(fromRoot)) {
+		return { kind: "found", path: fromRoot };
+	}
+
+	// 3. Case-insensitive search (only scan markdown files)
+	const allFiles: string[] = [];
+	walkMarkdownFiles(projectRoot, projectRoot, allFiles, IGNORED_DIRS);
+	const matches: string[] = [];
+
+	for (const match of allFiles) {
+		const normalizedMatch = normalizeSeparators(match);
+		const matchLookupKey = getLookupKey(normalizedMatch, isBareFilename);
+
+		if (matchLookupKey === targetLookupKey) {
+			const full = resolve(projectRoot, normalizedMatch);
+			if (isWithinProjectRoot(full, projectRoot)) {
+				matches.push(full);
+			}
+		}
+	}
+
+	if (matches.length === 1) {
+		return { kind: "found", path: matches[0] };
+	}
+	if (matches.length > 1) {
+		const projectRootPrefix = `${normalizeComparablePath(projectRoot)}/`;
+		const relative = matches.map((match) =>
+			normalizeComparablePath(match).replace(projectRootPrefix, ""),
+		);
+		return { kind: "ambiguous", input, matches: relative };
+	}
+
+	return { kind: "not_found", input };
+}
+
+/**
+ * Resolve a markdown file path within a project root.
+ *
+ * @param input - User-provided path (absolute, relative, or bare filename)
+ * @param projectRoot - Project root directory to search within
+ */
+export function resolveMarkdownFile(
+	input: string,
+	projectRoot: string,
+): ResolveResult {
+	const originalInput = input.trim();
+	const unquotedInput = stripWrappingQuotes(originalInput);
+
+	const primary = resolveMarkdownFileCore(unquotedInput, projectRoot);
+	if (primary.kind === "found") {
+		return primary;
+	}
+	if (primary.kind === "ambiguous") {
+		return { ...primary, input: originalInput };
+	}
+
+	if (!unquotedInput.startsWith("@")) {
+		return { kind: "not_found", input: originalInput };
+	}
+
+	const normalizedInput = unquotedInput.replace(/^@+/, "");
+	if (!normalizedInput) {
+		return { kind: "not_found", input: originalInput };
+	}
+
+	const fallback = resolveMarkdownFileCore(normalizedInput, projectRoot);
+	if (fallback.kind === "found") {
+		return fallback;
+	}
+	if (fallback.kind === "ambiguous") {
+		return { ...fallback, input: originalInput };
+	}
+
+	return { kind: "not_found", input: originalInput };
+}
+
+/**
+ * Check if a directory contains at least one file matching the given extensions.
+ * Used to validate folder annotation targets.
+ *
+ * @param dirPath - Directory to search
+ * @param excludedDirs - Directory names to skip (with trailing slash, e.g. "node_modules/")
+ * @param extensions - Regex to match file extensions (default: markdown only)
+ */
+export function hasMarkdownFiles(
+	dirPath: string,
+	excludedDirs: string[] = IGNORED_DIRS,
+	extensions: RegExp = /\.mdx?$/i,
+): boolean {
+	function walk(dir: string): boolean {
+		let entries;
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			return false;
+		}
+		for (const entry of entries) {
+			if (entry.isDirectory()) {
+				if (excludedDirs.some((d) => d === entry.name + "/")) continue;
+				if (walk(join(dir, entry.name))) return true;
+			} else if (entry.isFile() && extensions.test(entry.name)) {
+				return true;
+			}
+		}
+		return false;
+	}
+	return walk(dirPath);
+}

package/3p/pi-plannotator/packages/shared/review-args.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import { parseReviewArgs } from "./review-args";
+
+describe("parseReviewArgs", () => {
+  test("defaults to auto VCS and local PR checkout", () => {
+    expect(parseReviewArgs("")).toEqual({
+      prUrl: undefined,
+      vcsType: undefined,
+      useLocal: true,
+    });
+  });
+
+  test("parses --git without a PR URL", () => {
+    expect(parseReviewArgs("--git")).toEqual({
+      prUrl: undefined,
+      vcsType: "git",
+      useLocal: true,
+    });
+  });
+
+  test("parses PR URLs before or after --git", () => {
+    expect(parseReviewArgs("--git https://github.com/acme/repo/pull/12")).toEqual({
+      prUrl: "https://github.com/acme/repo/pull/12",
+      vcsType: "git",
+      useLocal: true,
+    });
+    expect(parseReviewArgs("https://github.com/acme/repo/pull/12 --git")).toEqual({
+      prUrl: "https://github.com/acme/repo/pull/12",
+      vcsType: "git",
+      useLocal: true,
+    });
+  });
+
+  test("preserves --no-local for PR review mode", () => {
+    expect(parseReviewArgs("--no-local https://github.com/acme/repo/pull/12")).toEqual({
+      prUrl: "https://github.com/acme/repo/pull/12",
+      vcsType: undefined,
+      useLocal: false,
+    });
+  });
+
+  test("accepts argv arrays from the compiled CLI", () => {
+    expect(parseReviewArgs(["--git", "--no-local", "https://github.com/acme/repo/pull/12"])).toEqual({
+      prUrl: "https://github.com/acme/repo/pull/12",
+      vcsType: "git",
+      useLocal: false,
+    });
+  });
+
+  test("strips wrapping quotes from string and argv inputs", () => {
+    expect(parseReviewArgs(`--git "https://github.com/acme/repo/pull/12"`).prUrl)
+      .toBe("https://github.com/acme/repo/pull/12");
+    expect(parseReviewArgs(["--git", "\"https://github.com/acme/repo/pull/12\""]).prUrl)
+      .toBe("https://github.com/acme/repo/pull/12");
+  });
+
+  test("keeps non-url positional input as local review mode", () => {
+    expect(parseReviewArgs("--git not-a-url")).toEqual({
+      prUrl: undefined,
+      vcsType: "git",
+      useLocal: true,
+    });
+  });
+});

package/3p/pi-plannotator/packages/shared/review-args.ts

@@ -0,0 +1,85 @@
+import type { VcsSelection } from "./vcs-core";
+import { stripWrappingQuotes } from "./resolve-file";
+
+export interface ParsedReviewArgs {
+  prUrl?: string;
+  vcsType?: VcsSelection;
+  useLocal: boolean;
+}
+
+export function parseReviewArgs(input: string | string[]): ParsedReviewArgs {
+  const tokens = Array.isArray(input)
+    ? input.map((token) => stripWrappingQuotes(token.trim())).filter(Boolean)
+    : tokenizeReviewArgs(input ?? "");
+
+  let vcsType: VcsSelection | undefined;
+  let useLocal = true;
+  const positional: string[] = [];
+
+  for (const token of tokens) {
+    switch (token) {
+      case "--git":
+        vcsType = "git";
+        break;
+      case "--local":
+        useLocal = true;
+        break;
+      case "--no-local":
+        useLocal = false;
+        break;
+      default:
+        positional.push(token);
+        break;
+    }
+  }
+
+  const target = positional[0];
+  return {
+    prUrl: target && isReviewUrl(target) ? target : undefined,
+    vcsType,
+    useLocal,
+  };
+}
+
+function isReviewUrl(value: string): boolean {
+  return value.startsWith("http://") || value.startsWith("https://");
+}
+
+function tokenizeReviewArgs(input: string): string[] {
+  const raw = input.trim();
+  if (!raw) return [];
+
+  const tokens: string[] = [];
+  let current = "";
+  let quote: "'" | "\"" | undefined;
+
+  for (let i = 0; i < raw.length; i++) {
+    const char = raw[i];
+    if (quote) {
+      if (char === quote) {
+        quote = undefined;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+
+    if (char === "'" || char === "\"") {
+      quote = char;
+      continue;
+    }
+
+    if (/\s/.test(char)) {
+      if (current) {
+        tokens.push(current);
+        current = "";
+      }
+      continue;
+    }
+
+    current += char;
+  }
+
+  if (current) tokens.push(current);
+  return tokens.map((token) => stripWrappingQuotes(token.trim())).filter(Boolean);
+}