@optique/env 1.4.0-dev.2628 → 1.4.0-dev.2631

package/dist/index.cjs

@@ -326,6 +326,11 @@ function createEnvContext(options = {}) {
 * > but this env context is not, the error explicitly names the `contexts`
 * > option to aid diagnosis.
 *
+* Since 1.4.0, visible documentation entries include the full environment
+* variable name in `DocEntry.envVars`. Set `showEnvironment` on the runner
+* or formatter to display these names without reading their values. Parsers
+* without documentation entries, such as `fail()`, have no automatic entry.
+*
 * @param parser Parser that reads CLI values.
 * @param options Environment binding options.
 * @returns A parser with environment fallback behavior.
@@ -441,7 +446,22 @@ function bindEnv(parser, options) {
 		...typeof deferPromptUntilConfigResolves === "function" ? { shouldDeferCompletion: (state, exec) => deferPromptUntilConfigResolves.call(parser, state, exec) } : {},
 		getDocFragments(state, upperDefaultValue) {
 			const defaultValue = upperDefaultValue ?? options.default;
-			return parser.getDocFragments(state, defaultValue);
+			const docs = parser.getDocFragments(state, defaultValue);
+			const name = `${options.context.prefix}${options.key}`;
+			const attach = (entry) => ({
+				...entry,
+				envVars: [...new Set([name, ...entry.envVars ?? []])]
+			});
+			return {
+				...docs,
+				fragments: docs.fragments.map((fragment) => fragment.type === "entry" ? {
+					...attach(fragment),
+					type: "entry"
+				} : {
+					...fragment,
+					entries: fragment.entries.map(attach)
+				})
+			};
 		}
 	};
 	(0, __optique_core_extension.inheritOptionScope)(boundParser, parser);

package/dist/index.d.cts

@@ -169,6 +169,11 @@ interface BindEnvOptions<M extends Mode, TValue> {
  * > but this env context is not, the error explicitly names the `contexts`
  * > option to aid diagnosis.
  *
+ * Since 1.4.0, visible documentation entries include the full environment
+ * variable name in `DocEntry.envVars`. Set `showEnvironment` on the runner
+ * or formatter to display these names without reading their values. Parsers
+ * without documentation entries, such as `fail()`, have no automatic entry.
+ *
  * @param parser Parser that reads CLI values.
  * @param options Environment binding options.
  * @returns A parser with environment fallback behavior.

package/dist/index.d.ts

@@ -169,6 +169,11 @@ interface BindEnvOptions<M extends Mode, TValue> {
  * > but this env context is not, the error explicitly names the `contexts`
  * > option to aid diagnosis.
  *
+ * Since 1.4.0, visible documentation entries include the full environment
+ * variable name in `DocEntry.envVars`. Set `showEnvironment` on the runner
+ * or formatter to display these names without reading their values. Parsers
+ * without documentation entries, such as `fail()`, have no automatic entry.
+ *
  * @param parser Parser that reads CLI values.
  * @param options Environment binding options.
  * @returns A parser with environment fallback behavior.

package/dist/index.js

@@ -303,6 +303,11 @@ function createEnvContext(options = {}) {
 * > but this env context is not, the error explicitly names the `contexts`
 * > option to aid diagnosis.
 *
+* Since 1.4.0, visible documentation entries include the full environment
+* variable name in `DocEntry.envVars`. Set `showEnvironment` on the runner
+* or formatter to display these names without reading their values. Parsers
+* without documentation entries, such as `fail()`, have no automatic entry.
+*
 * @param parser Parser that reads CLI values.
 * @param options Environment binding options.
 * @returns A parser with environment fallback behavior.
@@ -418,7 +423,22 @@ function bindEnv(parser, options) {
 		...typeof deferPromptUntilConfigResolves === "function" ? { shouldDeferCompletion: (state, exec) => deferPromptUntilConfigResolves.call(parser, state, exec) } : {},
 		getDocFragments(state, upperDefaultValue) {
 			const defaultValue = upperDefaultValue ?? options.default;
-			return parser.getDocFragments(state, defaultValue);
+			const docs = parser.getDocFragments(state, defaultValue);
+			const name = `${options.context.prefix}${options.key}`;
+			const attach = (entry) => ({
+				...entry,
+				envVars: [...new Set([name, ...entry.envVars ?? []])]
+			});
+			return {
+				...docs,
+				fragments: docs.fragments.map((fragment) => fragment.type === "entry" ? {
+					...attach(fragment),
+					type: "entry"
+				} : {
+					...fragment,
+					entries: fragment.entries.map(attach)
+				})
+			};
 		}
 	};
 	inheritOptionScope(boundParser, parser);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/env",
-  "version": "1.4.0-dev.2628",
+  "version": "1.4.0-dev.2631",
   "description": "Environment variable support for Optique",
   "keywords": [
     "CLI",
@@ -60,10 +60,10 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "1.4.0-dev.2628+867c4f91"
+    "@optique/core": "1.4.0-dev.2631+0f2bd6a0"
   },
   "devDependencies": {
-    "@optique/config": "1.4.0-dev.2628+867c4f91",
+    "@optique/config": "1.4.0-dev.2631+0f2bd6a0",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",