Tighten stdlib typespecs to match implementations

Candidates found by lib/elixir/scripts/compare_specs_and_signatures.exs:
these @specs declared strictly wider return types than the functions can
produce, with the gap carrying no intentional API room:

  * File.Stream.t/0: type the struct fields (mirrors IO.Stream.t/0)
  * Map.new/0: %{} instead of map()
  * List.keyfind!/3: tuple() -- the false branch of :lists.keyfind/3
    always raises
  * Logger.levels/0: :logger.level() excludes :warn, which is only an
    accepted input alias and is never returned
  * Code.available_compiler_options/0 and Mix.compilers/0: literal atoms
  * Macro.Env.location/1 and Macro.Env.stacktrace/1: precise shapes
  * ExUnit.AssertionError.no_value/0: the literal atom
  * Module.reserved_attributes/0: value shape %{doc: binary()}
  * Inspect.Algebra.break/1 and flex_break/1: concrete doc_break tuples

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: lukaszsamson

lib/elixir/lib/code.ex

@@ -1734,7 +1734,21 @@ defmodule Code do
       #=> [:docs, :debug_info, ...]
 
   """
-  @spec available_compiler_options() :: [atom]
+  @spec available_compiler_options() :: [
+          :debug_info
+          | :docs
+          | :erlc_options
+          | :ignore_already_consolidated
+          | :ignore_module_conflict
+          | :infer_signatures
+          | :module_definition
+          | :no_warn_undefined
+          | :on_undefined_variable
+          | :parser_options
+          | :relative_paths
+          | :tracers,
+          ...
+        ]
   def available_compiler_options do
     @available_compiler_options
   end

lib/elixir/lib/file/stream.ex

@@ -18,7 +18,13 @@ defmodule File.Stream do
 
   defstruct path: nil, modes: [], line_or_bytes: :line, raw: true, node: nil
 
-  @type t :: %__MODULE__{}
+  @type t :: %__MODULE__{
+          path: Path.t(),
+          modes: [term()],
+          line_or_bytes: :line | pos_integer(),
+          raw: boolean(),
+          node: node()
+        }
 
   @doc false
   def __build__(path, line_or_bytes, modes) do

lib/elixir/lib/inspect/algebra.ex

@@ -858,7 +858,7 @@ defmodule Inspect.Algebra do
       "aaaaaaaaaaaaaaaaaaaa\nb"
 
   """
-  @spec break(binary) :: doc_break
+  @spec break(binary) :: {:doc_break, binary, :strict}
   def break(string \\ " ") when is_binary(string) do
     doc_break(string, :strict)
   end
@@ -922,7 +922,7 @@ defmodule Inspect.Algebra do
   maximum number of entries on the same line.
   """
   @doc since: "1.6.0"
-  @spec flex_break(binary) :: doc_break
+  @spec flex_break(binary) :: {:doc_break, binary, :flex}
   def flex_break(string \\ " ") when is_binary(string) do
     doc_break(string, :flex)
   end

lib/elixir/lib/macro/env.ex

@@ -203,7 +203,7 @@ defmodule Macro.Env do
   Returns a keyword list containing the file and line
   information as keys.
   """
-  @spec location(t) :: keyword
+  @spec location(t) :: [file: file, line: line]
   def location(env)
 
   def location(%{__struct__: Macro.Env, file: file, line: line}) do
@@ -700,7 +700,7 @@ defmodule Macro.Env do
   @doc """
   Returns the environment stacktrace.
   """
-  @spec stacktrace(t) :: list
+  @spec stacktrace(t) :: [{module, atom, arity, keyword}]
   def stacktrace(%{__struct__: Macro.Env} = env) do
     cond do
       is_nil(env.module) ->

lib/elixir/lib/map.ex

@@ -201,7 +201,7 @@ defmodule Map do
       %{}
 
   """
-  @spec new :: map
+  @spec new :: %{}
   def new, do: %{}
 
   @doc """

lib/elixir/lib/module.ex

@@ -754,7 +754,7 @@ defmodule Module do
 
   """
   @doc since: "1.12.0"
-  @spec reserved_attributes() :: map
+  @spec reserved_attributes() :: %{optional(atom()) => %{doc: binary()}}
   def reserved_attributes() do
     %{
       after_compile: %{

lib/ex_unit/lib/ex_unit/assertions.ex

@@ -33,7 +33,7 @@ defmodule ExUnit.AssertionError do
   @doc """
   Indicates no meaningful value for a field.
   """
-  @spec no_value :: atom
+  @spec no_value :: :ex_unit_no_meaningful_value
   def no_value do
     @no_value
   end

lib/logger/lib/logger.ex

@@ -537,7 +537,7 @@ defmodule Logger do
   Returns all the available levels.
   """
   @doc since: "1.16.0"
-  @spec levels() :: [level(), ...]
+  @spec levels() :: [:logger.level(), ...]
   def levels(), do: @levels
 
   @doc ~S"""

lib/mix/lib/mix.ex

@@ -536,7 +536,7 @@ defmodule Mix do
       end
 
   """
-  @spec compilers() :: [atom()]
+  @spec compilers() :: [:app | :elixir | :erlang, ...]
   def compilers do
     [:erlang, :elixir, :app]
   end