@longph2102/v-flow 1.5.0

package/cli/lib/module-card-lint.js

@@ -0,0 +1,304 @@
+/**
+ * Module Card Lint — Structural validation for Understand-tier knowledge artifacts
+ *
+ * Validates module cards in `.v-flow/modules/domain-xxx/`:
+ *   - File completeness (required card files present)
+ *   - SKILL.md required headings (HEADING MAP)
+ *   - Leftover template placeholders / unscanned markers
+ *   - business-quiz.md: questions phrased in BUSINESS language, not code
+ *
+ * SCOPE — same charter as cli/commands/validate.js: this is STRUCTURAL lint only.
+ * It does NOT judge whether a question is "a good business question" (that is the
+ * BA/human answer-key's job, per business-quiz.md design). It only flags
+ * deterministic signals that a quiz question leaked code vocabulary — the concrete
+ * "BA đọc không hiểu vì dính code" pain. Default severity = warning; the validate
+ * command's --strict flag escalates. Markdown-first + regex is intentional.
+ *
+ * All functions are pure (content/path in → result out) so they unit-test cleanly.
+ */
+
+const path = require('path');
+const fs = require('fs-extra');
+
+// ════════════════════════════════════════════════════════════
+// CARD STRUCTURE CONTRACT
+// ════════════════════════════════════════════════════════════
+
+/** Files every generated module card must contain. */
+const REQUIRED_CARD_FILES = [
+  'SKILL.md',
+  'use-cases.md',
+  'api-specs.md',
+  'tech-context.md',
+  'cross-service.md',
+  'db.md',
+  'state-diagram.md',
+  'permissions.md',
+  'business-quiz.md',
+  'dev-quiz.md',
+];
+
+/** Present only when the module has a frontend — absence is not an error. */
+const OPTIONAL_CARD_FILES = ['ui-flows.md'];
+
+/** Headings SKILL.md must contain (from its HEADING MAP). */
+const REQUIRED_SKILL_HEADINGS = [
+  '## Quick Summary',
+  '## Key Business Rules',
+  '## Key Entities',
+  '## No-Go Zones',          // matched loosely (emoji/suffix tolerated)
+  '## 📂 Supporting Files',
+];
+
+/** Headings business-quiz.md must contain. */
+const REQUIRED_QUIZ_HEADINGS = [
+  '## MUST',
+  '## SHOULD',
+];
+
+// High-signal residue that should never survive in a real, scanned card.
+const UNSCANNED_MARKER = /\[❓[^\]]*\]/;            // [❓ CẦN SCAN CODE] → issue
+const LITERAL_DATE_PLACEHOLDER = /\bYYYY-MM-DD\b/;   // unfilled date → warning
+// Raw template tokens (curly placeholders that carry template instruction words).
+const TEMPLATE_TOKEN = /\{(Tên|tên|version|date|Câu hỏi|Lý do|N |~X|file_thực|function_thực|EntityName|table_name|field\d|RelatedEntity|mô tả|danh sách|giải thích|đoạn code|rule|Rule)[^}]*\}/;
+const AI_INFERRED_MARKER = /\[⚠️\s*AI-inferred\]/g;  // unverified business rule → count
+
+// ════════════════════════════════════════════════════════════
+// BUSINESS-QUIZ CODE-TOKEN DETECTION
+// ════════════════════════════════════════════════════════════
+
+/**
+ * Deterministic signals that a question is phrased in CODE rather than BUSINESS
+ * language. Each is a strong signal in Vietnamese prose (which uses neither
+ * underscores nor internal capitals nor backticks).
+ */
+const CODE_TOKEN_PATTERNS = [
+  { name: 'backtick code', re: /`[^`]+`/g },
+  { name: 'file/extension', re: /\b[\w/-]+\.(?:js|jsx|ts|tsx|dart|java|py|rb|go|php|cs|sql|ya?ml|json|kt|swift|cpp|hpp)\b/gi },
+  { name: 'function call', re: /\b[A-Za-z_]\w*\(\s*\)/g },
+  { name: 'camelCase', re: /\b[a-z][a-z0-9]*[A-Z][A-Za-z0-9]*\b/g },
+  { name: 'snake_case', re: /\b[a-z][a-z0-9]*_[a-z0-9_]+\b/g },
+  { name: 'CONSTANT_CASE', re: /\b[A-Z][A-Z0-9]*_[A-Z0-9_]+\b/g },
+  { name: 'API endpoint', re: /\/(?:api|v\d)\/[\w/{}-]+/gi },
+];
+
+/** Remove HTML comments so template guidance/examples are never linted. */
+function stripComments(content) {
+  return content.replace(/<!--[\s\S]*?-->/g, '');
+}
+
+/**
+ * Extract quiz questions from business-quiz.md.
+ * @returns {Array<{id, name, questionText}>}
+ */
+function extractQuizQuestions(content) {
+  const clean = stripComments(content);
+  const lines = clean.split('\n');
+  const questions = [];
+
+  let current = null;
+  let capturing = false;       // inside the question body
+  let sawLabel = false;        // an explicit "**Câu hỏi**" label was seen for `current`
+  let buffer = [];
+
+  const flush = () => {
+    if (current) {
+      current.questionText = buffer.join('\n').trim();
+      questions.push(current);
+    }
+    buffer = [];
+    capturing = false;
+    sawLabel = false;
+  };
+
+  // Accept "**Câu hỏi**", "**Câu hỏi:**", "** Câu hỏi **", with/without trailing colon.
+  const QUESTION_LABEL = /^\s*\*\*\s*Câu hỏi\s*:?\s*\*\*\s*:?\s*/i;
+  // A body ends at the next bold field ("**Lý do…**"), a divider, or a heading.
+  const isStop = (l) => /^\s*\*\*/.test(l) || /^---\s*$/.test(l) || /^#{2,3}\s/.test(l);
+
+  for (const line of lines) {
+    const qHeading = line.match(/^###\s+(Q\d+)\s*[:.)-]?\s*(.*)$/i);
+    if (qHeading) {
+      flush();
+      current = { id: qHeading[1].toUpperCase(), name: (qHeading[2] || '').replace(/\[.*?\]/g, '').trim(), questionText: '' };
+      continue;
+    }
+    if (!current) continue;
+
+    // Explicit "**Câu hỏi**" label → capture the rest of this line + following body.
+    if (QUESTION_LABEL.test(line)) {
+      capturing = true;
+      sawLabel = true;
+      buffer.push(line.replace(QUESTION_LABEL, ''));
+      continue;
+    }
+    if (capturing) {
+      if (isStop(line)) { capturing = false; continue; }
+      buffer.push(line);
+      continue;
+    }
+    // Fallback: no "**Câu hỏi**" label — treat the first prose line(s) directly
+    // under "### QNN" as the question body (cards that omit the label still count).
+    if (!sawLabel && buffer.length === 0 && line.trim() && !isStop(line)) {
+      capturing = true;
+      buffer.push(line);
+    }
+  }
+  flush();
+
+  return questions.filter((q) => q.questionText.length > 0);
+}
+
+/**
+ * Find unique code tokens in a question's text.
+ * @returns {Array<{token, kind}>}
+ */
+function findCodeTokens(questionText) {
+  const found = new Map(); // token → kind (first match wins)
+  for (const { name, re } of CODE_TOKEN_PATTERNS) {
+    const matches = questionText.match(re);
+    if (!matches) continue;
+    for (const m of matches) {
+      const token = m.trim();
+      if (token && !found.has(token)) found.set(token, name);
+    }
+  }
+  return [...found.entries()].map(([token, kind]) => ({ token, kind }));
+}
+
+/**
+ * Lint a business-quiz.md for code-coupled questions + structure.
+ * @param {string} content
+ * @returns {{ issues: string[], warnings: string[], ok: string[] }}
+ */
+function lintBusinessQuiz(content) {
+  const issues = [];
+  const warnings = [];
+  const ok = [];
+
+  // Required headings — tolerant match (emoji/case/suffix ok), same spirit as
+  // SKILL.md's hasHeading. The template ships "## MUST — Câu Hỏi Bắt Buộc" and
+  // authors add emoji ("## 🔴 MUST …"); a strict substring check false-flagged those.
+  const clean = stripComments(content);
+  for (const h of REQUIRED_QUIZ_HEADINGS) {
+    if (!hasHeading(clean, h)) {
+      issues.push(`business-quiz.md: thiếu heading "${h}" (hoặc biến thể MUST/SHOULD)`);
+    }
+  }
+
+  // Answer-leak: the file is designed to contain NO answers (human is the key).
+  if (/^#{2,3}\s+(Đáp án|Answer|Đáp Án)\b/im.test(clean)) {
+    warnings.push('business-quiz.md: phát hiện mục "Đáp án/Answer" — file quiz KHÔNG được chứa đáp án (human BA/PO là answer key)');
+  }
+
+  const questions = extractQuizQuestions(content);
+  if (questions.length === 0) {
+    warnings.push('business-quiz.md: không tìm thấy câu hỏi nào (### Q01 …)');
+    return { issues, warnings, ok };
+  }
+
+  let leaked = 0;
+  for (const q of questions) {
+    const tokens = findCodeTokens(q.questionText);
+    if (tokens.length === 0) continue;
+    leaked++;
+    const preview = tokens.slice(0, 5).map((t) => `${t.token} (${t.kind})`).join(', ');
+    const more = tokens.length > 5 ? ` …+${tokens.length - 5}` : '';
+    warnings.push(`${q.id}: câu hỏi dính ngôn ngữ code → BA khó đọc: ${preview}${more}`);
+  }
+
+  if (leaked === 0) {
+    ok.push(`${questions.length} câu hỏi đều dùng ngôn ngữ nghiệp vụ (không dính code)`);
+  } else {
+    ok.push(`${questions.length - leaked}/${questions.length} câu hỏi dùng ngôn ngữ nghiệp vụ`);
+  }
+
+  return { issues, warnings, ok };
+}
+
+// ════════════════════════════════════════════════════════════
+// CARD STRUCTURE VALIDATION
+// ════════════════════════════════════════════════════════════
+
+/** Loose heading presence check (tolerates emoji / trailing qualifiers). */
+function hasHeading(content, heading) {
+  if (content.includes(heading)) return true;
+  // Match on the core text after stripping emoji/punct for No-Go style headings.
+  const core = heading.replace(/^#+\s*/, '').replace(/[^\p{L}\p{N} ]/gu, '').trim().toLowerCase();
+  return content
+    .split('\n')
+    .some((l) => /^#{2,3}\s/.test(l) && l.replace(/[^\p{L}\p{N} ]/gu, '').toLowerCase().includes(core));
+}
+
+/**
+ * Validate one module-card directory (files + headings + placeholders).
+ * Pure over an injected file map for testability; the CLI passes a real reader.
+ *
+ * @param {string} cardName — e.g. "domain-orders"
+ * @param {(file: string) => (string|null)} readFile — returns content or null if absent
+ * @returns {{ issues: string[], warnings: string[], ok: string[] }}
+ */
+function validateModuleCardStructure(cardName, readFile) {
+  const issues = [];
+  const warnings = [];
+  const ok = [];
+
+  // 1. Required files present
+  const missing = [];
+  const present = [];
+  for (const f of REQUIRED_CARD_FILES) {
+    if (readFile(f) === null || readFile(f) === undefined) missing.push(f);
+    else present.push(f);
+  }
+  if (missing.length) issues.push(`thiếu file bắt buộc: ${missing.join(', ')}`);
+  else ok.push(`đủ ${REQUIRED_CARD_FILES.length} file card bắt buộc`);
+
+  for (const f of OPTIONAL_CARD_FILES) {
+    if (readFile(f) !== null && readFile(f) !== undefined) present.push(f);
+  }
+
+  // 2. SKILL.md headings
+  const skill = readFile('SKILL.md');
+  if (skill !== null && skill !== undefined) {
+    const skillClean = stripComments(skill);
+    const missingH = REQUIRED_SKILL_HEADINGS.filter((h) => !hasHeading(skillClean, h));
+    if (missingH.length) issues.push(`SKILL.md: thiếu heading: ${missingH.join(' · ')}`);
+    else ok.push('SKILL.md đủ heading bắt buộc');
+  }
+
+  // 3. Placeholder / unscanned-marker sweep across present files
+  let aiInferred = 0;
+  for (const f of present) {
+    const content = readFile(f);
+    if (content === null || content === undefined) continue;
+    const clean = stripComments(content);
+    if (UNSCANNED_MARKER.test(clean)) {
+      issues.push(`${f}: còn marker chưa scan code (❓ CẦN SCAN) — card chưa đối chiếu code thật`);
+    }
+    if (TEMPLATE_TOKEN.test(clean)) {
+      warnings.push(`${f}: còn placeholder template chưa điền ({…})`);
+    }
+    if (LITERAL_DATE_PLACEHOLDER.test(clean)) {
+      warnings.push(`${f}: còn ngày placeholder "YYYY-MM-DD" chưa điền`);
+    }
+    const inferred = clean.match(AI_INFERRED_MARKER);
+    if (inferred) aiInferred += inferred.length;
+  }
+  if (aiInferred > 0) {
+    warnings.push(`${aiInferred} business rule còn nhãn [⚠️ AI-inferred] — chưa được human xác nhận`);
+  }
+
+  return { issues, warnings, ok };
+}
+
+module.exports = {
+  REQUIRED_CARD_FILES,
+  OPTIONAL_CARD_FILES,
+  REQUIRED_SKILL_HEADINGS,
+  CODE_TOKEN_PATTERNS,
+  stripComments,
+  extractQuizQuestions,
+  findCodeTokens,
+  lintBusinessQuiz,
+  validateModuleCardStructure,
+};

package/cli/lib/module-card-score.js

@@ -0,0 +1,223 @@
+/**
+ * Module Card Score — objective tier of the scorecard (Decision 3).
+ *
+ * Computes the 6-point OBJECTIVE half of a module card's score from facts a
+ * machine can re-check. Pure: (cardName, readFile, oracle) → scorecard object.
+ * Anyone re-running with the same oracle gets the same number — that IS the proof.
+ *
+ *   structural (2)  — files/headings/placeholders + quiz language   [no oracle]
+ *   grounded   (2)  — BR `Source:` refs resolve to real code        [oracle.symbolExists]
+ *   freshness  (1)  — referenced files unchanged since last_verified [oracle.changedSince]
+ *   coverage   (1)  — % of module symbols referenced                 [oracle.symbolsOf → full graph]
+ *
+ * HONEST DEGRADATION: a dimension the oracle can't verify is marked
+ * { verified: false, score: 0 } with a reason — never silently counted as a pass.
+ * Mode stamp: all verified → none · coverage-only missing → "*" · grounded/
+ * freshness also missing (NullOracle) → "†".
+ *
+ * Subjective half (business/dev correctness, depth) is NOT computed here — it
+ * needs human + AI graders (Decision 2/3).
+ */
+
+const { validateModuleCardStructure, lintBusinessQuiz, REQUIRED_CARD_FILES, OPTIONAL_CARD_FILES } = require('./module-card-lint');
+
+const ALL_CARD_FILES = [...REQUIRED_CARD_FILES, ...OPTIONAL_CARD_FILES];
+
+function round1(n) {
+  return Math.round(n * 10) / 10;
+}
+
+/**
+ * Extract code references of the form:  Source: `path/file.ext:123`, hàm `funcName`
+ * @returns {Array<{file, line, name, raw}>}
+ */
+function extractRefs(content) {
+  const refs = [];
+  const re = /Source:\s*`([^`]+)`(?:[^\n]*?hàm\s*`([^`]+)`)?/gi;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    const fileLine = m[1].trim();
+    const name = m[2] ? m[2].trim() : null;
+    let file = fileLine;
+    let line = null;
+    const idx = fileLine.lastIndexOf(':');
+    if (idx > 0 && /^\d+$/.test(fileLine.slice(idx + 1))) {
+      file = fileLine.slice(0, idx);
+      line = parseInt(fileLine.slice(idx + 1), 10);
+    }
+    refs.push({ file, line, name, raw: m[0].trim() });
+  }
+  return refs;
+}
+
+/** Pull last-verified date from SKILL.md (body "**Last verified**" or frontmatter). */
+function extractLastVerified(skillContent) {
+  if (!skillContent) return null;
+  const m =
+    skillContent.match(/\*\*Last verified\*\*\s*:?\s*([0-9]{4}-[0-9]{2}-[0-9]{2})/i) ||
+    skillContent.match(/last_updated\s*:\s*["']?([0-9]{4}-[0-9]{2}-[0-9]{2})/i);
+  return m ? m[1] : null;
+}
+
+/**
+ * @param {string} cardName
+ * @param {(file:string)=>(string|null)} readFile
+ * @param {object} oracle — KnowledgeOracle implementation
+ * @returns {object} scorecard
+ */
+function scoreModuleCard(cardName, readFile, oracle) {
+  const dimensions = [];
+
+  // ── 1. Structural (2) — no oracle ──────────────────────────
+  const struct = validateModuleCardStructure(cardName, readFile);
+  const quizContent = readFile('business-quiz.md');
+  const quizR = quizContent !== null && quizContent !== undefined ? lintBusinessQuiz(quizContent) : { issues: [], warnings: [], ok: [] };
+  const issues = struct.issues.length + quizR.issues.length;
+  const warnings = struct.warnings.length + quizR.warnings.length;
+  const structScore = Math.max(0, Math.min(2, 2 - issues * 0.5 - warnings * 0.1));
+  dimensions.push({
+    key: 'structural',
+    max: 2,
+    score: round1(structScore),
+    verified: true,
+    evidence: { issues, warnings, formula: '2 - issues*0.5 - warnings*0.1' },
+  });
+
+  // Gather all card content + refs once. Dedupe identical refs — the same code
+  // citation appearing in several card files counts once.
+  const allContent = ALL_CARD_FILES.map((f) => readFile(f)).filter(Boolean).join('\n');
+  const seen = new Set();
+  const refs = extractRefs(allContent).filter((r) => {
+    const key = `${r.file}:${r.line}:${r.name}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  // ── 2. Grounded (2) — oracle.symbolExists ──────────────────
+  if (refs.length === 0) {
+    dimensions.push({
+      key: 'grounded',
+      max: 2,
+      score: 0,
+      verified: false,
+      evidence: { refs_total: 0, reason: 'không có ref code (Source:) để đối chiếu' },
+    });
+  } else {
+    const probe = oracle.symbolExists(refs[0]);
+    if (!probe.supported) {
+      dimensions.push({
+        key: 'grounded',
+        max: 2,
+        score: 0,
+        verified: false,
+        evidence: { refs_total: refs.length, reason: probe.reason || 'oracle không hỗ trợ' },
+      });
+    } else {
+      const broken = [];
+      let resolved = 0;
+      for (const ref of refs) {
+        const r = oracle.symbolExists(ref);
+        if (r.exists) resolved++;
+        else broken.push(`${ref.raw} — ${r.reason || 'unresolved'}`);
+      }
+      dimensions.push({
+        key: 'grounded',
+        max: 2,
+        score: round1((resolved / refs.length) * 2),
+        verified: true,
+        evidence: { refs_total: refs.length, refs_resolved: resolved, broken: broken.slice(0, 10) },
+      });
+    }
+  }
+
+  // ── 3. Freshness / no-drift (1) — oracle.changedSince ──────
+  const lastVerified = extractLastVerified(readFile('SKILL.md'));
+  const refFiles = [...new Set(refs.map((r) => r.file))];
+  if (refFiles.length === 0) {
+    dimensions.push({
+      key: 'freshness',
+      max: 1,
+      score: 0,
+      verified: false,
+      evidence: { reason: 'không có file tham chiếu để kiểm drift' },
+    });
+  } else {
+    const probe = oracle.changedSince(refFiles[0], lastVerified);
+    if (!probe.supported || !lastVerified) {
+      dimensions.push({
+        key: 'freshness',
+        max: 1,
+        score: 0,
+        verified: false,
+        evidence: { last_verified: lastVerified, reason: !lastVerified ? 'thiếu Last verified trong SKILL.md' : probe.reason },
+      });
+    } else {
+      const drifted = [];
+      let unchanged = 0;
+      let checkable = 0;
+      for (const f of refFiles) {
+        const r = oracle.changedSince(f, lastVerified);
+        if (r.changed === null) continue; // not checkable (e.g. file missing) — handled by grounded
+        checkable++;
+        if (r.changed) drifted.push(`${f} (${r.commits} commit sau ${lastVerified})`);
+        else unchanged++;
+      }
+      dimensions.push({
+        key: 'freshness',
+        max: 1,
+        score: checkable === 0 ? 0 : round1((unchanged / checkable) * 1),
+        verified: checkable > 0,
+        evidence: {
+          last_verified: lastVerified,
+          files_checked: checkable,
+          drifted: drifted.slice(0, 10),
+          // checkable===0 → mọi file ref đều không kiểm được (thiếu file). Không có
+          // reason ở đây thì evidenceLine in ra "undefined".
+          ...(checkable === 0 ? { reason: 'không có file tham chiếu nào tồn tại để kiểm drift (xem chiều Bằng chứng)' } : {}),
+        },
+      });
+    }
+  }
+
+  // ── 4. Coverage (1) — oracle.symbolsOf (full graph) ────────
+  // Scope = directories of the card's referenced files (the area it "owns").
+  const refDirs = [...new Set(refFiles.map((f) => (f.includes('/') ? f.slice(0, f.lastIndexOf('/')) : '.')))];
+  const cov = oracle.symbolsOf(cardName, { files: refFiles, dirs: refDirs });
+  if (!cov.supported) {
+    dimensions.push({
+      key: 'coverage',
+      max: 1,
+      score: 0,
+      verified: false,
+      evidence: { reason: cov.reason || 'cần full-graph oracle' },
+    });
+  } else {
+    const total = cov.symbols ? cov.symbols.length : 0;
+    const mentioned = total === 0 ? 0 : cov.symbols.filter((s) => allContent.includes(s)).length;
+    dimensions.push({
+      key: 'coverage',
+      max: 1,
+      score: total === 0 ? 0 : round1((mentioned / total) * 1),
+      verified: total > 0,
+      evidence: { symbols_total: total, symbols_mentioned: mentioned },
+    });
+  }
+
+  // ── Totals + honest mode stamp ─────────────────────────────
+  const total = round1(dimensions.reduce((s, d) => s + d.score, 0));
+  const fullyVerified = dimensions.every((d) => d.verified);
+  const stamp = fullyVerified ? '' : oracle.name === 'declared-only' ? '†' : '*';
+
+  return {
+    module: cardName,
+    oracle: oracle.name,
+    objective_total: total,
+    objective_max: 6,
+    fully_verified: fullyVerified,
+    stamp,
+    dimensions,
+  };
+}
+
+module.exports = { scoreModuleCard, extractRefs, extractLastVerified, round1 };