@shirokuma-library/shirokuma-docs 0.1.0-alpha.5

package/portal/lib/db-schema-utils.ts

@@ -0,0 +1,182 @@
+/**
+ * Shared utilities for DB Schema pages
+ */
+
+// Category configuration with styling
+export const categoryConfig: Record<
+  string,
+  { label: string; color: string; bgColor: string }
+> = {
+  auth: {
+    label: "認証",
+    color: "text-blue-500",
+    bgColor: "bg-blue-100 dark:bg-blue-900/30",
+  },
+  authentication: {
+    label: "認証",
+    color: "text-blue-500",
+    bgColor: "bg-blue-100 dark:bg-blue-900/30",
+  },
+  content: {
+    label: "コンテンツ",
+    color: "text-green-500",
+    bgColor: "bg-green-100 dark:bg-green-900/30",
+  },
+  organization: {
+    label: "組織",
+    color: "text-purple-500",
+    bgColor: "bg-purple-100 dark:bg-purple-900/30",
+  },
+  organizations: {
+    label: "組織",
+    color: "text-purple-500",
+    bgColor: "bg-purple-100 dark:bg-purple-900/30",
+  },
+  project: {
+    label: "プロジェクト",
+    color: "text-amber-500",
+    bgColor: "bg-amber-100 dark:bg-amber-900/30",
+  },
+  projects: {
+    label: "プロジェクト",
+    color: "text-amber-500",
+    bgColor: "bg-amber-100 dark:bg-amber-900/30",
+  },
+  session: {
+    label: "セッション",
+    color: "text-cyan-500",
+    bgColor: "bg-cyan-100 dark:bg-cyan-900/30",
+  },
+  sessions: {
+    label: "セッション",
+    color: "text-cyan-500",
+    bgColor: "bg-cyan-100 dark:bg-cyan-900/30",
+  },
+  "work sessions": {
+    label: "セッション",
+    color: "text-cyan-500",
+    bgColor: "bg-cyan-100 dark:bg-cyan-900/30",
+  },
+  entity: {
+    label: "エンティティ",
+    color: "text-rose-500",
+    bgColor: "bg-rose-100 dark:bg-rose-900/30",
+  },
+  entities: {
+    label: "エンティティ",
+    color: "text-rose-500",
+    bgColor: "bg-rose-100 dark:bg-rose-900/30",
+  },
+  activity: {
+    label: "アクティビティ",
+    color: "text-indigo-500",
+    bgColor: "bg-indigo-100 dark:bg-indigo-900/30",
+  },
+  activities: {
+    label: "アクティビティ",
+    color: "text-indigo-500",
+    bgColor: "bg-indigo-100 dark:bg-indigo-900/30",
+  },
+  token: {
+    label: "トークン",
+    color: "text-orange-500",
+    bgColor: "bg-orange-100 dark:bg-orange-900/30",
+  },
+  tokens: {
+    label: "トークン",
+    color: "text-orange-500",
+    bgColor: "bg-orange-100 dark:bg-orange-900/30",
+  },
+  "mcp tokens": {
+    label: "トークン",
+    color: "text-orange-500",
+    bgColor: "bg-orange-100 dark:bg-orange-900/30",
+  },
+  context: {
+    label: "コンテキスト",
+    color: "text-teal-500",
+    bgColor: "bg-teal-100 dark:bg-teal-900/30",
+  },
+  "user context": {
+    label: "コンテキスト",
+    color: "text-teal-500",
+    bgColor: "bg-teal-100 dark:bg-teal-900/30",
+  },
+  other: {
+    label: "その他",
+    color: "text-gray-500",
+    bgColor: "bg-gray-100 dark:bg-gray-900/30",
+  },
+};
+
+// Normalize category name to standard format
+export function normalizeCategory(category: string | undefined): string {
+  if (!category) return "other";
+  const lower = category.toLowerCase();
+
+  // Map aliases to canonical names
+  if (lower === "authentication" || lower === "auth") return "auth";
+  if (lower === "organizations" || lower === "organization") return "organization";
+  if (lower === "projects" || lower === "project") return "project";
+  if (lower === "sessions" || lower === "session" || lower === "work sessions")
+    return "session";
+  if (lower === "entities" || lower === "entity") return "entity";
+  if (lower === "activities" || lower === "activity") return "activity";
+  if (lower === "tokens" || lower === "token" || lower === "mcp tokens")
+    return "token";
+  if (lower === "content" || lower === "contents") return "content";
+  if (lower === "user context" || lower === "context") return "context";
+
+  return lower in categoryConfig ? lower : "other";
+}
+
+// Infer category from table name
+export function inferCategory(tableName: string): string {
+  const name = tableName.toLowerCase();
+
+  if (
+    name.includes("user") ||
+    name.includes("session") ||
+    name.includes("account") ||
+    name.includes("verification")
+  ) {
+    return "auth";
+  }
+  if (name.includes("organization") || name.includes("member")) {
+    return "organization";
+  }
+  if (name.includes("project")) {
+    return "project";
+  }
+  if (name.includes("work_session") || name.includes("session_")) {
+    return "session";
+  }
+  if (name.includes("entity") || name.includes("entities")) {
+    return "entity";
+  }
+  if (name.includes("activity") || name.includes("activities")) {
+    return "activity";
+  }
+  if (name.includes("token")) {
+    return "token";
+  }
+  if (
+    name.includes("post") ||
+    name.includes("category") ||
+    name.includes("tag") ||
+    name.includes("comment")
+  ) {
+    return "content";
+  }
+  if (name.includes("context")) {
+    return "context";
+  }
+
+  return "other";
+}
+
+// Get category config with fallback
+export function getCategoryConfig(category: string) {
+  const normalized = normalizeCategory(category);
+  return categoryConfig[normalized] || categoryConfig.other;
+}

