css-comments-to-json 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,415 @@
+# css-comments-to-json
+
+Generate styleguide JSON data from CSS comments.
+
+[English](#english) / [日本語](#日本語)
+
+## English
+
+This package is inspired by Hologram and KSS. It parses documentation comments written close to your CSS components and turns them into structured styleguide data.
+
+Unlike Hologram or many KSS-style tools, this package does not try to render a complete styleguide UI by itself. It focuses on generating JSON that can be consumed by Eleventy, Astro, VitePress, or any static site generator.
+
+## Why
+
+Storybook is a powerful component workshop, and it is often the right tool for application components with many states, props, interactions, and visual tests.
+
+But not every project needs that much machinery. For static sites, CSS-first component libraries, Eleventy/Nunjucks projects, corporate websites, landing pages, and CMS-oriented builds, a full component workshop can be more than the project needs.
+
+`css-comments-to-json` is for projects where you want:
+
+- CSS comments to be the source of truth for component usage.
+- Class tables, descriptions, variants, and HTML examples to live near the CSS.
+- Structured JSON that your existing static site generator can render.
+- A lightweight alternative when Storybook is more than you need.
+- Documentation that is easy for both humans and AI coding agents to read.
+
+The basic flow is:
+
+```txt
+CSS comments
+  -> styleguide JSON
+  -> your static site generator
+```
+
+In short: this is a lightweight styleguide data generator for CSS-first projects, not a replacement for Storybook.
+
+## When To Use This
+
+Use this when:
+
+- You are building mostly static HTML/CSS sites.
+- Your components are documented by class names and HTML examples.
+- You already have an SSG such as Eleventy and want to render the styleguide there.
+- You want Hologram/KSS-like CSS documentation without adopting a full UI workshop.
+- You want AI tools to infer existing component usage from source-adjacent documentation.
+
+## Install
+
+```sh
+npm install -D css-comments-to-json
+```
+
+## CLI
+
+```sh
+npx css-comments-to-json \
+  --input "src/assets/css/**/*.css" \
+  --output "src/_data" \
+  --prefix styleguide
+```
+
+This writes files like:
+
+```txt
+src/_data/styleguidecomponent.json
+src/_data/styleguidebase-component.json
+```
+
+## CSS Comment Format
+
+```css
+/*
+* @sg-category Component
+* @sg-name CTA
+* @sg-description CTA component.
+* @sg-table
+* | Class | Description |
+* |-------|-------------|
+* | c-cta | CTA container |
+* @sg-example
+<div class="c-cta">
+  CTA
+</div>
+*/
+```
+
+Supported tags:
+
+- `@sg-category`
+- `@sg-name`
+- `@sg-sub-name`
+- `@sg-description`
+- `@sg-table`
+- `@sg-example`
+- `@sg-markup`
+- `@sg-variant`
+
+## JavaScript API
+
+```js
+import { generateStyleguideData } from 'css-comments-to-json';
+
+await generateStyleguideData({
+  input: 'src/assets/css/**/*.css',
+  output: 'src/_data',
+  prefix: 'styleguide',
+});
+```
+
+For parsing a single CSS string:
+
+```js
+import { parseStyleguideComments } from 'css-comments-to-json';
+
+const data = parseStyleguideComments(css);
+```
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `input` | `src/assets/css/**/*.css` | CSS input glob |
+| `output` | `src/_data` | Output directory |
+| `prefix` | `styleguide` | Output filename prefix |
+| `cwd` | `process.cwd()` | Working directory |
+| `dryRun` | `false` | Return output files without writing |
+| `includeSource` | `false` | Include source file and line |
+
+## Config File
+
+You can keep options in a JavaScript config file:
+
+```js
+// css-comments-to-json.config.mjs
+export default {
+  input: 'src/assets/css/**/*.css',
+  output: 'src/_data',
+  prefix: 'styleguide',
+  includeSource: true,
+};
+```
+
+Run it with:
+
+```sh
+npx css-comments-to-json --config css-comments-to-json.config.mjs
+```
+
+CLI flags override config file values.
+
+## JSON Output
+
+Each `@sg-category` becomes one JSON file. For example, `Component` with the
+default `styleguide` prefix becomes `styleguidecomponent.json`.
+
+```json
+[
+  {
+    "name": "CTA",
+    "id": "cta",
+    "description": "CTA component.",
+    "children": [],
+    "tables": [
+      "| Class | Description |\n|-------|-------------|\n| c-cta | CTA container |"
+    ],
+    "examples": [
+      {
+        "name": "default",
+        "code": "<div class=\"c-cta\">\n  CTA\n</div>"
+      }
+    ]
+  }
+]
+```
+
+When `includeSource` is enabled, each component also includes `source.file` and
+`source.line`.
+
+## Warnings
+
+The CLI prints warnings for incomplete styleguide comments, such as:
+
+- Missing `@sg-category`
+- Missing or empty `@sg-name`
+- Empty `@sg-example`, `@sg-markup`, or `@sg-table` blocks
+- `@sg-sub-name`, `@sg-example`, `@sg-markup`, or `@sg-table` before `@sg-name`
+
+The JavaScript API returns the same warnings:
+
+```js
+const result = await generateStyleguideData({
+  input: 'src/assets/css/**/*.css',
+});
+
+console.log(result.warnings);
+```
+
+## Eleventy
+
+Use the CLI before Eleventy builds:
+
+```json
+{
+  "scripts": {
+    "build:css-comments-json": "css-comments-to-json --input \"src/assets/css/**/*.css\" --output \"src/_data\" --prefix styleguide",
+    "build": "npm run build:css-comments-json && eleventy"
+  }
+}
+```
+
+## 日本語
+
+`css-comments-to-json` は、CSS 内の構造化コメントを読み取り、JSON に変換する小さな CLI/API です。
+
+Hologram や KSS のような「CSS コメントを実装に近い場所へ置く」思想に影響を受けています。ただし、このパッケージ自体は完全なスタイルガイド UI を生成しません。CSS コメントから JSON を生成し、その JSON を Eleventy、Astro、VitePress など任意の静的サイトジェネレータで表示することに特化しています。
+
+### なぜ使うのか
+
+Storybook は強力なコンポーネントワークショップです。状態、props、インタラクション、visual test が多いアプリケーションコンポーネントでは適した選択です。
+
+一方で、すべてのプロジェクトに Storybook ほどの仕組みが必要とは限りません。静的サイト、CSS 中心のコンポーネント、Eleventy/Nunjucks、コーポレートサイト、LP、CMS 実装寄りの案件では、もう少し軽い仕組みの方が合うことがあります。
+
+`css-comments-to-json` は、次のような場合に向いています。
+
+- CSS コメントをコンポーネント利用方法の一次情報にしたい。
+- class 一覧、説明、variant、HTML 例を CSS の近くに置きたい。
+- 既存の静的サイトジェネレータでスタイルガイドを表示したい。
+- Storybook までは不要だが、軽量なスタイルガイドデータは欲しい。
+- 人間にも AI コーディングエージェントにも読みやすいコンポーネントドキュメントを作りたい。
+
+基本の流れは次の通りです。
+
+```txt
+CSS コメント
+  -> スタイルガイド用 JSON
+  -> 任意の静的サイトジェネレータ
+```
+
+つまり、これは Storybook の代替ではなく、CSS-first なプロジェクト向けの軽量な JSON 生成ツールです。
+
+### 向いているケース
+
+向いているケース:
+
+- 静的 HTML/CSS 中心のサイトを作っている。
+- コンポーネントを class 名と HTML 例で管理している。
+- Eleventy などの SSG が既にあり、その中でスタイルガイドを表示したい。
+- Hologram/KSS 的な CSS ドキュメントは欲しいが、重いコンポーネントワークショップは不要。
+- AI に既存コンポーネントの使い方を読み取らせたい。
+
+### インストール
+
+```sh
+npm install -D css-comments-to-json
+```
+
+### CLI
+
+```sh
+npx css-comments-to-json \
+  --input "src/assets/css/**/*.css" \
+  --output "src/_data" \
+  --prefix styleguide
+```
+
+次のような JSON を出力します。
+
+```txt
+src/_data/styleguidecomponent.json
+src/_data/styleguidebase-component.json
+```
+
+### CSS コメント形式
+
+```css
+/*
+* @sg-category Component
+* @sg-name CTA
+* @sg-description CTA コンポーネント。
+* @sg-table
+* | クラス名 | 説明 |
+* |----------|------|
+* | c-cta | CTA コンテナ |
+* @sg-example
+<div class="c-cta">
+  CTA
+</div>
+*/
+```
+
+対応タグ:
+
+- `@sg-category`
+- `@sg-name`
+- `@sg-sub-name`
+- `@sg-description`
+- `@sg-table`
+- `@sg-example`
+- `@sg-markup`
+- `@sg-variant`
+
+### JavaScript API
+
+```js
+import { generateStyleguideData } from 'css-comments-to-json';
+
+await generateStyleguideData({
+  input: 'src/assets/css/**/*.css',
+  output: 'src/_data',
+  prefix: 'styleguide',
+});
+```
+
+CSS 文字列を直接パースする場合:
+
+```js
+import { parseStyleguideComments } from 'css-comments-to-json';
+
+const data = parseStyleguideComments(css);
+```
+
+### オプション
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `input` | `src/assets/css/**/*.css` | CSS 入力 glob |
+| `output` | `src/_data` | 出力ディレクトリ |
+| `prefix` | `styleguide` | 出力ファイル名の prefix |
+| `cwd` | `process.cwd()` | 作業ディレクトリ |
+| `dryRun` | `false` | ファイルを書き込まず、出力予定だけ返す |
+| `includeSource` | `false` | 出力に元ファイルと行番号を含める |
+
+### 設定ファイル
+
+JavaScript の設定ファイルにオプションをまとめられます。
+
+```js
+// css-comments-to-json.config.mjs
+export default {
+  input: 'src/assets/css/**/*.css',
+  output: 'src/_data',
+  prefix: 'styleguide',
+  includeSource: true,
+};
+```
+
+次のように実行します。
+
+```sh
+npx css-comments-to-json --config css-comments-to-json.config.mjs
+```
+
+CLI の指定は、設定ファイルの値を上書きします。
+
+### JSON 出力例
+
+`@sg-category` ごとに 1 つの JSON ファイルを生成します。たとえば
+`Component` は、標準の `styleguide` prefix では `styleguidecomponent.json`
+になります。
+
+```json
+[
+  {
+    "name": "CTA",
+    "id": "cta",
+    "description": "CTA component.",
+    "children": [],
+    "tables": [
+      "| Class | Description |\n|-------|-------------|\n| c-cta | CTA container |"
+    ],
+    "examples": [
+      {
+        "name": "default",
+        "code": "<div class=\"c-cta\">\n  CTA\n</div>"
+      }
+    ]
+  }
+]
+```
+
+`includeSource` を有効にすると、各コンポーネントに `source.file` と
+`source.line` も含まれます。
+
+### Warning
+
+CLI は、不完全なスタイルガイドコメントに warning を出します。
+
+- `@sg-category` がない
+- `@sg-name` がない、または空
+- `@sg-example`、`@sg-markup`、`@sg-table` の中身が空
+- `@sg-name` より前に `@sg-sub-name`、`@sg-example`、`@sg-markup`、
+  `@sg-table` が出ている
+
+JavaScript API でも同じ warning を取得できます。
+
+```js
+const result = await generateStyleguideData({
+  input: 'src/assets/css/**/*.css',
+});
+
+console.log(result.warnings);
+```
+
+### Eleventy で使う
+
+Eleventy のビルド前に CLI を実行します。
+
+```json
+{
+  "scripts": {
+    "build:css-comments-json": "css-comments-to-json --input \"src/assets/css/**/*.css\" --output \"src/_data\" --prefix styleguide",
+    "build": "npm run build:css-comments-json && eleventy"
+  }
+}
+```

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "css-comments-to-json",
+  "version": "0.1.0",
+  "description": "Generate styleguide JSON data from CSS comments.",
+  "type": "module",
+  "license": "MIT",
+  "author": "masizime",
+  "sideEffects": false,
+  "bin": {
+    "css-comments-to-json": "./src/cli.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check src/cli.js && node --check src/index.js && npm test",
+    "prepublishOnly": "npm run check"
+  },
+  "keywords": [
+    "css",
+    "comments",
+    "json",
+    "cli",
+    "styleguide",
+    "documentation",
+    "hologram",
+    "kss",
+    "eleventy",
+    "nunjucks",
+    "ssg",
+    "static-site-generator"
+  ],
+  "dependencies": {
+    "glob": "^13.0.6"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tamshow/css-comments-to-json.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tamshow/css-comments-to-json/issues"
+  },
+  "homepage": "https://github.com/tamshow/css-comments-to-json#readme"
+}

