@educa-corp/sdd-framework 0.4.2 → 0.5.0

package/bin/self-check.js

@@ -8,16 +8,23 @@
  * 3 consumer, 0 producer, sống qua nhiều version mà không lệnh nào, không cổng
  * nào, không test nào bắt được. Đây là cái bắt lớp lỗi đó một cách mechanical.
  *
- * 6 rule:
- *   R1  field có read_by nhưng KHÔNG có producer         → ERROR  (bắt được G1)
- *   R2  field có producer nhưng KHÔNG ai đọc             → WARN   (bắt được G15, fe_phase)
+ * 7 rule — áp cho tags · tsv_columns · aux_tables (_seams.tsv) · queues (feedback/*):
+ *   R1  field/hàng đợi có read_by nhưng KHÔNG có producer → ERROR  (bắt được G1; queue: G26)
+ *   R2  field có producer nhưng KHÔNG ai đọc             → WARN   (bắt được G15, fe_phase, test_type)
  *   R3  actor được khai là producer/consumer mà file của
- *       nó KHÔNG nhắc tên field                          → ERROR  (bắt được G5, G12, G13)
+ *       nó KHÔNG nhắc tên field/cột/path_key             → ERROR  (bắt được G5, G12, G13, G31, G32)
  *   R4  {paths.X} dùng trong lệnh mà X không có trong
  *       project-context.yaml, và ngược lại key chết      → ERROR / WARN (bắt được G17)
- *   R5  pattern bị cấm xuất hiện trở lại                 → ERROR  (bắt được G3, G8, G10, G18, G21)
+ *   R5  pattern bị cấm xuất hiện trở lại                 → ERROR  (bắt được G3, G8, G10, G18, G21, G11)
  *   R6  giá trị enum khai trong vocabulary mà không actor
  *       nào dùng                                         → WARN   (bắt được G19: integration vs integrated)
+ *   R7  audit flag thiếu counter {flag}_count trong CẢ
+ *       Step 7 LẪN khối `summary` của validate-traces     → ERROR  (bắt được G33)
+ *
+ * PHẠM VI (G30): trước đó schema chỉ phủ 16/44 tag — R1/R3 mù với 28 cái còn lại, và ĐÓ LÀ
+ * cách G31 (@trace.service: 2 consumer khai, 0 nơi chứa) cùng G32 (design-spec: 0 cột/0 tag/
+ * 0 cờ) sống qua nhiều version với dấu ✅. Dấu ✅ chỉ có nghĩa "phần ĐÃ KHAI thì đúng".
+ * Giữ phạm vi đầy đủ: thêm tag/cột/bảng/hàng đợi mới thì khai NGAY, đừng để dồn.
  *
  * Chạy: node bin/self-check.js            (exit 1 nếu có ERROR)
  *       node bin/self-check.js --warn-only (luôn exit 0)
@@ -126,6 +133,59 @@ function checkField(kind, name, def) {
 for (const t of schema.tags)        checkField('tag', t.name, t);
 for (const c of schema.tsv_columns) checkField('cột TSV', c.name, c);
 
+// Bảng phụ (_seams.tsv) — nguồn của 2 cờ 🔴 chặn PR nhưng nằm ngoài SoT tới G30.
+// Chạy CÙNG checkField, không cần rule mới: mỗi cột là một field có producer/consumer.
+for (const t of schema.aux_tables || []) {
+  checkField(`bảng phụ \`${t.name}\``, t.name, t);          // file phải được cả 2 đầu nhắc tên
+  // `column_actors` = actor thao tác ở MỨC CỘT (ghi/parse từng field). Actor chỉ dùng bảng ở
+  // MỨC BẢNG (vd review-code chỉ kiểm "có dòng PENDING không") KHÔNG phải nhắc đủ tên cột —
+  // đòi thế là báo oan. Không khai `column_actors` → mặc định mọi actor.
+  const colActors = t.column_actors || [...(t.written_by || []), ...(t.read_by || [])];
+  for (const col of t.columns || []) {
+    for (const actor of new Set(colActors)) {
+      const text = actorText[actor];
+      if (text === undefined) continue;
+      if (!mentions(text, col)) {
+        err('R3', `cột \`${t.name}:${col}\`: schema khai \`${actor}\` đụng bảng này nhưng ${schema.actors[actor]} KHÔNG nhắc cột \`${col}\``,
+            `Hoặc lệnh thiếu implement, hoặc cột đã đổi tên. Bảng này là NGUỒN của SEAM_UNWIRED/STUB_UNRESOLVED —\n`
+          + `        đổi tên cột mà không ai bắt được thì hai cờ 🔴 chặn PR sẽ mù trong im lặng.`);
+      }
+    }
+  }
+}
+
+// Hàng đợi feedback — bắt ca "hàng đợi có producer nhưng KHÔNG ai drain" (hình dạng của G26).
+//
+// KHÔNG dùng chung mentions() với tag/cột: path key luôn xuất hiện dưới dạng `{paths.X}`,
+// tức LUÔN có dấu `.` đứng trước — mà mentions() cố ý chặn ký tự đó (để `@trace.XXsc_version`
+// không bị coi là đã nhắc `sc_version`). Dùng thẳng thì 100% queue báo lỗi oan.
+// Ở đây chỉ cần chặn hậu tố: `bug_reports_dir` không được khớp `bug_reports_dirX`.
+const mentionsKey = (text, key) =>
+  new RegExp(`\\b${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![A-Za-z0-9_])`).test(text);
+
+for (const q of schema.queues || []) {
+  const producers = q.written_by || [];
+  const consumers = q.read_by || [];
+  const label = `hàng đợi \`${q.name}\``;
+
+  if (producers.length && !consumers.length) {
+    err('R1', `${label}: có producer nhưng KHÔNG ai đọc — file vào đó rồi nằm lại vĩnh viễn`,
+        `Đây là hình dạng của G26 (prd-change-requests: có producer, có storage, có commit,\n`
+      + `        có mặt trong /sync — nhưng 0 consumer, và không gì báo).`);
+  }
+  if (consumers.length && !producers.length) {
+    err('R1', `${label}: có consumer nhưng KHÔNG ai ghi vào — hàng đợi chết?`);
+  }
+  for (const actor of new Set([...producers, ...consumers])) {
+    const text = actorText[actor];
+    if (text === undefined) continue;
+    if (!mentionsKey(text, q.path_key)) {
+      err('R3', `${label}: schema khai \`${actor}\` đụng hàng đợi này nhưng ${schema.actors[actor]} KHÔNG nhắc \`${q.path_key}\``,
+          `Hoặc lệnh thiếu implement, hoặc schema khai sai.`);
+    }
+  }
+}
+
 // ── R4 — {paths.X} vs project-context.yaml ────────────────────────────────────
 const cfgPath = path.join(ROOT, schema.path_keys.config_file);
 if (!fs.existsSync(cfgPath)) {
@@ -202,9 +262,67 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
   }
 }
 
+// ── R7 — mỗi audit flag phải có counter trong summary ─────────────────────────
+// Vì sao tồn tại (G33): PRD_DRIFT / TECHDOC_DRIFT / FE_TECHDOC_DRIFT được TÍNH ở Step 4-5
+// và CÓ mảng chi tiết trong `issues`, nhưng KHÔNG có counter trong `summary`. Dashboard đọc
+// `summary` → ba cờ đó vô hình ở tầng tổng hợp. Bất đối xứng 7/10 còn tệ hơn thiếu cả 10:
+// người viết dashboard thấy có counter cho các cờ khác nên tưởng `summary` là đủ.
+//
+// CỐ Ý KHÔNG CÓ ESCAPE HATCH (không `allow_no_counter`). Một luật có cửa thoát dùng được
+// ngay là luật yếu — đó chính là cách G30 xảy ra (schema phủ 16/43 tag rồi dừng). Cờ nào
+// "chỉ để nhắc, chưa phải lỗi" (SEAM_PENDING/STUB_PENDING) thì counter của nó vẫn có giá
+// trị: PM đọc để xếp thứ tự gen UC. Thêm 2 dòng rẻ hơn nhiều so với một ngoại lệ vĩnh viễn.
+// SIẾT (G30 lô 8): bản đầu chỉ hỏi "tên counter có xuất hiện Ở ĐÂU ĐÓ trong file không".
+// Test G27 lộ ra lỗ: gỡ counter khỏi ĐÚNG hai chỗ luật đòi (Step 7 + `summary`) mà R7 vẫn PASS,
+// vì tên còn sót trong khối report terminal. Tức nó bắt được ca "quên hoàn toàn" (ca thật của
+// G33) nhưng KHÔNG bắt ca "có ở report mà quên ở summary" — mà đó CHÍNH LÀ ca làm dashboard mù.
+// Giờ kiểm từng khối riêng.
+{
+  const flagVocab = schema.vocabularies.audit_flags;
+  const vtName = 'validate-traces';
+  const vtText = actorText[vtName];
+  if (flagVocab && vtText !== undefined) {
+    /** Cắt lát văn bản giữa hai mốc; null nếu không tìm thấy mốc (đừng im lặng bỏ qua). */
+    const slice = (from, to) => {
+      const a = vtText.indexOf(from);
+      if (a < 0) return null;
+      const b = vtText.indexOf(to, a + from.length);
+      return vtText.slice(a, b < 0 ? undefined : b);
+    };
+    const zones = [
+      { label: 'Step 7 (aggregate)', text: slice('### Step 7 —', '### Step 7b') },
+      { label: '`summary` của trace-report.json', text: slice('"summary": {', '"prds"') },
+    ];
+
+    for (const z of zones) {
+      if (z.text === null) {
+        warn('R7', `Không định vị được khối "${z.label}" trong ${schema.actors[vtName]} — R7 bỏ qua khối này`,
+             'Mốc cắt đã đổi? Cập nhật `slice()` trong self-check.js, đừng để R7 mù trong im lặng.');
+      }
+    }
+
+    const missing = [];
+    for (const flag of flagVocab.values || []) {
+      const counter = `${flag.toLowerCase()}_count`;
+      const gone = zones.filter(z => z.text !== null && !mentions(z.text, counter));
+      if (gone.length) missing.push({ flag, counter, zones: gone.map(z => z.label) });
+    }
+    if (missing.length) {
+      err('R7', `${missing.length} audit flag thiếu counter trong ${schema.actors[vtName]}`,
+          missing.map(m => `${m.flag} → thiếu \`${m.counter}\` ở: ${m.zones.join(' + ')}`).join('\n        ')
+        + `\n        Counter PHẢI có ở CẢ HAI khối. Chỉ có ở report terminal là KHÔNG đủ —`
+        + `\n        dashboard đọc \`summary\`, nên cờ sẽ vô hình ở tầng tổng hợp (G33).`);
+    }
+  } else if (!flagVocab) {
+    warn('R7', 'Không tìm thấy vocabulary `audit_flags` — R7 không chạy được');
+  }
+}
+
 // ── report ────────────────────────────────────────────────────────────────────
 const tagCount = schema.tags.length;
 const colCount = schema.tsv_columns.length;
+const auxCount = (schema.aux_tables || []).length;
+const queueCount = (schema.queues || []).length;
 console.log('');
 console.log('Self-check (bin/trace-schema.json) ...');
 console.log('');
@@ -219,7 +337,7 @@ show(errors, '❌');
 show(warns,  '⚠️ ');
 
 if (!errors.length && !warns.length) {
-  console.log(`  ✅ ${tagCount} tag + ${colCount} cột TSV + ${Object.keys(schema.vocabularies).length - 1} vocabulary — contract khớp mọi lệnh`);
+  console.log(`  ✅ ${tagCount} tag + ${colCount} cột TSV + ${auxCount} bảng phụ + ${queueCount} hàng đợi + ${Object.keys(schema.vocabularies).length - 1} vocabulary — contract khớp mọi lệnh`);
 }
 console.log('');