package/portal/lib/format.ts

@@ -0,0 +1,43 @@
+/**
+ * ポータル出力形式ユーティリティ
+ *
+ * PORTAL_FORMAT 環境変数からポータルの出力形式を取得
+ */
+
+/**
+ * ポータル出力形式
+ * - "card": カード形式（デフォルト・視覚的に分かりやすい）
+ * - "document": ドキュメント形式（テーブル・アコーディオン、情報密度が高い）
+ */
+export type PortalFormat = "card" | "document";
+
+/**
+ * ポータルの出力形式を取得
+ *
+ * ビルド時に PORTAL_FORMAT 環境変数から読み取り、
+ * 静的生成時にページに埋め込まれる
+ */
+export function getPortalFormat(): PortalFormat {
+  const format = process.env.PORTAL_FORMAT;
+
+  if (format === "document") {
+    return "document";
+  }
+
+  // デフォルトは card
+  return "card";
+}
+
+/**
+ * ドキュメント形式かどうかを判定
+ */
+export function isDocumentFormat(): boolean {
+  return getPortalFormat() === "document";
+}
+
+/**
+ * カード形式かどうかを判定
+ */
+export function isCardFormat(): boolean {
+  return getPortalFormat() === "card";
+}

package/portal/lib/hooks/use-hash-tab.ts

