projen 0.99.46 → 0.99.48

package/lib/javascript/node-package.d.ts

@@ -700,6 +700,19 @@ export declare class NodePackage extends Component {
     tryResolveDependencyVersion(dependencyName: string): string | undefined;
     synthesize(): void;
     postSynthesize(): void;
+    /**
+     * Checks whether dependencies need to be installed before dependency
+     * resolution.
+     *
+     * @returns a structured trigger describing the reason, or `undefined` if
+     * no install is needed.
+     */
+    private determineInitialInstallTrigger;
+    /**
+     * Logs user-facing information about why dependencies are being installed.
+     * Emits an info-level summary and debug-level details (reason, diff, resolutions).
+     */
+    private logInstallTrigger;
     /**
      * The command prefix to use when executing binary commands for this package
      * manager (e.g. `npx`, `pnpm exec`, `yarn`, `bunx`).
@@ -729,9 +742,11 @@ export declare class NodePackage extends Component {
     private renderDependencies;
     /**
      * Resolves any deps that do not have a specified version (e.g. `*`) and
-     * update `package.json` if needed.
+     * updates `package.json` if needed. Does not log or install — the caller
+     * is responsible for acting on the returned changes.
      *
-     * @returns `true` if package.json was updated or `false` if not.
+     * @returns list of human-readable resolution changes, or `undefined` if
+     * `package.json` does not exist. An empty array means no changes were made.
      */
     private resolveDepsAndWritePackageJson;
     private renderPackageResolutions;
@@ -752,7 +767,13 @@ export declare class NodePackage extends Component {
      */
     private resolveScriptCommand;
     private readPackageJson;
-    private installDependencies;
+    /**
+     * Runs the install or install:ci task. Does not log — the caller is
+     * responsible for informing the user before calling this method.
+     *
+     * @param _trigger the reason for the install, available for subclasses to act on.
+     */
+    protected installDependencies(_trigger: InstallTrigger): void;
     /**
      * Sets the `packageManager` field in `package.json` for corepack-managed
      * package managers (yarn berry and pnpm).
@@ -848,4 +869,32 @@ export interface YarnBerryOptions {
      */
     readonly zeroInstalls?: boolean;
 }
+/**
+ * Why a dependency install was triggered during synthesis.
+ */
+export declare enum InstallReason {
+    /** The node_modules directory does not exist. */
+    NO_NODE_MODULES = "node_modules is missing",
+    /** The package.json file was modified during synthesis. */
+    PACKAGE_JSON_CHANGED = "package.json has changed",
+    /** Wildcard dependency versions were resolved to concrete ranges. */
+    DEPS_RESOLVED = "resolved dependency versions changed"
+}
+/**
+ * Describes why dependencies need to be installed.
+ */
+export interface InstallTrigger {
+    /** The reason for the install. */
+    readonly reason: InstallReason;
+    /**
+     * A unified diff of the package.json changes.
+     * Only present when reason is `PACKAGE_JSON_CHANGED`.
+     */
+    readonly diff?: string[];
+    /**
+     * Human-readable descriptions of resolved dependency version changes.
+     * Only present when reason is `DEPS_RESOLVED`.
+     */
+    readonly resolutions?: string[];
+}
 export declare function defaultNpmToken(npmToken: string | undefined, registry: string | undefined): string | undefined;