Coverage for src/debputy/lsp/lsp_debian_control_reference_data.py: 84%

1410 statements  

« prev     ^ index     » next       coverage.py v7.16.1, created at 2026-10-28 20:14 +0000

1import collections 

2import dataclasses 

3import functools 

4import importlib.resources 

5import itertools 

6import operator 

7import os.path 

8import re 

9import textwrap 

10from abc import ABC 

11from typing import ( 

12 Optional, 

13 cast, 

14 Generic, 

15 TypeVar, 

16 Union, 

17 Any, 

18 TYPE_CHECKING, 

19 Self, 

20) 

21from collections.abc import Mapping, Iterable, Callable, Sequence, Iterator, Container 

22 

23from debian.debian_support import DpkgArchTable, Version 

24 

25import debputy.lsp.data.deb822_data as deb822_ref_data_dir 

26from debputy.filesystem_scan import VirtualPathBase 

27from debputy.linting.lint_util import LintState, with_range_in_continuous_parts 

28from debputy.linting.lint_util import te_range_to_lsp 

29from debputy.lsp.diagnostics import LintSeverity 

30from debputy.lsp.lsp_reference_keyword import ( 

31 Keyword, 

32 allowed_values, 

33 format_comp_item_synopsis_doc, 

34 LSP_DATA_DOMAIN, 

35 ALL_PUBLIC_NAMED_STYLES_AS_KEYWORDS, 

36) 

37from debputy.lsp.quickfixes import ( 

38 propose_correct_text_quick_fix, 

39 propose_remove_range_quick_fix, 

40) 

41from debputy.lsp.ref_models.deb822_reference_parse_models import ( 

42 Deb822ReferenceData, 

43 DEB822_REFERENCE_DATA_PARSER, 

44 FieldValueClass, 

45 StaticValue, 

46 Deb822Field, 

47 UsageHint, 

48 Alias, 

49) 

50from debputy.lsp.text_edit import apply_text_edits 

51from debputy.lsp.text_util import ( 

52 normalize_dctrl_field_name, 

53 LintCapablePositionCodec, 

54 trim_end_of_line_whitespace, 

55) 

56from debian._deb822_repro.parsing import ( 

57 Deb822KeyValuePairElement, 

58 LIST_SPACE_SEPARATED_INTERPRETATION, 

59 Deb822ParagraphElement, 

60 Deb822FileElement, 

61 Interpretation, 

62 parse_deb822_file, 

63 Deb822ParsedTokenList, 

64 Deb822ValueLineElement, 

65) 

66from debian._deb822_repro.tokens import ( 

67 Deb822FieldNameToken, 

68) 

69from debian._deb822_repro.types import FormatterCallback, TE 

70from debputy.lsp.vendoring.wrap_and_sort import _sort_packages_key 

71from debputy.lsprotocol.types import ( 

72 DiagnosticTag, 

73 Range, 

74 TextEdit, 

75 Position, 

76 CompletionItem, 

77 MarkupContent, 

78 CompletionItemTag, 

79 MarkupKind, 

80 CompletionItemKind, 

81 CompletionItemLabelDetails, 

82) 

83from debputy.manifest_parser.exceptions import ManifestParseException 

84from debputy.manifest_parser.util import AttributePath 

85from debputy.path_matcher import BasenameGlobMatch 

86from debputy.plugin.api import VirtualPath 

87from debputy.pydeb_compat import resolve_dpkg_arch_keyword_for_all_archs 

88from debputy.util import PKGNAME_REGEX, _info, detect_possible_typo, _error 

89from debputy.yaml import MANIFEST_YAML 

90 

91try: 

92 from debian._deb822_repro.locatable import ( 

93 Position as TEPosition, 

94 Range as TERange, 

95 START_POSITION, 

96 ) 

97except ImportError: 

98 pass 

99 

100 

101if TYPE_CHECKING: 

102 from debputy.lsp.maint_prefs import EffectiveFormattingPreference 

103 from debputy.lsp.debputy_ls import DebputyLanguageServer 

104 

105 

106F = TypeVar("F", bound="Deb822KnownField", covariant=True) 

107S = TypeVar("S", bound="StanzaMetadata") 

108 

109 

110SUBSTVAR_RE = re.compile(r"[$][{][a-zA-Z0-9][a-zA-Z0-9-:]*[}]") 

111 

112_RE_SYNOPSIS_STARTS_WITH_ARTICLE = re.compile(r"^\s*(an?|the)(?:\s|$)", re.I) 

113_RE_SV = re.compile(r"(\d+[.]\d+[.]\d+)([.]\d+)?") 

114_RE_SYNOPSIS_IS_TEMPLATE = re.compile( 

115 r"^\s*(missing|<insert up to \d+ chars description>)$" 

116) 

117_RE_SYNOPSIS_IS_TOO_SHORT = re.compile(r"^\s*(\S+)$") 

118CURRENT_STANDARDS_VERSION = Version("4.7.4") 

119 

120 

121CustomFieldCheck = Callable[ 

122 [ 

123 "F", 

124 Deb822FileElement, 

125 Deb822KeyValuePairElement, 

126 "TERange", 

127 "TERange", 

128 Deb822ParagraphElement, 

129 "TEPosition", 

130 LintState, 

131 ], 

132 None, 

133] 

134 

135 

136@functools.lru_cache 

137def all_package_relationship_fields() -> Mapping[str, str]: 

138 # TODO: Pull from `dpkg-dev` when possible fallback only to the static list. 

139 return { 

140 f.lower(): f 

141 for f in ( 

142 "Pre-Depends", 

143 "Depends", 

144 "Recommends", 

145 "Suggests", 

146 "Enhances", 

147 "Conflicts", 

148 "Breaks", 

149 "Replaces", 

150 "Provides", 

151 "Built-Using", 

152 "Static-Built-Using", 

153 ) 

154 } 

155 

156 

157@functools.lru_cache 

158def all_source_relationship_fields() -> Mapping[str, str]: 

159 # TODO: Pull from `dpkg-dev` when possible fallback only to the static list. 

160 return { 

161 f.lower(): f 

162 for f in ( 

163 "Build-Depends", 

164 "Build-Depends-Arch", 

165 "Build-Depends-Indep", 

166 "Build-Conflicts", 

167 "Build-Conflicts-Arch", 

168 "Build-Conflicts-Indep", 

169 ) 

170 } 

171 

172 

173ALL_SECTIONS_WITHOUT_COMPONENT = frozenset( 

174 [ 

175 "admin", 

176 "cli-mono", 

177 "comm", 

178 "database", 

179 "debian-installer", 

180 "debug", 

181 "devel", 

182 "doc", 

183 "editors", 

184 "education", 

185 "electronics", 

186 "embedded", 

187 "fonts", 

188 "games", 

189 "gnome", 

190 "gnu-r", 

191 "gnustep", 

192 "golang", 

193 "graphics", 

194 "hamradio", 

195 "haskell", 

196 "httpd", 

197 "interpreters", 

198 "introspection", 

199 "java", 

200 "javascript", 

201 "kde", 

202 "kernel", 

203 "libdevel", 

204 "libs", 

205 "lisp", 

206 "localization", 

207 "mail", 

208 "math", 

209 "metapackages", 

210 "misc", 

211 "net", 

212 "news", 

213 "ocaml", 

214 "oldlibs", 

215 "otherosfs", 

216 "perl", 

217 "php", 

218 "python", 

219 "ruby", 

220 "rust", 

221 "science", 

222 "shells", 

223 "sound", 

224 "tasks", 

225 "tex", 

226 "text", 

227 "utils", 

228 "vcs", 

229 "video", 

230 "virtual", 

231 "web", 

232 "x11", 

233 "xfce", 

234 "zope", 

235 ] 

236) 

237 

238ALL_COMPONENTS = frozenset( 

239 [ 

240 "main", 

241 "restricted", # Ubuntu 

242 "non-free", 

243 "non-free-firmware", 

244 "contrib", 

245 ] 

246) 

247 

248 

249def _fields(*fields: F) -> Mapping[str, F]: 

250 return {normalize_dctrl_field_name(f.name.lower()): f for f in fields} 

251 

252 

253def _complete_section_sort_hint( 

254 keyword: Keyword, 

255 _lint_state: LintState, 

256 stanza_parts: Sequence[Deb822ParagraphElement], 

257 _value_being_completed: str, 

258) -> str | None: 

259 for stanza in stanza_parts: 259 ↛ 264line 259 didn't jump to line 264 because the loop on line 259 didn't complete

260 pkg = stanza.get("Package") 

261 if pkg is not None: 261 ↛ 259line 261 didn't jump to line 259 because the condition on line 261 was always true

262 break 

263 else: 

264 return None 

265 section = package_name_to_section(pkg) 

266 value_parts = keyword.value.rsplit("/", 1) 

267 keyword_section = value_parts[-1] 

268 keyword_component = f" ({value_parts[0]})" if len(value_parts) > 1 else "" 

269 if section is None: 

270 if keyword_component == "": 

271 return keyword_section 

272 return f"zz-{keyword_section}{keyword_component}" 

273 if keyword_section != section: 

274 return f"zz-{keyword_section}{keyword_component}" 

275 return f"aa-{keyword_section}{keyword_component}" 

276 

277 

278ALL_SECTIONS = allowed_values( 

279 Keyword( 

280 s if c is None else f"{c}/{s}", 

281 sort_text=_complete_section_sort_hint, 

282 replaced_by=s if c == "main" else None, 

283 ) 

284 for c, s in itertools.product( 

285 itertools.chain(cast("Iterable[Optional[str]]", [None]), ALL_COMPONENTS), 

286 ALL_SECTIONS_WITHOUT_COMPONENT, 

287 ) 

288) 

289 

290 

291def all_architectures_and_wildcards( 

292 arch2table: collections.abc.Iterator[tuple[str, tuple[str, str]]], 

293 *, 

294 allow_negations: bool = False, 

295) -> Iterable[str | Keyword]: 

296 wildcards = set() 

297 yield Keyword( 

298 "any", 

299 is_exclusive=True, 

300 synopsis="Built once per machine architecture (native code, such as C/C++, interpreter to C bindings)", 

301 long_description=textwrap.dedent("""\ 

302 This is an architecture-dependent package, and needs to be 

303 compiled for each and every architecture. 

304 

305 The name `any` refers to that this is an architecture 

306 *wildcard* matching *any machine architecture* supported by 

307 dpkg. 

308 """), 

309 ) 

310 yield Keyword( 

311 "all", 

312 is_exclusive=True, 

313 synopsis="Independent of machine architecture (scripts, data, documentation, or Java without JNI)", 

314 long_description=textwrap.dedent("""\ 

315 The package is an architecture independent package. This is 

316 typically appropriate for packages containing only scripts, 

317 data or documentation. 

318 

319 The name `all` refers to that the same build of a package 

320 can be used for *all* architectures. Though note that it is still 

321 subject to the rules of the `Multi-Arch` field. 

322 """), 

323 ) 

324 for arch_name, (cpu_name, os_name) in arch2table: 

325 yield arch_name 

326 if allow_negations: 

327 yield f"!{arch_name}" 

328 cpu_wc = "any-" + cpu_name 

329 os_wc = os_name + "-any" 

330 if cpu_wc not in wildcards: 

331 yield cpu_wc 

332 if allow_negations: 

333 yield f"!{cpu_wc}" 

334 wildcards.add(cpu_wc) 

335 if os_wc not in wildcards: 

336 yield os_wc 

337 if allow_negations: 

338 yield f"!{os_wc}" 

339 wildcards.add(os_wc) 

340 # Add the remaining wildcards 

341 

342 

343@functools.lru_cache 

344def _dpkg_arch_table() -> DpkgArchTable: 

345 return DpkgArchTable.load_arch_table() 

346 

347 

348@functools.lru_cache 

349def dpkg_architecture_values(keyword: str) -> frozenset[str] | None: 

350 return resolve_dpkg_arch_keyword_for_all_archs(_dpkg_arch_table(), keyword) 

351 

352 

353@functools.lru_cache 

354def dpkg_arch_and_wildcards(*, allow_negations=False) -> frozenset[str | Keyword]: 

355 dpkg_arch_table = _dpkg_arch_table() 

356 try: 

357 # Requires python-debian/1.2.0+ 

358 all_archs = dpkg_arch_table.all_valid_dpkg_architectures() 

359 except AttributeError: 

360 # Hack for older versions 

361 return frozenset( 

362 all_architectures_and_wildcards( 

363 ( 

364 (k, (v.cpu_name, v.os_name)) 

365 for k, v in dpkg_arch_table._arch2table.items() 

366 ), 

367 allow_negations=allow_negations, 

368 ) 

369 ) 

370 else: 

371 return frozenset( 

372 all_architectures_and_wildcards( 

373 ( 

374 (a.debian_name(), (a.debian_cpu_name(), a.os_name())) 

375 for a in all_archs 

376 ), 

377 allow_negations=allow_negations, 

378 ) 

379 ) 

380 

381 

382def extract_first_value_and_position( 

383 kvpair: Deb822KeyValuePairElement, 

384 stanza_pos: "TEPosition", 

385 *, 

386 interpretation: Interpretation[ 

387 Deb822ParsedTokenList[Any, Any] 

388 ] = LIST_SPACE_SEPARATED_INTERPRETATION, 

389) -> tuple[str | None, TERange | None]: 

390 kvpair_pos = kvpair.position_in_parent().relative_to(stanza_pos) 

391 value_element_pos = kvpair.value_element.position_in_parent().relative_to( 

392 kvpair_pos 

393 ) 

394 for value_ref in kvpair.interpret_as(interpretation).iter_value_references(): 394 ↛ 401line 394 didn't jump to line 401 because the loop on line 394 didn't complete

395 v = value_ref.value 

396 section_value_loc = value_ref.locatable 

397 value_range_te = section_value_loc.range_in_parent().relative_to( 

398 value_element_pos 

399 ) 

400 return v, value_range_te 

401 return None, None 

402 

403 

404def _sv_field_validation( 

405 known_field: "F", 

406 _deb822_file: Deb822FileElement, 

407 kvpair: Deb822KeyValuePairElement, 

408 _kvpair_range: "TERange", 

409 _field_name_range_te: "TERange", 

410 _stanza: Deb822ParagraphElement, 

411 stanza_position: "TEPosition", 

412 lint_state: LintState, 

413) -> None: 

414 sv_value, sv_value_range = extract_first_value_and_position( 

415 kvpair, 

416 stanza_position, 

417 ) 

418 m = _RE_SV.fullmatch(sv_value) 

419 if m is None: 

420 lint_state.emit_diagnostic( 

421 sv_value_range, 

422 f'Not a valid standards version. Current version is "{CURRENT_STANDARDS_VERSION}"', 

423 "warning", 

424 known_field.unknown_value_authority, 

425 ) 

426 return 

427 

428 sv_version = Version(sv_value) 

429 if sv_version < CURRENT_STANDARDS_VERSION: 

430 lint_state.emit_diagnostic( 

431 sv_value_range, 

432 f"Latest Standards-Version is {CURRENT_STANDARDS_VERSION}", 

433 "informational", 

434 known_field.unknown_value_authority, 

435 ) 

436 return 

437 extra = m.group(2) 

438 if extra: 

439 extra_len = lint_state.position_codec.client_num_units(extra) 

440 lint_state.emit_diagnostic( 

441 TERange.between( 

442 TEPosition( 

443 sv_value_range.end_pos.line_position, 

444 sv_value_range.end_pos.cursor_position - extra_len, 

445 ), 

446 sv_value_range.end_pos, 

447 ), 

448 "Unnecessary version segment. This part of the version is only used for editorial changes", 

449 "informational", 

450 known_field.unknown_value_authority, 

451 quickfixes=[ 

452 propose_remove_range_quick_fix( 

453 proposed_title="Remove unnecessary version part" 

454 ) 

455 ], 

456 ) 

457 

458 

459def _dctrl_ma_field_validation( 

460 _known_field: "F", 

461 _deb822_file: Deb822FileElement, 

462 _kvpair: Deb822KeyValuePairElement, 

463 _kvpair_range: "TERange", 

464 _field_name_range: "TERange", 

465 stanza: Deb822ParagraphElement, 

466 stanza_position: "TEPosition", 

467 lint_state: LintState, 

468) -> None: 

469 ma_kvpair = stanza.get_kvpair_element(("Multi-Arch", 0), use_get=True) 

470 arch = stanza.get("Architecture", "any") 

471 if arch == "all" and ma_kvpair is not None: 471 ↛ exitline 471 didn't return from function '_dctrl_ma_field_validation' because the condition on line 471 was always true

472 ma_value, ma_value_range = extract_first_value_and_position( 

473 ma_kvpair, 

474 stanza_position, 

475 ) 

476 if ma_value == "same": 

477 lint_state.emit_diagnostic( 

478 ma_value_range, 

479 "Multi-Arch: same is not valid for Architecture: all packages. Maybe you want foreign?", 

480 "error", 

481 "debputy", 

482 ) 

483 

484 

485def _udeb_only_field_validation( 

486 known_field: "F", 

487 _deb822_file: Deb822FileElement, 

488 _kvpair: Deb822KeyValuePairElement, 

489 _kvpair_range: "TERange", 

490 field_name_range: "TERange", 

491 stanza: Deb822ParagraphElement, 

492 _stanza_position: "TEPosition", 

493 lint_state: LintState, 

494) -> None: 

495 package_type = stanza.get("Package-Type") 

496 if package_type != "udeb": 

497 lint_state.emit_diagnostic( 

498 field_name_range, 

499 f"The {known_field.name} field is only applicable to udeb packages (`Package-Type: udeb`)", 

500 "warning", 

501 "debputy", 

502 ) 

503 

504 

505def _not_applicable_to_udeb_field_validation( 

506 known_field: "F", 

507 _deb822_file: Deb822FileElement, 

508 _kvpair: Deb822KeyValuePairElement, 

509 kvpair_range: "TERange", 

510 _field_name_range: "TERange", 

511 stanza: Deb822ParagraphElement, 

512 _stanza_position: "TEPosition", 

513 lint_state: LintState, 

514) -> None: 

515 package_type = stanza.get("Package-Type") 

516 if package_type == "udeb": 

517 lint_state.emit_diagnostic( 

518 kvpair_range, 

519 f"The {known_field.name} field is not applicable to udeb packages (`Package-Type: udeb`)", 

520 "warning", 

521 "debputy", 

522 quickfixes=[propose_remove_range_quick_fix()], 

523 ) 

524 

525 

526def _complete_only_in_arch_dep_pkgs( 

527 stanza_parts: Iterable[Deb822ParagraphElement], 

528) -> bool: 

529 for stanza in stanza_parts: 

530 arch = stanza.get("Architecture") 

531 if arch is None: 

532 continue 

533 archs = arch.split() 

534 return "all" not in archs 

535 return False 

536 

537 

538def _complete_only_for_udeb_pkgs( 

539 stanza_parts: Iterable[Deb822ParagraphElement], 

540) -> bool: 

541 for stanza in stanza_parts: 

542 for option in ("Package-Type", "XC-Package-Type"): 

543 pkg_type = stanza.get(option) 

544 if pkg_type is not None: 

545 return pkg_type == "udeb" 

546 return False 

547 

548 

549def _arch_not_all_only_field_validation( 

550 known_field: "F", 

551 _deb822_file: Deb822FileElement, 

552 _kvpair: Deb822KeyValuePairElement, 

553 _kvpair_range_te: "TERange", 

554 field_name_range_te: "TERange", 

555 stanza: Deb822ParagraphElement, 

556 _stanza_position: "TEPosition", 

557 lint_state: LintState, 

558) -> None: 

559 architecture = stanza.get("Architecture") 

560 if architecture == "all": 560 ↛ exitline 560 didn't return from function '_arch_not_all_only_field_validation' because the condition on line 560 was always true

561 lint_state.emit_diagnostic( 

562 field_name_range_te, 

563 f"The {known_field.name} field is not applicable to arch:all packages (`Architecture: all`)", 

564 "warning", 

565 "debputy", 

566 ) 

567 

568 

569def _binary_package_from_same_source( 

570 known_field: "F", 

571 _deb822_file: Deb822FileElement, 

572 _kvpair: Deb822KeyValuePairElement, 

573 kvpair_range: "TERange", 

574 _field_name_range: "TERange", 

575 stanza: Deb822ParagraphElement, 

576 stanza_position: "TEPosition", 

577 lint_state: LintState, 

578) -> None: 