@@ -0,0 +1,144 @@
+/**
+ * useHashTab Hook
+ *
+ * Syncs tab state with URL hash for browser history support.
+ * Replaces duplicated logic in:
+ * - feature-map/feature-map-client.tsx
+ * - details/[type]/[module]/[item]/item-tabs-client.tsx
+ * - components/tabs-with-hash.tsx
+ */
+
+"use client";
+
+import { useState, useEffect, useCallback } from "react";
+
+export interface UseHashTabOptions {
+  /** Prefix for hash (e.g., "tab-" results in #tab-overview) */
+  hashPrefix?: string;
+  /** Use replaceState instead of pushState */
+  replaceState?: boolean;
+}
+
+export interface UseHashTabResult<T extends string> {
+  /** Currently active tab */
+  activeTab: T;
+  /** Whether component is mounted (for SSR hydration) */
+  mounted: boolean;
+  /** Handler for tab change */
+  handleTabChange: (value: string) => void;
+  /** Set tab without updating URL */
+  setActiveTabSilent: (value: T) => void;
+}
+
+/**
+ * Hook for syncing tab state with URL hash
+ *
+ * @param defaultTab - Default tab value when no hash is present
+ * @param validTabs - Array of valid tab values
+ * @param options - Optional configuration
+ * @returns Tab state and handlers
+ *
+ * @example
+ * const TABS = ["overview", "code", "tests"] as const;
+ * type TabType = typeof TABS[number];
+ *
+ * const { activeTab, mounted, handleTabChange } = useHashTab<TabType>(
+ *   "overview",
+ *   TABS
+ * );
+ *
+ * // Use with Tabs component
+ * <Tabs value={activeTab} onValueChange={handleTabChange}>
+ *   ...
+ * </Tabs>
+ */
+export function useHashTab<T extends string>(
+  defaultTab: T,
+  validTabs: readonly T[],
+  options: UseHashTabOptions = {}
+): UseHashTabResult<T> {
+  const { hashPrefix = "", replaceState = false } = options;
+  const [activeTab, setActiveTab] = useState<T>(defaultTab);
+  const [mounted, setMounted] = useState(false);
+
+  // Parse hash value to tab
+  const parseHash = useCallback(
+    (hash: string): T | null => {
+      // Remove # and prefix
+      let value = hash.slice(1);
+      if (hashPrefix && value.startsWith(hashPrefix)) {
+        value = value.slice(hashPrefix.length);
+      }
+      // Validate
+      if (validTabs.includes(value as T)) {
+        return value as T;
+      }
+      return null;
+    },
+    [hashPrefix, validTabs]
+  );
+
+  // Format tab to hash
+  const formatHash = useCallback(
+    (tab: T): string => {
+      return `#${hashPrefix}${tab}`;
+    },
+    [hashPrefix]
+  );
+
+  // Handle hash change event
+  useEffect(() => {
+    setMounted(true);
+
+    const handleHashChange = () => {
+      const hash = window.location.hash;
+      const tab = parseHash(hash);
+      if (tab) {
+        setActiveTab(tab);
+      }
+    };
+
+    // Set initial tab from hash
+    handleHashChange();
+
+    // Listen for hash changes (back/forward navigation)
+    window.addEventListener("hashchange", handleHashChange);
+    return () => window.removeEventListener("hashchange", handleHashChange);
+  }, [parseHash]);
+
+  // Handle tab change with URL update
+  const handleTabChange = useCallback(
+    (value: string) => {
+      if (!validTabs.includes(value as T)) return;
+
+      const tab = value as T;
+      setActiveTab(tab);
+
+      // Update URL hash
+      const hash = formatHash(tab);
+      if (replaceState) {
+        window.history.replaceState(null, "", hash);
+      } else {
+        window.history.pushState(null, "", hash);
+      }
+    },
+    [validTabs, formatHash, replaceState]
+  );
+
+  // Set tab without URL update (for programmatic control)
+  const setActiveTabSilent = useCallback(
+    (value: T) => {
+      if (validTabs.includes(value)) {
+        setActiveTab(value);
+      }
+    },
+    [validTabs]
+  );
+
+  return {
+    activeTab,
+    mounted,
+    handleTabChange,
+    setActiveTabSilent,
+  };
+}

package/portal/lib/path-utils.ts

