@interactive-inc/docs-client 0.0.7 → 0.0.9

package/README.md

@@ -1,228 +0,0 @@
-# @interactive-inc/docs-client
-
-技術仕様書、製品資料など、Markdownで記述された資料をリポジトリで管理する際に、それらを効率的に読み書きするためのAPIを提供します。
-
-```ts
-import { DocClient, DocFileSystem, DocPathSystem } from "@interactive-inc/docs-client"
-
-const docClient = new DocClient({
-  fileSystem: new DocFileSystem({
-    basePath: "/docs", // リポジトリ内のドキュメントルート
-    pathSystem: new DocPathSystem(),
-  }),
-})
-
-const ref = docClient
-  .directory("products/product-1/features")
-  .file("login.md")
-
-const entity = await ref.read()
-
-if (entity instanceof Error) throw entity
-
-console.log(entity.content.title)
-```
-
-## インストール
-
-```bash
-bun add @interactive-inc/docs
-# または
-npm install @interactive-inc/docs
-```
-
-## 設計
-
-このライブラリは、Markdownファイルを構造化されたディレクトリでの動作を想定しています。
-
-以下は製品仕様書を管理する場合の一例です。ディレクトリ構造は自由に設計できます：
-
-```
-docs/                   # ドキュメントルート（任意の名前）
-├── products/           # 製品ドキュメント（例）
-│   ├── product-a/
-│   │   ├── index.md    # 製品概要
-│   │   ├── features/   # 機能仕様
-│   │   │   ├── login.md
-│   │   │   └── _/      # アーカイブ（非推奨・削除予定）
-│   │   │       └── old-feature.md
-│   │   ├── pages/      # 画面仕様
-│   │   └── terms/      # 製品固有の用語
-│   └── product-b/
-├── terms/              # 共通用語集（例）
-├── guidelines/         # 開発ガイドライン（例）
-└── index.md            # ルートドキュメント
-```
-
-## 機能
-
-### アーカイブシステム
-
-ファイルを削除する代わりに、`_`ディレクトリに移動することで論理削除を表現できます。
-
-- `features/login.md` → `features/_/login.md` （アーカイブ）
-- アーカイブされたファイルも読み取り可能
-- 必要に応じて復元可能
-
-```ts
-// ファイルをアーカイブする
-const fileRef = docClient.directory("specs/v1").mdFile("deprecated-api.md")
-await fileRef.archive()
-```
-
-### メタデータ管理
-
-各Markdownファイルの先頭にYAML形式でメタデータを記述：
-
-```markdown
----
-title: ログイン機能
-milestone: 2025.01
-features:
-  - authentication
-  - security
-priority: high
-is-done: false
----
-
-# ログイン機能
-
-説明...
-
-本文...
-```
-
-このように操作できます。
-
-```ts
-// FrontMatterの読み取り
-const fileRef = docClient.directory("features").mdFile("login.md")
-
-const file = await fileRef.read()
-
-if (file instanceof Error) throw file
-
-// "ログイン機能"
-console.log(file.content.frontMatter.title)
-
-// ["authentication", "security"]
-console.log(file.content.frontMatter.features)
-```
-
-### ファイル間のリレーション
-
-FrontMatterとスキーマを使用して、ドキュメント間の関連を定義できます。
-
-#### スキーマの定義（index.md）
-
-```markdown
----
-title: 機能一覧
-schema:
-  page:
-    type: relation
-    path: "../pages"
-    title: 関連ページ
-    required: false
-  tags:
-    type: multi-relation
-    path: "../tags"
-    title: タグ
-    required: false
----
-```
-
-#### リレーションの使用
-
-features/login.md
-
-```markdown
----
-title: ログイン機能
-page: login-page
-tags:
-  - authentication
-  - security
----
-```
-
-#### 使い方
-
-```ts
-const featureRef = docClient.directory("features").mdFile("login.md")
-
-const relatedTags = await featureRef.relations("tags")
-
-for (const tagRef of relatedTags) {
-  const tagEntity = await tagRef.read()
-  if (tagEntity instanceof Error) continue
-  console.log(tagEntity.content.title)
-}
-```
-
-## 使い方
-
-### 初期設定
-
-```ts
-import { DocClient, DocFileSystem, DocPathSystem } from "@interactive-inc/docs-client"
-
-const docClient = new DocClient({
-  fileSystem: new DocFileSystem({
-    basePath: "/path/to/your-repo/docs",
-    pathSystem: new DocPathSystem(),
-  }),
-})
-```
-
-### ファイルの読み書き
-
-```ts
-// ファイル読み取り
-const fileRef = docClient
-  .directory("specifications/api")
-  .mdFile("authentication.md")
-
-const entity = await fileRef.read()
-if (entity instanceof Error) throw entity
-
-console.log(entity.content.body)
-console.log(entity.content.frontMatter.value)
-
-// ファイル作成・更新
-await fileRef.writeContent(`---
-title: 認証API仕様
-version: 2.0.0
----
-
-# 認証API仕様
-
-POST /api/v2/auth/login
-`)
-```
-
-### FrontMatterの操作
-
-```ts
-const entity = await fileRef.read()
-if (entity instanceof Error) throw entity
-
-// メタデータ更新
-const newFrontMatter = new DocFrontMatterMdValue({
-  ...entity.content.frontMatter.value,
-  milestone: "2025.02",
-})
-
-const newContent = entity.content.withFrontMatter(newFrontMatter)
-await fileRef.writeContent(newContent.toText())
-```
-
-### アーカイブ操作
-
-```ts
-// ファイルをアーカイブ
-const fileRef = docClient
-  .directory("specifications/api/v1")
-  .mdFile("legacy-endpoints.md")
-await fileRef.archive()
-```

