--- name: graphql-inspector-audit-022053f65478 user-invocable: false description: Use when auditing GraphQL operations for complexity metrics, depth analysis, directive usage, or query performance concerns. allowed-tools: [Read, Write, Edit, Bash, Glob, Grep] --- # GraphQL Inspector - Audit Expert knowledge of GraphQL Inspector's audit command for analyzing operation complexity and identifying potential performance issues. ## Overview The audit command analyzes GraphQL operations to provide metrics about query depth, directive count, alias count, and complexity. This helps identify operations that may cause performance issues before they reach production. ## Core Commands ### Basic Audit ```bash # Audit all GraphQL operations npx @graphql-inspector/cli audit './src/**/*.graphql' # Audit operations from TypeScript files npx @graphql-inspector/cli audit './src/**/*.tsx' # Audit with multiple patterns npx @graphql-inspector/cli audit './packages/**/*.graphql' './apps/**/*.tsx' ``` ### Audit with Schema ```bash # Audit against a specific schema npx @graphql-inspector/cli audit './src/**/*.graphql' --schema './schema.graphql' ``` ## Metrics Analyzed ### Query Depth Measures the maximum nesting level of a query: ```graphql # Depth: 4 query UserPosts { user { # 1 posts { # 2 comments { # 3 author { # 4 name } } } } } ``` High depth operations can cause: - Slow database queries (N+1 problems) - Memory pressure on resolvers - Long response times ### Alias Count Counts the number of field aliases: ```graphql # Alias count: 3 query MultipleUsers { admin: user(id: "1") { name } moderator: user(id: "2") { name } member: user(id: "3") { name } } ``` High alias counts can: - Multiply database queries - Increase payload size - Indicate query batching abuse ### Directive Count Counts directives used in the operation: ```graphql # Directive count: 4 query ConditionalData($includeEmail: Boolean!, $skipPhone: Boolean!) { user { name email @include(if: $includeEmail) phone @skip(if: $skipPhone) avatar @cacheControl(maxAge: 3600) bio @deprecated } } ``` ### Token Count Counts the total tokens in the operation: ```graphql # Higher token count = more complex query query ComplexQuery { users( filter: { status: ACTIVE, role: ADMIN } orderBy: { field: NAME, direction: ASC } pagination: { limit: 10, offset: 0 } ) { id name email role createdAt updatedAt } } ``` ## Audit Output The audit command outputs detailed metrics for each operation: ``` ┌──────────────────────────────────────────────────────────────┐ │ GetUser (./src/queries/user.graphql) │ ├──────────────────────────────────────────────────────────────┤ │ Depth │ 5 │ │ Aliases │ 0 │ │ Directives │ 2 │ │ Tokens │ 45 │ │ Complexity │ 12 │ └──────────────────────────────────────────────────────────────┘ ``` ## Configuration Create `.graphql-inspector.yaml`: ```yaml audit: documents: './src/**/*.graphql' # Thresholds for warnings thresholds: depth: 10 aliases: 5 directives: 10 tokens: 500 complexity: 100 ``` ## CI/CD Integration ### GitHub Actions ```yaml name: Audit Operations user-invocable: false on: pull_request: paths: - 'src/**/*.graphql' - 'src/**/*.tsx' jobs: audit: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install Inspector run: npm install -g @graphql-inspector/cli - name: Audit operations run: | graphql-inspector audit 'src/**/*.graphql' ``` ### Audit Report Generate a detailed report: ```bash # JSON output for processing npx @graphql-inspector/cli audit './src/**/*.graphql' --json > audit-report.json # Human-readable output npx @graphql-inspector/cli audit './src/**/*.graphql' 2>&1 | tee audit-report.txt ``` ## Use Cases ### Pre-PR Checks Run before creating pull requests: ```bash # Script to check operations before PR #!/bin/bash echo "Auditing GraphQL operations..." npx @graphql-inspector/cli audit './src/**/*.graphql' if [ $? -ne 0 ]; then echo "Warning: Some operations may have performance issues" fi ``` ### Periodic Analysis Schedule regular audits: ```yaml # GitHub Action for weekly audit name: Weekly GraphQL Audit user-invocable: false on: schedule: - cron: '0 9 * * 1' # Monday 9am jobs: audit: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: npm install -g @graphql-inspector/cli - run: graphql-inspector audit './src/**/*.graphql' --json > audit.json - name: Upload audit report uses: actions/upload-artifact@v4 with: name: graphql-audit path: audit.json ``` ### Complexity Budgets Set limits per operation type: ```yaml # Custom thresholds by operation type audit: thresholds: queries: depth: 10 complexity: 100 mutations: depth: 5 complexity: 50 subscriptions: depth: 3 complexity: 25 ``` ## Best Practices 1. **Regular audits** - Run weekly to catch complexity creep 2. **Set thresholds** - Define acceptable limits for your API 3. **Track trends** - Monitor metrics over time 4. **Review outliers** - Investigate operations with high metrics 5. **Optimize hot paths** - Focus on frequently-used operations 6. **Document exceptions** - Explain why complex operations are needed 7. **Educate team** - Share audit results and best practices 8. **Automate alerts** - Notify when thresholds are exceeded ## Common Patterns ### Reducing Query Depth Before (depth 6): ```graphql query DeepQuery { user { posts { comments { author { profile { avatar } } } } } } ``` After (depth 3): ```graphql query FlattenedQuery { user { posts { comments { authorName authorAvatar # Denormalized field } } } } ``` ### Reducing Alias Count Before (5 aliases): ```graphql query MultipleUsers { user1: user(id: "1") { ...UserFields } user2: user(id: "2") { ...UserFields } user3: user(id: "3") { ...UserFields } user4: user(id: "4") { ...UserFields } user5: user(id: "5") { ...UserFields } } ``` After (batch query): ```graphql query BatchUsers { users(ids: ["1", "2", "3", "4", "5"]) { ...UserFields } } ``` ## Troubleshooting ### No operations found - Check glob pattern matches files - Verify files contain valid GraphQL operations - Ensure file extensions are included ### Metrics seem wrong - Verify operation is complete - Check for fragment definitions - Review inline fragment usage ### Audit is slow - Limit scope with specific globs - Exclude generated files - Use `--parallel` if available ## When to Use This Skill - Performance analysis of GraphQL operations - Identifying complex queries before production - Setting up complexity budgets - Regular codebase health checks - Training developers on query optimization - Pre-release quality gates --- Source attribution: TheBushidoCollective Original project: https://github.com/TheBushidoCollective/han/blob/19caa51d5fd144ef6b2764f2332f4c856aa5d1af/plugins/tools/graphql-inspector/skills/graphql-inspector-audit/SKILL.md License: Apache-2.0 License information: https://www.apache.org/licenses/LICENSE-2.0 Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice # Functional Source License, Version 1.1, ALv2 Future License ## Abbreviation FSL-1.1-ALv2 ## Notice Copyright 2025 The Bushido Collective ## Terms and Conditions ### Licensor ("We") The party offering the Software under these Terms and Conditions. ### The Software The "Software" is each version of the software that we make available under these Terms and Conditions, as indicated by our inclusion of these Terms and Conditions with the Software. ### License Grant Subject to your compliance with this License Grant and the Patents, Redistribution and Trademark clauses below, we hereby grant you the right to use, copy, modify, create derivative works, publicly perform, publicly display and redistribute the Software for any Permitted Purpose identified below. ### Permitted Purpose A Permitted Purpose is any purpose other than a Competing Use. A Competing Use means making the Software available to others in a commercial product or service that: 1. substitutes for the Software; 2. substitutes for any other product or service we offer using the Software that exists as of the date we make the Software available; or 3. offers the same or substantially similar functionality as the Software. Permitted Purposes specifically include using the Software: 1. for your internal use and access; 2. for non-commercial education; 3. for non-commercial research; and 4. in connection with professional services that you provide to a licensee using the Software in accordance with these Terms and Conditions. ### Patents To the extent your use for a Permitted Purpose would necessarily infringe our patents, the license grant above includes a license under our patents. If you make a claim against any party that the Software infringes or contributes to the infringement of any patent, then your patent license to the Software ends immediately. ### Redistribution The Terms and Conditions apply to all copies, modifications and derivatives of the Software. If you redistribute any copies, modifications or derivatives of the Software, you must include a copy of or a link to these Terms and Conditions and not remove any copyright notices provided in or with the Software. ### Disclaimer THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT. IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE. ### Trademarks Except for displaying the License Details and identifying us as the origin of the Software, you have no right under these Terms and Conditions to use our trademarks, trade names, service marks or product names. ## Grant of Future License We hereby irrevocably grant you an additional license to use the Software under the Apache License, Version 2.0 that is effective on the second anniversary of the date we make the Software available. On or after that date, you may use the Software under the Apache License, Version 2.0, in which case the following will apply: Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. # Mega AI Hub resource metadata Creator / publisher: TheBushidoCollective Original project: https://github.com/TheBushidoCollective/han/blob/19caa51d5fd144ef6b2764f2332f4c856aa5d1af/plugins/tools/graphql-inspector/skills/graphql-inspector-audit/SKILL.md Attribution basis: Source repository record Fields of work: Data & Analytics, Development & Engineering, Product Management Roles: Backend Developer, Data Analyst, Product Manager Specialties: API Tools: Graphql Inspector Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 6cbb9c5a24041304580e5b426bfd4a744f7924245c75d49ef4431decbad90993