@@ -0,0 +1,25 @@
+/**
+ * Utility functions for encoding/decoding file paths in URLs
+ *
+ * Problem: Nginx decodes %2F to / before matching files, so we can't use
+ * URL-encoded slashes in static file paths.
+ *
+ * Solution: Replace / with _SLASH_ for URL-safe file paths
+ * Note: Using _SLASH_ instead of __ because __tests__ directories contain __
+ */
+
+/**
+ * Encode a file path for use in URLs
+ * Replaces / with _SLASH_ to avoid Nginx decoding issues
+ */
+export function encodeFilePath(filePath: string): string {
+  return filePath.replace(/\//g, "_SLASH_");
+}
+
+/**
+ * Decode a URL-safe file path back to original
+ * Replaces _SLASH_ with /
+ */
+export function decodeFilePath(encodedPath: string): string {
+  return encodedPath.replace(/_SLASH_/g, "/");
+}

package/portal/lib/search-index-generator.ts

@@ -0,0 +1,214 @@
+/**
+ * Generate search index from documentation data
+ * This is used at build time to create a searchable index
+ */
+
+import type { SearchIndex, SearchItem } from "./search";
+import type {
+  FeatureMapData,
+  DbSchemaData,
+  TestCasesData,
+  DetailsData,
+} from "./types";
+
+/**
+ * Generate search index from all available data
+ */
+export function generateSearchIndex(
+  featureMap: FeatureMapData | null,
+  dbSchema: DbSchemaData | null,
+  testCases: TestCasesData | null,
+  details: DetailsData | null
+): SearchIndex {
+  const items: SearchItem[] = [];
+
+  // Index feature map items
+  if (featureMap) {
+    for (const [moduleName, group] of Object.entries(featureMap.features)) {
+      // Screens
+      for (const screen of group.screens || []) {
+        items.push({
+          id: `screen-${moduleName}-${screen.name}`,
+          title: screen.name,
+          description: screen.description || screen.descriptionEn || `${moduleName}モジュールの画面`,
+          category: "screen",
+          module: moduleName,
+          path: `/details/screens/${encodeURIComponent(moduleName)}/${encodeURIComponent(screen.name)}`,
+          keywords: [
+            screen.route || "",
+            ...(screen.components || []),
+            ...(screen.actions || []),
+          ].filter(Boolean),
+        });
+      }
+
+      // Components
+      for (const component of group.components || []) {
+        items.push({
+          id: `component-${moduleName}-${component.name}`,
+          title: component.name,
+          description: component.description || component.descriptionEn || `${moduleName}モジュールのコンポーネント`,
+          category: "component",
+          module: moduleName,
+          path: `/details/components/${encodeURIComponent(moduleName)}/${encodeURIComponent(component.name)}`,
+          keywords: component.props?.map((p) => p.name) || [],
+        });
+      }
+
+      // Actions
+      for (const action of group.actions || []) {
+        items.push({
+          id: `action-${moduleName}-${action.name}`,
+          title: action.name,
+          description: action.description || action.descriptionEn || `${moduleName}モジュールのServer Action`,
+          category: "action",
+          module: moduleName,
+          path: `/details/actions/${encodeURIComponent(moduleName)}/${encodeURIComponent(action.name)}`,
+          keywords: [
+            ...(action.params?.map((p) => p.name) || []),
+            ...(action.dbTables || []),
+          ],
+        });
+      }
+
+      // Tables (from feature map)
+      for (const table of group.tables || []) {
+        items.push({
+          id: `table-${moduleName}-${table.name}`,
+          title: table.name,
+          description: table.description || `${moduleName}モジュールのDBテーブル`,
+          category: "table",
+          module: moduleName,
+          path: `/details/tables/${encodeURIComponent(moduleName)}/${encodeURIComponent(table.name)}`,
+          keywords: table.columns?.map((c) => c.name) || [],
+        });
+      }
+    }
+
+    // Uncategorized items
+    const uncategorized = featureMap.uncategorized;
+    if (uncategorized) {
+      for (const screen of uncategorized.screens || []) {
+        items.push({
+          id: `screen-uncategorized-${screen.name}`,
+          title: screen.name,
+          description: screen.description || screen.descriptionEn || "未分類の画面",
+          category: "screen",
+          module: "Uncategorized",
+          path: `/details/screens/Uncategorized/${encodeURIComponent(screen.name)}`,
+          keywords: [screen.route || ""].filter(Boolean),
+        });
+      }
+      // ... similar for other uncategorized types
+    }
+  }
+
+  // Index DB schema tables
+  if (dbSchema) {
+    for (const table of dbSchema.tables) {
+      // Check if already indexed from feature map
+      const existingIndex = items.findIndex(
+        (item) => item.category === "table" && item.title === table.name
+      );
+
+      if (existingIndex === -1) {
+        items.push({
+          id: `db-${table.name}`,
+          title: table.name,
+          description: table.description || `${table.category || "データベース"}テーブル`,
+          category: "db",
+          module: table.category || undefined,
+          path: `/db-schema/${encodeURIComponent(table.name)}`,
+          keywords: [
+            ...(table.columns?.map((c) => c.name) || []),
+            ...(table.foreignKeys?.map((fk) => fk.references.table) || []),
+          ],
+        });
+      } else {
+        // Enhance existing entry with more keywords
+        const existing = items[existingIndex];
+        existing.keywords = [
+          ...existing.keywords,
+          ...(table.columns?.map((c) => c.name) || []),
+        ];
+        // Update path to db-schema page for richer info
+        existing.path = `/db-schema/${encodeURIComponent(table.name)}`;
+      }
+    }
+  }
+
+  // Index test cases (grouped by describe block)
+  if (testCases) {
+    const describeGroups = new Map<string, { tests: typeof testCases.testCases; firstTest: (typeof testCases.testCases)[0] }>();
+
+    for (const tc of testCases.testCases) {
+      const key = `${tc.file}:${tc.describe}`;
+      const existing = describeGroups.get(key);
+      if (existing) {
+        existing.tests.push(tc);
+      } else {
+        describeGroups.set(key, { tests: [tc], firstTest: tc });
+      }
+    }
+
+    for (const [key, { tests, firstTest }] of describeGroups) {
+      const fileName = firstTest.file.split("/").pop() || firstTest.file;
+      items.push({
+        id: `test-${key}`,
+        title: firstTest.describe,
+        description: `${fileName} (${tests.length}件のテスト)`,
+        category: "test",
+        path: `/test-cases#${encodeURIComponent(firstTest.file)}`,
+        keywords: [
+          firstTest.framework,
+          fileName,
+          ...tests.map((t) => t.it),
+        ],
+      });
+    }
+  }
+
+  // Add details data to enhance existing items
+  if (details) {
+    for (const [key, detail] of Object.entries(details.details)) {
+      const [type, moduleName, name] = key.split("/");
+      const existingIdx = items.findIndex(
+        (item) =>
+          item.title === name &&
+          item.module === moduleName &&
+          item.category === type
+      );
+
+      if (existingIdx !== -1) {
+        // Enhance with more keywords from details
+        const existing = items[existingIdx];
+        if (detail.jsDoc?.params) {
+          existing.keywords.push(...detail.jsDoc.params.map((p) => p.name));
+        }
+        if (detail.related?.usedInScreens) {
+          existing.keywords.push(...detail.related.usedInScreens);
+        }
+        if (detail.related?.usedInComponents) {
+          existing.keywords.push(...detail.related.usedInComponents);
+        }
+      }
+    }
+  }
+
+  // Remove duplicates and empty keywords
+  for (const item of items) {
+    item.keywords = [...new Set(item.keywords.filter(Boolean))];
+  }
+
+  return {
+    items,
+    generatedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Serialize search index to JSON for client-side use
+ */
+export function serializeSearchIndex(index: SearchIndex): string {
+  return JSON.stringify(index);
+}