import type { AgencyProgram } from "./types.js";
/** Walk up from `startDir` looking for a sibling file named `filename`.
 *  Returns the absolute path of the first match, or `null` if no match is
 *  found before reaching the filesystem root. An optional `accept` predicate
 *  lets callers reject false-positive matches (e.g. a `package.json` with the
 *  wrong `name` field) and keep walking. */
export declare function findFileUp(startDir: string, filename: string, accept?: (absPath: string) => boolean): string | null;
/**
 * Walk up from startDir until we find a directory containing package.json.
 *
 * If `packageName` is supplied, we only accept a package.json whose `name`
 * field equals that string — useful for callers that need to find a
 * specific package root (e.g. `agency-lang`) even when intermediate
 * directories above the starting point contain unrelated package.jsons
 * (workspaces, nested tooling configs, etc.).
 */
export declare function findPackageRoot(startDir: string, packageName?: string): string;
/**
 * Returns the absolute path to the stdlib directory.
 */
export declare function getStdlibDir(): string;
/**
 * Stdlib modules that must NOT have the auto-import prelude
 * (`import { ... } from "std::index"`) prepended when parsed/compiled.
 *
 * - `index.agency` declares the very symbols the prelude imports, so
 *   wrapping it would be circular.
 * - `array.agency` re-exports those same auto-imported symbols from
 *   `std::index` for backward compatibility. A prelude-wrapped module
 *   cannot cleanly re-export a name the prelude also auto-imports (the
 *   generated `__registerTool(name)` would reference a re-export binding
 *   still in its temporal dead zone), so it must be left un-templated too.
 *
 * Centralized here because several parse/compile entry points each need
 * to make this per-file decision — keep them all going through this one
 * predicate rather than re-deriving `absPath === index.agency` inline.
 */
export declare function isNonTemplatedStdlib(absPath: string): boolean;
/**
 * Returns the absolute path to the bundled agents directory, resolved relative
 * to this compiled module (`lib/agents` in dev, `dist/lib/agents` at runtime).
 */
export declare function getAgentsDir(): string;
/**
 * Returns all .agency files in the stdlib directory (recursively) as
 * absolute paths.
 */
export declare function getStdlibFiles(): string[];
/**
 * Map an absolute stdlib .agency file path to its `std::`-qualified module
 * name (POSIX-separated, no extension). e.g. `<stdlib>/ui/table.agency`
 * -> `std::ui/table`.
 */
export declare function stdlibModuleName(absPath: string): string;
/**
 * Returns the absolute path to the tests directory.
 */
export declare function getTestDir(): string;
/**
 * Returns true if the import path is a standard library import (starts with "std::").
 */
export declare function isStdlibImport(importPath: string): boolean;
/**
 * Classification of an import path. Used by ImportPolicy to allow / reject
 * imports by category.
 *
 *   - "stdlib" — `std::*` (e.g. `std::shell`)
 *   - "pkg"    — `pkg::*` (e.g. `pkg::wikipedia`)
 *   - "local"  — relative or absolute file paths (e.g. `./util.agency`)
 *   - "node"   — bare specifiers resolved by Node (e.g. `fs`, `child_process`)
 *
 * Order is load-bearing: stdlib and pkg are checked first so that a
 * `pkg::foo.agency` style path is never mis-classified as "local".
 */
export type ImportKind = "stdlib" | "pkg" | "local" | "node";
export declare function importKind(modulePath: string): ImportKind;
/**
 * Declarative import-allow-list / deny-list. Used by both `compileSource`
 * (to reject disallowed imports up front) and `_filterImports` in the
 * stdlib (to strip them from source).
 *
 * Semantics (see isImportAllowed):
 *   - Exclude rules always win: if a path matches anything in
 *     `excludedPackages` or `excludeKinds`, it is rejected.
 *   - When all four lists are empty, every import is allowed (default-allow).
 *   - When at least one allow list is non-empty, an import must match an
 *     allowed kind OR an allowed package glob (union across the two axes).
 */
export type ImportPolicy = {
    allowedPackages?: string[];
    excludedPackages?: string[];
    allowKinds?: ImportKind[];
    excludeKinds?: ImportKind[];
};
export declare function isImportAllowed(modulePath: string, policy: ImportPolicy): boolean;
/**
 * Strip the "std::" prefix from a standard library import path.
 * If the path is not a std:: import, returns it unchanged.
 */
export declare function normalizeStdlibPath(importPath: string): string;
/**
 * Returns true if the import path is a package import (starts with "pkg::").
 */
export declare function isPkgImport(importPath: string): boolean;
/**
 * Returns true if the import path points to Agency code that the compiler
 * should follow and process (relative .agency files, std:: imports, or pkg:: imports).
 */
export declare function isAgencyImport(importPath: string): boolean;
export type AgencyImportTargetsOptions = {
    localOnly?: boolean;
};
/**
 * Return import paths that point at Agency modules from a parsed program.
 * Includes ordinary imports, `import node` statements, and re-exports.
 */
export declare function agencyImportTargets(program: AgencyProgram, options?: AgencyImportTargetsOptions): string[];
/**
 * Strip the "pkg::" prefix from a package import path.
 * If the path is not a pkg:: import, returns it unchanged.
 */
export declare function normalizePkgPath(importPath: string): string;
/**
 * Parse a pkg:: import into package name and optional subpath.
 * Validates that the specifier is well-formed and contains no path traversal.
 *
 * - "pkg::toolbox"                -> { packageName: "toolbox", subpath: undefined }
 * - "pkg::toolbox/strings"        -> { packageName: "toolbox", subpath: "strings" }
 * - "pkg::@scope/toolbox"         -> { packageName: "@scope/toolbox", subpath: undefined }
 * - "pkg::@scope/toolbox/strings" -> { packageName: "@scope/toolbox", subpath: "strings" }
 */
export declare function parsePkgImport(importPath: string): {
    packageName: string;
    subpath: string | undefined;
};
/**
 * Resolve a pkg:: import to an absolute filesystem path to the .agency file.
 * Uses createRequire rooted at the importing file's directory to find the
 * package via Node's module resolution, then reads its package.json "agency"
 * field for the entry point.
 */
export declare function resolvePkgAgencyPath(importPath: string, fromFile: string): string;
/**
 * Resolve an Agency import path to an absolute filesystem path.
 *
 * - "std::foo"       -> <package-root>/stdlib/foo.agency
 * - "std::foo/bar"   -> <package-root>/stdlib/foo/bar.agency
 * - "pkg::toolbox"   -> <node_modules>/toolbox/<agency entry>.agency
 * - "pkg::toolbox/x" -> <node_modules>/toolbox/x.agency
 * - "./foo.agency"   -> resolved relative to the importing file
 * - "./foo.js"       -> resolved relative to the importing file (non-agency, kept as-is)
 */
export declare function resolveAgencyImportPath(importPath: string, fromFile: string): string;
/**
 * Convert an Agency import path to the path that should appear in generated
 * TypeScript import statements.
 *
 * - "std::foo"      -> relative path to <stdlib-dir>/foo.js from the source file
 * - "./foo.agency"  -> "./foo.js" (relative, just extension swap)
 *
 * @param fromFile - Absolute path of the source file containing the import.
 *   Used to compute relative paths for stdlib imports. If not provided,
 *   falls back to absolute paths.
 */
export declare function toCompiledImportPath(importPath: string, fromFile?: string): string;