swallowkit 1.0.0-beta.6 → 1.0.0-beta.60

package/src/core/verify/index.ts

@@ -0,0 +1,468 @@
+/**
+ * Verify — 生成後の検証チェックを実行し、機械可読な結果を返す。
+ *
+ * 提供チェック:
+ * - structure:  プロジェクト構造規約 (validateProject)
+ * - drift:      生成物と現在状態の乖離 (detectDrift)
+ * - typecheck:  TypeScript 型チェック (tsc --noEmit / typecheck script)
+ * - build/lint/test: package.json scripts に同名 script がある場合のみ実行 (なければ skip)
+ * - custom:     swallowkit.config の verify.checks で定義されたプロジェクト固有チェック
+ *
+ * 既定実行セットは structure/drift/typecheck + custom。build/lint/test は --checks で明示指定。
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { spawnSync } from "child_process";
+import { loadConfig } from "../config";
+import { detectDrift, DriftFinding } from "../project/drift";
+import { saveLastVerifyState } from "../project/state";
+import { ProjectViolation, validateProject } from "../project/validation";
+import { CustomVerifyCheck } from "../../types";
+import { detectFromProject, getCommands } from "../../utils/package-manager";
+
+export type VerifyCheckStatus = "pass" | "fail" | "skip" | "error";
+
+export interface VerifyCheckEvidence {
+  command?: string;
+  exitCode?: number;
+  violations?: ProjectViolation[];
+  findings?: DriftFinding[];
+  logTail?: string[];
+  /** --compact で抑制された info-severity findings の件数。 */
+  suppressedInfoFindings?: number;
+}
+
+export interface VerifyCheckResult {
+  id: string;
+  title: string;
+  status: VerifyCheckStatus;
+  durationMs: number;
+  fixable: boolean;
+  evidence: VerifyCheckEvidence;
+  suggestedActions: string[];
+}
+
+export interface VerifySummary {
+  passed: number;
+  failed: number;
+  skipped: number;
+  errors: number;
+  /** true = すべてのチェックが pass または skip */
+  done: boolean;
+}
+
+export interface VerifyResult {
+  checks: VerifyCheckResult[];
+  summary: VerifySummary;
+  verifiedAt: string;
+}
+
+export const AVAILABLE_VERIFY_CHECKS = ["structure", "drift", "typecheck", "build", "lint", "test"] as const;
+export type VerifyCheckId = (typeof AVAILABLE_VERIFY_CHECKS)[number];
+
+/** 既定で実行される built-in チェック。build/lint/test は明示指定時のみ。 */
+export const DEFAULT_VERIFY_CHECKS = ["structure", "drift", "typecheck"] as const;
+
+async function runStructureCheck(projectRoot: string): Promise<VerifyCheckResult> {
+  const startedAt = Date.now();
+  try {
+    const result = await validateProject(projectRoot);
+    const errors = result.violations.filter((violation) => violation.severity === "error");
+    return {
+      id: "structure",
+      title: "Project structure conventions",
+      status: errors.length === 0 ? "pass" : "fail",
+      durationMs: Date.now() - startedAt,
+      fixable: true,
+      evidence: { violations: result.violations },
+      suggestedActions:
+        errors.length === 0
+          ? []
+          : errors.map((violation) => violation.suggestedFix ?? violation.message),
+    };
+  } catch (error) {
+    return {
+      id: "structure",
+      title: "Project structure conventions",
+      status: "error",
+      durationMs: Date.now() - startedAt,
+      fixable: false,
+      evidence: { logTail: [error instanceof Error ? error.message : String(error)] },
+      suggestedActions: ["Run this command inside a SwallowKit project root."],
+    };
+  }
+}
+
+async function runDriftCheck(projectRoot: string): Promise<VerifyCheckResult> {
+  const startedAt = Date.now();
+  try {
+    const result = await detectDrift(projectRoot);
+    const errors = result.findings.filter((finding) => finding.severity === "error");
+    return {
+      id: "drift",
+      title: "Generated artifact drift",
+      status: errors.length === 0 ? "pass" : "fail",
+      durationMs: Date.now() - startedAt,
+      fixable: true,
+      evidence: { findings: result.findings },
+      suggestedActions: errors.map((finding) => finding.repairAction),
+    };
+  } catch (error) {
+    return {
+      id: "drift",
+      title: "Generated artifact drift",
+      status: "error",
+      durationMs: Date.now() - startedAt,
+      fixable: false,
+      evidence: { logTail: [error instanceof Error ? error.message : String(error)] },
+      suggestedActions: [],
+    };
+  }
+}
+
+function tailLines(text: string, count: number): string[] {
+  return text
+    .split(/\r?\n/)
+    .filter((line) => line.trim().length > 0)
+    .slice(-count);
+}
+
+interface CommandCheckSpec {
+  id: string;
+  title: string;
+  command: string;
+  args: string[];
+  timeoutMs?: number;
+  failAction: string;
+}
+
+function runCommandCheck(projectRoot: string, spec: CommandCheckSpec): VerifyCheckResult {
+  const startedAt = Date.now();
+  const commandLabel = [spec.command, ...spec.args].join(" ").trim();
+  try {
+    const result = spawnSync(spec.command, spec.args, {
+      cwd: projectRoot,
+      shell: true,
+      encoding: "utf-8",
+      timeout: spec.timeoutMs ?? 5 * 60 * 1000,
+    });
+
+    const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
+    const exitCode = typeof result.status === "number" ? result.status : -1;
+
+    if (result.error) {
+      return {
+        id: spec.id,
+        title: spec.title,
+        status: "error",
+        durationMs: Date.now() - startedAt,
+        fixable: false,
+        evidence: { command: commandLabel, logTail: [result.error.message] },
+        suggestedActions: [`Ensure "${commandLabel}" can run in this project.`],
+      };
+    }
+
+    return {
+      id: spec.id,
+      title: spec.title,
+      status: exitCode === 0 ? "pass" : "fail",
+      durationMs: Date.now() - startedAt,
+      fixable: true,
+      evidence: {
+        command: commandLabel,
+        exitCode,
+        logTail: tailLines(output, 50),
+      },
+      suggestedActions: exitCode === 0 ? [] : [spec.failAction],
+    };
+  } catch (error) {
+    return {
+      id: spec.id,
+      title: spec.title,
+      status: "error",
+      durationMs: Date.now() - startedAt,
+      fixable: false,
+      evidence: { command: commandLabel, logTail: [error instanceof Error ? error.message : String(error)] },
+      suggestedActions: [],
+    };
+  }
+}
+
+function readPackageScripts(projectRoot: string): Record<string, string> {
+  const packageJsonPath = path.join(projectRoot, "package.json");
+  if (!fs.existsSync(packageJsonPath)) return {};
+  try {
+    const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8")) as { scripts?: Record<string, string> };
+    return pkg.scripts ?? {};
+  } catch {
+    return {};
+  }
+}
+
+function runTypecheckCheck(projectRoot: string): VerifyCheckResult {
+  const startedAt = Date.now();
+
+  if (!fs.existsSync(path.join(projectRoot, "tsconfig.json"))) {
+    return {
+      id: "typecheck",
+      title: "TypeScript type check",
+      status: "skip",
+      durationMs: Date.now() - startedAt,
+      fixable: false,
+      evidence: { logTail: ["tsconfig.json not found; skipping typecheck."] },
+      suggestedActions: [],
+    };
+  }
+
+  // typecheck は shared のビルド済み dist/ を参照する。古い dist による
+  // 「no exported member」誤検知を防ぐため、先に shared をビルドする。
+  const sharedBuild = runSharedBuildIfPresent(projectRoot);
+  if (sharedBuild.ran && !sharedBuild.ok) {
+    return {
+      id: "typecheck",
+      title: "TypeScript type check",
+      status: "fail",
+      durationMs: Date.now() - startedAt,
+      fixable: true,
+      evidence: { command: sharedBuild.command, logTail: sharedBuild.logTail },
+      suggestedActions: [
+        "Fix the shared package build errors first; typecheck resolves the shared package from its built dist/.",
+      ],
+    };
+  }
+
+  const scripts = readPackageScripts(projectRoot);
+  let command: string;
+  let args: string[];
+  if (typeof scripts.typecheck === "string") {
+    const pm = detectFromProject(projectRoot);
+    command = getCommands(pm).name;
+    args = ["run", "typecheck"];
+  } else {
+    command = "npx";
+    args = ["tsc", "--noEmit"];
+  }
+
+  return runCommandCheck(projectRoot, {
+    id: "typecheck",
+    title: "TypeScript type check",
+    command,
+    args,
+    failAction: "Fix the TypeScript errors listed in evidence.logTail, then re-run verify.",
+  });
+}
+
+const SCRIPT_CHECK_TITLES: Record<string, string> = {
+  build: "Project build",
+  lint: "Lint",
+  test: "Test suite",
+};
+
+interface SharedBuildOutcome {
+  ran: boolean;
+  ok: boolean;
+  command?: string;
+  logTail?: string[];
+}
+
+/** shared/package.json に build script があれば実行する (なければ no-op)。 */
+function runSharedBuildIfPresent(projectRoot: string): SharedBuildOutcome {
+  const sharedPackageJsonPath = path.join(projectRoot, "shared", "package.json");
+  if (!fs.existsSync(sharedPackageJsonPath)) return { ran: false, ok: true };
+  try {
+    const pkg = JSON.parse(fs.readFileSync(sharedPackageJsonPath, "utf-8")) as { scripts?: Record<string, string> };
+    if (typeof pkg.scripts?.build !== "string") return { ran: false, ok: true };
+  } catch {
+    return { ran: false, ok: true };
+  }
+
+  const pm = detectFromProject(projectRoot);
+  const command = getCommands(pm).name;
+  const result = spawnSync(command, ["run", "build"], {
+    cwd: path.join(projectRoot, "shared"),
+    shell: true,
+    encoding: "utf-8",
+    timeout: 5 * 60 * 1000,
+  });
+  const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
+  const ok = result.status === 0 && !result.error;
+  return {
+    ran: true,
+    ok,
+    command: `${command} run build (in shared/)`,
+    logTail: ok ? undefined : tailLines(result.error ? `${output}\n${result.error.message}` : output, 50),
+  };
+}
+
+function runScriptCheck(projectRoot: string, scriptName: "build" | "lint" | "test"): VerifyCheckResult {
+  const startedAt = Date.now();
+  const scripts = readPackageScripts(projectRoot);
+  const title = SCRIPT_CHECK_TITLES[scriptName];
+
+  if (typeof scripts[scriptName] !== "string") {
+    return {
+      id: scriptName,
+      title,
+      status: "skip",
+      durationMs: Date.now() - startedAt,
+      fixable: false,
+      evidence: { logTail: [`No "${scriptName}" script in package.json; skipping.`] },
+      suggestedActions: [],
+    };
+  }
+
+  const pm = detectFromProject(projectRoot);
+  return runCommandCheck(projectRoot, {
+    id: scriptName,
+    title,
+    command: getCommands(pm).name,
+    args: ["run", scriptName],
+    timeoutMs: 10 * 60 * 1000,
+    failAction: `Fix the ${scriptName} failures listed in evidence.logTail, then re-run verify.`,
+  });
+}
+
+const CUSTOM_CHECK_ID = /^[a-z][a-z0-9-]*$/;
+
+/** swallowkit.config の verify.checks を projectRoot 基準で静かに読み込む。 */
+export function loadCustomVerifyChecks(projectRoot: string): CustomVerifyCheck[] {
+  const configNames = ["swallowkit.config.json", "swallowkit.config.js", ".swallowkitrc.json"];
+  for (const name of configNames) {
+    const configPath = path.join(projectRoot, name);
+    if (!fs.existsSync(configPath)) continue;
+    try {
+      const checks = loadConfig(configPath, false, true).verify?.checks ?? [];
+      return checks.filter(
+        (check) =>
+          typeof check?.id === "string" &&
+          CUSTOM_CHECK_ID.test(check.id) &&
+          !(AVAILABLE_VERIFY_CHECKS as readonly string[]).includes(check.id) &&
+          typeof check.command === "string" &&
+          check.command.trim().length > 0
+      );
+    } catch {
+      return [];
+    }
+  }
+  return [];
+}
+
+function runCustomCheck(projectRoot: string, check: CustomVerifyCheck): VerifyCheckResult {
+  return runCommandCheck(projectRoot, {
+    id: check.id,
+    title: check.title ?? `Custom check: ${check.id}`,
+    command: check.command,
+    args: [],
+    timeoutMs: check.timeoutMs,
+    failAction: `Fix the failures reported by "${check.command}", then re-run verify.`,
+  });
+}
+
+export async function runVerify(
+  checkIds?: string[],
+  projectRoot: string = process.cwd()
+): Promise<VerifyResult> {
+  const customChecks = loadCustomVerifyChecks(projectRoot);
+  const customIds = customChecks.map((check) => check.id);
+  const availableIds = [...AVAILABLE_VERIFY_CHECKS, ...customIds];
+
+  const requested = (checkIds && checkIds.length > 0
+    ? checkIds
+    : [...DEFAULT_VERIFY_CHECKS, ...customIds]
+  ).map((id) => id.trim()).filter(Boolean);
+
+  const unknown = requested.filter((id) => !availableIds.includes(id));
+  if (unknown.length > 0) {
+    throw new Error(
+      `Unknown verify check(s): ${unknown.join(", ")}. Available checks: ${availableIds.join(", ")}`
+    );
+  }
+
+  const checks: VerifyCheckResult[] = [];
+  for (const id of requested) {
+    if (id === "structure") {
+      checks.push(await runStructureCheck(projectRoot));
+    } else if (id === "drift") {
+      checks.push(await runDriftCheck(projectRoot));
+    } else if (id === "typecheck") {
+      checks.push(runTypecheckCheck(projectRoot));
+    } else if (id === "build" || id === "lint" || id === "test") {
+      checks.push(runScriptCheck(projectRoot, id));
+    } else {
+      const custom = customChecks.find((check) => check.id === id);
+      if (custom) checks.push(runCustomCheck(projectRoot, custom));
+    }
+  }
+
+  const summary: VerifySummary = {
+    passed: checks.filter((check) => check.status === "pass").length,
+    failed: checks.filter((check) => check.status === "fail").length,
+    skipped: checks.filter((check) => check.status === "skip").length,
+    errors: checks.filter((check) => check.status === "error").length,
+    done: checks.every((check) => check.status === "pass" || check.status === "skip"),
+  };
+
+  const result: VerifyResult = {
+    checks,
+    summary,
+    verifiedAt: new Date().toISOString(),
+  };
+
+  saveLastVerifyState(result, projectRoot);
+  return result;
+}
+
+/**
+ * Agent 消費向けに info-severity の drift findings (「user-owned が編集されたが想定内」等)
+ * を除去したコンパクトな結果を返す。判定 (summary) は変わらない。
+ */
+export function compactVerifyResult(result: VerifyResult): VerifyResult {
+  return {
+    ...result,
+    checks: result.checks.map((check) => {
+      const findings = check.evidence.findings;
+      if (!findings || findings.length === 0) return check;
+      const kept = findings.filter((finding) => finding.severity !== "info");
+      const suppressed = findings.length - kept.length;
+      if (suppressed === 0) return check;
+      return {
+        ...check,
+        evidence: { ...check.evidence, findings: kept, suppressedInfoFindings: suppressed },
+      };
+    }),
+  };
+}
+
+export interface FailureExplanation {
+  checkId: string;
+  title: string;
+  status: VerifyCheckStatus;
+  verifiedAt: string;
+  evidence: VerifyCheckEvidence;
+  suggestedActions: string[];
+}
+
+export function explainVerifyFailure(
+  lastVerify: VerifyResult,
+  checkId?: string
+): FailureExplanation[] {
+  const targets = checkId
+    ? lastVerify.checks.filter((check) => check.id === checkId)
+    : lastVerify.checks.filter((check) => check.status === "fail" || check.status === "error");
+
+  if (checkId && targets.length === 0) {
+    throw new Error(
+      `Unknown check "${checkId}" in the last verify result. Available: ${lastVerify.checks.map((check) => check.id).join(", ")}`
+    );
+  }
+
+  return targets.map((check) => ({
+    checkId: check.id,
+    title: check.title,
+    status: check.status,
+    verifiedAt: lastVerify.verifiedAt,
+    evidence: check.evidence,
+    suggestedActions: check.suggestedActions,
+  }));
+}

