docs: add SDK dependency map generator and sync tooling by ciscoRankush · Pull Request #662 · webex/widgets

ciscoRankush · 2026-03-24T12:50:17Z

COMPLETES #N/A (new tooling initiative — companion to webex-js-sdk PR #4800)

This pull request addresses

The consumer side of cross-repo SDK synchronization. When SDK APIs change in @webex/contact-center, ccWidgets needs to know exactly which files and line numbers are affected. Currently there is no automated way to detect impact of SDK changes on the consumer codebase.

by making the following changes

scripts/generate-sdk-deps.ts: ts-morph based scanner that analyzes all @webex/contact-center imports across the monorepo and maps each SDK API (methods, types, events) to exact consumer file paths and line numbers.
sdk-dependencies.yaml: Auto-generated dependency map tracking 26 types, 1 method call, and 34 total import usages.
scripts/tsconfig.json: Node-specific TypeScript config for scripts.
.claude/commands/sync-sdk.md: /sync-sdk Claude Code skill that diffs SDK manifests and produces impact reports.
.claude/hooks/check-sdk-version-change.sh: PostToolUse hook reminding developers to run /sync-sdk on SDK version changes.
.sdk-cache/: Cached previous SDK manifest for version-to-version diffing.

Key capabilities:

Scans 73 source files (excludes dist/, tests, node_modules)
Reads SDK manifest from node_modules or falls back to local ccSDK path
Tracks method calls, type imports, and event listeners with file + line precision
Impact report classifies changes as breaking vs non-breaking

Change Type

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update
Tooling change
Internal code refactor

The following scenarios were tested

Ran npx ts-node --project scripts/tsconfig.json scripts/generate-sdk-deps.ts — generates sdk-dependencies.yaml tracking 26 types, 1 method, 34 imports
Verified dist/test/node_modules exclusion
Verified manifest fallback to local ccSDK path
End-to-end: simulated stationLogin param change -> impact report correctly identified affected files
PostToolUse hook tested: fires on SDK package.json edit, silent on others

The GAI Coding Policy And Copyright Annotation Best Practices

Checklist before merging

I have not skipped any automated checks
All existing and new tests passed
I have updated the testing document
I have tested the functionality with amplify link

Add automated SDD documentation drift detection tooling: - /spec-drift: full scan command for validating all ai-docs against source code - /spec-drift-changed: incremental scan for changed files only - Pre-commit hook to block commits when ai-docs drift is unverified Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Register hook in settings.json (was dead code without it) - Fail-closed when python3 unavailable or JSON parse fails - Use content-based hash (git diff --cached) instead of path-only hash - Don't consume marker in PreToolUse — invalidated naturally by content changes - Precise case pattern to avoid matching git commit-tree - Add shasum/sha256sum portability fallback - Fix "Task tool" → "Agent tool" references in command files - Add agent timeout handling rule - Add staged-only content note for verification marker - Make widget path mappings dynamic instead of hardcoded - Label inventory as example - Document advisory-only nature of verification Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add cross-repo SDK synchronization tooling for detecting and tracking SDK API changes across the consumer codebase. - scripts/generate-sdk-deps.ts: scans all SDK imports, traces to file+line - sdk-dependencies.yaml: generated dependency map for @webex/contact-center - .claude/commands/sync-sdk.md: /sync-sdk skill for impact reports - .claude/hooks/check-sdk-version-change.sh: notifies on SDK version change - .sdk-cache/: cached manifest for version-to-version diffing Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chatgpt-codex-connector · 2026-03-24T12:57:45Z

💡 Codex Review

widgets/.github/workflows/pull-request.yml

Lines 71 to 73 in dc755f4

    
           uses: actions/checkout@v3 
        
           with: 
        
             ref: ${{ github.event.pull_request.head.sha }}

Stop running pull_request_target on untrusted head commits

This workflow runs on pull_request_target (privileged context with repository secrets) and then checks out ${{ github.event.pull_request.head.sha }}; that executes attacker-controlled code from the PR branch during yarn/build steps while secrets are already injected at workflow scope. A forked PR can exfiltrate those secrets by changing package scripts, so this is a critical CI security issue.

widgets/scripts/generate-sdk-deps.ts

