@highpixel-co/palda-design-system 0.4.1 → 0.5.0

package/dist/harness/check.mjs

@@ -0,0 +1,330 @@
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import yaml from 'js-yaml';
+import ts from 'typescript';
+import { validateScreenHtml } from '../scripts/check-examples.mjs';
+
+const PACKAGE = '@highpixel-co/palda-design-system';
+const EXCEPTION_RULES = ['primitive-import', 'icon-import', 'opaque-import'];
+const SOURCE = /\.(?:[cm]?[jt]s|[jt]sx)$/;
+const EXCLUDED = /(?:\.(?:test|spec|stories|gen)\.[cm]?[jt]sx?|\.d\.[cm]?ts)$/;
+const IGNORED_DIRS = new Set(['node_modules', '.git', 'dist', 'coverage']);
+const normalize = (path) => path.replaceAll('\\', '/');
+
+function localPath(root, path) {
+  if (typeof path !== 'string' || !path.trim() || isAbsolute(path)) {
+    throw new Error(`프로젝트 내부 상대 경로가 필요합니다: ${path}`);
+  }
+  const target = resolve(root, path);
+  if (relative(root, target).startsWith('..') || isAbsolute(relative(root, target))) {
+    throw new Error(`프로젝트 밖 경로는 지원하지 않습니다: ${path}`);
+  }
+  // 부모 디렉터리의 symlink도 외부 경로를 숨기지 못하게 한다.
+  let cursor = target;
+  while (cursor !== root) {
+    if (existsSync(cursor) && lstatSync(cursor).isSymbolicLink()) {
+      throw new Error(`symlink 경로는 지원하지 않습니다: ${path}`);
+    }
+    cursor = dirname(cursor);
+  }
+  return target;
+}
+
+export function validateConfig(root, config) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error('설정은 JSON 객체여야 합니다.');
+  }
+  for (const key of Object.keys(config)) {
+    if (!['source', 'screens', 'exceptions'].includes(key))
+      throw new Error(`알 수 없는 설정: ${key}`);
+  }
+  for (const key of ['source', 'screens']) {
+    if (config[key] === undefined) continue;
+    if (!Array.isArray(config[key]) || config[key].length === 0)
+      throw new Error(`${key} 경로가 없습니다.`);
+    config[key].forEach((path) => localPath(root, path));
+  }
+  if (config.exceptions !== undefined && !Array.isArray(config.exceptions)) {
+    throw new Error('exceptions는 배열이어야 합니다.');
+  }
+  for (const entry of config.exceptions ?? []) {
+    if (
+      !entry ||
+      typeof entry !== 'object' ||
+      Object.keys(entry).some((key) => !['file', 'rule', 'symbol', 'reason'].includes(key)) ||
+      !EXCEPTION_RULES.includes(entry.rule) ||
+      !['file', 'symbol', 'reason'].every(
+        (key) => typeof entry[key] === 'string' && entry[key].trim(),
+      ) ||
+      !SOURCE.test(entry.file) ||
+      /[*?]/.test(entry.file)
+    ) {
+      throw new Error('예외는 정확한 file, rule, symbol과 reason을 지정해야 합니다.');
+    }
+    localPath(root, entry.file);
+    if (normalize(entry.file) !== normalize(relative(root, resolve(root, entry.file)))) {
+      throw new Error(`예외 file은 정규화된 상대 경로여야 합니다: ${entry.file}`);
+    }
+  }
+  return config;
+}
+
+function collect(root, paths, accepts) {
+  const files = new Set();
+  let excluded = 0;
+  function visit(directory) {
+    if (!existsSync(directory) || !lstatSync(directory).isDirectory()) {
+      throw new Error(`검사 디렉터리가 없습니다: ${relative(root, directory)}`);
+    }
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      if (IGNORED_DIRS.has(entry.name)) continue;
+      const file = join(directory, entry.name);
+      if (entry.isSymbolicLink())
+        throw new Error(`symlink 대상은 지원하지 않습니다: ${relative(root, file)}`);
+      if (entry.isDirectory()) visit(file);
+      else if (accepts(entry.name)) {
+        if (EXCLUDED.test(entry.name)) excluded++;
+        else files.add(file);
+      }
+    }
+  }
+  paths.forEach((path) => visit(localPath(root, path)));
+  if (files.size === 0)
+    throw new Error('검사 대상 파일이 0개입니다. 설정 경로와 지원 확장자를 확인하세요.');
+  return { files: [...files].sort(), excluded };
+}
+
+function lockedDependency(root) {
+  let directory = root;
+  while (true) {
+    const pnpm = join(directory, 'pnpm-lock.yaml');
+    const npm = join(directory, 'package-lock.json');
+    if (existsSync(pnpm) && existsSync(npm))
+      throw new Error('잠금 파일이 둘입니다. 프로젝트의 패키지 매니저를 하나로 정하세요.');
+    const importer = normalize(relative(directory, root));
+    if (existsSync(pnpm)) {
+      const lock = yaml.load(readFileSync(pnpm, 'utf8'));
+      if (String(lock?.lockfileVersion) !== '9.0' && String(lock?.lockfileVersion) !== '9') {
+        throw new Error('pnpm lockfileVersion 9만 지원합니다.');
+      }
+      const entry = lock.importers?.[importer || '.'];
+      const dep = entry?.dependencies?.[PACKAGE] ?? entry?.devDependencies?.[PACKAGE];
+      return {
+        specifier: dep?.specifier,
+        version: typeof dep?.version === 'string' ? dep.version.split('(')[0] : dep?.version,
+      };
+    }
+    if (existsSync(npm)) {
+      const lock = JSON.parse(readFileSync(npm, 'utf8'));
+      if (![2, 3].includes(lock.lockfileVersion))
+        throw new Error('npm lockfileVersion 2 또는 3만 지원합니다.');
+      const entry = lock.packages?.[importer];
+      let prefix = importer;
+      let installed;
+      while (true) {
+        installed = lock.packages?.[`${prefix ? `${prefix}/` : ''}node_modules/${PACKAGE}`];
+        if (installed || !prefix) break;
+        const parent = normalize(dirname(prefix));
+        prefix = parent === '.' ? '' : parent;
+      }
+      return {
+        specifier: entry?.dependencies?.[PACKAGE] ?? entry?.devDependencies?.[PACKAGE],
+        version: installed?.version,
+      };
+    }
+    if (existsSync(join(directory, 'yarn.lock')))
+      throw new Error('Yarn 잠금 파일은 아직 지원하지 않습니다.');
+    const parent = dirname(directory);
+    if (parent === directory) throw new Error('pnpm-lock.yaml 또는 package-lock.json이 없습니다.');
+    directory = parent;
+  }
+}
+
+function dependencyProblems(root, metadata) {
+  try {
+    const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+    const version = manifest.dependencies?.[PACKAGE] ?? manifest.devDependencies?.[PACKAGE];
+    if (typeof version !== 'string' || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+      throw new Error(`DS 의존성은 정확한 버전으로 고정해야 합니다: ${version ?? '없음'}`);
+    }
+    if (version !== metadata.packageVersion)
+      throw new Error(
+        `앱 DS 버전 ${version}과 실행 중인 하네스 ${metadata.packageVersion}이 다릅니다.`,
+      );
+    const locked = lockedDependency(root);
+    if (locked.specifier !== version || locked.version !== version) {
+      throw new Error(
+        `DS package.json과 lockfile 버전이 다릅니다: ${version} / ${locked.specifier} / ${locked.version}`,
+      );
+    }
+    return [];
+  } catch (error) {
+    return [
+      {
+        file: 'package.json',
+        line: 1,
+        rule: 'dependency',
+        symbol: PACKAGE,
+        message: error.message,
+      },
+    ];
+  }
+}
+
+export function checkConsumer(projectRoot, config, metadata) {
+  const root = resolve(projectRoot);
+  validateConfig(root, config);
+  const scan = collect(root, config.source ?? ['src'], (name) => SOURCE.test(name));
+  const report = {
+    files: scan.files.length,
+    excluded: scan.excluded,
+    exceptions: 0,
+    drafts: [],
+    problems: dependencyProblems(root, metadata),
+  };
+  function add(problem) {
+    if (
+      (config.exceptions ?? []).some(
+        (entry) =>
+          entry.file === problem.file &&
+          entry.rule === problem.rule &&
+          entry.symbol === problem.symbol,
+      )
+    )
+      report.exceptions++;
+    else report.problems.push(problem);
+  }
+  for (const fullPath of scan.files) {
+    const file = normalize(relative(root, fullPath));
+    const parsed = ts.createSourceFile(
+      fullPath,
+      readFileSync(fullPath, 'utf8'),
+      ts.ScriptTarget.Latest,
+      true,
+    );
+    for (const diagnostic of parsed.parseDiagnostics) {
+      add({
+        file,
+        line: parsed.getLineAndCharacterOfPosition(diagnostic.start ?? 0).line + 1,
+        rule: 'syntax',
+        symbol: '',
+        message: ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'),
+      });
+    }
+    function inspect(node, moduleName, names, opaque = false) {
+      const line = parsed.getLineAndCharacterOfPosition(node.getStart(parsed)).line + 1;
+      const problem = (rule, symbol, message) => add({ file, line, rule, symbol, message });
+      if (moduleName.startsWith('@radix-ui/') || moduleName === 'class-variance-authority') {
+        problem(
+          'primitive-import',
+          moduleName,
+          `${moduleName} 직접 사용 대신 DS 자산을 사용하세요.`,
+        );
+        return;
+      }
+      const isDs = moduleName === PACKAGE || moduleName.startsWith(`${PACKAGE}/`);
+      if (!isDs && moduleName !== 'lucide-react') return;
+      if (moduleName === `${PACKAGE}/styles.css` && names.length === 0 && !opaque) return;
+      if (opaque) {
+        problem(
+          'opaque-import',
+          moduleName,
+          `${moduleName}: 이름을 명시한 정적 import/re-export를 사용하세요.`,
+        );
+        return;
+      }
+      for (const { symbol, typeOnly } of names) {
+        if (moduleName === 'lucide-react') {
+          if (!typeOnly && metadata.iconReplacements[symbol])
+            problem(
+              'icon-import',
+              symbol,
+              `${symbol} 대신 DS ${metadata.iconReplacements[symbol]}을 사용하세요.`,
+            );
+          continue;
+        }
+        const subpath = moduleName === PACKAGE ? '.' : `.${moduleName.slice(PACKAGE.length)}`;
+        const group = metadata.exports[subpath];
+        if (
+          !group ||
+          !(typeOnly ? [...group.values, ...group.types] : group.values).includes(symbol)
+        ) {
+          problem(
+            'unknown-export',
+            symbol,
+            `${moduleName}에 ${typeOnly ? '타입 ' : ''}${symbol} export가 없습니다.`,
+          );
+        } else if (!typeOnly) {
+          for (const asset of metadata.assets.filter(
+            (asset) => asset.status === 'draft' && asset.exports.includes(symbol),
+          )) {
+            report.drafts.push({ file, line, symbol, asset: asset.key });
+          }
+        }
+      }
+      if (isDs && names.length === 0 && moduleName !== `${PACKAGE}/styles.css`) {
+        const subpath = moduleName === PACKAGE ? '.' : `.${moduleName.slice(PACKAGE.length)}`;
+        if (!metadata.exports[subpath])
+          problem('unknown-export', moduleName, `지원하지 않는 DS 경로: ${moduleName}`);
+      }
+    }
+    function visit(node) {
+      if (
+        (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) &&
+        node.moduleSpecifier &&
+        ts.isStringLiteral(node.moduleSpecifier)
+      ) {
+        const clause = ts.isImportDeclaration(node) ? node.importClause : node;
+        const bindings = ts.isImportDeclaration(node) ? clause?.namedBindings : node.exportClause;
+        const names =
+          bindings && (ts.isNamedImports(bindings) || ts.isNamedExports(bindings))
+            ? bindings.elements.map((element) => ({
+                symbol: (element.propertyName ?? element.name).text,
+                typeOnly: !!clause.isTypeOnly || element.isTypeOnly,
+              }))
+            : [];
+        if (ts.isImportDeclaration(node) && clause?.name)
+          names.unshift({ symbol: 'default', typeOnly: !!clause.isTypeOnly });
+        const opaque =
+          (!!bindings && ts.isNamespaceImport(bindings)) ||
+          (ts.isExportDeclaration(node) && (!bindings || ts.isNamespaceExport(bindings)));
+        inspect(node, node.moduleSpecifier.text, names, opaque);
+      } else if (
+        ts.isCallExpression(node) &&
+        (node.expression.kind === ts.SyntaxKind.ImportKeyword ||
+          (ts.isIdentifier(node.expression) && node.expression.text === 'require')) &&
+        node.arguments[0] &&
+        ts.isStringLiteralLike(node.arguments[0])
+      ) {
+        inspect(node, node.arguments[0].text, [], true);
+      } else if (
+        ts.isImportEqualsDeclaration(node) &&
+        ts.isExternalModuleReference(node.moduleReference) &&
+        node.moduleReference.expression &&
+        ts.isStringLiteral(node.moduleReference.expression)
+      ) {
+        inspect(node, node.moduleReference.expression.text, [], true);
+      }
+      ts.forEachChild(node, visit);
+    }
+    visit(parsed);
+  }
+  return report;
+}
+
+export function checkScreens(projectRoot, config) {
+  const root = resolve(projectRoot);
+  validateConfig(root, config);
+  const scan = collect(root, config.screens ?? ['preview'], (name) => name.endsWith('.html'));
+  const problems = scan.files.flatMap((fullPath) => {
+    const file = normalize(relative(root, fullPath));
+    return validateScreenHtml(readFileSync(fullPath, 'utf8'), file, true).map((message) => ({
+      file,
+      line: 1,
+      rule: 'screen',
+      symbol: '',
+      message,
+    }));
+  });
+  return { files: scan.files.length, excluded: scan.excluded, exceptions: 0, drafts: [], problems };
+}

