Create detailed report

Author: johnsamuelwrites

.github/QUICK_REFERENCE.md

@@ -0,0 +1,112 @@
+# Quick Reference: Keyword Sync Workflow
+
+## Before You Commit
+
+`bash
+# 1. Install deps (one-time)
+pip install pyyaml
+
+# 2. Validate locally
+python .github/scripts/sync-keywords.py \
+  --reference ../multilingual/multilingualprogramming/resources/usm/keywords.json \
+  --target data/keywords.yaml \
+  --report sync-report.json
+
+# 3. Check results
+python .github/scripts/check-sync-results.py sync-report.json
+# Exit code 0 = pass, 1 = fail
+
+# 4. View details
+cat sync-report.json | jq .
+`
+
+## Updating Keywords Interactively
+
+`bash
+# Dry-run: see what would change
+python .github/scripts/update-keywords-from-reference.py \
+  --reference ../multilingual/multilingualprogramming/resources/usm/keywords.json \
+  --target data/keywords.yaml \
+  --dry-run
+
+# Actually update (creates backup)
+python .github/scripts/update-keywords-from-reference.py \
+  --reference ../multilingual/multilingualprogramming/resources/usm/keywords.json \
+  --target data/keywords.yaml \
+  --interactive \
+  --backup
+`
+
+## GitHub Workflow Feedback
+
+When you push/PR with keyword changes:
+
+✓ Workflow runs automatically
+✓ Creates sync-report.json
+✓ Posts comment on PR with results
+✓ Artifacts available for download
+
+**Example PR Comment:**
+`
+## Keyword Registry Sync Report
+
+✅ All keywords are in sync with the reference implementation.
+
+**Coverage**: 100%
+`
+
+**Or if issues:**
+`
+## Keyword Registry Sync Report
+
+⚠️ Keyword registry sync issues detected.
+
+### Language Mismatches
+- if (ja): Expected 'もし', got '如果'
+- class (fr): Expected 'classe', got 'class'
+
+**Coverage**: 95%
+`
+
+## Common Issues
+
+**"Coverage below 95%"**
+→ Add missing constructs to keywords.yaml or lower threshold
+
+**"Language mismatches detected"**  
+→ Update values in keywords.yaml to match reference
+
+**"Missing language support"**
+→ Add language columns (sv, da, fi, etc.) to keywords.yaml
+
+**Unicode errors**
+→ Ensure keywords.yaml is UTF-8 encoded
+
+## File Locations
+
+- Workflow: .github/workflows/sync-keywords.yml
+- Sync script: .github/scripts/sync-keywords.py
+- Check script: .github/scripts/check-sync-results.py
+- Update script: .github/scripts/update-keywords-from-reference.py
+- Keywords: data/keywords.yaml
+- Reference: ../multilingual/multilingualprogramming/resources/usm/keywords.json
+- Report: sync-report.json (generated)
+- Docs: .github/SYNC_WORKFLOW.md
+
+## Configuration
+
+In .github/workflows/sync-keywords.yml:
+
+`yaml
+# Minimum coverage threshold
+check-sync-results.py sync-report.json --min-coverage 95
+
+# Strict mode (fail on warnings)
+check-sync-results.py sync-report.json --strict
+`
+
+## Resources
+
+- 🔗 Multilingual Repo: https://github.com/multilingualprogramming/multilingual
+- 📖 Full Docs: .github/SYNC_WORKFLOW.md
+- 🐛 Issues: .github/scripts/ (check source code)

.github/scripts/check-sync-results.py

@@ -43,30 +43,30 @@ def main():
         failed = False
 
         if status == 'error':
-            print('❌ FAILED: Validation error occurred')
+            sys.stdout.write('[FAIL] Validation error occurred\n')
             failed = True
 
         if status == 'warning' and args.strict:
-            print('⚠️  FAILED: Warnings detected in strict mode')
+            sys.stdout.write('[FAIL] Warnings detected in strict mode\n')
             failed = True
 
         if coverage < args.min_coverage:
-            print(f'❌ FAILED: Coverage {coverage}% below minimum {args.min_coverage}%')
+            sys.stdout.write(f'[FAIL] Coverage {coverage}% below minimum {args.min_coverage}%\n')
             failed = True
 
         if missing_constructs > 0:
-            print(f'⚠️  WARNING: {missing_constructs} missing constructs in target')
+            sys.stdout.write(f'[WARN] {missing_constructs} missing constructs in target\n')
 
         if mismatches > 0:
-            print(f'⚠️  WARNING: {mismatches} keyword mismatches detected')
+            sys.stdout.write(f'[WARN] {mismatches} keyword mismatches detected\n')
 
         if not failed:
             if status == 'success':
