@nmakarov/cli-toolkit 0.33.0 → 0.37.0

package/dist/init.cjs

@@ -1866,6 +1866,49 @@ var Params = class _Params {
       module: moduleName ?? this._currentModule
     });
   }
+  /**
+   * Report a param value that a component RESOLVED ON ITS OWN — outside
+   * Params.get() — e.g. discovered by combining its config files (the way
+   * blueprints merge defaults/aggregator/feed data). Without this, every
+   * key such a component probed for an override shows up in the
+   * --showUsedParams dump as "undefined (default)"; reporting upgrades the
+   * entry to the value the component actually works with.
+   *
+   * Attribution rules:
+   *   - entries figured from an explicit input (cli/env/options/…) are left
+   *     untouched — the component merely confirmed them, the origin stands;
+   *   - "default" entries (Params had nothing) and earlier reports are
+   *     replaced by the report;
+   *   - keys never seen by Params are appended as new entries.
+   * The LATEST report wins — a component may resolve the same key several
+   * times with increasing specificity (e.g. a blueprint re-merged for a
+   * concrete resource) and the dump should show what it settled on.
+   * Later params.get() probes that find nothing ("default") never shadow a
+   * reported value — see {@link getFiguredByModule}.
+   *
+   * @param {string} key
+   * @param {*} value - the value the component actually uses
+   * @param {string} [source="discovered"] - short origin label, e.g. "blueprint"
+   * @param {string} [moduleName] - dump section; defaults to the current module
+   */
+  reportResolved(key, value, source = "discovered", moduleName) {
+    const mod = moduleName ?? this._currentModule;
+    const mine = this.trackedParams.filter((e) => e.key === key && e.module === mod);
+    if (mine.some((e) => e.source !== "default" && !e.reported)) {
+      return;
+    }
+    this.trackedParams = this.trackedParams.filter(
+      (e) => !(e.key === key && e.module === mod)
+    );
+    this.trackedParams.push({
+      key,
+      definition: "reported",
+      value,
+      source,
+      module: mod,
+      reported: true
+    });
+  }
   /**
    * Get all tracked parameters (for --stopAfter=init)
    */
@@ -1890,12 +1933,24 @@ var Params = class _Params {
   /**
    * Get figured parameters grouped by module name.
    * Same param can appear in multiple modules (e.g. source, resource).
+   * Last occurrence per key wins, EXCEPT that an empty probe — a
+   * params.get() that found nothing ("default", undefined) — never shadows
+   * a value reported via {@link reportResolved}: components probe for
+   * overrides on every resolution cycle, and those misses say nothing about
+   * the value the component actually uses.
    */
   getFiguredByModule() {
+    const reported = /* @__PURE__ */ new Set();
+    for (const param of this.trackedParams) {
+      if (param.reported) reported.add(`${param.module}\0${param.key}`);
+    }
     const byModule = {};
     for (const param of this.trackedParams) {
       const mod = param.module;
       if (!byModule[mod]) byModule[mod] = {};
+      if (!param.reported && param.source === "default" && reported.has(`${mod}\0${param.key}`)) {
+        continue;
+      }
       byModule[mod][param.key] = { value: param.value, source: param.source };
     }
     return byModule;