jrrribeiro commited on
Commit
178fe29
·
1 Parent(s): 0ad3135

feat(cli): harden schema validation and jsonl error handling

Browse files
Files changed (2) hide show
  1. src/cli/project_cli.py +138 -19
  2. tests/unit/test_project_cli.py +125 -0
src/cli/project_cli.py CHANGED
@@ -2,6 +2,7 @@ from __future__ import annotations
2
 
3
  import argparse
4
  import json
 
5
  from pathlib import Path
6
  from typing import Any
7
 
@@ -13,29 +14,109 @@ DEFAULT_DATASET_DIRS = [
13
  "exports",
14
  ]
15
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
16
 
17
  def _load_json(path: Path, default: Any) -> Any:
18
  if not path.exists():
19
  return default
20
- return json.loads(path.read_text(encoding="utf-8"))
 
 
 
 
21
 
22
 
23
  def _write_json(path: Path, payload: Any) -> None:
24
  path.parent.mkdir(parents=True, exist_ok=True)
25
- path.write_text(json.dumps(payload, indent=2, ensure_ascii=True) + "\n", encoding="utf-8")
 
 
26
 
27
 
28
  def _project_exists(projects: list[dict[str, Any]], slug: str) -> bool:
29
  return any(p.get("project_slug") == slug for p in projects)
30
 
31
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
32
  def cmd_create_project(args: argparse.Namespace) -> int:
 
 
 
 
 
 
33
  projects_file = Path(args.projects_file)
34
- projects: list[dict[str, Any]] = _load_json(projects_file, [])
35
 
36
  if _project_exists(projects, args.slug):
37
  print(f"ERROR: project '{args.slug}' already exists")
38
- return 1
39
 
40
  project_entry: dict[str, Any] = {
41
  "project_slug": args.slug,
@@ -55,16 +136,19 @@ def cmd_create_project(args: argparse.Namespace) -> int:
55
 
56
  if args.user_access_file and args.owner:
57
  access_file = Path(args.user_access_file)
58
- access_payload: dict[str, dict[str, str]] = _load_json(access_file, {})
59
  owner_roles = access_payload.setdefault(args.owner, {})
60
  owner_roles[args.slug] = "admin"
61
  _write_json(access_file, access_payload)
62
 
63
  print(f"OK: project '{args.slug}' created")
64
- return 0
65
 
66
 
67
  def cmd_init_dataset(args: argparse.Namespace) -> int:
 
 
 
68
  root = Path(args.dataset_root) / args.slug
69
  for dirname in DEFAULT_DATASET_DIRS:
70
  (root / dirname).mkdir(parents=True, exist_ok=True)
@@ -82,7 +166,7 @@ def cmd_init_dataset(args: argparse.Namespace) -> int:
82
 
83
  _write_json(root / "index" / "project_metadata.json", metadata)
84
  print(f"OK: dataset scaffold initialized at {root}")
85
- return 0
86
 
87
 
88
  def _read_jsonl(path: Path) -> list[dict[str, Any]]:
@@ -90,23 +174,49 @@ def _read_jsonl(path: Path) -> list[dict[str, Any]]:
90
  if not path.exists():
91
  return rows
92
 
93
- for line_no, raw in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
 
94
  line = raw.strip()
95
  if not line:
96
  continue
97
  try:
98
- rows.append(json.loads(line))
99
  except json.JSONDecodeError as exc:
100
- raise ValueError(f"Invalid JSONL at line {line_no}: {exc}") from exc
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
101
  return rows
102
 
103
 
104
  def cmd_build_index(args: argparse.Namespace) -> int:
 
 
105
  project_root = Path(args.dataset_root) / args.slug
106
  detections_file = project_root / "detections" / "detections.jsonl"
107
  rows = _read_jsonl(detections_file)
108
 
109
- sorted_rows = sorted(rows, key=lambda d: float(d.get("confidence", 0.0)), reverse=True)
110
  index_payload = {
111
  "project_slug": args.slug,
112
  "count": len(sorted_rows),
@@ -115,7 +225,7 @@ def cmd_build_index(args: argparse.Namespace) -> int:
115
  "detection_key": r.get("detection_key"),
116
  "audio_id": r.get("audio_id"),
117
  "scientific_name": r.get("scientific_name"),
118
- "confidence": float(r.get("confidence", 0.0)),
119
  }
120
  for r in sorted_rows
121
  ],
