build(Makefile): enable parallel make -j gen with correct dependency graph (#22612)

`make gen` could not run with `-j` because inter-target dependency edges
were missing. Multiple recipes compile `coderd/rbac` (which includes
generated files like `object_gen.go`), and without explicit ordering,
parallel runs produced syntax errors from mid-write reads.

Three main changes:

**Dependency graph fixes** declare the compile-time chain through
`coderd/rbac` so that `object_gen.go` is written before anything that
imports it is compiled. The DB generation targets use a GNU Make 4.3+
grouped target (`&:`) so Make knows `generate.sh` co-produces
`querier.go`, `unique_constraint.go`, `dbmetrics`, and `dbauthz` in a
single invocation. `SKIP_DUMP_SQL=1` avoids re-entrant `make` inside
`generate.sh` when the Makefile already guarantees `dump.sql` is fresh.

**`scripts/atomicwrite` package** replaces `os.WriteFile` in all gen
scripts with a temp-file-in-same-dir + rename pattern, preventing
interrupted runs from leaving partial files.

**`.PRECIOUS` and shell atomic writes** protect git-tracked generated
files from Make's default delete-on-error behavior. Since these files
are committed, deletion is worse than staleness -- `git restore` is the
recovery path.

CI now runs `make -j --output-sync -B gen` (~32s, down from ~85s
serial).

| Scenario                          | Before             | After    |
|-----------------------------------|--------------------|----------|
| `make gen` (serial)               | 95s                | 95s      |
| `make -j gen` (parallel)          | race error         | **22s**  |
| CI `make -j --output-sync -B gen` | forced serial ~85s | **~32s** |

scripts/apidocgen/generate.sh

@@ -10,6 +10,11 @@ source "$(dirname "$(dirname "${BASH_SOURCE[0]}")")/lib.sh"
 APIDOCGEN_DIR=$(dirname "${BASH_SOURCE[0]}")
 API_MD_TMP_FILE=$(mktemp /tmp/coder-apidocgen.XXXXXX)
 
+# SWAG_OUTPUT_DIR controls where swag writes swagger.json and docs.go.
+# The caller may set it to a temp directory to avoid writing directly
+# into the working tree.
+SWAG_OUTPUT_DIR="${SWAG_OUTPUT_DIR:-./coderd/apidoc}"
+
 cleanup() {
 	rm -f "${API_MD_TMP_FILE}"
 }
@@ -28,14 +33,14 @@ pushd "${APIDOCGEN_DIR}"
 
 # Make sure that widdershins is installed correctly.
 pnpm exec -- widdershins --version
-# Render the Markdown file.
+# Render the Markdown file from the swagger output.
 pnpm exec -- widdershins \
 	--user_templates "./markdown-template" \
 	--search false \
 	--omitHeader true \
 	--language_tabs "shell:curl" \
-	--summary "../../coderd/apidoc/swagger.json" \
+	--summary "${SWAG_OUTPUT_DIR}/swagger.json" \
 	--outfile "${API_MD_TMP_FILE}"
 # Perform the postprocessing
-go run postprocess/main.go -in-md-file-single "${API_MD_TMP_FILE}"
+go run postprocess/main.go -in-md-file-single "${API_MD_TMP_FILE}" -docs-directory "${APIDOCGEN_DOCS_DIR:-../../docs}"
 popd

scripts/apidocgen/postprocess/main.go

@@ -13,6 +13,8 @@ import (
 	"strings"
 
 	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/v2/scripts/atomicwrite"
 )
 
 const (
@@ -126,7 +128,7 @@ func writeDocs(sections [][]byte) error {
 	log.Println("Write docs to destination")
 
 	apiDir := path.Join(docsDirectory, apiSubdir)
-	err := os.WriteFile(path.Join(apiDir, apiIndexFile), []byte(apiIndexContent), 0o644) // #nosec
+	err := atomicwrite.File(path.Join(apiDir, apiIndexFile), []byte(apiIndexContent))
 	if err != nil {
 		return xerrors.Errorf(`can't write the index file: %w`, err)
 	}
@@ -147,7 +149,7 @@ func writeDocs(sections [][]byte) error {
 
 		mdFilename := toMdFilename(sectionName)
 		docPath := path.Join(apiDir, mdFilename)
-		err = os.WriteFile(docPath, section, 0o644) // #nosec
+		err = atomicwrite.File(docPath, section)
 		if err != nil {
 			return xerrors.Errorf(`can't write doc file "%s": %w`, docPath, err)
 		}
@@ -226,7 +228,7 @@ func writeDocs(sections [][]byte) error {
 		return xerrors.Errorf("json.Marshal failed: %w", err)
 	}
 
-	err = os.WriteFile(manifestPath, manifestFile, 0o644) // #nosec
+	err = atomicwrite.File(manifestPath, manifestFile)
 	if err != nil {
 		return xerrors.Errorf("can't write manifest file: %w", err)
 	}

scripts/apidocgen/swaginit/main.go

@@ -16,11 +16,17 @@ import (
 func main() {
 	logger := log.New(os.Stdout, "", log.LstdFlags)
 
+	outputDir := "./coderd/apidoc"
+	if d := os.Getenv("SWAG_OUTPUT_DIR"); d != "" {
+		outputDir = d
+	}
+
 	err := gen.New().Build(&gen.Config{
 		SearchDir:          "./coderd,./codersdk,./enterprise/coderd,./enterprise/wsproxy/wsproxysdk",
 		MainAPIFile:        "coderd.go",
-		OutputDir:          "./coderd/apidoc",
+		OutputDir:          outputDir,
 		OutputTypes:        []string{"go", "json"},
+		PackageName:        "apidoc",
 		ParseDependency:    1,
 		Strict:             true,
 		OverridesFile:      gen.DefaultOverridesFile,