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]>
81 lines
2.8 KiB
JSON
81 lines
2.8 KiB
JSON
{
|
|
"name": "@zitadel/docs",
|
|
"packageManager": "[email protected]+sha512.41872f037ad22f7348e3b1debbaf7e867cfd448f2726d9cf74c08f19507c31d2c8e7a11525b983febc2df640b5438dee6023ebb1f84ed43cc2d654d2bc326264",
|
|
"private": true,
|
|
"type": "module",
|
|
"scripts": {
|
|
"generate:index-pages": "tsx scripts/generate-index-pages.ts",
|
|
"generate:error-reference": "tsx scripts/generate-error-reference.ts",
|
|
"fetch:remote-content": "node scripts/fetch-remote-content.mjs",
|
|
"generate:proto-docs": "node scripts/generate-proto-docs.mjs",
|
|
"generate:api-reference": "node scripts/generate-api-reference.ts --only-generate",
|
|
"fix:api-links": "node scripts/generate-api-reference.ts --only-fix",
|
|
"build:mdx-source": "fumadocs-mdx",
|
|
"build": "next build",
|
|
"dev": "next dev",
|
|
"generate": "nx run @zitadel/docs:generate",
|
|
"start": "next start",
|
|
"clean": "node scripts/clean.mjs",
|
|
"check:types": "fumadocs-mdx && next typegen && tsc --noEmit",
|
|
"check:links": "tsx scripts/check-links.ts",
|
|
"test:scripts": "node --test scripts/*.test.mjs",
|
|
"postinstall": "fumadocs-mdx",
|
|
"lint": "eslint ."
|
|
},
|
|
"dependencies": {
|
|
"@headlessui/react": "^2.2.10",
|
|
"@heroicons/react": "^2.2.0",
|
|
"@inkeep/cxkit-react": "^0.5.117",
|
|
"@scalar/api-reference": "^1.55.3",
|
|
"@shikijs/rehype": "^4.0.2",
|
|
"@shikijs/types": "^4.0.2",
|
|
"@types/js-yaml": "^4.0.9",
|
|
"clsx": "^2.1.1",
|
|
"fumadocs-core": "16.8.10",
|
|
"fumadocs-mdx": "14.3.2",
|
|
"fumadocs-openapi": "10.8.2",
|
|
"fumadocs-ui": "16.8.10",
|
|
"js-yaml": "^4.3.1",
|
|
"lucide-react": "^0.577.0",
|
|
"mixpanel-browser": "^2.78.0",
|
|
"next": "16.2.11",
|
|
"next-themes": "^0.4.6",
|
|
"react": "19.2.6",
|
|
"react-copy-to-clipboard": "^5.1.1",
|
|
"react-dom": "19.2.6",
|
|
"react-google-charts": "^5.2.1",
|
|
"shiki": "^4.0.2",
|
|
"tailwind-merge": "^3.6.0",
|
|
"vanilla-cookieconsent": "^3.1.0",
|
|
"zod": "^4.4.3"
|
|
},
|
|
"devDependencies": {
|
|
"@eslint/js": "^10.0.1",
|
|
"@tailwindcss/postcss": "^4.3.0",
|
|
"@tailwindcss/typography": "^0.5.19",
|
|
"@types/mdx": "^2.0.13",
|
|
"@types/node": "^25.7.0",
|
|
"@types/react": "19.2.14",
|
|
"@types/react-dom": "19.2.3",
|
|
"@typescript-eslint/eslint-plugin": "^8.59.3",
|
|
"@typescript-eslint/parser": "^8.59.3",
|
|
"eslint": "^10.3.0",
|
|
"eslint-config-prettier": "^10.1.8",
|
|
"eslint-import-resolver-typescript": "^4.4.4",
|
|
"eslint-plugin-import": "^2.32.0",
|
|
"eslint-plugin-mdx": "^3.7.0",
|
|
"glob": "^13.0.6",
|
|
"globals": "^17.6.0",
|
|
"next-validate-link": "^1.6.6",
|
|
"postcss": "^8.5.23",
|
|
"raw-loader": "^4.0.2",
|
|
"remark-heading-id": "^1.0.1",
|
|
"semver": "^7.8.0",
|
|
"tailwindcss": "^4.3.0",
|
|
"tailwindcss-animate": "^1.0.7",
|
|
"tsx": "4.21.0",
|
|
"typescript": "^5.9.3",
|
|
"yaml-loader": "^0.9.0"
|
|
}
|
|
}
|