From 5cde858a544af07393a7c9c16039ca9bade77c26 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Wed, 21 Jan 2026 18:10:29 -0500
Subject: [PATCH] Simplify isFileDef and improve typing

---
 packages/base/card-api.gts                    | 50 ++++++-------------
 packages/base/links-to-editor.gts             |  2 +-
 packages/base/links-to-many-component.gts     |  8 +--
 packages/host/app/lib/gc-card-store.ts        |  7 +--
 packages/host/app/resources/card-resource.ts  | 10 +---
 .../components/card-basics-test.gts           |  2 +-
 packages/runtime-common/code-ref.ts           | 11 ++++
 7 files changed, 33 insertions(+), 57 deletions(-)

diff --git a/packages/base/card-api.gts b/packages/base/card-api.gts
index f444844bb3..a562ef1086 100644
--- a/packages/base/card-api.gts
+++ b/packages/base/card-api.gts
@@ -16,7 +16,6 @@ import { getLinksToManyComponent } from './links-to-many-component';
 import {
   assertIsSerializerName,
   baseRef,
-  baseRealm,
   CardContextName,
   CardError,
   CodeRef,
@@ -32,12 +31,12 @@ import {
   getSerializer,
   humanReadable,
   identifyCard,
-  normalizeCodeRef,
   isBaseInstance,
   isCardError,
   isCardInstance as _isCardInstance,
   isCardResource,
   isFileMetaResource,
+  isFileDef,
   isField,
   isFieldInstance,
   isRelationship,
@@ -167,6 +166,7 @@ export {
   getFields,
   isCard,
   isField,
+  isFileDef,
   localId,
   meta,
   primitive,
@@ -333,28 +333,6 @@ export function instanceOf(instance: BaseDef, clazz: typeof BaseDef): boolean {
   return false;
 }
 
-export function isFileDefConstructor(card: typeof BaseDef): boolean {
-  let baseFileDefRef = {
-    module: `${baseRealm.url}file-api`,
-    name: 'FileDef',
-  };
-  let current: typeof BaseDef | undefined = card;
-  while (current) {
-    let ref = identifyCard(current);
-    if (ref) {
-      let normalized = normalizeCodeRef(ref);
-      if (
-        normalized.module === baseFileDefRef.module &&
-        normalized.name === baseFileDefRef.name
-      ) {
-        return true;
-      }
-    }
-    current = getAncestor(current) as typeof BaseDef | undefined;
-  }
-  return false;
-}
-
 class Logger {
   private promises: Promise<any>[] = [];
 
@@ -1087,7 +1065,7 @@ class LinksTo<CardT extends LinkableDefConstructor> implements Field<CardT> {
     visited: Set<string>,
     opts?: SerializeOpts,
   ) {
-    let relationshipType = isFileDefConstructor(this.card as typeof BaseDef)
+    let relationshipType = isFileDef(this.card)
       ? FileMetaResourceType
       : CardResourceType;
     if (isNotLoadedValue(value)) {
@@ -1110,7 +1088,7 @@ class LinksTo<CardT extends LinkableDefConstructor> implements Field<CardT> {
         },
       };
     }
-    if (isFileDefConstructor(this.card as typeof BaseDef) && !value.id) {
+    if (isFileDef(this.card) && !value.id) {
       throw new Error(
         `linksTo field '${this.name}' cannot serialize a FileDef without an id`,
       );
@@ -1266,7 +1244,7 @@ class LinksTo<CardT extends LinkableDefConstructor> implements Field<CardT> {
       if (isNotLoadedValue(value)) {
         return value;
       }
-      if (isFileDefConstructor(this.card as typeof BaseDef) && !value.id) {
+      if (isFileDef(this.card) && !value.id) {
         throw new Error(
           `field validation error: the linksTo field '${this.name}' cannot reference a FileDef without an id`,
         );
@@ -1310,7 +1288,7 @@ class LinksTo<CardT extends LinkableDefConstructor> implements Field<CardT> {
       let innerModel = model.field(fieldName);
       return innerModel as unknown as Box<CardDef | null>;
     };
-    let isFileDef = isFileDefConstructor(linksToField.card as typeof BaseDef);
+    let isFileDefField = isFileDef(linksToField.card);
     function shouldRenderEditor(
       format: Format | undefined,
       defaultFormat: Format,
@@ -1323,14 +1301,14 @@ class LinksTo<CardT extends LinkableDefConstructor> implements Field<CardT> {
       format: Format | undefined,
       defaultFormat: Format,
       model: Box<FieldDef>,
-      isFileDef: boolean,
+      isFileDefField: boolean,
     ) {
       let effectiveFormat = format ?? defaultFormat;
       if (
         effectiveFormat === 'edit' &&
         (('isCardDef' in model.value.constructor &&
           model.value.constructor.isCardDef) ||
-          isFileDef)
+          isFileDefField)
       ) {
         return 'fitted';
       }
@@ -1352,7 +1330,7 @@ class LinksTo<CardT extends LinkableDefConstructor> implements Field<CardT> {
           <DefaultFormatsConsumer as |defaultFormats|>
             {{#if
               (shouldRenderEditor
-                @format defaultFormats.cardDef isComputed isFileDef
+                @format defaultFormats.cardDef isComputed isFileDefField
               )
             }}
               <LinksToEditor
@@ -1369,7 +1347,7 @@ class LinksTo<CardT extends LinkableDefConstructor> implements Field<CardT> {
                     @format
                     defaultFormats.cardDef
                     model
-                    isFileDef
+                    isFileDefField
                   }}
                   @displayContainer={{@displayContainer}}
                   ...attributes
@@ -1580,7 +1558,7 @@ class LinksToMany<FieldT extends LinkableDefConstructor>
       throw new Error(`Expected array for field value ${this.name}`);
     }
 
-    let relationshipType = isFileDefConstructor(this.card as typeof BaseDef)
+    let relationshipType = isFileDef(this.card)
       ? FileMetaResourceType
       : CardResourceType;
     let relationships: Record<string, Relationship> = {};
@@ -1603,7 +1581,7 @@ class LinksToMany<FieldT extends LinkableDefConstructor>
         };
         return;
       }
-      if (isFileDefConstructor(this.card as typeof BaseDef) && !value.id) {
+      if (isFileDef(this.card) && !value.id) {
         throw new Error(
           `linksToMany field '${this.name}' cannot serialize a FileDef without an id`,
         );
@@ -1815,7 +1793,7 @@ class LinksToMany<FieldT extends LinkableDefConstructor>
       if (
         !isNotLoadedValue(value) &&
         value != null &&
-        isFileDefConstructor(expectedCard as typeof BaseDef) &&
+        isFileDef(expectedCard) &&
         !value.id
       ) {
         throw new Error(
@@ -2770,7 +2748,7 @@ function lazilyLoadLink(
     ),
   );
   (async () => {
-    let isFileLink = isFileDefConstructor(field.card as typeof BaseDef);
+    let isFileLink = isFileDef(field.card);
     try {
       let fieldValue: CardDef | FileDef;
       if (isFileLink) {
diff --git a/packages/base/links-to-editor.gts b/packages/base/links-to-editor.gts
index d451f07b60..2a8bab9d6a 100644
--- a/packages/base/links-to-editor.gts
+++ b/packages/base/links-to-editor.gts
@@ -1,4 +1,5 @@
 import GlimmerComponent from '@glimmer/component';
+import { hash } from '@ember/helper';
 import { on } from '@ember/modifier';
 import {
   restartableTask,
@@ -32,7 +33,6 @@ import {
 import { Button, IconButton } from '@cardstack/boxel-ui/components';
 import { IconMinusCircle } from '@cardstack/boxel-ui/icons';
 import { consume } from 'ember-provide-consume-context';
-import { hash } from '@ember/helper';
 
 interface Signature {
   Element: HTMLElement;
diff --git a/packages/base/links-to-many-component.gts b/packages/base/links-to-many-component.gts
index 2a6b173fd2..8b6ebda88b 100644
--- a/packages/base/links-to-many-component.gts
+++ b/packages/base/links-to-many-component.gts
@@ -13,7 +13,7 @@ import {
   type LinkableDefConstructor,
   CreateCardFn,
   CardCrudFunctions,
-  isFileDefConstructor,
+  isFileDef,
 } from './card-api';
 import {
   BoxComponentSignature,
@@ -515,13 +515,13 @@ export function getLinksToManyComponent({
       getBoxComponent(cardTypeFor(field, child), child, field),
     ); // Wrap the the components in a function so that the template is reactive to changes in the model (this is essentially a helper)
   let isComputed = !!field.computeVia || !!field.queryDefinition;
-  let isFileDef = isFileDefConstructor(field.card as typeof BaseDef);
+  let isFileDefField = isFileDef(field.card);
   let linksToManyComponent = class LinksToManyComponent extends GlimmerComponent<BoxComponentSignature> {
     <template>
       <DefaultFormatsConsumer as |defaultFormats|>
         {{#if
           (shouldRenderEditor
-            @format defaultFormats.cardDef isComputed isFileDef
+            @format defaultFormats.cardDef isComputed isFileDefField
           )
         }}
           <LinksToManyEditor
@@ -559,7 +559,7 @@ export function getLinksToManyComponent({
                     @format={{getPluralChildFormat
                       effectiveFormat
                       model
-                      isFileDef
+                      isFileDefField
                     }}
                     @displayContainer={{@displayContainer}}
                     class='linksToMany-item'
diff --git a/packages/host/app/lib/gc-card-store.ts b/packages/host/app/lib/gc-card-store.ts
index 61bb0cc7f6..72fe09bd2a 100644
--- a/packages/host/app/lib/gc-card-store.ts
+++ b/packages/host/app/lib/gc-card-store.ts
@@ -5,6 +5,7 @@ import { TrackedMap } from 'tracked-built-ins';
 import {
   isPrimitive,
   isCardInstance,
+  isFileDefInstance,
   isLocalId,
   localId as localIdSymbol,
   loadCardDocument,
@@ -54,12 +55,6 @@ type StoreHooks = {
   ): StoreSearchResource<T>;
 };
 
-function isFileDefInstance(item: unknown): item is FileDef {
-  return Boolean(
-    (item as { constructor?: { isFileDef?: boolean } })?.constructor?.isFileDef,
-  );
-}
-
 function isCardOrFileInstance(item: unknown): item is StoredInstance {
   return isCardInstance(item) || isFileDefInstance(item);
 }
diff --git a/packages/host/app/resources/card-resource.ts b/packages/host/app/resources/card-resource.ts
index 100cd25424..814673c404 100644
--- a/packages/host/app/resources/card-resource.ts
+++ b/packages/host/app/resources/card-resource.ts
@@ -7,20 +7,12 @@ import { service } from '@ember/service';
 
 import { Resource } from 'ember-modify-based-class-resource';
 
-import { isCardInstance } from '@cardstack/runtime-common';
+import { isCardInstance, isFileDefInstance } from '@cardstack/runtime-common';
 
 import type { BaseDef } from 'https://cardstack.com/base/card-api';
-import type { FileDef } from 'https://cardstack.com/base/file-api';
 
 import type StoreService from '../services/store';
 
-function isFileDefInstance(value: unknown): value is FileDef {
-  return Boolean(
-    (value as { constructor?: { isFileDef?: boolean } })?.constructor
-      ?.isFileDef,
-  );
-}
-
 interface Args {
   named: {
     id: string | undefined;
diff --git a/packages/host/tests/integration/components/card-basics-test.gts b/packages/host/tests/integration/components/card-basics-test.gts
index 3137a4c7e5..71401af5e4 100644
--- a/packages/host/tests/integration/components/card-basics-test.gts
+++ b/packages/host/tests/integration/components/card-basics-test.gts
@@ -701,7 +701,7 @@ module('Integration | card-basics', function (hooks) {
 
       test('linksTo FileDef renders delegated view from realm file meta', async function (assert) {
         class Gallery extends CardDef {
-          @field hero = linksTo(FileDef as unknown as typeof CardDef);
+          @field hero = linksTo(FileDef);
           static fitted = class Fitted extends Component<typeof this> {
             <template>
               <div data-test-gallery-fitted>
diff --git a/packages/runtime-common/code-ref.ts b/packages/runtime-common/code-ref.ts
index 6aee1d7e4d..f9b5e45100 100644
--- a/packages/runtime-common/code-ref.ts
+++ b/packages/runtime-common/code-ref.ts
@@ -6,6 +6,7 @@ import type {
   FieldDef,
   FieldConstructor,
 } from 'https://cardstack.com/base/card-api';
+import type { FileDef } from 'https://cardstack.com/base/file-api';
 import { Loader } from './loader';
 import {
   isField,
@@ -109,12 +110,22 @@ export function isFieldDef(field: any): field is typeof FieldDef {
   return isBaseDef(field) && 'isFieldDef' in field;
 }
 
+export function isFileDef(def: any): def is typeof FileDef {
+  return isBaseDef(def) && 'isFileDef' in def;
+}
+
 export function isFieldInstance<T extends FieldDef>(
   fieldInstance: any,
 ): fieldInstance is T {
   return isFieldDef(fieldInstance?.constructor);
 }
 
+export function isFileDefInstance<T extends FileDef>(
+  fileInstance: any,
+): fileInstance is T {
+  return isFileDef(fileInstance?.constructor);
+}
+
 export function isPrimitive(def: any) {
   return isBaseDef(def) && primitive in def;
 }