mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 05:52:51 +00:00
e8d95f306b
## Summary - Add a searchable catalog of every error ID ZITADEL's gRPC/Connect APIs can return (`content/apis/errors.mdx`), wired into the sidebar next to "gRPC Status Codes" (with a cross-link added there too). There was previously no such reference — error IDs are assigned ad hoc at ~3,800 call sites across the backend. - `scripts/generate-error-reference.ts` scans `internal/**/*.go` and `backend/**/*.go` for `zerrors.Throw*()` call sites, resolves i18n messages, and clusters ~3,200 distinct IDs into ~1,160 distinct causes by (subsystem, gRPC code, message) — so identical causes are merged into one entry instead of repeated ~3,200 times. - Detects real ID collisions (same ID thrown for genuinely different reasons at different call sites) and surfaces them as warnings, rather than silently merging them. - Generates a worked example API response for every cause. - 116 of the highest-impact causes (covering the majority of call sites) carry an explanation written against the actual source rather than the raw message text; the rest carry a mechanically derived explanation — both are visibly labeled by source so the depth of research is transparent. - New `ErrorReference` component renders the catalog as a searchable, collapsible subsystem → gRPC code → cause tree. The generator is a standalone script (`pnpm generate:error-reference` in `apps/docs`), not wired into the docs build's `generate` chain, since scanning the whole Go backend on every docs build would be wasteful. The generated `data.json` and the curated overrides are committed, the same way `content/apis/benchmarks/**/output.json` is already committed despite being externally generated. ## Test plan - [x] `pnpm nx run @zitadel/docs:check-types` passes - [x] `pnpm nx run @zitadel/docs:lint` passes - [x] `pnpm nx run @zitadel/docs:check-links` passes - [x] Verified locally in `pnpm nx run @zitadel/docs:dev`: page renders, tree expands/collapses, search filters by ID/message, collision warnings render correctly (e.g. `AUTHZ-Kl3p0`) --------- Co-authored-by: Rajat Singh <[email protected]> Co-authored-by: Claude Sonnet 5 <[email protected]> Co-authored-by: Marco A. <[email protected]>
283 lines
7.0 KiB
JSON
283 lines
7.0 KiB
JSON
{
|
|
"name": "@zitadel/docs",
|
|
"$schema": "../../node_modules/nx/schemas/project-schema.json",
|
|
"targets": {
|
|
"build": {
|
|
"executor": "nx:run-commands",
|
|
"options": {
|
|
"command": "pnpm build",
|
|
"cwd": "apps/docs"
|
|
},
|
|
"outputs": [
|
|
"{projectRoot}/.next"
|
|
],
|
|
"dependsOn": [
|
|
"^build",
|
|
"check-links"
|
|
],
|
|
"inputs": [
|
|
"default",
|
|
"^production"
|
|
],
|
|
"cache": true
|
|
},
|
|
"dev": {
|
|
"executor": "nx:run-commands",
|
|
"options": {
|
|
"command": "pnpm dev",
|
|
"cwd": "apps/docs"
|
|
},
|
|
"dependsOn": [
|
|
"generate"
|
|
]
|
|
},
|
|
"start": {
|
|
"executor": "nx:run-commands",
|
|
"options": {
|
|
"command": "pnpm start",
|
|
"cwd": "apps/docs"
|
|
},
|
|
"dependsOn": [
|
|
"build"
|
|
]
|
|
},
|
|
"fetch-remote-content": {
|
|
"executor": "nx:run-commands",
|
|
"options": {
|
|
"command": "pnpm fetch:remote-content",
|
|
"cwd": "apps/docs"
|
|
},
|
|
"outputs": [
|
|
"{projectRoot}/content/v*",
|
|
"{projectRoot}/content/versions.json",
|
|
"{projectRoot}/public/v*"
|
|
],
|
|
"cache": true,
|
|
"inputs": [
|
|
"default",
|
|
{
|
|
"runtime": "git ls-remote --tags --sort=-v:refname https://github.com/zitadel/zitadel.git | grep 'refs/tags/v[0-9]' | grep -v '\\^{}' | head -n 5"
|
|
}
|
|
]
|
|
},
|
|
"generate-proto-docs": {
|
|
"executor": "nx:run-commands",
|
|
"options": {
|
|
"command": "bash -c 'GOOS=$(uname -s | tr \"[:upper:]\" \"[:lower:]\"); GOARCH=$(uname -m); GOARCH=${GOARCH/x86_64/amd64}; GOARCH=${GOARCH/aarch64/arm64}; PATH=\"${PWD}/../../.artifacts/bin/${GOOS}/${GOARCH}:$PATH\" pnpm generate:proto-docs'",
|
|
"cwd": "apps/docs"
|
|
},
|
|
"dependsOn": [
|
|
"fetch-remote-content",
|
|
"install-proto-plugins"
|
|
],
|
|
"outputs": [
|
|
"{projectRoot}/openapi"
|
|
],
|
|
"cache": true,
|
|
"inputs": [
|
|
"{projectRoot}/scripts/generate-proto-docs.mjs",
|
|
"{projectRoot}/buf.gen.yaml",
|
|
"{workspaceRoot}/proto/**/*",
|
|
{
|
|
"dependentTasksOutputFiles": "apps/docs/content/versions.json"
|
|
},
|
|
{
|
|
"dependentTasksOutputFiles": ".artifacts/bin/*/*/protoc-gen-connect-openapi"
|
|
}
|
|
]
|
|
},
|
|
"install-proto-plugins": {
|
|
"executor": "nx:run-commands",
|
|
"options": {
|
|
"command": "bash ./apps/docs/scripts/install-proto-plugins.sh"
|
|
},
|
|
"cache": true,
|
|
"inputs": [
|
|
{ "runtime": "uname -s" },
|
|
{ "runtime": "uname -m" },
|
|
"{projectRoot}/scripts/install-proto-plugins.sh"
|
|
],
|
|
"outputs": [
|
|
"{workspaceRoot}/.artifacts/bin/*/*/protoc-gen-connect-openapi"
|
|
]
|
|
},
|
|
"generate-api-reference": {
|
|
"executor": "nx:run-commands",
|
|
"options": {
|
|
"command": "pnpm generate:api-reference",
|
|
"cwd": "apps/docs"
|
|
},
|
|
"outputs": [
|
|
"{projectRoot}/content/reference/api",
|
|
"{projectRoot}/content/v*/reference/api"
|
|
],
|
|
"dependsOn": [
|
|
"generate-proto-docs"
|
|
],
|
|
"cache": true,
|
|
"inputs": [
|
|
"{projectRoot}/scripts/generate-api-reference.mts",
|
|
{
|
|
"dependentTasksOutputFiles": "apps/docs/openapi/**"
|
|
}
|
|
]
|
|
},
|
|
"fix-api-links": {
|
|
"executor": "nx:run-commands",
|
|
"options": {
|
|
"command": "pnpm fix:api-links",
|
|
"cwd": "apps/docs"
|
|
},
|
|
"dependsOn": [
|
|
"generate-api-reference"
|
|
],
|
|
"cache": false,
|
|
"inputs": [
|
|
"default",
|
|
{
|
|
"dependentTasksOutputFiles": "apps/docs/content/reference/api/**"
|
|
}
|
|
]
|
|
},
|
|
"generate-error-reference": {
|
|
"executor": "nx:run-commands",
|
|
"options": {
|
|
"command": "pnpm generate:error-reference",
|
|
"cwd": "apps/docs"
|
|
},
|
|
"outputs": [
|
|
"{projectRoot}/components/ErrorReference/data.json"
|
|
],
|
|
"cache": true,
|
|
"inputs": [
|
|
"{projectRoot}/scripts/generate-error-reference.ts",
|
|
"{projectRoot}/scripts/error-reference-overrides/**",
|
|
"{projectRoot}/lib/grpc-status.ts",
|
|
"{workspaceRoot}/internal/**/*.go",
|
|
"{workspaceRoot}/backend/**/*.go",
|
|
"{workspaceRoot}/internal/static/i18n/en.yaml",
|
|
"{workspaceRoot}/internal/api/ui/login/static/i18n/en.yaml",
|
|
"{workspaceRoot}/internal/notification/static/i18n/en.yaml"
|
|
]
|
|
},
|
|
"generate-index-pages": {
|
|
"executor": "nx:run-commands",
|
|
"options": {
|
|
"command": "pnpm generate:index-pages",
|
|
"cwd": "apps/docs"
|
|
},
|
|
"outputs": [
|
|
"{projectRoot}/content/**/index.mdx"
|
|
],
|
|
"dependsOn": [
|
|
"fetch-remote-content"
|
|
],
|
|
"cache": true,
|
|
"inputs": [
|
|
"default",
|
|
"{projectRoot}/content/versions.json"
|
|
]
|
|
},
|
|
"build-mdx-source": {
|
|
"executor": "nx:run-commands",
|
|
"options": {
|
|
"command": "pnpm build:mdx-source",
|
|
"cwd": "apps/docs"
|
|
},
|
|
"outputs": [
|
|
"{projectRoot}/.source"
|
|
],
|
|
"dependsOn": [
|
|
"fix-api-links",
|
|
"generate-index-pages"
|
|
],
|
|
"cache": true,
|
|
"inputs": [
|
|
"default",
|
|
{
|
|
"dependentTasksOutputFiles": "apps/docs/content/**"
|
|
}
|
|
]
|
|
},
|
|
"generate": {
|
|
"executor": "nx:run-commands",
|
|
"options": {
|
|
"command": "echo 'Generation complete'",
|
|
"cwd": "apps/docs"
|
|
},
|
|
"dependsOn": [
|
|
"build-mdx-source"
|
|
]
|
|
},
|
|
"check-links": {
|
|
"executor": "nx:run-commands",
|
|
"options": {
|
|
"command": "pnpm check:links",
|
|
"cwd": "apps/docs"
|
|
},
|
|
"dependsOn": [
|
|
"generate"
|
|
],
|
|
"cache": true,
|
|
"inputs": [
|
|
"default",
|
|
"^production",
|
|
"{workspaceRoot}/proto/**/*",
|
|
"{projectRoot}/content/**/*",
|
|
"{projectRoot}/public/**/*"
|
|
]
|
|
},
|
|
"clean": {
|
|
"executor": "nx:run-commands",
|
|
"options": {
|
|
"command": "pnpm clean",
|
|
"cwd": "apps/docs"
|
|
}
|
|
},
|
|
"check-types": {
|
|
"executor": "nx:run-commands",
|
|
"options": {
|
|
"command": "pnpm check:types",
|
|
"cwd": "apps/docs"
|
|
},
|
|
"dependsOn": [
|
|
"generate"
|
|
],
|
|
"cache": true,
|
|
"inputs": [
|
|
"default",
|
|
"{projectRoot}/tsconfig.json",
|
|
"{projectRoot}/**/*.{ts,tsx}",
|
|
"{projectRoot}/.next/types/**/*.ts"
|
|
]
|
|
},
|
|
"test": {
|
|
"executor": "nx:run-commands",
|
|
"options": {
|
|
"command": "pnpm test:scripts",
|
|
"cwd": "apps/docs"
|
|
},
|
|
"dependsOn": [
|
|
"check-types",
|
|
"check-links"
|
|
]
|
|
},
|
|
"lint": {
|
|
"executor": "nx:run-commands",
|
|
"options": {
|
|
"command": "pnpm lint",
|
|
"cwd": "apps/docs"
|
|
},
|
|
"dependsOn": [
|
|
"generate"
|
|
],
|
|
"cache": true,
|
|
"inputs": [
|
|
"default",
|
|
"{workspaceRoot}/.eslintrc.json",
|
|
"{projectRoot}/eslint.config.mjs",
|
|
"{projectRoot}/content/**/*.{md,mdx}"
|
|
]
|
|
}
|
|
}
|
|
} |