579 doc_main_package_kvpair = stanza.get_kvpair_element( 

580 (known_field.name, 0), use_get=True 

581 ) 

582 if len(lint_state.binary_packages) == 1: 

583 lint_state.emit_diagnostic( 

584 kvpair_range, 

585 f"The {known_field.name} field is redundant for source packages that only build one binary package", 

586 "warning", 

587 "debputy", 

588 quickfixes=[propose_remove_range_quick_fix()], 

589 ) 

590 return 

591 if doc_main_package_kvpair is not None: 591 ↛ exitline 591 didn't return from function '_binary_package_from_same_source' because the condition on line 591 was always true

592 doc_main_package, value_range = extract_first_value_and_position( 

593 doc_main_package_kvpair, 

594 stanza_position, 

595 ) 

596 if doc_main_package is None or doc_main_package in lint_state.binary_packages: 

597 return 

598 lint_state.emit_diagnostic( 

599 value_range, 

600 f"The {known_field.name} field must name a package listed in debian/control", 

601 "error", 

602 "debputy", 

603 quickfixes=[ 

604 propose_correct_text_quick_fix(name) 

605 for name in lint_state.binary_packages 

606 ], 

607 ) 

608 

609 

610def _single_line_span_range_relative_to_pos( 

611 span: tuple[int, int], 

612 relative_to: "TEPosition", 

613) -> Range: 

614 return TERange( 

615 TEPosition( 

616 relative_to.line_position, 

617 relative_to.cursor_position + span[0], 

618 ), 

619 TEPosition( 

620 relative_to.line_position, 

621 relative_to.cursor_position + span[1], 

622 ), 

623 ) 

624 

625 

626def _check_extended_description_line( 

627 description_value_line: Deb822ValueLineElement, 

628 description_line_range_te: "TERange", 

629 package: str | None, 

630 lint_state: LintState, 

631) -> None: 

632 if description_value_line.comment_element is not None: 632 ↛ 635line 632 didn't jump to line 635 because the condition on line 632 was never true

633 # TODO: Fix this limitation (we get the content and the range wrong with comments. 

634 # They are rare inside a Description, so this is a 80:20 trade off 

635 return 

636 description_line_with_leading_space = ( 

637 description_value_line.convert_to_text().rstrip() 

638 ) 

639 try: 

640 idx = description_line_with_leading_space.index( 

641 "<insert long description, indented with spaces>" 

642 ) 

643 except ValueError: 

644 pass 

645 else: 

646 template_span = idx, idx + len( 

647 "<insert long description, indented with spaces>" 

648 ) 

649 lint_state.emit_diagnostic( 

650 _single_line_span_range_relative_to_pos( 

651 template_span, 

652 description_line_range_te.start_pos, 

653 ), 

654 "Unfilled or left-over template from dh_make", 

655 "error", 

656 "debputy", 

657 ) 

658 if len(description_line_with_leading_space) > 80: 

659 # Policy says nothing here, but lintian has 80 characters as hard limit and that 

660 # probably matches the limitation of package manager UIs (TUIs/GUIs) somewhere. 

661 # 

662 # See also debputy#122 

663 span = 80, len(description_line_with_leading_space) 

664 lint_state.emit_diagnostic( 

665 _single_line_span_range_relative_to_pos( 

666 span, 

667 description_line_range_te.start_pos, 

668 ), 

669 "Package description line is too long; please line wrap it.", 

670 "warning", 

671 "debputy", 

672 ) 

673 

674 

675def _check_synopsis( 

676 synopsis_value_line: Deb822ValueLineElement, 

677 synopsis_range_te: "TERange", 

678 field_name_range_te: "TERange", 

679 package: str | None, 

680 lint_state: LintState, 

681) -> None: 

682 # This function would compute range would be wrong if there is a comment 

683 assert synopsis_value_line.comment_element is None 

684 synopsis_text_with_leading_space = synopsis_value_line.convert_to_text().rstrip() 

685 if not synopsis_text_with_leading_space: 

686 lint_state.emit_diagnostic( 

687 field_name_range_te, 

688 "Package synopsis is missing", 

689 "warning", 

690 "debputy", 

691 ) 

692 return 

693 synopsis_text_trimmed = synopsis_text_with_leading_space.lstrip() 

694 synopsis_offset = len(synopsis_text_with_leading_space) - len(synopsis_text_trimmed) 

695 starts_with_article = _RE_SYNOPSIS_STARTS_WITH_ARTICLE.search( 

696 synopsis_text_with_leading_space 

697 ) 

698 # TODO: Handle ${...} expansion 

699 if starts_with_article: 

700 lint_state.emit_diagnostic( 

701 _single_line_span_range_relative_to_pos( 

702 starts_with_article.span(1), 

703 synopsis_range_te.start_pos, 

704 ), 

705 "Package synopsis starts with an article (a/an/the).", 

706 "warning", 

707 "DevRef 6.2.2", 

708 ) 

709 if len(synopsis_text_trimmed) >= 80: 

710 # Policy says `certainly under 80 characters.`, so exactly 80 characters is considered bad too. 

711 span = synopsis_offset + 79, len(synopsis_text_with_leading_space) 

712 lint_state.emit_diagnostic( 

713 _single_line_span_range_relative_to_pos( 

714 span, 

715 synopsis_range_te.start_pos, 

716 ), 

717 "Package synopsis is too long.", 

718 "warning", 

719 "Policy 3.4.1", 

720 ) 

721 if template_match := _RE_SYNOPSIS_IS_TEMPLATE.match( 

722 synopsis_text_with_leading_space 

723 ): 

724 lint_state.emit_diagnostic( 

725 _single_line_span_range_relative_to_pos( 

726 template_match.span(1), 

727 synopsis_range_te.start_pos, 

728 ), 

729 "Package synopsis is a placeholder", 

730 "warning", 

731 "debputy", 

732 ) 

733 elif too_short_match := _RE_SYNOPSIS_IS_TOO_SHORT.match( 

734 synopsis_text_with_leading_space 

735 ): 

736 if not SUBSTVAR_RE.match(synopsis_text_with_leading_space.strip()): 

737 lint_state.emit_diagnostic( 

738 _single_line_span_range_relative_to_pos( 

739 too_short_match.span(1), 

740 synopsis_range_te.start_pos, 

741 ), 

742 "Package synopsis is too short", 

743 "warning", 

744 "debputy", 

745 ) 

746 

747 

748def dctrl_description_validator( 

749 _known_field: "F", 

750 _deb822_file: Deb822FileElement, 

751 kvpair: Deb822KeyValuePairElement, 

752 kvpair_range_te: "TERange", 

753 _field_name_range: "TERange", 

754 stanza: Deb822ParagraphElement, 

755 _stanza_position: "TEPosition", 

756 lint_state: LintState, 

757) -> None: 

758 value_lines = kvpair.value_element.value_lines 

759 if not value_lines: 759 ↛ 760line 759 didn't jump to line 760 because the condition on line 759 was never true

760 return 

761 package = stanza.get("Package") 

762 synopsis_value_line = value_lines[0] 

763 value_range_te = kvpair.value_element.range_in_parent().relative_to( 

764 kvpair_range_te.start_pos 

765 ) 

766 synopsis_line_range_te = synopsis_value_line.range_in_parent().relative_to( 

767 value_range_te.start_pos 

768 ) 

769 if synopsis_value_line.continuation_line_token is None: 769 ↛ 782line 769 didn't jump to line 782 because the condition on line 769 was always true

770 field_name_range_te = kvpair.field_token.range_in_parent().relative_to( 

771 kvpair_range_te.start_pos 

772 ) 

773 _check_synopsis( 

774 synopsis_value_line, 

775 synopsis_line_range_te, 

776 field_name_range_te, 

777 package, 

778 lint_state, 

779 ) 

780 description_lines = value_lines[1:] 

781 else: 

782 description_lines = value_lines 

783 for description_line in description_lines: 

784 description_line_range_te = description_line.range_in_parent().relative_to( 

785 value_range_te.start_pos 

786 ) 

787 _check_extended_description_line( 

788 description_line, 

789 description_line_range_te, 

790 package, 

791 lint_state, 

792 ) 

793 

794 

795def _has_packaging_expected_file( 

796 name: str, 

797 msg: str, 

798 severity: LintSeverity = "error", 

799) -> CustomFieldCheck: 

800 

801 def _impl( 

802 _known_field: "F", 

803 _deb822_file: Deb822FileElement, 

804 _kvpair: Deb822KeyValuePairElement, 

805 kvpair_range_te: "TERange", 

806 _field_name_range_te: "TERange", 

807 _stanza: Deb822ParagraphElement, 

808 _stanza_position: "TEPosition", 

809 lint_state: LintState, 

810 ) -> None: 

811 debian_dir = lint_state.debian_dir 

812 if debian_dir is None: 

813 return 

814 cpy = debian_dir.lookup(name) 

815 if not cpy: 815 ↛ 816line 815 didn't jump to line 816 because the condition on line 815 was never true

816 lint_state.emit_diagnostic( 

817 kvpair_range_te, 

818 msg, 

819 severity, 

820 "debputy", 

821 diagnostic_applies_to_another_file=f"debian/{name}", 

822 ) 

823 

824 return _impl 

825 

826 

827_check_missing_debian_rules = _has_packaging_expected_file( 

828 "rules", 

829 'Missing debian/rules when the Build-Driver is unset or set to "debian-rules"', 

830) 

831 

832 

833def _has_build_instructions( 

834 known_field: "F", 

835 deb822_file: Deb822FileElement, 

836 kvpair: Deb822KeyValuePairElement, 

837 kvpair_range_te: "TERange", 

838 field_name_range_te: "TERange", 

839 stanza: Deb822ParagraphElement, 

840 stanza_position: "TEPosition", 

841 lint_state: LintState, 

842) -> None: 

843 if stanza.get("Build-Driver", "debian-rules").lower() != "debian-rules": 

844 return 

845 

846 _check_missing_debian_rules( 

847 known_field, 

848 deb822_file, 

849 kvpair, 

850 kvpair_range_te, 

851 field_name_range_te, 

852 stanza, 

853 stanza_position, 

854 lint_state, 

855 ) 

856 

857 

858def _canonical_maintainer_name( 

859 known_field: "F", 

860 _deb822_file: Deb822FileElement, 

861 kvpair: Deb822KeyValuePairElement, 

862 kvpair_range_te: "TERange", 

863 _field_name_range_te: "TERange", 

864 _stanza: Deb822ParagraphElement, 

865 _stanza_position: "TEPosition", 

866 lint_state: LintState, 

867) -> None: 

868 value_element_pos = kvpair.value_element.position_in_parent().relative_to( 

869 kvpair_range_te.start_pos 

870 ) 

871 try: 

872 interpreted_value = kvpair.interpret_as( 

873 known_field.field_value_class.interpreter() 

874 ) 

875 except ValueError: 

876 return 

877 

878 for part in interpreted_value.iter_parts(): 

879 if part.is_separator or part.is_whitespace or part.is_whitespace: 

880 continue 

881 name_and_email = part.convert_to_text() 

882 try: 

883 email_start = name_and_email.rindex("<") 

884 email_end = name_and_email.rindex(">") 

885 email = name_and_email[email_start + 1 : email_end] 

886 except IndexError: 

887 continue 

888 

889 pref = lint_state.maint_preference_table.maintainer_preferences.get(email) 

890 if pref is None or not pref.canonical_name: 

891 continue 

892 

893 expected = f"{pref.canonical_name} <{email}>" 

894 if expected == name_and_email: 894 ↛ 895line 894 didn't jump to line 895 because the condition on line 894 was never true

895 continue 

896 value_range_te = part.range_in_parent().relative_to(value_element_pos) 

897 lint_state.emit_diagnostic( 

898 value_range_te, 

899 "Non-canonical or incorrect spelling of maintainer name", 

900 "informational", 

901 "debputy", 

902 quickfixes=[propose_correct_text_quick_fix(expected)], 

903 ) 

904 

905 

906def _maintainer_field_validator( 

907 known_field: "F", 

908 _deb822_file: Deb822FileElement, 

909 kvpair: Deb822KeyValuePairElement, 

910 kvpair_range_te: "TERange", 

911 _field_name_range_te: "TERange", 

912 _stanza: Deb822ParagraphElement, 

913 _stanza_position: "TEPosition", 

914 lint_state: LintState, 

915) -> None: 

916 

917 value_element_pos = kvpair.value_element.position_in_parent().relative_to( 

918 kvpair_range_te.start_pos 

919 ) 

920 interpreted_value = kvpair.interpret_as(known_field.field_value_class.interpreter()) 

921 for part in interpreted_value.iter_parts(): 

922 if not part.is_separator: 

923 continue 

924 value_range_te = part.range_in_parent().relative_to(value_element_pos) 

925 severity = known_field.unknown_value_severity 

926 assert severity is not None 

927 # TODO: Check for a follow up maintainer and based on that the quick fix is either 

928 # to remove the dead separator OR move the trailing data into `Uploaders` 

929 lint_state.emit_diagnostic( 

930 value_range_te, 

931 'The "Maintainer" field has a trailing separator, but it is a single value field.', 

932 severity, 

933 known_field.unknown_value_authority, 

934 ) 

935 

936 

937def _use_https_instead_of_http( 

938 known_field: "F", 

939 _deb822_file: Deb822FileElement, 

940 kvpair: Deb822KeyValuePairElement, 

941 kvpair_range_te: "TERange", 

942 _field_name_range_te: "TERange", 

943 _stanza: Deb822ParagraphElement, 

944 _stanza_position: "TEPosition", 

945 lint_state: LintState, 

946) -> None: 

947 value_element_pos = kvpair.value_element.position_in_parent().relative_to( 

948 kvpair_range_te.start_pos 

949 ) 

950 interpreted_value = kvpair.interpret_as(known_field.field_value_class.interpreter()) 

951 for part in interpreted_value.iter_parts(): 

952 value = part.convert_to_text() 

953 if not value.startswith("http://"): 

954 continue 

955 value_range_te = part.range_in_parent().relative_to(value_element_pos) 

956 problem_range_te = TERange.between( 

957 value_range_te.start_pos, 

958 TEPosition( 

959 value_range_te.start_pos.line_position, 

960 value_range_te.start_pos.cursor_position + 7, 

961 ), 

962 ) 

963 lint_state.emit_diagnostic( 

964 problem_range_te, 

965 "The Format URL should use https:// rather than http://", 

966 "warning", 

967 "debputy", 

968 quickfixes=[propose_correct_text_quick_fix("https://")], 

969 ) 

970 

971 

972def _each_value_match_regex_validation( 

973 regex: re.Pattern, 

974 *, 

975 diagnostic_severity: LintSeverity = "error", 

976 authority_reference: str | None = None, 

977) -> CustomFieldCheck: 

978 

979 def _validator( 

980 known_field: "F", 

981 _deb822_file: Deb822FileElement, 

982 kvpair: Deb822KeyValuePairElement, 

983 kvpair_range_te: "TERange", 

984 _field_name_range_te: "TERange", 

985 _stanza: Deb822ParagraphElement, 

986 _stanza_position: "TEPosition", 

987 lint_state: LintState, 

988 ) -> None: 

989 nonlocal authority_reference 

990 interpreter = known_field.field_value_class.interpreter() 

991 if interpreter is None: 

992 raise AssertionError( 

993 f"{known_field.name} has field type {known_field.field_value_class}, which cannot be" 

994 f" regex validated since it does not have a tokenization" 

995 ) 

996 auth_ref = ( 

997 authority_reference 

998 if authority_reference is not None 

999 else known_field.unknown_value_authority 

1000 ) 

1001 

1002 value_element_pos = kvpair.value_element.position_in_parent().relative_to( 

1003 kvpair_range_te.start_pos 

1004 ) 

1005 for value_ref in kvpair.interpret_as(interpreter).iter_value_references(): 

1006 v = value_ref.value 

1007 m = regex.fullmatch(v) 

1008 if m is not None: 

1009 continue 

1010 

1011 if "${" in v: 

1012 # Ignore substvars 

1013 continue 

1014 

1015 section_value_loc = value_ref.locatable 

1016 value_range_te = section_value_loc.range_in_parent().relative_to( 

1017 value_element_pos 

1018 ) 

1019 lint_state.emit_diagnostic( 

1020 value_range_te, 

1021 f'The value "{v}" does not match the regex {regex.pattern}.', 

1022 diagnostic_severity, 

1023 auth_ref, 

1024 ) 

1025 

1026 return _validator 

1027 

1028 

1029_DEP_OR_RELATION = re.compile(r"[|]") 

1030_DEP_RELATION_CLAUSE = re.compile( 

1031 r""" 

1032 ^ 

1033 \s* 

1034 (?P<name_arch_qual>[-+.a-zA-Z0-9${}:]{2,}) 

1035 \s* 

1036 (?: [(] \s* (?P<operator>>>|>=|>|=|<|<=|<<) \s* (?P<version> [0-9$][^)]*|[$][{]\S+[}]) \s* [)] \s* )? 

1037 (?: \[ (?P<arch_restriction> [\s!\w\-]+) ] \s*)? 

1038 (?: < (?P<build_profile_restriction> .+ ) > \s*)? 

1039 ((?P<garbage>\S.*)\s*)? 

1040 $ 

1041""", 

1042 re.VERBOSE | re.MULTILINE, 

1043) 

1044 

1045 

1046def _span_to_te_range( 

1047 text: str, 

1048 start_pos: int, 

1049 end_pos: int, 

1050) -> TERange: 

1051 prefix = text[0:start_pos] 

1052 prefix_plus_text = text[0:end_pos] 

1053 

1054 start_line = prefix.count("\n") 

1055 if start_line: 

1056 start_newline_offset = prefix.rindex("\n") 

1057 # +1 to skip past the newline 

1058 start_cursor_pos = start_pos - (start_newline_offset + 1) 

1059 else: 

1060 start_cursor_pos = start_pos 

1061 

1062 end_line = prefix_plus_text.count("\n") 

1063 if end_line == start_line: 

1064 end_cursor_pos = start_cursor_pos + (end_pos - start_pos) 

1065 else: 

1066 end_newline_offset = prefix_plus_text.rindex("\n") 

1067 end_cursor_pos = end_pos - (end_newline_offset + 1) 

1068 

1069 return TERange( 

1070 TEPosition( 

1071 start_line, 

1072 start_cursor_pos, 

1073 ), 

1074 TEPosition( 

1075 end_line, 

1076 end_cursor_pos, 

1077 ), 

1078 ) 

1079 

1080 

1081def _split_w_spans( 

1082 v: str, 

1083 sep: str, 

1084 *, 

1085 offset: int = 0, 

1086) -> Sequence[tuple[str, int, int]]: 

1087 separator_size = len(sep) 

1088 parts = v.split(sep) 

1089 for part in parts: 

1090 size = len(part) 

1091 end_offset = offset + size 

1092 yield part, offset, end_offset 

1093 offset = end_offset + separator_size 

1094 

1095 

1096_COLLAPSE_WHITESPACE = re.compile(r"\s+") 

1097 

1098 

1099def _cleanup_rel(rel: str) -> str: 

1100 return _COLLAPSE_WHITESPACE.sub(" ", rel.strip()) 

1101 

1102 

1103def _text_to_te_position(text: str) -> "TEPosition": 

1104 newlines = text.count("\n") 

1105 if not newlines: 

1106 return TEPosition( 

1107 newlines, 

1108 len(text), 

1109 ) 

1110 last_newline_offset = text.rindex("\n") 

1111 line_offset = len(text) - (last_newline_offset + 1) 

1112 return TEPosition( 

1113 newlines, 

1114 line_offset, 

1115 ) 

1116 

1117 

1118@dataclasses.dataclass(slots=True, frozen=True) 

1119class Relation: 

1120 name: str 

1121 arch_qual: str | None = None 

1122 version_operator: str | None = None 

1123 version: str | None = None 

1124 arch_restriction: str | None = None 

1125 build_profile_restriction: str | None = None 

1126 # These offsets are intended to show the relation itself. They are not 

1127 # the relation boundary offsets (they will omit leading whitespace as 

1128 # an example). 

1129 content_display_offset: int = -1 

1130 content_display_end_offset: int = -1 

1131 

1132 

1133def relation_key_variations( 

1134 relation: Relation, 

1135) -> tuple[str, str | None, str | None]: 

