grind-t-tech-debt 0.1.0__tar.gz

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 (26) hide show
  1. grind_t_tech_debt-0.1.0/PKG-INFO +11 -0
  2. grind_t_tech_debt-0.1.0/pyproject.toml +118 -0
  3. grind_t_tech_debt-0.1.0/pyproject.toml.orig +86 -0
  4. grind_t_tech_debt-0.1.0/src/tech_debt/__init__.py +3 -0
  5. grind_t_tech_debt-0.1.0/src/tech_debt/_entities/__init__.py +0 -0
  6. grind_t_tech_debt-0.1.0/src/tech_debt/_entities/agent_settings.py +9 -0
  7. grind_t_tech_debt-0.1.0/src/tech_debt/_entities/codex_model.py +16 -0
  8. grind_t_tech_debt-0.1.0/src/tech_debt/_entities/defect.py +208 -0
  9. grind_t_tech_debt-0.1.0/src/tech_debt/_entities/path_distribution.py +14 -0
  10. grind_t_tech_debt-0.1.0/src/tech_debt/_entities/search_tech_debt_prompt.py +16 -0
  11. grind_t_tech_debt-0.1.0/src/tech_debt/_stateful_computations/__init__.py +0 -0
  12. grind_t_tech_debt-0.1.0/src/tech_debt/_stateful_effects/__init__.py +0 -0
  13. grind_t_tech_debt-0.1.0/src/tech_debt/_stateful_effects/codex_session.py +121 -0
  14. grind_t_tech_debt-0.1.0/src/tech_debt/_stateful_workflows/__init__.py +0 -0
  15. grind_t_tech_debt-0.1.0/src/tech_debt/_stateless_computations/__init__.py +0 -0
  16. grind_t_tech_debt-0.1.0/src/tech_debt/_stateless_computations/format_search_error.py +22 -0
  17. grind_t_tech_debt-0.1.0/src/tech_debt/_stateless_computations/validate_path_distribution.py +47 -0
  18. grind_t_tech_debt-0.1.0/src/tech_debt/_stateless_effects/__init__.py +0 -0
  19. grind_t_tech_debt-0.1.0/src/tech_debt/_stateless_effects/list_codex_models.py +74 -0
  20. grind_t_tech_debt-0.1.0/src/tech_debt/_stateless_effects/list_search_files.py +24 -0
  21. grind_t_tech_debt-0.1.0/src/tech_debt/_stateless_effects/normalize_search_paths.py +13 -0
  22. grind_t_tech_debt-0.1.0/src/tech_debt/_stateless_effects/read_agent_settings.py +11 -0
  23. grind_t_tech_debt-0.1.0/src/tech_debt/_stateless_workflows/__init__.py +0 -0
  24. grind_t_tech_debt-0.1.0/src/tech_debt/_stateless_workflows/search_tech_debt.py +109 -0
  25. grind_t_tech_debt-0.1.0/src/tech_debt/main.py +195 -0
  26. grind_t_tech_debt-0.1.0/src/tech_debt/py.typed +0 -0
