arkanalyzer 1.0.89 → 1.0.91

package/lib/frontend/common/ModuleAnalysisConfig.js

@@ -0,0 +1,144 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Huawei Device Co., Ltd.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModuleAnalysisConfig = void 0;
+const SparseBitVector_1 = require("../../utils/SparseBitVector");
+const ModuleDepth_1 = require("./ModuleDepth");
+/**
+ * ModuleAnalysisConfig configures target module selection and load levels
+ * for module-level analysis.
+ *
+ * Target module selection uses three dimensions combined as:
+ * ```
+ * module is target ⟺ !excludedModuleIds.has(id)
+ *                    && (includedTypes.has(type) || targetModuleIds.has(id))
+ * ```
+ * Priority: exclude > type filter / ID include (union).
+ *
+ * All three dimensions use {@link SparseBitVector} for efficient O(1) membership tests.
+ * Bit indices are {@link ModuleID} (for ID include/exclude) or {@link ModuleType} enum values
+ * (for type filter).
+ *
+ * Load levels ({@link ModuleDepthLevel}) control how much data is built for ArkFile objects:
+ * - {@link loadLevel} applies to target modules (default {@link ModuleDepthLevel.BODIES}).
+ * - {@link dependencyLoadLevel} applies to dependency modules — modules in the closure but
+ *   not targets (default {@link ModuleDepthLevel.SIGNATURES}).
+ *
+ * @category core/model
+ */
+class ModuleAnalysisConfig {
+    constructor() {
+        /** Type filter: bit index = ModuleType enum value (0=PROJECT, 1=SDK, 2=OH_MODULES). */
+        this.includedTypes = new SparseBitVector_1.SparseBitVector();
+        /** Explicit include IDs: bit index = ModuleID (additive to type filter). */
+        this.targetModuleIds = new SparseBitVector_1.SparseBitVector();
+        /** Explicit exclude IDs: bit index = ModuleID (highest priority, overrides everything). */
+        this.excludedModuleIds = new SparseBitVector_1.SparseBitVector();
+        /** Load level for target modules. Default BODIES. */
+        this.loadLevel = ModuleDepth_1.ModuleDepthLevel.BODIES;
+        /** Load level for dependency modules (in closure but not targets). Default SIGNATURES. */
+        this.dependencyLoadLevel = ModuleDepth_1.ModuleDepthLevel.SIGNATURES;
+    }
+    // --- Type filter ---
+    /**
+     * Set whether all modules of the given type are included as targets.
+     * Returns this config to allow chaining.
+     */
+    setIncludeType(type, include) {
+        if (include) {
+            this.includedTypes.set(type);
+        }
+        else {
+            this.includedTypes.reset(type);
+        }
+        return this;
+    }
+    /** Check whether modules of the given type are included by the type filter. */
+    isTypeIncluded(type) {
+        return this.includedTypes.test(type);
+    }
+    // --- ID include (additive to type filter) ---
+    /**
+     * Replace the current explicit include ID set with the given IDs.
+     * Returns this config to allow chaining.
+     */
+    setTargetModuleIds(ids) {
+        this.targetModuleIds.clear();
+        ids.forEach(id => this.targetModuleIds.set(id));
+        return this;
+    }
+    /**
+     * Add a single module ID to the explicit include set.
+     * Returns this config to allow chaining.
+     */
+    addTargetModuleId(id) {
+        this.targetModuleIds.set(id);
+        return this;
+    }
+    /** Returns the explicit include ID set as a {@link SparseBitVector} (read-only, do not modify). */
+    getTargetModuleIds() {
+        return this.targetModuleIds;
+    }
+    // --- ID exclude (highest priority) ---
+    /**
+     * Replace the current explicit exclude ID set with the given IDs.
+     * Returns this config to allow chaining.
+     */
+    setExcludedModuleIds(ids) {
+        this.excludedModuleIds.clear();
+        ids.forEach(id => this.excludedModuleIds.set(id));
+        return this;
+    }
+    /**
+     * Add a single module ID to the explicit exclude set.
+     * Excluded modules are never targets, regardless of type filter or explicit include.
+     * Returns this config to allow chaining.
+     */
+    excludeModuleId(id) {
+        this.excludedModuleIds.set(id);
+        return this;
+    }
+    /** Returns the explicit exclude ID set as a {@link SparseBitVector} (read-only, do not modify). */
+    getExcludedModuleIds() {
+        return this.excludedModuleIds;
+    }
+    // --- Load levels ---
+    /**
+     * Set the {@link ModuleDepthLevel} for target modules.
+     * Returns this config to allow chaining.
+     */
+    setLoadLevel(level) {
+        this.loadLevel = level;
+        return this;
+    }
+    /** Get the {@link ModuleDepthLevel} for target modules. Default {@link ModuleDepthLevel.BODIES}. */
+    getLoadLevel() {
+        return this.loadLevel;
+    }
+    /**
+     * Set the {@link ModuleDepthLevel} for dependency modules (in closure but not targets).
+     * Returns this config to allow chaining.
+     */
+    setDependencyLoadLevel(level) {
+        this.dependencyLoadLevel = level;
+        return this;
+    }
+    /** Get the {@link ModuleDepthLevel} for dependency modules. Default {@link ModuleDepthLevel.SIGNATURES}. */
+    getDependencyLoadLevel() {
+        return this.dependencyLoadLevel;
+    }
+}
+exports.ModuleAnalysisConfig = ModuleAnalysisConfig;

