@genn-inc/cluebase-cli 0.0.1

package/src/setup-doctor-quality-checks-a.mjs

@@ -0,0 +1,593 @@
+// Data-quality checks (first half).
+// Extracted from setup-doctor-quality for file-size limits; content is unchanged.
+
+import {
+  ALLOWED_GROUP_TYPES,
+  DEV_HOST_PATTERNS,
+  FAKE_PLACEHOLDER_NAMES,
+  buildCheck,
+  buildErrorMessage,
+  countCluebaseInitCalls,
+  errorPass,
+  findDuplicateGroupOwnerViolations,
+  findHardcodedIdentifyLiterals,
+  findInitCalls,
+  groupSitesOf,
+  hasHardcodedKeys,
+  identifySitesOf,
+  initSitesOf,
+  isPlainObject,
+  isString,
+  matchesAny,
+  readSiteFile,
+  stringOrNull,
+  warnPass,
+} from "./setup-doctor-quality-shared.mjs";
+
+export const checkC1 = (discoveries) => {
+  const id = "C1";
+  const sites = identifySitesOf(discoveries);
+  if (sites.length === 0) return errorPass(id);
+  const offenders = [];
+  for (const site of sites) {
+    const fields = site?.available_fields;
+    if (!isPlainObject(fields)) continue;
+    const idPath = stringOrNull(fields.id);
+    const namePath = stringOrNull(fields.name);
+    if (idPath && namePath && idPath === namePath) {
+      offenders.push({ file: site.file, line: site.line, idPath, namePath });
+    }
+  }
+  if (offenders.length === 0) return errorPass(id);
+  const firstOffender = offenders[0];
+  return buildCheck({
+    id,
+    severity: "error",
+    passed: false,
+    message: buildErrorMessage({
+      detected: `cluebase.identify(${firstOffender.idPath}, { name: ${firstOffender.namePath} }) を検出`,
+      location: `${firstOffender.file}:${firstOffender.line}`,
+      impact:
+        "分析側で「ユーザー X さん」 と表示されるべき箇所が全部 raw ID 文字列 「user_a1b2c3d4」 並びになります。",
+      actions: [
+        "user model に name field を追加してください、 または",
+        "/cluebase-discover を再実行して email 代用に切り替えてください",
+      ],
+    }),
+    details: { offenders },
+  });
+};
+
+// C2: name path が null / undefined / 空文字 (= 表示名を取得できない環境)。
+// STEP 5 の「name path が無ければ omit して続行 (name: id は禁止)」と整合させ、
+// hard STOP ではなく WARN で通す。表示名なしでも identify / 分析は動作する。
+// 名前偽装 (email や id を name に流用) は doctrine 違反なので remediation でも
+// 指示しない。name == id の代入検出は別 check が ERROR として担う。
+export const checkC2 = (discoveries) => {
+  const id = "C2";
+  const sites = identifySitesOf(discoveries);
+  if (sites.length === 0) return warnPass(id);
+  const offenders = [];
+  for (const site of sites) {
+    const fields = site?.available_fields;
+    if (!isPlainObject(fields)) continue;
+    const namePath = fields.name;
+    if (
+      namePath === null ||
+      namePath === undefined ||
+      (typeof namePath === "string" && namePath.trim() === "")
+    ) {
+      offenders.push({ file: site.file, line: site.line, namePath });
+    }
+  }
+  if (offenders.length === 0) return warnPass(id);
+  const first = offenders[0];
+  return buildCheck({
+    id,
+    severity: "warn",
+    passed: false,
+    message: `WARN: 表示名 (name) を取得できない identify site があります (offender: ${first.file}:${first.line})。name を省いて続行します — 名前なしでも identify / 分析は動作します。後から表示名を出したい場合は /cluebase-discover を再実行し、実在する表示名 field を name に指定してください (email や id を name に流用しないでください)。`,
+    details: { offenders },
+  });
+};
+
+// C9: identify が hardcoded literal で呼ばれている
+export const checkC9 = async ({ discoveries, repoRoot, signal, sourceFiles = null }) => {
+  const id = "C9";
+  const sites = identifySitesOf(discoveries);
+  if (sites.length === 0) return errorPass(id);
+  const offenders = [];
+  for (const site of sites) {
+    if (!site?.file) continue;
+    const content = await readSiteFile({ repoRoot, file: site.file, signal, sourceFiles });
+    if (content === null) continue;
+    const literalCalls = findHardcodedIdentifyLiterals(content);
+    for (const call of literalCalls) {
+      offenders.push({ file: site.file, line: site.line, literal: call });
+    }
+  }
+  if (offenders.length === 0) return errorPass(id);
+  const first = offenders[0];
+  return buildCheck({
+    id,
+    severity: "error",
+    passed: false,
+    message: buildErrorMessage({
+      detected: `cluebase.identify が hardcoded literal で呼ばれているのを検出 (例: ${first.literal})`,
+      location: first.file,
+      impact:
+        "全てのユーザーが同じ ID として記録され、 ユーザー識別が機能しません。 分析・顧客理解が崩壊します。",
+      actions: [
+        "literal を user.id 等の dynamic な path に差し替えてください",
+        "/cluebase-discover を再実行して available_fields.id を再検出してください",
+      ],
+    }),
+    details: { offenders },
+  });
+};
+
+// C10: name に fake placeholder
+export const checkC10 = (discoveries) => {
+  const id = "C10";
+  const sites = identifySitesOf(discoveries);
+  if (sites.length === 0) return errorPass(id);
+  const offenders = [];
+  for (const site of sites) {
+    const fields = site?.available_fields;
+    if (!isPlainObject(fields)) continue;
+    const namePath = fields.name;
+    if (typeof namePath !== "string") continue;
+    const namePathLower = namePath.toLowerCase().trim();
+    // path 自体が literal string ("...") の場合に placeholder と判定
+    const literalMatch = namePath.match(/^["'`]([^"'`]+)["'`]$/);
+    if (literalMatch) {
+      const literalValue = literalMatch[1].toLowerCase().trim();
+      if (FAKE_PLACEHOLDER_NAMES.includes(literalValue)) {
+        offenders.push({ file: site.file, line: site.line, namePath });
+        continue;
+      }
+    }
+    // path に含まれる literal string 部分
+    if (
+      FAKE_PLACEHOLDER_NAMES.some((placeholder) =>
+        namePathLower.includes(`"${placeholder}"`) ||
+        namePathLower.includes(`'${placeholder}'`),
+      )
+    ) {
+      offenders.push({ file: site.file, line: site.line, namePath });
+    }
+  }
+  if (offenders.length === 0) return errorPass(id);
+  const first = offenders[0];
+  return buildCheck({
+    id,
+    severity: "error",
+    passed: false,
+    message: buildErrorMessage({
+      detected: `cluebase.identify の name に fake placeholder (例: ${first.namePath}) を検出`,
+      location: `${first.file}:${first.line}`,
+      impact:
+        "全ユーザーが同じ placeholder 名で識別され、 分析側で個別ユーザーの行動が混ざります。",
+      actions: [
+        "user model から実際の display 名を取得する path に差し替えてください",
+        "name が null になる可能性がある場合は email 等の代替 field を使ってください",
+      ],
+    }),
+    details: { offenders },
+  });
+};
+
+// C11: name path が email path と同じ (= 表示で email 重複露出)
+export const checkC11 = (discoveries) => {
+  const id = "C11";
+  const sites = identifySitesOf(discoveries);
+  if (sites.length === 0) return warnPass(id);
+  const offenders = [];
+  for (const site of sites) {
+    const fields = site?.available_fields;
+    if (!isPlainObject(fields)) continue;
+    const namePath = stringOrNull(fields.name);
+    const emailPath = stringOrNull(fields.email);
+    if (namePath && emailPath && namePath === emailPath) {
+      offenders.push({ file: site.file, line: site.line, namePath, emailPath });
+    }
+  }
+  if (offenders.length === 0) return warnPass(id);
+  return buildCheck({
+    id,
+    severity: "warn",
+    passed: false,
+    message:
+      "WARN: cluebase.identify の name path が email path と一致しています。 顧客 UI で email が name 欄に重複露出します。 user.display_name 等の別 field 採用を検討してください。",
+    details: { offenders },
+  });
+};
+
+// ============================================================
+// group (= 組織所属) 関連
+// ============================================================
+
+// C3: cluebase.group の name path が groupKey path と完全一致
+export const checkC3 = (discoveries) => {
+  const id = "C3";
+  const sites = groupSitesOf(discoveries);
+  if (sites.length === 0) return errorPass(id);
+  const offenders = [];
+  for (const site of sites) {
+    const fields = site?.available_fields;
+    if (!isPlainObject(fields)) continue;
+    const keyPath =
+      stringOrNull(fields.groupKey) ??
+      stringOrNull(fields.group_key) ??
+      stringOrNull(fields.id);
+    const namePath = stringOrNull(fields.name);
+    if (keyPath && namePath && keyPath === namePath) {
+      offenders.push({ file: site.file, line: site.line, keyPath, namePath });
+    }
+  }
+  if (offenders.length === 0) return errorPass(id);
+  const first = offenders[0];
+  return buildCheck({
+    id,
+    severity: "error",
+    passed: false,
+    message: buildErrorMessage({
+      detected: `cluebase.group の name path (${first.namePath}) が groupKey path と一致を検出`,
+      location: `${first.file}:${first.line}`,
+      impact:
+        "組織名が raw ID 文字列で表示され、 workspace 会話で組織を識別できなくなります。",
+      actions: [
+        "group model に name / title field を追加してください、 または",
+        "/cluebase-discover を再実行して name 用の semantic path を再検出してください",
+      ],
+    }),
+    details: { offenders },
+  });
+};
+
+// C12: groupType literal が MVP public contract 以外
+export const checkC12 = async ({ discoveries, repoRoot, signal, sourceFiles = null }) => {
+  const id = "C12";
+  const sites = groupSitesOf(discoveries);
+  if (sites.length === 0) return errorPass(id);
+  const offenders = [];
+  for (const site of sites) {
+    const fields = site?.available_fields;
+    if (isPlainObject(fields) && isString(fields.groupType)) {
+      const literal = fields.groupType.replace(/^["'`]|["'`]$/g, "").trim();
+      if (literal && !ALLOWED_GROUP_TYPES.includes(literal)) {
+        offenders.push({ file: site.file, line: site.line, groupType: literal });
+      }
+    }
+    // source code 上で cluebase.group("xxx", <key>, ...) も拾う
+    if (site?.file) {
+      const content = await readSiteFile({ repoRoot, file: site.file, signal, sourceFiles });
+      if (content === null) continue;
+      const matches = content.matchAll(
+        /cluebase\.group\s*\(\s*["'`]([^"'`]+)["'`]/g,
+      );
+      for (const match of matches) {
+        const literal = match[1].trim();
+        if (literal && !ALLOWED_GROUP_TYPES.includes(literal)) {
+          offenders.push({ file: site.file, line: site.line, groupType: literal });
+        }
+      }
+    }
+  }
+  if (offenders.length === 0) return errorPass(id);
+  const first = offenders[0];
+  return buildCheck({
+    id,
+    severity: "error",
+    passed: false,
+    message: buildErrorMessage({
+      detected: `cluebase.group の groupType に許可外の literal を検出 (offender: "${first.groupType}")`,
+      location: `${first.file}:${first.line}`,
+      impact: `MVP の groupType は ${ALLOWED_GROUP_TYPES.join(" / ")} のみです。account/workspace は将来導入予定であり、今使うと Cluebase の会社+ユーザー evidence が分散します。`,
+      actions: [
+        `groupType を ${ALLOWED_GROUP_TYPES.join(" / ")} に修正してください`,
+      ],
+    }),
+    details: { offenders, allowed: [...ALLOWED_GROUP_TYPES] },
+  });
+};
+
+// C13: group が identify 未挿入の boundary で呼ばれている (= orphan group)
+//
+// identify call が application 全体に 1 件でも存在すれば、 boundary
+// は「同 app 内の login flow 経由」 と認識して pass。 identify 0 件 + group
+// 1+ 件のみを warn (= 真の orphan, identify を入れる必要あり)。 production
+// reach への影響なし + 偽陽性を排除する。
+export const checkC13 = (discoveries) => {
+  const id = "C13";
+  const groupSites = groupSitesOf(discoveries);
+  if (groupSites.length === 0) return warnPass(id);
+  const duplicateOwnerViolations = findDuplicateGroupOwnerViolations(groupSites);
+  if (duplicateOwnerViolations.length > 0) {
+    const first = duplicateOwnerViolations[0];
+    return buildCheck({
+      id,
+      severity: "error",
+      passed: false,
+      message: buildErrorMessage({
+        detected:
+          "cluebase.group の active-context owner と create/join/switch handler の重複配置を検出",
+        location: `${first.activeOwner.file}:${first.activeOwner.line ?? "?"}`,
+        impact:
+          "同じ active organization に対して organization_associated が二重送信されます。SDK 側で隠すのではなく、setup の呼び出し位置を一箇所に統一する必要があります。",
+        actions: [
+          "active-context owner を唯一の cluebase.group 呼び出し元にしてください",
+          "create / join / switch handler 側の cluebase.group を削除し、active state 更新だけにしてください",
+          "/cluebase-discover-review を再実行して group_sites を de-dupe してください",
+        ],
+      }),
+      details: { violations: duplicateOwnerViolations },
+    });
+  }
+  const identifyCount = identifySitesOf(discoveries).filter((site) =>
+    isString(site?.file),
+  ).length;
+  if (identifyCount > 0) return warnPass(id);
+  // identify が application に 1 件もない + group が 1+ 件存在する = 真の
+  // orphan。 ユーザー識別前に組織所属が記録されると、 顧客行動が「組織のみ・
+  // ユーザー不在」 として残るため warn。
+  return buildCheck({
+    id,
+    severity: "warn",
+    passed: false,
+    message: `WARN: identify 挿入が無いまま group が呼ばれている (${groupSites.length} 件)。 application 全体で identify call site が見つかりません。 ユーザー識別前に組織所属が記録されると、 顧客行動が「組織のみ・ユーザー不在」 として残ります。 login boundary に identify を追加してください。`,
+    details: { group_sites: groupSites.slice(0, 5) },
+  });
+};
+
+// C14: MVP で deferred の account/workspace context が漏れていないか
+export const checkC14 = async ({ discoveries, repoRoot, signal, sourceFiles = null }) => {
+  const id = "C14";
+  const sites = groupSitesOf(discoveries);
+  if (sites.length === 0) return errorPass(id);
+  const offenders = [];
+  for (const site of sites) {
+    if (!site?.file) continue;
+    const content = await readSiteFile({ repoRoot, file: site.file, signal, sourceFiles });
+    if (content === null) continue;
+    // cluebase.group("account" | "workspace", ...) と workspace/account trait leak を検出。
+    const deferredGroupType = content.match(
+      /cluebase\.group\s*\(\s*["'`](account|workspace)["'`]/i,
+    );
+    const accountWithWorkspace = content.match(
+      /cluebase\.group\s*\(\s*["'`]account["'`][^)]*[{,\s"']workspace[_-]?id\s*[:=]/i,
+    );
+    const workspaceWithAccount = content.match(
+      /cluebase\.group\s*\(\s*["'`]workspace["'`][^)]*[{,\s"']account[_-]?id\s*[:=]/i,
+    );
+    const deferredIdentityTrait = content.match(
+      /cluebase\.group\s*\([^)]*{[^)]*["'`]?(?:account|workspace)[_-]?id["'`]?\s*[:=]/i,
+    );
+    if (deferredGroupType) {
+      offenders.push({
+        file: site.file,
+        line: site.line,
+        issue: `MVP 対象外 groupType ${deferredGroupType[1]} を使っている`,
+      });
+    }
+    if (accountWithWorkspace) {
+      offenders.push({
+        file: site.file,
+        line: site.line,
+        issue: "MVP 対象外の account/workspace trait を渡している",
+      });
+    }
+    if (deferredIdentityTrait) {
+      offenders.push({
+        file: site.file,
+        line: site.line,
+        issue: "MVP 対象外の account/workspace trait を渡している",
+      });
+    }
+    if (workspaceWithAccount) {
+      offenders.push({
+        file: site.file,
+        line: site.line,
+        issue: "MVP 対象外の workspace/account trait を渡している",
+      });
+    }
+  }
+  if (offenders.length === 0) return errorPass(id);
+  const first = offenders[0];
+  return buildCheck({
+    id,
+    severity: "error",
+    passed: false,
+    message: buildErrorMessage({
+      detected: `MVP 対象外の group context を検出: ${first.issue}`,
+      location: `${first.file}:${first.line}`,
+      impact:
+        "MVP では会社+ユーザーだけを Cluebase の public identity contract にするため、account/workspace を混ぜると同じ会社の evidence が分散します。",
+      actions: [
+        'cluebase.group("organization", organizationId, traits) に揃えてください',
+        "account/workspace は将来導入時に改めて contract を決めます",
+      ],
+    }),
+    details: { offenders },
+  });
+};
+
+// ============================================================
+// init (= bootstrap) 関連
+// ============================================================
+
+// C4: cluebase.init の projectKey が env から読まれていない
+export const checkC4 = async ({ discoveries, repoRoot, signal, sourceFiles = null }) => {
+  const id = "C4";
+  const initSites = initSitesOf(discoveries);
+  if (initSites.length === 0) return errorPass(id);
+  const offenders = [];
+  for (const site of initSites) {
+    if (!site?.file) continue;
+    const content = await readSiteFile({ repoRoot, file: site.file, signal, sourceFiles });
+    if (content === null) continue;
+    const initCalls = findInitCalls(content);
+    for (const call of initCalls) {
+      if (hasHardcodedKeys(call)) {
+        offenders.push({ file: site.file, snippet: call });
+      }
+    }
+  }
+  if (offenders.length === 0) return errorPass(id);
+  const first = offenders[0];
+  return buildCheck({
+    id,
+    severity: "error",
+    passed: false,
+    message: buildErrorMessage({
+      detected: `cluebase.init の projectKey が hardcoded で書かれているのを検出`,
+      location: first.file,
+      impact:
+        "projectKey が repository に commit されると、環境別 (dev / prod) の切替が不可能になります。",
+      actions: [
+        "backend は server env、browser code は framework に合う public env / runtime config から projectKey を読むよう変更してください",
+      ],
+    }),
+    details: { offenders },
+  });
+};
+
+// C15: endpoint が localhost / 127.0.0.1 / dev URL に hardcode
+export const checkC15 = async ({ discoveries, repoRoot, signal, sourceFiles = null }) => {
+  const id = "C15";
+  const initSites = initSitesOf(discoveries);
+  if (initSites.length === 0) return errorPass(id);
+  const offenders = [];
+  for (const site of initSites) {
+    if (!site?.file) continue;
+    const content = await readSiteFile({ repoRoot, file: site.file, signal, sourceFiles });
+    if (content === null) continue;
+    const initCalls = findInitCalls(content);
+    for (const call of initCalls) {
+      const endpointMatch = call.match(/endpoint\s*[:=]\s*["'`]([^"'`]+)["'`]/);
+      if (endpointMatch) {
+        const endpoint = endpointMatch[1];
+        if (matchesAny(endpoint, DEV_HOST_PATTERNS)) {
+          offenders.push({ file: site.file, endpoint });
+        }
+      }
+    }
+  }
+  if (offenders.length === 0) return errorPass(id);
+  const first = offenders[0];
+  return buildCheck({
+    id,
+    severity: "error",
+    passed: false,
+    message: buildErrorMessage({
+      detected: `cluebase.init endpoint に dev URL hardcoded: ${first.endpoint}`,
+      location: first.file,
+      impact:
+        "production deploy 時に dev endpoint へ送信され、 顧客イベントが失われます。",
+      actions: [
+        "frontend cluebase.init は framework ごとの public Cluebase API base URL env から endpoint を読むよう変更してください",
+        "backend cluebase.init は CLUEBASE_INGEST_ENDPOINT から endpoint を読むよう変更してください",
+      ],
+    }),
+    details: { offenders },
+  });
+};
+
+const backendInitSitesOf = (discoveries) => {
+  if (!isPlainObject(discoveries)) return [];
+  const entry = discoveries.cluebase_init_backend;
+  return isPlainObject(entry) && isString(entry.file) ? [entry] : [];
+};
+
+// C16: backend projectKey と serviceKey が同じ value (= 取り違え)
+export const checkC16 = async ({ discoveries, repoRoot, signal, sourceFiles = null }) => {
+  const id = "C16";
+  const initSites = backendInitSitesOf(discoveries);
+  if (initSites.length === 0) return errorPass(id);
+  const offenders = [];
+  for (const site of initSites) {
+    if (!site?.file) continue;
+    const content = await readSiteFile({ repoRoot, file: site.file, signal, sourceFiles });
+    if (content === null) continue;
+    const initCalls = findInitCalls(content);
+    for (const call of initCalls) {
+      const projectKeyMatch = call.match(/projectKey\s*[:=]\s*([^,}\n]+)/);
+      const serviceKeyMatch = call.match(/serviceKey\s*[:=]\s*([^,}\n]+)/);
+      if (projectKeyMatch && serviceKeyMatch) {
+        const pk = projectKeyMatch[1].trim().replace(/[,;]$/, "").trim();
+        const sk = serviceKeyMatch[1].trim().replace(/[,;]$/, "").trim();
+        if (pk === sk) {
+          offenders.push({ file: site.file, value: pk });
+        }
+      }
+    }
+  }
+  if (offenders.length === 0) return errorPass(id);
+  const first = offenders[0];
+  return buildCheck({
+    id,
+    severity: "error",
+    passed: false,
+    message: buildErrorMessage({
+      detected: `backend cluebase.init で projectKey と serviceKey に同じ値 (${first.value}) を指定`,
+      location: first.file,
+      impact:
+        "project と backend service の役割が混同され、event attribution が不正になります。",
+      actions: [
+        "projectKey は pk_dev_xxx / pk_prod_xxx 形式 (project 全体の識別)",
+        "backend serviceKey には projectKey とは別の値を指定してください",
+        "別々の値を指定してください",
+      ],
+    }),
+    details: { offenders },
+  });
+};
+
+// C17: init が同 surface (= frontend / backend) 内で複数回呼ばれている
+// frontend/backend は別 process のため、各 surface 1 init は normal (= WARN
+// しない)。同 surface 内で 2+ の時だけ WARN。
+export const checkC17 = async ({ discoveries, repoRoot, signal, sourceFiles = null }) => {
+  const id = "C17";
+  const sitesByPurpose = {
+    frontend: isPlainObject(discoveries?.cluebase_init_frontend) &&
+      isString(discoveries.cluebase_init_frontend.file)
+      ? discoveries.cluebase_init_frontend
+      : null,
+    backend: isPlainObject(discoveries?.cluebase_init_backend) &&
+      isString(discoveries.cluebase_init_backend.file)
+      ? discoveries.cluebase_init_backend
+      : null,
+  };
+  const violations = [];
+  for (const [purpose, site] of Object.entries(sitesByPurpose)) {
+    if (!site?.file) continue;
+    const content = await readSiteFile({
+      repoRoot,
+      file: site.file,
+      signal,
+      sourceFiles,
+    });
+    if (content === null) continue;
+    const callCount = countCluebaseInitCalls(content);
+    if (callCount > 1) {
+      violations.push({ purpose, file: site.file, callCount });
+    }
+  }
+  if (violations.length === 0) return warnPass(id);
+  const messages = violations.map(
+    (v) => `${v.purpose} (${v.file}) で ${v.callCount} 回`,
+  );
+  return buildCheck({
+    id,
+    severity: "warn",
+    passed: false,
+    message: `WARN: cluebase.init が同 surface 内で複数回呼ばれています: ${messages.join(", ")}。 frontend / backend は別 process なので各 surface 1 init は normal、 同 surface 内 2+ のみ問題です。`,
+    details: { violations },
+  });
+};
+
+// ============================================================
+// insertion site 関連
+// ============================================================
+
+// C6: discoveries.json の identify_sites 全件に挿入完了