continuum-toolkit 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.
Files changed (72) hide show
  1. cli/__init__.py +12 -0
  2. cli/main.py +415 -0
  3. confidence/__init__.py +13 -0
  4. confidence/calculator.py +308 -0
  5. confidence/models.py +40 -0
  6. context/__init__.py +17 -0
  7. context/models.py +108 -0
  8. context/pruner.py +228 -0
  9. context/selector.py +193 -0
  10. continuum_toolkit-1.0.0.dist-info/METADATA +511 -0
  11. continuum_toolkit-1.0.0.dist-info/RECORD +72 -0
  12. continuum_toolkit-1.0.0.dist-info/WHEEL +5 -0
  13. continuum_toolkit-1.0.0.dist-info/entry_points.txt +2 -0
  14. continuum_toolkit-1.0.0.dist-info/licenses/LICENSE +21 -0
  15. continuum_toolkit-1.0.0.dist-info/top_level.txt +13 -0
  16. contradictions/__init__.py +19 -0
  17. contradictions/detector.py +442 -0
  18. contradictions/models.py +75 -0
  19. core/__init__.py +97 -0
  20. core/enums.py +130 -0
  21. core/evidence.py +117 -0
  22. core/interfaces.py +209 -0
  23. core/schema.py +391 -0
  24. core/serializer.py +84 -0
  25. core/state_models.py +530 -0
  26. daemon/__init__.py +12 -0
  27. daemon/service.py +170 -0
  28. extractors/__init__.py +51 -0
  29. extractors/base.py +117 -0
  30. extractors/config/parsers.py +288 -0
  31. extractors/config/secret_sanitizer.py +91 -0
  32. extractors/config_extractor.py +172 -0
  33. extractors/conversation/analyzers.py +193 -0
  34. extractors/conversation/models.py +148 -0
  35. extractors/conversation_extractor.py +166 -0
  36. extractors/git_extractor.py +305 -0
  37. extractors/parsers/base.py +91 -0
  38. extractors/parsers/comment_parser.py +51 -0
  39. extractors/parsers/js_ts_parser.py +171 -0
  40. extractors/parsers/python_parser.py +180 -0
  41. extractors/verification/runners.py +278 -0
  42. extractors/verification_extractor.py +263 -0
  43. extractors/workspace_extractor.py +221 -0
  44. graph/__init__.py +24 -0
  45. graph/diff.py +109 -0
  46. graph/manager.py +473 -0
  47. graph/models.py +62 -0
  48. graph/propagator.py +194 -0
  49. graph/query.py +86 -0
  50. graph/snapshot.py +85 -0
  51. handoff/__init__.py +28 -0
  52. handoff/adapters/__init__.py +45 -0
  53. handoff/adapters/base.py +90 -0
  54. handoff/adapters/claude_adapter.py +176 -0
  55. handoff/adapters/codex_gpt_adapter.py +151 -0
  56. handoff/adapters/gemini_adapter.py +151 -0
  57. handoff/adapters/local_model_adapter.py +130 -0
  58. handoff/models.py +88 -0
  59. handoff/packager.py +288 -0
  60. pipeline/__init__.py +9 -0
  61. pipeline/orchestrator.py +260 -0
  62. resolution/__init__.py +15 -0
  63. resolution/resolver.py +311 -0
  64. storage/__init__.py +18 -0
  65. storage/hooks.py +125 -0
  66. storage/manager.py +127 -0
  67. storage/models.py +39 -0
  68. storage/recovery.py +98 -0
  69. watcher/__init__.py +17 -0
  70. watcher/detector.py +136 -0
  71. watcher/models.py +62 -0
  72. watcher/updater.py +163 -0
