@clue-ai/cli 0.0.3

package/src/fastapi-analyzer.mjs

@@ -0,0 +1,340 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join, relative, sep } from "node:path";
+import { createHash } from "node:crypto";
+import { buildOperationSourceKey } from "./contracts.mjs";
+
+const METHOD_PATTERN = "(get|post|put|patch|delete|head|options)";
+const ROUTE_DECORATOR = new RegExp(
+  `@(?<router>[A-Za-z_][A-Za-z0-9_]*)\\.${METHOD_PATTERN}\\(\\s*["'](?<path>[^"']+)["']`,
+  "gi",
+);
+const API_ROUTE_DECORATOR = /@(?<router>[A-Za-z_][A-Za-z0-9_]*)\.api_route\(\s*["'](?<path>[^"']+)["'][\s\S]*?methods\s*=\s*\[(?<methods>[^\]]+)\]/gi;
+const FUNCTION_PATTERN = /(?:async\s+def|def)\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\(/g;
+const ROUTER_ASSIGNMENT = /\b(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*=\s*APIRouter\s*\(/g;
+const INCLUDE_ROUTER_CALL = /\b(?<owner>[A-Za-z_][A-Za-z0-9_]*)\.include_router\s*\(/g;
+const FROM_IMPORT = /^\s*from\s+(?<module>[A-Za-z0-9_.]+|\.+[A-Za-z0-9_.]*)\s+import\s+(?<names>[A-Za-z0-9_,\s]+)$/gm;
+
+const sha256 = (value) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
+
+const readCallArgs = (source, openParenIndex) => {
+  let depth = 0;
+  let quote = null;
+  let escaped = false;
+  for (let index = openParenIndex; index < source.length; index += 1) {
+    const char = source[index];
+    if (quote) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (char === "\"" || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === "(") {
+      depth += 1;
+      continue;
+    }
+    if (char === ")") {
+      depth -= 1;
+      if (depth === 0) {
+        return source.slice(openParenIndex + 1, index);
+      }
+    }
+  }
+  throw new Error("unterminated FastAPI call expression");
+};
+
+const extractPrefix = ({ args, relativePath, callName }) => {
+  const prefixMatch = /\bprefix\s*=\s*(?<quote>["'])(?<value>[^"']*)\k<quote>/m.exec(args);
+  if (prefixMatch?.groups?.value !== undefined) {
+    return normalizePath(prefixMatch.groups.value);
+  }
+  if (/\bprefix\s*=/.test(args)) {
+    throw new Error(`${relativePath}: ${callName} uses a dynamic prefix that cannot be analyzed safely`);
+  }
+  return "";
+};
+
+const normalizePath = (path) => {
+  const normalized = path.trim().startsWith("/") ? path.trim() : `/${path.trim()}`;
+  return normalized.replace(/\/{2,}/g, "/").replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, "{$1}");
+};
+
+const combinePaths = (...parts) => {
+  const joined = parts
+    .map((part) => String(part || "").trim())
+    .filter(Boolean)
+    .map((part) => part.replace(/^\/+|\/+$/g, ""))
+    .filter(Boolean)
+    .join("/");
+  return joined ? normalizePath(joined) : "/";
+};
+
+const parseMethods = (methodsText) =>
+  methodsText
+    .split(",")
+    .map((entry) => entry.replace(/["'\s]/g, "").toUpperCase())
+    .filter(Boolean);
+
+const parseImportNames = (names) =>
+  names
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .map((entry) => {
+      const [name, alias] = entry.split(/\s+as\s+/);
+      return {
+        importedName: name.trim(),
+        localName: (alias ?? name).trim(),
+      };
+    });
+
+const normalizeModuleCandidates = (currentRelativePath, moduleName) => {
+  const currentDir = dirname(currentRelativePath);
+  if (moduleName.startsWith(".")) {
+    const leadingDots = moduleName.match(/^\.+/)?.[0].length ?? 0;
+    const rest = moduleName.slice(leadingDots);
+    const baseParts = currentDir === "." ? [] : currentDir.split(/[\\/]+/);
+    const keepParts = baseParts.slice(0, Math.max(0, baseParts.length - leadingDots + 1));
+    const moduleParts = rest ? rest.split(".") : [];
+    const base = join(...keepParts, ...moduleParts);
+    return [`${base}.py`, join(base, "__init__.py")].filter((entry) => entry !== ".py");
+  }
+  const base = moduleName.split(".").join(sep);
+  return [`${base}.py`, join(base, "__init__.py")];
+};
+
+const resolveImportFile = ({ filesByRelativePath, currentRelativePath, moduleName }) => {
+  const candidates = normalizeModuleCandidates(currentRelativePath, moduleName);
+  for (const candidate of candidates) {
+    if (filesByRelativePath.has(candidate)) {
+      return candidate;
+    }
+  }
+  for (const knownPath of filesByRelativePath.keys()) {
+    if (candidates.some((candidate) => knownPath.endsWith(candidate))) {
+      return knownPath;
+    }
+  }
+  return null;
+};
+
+const parseRouterAssignments = (source, relativePath) => {
+  const prefixes = new Map();
+  for (const match of source.matchAll(ROUTER_ASSIGNMENT)) {
+    const openParenIndex = match.index + match[0].length - 1;
+    const args = readCallArgs(source, openParenIndex);
+    prefixes.set(
+      match.groups.name,
+      extractPrefix({ args, relativePath, callName: "APIRouter" }),
+    );
+  }
+  return prefixes;
+};
+
+const parseImports = ({ source, currentRelativePath, filesByRelativePath }) => {
+  const imports = new Map();
+  for (const match of source.matchAll(FROM_IMPORT)) {
+    const targetFile = resolveImportFile({
+      filesByRelativePath,
+      currentRelativePath,
+      moduleName: match.groups.module,
+    });
+    if (!targetFile) {
+      continue;
+    }
+    for (const entry of parseImportNames(match.groups.names)) {
+      imports.set(entry.localName, {
+        file: targetFile,
+        name: entry.importedName,
+      });
+    }
+  }
+  return imports;
+};
+
+const parseIncludeRouters = ({ source, relativePath, imports }) => {
+  const includes = [];
+  for (const match of source.matchAll(INCLUDE_ROUTER_CALL)) {
+    const openParenIndex = match.index + match[0].length - 1;
+    const args = readCallArgs(source, openParenIndex);
+    const routerMatch = /^\s*(?<router>[A-Za-z_][A-Za-z0-9_]*)/.exec(args);
+    if (!routerMatch?.groups?.router) {
+      throw new Error(`${relativePath}: include_router target cannot be analyzed safely`);
+    }
+    const routerName = routerMatch.groups.router;
+    const imported = imports.get(routerName);
+    includes.push({
+      file: imported?.file ?? relativePath,
+      routerName: imported?.name ?? routerName,
+      prefix: extractPrefix({ args, relativePath, callName: "include_router" }),
+    });
+  }
+  return includes;
+};
+
+const findNextFunction = (source, fromIndex) => {
+  FUNCTION_PATTERN.lastIndex = fromIndex;
+  const match = FUNCTION_PATTERN.exec(source);
+  if (!match?.groups?.name) {
+    const snippet = source.slice(fromIndex, Math.min(source.length, fromIndex + 1200));
+    return { name: null, snippet, code_structure: extractCodeStructure(snippet) };
+  }
+  const nextDecorator = source.indexOf("\n@", match.index + 1);
+  const end = nextDecorator > match.index ? nextDecorator : Math.min(source.length, match.index + 3000);
+  const snippet = source.slice(match.index, end);
+  return {
+    name: match.groups.name,
+    snippet,
+    code_structure: extractCodeStructure(snippet),
+  };
+};
+
+const extractCodeStructure = (snippet) => {
+  const firstLine = snippet.split("\n")[0] ?? "";
+  const returnAnnotation = /\)\s*->\s*(?<annotation>[^:]+):/.exec(firstLine)?.groups?.annotation?.trim() ?? null;
+  const parameterAnnotations = [
+    ...firstLine.matchAll(/\b(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*:\s*(?<annotation>[A-Za-z_][A-Za-z0-9_.\[\], ]*)/g),
+  ].map((match) => ({
+    name: match.groups.name,
+    annotation: match.groups.annotation.trim(),
+  }));
+  const callTargets = [
+    ...snippet.matchAll(/\b(?<target>[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)+)\s*\(/g),
+  ]
+    .map((match) => match.groups.target)
+    .filter((target) => !target.startsWith("json.") && !target.startsWith("logging."));
+  const dependencyHints = [
+    ...snippet.matchAll(/\bDepends\(\s*(?<target>[A-Za-z_][A-Za-z0-9_.]*)?/g),
+  ]
+    .map((match) => match.groups.target)
+    .filter(Boolean);
+  return {
+    parameter_annotations: [...new Set(parameterAnnotations.map((entry) => `${entry.name}:${entry.annotation}`))],
+    response_annotation: returnAnnotation,
+    call_targets: [...new Set(callTargets)].slice(0, 40),
+    dependency_hints: [...new Set(dependencyHints)].slice(0, 20),
+  };
+};
+
+const routeRecord = ({
+  route,
+  method,
+  pathTemplate,
+  relativePath,
+  functionInfo,
+  decorator,
+}) => ({
+  operation_source_key: buildOperationSourceKey(method, pathTemplate),
+  method,
+  path_template: pathTemplate,
+  source: {
+    file_fingerprint: sha256(relativePath),
+    handler_fingerprint: sha256(functionInfo.name ?? `${relativePath}:${method}:${pathTemplate}`),
+    source_fingerprint: sha256(functionInfo.snippet),
+  },
+  ai_context: {
+    relative_path: relativePath,
+    route_decorator: decorator,
+    handler_name: functionInfo.name,
+    source_snippet: functionInfo.snippet,
+    code_structure: functionInfo.code_structure,
+    router_prefix: route.routerPrefix,
+    include_prefix: route.includePrefix,
+  },
+});
+
+export const analyzeFastApiRoutes = async ({ repoRoot, files }) => {
+  const records = [];
+  const filesByRelativePath = new Map();
+  for (const file of files) {
+    const source = await readFile(file, "utf8");
+    const relativePath = relative(repoRoot, file);
+    const record = { file, relativePath, source };
+    records.push(record);
+    filesByRelativePath.set(relativePath, record);
+  }
+
+  for (const record of records) {
+    record.routerPrefixes = parseRouterAssignments(record.source, record.relativePath);
+    record.imports = parseImports({
+      source: record.source,
+      currentRelativePath: record.relativePath,
+      filesByRelativePath,
+    });
+  }
+
+  const includePrefixes = new Map();
+  for (const record of records) {
+    for (const include of parseIncludeRouters({
+      source: record.source,
+      relativePath: record.relativePath,
+      imports: record.imports,
+    })) {
+      const key = `${include.file}::${include.routerName}`;
+      const current = includePrefixes.get(key) ?? [];
+      current.push(include.prefix);
+      includePrefixes.set(key, current);
+    }
+  }
+
+  const routes = [];
+  for (const record of records) {
+    const buildForDecorator = ({ match, method, decoratorPath }) => {
+      const routerName = match.groups.router;
+      const functionInfo = findNextFunction(record.source, match.index + match[0].length);
+      const key = `${record.relativePath}::${routerName}`;
+      const localRouterPrefix = record.routerPrefixes.get(routerName) ?? "";
+      const prefixes = includePrefixes.get(key) ?? [""];
+      for (const includePrefix of prefixes) {
+        routes.push(
+          routeRecord({
+            route: {
+              routerPrefix: localRouterPrefix,
+              includePrefix,
+            },
+            method,
+            pathTemplate: combinePaths(includePrefix, localRouterPrefix, decoratorPath),
+            relativePath: record.relativePath,
+            functionInfo,
+            decorator: match[0],
+          }),
+        );
+      }
+    };
+
+    for (const match of record.source.matchAll(ROUTE_DECORATOR)) {
+      buildForDecorator({
+        match,
+        method: String(match[2]).toUpperCase(),
+        decoratorPath: normalizePath(match.groups.path),
+      });
+    }
+
+    for (const match of record.source.matchAll(API_ROUTE_DECORATOR)) {
+      for (const method of parseMethods(match.groups.methods)) {
+        buildForDecorator({
+          match,
+          method,
+          decoratorPath: normalizePath(match.groups.path),
+        });
+      }
+    }
+  }
+
+  const byKey = new Map();
+  for (const route of routes) {
+    if (!byKey.has(route.operation_source_key)) {
+      byKey.set(route.operation_source_key, route);
+    }
+  }
+  return [...byKey.values()].sort((a, b) =>
+    a.operation_source_key.localeCompare(b.operation_source_key),
+  );
+};

package/src/init-tool.mjs

@@ -0,0 +1,86 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { buildInitReport, validateInitRequest } from "./contracts.mjs";
+import { applyLifecyclePlan, planLifecycleInsertions } from "./lifecycle-init.mjs";
+
+const workflowRequestPayload = (request) =>
+  JSON.stringify(
+    {
+      project_key: "${{ vars.CLUE_PROJECT_KEY }}",
+      environment: "${{ vars.CLUE_ENVIRONMENT }}",
+      service_key: request.service_key,
+      repository: {
+        provider: "github",
+        repository_id: "${{ github.repository_id }}",
+        owner: "${{ github.repository_owner }}",
+        name: "${{ github.event.repository.name }}",
+        default_branch: "${{ github.event.repository.default_branch }}",
+        merge_commit: "${{ github.sha }}",
+        workflow_run_id: "${{ github.run_id }}",
+      },
+      service: {
+        service_key: request.service_key,
+        root_path: request.allowed_source_paths[0],
+        framework: request.framework,
+        language: "python",
+      },
+      allowed_source_paths: request.allowed_source_paths,
+      excluded_source_paths: request.excluded_source_paths,
+      clue_api_base_url: "${{ vars.CLUE_API_BASE_URL }}",
+      ai_model: "${{ vars.CLUE_AI_MODEL }}",
+    },
+    null,
+    10,
+  ).trim();
+
+const workflowTemplate = (request) => `name: Clue Semantic Snapshot
+
+on:
+  push:
+
+jobs:
+  semantic-snapshot:
+    if: github.ref_name == github.event.repository.default_branch
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - name: Run Clue semantic generation
+        continue-on-error: true
+        env:
+          CLUE_API_KEY: \${{ secrets.CLUE_API_KEY }}
+          AI_PROVIDER_API_KEY: \${{ secrets.AI_PROVIDER_API_KEY }}
+        run: |
+          mkdir -p .clue
+          cat > .clue/semantic-request.runtime.json <<'JSON'
+          ${workflowRequestPayload(request)}
+          JSON
+          npx @clue-ai/cli semantic-ci --request .clue/semantic-request.runtime.json --repo .
+`;
+
+export const runInitTool = async ({
+  repoRoot,
+  request: rawRequest,
+  env = process.env,
+  lifecyclePlanner = planLifecycleInsertions,
+}) => {
+  const request = validateInitRequest(rawRequest);
+  const workflowPath = join(repoRoot, request.ci_workflow_path);
+  await mkdir(dirname(workflowPath), { recursive: true });
+  await writeFile(workflowPath, workflowTemplate(request), "utf8");
+  const lifecyclePlan = await lifecyclePlanner({ repoRoot, request, env });
+  const lifecycleResult = await applyLifecyclePlan({
+    repoRoot,
+    plan: lifecyclePlan,
+  });
+
+  return buildInitReport({
+    request,
+    lifecycleInsertions: lifecycleResult.lifecycleInsertions,
+    warnings: [
+      ...lifecycleResult.warnings,
+    ],
+  });
+};

package/src/lifecycle-init.mjs

@@ -0,0 +1,206 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+import { listAllowedSourceFiles } from "./path-policy.mjs";
+
+const API_NAMES = new Set([
+  "ClueInit",
+  "ClueIdentify",
+  "ClueSetAccount",
+  "ClueLogout",
+]);
+
+const SOURCE_EXTENSIONS = [".py", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+const MAX_CONTEXT_FILES = 180;
+const MAX_FILE_CHARS = 12_000;
+const MAX_TOTAL_CHARS = 360_000;
+
+const nonEmpty = (value, field) => {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${field} is required`);
+  }
+  return value.trim();
+};
+
+const safeRelativePath = (repoRoot, filePath) => {
+  const root = resolve(repoRoot);
+  const absolutePath = resolve(root, filePath);
+  const relativePath = relative(root, absolutePath);
+  if (
+    relativePath.startsWith("..") ||
+    isAbsolute(relativePath)
+  ) {
+    throw new Error(`edit path escapes repo root: ${filePath}`);
+  }
+  return { absolutePath, relativePath };
+};
+
+const assertApiName = (apiName) => {
+  if (!API_NAMES.has(apiName)) {
+    throw new Error(`unsupported lifecycle API: ${apiName}`);
+  }
+  return apiName;
+};
+
+const assertNoForbiddenInstrumentation = (replacement) => {
+  if (replacement.includes("ClueTrack")) {
+    throw new Error("init tool must not add broad ClueTrack instrumentation");
+  }
+  if (/data-clue-(id|key)/i.test(replacement)) {
+    throw new Error("init tool must not add data-clue-id or data-clue-key");
+  }
+};
+
+const normalizeLifecycleInsertion = (input) => ({
+  api_name: assertApiName(nonEmpty(input.api_name, "api_name")),
+  file_path: nonEmpty(input.file_path, "file_path"),
+  confidence: Math.max(0, Math.min(1, Number(input.confidence ?? 0))),
+  reason: nonEmpty(input.reason, "reason"),
+});
+
+const normalizePlan = (input) => {
+  if (!input || typeof input !== "object") {
+    throw new Error("AI lifecycle plan must be an object");
+  }
+  if (!Array.isArray(input.edits)) {
+    throw new Error("AI lifecycle plan must include edits");
+  }
+  const edits = input.edits.map((edit) => ({
+    file_path: nonEmpty(edit.file_path, "edit.file_path"),
+    find: nonEmpty(edit.find, "edit.find"),
+    replace: nonEmpty(edit.replace, "edit.replace"),
+  }));
+  const lifecycleInsertions = Array.isArray(input.lifecycle_insertions)
+    ? input.lifecycle_insertions.map(normalizeLifecycleInsertion)
+    : [];
+  return {
+    edits,
+    lifecycleInsertions,
+    warnings: Array.isArray(input.warnings)
+      ? input.warnings
+          .filter((warning) => typeof warning === "string" && warning.trim())
+          .map((warning) => warning.trim())
+      : [],
+  };
+};
+
+export const applyLifecyclePlan = async ({ repoRoot, plan: rawPlan }) => {
+  const plan = normalizePlan(rawPlan);
+  for (const edit of plan.edits) {
+    const { absolutePath } = safeRelativePath(repoRoot, edit.file_path);
+    assertNoForbiddenInstrumentation(edit.replace);
+    const current = await readFile(absolutePath, "utf8");
+    const occurrences = current.split(edit.find).length - 1;
+    if (occurrences !== 1) {
+      throw new Error(
+        `edit.find must match exactly once in ${edit.file_path}; matched ${occurrences}`,
+      );
+    }
+    await writeFile(absolutePath, current.replace(edit.find, edit.replace), "utf8");
+  }
+  return {
+    lifecycleInsertions: plan.lifecycleInsertions,
+    warnings: plan.warnings,
+  };
+};
+
+const readContextFiles = async ({ repoRoot, request }) => {
+  const files = await listAllowedSourceFiles({
+    repoRoot,
+    allowedSourcePaths: request.allowed_source_paths,
+    excludedSourcePaths: request.excluded_source_paths,
+    extensions: SOURCE_EXTENSIONS,
+  });
+  const context = [];
+  let totalChars = 0;
+  for (const absolutePath of files.slice(0, MAX_CONTEXT_FILES)) {
+    const text = await readFile(absolutePath, "utf8");
+    const snippet = text.slice(0, MAX_FILE_CHARS);
+    totalChars += snippet.length;
+    if (totalChars > MAX_TOTAL_CHARS) {
+      break;
+    }
+    context.push({
+      file_path: relative(resolve(repoRoot), absolutePath),
+      source: snippet,
+      truncated: text.length > snippet.length,
+    });
+  }
+  return context;
+};
+
+const buildLifecyclePrompt = ({ request, files }) => JSON.stringify({
+  task: "Add Clue SDK lifecycle API calls to this repository using exact text replacements.",
+  rules: [
+    "Return JSON only.",
+    "Use only exact replacements. Each find string must be copied exactly from source.",
+    "Add ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout where repository code has clear lifecycle points.",
+    "Do not add broad ClueTrack instrumentation.",
+    "Do not add data-clue-id, data-clue-key, or similar DOM tags.",
+    "Do not create route semantics files or layer files.",
+    "Prefer minimal edits that engineers can review in one PR.",
+    "If a lifecycle point is unclear, skip that edit and include a warning.",
+  ],
+  repository_context: {
+    target_tool: request.target_tool,
+    framework: request.framework,
+    project_key: request.project_key,
+    environment: request.environment,
+    service_key: request.service_key,
+  },
+  output_shape: {
+    edits: [
+      {
+        file_path: "app/main.py",
+        find: "exact original text",
+        replace: "exact replacement text",
+      },
+    ],
+    lifecycle_insertions: [
+      {
+        api_name: "ClueInit",
+        file_path: "app/main.py",
+        confidence: 0.8,
+        reason: "SDK initialized where FastAPI app is created.",
+      },
+    ],
+    warnings: ["short engineer review note"],
+  },
+  files,
+});
+
+export const planLifecycleInsertions = async ({ repoRoot, request, env }) => {
+  const apiKey = env.AI_PROVIDER_API_KEY;
+  if (!apiKey) {
+    throw new Error("AI_PROVIDER_API_KEY is required for lifecycle API insertion");
+  }
+  const files = await readContextFiles({ repoRoot, request });
+  const baseUrl = String(env.AI_PROVIDER_BASE_URL || "https://api.openai.com/v1").replace(/\/+$/, "");
+  const model = String(env.CLUE_INIT_AI_MODEL || env.CLUE_AI_MODEL || "gpt-5.4-mini");
+  const response = await fetch(`${baseUrl}/chat/completions`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      model,
+      messages: [
+        {
+          role: "system",
+          content: "You are a safe code-edit planner for Clue SDK initialization. Return schema-valid JSON only.",
+        },
+        { role: "user", content: buildLifecyclePrompt({ request, files }) },
+      ],
+      response_format: { type: "json_object" },
+    }),
+  });
+  if (!response.ok) {
+    throw new Error(`AI provider failed during lifecycle planning: ${response.status}`);
+  }
+  const body = await response.json();
+  const content = body?.choices?.[0]?.message?.content;
+  if (typeof content !== "string" || content.trim() === "") {
+    throw new Error("AI provider returned empty lifecycle plan");
+  }
+  return JSON.parse(content);
+};

package/src/path-policy.mjs

@@ -0,0 +1,75 @@
+import { readdir, stat } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+const DEFAULT_EXCLUDES = [
+  ".git",
+  ".env",
+  ".next",
+  "node_modules",
+  "dist",
+  "build",
+  "coverage",
+  "logs",
+  "tmp",
+  "vendor",
+  "__pycache__",
+];
+
+const hasExcludedPart = (relativePath, excludes) => {
+  const parts = relativePath.split(/[\\/]+/).filter(Boolean);
+  return parts.some((part) => excludes.includes(part));
+};
+
+const isInsideRoot = (root, absolutePath) => {
+  const relativePath = relative(root, absolutePath);
+  return (
+    relativePath === "" ||
+    (!relativePath.startsWith("..") && !isAbsolute(relativePath))
+  );
+};
+
+export const listAllowedSourceFiles = async ({
+  repoRoot,
+  allowedSourcePaths,
+  excludedSourcePaths,
+  extensions,
+}) => {
+  const root = resolve(repoRoot);
+  const excludes = [...new Set([...DEFAULT_EXCLUDES, ...excludedSourcePaths])];
+  const files = [];
+  const allowedExtensions = new Set(extensions);
+
+  const walk = async (absolutePath) => {
+    const relativePath = relative(root, absolutePath);
+    if (relativePath && hasExcludedPart(relativePath, excludes)) {
+      return;
+    }
+    const currentStat = await stat(absolutePath);
+    if (currentStat.isDirectory()) {
+      const entries = await readdir(absolutePath);
+      for (const entry of entries) {
+        await walk(join(absolutePath, entry));
+      }
+      return;
+    }
+    if (
+      currentStat.isFile() &&
+      [...allowedExtensions].some((extension) => absolutePath.endsWith(extension))
+    ) {
+      files.push(absolutePath);
+    }
+  };
+
+  for (const sourcePath of allowedSourcePaths) {
+    const absolutePath = resolve(root, sourcePath);
+    if (!isInsideRoot(root, absolutePath)) {
+      throw new Error(`allowed_source_paths escapes repo root: ${sourcePath}`);
+    }
+    await walk(absolutePath);
+  }
+
+  return files.sort();
+};
+
+export const listAllowedPythonFiles = async (options) =>
+  listAllowedSourceFiles({ ...options, extensions: [".py"] });