sonamu 0.10.4 → 0.10.6

package/src/cone/cone-generator.ts

@@ -85,10 +85,9 @@ function getApiKey(): string {
 }
 
 /**
- * 도메인별 {domain}.contract.md와 architecture.md를 읽어 컨텍스트로 반환합니다.
+ * 도메인별 {domain}.contract.md를 읽어 컨텍스트로 반환합니다.
  *
- * - contract/{domain}/{domain}.contract.md: 도메인 규칙과 결정 근거 (주 참조 대상)
- * - .claude/skills/project/architecture.md: 엔티티 설계 구조 (보조 참조)
+ * - contract/{domain}/{domain}.contract.md: 도메인 규칙과 결정 근거
  *
  * cone 생성 시 LLM에게 전달하여 도메인 맥락에 맞는 메타데이터를 생성하도록 합니다.
  */
@@ -122,21 +121,6 @@ function readProjectSkills(): string {
       }
     }
 
-    // .claude/skills/project/architecture.md 보조 참조
-    const architecturePath = path.join(
-      projectRoot,
-      ".claude",
-      "skills",
-      "project",
-      "architecture.md",
-    );
-    if (fs.existsSync(architecturePath)) {
-      const content = fs.readFileSync(architecturePath, "utf-8").trim();
-      if (content) {
-        contents.push(`--- architecture.md ---\n${content}`);
-      }
-    }
-
     return contents.join("\n\n");
   } catch {
     // Sonamu 미초기화 또는 파일 접근 오류 시 빈 문자열 반환

package/src/database/__tests__/puri.test.ts

@@ -7,6 +7,7 @@ type TestSchema = {
   users: {
     id: number;
     name: string;
+    department_id: number | null;
     payload: {
       actor: {
         id: string;
@@ -18,6 +19,14 @@ type TestSchema = {
     state: string;
     readonly __json__: readonly ["payload", "tags", "state"];
   };
+  departments: {
+    id: number;
+    name: string;
+  };
+  companies: {
+    id: number;
+    name: string;
+  };
 };
 
 const db = knex({ client: "pg" });
@@ -99,3 +108,177 @@ describe("Puri JSONB containment", () => {
     expect(query.rawQuery().toSQL().sql).toBe('select * from "users"');
   });
 });
+
+describe("Puri ensureJoin", () => {
+  it("기존의 동일한 JOIN을 재사용한다", () => {
+    const query = usersQuery()
+      .join({ department: "departments" }, "users.department_id", "department.id")
+      .ensureJoin({ department: "departments" }, "users.department_id", "department.id");
+
+    expect(query.toQuery().match(/join "departments" as "department"/g)).toHaveLength(1);
+  });
+
+  it("등록되지 않은 JOIN을 추가한다", () => {
+    const query = usersQuery().ensureJoin(
+      { department: "departments" },
+      "users.department_id",
+      "department.id",
+    );
+
+    expect(query.toQuery()).toContain(
+      'join "departments" as "department" on "users"."department_id" = "department"."id"',
+    );
+  });
+
+  it("같은 alias의 JOIN 조건이 다르면 실행 전에 오류를 던진다", () => {
+    const query = usersQuery().join(
+      { department: "departments" },
+      "users.department_id",
+      "department.id",
+    );
+
+    expect(() =>
+      query.ensureJoin({ department: "departments" }, "users.id", "department.id"),
+    ).toThrowError(
+      [
+        'Join alias "department" is already registered with a different definition.',
+        "Existing: JOIN departments AS department ON users.department_id = department.id",
+        "Requested: JOIN departments AS department ON users.id = department.id",
+      ].join("\n"),
+    );
+  });
+
+  it.each([
+    {
+      name: "테이블",
+      create: () =>
+        usersQuery()
+          .join({ department: "departments" }, "users.department_id", "department.id")
+          .ensureJoin({ department: "companies" }, "users.department_id", "department.id"),
+      requested: "Requested: JOIN companies AS department ON users.department_id = department.id",
+    },
+    {
+      name: "JOIN 타입",
+      create: () =>
+        usersQuery()
+          .join({ department: "departments" }, "users.department_id", "department.id")
+          .ensureLeftJoin({ department: "departments" }, "users.department_id", "department.id"),
+      requested:
+        "Requested: LEFT JOIN departments AS department ON users.department_id = department.id",
+    },
+    {
+      name: "왼쪽 조건",
+      create: () =>
+        usersQuery()
+          .join({ department: "departments" }, "users.department_id", "department.id")
+          .ensureJoin({ department: "departments" }, "users.id", "department.id"),
+      requested: "Requested: JOIN departments AS department ON users.id = department.id",
+    },
+    {
+      name: "오른쪽 조건",
+      create: () =>
+        usersQuery()
+          .join({ department: "departments" }, "users.department_id", "department.id")
+          .ensureJoin({ department: "departments" }, "users.department_id", "department.name"),
+      requested:
+        "Requested: JOIN departments AS department ON users.department_id = department.name",
+    },
+  ])("같은 alias의 $name 정의가 다르면 실행 전에 오류를 던진다", ({ create, requested }) => {
+    expect(create).toThrowError(
+      'Join alias "department" is already registered with a different definition.',
+    );
+    expect(create).toThrowError(requested);
+  });
+
+  it("일반 JOIN은 같은 alias를 중복 등록할 수 없다", () => {
+    const query = usersQuery().join(
+      { department: "departments" },
+      "users.department_id",
+      "department.id",
+    );
+
+    expect(() =>
+      query.join({ department: "departments" }, "users.department_id", "department.id"),
+    ).toThrowError(/Join alias "department" is already registered/);
+  });
+
+  it("같은 테이블을 서로 다른 alias로 JOIN할 수 있다", () => {
+    const query = usersQuery()
+      .ensureJoin(
+        { primary_department: "departments" },
+        "users.department_id",
+        "primary_department.id",
+      )
+      .ensureJoin({ fallback_department: "departments" }, "users.id", "fallback_department.id");
+
+    expect(query.toQuery()).toContain('join "departments" as "primary_department"');
+    expect(query.toQuery()).toContain('join "departments" as "fallback_department"');
+  });
+
+  it("기존의 동일한 LEFT JOIN을 재사용한다", () => {
+    const query = usersQuery()
+      .leftJoin({ department: "departments" }, "users.department_id", "department.id")
+      .ensureLeftJoin({ department: "departments" }, "users.department_id", "department.id");
+
+    expect(query.toQuery().match(/left join "departments" as "department"/g)).toHaveLength(1);
+  });
+
+  it("callback JOIN은 동일성을 추론하지 않는다", () => {
+    const query = usersQuery().join({ department: "departments" }, (join) => {
+      join.on("users.department_id", "department.id");
+    });
+
+    expect(() =>
+      query.ensureJoin({ department: "departments" }, "users.department_id", "department.id"),
+    ).toThrowError(/Existing: JOIN departments AS department with opaque condition/);
+  });
+
+  it("clone은 JOIN registry를 독립적으로 복제한다", () => {
+    const original = usersQuery().ensureJoin(
+      { department: "departments" },
+      "users.department_id",
+      "department.id",
+    );
+    const cloned = original
+      .clone()
+      .ensureJoin({ department: "departments" }, "users.department_id", "department.id")
+      .ensureJoin({ fallback: "departments" }, "users.id", "fallback.id");
+
+    expect(original.toQuery()).not.toContain('as "fallback"');
+    expect(cloned.toQuery()).toContain('as "fallback"');
+    expect(cloned.toQuery().match(/join "departments" as "department"/g)).toHaveLength(1);
+  });
+
+  it("JOIN을 clear한 뒤 같은 alias를 다시 등록할 수 있다", () => {
+    const query = usersQuery()
+      .ensureJoin({ department: "departments" }, "users.department_id", "department.id")
+      .clear("join")
+      .ensureJoin({ department: "departments" }, "users.department_id", "department.id");
+
+    expect(query.toQuery().match(/join "departments" as "department"/g)).toHaveLength(1);
+  });
+
+  it("clearJoin으로 삭제한 alias를 다시 등록할 수 있다", () => {
+    const query = usersQuery()
+      .ensureJoin({ department: "departments" }, "users.department_id", "department.id")
+      .clearJoin("department")
+      .ensureJoin({ department: "departments" }, "users.department_id", "department.id");
+
+    expect(query.toQuery().match(/join "departments" as "department"/g)).toHaveLength(1);
+  });
+
+  it("clearJoin은 subquery JOIN의 registry도 함께 제거한다", () => {
+    const departmentIds = new Puri<
+      TestSchema,
+      { departments: TestSchema["departments"] },
+      TestSchema["departments"]
+    >(db, "departments").select({ id: "departments.id" });
+    const query = usersQuery()
+      .join({ department: departmentIds }, "users.department_id", "department.id")
+      .clearJoin("department")
+      .ensureJoin({ department: "departments" }, "users.department_id", "department.id");
+
+    expect(query.toQuery()).not.toContain('select "id" from "departments"');
+    expect(query.toQuery().match(/join "departments" as "department"/g)).toHaveLength(1);
+  });
+});

package/src/database/knex.ts

@@ -12,14 +12,17 @@ export function createKnexInstance(config: Knex.Config): Knex {
   }
 
   config.pool = {
+    // 아래는 기본값이며, 호출측이 config.pool로 덮어쓸 수 있다.
+    // (예: 마이그레이션 상태 조회는 fail-fast를 위해 짧은 타임아웃 + propagateCreateError를 지정)
     maxConnectionLifetimeMillis: 1800000,
     maxConnectionLifetimeJitterMillis: 300000,
-    ...config.pool,
     propagateCreateError: false,
     idleTimeoutMillis: 10000,
     reapIntervalMillis: 1000,
     acquireTimeoutMillis: 30000,
     createTimeoutMillis: 30000,
+    ...config.pool,
+    // validate/afterCreate는 항상 프레임워크 기본값을 사용한다.
     validate: (connection: unknown) => {
       if (typeof connection !== "object" || connection === null) return false;
       const conn = connection as Record<string, unknown>;

package/src/database/puri.ts

@@ -61,6 +61,24 @@ type PuriOrderByRuntimeItem = {
 };
 type PuriOrderByRuntimeEntry = string | PuriOrderByExpression | PuriOrderByRuntimeItem;
 
+type FromRegistration = {
+  kind: "from";
+  alias: string;
+  table: string | null;
+};
+
+type JoinRegistration = {
+  kind: "join";
+  alias: string;
+  table: string | null;
+  joinType: "join" | "leftJoin";
+  left: string | null;
+  right: string | null;
+  reusable: boolean;
+};
+
+type CorrelationRegistration = FromRegistration | JoinRegistration;
+
 function normalizeFuzzyOperator(operator?: string): FuzzyOperator {
   const normalized = operator?.trim() ?? "<%";
   const fuzzyOperator = FUZZY_OPERATORS.find((candidate) => candidate === normalized);
@@ -123,6 +141,7 @@ function isSqlExpression(value: PuriOrderByRuntimeEntry): value is PuriOrderByEx
 export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
   private knexQuery: Knex.QueryBuilder;
   private tableSpec: TableSpec | null = null;
+  private correlationRegistry = new Map<string, CorrelationRegistration>();
 
   // 생성자 시그니처들
   constructor(knex: Knex, tableName: string);
@@ -135,6 +154,11 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
       // Case: new Puri(knex, "users")
       this.knexQuery = this.knex(tableNameOrSource).from(tableNameOrSource);
       this.tableSpec = this.safeGetTableSpec(tableNameOrSource);
+      this.correlationRegistry.set(tableNameOrSource, {
+        kind: "from",
+        alias: tableNameOrSource,
+        table: tableNameOrSource,
+      });
     } else if (typeof tableNameOrSource === "object") {
       const entries = Object.entries(tableNameOrSource);
       if (entries.length !== 1) {
@@ -145,9 +169,11 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
       if (typeof source === "string") {
         this.knexQuery = this.knex(source).from({ [alias]: source });
         this.tableSpec = this.safeGetTableSpec(source);
+        this.correlationRegistry.set(alias, { kind: "from", alias, table: source });
       } else if (source instanceof Puri) {
         const subqueryBuilder = source.rawQuery();
         this.knexQuery = this.knex.from(subqueryBuilder.as(alias));
+        this.correlationRegistry.set(alias, { kind: "from", alias, table: null });
       } else {
         throw new Error("Invalid table specification");
       }
@@ -559,19 +585,27 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
   // CLEAR
   clear(statement: ClearStatements): this {
     this.knexQuery.clear(statement);
+    if (statement === "join") {
+      this.clearJoinRegistrations();
+    }
     return this;
   }
 
   // knex에 없어서 직접 구현함
   clearJoin(alias: string): this {
+    let removed = false;
     (this.knexQuery as any)._statements = (this.knexQuery as any)._statements.filter((s: any) => {
       if ("joinType" in s) {
-        const [_alias, _table] = Object.entries(s.table)[0];
-        return _alias !== alias;
+        const shouldRemove = this.getKnexJoinAlias(s.table) === alias;
+        removed ||= shouldRemove;
+        return !shouldRemove;
       } else {
         return true;
       }
     });
+    if (removed && this.correlationRegistry.get(alias)?.kind === "join") {
+      this.correlationRegistry.delete(alias);
+    }
     return this;
   }
 
@@ -625,6 +659,22 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
     return this.__commonJoin("join", tableNameOrSpec, ...args);
   }
 
+  // ENSURE JOIN: 테이블 + Alias
+  ensureJoin<TJoinTable extends keyof TSchema, TJoinAlias extends string>(
+    tableSpec: { [K in TJoinAlias]: TJoinTable },
+    left: AvailableColumns<TTables>,
+    right: `${TJoinAlias}.${ColumnKeys<TSchema[TJoinTable]>}`,
+  ): Puri<TSchema, TTables & Record<TJoinAlias, TSchema[TJoinTable]>, TResult>;
+  // ENSURE JOIN: 테이블명
+  ensureJoin<TJoinTable extends keyof TSchema>(
+    tableName: TJoinTable,
+    left: AvailableColumns<TTables>,
+    right: `${TJoinTable & string}.${ColumnKeys<TSchema[TJoinTable]>}`,
+  ): Puri<TSchema, TTables & Record<TJoinTable, TSchema[TJoinTable]>, TResult>;
+  ensureJoin(tableNameOrSpec: any, left: string, right: string): any {
+    return this.__ensureJoin("join", tableNameOrSpec, left, right);
+  }
+
   // LEFT JOIN: 서브쿼리 + Alias
   leftJoin<TJoinAlias extends string, TSubResult>(
     tableSpec: { [K in TJoinAlias]: Puri<TSchema, any, TSubResult> },
@@ -676,7 +726,38 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
     return this.__commonJoin("leftJoin", tableNameOrSpec, ...args);
   }
 
+  // ENSURE LEFT JOIN: 테이블 + Alias
+  ensureLeftJoin<
+    TJoinTable extends keyof TSchema,
+    TJoinAlias extends string,
+    TLeft extends AvailableColumns<TTables>,
+  >(
+    tableSpec: { [K in TJoinAlias]: TJoinTable },
+    left: TLeft,
+    right: `${TJoinAlias}.${ColumnKeys<TSchema[TJoinTable]>}`,
+  ): Puri<
+    TSchema,
+    TTables & Record<TJoinAlias, TSchema[TJoinTable] & LeftJoinMarkerFor<TTables, TLeft>>,
+    TResult
+  >;
+  // ENSURE LEFT JOIN: 테이블명
+  ensureLeftJoin<TJoinTable extends keyof TSchema, TLeft extends AvailableColumns<TTables>>(
+    tableName: TJoinTable,
+    left: TLeft,
+    right: `${TJoinTable & string}.${ColumnKeys<TSchema[TJoinTable]>}`,
+  ): Puri<
+    TSchema,
+    TTables & Record<TJoinTable, TSchema[TJoinTable] & LeftJoinMarkerFor<TTables, TLeft>>,
+    TResult
+  >;
+  ensureLeftJoin(tableNameOrSpec: any, left: string, right: string): any {
+    return this.__ensureJoin("leftJoin", tableNameOrSpec, left, right);
+  }
+
   __commonJoin(joinType: "join" | "leftJoin", tableNameOrSpec: any, ...args: any[]): this {
+    const registration = this.createJoinRegistration(joinType, tableNameOrSpec, args);
+    this.assertCorrelationAvailable(registration);
+
     if (typeof tableNameOrSpec === "string") {
       // Case 1: join("posts", ...)
       const tableName = tableNameOrSpec;
@@ -734,9 +815,154 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
       throw new Error("Invalid arguments");
     }
 
+    this.correlationRegistry.set(registration.alias, registration);
     return this;
   }
 
+  private __ensureJoin(
+    joinType: "join" | "leftJoin",
+    tableNameOrSpec: string | Record<string, string>,
+    left: string,
+    right: string,
+  ): this {
+    const requested = this.createJoinRegistration(joinType, tableNameOrSpec, [left, right]);
+    if (!requested.reusable) {
+      throw new Error(
+        `${joinType === "join" ? "ensureJoin" : "ensureLeftJoin"} only supports physical tables with simple column equality conditions.`,
+      );
+    }
+    const existing = this.correlationRegistry.get(requested.alias);
+
+    if (!existing) {
+      return this.__commonJoin(joinType, tableNameOrSpec, left, right);
+    }
+
+    if (this.isSameJoinRegistration(existing, requested)) {
+      return this;
+    }
+
+    throw this.createJoinConflictError(existing, requested);
+  }
+
+  private createJoinRegistration(
+    joinType: "join" | "leftJoin",
+    tableNameOrSpec: any,
+    args: any[],
+  ): JoinRegistration {
+    let alias: string;
+    let table: string | null;
+
+    if (typeof tableNameOrSpec === "string") {
+      alias = tableNameOrSpec;
+      table = tableNameOrSpec;
+    } else if (typeof tableNameOrSpec === "object") {
+      const entries = Object.entries(tableNameOrSpec);
+      if (entries.length !== 1) {
+        throw new Error("Table spec must have exactly one entry");
+      }
+      assert(entries[0]);
+      const [[joinAlias, spec]] = entries;
+      alias = joinAlias;
+      table = typeof spec === "string" ? spec : null;
+    } else {
+      throw new Error("Invalid arguments");
+    }
+
+    const [left, right] = args;
+    const reusable =
+      table !== null && args.length === 2 && typeof left === "string" && typeof right === "string";
+
+    return {
+      kind: "join",
+      alias,
+      table,
+      joinType,
+      left: reusable ? left : null,
+      right: reusable ? right : null,
+      reusable,
+    };
+  }
+
+  private assertCorrelationAvailable(requested: JoinRegistration): void {
+    const existing = this.correlationRegistry.get(requested.alias);
+    if (existing) {
+      if (this.isSameJoinRegistration(existing, requested)) {
+        throw new Error(
+          `Join alias "${requested.alias}" is already registered. Use ensureJoin() or ensureLeftJoin() to reuse an identical join.`,
+        );
+      }
+      throw this.createJoinConflictError(existing, requested);
+    }
+  }
+
+  private isSameJoinRegistration(
+    existing: CorrelationRegistration,
+    requested: JoinRegistration,
+  ): existing is JoinRegistration {
+    return (
+      existing.kind === "join" &&
+      existing.reusable &&
+      requested.reusable &&
+      existing.table === requested.table &&
+      existing.joinType === requested.joinType &&
+      existing.left === requested.left &&
+      existing.right === requested.right
+    );
+  }
+
+  private createJoinConflictError(
+    existing: CorrelationRegistration,
+    requested: JoinRegistration,
+  ): Error {
+    return new Error(
+      [
+        `Join alias "${requested.alias}" is already registered with a different definition.`,
+        `Existing: ${this.formatCorrelationRegistration(existing)}`,
+        `Requested: ${this.formatCorrelationRegistration(requested)}`,
+      ].join("\n"),
+    );
+  }
+
+  private formatCorrelationRegistration(registration: CorrelationRegistration): string {
+    if (registration.kind === "from") {
+      return `FROM ${registration.table ?? "subquery"} AS ${registration.alias}`;
+    }
+
+    const joinKeyword = registration.joinType === "join" ? "JOIN" : "LEFT JOIN";
+    const source = registration.table ?? "opaque source";
+    const condition = registration.reusable
+      ? ` ON ${registration.left} = ${registration.right}`
+      : " with opaque condition";
+    return `${joinKeyword} ${source} AS ${registration.alias}${condition}`;
+  }
+
+  private clearJoinRegistrations(): void {
+    for (const [alias, registration] of this.correlationRegistry) {
+      if (registration.kind === "join") {
+        this.correlationRegistry.delete(alias);
+      }
+    }
+  }
+
+  private getKnexJoinAlias(table: unknown): string | null {
+    if (typeof table === "string") {
+      return table;
+    }
+    if (typeof table === "object" && table !== null) {
+      if (
+        "_single" in table &&
+        typeof table._single === "object" &&
+        table._single !== null &&
+        "as" in table._single &&
+        typeof table._single.as === "string"
+      ) {
+        return table._single.as;
+      }
+      return Object.keys(table)[0] ?? null;
+    }
+    return null;
+  }
+
   // WHERE: 객체 - 사용: .where({ "u.id": 1, "u.status": "active" })
   where(conditions: WhereCondition<TTables>): this;
   // WHERE: 컬럼 - 사용: .where("u.id", 1), .where("u.id", null)
@@ -1278,6 +1504,7 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
     // 'dual'은 더미 테이블이며, 바로 아래 줄에서 knexQuery가 덮어씌워집니다.
     const newPuri = new Puri<TSchema, TTables, TResult>(this.knex, "dual");
     newPuri.knexQuery = this.knexQuery.clone();
+    newPuri.correlationRegistry = new Map(this.correlationRegistry);
     return newPuri;
   }
 

package/src/database/puri.types.test-d.ts

@@ -661,3 +661,59 @@ describe("Puri orderBy methods", () => {
     query.orderBy(["name", "missing_column"]);
   });
 });
+
+describe("Puri ensureJoin methods", () => {
+  it("ensureJoin 이후 alias 컬럼을 타입 안전하게 사용할 수 있다", () => {
+    type Query = Puri<MockSchema, { users: MockSchema["users"] }, MockSchema["users"]>;
+    const query = {} as Query;
+
+    const joined = query.ensureJoin(
+      { department: "departments" },
+      "users.department_id",
+      "department.id",
+    );
+
+    expectTypeOf(joined.where("department.name", "개발팀")).toEqualTypeOf(joined);
+
+    // @ts-expect-error JOIN한 테이블에 없는 컬럼은 사용할 수 없다.
+    joined.where("department.email", "dev@example.com");
+  });
+
+  it("ensureLeftJoin은 nullable FK의 객체 타입을 유지한다", () => {
+    type Query = Puri<MockSchema, { users: MockSchema["users"] }, MockSchema["users"]>;
+    const query = {} as Query;
+
+    const result = query
+      .ensureLeftJoin({ department: "departments" }, "users.department_id", "department.id")
+      .select({ department: { id: "department.id" } })
+      .first();
+
+    expectTypeOf(result).resolves.toEqualTypeOf<{
+      department: { id: number } | null;
+    }>();
+  });
+
+  it("ensureLeftJoin은 non-null FK의 객체를 non-null로 추론한다", () => {
+    type Query = Puri<MockSchema, { employees: MockSchema["employees"] }, MockSchema["employees"]>;
+    const query = {} as Query;
+
+    const result = query
+      .ensureLeftJoin({ user: "users" }, "employees.user_id", "user.id")
+      .select({ user: { id: "user.id" } })
+      .first();
+
+    expectTypeOf(result).resolves.toEqualTypeOf<{
+      user: { id: number };
+    }>();
+  });
+
+  it("ensureJoin은 callback 형식을 허용하지 않는다", () => {
+    type Query = Puri<MockSchema, { users: MockSchema["users"] }, MockSchema["users"]>;
+    const query = {} as Query;
+
+    // @ts-expect-error callback JOIN은 동일성을 판정할 수 없으므로 지원하지 않는다.
+    query.ensureJoin({ department: "departments" }, (join) => {
+      join.on("users.department_id", "department.id");
+    });
+  });
+});

package/src/migration/code-generation.ts

@@ -757,7 +757,7 @@ async function generateCreateCode_ColumnAndIndexes(
 
   // 컬럼, 인덱스 처리
   const lines: string[] = [
-    'import { Knex } from "knex";',
+    'import type { Knex } from "knex";',
     "",
     "export async function up(knex: Knex): Promise<void> {",
     ...helperDefinitions,
@@ -1083,7 +1083,7 @@ async function generateCreateCode_Foreign(
   }
 
   const lines: string[] = [
-    'import { Knex } from "knex";',
+    'import type { Knex } from "knex";',
     "",
     "export async function up(knex: Knex): Promise<void> {",
     `return knex.schema.alterTable("${table}", (table) => {`,
@@ -1304,7 +1304,7 @@ async function generateAlterCode_ColumnAndIndexes(
   ];
 
   const lines: string[] = [
-    'import { Knex } from "knex";',
+    'import type { Knex } from "knex";',
     "",
     "export async function up(knex: Knex): Promise<void> {",
     ...(upBuilderLines.length > 0
@@ -1776,7 +1776,7 @@ async function generateAlterCode_Foreigns(
   }
 
   const lines: string[] = [
-    'import { Knex } from "knex";',
+    'import type { Knex } from "knex";',
     "",
     "export async function up(knex: Knex): Promise<void> {",
     `return knex.schema.alterTable("${table}", (table) => {`,
@@ -2104,7 +2104,7 @@ async function generatePkTypeChangeMigration(
   }
 
   const lines: string[] = [
-    'import { Knex } from "knex";',
+    'import type { Knex } from "knex";',
     "",
     "export async function up(knex: Knex): Promise<void> {",
     ...upLines,