@@ -123,16 +233,18 @@ def cmd_build_index(args: argparse.Namespace) -> int:
123
 
124
  _write_json(project_root / "index" / "detections_index.json", index_payload)
125
  print(f"OK: index generated with {len(sorted_rows)} detections")
126
- return 0
127
 
128
 
129
  def cmd_verify_project(args: argparse.Namespace) -> int:
 
 
130
  projects_file = Path(args.projects_file)
131
- projects: list[dict[str, Any]] = _load_json(projects_file, [])
132
 
133
  if not _project_exists(projects, args.slug):
134
  print(f"ERROR: project '{args.slug}' not found in {projects_file}")
135
- return 1
136
 
137
  project_root = Path(args.dataset_root) / args.slug
138
  missing: list[str] = []
@@ -155,10 +267,10 @@ def cmd_verify_project(args: argparse.Namespace) -> int:
155
  print("ERROR: project verification failed; missing paths:")
156
  for item in missing:
157
  print(f" - {item}")
158
- return 1
159
 
160
  print(f"OK: project '{args.slug}' verified")
161
- return 0
162
 
163
 
164
  def build_parser() -> argparse.ArgumentParser:
@@ -200,8 +312,15 @@ def build_parser() -> argparse.ArgumentParser:
200
 
201
  def main(argv: list[str] | None = None) -> int:
202
  parser = build_parser()
203
- args = parser.parse_args(argv)
204
- return int(args.func(args))
 
 
 
 
 
 
 
205
 
206
 
207
  if __name__ == "__main__":
 
2
 
3
  import argparse
4
  import json
5
+ import re
6
  from pathlib import Path
7
  from typing import Any
8
 
 
14
  "exports",
15
  ]
16
 
17
+ EXIT_OK = 0
18
+ EXIT_VALIDATION_ERROR = 1
19
+ EXIT_IO_ERROR = 2
20
+
21
+ SLUG_PATTERN = re.compile(r"^[a-z0-9][a-z0-9-]{1,62}$")
22
+ REPO_ID_PATTERN = re.compile(r"^[^\s/]+/[^\s/]+$")
23
+
24
+
25
+ class CliValidationError(ValueError):
26
+ pass
27
+
28
+
29
+ def _safe_read_text(path: Path) -> str:
30
+ try:
31
+ return path.read_text(encoding="utf-8")
32
+ except FileNotFoundError:
33
+ raise
34
+ except UnicodeDecodeError as exc:
35
+ raise CliValidationError(f"Invalid UTF-8 content in {path}: {exc}") from exc
36
+ except OSError as exc:
37
+ raise OSError(f"Could not read {path}: {exc}") from exc
38
+
39
+
40
+ def _validate_slug(slug: str) -> None:
41
+ if not SLUG_PATTERN.fullmatch(slug):
42
+ raise CliValidationError(
43
+ "Invalid slug. Use lowercase letters, numbers, and hyphens, length 2-63."
44
+ )
45
+
46
+
47
+ def _validate_repo_id(repo_id: str) -> None:
48
+ if not REPO_ID_PATTERN.fullmatch(repo_id):
49
+ raise CliValidationError(
50
+ "Invalid dataset_repo_id. Expected format 'owner/repo' without spaces."
51
+ )
52
+
53
 
54
  def _load_json(path: Path, default: Any) -> Any:
55
  if not path.exists():
56
  return default
57
+ raw = _safe_read_text(path)
58
+ try:
59
+ return json.loads(raw)
60
+ except json.JSONDecodeError as exc:
61
+ raise CliValidationError(f"Invalid JSON in {path}: {exc}") from exc
62
 
63
 
64
  def _write_json(path: Path, payload: Any) -> None:
65
  path.parent.mkdir(parents=True, exist_ok=True)