1136 operator_variants = ( 

1137 [relation.version_operator, None] 

1138 if relation.version_operator is not None 

1139 else [None] 

1140 ) 

1141 arch_qual_variants = ( 

1142 [relation.arch_qual, None] 

1143 if relation.arch_qual is not None and relation.arch_qual != "any" 

1144 else [None] 

1145 ) 

1146 for arch_qual, version_operator in itertools.product( 

1147 arch_qual_variants, 

1148 operator_variants, 

1149 ): 

1150 yield relation.name, arch_qual, version_operator 

1151 

1152 

1153def dup_check_relations( 

1154 known_field: "F", 

1155 relations: Sequence[Relation], 

1156 raw_value_masked_comments: str, 

1157 value_element_pos: "TEPosition", 

1158 lint_state: LintState, 

1159) -> None: 

1160 overlap_table = {} 

1161 for relation in relations: 

1162 version_operator = relation.version_operator 

1163 arch_qual = relation.arch_qual 

1164 if relation.arch_restriction or relation.build_profile_restriction: 1164 ↛ 1165line 1164 didn't jump to line 1165 because the condition on line 1164 was never true

1165 continue 

1166 

1167 for relation_key in relation_key_variations(relation): 

1168 prev_relation = overlap_table.get(relation_key) 

1169 if prev_relation is None: 

1170 overlap_table[relation_key] = relation 

1171 else: 

1172 prev_version_operator = prev_relation.version_operator 

1173 

1174 if ( 

1175 prev_version_operator 

1176 and version_operator 

1177 and prev_version_operator[0] != version_operator[0] 

1178 and version_operator[0] in ("<", ">") 

1179 and prev_version_operator[0] in ("<", ">") 

1180 ): 

1181 # foo (>= 1), foo (<< 2) and similar should not trigger a warning. 

1182 continue 

1183 

1184 prev_arch_qual = prev_relation.arch_qual 

1185 if ( 

1186 arch_qual != prev_arch_qual 

1187 and prev_arch_qual != "any" 

1188 and arch_qual != "any" 

1189 ): 

1190 # foo:amd64 != foo:native and that might matter - especially for "libfoo-dev, libfoo-dev:native" 

1191 # 

1192 # This check is probably a too forgiving in some corner cases. 

1193 continue 

1194 

1195 if ( 

1196 known_field.name == "Provides" 

1197 and version_operator == "=" 

1198 and prev_version_operator == version_operator 

1199 and relation.version != prev_relation.version 

1200 ): 

1201 # Provides: foo (= 1), foo (= 2) is legal and not mergeable 

1202 continue 

1203 

1204 orig_relation_range = TERange( 

1205 _text_to_te_position( 

1206 raw_value_masked_comments[ 

1207 : prev_relation.content_display_offset 

1208 ] 

1209 ), 

1210 _text_to_te_position( 

1211 raw_value_masked_comments[ 

1212 : prev_relation.content_display_end_offset 

1213 ] 

1214 ), 

1215 ).relative_to(value_element_pos) 

1216 

1217 duplicate_relation_range = TERange( 

1218 _text_to_te_position( 

1219 raw_value_masked_comments[: relation.content_display_offset] 

1220 ), 

1221 _text_to_te_position( 

1222 raw_value_masked_comments[: relation.content_display_end_offset] 

1223 ), 

1224 ).relative_to(value_element_pos) 

1225 

1226 lint_state.emit_diagnostic( 

1227 duplicate_relation_range, 

1228 "Duplicate relationship. Merge with the previous relationship", 

1229 "warning", 

1230 known_field.unknown_value_authority, 

1231 related_information=[ 

1232 lint_state.related_diagnostic_information( 

1233 orig_relation_range, 

1234 "The previous definition", 

1235 ), 

1236 ], 

1237 ) 

1238 # We only emit for the first duplicate "key" for each relation. Odds are remaining 

1239 # keys point to the same match. Even if they do not, it does not really matter as 

1240 # we already pointed out an issue for the user to follow up on. 

1241 break 

1242 

1243 

1244def _dctrl_check_dep_version_operator( 

1245 known_field: "F", 

1246 version_operator: str, 

1247 version_operator_span: tuple[int, int], 

1248 version_operators: frozenset[str], 

1249 raw_value_masked_comments: str, 

1250 offset: int, 

1251 value_element_pos: "TEPosition", 

1252 lint_state: LintState, 

1253) -> bool: 

1254 if ( 

1255 version_operators 

1256 and version_operator is not None 

1257 and version_operator not in version_operators 

1258 ): 

1259 v_start_offset = offset + version_operator_span[0] 

1260 v_end_offset = offset + version_operator_span[1] 

1261 version_problem_range_te = TERange( 

1262 _text_to_te_position(raw_value_masked_comments[:v_start_offset]), 

1263 _text_to_te_position(raw_value_masked_comments[:v_end_offset]), 

1264 ).relative_to(value_element_pos) 

1265 

1266 sorted_version_operators = sorted(version_operators) 

1267 

1268 excluding_equal = f"{version_operator}{version_operator}" 

1269 including_equal = f"{version_operator}=" 

1270 

1271 if version_operator in (">", "<") and ( 

1272 excluding_equal in version_operators or including_equal in version_operators 

1273 ): 

1274 lint_state.emit_diagnostic( 

1275 version_problem_range_te, 

1276 f'Obsolete version operator "{version_operator}" that is no longer supported.', 

1277 "error", 

1278 "Policy 7.1", 

1279 quickfixes=[ 

1280 propose_correct_text_quick_fix(n) 

1281 for n in (excluding_equal, including_equal) 

1282 if not version_operators or n in version_operators 

1283 ], 

1284 ) 

1285 else: 

1286 lint_state.emit_diagnostic( 

1287 version_problem_range_te, 

1288 f'The version operator "{version_operator}" is not allowed in {known_field.name}', 

1289 "error", 

1290 known_field.unknown_value_authority, 

1291 quickfixes=[ 

1292 propose_correct_text_quick_fix(n) for n in sorted_version_operators 

1293 ], 

1294 ) 

1295 return True 

1296 return False 

1297 

1298 

1299def _dctrl_validate_dep( 

1300 known_field: "DF", 

1301 _deb822_file: Deb822FileElement, 

1302 kvpair: Deb822KeyValuePairElement, 

1303 kvpair_range_te: "TERange", 

1304 _field_name_range: "TERange", 

1305 _stanza: Deb822ParagraphElement, 

1306 _stanza_position: "TEPosition", 

1307 lint_state: LintState, 

1308) -> None: 

1309 value_element_pos = kvpair.value_element.position_in_parent().relative_to( 

1310 kvpair_range_te.start_pos 

1311 ) 

1312 raw_value_with_comments = kvpair.value_element.convert_to_text() 

1313 raw_value_masked_comments = "".join( 

1314 (line if not line.startswith("#") else (" " * (len(line) - 1)) + "\n") 

1315 for line in raw_value_with_comments.splitlines(keepends=True) 

1316 ) 

1317 if isinstance(known_field, DctrlRelationshipKnownField): 

1318 version_operators = known_field.allowed_version_operators 

1319 supports_or_relation = known_field.supports_or_relation 

1320 else: 

1321 version_operators = frozenset({">>", ">=", "=", "<=", "<<"}) 

1322 supports_or_relation = True 

1323 

1324 relation_dup_table = collections.defaultdict(list) 

1325 

1326 for rel, rel_offset, rel_end_offset in _split_w_spans( 

1327 raw_value_masked_comments, "," 

1328 ): 

1329 sub_relations = [] 

1330 for or_rel, offset, end_offset in _split_w_spans(rel, "|", offset=rel_offset): 

1331 if or_rel.isspace(): 

1332 continue 

1333 if sub_relations and not supports_or_relation: 

1334 separator_range_te = TERange( 

1335 _text_to_te_position(raw_value_masked_comments[: offset - 1]), 

1336 _text_to_te_position(raw_value_masked_comments[:offset]), 

1337 ).relative_to(value_element_pos) 

1338 lint_state.emit_diagnostic( 

1339 separator_range_te, 

1340 f'The field {known_field.name} does not support "|" (OR) in relations.', 

1341 "error", 

1342 known_field.unknown_value_authority, 

1343 ) 

1344 m = _DEP_RELATION_CLAUSE.fullmatch(or_rel) 

1345 

1346 if m is not None: 

1347 garbage = m.group("garbage") 

1348 version_operator = m.group("operator") 

1349 version_operator_span = m.span("operator") 

1350 if _dctrl_check_dep_version_operator( 

1351 known_field, 

1352 version_operator, 

1353 version_operator_span, 

1354 version_operators, 

1355 raw_value_masked_comments, 

1356 offset, 

1357 value_element_pos, 

1358 lint_state, 

1359 ): 

1360 sub_relations.append(Relation("<BROKEN>")) 

1361 else: 

1362 name_arch_qual = m.group("name_arch_qual") 

1363 if ":" in name_arch_qual: 

1364 name, arch_qual = name_arch_qual.split(":", 1) 

1365 else: 

1366 name = name_arch_qual 

1367 arch_qual = None 

1368 sub_relations.append( 

1369 Relation( 

1370 name, 

1371 arch_qual=arch_qual, 

1372 version_operator=version_operator, 

1373 version=m.group("version"), 

1374 arch_restriction=m.group("build_profile_restriction"), 

1375 build_profile_restriction=m.group( 

1376 "build_profile_restriction" 

1377 ), 

1378 content_display_offset=offset + m.start("name_arch_qual"), 

1379 # TODO: This should be trimmed in the end. 

1380 content_display_end_offset=rel_end_offset, 

1381 ) 

1382 ) 

1383 else: 

1384 garbage = None 

1385 sub_relations.append(Relation("<BROKEN>")) 

1386 

1387 if m is not None and not garbage: 

1388 continue 

1389 if m is not None: 

1390 garbage_span = m.span("garbage") 

1391 garbage_start, garbage_end = garbage_span 

1392 error_start_offset = offset + garbage_start 

1393 error_end_offset = offset + garbage_end 

1394 garbage_part = raw_value_masked_comments[ 

1395 error_start_offset:error_end_offset 

1396 ] 

1397 else: 

1398 garbage_part = None 

1399 error_start_offset = offset 

1400 error_end_offset = end_offset 

1401 

1402 problem_range_te = TERange( 

1403 _text_to_te_position(raw_value_masked_comments[:error_start_offset]), 

1404 _text_to_te_position(raw_value_masked_comments[:error_end_offset]), 

1405 ).relative_to(value_element_pos) 

1406 

1407 if garbage_part is not None: 

1408 if _DEP_RELATION_CLAUSE.fullmatch(garbage_part) is not None: 

1409 msg = ( 

1410 "Trailing data after a relationship that might be a second relationship." 

1411 " Is a separator missing before this part?" 

1412 ) 

1413 else: 

1414 msg = "Parse error of the relationship. Either a syntax error or a missing separator somewhere." 

1415 lint_state.emit_diagnostic( 

1416 problem_range_te, 

1417 msg, 

1418 "error", 

1419 known_field.unknown_value_authority, 

1420 ) 

1421 else: 

1422 dep = _cleanup_rel( 

1423 raw_value_masked_comments[error_start_offset:error_end_offset] 

1424 ) 

1425 lint_state.emit_diagnostic( 

1426 problem_range_te, 

1427 f'Could not parse "{dep}" as a dependency relation.', 

1428 "error", 

1429 known_field.unknown_value_authority, 

1430 ) 

1431 if ( 

1432 len(sub_relations) == 1 

1433 and (relation := sub_relations[0]).name != "<BROKEN>" 

1434 ): 

1435 # We ignore OR-relations in the dup-check for now. We also skip relations with problems. 

1436 relation_dup_table[relation.name].append(relation) 

1437 

1438 for relations in relation_dup_table.values(): 

1439 if len(relations) > 1: 

1440 dup_check_relations( 

1441 known_field, 

1442 relations, 

1443 raw_value_masked_comments, 

1444 value_element_pos, 

1445 lint_state, 

1446 ) 

1447 

1448 

1449def _rrr_build_driver_mismatch( 

1450 _known_field: "F", 

1451 _deb822_file: Deb822FileElement, 

1452 _kvpair: Deb822KeyValuePairElement, 

1453 kvpair_range_te: "TERange", 

1454 _field_name_range: "TERange", 

1455 stanza: Deb822ParagraphElement, 

1456 _stanza_position: "TEPosition", 

1457 lint_state: LintState, 

1458) -> None: 

1459 dr = stanza.get("Build-Driver", "debian-rules") 

1460 if dr != "debian-rules": 

1461 lint_state.emit_diagnostic( 

1462 kvpair_range_te, 

1463 f'The Rules-Requires-Root field is irrelevant for the Build-Driver "{dr}".', 

1464 "informational", 

1465 "debputy", 

1466 quickfixes=[ 

1467 propose_remove_range_quick_fix( 

1468 proposed_title="Remove Rules-Requires-Root" 

1469 ) 

1470 ], 

1471 ) 

1472 

1473 

1474class Dep5Matcher(BasenameGlobMatch): 

1475 def __init__(self, basename_glob: str) -> None: 

1476 super().__init__( 

1477 basename_glob, 

1478 only_when_in_directory=None, 

1479 path_type=None, 

1480 recursive_match=False, 

1481 ) 

1482 

1483 

1484def _match_dep5_segment( 

1485 current_dir: VirtualPathBase, basename_glob: str 

1486) -> Iterable[VirtualPathBase]: 

1487 if "*" in basename_glob or "?" in basename_glob: 

1488 return Dep5Matcher(basename_glob).finditer(current_dir) 

1489 else: 

1490 res = current_dir.get(basename_glob) 

1491 if res is None: 

1492 return tuple() 

1493 return (res,) 

1494 

1495 

1496_RE_SLASHES = re.compile(r"//+") 

1497 

1498 

1499def _dep5_unnecessary_symbols( 

1500 value: str, 

1501 value_range: TERange, 

1502 lint_state: LintState, 

1503) -> None: 

1504 slash_check_index = 0 

1505 if value.startswith(("./", "/")): 

1506 prefix_len = 1 if value[0] == "/" else 2 

1507 if value[prefix_len - 1 : prefix_len + 2].startswith("//"): 1507 ↛ 1511line 1507 didn't jump to line 1511 because the condition on line 1507 was always true

1508 _, slashes_end = _RE_SLASHES.search(value).span() 

1509 prefix_len = slashes_end 

1510 

1511 slash_check_index = prefix_len 

1512 prefix_range = TERange( 

1513 value_range.start_pos, 

1514 TEPosition( 

1515 value_range.start_pos.line_position, 

1516 value_range.start_pos.cursor_position + prefix_len, 

1517 ), 

1518 ) 

1519 lint_state.emit_diagnostic( 

1520 prefix_range, 

1521 f'Unnecessary prefix "{value[0:prefix_len]}"', 

1522 "warning", 

1523 "debputy", 

1524 quickfixes=[ 

1525 propose_remove_range_quick_fix( 

1526 proposed_title=f'Delete "{value[0:prefix_len]}"' 

1527 ) 

1528 ], 

1529 ) 

1530 

1531 for m in _RE_SLASHES.finditer(value, slash_check_index): 

1532 m_start, m_end = m.span(0) 

1533 

1534 prefix_range = TERange( 

1535 TEPosition( 

1536 value_range.start_pos.line_position, 

1537 value_range.start_pos.cursor_position + m_start, 

1538 ), 

1539 TEPosition( 

1540 value_range.start_pos.line_position, 

1541 value_range.start_pos.cursor_position + m_end, 

1542 ), 

1543 ) 

1544 lint_state.emit_diagnostic( 

1545 prefix_range, 

1546 'Simplify to a single "/"', 

1547 "warning", 

1548 "debputy", 

1549 quickfixes=[propose_correct_text_quick_fix("/")], 

1550 ) 

1551 

1552 

1553def _dep5_files_check( 

1554 known_field: "F", 

1555 _deb822_file: Deb822FileElement, 

1556 kvpair: Deb822KeyValuePairElement, 

1557 kvpair_range_te: "TERange", 

1558 _field_name_range: "TERange", 

1559 _stanza: Deb822ParagraphElement, 

1560 _stanza_position: "TEPosition", 

1561 lint_state: LintState, 

1562) -> None: 

1563 interpreter = known_field.field_value_class.interpreter() 

1564 assert interpreter is not None 

1565 full_value_range = kvpair.value_element.range_in_parent().relative_to( 

1566 kvpair_range_te.start_pos 

1567 ) 

1568 values_with_ranges = [] 

1569 for value_ref in kvpair.interpret_as(interpreter).iter_value_references(): 

1570 value_range = value_ref.locatable.range_in_parent().relative_to( 

1571 full_value_range.start_pos 

1572 ) 

1573 value = value_ref.value 

1574 values_with_ranges.append((value_ref.value, value_range)) 

1575 _dep5_unnecessary_symbols(value, value_range, lint_state) 

1576 

1577 source_root = lint_state.source_root 

1578 if source_root is None: 

1579 return 

1580 i = 0 

1581 limit = len(values_with_ranges) 

1582 while i < limit: 

1583 value, value_range = values_with_ranges[i] 

1584 i += 1 

1585 

1586 

1587_HOMEPAGE_CLUTTER_RE = re.compile(r"<(?:UR[LI]:)?(.*)>") 

1588_URI_RE = re.compile(r"(?P<protocol>[a-z0-9]+)://(?P<host>[^\s/+]+)(?P<path>/[^\s?]*)?") 

1589_KNOWN_HTTPS_HOSTS = frozenset( 

1590 [ 

1591 "debian.org", 

1592 "bioconductor.org", 

1593 "cran.r-project.org", 

1594 "github.com", 

1595 "gitlab.com", 

1596 "metacpan.org", 

1597 "gnu.org", 

1598 ] 

1599) 

1600_REPLACED_HOSTS = frozenset({"alioth.debian.org"}) 

1601_NO_DOT_GIT_HOMEPAGE_HOSTS = frozenset( 

1602 { 

1603 "salsa.debian.org", 

1604 "github.com", 

1605 "gitlab.com", 

1606 } 

1607) 

1608 

1609 

1610def _is_known_host(host: str, known_hosts: Container[str]) -> bool: 

1611 if host in known_hosts: 

1612 return True 

1613 while host: 1613 ↛ 1621line 1613 didn't jump to line 1621 because the condition on line 1613 was always true

1614 try: 

1615 idx = host.index(".") 

1616 host = host[idx + 1 :] 

1617 except ValueError: 

1618 break 

1619 if host in known_hosts: 

1620 return True 

1621 return False 

1622 

1623 

1624def _validate_homepage_field( 

1625 _known_field: "F", 

1626 _deb822_file: Deb822FileElement, 

1627 kvpair: Deb822KeyValuePairElement, 

1628 kvpair_range_te: "TERange", 

1629 _field_name_range_te: "TERange", 

1630 _stanza: Deb822ParagraphElement, 

1631 _stanza_position: "TEPosition", 

1632 lint_state: LintState, 

1633) -> None: 

1634 value = kvpair.value_element.convert_to_text() 

1635 offset = 0 

1636 homepage = value 

1637 if "<" in value and (m := _HOMEPAGE_CLUTTER_RE.search(value)): 

1638 expected_value = m.group(1) 

1639 quickfixes = [] 

1640 if expected_value: 1640 ↛ 1644line 1640 didn't jump to line 1644 because the condition on line 1640 was always true

1641 homepage = expected_value.strip() 

1642 offset = m.start(1) 

1643 quickfixes.append(propose_correct_text_quick_fix(expected_value)) 

1644 lint_state.emit_diagnostic( 

1645 _single_line_span_range_relative_to_pos( 

1646 m.span(), 

1647 kvpair.value_element.position_in_parent().relative_to( 

1648 kvpair_range_te.start_pos 

1649 ), 

1650 ), 

1651 "Superfluous URL/URI wrapping", 

1652 "informational", 

1653 "Policy 5.6.23", 

1654 quickfixes=quickfixes, 

1655 ) 

1656 # Note falling through here can cause "two rounds" for debputy lint --auto-fix 

1657 m = _URI_RE.search(homepage) 

1658 if not m: 1658 ↛ 1659line 1658 didn't jump to line 1659 because the condition on line 1658 was never true

1659 return 

1660 # TODO relative to lintian: `bad-homepage` and most of the `fields/bad-homepages` hints. 

1661 protocol = m.group("protocol") 

1662 host = m.group("host") 