@@ -0,0 +1,166 @@
1
+ """
2
+ Project Continuum - Conversation & Agent State Evidence Extractor
3
+ =================================================================
4
+ Milestone 2 - Phase 5: Conversation & Agent State Ingestion.
5
+ Ingests conversational transcripts (JSON, markdown, or plain-text), extracts
6
+ requirements, unverified claims, architectural decisions, and tactical agent
7
+ state, generating Level 5 canonical evidence without contaminating ProjectState.
8
+ """
9
+
10
+ from pathlib import Path
11
+ from typing import Any, Dict, List, Optional, Tuple, Union
12
+
13
+ from core.enums import EvidenceType, EvidenceLevel, Status
14
+ from core.evidence import Evidence
15
+ from core.state_models import (
16
+ AgentExecutionState,
17
+ CanonicalProjectState,
18
+ ConversationalState,
19
+ )
20
+ from extractors.base import BaseEvidenceExtractor
21
+ from extractors.conversation.analyzers import TranscriptAnalysisResult, TranscriptAnalyzer
22
+ from extractors.conversation.models import ConversationTranscript, TurnRole
23
+
24
+
25
+ class ConversationEvidenceExtractor(BaseEvidenceExtractor):
26
+ """
27
+ Extractor responsible for Phase 5: Ingesting conversation transcripts
28
+ and recording conversational intent and agent execution states.
29
+ """
30
+
31
+ @property
32
+ def extractor_name(self) -> str:
33
+ return "ConversationEvidenceExtractor"
34
+
35
+ @property
36
+ def supported_evidence_types(self) -> List[EvidenceType]:
37
+ return [
38
+ EvidenceType.CONVERSATION_ASSERTION,
39
+ EvidenceType.USER_REQUIREMENT,
40
+ EvidenceType.AGENT_CLAIM,
41
+ ]
42
+
43
+ def can_extract(self, target_path_or_input: str) -> bool:
44
+ # Can extract from a file (.json, .txt, .md) or from raw text string
45
+ if isinstance(target_path_or_input, str):
46
+ if Path(target_path_or_input).exists():
47
+ return True
48
+ # Or raw conversational text
49
+ return "user:" in target_path_or_input.lower() or "assistant:" in target_path_or_input.lower() or "{" in target_path_or_input
50
+ return False
51
+
52
+ def load_transcript(self, source: Union[str, Path, Dict[str, Any]]) -> ConversationTranscript:
53
+ """Loads a transcript from a file, raw string, or dictionary."""
54
+ if isinstance(source, dict):
55
+ return ConversationTranscript.from_dict(source)
56
+
57
+ if isinstance(source, (str, Path)):
58
+ path = Path(source)
59
+ if path.exists() and path.is_file():
60
+ content = path.read_text(encoding="utf-8", errors="replace")
61
+ if path.suffix.lower() == ".json":
62
+ return ConversationTranscript.from_json(content)
63
+ else:
64
+ return ConversationTranscript.from_plain_text(content)
65
+ elif isinstance(source, str):
66
+ # Check if JSON string
67
+ if source.strip().startswith("{") or source.strip().startswith("["):
68
+ try:
69
+ return ConversationTranscript.from_json(source)
70
+ except Exception:
71
+ pass
72
+ return ConversationTranscript.from_plain_text(source)
73
+
74
+ return ConversationTranscript()
75
+
76
+ def extract(self, target_path_or_input: str, context: Optional[Dict[str, Any]] = None) -> List[Evidence]:
77
+ transcript = self.load_transcript(target_path_or_input)
78
+ analysis: TranscriptAnalysisResult = TranscriptAnalyzer.analyze(transcript)
79
+
80
+ evidence_list: List[Evidence] = []
81
+ source_label = str(target_path_or_input) if isinstance(target_path_or_input, (str, Path)) else "raw_transcript"
82
+
83
+ # 1. User Requirements Evidence
84
+ for req in analysis.requirements:
85
+ ev = self.create_evidence(
86
+ evidence_type=EvidenceType.USER_REQUIREMENT,
87
+ summary=f"User Requirement #{req.id}: {req.title}",
88
+ raw_payload={"requirement": req.to_dict(), "session_id": transcript.session_id},
89
+ source_uri=source_label,
90
+ locator=f"turn:{req.source_turn}"
91
+ )
92
+ req.evidence_id = ev.id
93
+ evidence_list.append(ev)
94
+
95
+ # 2. Agent Claims Evidence
96
+ for claim in analysis.agent_claims:
97
+ ev = self.create_evidence(
98
+ evidence_type=EvidenceType.AGENT_CLAIM,
99
+ summary=f"Agent Claim #{claim.id} by {claim.source_agent}: '{claim.claim_text}'",
100
+ raw_payload={"claim": claim.to_dict(), "session_id": transcript.session_id},
101
+ source_uri=source_label,
102
+ locator=f"turn:{claim.turn_id}"
103
+ )
104
+ claim.evidence_id = ev.id
105
+ evidence_list.append(ev)
106
+
107
+ # 3. Overall Conversational State Evidence
108
+ evidence_list.append(self.create_evidence(
109
+ evidence_type=EvidenceType.CONVERSATION_ASSERTION,
110
+ summary=(
111
+ f"Ingested transcript with {len(transcript.turns)} turns: "
112
+ f"{len(analysis.requirements)} requirements, {len(analysis.agent_claims)} agent claims, "
113
+ f"{len(analysis.decisions)} decisions, {len(analysis.unresolved_questions)} unresolved Qs"
114
+ ),
115
+ raw_payload={
116
+ "session_id": transcript.session_id,
117
+ "platform": transcript.platform,
118
+ "model_name": transcript.model_name,
119
+ "referenced_files": analysis.referenced_files,
120
+ "decisions": [d.to_dict() for d in analysis.decisions],
121
+ "assumptions": analysis.assumptions,
122
+ "unresolved_questions": [q.to_dict() for q in analysis.unresolved_questions]
123
+ },
124
+ source_uri=source_label,
125
+ locator="session:transcript"
126
+ ))
127
+
128
+ return evidence_list
129
+
130
+ def ingest_transcript(
131
+ self,
132
+ transcript_source: Union[str, Path, Dict[str, Any]],
133
+ canonical_state: CanonicalProjectState
134
+ ) -> Tuple[ConversationalState, AgentExecutionState]:
135
+ """
136
+ Populates CanonicalProjectState.conversational_state and agent_execution_state
137
+ while STRICTLY ensuring that ProjectState remains completely unchanged.
138
+ """
139
+ transcript = self.load_transcript(transcript_source)
140
+ analysis = TranscriptAnalyzer.analyze(transcript)
141
+ evidence_list = self.extract(transcript_source if isinstance(transcript_source, str) else str(transcript.session_id))
142
+
143
+ # Register evidence
144
+ for ev in evidence_list:
145
+ canonical_state.add_evidence(ev)
146
+
147
+ # Update ConversationalState
148
+ cs = canonical_state.conversational_state
149
+ cs.session_id = transcript.session_id
150
+ cs.user_requirements.extend(analysis.requirements)
151
+ cs.agent_claims.extend(analysis.agent_claims)
152
+ cs.architectural_decisions.extend(analysis.decisions)
153
+ cs.assumptions.extend(analysis.assumptions)
154
+ cs.unresolved_questions.extend(analysis.unresolved_questions)
155
+ cs.transcript_provenance.append(f"session:{transcript.session_id} ({len(transcript.turns)} turns)")
156
+
157
+ # Update AgentExecutionState
158
+ aes = canonical_state.agent_execution_state
159
+ aes.agent_id = transcript.model_name or "assistant_session"
160
+ aes.model_name = transcript.model_name or "unknown"
161
+ aes.active_tasks.extend(analysis.tactical_tasks)
162
+ aes.modified_files_in_flight.extend(analysis.referenced_files)
163
+ if analysis.next_action:
164
+ aes.next_action = analysis.next_action
165
+
166
+ return cs, aes
@@ -0,0 +1,305 @@
1
+ """
2
+ Project Continuum - Git History & Workspace Delta Evidence Extractor
3
+ ====================================================================
4
+ Milestone 2 - Phase 3: Git History & Delta Analysis.
5
+ Extracts branch, HEAD commit, staged/unstaged changes, untracked files,
6
+ commit logs, and file churn metrics. Gracefully handles non-git folders
7
+ and repositories with zero commits without failing.
8
+ """
9
+
10
+ from collections import defaultdict
11
+ from pathlib import Path
12
+ import subprocess
13
+ from typing import Any, Dict, List, Optional, Tuple
14
+
15
+ from core.enums import EvidenceType, EvidenceLevel
16
+ from core.evidence import Evidence
17
+ from core.state_models import (
18
+ CanonicalProjectState,
19
+ GitState,
20
+ ProjectState,
21
+ )
22
+ from extractors.base import BaseEvidenceExtractor
23
+
24
+
25
+ class GitEvidenceExtractor(BaseEvidenceExtractor):
26
+ """
27
+ Extractor responsible for harvesting verifiable Git state and history.
28
+ """
29
+
30
+ @property
31
+ def extractor_name(self) -> str:
32
+ return "GitEvidenceExtractor"
33
+
34
+ @property
35
+ def supported_evidence_types(self) -> List[EvidenceType]:
36
+ return [
37
+ EvidenceType.GIT_STATUS,
38
+ EvidenceType.GIT_DIFF,
39
+ EvidenceType.GIT_COMMIT,
40
+ ]
41
+
42
+ def can_extract(self, target_path_or_input: str) -> bool:
43
+ path = Path(target_path_or_input)
44
+ return path.exists() and path.is_dir()
45
+
46
+ def _run_git_command(self, repo_dir: Path, args: List[str]) -> Tuple[int, str, str]:
47
+ """Runs a git command safely and returns (exit_code, stdout, stderr)."""
48
+ try:
49
+ res = subprocess.run(
50
+ ["git"] + args,
51
+ cwd=str(repo_dir),
52
+ stdout=subprocess.PIPE,
53
+ stderr=subprocess.PIPE,
54
+ text=True,
55
+ encoding="utf-8",
56
+ errors="replace",
57
+ timeout=15
58
+ )
59
+ return res.returncode, res.stdout, res.stderr
60
+ except Exception as e:
61
+ return 1, "", str(e)
62
+
63
+ def is_git_repository(self, root_path: Path) -> bool:
64
+ """Checks if the given directory is within a valid git repository."""
65
+ code, out, _ = self._run_git_command(root_path, ["rev-parse", "--is-inside-work-tree"])
66
+ return code == 0 and out.strip() == "true"
67
+
68
+ def get_head_info(self, root_path: Path) -> Tuple[Optional[str], Optional[str]]:
69
+ """
70
+ Extracts (branch_name, head_commit_sha).
71
+ Handles unborn branches (repos with 0 commits).
72
+ """
73
+ # Get branch
74
+ code, branch_out, _ = self._run_git_command(root_path, ["branch", "--show-current"])
75
+ branch = branch_out.strip() if (code == 0 and branch_out.strip()) else None
76
+
77
+ if not branch:
78
+ # Fallback for older git or detached head
79
+ code, sym_out, _ = self._run_git_command(root_path, ["symbolic-ref", "--short", "HEAD"])
80
+ branch = sym_out.strip() if code == 0 and sym_out.strip() else "HEAD (detached)"
81
+
82
+ # Get HEAD commit
83
+ code, commit_out, _ = self._run_git_command(root_path, ["rev-parse", "HEAD"])
84
+ cleaned_commit = commit_out.strip()
85
+ head_commit = cleaned_commit if (code == 0 and len(cleaned_commit) == 40) else None
86
+
87
+ return branch, head_commit
88
+
89
+ def get_working_tree_status(self, root_path: Path) -> Dict[str, Any]:
90
+ """
91
+ Parses `git status --porcelain=v1` into staged, unstaged, untracked, and deleted files.
92
+ """
93
+ code, out, _ = self._run_git_command(root_path, ["status", "--porcelain=v1"])
94
+ if code != 0:
95
+ return {
96
+ "is_dirty": False,
97
+ "staged_files": [],
98
+ "unstaged_files": [],
99
+ "untracked_files": [],
100
+ "deleted_files": []
101
+ }
102
+
103
+ staged: List[str] = []
104
+ unstaged: List[str] = []
105
+ untracked: List[str] = []
106
+ deleted: List[str] = []
107
+
108
+ for raw_line in out.splitlines():
109
+ if not raw_line or len(raw_line) < 3:
110
+ continue
111
+
112
+ # In porcelain v1, the first 2 characters are status codes, followed by a space
113
+ status_code = raw_line[:2]
114
+ file_path = raw_line[3:].strip()
115
+ # If path was renamed, porcelain format is `orig -> dest`
116
+ if " -> " in file_path:
117
+ file_path = file_path.split(" -> ")[1].strip()
118
+
119
+ index_status = status_code[0]
120
+ worktree_status = status_code[1]
121
+
122
+ # Untracked
123
+ if status_code == "??" or index_status == "?":
124
+ untracked.append(file_path)
125
+ continue
126
+
127
+ # Staged changes (Index)
128
+ if index_status in {"A", "M", "R", "C"}:
129
+ staged.append(file_path)
130
+ elif index_status == "D":
131
+ staged.append(file_path)
132
+ deleted.append(file_path)
133
+
134
+ # Unstaged changes (Worktree)
135
+ if worktree_status in {"M", "T"}:
136
+ unstaged.append(file_path)
137
+ elif worktree_status == "D":
138
+ unstaged.append(file_path)
139
+ deleted.append(file_path)
140
+
141
+ is_dirty = bool(staged or unstaged or untracked or deleted)
142
+
143
+ return {
144
+ "is_dirty": is_dirty,
145
+ "staged_files": sorted(list(set(staged))),
146
+ "unstaged_files": sorted(list(set(unstaged))),
147
+ "untracked_files": sorted(list(set(untracked))),
148
+ "deleted_files": sorted(list(set(deleted)))
149
+ }
150
+
151
+ def get_recent_commits(self, root_path: Path, max_count: int = 15) -> List[Dict[str, Any]]:
152
+ """
153
+ Retrieves recent commit log with SHA, author, timestamp, and message.
154
+ """
155
+ format_str = "%H%x1f%an%x1f%ae%x1f%aI%x1f%s"
156
+ code, out, _ = self._run_git_command(
157
+ root_path,
158
+ ["log", f"-n{max_count}", f"--pretty=format:{format_str}"]
159
+ )
160
+ if code != 0 or not out:
161
+ return []
162
+
163
+ commits: List[Dict[str, Any]] = []
164
+ for line in out.splitlines():
165
+ parts = line.split("\x1f")
166
+ if len(parts) >= 5:
167
+ commits.append({
168
+ "commit_hash": parts[0],
169
+ "author_name": parts[1],
170
+ "author_email": parts[2],
171
+ "authored_at": parts[3],
172
+ "subject": parts[4]
173
+ })
174
+
175
+ return commits
176
+
177
+ def get_file_churn(self, root_path: Path, max_commits: int = 20) -> Dict[str, Dict[str, int]]:
178
+ """
179
+ Calculates file modification churn (insertions, deletions, modification count).
180
+ """
181
+ code, out, _ = self._run_git_command(
182
+ root_path,
183
+ ["log", f"-n{max_commits}", "--numstat", "--pretty=format:"]
184
+ )
185
+ if code != 0 or not out:
186
+ return {}
187
+
188
+ churn: Dict[str, Dict[str, int]] = defaultdict(lambda: {"insertions": 0, "deletions": 0, "commits": 0})
189
+
190
+ for line in out.splitlines():
191
+ parts = line.strip().split()
192
+ if len(parts) == 3:
193
+ added_str, deleted_str, file_path = parts
194
+ added = int(added_str) if added_str.isdigit() else 0
195
+ deleted = int(deleted_str) if deleted_str.isdigit() else 0
196
+ churn[file_path]["insertions"] += added
197
+ churn[file_path]["deletions"] += deleted
198
+ churn[file_path]["commits"] += 1
199
+
200
+ return dict(churn)
201
+
202
+ def extract(self, target_path_or_input: str, context: Optional[Dict[str, Any]] = None) -> List[Evidence]:
203
+ root_path = Path(target_path_or_input).resolve()
204
+ evidence_list: List[Evidence] = []
205
+
206
+ if not self.is_git_repository(root_path):
207
+ evidence_list.append(self.create_evidence(
208
+ evidence_type=EvidenceType.GIT_STATUS,
209
+ summary="Workspace is not a Git repository or Git is unavailable",
210
+ raw_payload={"is_repo": False},
211
+ source_uri=str(root_path),
212
+ locator="git:none"
213
+ ))
214
+ return evidence_list
215
+
216
+ branch, head_commit = self.get_head_info(root_path)
217
+ status_info = self.get_working_tree_status(root_path)
218
+ commits = self.get_recent_commits(root_path)
219
+ churn = self.get_file_churn(root_path)
220
+
221
+ # 1. Git Status Evidence
222
+ status_summary = (
223
+ f"Git repository on branch '{branch or 'unborn'}' (HEAD: {head_commit[:7] if head_commit else 'none'}). "
224
+ f"Working tree is {'DIRTY' if status_info['is_dirty'] else 'CLEAN'} "
225
+ f"({len(status_info['staged_files'])} staged, {len(status_info['unstaged_files'])} unstaged, {len(status_info['untracked_files'])} untracked)"
226
+ )
227
+ status_payload = {
228
+ "is_repo": True,
229
+ "branch": branch,
230
+ "head_commit": head_commit,
231
+ **status_info
232
+ }
233
+ evidence_list.append(self.create_evidence(
234
+ evidence_type=EvidenceType.GIT_STATUS,
235
+ summary=status_summary,
236
+ raw_payload=status_payload,
237
+ source_uri=str(root_path),
238
+ locator="git:status"
239
+ ))
240
+
241
+ # 2. Git Commit History Evidence
242
+ if commits:
243
+ evidence_list.append(self.create_evidence(
244
+ evidence_type=EvidenceType.GIT_COMMIT,
245
+ summary=f"Recent Git commit history: {len(commits)} commits recorded",
246
+ raw_payload={"commits": commits},
247
+ source_uri=str(root_path),
248
+ locator=f"git:commits:{head_commit[:7] if head_commit else 'all'}"
249
+ ))
250
+
251
+ # 3. Git Diff / Churn Evidence
252
+ if churn:
253
+ evidence_list.append(self.create_evidence(
254
+ evidence_type=EvidenceType.GIT_DIFF,
255
+ summary=f"Calculated file churn across recent commits for {len(churn)} files",
256
+ raw_payload={"churn": churn},
257
+ source_uri=str(root_path),
258
+ locator="git:churn"
259
+ ))
260
+
261
+ return evidence_list
262
+
263
+ def populate_project_state(self, root_dir: str, canonical_state: CanonicalProjectState) -> ProjectState:
264
+ """Populates ProjectState.git_state and registers git evidence."""
265
+ root_path = Path(root_dir).resolve()
266
+ evidence_list = self.extract(str(root_path))
267
+
268
+ is_repo = False
269
+ branch = None
270
+ head_commit = None
271
+ is_dirty = False
272
+ staged: List[str] = []
273
+ unstaged: List[str] = []
274
+ untracked: List[str] = []
275
+ commits: List[Dict[str, Any]] = []
276
+
277
+ for ev in evidence_list:
278
+ canonical_state.add_evidence(ev)
279
+ if ev.type == EvidenceType.GIT_STATUS:
280
+ is_repo = ev.raw_payload.get("is_repo", False)
281
+ branch = ev.raw_payload.get("branch")
282
+ head_commit = ev.raw_payload.get("head_commit")
283
+ is_dirty = ev.raw_payload.get("is_dirty", False)
284
+ staged = ev.raw_payload.get("staged_files", [])
285
+ unstaged = ev.raw_payload.get("unstaged_files", [])
286
+ untracked = ev.raw_payload.get("untracked_files", [])
287
+ elif ev.type == EvidenceType.GIT_COMMIT:
288
+ commits = ev.raw_payload.get("commits", [])
289
+
290
+ git_state = GitState(
291
+ is_repo=is_repo,
292
+ branch=branch,
293
+ head_commit=head_commit,
294
+ is_dirty=is_dirty,
295
+ staged_files=staged,
296
+ unstaged_files=unstaged,
297
+ untracked_files=untracked,
298
+ recent_commits=commits,
299
+ evidence_ids=[ev.id for ev in evidence_list]
300
+ )
301
+
302
+ ps = canonical_state.project_state
303
+ ps.git_state = git_state
304
+ ps.evidence_ids.extend([ev.id for ev in evidence_list])
305
+ return ps
@@ -0,0 +1,91 @@
1
+ """
2
+ Project Continuum - Parser Base and Common Types
3
+ =================================================
4
+ Defines the ILanguageParser contract and ParserResult structure.
5
+ """
6
+
7
+ from dataclasses import dataclass, field
8
+ from typing import Any, Dict, List, Optional, Protocol, runtime_checkable
9
+
10
+ from core.state_models import AstSymbol
11
+
12
+
13
+ @dataclass
14
+ class CommentMarker:
15
+ """Represents a TODO, FIXME, BUG, HACK, or NOTE found in source code."""
16
+ marker_type: str # TODO, FIXME, BUG, HACK, NOTE
17
+ text: str
18
+ line_number: int
19
+ file_path: str
20
+
21
+ def to_dict(self) -> Dict[str, Any]:
22
+ return {
23
+ "marker_type": self.marker_type,
24
+ "text": self.text,
25
+ "line_number": self.line_number,
26
+ "file_path": self.file_path
27
+ }
28
+
29
+
30
+ @dataclass
31
+ class ImportStatement:
32
+ """Represents an imported module, package, or symbol."""
33
+ module: str
34
+ imported_names: List[str] = field(default_factory=list)
35
+ alias: Optional[str] = None
36
+ line_number: int = 1
37
+ is_type_only: bool = False
38
+
39
+ def to_dict(self) -> Dict[str, Any]:
40
+ return {
41
+ "module": self.module,
42
+ "imported_names": self.imported_names,
43
+ "alias": self.alias,
44
+ "line_number": self.line_number,
45
+ "is_type_only": self.is_type_only
46
+ }
47
+
48
+
49
+ @dataclass
50
+ class ParseError:
51
+ """Non-fatal parse error recorded when analyzing malformed files."""
52
+ file_path: str
53
+ message: str
54
+ line_number: Optional[int] = None
55
+
56
+ def to_dict(self) -> Dict[str, Any]:
57
+ return {
58
+ "file_path": self.file_path,
59
+ "message": self.message,
60
+ "line_number": self.line_number
61
+ }
62
+
63
+
64
+ @dataclass
65
+ class ParserResult:
66
+ """Structured result returned by a language parser."""
67
+ file_path: str
68
+ language: str
69
+ symbols: List[AstSymbol] = field(default_factory=list)
70
+ imports: List[ImportStatement] = field(default_factory=list)
71
+ markers: List[CommentMarker] = field(default_factory=list)
72
+ errors: List[ParseError] = field(default_factory=list)
73
+ line_count: int = 0
74
+ exported_symbols: List[str] = field(default_factory=list)
75
+
76
+
77
+ @runtime_checkable
78
+ class ILanguageParser(Protocol):
79
+ """
80
+ Contract implemented by all language-specific source parsers.
81
+ """
82
+ @property
83
+ def language_name(self) -> str:
84
+ ...
85
+
86
+ @property
87
+ def supported_extensions(self) -> List[str]:
88
+ ...
89
+
90
+ def parse_source(self, file_path: str, content: str) -> ParserResult:
91
+ ...
@@ -0,0 +1,51 @@
1
+ """
2
+ Project Continuum - Universal Comment Marker Parser
3
+ ===================================================
4
+ Scans source files across various languages for TODO, FIXME, BUG, HACK markers.
5
+ """
6
+
7
+ import re
8
+ from typing import List
9
+ from extractors.parsers.base import CommentMarker
10
+
11
+
12
+ class CommentMarkerParser:
13
+ """
14
+ Detects inline TODO, FIXME, BUG, HACK, and OPTIMIZE markers
15
+ across different programming language comment formats (//, #, /*, --, etc.).
16
+ """
17
+
18
+ # Matches patterns like:
19
+ # // TODO: fix this
20
+ # # FIXME(user): handle null
21
+ # /* BUG: memory leak */
22
+ # -- TODO: sql migration
23
+ MARKER_PATTERN = re.compile(
24
+ r'(?:(?://|#|--|/\*|;)\s*)\b(TODO|FIXME|BUG|HACK|OPTIMIZE|NOTE|XXX)\b(?:\s*\((.*?)\))?\s*[:-]?\s*(.*?)(?:\*/)?$',
25
+ re.IGNORECASE
26
+ )
27
+
28
+ @classmethod
29
+ def extract_markers(cls, file_path: str, content: str) -> List[CommentMarker]:
30
+ markers: List[CommentMarker] = []
31
+ lines = content.splitlines()
32
+
33
+ for idx, line in enumerate(lines, start=1):
34
+ match = cls.MARKER_PATTERN.search(line)
35
+ if match:
36
+ marker_type = match.group(1).upper()
37
+ author_scope = match.group(2)
38
+ desc = match.group(3).strip()
39
+
40
+ full_text = f"({author_scope}) {desc}" if author_scope else desc
41
+ if not full_text:
42
+ full_text = line.strip()
43
+
44
+ markers.append(CommentMarker(
45
+ marker_type=marker_type,
46
+ text=full_text,
47
+ line_number=idx,
48
+ file_path=file_path
49
+ ))
50
+
51
+ return markers