66
+ temp_path = path.with_suffix(path.suffix + ".tmp")
67
+ temp_path.write_text(json.dumps(payload, indent=2, ensure_ascii=True) + "\n", encoding="utf-8")
68
+ temp_path.replace(path)
69
 
70
 
71
  def _project_exists(projects: list[dict[str, Any]], slug: str) -> bool:
72
  return any(p.get("project_slug") == slug for p in projects)
73
 
74
 
75
+ def _as_project_list(payload: Any, source: Path) -> list[dict[str, Any]]:
76
+ if not isinstance(payload, list):
77
+ raise CliValidationError(f"Expected list in {source}, got {type(payload).__name__}")
78
+ for idx, item in enumerate(payload):
79
+ if not isinstance(item, dict):
80
+ raise CliValidationError(f"Project entry at index {idx} in {source} is not an object")
81
+ for field in ("project_slug", "name", "dataset_repo_id"):
82
+ if field not in item or not isinstance(item[field], str) or not item[field].strip():
83
+ raise CliValidationError(
84
+ f"Project entry at index {idx} in {source} has invalid '{field}'"
85
+ )
86
+ return payload
87
+
88
+
89
+ def _as_access_map(payload: Any, source: Path) -> dict[str, dict[str, str]]:
90
+ if not isinstance(payload, dict):
91
+ raise CliValidationError(f"Expected object in {source}, got {type(payload).__name__}")
92
+ for username, roles in payload.items():
93
+ if not isinstance(username, str) or not username.strip():
94
+ raise CliValidationError(f"Invalid username key in {source}")
95
+ if not isinstance(roles, dict):
96
+ raise CliValidationError(f"Roles for '{username}' in {source} must be an object")
97
+ for project_slug, role in roles.items():
98
+ if not isinstance(project_slug, str) or not project_slug.strip():
99
+ raise CliValidationError(f"Invalid project slug for user '{username}' in {source}")
100
+ if role not in {"admin", "validator"}:
101
+ raise CliValidationError(
102
+ f"Invalid role '{role}' for user '{username}' and project '{project_slug}' in {source}"
103
+ )
104
+ return payload
105
+
106
+
107
  def cmd_create_project(args: argparse.Namespace) -> int:
108
+ _validate_slug(args.slug)
109
+ _validate_repo_id(args.dataset_repo_id)
110
+
111
+ if args.owner and not args.owner.strip():
112
+ raise CliValidationError("Owner cannot be blank")
113
+
114
  projects_file = Path(args.projects_file)
115
+ projects = _as_project_list(_load_json(projects_file, []), projects_file)
116
 
117
  if _project_exists(projects, args.slug):
118
  print(f"ERROR: project '{args.slug}' already exists")
119
+ return EXIT_VALIDATION_ERROR
120
 