1663 path = m.group("path") or "" 

1664 if _is_known_host(host, _REPLACED_HOSTS): 

1665 span = m.span("host") 

1666 lint_state.emit_diagnostic( 

1667 _single_line_span_range_relative_to_pos( 

1668 (span[0] + offset, span[1] + offset), 

1669 kvpair.value_element.position_in_parent().relative_to( 

1670 kvpair_range_te.start_pos 

1671 ), 

1672 ), 

1673 f'The server "{host}" is no longer in use.', 

1674 "warning", 

1675 "debputy", 

1676 ) 

1677 return 

1678 if ( 

1679 protocol == "ftp" 

1680 or protocol == "http" 

1681 and _is_known_host(host, _KNOWN_HTTPS_HOSTS) 

1682 ): 

1683 span = m.span("protocol") 

1684 if protocol == "ftp" and not _is_known_host(host, _KNOWN_HTTPS_HOSTS): 1684 ↛ 1685line 1684 didn't jump to line 1685 because the condition on line 1684 was never true

1685 msg = "Insecure protocol for website (check if a https:// variant is available)" 

1686 quickfixes = [] 

1687 else: 

1688 msg = "Replace with https://. The host is known to support https" 

1689 quickfixes = [propose_correct_text_quick_fix("https")] 

1690 lint_state.emit_diagnostic( 

1691 _single_line_span_range_relative_to_pos( 

1692 (span[0] + offset, span[1] + offset), 

1693 kvpair.value_element.position_in_parent().relative_to( 

1694 kvpair_range_te.start_pos 

1695 ), 

1696 ), 

1697 msg, 

1698 "pedantic", 

1699 "debputy", 

1700 quickfixes=quickfixes, 

1701 ) 

1702 if path.endswith(".git") and _is_known_host(host, _NO_DOT_GIT_HOMEPAGE_HOSTS): 

1703 span = m.span("path") 

1704 msg = "Unnecessary suffix" 

1705 quickfixes = [propose_correct_text_quick_fix(path[:-4])] 

1706 lint_state.emit_diagnostic( 

1707 _single_line_span_range_relative_to_pos( 

1708 (span[1] - 4 + offset, span[1] + offset), 

1709 kvpair.value_element.position_in_parent().relative_to( 

1710 kvpair_range_te.start_pos 

1711 ), 

1712 ), 

1713 msg, 

1714 "pedantic", 

1715 "debputy", 

1716 quickfixes=quickfixes, 

1717 ) 

1718 

1719 

1720def _combined_custom_field_check(*checks: CustomFieldCheck) -> CustomFieldCheck: 

1721 def _validator( 

1722 known_field: "F", 

1723 deb822_file: Deb822FileElement, 

1724 kvpair: Deb822KeyValuePairElement, 

1725 kvpair_range_te: "TERange", 

1726 field_name_range_te: "TERange", 

1727 stanza: Deb822ParagraphElement, 

1728 stanza_position: "TEPosition", 

1729 lint_state: LintState, 

1730 ) -> None: 

1731 for check in checks: 

1732 check( 

1733 known_field, 

1734 deb822_file, 

1735 kvpair, 

1736 kvpair_range_te, 

1737 field_name_range_te, 

1738 stanza, 

1739 stanza_position, 

1740 lint_state, 

1741 ) 

1742 

1743 return _validator 

1744 

1745 

1746@dataclasses.dataclass(slots=True, frozen=True) 

1747class PackageNameSectionRule: 

1748 section: str 

1749 check: Callable[[str], bool] 

1750 

1751 

1752def _package_name_section_rule( 

1753 section: str, 

1754 check: Callable[[str], bool] | re.Pattern, 

1755 *, 

1756 confirm_re: re.Pattern | None = None, 

1757) -> PackageNameSectionRule: 

1758 if confirm_re is not None: 

1759 assert callable(check) 

1760 

1761 def _impl(v: str) -> bool: 

1762 return check(v) and confirm_re.search(v) 

1763 

1764 elif isinstance(check, re.Pattern): 1764 ↛ 1766line 1764 didn't jump to line 1766 because the condition on line 1764 was never true

1765 

1766 def _impl(v: str) -> bool: 

1767 return check.search(v) is not None 

1768 

1769 else: 

1770 _impl = check 

1771 

1772 return PackageNameSectionRule(section, _impl) 

1773 

1774 

1775# rules: order is important (first match wins in case of a conflict) 

1776_PKGNAME_VS_SECTION_RULES = [ 

1777 _package_name_section_rule("debian-installer", lambda n: n.endswith("-udeb")), 

1778 _package_name_section_rule("doc", lambda n: n.endswith(("-doc", "-docs"))), 

1779 _package_name_section_rule("debug", lambda n: n.endswith(("-dbg", "-dbgsym"))), 

1780 _package_name_section_rule( 

1781 "httpd", 

1782 lambda n: n.startswith(("lighttpd-mod", "libapache2-mod-", "libnginx-mod-")), 

1783 ), 

1784 _package_name_section_rule("gnustep", lambda n: n.startswith("gnustep-")), 

1785 _package_name_section_rule( 

1786 "gnustep", 

1787 lambda n: n.endswith( 

1788 ( 

1789 ".framework", 

1790 ".framework-common", 

1791 ".tool", 

1792 ".tool-common", 

1793 ".app", 

1794 ".app-common", 

1795 ) 

1796 ), 

1797 ), 

1798 _package_name_section_rule("embedded", lambda n: n.startswith("moblin-")), 

1799 _package_name_section_rule("javascript", lambda n: n.startswith("node-")), 

1800 _package_name_section_rule( 

1801 "zope", 

1802 lambda n: n.startswith(("python-zope", "python3-zope", "zope")), 

1803 ), 

1804 _package_name_section_rule( 

1805 "python", 

1806 lambda n: n.startswith(("python-", "python3-")), 

1807 ), 

1808 _package_name_section_rule( 

1809 "gnu-r", 

1810 lambda n: n.startswith(("r-cran-", "r-bioc-", "r-other-")), 

1811 ), 

1812 _package_name_section_rule("editors", lambda n: n.startswith("elpa-")), 

1813 _package_name_section_rule("lisp", lambda n: n.startswith("cl-")), 

1814 _package_name_section_rule( 

1815 "lisp", 

1816 lambda n: "-elisp-" in n or n.endswith("-elisp"), 

1817 ), 

1818 _package_name_section_rule( 

1819 "lisp", 

1820 lambda n: n.startswith("lib") and n.endswith("-guile"), 

1821 ), 

1822 _package_name_section_rule("lisp", lambda n: n.startswith("guile-")), 

1823 _package_name_section_rule("golang", lambda n: n.startswith("golang-")), 

1824 _package_name_section_rule( 

1825 "perl", 

1826 lambda n: n.startswith("lib") and n.endswith("-perl"), 

1827 ), 

1828 _package_name_section_rule( 

1829 "cli-mono", 

1830 lambda n: n.startswith("lib") and n.endswith(("-cil", "-cil-dev")), 

1831 ), 

1832 _package_name_section_rule( 

1833 "java", 

1834 lambda n: n.startswith("lib") and n.endswith(("-java", "-gcj", "-jni")), 

1835 ), 

1836 _package_name_section_rule( 

1837 "php", 

1838 lambda n: n.startswith(("libphp", "php")), 

1839 confirm_re=re.compile(r"^(?:lib)?php(?:\d(?:\.\d)?)?-"), 

1840 ), 

1841 _package_name_section_rule( 

1842 "php", lambda n: n.startswith("lib-") and n.endswith("-php") 

1843 ), 

1844 _package_name_section_rule( 

1845 "haskell", 

1846 lambda n: n.startswith(("haskell-", "libhugs-", "libghc-", "libghc6-")), 

1847 ), 

1848 _package_name_section_rule( 

1849 "ruby", 

1850 lambda n: "-ruby" in n, 

1851 confirm_re=re.compile(r"^lib.*-ruby(?:1\.\d)?$"), 

1852 ), 

1853 _package_name_section_rule("ruby", lambda n: n.startswith("ruby-")), 

1854 _package_name_section_rule( 

1855 "rust", 

1856 lambda n: n.startswith("librust-") and n.endswith("-dev"), 

1857 ), 

1858 _package_name_section_rule("rust", lambda n: n.startswith("rust-")), 

1859 _package_name_section_rule( 

1860 "ocaml", 

1861 lambda n: n.startswith("lib-") and n.endswith(("-ocaml-dev", "-camlp4-dev")), 

1862 ), 

1863 _package_name_section_rule("javascript", lambda n: n.startswith("libjs-")), 

1864 _package_name_section_rule( 

1865 "interpreters", 

1866 lambda n: n.startswith("lib-") and n.endswith(("-tcl", "-lua", "-gst")), 

1867 ), 

1868 _package_name_section_rule( 

1869 "introspection", 

1870 lambda n: n.startswith("gir-"), 

1871 confirm_re=re.compile(r"^gir\d+\.\d+-.*-\d+\.\d+$"), 

1872 ), 

1873 _package_name_section_rule( 

1874 "fonts", 

1875 lambda n: n.startswith(("xfonts-", "fonts-", "ttf-")), 

1876 ), 

1877 _package_name_section_rule("admin", lambda n: n.startswith(("libnss-", "libpam-"))), 

1878 _package_name_section_rule( 

1879 "localization", 

1880 lambda n: n.startswith( 

1881 ( 

1882 "aspell-", 

1883 "hunspell-", 

1884 "myspell-", 

1885 "mythes-", 

1886 "dict-freedict-", 

1887 "gcompris-sound-", 

1888 ) 

1889 ), 

1890 ), 

1891 _package_name_section_rule( 

1892 "localization", 

1893 lambda n: n.startswith("hyphen-"), 

1894 confirm_re=re.compile(r"^hyphen-[a-z]{2}(?:-[a-z]{2})?$"), 

1895 ), 

1896 _package_name_section_rule( 

1897 "localization", 

1898 lambda n: "-l10n-" in n or n.endswith("-l10n"), 

1899 ), 

1900 _package_name_section_rule("kernel", lambda n: n.endswith(("-dkms", "-firmware"))), 

1901 _package_name_section_rule( 

1902 "libdevel", 

1903 lambda n: n.startswith("lib") and n.endswith(("-dev", "-headers")), 

1904 ), 

1905 _package_name_section_rule( 

1906 "libs", 

1907 lambda n: n.startswith("lib"), 

1908 confirm_re=re.compile(r"^lib.*\d[ad]?$"), 

1909 ), 

1910] 

1911 

1912 

1913# Fiddling with the package name can cause a lot of changes (diagnostic scans), so we have an upper bound 

1914# on the cache. The number is currently just taken out of a hat. 

1915@functools.lru_cache(64) 

1916def package_name_to_section(name: str) -> str | None: 

1917 for rule in _PKGNAME_VS_SECTION_RULES: 

1918 if rule.check(name): 

1919 return rule.section 

1920 return None 

1921 

1922 

1923def _unknown_value_check( 

1924 field_name: str, 

1925 value: str, 

1926 known_values: Mapping[str, Keyword], 

1927 unknown_value_severity: LintSeverity | None, 

1928) -> tuple[Keyword | None, str | None, LintSeverity | None, Any | None]: 

1929 known_value = known_values.get(value) 

1930 message = None 

1931 severity = unknown_value_severity 

1932 fix_data = None 

1933 if known_value is None: 

1934 candidates = detect_possible_typo( 

1935 value, 

1936 known_values, 

1937 ) 

1938 if len(known_values) < 5: 1938 ↛ 1939line 1938 didn't jump to line 1939 because the condition on line 1938 was never true

1939 values = ", ".join(sorted(known_values)) 

1940 hint_text = f" Known values for this field: {values}" 

1941 else: 

1942 hint_text = "" 

1943 fix_data = None 

1944 severity = unknown_value_severity 

1945 fix_text = hint_text 

1946 if candidates: 

1947 match = candidates[0] 

1948 if len(candidates) == 1: 1948 ↛ 1950line 1948 didn't jump to line 1950 because the condition on line 1948 was always true

1949 known_value = known_values[match] 

1950 fix_text = ( 

1951 f' It is possible that the value is a typo of "{match}".{fix_text}' 

1952 ) 

1953 fix_data = [propose_correct_text_quick_fix(m) for m in candidates] 

1954 elif severity is None: 1954 ↛ 1955line 1954 didn't jump to line 1955 because the condition on line 1954 was never true

1955 return None, None, None, None 

1956 if severity is None: 

1957 severity = cast("LintSeverity", "warning") 

1958 # It always has leading whitespace 

1959 message = fix_text.strip() 

1960 else: 

1961 message = f'The value "{value}" is not supported in {field_name}.{fix_text}' 

1962 return known_value, message, severity, fix_data 

1963 

1964 

1965def _dep5_escape_path(path: str) -> str: 

1966 return path.replace(" ", "?") 

1967 

1968 

1969def _noop_escape_path(path: str) -> str: 

1970 return path 

1971 

1972 

1973def _should_ignore_dir( 

1974 path: VirtualPath, 

1975 *, 

1976 supports_dir_match: bool = False, 

1977 match_non_persistent_paths: bool = False, 

1978) -> bool: 

1979 if not supports_dir_match and not any(path.iterdir()): 

1980 return True 

1981 cachedir_tag = path.get("CACHEDIR.TAG") 

1982 if ( 

1983 not match_non_persistent_paths 

1984 and cachedir_tag is not None 

1985 and cachedir_tag.is_file 

1986 ): 

1987 # https://bford.info/cachedir/ 

1988 with cachedir_tag.open(byte_io=True, buffering=64) as fd: 

1989 start = fd.read(43) 

1990 if start == b"Signature: 8a477f597d28d172789f06886806bc55": 

1991 return True 

1992 return False 

1993 

1994 

1995@dataclasses.dataclass(slots=True) 

1996class Deb822KnownField: 

1997 name: str 

1998 field_value_class: FieldValueClass 

1999 warn_if_default: bool = True 

2000 unknown_value_authority: str = "debputy" 

2001 missing_field_authority: str = "debputy" 

2002 replaced_by: str | None = None 

2003 deprecated_with_no_replacement: bool = False 

2004 missing_field_severity: LintSeverity | None = None 

2005 default_value: str | None = None 

2006 known_values: Mapping[str, Keyword] | None = None 

2007 unknown_value_severity: LintSeverity | None = "error" 

2008 translation_context: str = "" 

2009 # One-line description for space-constrained docs (such as completion docs) 

2010 synopsis: str | None = None 

2011 usage_hint: UsageHint | None = None 

2012 long_description: str | None = None 

2013 spellcheck_value: bool = False 

2014 inheritable_from_other_stanza: bool = False 

2015 show_as_inherited: bool = True 

2016 custom_field_check: CustomFieldCheck | None = None 

2017 can_complete_field_in_stanza: None | ( 

2018 Callable[[Iterable[Deb822ParagraphElement]], bool] 

2019 ) = None 

2020 is_substvars_disabled_even_if_allowed_by_stanza: bool = False 

2021 is_alias_of: str | None = None 

2022 is_completion_suggestion: bool = True 

2023 

2024 def synopsis_translated( 

2025 self, translation_provider: Union["DebputyLanguageServer", "LintState"] 

2026 ) -> str | None: 

2027 if self.synopsis is None: 

2028 return None 

2029 return translation_provider.translation(LSP_DATA_DOMAIN).pgettext( 

2030 self.translation_context, 

2031 self.synopsis, 

2032 ) 

2033 

2034 def long_description_translated( 

2035 self, translation_provider: Union["DebputyLanguageServer", "LintState"] 

2036 ) -> str | None: 

2037 if self.long_description_translated is None: 2037 ↛ 2038line 2037 didn't jump to line 2038 because the condition on line 2037 was never true

2038 return None 

2039 return translation_provider.translation(LSP_DATA_DOMAIN).pgettext( 

2040 self.translation_context, 

2041 self.long_description, 

2042 ) 

2043 

2044 def _can_complete_field_in_stanza( 

2045 self, 

2046 stanza_parts: Sequence[Deb822ParagraphElement], 

2047 ) -> bool: 

2048 if not self.is_completion_suggestion: 2048 ↛ 2049line 2048 didn't jump to line 2049 because the condition on line 2048 was never true

2049 return False 

2050 return ( 

2051 self.can_complete_field_in_stanza is None 

2052 or self.can_complete_field_in_stanza(stanza_parts) 

2053 ) 

2054 

2055 def complete_field( 

2056 self, 

2057 lint_state: LintState, 

2058 stanza_parts: Sequence[Deb822ParagraphElement], 

2059 markdown_kind: MarkupKind, 

2060 ) -> CompletionItem | None: 

2061 if not self._can_complete_field_in_stanza(stanza_parts): 

2062 return None 

2063 name = self.name 

2064 complete_as = name + ": " 

2065 options = self.value_options_for_completer( 

2066 lint_state, 

2067 stanza_parts, 

2068 "", 

2069 markdown_kind, 

2070 is_completion_for_field=True, 

2071 ) 

2072 if options is not None and len(options) == 1: 

2073 value = options[0].insert_text 

2074 if value is not None: 2074 ↛ 2076line 2074 didn't jump to line 2076 because the condition on line 2074 was always true

2075 complete_as += value 

2076 tags = [] 

2077 is_deprecated = False 

2078 if self.replaced_by or self.deprecated_with_no_replacement: 

2079 is_deprecated = True 

2080 tags.append(CompletionItemTag.Deprecated) 

2081 

2082 doc = self.long_description 

2083 if doc: 

2084 doc = MarkupContent( 

2085 value=doc, 

2086 kind=markdown_kind, 

2087 ) 

2088 else: 

2089 doc = None 

2090 

2091 return CompletionItem( 

2092 name, 

2093 insert_text=complete_as, 

2094 deprecated=is_deprecated, 

2095 tags=tags, 

2096 detail=format_comp_item_synopsis_doc( 

2097 self.usage_hint, 

2098 self.synopsis_translated(lint_state), 

2099 is_deprecated, 

2100 ), 

2101 documentation=doc, 

2102 ) 

2103 

2104 def _complete_files( 

2105 self, 

2106 base_dir: VirtualPathBase | None, 

2107 value_being_completed: str, 

2108 *, 

2109 is_dep5_file_list: bool = False, 

2110 supports_dir_match: bool = False, 

2111 supports_spaces_in_filename: bool = False, 

2112 match_non_persistent_paths: bool = False, 

2113 ) -> Sequence[CompletionItem] | None: 

2114 _info(f"_complete_files: {base_dir.fs_path} - {value_being_completed!r}") 

2115 if base_dir is None or not base_dir.is_dir: 

2116 return None 

2117 

2118 if is_dep5_file_list: 

2119 supports_spaces_in_filename = True 

2120 supports_dir_match = False 

2121 match_non_persistent_paths = False 

2122 

2123 if value_being_completed == "": 

2124 current_dir = base_dir 

2125 unmatched_parts: Sequence[str] = () 

2126 else: 

2127 current_dir, unmatched_parts = base_dir.attempt_lookup( 

2128 value_being_completed 

2129 ) 

2130 

2131 if len(unmatched_parts) > 1: 

2132 # Unknown directory part / glob, and we currently do not deal with that. 

2133 return None 

2134 if len(unmatched_parts) == 1 and unmatched_parts[0] == "*": 

2135 # Avoid convincing the client to remove the star (seen with emacs) 

2136 return None 

2137 items = [] 

2138 

2139 path_escaper = _dep5_escape_path if is_dep5_file_list else _noop_escape_path 

2140 

2141 for child in current_dir.iterdir(): 

2142 if child.is_symlink and is_dep5_file_list: 

2143 continue 

2144 if not supports_spaces_in_filename and ( 

2145 " " in child.name or "\t" in child.name 

2146 ): 

2147 continue 

2148 sort_text = ( 

2149 f"z-{child.name}" if child.name.startswith(".") else f"a-{child.name}" 

2150 ) 

2151 if child.is_dir: 

2152 if _should_ignore_dir( 

2153 child, 

2154 supports_dir_match=supports_dir_match, 

2155 match_non_persistent_paths=match_non_persistent_paths, 

2156 ): 

2157 continue 

2158 items.append( 

2159 CompletionItem( 

2160 f"{child.path}/", 

2161 label_details=CompletionItemLabelDetails( 

2162 description=child.path, 

2163 ), 

2164 insert_text=path_escaper(f"{child.path}/"), 

2165 filter_text=f"{child.path}/", 

2166 sort_text=sort_text, 

2167 kind=CompletionItemKind.Folder, 

2168 ) 

2169 ) 

