@c-time/frelio-data-json-generator

FrelioBuildDataRecipe に従って FrelioDataJson を生成するライブラリ。

概要

@c-time/frelio-data-json-generator は GitHub Actions で実行され、CMS で編集されたコンテンツを HTML 生成用の JSON ファイル（FrelioDataJson）に変換します。

特徴

• 差分ビルド: Git diff に基づいて変更されたコンテンツのみを再生成
• フルリビルド: すべてのコンテンツを再生成（--full-rebuild オプション）
• 依存マップ: テンプレートやパーツの変更も追跡し、影響を受けるすべての出力を再生成
• エラーレポート: 一部のコンテンツが生成できなくても処理を継続し、エラーをレポート
• ドライラン: ファイルを出力せずにレポートのみ生成（--dry-run オプション）

インストール

npm install @c-time/frelio-data-json-generator

CLI 使用例

# 差分ビルド（デフォルト: origin/main...HEAD）
npx tsx scripts/generate-data-json.ts

# フルリビルド（全ファイル再生成）
npx tsx scripts/generate-data-json.ts --full-rebuild

# ドライラン（ファイル出力せずレポートのみ）
npx tsx scripts/generate-data-json.ts --dry-run

# 差分範囲を指定
npx tsx scripts/generate-data-json.ts --diff-range "origin/develop...HEAD"

# ログレベル
npx tsx scripts/generate-data-json.ts --log-level debug
npx tsx scripts/generate-data-json.ts --log-level info   # デフォルト
npx tsx scripts/generate-data-json.ts --log-level quiet

プログラム使用例