package/lib/frontend/common/ModuleBuilder.d.ts

@@ -0,0 +1,497 @@
+import { SparseBitVector } from '../../utils/SparseBitVector';
+import { ArkModule, ModuleID } from '../../core/model/ArkModule';
+import { ModuleDepGraph } from '../../core/graph/ModuleDepGraph';
+import { ModuleDepthLevel } from './ModuleDepth';
+import { ModuleAnalysisConfig } from './ModuleAnalysisConfig';
+import type { Scene } from '../../Scene';
+import type { SceneOptions } from '../../Config';
+/**
+ * ModuleBuilder holds the build logic for module-level analysis embedded in {@link Scene}.
+ *
+ * It is responsible for the build side of the module lifecycle: registration, SDK build, module
+ * preparation, dependency graph construction and SCC analysis, and module loading. Persistent
+ * state (the Canonicalizer, pathToId map, dependency graph, and progress flags) lives on the
+ * owning {@link Scene}; this class reads and writes that state through the Scene accessors.
+ *
+ * Each module is identified by its absolute path and assigned a dense integer {@link ModuleID} via
+ * the Scene's Canonicalizer using the objectIdentity strategy. The `pathToId` map on the Scene is
+ * a persistent cache that survives graph construction, allowing runtime path-based lookups.
+ *
+ * @category core/model
+ */
+export declare class ModuleBuilder {
+    private scene;
+    /** Persistent map from absolute module path to ModuleID (survives graph construction). */
+    private pathToId;
+    /** Reference to Scene's persistent memory monitor; set by initCacheManagement. */
+    private monitor?;
+    /** Reference to Scene's persistent module cache; set by initCacheManagement. */
+    private cache?;
+    /** Topological order of the current call, used for protected-set computation and Phase 2/3 reverse-topo iteration. */
+    private topoOrder;
+    /** Map from moduleId to its index in topoOrder for O(1) lookup. */
+    private topoOrderIndex?;
+    /** Load level to which protected dependency modules are downgraded during eviction Phase 2. */
+    private dependencyLoadLevel;
+    /**
+     * Estimated heapUsed bytes per file for each depth level, used for pre-load memory cost estimation.
+     * Calibrated from scene_board_ext measurements (no-eviction, no GC runs):
+     * - BODIES: P75 of per-module heapUsed-per-file at BODIES level = ~1.7MB/file
+     * - SIGNATURES: P75 of per-module heapUsed-per-file at SIGNATURES level = ~700KB/file
+     * - IMPORTS/META: negligible (metadata only).
+     *
+     * No-GC calibration matches production conditions (no forced GC). Without GC,
+     * heapUsed increments include uncollected garbage from parsing and type inference,
+     * which is several times larger than surviving data.
+     *
+     * Used for pre-load estimation (deciding whether eviction is needed before loading)
+     * and as a fallback for unload estimation when the heapUsed table has no entry.
+     */
+    private static readonly HEAPUSED_PER_FILE;
+    /**
+     * Ratio of memory released by downgrading from BODIES to SIGNATURES, relative to
+     * the BODIES-level heapUsed. Calibrated from GC trace test data:
+     * downgrade releases ~60% of BODIES heapUsed (method bodies + AST + source code).
+     */
+    private static readonly DOWNGRADE_RELEASE_RATIO;
+    constructor(scene: Scene);
+    /** Get a registered module by its ModuleID. Returns undefined when the id is out of bounds. */
+    getModule(id: ModuleID): ArkModule | undefined;
+    /** Look up a module by its absolute path using the pathToId cache. */
+    getModuleByPath(modulePath: string): ArkModule | undefined;
+    /** Total number of registered modules. */
+    getModuleCount(): number;
+    /**
+     * Iterate over all registered modules.
+     * Iteration order follows ModuleID assignment order (0, 1, 2, ...).
+     */
+    modulesIterator(): IterableIterator<ArkModule>;
+    /** Find the next module starting from the cursor. */
+    private nextModule;
+    /** Topologically sorted module IDs (empty before dependency analysis completes). */
+    getTopoOrder(): ModuleID[];
+    /**
+     * Resolve a dependency alias within the scope of the given module.
+     * Looks up the alias in the module's per-module alias map, then resolves the
+     * resulting ModuleID back to the depended-on ArkModule.
+     */
+    resolveAlias(moduleId: ModuleID, alias: string): ArkModule | undefined;
+    /**
+     * Resolve the final set of target module IDs from the config's three selection dimensions.
+     * Excluded IDs take precedence; type filter and explicit include IDs are unioned.
+     */
+    resolveTargetModuleIds(config: ModuleAnalysisConfig): SparseBitVector;
+    /**
+     * Compute transitive closure of module IDs reachable from the given target IDs via
+     * dependency edges (BFS over {@link ModuleDepGraph.getSuccModuleIds}).
+     * SDK modules are never included in the closure.
+     */
+    computeModuleClosureByIds(targetIds: SparseBitVector): SparseBitVector;
+    /** Filter the topological order to only include module IDs present in the given closure. */
+    getFilteredTopoOrder(closure: SparseBitVector): ModuleID[];
+    /** Get the ModuleID assigned to a registered ArkModule. */
+    getModuleId(module: ArkModule): ModuleID;
+    /** Create a {@link ModuleDepGraph} sharing the scene's module canonicalizer. */
+    createModuleDepGraph(): ModuleDepGraph;
+    /**
+     * Register a module by its absolute path. If the same path has already been registered, the
+     * existing {@link ArkModule} is returned unchanged. A new ModuleID is allocated via the
+     * Scene's Canonicalizer for first-time registrations, and cached on the module.
+     *
+     * @param modulePath - Absolute path of the module (primary identifier).
+     * @param moduleName - Optional module name (auxiliary field, e.g. "@ohos/entry").
+     * @returns The registered ArkModule (newly created or previously registered).
+     */
+    registerModule(modulePath: string, moduleName?: string): ArkModule;
+    /**
+     * Register and build SDK modules in one fused step. Each project-level SDK is treated as an
+     * {@link ArkModule} (moduleType=SDK): its files are collected, parsed, and registered into the
+     * module's `filesMap` as well as the scene's `sdkArkFilesMap`. SDK type inference and global
+     * API merge run after all SDK files are built.
+     *
+     * This method merges the former `prepareSdkModules` (registration-only) and `SDKBuilder.buildSdks`
+     * (building-only) into a single step — SDK modules are never just registered without being built.
+     *
+     * Module-level SDKs (those with `moduleName` set) are skipped entirely.
+     *
+     * Idempotent: guarded by {@link SceneBuildStage.SDK_INFERRED}.
+     */
+    buildSdkModules(): void;
+    /**
+     * Collect and build all source files for a single SDK module. Each file is parsed via
+     * {@link ArktsFrontend.buildArkFileFromSdkPath} (using the SDK name as projectName), default
+     * method bodies are built and all BodyBuilders freed, then the file is registered into both
+     * the module's `filesMap` and the scene's `sdkArkFilesMap`. C++ SDK files are skipped.
+     */
+    private buildSdkModuleFiles;
+    /**
+     * Collect source file paths for an SDK.
+     *
+     * Built-in SDK uses {@link SdkUtils.fetchBuiltInFiles} (reference-based DFS over `lib.*.d.ts`);
+     * other SDKs scan the directory with the scene's supported extensions and ignore patterns.
+     */
+    private collectSdkFiles;
+    /**
+     * Parse a single SDK source file into an ArkFile, build default method bodies, free all
+     * BodyBuilders, and register the file in both the module's `filesMap` and the scene's
+     * `sdkArkFilesMap`.
+     */
+    private parseAndRegisterSdkFile;
+    /**
+     * Read `build-profile.json5` from the project root and call
+     * {@link SdkUtils.setEsVersion} so that {@link SdkUtils.fetchBuiltInFiles} selects the correct
+     * `lib.*.d.ts` entry.
+     */
+    private setEsVersionFromBuildProfile;
+    /**
+     * Prepare modules by discovering and registering project modules and oh_modules dependencies.
+     *
+     * Reads build-profile.json5 to discover project modules, then scans oh_modules directories
+     * to discover third-party dependencies. Only basic info (paths) is registered —
+     * oh-package.json5 is NOT read and no dependency graph is built.
+     *
+     * Idempotent: if module preparation has already been completed via
+     * `Scene.setModulesRegistered(true)`, this method returns immediately.
+     * Note: this method does NOT set modulesRegistered — that is done by
+     * `Scene.analyseByModule` after both prepareModules and analyzeModuleDependencies complete.
+     */
+    prepareModules(): void;
+    /**
+     * Read build-profile.json5 from the project root and register each module as
+     * ArkModule(moduleType=PROJECT). The module's srcPath is resolved to an absolute path
+     * via path.resolve(projectDir, srcPath). oh-package.json5 is NOT read.
+     */
+    private registerProjectModules;
+    /**
+     * Scan oh_modules directories and register third-party dependencies as
+     * ArkModule(moduleType=OH_MODULES).
+     *
+     * Scans two types of oh_modules directories:
+     * 1. The project-level oh_modules/ under the project root.
+     * 2. The oh_modules/ under each registered PROJECT module's directory.
+     *
+     * A Set is used to avoid scanning the same directory twice.
+     */
+    private registerOhModulesModules;
+    /**
+     * Recursively scan a single oh_modules directory, registering discovered packages as
+     * ArkModule(moduleType=OH_MODULES).
+     *
+     * Directories starting with '@' (scoped packages) are recursed into.
+     * Regular directories have their symlinks resolved via fs.realpathSync() and are
+     * registered if not already present (deduplication by resolved real path).
+     *
+     * @param ohModulesDir - Absolute path of the oh_modules directory to scan.
+     */
+    private scanOhModulesDirectory;
+    /**
+     * Main entry point for module dependency analysis.
+     *
+     * Reads oh-package.json5 to update module names, builds the dependency graph,
+     * runs SCC detection with post-processing refinement. The topological order and SCC groups
+     * are stored inside the dependency graph on the Scene, accessed via `ModuleBuilder.getTopoOrder()`.
+     *
+     * Idempotent: if the dependency graph already exists on the Scene, this method returns immediately.
+     */
+    analyzeModuleDependencies(): void;
+    /**
+     * Build the module dependency graph by reading each module's oh-package.json5.
+     *
+     * Creates a new {@link ModuleDepGraph} with the shared canonicalizer, adds all
+     * registered modules as nodes, then resolves dependencies and adds edges.
+     * Resolved dependencies create graph edges and update the module's alias map;
+     * unresolved dependencies are recorded as unresolved dependencies. The built graph is
+     * stored on the Scene via `Scene.setModuleDepGraph()`.
+     */
+    private buildDependencyGraph;
+    /**
+     * Read the project root oh-package.json5 and extract `overrides` and `overrideDependencyMap`.
+     *
+     * Both fields are optional dependency override configurations. `overrides` maps a dependency
+     * alias to an override path (local path, file: path, or @module: reference).
+     * `overrideDependencyMap` maps a dependency alias to an override file path. When a dependency
+     * alias is present in either map, the override path is used instead of the original dependency
+     * value during resolution (checked before normal resolution).
+     *
+     * @returns An object with `overrides` and `overrideDependencyMap` string maps (empty when absent).
+     */
+    private readProjectOverrides;
+    /**
+     * Coerce a record value to a `{ [k: string]: string }` map, dropping non-string entries.
+     */
+    private toStringMap;
+    /**
+     * Extract dependency entries from oh-package.json5 content.
+     *
+     * Traverses dependencies (→ DEPENDENCIES), devDependencies (→ DEV_DEPENDENCIES),
+     * and dynamicDependencies (→ DYNAMIC), returning a [alias, value, DependencyType]
+     * triple for each entry. The DependencyType is used during SCC post-processing
+     * to determine edge removal priority when splitting oversized groups.
+     */
+    private extractDependenciesWithValues;
+    /**
+     * Resolve a dependency declaration to its target {@link ArkModule}.
+     *
+     * Resolution priority:
+     * 0. overrides / overrideDependencyMap — when the alias is present in either project-level
+     *    override map, the override path replaces the original dependency value before resolution.
+     * 1. {@link MODULE_PREFIX} prefix — find by moduleName among registered modules
+     * 2. "./", "../", or "file:" prefix — resolve as local path relative to
+     *    scopeModulePath, look up in pathToId
+     * 3. Version number — look in oh_modules directories in priority order:
+     *    a. current module's oh_modules (scopeModulePath/oh_modules/alias)
+     *    b. project-level oh_modules (projectDir/oh_modules/alias)
+     *    c. .ohpm cache (projectDir/oh_modules/.ohpm/<name>@<version>/oh_modules/<name>)
+     *    Each candidate is verified as a directory, resolved via fs.realpathSync(), then looked
+     *    up in pathToId. For .har dependencies inside the .ohpm cache, the current module's
+     *    oh_modules base is recomputed from the enclosing oh_modules ancestor.
+     *
+     * @param alias - The dependency alias (key in oh-package.json5 dependencies).
+     * @param depValue - The dependency value (path, version, or @module: reference).
+     * @param scopeModulePath - The absolute path of the source module (for relative path resolution).
+     * @param overrides - Optional project-level overrides map (alias -> override path).
+     * @param overrideDependencyMap - Optional project-level overrideDependencyMap (alias -> override path).
+     * @returns The target ArkModule if resolved, undefined otherwise.
+     */
+    private resolveDepModule;
+    /**
+     * Find a module path in the .ohpm cache directory.
+     *
+     * Mirrors {@link ModuleUtils.findModulePathInOHPM}: the cache lives at
+     * `<projectDir>/oh_modules/.ohpm` and stores packages as
+     * `<moduleName.replace('/', '+')>@<version>/oh_modules/<moduleName>`. Exact versions are
+     * matched directly; `^`-prefixed ranges pick the first directory whose version is not less
+     * than the requested minimum.
+     *
+     * @param projectDir - The project root directory.
+     * @param moduleName - The dependency alias / module name.
+     * @param version - The dependency version value (exact or `^`-prefixed).
+     * @returns The candidate directory path, or '' when not found.
+     */
+    private findModulePathInOHPM;
+    /**
+     * Read oh-package.json5 for each registered module and update moduleName.
+     *
+     * The "name" field in oh-package.json5 (e.g. "@ohos/entry") is the canonical
+     * module name used for "@module:" reference resolution. This method populates
+     * {@link ArkModule.moduleName} from oh-package.json5, overriding the short name
+     * from build-profile.json5 set during registration.
+     */
+    private updateModuleNamesFromOhPkg;
+    private registerModulePath;
+    /**
+     * Map a {@link ModuleDepthLevel} to the corresponding {@link ModuleLoadState}.
+     * Used by {@link loadModule} to translate the configured depth level into a load state.
+     */
+    private depthLevelToLoadState;
+    /**
+     * Reverse mapping of {@link depthLevelToLoadState}. Used to look up the heapUsed table
+     * entry for a module's current load state.
+     */
+    private loadStateToDepthLevel;
+    /**
+     * Run type inference on the module's files, following the same pattern as
+     * {@link Scene.inferTypes} but scoped to a single module.
+     *
+     * Reuses the file topological order already computed by {@link analyzeFileDependencies}
+     * (stored in the module's {@link FileDepGraph}) so that depended-on files are inferred first.
+     * Falls back to unsorted iteration when no file dependency graph is available (e.g. when this
+     * method is called directly without a prior {@link loadModule}).
+     *
+     * At SIGNATURES level (no method bodies), only the `preInfer` phase is effective (generic
+     * types, parameter types, signature return types, import/export resolution). At BODIES level,
+     * full type inference runs (including stmt-level propagation and return type aggregation).
+     *
+     * Does NOT call {@link Scene.getMethodsMap}(true): rebuilding the global index would clear
+     * caches for other modules. Does NOT set {@link Scene.buildStage} to TYPE_INFERRED: that is a
+     * whole-scene flag. Does NOT call {@link SdkUtils.dispose} / {@link ModuleUtils.dispose} /
+     * {@link ValueUtil.dispose}: the global caches are shared across modules and should be
+     * released by the caller after all modules are processed.
+     *
+     * @param module - The module whose files are to be type-inferred.
+     * @param times - Number of inference iterations (clamped to 1–5). Default 1.
+     */
+    inferModuleTypes(module: ArkModule, times?: number): void;
+    /**
+     * Load module data at the specified depth level.
+     *
+     * Dependencies are NOT recursively loaded here — the caller (e.g.
+     * {@link Scene.analyseByModule}) must iterate modules in topological order so that
+     * depended-on modules are loaded before their dependents.
+     *
+     * When cache management has been initialized via {@link initCacheManagement}, this method
+     * automatically checks memory before loading (evicting cached modules if over threshold)
+     * and registers the module in the cache after loading.
+     *
+     * Flow:
+     * 1. SDK modules are skipped — their file content is built by {@link buildSdkModules}, not here.
+     * 2. Idempotent: skip if the module's loadState already reaches the target load state.
+     * 3. Build module data to the effective level via {@link buildModuleToLevel}, which integrates
+     *    intra-module file dependency analysis and topological-order parsing.
+     * 4. When the effective level reaches BODIES, build method bodies (ArkBody/CFG/Stmt/Expr) via
+     *    {@link FrontendBuilder.buildModuleMethodBody}, following the same two-phase pattern as
+     *    {@link Scene.genArkFiles}.
+     * 5. When the effective level reaches SIGNATURES, run type inference on the module's files
+     *    via {@link inferModuleTypes}, referencing the logic of {@link Scene.inferTypes}.
+     * 6. Set the load state to the target level (after successful build).
+     *
+     * @param moduleId - ID of the module to load.
+     * @param depthLevel - The depth level to load the module to.
+     */
+    loadModule(moduleId: ModuleID, depthLevel?: ModuleDepthLevel): void;
+    /**
+     * Unload a module's data, releasing heavy data and resetting to NOT_LOADED state.
+     *
+     * Clears the module's filesMap (releasing ArkFile/ArkClass/ArkMethod objects), resets the
+     * file dependency graph (so that the next {@link loadModule} rebuilds IMPORTS from scratch),
+     * and sets the load state to NOT_LOADED. After unloading, {@link loadModule} can rebuild
+     * the module from scratch.
+     *
+     * SDK modules are not unloaded (their data is built by {@link buildSdkModules} and shared
+     * globally).
+     *
+     * @param moduleId - ID of the module to unload.
+     */
+    unload(moduleId: ModuleID): void;
+    /**
+     * Break all internal references between IR objects in a module's ArkFiles.
+     * Called after {@link Scene.disposeModule} to ensure that IR objects (ArkClass, ArkMethod,
+     * ArkBody, ArkField, ExportInfo, ImportInfo) do not retain each other through cross-references,
+     * allowing V8 GC to reclaim them individually.
+     */
+    private breakInternalReferences;
+    /**
+     * Initialize or update cache management for module loading.
+     *
+     * On the first call, creates a {@link ModuleCache} and {@link MemoryMonitor} and stores
+     * them persistently in {@link Scene}. On subsequent calls, reuses the persistent instances
+     * and only updates the per-call topological order.
+     *
+     * @param options - Scene options containing memoryLimitMB.
+     * @param topoOrder - Topological order of modules to be loaded (dependees before dependents).
+     * @param dependencyLoadLevel - Load level to downgrade protected dependencies to during eviction.
+     */
+    initCacheManagement(options: SceneOptions, topoOrder: ModuleID[], dependencyLoadLevel?: ModuleDepthLevel): void;
+    /**
+     * Check memory and evict cached modules if needed, before loading a new module.
+     *
+     * Estimates the heapUsed increment of the upcoming load (from the heapUsed table if available,
+     * otherwise from HEAPUSED_PER_FILE), computes a heapUsed upper limit (heapUsedLimit - estimated
+     * increment), takes one actual heapUsed measurement, and only proceeds with eviction if
+     * heapUsed exceeds the upper limit.
+     *
+     * During eviction, the heapUsed estimate is tracked via {@link HeapUsedEstimateState},
+     * decremented by the heapUsed table value of each unloaded/downgraded module.
+     */
+    private evictIfNeeded;
+    private runPhase1Eviction;
+    private runPhase2Downgrade;
+    private runPhase3Eviction;
+    /**
+     * Estimate the memory cost of loading a module at the given depth level.
+     * Used as a fallback when the heapUsed table has no entry for this module+level.
+     */
+    private estimateLoadCost;
+    /**
+     * Estimate the heapUsed increment for loading a module at the given depth level.
+     * Uses the heapUsed table value if available (from a prior first-load measurement),
+     * otherwise falls back to {@link estimateLoadCost} (fileCount × HEAPUSED_PER_FILE).
+     */
+    private estimateLoadHeapUsed;
+    /**
+     * Estimate the heapUsed decrease from unloading a module (full unload).
+     * Uses the heapUsed table value for the module's current load level,
+     * or falls back to HEAPUSED_PER_FILE estimate.
+     */
+    private estimateUnloadHeapUsedDecrease;
+    /**
+     * Estimate the heapUsed decrease from downgrading a module from its current level
+     * to a target level. Uses a ratio-based approach: downgrade releases a fixed
+     * proportion of the current-level heapUsed, avoiding the need for target-level
+     * table entries (which are never populated since downgradeModule doesn't write
+     * to the heapUsed table).
+     */
+    private estimateDowngradeHeapUsedDecrease;
+    /**
+     * Downgrade a module's loaded data to the given target level (min SIGNATURES), releasing the
+     * heavy method-body/view-tree/AST data while keeping signatures (ArkClass/method signatures,
+     * filesMap, Scene index maps) so dependents can still resolve types. No-op if already at or
+     * below the target level. Used by eviction Phase 2.
+     */
+    private downgradeModule;
+    /**
+     * Get the number of source files in a module. If the module's filesMap is empty
+     * (not yet loaded), scans the module directory.
+     */
+    private getFileCount;
+    /**
+     * Compute the hard and soft protected sets for eviction.
+     * - Hard: the current module and its direct dependencies (never evicted).
+     * - Soft: direct dependencies of not-yet-loaded modules, plus already-cached modules
+     *   at later topo positions (to avoid reload overhead).
+     */
+    private computeProtectedSets;
+    /**
+     * Build module data to the specified depth level, integrating intra-module file dependency
+     * analysis into the build flow.
+     *
+     * Two-phase build for level > IMPORTS:
+     * 1. Ensure ArkFile shells exist (create if filesMap is empty, reuse otherwise).
+     * 2. Build all files to IMPORTS level (lightweight import/export parsing, no dependency on
+     *    other files in the module).
+     * 3. Analyze intra-module file dependencies → compute topological order (moved here from
+     *    {@link loadModule} so it is part of the build-to-level flow).
+     * 4. For level > IMPORTS: upgrade each file to the target level (SIGNATURES/BODIES) in
+     *    topological order, so that depended-on files are parsed first.
+     *
+     * For level == META: only shells are created (no content).
+     * For level == IMPORTS: steps 1-3 (topoOrder available for later type inference).
+     * For level >= SIGNATURES: steps 1-4 (signatures built in topoOrder).
+     *
+     * The {@link ArkModule.hasFileTopoOrder} flag is used to detect whether IMPORTS was already
+     * built (e.g. when upgrading from IMPORTS to SIGNATURES), avoiding redundant re-parsing.
+     *
+     * @param module - The module to build.
+     * @param level - The target depth level.
+     */
+    buildModuleToLevel(module: ArkModule, level: ModuleDepthLevel): void;
+    /**
+     * Analyze file-to-file dependencies within a module using the import/export `from` specifiers
+     * populated at IMPORTS level.
+     *
+     * Builds a {@link FileDepGraph}, resolves relative `from` specifiers to file paths within the
+     * same module, adds dependency edges, computes a topological order via SCC detection, and
+     * stores the graph on the {@link ArkModule}. The topological order is retained inside the
+     * FileDepGraph and queried via {@link ArkModule.hasFileTopoOrder}.
+     *
+     * - Only relative `from` specifiers (`./`, `../`) are resolved; bare specifiers are ignored.
+     * - Resolution matches the specifier against already-existing ArkFile paths in the module's filesMap.
+     * - Only files within the module (present in the module's filesMap) get edges; external files are ignored.
+     *
+     * @param module - The module whose files are analyzed.
+     */
+    analyzeFileDependencies(module: ArkModule): void;
+    /**
+     * Collect all `from` specifiers from an ArkFile's import and export infos.
+     * Duplicate specifiers are deduplicated.
+     */
+    private collectFromSpecifiers;
+    /**
+     * Resolve a relative `from` specifier (e.g. `./b`, `../utils/helper`) to an absolute file path
+     * that exists as an already-built ArkFile in the module.
+     *
+     * Resolution matches against the keys of {@link pathToFile} (the module's already-generated
+     * ArkFile paths) instead of probing the filesystem:
+     *
+     * 1. The specifier as-is (may already include an extension).
+     * 2. The specifier with each unique extension found among existing ArkFile paths appended.
+     * 3. The specifier as a directory: look for an index file whose path is in {@link pathToFile}.
+     *
+     * @param from - The relative from specifier (starts with `./` or `../`).
+     * @param arkFile - The file containing the import/export (base for relative resolution).
+     * @param pathToFile - Map of already-built ArkFile paths in the module.
+     * @returns The resolved absolute file path, or undefined if not found.
+     */
+    private resolveFromSpecifier;
+}
+//# sourceMappingURL=ModuleBuilder.d.ts.map

package/lib/frontend/common/ModuleBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ModuleBuilder.d.ts","sourceRoot":"","sources":["../../../src/frontend/common/ModuleBuilder.ts"],"names":[],"mappings":"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"}