@genn-inc/cluebase-cli 0.0.1

package/src/setup-doctor-quality-shared.mjs

@@ -0,0 +1,382 @@
+// Shared constants and helpers for the /cluebase-doctor data-quality checks.
+// Extracted from setup-doctor-quality for file-size limits; content is
+// unchanged.
+
+import { readSetupDoctorFile } from "./setup-doctor-file-boundary.mjs";
+
+export const ALLOWED_GROUP_TYPES = Object.freeze(["organization"]);
+
+export const FAKE_PLACEHOLDER_NAMES = Object.freeze([
+  "noreply@example.com",
+  "example@example.com",
+  "user@example.com",
+  "unknown",
+  "anonymous",
+  "null",
+  "undefined",
+  "user",
+  "guest",
+  "test",
+  "default",
+]);
+
+export const PLACEHOLDER_ENV_VALUES = Object.freeze([
+  "",
+  "your-key-here",
+  "xxx",
+  "yyy",
+  "zzz",
+  "todo",
+  "tbd",
+  "placeholder",
+  "changeme",
+  "change-me",
+  "your_key_here",
+  "<your-key>",
+  "your-project-key",
+  "your-service-key",
+  "your-api-key",
+]);
+
+export const TEST_DIR_PATTERNS = [
+  /(^|\/)test(s)?\//i,
+  /(^|\/)__tests?__\//i,
+  /(^|\/)spec\//i,
+  /\.test\.[a-z]+$/i,
+  /\.spec\.[a-z]+$/i,
+];
+
+export const VENDORED_DIR_PATTERNS = [
+  /(^|\/)node_modules\//,
+  /(^|\/)vendor\//,
+  /(^|\/)vendored\//,
+  /(^|\/)\.next\//,
+  /(^|\/)dist\//,
+  /(^|\/)build\//,
+  /(^|\/)\.turbo\//,
+  /(^|\/)out\//,
+];
+
+export const DEV_HOST_PATTERNS = [
+  /https?:\/\/localhost(:\d+)?(\/|$)/i,
+  /https?:\/\/127\.0\.0\.1(:\d+)?(\/|$)/i,
+  /https?:\/\/0\.0\.0\.0(:\d+)?(\/|$)/i,
+  /https?:\/\/.*\.local(:\d+)?(\/|$)/i,
+  /https?:\/\/.*\.dev(:\d+)?(\/|$)/i,
+];
+
+export const SENSITIVE_FIELD_PATTERNS = [
+  /password/i,
+  /passwd/i,
+  /secret/i,
+  /token/i,
+  /api[_-]?key/i,
+  /private[_-]?key/i,
+  /credit[_-]?card/i,
+  /ssn/i,
+  /cvv/i,
+];
+
+export const VALID_SDK_PACKAGES = Object.freeze([
+  "@genn-inc/cluebase-frontend-sdk",
+  "@genn-inc/cluebase-backend-sdk",
+  "cluebase-backend-sdk",
+]);
+
+export const GROUP_OWNER_ACTIVE_KIND = "active_context_owner";
+export const GROUP_OWNER_CONTEXT_CHANGE_KIND = "context_change";
+
+export const GROUP_OWNER_KIND_ALIASES = Object.freeze({
+  active_context_owner: GROUP_OWNER_ACTIVE_KIND,
+  active_context_restore: GROUP_OWNER_ACTIVE_KIND,
+  guarded_active_context: GROUP_OWNER_ACTIVE_KIND,
+  context_owner: GROUP_OWNER_ACTIVE_KIND,
+  initial_context: "initial_context",
+  context_change: GROUP_OWNER_CONTEXT_CHANGE_KIND,
+  create_context: GROUP_OWNER_CONTEXT_CHANGE_KIND,
+  join_context: GROUP_OWNER_CONTEXT_CHANGE_KIND,
+  switch_context: GROUP_OWNER_CONTEXT_CHANGE_KIND,
+  onboarding_context: GROUP_OWNER_CONTEXT_CHANGE_KIND,
+});
+
+export const WRONG_SDK_PACKAGE_PATTERNS = [
+  /@genn-inc\/cluebase-cli/,
+  /@cluebase\/cli/,
+  /@cluebase\/frontend-sdk/,
+  /@cluebase\/backend-sdk/,
+  /@cluebase-ai\/cli/,
+  /@cluebase-ai\/cluebase-cli/,
+  /@cluebase-ai\/frontend-sdk/,
+  /@cluebase-ai\/backend-sdk/,
+];
+
+export const REQUIRED_PROJECT_KEY_ENV_NAMES = Object.freeze([
+  "CLUEBASE_PROJECT_KEY",
+  "NEXT_PUBLIC_CLUEBASE_PROJECT_KEY",
+  "VITE_CLUEBASE_PROJECT_KEY",
+  "REACT_APP_CLUEBASE_PROJECT_KEY",
+  "PUBLIC_CLUEBASE_PROJECT_KEY",
+  "NUXT_PUBLIC_CLUEBASE_PROJECT_KEY",
+]);
+
+export const COMMON_ENV_KEY_TYPOS = Object.freeze({
+  "NEXT_PUBLIC_CLUEBASE_KEY": "NEXT_PUBLIC_CLUEBASE_PROJECT_KEY",
+  "CLUEBASE_KEY": "CLUEBASE_PROJECT_KEY",
+  "CLUEBASE_PROJ_KEY": "CLUEBASE_PROJECT_KEY",
+  "CLUEBASE_PROJECTKEY": "CLUEBASE_PROJECT_KEY",
+  "NEXT_PUBLIC_CLUEBASE_PROJECTKEY": "NEXT_PUBLIC_CLUEBASE_PROJECT_KEY",
+  "VITE_CLUEBASE_PROJECTKEY": "VITE_CLUEBASE_PROJECT_KEY",
+});
+
+export const isString = (value) => typeof value === "string" && value.length > 0;
+export const isPlainObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+export const matchesAny = (value, patterns) => {
+  if (!isString(value)) return false;
+  return patterns.some((pattern) => pattern.test(value));
+};
+
+// ============================================================
+// Check result builder
+// ============================================================
+
+export const buildCheck = ({ id, severity, passed, message = null, details = null }) => ({
+  id,
+  severity,
+  passed: Boolean(passed),
+  message,
+  details,
+});
+
+export const errorPass = (id) => buildCheck({ id, severity: "error", passed: true });
+export const warnPass = (id) => buildCheck({ id, severity: "warn", passed: true });
+
+// ============================================================
+// identify (= 顧客識別) 関連
+// ============================================================
+
+
+export const stringOrNull = (value) =>
+  typeof value === "string" && value.trim() ? value.trim() : null;
+
+export const groupOwnerKindOf = (site) => {
+  const explicit =
+    stringOrNull(site?.group_owner_kind) ??
+    stringOrNull(site?.groupOwnerKind) ??
+    stringOrNull(site?.boundary_role);
+  if (explicit) {
+    const normalized = explicit.trim().toLowerCase().replaceAll("-", "_");
+    if (GROUP_OWNER_KIND_ALIASES[normalized]) {
+      return GROUP_OWNER_KIND_ALIASES[normalized];
+    }
+  }
+
+  const haystack = [
+    site?.file,
+    site?.rationale,
+    site?.evidence_snippet,
+    site?.field_acquisition_notes,
+  ]
+    .filter(isString)
+    .join(" ")
+    .toLowerCase();
+
+  if (
+    /active[_\s-]?context[_\s-]?owner/.test(haystack) ||
+    /lastcluebasegroupkey/.test(haystack) ||
+    /onboardingguard/.test(haystack) ||
+    /provider/.test(haystack) ||
+    /session restore/.test(haystack) ||
+    /auth-state listener/.test(haystack) ||
+    /onauthstatechange/.test(haystack)
+  ) {
+    return GROUP_OWNER_ACTIVE_KIND;
+  }
+
+  if (
+    /\b(create|join|switch|onboard)\b/.test(haystack) ||
+    /accept[-_\s]?invite/.test(haystack) ||
+    /create[-_\s]?workspace/.test(haystack) ||
+    /join[-_\s]?workspace/.test(haystack) ||
+    /switch[-_\s]?workspace/.test(haystack) ||
+    /setactiveworkspace/.test(haystack)
+  ) {
+    return GROUP_OWNER_CONTEXT_CHANGE_KIND;
+  }
+
+  return null;
+};
+
+export const groupSiteSurfaceOf = (site) => {
+  const explicit =
+    stringOrNull(site?.surface) ??
+    stringOrNull(site?.runtime) ??
+    stringOrNull(site?.side);
+  if (explicit) return explicit.trim().toLowerCase();
+
+  const file = stringOrNull(site?.file)?.toLowerCase() ?? "";
+  if (
+    /\.py$/.test(file) ||
+    /(^|\/)(backend|server|api|routes?|controllers?|views?)\//.test(file) ||
+    /(^|\/)route\.(ts|js)$/.test(file) ||
+    /(^|\/)\+server\.(ts|js)$/.test(file)
+  ) {
+    return "backend";
+  }
+  return "frontend";
+};
+
+export const findDuplicateGroupOwnerViolations = (groupSites) => {
+  const bySurface = new Map();
+  for (const site of groupSites) {
+    if (!isString(site?.file)) continue;
+    const ownerKind = groupOwnerKindOf(site);
+    if (!ownerKind) continue;
+    const surface = groupSiteSurfaceOf(site);
+    const entry = bySurface.get(surface) ?? {
+      surface,
+      activeOwners: [],
+      contextChanges: [],
+    };
+    if (ownerKind === GROUP_OWNER_ACTIVE_KIND) {
+      entry.activeOwners.push(site);
+    }
+    if (ownerKind === GROUP_OWNER_CONTEXT_CHANGE_KIND) {
+      entry.contextChanges.push(site);
+    }
+    bySurface.set(surface, entry);
+  }
+
+  const violations = [];
+  for (const entry of bySurface.values()) {
+    if (entry.activeOwners.length === 0 || entry.contextChanges.length === 0) {
+      continue;
+    }
+    for (const activeOwner of entry.activeOwners) {
+      for (const contextChange of entry.contextChanges) {
+        violations.push({
+          surface: entry.surface,
+          activeOwner: {
+            file: activeOwner.file,
+            line: activeOwner.line,
+            group_owner_kind: groupOwnerKindOf(activeOwner),
+          },
+          duplicateHandler: {
+            file: contextChange.file,
+            line: contextChange.line,
+            group_owner_kind: groupOwnerKindOf(contextChange),
+          },
+        });
+      }
+    }
+  }
+  return violations;
+};
+
+export const identifySitesOf = (discoveries) => {
+  if (!isPlainObject(discoveries)) return [];
+  return Array.isArray(discoveries.identify_sites) ? discoveries.identify_sites : [];
+};
+
+export const groupSitesOf = (discoveries) => {
+  if (!isPlainObject(discoveries)) return [];
+  const organizationSites = Array.isArray(discoveries.group_sites)
+    ? discoveries.group_sites
+    : [];
+  return organizationSites;
+};
+
+export const resetSitesOf = (discoveries) => {
+  if (!isPlainObject(discoveries)) return [];
+  const logoutSites = Array.isArray(discoveries.reset_sites)
+    ? discoveries.reset_sites
+    : [];
+  return logoutSites;
+};
+
+export const initSitesOf = (discoveries) => {
+  if (!isPlainObject(discoveries)) return [];
+  const result = [];
+  for (const key of ["cluebase_init_frontend", "cluebase_init_backend"]) {
+    const entry = discoveries[key];
+    if (isPlainObject(entry) && isString(entry.file)) {
+      result.push(entry);
+    }
+  }
+  return result;
+};
+
+export const allInsertionSitesOf = (discoveries) => [
+  ...identifySitesOf(discoveries),
+  ...groupSitesOf(discoveries),
+  ...resetSitesOf(discoveries),
+  ...initSitesOf(discoveries),
+];
+
+export const readSiteFile = async ({ repoRoot, file, sourceFiles, signal }) => {
+  if (isPlainObject(sourceFiles) && file in sourceFiles) {
+    return typeof sourceFiles[file] === "string" ? sourceFiles[file] : null;
+  }
+  if (!repoRoot) return null;
+  return readSetupDoctorFile({
+    repoRoot,
+    path: file,
+    signal,
+    optional: true,
+  });
+};
+
+export const findInitCalls = (content) => {
+  const calls = [];
+  const matches = content.matchAll(/cluebase\.init\s*\(([\s\S]*?)\)/g);
+  for (const match of matches) {
+    calls.push(match[0]);
+  }
+  return calls;
+};
+
+export const countCluebaseInitCalls = (content) =>
+  (content.match(/cluebase\.init\s*\(/g) ?? []).length;
+
+export const hasHardcodedKeys = (callSnippet) => {
+  // projectKey に literal string が直接書かれているか
+  const projectKeyLiteral = /projectKey\s*[:=]\s*["'`](pk_[a-z]+_[A-Za-z0-9_-]+)["'`]/.test(
+    callSnippet,
+  );
+  return projectKeyLiteral;
+};
+
+export const findHardcodedIdentifyLiterals = (content) => {
+  const calls = [];
+  // cluebase.identify("literal", ...) もしくは cluebase.identify('literal', ...)
+  const matches = content.matchAll(/cluebase\.identify\s*\(\s*(["'`])([^"'`]+)\1/g);
+  for (const match of matches) {
+    calls.push(match[0]);
+  }
+  return calls;
+};
+
+// ============================================================
+// ERROR メッセージ構築
+// ============================================================
+
+export const buildErrorMessage = ({ detected, location, impact, actions }) => {
+  const actionLines = (actions ?? [])
+    .map((action, index) => `     ${index + 1}. ${action}`)
+    .join("\n");
+  return [
+    `× ERROR: ${detected}`,
+    `   場所: ${location}`,
+    `   影響: ${impact}`,
+    `   対応:`,
+    actionLines,
+    `   setup は中断されました。`,
+  ].join("\n");
+};
+
+// ============================================================
+// 30 check Runner (= 全 check を並列実行 + 集計)
+// ============================================================
+
+// public API: 30 check を全実行

package/src/setup-doctor-quality.mjs

@@ -0,0 +1,209 @@
+// setup-doctor-quality: `/cluebase-doctor` の 30 check 厳格データ品質ガード。
+//
+// API 疎通だけでは検知不能な「動いているのに使えない」状態を fail-fast
+// で halt する。 各 check は純粋関数で source / discoveries.json / env file
+// を受け取り {id, severity, passed, message, details} を返す (= 副作用なし)。
+// 個別 check の実装は setup-doctor-quality-checks-a / -checks-b、 共有定数・
+// helper は setup-doctor-quality-shared にある。
+
+import {
+  checkC1,
+  checkC10,
+  checkC11,
+  checkC12,
+  checkC13,
+  checkC14,
+  checkC15,
+  checkC16,
+  checkC17,
+  checkC2,
+  checkC3,
+  checkC4,
+  checkC9,
+} from "./setup-doctor-quality-checks-a.mjs";
+import {
+  checkC18,
+  checkC19,
+  checkC20,
+  checkC21,
+  checkC22,
+  checkC23,
+  checkC24,
+  checkC25,
+  checkC26,
+  checkC27,
+  checkC28,
+  checkC29,
+  checkC30,
+  checkC5,
+  checkC6,
+  checkC7,
+  checkC8,
+} from "./setup-doctor-quality-checks-b.mjs";
+import { isPlainObject, isString } from "./setup-doctor-quality-shared.mjs";
+import {
+  readSetupDoctorFile,
+  readSetupDoctorJson,
+} from "./setup-doctor-file-boundary.mjs";
+
+// Re-export the individual checks so `setup-doctor-quality.mjs` stays the public
+// entry point for the check functions after the file-size split.
+export {
+  checkC1,
+  checkC2,
+  checkC3,
+  checkC4,
+  checkC5,
+  checkC6,
+  checkC7,
+  checkC8,
+  checkC9,
+  checkC10,
+  checkC11,
+  checkC12,
+  checkC13,
+  checkC14,
+  checkC15,
+  checkC16,
+  checkC17,
+  checkC18,
+  checkC19,
+  checkC20,
+  checkC21,
+  checkC22,
+  checkC23,
+  checkC24,
+  checkC25,
+  checkC26,
+  checkC27,
+  checkC28,
+  checkC29,
+  checkC30,
+};
+
+export const runQualityChecks = async ({
+  discoveries = null,
+  envFiles = null,
+  packageJson = null,
+  repoRoot = ".",
+  sourceFiles = null,
+  signal,
+}) => {
+  const ctx = {
+    discoveries,
+    envFiles,
+    packageJson,
+    repoRoot,
+    signal,
+    sourceFiles,
+  };
+
+  // 並列実行可能な (= sync / async) check を一括 await
+  const results = await Promise.all([
+    Promise.resolve(checkC1(discoveries)),
+    Promise.resolve(checkC2(discoveries)),
+    Promise.resolve(checkC3(discoveries)),
+    checkC4(ctx),
+    checkC5(ctx),
+    checkC6(ctx),
+    Promise.resolve(checkC7(discoveries)),
+    checkC8(ctx),
+    checkC9(ctx),
+    Promise.resolve(checkC10(discoveries)),
+    Promise.resolve(checkC11(discoveries)),
+    checkC12(ctx),
+    Promise.resolve(checkC13(discoveries)),
+    checkC14(ctx),
+    checkC15(ctx),
+    checkC16(ctx),
+    checkC17(ctx),
+    checkC18(ctx),
+    Promise.resolve(checkC19(discoveries)),
+    Promise.resolve(checkC20(discoveries)),
+    checkC21(ctx),
+    checkC22(ctx),
+    checkC23(ctx),
+    checkC24(ctx),
+    Promise.resolve(checkC25({ envFiles })),
+    Promise.resolve(checkC26({ envFiles })),
+    Promise.resolve(checkC27({ envFiles })),
+    checkC28(ctx),
+    checkC29(ctx),
+    checkC30(ctx),
+  ]);
+
+  // 集計
+  const errorChecks = results.filter((c) => c.severity === "error");
+  const warnChecks = results.filter((c) => c.severity === "warn");
+  const failedErrors = errorChecks.filter((c) => !c.passed);
+  const failedWarns = warnChecks.filter((c) => !c.passed);
+
+  return {
+    checks: results,
+    summary: {
+      total: results.length,
+      errorTotal: errorChecks.length,
+      warnTotal: warnChecks.length,
+      errorFailed: failedErrors.length,
+      warnFailed: failedWarns.length,
+      passed: failedErrors.length === 0,
+    },
+  };
+};
+
+// helper: 顧客 repo 標準位置から discoveries / env / package.json をロード
+export const loadQualityInputs = async ({ repoRoot = ".", signal } = {}) => {
+  const discoveries = await readJsonIfExists(
+    repoRoot,
+    ".cluebase/discoveries.json",
+    signal,
+  );
+  const packageJson = await readJsonIfExists(
+    repoRoot,
+    "package.json",
+    signal,
+  );
+  const envFiles = await readEnvFiles({ repoRoot, discoveries, signal });
+  return { discoveries, packageJson, envFiles };
+};
+
+const readJsonIfExists = async (repoRoot, path, signal) => {
+  return readSetupDoctorJson({ repoRoot, path, signal, optional: true });
+};
+
+const COMMON_ENV_FILE_NAMES = [
+  ".env",
+  ".env.local",
+  ".env.development",
+  ".env.production",
+];
+
+const readEnvFiles = async ({ repoRoot, discoveries, signal }) => {
+  const result = {};
+  const candidates = new Set();
+  // discoveries.env_files から
+  if (isPlainObject(discoveries) && isPlainObject(discoveries.env_files)) {
+    for (const kind of ["frontend", "backend"]) {
+      const entry = discoveries.env_files[kind];
+      if (isPlainObject(entry) && isString(entry.path)) {
+        candidates.add(entry.path);
+      }
+    }
+  }
+  // よくある場所
+  for (const name of COMMON_ENV_FILE_NAMES) {
+    candidates.add(name);
+  }
+  for (const candidate of candidates) {
+    const content = await readSetupDoctorFile({
+      repoRoot,
+      path: candidate,
+      signal,
+      optional: true,
+    });
+    if (content !== null) {
+      result[candidate] = content;
+    }
+  }
+  return result;
+};