Add @pothos/plugin-semantic-nullability

Plugin that converts non-null fields to nullable with @semanticNonNull
directives. Supports per-field opt-in via `semanticNonNull: true` and
schema-wide conversion via `allNonNullFields: true` with per-field
opt-out. Correctly computes `levels` for nested list types.

https://claude.ai/code/session_01MLrx31yBgXYrx1LEzfPs2e

Author: claude

packages/plugin-semantic-nullability/esm/.gitignore

@@ -0,0 +1,4 @@
+*
+!.gitignore
+!.npmignore
+!package.json

packages/plugin-semantic-nullability/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@pothos/plugin-semantic-nullability",
+  "version": "0.1.0",
+  "description": "A Pothos plugin that converts non-null fields to nullable with @semanticNonNull directives",
+  "main": "./lib/index.js",
+  "types": "./dts/index.d.ts",
+  "module": "./esm/index.js",
+  "exports": {
+    "import": {
+      "default": "./esm/index.js"
+    },
+    "require": {
+      "types": "./dts/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "scripts": {
+    "type": "tsc --project tsconfig.type.json",
+    "build": "pnpm build:clean && pnpm build:cjs && pnpm build:dts && pnpm build:esm",
+    "build:clean": "git clean -dfX esm lib",
+    "build:cjs": "swc src -d lib --config-file ../../.swcrc -C module.type=commonjs --strip-leading-paths",
+    "build:esm": "cp -r dts/* esm/ && swc src -d esm --config-file ../../.swcrc -C module.type=es6 --strip-leading-paths && pnpm esm:extensions",
+    "build:dts": "tsc",
+    "esm:extensions": "TS_NODE_PROJECT=../../tsconfig.json node -r @swc-node/register ../../scripts/esm-transformer.ts",
+    "test": "pnpm vitest --run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hayes/pothos.git",
+    "directory": "packages/plugin-semantic-nullability"
+  },
+  "author": "Michael Hayes",
+  "license": "ISC",
+  "keywords": [
+    "pothos",
+    "graphql",
+    "schema",
+    "typescript",
+    "semantic-nullability",
+    "semanticNonNull"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "@pothos/core": "*",
+    "graphql": "^16.10.0"
+  },
+  "devDependencies": {
+    "@pothos/core": "workspace:*",
+    "@pothos/test-utils": "workspace:*",
+    "graphql-tag": "^2.12.6"
+  },
+  "gitHead": "9dfe52f1975f41a111e01bf96a20033a914e2acc"
+}

packages/plugin-semantic-nullability/src/global-types.ts

@@ -0,0 +1,34 @@
+import type {
+  FieldNullability,
+  InputFieldMap,
+  SchemaTypes,
+  TypeParam,
+} from '@pothos/core';
+import type { PothosSemanticNullabilityPlugin } from '.';
+
+declare global {
+  export namespace PothosSchemaTypes {
+    export interface Plugins<Types extends SchemaTypes> {
+      semanticNullability: PothosSemanticNullabilityPlugin<Types>;
+    }
+
+    export interface SchemaBuilderOptions<Types extends SchemaTypes> {
+      semanticNullability?: {
+        /** When true, all non-null output fields are converted to nullable with @semanticNonNull */
+        allNonNullFields?: boolean;
+      };
+    }
+
+    export interface FieldOptions<
+      Types extends SchemaTypes = SchemaTypes,
+      ParentShape = unknown,
+      Type extends TypeParam<Types> = TypeParam<Types>,
+      Nullable extends FieldNullability<Type> = FieldNullability<Type>,
+      Args extends InputFieldMap = InputFieldMap,
+      ResolveShape = unknown,
+      ResolveReturnShape = unknown,
+    > {
+      semanticNonNull?: boolean;
+    }
+  }
+}

packages/plugin-semantic-nullability/src/index.ts

@@ -0,0 +1,145 @@
+import './global-types';
+import SchemaBuilder, {
+  BasePlugin,
+  type PothosOutputFieldConfig,
+  type PothosOutputFieldType,
+  type SchemaTypes,
+} from '@pothos/core';
+import {
+  DirectiveLocation,
+  GraphQLDirective,
+  GraphQLInt,
+  GraphQLList,
+  GraphQLNonNull,
+  type GraphQLSchema,
+} from 'graphql';
+
+const pluginName = 'semanticNullability';
+
+export default pluginName;
+
+function collectNonNullLevels<Types extends SchemaTypes>(
+  type: PothosOutputFieldType<Types>,
+  level = 0,
+): number[] {
+  const levels: number[] = [];
+
+  if (!type.nullable) {
+    levels.push(level);
+  }
+
+  if (type.kind === 'List') {
+    levels.push(...collectNonNullLevels(type.type, level + 1));
+  }
+
+  return levels;
+}
+
+function makeNullable<Types extends SchemaTypes>(
+  type: PothosOutputFieldType<Types>,
+): PothosOutputFieldType<Types> {
+  if (type.kind === 'List') {
+    return {
+      ...type,
+      nullable: true,
+      type: makeNullable(type.type),
+    };
+  }
+
+  return {
+    ...type,
+    nullable: true,
+  };
+}
+
+export class PothosSemanticNullabilityPlugin<
+  Types extends SchemaTypes,
+> extends BasePlugin<Types> {
+  override onOutputFieldConfig(
+    fieldConfig: PothosOutputFieldConfig<Types>,
+  ): PothosOutputFieldConfig<Types> {
+    const fieldOption = fieldConfig.pothosOptions.semanticNonNull;
+    const allNonNullFields =
+      this.builder.options.semanticNullability?.allNonNullFields ?? false;
+
+    // Per-field option takes priority over the schema-wide default.
+    const enabled = fieldOption ?? allNonNullFields;
+
+    if (!enabled) {
+      return fieldConfig;
+    }
+
+    // Collect which levels are non-null before we modify anything
+    const levels = collectNonNullLevels(fieldConfig.type);
+
+    // Nothing to convert if already fully nullable
+    if (levels.length === 0) {
+      return fieldConfig;
+    }
+
+    // Make all levels nullable and attach the directive.
+    // Omit levels arg when it's just [0] (the default).
+    const directiveArgs = levels.length === 1 && levels[0] === 0 ? {} : { levels };
+
+    return {
+      ...fieldConfig,
+      type: makeNullable(fieldConfig.type),
+      extensions: {
+        ...fieldConfig.extensions,
+        directives: mergeDirective(
+          fieldConfig.extensions?.directives as DirectiveList | undefined,
+          directiveArgs,
+        ),
+      },
+    };
+  }
+
+  override afterBuild(schema: GraphQLSchema) {
+    // Add the @semanticNonNull directive definition to the schema if not already present
+    const existing = schema.getDirectives();
+    const hasDirective = existing.some((d) => d.name === 'semanticNonNull');
+
+    if (!hasDirective) {
+      const directives = [
+        ...existing,
+        new GraphQLDirective({
+          name: 'semanticNonNull',
+          locations: [DirectiveLocation.FIELD_DEFINITION],
+          args: {
+            levels: {
+              type: new GraphQLList(new GraphQLNonNull(GraphQLInt)),
+              defaultValue: [0],
+            },
+          },
+        }),
+      ];
+
+      // GraphQLSchema stores directives as a readonly array set during construction,
+      // but we need to add our directive after the schema is built.
+      Object.defineProperty(schema, '_directives', { value: directives });
+    }
+
+    return schema;
+  }
+}
+
+type DirectiveList = Array<{ name: string; args: Record<string, unknown> }>;
+
+function mergeDirective(
+  existing: DirectiveList | undefined,
+  directiveArgs: { levels?: number[] },
+): DirectiveList {
+  const existingDirectives = existing ?? [];
+
+  return [
+    ...(Array.isArray(existingDirectives)
+      ? existingDirectives
+      : Object.keys(existingDirectives).map((name) => ({
+          name,
+          args: (existingDirectives as unknown as Record<string, Record<string, unknown>>)[name],
+        }))),
+    { name: 'semanticNonNull', args: directiveArgs },
+  ];
+}
+
+SchemaBuilder.registerPlugin(pluginName, PothosSemanticNullabilityPlugin);

packages/plugin-semantic-nullability/tests/__snapshots__/index.test.ts.snap

@@ -0,0 +1,22 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`plugin-semantic-nullability > per-field opt-in > generates expected schema 1`] = `
+"directive @semanticNonNull(levels: [Int!] = [0]) on FIELD_DEFINITION
+
+type Query {
+  age: Int!
+  bio: String
+  name: String
+  tags: [String]
+}"
+`;
+
+exports[`plugin-semantic-nullability > schema-wide allNonNullFields > generates expected schema 1`] = `
+"directive @semanticNonNull(levels: [Int!] = [0]) on FIELD_DEFINITION
+
+type Query {
+  age: Int!
+  bio: String
+  name: String
+}"
+`;