@educa-corp/sdd-framework 0.9.5 → 0.9.6

package/bin/self-check.js

@@ -431,22 +431,69 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
     // schema đó chỉ là chữ. Đây là nửa "máy canh" của luật "khai tường minh + để máy canh" —
     // và hợp đồng test-id là chỗ luật đó bị thiếu lâu nhất (3 lệnh đọc, 2 lệnh ghi, 0 nơi kiểm).
     {
-      const TC = schema.testid_contract;
-      if (TC && Array.isArray(TC.lint_rules)) {
-        const emits = new Set((lintText.match(/\b(?:err|warn)\('(T\d+)'/g) || [])
-          .map(m => /T\d+/.exec(m)[0]));
-        for (const r of TC.lint_rules) {
-          if (!r.why) {
-            err('R8', `\`testid_contract.lint_rules\` mục \`${r.rule}\` thiếu \`why\``,
-                'Một rule không nói được VÌ SAO sẽ bị người sau coi là tuỳ ý và gỡ đi.');
+      const emits = new Set((lintText.match(/\b(?:err|warn)\('(T\d+)'/g) || [])
+        .map(m => /T\d+/.exec(m)[0]));
+
+      // Gom MỌI chỗ trong schema khai một lint rule cho hợp đồng test-id.
+      // `testid_fourth_leg.lint_rule` vào đây ở G76: khối đó khai `T19` và — trước bản sửa này —
+      // KHÔNG chỗ nào ép nó tồn tại. Gỡ `warn('T19')` khỏi lint-trace vẫn build xanh, tức là
+      // khối schema mới thêm lại đúng khuôn B ("luật ĐÚNG, viết RÕ, KHÔNG AI CANH") mà nó sinh
+      // ra để chống. Một allowlist đọc-từ-một-khoá-cứng chỉ phủ đúng khoá đó — cùng bài học R18.
+      const declaredRules = [
+        ...((schema.testid_contract || {}).lint_rules || [])
+          .map(r => ({ ...r, at: 'testid_contract.lint_rules' })),
+        ...((schema.testid_fourth_leg || {}).lint_rule
+          ? [{ ...schema.testid_fourth_leg.lint_rule, at: 'testid_fourth_leg.lint_rule' }]
+          : []),
+      ];
+
+      // ── R8f — qc_artifact_stamp: mỗi field phải khai `probe` + `artifact`, và T20 phải tồn tại ──
+      //
+      // G85: `fields.bdd_version` khai nguồn "| **Version** | của header .feature" — cú pháp hợp lệ,
+      // mô tả rõ ràng, và KHÔNG THỂ ĐÚNG (.feature là Gherkin, không có bảng). Một rule chỉ canh
+      // "mô tả có tồn tại" sẽ cho nó qua. Nên phần canh chia hai tầng, đúng khuôn self-check ↔ lint:
+      //   R8f (đây)        — canh CONTRACT: field có khai probe/artifact hợp lệ không
+      //   T20 (lint-trace) — canh DỮ LIỆU : probe đó có TÌM ĐƯỢC ở artifact thật không
+      {
+        const QS = schema.qc_artifact_stamp;
+        if (QS && QS.fields) {
+          const KINDS = new Set(['prd', 'feature', 'tech-design', 'design-spec']);
+          for (const [name, f] of Object.entries(QS.fields)) {
+            if (!f || typeof f !== 'object' || !f.probe) {
+              err('R8', `\`qc_artifact_stamp.fields.${name}\` thiếu \`probe\``,
+                  'Không có probe thì không ai kiểm được mô tả nguồn có TÌM ĐƯỢC ở artifact thật\n'
+                + '        hay không — đúng khe mà G85 lọt qua.');
+              continue;
+            }
+            try { new RegExp(f.probe); }
+            catch { err('R8', `\`qc_artifact_stamp.fields.${name}.probe\` không phải regex hợp lệ`,
+                        `Giá trị: ${f.probe}`); }
+            if (!KINDS.has(f.artifact)) {
+              err('R8', `\`qc_artifact_stamp.fields.${name}.artifact\` không hợp lệ: ${f.artifact}`,
+                  `Phải là một trong: ${[...KINDS].join(' · ')}. Sai loại thì T20 soi nhầm tập file\n`
+                + '        và báo sạch trên một thứ chưa từng được kiểm.');
+            }
           }
-          if (!emits.has(r.rule)) {
-            err('R8', `schema khai \`testid_contract\` rule \`${r.rule}\` mà ${LINT_REL} KHÔNG phát ra`,
-                'Khai rule rồi mà checker không có nó = hợp đồng test-id không được kiểm ở đâu cả,\n'
-              + '        trong khi bảng §4.5.6 có 3 lệnh đọc và 2 lệnh ghi.');
+          const lr = QS.lint_rule;
+          if (lr && !new Set((lintText.match(/\b(?:err|warn)\('(T\d+)'/g) || [])
+              .map(m => /T\d+/.exec(m)[0])).has(lr.rule)) {
+            err('R8', `schema khai \`qc_artifact_stamp.lint_rule\` rule \`${lr.rule}\` mà ${LINT_REL} KHÔNG phát ra`,
+                'Khai rule rồi mà checker không có nó = mô tả nguồn không được kiểm ở đâu cả.');
           }
         }
       }
+
+      for (const r of declaredRules) {
+        if (!r.why) {
+          err('R8', `\`${r.at}\` mục \`${r.rule}\` thiếu \`why\``,
+              'Một rule không nói được VÌ SAO sẽ bị người sau coi là tuỳ ý và gỡ đi.');
+        }
+        if (!emits.has(r.rule)) {
+          err('R8', `schema khai \`${r.at}\` rule \`${r.rule}\` mà ${LINT_REL} KHÔNG phát ra`,
+              'Khai rule rồi mà checker không có nó = hợp đồng test-id không được kiểm ở đâu cả,\n'
+            + '        trong khi bảng §4.5.6 có 3 lệnh đọc và 2 lệnh ghi.');
+        }
+      }
     }
 
     // ── R8c — `n` phải là 1..N liền mạch, không trùng ──
@@ -1382,6 +1429,130 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
   }
 }
 
+// ── R17 — cờ bỏ qua điều kiện chỉ được mang MỘT tên: --force ──────────────────
+//
+// Vì sao: trước `gate.bypass_flags`, mỗi chỗ bypass đặt một tên riêng — `--force`
+// (generate-code), `--include-draft` (qc-scope), và exec-d0-b5 còn đang đề xuất
+// `--no-testid-contract` "theo đúng tinh thần --include-draft". Cái thứ ba chưa kịp sinh ra
+// đã thấy nó sẽ là cái thứ ba. Luật gom về một tên đã viết; đây là phần MÁY CANH.
+//
+// USE-CHECK, KHÔNG PHẢI MENTION-CHECK — cùng bài học R12. Một rule grep thô sẽ báo oan mỗi
+// lần file NHẮC TÊN một cờ cũ trong câu giải thích, mà rules/workflow.md đang cố ý nhắc
+// `--include-draft` bốn lần để giải thích tên đã bỏ. Nên chỉ quét DÒNG ĐỊNH NGHĨA cờ (hàng
+// bảng mở đầu bằng một cờ trong backtick), và BỎ QUA mọi dòng blockquote — nơi chứa toàn bộ
+// phần biện minh.
+{
+  const BF = (schema.gate || {}).bypass_flags;
+  if (BF) {
+    const canonical = BF.canonical_name || '--force';
+
+    // Cờ KHÔNG phải bypass — chúng chọn chế độ/phạm vi, không bỏ qua điều kiện nào.
+    const NON_BYPASS = new Set([
+      '--yes', '--force', '--resume', '--fix', '--all', '--api', '--atomic-max', '--phase',
+      '--from-code', '--uc', '--prd', '--domain', '--full', '--remote', '--init', '--apply',
+      '--retire', '--review', '--interview', '--from', '--comment', '--code', '--trace',
+      '--specs', '--flag', '--lint-trace', '--migrate-specs', '--warn-only',
+      '--realign', '--realign-prd-version', '--realign-techdoc-revision', '--reconcile-code',
+    ]);
+    // Hình dạng một cờ BYPASS mới.
+    const BYPASS_SHAPE = /^--(no|skip|ignore|include|allow|accept|bypass|override)-/;
+
+    for (const cmd of Object.keys(schema.actors || {})) {
+      const rel = schema.actors[cmd];
+      if (!/^commands\//.test(rel)) continue;
+      const abs = path.join(ROOT, rel);
+      if (!fs.existsSync(abs)) continue;
+
+      for (const line of fs.readFileSync(abs, 'utf8').split(/\r?\n/)) {
+        if (/^\s*>/.test(line)) continue;                    // blockquote = phần giải thích
+        const m = /^\s*\|\s*`(--[a-z0-9-]+)`/.exec(line);    // hàng bảng định nghĩa cờ
+        if (!m) continue;
+        const flag = m[1];
+        if (NON_BYPASS.has(flag) || !BYPASS_SHAPE.test(flag)) continue;
+        err('R17', `${rel} định nghĩa cờ bypass riêng \`${flag}\``,
+            `Mọi chỗ "biết mà vẫn chạy" dùng CHUNG một tên: \`${canonical}\`\n`
+          + `        (schema → gate.bypass_flags · rules/workflow.md §Cờ bỏ qua điều kiện).\n`
+          + `        Mỗi lệnh một tên riêng thì người dùng gặp cổng chặn, không nhớ lệnh này dùng\n`
+          + `        từ nào, rồi đi SỬA SPEC cho hợp lệ giả thay vì khai mình đang chạy sớm.`);
+      }
+    }
+
+    for (const e of BF.declared_by || []) {
+      if (!e.bypasses) {
+        err('R17', `\`bypass_flags.declared_by\` mục \`${e.cmd}\` thiếu \`bypasses\``,
+            'Điều khoản (1): phạm vi khai TỪNG LỆNH, không bao giờ bao trùm. Không nói rõ nó bỏ\n'
+          + '        qua ĐÚNG điều kiện nào thì `--force` thành "ghi đè tất cả".');
+      }
+      const rel = (schema.actors || {})[e.cmd] || `steps/${e.cmd}.md`;
+      const abs = path.join(ROOT, rel);
+      if (fs.existsSync(abs) && !fs.readFileSync(abs, 'utf8').includes(canonical)) {
+        err('R17', `\`bypass_flags.declared_by\` khai \`${e.cmd}\` nhưng ${rel} không nhắc \`${canonical}\``,
+            'Khai một producer không tồn tại thì luật trông như đã được áp, trong khi không ai áp.');
+      }
+    }
+  }
+}
+
+// ── R18 — lệnh ghi artifact phải KHAI, và "có người nhập tay" thì phải `hard` ──
+//
+// Vì sao: `gate.checkpoint_levels` là ALLOWLIST với mặc định `normal` (mức LỎNG NHẤT), và
+// R11 duyệt TỪ SCHEMA RA FILE — nó chỉ kiểm lệnh ĐÃ liệt kê. Lệnh chưa khai thì không vòng
+// lặp nào chạm tới. Nên "quên khai" = "mở cửa", và nó đã xảy ra BỐN lần: G67 · G77 · G78 · G79.
+//
+// R18 duyệt CHIỀU NGƯỢC LẠI. Đó là toàn bộ giá trị của nó: một checker duyệt allowlist chỉ
+// thấy được cái ĐÃ KHAI, mà cái CHƯA KHAI mới là chỗ lỗi sống.
+{
+  const AW = schema.artifact_writers;
+  const CL = (schema.gate || {}).checkpoint_levels;
+  if (AW && CL) {
+    const hardSet = new Set((CL.hard || []).map(e => e.cmd));
+    const enrolled = AW.enrolled || {};
+    const pending = (AW.pending_enrollment || {}).cmds || [];
+
+    for (const cmd of Object.keys(enrolled)) {
+      const e = enrolled[cmd];
+      const rel = `commands/${cmd}.tmpl`;
+
+      if (!fs.existsSync(path.join(ROOT, rel))) {
+        err('R18', `\`artifact_writers.enrolled\` khai \`${cmd}\` — ${rel} không tồn tại`,
+            'Lệnh bị đổi tên/bỏ? Khai một lệnh không có nghĩa là registry đang phủ nó.');
+        continue;
+      }
+      if (!Array.isArray(e.writes) || !e.writes.length) {
+        err('R18', `\`artifact_writers.enrolled.${cmd}\` thiếu \`writes\``,
+            'Không liệt kê ghi cái gì thì không ai kiểm được "cái đó có người nhập tay không".');
+      }
+      if (typeof e.has_human_content !== 'boolean') {
+        err('R18', `\`artifact_writers.enrolled.${cmd}\` thiếu \`has_human_content\` (boolean)`,
+            'Đây là CÂU HỎI mà bốn lần trước không ai hỏi: "file này có phần người nhập tay\n'
+          + '        không?". Bỏ trống là quay lại đúng mặc định lỏng mà rule này sinh ra để đảo.');
+      }
+      // `why` BẮT BUỘC cả khi false — đó chính là G79.
+      if (!e.why) {
+        err('R18', `\`artifact_writers.enrolled.${cmd}\` thiếu \`why\``,
+            'Bắt buộc CẢ KHI `has_human_content: false`. Ghi đè an toàn mà không ai khai là an\n'
+          + '        toàn thì một ngoại lệ CÓ CHỦ Ý trông y hệt một chỗ sót — và sẽ bị copy đi (G79).');
+      }
+      if (e.has_human_content === true && !hardSet.has(cmd)) {
+        err('R18', `\`${cmd}\` ghi artifact CÓ phần người nhập tay nhưng KHÔNG ở \`checkpoint_levels.hard\``,
+            `Khai: "${String(e.why || '').slice(0, 110)}…"\n`
+          + `        Ghi đè thứ người nhập tay mà chỉ ở mức \`normal\` thì \`--yes\` xoá nó TRONG IM LẶNG.\n`
+          + `        Sửa: thêm \`${cmd}\` vào gate.checkpoint_levels.hard + viết §luật chạy lại trong lệnh.`);
+      }
+    }
+
+    // Chiều ngược: lệnh đã ở `hard` VÌ LÝ DO GHI ĐÈ phải có mặt trong registry.
+    for (const h of CL.hard || []) {
+      if (!/ghi đè/i.test(String(h.why || ''))) continue;   // `hard` vì lý do khác (vd --resume)
+      if (!enrolled[h.cmd] && !pending.includes(h.cmd)) {
+        err('R18', `\`${h.cmd}\` ở \`checkpoint_levels.hard\` vì ghi đè, nhưng không có trong \`artifact_writers\``,
+            'Hai nơi cùng nói về một chuyện mà chỉ một nơi biết — nơi kia sẽ lệch.\n'
+          + '        Thêm vào `enrolled` (đã rà) hoặc `pending_enrollment` (chưa rà, nợ được KHAI).');
+      }
+    }
+  }
+}
+
 // ── report ────────────────────────────────────────────────────────────────────
 const tagCount = schema.tags.length;
 const colCount = schema.tsv_columns.length;