quality-graph-github 0.1.10__py3-none-any.whl → 0.2.1__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.
qg_github/approvals.py CHANGED
@@ -10,6 +10,7 @@ from typing import TYPE_CHECKING, cast
10
10
 
11
11
  from qg_github.comments import DEFAULT_BOT_LOGIN
12
12
  from qg_github.github import GitHubPort, paged
13
+ from quality_graph_core.json_values import JSON
13
14
  from quality_graph_core.policy import ApprovalTarget
14
15
 
15
16
  if TYPE_CHECKING:
@@ -55,23 +56,23 @@ class ApprovalRecord:
55
56
  @classmethod
56
57
  def from_json(cls, value: str) -> ApprovalRecord:
57
58
  """Parse a record from untrusted marker JSON."""
58
- data = _object(cast("JsonValue", json.loads(value)), "approval record")
59
+ data = JSON.object(cast("JsonValue", json.loads(value)), "approval record")
59
60
  if data.get("version") != 0:
60
61
  message = "unsupported approval record version"
61
62
  raise ValueError(message)
62
- operation = _string(data.get("operation"), "approval operation")
63
+ operation = JSON.string(data.get("operation"), "approval operation")
63
64
  if operation not in {"add", "remove"}:
64
65
  message = f"unknown approval operation: {operation}"
65
66
  raise ValueError(message)
66
67
  targets = tuple(
67
- ApprovalTarget.from_key(_string(item, "approval target"))
68
- for item in _array(data.get("targets"), "approval targets")
68
+ ApprovalTarget.from_key(JSON.string(item, "approval target"))
69
+ for item in JSON.array(data.get("targets"), "approval targets")
69
70
  )
70
71
  return cls(
71
72
  operation == "add",
72
73
  targets,
73
- _string(data.get("actor"), "approval actor"),
74
- _integer(data.get("sourceCommentId"), "approval source comment id"),
74
+ JSON.string(data.get("actor"), "approval actor"),
75
+ JSON.integer(data.get("sourceCommentId"), "approval source comment id"),
75
76
  )
76
77
 
77
78
 
