@dav3/gql-of-power 1.3.0 → 1.4.0

package/.fallowrc.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "./node_modules/fallow/schema.json",
+	"entry": [
+		"src/index.{ts,tsx,js,jsx}",
+		"scripts/update-version.ts",
+		"tests/run-sample-tests.ts",
+		"tests/regression/generate-sql-snapshots.ts"
+	],
+	"ignorePatterns": ["dist/**", "coverage/**", "tests/fixtures/**", "examples/**"],
+	"ignoreDependencies": [],
+	"ignoreExports": [
+		{
+			"file": "src/types/gql-types.ts",
+			"exports": ["*"],
+			"reason": "Generated filter/pagination input type shapes consumed via type-graphql decorators, not direct imports."
+		}
+	],
+	"audit": {
+		"deadCodeBaseline": "fallow-baselines/dead-code.json",
+		"healthBaseline": "fallow-baselines/health.json",
+		"dupesBaseline": "fallow-baselines/dupes.json"
+	}
+}

package/.prettierignore

@@ -0,0 +1,13 @@
+# Build output
+dist/
+coverage/
+
+# Lockfiles (binary / auto-generated)
+bun.lockb
+pnpm-lock.yaml
+package-lock.json
+yarn.lock
+
+# fallow caches (auto-managed) + machine-generated baselines
+.fallow/
+fallow-baselines/

package/README.md

@@ -568,6 +568,27 @@ No `limit` or `offset` parameters are accepted — `LIMIT 1` is always applied.
 
 ---
 
+## Agent Integration
+
+This library ships an **agent skill** (`agents/`) that teaches AI coding assistants (Claude Code, Cursor, Hermes, or any agent reading `AGENTS.md`) how to scaffold gql-of-power entities, relationships, and advanced features correctly — using copy-paste templates, annotated relationship examples, and a decision tree for picking the right relationship type.
+
+To install it in a consumer project (one-time setup):
+
+```bash
+# Claude Code
+mkdir -p .claude/skills && cp -R node_modules/@dav3/gql-of-power/agents/ .claude/skills/gql-of-power/
+
+# Cursor
+mkdir -p .cursor/rules && cp node_modules/@dav3/gql-of-power/agents/SKILL.md .cursor/rules/gql-of-power.mdc
+
+# Hermes
+ln -s node_modules/@dav3/gql-of-power/agents ~/.hermes/skills/gql-of-power
+```
+
+See [`agents/install.md`](./agents/install.md) for full instructions (including a symlink option that tracks gql-of-power updates, slash-command setup, and a generic `AGENTS.md` snippet). Once installed, ask your agent to "add a gql-of-power entity" and it will follow the library's intended patterns.
+
+---
+
 ## Development
 
 ```bash
@@ -575,8 +596,11 @@ bun install        # Install dependencies
 bun run build      # Compile TypeScript → dist/
 bun run test       # Run all tests
 bun run test:watch # Watch mode
+bun run audit      # Codebase-intelligence gate (fallow): dead code, duplication, complexity
 ```
 
+`bun run audit` runs the changed-file gate against saved baselines in `.fallow/` and fails only on **new** findings it introduces. Use `bun run audit:full` for the complete report, or `bun run audit:dead-code` / `audit:dupes` / `audit:health` for individual analyses. See `AGENTS.md` for the full audit workflow.
+
 ---
 
 ## License

package/agents/templates/entity-skeleton.ts.txt

