@central-design-system/skills 4.0.0-alpha.6

package/skills/cds-builder/scripts/check-contracts.mjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+/**
+ * CDS contract linter — checks Cds* component usage in .vue files against
+ * the generated API reference of this skill (`references/components/*/api.md`).
+ *
+ * An invented prop or event does not throw at runtime — it is silently
+ * ignored, which is the most common cause of "why doesn't it work". This
+ * script catches that mechanically:
+ *
+ *   node scripts/check-contracts.mjs src/components/MyForm.vue
+ *   node scripts/check-contracts.mjs src/            # walks *.vue recursively
+ *
+ * Exit code 0 — everything matches the contracts; 1 — problems found;
+ * 2 — could not run (no reference, no input files).
+ *
+ * The reference is resolved relative to this script, so the linter works
+ * wherever the skill directory is installed. No dependencies, Node >= 18.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REFERENCES = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'references', 'components');
+
+/** Attributes legal on any component: passed through to the DOM or Vue built-ins. */
+const PASS_THROUGH = new Set([
+  'class',
+  'style',
+  'id',
+  'ref',
+  'key',
+  'is',
+  'name',
+  'title',
+  'role',
+  'tabindex',
+  'type',
+  'autofocus',
+  'for',
+  'slot'
+]);
+const PASS_PREFIXES = ['aria-', 'data-', 'v-'];
+
+/**
+ * Native HTML attributes that legitimately fall through to the inner
+ * element (Vue fallthrough attrs): `maxlength` on a text field, `target`
+ * on a link, a static `value` in display-only examples. They are not part
+ * of the CDS contract, but they are not invented API either.
+ */
+const NATIVE_ATTRS = new Set([
+  'href',
+  'target',
+  'rel',
+  'download',
+  'value',
+  'placeholder',
+  'maxlength',
+  'minlength',
+  'min',
+  'max',
+  'step',
+  'pattern',
+  'rows',
+  'cols',
+  'wrap',
+  'accept',
+  'multiple',
+  'autocomplete',
+  'inputmode',
+  'enterkeyhint',
+  'spellcheck',
+  'autocapitalize',
+  'list',
+  'form',
+  'alt',
+  'src',
+  'width',
+  'height',
+  'loading',
+  'draggable',
+  'lang',
+  'dir',
+  'required',
+  'readonly',
+  'disabled'
+]);
+
+/** Native DOM events that components re-emit or that land on the root element. */
+const NATIVE_EVENTS = new Set([
+  'click',
+  'dblclick',
+  'submit',
+  'input',
+  'change',
+  'focus',
+  'blur',
+  'keydown',
+  'keyup',
+  'keypress',
+  'mousedown',
+  'mouseup',
+  'mouseenter',
+  'mouseleave',
+  'mousemove',
+  'touchstart',
+  'touchend',
+  'scroll',
+  'wheel',
+  'dragstart',
+  'dragend',
+  'drop',
+  'contextmenu'
+]);
+
+const kebabToCamel = (s) => s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+const kebabToPascal = (s) => s.replace(/(?:^|-)([a-z0-9])/g, (_, c) => c.toUpperCase());
+
+/**
+ * Contract index: component name (`CdsSelect`) → { props, events, slots, file }.
+ * One api.md often documents a whole family (`cds-tabs/api.md` → CdsTabs,
+ * CdsTab, CdsTabsView…), so every `## CdsX` section is indexed separately.
+ */
+function buildContractIndex() {
+  const index = new Map();
+  if (!existsSync(REFERENCES)) return index;
+
+  for (const dir of readdirSync(REFERENCES)) {
+    const apiFile = join(REFERENCES, dir, 'api.md');
+    if (!existsSync(apiFile)) continue;
+    const text = readFileSync(apiFile, 'utf-8');
+
+    for (const section of text.split(/^## (?=Cds)/m).slice(1)) {
+      const name = section.slice(0, section.indexOf('\n')).trim();
+      const contract = {
+        props: new Set(),
+        events: new Set(),
+        slots: new Set(),
+        file: `references/components/${dir}/api.md`
+      };
+
+      for (const [label, key] of [
+        ['Props', 'props'],
+        ['Events', 'events'],
+        ['Slots', 'slots']
+      ]) {
+        const match = section.match(new RegExp(`\\*\\*${label}\\*\\*\\n\\n((?:\\|.*\\n)+)`));
+        if (!match) continue;
+        for (const line of match[1].split('\n').slice(2)) {
+          const cell = line.split('|')[1]?.trim().replace(/`/g, '');
+          if (cell) contract[key].add(cell);
+        }
+      }
+
+      index.set(name, contract);
+    }
+  }
+
+  return index;
+}
+
+const TAG_RE = /<(Cds[A-Za-z0-9]+|cds-[a-z0-9-]+)((?:[^>"']|"[^"]*"|'[^']*')*?)\/?>/gs;
+const ATTR_RE = /(?:^|\s)([@:#]?[\w:.-]+)(?:=(?:"[^"]*"|'[^']*'))?/g;
+
+function checkFile(path, index) {
+  const source = readFileSync(path, 'utf-8');
+  const problems = [];
+
+  for (const tag of source.matchAll(TAG_RE)) {
+    let [, component, attrs] = tag;
+    if (component.startsWith('cds-')) component = kebabToPascal(component);
+    const line = source.slice(0, tag.index).split('\n').length;
+
+    // Транзишены (CdsTransitionFade, …) — экспорт библиотеки, но не
+    // компоненты справочника: у них нет собственного api.md.
+    if (component.startsWith('CdsTransition')) continue;
+
+    const contract = index.get(component);
+    if (!contract) {
+      problems.push({ line, component, kind: 'component', name: component });
+      continue;
+    }
+
+    for (const attr of attrs.matchAll(ATTR_RE)) {
+      const raw = attr[1];
+      if (!raw || raw === '/') continue;
+      const isEvent = raw.startsWith('@');
+      let name = raw.replace(/^[@:#]/, '').split('.')[0];
+      if (!name || raw.startsWith('#')) continue; // slot shorthand lives on <template>
+      if (raw.startsWith('v-') || PASS_PREFIXES.some((p) => name.startsWith(p)) || PASS_THROUGH.has(name)) continue;
+
+      if (isEvent) {
+        const known =
+          contract.events.has(name) ||
+          contract.events.has(kebabToCamel(name)) ||
+          name.startsWith('update:') ||
+          NATIVE_EVENTS.has(name);
+        if (!known) problems.push({ line, component, kind: 'event', name, file: contract.file });
+      } else if (!contract.props.has(name) && !contract.props.has(kebabToCamel(name)) && !NATIVE_ATTRS.has(name)) {
+        problems.push({ line, component, kind: 'prop', name, file: contract.file });
+      }
+    }
+  }
+
+  return problems;
+}
+
+function collectVueFiles(paths) {
+  const files = [];
+  const walk = (p) => {
+    const stat = statSync(p);
+    if (stat.isDirectory()) {
+      for (const entry of readdirSync(p)) {
+        if (entry === 'node_modules' || entry.startsWith('.')) continue;
+        walk(join(p, entry));
+      }
+    } else if (p.endsWith('.vue')) {
+      files.push(p);
+    }
+  };
+  for (const p of paths) {
+    if (existsSync(p)) walk(p);
+    else console.error(`! not found: ${p}`);
+  }
+  return files;
+}
+
+const args = process.argv.slice(2);
+if (args.length === 0) {
+  console.error('Usage: node check-contracts.mjs <file.vue | dir> [...]');
+  process.exit(2);
+}
+
+const index = buildContractIndex();
+if (index.size === 0) {
+  console.error(`! contract reference not found at ${REFERENCES} — is the cds-builder skill installed completely?`);
+  process.exit(2);
+}
+
+const files = collectVueFiles(args);
+if (files.length === 0) {
+  console.error('! no .vue files found in the given paths');
+  process.exit(2);
+}
+
+let total = 0;
+for (const file of files) {
+  const problems = checkFile(file, index);
+  total += problems.length;
+  for (const p of problems) {
+    if (p.kind === 'component') {
+      console.log(`${file}:${p.line} — component <${p.name}> does not exist in CDS`);
+    } else {
+      console.log(`${file}:${p.line} — <${p.component}> has no ${p.kind} \`${p.name}\` (see ${p.file})`);
+    }
+  }
+}
+
+if (total === 0) {
+  console.log(`✓ ${files.length} file(s) checked — every component, prop and event exists in the contracts`);
+} else {
+  console.log(`✗ ${total} problem(s): an unknown prop/event is silently ignored at runtime — fix or remove it`);
+  process.exit(1);
+}

package/skills/cds-migrate/GENERATION.md

@@ -0,0 +1,44 @@
+# Генерация скиллов CDS
+
+- Версия `@central-design-system/components`: 4.0.0-alpha.6
+- Скиллы в пакете: cds-builder, cds-migrate, cds-refactor
+
+## Статистика
+
+- Семейств компонентов: 79
+- Контрактов meta.json: 125
+- Извлечено примеров: 710
+- Пропущено историй (неожиданная форма):
+  - нет
+
+## Полнота документации
+
+Счётчики ниже — долг документации, а не ошибка генерации: справочники
+собираются из того, что заполнено, и растут по мере переработки страниц
+компонентов.
+
+- Описание («что это и когда брать»): 77 из 79
+- Подсказка «Смотрите также»: 77 из 79
+- Рекомендации Do/Don't: 60 из 79 (пар правил: 169)
+- Props/events/slots/exposed без описания: 0
+- Без описания: CdsApp, CdsDefaultsProvider
+- Без рекомендаций: CdsApp, CdsButtonGroup, CdsCheckboxButton, CdsCounter, CdsDefaultsProvider, CdsDescription, CdsField, CdsInput, CdsLabel, CdsLoader, CdsMain, CdsMessages, CdsNotificationAlert, CdsPage, CdsRadio, CdsSelectionControl, CdsSelectionControlGroup, CdsSurface, CdsToastQueue
+- Без примеров: CdsApp, CdsDefaultsProvider, CdsRadio
+
+## Перевод (en)
+
+Генераторы читают английские страницы (`docs/en/`) и `@en` из JSDoc; там, где
+перевода ещё нет, подставляется русский текст — это долг перевода.
+
+- Страниц компонентов переведено: 77 из 79
+- Страниц: 107 — ok 101, outdated 0, drift 0, missing 6
+- Props/events/slots/exposed без `@en`: 0
+- Подписи DoDont/AnatomyDemo без `-en`/`labelEn`: 9
+
+## Регенерация
+
+```bash
+cd packages/components
+bun run generate:meta   # если менялись компоненты
+bun run generate:skill
+```

package/skills/cds-migrate/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: cds-migrate
+description: >-
+  Migrating a project from CDS 3 to CDS 4 (`@central-design-system/components`,
+  Central Design System, B2B-Center): package upgrade, style entry points,
+  component and prop renames, icons, CSS architecture, composables and hooks.
+  Use this skill when the user bumps the CDS version, hits breakage after an
+  upgrade, sees a `[CDS UPGRADE]` warning in the console, or uses CDS 3
+  patterns — `@central-design-system/components/dist/cds.css`,
+  `@central-design-system/icons`, `CdsDropdown`, `CdsRadioButton`,
+  `CdsProgress`, `CdsTabsV2`, `CdsCheckboxGroup`, `CdsContainer` — even if the
+  words "migration" or "upgrade" were never said. RU triggers: «мигрируй с
+  CDS 3», «обнови CDS до 4», «после обновления CDS сломались стили»,
+  «не находит dist/cds.css», «что изменилось в CDS 4», «CdsDropdown не
+  работает», «предупреждение CDS UPGRADE». EN triggers: «migrate to CDS 4»,
+  «upgrade central design system», «breaking changes CDS 4».
+metadata:
+  author: cds-team
+  version: "4.0.0-alpha.6"
+  source: https://gitlab.b2b-center.ru/cds/central-design-system
+---
+
+# CDS 3 → CDS 4 migration
+
+You are migrating a project from CDS 3 to CDS 4 (version 4.0.0-alpha.6). Work
+step by step and do not guess the project's state — look at the code first.
+
+The full guide with every change and its Before / After pairs is
+`references/migration-full.md` (currently in Russian). This file covers the
+order of work and what comes up most often; when in doubt, open the full
+guide.
+
+---
+
+## Step 1 — Inspect the project
+
+Look at `package.json`:
+
+- the `@central-design-system/components` version (CDS 3 — `3.x`, CDS 4 —
+  `4.x`);
+- whether `@central-design-system/icons` is present (the package is deprecated
+  in CDS 4);
+- the bundler and framework, the package manager by the lock file.
+
+Then find the spots in the code that are guaranteed to change:
+
+```bash
+grep -rn "dist/cds.css\|@central-design-system/icons" src/
+grep -rn "CdsDropdown\|CdsRadioButton\|CdsProgress\|CdsTabsV2\|CdsCheckboxGroup\|CdsContainer" src/
+```
+
+Tell the user what you found before editing anything: the scope of the
+migration must be clear up front.
+
+---
+
+## Step 2 — Update the package and the style entry point
+
+The CSS import changed — this is the breaking change everyone hits:
+
+```ts
+// Before (CDS 3)
+import '@central-design-system/components/dist/cds.css';
+
+// After (CDS 4)
+import '@central-design-system/components/styles';
+```
+
+`dist/cds.css` is no longer a public entry point; the old path simply will
+not resolve.
+
+The global reset from CDS 3 is now **off by default**. If the layout "broke"
+after the upgrade, enable it explicitly:
+
+```scss
+@use '@central-design-system/components/styles' with ($legacy-reset: true);
+```
+
+---
+
+## Step 3 — Icons
+
+The `@central-design-system/icons` package is marked deprecated but keeps
+working through a legacy mode — icon migration can be deferred and done as a
+separate step. How to move to iconpacks via `createCds({ icons })` — section
+2 (Icons) of the full guide.
+
+---
+
+## Step 4 — Component renames
+
+| CDS 3 | CDS 4 |
+| --- | --- |
+| `CdsDropdown` | `CdsSelect` (native `<select>` — via the `native-select` prop) |
+| `CdsRadioButton` | `CdsRadioGroup` |
+| `CdsProgress` | `CdsProgressBar` |
+| `CdsTabsV2` | `CdsTabs` |
+| `CdsCheckboxGroup` | removed — use `CdsCheckbox` on its own |
+| `CdsContainer` | removed |
+
+Renaming is only the first step: **the new component's prop contract may have
+changed**. After replacing the name, check the component's `api.md` in the
+`cds-builder` skill (`../cds-builder/references/components/<slug>/api.md`). If
+`cds-builder` is not installed, the contracts are in the npm package:
+`node_modules/@central-design-system/components/llms/llms-components.txt`.
+
+Check `CdsBadge` separately: `count` → `content`, `limited` → `:max`, the
+`invertColor` prop was removed.
+
+---
+
+## Step 5 — Styles and tokens
+
+The CSS architecture moved to ITCSS and native `@layer`. The practical
+consequence: global overrides of CDS styles written without `!important` may
+stop applying — the cascade is now determined by layers. Section 4 (Styles
+and tokens) of the full guide describes how to override correctly.
+
+While you are at it, replace the remaining hardcoded colors with `--cds-*`
+tokens — theme switching in CDS 4 depends on them.
+
+---
+
+## Step 6 — Composables, hooks and exports
+
+Sections 5 (Composables), 6 (Hooks) and 7 (Build and exports) of the full
+guide. This is where import changes and public utility changes live — check
+them if the build complains about a missing export.
+
+---
+
+## Step 7 — Verification
+
+Go through the list and check off every item:
+
+- [ ] No `dist/cds.css` left in the code, styles are imported via `/styles`.
+- [ ] The application builds without import resolution errors.
+- [ ] Not a single old component name:
+      `grep -rn "CdsDropdown\|CdsRadioButton\|CdsProgress\b\|CdsTabsV2\|CdsCheckboxGroup\|CdsContainer" src/`
+- [ ] Dev mode was started, the console was reviewed: every `[CDS UPGRADE]`
+      warning is handled — it points at a deprecated prop.
+- [ ] The layout was checked visually: if it broke — look at `legacy-reset`
+      (step 2) or CSS layers (step 5).
+- [ ] Dark theme and theme switching work, if the project uses them.
+
+Report what remains open — an unfinished migration is worse than one never
+started if the user believes it is complete.
+
+---
+
+## When to ask
+
+Act on your own for mechanical replacements (paths, component names). Ask if:
+
+- the project overrides CDS styles and it is unclear which overrides are
+  intentional;
+- the migration touches many files and the user has not said whether to do
+  everything at once or in parts;
+- you hit a CDS 3 pattern the full guide does not cover — do not invent a
+  replacement, say so instead.