sdtk-kit 0.3.9 → 1.0.0

package/assets/toolkit/toolkit/skills/sdtk-screen-design-spec/scripts/validate_flow_action_spec_numbering.py

@@ -1,414 +0,0 @@
-from __future__ import annotations
-
-import argparse
-import re
-import sys
-from dataclasses import dataclass
-from pathlib import Path
-
-
-TABLE_ROW_RE = re.compile(r"^\|.*\|\s*$")
-TABLE_SEP_RE = re.compile(r"^\|\s*:?-+:?\s*(\|\s*:?-+:?\s*)+\|\s*$")
-HEADING_RE = re.compile(r"^(#{1,6})\s+(.*\S)\s*$")
-SCREEN_SECTION_HEADING_RE = re.compile(r"^###\s+(.*\S)\s*$", re.MULTILINE)
-VI_DIACRITIC_RE = re.compile(r"[À-ỹ]")
-VI_PHRASE_RE = re.compile(
-    r"\b("
-    r"thuc thi|hien thi|cap nhat|bo sung|can xac nhan|trong anh|"
-    r"duoc tra kem|tao lich|theo user|muc global|thay the cho|bao gom"
-    r")\b",
-    re.IGNORECASE,
-)
-INLINE_HEADING_RE = re.compile(r".+\s#{2,}\s+\S")
-IMAGE_LINK_RE = re.compile(r"!\[[^\]]*\]\(([^)]+)\)")
-PLANTUML_FENCE_START_RE = re.compile(r"^\s*```plantuml\s*$", re.IGNORECASE)
-NEW_STYLE_ACTIVITY_LINE_RE = re.compile(
-    r"^\s*(start|stop|partition\s+\"|if\s*\(|fork(?:\s+again)?\b|end\s+fork\b|note\s+(?:right|left|top|bottom)\b|:[^;\n]+;)",
-    re.IGNORECASE,
-)
-LEGACY_ACTIVITY_START_RE = re.compile(r"\(\*\)")
-LEGACY_EDGE_LABEL_RE = re.compile(r"-->\s*\[")
-MIXED_ACTIVITY_ARROW_RE = re.compile(r":[^;\n]+;\s*-->")
-
-
-@dataclass(frozen=True)
-class Occurrence:
-    number: int
-    section: str
-    line_no: int
-    raw_line: str
-
-
-def _split_table_row(line: str) -> list[str]:
-    # Keep it simple: markdown tables in our spec are plain and don't escape pipes.
-    parts = [p.strip() for p in line.strip().strip("|").split("|")]
-    return parts
-
-
-def _read_text(path: Path) -> str:
-    # Prefer UTF-8; fallback to cp1252-ish if user saved without UTF-8.
-    for enc in ("utf-8", "utf-8-sig", "cp1252"):
-        try:
-            return path.read_text(encoding=enc)
-        except UnicodeDecodeError:
-            continue
-    return path.read_text(errors="replace")
-
-
-def collect_hygiene_issues(md_text: str, *, en_check: bool) -> dict[str, list[tuple[int, str]]]:
-    issues: dict[str, list[tuple[int, str]]] = {
-        "encoding": [],
-        "vi_diacritic": [],
-        "vi_phrase": [],
-        "inline_heading": [],
-    }
-    lines = md_text.splitlines()
-    in_code_block = False
-
-    for idx, line in enumerate(lines, start=1):
-        stripped = line.strip()
-        if stripped.startswith("```"):
-            in_code_block = not in_code_block
-            continue
-        if in_code_block:
-            continue
-
-        if "�" in line or "ↁE" in line:
-            issues["encoding"].append((idx, line))
-
-        # A common corruption symptom: merged headings inside normal text lines.
-        if INLINE_HEADING_RE.search(line) and not stripped.startswith("#"):
-            issues["inline_heading"].append((idx, line))
-
-        if en_check:
-            lowered = stripped.lower()
-            if "original text" in lowered:
-                continue
-            if VI_DIACRITIC_RE.search(line):
-                issues["vi_diacritic"].append((idx, line))
-            elif VI_PHRASE_RE.search(line):
-                issues["vi_phrase"].append((idx, line))
-
-    return issues
-
-
-def _is_root_relative_docs_href(href: str) -> bool:
-    normalized = href.strip().replace("\\", "/").lower()
-    if not normalized:
-        return False
-    if re.match(r"^[a-z][a-z0-9+.-]*://", normalized):
-        return False
-    if normalized.startswith(("mailto:", "tel:", "data:", "#")):
-        return False
-    return normalized.startswith(("docs/", "./docs/", "/docs/"))
-
-
-def collect_screen_image_path_issues(md_text: str) -> list[tuple[int, str]]:
-    issues: list[tuple[int, str]] = []
-    lines = md_text.splitlines()
-    in_code_block = False
-    expecting_image_line = False
-
-    for idx, line in enumerate(lines, start=1):
-        stripped = line.strip()
-        if stripped.startswith("```"):
-            in_code_block = not in_code_block
-            expecting_image_line = False
-            continue
-        if in_code_block:
-            continue
-        if not stripped:
-            continue
-
-        if stripped.lower().startswith("screen image:"):
-            expecting_image_line = stripped.lower() == "screen image:"
-            hrefs = IMAGE_LINK_RE.findall(stripped)
-        elif expecting_image_line and stripped.startswith("!["):
-            expecting_image_line = False
-            hrefs = IMAGE_LINK_RE.findall(stripped)
-        else:
-            hrefs = []
-            if not stripped.startswith("<!--"):
-                expecting_image_line = False
-
-        for href in hrefs:
-            if _is_root_relative_docs_href(href):
-                issues.append((idx, href))
-
-    return issues
-
-
-def collect_plantuml_activity_syntax_issues(md_text: str) -> list[tuple[int, str]]:
-    issues: list[tuple[int, str]] = []
-    lines = md_text.splitlines()
-    in_plantuml_block = False
-    block_start_line = 0
-    block_lines: list[str] = []
-
-    def flush_block() -> None:
-        nonlocal issues, block_lines, block_start_line
-        if not block_lines:
-            return
-        has_new_style = any(NEW_STYLE_ACTIVITY_LINE_RE.search(line) for line in block_lines)
-        if not has_new_style:
-            block_lines = []
-            block_start_line = 0
-            return
-
-        for offset, line in enumerate(block_lines, start=0):
-            line_no = block_start_line + offset
-            if LEGACY_ACTIVITY_START_RE.search(line):
-                issues.append(
-                    (line_no, "Legacy activity start marker `(*)` is not allowed in new-style activity diagrams.")
-                )
-            if MIXED_ACTIVITY_ARROW_RE.search(line):
-                issues.append(
-                    (line_no, "Do not append legacy `-->` transitions after a new-style `:Activity;` action line.")
-                )
-            elif LEGACY_EDGE_LABEL_RE.search(line):
-                issues.append(
-                    (line_no, "Legacy edge labels like `--> [label]` are not allowed in new-style activity diagrams.")
-                )
-
-        block_lines = []
-        block_start_line = 0
-
-    for idx, line in enumerate(lines, start=1):
-        if not in_plantuml_block and PLANTUML_FENCE_START_RE.match(line):
-            in_plantuml_block = True
-            block_start_line = idx + 1
-            block_lines = []
-            continue
-
-        if in_plantuml_block and line.strip().startswith("```"):
-            flush_block()
-            in_plantuml_block = False
-            continue
-
-        if in_plantuml_block:
-            block_lines.append(line)
-
-    if in_plantuml_block:
-        flush_block()
-
-    return issues
-
-
-def collect_wireframe_mapping_issues(md_text: str) -> list[tuple[int, str]]:
-    issues: list[tuple[int, str]] = []
-    sections = list(SCREEN_SECTION_HEADING_RE.finditer(md_text))
-    for idx, match in enumerate(sections):
-        start = match.start()
-        end = sections[idx + 1].start() if idx + 1 < len(sections) else len(md_text)
-        section_text = md_text[start:end]
-
-        if "Design Source Type: generated-draft" not in section_text:
-            continue
-        if "> Screen image not rendered in this environment." in section_text:
-            continue
-        if "Screen image:" not in section_text or "![" not in section_text:
-            continue
-        if "#### Wireframe Marker Mapping" in section_text:
-            continue
-
-        line_no = md_text.count("\n", 0, start) + 1
-        section_name = match.group(1).strip()
-        issues.append(
-            (line_no, f"{section_name}: missing `Wireframe Marker Mapping` table for generated-draft screen.")
-        )
-
-    return issues
-
-
-def parse_action_tables(md_text: str) -> list[Occurrence]:
-    occurrences: list[Occurrence] = []
-    current_section = ""
-    lines = md_text.splitlines()
-
-    i = 0
-    while i < len(lines):
-        line = lines[i]
-
-        m = HEADING_RE.match(line)
-        if m:
-            current_section = m.group(2).strip()
-
-        # Detect table header
-        if i + 1 < len(lines) and TABLE_ROW_RE.match(line) and TABLE_ROW_RE.match(lines[i + 1]):
-            header = _split_table_row(line)
-            sep = lines[i + 1]
-
-            if not TABLE_SEP_RE.match(sep):
-                i += 1
-                continue
-
-            # Only validate action tables: must contain No + Action + Description
-            lowered = [h.lower() for h in header]
-            if "no" not in lowered and "no." not in lowered:
-                i += 1
-                continue
-            if "action" not in lowered or "description" not in lowered:
-                i += 1
-                continue
-
-            try:
-                no_index = lowered.index("no")
-            except ValueError:
-                no_index = lowered.index("no.")
-
-            # Consume rows until table ends
-            j = i + 2
-            while j < len(lines) and TABLE_ROW_RE.match(lines[j]):
-                row = _split_table_row(lines[j])
-                if len(row) <= no_index:
-                    j += 1
-                    continue
-                raw_no = row[no_index]
-                try:
-                    number = int(raw_no)
-                except ValueError:
-                    j += 1
-                    continue
-                occurrences.append(
-                    Occurrence(
-                        number=number,
-                        section=current_section or "(unknown section)",
-                        line_no=j + 1,  # 1-based
-                        raw_line=lines[j],
-                    )
-                )
-                j += 1
-
-            i = j
-            continue
-
-        i += 1
-
-    return occurrences
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description="Validate numbering in flow-action spec tables.")
-    parser.add_argument("--spec", required=True, help="Path to *_FLOW_ACTION_SPEC.md")
-    parser.add_argument(
-        "--en-check",
-        action="store_true",
-        help="Enable EN artifact hygiene checks (Vietnamese leftovers + encoding corruption).",
-    )
-    args = parser.parse_args()
-
-    try:
-        sys.stdout.reconfigure(encoding="utf-8")  # type: ignore[attr-defined]
-        sys.stderr.reconfigure(encoding="utf-8")  # type: ignore[attr-defined]
-    except Exception:
-        pass
-
-    spec_path = Path(args.spec)
-    if not spec_path.exists():
-        print(f"[ERROR] Not found: {spec_path}", file=sys.stderr)
-        return 2
-
-    text = _read_text(spec_path)
-    occ = parse_action_tables(text)
-
-    by_number: dict[int, list[Occurrence]] = {}
-    for o in occ:
-        by_number.setdefault(o.number, []).append(o)
-
-    duplicates = {n: os for n, os in by_number.items() if len(os) > 1}
-
-    max_seen = -1
-    decreases: list[tuple[Occurrence, int]] = []
-    for o in occ:
-        if o.number < max_seen:
-            decreases.append((o, max_seen))
-        max_seen = max(max_seen, o.number)
-
-    has_issues = bool(duplicates or decreases)
-    hygiene = collect_hygiene_issues(text, en_check=args.en_check)
-    image_path_issues = collect_screen_image_path_issues(text)
-    plantuml_activity_issues = collect_plantuml_activity_syntax_issues(text)
-    wireframe_mapping_issues = collect_wireframe_mapping_issues(text)
-    if hygiene["encoding"] or hygiene["inline_heading"]:
-        has_issues = True
-    if args.en_check and (hygiene["vi_diacritic"] or hygiene["vi_phrase"]):
-        has_issues = True
-    if image_path_issues:
-        has_issues = True
-    if plantuml_activity_issues:
-        has_issues = True
-    if wireframe_mapping_issues:
-        has_issues = True
-
-    print(f"Checked: {spec_path}")
-    print(f"- Total numbered rows: {len(occ)}")
-    print(f"- Unique numbers: {len(by_number)}")
-    print(f"- EN hygiene check enabled: {args.en_check}")
-
-    if not occ:
-        print("[WARN] No action tables detected (| No | Action | Description | ... |).")
-
-    if duplicates:
-        print("\n[FAIL] Duplicate numbers found:")
-        for n in sorted(duplicates.keys()):
-            print(f"- No {n}:")
-            for o in duplicates[n]:
-                print(f"  - {o.section} (line {o.line_no})")
-
-    if decreases:
-        print("\n[FAIL] Numbering decreases/resets detected (global numbering policy):")
-        for o, prev_max in decreases:
-            print(f"- No {o.number} after max {prev_max}: {o.section} (line {o.line_no})")
-
-    if hygiene["encoding"]:
-        print("\n[FAIL] Encoding/mojibake markers detected:")
-        for line_no, line in hygiene["encoding"][:20]:
-            print(f"- line {line_no}: {line.strip()}")
-
-    if hygiene["inline_heading"]:
-        print("\n[FAIL] Inline/merged heading patterns detected:")
-        for line_no, line in hygiene["inline_heading"][:20]:
-            print(f"- line {line_no}: {line.strip()}")
-
-    if args.en_check and hygiene["vi_diacritic"]:
-        print("\n[FAIL] Vietnamese diacritic text detected in EN artifact:")
-        for line_no, line in hygiene["vi_diacritic"][:20]:
-            print(f"- line {line_no}: {line.strip()}")
-
-    if args.en_check and hygiene["vi_phrase"]:
-        print("\n[FAIL] Vietnamese phrase patterns detected in EN artifact:")
-        for line_no, line in hygiene["vi_phrase"][:20]:
-            print(f"- line {line_no}: {line.strip()}")
-
-    if image_path_issues:
-        print("\n[FAIL] Screen image markdown paths must be file-relative, not docs-root-relative:")
-        for line_no, href in image_path_issues[:20]:
-            print(f"- line {line_no}: {href}")
-
-    if plantuml_activity_issues:
-        print("\n[FAIL] Mixed or legacy PlantUML activity syntax detected in a new-style screen-flow block:")
-        for line_no, message in plantuml_activity_issues[:20]:
-            print(f"- line {line_no}: {message}")
-
-    if wireframe_mapping_issues:
-        print("\n[FAIL] Missing wireframe-marker mapping tables for generated-draft screens:")
-        for line_no, message in wireframe_mapping_issues[:20]:
-            print(f"- line {line_no}: {message}")
-
-    if not has_issues:
-        print("\n[OK] Numbering and text hygiene checks passed.")
-        return 0
-
-    print("\nHint: Use global numbering across the full document.")
-    print("- Do not repeat No values in any action table.")
-    print("- Do not reset numbering per screen/dialog.")
-    print("- Use file-relative screen image paths such as assets/<feature>/screens/<screen>.svg.")
-    print("- Use new-style PlantUML activity syntax only for screen-flow diagrams.")
-    print("- Add a `Wireframe Marker Mapping` table when a generated-draft screen embeds a wireframe image.")
-    print("- Keep EN artifacts free of Vietnamese leftovers and encoding corruption.")
-    print("- Keep headings/sections on separate lines (avoid merged markdown blocks).")
-    return 1
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/assets/toolkit/toolkit/skills/sdtk-test-case-spec/SKILL.md