package/src/cli.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+
+import process from 'node:process';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { generateStyleguideData } from './index.js';
+
+function printHelp() {
+  console.log(`Usage:
+  css-comments-to-json [options]
+
+Options:
+  --input <glob>     CSS input glob (default: src/assets/css/**/*.css)
+  --output <dir>     Output directory (default: src/_data)
+  --prefix <name>    Output filename prefix (default: styleguide)
+  --cwd <dir>        Working directory (default: process.cwd())
+  --config <file>    Load options from a JS config file
+  --source           Include source file and line in output
+  --dry-run          Print files that would be written without writing
+  --help             Show this help
+
+Example:
+  css-comments-to-json --input "src/assets/css/**/*.css" --output "src/_data"`);
+}
+
+function parseArgs(argv) {
+  const options = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--source') {
+      options.includeSource = true;
+    } else if (
+      arg === '--input' ||
+      arg === '--output' ||
+      arg === '--prefix' ||
+      arg === '--cwd' ||
+      arg === '--config'
+    ) {
+      const value = argv[index + 1];
+      if (!value || value.startsWith('--')) {
+        throw new Error(`${arg} requires a value`);
+      }
+      options[arg.slice(2)] = value;
+      index += 1;
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+async function loadConfig(configPath, cwd) {
+  if (!configPath) {
+    return {};
+  }
+
+  const absolutePath = path.resolve(cwd || process.cwd(), configPath);
+  const configModule = await import(pathToFileURL(absolutePath).href);
+  const config = configModule.default || configModule;
+
+  if (!config || typeof config !== 'object') {
+    throw new Error(`Config must export an object: ${configPath}`);
+  }
+
+  return config;
+}
+
+async function main() {
+  const cliOptions = parseArgs(process.argv.slice(2));
+
+  if (cliOptions.help) {
+    printHelp();
+    return;
+  }
+
+  const config = await loadConfig(cliOptions.config, cliOptions.cwd);
+  const optionsFromCli = { ...cliOptions };
+  delete optionsFromCli.config;
+  delete optionsFromCli.help;
+  const options = {
+    ...config,
+    ...optionsFromCli,
+  };
+  const result = await generateStyleguideData(options);
+
+  for (const warning of result.warnings) {
+    const source = warning.source
+      ? `${warning.source.file}${warning.source.line ? `:${warning.source.line}` : ''}`
+      : 'unknown source';
+    console.warn(`[warn] ${source} ${warning.message}`);
+  }
+
+  if (options.dryRun) {
+    for (const outputFile of result.outputFiles) {
+      console.log(`[dry-run] ${outputFile.filePath}`);
+    }
+  } else {
+    for (const outputFile of result.outputFiles) {
+      console.log(`write ${outputFile.filePath}`);
+    }
+  }
+
+  console.log(
+    `parsed ${result.files.length} files, generated ${result.outputFiles.length} files`,
+  );
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

package/src/index.js

@@ -0,0 +1,441 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { globSync } from 'glob';
+
+export const defaultOptions = {
+  input: 'src/assets/css/**/*.css',
+  output: 'src/_data',
+  prefix: 'styleguide',
+  cwd: process.cwd(),
+  dryRun: false,
+  includeSource: false,
+  warnings: undefined,
+};
+
+export function slugify(value) {
+  return String(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+export function removeStyleAttributes(html) {
+  return html.replace(/ style="[^"]*"/g, '');
+}
+
+function formatSource(source) {
+  if (!source) return 'unknown source';
+  return `${source.file}${source.line ? `:${source.line}` : ''}`;
+}
+
+function pushWarning(warnings, message, source) {
+  if (!warnings) return;
+  warnings.push({
+    message,
+    source,
+  });
+}
+
+function getBlockName(value) {
+  return value.trim().split(/\s+/)[0] || 'default';
+}
+
+function pushExample(target, currentExample, warnings, source) {
+  if (!target || currentExample.length === 0) return;
+  const code = removeStyleAttributes(currentExample.slice(1).join('\n').trim());
+
+  if (!code) {
+    pushWarning(warnings, '@sg-example has no example body', source);
+  }
+
+  target.examples = target.examples || [];
+  target.examples.push({
+    name: getBlockName(currentExample[0]),
+    code,
+  });
+}
+
+function pushMarkup(target, currentMarkup, warnings, source) {
+  if (!target || currentMarkup.length === 0) return;
+  const code = removeStyleAttributes(currentMarkup.slice(1).join('\n').trim());
+
+  if (!code) {
+    pushWarning(warnings, '@sg-markup has no markup body', source);
+  }
+
+  target.markup = target.markup || [];
+  target.markup.push({
+    name: getBlockName(currentMarkup[0]),
+    code,
+  });
+}
+
+function pushTable(target, currentTable, warnings, source) {
+  if (!target || currentTable.length === 0) return;
+  const table = currentTable.join('\n').trim();
+
+  if (!table) {
+    pushWarning(warnings, '@sg-table has no table body', source);
+  }
+
+  target.tables = target.tables || [];
+  target.tables.push(table);
+}
+
+function getCommentStartLine(content, commentStartIndex) {
+  return content.slice(0, commentStartIndex).split('\n').length;
+}
+
+function normalizeCommentLines(comment) {
+  return comment
+    .split('\n')
+    .map((line) => line.trim().replace(/^\*\s?/, ''))
+    .filter((line) => line !== '*/' && line !== '/');
+}
+
+function getOrCreateComponent(categoryMap, category, name, source) {
+  const parentId = slugify(name);
+  if (!categoryMap[category]) categoryMap[category] = [];
+
+  let component = categoryMap[category].find((item) => item.name === name);
+
+  if (!component) {
+    component = {
+      name,
+      id: parentId,
+      children: [],
+    };
+
+    if (source) {
+      component.source = source;
+    }
+
+    categoryMap[category].push(component);
+  }
+
+  return component;
+}
+
+export function parseStyleguideComment(comment, categoryMap, options = {}) {
+  const { source, warningSource = source, warnings } = options;
+  const lines = normalizeCommentLines(comment);
+
+  let parentComponent = null;
+  let childComponent = null;
+  let currentExample = [];
+  let currentMarkup = [];
+  let currentTable = [];
+  let inTableBlock = false;
+  let category = 'default';
+  let hasCategory = false;
+  let hasName = false;
+
+  function flushBlocks() {
+    const target = childComponent || parentComponent;
+    pushExample(target, currentExample, warnings, warningSource);
+    pushMarkup(target, currentMarkup, warnings, warningSource);
+    pushTable(target, currentTable, warnings, warningSource);
+    currentExample = [];
+    currentMarkup = [];
+    currentTable = [];
+    inTableBlock = false;
+  }
+
+  for (const line of lines) {
+    if (line.startsWith('@sg-category')) {
+      flushBlocks();
+      category = line.substring('@sg-category'.length).trim() || 'default';
+      hasCategory = true;
+    } else if (line.startsWith('@sg-name')) {
+      flushBlocks();
+      const parentName = line.substring('@sg-name'.length).trim();
+
+      if (!parentName) {
+        pushWarning(warnings, '@sg-name is empty', warningSource);
+        inTableBlock = false;
+        continue;
+      }
+
+      hasName = true;
+      parentComponent = getOrCreateComponent(
+        categoryMap,
+        category,
+        parentName,
+        source,
+      );
+      childComponent = null;
+      inTableBlock = false;
+    } else if (line.startsWith('@sg-sub-name')) {
+      flushBlocks();
+      if (!parentComponent) {
+        pushWarning(
+          warnings,
+          '@sg-sub-name appears before @sg-name',
+          warningSource,
+        );
+      }
+      childComponent = {
+        subName: line.substring('@sg-sub-name'.length).trim(),
+      };
+      if (source) {
+        childComponent.source = source;
+      }
+      if (parentComponent) {
+        parentComponent.children.push(childComponent);
+      }
+      inTableBlock = false;
+    } else if (line.startsWith('@sg-description')) {
+      flushBlocks();
+      if (childComponent) {
+        childComponent.description = line
+          .substring('@sg-description'.length)
+          .trim();
+      } else if (parentComponent) {
+        parentComponent.description = line
+          .substring('@sg-description'.length)
+          .trim();
+      }
+      inTableBlock = false;
+    } else if (line.startsWith('@sg-example')) {
+      flushBlocks();
+      if (!childComponent && !parentComponent) {
+        pushWarning(
+          warnings,
+          '@sg-example appears before @sg-name',
+          warningSource,
+        );
+      }
+      currentExample.push(line.substring('@sg-example'.length).trim());
+      inTableBlock = false;
+    } else if (line.startsWith('@sg-markup')) {
+      flushBlocks();
+      if (!childComponent && !parentComponent) {
+        pushWarning(
+          warnings,
+          '@sg-markup appears before @sg-name',
+          warningSource,
+        );
+      }
+      currentMarkup.push(line.substring('@sg-markup'.length).trim());
+      inTableBlock = false;
+    } else if (line.startsWith('@sg-variant')) {
+      flushBlocks();
+      if (childComponent) {
+        childComponent.variants = childComponent.variants || [];
+        childComponent.variants.push(
+          line.substring('@sg-variant'.length).trim(),
+        );
+      } else if (parentComponent) {
+        parentComponent.variants = parentComponent.variants || [];
+        parentComponent.variants.push(
+          line.substring('@sg-variant'.length).trim(),
+        );
+      }
+      inTableBlock = false;
+    } else if (line.startsWith('@sg-table')) {
+      flushBlocks();
+      if (!childComponent && !parentComponent) {
+        pushWarning(
+          warnings,
+          '@sg-table appears before @sg-name',
+          warningSource,
+        );
+      }
+      inTableBlock = true;
+    } else if (inTableBlock) {
+      currentTable.push(line);
+    } else if (line.startsWith('@sg-')) {
+      flushBlocks();
+    } else {
+      if (currentExample.length > 0) {
+        currentExample.push(line);
+      } else if (currentMarkup.length > 0) {
+        currentMarkup.push(line);
+      }
+      inTableBlock = false;
+    }
+  }
+
+  if (!hasCategory) {
+    pushWarning(
+      warnings,
+      `@sg-category is missing; using "default" for ${formatSource(warningSource)}`,
+      warningSource,
+    );
+  }
+  if (!hasName) {
+    pushWarning(
+      warnings,
+      '@sg-name is missing; comment block was ignored',
+      warningSource,
+    );
+  }
+
+  flushBlocks();
+}
+
+export function parseStyleguideComments(content, options = {}) {
+  const mergedOptions = {
+    filePath: undefined,
+    includeSource: false,
+    warnings: undefined,
+    ...options,
+  };
+  const categoryMap = {};
+  const commentRegex = /\/\*[\s\S]*?\*\//g;
+  const matches = content.matchAll(commentRegex);
+
+  for (const match of matches) {
+    const comment = match[0];
+    if (!/@sg-/.test(comment)) continue;
+
+    const sourceBase = mergedOptions.filePath
+      ? {
+          file: mergedOptions.filePath,
+          line: getCommentStartLine(content, match.index || 0),
+        }
+      : undefined;
+    const source =
+      mergedOptions.includeSource && sourceBase
+        ? sourceBase
+        : undefined;
+    const warningSource =
+      sourceBase
+        ? {
+            ...sourceBase,
+          }
+        : undefined;
+
+    parseStyleguideComment(comment, categoryMap, {
+      source,
+      warningSource,
+      warnings: mergedOptions.warnings,
+    });
+  }
+
+  return categoryMap;
+}
+
+export function mergeCategoryMaps(target, source) {
+  for (const [category, components] of Object.entries(source)) {
+    if (!target[category]) target[category] = [];
+
+    for (const component of components) {
+      const existing = target[category].find(
+        (item) => item.name === component.name,
+      );
+
+      if (existing) {
+        existing.children.push(...(component.children || []));
+        if (component.description && !existing.description) {
+          existing.description = component.description;
+        }
+        if (component.tables) {
+          existing.tables = [...(existing.tables || []), ...component.tables];
+        }
+        if (component.examples) {
+          existing.examples = [
+            ...(existing.examples || []),
+            ...component.examples,
+          ];
+        }
+        if (component.markup) {
+          existing.markup = [...(existing.markup || []), ...component.markup];
+        }
+        if (component.variants) {
+          existing.variants = [
+            ...(existing.variants || []),
+            ...component.variants,
+          ];
+        }
+      } else {
+        target[category].push(component);
+      }
+    }
+  }
+
+  return target;
+}
+
+export async function collectStyleguideData(options = {}) {
+  const mergedOptions = {
+    ...defaultOptions,
+    ...options,
+  };
+  const files = globSync(mergedOptions.input, {
+    cwd: mergedOptions.cwd,
+    nodir: true,
+  }).sort();
+  const categoryMap = {};
+  const warnings = mergedOptions.warnings || [];
+
+  for (const file of files) {
+    const absolutePath = path.resolve(mergedOptions.cwd, file);
+    const content = await fs.readFile(absolutePath, 'utf8');
+    const parsed = parseStyleguideComments(content, {
+      filePath: file,
+      includeSource: mergedOptions.includeSource,
+      warnings,
+    });
+    mergeCategoryMaps(categoryMap, parsed);
+  }
+
+  return {
+    files,
+    categories: categoryMap,
+    warnings,
+  };
+}
+
+export function createOutputFiles(categories, options = {}) {
+  const mergedOptions = {
+    ...defaultOptions,
+    ...options,
+  };
+
+  return Object.entries(categories).map(([category, components]) => {
+    const safeCategory = slugify(category) || 'default';
+    const fileName = `${mergedOptions.prefix}${safeCategory}.json`;
+    const filePath = path.resolve(
+      mergedOptions.cwd,
+      mergedOptions.output,
+      fileName,
+    );
+
+    return {
+      category,
+      filePath,
+      data: components,
+      json: `${JSON.stringify(components, null, 2)}\n`,
+    };
+  });
+}
+
+export async function writeStyleguideData(categories, options = {}) {
+  const mergedOptions = {
+    ...defaultOptions,
+    ...options,
+  };
+  const outputFiles = createOutputFiles(categories, mergedOptions);
+
+  if (mergedOptions.dryRun) {
+    return outputFiles;
+  }
+
+  for (const outputFile of outputFiles) {
+    await fs.mkdir(path.dirname(outputFile.filePath), { recursive: true });
+    await fs.writeFile(outputFile.filePath, outputFile.json, 'utf8');
+  }
+
+  return outputFiles;
+}
+
+export async function generateStyleguideData(options = {}) {
+  const collected = await collectStyleguideData(options);
+  const outputFiles = await writeStyleguideData(collected.categories, options);
+
+  return {
+    ...collected,
+    outputFiles,
+  };
+}