rcdebug 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,181 @@
1
+ """
2
+ GitHub Open-Source Luau Experiment Harvester (zero-dependency stdlib).
3
+
4
+ Fetches public .luau/.lua files from GitHub repositories, extracts structural
5
+ Context + Sink + Guard idioms, and distills them into FlawBrain and learned_flaws.json.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import json
11
+ import os
12
+ import re
13
+ import ssl
14
+ from dataclasses import dataclass
15
+ from pathlib import Path
16
+ from typing import Any
17
+ from urllib.error import HTTPError, URLError
18
+ from urllib.parse import quote_plus
19
+ from urllib.request import Request, urlopen
20
+
21
+ from .learner import FlawBrain
22
+ from .models import Finding
23
+
24
+ GITHUB_SEARCH_REPOS_URL = "https://api.github.com/search/repositories"
25
+ USER_AGENT = "rcdebug-luau-harvester/1.0"
26
+
27
+ _REMOTE_RE = re.compile(r"(\w+)\.(?:OnServerEvent|OnServerInvoke)")
28
+ _DS_RE = re.compile(r":\s*(UpdateAsync|SetAsync|GetAsync)\s*\(")
29
+ _CLEANUP_RE = re.compile(r"\b(Trove|Janitor|Maid|Debris:AddItem)\b")
30
+ _GUARD_RE = re.compile(r"\b(typeof|os\.clock|pcall|math\.clamp)\b")
31
+
32
+
33
+ @dataclass(frozen=True, slots=True)
34
+ class HarvestResult:
35
+ repos_scanned: int
36
+ files_distilled: int
37
+ patterns_learned: int
38
+ offline_fallback: bool
39
+ message: str
40
+
41
+
42
+ def _ssl_context() -> ssl.SSLContext:
43
+ macos_ca = Path("/etc/ssl/cert.pem")
44
+ if macos_ca.exists():
45
+ return ssl.create_default_context(cafile=str(macos_ca))
46
+ return ssl.create_default_context()
47
+
48
+
49
+ def _github_get_json(url: str, timeout: float = 5.0) -> Any:
50
+ headers = {
51
+ "Accept": "application/vnd.github+json",
52
+ "User-Agent": USER_AGENT,
53
+ }
54
+ token = os.environ.get("GITHUB_TOKEN", "").strip()
55
+ if token:
56
+ headers["Authorization"] = f"Bearer {token}"
57
+
58
+ req = Request(url, headers=headers, method="GET")
59
+ with urlopen(req, timeout=timeout, context=_ssl_context()) as resp:
60
+ return json.loads(resp.read().decode("utf-8", errors="replace"))
61
+
62
+
63
+ def _github_get_text(url: str, timeout: float = 5.0) -> str:
64
+ req = Request(url, headers={"User-Agent": USER_AGENT}, method="GET")
65
+ with urlopen(req, timeout=timeout, context=_ssl_context()) as resp:
66
+ return resp.read().decode("utf-8", errors="replace")
67
+
68
+
69
+ def distill_luau_source(source: str, repo_name: str, file_path: str, brain: FlawBrain) -> int:
70
+ """
71
+ Extracts Context + Sink + Guard patterns from a Luau source file and
72
+ ingests them into `brain`. Returns count of distilled records.
73
+ """
74
+ distilled = 0
75
+ has_guard = bool(_GUARD_RE.search(source))
76
+ has_cleanup = bool(_CLEANUP_RE.search(source))
77
+
78
+ for m in _REMOTE_RE.finditer(source):
79
+ remote_name = m.group(1)
80
+ sev = "INFO" if has_guard else "CRITICAL"
81
+ brain.ingest_flaw_record(
82
+ domain="RemoteSecurity",
83
+ severity=sev,
84
+ text=f"{remote_name} OnServerEvent {repo_name} {file_path}",
85
+ fix=f"Validate typeof() and os.clock() cooldowns on {remote_name}.",
86
+ )
87
+ distilled += 1
88
+
89
+ for m in _DS_RE.finditer(source):
90
+ op = m.group(1)
91
+ sev = "INFO" if op == "UpdateAsync" else "CRITICAL"
92
+ brain.ingest_flaw_record(
93
+ domain="Platform",
94
+ severity=sev,
95
+ text=f"DataStore {op} {repo_name} {file_path}",
96
+ fix="Use DataStore:UpdateAsync() inside pcall() with session locking.",
97
+ )
98
+ distilled += 1
99
+
100
+ if has_cleanup:
101
+ brain.ingest_flaw_record(
102
+ domain="Performance",
103
+ severity="INFO",
104
+ text=f"Lifecycle cleanup Trove Janitor Debris {repo_name}",
105
+ fix="Bind RBXScriptConnections and transient instances to Trove/Janitor.",
106
+ )
107
+ distilled += 1
108
+
109
+ return distilled
110
+
111
+
112
+ def harvest_github_luau(
113
+ query: str = "roblox luau",
114
+ brain: FlawBrain | None = None,
115
+ max_repos: int = 3,
116
+ max_files_per_repo: int = 3,
117
+ ) -> HarvestResult:
118
+ """
119
+ Searches public GitHub repositories for Luau code, downloads sample .luau/.lua
120
+ files, and distills idioms into `FlawBrain`. Gracefully handles offline/rate-limit errors.
121
+ """
122
+ target_brain = brain or FlawBrain()
123
+ q = quote_plus(f"{query} language:Luau")
124
+ search_url = f"{GITHUB_SEARCH_REPOS_URL}?q={q}&sort=stars&order=desc&per_page={max_repos}"
125
+
126
+ try:
127
+ search_data = _github_get_json(search_url)
128
+ except (HTTPError, URLError, TimeoutError, OSError) as exc:
129
+ return HarvestResult(
130
+ repos_scanned=0,
131
+ files_distilled=0,
132
+ patterns_learned=0,
133
+ offline_fallback=True,
134
+ message=f"GitHub API unavailable ({exc}); using local 120k flaw corpus & FlawBrain.",
135
+ )
136
+
137
+ items = search_data.get("items", []) if isinstance(search_data, dict) else []
138
+ repos_scanned = 0
139
+ files_distilled = 0
140
+ patterns_learned = 0
141
+
142
+ for repo in items[:max_repos]:
143
+ full_name = repo.get("full_name")
144
+ default_branch = repo.get("default_branch", "main")
145
+ if not full_name:
146
+ continue
147
+ repos_scanned += 1
148
+ tree_url = f"https://api.github.com/repos/{full_name}/git/trees/{default_branch}?recursive=1"
149
+ try:
150
+ tree_data = _github_get_json(tree_url)
151
+ except Exception:
152
+ continue
153
+
154
+ tree = tree_data.get("tree", []) if isinstance(tree_data, dict) else []
155
+ luau_paths = [
156
+ node["path"]
157
+ for node in tree
158
+ if isinstance(node, dict)
159
+ and node.get("type") == "blob"
160
+ and str(node.get("path", "")).endswith((".luau", ".lua"))
161
+ ][:max_files_per_repo]
162
+
163
+ for fpath in luau_paths:
164
+ raw_url = f"https://raw.githubusercontent.com/{full_name}/{default_branch}/{fpath}"
165
+ try:
166
+ src = _github_get_text(raw_url)
167
+ except Exception:
168
+ continue
169
+ files_distilled += 1
170
+ patterns_learned += distill_luau_source(src, full_name, fpath, target_brain)
171
+
172
+ if patterns_learned > 0:
173
+ target_brain.save()
174
+
175
+ return HarvestResult(
176
+ repos_scanned=repos_scanned,
177
+ files_distilled=files_distilled,
178
+ patterns_learned=patterns_learned,
179
+ offline_fallback=False,
180
+ message=f"Harvested {files_distilled} Luau files across {repos_scanned} GitHub repo(s).",
181
+ )