1from dataclasses import dataclass, field, fields
2from enum import Enum
3from pathlib import Path
4from typing import Any, Required, TypedDict, cast
5
6from jsonschema import ValidationError, validate
7
8COMMENT_FILETYPE = {
9 "cpp": ["c", "ci", "cpp", "cc", "cxx", "h", "hpp", "hxx", "hh", "ihl"],
10 "python": ["py"],
11 "cs": ["cs"],
12 # ".mts"/".cts" are TypeScript's own ESM/CJS module variants. ".js"/".jsx"/
13 # ".mjs"/".cjs" are JavaScript. All of these share the "ts" comment type:
14 # comment syntax is identical across the family, and the analyse stage
15 # picks the actual tree-sitter grammar per file from the suffix (the plain
16 # TypeScript grammar for ".ts"/".mts"/".cts", the TSX grammar for
17 # everything else — see utils.ts_grammar_key), so no separate
18 # comment_type value is needed here.
19 "ts": ["ts", "tsx", "mts", "cts", "js", "jsx", "mjs", "cjs"],
20 "yaml": ["yml", "yaml"],
21 "rust": ["rs"],
22 "go": ["go"],
23 "jsonc": ["jsonc", "json"],
24 # Bash uses `#` line comments; zsh and ksh share the same comment syntax and
25 # are scanned with the bash grammar. Fish is intentionally excluded: it is
26 # not POSIX-compatible and no tree-sitter-fish distribution is published on
27 # PyPI, so it cannot be wired in here. Track fish separately if a PyPI
28 # grammar becomes available.
29 "bash": ["sh", "bash", "zsh", "ksh"],
30}
31
32
33# Default ``exclude`` glob patterns applied to ``ts`` (TypeScript/JavaScript
34# family) projects when their configuration does not set ``exclude``
35# explicitly.
36#
37# ``src_dir`` defaults to ``"./"`` and the ``ts`` comment type claims ``.js``/
38# ``.jsx``/``.mjs``/``.cjs`` in addition to TypeScript's own extensions, so a
39# checked-in ``tsc``/bundler output directory (``dist/``, ``build/``, ...) is
40# otherwise scanned as source alongside the ``.ts`` it was generated from,
41# producing duplicate need ids for the same marker. These directory names are
42# common generated-output or dependency locations across the JS/TS ecosystem,
43# so excluding them by default avoids that duplication for most projects out
44# of the box.
45#
46# ``**/lib/**`` is deliberately NOT in this list: it is ambiguous even within
47# the JS/TS ecosystem, where many packages use ``lib/`` for hand-written
48# source rather than as a ``tsc`` ``outDir``. Projects whose ``outDir`` is
49# ``lib`` should add ``"**/lib/**"`` to their own ``exclude`` explicitly.
50#
51# This default is applied only for ``comment_type == "ts"``. Every other
52# ``comment_type`` (``cpp``, ``python``, ``rust``, ``go``, ``yaml``, ``jsonc``,
53# ``bash``, ``cs``, ...) defaults ``exclude`` to ``[]`` — unchanged from
54# before this default existed. ``cpp`` projects in particular very commonly
55# keep hand-written library source under ``lib/``, so a directory-name-based
56# default that isn't scoped to the language family would silently drop
57# markers there.
58#
59# Setting ``exclude`` explicitly in a project's configuration replaces this
60# default outright (it is not merged) — including setting it to ``[]`` to
61# scan everything.
62TS_DEFAULT_EXCLUDE = [
63 "**/node_modules/**",
64 "**/dist/**",
65 "**/build/**",
66 "**/out/**",
67 "**/coverage/**",
68]
69
70
71class CommentType(str, Enum): # noqa: UP042 # StrEnum changes str(member), which reaches CLI warnings and error messages
72 python = "python"
73 cpp = "cpp"
74 cs = "cs"
[docs] 75 # @Support TypeScript style comments, IMPL_TS_1, impl, [FE_TS]
76 ts = "ts"
77 yaml = "yaml"
[docs] 78 # @Support Rust style comments, IMPL_RUST_1, impl, [FE_RUST]
79 rust = "rust"
[docs] 80 # @Support Go style comments, IMPL_GO_1, impl, [FE_GO]
81 go = "go"
[docs] 82 # @Support JSONC style comments, IMPL_JSONC_1, impl, [FE_JSONC]
83 jsonc = "jsonc"
[docs] 84 # @Support Bash style comments, IMPL_BASH_1, impl, [FE_BASH]
85 bash = "bash"
86
87
88def default_exclude_for_comment_type(comment_type: str) -> list[str]:
89 """Resolve the default ``exclude`` patterns for a given ``comment_type``.
90
91 Only the ``ts`` (TypeScript/JavaScript) family gets a non-empty default —
92 see ``TS_DEFAULT_EXCLUDE`` for why. Every other ``comment_type`` defaults
93 to ``[]``, i.e. no default exclusion at all, matching the behavior before
94 a default was ever introduced.
95 """
96 if comment_type == CommentType.ts:
97 return list(TS_DEFAULT_EXCLUDE)
98 return []
99
100
101class SourceDiscoverSectionConfigType(TypedDict, total=False):
102 """Define typing for loading configuration from TOML files"""
103
104 src_dir: Required[str]
105 exclude: list[str]
106 include: list[str]
107 gitignore: bool
108 follow_links: bool
109 comment_type: CommentType
110
111
112class SourceDiscoverConfigType(TypedDict, total=False):
113 """Define typing for its API configuration"""
114
115 src_dir: Required[Path]
116 exclude: list[str]
117 include: list[str]
118 gitignore: bool
119 follow_links: bool
120 comment_type: CommentType
121
122
123@dataclass
124class SourceDiscoverConfig:
125 @classmethod
126 def field_names(cls) -> set[str]:
127 return {item.name for item in fields(cls)}
128
129 src_dir: Path = field(
130 default_factory=lambda: Path("./"), metadata={"schema": {"type": "string"}}
131 )
132 """The root of the source directory."""
133
134 exclude: list[str] | None = field(
135 default=None,
136 metadata={"schema": {"type": "array", "items": {"type": "string"}}},
137 )
138 """The glob pattern to exclude files.
139
140 Leave unset (``None``) to get the ``comment_type``-derived default
141 resolved in ``__post_init__`` (see ``default_exclude_for_comment_type``):
142 ``TS_DEFAULT_EXCLUDE`` for ``comment_type == "ts"``, ``[]`` for every
143 other ``comment_type``. Set this explicitly — including to ``[]`` — to
144 replace that default outright; it is never merged with it.
145 """
146
147 include: list[str] = field(
148 default_factory=list,
149 metadata={"schema": {"type": "array", "items": {"type": "string"}}},
150 )
151 """The glob pattern to include files."""
152
153 gitignore: bool = field(default=True, metadata={"schema": {"type": "boolean"}})
154 """Whether to respect .gitignore to exclude files."""
155
156 follow_links: bool = field(default=False, metadata={"schema": {"type": "boolean"}})
157 """Whether to follow symbolic links during file discovery."""
158
159 comment_type: str = field(
160 default="cpp",
161 metadata={
162 "schema": {
163 "type": "string",
164 "enum": sorted(COMMENT_FILETYPE),
165 }
166 },
167 )
168 """The file types to discover."""
169
170 def __post_init__(self) -> None:
171 # ``None`` means "the user didn't set exclude" (a dataclass field
172 # default can't otherwise be told apart from an explicit ``[]``) —
173 # resolve it to the comment_type-derived default. An explicit value,
174 # including ``[]``, is left untouched.
175 if self.exclude is None:
176 self.exclude = default_exclude_for_comment_type(self.comment_type)
177
178 @classmethod
179 def get_schema(cls, name: str) -> dict[str, Any] | None:
180 _field = next(_field for _field in fields(cls) if _field.name is name)
181 if _field.metadata and "schema" in _field.metadata:
182 return cast(dict[str, Any], _field.metadata["schema"])
183 return None
184
185 def check_schema(self) -> list[str]:
186 errors = []
187 for _field_name in self.field_names():
188 schema = self.get_schema(_field_name)
189 value = getattr(self, _field_name)
190 if isinstance(value, Path): # adapt to json schema restriction
191 value = str(value)
192 try:
193 validate(
194 instance=value,
195 schema=schema, # ty: ignore[invalid-argument-type]
196 ) # validate has no type specified
197 except ValidationError as e:
198 errors.append(
199 f"Schema validation error in field '{_field_name}': {e.message}"
200 )
201 return errors
Back to top