2170 else: 

2171 items.append( 

2172 CompletionItem( 

2173 child.path, 

2174 label_details=CompletionItemLabelDetails( 

2175 description=child.path, 

2176 ), 

2177 insert_text=path_escaper(child.path), 

2178 filter_text=child.path, 

2179 sort_text=sort_text, 

2180 kind=CompletionItemKind.File, 

2181 ) 

2182 ) 

2183 return items 

2184 

2185 def value_options_for_completer( 

2186 self, 

2187 lint_state: LintState, 

2188 stanza_parts: Sequence[Deb822ParagraphElement], 

2189 value_being_completed: str, 

2190 markdown_kind: MarkupKind, 

2191 *, 

2192 is_completion_for_field: bool = False, 

2193 ) -> Sequence[CompletionItem] | None: 

2194 known_values = self.known_values 

2195 if self.field_value_class == FieldValueClass.DEP5_FILE_LIST: 2195 ↛ 2196line 2195 didn't jump to line 2196 because the condition on line 2195 was never true

2196 if is_completion_for_field: 

2197 return None 

2198 return self._complete_files( 

2199 lint_state.source_root, 

2200 value_being_completed, 

2201 is_dep5_file_list=True, 

2202 ) 

2203 

2204 if known_values is None: 

2205 return None 

2206 if is_completion_for_field and ( 

2207 len(known_values) == 1 

2208 or ( 

2209 len(known_values) == 2 

2210 and self.warn_if_default 

2211 and self.default_value is not None 

2212 ) 

2213 ): 

2214 value = next( 

2215 iter(v for v in self.known_values if v != self.default_value), 

2216 None, 

2217 ) 

2218 if value is None: 2218 ↛ 2219line 2218 didn't jump to line 2219 because the condition on line 2218 was never true

2219 return None 

2220 return [CompletionItem(value, insert_text=value)] 

2221 return [ 

2222 keyword.as_completion_item( 

2223 lint_state, 

2224 stanza_parts, 

2225 value_being_completed, 

2226 markdown_kind, 

2227 ) 

2228 for keyword in known_values.values() 

2229 if keyword.is_keyword_valid_completion_in_stanza(stanza_parts) 

2230 and keyword.is_completion_suggestion 

2231 ] 

2232 

2233 def field_omitted_diagnostics( 

2234 self, 

2235 deb822_file: Deb822FileElement, 

2236 representation_field_range: "TERange", 

2237 stanza: Deb822ParagraphElement, 

2238 stanza_position: "TEPosition", 

2239 header_stanza: Deb822FileElement | None, 

2240 lint_state: LintState, 

2241 ) -> None: 

2242 missing_field_severity = self.missing_field_severity 

2243 if missing_field_severity is None: 2243 ↛ 2246line 2243 didn't jump to line 2246 because the condition on line 2243 was always true

2244 return 

2245 

2246 if ( 

2247 self.inheritable_from_other_stanza 

2248 and header_stanza is not None 

2249 and self.name in header_stanza 

2250 ): 

2251 return 

2252 

2253 lint_state.emit_diagnostic( 

2254 representation_field_range, 

2255 f"Stanza is missing field {self.name}", 

2256 missing_field_severity, 

2257 self.missing_field_authority, 

2258 ) 

2259 

2260 async def field_diagnostics( 

2261 self, 

2262 deb822_file: Deb822FileElement, 

2263 kvpair: Deb822KeyValuePairElement, 

2264 stanza: Deb822ParagraphElement, 

2265 stanza_position: "TEPosition", 

2266 kvpair_range_te: "TERange", 

2267 lint_state: LintState, 

2268 *, 

2269 field_name_typo_reported: bool = False, 

2270 ) -> None: 

2271 field_name_token = kvpair.field_token 

2272 field_name_range_te = kvpair.field_token.range_in_parent().relative_to( 

2273 kvpair_range_te.start_pos 

2274 ) 

2275 field_name = field_name_token.text 

2276 # The `self.name` attribute is the canonical name whereas `field_name` is the name used. 

2277 # This distinction is important for `d/control` where `X[CBS]-` prefixes might be used 

2278 # in one but not the other. 

2279 field_value = stanza[field_name] 

2280 self._diagnostics_for_field_name( 

2281 kvpair_range_te, 

2282 field_name_token, 

2283 field_name_range_te, 

2284 field_name_typo_reported, 

2285 lint_state, 

2286 ) 

2287 if self.custom_field_check is not None: 

2288 self.custom_field_check( 

2289 self, 

2290 deb822_file, 

2291 kvpair, 

2292 kvpair_range_te, 

2293 field_name_range_te, 

2294 stanza, 

2295 stanza_position, 

2296 lint_state, 

2297 ) 

2298 self._dep5_file_list_diagnostics(kvpair, kvpair_range_te.start_pos, lint_state) 

2299 if self.spellcheck_value: 

2300 words = kvpair.interpret_as(LIST_SPACE_SEPARATED_INTERPRETATION) 

2301 spell_checker = lint_state.spellchecker() 

2302 value_position = kvpair.value_element.position_in_parent().relative_to( 

2303 kvpair_range_te.start_pos 

2304 ) 

2305 async for word_ref in lint_state.slow_iter( 

2306 words.iter_value_references(), yield_every=25 

2307 ): 

2308 token = word_ref.value 

2309 for word, pos, endpos in spell_checker.iter_words(token): 

2310 corrections = spell_checker.provide_corrections_for(word) 

2311 if not corrections: 

2312 continue 

2313 word_loc = word_ref.locatable 

2314 word_pos_te = word_loc.position_in_parent().relative_to( 

2315 value_position 

2316 ) 

2317 if pos: 2317 ↛ 2318line 2317 didn't jump to line 2318 because the condition on line 2317 was never true

2318 word_pos_te = TEPosition(0, pos).relative_to(word_pos_te) 

2319 word_size = TERange( 

2320 START_POSITION, 

2321 TEPosition(0, endpos - pos), 

2322 ) 

2323 lint_state.emit_diagnostic( 

2324 TERange.from_position_and_size(word_pos_te, word_size), 

2325 f'Spelling "{word}"', 

2326 "spelling", 

2327 "debputy", 

2328 quickfixes=[ 

2329 propose_correct_text_quick_fix(c) for c in corrections 

2330 ], 

2331 enable_non_interactive_auto_fix=False, 

2332 ) 

2333 else: 

2334 self._known_value_diagnostics( 

2335 kvpair, 

2336 kvpair_range_te.start_pos, 

2337 lint_state, 

2338 ) 

2339 

2340 if self.warn_if_default and field_value == self.default_value: 2340 ↛ 2341line 2340 didn't jump to line 2341 because the condition on line 2340 was never true

2341 lint_state.emit_diagnostic( 

2342 kvpair_range_te, 

2343 f'The field "{field_name}" is redundant as it is set to the default value and the field' 

2344 " should only be used in exceptional cases.", 

2345 "warning", 

2346 "debputy", 

2347 ) 

2348 

2349 def _diagnostics_for_field_name( 

2350 self, 

2351 kvpair_range: "TERange", 

2352 token: Deb822FieldNameToken, 

2353 token_range: "TERange", 

2354 typo_detected: bool, 

2355 lint_state: LintState, 

2356 ) -> None: 

2357 field_name = token.text 

2358 # Defeat the case-insensitivity from python-debian 

2359 field_name_cased = str(field_name) 

2360 if self.deprecated_with_no_replacement: 

2361 lint_state.emit_diagnostic( 

2362 kvpair_range, 

2363 f'"{field_name_cased}" is deprecated and no longer used', 

2364 "warning", 

2365 "debputy", 

2366 quickfixes=[propose_remove_range_quick_fix()], 

2367 tags=[DiagnosticTag.Deprecated], 

2368 ) 

2369 elif self.replaced_by is not None: 

2370 lint_state.emit_diagnostic( 

2371 token_range, 

2372 f'"{field_name_cased}" has been replaced by "{self.replaced_by}"', 

2373 "warning", 

2374 "debputy", 

2375 tags=[DiagnosticTag.Deprecated], 

2376 quickfixes=[propose_correct_text_quick_fix(self.replaced_by)], 

2377 ) 

2378 

2379 if not typo_detected and field_name_cased != self.name: 

2380 lint_state.emit_diagnostic( 

2381 token_range, 

2382 f'Non-canonical spelling of "{self.name}"', 

2383 "pedantic", 

2384 self.unknown_value_authority, 

2385 quickfixes=[propose_correct_text_quick_fix(self.name)], 

2386 ) 

2387 

2388 def _dep5_file_list_diagnostics( 

2389 self, 

2390 kvpair: Deb822KeyValuePairElement, 

2391 kvpair_position: "TEPosition", 

2392 lint_state: LintState, 

2393 ) -> None: 

2394 source_root = lint_state.source_root 

2395 if ( 

2396 self.field_value_class != FieldValueClass.DEP5_FILE_LIST 

2397 or source_root is None 

2398 ): 

2399 return 

2400 interpreter = self.field_value_class.interpreter() 

2401 values = kvpair.interpret_as(interpreter) 

2402 value_off = kvpair.value_element.position_in_parent().relative_to( 

2403 kvpair_position 

2404 ) 

2405 

2406 assert interpreter is not None 

2407 

2408 for token in values.iter_parts(): 

2409 if token.is_whitespace: 

2410 continue 

2411 text = token.convert_to_text() 

2412 if "?" in text or "*" in text: 2412 ↛ 2414line 2412 didn't jump to line 2414 because the condition on line 2412 was never true

2413 # TODO: We should validate these as well 

2414 continue 

2415 matched_path, missing_part = source_root.attempt_lookup(text) 

2416 # It is common practice to delete "dirty" files during clean. This causes files listed 

2417 # in `debian/copyright` to go missing and as a consequence, we do not validate whether 

2418 # they are present (that would require us to check the `.orig.tar`, which we could but 

2419 # do not have the infrastructure for). 

2420 if not missing_part and matched_path.is_dir and self.name == "Files": 

2421 path_range_te = token.range_in_parent().relative_to(value_off) 

2422 lint_state.emit_diagnostic( 

2423 path_range_te, 

2424 "Directories cannot be a match. Use `dir/*` to match everything in it", 

2425 "warning", 

2426 self.unknown_value_authority, 

2427 quickfixes=[ 

2428 propose_correct_text_quick_fix(f"{matched_path.path}/*") 

2429 ], 

2430 ) 

2431 

2432 def _known_value_diagnostics( 

2433 self, 

2434 kvpair: Deb822KeyValuePairElement, 

2435 kvpair_position: "TEPosition", 

2436 lint_state: LintState, 

2437 ) -> None: 

2438 unknown_value_severity = self.unknown_value_severity 

2439 interpreter = self.field_value_class.interpreter() 

2440 if interpreter is None: 

2441 return 

2442 try: 

2443 values = kvpair.interpret_as(interpreter) 

2444 except ValueError: 

2445 value_range = kvpair.value_element.range_in_parent().relative_to( 

2446 kvpair_position 

2447 ) 

2448 lint_state.emit_diagnostic( 

2449 value_range, 

2450 "Error while parsing field (diagnostics related to this field may be incomplete)", 

2451 "pedantic", 

2452 "debputy", 

2453 ) 

2454 return 

2455 value_off = kvpair.value_element.position_in_parent().relative_to( 

2456 kvpair_position 

2457 ) 

2458 

2459 last_token_non_ws_sep_token: TE | None = None 

2460 for token in values.iter_parts(): 

2461 if token.is_whitespace: 

2462 continue 

2463 if not token.is_separator: 

2464 last_token_non_ws_sep_token = None 

2465 continue 

2466 if last_token_non_ws_sep_token is not None: 

2467 sep_range_te = token.range_in_parent().relative_to(value_off) 

2468 lint_state.emit_diagnostic( 

2469 sep_range_te, 

2470 "Duplicate separator", 

2471 "error", 

2472 self.unknown_value_authority, 

2473 ) 

2474 last_token_non_ws_sep_token = token 

2475 

2476 allowed_values = self.known_values 

2477 if not allowed_values: 

2478 return 

2479 

2480 first_value = None 

2481 first_exclusive_value_ref = None 

2482 first_exclusive_value = None 

2483 has_emitted_for_exclusive = False 

2484 

2485 for value_ref in values.iter_value_references(): 

2486 value = value_ref.value 

2487 if ( 2487 ↛ 2491line 2487 didn't jump to line 2491 because the condition on line 2487 was never true

2488 first_value is not None 

2489 and self.field_value_class == FieldValueClass.SINGLE_VALUE 

2490 ): 

2491 value_loc = value_ref.locatable 

2492 range_position_te = value_loc.range_in_parent().relative_to(value_off) 

2493 lint_state.emit_diagnostic( 

2494 range_position_te, 

2495 f"The field {self.name} can only have exactly one value.", 

2496 "error", 

2497 self.unknown_value_authority, 

2498 ) 

2499 # TODO: Add quickfix if the value is also invalid 

2500 continue 

2501 

2502 if first_exclusive_value_ref is not None and not has_emitted_for_exclusive: 

2503 assert first_exclusive_value is not None 

2504 value_loc = first_exclusive_value_ref.locatable 

2505 value_range_te = value_loc.range_in_parent().relative_to(value_off) 

2506 lint_state.emit_diagnostic( 

2507 value_range_te, 

2508 f'The value "{first_exclusive_value}" cannot be used with other values.', 

2509 "error", 

2510 self.unknown_value_authority, 

2511 ) 

2512 

2513 known_value, unknown_value_message, unknown_severity, typo_fix_data = ( 

2514 _unknown_value_check( 

2515 self.name, 

2516 value, 

2517 self.known_values, 

2518 unknown_value_severity, 

2519 ) 

2520 ) 

2521 value_loc = value_ref.locatable 

2522 value_range = value_loc.range_in_parent().relative_to(value_off) 

2523 

2524 if known_value and known_value.is_exclusive: 

2525 first_exclusive_value = known_value.value # In case of typos. 

2526 first_exclusive_value_ref = value_ref 

2527 if first_value is not None: 

2528 has_emitted_for_exclusive = True 

2529 lint_state.emit_diagnostic( 

2530 value_range, 

2531 f'The value "{known_value.value}" cannot be used with other values.', 

2532 "error", 

2533 self.unknown_value_authority, 

2534 ) 

2535 

2536 if first_value is None: 

2537 first_value = value 

2538 

2539 if unknown_value_message is not None: 

2540 assert unknown_severity is not None 

2541 lint_state.emit_diagnostic( 

2542 value_range, 

2543 unknown_value_message, 

2544 unknown_severity, 

2545 self.unknown_value_authority, 

2546 quickfixes=typo_fix_data, 

2547 ) 

2548 

2549 if known_value is not None and known_value.is_deprecated: 

2550 replacement = known_value.replaced_by 

2551 if replacement is not None: 2551 ↛ 2557line 2551 didn't jump to line 2557 because the condition on line 2551 was always true

2552 obsolete_value_message = ( 

2553 f'The value "{value}" has been replaced by "{replacement}"' 

2554 ) 

2555 obsolete_fix_data = [propose_correct_text_quick_fix(replacement)] 

2556 else: 

2557 obsolete_value_message = ( 

2558 f'The value "{value}" is obsolete without a single replacement' 

2559 ) 

2560 obsolete_fix_data = None 

2561 lint_state.emit_diagnostic( 

2562 value_range, 

2563 obsolete_value_message, 

2564 "warning", 

2565 "debputy", 

2566 quickfixes=obsolete_fix_data, 

2567 ) 

2568 

2569 def _reformat_field_name( 

2570 self, 

2571 effective_preference: "EffectiveFormattingPreference", 

2572 stanza_range: TERange, 

2573 kvpair: Deb822KeyValuePairElement, 

2574 position_codec: LintCapablePositionCodec, 

2575 lines: list[str], 

2576 ) -> Iterable[TextEdit]: 

2577 if not effective_preference.deb822_auto_canonical_size_field_names: 2577 ↛ 2578line 2577 didn't jump to line 2578 because the condition on line 2577 was never true

2578 return 

2579 # The `str(kvpair.field_name)` is to avoid the "magic" from `python3-debian`'s Deb822 keys. 

2580 if str(kvpair.field_name) == self.name: 

2581 return 

2582 

2583 field_name_range_te = kvpair.field_token.range_in_parent().relative_to( 

2584 kvpair.range_in_parent().relative_to(stanza_range.start_pos).start_pos 

2585 ) 

2586 

2587 edit_range = position_codec.range_to_client_units( 

2588 lines, 

2589 Range( 

2590 Position( 

2591 field_name_range_te.start_pos.line_position, 

2592 field_name_range_te.start_pos.cursor_position, 

2593 ), 

2594 Position( 

2595 field_name_range_te.start_pos.line_position, 

2596 field_name_range_te.end_pos.cursor_position, 

2597 ), 

2598 ), 

2599 ) 

2600 yield TextEdit( 

2601 edit_range, 

2602 self.name, 

2603 ) 

2604 

2605 def reformat_field( 

2606 self, 

2607 effective_preference: "EffectiveFormattingPreference", 

2608 stanza_range: TERange, 

2609 kvpair: Deb822KeyValuePairElement, 

2610 formatter: FormatterCallback, 

2611 position_codec: LintCapablePositionCodec, 

2612 lines: list[str], 

2613 ) -> Iterable[TextEdit]: 

2614 kvpair_range = kvpair.range_in_parent().relative_to(stanza_range.start_pos) 

2615 yield from self._reformat_field_name( 

2616 effective_preference, 

2617 stanza_range, 

2618 kvpair, 

2619 position_codec, 

2620 lines, 

2621 ) 

2622 return trim_end_of_line_whitespace( 

2623 position_codec, 

2624 lines, 

2625 line_range=range( 

2626 kvpair_range.start_pos.line_position, 

2627 kvpair_range.end_pos.line_position, 

2628 ), 

2629 ) 

2630 

2631 def replace(self, **changes: Any) -> "Self": 

2632 return dataclasses.replace(self, **changes) 

2633 

2634 

2635@dataclasses.dataclass(slots=True) 

2636class DctrlLikeKnownField(Deb822KnownField): 

2637 

2638 def reformat_field( 

2639 self, 

2640 effective_preference: "EffectiveFormattingPreference", 

2641 stanza_range: TERange, 

2642 kvpair: Deb822KeyValuePairElement, 

2643 formatter: FormatterCallback, 

2644 position_codec: LintCapablePositionCodec, 

2645 lines: list[str], 

2646 ) -> Iterable[TextEdit]: 

2647 interpretation = self.field_value_class.interpreter() 

2648 if ( 2648 ↛ 2652line 2648 didn't jump to line 2652 because the condition on line 2648 was never true

2649 not effective_preference.deb822_normalize_field_content 

2650 or interpretation is None 

2651 ): 

2652 yield from super(DctrlLikeKnownField, self).reformat_field( 

2653 effective_preference, 

2654 stanza_range, 

2655 kvpair, 

2656 formatter, 

2657 position_codec, 

2658 lines, 

2659 ) 

2660 return 

2661 if not self.reformattable_field: 

2662 yield from super(DctrlLikeKnownField, self).reformat_field( 

2663 effective_preference, 

2664 stanza_range, 

2665 kvpair, 

2666 formatter, 

2667 position_codec, 

2668 lines, 

2669 ) 

2670 return 

2671 

2672 # Preserve the name fixes from the super call. 

2673 yield from self._reformat_field_name( 

2674 effective_preference, 

2675 stanza_range, 

2676 kvpair, 

2677 position_codec, 

2678 lines, 

2679 ) 

2680 

2681 seen: set[str] = set() 

2682 old_kvpair_range = kvpair.range_in_parent() 

2683 sort = self.is_sortable_field 

2684 

2685 # Avoid the context manager as we do not want to perform the change (it would contaminate future ranges) 

2686 field_content = kvpair.interpret_as(interpretation) 

2687 old_value = field_content.convert_to_text(with_field_name=False) 

2688 for package_ref in field_content.iter_value_references(): 

2689 value = package_ref.value 

2690 value_range = package_ref.locatable.range_in_parent().relative_to( 

2691 stanza_range.start_pos 

2692 ) 

2693 sublines = lines[ 

2694 value_range.start_pos.line_position : value_range.end_pos.line_position 

2695 ] 

2696 

