Debian Codegraph @

.claude/skills/pr-review/references/examples.md

raw
1 # Review Examples
2
3 These compact examples illustrate recurring implementation patterns. They are
4 templates for reasoning, not project history or line-level prescriptions.
5
6 ## Contents
7
8 - Backend type inference and explicit error flow
9 - Explicit options, normalized type paths, and shared pass machinery
10 - Record semantics and proportional tests
11 - Located diagnostics, narrow layering, and end-to-end tests
12 - Explicit ASR layout guarantees and portability warnings
13 - Canonical and idempotent symbol handling
14 - Explicit provenance and discriminant-aware fields
15 - Syntax normalization in AST-to-ASR
16 - Semantic diagnostics after parsing and scope-bearing Blocks
17 - Native interoperability headers and runtime buffer capacities
18 - Real assertions and append-only diagnostic fixtures
19 - Lexer/grammar composition and version-independent helpers
20 - Shared type-size logic
21 - Root-cause discipline for external CI
22
23 ## Bad: infer an ASR fact from LLVM and bitcast
24
25 ```diff
26 +llvm::Type *expected_type = llvm_utils->get_type_from_ttype_t_util(
27 + ASRUtils::EXPR(ASR::make_Var_t(...)), orig_arg->m_type, module.get());
28 +if (tmp->getType() != expected_type) {
29 + tmp = builder->CreateBitCast(tmp, expected_type);
30 +}
31 ```
32
33 **Problem:** LLVM type inequality is being used to discover a semantic
34 distinction. The cast may hide an incorrect ASR type, physical representation,
35 or procedure interface.
36
37 **Rework:** identify why actual and formal types differ. Resolve the distinction
38 in semantics or represent the required procedure representation explicitly in
39 ASR, verify it, and let LLVM lowering emit the already-known target type.
40
41 ## Bad to good: exception control flow to `Result`
42
43 Bad:
44
45 ```diff
46 +diagnostics.add(diag::Diagnostic(...));
47 +throw parser_local::ParserAbort();
48 ...
49 +} catch (const parser_local::ParserAbort &) {
50 + Error error;
51 + return error;
52 +}
53 ```
54
55 Good:
56
57 ```cpp
58 bool process_include(..., diag::Diagnostics &diagnostics) {
59 if (!file_found) {
60 diagnostics.add(diag::Diagnostic(...,
61 {diag::Label("", {loc})}));
62 return false;
63 }
64 Result<std::string> include_res = prescan(..., diagnostics);
65 if (!include_res.ok) return false;
66 include = include_res.result;
67 return true;
68 }
69 ```
70
71 **Why:** expected compiler failures remain visible in the call chain, and the
72 diagnostic retains its source location.
73
74 ## Bad to good: magic-string intent
75
76 Bad:
77
78 ```python
79 if "--show-fortran" in cmd:
80 stdout_ext = ".f90"
81 else:
82 stdout_ext = ".stdout"
83 ```
84
85 Good:
86
87 ```python
88 def run(..., stdout_ext=".stdout"):
89 stdout_file = os.path.join(out_dir, basename + stdout_ext)
90
91 run(..., stdout_ext=".f90")
92 ```
93
94 **Why:** the caller already knows the output kind. A generic helper should not
95 parse a command string to rediscover intent.
96
97 ## Bad to good: duplicate a scalar path for arrays
98
99 Bad:
100
101 ```cpp
102 if (is_struct(target_type)) {
103 // resolve ~assign and walk parents
104 }
105 if (!sym && is_array_of_struct(target_type)) {
106 // copy of the same resolution and parent walk
107 }
108 ```
109
110 Good:
111
112 ```cpp
113 ASR::ttype_t *base_target_type = ASRUtils::extract_type(target_type);
114 ASR::ttype_t *base_value_type = ASRUtils::extract_type(value_type);
115 sym = resolve_assignment(base_target_type, base_value_type);
116 ```
117
118 **Why:** normalizing once keeps scalar and array behavior aligned and prevents
119 future fixes from changing only one copied path.
120
121 ## Bad: rebuild pass machinery locally
122
123 ```cpp
124 Vec<ASR::expr_t*> idx_vars;
125 // create indices, compute bounds, build element references,
126 // construct nested DoLoop nodes, and replace the statement
127 ```
128
129 **Rework:** keep the special case to detection and argument preparation. Reuse
130 `PassUtils::get_bound`, `get_index_kind()`, `create_array_ref`, and an existing
131 loop wrapper or `generate_loop`.
132
133 ## Bad: flatten records because memory is contiguous
134
135 ```cpp
136 str_src_data = llvm_utils->get_stringArray_data(array_type, unit_val);
137 llvm::Value *elem_len =
138 llvm_utils->get_stringArray_length(array_type, unit_val);
139 // Treat elem_len * n_elems as one stream.
140 ```
141
142 For `character(2) :: lines(2) = ["42", "43"]`, `read(lines, *) a, b`
143 must read two records. Flattening exposes `"4243"` as one record and changes
144 language semantics.
145
146 **Rework:** preserve element length and count as separate record metadata,
147 preferably before backend lowering; make the runtime iterate records. Add this
148 exact multi-record, no-padding test.
149
150 ## Bad: a huge fixture for one small behavior
151
152 ```diff
153 @@ -0,0 +1,1300 @@
154 +program runtime_stacktrace_test
155 ```
156
157 **Rework:** reduce the source to the smallest program that triggers the same
158 bounds failure. If compact coverage already exists, do not commit an unrelated
159 large fixture.
160
161 ## Good: semantic diagnostics retain source facts
162
163 ```diff
164 -std::vector<std::string> assgn_proc_names;
165 +std::vector<std::pair<std::string, Location>> assgn_proc_names_locations;
166 ...
167 -ASR::symbol_t *sym = current_scope->resolve_symbol(name);
168 +ASR::symbol_t *sym =
169 + current_scope->resolve_symbol(to_lower(name_loc.first));
170 ...
171 -{Label("", {})}
172 +{Label("", {name_loc.second})}
173 ```
174
175 **Why:** source location survives semantic processing, symbol lookup follows
176 Fortran case rules, and failures point to the relevant source.
177
178 ## Good: choose the narrow correct layer
179
180 ```cpp
181 std::string cpp_input = code_orig;
182 if (!cpp_input.empty() && cpp_input.back() != '\n') {
183 cpp_input.push_back('\n');
184 }
185 Result<std::string> res =
186 cpp.run(cpp_input, lm, cpp.macro_definitions, diagnostics);
187 ```
188
189 File-like inputs require a trailing newline, while the shared preprocessor also
190 handles recursive macro fragments that must not gain one. Normalize at the
191 file-like entry point, not unconditionally in the deepest shared function.
192
193 ## Good: compact end-to-end regression
194
195 ```cmake
196 RUN(NAME defined_op_match_02 LABELS gfortran llvm)
197 ```
198
199 Pair the registration with a small program containing `error stop` checks for
200 present, absent, whole-array, section, and scalar cases. This makes the test
201 behavioral, registered, and differential across the reference and LLVM
202 backends.
203
204 ## Good: encode a layout guarantee in ASR
205
206 ```diff
207 -| Struct(... bool is_packed, bool is_abstract, ...)
208 +| Struct(... bool is_packed, bool is_abstract, bool is_sequence, ...)
209 ```
210
211 Set the field during AST-to-ASR:
212
213 ```cpp
214 bool is_sequence = has_attribute(x, AST::simple_attributeType::AttrSequence);
215 ASR::make_Struct_t(..., is_packed, is_abstract, is_sequence, ...);
216 ```
217
218 Consume the semantic fact mechanically:
219
220 ```cpp
221 bool has_defined_layout =
222 struct_type->m_abi == ASR::abiType::BindC ||
223 struct_type->m_is_sequence;
224 if (has_defined_layout) {
225 // Lower fixed character members as inline storage.
226 }
227 ```
228
229 **Why:** the frontend records the language-level layout guarantee once.
230 Codegen no longer has to infer it from an LLVM type or member shape, and ASR
231 verification can reject inconsistent states.
232
233 ## Good: warn when accepting a language extension
234
235 ```cpp
236 if (!has_len || char_len != 1) {
237 diag.semantic_warning_label(
238 "character component of a BIND(C) type with length other than 1 "
239 "is not standard-conforming (LFortran extension)",
240 {member->base.base.loc},
241 "use character(len=1) or an array of length-1 elements");
242 }
243 ```
244
245 Register runtime behavior only for compilers that accept the extension, and add
246 a reference diagnostic that checks the warning location and conforming
247 alternative.
248
249 **Why:** useful extensions remain available without misleading users about
250 portability. Testing both behavior and diagnostics prevents the extension from
251 silently becoming an undocumented language divergence.
252
253 ## Good: import the terminal symbol definition
254
255 Bad:
256
257 ```cpp
258 ASR::symbol_t *struct_sym = get_struct_sym_from_struct_expr(expr);
259 ASR::make_ExternalSymbol_t(..., struct_sym, ...);
260 ```
261
262 Good:
263
264 ```cpp
265 ASR::symbol_t *struct_sym = get_struct_sym_from_struct_expr(expr);
266 ASR::symbol_t *original_struct =
267 ASRUtils::symbol_get_past_external(struct_sym);
268 if (original_struct == nullptr) return nullptr;
269 ASR::make_ExternalSymbol_t(..., original_struct,
270 ASRUtils::symbol_name(ASRUtils::get_asr_owner(original_struct)), ...);
271 ```
272
273 **Why:** an imported symbol points directly to its definition rather than
274 forming an `ExternalSymbol` chain. Transitive imports then have one canonical
275 owner and downstream consumers do not need repeated unwrapping.
276
277 ## Good: make symbol creation idempotent
278
279 Bad:
280
281 ```cpp
282 ASR::symbol_t *var_sym = make_index_variable(...);
283 current_scope->add_symbol(var_name, var_sym);
284 ```
285
286 Good:
287
288 ```cpp
289 ASR::symbol_t *var_sym = current_scope->get_symbol(var_name);
290 if (var_sym == nullptr) {
291 var_sym = make_index_variable(...);
292 current_scope->add_symbol(var_name, var_sym);
293 }
294 ASR::expr_t *var = ASRUtils::EXPR(
295 ASR::make_Var_t(al, loc, var_sym));
296 ```
297
298 **Why:** repeated or overlapping lowering paths reuse the current-scope symbol
299 instead of creating duplicate names and invalidating symbol-table invariants.
300 The compatibility of an existing symbol must still be checked when the context
301 does not guarantee it.
302
303 ## Bad to good: derive provenance instead of matching generated names
304
305 Bad:
306
307 ```cpp
308 if (starts_with(symbol_name, "1_") ||
309 starts_with(symbol_name, "__compiler_marker_")) {
310 entry.hidden = true;
311 }
312 ```
313
314 Good:
315
316 ```cpp
317 ASR::symbol_t *definition =
318 ASRUtils::symbol_get_past_external(symbol);
319 ASR::symbol_t *owner =
320 definition ? ASRUtils::get_asr_owner(definition) : nullptr;
321
322 entry.is_synthetic_member =
323 owner && (ASR::is_a<ASR::Struct_t>(*owner) ||
324 ASR::is_a<ASR::Enum_t>(*owner) ||
325 ASR::is_a<ASR::Union_t>(*owner));
326 ```
327
328 If several consumers need this distinction, store the provenance flag in ASR
329 instead of recomputing it.
330
331 **Why:** imported user symbols and synthetic member lookups can share a node
332 kind. Generated names are implementation details and rarely cover every source
333 of an entity.
334
335 ## Bad to good: access kind-dependent storage through one abstraction
336
337 Bad:
338
339 ```cpp
340 double value = ASR::down_cast<ASR::RealConstant_t>(
341 ASRUtils::expr_value(arg))->m_r;
342 ```
343
344 If `m_r` stores a floating value for common kinds but encodes a pointer to wider
345 storage for another kind, the unconditional read silently produces nonsense.
346
347 Good shape:
348
349 ```cpp
350 RealValue value = ASRUtils::extract_real_constant(arg);
351 switch (value.kind) {
352 case 4:
353 case 8:
354 use_native(value.native);
355 break;
356 case 16:
357 use_wide(value.wide);
358 break;
359 }
360 ```
361
362 Alternatively, use distinct explicit fields whose types make the
363 representations impossible to confuse.
364
365 **Why:** every reader honors the same discriminant. Do not add another field
366 that merely duplicates the kind already stored in the expression type.
367
368 ## Good: normalize syntax before backend lowering
369
370 ```diff
371 +| KW_TYPE KW_IS "(" TK_NAME "(" kind_arg_list ")" ")" sep statements {
372 + $$ = TYPE_STMTVAR(
373 + ATTR_TYPE_NAME_KIND(Type, SYMBOL($4, @4), $6, @$),
374 + TRIVIA_AFTER($9, @$), $10, @$);
375 +}
376 ```
377
378 In AST-to-ASR, recognize that the parsed type denotes a derived type and lower
379 it to the same canonical type-guard representation used by the simpler syntax:
380
381 ```cpp
382 ASR::symbol_t *type_decl =
383 ASRUtils::symbol_get_past_external(parsed_type_declaration);
384 if (type_decl && ASR::is_a<ASR::Struct_t>(*type_decl)) {
385 lower_as_struct_type_guard(type_decl, selector, body);
386 }
387 ```
388
389 **Why:** grammar handles the source form, semantics resolves its meaning, and
390 the backend receives an existing canonical ASR node.
391
392 ## Bad to good: semantic validation in a parser action
393
394 Bad:
395
396 ```cpp
397 #define REQUIREMENT(name, args, body, loc) ( \
398 check_duplicate_args(parser, args), \
399 make_Requirement_t(...))
400 ```
401
402 Good: retain each argument's source location in AST and validate it during
403 AST-to-ASR:
404
405 ```cpp
406 std::map<std::string, Location> seen;
407 for (const AST::arg_t &arg_node : requirement_args) {
408 std::string arg = to_lower(arg_node.m_arg);
409 auto previous = seen.find(arg);
410 if (previous != seen.end()) {
411 diag.add(Diagnostic(
412 "parameter '" + arg + "' is declared more than once",
413 Level::Error, Stage::Semantic, {
414 Label("first declared here", {previous->second}),
415 Label("redeclared here", {arg_node.loc})}));
416 throw SemanticAbort();
417 }
418 seen.emplace(arg, arg_node.loc);
419 }
420 ```
421
422 **Why:** parsing always produces AST. Semantics can identify both precise
423 offending tokens and participate in continue-compilation recovery.
424
425 ## Bad to good: assert the condition, not the message
426
427 Bad:
428
429 ```cpp
430 LCOMPILERS_ASSERT("parameter number is in range");
431 if (i >= call.n_args) continue;
432 ```
433
434 The string is always truthy, and the `continue` hides an invalid formal/actual
435 mapping.
436
437 Good:
438
439 ```cpp
440 LCOMPILERS_ASSERT(i < call.n_args);
441 LCOMPILERS_ASSERT(formal_count == actual_count ||
442 omitted_arguments_are_valid(call));
443 ```
444
445 When the invariant applies to all valid ASR, add the equivalent requirement to
446 ASR verification rather than relying only on a backend assertion.
447
448 ## Good: keep a shared diagnostic fixture append-only
449
450 Bad:
451
452 ```fortran
453 program continue_compilation
454 ! Existing cases and internal helper procedures are interleaved.
455 ! Inserting a new case shifts every later diagnostic line.
456 end program
457 ```
458
459 Good:
460
461 ```fortran
462 module diagnostic_helpers
463 contains
464 ! Stable helper procedures.
465 end module
466
467 program continue_compilation
468 use diagnostic_helpers
469 ! Existing cases remain fixed; append new cases here.
470 end program
471 ```
472
473 **Why:** source locations in existing reference diagnostics stay stable while
474 the file remains a single recoverable-error test.
475
476 ## Bad to good: put local scope on a symbol
477
478 Bad ASR shape:
479
480 ```text
481 DoConcurrentLoop(symbol_table symtab, do_loop_head* head, stmt* body)
482 ```
483
484 A statement node should not own a symbol table.
485
486 Good:
487
488 ```text
489 DoConcurrentLoop(do_loop_head* head, stmt* body)
490 Block(symbol_table symtab, identifier name, stmt* body)
491 ```
492
493 When the loop header declares local names, lower the body to a `BlockCall`
494 referencing a compiler-generated `Block`. Require that shape in ASR verification
495 and visit the loop under the Block's scope.
496
497 **Why:** symbol ownership remains uniform, and every consumer follows the same
498 verified representation instead of learning another statement-specific scope
499 exception.
500
501 ## Bad to good: use each compiler's interoperability header
502
503 Bad:
504
505 ```c
506 #define _lfortran_cfi_calloc calloc
507 #define _lfortran_cfi_free free
508 #include "../src/libasr/runtime/ISO_Fortran_binding.h"
509 ```
510
511 Good:
512
513 ```c
514 #include "ISO_Fortran_binding.h"
515 ```
516
517 Configure each compiler invocation so its include path and runtime provide the
518 matching standard interoperability implementation.
519
520 **Why:** a differential test must exercise each compiler's ABI, not compile all
521 variants against one compiler's private descriptor definitions and shims.
522
523 ## Bad to good: respect the runtime buffer contract
524
525 Bad:
526
527 ```c
528 snprintf(iomsg, iomsg_len + 1,
529 "cannot open file '%s': %s", filename, reason);
530 ```
531
532 If `iomsg` points to `iomsg_len` bytes, the advertised capacity is one byte too
533 large.
534
535 Good:
536
537 ```c
538 if (iomsg != NULL && iomsg_len > 0) {
539 snprintf(iomsg, (size_t)iomsg_len,
540 "cannot open file '%s': %s", filename, reason);
541 }
542 ```
543
544 **Why:** bounded APIs trust the supplied capacity. Tests should exercise every
545 error branch with short, exact-size, and truncated message buffers.
546
547 ## Bad to good: extend the grammar at the compositional rule
548
549 Bad:
550
551 ```text
552 decl_statements : decl_statements special_decl
553 var_decl_star : var_decl_star special_decl
554 decl_star : decl_star special_decl
555 ```
556
557 Good:
558
559 ```text
560 decl_statement : ordinary_decl
561 | special_decl
562
563 decl_statements : decl_statements decl_statement
564 ```
565
566 Add a parser-level test for every new lexer token and audit all source-form
567 lexer paths that emit it.
568
569 **Why:** one per-item production composes through every existing list context.
570 Patching each wrapper duplicates grammar knowledge and inevitably misses one.
571
572 ## Bad to good: isolate toolchain-version compatibility
573
574 Bad:
575
576 ```cpp
577 #if LLVM_VERSION_MAJOR >= 15
578 value = load_new(...);
579 #else
580 value = load_old(...);
581 #endif
582 ```
583
584 repeated at several lowering sites.
585
586 Good:
587
588 ```cpp
589 value = llvm_utils->load_compatible(pointer, element_type);
590 ```
591
592 with the version conditional implemented once inside `load_compatible`.
593
594 **Why:** semantic lowering no longer knows toolchain-version details, and
595 compatibility behavior has one implementation and one focused test surface.
596
597 ## Bad to good: duplicate size calculations
598
599 Bad:
600
601 ```cpp
602 auto [size, align] = compute_type_size_align(type);
603 if (ASRUtils::is_string(type)) {
604 size *= extract_string_length(type);
605 }
606 ```
607
608 Repeated copies of the string adjustment will drift and can double-apply the
609 length.
610
611 Good:
612
613 ```cpp
614 if (ASR::is_a<ASR::String_t>(*type)) {
615 ASR::String_t *string_type = ASR::down_cast<ASR::String_t>(type);
616 int64_t len;
617 if (string_type->m_kind <= 0 ||
618 string_type->m_len == nullptr ||
619 !ASRUtils::extract_value(string_type->m_len, len) ||
620 len < 0) {
621 return {-1, -1};
622 }
623 return {string_type->m_kind * len, 1};
624 }
625 ```
626
627 **Why:** the shared size-and-alignment helper owns the complete definition.
628 Callers no longer add type-specific corrections.
629
630 ## Bad: disable external coverage without finding the failing toolchain
631
632 ```sh
633 # Temporary fix
634 git cherry-pick <upstream-commit-that-disables-this-compiler>
635 ```
636
637 **Problem:** the imported patch may reduce compiler coverage while the observed
638 failure actually comes from a reference compiler, runtime, launcher, or
639 dependency.
640
641 **Rework:** identify the command and toolchain that fails, preserve unaffected
642 coverage, and fix the root cause. If quarantine is unavoidable, skip only the
643 specific failing case, attach it to a tracked defect, and add a condition that
644 can be removed when the defect is fixed.