[dnevzorov]

AppSync ignores quoted descriptions (" and """) and reads # comments instead. Stitching also drops # comments.

This converts every description to a # comment block, for single and stitched schemas:

• blank lines are removed (AppSync keeps only the text after the last empty comment line);
• argument and enum value descriptions, which AppSync drops, are folded into the field, directive or enum description as Arguments: / Values: lists.

Replaces #639, which used the fork's master as head and picked up unrelated changes.

Summary by CodeRabbit

• New Features
  • Schema descriptions are now rendered as # comments that AppSync can read, including descriptions for fields, arguments, directives, enums, and enum values.
  • Argument and enum-value descriptions are included with their parent field or enum. Blank comment lines are removed, and descriptions are converted in both single-file and merged schemas. Existing leading comments are also preserved when generating schema output.
• Documentation
  • Updated schema guidance to explain description conversion and clarify that stitching can remove existing # descriptions.

[coderabbitai]

No actionable comments were generated in the recent review.

Walkthrough

Schema generation converts GraphQL descriptions into # comments for single-file and merged schemas. It folds argument descriptions into fields and enum-value descriptions into enums. Fixtures, snapshots, and configuration documentation cover the converted output.

Changes: Schema description conversion

Layer / File(s)	Summary
Convert descriptions during schema generation src/resources/Schema.ts	Schema generation converts descriptions for single-file and merged schemas. The converter uses leading comments when descriptions are absent, folds argument and enum-value descriptions into parent descriptions, and prints definitions and fields with comments. The validation method is renamed to validateSchema; its implementation is unchanged.
Cover converted descriptions src/__tests__/fixtures/schemas/*, src/__tests__/schema.test.ts, doc/general-config.md	Fixtures and snapshots cover field, argument, type, enum, and enum-value descriptions in converted schemas. The configuration guide describes comment conversion and description folding.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant Schema as Schema.generateSchema
  participant Converter as convertDescriptions
  participant Printer as Schema definition and field printers
  Schema->>Converter: Schema text
  Converter->>Converter: Extract comments and fold descriptions
  Converter->>Printer: Definitions with converted descriptions
  Printer-->>Schema: Schema text with # comments

Loading

Possibly related PRs

• sid88in/serverless-appsync-plugin#639: Both PRs convert GraphQL descriptions into AppSync-compatible # comments. PR #764 continues the schema-conversion implementation, including enum extension values.
• sid88in/serverless-appsync-plugin#760: PR #760 changes how generated schema text is delivered through DefinitionS3Location. PR #764 converts descriptions in that generated text.

Merge Risk: Minimal · up to ad339

The change has no actionable merge-blocking risk after review.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documenta…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title "fix: convert GraphQL descriptions into AppSync comments" matches the main change. The raw summary shows Schema.ts now converts schema descriptions into # comments for AppSync, and the s…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Title check

Explanation

The title "fix: convert GraphQL descriptions into AppSync comments" matches the main change. The raw summary shows Schema.ts now converts schema descriptions into # comments for AppSync, and the schema tests and fixtures expect that output. The PR objectives state the same goal. The title is specific and concise, and it uses the conventional fix: prefix.

Full details: Docstring Coverage

Explanation

Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 6 functions across 2 files. (1 skipped: 1 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

Finishing Touches

Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Some tools did not complete. Review the errors below.

ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install timed out. The project may have too many dependencies for the sandbox.

CodeRabbit Verify

• Run CodeRabbit Verify to test the changes in this pull request.

Recent review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: e01ea8f5-d6ea-44ee-b7fa-5ab12212ec14

Commits

Reviewing files that changed from the base of the PR and between de1c5d4 and ad33924.

Files selected for processing: 2

• src/__tests__/fixtures/schemas/single/schema.graphql
• src/resources/Schema.ts

Files skipped from review as they are similar to previous changes: 1

• src/tests/fixtures/schemas/single/schema.graphql

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 1 remain after this review.

[coderabbitai]

• Fix comments: Fix CodeRabbit comments on this PR

[coderabbitai]

Additional comments: 1

src/resources/Schema.ts: 1

209-209: Minor · Functional Correctness · Quick win

Unverified finding
Verification ran but could not confirm this finding. It is shown for review, not as a verified issue.

Preserve empty-comment boundaries in existing comments.

The generic visitor now captures field comments, but this filter joins blocks separated by an empty # line. AppSync previously used only the text after that line as the description. Keep only that final block when converting existing comments. (raw.githubusercontent.com)

Review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: c142092f-aab9-4fb0-b1f3-b5146377b513

Commits

Reviewing files that changed from the base of the PR and between bed237f and de1c5d4.

Files selected for processing: 3

• src/__tests__/fixtures/schemas/single/schema.graphql
• src/__tests__/schema.test.ts
• src/resources/Schema.ts

Files skipped from review as they are similar to previous changes: 1

• src/tests/fixtures/schemas/single/schema.graphql

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 2 remain after this review.