package/build/index.d.ts

@@ -800,6 +800,10 @@ declare class DocSchemaValue {
      */
     private isNullOrUndefined;
     toJson(): DocSchemaRecord;
+    /**
+     * スキーマを正規化
+     */
+    private static normalizeSchema;
 }
 
 /**

package/build/index.js

@@ -1348,9 +1348,9 @@ var DocSchemaFieldFactory = class {
     const baseField = {
       type: normalizedType,
       required: fieldRequired ?? false,
-      title: fieldTitle,
-      description: fieldDescription,
-      default: fieldDefault
+      title: fieldTitle ?? null,
+      description: fieldDescription ?? null,
+      default: fieldDefault ?? null
     };
     return {
       ...baseField,
@@ -1364,9 +1364,9 @@ var DocSchemaFieldFactory = class {
     return {
       type: "text",
       required: false,
-      title: "",
-      description: "",
-      default: ""
+      title: null,
+      description: null,
+      default: null
     };
   }
   /**
@@ -2109,9 +2109,10 @@ import { parse as parse2, stringify as stringify3 } from "yaml";
 
 // lib/values/doc-schema-value.ts
 var DocSchemaValue = class _DocSchemaValue {
+  value;
   constructor(value) {
-    this.value = value;
-    zDocSchema.parse(value);
+    this.value = _DocSchemaValue.normalizeSchema(value);
+    zDocSchema.parse(this.value);
     Object.freeze(this.value);
     Object.freeze(this);
   }
@@ -2130,7 +2131,7 @@ var DocSchemaValue = class _DocSchemaValue {
       return null;
     }
     const factory = new DocSchemaFieldFactory();
-    return factory.fromSchemaEntry(name, fieldDef);
+    return factory.fromUnknown(name, fieldDef);
   }
   get fields() {
     const factory = new DocSchemaFieldFactory();
@@ -2139,7 +2140,7 @@ var DocSchemaValue = class _DocSchemaValue {
       if (!fieldValue) {
         throw new Error(`Field ${name} not found in schema`);
       }
-      return factory.fromSchemaEntry(name, fieldValue);
+      return factory.fromUnknown(name, fieldValue);
     });
   }
   get relationFields() {
@@ -2351,6 +2352,21 @@ var DocSchemaValue = class _DocSchemaValue {
   toJson() {
     return this.value;
   }
+  /**
+   * スキーマを正規化
+   */
+  static normalizeSchema(schema) {
+    const normalized = {};
+    const factory = new DocSchemaFieldFactory();
+    for (const [key, field] of Object.entries(schema)) {
+      try {
+        const normalizedField = factory.fromUnknown(key, field);
+        normalized[key] = normalizedField.toJson();
+      } catch {
+      }
+    }
+    return normalized;
+  }
 };
 
 // lib/values/doc-front-matter-index-value.ts