@@ -0,0 +1,11 @@
1
+ Metadata-Version: 2.4
2
+ Name: grind-t-tech-debt
3
+ Version: 0.1.0
4
+ Summary: Tool for managing technical debt.
5
+ Author: grind-t
6
+ Author-email: grind-t <grindt.gd@gmail.com>
7
+ License-Expression: ISC
8
+ Requires-Dist: pydantic>=2.14.4
9
+ Requires-Python: >=3.14
10
+ Project-URL: Homepage, https://github.com/grind-t/tech-debt
11
+ Project-URL: Issues, https://github.com/grind-t/tech-debt/issues
@@ -0,0 +1,118 @@
1
+ [project]
2
+ name = "grind-t-tech-debt"
3
+ version = "0.1.0"
4
+ description = "Tool for managing technical debt."
5
+ license = "ISC"
6
+ requires-python = ">=3.14"
7
+ dependencies = ["pydantic>=2.14.4"]
8
+
9
+ [[project.authors]]
10
+ name = "grind-t"
11
+ email = "grindt.gd@gmail.com"
12
+
13
+ [project.scripts]
14
+ tech-debt = "tech_debt:main"
15
+
16
+ [project.urls]
17
+ Homepage = "https://github.com/grind-t/tech-debt"
18
+ Issues = "https://github.com/grind-t/tech-debt/issues"
19
+
20
+ [build-system]
21
+ requires = ["uv_build>=0.12.9,<0.13.0"]
22
+ build-backend = "uv_build"
23
+
24
+ [tool.uv.build-backend]
25
+ module-name = "tech_debt"
26
+
27
+ [tool.ruff.lint]
28
+ select = [
29
+ "E",
30
+ "F",
31
+ "I",
32
+ "UP",
33
+ "B",
34
+ "SIM",
35
+ "RUF",
36
+ "PT",
37
+ "N",
38
+ "C4",
39
+ "PIE",
40
+ "PERF",
41
+ "FURB",
42
+ "PTH",
43
+ "T20",
44
+ "ANN",
45
+ "ASYNC",
46
+ "DTZ",
47
+ "TID",
48
+ ]
49
+ ignore = ["RUF001"]
50
+
51
+ [tool.ruff.lint.flake8-tidy-imports]
52
+ ban-relative-imports = "all"
53
+
54
+ [tool.ruff.lint.flake8-tidy-imports.banned-api."pytest.mark.parametrize"]
55
+ msg = "Use the `subtests` fixture with named cases instead."
56
+
57
+ [tool.ruff.lint.per-file-ignores]
58
+ "tests/**" = ["ANN"]
59
+ "benchmarks/**" = [
60
+ "ANN",
61
+ "TID251",
62
+ ]
63
+
64
+ [tool.pytest.ini_options]
65
+ testpaths = ["tests"]
66
+ addopts = [
67
+ "--import-mode=importlib",
68
+ "--strict-markers",
69
+ "--strict-config",
70
+ "-ra",
71
+ "-q",
72
+ ]
73
+ xfail_strict = true
74
+ filterwarnings = ["error"]
75
+
76
+ [tool.poe.tasks]
77
+ fmt = "ruff format"
78
+ typecheck = "ty check"
79
+ test = "pytest"
80
+ build = "uv build"
81
+ check = [
82
+ "lint",
83
+ "typecheck",
84
+ "test",
85
+ ]
86
+
87
+ [[tool.poe.tasks.lint]]
88
+ cmd = "ruff check"
89
+
90
+ [[tool.poe.tasks.lint]]
91
+ cmd = "lint-imports --no-logo"
92
+
93
+ [[tool.poe.tasks.lint]]
94
+ cmd = "lint-rules src"
95
+
96
+ [tool.importlinter]
97
+ root_package = "tech_debt"
98
+ include_external_packages = true
99
+
100
+ [[tool.importlinter.contracts]]
101
+ name = "Effects -> workflows -> computations -> entities"
102
+ type = "layers"
103
+ layers = [
104
+ "tech_debt._stateless_effects : tech_debt._stateful_effects",
105
+ "tech_debt._stateless_workflows : tech_debt._stateful_workflows",
106
+ "tech_debt._stateless_computations : tech_debt._stateful_computations",
107
+ "tech_debt._entities",
108
+ ]
109
+
110
+ [dependency-groups]
111
+ dev = [
112
+ "grind-t-lint-rules>=0.4.0",
113
+ "import-linter",
114
+ "poethepoet",
115
+ "pytest",
116
+ "ruff",
117
+ "ty",
118
+ ]
@@ -0,0 +1,86 @@
1
+ [project]
2
+ name = "grind-t-tech-debt"
3
+ version = "0.1.0"
4
+ description = "Tool for managing technical debt."
5
+ license = "ISC"
6
+ authors = [
7
+ { name = "grind-t", email = "grindt.gd@gmail.com" }
8
+ ]
9
+ requires-python = ">=3.14"
10
+ dependencies = [
11
+ "pydantic>=2.14.4",
12
+ ]
13
+
14
+ [project.scripts]
15
+ tech-debt = "tech_debt:main"
16
+
17
+ [project.urls]
18
+ Homepage = "https://github.com/grind-t/tech-debt"
19
+ Issues = "https://github.com/grind-t/tech-debt/issues"
20
+
21
+ [build-system]
22
+ requires = ["uv_build>=0.12.9,<0.13.0"]
23
+ build-backend = "uv_build"
24
+
25
+ [tool.uv.build-backend]
26
+ module-name = "tech_debt"
27
+
28
+ [tool.ruff.lint]
29
+ select = [
30
+ "E", "F", "I", "UP", "B", "SIM", "RUF", "PT", "N",
31
+ "C4", "PIE", "PERF", "FURB", "PTH", "T20", "ANN", "ASYNC", "DTZ", "TID",
32
+ ]
33
+ ignore = ["RUF001"] # allow Cyrillic in strings
34
+
35
+ [tool.ruff.lint.flake8-tidy-imports]
36
+ ban-relative-imports = "all"
37
+
38
+ [tool.ruff.lint.flake8-tidy-imports.banned-api]
39
+ "pytest.mark.parametrize".msg = "Use the `subtests` fixture with named cases instead."
40
+
41
+ [tool.ruff.lint.per-file-ignores]
42
+ "tests/**" = ["ANN"]
43
+ "benchmarks/**" = ["ANN", "TID251"] # benchmarks need parametrize: subtests are not timed separately
44
+
45
+ [tool.pytest.ini_options]
46
+ testpaths = ["tests"]
47
+ addopts = ["--import-mode=importlib", "--strict-markers", "--strict-config", "-ra", "-q"]
48
+ xfail_strict = true
49
+ filterwarnings = ["error"]
50
+
51
+ [tool.poe.tasks]
52
+ fmt = "ruff format"
53
+ lint = [
54
+ { cmd = "ruff check" },
55
+ { cmd = "lint-imports --no-logo" },
56
+ { cmd = "lint-rules src" },
57
+ ]
58
+ typecheck = "ty check"
59
+ test = "pytest"
60
+ build = "uv build"
61
+ check = ["lint", "typecheck", "test"]
62
+
63
+ [dependency-groups]
64
+ dev = [
65
+ "grind-t-lint-rules>=0.4.0",
66
+ "import-linter",
67
+ "poethepoet",
68
+ "pytest",
69
+ "ruff",
70
+ "ty",
71
+ ]
72
+
73
+ # ---------- Architecture rules enforced by lint-imports ----------
74
+ [tool.importlinter]
75
+ root_package = "tech_debt"
76
+ include_external_packages = true
77
+
78
+ [[tool.importlinter.contracts]]
79
+ name = "Effects -> workflows -> computations -> entities"
80
+ type = "layers"
81
+ layers = [
82
+ "tech_debt._stateless_effects : tech_debt._stateful_effects",
83
+ "tech_debt._stateless_workflows : tech_debt._stateful_workflows",
84
+ "tech_debt._stateless_computations : tech_debt._stateful_computations",
85
+ "tech_debt._entities",
86
+ ]
@@ -0,0 +1,3 @@
1
+ from tech_debt.main import main
2
+
3
+ __all__ = ["main"]
@@ -0,0 +1,9 @@
1
+ from typing import Literal
2
+
3
+ from pydantic import BaseModel, Field
4
+
5
+
6
+ class AgentSettings(BaseModel):
7
+ provider: Literal["codex"] = "codex"
8
+ model: str = Field(min_length=1)
9
+ reasoning_effort: str = Field(min_length=1)
@@ -0,0 +1,16 @@
1
+ from pydantic import BaseModel, Field
2
+
3
+
4
+ class _ReasoningEffort(BaseModel):
5
+ reasoning_effort: str = Field(alias="reasoningEffort")
6
+ description: str
7
+
8
+
9
+ class CodexModel(BaseModel):
10
+ model: str
11
+ display_name: str = Field(alias="displayName")
12
+ is_default: bool = Field(default=False, alias="isDefault")
13
+ default_reasoning_effort: str = Field(alias="defaultReasoningEffort")
14
+ supported_reasoning_efforts: list[_ReasoningEffort] = Field(
15
+ alias="supportedReasoningEfforts"
16
+ )
@@ -0,0 +1,208 @@
1
+ from typing import Literal, Self, get_args
2
+
3
+ from pydantic import BaseModel, ConfigDict, Field, JsonValue, model_validator
4
+
5
+ _FunctionalSuitability = Literal[
6
+ "Functional completeness",
7
+ "Functional correctness",
8
+ "Functional appropriateness",
9
+ ]
10
+
11
+ _PerformanceEfficiency = Literal[
12
+ "Time behaviour",
13
+ "Resource utilization",
14
+ "Capacity",
15
+ ]
16
+
17
+ _Compatibility = Literal[
18
+ "Co-existence",
19
+ "Interoperability",
20
+ ]
21
+
22
+ _InteractionCapability = Literal[
23
+ "Appropriateness recognizability",
24
+ "Learnability",
25
+ "Operability",
26
+ "User error protection",
27
+ "User engagement",
28
+ "Inclusivity",
29
+ "User assistance",
30
+ "Self-descriptiveness",
31
+ ]
32
+
33
+ _Reliability = Literal[
34
+ "Faultlessness",
35
+ "Availability",
36
+ "Fault tolerance",
37
+ "Recoverability",
38
+ ]
39
+
40
+ _Security = Literal[
41
+ "Confidentiality",
42
+ "Integrity",
43
+ "Non-repudiation",
44
+ "Accountability",
45
+ "Authenticity",
46
+ "Resistance",
47
+ ]
48
+
49
+ _Maintainability = Literal[
50
+ "Modularity",
51
+ "Reusability",
52
+ "Analysability",
53
+ "Modifiability",
54
+ "Testability",
55
+ ]
56
+
57
+ _Flexibility = Literal[
58
+ "Adaptability",
59
+ "Scalability",
60
+ "Installability",
61
+ "Replaceability",
62
+ ]
63
+
64
+ _Safety = Literal[
65
+ "Operational constraint",
66
+ "Risk identification",
67
+ "Fail safe",
68
+ "Hazard warning",
69
+ "Safe integration",
70
+ ]
71
+
72
+ _Characteristic = Literal[
73
+ "Functional suitability",
74
+ "Performance efficiency",
75
+ "Compatibility",
76
+ "Interaction capability",
77
+ "Reliability",
78
+ "Security",
79
+ "Maintainability",
80
+ "Flexibility",
81
+ "Safety",
82
+ ]
83
+
84
+ _Subcharacteristic = (
85
+ _FunctionalSuitability
86
+ | _PerformanceEfficiency
87
+ | _Compatibility
88
+ | _InteractionCapability
89
+ | _Reliability
90
+ | _Security
91
+ | _Maintainability
92
+ | _Flexibility
93
+ | _Safety
94
+ )
95
+
96
+ _SUBCHARACTERISTICS = {
97
+ "Functional suitability": get_args(_FunctionalSuitability),
98
+ "Performance efficiency": get_args(_PerformanceEfficiency),
99
+ "Compatibility": get_args(_Compatibility),
100
+ "Interaction capability": get_args(_InteractionCapability),
101
+ "Reliability": get_args(_Reliability),
102
+ "Security": get_args(_Security),
103
+ "Maintainability": get_args(_Maintainability),
104
+ "Flexibility": get_args(_Flexibility),
105
+ "Safety": get_args(_Safety),
106
+ }
107
+
108
+ _MOST_LIKELY_RISK_EXAMPLE: dict[str, JsonValue] = {
109
+ "event": "A maintainer changes how totals are computed",
110
+ "consequence": (
111
+ "Each change takes three edits and three reviews, "
112
+ "so changes to totals ship slower"
113
+ ),
114
+ "likelihood": "High",
115
+ "severity": "Minor",
116
+ }
117
+ _WORST_CREDIBLE_RISK_EXAMPLE: dict[str, JsonValue] = {
118
+ "event": (
119
+ "A maintainer changes totals and misses one of the three copies, "
120
+ "and no test compares totals across them"
121
+ ),
122
+ "consequence": (
123
+ "Customers are invoiced amounts that differ from their orders, "
124
+ "and invoices have to be corrected and reissued"
125
+ ),
126
+ "likelihood": "Medium",
127
+ "severity": "Critical",
128
+ }
129
+
130
+
131
+ class _Risk(BaseModel):
132
+ model_config = ConfigDict(extra="forbid")
133
+
134
+ event: str = Field(
135
+ description=(
136
+ "A real event that could occur and would not be detected by "
137
+ "existing tests, checks, or monitoring."
138
+ ),
139
+ )
140
+ consequence: str = Field(
141
+ description=(
142
+ "Impact on users, business, or the speed and reliability "
143
+ "of agents and people working with the system."
144
+ ),
145
+ )
146
+ likelihood: Literal["High", "Medium", "Low"]
147
+ severity: Literal["Blocking", "Critical", "Major", "Minor", "Inconsequential"]
148
+
149
+
150
+ class _DefectRisks(BaseModel):
151
+ """Most likely risk and worst credible risk; use null when they coincide."""
152
+
153
+ model_config = ConfigDict(
154
+ extra="forbid",
155
+ json_schema_extra={
156
+ "examples": [
157
+ {
158
+ "most_likely": _MOST_LIKELY_RISK_EXAMPLE,
159
+ "worst_credible": _WORST_CREDIBLE_RISK_EXAMPLE,
160
+ }
161
+ ]
162
+ },
163
+ )
164
+
165
+ most_likely: _Risk
166
+ worst_credible: _Risk | None = Field(
167
+ description="Worst credible consequence, if different from the most likely.",
168
+ )
169
+
170
+
171
+ class Defect(BaseModel):
172
+ model_config = ConfigDict(extra="forbid")
173
+
174
+ description: str = Field(
175
+ description="Brief description of the problem.",
176
+ examples=["Order totals are computed in three places"],
177
+ )
178
+ location: str = Field(
179
+ description="Location of the defect in the project.",
180
+ examples=["src/orders/totals.py, src/billing/invoice.py, src/reports/sales.py"],
181
+ )
182
+ type: str = Field(
183
+ description=(
184
+ "Name of the established problem family this defect belongs to, "
185
+ "from a standard, book, or commonly accepted practice. "
186
+ "Include the source or version where needed."
187
+ ),
188
+ examples=["Duplicated Code (Fowler, Refactoring, 2nd ed.)"],
189
+ )
190
+ characteristic: _Characteristic = Field(
191
+ description="ISO/IEC 25010:2023 quality characteristic degraded by the defect.",
192
+ examples=["Maintainability"],
193
+ )
194
+ subcharacteristic: _Subcharacteristic = Field(
195
+ description="Degraded subcharacteristic of the chosen quality characteristic.",
196
+ examples=["Modifiability"],
197
+ )
198
+ risks: _DefectRisks
199
+
200
+ @model_validator(mode="after")
201
+ def _validate_subcharacteristic(self) -> Self:
202
+ allowed = _SUBCHARACTERISTICS[self.characteristic]
203
+ if self.subcharacteristic not in allowed:
204
+ raise ValueError(
205
+ f"{self.subcharacteristic!r} does not belong to "
206
+ f"{self.characteristic!r}. Expected one of: {', '.join(allowed)}"
207
+ )
208
+ return self
@@ -0,0 +1,14 @@
1
+ from pathlib import PurePath
2
+ from typing import Annotated
3
+
4
+ from pydantic import Field, WithJsonSchema
5
+
6
+ type PathDistribution = Annotated[
7
+ list[list[Annotated[PurePath, WithJsonSchema({"type": "string"})]]],
8
+ Field(
9
+ description=(
10
+ "Balanced, non-overlapping search scopes covering the specified paths."
11
+ ),
12
+ examples=[[["src/orders"], ["src/billing", "src/reports"]]],
13
+ ),
14
+ ]
@@ -0,0 +1,16 @@
1
+ DISTRIBUTE_PATHS_PROMPT = (
2
+ "Divide these project paths into {parallelism} balanced, non-overlapping "
3
+ "search scopes covering all specified paths: {paths}"
4
+ )
5
+ CORRECT_PATH_DISTRIBUTION_PROMPT = (
6
+ "Correct the path distribution to resolve these validation errors: {errors}"
7
+ )
8
+ SEARCH_TECH_DEBT_PROMPT = "Search technical debt within these project paths: {paths}"
9
+ FORMAT_FINDINGS_PROMPT = "Format the findings according to the provided schema"
10
+ RECHECK_FINDINGS_PROMPT = (
11
+ "Recheck all findings and remove false positives "
12
+ "and any findings you are uncertain about"
13
+ )
14
+ DEDUPLICATE_FINDINGS_PROMPT = (
15
+ "Find and remove semantically duplicate defects: {findings}"
16
+ )
@@ -0,0 +1,121 @@
1
+ import asyncio
2
+ import json
3
+ import subprocess
4
+ from contextlib import suppress
5
+ from pathlib import Path
6
+ from tempfile import TemporaryDirectory
7
+ from typing import overload
8
+
9
+ from pydantic import TypeAdapter
10
+
11
+ from tech_debt._entities.agent_settings import AgentSettings
12
+ from tech_debt._stateless_workflows.search_tech_debt import AgentSession
13
+
14
+
15
+ class CodexSession(AgentSession):
16
+ """Run consecutive prompts in one Codex session."""
17
+
18
+ def __init__(self, settings: AgentSettings) -> None:
19
+ self._settings = settings
20
+ self._session_id: str | None = None
21
+ self._lock = asyncio.Lock()
22
+
23
+ @overload
24
+ async def next_turn[Response](
25
+ self, prompt: str, schema: TypeAdapter[Response]
26
+ ) -> Response: ...
27
+
28
+ @overload
29
+ async def next_turn(self, prompt: str, schema: None = None) -> str: ...
30
+
31
+ async def next_turn[Response](
32
+ self, prompt: str, schema: TypeAdapter[Response] | None = None
33
+ ) -> Response | str:
34
+ """Start the session or continue it, optionally validating the response."""
35
+ async with self._lock:
36
+ with TemporaryDirectory(prefix="tech-debt-codex-") as directory:
37
+ response_path = Path(directory) / "response.json"
38
+ command = ["codex", "exec", "--sandbox", "read-only"]
39
+ if self._session_id is not None:
40
+ command.append("resume")
41
+ command.extend(
42
+ [
43
+ "--model",
44
+ self._settings.model,
45
+ "--config",
46
+ "model_reasoning_effort="
47
+ + json.dumps(self._settings.reasoning_effort),
48
+ ]
49
+ )
50
+ command.append("--json")
51
+ wrapped = False
52
+ if schema is not None:
53
+ output_schema = schema.json_schema()
54
+ wrapped = output_schema.get("type") != "object"
55
+ if wrapped:
56
+ definitions = output_schema.pop("$defs", {})
57
+ output_schema = {
58
+ "type": "object",
59
+ "properties": {"result": output_schema},
60
+ "required": ["result"],
61
+ "additionalProperties": False,
62
+ "$defs": definitions,
63
+ }
64
+ schema_path = Path(directory) / "schema.json"
65
+ await asyncio.to_thread(
66
+ schema_path.write_text,
67
+ json.dumps(output_schema),
68
+ encoding="utf-8",
69
+ )
70
+ command.extend(["--output-schema", str(schema_path)])
71
+ command.extend(["--output-last-message", str(response_path)])
72
+ if self._session_id is not None:
73
+ command.append(self._session_id)
74
+ command.append("-")
75
+
76
+ process = await asyncio.create_subprocess_exec(
77
+ *command,
78
+ stdin=asyncio.subprocess.PIPE,
79
+ stdout=asyncio.subprocess.PIPE,
80
+ stderr=asyncio.subprocess.PIPE,
81
+ )
82
+ communication = asyncio.create_task(
83
+ process.communicate(prompt.encode("utf-8"))
84
+ )
85
+ try:
86
+ stdout, stderr = await asyncio.shield(communication)
87
+ except asyncio.CancelledError:
88
+ if process.returncode is None:
89
+ with suppress(ProcessLookupError):
90
+ process.kill()
91
+ await communication
92
+ raise
93
+
94
+ returncode = await process.wait()
95
+ if returncode != 0:
96
+ raise subprocess.CalledProcessError(
97
+ returncode,
98
+ command,
99
+ stderr=stderr.decode("utf-8", errors="replace"),
100
+ )
101
+
102
+ for line in stdout.decode("utf-8").splitlines():
103
+ if not line.strip():
104
+ continue
105
+ event = json.loads(line)
106
+ if event.get("type") == "thread.started":
107
+ thread_id = event.get("thread_id")
108
+ if not isinstance(thread_id, str) or not thread_id:
109
+ raise RuntimeError("Codex returned an invalid session ID")
110
+ self._session_id = thread_id
111
+ if self._session_id is None:
112
+ raise RuntimeError("Codex did not return a session ID")
113
+
114
+ response = await asyncio.to_thread(
115
+ response_path.read_text, encoding="utf-8"
116
+ )
117
+ if schema is None:
118
+ return response
119
+ if wrapped:
120
+ response = json.dumps(json.loads(response)["result"])
121
+ return schema.validate_json(response)
@@ -0,0 +1,22 @@
1
+ from typing import Protocol, runtime_checkable
2
+
3
+
4
+ @runtime_checkable
5
+ class _ProcessFailure(Protocol):
6
+ returncode: int
7
+ stderr: str | bytes | None
8
+
9
+
10
+ def format_search_error(error: BaseException) -> str:
11
+ """Describe search failures, preserving Codex stderr and grouped causes."""
12
+ if isinstance(error, BaseExceptionGroup):
13
+ return "\n\n".join(format_search_error(cause) for cause in error.exceptions)
14
+ if isinstance(error, _ProcessFailure):
15
+ message = f"Codex exited with code {error.returncode}."
16
+ detail = error.stderr
17
+ if isinstance(detail, bytes):
18
+ detail = detail.decode("utf-8", errors="replace")
19
+ if detail and detail.strip():
20
+ return f"{message}\n{detail.strip()}"
21
+ return message
22
+ return str(error).strip() or type(error).__name__
@@ -0,0 +1,47 @@
1
+ from collections.abc import Collection, Sequence
2
+ from pathlib import PurePath
3
+
4
+
5
+ def validate_path_distribution(
6
+ paths: Sequence[PurePath],
7
+ distribution: Sequence[Sequence[PurePath]],
8
+ parallelism: int,
9
+ files: Collection[PurePath],
10
+ ) -> None:
11
+ """Validate canonical scopes against source roots and their file inventory."""
12
+ errors: list[str] = []
13
+ if len(distribution) != parallelism:
14
+ errors.append("Path distribution must contain exactly parallelism scopes")
15
+ for index, scope in enumerate(distribution):
16
+ if not scope:
17
+ errors.append(f"Search scope {index + 1} is empty")
18
+ errors.extend(
19
+ f"Search path is outside the original search area: {path}"
20
+ for path in scope
21
+ if not any(path.is_relative_to(root) for root in paths)
22
+ )
23
+
24
+ for index, scope in enumerate(distribution):
25
+ for other in distribution[index + 1 :]:
26
+ for path in scope:
27
+ errors.extend(
28
+ f"Search scopes overlap: {path} and {other_path}"
29
+ for other_path in other
30
+ if path.is_relative_to(other_path)
31
+ or other_path.is_relative_to(path)
32
+ )
33
+
34
+ missing = sorted(
35
+ str(file)
36
+ for file in files
37
+ if not any(
38
+ file.is_relative_to(path) for scope in distribution for path in scope
39
+ )
40
+ )
41
+ if missing:
42
+ errors.append(
43
+ f"Distribution omits {len(missing)} files, "
44
+ f"including: {', '.join(missing[:10])}"
45
+ )
46
+ if errors:
47
+ raise ValueError("\n".join(errors))
@@ -0,0 +1,74 @@
1
+ import asyncio
2
+ import json
3
+ from contextlib import suppress
4
+
5
+ from pydantic import TypeAdapter
6
+
7
+ from tech_debt._entities.codex_model import CodexModel
8
+
9
+
10
+ async def list_codex_models() -> list[CodexModel]:
11
+ """Read the model catalog and supported efforts from Codex app-server."""
12
+ process = await asyncio.create_subprocess_exec(
13
+ "codex",
14
+ "app-server",
15
+ stdin=asyncio.subprocess.PIPE,
16
+ stdout=asyncio.subprocess.PIPE,
17
+ stderr=asyncio.subprocess.DEVNULL,
18
+ limit=1024 * 1024,
19
+ )
20
+ assert process.stdin is not None
21
+ assert process.stdout is not None
22
+ writer = process.stdin
23
+ reader = process.stdout
24
+
25
+ async def request(
26
+ request_id: int, method: str, params: dict[str, object]
27
+ ) -> dict[str, object]:
28
+ writer.write(
29
+ (
30
+ json.dumps({"id": request_id, "method": method, "params": params})
31
+ + "\n"
32
+ ).encode("utf-8")
33
+ )
34
+ await writer.drain()
35
+ while line := await reader.readline():
36
+ message = json.loads(line)
37
+ if message.get("id") != request_id:
38
+ continue
39
+ if "error" in message:
40
+ raise RuntimeError(f"Codex {method} failed")
41
+ return message["result"]
42
+ raise RuntimeError("Codex app-server closed before returning a response")
43
+
44
+ async def fetch() -> list[CodexModel]:
45
+ await request(
46
+ 0,
47
+ "initialize",
48
+ {"clientInfo": {"name": "tech-debt", "version": "0.1.0"}},
49
+ )
50
+ writer.write(b'{"method":"initialized"}\n')
51
+ await writer.drain()
52
+ models: list[CodexModel] = []
53
+ adapter = TypeAdapter(list[CodexModel])
54
+ cursor = None
55
+ request_id = 1
56
+ while True:
57
+ result = await request(
58
+ request_id,
59
+ "model/list",
60
+ {"limit": 100, "includeHidden": False, "cursor": cursor},
61
+ )
62
+ models.extend(adapter.validate_python(result["data"]))
63
+ cursor = result.get("nextCursor")
64
+ if cursor is None:
65
+ return models
66
+ request_id += 1
67
+
68
+ try:
69
+ return await asyncio.wait_for(fetch(), timeout=20)
70
+ finally:
71
+ if process.returncode is None:
72
+ with suppress(ProcessLookupError):
73
+ process.kill()
74
+ await process.communicate()
@@ -0,0 +1,24 @@
1
+ from collections.abc import Sequence
2
+ from pathlib import Path, PurePath
3
+
4
+
5
+ def list_search_files(paths: Sequence[PurePath]) -> frozenset[PurePath]:
6
+ """List files under canonical roots without following directory symlinks."""
7
+ roots = [Path(path) for path in paths]
8
+ files: set[PurePath] = set()
9
+ for root in roots:
10
+ if root.is_file():
11
+ files.add(root)
12
+ continue
13
+ for directory, _, names in root.walk(on_error=_raise_walk_error):
14
+ for name in names:
15
+ file = directory / name
16
+ if file.is_file():
17
+ resolved = file.resolve(strict=True)
18
+ if any(resolved.is_relative_to(source) for source in roots):
19
+ files.add(resolved)
20
+ return frozenset(files)
21
+
22
+
23
+ def _raise_walk_error(error: OSError) -> None:
24
+ raise error
@@ -0,0 +1,13 @@
1
+ from collections.abc import Sequence
2
+ from pathlib import Path, PurePath
3
+
4
+
5
+ def normalize_search_paths(paths: Sequence[PurePath]) -> list[PurePath]:
6
+ """Resolve existing files and directories, including symbolic links."""
7
+ try:
8
+ normalized: list[PurePath] = [
9
+ Path(path).expanduser().resolve(strict=True) for path in paths
10
+ ]
11
+ except OSError as error:
12
+ raise ValueError(f"Cannot resolve search paths: {error}") from error
13
+ return normalized
@@ -0,0 +1,11 @@
1
+ import tomllib
2
+ from pathlib import Path
3
+
4
+ from tech_debt._entities.agent_settings import AgentSettings
5
+
6
+
7
+ def read_agent_settings() -> AgentSettings:
8
+ """Read and validate settings from .tech-debt.toml in the current directory."""
9
+ with Path(".tech-debt.toml").open("rb") as file:
10
+ configuration = tomllib.load(file)
11
+ return AgentSettings.model_validate(configuration.get("agent", {}))
@@ -0,0 +1,109 @@
1
+ import asyncio
2
+ from collections.abc import Callable, Collection, Sequence
3
+ from pathlib import PurePath
4
+ from typing import Protocol, overload
5
+
6
+ from pydantic import TypeAdapter
7
+
8
+ from tech_debt._entities.defect import Defect
9
+ from tech_debt._entities.path_distribution import PathDistribution
10
+ from tech_debt._entities.search_tech_debt_prompt import (
11
+ CORRECT_PATH_DISTRIBUTION_PROMPT,
12
+ DEDUPLICATE_FINDINGS_PROMPT,
13
+ DISTRIBUTE_PATHS_PROMPT,
14
+ FORMAT_FINDINGS_PROMPT,
15
+ RECHECK_FINDINGS_PROMPT,
16
+ SEARCH_TECH_DEBT_PROMPT,
17
+ )
18
+ from tech_debt._stateless_computations.validate_path_distribution import (
19
+ validate_path_distribution,
20
+ )
21
+
22
+
23
+ class AgentSession(Protocol):
24
+ @overload
25
+ async def next_turn[Response](
26
+ self, prompt: str, schema: TypeAdapter[Response], /
27
+ ) -> Response: ...
28
+
29
+ @overload
30
+ async def next_turn(self, prompt: str, schema: None = None, /) -> str: ...
31
+
32
+
33
+ async def search_tech_debt(
34
+ create_session: Callable[[], AgentSession],
35
+ paths: Sequence[PurePath],
36
+ parallelism: int,
37
+ *,
38
+ normalize_paths: Callable[[Sequence[PurePath]], list[PurePath]],
39
+ list_files: Callable[[Sequence[PurePath]], Collection[PurePath]],
40
+ ) -> list[Defect]:
41
+ """Search technical debt using ``parallelism`` concurrent search sessions."""
42
+ if parallelism < 1:
43
+ raise ValueError("parallelism must be greater than zero")
44
+ if not paths:
45
+ raise ValueError("Search paths must not be empty")
46
+ paths = await asyncio.to_thread(normalize_paths, paths)
47
+ if parallelism == 1:
48
+ return await _search_tech_debt_session(create_session(), paths)
49
+
50
+ files = await asyncio.to_thread(list_files, paths)
51
+ distribution = await _distribute_paths(
52
+ create_session(), paths, parallelism, normalize_paths, files
53
+ )
54
+
55
+ async with asyncio.TaskGroup() as group:
56
+ searches = [
57
+ group.create_task(_search_tech_debt_session(create_session(), scope))
58
+ for scope in distribution
59
+ ]
60
+ defects = [defect for search in searches for defect in search.result()]
61
+ schema = TypeAdapter(list[Defect])
62
+ deduplicator = create_session()
63
+ return await deduplicator.next_turn(
64
+ DEDUPLICATE_FINDINGS_PROMPT.format(
65
+ findings=schema.dump_json(defects).decode("utf-8")
66
+ ),
67
+ schema,
68
+ )
69
+
70
+
71
+ async def _distribute_paths(
72
+ session: AgentSession,
73
+ paths: Sequence[PurePath],
74
+ parallelism: int,
75
+ normalize_paths: Callable[[Sequence[PurePath]], list[PurePath]],
76
+ files: Collection[PurePath],
77
+ ) -> PathDistribution:
78
+ distribution_schema = TypeAdapter(PathDistribution)
79
+ prompt = DISTRIBUTE_PATHS_PROMPT.format(
80
+ paths=", ".join(map(str, paths)), parallelism=parallelism
81
+ )
82
+ corrected = False
83
+ while True:
84
+ try:
85
+ distribution = await session.next_turn(prompt, distribution_schema)
86
+ if any(not path.is_absolute() for scope in distribution for path in scope):
87
+ raise ValueError("Path distribution must contain only absolute paths")
88
+ normalized = [
89
+ await asyncio.to_thread(normalize_paths, scope)
90
+ for scope in distribution
91
+ ]
92
+ validate_path_distribution(paths, normalized, parallelism, files)
93
+ return normalized
94
+ except ValueError as error:
95
+ if corrected:
96
+ raise
97
+ corrected = True
98
+ prompt = CORRECT_PATH_DISTRIBUTION_PROMPT.format(errors=str(error))
99
+
100
+
101
+ async def _search_tech_debt_session(
102
+ session: AgentSession, paths: Sequence[PurePath]
103
+ ) -> list[Defect]:
104
+ await session.next_turn(
105
+ SEARCH_TECH_DEBT_PROMPT.format(paths=", ".join(map(str, paths)))
106
+ )
107
+ schema = TypeAdapter(list[Defect])
108
+ await session.next_turn(FORMAT_FINDINGS_PROMPT, schema)
109
+ return await session.next_turn(RECHECK_FINDINGS_PROMPT, schema)
@@ -0,0 +1,195 @@
1
+ import argparse
2
+ import asyncio
3
+ import json
4
+ import shutil
5
+ import subprocess
6
+ import sys
7
+ from collections.abc import Sequence
8
+ from functools import partial
9
+ from pathlib import Path
10
+
11
+ from pydantic import TypeAdapter
12
+
13
+ from tech_debt._entities.defect import Defect
14
+ from tech_debt._stateful_effects.codex_session import CodexSession
15
+ from tech_debt._stateless_computations.format_search_error import format_search_error
16
+ from tech_debt._stateless_effects.list_codex_models import list_codex_models
17
+ from tech_debt._stateless_effects.list_search_files import list_search_files
18
+ from tech_debt._stateless_effects.normalize_search_paths import normalize_search_paths
19
+ from tech_debt._stateless_effects.read_agent_settings import read_agent_settings
20
+ from tech_debt._stateless_workflows.search_tech_debt import search_tech_debt
21
+
22
+
23
+ def main() -> None:
24
+ parser = argparse.ArgumentParser(prog="tech-debt")
25
+ commands = parser.add_subparsers(dest="command", required=True)
26
+ commands.add_parser("init", help="Check Codex CLI availability and authentication")
27
+ search = commands.add_parser("search", help="Search for technical debt")
28
+ search.add_argument(
29
+ "paths",
30
+ nargs="*",
31
+ type=Path,
32
+ default=[Path()],
33
+ help="Paths to search (default: .)",
34
+ )
35
+ search.add_argument(
36
+ "--parallelism",
37
+ "-p",
38
+ type=int,
39
+ default=1,
40
+ help="Number of parallel search sessions (default: 1)",
41
+ )
42
+ args = parser.parse_args()
43
+
44
+ if args.command == "init":
45
+ _init(parser)
46
+ elif args.command == "search":
47
+ _search(parser, args.paths, args.parallelism)
48
+
49
+
50
+ def _search(
51
+ parser: argparse.ArgumentParser, paths: Sequence[Path], parallelism: int
52
+ ) -> None:
53
+ if parallelism < 1:
54
+ parser.error("--parallelism must be greater than zero")
55
+ try:
56
+ settings = read_agent_settings()
57
+ except FileNotFoundError:
58
+ parser.exit(status=1, message="Run 'tech-debt init' before searching.\n")
59
+ except ValueError:
60
+ parser.exit(
61
+ status=1,
62
+ message="Invalid agent settings. Run 'tech-debt init' to configure them.\n",
63
+ )
64
+ except OSError:
65
+ parser.exit(status=1, message="Unable to read .tech-debt.toml.\n")
66
+
67
+ try:
68
+ defects = asyncio.run(
69
+ search_tech_debt(
70
+ partial(CodexSession, settings),
71
+ paths,
72
+ parallelism,
73
+ normalize_paths=normalize_search_paths,
74
+ list_files=list_search_files,
75
+ )
76
+ )
77
+ except KeyboardInterrupt:
78
+ parser.exit(status=130, message="\nSearch cancelled.\n")
79
+ except (
80
+ OSError,
81
+ RuntimeError,
82
+ ValueError,
83
+ subprocess.CalledProcessError,
84
+ ExceptionGroup,
85
+ ) as error:
86
+ parser.exit(status=1, message=f"Search failed:\n{format_search_error(error)}\n")
87
+ sys.stdout.write(
88
+ TypeAdapter(list[Defect]).dump_json(defects, indent=2).decode("utf-8")
89
+ )
90
+ sys.stdout.write("\n")
91
+
92
+
93
+ def _init(parser: argparse.ArgumentParser) -> None:
94
+ executable = shutil.which("codex")
95
+ if executable is None:
96
+ parser.exit(
97
+ status=1,
98
+ message=(
99
+ "Only Codex CLI is currently supported. "
100
+ "Install Codex CLI and ensure 'codex' is available in PATH.\n"
101
+ ),
102
+ )
103
+
104
+ checks = (
105
+ (["--version"], "Codex CLI is not working. Check your Codex CLI installation."),
106
+ (
107
+ ["login", "status"],
108
+ "Codex CLI authentication check failed. Run 'codex login' and try again.",
109
+ ),
110
+ )
111
+ for arguments, failure_message in checks:
112
+ try:
113
+ subprocess.run(
114
+ [executable, *arguments],
115
+ stdin=subprocess.DEVNULL,
116
+ capture_output=True,
117
+ check=True,
118
+ timeout=10,
119
+ )
120
+ except subprocess.CalledProcessError:
121
+ parser.exit(status=1, message=f"{failure_message}\n")
122
+ except subprocess.TimeoutExpired:
123
+ parser.exit(status=1, message="Codex CLI check timed out. Try again.\n")
124
+ except OSError:
125
+ parser.exit(
126
+ status=1,
127
+ message="Unable to start Codex CLI. Check your installation.\n",
128
+ )
129
+
130
+ try:
131
+ models = asyncio.run(list_codex_models())
132
+ except OSError, RuntimeError, TimeoutError, ValueError:
133
+ parser.exit(
134
+ status=1,
135
+ message="Unable to load Codex models. Check Codex CLI and retry.\n",
136
+ )
137
+ models = [model for model in models if model.supported_reasoning_efforts]
138
+ if not models:
139
+ parser.exit(
140
+ status=1, message="No Codex models with reasoning effort available.\n"
141
+ )
142
+
143
+ try:
144
+ model_index = _choose(
145
+ "Select a model for technical debt search",
146
+ [f"{model.display_name} ({model.model})" for model in models],
147
+ default=next(
148
+ (index for index, model in enumerate(models) if model.is_default), 0
149
+ ),
150
+ )
151
+ model = models[model_index]
152
+ efforts = model.supported_reasoning_efforts
153
+ effort_index = _choose(
154
+ "Select reasoning effort",
155
+ [f"{effort.reasoning_effort}: {effort.description}" for effort in efforts],
156
+ default=next(
157
+ (
158
+ index
159
+ for index, effort in enumerate(efforts)
160
+ if effort.reasoning_effort == model.default_reasoning_effort
161
+ ),
162
+ 0,
163
+ ),
164
+ )
165
+ except EOFError, KeyboardInterrupt:
166
+ parser.exit(status=1, message="\nInitialization cancelled.\n")
167
+
168
+ configuration = (
169
+ "[agent]\n"
170
+ 'provider = "codex"\n'
171
+ f"model = {json.dumps(model.model)}\n"
172
+ f"reasoning_effort = {json.dumps(efforts[effort_index].reasoning_effort)}\n"
173
+ )
174
+ try:
175
+ Path(".tech-debt.toml").write_text(configuration, encoding="utf-8")
176
+ except OSError:
177
+ parser.exit(status=1, message="Unable to save .tech-debt.toml.\n")
178
+ sys.stdout.write("Configuration saved to .tech-debt.toml.\n")
179
+
180
+
181
+ def _choose(title: str, options: Sequence[str], *, default: int = 0) -> int:
182
+ sys.stdout.write(f"\n{title}:\n")
183
+ for index, option in enumerate(options, start=1):
184
+ sys.stdout.write(f" {index}. {option}\n")
185
+ while True:
186
+ answer = input(f"Choice [{default + 1}]: ").strip()
187
+ if not answer:
188
+ return default
189
+ try:
190
+ selected = int(answer) - 1
191
+ except ValueError:
192
+ selected = -1
193
+ if 0 <= selected < len(options):
194
+ return selected
195
+ sys.stdout.write(f"Enter a number between 1 and {len(options)}.\n")
File without changes