@birdapi/velinstyle 0.8.0 → 0.9.0

package/cli/docgen/markdown.js

@@ -0,0 +1,43 @@
+/**
+ * Minimal Markdown helpers for doc generation (stable sort, escaping).
+ */
+
+export function escapeCell(s) {
+  return String(s ?? '')
+    .replace(/\|/g, '\\|')
+    .replace(/\r?\n/g, ' ');
+}
+
+export function heading(level, text) {
+  const n = Math.min(6, Math.max(1, level));
+  return `${'#'.repeat(n)} ${text}\n`;
+}
+
+export function table(headers, rows) {
+  const h = headers.map(escapeCell);
+  const lines = [
+    `| ${h.join(' | ')} |`,
+    `| ${h.map(() => '---').join(' | ')} |`,
+  ];
+  for (const row of rows) {
+    lines.push(`| ${row.map(escapeCell).join(' | ')} |`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+export function bulletList(items) {
+  if (!items.length) return '_None._\n';
+  return `${items.map((i) => `- ${i}`).join('\n')}\n`;
+}
+
+export function codeBlock(lang, code) {
+  return `\`\`\`${lang}\n${code}\n\`\`\`\n`;
+}
+
+export function banner(source) {
+  return `<!-- Auto-generated by \`velinstyle docs generate\`. Do not edit. Source: ${source} -->\n\n`;
+}
+
+export function sortByKey(arr, key) {
+  return [...arr].sort((a, b) => String(a[key]).localeCompare(String(b[key])));
+}

package/cli/docs-generate.js

@@ -0,0 +1,196 @@
+import { mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { extractComponents, renderComponent, renderComponentsIndex } from './docgen/extract-components.js';
+import { extractTokens, renderTokenCategory, renderTokensIndex, renderJsonSchema } from './docgen/extract-tokens.js';
+import { extractUtilities, renderUtilityFile, renderUtilitiesIndex } from './docgen/extract-utilities.js';
+import { loadCliManifest, validateManifest, renderCliDocs } from './docgen/extract-cli.js';
+import { extractA11yModules, renderScannerRules, renderA11yModules } from './docgen/extract-rules.js';
+import { loadComponentContracts, renderWcagAaaMatrix } from './docgen/extract-a11y.js';
+import { banner, heading } from './docgen/markdown.js';
+import { buildSearchIndex } from './search-index.js';
+import { writeAttributesDocs } from './docgen/extract-attributes.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = join(__dirname, '..');
+
+const SCOPES = ['all', 'components', 'tokens', 'utilities', 'cli', 'rules', 'a11y', 'attributes', 'meta'];
+
+function writeFile(path, content) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content, 'utf-8');
+}
+
+function clearScopeDir(outDir, sub) {
+  const dir = join(outDir, sub);
+  if (existsSync(dir)) rmSync(dir, { recursive: true });
+  mkdirSync(dir, { recursive: true });
+}
+
+export async function generateDocs(options = {}) {
+  const scope = options.scope || 'all';
+  const outDir = options.outDir || join(PKG_ROOT, 'docs', 'generated');
+  const srcDir = join(PKG_ROOT, 'src');
+  const componentsDir = join(PKG_ROOT, 'components');
+  const written = [];
+
+  if (!SCOPES.includes(scope)) {
+    return { ok: false, error: `Unknown scope "${scope}". Use: ${SCOPES.join(', ')}` };
+  }
+
+  const run = (name) => scope === 'all' || scope === name;
+
+  if (run('components')) {
+    clearScopeDir(outDir, 'components');
+    const contracts = loadComponentContracts(PKG_ROOT);
+    const components = extractComponents(componentsDir);
+    for (const c of components) {
+      const p = join(outDir, 'components', `${c.tag}.md`);
+      writeFile(p, renderComponent(c, contracts));
+      written.push(p);
+    }
+    const indexPath = join(outDir, 'components', 'README.md');
+    writeFile(indexPath, renderComponentsIndex(components));
+    written.push(indexPath);
+  }
+
+  if (run('tokens')) {
+    clearScopeDir(outDir, 'tokens');
+    const extracted = extractTokens(srcDir);
+    for (const cat of extracted.categories) {
+      const p = join(outDir, 'tokens', `${cat}.md`);
+      writeFile(p, renderTokenCategory(cat, extracted.byCategory[cat]));
+      written.push(p);
+    }
+    const indexPath = join(outDir, 'tokens', 'README.md');
+    writeFile(indexPath, renderTokensIndex(extracted));
+    written.push(indexPath);
+
+    const schemaPath = join(PKG_ROOT, 'examples', 'tokens.schema.json');
+    if (existsSync(schemaPath)) {
+      const schemaMd = join(outDir, 'tokens', 'json-schema.md');
+      writeFile(
+        schemaMd,
+        renderJsonSchema('examples/tokens.schema.json', readFileSync(schemaPath, 'utf-8')),
+      );
+      written.push(schemaMd);
+    }
+  }
+
+  if (run('utilities')) {
+    clearScopeDir(outDir, 'utilities');
+    const extracted = extractUtilities(srcDir);
+    for (const cat of extracted.files) {
+      const p = join(outDir, 'utilities', `${cat}.md`);
+      writeFile(p, renderUtilityFile(cat, extracted.byFile[cat]));
+      written.push(p);
+    }
+    const indexPath = join(outDir, 'utilities', 'README.md');
+    writeFile(indexPath, renderUtilitiesIndex(extracted));
+    written.push(indexPath);
+  }
+
+  if (run('cli')) {
+    mkdirSync(join(outDir, 'cli'), { recursive: true });
+    const manifest = loadCliManifest();
+    const errors = validateManifest(manifest);
+    if (errors.length) {
+      return { ok: false, error: errors.join('; ') };
+    }
+    const p = join(outDir, 'cli', 'commands.md');
+    writeFile(p, renderCliDocs(manifest));
+    written.push(p);
+  }
+
+  if (run('rules')) {
+    mkdirSync(join(outDir, 'rules'), { recursive: true });
+    const p = join(outDir, 'rules', 'scanner.md');
+    writeFile(p, renderScannerRules());
+    written.push(p);
+  }
+
+  if (run('a11y')) {
+    mkdirSync(join(outDir, 'a11y'), { recursive: true });
+    const modules = extractA11yModules(srcDir);
+    const p = join(outDir, 'a11y', 'modules.md');
+    writeFile(p, renderA11yModules(modules));
+    written.push(p);
+    const contracts = loadComponentContracts(PKG_ROOT);
+    const matrixPath = join(outDir, 'a11y', 'wcag22-aaa-matrix.md');
+    writeFile(matrixPath, renderWcagAaaMatrix(contracts));
+    written.push(matrixPath);
+  }
+
+  if (run('attributes')) {
+    mkdirSync(join(outDir, 'attributes'), { recursive: true });
+    for (const { path: p, content } of writeAttributesDocs(outDir)) {
+      writeFile(p, content);
+      written.push(p);
+    }
+  }
+
+  if (run('meta')) {
+    mkdirSync(join(outDir, 'meta'), { recursive: true });
+    const { buildAgentBundle } = await import('../core/meta/index.js');
+    const { renderMetaReadme } = await import('./docgen/extract-meta.js');
+    const bundle = await buildAgentBundle({ pkgRoot: PKG_ROOT });
+    const readmePath = join(outDir, 'meta', 'README.md');
+    writeFile(readmePath, renderMetaReadme(bundle));
+    written.push(readmePath);
+    try {
+      const { buildMeta } = await import('./meta.js');
+      const metaOut = await buildMeta({
+        outFile: join(PKG_ROOT, 'dist', 'velin-agent.json'),
+        llmsFile: join(PKG_ROOT, 'dist', 'llms.txt'),
+      });
+      written.push(...metaOut.written);
+    } catch (err) {
+      console.warn('velin-agent.json:', err.message);
+    }
+  }
+
+  if (scope === 'all') {
+    let root = banner('velinstyle docs generate');
+    root += heading(1, 'VelinStyle generated reference');
+    root += '\n> **Do not edit manually.** Regenerate with `npm run docs:generate` or `velinstyle docs generate`.\n\n';
+    root += '| Section | Description |\n| --- | --- |\n';
+    root += '| [components](./components/) | Web Components API |\n';
+    root += '| [tokens](./tokens/) | Design tokens (`--velin-*`) |\n';
+    root += '| [utilities](./utilities/) | Utility classes |\n';
+    root += '| [cli](./cli/) | CLI commands |\n';
+    root += '| [rules](./rules/) | Scanner & perf rules |\n';
+    root += '| [a11y](./a11y/) | Accessibility CSS modules |\n';
+    root += '| [attributes](./attributes/) | Velin HTML attribute extensions |\n';
+    root += '| [meta](./meta/) | Velin-Meta agent context (AI assistants) |\n';
+    writeFile(join(outDir, 'README.md'), root);
+    written.push(join(outDir, 'README.md'));
+  }
+
+  if (options.searchIndex !== false && (scope === 'all' || scope === 'components' || scope === 'meta')) {
+    try {
+      const idx = buildSearchIndex({
+        generatedDir: outDir,
+        outFile: join(PKG_ROOT, 'dist', 'search-index.json'),
+      });
+      written.push(idx.outFile);
+    } catch (err) {
+      console.warn('search index:', err.message);
+    }
+  }
+
+  return { ok: true, written: written.length, paths: written };
+}
+
+export async function docsGenerateMain(argv = process.argv.slice(2)) {
+  const scopeIdx = argv.indexOf('--scope');
+  const outIdx = argv.indexOf('--out');
+  const scope = scopeIdx !== -1 && argv[scopeIdx + 1] ? argv[scopeIdx + 1] : 'all';
+  const outDir = outIdx !== -1 && argv[outIdx + 1] ? argv[outIdx + 1] : join(PKG_ROOT, 'docs', 'generated');
+
+  const result = await generateDocs({ scope, outDir });
+  if (!result.ok) {
+    console.error(result.error);
+    process.exit(1);
+  }
+  console.log(`Generated ${result.written} file(s) in ${outDir}`);
+}

package/cli/index.js

@@ -15,7 +15,7 @@ const LAYERS = ['tokens', 'reset', 'base', 'a11y', 'layout', 'components', 'util
 
 const LAYER_FILES = {
   tokens: [
-    'tokens/color.css', 'tokens/spacing.css', 'tokens/typography.css',
+    'tokens/fonts.css', 'tokens/color.css', 'tokens/spacing.css', 'tokens/typography.css',
     'tokens/radius.css', 'tokens/shadow.css', 'tokens/motion.css',
     'tokens/z-index.css', 'tokens/aspect-ratio.css',
   ],
@@ -25,6 +25,8 @@ const LAYER_FILES = {
     'a11y/sr-only.css', 'a11y/skip-link.css', 'a11y/reduced-motion.css',
     'a11y/forced-colors.css', 'a11y/skeleton.css', 'a11y/preferences.css',
     'a11y/focus-not-obscured.css', 'a11y/target-size.css', 'a11y/high-contrast-aaa.css',
+    'a11y/authentication.css', 'a11y/consistent-help.css', 'a11y/dragging-alternatives.css',
+    'a11y/focus-appearance.css',
   ],
   security: ['a11y/security.css'],
   layout: [
@@ -47,8 +49,9 @@ const LAYER_FILES = {
     'utilities/position.css', 'utilities/animation.css', 'utilities/gradient.css',
     'utilities/print.css', 'utilities/responsive.css', 'utilities/divide.css',
     'utilities/scroll.css', 'utilities/color-mix.css', 'utilities/scroll-animation.css',
-    'utilities/view-transition.css', 'utilities/scope.css', 'utilities/anchor.css',
-    'utilities/filter.css', 'utilities/container-style.css', 'utilities/state.css',
+    'utilities/view-transition.css',     'utilities/scope.css', 'utilities/anchor.css',
+    'utilities/filter.css', 'utilities/filter-effects.css', 'utilities/chart-animation.css',
+    'utilities/container-style.css', 'utilities/state.css',
     'utilities/safe-area.css',
   ],
   helpers: ['helpers/helpers.css'],
@@ -80,7 +83,7 @@ function hasFlag(flag, alias) {
 
 function help() {
   console.log(`
-  ${C.bold('VelinStyle CLI')} v0.8.0
+  ${C.bold('VelinStyle CLI')} v0.9.0
 
   ${C.bold('Usage:')}
     velinstyle init                 Create velinstyle.config.js
@@ -93,7 +96,12 @@ function help() {
     velinstyle blueprint [name]     Print HTML blueprint (run: velinstyle blueprint list)
     velinstyle scaffold "<prompt>"  Generate layout HTML from a text description
     velinstyle layout <sub>         Responsive layout audit and fixes
+    velinstyle perf <sub>           Performance audit (images, scripts) with --fix
     velinstyle tokens build         Generate CSS variables from tokens.json
+    velinstyle tokens validate      Validate tokens.json schema
+    velinstyle docs generate        Auto-generate Markdown API reference
+    velinstyle meta                 Build agent context (velin-agent.json, llms.txt)
+    velinstyle search index         Build JSON search index for VelinSearch
 
   ${C.bold('Icons subcommands:')}
     icons list                      Show available icon providers
@@ -120,14 +128,29 @@ function help() {
     velinstyle layout suggest [path]  Audit with fix suggestions
     velinstyle layout fix [path]      Apply safe fixes (--dry-run default, --write)
 
+  ${C.bold('Performance (0.9.0):')}
+    velinstyle perf audit [path]      Report CLS, lazy-load, script defer issues
+    velinstyle perf suggest [path]    Same as audit with fix hints
+    velinstyle perf fix [path]        Apply safe fixes (--write)
+
   ${C.bold('Tokens:')}
     velinstyle tokens build [--input <path>] [--output, -o <file>]
+    velinstyle tokens validate [--input <path>]
+
+  ${C.bold('Docs (0.9.0):')}
+    velinstyle docs generate [--scope all|components|tokens|utilities|cli|rules|a11y|meta] [--out docs/generated]
+    velinstyle meta [--out dist/velin-agent.json] [--llms-out dist/llms.txt] [--base-url URL]
+    velinstyle meta page <file.html> [--write]
+
+  ${C.bold('Search:')}
+    velinstyle search index [--out dist/search-index.json] [--extra-html dir1,dir2]
 
   ${C.bold('Scan options:')}
     --fix                           Auto-fix safe issues (writes files)
     --fix-dry-run                   Show files that would be auto-fixed; no write
     --fix-lang <code>               Default lang for a11y/html-lang fix (default: de)
     --severity <level>              Minimum severity: error, warning, info
+    --only <category>               Filter: security, pii, a11y, css, perf
 
   ${C.bold('Prefix options (velinstyle prefix):')}
     --write                         Write files (default is dry-run)
@@ -470,13 +493,64 @@ async function tokensBuildCmd() {
   }
 }
 
+async function tokensValidateCmd() {
+  const input = getArg('--input') || 'examples/tokens.sample.json';
+  const { validateTokensJson } = await import('./tokens-validate.js');
+  const result = validateTokensJson(resolve(input));
+  if (result.ok) {
+    console.log(C.green(`Valid: ${resolve(input)}`));
+    process.exit(0);
+  }
+  console.log(C.red(`Invalid: ${resolve(input)}`));
+  result.errors.forEach((e) => console.log(`  - ${e}`));
+  process.exit(1);
+}
+
 async function tokensCmd() {
   const sub = args[1];
   if (sub === 'build') {
     await tokensBuildCmd();
+  } else if (sub === 'validate') {
+    await tokensValidateCmd();
   } else {
-    console.log('Usage: velinstyle tokens build [--input tokens.json] [--output out.css]');
+    console.log('Usage: velinstyle tokens build|validate [--input tokens.json] [--output, -o <file>]');
+  }
+}
+
+async function perfCmd() {
+  const sub = args[1] || 'audit';
+  const rawTarget = args[2] && !args[2].startsWith('-') ? args[2] : '.';
+  const targetPath = resolve(rawTarget);
+  const asJson = hasFlag('--json');
+  const write = hasFlag('--write');
+  const dryRun = hasFlag('--dry-run') || !write;
+
+  const { auditPath, formatTextReport, fixPath } = await import('./perf-audit.js');
+
+  if (sub === 'fix') {
+    const result = fixPath(targetPath, { write, dryRun });
+    if (asJson) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    if (result.changes.length === 0) {
+      console.log(C.green('No safe performance fixes to apply.'));
+      return;
+    }
+    for (const c of result.changes) {
+      console.log(`${dryRun ? '[dry-run] ' : ''}${c.file}`);
+      c.changes.forEach((ch) => console.log(C.dim(`  - ${ch}`)));
+    }
+    return;
   }
+
+  const { issues, files } = auditPath(targetPath);
+  if (asJson) {
+    console.log(JSON.stringify({ files, issues }, null, 2));
+    return;
+  }
+  console.log(formatTextReport(issues, files));
+  process.exit(issues.some((x) => x.severity === 'error') ? 1 : 0);
 }
 
 async function prefixCmd() {
@@ -608,6 +682,44 @@ async function layoutCmd() {
   process.exit(issues.some((x) => x.severity === 'error') ? 1 : 0);
 }
 
+async function docsCmd() {
+  const sub = args[1];
+  if (sub === 'generate') {
+    const scope = getArg('--scope') || 'all';
+    const out = getArg('--out') || join(PKG_ROOT, 'docs', 'generated');
+    const { generateDocs } = await import('./docs-generate.js');
+    const result = await generateDocs({ scope, outDir: resolve(out), searchIndex: true });
+    if (!result.ok) {
+      console.log(C.red(result.error));
+      process.exit(1);
+    }
+    console.log(C.green(`Generated ${result.written} file(s) → ${resolve(out)}`));
+    return;
+  }
+  console.log('Usage: velinstyle docs generate [--scope all|components|tokens|utilities|cli|rules|a11y|meta] [--out <dir>]');
+}
+
+async function metaCmd() {
+  const { metaMain } = await import('./meta.js');
+  await metaMain(process.argv.slice(2));
+}
+
+async function searchCmd() {
+  const sub = args[1];
+  if (sub === 'index') {
+    const out = getArg('--out') || join(PKG_ROOT, 'dist', 'search-index.json');
+    const extra = getArg('--extra-html');
+    const { buildSearchIndex } = await import('./search-index.js');
+    const result = buildSearchIndex({
+      outFile: resolve(out),
+      extraHtmlDirs: extra ? extra.split(',').map((p) => resolve(p.trim())) : [],
+    });
+    console.log(C.green(`Search index: ${result.count} entries → ${result.outFile}`));
+    return;
+  }
+  console.log('Usage: velinstyle search index [--out <file>] [--extra-html dir1,dir2]');
+}
+
 async function scanCmd() {
   const targetPath = args[1] && !args[1].startsWith('-') ? resolve(args[1]) : resolve('.');
   const format = getArg('--format') || 'text';
@@ -647,6 +759,10 @@ switch (command) {
   case 'prefix': await prefixCmd(); break;
   case 'scaffold': await scaffoldCmd(); break;
   case 'layout': await layoutCmd(); break;
+  case 'perf': await perfCmd(); break;
+  case 'docs': await docsCmd(); break;
+  case 'meta': await metaCmd(); break;
+  case 'search': await searchCmd(); break;
   case '--help': case '-h': help(); break;
   default: help(); break;
 }

package/cli/meta.js

@@ -0,0 +1,97 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join, dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { buildAgentBundle, buildLlmsTxt, buildPageMeta, serializePageMetaScript } from '../core/meta/index.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = join(__dirname, '..');
+
+/**
+ * @param {object} [options]
+ * @param {string} [options.outFile]
+ * @param {string} [options.llmsFile]
+ * @param {string} [options.baseUrl]
+ * @param {boolean} [options.llms]
+ */
+export async function buildMeta(options = {}) {
+  const outFile = options.outFile || join(PKG_ROOT, 'dist', 'velin-agent.json');
+  const llmsFile = options.llmsFile || join(PKG_ROOT, 'dist', 'llms.txt');
+  const bundle = await buildAgentBundle({ pkgRoot: PKG_ROOT });
+
+  mkdirSync(dirname(outFile), { recursive: true });
+  writeFileSync(outFile, JSON.stringify(bundle, null, 2), 'utf-8');
+
+  const written = [outFile];
+
+  if (options.llms !== false) {
+    const llms = buildLlmsTxt(bundle, options.baseUrl || 'https://velinstyle.info');
+    writeFileSync(llmsFile, llms, 'utf-8');
+    written.push(llmsFile);
+  }
+
+  return { ok: true, bundle, written, count: written.length };
+}
+
+/**
+ * @param {string} htmlPath
+ * @param {object} [options]
+ */
+export function metaPage(htmlPath, options = {}) {
+  const abs = resolve(htmlPath);
+  if (!existsSync(abs)) {
+    return { ok: false, error: `File not found: ${abs}` };
+  }
+  const html = readFileSync(abs, 'utf-8');
+  const rel = htmlPath.replace(/\\/g, '/');
+  const meta = buildPageMeta(html, rel, PKG_ROOT);
+  const script = serializePageMetaScript(meta);
+
+  if (options.write) {
+    if (html.includes('id="velin-meta"')) {
+      const updated = html.replace(
+        /<script[^>]*id=["']velin-meta["'][^>]*>[\s\S]*?<\/script>/i,
+        script,
+      );
+      writeFileSync(abs, updated, 'utf-8');
+    } else if (/<\/head>/i.test(html)) {
+      writeFileSync(abs, html.replace(/<\/head>/i, `  ${script}\n</head>`), 'utf-8');
+    } else {
+      return { ok: false, error: 'No </head> or existing velin-meta block found' };
+    }
+  }
+
+  return { ok: true, meta, script };
+}
+
+export async function metaMain(argv = process.argv.slice(2)) {
+  const pageIdx = argv.indexOf('page');
+  if (pageIdx !== -1 && argv[pageIdx + 1]) {
+    const write = argv.includes('--write');
+    const result = metaPage(argv[pageIdx + 1], { write });
+    if (!result.ok) {
+      console.error(result.error);
+      process.exit(1);
+    }
+    if (write) {
+      console.log(`Updated velin-meta in ${argv[pageIdx + 1]}`);
+    } else {
+      console.log(result.script);
+    }
+    return;
+  }
+
+  const outIdx = argv.indexOf('--out');
+  const llmsIdx = argv.indexOf('--llms-out');
+  const baseIdx = argv.indexOf('--base-url');
+  const noLlms = argv.includes('--no-llms');
+
+  const result = await buildMeta({
+    outFile: outIdx !== -1 && argv[outIdx + 1] ? resolve(argv[outIdx + 1]) : undefined,
+    llmsFile: llmsIdx !== -1 && argv[llmsIdx + 1] ? resolve(argv[llmsIdx + 1]) : undefined,
+    baseUrl: baseIdx !== -1 && argv[baseIdx + 1] ? argv[baseIdx + 1] : undefined,
+    llms: !noLlms,
+  });
+
+  console.log(`Velin-Meta: wrote ${result.count} file(s)`);
+  for (const p of result.written) console.log(`  ${p}`);
+}