bazel: bazelize docs/generated/redact_safe.md generation

[rickystewart]

Epic CRDB-8035

[rickystewart]

	@(echo "The following types are considered always safe for reporting:"; echo; \
	  echo "File | Type"; echo "--|--") >[email protected] || { rm -f [email protected]; exit 1; }
	@git grep --recurse-submodules -n '^func \(.*\) SafeValue\(\)' | \
	  grep -v '^vendor/github.com/cockroachdb/redact' | \
	  sed -E -e 's/^([^:]*):[0-9]+:func \(([^ ]* )?(.*)\) SafeValue.*$$/\1 | \`\3\`/g' | \
	  sort >>[email protected] || { rm -f [email protected]; exit 1; }
	@git grep --recurse-submodules -n 'redact\.RegisterSafeType' | \
	  grep -vE '^([^:]*):[0-9]+:[ 	]*//' | \
	  grep -v '^vendor/github.com/cockroachdb/redact' | \
	  sed -E -e 's/^([^:]*):[0-9]+:.*redact\.RegisterSafeType\((.*)\).*/\1 | \`\2\`/g' | \
	  sort  >>[email protected] || { rm -f [email protected]; exit 1; }

This is easily something that we can't bazelize -- we can't pass the entire source tree into a Bazel genrule to grep the sources, let alone the entire tree of all the dependencies that we depend on.

If we still want this file in-tree and we still want it generated along with the rest of our documentation, then we'll either have to find a more sensible (incremental, not monolithic) way to construct this file, or we'll have to accept that we can't use Bazel to build it.

cc @knz

[knz]

The function of this is twofold.

One is to ensure we get a GitHub PR notification when a type is added to this list.

Another is to document the list of these types, for folk who want to know how the type they're looking at will be treated.

I'm not sure what "incremental" would look like?

In any case, this is more or less the same challenge as ensuring our linter tests can run. What does Bazel think about the linters?

[rickystewart]

I'm not sure what "incremental" would look like?

(This is hypothetical, I haven't designed this and don't think that trying to implement this makes sense given the ROI.) We'd need a way to compute the list of "redact-safe" types for an individual Go package, and then a way to union all those redact-safe types across all of our Go packages and our dependencies. i.e., the same thing, but computed incrementally rather than doing a grep over the entire codebase including dependencies.

In any case, this is more or less the same challenge as ensuring our linter tests can run. What does Bazel think about the linters?

Yeah, so the linters don't really run "inside" the Bazel sandbox. You can use Bazel to build a test binary containing the linter tests and then run it from within the workspace, but that's meaningfully different from asking Bazel to run a test itself, in which case all the dependencies for the test would have to be captured in the sandbox -- and the "dependencies" for the linter include the entire source tree, which is a non-starter. Similarly, we can't capture the entire source tree as a dependency for redact_safe.md.

I think the way this is going to go is that whatever command we have people run to generate documentation (dev generate docs or whatever) is going to run a bazel build to build the majority of the documentation, and then it'll probably "cheat" and just do the git grep thing directly to generate redact_safe.md.