@lism-css/mcp 0.26.0 → 0.28.0

package/dist/lib/markdown-utils.d.ts

@@ -1,38 +1,19 @@
-/**
- * Markdown から指定した見出しのセクションを抽出する。
- * 同レベル以上の次の見出しが来るまでの内容を返す。
- * @param md - Markdown 全文
- * @param heading - 見出しテキスト（`#` プレフィックスあり・なし両可）
- */
+/** 指定見出しから同レベル以上の次の見出しまでを抽出する。headingは#の有無を問わない。 */
 export declare function extractSection(md: string, heading: string): string;
-/**
- * Markdown から全ての見出しとその開始行を抽出する。
- */
 export declare function listHeadings(md: string): {
     level: number;
     text: string;
     line: number;
 }[];
 export interface PropRow {
-    /** Lism Prop 名（例: "fz"） */
     prop: string;
-    /** CSS プロパティ名（例: "font-size"）。変数形式（"--hl"）も含む */
     cssProperty: string;
-    /** 所属する ### セクション名 */
     sectionName: string;
-    /** プリセット値クラス列の生テキスト（例: "-fz:base, -fz:5xl, ..."） */
     presetColumn: string;
 }
-/**
- * property-class.md のテーブルを全て解析して PropRow[] を返す。
- * `| Prop | CSS プロパティ | ...` 形式のテーブルのみ対象とする。
- */
+/** Property Classの対象テーブルを解析してPropRowへ変換する。 */
 export declare function parsePropRows(md: string): PropRow[];