package/src/database/base-model.ts

@@ -0,0 +1,184 @@
+import { z } from "zod";
+import { getDatabaseClient } from "./client.js";
+import { ensureServerSide } from "./runtime-check.js";
+
+/**
+ * @deprecated BaseModel is deprecated and will be removed in a future version.
+ * 
+ * Instead of using BaseModel, define your models as pure Zod schemas:
+ * 
+ * @example
+ * ```typescript
+ * // shared/models/user.ts
+ * import { z } from 'zod';
+ * 
+ * export const userSchema = z.object({
+ *   id: z.string(),
+ *   email: z.string().email(),
+ *   name: z.string(),
+ * });
+ * 
+ * export type UserType = z.infer<typeof userSchema>;
+ * ```
+ * 
+ * Then use the scaffold command to generate CRUD operations:
+ * ```bash
+ * npx swallowkit scaffold shared/models/user.ts
+ * ```
+ * 
+ * This will generate:
+ * - Azure Functions with Cosmos DB bindings
+ * - Next.js BFF API routes
+ * - Type-safe React components
+ * 
+ * Use the generated API from frontend:
+ * ```typescript
+ * import { api } from '@/lib/api/backend';
+ * import type { UserType } from '@myapp/shared';
+ * 
+ * const users = await api.get<UserType[]>('/api/users');
+ * await api.post<UserType>('/api/users', { email: 'test@example.com', name: 'Test' });
+ * ```
+ */
+export abstract class BaseModel {
+  /**
+   * Zod スキーマ（サブクラスで定義）
+   */
+  static schema: z.ZodObject<any>;
+
+  /**
+   * Cosmos DB コンテナ名（サブクラスで定義）
+   */
+  static container: string;
+
+  /**
+   * パーティションキー（サブクラスで定義）
+   * @example "/email" or "/id"
+   */
+  static partitionKey: string;
+
+  /**
+   * データベースクライアントを取得
+   */
+  protected static getClient() {
+    return getDatabaseClient();
+  }
+
+  /**
+   * ドキュメントを作成
+   * @param data ドキュメントデータ
+   * @returns 作成されたドキュメント
+   */
+  static async create<T = any>(data: T): Promise<T> {
+    ensureServerSide(`${this.name}.create`);
+
+    // Zodスキーマでバリデーション
+    const validated = this.schema.parse(data);
+
+    const client = this.getClient();
+    const result = await client.createDocument(this.container, validated);
+    
+    return result as T;
+  }
+
+  /**
+   * ID でドキュメントを取得
+   * @param id ドキュメントID
+   * @returns ドキュメント（見つからない場合は null）
+   */
+  static async findById<T = any>(id: string): Promise<T | null> {
+    ensureServerSide(`${this.name}.findById`);
+
+    const client = this.getClient();
+    const result = await client.getDocument(this.container, id);
+    
+    if (!result) {
+      return null;
+    }
+
+    // Zodスキーマでバリデーション
+    return this.schema.parse(result) as T;
+  }
+
+  /**
+   * クエリでドキュメントを検索
+   * @param query SQL クエリの WHERE 句部分（省略時は全件取得）
+   * @param parameters クエリパラメータ
+   * @returns ドキュメントの配列
+   */
+  static async find<T = any>(query?: string, parameters?: any[]): Promise<T[]> {
+    ensureServerSide(`${this.name}.find`);
+
+    const client = this.getClient();
+    
+    const fullQuery = query 
+      ? `SELECT * FROM c WHERE ${query}`
+      : `SELECT * FROM c`;
+    
+    const results = await client.query(this.container, fullQuery, parameters);
+    
+    // 各ドキュメントをZodスキーマでバリデーション
+    return results.map((result) => this.schema.parse(result)) as T[];
+  }
+
+  /**
+   * ドキュメントを更新
+   * @param data 更新するドキュメントデータ（id フィールド必須）
+   * @returns 更新されたドキュメント
+   */
+  static async update<T = any>(data: T): Promise<T> {
+    ensureServerSide(`${this.name}.update`);
+
+    // Zodスキーマでバリデーション
+    const validated = this.schema.parse(data);
+
+    if (!(validated as any).id) {
+      throw new Error(`${this.name}.update requires an 'id' field`);
+    }
+
+    const client = this.getClient();
+    const result = await client.updateDocument(this.container, validated);
+    
+    return result as T;
+  }
+
+  /**
+   * ドキュメントを削除
+   * @param id ドキュメントID
+   */
+  static async delete(id: string): Promise<void> {
+    ensureServerSide(`${this.name}.delete`);
+
+    const client = this.getClient();
+    await client.deleteDocument(this.container, id);
+  }
+
+  /**
+   * カスタムクエリを実行
+   * @param query 完全な SQL クエリ
+   * @param parameters クエリパラメータ
+   * @returns ドキュメントの配列
+   */
+  static async query<T = any>(query: string, parameters?: any[]): Promise<T[]> {
+    ensureServerSide(`${this.name}.query`);
+
+    const client = this.getClient();
+    const results = await client.query(this.container, query, parameters);
+    
+    // 各ドキュメントをZodスキーマでバリデーション
+    return results.map((result) => this.schema.parse(result)) as T[];
+  }
+
+  /**
+   * Get the API resource name from container name
+   * Converts container name (e.g., "Todos", "Products") to resource path (e.g., "todos", "products")
+   * @returns Resource name in lowercase plural form
+   */
+  static getResourceName(): string {
+    if (!this.container) {
+      throw new Error(`${this.name} must define a static 'container' property`);
+    }
+    // Convert container name to lowercase (Todos -> todos, Products -> products)
+    return this.container.toLowerCase();
+  }
+}