2697 # debputy#112: Avoid truncating "inline comments" 

2698 if any(line.startswith("#") for line in sublines): 2698 ↛ 2699line 2698 didn't jump to line 2699 because the condition on line 2698 was never true

2699 return 

2700 if self.is_relationship_field: 2700 ↛ 2703line 2700 didn't jump to line 2703 because the condition on line 2700 was always true

2701 new_value = " | ".join(x.strip() for x in value.split("|")) 

2702 else: 

2703 new_value = value 

2704 if not sort or new_value not in seen: 2704 ↛ 2709line 2704 didn't jump to line 2709 because the condition on line 2704 was always true

2705 if new_value != value: 2705 ↛ 2706line 2705 didn't jump to line 2706 because the condition on line 2705 was never true

2706 package_ref.value = new_value 

2707 seen.add(new_value) 

2708 else: 

2709 package_ref.remove() 

2710 if sort: 2710 ↛ 2712line 2710 didn't jump to line 2712 because the condition on line 2710 was always true

2711 field_content.sort(key=_sort_packages_key) 

2712 field_content.value_formatter(formatter) 

2713 field_content.reformat_when_finished() 

2714 

2715 new_value = field_content.convert_to_text(with_field_name=False) 

2716 if new_value != old_value: 

2717 value_range = kvpair.value_element.range_in_parent().relative_to( 

2718 old_kvpair_range.start_pos 

2719 ) 

2720 range_server_units = te_range_to_lsp( 

2721 value_range.relative_to(stanza_range.start_pos) 

2722 ) 

2723 yield TextEdit( 

2724 position_codec.range_to_client_units(lines, range_server_units), 

2725 new_value, 

2726 ) 

2727 

2728 @property 

2729 def reformattable_field(self) -> bool: 

2730 return self.is_relationship_field or self.is_sortable_field 

2731 

2732 @property 

2733 def is_relationship_field(self) -> bool: 

2734 return False 

2735 

2736 @property 

2737 def is_sortable_field(self) -> bool: 

2738 return self.is_relationship_field 

2739 

2740 

2741@dataclasses.dataclass(slots=True) 

2742class DTestsCtrlKnownField(DctrlLikeKnownField): 

2743 @property 

2744 def is_relationship_field(self) -> bool: 

2745 return self.name == "Depends" 

2746 

2747 @property 

2748 def is_sortable_field(self) -> bool: 

2749 return self.is_relationship_field or self.name in ( 

2750 "Features", 

2751 "Restrictions", 

2752 "Tests", 

2753 ) 

2754 

2755 

2756@dataclasses.dataclass(slots=True) 

2757class DctrlKnownField(DctrlLikeKnownField): 

2758 

2759 def field_omitted_diagnostics( 

2760 self, 

2761 deb822_file: Deb822FileElement, 

2762 representation_field_range: "TERange", 

2763 stanza: Deb822ParagraphElement, 

2764 stanza_position: "TEPosition", 

2765 header_stanza: Deb822FileElement | None, 

2766 lint_state: LintState, 

2767 ) -> None: 

2768 missing_field_severity = self.missing_field_severity 

2769 if missing_field_severity is None: 

2770 return 

2771 

2772 if ( 

2773 self.inheritable_from_other_stanza 

2774 and header_stanza is not None 

2775 and self.name in header_stanza 

2776 ): 

2777 return 

2778 

2779 if self.name == "Standards-Version": 

2780 stanzas = list(deb822_file)[1:] 

2781 if all(s.get("Package-Type") == "udeb" for s in stanzas): 

2782 return 

2783 

2784 lint_state.emit_diagnostic( 

2785 representation_field_range, 

2786 f"Stanza is missing field {self.name}", 

2787 missing_field_severity, 

2788 self.missing_field_authority, 

2789 ) 

2790 

2791 def reformat_field( 

2792 self, 

2793 effective_preference: "EffectiveFormattingPreference", 

2794 stanza_range: TERange, 

2795 kvpair: Deb822KeyValuePairElement, 

2796 formatter: FormatterCallback, 

2797 position_codec: LintCapablePositionCodec, 

2798 lines: list[str], 

2799 ) -> Iterable[TextEdit]: 

2800 if ( 

2801 self.name == "Architecture" 

2802 and effective_preference.deb822_normalize_field_content 

2803 ): 

2804 interpretation = self.field_value_class.interpreter() 

2805 assert interpretation is not None 

2806 interpreted = kvpair.interpret_as(interpretation) 

2807 archs = list(interpreted) 

2808 # Sort, with wildcard entries (such as linux-any) first: 

2809 archs = sorted(archs, key=lambda x: ("any" not in x, x)) 

2810 new_value = f" {' '.join(archs)}\n" 

2811 reformat_edits = list( 

2812 self._reformat_field_name( 

2813 effective_preference, 

2814 stanza_range, 

2815 kvpair, 

2816 position_codec, 

2817 lines, 

2818 ) 

2819 ) 

2820 if new_value != interpreted.convert_to_text(with_field_name=False): 

2821 value_range = kvpair.value_element.range_in_parent().relative_to( 

2822 kvpair.range_in_parent().start_pos 

2823 ) 

2824 kvpair_range = te_range_to_lsp( 

2825 value_range.relative_to(stanza_range.start_pos) 

2826 ) 

2827 reformat_edits.append( 

2828 TextEdit( 

2829 position_codec.range_to_client_units(lines, kvpair_range), 

2830 new_value, 

2831 ) 

2832 ) 

2833 return reformat_edits 

2834 

2835 return super(DctrlKnownField, self).reformat_field( 

2836 effective_preference, 

2837 stanza_range, 

2838 kvpair, 

2839 formatter, 

2840 position_codec, 

2841 lines, 

2842 ) 

2843 

2844 @property 

2845 def is_relationship_field(self) -> bool: 

2846 name_lc = self.name.lower() 

2847 return ( 

2848 name_lc in all_package_relationship_fields() 

2849 or name_lc in all_source_relationship_fields() 

2850 ) 

2851 

2852 @property 

2853 def reformattable_field(self) -> bool: 

2854 return self.is_relationship_field or self.name == "Uploaders" 

2855 

2856 

2857@dataclasses.dataclass(slots=True) 

2858class DctrlRelationshipKnownField(DctrlKnownField): 

2859 allowed_version_operators: frozenset[str] = frozenset() 

2860 supports_or_relation: bool = True 

2861 

2862 @property 

2863 def is_relationship_field(self) -> bool: 

2864 return True 

2865 

2866 

2867SOURCE_FIELDS = _fields( 

2868 DctrlKnownField( 

2869 "Source", 

2870 FieldValueClass.SINGLE_VALUE, 

2871 custom_field_check=_combined_custom_field_check( 

2872 _each_value_match_regex_validation(PKGNAME_REGEX), 

2873 _has_packaging_expected_file( 

2874 "copyright", 

2875 "No copyright file (package license)", 

2876 severity="warning", 

2877 ), 

2878 _has_packaging_expected_file( 

2879 "changelog", 

2880 "No Debian changelog file", 

2881 severity="error", 

2882 ), 

2883 _has_build_instructions, 

2884 ), 

2885 ), 

2886 DctrlKnownField( 

2887 "Standards-Version", 

2888 FieldValueClass.SINGLE_VALUE, 

2889 custom_field_check=_sv_field_validation, 

2890 ), 

2891 DctrlKnownField( 

2892 "Section", 

2893 FieldValueClass.SINGLE_VALUE, 

2894 known_values=ALL_SECTIONS, 

2895 ), 

2896 DctrlKnownField( 

2897 "Priority", 

2898 FieldValueClass.SINGLE_VALUE, 

2899 ), 

2900 DctrlKnownField( 

2901 "Maintainer", 

2902 FieldValueClass.COMMA_SEPARATED_EMAIL_LIST, 

2903 custom_field_check=_combined_custom_field_check( 

2904 _maintainer_field_validator, 

2905 _canonical_maintainer_name, 

2906 ), 

2907 ), 

2908 DctrlKnownField( 

2909 "Uploaders", 

2910 FieldValueClass.COMMA_SEPARATED_EMAIL_LIST, 

2911 custom_field_check=_canonical_maintainer_name, 

2912 ), 

2913 DctrlRelationshipKnownField( 

2914 "Build-Depends", 

2915 FieldValueClass.COMMA_SEPARATED_LIST, 

2916 custom_field_check=_dctrl_validate_dep, 

2917 ), 

2918 DctrlRelationshipKnownField( 

2919 "Build-Depends-Arch", 

2920 FieldValueClass.COMMA_SEPARATED_LIST, 

2921 custom_field_check=_dctrl_validate_dep, 

2922 ), 

2923 DctrlRelationshipKnownField( 

2924 "Build-Depends-Indep", 

2925 FieldValueClass.COMMA_SEPARATED_LIST, 

2926 custom_field_check=_dctrl_validate_dep, 

2927 ), 

2928 DctrlRelationshipKnownField( 

2929 "Build-Conflicts", 

2930 FieldValueClass.COMMA_SEPARATED_LIST, 

2931 supports_or_relation=False, 

2932 custom_field_check=_dctrl_validate_dep, 

2933 ), 

2934 DctrlRelationshipKnownField( 

2935 "Build-Conflicts-Arch", 

2936 FieldValueClass.COMMA_SEPARATED_LIST, 

2937 supports_or_relation=False, 

2938 custom_field_check=_dctrl_validate_dep, 

2939 ), 

2940 DctrlRelationshipKnownField( 

2941 "Build-Conflicts-Indep", 

2942 FieldValueClass.COMMA_SEPARATED_LIST, 

2943 supports_or_relation=False, 

2944 custom_field_check=_dctrl_validate_dep, 

2945 ), 

2946 DctrlKnownField( 

2947 "Rules-Requires-Root", 

2948 FieldValueClass.SPACE_SEPARATED_LIST, 

2949 custom_field_check=_rrr_build_driver_mismatch, 

2950 ), 

2951 DctrlKnownField( 

2952 "X-Style", 

2953 FieldValueClass.SINGLE_VALUE, 

2954 known_values=ALL_PUBLIC_NAMED_STYLES_AS_KEYWORDS, 

2955 ), 

2956 DctrlKnownField( 

2957 "Homepage", 

2958 FieldValueClass.SINGLE_VALUE, 

2959 custom_field_check=_validate_homepage_field, 

2960 ), 

2961) 

2962 

2963 

2964BINARY_FIELDS = _fields( 

2965 DctrlKnownField( 

2966 "Package", 

2967 FieldValueClass.SINGLE_VALUE, 

2968 custom_field_check=_each_value_match_regex_validation(PKGNAME_REGEX), 

2969 ), 

2970 DctrlKnownField( 

2971 "Architecture", 

2972 FieldValueClass.SPACE_SEPARATED_LIST, 

2973 # FIXME: Specialize validation for architecture ("!foo" is not a "typo" and should have a better warning) 

2974 known_values=allowed_values(dpkg_arch_and_wildcards()), 

2975 ), 

2976 DctrlKnownField( 

2977 "Pre-Depends", 

2978 FieldValueClass.COMMA_SEPARATED_LIST, 

2979 custom_field_check=_dctrl_validate_dep, 

2980 ), 

2981 DctrlKnownField( 

2982 "Depends", 

2983 FieldValueClass.COMMA_SEPARATED_LIST, 

2984 custom_field_check=_dctrl_validate_dep, 

2985 ), 

2986 DctrlKnownField( 

2987 "Recommends", 

2988 FieldValueClass.COMMA_SEPARATED_LIST, 

2989 custom_field_check=_dctrl_validate_dep, 

2990 ), 

2991 DctrlKnownField( 

2992 "Suggests", 

2993 FieldValueClass.COMMA_SEPARATED_LIST, 

2994 custom_field_check=_dctrl_validate_dep, 

2995 ), 

2996 DctrlKnownField( 

2997 "Enhances", 

2998 FieldValueClass.COMMA_SEPARATED_LIST, 

2999 custom_field_check=_dctrl_validate_dep, 

3000 ), 

3001 DctrlRelationshipKnownField( 

3002 "Provides", 

3003 FieldValueClass.COMMA_SEPARATED_LIST, 

3004 custom_field_check=_dctrl_validate_dep, 

3005 supports_or_relation=False, 

3006 allowed_version_operators=frozenset(["="]), 

3007 ), 

3008 DctrlRelationshipKnownField( 

3009 "Conflicts", 

3010 FieldValueClass.COMMA_SEPARATED_LIST, 

3011 custom_field_check=_dctrl_validate_dep, 

3012 supports_or_relation=False, 

3013 ), 

3014 DctrlRelationshipKnownField( 

3015 "Breaks", 

3016 FieldValueClass.COMMA_SEPARATED_LIST, 

3017 custom_field_check=_dctrl_validate_dep, 

3018 supports_or_relation=False, 

3019 ), 

3020 DctrlRelationshipKnownField( 

3021 "Replaces", 

3022 FieldValueClass.COMMA_SEPARATED_LIST, 

3023 custom_field_check=_dctrl_validate_dep, 

3024 ), 

3025 DctrlKnownField( 

3026 "Build-Profiles", 

3027 FieldValueClass.BUILD_PROFILES_LIST, 

3028 ), 

3029 DctrlKnownField( 

3030 "Section", 

3031 FieldValueClass.SINGLE_VALUE, 

3032 known_values=ALL_SECTIONS, 

3033 ), 

3034 DctrlRelationshipKnownField( 

3035 "Built-Using", 

3036 FieldValueClass.COMMA_SEPARATED_LIST, 

3037 custom_field_check=_arch_not_all_only_field_validation, 

3038 can_complete_field_in_stanza=_complete_only_in_arch_dep_pkgs, 

3039 supports_or_relation=False, 

3040 allowed_version_operators=frozenset(["="]), 

3041 ), 

3042 DctrlRelationshipKnownField( 

3043 "Static-Built-Using", 

3044 FieldValueClass.COMMA_SEPARATED_LIST, 

3045 custom_field_check=_arch_not_all_only_field_validation, 

3046 can_complete_field_in_stanza=_complete_only_in_arch_dep_pkgs, 

3047 supports_or_relation=False, 

3048 allowed_version_operators=frozenset(["="]), 

3049 ), 

3050 DctrlKnownField( 

3051 "Multi-Arch", 

3052 FieldValueClass.SINGLE_VALUE, 

3053 custom_field_check=_combined_custom_field_check( 

3054 _not_applicable_to_udeb_field_validation, _dctrl_ma_field_validation 

3055 ), 

3056 known_values=allowed_values( 

3057 ( 

3058 Keyword( 

3059 "same", 

3060 can_complete_keyword_in_stanza=_complete_only_in_arch_dep_pkgs, 

3061 ), 

3062 ), 

3063 ), 

3064 ), 

3065 DctrlKnownField( 

3066 "XB-Installer-Menu-Item", 

3067 FieldValueClass.SINGLE_VALUE, 

3068 can_complete_field_in_stanza=_complete_only_for_udeb_pkgs, 

3069 custom_field_check=_combined_custom_field_check( 

3070 _udeb_only_field_validation, 

3071 _each_value_match_regex_validation(re.compile(r"^[1-9]\d{3,4}$")), 

3072 ), 

3073 ), 

3074 DctrlKnownField( 

3075 "X-DH-Build-For-Type", 

3076 FieldValueClass.SINGLE_VALUE, 

3077 custom_field_check=_arch_not_all_only_field_validation, 

3078 can_complete_field_in_stanza=_complete_only_in_arch_dep_pkgs, 

3079 ), 

3080 DctrlKnownField( 

3081 "X-Doc-Main-Package", 

3082 FieldValueClass.SINGLE_VALUE, 

3083 custom_field_check=_binary_package_from_same_source, 

3084 ), 

3085 DctrlKnownField( 

3086 "X-Time64-Compat", 

3087 FieldValueClass.SINGLE_VALUE, 

3088 can_complete_field_in_stanza=_complete_only_in_arch_dep_pkgs, 

3089 custom_field_check=_combined_custom_field_check( 

3090 _each_value_match_regex_validation(PKGNAME_REGEX), 

3091 _arch_not_all_only_field_validation, 

3092 ), 

3093 ), 

3094 DctrlKnownField( 

3095 "Description", 

3096 FieldValueClass.FREE_TEXT_FIELD, 

3097 custom_field_check=dctrl_description_validator, 

3098 ), 

3099 DctrlKnownField( 

3100 "XB-Cnf-Visible-Pkgname", 

3101 FieldValueClass.SINGLE_VALUE, 

3102 custom_field_check=_each_value_match_regex_validation(PKGNAME_REGEX), 

3103 ), 

3104 DctrlKnownField( 

3105 "Homepage", 

3106 FieldValueClass.SINGLE_VALUE, 

3107 show_as_inherited=False, 

3108 custom_field_check=_validate_homepage_field, 

3109 ), 

3110) 

3111_DEP5_HEADER_FIELDS = _fields( 

3112 Deb822KnownField( 

3113 "Format", 

3114 FieldValueClass.SINGLE_VALUE, 

3115 custom_field_check=_use_https_instead_of_http, 

3116 ), 

3117) 

3118_DEP5_FILES_FIELDS = _fields( 

3119 Deb822KnownField( 

3120 "Files", 

3121 FieldValueClass.DEP5_FILE_LIST, 

3122 custom_field_check=_dep5_files_check, 

3123 ), 

3124) 

3125_DEP5_LICENSE_FIELDS = _fields( 

3126 Deb822KnownField( 

3127 "License", 

3128 FieldValueClass.FREE_TEXT_FIELD, 

3129 ), 

3130) 

3131 

3132_DTESTSCTRL_FIELDS = _fields( 

3133 DTestsCtrlKnownField( 

3134 "Architecture", 

3135 FieldValueClass.SPACE_SEPARATED_LIST, 

3136 # FIXME: Specialize validation for architecture ("!fou" to "foo" would be bad) 

3137 known_values=allowed_values(dpkg_arch_and_wildcards(allow_negations=True)), 

3138 ), 

3139) 

3140_DWATCH_HEADER_FIELDS = _fields() 

3141_DWATCH_TEMPLATE_FIELDS = _fields() 

3142_DWATCH_SOURCE_FIELDS = _fields() 

3143 

3144 

3145@dataclasses.dataclass(slots=True) 

3146class StanzaMetadata(Mapping[str, F], Generic[F], ABC): 

3147 stanza_type_name: str 

3148 stanza_fields: Mapping[str, F] 

3149 is_substvars_allowed_in_stanza: bool 

3150 

3151 async def stanza_diagnostics( 

3152 self, 

3153 deb822_file: Deb822FileElement, 

3154 stanza: Deb822ParagraphElement, 

3155 stanza_position_in_file: "TEPosition", 

3156 lint_state: LintState, 

3157 *, 

3158 inherit_from_stanza: Deb822ParagraphElement | None = None, 

3159 confusable_with_stanza_name: str | None = None, 

3160 confusable_with_stanza_metadata: Optional["StanzaMetadata[F]"] = None, 

3161 ) -> None: 

3162 if (confusable_with_stanza_name is None) ^ ( 3162 ↛ 3165line 3162 didn't jump to line 3165 because the condition on line 3162 was never true

3163 confusable_with_stanza_metadata is None 

3164 ): 

3165 raise ValueError( 

3166 "confusable_with_stanza_name and confusable_with_stanza_metadata must be used together" 

3167 ) 

3168 _, representation_field_range = self.stanza_representation( 

3169 stanza, 

3170 stanza_position_in_file, 

3171 ) 

3172 known_fields = self.stanza_fields 

3173 self.omitted_field_diagnostics( 

3174 lint_state, 

3175 deb822_file, 

3176 stanza, 

3177 stanza_position_in_file, 

3178 inherit_from_stanza=inherit_from_stanza, 

3179 representation_field_range=representation_field_range, 

3180 ) 

3181 seen_fields: dict[str, tuple[str, str, "TERange", list[Range], set[str]]] = {} 

3182 

3183 async for kvpair_range, kvpair in lint_state.slow_iter( 

3184 with_range_in_continuous_parts( 

3185 stanza.iter_parts(), 

3186 start_relative_to=stanza_position_in_file, 

3187 ), 

3188 yield_every=1, 

3189 ): 

3190 if not isinstance(kvpair, Deb822KeyValuePairElement): 3190 ↛ 3191line 3190 didn't jump to line 3191 because the condition on line 3190 was never true

3191 continue 

3192 field_name_token = kvpair.field_token 