121
  project_entry: dict[str, Any] = {
122
  "project_slug": args.slug,
 
136
 
137
  if args.user_access_file and args.owner:
138
  access_file = Path(args.user_access_file)
139
+ access_payload = _as_access_map(_load_json(access_file, {}), access_file)
140
  owner_roles = access_payload.setdefault(args.owner, {})
141
  owner_roles[args.slug] = "admin"
142
  _write_json(access_file, access_payload)
143
 
144
  print(f"OK: project '{args.slug}' created")
145
+ return EXIT_OK
146
 
147
 
148
  def cmd_init_dataset(args: argparse.Namespace) -> int:
149
+ _validate_slug(args.slug)
150
+ _validate_repo_id(args.dataset_repo_id)
151
+
152
  root = Path(args.dataset_root) / args.slug
153
  for dirname in DEFAULT_DATASET_DIRS:
154
  (root / dirname).mkdir(parents=True, exist_ok=True)
 
166
 
167
  _write_json(root / "index" / "project_metadata.json", metadata)
168
  print(f"OK: dataset scaffold initialized at {root}")
169
+ return EXIT_OK
170
 
171
 
172
  def _read_jsonl(path: Path) -> list[dict[str, Any]]:
 
174
  if not path.exists():
175
  return rows
176
 
177
+ raw_content = _safe_read_text(path)
178
+ for line_no, raw in enumerate(raw_content.splitlines(), start=1):
179
  line = raw.strip()
180
  if not line:
181
  continue
182
  try:
183
+ parsed = json.loads(line)
184
  except json.JSONDecodeError as exc:
185
+ raise CliValidationError(
186
+ f"Invalid JSONL in {path} at line {line_no}: {exc.msg} (column {exc.colno})"
187
+ ) from exc
188
+
189
+ if not isinstance(parsed, dict):
190
+ raise CliValidationError(
191
+ f"Invalid JSONL in {path} at line {line_no}: expected object per line"
192
+ )
193
+
194
+ required = ("detection_key", "audio_id", "scientific_name", "confidence")
195
+ for field in required:
196
+ if field not in parsed:
197
+ raise CliValidationError(
198
+ f"Invalid JSONL in {path} at line {line_no}: missing '{field}'"
199
+ )
200
+
201
+ try:
202
+ parsed["confidence"] = float(parsed["confidence"])
203
+ except (TypeError, ValueError) as exc:
204
+ raise CliValidationError(
205
+ f"Invalid JSONL in {path} at line {line_no}: 'confidence' must be numeric"
206
+ ) from exc
207
+
208
+ rows.append(parsed)
209
  return rows
210
 
211
 
212
  def cmd_build_index(args: argparse.Namespace) -> int:
213
+ _validate_slug(args.slug)
214
+
215
  project_root = Path(args.dataset_root) / args.slug
216
  detections_file = project_root / "detections" / "detections.jsonl"
217
  rows = _read_jsonl(detections_file)
218
 
219
+ sorted_rows = sorted(rows, key=lambda d: d["confidence"], reverse=True)
220
  index_payload = {
221
  "project_slug": args.slug,
222
  "count": len(sorted_rows),
 
225
  "detection_key": r.get("detection_key"),
226
  "audio_id": r.get("audio_id"),
227
  "scientific_name": r.get("scientific_name"),
228
+ "confidence": r["confidence"],
229
  }
230
  for r in sorted_rows
231
  ],
 
233
 
234
  _write_json(project_root / "index" / "detections_index.json", index_payload)
235
  print(f"OK: index generated with {len(sorted_rows)} detections")
236
+ return EXIT_OK
237
 
238
 
239
  def cmd_verify_project(args: argparse.Namespace) -> int:
240
+ _validate_slug(args.slug)
241
+
242
  projects_file = Path(args.projects_file)
243
+ projects = _as_project_list(_load_json(projects_file, []), projects_file)
244
 
245
  if not _project_exists(projects, args.slug):
246
  print(f"ERROR: project '{args.slug}' not found in {projects_file}")
247
+ return EXIT_VALIDATION_ERROR
248
 
249
  project_root = Path(args.dataset_root) / args.slug
250
  missing: list[str] = []
 
267
  print("ERROR: project verification failed; missing paths:")
268
  for item in missing:
269
  print(f" - {item}")
270
+ return EXIT_VALIDATION_ERROR
271
 
272
  print(f"OK: project '{args.slug}' verified")
273
+ return EXIT_OK
274
 
275
 
276
  def build_parser() -> argparse.ArgumentParser:
 
312
 
313
  def main(argv: list[str] | None = None) -> int:
314
  parser = build_parser()
315
+ try:
316
+ args = parser.parse_args(argv)
317
+ return int(args.func(args))
318
+ except CliValidationError as exc:
319
+ print(f"ERROR: {exc}")
320
+ return EXIT_VALIDATION_ERROR
321
+ except OSError as exc:
322
+ print(f"ERROR: I/O failure: {exc}")
323
+ return EXIT_IO_ERROR
324
 
325
 
326
  if __name__ == "__main__":
tests/unit/test_project_cli.py CHANGED
@@ -1,6 +1,8 @@
1
  import json
2
  from pathlib import Path
3
 
 
 
4
  from src.cli.project_cli import main
5
 
6
 
@@ -160,3 +162,126 @@ def test_init_build_and_verify_project_flow(tmp_path: Path) -> None:
160
  ]
161
  )
162
  assert verify_exit == 0
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  import json
2
  from pathlib import Path
3
 
