sparkle-design-cli 1.3.8 → 1.3.10

package/lib/check.js

@@ -0,0 +1,174 @@
+import fs from 'fs';
+import path from 'path';
+
+import { getCheckRules, getManualReviewReminders } from './anti-pattern-rules.js';
+
+const DEFAULT_TARGET = 'src';
+const TEXT_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx']);
+const RULES = getCheckRules();
+const MANUAL_REVIEW_REMINDERS = getManualReviewReminders();
+
+function toRelativeReportPath(filePath) {
+  return path.relative(process.cwd(), filePath).split(path.sep).join('/');
+}
+
+function collectFiles(targetPath, files, visited) {
+  if (!fs.existsSync(targetPath)) {
+    throw new Error(`Target path does not exist: ${targetPath}`);
+  }
+
+  const realPath = fs.realpathSync(targetPath);
+  if (visited.has(realPath)) {
+    return;
+  }
+  visited.add(realPath);
+
+  const stat = fs.statSync(realPath);
+
+  if (stat.isFile()) {
+    if (TEXT_EXTENSIONS.has(path.extname(realPath))) {
+      files.add(realPath);
+    }
+    return;
+  }
+
+  if (!stat.isDirectory()) {
+    return;
+  }
+
+  for (const entry of fs.readdirSync(realPath, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name === '.git') {
+      continue;
+    }
+
+    collectFiles(path.join(realPath, entry.name), files, visited);
+  }
+}
+
+function getLineNumber(content, index) {
+  return content.slice(0, index).split(/\r?\n/).length;
+}
+
+function formatMatch(match) {
+  return match[0].replace(/\s+/g, ' ').trim().slice(0, 120);
+}
+
+function collectFindings(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const findings = [];
+
+  for (const rule of RULES) {
+    for (const match of content.matchAll(rule.pattern)) {
+      findings.push({
+        filePath,
+        id: rule.id,
+        description: rule.description,
+        recommendation: rule.recommendation,
+        line: getLineNumber(content, match.index ?? 0),
+        snippet: formatMatch(match),
+      });
+    }
+  }
+
+  return findings;
+}
+
+function createCheckReport(targets = []) {
+  const resolvedTargets = targets.length > 0 ? targets : [DEFAULT_TARGET];
+  const files = new Set();
+  const visited = new Set();
+
+  for (const target of resolvedTargets) {
+    collectFiles(path.resolve(process.cwd(), target), files, visited);
+  }
+
+  const checkedFiles = [...files]
+    .map((filePath) => toRelativeReportPath(filePath))
+    .sort((left, right) => left.localeCompare(right));
+  const findings = [...files]
+    .flatMap(collectFindings)
+    .map((finding) => ({
+      ...finding,
+      filePath: toRelativeReportPath(finding.filePath),
+    }))
+    .sort((left, right) => {
+      const fileComparison = left.filePath.localeCompare(right.filePath);
+      if (fileComparison !== 0) {
+        return fileComparison;
+      }
+
+      if (left.line !== right.line) {
+        return left.line - right.line;
+      }
+
+      return left.id.localeCompare(right.id);
+    });
+
+  return {
+    targets: resolvedTargets,
+    checkedFiles,
+    findings,
+    manualReviewReminders: MANUAL_REVIEW_REMINDERS,
+  };
+}
+
+function printTextReport(report, options = {}) {
+  if (report.findings.length === 0) {
+    console.log('sparkle-design-cli check: no findings');
+  } else {
+    console.log(`sparkle-design-cli check: ${report.findings.length} finding(s)\n`);
+
+    for (const finding of report.findings) {
+      console.log(`${finding.filePath}:${finding.line} [${finding.id}] ${finding.description}`);
+      console.log(`  Recommendation: ${finding.recommendation}`);
+      console.log(`  Snippet: ${finding.snippet}`);
+      console.log('');
+    }
+  }
+
+  console.log('Manual review reminders:');
+  for (const reminder of report.manualReviewReminders) {
+    console.log(`- [${reminder.id}] ${reminder.message}`);
+  }
+
+  if (options.strict && report.findings.length > 0) {
+    console.error('sparkle-design-cli check: failed because --strict was specified');
+  }
+}
+
+function printJsonReport(report, options = {}) {
+  const strictMode = Boolean(options.strict);
+  const passed = !(strictMode && report.findings.length > 0);
+
+  console.log(
+    JSON.stringify(
+      {
+        summary: {
+          targetCount: report.targets.length,
+          checkedFileCount: report.checkedFiles.length,
+          findingCount: report.findings.length,
+          strictMode,
+          passed,
+          exitCode: passed ? 0 : 1,
+        },
+        ...report,
+      },
+      null,
+      2
+    )
+  );
+}
+
+export function checkProject(targets = [], options = {}) {
+  const report = createCheckReport(targets);
+
+  if (options.format === 'json') {
+    printJsonReport(report, options);
+  } else {
+    printTextReport(report, options);
+  }
+
+  return report.findings.length > 0;
+}
+
+export { RULES, collectFindings, createCheckReport, MANUAL_REVIEW_REMINDERS };

