ci: Add redirect target validator, fix 18 broken redirects (#1093)

* ci: Add redirect target validator and fix 18 broken redirects

Add validate-redirects CI check that verifies all .gitbook.yaml
redirect targets resolve to existing pages. Fix 18 broken targets
caused by pages being moved or removed over time.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: Keep README.md redirect targets, update validator to handle them

GitBook resolves README.md in redirect targets as directory URLs, so
these don't need to be changed. Update the validator to accept
foo/README.md when foo.md exists as the page file.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: Remove redundant latest/ redirect prefix and deduplicate entry

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: Replace ad-hoc YAML parser with yaml package in redirect validator

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* ci: Format code

* fix: Use actual file paths for redirect targets instead of README.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: Remove implicit directory/README.md resolution from redirect validator

Redirect targets should always point to exact files.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: Ensure all redirect targets point to files, not bare directories

Replace bare directory targets with explicit README.md paths and
update the validator to reject directories.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: Remove unnecessary comments from redirect validator

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: Remove unused .md extension fallback from redirect validator

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: Remove README.md→parent.md fallback from redirect validator

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Seam Bot <seambot@getseam.com>

Author: 3 people

.gitbook.yaml

@@ -4,7 +4,6 @@ root: ./docs/guides/
   readme: README.md
   summary: SUMMARY.md
 redirects:
-  latest/quickstart/get-api-key: latest/quickstart.md
   quickstart/get-api-key: quickstart.md
   quickstart/installation: quickstart.md
   quickstart/authentication: quickstart.md
@@ -16,18 +15,18 @@ redirects:
   core-concepts/workspaces/personal-access-tokens: core-concepts/authentication/personal-access-tokens.md
   core-concepts/workspaces/client-session-tokens: core-concepts/authentication/client-session-tokens/README.md
   core-concepts/workspaces/client-session-tokens/implementing-client-sessions-for-device-management-in-the-backend: core-concepts/authentication/client-session-tokens/implementing-client-sessions-for-device-management-in-the-backend.md
-  products/access-systems/user-management: capability-guides/access-systems/user-management/README.md
-  capability-guides/access-systems/managing-credentials: capability-guides/access-systems/managing-credentials/README.md
+  products/access-systems/user-management: capability-guides/access-systems/user-management.md
+  capability-guides/access-systems/managing-credentials: capability-guides/access-systems/managing-credentials.md
   capability-guides/access-systems/assigning-credentials-to-users: capability-guides/access-systems/managing-credentials/assigning-credentials-to-users.md
   products/access-systems/suspending-and-unsuspending-users: capability-guides/access-systems/user-management/suspending-and-unsuspending-users.md
   products/seam-bridge-in-development: capability-guides/seam-bridge.md
   core-concepts/connect-webviews: core-concepts/connect-webviews/README.md
   device-guides/4suites-locks: device-and-system-integration-guides/4suites-locks/README.md
   device-guides/assa-abloy-visionline-access-control-system-in-development: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/README.md
-  device-guides/assa-abloy-visionline-access-control-system-in-development/credential-types: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/credential-types.md
-  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/visionline-credential-metadata: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-credential-metadata.md
+  device-guides/assa-abloy-visionline-access-control-system-in-development/credential-types: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/README.md
+  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/visionline-credential-metadata: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/README.md
   device-guides/assa-abloy-visionline-access-control-system-in-development/common-use-cases: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/common-use-cases.md
-  capability-guides/access-systems/understanding-acs-differences: capability-guides/access-systems/understanding-access-control-system-differences.md
+  capability-guides/access-systems/understanding-acs-differences: capability-guides/access-systems/README.md
   capability-guides/thermostats/creating-and-managing-climate-schedules: capability-guides/thermostats/creating-and-managing-thermostat-schedules.md
   device-guides/get-started-with-schlage-locks: device-and-system-integration-guides/schlage-locks/get-started-with-schlage-locks.md
   api-clients/access-codes/convert-an-unmanaged-access-code: api/access_codes/unmanaged/convert_to_managed.md
@@ -95,16 +94,16 @@ redirects:
   api-clients/connected-accounts/list-connected-accounts: api/connected_accounts/list.md
   api-clients/connected-accounts/update-a-connected-account: api/connected_accounts/update.md
   api-clients/connected-accounts: api/connected_accounts/README.md
-  api-clients/devices/delete-device: api/devices/delete.md
+  api-clients/devices/delete-device: api/devices/README.md
   api-clients/devices/get-device-1: api/devices/unmanaged/get.md
   api-clients/devices/get-device: api/devices/get.md
   api-clients/devices/list-device-providers: api/devices/list_device_providers.md
   api-clients/devices/list-devices: api/devices/list.md
   api-clients/devices/list-unmanaged-devices: api/devices/unmanaged/list.md
   api-clients/devices/update-device: api/devices/update.md
   api-clients/devices/update-unmanaged-device: api/devices/unmanaged/update.md
-  api-clients/events/get-an-event: api-clients/events/get.md
-  api-clients/events/list-events: api-clients/events/list.md
+  api-clients/events/get-an-event: api/events/get.md
+  api-clients/events/list-events: api/events/list.md
   api-clients/locks/get-lock: api/locks/get.md
   api-clients/locks/list-locks: api/locks/list.md
   api-clients/locks/lock-a-lock: api/locks/lock_door.md
@@ -114,7 +113,7 @@ redirects:
   api-clients/noise-sensors/list-noise-thresholds: api/noise_sensors/noise_thresholds/list.md
   api-clients/noise-sensors/update-noise-threshold: api/noise_sensors/noise_thresholds/update.md
   api-clients/noise-sensors: api/noise_sensors/README.md
-  api-clients/thermostats/get-thermostat: api/thermostats/get.md
+  api-clients/thermostats/get-thermostat: api/thermostats/README.md
   api-clients/thermostats/list-thermostats: api/thermostats/list.md
   api-clients/thermostats/set-fan-mode: api/thermostats/set_fan_mode.md
   api-clients/thermostats/set-to-cool-mode: api/thermostats/cool.md
@@ -136,7 +135,7 @@ redirects:
   api-clients/workspaces/get-workspace: api/workspaces/get.md
   api-clients/workspaces/reset-workspace: api/workspaces/reset_sandbox.md
   api-clients/phones/create-a-sandbox-phone: api/phones/simulate/create_sandbox_phone.md
-  device-and-system-integration-guides/assa-abloy-credential-services-credential-manager-in-development: device-and-system-integration-guides/assa-abloy-credential-services-credential-manager/README.md
+  device-and-system-integration-guides/assa-abloy-credential-services-credential-manager-in-development: device-and-system-integration-guides/assa-abloy-vingcard-credential-services.md
   device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/README.md
   device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/visionline-acs-setup-instructions: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/README.md
   device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/README.md
@@ -183,13 +182,13 @@ redirects:
   device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/step-7-purchase-and-import-the-callback-and-mobile-service-options-from-assa-abloy: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/step-7-purchase-and-import-the-callback-and-mobile-service-options-from-assa-abloy.md
   device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/step-8-create-a-production-workspace: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/step-8-create-a-production-workspace.md
   device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/step-9-connect-your-visionline-production-account-to-seam: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/step-9-connect-your-visionline-production-account-to-seam.md
-  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/credential-types/README.md
-  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/issuing-various-types-of-guest-mobile-credentials: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/credential-types/issuing-various-types-of-guest-mobile-credentials.md
-  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/issuing-various-types-of-guest-joiner-mobile-credentials: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/credential-types/issuing-various-types-of-guest-joiner-mobile-credentials.md
-  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/retrieving-guest-and-common-entrances: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/credential-types/retrieving-guest-and-common-entrances.md
-  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/checking-if-a-user-identity-has-a-phone-that-is-set-up-for-a-credential-manager: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/credential-types/checking-if-a-user-identity-has-a-phone-that-is-set-up-for-a-credential-manager.md
-  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/updating-guest-mobile-credentials: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/credential-types/updating-guest-mobile-credentials.md
-  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/revoking-mobile-credentials: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/credential-types/revoking-mobile-credentials.md
+  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/README.md
+  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/issuing-various-types-of-guest-mobile-credentials: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/README.md
+  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/issuing-various-types-of-guest-joiner-mobile-credentials: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/README.md
+  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/retrieving-guest-and-common-entrances: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/README.md
+  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/checking-if-a-user-identity-has-a-phone-that-is-set-up-for-a-credential-manager: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/README.md
+  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/updating-guest-mobile-credentials: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/README.md
+  device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/credential-types/revoking-mobile-credentials: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/README.md
   device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/mobile-credential-related-properties: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/mobile-credential-related-properties.md
   device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/common-use-cases: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/common-use-cases.md
   device-and-system-integration-guides/assa-abloy-visionline-access-control-system-in-development/special-requirements-for-android-mobile-access-sdk-development: device-and-system-integration-guides/assa-abloy-visionline-access-control-system/special-requirements-for-android-mobile-access-sdk-development.md

.github/workflows/generate.yml

@@ -84,3 +84,5 @@ jobs:
         run: npm run validate-links
       - name: Validate all pages are in SUMMARY.md
         run: npm run validate-orphan-pages
+      - name: Validate redirect targets
+        run: npm run validate-redirects

codegen/validate-redirects.ts

@@ -0,0 +1,59 @@
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+import YAML from 'yaml'
+
+import { siteSections } from './lib/config.js'
+
+const gitbookConfig = YAML.parse(readFileSync('.gitbook.yaml', 'utf-8')) as {
+  redirects?: Record<string, string>
+}
+
+interface Redirect {
+  source: string
+  target: string
+}
+
+const redirects: Redirect[] = Object.entries(gitbookConfig.redirects ?? {}).map(
+  ([source, target]) => ({ source, target }),
+)
+
+function pageExists(fullPath: string): boolean {
+  return existsSync(fullPath) && statSync(fullPath).isFile()
+}
+
+function resolveTarget(target: string): boolean {
+  for (const section of siteSections) {
+    if (section.urlPrefix === '') continue
+
+    const prefix = section.urlPrefix.replace(/^\//, '') + '/'
+    if (target.startsWith(prefix)) {
+      const relativePath = target.slice(prefix.length)
+      return pageExists(join(section.root, relativePath))
+    }
+  }
+
+  const guidesSection = siteSections.find((s) => s.urlPrefix === '')
+  if (guidesSection == null) return false
+
+  return pageExists(join(guidesSection.root, target))
+}
+
+const broken: Redirect[] = redirects.filter((r) => !resolveTarget(r.target))
+
+if (broken.length > 0) {
+  // eslint-disable-next-line no-console
+  console.error(
+    `Found ${broken.length} redirect(s) with missing target(s) in .gitbook.yaml:\n`,
+  )
+  for (const { source, target } of broken) {
+    // eslint-disable-next-line no-console
+    console.error(`  ${source}`)
+    // eslint-disable-next-line no-console
+    console.error(`    target: ${target}\n`)
+  }
+  process.exit(1)
+} else {
+  // eslint-disable-next-line no-console
+  console.log('All .gitbook.yaml redirect targets are valid.')
+}

package-lock.json

@@ -19,6 +19,7 @@
     "validate-paths": "tsx codegen/validate-paths.ts",
     "validate-links": "tsx codegen/validate-links.ts",
     "validate-orphan-pages": "tsx codegen/validate-orphan-pages.ts",
+    "validate-redirects": "tsx codegen/validate-redirects.ts",
     "typecheck": "tsc",
     "lint": "eslint .",
     "postlint": "prettier --check --ignore-path .prettierignore .",
@@ -41,6 +42,7 @@
     "command-exists": "^1.2.9",
     "execa": "^9.3.1",
     "prettier": "^3.0.0",
+    "yaml": "^2.8.3",
     "zod": "^3.23.8"
   }
 }