From 7fa99f10e603dc20be4252f21b44693d876fbbcb Mon Sep 17 00:00:00 2001 From: Dan Lynch Date: Tue, 17 Nov 2026 04:04:42 +0000 Subject: [PATCH 1/3] fix(codegen): computed fields in CLI/ORM/docs, prune stale generated skills - CLI: derive update fields from the patch type and create fields from the create input; never select or prompt for a field that takes arguments - ORM: fields returning an object type need a sub-selection and get a real interface + Select type instead of an unknown alias - docs: examples only select/set fields that exist and are selectable - skills: a generated skill directory holds exactly the files generated, and generated skills of dropped targets are removed --- .../client-generator.test.ts.snap | 10 +- .../__tests__/codegen/cli-generator.test.ts | 120 +++++++++++++++ .../__tests__/codegen/computed-fields.test.ts | 104 +++++++++++++ .../codegen/generated-skills.test.ts | 107 +++++++++++++ .../src/core/codegen/cli/docs-generator.ts | 8 +- .../codegen/cli/table-command-generator.ts | 12 +- .../codegen/src/core/codegen/docs-utils.ts | 76 ++++++++-- .../src/core/codegen/hooks-docs-generator.ts | 18 +-- .../src/core/codegen/orm/docs-generator.ts | 10 +- .../core/codegen/orm/input-types-generator.ts | 89 +++++++++-- .../core/codegen/templates/select-types.ts | 10 +- graphql/codegen/src/core/codegen/utils.ts | 81 ++++++++-- graphql/codegen/src/core/generate.ts | 45 +++++- graphql/codegen/src/core/output/index.ts | 6 + graphql/codegen/src/core/output/skills.ts | 143 ++++++++++++++++++ 15 files changed, 764 insertions(+), 75 deletions(-) create mode 100644 graphql/codegen/src/__tests__/codegen/computed-fields.test.ts create mode 100644 graphql/codegen/src/__tests__/codegen/generated-skills.test.ts create mode 100644 graphql/codegen/src/core/output/skills.ts diff --git a/graphql/codegen/src/__tests__/codegen/__snapshots__/client-generator.test.ts.snap b/graphql/codegen/src/__tests__/codegen/__snapshots__/client-generator.test.ts.snap index 132201a03b..32a3544b0f 100644 --- a/graphql/codegen/src/__tests__/codegen/__snapshots__/client-generator.test.ts.snap +++ b/graphql/codegen/src/__tests__/codegen/__snapshots__/client-generator.test.ts.snap @@ -553,9 +553,13 @@ export type InferSelectResult = TSelect extends undefined ? K extends keyof TEntity ? NonNullable extends ConnectionResult ? ConnectionResult> - : - | InferSelectResult, NestedSelect> - | (null extends TEntity[K] ? null : never) + : NonNullable extends readonly (infer Item)[] + ? + | InferSelectResult, NestedSelect>[] + | (null extends TEntity[K] ? null : never) + : + | InferSelectResult, NestedSelect> + | (null extends TEntity[K] ? null : never) : never : K extends keyof TEntity ? TEntity[K] diff --git a/graphql/codegen/src/__tests__/codegen/cli-generator.test.ts b/graphql/codegen/src/__tests__/codegen/cli-generator.test.ts index d02c21d918..a3bdeba050 100644 --- a/graphql/codegen/src/__tests__/codegen/cli-generator.test.ts +++ b/graphql/codegen/src/__tests__/codegen/cli-generator.test.ts @@ -25,6 +25,7 @@ import type { Relations, Table, TypeRef, + TypeRegistry, } from '../../types/schema'; const fieldTypes = { @@ -281,6 +282,125 @@ describe('cli-generator without a create mutation', () => { }); }); +// A table shaped like the storage `File` type: no create mutation, a computed +// field that takes arguments, and computed fields with and without an object +// return type. None of the computed fields are in the patch type. +const computedFileTable = createTable({ + name: 'Asset', + fields: [ + { name: 'id', type: fieldTypes.uuid }, + { name: 'filename', type: fieldTypes.string }, + { name: 'search', type: { gqlType: 'FullText', isArray: false } }, + { name: 'searchTsvRank', type: { gqlType: 'Float', isArray: false } }, + { name: 'downloadUrl', type: fieldTypes.string }, + { + name: 'uploadUrl', + type: fieldTypes.string, + args: [{ name: 'width', type: createTypeRef('SCALAR', 'Int'), isRequired: false }], + }, + { name: 'uploadVersions', type: { gqlType: 'AssetVersion', isArray: true } }, + ], + query: { + all: 'assets', + one: 'asset', + create: null, + update: 'updateAsset', + delete: 'deleteAsset', + }, +}); + +const computedFileRegistry: TypeRegistry = new Map([ + [ + 'AssetPatch', + { + kind: 'INPUT_OBJECT', + name: 'AssetPatch', + inputFields: [ + { name: 'filename', type: createTypeRef('SCALAR', 'String') }, + { name: 'search', type: createTypeRef('SCALAR', 'FullText') }, + ], + }, + ], + [ + 'AssetVersion', + { + kind: 'OBJECT', + name: 'AssetVersion', + fields: [ + { name: 'url', type: createTypeRef('NON_NULL', null, createTypeRef('SCALAR', 'String')) }, + { name: 'width', type: createTypeRef('SCALAR', 'Int') }, + ], + }, + ], +]); + +describe('cli-generator with computed fields', () => { + const generateAssetCommand = (typeRegistry?: TypeRegistry): string => { + const { files } = generateCli({ + tables: [computedFileTable], + customOperations: { queries: [], mutations: [] }, + config: { cli: { toolName: 'myapp' } }, + typeRegistry, + }); + return files.find((f) => f.fileName === 'commands/asset.ts')!.content; + }; + + it('never selects a field that takes arguments as `field: true`', () => { + expect(generateAssetCommand(computedFileRegistry)).not.toContain('uploadUrl: true'); + expect(generateAssetCommand()).not.toContain('uploadUrl: true'); + }); + + it('leaves computed fields out of the default select', () => { + const content = generateAssetCommand(computedFileRegistry); + expect(content).toContain('filename: true'); + expect(content).not.toContain('downloadUrl: true'); + expect(content).not.toContain('uploadVersions: true'); + expect(content).not.toContain('searchTsvRank: true'); + }); + + it('derives update fields from the patch type when there is no create input', () => { + const content = generateAssetCommand(computedFileRegistry); + expect(content).toContain('filename: cleanedData.filename'); + expect(content).not.toContain('cleanedData.downloadUrl'); + expect(content).not.toContain('cleanedData.uploadUrl'); + expect(content).not.toContain('cleanedData.uploadVersions'); + expect(content).not.toContain("name: 'uploadUrl'"); + expect(content).not.toContain("name: 'uploadVersions'"); + expect(content).not.toContain("name: 'downloadUrl'"); + }); + + it('keeps computed fields out of docs examples', () => { + const docs = [ + generateOrmReadme([computedFileTable], [], computedFileRegistry), + generateHooksReadme([computedFileTable], [], computedFileRegistry), + ...generateOrmSkills([computedFileTable], [], 'default', computedFileRegistry), + ...generateHooksSkills([computedFileTable], [], 'default', computedFileRegistry), + ].map((f) => f.content); + for (const content of docs) { + expect(content).not.toContain('uploadUrl: true'); + expect(content).not.toContain('uploadVersions: true'); + expect(content).not.toContain('uploadUrl: \''); + } + expect(docs[0]).toMatch(/`uploadUrl` \| String \| No/); + expect(docs[0]).toMatch(/`downloadUrl` \| String \| No/); + }); + + it('references the real tsvector rank field in search examples', () => { + const readme = generateCliReadme( + [computedFileTable], + [], + 'myapp', + computedFileRegistry, + ).content; + // `filename` and `searchTsvRank` exist on the table; `title`, `tsvRank` + // and `searchScore` do not + expect(readme).toContain('--where.search "search query" --select filename,searchTsvRank'); + expect(readme).toContain('--where.unifiedSearch "search query" --select filename,searchTsvRank'); + expect(readme).toContain('--limit 10 --select id,filename'); + expect(readme).not.toMatch(/--select \S*\b(title|tsvRank|searchScore)\b/); + }); +}); + describe('cli docs generator', () => { it('generates CLI README', () => { const readme = generateCliReadme([carTable, driverTable], allCustomOps, 'myapp'); diff --git a/graphql/codegen/src/__tests__/codegen/computed-fields.test.ts b/graphql/codegen/src/__tests__/codegen/computed-fields.test.ts new file mode 100644 index 0000000000..6062b00e20 --- /dev/null +++ b/graphql/codegen/src/__tests__/codegen/computed-fields.test.ts @@ -0,0 +1,104 @@ +/** + * ORM types for computed fields: a field that takes arguments and/or returns + * an object type cannot be selected as `field: true`. + */ +import { generateInputTypesFile } from '../../core/codegen/orm/input-types-generator'; +import type { Table, TypeRef, TypeRegistry } from '../../types/schema'; + +const ref = (kind: TypeRef['kind'], name: string | null, ofType?: TypeRef): TypeRef => ({ + kind, + name, + ofType, +}); + +const assetTable: Table = { + name: 'Asset', + fields: [ + { name: 'id', type: { gqlType: 'UUID', isArray: false } }, + { name: 'filename', type: { gqlType: 'String', isArray: false } }, + { + name: 'uploadUrl', + type: { gqlType: 'String', isArray: false }, + args: [{ name: 'width', type: ref('SCALAR', 'Int'), isRequired: false }], + }, + { name: 'uploadVersions', type: { gqlType: 'AssetVersion', isArray: true } }, + { + name: 'uploadVersion', + type: { gqlType: 'AssetVersion', isArray: false }, + args: [{ name: 'name', type: ref('SCALAR', 'String'), isRequired: true }], + }, + ], + relations: { belongsTo: [], hasOne: [], hasMany: [], manyToMany: [] }, + query: { + all: 'assets', + one: 'asset', + create: null, + update: 'updateAsset', + delete: 'deleteAsset', + }, +}; + +const registry: TypeRegistry = new Map([ + [ + 'AssetPatch', + { + kind: 'INPUT_OBJECT', + name: 'AssetPatch', + inputFields: [{ name: 'filename', type: ref('SCALAR', 'String') }], + }, + ], + [ + 'AssetVersion', + { + kind: 'OBJECT', + name: 'AssetVersion', + fields: [ + { name: 'url', type: ref('NON_NULL', null, ref('SCALAR', 'String')) }, + { name: 'width', type: ref('SCALAR', 'Int') }, + ], + }, + ], +]); + +const normalize = (code: string): string => code.replace(/\s+/g, ' '); + +describe('ORM types for computed fields', () => { + const content = normalize( + generateInputTypesFile(registry, new Set(), [assetTable]).content, + ); + const selectStart = content.indexOf('export type AssetSelect = {'); + const selectType = content.slice( + selectStart, + content.indexOf('export ', selectStart + 1), + ); + + it('types a field with arguments as { args, select? }', () => { + expect(selectType).toContain( + 'uploadUrl?: { args: { width?: number; }; select?: Record; };', + ); + }); + + it('requires a sub-selection for a field returning an object type', () => { + expect(selectType).toContain('uploadVersions?: { select: AssetVersionSelect; };'); + expect(selectType).not.toContain('uploadVersions?: boolean'); + expect(selectType).toContain( + 'uploadVersion?: { args: { name: string; }; select: AssetVersionSelect; };', + ); + }); + + it('emits the object type and its Select type instead of an unknown alias', () => { + expect(content).toContain('export interface AssetVersion {'); + expect(content).toContain('export type AssetVersionSelect = {'); + expect(content).not.toContain('export type AssetVersion = unknown'); + }); + + it('keeps computed fields out of the patch type', () => { + const patch = content.slice( + content.indexOf('export interface AssetPatch {'), + content.indexOf('}', content.indexOf('export interface AssetPatch {')), + ); + expect(patch).toContain('filename?:'); + expect(patch).not.toContain('uploadUrl'); + expect(patch).not.toContain('uploadVersions'); + }); +}); diff --git a/graphql/codegen/src/__tests__/codegen/generated-skills.test.ts b/graphql/codegen/src/__tests__/codegen/generated-skills.test.ts new file mode 100644 index 0000000000..17a4eb6add --- /dev/null +++ b/graphql/codegen/src/__tests__/codegen/generated-skills.test.ts @@ -0,0 +1,107 @@ +import * as fs from 'node:fs'; +import * as os from 'node:os'; +import * as path from 'node:path'; + +import { + GENERATED_SKILL_MARKER, + removeStaleGeneratedSkills, + writeGeneratedSkills, +} from '../../core/output'; + +describe('generated skills', () => { + let skillsDir: string; + + const write = (relativePath: string, content: string): string => { + const filePath = path.join(skillsDir, relativePath); + fs.mkdirSync(path.dirname(filePath), { recursive: true }); + fs.writeFileSync(filePath, content); + return filePath; + }; + const generatedSkill = `---\nname: x\n---\n\n${GENERATED_SKILL_MARKER}\n`; + + beforeEach(() => { + skillsDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegen-skills-test-')); + }); + + afterEach(() => { + fs.rmSync(skillsDir, { recursive: true, force: true }); + }); + + it('leaves a generated skill directory with exactly the files it wrote', async () => { + const staleRef = write('orm-auth/references/request-upload-url.md', 'stale'); + const staleNested = write('orm-auth/old/nested/file.md', 'stale'); + write('orm-auth/SKILL.md', 'old'); + + const result = await writeGeneratedSkills( + [ + { path: 'orm-auth/SKILL.md', content: generatedSkill }, + { path: 'orm-auth/references/user.md', content: '# user\n' }, + ], + skillsDir, + ); + + expect(result.success).toBe(true); + expect(result.skillNames).toEqual(['orm-auth']); + expect(result.filesRemoved.sort()).toEqual([staleNested, staleRef].sort()); + expect(fs.readdirSync(path.join(skillsDir, 'orm-auth')).sort()).toEqual([ + 'SKILL.md', + 'references', + ]); + expect(fs.readdirSync(path.join(skillsDir, 'orm-auth', 'references'))).toEqual([ + 'user.md', + ]); + expect(fs.readFileSync(path.join(skillsDir, 'orm-auth', 'SKILL.md'), 'utf-8')).toBe( + generatedSkill, + ); + }); + + it('does not touch sibling skill directories when writing', async () => { + const handWritten = write('pgpm/references/deploy.md', 'hand-written'); + const otherGenerated = write('orm-admin/references/stale.md', 'other run'); + + await writeGeneratedSkills( + [{ path: 'orm-auth/SKILL.md', content: generatedSkill }], + skillsDir, + ); + + expect(fs.existsSync(handWritten)).toBe(true); + expect(fs.existsSync(otherGenerated)).toBe(true); + }); + + it('removes generated skills of targets that are no longer generated', () => { + write('orm-auth/SKILL.md', generatedSkill); + write('orm-public/SKILL.md', generatedSkill); + write('orm-public/references/user.md', '# user\n'); + + expect(removeStaleGeneratedSkills(skillsDir, ['orm-auth'])).toEqual(['orm-public']); + expect(fs.existsSync(path.join(skillsDir, 'orm-public'))).toBe(false); + expect(fs.existsSync(path.join(skillsDir, 'orm-auth', 'SKILL.md'))).toBe(true); + }); + + it('keeps generated skills of configured targets that were not regenerated', () => { + write('orm-auth/SKILL.md', generatedSkill); + write('orm-cluster/SKILL.md', generatedSkill); + write('orm-public/SKILL.md', generatedSkill); + + expect(removeStaleGeneratedSkills(skillsDir, ['orm-auth'], ['cluster'])).toEqual([ + 'orm-public', + ]); + expect(fs.existsSync(path.join(skillsDir, 'orm-cluster'))).toBe(true); + }); + + it('keeps hand-written skills and generated skills of other families', () => { + // same family prefix, but no generator marker + write('orm-guide/SKILL.md', '---\nname: orm-guide\n---\n\nHand-written.\n'); + // generated, but by a run that produces a different family + write('hooks-public/SKILL.md', generatedSkill); + // unrelated hand-written skill + write('pgpm/SKILL.md', '---\nname: pgpm\n---\n'); + // no SKILL.md at all + write('orm-notes/README.md', 'notes'); + + expect(removeStaleGeneratedSkills(skillsDir, ['orm-auth'])).toEqual([]); + for (const name of ['orm-guide', 'hooks-public', 'pgpm', 'orm-notes']) { + expect(fs.existsSync(path.join(skillsDir, name))).toBe(true); + } + }); +}); diff --git a/graphql/codegen/src/core/codegen/cli/docs-generator.ts b/graphql/codegen/src/core/codegen/cli/docs-generator.ts index bdab552385..524d584622 100644 --- a/graphql/codegen/src/core/codegen/cli/docs-generator.ts +++ b/graphql/codegen/src/core/codegen/cli/docs-generator.ts @@ -174,7 +174,7 @@ export function generateReadme( } const specialGroups = categorizeSpecialFields(table, registry); lines.push(...buildSpecialFieldsMarkdown(specialGroups)); - lines.push(...buildSearchExamplesMarkdown(specialGroups, toolName, kebab)); + lines.push(...buildSearchExamplesMarkdown(specialGroups, toolName, kebab, table)); lines.push(''); } } @@ -506,7 +506,7 @@ export function generateSkills( description: `List ${singularName} records with filtering and ordering`, code: [`${toolName} ${kebab} list --where.${pk.name}.equalTo --orderBy ${pk.name.replace(/([A-Z])/g, '_$1').toUpperCase()}_ASC`], }, - ...buildSearchExamples(skillSpecialGroups, toolName, kebab), + ...buildSearchExamples(skillSpecialGroups, toolName, kebab, table), ...(table.query?.create !== null ? [{ description: `Create a ${singularName}`, @@ -848,7 +848,7 @@ export function generateMultiTargetReadme( } const mtSpecialGroups = categorizeSpecialFields(table, registry); lines.push(...buildSpecialFieldsMarkdown(mtSpecialGroups)); - lines.push(...buildSearchExamplesMarkdown(mtSpecialGroups, toolName, `${tgt.name}:${kebab}`)); + lines.push(...buildSearchExamplesMarkdown(mtSpecialGroups, toolName, `${tgt.name}:${kebab}`, table)); lines.push(''); } @@ -1243,7 +1243,7 @@ export function generateMultiTargetSkills( description: `List ${singularName} records with filtering and ordering`, code: [`${toolName} ${cmd} list --where.${pk.name}.equalTo --orderBy ${pk.name.replace(/([A-Z])/g, '_$1').toUpperCase()}_ASC`], }, - ...buildSearchExamples(mtSkillSpecialGroups, toolName, cmd), + ...buildSearchExamples(mtSkillSpecialGroups, toolName, cmd, table), { description: `Create a ${singularName}`, code: [ diff --git a/graphql/codegen/src/core/codegen/cli/table-command-generator.ts b/graphql/codegen/src/core/codegen/cli/table-command-generator.ts index 73ba2f507a..fff8ba91ec 100644 --- a/graphql/codegen/src/core/codegen/cli/table-command-generator.ts +++ b/graphql/codegen/src/core/codegen/cli/table-command-generator.ts @@ -1090,9 +1090,11 @@ function buildMutationHandler( const allWhereFieldNames = new Set([...pkFieldNames, ...extraKeys.map((ek) => ek.name)]); // Get the set of writable field names from the type registry - // This filters out computed fields (e.g. searchTsvRank, hashUuid) that exist - // on the entity type but not on the create/update input type. - const writableFields = getWritableFieldNames(table, typeRegistry); + // This filters out computed fields (e.g. searchTsvRank, downloadUrl) that exist + // on the entity type but not on this operation's input type (create input for + // create, patch for update). + const writableFields = + operation === 'delete' ? null : getWritableFieldNames(table, typeRegistry, operation); // Get fields that have defaults from introspection (for create operations) const fieldsWithDefaults = getFieldsWithDefaults(table, typeRegistry); @@ -1113,7 +1115,9 @@ function buildMutationHandler( // Always exclude ORM-excluded fields (except where-clause fields handled above) (allWhereFieldNames.has(f.name) || !ORM_EXCLUDED_FIELDS.includes(f.name)) && // If we have type registry info, only include fields that exist in the input type - (writableFields === null || writableFields.has(f.name)), + (writableFields === null || writableFields.has(f.name)) && + // Without it, a field taking arguments is still never a column + !(f.args && f.args.length > 0), ); const questions: t.Expression[] = []; diff --git a/graphql/codegen/src/core/codegen/docs-utils.ts b/graphql/codegen/src/core/codegen/docs-utils.ts index edc2afe747..ca76db2f33 100644 --- a/graphql/codegen/src/core/codegen/docs-utils.ts +++ b/graphql/codegen/src/core/codegen/docs-utils.ts @@ -1,6 +1,11 @@ import type { DocsConfig } from '../../types/config'; import type { Argument, Field, Operation, Table, TypeRef, TypeRegistry } from '../../types/schema'; -import { getPrimaryKeyInfo, getScalarFields, getWritableFieldNames } from './utils'; +import { + getPrimaryKeyInfo, + getScalarFields, + getWritableFieldNames, + isPlainSelectableField, +} from './utils'; export interface GeneratedDocFile { fileName: string; @@ -80,6 +85,14 @@ export function formatTypeRef( return t.name ?? 'unknown'; } +/** + * Fields a docs example can select as `field: true`: everything except + * fields that take arguments or return an object type. + */ +export function getExampleSelectFields(table: Table, typeRegistry?: TypeRegistry): Field[] { + return getScalarFields(table).filter((f) => isPlainSelectableField(f, typeRegistry)); +} + export function getEditableFields(table: Table, typeRegistry?: TypeRegistry): Field[] { const pk = getPrimaryKeyInfo(table)[0]; const writableFields = getWritableFieldNames(table, typeRegistry); @@ -91,7 +104,9 @@ export function getEditableFields(table: Table, typeRegistry?: TypeRegistry): Fi f.name !== 'updatedAt' && // When a TypeRegistry is available, filter out computed/plugin-added // fields (e.g. search scores, trgm similarity) that aren't real columns - (writableFields === null || writableFields.has(f.name)), + (writableFields === null || writableFields.has(f.name)) && + // Without a TypeRegistry, a field taking arguments is still never a column + !(f.args && f.args.length > 0), ); } @@ -157,7 +172,7 @@ function isTsvectorField(f: Field): boolean { function isSearchComputedField(f: Field): boolean { if (f.name === 'searchScore') return true; if (/TrgmSimilarity$/.test(f.name)) return true; - if (/TsvectorRank$/.test(f.name)) return true; + if (/Tsv(ector)?Rank$/.test(f.name)) return true; if (/Bm25Score$/.test(f.name)) return true; return false; } @@ -301,21 +316,48 @@ export function buildSearchExamples( specialGroups: SpecialFieldGroup[], toolName: string, cmd: string, + table?: Table, ): SearchExample[] { const examples: SearchExample[] = []; const scoreFields: string[] = []; + // Examples may only reference fields the table really has + const allFieldNames = new Set( + (table ? table.fields : specialGroups.flatMap((g) => g.fields)).map( + (f) => f.name, + ), + ); + const specialFieldNames = new Set( + specialGroups.flatMap((g) => g.fields.map((f) => f.name)), + ); + const displayField = + ['title', 'name', 'displayName', 'label'].find((n) => allFieldNames.has(n)) ?? + table?.fields.find( + (f) => + f.type.gqlType === 'String' && + !f.type.isArray && + !(f.args && f.args.length > 0) && + !specialFieldNames.has(f.name), + )?.name ?? + (table && !allFieldNames.has('title') ? 'id' : 'title'); + const selectArg = (...extra: string[]): string => + [...new Set([displayField, ...extra.filter((n) => allFieldNames.has(n))])].join(','); for (const group of specialGroups) { for (const field of group.fields) { // tsvector (FullText scalar) — where input uses the column name directly if (field.type.gqlType === 'FullText' && !field.type.isArray) { + // The rank is exposed as `TsvRank` (search → searchTsvRank, + // searchTsv → searchTsvRank); only reference it when the table has it + const rankField = [`${field.name}TsvRank`, `${field.name}Rank`].find( + (name) => allFieldNames.has(name), + ); examples.push({ description: `Full-text search via tsvector (\`${field.name}\`)`, code: [ - `${toolName} ${cmd} list --where.${field.name} "search query" --select title,tsvRank`, + `${toolName} ${cmd} list --where.${field.name} "search query" --select ${selectArg(...(rankField ? [rankField] : []))}`, ], }); - scoreFields.push('tsvRank'); + if (rankField) scoreFields.push(rankField); } // BM25 computed score — bodyBm25Score → bm25Body @@ -325,7 +367,7 @@ export function buildSearchExamples( examples.push({ description: `BM25 keyword search via \`${inputName}\``, code: [ - `${toolName} ${cmd} list --where.${inputName}.query "search query" --select title,${field.name}`, + `${toolName} ${cmd} list --where.${inputName}.query "search query" --select ${selectArg(field.name)}`, ], }); scoreFields.push(field.name); @@ -338,7 +380,7 @@ export function buildSearchExamples( examples.push({ description: `Fuzzy search via trigram similarity (\`${inputName}\`)`, code: [ - `${toolName} ${cmd} list --where.${inputName}.value "approximate query" --where.${inputName}.threshold 0.3 --select title,${field.name}`, + `${toolName} ${cmd} list --where.${inputName}.value "approximate query" --where.${inputName}.threshold 0.3 --select ${selectArg(field.name)}`, ], }); scoreFields.push(field.name); @@ -350,15 +392,15 @@ export function buildSearchExamples( description: `Vector similarity search via \`${field.name}\` (manual vector)`, code: [ `# Pass a pre-computed vector array via dot-notation`, - `${toolName} ${cmd} list --where.${field.name}.vector '[0.1,0.2,0.3]' --where.${field.name}.distance 1.0 --select title,${field.name}VectorDistance`, + `${toolName} ${cmd} list --where.${field.name}.vector '[0.1,0.2,0.3]' --where.${field.name}.distance 1.0 --select ${selectArg(`${field.name}VectorDistance`)}`, ], }); examples.push({ description: `Vector semantic search via \`${field.name}\` with --auto-embed`, code: [ `# --auto-embed converts text to vectors using the configured embedder (e.g. Ollama nomic-embed-text)`, - `EMBEDDER_PROVIDER=ollama ${toolName} ${cmd} search "semantic query" --auto-embed --select title,${field.name}VectorDistance`, - `EMBEDDER_PROVIDER=ollama ${toolName} ${cmd} list --where.${field.name}.vector "semantic query" --auto-embed --select title,${field.name}VectorDistance`, + `EMBEDDER_PROVIDER=ollama ${toolName} ${cmd} search "semantic query" --auto-embed --select ${selectArg(`${field.name}VectorDistance`)}`, + `EMBEDDER_PROVIDER=ollama ${toolName} ${cmd} list --where.${field.name}.vector "semantic query" --auto-embed --select ${selectArg(`${field.name}VectorDistance`)}`, ], }); examples.push({ @@ -385,9 +427,7 @@ export function buildSearchExamples( ), ); if (hasTextSearch) { - const fieldsArg = scoreFields.length > 0 - ? `title,${[...new Set(scoreFields)].join(',')}` - : 'title'; + const fieldsArg = selectArg(...scoreFields); examples.push({ description: 'Composite search (unifiedSearch dispatches to all text adapters)', code: [ @@ -398,11 +438,14 @@ export function buildSearchExamples( // Combined search + pagination + ordering example if (examples.length > 0) { + const paginationSelect = [ + ...new Set(['id', ...selectArg('searchScore').split(',')]), + ].join(','); examples.push({ description: 'Search with pagination and field projection', code: [ - `${toolName} ${cmd} list --where.unifiedSearch "query" --limit 10 --select id,title,searchScore`, - `${toolName} ${cmd} search "query" --limit 10 --select id,title,searchScore`, + `${toolName} ${cmd} list --where.unifiedSearch "query" --limit 10 --select ${paginationSelect}`, + `${toolName} ${cmd} search "query" --limit 10 --select ${paginationSelect}`, ], }); } @@ -418,8 +461,9 @@ export function buildSearchExamplesMarkdown( specialGroups: SpecialFieldGroup[], toolName: string, cmd: string, + table?: Table, ): string[] { - const examples = buildSearchExamples(specialGroups, toolName, cmd); + const examples = buildSearchExamples(specialGroups, toolName, cmd, table); if (examples.length === 0) return []; const lines: string[] = []; lines.push('**Search Examples:**'); diff --git a/graphql/codegen/src/core/codegen/hooks-docs-generator.ts b/graphql/codegen/src/core/codegen/hooks-docs-generator.ts index c45ddd506d..451148ccba 100644 --- a/graphql/codegen/src/core/codegen/hooks-docs-generator.ts +++ b/graphql/codegen/src/core/codegen/hooks-docs-generator.ts @@ -8,6 +8,8 @@ import { buildSkillReference, fieldPlaceholder, formatArgType, + getEditableFields, + getExampleSelectFields, getReadmeHeader, pkPlaceholder, } from './docs-utils'; @@ -22,7 +24,6 @@ import { getDeleteMutationHookName, getListQueryHookName, getPrimaryKeyInfo, - getScalarFields, getSingleQueryHookName, getTableNames, getUpdateMutationHookName, @@ -129,7 +130,7 @@ export function generateHooksReadme( for (const table of tables) { const { singularName, pluralName } = getTableNames(table); const pk = getPrimaryKeyInfo(table)[0]; - const scalarFields = getScalarFields(table); + const selectFields = getExampleSelectFields(table, registry); lines.push(`### ${table.name}`); lines.push(''); @@ -140,7 +141,7 @@ export function generateHooksReadme( `const { data, isLoading } = ${getListQueryHookName(table)}({`, ); lines.push( - ` selection: { fields: { ${scalarFields.map((f) => `${f.name}: true`).join(', ')} } },`, + ` selection: { fields: { ${selectFields.map((f) => `${f.name}: true`).join(', ')} } },`, ); lines.push('});'); lines.push(''); @@ -152,7 +153,7 @@ export function generateHooksReadme( ); lines.push(` ${pk.name}: ${pkPlaceholder(pk)},`); lines.push( - ` selection: { fields: { ${scalarFields.map((f) => `${f.name}: true`).join(', ')} } },`, + ` selection: { fields: { ${selectFields.map((f) => `${f.name}: true`).join(', ')} } },`, ); lines.push('});'); lines.push(''); @@ -168,7 +169,7 @@ export function generateHooksReadme( ); lines.push('});'); lines.push( - `create({ ${scalarFields.filter((f) => f.name !== pk.name && f.name !== 'nodeId' && f.name !== 'createdAt' && f.name !== 'updatedAt').map((f) => `${f.name}: ${fieldPlaceholder(f)}`).join(', ')} });`, + `create({ ${getEditableFields(table, registry).map((f) => `${f.name}: ${fieldPlaceholder(f)}`).join(', ')} });`, ); } if (getBulkInsertMutationName(table)) { @@ -182,7 +183,7 @@ export function generateHooksReadme( ); lines.push('});'); lines.push( - `bulkCreate({ data: [{ ${scalarFields.filter((f) => f.name !== pk.name && f.name !== 'nodeId' && f.name !== 'createdAt' && f.name !== 'updatedAt').map((f) => `${f.name}: ${fieldPlaceholder(f)}`).join(', ')} }] });`, + `bulkCreate({ data: [{ ${getEditableFields(table, registry).map((f) => `${f.name}: ${fieldPlaceholder(f)}`).join(', ')} }] });`, ); } lines.push('```'); @@ -294,8 +295,7 @@ export function generateHooksSkills( for (const table of tables) { const { singularName, pluralName } = getTableNames(table); const pk = getPrimaryKeyInfo(table)[0]; - const scalarFields = getScalarFields(table); - const selectFields = scalarFields + const selectFields = getExampleSelectFields(table, registry) .map((f) => `${f.name}: true`) .join(', '); @@ -343,7 +343,7 @@ export function generateHooksSkills( `const { mutate } = ${getCreateMutationHookName(table)}({`, ` selection: { fields: { ${pk.name}: true } },`, '});', - `mutate({ ${scalarFields.filter((f) => f.name !== pk.name && f.name !== 'nodeId' && f.name !== 'createdAt' && f.name !== 'updatedAt').map((f) => `${f.name}: ${fieldPlaceholder(f)}`).join(', ')} });`, + `mutate({ ${getEditableFields(table, registry).map((f) => `${f.name}: ${fieldPlaceholder(f)}`).join(', ')} });`, ], }] : []), diff --git a/graphql/codegen/src/core/codegen/orm/docs-generator.ts b/graphql/codegen/src/core/codegen/orm/docs-generator.ts index 420dd3778e..6ea2220e22 100644 --- a/graphql/codegen/src/core/codegen/orm/docs-generator.ts +++ b/graphql/codegen/src/core/codegen/orm/docs-generator.ts @@ -11,6 +11,7 @@ import { fieldPlaceholder, formatArgType, getEditableFields, + getExampleSelectFields, getReadmeHeader, pkPlaceholder, } from '../docs-utils'; @@ -68,7 +69,8 @@ export function generateOrmReadme( const { singularName } = getTableNames(table); const pk = getPrimaryKeyInfo(table)[0]; const scalarFields = getScalarFields(table); - const editableFields = getEditableFields(table); + const editableFields = getEditableFields(table, registry); + const selectFields = getExampleSelectFields(table, registry); lines.push(`### \`db.${singularName}\``); lines.push(''); @@ -91,12 +93,12 @@ export function generateOrmReadme( lines.push('```typescript'); lines.push(`// List all ${singularName} records`); lines.push( - `const items = await db.${singularName}.findMany({ select: { ${scalarFields.map((f) => `${f.name}: true`).join(', ')} } }).execute();`, + `const items = await db.${singularName}.findMany({ select: { ${selectFields.map((f) => `${f.name}: true`).join(', ')} } }).execute();`, ); lines.push(''); lines.push(`// Get one by ${pk.name}`); lines.push( - `const item = await db.${singularName}.findOne({ ${pk.name}: ${pkPlaceholder(pk)}, select: { ${scalarFields.map((f) => `${f.name}: true`).join(', ')} } }).execute();`, + `const item = await db.${singularName}.findOne({ ${pk.name}: ${pkPlaceholder(pk)}, select: { ${selectFields.map((f) => `${f.name}: true`).join(', ')} } }).execute();`, ); lines.push(''); if (table.query?.create !== null) { @@ -291,7 +293,7 @@ export function generateOrmSkills( for (const table of tables) { const { singularName } = getTableNames(table); const pk = getPrimaryKeyInfo(table)[0]; - const editableFields = getEditableFields(table); + const editableFields = getEditableFields(table, registry); const modelName = lcFirst(singularName); const refName = toKebabCase(singularName); diff --git a/graphql/codegen/src/core/codegen/orm/input-types-generator.ts b/graphql/codegen/src/core/codegen/orm/input-types-generator.ts index 52a5ac3f6a..78a469bf0e 100644 --- a/graphql/codegen/src/core/codegen/orm/input-types-generator.ts +++ b/graphql/codegen/src/core/codegen/orm/input-types-generator.ts @@ -571,6 +571,7 @@ function collectCustomScalarTypes( if (excludedTypeNames.has(fieldType)) continue; if (tableTypeNames.has(fieldType)) continue; if (isLikelyEnumType(fieldType, typeRegistry)) continue; + if (typeRegistry.get(fieldType)?.kind === 'OBJECT') continue; customScalarTypes.add(fieldType); } } @@ -578,6 +579,40 @@ function collectCustomScalarTypes( return Array.from(customScalarTypes).sort(); } +/** + * Object types returned by non-relation entity fields (e.g. a computed + * `avatarVersions: [FileVersion!]`). They need an interface and a Select type, + * and the field needs a sub-selection instead of `true`. + */ +function collectEntityObjectFieldTypes( + tables: Table[], + typeRegistry: TypeRegistry, +): Set { + const objectTypes = new Set(); + const tableTypeNames = new Set(tables.map((table) => table.name)); + + for (const table of tables) { + for (const field of table.fields) { + if (isRelationField(field.name, table)) continue; + const fieldType = getEntityObjectFieldType(field, typeRegistry); + if (fieldType && !tableTypeNames.has(fieldType)) objectTypes.add(fieldType); + } + } + + return objectTypes; +} + +function getEntityObjectFieldType( + field: Table['fields'][number], + typeRegistry?: TypeRegistry, +): string | null { + const fieldType = + typeof field.type === 'string' ? field.type : field.type.gqlType; + // Types mapped to a TS scalar (e.g. Interval -> string) stay scalar selects + if (SCALAR_NAMES.has(fieldType)) return null; + return typeRegistry?.get(fieldType)?.kind === 'OBJECT' ? fieldType : null; +} + function generateCustomScalarTypes(customScalarTypes: string[]): t.Statement[] { if (customScalarTypes.length === 0) return []; @@ -840,12 +875,18 @@ function generateEntityWithRelations(tables: Table[]): t.Statement[] { function buildSelectTypeLiteral( table: Table, tableByName: Map, + typeRegistry?: TypeRegistry, ): t.TSTypeLiteral { const members: t.TSTypeElement[] = []; // Add scalar fields (and fields with arguments) for (const field of table.fields) { if (!isRelationField(field.name, table)) { + const objectType = tableByName.has( + typeof field.type === 'string' ? field.type : field.type.gqlType, + ) + ? null + : getEntityObjectFieldType(field, typeRegistry); if (field.args && field.args.length > 0) { // Field with arguments (e.g. requestUploadUrl on bucket types) const argMembers: t.TSTypeElement[] = field.args.map((arg) => { @@ -874,16 +915,19 @@ function buildSelectTypeLiteral( const selectProp = t.tsPropertySignature( t.identifier('select'), t.tsTypeAnnotation( - t.tsTypeReference( - t.identifier('Record'), - t.tsTypeParameterInstantiation([ - t.tsStringKeyword(), - t.tsBooleanKeyword(), - ]), - ), + objectType + ? t.tsTypeReference(t.identifier(`${objectType}Select`)) + : t.tsTypeReference( + t.identifier('Record'), + t.tsTypeParameterInstantiation([ + t.tsStringKeyword(), + t.tsBooleanKeyword(), + ]), + ), ), ); - selectProp.optional = true; + // An object type cannot be selected without a sub-selection + selectProp.optional = !objectType; return selectProp; })(), ]), @@ -891,6 +935,20 @@ function buildSelectTypeLiteral( ); prop.optional = true; members.push(prop); + } else if (objectType) { + const selectProp = t.tsPropertySignature( + t.identifier('select'), + t.tsTypeAnnotation( + t.tsTypeReference(t.identifier(`${objectType}Select`)), + ), + ); + selectProp.optional = false; + const prop = t.tsPropertySignature( + t.identifier(field.name), + t.tsTypeAnnotation(t.tsTypeLiteral([selectProp])), + ); + prop.optional = true; + members.push(prop); } else { const prop = t.tsPropertySignature( t.identifier(field.name), @@ -1092,6 +1150,7 @@ function buildSelectTypeLiteral( function generateEntitySelectTypes( tables: Table[], tableByName: Map, + typeRegistry?: TypeRegistry, ): t.Statement[] { const statements: t.Statement[] = []; @@ -1100,7 +1159,7 @@ function generateEntitySelectTypes( const typeAlias = t.tsTypeAliasDeclaration( t.identifier(`${typeName}Select`), null, - buildSelectTypeLiteral(table, tableByName), + buildSelectTypeLiteral(table, tableByName, typeRegistry), ); statements.push(t.exportNamedDeclaration(typeAlias)); } @@ -2083,6 +2142,12 @@ export function generateInputTypesFile( tablesList, enumTypes, ); + // Object types returned by entity fields get an interface + Select type + // alongside the payload types (section 8) + const mergedUsedPayloadTypes = new Set([ + ...(usedPayloadTypes ?? []), + ...collectEntityObjectFieldTypes(tablesList, typeRegistry), + ]); // 1. Scalar filter types statements.push(...generateScalarFilterTypes()); @@ -2099,7 +2164,7 @@ export function generateInputTypesFile( statements.push(...generateRelationHelperTypes()); statements.push(...generateEntityRelationTypes(tablesList, tableByName)); statements.push(...generateEntityWithRelations(tablesList)); - statements.push(...generateEntitySelectTypes(tablesList, tableByName)); + statements.push(...generateEntitySelectTypes(tablesList, tableByName, typeRegistry)); // 4. Table filter types // Pass typeRegistry to use schema's filter type as source of truth, @@ -2153,7 +2218,7 @@ export function generateInputTypesFile( ); // 8. Payload/return types for custom operations - if (usedPayloadTypes && usedPayloadTypes.size > 0) { + if (mergedUsedPayloadTypes.size > 0) { const alreadyGeneratedTypes = new Set(); if (tables) { for (const table of tables) { @@ -2164,7 +2229,7 @@ export function generateInputTypesFile( statements.push( ...generatePayloadTypes( typeRegistry, - usedPayloadTypes, + mergedUsedPayloadTypes, alreadyGeneratedTypes, comments, ), diff --git a/graphql/codegen/src/core/codegen/templates/select-types.ts b/graphql/codegen/src/core/codegen/templates/select-types.ts index 476dd51918..1828d4d47c 100644 --- a/graphql/codegen/src/core/codegen/templates/select-types.ts +++ b/graphql/codegen/src/core/codegen/templates/select-types.ts @@ -178,9 +178,13 @@ export type InferSelectResult = TSelect extends undefined ? K extends keyof TEntity ? NonNullable extends ConnectionResult ? ConnectionResult> - : - | InferSelectResult, NestedSelect> - | (null extends TEntity[K] ? null : never) + : NonNullable extends readonly (infer Item)[] + ? + | InferSelectResult, NestedSelect>[] + | (null extends TEntity[K] ? null : never) + : + | InferSelectResult, NestedSelect> + | (null extends TEntity[K] ? null : never) : never : K extends keyof TEntity ? TEntity[K] diff --git a/graphql/codegen/src/core/codegen/utils.ts b/graphql/codegen/src/core/codegen/utils.ts index 2fe6fc3edb..28a1877e27 100644 --- a/graphql/codegen/src/core/codegen/utils.ts +++ b/graphql/codegen/src/core/codegen/utils.ts @@ -16,7 +16,7 @@ import type { Table, TypeRegistry, } from '../../types/schema'; -import { scalarToFilterType, scalarToTsType } from './scalars'; +import { SCALAR_NAMES, scalarToFilterType, scalarToTsType } from './scalars'; // Re-export string manipulation helpers from inflekt (single source of truth) export { lcFirst, toCamelCase, toConstantCase, toPascalCase, ucFirst }; @@ -466,28 +466,79 @@ export function resolveInnerInputType( } /** - * Get the set of field names that actually exist in the create input type. - * Fields not in this set (e.g. computed fields like searchTsvRank, hashUuid) - * are plugin-added computed fields that don't correspond to real database columns. - * Returns null when no typeRegistry is provided (caller should treat as "no filtering"). + * Field names of the create input type (`CreateXInput.x`), or null when the + * schema has no such type (no create mutation) or no typeRegistry is given. */ -export function getWritableFieldNames( +export function getCreateInputFieldNames( table: Table, typeRegistry?: TypeRegistry, ): Set | null { if (!typeRegistry) return null; - - const createInputTypeName = getCreateInputTypeName(table); - const resolved = resolveInnerInputType(createInputTypeName, typeRegistry); + const resolved = resolveInnerInputType(getCreateInputTypeName(table), typeRegistry); return resolved?.fields ?? null; } +/** + * Field names of the patch input type (`XPatch`), or null when the schema has + * no such type (no update mutation) or no typeRegistry is given. + */ +export function getPatchFieldNames( + table: Table, + typeRegistry?: TypeRegistry, +): Set | null { + if (!typeRegistry) return null; + const patchType = typeRegistry.get(getPatchTypeName(table)); + if (patchType?.kind !== 'INPUT_OBJECT' || !patchType.inputFields) return null; + return new Set(patchType.inputFields.map((f) => f.name)); +} + +/** + * Get the set of field names the schema accepts as input for a table. + * - `'create'`: fields of the create input type + * - `'update'`: fields of the patch type + * - omitted: fields of either (the table's columns, as far as its inputs show) + * Fields outside this set (e.g. searchTsvRank, downloadUrl) are computed fields + * that exist on the entity type but cannot be written. + * Returns null when the schema has no matching input type or no typeRegistry + * is provided (caller should treat as "no filtering"). + */ +export function getWritableFieldNames( + table: Table, + typeRegistry?: TypeRegistry, + operation?: 'create' | 'update', +): Set | null { + if (operation === 'create') return getCreateInputFieldNames(table, typeRegistry); + if (operation === 'update') return getPatchFieldNames(table, typeRegistry); + + const createFields = getCreateInputFieldNames(table, typeRegistry); + const patchFields = getPatchFieldNames(table, typeRegistry); + if (!createFields && !patchFields) return null; + return new Set([...(createFields ?? []), ...(patchFields ?? [])]); +} + +/** + * Whether a field can be selected as a bare `field: true`. + * A field that takes arguments needs `{ args }`, and a field returning an + * object type needs a sub-selection, so neither qualifies. + */ +export function isPlainSelectableField( + field: Field, + typeRegistry?: TypeRegistry, +): boolean { + if (field.args && field.args.length > 0) return false; + const gqlType = field.type.gqlType.replace(/[![\]]/g, ''); + // Types mapped to a TS scalar (e.g. Interval -> string) are selected as scalars + if (SCALAR_NAMES.has(gqlType)) return true; + return typeRegistry?.get(gqlType)?.kind !== 'OBJECT'; +} + /** * Get scalar fields that represent actual database columns (not computed/plugin-added). - * When a TypeRegistry is provided, filters out fields that don't exist in the - * create input type — these are computed fields added by plugins (e.g. search scores, - * hash UUIDs) that aren't real columns and shouldn't appear in default selections. - * Without a TypeRegistry, falls back to all scalar fields. + * When a TypeRegistry is provided, filters out fields that are in neither the + * create input nor the patch type — these are computed fields added by plugins + * (e.g. search scores, file URLs) that aren't real columns and shouldn't appear + * in default selections. Fields that cannot be selected as `field: true` are + * always left out. */ export function getSelectableScalarFields( table: Table, @@ -495,7 +546,9 @@ export function getSelectableScalarFields( ): Field[] { const writableFields = getWritableFieldNames(table, typeRegistry); return getScalarFields(table).filter( - (f) => writableFields === null || writableFields.has(f.name), + (f) => + isPlainSelectableField(f, typeRegistry) && + (writableFields === null || writableFields.has(f.name)), ); } diff --git a/graphql/codegen/src/core/generate.ts b/graphql/codegen/src/core/generate.ts index c5386bbc91..8db9b8b855 100644 --- a/graphql/codegen/src/core/generate.ts +++ b/graphql/codegen/src/core/generate.ts @@ -48,7 +48,7 @@ import { generateTargetReadme, } from './codegen/target-docs-generator'; import { createSchemaSource, validateSourceOptions } from './introspect'; -import { writeGeneratedFiles } from './output'; +import { removeStaleGeneratedSkills, writeGeneratedFiles, writeGeneratedSkills } from './output'; import { runCodegenPipeline, validateTablesFound } from './pipeline'; import { findWorkspaceRoot } from './workspace'; @@ -65,6 +65,8 @@ export interface GenerateResult { output?: string; tables?: string[]; filesWritten?: string[]; + /** Generated skill directories written by this run (absent when none were) */ + skills?: { dir: string; names: string[] }; errors?: string[]; pipelineData?: { tables: Table[]; @@ -322,6 +324,7 @@ export async function generate( ]; const targetName = internalOptions?.targetName ?? 'default'; const skillsToWrite: Array<{ path: string; content: string }> = []; + let skillsWritten: GenerateResult['skills']; if (runOrm) { if (docsConfig.readme) { @@ -405,9 +408,7 @@ export async function generate( if (skillsToWrite.length > 0) { const skillsOutputDir = resolveSkillsOutputDir(config, outputRoot); - const skillsWriteResult = await writeGeneratedFiles(skillsToWrite, skillsOutputDir, [], { - pruneStaleFiles: false, - }); + const skillsWriteResult = await writeGeneratedSkills(skillsToWrite, skillsOutputDir); if (!skillsWriteResult.success) { return { success: false, @@ -417,6 +418,7 @@ export async function generate( }; } allFilesWritten.push(...(skillsWriteResult.filesWritten ?? [])); + skillsWritten = { dir: skillsOutputDir, names: skillsWriteResult.skillNames }; } } @@ -437,6 +439,7 @@ export async function generate( output: outputRoot, tables: tables.map((t) => t.name), filesWritten: allFilesWritten, + skills: skillsWritten, pipelineData: { tables, customOperations: { @@ -509,7 +512,10 @@ export interface GenerateMultiOptions { dryRun?: boolean; schema?: SchemaConfig; unifiedCli?: CliConfig | boolean; - /** Remove subdirectories in the output root that don't match any current target name. */ + /** + * Remove subdirectories in the output root that don't match any current target name, + * and generated skill directories of targets that no longer exist. + */ cleanStaleTargets?: boolean; } @@ -683,6 +689,13 @@ export async function generateMulti( const cliTargets: MultiTargetCliTarget[] = []; + const skillNamesByDir = new Map>(); + const recordSkills = (dir: string, skillNames: string[]) => { + const recorded = skillNamesByDir.get(dir) ?? new Set(); + for (const skillName of skillNames) recorded.add(skillName); + skillNamesByDir.set(dir, recorded); + }; + // Remove stale target directories before generating if (cleanStaleTargets && names.length > 0 && !dryRun) { const firstOutput = getConfigOptions(configs[names[0]]).output; @@ -711,6 +724,7 @@ export async function generateMulti( useUnifiedCli ? { skipCli: true, targetName: name } : { targetName: name }, ); results.push({ name, result }); + if (result.skills) recordSkills(result.skills.dir, result.skills.names); if (!result.success) { hasError = true; } else { @@ -815,7 +829,8 @@ export async function generateMulti( firstTargetResolved, firstTargetResolved.output, ); - await writeGeneratedFiles(cliSkillsToWrite, skillsOutputDir, [], { pruneStaleFiles: false }); + const cliSkillsResult = await writeGeneratedSkills(cliSkillsToWrite, skillsOutputDir); + recordSkills(skillsOutputDir, cliSkillsResult.skillNames); } } @@ -855,6 +870,24 @@ export async function generateMulti( } } + // Remove generated skills of targets that no longer exist. A configured + // target that failed (e.g. a schema without tables) did not rewrite its + // skills, so those are kept rather than treated as stale. + if (cleanStaleTargets && !dryRun) { + const failedNames = results.filter((r) => !r.result.success).map((r) => r.name); + for (const [skillsDir, skillNames] of skillNamesByDir) { + const removedSkills = removeStaleGeneratedSkills( + skillsDir, + Array.from(skillNames), + failedNames, + ); + if (verbose) { + for (const skillName of removedSkills) { + console.log(`Removed stale generated skill: ${skillName}`); + } + } + } + } } finally { for (const shared of sharedSources.values()) { const keepDb = Object.values(configs).some((c) => c.db?.keepDb); diff --git a/graphql/codegen/src/core/output/index.ts b/graphql/codegen/src/core/output/index.ts index e4cbae29b0..8fa37750bc 100644 --- a/graphql/codegen/src/core/output/index.ts +++ b/graphql/codegen/src/core/output/index.ts @@ -2,6 +2,12 @@ * Output module exports */ +export { + GENERATED_SKILL_MARKER, + removeStaleGeneratedSkills, + writeGeneratedSkills, + type WriteSkillsResult, +} from './skills'; export { type GeneratedFile, writeGeneratedFiles, diff --git a/graphql/codegen/src/core/output/skills.ts b/graphql/codegen/src/core/output/skills.ts new file mode 100644 index 0000000000..f359ccfdfb --- /dev/null +++ b/graphql/codegen/src/core/output/skills.ts @@ -0,0 +1,143 @@ +/** + * Writing and pruning of generated agent skills. + * + * A generated skill is a directory `//` holding a + * `SKILL.md` and `references/*.md`. The skills directory is shared with + * hand-written skills, so pruning is scoped to what the generator owns: + * - a skill directory written in this run is left with exactly the files + * written in this run + * - a skill directory that was not written is only removed when its SKILL.md + * carries the generator marker and it belongs to a family (`orm-`, `cli-`, + * `hooks-`) that this run generated + */ +import * as fs from 'node:fs'; +import * as path from 'node:path'; + +import { type GeneratedFile, writeGeneratedFiles, type WriteResult } from './writer'; + +/** Marker the docs generators put in every generated SKILL.md. */ +export const GENERATED_SKILL_MARKER = + ''; + +export interface WriteSkillsResult extends WriteResult { + /** Names of the skill directories written, relative to the skills dir */ + skillNames: string[]; + /** Absolute paths of stale files removed from those directories */ + filesRemoved: string[]; +} + +function getSkillName(filePath: string): string | null { + const segments = filePath.split(/[\\/]/).filter(Boolean); + return segments.length > 1 ? segments[0] : null; +} + +function findFiles(dir: string): string[] { + const files: string[] = []; + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + const fullPath = path.join(dir, entry.name); + if (entry.isDirectory()) { + files.push(...findFiles(fullPath)); + } else { + files.push(fullPath); + } + } + return files; +} + +function removeEmptyDirs(dir: string): void { + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + if (!entry.isDirectory()) continue; + const fullPath = path.join(dir, entry.name); + removeEmptyDirs(fullPath); + if (fs.readdirSync(fullPath).length === 0) fs.rmdirSync(fullPath); + } +} + +/** + * Write generated skill files and remove every other file from the skill + * directories they belong to. Sibling skill directories are not touched. + */ +export async function writeGeneratedSkills( + files: GeneratedFile[], + skillsDir: string, +): Promise { + const writeResult = await writeGeneratedFiles(files, skillsDir, [], { + pruneStaleFiles: false, + }); + const skillNames = Array.from( + new Set(files.map((f) => getSkillName(f.path)).filter((n): n is string => !!n)), + ).sort(); + const filesRemoved: string[] = []; + if (!writeResult.success) { + return { ...writeResult, skillNames, filesRemoved }; + } + + const expected = new Set(files.map((f) => path.resolve(skillsDir, f.path))); + const errors: string[] = []; + for (const skillName of skillNames) { + const skillDir = path.resolve(skillsDir, skillName); + try { + for (const existing of findFiles(skillDir)) { + if (expected.has(path.resolve(existing))) continue; + fs.rmSync(existing, { force: true }); + filesRemoved.push(existing); + } + removeEmptyDirs(skillDir); + } catch (err) { + const message = err instanceof Error ? err.message : 'Unknown error'; + errors.push(`Failed to prune stale skill files in ${skillDir}: ${message}`); + } + } + + return { + ...writeResult, + success: errors.length === 0, + errors: errors.length > 0 ? errors : undefined, + skillNames, + filesRemoved, + }; +} + +function getSkillFamily(skillName: string): string | null { + const dash = skillName.indexOf('-'); + return dash > 0 ? skillName.slice(0, dash) : null; +} + +/** + * Remove generated skill directories that the current run no longer produces + * (e.g. the skills of an API target that was dropped). + * Only directories marked as generated, in a family the run generated, are + * eligible; `keepTargetNames` protects the skills of targets that are still + * configured but were not regenerated. Returns the names of the directories + * removed. + */ +export function removeStaleGeneratedSkills( + skillsDir: string, + currentSkillNames: string[], + keepTargetNames: string[] = [], +): string[] { + const removed: string[] = []; + if (!fs.existsSync(skillsDir)) return removed; + + const current = new Set(currentSkillNames); + const families = new Set( + currentSkillNames.map(getSkillFamily).filter((f): f is string => !!f), + ); + for (const family of families) { + for (const targetName of keepTargetNames) current.add(`${family}-${targetName}`); + } + + for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) { + if (!entry.isDirectory() || current.has(entry.name)) continue; + const family = getSkillFamily(entry.name); + if (!family || !families.has(family)) continue; + + const skillFile = path.join(skillsDir, entry.name, 'SKILL.md'); + if (!fs.existsSync(skillFile)) continue; + if (!fs.readFileSync(skillFile, 'utf-8').includes(GENERATED_SKILL_MARKER)) continue; + + fs.rmSync(path.join(skillsDir, entry.name), { recursive: true, force: true }); + removed.push(entry.name); + } + return removed.sort(); +} From 25e6b41b336448ee70a9b9b9f8d597cf18954815 Mon Sep 17 00:00:00 2001 From: Dan Lynch Date: Tue, 17 Nov 2026 04:12:17 +0000 Subject: [PATCH 2/3] fix(codegen): keep generated skills of every configured target --- graphql/codegen/src/core/generate.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/graphql/codegen/src/core/generate.ts b/graphql/codegen/src/core/generate.ts index 8db9b8b855..c605e49bba 100644 --- a/graphql/codegen/src/core/generate.ts +++ b/graphql/codegen/src/core/generate.ts @@ -871,15 +871,15 @@ export async function generateMulti( } // Remove generated skills of targets that no longer exist. A configured - // target that failed (e.g. a schema without tables) did not rewrite its - // skills, so those are kept rather than treated as stale. + // target that did not rewrite its skills (it failed, e.g. a schema without + // tables, or has skills disabled) keeps them: only a target that is no + // longer configured is stale. if (cleanStaleTargets && !dryRun) { - const failedNames = results.filter((r) => !r.result.success).map((r) => r.name); for (const [skillsDir, skillNames] of skillNamesByDir) { const removedSkills = removeStaleGeneratedSkills( skillsDir, Array.from(skillNames), - failedNames, + names, ); if (verbose) { for (const skillName of removedSkills) { From dda7995fe8f09202b0373a0b5262a227e1eb3446 Mon Sep 17 00:00:00 2001 From: Dan Lynch Date: Tue, 17 Nov 2026 04:12:17 +0000 Subject: [PATCH 3/3] fix(codegen): build nested sub-selections for fields with arguments --- .../__tests__/codegen/query-builder.test.ts | 47 +++++++++++++++++++ .../core/codegen/templates/query-builder.ts | 4 +- 2 files changed, 48 insertions(+), 3 deletions(-) diff --git a/graphql/codegen/src/__tests__/codegen/query-builder.test.ts b/graphql/codegen/src/__tests__/codegen/query-builder.test.ts index 664bbde397..5460920166 100644 --- a/graphql/codegen/src/__tests__/codegen/query-builder.test.ts +++ b/graphql/codegen/src/__tests__/codegen/query-builder.test.ts @@ -59,6 +59,11 @@ function addVariable( variables[spec.varName] = spec.value; } +function buildValueAst(value: unknown): import('graphql').ValueNode { + if (typeof value === 'number') return t.intValue({ value: value.toString() }); + return t.stringValue({ value: String(value) }); +} + function buildSelections( select: Record | undefined, connectionFieldsMap?: Record>, @@ -79,11 +84,31 @@ function buildSelections( if (typeof value === 'object' && value !== null) { const nested = value as { select?: Record; + args?: Record; first?: number; filter?: Record; orderBy?: string[]; connection?: boolean; }; + if (nested.args && typeof nested.args === 'object') { + const fieldArgs = Object.entries(nested.args).map( + ([argName, argValue]) => + t.argument({ name: argName, value: buildValueAst(argValue) }), + ); + const subSelections = nested.select + ? buildSelections(nested.select, connectionFieldsMap) + : []; + fields.push( + t.field({ + name: key, + args: fieldArgs.length ? fieldArgs : undefined, + selectionSet: subSelections.length + ? t.selectionSet({ selections: subSelections }) + : undefined, + }), + ); + continue; + } if (!nested.select || typeof nested.select !== 'object') { throw new Error( `Invalid selection for field "${key}": nested selections must include a "select" object.`, @@ -525,6 +550,28 @@ describe('query-builder', () => { ?.selections as FieldNode[]; expect(authorSelections[0].name.value).toBe('id'); }); + + it('keeps sub-selections of an object returned by a field with arguments', () => { + const result = buildSelections({ + thumbnail: { + args: { width: 200 }, + select: { url: true, source: { select: { key: true } } }, + }, + }); + + const document = t.document({ + definitions: [ + t.operationDefinition({ + operation: OP_QUERY, + name: 'Q', + selectionSet: t.selectionSet({ selections: result }), + }), + ], + }); + expect(print(document).replace(/\s+/g, ' ')).toContain( + 'thumbnail(width: 200) { url source { key } }', + ); + }); }); describe('buildFindManyDocument', () => { diff --git a/graphql/codegen/src/core/codegen/templates/query-builder.ts b/graphql/codegen/src/core/codegen/templates/query-builder.ts index 536ab19b0c..775f101622 100644 --- a/graphql/codegen/src/core/codegen/templates/query-builder.ts +++ b/graphql/codegen/src/core/codegen/templates/query-builder.ts @@ -153,9 +153,7 @@ export function buildSelections( ); const nestedSelect = nested.select; if (nestedSelect && typeof nestedSelect === 'object') { - const subSelections = Object.entries(nestedSelect) - .filter(([, v]) => v) - .map(([name]) => t.field({ name })); + const subSelections = buildSelections(nestedSelect, connectionFieldsMap); fields.push( t.field({ name: key,