Fix custom `twitter_scrooge` toolchain breakages

[mbland]

trafficstars

Description

Adds the examples/twitter_scrooge repository, adds test_twitter_scrooge_example to test/shell/test_examples.sh, and enables overriding all twitter_scrooge dependencies. Fixes #1744.

Adds docs/twitter_scrooge.md and includes extensive comments in examples/twitter_scrooge/{BUILD,MODULE.bazel,WORKSPACE}.

Also updates test/shell/test_examples.sh:

• It now uses run_tests from test/shell/test_runner.sh, and all test functions begin with test_. This enables automatic discovery and easy skipping of test cases (using the prefix _test_).

• Replaces test_example with run_in_example_dir. This removes a subshell per test case, and allows for passing individually quoted arguments.

Motivation

Fixes two breakages related to overriding default twitter_scrooge dependencies under Bzlmod (neither problem manifested under `WORKSPACE).

The first happened when using setup_scrooge_toolchain without instantiating the default Scala and twitter_scrooge toolchains and importing some of their repos. Even with all the available dependency parameters to setup_scrooge_toolchain specified, the build would break with errors like:

no such package
  '@@[unknown repo 'io_bazel_rules_scala_scopt_2_13_16'
  requested from @@]//':

The repository
  '@@[unknown repo 'io_bazel_rules_scala_scopt_2_13_16'
  requested from @@]'
  could not be resolved:

No repository visible as '@io_bazel_rules_scala_scopt_2_13_16'
  from main repository and referenced by
  '//tools/scala:compiler_classpath_provider'

This was because setup_scala_toolchain still contained hardcoded references to io_bazel_rules_scala_scopt and other internal dependency repos. The workaround was to instantiate the builtin toolchains, then use use_repo to bring these internal repositories into scope.

The fix was to make all of these repos overridable via setup_scala_toolchain and the scala_deps.twitter_scrooge() tag class. Now providing all the dependency arguments to setup_scala_toolchain avoids the need instantiate the builtin toolchains.

The second breakage happened when specifying overrides for the scala_deps.twitter_scrooge() tag class:

@@rules_scala+//scala/extensions:rules_scala++scala_deps+rules_scala_toolchains:
  expected value of type 'string' for dict value element,
  but got
  Label("@@rules_jvm_external++maven+maven//:org_apache_thrift_libthrift")

This happened because:

• The scala_deps module extension compiled its twitter_scrooge tag class Labels into a dictionary.

• It passed this string to Label dict to scala_toolchains(), which assigned it to the twitter_scrooge_options attribute of scala_toolchains_repo.

• The scala_toolchains_repo attribute is of type attr.string_dict, not attr.string_keyed_label_dict.

The fix was to translate the Labels in this dictionary into strings at the point of scala_toolchains_repo assignment. We don't officially support Bazel 6 anymore, but I didn't want to change the attribute to string_keyed_label_dict just yet. Things still work fine without it, and it gives Bazel 6 users a little more wiggle room and time to migrate.