Lines 283 to 285 in dc755f4

    
           // Match: instance.method() patterns 
        
           if (callText.startsWith(localName + '.')) { 
        
             const methodName = callText.replace(localName + '.', '').split('(')[0];

Track SDK instance method calls, not only imported symbols

Method usage detection only records calls whose expression starts with the imported identifier (localName.method()), so calls on SDK instances (cc.stationLogin(...), task.accept(), etc.) are missed unless the receiver itself is the import symbol. That causes the generated dependency map to under-report method consumers and can miss real breakage when SDK methods change.

widgets/.claude/settings.json

Lines 3 to 7 in dc755f4

    
           "PreToolUse": [ 
        
             { 
        
               "matcher": "Bash", 
        
               "hooks": [".claude/hooks/check-ai-docs-drift.sh"] 
        
             }

Register the SDK change hook in Claude settings

The new check-sdk-version-change.sh hook is added but never wired into .claude/settings.json; only PreToolUse is configured here. As a result, the intended PostToolUse reminder to run /sync-sdk will never execute after package.json edits, so SDK drift checks are silently skipped.

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Add usage instructions for SDK dependency tracking and /sync-sdk skill, including mandatory API verification steps for AI agents. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ca127a0b12

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-03-26T08:49:23Z

scripts/generate-sdk-deps.ts

+            if (callText.startsWith(localName + '.')) {
+              const methodName = callText.replace(localName + '.', '').split('(')[0];


Track SDK calls on instance variables

The method detector only records calls whose callee text starts with the imported symbol (for example Webex.), so it misses SDK calls made through derived instances like webex.once(...) and this.cc.register() in packages/contact-center/store/src/store.ts. That creates false negatives in sdk-dependencies.yaml, so /sync-sdk can report no impacted files even when a breaking SDK method change affects runtime code.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-03-26T08:49:23Z

scripts/generate-sdk-deps.ts

+const SCAN_DIRS = [
+  'packages/contact-center',
+];


Scan all SDK consumer directories

The scanner is hardcoded to packages/contact-center, but this repo also has SDK consumers outside that path (for example widgets-samples/cc/samples-cc-react-app/src/App.tsx imports @webex/contact-center). As a result, the generated dependency map is incomplete and the sync report can understate affected files when SDK APIs change.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-03-26T08:49:23Z

.claude/settings.json

+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [".claude/hooks/check-ai-docs-drift.sh"]


Wire PostToolUse SDK hook in settings

The commit adds .claude/hooks/check-sdk-version-change.sh, but .claude/settings.json only registers a PreToolUse hook and never registers any PostToolUse hook. That means SDK version-change reminders never run when package.json is edited, so the documented /sync-sdk safeguard is effectively disabled.

Useful? React with 👍 / 👎.

The .sdk-cache/ directory is a local dev cache for SDK manifest diffing. Each developer's cache reflects when they last ran /sync-sdk. It should not be committed. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a0c2041100

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-03-26T08:59:43Z

scripts/generate-sdk-deps.ts

+          if (callText.startsWith(importName + '.')) {
+            const methodName = callText.replace(importName + '.', '').split('(')[0];
+            const callLine = call.getStartLineNumber();
+            const qualifiedName = `default.${methodName}`;


Use canonical method keys for default-import calls

Record default-import calls under the SDK API name instead of default.*: this branch currently emits keys like default.init (see generated sdk-dependencies.yaml), but manifest-derived method changes are keyed as SDK names (for example Webex.init/init). When /sync-sdk cross-references manifest changes to dependency-map keys, these call sites can be missed, so a breaking change to Webex.init may incorrectly report no impacted consumers.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-03-26T08:59:43Z

scripts/generate-sdk-deps.ts

+      const matchedSdk = TRACKED_SDKS.find((sdk) =>
+        moduleSpecifier === sdk || moduleSpecifier.startsWith(sdk + '/')


Recognize node_modules-prefixed SDK import specifiers

Broaden the module-specifier match beyond @webex/contact-center and @webex/contact-center/...: current logic skips imports written as node_modules/@webex/contact-center/... (for example in packages/contact-center/store/src/store.types.ts), so those SDK types never enter sdk-dependencies.yaml. This creates false negatives in impact reports when those imported SDK definitions change.

Useful? React with 👍 / 👎.

Replace separate TRACKED_SDKS and SCAN_DIRS arrays with a single SDK_CONFIG array where each entry has package, scanDirs, and localManifestPath. Adding a new SDK dependency now requires one config entry instead of changes in multiple places. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

ciscoRankush and others added 3 commits March 11, 2026 14:12

ciscoRankush changed the title ~~feat: add SDK dependency map generator and sync tooling~~ chore: add SDK dependency map generator and sync tooling Mar 24, 2026

ciscoRankush changed the base branch from master to next March 24, 2026 12:54

ciscoRankush requested a review from a team as a code owner March 24, 2026 12:54

ciscoRankush changed the title ~~chore: add SDK dependency map generator and sync tooling~~ docs: add SDK dependency map generator and sync tooling Mar 24, 2026

docs: add SDK sync section to AGENTS.md

ca127a0

Add usage instructions for SDK dependency tracking and /sync-sdk skill, including mandatory API verification steps for AI agents. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chatgpt-codex-connector bot reviewed Mar 26, 2026

View reviewed changes

chore: gitignore .sdk-cache/ and remove from tracking

a0c2041

The .sdk-cache/ directory is a local dev cache for SDK manifest diffing. Each developer's cache reflects when they last ran /sync-sdk. It should not be committed. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chatgpt-codex-connector bot reviewed Mar 26, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add SDK dependency map generator and sync tooling#662

docs: add SDK dependency map generator and sync tooling#662
ciscoRankush wants to merge 6 commits intowebex:nextfrom
ciscoRankush:sdk-manifest-generator

ciscoRankush commented Mar 24, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector bot commented Mar 24, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

chatgpt-codex-connector bot Mar 26, 2026

Uh oh!

chatgpt-codex-connector bot Mar 26, 2026

Uh oh!

chatgpt-codex-connector bot Mar 26, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

chatgpt-codex-connector bot Mar 26, 2026

Uh oh!

chatgpt-codex-connector bot Mar 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		if (callText.startsWith(localName + '.')) {
		const methodName = callText.replace(localName + '.', '').split('(')[0];

		const matchedSdk = TRACKED_SDKS.find((sdk) =>
		moduleSpecifier === sdk \|\| moduleSpecifier.startsWith(sdk + '/')

Conversation

ciscoRankush commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

COMPLETES #N/A (new tooling initiative — companion to webex-js-sdk PR #4800)

This pull request addresses

by making the following changes

Change Type

The following scenarios were tested

The GAI Coding Policy And Copyright Annotation Best Practices

Checklist before merging

Uh oh!

chatgpt-codex-connector bot commented Mar 24, 2026

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

ciscoRankush commented Mar 24, 2026 •

edited

Loading