@@ -4139,8 +4155,9 @@ var DocClient = class {
    * Markdownファイル参照を取得
    */
   mdFile(relativePath) {
+    const normalizedPath = relativePath.endsWith(".md") ? relativePath : `${relativePath}.md`;
     return new DocFileMdReference({
-      path: relativePath,
+      path: normalizedPath,
       fileSystem: this.fileSystem,
       pathSystem: this.pathSystem
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interactive-inc/docs-client",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "type": "module",
   "scripts": {
     "check": "tsgo --noEmit",

package/debug/debug.ts

@@ -1,108 +0,0 @@
-import { DocClient } from "../lib/doc-client"
-import { DocFileSystem } from "../lib/doc-file-system"
-import { DocPathSystem } from "../lib/doc-path-system"
-
-// DocClientの初期化
-const basePath = "/Users/n/Documents/open-docs/docs" // docs ディレクトリをベースパスに
-const pathSystem = new DocPathSystem()
-const fileSystem = new DocFileSystem({
-  basePath,
-  pathSystem,
-})
-const docClient = new DocClient({
-  fileSystem,
-  pathSystem,
-})
-
-async function demonstrateRelations() {
-  console.log("=== DocClient リレーション機能のデモ ===\n")
-
-  // 1. ファイルを取得 (.mdファイルなのでmdFile()を使用)
-  const pageFile = docClient.mdFile("products/doc-browser/pages/home.md")
-  console.log("1. ファイルを取得:")
-  console.log(`   パス: ${pageFile.path}`)
-
-  // 2. ファイルの内容を読み込む
-  const pageEntity = await pageFile.read()
-  if (pageEntity instanceof Error) {
-    console.error("   エラー:", pageEntity.message)
-    return
-  }
-  console.log(`   タイトル: ${pageEntity.content.title}`)
-  console.log(`   FrontMatter:`, pageEntity.content.frontMatter.value)
-
-  // 3. 単一のリレーションを取得（author）
-  console.log("\n2. 単一のリレーションを取得 (author):")
-  const authorRelation = await pageFile.relation("author")
-  if (authorRelation && !(authorRelation instanceof Error)) {
-    console.log(`   リレーション先のパス: ${authorRelation.path}`)
-
-    // リレーション先のファイルを読み込む
-    const authorEntity = await authorRelation.read()
-    if (!(authorEntity instanceof Error)) {
-      console.log(`   著者名: ${authorEntity.content.title}`)
-      console.log(
-        `   内容の一部: ${authorEntity.content.body.substring(0, 50)}...`,
-      )
-    } else {
-      console.log(`   読み込みエラー: ${authorEntity.message}`)
-    }
-  } else if (authorRelation instanceof Error) {
-    console.log(`   エラー: ${authorRelation.message}`)
-  } else {
-    console.log("   リレーションが見つかりません")
-  }
-
-  // 4. 複数のリレーションを取得（features）
-  console.log("\n3. 複数のリレーションを取得 (features):")
-  const featureRelations = await pageFile.relations("features")
-  console.log(`   機能数: ${featureRelations.length}`)
-
-  for (const featureRef of featureRelations) {
-    console.log(`   - パス: ${featureRef.path}`)
-    const featureEntity = await featureRef.read()
-    if (!(featureEntity instanceof Error)) {
-      console.log(`     タイトル: ${featureEntity.content.title}`)
-    }
-  }
-
-  // 4.5. 別の単一リレーションを取得（category）
-  console.log("\n4. 別の単一リレーションを取得 (category):")
-  const categoryRelation = await pageFile.relation("category")
-  if (categoryRelation && !(categoryRelation instanceof Error)) {
-    console.log(`   リレーション先のパス: ${categoryRelation.path}`)
-    const categoryEntity = await categoryRelation.read()
-    if (!(categoryEntity instanceof Error)) {
-      console.log(`   カテゴリー名: ${categoryEntity.content.title}`)
-    }
-  }
-
-  // 5. ディレクトリのindex.mdからスキーマを確認
-  console.log("\n5. ディレクトリのindex.mdからスキーマを確認:")
-  const indexFile = await pageFile.getDirectoryIndex()
-  if (indexFile) {
-    const schema = indexFile.content.frontMatter.value.schema
-    console.log("   スキーマ定義:")
-    if (schema && typeof schema === "object") {
-      for (const [key, field] of Object.entries(schema)) {
-        if (typeof field === "object" && field !== null && "type" in field) {
-          console.log(`   - ${key}: ${field.type}`)
-          if ("path" in field) {
-            console.log(`     パス: ${field.path}`)
-          }
-        }
-      }
-    }
-  }
-
-  // 6. ディレクトリ内のファイル一覧を取得
-  console.log("\n6. ディレクトリ内のファイル一覧:")
-  const pagesDir = docClient.directory("products/doc-browser/pages")
-  const files = await pagesDir.files()
-  for (const file of files) {
-    console.log(`   - ${file.path}`)
-  }
-}
-
-// 実行
-demonstrateRelations().catch(console.error)