Skip to content

feat(codegen): replace generic <value> placeholders with type-aware placeholders#855

Merged
pyramation merged 1 commit intomainfrom
devin/1773988167-type-aware-placeholders
Mar 20, 2026
Merged

feat(codegen): replace generic <value> placeholders with type-aware placeholders#855
pyramation merged 1 commit intomainfrom
devin/1773988167-type-aware-placeholders

Conversation

@pyramation
Copy link
Contributor

Summary

Generated documentation and skill reference files previously used generic <value> placeholders in all code examples, which were non-descriptive. This PR replaces them with type-aware placeholders derived from the GraphQL schema (e.g. <UUID>, <String>, <Int>, <Boolean>).

Before: db.car.findOne({ id: '<value>' ... })
After: db.car.findOne({ id: '<UUID>' ... })

Three new helpers were added to docs-utils.ts:

  • fieldPlaceholder(field) — for table fields (CleanField with type.gqlType)
  • pkPlaceholder(pk) — for primary key fields (PrimaryKeyField with direct gqlType)
  • argPlaceholder(arg, registry?) — for operation arguments; expands INPUT_OBJECT types into constituent fields when ≤5 fields, otherwise shows the type name

flattenedArgsToFlags() was also updated to use <TypeName> in CLI flag docs.

The TypeRegistry is now threaded through generate.ts → ORM/hooks doc generators so argPlaceholder can resolve INPUT_OBJECT fields.

Review & Testing Checklist for Human

  • Verify argPlaceholder INPUT_OBJECT expansion: The function expands input objects with ≤5 fields (excluding clientMutationId). Run codegen against a schema with input types to confirm the sign-in example now shows { email: '<String>', password: '<String>' } instead of '<value>'
  • Confirm pkPlaceholder vs fieldPlaceholder distinction is correct everywhere: PrimaryKeyField has gqlType at top level while CleanField nests it under .type.gqlType. Grep for pkPlaceholder and fieldPlaceholder usage to verify no mismatches
  • Check ORM update examples: The update code examples changed from '<new-value>' (semantic hint) to the field's actual type placeholder — verify this tradeoff is acceptable
  • Run full codegen against a real schema (e.g. the auth schema that produces sign-in.md) to verify the actual output matches expectations

Notes

  • Semantic placeholders in CLI config/auth commands (<key>, <value>, <token>, <name>) are intentionally unchanged — they describe the semantic role, not a typed field
  • The hardcoded '<UUID>' in generic SKILL.md examples (db.<model>.findOne({ id: '<UUID>' ...})) assumes UUID primary keys, which is the common case
  • 6 test failures in CI are pre-existing module resolution issues (e.g. @pgpmjs/core, pg-cache) unrelated to this change

Link to Devin session: https://app.devin.ai/sessions/6acc9cfe2eb74b44819e6c7e3d747d68
Requested by: @pyramation

…laceholders

- Add fieldPlaceholder(), pkPlaceholder(), and argPlaceholder() helpers to docs-utils.ts
- fieldPlaceholder: generates '<TypeName>' from CleanField (e.g. '<String>', '<UUID>')
- pkPlaceholder: generates '<TypeName>' from PrimaryKeyField
- argPlaceholder: handles scalars and INPUT_OBJECT types (expands fields when ≤5)
- Update flattenedArgsToFlags() to use <TypeName> instead of <value>
- Update ORM docs-generator to use type-aware placeholders for all code examples
- Update hooks docs-generator to use type-aware placeholders for all code examples
- Update CLI docs-generator to use type-aware flag placeholders
- Thread TypeRegistry through generate.ts to ORM and hooks generators
- Update test snapshots
@devin-ai-integration
Copy link
Contributor

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment and CI monitoring

@pyramation pyramation merged commit 633aadf into main Mar 20, 2026
44 checks passed
@pyramation pyramation deleted the devin/1773988167-type-aware-placeholders branch March 20, 2026 06:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant