fix: make core declarations portable

CHANGELOG.md

@@ -31,6 +31,12 @@ Three reach npm for the first time in this release:
   18, and Node 20 before 20.19, are no longer supported.
 - `@flatbread/config` declares `@flatbread/core` as a runtime dependency. It
   was a devDependency, which worked inside this monorepo and nowhere else.
+- `@flatbread/core` no longer emits type declarations a packed install cannot
+  resolve. Its `.d.ts` files reached into the private paths
+  `graphql/jsutils/Maybe` and `graphql/jsutils/ObjMap`; they now use public
+  GraphQL types, and `FlatbreadProvider.query()` declares its return as
+  GraphQL's public `ExecutionResult`. `vfile@5.3.4` moves from devDependencies
+  to dependencies, because the public types name `VFile`.
 - `@flatbread/codegen` widens its peer range on `@flatbread/config` and
   `@flatbread/core` from `workspace:*` to `workspace:^`, so it publishes a
   caret range instead of an exact pin.

packages/core/package.json

@@ -36,13 +36,13 @@
     "graphql-compose": "9.0.8",
     "lodash-es": "4.18.1",
     "matcher": "5.0.0",
-    "plur": "5.1.0"
+    "plur": "5.1.0",
+    "vfile": "5.3.4"
   },
   "devDependencies": {
     "@types/lodash-es": "4.17.6",
     "@types/node": "16.11.47",
     "tsup": "6.2.1",
-    "typescript": "4.7.4",
-    "vfile": "5.3.4"
+    "typescript": "4.7.4"
   }
 }

packages/core/src/providers/base.ts

@@ -2,7 +2,8 @@ import { generateSchema } from '../generators/schema';
 import { FlatbreadConfig } from '../types';
 import { initializeConfig } from '../utils/initializeConfig';
 
-import { graphql, GraphQLArgs, GraphQLSchema } from 'graphql';
+import { graphql } from 'graphql';
+import type { ExecutionResult, GraphQLArgs, GraphQLSchema } from 'graphql';
 
 /**
  * **Flatbread Provider**
@@ -23,7 +24,7 @@ export class FlatbreadProvider {
    * @param args GraphQLArgs needed for executing a query. Typically, this is just a standard GraphQL query.
    * @returns GraphQL response
    */
-  async query(args: Omit<GraphQLArgs, 'schema'>) {
+  async query(args: Omit<GraphQLArgs, 'schema'>): Promise<ExecutionResult> {
     const schema = await this.schemaPromise;
     return await graphql({ schema, ...args });
   }

packages/core/src/types.test.ts

@@ -1,4 +1,5 @@
 import test from 'ava';
+import { readFileSync } from 'node:fs';
 import type {
   Content,
   ContentEntry,
@@ -37,6 +38,9 @@ type ContentNodeIdUsesIdentifierField = Assert<
 type OverrideResolveReturnsUnknown = Assert<
   Equal<ReturnType<Override['resolve']>, unknown>
 >;
+type OverrideDescriptionMatchesGraphQL = Assert<
+  Equal<Override['description'], string | null | undefined>
+>;
 
 test('core public content types expose narrowed relation surfaces', (t) => {
   const entry: ContentEntry = {
@@ -63,9 +67,31 @@ test('core public content types expose narrowed relation surfaces', (t) => {
   t.is(unsafeString, 'value');
 });
 
+test('core declarations use only the public GraphQL type surface', (t) => {
+  const declarations = readFileSync(
+    new URL('../dist/index.d.ts', import.meta.url),
+    'utf8'
+  );
+
+  t.false(declarations.includes('graphql/jsutils/'));
+});
+
+test('core publishes dependencies used by its declarations', (t) => {
+  const manifest = JSON.parse(
+    readFileSync(new URL('../package.json', import.meta.url), 'utf8')
+  ) as {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+  };
+
+  t.is(manifest.dependencies?.vfile, '5.3.4');
+  t.false('vfile' in (manifest.devDependencies ?? {}));
+});
+
 void (0 as unknown as ContentEntryRefsAreTyped);
 void (0 as unknown as ContentNodeKeepsUnknownFields);
 void (0 as unknown as SourceFetchUsesContent);
 void (0 as unknown as SourceFetchByTypeReturnsVFiles);
 void (0 as unknown as ContentNodeIdUsesIdentifierField);
 void (0 as unknown as OverrideResolveReturnsUnknown);
+void (0 as unknown as OverrideDescriptionMatchesGraphQL);

packages/core/src/types.ts

@@ -1,9 +1,9 @@
-import {
+import type {
   GraphQLFieldConfigArgumentMap,
+  GraphQLFieldConfig,
   GraphQLInputType,
   GraphQLSchema,
 } from 'graphql';
-import { Maybe } from 'graphql/jsutils/Maybe';
 import type { VFile } from 'vfile';
 
 // Import CodegenOptions type from the codegen package
@@ -195,7 +195,7 @@ export interface Override {
   field: string;
   type: GraphQLInputType | string;
   args?: GraphQLFieldConfigArgumentMap;
-  description?: Maybe<string>;
+  description?: GraphQLFieldConfig<unknown, unknown>['description'];
   resolve: (
     data: unknown,
     extended: {