@@ -105,7 +106,7 @@ def approval_ledger(
105
106
  approvals: set[ApprovalTarget] = set()
106
107
  comments = sorted(
107
108
  paged(port, f"/issues/{number}/comments"),
108
- key=lambda item: _integer(item.get("id"), "approval comment id"),
109
+ key=lambda item: JSON.integer(item.get("id"), "approval comment id"),
109
110
  )
110
111
  for comment in comments:
111
112
  author = comment.get("user")
@@ -137,36 +138,8 @@ def append_approval_record(
137
138
  f"Quality Graph recorded that @{record.actor} {action} {targets}.\n\n"
138
139
  f"{record_marker(record)}"
139
140
  )
140
- response = _object(
141
+ response = JSON.object(
141
142
  port.request("POST", f"/issues/{number}/comments", {"body": body}),
142
143
  "approval comment",
143
144
  )
144
- return _integer(response.get("id"), "approval comment id")
145
-
146
-
147
- def _object(value: JsonValue, context: str) -> dict[str, JsonValue]:
148
- if not isinstance(value, dict):
149
- message = f"{context} must be an object"
150
- raise TypeError(message)
151
- return value
152
-
153
-
154
- def _array(value: JsonValue, context: str) -> list[JsonValue]:
155
- if not isinstance(value, list):
156
- message = f"{context} must be an array"
157
- raise TypeError(message)
158
- return value
159
-
160
-
161
- def _string(value: JsonValue, context: str) -> str:
162
- if not isinstance(value, str):
163
- message = f"{context} must be a string"
164
- raise TypeError(message)
165
- return value
166
-
167
-
168
- def _integer(value: JsonValue, context: str) -> int:
169
- if not isinstance(value, int) or isinstance(value, bool):
170
- message = f"{context} must be an integer"
171
- raise TypeError(message)
172
- return value
145
+ return JSON.integer(response.get("id"), "approval comment id")
qg_github/artifacts.py CHANGED
@@ -12,7 +12,8 @@ from pathlib import PurePosixPath
12
12
  from typing import TYPE_CHECKING
13
13
 
14
14
  from qg_github.github import GITHUB_PAGE_SIZE, GitHubPort
15
- from quality_graph_core.result import JsonValue, Result
15
+ from quality_graph_core.json_values import JsonValidator
16
+ from quality_graph_core.result import JsonValue, Provenance, Result, ResultStatus
16
17
 
17
18
  if TYPE_CHECKING:
18
19
  from collections.abc import Iterable, Mapping
@@ -30,6 +31,9 @@ class ArtifactError(ValueError):
30
31
  """Represent an invalid or incompatible result artifact."""
31
32
 
32
33
 
34
+ JSON = JsonValidator(ArtifactError)
35
+
36
+
33
37
  class DeclarationMismatchError(ArtifactError):
34
38
  """Identify a different declaration after workflow identity has been verified."""
35
39
 
@@ -46,6 +50,9 @@ class ArtifactExpectation:
46
50
  node_ids: frozenset[str]
47
51
  flow_id: str | None = None
48
52
  operation_ids: Mapping[str, str] = field(default_factory=dict)
53
+ run_attempt: int = 1
54
+ node_attempts: Mapping[str, int] = field(default_factory=dict)
55
+ node_conclusions: Mapping[str, str] = field(default_factory=dict)
49
56
 
50
57
 
51
58
  @dataclass(frozen=True)
@@ -63,19 +70,34 @@ def download_results(
63
70
  port: GitHubPort,
64
71
  expectation: ArtifactExpectation,
65
72
  ) -> dict[str, Result]:
66
- """Download the newest valid attempt for every expected node."""
67
- selected: dict[str, tuple[int, Result]] = {}
73
+ """Download results bound to the expected execution of each node."""
74
+ selected: dict[str, Result] = {}
75
+ seen: dict[tuple[str, int], Result] = {}
68
76
  for descriptor in _artifact_descriptors(port, expectation.workflow_run_id):
69
77
  if descriptor.node_id not in expectation.node_ids:
70
78
  message = f"artifact targets unknown graph node: {descriptor.node_id}"
79
+ raise DeclarationMismatchError(message)
80
+ if descriptor.attempt > expectation.run_attempt:
81
+ message = "result artifact attempt exceeds the latest workflow attempt"
71
82
  raise ArtifactError(message)
72
83
  archive = port.download(f"/actions/artifacts/{descriptor.id}/zip")
73
84
  result = _result_from_archive(archive, descriptor)
74
85
  _validate_result(result, descriptor, expectation)
75
- current = selected.get(descriptor.node_id)
76
- if current is None or descriptor.attempt >= current[0]:
77
- selected[descriptor.node_id] = (descriptor.attempt, result)
78
- return {node_id: result for node_id, (_, result) in selected.items()}
86
+ key = (descriptor.node_id, descriptor.attempt)
87
+ if key in seen and seen[key] != result:
88
+ message = f"conflicting result artifacts for node {key[0]} attempt {key[1]}"
89
+ raise ArtifactError(message)
90
+ seen[key] = result
91
+ expected_attempt = expectation.node_attempts.get(
92
+ descriptor.node_id, expectation.run_attempt
93
+ )
94
+ if descriptor.attempt == expected_attempt:
95
+ conclusion = expectation.node_conclusions.get(descriptor.node_id)
96
+ if result.status is ResultStatus.PASSED and conclusion not in {None, "success"}:
97
+ message = f"passed result contradicts workflow job state: {descriptor.node_id}"
98
+ raise ArtifactError(message)
99
+ selected[descriptor.node_id] = result
100
+ return selected
79
101
 
80
102
 
81
103
  def _artifact_descriptors(port: GitHubPort, run_id: int) -> tuple[ArtifactDescriptor, ...]:
@@ -83,10 +105,10 @@ def _artifact_descriptors(port: GitHubPort, run_id: int) -> tuple[ArtifactDescri
83
105
  page = 1
84
106
  while True:
85
107
  path = f"/actions/runs/{run_id}/artifacts?per_page={GITHUB_PAGE_SIZE}&page={page}"
86
- response = _object(port.request("GET", path), "workflow artifacts")
87
- artifacts = _array(response.get("artifacts"), "workflow artifacts")
108
+ response = JSON.object(port.request("GET", path), "workflow artifacts")
109
+ artifacts = JSON.array(response.get("artifacts"), "workflow artifacts")
88
110
  for value in artifacts:
89
- descriptor = _artifact_descriptor(_object(value, "workflow artifact"))
111
+ descriptor = _artifact_descriptor(JSON.object(value, "workflow artifact"))
90
112
  if descriptor is not None:
91
113
  descriptors.append(descriptor)
92
114
  if len(artifacts) < GITHUB_PAGE_SIZE:
@@ -95,19 +117,19 @@ def _artifact_descriptors(port: GitHubPort, run_id: int) -> tuple[ArtifactDescri
95
117
 
96
118
 
97
119
  def _artifact_descriptor(data: dict[str, JsonValue]) -> ArtifactDescriptor | None:
98
- name = _string(data.get("name"), "artifact name")
120
+ name = JSON.string(data.get("name"), "artifact name")
99
121
  match = ARTIFACT_NAME_RE.fullmatch(name)
100
122
  if match is None:
101
123
  return None
102
124
  if data.get("expired") is True:
103
125
  message = f"result artifact has expired: {name}"
104
126
  raise ArtifactError(message)
105
- artifact_id = _integer(data.get("id"), "artifact id")
106
- size = _integer(data.get("size_in_bytes"), "artifact size")
127
+ artifact_id = JSON.integer(data.get("id"), "artifact id")
128
+ size = JSON.integer(data.get("size_in_bytes"), "artifact size")
107
129
  if not 0 <= size <= MAX_ARTIFACT_ARCHIVE_BYTES:
108
130
  message = f"artifact exceeds the archive size limit: {name}"
109
131
  raise ArtifactError(message)
110
- digest = _string(data.get("digest"), "artifact digest")
132
+ digest = JSON.string(data.get("digest"), "artifact digest")
111
133
  if not digest.startswith("sha256:") or len(digest) != len("sha256:") + 64:
112
134
  message = f"artifact has an invalid digest: {name}"
113
135
  raise ArtifactError(message)
@@ -173,6 +195,9 @@ def _validate_result(
173
195
  expectation: ArtifactExpectation,
174
196
  ) -> None:
175
197
  provenance = result.provenance
198
+ if not isinstance(provenance, Provenance):
199
+ message = "GitHub artifact contains foreign provider provenance"
200
+ raise ArtifactError(message)
176
201
  expected = (
177
202
  expectation.repository,
178
203
  expectation.pull_request,
@@ -197,36 +222,13 @@ def _validate_result(
197
222
  message = f"artifact provenance does not match workflow metadata: {descriptor.id}"
198
223
  raise ArtifactError(message)
199
224
  if provenance.graph_digest != expectation.graph_digest:
200
- message = f"artifact provenance does not match workflow metadata: {descriptor.id}"
225
+ message = (
226
+ f"artifact {descriptor.id} provenance: graphDigest mismatch: "
227
+ f"expected {expectation.graph_digest}, "
228
+ f"execution reported {provenance.graph_digest}; "
229
+ "see https://quality-graph.xyz/security/#graph-evolution"
230
+ )
201
231
  raise DeclarationMismatchError(message)
202
232
  if observed[5:] != expected[5:]:
203
233
  message = f"artifact provenance does not match workflow metadata: {descriptor.id}"
204
234
  raise ArtifactError(message)
205
-
206
-
207
- def _object(value: JsonValue, context: str) -> dict[str, JsonValue]:
208
- if not isinstance(value, dict):
209
- message = f"{context} must be an object"
210
- raise ArtifactError(message)
211
- return value
212
-
213
-
214
- def _array(value: JsonValue, context: str) -> list[JsonValue]:
215
- if not isinstance(value, list):
216
- message = f"{context} must be an array"
217
- raise ArtifactError(message)
218
- return value
219
-
220
-
221
- def _string(value: JsonValue, context: str) -> str:
222
- if not isinstance(value, str):
223
- message = f"{context} must be a string"
224
- raise ArtifactError(message)
225
- return value
226
-
227
-
228
- def _integer(value: JsonValue, context: str) -> int:
229
- if not isinstance(value, int) or isinstance(value, bool):
230
- message = f"{context} must be an integer"
231
- raise ArtifactError(message)
232
- return value
qg_github/commands.py CHANGED
@@ -16,6 +16,7 @@ from qg_github.declarations import read_pr_results
16
16
  from qg_github.github import GITHUB_PAGE_SIZE, GitHubPort
17
17
  from qg_github.presentation import pr_presentation_graph
18
18
  from quality_graph_core.graph import Graph
19
+ from quality_graph_core.json_values import JSON
19
20
  from quality_graph_core.policy import ApprovalTarget, effective_graph
20
21
  from quality_graph_core.result import ControlKind, JsonValue
21
22
 
@@ -103,16 +104,16 @@ def command_request(
103
104
  bot_logins: tuple[str, ...] = (DEFAULT_BOT_LOGIN,),
104
105
  ) -> CommandRequest | None:
105
106
  """Extract a direct command or one canonical checkbox transition."""
106
- event = _object(event_value, "issue comment event")
107
- comment = _object(event.get("comment"), "issue comment")
108
- comment_id = _integer(comment.get("id"), "comment id")
109
- body = _string(comment.get("body"), "comment body").strip()
110
- issue = _object(event.get("issue"), "issue")
111
- number = _optional_integer(issue.get("number"), "issue number")
107
+ event = JSON.object(event_value, "issue comment event")
108
+ comment = JSON.object(event.get("comment"), "issue comment")
109
+ comment_id = JSON.integer(comment.get("id"), "comment id")
110
+ body = JSON.string(comment.get("body"), "comment body").strip()
111
+ issue = JSON.object(event.get("issue"), "issue")
112
+ number = JSON.optional_integer(issue.get("number"), "issue number")
112
113
  pull_request = number if issue.get("pull_request") is not None else None
113
114
  author = comment.get("user")
114
115
  author_login = (
115
- _optional_string(author.get("login"), "comment author")
116
+ JSON.optional_string(author.get("login"), "comment author")
116
117
  if isinstance(author, dict)
117
118
  else None
118
119
  )
@@ -120,9 +121,9 @@ def command_request(
120
121
  return CommandRequest(comment_id, body, author_login, pull_request)
121
122
  if event.get("action") != "edited" or author_login not in bot_logins:
122
123
  return None
123
- changes = _object(event.get("changes"), "comment changes")
124
- body_change = _object(changes.get("body"), "comment body change")
125
- previous = _string(body_change.get("from"), "previous comment body")
124
+ changes = JSON.object(event.get("changes"), "comment changes")
125
+ body_change = JSON.object(changes.get("body"), "comment body change")
126
+ previous = JSON.string(body_change.get("from"), "previous comment body")
126
127
  before = control_states(previous)
127
128
  after = control_states(body)
128
129
  changed = [marker for marker in before.keys() & after.keys() if before[marker] != after[marker]]
@@ -132,8 +133,8 @@ def command_request(
132
133
  if commands is None:
133
134
  return None
134
135
  apply, reverse = commands
135
- sender = _object(event.get("sender"), "event sender")
136
- actor = _optional_string(sender.get("login"), "event sender login")
136
+ sender = JSON.object(event.get("sender"), "event sender")
137
+ actor = JSON.optional_string(sender.get("login"), "event sender login")
137
138
  selected = apply if after[changed[0]] else reverse
138
139
  return CommandRequest(comment_id, selected, actor, pull_request, previous)
139
140
 
@@ -185,9 +186,9 @@ def dispatch_pr_command(port: GitHubPort, event_value: JsonValue) -> CommandOutc
185
186
  request = command_request(event_value)
186
187
  if request is None or request.pull_request is None:
187
188
  return CommandOutcome(handled=False)
188
- pull = _object(port.request("GET", f"/pulls/{request.pull_request}"), "pull request")
189
- base = _object(pull.get("base"), "pull request base")
190
- base_sha = _string(base.get("sha"), "pull request base SHA")
189
+ pull = JSON.object(port.request("GET", f"/pulls/{request.pull_request}"), "pull request")
190
+ base = JSON.object(pull.get("base"), "pull request base")
191
+ base_sha = JSON.string(base.get("sha"), "pull request base SHA")
191
192
  graph = Graph.from_yaml(_repository_file(port, "qg.yaml", base_sha))
192
193
  if pr_presentation_graph(graph) is None:
193
194
  return CommandOutcome(handled=False)
@@ -196,11 +197,11 @@ def dispatch_pr_command(port: GitHubPort, event_value: JsonValue) -> CommandOutc
196
197
 
197
198
  # pragma: no mutate start
198
199
  def _command_context(port: GitHubPort, number: int) -> CommandContext:
199
- pull = _object(port.request("GET", f"/pulls/{number}"), "pull request")
200
- head = _object(pull.get("head"), "pull request head")
201
- base = _object(pull.get("base"), "pull request base")
202
- head_sha = _string(head.get("sha"), "pull request head SHA")
203
- base_sha = _string(base.get("sha"), "pull request base SHA")
200
+ pull = JSON.object(port.request("GET", f"/pulls/{number}"), "pull request")
201
+ head = JSON.object(pull.get("head"), "pull request head")
202
+ base = JSON.object(pull.get("base"), "pull request base")
203
+ head_sha = JSON.string(head.get("sha"), "pull request head SHA")
204
+ base_sha = JSON.string(base.get("sha"), "pull request base SHA")
204
205
  graph = Graph.from_yaml(_repository_file(port, "qg.yaml", base_sha))
205
206
  compiled = compile_graph(graph)
206
207
  projected = pr_presentation_graph(graph)
@@ -209,8 +210,8 @@ def _command_context(port: GitHubPort, number: int) -> CommandContext:
209
210
  raise ValueError(message)
210
211
  graph = projected
211
212
  run = _latest_run(port, number)
212
- run_id = _integer(run.get("id"), "workflow run id")
213
- attempt = _integer(run.get("run_attempt", 1), "workflow run attempt")
213
+ run_id = JSON.integer(run.get("id"), "workflow run id")
214
+ attempt = JSON.integer(run.get("run_attempt", 1), "workflow run attempt")
214
215
  expectation = ArtifactExpectation(
215
216
  port.repository,
216
217
  number,
@@ -220,11 +221,9 @@ def _command_context(port: GitHubPort, number: int) -> CommandContext:
220
221
  frozenset(node.id for node in graph.nodes),
221
222
  graph.flow_id,
222
223
  {node.id: node.operation_id for node in graph.nodes if node.operation_id is not None},
224
+ run_attempt=attempt,
223
225
  )
224
226
  graph, results = read_pr_results(port, graph, expectation)
225
- if any(result.provenance.run_attempt > attempt for result in results.values()):
226
- message = "result artifact attempt exceeds the latest workflow attempt"
227
- raise ValueError(message)
228
227
  state = effective_graph(graph, results, set())
229
228
  return CommandContext(graph, run_id, state.targets)
230
229
 
@@ -237,15 +236,15 @@ def _latest_run(port: GitHubPort, number: int) -> dict[str, JsonValue]:
237
236
  "/actions/workflows/quality-graph.yml/runs?event=pull_request"
238
237
  f"&per_page={GITHUB_PAGE_SIZE}&page={page}"
239
238
  )
240
- response = _object(port.request("GET", path), "workflow runs")
241
- values = _array(response.get("workflow_runs", []), "workflow runs")
239
+ response = JSON.object(port.request("GET", path), "workflow runs")
240
+ values = JSON.array(response.get("workflow_runs", []), "workflow runs")
242
241
  runs.extend(
243
242
  run
244
243
  for value in values
245
- for run in (_object(value, "workflow run"),)
244
+ for run in (JSON.object(value, "workflow run"),)
246
245
  if any(
247
- _object(pull, "workflow pull request").get("number") == number
248
- for pull in _array(run.get("pull_requests", []), "workflow pull requests")
246
+ JSON.object(pull, "workflow pull request").get("number") == number
247
+ for pull in JSON.array(run.get("pull_requests", []), "workflow pull requests")
249
248
  )
250
249
  )
251
250
  if len(values) < GITHUB_PAGE_SIZE:
@@ -254,7 +253,7 @@ def _latest_run(port: GitHubPort, number: int) -> dict[str, JsonValue]:
254
253
  if not runs:
255
254
  message = f"no Quality Graph workflow run found for PR #{number}"
256
255
  raise ValueError(message)
257
- return max(runs, key=lambda run: _integer(run.get("id"), "workflow run id"))
256
+ return max(runs, key=lambda run: JSON.integer(run.get("id"), "workflow run id"))
258
257
 
259
258
 
260
259
  # pragma: no mutate end
@@ -264,8 +263,8 @@ def _authorized(port: GitHubPort, actor: str, roles: tuple[str, ...]) -> bool:
264
263
  response = port.request("GET", f"/collaborators/{login}/permission")
265
264
  except RuntimeError:
266
265
  return False
267
- data = _object(response, "collaborator permission")
268
- permission = _optional_string(data.get("permission"), "collaborator permission")
266
+ data = JSON.object(response, "collaborator permission")
267
+ permission = JSON.optional_string(data.get("permission"), "collaborator permission")
269
268
  return permission in roles
270
269
 
271
270
 
@@ -294,11 +293,11 @@ def _command_targets(
294
293
  def _repository_file(port: GitHubPort, path: str, ref: str) -> str:
295
294
  encoded_path = urllib.parse.quote(path, safe="")
296
295
  encoded_ref = urllib.parse.quote(ref, safe="")
297
- response = _object(
296
+ response = JSON.object(
298
297
  port.request("GET", f"/contents/{encoded_path}?ref={encoded_ref}"),
299
298
  "repository file",
300
299
  )
301
- content = _string(response.get("content"), "repository file content")
300
+ content = JSON.string(response.get("content"), "repository file content")
302
301
  return base64.b64decode(content.replace("\n", ""), validate=True).decode()
303
302
 
304
303
 
@@ -324,40 +323,4 @@ def _help_body() -> str:
324
323
  - `/qg remove-ignore-file <path>`"""
325
324
 
326
325
 
327
- def _object(value: JsonValue, context: str) -> dict[str, JsonValue]:
328
- if not isinstance(value, dict):
329
- message = f"{context} must be an object"
330
- raise TypeError(message)
331
- return value
332
-
333
-
334
- def _array(value: JsonValue, context: str) -> list[JsonValue]:
335
- if not isinstance(value, list):
336
- message = f"{context} must be an array"
337
- raise TypeError(message)
338
- return value
339
-
340
-
341
- def _string(value: JsonValue, context: str) -> str:
342
- if not isinstance(value, str):
343
- message = f"{context} must be a string"
344
- raise TypeError(message)
345
- return value
346
-
347
-
348
- def _optional_string(value: JsonValue, context: str) -> str | None:
349
- return None if value is None else _string(value, context)
350
-
351
-
352
- def _integer(value: JsonValue, context: str) -> int:
353
- if not isinstance(value, int) or isinstance(value, bool):
354
- message = f"{context} must be an integer"
355
- raise TypeError(message)
356
- return value
357
-
358
-
359
- def _optional_integer(value: JsonValue, context: str) -> int | None:
360
- return None if value is None else _integer(value, context)
361
-
362
-
363
326
  # pragma: no mutate end
qg_github/comments.py CHANGED
@@ -6,11 +6,11 @@ from dataclasses import dataclass
6
6
  from typing import TYPE_CHECKING
7
7
 
8
8
  from qg_github.github import GitHubPort, paged
9
+ from quality_graph_core.json_values import JSON
9
10
 
10
11
  if TYPE_CHECKING:
11
12
  from collections.abc import Iterable
12
13
 
13
- from quality_graph_core.result import JsonValue
14
14
 
15
15
  GITHUB_COMMENT_BODY_LIMIT = 65_536
16
16
  DEFAULT_BOT_LOGIN = "github-actions[bot]"
@@ -87,7 +87,7 @@ def upsert_managed_comment(
87
87
  return existing
88
88
  else:
89
89
  response = port.request("PATCH", f"/issues/comments/{existing.id}", {"body": rendered})
90
- data = _object(response, "managed comment")
90
+ data = JSON.object(response, "managed comment")
91
91
  comment_id = data.get("id")
92
92
  response_body = data.get("body")
93
93
  if not isinstance(comment_id, int) or isinstance(comment_id, bool):
@@ -97,10 +97,3 @@ def upsert_managed_comment(
97
97
  message = "managed comment response has no body"
98
98
  raise TypeError(message)
99
99
  return ManagedComment(comment_id, response_body)
100
-
101
-
102
- def _object(value: JsonValue, context: str) -> dict[str, JsonValue]:
103
- if not isinstance(value, dict):
104
- message = f"{context} must be an object"
105
- raise TypeError(message)
106
- return value