3193 field_name = field_name_token.text 

3194 field_name_lc = field_name.lower() 

3195 # Defeat any tricks from `python-debian` from here on out 

3196 field_name = str(field_name) 

3197 normalized_field_name_lc = self.normalize_field_name(field_name_lc) 

3198 known_field = known_fields.get(normalized_field_name_lc) 

3199 field_value = stanza[field_name] 

3200 kvpair_range_te = kvpair.range_in_parent().relative_to( 

3201 stanza_position_in_file 

3202 ) 

3203 field_range = kvpair.field_token.range_in_parent().relative_to( 

3204 kvpair_range_te.start_pos 

3205 ) 

3206 field_position_te = field_range.start_pos 

3207 field_name_typo_detected = False 

3208 dup_field_key = ( 

3209 known_field.name 

3210 if known_field is not None 

3211 else normalized_field_name_lc 

3212 ) 

3213 existing_field_range = seen_fields.get(dup_field_key) 

3214 if existing_field_range is not None: 

3215 existing_field_range[3].append(field_range) 

3216 existing_field_range[4].add(field_name) 

3217 else: 

3218 normalized_field_name = self.normalize_field_name(field_name) 

3219 seen_fields[dup_field_key] = ( 

3220 known_field.name if known_field else field_name, 

3221 normalized_field_name, 

3222 field_range, 

3223 [], 

3224 {field_name}, 

3225 ) 

3226 

3227 if known_field is None: 

3228 candidates = detect_possible_typo( 

3229 normalized_field_name_lc, known_fields 

3230 ) 

3231 if candidates: 

3232 known_field = known_fields[candidates[0]] 

3233 field_range = TERange.from_position_and_size( 

3234 field_position_te, kvpair.field_token.size() 

3235 ) 

3236 field_name_typo_detected = True 

3237 lint_state.emit_diagnostic( 

3238 field_range, 

3239 f'The "{field_name}" looks like a typo of "{known_field.name}".', 

3240 "warning", 

3241 "debputy", 

3242 quickfixes=[ 

3243 propose_correct_text_quick_fix(known_fields[m].name) 

3244 for m in candidates 

3245 ], 

3246 ) 

3247 if field_value.strip() == "": 3247 ↛ 3248line 3247 didn't jump to line 3248 because the condition on line 3247 was never true

3248 lint_state.emit_diagnostic( 

3249 field_range, 

3250 f"The {field_name} has no value. Either provide a value or remove it.", 

3251 "error", 

3252 "Policy 5.1", 

3253 ) 

3254 continue 

3255 if known_field is None: 

3256 known_else_where = confusable_with_stanza_metadata.stanza_fields.get( 

3257 normalized_field_name_lc 

3258 ) 

3259 if known_else_where is not None: 

3260 msg = ( 

3261 f"The {kvpair.field_name} field is defined for use in the" 

3262 f' "{confusable_with_stanza_name}" stanza. Please move it to the right place, remove it,' 

3263 f" or in case of two run-in stanzas add an empty newline to separate them" 

3264 ) 

3265 lint_state.emit_diagnostic( 

3266 field_range, 

3267 msg, 

3268 "error", 

3269 known_else_where.missing_field_authority, 

3270 ) 

3271 continue 

3272 await known_field.field_diagnostics( 

3273 deb822_file, 

3274 kvpair, 

3275 stanza, 

3276 stanza_position_in_file, 

3277 kvpair_range_te, 

3278 lint_state, 

3279 field_name_typo_reported=field_name_typo_detected, 

3280 ) 

3281 

3282 inherit_value = ( 

3283 inherit_from_stanza.get(field_name) if inherit_from_stanza else None 

3284 ) 

3285 

3286 if ( 

3287 known_field.inheritable_from_other_stanza 

3288 and inherit_value is not None 

3289 and field_value == inherit_value 

3290 ): 

3291 quick_fix = propose_remove_range_quick_fix( 

3292 proposed_title="Remove redundant definition" 

3293 ) 

3294 lint_state.emit_diagnostic( 

3295 kvpair_range_te, 

3296 f"The field {field_name} duplicates the value from the Source stanza.", 

3297 "informational", 

3298 "debputy", 

3299 quickfixes=[quick_fix], 

3300 ) 

3301 for ( 

3302 field_name, 

3303 normalized_field_name, 

3304 field_range, 

3305 duplicates, 

3306 used_fields, 

3307 ) in seen_fields.values(): 

3308 if not duplicates: 

3309 continue 

3310 if len(used_fields) != 1 or field_name not in used_fields: 

3311 via_aliases_msg = " (via aliases)" 

3312 else: 

3313 via_aliases_msg = "" 

3314 for dup_range in duplicates: 

3315 lint_state.emit_diagnostic( 

3316 dup_range, 

3317 f'The field "{field_name}"{via_aliases_msg} was used multiple times in this stanza.' 

3318 " Please ensure the field is only used once per stanza.", 

3319 "error", 

3320 "Policy 5.1", 

3321 related_information=[ 

3322 lint_state.related_diagnostic_information( 

3323 field_range, 

3324 message=f"First definition of {field_name}", 

3325 ), 

3326 ], 

3327 ) 

3328 

3329 def __getitem__(self, key: str) -> F: 

3330 key_lc = key.lower() 

3331 key_norm = normalize_dctrl_field_name(key_lc) 

3332 return self.stanza_fields[key_norm] 

3333 

3334 def __len__(self) -> int: 

3335 return len(self.stanza_fields) 

3336 

3337 def __iter__(self) -> Iterator[str]: 

3338 return iter(self.stanza_fields.keys()) 

3339 

3340 def omitted_field_diagnostics( 

3341 self, 

3342 lint_state: LintState, 

3343 deb822_file: Deb822FileElement, 

3344 stanza: Deb822ParagraphElement, 

3345 stanza_position: "TEPosition", 

3346 *, 

3347 inherit_from_stanza: Deb822ParagraphElement | None = None, 

3348 representation_field_range: Range | None = None, 

3349 ) -> None: 

3350 if representation_field_range is None: 3350 ↛ 3351line 3350 didn't jump to line 3351 because the condition on line 3350 was never true

3351 _, representation_field_range = self.stanza_representation( 

3352 stanza, 

3353 stanza_position, 

3354 ) 

3355 for known_field in self.stanza_fields.values(): 

3356 if known_field.name in stanza: 

3357 continue 

3358 

3359 known_field.field_omitted_diagnostics( 

3360 deb822_file, 

3361 representation_field_range, 

3362 stanza, 

3363 stanza_position, 

3364 inherit_from_stanza, 

3365 lint_state, 

3366 ) 

3367 

3368 def _paragraph_representation_field( 

3369 self, 

3370 paragraph: Deb822ParagraphElement, 

3371 ) -> Deb822KeyValuePairElement: 

3372 return next(iter(paragraph.iter_parts_of_type(Deb822KeyValuePairElement))) 

3373 

3374 def normalize_field_name(self, field_name: str) -> str: 

3375 return field_name 

3376 

3377 def stanza_representation( 

3378 self, 

3379 stanza: Deb822ParagraphElement, 

3380 stanza_position: TEPosition, 

3381 ) -> tuple[Deb822KeyValuePairElement, TERange]: 

3382 representation_field = self._paragraph_representation_field(stanza) 

3383 representation_field_range = representation_field.range_in_parent().relative_to( 

3384 stanza_position 

3385 ) 

3386 return representation_field, representation_field_range 

3387 

3388 def reformat_stanza( 

3389 self, 

3390 effective_preference: "EffectiveFormattingPreference", 

3391 stanza: Deb822ParagraphElement, 

3392 stanza_range: TERange, 

3393 formatter: FormatterCallback, 

3394 position_codec: LintCapablePositionCodec, 

3395 lines: list[str], 

3396 ) -> Iterable[TextEdit]: 

3397 for field_name in stanza: 

3398 known_field = self.stanza_fields.get(field_name.lower()) 

3399 if known_field is None: 

3400 continue 

3401 kvpair = stanza.get_kvpair_element(field_name) 

3402 yield from known_field.reformat_field( 

3403 effective_preference, 

3404 stanza_range, 

3405 kvpair, 

3406 formatter, 

3407 position_codec, 

3408 lines, 

3409 ) 

3410 

3411 

3412@dataclasses.dataclass(slots=True) 

3413class Dep5StanzaMetadata(StanzaMetadata[Deb822KnownField]): 

3414 pass 

3415 

3416 

3417@dataclasses.dataclass(slots=True) 

3418class DctrlStanzaMetadata(StanzaMetadata[DctrlKnownField]): 

3419 

3420 def normalize_field_name(self, field_name: str) -> str: 

3421 return normalize_dctrl_field_name(field_name) 

3422 

3423 

3424@dataclasses.dataclass(slots=True) 

3425class DTestsCtrlStanzaMetadata(StanzaMetadata[DTestsCtrlKnownField]): 

3426 

3427 def omitted_field_diagnostics( 

3428 self, 

3429 lint_state: LintState, 

3430 deb822_file: Deb822FileElement, 

3431 stanza: Deb822ParagraphElement, 

3432 stanza_position: "TEPosition", 

3433 *, 

3434 inherit_from_stanza: Deb822ParagraphElement | None = None, 

3435 representation_field_range: Range | None = None, 

3436 ) -> None: 

3437 if representation_field_range is None: 3437 ↛ 3438line 3437 didn't jump to line 3438 because the condition on line 3437 was never true

3438 _, representation_field_range = self.stanza_representation( 

3439 stanza, 

3440 stanza_position, 

3441 ) 

3442 auth_ref = self.stanza_fields["tests"].missing_field_authority 

3443 if "Tests" not in stanza and "Test-Command" not in stanza: 

3444 lint_state.emit_diagnostic( 

3445 representation_field_range, 

3446 'Stanza must have either a "Tests" or a "Test-Command" field', 

3447 "error", 

3448 # TODO: Better authority_reference 

3449 auth_ref, 

3450 ) 

3451 if "Tests" in stanza and "Test-Command" in stanza: 

3452 lint_state.emit_diagnostic( 

3453 representation_field_range, 

3454 'Stanza cannot have both a "Tests" and a "Test-Command" field', 

3455 "error", 

3456 # TODO: Better authority_reference 

3457 auth_ref, 

3458 ) 

3459 

3460 # Note that since we do not use the field names for stanza classification, we 

3461 # always do the super call. 

3462 super(DTestsCtrlStanzaMetadata, self).omitted_field_diagnostics( 

3463 lint_state, 

3464 deb822_file, 

3465 stanza, 

3466 stanza_position, 

3467 representation_field_range=representation_field_range, 

3468 inherit_from_stanza=inherit_from_stanza, 

3469 ) 

3470 

3471 

3472@dataclasses.dataclass(slots=True) 

3473class DebianWatchStanzaMetadata(StanzaMetadata[Deb822KnownField]): 

3474 

3475 def omitted_field_diagnostics( 

3476 self, 

3477 lint_state: LintState, 

3478 deb822_file: Deb822FileElement, 

3479 stanza: Deb822ParagraphElement, 

3480 stanza_position: "TEPosition", 

3481 *, 

3482 inherit_from_stanza: Deb822ParagraphElement | None = None, 

3483 representation_field_range: Range | None = None, 

3484 ) -> None: 

3485 if representation_field_range is None: 3485 ↛ 3486line 3485 didn't jump to line 3486 because the condition on line 3485 was never true

3486 _, representation_field_range = self.stanza_representation( 

3487 stanza, 

3488 stanza_position, 

3489 ) 

3490 

3491 if ( 3491 ↛ 3496line 3491 didn't jump to line 3496 because the condition on line 3491 was never true

3492 self.stanza_type_name != "Header" 

3493 and "Source" not in stanza 

3494 and "Template" not in stanza 

3495 ): 

3496 lint_state.emit_diagnostic( 

3497 representation_field_range, 

3498 'Stanza must have either a "Source" or a "Template" field', 

3499 "error", 

3500 # TODO: Better authority_reference 

3501 "debputy", 

3502 ) 

3503 # The required fields depends on which stanza it is. Therefore, we omit the super 

3504 # call until this error is resolved. 

3505 return 

3506 

3507 super(DebianWatchStanzaMetadata, self).omitted_field_diagnostics( 

3508 lint_state, 

3509 deb822_file, 

3510 stanza, 

3511 stanza_position, 

3512 representation_field_range=representation_field_range, 

3513 inherit_from_stanza=inherit_from_stanza, 

3514 ) 

3515 

3516 

3517def lsp_reference_data_dir() -> str: 

3518 return os.path.join( 

3519 os.path.dirname(__file__), 

3520 "data", 

3521 ) 

3522 

3523 

3524class Deb822FileMetadata(Generic[S, F]): 

3525 

3526 def __init__(self) -> None: 

3527 self._is_initialized = False 

3528 self._data: Deb822ReferenceData | None = None 

3529 

3530 @property 

3531 def reference_data_basename(self) -> str: 

3532 raise NotImplementedError 

3533 

3534 def _new_field( 

3535 self, 

3536 name: str, 

3537 field_value_type: FieldValueClass, 

3538 ) -> F: 

3539 raise NotImplementedError 

3540 

3541 def _reference_data(self) -> Deb822ReferenceData: 

3542 ref = self._data 

3543 if ref is not None: 3543 ↛ 3544line 3543 didn't jump to line 3544 because the condition on line 3543 was never true

3544 return ref 

3545 

3546 p = importlib.resources.files(deb822_ref_data_dir.__name__).joinpath( 

3547 self.reference_data_basename 

3548 ) 

3549 

3550 with p.open("r", encoding="utf-8") as fd: 

3551 raw = MANIFEST_YAML.load(fd) 

3552 

3553 attr_path = AttributePath.root_path(p) 

3554 try: 

3555 ref = DEB822_REFERENCE_DATA_PARSER.parse_input(raw, attr_path) 

3556 except ManifestParseException as e: 

3557 raise ValueError( 

3558 f"Internal error: Could not parse reference data [{self.reference_data_basename}]: {e.message}" 

3559 ) from e 

3560 self._data = ref 

3561 return ref 

3562 

3563 @property 

3564 def is_initialized(self) -> bool: 

3565 return self._is_initialized 

3566 

3567 def ensure_initialized(self) -> None: 

3568 if self.is_initialized: 

3569 return 

3570 # Enables us to use __getitem__ 

3571 self._is_initialized = True 

3572 ref_data = self._reference_data() 

3573 ref_defs = ref_data.get("definitions") 

3574 variables = {} 

3575 ref_variables = ref_defs.get("variables", []) if ref_defs else [] 

3576 for ref_variable in ref_variables: 

3577 name = ref_variable["name"] 

3578 fallback = ref_variable["fallback"] 

3579 variables[name] = fallback 

3580 

3581 def _resolve_doc(template: str | None) -> str | None: 

3582 if template is None: 3582 ↛ 3583line 3582 didn't jump to line 3583 because the condition on line 3582 was never true

3583 return None 

3584 try: 

3585 return template.format(**variables) 

3586 except ValueError as e: 

3587 template_escaped = template.replace("\n", "\\r") 

3588 _error(f"Bad template: {template_escaped}: {e}") 

3589 

3590 for ref_stanza_type in ref_data["stanza_types"]: 

3591 stanza_name = ref_stanza_type["stanza_name"] 

3592 stanza = self[stanza_name] 

3593 stanza_fields = dict(stanza.stanza_fields) 

3594 stanza.stanza_fields = stanza_fields 

3595 for ref_field in ref_stanza_type["fields"]: 

3596 _resolve_field( 

3597 ref_field, 

3598 stanza_fields, 

3599 self._new_field, 

3600 _resolve_doc, 

3601 f"Stanza:{stanza.stanza_type_name}|Field:{ref_field['canonical_name']}", 

3602 ) 

3603 

3604 def file_metadata_applies_to_file( 

3605 self, 

3606 deb822_file: Deb822FileElement | None, 

3607 ) -> bool: 

3608 return deb822_file is not None 

3609 

3610 def classify_stanza(self, stanza: Deb822ParagraphElement, stanza_idx: int) -> S: 

3611 return self.guess_stanza_classification_by_idx(stanza_idx) 

3612 

3613 def guess_stanza_classification_by_idx(self, stanza_idx: int) -> S: 

3614 raise NotImplementedError 

3615 

3616 def stanza_types(self) -> Iterable[S]: 

3617 raise NotImplementedError 

3618 

3619 def __getitem__(self, item: str) -> S: 

3620 raise NotImplementedError 

3621 

3622 def get(self, item: str) -> S | None: 

3623 try: 

3624 return self[item] 

3625 except KeyError: 

3626 return None 

3627 

3628 def reformat( 

3629 self, 

3630 effective_preference: "EffectiveFormattingPreference", 

3631 deb822_file: Deb822FileElement, 

3632 formatter: FormatterCallback, 

3633 _content: str, 

3634 position_codec: LintCapablePositionCodec, 

3635 lines: list[str], 

3636 ) -> Iterable[TextEdit]: 

3637 stanza_idx = -1 

3638 for token_or_element in deb822_file.iter_parts(): 

3639 if isinstance(token_or_element, Deb822ParagraphElement): 

3640 stanza_range = token_or_element.range_in_parent() 

3641 stanza_idx += 1 

3642 stanza_metadata = self.classify_stanza(token_or_element, stanza_idx) 

3643 yield from stanza_metadata.reformat_stanza( 

3644 effective_preference, 

3645 token_or_element, 

3646 stanza_range, 

3647 formatter, 

3648 position_codec, 

3649 lines, 

3650 ) 

3651 else: 

3652 token_range = token_or_element.range_in_parent() 

3653 yield from trim_end_of_line_whitespace( 

3654 position_codec, 

3655 lines, 

3656 line_range=range( 

3657 token_range.start_pos.line_position, 

3658 token_range.end_pos.line_position, 

3659 ), 

3660 ) 

3661 

3662 

3663_DCTRL_SOURCE_STANZA = DctrlStanzaMetadata( 

3664 "Source", 

3665 SOURCE_FIELDS, 

3666 is_substvars_allowed_in_stanza=False, 

3667) 

3668_DCTRL_PACKAGE_STANZA = DctrlStanzaMetadata( 

3669 "Package", 

3670 BINARY_FIELDS, 

3671 is_substvars_allowed_in_stanza=True, 

3672) 

3673 

3674_DEP5_HEADER_STANZA = Dep5StanzaMetadata( 

3675 "Header", 

3676 _DEP5_HEADER_FIELDS, 

3677 is_substvars_allowed_in_stanza=False, 

3678) 

3679_DEP5_FILES_STANZA = Dep5StanzaMetadata( 

3680 "Files", 

3681 _DEP5_FILES_FIELDS, 

3682 is_substvars_allowed_in_stanza=False, 

3683) 

3684_DEP5_LICENSE_STANZA = Dep5StanzaMetadata( 

3685 "License", 

3686 _DEP5_LICENSE_FIELDS, 

3687 is_substvars_allowed_in_stanza=False, 

3688) 

3689 

3690_DTESTSCTRL_STANZA = DTestsCtrlStanzaMetadata( 

3691 "Tests", 

3692 _DTESTSCTRL_FIELDS, 

3693 is_substvars_allowed_in_stanza=False, 

3694) 

3695 

3696_WATCH_HEADER_HEADER_STANZA = DebianWatchStanzaMetadata( 

3697 "Header", 

3698 _DWATCH_HEADER_FIELDS, 

3699 is_substvars_allowed_in_stanza=False, 

3700) 

3701_WATCH_SOURCE_STANZA = DebianWatchStanzaMetadata( 

3702 "Source", 

3703 _DWATCH_SOURCE_FIELDS, 

3704 is_substvars_allowed_in_stanza=False, 

3705) 

3706 

3707 

3708class Dep5FileMetadata(Deb822FileMetadata[Dep5StanzaMetadata, Deb822KnownField]): 

3709 

3710 @property 

3711 def reference_data_basename(self) -> str: 

3712 return "debian_copyright_reference_data.yaml" 

3713 

3714 def _new_field( 

3715 self, 

3716 name: str, 

3717 field_value_type: FieldValueClass, 

3718 ) -> F: 

3719 return Deb822KnownField(name, field_value_type) 

3720 

3721 def file_metadata_applies_to_file( 

3722 self, 

3723 deb822_file: Deb822FileElement | None, 

3724 ) -> bool: 