@@ -0,0 +1,136 @@
+// gql-of-power entity skeleton — copy, rename, and adapt.
+// Middle-earth themed example: a "Weapon" entity with a m:1 to its Bearer.
+//
+// This file is a template, not importable code. Place your real files in:
+//   schema/entities.ts   (ORM class + EntityMetadata)
+//   schema/fields.ts     (FieldsSettings)
+//   graphql/entities.ts  (createGQLTypes calls)
+//   graphql/resolvers.ts (@Resolver + @Query classes)
+
+import 'reflect-metadata';
+import { GraphQLResolveInfo } from 'graphql';
+import {
+	createGQLTypes,
+	GQLEntityFilterInputFieldType,
+	FieldsSettings,
+} from '@dav3/gql-of-power';
+import { EntityMetadata, EntityProperty, ReferenceType } from '@dav3/gql-of-power';
+import { Arg, Info, Int, Query, Resolver } from 'type-graphql';
+import { queryManager, provider } from './your-app-setup'; // <-- your wiring
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 1. ORM ENTITY CLASS  (schema/entities.ts)
+//    Plain TS class. Property names = JS names. Relationship fields optional.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class Weapon {
+	id!: number;
+	name!: string;
+	damage!: number;
+	// m:1 relationship — Weapon holds bearerId
+	bearerId?: number;
+	bearer?: Person;
+}
+
+export class Person {
+	id!: number;
+	name!: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 2. ENTITY METADATA  (schema/entities.ts)
+//    SQL reality: table, PKs, column names, relationship join columns.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const prop = (
+	type: string,
+	name: string,
+	fieldNames: string[],
+	reference?: {
+		referenceType: ReferenceType;
+		joinColumns?: string[];
+		referencedColumnNames?: string[];
+		mappedBy?: string;
+	}
+): EntityProperty => ({
+	type,
+	name,
+	fieldNames,
+	mappedBy: reference?.mappedBy || '',
+	joinColumns: reference?.joinColumns || [],
+	referencedColumnNames: reference?.referencedColumnNames || [],
+	inverseJoinColumns: [],
+	pivotTable: '',
+	reference: reference?.referenceType,
+});
+
+export const WeaponMetadata: EntityMetadata<Weapon> = {
+	name: 'Weapon',
+	tableName: 'weapons',
+	primaryKeys: ['id'],
+	properties: {
+		id: prop('number', 'id', ['id']),
+		name: prop('string', 'name', ['weapon_name']),
+		damage: prop('number', 'damage', ['damage']),
+		bearerId: prop('number', 'bearerId', ['bearer_id']),
+		bearer: prop('Person', 'bearer', ['bearer_id'], {
+			referenceType: ReferenceType.MANY_TO_ONE,
+			joinColumns: ['bearer_id'],
+			referencedColumnNames: ['id'],
+		}),
+	},
+};
+
+export const PersonMetadata: EntityMetadata<Person> = {
+	name: 'Person',
+	tableName: 'persons',
+	primaryKeys: ['id'],
+	properties: {
+		id: prop('number', 'id', ['id']),
+		name: prop('string', 'name', ['person_name']),
+	},
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 3. FIELDS SETTINGS  (schema/fields.ts)
+//    How each field maps to GraphQL. Pass to createGQLTypes.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Create PersonGQL first (Weapon references it)
+export const PersonGQL = createGQLTypes(Person, {
+	id: { type: () => Number, generateFilter: true },
+	name: { type: () => String, generateFilter: true },
+});
+
+export const WeaponFields: Partial<FieldsSettings<Weapon>> = {
+	id: { type: () => Number, generateFilter: true },
+	name: { type: () => String, generateFilter: true },
+	damage: { type: () => Int, generateFilter: true },
+	bearer: {
+		type: () => PersonGQL.GQLEntity,
+		options: { nullable: true },
+		generateFilter: true,
+		relatedEntityName: () => Person.name,
+		getFilterType: () => Int,
+	},
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 4. WIRE + RESOLVE  (graphql/entities.ts, graphql/resolvers.ts)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const WeaponGQL = createGQLTypes(Weapon, WeaponFields);
+
+@Resolver(() => WeaponGQL.GQLEntity || Object)
+export class WeaponResolver extends WeaponGQL.FieldsResolver {
+	@Query(() => [WeaponGQL.GQLEntity])
+	async weapons(
+		@Info() info: GraphQLResolveInfo,
+		@Arg('filter', () => WeaponGQL.GQLEntityFilterInput || Object, { nullable: true })
+		filter?: GQLEntityFilterInputFieldType<Weapon>
+	) {
+		// Relationship-field filters need `as any` (the type doesn't surface them):
+		//   { bearer: { name: 'Aragorn' } } as any
+		return await queryManager.getQueryResultsForInfo(provider, Weapon, info, filter);
+	}
+}

package/dist/entities/gql-entity.d.ts

@@ -1,5 +1,6 @@
 import { getMetadataStorage } from 'type-graphql';
-import { CountFieldMeta, CustomFieldsSettings, FieldSettings, FieldsSettings, GQLEntityFilterInputFieldType, GQLEntityPaginationInputType, RelatedFieldSettings } from '../types';
+import { CountFieldMeta, CustomFieldsSettings, FieldSettings, FieldsSettings, RelatedFieldSettings } from '../types/sql-types';
+import { GQLEntityFilterInputFieldType, GQLEntityPaginationInputType } from '../types/gql-types';
 import { AccessControlEntry } from '../types/access-control';
 export declare const setGlobalConfig: (config: {
     gqlTypesSuffix?: string;