import {
  generateDataJson,
  NodeFileSystem,
  getGitDiff,
} from '@c-time/frelio-data-json-generator'
import { readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'fs'
import { dirname, join } from 'path'

// レシピと依存マップを読み込み
const recipe = JSON.parse(
  readFileSync('frelio-data/admin/recipes/build-data-recipe.json', 'utf-8')
)
const dependencyMap = JSON.parse(
  readFileSync('frelio-data/admin/dependency-map.json', 'utf-8')
)

// Git diff を取得
const gitDiff = await getGitDiff('origin/main...HEAD')

// FrelioDataJson を生成
const result = await generateDataJson({
  recipe,
  dependencyMap,
  gitDiff,
  fileSystem: new NodeFileSystem(),
  contentRootPath: 'frelio-data/site',
  outputRootPath: 'frelio-data/generated/data-json',
  options: {
    fullRebuild: false,
    dryRun: false,
    logLevel: 'info',
  },
})

const OUTPUT_ROOT = 'frelio-data/generated/data-json'

// 結果を出力
for (const output of result.outputs) {
  const fullPath = join(OUTPUT_ROOT, output.path)

  if (output.content.type === 'delete') {
    // 削除
    unlinkSync(fullPath)
  } else {
    // 作成/更新
    mkdirSync(dirname(fullPath), { recursive: true })
    writeFileSync(fullPath, JSON.stringify(output.content, null, 2))
  }
}

// レポートを出力
writeFileSync(
  'frelio-data/generated/report.json',
  JSON.stringify(result.report, null, 2)
)

console.log(`Updated: ${result.report.stats.updated}`)
console.log(`Deleted: ${result.report.stats.deleted}`)
console.log(`Errors: ${result.report.stats.errors}`)

カスタムフィールド

レシピの customFields を使って、出力 JSON にフィールドを追加・変換できます。3つのタイプがあります。

変換型（Transform）

ソース式とフォーマット関数でフィールド値を変換・整形します。

{ "field": "formattedDate", "source": "{$this.publishedAt}", "type": "date", "format": "YYYY年M月D日" }
{ "field": "excerpt", "source": "{$this.body}", "type": "truncate", "length": 100 }
{ "field": "fullTitle", "source": "{$this.title} - {$this.subtitle}" }

フォーマットタイプ一覧:

リレーションリスト型（RelationList）

任意のコンテンツタイプのリストを参照・埋め込みます。

{
  "field": "relatedArticles",
  "type": "relationList",
  "contentTypeId": "article",
  "limit": 5,
  "sort": { "field": "publishedAt", "direction": "desc" },
  "filters": [{ "field": "status", "operator": "eq", "value": "published" }]
}

定数型（Constant）

コンテンツに依存しない固定値を出力します。文字列・数値・真偽値・配列・オブジェクト等の任意の値を設定可能です。

{ "field": "siteName", "type": "constant", "value": "My Site" }
{ "field": "baseUrl", "type": "constant", "value": "https://example.com" }
{ "field": "maxItems", "type": "constant", "value": 10 }
{ "field": "features", "type": "constant", "value": ["blog", "news"] }

出力形式

FrelioDataJson

{
  "type": "update",
  "template": "article/detail.html",
  "outputFile": "articles/my-article.json",
  "data": {
    "contentId": "123e4567-e89b-12d3-a456-426614174000",
    "slug": "my-article",
    "title": "記事タイトル",
    "body": "<p>記事本文...</p>"
  }
}

report.json

{
  "generatedAt": "2026-03-28T10:00:00.000Z",
  "mode": "incremental",
  "dryRun": false,
  "stats": {
    "updated": 15,
    "deleted": 2,
    "skipped": 0,
    "errors": 1
  },
  "outputs": [
    { "path": "articles/my-article.json", "status": "updated" },
    { "path": "articles/old-article.json", "status": "deleted" }
  ],
  "errors": [
    {
      "code": "RELATION_NOT_FOUND",
      "outputPath": "articles/broken.json",
      "contentId": "abc-123",
      "field": "relatedCategory",
      "message": "リレーション先 'category/xyz' が見つかりません"
    }
  ],
  "warnings": [
    {
      "code": "EMPTY_LIST",
      "outputPath": "tags/empty-tag.json",
      "message": "リストが空です: tags"
    }
  ]
}

処理フロー

1. Git diff から変更ファイルを検出（または --full-rebuild で全件）
2. dependency-map を使って再生成スコープを計算
3. templateIncludes でパーツ変更の影響を拡張
4. 既存出力をスキャンして削除検出に備える
5. 必要なコンテンツをロード
6. レシピに従って FrelioDataJson を生成
7. 削除対象を検出（今回出力されなかったファイル）
8. レポートを生成

エラーハンドリング

一部のコンテンツが生成できなくても、処理は最後まで継続します。 エラーは report.json の errors に記録され、CMS-admin で確認できます。

エラーコード

警告コード

オプション

API リファレンス

generateDataJson(input)

メイン関数。FrelioDataJson を生成します。

function generateDataJson(
  input: GenerateDataJsonInput
): Promise<GenerateDataJsonResult>

入力

出力

getGitDiff(diffRange)

指定した範囲の Git diff を取得してパースします。

function getGitDiff(diffRange: string): Promise<GitDiffInfo>

parseGitDiff(diffText)

git diff --name-status の出力をパースします。

function parseGitDiff(diffText: string): GitDiffInfo

NodeFileSystem

Node.js のファイルシステムを使う FileSystemPort 実装。

class NodeFileSystem implements FileSystemPort {
  readFile(path: string): Promise<string>
  exists(path: string): Promise<boolean>
  listFiles(pattern: string): Promise<string[]>
}

GitHub Actions 設定例

差分ビルド

name: Generate Data JSON

on:
  push:
    branches: [staging-*]
    paths:
      - 'frelio-data/site/**'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 差分比較のため

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci
      - run: npx tsx scripts/generate-data-json.ts

      - name: Commit generated files
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add frelio-data/generated/
          git commit -m "chore: generate data JSON" || true
          git push

フルリビルド（タグベース）

name: Full Rebuild Data JSON

on:
  push:
    tags:
      - 'rebuild-*'

jobs:
  rebuild:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci
      - run: npx tsx scripts/generate-data-json.ts --full-rebuild

依存関係

@c-time/frelio-data-json-generator
├── @c-time/frelio-data-json         # 出力型 (FrelioDataJson)
├── @c-time/frelio-data-json-recipe  # レシピ型 (FrelioBuildDataRecipe)
└── @c-time/frelio-dependency-map    # スコープ選定 (FrelioDependencyMap)

ライセンス

Private