3725 if not super().file_metadata_applies_to_file(deb822_file): 3725 ↛ 3726line 3725 didn't jump to line 3726 because the condition on line 3725 was never true

3726 return False 

3727 first_stanza = next(iter(deb822_file), None) 

3728 if first_stanza is None or "Format" not in first_stanza: 

3729 # No parseable stanzas or the first one did not have a Format, which is necessary. 

3730 return False 

3731 

3732 for part in deb822_file.iter_parts(): 3732 ↛ 3738line 3732 didn't jump to line 3738 because the loop on line 3732 didn't complete

3733 if part.is_error: 

3734 # Error first, then it might just be a "Format:" in the middle of a free-text file. 

3735 return False 

3736 if part is first_stanza: 3736 ↛ 3732line 3736 didn't jump to line 3732 because the condition on line 3736 was always true

3737 break 

3738 return True 

3739 

3740 def classify_stanza( 

3741 self, 

3742 stanza: Deb822ParagraphElement, 

3743 stanza_idx: int, 

3744 ) -> Dep5StanzaMetadata: 

3745 self.ensure_initialized() 

3746 if stanza_idx == 0: 3746 ↛ 3747line 3746 didn't jump to line 3747 because the condition on line 3746 was never true

3747 return _DEP5_HEADER_STANZA 

3748 if stanza_idx > 0: 3748 ↛ 3752line 3748 didn't jump to line 3752 because the condition on line 3748 was always true

3749 if "Files" in stanza: 

3750 return _DEP5_FILES_STANZA 

3751 return _DEP5_LICENSE_STANZA 

3752 raise ValueError("The stanza_idx must be 0 or greater") 

3753 

3754 def guess_stanza_classification_by_idx(self, stanza_idx: int) -> Dep5StanzaMetadata: 

3755 self.ensure_initialized() 

3756 if stanza_idx == 0: 

3757 return _DEP5_HEADER_STANZA 

3758 if stanza_idx > 0: 

3759 return _DEP5_FILES_STANZA 

3760 raise ValueError("The stanza_idx must be 0 or greater") 

3761 

3762 def stanza_types(self) -> Iterable[Dep5StanzaMetadata]: 

3763 self.ensure_initialized() 

3764 # Order assumption made in the LSP code. 

3765 yield _DEP5_HEADER_STANZA 

3766 yield _DEP5_FILES_STANZA 

3767 yield _DEP5_LICENSE_STANZA 

3768 

3769 def __getitem__(self, item: str) -> Dep5StanzaMetadata: 

3770 self.ensure_initialized() 

3771 if item == "Header": 

3772 return _DEP5_HEADER_STANZA 

3773 if item == "Files": 

3774 return _DEP5_FILES_STANZA 

3775 if item == "License": 3775 ↛ 3777line 3775 didn't jump to line 3777 because the condition on line 3775 was always true

3776 return _DEP5_LICENSE_STANZA 

3777 raise KeyError(item) 

3778 

3779 

3780class DebianWatch5FileMetadata( 

3781 Deb822FileMetadata[DebianWatchStanzaMetadata, Deb822KnownField] 

3782): 

3783 

3784 @property 

3785 def reference_data_basename(self) -> str: 

3786 return "debian_watch_reference_data.yaml" 

3787 

3788 def _new_field( 

3789 self, 

3790 name: str, 

3791 field_value_type: FieldValueClass, 

3792 ) -> F: 

3793 return Deb822KnownField(name, field_value_type) 

3794 

3795 def file_metadata_applies_to_file( 

3796 self, deb822_file: Deb822FileElement | None 

3797 ) -> bool: 

3798 if not super().file_metadata_applies_to_file(deb822_file): 3798 ↛ 3799line 3798 didn't jump to line 3799 because the condition on line 3798 was never true

3799 return False 

3800 first_stanza = next(iter(deb822_file), None) 

3801 

3802 if first_stanza is None or "Version" not in first_stanza: 3802 ↛ 3804line 3802 didn't jump to line 3804 because the condition on line 3802 was never true

3803 # No parseable stanzas or the first one did not have a Version field, which is necessary. 

3804 return False 

3805 

3806 try: 

3807 if int(first_stanza.get("Version")) < 5: 3807 ↛ 3808line 3807 didn't jump to line 3808 because the condition on line 3807 was never true

3808 return False 

3809 except (ValueError, IndexError, TypeError): 

3810 return False 

3811 

3812 for part in deb822_file.iter_parts(): 3812 ↛ 3818line 3812 didn't jump to line 3818 because the loop on line 3812 didn't complete

3813 if part.is_error: 3813 ↛ 3815line 3813 didn't jump to line 3815 because the condition on line 3813 was never true

3814 # Error first, then it might just be a "Version:" in the middle of a free-text file. 

3815 return False 

3816 if part is first_stanza: 3816 ↛ 3812line 3816 didn't jump to line 3812 because the condition on line 3816 was always true

3817 break 

3818 return True 

3819 

3820 def classify_stanza( 

3821 self, 

3822 stanza: Deb822ParagraphElement, 

3823 stanza_idx: int, 

3824 ) -> DebianWatchStanzaMetadata: 

3825 self.ensure_initialized() 

3826 if stanza_idx == 0: 

3827 return _WATCH_HEADER_HEADER_STANZA 

3828 if stanza_idx > 0: 3828 ↛ 3830line 3828 didn't jump to line 3830 because the condition on line 3828 was always true

3829 return _WATCH_SOURCE_STANZA 

3830 raise ValueError("The stanza_idx must be 0 or greater") 

3831 

3832 def guess_stanza_classification_by_idx( 

3833 self, stanza_idx: int 

3834 ) -> DebianWatchStanzaMetadata: 

3835 self.ensure_initialized() 

3836 if stanza_idx == 0: 3836 ↛ 3837line 3836 didn't jump to line 3837 because the condition on line 3836 was never true

3837 return _WATCH_HEADER_HEADER_STANZA 

3838 if stanza_idx > 0: 3838 ↛ 3840line 3838 didn't jump to line 3840 because the condition on line 3838 was always true

3839 return _WATCH_SOURCE_STANZA 

3840 raise ValueError("The stanza_idx must be 0 or greater") 

3841 

3842 def stanza_types(self) -> Iterable[DebianWatchStanzaMetadata]: 

3843 self.ensure_initialized() 

3844 # Order assumption made in the LSP code. 

3845 yield _WATCH_HEADER_HEADER_STANZA 

3846 yield _WATCH_SOURCE_STANZA 

3847 

3848 def __getitem__(self, item: str) -> DebianWatchStanzaMetadata: 

3849 self.ensure_initialized() 

3850 if item == "Header": 

3851 return _WATCH_HEADER_HEADER_STANZA 

3852 if item == "Source": 3852 ↛ 3854line 3852 didn't jump to line 3854 because the condition on line 3852 was always true

3853 return _WATCH_SOURCE_STANZA 

3854 raise KeyError(item) 

3855 

3856 

3857def _resolve_keyword( 

3858 ref_value: StaticValue, 

3859 known_values: dict[str, Keyword], 

3860 resolve_template: Callable[[str | None], str | None], 

3861 translation_context: str, 

3862) -> None: 

3863 value_key = ref_value["value"] 

3864 changes = { 

3865 "translation_context": translation_context, 

3866 } 

3867 try: 

3868 known_value = known_values[value_key] 

3869 except KeyError: 

3870 known_value = Keyword(value_key) 

3871 known_values[value_key] = known_value 

3872 else: 

3873 if known_value.is_alias_of: 3873 ↛ 3874line 3873 didn't jump to line 3874 because the condition on line 3873 was never true

3874 raise ValueError( 

3875 f"The value {known_value.value} has an alias {known_value.is_alias_of} that conflicts with" 

3876 f' {value_key} or the data file used an alias in its `canonical-name` rather than the "true" name' 

3877 ) 

3878 value_doc = ref_value.get("documentation") 

3879 if value_doc is not None: 

3880 changes["synopsis"] = value_doc.get("synopsis") 

3881 changes["long_description"] = resolve_template( 

3882 value_doc.get("long_description") 

3883 ) 

3884 if is_exclusive := ref_value.get("is_exclusive"): 

3885 changes["is_exclusive"] = is_exclusive 

3886 if (sort_key := ref_value.get("sort_key")) is not None: 

3887 changes["sort_text"] = sort_key 

3888 if (usage_hint := ref_value.get("usage_hint")) is not None: 

3889 changes["usage_hint"] = usage_hint 

3890 if changes: 3890 ↛ 3894line 3890 didn't jump to line 3894 because the condition on line 3890 was always true

3891 known_value = known_value.replace(**changes) 

3892 known_values[value_key] = known_value 

3893 

3894 _expand_aliases( 

3895 known_value, 

3896 known_values, 

3897 operator.attrgetter("value"), 

3898 ref_value.get("aliases"), 

3899 "The value `{ALIAS}` is an alias of `{NAME}`.", 

3900 ) 

3901 

3902 

3903def _resolve_field( 

3904 ref_field: Deb822Field, 

3905 stanza_fields: dict[str, F], 

3906 field_constructor: Callable[[str, FieldValueClass], F], 

3907 resolve_template: Callable[[str | None], str | None], 

3908 translation_context: str, 

3909) -> None: 

3910 field_name = ref_field["canonical_name"] 

3911 field_value_type = FieldValueClass.from_key(ref_field["field_value_type"]) 

3912 doc = ref_field.get("documentation") 

3913 ref_values = ref_field.get("values", []) 

3914 norm_field_name = normalize_dctrl_field_name(field_name.lower()) 

3915 

3916 try: 

3917 field = stanza_fields[norm_field_name] 

3918 except KeyError: 

3919 field = field_constructor( 

3920 field_name, 

3921 field_value_type, 

3922 ) 

3923 stanza_fields[norm_field_name] = field 

3924 else: 

3925 if field.name != field_name: 3925 ↛ 3926line 3925 didn't jump to line 3926 because the condition on line 3925 was never true

3926 _error( 

3927 f'Error in reference data: Code uses "{field.name}" as canonical name and the data file' 

3928 f" uses {field_name}. Please ensure the data is correctly aligned." 

3929 ) 

3930 if field.field_value_class != field_value_type: 3930 ↛ 3931line 3930 didn't jump to line 3931 because the condition on line 3930 was never true

3931 _error( 

3932 f'Error in reference data for field "{field.name}": Code has' 

3933 f" {field.field_value_class.key} and the data file uses {field_value_type.key}" 

3934 f" for field-value-type. Please ensure the data is correctly aligned." 

3935 ) 

3936 if field.is_alias_of: 3936 ↛ 3937line 3936 didn't jump to line 3937 because the condition on line 3936 was never true

3937 raise ValueError( 

3938 f"The field {field.name} has an alias {field.is_alias_of} that conflicts with" 

3939 f' {field_name} or the data file used an alias in its `canonical-name` rather than the "true" name' 

3940 ) 

3941 

3942 if doc is not None: 

3943 field.synopsis = doc.get("synopsis") 

3944 field.long_description = resolve_template(doc.get("long_description")) 

3945 

3946 field.default_value = ref_field.get("default_value") 

3947 field.warn_if_default = ref_field.get("warn_if_default", True) 

3948 field.spellcheck_value = ref_field.get("spellcheck_value", False) 

3949 field.deprecated_with_no_replacement = ref_field.get( 

3950 "is_obsolete_without_replacement", False 

3951 ) 

3952 field.replaced_by = ref_field.get("replaced_by") 

3953 field.translation_context = translation_context 

3954 field.usage_hint = ref_field.get("usage_hint") 

3955 field.missing_field_severity = ref_field.get("missing_field_severity", None) 

3956 unknown_value_severity = ref_field.get("unknown_value_severity", "error") 

3957 field.unknown_value_severity = ( 

3958 None if unknown_value_severity == "none" else unknown_value_severity 

3959 ) 

3960 field.unknown_value_authority = ref_field.get("unknown_value_authority", "debputy") 

3961 field.missing_field_authority = ref_field.get("missing_field_authority", "debputy") 

3962 field.is_substvars_disabled_even_if_allowed_by_stanza = not ref_field.get( 

3963 "supports_substvars", 

3964 True, 

3965 ) 

3966 field.inheritable_from_other_stanza = ref_field.get( 

3967 "inheritable_from_other_stanza", 

3968 False, 

3969 ) 

3970 

3971 known_values = field.known_values 

3972 if known_values is None: 

3973 known_values = {} 

3974 else: 

3975 known_values = dict(known_values) 

3976 

3977 for ref_value in ref_values: 

3978 _resolve_keyword(ref_value, known_values, resolve_template, translation_context) 

3979 

3980 if known_values: 

3981 field.known_values = known_values 

3982 

3983 _expand_aliases( 

3984 field, 

3985 stanza_fields, 

3986 operator.attrgetter("name"), 

3987 ref_field.get("aliases"), 

3988 "The field `{ALIAS}` is an alias of `{NAME}`.", 

3989 ) 

3990 

3991 

3992A = TypeVar("A", Keyword, Deb822KnownField) 

3993 

3994 

3995def _expand_aliases( 

3996 item: A, 

3997 item_container: dict[str, A], 

3998 canonical_name_resolver: Callable[[A], str], 

3999 aliases_ref: list[Alias] | None, 

4000 doc_template: str, 

4001) -> None: 

4002 if aliases_ref is None: 

4003 return 

4004 name = canonical_name_resolver(item) 

4005 assert name is not None, "canonical_name_resolver is not allowed to return None" 

4006 for alias_ref in aliases_ref: 

4007 alias_name = alias_ref["alias"] 

4008 alias_doc = item.long_description 

4009 is_completion_suggestion = alias_ref.get("is_completion_suggestion", False) 

4010 doc_suffix = doc_template.format(NAME=name, ALIAS=alias_name) 

4011 if alias_doc: 

4012 alias_doc += f"\n\n{doc_suffix}" 

4013 else: 

4014 alias_doc = doc_suffix 

4015 alias_field = item.replace( 

4016 long_description=alias_doc, 

4017 is_alias_of=name, 

4018 is_completion_suggestion=is_completion_suggestion, 

4019 ) 

4020 alias_key = alias_name.lower() 

4021 if alias_name in item_container: 4021 ↛ 4022line 4021 didn't jump to line 4022 because the condition on line 4021 was never true

4022 existing_name = canonical_name_resolver(item_container[alias_key]) 

4023 assert ( 

4024 existing_name is not None 

4025 ), "canonical_name_resolver is not allowed to return None" 

4026 raise ValueError( 

4027 f"The value {name} has an alias {alias_name} that conflicts with {existing_name}" 

4028 ) 

4029 item_container[alias_key] = alias_field 

4030 

4031 

4032class DctrlFileMetadata(Deb822FileMetadata[DctrlStanzaMetadata, DctrlKnownField]): 

4033 

4034 @property 

4035 def reference_data_basename(self) -> str: 

4036 return "debian_control_reference_data.yaml" 

4037 

4038 def _new_field( 

4039 self, 

4040 name: str, 

4041 field_value_type: FieldValueClass, 

4042 ) -> F: 

4043 return DctrlKnownField(name, field_value_type) 

4044 

4045 def guess_stanza_classification_by_idx( 

4046 self, 

4047 stanza_idx: int, 

4048 ) -> DctrlStanzaMetadata: 

4049 self.ensure_initialized() 

4050 if stanza_idx == 0: 

4051 return _DCTRL_SOURCE_STANZA 

4052 if stanza_idx > 0: 4052 ↛ 4054line 4052 didn't jump to line 4054 because the condition on line 4052 was always true

4053 return _DCTRL_PACKAGE_STANZA 

4054 raise ValueError("The stanza_idx must be 0 or greater") 

4055 

4056 def stanza_types(self) -> Iterable[DctrlStanzaMetadata]: 

4057 self.ensure_initialized() 

4058 # Order assumption made in the LSP code. 

4059 yield _DCTRL_SOURCE_STANZA 

4060 yield _DCTRL_PACKAGE_STANZA 

4061 

4062 def __getitem__(self, item: str) -> DctrlStanzaMetadata: 

4063 self.ensure_initialized() 

4064 if item == "Source": 

4065 return _DCTRL_SOURCE_STANZA 

4066 if item == "Package": 4066 ↛ 4068line 4066 didn't jump to line 4068 because the condition on line 4066 was always true

4067 return _DCTRL_PACKAGE_STANZA 

4068 raise KeyError(item) 

4069 

4070 def reformat( 

4071 self, 

4072 effective_preference: "EffectiveFormattingPreference", 

4073 deb822_file: Deb822FileElement, 

4074 formatter: FormatterCallback, 

4075 content: str, 

4076 position_codec: LintCapablePositionCodec, 

4077 lines: list[str], 

4078 ) -> Iterable[TextEdit]: 

4079 edits = list( 

4080 super().reformat( 

4081 effective_preference, 

4082 deb822_file, 

4083 formatter, 

4084 content, 

4085 position_codec, 

4086 lines, 

4087 ) 

4088 ) 

4089 

4090 if ( 4090 ↛ 4095line 4090 didn't jump to line 4095 because the condition on line 4090 was always true

4091 not effective_preference.deb822_normalize_stanza_order 

4092 or deb822_file.find_first_error_element() is not None 

4093 ): 

4094 return edits 

4095 names = [] 

4096 for idx, stanza in enumerate(deb822_file): 

4097 if idx < 2: 

4098 continue 

4099 name = stanza.get("Package") 

4100 if name is None: 

4101 return edits 

4102 names.append(name) 

4103 

4104 reordered = sorted(names) 

4105 if names == reordered: 

4106 return edits 

4107 

4108 if edits: 

4109 content = apply_text_edits(content, lines, edits) 

4110 lines = content.splitlines(keepends=True) 

4111 deb822_file = parse_deb822_file( 

4112 lines, 

4113 accept_files_with_duplicated_fields=True, 

4114 accept_files_with_error_tokens=True, 

4115 ) 

4116 

4117 stanzas = list(deb822_file) 

4118 reordered_stanza = stanzas[:2] + sorted( 

4119 stanzas[2:], key=operator.itemgetter("Package") 

4120 ) 

4121 bits = [] 

4122 stanza_idx = 0 

4123 for token_or_element in deb822_file.iter_parts(): 

4124 if isinstance(token_or_element, Deb822ParagraphElement): 

4125 bits.append(reordered_stanza[stanza_idx].dump()) 

4126 stanza_idx += 1 

4127 else: 

4128 bits.append(token_or_element.convert_to_text()) 

4129 

4130 new_content = "".join(bits) 

4131 

4132 return [ 

4133 TextEdit( 

4134 Range( 

4135 Position(0, 0), 

4136 Position(len(lines) + 1, 0), 

4137 ), 

4138 new_content, 

4139 ) 

4140 ] 

4141 

4142 

4143class DTestsCtrlFileMetadata( 

4144 Deb822FileMetadata[DTestsCtrlStanzaMetadata, DTestsCtrlKnownField] 

4145): 

4146 

4147 @property 

4148 def reference_data_basename(self) -> str: 

4149 return "debian_tests_control_reference_data.yaml" 

4150 

4151 def _new_field( 

4152 self, 

4153 name: str, 

4154 field_value_type: FieldValueClass, 

4155 ) -> F: 

4156 return DTestsCtrlKnownField(name, field_value_type) 

4157 

4158 def guess_stanza_classification_by_idx(self, stanza_idx: int) -> S: 

4159 if stanza_idx >= 0: 4159 ↛ 4162line 4159 didn't jump to line 4162 because the condition on line 4159 was always true

4160 self.ensure_initialized() 

4161 return _DTESTSCTRL_STANZA 

4162 raise ValueError("The stanza_idx must be 0 or greater") 

4163 

4164 def stanza_types(self) -> Iterable[S]: 

4165 self.ensure_initialized() 

4166 yield _DTESTSCTRL_STANZA 

4167 

4168 def __getitem__(self, item: str) -> S: 

4169 self.ensure_initialized() 

4170 if item == "Tests": 4170 ↛ 4172line 4170 didn't jump to line 4172 because the condition on line 4170 was always true

4171 return _DTESTSCTRL_STANZA 

4172 raise KeyError(item) 

4173 

4174 

4175TRANSLATABLE_DEB822_FILE_METADATA: Sequence[ 

4176 Callable[[], Deb822FileMetadata[Any, Any]] 

4177] = [ 

4178 DctrlFileMetadata, 

4179 Dep5FileMetadata, 

4180 DTestsCtrlFileMetadata, 

4181]