flake.nix

{
  description = "fredshell — an opinionated Rust shell";

  inputs = {
    precommit.url = "github:FredSystems/pre-commit-checks";
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";

    # PLAN_05 §4.5 — pinned reference toolchain for the spec harness.
    #
    # `bash` and `coreutils` from this input define the v1 oracle for
    # `cargo xtask spec record` and the bash-compat corpus. Pinned to
    # an explicit rev so the reference does not drift when the
    # floating `nixpkgs` input advances.
    #
    # Bump policy: bump deliberately, capturing the new versions in
    # `tests/spec/REFERENCE.md` and re-recording any affected fixtures
    # in the same commit. `cargo xtask spec versions` reports drift
    # between this pin and the floating `nixpkgs` as advisory output.
    nixpkgs-reference.url = "github:nixos/nixpkgs/88ae3822eb8aec31f12a4a1895cb064413511177";

    rust-overlay = {
      url = "github:oxalica/rust-overlay";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs =
    {
      self,
      precommit,
      nixpkgs,
      nixpkgs-reference,
      rust-overlay,
      ...
    }:
    let
      inherit (nixpkgs) lib;
      systems = precommit.lib.supportedSystems;
    in
    {
      ##########################################################################
      ## OVERLAY — adds `pkgs.fredshell` when applied
      ##########################################################################
      overlays.default = import ./nix/overlay.nix { fredshell-flake = self; };

      ##########################################################################
      ## HOME-MANAGER MODULE — `programs.fredshell` option set
      ##########################################################################
      homeManagerModules.default = import ./nix/home-manager-module.nix { fredshell-flake = self; };

      packages = lib.genAttrs systems (
        system:
        let
          pkgs = import nixpkgs {
            inherit system;
            overlays = [ rust-overlay.overlays.default ];
          };

          referencePkgs = import nixpkgs-reference { inherit system; };

          rustToolchain = pkgs.rust-bin.stable.latest.default;

          rustPlatform = pkgs.makeRustPlatform {
            cargo = rustToolchain;
            rustc = rustToolchain;
          };
        in
        {
          fredshell = rustPlatform.buildRustPackage {
            pname = "fredshell";
            version = "0.1.0";
            src = pkgs.lib.cleanSource ./.;

            cargoLock.lockFile = ./Cargo.lock;

            nativeBuildInputs = [
              pkgs.pkg-config
              pkgs.makeWrapper
            ];

            buildInputs = [ ];

            # The fredshell binary lives in the `fredshell` crate.
            cargoBuildFlags = [
              "-p"
              "fredshell"
            ];

            meta = with pkgs.lib; {
              description = "An opinionated, batteries-included Rust shell";
              homepage = "https://github.com/fredsystems/fredshell";
              license = licenses.mit;
              mainProgram = "fredshell";
              platforms = platforms.unix;
            };
          };

          # PLAN_05 §4.5 — pinned reference toolchain.
          # Re-exposed as flake packages so the spec harness and CI
          # can resolve them via `nix build .#bashReference` /
          # `.#coreutilsReference` rather than hardcoding store paths.
          bashReference = referencePkgs.bash;
          coreutilsReference = referencePkgs.coreutils;
        }
      );

      ##########################################################################
      ## CHECKS — unified base+rust via mkCheck
      ##########################################################################
      checks = builtins.listToAttrs (
        map (system: {
          name = system;
          value = {
            pre-commit-check = precommit.lib.mkCheck {
              inherit system;
              src = ./.;
              check_rust = true;
              enableXtask = true;
              rust_options = {
                xtaskCheck = "pc";
              };
              extraExcludes = [
                "typos.toml"
              ];
            };
          };
        }) systems
      );

      ##########################################################################
      ## DEV SHELLS
      ##########################################################################
      devShells = builtins.listToAttrs (
        map (system: {
          name = system;

          value =
            let
              pkgs = import nixpkgs { inherit system; };
              referencePkgs = import nixpkgs-reference { inherit system; };

              # `rust-bin` only exists once the rust-overlay is applied.
              # The default shell takes its toolchain from mkCheck, so it
              # does not need this; the nightly shell below does.
              rustPkgs = import nixpkgs {
                inherit system;
                overlays = [ rust-overlay.overlays.default ];
              };

              nightlyToolchain = rustPkgs.rust-bin.nightly.latest.default.override {
                extensions = [
                  "clippy"
                  "rustfmt"
                ];
              };

              chk = self.checks.${system}."pre-commit-check";

              corePkgs = chk.enabledPackages or [ ];

              extraRustTools = [
                pkgs.cargo-deny
                pkgs.cargo-machete
                pkgs.cargo-make
                pkgs.cargo-flamegraph
                pkgs.typos
                pkgs.markdownlint-cli2
              ]
              ++ pkgs.lib.optionals pkgs.stdenv.isLinux [
                pkgs.cargo-llvm-cov
                pkgs.perf
              ];

              # Extra dev packages provided by mkCheck (includes the rust
              # toolchain).
              extraDev = chk.passthru.devPackages or [ ];
            in
            {
              default = pkgs.mkShell {
                # ORDER IS SIGNIFICANT. `extraDev` carries the mkCheck rust
                # toolchain (rustc + cargo + clippy + rustfmt from a single
                # release), while `corePkgs` carries git-hooks.nix's own
                # standalone `cargo` / `clippy` / `rustfmt` derivations, which
                # can come from a different rustc release. Two toolchains end
                # up on PATH and earlier entries win, so `extraDev` MUST come
                # first — otherwise `cargo clippy` runs a `clippy-driver` built
                # by a different rustc than the `rustc` that compiled the
                # dependency rlibs and every workspace crate fails with
                # E0514 "found crate ... compiled by an incompatible version
                # of rustc".
                #
                # `extraDev` must also stay a flat splice rather than an
                # element of `extraRustTools`: nesting a list inside
                # `buildInputs` is deprecated as of Nixpkgs 26.05.
                buildInputs = extraDev ++ corePkgs ++ extraRustTools;

                # PLAN_05 §4.5 — expose the pinned reference toolchain
                # to the spec harness via env vars. The harness reads
                # FREDSHELL_REFERENCE_BASH / FREDSHELL_REFERENCE_COREUTILS
                # instead of consulting PATH so the pin is explicit and
                # cannot be shadowed by the host system bash (e.g.
                # macOS bash 3.2).
                FREDSHELL_REFERENCE_BASH = "${referencePkgs.bash}/bin/bash";
                FREDSHELL_REFERENCE_COREUTILS = "${referencePkgs.coreutils}/bin";
                FREDSHELL_REFERENCE_BASH_VERSION = referencePkgs.bash.version;
                FREDSHELL_REFERENCE_COREUTILS_VERSION = referencePkgs.coreutils.version;
                FREDSHELL_FLOATING_BASH_VERSION = pkgs.bash.version;
                FREDSHELL_FLOATING_COREUTILS_VERSION = pkgs.coreutils.version;

                shellHook = ''
                  ${chk.shellHook}

                  alias pre-commit="pre-commit run --all-files"
                '';
              };

              # Reproduces the CI `check` matrix's nightly leg locally.
              #
              # CI runs `cargo xtask check` on both stable and nightly, but
              # the default shell only carries the stable toolchain, so a
              # nightly-only lint break (e.g. a newly-added
              # `clippy::nursery` lint) could not be reproduced without
              # this shell. That gap let a single new lint hold twelve
              # dependency PRs red.
              #
              # This shell deliberately OMITS `extraDev` and `corePkgs`.
              # Those carry the stable rustc/cargo/clippy and the
              # pre-commit tooling; putting them alongside the nightly
              # toolchain would put two toolchains on PATH and trip the
              # E0514 failure documented on the default shell above.
              # Consequence: this shell has no pre-commit hooks and no
              # cargo-deny/llvm-cov. Commit from the default shell; use
              # this one only to run `cargo xtask check` on nightly.
              #
              # CARGO_TARGET_DIR is separate so swapping between shells
              # does not invalidate the stable build cache every time.
              # It is set in the shellHook rather than as a static env
              # var because it MUST be absolute — see the note there.
              nightly = pkgs.mkShell {
                buildInputs = [
                  nightlyToolchain
                  pkgs.cargo-machete
                ];

                # Same pinned spec-harness reference as the default shell —
                # `cargo xtask check` runs `cargo test --workspace`, which
                # includes the spec corpus.
                FREDSHELL_REFERENCE_BASH = "${referencePkgs.bash}/bin/bash";
                FREDSHELL_REFERENCE_COREUTILS = "${referencePkgs.coreutils}/bin";
                FREDSHELL_REFERENCE_BASH_VERSION = referencePkgs.bash.version;
                FREDSHELL_REFERENCE_COREUTILS_VERSION = referencePkgs.coreutils.version;
                FREDSHELL_FLOATING_BASH_VERSION = pkgs.bash.version;
                FREDSHELL_FLOATING_COREUTILS_VERSION = pkgs.coreutils.version;

                shellHook = ''
                  # CARGO_TARGET_DIR MUST be absolute. A relative value is
                  # resolved against each cargo invocation's cwd, and
                  # trybuild runs cargo from inside
                  # crates/fredshell-spec-macros. A relative
                  # "target/nightly" therefore produces a second target
                  # tree at crates/fredshell-spec-macros/target/nightly,
                  # which the root-anchored `/target/` gitignore does not
                  # cover — cargo-machete then walks trybuild's generated
                  # manifests and fails `cargo xtask check` with bogus
                  # unused-dependency findings.
                  CARGO_TARGET_DIR="$(git rev-parse --show-toplevel 2>/dev/null || pwd)/target/nightly"
                  export CARGO_TARGET_DIR
                '';
              };
            };
        }) systems
      );
    };
}