package/dist/harness/cli.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { checkConsumer, checkScreens } from './check.mjs';
+
+const directory = dirname(fileURLToPath(import.meta.url));
+let json = process.argv.includes('--json');
+try {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      root: { type: 'string' },
+      config: { type: 'string' },
+      json: { type: 'boolean' },
+      help: { type: 'boolean', short: 'h' },
+      version: { type: 'boolean' },
+    },
+  });
+  json = values.json ?? false;
+  if (values.help || (positionals.length === 0 && !values.version)) {
+    console.log(`palda-ds check|screens|guide [--root path] [--config path] [--json]
+  check    React/TypeScript 앱의 DS import와 package/lockfile 버전 검사
+  screens  HTML 화면 선언과 블록 규칙 검사 (기본 preview/)
+  guide    설치된 사용 설명서 위치
+  --version  설치된 하네스/DS 버전
+설정: 앱의 palda-ds.config.json (선택). 대상 0개·구성 오류는 실패합니다.`);
+  } else {
+    const metadata = JSON.parse(readFileSync(join(directory, 'metadata.json'), 'utf8'));
+    if (
+      metadata.schemaVersion !== 1 ||
+      !metadata.packageVersion ||
+      !metadata.exports ||
+      !metadata.assets ||
+      !metadata.iconReplacements
+    ) {
+      throw new Error('패키지 하네스 metadata가 올바르지 않습니다. 패키지를 다시 설치하세요.');
+    }
+    if (values.version) {
+      console.log(metadata.packageVersion);
+    } else {
+      if (positionals.length !== 1 || !['check', 'screens', 'guide'].includes(positionals[0])) {
+        throw new Error('명령은 check, screens, guide 중 하나입니다. --help를 확인하세요.');
+      }
+      const command = positionals[0];
+      if (command === 'guide') {
+        const guide = resolve(directory, '../guide/docs/CONSUMER_GUIDE.md');
+        if (!existsSync(guide)) throw new Error('패키지 사용 설명서가 없습니다.');
+        console.log(json ? JSON.stringify({ version: metadata.packageVersion, guide }) : guide);
+      } else {
+        const root = resolve(values.root ?? process.cwd());
+        const configPath = resolve(root, values.config ?? 'palda-ds.config.json');
+        const config = existsSync(configPath) ? JSON.parse(readFileSync(configPath, 'utf8')) : {};
+        if (values.config && !existsSync(configPath))
+          throw new Error(`설정 파일이 없습니다: ${configPath}`);
+        const report =
+          command === 'check' ? checkConsumer(root, config, metadata) : checkScreens(root, config);
+        const output = {
+          command,
+          version: metadata.packageVersion,
+          ok: report.problems.length === 0,
+          ...report,
+        };
+        if (json) console.log(JSON.stringify(output, null, 2));
+        else {
+          console.log(
+            `Palda DS ${metadata.packageVersion} ${command}: ${report.files}개 파일 검사, ${report.excluded}개 제외, ${report.exceptions}개 예외 적용`,
+          );
+          report.problems.forEach((p) =>
+            console.error(`${p.file}:${p.line} [${p.rule}] ${p.message}`),
+          );
+          report.drafts.forEach((d) =>
+            console.log(
+              `${d.file}:${d.line} [draft] ${d.symbol} — catalog/${d.asset}의 사용 조건을 검토하세요.`,
+            ),
+          );
+          console.log(output.ok ? '검사 통과' : `검사 실패 ${report.problems.length}건`);
+        }
+        if (!output.ok) process.exitCode = 1;
+      }
+    }
+  }
+} catch (error) {
+  if (json) console.log(JSON.stringify({ ok: false, error: error.message }));
+  else console.error(`Palda DS 검사 구성 오류: ${error.message}`);
+  process.exitCode = 1;
+}