-                print('✅ PASSED: Keywords are in sync')
+                sys.stdout.write('[PASS] Keywords are in sync\n')
             elif status == 'warning':
-                print('✅ PASSED: Warnings detected but acceptable')
+                sys.stdout.write('[PASS] Warnings detected but acceptable\n')
             else:
-                print('✅ PASSED: Validation complete')
+                sys.stdout.write('[PASS] Validation complete\n')
 
         print()
         sys.exit(1 if failed else 0)

.github/scripts/sync-keywords.py

@@ -1,11 +1,11 @@
-#!/usr/bin/env python3
+#!/usr/bin/env python3
 """
 Validate keyword registry sync with multilingual reference implementation.
 
 Compares the tree-sitter-multilingual keywords.yaml with the reference
 keywords.json from the multilingual repository, checking for:
 - Missing or extra constructs
-- Language mismatches
+- Language mismatches with normalization
 - Keyword value differences
 - Coverage gaps
 
@@ -34,7 +34,9 @@ def load_target_keywords(path: str) -> Dict[str, Any]:
 
 
 def normalize_keyword(kw: str) -> str:
-    """Normalize keyword for comparison (lowercase, strip spaces)."""
+    """Normalize keyword for comparison (lowercase, strip spaces, handle variants)."""
+    if not isinstance(kw, str):
+        kw = str(kw)
     return kw.lower().strip().replace(' ', '_').replace('-', '_')
 
 
@@ -137,13 +139,7 @@ def compare_keywords(
             ref_value = ref_langs[lang]
             target_value = target_langs.get(lang)
 
-            # Normalize for comparison
-            ref_normalized = normalize_keyword(ref_value) if isinstance(ref_value, str) else \
-                            [normalize_keyword(v) for v in ref_value]
-            target_normalized = normalize_keyword(target_value) if isinstance(target_value, str) and target_value else \
-                               [normalize_keyword(v) for v in target_value] if isinstance(target_value, list) else None
-
-            # Check if values match (allowing for normalization)
+            # Check if values match
             if target_value is None:
                 construct_details['missing_languages'].append(lang)
                 construct_details['complete'] = False
@@ -153,35 +149,35 @@ def compare_keywords(
                 })
                 report['status'] = 'warning'
             else:
+                # Normalize both for comparison
+                if isinstance(ref_value, list):
+                    ref_normalized = set(normalize_keyword(v) for v in ref_value)
+                else:
+                    ref_normalized = set([normalize_keyword(ref_value)])
+
+                if isinstance(target_value, list):
+                    target_normalized = set(normalize_keyword(v) for v in target_value)
+                else:
+                    target_normalized = set([normalize_keyword(target_value)])
+
                 # Compare normalized values
-                if isinstance(ref_normalized, list) and isinstance(target_normalized, list):
-                    if set(ref_normalized) != set(target_normalized):
-                        construct_details['mismatches'].append({
-                            'language': lang,
-                            'expected': ref_value,
-                            'actual': target_value,
-                        })
-                        report['language_mismatches'].append({
-                            'construct': construct,
-                            'language': lang,
-                            'expected': ref_value if isinstance(ref_value, str) else ref_value[0],
-                            'actual': target_value if isinstance(target_value, str) else target_value[0],
-                        })
-                        report['status'] = 'warning'
-                elif isinstance(ref_normalized, str) and isinstance(target_normalized, str):
-                    if ref_normalized != target_normalized:
-                        construct_details['mismatches'].append({
-                            'language': lang,
-                            'expected': ref_value,
-                            'actual': target_value,
-                        })
-                        report['language_mismatches'].append({
-                            'construct': construct,
-                            'language': lang,
-                            'expected': ref_value,
-                            'actual': target_value,
-                        })
-                        report['status'] = 'warning'
+                if ref_normalized != target_normalized:
+                    # Get display values
+                    ref_display = ref_value if isinstance(ref_value, str) else ref_value[0] if ref_value else ''
+                    target_display = target_value if isinstance(target_value, str) else target_value[0] if target_value else ''
+
+                    construct_details['mismatches'].append({
+                        'language': lang,
+                        'expected': ref_value,
+                        'actual': target_value,
+                    })
+                    report['language_mismatches'].append({
+                        'construct': construct,
+                        'language': lang,
+                        'expected': ref_display,
+                        'actual': target_display,
+                    })
+                    report['status'] = 'warning'
 
         report['details'][construct] = construct_details
 
@@ -213,73 +209,91 @@ def main():
     args = parser.parse_args()
 
     try:
-        # Load data
-        print('Loading reference keywords...')
+        # Force UTF-8 output
+        if sys.stdout.encoding != 'utf-8':
+            import io
+            sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', line_buffering=True)
+        if sys.stderr.encoding != 'utf-8':
+            import io
+            sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8', line_buffering=True)
+
+        sys.stdout.write('Loading reference keywords...\n')
+        sys.stdout.flush()
         ref_data = load_reference_keywords(args.reference)
         ref_languages = ref_data.get('languages', [])
 
-        print('Loading target keywords...')
+        sys.stdout.write('Loading target keywords...\n')
+        sys.stdout.flush()
         target_data = load_target_keywords(args.target)
 
         # Extract and normalize
-        print('Extracting reference keywords...')
+        sys.stdout.write('Extracting reference keywords...\n')
+        sys.stdout.flush()
         ref_keywords = extract_reference_keywords(ref_data)
 
         # Compare
-        print('Comparing keywords...')
+        sys.stdout.write('Comparing keywords...\n')
+        sys.stdout.flush()
         report, all_good = compare_keywords(ref_keywords, target_data, ref_languages)
 
         # Write report
-        print(f'Writing report to {args.report}...')
+        sys.stdout.write(f'Writing report to {args.report}...\n')
+        sys.stdout.flush()
         with open(args.report, 'w', encoding='utf-8') as f:
             json.dump(report, f, ensure_ascii=False, indent=2)
 
         # Print summary
-        print('\n' + '='*60)
-        print('SYNC VALIDATION REPORT')
-        print('='*60)
-        print(f'Status: {report["status"].upper()}')
-        print(f'Coverage: {report["coverage"]}%')
-        print(f'Missing constructs: {len(report["missing_constructs"])}')
-        print(f'Language mismatches: {len(report["language_mismatches"])}')
-        print(f'Missing language support: {len(report["missing_languages"])}')
+        sys.stdout.write('\n' + '='*60 + '\n')
+        sys.stdout.write('SYNC VALIDATION REPORT\n')
+        sys.stdout.write('='*60 + '\n')
+        sys.stdout.write(f'Status: {report["status"].upper()}\n')
+        sys.stdout.write(f'Coverage: {report["coverage"]}%\n')
+        sys.stdout.write(f'Missing constructs: {len(report["missing_constructs"])}\n')
+        sys.stdout.write(f'Language mismatches: {len(report["language_mismatches"])}\n')
+        sys.stdout.write(f'Missing language support: {len(report["missing_languages"])}\n')
 
         if report['missing_constructs']:
-            print(f'\nMissing constructs:')
+            sys.stdout.write(f'\nMissing constructs:\n')
             for c in report['missing_constructs'][:5]:
-                print(f'  - {c}')
+                sys.stdout.write(f'  - {c}\n')
             if len(report['missing_constructs']) > 5:
-                print(f'  ... and {len(report["missing_constructs"]) - 5} more')
+                sys.stdout.write(f'  ... and {len(report["missing_constructs"]) - 5} more\n')
 
         if report['language_mismatches']:
-            print(f'\nLanguage mismatches (first 5):')
+            sys.stdout.write(f'\nLanguage mismatches (first 5):\n')
             for m in report['language_mismatches'][:5]:
-                print(f'  - {m["construct"]} ({m["language"]}): {m["expected"]} != {m["actual"]}')
+                construct = m.get('construct', '?')
+                lang = m.get('language', '?')
+                sys.stdout.write(f'  - {construct} ({lang})\n')
             if len(report['language_mismatches']) > 5:
-                print(f'  ... and {len(report["language_mismatches"]) - 5} more')
+                sys.stdout.write(f'  ... and {len(report["language_mismatches"]) - 5} more\n')
 
-        print('='*60)
+        sys.stdout.write('='*60 + '\n')
+        sys.stdout.flush()
 
         # Exit code
         sys.exit(0 if all_good else 1)
 
     except Exception as e:
-        error_report = {
-            'status': 'error',
-            'coverage': 0,
-            'missing_constructs': [],
-            'extra_constructs': [],
-            'language_mismatches': [],
-            'missing_languages': [],
-            'details': {},
-            'error': str(e),
-        }
+        import traceback
+        sys.stderr.write(f'ERROR: {e}\n')
+        sys.stderr.flush()
+        traceback.print_exc(file=sys.stderr)
+
+        # Write error report
         try:
             with open(args.report, 'w', encoding='utf-8') as f:
-                json.dump(error_report, f, ensure_ascii=False, indent=2)
-        except Exception:
+                json.dump({
+                    'status': 'error',
+                    'error': str(e),
+                    'missing_constructs': [],
+                    'language_mismatches': [],
+                    'missing_languages': [],
+                    'coverage': 0,
+                }, f, ensure_ascii=False, indent=2)
+        except:
             pass
-        print(f'ERROR: {e}', file=sys.stderr)
+
         sys.exit(1)