4
+ import pytest
5
+
6
  from src.cli.project_cli import main
7
 
8
 
 
162
  ]
163
  )
164
  assert verify_exit == 0
165
+
166
+
167
+ def test_create_project_rejects_invalid_slug(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
168
+ projects_file = tmp_path / "projects.json"
169
+ projects_file.write_text("[]\n", encoding="utf-8")
170
+
171
+ exit_code = main(
172
+ [
173
+ "create-project",
174
+ "--projects-file",
175
+ str(projects_file),
176
+ "--slug",
177
+ "Invalid Slug",
178
+ "--name",
179
+ "Project",
180
+ "--dataset-repo-id",
181
+ "org/p1",
182
+ ]
183
+ )
184
+
185
+ captured = capsys.readouterr()
186
+ assert exit_code == 1
187
+ assert "Invalid slug" in captured.out
188
+
189
+
190
+ def test_create_project_fails_on_invalid_projects_json(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
191
+ projects_file = tmp_path / "projects.json"
192
+ projects_file.write_text("{not-json", encoding="utf-8")
193
+
194
+ exit_code = main(
195
+ [
196
+ "create-project",
197
+ "--projects-file",
198
+ str(projects_file),
199
+ "--slug",
200
+ "p3",
201
+ "--name",
202
+ "Project 3",
203
+ "--dataset-repo-id",
204
+ "org/p3",
205
+ ]
206
+ )
207
+
208
+ captured = capsys.readouterr()
209
+ assert exit_code == 1
210
+ assert "Invalid JSON" in captured.out
211
+
212
+
213
+ def test_build_index_fails_on_invalid_jsonl_line(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
214
+ dataset_root = tmp_path / "datasets"
215
+ project_root = dataset_root / "p4"
216
+ (project_root / "detections").mkdir(parents=True)
217
+ (project_root / "index").mkdir(parents=True)
218
+ (project_root / "detections" / "detections.jsonl").write_text("{bad json}\n", encoding="utf-8")
219
+
220
+ exit_code = main(
221
+ [
222
+ "build-index",
223
+ "--dataset-root",
224
+ str(dataset_root),
225
+ "--slug",
226
+ "p4",
227
+ ]
228
+ )
229
+
230
+ captured = capsys.readouterr()
231
+ assert exit_code == 1
232
+ assert "Invalid JSONL" in captured.out
233
+ assert "line 1" in captured.out
234
+
235
+
236
+ def test_build_index_fails_on_non_numeric_confidence(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
237
+ dataset_root = tmp_path / "datasets"
238
+ project_root = dataset_root / "p5"
239
+ (project_root / "detections").mkdir(parents=True)
240
+ (project_root / "index").mkdir(parents=True)
241
+ (project_root / "detections" / "detections.jsonl").write_text(
242
+ json.dumps(
243
+ {
244
+ "detection_key": "k1",
245
+ "audio_id": "a1",
246
+ "scientific_name": "Sp",
247
+ "confidence": "not-a-number",
248
+ }
249
+ )
250
+ + "\n",
251
+ encoding="utf-8",
252
+ )
253
+
254
+ exit_code = main(
255
+ [
256
+ "build-index",
257
+ "--dataset-root",
258
+ str(dataset_root),
259
+ "--slug",
260
+ "p5",
261
+ ]
262
+ )
263
+
264
+ captured = capsys.readouterr()
265
+ assert exit_code == 1
266
+ assert "confidence" in captured.out
267
+
268
+
269
+ def test_verify_project_rejects_invalid_projects_schema(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
270
+ projects_file = tmp_path / "projects.json"
271
+ projects_file.write_text(json.dumps({"project_slug": "p2"}), encoding="utf-8")
272
+
273
+ exit_code = main(
274
+ [
275
+ "verify-project",
276
+ "--projects-file",
277
+ str(projects_file),
278
+ "--dataset-root",
279
+ str(tmp_path / "datasets"),
280
+ "--slug",
281
+ "p2",
282
+ ]
283
+ )
284
+
285
+ captured = capsys.readouterr()
286
+ assert exit_code == 1
287
+ assert "Expected list" in captured.out