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

package/dist/index.cjs

@@ -21,6 +21,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
+const __optique_core_doc = __toESM(require("@optique/core/doc"));
+const __optique_core_usage = __toESM(require("@optique/core/usage"));
 const node_fs = __toESM(require("node:fs"));
 const node_path = __toESM(require("node:path"));
 const __optique_core_annotations = __toESM(require("@optique/core/annotations"));
@@ -329,7 +331,8 @@ function createEnvContext(options = {}) {
 * 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.
+* with `sourceOnly` documentation, such as `fail()`, receive independent
+* environment records. Use `documentation.description` for purpose text.
 *
 * @param parser Parser that reads CLI values.
 * @param options Environment binding options.
@@ -448,12 +451,20 @@ function bindEnv(parser, options) {
 			const defaultValue = upperDefaultValue ?? options.default;
 			const docs = parser.getDocFragments(state, defaultValue);
 			const name = `${options.context.prefix}${options.key}`;
+			const hidden = (0, __optique_core_usage.isDocHidden)(options.documentation?.hidden);
+			const visibleEntry = docs.fragments.some((fragment) => (fragment.type === "entry" ? [fragment] : fragment.entries).some((entry) => !(0, __optique_core_doc.isDocEntryHidden)(entry) && (0, __optique_core_usage.formatUsageTerm)(entry.term, { context: "doc" }).trim() !== ""));
+			const ownBindings = docs.sourceOnly === true || (options.documentation?.description?.length ?? 0) > 0 && visibleEntry ? [{
+				name,
+				...options.documentation
+			}] : [];
+			const bindings = [...ownBindings, ...docs.environmentBindings ?? []];
 			const attach = (entry) => ({
 				...entry,
-				envVars: [...new Set([name, ...entry.envVars ?? []])]
+				envVars: [...new Set([...hidden ? [] : [name], ...entry.envVars ?? []])]
 			});
 			return {
 				...docs,
+				...bindings.length > 0 && { environmentBindings: bindings },
 				fragments: docs.fragments.map((fragment) => fragment.type === "entry" ? {
 					...attach(fragment),
 					type: "entry"

package/dist/index.d.cts

@@ -1,3 +1,4 @@
+import { HiddenVisibility } from "@optique/core/usage";
 import { SourceContext } from "@optique/core/context";
 import { FluentParser } from "@optique/core/fluent";
 import { Message } from "@optique/core/message";
@@ -126,6 +127,16 @@ declare function createEnvContext(options?: EnvContextOptions): EnvContext;
  * @since 1.0.0
  */
 interface BindEnvOptions<M extends Mode, TValue> {
+  /**
+   * Environment purpose and visibility, independent of CLI descriptions.
+   * This cannot expose an enclosing hidden parser. A CLI-less custom parser
+   * must declare `DocFragments.sourceOnly` to receive an independent entry.
+   * @since 1.4.0
+   */
+  readonly documentation?: {
+    readonly description?: Message;
+    readonly hidden?: HiddenVisibility;
+  };
   /**
    * The environment context to read from.
    */
@@ -172,7 +183,8 @@ interface BindEnvOptions<M extends Mode, TValue> {
  * 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.
+ * with `sourceOnly` documentation, such as `fail()`, receive independent
+ * environment records. Use `documentation.description` for purpose text.
  *
  * @param parser Parser that reads CLI values.
  * @param options Environment binding options.

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { HiddenVisibility } from "@optique/core/usage";
 import { FluentParser } from "@optique/core/fluent";
 import { Message } from "@optique/core/message";
 import { NonEmptyString, ValueParser } from "@optique/core/valueparser";
@@ -126,6 +127,16 @@ declare function createEnvContext(options?: EnvContextOptions): EnvContext;
  * @since 1.0.0
  */
 interface BindEnvOptions<M extends Mode, TValue> {
+  /**
+   * Environment purpose and visibility, independent of CLI descriptions.
+   * This cannot expose an enclosing hidden parser. A CLI-less custom parser
+   * must declare `DocFragments.sourceOnly` to receive an independent entry.
+   * @since 1.4.0
+   */
+  readonly documentation?: {
+    readonly description?: Message;
+    readonly hidden?: HiddenVisibility;
+  };
   /**
    * The environment context to read from.
    */
@@ -172,7 +183,8 @@ interface BindEnvOptions<M extends Mode, TValue> {
  * 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.
+ * with `sourceOnly` documentation, such as `fail()`, receive independent
+ * environment records. Use `documentation.description` for purpose text.
  *
  * @param parser Parser that reads CLI values.
  * @param options Environment binding options.

package/dist/index.js

@@ -1,3 +1,5 @@
+import { isDocEntryHidden } from "@optique/core/doc";
+import { formatUsageTerm, isDocHidden } from "@optique/core/usage";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { getAnnotations } from "@optique/core/annotations";
@@ -306,7 +308,8 @@ function createEnvContext(options = {}) {
 * 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.
+* with `sourceOnly` documentation, such as `fail()`, receive independent
+* environment records. Use `documentation.description` for purpose text.
 *
 * @param parser Parser that reads CLI values.
 * @param options Environment binding options.
@@ -425,12 +428,20 @@ function bindEnv(parser, options) {
 			const defaultValue = upperDefaultValue ?? options.default;
 			const docs = parser.getDocFragments(state, defaultValue);
 			const name = `${options.context.prefix}${options.key}`;
+			const hidden = isDocHidden(options.documentation?.hidden);
+			const visibleEntry = docs.fragments.some((fragment) => (fragment.type === "entry" ? [fragment] : fragment.entries).some((entry) => !isDocEntryHidden(entry) && formatUsageTerm(entry.term, { context: "doc" }).trim() !== ""));
+			const ownBindings = docs.sourceOnly === true || (options.documentation?.description?.length ?? 0) > 0 && visibleEntry ? [{
+				name,
+				...options.documentation
+			}] : [];
+			const bindings = [...ownBindings, ...docs.environmentBindings ?? []];
 			const attach = (entry) => ({
 				...entry,
-				envVars: [...new Set([name, ...entry.envVars ?? []])]
+				envVars: [...new Set([...hidden ? [] : [name], ...entry.envVars ?? []])]
 			});
 			return {
 				...docs,
+				...bindings.length > 0 && { environmentBindings: bindings },
 				fragments: docs.fragments.map((fragment) => fragment.type === "entry" ? {
 					...attach(fragment),
 					type: "entry"

package/package.json

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