Source code becomes a graph. Rules become questions.

# The fluent builder stores project_path. Extraction resolves it here.
root = os.path.abspath(project_path or os.getcwd())

# os.walk yields one directory at a time: its path,
# mutable child-directory names, and the file names inside it.
for dirpath, dirnames, filenames in os.walk(root):
    # Example before filtering: ["src", ".venv", "build"]
    # Replace this same list's contents, so os.walk sees ["src"]
    # and never descends into .venv or build.
    dirnames[:] = [
        name for name in dirnames
        if not _should_exclude_path(
            os.path.join(dirpath, name), root, exclude, is_dir=True
        )
    ]
    for filename in filenames:
        full_path = os.path.join(dirpath, filename)
        if filename.endswith(".py") and not _should_exclude_path(
            full_path, root, exclude, is_dir=False
        ):
            # Keep one stable absolute identity per Python source file.
            py_files.append(os.path.abspath(full_path))

def _extract_located_imports(file_path):
    # Decode the complete .py file into one Python string.
    try:
        with open(file_path, "r", encoding="utf-8", errors="replace") as file:
            source = file.read()
    except (OSError, IOError):
        return []

    # filename labels parser diagnostics; ast.parse does not read the file.
    try:
        tree = ast.parse(source, filename=file_path)
    except SyntaxError:
        return []

    imports = []
    ignore_directives = _find_ignore_directives(source)
    type_checking_ranges = _find_type_checking_ranges(tree)
    conditional_import_ranges = _find_conditional_import_ranges(tree)
    # Walk descendants because imports may be nested in functions or try blocks.
    for node in ast.walk(tree):
        if isinstance(node, ast.Import):
            syntax_kind = ImportKind.IMPORT
            kind = _classify_import(
                node, syntax_kind, type_checking_ranges, conditional_import_ranges
            )
            for alias in node.names:
                imports.append(_LocatedImport(
                    alias.name, kind, node.lineno, syntax_kind
                ))
        elif isinstance(node, ast.ImportFrom):
            # Relative and from-import nodes follow the same record pipeline.
            ...
        elif isinstance(node, ast.Call):
            # Only literal importlib/__import__ module names can be recorded.
            ...
    # Apply inline and next-line # archunit: ignore directives.
    return [
        item for item in imports
        if not _is_ignored_import(item, ignore_directives)
    ]

// projectFiles(explicitPath) uses that config. Without one, start at cwd.
const configFile = explicitPath ?? guessLocationOfTsconfig();

function guessLocationOfTsconfigRecursively(directory: string) {
  const names = fs.readdirSync(directory);
  if (names.includes('tsconfig.json')) {
    return path.resolve(directory, 'tsconfig.json');
  }

  const parent = path.resolve(directory, '..');
  if (parent === path.resolve(directory)) return undefined;
  // Search upward through parents, not downward through child folders.
  return guessLocationOfTsconfigRecursively(parent);
}

// The directory containing the selected config becomes the root.
const rootDir = path.dirname(path.resolve(configFile));

function visitConfig(candidate: string) {
  const config = ts.readConfigFile(candidate, ts.sys.readFile);
  const parsed = ts.parseJsonConfigFileContent(
    config.config, ts.sys, path.dirname(candidate), {}, candidate
  );

  contexts.push(parsed);
  // Project references are visited explicitly and protected by a Set.
  for (const reference of parsed.projectReferences ?? []) {
    visitConfig(ts.resolveProjectReferencePath(reference));
  }
}

const files = [...new Set(contexts.flatMap(c => c.fileNames))];
const host = ts.createCompilerHost(rootOptions);
const program = ts.createProgram({ rootNames: files, options: rootOptions, host });

for (const sourceFile of program.getSourceFiles()) {
  // At SourceFile level, this visits top-level syntax children.
  ts.forEachChild(sourceFile, node => {
    if (ts.isImportDeclaration(node)) recordImport(node, sourceFile);
  });
}