docsentinel 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. docsentinel/__init__.py +20 -0
  2. docsentinel/baseline.py +56 -0
  3. docsentinel/cli.py +237 -0
  4. docsentinel/code_discovery.py +84 -0
  5. docsentinel/config.py +604 -0
  6. docsentinel/deep_support.py +59 -0
  7. docsentinel/detectors/__init__.py +41 -0
  8. docsentinel/detectors/_triples.py +169 -0
  9. docsentinel/detectors/anchors.py +196 -0
  10. docsentinel/detectors/assets.py +419 -0
  11. docsentinel/detectors/comments.py +90 -0
  12. docsentinel/detectors/contradictions.py +134 -0
  13. docsentinel/detectors/deprecated_refs.py +916 -0
  14. docsentinel/detectors/document_ids.py +773 -0
  15. docsentinel/detectors/fence_languages.py +214 -0
  16. docsentinel/detectors/fences.py +172 -0
  17. docsentinel/detectors/headings.py +237 -0
  18. docsentinel/detectors/links.py +202 -0
  19. docsentinel/detectors/loader.py +29 -0
  20. docsentinel/detectors/naming.py +547 -0
  21. docsentinel/detectors/navigation.py +652 -0
  22. docsentinel/detectors/path_boundaries.py +499 -0
  23. docsentinel/detectors/paths.py +180 -0
  24. docsentinel/detectors/references.py +381 -0
  25. docsentinel/detectors/sections.py +533 -0
  26. docsentinel/detectors/standard/__init__.py +10 -0
  27. docsentinel/detectors/standard/complexity.py +117 -0
  28. docsentinel/detectors/standard/corpus.py +334 -0
  29. docsentinel/detectors/standard/duplication.py +95 -0
  30. docsentinel/detectors/standard/low_information.py +142 -0
  31. docsentinel/detectors/standard/signatures.py +175 -0
  32. docsentinel/detectors/tables.py +424 -0
  33. docsentinel/discovery.py +43 -0
  34. docsentinel/engine.py +229 -0
  35. docsentinel/errors.py +16 -0
  36. docsentinel/markdown_blocks.py +1442 -0
  37. docsentinel/models.py +36 -0
  38. docsentinel/py.typed +0 -0
  39. docsentinel/pytest_plugin.py +14 -0
  40. docsentinel/reporting.py +188 -0
  41. docsentinel/rules.py +97 -0
  42. docsentinel-1.0.0.dist-info/METADATA +200 -0
  43. docsentinel-1.0.0.dist-info/RECORD +46 -0
  44. docsentinel-1.0.0.dist-info/WHEEL +4 -0
  45. docsentinel-1.0.0.dist-info/entry_points.txt +2 -0
  46. docsentinel-1.0.0.dist-info/licenses/LICENSE +21 -0
