codeplain 0.3.13.dev47__py3-none-any.whl → 0.3.13.dev48__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.
plain_file.py CHANGED
@@ -1,871 +1,3 @@
1
- import io
2
- import os
3
- from dataclasses import dataclass
4
- from pathlib import Path
5
- from typing import Iterable, Sequence, cast
6
- from urllib.parse import urlparse
1
+ """Compatibility shim: the parser now lives in the ``plain-parser`` package."""
7
2
 
8
- import frontmatter
9
- import mistletoe
10
- import mistletoe.block_token
11
- from liquid2 import DictLoader, Environment
12
- from mistletoe.block_token import List, Paragraph, Quote
13
- from mistletoe.markdown_renderer import Fragment, MarkdownRenderer
14
- from mistletoe.span_token import Emphasis, Link, RawText, SpanToken, Strong
15
- from mistletoe.token import Token
16
- from mistletoe.utils import traverse
17
-
18
- import concept_utils
19
- import file_utils
20
- import plain_spec
21
- from plain2code_exceptions import (
22
- ImportedModuleWithFunctionalitiesError,
23
- MissingFunctionalitiesError,
24
- ModuleDoesNotExistError,
25
- PlainSyntaxError,
26
- UnsupportedBase64Content,
27
- )
28
- from plain2code_nodes import Plain2CodeIncludeTag, Plain2CodeLoaderMixin
29
- from plain2code_utils import find_large_base64_blob
30
-
31
- RESOURCE_MARKER = "[resource]"
32
-
33
- IMPORT_DIRECTIVE = "import"
34
- REQUIRES_DIRECTIVE = "requires"
35
- REQUIRED_CONCEPTS_DIRECTIVE = "required_concepts"
36
- EXPORTED_CONCEPTS_DIRECTIVE = "exported_concepts"
37
-
38
- PLAIN_SOURCE_FILE_EXTENSION = ".plain"
39
-
40
- PLAIN_SOURCE_TEMPLATE = {
41
- plain_spec.DEFINITIONS: None,
42
- plain_spec.NON_FUNCTIONAL_REQUIREMENTS: None,
43
- plain_spec.TEST_REQUIREMENTS: None,
44
- }
45
-
46
-
47
- @dataclass
48
- class PlainFileParseResult:
49
- plain_source: dict
50
- plain_source_obj: frontmatter.Post
51
- required_modules: list[str]
52
- required_concepts: list[str]
53
-
54
-
55
- class PlainRenderer(MarkdownRenderer):
56
- def render_link(self, token: Link) -> Iterable[Fragment]:
57
- yield from self.embed_span(
58
- Fragment(f"`{RESOURCE_MARKER}"),
59
- cast("Iterable[SpanToken]", token.children),
60
- Fragment("`"),
61
- )
62
-
63
-
64
- def get_filename_from_module_name(module_name: str) -> str:
65
- return f"{module_name}{PLAIN_SOURCE_FILE_EXTENSION}"
66
-
67
-
68
- def get_module_name_from_filename(filename: str) -> str:
69
- return filename.replace(PLAIN_SOURCE_FILE_EXTENSION, "")
70
-
71
-
72
- def remove_quotes(token):
73
- # If the token has no children, there's nothing to remove.
74
- if not hasattr(token, "children") or token.children is None:
75
- return
76
-
77
- # Convert children to a list for easy filtering.
78
- children_list = list(token.children)
79
-
80
- # Build a filtered list that excludes Quote tokens.
81
- new_children = []
82
- for child in children_list:
83
- if not isinstance(child, Quote):
84
- # Recursively remove quotes in any nested children.
85
- remove_quotes(child)
86
- new_children.append(child)
87
-
88
- # Convert the filtered list back to a tuple (or a list, if you prefer).
89
- # Mistletoe tokens often expect a tuple, so tuple is safest.
90
- token.children = tuple(new_children)
91
-
92
-
93
- def check_section_for_linked_resources(section, template_dirs):
94
- linked_resources = []
95
- for link in traverse(section, klass=Link):
96
- parsed_url = urlparse(link.node.target)
97
- if parsed_url.scheme != "" or os.path.isabs(link.node.target):
98
- raise PlainSyntaxError(
99
- f"Plain syntax error: Only relative links are allowed (text: {link.node.children[0].content}, target: {link.node.target})."
100
- )
101
-
102
- resolved_target = file_utils.resolve_linked_resource(template_dirs, link.node.target)
103
- if resolved_target is None:
104
- searched_dirs = "\n".join(f" {position}. {dir}" for position, dir in enumerate(template_dirs, start=1))
105
- raise PlainSyntaxError(
106
- f"Plain syntax error: Link {link.node.target} does not exist. "
107
- f"Linked resources are looked up relative to the following directories "
108
- f"(highest to lowest precedence):\n{searched_dirs}"
109
- )
110
-
111
- if not os.path.isfile(resolved_target):
112
- raise PlainSyntaxError(
113
- f"Plain syntax error: Link {link.node.target} must be a file (resolved to {resolved_target})."
114
- )
115
-
116
- if len(link.node.children) != 1:
117
- raise PlainSyntaxError(f"Plain syntax error: Link must have text specified (link: {link.node.target}).")
118
-
119
- linked_resource_file_extension = os.path.splitext(os.path.basename(link.node.target))[1]
120
- if linked_resource_file_extension == ".plain":
121
- raise PlainSyntaxError(
122
- f"Referenced resource '{link.node.target}' is a .plain file. "
123
- f"Referencing .plain files through Linked Resources is not supported. "
124
- "Please use the import section to include definitions or implementation/test requirements from another module."
125
- )
126
-
127
- linked_resources.append({"text": link.node.children[0].content, "target": link.node.target})
128
-
129
- if linked_resources:
130
- section.linked_resources = linked_resources
131
-
132
-
133
- def check_for_linked_resources(plain_source, template_dirs):
134
- for specification_heading in plain_spec.ALLOWED_SPECIFICATION_HEADINGS:
135
- if specification_heading in plain_source and hasattr(plain_source[specification_heading], "children"):
136
- for requirement in plain_source[specification_heading].children:
137
- check_section_for_linked_resources(requirement, template_dirs)
138
-
139
- if hasattr(requirement, plain_spec.ACCEPTANCE_TESTS):
140
- for acceptance_test in requirement.acceptance_tests:
141
- check_section_for_linked_resources(acceptance_test, template_dirs)
142
-
143
-
144
- def process_section_code_variables(section, code_variables):
145
- if "markdown" not in section:
146
- return
147
-
148
- code_variables_array = []
149
- for key, value in code_variables.items():
150
- if key not in section["markdown"]:
151
- continue
152
-
153
- variable_name = next(iter(value))
154
- section["markdown"] = section["markdown"].replace(key, f"{{{{ {variable_name} }}}}")
155
-
156
- code_variables_array.append({"name": variable_name, "value": value[variable_name]})
157
-
158
- if code_variables_array:
159
- section["code_variables"] = code_variables_array
160
-
161
-
162
- def process_code_variables(plain_source, code_variables):
163
- for specification_heading in plain_spec.ALLOWED_SPECIFICATION_HEADINGS:
164
- if specification_heading in plain_source:
165
- for requirement in plain_source[specification_heading]:
166
- process_section_code_variables(requirement, code_variables)
167
-
168
-
169
- def has_functional_specs_section(plain_source) -> bool:
170
- """Whether the module declares a ***functional specs*** section (even if it is empty)."""
171
- return plain_spec.FUNCTIONAL_REQUIREMENTS in plain_source
172
-
173
-
174
- def count_functionalities(plain_source) -> int:
175
- """Number of functionalities under the ***functional specs*** section (0 if absent or empty)."""
176
- section = plain_source.get(plain_spec.FUNCTIONAL_REQUIREMENTS)
177
- return len(section.children) if section is not None else 0
178
-
179
-
180
- def validate_functionalities_have_implementation_reqs(plain_source, module_name, has_requires=False) -> None:
181
- """Raise if the module has functionalities but no implementation reqs are specified.
182
-
183
- ``has_requires`` indicates whether the module depends on another module via ``requires``.
184
- Unlike ``import``, ``requires`` does not inherit implementation reqs, so a hint is added to
185
- steer users who expected inheritance.
186
- """
187
- implementation_reqs = plain_source[plain_spec.NON_FUNCTIONAL_REQUIREMENTS]
188
- has_implementation_reqs = (
189
- implementation_reqs is not None
190
- and hasattr(implementation_reqs, "children")
191
- and len(implementation_reqs.children) > 0
192
- )
193
- if not has_implementation_reqs:
194
- message = (
195
- f"Plain syntax error: Module '{module_name}' defines functionalities but specifies no "
196
- f"{plain_spec.NON_FUNCTIONAL_REQUIREMENTS}. At least one implementation req is required."
197
- )
198
- if has_requires:
199
- message += (
200
- " Implementation reqs are not inherited through 'requires' — "
201
- "add them to this module, or 'import' a module that provides them."
202
- )
203
- raise PlainSyntaxError(message)
204
-
205
-
206
- def _is_acceptance_test_heading(token) -> tuple[bool, str | None]:
207
- """
208
- Check if token is an 'Acceptance test:' heading.
209
-
210
- This method is going to evaluate to True when:
211
-
212
- - The token is a Paragraph
213
- - The paragraph has 1 child
214
- - The child is an Emphasis (*** ... *** marker)
215
- - The Emphasis has 1 child (the raw text content)
216
- - The child of the Emphasis is a Strong
217
- - The Strong has 1 child
218
- - The child of the Strong is a RawText
219
- - The RawText content is equal to "Acceptance test:"
220
-
221
- This is expected structure for the acceptance test heading.
222
- """
223
- if not isinstance(token, Paragraph):
224
- return False, None
225
-
226
- # Check for the specific structure, descending one level at a time. mistletoe types
227
- # ``children`` as ``Optional[Iterable[Token]]``, so cast each level to a concrete
228
- # sequence before indexing/len.
229
- children = cast("Sequence[Token]", token.children)
230
- if len(children) != 1 or not isinstance(children[0], Emphasis):
231
- return False, None
232
-
233
- emphasis_children = cast("Sequence[Token]", children[0].children)
234
- if len(emphasis_children) != 1 or not isinstance(emphasis_children[0], Strong):
235
- return False, None
236
-
237
- strong_children = cast("Sequence[Token]", emphasis_children[0].children)
238
- if len(strong_children) != 1 or not isinstance(strong_children[0], RawText):
239
- return False, None
240
-
241
- # Check the actual text content
242
- content = strong_children[0].content.strip()
243
- if content == plain_spec.ACCEPTANCE_TEST_HEADING:
244
- return True, None
245
- problem = f"Syntax error at line {token.line_number}: Invalid acceptance test heading (`{content}`). Expected: `{plain_spec.ACCEPTANCE_TEST_HEADING}.`"
246
- return False, problem
247
-
248
-
249
- def _find_acceptance_test_heading(token):
250
- """
251
- Recursively search a token tree for an `acceptance tests` heading.
252
-
253
- Returns the heading token if one is found anywhere in the subtree, otherwise None.
254
- Used to detect acceptance tests nested under sections other than functional specs.
255
- """
256
- is_acceptance_test_heading, _ = _is_acceptance_test_heading(token)
257
- if is_acceptance_test_heading:
258
- return token
259
-
260
- if getattr(token, "children", None):
261
- for child in token.children:
262
- found = _find_acceptance_test_heading(child)
263
- if found is not None:
264
- return found
265
-
266
- return None
267
-
268
-
269
- def _process_single_acceptance_test_requirement(functional_requirement: mistletoe.block_token.ListItem):
270
- """
271
- Process a single functionality to extract acceptance tests.
272
-
273
- Expected functional_requirement properties:
274
- - Is a list item
275
- - If acceptance tests are specified, it has 3 children:
276
- - List item element with functionality instructions/text
277
- - Paragraph with `***Acceptance test:***` heading
278
- - List of acceptance tests
279
- - If acceptance tests are not specified, it has 1 child:
280
- - List item element with functionality instructions/text
281
- """
282
- new_children: list = []
283
- functional_requirement_children = iter(functional_requirement.children or ())
284
- acceptance_tests_found_already = False
285
-
286
- for functional_requirement_child in functional_requirement_children:
287
- is_acceptance_test_heading, acceptance_test_heading_problem = _is_acceptance_test_heading(
288
- functional_requirement_child
289
- )
290
- if acceptance_test_heading_problem:
291
- # Handle the case when the heading is not valid. This case includes cases such as:
292
- # - Writing `acceptance test` instead of `acceptance tests` (or any other syntax diffs).
293
- # - Instead of specifying `acceptance tests` below the functionality, creator of the plain file
294
- # might have specified some other building block (e.g. `implementation reqs`)
295
- raise PlainSyntaxError(f"Plain syntax error: {acceptance_test_heading_problem}")
296
-
297
- if is_acceptance_test_heading:
298
- if acceptance_tests_found_already:
299
- # Handle edge case of duplicated ***acceptance tests*** heading
300
- raise PlainSyntaxError(
301
- f"Plain syntax error: Syntax error at line {functional_requirement_child.line_number}: Duplicate 'acceptance tests' heading found within the same functionality. Only one block of acceptance tests is allowed per functionality."
302
- )
303
-
304
- try:
305
- # If there is an acceptance test heading, the next token should be a list, with children being list items
306
- next_token = next(functional_requirement_children)
307
- if isinstance(next_token, List):
308
- # Found valid acceptance test list -> Assign it property acceptance_tests and append all list items to it
309
- if not hasattr(functional_requirement, plain_spec.ACCEPTANCE_TESTS):
310
- functional_requirement.acceptance_tests = []
311
- for list_item in next_token.children:
312
- functional_requirement.acceptance_tests.append(list_item)
313
- acceptance_tests_found_already = True
314
- else:
315
- # Not followed by a list, keep both tokens
316
- new_children.append(functional_requirement_child)
317
- new_children.append(next_token)
318
- except StopIteration:
319
- # No next token, keep this one
320
- new_children.append(functional_requirement_child)
321
- else:
322
- # Regular token, keep it
323
- new_children.append(functional_requirement_child)
324
-
325
- # Assign the children property to all the children of the functionality from previous, with exception
326
- # of those we parsed as acceptance tests
327
- container_type = cast(type, type(functional_requirement.children))
328
- functional_requirement.children = container_type(new_children)
329
-
330
-
331
- def process_acceptance_tests(plain_source):
332
- # Early returns for cases without functionalities
333
- if plain_spec.FUNCTIONAL_REQUIREMENTS not in plain_source:
334
- return
335
- frs = plain_source[plain_spec.FUNCTIONAL_REQUIREMENTS]
336
- if not hasattr(frs, "children"):
337
- return
338
-
339
- # Process each functionality
340
- for functional_requirement in frs.children:
341
- if not hasattr(functional_requirement, "children"):
342
- continue
343
-
344
- # Process each requirement to extract acceptance tests
345
- _process_single_acceptance_test_requirement(functional_requirement)
346
-
347
-
348
- def get_raw_text(token):
349
- if isinstance(token, RawText):
350
- yield token.content
351
- elif hasattr(token, "children"):
352
- if token.children is None:
353
- return
354
- for child in token.children:
355
- yield from get_raw_text(child)
356
- elif hasattr(token, "content"):
357
- yield token.content
358
- else:
359
- raise Exception(f"Unknown token type: {type(token)}")
360
-
361
-
362
- def marshall_plain_source(input_plain_source):
363
- plain_source = {}
364
- with PlainRenderer() as renderer:
365
- if "ID" in input_plain_source:
366
- plain_source["ID"] = input_plain_source["ID"]
367
-
368
- if "Heading" in input_plain_source:
369
- plain_source["Heading"] = input_plain_source["Heading"]
370
-
371
- for specification_heading in plain_spec.ALLOWED_SPECIFICATION_HEADINGS:
372
- if specification_heading in input_plain_source and hasattr(
373
- input_plain_source[specification_heading], "children"
374
- ):
375
- list_of_requirements = []
376
- for requirement in input_plain_source[specification_heading].children:
377
- requirement_section = {"markdown": renderer.render(requirement).strip()}
378
- if hasattr(requirement, "linked_resources"):
379
- requirement_section["linked_resources"] = requirement.linked_resources
380
-
381
- if hasattr(requirement, plain_spec.ACCEPTANCE_TESTS):
382
- requirement_section[plain_spec.ACCEPTANCE_TESTS] = []
383
- for acceptance_test in requirement.acceptance_tests:
384
- acceptance_test_section = {"markdown": renderer.render(acceptance_test).strip()}
385
- if hasattr(acceptance_test, "linked_resources"):
386
- acceptance_test_section["linked_resources"] = acceptance_test.linked_resources
387
- requirement_section[plain_spec.ACCEPTANCE_TESTS].append(acceptance_test_section)
388
-
389
- list_of_requirements.append(requirement_section)
390
-
391
- plain_source[specification_heading] = list_of_requirements
392
-
393
- return plain_source
394
-
395
-
396
- class Plain2CodeDictLoader(Plain2CodeLoaderMixin, DictLoader):
397
- pass
398
-
399
-
400
- def render_plain_source(plain_source, loaded_templates, code_variables):
401
- env = Environment(loader=Plain2CodeDictLoader(loaded_templates))
402
- env.tags["include"] = Plain2CodeIncludeTag(env)
403
- env.filters["code_variable"] = plain_spec.code_variable_liquid_filter
404
- env.filters["prohibited_chars"] = plain_spec.prohibited_chars_liquid_filter
405
-
406
- template = env.from_string(plain_source)
407
-
408
- return template.render(code_variables=code_variables)
409
-
410
-
411
- def process_imports(
412
- plain_source: dict,
413
- imports: list[str],
414
- code_variables: dict,
415
- template_dirs: list[str],
416
- imported_modules: list[str],
417
- modules_trace: list[str],
418
- ) -> list[str]:
419
- required_concepts = list[str]()
420
- for module_name in imports:
421
- if module_name in modules_trace:
422
- raise PlainSyntaxError(f"Plain syntax error: Circular import detected: {module_name}.")
423
-
424
- if module_name in imported_modules:
425
- continue
426
-
427
- plain_file_parse_result = parse_plain_file(
428
- module_name, code_variables, template_dirs, imported_modules, modules_trace
429
- )
430
-
431
- if has_functional_specs_section(plain_file_parse_result.plain_source):
432
- raise ImportedModuleWithFunctionalitiesError(
433
- f"Module '{module_name}' is imported but contains functional specs. "
434
- f"Imported modules may only provide definitions, implementation reqs, and test reqs — "
435
- f"use 'requires' instead of 'import' if this module's functionalities should be built on."
436
- )
437
-
438
- for specification_heading in plain_file_parse_result.plain_source:
439
- if specification_heading not in plain_spec.ALLOWED_IMPORT_SPECIFICATION_HEADINGS:
440
- raise PlainSyntaxError(
441
- f"Plain syntax error: Invalid specification heading (`{specification_heading}`). Allowed headings: {', '.join(plain_spec.ALLOWED_IMPORT_SPECIFICATION_HEADINGS)}"
442
- )
443
-
444
- if plain_source[specification_heading] is None:
445
- plain_source[specification_heading] = plain_file_parse_result.plain_source[specification_heading]
446
- elif plain_file_parse_result.plain_source[specification_heading] is not None:
447
- plain_source[specification_heading].children.extend(
448
- plain_file_parse_result.plain_source[specification_heading].children
449
- )
450
-
451
- if REQUIRED_CONCEPTS_DIRECTIVE in plain_file_parse_result.plain_source_obj.metadata:
452
- for item in plain_file_parse_result.plain_source_obj.metadata[REQUIRED_CONCEPTS_DIRECTIVE]:
453
- assert isinstance(
454
- item, str
455
- ), f"Syntax error: Invalid {REQUIRED_CONCEPTS_DIRECTIVE} metadata. Expected a string."
456
- new_concepts, _ = concept_utils.extract_concepts_from_definition(item)
457
- required_concepts.extend(new_concepts)
458
-
459
- required_concepts.extend(plain_file_parse_result.required_concepts)
460
-
461
- imported_modules.append(module_name)
462
-
463
- return required_concepts
464
-
465
-
466
- def normalize_line_endings(plain_source_text: str) -> str:
467
- return plain_source_text.replace("\r\n", "\n").replace("\r", "\n")
468
-
469
-
470
- def restore_stripped_lines(plain_source_text: str, content: str) -> str:
471
- stripped_source = plain_source_text.rstrip()
472
- if not content or not stripped_source.endswith(content):
473
- return content
474
-
475
- stripped_line_count = stripped_source[: len(stripped_source) - len(content)].count("\n")
476
- return "\n" * stripped_line_count + content
477
-
478
-
479
- def read_plain_source_metadata(plain_source_text):
480
- try:
481
- plain_source_obj = frontmatter.loads(plain_source_text)
482
- except Exception as e:
483
- raise PlainSyntaxError(f"Plain syntax error: Invalid frontmatter: {e}")
484
-
485
- for directive in [EXPORTED_CONCEPTS_DIRECTIVE, REQUIRED_CONCEPTS_DIRECTIVE]:
486
- if directive in plain_source_obj.metadata:
487
- assert isinstance(
488
- plain_source_obj.metadata[directive], list
489
- ), f"Syntax error: Invalid {directive} metadata. Expected a list."
490
- prepared_metadata = []
491
- for item in plain_source_obj.metadata[directive]:
492
- if isinstance(item, dict):
493
- for k, v in item.items():
494
- prepared_metadata.append(f"- {k}: {v}")
495
- elif isinstance(item, str):
496
- prepared_metadata.append(f"- {item}")
497
- else:
498
- raise PlainSyntaxError(
499
- f"Plain syntax error: Invalid {directive} metadata. Expected a dictionary or a string."
500
- )
501
-
502
- plain_source_obj.metadata[directive] = prepared_metadata
503
-
504
- return plain_source_obj
505
-
506
-
507
- def parse_plain_source( # noqa: C901
508
- plain_source_text: str,
509
- code_variables: dict,
510
- template_dirs: list[str],
511
- imported_modules: list[str],
512
- modules_trace: list[str],
513
- ) -> PlainFileParseResult:
514
- plain_source_text = normalize_line_endings(plain_source_text)
515
-
516
- plain_source_obj = read_plain_source_metadata(plain_source_text)
517
-
518
- plain_source = PLAIN_SOURCE_TEMPLATE.copy()
519
-
520
- if IMPORT_DIRECTIVE in plain_source_obj.metadata:
521
- required_concepts = process_imports(
522
- plain_source,
523
- plain_source_obj.metadata[IMPORT_DIRECTIVE],
524
- code_variables,
525
- template_dirs,
526
- imported_modules,
527
- modules_trace,
528
- )
529
- else:
530
- required_concepts = list[str]()
531
-
532
- [_, loaded_templates] = file_utils.get_loaded_templates(template_dirs, plain_source_text)
533
-
534
- plain_source_content = restore_stripped_lines(plain_source_text, plain_source_obj.content)
535
-
536
- plain_source_full_text = render_plain_source(plain_source_content, loaded_templates, code_variables)
537
-
538
- plain_file = mistletoe.Document(io.StringIO(plain_source_full_text))
539
-
540
- remove_quotes(plain_file)
541
-
542
- current_specification_heading = None
543
- processed_specification_headings = set[str]()
544
- for token in plain_file.children:
545
- token_text = "".join(get_raw_text(token)).strip()
546
- if isinstance(token, Paragraph):
547
- paragraph_children = cast("Sequence[Token]", token.children)
548
- emphasis_children = (
549
- cast("Sequence[Token]", paragraph_children[0].children)
550
- if paragraph_children and isinstance(paragraph_children[0], Emphasis)
551
- else ()
552
- )
553
- if not (
554
- len(paragraph_children) == 1
555
- and isinstance(paragraph_children[0], Emphasis)
556
- and len(emphasis_children) == 1
557
- and isinstance(emphasis_children[0], Strong)
558
- ):
559
-
560
- raise PlainSyntaxError(
561
- f"Plain syntax error: Syntax error at line {token.line_number}: Invalid specification (`{token_text}`)"
562
- )
563
-
564
- strong_children = cast("Sequence[Token]", emphasis_children[0].children)
565
- specification_heading = cast(RawText, strong_children[0]).content
566
-
567
- if specification_heading == plain_spec.ACCEPTANCE_TEST_HEADING:
568
- raise PlainSyntaxError(
569
- f"Plain syntax error: Syntax error at line {token.line_number}: {plain_spec.ACCEPTANCE_TEST_HEADING} heading should be nested under specific functional spec."
570
- )
571
-
572
- if specification_heading not in plain_spec.ALLOWED_SPECIFICATION_HEADINGS:
573
- raise PlainSyntaxError(
574
- f"Plain syntax error: Syntax error at line {token.line_number}: Invalid specification heading (`{specification_heading}`). Allowed headings: {', '.join(plain_spec.ALLOWED_SPECIFICATION_HEADINGS)}"
575
- )
576
-
577
- if (
578
- specification_heading == plain_spec.FUNCTIONAL_REQUIREMENTS
579
- and specification_heading not in plain_source
580
- ):
581
- plain_source[specification_heading] = None
582
-
583
- if specification_heading in processed_specification_headings:
584
- raise PlainSyntaxError(
585
- f"Plain syntax error: Syntax error at line {token.line_number}: Duplicate specification heading (`{specification_heading}`)"
586
- )
587
-
588
- if specification_heading == plain_spec.DEFINITIONS and current_specification_heading is not None:
589
- raise PlainSyntaxError(
590
- f"Plain syntax error: Syntax error at line {token.line_number}: Definitions specification must be the first specification in the section (`{token_text}`)"
591
- )
592
-
593
- current_specification_heading = specification_heading
594
- if plain_source[current_specification_heading] is None:
595
- plain_source[current_specification_heading] = mistletoe.Document("")
596
-
597
- processed_specification_headings.add(current_specification_heading)
598
- elif isinstance(token, List):
599
- if current_specification_heading is None:
600
- raise PlainSyntaxError(
601
- f"Plain syntax error: Syntax error at line {token.line_number}: Missing specification heading (`{token_text}`)"
602
- )
603
- plain_source[current_specification_heading].children.extend(token.children)
604
-
605
- else:
606
- raise PlainSyntaxError(
607
- f"Plain syntax error: Syntax error at line {token.line_number}: Invalid source structure (`{token_text}`)"
608
- )
609
-
610
- # Acceptance tests are only allowed nested under functional specs. Reject them when
611
- # they are nested under any other section (e.g. definitions, implementation reqs, test reqs).
612
- for non_functional_heading in (
613
- plain_spec.DEFINITIONS,
614
- plain_spec.NON_FUNCTIONAL_REQUIREMENTS,
615
- plain_spec.TEST_REQUIREMENTS,
616
- ):
617
- section = plain_source.get(non_functional_heading)
618
- if section is None:
619
- continue
620
- nested_acceptance_test_heading = _find_acceptance_test_heading(section)
621
- if nested_acceptance_test_heading is not None:
622
- raise PlainSyntaxError(
623
- f"Plain syntax error: Syntax error at line {nested_acceptance_test_heading.line_number}: {plain_spec.ACCEPTANCE_TEST_HEADING} heading should be nested under specific functional spec."
624
- )
625
-
626
- defined_concepts = set[str]()
627
- if plain_source[plain_spec.DEFINITIONS] is not None:
628
- with PlainRenderer() as renderer:
629
- for token in plain_source[plain_spec.DEFINITIONS].children:
630
- rendered_token = renderer.render(token)
631
- new_concepts, _ = concept_utils.extract_concepts_from_definition(rendered_token)
632
- defined_concepts.update(new_concepts)
633
- for concept in new_concepts:
634
- if concept in required_concepts:
635
- required_concepts.remove(concept)
636
-
637
- if EXPORTED_CONCEPTS_DIRECTIVE in plain_source_obj.metadata:
638
- module_name = modules_trace[-1] if modules_trace else None
639
- subject = f"Module '{module_name}'" if module_name else "Module"
640
-
641
- for entry in plain_source_obj.metadata[EXPORTED_CONCEPTS_DIRECTIVE]:
642
- exported_concepts, errors = concept_utils.extract_concepts_from_definition(entry)
643
- if errors:
644
- raise PlainSyntaxError(
645
- f"Plain syntax error: {subject} exports an invalid concept (`{entry}`). "
646
- f"Expected a concept token, e.g. :ConceptName:."
647
- )
648
-
649
- for exported_concept in exported_concepts:
650
- if exported_concept in concept_utils.DEFAULT_CONCEPTS:
651
- raise PlainSyntaxError(
652
- f"Plain syntax error: {subject} cannot export default concept {exported_concept}. "
653
- f"Only user-defined concepts can be exported."
654
- )
655
-
656
- if exported_concept not in defined_concepts:
657
- message = f"Plain syntax error: {subject} exports undefined concept {exported_concept}."
658
- if REQUIRES_DIRECTIVE in plain_source_obj.metadata:
659
- message += (
660
- " An exported concept must be defined in this module's definitions or in an "
661
- "imported module; a concept inherited through requires cannot be re-exported."
662
- )
663
- raise PlainSyntaxError(message)
664
-
665
- required_modules = []
666
- if REQUIRES_DIRECTIVE in plain_source_obj.metadata:
667
- required_modules = plain_source_obj.metadata[REQUIRES_DIRECTIVE]
668
-
669
- return PlainFileParseResult(
670
- plain_source=plain_source,
671
- plain_source_obj=plain_source_obj,
672
- required_modules=required_modules,
673
- required_concepts=required_concepts,
674
- )
675
-
676
-
677
- def read_module_plain_source(module_name: str, template_dirs: list[str]) -> str:
678
- plain_source_text = file_utils.open_from(template_dirs, module_name + PLAIN_SOURCE_FILE_EXTENSION)
679
- if plain_source_text is None:
680
- raise ModuleDoesNotExistError(f"Module does not exist ({module_name}).")
681
-
682
- blob = find_large_base64_blob(plain_source_text)
683
- if blob is not None:
684
- raise UnsupportedBase64Content(
685
- f"Module '{module_name}' contains a base64-encoded blob ({len(blob)} characters) "
686
- "inlined in the specification. This is not supported."
687
- "Remove the base64 data from the .plain file or if necessary,"
688
- "include the binary file path in the specification."
689
- )
690
-
691
- return plain_source_text
692
-
693
-
694
- def parse_plain_file(
695
- module_name: str,
696
- code_variables: dict,
697
- template_dirs: list[str],
698
- imported_modules: list[str],
699
- modules_trace: list[str],
700
- ) -> PlainFileParseResult: # noqa: C901
701
- plain_source_text = read_module_plain_source(module_name, template_dirs)
702
-
703
- return parse_plain_source(
704
- plain_source_text,
705
- code_variables,
706
- template_dirs,
707
- imported_modules,
708
- modules_trace + [module_name],
709
- )
710
-
711
-
712
- def process_required_modules(
713
- required_modules: list[str],
714
- code_variables: dict,
715
- template_dirs: list[str],
716
- all_required_modules: list[str],
717
- modules_trace: list[str],
718
- ) -> list[mistletoe.block_token.token]:
719
- exported_definitions = list[mistletoe.block_token.token]()
720
- for module_name in required_modules:
721
- if module_name in modules_trace:
722
- raise PlainSyntaxError(f"Plain syntax error: Circular required module detected: {module_name}.")
723
-
724
- if len(all_required_modules) > 0 and module_name == all_required_modules[-1]:
725
- continue
726
-
727
- plain_file_parse_result = parse_plain_file(
728
- module_name, code_variables, template_dirs, imported_modules=[], modules_trace=[]
729
- )
730
-
731
- if len(plain_file_parse_result.required_modules) == 0:
732
- if len(all_required_modules) > 0:
733
- # For now we require that there is fixed order how required modules are dependent.
734
- # In the future we will support the cases where required modules can be rendered independently
735
- # and then merged (somehow).
736
- raise PlainSyntaxError(
737
- f"Plain syntax error: There must be a fixed order how required modules are dependent ({module_name})."
738
- )
739
- else:
740
- process_required_modules(
741
- plain_file_parse_result.required_modules,
742
- code_variables,
743
- template_dirs,
744
- all_required_modules,
745
- modules_trace + [module_name],
746
- )
747
-
748
- if EXPORTED_CONCEPTS_DIRECTIVE in plain_file_parse_result.plain_source_obj.metadata:
749
- exported_concepts = list[str]()
750
- for concept in plain_file_parse_result.plain_source_obj.metadata[EXPORTED_CONCEPTS_DIRECTIVE]:
751
- exported_concepts.extend(concept_utils.extract_concepts_from_definition(concept)[0])
752
-
753
- with PlainRenderer() as renderer:
754
- for exported_concept in exported_concepts:
755
- exported_definitions.extend(
756
- concept_utils.find_concept_definitions_in_plain_source(
757
- exported_concept, plain_file_parse_result.plain_source, renderer
758
- )
759
- )
760
-
761
- all_required_modules.append(module_name)
762
-
763
- return exported_definitions
764
-
765
-
766
- def process_exported_definitions(plain_source: dict, exported_definitions: list[mistletoe.block_token.token]) -> None:
767
- if len(exported_definitions) == 0:
768
- return
769
-
770
- if plain_source[plain_spec.DEFINITIONS] is None:
771
- plain_source[plain_spec.DEFINITIONS] = mistletoe.Document("")
772
-
773
- with PlainRenderer() as renderer:
774
- for exported_definition in exported_definitions:
775
- add_defintion = True
776
-
777
- exported_rendered_definition = renderer.render(exported_definition).strip()
778
- for definition in plain_source[plain_spec.DEFINITIONS].children:
779
- rendered_definition = renderer.render(definition).strip()
780
- if exported_rendered_definition == rendered_definition:
781
- add_defintion = False
782
- break
783
-
784
- if add_defintion:
785
- plain_source[plain_spec.DEFINITIONS].children.append(exported_definition)
786
-
787
-
788
- def plain_file_parser( # noqa: C901
789
- plain_source_file_name: str,
790
- template_dirs: list[str],
791
- ) -> tuple[str, dict, list[str]]:
792
- # code_variables are used to pass code variables to the plain source
793
- # they need to be passed as an argument to the function because they populated when liquid templating is applied
794
- # and we need to pass them to the marshalled_plain_source_tree after it's rendered
795
- plain_source_file_path = Path(plain_source_file_name)
796
- if plain_source_file_path.suffix != PLAIN_SOURCE_FILE_EXTENSION:
797
- raise PlainSyntaxError(
798
- f"Plain syntax error: Invalid plain file extension: {plain_source_file_path.suffix}. Expected: {PLAIN_SOURCE_FILE_EXTENSION}."
799
- )
800
-
801
- module_name = (
802
- plain_source_file_path.stem
803
- if plain_source_file_path.is_absolute()
804
- else plain_source_file_path.with_suffix("").as_posix()
805
- )
806
-
807
- code_variables = {}
808
-
809
- plain_file_parse_result = parse_plain_file(
810
- module_name,
811
- code_variables,
812
- template_dirs,
813
- imported_modules=[],
814
- modules_trace=[],
815
- )
816
-
817
- if len(plain_file_parse_result.required_concepts) > 0:
818
- missing_required_concepts_msg = "Missing required concepts: "
819
- missing_required_concepts_msg += ", ".join(plain_file_parse_result.required_concepts)
820
- raise PlainSyntaxError(
821
- f"Plain syntax error: Not all required concepts were defined. {missing_required_concepts_msg}."
822
- )
823
-
824
- if not has_functional_specs_section(plain_file_parse_result.plain_source):
825
- # No ***functional specs*** section at all: valid as an import, but not renderable. Usage error.
826
- raise MissingFunctionalitiesError(
827
- f"Module '{module_name}' does not have any functionality specified. "
828
- f"At least one functionality is required for rendering."
829
- )
830
-
831
- if count_functionalities(plain_file_parse_result.plain_source) == 0:
832
- # ***functional specs*** section present but empty: invalid in every role. Syntax error.
833
- raise PlainSyntaxError(
834
- f"Plain syntax error: Module '{module_name}' has an empty "
835
- f"'{plain_spec.FUNCTIONAL_REQUIREMENTS}' section. At least one functionality must be specified."
836
- )
837
-
838
- validate_functionalities_have_implementation_reqs(
839
- plain_file_parse_result.plain_source,
840
- module_name,
841
- has_requires=bool(plain_file_parse_result.required_modules),
842
- )
843
-
844
- exported_definitions = process_required_modules(
845
- plain_file_parse_result.required_modules,
846
- code_variables={},
847
- template_dirs=template_dirs,
848
- all_required_modules=[],
849
- modules_trace=[],
850
- )
851
-
852
- process_exported_definitions(plain_file_parse_result.plain_source, exported_definitions)
853
-
854
- process_acceptance_tests(plain_file_parse_result.plain_source)
855
-
856
- check_for_linked_resources(plain_file_parse_result.plain_source, template_dirs)
857
-
858
- marshalled_plain_source = marshall_plain_source(plain_file_parse_result.plain_source)
859
-
860
- process_code_variables(marshalled_plain_source, code_variables)
861
-
862
- validation_errors = concept_utils.validate_concepts(marshalled_plain_source)
863
- if len(validation_errors) > 0:
864
- errors_msg = "\n".join(validation_errors)
865
- msg = f"Found {len(validation_errors)} errors in the plain file:\n{errors_msg}"
866
- raise PlainSyntaxError(f"Plain syntax error: {msg}")
867
-
868
- if plain_spec.DEFINITIONS in marshalled_plain_source:
869
- concept_utils.sort_definitions(marshalled_plain_source[plain_spec.DEFINITIONS])
870
-
871
- return module_name, marshalled_plain_source, plain_file_parse_result.required_modules
3
+ from plain_parser.plain_file import * # noqa: F401,F403