@bamboocss/parser 1.45.4 → 1.46.0

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { Context, DeadImport, ParserOptions, StyleDecoder, Stylesheet } from "@bamboocss/core";
 import { ArtifactId, BambooHooks, ConfigTsOptions, CssArtifactType, LoadConfigResult, ParserResultConfigureOptions, ParserResultInterface, ResultItem, Runtime, SpecFile, SpecType, SpecTypeMap } from "@bamboocss/types";
-import { FileSystemRefreshResult, Project as Project$1, ProjectOptions as ProjectOptions$1, SourceFile } from "ts-morph";
+import { FileSystemRefreshResult, Project as Project$1, ProjectOptions as ProjectOptions$1, SourceFile, ts } from "ts-morph";
+import { ResolveModule } from "@bamboocss/extractor";
 
 //#region ../generator/dist/index.d.cts
 //#region src/generator.d.ts
@@ -219,9 +220,6 @@ declare class Generator extends Context {
  * Get CSS for a specific theme
  */
 //#endregion
-//#region src/imported-recipes.d.ts
-type ResolveModule = (specifier: string, from: SourceFile) => SourceFile | undefined;
-//#endregion
 //#region src/unresolved-styles.d.ts
 interface UnresolvedStyle {
   /**
@@ -277,6 +275,8 @@ declare class ParserResult implements ParserResultInterface {
   pattern: Map<string, Set<ResultItem>>;
   filePath: string | undefined;
   encoder: ParserOptions['encoder'];
+  /** Resolver targets crossed while extracting values which contributed CSS. */
+  private dependencies;
   /**
    * `css()` calls whose styles the build could not fully see.
    *
@@ -355,6 +355,17 @@ declare class ParserResult implements ParserResultInterface {
   setRecipe(recipeName: string, result: ResultItem): void;
   isEmpty(): boolean;
   setFilePath(filePath: string): this;
+  /** @internal Called only by the extractor-facing resolver, not by import classification. */
+  addDependency(filePath: string): void;
+  /**
+   * Local source paths crossed while resolving values this extraction actually encoded.
+   *
+   * The Project ledger deliberately records every local import, including ordinary runtime
+   * bindings. Box nodes retain the declaration node followed while resolving a style value,
+   * so this is the narrow semantic target set consumers can feed back to that ledger to recover
+   * re-export/barrel paths without watching unrelated imports.
+   */
+  getDependencies(): string[];
   merge(result: ParserResult): this;
   toArray(): ResultItem[];
   toJSON(): {
@@ -387,31 +398,73 @@ resolveModule?: ResolveModule) => ParserResult | undefined;
 //#endregion
 //#region src/project.d.ts
 interface ProjectOptions extends ProjectOptions$1 {
+  /**
+   * Snapshot `getFiles()` now, but defer reading and parsing that inventory until a source
+   * graph operation. `BambooContext` opts into this; standalone Projects remain eager.
+   *
+   * @internal
+   */
+  deferInitialSourceFiles?: boolean;
   readFile: Runtime['fs']['readFileSync'];
   getFiles(): string[];
   hooks: Partial<BambooHooks>;
   parserOptions: ParserOptions;
+  /** @internal Exact tsconfig files which produced the current compiler resolution options. */
+  resolutionConfigFiles?: readonly string[];
   tsOptions?: ConfigTsOptions;
 }
+/** @internal One stable local module-resolution observation from a source AST. */
+interface ResolutionFact {
+  readonly importer: string;
+  readonly target: string | null;
+  readonly specifier: string;
+  readonly kind: 'import' | 'export';
+  readonly ordinal: number;
+}
+/** @internal Exact semantic closure plus missing local paths which can redirect it. */
+interface ResolutionReadSet {
+  readonly dependencies: readonly string[];
+  readonly pendingCandidates: readonly string[];
+}
+/** @internal Deterministic filesystem work performed by the Project-owned resolver. */
+interface ResolutionWork {
+  readonly moduleResolutionsAttempted: number;
+  readonly sourceFilesAdded: number;
+  readonly sourceFilesRead: number;
+}
 declare class Project {
-  private options;
-  project: Project$1;
+  #private;
+  /**
+   * Source-loading contract for the opt-in deferred mode:
+   *
+   * - materializing: `project`, `getSourceFile`, `getDependents`, every create/add/remove/reload
+   *   API, and non-JSON `parseSourceFile`;
+   * - graph-independent: `files`, `parser`, `parserOptions`, `readFile`, `getFiles`, the
+   *   resolution-ledger/work getters, `getUnresolvedImporters`, `parseJson`/JSON
+   *   `parseSourceFile`, `transformFile`, `classify`.
+   *
+   * Graph-independent means outside the atomic preload. While it is `loading`, every public
+   * wrapper entry rejects reentrancy before returning live state or invoking a callback.
+   *
+   * Private resolution and dependency helpers are reachable only after a materializing parse.
+   */
   parser: ReturnType<typeof createParser>;
+  project: Project$1;
+  private options;
   get parserOptions(): ParserOptions;
   constructor(options: ProjectOptions);
   get files(): string[];
-  /**
-   * Reverse dependency graph: imported file -> files importing it, both keyed on
-   * the source file's own normalized path so lookups match regardless of whether
-   * the caller passed a relative, aliased or platform-specific path.
-   *
-   * Populated while parsing. Cross-file extraction folds imported values into the
-   * importer's output, so editing a shared style file has to re-parse everyone who
-   * imports it — re-parsing only the changed file leaves consumers stale.
-   */
+  /** Reverse dependency graph: resolved target -> importers. */
   private dependents;
   /** Forward edges, so a re-parse can retract exactly the previous ones. */
   private dependencies;
+  /**
+   * Deleted targets retain their last importers until those importers are reparsed.
+   *
+   * A watcher commonly removes first and asks second. The ledger itself must say the target
+   * is now unresolved, while this one-turn tombstone keeps that unlink query answerable.
+   */
+  private removedDependents;
   /**
    * Path as a caller spells it -> the source file's own path.
    *
@@ -423,30 +476,33 @@ declare class Project {
    */
   private canonicalPaths;
   /**
-   * Files holding at least one import whose specifier resolved to nothing.
+   * Files holding at least one import whose local resolution is not final.
    *
-   * A broken or not-yet-created import produces no edge, so when the file it wants
-   * finally appears there is nothing in the graph connecting them. These importers
-   * are the only candidates for that, and the set is normally empty.
+   * A broken or not-yet-created import produces no edge. A successful fallback edge
+   * likewise cannot point at the missing higher-priority candidate that may replace it.
+   * These importers are the only candidates for either add-event transition, and the
+   * set is normally empty.
    */
   private unresolvedImporters;
-  /** Files whose imports did not all resolve when they were last parsed. */
+  /** Exact post-transform resolution facts, one immutable list per importer. */
+  private resolutionsByImporter;
+  /** One hook/transform transaction for each source revision Bamboo can semantically read. */
+  private sourcePreparations;
+  /** Paths explicitly removed through this wrapper, until an add/create observes them again. */
+  private removedSourcePaths;
+  private resolutionWork;
+  private resetResolutionState;
+  /** Files whose imports may resolve differently after a local file appears. */
   getUnresolvedImporters: () => string[];
+  /** @internal Immutable resolution facts in importer/AST order. */
+  getResolutionLedger: () => readonly ResolutionFact[];
+  /** @internal Every distinct local target represented by the current ledger. */
+  getResolvedSourceFiles: () => readonly string[];
+  /** @internal Deterministic resolver/add/read work, for regression assertions. */
+  getResolutionWork: () => ResolutionWork;
   getSourceFile: (filePath: string) => SourceFile | undefined;
   /** ts-morph reports forward slashes; normalize callers' paths to match on Windows. */
   private normalizePath;
-  /**
-   * Resolves a module specifier to a file already in the project.
-   *
-   * Deliberately not `decl.getModuleSpecifierSourceFile()`: that goes through the
-   * symbol table, which forces `initializeTypeChecker` on first use and costs
-   * hundreds of ms on a cold build. `ts.resolveModuleName` is purely a filesystem
-   * lookup, and a shared cache keeps repeat specifiers off the disk.
-   *
-   * Looks the result up rather than adding it, so resolving `react` cannot pull a
-   * `.d.ts` into the project. The graph only tracks files bamboo already scans.
-   */
-  private moduleResolutionCache;
   /**
    * Everything memoized against the shape of the file tree, including the negative half.
    *
@@ -456,20 +512,74 @@ declare class Project {
    * importing it, since resolution is what finds one.
    */
   private invalidate;
-  private resolveImport;
   /**
-   * `resolveImport` in the shape a caller can use, for a specifier read off any declaration.
+   * Invalidate module/evaluator state after a resolver configuration byte changes.
+   *
+   * Unlike `resetResolutionState`, this keeps the published dependency graph long enough for
+   * an incremental consumer to take its old dependent closure. Each reparsed importer replaces
+   * its own facts under the bumped revision; unrelated graph entries remain available until
+   * they are next queried instead of forcing a whole-project rebuild.
    *
-   * Shares the module resolution cache above, so a barrel resolved while tracking
-   * dependencies is not resolved again while looking for recipes.
+   * @internal
    */
+  refreshResolutionConfiguration: (compilerOptions: ts.CompilerOptions | undefined, resolutionConfigFiles: readonly string[], replaceCompilerOptions: boolean) => void;
+  private isLocalAlias;
+  private getLocalFailedLookupCandidates;
+  private isUnresolvedLocalSpecifier;
+  private isInCheckout;
+  private resolveSpecifier;
+  private retractImporter;
+  private publishResolutionFacts;
+  private ensureResolutionFacts;
+  /** The sole cross-file source resolver supplied to parser and extractor. */
   private resolveModule;
   private trackDependencies;
+  private invalidateSourcePreparation;
+  /**
+   * Apply the parser hook and built-in transform once to one source revision.
+   *
+   * Resolver traversal is a semantic read just as surely as an explicit parse: returning a
+   * raw dependency here would let parse order decide both the value extraction sees and the
+   * downstream edges the ledger records. The transaction is published only after the AST and
+   * its facts agree. A failed or re-entered attempt restores the input AST and can be retried.
+   */
+  private prepareEffectiveSource;
+  private markTargetRemoved;
   /**
    * Every file that transitively imports `filePath`, so a watcher can re-parse the
    * consumers of an edited file. Excludes `filePath` itself.
    */
   getDependents: (filePath: string) => string[];
+  /**
+   * Every local source transitively read by `filePath`, excluding the file itself. When
+   * `targets` are supplied, retain only paths leading to one of those semantic reads.
+   *
+   * This is the forward half of `getDependents`, exposed for bundler consumers which must
+   * register the complete semantic read-set as watch files. Walking the indexed ledger closure
+   * avoids rescanning every resolution fact once per transformed module.
+   */
+  getDependencies: (filePath: string, targets?: Iterable<string>) => string[];
+  /**
+   * Exact semantic dependencies plus missing local resolver candidates which can supersede
+   * one of those dependencies.
+   *
+   * Candidate provenance stays attached to its import/export fact. Filtering those facts
+   * through the selected dependency closure keeps an unrelated runtime import—even a local
+   * alias with its own fallback—out of the watch set without asking consumers to reinterpret
+   * specifiers or scan the checkout.
+   */
+  getResolutionReadSet: (filePath: string, targets?: Iterable<string>, previous?: ResolutionReadSet) => ResolutionReadSet;
+  /**
+   * Exact resolution configuration files read by the semantic closure selected by `targets`.
+   *
+   * Package manifests stay attached to their import/export ordinal, so a runtime-only branch
+   * cannot turn an arbitrary package.json into a Builder dependency. Tsconfig files are global
+   * inputs to those same selected facts and are added only when the owner has a semantic
+   * cross-file read.
+   *
+   * @internal
+   */
+  getResolutionConfigurationFiles: (filePath: string, targets?: Iterable<string>, previous?: Iterable<string>) => readonly string[];
   createSourceFile: (filePath: string) => SourceFile;
   createSourceFiles: () => void;
   addSourceFile: (filePath: string, content: string) => SourceFile;
@@ -484,4 +594,4 @@ declare class Project {
   classify: (fileMap: Map<string, ParserResultInterface>) => import("@bamboocss/types").ClassifyReport;
 }
 //#endregion
-export { ParserResult, Project, ProjectOptions, type UnresolvedStyle, findUnresolvedStyles };
+export { ParserResult, Project, ProjectOptions, ResolutionFact, ResolutionReadSet, ResolutionWork, type UnresolvedStyle, findUnresolvedStyles };

package/dist/index.d.mts

@@ -1,4 +1,5 @@
-import { FileSystemRefreshResult, Project as Project$1, ProjectOptions as ProjectOptions$1, SourceFile } from "ts-morph";
+import { FileSystemRefreshResult, Project as Project$1, ProjectOptions as ProjectOptions$1, SourceFile, ts } from "ts-morph";
+import { ResolveModule } from "@bamboocss/extractor";
 import { Context, DeadImport, ParserOptions, StyleDecoder, Stylesheet } from "@bamboocss/core";
 import { ArtifactId, BambooHooks, ConfigTsOptions, CssArtifactType, LoadConfigResult, ParserResultConfigureOptions, ParserResultInterface, ResultItem, Runtime, SpecFile, SpecType, SpecTypeMap } from "@bamboocss/types";
 
@@ -219,9 +220,6 @@ declare class Generator extends Context {
  * Get CSS for a specific theme
  */
 //#endregion
-//#region src/imported-recipes.d.ts
-type ResolveModule = (specifier: string, from: SourceFile) => SourceFile | undefined;
-//#endregion
 //#region src/unresolved-styles.d.ts
 interface UnresolvedStyle {
   /**
@@ -277,6 +275,8 @@ declare class ParserResult implements ParserResultInterface {
   pattern: Map<string, Set<ResultItem>>;
   filePath: string | undefined;
   encoder: ParserOptions['encoder'];
+  /** Resolver targets crossed while extracting values which contributed CSS. */
+  private dependencies;
   /**
    * `css()` calls whose styles the build could not fully see.
    *
@@ -355,6 +355,17 @@ declare class ParserResult implements ParserResultInterface {
   setRecipe(recipeName: string, result: ResultItem): void;
   isEmpty(): boolean;
   setFilePath(filePath: string): this;
+  /** @internal Called only by the extractor-facing resolver, not by import classification. */
+  addDependency(filePath: string): void;
+  /**
+   * Local source paths crossed while resolving values this extraction actually encoded.
+   *
+   * The Project ledger deliberately records every local import, including ordinary runtime
+   * bindings. Box nodes retain the declaration node followed while resolving a style value,
+   * so this is the narrow semantic target set consumers can feed back to that ledger to recover
+   * re-export/barrel paths without watching unrelated imports.
+   */
+  getDependencies(): string[];
   merge(result: ParserResult): this;
   toArray(): ResultItem[];
   toJSON(): {
@@ -387,31 +398,73 @@ resolveModule?: ResolveModule) => ParserResult | undefined;
 //#endregion
 //#region src/project.d.ts
 interface ProjectOptions extends ProjectOptions$1 {
+  /**
+   * Snapshot `getFiles()` now, but defer reading and parsing that inventory until a source
+   * graph operation. `BambooContext` opts into this; standalone Projects remain eager.
+   *
+   * @internal
+   */
+  deferInitialSourceFiles?: boolean;
   readFile: Runtime['fs']['readFileSync'];
   getFiles(): string[];
   hooks: Partial<BambooHooks>;
   parserOptions: ParserOptions;
+  /** @internal Exact tsconfig files which produced the current compiler resolution options. */
+  resolutionConfigFiles?: readonly string[];
   tsOptions?: ConfigTsOptions;
 }
+/** @internal One stable local module-resolution observation from a source AST. */
+interface ResolutionFact {
+  readonly importer: string;
+  readonly target: string | null;
+  readonly specifier: string;
+  readonly kind: 'import' | 'export';
+  readonly ordinal: number;
+}
+/** @internal Exact semantic closure plus missing local paths which can redirect it. */
+interface ResolutionReadSet {
+  readonly dependencies: readonly string[];
+  readonly pendingCandidates: readonly string[];
+}
+/** @internal Deterministic filesystem work performed by the Project-owned resolver. */
+interface ResolutionWork {
+  readonly moduleResolutionsAttempted: number;
+  readonly sourceFilesAdded: number;
+  readonly sourceFilesRead: number;
+}
 declare class Project {
-  private options;
-  project: Project$1;
+  #private;
+  /**
+   * Source-loading contract for the opt-in deferred mode:
+   *
+   * - materializing: `project`, `getSourceFile`, `getDependents`, every create/add/remove/reload
+   *   API, and non-JSON `parseSourceFile`;
+   * - graph-independent: `files`, `parser`, `parserOptions`, `readFile`, `getFiles`, the
+   *   resolution-ledger/work getters, `getUnresolvedImporters`, `parseJson`/JSON
+   *   `parseSourceFile`, `transformFile`, `classify`.
+   *
+   * Graph-independent means outside the atomic preload. While it is `loading`, every public
+   * wrapper entry rejects reentrancy before returning live state or invoking a callback.
+   *
+   * Private resolution and dependency helpers are reachable only after a materializing parse.
+   */
   parser: ReturnType<typeof createParser>;
+  project: Project$1;
+  private options;
   get parserOptions(): ParserOptions;
   constructor(options: ProjectOptions);
   get files(): string[];
-  /**
-   * Reverse dependency graph: imported file -> files importing it, both keyed on
-   * the source file's own normalized path so lookups match regardless of whether
-   * the caller passed a relative, aliased or platform-specific path.
-   *
-   * Populated while parsing. Cross-file extraction folds imported values into the
-   * importer's output, so editing a shared style file has to re-parse everyone who
-   * imports it — re-parsing only the changed file leaves consumers stale.
-   */
+  /** Reverse dependency graph: resolved target -> importers. */
   private dependents;
   /** Forward edges, so a re-parse can retract exactly the previous ones. */
   private dependencies;
+  /**
+   * Deleted targets retain their last importers until those importers are reparsed.
+   *
+   * A watcher commonly removes first and asks second. The ledger itself must say the target
+   * is now unresolved, while this one-turn tombstone keeps that unlink query answerable.
+   */
+  private removedDependents;
   /**
    * Path as a caller spells it -> the source file's own path.
    *
@@ -423,30 +476,33 @@ declare class Project {
    */
   private canonicalPaths;
   /**
-   * Files holding at least one import whose specifier resolved to nothing.
+   * Files holding at least one import whose local resolution is not final.
    *
-   * A broken or not-yet-created import produces no edge, so when the file it wants
-   * finally appears there is nothing in the graph connecting them. These importers
-   * are the only candidates for that, and the set is normally empty.
+   * A broken or not-yet-created import produces no edge. A successful fallback edge
+   * likewise cannot point at the missing higher-priority candidate that may replace it.
+   * These importers are the only candidates for either add-event transition, and the
+   * set is normally empty.
    */
   private unresolvedImporters;
-  /** Files whose imports did not all resolve when they were last parsed. */
+  /** Exact post-transform resolution facts, one immutable list per importer. */
+  private resolutionsByImporter;
+  /** One hook/transform transaction for each source revision Bamboo can semantically read. */
+  private sourcePreparations;
+  /** Paths explicitly removed through this wrapper, until an add/create observes them again. */
+  private removedSourcePaths;
+  private resolutionWork;
+  private resetResolutionState;
+  /** Files whose imports may resolve differently after a local file appears. */
   getUnresolvedImporters: () => string[];
+  /** @internal Immutable resolution facts in importer/AST order. */
+  getResolutionLedger: () => readonly ResolutionFact[];
+  /** @internal Every distinct local target represented by the current ledger. */
+  getResolvedSourceFiles: () => readonly string[];
+  /** @internal Deterministic resolver/add/read work, for regression assertions. */
+  getResolutionWork: () => ResolutionWork;
   getSourceFile: (filePath: string) => SourceFile | undefined;
   /** ts-morph reports forward slashes; normalize callers' paths to match on Windows. */
   private normalizePath;
-  /**
-   * Resolves a module specifier to a file already in the project.
-   *
-   * Deliberately not `decl.getModuleSpecifierSourceFile()`: that goes through the
-   * symbol table, which forces `initializeTypeChecker` on first use and costs
-   * hundreds of ms on a cold build. `ts.resolveModuleName` is purely a filesystem
-   * lookup, and a shared cache keeps repeat specifiers off the disk.
-   *
-   * Looks the result up rather than adding it, so resolving `react` cannot pull a
-   * `.d.ts` into the project. The graph only tracks files bamboo already scans.
-   */
-  private moduleResolutionCache;
   /**
    * Everything memoized against the shape of the file tree, including the negative half.
    *
@@ -456,20 +512,74 @@ declare class Project {
    * importing it, since resolution is what finds one.
    */
   private invalidate;
-  private resolveImport;
   /**
-   * `resolveImport` in the shape a caller can use, for a specifier read off any declaration.
+   * Invalidate module/evaluator state after a resolver configuration byte changes.
+   *
+   * Unlike `resetResolutionState`, this keeps the published dependency graph long enough for
+   * an incremental consumer to take its old dependent closure. Each reparsed importer replaces
+   * its own facts under the bumped revision; unrelated graph entries remain available until
+   * they are next queried instead of forcing a whole-project rebuild.
    *
-   * Shares the module resolution cache above, so a barrel resolved while tracking
-   * dependencies is not resolved again while looking for recipes.
+   * @internal
    */
+  refreshResolutionConfiguration: (compilerOptions: ts.CompilerOptions | undefined, resolutionConfigFiles: readonly string[], replaceCompilerOptions: boolean) => void;
+  private isLocalAlias;
+  private getLocalFailedLookupCandidates;
+  private isUnresolvedLocalSpecifier;
+  private isInCheckout;
+  private resolveSpecifier;
+  private retractImporter;
+  private publishResolutionFacts;
+  private ensureResolutionFacts;
+  /** The sole cross-file source resolver supplied to parser and extractor. */
   private resolveModule;
   private trackDependencies;
+  private invalidateSourcePreparation;
+  /**
+   * Apply the parser hook and built-in transform once to one source revision.
+   *
+   * Resolver traversal is a semantic read just as surely as an explicit parse: returning a
+   * raw dependency here would let parse order decide both the value extraction sees and the
+   * downstream edges the ledger records. The transaction is published only after the AST and
+   * its facts agree. A failed or re-entered attempt restores the input AST and can be retried.
+   */
+  private prepareEffectiveSource;
+  private markTargetRemoved;
   /**
    * Every file that transitively imports `filePath`, so a watcher can re-parse the
    * consumers of an edited file. Excludes `filePath` itself.
    */
   getDependents: (filePath: string) => string[];
+  /**
+   * Every local source transitively read by `filePath`, excluding the file itself. When
+   * `targets` are supplied, retain only paths leading to one of those semantic reads.
+   *
+   * This is the forward half of `getDependents`, exposed for bundler consumers which must
+   * register the complete semantic read-set as watch files. Walking the indexed ledger closure
+   * avoids rescanning every resolution fact once per transformed module.
+   */
+  getDependencies: (filePath: string, targets?: Iterable<string>) => string[];
+  /**
+   * Exact semantic dependencies plus missing local resolver candidates which can supersede
+   * one of those dependencies.
+   *
+   * Candidate provenance stays attached to its import/export fact. Filtering those facts
+   * through the selected dependency closure keeps an unrelated runtime import—even a local
+   * alias with its own fallback—out of the watch set without asking consumers to reinterpret
+   * specifiers or scan the checkout.
+   */
+  getResolutionReadSet: (filePath: string, targets?: Iterable<string>, previous?: ResolutionReadSet) => ResolutionReadSet;
+  /**
+   * Exact resolution configuration files read by the semantic closure selected by `targets`.
+   *
+   * Package manifests stay attached to their import/export ordinal, so a runtime-only branch
+   * cannot turn an arbitrary package.json into a Builder dependency. Tsconfig files are global
+   * inputs to those same selected facts and are added only when the owner has a semantic
+   * cross-file read.
+   *
+   * @internal
+   */
+  getResolutionConfigurationFiles: (filePath: string, targets?: Iterable<string>, previous?: Iterable<string>) => readonly string[];
   createSourceFile: (filePath: string) => SourceFile;
   createSourceFiles: () => void;
   addSourceFile: (filePath: string, content: string) => SourceFile;
@@ -484,4 +594,4 @@ declare class Project {
   classify: (fileMap: Map<string, ParserResultInterface>) => import("@bamboocss/types").ClassifyReport;
 }
 //#endregion
-export { ParserResult, Project, ProjectOptions, type UnresolvedStyle, findUnresolvedStyles };
+export { ParserResult, Project, ProjectOptions, ResolutionFact, ResolutionReadSet, ResolutionWork, type UnresolvedStyle, findUnresolvedStyles };