-/**
- * Markdown からコンポーネント名に一致するセクションを探して返す。
- *
- * components-ui.md のように各コンポーネントが `## ComponentName` で始まる場合に有効。
- */
+/** 各コンポーネントが`## ComponentName`で始まる文書向け。 */
 export declare function findComponentByHeading(md: string, name: string): string;
 /**
  * Markdown 内のテーブルセル（`` `<ComponentName>` ``）からコンポーネントを含む

package/dist/lib/markdown-utils.js

@@ -1,14 +1,8 @@
-/** 見出しの `#` レベルを返す（見出しでなければ 0） */
 function headingLevel(line) {
     const m = line.match(/^(#{1,6})\s/);
     return m ? m[1].length : 0;
 }
-/**
- * Markdown から指定した見出しのセクションを抽出する。
- * 同レベル以上の次の見出しが来るまでの内容を返す。
- * @param md - Markdown 全文
- * @param heading - 見出しテキスト（`#` プレフィックスあり・なし両可）
- */
+/** 指定見出しから同レベル以上の次の見出しまでを抽出する。headingは#の有無を問わない。 */
 export function extractSection(md, heading) {
     const headingText = heading.replace(/^#+\s*/, '').trim();
     const lines = md.split('\n');
@@ -34,9 +28,6 @@ export function extractSection(md, heading) {
     }
     return lines.slice(startIdx, endIdx).join('\n').trimEnd();
 }
-/**
- * Markdown から全ての見出しとその開始行を抽出する。
- */
 export function listHeadings(md) {
     return md.split('\n').flatMap((line, i) => {
         const lv = headingLevel(line);
@@ -45,38 +36,32 @@ export function listHeadings(md) {
         return [{ level: lv, text: line.replace(/^#+\s*/, '').trim(), line: i }];
     });
 }
-/**
- * property-class.md のテーブルを全て解析して PropRow[] を返す。
- * `| Prop | CSS プロパティ | ...` 形式のテーブルのみ対象とする。
- */
+/** Property Classの対象テーブルを解析してPropRowへ変換する。 */
 export function parsePropRows(md) {
     const lines = md.split('\n');
     const rows = [];
     let currentSection = '';
     let inPropTable = false;
+    // 見出しと対象テーブルの範囲を追跡する。
     for (const line of lines) {
         const lv = headingLevel(line);
-        // セクション見出しを追跡（### レベル）
         if (lv >= 2) {
             currentSection = line.replace(/^#+\s*/, '').trim();
             inPropTable = false;
             continue;
         }
-        // Property Class テーブルのヘッダー行を検出
         if (line.includes('Prop') && line.includes('CSS プロパティ')) {
             inPropTable = true;
             continue;
         }
-        // 区切り行はスキップ
         if (inPropTable && /^\|[-\s|:]+\|/.test(line)) {
             continue;
         }
-        // テーブルの終了を検出
         if (inPropTable && !line.startsWith('|')) {
             inPropTable = false;
             continue;
         }
-        // データ行を解析
+        // 対象テーブルの各行をPropRowへ変換する。
         if (inPropTable && line.startsWith('|')) {
             const cells = line
                 .split('|')
@@ -84,9 +69,7 @@ export function parsePropRows(md) {
                 .filter(Boolean);
             if (cells.length >= 2) {
                 const prop = cells[0].replace(/`/g, '').trim();
-                // CSS プロパティ: バッククォート除去、括弧内の注釈は保持しない
                 const cssPropertyRaw = cells[1].replace(/`/g, '').trim();
-                // `line-height`（`--hl` 経由） のような括弧注釈を除去
                 const cssProperty = cssPropertyRaw
                     .replace(/（[^）]*）$/, '')
                     .replace(/\([^)]*\)$/, '')
@@ -103,11 +86,7 @@ export function parsePropRows(md) {
 // ----------------------------------------------------------------
 // コンポーネント検索
 // ----------------------------------------------------------------
-/**
- * Markdown からコンポーネント名に一致するセクションを探して返す。
- *
- * components-ui.md のように各コンポーネントが `## ComponentName` で始まる場合に有効。
- */
+/** 各コンポーネントが`## ComponentName`で始まる文書向け。 */
 export function findComponentByHeading(md, name) {
     return extractSection(md, name);
 }
@@ -119,10 +98,9 @@ export function findComponentByHeading(md, name) {
 export function findComponentInTables(md, name) {
     const nameLower = name.toLowerCase();
     const lines = md.split('\n');
-    // コンポーネント名のパターン: `<Flex>`, `<flex>`, または単純に "flex" がテーブル行に含まれるか
     const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     const pattern = new RegExp(`\`?<${escaped}>?\`?`, 'i');
-    // まず対象行を探す
+    // コンポーネントを含むテーブル行を探す。
     let targetLineIdx = -1;
     for (let i = 0; i < lines.length; i++) {
         if (lines[i].startsWith('|') && (pattern.test(lines[i]) || lines[i].toLowerCase().includes(`\`${nameLower}\``))) {
@@ -132,7 +110,7 @@ export function findComponentInTables(md, name) {
     }
     if (targetLineIdx === -1)
         return '';
-    // 対象行を含む ## セクションの開始を遡って探す
+    // 対象行を含む##節の範囲を決める。
     let sectionStart = -1;
     let sectionLevel = 0;
     for (let i = targetLineIdx; i >= 0; i--) {
@@ -145,7 +123,6 @@ export function findComponentInTables(md, name) {
     }
     if (sectionStart === -1)
         return lines.slice(0, targetLineIdx + 20).join('\n');
-    // セクションの終端を探す
     let sectionEnd = lines.length;
     for (let i = sectionStart + 1; i < lines.length; i++) {
         const lv = headingLevel(lines[i]);

package/dist/lib/search.d.ts

@@ -1,8 +1,5 @@
 import type { DocsEntry, SearchResult } from './types.js';
-/**
- * Property Class 記法（例: "-g:5", ".-p:20", "-fz"）から prop 名を抽出する。
- * get-props-system.ts からも利用される共通ユーティリティ。
- */
+/** Property Class記法からprop名を取り出す。get-props-system.tsからも利用する。 */
 export declare function parsePropClassName(input: string): string | null;
 export interface SearchDocsOptions {
     category?: string;

package/dist/lib/search.js

@@ -4,32 +4,22 @@ function tokenize(text) {
         .split(/[\s\-_./]+/)
         .filter((t) => t.length > 0);
 }
-// ".-g:5" or "-g:5" → prop="g", value="5" / "-p" → prop="p"
 const PROP_CLASS_RE = /^\.?-([a-z][a-z0-9-]*)(:.+)?$/i;
-/**
- * Property Class 記法（例: "-g:5", ".-p:20", "-fz"）から prop 名を抽出する。
- * get-props-system.ts からも利用される共通ユーティリティ。
- */
+/** Property Class記法からprop名を取り出す。get-props-system.tsからも利用する。 */
 export function parsePropClassName(input) {
     const m = input.match(PROP_CLASS_RE);
     return m ? m[1].toLowerCase() : null;
 }
-/**
- * 検索クエリをCSSプロパティ名やProperty Class記法で展開する。
- * 例: "font-size" → "font-size fz"
- * 例: "-g:5" → "-g:5 g gap property class"
- */
+/** CSSプロパティとProperty Classを相互展開して検索語を補う。 */
 function expandQuery(query, cssPropertyMap) {
     const additions = [];
     const queryLower = query.toLowerCase();
     const parsedProp = parsePropClassName(queryLower.trim());
     if (cssPropertyMap) {
         for (const [cssProp, lismProps] of cssPropertyMap) {
-            // Property Class 記法の逆引き（例: "-g:5" の "g" → "gap"）
             if (parsedProp && lismProps.includes(parsedProp)) {
                 additions.push(cssProp);
             }
-            // CSSプロパティ名の展開（例: "font-size" → "fz"）
             if (queryLower.includes(cssProp)) {
                 additions.push(...lismProps);
             }
@@ -47,20 +37,16 @@ function scoreEntry(entry, queryTokens) {
     const headingsLower = entry.headings.join(' ').toLowerCase();
     const keywordsLower = entry.keywords.join(' ').toLowerCase();
     const snippetLower = entry.snippet.toLowerCase();
+    // titleからsnippetへ順に重みを下げる。
     for (const token of queryTokens) {
-        // title matches are weighted highest
         if (titleLower.includes(token))
             score += 10;
-        // keywords
         if (keywordsLower.includes(token))
             score += 5;
-        // headings
         if (headingsLower.includes(token))
             score += 3;
-        // description
         if (descLower.includes(token))
             score += 2;
-        // snippet
         if (snippetLower.includes(token))
             score += 1;
     }
@@ -68,7 +54,7 @@ function scoreEntry(entry, queryTokens) {
 }
 export function searchDocs(entries, query, options) {
     const { category, limit = 10, cssPropertyMap, guideTopics } = options ?? {};
-    // CSSプロパティ名・Property Class記法をLism prop名に展開してからトークナイズ
+    // CSSプロパティ名とProperty Class記法も同じ検索対象へ展開する。
     const expandedQuery = expandQuery(query, cssPropertyMap);
     const queryTokens = tokenize(expandedQuery);
     if (queryTokens.length === 0)
@@ -103,19 +89,14 @@ const SITE_BASE_URL = 'https://lism-css.com';
 function slugToPageUrl(slug) {
     return slug.startsWith('ui/') ? `${SITE_BASE_URL}/${slug}/` : `${SITE_BASE_URL}/docs/${slug}/`;
 }
-/** `sourcePath`（拡張子なし）の末尾セグメントを返す（例: `primitives/l--flex` → `l--flex`） */
 function getBasename(withoutExt) {
     const parts = withoutExt.split('/');
     return parts[parts.length - 1];
 }
-/**
- * 検索結果のページを詳しく見るための推奨フォローアップツール呼び出しを返す。
- * sourcePath による判定をカテゴリによる判定より優先する。
- */
+/** 検索結果を掘り下げる推奨ツールを返す。カテゴリよりsourcePathの規則を優先する。 */
 function getNextTool(entry, guideTopics) {
     const withoutExt = entry.sourcePath.replace(/\.mdx$/, '');
     const basename = getBasename(withoutExt);
-    // sourcePath ベースの判定（category より優先）
     if (withoutExt === 'core-components/lism-props') {
         return 'get_props_system()';
     }
@@ -128,13 +109,10 @@ function getNextTool(entry, guideTopics) {
     if (withoutExt.startsWith('property-class/')) {
         return `get_props_system(prop: "${basename}")`;
     }
-    // ui/block-examples/（Chat, Timeline 等）と ui/components/（Card, Hero 等）は、
-    // パッケージが提供するコンポーネントではなく Lism CSS での実装例ページなので get_component では解決できない。
-    // 詳細が必要な場合は検索結果の url を参照してもらう。
+    // 実装例ページはパッケージ提供コンポーネントではないためget_componentでは解決できない。
     if (withoutExt.startsWith('ui/block-examples/') || withoutExt.startsWith('ui/components/')) {
         return null;
     }
-    // category ベースの判定
     switch (entry.category) {
         case 'core-components':
             return `get_component(name: "${basename}")`;
@@ -156,12 +134,6 @@ function getNextTool(entry, guideTopics) {
  * IMPORTANT: `apps/docs/src/lib/contentSlug.ts` の `toContentSlug` と必ず同じロジックに保つこと。
  * 別ワークスペース（apps/docs）なので直接 import できず、ローカル実装で複製している。
  * apps/docs 側を変更した場合は必ずここも合わせて更新する。
- *
- * 例:
- *   `primitives/l--tileGrid.mdx`    → `primitives/l--tileGrid`
- *   `trait-class/is--boxLink.mdx`   → `trait-class/is--boxLink`
- *   `core-components/Group.mdx`     → `core-components/group`
- *   `ui/DummyText.mdx`              → `ui/dummytext`
  */
 const PRESERVE_CASE_PREFIXES = ['primitives/', 'trait-class/'];
 export function sourcePathToUrlSlug(sourcePath) {

package/dist/tools/convert-css.js

@@ -3,7 +3,6 @@ import { loadPropsMarkdown } from '../lib/load-markdown.js';
 import { parsePropRows } from '../lib/markdown-utils.js';
 import { MetaInfoSchema } from '../lib/schemas.js';
 import { success, error, READ_ONLY_ANNOTATIONS } from '../lib/response.js';
-/** 変換結果の1行 */
 const ConversionEntrySchema = z.object({
     css: z.string(),
     lismProp: z.string().nullable(),
@@ -12,7 +11,6 @@ const ConversionEntrySchema = z.object({
     confidence: z.enum(['exact', 'approximate', 'unmapped']),
     note: z.string(),
 });
-/** コンポーネント提案 */
 const ComponentSuggestionSchema = z.object({
     name: z.string(),
     reason: z.string(),
@@ -21,7 +19,6 @@ const ComponentSuggestionSchema = z.object({
 // ----------------------------------------------------------------
 // CSS パース
 // ----------------------------------------------------------------
-/** @ルール（@media 等）が含まれていないか検査する */
 function detectAtRules(cssText) {
     const atRuleMatch = cssText.match(/^@(\w[\w-]*)/m);
     if (atRuleMatch) {
@@ -29,16 +26,12 @@ function detectAtRules(cssText) {
     }
     return null;
 }
-/**
- * CSS テキストから宣言を抽出する。
- * `;` で分割する際に `url()` 等の括弧内の `;` を無視する。
- */
+/** CSSテキストから宣言を抽出する。url()などの括弧内にある`;`は区切りとみなさない。 */
 function parseCssDeclarations(cssText) {
-    // コメント除去
+    // コメントとセレクタの外枠を取り除く。
     let cleaned = cssText.replace(/\/\*[\s\S]*?\*\//g, '');
-    // セレクタ + ブレースを除去（裸の宣言リストも受け付ける）
     cleaned = cleaned.replace(/[^{}]*\{/g, '').replace(/\}/g, '');
-    // 括弧のネストを考慮して `;` で分割
+    // 括弧の深さを追いながら宣言単位に分ける。
     const segments = [];
     let current = '';
     let parenDepth = 0;
@@ -72,12 +65,10 @@ function parseCssDeclarations(cssText) {
     }
     return declarations;
 }
-/** プリセット値列から値を抽出する（例: "-fz:base, -fz:5xl" → ["base", "5xl"]） */
 function extractPresetValues(presetColumn, propName) {
     if (!presetColumn || presetColumn === '—' || presetColumn === '-')
         return [];
     const values = [];
-    // -{prop}:{value} パターンを全て抽出
     const escaped = propName.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
     const regex = new RegExp(`-${escaped}:([^,\\s\`〜]+)`, 'g');
     let match;
@@ -98,7 +89,6 @@ function buildCssPropertyMap(mappings) {
     const map = new Map();
     for (const mapping of mappings) {
         const normalized = mapping.cssProperty.toLowerCase();
-        // CSS カスタムプロパティ形式はスキップ（"--hl" 等）
         if (!normalized.startsWith('(class:')) {
             map.set(normalized, mapping);
         }
@@ -108,7 +98,6 @@ function buildCssPropertyMap(mappings) {
 // ----------------------------------------------------------------
 // 値のマッピング
 // ----------------------------------------------------------------
-/** よくある CSS 値 → Lism トークン値の変換テーブル */
 const VALUE_ALIASES = {
     'space-between': 'between',
     currentcolor: 'current',
@@ -119,10 +108,8 @@ function suggestValue(mapping, cssValue) {
     const tokens = mapping.presetValues;
     if (tokens.length === 0)
         return null;
-    // 直接一致
     if (tokens.includes(cssValue))
         return cssValue;
-    // エイリアス変換後に一致
     const aliased = VALUE_ALIASES[cssValue.toLowerCase()];
     if (aliased && tokens.includes(aliased))
         return aliased;
@@ -131,12 +118,12 @@ function suggestValue(mapping, cssValue) {
 // ----------------------------------------------------------------
 // コンポーネント検出
 // ----------------------------------------------------------------
+/** display関連の宣言から利用できるLismレイアウトコンポーネントを提案する。 */
 function detectComponent(declarations) {
     const propMap = new Map(declarations.map((d) => [d.property, d.value.toLowerCase()]));
     const display = propMap.get('display');
     const flexDirection = propMap.get('flex-direction');
     const placeItems = propMap.get('place-items');
-    // Stack: flex + column
     if (display === 'flex' && (flexDirection === 'column' || flexDirection === 'column-reverse')) {
         return {
             name: 'Stack',
@@ -144,7 +131,6 @@ function detectComponent(declarations) {
             implicitCss: ['display: flex', 'flex-direction: column'],
         };
     }
-    // Center: grid + place-items: center
     if (display === 'grid' && placeItems === 'center') {
         return {
             name: 'Center',
@@ -152,7 +138,6 @@ function detectComponent(declarations) {
             implicitCss: ['display: grid', 'place-items: center'],
         };
     }
-    // Flex
     if (display === 'flex') {
         return {
             name: 'Flex',
@@ -160,7 +145,6 @@ function detectComponent(declarations) {
             implicitCss: ['display: flex'],
         };
     }
-    // Grid
     if (display === 'grid') {
         return {
             name: 'Grid',
@@ -177,6 +161,7 @@ function findCategory(mappings, propName) {
     const found = mappings.find((m) => m.prop === propName);
     return found?.sectionName ?? 'unknown';
 }
+/** 変換結果からJSX使用例を組み立てる。 */
 function buildExample(conversions, component) {
     const tagName = component?.name ?? 'Lism';
     const implicitCssSet = new Set(component?.implicitCss.map((c) => c.split(':')[0].trim()) ?? []);
@@ -188,7 +173,7 @@ function buildExample(conversions, component) {
             styles.push(conv.css);
             continue;
         }
-        // コンポーネントが暗黙的に付与する CSS はスキップ
+        // コンポーネントが暗黙に持つCSSは重複出力しない。
         if (implicitCssSet.has(cssProp))
             continue;
         if (conv.suggestedValue != null) {
@@ -232,7 +217,6 @@ export function registerConvertCss(server) {
         annotations: READ_ONLY_ANNOTATIONS,
     }, ({ css }) => {
         try {
-            // @ ルール検出
             const atRuleError = detectAtRules(css);
             if (atRuleError) {
                 return error(atRuleError);
@@ -244,7 +228,7 @@ export function registerConvertCss(server) {
             if (declarations.length === 0) {
                 return error('No CSS declarations found. Provide CSS in "property: value;" format.');
             }
-            // 各宣言を変換
+            // 各宣言をLism Propと候補値へ変換する。
             const conversions = declarations.map((decl) => {
                 const mapping = cssPropertyMap.get(decl.property);
                 if (!mapping) {
@@ -272,9 +256,8 @@ export function registerConvertCss(server) {
                             : `Use as a custom value (category: ${category})`,
                 };
             });
-            // コンポーネント検出
+            // 変換結果からコンポーネント候補と使用例を組み立てる。
             const suggestedComponent = detectComponent(declarations);
-            // 使用例
             const example = buildExample(conversions, suggestedComponent);
             return success({
                 conversions,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lism-css/mcp",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "MCP server for lism-css documentation and API reference.",
   "keywords": [
     "mcp",