docsentinel/config.py ADDED
@@ -0,0 +1,604 @@
1
+ """Configuration for local, deterministic scans."""
2
+
3
+ import re
4
+ import tomllib
5
+ from dataclasses import dataclass
6
+ from pathlib import Path
7
+ from typing import Optional
8
+
9
+ _CONFIG_OPTIONS = {
10
+ "include",
11
+ "exclude",
12
+ "profile",
13
+ "select",
14
+ "ignore",
15
+ "baseline",
16
+ "max_grade_level",
17
+ "duplicate_similarity",
18
+ "min_information_score",
19
+ "docsig_paths",
20
+ # Standard-profile statistical size limits (DS201, DS202, DS203).
21
+ "min_document_words",
22
+ "min_paragraph_words",
23
+ "min_paragraph_chars",
24
+ "deep_confirm",
25
+ # Story 02 — anchor identity and collisions (DS104).
26
+ "anchor_collision_policy",
27
+ "anchor_renderer",
28
+ # Story 03 — heading hierarchy validation (DS105).
29
+ "heading_level_policy",
30
+ "first_heading_level",
31
+ "multiple_h1_policy",
32
+ "setext_heading_support",
33
+ # Story 04 — contentless section detection (DS106).
34
+ "empty_section_policy",
35
+ "placeholder_content_policy",
36
+ "image_content_counts",
37
+ "empty_section_min_text_chars",
38
+ # Story 05 — reference definition integrity (DS108).
39
+ "unused_reference_definitions",
40
+ "duplicate_reference_definitions",
41
+ "reference_label_normalization",
42
+ # Story 06 — fenced code boundary validation (DS109).
43
+ "fence_dialect",
44
+ "report_stray_closing_fence",
45
+ # Story 07 — code fence language policy (DS110).
46
+ "require_fence_languages",
47
+ "allow_unlabelled_empty_fences",
48
+ "allowed_fence_languages",
49
+ # Story 08 — pipe table structural validation (DS117).
50
+ "table_dialect",
51
+ "table_strict_cells",
52
+ "table_enable",
53
+ # Story 09 — configured navigation integrity (DS112).
54
+ "navigation_indexes",
55
+ "navigation_required",
56
+ "navigation_unique_targets",
57
+ "navigation_check_missing",
58
+ # Story 10 — missing local media assets (DS113).
59
+ "asset_extensions",
60
+ "check_html_asset_tags",
61
+ "check_markdown_images",
62
+ "check_srcset",
63
+ "missing_asset_policy",
64
+ # Story 11 — repository root path boundaries (DS116).
65
+ "root_escape_policy",
66
+ "decode_percent_paths",
67
+ "windows_path_policy",
68
+ # Story 12 — document identity uniqueness (DS114).
69
+ "document_id_field",
70
+ "document_id_scope",
71
+ "document_id_case_sensitive",
72
+ "document_id_required",
73
+ # Story 13 — deprecated reference and terminology (DS115).
74
+ "deprecated_references_file",
75
+ "deprecated_check_prose",
76
+ "deprecated_check_links",
77
+ "deprecated_case_sensitive",
78
+ # Story 14 — documentation path naming policy (DS118).
79
+ "documentation_naming",
80
+ "documentation_naming_allow",
81
+ "documentation_naming_directories",
82
+ "documentation_naming_prefix_patterns",
83
+ }
84
+ _SELECTOR_PATTERN = re.compile(r"DS\d*")
85
+
86
+ # A ``document_id_field`` (the frontmatter key DS114 reads) must be a simple,
87
+ # identifier-like key name, bounded in length so a pathological config value can
88
+ # never drive an unbounded key comparison in the detector.
89
+ _DOCUMENT_ID_FIELD_PATTERN = re.compile(r"[A-Za-z_][A-Za-z0-9_-]{0,127}")
90
+
91
+ # Enum-valued options and their accepted vocabularies. Where a milestone
92
+ # specification fixes a single value (for example ``anchor_renderer`` or the
93
+ # dialect options), only that value is accepted until a story widens it.
94
+ _ENUM_OPTIONS: dict[str, frozenset[str]] = {
95
+ "anchor_collision_policy": frozenset({"off", "explicit"}),
96
+ "anchor_renderer": frozenset({"github"}),
97
+ "heading_level_policy": frozenset({"off", "no-skips"}),
98
+ "multiple_h1_policy": frozenset({"allow", "warn"}),
99
+ "empty_section_policy": frozenset({"off", "leaf", "all"}),
100
+ "placeholder_content_policy": frozenset({"ignore", "count"}),
101
+ "duplicate_reference_definitions": frozenset({"off", "warn", "error"}),
102
+ "reference_label_normalization": frozenset({"commonmark"}),
103
+ "fence_dialect": frozenset({"gfm-subset"}),
104
+ "table_dialect": frozenset({"gfm-subset"}),
105
+ "missing_asset_policy": frozenset({"off", "warn", "error"}),
106
+ "root_escape_policy": frozenset({"off", "warn", "error"}),
107
+ "windows_path_policy": frozenset({"off", "portable"}),
108
+ "document_id_scope": frozenset({"corpus", "directory"}),
109
+ "documentation_naming": frozenset({"off", "kebab", "snake"}),
110
+ }
111
+
112
+ # Boolean-valued options, paired with the ``Config`` attribute defaults.
113
+ _BOOL_OPTIONS = (
114
+ "setext_heading_support",
115
+ "image_content_counts",
116
+ "unused_reference_definitions",
117
+ "report_stray_closing_fence",
118
+ "require_fence_languages",
119
+ "allow_unlabelled_empty_fences",
120
+ "table_strict_cells",
121
+ "table_enable",
122
+ "navigation_unique_targets",
123
+ "navigation_check_missing",
124
+ "check_html_asset_tags",
125
+ "check_markdown_images",
126
+ "check_srcset",
127
+ "decode_percent_paths",
128
+ "document_id_case_sensitive",
129
+ "document_id_required",
130
+ "deprecated_check_prose",
131
+ "deprecated_check_links",
132
+ "deprecated_case_sensitive",
133
+ "documentation_naming_directories",
134
+ )
135
+
136
+ # Options holding a list of nonempty, non-path strings.
137
+ _STR_LIST_OPTIONS = (
138
+ "allowed_fence_languages",
139
+ "asset_extensions",
140
+ "documentation_naming_allow",
141
+ "documentation_naming_prefix_patterns",
142
+ )
143
+
144
+ # Options holding a list of nonempty relative paths that must stay under root.
145
+ _ROOT_PATH_LIST_OPTIONS = (
146
+ "navigation_indexes",
147
+ "navigation_required",
148
+ )
149
+
150
+
151
+ class ConfigError(ValueError):
152
+ """An invalid or unreadable DocSentinel configuration."""
153
+
154
+
155
+ @dataclass(frozen=True)
156
+ class Config:
157
+ """Immutable settings for a DocSentinel scan.
158
+
159
+ .. note::
160
+
161
+ :func:`load_config` validates every option (enum vocabularies, ranges,
162
+ path containment) before constructing this dataclass. Constructing
163
+ ``Config(...)`` directly, as a library caller may, bypasses that
164
+ load-time validation: the field values are trusted as given, so callers
165
+ that build a ``Config`` by hand are responsible for passing valid values.
166
+
167
+ :ivar include: Glob patterns of Markdown documents to inventory.
168
+ :ivar exclude: Glob/directory patterns removed from the inventory.
169
+ :ivar profile: Active profile, one of ``fast``, ``standard``, ``deep``.
170
+ :ivar select: Rule codes or prefixes to activate; empty selects all.
171
+ :ivar ignore: Rule codes or prefixes to suppress; wins over ``select``.
172
+ :ivar baseline: Path to a baseline JSON file, or ``None``.
173
+ :ivar max_grade_level: Maximum acceptable readability grade for ``DS201``.
174
+ :ivar duplicate_similarity: Cosine-similarity threshold for ``DS202``.
175
+ :ivar min_information_score: Minimum information score for ``DS203``.
176
+ :ivar docsig_paths: Python source roots scanned by ``DS204``.
177
+ :ivar min_document_words: Minimum prose-word count before ``DS201`` scores a
178
+ document. Documents with fewer prose words (after Markdown stripping) are
179
+ skipped, so short notes are never penalised for readability. Integer
180
+ ``>= 1``; the default ``50`` reproduces the historical built-in floor.
181
+ :ivar min_paragraph_words: Minimum prose-word count for a paragraph to enter
182
+ the ``DS202``/``DS203`` corpus. Paragraphs with fewer words are not
183
+ analysed. Integer ``>= 1``; the default ``5`` reproduces the historical
184
+ built-in floor.
185
+ :ivar min_paragraph_chars: Minimum visible-character count for a paragraph to
186
+ enter the ``DS202``/``DS203`` corpus. Paragraphs shorter than this are not
187
+ analysed. A paragraph must clear **both** this and ``min_paragraph_words``.
188
+ Integer ``>= 0``; the default ``30`` reproduces the historical built-in
189
+ floor.
190
+ :ivar deep_confirm: Whether the deep profile is explicitly confirmed.
191
+ :ivar anchor_collision_policy: ``DS104`` collision policy.
192
+ :ivar anchor_renderer: Renderer whose slugging ``DS104`` emulates.
193
+ :ivar heading_level_policy: ``DS105`` heading-level policy.
194
+ :ivar first_heading_level: Expected first heading level (1..6) for ``DS105``.
195
+ :ivar multiple_h1_policy: Policy for repeated H1 headings.
196
+ :ivar setext_heading_support: Whether setext headings participate in ``DS105``.
197
+ :ivar empty_section_policy: ``DS106`` contentless-section policy.
198
+ :ivar placeholder_content_policy: Whether HTML comments count as ``DS106`` content.
199
+ :ivar image_content_counts: Whether an image counts as section content.
200
+ :ivar empty_section_min_text_chars: ``DS106`` visible-text threshold. A section is
201
+ flagged when its visible non-whitespace character count is ``<=`` this value,
202
+ so a section must carry **strictly more** than ``empty_section_min_text_chars``
203
+ visible characters to count as non-empty; the default ``0`` means any visible
204
+ text at all is enough. Positive values are deferred to the ``DS203`` quality
205
+ policy, so a caller who sets ``5`` should expect sections with exactly five
206
+ visible characters to be flagged.
207
+ :ivar unused_reference_definitions: Whether unused definitions warn (``DS108``).
208
+ :ivar duplicate_reference_definitions: ``DS108`` duplicate-definition policy.
209
+ :ivar reference_label_normalization: Reference-label normalization dialect.
210
+ :ivar fence_dialect: Fenced-code dialect recognized by ``DS109``.
211
+ :ivar report_stray_closing_fence: Whether unattached closers are reported.
212
+ :ivar require_fence_languages: Whether ``DS110`` requires a fence language.
213
+ :ivar allow_unlabelled_empty_fences: Whether empty fences may be unlabelled.
214
+ :ivar allowed_fence_languages: Allowlist of fence languages; empty allows all.
215
+ :ivar table_dialect: Pipe-table dialect recognized by ``DS117``.
216
+ :ivar table_strict_cells: Whether ``DS117`` enforces consistent cell counts.
217
+ :ivar table_enable: Whether the ``DS117`` table check runs.
218
+ :ivar navigation_indexes: Navigation index documents inspected by ``DS112``.
219
+ :ivar navigation_required: Documents required to appear in navigation.
220
+ :ivar navigation_unique_targets: Whether navigation targets must be unique.
221
+ :ivar navigation_check_missing: Whether missing navigation targets warn.
222
+ :ivar asset_extensions: Media extensions ``DS113`` treats as local assets.
223
+ :ivar check_html_asset_tags: Whether ``DS113`` inspects HTML media tags.
224
+ :ivar check_markdown_images: Whether ``DS113`` inspects Markdown images.
225
+ :ivar check_srcset: Whether ``DS113`` inspects ``srcset`` candidates.
226
+ :ivar missing_asset_policy: ``DS113`` severity policy for a missing or
227
+ non-regular local asset (``"off"``/``"warn"``/``"error"``), mirroring
228
+ ``root_escape_policy``: ``"off"`` suppresses the rule with no filesystem
229
+ access, ``"warn"`` downgrades each finding to ``warning`` severity, and
230
+ ``"error"`` (the default, blocking) keeps the rule's ``error`` severity.
231
+ The :class:`~docsentinel.rules.Rule` metadata severity stays ``error``
232
+ regardless of this policy.
233
+ :ivar root_escape_policy: ``DS116`` root-escape policy.
234
+ :ivar decode_percent_paths: Whether percent-encoded paths are decoded once.
235
+ :ivar windows_path_policy: ``DS116`` Windows path portability policy.
236
+ :ivar document_id_field: Front-matter key carrying the document identity.
237
+ :ivar document_id_scope: Scope within which identities must be unique.
238
+ :ivar document_id_case_sensitive: Whether identity comparison is case-sensitive.
239
+ :ivar document_id_required: Whether every document must declare an identity.
240
+ :ivar deprecated_references_file: Mapping file of deprecated names, or empty.
241
+ :ivar deprecated_check_prose: Whether ``DS115`` scans prose for deprecated names.
242
+ :ivar deprecated_check_links: Whether ``DS115`` scans link targets.
243
+ :ivar deprecated_case_sensitive: Whether deprecated matching is case-sensitive.
244
+ :ivar documentation_naming: ``DS118`` naming policy (``off``/``kebab``/``snake``).
245
+ :ivar documentation_naming_allow: Exempt file names for ``DS118``.
246
+ :ivar documentation_naming_directories: Whether ``DS118`` checks directories.
247
+ :ivar documentation_naming_prefix_patterns: Validated prefix exceptions.
248
+ """
249
+
250
+ include: tuple[str, ...] = ("*.md", "**/*.md")
251
+ exclude: tuple[str, ...] = (".git", ".venv", "node_modules")
252
+ profile: str = "fast"
253
+ select: tuple[str, ...] = ()
254
+ ignore: tuple[str, ...] = ()
255
+ baseline: Optional[str] = None
256
+ max_grade_level: float = 14.0
257
+ duplicate_similarity: float = 0.85
258
+ min_information_score: float = 0.15
259
+ docsig_paths: tuple[str, ...] = ("src",)
260
+ min_document_words: int = 50
261
+ min_paragraph_words: int = 5
262
+ min_paragraph_chars: int = 30
263
+ deep_confirm: bool = False
264
+ anchor_collision_policy: str = "explicit"
265
+ anchor_renderer: str = "github"
266
+ heading_level_policy: str = "no-skips"
267
+ first_heading_level: int = 1
268
+ multiple_h1_policy: str = "allow"
269
+ setext_heading_support: bool = True
270
+ empty_section_policy: str = "leaf"
271
+ placeholder_content_policy: str = "ignore"
272
+ image_content_counts: bool = True
273
+ empty_section_min_text_chars: int = 0
274
+ unused_reference_definitions: bool = False
275
+ duplicate_reference_definitions: str = "warn"
276
+ reference_label_normalization: str = "commonmark"
277
+ fence_dialect: str = "gfm-subset"
278
+ report_stray_closing_fence: bool = False
279
+ require_fence_languages: bool = False
280
+ allow_unlabelled_empty_fences: bool = True
281
+ allowed_fence_languages: tuple[str, ...] = ()
282
+ table_dialect: str = "gfm-subset"
283
+ table_strict_cells: bool = True
284
+ table_enable: bool = True
285
+ navigation_indexes: tuple[str, ...] = ()
286
+ navigation_required: tuple[str, ...] = ()
287
+ navigation_unique_targets: bool = True
288
+ navigation_check_missing: bool = True
289
+ asset_extensions: tuple[str, ...] = ("png", "jpg", "jpeg", "svg", "webp", "gif", "pdf")
290
+ check_html_asset_tags: bool = True
291
+ check_markdown_images: bool = True
292
+ check_srcset: bool = True
293
+ missing_asset_policy: str = "error"
294
+ root_escape_policy: str = "error"
295
+ decode_percent_paths: bool = True
296
+ windows_path_policy: str = "portable"
297
+ document_id_field: str = "id"
298
+ document_id_scope: str = "corpus"
299
+ document_id_case_sensitive: bool = True
300
+ document_id_required: bool = False
301
+ deprecated_references_file: str = ""
302
+ deprecated_check_prose: bool = True
303
+ deprecated_check_links: bool = True
304
+ deprecated_case_sensitive: bool = True
305
+ documentation_naming: str = "off"
306
+ documentation_naming_allow: tuple[str, ...] = ("README.md", "index.md")
307
+ documentation_naming_directories: bool = True
308
+ documentation_naming_prefix_patterns: tuple[str, ...] = ()
309
+
310
+
311
+ def _require_bool(name: str, value: object) -> bool:
312
+ """Return ``value`` when it is a real boolean, else raise ``ConfigError``.
313
+
314
+ :param name: Option name used in the error message.
315
+ :param value: Candidate value from the TOML table.
316
+ :returns: The validated boolean.
317
+ """
318
+ if not isinstance(value, bool):
319
+ raise ConfigError(f"{name} must be true or false")
320
+ return value
321
+
322
+
323
+ def _require_bounded_int(name: str, value: object, minimum: int) -> int:
324
+ """Return ``value`` when it is an ``int`` at or above ``minimum``, else raise ``ConfigError``.
325
+
326
+ Real booleans and floats (even integral ones such as ``5.0``) are rejected,
327
+ matching the strictness of the other numeric options.
328
+
329
+ :param name: Option name used in the error message.
330
+ :param value: Candidate value from the TOML table.
331
+ :param minimum: The smallest accepted integer value.
332
+ :returns: The validated integer.
333
+ """
334
+ if not isinstance(value, int) or isinstance(value, bool) or value < minimum:
335
+ requirement = "a non-negative integer" if minimum == 0 else f"an integer >= {minimum}"
336
+ raise ConfigError(f"{name} must be {requirement}")
337
+ return value
338
+
339
+
340
+ def _require_enum(name: str, value: object, allowed: frozenset[str]) -> str:
341
+ """Return ``value`` when it is one of ``allowed``, else raise ``ConfigError``.
342
+
343
+ :param name: Option name used in the error message.
344
+ :param value: Candidate value from the TOML table.
345
+ :param allowed: The accepted vocabulary for this option.
346
+ :returns: The validated string.
347
+ """
348
+ if not isinstance(value, str) or value not in allowed:
349
+ joined = ", ".join(sorted(allowed))
350
+ raise ConfigError(f"{name} must be one of: {joined}")
351
+ return value
352
+
353
+
354
+ def _require_str_list(name: str, value: object) -> tuple[str, ...]:
355
+ """Return a tuple of nonempty strings, else raise ``ConfigError``.
356
+
357
+ :param name: Option name used in the error message.
358
+ :param value: Candidate value from the TOML table.
359
+ :returns: The validated strings as a tuple.
360
+ """
361
+ if not isinstance(value, list) or not all(isinstance(item, str) and item for item in value):
362
+ raise ConfigError(f"{name} must be a list of nonempty strings")
363
+ return tuple(value)
364
+
365
+
366
+ def _require_fence_language_list(name: str, value: object) -> tuple[str, ...]:
367
+ """Return a tuple of single-token fence languages, else raise ``ConfigError``.
368
+
369
+ A fence language is the first whitespace-delimited token of a fence info
370
+ string, so an allowlist entry that itself contains whitespace (``"python
371
+ bash"``, a leading space, or an embedded tab) could never match any single
372
+ fence language and almost certainly signals a malformed config. Such entries
373
+ are rejected; ordinary tokens with punctuation such as ``"c++"`` or
374
+ ``"objective-c"`` remain valid.
375
+
376
+ :param name: Option name used in the error message.
377
+ :param value: Candidate value from the TOML table.
378
+ :returns: The validated single-token languages as a tuple.
379
+ """
380
+ languages = _require_str_list(name, value)
381
+ for language in languages:
382
+ if any(character.isspace() for character in language):
383
+ raise ConfigError(f"{name} entries must be single tokens without whitespace: {language!r}")
384
+ return languages
385
+
386
+
387
+ def _is_within_root(path_part: str) -> bool:
388
+ """Return whether a relative path stays lexically within the scan root.
389
+
390
+ The check is lexical and performs no filesystem access: absolute paths,
391
+ Windows drive/UNC paths, backslash separators, and ``..`` escapes above the
392
+ root are rejected.
393
+
394
+ :param path_part: A candidate ``/``-separated relative path.
395
+ :returns: ``True`` when the path is root-relative and does not escape.
396
+ """
397
+ if path_part.startswith("/") or "\\" in path_part:
398
+ return False
399
+ if re.match(r"^[A-Za-z]:", path_part):
400
+ return False
401
+ depth = 0
402
+ for part in path_part.split("/"):
403
+ if part in ("", "."):
404
+ continue
405
+ if part == "..":
406
+ if depth == 0:
407
+ return False
408
+ depth -= 1
409
+ else:
410
+ depth += 1
411
+ return True
412
+
413
+
414
+ def _require_root_path_list(name: str, value: object) -> tuple[str, ...]:
415
+ """Return a tuple of root-relative paths, else raise ``ConfigError``.
416
+
417
+ :param name: Option name used in the error message.
418
+ :param value: Candidate value from the TOML table.
419
+ :returns: The validated paths as a tuple.
420
+ """
421
+ if not isinstance(value, list) or not all(isinstance(item, str) and item for item in value):
422
+ raise ConfigError(f"{name} must be a list of nonempty paths under the scan root")
423
+ for item in value:
424
+ if not _is_within_root(item):
425
+ raise ConfigError(f"{name} entries must stay within the scan root: {item}")
426
+ return tuple(value)
427
+
428
+
429
+ def _load_toml_table(source: Path, *, wrapped: bool) -> dict[str, object]:
430
+ """Load and validate options from a standalone or pyproject TOML table.
431
+
432
+ :param source: The TOML file to read.
433
+ :param wrapped: Whether to unwrap a ``[tool.doc_sentinel]`` table.
434
+ :returns: The raw options mapping.
435
+ """
436
+ try:
437
+ with source.open("rb") as stream:
438
+ data = tomllib.load(stream)
439
+ except (OSError, UnicodeDecodeError, tomllib.TOMLDecodeError) as exc:
440
+ raise ConfigError(f"Cannot read {source}: {exc}") from exc
441
+
442
+ options: object = data
443
+ if wrapped:
444
+ tool = data.get("tool")
445
+ if not isinstance(tool, dict) or "doc_sentinel" not in tool:
446
+ return {}
447
+ options = tool["doc_sentinel"]
448
+ if not isinstance(options, dict):
449
+ raise ConfigError("Unknown config options: tool.doc_sentinel must be a table")
450
+
451
+ unknown = set(options) - _CONFIG_OPTIONS
452
+ if unknown:
453
+ raise ConfigError(f"Unknown config options: {', '.join(sorted(unknown))}")
454
+ return options
455
+
456
+
457
+ def load_config(root: Path, path: Optional[Path] = None) -> Config:
458
+ """Load an explicit config or discover root-level DocSentinel settings.
459
+
460
+ A standalone ``doc_sentinel.toml`` wins over ``[tool.doc_sentinel]`` in
461
+ ``pyproject.toml``; when neither exists, defaults are returned. An explicit
462
+ ``path`` bypasses discovery. A :class:`Config` injected directly by a
463
+ library caller is used verbatim by the engine and never consults files.
464
+
465
+ :param root: The scan root directory used for discovery.
466
+ :param path: An explicit config file, or ``None`` to discover one.
467
+ :returns: The validated :class:`Config`.
468
+ """
469
+ if path is not None:
470
+ source = path
471
+ wrapped = source.name == "pyproject.toml"
472
+ else:
473
+ standalone = root / "doc_sentinel.toml"
474
+ pyproject = root / "pyproject.toml"
475
+ if standalone.exists():
476
+ source = standalone
477
+ wrapped = False
478
+ elif pyproject.exists():
479
+ source = pyproject
480
+ wrapped = True
481
+ else:
482
+ return Config()
483
+
484
+ options = _load_toml_table(source, wrapped=wrapped)
485
+ defaults = Config()
486
+ include = options.get("include", list(defaults.include))
487
+ exclude = options.get("exclude", list(defaults.exclude))
488
+ profile = options.get("profile", defaults.profile)
489
+ select = options.get("select", list(defaults.select))
490
+ ignore = options.get("ignore", list(defaults.ignore))
491
+ baseline = options.get("baseline", defaults.baseline)
492
+ max_grade_level = options.get("max_grade_level", defaults.max_grade_level)
493
+ duplicate_similarity = options.get("duplicate_similarity", defaults.duplicate_similarity)
494
+ min_information_score = options.get("min_information_score", defaults.min_information_score)
495
+ docsig_paths = options.get("docsig_paths", list(defaults.docsig_paths))
496
+ deep_confirm = options.get("deep_confirm", defaults.deep_confirm)
497
+ for name, value in (("include", include), ("exclude", exclude)):
498
+ if not isinstance(value, list) or not all(isinstance(item, str) and item for item in value):
499
+ raise ConfigError(f"{name} must be a list of nonempty patterns")
500
+ if not isinstance(docsig_paths, list) or not all(isinstance(item, str) and item for item in docsig_paths):
501
+ raise ConfigError("docsig_paths must be a list of nonempty paths")
502
+ for name, value in (("select", select), ("ignore", ignore)):
503
+ if not isinstance(value, list) or not all(
504
+ isinstance(item, str) and _SELECTOR_PATTERN.fullmatch(item) for item in value
505
+ ):
506
+ raise ConfigError(f"{name} must be a list of DS rule codes or prefixes")
507
+ if not isinstance(profile, str) or profile not in ("fast", "standard", "deep"):
508
+ raise ConfigError("profile must be fast, standard, or deep")
509
+ if baseline is not None and (not isinstance(baseline, str) or not baseline):
510
+ raise ConfigError("baseline must be a nonempty string")
511
+ if not isinstance(max_grade_level, (int, float)) or isinstance(max_grade_level, bool) or max_grade_level <= 0:
512
+ raise ConfigError("max_grade_level must be a positive number")
513
+ if (
514
+ not isinstance(duplicate_similarity, (int, float))
515
+ or isinstance(duplicate_similarity, bool)
516
+ or not (0.0 <= float(duplicate_similarity) <= 1.0)
517
+ ):
518
+ raise ConfigError("duplicate_similarity must be a number between 0 and 1")
519
+ if (
520
+ not isinstance(min_information_score, (int, float))
521
+ or isinstance(min_information_score, bool)
522
+ or not (0.0 <= float(min_information_score) <= 1.0)
523
+ ):
524
+ raise ConfigError("min_information_score must be a number between 0 and 1")
525
+ if not isinstance(deep_confirm, bool):
526
+ raise ConfigError("deep_confirm must be true or false")
527
+
528
+ extra = _load_extra_options(options, defaults)
529
+
530
+ return Config(
531
+ include=tuple(include),
532
+ exclude=tuple(exclude),
533
+ profile=profile,
534
+ select=tuple(select),
535
+ ignore=tuple(ignore),
536
+ baseline=baseline,
537
+ max_grade_level=float(max_grade_level),
538
+ duplicate_similarity=float(duplicate_similarity),
539
+ min_information_score=float(min_information_score),
540
+ docsig_paths=tuple(docsig_paths),
541
+ deep_confirm=deep_confirm,
542
+ **extra,
543
+ )
544
+
545
+
546
+ def _load_extra_options(options: dict[str, object], defaults: Config) -> dict[str, object]:
547
+ """Validate the Story 02–14 typed options into ``Config`` keyword arguments.
548
+
549
+ :param options: The raw options mapping from the TOML table.
550
+ :param defaults: A default :class:`Config` used to source field defaults.
551
+ :returns: A mapping of validated keyword arguments for :class:`Config`.
552
+ """
553
+ extra: dict[str, object] = {}
554
+ for name in _BOOL_OPTIONS:
555
+ extra[name] = _require_bool(name, options.get(name, getattr(defaults, name)))
556
+ for name, allowed in _ENUM_OPTIONS.items():
557
+ extra[name] = _require_enum(name, options.get(name, getattr(defaults, name)), allowed)
558
+ for name in _STR_LIST_OPTIONS:
559
+ if name in options:
560
+ validate = _require_fence_language_list if name == "allowed_fence_languages" else _require_str_list
561
+ extra[name] = validate(name, options[name])
562
+ else:
563
+ extra[name] = getattr(defaults, name)
564
+ for name in _ROOT_PATH_LIST_OPTIONS:
565
+ if name in options:
566
+ extra[name] = _require_root_path_list(name, options[name])
567
+ else:
568
+ extra[name] = getattr(defaults, name)
569
+
570
+ first_heading_level = options.get("first_heading_level", defaults.first_heading_level)
571
+ if (
572
+ not isinstance(first_heading_level, int)
573
+ or isinstance(first_heading_level, bool)
574
+ or not (1 <= first_heading_level <= 6)
575
+ ):
576
+ raise ConfigError("first_heading_level must be an integer between 1 and 6")
577
+ extra["first_heading_level"] = first_heading_level
578
+
579
+ min_text_chars = options.get("empty_section_min_text_chars", defaults.empty_section_min_text_chars)
580
+ if not isinstance(min_text_chars, int) or isinstance(min_text_chars, bool) or min_text_chars < 0:
581
+ raise ConfigError("empty_section_min_text_chars must be a non-negative integer")
582
+ extra["empty_section_min_text_chars"] = min_text_chars
583
+
584
+ for name, minimum in (("min_document_words", 1), ("min_paragraph_words", 1), ("min_paragraph_chars", 0)):
585
+ extra[name] = _require_bounded_int(name, options.get(name, getattr(defaults, name)), minimum)
586
+
587
+ document_id_field = options.get("document_id_field", defaults.document_id_field)
588
+ if not isinstance(document_id_field, str) or not document_id_field:
589
+ raise ConfigError("document_id_field must be a nonempty string")
590
+ if not _DOCUMENT_ID_FIELD_PATTERN.fullmatch(document_id_field):
591
+ raise ConfigError(
592
+ "document_id_field must be a simple key name: a letter or underscore "
593
+ "followed by letters, digits, underscores or hyphens, at most 128 characters"
594
+ )
595
+ extra["document_id_field"] = document_id_field
596
+
597
+ deprecated_file = options.get("deprecated_references_file", defaults.deprecated_references_file)
598
+ if not isinstance(deprecated_file, str):
599
+ raise ConfigError("deprecated_references_file must be a path string under the scan root")
600
+ if deprecated_file and not _is_within_root(deprecated_file):
601
+ raise ConfigError("deprecated_references_file must stay within the scan root")
602
+ extra["deprecated_references_file"] = deprecated_file
603
+
604
+ return extra
@@ -0,0 +1,59 @@
1
+ """Lazy loaders and readiness probes for deep profile dependencies and models.
2
+
3
+ TODO(milestone-0002-dedup): consider unifying optional-dependency probes across profiles.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import importlib
9
+ from typing import TYPE_CHECKING
10
+
11
+ if TYPE_CHECKING:
12
+ import spacy.language
13
+
14
+ DEEP_EXTRA_HINT: str = (
15
+ "install the deep extra (pip install docsentinel[deep]) and the model (python -m spacy download en_core_web_sm)"
16
+ )
17
+ MODEL_NAME: str = "en_core_web_sm"
18
+
19
+
20
+ def libraries_available() -> bool:
21
+ """Return True if both spacy and textacy can be imported without error."""
22
+ try:
23
+ importlib.import_module("spacy")
24
+ importlib.import_module("textacy")
25
+ except ImportError:
26
+ status = False
27
+ return status
28
+ return True
29
+
30
+
31
+ def model_available() -> bool:
32
+ """Return True if the pinned spaCy model package is installed, without fully loading it."""
33
+ try:
34
+ spacy_util = importlib.import_module("spacy.util")
35
+ except ImportError:
36
+ status = False
37
+ return status
38
+ return bool(spacy_util.is_package(MODEL_NAME))
39
+
40
+
41
+ def deep_ready() -> bool:
42
+ """Return True if both libraries and the pinned model are available."""
43
+ return libraries_available() and model_available()
44
+
45
+
46
+ def load_pipeline() -> spacy.language.Language:
47
+ """Load and return the pinned spaCy model pipeline.
48
+
49
+ Raises RuntimeError with install guidance if libraries or model are missing.
50
+ """
51
+ try:
52
+ spacy = importlib.import_module("spacy")
53
+ except ImportError as exc:
54
+ raise RuntimeError(f"deep profile needs the model '{MODEL_NAME}': {DEEP_EXTRA_HINT}") from exc
55
+
56
+ try:
57
+ return spacy.load(MODEL_NAME)
58
+ except (OSError, ImportError) as exc:
59
+ raise RuntimeError(f"deep profile needs the model '{MODEL_NAME}': {DEEP_EXTRA_HINT}") from exc