package/lib/setup.js

@@ -0,0 +1,260 @@
+import fs from 'fs';
+import path from 'path';
+
+const ASSISTANT_CONFIG = {
+  claude: {
+    path: 'CLAUDE.md',
+  },
+  codex: {
+    path: 'AGENTS.md',
+  },
+  cursor: {
+    path: '.cursor/rules/sparkle-design-guard.mdc',
+  },
+  generic: {
+    path: 'SPARKLE-DESIGN-AI.md',
+  },
+};
+
+const BLOCK_START = '<!-- sparkle-design-cli:setup:start -->';
+const BLOCK_END = '<!-- sparkle-design-cli:setup:end -->';
+const TARGET_CANDIDATES = ['src', 'src/components', 'src/features', 'app', 'components'];
+const UNSAFE_TARGET_PATTERN = /[\s"'`;$&|<>()[\]{}\\]/;
+
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function ensureDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function writeJson(filePath, value) {
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function normalizeTarget(cwd, target, sourceLabel) {
+  const trimmed = target.trim();
+
+  if (!trimmed) {
+    throw new Error(`Target path is empty (${sourceLabel})`);
+  }
+
+  if (path.isAbsolute(trimmed)) {
+    throw new Error(`Target path must be relative to the project root: ${trimmed}`);
+  }
+
+  if (UNSAFE_TARGET_PATTERN.test(trimmed)) {
+    throw new Error(
+      `Target path contains unsupported characters: ${trimmed}. Use a simple relative path without spaces or shell metacharacters.`
+    );
+  }
+
+  const normalized = path.posix.normalize(trimmed.replace(/\\/g, '/'));
+
+  if (normalized === '.' || normalized === '') {
+    throw new Error(`Target path is empty (${sourceLabel})`);
+  }
+
+  if (normalized.startsWith('../')) {
+    throw new Error(`Target path must stay inside the project root: ${trimmed}`);
+  }
+
+  const absolutePath = path.resolve(cwd, normalized);
+  if (!fs.existsSync(absolutePath)) {
+    throw new Error(`Target path does not exist: ${normalized}`);
+  }
+
+  return normalized;
+}
+
+function detectTarget(cwd) {
+  for (const candidate of TARGET_CANDIDATES) {
+    const absolutePath = path.resolve(cwd, candidate);
+    if (fs.existsSync(absolutePath)) {
+      return candidate;
+    }
+  }
+
+  throw new Error(
+    'Could not auto-detect a lint target. Pass --target with an existing relative path such as src or app.'
+  );
+}
+
+function isManagedSparkleScript(value, mode) {
+  if (!value || typeof value !== 'string') {
+    return false;
+  }
+
+  const tokens = value.trim().split(/\s+/);
+  if (tokens.length < 3) {
+    return false;
+  }
+
+  if (tokens[0] !== 'sparkle-design-cli' || tokens[1] !== 'check') {
+    return false;
+  }
+
+  const hasStrict = tokens.includes('--strict');
+  const formatIndex = tokens.indexOf('--format');
+  const formatValue = formatIndex >= 0 ? tokens[formatIndex + 1] : null;
+
+  if (mode === 'strict') {
+    return hasStrict && formatIndex === -1;
+  }
+
+  if (mode === 'json') {
+    return formatIndex >= 0 && formatValue === 'json' && !hasStrict;
+  }
+
+  return false;
+}
+
+function buildInstructionBlock(target, assistant) {
+  const heading = assistant === 'cursor' ? '# Sparkle Design Guard' : '## Sparkle Design Guard';
+
+  return [
+    BLOCK_START,
+    heading,
+    '',
+    '- Run `lint:sparkle` when Sparkle Design changes are involved.',
+    `- For AI review, prefer \`lint:sparkle:json\` or run \`npx --yes sparkle-design-cli check ${target} --format json\` directly.`,
+    '- Always inspect both `findings` and `manualReviewReminders` from the JSON output.',
+    '- If semantic guidance is still needed, consult Sparkle Design docs and JSDoc examples.',
+    BLOCK_END,
+  ].join('\n');
+}
+
+function updateInstructionFile(filePath, block) {
+  const exists = fs.existsSync(filePath);
+  const current = exists ? fs.readFileSync(filePath, 'utf8') : '';
+
+  if (current.includes(BLOCK_START) && current.includes(BLOCK_END)) {
+    const next = current.replace(new RegExp(`${BLOCK_START}[\\s\\S]*?${BLOCK_END}`), block);
+    return { changed: next !== current, content: next, existed: exists };
+  }
+
+  const separator = current.trim().length > 0 ? '\n\n' : '';
+  return {
+    changed: true,
+    content: `${current}${separator}${block}\n`,
+    existed: exists,
+  };
+}
+
+function resolveScriptUpdate(existingValue, nextValue, mode, force) {
+  if (!existingValue) {
+    return { value: nextValue, changed: true, conflict: false, reason: 'created' };
+  }
+
+  if (existingValue === nextValue) {
+    return { value: existingValue, changed: false, conflict: false, reason: 'unchanged' };
+  }
+
+  if (force || isManagedSparkleScript(existingValue, mode)) {
+    return { value: nextValue, changed: true, conflict: false, reason: force ? 'forced' : 'updated' };
+  }
+
+  return { value: existingValue, changed: false, conflict: true, reason: 'preserved-custom' };
+}
+
+function updatePackageJson(filePath, target, force) {
+  const pkg = readJson(filePath);
+  const scripts = { ...(pkg.scripts ?? {}) };
+
+  const strictResult = resolveScriptUpdate(
+    scripts['lint:sparkle'],
+    `sparkle-design-cli check ${target} --strict`,
+    'strict',
+    force
+  );
+  const jsonResult = resolveScriptUpdate(
+    scripts['lint:sparkle:json'],
+    `sparkle-design-cli check ${target} --format json`,
+    'json',
+    force
+  );
+
+  scripts['lint:sparkle'] = strictResult.value;
+  scripts['lint:sparkle:json'] = jsonResult.value;
+
+  return {
+    changed: strictResult.changed || jsonResult.changed || !pkg.scripts,
+    packageJson: {
+      ...pkg,
+      scripts,
+    },
+    scriptResults: {
+      'lint:sparkle': strictResult,
+      'lint:sparkle:json': jsonResult,
+    },
+  };
+}
+
+export function setupAssistant(options = {}) {
+  const assistant = options.assistant ?? 'generic';
+  const cwd = process.cwd();
+  const dryRun = Boolean(options.dryRun);
+  const force = Boolean(options.forceScriptUpdate);
+  const assistantConfig = ASSISTANT_CONFIG[assistant];
+
+  if (!assistantConfig) {
+    throw new Error(`Unsupported assistant: ${assistant}`);
+  }
+
+  const targetSource = options.target ? 'explicit' : 'auto';
+  const target = options.target
+    ? normalizeTarget(cwd, options.target, 'explicit')
+    : normalizeTarget(cwd, detectTarget(cwd), 'auto');
+
+  const packageJsonPath = path.resolve(cwd, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    throw new Error(`package.json not found in ${cwd}`);
+  }
+
+  const instructionPath = path.resolve(cwd, assistantConfig.path);
+  const packageResult = updatePackageJson(packageJsonPath, target, force);
+  const instructionBlock = buildInstructionBlock(target, assistant);
+  const instructionResult = updateInstructionFile(instructionPath, instructionBlock);
+
+  if (!dryRun) {
+    if (packageResult.changed) {
+      writeJson(packageJsonPath, packageResult.packageJson);
+    }
+
+    if (instructionResult.changed) {
+      ensureDir(instructionPath);
+      fs.writeFileSync(instructionPath, instructionResult.content, 'utf8');
+    }
+  }
+
+  const summary = {
+    assistant,
+    target,
+    targetSource,
+    dryRun,
+    forceScriptUpdate: force,
+    packageJson: {
+      path: path.relative(cwd, packageJsonPath),
+      changed: packageResult.changed,
+      scripts: {
+        'lint:sparkle': packageResult.packageJson.scripts?.['lint:sparkle'] ?? null,
+        'lint:sparkle:json': packageResult.packageJson.scripts?.['lint:sparkle:json'] ?? null,
+      },
+      results: packageResult.scriptResults,
+    },
+    instructions: {
+      path: path.relative(cwd, instructionPath),
+      changed: instructionResult.changed,
+      existed: instructionResult.existed,
+    },
+  };
+
+  console.log(JSON.stringify(summary, null, 2));
+  return summary;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparkle-design-cli",
-  "version": "1.3.8",
+  "version": "1.3.10",
   "description": "Sparkle Design CSS Generator - デザインシステムCSSを設定ファイルから生成するツール",
   "main": "lib/generate-css.js",
   "type": "module",
@@ -13,7 +13,8 @@
     "lint": "eslint bin/ lib/ test/",
     "lint:fix": "eslint bin/ lib/ test/ --fix",
     "format": "prettier --write bin/ lib/ test/ *.md *.json",
-    "format:check": "prettier --check bin/ lib/ test/ *.md *.json"
+    "format:check": "prettier --check bin/ lib/ test/ *.md *.json",
+    "sync:anti-pattern-docs": "node scripts/sync-anti-pattern-docs.mjs"
   },
   "keywords": [
     "css",