/**
 * 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;
/**
 * Returns all .agency files in the stdlib directory as absolute paths.
 */
export declare function getStdlibFiles(): 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;
/**
 * 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;
