projectbudget 0.1.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 (124) hide show
  1. projectbudget/__init__.py +10 -0
  2. projectbudget/adapters/__init__.py +5 -0
  3. projectbudget/adapters/export_format.py +220 -0
  4. projectbudget/adapters/manifest.py +341 -0
  5. projectbudget/adapters/sources.py +232 -0
  6. projectbudget/api/__init__.py +1 -0
  7. projectbudget/api/backlog.py +20 -0
  8. projectbudget/api/budget.py +56 -0
  9. projectbudget/api/catalog.py +129 -0
  10. projectbudget/api/forecast.py +20 -0
  11. projectbudget/api/projects.py +57 -0
  12. projectbudget/api/purchases.py +154 -0
  13. projectbudget/api/requirements.py +92 -0
  14. projectbudget/api/router.py +115 -0
  15. projectbudget/api/schemas.py +997 -0
  16. projectbudget/api/sync.py +135 -0
  17. projectbudget/api/transfer.py +36 -0
  18. projectbudget/cli/__init__.py +1 -0
  19. projectbudget/cli/demo.py +51 -0
  20. projectbudget/cli/main.py +554 -0
  21. projectbudget/domain/__init__.py +1 -0
  22. projectbudget/domain/catalog.py +173 -0
  23. projectbudget/domain/consolidation.py +264 -0
  24. projectbudget/domain/forecast.py +381 -0
  25. projectbudget/domain/manifest.py +80 -0
  26. projectbudget/domain/money.py +191 -0
  27. projectbudget/domain/principal.py +23 -0
  28. projectbudget/domain/sync.py +506 -0
  29. projectbudget/fixtures/__init__.py +1 -0
  30. projectbudget/fixtures/canonical.py +178 -0
  31. projectbudget/localtime.py +90 -0
  32. projectbudget/mcp_server.py +351 -0
  33. projectbudget/persistence/__init__.py +5 -0
  34. projectbudget/persistence/backup.py +63 -0
  35. projectbudget/persistence/base.py +23 -0
  36. projectbudget/persistence/engine.py +96 -0
  37. projectbudget/persistence/migrate.py +100 -0
  38. projectbudget/persistence/migrations/env.py +55 -0
  39. projectbudget/persistence/migrations/script.py.mako +24 -0
  40. projectbudget/persistence/migrations/versions/0001_initial.py +24 -0
  41. projectbudget/persistence/migrations/versions/0002_owner_auth.py +87 -0
  42. projectbudget/persistence/migrations/versions/0003_domain_core.py +141 -0
  43. projectbudget/persistence/migrations/versions/0004_inventory_and_backlog_order.py +74 -0
  44. projectbudget/persistence/migrations/versions/0005_budget_plan_and_purchases.py +151 -0
  45. projectbudget/persistence/migrations/versions/0006_catalog_merge_redirect.py +39 -0
  46. projectbudget/persistence/migrations/versions/0007_sync_sources_and_source_refs.py +129 -0
  47. projectbudget/persistence/models.py +371 -0
  48. projectbudget/persistence/session.py +11 -0
  49. projectbudget/py.typed +0 -0
  50. projectbudget/services/__init__.py +1 -0
  51. projectbudget/services/auth.py +367 -0
  52. projectbudget/services/backlog.py +150 -0
  53. projectbudget/services/budget.py +237 -0
  54. projectbudget/services/catalog.py +518 -0
  55. projectbudget/services/clock.py +15 -0
  56. projectbudget/services/errors.py +95 -0
  57. projectbudget/services/forecast.py +27 -0
  58. projectbudget/services/guards.py +30 -0
  59. projectbudget/services/inventory.py +314 -0
  60. projectbudget/services/passwords.py +55 -0
  61. projectbudget/services/projects.py +128 -0
  62. projectbudget/services/purchases.py +588 -0
  63. projectbudget/services/requirements.py +318 -0
  64. projectbudget/services/sync.py +966 -0
  65. projectbudget/services/tokens.py +147 -0
  66. projectbudget/services/transfer.py +536 -0
  67. projectbudget/services/workspace.py +57 -0
  68. projectbudget/settings.py +119 -0
  69. projectbudget/web/__init__.py +4 -0
  70. projectbudget/web/app.py +79 -0
  71. projectbudget/web/auth.py +146 -0
  72. projectbudget/web/errors.py +94 -0
  73. projectbudget/web/health.py +56 -0
  74. projectbudget/web/pages/__init__.py +1 -0
  75. projectbudget/web/pages/account.py +90 -0
  76. projectbudget/web/pages/backlog.py +59 -0
  77. projectbudget/web/pages/budget.py +112 -0
  78. projectbudget/web/pages/catalog.py +220 -0
  79. projectbudget/web/pages/data.py +67 -0
  80. projectbudget/web/pages/login.py +137 -0
  81. projectbudget/web/pages/projects.py +313 -0
  82. projectbudget/web/pages/purchases.py +231 -0
  83. projectbudget/web/pages/sync.py +242 -0
  84. projectbudget/web/pages/timeline.py +97 -0
  85. projectbudget/web/pages/tokens.py +78 -0
  86. projectbudget/web/security.py +109 -0
  87. projectbudget/web/static/app.css +164 -0
  88. projectbudget/web/static/confirm.js +29 -0
  89. projectbudget/web/static/favicon.svg +1 -0
  90. projectbudget/web/static/timeline.js +112 -0
  91. projectbudget/web/static/vendor/chartjs/LICENSE.md +9 -0
  92. projectbudget/web/static/vendor/chartjs/README.md +10 -0
  93. projectbudget/web/static/vendor/chartjs/chart.umd.js +14 -0
  94. projectbudget/web/static/vendor/htmx/LICENSE +13 -0
  95. projectbudget/web/static/vendor/htmx/README.md +9 -0
  96. projectbudget/web/static/vendor/htmx/htmx.min.js +1 -0
  97. projectbudget/web/templates/account.html +28 -0
  98. projectbudget/web/templates/backlog.html +41 -0
  99. projectbudget/web/templates/base.html +42 -0
  100. projectbudget/web/templates/budget.html +83 -0
  101. projectbudget/web/templates/catalog.html +57 -0
  102. projectbudget/web/templates/catalog_item.html +110 -0
  103. projectbudget/web/templates/data.html +37 -0
  104. projectbudget/web/templates/error.html +9 -0
  105. projectbudget/web/templates/login.html +23 -0
  106. projectbudget/web/templates/partials/backlog_table.html +77 -0
  107. projectbudget/web/templates/partials/requirement_row.html +73 -0
  108. projectbudget/web/templates/partials/token_row.html +18 -0
  109. projectbudget/web/templates/project.html +112 -0
  110. projectbudget/web/templates/projects.html +32 -0
  111. projectbudget/web/templates/purchase.html +101 -0
  112. projectbudget/web/templates/purchases.html +50 -0
  113. projectbudget/web/templates/setup_required.html +12 -0
  114. projectbudget/web/templates/sync.html +56 -0
  115. projectbudget/web/templates/sync_source.html +166 -0
  116. projectbudget/web/templates/timeline.html +136 -0
  117. projectbudget/web/templates/tokens.html +39 -0
  118. projectbudget/web/templates.py +54 -0
  119. projectbudget-0.1.0.dist-info/METADATA +125 -0
  120. projectbudget-0.1.0.dist-info/RECORD +124 -0
  121. projectbudget-0.1.0.dist-info/WHEEL +4 -0
  122. projectbudget-0.1.0.dist-info/entry_points.txt +2 -0
  123. projectbudget-0.1.0.dist-info/licenses/LICENSE +201 -0
  124. projectbudget-0.1.0.dist-info/licenses/NOTICE +5 -0
