effect 4.0.0-beta.13 → 4.0.0-beta.15

package/src/unstable/cli/GlobalFlag.ts

@@ -4,11 +4,8 @@
 
 import * as Console from "../../Console.ts"
 import * as Effect from "../../Effect.ts"
-import { dual } from "../../Function.ts"
-import * as Layer from "../../Layer.ts"
-import type { LogLevel } from "../../LogLevel.ts"
+import type { LogLevel as LogLevelType } from "../../LogLevel.ts"
 import * as Option from "../../Option.ts"
-import * as References from "../../References.ts"
 import * as ServiceMap from "../../ServiceMap.ts"
 import * as CliOutput from "./CliOutput.ts"
 import type * as Command from "./Command.ts"
@@ -51,10 +48,21 @@ export interface Action<A> {
  * @since 4.0.0
  * @category models
  */
-export interface Setting<A> {
+export interface Setting<Id extends string, A> extends ServiceMap.Service<Setting.Identifier<Id>, A> {
   readonly _tag: "Setting"
+  readonly id: Id
   readonly flag: Flag.Flag<A>
-  readonly layer: (value: A) => Layer.Layer<never>
+}
+
+/**
+ * @since 4.0.0
+ */
+export declare namespace Setting {
+  /**
+   * @since 4.0.0
+   * @category models
+   */
+  export type Identifier<Id extends string> = `effect/unstable/cli/GlobalFlag/${Id}`
 }
 
 /**
@@ -63,7 +71,7 @@ export interface Setting<A> {
  * @since 4.0.0
  * @category models
  */
-export type GlobalFlag<A> = Action<A> | Setting<A>
+export type GlobalFlag<A> = Action<A> | Setting<any, A>
 
 /* ========================================================================== */
 /* Constructors                                                               */
@@ -93,21 +101,31 @@ export const action = <A>(options: {
  * @since 4.0.0
  * @category constructors
  */
-export const setting = <A>(options: {
+export const setting = <const Id extends string>(
+  id: Id
+) =>
+<A>(options: {
   readonly flag: Flag.Flag<A>
-  readonly layer: (value: A) => Layer.Layer<never>
-}): Setting<A> => ({
-  _tag: "Setting",
-  flag: options.flag,
-  layer: options.layer
-})
+}): Setting<Id, A> => {
+  settingIdCounter += 1
+  const ref = ServiceMap.Service<Setting.Identifier<Id>, A>(
+    `effect/unstable/cli/GlobalFlag/${id}/${settingIdCounter}`
+  )
+  return Object.assign(ref, {
+    _tag: "Setting" as const,
+    id,
+    flag: options.flag
+  })
+}
+
+let settingIdCounter = 0
 
 /* ========================================================================== */
 /* Built-in Flag References                                                   */
 /* ========================================================================== */
 
 import * as CommandDescriptor from "./internal/completions/CommandDescriptor.ts"
-import * as Completions from "./internal/completions/Completions.ts"
+import * as CompletionsInternal from "./internal/completions/Completions.ts"
 import * as HelpInternal from "./internal/help.ts"
 
 /**
@@ -117,24 +135,18 @@ import * as HelpInternal from "./internal/help.ts"
  * @since 4.0.0
  * @category references
  */
-export const Help: ServiceMap.Reference<Action<boolean>> = ServiceMap.Reference(
-  "effect/cli/GlobalFlag/Help",
-  {
-    defaultValue: () =>
-      action({
-        flag: Flag.boolean("help").pipe(
-          Flag.withAlias("h"),
-          Flag.withDescription("Show help information")
-        ),
-        run: (_, { command, commandPath }) =>
-          Effect.gen(function*() {
-            const formatter = yield* CliOutput.Formatter
-            const helpDoc = yield* HelpInternal.getHelpForCommandPath(command, commandPath, Registry)
-            yield* Console.log(formatter.formatHelpDoc(helpDoc))
-          })
-      })
-  }
-)
+export const Help: Action<boolean> = action({
+  flag: Flag.boolean("help").pipe(
+    Flag.withAlias("h"),
+    Flag.withDescription("Show help information")
+  ),
+  run: (_, { command, commandPath }) =>
+    Effect.gen(function*() {
+      const formatter = yield* CliOutput.Formatter
+      const helpDoc = yield* HelpInternal.getHelpForCommandPath(command, commandPath, BuiltIns)
+      yield* Console.log(formatter.formatHelpDoc(helpDoc))
+    })
+})
 
 /**
  * The `--version` global flag.
@@ -143,22 +155,16 @@ export const Help: ServiceMap.Reference<Action<boolean>> = ServiceMap.Reference(
  * @since 4.0.0
  * @category references
  */
-export const Version: ServiceMap.Reference<Action<boolean>> = ServiceMap.Reference(
-  "effect/cli/GlobalFlag/Version",
-  {
-    defaultValue: () =>
-      action({
-        flag: Flag.boolean("version").pipe(
-          Flag.withDescription("Show version information")
-        ),
-        run: (_, { command, version }) =>
-          Effect.gen(function*() {
-            const formatter = yield* CliOutput.Formatter
-            yield* Console.log(formatter.formatVersion(command.name, version))
-          })
-      })
-  }
-)
+export const Version: Action<boolean> = action({
+  flag: Flag.boolean("version").pipe(
+    Flag.withDescription("Show version information")
+  ),
+  run: (_, { command, version }) =>
+    Effect.gen(function*() {
+      const formatter = yield* CliOutput.Formatter
+      yield* Console.log(formatter.formatVersion(command.name, version))
+    })
+})
 
 /**
  * The `--completions` global flag.
@@ -167,25 +173,20 @@ export const Version: ServiceMap.Reference<Action<boolean>> = ServiceMap.Referen
  * @since 4.0.0
  * @category references
  */
-export const CompletionsFlag: ServiceMap.Reference<
-  Action<Option.Option<"bash" | "zsh" | "fish">>
-> = ServiceMap.Reference("effect/cli/GlobalFlag/Completions", {
-  defaultValue: () =>
-    action({
-      flag: Flag.choice("completions", ["bash", "zsh", "fish", "sh"] as const)
-        .pipe(
-          Flag.optional,
-          Flag.map((v) => Option.map(v, (s) => s === "sh" ? "bash" : s)),
-          Flag.withDescription("Print shell completion script")
-        ),
-      run: (shell, { command }) =>
-        Effect.gen(function*() {
-          if (Option.isNone(shell)) return
-          const descriptor = CommandDescriptor.fromCommand(command)
-          yield* Console.log(
-            Completions.generate(command.name, shell.value, descriptor)
-          )
-        })
+export const Completions: Action<Option.Option<"bash" | "zsh" | "fish">> = action({
+  flag: Flag.choice("completions", ["bash", "zsh", "fish", "sh"] as const)
+    .pipe(
+      Flag.optional,
+      Flag.map((v) => Option.map(v, (s) => s === "sh" ? "bash" : s)),
+      Flag.withDescription("Print shell completion script")
+    ),
+  run: (shell, { command }) =>
+    Effect.gen(function*() {
+      if (Option.isNone(shell)) return
+      const descriptor = CommandDescriptor.fromCommand(command)
+      yield* Console.log(
+        CompletionsInternal.generate(command.name, shell.value, descriptor)
+      )
     })
 })
 
@@ -196,147 +197,47 @@ export const CompletionsFlag: ServiceMap.Reference<
  * @since 4.0.0
  * @category references
  */
-export const LogLevelFlag: ServiceMap.Reference<
-  Setting<Option.Option<LogLevel>>
-> = ServiceMap.Reference("effect/cli/GlobalFlag/LogLevel", {
-  defaultValue: () =>
-    setting({
-      flag: Flag.choiceWithValue(
-        "log-level",
-        [
-          ["all", "All"],
-          ["trace", "Trace"],
-          ["debug", "Debug"],
-          ["info", "Info"],
-          ["warn", "Warn"],
-          ["warning", "Warn"],
-          ["error", "Error"],
-          ["fatal", "Fatal"],
-          ["none", "None"]
-        ] as const
-      ).pipe(
-        Flag.optional,
-        Flag.withDescription("Sets the minimum log level")
-      ),
-      layer: (value) =>
-        Option.match(value, {
-          onNone: () => Layer.empty,
-          onSome: (level) => Layer.succeed(References.MinimumLogLevel, level)
-        })
-    })
+export const LogLevel: Setting<"log-level", Option.Option<LogLevelType>> = setting("log-level")({
+  flag: Flag.choiceWithValue(
+    "log-level",
+    [
+      ["all", "All"],
+      ["trace", "Trace"],
+      ["debug", "Debug"],
+      ["info", "Info"],
+      ["warn", "Warn"],
+      ["warning", "Warn"],
+      ["error", "Error"],
+      ["fatal", "Fatal"],
+      ["none", "None"]
+    ] as const
+  ).pipe(
+    Flag.optional,
+    Flag.withDescription("Sets the minimum log level")
+  )
 })
 
 /* ========================================================================== */
-/* Registry                                                                   */
+/* References                                                                 */
 /* ========================================================================== */
 
 /**
- * The ordered set of global flag references.
- * The parser iterates this set to know which flags to extract.
+ * Built-in global flags in default precedence order.
  *
  * @since 4.0.0
  * @category references
  */
-export const Registry: ServiceMap.Reference<
-  Set<ServiceMap.Reference<GlobalFlag<any>>>
-> = ServiceMap.Reference("effect/cli/GlobalFlag/Registry", {
-  defaultValue: () =>
-    new Set([
-      Help as ServiceMap.Reference<GlobalFlag<any>>,
-      Version as ServiceMap.Reference<GlobalFlag<any>>,
-      CompletionsFlag as ServiceMap.Reference<GlobalFlag<any>>,
-      LogLevelFlag as ServiceMap.Reference<GlobalFlag<any>>
-    ])
-})
-
-/* ========================================================================== */
-/* Public API                                                                 */
-/* ========================================================================== */
+export const BuiltIns: ReadonlyArray<GlobalFlag<any>> = [
+  Help,
+  Version,
+  Completions,
+  LogLevel
+]
 
 /**
- * Adds a global flag to the registry.
+ * Built-in setting context identifiers.
  *
  * @since 4.0.0
- * @category modifiers
- */
-export const add: {
-  /* ========================================================================== */
-  /* Public API                                                                 */
-  /* ========================================================================== */
-
-  /**
-   * Adds a global flag to the registry.
-   *
-   * @since 4.0.0
-   * @category modifiers
-   */
-  <A>(ref: ServiceMap.Reference<GlobalFlag<A>>): <B, E, R>(
-    self: Effect.Effect<B, E, R>
-  ) => Effect.Effect<B, E, R>
-  /* ========================================================================== */
-  /* Public API                                                                 */
-  /* ========================================================================== */
-
-  /**
-   * Adds a global flag to the registry.
-   *
-   * @since 4.0.0
-   * @category modifiers
-   */
-  <B, E, R, A>(self: Effect.Effect<B, E, R>, ref: ServiceMap.Reference<GlobalFlag<A>>): Effect.Effect<B, E, R>
-} = dual(
-  2,
-  Effect.fnUntraced(function*<B, E, R, A>(
-    self: Effect.Effect<B, E, R>,
-    ref: ServiceMap.Reference<GlobalFlag<A>>
-  ) {
-    const currentRegistry = yield* Registry
-    const nextRegistry = new Set([...currentRegistry, ref])
-    return yield* Effect.provideService(self, Registry, nextRegistry)
-  })
-)
-
-/**
- * Removes a global flag by its reference.
- *
- * @since 4.0.0
- * @category modifiers
- */
-export const remove: {
-  /**
-   * Removes a global flag by its reference.
-   *
-   * @since 4.0.0
-   * @category modifiers
-   */
-  <A>(ref: ServiceMap.Reference<GlobalFlag<A>>): <B, E, R>(
-    self: Effect.Effect<B, E, R>
-  ) => Effect.Effect<B, E, R>
-  /**
-   * Removes a global flag by its reference.
-   *
-   * @since 4.0.0
-   * @category modifiers
-   */
-  <B, E, R, A>(self: Effect.Effect<B, E, R>, ref: ServiceMap.Reference<GlobalFlag<A>>): Effect.Effect<B, E, R>
-} = dual(
-  2,
-  Effect.fnUntraced(function*<B, E, R, A>(
-    self: Effect.Effect<B, E, R>,
-    ref: ServiceMap.Reference<GlobalFlag<A>>
-  ) {
-    const currentRegistry = yield* Registry
-    const nextRegistry = new Set(currentRegistry)
-    nextRegistry.delete(ref)
-    return yield* Effect.provideService(self, Registry, nextRegistry)
-  })
-)
-
-/**
- * Removes all global flags (built-in and user-defined).
- *
- * @since 4.0.0
- * @category modifiers
+ * @category models
  */
-export const clear = <B, E, R>(self: Effect.Effect<B, E, R>): Effect.Effect<B, E, R> =>
-  Effect.provideService(self, Registry, new Set())
+export type BuiltInSettingContext = Setting.Identifier<"log-level">

package/src/unstable/cli/internal/command.ts

@@ -12,6 +12,7 @@ import { pipeArguments } from "../../../Pipeable.ts"
 import * as Predicate from "../../../Predicate.ts"
 import * as ServiceMap from "../../../ServiceMap.ts"
 import * as CliError from "../CliError.ts"
+import type * as GlobalFlag from "../GlobalFlag.ts"
 import type { ArgDoc, ExampleDoc, FlagDoc, HelpDoc, SubcommandGroupDoc } from "../HelpDoc.ts"
 import * as Param from "../Param.ts"
 import * as Primitive from "../Primitive.ts"
@@ -36,6 +37,7 @@ export interface CommandInternal<Name extends string, Input, E, R> extends Comma
   readonly config: ConfigInternal
   readonly service: ServiceMap.Service<CommandContext<Name>, Input>
   readonly annotations: ServiceMap.ServiceMap<never>
+  readonly globalFlags: ReadonlyArray<GlobalFlag.GlobalFlag<any>>
   readonly parse: (input: ParsedTokens) => Effect.Effect<Input, CliError.CliError, Environment>
   readonly handle: (
     input: Input,
@@ -88,6 +90,7 @@ export const makeCommand = <const Name extends string, Input, E, R>(options: {
   readonly config: ConfigInternal
   readonly service?: ServiceMap.Service<CommandContext<Name>, Input> | undefined
   readonly annotations?: ServiceMap.ServiceMap<never> | undefined
+  readonly globalFlags?: ReadonlyArray<GlobalFlag.GlobalFlag<any>> | undefined
   readonly description?: string | undefined
   readonly shortDescription?: string | undefined
   readonly alias?: string | undefined
@@ -101,6 +104,7 @@ export const makeCommand = <const Name extends string, Input, E, R>(options: {
   const service = options.service ?? ServiceMap.Service<CommandContext<Name>, Input>(`${TypeId}/${options.name}`)
   const config = options.config
   const annotations = options.annotations ?? ServiceMap.empty()
+  const globalFlags = options.globalFlags ?? []
   const subcommands = options.subcommands ?? []
 
   const handle = (
@@ -191,6 +195,7 @@ export const makeCommand = <const Name extends string, Input, E, R>(options: {
     name: options.name,
     examples: options.examples ?? [],
     annotations,
+    globalFlags,
     subcommands,
     config,
     service,

package/src/unstable/cli/internal/help.ts

@@ -6,49 +6,129 @@
  * Extracted from command.ts to avoid circular dependencies.
  */
 import * as Effect from "../../../Effect.ts"
-import type * as ServiceMap from "../../../ServiceMap.ts"
 import type { Command } from "../Command.ts"
-import type { GlobalFlag } from "../GlobalFlag.ts"
+import type * as GlobalFlag from "../GlobalFlag.ts"
 import type { FlagDoc, HelpDoc } from "../HelpDoc.ts"
 import * as Param from "../Param.ts"
 import * as Primitive from "../Primitive.ts"
 import { toImpl } from "./command.ts"
 
+const dedupeGlobalFlags = (
+  flags: ReadonlyArray<GlobalFlag.GlobalFlag<any>>
+): ReadonlyArray<GlobalFlag.GlobalFlag<any>> => {
+  const seen = new Set<GlobalFlag.GlobalFlag<any>>()
+  const deduped: Array<GlobalFlag.GlobalFlag<any>> = []
+  for (const flag of flags) {
+    if (seen.has(flag)) {
+      continue
+    }
+    seen.add(flag)
+    deduped.push(flag)
+  }
+  return deduped
+}
+
 /**
- * Helper function to get help documentation for a specific command path.
- * Navigates through the command hierarchy to find the right command.
- * Reads global flags from the registry and includes them in the help doc.
+ * Returns the resolved command lineage for the provided path.
+ * Includes the root command as the first element.
  */
-export const getHelpForCommandPath = <Name extends string, Input, E, R>(
+export const getCommandsForCommandPath = <Name extends string, Input, E, R>(
   command: Command<Name, Input, E, R>,
-  commandPath: ReadonlyArray<string>,
-  registry: ServiceMap.Reference<Set<ServiceMap.Reference<GlobalFlag<unknown>>>>
-): Effect.Effect<HelpDoc, never, never> =>
-  Effect.gen(function*() {
-    let currentCommand: Command.Any = command
+  commandPath: ReadonlyArray<string>
+): ReadonlyArray<Command.Any> => {
+  const commands: Array<Command.Any> = [command]
+  let currentCommand: Command.Any = command
 
-    for (let i = 1; i < commandPath.length; i++) {
-      const subcommandName = commandPath[i]
-      let subcommand: Command.Any | undefined = undefined
+  for (let i = 1; i < commandPath.length; i++) {
+    const subcommandName = commandPath[i]
+    let subcommand: Command.Any | undefined = undefined
 
-      for (const group of currentCommand.subcommands) {
-        subcommand = group.commands.find((sub) => sub.name === subcommandName)
-        if (subcommand) {
-          break
-        }
+    for (const group of currentCommand.subcommands) {
+      subcommand = group.commands.find((sub) => sub.name === subcommandName)
+      if (subcommand) {
+        break
       }
+    }
 
-      if (subcommand) {
-        currentCommand = subcommand
+    if (!subcommand) {
+      break
+    }
+
+    commands.push(subcommand)
+    currentCommand = subcommand
+  }
+
+  return commands
+}
+
+/**
+ * Returns active global flags for a command path.
+ * Built-ins are prepended and declarations are collected root -> leaf.
+ */
+export const getGlobalFlagsForCommandPath = <Name extends string, Input, E, R>(
+  command: Command<Name, Input, E, R>,
+  commandPath: ReadonlyArray<string>,
+  builtIns: ReadonlyArray<GlobalFlag.GlobalFlag<any>>
+): ReadonlyArray<GlobalFlag.GlobalFlag<any>> => {
+  const commands = getCommandsForCommandPath(command, commandPath)
+  const declared = commands.flatMap((current) => toImpl(current).globalFlags)
+  return dedupeGlobalFlags([
+    ...builtIns,
+    ...declared
+  ])
+}
+
+const collectDeclaredGlobalFlags = (command: Command.Any): ReadonlyArray<GlobalFlag.GlobalFlag<any>> => {
+  const collected: Array<GlobalFlag.GlobalFlag<any>> = []
+
+  const visit = (current: Command.Any): void => {
+    const impl = toImpl(current)
+    for (const flag of impl.globalFlags) {
+      collected.push(flag)
+    }
+    for (const group of current.subcommands) {
+      for (const subcommand of group.commands) {
+        visit(subcommand)
       }
     }
+  }
+
+  visit(command)
+  return dedupeGlobalFlags(collected)
+}
+
+/**
+ * Returns all global flags declared in a command tree.
+ * Built-ins are prepended and command declarations are deduplicated by identity.
+ */
+export const getGlobalFlagsForCommandTree = <Name extends string, Input, E, R>(
+  command: Command<Name, Input, E, R>,
+  builtIns: ReadonlyArray<GlobalFlag.GlobalFlag<any>>
+): ReadonlyArray<GlobalFlag.GlobalFlag<any>> =>
+  dedupeGlobalFlags([
+    ...builtIns,
+    ...collectDeclaredGlobalFlags(command)
+  ])
+
+/**
+ * Helper function to get help documentation for a specific command path.
+ * Navigates through the command hierarchy to find the right command.
+ * Reads active global flags for the path and includes them in the help doc.
+ */
+export const getHelpForCommandPath = <Name extends string, Input, E, R>(
+  command: Command<Name, Input, E, R>,
+  commandPath: ReadonlyArray<string>,
+  builtIns: ReadonlyArray<GlobalFlag.GlobalFlag<any>>
+): Effect.Effect<HelpDoc, never, never> =>
+  Effect.gen(function*() {
+    const commands = getCommandsForCommandPath(command, commandPath)
+    const currentCommand = commands.length > 0 ? commands[commands.length - 1] : command
 
     const baseDoc = toImpl(currentCommand).buildHelpDoc(commandPath)
 
-    const refs = yield* registry
+    const flags = getGlobalFlagsForCommandPath(command, commandPath, builtIns)
     const globalFlagDocs: Array<FlagDoc> = []
-    for (const ref of refs) {
-      const flag = yield* ref
+    for (const flag of flags) {
       const singles = Param.extractSingleParams(flag.flag)
       for (const single of singles) {
         const formattedAliases = single.aliases.map((alias) => alias.length === 1 ? `-${alias}` : `--${alias}`)