polen 0.11.0-next.11 → 0.11.0-next.13

package/src/api/iso/schema/routing.ts

@@ -1,3 +1,4 @@
+import { Grafaid } from '#lib/grafaid'
 import { VERSION_LATEST } from './constants.js'
 
 export interface ReferencePathParts {
@@ -6,6 +7,11 @@ export interface ReferencePathParts {
   field?: string
 }
 
+interface RouteCheck {
+  pathname: string
+  params: Record<string, string | undefined>
+}
+
 export const createReferencePath = (parts: ReferencePathParts): string => {
   const basePath = createReferenceBasePath(parts.version)
   return joinSegmentsAndPaths(basePath, parts.type, parts.field)
@@ -51,3 +57,86 @@ export const joinSegmentsAndPaths = (
 
   return path
 }
+
+/**
+ * Check if the current route is a reference route
+ * @param route - Route information containing pathname and params
+ * @returns True if on a reference route
+ */
+export const isReferenceRoute = (route: RouteCheck): boolean => {
+  return route.params[`type`] !== undefined
+    || route.params[`field`] !== undefined
+    || route.params[`argument`] !== undefined
+    || route.pathname.includes(`/${segmentLiterals.reference}`)
+}
+
+/**
+ * Assert that the current route is a reference route
+ * @param route - Route information containing pathname and params
+ * @throws {Error} If not on a reference route
+ */
+export const assertReferenceRoute = (route: RouteCheck): void => {
+  if (!isReferenceRoute(route)) {
+    throw new Error('Not on a reference route. This function can only be used on reference routes.')
+  }
+}
+
+/**
+ * View type for reference routes
+ */
+export type ReferenceViewType =
+  | 'index' // No type selected
+  | 'type' // Type selected, no field
+  | 'field' // Type and field selected
+  | 'type-missing' // Type not found in schema
+  | 'field-missing' // Field not found on type
+
+export interface ReferenceViewParams {
+  schema: import('graphql').GraphQLSchema
+  type?: string
+  field?: string
+}
+
+/**
+ * Determine the view type for a reference route based on params and schema
+ */
+export const getReferenceViewType = (params: ReferenceViewParams): ReferenceViewType => {
+  const { schema, type: typeName, field: fieldName } = params
+
+  // No type selected - show index
+  if (!typeName) {
+    return 'index'
+  }
+
+  // Check if type exists
+  const type = schema.getType(typeName)
+  if (!type) {
+    return 'type-missing'
+  }
+
+  // No field selected - show type
+  if (!fieldName) {
+    return 'type'
+  }
+
+  // Check if type has fields
+  if (!Grafaid.Schema.TypesLike.isFielded(type)) {
+    return 'field-missing'
+  }
+
+  // Check if field exists
+  const fields = type.getFields()
+  if (!fields[fieldName]) {
+    return 'field-missing'
+  }
+
+  // Field exists - show field
+  return 'field'
+}
+
+/**
+ * Type guard to check if view type indicates missing content
+ */
+export const isMissingView = (viewType: ReferenceViewType): viewType is 'type-missing' | 'field-missing' => {
+  return viewType === 'type-missing' || viewType === 'field-missing'
+}

package/src/api/iso/schema/validation.ts

@@ -0,0 +1,136 @@
+import { Grafaid } from '#lib/grafaid'
+import type { GraphQLFieldMap, GraphQLSchema } from 'graphql'
+
+export interface PathValidation {
+  version?: string
+  type?: string
+  field?: string
+  argument?: string
+}
+
+/**
+ * Check if a reference path exists in the given schema
+ */
+export const doesPathExist = (schema: GraphQLSchema, path: PathValidation): boolean => {
+  if (!path.type) return true
+
+  const type = schema.getType(path.type)
+  if (!type) return false
+
+  if (!path.field) return true
+
+  if (!Grafaid.Schema.TypesLike.isFielded(type)) return false
+
+  const fields = type.getFields() as GraphQLFieldMap<unknown, unknown>
+  const field = fields[path.field]
+  if (!field) return false
+
+  if (!path.argument) return true
+
+  // Check if argument exists
+  const arg = field.args.find(a => a.name === path.argument)
+  return !!arg
+}
+
+/**
+ * Find the best fallback path when the current path doesn't exist
+ */
+export const findFallbackPath = (
+  schema: GraphQLSchema,
+  currentPath: PathValidation,
+): PathValidation => {
+  // If no type specified, return empty path
+  if (!currentPath.type) {
+    return { type: `Query` }
+  }
+
+  // Check if current path exists
+  if (doesPathExist(schema, currentPath)) {
+    return currentPath
+  }
+
+  // If viewing an argument that doesn't exist, fall back to parent field
+  if (currentPath.argument && currentPath.field) {
+    const fieldPath = { type: currentPath.type, field: currentPath.field }
+    if (doesPathExist(schema, fieldPath)) {
+      return fieldPath
+    }
+  }
+
+  // If viewing a field that doesn't exist, fall back to parent type
+  if (currentPath.field) {
+    const typePath = { type: currentPath.type }
+    if (doesPathExist(schema, typePath)) {
+      return typePath
+    }
+  }
+
+  // If viewing a type that doesn't exist, fall back to Query type
+  return { type: `Query` }
+}
+
+/**
+ * Get all available types in a schema
+ */
+export const getAvailableTypes = (schema: GraphQLSchema): string[] => {
+  const typeMap = schema.getTypeMap()
+  return Object.keys(typeMap).filter(name => !name.startsWith(`__`))
+}
+
+/**
+ * Get all available fields for a type
+ */
+export const getAvailableFields = (schema: GraphQLSchema, typeName: string): string[] => {
+  const type = schema.getType(typeName)
+  if (!type || !Grafaid.Schema.TypesLike.isFielded(type)) {
+    return []
+  }
+
+  const fields = type.getFields() as GraphQLFieldMap<unknown, unknown>
+  return Object.keys(fields)
+}
+
+/**
+ * Check if a path would require a redirect when switching to a new schema version
+ */
+export const wouldRequireRedirect = (
+  currentSchema: GraphQLSchema,
+  targetSchema: GraphQLSchema,
+  currentPath: PathValidation,
+): boolean => {
+  const existsInCurrent = doesPathExist(currentSchema, currentPath)
+  const existsInTarget = doesPathExist(targetSchema, currentPath)
+
+  return existsInCurrent && !existsInTarget
+}
+
+/**
+ * Get a human-readable description of what will happen when switching versions
+ */
+export const getRedirectDescription = (
+  targetSchema: GraphQLSchema,
+  currentPath: PathValidation,
+  fallbackPath: PathValidation,
+  targetVersion?: string,
+): string | null => {
+  if (!currentPath.type) return null
+
+  const currentExists = doesPathExist(targetSchema, currentPath)
+  if (currentExists) return null
+
+  const versionInfo = targetVersion ? ` in version ${targetVersion}` : ` in this version`
+
+  if (currentPath.argument && fallbackPath.field) {
+    return `Argument "${currentPath.argument}" doesn't exist${versionInfo}. Redirecting to field "${fallbackPath.field}".`
+  }
+
+  if (currentPath.field && fallbackPath.type && !fallbackPath.field) {
+    return `Field "${currentPath.field}" doesn't exist${versionInfo}. Redirecting to type "${fallbackPath.type}".`
+  }
+
+  if (currentPath.type !== fallbackPath.type) {
+    return `Type "${currentPath.type}" doesn't exist${versionInfo}. Redirecting to type "${fallbackPath.type}".`
+  }
+
+  return `This path doesn't exist${versionInfo}. Redirecting to a valid location.`
+}

package/src/api/schema/data-sources/introspection/introspection.ts

@@ -1,9 +1,9 @@
-import { Grafaid } from '#lib/grafaid/index'
-import { GraphqlChange } from '#lib/graphql-change/index'
-import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
-import { GraphqlSchemaLoader } from '#lib/graphql-schema-loader/index'
+import { Grafaid } from '#lib/grafaid'
+import { GraphqlChange } from '#lib/graphql-change'
+import type { GraphqlChangeset } from '#lib/graphql-changeset'
+import { GraphqlSchemaLoader } from '#lib/graphql-schema-loader'
 import { Fs, Json, Path } from '@wollybeard/kit'
-import type { NonEmptyChangeSets, SchemaReadResult } from '../../schema.js'
+import type { SchemaReadResult } from '../../schema.js'
 
 /**
  * Configuration for loading schema via GraphQL introspection.
@@ -191,7 +191,9 @@ export const readOrThrow = async (
  * Create a single changeset from a schema object.
  * This is the core logic for handling single (unversioned) schemas from introspection.
  */
-export const createSingleSchemaChangeset = async (schema: Grafaid.Schema.Schema): Promise<NonEmptyChangeSets> => {
+export const createSingleSchemaChangeset = async (
+  schema: Grafaid.Schema.Schema,
+): Promise<GraphqlChangeset.ChangelogLinked> => {
   const date = new Date() // Generate date here for unversioned schema
   const after = schema
   const before = Grafaid.Schema.empty
@@ -200,14 +202,15 @@ export const createSingleSchemaChangeset = async (schema: Grafaid.Schema.Schema)
     after,
   })
 
-  const changeset: GraphqlChangeset.ChangeSet = {
+  const changeset: GraphqlChangeset.IntermediateChangeSetLinked = {
+    type: 'IntermediateChangeSet',
     date,
-    after,
-    before,
+    after: { version: null, data: after },
+    before: { version: null, data: before },
     changes,
   }
 
-  const result: NonEmptyChangeSets = [changeset]
+  const result: GraphqlChangeset.ChangelogLinked = [changeset]
 
   return result
 }

package/src/api/schema/data-sources/memory/memory.ts

@@ -1,8 +1,7 @@
-import { Grafaid } from '#lib/grafaid/index'
-import { GraphqlChange } from '#lib/graphql-change/index'
-import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
+import { Grafaid } from '#lib/grafaid'
+import { GraphqlChange } from '#lib/graphql-change'
+import type { GraphqlChangeset } from '#lib/graphql-changeset'
 import { Arr } from '@wollybeard/kit'
-import type { NonEmptyChangeSets } from '../../schema.js'
 
 /**
  * Configuration for defining schemas programmatically in memory.
@@ -68,7 +67,7 @@ export const normalize = (configInput: ConfigInput): Config => {
 
 export const read = async (
   configInput: ConfigInput,
-): Promise<null | NonEmptyChangeSets> => {
+): Promise<null | GraphqlChangeset.ChangelogLinked> => {
   const config = normalize(configInput)
 
   if (!Arr.isntEmpty(config.versions)) {
@@ -86,30 +85,41 @@ export const read = async (
 
   // todo: make DRY, this is same as for schema-directory
   const changesets = await Promise.all(
-    Arr.map(versions, async (version, index): Promise<GraphqlChangeset.ChangeSet> => {
+    Arr.map(versions, async (version, index): Promise<GraphqlChangeset.ChangeSetLinked> => {
       const current = version
       const previous = versions[index - 1]
 
       const before = previous?.schema ?? Grafaid.Schema.empty
       const after = current.schema
 
-      const changes = await GraphqlChange.calcChangeset({
-        before,
-        after,
-      })
+      if (!previous) {
+        // First version - create InitialChangeSet
+        return {
+          type: 'InitialChangeSet',
+          date: current.date,
+          after: { version: null, data: after },
+        }
+      } else {
+        // Subsequent versions - create IntermediateChangeSet
+        const changes = await GraphqlChange.calcChangeset({
+          before,
+          after,
+        })
 
-      return {
-        date: current.date,
-        before,
-        after,
-        changes,
+        return {
+          type: 'IntermediateChangeSet',
+          date: current.date,
+          before: { version: null, data: before },
+          after: { version: null, data: after },
+          changes,
+        }
       }
     }),
   )
 
   changesets.reverse()
 
-  const schema: NonEmptyChangeSets = changesets
+  const schema: GraphqlChangeset.ChangelogLinked = changesets
 
   return schema
 }

package/src/api/schema/data-sources/schema-directory/schema-directory.ts

@@ -1,10 +1,9 @@
-import { Grafaid } from '#lib/grafaid/index'
-import { GraphqlChange } from '#lib/graphql-change/index'
-import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
+import { Grafaid } from '#lib/grafaid'
+import { GraphqlChange } from '#lib/graphql-change'
+import type { GraphqlChangeset } from '#lib/graphql-changeset'
 import { debugPolen } from '#singletons/debug'
 import { Arr, Path } from '@wollybeard/kit'
 import { glob } from 'tinyglobby'
-import type { NonEmptyChangeSets } from '../../schema.js'
 import { readSingleSchemaFile } from '../schema-file/schema-file.js'
 import { FileNameExpression } from './file-name-expression/index.js'
 
@@ -71,7 +70,7 @@ export const normalizeConfig = (configInput: ConfigInput): Config => {
   return config
 }
 
-export const readOrThrow = async (configInput: ConfigInput): Promise<null | NonEmptyChangeSets> => {
+export const readOrThrow = async (configInput: ConfigInput): Promise<null | GraphqlChangeset.ChangelogLinked> => {
   const config = normalizeConfig(configInput)
 
   debug(`will search`, config)
@@ -124,7 +123,7 @@ export const readOrThrow = async (configInput: ConfigInput): Promise<null | NonE
  */
 const readVersionedSchemas = async (
   versionedExpressions: FileNameExpression.ExpressionVersioned[],
-): Promise<NonEmptyChangeSets> => {
+): Promise<GraphqlChangeset.ChangelogLinked> => {
   const versions = await Promise.all(Arr.map(versionedExpressions, async fileNameExpression => {
     const schemaFile = await Grafaid.Schema.read(fileNameExpression.filePath)
     // Should never happen since these paths come from the glob.
@@ -140,23 +139,34 @@ const readVersionedSchemas = async (
   versions.sort((a, b) => a.date.getTime() - b.date.getTime())
 
   const changesets = await Promise.all(
-    Arr.map(versions, async (version, index): Promise<GraphqlChangeset.ChangeSet> => {
+    Arr.map(versions, async (version, index): Promise<GraphqlChangeset.ChangeSetLinked> => {
       const current = version
       const previous = versions[index - 1]
 
       const before = previous?.schema ?? Grafaid.Schema.empty
       const after = current.schema
 
-      const changes = await GraphqlChange.calcChangeset({
-        before,
-        after,
-      })
-
-      return {
-        date: current.date,
-        before,
-        after,
-        changes,
+      if (!previous) {
+        // First version - create InitialChangeSet
+        return {
+          type: 'InitialChangeSet',
+          date: current.date,
+          after: { version: null, data: after },
+        }
+      } else {
+        // Subsequent versions - create IntermediateChangeSet
+        const changes = await GraphqlChange.calcChangeset({
+          before,
+          after,
+        })
+
+        return {
+          type: 'IntermediateChangeSet',
+          date: current.date,
+          before: { version: null, data: before },
+          after: { version: null, data: after },
+          changes,
+        }
       }
     }),
   )
@@ -164,5 +174,5 @@ const readVersionedSchemas = async (
   changesets.reverse()
 
   debug(`computed versioned schema`)
-  return changesets as NonEmptyChangeSets
+  return changesets as GraphqlChangeset.ChangelogLinked
 }

package/src/api/schema/data-sources/schema-file/schema-file.ts

@@ -1,8 +1,7 @@
-import { Grafaid } from '#lib/grafaid/index'
-import { GraphqlChange } from '#lib/graphql-change/index'
-import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
+import { Grafaid } from '#lib/grafaid'
+import { GraphqlChange } from '#lib/graphql-change'
+import type { GraphqlChangeset } from '#lib/graphql-changeset'
 import { Path } from '@wollybeard/kit'
-import type { NonEmptyChangeSets } from '../../schema.js'
 
 const defaultPaths = {
   schemaFile: `./schema.graphql`,
@@ -46,7 +45,7 @@ export const normalizeConfig = (configInput: ConfigInput): Config => {
 
 export const readOrThrow = async (
   configInput: ConfigInput,
-): Promise<null | NonEmptyChangeSets> => {
+): Promise<null | GraphqlChangeset.ChangelogLinked> => {
   const config = normalizeConfig(configInput)
 
   const schemaFile = await Grafaid.Schema.read(config.path)
@@ -59,7 +58,7 @@ export const readOrThrow = async (
  * Create a single changeset from a schema file path.
  * This is the core logic for handling single (unversioned) schemas.
  */
-export const readSingleSchemaFile = async (filePath: string): Promise<NonEmptyChangeSets> => {
+export const readSingleSchemaFile = async (filePath: string): Promise<GraphqlChangeset.ChangelogLinked> => {
   const schemaFile = await Grafaid.Schema.read(filePath)
   if (!schemaFile) throw new Error(`Failed to read schema file: ${filePath}`)
 
@@ -71,14 +70,15 @@ export const readSingleSchemaFile = async (filePath: string): Promise<NonEmptyCh
     after,
   })
 
-  const changeset: GraphqlChangeset.ChangeSet = {
+  const changeset: GraphqlChangeset.IntermediateChangeSetLinked = {
+    type: 'IntermediateChangeSet',
     date,
-    after,
-    before,
+    after: { version: null, data: after },
+    before: { version: null, data: before },
     changes,
   }
 
-  const schema: NonEmptyChangeSets = [changeset]
+  const schema: GraphqlChangeset.ChangelogLinked = [changeset]
 
   return schema
 }

package/src/api/schema/read.ts

@@ -1,6 +1,6 @@
-import { Arr, Fs, Path } from '@wollybeard/kit'
+import type { GraphqlChangeset } from '#lib/graphql-changeset'
+import { Arr } from '@wollybeard/kit'
 import * as DataSources from './data-sources/data-sources.js'
-import type { NonEmptyChangeSets } from './schema.js'
 
 export type DataSourceType =
   | `file`
@@ -15,7 +15,7 @@ export type DataSourceType =
  * Result of schema reading with provenance tracking for file watching and debugging.
  */
 export interface SchemaReadResult {
-  data: NonEmptyChangeSets | null
+  data: GraphqlChangeset.ChangelogLinked | null
   source: {
     type: DataSourceType
     /**
@@ -26,7 +26,7 @@ export interface SchemaReadResult {
      *
      * @returns Promise resolving to the recreated schema data, or null if recreation fails
      */
-    reCreate?: () => Promise<NonEmptyChangeSets | null>
+    reCreate?: () => Promise<GraphqlChangeset.ChangelogLinked | null>
   }
 }
 
@@ -121,7 +121,7 @@ export interface Config {
     /**
      * Pre-built schema object to use directly.
      */
-    data?: NonEmptyChangeSets
+    data?: GraphqlChangeset.ChangelogLinked
     /**
      * Configuration for loading schema via GraphQL introspection.
      *

package/src/api/schema/schema.ts

@@ -1,5 +1,3 @@
-import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
-
 // Re-export everything from isomorphic layer
 export * from '../iso/schema/constants.js'
 export * as Routing from '../iso/schema/routing.js'
@@ -8,15 +6,3 @@ export * as Routing from '../iso/schema/routing.js'
 export * as DataSources from './data-sources/data-sources.js'
 export * from './metadata.js'
 export * from './read.js'
-
-export type ChangeSets = GraphqlChangeset.ChangeSet[]
-
-export type NonEmptyChangeSets = [GraphqlChangeset.ChangeSet, ...GraphqlChangeset.ChangeSet[]]
-
-/**
- * Changelog data structure for JSON serialization
- */
-export interface ChangelogData {
-  changes: GraphqlChangeset.ChangeSet['changes']
-  date: string
-}

package/src/api/schema-augmentation/augmentations/description.ts

@@ -1,4 +1,4 @@
-import type { GrafaidOld } from '#lib/grafaid-old/index'
+import type { GrafaidOld } from '#lib/grafaid-old'
 import { neverCase } from '@wollybeard/kit/language'
 import type { Target } from '../target.js'
 import { locateTargetField, locateTargetType } from '../target.js'

package/src/api/schema-augmentation/schema-augmentation.ts

@@ -1,4 +1,4 @@
-import type { GrafaidOld } from '#lib/grafaid-old/index'
+import type { GrafaidOld } from '#lib/grafaid-old'
 import { neverCase } from '@wollybeard/kit/language'
 import * as AugmentationDescription from './augmentations/description.js'
 

package/src/api/schema-augmentation/target.ts

@@ -1,4 +1,4 @@
-import { Grafaid } from '#lib/grafaid/index'
+import { Grafaid } from '#lib/grafaid'
 
 export type Target = TargetType | TargetField