@@ -0,0 +1,10 @@
1
+ """ProjectBudget: one honest shopping backlog across all your projects."""
2
+
3
+ from importlib.metadata import PackageNotFoundError, version
4
+
5
+ try:
6
+ __version__ = version("projectbudget")
7
+ except PackageNotFoundError: # pragma: no cover - source tree that was never installed
8
+ __version__ = "0.0.0"
9
+
10
+ __all__ = ["__version__"]
@@ -0,0 +1,5 @@
1
+ """Adapters: the formats and sources at the edge of the system (RFC v3 §3).
2
+
3
+ Export/import lives here; the sync adapters (manifest file, CSV, GitHub) follow
4
+ with Milestone 4. Nothing in this package opens a database session.
5
+ """
@@ -0,0 +1,220 @@
1
+ """The canonical export document (ADR-008): one versioned JSON file for the whole workspace.
2
+
3
+ Pure data: pydantic models that validate a document and nothing else. Money is an
4
+ integer in minor units (``*_minor`` fields) in the document's single currency;
5
+ dates are ISO strings; every id is preserved so an import reproduces the
6
+ workspace exactly. Unknown fields are rejected so a typo cannot silently drop data.
7
+ """
8
+
9
+ import json
10
+ from datetime import date, datetime
11
+ from typing import Any
12
+
13
+ from pydantic import BaseModel, ConfigDict, Field, ValidationError
14
+
15
+ from projectbudget.domain.catalog import (
16
+ Confidence,
17
+ EstimateOrigin,
18
+ Intent,
19
+ ItemKind,
20
+ MovementReason,
21
+ PurchaseStatus,
22
+ ReviewState,
23
+ RunStatus,
24
+ Sharing,
25
+ SourceKind,
26
+ )
27
+
28
+ FORMAT = "projectbudget-workspace"
29
+ VERSION = 2
30
+ SUPPORTED_VERSIONS = (1, 2)
31
+ """Version 1 had no sync sources or source references; it is read and upgraded on import."""
32
+
33
+
34
+ class InvalidDocumentError(ValueError):
35
+ """Not a ProjectBudget export, the wrong version, or a field that does not validate."""
36
+
37
+
38
+ class Record(BaseModel):
39
+ model_config = ConfigDict(extra="forbid", str_strip_whitespace=False)
40
+
41
+
42
+ class ProjectRecord(Record):
43
+ id: str
44
+ name: str
45
+ archived: bool
46
+ notes: str
47
+ source_id: str | None = None
48
+ external_id: str | None = None
49
+ created_at: datetime
50
+ updated_at: datetime
51
+
52
+
53
+ class CatalogItemRecord(Record):
54
+ id: str
55
+ slug: str
56
+ name: str
57
+ kind: ItemKind
58
+ unit: str
59
+ review_state: ReviewState
60
+ merged_into_id: str | None
61
+ created_by_source_id: str | None = None
62
+ created_at: datetime
63
+ updated_at: datetime
64
+
65
+
66
+ class RequirementRecord(Record):
67
+ id: str
68
+ project_id: str
69
+ catalog_item_id: str
70
+ qty: int
71
+ priority: int
72
+ sort_order: int
73
+ intent: Intent
74
+ archive_reason: str | None
75
+ sharing: Sharing
76
+ notes: str
77
+ source_id: str | None = None
78
+ external_id: str | None = None
79
+ created_at: datetime
80
+ updated_at: datetime
81
+
82
+
83
+ class PriceEstimateRecord(Record):
84
+ id: str
85
+ catalog_item_id: str
86
+ amount_minor: int
87
+ as_of: date
88
+ confidence: Confidence
89
+ origin: EstimateOrigin
90
+ created_at: datetime
91
+
92
+
93
+ class InventoryMovementRecord(Record):
94
+ id: str
95
+ catalog_item_id: str
96
+ delta_qty: int
97
+ reason: MovementReason
98
+ requirement_id: str | None
99
+ purchase_line_id: str | None
100
+ occurred_on: date
101
+ note: str
102
+ created_at: datetime
103
+
104
+
105
+ class PurchaseLineRecord(Record):
106
+ id: str
107
+ catalog_item_id: str
108
+ position: int
109
+ qty: int
110
+ unit_price_minor: int
111
+ received_qty: int
112
+
113
+
114
+ class PurchaseRecord(Record):
115
+ id: str
116
+ vendor: str
117
+ ordered_on: date
118
+ status: PurchaseStatus
119
+ shipping_minor: int
120
+ tax_minor: int
121
+ notes: str
122
+ lines: list[PurchaseLineRecord]
123
+ created_at: datetime
124
+ updated_at: datetime
125
+
126
+
127
+ class MonthOverrideRecord(Record):
128
+ id: str
129
+ month: date
130
+ delta_minor: int
131
+ label: str
132
+ created_at: datetime
133
+
134
+
135
+ class BudgetPlanRecord(Record):
136
+ earmarked_funds_minor: int
137
+ balance_as_of: date
138
+ protected_reserve_minor: int
139
+ monthly_contribution_minor: int
140
+ horizon_months: int
141
+ contingency_pct: int
142
+ updated_at: datetime
143
+ overrides: list[MonthOverrideRecord]
144
+
145
+
146
+ class SyncSourceRecord(Record):
147
+ id: str
148
+ kind: SourceKind
149
+ locator: str
150
+ branch: str | None
151
+ path: str | None
152
+ external_project_id: str | None
153
+ token_env: str | None
154
+ last_revision: str | None
155
+ last_content_hash: str | None
156
+ created_at: datetime
157
+ updated_at: datetime
158
+
159
+
160
+ class SyncRunRecord(Record):
161
+ id: str
162
+ source_id: str
163
+ status: RunStatus
164
+ revision: str | None
165
+ content_hash: str | None
166
+ summary: dict[str, Any]
167
+ created_at: datetime
168
+
169
+
170
+ class WorkspaceDocument(Record):
171
+ """The whole workspace. Collections are sorted by id so two exports of one state are equal."""
172
+
173
+ format: str = Field(default=FORMAT)
174
+ version: int = Field(default=VERSION)
175
+ exported_at: datetime
176
+ currency: str
177
+ projects: list[ProjectRecord]
178
+ catalog_items: list[CatalogItemRecord]
179
+ requirements: list[RequirementRecord]
180
+ price_estimates: list[PriceEstimateRecord]
181
+ inventory_movements: list[InventoryMovementRecord]
182
+ purchases: list[PurchaseRecord]
183
+ backlog_order: list[str]
184
+ budget_plan: BudgetPlanRecord | None
185
+ sync_sources: list[SyncSourceRecord] = Field(default_factory=list)
186
+ sync_runs: list[SyncRunRecord] = Field(default_factory=list)
187
+
188
+ def to_json(self) -> str:
189
+ """Stable text: sorted keys, two-space indent, trailing newline."""
190
+ return json.dumps(self.model_dump(mode="json"), indent=2, sort_keys=True) + "\n"
191
+
192
+ def content_without_timestamp(self) -> dict[str, Any]:
193
+ """Everything but ``exported_at``: what two exports of the same workspace share."""
194
+ data = self.model_dump(mode="json")
195
+ data.pop("exported_at")
196
+ return data
197
+
198
+
199
+ def parse_document(data: bytes | str | dict[str, Any]) -> WorkspaceDocument:
200
+ """Validate raw JSON (or an already-decoded object) into a document, or raise."""
201
+ try:
202
+ raw: Any = json.loads(data) if isinstance(data, bytes | str) else data
203
+ except json.JSONDecodeError as exc:
204
+ raise InvalidDocumentError(f"Not JSON: {exc}") from exc
205
+ if not isinstance(raw, dict):
206
+ raise InvalidDocumentError("An export is a JSON object")
207
+ if raw.get("format") != FORMAT:
208
+ raise InvalidDocumentError(f"Not a ProjectBudget export (format {raw.get('format')!r})")
209
+ if raw.get("version") not in SUPPORTED_VERSIONS:
210
+ raise InvalidDocumentError(
211
+ f"Export version {raw.get('version')!r} is not supported; this build reads versions "
212
+ + ", ".join(str(v) for v in SUPPORTED_VERSIONS)
213
+ )
214
+ raw = {**raw, "version": VERSION} # version 1 documents validate as version 2 with defaults
215
+ try:
216
+ return WorkspaceDocument.model_validate(raw)
217
+ except ValidationError as exc:
218
+ first = exc.errors()[0]
219
+ where = ".".join(str(part) for part in first["loc"])
220
+ raise InvalidDocumentError(f"Invalid export at {where}: {first['msg']}") from exc
@@ -0,0 +1,341 @@
1
+ """Parse manifest v1 from YAML or CSV with line-level schema errors (RFC v3 §6, ADR-007).
2
+
3
+ A schema error (invalid YAML, a missing field, a duplicate id, a float where a
4
+ decimal string belongs) rejects the whole file: ``ManifestError`` carries every
5
+ issue with its line. Semantic questions (does the catalog item exist, does the
6
+ currency match) are not asked here; the sync engine answers them per item.
7
+ """
8
+
9
+ import csv
10
+ import io
11
+ from typing import Annotated, Any
12
+
13
+ import yaml
14
+ from pydantic import BaseModel, ConfigDict, Field, StrictInt, StrictStr, ValidationError
15
+
16
+ from projectbudget.domain.catalog import (
17
+ NAME_MAX_LENGTH,
18
+ SLUG_MAX_LENGTH,
19
+ UNIT_MAX_LENGTH,
20
+ ItemKind,
21
+ Sharing,
22
+ validate_slug,
23
+ )
24
+ from projectbudget.domain.manifest import (
25
+ AMOUNT_PATTERN,
26
+ MANIFEST_VERSION,
27
+ Manifest,
28
+ ManifestError,
29
+ ManifestEstimate,
30
+ ManifestIssue,
31
+ ManifestItem,
32
+ )
33
+
34
+ CSV_COLUMNS = ("id", "name", "qty", "unit", "kind", "priority", "sharing", "catalog", "estimate")
35
+ MAX_MANIFEST_BYTES = 2 * 1024 * 1024
36
+
37
+ Slug = Annotated[StrictStr, Field(min_length=1, max_length=SLUG_MAX_LENGTH)]
38
+
39
+
40
+ class Strict(BaseModel):
41
+ model_config = ConfigDict(extra="forbid")
42
+
43
+
44
+ class EstimateDocument(Strict):
45
+ amount: Annotated[StrictStr, Field(pattern=AMOUNT_PATTERN)] | None = Field(
46
+ default=None, description='Decimal string, e.g. "12.50". YAML numbers are rejected.'
47
+ )
48
+ amount_minor: StrictInt | None = Field(default=None, ge=0)
49
+ currency: Annotated[StrictStr, Field(pattern=r"^[A-Za-z]{3}$")] | None = None
50
+
51
+
52
+ class ItemDocument(Strict):
53
+ id: Slug
54
+ name: Annotated[StrictStr, Field(min_length=1, max_length=NAME_MAX_LENGTH)]
55
+ qty: Annotated[StrictInt, Field(ge=1)]
56
+ unit: Annotated[StrictStr, Field(min_length=1, max_length=UNIT_MAX_LENGTH)] = "each"
57
+ kind: ItemKind = ItemKind.CONSUMABLE
58
+ priority: Annotated[StrictInt, Field(ge=1, le=3)] = 2
59
+ sharing: Sharing = Sharing.SHARED
60
+ estimate: EstimateDocument | None = None
61
+ catalog: Slug | None = None
62
+ notes: StrictStr = ""
63
+
64
+
65
+ class ProjectDocument(Strict):
66
+ id: Slug
67
+ name: Annotated[StrictStr, Field(min_length=1, max_length=NAME_MAX_LENGTH)] | None = None
68
+
69
+
70
+ class ManifestDocument(Strict):
71
+ """Manifest v1. The JSON Schema in the repository is generated from this model."""
72
+
73
+ version: Annotated[StrictInt, Field(ge=MANIFEST_VERSION, le=MANIFEST_VERSION)]
74
+ project: ProjectDocument
75
+ items: list[ItemDocument]
76
+
77
+
78
+ def manifest_json_schema() -> dict[str, Any]:
79
+ schema = ManifestDocument.model_json_schema()
80
+ schema["$schema"] = "https://json-schema.org/draft/2020-12/schema"
81
+ schema["$id"] = "https://github.com/sdeery14/project-budget/blob/main/docs/manifest.schema.json"
82
+ schema["title"] = "ProjectBudget manifest v1"
83
+ return schema
84
+
85
+
86
+ # --- YAML ------------------------------------------------------------------------------
87
+
88
+
89
+ def _line_map(node: yaml.Node, path: str, lines: dict[str, int]) -> None:
90
+ """Record the 1-based line of every mapping value and sequence element by its path."""
91
+ lines.setdefault(path, node.start_mark.line + 1)
92
+ if isinstance(node, yaml.MappingNode):
93
+ for key_node, value_node in node.value:
94
+ key = str(getattr(key_node, "value", "?"))
95
+ child = f"{path}.{key}" if path else key
96
+ lines[child] = value_node.start_mark.line + 1
97
+ _line_map(value_node, child, lines)
98
+ elif isinstance(node, yaml.SequenceNode):
99
+ for index, element in enumerate(node.value):
100
+ child = f"{path}[{index}]"
101
+ lines[child] = element.start_mark.line + 1
102
+ _line_map(element, child, lines)
103
+
104
+
105
+ def _path_of(loc: tuple[int | str, ...]) -> str:
106
+ path = ""
107
+ for part in loc:
108
+ path = (
109
+ f"{path}[{part}]"
110
+ if isinstance(part, int)
111
+ else (f"{path}.{part}" if path else str(part))
112
+ )
113
+ return path
114
+
115
+
116
+ def _nearest_line(path: str, lines: dict[str, int]) -> int | None:
117
+ while path:
118
+ if path in lines:
119
+ return lines[path]
120
+ cut = max(path.rfind("."), path.rfind("["))
121
+ path = path[:cut] if cut > 0 else ""
122
+ return lines.get("")
123
+
124
+
125
+ def _issues_from_validation(
126
+ exc: ValidationError, lines: dict[str, int]
127
+ ) -> tuple[ManifestIssue, ...]:
128
+ issues = []
129
+ for error in exc.errors():
130
+ path = _path_of(tuple(error["loc"]))
131
+ message = error["msg"]
132
+ if error["type"] == "string_type" and path.endswith("amount"):
133
+ message = 'amount must be a quoted decimal string such as "12.50", not a number'
134
+ issues.append(
135
+ ManifestIssue(path=path or "document", message=message, line=_nearest_line(path, lines))
136
+ )
137
+ return tuple(issues)
138
+
139
+
140
+ def _raw_id_issues(data: dict[str, Any], lines: dict[str, int]) -> list[ManifestIssue]:
141
+ """Slug and duplicate problems found on the raw document, so they show up with schema errors."""
142
+ issues: list[ManifestIssue] = []
143
+ items = data.get("items")
144
+ if not isinstance(items, list):
145
+ return issues
146
+ seen: dict[str, int] = {}
147
+ for index, raw in enumerate(items):
148
+ if not isinstance(raw, dict) or not isinstance(raw.get("id"), str):
149
+ continue
150
+ item_id = raw["id"]
151
+ path = f"items[{index}].id"
152
+ try:
153
+ validate_slug(item_id)
154
+ except ValueError as exc:
155
+ issues.append(ManifestIssue(path=path, message=str(exc), line=lines.get(path)))
156
+ if item_id in seen:
157
+ issues.append(
158
+ ManifestIssue(
159
+ path=path,
160
+ message=f"duplicate item id {item_id!r} (first used at items[{seen[item_id]}])",
161
+ line=lines.get(path),
162
+ )
163
+ )
164
+ seen.setdefault(item_id, index)
165
+ return issues
166
+
167
+
168
+ def _validate(data: dict[str, Any], lines: dict[str, int]) -> ManifestDocument:
169
+ """Schema validation plus the id checks, reported together with their lines."""
170
+ try:
171
+ return ManifestDocument.model_validate(data)
172
+ except ValidationError as exc:
173
+ raise ManifestError(
174
+ _issues_from_validation(exc, lines) + tuple(_raw_id_issues(data, lines))
175
+ ) from exc
176
+
177
+
178
+ def _to_domain(doc: ManifestDocument, lines: dict[str, int]) -> Manifest:
179
+ issues: list[ManifestIssue] = []
180
+ seen: dict[str, int] = {}
181
+ for index, item in enumerate(doc.items):
182
+ path = f"items[{index}].id"
183
+ try:
184
+ validate_slug(item.id)
185
+ except ValueError as exc:
186
+ issues.append(ManifestIssue(path=path, message=str(exc), line=lines.get(path)))
187
+ if item.id in seen:
188
+ issues.append(
189
+ ManifestIssue(
190
+ path=path,
191
+ message=f"duplicate item id {item.id!r} (first used at items[{seen[item.id]}])",
192
+ line=lines.get(path),
193
+ )
194
+ )
195
+ seen.setdefault(item.id, index)
196
+ if item.catalog is not None:
197
+ try:
198
+ validate_slug(item.catalog)
199
+ except ValueError as exc:
200
+ cpath = f"items[{index}].catalog"
201
+ issues.append(ManifestIssue(path=cpath, message=str(exc), line=lines.get(cpath)))
202
+ if (
203
+ item.estimate is not None
204
+ and item.estimate.amount is None
205
+ and item.estimate.amount_minor is None
206
+ ):
207
+ epath = f"items[{index}].estimate"
208
+ issues.append(
209
+ ManifestIssue(
210
+ path=epath,
211
+ message="estimate needs amount or amount_minor",
212
+ line=lines.get(epath),
213
+ )
214
+ )
215
+ try:
216
+ validate_slug(doc.project.id)
217
+ except ValueError as exc:
218
+ issues.append(
219
+ ManifestIssue(path="project.id", message=str(exc), line=lines.get("project.id"))
220
+ )
221
+ if issues:
222
+ raise ManifestError(tuple(issues))
223
+ return Manifest(
224
+ version=doc.version,
225
+ project_id=doc.project.id,
226
+ project_name=doc.project.name or doc.project.id,
227
+ items=tuple(
228
+ ManifestItem(
229
+ id=item.id,
230
+ name=" ".join(item.name.split()),
231
+ qty=item.qty,
232
+ unit=item.unit.strip().lower(),
233
+ kind=item.kind,
234
+ priority=item.priority,
235
+ sharing=item.sharing,
236
+ estimate=ManifestEstimate(
237
+ amount=item.estimate.amount,
238
+ amount_minor=item.estimate.amount_minor,
239
+ currency=item.estimate.currency,
240
+ )
241
+ if item.estimate is not None
242
+ else None,
243
+ catalog=item.catalog,
244
+ notes=item.notes.strip(),
245
+ )
246
+ for item in doc.items
247
+ ),
248
+ )
249
+
250
+
251
+ def _text(content: bytes | str) -> str:
252
+ if isinstance(content, str):
253
+ return content
254
+ if len(content) > MAX_MANIFEST_BYTES:
255
+ raise ManifestError((ManifestIssue(path="document", message="manifest larger than 2 MB"),))
256
+ try:
257
+ return content.decode("utf-8")
258
+ except UnicodeDecodeError as exc:
259
+ raise ManifestError((ManifestIssue(path="document", message=f"not UTF-8: {exc}"),)) from exc
260
+
261
+
262
+ def parse_yaml(content: bytes | str) -> Manifest:
263
+ """Parse a ``project-budget.yaml``; every schema problem is reported with its line."""
264
+ text = _text(content)
265
+ try:
266
+ loader = yaml.SafeLoader(text)
267
+ try:
268
+ node = loader.get_single_node()
269
+ data = loader.construct_document(node) if node is not None else None
270
+ finally:
271
+ loader.dispose()
272
+ except yaml.YAMLError as exc:
273
+ mark = getattr(exc, "problem_mark", None)
274
+ line = mark.line + 1 if mark is not None else None
275
+ problem = getattr(exc, "problem", None) or str(exc)
276
+ raise ManifestError(
277
+ (ManifestIssue(path="document", message=f"invalid YAML: {problem}", line=line),)
278
+ ) from exc
279
+ if not isinstance(data, dict):
280
+ raise ManifestError(
281
+ (ManifestIssue(path="document", message="the manifest must be a mapping", line=1),)
282
+ )
283
+ lines: dict[str, int] = {}
284
+ if node is not None:
285
+ _line_map(node, "", lines)
286
+ return _to_domain(_validate(data, lines), lines)
287
+
288
+
289
+ # --- CSV -------------------------------------------------------------------------------
290
+
291
+
292
+ def parse_csv(
293
+ content: bytes | str, *, project_id: str, project_name: str | None = None
294
+ ) -> Manifest:
295
+ """Parse the fixed-column CSV form. The project id comes from the source, not the file."""
296
+ text = _text(content)
297
+ reader = csv.DictReader(io.StringIO(text))
298
+ header = tuple(name.strip() for name in (reader.fieldnames or ()))
299
+ if set(header) != set(CSV_COLUMNS) or len(header) != len(CSV_COLUMNS):
300
+ raise ManifestError(
301
+ (
302
+ ManifestIssue(
303
+ path="header",
304
+ message=f"columns must be exactly {', '.join(CSV_COLUMNS)}; got {', '.join(header) or 'nothing'}",
305
+ line=1,
306
+ ),
307
+ )
308
+ )
309
+ items: list[dict[str, Any]] = []
310
+ lines: dict[str, int] = {"project.id": 1}
311
+ for index, row in enumerate(reader):
312
+ line = index + 2
313
+ if all(not (value or "").strip() for value in row.values()):
314
+ continue
315
+ record: dict[str, Any] = {}
316
+ clean = {
317
+ key.strip(): (value or "").strip() for key, value in row.items() if key is not None
318
+ }
319
+ for key in ("id", "name", "unit", "kind", "sharing", "catalog"):
320
+ if clean.get(key):
321
+ record[key] = clean[key]
322
+ for key in ("qty", "priority"):
323
+ if clean.get(key):
324
+ try:
325
+ record[key] = int(clean[key])
326
+ except ValueError:
327
+ record[key] = clean[key] # let validation report it
328
+ if clean.get("estimate"):
329
+ record["estimate"] = {"amount": clean["estimate"]}
330
+ items.append(record)
331
+ position = len(items) - 1
332
+ lines[f"items[{position}]"] = line
333
+ for key in record:
334
+ lines[f"items[{position}].{key}"] = line
335
+ lines[f"items[{position}].estimate.amount"] = line
336
+ data = {
337
+ "version": MANIFEST_VERSION,
338
+ "project": {"id": project_id, "name": project_name or project_id},
339
+ "items": items,
340
+ }
341
+ return _to_domain(_validate(data, lines), lines)