@@ -1,74 +0,0 @@
----
-name: sdtk-test-case-spec
-description: Generate screen-based QA test-case markdown (`[FEATURE_KEY]_TEST_CASE.md`) in Excel-aligned layout (Statistic + per-screen UTC/ITC worksheets). Use when QA needs reusable test design artifacts before or during execution.
----
-
-# SDTK Test Case Spec
-
-## Critical Constraints
-- I do not invent test coverage beyond BA, flow-action, and API sources.
-- I do not let test totals drift away from worksheet rows or the QA baseline.
-
-## Outputs
-- `docs/qa/[FEATURE_KEY]_TEST_CASE.md`
-- Optional project variant:
-  - `docs/en/qa/[FEATURE_KEY]_TEST_CASE.md` (only when project uses `docs/en/**`)
-
-## Required Inputs
-- Feature key (`FEATURE_KEY`)
-- Screen/flow references:
-  - `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md`
-  - `docs/specs/BA_SPEC_[FEATURE_KEY].md`
-- API reference:
-  - `docs/api/[FEATURE_KEY]_ENDPOINTS.md`
-  - (optional) `docs/api/[FeaturePascal]_API.yaml`
-- Clarification source:
-  - `docs/specs/Q&A.md` or `docs/en/specs/Q&A.md` when available
-
-## Core Rules
-1. Apply `./references/TEST_CASE_CREATION_RULES.md` first.
-2. Keep section order fixed (Statistic -> Abbreviations -> Scope -> References -> Environment -> Coverage -> Screen-based UTC/ITC -> OQ -> STC/UAT note).
-3. Use screen-first layout to mirror worksheet structure.
-4. Keep one unified 18-column schema for UTC/ITC rows.
-5. Keep stable case IDs; do not renumber only because of regrouping.
-6. Track unresolved decisions via `OQ-xx` and keep benchmark-expected OQs explicitly OPEN per `governance/ai/core/SDTK_BENCHMARK_OQ_POLICY.md`.
-7. Quote exact BA, API, or flow-action requirement text when a testcase or coverage claim depends on that requirement.
-
-## Procedure
-1. Resolve output path:
-   - default `docs/qa/[FEATURE_KEY]_TEST_CASE.md`
-   - use `docs/en/qa/...` only if the repo already follows `docs/en/**`.
-2. Build/refresh `Statistic Summary (Excel-aligned)` with UT total, IT total, and grand total.
-3. Build `Feature Coverage Matrix` from flow/action and API docs.
-4. Split UTC/ITC by screen sections (`screen-first`), not by test type only.
-5. Fill conflict/permission/error-path cases from Q&A decisions and API contracts.
-6. Record unresolved items in section `Open Questions`.
-7. Validate:
-   - counts in summary match table rows
-   - structured TEST_CASE total stays aligned with the QA release-report baseline; if E2E is tracked separately, label it separately instead of inflating grand total
-   - no placeholder tokens like `??`
-   - out-of-scope boundaries are explicit
-
-## Specification Quoting
-When a testcase, coverage note, or defect check depends on a requirement, quote the exact source text before stating coverage or mismatch.
-
-Use this format:
-- `Spec says: "[exact quote]" -> Evidence: [covered/not covered + file reference]`
-
-## Role Integration
-- Primary owner: `/qa`.
-- `/qa` uses this skill to design/update reusable test-case specs.
-- `sdtk-qa` still owns release decision artifact (`QA_RELEASE_REPORT_*`).
-
-## Notes
-- This skill is for test-case specification artifacts, not test execution logs.
-- For release approval and defect triage, continue with `sdtk-qa`.
-
-## Validator Script
-- `scripts/validate_test_case_spec.py`
-
-### Typical command
-```powershell
-python "toolkit/skills/sdtk-test-case-spec/scripts/validate_test_case_spec.py" `
-  --file "docs/qa/[FEATURE_KEY]_TEST_CASE.md"
-```

package/assets/toolkit/toolkit/skills/sdtk-test-case-spec/references/TEST_CASE_CREATION_RULES.md

@@ -1,129 +0,0 @@
-# TEST CASE CREATION RULES
-## Canonical rules for `[FEATURE_KEY]_TEST_CASE.md`
-
-**Version:** 1.0.0  
-**Last Updated:** 2026-02-25
-
----
-
-## 1. Purpose
-- Standardize creation of feature test-case documents in markdown.
-- Mirror Excel-style worksheet layout while keeping output reviewable in `.md`.
-- Keep QA artifacts reusable across projects, domains, and screen sets.
-
----
-
-## 2. Output Contract
-- Primary output file:
-  - `docs/qa/[FEATURE_KEY]_TEST_CASE.md`
-- Optional language/project variant:
-  - `docs/en/qa/[FEATURE_KEY]_TEST_CASE.md` (only when the project explicitly uses `docs/en/**`).
-
----
-
-## 3. Required Section Order
-1. Document metadata (`Document ID`, `Version`, `Date`, `Author`, `Status`)
-2. `Statistic Summary (Excel-aligned)`
-3. `Abbreviations`
-4. `1. Scope`
-5. `2. References`
-6. `3. Test Environment and Common Data`
-7. `4. Feature Coverage Matrix`
-8. `5. Screen-based Test Cases (Excel-aligned)`
-9. `6. Open Questions (for final freeze)`
-10. `7. STC/UAT Note`
-
-Do not reorder these sections unless the user requests a different contract.
-
----
-
-## 4. Statistic Summary Rules
-- Place summary near the top of the file (before detailed UTC/ITC tables).
-- Keep columns aligned with Excel `Statistic` logic:
-  - `Num of Case`
-  - `OK`
-  - `NG`
-  - `Not tested yet`
-  - `Done (%)`
-  - `Updated Date`
-- Compute:
-  - `Not tested yet = Num of Case - (OK + NG)`
-  - `Done (%) = (OK + NG) / Num of Case`
-- Include subtotal rows at minimum:
-  - `Unit Test Total`
-  - `Integration Test Total`
-  - `Grand Total`
-
----
-
-## 5. Screen-Based Worksheet Mapping
-- Use `screen-first` layout to mirror Excel tabs:
-  - Each functional screen has a section (for example `SCH01`, `SCH02`, ...).
-  - Each screen section can have 2 sub-sections:
-    - `UTC` worksheet (name pattern: `[SCREEN_KEY]_UTC`)
-    - `ITC` worksheet (name pattern: `[SCREEN_KEY]_ITC`)
-- Add one mapping table in section 5 that lists:
-  - `Screen`
-  - `Suggested Worksheet Pair`
-  - `UTC Cases`
-  - `ITC Cases`
-  - `Notes`
-
----
-
-## 6. Test Case Table Schema (Mandatory)
-- Use one unified 18-column schema for both UTC and ITC tables:
-  - `No`
-  - `Test Type`
-  - `Test Perspective`
-  - `Test Item`
-  - `Precondition`
-  - `Test Steps`
-  - `Expected Result`
-  - `Browser`
-  - `Test Execution Result`
-  - `Remarks`
-  - `Reviewer`
-  - `Review Date`
-  - `OK/NG`
-  - `Cause`
-  - `Countermeasure`
-  - `Owner`
-  - `Completion Date`
-  - `Confirmation`
-
----
-
-## 7. Numbering and ID Policy
-- Keep a stable `No` for each test case row.
-- Do not renumber existing case IDs only for visual regrouping.
-- In screen-split sections, case IDs may be non-contiguous; this is allowed.
-- Summary/helper tables must keep contiguous `No` (`1,2,3,...`).
-
----
-
-## 8. Open Questions (OQ) Policy
-- If expected behavior is unclear, create `OQ-xx` entries in section 6.
-- Do not assume behavior for:
-  - permission matrix
-  - conflict dialog/action semantics
-  - API contract ambiguities
-  - release-scope boundary
-- When resolved, keep question row and set status/remarks to resolved.
-
----
-
-## 9. Language and Encoding
-- Default artifact language: English.
-- Keep original JP/VI labels when required by business/UI traceability (for example button labels).
-- File encoding must be UTF-8.
-- Avoid mojibake and placeholder tokens (`??`, `?????`) in final output.
-
----
-
-## 10. Final Validation Checklist
-- Required sections exist and are in correct order.
-- Statistic totals equal sum of UTC/ITC rows.
-- Screen mapping table case counts match actual UTC/ITC table counts.
-- Scope explicitly states in-scope and out-of-scope boundaries.
-- Open questions are explicitly tracked with owner and impact.