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
« 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
23from debian.debian_support import DpkgArchTable, Version
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
91try:
92 from debian._deb822_repro.locatable import (
93 Position as TEPosition,
94 Range as TERange,
95 START_POSITION,
96 )
97except ImportError:
98 pass
101if TYPE_CHECKING:
102 from debputy.lsp.maint_prefs import EffectiveFormattingPreference
103 from debputy.lsp.debputy_ls import DebputyLanguageServer
106F = TypeVar("F", bound="Deb822KnownField", covariant=True)
107S = TypeVar("S", bound="StanzaMetadata")
110SUBSTVAR_RE = re.compile(r"[$][{][a-zA-Z0-9][a-zA-Z0-9-:]*[}]")
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")
121CustomFieldCheck = Callable[
122 [
123 "F",
124 Deb822FileElement,
125 Deb822KeyValuePairElement,
126 "TERange",
127 "TERange",
128 Deb822ParagraphElement,
129 "TEPosition",
130 LintState,
131 ],
132 None,
133]
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 }
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 }
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)
238ALL_COMPONENTS = frozenset(
239 [
240 "main",
241 "restricted", # Ubuntu
242 "non-free",
243 "non-free-firmware",
244 "contrib",
245 ]
246)
249def _fields(*fields: F) -> Mapping[str, F]:
250 return {normalize_dctrl_field_name(f.name.lower()): f for f in fields}
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}"
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)
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.
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.
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
343@functools.lru_cache
344def _dpkg_arch_table() -> DpkgArchTable:
345 return DpkgArchTable.load_arch_table()
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)
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 )
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
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
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 )
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 )
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 )
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 )
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
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
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 )
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 )
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 )
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 )
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 )
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 )
795def _has_packaging_expected_file(
796 name: str,
797 msg: str,
798 severity: LintSeverity = "error",
799) -> CustomFieldCheck:
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 )
824 return _impl
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)
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
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 )
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
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
889 pref = lint_state.maint_preference_table.maintainer_preferences.get(email)
890 if pref is None or not pref.canonical_name:
891 continue
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 )
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:
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 )
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 )
972def _each_value_match_regex_validation(
973 regex: re.Pattern,
974 *,
975 diagnostic_severity: LintSeverity = "error",
976 authority_reference: str | None = None,
977) -> CustomFieldCheck:
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 )
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
1011 if "${" in v:
1012 # Ignore substvars
1013 continue
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 )
1026 return _validator
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)
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]
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
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)
1069 return TERange(
1070 TEPosition(
1071 start_line,
1072 start_cursor_pos,
1073 ),
1074 TEPosition(
1075 end_line,
1076 end_cursor_pos,
1077 ),
1078 )
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
1096_COLLAPSE_WHITESPACE = re.compile(r"\s+")
1099def _cleanup_rel(rel: str) -> str:
1100 return _COLLAPSE_WHITESPACE.sub(" ", rel.strip())
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 )
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
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
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
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
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
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
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
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)
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)
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
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)
1266 sorted_version_operators = sorted(version_operators)
1268 excluding_equal = f"{version_operator}{version_operator}"
1269 including_equal = f"{version_operator}="
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
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
1324 relation_dup_table = collections.defaultdict(list)
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)
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>"))
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
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)
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)
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 )
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 )
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 )
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,)
1496_RE_SLASHES = re.compile(r"//+")
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
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 )
1531 for m in _RE_SLASHES.finditer(value, slash_check_index):
1532 m_start, m_end = m.span(0)
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 )
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)
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
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)
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
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 )
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 )
1743 return _validator
1746@dataclasses.dataclass(slots=True, frozen=True)
1747class PackageNameSectionRule:
1748 section: str
1749 check: Callable[[str], bool]
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)
1761 def _impl(v: str) -> bool:
1762 return check(v) and confirm_re.search(v)
1764 elif isinstance(check, re.Pattern): 1764 ↛ 1766line 1764 didn't jump to line 1766 because the condition on line 1764 was never true
1766 def _impl(v: str) -> bool:
1767 return check.search(v) is not None
1769 else:
1770 _impl = check
1772 return PackageNameSectionRule(section, _impl)
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]
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
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
1965def _dep5_escape_path(path: str) -> str:
1966 return path.replace(" ", "?")
1969def _noop_escape_path(path: str) -> str:
1970 return path
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
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
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 )
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 )
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 )
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)
2082 doc = self.long_description
2083 if doc:
2084 doc = MarkupContent(
2085 value=doc,
2086 kind=markdown_kind,
2087 )
2088 else:
2089 doc = None
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 )
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
2118 if is_dep5_file_list:
2119 supports_spaces_in_filename = True
2120 supports_dir_match = False
2121 match_non_persistent_paths = False
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 )
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 = []
2139 path_escaper = _dep5_escape_path if is_dep5_file_list else _noop_escape_path
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
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 )
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 ]
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
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
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 )
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 )
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 )
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 )
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 )
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 )
2406 assert interpreter is not None
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 )
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 )
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
2476 allowed_values = self.known_values
2477 if not allowed_values:
2478 return
2480 first_value = None
2481 first_exclusive_value_ref = None
2482 first_exclusive_value = None
2483 has_emitted_for_exclusive = False
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
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 )
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)
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 )
2536 if first_value is None:
2537 first_value = value
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 )
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 )
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
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 )
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 )
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 )
2631 def replace(self, **changes: Any) -> "Self":
2632 return dataclasses.replace(self, **changes)
2635@dataclasses.dataclass(slots=True)
2636class DctrlLikeKnownField(Deb822KnownField):
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
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 )
2681 seen: set[str] = set()
2682 old_kvpair_range = kvpair.range_in_parent()
2683 sort = self.is_sortable_field
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 ]
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()
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 )
2728 @property
2729 def reformattable_field(self) -> bool:
2730 return self.is_relationship_field or self.is_sortable_field
2732 @property
2733 def is_relationship_field(self) -> bool:
2734 return False
2736 @property
2737 def is_sortable_field(self) -> bool:
2738 return self.is_relationship_field
2741@dataclasses.dataclass(slots=True)
2742class DTestsCtrlKnownField(DctrlLikeKnownField):
2743 @property
2744 def is_relationship_field(self) -> bool:
2745 return self.name == "Depends"
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 )
2756@dataclasses.dataclass(slots=True)
2757class DctrlKnownField(DctrlLikeKnownField):
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
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
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
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 )
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
2835 return super(DctrlKnownField, self).reformat_field(
2836 effective_preference,
2837 stanza_range,
2838 kvpair,
2839 formatter,
2840 position_codec,
2841 lines,
2842 )
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 )
2852 @property
2853 def reformattable_field(self) -> bool:
2854 return self.is_relationship_field or self.name == "Uploaders"
2857@dataclasses.dataclass(slots=True)
2858class DctrlRelationshipKnownField(DctrlKnownField):
2859 allowed_version_operators: frozenset[str] = frozenset()
2860 supports_or_relation: bool = True
2862 @property
2863 def is_relationship_field(self) -> bool:
2864 return True
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)
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)
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()
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
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]]] = {}
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 )
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 )
3282 inherit_value = (
3283 inherit_from_stanza.get(field_name) if inherit_from_stanza else None
3284 )
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 )
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]
3334 def __len__(self) -> int:
3335 return len(self.stanza_fields)
3337 def __iter__(self) -> Iterator[str]:
3338 return iter(self.stanza_fields.keys())
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
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 )
3368 def _paragraph_representation_field(
3369 self,
3370 paragraph: Deb822ParagraphElement,
3371 ) -> Deb822KeyValuePairElement:
3372 return next(iter(paragraph.iter_parts_of_type(Deb822KeyValuePairElement)))
3374 def normalize_field_name(self, field_name: str) -> str:
3375 return field_name
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
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 )
3412@dataclasses.dataclass(slots=True)
3413class Dep5StanzaMetadata(StanzaMetadata[Deb822KnownField]):
3414 pass
3417@dataclasses.dataclass(slots=True)
3418class DctrlStanzaMetadata(StanzaMetadata[DctrlKnownField]):
3420 def normalize_field_name(self, field_name: str) -> str:
3421 return normalize_dctrl_field_name(field_name)
3424@dataclasses.dataclass(slots=True)
3425class DTestsCtrlStanzaMetadata(StanzaMetadata[DTestsCtrlKnownField]):
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 )
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 )
3472@dataclasses.dataclass(slots=True)
3473class DebianWatchStanzaMetadata(StanzaMetadata[Deb822KnownField]):
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 )
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
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 )
3517def lsp_reference_data_dir() -> str:
3518 return os.path.join(
3519 os.path.dirname(__file__),
3520 "data",
3521 )
3524class Deb822FileMetadata(Generic[S, F]):
3526 def __init__(self) -> None:
3527 self._is_initialized = False
3528 self._data: Deb822ReferenceData | None = None
3530 @property
3531 def reference_data_basename(self) -> str:
3532 raise NotImplementedError
3534 def _new_field(
3535 self,
3536 name: str,
3537 field_value_type: FieldValueClass,
3538 ) -> F:
3539 raise NotImplementedError
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
3546 p = importlib.resources.files(deb822_ref_data_dir.__name__).joinpath(
3547 self.reference_data_basename
3548 )
3550 with p.open("r", encoding="utf-8") as fd:
3551 raw = MANIFEST_YAML.load(fd)
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
3563 @property
3564 def is_initialized(self) -> bool:
3565 return self._is_initialized
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
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}")
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 )
3604 def file_metadata_applies_to_file(
3605 self,
3606 deb822_file: Deb822FileElement | None,
3607 ) -> bool:
3608 return deb822_file is not None
3610 def classify_stanza(self, stanza: Deb822ParagraphElement, stanza_idx: int) -> S:
3611 return self.guess_stanza_classification_by_idx(stanza_idx)
3613 def guess_stanza_classification_by_idx(self, stanza_idx: int) -> S:
3614 raise NotImplementedError
3616 def stanza_types(self) -> Iterable[S]:
3617 raise NotImplementedError
3619 def __getitem__(self, item: str) -> S:
3620 raise NotImplementedError
3622 def get(self, item: str) -> S | None:
3623 try:
3624 return self[item]
3625 except KeyError:
3626 return None
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 )
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)
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)
3690_DTESTSCTRL_STANZA = DTestsCtrlStanzaMetadata(
3691 "Tests",
3692 _DTESTSCTRL_FIELDS,
3693 is_substvars_allowed_in_stanza=False,
3694)
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)
3708class Dep5FileMetadata(Deb822FileMetadata[Dep5StanzaMetadata, Deb822KnownField]):
3710 @property
3711 def reference_data_basename(self) -> str:
3712 return "debian_copyright_reference_data.yaml"
3714 def _new_field(
3715 self,
3716 name: str,
3717 field_value_type: FieldValueClass,
3718 ) -> F:
3719 return Deb822KnownField(name, field_value_type)
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
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
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")
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")
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
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)
3780class DebianWatch5FileMetadata(
3781 Deb822FileMetadata[DebianWatchStanzaMetadata, Deb822KnownField]
3782):
3784 @property
3785 def reference_data_basename(self) -> str:
3786 return "debian_watch_reference_data.yaml"
3788 def _new_field(
3789 self,
3790 name: str,
3791 field_value_type: FieldValueClass,
3792 ) -> F:
3793 return Deb822KnownField(name, field_value_type)
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)
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
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
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
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")
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")
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
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)
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
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 )
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())
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 )
3942 if doc is not None:
3943 field.synopsis = doc.get("synopsis")
3944 field.long_description = resolve_template(doc.get("long_description"))
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 )
3971 known_values = field.known_values
3972 if known_values is None:
3973 known_values = {}
3974 else:
3975 known_values = dict(known_values)
3977 for ref_value in ref_values:
3978 _resolve_keyword(ref_value, known_values, resolve_template, translation_context)
3980 if known_values:
3981 field.known_values = known_values
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 )
3992A = TypeVar("A", Keyword, Deb822KnownField)
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
4032class DctrlFileMetadata(Deb822FileMetadata[DctrlStanzaMetadata, DctrlKnownField]):
4034 @property
4035 def reference_data_basename(self) -> str:
4036 return "debian_control_reference_data.yaml"
4038 def _new_field(
4039 self,
4040 name: str,
4041 field_value_type: FieldValueClass,
4042 ) -> F:
4043 return DctrlKnownField(name, field_value_type)
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")
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
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)
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 )
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)
4104 reordered = sorted(names)
4105 if names == reordered:
4106 return edits
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 )
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())
4130 new_content = "".join(bits)
4132 return [
4133 TextEdit(
4134 Range(
4135 Position(0, 0),
4136 Position(len(lines) + 1, 0),
4137 ),
4138 new_content,
4139 )
4140 ]
4143class DTestsCtrlFileMetadata(
4144 Deb822FileMetadata[DTestsCtrlStanzaMetadata, DTestsCtrlKnownField]
4145):
4147 @property
4148 def reference_data_basename(self) -> str:
4149 return "debian_tests_control_reference_data.yaml"
4151 def _new_field(
4152 self,
4153 name: str,
4154 field_value_type: FieldValueClass,
4155 ) -> F:
4156 return DTestsCtrlKnownField(name, field_value_type)
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")
4164 def stanza_types(self) -> Iterable[S]:
4165 self.ensure_initialized()
4166 yield _DTESTSCTRL_STANZA
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)
4175TRANSLATABLE_DEB822_FILE_METADATA: Sequence[
4176 Callable[[], Deb822FileMetadata[Any, Any]]
4177] = [
4178 DctrlFileMetadata,
4179 Dep5FileMetadata,
4180 DTestsCtrlFileMetadata,
4181]