docu · Nivel 1

Arquitectura 15

QuéDetalleEvidencia
docu1 archivos · python
Ver prueba
src/docu/__init__.py#L1-L10
1"""docu — agente autonomo de documentacion tecnica.
2
3El paquete `core` no importa nada de `adapters`: esa es la garantia de agnosticismo
4(ver Plan.md §2, "test de agnosticismo").
5"""
6
7from docu.core.contracts import SCHEMA_VERSION
8
9__version__ = "0.1.0"
10__all__ = ["SCHEMA_VERSION", "__version__"]
docu.adapters1 archivos · python
Ver prueba
src/docu/adapters/__init__.py#L1-L1
1"""Implementaciones de los puertos del nucleo. Nada de aqui lo importa `docu.core`."""
docu.adapters.embedders2 archivos · python
Ver prueba
src/docu/adapters/embedders/__init__.py#L1-L1
1"""Adaptadores de embeddings: locales (ONNX) o por API, detras del puerto `Embedder`."""
docu.adapters.langs6 archivos · python
Ver prueba
src/docu/adapters/langs/__init__.py#L1-L1
1"""Adaptadores de lenguaje: uno por lenguaje, detras del puerto `LangAdapter`."""
docu.adapters.sources3 archivos · python
Ver prueba
src/docu/adapters/sources/__init__.py#L1-L5
1"""Adaptadores de fuentes no-código (PDF, y en el futuro web e IaC)."""
2
3from docu.adapters.sources import pdf
4
5__all__ = ["pdf"]
docu.audit2 archivos · python
Ver prueba
src/docu/audit/__init__.py#L1-L5
1"""Auditoria: comprobaciones deterministas sobre la documentacion generada."""
2
3from docu.audit import verify
4
5__all__ = ["verify"]
docu.conformance3 archivos · python
Ver prueba
src/docu/conformance/__init__.py#L1-L5
1"""Conformidad arquitectonica: modelo prescriptivo frente al codigo real."""
2
3from docu.conformance import drift, model
4
5__all__ = ["drift", "model"]
docu.core6 archivos · python
Ver prueba
src/docu/core/__init__.py#L1-L5
1"""Contratos, puertos y politica del nucleo. Sin dependencias externas."""
2
3from docu.core import contracts, policy, ports
4
5__all__ = ["contracts", "policy", "ports"]
docu.delivery7 archivos · python
Ver prueba
src/docu/delivery/__init__.py#L1-L5
1"""Superficies de entrega: CLI, CI y servidor MCP (solo lectura)."""
2
3from docu.delivery.exit_codes import ExitCode
4
5__all__ = ["ExitCode"]
docu.generate9 archivos · python
Ver prueba
src/docu/generate/__init__.py#L1-L5
1"""Generacion: hechos verificables, renderizado por nivel y compuerta de calidad."""
2
3from docu.generate import facts, markdown, pipeline
4
5__all__ = ["facts", "markdown", "pipeline"]
docu.index8 archivos · python
Ver prueba
src/docu/index/__init__.py#L1-L5
1"""Indice: segmentación, metadatos, paquetes, grafo de dependencias y frescura."""
2
3from docu.index import chunker, freshness, packages
4
5__all__ = ["chunker", "freshness", "packages"]
docu.learn5 archivos · python
Ver prueba
src/docu/learn/__init__.py#L1-L5
1"""Aprendizaje entre instalaciones: ledger, patrones, promocion validada y federacion."""
2
3from docu.learn import federation, ledger, patterns, promotion
4
5__all__ = ["federation", "ledger", "patterns", "promotion"]
docu.publish2 archivos · python
Ver prueba
src/docu/publish/__init__.py#L1-L5
1"""Publicación: la documentación como web con profundidad bajo demanda."""
2
3from docu.publish.site import LEVEL_SECTIONS, SECTIONS, Page, build_site, escape, snippet
4
5__all__ = ["LEVEL_SECTIONS", "SECTIONS", "Page", "build_site", "escape", "snippet"]
docu.retrieve4 archivos · python
Ver prueba
src/docu/retrieve/__init__.py#L1-L5
1"""Recuperacion: expansion de consulta, busqueda sobre documentos y sobre codigo."""
2
3from docu.retrieve import glossary, hybrid, search
4
5__all__ = ["glossary", "hybrid", "search"]
eval2 archivos · python
Ver prueba
eval/__init__.py#L1-L1
1"""Arnés de evaluación: golden sets y línea base de recuperación (F0)."""

Dependencias 17

QuéDetalleEvidencia
requires-python>=3.11
Ver prueba
pyproject.toml#L10-L10
10requires-python = ">=3.11"
typer>=0.12
Ver prueba
pyproject.toml#L18-L18
18cli = ["typer>=0.12"]            # alternativa ergonomica a argparse (el CLI actual es stdlib)
PyYAML>=6.0
Ver prueba
pyproject.toml#L19-L19
19profile = ["PyYAML>=6.0"]        # lectura de docu.profile.yaml
tree-sitter>=0.23
Ver prueba
pyproject.toml#L20-L20
20langs = ["tree-sitter>=0.23", "tree-sitter-python", "tree-sitter-typescript", "tree-sitter-java"]
tree-sitter-python(sin versión fija)
Ver prueba
pyproject.toml#L20-L20
20langs = ["tree-sitter>=0.23", "tree-sitter-python", "tree-sitter-typescript", "tree-sitter-java"]
tree-sitter-typescript(sin versión fija)
Ver prueba
pyproject.toml#L20-L20
20langs = ["tree-sitter>=0.23", "tree-sitter-python", "tree-sitter-typescript", "tree-sitter-java"]
tree-sitter-java(sin versión fija)
Ver prueba
pyproject.toml#L20-L20
20langs = ["tree-sitter>=0.23", "tree-sitter-python", "tree-sitter-typescript", "tree-sitter-java"]
chromadb>=0.5
Ver prueba
pyproject.toml#L21-L21
21index = ["chromadb>=0.5", "onnxruntime>=1.18", "tokenizers>=0.19"]
onnxruntime>=1.18
Ver prueba
pyproject.toml#L21-L21
21index = ["chromadb>=0.5", "onnxruntime>=1.18", "tokenizers>=0.19"]
tokenizers>=0.19
Ver prueba
pyproject.toml#L21-L21
21index = ["chromadb>=0.5", "onnxruntime>=1.18", "tokenizers>=0.19"]
pdfplumber>=0.11
Ver prueba
pyproject.toml#L22-L22
22docs = ["pdfplumber>=0.11", "markdown-it-py>=3.0"]
markdown-it-py>=3.0
Ver prueba
pyproject.toml#L22-L22
22docs = ["pdfplumber>=0.11", "markdown-it-py>=3.0"]
jinja2>=3.1
Ver prueba
pyproject.toml#L23-L23
23generate = ["jinja2>=3.1"]
ragas>=0.1
Ver prueba
pyproject.toml#L24-L24
24eval = ["ragas>=0.1"]
pytest>=8.0
Ver prueba
pyproject.toml#L25-L25
25dev = ["pytest>=8.0", "ruff>=0.6", "mypy>=1.10"]
ruff>=0.6
Ver prueba
pyproject.toml#L25-L25
25dev = ["pytest>=8.0", "ruff>=0.6", "mypy>=1.10"]
mypy>=1.10
Ver prueba
pyproject.toml#L25-L25
25dev = ["pytest>=8.0", "ruff>=0.6", "mypy>=1.10"]

API HTTP

Sin evidencia disponible: esta sección no se documenta y no se rellena con texto plausible.

Configuración 24

QuéDetalleEvidencia
schema_version1.0
Ver prueba
docu.profile.yaml#L3-L3
3schema_version: "1.0"
projectdocu
Ver prueba
docu.profile.yaml#L5-L5
5project: docu
modeapply
Ver prueba
docu.profile.yaml#L6-L6
6mode: apply                 # propose | apply | publish
sources.git.refHEAD
Ver prueba
docu.profile.yaml#L10-L10
10    ref: HEAD
sources.pdf[]
Ver prueba
docu.profile.yaml#L31-L31
31  pdf: []
sources.web.allowlist["docs.spring.io", "docs.python.org", "developer.mozilla.org"]
Ver prueba
docu.profile.yaml#L33-L33
33    allowlist: ["docs.spring.io", "docs.python.org", "developer.mozilla.org"]
sources.contracts[]
Ver prueba
docu.profile.yaml#L34-L34
34  contracts: []
output.dirdocs/generated
Ver prueba
docu.profile.yaml#L37-L37
37  dir: docs/generated
output.languagees
Ver prueba
docu.profile.yaml#L38-L38
38  language: es
output.levels.l1true
Ver prueba
docu.profile.yaml#L40-L40
40    l1: true
output.levels.l2true
Ver prueba
docu.profile.yaml#L41-L41
41    l2: true
output.levels.l3true
Ver prueba
docu.profile.yaml#L42-L42
42    l3: true
output.levels.l4true
Ver prueba
docu.profile.yaml#L43-L43
43    l4: true
output.notation.diagramsmermaid
Ver prueba
docu.profile.yaml#L45-L45
45    diagrams: mermaid
output.notation.architecturec4
Ver prueba
docu.profile.yaml#L46-L46
46    architecture: c4
output.notation.apiopenapi3.1
Ver prueba
docu.profile.yaml#L47-L47
47    api: openapi3.1
acceptance.thresholds.accuracy8.5
Ver prueba
docu.profile.yaml#L51-L51
51    accuracy: 8.5
acceptance.thresholds.completeness9.0
Ver prueba
docu.profile.yaml#L52-L52
52    completeness: 9.0
acceptance.thresholds.attribution9.5
Ver prueba
docu.profile.yaml#L53-L53
53    attribution: 9.5
acceptance.thresholds.conciseness7.5
Ver prueba
docu.profile.yaml#L54-L54
54    conciseness: 7.5
freshness.ttl_days90
Ver prueba
docu.profile.yaml#L57-L57
57  ttl_days: 90
learn.promotion_delta0.05
Ver prueba
docu.profile.yaml#L60-L60
60  promotion_delta: 0.05
learn.rollback_drop0.05
Ver prueba
docu.profile.yaml#L61-L61
61  rollback_drop: 0.05
learn.federatefalse
Ver prueba
docu.profile.yaml#L62-L62
62  federate: false

Modelo de datos 425

QuéDetalleEvidencia
Segment.pathstr
Ver prueba
eval/harness.py#L123-L123
123    path: str
Segment.startint
Ver prueba
eval/harness.py#L124-L124
124    start: int
Segment.endint
Ver prueba
eval/harness.py#L125-L125
125    end: int
Segment.textstr
Ver prueba
eval/harness.py#L126-L126
126    text: str
Segment.tokenstuple[str, ...]
Ver prueba
eval/harness.py#L127-L127
127    tokens: tuple[str, ...] = ()
Segment.exact_namestuple[str, ...]
Ver prueba
eval/harness.py#L128-L128
128    exact_names: tuple[str, ...] = ()
Segment.citationstr | None
Ver prueba
eval/harness.py#L129-L129
129    citation: str | None = None
BM25.k1float
Ver prueba
eval/harness.py#L263-L263
263    k1: float = 1.5
BM25.bfloat
Ver prueba
eval/harness.py#L264-L264
264    b: float = 0.75
BM25.segmentsSequence[Segment]
Ver prueba
eval/harness.py#L265-L265
265    segments: Sequence[Segment] = ()
BM25._dfdict[str, int]
Ver prueba
eval/harness.py#L266-L266
266    _df: dict[str, int] = field(default_factory=dict, init=False)
BM25._lengthslist[int]
Ver prueba
eval/harness.py#L267-L267
267    _lengths: list[int] = field(default_factory=list, init=False)
BM25._avgdlfloat
Ver prueba
eval/harness.py#L268-L268
268    _avgdl: float = field(default=0.0, init=False)
AutoIndex.segmentsSequence[Segment]
Ver prueba
eval/harness.py#L437-L437
437    segments: Sequence[Segment]
AutoIndex.embedderobject
Ver prueba
eval/harness.py#L438-L438
438    embedder: object = None
AutoIndex._symbolsSymbolIndex
Ver prueba
eval/harness.py#L439-L439
439    _symbols: SymbolIndex = field(init=False, repr=False)
AutoIndex._hybridHybridIndex
Ver prueba
eval/harness.py#L440-L440
440    _hybrid: HybridIndex = field(init=False, repr=False)
HybridIndex.segmentsSequence[Segment]
Ver prueba
eval/harness.py#L460-L460
460    segments: Sequence[Segment]
HybridIndex.embedderobject
Ver prueba
eval/harness.py#L461-L461
461    embedder: object = None
HybridIndex.k1float
Ver prueba
eval/harness.py#L462-L462
462    k1: float = 1.5
HybridIndex.bfloat
Ver prueba
eval/harness.py#L463-L463
463    b: float = 0.75
HybridIndex.rrf_kint
Ver prueba
eval/harness.py#L464-L464
464    rrf_k: int = 60
HybridIndex.max_exact_per_fileint
Ver prueba
eval/harness.py#L465-L465
465    max_exact_per_file: int = 2
HybridIndex.max_per_fileint
Ver prueba
eval/harness.py#L466-L466
466    max_per_file: int = 2
HybridIndex._bm25BM25
Ver prueba
eval/harness.py#L467-L467
467    _bm25: BM25 = field(init=False, repr=False)
HybridIndex._by_namedict[str, list[Segment]]
Ver prueba
eval/harness.py#L468-L468
468    _by_name: dict[str, list[Segment]] = field(init=False, repr=False, default_factory=dict)
HybridIndex._vectorslist[list[float]]
Ver prueba
eval/harness.py#L469-L469
469    _vectors: list[list[float]] = field(init=False, repr=False, default_factory=list)
SymbolIndex.segmentsSequence[Segment]
Ver prueba
eval/harness.py#L548-L548
548    segments: Sequence[Segment]
SymbolIndex.k1float
Ver prueba
eval/harness.py#L549-L549
549    k1: float = 1.5
SymbolIndex.bfloat
Ver prueba
eval/harness.py#L550-L550
550    b: float = 0.75
SymbolIndex.rrf_kint
Ver prueba
eval/harness.py#L551-L551
551    rrf_k: int = 60
SymbolIndex.max_exact_per_fileint
Ver prueba
eval/harness.py#L552-L552
552    max_exact_per_file: int = 2
SymbolIndex.max_per_fileint
Ver prueba
eval/harness.py#L553-L553
553    max_per_file: int = 2
SymbolIndex._bm25BM25
Ver prueba
eval/harness.py#L554-L554
554    _bm25: BM25 = field(init=False, repr=False)
SymbolIndex._by_namedict[str, list[Segment]]
Ver prueba
eval/harness.py#L555-L555
555    _by_name: dict[str, list[Segment]] = field(init=False, repr=False, default_factory=dict)
Expected.pathstr
Ver prueba
eval/harness.py#L602-L602
602    path: str
Expected.symbolstr | None
Ver prueba
eval/harness.py#L603-L603
603    symbol: str | None = None
Expected.linestuple[int, int] | None
Ver prueba
eval/harness.py#L604-L604
604    lines: tuple[int, int] | None = None
Expected.optionalbool
Ver prueba
eval/harness.py#L605-L605
605    optional: bool = False
Case.idstr
Ver prueba
eval/harness.py#L610-L610
610    id: str
Case.categorystr
Ver prueba
eval/harness.py#L611-L611
611    category: str
Case.questionstr
Ver prueba
eval/harness.py#L612-L612
612    question: str
Case.expectedtuple[Expected, ...]
Ver prueba
eval/harness.py#L613-L613
613    expected: tuple[Expected, ...]
Case.answerstr
Ver prueba
eval/harness.py#L614-L614
614    answer: str = ""
Case.notesstr
Ver prueba
eval/harness.py#L615-L615
615    notes: str = ""
Case.querystr
Ver prueba
eval/harness.py#L616-L616
616    query: str = ""
CaseResult.case_idstr
Ver prueba
eval/harness.py#L631-L631
631    case_id: str
CaseResult.categorystr
Ver prueba
eval/harness.py#L632-L632
632    category: str
CaseResult.recallfloat
Ver prueba
eval/harness.py#L633-L633
633    recall: float
CaseResult.hitbool
Ver prueba
eval/harness.py#L634-L634
634    hit: bool
CaseResult.mrrfloat
Ver prueba
eval/harness.py#L635-L635
635    mrr: float
CaseResult.line_hitbool | None
Ver prueba
eval/harness.py#L636-L636
636    line_hit: bool | None
CaseResult.symbol_hitbool | None
Ver prueba
eval/harness.py#L637-L637
637    symbol_hit: bool | None
CaseResult.query_modestr
Ver prueba
eval/harness.py#L638-L638
638    query_mode: str
CaseResult.passedbool
Ver prueba
eval/harness.py#L639-L639
639    passed: bool
CaseResult.retrievedtuple[str, ...]
Ver prueba
eval/harness.py#L640-L640
640    retrieved: tuple[str, ...]
CaseResult.elapsed_msfloat
Ver prueba
eval/harness.py#L641-L641
641    elapsed_ms: float
Report.projectstr
Ver prueba
eval/harness.py#L646-L646
646    project: str
Report.kint
Ver prueba
eval/harness.py#L647-L647
647    k: int
Report.filesint
Ver prueba
eval/harness.py#L648-L648
648    files: int
Report.segmentsint
Ver prueba
eval/harness.py#L649-L649
649    segments: int
Report.resultslist[CaseResult]
Ver prueba
eval/harness.py#L650-L650
650    results: list[CaseResult]
Report.query_fieldstr
Ver prueba
eval/harness.py#L651-L651
651    query_field: str = "auto"
Report.index_modestr
Ver prueba
eval/harness.py#L652-L652
652    index_mode: str = "windows"
Report.query_expansionbool
Ver prueba
eval/harness.py#L653-L653
653    query_expansion: bool = False
Report.generated_atstr
Ver prueba
eval/harness.py#L654-L654
654    generated_at: str = ""
Report.schema_versionstr
Ver prueba
eval/harness.py#L655-L655
655    schema_version: str = SCHEMA_VERSION
OnnxEmbedder.model_dirPath | str
Ver prueba
src/docu/adapters/embedders/onnx_local.py#L43-L43
43    model_dir: Path | str = DEFAULT_MODEL_DIR
OnnxEmbedder.embedder_idstr
Ver prueba
src/docu/adapters/embedders/onnx_local.py#L44-L44
44    embedder_id: str = DEFAULT_EMBEDDER_ID
OnnxEmbedder.max_lengthint
Ver prueba
src/docu/adapters/embedders/onnx_local.py#L45-L45
45    max_length: int = 256
OnnxEmbedder.batch_sizeint
Ver prueba
src/docu/adapters/embedders/onnx_local.py#L46-L46
46    batch_size: int = 16
OnnxEmbedder._sessionobject | None
Ver prueba
src/docu/adapters/embedders/onnx_local.py#L47-L47
47    _session: object | None = None
OnnxEmbedder._tokenizerobject | None
Ver prueba
src/docu/adapters/embedders/onnx_local.py#L48-L48
48    _tokenizer: object | None = None
OnnxEmbedder._input_namestuple[str, ...]
Ver prueba
src/docu/adapters/embedders/onnx_local.py#L49-L49
49    _input_names: tuple[str, ...] = ()
OnnxEmbedder._dimint
Ver prueba
src/docu/adapters/embedders/onnx_local.py#L50-L50
50    _dim: int = 384
JavaLangAdapter.languagestr
Ver prueba
src/docu/adapters/langs/java.py#L369-L369
369    language: str = "java"
JavaLangAdapter.file_globstuple[str, ...]
Ver prueba
src/docu/adapters/langs/java.py#L370-L370
370    file_globs: tuple[str, ...] = ("*.java",)
PythonLangAdapter.languagestr
Ver prueba
src/docu/adapters/langs/python.py#L22-L22
22    language: str = "python"
PythonLangAdapter.file_globstuple[str, ...]
Ver prueba
src/docu/adapters/langs/python.py#L23-L23
23    file_globs: tuple[str, ...] = ("*.py",)
TypeScriptLangAdapter.languagestr
Ver prueba
src/docu/adapters/langs/typescript.py#L88-L88
88    language: str = "typescript"
TypeScriptLangAdapter.file_globstuple[str, ...]
Ver prueba
src/docu/adapters/langs/typescript.py#L89-L89
89    file_globs: tuple[str, ...] = ("*.ts", "*.tsx", "*.js", "*.jsx", "*.mjs", "*.cjs")
PdfPage.numberint
Ver prueba
src/docu/adapters/sources/pdf.py#L120-L120
120    number: int
PdfPage.textstr
Ver prueba
src/docu/adapters/sources/pdf.py#L121-L121
121    text: str
PdfText.pagestuple[PdfPage, ...]
Ver prueba
src/docu/adapters/sources/pdf.py#L126-L126
126    pages: tuple[PdfPage, ...] = ()
PdfText.total_pagesint
Ver prueba
src/docu/adapters/sources/pdf.py#L127-L127
127    total_pages: int = 0
PdfText.charsint
Ver prueba
src/docu/adapters/sources/pdf.py#L128-L128
128    chars: int = 0
PdfText.methodstr
Ver prueba
src/docu/adapters/sources/pdf.py#L129-L129
129    method: str = "desconocido"
PdfText.warningstuple[str, ...]
Ver prueba
src/docu/adapters/sources/pdf.py#L130-L130
130    warnings: tuple[str, ...] = field(default_factory=tuple)
Snapshot.urlstr
Ver prueba
src/docu/adapters/sources/web.py#L44-L44
44    url: str
Snapshot.textstr
Ver prueba
src/docu/adapters/sources/web.py#L45-L45
45    text: str
Snapshot.shastr
Ver prueba
src/docu/adapters/sources/web.py#L46-L46
46    sha: str
Snapshot.captured_atstr
Ver prueba
src/docu/adapters/sources/web.py#L47-L47
47    captured_at: str
Snapshot.status_codeint
Ver prueba
src/docu/adapters/sources/web.py#L48-L48
48    status_code: int = 200
Check.namestr
Ver prueba
src/docu/audit/verify.py#L43-L43
43    name: str
Check.totalint
Ver prueba
src/docu/audit/verify.py#L44-L44
44    total: int
Check.failedint
Ver prueba
src/docu/audit/verify.py#L45-L45
45    failed: int
Check.detailstuple[str, ...]
Ver prueba
src/docu/audit/verify.py#L46-L46
46    details: tuple[str, ...] = ()
Check.notestr
Ver prueba
src/docu/audit/verify.py#L47-L47
47    note: str = ""
AuditReport.projectstr
Ver prueba
src/docu/audit/verify.py#L73-L73
73    project: str
AuditReport.checksdict[str, Check]
Ver prueba
src/docu/audit/verify.py#L74-L74
74    checks: dict[str, Check] = field(default_factory=dict)
AuditReport.facts_totalint
Ver prueba
src/docu/audit/verify.py#L76-L76
76    facts_total: int = 0
AuditReport.excludeddict[str, int]
Ver prueba
src/docu/audit/verify.py#L77-L77
77    excluded: dict[str, int] = field(default_factory=dict)
Discrepancy.kindstr
Ver prueba
src/docu/conformance/drift.py#L39-L39
39    kind: str
Discrepancy.subjectstr
Ver prueba
src/docu/conformance/drift.py#L40-L40
40    subject: str
Discrepancy.detailstr
Ver prueba
src/docu/conformance/drift.py#L41-L41
41    detail: str
Discrepancy.code_citationstr | None
Ver prueba
src/docu/conformance/drift.py#L42-L42
42    code_citation: str | None = None
Discrepancy.declaration_sourcestr | None
Ver prueba
src/docu/conformance/drift.py#L43-L43
43    declaration_source: str | None = None
DriftReport.modelArchitectureModel
Ver prueba
src/docu/conformance/drift.py#L67-L67
67    model: ArchitectureModel
DriftReport.discrepancieslist[Discrepancy]
Ver prueba
src/docu/conformance/drift.py#L68-L68
68    discrepancies: list[Discrepancy] = field(default_factory=list)
DriftReport.routes_in_codeint
Ver prueba
src/docu/conformance/drift.py#L69-L69
69    routes_in_code: int = 0
DriftReport.components_in_codeint
Ver prueba
src/docu/conformance/drift.py#L70-L70
70    components_in_code: int = 0
RouteFact.keystr
Ver prueba
src/docu/conformance/drift.py#L128-L128
128    key: str
RouteFact.citationstr
Ver prueba
src/docu/conformance/drift.py#L129-L129
129    citation: str
RouteFact.handlerstr
Ver prueba
src/docu/conformance/drift.py#L130-L130
130    handler: str
CodeFacts.routestuple[RouteFact, ...]
Ver prueba
src/docu/conformance/drift.py#L135-L135
135    routes: tuple[RouteFact, ...]
CodeFacts.componentsMapping[str, str]
Ver prueba
src/docu/conformance/drift.py#L136-L136
136    components: Mapping[str, str]  # nombre de tipo -> cita
CodeFacts.dependenciestuple[tuple[str, str], ...]
Ver prueba
src/docu/conformance/drift.py#L137-L137
137    dependencies: tuple[tuple[str, str], ...]  # (llamador, llamado)
Route.verbstr
Ver prueba
src/docu/conformance/model.py#L32-L32
32    verb: str
Route.pathstr
Ver prueba
src/docu/conformance/model.py#L33-L33
33    path: str
DeclaredComponent.namestr
Ver prueba
src/docu/conformance/model.py#L45-L45
45    name: str
DeclaredComponent.kindstr
Ver prueba
src/docu/conformance/model.py#L46-L46
46    kind: str = "component"
DeclaredComponent.providestuple[Route, ...]
Ver prueba
src/docu/conformance/model.py#L47-L47
47    provides: tuple[Route, ...] = ()
DeclaredComponent.depends_ontuple[str, ...]
Ver prueba
src/docu/conformance/model.py#L48-L48
48    depends_on: tuple[str, ...] = ()
DeclaredComponent.sourcestr
Ver prueba
src/docu/conformance/model.py#L49-L49
49    source: str = ""
ArchitectureModel.componentstuple[DeclaredComponent, ...]
Ver prueba
src/docu/conformance/model.py#L54-L54
54    components: tuple[DeclaredComponent, ...] = ()
ArchitectureModel.routestuple[Route, ...]
Ver prueba
src/docu/conformance/model.py#L55-L55
55    routes: tuple[Route, ...] = ()
ArchitectureModel.sourcestuple[str, ...]
Ver prueba
src/docu/conformance/model.py#L56-L56
56    sources: tuple[str, ...] = ()
ArchitectureModel.schema_versionstr
Ver prueba
src/docu/conformance/model.py#L57-L57
57    schema_version: str = "1.0"
Artifact.artifact_idstr
Ver prueba
src/docu/core/contracts.py#L99-L99
99    artifact_id: str
Artifact.kindSourceKind
Ver prueba
src/docu/core/contracts.py#L100-L100
100    kind: SourceKind
Artifact.uristr
Ver prueba
src/docu/core/contracts.py#L101-L101
101    uri: str
Artifact.content_hashstr
Ver prueba
src/docu/core/contracts.py#L102-L102
102    content_hash: str
Artifact.captured_atdatetime
Ver prueba
src/docu/core/contracts.py#L103-L103
103    captured_at: datetime
Artifact.langstr | None
Ver prueba
src/docu/core/contracts.py#L104-L104
104    lang: str | None = None
Artifact.snapshot_pathstr | None
Ver prueba
src/docu/core/contracts.py#L105-L105
105    snapshot_path: str | None = None
Artifact.metadataMapping[str, Any]
Ver prueba
src/docu/core/contracts.py#L106-L106
106    metadata: Mapping[str, Any] = field(default_factory=dict)
Artifact.schema_versionstr
Ver prueba
src/docu/core/contracts.py#L107-L107
107    schema_version: str = SCHEMA_VERSION
Symbol.namestr
Ver prueba
src/docu/core/contracts.py#L122-L122
122    name: str
Symbol.qualnamestr
Ver prueba
src/docu/core/contracts.py#L123-L123
123    qualname: str
Symbol.kindSymbolKind
Ver prueba
src/docu/core/contracts.py#L124-L124
124    kind: SymbolKind
Symbol.pathstr
Ver prueba
src/docu/core/contracts.py#L125-L125
125    path: str
Symbol.line_startint
Ver prueba
src/docu/core/contracts.py#L126-L126
126    line_start: int
Symbol.line_endint
Ver prueba
src/docu/core/contracts.py#L127-L127
127    line_end: int
Symbol.signaturestr | None
Ver prueba
src/docu/core/contracts.py#L128-L128
128    signature: str | None = None
Symbol.childrenSequence[Symbol]
Ver prueba
src/docu/core/contracts.py#L129-L129
129    children: Sequence[Symbol] = ()
Symbol.annotationsSequence[str]
Ver prueba
src/docu/core/contracts.py#L130-L130
130    annotations: Sequence[str] = ()
Symbol.schema_versionstr
Ver prueba
src/docu/core/contracts.py#L131-L131
131    schema_version: str = SCHEMA_VERSION
Chunk.chunk_idstr
Ver prueba
src/docu/core/contracts.py#L145-L145
145    chunk_id: str
Chunk.artifact_idstr
Ver prueba
src/docu/core/contracts.py#L146-L146
146    artifact_id: str
Chunk.source_typeSourceKind
Ver prueba
src/docu/core/contracts.py#L147-L147
147    source_type: SourceKind
Chunk.contentstr
Ver prueba
src/docu/core/contracts.py#L148-L148
148    content: str
Chunk.content_prefixstr
Ver prueba
src/docu/core/contracts.py#L149-L149
149    content_prefix: str
Chunk.content_hashstr
Ver prueba
src/docu/core/contracts.py#L150-L150
150    content_hash: str
Chunk.file_pathstr
Ver prueba
src/docu/core/contracts.py#L151-L151
151    file_path: str
Chunk.langstr | None
Ver prueba
src/docu/core/contracts.py#L152-L152
152    lang: str | None
Chunk.enclosing_symbolstr | None
Ver prueba
src/docu/core/contracts.py#L153-L153
153    enclosing_symbol: str | None
Chunk.symbol_kindSymbolKind
Ver prueba
src/docu/core/contracts.py#L154-L154
154    symbol_kind: SymbolKind
Chunk.line_startint
Ver prueba
src/docu/core/contracts.py#L155-L155
155    line_start: int
Chunk.line_endint
Ver prueba
src/docu/core/contracts.py#L156-L156
156    line_end: int
Chunk.ingested_atdatetime
Ver prueba
src/docu/core/contracts.py#L157-L157
157    ingested_at: datetime
Chunk.repostr | None
Ver prueba
src/docu/core/contracts.py#L158-L158
158    repo: str | None = None
Chunk.commitstr | None
Ver prueba
src/docu/core/contracts.py#L159-L159
159    commit: str | None = None
Chunk.dependenciesSequence[str]
Ver prueba
src/docu/core/contracts.py#L160-L160
160    dependencies: Sequence[str] = ()
Chunk.embed_modelstr | None
Ver prueba
src/docu/core/contracts.py#L161-L161
161    embed_model: str | None = None
Chunk.chunkerstr
Ver prueba
src/docu/core/contracts.py#L162-L162
162    chunker: str = "ast-v2"
Chunk.schema_versionstr
Ver prueba
src/docu/core/contracts.py#L163-L163
163    schema_version: str = SCHEMA_VERSION
Claim.textstr
Ver prueba
src/docu/core/contracts.py#L210-L210
210    text: str
Claim.evidenceSequence[str]
Ver prueba
src/docu/core/contracts.py#L211-L211
211    evidence: Sequence[str] = ()
ContentNode.node_idstr
Ver prueba
src/docu/core/contracts.py#L226-L226
226    node_id: str
ContentNode.kindstr
Ver prueba
src/docu/core/contracts.py#L227-L227
227    kind: str
ContentNode.titlestr
Ver prueba
src/docu/core/contracts.py#L228-L228
228    title: str
ContentNode.claimslist[Claim]
Ver prueba
src/docu/core/contracts.py#L229-L229
229    claims: list[Claim] = field(default_factory=list)
ContentNode.levelstuple[str, ...]
Ver prueba
src/docu/core/contracts.py#L230-L230
230    levels: tuple[str, ...] = ("l1",)
ContentNode.stateDocState
Ver prueba
src/docu/core/contracts.py#L231-L231
231    state: DocState = DocState.FRESH
ContentNode.confidencefloat
Ver prueba
src/docu/core/contracts.py#L232-L232
232    confidence: float = 0.0
ContentNode.rendereddict[str, str]
Ver prueba
src/docu/core/contracts.py#L233-L233
233    rendered: dict[str, str] = field(default_factory=dict)
ContentNode.schema_versionstr
Ver prueba
src/docu/core/contracts.py#L234-L234
234    schema_version: str = SCHEMA_VERSION
Metrics.accuracyfloat
Ver prueba
src/docu/core/contracts.py#L251-L251
251    accuracy: float
Metrics.completenessfloat
Ver prueba
src/docu/core/contracts.py#L252-L252
252    completeness: float
Metrics.attributionfloat
Ver prueba
src/docu/core/contracts.py#L253-L253
253    attribution: float
Metrics.concisenessfloat
Ver prueba
src/docu/core/contracts.py#L254-L254
254    conciseness: float
Metrics.freshnessfloat
Ver prueba
src/docu/core/contracts.py#L255-L255
255    freshness: float = 10.0
Metrics.cost_usdfloat
Ver prueba
src/docu/core/contracts.py#L256-L256
256    cost_usd: float = 0.0
Metrics.unsupported_claimsint
Ver prueba
src/docu/core/contracts.py#L257-L257
257    unsupported_claims: int = 0
Metrics.schema_versionstr
Ver prueba
src/docu/core/contracts.py#L258-L258
258    schema_version: str = SCHEMA_VERSION
GateDecision.outcomeGateOutcome
Ver prueba
src/docu/core/contracts.py#L265-L265
265    outcome: GateOutcome
GateDecision.reasonstuple[str, ...]
Ver prueba
src/docu/core/contracts.py#L266-L266
266    reasons: tuple[str, ...] = ()
RunRecord.run_idstr
Ver prueba
src/docu/core/contracts.py#L285-L285
285    run_id: str
RunRecord.projectstr
Ver prueba
src/docu/core/contracts.py#L286-L286
286    project: str
RunRecord.commitstr | None
Ver prueba
src/docu/core/contracts.py#L287-L287
287    commit: str | None
RunRecord.modeMode
Ver prueba
src/docu/core/contracts.py#L288-L288
288    mode: Mode
RunRecord.started_atdatetime
Ver prueba
src/docu/core/contracts.py#L289-L289
289    started_at: datetime
RunRecord.finished_atdatetime | None
Ver prueba
src/docu/core/contracts.py#L290-L290
290    finished_at: datetime | None = None
RunRecord.versionsdict[str, str]
Ver prueba
src/docu/core/contracts.py#L291-L291
291    versions: dict[str, str] = field(default_factory=dict)
RunRecord.metricsMetrics | None
Ver prueba
src/docu/core/contracts.py#L292-L292
292    metrics: Metrics | None = None
RunRecord.gateGateDecision | None
Ver prueba
src/docu/core/contracts.py#L293-L293
293    gate: GateDecision | None = None
RunRecord.pages_writtenint
Ver prueba
src/docu/core/contracts.py#L294-L294
294    pages_written: int = 0
RunRecord.pages_skippedint
Ver prueba
src/docu/core/contracts.py#L295-L295
295    pages_skipped: int = 0
RunRecord.cost_usdfloat
Ver prueba
src/docu/core/contracts.py#L296-L296
296    cost_usd: float = 0.0
RunRecord.errorslist[str]
Ver prueba
src/docu/core/contracts.py#L297-L297
297    errors: list[str] = field(default_factory=list)
RunRecord.schema_versionstr
Ver prueba
src/docu/core/contracts.py#L298-L298
298    schema_version: str = SCHEMA_VERSION
FreshnessRecord.node_idstr
Ver prueba
src/docu/core/contracts.py#L336-L336
336    node_id: str
FreshnessRecord.input_hashstr
Ver prueba
src/docu/core/contracts.py#L337-L337
337    input_hash: str
FreshnessRecord.stateDocState
Ver prueba
src/docu/core/contracts.py#L338-L338
338    state: DocState
FreshnessRecord.generated_atdatetime
Ver prueba
src/docu/core/contracts.py#L339-L339
339    generated_at: datetime
FreshnessRecord.ttl_daysint
Ver prueba
src/docu/core/contracts.py#L340-L340
340    ttl_days: int = 90
FreshnessRecord.schema_versionstr
Ver prueba
src/docu/core/contracts.py#L341-L341
341    schema_version: str = SCHEMA_VERSION
Thresholds.accuracyfloat
Ver prueba
src/docu/core/policy.py#L23-L23
23    accuracy: float = 8.5
Thresholds.completenessfloat
Ver prueba
src/docu/core/policy.py#L24-L24
24    completeness: float = 9.0
Thresholds.attributionfloat
Ver prueba
src/docu/core/policy.py#L25-L25
25    attribution: float = 9.5
Thresholds.concisenessfloat
Ver prueba
src/docu/core/policy.py#L26-L26
26    conciseness: float = 7.5
Budget.max_cost_usdfloat
Ver prueba
src/docu/core/policy.py#L41-L41
41    max_cost_usd: float = 3.0
Budget.max_secondsfloat
Ver prueba
src/docu/core/policy.py#L42-L42
42    max_seconds: float = 900.0
Budget.max_pagesint
Ver prueba
src/docu/core/policy.py#L43-L43
43    max_pages: int = 40
Budget.max_llm_callsint
Ver prueba
src/docu/core/policy.py#L44-L44
44    max_llm_calls: int = 120
Budget.spent_usdfloat
Ver prueba
src/docu/core/policy.py#L45-L45
45    spent_usd: float = 0.0
Budget.elapsed_sfloat
Ver prueba
src/docu/core/policy.py#L46-L46
46    elapsed_s: float = 0.0
Budget.pages_writtenint
Ver prueba
src/docu/core/policy.py#L47-L47
47    pages_written: int = 0
Budget.llm_callsint
Ver prueba
src/docu/core/policy.py#L48-L48
48    llm_calls: int = 0
GatePolicy.thresholdsThresholds
Ver prueba
src/docu/core/policy.py#L79-L79
79    thresholds: Thresholds = field(default_factory=Thresholds)
GatePolicy.require_zero_unsupportedbool
Ver prueba
src/docu/core/policy.py#L80-L80
80    require_zero_unsupported: bool = True
GatePolicy.require_freshbool
Ver prueba
src/docu/core/policy.py#L81-L81
81    require_fresh: bool = True
SourceAdapter.namestr
Ver prueba
src/docu/core/ports.py#L21-L21
21    name: str
SourceAdapter.kindtype
Ver prueba
src/docu/core/ports.py#L22-L22
22    kind: type
LangAdapter.languagestr
Ver prueba
src/docu/core/ports.py#L38-L38
38    language: str
LangAdapter.file_globsSequence[str]
Ver prueba
src/docu/core/ports.py#L39-L39
39    file_globs: Sequence[str]
Chunker.namestr
Ver prueba
src/docu/core/ports.py#L59-L59
59    name: str
Embedder.embedder_idstr
Ver prueba
src/docu/core/ports.py#L72-L72
72    embedder_id: str
Embedder.dimint
Ver prueba
src/docu/core/ports.py#L73-L73
73    dim: int
VectorStore.store_idstr
Ver prueba
src/docu/core/ports.py#L83-L83
83    store_id: str
Reranker.reranker_idstr
Ver prueba
src/docu/core/ports.py#L101-L101
101    reranker_id: str
RenderAdapter.namestr
Ver prueba
src/docu/core/ports.py#L114-L114
114    name: str
RenderAdapter.targetstr
Ver prueba
src/docu/core/ports.py#L115-L115
115    target: str
Judge.judge_idstr
Ver prueba
src/docu/core/ports.py#L125-L125
125    judge_id: str
Judge.temperaturefloat
Ver prueba
src/docu/core/ports.py#L126-L126
126    temperature: float
Publisher.publisher_idstr
Ver prueba
src/docu/core/ports.py#L136-L136
136    publisher_id: str
Profile.projectstr
Ver prueba
src/docu/core/profile.py#L54-L54
54    project: str
Profile.modeMode
Ver prueba
src/docu/core/profile.py#L55-L55
55    mode: Mode = Mode.APPLY
Profile.levelstuple[str, ...]
Ver prueba
src/docu/core/profile.py#L56-L56
56    levels: tuple[str, ...] = ("l1", "l4")
Profile.output_dirstr
Ver prueba
src/docu/core/profile.py#L57-L57
57    output_dir: str = "docs/generated"
Profile.languagestr
Ver prueba
src/docu/core/profile.py#L58-L58
58    language: str = "es"
Profile.ttl_daysint
Ver prueba
src/docu/core/profile.py#L59-L59
59    ttl_days: int = 90
Profile.includetuple[str, ...]
Ver prueba
src/docu/core/profile.py#L60-L60
60    include: tuple[str, ...] = ()
Profile.excludetuple[str, ...]
Ver prueba
src/docu/core/profile.py#L61-L61
61    exclude: tuple[str, ...] = DEFAULT_EXCLUDE
Profile.thresholdsThresholds
Ver prueba
src/docu/core/profile.py#L62-L62
62    thresholds: Thresholds = field(default_factory=Thresholds)
Profile.glossaryMapping[str, tuple[str, ...]]
Ver prueba
src/docu/core/profile.py#L63-L63
63    glossary: Mapping[str, tuple[str, ...]] = field(default_factory=dict)
Profile.promotion_deltafloat
Ver prueba
src/docu/core/profile.py#L64-L64
64    promotion_delta: float = 0.05
Profile.rollback_dropfloat
Ver prueba
src/docu/core/profile.py#L65-L65
65    rollback_drop: float = 0.05
Profile.federatebool
Ver prueba
src/docu/core/profile.py#L66-L66
66    federate: bool = False
Profile.web_allowlisttuple[str, ...]
Ver prueba
src/docu/core/profile.py#L67-L67
67    web_allowlist: tuple[str, ...] = ()
Profile.web_urlstuple[str, ...]
Ver prueba
src/docu/core/profile.py#L68-L68
68    web_urls: tuple[str, ...] = ()
Profile.pathPath | None
Ver prueba
src/docu/core/profile.py#L69-L69
69    path: Path | None = None
Profile.rawMapping[str, object]
Ver prueba
src/docu/core/profile.py#L70-L70
70    raw: Mapping[str, object] = field(default_factory=dict)
Change.fieldstr
Ver prueba
src/docu/core/profile.py#L321-L321
321    field: str
Change.beforeobject
Ver prueba
src/docu/core/profile.py#L322-L322
322    before: object
Change.afterobject
Ver prueba
src/docu/core/profile.py#L323-L323
323    after: object
Change.reasonstr
Ver prueba
src/docu/core/profile.py#L324-L324
324    reason: str
Change.appliedbool
Ver prueba
src/docu/core/profile.py#L325-L325
325    applied: bool = True
CleanPlan.documentslist[Path]
Ver prueba
src/docu/delivery/cleanup.py#L47-L47
47    documents: list[Path] = field(default_factory=list)
CleanPlan.artifactslist[Path]
Ver prueba
src/docu/delivery/cleanup.py#L48-L48
48    artifacts: list[Path] = field(default_factory=list)
CleanPlan.statelist[Path]
Ver prueba
src/docu/delivery/cleanup.py#L49-L49
49    state: list[Path] = field(default_factory=list)
CleanPlan.ledgerlist[Path]
Ver prueba
src/docu/delivery/cleanup.py#L50-L50
50    ledger: list[Path] = field(default_factory=list)
CleanPlan.warningslist[str]
Ver prueba
src/docu/delivery/cleanup.py#L51-L51
51    warnings: list[str] = field(default_factory=list)
ResolvedOptions.profileProfile | None
Ver prueba
src/docu/delivery/cli.py#L292-L292
292    profile: Profile | None
ResolvedOptions.projectstr
Ver prueba
src/docu/delivery/cli.py#L293-L293
293    project: str
ResolvedOptions.levelstuple[str, ...]
Ver prueba
src/docu/delivery/cli.py#L294-L294
294    levels: tuple[str, ...]
ResolvedOptions.out_dirPath
Ver prueba
src/docu/delivery/cli.py#L295-L295
295    out_dir: Path
ResolvedOptions.ttl_daysint
Ver prueba
src/docu/delivery/cli.py#L296-L296
296    ttl_days: int
ResolvedOptions.includetuple[str, ...]
Ver prueba
src/docu/delivery/cli.py#L297-L297
297    include: tuple[str, ...]
ResolvedOptions.excludetuple[str, ...]
Ver prueba
src/docu/delivery/cli.py#L298-L298
298    exclude: tuple[str, ...]
ResolvedOptions.thresholdsThresholds
Ver prueba
src/docu/delivery/cli.py#L299-L299
299    thresholds: Thresholds
ResolvedOptions.manifestPath | None
Ver prueba
src/docu/delivery/cli.py#L300-L300
300    manifest: Path | None
_Handler.server_versionsin tipo declarado
Ver prueba
src/docu/delivery/http_server.py#L27-L27
27    server_version = "docu-mcp-http/0.1"
_Handler.mcpMcpServer
Ver prueba
src/docu/delivery/http_server.py#L28-L28
28    mcp: McpServer  # inyectado por clase antes de servir
ProjectRef.namestr
Ver prueba
src/docu/delivery/mcp_server.py#L167-L167
167    name: str
ProjectRef.rootPath
Ver prueba
src/docu/delivery/mcp_server.py#L168-L168
168    root: Path
ProjectRef.docs_dirPath
Ver prueba
src/docu/delivery/mcp_server.py#L169-L169
169    docs_dir: Path
McpServer.rootPath
Ver prueba
src/docu/delivery/mcp_server.py#L219-L219
219    root: Path = Path(".")
McpServer.docs_dirPath
Ver prueba
src/docu/delivery/mcp_server.py#L220-L220
220    docs_dir: Path = Path("docs/generated")
McpServer.manifest_pathPath | None
Ver prueba
src/docu/delivery/mcp_server.py#L221-L221
221    manifest_path: Path | None = None
McpServer.profile_pathPath | None
Ver prueba
src/docu/delivery/mcp_server.py#L222-L222
222    profile_path: Path | None = None
McpServer.workspacePath | None
Ver prueba
src/docu/delivery/mcp_server.py#L223-L223
223    workspace: Path | None = None
McpServer.densebool
Ver prueba
src/docu/delivery/mcp_server.py#L224-L224
224    dense: bool = True
McpServer._refsdict[str, ProjectRef]
Ver prueba
src/docu/delivery/mcp_server.py#L225-L225
225    _refs: dict[str, ProjectRef] = field(default_factory=dict, init=False, repr=False)
McpServer._indexesdict[str, DocIndex]
Ver prueba
src/docu/delivery/mcp_server.py#L226-L226
226    _indexes: dict[str, DocIndex] = field(default_factory=dict, init=False, repr=False)
McpServer._code_indexesdict[str, object]
Ver prueba
src/docu/delivery/mcp_server.py#L227-L227
227    _code_indexes: dict[str, object] = field(default_factory=dict, init=False, repr=False)
Diagram.namestr
Ver prueba
src/docu/generate/diagrams.py#L43-L43
43    name: str
Diagram.kindstr
Ver prueba
src/docu/generate/diagrams.py#L44-L44
44    kind: str
Diagram.mermaidstr
Ver prueba
src/docu/generate/diagrams.py#L45-L45
45    mermaid: str
Diagram.notestr
Ver prueba
src/docu/generate/diagrams.py#L46-L46
46    note: str = ""
DocSection.pathstr
Ver prueba
src/docu/generate/docs_evidence.py#L52-L52
52    path: str
DocSection.titlestr
Ver prueba
src/docu/generate/docs_evidence.py#L53-L53
53    title: str
DocSection.bodystr
Ver prueba
src/docu/generate/docs_evidence.py#L54-L54
54    body: str
DocSection.line_startint
Ver prueba
src/docu/generate/docs_evidence.py#L55-L55
55    line_start: int
DocSection.line_endint
Ver prueba
src/docu/generate/docs_evidence.py#L56-L56
56    line_end: int
Fact.kindstr
Ver prueba
src/docu/generate/facts.py#L32-L32
32    kind: str
Fact.subjectstr
Ver prueba
src/docu/generate/facts.py#L33-L33
33    subject: str
Fact.detailstr
Ver prueba
src/docu/generate/facts.py#L34-L34
34    detail: str
Fact.citationstr
Ver prueba
src/docu/generate/facts.py#L35-L35
35    citation: str
Fact.attributesMapping[str, str]
Ver prueba
src/docu/generate/facts.py#L36-L36
36    attributes: Mapping[str, str] = field(default_factory=dict)
Narrative.intentlist[Fact]
Ver prueba
src/docu/generate/narrative.py#L51-L51
51    intent: list[Fact] = field(default_factory=list)
Narrative.decisionslist[Fact]
Ver prueba
src/docu/generate/narrative.py#L52-L52
52    decisions: list[Fact] = field(default_factory=list)
Narrative.introstr
Ver prueba
src/docu/generate/narrative.py#L53-L53
53    intro: str = ""
GeneratedDoc.levelstr
Ver prueba
src/docu/generate/pipeline.py#L92-L92
92    level: str
GeneratedDoc.pathPath
Ver prueba
src/docu/generate/pipeline.py#L93-L93
93    path: Path
GeneratedDoc.contentstr
Ver prueba
src/docu/generate/pipeline.py#L94-L94
94    content: str
GenerationResult.projectstr
Ver prueba
src/docu/generate/pipeline.py#L99-L99
99    project: str
GenerationResult.docstuple[GeneratedDoc, ...]
Ver prueba
src/docu/generate/pipeline.py#L100-L100
100    docs: tuple[GeneratedDoc, ...]
GenerationResult.factstuple[Fact, ...]
Ver prueba
src/docu/generate/pipeline.py#L101-L101
101    facts: tuple[Fact, ...]
GenerationResult.sourcesMapping[str, str]
Ver prueba
src/docu/generate/pipeline.py#L102-L102
102    sources: Mapping[str, str]
GenerationResult.metricsMetrics
Ver prueba
src/docu/generate/pipeline.py#L103-L103
103    metrics: Metrics
GenerationResult.gateGateDecision
Ver prueba
src/docu/generate/pipeline.py#L104-L104
104    gate: GateDecision
GenerationResult.elapsed_sfloat
Ver prueba
src/docu/generate/pipeline.py#L105-L105
105    elapsed_s: float
GenerationResult.unsupportedtuple[Fact, ...]
Ver prueba
src/docu/generate/pipeline.py#L106-L106
106    unsupported: tuple[Fact, ...] = field(default_factory=tuple)
GenerationResult.statesMapping[str, DocState]
Ver prueba
src/docu/generate/pipeline.py#L107-L107
107    states: Mapping[str, DocState] = field(default_factory=dict)
GenerationResult.manifest_pathPath | None
Ver prueba
src/docu/generate/pipeline.py#L108-L108
108    manifest_path: Path | None = None
GenerationResult.applicabilityMapping[str, bool]
Ver prueba
src/docu/generate/pipeline.py#L109-L109
109    applicability: Mapping[str, bool] = field(default_factory=dict)
GenerationResult.unsupported_languagesMapping[str, int]
Ver prueba
src/docu/generate/pipeline.py#L110-L110
110    unsupported_languages: Mapping[str, int] = field(default_factory=dict)
GenerationResult.diagramstuple[str, ...]
Ver prueba
src/docu/generate/pipeline.py#L111-L111
111    diagrams: tuple[str, ...] = field(default_factory=tuple)
GenerationResult.dry_runbool
Ver prueba
src/docu/generate/pipeline.py#L112-L112
112    dry_run: bool = False
ProseResponse.reviewerstr
Ver prueba
src/docu/generate/prose.py#L54-L54
54    reviewer: str = ""
ProseResponse.sectionsdict[str, list[dict[str, object]]]
Ver prueba
src/docu/generate/prose.py#L55-L55
55    sections: dict[str, list[dict[str, object]]] = field(default_factory=dict)
ProseResponse.errorslist[str]
Ver prueba
src/docu/generate/prose.py#L56-L56
56    errors: list[str] = field(default_factory=list)
ProseResponse.warningslist[str]
Ver prueba
src/docu/generate/prose.py#L57-L57
57    warnings: list[str] = field(default_factory=list)
Verdict.judgestr
Ver prueba
src/docu/generate/prose.py#L68-L68
68    judge: str = ""
Verdict.scorefloat
Ver prueba
src/docu/generate/prose.py#L69-L69
69    score: float = 0.0
Verdict.criteriadict[str, float]
Ver prueba
src/docu/generate/prose.py#L70-L70
70    criteria: dict[str, float] = field(default_factory=dict)
Verdict.issueslist[str]
Ver prueba
src/docu/generate/prose.py#L71-L71
71    issues: list[str] = field(default_factory=list)
Verdict.errorslist[str]
Ver prueba
src/docu/generate/prose.py#L72-L72
72    errors: list[str] = field(default_factory=list)
SymbolChunker.namestr
Ver prueba
src/docu/index/chunker.py#L49-L49
49    name: str = DEFAULT_CHUNKER
SymbolChunker.max_tokensint
Ver prueba
src/docu/index/chunker.py#L50-L50
50    max_tokens: int = 1024
SymbolChunker.overlap_tokensint
Ver prueba
src/docu/index/chunker.py#L51-L51
51    overlap_tokens: int = 128
InputComponents.source_contentstr
Ver prueba
src/docu/index/freshness.py#L29-L29
29    source_content: str
InputComponents.deps_signaturestr
Ver prueba
src/docu/index/freshness.py#L30-L30
30    deps_signature: str
InputComponents.templatestr
Ver prueba
src/docu/index/freshness.py#L31-L31
31    template: str
InputComponents.embedderstr
Ver prueba
src/docu/index/freshness.py#L32-L32
32    embedder: str
InputComponents.chunkerstr
Ver prueba
src/docu/index/freshness.py#L33-L33
33    chunker: str
InputComponents.profilestr
Ver prueba
src/docu/index/freshness.py#L34-L34
34    profile: str
IgnoreRule.rawstr
Ver prueba
src/docu/index/ignore.py#L19-L19
19    raw: str
IgnoreRule.patternstr
Ver prueba
src/docu/index/ignore.py#L20-L20
20    pattern: str
IgnoreRule.negatebool
Ver prueba
src/docu/index/ignore.py#L21-L21
21    negate: bool
IgnoreRule.directory_onlybool
Ver prueba
src/docu/index/ignore.py#L22-L22
22    directory_only: bool
IgnoreRule.anchoredbool
Ver prueba
src/docu/index/ignore.py#L23-L23
23    anchored: bool
IgnoreRule.regexre.Pattern[str]
Ver prueba
src/docu/index/ignore.py#L24-L24
24    regex: re.Pattern[str]
DocEntry.levelstr
Ver prueba
src/docu/index/manifest.py#L36-L36
36    level: str
DocEntry.pathstr
Ver prueba
src/docu/index/manifest.py#L37-L37
37    path: str
DocEntry.input_hashstr
Ver prueba
src/docu/index/manifest.py#L38-L38
38    input_hash: str
DocEntry.generated_atstr
Ver prueba
src/docu/index/manifest.py#L39-L39
39    generated_at: str
DocEntry.content_hashstr
Ver prueba
src/docu/index/manifest.py#L40-L40
40    content_hash: str
DocEntry.ttl_daysint
Ver prueba
src/docu/index/manifest.py#L41-L41
41    ttl_days: int = 90
DocEntry.sourcesMapping[str, str]
Ver prueba
src/docu/index/manifest.py#L42-L42
42    sources: Mapping[str, str] = field(default_factory=dict)
Manifest.projectstr
Ver prueba
src/docu/index/manifest.py#L75-L75
75    project: str
Manifest.docslist[DocEntry]
Ver prueba
src/docu/index/manifest.py#L76-L76
76    docs: list[DocEntry] = field(default_factory=list)
Manifest.versionsMapping[str, str]
Ver prueba
src/docu/index/manifest.py#L77-L77
77    versions: Mapping[str, str] = field(default_factory=lambda: dict(DEFAULT_VERSIONS))
Manifest.schema_versionstr
Ver prueba
src/docu/index/manifest.py#L78-L78
78    schema_version: str = MANIFEST_VERSION
DetectedPackage.namestr
Ver prueba
src/docu/index/packages.py#L25-L25
25    name: str
DetectedPackage.languagestr
Ver prueba
src/docu/index/packages.py#L26-L26
26    language: str
DetectedPackage.filestuple[str, ...]
Ver prueba
src/docu/index/packages.py#L27-L27
27    files: tuple[str, ...]
DetectedPackage.declarationstr
Ver prueba
src/docu/index/packages.py#L28-L28
28    declaration: str  # ruta#L inicio-L fin de la declaración
PdfDocument.relstr
Ver prueba
src/docu/index/pdfdocs.py#L25-L25
25    rel: str
PdfDocument.pagesint
Ver prueba
src/docu/index/pdfdocs.py#L26-L26
26    pages: int
PdfDocument.charsint
Ver prueba
src/docu/index/pdfdocs.py#L27-L27
27    chars: int
PdfDocument.methodstr
Ver prueba
src/docu/index/pdfdocs.py#L28-L28
28    method: str
PdfDocument.statusstr
Ver prueba
src/docu/index/pdfdocs.py#L29-L29
29    status: str
PdfDocument.usablebool
Ver prueba
src/docu/index/pdfdocs.py#L30-L30
30    usable: bool
PdfDocument.warningstuple[str, ...]
Ver prueba
src/docu/index/pdfdocs.py#L31-L31
31    warnings: tuple[str, ...] = ()
WebDocument.urlstr
Ver prueba
src/docu/index/webdocs.py#L19-L19
19    url: str
WebDocument.relstr
Ver prueba
src/docu/index/webdocs.py#L20-L20
20    rel: str
WebDocument.shastr
Ver prueba
src/docu/index/webdocs.py#L21-L21
21    sha: str
WebDocument.captured_atstr
Ver prueba
src/docu/index/webdocs.py#L22-L22
22    captured_at: str
WebDocument.linesint
Ver prueba
src/docu/index/webdocs.py#L23-L23
23    lines: int
WebDocument.charsint
Ver prueba
src/docu/index/webdocs.py#L24-L24
24    chars: int
WebDocument.usablebool
Ver prueba
src/docu/index/webdocs.py#L25-L25
25    usable: bool
WebDocument.errorstr
Ver prueba
src/docu/index/webdocs.py#L26-L26
26    error: str = ""
FederationPayload.dataMapping[str, object]
Ver prueba
src/docu/learn/federation.py#L34-L34
34    data: Mapping[str, object]
Pattern.pattern_idstr
Ver prueba
src/docu/learn/patterns.py#L28-L28
28    pattern_id: str
Pattern.stackstr
Ver prueba
src/docu/learn/patterns.py#L29-L29
29    stack: str
Pattern.kindstr
Ver prueba
src/docu/learn/patterns.py#L30-L30
30    kind: str  # "profile_default" | "glossary_entry" | "failure_avoidance"
Pattern.metricsMapping[str, float]
Ver prueba
src/docu/learn/patterns.py#L31-L31
31    metrics: Mapping[str, float] = field(default_factory=dict)
Pattern.runsint
Ver prueba
src/docu/learn/patterns.py#L32-L32
32    runs: int = 0
Pattern.notesstr
Ver prueba
src/docu/learn/patterns.py#L33-L33
33    notes: str = ""
PatternLibrary.patternsdict[str, Pattern]
Ver prueba
src/docu/learn/patterns.py#L62-L62
62    patterns: dict[str, Pattern] = field(default_factory=dict)
PatternLibrary.historylist[dict[str, object]]
Ver prueba
src/docu/learn/patterns.py#L63-L63
63    history: list[dict[str, object]] = field(default_factory=list)
PatternLibrary.versionstr
Ver prueba
src/docu/learn/patterns.py#L64-L64
64    version: str = "0"
PatternLibrary.schema_versionstr
Ver prueba
src/docu/learn/patterns.py#L65-L65
65    schema_version: str = SCHEMA_VERSION
Candidate.patternPattern
Ver prueba
src/docu/learn/patterns.py#L159-L159
159    pattern: Pattern
Candidate.reasonsSequence[str]
Ver prueba
src/docu/learn/patterns.py#L160-L160
160    reasons: Sequence[str] = ()
Decision.actionstr
Ver prueba
src/docu/learn/promotion.py#L22-L22
22    action: str
Decision.pattern_idstr
Ver prueba
src/docu/learn/promotion.py#L23-L23
23    pattern_id: str
Decision.deltafloat
Ver prueba
src/docu/learn/promotion.py#L24-L24
24    delta: float
Decision.reasonsSequence[str]
Ver prueba
src/docu/learn/promotion.py#L25-L25
25    reasons: Sequence[str] = field(default_factory=tuple)
Page.namestr
Ver prueba
src/docu/publish/site.py#L125-L125
125    name: str
Page.titlestr
Ver prueba
src/docu/publish/site.py#L126-L126
126    title: str
Page.htmlstr
Ver prueba
src/docu/publish/site.py#L127-L127
127    html: str
CodeChunk.pathstr
Ver prueba
src/docu/retrieve/hybrid.py#L36-L36
36    path: str
CodeChunk.startint
Ver prueba
src/docu/retrieve/hybrid.py#L37-L37
37    start: int
CodeChunk.endint
Ver prueba
src/docu/retrieve/hybrid.py#L38-L38
38    end: int
CodeChunk.textstr
Ver prueba
src/docu/retrieve/hybrid.py#L39-L39
39    text: str
CodeChunk.symbolstr | None
Ver prueba
src/docu/retrieve/hybrid.py#L40-L40
40    symbol: str | None
CodeChunk.kindstr
Ver prueba
src/docu/retrieve/hybrid.py#L41-L41
41    kind: str
CodeChunk.tokenstuple[str, ...]
Ver prueba
src/docu/retrieve/hybrid.py#L42-L42
42    tokens: tuple[str, ...] = ()
CodeChunk.exact_namestuple[str, ...]
Ver prueba
src/docu/retrieve/hybrid.py#L43-L43
43    exact_names: tuple[str, ...] = ()
CodeIndex.chunkslist[CodeChunk]
Ver prueba
src/docu/retrieve/hybrid.py#L116-L116
116    chunks: list[CodeChunk] = field(default_factory=list)
CodeIndex.embedderobject | None
Ver prueba
src/docu/retrieve/hybrid.py#L117-L117
117    embedder: object | None = None
CodeIndex.glossaryMapping[str, Sequence[str]] | None
Ver prueba
src/docu/retrieve/hybrid.py#L118-L118
118    glossary: Mapping[str, Sequence[str]] | None = None
CodeIndex.k1float
Ver prueba
src/docu/retrieve/hybrid.py#L119-L119
119    k1: float = 1.5
CodeIndex.bfloat
Ver prueba
src/docu/retrieve/hybrid.py#L120-L120
120    b: float = 0.75
CodeIndex._dfdict[str, int]
Ver prueba
src/docu/retrieve/hybrid.py#L121-L121
121    _df: dict[str, int] = field(default_factory=dict, init=False, repr=False)
CodeIndex._lengthslist[int]
Ver prueba
src/docu/retrieve/hybrid.py#L122-L122
122    _lengths: list[int] = field(default_factory=list, init=False, repr=False)
CodeIndex._avgdlfloat
Ver prueba
src/docu/retrieve/hybrid.py#L123-L123
123    _avgdl: float = field(default=0.0, init=False, repr=False)
CodeIndex._by_namedict[str, list[CodeChunk]]
Ver prueba
src/docu/retrieve/hybrid.py#L124-L124
124    _by_name: dict[str, list[CodeChunk]] = field(default_factory=dict, init=False, repr=False)
CodeIndex._vectorslist[Sequence[float]]
Ver prueba
src/docu/retrieve/hybrid.py#L125-L125
125    _vectors: list[Sequence[float]] = field(default_factory=list, init=False, repr=False)
CodeIndex._dense_readybool
Ver prueba
src/docu/retrieve/hybrid.py#L126-L126
126    _dense_ready: bool = field(default=False, init=False, repr=False)
Section.documentstr
Ver prueba
src/docu/retrieve/search.py#L71-L71
71    document: str
Section.headingstr
Ver prueba
src/docu/retrieve/search.py#L72-L72
72    heading: str
Section.bodystr
Ver prueba
src/docu/retrieve/search.py#L73-L73
73    body: str
Section.levelstr
Ver prueba
src/docu/retrieve/search.py#L74-L74
74    level: str = ""
Section.tokenstuple[str, ...]
Ver prueba
src/docu/retrieve/search.py#L75-L75
75    tokens: tuple[str, ...] = ()
Section.citationstuple[str, ...]
Ver prueba
src/docu/retrieve/search.py#L76-L76
76    citations: tuple[str, ...] = ()
DocIndex.sectionslist[Section]
Ver prueba
src/docu/retrieve/search.py#L129-L129
129    sections: list[Section] = field(default_factory=list)
DocIndex.k1float
Ver prueba
src/docu/retrieve/search.py#L130-L130
130    k1: float = 1.5
DocIndex.bfloat
Ver prueba
src/docu/retrieve/search.py#L131-L131
131    b: float = 0.75
DocIndex.glossaryMapping[str, Sequence[str]] | None
Ver prueba
src/docu/retrieve/search.py#L132-L132
132    glossary: Mapping[str, Sequence[str]] | None = None
DocIndex._dfdict[str, int]
Ver prueba
src/docu/retrieve/search.py#L133-L133
133    _df: dict[str, int] = field(default_factory=dict, init=False)
DocIndex._avgdlfloat
Ver prueba
src/docu/retrieve/search.py#L134-L134
134    _avgdl: float = field(default=0.0, init=False)

Tipos 97

QuéDetalleEvidencia
Segmentclass
Ver prueba
eval/harness.py#L116-L129
Anotaciones: @dataclass
116class Segment:
117    """Unidad recuperable.
118
119    En modo `windows` es una ventana de lineas; en modo `symbols` es un chunk del chunker
120    sintactico de `docu`, con el nombre del simbolo como canal de coincidencia exacta.
121    """
122
123    path: str
124    start: int
125    end: int
126    text: str
127    tokens: tuple[str, ...] = ()
128    exact_names: tuple[str, ...] = ()
129    citation: str | None = None
BM25class
Ver prueba
eval/harness.py#L260-L302
Anotaciones: @dataclass
260class BM25:
261    """BM25 Okapi en stdlib. Canal lexico de ambos indices."""
262
263    k1: float = 1.5
264    b: float = 0.75
265    segments: Sequence[Segment] = ()
266    _df: dict[str, int] = field(default_factory=dict, init=False)
267    _lengths: list[int] = field(default_factory=list, init=False)
268    _avgdl: float = field(default=0.0, init=False)
269
270    def __post_init__(self) -> None:
271        for segment in self.segments:
272            self._lengths.append(len(segment.tokens))
273            for term in set(segment.tokens):
274                self._df[term] = self._df.get(term, 0) + 1
275        self._avgdl = (sum(self._lengths) / len(self._lengths)) if self._lengths else 0.0
276
277    def _idf(self, term: str) -> float:
278        n = len(self.segments)
279        df = self._df.get(term, 0)
280        return log(1 + (n - df + 0.5) / (df + 0.5))
281
282    def scores(self, query: str) -> list[float]:
283        terms = tokenize(query)
284        results: list[float] = []
285        for segment, length in zip(self.segments, self._lengths):
286            freq: dict[str, int] = {}
287            for token in segment.tokens:
288                freq[token] = freq.get(token, 0) + 1
289            score = 0.0
290            for term in set(terms):
291                tf = freq.get(term, 0)
292                if tf == 0:
293                    continue
294                denom = tf + self.k1 * (1 - self.b + self.b * (length / self._avgdl if self._avgdl else 1.0))
295                score += self._idf(term) * (tf * (self.k1 + 1)) / denom
296            results.append(score)
297        return results
298
299    def search(self, query: str, k: int = 10) -> list[tuple[Segment, float]]:
AutoIndexclass
Ver prueba
eval/harness.py#L429-L449
Anotaciones: @dataclass
429class AutoIndex:
430    """Indice de F2 con enrutado por tipo de consulta.
431
432    Medido: los identificadores tecleados a mano rinden mejor con el indice de simbolos
433    (1.000 vs 0.950) y las preguntas humanas rinden mejor con el hibrido (MRR 0.596 vs 0.518).
434    Enrutar es mas honesto que inventar un promedio que empeora ambos casos.
435    """
436
437    segments: Sequence[Segment]
438    embedder: object = None
439    _symbols: SymbolIndex = field(init=False, repr=False)
440    _hybrid: HybridIndex = field(init=False, repr=False)
441
442    def __post_init__(self) -> None:
443        self._symbols = SymbolIndex(segments=self.segments)
444        self._hybrid = HybridIndex(segments=self.segments, embedder=self.embedder)
445
446    def search(self, query: str, k: int = 10) -> list[tuple[Segment, float]]:
447        if _looks_like_identifier(query):
448            return self._symbols.search(query, k=k)
449        return self._hybrid.search(query, k=k)
HybridIndexclass
Ver prueba
eval/harness.py#L453-L534
Anotaciones: @dataclass
453class HybridIndex:
454    """Indice de F2: denso (multilingue) + lexico + coincidencia exacta de simbolo, fusionados.
455
456    La fusion RRF es lo que evita que un canal aplaste a los demas: cada canal aporta su
457    ranking, no su puntuacion, y las puntuaciones entre modelos no son comparables.
458    """
459
460    segments: Sequence[Segment]
461    embedder: object = None
462    k1: float = 1.5
463    b: float = 0.75
464    rrf_k: int = 60
465    max_exact_per_file: int = 2
466    max_per_file: int = 2
467    _bm25: BM25 = field(init=False, repr=False)
468    _by_name: dict[str, list[Segment]] = field(init=False, repr=False, default_factory=dict)
469    _vectors: list[list[float]] = field(init=False, repr=False, default_factory=list)
470
471    def __post_init__(self) -> None:
472        self._bm25 = BM25(k1=self.k1, b=self.b, segments=self.segments)
473        for segment in self.segments:
474            for name in segment.exact_names:
475                self._by_name.setdefault(name, []).append(segment)
476        if self.embedder is not None:
477            self._vectors = list(self.embedder.embed([segment.text for segment in self.segments]))
478
479    # ------------------------------------------------------------------ canales
480
481    def _dense_channel(self, query: str, limit: int) -> list[Segment]:
482        if not self._vectors:
483            return []
484        from docu.adapters.embedders.onnx_local import cosine
485
486        query_vector = self.embedder.embed([query])[0]  # type: ignore[union-attr]
487        scored = [
488            (segment, cosine(query_vector, vector))
489            for segment, vector in zip(self.segments, self._vectors)
490        ]
491        scored.sort(key=lambda item: item[1], reverse=True)
492        return [segment for segment, _score in scored[:limit]]
SymbolIndexclass
Ver prueba
eval/harness.py#L538-L594
Anotaciones: @dataclass
538class SymbolIndex:
539    """Indice de F1: fusiona el canal lexico con un canal de coincidencia exacta de simbolo.
540
541    Dos lecciones aprendidas midiendo:
542    - Un refuerzo aditivo no funciona: los archivos con mas vocabulario comun ganan.
543    - La prioridad absoluta tampoco: todos los chunks de un tipo coinciden y desplazan al
544      recurso no-Java (`.imports`, `pom.xml`, `application.yml`) que responde la pregunta.
545    Por eso se fusionan con RRF y el canal exacto se limita a dos chunks por archivo.
546    """
547
548    segments: Sequence[Segment]
549    k1: float = 1.5
550    b: float = 0.75
551    rrf_k: int = 60
552    max_exact_per_file: int = 2
553    max_per_file: int = 2
554    _bm25: BM25 = field(init=False, repr=False)
555    _by_name: dict[str, list[Segment]] = field(init=False, repr=False, default_factory=dict)
556
557    def __post_init__(self) -> None:
558        self._bm25 = BM25(k1=self.k1, b=self.b, segments=self.segments)
559        for segment in self.segments:
560            for name in segment.exact_names:
561                self._by_name.setdefault(name, []).append(segment)
562
563    def _exact_channel(self, terms: set[str]) -> list[Segment]:
564        hits: list[Segment] = []
565        seen: set[tuple[str, int, int]] = set()
566        per_file: dict[str, int] = {}
567        for term in sorted(terms):
568            for segment in self._by_name.get(term, ()):
569                key = (segment.path, segment.start, segment.end)
570                if key in seen:
571                    continue
572                if per_file.get(segment.path, 0) >= self.max_exact_per_file:
573                    continue
574                seen.add(key)
575                per_file[segment.path] = per_file.get(segment.path, 0) + 1
576                hits.append(segment)
577        return hits
Expectedclass
Ver prueba
eval/harness.py#L601-L605
Anotaciones: @dataclass
601class Expected:
602    path: str
603    symbol: str | None = None
604    lines: tuple[int, int] | None = None
605    optional: bool = False
Caseclass
Ver prueba
eval/harness.py#L609-L626
Anotaciones: @dataclass
609class Case:
610    id: str
611    category: str
612    question: str
613    expected: tuple[Expected, ...]
614    answer: str = ""
615    notes: str = ""
616    query: str = ""
617    """Consulta de recuperación (identificadores, inglés). Si falta, se usa `question`."""
618
619    @property
620    def required_paths(self) -> tuple[str, ...]:
621        return tuple(e.path for e in self.expected if not e.optional)
622
623    def retrieval_query(self, field: str = "auto") -> str:
624        if field == "question" or not self.query:
625            return self.question
626        return self.query
CaseResultclass
Ver prueba
eval/harness.py#L630-L641
Anotaciones: @dataclass
630class CaseResult:
631    case_id: str
632    category: str
633    recall: float
634    hit: bool
635    mrr: float
636    line_hit: bool | None
637    symbol_hit: bool | None
638    query_mode: str
639    passed: bool
640    retrieved: tuple[str, ...]
641    elapsed_ms: float
Reportclass
Ver prueba
eval/harness.py#L645-L776
Anotaciones: @dataclass
645class Report:
646    project: str
647    k: int
648    files: int
649    segments: int
650    results: list[CaseResult]
651    query_field: str = "auto"
652    index_mode: str = "windows"
653    query_expansion: bool = False
654    generated_at: str = ""
655    schema_version: str = SCHEMA_VERSION
656
657    def _agg(self, results: Sequence[CaseResult]) -> dict[str, float]:
658        if not results:
659            return {}
660        line_results = [r.line_hit for r in results if r.line_hit is not None]
661        symbol_results = [r.symbol_hit for r in results if r.symbol_hit is not None]
662        mode_results = [r.query_mode for r in results]
663        return {
664            "cases": len(results),
665            "recall": statistics.fmean(r.recall for r in results),
666            "hit_rate": sum(1 for r in results if r.hit) / len(results),
667            "mrr": statistics.fmean(r.mrr for r in results),
668            "line_accuracy": (sum(1 for x in line_results if x) / len(line_results)) if line_results else 0.0,
669            "symbol_rate": (sum(1 for x in symbol_results if x) / len(symbol_results)) if symbol_results else 0.0,
670            "mean_ms": statistics.fmean(r.elapsed_ms for r in results),
671            "mode_distribution": {m: mode_results.count(m) for m in set(mode_results)},
672        }
673
674    @property
675    def overall(self) -> dict[str, float]:
676        return self._agg(self.results)
677
678    def by_category(self) -> dict[str, dict[str, float]]:
679        categories = sorted({r.category for r in self.results})
680        return {cat: self._agg([r for r in self.results if r.category == cat]) for cat in categories}
681
682    def by_mode(self) -> dict[str, dict[str, float]]:
683        """Devuelve el _agg de cada modo de consulta para ver umbrales por separado."""
684        modes = sorted({r.query_mode for r in self.results})
OnnxEmbedderclass
Ver prueba
src/docu/adapters/embedders/onnx_local.py#L40-L104
Anotaciones: @dataclass
40class OnnxEmbedder:
41    """Implementa el puerto `Embedder`. Carga perezosa: importar el modulo no exige onnxruntime."""
42
43    model_dir: Path | str = DEFAULT_MODEL_DIR
44    embedder_id: str = DEFAULT_EMBEDDER_ID
45    max_length: int = 256
46    batch_size: int = 16
47    _session: object | None = None
48    _tokenizer: object | None = None
49    _input_names: tuple[str, ...] = ()
50    _dim: int = 384
51
52    @property
53    def dim(self) -> int:
54        return self._dim
55
56    @property
57    def available(self) -> bool:
58        return (Path(self.model_dir) / "model.onnx").exists() and (
59            Path(self.model_dir) / "tokenizer.json"
60        ).exists()
61
62    def _load(self) -> None:
63        if self._session is not None:
64            return
65        if not self.available:
66            raise FileNotFoundError(
67                f"modelo ONNX no encontrado en {self.model_dir!r}; descarga tokenizer.json y model.onnx"
68            )
69        import onnxruntime as ort
70        from tokenizers import Tokenizer
71
72        directory = Path(self.model_dir)
73        tokenizer = Tokenizer.from_file(str(directory / "tokenizer.json"))
74        tokenizer.enable_truncation(max_length=self.max_length)
75        tokenizer.enable_padding(pad_id=0, pad_token="[PAD]")
76        options = ort.SessionOptions()
77        options.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL
78        session = ort.InferenceSession(
79            str(directory / "model.onnx"), options, providers=["CPUExecutionProvider"]
Linesclass
Ver prueba
src/docu/adapters/langs/_braces.py#L233-L250
233class Lines:
234    """Conversion offsets <-> numeros de linea (1-based)."""
235
236    def __init__(self, source: str) -> None:
237        self.starts = [0]
238        for index, ch in enumerate(source):
239            if ch == "\n":
240                self.starts.append(index + 1)
241
242    def line_of(self, offset: int) -> int:
243        low, high = 0, len(self.starts) - 1
244        while low < high:
245            mid = (low + high + 1) // 2
246            if self.starts[mid] <= offset:
247                low = mid
248            else:
249                high = mid - 1
250        return low + 1
_Linesclass
Ver prueba
src/docu/adapters/langs/java.py#L144-L161
144class _Lines:
145    """Conversion offsets <-> numeros de linea (1-based)."""
146
147    def __init__(self, source: str) -> None:
148        self.starts = [0]
149        for index, ch in enumerate(source):
150            if ch == "\n":
151                self.starts.append(index + 1)
152
153    def line_of(self, offset: int) -> int:
154        low, high = 0, len(self.starts) - 1
155        while low < high:
156            mid = (low + high + 1) // 2
157            if self.starts[mid] <= offset:
158                low = mid
159            else:
160                high = mid - 1
161        return low + 1
JavaLangAdapterclass
Ver prueba
src/docu/adapters/langs/java.py#L366-L590
Anotaciones: @dataclass
366class JavaLangAdapter:
367    """`LangAdapter` de referencia. Sin estado: seguro para procesar archivos en paralelo."""
368
369    language: str = "java"
370    file_globs: tuple[str, ...] = ("*.java",)
371
372    # ------------------------------------------------------------------ simbolos
373
374    def symbols(self, path: str, source: str) -> tuple[Symbol, ...]:
375        masked = mask_annotation_braces(mask_source(source))
376        depth = depth_map(masked)
377        lines = _Lines(source)
378        routes: list[Symbol] = []
379        types: list[tuple[Symbol, int, int]] = []  # (simbolo, offset inicio, offset fin)
380        previous_end = 0
381
382        for match in _TYPE_RE.finditer(masked):
383            keyword, name = match.group(1), match.group(2)
384            if masked[max(0, match.start() - 1)] == ".":
385                continue  # `Foo.class` no es una declaracion
386            open_brace = masked.find("{", match.end())
387            if open_brace == -1:
388                continue
389            close_brace = matching_brace(masked, open_brace)
390            level = depth[open_brace]
391            decl_start = _declaration_start(masked, depth, match.start(), 0, level)
392            annotation_text, annotation_offset = _annotation_block(source, previous_end, match.start())
393            annotations = annotation_names(annotation_text)
394            base_route = class_level_route(annotation_text)
395            type_line = lines.line_of(decl_start)
396            if annotation_text:
397                type_line = min(type_line, lines.line_of(annotation_offset))
398            previous_end = close_brace + 1
399
400            children, member_routes = self._members(
401                path=path,
402                source=source,
403                masked=masked,
404                depth=depth,
405                lines=lines,
PythonLangAdapterclass
Ver prueba
src/docu/adapters/langs/python.py#L19-L200
Anotaciones: @dataclass
19class PythonLangAdapter:
20    """`LangAdapter` para Python. Devuelve `()` ante codigo invalido en lugar de reventar."""
21
22    language: str = "python"
23    file_globs: tuple[str, ...] = ("*.py",)
24
25    # ------------------------------------------------------------------ simbolos
26
27    def symbols(self, path: str, source: str) -> tuple[Symbol, ...]:
28        try:
29            tree = ast.parse(source)
30        except SyntaxError:
31            return ()
32
33        found: list[Symbol] = []
34        for node in tree.body:
35            symbol = self._module_member(path, node, container=None)
36            if symbol is not None:
37                found.append(symbol)
38            found.extend(self._routes(path, node, container=None))
39        return tuple(found)
40
41    def _module_member(
42        self, path: str, node: ast.AST, container: str | None
43    ) -> Symbol | None:
44        if isinstance(node, ast.ClassDef):
45            children = tuple(
46                child
47                for child in (
48                    self._module_member(path, item, container=node.name) for item in node.body
49                )
50                if child is not None
51            )
52            fields = tuple(
53                field
54                for field in (
55                    self._class_field(path, item, container=node.name) for item in node.body
56                )
57                if field is not None
58            )
TypeScriptLangAdapterclass
Ver prueba
src/docu/adapters/langs/typescript.py#L87-L423
Anotaciones: @dataclass
87class TypeScriptLangAdapter:
88    language: str = "typescript"
89    file_globs: tuple[str, ...] = ("*.ts", "*.tsx", "*.js", "*.jsx", "*.mjs", "*.cjs")
90
91    # ------------------------------------------------------------------ simbolos
92
93    def symbols(self, path: str, source: str) -> tuple[Symbol, ...]:
94        masked = mask_annotation_braces(mask_source(source))
95        depth = depth_map(masked)
96        lines = Lines(source)
97        found: list[Symbol] = []
98        previous_end = 0
99
100        for match in _TYPE_RE.finditer(masked):
101            open_brace = masked.find("{", match.end())
102            if open_brace == -1:
103                continue
104            close_brace = matching_brace(masked, open_brace)
105            level = depth[open_brace]
106            decl_start = declaration_start(masked, depth, match.start(), 0, level)
107            kind = {
108                "class": SymbolKind.CLASS,
109                "interface": SymbolKind.INTERFACE,
110                "enum": SymbolKind.ENUM,
111            }[match.group(1)]
112            annotation_text, annotation_offset = _annotation_block(source, previous_end, match.start())
113            annotations = _decorators_in(annotation_text)
114            previous_end = close_brace + 1
115            type_line = lines.line_of(decl_start)
116            if annotation_text:
117                type_line = min(type_line, lines.line_of(annotation_offset))
118
119            children, routes = self._members(
120                path=path,
121                source=source,
122                masked=masked,
123                depth=depth,
124                lines=lines,
125                level=level + 1,
126                open_brace=open_brace,
PdfErrorclass
Ver prueba
src/docu/adapters/sources/pdf.py#L36-L37
36class PdfError(ValueError):
37    """El archivo no es un PDF legible por este extractor."""
PdfPageclass
Ver prueba
src/docu/adapters/sources/pdf.py#L119-L121
Anotaciones: @dataclass
119class PdfPage:
120    number: int
121    text: str
PdfTextclass
Ver prueba
src/docu/adapters/sources/pdf.py#L125-L145
Anotaciones: @dataclass
125class PdfText:
126    pages: tuple[PdfPage, ...] = ()
127    total_pages: int = 0
128    chars: int = 0
129    method: str = "desconocido"
130    warnings: tuple[str, ...] = field(default_factory=tuple)
131
132    @property
133    def usable(self) -> bool:
134        """¿Hay texto suficiente para citar algo, o es un PDF escaneado?"""
135        if self.total_pages <= 0:
136            return False
137        return self.chars >= MIN_CHARS_PER_PAGE * self.total_pages
138
139    @property
140    def status(self) -> str:
141        if self.usable:
142            return "texto extraído"
143        if self.total_pages and self.chars:
144            return "texto insuficiente (posible PDF escaneado o con codificación no soportada)"
145        return "sin texto extraíble (PDF escaneado, cifrado o corrupto)"
WebErrorclass
Ver prueba
src/docu/adapters/sources/web.py#L38-L39
38class WebError(ValueError):
39    """La fuente web no se pudo capturar con las garantías exigidas."""
Snapshotclass
Ver prueba
src/docu/adapters/sources/web.py#L43-L62
Anotaciones: @dataclass
43class Snapshot:
44    url: str
45    text: str
46    sha: str
47    captured_at: str
48    status_code: int = 200
49
50    @property
51    def lines(self) -> int:
52        return len(self.text.splitlines())
53
54    @property
55    def usable(self) -> bool:
56        return len(self.text.strip()) >= MIN_TEXT_CHARS
57
58    @property
59    def slug(self) -> str:
60        parsed = urlparse(self.url)
61        base = re.sub(r"[^a-z0-9]+", "-", (parsed.netloc + parsed.path).lower()).strip("-")
62        return (base or "pagina")[:80]
_TextExtractorclass
Ver prueba
src/docu/adapters/sources/web.py#L65-L101
65class _TextExtractor(HTMLParser):
66    """HTML → texto con saltos en los límites de bloque, sin dependencias."""
67
68    def __init__(self) -> None:
69        super().__init__(convert_charrefs=True)
70        self._parts: list[str] = []
71        self._skip_depth = 0
72
73    def handle_starttag(self, tag: str, attrs) -> None:
74        if tag in SKIP_TAGS:
75            self._skip_depth += 1
76            return
77        if tag in BLOCK_TAGS:
78            self._parts.append("\n")
79
80    def handle_endtag(self, tag: str) -> None:
81        if tag in SKIP_TAGS and self._skip_depth:
82            self._skip_depth -= 1
83            return
84        if tag in BLOCK_TAGS:
85            self._parts.append("\n")
86
87    def handle_data(self, data: str) -> None:
88        if self._skip_depth:
89            return
90        self._parts.append(data)
91
92    def text(self) -> str:
93        raw = "".join(self._parts)
94        lines = [" ".join(line.split()) for line in raw.splitlines()]
95        compact = [line for line in lines if line]
96        deduped: list[str] = []
97        for line in compact:
98            if deduped and deduped[-1] == line:
99                continue  # menús y cabeceras repetidas: ruido, no contenido
100            deduped.append(line)
101        return "\n".join(deduped)
Checkclass
Ver prueba
src/docu/audit/verify.py#L40-L68
Anotaciones: @dataclass
40class Check:
41    """Resultado de una comprobación."""
42
43    name: str
44    total: int
45    failed: int
46    details: tuple[str, ...] = ()
47    note: str = ""
48
49    @property
50    def passed(self) -> bool:
51        return self.failed == 0
52
53    @property
54    def score(self) -> float:
55        if self.total == 0:
56            return 0.0 if self.failed else 100.0
57        return 100.0 * (self.total - self.failed) / self.total
58
59    def to_dict(self) -> dict[str, object]:
60        return {
61            "check": self.name,
62            "total": self.total,
63            "failed": self.failed,
64            "passed": self.passed,
65            "score": round(self.score, 2),
66            "note": self.note,
67            "details": list(self.details),
68        }
AuditReportclass
Ver prueba
src/docu/audit/verify.py#L72-L143
Anotaciones: @dataclass
72class AuditReport:
73    project: str
74    checks: dict[str, Check] = field(default_factory=dict)
75    #: Total de afirmaciones del documento y desglose de las que esta auditoría no mira.
76    facts_total: int = 0
77    excluded: dict[str, int] = field(default_factory=dict)
78
79    @property
80    def score(self) -> float:
81        total = sum(WEIGHTS[name] for name in self.checks)
82        if not total:
83            return 0.0
84        return round(
85            sum(WEIGHTS[name] * check.score for name, check in self.checks.items()) / total, 2
86        )
87
88    @property
89    def passed(self) -> bool:
90        return all(check.passed for check in self.checks.values())
91
92    def to_dict(self) -> dict[str, object]:
93        return {
94            "schema_version": "1.0",
95            "project": self.project,
96            "score": self.score,
97            "passed": self.passed,
98            "weights": WEIGHTS,
99            "facts_total": self.facts_total,
100            "excluded": self.excluded,
101            "checks": {name: check.to_dict() for name, check in self.checks.items()},
102        }
103
104    def _reconciliation(self) -> str:
105        """Una sola cifra para el mismo universo: total, auditadas y excluidas con su motivo."""
106        audited = max((check.total for check in self.checks.values()), default=0)
107        if not self.facts_total:
108            return f"Afirmaciones auditadas: **{audited}**"
109        excluded = sum(self.excluded.values())
110        detail = " · ".join(f"{kind} {count}" for kind, count in sorted(self.excluded.items()))
111        suffix = f" ({detail})" if detail else ""
Discrepancyclass
Ver prueba
src/docu/conformance/drift.py#L38-L62
Anotaciones: @dataclass
38class Discrepancy:
39    kind: str
40    subject: str
41    detail: str
42    code_citation: str | None = None
43    declaration_source: str | None = None
44
45    @property
46    def severity(self) -> str:
47        return SEVERITY.get(self.kind, "warning")
48
49    @property
50    def action(self) -> str:
51        return ACTION.get(self.kind, "revisar")
52
53    def to_dict(self) -> dict[str, object]:
54        return {
55            "kind": self.kind,
56            "severity": self.severity,
57            "subject": self.subject,
58            "detail": self.detail,
59            "code_citation": self.code_citation,
60            "declaration_source": self.declaration_source,
61            "action": self.action,
62        }
DriftReportclass
Ver prueba
src/docu/conformance/drift.py#L66-L118
Anotaciones: @dataclass
66class DriftReport:
67    model: ArchitectureModel
68    discrepancies: list[Discrepancy] = field(default_factory=list)
69    routes_in_code: int = 0
70    components_in_code: int = 0
71
72    @property
73    def errors(self) -> list[Discrepancy]:
74        return [item for item in self.discrepancies if item.severity == "error"]
75
76    @property
77    def warnings(self) -> list[Discrepancy]:
78        return [item for item in self.discrepancies if item.severity != "error"]
79
80    @property
81    def is_clean(self) -> bool:
82        return not self.discrepancies
83
84    def to_dict(self) -> dict[str, object]:
85        return {
86            "schema_version": "1.0",
87            "sources": list(self.model.sources),
88            "routes_in_code": self.routes_in_code,
89            "components_in_code": self.components_in_code,
90            "errors": len(self.errors),
91            "warnings": len(self.warnings),
92            "discrepancies": [item.to_dict() for item in self.discrepancies],
93        }
94
95    def to_markdown(self) -> str:
96        lines = [
97            "# Deriva arquitectónica",
98            "",
99            (f"Modelo declarado: {', '.join(self.model.sources) or '—'} · "
100            f"rutas en código: {self.routes_in_code} · componentes en código: {self.components_in_code}"),
101            "",
102        ]
103        if self.is_clean:
104            lines.append("Sin discrepancias: el código implementa lo declarado.")
105            return "\n".join(lines) + "\n"
RouteFactclass
Ver prueba
src/docu/conformance/drift.py#L125-L130
Anotaciones: @dataclass
125class RouteFact:
126    """Ruta encontrada en el codigo, con su cita y el simbolo que la implementa."""
127
128    key: str
129    citation: str
130    handler: str
CodeFactsclass
Ver prueba
src/docu/conformance/drift.py#L134-L137
Anotaciones: @dataclass
134class CodeFacts:
135    routes: tuple[RouteFact, ...]
136    components: Mapping[str, str]  # nombre de tipo -> cita
137    dependencies: tuple[tuple[str, str], ...]  # (llamador, llamado)
Routeclass
Ver prueba
src/docu/conformance/model.py#L31-L40
Anotaciones: @dataclass
31class Route:
32    verb: str
33    path: str
34
35    @property
36    def key(self) -> str:
37        return f"{self.verb.upper()} {self.path}"
38
39    def __str__(self) -> str:
40        return self.key
DeclaredComponentclass
Ver prueba
src/docu/conformance/model.py#L44-L49
Anotaciones: @dataclass
44class DeclaredComponent:
45    name: str
46    kind: str = "component"
47    provides: tuple[Route, ...] = ()
48    depends_on: tuple[str, ...] = ()
49    source: str = ""
ArchitectureModelclass
Ver prueba
src/docu/conformance/model.py#L53-L79
Anotaciones: @dataclass
53class ArchitectureModel:
54    components: tuple[DeclaredComponent, ...] = ()
55    routes: tuple[Route, ...] = ()
56    sources: tuple[str, ...] = ()
57    schema_version: str = "1.0"
58
59    @property
60    def component_names(self) -> set[str]:
61        return {component.name for component in self.components}
62
63    @property
64    def declared_routes(self) -> set[str]:
65        returns = {route.key for route in self.routes}
66        for component in self.components:
67            returns.update(route.key for route in component.provides)
68        return returns
69
70    def declared_dependencies(self) -> set[tuple[str, str]]:
71        return {
72            (component.name, dependency)
73            for component in self.components
74            for dependency in component.depends_on
75        }
76
77    @property
78    def is_empty(self) -> bool:
79        return not self.components and not self.routes
SourceKindclass
Ver prueba
src/docu/core/contracts.py#L36-L43
36class SourceKind(str, Enum):
37    GIT_REPOSITORY = "git_repository"
38    PDF = "pdf"
39    WEB = "web"
40    OPENAPI = "openapi"
41    SQL = "sql"
42    IAC = "iac"
43    ADR = "adr"
SymbolKindclass
Ver prueba
src/docu/core/contracts.py#L46-L58
46class SymbolKind(str, Enum):
47    MODULE = "module"
48    CLASS = "class"
49    INTERFACE = "interface"
50    ENUM = "enum"
51    FUNCTION = "function"
52    METHOD = "method"
53    CONSTRUCTOR = "constructor"
54    FIELD = "field"
55    HTTP_ROUTE = "http_route"
56    SQL_TABLE = "sql_table"
57    CONFIG_KEY = "config_key"
58    UNKNOWN = "unknown"
DocStateclass
Ver prueba
src/docu/core/contracts.py#L61-L69
61class DocState(str, Enum):
62    """Frescura de una pagina (Guia-v2.md §7)."""
63
64    FRESH = "fresh"
65    STALE = "stale"
66    EXPIRED = "expired"
67    #: El manifest declara la página pero el archivo no está en disco. No es «fresco» ni «viejo»:
68    #: es inexistente, y confundirlo con frescura es un éxito silencioso.
69    MISSING = "missing"
Modeclass
Ver prueba
src/docu/core/contracts.py#L72-L77
72class Mode(str, Enum):
73    """Grado de autonomia (Guia-v2.md §7)."""
74
75    PROPOSE = "propose"
76    APPLY = "apply"
77    PUBLISH = "publish"
GateOutcomeclass
Ver prueba
src/docu/core/contracts.py#L80-L85
80class GateOutcome(str, Enum):
81    """Resultado de evaluar las compuertas de calidad."""
82
83    PUBLISH = "publish"
84    REVIEW = "review"
85    ABORT = "abort"
Artifactclass
Ver prueba
src/docu/core/contracts.py#L92-L115
Anotaciones: @dataclass
92class Artifact:
93    """Unidad de entrada tal como la entrega un `SourceAdapter`.
94
95    `snapshot_path` es obligatorio para fuentes volatiles (web, PDF remoto): sin snapshot
96    no hay reproducibilidad y, por tanto, la fuente no es citable.
97    """
98
99    artifact_id: str
100    kind: SourceKind
101    uri: str
102    content_hash: str
103    captured_at: datetime
104    lang: str | None = None
105    snapshot_path: str | None = None
106    metadata: Mapping[str, Any] = field(default_factory=dict)
107    schema_version: str = SCHEMA_VERSION
108
109    def __post_init__(self) -> None:
110        if not self.artifact_id:
111            raise ValueError("artifact_id vacio")
112        if self.kind in (SourceKind.WEB, SourceKind.PDF) and not self.snapshot_path:
113            raise ValueError(
114                f"fuente volatil {self.uri!r} requiere snapshot_path: sin snapshot no es citable"
115            )
Symbolclass
Ver prueba
src/docu/core/contracts.py#L119-L135
Anotaciones: @dataclass
119class Symbol:
120    """Simbolo extraido del codigo por un `LangAdapter`."""
121
122    name: str
123    qualname: str
124    kind: SymbolKind
125    path: str
126    line_start: int
127    line_end: int
128    signature: str | None = None
129    children: Sequence[Symbol] = ()
130    annotations: Sequence[str] = ()
131    schema_version: str = SCHEMA_VERSION
132
133    @property
134    def is_container(self) -> bool:
135        return self.kind in (SymbolKind.CLASS, SymbolKind.INTERFACE, SymbolKind.ENUM, SymbolKind.MODULE)
Chunkclass
Ver prueba
src/docu/core/contracts.py#L142-L197
Anotaciones: @dataclass
142class Chunk:
143    """Bloque indexado. El prefijo es obligatorio: es la senal de contexto que usa el modelo."""
144
145    chunk_id: str
146    artifact_id: str
147    source_type: SourceKind
148    content: str
149    content_prefix: str
150    content_hash: str
151    file_path: str
152    lang: str | None
153    enclosing_symbol: str | None
154    symbol_kind: SymbolKind
155    line_start: int
156    line_end: int
157    ingested_at: datetime
158    repo: str | None = None
159    commit: str | None = None
160    dependencies: Sequence[str] = ()
161    embed_model: str | None = None
162    chunker: str = "ast-v2"
163    schema_version: str = SCHEMA_VERSION
164
165    def __post_init__(self) -> None:
166        if not self.content_prefix:
167            raise ValueError("content_prefix vacio: rompe la trazabilidad contextual")
168        if self.line_start < 1 or self.line_end < self.line_start:
169            raise ValueError(f"rango de lineas invalido: {self.line_start}-{self.line_end}")
170
171    @property
172    def citation(self) -> str:
173        """Referencia humana y estable para insertar en el documento."""
174        return f"{self.file_path}#L{self.line_start}-L{self.line_end}"
175
176    def to_record(self) -> dict[str, Any]:
177        """Forma plana para el vector store."""
178        return {
179            "chunk_id": self.chunk_id,
180            "artifact_id": self.artifact_id,
181            "source_type": self.source_type.value,
Claimclass
Ver prueba
src/docu/core/contracts.py#L204-L215
Anotaciones: @dataclass
204class Claim:
205    """Una afirmacion del documento y las evidencias que la sostienen.
206
207    Invariante del producto: un `Claim` sin `evidence` no puede publicarse (Guia-v2.md §3.5).
208    """
209
210    text: str
211    evidence: Sequence[str] = ()
212
213    @property
214    def verified(self) -> bool:
215        return len(self.evidence) > 0
ContentNodeclass
Ver prueba
src/docu/core/contracts.py#L219-L241
Anotaciones: @dataclass
219class ContentNode:
220    """Nodo del grafo de contenido: **fuente unica de verdad** de los cuatro niveles.
221
222    Un hecho (p. ej. el puerto 8080) existe aqui una sola vez y se renderiza con distinta
223    profundidad; nunca se reescribe por nivel.
224    """
225
226    node_id: str
227    kind: str
228    title: str
229    claims: list[Claim] = field(default_factory=list)
230    levels: tuple[str, ...] = ("l1",)
231    state: DocState = DocState.FRESH
232    confidence: float = 0.0
233    rendered: dict[str, str] = field(default_factory=dict)
234    schema_version: str = SCHEMA_VERSION
235
236    @property
237    def unsupported(self) -> list[Claim]:
238        return [c for c in self.claims if not c.verified]
239
240    def is_publishable(self) -> bool:
241        return not self.unsupported and self.state is DocState.FRESH
Metricsclass
Ver prueba
src/docu/core/contracts.py#L248-L258
Anotaciones: @dataclass
248class Metrics:
249    """Las seis metricas del producto (Guia-v2.md §5). Escala 1-10 salvo las indicadas."""
250
251    accuracy: float
252    completeness: float
253    attribution: float
254    conciseness: float
255    freshness: float = 10.0
256    cost_usd: float = 0.0
257    unsupported_claims: int = 0
258    schema_version: str = SCHEMA_VERSION
GateDecisionclass
Ver prueba
src/docu/core/contracts.py#L262-L275
Anotaciones: @dataclass
262class GateDecision:
263    """Salida de `policy.evaluate`: la unica forma en que el agente decide publicar."""
264
265    outcome: GateOutcome
266    reasons: tuple[str, ...] = ()
267
268    @property
269    def may_write(self) -> bool:
270        """PROPOSE nunca escribe; REVIEW escribe en rama y abre PR; PUBLISH publica."""
271        return self.outcome is not GateOutcome.ABORT
272
273    def describe(self) -> str:
274        head = self.outcome.value.upper()
275        return f"{head}: " + "; ".join(self.reasons) if self.reasons else head
RunRecordclass
Ver prueba
src/docu/core/contracts.py#L282-L326
Anotaciones: @dataclass
282class RunRecord:
283    """Una fila del ledger local (`.docu/ledger.jsonl`). Base del aprendizaje."""
284
285    run_id: str
286    project: str
287    commit: str | None
288    mode: Mode
289    started_at: datetime
290    finished_at: datetime | None = None
291    versions: dict[str, str] = field(default_factory=dict)
292    metrics: Metrics | None = None
293    gate: GateDecision | None = None
294    pages_written: int = 0
295    pages_skipped: int = 0
296    cost_usd: float = 0.0
297    errors: list[str] = field(default_factory=list)
298    schema_version: str = SCHEMA_VERSION
299
300    @property
301    def duration_s(self) -> float | None:
302        if self.finished_at is None:
303            return None
304        return (self.finished_at - self.started_at).total_seconds()
305
306    def to_jsonl(self) -> str:
307        payload = {
308            "run_id": self.run_id,
309            "project": self.project,
310            "commit": self.commit,
311            "mode": self.mode.value,
312            "started_at": self.started_at.isoformat(),
313            "finished_at": self.finished_at.isoformat() if self.finished_at else None,
314            "duration_s": self.duration_s,
315            "versions": self.versions,
316            "metrics": asdict(self.metrics) if self.metrics else None,
317            "gate": {"outcome": self.gate.outcome.value, "reasons": list(self.gate.reasons)}
318            if self.gate
319            else None,
320            "pages_written": self.pages_written,
321            "pages_skipped": self.pages_skipped,
FreshnessRecordclass
Ver prueba
src/docu/core/contracts.py#L333-L345
Anotaciones: @dataclass
333class FreshnessRecord:
334    """Estado de frescura de una pagina (Guia-v2.md §7)."""
335
336    node_id: str
337    input_hash: str
338    state: DocState
339    generated_at: datetime
340    ttl_days: int = 90
341    schema_version: str = SCHEMA_VERSION
342
343    def is_expired(self, now: datetime | None = None) -> bool:
344        moment = now or utcnow()
345        return moment - self.generated_at > timedelta(days=self.ttl_days)
BudgetExhaustedclass
Ver prueba
src/docu/core/policy.py#L15-L16
15class BudgetExhausted(RuntimeError):
16    """Se agoto un presupuesto: la corrida entrega lo completo y deja `pending`, no texto degradado."""
Thresholdsclass
Ver prueba
src/docu/core/policy.py#L20-L34
Anotaciones: @dataclass
20class Thresholds:
21    """Umbrales **por metrica**. Un unico umbral para cuatro metricas distintas es un error de diseno."""
22
23    accuracy: float = 8.5
24    completeness: float = 9.0
25    attribution: float = 9.5
26    conciseness: float = 7.5
27
28    def as_mapping(self) -> Mapping[str, float]:
29        return {
30            "accuracy": self.accuracy,
31            "completeness": self.completeness,
32            "attribution": self.attribution,
33            "conciseness": self.conciseness,
34        }
Budgetclass
Ver prueba
src/docu/core/policy.py#L38-L72
Anotaciones: @dataclass
38class Budget:
39    """Presupuesto por corrida. `spend()` lanza cuando se agota: fallar rapido y limpio."""
40
41    max_cost_usd: float = 3.0
42    max_seconds: float = 900.0
43    max_pages: int = 40
44    max_llm_calls: int = 120
45    spent_usd: float = 0.0
46    elapsed_s: float = 0.0
47    pages_written: int = 0
48    llm_calls: int = 0
49
50    def spend(self, *, usd: float = 0.0, seconds: float = 0.0, pages: int = 0, calls: int = 0) -> None:
51        self.spent_usd += usd
52        self.elapsed_s += seconds
53        self.pages_written += pages
54        self.llm_calls += calls
55        if self.exceeded():
56            raise BudgetExhausted("; ".join(self.exceeded()))
57
58    def exceeded(self) -> list[str]:
59        problems: list[str] = []
60        if self.spent_usd > self.max_cost_usd:
61            problems.append(f"coste {self.spent_usd:.2f} > {self.max_cost_usd:.2f} USD")
62        if self.elapsed_s > self.max_seconds:
63            problems.append(f"tiempo {self.elapsed_s:.0f}s > {self.max_seconds:.0f}s")
64        if self.pages_written > self.max_pages:
65            problems.append(f"paginas {self.pages_written} > {self.max_pages}")
66        if self.llm_calls > self.max_llm_calls:
67            problems.append(f"llamadas {self.llm_calls} > {self.max_llm_calls}")
68        return problems
69
70    @property
71    def remaining_usd(self) -> float:
72        return max(0.0, self.max_cost_usd - self.spent_usd)
GatePolicyclass
Ver prueba
src/docu/core/policy.py#L76-L104
Anotaciones: @dataclass
76class GatePolicy:
77    """Reglas de aprobacion. Las puertas duras no se negocian por metrica."""
78
79    thresholds: Thresholds = field(default_factory=Thresholds)
80    require_zero_unsupported: bool = True
81    require_fresh: bool = True
82
83    def evaluate(self, metrics: Metrics, mode: Mode) -> GateDecision:
84        reasons: list[str] = []
85
86        # Puertas duras: cualquier violacion aborta la publicacion (no la corrida).
87        if self.require_zero_unsupported and metrics.unsupported_claims > 0:
88            reasons.append(f"{metrics.unsupported_claims} afirmaciones sin evidencia")
89        if self.require_fresh and metrics.freshness < 10.0:
90            reasons.append(f"frescura {metrics.freshness:.1f}/10")
91
92        # Puertas de umbral: por debajo se abre revision, no se publica.
93        for name, floor in self.thresholds.as_mapping().items():
94            value = getattr(metrics, name)
95            if value < floor:
96                reasons.append(f"{name} {value:.1f} < {floor:.1f}")
97
98        if mode is Mode.PROPOSE:
99            return GateDecision(GateOutcome.REVIEW, tuple(reasons) or ("modo propose: revisar diff",))
100        if reasons:
101            hard = self.require_zero_unsupported and metrics.unsupported_claims > 0
102            hard = hard or (self.require_fresh and metrics.freshness < 10.0)
103            return GateDecision(GateOutcome.ABORT if hard else GateOutcome.REVIEW, tuple(reasons))
104        return GateDecision(GateOutcome.PUBLISH, ())
SourceAdapterclass
Ver prueba
src/docu/core/ports.py#L18-L28
Anotaciones: @runtime_checkable
18class SourceAdapter(Protocol):
19    """Trae artefactos de una fuente (git, pdf, web, openapi, sql, iac)."""
20
21    name: str
22    kind: type
23
24    def discover(self, root: str, include: Sequence[str], exclude: Sequence[str]) -> Iterable[Artifact]:
25        ...
26
27    def read(self, artifact: Artifact) -> str | bytes:
28        ...
LangAdapterclass
Ver prueba
src/docu/core/ports.py#L32-L52
Anotaciones: @runtime_checkable
32class LangAdapter(Protocol):
33    """Extrae estructura de codigo. Uno por lenguaje; ningun `if lang ==` en el nucleo.
34
35    Debe pasar `tests/conformance_langs/` sin tocar `core/`.
36    """
37
38    language: str
39    file_globs: Sequence[str]
40
41    def symbols(self, path: str, source: str) -> Sequence[Symbol]:
42        ...
43
44    def imports(self, path: str, source: str) -> Sequence[str]:
45        ...
46
47    def calls(self, path: str, source: str) -> Sequence[tuple[str, str]]:
48        """Aristas (llamador, llamado) solo cuando son **estaticamente verificables**.
49
50        El despacho dinamico no se inventa: se omite o se marca con confianza baja.
51        """
52        ...
Chunkerclass
Ver prueba
src/docu/core/ports.py#L56-L62
Anotaciones: @runtime_checkable
56class Chunker(Protocol):
57    """Segmentacion sintactica: un simbolo por chunk cuando cabe; nunca corte por tamano ciego."""
58
59    name: str
60
61    def chunk(self, artifact: Artifact, symbols: Sequence[Symbol], source: str) -> Sequence[Chunk]:
62        ...
Embedderclass
Ver prueba
src/docu/core/ports.py#L69-L76
Anotaciones: @runtime_checkable
69class Embedder(Protocol):
70    """Embeddings intercambiables. `embedder_id` incluye modelo y dimension: entra en el hash."""
71
72    embedder_id: str
73    dim: int
74
75    def embed(self, texts: Sequence[str]) -> Sequence[Sequence[float]]:
76        ...
VectorStoreclass
Ver prueba
src/docu/core/ports.py#L80-L94
Anotaciones: @runtime_checkable
80class VectorStore(Protocol):
81    """Almacen vectorial detras de un puerto: Chroma hoy, pgvector o Qdrant mañana."""
82
83    store_id: str
84
85    def upsert(self, namespace: str, chunks: Sequence[Chunk], vectors: Sequence[Sequence[float]]) -> int:
86        ...
87
88    def query(
89        self, namespace: str, vector: Sequence[float], top_k: int, filters: Mapping[str, Any] | None = None
90    ) -> Sequence[tuple[Chunk, float]]:
91        ...
92
93    def delete_by_filter(self, namespace: str, filters: Mapping[str, Any]) -> int:
94        ...
Rerankerclass
Ver prueba
src/docu/core/ports.py#L98-L104
Anotaciones: @runtime_checkable
98class Reranker(Protocol):
99    """Cross-encoder: reordena el par consulta-fragmento. Segunda etapa tras la fusion RRF."""
100
101    reranker_id: str
102
103    def rank(self, query: str, chunks: Sequence[Chunk], top_n: int) -> Sequence[tuple[Chunk, float]]:
104        ...
RenderAdapterclass
Ver prueba
src/docu/core/ports.py#L111-L118
Anotaciones: @runtime_checkable
111class RenderAdapter(Protocol):
112    """Convierte un nodo del grafo de contenido en texto de un nivel/notacion concreto."""
113
114    name: str
115    target: str
116
117    def render(self, node: ContentNode, context: Mapping[str, Any]) -> str:
118        ...
Judgeclass
Ver prueba
src/docu/core/ports.py#L122-L129
Anotaciones: @runtime_checkable
122class Judge(Protocol):
123    """Evaluador separado del generador, con version pinneada (Guia-v2.md §5)."""
124
125    judge_id: str
126    temperature: float
127
128    def score(self, document: str, evidence: Sequence[Chunk], rubric: Mapping[str, Any]) -> Metrics:
129        ...
Publisherclass
Ver prueba
src/docu/core/ports.py#L133-L145
Anotaciones: @runtime_checkable
133class Publisher(Protocol):
134    """Destino final. `revert` es obligatorio: la autonomia sin reversibilidad es un riesgo."""
135
136    publisher_id: str
137
138    def propose(self, path: str, content: str, message: str) -> str:
139        ...
140
141    def apply(self, proposal_id: str) -> str:
142        ...
143
144    def revert(self, applied_id: str) -> None:
145        ...
ProfileErrorclass
Ver prueba
src/docu/core/profile.py#L46-L47
46class ProfileError(ValueError):
47    """El perfil no cumple el esquema: mejor fallar que documentar con supuestos equivocados."""
Profileclass
Ver prueba
src/docu/core/profile.py#L51-L107
Anotaciones: @dataclass
51class Profile:
52    """Configuración efectiva de una instalación."""
53
54    project: str
55    mode: Mode = Mode.APPLY
56    levels: tuple[str, ...] = ("l1", "l4")
57    output_dir: str = "docs/generated"
58    language: str = "es"
59    ttl_days: int = 90
60    include: tuple[str, ...] = ()
61    exclude: tuple[str, ...] = DEFAULT_EXCLUDE
62    thresholds: Thresholds = field(default_factory=Thresholds)
63    glossary: Mapping[str, tuple[str, ...]] = field(default_factory=dict)
64    promotion_delta: float = 0.05
65    rollback_drop: float = 0.05
66    federate: bool = False
67    web_allowlist: tuple[str, ...] = ()
68    web_urls: tuple[str, ...] = ()
69    path: Path | None = None
70    raw: Mapping[str, object] = field(default_factory=dict)
71
72    @property
73    def exists(self) -> bool:
74        return self.path is not None and self.path.exists()
75
76    @property
77    def effective_exclude(self) -> tuple[str, ...]:
78        """Exclusiones aplicadas = las del archivo + los defaults de higiene.
79
80        Se calculan al usar el perfil, no al cargarlo: si se fusionaran en la carga, el archivo
81        dejaría de reflejar el comportamiento y la orden de cambio nunca podría proponer nada.
82        """
83        return tuple(dict.fromkeys((*self.exclude, *DEFAULT_EXCLUDE)))
84
85    def to_dict(self) -> dict[str, object]:
86        return {
87            "schema_version": "1.0",
88            "project": self.project,
89            "mode": self.mode.value,
90            "output": {"dir": self.output_dir, "levels": {level: level in self.levels for level in LEVELS}, "language": self.language},
Changeclass
Ver prueba
src/docu/core/profile.py#L318-L332
Anotaciones: @dataclass
318class Change:
319    """Una diferencia entre el perfil vigente y lo que la detección propone."""
320
321    field: str
322    before: object
323    after: object
324    reason: str
325    applied: bool = True
326
327    @property
328    def kind(self) -> str:
329        return "aplicado" if self.applied else "conservado"
330
331    def describe(self) -> str:
332        return f"{self.field}: {self.before!r} → {self.after!r} ({self.reason})"
YamlErrorclass
Ver prueba
src/docu/core/yamlmini.py#L14-L15
14class YamlError(ValueError):
15    """El documento no pertenece al subconjunto soportado."""
CleanPlanclass
Ver prueba
src/docu/delivery/cleanup.py#L44-L69
Anotaciones: @dataclass
44class CleanPlan:
45    """Lo que se borraría (o se borró), separado por tipo para poder revisarlo."""
46
47    documents: list[Path] = field(default_factory=list)
48    artifacts: list[Path] = field(default_factory=list)
49    state: list[Path] = field(default_factory=list)
50    ledger: list[Path] = field(default_factory=list)
51    warnings: list[str] = field(default_factory=list)
52
53    @property
54    def empty(self) -> bool:
55        return not (self.documents or self.artifacts or self.state or self.ledger)
56
57    @property
58    def total(self) -> int:
59        return len(self.documents) + len(self.artifacts) + len(self.state) + len(self.ledger)
60
61    def to_dict(self) -> dict[str, object]:
62        return {
63            "documents": [str(path) for path in self.documents],
64            "artifacts": [str(path) for path in self.artifacts],
65            "state": [str(path) for path in self.state],
66            "ledger": [str(path) for path in self.ledger],
67            "warnings": list(self.warnings),
68            "total": self.total,
69        }
_Parserclass
Ver prueba
src/docu/delivery/cli.py#L56-L67
56class _Parser(argparse.ArgumentParser):
57    """ArgumentParser que explica el caso más común de «comando desconocido»: binario viejo."""
58
59    def error(self, message: str) -> None:  # pragma: no cover - lo ejerce argparse
60        if "invalid choice" in message:
61            message += (
62                "\n\nSi instalaste docu como herramienta (`uv tool install` / `pipx install`), tu copia "
63                "puede ser anterior a este comando. Actualizá con:\n"
64                "  uv tool install --force <ruta-del-repo>   ·   pipx reinstall docu\n"
65                "Y comprobá con `docu --version`, que muestra la ruta desde la que se ejecuta."
66            )
67        super().error(message)
CliErrorclass
Ver prueba
src/docu/delivery/cli.py#L280-L285
280class CliError(RuntimeError):
281    """Error de uso con codigo de salida propio: el CI decide sin parsear mensajes."""
282
283    def __init__(self, message: str, code: ExitCode) -> None:
284        super().__init__(message)
285        self.code = code
ResolvedOptionsclass
Ver prueba
src/docu/delivery/cli.py#L289-L300
Anotaciones: @dataclass
289class ResolvedOptions:
290    """Perfil + banderas de CLI ya resueltas: una sola verdad para generar y verificar."""
291
292    profile: Profile | None
293    project: str
294    levels: tuple[str, ...]
295    out_dir: Path
296    ttl_days: int
297    include: tuple[str, ...]
298    exclude: tuple[str, ...]
299    thresholds: Thresholds
300    manifest: Path | None
ExitCodeclass
Ver prueba
src/docu/delivery/exit_codes.py#L8-L16
8class ExitCode(IntEnum):
9    OK = 0
10    NO_CHANGES = 10          # nada que regenerar: exito silencioso
11    NEEDS_REVIEW = 20        # compuerta de calidad abierta: hay que mirar
12    BUDGET_EXHAUSTED = 30    # se agoto presupuesto: entrega parcial
13    UNCITABLE_SOURCE = 40    # fuente volatil sin snapshot
14    NOT_IMPLEMENTED = 50     # fase aun no construida (scaffold)
15    CONFIG_ERROR = 60        # perfil invalido o ausente
16    INTERNAL_ERROR = 70      # bug del motor
_Handlerclass
Ver prueba
src/docu/delivery/http_server.py#L26-L89
26class _Handler(BaseHTTPRequestHandler):
27    server_version = "docu-mcp-http/0.1"
28    mcp: McpServer  # inyectado por clase antes de servir
29
30    # ------------------------------------------------------------------ rutas
31
32    def do_GET(self) -> None:
33        if self.path.rstrip("/") in ("/health", ""):
34            self._json(
35                200,
36                {
37                    "status": "ok",
38                    "protocol_version": PROTOCOL_VERSION,
39                    "projects": [
40                        {"name": ref.name, "documented": ref.has_docs} for ref in self.mcp.projects()
41                    ],
42                },
43            )
44            return
45        if self.path.rstrip("/") == "/projects":
46            payload = self.mcp.call_tool("list_projects", {})
47            self._json(200, payload)
48            return
49        self._json(404, {"error": f"ruta desconocida: {self.path}"})
50
51    def do_POST(self) -> None:
52        if self.path.rstrip("/") != "/mcp":
53            self._json(404, {"error": f"ruta desconocida: {self.path}"})
54            return
55        length = int(self.headers.get("Content-Length") or 0)
56        if length <= 0:
57            self._json(400, {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": "cuerpo vacío"}})
58            return
59        if length > MAX_BODY_BYTES:
60            self._json(413, {"error": "cuerpo demasiado grande"})
61            return
62        raw = self.rfile.read(length)
63        try:
64            request = json.loads(raw)
65        except json.JSONDecodeError as error:
ProjectRefclass
Ver prueba
src/docu/delivery/mcp_server.py#L164-L188
Anotaciones: @dataclass
164class ProjectRef:
165    """Un proyecto servido: su raíz y el directorio con la documentación generada."""
166
167    name: str
168    root: Path
169    docs_dir: Path
170
171    @property
172    def has_docs(self) -> bool:
173        return self.docs_dir.exists() and any(self.docs_dir.glob("*.md"))
174
175    @property
176    def project_name(self) -> str:
177        """Nombre documentado del proyecto (el del manifest), no el del directorio.
178
179        Sin esto, `list_projects` devolvía `name: ""` y un agente multi-proyecto no podía saber qué
180        estaba consultando.
181        """
182        from docu.generate.pipeline import manifest_file
183        from docu.index.manifest import Manifest
184
185        manifest = Manifest.load(manifest_file(self.root, None))
186        if manifest is not None and manifest.project:
187            return manifest.project
188        return self.root.name
ToolErrorclass
Ver prueba
src/docu/delivery/mcp_server.py#L206-L207
206class ToolError(Exception):
207    """Error de negocio del servidor: se devuelve como contenido de error, no como caída."""
McpServerclass
Ver prueba
src/docu/delivery/mcp_server.py#L211-L626
Anotaciones: @dataclass
211class McpServer:
212    """Servidor de solo lectura sobre **uno o varios** proyectos documentados.
213
214    Con `workspace` apunta a una carpeta que contiene repositorios; cada uno con
215    `docs/generated` se sirve como proyecto. Así un agente que trabaja en el repo A puede
216    consultar la documentación del repo B con el mismo servidor, sin cambiar de configuración.
217    """
218
219    root: Path = Path(".")
220    docs_dir: Path = Path("docs/generated")
221    manifest_path: Path | None = None
222    profile_path: Path | None = None
223    workspace: Path | None = None
224    dense: bool = True
225    _refs: dict[str, ProjectRef] = field(default_factory=dict, init=False, repr=False)
226    _indexes: dict[str, DocIndex] = field(default_factory=dict, init=False, repr=False)
227    _code_indexes: dict[str, object] = field(default_factory=dict, init=False, repr=False)
228
229    def __post_init__(self) -> None:
230        root_ref = ProjectRef(name=self.root.name, root=self.root, docs_dir=self.docs_dir)
231        self._refs = {}
232        # En modo workspace solo se sirve la raíz si tiene documentación: la carpeta contenedora
233        # no es un proyecto, y listarla confunde al agente que elige destino.
234        if self.workspace is None or root_ref.has_docs:
235            self._refs[root_ref.name] = root_ref
236        if self.workspace is not None:
237            for ref in discover_workspace(self.workspace):
238                self._refs.setdefault(ref.name, ref)
239
240    # ------------------------------------------------------------------ proyectos
241
242    def projects(self) -> list[ProjectRef]:
243        """Proyectos servidos: la raíz del servidor y los descubiertos en el workspace."""
244        return list(self._refs.values())
245
246    def resolve(self, arguments: Mapping[str, Any]) -> ProjectRef:
247        """Proyecto solicitado; si hay uno solo, no hace falta nombrarlo."""
248        requested = str(arguments.get("project") or "").strip()
249        candidates = self.projects()
250        if requested:
Diagramclass
Ver prueba
src/docu/generate/diagrams.py#L40-L50
Anotaciones: @dataclass
40class Diagram:
41    """Diagrama listo para escribir y para embeber en el documento."""
42
43    name: str
44    kind: str
45    mermaid: str
46    note: str = ""
47
48    @property
49    def filename(self) -> str:
50        return f"{self.name}.mmd"
DocSectionclass
Ver prueba
src/docu/generate/docs_evidence.py#L49-L73
Anotaciones: @dataclass
49class DocSection:
50    """Una sección de la documentación existente, con su rango de líneas."""
51
52    path: str
53    title: str
54    body: str
55    line_start: int
56    line_end: int
57
58    @property
59    def citation(self) -> str:
60        return f"{self.path}#L{self.line_start}-L{self.line_end}"
61
62    def matches(self, hints: Sequence[str]) -> bool:
63        haystack = f"{self.title} {self.body[:200]}".lower()
64        return any(hint in haystack for hint in hints)
65
66    def to_fact(self) -> Fact:
67        return Fact(
68            kind="doc_section",
69            subject=f"{self.path} › {self.title}",
70            detail=self.body[:MAX_TEXT] or "—",
71            citation=self.citation,
72            attributes={"source": self.path, "title": self.title},
73        )
Factclass
Ver prueba
src/docu/generate/facts.py#L29-L44
Anotaciones: @dataclass
29class Fact:
30    """Una afirmacion atomica con su evidencia."""
31
32    kind: str
33    subject: str
34    detail: str
35    citation: str
36    attributes: Mapping[str, str] = field(default_factory=dict)
37
38    @property
39    def verified(self) -> bool:
40        return bool(self.citation)
41
42    @property
43    def location(self) -> str:
44        return self.citation
Narrativeclass
Ver prueba
src/docu/generate/narrative.py#L48-L57
Anotaciones: @dataclass
48class Narrative:
49    """Lo que el generador pudo decir con evidencia, y lo que no."""
50
51    intent: list[Fact] = field(default_factory=list)
52    decisions: list[Fact] = field(default_factory=list)
53    intro: str = ""
54
55    @property
56    def facts(self) -> list[Fact]:
57        return [*self.intent, *self.decisions]
GeneratedDocclass
Ver prueba
src/docu/generate/pipeline.py#L91-L94
Anotaciones: @dataclass
91class GeneratedDoc:
92    level: str
93    path: Path
94    content: str
GenerationResultclass
Ver prueba
src/docu/generate/pipeline.py#L98-L123
Anotaciones: @dataclass
98class GenerationResult:
99    project: str
100    docs: tuple[GeneratedDoc, ...]
101    facts: tuple[Fact, ...]
102    sources: Mapping[str, str]
103    metrics: Metrics
104    gate: GateDecision
105    elapsed_s: float
106    unsupported: tuple[Fact, ...] = field(default_factory=tuple)
107    states: Mapping[str, DocState] = field(default_factory=dict)
108    manifest_path: Path | None = None
109    applicability: Mapping[str, bool] = field(default_factory=dict)
110    unsupported_languages: Mapping[str, int] = field(default_factory=dict)
111    diagrams: tuple[str, ...] = field(default_factory=tuple)
112    dry_run: bool = False
113
114    @property
115    def wrote_files(self) -> bool:
116        return bool(self.docs) and not self.dry_run
117
118    @property
119    def pending(self) -> tuple[str, ...]:
120        """Niveles que quedaron sin regenerar en modo incremental."""
121        return tuple(
122            level for level, state in self.states.items() if state is DocState.FRESH
123        )
ProseResponseclass
Ver prueba
src/docu/generate/prose.py#L51-L61
Anotaciones: @dataclass
51class ProseResponse:
52    """Lo que devolvió el agente redactor, ya validado."""
53
54    reviewer: str = ""
55    sections: dict[str, list[dict[str, object]]] = field(default_factory=dict)
56    errors: list[str] = field(default_factory=list)
57    warnings: list[str] = field(default_factory=list)
58
59    @property
60    def accepted(self) -> bool:
61        return not self.errors and bool(self.sections)
Verdictclass
Ver prueba
src/docu/generate/prose.py#L65-L76
Anotaciones: @dataclass
65class Verdict:
66    """Veredicto de un segundo agente sobre la prosa."""
67
68    judge: str = ""
69    score: float = 0.0
70    criteria: dict[str, float] = field(default_factory=dict)
71    issues: list[str] = field(default_factory=list)
72    errors: list[str] = field(default_factory=list)
73
74    @property
75    def accepted(self) -> bool:
76        return not self.errors and self.score >= MIN_JUDGE_SCORE
SymbolChunkerclass
Ver prueba
src/docu/index/chunker.py#L46-L220
Anotaciones: @dataclass
46class SymbolChunker:
47    """Chunker por simbolos: implementa el puerto `Chunker`."""
48
49    name: str = DEFAULT_CHUNKER
50    max_tokens: int = 1024
51    overlap_tokens: int = 128
52
53    def chunk(
54        self,
55        artifact: Artifact,
56        symbols: Sequence[Symbol],
57        source: str,
58        dependencies: Mapping[str, Sequence[str]] | None = None,
59    ) -> tuple[Chunk, ...]:
60        lines = source.splitlines()
61        if not lines:
62            return ()
63
64        routes = {symbol.qualname: symbol.name for symbol in symbols if symbol.kind is SymbolKind.HTTP_ROUTE}
65        chunks: list[Chunk] = []
66        for symbol in _flatten(symbols):
67            if symbol.kind is SymbolKind.HTTP_ROUTE:
68                continue  # su informacion viaja en el prefijo del metodo
69            if symbol.kind is SymbolKind.FIELD:
70                # Un campo suelto no es una unidad de recuperación útil: su información vive en el
71                # diccionario de datos del tipo y en el ERD, no en un chunk de una línea.
72                continue
73            start, end = self._span(symbol, symbols, lines)
74            body = "\n".join(lines[start - 1 : end])
75            if not body.strip():
76                continue
77            prefix = self._prefix(artifact, symbol, start, end, routes.get(symbol.qualname))
78            chunks.extend(
79                self._split(
80                    artifact=artifact,
81                    symbol=symbol,
82                    prefix=prefix,
83                    body=body,
84                    start=start,
85                    end=end,
InputComponentsclass
Ver prueba
src/docu/index/freshness.py#L26-L34
Anotaciones: @dataclass
26class InputComponents:
27    """Las seis entradas del hash. Cualquier componente vacio es un bug, no un caso borde."""
28
29    source_content: str
30    deps_signature: str
31    template: str
32    embedder: str
33    chunker: str
34    profile: str
IgnoreRuleclass
Ver prueba
src/docu/index/ignore.py#L18-L24
Anotaciones: @dataclass
18class IgnoreRule:
19    raw: str
20    pattern: str
21    negate: bool
22    directory_only: bool
23    anchored: bool
24    regex: re.Pattern[str]
DocEntryclass
Ver prueba
src/docu/index/manifest.py#L33-L68
Anotaciones: @dataclass
33class DocEntry:
34    """Estado registrado de una pagina generada."""
35
36    level: str
37    path: str
38    input_hash: str
39    generated_at: str
40    content_hash: str
41    ttl_days: int = 90
42    sources: Mapping[str, str] = field(default_factory=dict)
43
44    def to_dict(self) -> dict[str, object]:
45        return {
46            "level": self.level,
47            "path": self.path,
48            "input_hash": self.input_hash,
49            "generated_at": self.generated_at,
50            "content_hash": self.content_hash,
51            "ttl_days": self.ttl_days,
52            "sources": dict(self.sources),
53        }
54
55    @classmethod
56    def from_dict(cls, payload: Mapping[str, object]) -> DocEntry:
57        return cls(
58            level=str(payload["level"]),
59            path=str(payload["path"]),
60            input_hash=str(payload["input_hash"]),
61            generated_at=str(payload["generated_at"]),
62            content_hash=str(payload["content_hash"]),
63            ttl_days=int(payload.get("ttl_days", 90)),  # type: ignore[arg-type]
64            sources=dict(payload.get("sources") or {}),  # type: ignore[arg-type]
65        )
66
67    def generated_at_dt(self) -> datetime:
68        return datetime.fromisoformat(self.generated_at)
Manifestclass
Ver prueba
src/docu/index/manifest.py#L72-L124
Anotaciones: @dataclass
72class Manifest:
73    """Conjunto de paginas conocidas de un proyecto."""
74
75    project: str
76    docs: list[DocEntry] = field(default_factory=list)
77    versions: Mapping[str, str] = field(default_factory=lambda: dict(DEFAULT_VERSIONS))
78    schema_version: str = MANIFEST_VERSION
79
80    # ------------------------------------------------------------------ consulta
81
82    def entry(self, level: str) -> DocEntry | None:
83        return next((doc for doc in self.docs if doc.level == level), None)
84
85    def upsert(self, entry: DocEntry) -> None:
86        self.docs = [doc for doc in self.docs if doc.level != entry.level] + [entry]
87
88    # ------------------------------------------------------------------ persistencia
89
90    def to_dict(self) -> dict[str, object]:
91        return {
92            "schema_version": self.schema_version,
93            "project": self.project,
94            "versions": dict(self.versions),
95            "docs": [doc.to_dict() for doc in self.docs],
96        }
97
98    @classmethod
99    def from_dict(cls, payload: Mapping[str, object]) -> Manifest:
100        return cls(
101            project=str(payload.get("project", "")),
102            docs=[DocEntry.from_dict(item) for item in payload.get("docs", [])],  # type: ignore[union-attr]
103            versions=dict(payload.get("versions") or DEFAULT_VERSIONS),  # type: ignore[arg-type]
104            schema_version=str(payload.get("schema_version", MANIFEST_VERSION)),
105        )
106
107    def save(self, path: Path | str) -> Path:
108        target = Path(path)
109        target.parent.mkdir(parents=True, exist_ok=True)
110        target.write_text(json.dumps(self.to_dict(), ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
111        return target
DetectedPackageclass
Ver prueba
src/docu/index/packages.py#L22-L36
Anotaciones: @dataclass
22class DetectedPackage:
23    """Unidad arquitectónica detectada, con el archivo que la declara."""
24
25    name: str
26    language: str
27    files: tuple[str, ...]
28    declaration: str  # ruta#L inicio-L fin de la declaración
29
30    @property
31    def file_count(self) -> int:
32        return len(self.files)
33
34    @property
35    def citation(self) -> str:
36        return self.declaration
PdfDocumentclass
Ver prueba
src/docu/index/pdfdocs.py#L24-L50
Anotaciones: @dataclass
24class PdfDocument:
25    rel: str
26    pages: int
27    chars: int
28    method: str
29    status: str
30    usable: bool
31    warnings: tuple[str, ...] = ()
32
33    @property
34    def citation(self) -> str:
35        return f"{self.rel}#p1"
36
37    def to_fact(self) -> Fact:
38        extra = f" · {'; '.join(self.warnings)}" if self.warnings else ""
39        return Fact(
40            kind="pdf_document",
41            subject=self.rel,
42            detail=f"{self.status} · {self.pages} pág. · {self.chars} caract. · {self.method}{extra}",
43            citation=self.citation,
44            attributes={
45                "pages": str(self.pages),
46                "chars": str(self.chars),
47                "method": self.method,
48                "status": self.status,
49            },
50        )
WebDocumentclass
Ver prueba
src/docu/index/webdocs.py#L18-L45
Anotaciones: @dataclass
18class WebDocument:
19    url: str
20    rel: str
21    sha: str
22    captured_at: str
23    lines: int
24    chars: int
25    usable: bool
26    error: str = ""
27
28    @property
29    def citation(self) -> str:
30        return f"{self.rel}#L1-L{max(1, self.lines)}"
31
32    def to_fact(self) -> Fact:
33        status = "texto congelado" if self.usable else f"no capturada: {self.error or 'sin texto'}"
34        return Fact(
35            kind="web_source",
36            subject=self.url,
37            detail=f"{status} · {self.lines} líneas · {self.chars} caract. · {self.sha[:12]} · {self.captured_at}",
38            citation=self.citation,
39            attributes={
40                "sha": self.sha,
41                "captured_at": self.captured_at,
42                "lines": str(self.lines),
43                "status": status,
44            },
45        )
FederationErrorclass
Ver prueba
src/docu/learn/federation.py#L28-L29
28class FederationError(RuntimeError):
29    """El payload no cumple la política de privacidad: se rechaza el envío."""
FederationPayloadclass
Ver prueba
src/docu/learn/federation.py#L33-L37
Anotaciones: @dataclass
33class FederationPayload:
34    data: Mapping[str, object]
35
36    def to_json(self) -> str:
37        return json.dumps(self.data, ensure_ascii=False, indent=2, sort_keys=True)
Patternclass
Ver prueba
src/docu/learn/patterns.py#L25-L55
Anotaciones: @dataclass
25class Pattern:
26    """Un patrón aprendido: qué stack, qué mejora y con qué evidencia."""
27
28    pattern_id: str
29    stack: str
30    kind: str  # "profile_default" | "glossary_entry" | "failure_avoidance"
31    metrics: Mapping[str, float] = field(default_factory=dict)
32    runs: int = 0
33    notes: str = ""
34
35    def to_dict(self) -> dict[str, object]:
36        return {
37            "pattern_id": self.pattern_id,
38            "stack": self.stack,
39            "kind": self.kind,
40            "metrics": dict(self.metrics),
41            "runs": self.runs,
42            "notes": self.notes,
43        }
44
45    @classmethod
46    def from_dict(cls, payload: Mapping[str, object]) -> Pattern:
47        metrics = payload.get("metrics") or {}
48        return cls(
49            pattern_id=str(payload.get("pattern_id", "")),
50            stack=str(payload.get("stack", "")),
51            kind=str(payload.get("kind", "profile_default")),
52            metrics={str(key): float(value) for key, value in metrics.items()},  # type: ignore[union-attr]
53            runs=int(payload.get("runs", 0)),  # type: ignore[arg-type]
54            notes=str(payload.get("notes", "")),
55        )
PatternLibraryclass
Ver prueba
src/docu/learn/patterns.py#L59-L142
Anotaciones: @dataclass
59class PatternLibrary:
60    """Versión vigente + historial mínimo para poder revertir."""
61
62    patterns: dict[str, Pattern] = field(default_factory=dict)
63    history: list[dict[str, object]] = field(default_factory=list)
64    version: str = "0"
65    schema_version: str = SCHEMA_VERSION
66
67    def to_dict(self) -> dict[str, object]:
68        return {
69            "schema_version": self.schema_version,
70            "version": self.version,
71            "patterns": {key: pattern.to_dict() for key, pattern in self.patterns.items()},
72            "history": list(self.history),
73        }
74
75    @classmethod
76    def from_dict(cls, payload: Mapping[str, object]) -> PatternLibrary:
77        raw = payload.get("patterns") or {}
78        patterns = {
79            str(key): Pattern.from_dict(value)  # type: ignore[arg-type]
80            for key, value in raw.items()  # type: ignore[union-attr]
81            if isinstance(value, dict)
82        }
83        history = payload.get("history") or []
84        return cls(
85            patterns=patterns,
86            history=[item for item in history if isinstance(item, dict)],  # type: ignore[union-attr]
87            version=str(payload.get("version", "0")),
88            schema_version=str(payload.get("schema_version", SCHEMA_VERSION)),
89        )
90
91    # ------------------------------------------------------------------ persistencia
92
93    def save(self, path: Path | str) -> Path:
94        target = Path(path)
95        target.parent.mkdir(parents=True, exist_ok=True)
96        target.write_text(json.dumps(self.to_dict(), ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
97        return target
98
Candidateclass
Ver prueba
src/docu/learn/patterns.py#L156-L164
Anotaciones: @dataclass
156class Candidate:
157    """Patrón propuesto a partir del ledger, con la evidencia que lo respalda."""
158
159    pattern: Pattern
160    reasons: Sequence[str] = ()
161
162    @property
163    def key(self) -> str:
164        return self.pattern.pattern_id
Decisionclass
Ver prueba
src/docu/learn/promotion.py#L21-L33
Anotaciones: @dataclass
21class Decision:
22    action: str
23    pattern_id: str
24    delta: float
25    reasons: Sequence[str] = field(default_factory=tuple)
26
27    @property
28    def is_change(self) -> bool:
29        return self.action in (PROMOTE, ROLLBACK)
30
31    def describe(self) -> str:
32        detail = "; ".join(self.reasons) if self.reasons else "sin detalle"
33        return f"{self.action.upper()} {self.pattern_id} (Δ medio {self.delta:+.3f}): {detail}"
Pageclass
Ver prueba
src/docu/publish/site.py#L124-L127
Anotaciones: @dataclass
124class Page:
125    name: str
126    title: str
127    html: str
CodeChunkclass
Ver prueba
src/docu/retrieve/hybrid.py#L33-L59
Anotaciones: @dataclass
33class CodeChunk:
34    """Fragmento de código recuperable, con su cita y su símbolo."""
35
36    path: str
37    start: int
38    end: int
39    text: str
40    symbol: str | None
41    kind: str
42    tokens: tuple[str, ...] = ()
43    exact_names: tuple[str, ...] = ()
44
45    @property
46    def citation(self) -> str:
47        return f"{self.path}#L{self.start}-L{self.end}"
48
49    def to_dict(self, score: float) -> dict[str, object]:
50        return {
51            "citation": self.citation,
52            "path": self.path,
53            "start": self.start,
54            "end": self.end,
55            "symbol": self.symbol,
56            "kind": self.kind,
57            "score": round(score, 4),
58            "excerpt": self.text[:1200],
59        }
CodeIndexclass
Ver prueba
src/docu/retrieve/hybrid.py#L113-L253
Anotaciones: @dataclass
113class CodeIndex:
114    """Índice de código con los tres canales. El denso es opcional y se declara."""
115
116    chunks: list[CodeChunk] = field(default_factory=list)
117    embedder: object | None = None
118    glossary: Mapping[str, Sequence[str]] | None = None
119    k1: float = 1.5
120    b: float = 0.75
121    _df: dict[str, int] = field(default_factory=dict, init=False, repr=False)
122    _lengths: list[int] = field(default_factory=list, init=False, repr=False)
123    _avgdl: float = field(default=0.0, init=False, repr=False)
124    _by_name: dict[str, list[CodeChunk]] = field(default_factory=dict, init=False, repr=False)
125    _vectors: list[Sequence[float]] = field(default_factory=list, init=False, repr=False)
126    _dense_ready: bool = field(default=False, init=False, repr=False)
127
128    def __post_init__(self) -> None:
129        self._lengths = [len(chunk.tokens) for chunk in self.chunks]
130        for chunk in self.chunks:
131            for term in set(chunk.tokens):
132                self._df[term] = self._df.get(term, 0) + 1
133            for name in chunk.exact_names:
134                self._by_name.setdefault(name, []).append(chunk)
135        self._avgdl = (sum(self._lengths) / len(self._lengths)) if self._lengths else 0.0
136
137    # ------------------------------------------------------------------ capacidades
138
139    @property
140    def dense_available(self) -> bool:
141        return self.embedder is not None
142
143    def capabilities(self) -> dict[str, object]:
144        return {
145            "chunks": len(self.chunks),
146            "channels": ["lexical", "symbol"] + (["dense"] if self.dense_available else []),
147            "dense": self.dense_available,
148            # Un degradado silencioso parece un problema de calidad de la búsqueda: se explica.
149            "dense_reason": ""
150            if self.dense_available
151            else "modelo ONNX no descargado (docu no lo incluye: 113 MB); se usan léxico y símbolo",
152            "files_indexed": len({chunk.path for chunk in self.chunks}),
Sectionclass
Ver prueba
src/docu/retrieve/search.py#L68-L89
Anotaciones: @dataclass
68class Section:
69    """Seccion de un documento: la unidad que se devuelve a un agente."""
70
71    document: str
72    heading: str
73    body: str
74    level: str = ""
75    tokens: tuple[str, ...] = ()
76    citations: tuple[str, ...] = ()
77
78    @property
79    def text(self) -> str:
80        return f"{self.heading}\n{self.body}"
81
82    def to_dict(self) -> dict[str, object]:
83        return {
84            "document": self.document,
85            "level": self.level,
86            "heading": self.heading,
87            "body": self.body,
88            "citations": list(self.citations),
89        }
DocIndexclass
Ver prueba
src/docu/retrieve/search.py#L126-L196
Anotaciones: @dataclass
126class DocIndex:
127    """Indice BM25 en memoria sobre las secciones de los documentos generados."""
128
129    sections: list[Section] = field(default_factory=list)
130    k1: float = 1.5
131    b: float = 0.75
132    glossary: Mapping[str, Sequence[str]] | None = None
133    _df: dict[str, int] = field(default_factory=dict, init=False)
134    _avgdl: float = field(default=0.0, init=False)
135
136    def __post_init__(self) -> None:
137        lengths = [len(section.tokens) for section in self.sections]
138        for section in self.sections:
139            for term in set(section.tokens):
140                self._df[term] = self._df.get(term, 0) + 1
141        self._avgdl = (sum(lengths) / len(lengths)) if lengths else 0.0
142
143    @classmethod
144    def from_directory(cls, directory: Path | str, glossary: Mapping[str, Sequence[str]] | None = None) -> DocIndex:
145        """Carga todos los `.md` de un directorio de documentacion generada."""
146        sections: list[Section] = []
147        root = Path(directory)
148        if root.exists():
149            for path in sorted(root.glob("*.md")):
150                level = path.name.split("-", 1)[0]
151                sections.extend(split_sections(path, path.read_text(encoding="utf-8"), level))
152        return cls(sections=sections, glossary=glossary)
153
154    def _idf(self, term: str) -> float:
155        total = len(self.sections)
156        df = self._df.get(term, 0)
157        return math.log(1 + (total - df + 0.5) / (df + 0.5))
158
159    def search(
160        self,
161        query: str,
162        limit: int = 5,
163        expand_query: bool = True,
164        level: str | None = None,
165    ) -> list[tuple[Section, float]]:

Métodos 556

QuéDetalleEvidencia
_fuentedef _fuente(rutas: tuple[str, ...], tamano: int) -> ImageFont.FreeTypeFont
Ver prueba
docs/brand/make-cover.py#L39-L43
39def _fuente(rutas: tuple[str, ...], tamano: int) -> ImageFont.FreeTypeFont:
40    for ruta in rutas:
41        if Path(ruta).is_file():
42            return ImageFont.truetype(ruta, tamano)
43    return ImageFont.load_default(size=tamano)
_espaciadodef _espaciado(dibujo: ImageDraw.ImageDraw, xy: tuple[int, int], texto: str, fuente, extra: int, fill) -> int
Ver prueba
docs/brand/make-cover.py#L46-L52
46def _espaciado(dibujo: ImageDraw.ImageDraw, xy: tuple[int, int], texto: str, fuente, extra: int, fill) -> int:
47    """Texto con espaciado entre letras: el logotipo respira, el texto normal no."""
48    x, y = xy
49    for caracter in texto:
50        dibujo.text((x, y), caracter, font=fuente, fill=fill)
51        x += dibujo.textlength(caracter, font=fuente) + extra
52    return int(x)
componerdef componer(frame: Path, destino: Path) -> Path
Ver prueba
docs/brand/make-cover.py#L55-L97
55def componer(frame: Path, destino: Path) -> Path:
56    lienzo = Image.new("RGB", (ANCHO, ALTO), FONDO)
57    if frame.is_file():
58        arte = Image.open(frame).convert("RGB").resize((ANCHO, ALTO), Image.LANCZOS)
59        # Se oscurece apenas el arte para que el logotipo tenga contraste sin tapar la ilustración.
60        velo = Image.new("RGB", (ANCHO, ALTO), FONDO)
61        lienzo = Image.blend(arte, velo, 0.22)
62    dibujo = ImageDraw.Draw(lienzo)
63
64    # Logotipo y promesa, arriba a la izquierda: zona oscura del frame.
65    titulo = _fuente(FUENTES, 74)
66    _espaciado(dibujo, (66, 40), "docu", titulo, 5, ORO)
67
68    subtitulo = _fuente(FUENTES, 25)
69    dibujo.text(
70        (70, 132),
71        "documentación técnica que se puede verificar",
72        font=subtitulo,
73        fill=GRIS,
74    )
75
76    # Regla corta en azul: el mismo acento que el check del video.
77    dibujo.line([(70, 176), (170, 176)], fill=AZUL, width=3)
78
79    # Pie: la promesa concreta, en monoespaciada como una cita.
80    mono = _fuente(MONO, 19)
81    dibujo.text(
82        (70, 636),
83        "cada afirmación cita archivo#línea · extractivo · 0 USD",
84        font=mono,
85        fill=GRIS_APAGADO,
86    )
87
88    # Sello de licencia, abajo a la derecha.
89    sello = _fuente(FUENTES, 18)
90    etiqueta = "MIT · v0.1.0"
91    ancho_etiqueta = dibujo.textlength(etiqueta, font=sello)
92    x = ANCHO - 70 - ancho_etiqueta
93    dibujo.text((x, 636), etiqueta, font=sello, fill=GRIS_APAGADO)
94
maindef main(argv: list[str]) -> int
Ver prueba
docs/brand/make-cover.py#L100-L104
100def main(argv: list[str]) -> int:
101    frame = Path(argv[1]) if len(argv) > 1 else Path("docs/brand/frame-video.png")
102    destino = Path(argv[2]) if len(argv) > 2 else Path("docs/brand/portada.png")
103    print(componer(frame, destino))
104    return 0
_folddef _fold(text: str) -> str
Ver prueba
eval/harness.py#L81-L88
81def _fold(text: str) -> str:
82    """Quita diacríticos: `configuración` y `configuracion` deben ser el mismo término.
83
84    Un agente documentador en español se consulta indistintamente con y sin tildes; si el
85    tokenizador las trata como palabras distintas, el recall cae por un motivo que no tiene
86    nada que ver con la calidad del recuperador.
87    """
88    return "".join(c for c in unicodedata.normalize("NFD", text) if not unicodedata.combining(c))
tokenizedef tokenize(text: str) -> list[str]
Ver prueba
eval/harness.py#L91-L109
91def tokenize(text: str) -> list[str]:
92    """Tokens con descomposición de CamelCase, separadores y plegado de acentos.
93
94    Sin esto, BM25 puntúa identificadores Java como si fueran palabras opacas y el baseline
95    queda artificialmente malo.
96    """
97    tokens: list[str] = []
98    for raw in _WORD.findall(_fold(text)):
99        for part in re.split(r"[_.\-]", raw):
100            if not part:
101                continue
102            low = part.lower()
103            if low not in _STOP:
104                tokens.append(low)
105            for match in _CAMEL.finditer(part):
106                sub = match.group(0).lower()
107                if len(sub) > 2 and sub not in _STOP:
108                    tokens.append(sub)
109    return tokens
_matchesdef _matches(path: str, patterns: Sequence[str]) -> bool
Ver prueba
eval/harness.py#L132-L134
132def _matches(path: str, patterns: Sequence[str]) -> bool:
133    name = path.rsplit("/", 1)[-1]
134    return any(fnmatch.fnmatch(path, p) or fnmatch.fnmatch(name, p) for p in patterns)
discover_filesdef discover_files(repo: Path, include: Sequence[str], exclude: Sequence[str]) -> list[str]
Ver prueba
eval/harness.py#L137-L146
137def discover_files(repo: Path, include: Sequence[str], exclude: Sequence[str]) -> list[str]:
138    files: list[str] = []
139    for candidate in sorted(repo.rglob("*")):
140        if not candidate.is_file():
141            continue
142        rel = candidate.relative_to(repo).as_posix()
143        if _matches(rel, exclude) or not _matches(rel, include):
144            continue
145        files.append(rel)
146    return files
_window_segmentsdef _window_segments(repo: Path, rel: str, window: int, overlap: int) -> list[Segment]
Ver prueba
eval/harness.py#L149-L175
149def _window_segments(repo: Path, rel: str, window: int, overlap: int) -> list[Segment]:
150    try:
151        text = (repo / rel).read_text(encoding="utf-8", errors="strict")
152    except (UnicodeDecodeError, OSError):
153        return []
154    lines = text.splitlines()
155    if not lines:
156        return []
157    segments: list[Segment] = []
158    step = max(1, window - overlap)
159    for start in range(0, len(lines), step):
160        block = lines[start : start + window]
161        if not block:
162            break
163        body = "\n".join(block)
164        if not body.strip():
165            continue
166        segments.append(
167            Segment(
168                path=rel,
169                start=start + 1,
170                end=start + len(block),
171                text=body,
172                tokens=tuple(tokenize(f"{rel} {body}")),
173            )
174        )
175    return segments
build_corpusdef build_corpus(repo: Path, include: Sequence[str]=..., exclude: Sequence[str]=..., window: int=..., overlap: int=...) -> list[Segment]
Ver prueba
eval/harness.py#L178-L188
178def build_corpus(
179    repo: Path,
180    include: Sequence[str] = DEFAULT_INCLUDE,
181    exclude: Sequence[str] = DEFAULT_EXCLUDE,
182    window: int = 40,
183    overlap: int = 8,
184) -> list[Segment]:
185    segments: list[Segment] = []
186    for rel in discover_files(repo, include, exclude):
187        segments.extend(_window_segments(repo, rel, window, overlap))
188    return segments
_exact_namesdef _exact_names(qualname: str | None) -> tuple[str, ...]
Ver prueba
eval/harness.py#L191-L197
191def _exact_names(qualname: str | None) -> tuple[str, ...]:
192    """Nombres por los que un simbolo debe coincidir de forma exacta (sin descomponer)."""
193    if not qualname:
194        return ()
195    names = [qualname.lower()]
196    names.extend(part.lower() for part in re.split(r"[.#]", qualname) if part)
197    return tuple(dict.fromkeys(names))
build_symbol_corpusdef build_symbol_corpus(repo: Path, exclude: Sequence[str]=..., window: int=..., overlap: int=...) -> list[Segment]
Ver prueba
eval/harness.py#L200-L253
200def build_symbol_corpus(
201    repo: Path,
202    exclude: Sequence[str] = DEFAULT_EXCLUDE,
203    window: int = 40,
204    overlap: int = 8,
205) -> list[Segment]:
206    """Indice de F1: chunks sintacticos para Java y ventanas para el resto de artefactos.
207
208    Mezclar ambos es deliberado: la documentacion de operacion vive en `application.yml`,
209    `pom.xml` y `README.md`, y un indice que solo entienda Java perderia esos casos.
210    """
211    from docu.adapters.langs.java import JavaLangAdapter
212    from docu.core.contracts import Artifact, SourceKind, sha256_of, utcnow
213    from docu.index.chunker import SymbolChunker
214
215    adapter = JavaLangAdapter()
216    chunker = SymbolChunker()
217    all_files = discover_files(repo, DEFAULT_INCLUDE, exclude)
218    java_files = [rel for rel in all_files if rel.endswith(".java")]
219    segments: list[Segment] = []
220
221    for rel in java_files:
222        try:
223            source = (repo / rel).read_text(encoding="utf-8", errors="strict")
224        except (UnicodeDecodeError, OSError):
225            continue
226        artifact = Artifact(
227            artifact_id=f"{repo.name}:{rel}",
228            kind=SourceKind.GIT_REPOSITORY,
229            uri=rel,
230            content_hash=sha256_of(source.encode("utf-8")),
231            captured_at=utcnow(),
232            lang="java",
233        )
234        for chunk in chunker.chunk(artifact, adapter.symbols(rel, source), source):
235            text = f"{chunk.content_prefix}\n{chunk.content}"
236            segments.append(
237                Segment(
238                    path=chunk.file_path,
239                    start=chunk.line_start,
BM25.__post_init__def __post_init__(self) -> None
Ver prueba
eval/harness.py#L270-L275
270    def __post_init__(self) -> None:
271        for segment in self.segments:
272            self._lengths.append(len(segment.tokens))
273            for term in set(segment.tokens):
274                self._df[term] = self._df.get(term, 0) + 1
275        self._avgdl = (sum(self._lengths) / len(self._lengths)) if self._lengths else 0.0
BM25._idfdef _idf(self, term: str) -> float
Ver prueba
eval/harness.py#L277-L280
277    def _idf(self, term: str) -> float:
278        n = len(self.segments)
279        df = self._df.get(term, 0)
280        return log(1 + (n - df + 0.5) / (df + 0.5))
BM25.scoresdef scores(self, query: str) -> list[float]
Ver prueba
eval/harness.py#L282-L297
282    def scores(self, query: str) -> list[float]:
283        terms = tokenize(query)
284        results: list[float] = []
285        for segment, length in zip(self.segments, self._lengths):
286            freq: dict[str, int] = {}
287            for token in segment.tokens:
288                freq[token] = freq.get(token, 0) + 1
289            score = 0.0
290            for term in set(terms):
291                tf = freq.get(term, 0)
292                if tf == 0:
293                    continue
294                denom = tf + self.k1 * (1 - self.b + self.b * (length / self._avgdl if self._avgdl else 1.0))
295                score += self._idf(term) * (tf * (self.k1 + 1)) / denom
296            results.append(score)
297        return results
BM25.searchdef search(self, query: str, k: int=...) -> list[tuple[Segment, float]]
Ver prueba
eval/harness.py#L299-L302
299    def search(self, query: str, k: int = 10) -> list[tuple[Segment, float]]:
300        scored = list(zip(self.segments, self.scores(query)))
301        scored.sort(key=lambda item: item[1], reverse=True)
302        return [(seg, score) for seg, score in scored[:k] if score > 0]
_looks_like_identifierdef _looks_like_identifier(query: str) -> bool
Ver prueba
eval/harness.py#L305-L401
305def _looks_like_identifier(query: str) -> bool:
306    """¿La consulta es código tecleado o una pregunta humana?
307
308    Criterio estricto, aprendido midiendo: una palabra capitalizada NO es un identificador.
309    "Spring Boot" o "CORS" aparecen en preguntas humanas y enrutarla al índice de símbolos
310    empeoraba el MRR en español (0.596 -> 0.475). Se exige forma de código: punto entre
311    palabras, guion bajo, o camelCase real.
312
313    Nueva heurística (F-12): si la consulta tiene 3 o más palabras y al menos una
314    palabra natural O técnica no-identifier, se trata de una pregunta humana y no se
315    enruta al índice de símbolos. Esto evita falsos positivos como
316    "application.yml server port" (3 palabras con términos no-identifiers).
317
318    Además, palabras como "server", "port", "config", "setting", "api", "error", "handler",
319    son tratadas como términos naturales que no desencadenan enrutamiento a símbolos,
320    aun cuando aparezcan con camelCase o punto.
321
322    IMPORTANTE: Si la consulta TIENE sintaxis de código clara (punto entre tokens,
323    guion bajo, kebab-case, camelCase real), prevalece esa sintaxis y se considera
324    identifier. La comprobación de "3+ palabras naturales/técnicas" solo aplica
325    cuando NO hay sintaxis de código clara.
326    """
327    tokens = query.split()
328
329    # Extensiones de archivo: un token como "application.yml" NO es sintaxis de código,
330    # es un nombre de archivo. Sin esto, "application.yml server port" se enruta al
331    # índice de símbolos y el MRR cae (F-12).
332    _FILE_EXTS = {
333        "yml", "yaml", "json", "xml", "java", "py", "ts", "js", "jsx", "tsx",
334        "md", "properties", "conf", "cfg", "ini", "sh", "toml", "txt", "html",
335        "css", "sql", "gradle", "kt", "swift", "rb", "go", "c", "h", "cpp",
336    }
337
338    def _is_filename(token: str) -> bool:
339        m = re.fullmatch(r"([A-Za-z0-9_-]+)\.([A-Za-z0-9]+)", token)
340        if not m:
341            return False
342        if m.group(2).lower() not in _FILE_EXTS:
343            return False
344        # Si la parte antes del punto tiene camelCase real, es código
_diversitydef _diversity(ordered: Sequence[tuple[tuple[str, int, int], float]], k: int, cap: int, by_key: dict[tuple[str, int, int], Segment]) -> list[tuple[tuple[str, int, int], float]]
Ver prueba
eval/harness.py#L404-L425
404def _diversity(
405    ordered: Sequence[tuple[tuple[str, int, int], float]],
406    k: int,
407    cap: int,
408    by_key: dict[tuple[str, int, int], Segment],
409) -> list[tuple[tuple[str, int, int], float]]:
410    """Limita cuantos fragmentos aporta un mismo archivo (Guia-v2.md §3.4).
411
412    Sin esto, un archivo con muchos chunks utiles ocupa casi todo el top-k y desplaza la
413    evidencia de otros archivos: un documento generado asi cita ocho veces el mismo fichero.
414    """
415    out: list[tuple[tuple[str, int, int], float]] = []
416    per_file: dict[str, int] = {}
417    for key, score in ordered:
418        path = by_key[key].path
419        if per_file.get(path, 0) >= cap:
420            continue
421        per_file[path] = per_file.get(path, 0) + 1
422        out.append((key, score))
423        if len(out) >= k:
424            break
425    return out
AutoIndex.__post_init__def __post_init__(self) -> None
Ver prueba
eval/harness.py#L442-L444
442    def __post_init__(self) -> None:
443        self._symbols = SymbolIndex(segments=self.segments)
444        self._hybrid = HybridIndex(segments=self.segments, embedder=self.embedder)
AutoIndex.searchdef search(self, query: str, k: int=...) -> list[tuple[Segment, float]]
Ver prueba
eval/harness.py#L446-L449
446    def search(self, query: str, k: int = 10) -> list[tuple[Segment, float]]:
447        if _looks_like_identifier(query):
448            return self._symbols.search(query, k=k)
449        return self._hybrid.search(query, k=k)
HybridIndex.__post_init__def __post_init__(self) -> None
Ver prueba
eval/harness.py#L471-L477
471    def __post_init__(self) -> None:
472        self._bm25 = BM25(k1=self.k1, b=self.b, segments=self.segments)
473        for segment in self.segments:
474            for name in segment.exact_names:
475                self._by_name.setdefault(name, []).append(segment)
476        if self.embedder is not None:
477            self._vectors = list(self.embedder.embed([segment.text for segment in self.segments]))
HybridIndex._dense_channeldef _dense_channel(self, query: str, limit: int) -> list[Segment]
Ver prueba
eval/harness.py#L481-L492
481    def _dense_channel(self, query: str, limit: int) -> list[Segment]:
482        if not self._vectors:
483            return []
484        from docu.adapters.embedders.onnx_local import cosine
485
486        query_vector = self.embedder.embed([query])[0]  # type: ignore[union-attr]
487        scored = [
488            (segment, cosine(query_vector, vector))
489            for segment, vector in zip(self.segments, self._vectors)
490        ]
491        scored.sort(key=lambda item: item[1], reverse=True)
492        return [segment for segment, _score in scored[:limit]]
HybridIndex._exact_channeldef _exact_channel(self, terms: set[str]) -> list[Segment]
Ver prueba
eval/harness.py#L494-L506
494    def _exact_channel(self, terms: set[str]) -> list[Segment]:
495        hits: list[Segment] = []
496        seen: set[tuple[str, int, int]] = set()
497        per_file: dict[str, int] = {}
498        for term in sorted(terms):
499            for segment in self._by_name.get(term, ()):
500                key = (segment.path, segment.start, segment.end)
501                if key in seen or per_file.get(segment.path, 0) >= self.max_exact_per_file:
502                    continue
503                seen.add(key)
504                per_file[segment.path] = per_file.get(segment.path, 0) + 1
505                hits.append(segment)
506        return hits
HybridIndex._channel_weightsdef _channel_weights(self, query: str) -> tuple[float, float, float]
Ver prueba
eval/harness.py#L508-L515
508    def _channel_weights(self, query: str) -> tuple[float, float, float]:
509        """Enrutado por tipo de consulta: si el usuario teclea identificadores, el canal denso pesa menos.
510
511        Motivo medido: con consultas de identificadores el denso mete ruido y hace perder un caso
512        (`pom.xml`, C-13) sin aportar nada; con preguntas humanas es imprescindible.
513        """
514        identifier_like = _looks_like_identifier(query)
515        return (1.0, 0.5 if identifier_like else 1.0, 1.0)
HybridIndex.searchdef search(self, query: str, k: int=...) -> list[tuple[Segment, float]]
Ver prueba
eval/harness.py#L517-L534
517    def search(self, query: str, k: int = 10) -> list[tuple[Segment, float]]:
518        terms = set(tokenize(query))
519        limit = max(k * 5, 50)
520        channels = [
521            [segment for segment, _score in self._bm25.search(query, k=limit)],
522            self._dense_channel(query, limit),
523            self._exact_channel(terms),
524        ]
525        weights = self._channel_weights(query)
526        fused: dict[tuple[str, int, int], float] = {}
527        by_key: dict[tuple[str, int, int], Segment] = {}
528        for weight, channel in zip(weights, channels):
529            for rank, segment in enumerate(channel, start=1):
530                key = (segment.path, segment.start, segment.end)
531                by_key[key] = segment
532                fused[key] = fused.get(key, 0.0) + weight / (self.rrf_k + rank)
533        ordered = sorted(fused.items(), key=lambda item: item[1], reverse=True)
534        return [(by_key[key], score) for key, score in _diversity(ordered, k, self.max_per_file, by_key)]
SymbolIndex.__post_init__def __post_init__(self) -> None
Ver prueba
eval/harness.py#L557-L561
557    def __post_init__(self) -> None:
558        self._bm25 = BM25(k1=self.k1, b=self.b, segments=self.segments)
559        for segment in self.segments:
560            for name in segment.exact_names:
561                self._by_name.setdefault(name, []).append(segment)
SymbolIndex._exact_channeldef _exact_channel(self, terms: set[str]) -> list[Segment]
Ver prueba
eval/harness.py#L563-L577
563    def _exact_channel(self, terms: set[str]) -> list[Segment]:
564        hits: list[Segment] = []
565        seen: set[tuple[str, int, int]] = set()
566        per_file: dict[str, int] = {}
567        for term in sorted(terms):
568            for segment in self._by_name.get(term, ()):
569                key = (segment.path, segment.start, segment.end)
570                if key in seen:
571                    continue
572                if per_file.get(segment.path, 0) >= self.max_exact_per_file:
573                    continue
574                seen.add(key)
575                per_file[segment.path] = per_file.get(segment.path, 0) + 1
576                hits.append(segment)
577        return hits
SymbolIndex.searchdef search(self, query: str, k: int=...) -> list[tuple[Segment, float]]
Ver prueba
eval/harness.py#L579-L594
579    def search(self, query: str, k: int = 10) -> list[tuple[Segment, float]]:
580        terms = set(tokenize(query))
581        lexical = [segment for segment, _score in self._bm25.search(query, k=max(k * 5, 50))]
582        exact = self._exact_channel(terms)
583
584        fused: dict[tuple[str, int, int], float] = {}
585        for rank, segment in enumerate(lexical, start=1):
586            key = (segment.path, segment.start, segment.end)
587            fused[key] = fused.get(key, 0.0) + 1.0 / (self.rrf_k + rank)
588        for rank, segment in enumerate(exact, start=1):
589            key = (segment.path, segment.start, segment.end)
590            fused[key] = fused.get(key, 0.0) + 1.0 / (self.rrf_k + rank)
591
592        by_key = {(s.path, s.start, s.end): s for s in list(lexical) + list(exact)}
593        ordered = sorted(fused.items(), key=lambda item: item[1], reverse=True)
594        return [(by_key[key], score) for key, score in _diversity(ordered, k, self.max_per_file, by_key)]
Case.required_pathsdef required_paths(self) -> tuple[str, ...]
Ver prueba
eval/harness.py#L620-L621
Anotaciones: @property
620    def required_paths(self) -> tuple[str, ...]:
621        return tuple(e.path for e in self.expected if not e.optional)
Case.retrieval_querydef retrieval_query(self, field: str=...) -> str
Ver prueba
eval/harness.py#L623-L626
623    def retrieval_query(self, field: str = "auto") -> str:
624        if field == "question" or not self.query:
625            return self.question
626        return self.query
Report._aggdef _agg(self, results: Sequence[CaseResult]) -> dict[str, float]
Ver prueba
eval/harness.py#L657-L672
657    def _agg(self, results: Sequence[CaseResult]) -> dict[str, float]:
658        if not results:
659            return {}
660        line_results = [r.line_hit for r in results if r.line_hit is not None]
661        symbol_results = [r.symbol_hit for r in results if r.symbol_hit is not None]
662        mode_results = [r.query_mode for r in results]
663        return {
664            "cases": len(results),
665            "recall": statistics.fmean(r.recall for r in results),
666            "hit_rate": sum(1 for r in results if r.hit) / len(results),
667            "mrr": statistics.fmean(r.mrr for r in results),
668            "line_accuracy": (sum(1 for x in line_results if x) / len(line_results)) if line_results else 0.0,
669            "symbol_rate": (sum(1 for x in symbol_results if x) / len(symbol_results)) if symbol_results else 0.0,
670            "mean_ms": statistics.fmean(r.elapsed_ms for r in results),
671            "mode_distribution": {m: mode_results.count(m) for m in set(mode_results)},
672        }
Report.overalldef overall(self) -> dict[str, float]
Ver prueba
eval/harness.py#L675-L676
Anotaciones: @property
675    def overall(self) -> dict[str, float]:
676        return self._agg(self.results)
Report.by_categorydef by_category(self) -> dict[str, dict[str, float]]
Ver prueba
eval/harness.py#L678-L680
678    def by_category(self) -> dict[str, dict[str, float]]:
679        categories = sorted({r.category for r in self.results})
680        return {cat: self._agg([r for r in self.results if r.category == cat]) for cat in categories}
Report.by_modedef by_mode(self) -> dict[str, dict[str, float]]
Ver prueba
eval/harness.py#L682-L685
682    def by_mode(self) -> dict[str, dict[str, float]]:
683        """Devuelve el _agg de cada modo de consulta para ver umbrales por separado."""
684        modes = sorted({r.query_mode for r in self.results})
685        return {mode: self._agg([r for r in self.results if r.query_mode == mode]) for mode in modes}
Report.to_dictdef to_dict(self) -> dict[str, object]
Ver prueba
eval/harness.py#L687-L730
687    def to_dict(self) -> dict[str, object]:
688        return {
689            "schema_version": self.schema_version,
690            "project": self.project,
691            "k": self.k,
692            "query_field": self.query_field,
693            "index_mode": self.index_mode,
694            "query_expansion": self.query_expansion,
695            "files": self.files,
696            "segments": self.segments,
697            "generated_at": self.generated_at,
698            "overall": self.overall,
699            "by_category": self.by_category(),
700            "by_mode": self.by_mode(),
701            "thresholds_by_mode": {
702                "identifier": {
703                    "recall": RECALL_THRESHOLDS["identifier"],
704                    "mrr": MRR_THRESHOLDS["identifier"],
705                },
706                "human": {
707                    "recall": RECALL_THRESHOLDS["human"],
708                    "mrr": MRR_THRESHOLDS["human"],
709                },
710                "mixed": {
711                    "recall": RECALL_THRESHOLDS["mixed"],
712                    "mrr": MRR_THRESHOLDS["mixed"],
713                },
714            },
715            "cases": [
716                {
717                    "case_id": r.case_id,
718                    "category": r.category,
719                    "recall": round(r.recall, 4),
720                    "hit": r.hit,
721                    "mrr": round(r.mrr, 4),
722                    "line_hit": r.line_hit,
723                    "symbol_hit": r.symbol_hit,
724                    "query_mode": r.query_mode,
725                    "passed": r.passed,
726                    "retrieved": list(r.retrieved),
Report.to_markdowndef to_markdown(self) -> str
Ver prueba
eval/harness.py#L732-L776
732    def to_markdown(self) -> str:
733        o = self.overall
734        lines = [
735            f"# F0 — Línea base de recuperación · {self.project}",
736            "",
737            f"Generado: {self.generated_at} · k={self.k} · {self.files} archivos · {self.segments} segmentos",
738            f"Índice: `{self.index_mode}` · consulta: `{self.query_field}` "
739            "(identificadores/inglés si es `query`; pregunta en español si es `question`)"
740            f" · expansión de consulta: `{'sí' if self.query_expansion else 'no'}`",
741            "",
742            "| Métrica | Valor |",
743            "|---|---|",
744            f"| recall@{self.k} | {o['recall']:.3f} |",
745            f"| hit@{self.k} | {o['hit_rate']:.3f} |",
746            f"| MRR | {o['mrr']:.3f} |",
747            f"| acierto de líneas | {o['line_accuracy']:.3f} |",
748            f"| símbolo-rate | {o['symbol_rate']:.3f} |",
749            f"| latencia media | {o['mean_ms']:.1f} ms |",
750            "",
751            "## Umbrales por modo de consulta",
752            "",
753            "| Modo | Recall mínimo | MRR mínimo |",
754            "|---|---|---|",
755            f"| identificador | {RECALL_THRESHOLDS['identifier']:.2f} | {MRR_THRESHOLDS['identifier']:.2f} |",
756            f"| humano | {RECALL_THRESHOLDS['human']:.2f} | {MRR_THRESHOLDS['human']:.2f} |",
757            f"| mixto | {RECALL_THRESHOLDS['mixed']:.2f} | {MRR_THRESHOLDS['mixed']:.2f} |",
758            "",
759            "## Por categoría",
760            "",
761            "| Categoría | Casos | recall | hit | MRR |",
762            "|---|---|---|---|---|",
763        ]
764        for cat, agg in self.by_category().items():
765            lines.append(
766                f"| {cat} | {int(agg['cases'])} | {agg['recall']:.3f} | "
767                f"{agg['hit_rate']:.3f} | {agg['mrr']:.3f} |"
768            )
769        lines += ["", "## Casos", "", "| Caso | Categoría | recall | hit | MRR | Top-1 recuperado |", "|---|---|---|---|---|---|"]
770        for result in self.results:
771            top = result.retrieved[0] if result.retrieved else "—"
_overlapsdef _overlaps(a: tuple[int, int], b: tuple[int, int]) -> bool
Ver prueba
eval/harness.py#L779-L780
779def _overlaps(a: tuple[int, int], b: tuple[int, int]) -> bool:
780    return not (a[1] < b[0] or b[1] < a[0])
_query_modedef _query_mode(case: Case) -> str
Ver prueba
eval/harness.py#L800-L815
800def _query_mode(case: Case) -> str:
801    """Determina el modo de consulta basándose en el contenido.
802
803    Si la query parece un identificador (tokens con punto, guión bajo, camelCase)
804    se considera modo *identifier*; si contiene palabras conectadas o acentos,
805    modo *human*. El modo *mixed* es un caso intermedio.
806    """
807    from eval.harness import _looks_like_identifier
808
809    query = case.query or case.question
810    if not query:
811        return "mixed"
812    if _looks_like_identifier(query):
813        return "identifier"
814    # Preguntas humanas naturales: contiene conectores, artículos, acentos
815    return "human"
evaluatedef evaluate(cases: Sequence[Case], index: object, k: int=..., query_field: str=..., expand: bool=...) -> list[CaseResult]
Ver prueba
eval/harness.py#L818-L897
818def evaluate(
819    cases: Sequence[Case],
820    index: object,
821    k: int = 10,
822    query_field: str = "auto",
823    expand: bool = False,
824) -> list[CaseResult]:
825    results: list[CaseResult] = []
826    for case in cases:
827        started = time.perf_counter()
828        query = case.retrieval_query(query_field)
829        if expand:
830            from docu.retrieve.glossary import expand as expand_query
831
832            query = expand_query(query)
833        hits = index.search(query, k=k)  # type: ignore[attr-defined]
834        elapsed_ms = (time.perf_counter() - started) * 1000
835
836        retrieved_paths = [seg.path for seg, _ in hits]
837        required = set(case.required_paths)
838
839        # --- Recall por paths (como antes) ---
840        found_paths = {path for path in required if path in retrieved_paths}
841        recall = len(found_paths) / len(required) if required else 0.0
842
843        # --- Acierto de símbolo: ¿algún segmento recuperado coincide exact_name con un expected? ---
844        # Tokenizamos la query y comparamos los exact_names de los segments recuperados
845        symbol_hit: bool | None = None
846        if required and any(e.symbol for e in case.expected if not e.optional):
847            # Extraer los exact_names de las expecteds primarias
848            primary_expected = [e for e in case.expected if not e.optional and e.symbol]
849            if primary_expected:
850                # Verificar si algún retrieved segment tiene matching exact_name
851                retrieved_names: set[str] = set()
852                for seg, _ in hits:
853                    retrieved_names.update(seg.exact_names or ())
854                # Un expected se "acierta" si su exact_name aparece en algún retrieved segment
855                symbol_hit = any(
856                    any(exp.symbol.lower() in retrieved_names for exp in primary_expected)
857                )
_validate_case_iddef _validate_case_id(case: Case) -> list[str]
Ver prueba
eval/harness.py#L903-L912
903def _validate_case_id(case: Case) -> list[str]:
904    """Validaciones basicas del golden set: ids unicos y categorías conocidas."""
905    errors: list[str] = []
906    if not case.id.strip():
907        errors.append("case sin id")
908    if not case.question.strip():
909        errors.append(f"case {case.id}: pregunta vacía")
910    if not case.expected:
911        errors.append(f"case {case.id}: sin evidencia esperada")
912    return errors
_validate_golden_setdef _validate_golden_set(cases: Sequence[Case]) -> list[str]
Ver prueba
eval/harness.py#L915-L953
915def _validate_golden_set(cases: Sequence[Case]) -> list[str]:
916    """F-06: validación del golden set antes de evaluar nada.
917
918    Detecta dos violaciones conocidas del formato:
919    - Evidencia **opcional** declarada en un caso con **evidencia primaria** (F-06): un ítem
920      `optional: true` es consumidor secundario, no contribuye al recall principal.
921    - Duplicados: la misma evidencia esperada dos veces en un caso contamina el cálculo
922      de recall (recuento inflado).
923
924    Devuelve una lista de mensajes de error; vacía = golden set válido.
925    """
926    errors: list[str] = []
927    seen_case_ids: set[str] = set()
928    for case in cases:
929        case_errors = _validate_case_id(case)
930        if case.id in seen_case_ids:
931            case_errors.append(f"duplicate case id: {case.id}")
932        seen_case_ids.add(case.id)
933        if case_errors:
934            errors.extend(case_errors)
935
936        seen_paths: set[str] = set()
937        primary_paths: set[str] = set()
938        for expected in case.expected:
939            if expected.path in seen_paths:
940                errors.append(
941                    f"case {case.id}: evidencia duplicada: {expected.path} (repeat)"
942                )
943            seen_paths.add(expected.path)
944            if not expected.optional:
945                primary_paths.add(expected.path)
946
947        for expected in case.expected:
948            if expected.optional and expected.path in primary_paths:
949                errors.append(
950                    f"case {case.id}: evidencia opcional ({expected.path}) duplica una primaria "
951                    f"o coexiste con ella; la opcional no debe contaminar el recall principal (F-06)"
952                )
953    return errors
load_goldendef load_golden(path: Path) -> tuple[str, str, list[Case]]
Ver prueba
eval/harness.py#L956-L985
956def load_golden(path: Path) -> tuple[str, str, list[Case]]:
957    payload = json.loads(path.read_text(encoding="utf-8"))
958    cases: list[Case] = []
959    for raw in payload["cases"]:
960        expected = tuple(
961            Expected(
962                path=item["path"],
963                symbol=item.get("symbol"),
964                lines=tuple(item["lines"]) if item.get("lines") else None,  # type: ignore[arg-type]
965                optional=bool(item.get("optional", False)),
966            )
967            for item in raw["expected"]
968        )
969        cases.append(
970            Case(
971                id=raw["id"],
972                category=raw.get("category", "general"),
973                question=raw["question"],
974                expected=expected,
975                answer=raw.get("answer", ""),
976                notes=raw.get("notes", ""),
977                query=raw.get("query", ""),
978            )
979        )
980    errors = _validate_golden_set(cases)
981    if errors:
982        raise ValueError(
983            "golden set invalido: " + "; ".join(errors)
984        )
985    return payload.get("project", path.stem), payload.get("repo", ""), cases
rundef run(golden_path: Path, repo: Path | None, k: int, out_dir: Path, quiet: bool=..., query_field: str=..., label: str=..., index_mode: str=..., model_dir: str=..., expand: bool=...) -> Report
Ver prueba
eval/harness.py#L991-L1059
991def run(
992    golden_path: Path,
993    repo: Path | None,
994    k: int,
995    out_dir: Path,
996    quiet: bool = False,
997    query_field: str = "auto",
998    label: str = "",
999    index_mode: str = "windows",
1000    model_dir: str = DEFAULT_MODEL_DIR,
1001    expand: bool = False,
1002) -> Report:
1003    project, repo_from_golden, cases = load_golden(golden_path)
1004    root = repo or Path(repo_from_golden)
1005    if not root.exists():
1006        raise SystemExit(f"error: repositorio no encontrado: {root}")
1007
1008    if index_mode == "hybrid":
1009        from docu.adapters.embedders.onnx_local import OnnxEmbedder
1010
1011        embedder = OnnxEmbedder(model_dir=model_dir)
1012        if not embedder.available:
1013            raise SystemExit(f"error: modelo ONNX no encontrado en {model_dir!r}")
1014        segments = build_symbol_corpus(root)
1015        index: AutoIndex | HybridIndex | SymbolIndex | BM25 = HybridIndex(
1016            segments=segments, embedder=embedder
1017        )
1018    elif index_mode == "auto":
1019        from docu.adapters.embedders.onnx_local import OnnxEmbedder
1020
1021        embedder = OnnxEmbedder(model_dir=model_dir)
1022        segments = build_symbol_corpus(root)
1023        index = AutoIndex(segments=segments, embedder=embedder if embedder.available else None)
1024    elif index_mode == "symbols":
1025        segments = build_symbol_corpus(root)
1026        index = SymbolIndex(segments=segments)
1027    else:
1028        segments = build_corpus(root)
1029        index = BM25(segments=segments)
1030    results = evaluate(cases, index, k=k, query_field=query_field, expand=expand)
maindef main(argv: Sequence[str] | None=...) -> int
Ver prueba
eval/harness.py#L1062-L1106
1062def main(argv: Sequence[str] | None = None) -> int:
1063    parser = argparse.ArgumentParser(description="Arnés de evaluación F0 de docu")
1064    parser.add_argument("--golden", required=True, help="ruta del golden set (.json)")
1065    parser.add_argument("--repo", default=None, help="sobrescribe el repo del golden set")
1066    parser.add_argument("--k", type=int, default=10)
1067    parser.add_argument("--out", default="eval/reports", help="directorio de informes")
1068    parser.add_argument(
1069        "--query-field",
1070        choices=["auto", "query", "question"],
1071        default="auto",
1072        help="qué texto se usa como consulta: identificadores (query) o la pregunta tal cual",
1073    )
1074    parser.add_argument(
1075        "--index",
1076        choices=["windows", "symbols", "hybrid", "auto"],
1077        default="windows",
1078        help="windows: ventanas (F0) · symbols: chunks + match exacto (F1) · hybrid: +denso · auto: enruta por consulta",
1079    )
1080    parser.add_argument(
1081        "--model-dir",
1082        default=DEFAULT_MODEL_DIR,
1083        help=f"directorio del modelo ONNX (default: {DEFAULT_MODEL_DIR})",
1084    )
1085    parser.add_argument("--label", default="", help="sufijo del nombre del informe")
1086    parser.add_argument(
1087        "--expand",
1088        action="store_true",
1089        help="expande la consulta con el glosario de dominio (eval/glossary.py)",
1090    )
1091    parser.add_argument("--quiet", action="store_true")
1092    args = parser.parse_args(argv)
1093
1094    report = run(
1095        Path(args.golden),
1096        Path(args.repo) if args.repo else None,
1097        args.k,
1098        Path(args.out),
1099        args.quiet,
1100        query_field=args.query_field,
1101        label=args.label,
resolve_model_dirdef resolve_model_dir(*roots) -> Path | None
Ver prueba
src/docu/adapters/embedders/onnx_local.py#L20-L36
20def resolve_model_dir(*roots: Path | str | None) -> Path | None:
21    """Busca el modelo ONNX sin obligar a configurarlo.
22
23    Orden: variable de entorno, `.models/` del proyecto, `.models/` del workspace, directorio
24    actual. Devolver `None` es un caso normal: el motor sigue funcionando sin canal denso.
25    """
26    import os
27
28    from_env = os.environ.get(MODEL_ENV_VAR)
29    if from_env and (Path(from_env) / "model.onnx").exists():
30        return Path(from_env)
31    candidates = [Path(root) / DEFAULT_MODEL_DIR for root in roots if root is not None]
32    candidates.append(Path(os.getcwd()) / DEFAULT_MODEL_DIR)
33    for candidate in candidates:
34        if (candidate / "model.onnx").exists() and (candidate / "tokenizer.json").exists():
35            return candidate
36    return None
OnnxEmbedder.dimdef dim(self) -> int
Ver prueba
src/docu/adapters/embedders/onnx_local.py#L53-L54
Anotaciones: @property
53    def dim(self) -> int:
54        return self._dim
OnnxEmbedder.availabledef available(self) -> bool
Ver prueba
src/docu/adapters/embedders/onnx_local.py#L57-L60
Anotaciones: @property
57    def available(self) -> bool:
58        return (Path(self.model_dir) / "model.onnx").exists() and (
59            Path(self.model_dir) / "tokenizer.json"
60        ).exists()
OnnxEmbedder._loaddef _load(self) -> None
Ver prueba
src/docu/adapters/embedders/onnx_local.py#L62-L83
62    def _load(self) -> None:
63        if self._session is not None:
64            return
65        if not self.available:
66            raise FileNotFoundError(
67                f"modelo ONNX no encontrado en {self.model_dir!r}; descarga tokenizer.json y model.onnx"
68            )
69        import onnxruntime as ort
70        from tokenizers import Tokenizer
71
72        directory = Path(self.model_dir)
73        tokenizer = Tokenizer.from_file(str(directory / "tokenizer.json"))
74        tokenizer.enable_truncation(max_length=self.max_length)
75        tokenizer.enable_padding(pad_id=0, pad_token="[PAD]")
76        options = ort.SessionOptions()
77        options.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL
78        session = ort.InferenceSession(
79            str(directory / "model.onnx"), options, providers=["CPUExecutionProvider"]
80        )
81        self._tokenizer = tokenizer
82        self._session = session
83        self._input_names = tuple(item.name for item in session.get_inputs())
OnnxEmbedder.embeddef embed(self, texts: Sequence[str]) -> list[list[float]]
Ver prueba
src/docu/adapters/embedders/onnx_local.py#L85-L104
85    def embed(self, texts: Sequence[str]) -> list[list[float]]:
86        self._load()
87        assert self._tokenizer is not None and self._session is not None
88        vectors: list[list[float]] = []
89        for start in range(0, len(texts), self.batch_size):
90            batch = list(texts[start : start + self.batch_size])
91            encodings = self._tokenizer.encode_batch(batch)
92            feed: dict[str, object] = {
93                "input_ids": [enc.ids for enc in encodings],
94                "attention_mask": [enc.attention_mask for enc in encodings],
95            }
96            if "token_type_ids" in self._input_names:
97                feed["token_type_ids"] = [enc.type_ids for enc in encodings]
98            outputs = self._session.run(None, feed)
99            hidden = outputs[0]
100            vectors.extend(
101                _mean_pool_normalize(hidden[index], encodings[index].attention_mask)
102                for index in range(len(batch))
103            )
104        return vectors
_mean_pool_normalizedef _mean_pool_normalize(token_vectors: Sequence[Sequence[float]], mask: Sequence[int]) -> list[float]
Ver prueba
src/docu/adapters/embedders/onnx_local.py#L107-L122
107def _mean_pool_normalize(token_vectors: Sequence[Sequence[float]], mask: Sequence[int]) -> list[float]:
108    """Media enmascarada + normalizacion L2: coseno equivalente a producto escalar."""
109    dim = len(token_vectors[0])
110    total = [0.0] * dim
111    count = 0
112    for vector, flag in zip(token_vectors, mask):
113        if not flag:
114            continue
115        count += 1
116        for index, value in enumerate(vector):
117            total[index] += value
118    if count == 0:
119        return total
120    pooled = [value / count for value in total]
121    norm = math.sqrt(sum(value * value for value in pooled)) or 1.0
122    return [value / norm for value in pooled]
cosinedef cosine(left: Sequence[float], right: Sequence[float]) -> float
Ver prueba
src/docu/adapters/embedders/onnx_local.py#L125-L129
125def cosine(left: Sequence[float], right: Sequence[float]) -> float:
126    """Similitud coseno; ambos lados vienen normalizados, pero se protege el caso general."""
127    dot = sum(a * b for a, b in zip(left, right))
128    norm = math.sqrt(sum(a * a for a in left)) * math.sqrt(sum(b * b for b in right))
129    return dot / norm if norm else 0.0
mask_sourcedef mask_source(source: str) -> str
Ver prueba
src/docu/adapters/langs/_braces.py#L12-L68
12def mask_source(source: str, *, template_literals: bool = True) -> str:
13    """Sustituye comentarios y literales por espacios, conservando los saltos de linea.
14
15    Sin esto, una llave dentro de un string o un template literal desalinea todo el analisis.
16    """
17    out = list(source)
18    i, n = 0, len(source)
19    quotes = '"\'`' if template_literals else '"\''
20    while i < n:
21        ch = source[i]
22        if ch == "/" and i + 1 < n and source[i + 1] == "/":
23            while i < n and source[i] != "\n":
24                out[i] = " "
25                i += 1
26        elif ch == "/" and i + 1 < n and source[i + 1] == "*":
27            out[i] = out[i + 1] = " "
28            i += 2
29            while i < n and not (source[i] == "*" and i + 1 < n and source[i + 1] == "/"):
30                if source[i] != "\n":
31                    out[i] = " "
32                i += 1
33            if i < n:
34                out[i] = " "
35                if i + 1 < n:
36                    out[i + 1] = " "
37                i += 2
38        elif source.startswith('"""', i):
39            out[i] = out[i + 1] = out[i + 2] = " "
40            i += 3
41            while i < n and not source.startswith('"""', i):
42                if source[i] != "\n":
43                    out[i] = " "
44                i += 1
45            if i < n:
46                out[i] = out[i + 1] = out[i + 2] = " "
47                i += 3
48        elif ch in quotes:
49            quote = ch
50            out[i] = " "
51            i += 1
depth_mapdef depth_map(masked: str) -> list[int]
Ver prueba
src/docu/adapters/langs/_braces.py#L71-L81
71def depth_map(masked: str) -> list[int]:
72    """`depth[i]` = llaves abiertas antes de la posicion `i`."""
73    depth = [0] * len(masked)
74    current = 0
75    for index, ch in enumerate(masked):
76        depth[index] = current
77        if ch == "{":
78            current += 1
79        elif ch == "}":
80            current -= 1
81    return depth
matching_bracedef matching_brace(masked: str, open_index: int) -> int
Ver prueba
src/docu/adapters/langs/_braces.py#L84-L95
84def matching_brace(masked: str, open_index: int) -> int:
85    """Indice de la llave de cierre correspondiente (o el final si esta desbalanceado)."""
86    level = 0
87    for index in range(open_index, len(masked)):
88        ch = masked[index]
89        if ch == "{":
90            level += 1
91        elif ch == "}":
92            level -= 1
93            if level == 0:
94                return index
95    return len(masked) - 1
mask_annotation_bracesdef mask_annotation_braces(masked: str) -> str
Ver prueba
src/docu/adapters/langs/_braces.py#L98-L124
98def mask_annotation_braces(masked: str) -> str:
99    """Anula las llaves que viven **dentro** de una anotacion.
100
101    `@ApiResponses(value = { @ApiResponse(...), ... })` usa llaves de Java real: si se dejan, el
102    conteo de profundidad cree que hay un bloque y todos los metodos posteriores quedan «dentro» de
103    la anotacion, con lo que se pierden el metodo y su ruta. FastAPI/NestJS no lo necesitan, pero
104    dañar el conteo cuesta caro; anular es barato.
105    """
106    out = list(masked)
107    index = 0
108    total = len(masked)
109    while index < total:
110        if masked[index] == "@":
111            cursor = index + 1
112            while cursor < total and (masked[cursor].isalnum() or masked[cursor] in "_."):
113                cursor += 1
114            while cursor < total and masked[cursor].isspace():
115                cursor += 1
116            if cursor < total and masked[cursor] == "(":
117                close = matching_paren(masked, cursor)
118                for position in range(cursor, close):
119                    if out[position] in "{}":
120                        out[position] = " "
121                index = close + 1
122                continue
123        index += 1
124    return "".join(out)
matching_parendef matching_paren(masked: str, open_index: int) -> int
Ver prueba
src/docu/adapters/langs/_braces.py#L127-L138
127def matching_paren(masked: str, open_index: int) -> int:
128    """Indice del parentesis de cierre correspondiente."""
129    level = 0
130    for index in range(open_index, len(masked)):
131        ch = masked[index]
132        if ch == "(":
133            level += 1
134        elif ch == ")":
135            level -= 1
136            if level == 0:
137                return index
138    return len(masked) - 1
iter_callablesdef iter_callables(masked: str, depth: list[int], level: int, start: int, end: int, skip: frozenset[str] | set[str] | tuple[str, ...]=...)
Ver prueba
src/docu/adapters/langs/_braces.py#L141-L201
141def iter_callables(
142    masked: str,
143    depth: list[int],
144    level: int,
145    start: int,
146    end: int,
147    skip: frozenset[str] | set[str] | tuple[str, ...] = (),
148):
149    """Recorre declaraciones `nombre(...) {` con **parentesis balanceados**.
150
151    Un regex `[^()]*` no sirve para Java ni TypeScript reales: los parametros llevan anotaciones
152    (`@RequestHeader(value = "X", required = false)`, `@Body() dto`) y sus parentesis anidados
153    rompen el patron, con lo que se pierde el metodo **y su ruta**. Aqui se camina el texto contando
154    parentesis, que es lo que hace cualquier parser de verdad.
155    """
156    skipset = set(skip)
157    index = start
158    while index < end:
159        if masked[index] != "(":
160            index += 1
161            continue
162        cursor = index - 1
163        while cursor >= start and masked[cursor].isspace():
164            cursor -= 1
165        name_end = cursor
166        while cursor >= start and (masked[cursor].isalnum() or masked[cursor] in "_$"):
167            cursor -= 1
168        name = masked[cursor + 1 : name_end + 1]
169        previous = masked[cursor] if cursor >= start else ""
170        if (
171            name
172            and name[0].isalpha()
173            and name not in skipset
174            and previous != "@"
175            and depth[index] == level
176        ):
177            close = matching_paren(masked, index)
178            tail = close + 1
179            while tail < end and masked[tail].isspace():
180                tail += 1
annotations_beforedef annotations_before(source: str, name_start: int) -> str
Ver prueba
src/docu/adapters/langs/_braces.py#L204-L230
204def annotations_before(source: str, name_start: int) -> str:
205    """Bloque de anotaciones inmediatamente encima de una declaracion.
206
207    Se lee hacia arriba por lineas y se aceptan continuaciones mientras queden parentesis o llaves
208    abiertas. `@ApiResponses(value = { ... })` ocupa varias lineas y contiene llaves: cortar en la
209    primera linea perderia tambien `@PostMapping` y, con el, la ruta.
210    """
211    lines = source.splitlines()
212    row = source.count("\n", 0, name_start) - 1
213    collected: list[str] = []
214    balance = 0
215    while row >= 0:
216        stripped = lines[row].strip()
217        if not stripped:
218            if balance > 0:
219                collected.append("")
220                row -= 1
221                continue
222            break
223        if balance > 0 or stripped.startswith("@"):
224            collected.append(stripped)
225            balance += stripped.count("(") + stripped.count("{")
226            balance -= stripped.count(")") + stripped.count("}")
227            row -= 1
228            continue
229        break
230    return "\n".join(reversed(collected))
Lines.__init__def __init__(self, source: str) -> None
Ver prueba
src/docu/adapters/langs/_braces.py#L236-L240
236    def __init__(self, source: str) -> None:
237        self.starts = [0]
238        for index, ch in enumerate(source):
239            if ch == "\n":
240                self.starts.append(index + 1)
Lines.line_ofdef line_of(self, offset: int) -> int
Ver prueba
src/docu/adapters/langs/_braces.py#L242-L250
242    def line_of(self, offset: int) -> int:
243        low, high = 0, len(self.starts) - 1
244        while low < high:
245            mid = (low + high + 1) // 2
246            if self.starts[mid] <= offset:
247                low = mid
248            else:
249                high = mid - 1
250        return low + 1
skip_whitespacedef skip_whitespace(text: str, start: int, limit: int) -> int
Ver prueba
src/docu/adapters/langs/_braces.py#L253-L258
253def skip_whitespace(text: str, start: int, limit: int) -> int:
254    """Avanza sobre espacios y saltos: la declaracion empieza en la primera anotacion o token."""
255    index = start
256    while index < limit and text[index].isspace():
257        index += 1
258    return index
declaration_startdef declaration_start(masked: str, depth: list[int], offset: int, floor: int, level: int) -> int
Ver prueba
src/docu/adapters/langs/_braces.py#L261-L278
261def declaration_start(masked: str, depth: list[int], offset: int, floor: int, level: int) -> int:
262    """Inicio de la declaracion que contiene `offset`.
263
264    Detalle que importa: la llave `{` que abre un metodo anterior tiene la **misma** profundidad
265    que el miembro actual, pero no es su inicio. La frontera real es el `}` de cierre de ese
266    miembro previo, una profundidad mas adentro.
267    """
268    index = offset - 1
269    while index > floor:
270        ch = masked[index]
271        if depth[index] == level and ch == ";":
272            return skip_whitespace(masked, index + 1, offset)
273        if depth[index] == level + 1 and ch == "}":
274            return skip_whitespace(masked, index + 1, offset)
275        if depth[index] == level and ch == "}":
276            break
277        index -= 1
278    return skip_whitespace(masked, floor, offset)
strip_comment_argsdef strip_comment_args(text: str) -> str
Ver prueba
src/docu/adapters/langs/_braces.py#L281-L282
281def strip_comment_args(text: str) -> str:
282    return re.sub(r"//.*$", "", text, flags=re.MULTILINE)
mask_sourcedef mask_source(source: str) -> str
Ver prueba
src/docu/adapters/langs/java.py#L59-L114
59def mask_source(source: str) -> str:
60    """Sustituye comentarios y literales por espacios, conservando saltos de linea.
61
62    Sin esto, una llave dentro de un string o de un comentario desalinea todo el analisis.
63    """
64    out = list(source)
65    i, n = 0, len(source)
66    while i < n:
67        ch = source[i]
68        if ch == "/" and i + 1 < n and source[i + 1] == "/":
69            while i < n and source[i] != "\n":
70                out[i] = " "
71                i += 1
72        elif ch == "/" and i + 1 < n and source[i + 1] == "*":
73            out[i] = out[i + 1] = " "
74            i += 2
75            while i < n and not (source[i] == "*" and i + 1 < n and source[i + 1] == "/"):
76                if source[i] != "\n":
77                    out[i] = " "
78                i += 1
79            if i < n:
80                out[i] = " "
81                if i + 1 < n:
82                    out[i + 1] = " "
83                i += 2
84        elif source.startswith('"""', i):
85            out[i] = out[i + 1] = out[i + 2] = " "
86            i += 3
87            while i < n and not source.startswith('"""', i):
88                if source[i] != "\n":
89                    out[i] = " "
90                i += 1
91            if i < n:
92                out[i] = out[i + 1] = out[i + 2] = " "
93                i += 3
94        elif ch in ('"', "'"):
95            quote = ch
96            out[i] = " "
97            i += 1
98            while i < n:
depth_mapdef depth_map(masked: str) -> list[int]
Ver prueba
src/docu/adapters/langs/java.py#L117-L127
117def depth_map(masked: str) -> list[int]:
118    """`depth[i]` = llaves abiertas antes de la posicion `i`."""
119    depth = [0] * len(masked)
120    current = 0
121    for index, ch in enumerate(masked):
122        depth[index] = current
123        if ch == "{":
124            current += 1
125        elif ch == "}":
126            current -= 1
127    return depth
matching_bracedef matching_brace(masked: str, open_index: int) -> int
Ver prueba
src/docu/adapters/langs/java.py#L130-L141
130def matching_brace(masked: str, open_index: int) -> int:
131    """Indice de la llave de cierre correspondiente (o el final si esta desbalanceado)."""
132    level = 0
133    for index in range(open_index, len(masked)):
134        ch = masked[index]
135        if ch == "{":
136            level += 1
137        elif ch == "}":
138            level -= 1
139            if level == 0:
140                return index
141    return len(masked) - 1
_Lines.__init__def __init__(self, source: str) -> None
Ver prueba
src/docu/adapters/langs/java.py#L147-L151
147    def __init__(self, source: str) -> None:
148        self.starts = [0]
149        for index, ch in enumerate(source):
150            if ch == "\n":
151                self.starts.append(index + 1)
_Lines.line_ofdef line_of(self, offset: int) -> int
Ver prueba
src/docu/adapters/langs/java.py#L153-L161
153    def line_of(self, offset: int) -> int:
154        low, high = 0, len(self.starts) - 1
155        while low < high:
156            mid = (low + high + 1) // 2
157            if self.starts[mid] <= offset:
158                low = mid
159            else:
160                high = mid - 1
161        return low + 1
annotation_namesdef annotation_names(text: str) -> tuple[str, ...]
Ver prueba
src/docu/adapters/langs/java.py#L164-L166
164def annotation_names(text: str) -> tuple[str, ...]:
165    """Nombres de anotacion (`@Service`), sin argumentos."""
166    return tuple(f"@{name}" for name, _args in _ANNOTATION_RE.findall(text))
route_ofdef route_of(annotation: str, args: str | None) -> tuple[str, str | None] | None
Ver prueba
src/docu/adapters/langs/java.py#L169-L181
169def route_of(annotation: str, args: str | None) -> tuple[str, str | None] | None:
170    """(verbo, ruta) si la anotacion es de Spring MVC; `None` en caso contrario."""
171    if annotation not in HTTP_MAPPINGS:
172        return None
173    literal: str | None = None
174    if args:
175        found = _STRING_RE.search(args)
176        literal = found.group(1) if found else None
177    verb = HTTP_MAPPINGS[annotation]
178    if verb is None:
179        explicit = re.search(r"RequestMethod\.([A-Z]+)", args or "")
180        verb = explicit.group(1) if explicit else "ANY"
181    return verb, literal
class_level_routedef class_level_route(text: str) -> str | None
Ver prueba
src/docu/adapters/langs/java.py#L184-L190
184def class_level_route(text: str) -> str | None:
185    """Ruta base declarada con `@RequestMapping` a nivel de tipo."""
186    for annotation, args in _ANNOTATION_RE.findall(text):
187        mapping = route_of(annotation, args)
188        if mapping and mapping[1]:
189            return mapping[1]
190    return None
join_pathsdef join_paths(base: str | None, suffix: str | None) -> str
Ver prueba
src/docu/adapters/langs/java.py#L193-L201
193def join_paths(base: str | None, suffix: str | None) -> str:
194    """Une base y ruta y normaliza a una ruta HTTP con barra inicial."""
195    if not base:
196        combined = suffix or "/"
197    elif not suffix:
198        combined = base
199    else:
200        combined = base.rstrip("/") + "/" + suffix.lstrip("/")
201    return "/" + combined.lstrip("/")
_strip_annotationsdef _strip_annotations(text: str) -> str
Ver prueba
src/docu/adapters/langs/java.py#L204-L205
204def _strip_annotations(text: str) -> str:
205    return _ANNOTATION_RE.sub(" ", text)
_java_fieldsdef _java_fields(masked: str, source: str, depth: list[int], level: int, open_brace: int, close_brace: int, type_name: str, path: str, lines: _Lines) -> list[Symbol]
Ver prueba
src/docu/adapters/langs/java.py#L208-L267
208def _java_fields(
209    masked: str,
210    source: str,
211    depth: list[int],
212    level: int,
213    open_brace: int,
214    close_brace: int,
215    type_name: str,
216    path: str,
217    lines: _Lines,
218) -> list[Symbol]:
219    """Campos declarados en el cuerpo del tipo.
220
221    Sin campos no hay diccionario de datos ni ERD: el documento podía decir «qué métodos tiene»
222    pero no «qué datos guarda», que es la mitad de lo que un equipo necesita para integrarse.
223    """
224    fields: list[Symbol] = []
225    boundary = open_brace + 1
226    index = open_brace + 1
227    while index < close_brace:
228        char = masked[index]
229        if char == "{" and depth[index] == level - 1:
230            # Bloque anidado (tipo interno, inicializador o cuerpo de método): se salta entero.
231            index = matching_brace(masked, index) + 1
232            boundary = index
233            continue
234        if char == ";" and depth[index] == level:
235            statement = masked[boundary:index]
236            raw = source[boundary:index]
237            boundary = index + 1
238            cleaned = " ".join(_strip_annotations(statement).split())
239            if not cleaned or "(" in cleaned.split("=", 1)[0]:
240                index += 1
241                continue
242            head = cleaned.split("=", 1)[0].strip()
243            tokens = [token for token in head.split() if token not in FIELD_MODIFIERS]
244            if len(tokens) < 2:
245                index += 1
246                continue
247            name = tokens[-1]
_record_fieldsdef _record_fields(masked: str, source: str, type_name: str, path: str, match_end: int, lines: _Lines) -> list[Symbol]
Ver prueba
src/docu/adapters/langs/java.py#L270-L317
270def _record_fields(
271    masked: str,
272    source: str,
273    type_name: str,
274    path: str,
275    match_end: int,
276    lines: _Lines,
277) -> list[Symbol]:
278    """Componentes de un `record`: son sus campos, aunque vivan en la firma."""
279    paren = masked.find("(", match_end)
280    if paren == -1:
281        return []
282    close = matching_paren(masked, paren)
283    body = source[paren + 1 : close]
284    fields: list[Symbol] = []
285    depth = 0
286    chunk: list[str] = []
287    for char in body + ",":
288        if char in "(<[":
289            depth += 1
290        elif char in ")>]":
291            depth -= 1
292        if char == "," and depth == 0:
293            component = " ".join("".join(chunk).split())
294            chunk = []
295            if not component:
296                continue
297            cleaned = _strip_annotations(component)
298            tokens = [token for token in cleaned.split() if token not in FIELD_MODIFIERS]
299            if len(tokens) < 2:
300                continue
301            name = tokens[-1]
302            line = lines.line_of(source.find(name, paren))
303            fields.append(
304                Symbol(
305                    name=name,
306                    qualname=f"{type_name}.{name}",
307                    kind=SymbolKind.FIELD,
308                    path=path,
309                    line_start=line,
_annotation_blockdef _annotation_block(source: str, start: int, end: int) -> tuple[str, int]
Ver prueba
src/docu/adapters/langs/java.py#L320-L331
320def _annotation_block(source: str, start: int, end: int) -> tuple[str, int]:
321    """Anotaciones entre dos posiciones y offset donde empieza la primera.
322
323    Se toma el tramo completo entre el final del miembro anterior y el nombre actual: es
324    deterministico y evita adivinar donde acaba un bloque multilinea como
325    `@ApiResponses(value = { ... })`.
326    """
327    segment = source[start:end]
328    position = segment.find("@")
329    if position < 0:
330        return "", end
331    return segment[position:], start + position
_declaration_startdef _declaration_start(masked: str, depth: list[int], offset: int, floor: int, level: int) -> int
Ver prueba
src/docu/adapters/langs/java.py#L334-L351
334def _declaration_start(masked: str, depth: list[int], offset: int, floor: int, level: int) -> int:
335    """Inicio de la declaracion que contiene `offset`.
336
337    Reglas de frontera, y el detalle que importa: la llave `{` que abre un metodo anterior
338    tiene la **misma** profundidad que el miembro actual, pero no es su inicio. La frontera
339    real es el `}` de cierre de ese miembro previo, que vive una profundidad mas adentro.
340    """
341    index = offset - 1
342    while index > floor:
343        ch = masked[index]
344        if depth[index] == level and ch == ";":
345            return _skip_whitespace(masked, index + 1, offset)
346        if depth[index] == level + 1 and ch == "}":
347            return _skip_whitespace(masked, index + 1, offset)
348        if depth[index] == level and ch == "}":
349            break
350        index -= 1
351    return _skip_whitespace(masked, floor, offset)
_skip_whitespacedef _skip_whitespace(text: str, start: int, limit: int) -> int
Ver prueba
src/docu/adapters/langs/java.py#L354-L359
354def _skip_whitespace(text: str, start: int, limit: int) -> int:
355    """Avanza sobre espacios y saltos: la declaracion empieza en la primera anotacion o token."""
356    index = start
357    while index < limit and text[index].isspace():
358        index += 1
359    return index
JavaLangAdapter.symbolsdef symbols(self, path: str, source: str) -> tuple[Symbol, ...]
Ver prueba
src/docu/adapters/langs/java.py#L374-L469
374    def symbols(self, path: str, source: str) -> tuple[Symbol, ...]:
375        masked = mask_annotation_braces(mask_source(source))
376        depth = depth_map(masked)
377        lines = _Lines(source)
378        routes: list[Symbol] = []
379        types: list[tuple[Symbol, int, int]] = []  # (simbolo, offset inicio, offset fin)
380        previous_end = 0
381
382        for match in _TYPE_RE.finditer(masked):
383            keyword, name = match.group(1), match.group(2)
384            if masked[max(0, match.start() - 1)] == ".":
385                continue  # `Foo.class` no es una declaracion
386            open_brace = masked.find("{", match.end())
387            if open_brace == -1:
388                continue
389            close_brace = matching_brace(masked, open_brace)
390            level = depth[open_brace]
391            decl_start = _declaration_start(masked, depth, match.start(), 0, level)
392            annotation_text, annotation_offset = _annotation_block(source, previous_end, match.start())
393            annotations = annotation_names(annotation_text)
394            base_route = class_level_route(annotation_text)
395            type_line = lines.line_of(decl_start)
396            if annotation_text:
397                type_line = min(type_line, lines.line_of(annotation_offset))
398            previous_end = close_brace + 1
399
400            children, member_routes = self._members(
401                path=path,
402                source=source,
403                masked=masked,
404                depth=depth,
405                lines=lines,
406                level=level + 1,
407                open_brace=open_brace,
408                close_brace=close_brace,
409                type_name=name,
410                base_route=base_route,
411            )
412            fields = _java_fields(
413                masked,
JavaLangAdapter._membersdef _members(self) -> tuple[list[Symbol], list[Symbol]]
Ver prueba
src/docu/adapters/langs/java.py#L471-L557
471    def _members(
472        self,
473        *,
474        path: str,
475        source: str,
476        masked: str,
477        depth: list[int],
478        lines: _Lines,
479        level: int,
480        open_brace: int,
481        close_brace: int,
482        type_name: str,
483        base_route: str | None,
484    ) -> tuple[list[Symbol], list[Symbol]]:
485        members: list[Symbol] = []
486        routes: list[Symbol] = []
487        previous_end = open_brace + 1
488        for name, paren_open, _paren_close, tail_index in iter_callables(
489            masked, depth, level, open_brace + 1, close_brace, CONTROL_WORDS
490        ):
491            if masked[tail_index] == ";":
492                continue  # firma sin cuerpo: no es un metodo documentable
493
494            # Inicio del nombre: retroceder sobre espacios desde el parentesis de apertura.
495            cursor = paren_open - 1
496            while cursor > open_brace and masked[cursor].isspace():
497                cursor -= 1
498            name_start = cursor - len(name) + 1
499
500            # `record Request(...)` o `new Thing(...)` no son metodos: la palabra previa lo dice.
501            word_end = name_start - 1
502            while word_end > open_brace and masked[word_end].isspace():
503                word_end -= 1
504            word_start = word_end
505            while word_start > open_brace and (masked[word_start].isalnum() or masked[word_start] in "_$"):
506                word_start -= 1
507            if masked[word_start + 1 : word_end + 1] in NOT_METHODS:
508                # Saltar el bloque completo para que la proxima anotacion no herede estas lineas.
509                previous_end = (
510                    matching_brace(masked, tail_index) + 1 if masked[tail_index] == "{" else tail_index + 1
JavaLangAdapter.importsdef imports(self, path: str, source: str) -> tuple[str, ...]
Ver prueba
src/docu/adapters/langs/java.py#L561-L563
561    def imports(self, path: str, source: str) -> tuple[str, ...]:
562        masked = mask_source(source)
563        return tuple(fqn for fqn, _star in _IMPORT_RE.findall(masked))
JavaLangAdapter.callsdef calls(self, path: str, source: str) -> tuple[tuple[str, str], ...]
Ver prueba
src/docu/adapters/langs/java.py#L565-L590
565    def calls(self, path: str, source: str) -> tuple[tuple[str, str], ...]:
566        """Aristas (llamador, llamado) solo entre metodos declarados en el mismo archivo.
567
568        Cota deliberada: sin resolucion de tipos, atribuir llamadas a otros archivos produciria
569        aristas falsas y diagramas que mienten.
570        """
571        masked = mask_source(source)
572        declared: set[str] = set()
573        for symbol in self.symbols(path, source):
574            if symbol.kind is SymbolKind.METHOD:
575                declared.add(symbol.name)
576            for child in symbol.children:
577                if child.kind is SymbolKind.METHOD:
578                    declared.add(child.name)
579        edges: list[tuple[str, str]] = []
580        for match in _TYPE_RE.finditer(masked):
581            open_brace = masked.find("{", match.end())
582            if open_brace == -1:
583                continue
584            close_brace = matching_brace(masked, open_brace)
585            type_name = match.group(2)
586            for call in _CALL_RE.finditer(masked, open_brace, close_brace):
587                callee = call.group(1)
588                if callee in declared and callee != type_name:
589                    edges.append((type_name, callee))
590        return tuple(dict.fromkeys(edges))
PythonLangAdapter.symbolsdef symbols(self, path: str, source: str) -> tuple[Symbol, ...]
Ver prueba
src/docu/adapters/langs/python.py#L27-L39
27    def symbols(self, path: str, source: str) -> tuple[Symbol, ...]:
28        try:
29            tree = ast.parse(source)
30        except SyntaxError:
31            return ()
32
33        found: list[Symbol] = []
34        for node in tree.body:
35            symbol = self._module_member(path, node, container=None)
36            if symbol is not None:
37                found.append(symbol)
38            found.extend(self._routes(path, node, container=None))
39        return tuple(found)
PythonLangAdapter._module_memberdef _module_member(self, path: str, node: ast.AST, container: str | None) -> Symbol | None
Ver prueba
src/docu/adapters/langs/python.py#L41-L81
41    def _module_member(
42        self, path: str, node: ast.AST, container: str | None
43    ) -> Symbol | None:
44        if isinstance(node, ast.ClassDef):
45            children = tuple(
46                child
47                for child in (
48                    self._module_member(path, item, container=node.name) for item in node.body
49                )
50                if child is not None
51            )
52            fields = tuple(
53                field
54                for field in (
55                    self._class_field(path, item, container=node.name) for item in node.body
56                )
57                if field is not None
58            )
59            return Symbol(
60                name=node.name,
61                qualname=node.name if container is None else f"{container}.{node.name}",
62                kind=SymbolKind.CLASS,
63                path=path,
64                line_start=node.lineno,
65                line_end=getattr(node, "end_lineno", node.lineno),
66                signature=f"class {node.name}({', '.join(_base_name(base) for base in node.bases)})",
67                children=fields + children,
68                annotations=self._decorators(node),
69            )
70        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
71            return Symbol(
72                name=node.name,
73                qualname=node.name if container is None else f"{container}.{node.name}",
74                kind=SymbolKind.METHOD if container else SymbolKind.FUNCTION,
75                path=path,
76                line_start=node.lineno,
77                line_end=getattr(node, "end_lineno", node.lineno),
78                signature=_signature(node),
79                annotations=self._decorators(node),
80            )
PythonLangAdapter._class_fielddef _class_field(self, path: str, node: ast.AST, container: str) -> Symbol | None
Ver prueba
src/docu/adapters/langs/python.py#L83-L117
83    def _class_field(self, path: str, node: ast.AST, container: str) -> Symbol | None:
84        """Campo de clase: `nombre: Tipo` (anotado) o `nombre = valor` (sin tipo).
85
86        Los tipos declarados son la materia prima del diccionario de datos y del ERD: sin ellos el
87        documento describe métodos pero no datos, que es la mitad de una integración.
88        """
89        if isinstance(node, ast.AnnAssign):
90            if not isinstance(node.target, ast.Name):
91                return None
92            annotation = ast.unparse(node.annotation)
93            return Symbol(
94                name=node.target.id,
95                qualname=f"{container}.{node.target.id}",
96                kind=SymbolKind.FIELD,
97                path=path,
98                line_start=node.lineno,
99                line_end=getattr(node, "end_lineno", node.lineno),
100                signature=annotation,
101                annotations=(),
102            )
103        if isinstance(node, ast.Assign):
104            names = [target.id for target in node.targets if isinstance(target, ast.Name)]
105            if len(names) != 1 or names[0].isupper():  # constantes de módulo: no son entidades
106                return None
107            return Symbol(
108                name=names[0],
109                qualname=f"{container}.{names[0]}",
110                kind=SymbolKind.FIELD,
111                path=path,
112                line_start=node.lineno,
113                line_end=getattr(node, "end_lineno", node.lineno),
114                signature="",
115                annotations=(),
116            )
117        return None
PythonLangAdapter._decoratorsdef _decorators(self, node: ast.AST) -> tuple[str, ...]
Ver prueba
src/docu/adapters/langs/python.py#L119-L121
119    def _decorators(self, node: ast.AST) -> tuple[str, ...]:
120        decorators = getattr(node, "decorator_list", ())
121        return tuple(f"@{_decorator_name(item)}" for item in decorators)
PythonLangAdapter._routesdef _routes(self, path: str, node: ast.AST, container: str | None) -> list[Symbol]
Ver prueba
src/docu/adapters/langs/python.py#L123-L151
123    def _routes(self, path: str, node: ast.AST, container: str | None) -> list[Symbol]:
124        """Rutas HTTP declaradas por decorador (FastAPI/Flask)."""
125        routes: list[Symbol] = []
126        for decorator in getattr(node, "decorator_list", ()):
127            target = decorator.func if isinstance(decorator, ast.Call) else decorator
128            name = _decorator_name(target)
129            short = name.rsplit(".", 1)[-1].lower()
130            if short not in HTTP_DECORATORS:
131                continue
132            verb, route = _route_of(short, decorator)
133            if route is None:
134                continue
135            qualname = node.name if container is None else f"{container}.{node.name}"
136            routes.append(
137                Symbol(
138                    name=f"{verb} {route}",
139                    qualname=qualname,
140                    kind=SymbolKind.HTTP_ROUTE,
141                    path=path,
142                    line_start=getattr(decorator, "lineno", node.lineno),
143                    line_end=getattr(node, "lineno", getattr(decorator, "lineno", 0)),
144                    signature=_signature(node) if isinstance(node, ast.AST) else "",
145                    annotations=(f"@{name}",),
146                )
147            )
148        if isinstance(node, ast.ClassDef):
149            for item in node.body:
150                routes.extend(self._routes(path, item, container=node.name))
151        return routes
PythonLangAdapter.importsdef imports(self, path: str, source: str) -> tuple[str, ...]
Ver prueba
src/docu/adapters/langs/python.py#L155-L166
155    def imports(self, path: str, source: str) -> tuple[str, ...]:
156        try:
157            tree = ast.parse(source)
158        except SyntaxError:
159            return ()
160        modules: list[str] = []
161        for node in ast.walk(tree):
162            if isinstance(node, ast.Import):
163                modules.extend(alias.name for alias in node.names)
164            elif isinstance(node, ast.ImportFrom) and node.module:
165                modules.append(node.module)
166        return tuple(dict.fromkeys(modules))
PythonLangAdapter.callsdef calls(self, path: str, source: str) -> tuple[tuple[str, str], ...]
Ver prueba
src/docu/adapters/langs/python.py#L168-L200
168    def calls(self, path: str, source: str) -> tuple[tuple[str, str], ...]:
169        """Aristas (llamador, llamado) entre funciones declaradas en el mismo archivo.
170
171        Se atribuye la llamada a la funcion **mas interna** que la contiene; sin resolucion de
172        tipos, atribuirla a otra cosa produciria aristas falsas.
173        """
174        try:
175            tree = ast.parse(source)
176        except SyntaxError:
177            return ()
178        functions = _function_table(tree)
179        by_short: dict[str, list[str]] = {}
180        for qualname, _start, _end in functions:
181            by_short.setdefault(qualname.rsplit(".", 1)[-1], []).append(qualname)
182        edges: list[tuple[str, str]] = []
183        for node in ast.walk(tree):
184            if not isinstance(node, ast.Call):
185                continue
186            callee = _call_name(node.func)
187            if not callee or callee not in by_short:
188                continue
189            # Se prefiere el nombre calificado cuando es unico: `service.create()` es
190            # `OrderService.create`, no `create`.
191            resolved = by_short[callee][0] if len(by_short[callee]) == 1 else callee
192            line = getattr(node, "lineno", 0)
193            candidates = sorted(
194                (end - start, qualname)
195                for qualname, start, end in functions
196                if start <= line <= end and qualname != resolved
197            )
198            if candidates:
199                edges.append((candidates[0][1], resolved))
200        return tuple(dict.fromkeys(edges))
_base_namedef _base_name(node: ast.AST) -> str
Ver prueba
src/docu/adapters/langs/python.py#L206-L211
206def _base_name(node: ast.AST) -> str:
207    if isinstance(node, ast.Name):
208        return node.id
209    if isinstance(node, ast.Attribute):
210        return f"{_base_name(node.value)}.{node.attr}"
211    return "?"
_decorator_namedef _decorator_name(node: ast.AST) -> str
Ver prueba
src/docu/adapters/langs/python.py#L214-L221
214def _decorator_name(node: ast.AST) -> str:
215    if isinstance(node, ast.Call):
216        return _decorator_name(node.func)
217    if isinstance(node, ast.Attribute):
218        return f"{_decorator_name(node.value)}.{node.attr}"
219    if isinstance(node, ast.Name):
220        return node.id
221    return "?"
_route_ofdef _route_of(short: str, decorator: ast.AST) -> tuple[str, str | None]
Ver prueba
src/docu/adapters/langs/python.py#L224-L244
224def _route_of(short: str, decorator: ast.AST) -> tuple[str, str | None]:
225    """(verbo, ruta) desde el decorador, incluido `methods=[...]` de Flask."""
226    verb = short.upper() if short != "route" else "ANY"
227    route: str | None = None
228    if isinstance(decorator, ast.Call):
229        for argument in decorator.args:
230            if isinstance(argument, ast.Constant) and isinstance(argument.value, str):
231                route = argument.value
232                break
233        for keyword in decorator.keywords:
234            if keyword.arg == "path" and isinstance(keyword.value, ast.Constant):
235                route = keyword.value.value
236            if keyword.arg == "methods" and isinstance(keyword.value, ast.List):
237                methods = [
238                    element.value
239                    for element in keyword.value.elts
240                    if isinstance(element, ast.Constant) and isinstance(element.value, str)
241                ]
242                if methods:
243                    verb = methods[0].upper()
244    return verb, route
_signaturedef _signature(node: ast.AST) -> str
Ver prueba
src/docu/adapters/langs/python.py#L247-L264
247def _signature(node: ast.AST) -> str:
248    if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
249        return ""
250    args = node.args
251    parts: list[str] = []
252    positional = [*args.posonlyargs, *args.args]
253    defaults = [None] * (len(positional) - len(args.defaults)) + list(args.defaults)
254    for argument, default in zip(positional, defaults):
255        annotation = f": {ast.unparse(argument.annotation)}" if argument.annotation else ""
256        suffix = "=..." if default is not None else ""
257        parts.append(f"{argument.arg}{annotation}{suffix}")
258    if args.vararg:
259        parts.append(f"*{args.vararg.arg}")
260    if args.kwarg:
261        parts.append(f"**{args.kwarg.arg}")
262    prefix = "async def" if isinstance(node, ast.AsyncFunctionDef) else "def"
263    returns = f" -> {ast.unparse(node.returns)}" if node.returns else ""
264    return f"{prefix} {node.name}({', '.join(parts)}){returns}"
_call_namedef _call_name(node: ast.AST) -> str | None
Ver prueba
src/docu/adapters/langs/python.py#L267-L272
267def _call_name(node: ast.AST) -> str | None:
268    if isinstance(node, ast.Name):
269        return node.id
270    if isinstance(node, ast.Attribute):
271        return node.attr
272    return None
_function_tabledef _function_table(tree: ast.AST) -> list[tuple[str, int, int]]
Ver prueba
src/docu/adapters/langs/python.py#L275-L294
275def _function_table(tree: ast.AST) -> list[tuple[str, int, int]]:
276    """(nombre calificado, linea inicio, linea fin) de cada funcion, con su clase contenedora."""
277    table: list[tuple[str, int, int]] = []
278
279    def visit(node: ast.AST, prefix: str) -> None:
280        if isinstance(node, ast.ClassDef):
281            for child in node.body:
282                visit(child, f"{prefix}.{node.name}" if prefix else node.name)
283            return
284        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
285            qualname = f"{prefix}.{node.name}" if prefix else node.name
286            table.append((qualname, node.lineno, getattr(node, "end_lineno", node.lineno)))
287            for child in node.body:
288                visit(child, qualname)
289            return
290        for child in ast.iter_child_nodes(node):
291            visit(child, prefix)
292
293    visit(tree, "")
294    return table
adapter_fordef adapter_for(path: str) -> object | None
Ver prueba
src/docu/adapters/langs/registry.py#L16-L22
16def adapter_for(path: str) -> object | None:
17    """Adaptador cuyo glob casa con la ruta, o `None` si el lenguaje no esta soportado."""
18    for adapter in ADAPTERS:
19        for glob in adapter.file_globs:  # type: ignore[attr-defined]
20            if path.endswith(glob.lstrip("*")):
21                return adapter
22    return None
supported_languagesdef supported_languages() -> tuple[str, ...]
Ver prueba
src/docu/adapters/langs/registry.py#L25-L26
25def supported_languages() -> tuple[str, ...]:
26    return tuple(adapter.language for adapter in ADAPTERS)  # type: ignore[attr-defined]
TypeScriptLangAdapter.symbolsdef symbols(self, path: str, source: str) -> tuple[Symbol, ...]
Ver prueba
src/docu/adapters/langs/typescript.py#L93-L189
93    def symbols(self, path: str, source: str) -> tuple[Symbol, ...]:
94        masked = mask_annotation_braces(mask_source(source))
95        depth = depth_map(masked)
96        lines = Lines(source)
97        found: list[Symbol] = []
98        previous_end = 0
99
100        for match in _TYPE_RE.finditer(masked):
101            open_brace = masked.find("{", match.end())
102            if open_brace == -1:
103                continue
104            close_brace = matching_brace(masked, open_brace)
105            level = depth[open_brace]
106            decl_start = declaration_start(masked, depth, match.start(), 0, level)
107            kind = {
108                "class": SymbolKind.CLASS,
109                "interface": SymbolKind.INTERFACE,
110                "enum": SymbolKind.ENUM,
111            }[match.group(1)]
112            annotation_text, annotation_offset = _annotation_block(source, previous_end, match.start())
113            annotations = _decorators_in(annotation_text)
114            previous_end = close_brace + 1
115            type_line = lines.line_of(decl_start)
116            if annotation_text:
117                type_line = min(type_line, lines.line_of(annotation_offset))
118
119            children, routes = self._members(
120                path=path,
121                source=source,
122                masked=masked,
123                depth=depth,
124                lines=lines,
125                level=level + 1,
126                open_brace=open_brace,
127                close_brace=close_brace,
128                type_name=match.group(2),
129                base_route=_class_route(annotations),
130            )
131            found.extend(routes)
132            found.append(
TypeScriptLangAdapter._membersdef _members(self) -> tuple[list[Symbol], list[Symbol]]
Ver prueba
src/docu/adapters/langs/typescript.py#L191-L325
191    def _members(
192        self,
193        *,
194        path: str,
195        source: str,
196        masked: str,
197        depth: list[int],
198        lines: Lines,
199        level: int,
200        open_brace: int,
201        close_brace: int,
202        type_name: str,
203        base_route: str | None,
204    ) -> tuple[list[Symbol], list[Symbol]]:
205        members: list[Symbol] = []
206        routes: list[Symbol] = []
207        previous_end = open_brace + 1
208        seen: set[str] = set()
209
210        for name, paren_open, _paren_close, tail_index in iter_callables(
211            masked, depth, level, open_brace + 1, close_brace, CONTROL_WORDS
212        ):
213            if masked[tail_index] == ";":
214                continue  # firma sin cuerpo
215            cursor = paren_open - 1
216            while cursor > open_brace and masked[cursor].isspace():
217                cursor -= 1
218            name_start = cursor - len(name) + 1
219
220            # `new Foo(` o `interface Foo(` no son metodos.
221            word_end = name_start - 1
222            while word_end > open_brace and masked[word_end].isspace():
223                word_end -= 1
224            word_start = word_end
225            while word_start > open_brace and (masked[word_start].isalnum() or masked[word_start] in "_$"):
226                word_start -= 1
227            if masked[word_start + 1 : word_end + 1] in NOT_METHODS:
228                previous_end = (
229                    matching_brace(masked, tail_index) + 1 if masked[tail_index] == "{" else tail_index + 1
230                )
TypeScriptLangAdapter._express_routesdef _express_routes(self, path: str, source: str, masked: str, lines: Lines) -> list[Symbol]
Ver prueba
src/docu/adapters/langs/typescript.py#L327-L405
327    def _express_routes(self, path: str, source: str, masked: str, lines: Lines) -> list[Symbol]:
328        """Rutas declaradas por llamada (`app.get('/x', ...)`) o por comparación de ruta.
329
330        Segunda forma, muy común en servidores Node sin framework: `if (pathname === '/api/x' &&
331        req.method === 'GET')`. Se detecta el literal y el verbo del mismo `if`; si no hay verbo,
332        la ruta se documenta como `ANY`. Es una inferencia: el `handler` lo dice.
333        """
334        routes: list[Symbol] = []
335        seen: set[tuple[str, str]] = set()
336
337        # Se busca sobre el texto original (hacen falta los literales) y se descarta lo que cae
338        # dentro de comentarios o cadenas comprobando que el identificador sigue visible en el
339        # texto enmascarado.
340        def is_code(position: int) -> bool:
341            return position < len(masked) and masked[position] == source[position]
342
343        for match in EXPRESS_ROUTE_RE.finditer(source):
344            if not is_code(match.start()):
345                continue
346            literal = _STRING_RE.match(source, match.end())
347            if literal is None:
348                continue
349            verb = match.group("verb").upper()
350            if verb == "USE":
351                verb = "ANY"
352            route = "/" + literal.group(1).lstrip("/")
353            if (verb, route) in seen:
354                continue
355            seen.add((verb, route))
356            line = lines.line_of(match.start())
357            routes.append(
358                Symbol(
359                    name=f"{verb} {route}",
360                    qualname=f"{match.group('verb')}({route})",
361                    kind=SymbolKind.HTTP_ROUTE,
362                    path=path,
363                    line_start=line,
364                    line_end=line,
365                    signature=match.group(0).strip() + literal.group(0),
366                    annotations=(),
TypeScriptLangAdapter.importsdef imports(self, path: str, source: str) -> tuple[str, ...]
Ver prueba
src/docu/adapters/langs/typescript.py#L407-L408
407    def imports(self, path: str, source: str) -> tuple[str, ...]:
408        return tuple(match.group("module") for match in _IMPORT_RE.finditer(source))
TypeScriptLangAdapter.callsdef calls(self, path: str, source: str) -> tuple[tuple[str, str], ...]
Ver prueba
src/docu/adapters/langs/typescript.py#L410-L423
410    def calls(self, path: str, source: str) -> tuple[tuple[str, str], ...]:
411        """Aristas entre funciones o metodos declarados en el mismo archivo."""
412        symbols = self.symbols(path, source)
413        declared = {symbol.name for symbol in symbols if symbol.kind in (SymbolKind.METHOD, SymbolKind.FUNCTION)}
414        edges: list[tuple[str, str]] = []
415        for symbol in symbols:
416            for child in symbol.children:
417                body = source.splitlines()[child.line_start - 1 : child.line_end]
418                for line in body:
419                    for name in re.findall(r"[A-Za-z_$][\w$]*\s*\(", line):
420                        callee = name.rstrip("(").strip()
421                        if callee in declared and callee != child.name:
422                            edges.append((child.name, callee))
423        return tuple(dict.fromkeys(edges))
_annotation_blockdef _annotation_block(source: str, start: int, end: int) -> tuple[str, int]
Ver prueba
src/docu/adapters/langs/typescript.py#L429-L435
429def _annotation_block(source: str, start: int, end: int) -> tuple[str, int]:
430    """Decoradores entre dos posiciones y offset del primero."""
431    segment = source[start:end]
432    position = segment.find("@")
433    if position < 0:
434        return "", end
435    return segment[position:], start + position
_decorators_indef _decorators_in(text: str) -> tuple[str, ...]
Ver prueba
src/docu/adapters/langs/typescript.py#L438-L441
438def _decorators_in(text: str) -> tuple[str, ...]:
439    """Expresiones de decorador completas, con sus argumentos y sin saltos de linea."""
440    found = [" ".join(match.group(0).split()) for match in _DECORATOR_RE.finditer(text)]
441    return tuple(dict.fromkeys(found))
_class_routedef _class_route(decorators: tuple[str, ...]) -> str | None
Ver prueba
src/docu/adapters/langs/typescript.py#L444-L449
444def _class_route(decorators: tuple[str, ...]) -> str | None:
445    for decorator in decorators:
446        if decorator.lstrip("@").startswith("Controller"):
447            found = _STRING_RE.search(decorator)
448            return found.group(1) if found else ""
449    return None
_route_pathdef _route_path(text: str, annotation: str) -> str
Ver prueba
src/docu/adapters/langs/typescript.py#L452-L459
452def _route_path(text: str, annotation: str) -> str:
453    name = annotation.lstrip("@").split("(")[0]
454    pattern = re.compile(r"@" + re.escape(name) + r"\s*\(([^()]*)\)")
455    match = pattern.search(text)
456    if not match:
457        return "/"
458    literal = _STRING_RE.search(match.group(1))
459    return literal.group(1) if literal else "/"
_joindef _join(base: str | None, route: str) -> str
Ver prueba
src/docu/adapters/langs/typescript.py#L462-L470
462def _join(base: str | None, route: str) -> str:
463    """Une base y ruta y normaliza a una ruta HTTP con barra inicial."""
464    if route in ("", "/"):
465        combined = base or "/"
466    elif not base:
467        combined = route
468    else:
469        combined = base.rstrip("/") + "/" + route.lstrip("/")
470    return "/" + combined.lstrip("/")
_object_ofdef _object_of(value: bytes) -> bytes
Ver prueba
src/docu/adapters/sources/pdf.py#L47-L50
47def _object_of(value: bytes) -> bytes:
48    """Cuerpo del objeto si `value` es una referencia `N G R`; si no, el valor tal cual."""
49    match = REF_RE.fullmatch(value.strip())
50    return b"" if match is None else match.group(0)
_font_mapdef _font_map(objects: dict[int, bytes]) -> dict[str, tuple[dict[int, str], bool]]
Ver prueba
src/docu/adapters/sources/pdf.py#L53-L81
53def _font_map(objects: dict[int, bytes]) -> dict[str, tuple[dict[int, str], bool]]:
54    """Mapa `/F1 → (cmap, dos_bytes)` a partir de los recursos de cada página.
55
56    Es lo que separa «extraer texto» de «extraer basura»: un PDF real usa **una fuente subset por
57    rol** (cuerpo, negrita, símbolos), cada una con su propio `ToUnicode`. Aplicar un único mapa
58    global produce texto cifrado que parece texto.
59    """
60    fonts: dict[str, tuple[dict[int, str], bool]] = {}
61    for body in objects.values():
62        if PAGE_RE.search(body) is None and b"/Font" not in body:
63            continue
64        for resource in FONT_RESOURCES_RE.finditer(body):
65            block = resource.group(1)
66            if block.startswith(b"<<") is False:
67                referenced = objects.get(int(REF_RE.search(block).group(1)), b"") if REF_RE.search(block) else b""
68                block = referenced
69            for name, number in FONT_ENTRY_RE.findall(block):
70                font_body = objects.get(int(number), b"")
71                cmap: dict[int, str] = {}
72                to_unicode = re.search(rb"/ToUnicode\s+(\d+)\s+\d+\s+R", font_body)
73                if to_unicode:
74                    stream = _stream_of(objects.get(int(to_unicode.group(1)), b""))
75                    if stream:
76                        cmap = _parse_cmap(stream)
77                two_byte = bool(TYPE0_RE.search(font_body))
78                key = name.decode("latin-1")
79                if cmap or key not in fonts:
80                    fonts[key] = (cmap, two_byte)
81    return fonts
_decode_withdef _decode_with(raw: bytes, cmap: dict[int, str] | None, two_byte: bool) -> str
Ver prueba
src/docu/adapters/sources/pdf.py#L84-L94
84def _decode_with(raw: bytes, cmap: dict[int, str] | None, two_byte: bool) -> str:
85    if not cmap:
86        return raw.decode("latin-1", "replace")
87    if two_byte:
88        text = "".join(
89            cmap.get((raw[index] << 8) | raw[index + 1], "")
90            for index in range(0, len(raw) - 1, 2)
91        )
92        if text:
93            return text
94    return "".join(cmap.get(byte, chr(byte)) for byte in raw)
_looks_like_garbagedef _looks_like_garbage(text: str) -> bool
Ver prueba
src/docu/adapters/sources/pdf.py#L97-L115
97def _looks_like_garbage(text: str) -> bool:
98    """Detecta texto que el extractor produjo pero que no es legible.
99
100    Un PDF con fuentes subset mal mapeadas devuelve algo así como `P r e M H J e B D p e K`. Se
101    prefiere marcar la extracción como dudosa antes que citar basura: el documento generado sería
102    peor que no tenerlo.
103    """
104    compact = "".join(text.split())
105    if len(compact) < 40:
106        return False
107    letters = sum(1 for char in compact if char.isalpha())
108    spaces = text.count(" ")
109    single_char_tokens = sum(1 for token in text.split() if len(token) == 1)
110    tokens = max(1, len(text.split()))
111    if letters / len(compact) < 0.55:
112        return True
113    if single_char_tokens / tokens > 0.55:
114        return True
115    return bool(spaces and len(compact) / spaces < 2.0)
PdfText.usabledef usable(self) -> bool
Ver prueba
src/docu/adapters/sources/pdf.py#L133-L137
Anotaciones: @property
133    def usable(self) -> bool:
134        """¿Hay texto suficiente para citar algo, o es un PDF escaneado?"""
135        if self.total_pages <= 0:
136            return False
137        return self.chars >= MIN_CHARS_PER_PAGE * self.total_pages
PdfText.statusdef status(self) -> str
Ver prueba
src/docu/adapters/sources/pdf.py#L140-L145
Anotaciones: @property
140    def status(self) -> str:
141        if self.usable:
142            return "texto extraído"
143        if self.total_pages and self.chars:
144            return "texto insuficiente (posible PDF escaneado o con codificación no soportada)"
145        return "sin texto extraíble (PDF escaneado, cifrado o corrupto)"
is_pdfdef is_pdf(path: str, data: bytes | None=...) -> bool
Ver prueba
src/docu/adapters/sources/pdf.py#L148-L151
148def is_pdf(path: str, data: bytes | None = None) -> bool:
149    if path.lower().endswith(".pdf"):
150        return True
151    return bool(data and data.startswith(b"%PDF"))
_decodedef _decode(stream: bytes) -> bytes
Ver prueba
src/docu/adapters/sources/pdf.py#L157-L164
157def _decode(stream: bytes) -> bytes:
158    """Descomprime un stream si está en FlateDecode; si no, lo devuelve tal cual."""
159    for wbits in (zlib.MAX_WBITS, -zlib.MAX_WBITS, zlib.MAX_WBITS | 32):
160        try:
161            return zlib.decompress(stream, wbits)
162        except zlib.error:
163            continue
164    return stream
_objectsdef _objects(data: bytes) -> dict[int, bytes]
Ver prueba
src/docu/adapters/sources/pdf.py#L167-L172
167def _objects(data: bytes) -> dict[int, bytes]:
168    """Objetos del documento, indexados por número."""
169    found: dict[int, bytes] = {}
170    for match in OBJECT_RE.finditer(data):
171        found[int(match.group(1))] = match.group(3)
172    return found
_stream_ofdef _stream_of(body: bytes) -> bytes | None
Ver prueba
src/docu/adapters/sources/pdf.py#L175-L179
175def _stream_of(body: bytes) -> bytes | None:
176    match = STREAM_RE.search(body)
177    if match is None:
178        return None
179    return _decode(match.group(1))
_parse_cmapdef _parse_cmap(text: bytes) -> dict[int, str]
Ver prueba
src/docu/adapters/sources/pdf.py#L185-L204
185def _parse_cmap(text: bytes) -> dict[int, str]:
186    """`ToUnicode` CMap: códigos de byte → carácter, para fuentes con codificación propia."""
187    mapping: dict[int, str] = {}
188    for block in BFCHAR_RE.finditer(text):
189        for source, target in HEXPAIR_RE.findall(block.group(1)):
190            try:
191                mapping[int(source, 16)] = bytes.fromhex(target.decode()).decode("utf-16-be", "ignore")
192            except (ValueError, UnicodeDecodeError):
193                continue
194    for block in BFRANGE_RE.finditer(text):
195        for low, high, target in HEXRANGE_RE.findall(block.group(1)):
196            try:
197                start, end = int(low, 16), int(high, 16)
198                base = bytes.fromhex(target.decode()).decode("utf-16-be", "ignore")
199            except (ValueError, UnicodeDecodeError):
200                continue
201            for offset, code in enumerate(range(start, min(end, start + 255) + 1)):
202                if base:
203                    mapping[code] = chr(ord(base[0]) + offset) if len(base) == 1 else base
204    return mapping
_cmap_fordef _cmap_for(objects: dict[int, bytes]) -> dict[int, str]
Ver prueba
src/docu/adapters/sources/pdf.py#L207-L230
207def _cmap_for(objects: dict[int, bytes]) -> dict[int, str]:
208    """CMap `ToUnicode`: por referencia explícita o, si el PDF no la declara bien, por contenido.
209
210    Muchos generadores escriben el CMap sin que el diccionario de fuente lo referencie de forma
211    estándar; buscar el bloque `beginbfchar` es más tolerante sin inventar nada: se sigue leyendo el
212    mapa que el propio documento trae.
213    """
214    for body in objects.values():
215        if b"/ToUnicode" not in body:
216            continue
217        stream = _stream_of(body)
218        if stream is None:
219            continue
220        mapping = _parse_cmap(stream)
221        if mapping:
222            return mapping
223    for body in objects.values():
224        stream = _stream_of(body)
225        if stream is None or (b"beginbfchar" not in stream and b"beginbfrange" not in stream):
226            continue
227        mapping = _parse_cmap(stream)
228        if mapping:
229            return mapping
230    return {}
_decode_bytesdef _decode_bytes(raw: bytes, cmap: dict[int, str]) -> str
Ver prueba
src/docu/adapters/sources/pdf.py#L236-L246
236def _decode_bytes(raw: bytes, cmap: dict[int, str]) -> str:
237    if cmap:
238        if len(cmap) and max(cmap) > 255:
239            text = "".join(
240                cmap.get((raw[index] << 8) | raw[index + 1], "")
241                for index in range(0, len(raw) - 1, 2)
242            )
243            if text:
244                return text
245        return "".join(cmap.get(byte, chr(byte)) for byte in raw)
246    return raw.decode("latin-1", "replace")
_literaldef _literal(data: bytes, index: int) -> tuple[bytes, int]
Ver prueba
src/docu/adapters/sources/pdf.py#L249-L284
249def _literal(data: bytes, index: int) -> tuple[bytes, int]:
250    """Cadena literal `( … )` con escapes, incluidas las anidadas."""
251    depth = 1
252    out = bytearray()
253    index += 1
254    while index < len(data) and depth:
255        char = data[index]
256        if char == 0x5C:  # barra invertida
257            index += 1
258            if index >= len(data):
259                break
260            escape = data[index]
261            mapping = {0x6E: 10, 0x72: 13, 0x74: 9, 0x62: 8, 0x66: 12}
262            if escape in mapping:
263                out.append(mapping[escape])
264            elif 0x30 <= escape <= 0x37:
265                digits = bytes([escape])
266                while index + 1 < len(data) and 0x30 <= data[index + 1] <= 0x37 and len(digits) < 3:
267                    index += 1
268                    digits += bytes([data[index]])
269                out.append(int(digits, 8) & 0xFF)
270            elif escape in (0x0A, 0x0D):
271                pass  # continuación de línea: no aporta
272            else:
273                out.append(escape)
274        elif char == 0x28:
275            depth += 1
276            out.append(char)
277        elif char == 0x29:
278            depth -= 1
279            if depth:
280                out.append(char)
281        else:
282            out.append(char)
283        index += 1
284    return bytes(out), index
_hexstringdef _hexstring(data: bytes, index: int) -> tuple[bytes, int]
Ver prueba
src/docu/adapters/sources/pdf.py#L287-L297
287def _hexstring(data: bytes, index: int) -> tuple[bytes, int]:
288    end = data.find(b">", index)
289    if end == -1:
290        return b"", len(data)
291    digits = re.sub(rb"[^0-9A-Fa-f]", b"", data[index + 1 : end])
292    if len(digits) % 2:
293        digits += b"0"
294    try:
295        return bytes.fromhex(digits.decode()), end + 1
296    except ValueError:
297        return b"", end + 1
_content_textdef _content_text(data: bytes, cmap: dict[int, str], fonts: dict[str, tuple[dict[int, str], bool]] | None=...) -> str
Ver prueba
src/docu/adapters/sources/pdf.py#L300-L448
300def _content_text(
301    data: bytes,
302    cmap: dict[int, str],
303    fonts: dict[str, tuple[dict[int, str], bool]] | None = None,
304) -> str:
305    """Texto de un content stream: `Tj`, `TJ`, `'` y `"`, con saltos por `Td`/`TD`/`T*`/`Tm`.
306
307    El mapa de decodificación se elige por fuente (`Tf`): cada subset trae el suyo.
308    """
309    fonts = fonts or {}
310    active_cmap, active_two_byte = cmap, False
311    pieces: list[str] = []
312    pending: bytes | None = None
313    numbers: list[float] = []
314    last_y: float | None = None
315    index = 0
316    size = len(data)
317
318    def flush(separator: str = "") -> None:
319        nonlocal pending
320        if pending is None:
321            return
322        pieces.append(_decode_with(pending, active_cmap, active_two_byte))
323        pieces.append(separator)
324        pending = None
325
326    while index < size:
327        if data[index] == 0x2F:  # `/Nombre 12 Tf`
328            font_match = re.match(rb"/([A-Za-z0-9_.+-]+)\s+[\d.]+\s+Tf", data[index:])
329            if font_match:
330                name = font_match.group(1).decode("latin-1")
331                if name in fonts:
332                    active_cmap, active_two_byte = fonts[name]
333                index += font_match.end()
334                numbers.clear()
335                continue
336            index += 1
337            continue
338        char = data[index]
339        if char == 0x28:  # (
_page_streamsdef _page_streams(objects: dict[int, bytes]) -> list[bytes]
Ver prueba
src/docu/adapters/sources/pdf.py#L454-L471
454def _page_streams(objects: dict[int, bytes]) -> list[bytes]:
455    """Streams de cada página, en el orden del documento."""
456    streams: list[bytes] = []
457    for number in sorted(objects):
458        body = objects[number]
459        if not PAGE_RE.search(body):
460            continue
461        contents = CONTENTS_RE.search(body)
462        if contents is None:
463            streams.append(b"")
464            continue
465        page_data = bytearray()
466        for ref in REF_RE.findall(contents.group(1)):
467            stream = _stream_of(objects.get(int(ref), b""))
468            if stream:
469                page_data.extend(stream + b"\n")
470        streams.append(bytes(page_data))
471    return streams
extractdef extract(data: bytes) -> PdfText
Ver prueba
src/docu/adapters/sources/pdf.py#L474-L513
474def extract(data: bytes) -> PdfText:
475    """Texto por página, con método usado y avisos. Nunca lanza por contenido inválido."""
476    warnings: list[str] = []
477    if not data.startswith(b"%PDF"):
478        return PdfText(warnings=("el archivo no empieza con %PDF",))
479    if b"/Encrypt" in data:
480        return PdfText(warnings=("PDF cifrado: no se descifra",))
481
482    objects = _objects(data)
483    streams = _page_streams(objects)
484    cmap = _cmap_for(objects)
485    fonts = _font_map(objects)
486    method = "sin comprimir"
487    if b"/FlateDecode" in data:
488        method = "FlateDecode"
489
490    if not streams:
491        # Sin objetos de página: se intenta con todos los streams (PDFs minimalistas de prueba).
492        streams = [stream for stream in (_stream_of(body) for body in objects.values()) if stream]
493        if streams:
494            warnings.append("sin objetos de página: se extrajo de todos los streams")
495        method = f"{method} (sin estructura de páginas)"
496
497    pages: list[PdfPage] = []
498    for index, stream in enumerate(streams, start=1):
499        text = _content_text(stream, cmap, fonts)
500        pages.append(PdfPage(index, text))
501    chars = sum(len(page.text) for page in pages)
502    if cmap:
503        method = f"{method} + ToUnicode"
504    if not chars:
505        warnings.append("no se extrajo texto: PDF escaneado o con codificación no soportada")
506
507    return PdfText(
508        pages=tuple(pages),
509        total_pages=len(pages),
510        chars=chars,
511        method=method,
512        warnings=tuple(warnings),
513    )
pages_textdef pages_text(result: PdfText) -> str
Ver prueba
src/docu/adapters/sources/pdf.py#L516-L521
516def pages_text(result: PdfText) -> str:
517    """Texto plano con separadores de página, listo para escribir un sidecar."""
518    blocks: Iterable[str] = (
519        f"--- página {page.number} ---\n{page.text}" for page in result.pages if page.text
520    )
521    return "\n\n".join(blocks)
Snapshot.linesdef lines(self) -> int
Ver prueba
src/docu/adapters/sources/web.py#L51-L52
Anotaciones: @property
51    def lines(self) -> int:
52        return len(self.text.splitlines())
Snapshot.usabledef usable(self) -> bool
Ver prueba
src/docu/adapters/sources/web.py#L55-L56
Anotaciones: @property
55    def usable(self) -> bool:
56        return len(self.text.strip()) >= MIN_TEXT_CHARS
Snapshot.slugdef slug(self) -> str
Ver prueba
src/docu/adapters/sources/web.py#L59-L62
Anotaciones: @property
59    def slug(self) -> str:
60        parsed = urlparse(self.url)
61        base = re.sub(r"[^a-z0-9]+", "-", (parsed.netloc + parsed.path).lower()).strip("-")
62        return (base or "pagina")[:80]
_TextExtractor.__init__def __init__(self) -> None
Ver prueba
src/docu/adapters/sources/web.py#L68-L71
68    def __init__(self) -> None:
69        super().__init__(convert_charrefs=True)
70        self._parts: list[str] = []
71        self._skip_depth = 0
_TextExtractor.handle_starttagdef handle_starttag(self, tag: str, attrs) -> None
Ver prueba
src/docu/adapters/sources/web.py#L73-L78
73    def handle_starttag(self, tag: str, attrs) -> None:
74        if tag in SKIP_TAGS:
75            self._skip_depth += 1
76            return
77        if tag in BLOCK_TAGS:
78            self._parts.append("\n")
_TextExtractor.handle_endtagdef handle_endtag(self, tag: str) -> None
Ver prueba
src/docu/adapters/sources/web.py#L80-L85
80    def handle_endtag(self, tag: str) -> None:
81        if tag in SKIP_TAGS and self._skip_depth:
82            self._skip_depth -= 1
83            return
84        if tag in BLOCK_TAGS:
85            self._parts.append("\n")
_TextExtractor.handle_datadef handle_data(self, data: str) -> None
Ver prueba
src/docu/adapters/sources/web.py#L87-L90
87    def handle_data(self, data: str) -> None:
88        if self._skip_depth:
89            return
90        self._parts.append(data)
_TextExtractor.textdef text(self) -> str
Ver prueba
src/docu/adapters/sources/web.py#L92-L101
92    def text(self) -> str:
93        raw = "".join(self._parts)
94        lines = [" ".join(line.split()) for line in raw.splitlines()]
95        compact = [line for line in lines if line]
96        deduped: list[str] = []
97        for line in compact:
98            if deduped and deduped[-1] == line:
99                continue  # menús y cabeceras repetidas: ruido, no contenido
100            deduped.append(line)
101        return "\n".join(deduped)
html_to_textdef html_to_text(html: str) -> str
Ver prueba
src/docu/adapters/sources/web.py#L104-L108
104def html_to_text(html: str) -> str:
105    parser = _TextExtractor()
106    parser.feed(html)
107    parser.close()
108    return parser.text()
is_alloweddef is_allowed(url: str, allowlist: tuple[str, ...] | list[str]) -> bool
Ver prueba
src/docu/adapters/sources/web.py#L111-L125
111def is_allowed(url: str, allowlist: tuple[str, ...] | list[str]) -> bool:
112    """Sólo http/https y sólo dominios declarados: la lista blanca es del proyecto, no del agente."""
113    parsed = urlparse(url)
114    if parsed.scheme not in ("http", "https"):
115        return False
116    host = (parsed.hostname or "").lower()
117    if not host:
118        return False
119    for allowed in allowlist:
120        candidate = allowed.lower().strip()
121        if not candidate:
122            continue
123        if host == candidate or host.endswith("." + candidate):
124            return True
125    return False
fetchdef fetch(url: str, timeout: int=..., max_bytes: int=..., opener=..., attempts: int=...) -> tuple[str, int]
Ver prueba
src/docu/adapters/sources/web.py#L128-L165
128def fetch(
129    url: str,
130    timeout: int = TIMEOUT_SECONDS,
131    max_bytes: int = MAX_BYTES,
132    opener=None,
133    attempts: int = 2,
134) -> tuple[str, int]:
135    """Descarga el HTML. Devuelve (texto, código). `opener` permite inyectar uno en tests.
136
137    Un fallo de red transitorio (TLS, timeout) es habitual: se reintenta una vez antes de declarar
138    la fuente como no capturable.
139    """
140    open_url = opener or urllib.request.urlopen
141    last_error: Exception | None = None
142    for attempt in range(max(1, attempts)):
143        request = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
144        try:
145            with open_url(request, timeout=timeout) as response:
146                code = getattr(response, "status", 200)
147                payload = response.read(max_bytes + 1)
148            break
149        except (urllib.error.URLError, TimeoutError, OSError) as error:
150            last_error = error
151            if attempt + 1 >= attempts:
152                raise WebError(f"no se pudo descargar {url}: {error}") from error
153            time.sleep(1.0)
154    else:  # pragma: no cover - el bucle siempre rompe o lanza
155        raise WebError(f"no se pudo descargar {url}: {last_error}")
156    if len(payload) > max_bytes:
157        raise WebError(f"{url} supera el tope de {max_bytes} bytes")
158    charset = "utf-8"
159    match = re.search(rb"charset=[\"']?([\w-]+)", payload[:2048], re.IGNORECASE)
160    if match:
161        charset = match.group(1).decode("ascii", "ignore")
162    try:
163        return payload.decode(charset, "replace"), int(code)
164    except LookupError:
165        return payload.decode("utf-8", "replace"), int(code)
capturedef capture(url: str, allowlist: tuple[str, ...] | list[str], opener=...) -> Snapshot
Ver prueba
src/docu/adapters/sources/web.py#L168-L191
168def capture(url: str, allowlist: tuple[str, ...] | list[str], opener=None) -> Snapshot:
169    """Captura una URL y devuelve su snapshot validado."""
170    if not is_allowed(url, allowlist):
171        raise WebError(
172            f"{url} no está permitida: declara su dominio en el perfil "
173            "(`sources.web.allowlist`) antes de capturarla"
174        )
175    html, code = fetch(url, opener=opener)
176    text = html_to_text(html)
177    snapshot = Snapshot(
178        url=url,
179        text=text,
180        sha=__import__("hashlib").sha256(text.encode("utf-8")).hexdigest(),
181        captured_at=__import__("datetime").datetime.now(
182            __import__("datetime").timezone.utc
183        ).isoformat(timespec="seconds"),
184        status_code=code,
185    )
186    if not snapshot.usable:
187        raise WebError(
188            f"{url} no tiene texto útil ({len(text)} caracteres): ¿es una SPA con JavaScript o una "
189            "página de error? No se documenta una fuente vacía"
190        )
191    return snapshot
Check.passeddef passed(self) -> bool
Ver prueba
src/docu/audit/verify.py#L50-L51
Anotaciones: @property
50    def passed(self) -> bool:
51        return self.failed == 0
Check.scoredef score(self) -> float
Ver prueba
src/docu/audit/verify.py#L54-L57
Anotaciones: @property
54    def score(self) -> float:
55        if self.total == 0:
56            return 0.0 if self.failed else 100.0
57        return 100.0 * (self.total - self.failed) / self.total
Check.to_dictdef to_dict(self) -> dict[str, object]
Ver prueba
src/docu/audit/verify.py#L59-L68
59    def to_dict(self) -> dict[str, object]:
60        return {
61            "check": self.name,
62            "total": self.total,
63            "failed": self.failed,
64            "passed": self.passed,
65            "score": round(self.score, 2),
66            "note": self.note,
67            "details": list(self.details),
68        }
AuditReport.scoredef score(self) -> float
Ver prueba
src/docu/audit/verify.py#L80-L86
Anotaciones: @property
80    def score(self) -> float:
81        total = sum(WEIGHTS[name] for name in self.checks)
82        if not total:
83            return 0.0
84        return round(
85            sum(WEIGHTS[name] * check.score for name, check in self.checks.items()) / total, 2
86        )
AuditReport.passeddef passed(self) -> bool
Ver prueba
src/docu/audit/verify.py#L89-L90
Anotaciones: @property
89    def passed(self) -> bool:
90        return all(check.passed for check in self.checks.values())
AuditReport.to_dictdef to_dict(self) -> dict[str, object]
Ver prueba
src/docu/audit/verify.py#L92-L102
92    def to_dict(self) -> dict[str, object]:
93        return {
94            "schema_version": "1.0",
95            "project": self.project,
96            "score": self.score,
97            "passed": self.passed,
98            "weights": WEIGHTS,
99            "facts_total": self.facts_total,
100            "excluded": self.excluded,
101            "checks": {name: check.to_dict() for name, check in self.checks.items()},
102        }
AuditReport._reconciliationdef _reconciliation(self) -> str
Ver prueba
src/docu/audit/verify.py#L104-L115
104    def _reconciliation(self) -> str:
105        """Una sola cifra para el mismo universo: total, auditadas y excluidas con su motivo."""
106        audited = max((check.total for check in self.checks.values()), default=0)
107        if not self.facts_total:
108            return f"Afirmaciones auditadas: **{audited}**"
109        excluded = sum(self.excluded.values())
110        detail = " · ".join(f"{kind} {count}" for kind, count in sorted(self.excluded.items()))
111        suffix = f" ({detail})" if detail else ""
112        return (
113            f"Afirmaciones: **{self.facts_total}** · auditadas: **{audited}** · "
114            f"excluidas: **{excluded}**{suffix}"
115        )
AuditReport.to_markdowndef to_markdown(self) -> str
Ver prueba
src/docu/audit/verify.py#L117-L143
117    def to_markdown(self) -> str:
118        lines = [
119            f"# Auditoría de documentación · {self.project}",
120            "",
121            f"Nota: **{self.score:.2f}/100** · {'sin hallazgos' if self.passed else 'con hallazgos'}",
122            "",
123            self._reconciliation(),
124            "",
125            "| Comprobación | Peso | Resultado | Fallos | Detalle |",
126            "|---|---|---|---|---|",
127        ]
128        for name, check in self.checks.items():
129            mark = "✔" if check.passed else "✖"
130            lines.append(
131                f"| `{name}` | {WEIGHTS[name]} | {mark} {check.score:.0f}% | "
132                f"{check.failed}/{check.total} | {check.note} |"
133            )
134        lines += ["", "## Hallazgos", ""]
135        any_detail = False
136        for name, check in self.checks.items():
137            for detail in check.details:
138                any_detail = True
139                lines.append(f"- **{name}**: {detail}")
140        if not any_detail:
141            lines.append("_Ninguno._")
142        lines.append("")
143        return "\n".join(lines)
check_citationsdef check_citations(facts: Sequence[Fact], root: Path) -> Check
Ver prueba
src/docu/audit/verify.py#L149-L194
149def check_citations(facts: Sequence[Fact], root: Path) -> Check:
150    """Cada cita debe apuntar a un archivo existente, a un rango válido y contener su sujeto.
151
152    Es la comprobación que sostiene la promesa del producto: si una cita no se puede abrir y
153    confirmar, el documento no vale más que uno sin citas.
154    """
155    cache: dict[str, list[str] | None] = {}
156    failed = 0
157    details: list[str] = []
158    for fact in facts:
159        match = CITATION_RE.match(fact.citation)
160        if match is None:
161            failed += 1
162            details.append(f"{fact.subject}: cita sin formato `ruta#Lx-Ly` ({fact.citation!r})")
163            continue
164        path, start, end = match.group(1), int(match.group(2)), int(match.group(3))
165        if path not in cache:
166            target = root / path
167            cache[path] = (
168                target.read_text(encoding="utf-8", errors="replace").splitlines()
169                if target.exists()
170                else None
171            )
172        lines = cache[path]
173        if lines is None:
174            failed += 1
175            details.append(f"{fact.subject}: archivo inexistente {path}")
176            continue
177        if not lines and (start, end) == (1, 1):
178            # Archivo vacío (`__init__.py`): la afirmación es «este paquete existe» y la evidencia
179            # es la existencia del archivo. Citar L1-L1 es una convención explícita, no un error.
180            continue
181        if start < 1 or end > len(lines):
182            failed += 1
183            details.append(f"{fact.subject}: rango {start}-{end} fuera de {path} ({len(lines)} líneas)")
184            continue
185        span = _normalize_needle("\n".join(lines[start - 1 : end]))
186        supported = (
187            _prose_supported(fact, span)
188            if fact.kind in ("intent", "decision", "doc_section")
_probesdef _probes(fact: Fact) -> list[str]
Ver prueba
src/docu/audit/verify.py#L197-L217
197def _probes(fact: Fact) -> list[str]:
198    """Qué debe aparecer en el rango citado para considerar la afirmación sostenida."""
199    # Prosa y metadatos: el sujeto es una **etiqueta** (`README.md › Prerrequisitos`,
200    # `package.json (description)`), no un símbolo del código. La evidencia es el texto citado.
201    if fact.kind in ("intent", "decision", "doc_section"):
202        return [_normalize_needle(fact.detail[:80])] if fact.detail.strip() else []
203    if fact.kind in ("field", "sql_table", "http_route"):
204        return [fact.subject.rsplit(".", 1)[-1]]
205    subject = fact.subject
206    if fact.kind == "route":
207        verb, _, path = subject.partition(" ")
208        return [path] if verb == "ANY" else [verb, path]
209    if fact.kind in ("method", "type"):
210        return [subject.rsplit(".", 1)[-1]]
211    if fact.kind == "dependency":
212        return [subject.split(":")[-1]]
213    if fact.kind == "config_key":
214        return [subject.split(".")[-1]]
215    if fact.kind in ("package", "module", "parent", "plugin"):
216        return []  # la evidencia es el archivo declarante, ya verificado arriba
217    return [subject.rsplit(".", 1)[-1]]
_prose_supporteddef _prose_supported(fact: Fact, span: str) -> bool
Ver prueba
src/docu/audit/verify.py#L220-L234
220def _prose_supported(fact: Fact, span: str) -> bool:
221    """¿El rango citado sostiene la prosa citada?
222
223    El extractor de documentación une líneas (salta tablas y viñetas), así que el texto del hecho no
224    siempre es contiguo en el archivo. Se exige que **al menos el 70 % de sus palabras** aparezcan en
225    el rango: más honesto que fingir una comparación exacta que el propio extractor rompe.
226    """
227    # Se comparan **palabras**, no tokens con puntuación: la cita puede empezar con comillas o
228    # terminar con punto y la afirmación sigue sosteniéndose.
229    words = [word for word in re.findall(r"[a-z0-9_]+", _normalize_needle(fact.detail)) if len(word) > 3]
230    if not words:
231        return True
232    span_words = set(re.findall(r"[a-z0-9_]+", span))
233    hits = sum(1 for word in words if word in span_words)
234    return hits / len(words) >= 0.7
_normalize_needledef _normalize_needle(text: str) -> str
Ver prueba
src/docu/audit/verify.py#L237-L242
237def _normalize_needle(text: str) -> str:
238    """Normaliza el texto citado para compararlo: sin viñetas, sin énfasis y con un solo espacio."""
239    # Los guiones bajos NO se quitan: `pull_request` es un identificador, no énfasis.
240    cleaned = re.sub(r"[*`]", "", text)
241    cleaned = re.sub(r"^\s*[-*+]\s*", "", cleaned, flags=re.MULTILINE)
242    return re.sub(r"\s+", " ", cleaned).strip().lower()
check_duplicatesdef check_duplicates(facts: Sequence[Fact]) -> Check
Ver prueba
src/docu/audit/verify.py#L245-L260
245def check_duplicates(facts: Sequence[Fact]) -> Check:
246    """Una afirmación repetida **con la misma prueba** es ruido, no documentación.
247
248    El par (sujeto, cita) es la unidad: el mismo `uses` en dos pasos de un workflow YAML comparte
249    ruta aplanada pero vive en líneas distintas, así que no es duplicado.
250    """
251    seen: dict[tuple[str, str, str], int] = {}
252    for fact in facts:
253        key = (fact.kind, fact.subject, fact.citation)
254        seen[key] = seen.get(key, 0) + 1
255    repeated = {key: count for key, count in seen.items() if count > 1}
256    details = [
257        f"{kind} {subject!r} aparece {count} veces en {citation}"
258        for (kind, subject, citation), count in repeated.items()
259    ]
260    return Check("duplicates", len(facts), len(repeated), tuple(details[:20]), "afirmaciones repetidas")
_document_pathsdef _document_paths(text: str) -> set[str]
Ver prueba
src/docu/audit/verify.py#L263-L265
263def _document_paths(text: str) -> set[str]:
264    """Rutas HTTP documentadas en las tablas de un nivel."""
265    return {match.group(1) for match in PATH_CELL_RE.finditer(text)}
check_consistencydef check_consistency(docs: Mapping[str, str]) -> Check
Ver prueba
src/docu/audit/verify.py#L268-L284
268def check_consistency(docs: Mapping[str, str]) -> Check:
269    """El mismo hecho no puede diferir entre niveles: es el fallo que la guía llama deriva interna."""
270    if len(docs) < 2:
271        return Check("consistency", 0, 0, (), "un solo nivel generado: nada que contrastar")
272    paths = {level: _document_paths(text) for level, text in docs.items()}
273    reference_level = min(paths)
274    reference = paths[reference_level]
275    failed = 0
276    details: list[str] = []
277    for level, found in paths.items():
278        if level == reference_level:
279            continue
280        for missing in sorted(reference - found):
281            failed += 1
282            details.append(f"{missing} está en {reference_level} y no en {level}")
283    total = sum(len(value) for value in paths.values())
284    return Check("consistency", total, failed, tuple(details[:20]), "rutas coherentes entre niveles")
check_coveragedef check_coverage(facts: Sequence[Fact], root: Path) -> Check
Ver prueba
src/docu/audit/verify.py#L287-L297
287def check_coverage(facts: Sequence[Fact], root: Path) -> Check:
288    """Secciones aplicables que quedaron sin evidencia."""
289    applicable = applicability(facts, root)
290    required = [kind for kind, needed in applicable.items() if needed]
291    missing = [
292        kind
293        for kind in required
294        if not any(fact.kind in _evidence_kinds(kind) for fact in facts)
295    ]
296    details = [f"sección aplicable sin evidencia: {kind}" for kind in missing]
297    return Check("coverage", len(required), len(missing), tuple(details), "secciones aplicables")
_evidence_kindsdef _evidence_kinds(kind: str) -> tuple[str, ...]
Ver prueba
src/docu/audit/verify.py#L300-L303
300def _evidence_kinds(kind: str) -> tuple[str, ...]:
301    if kind == "module":
302        return ("module", "package")
303    return (kind,)
check_freshnessdef check_freshness(root: Path, levels: Sequence[str], manifest_path: Path | str | None=..., include: Sequence[str]=..., exclude: Sequence[str]=..., ttl_days: int=...) -> Check
Ver prueba
src/docu/audit/verify.py#L306-L336
306def check_freshness(
307    root: Path,
308    levels: Sequence[str],
309    manifest_path: Path | str | None = None,
310    include: Sequence[str] = (),
311    exclude: Sequence[str] = (),
312    ttl_days: int = 90,
313) -> Check:
314    """Estado del manifest: un documento desactualizado no es documentación, es historia.
315
316    El descubrimiento debe ser **el mismo** que usó la generación. Si no, los hashes no coinciden y
317    la auditoría inventa páginas obsoletas.
318    """
319    manifest, states, _hashes = inspect(
320        root,
321        levels=levels,
322        manifest_path=manifest_path,
323        include=include,
324        exclude=exclude,
325        ttl_days=ttl_days,
326    )
327    stale = [
328        f"{level}: {state.value}" for level, state in states.items() if state is not DocState.FRESH
329    ]
330    return Check(
331        "freshness",
332        len(states),
333        len(stale),
334        tuple(stale),
335        "sin manifest" if manifest is None else "estados del manifest",
336    )
auditdef audit(root: Path | str, docs_dir: Path | str | None=..., levels: Sequence[str]=..., profile_path: Path | str | None=..., include_tests: bool=..., facts: Sequence[Fact] | None=...) -> AuditReport
Ver prueba
src/docu/audit/verify.py#L342-L417
342def audit(
343    root: Path | str,
344    docs_dir: Path | str | None = None,
345    levels: Sequence[str] = ("l1", "l4"),
346    profile_path: Path | str | None = None,
347    include_tests: bool = False,
348    facts: Sequence[Fact] | None = None,
349) -> AuditReport:
350    """Ejecuta las cinco comprobaciones. Sin modelos, sin red, sin coste."""
351    root_path = Path(root).resolve()
352    profile = load(profile_path) if profile_path else (
353        load(find(root_path)) if find(root_path) else None
354    )
355    exclude = profile.effective_exclude if profile else ()
356    include = profile.include if profile else ()
357    # El universo auditable debe ser el **mismo** que el documentado: si el manual incluye
358    # intención, decisiones y secciones del repositorio, la auditoría tiene que verlas. Antes cada
359    # uno contaba su propio total (hallazgo F-26: 1306 en el documento contra 1236 en la auditoría).
360    if facts is None:
361        from docu.generate.docs_evidence import discover as discover_docs
362        from docu.generate.narrative import collect as collect_narrative
363        from docu.generate.pipeline import _discover, _read
364
365        code_facts, _sources = collect_facts(
366            root_path, include_tests=include_tests, include=include, exclude=exclude
367        )
368        counts: dict[str, int] = {}
369        for fact in code_facts:
370            counts[fact.kind] = counts.get(fact.kind, 0) + 1
371        narrative = collect_narrative(
372            root_path,
373            _discover(root_path, include_tests=include_tests, include=include, exclude=exclude),
374            counts,
375            root_path.name,
376            _read,
377        )
378        facts = [
379            *code_facts,
380            *narrative.facts,
381            *(section.to_fact() for section in discover_docs(root_path)),
Discrepancy.severitydef severity(self) -> str
Ver prueba
src/docu/conformance/drift.py#L46-L47
Anotaciones: @property
46    def severity(self) -> str:
47        return SEVERITY.get(self.kind, "warning")
Discrepancy.actiondef action(self) -> str
Ver prueba
src/docu/conformance/drift.py#L50-L51
Anotaciones: @property
50    def action(self) -> str:
51        return ACTION.get(self.kind, "revisar")
Discrepancy.to_dictdef to_dict(self) -> dict[str, object]
Ver prueba
src/docu/conformance/drift.py#L53-L62
53    def to_dict(self) -> dict[str, object]:
54        return {
55            "kind": self.kind,
56            "severity": self.severity,
57            "subject": self.subject,
58            "detail": self.detail,
59            "code_citation": self.code_citation,
60            "declaration_source": self.declaration_source,
61            "action": self.action,
62        }
DriftReport.errorsdef errors(self) -> list[Discrepancy]
Ver prueba
src/docu/conformance/drift.py#L73-L74
Anotaciones: @property
73    def errors(self) -> list[Discrepancy]:
74        return [item for item in self.discrepancies if item.severity == "error"]
DriftReport.warningsdef warnings(self) -> list[Discrepancy]
Ver prueba
src/docu/conformance/drift.py#L77-L78
Anotaciones: @property
77    def warnings(self) -> list[Discrepancy]:
78        return [item for item in self.discrepancies if item.severity != "error"]
DriftReport.is_cleandef is_clean(self) -> bool
Ver prueba
src/docu/conformance/drift.py#L81-L82
Anotaciones: @property
81    def is_clean(self) -> bool:
82        return not self.discrepancies
DriftReport.to_dictdef to_dict(self) -> dict[str, object]
Ver prueba
src/docu/conformance/drift.py#L84-L93
84    def to_dict(self) -> dict[str, object]:
85        return {
86            "schema_version": "1.0",
87            "sources": list(self.model.sources),
88            "routes_in_code": self.routes_in_code,
89            "components_in_code": self.components_in_code,
90            "errors": len(self.errors),
91            "warnings": len(self.warnings),
92            "discrepancies": [item.to_dict() for item in self.discrepancies],
93        }
DriftReport.to_markdowndef to_markdown(self) -> str
Ver prueba
src/docu/conformance/drift.py#L95-L112
95    def to_markdown(self) -> str:
96        lines = [
97            "# Deriva arquitectónica",
98            "",
99            (f"Modelo declarado: {', '.join(self.model.sources) or '—'} · "
100            f"rutas en código: {self.routes_in_code} · componentes en código: {self.components_in_code}"),
101            "",
102        ]
103        if self.is_clean:
104            lines.append("Sin discrepancias: el código implementa lo declarado.")
105            return "\n".join(lines) + "\n"
106        lines += ["| Tipo | Gravedad | Sujeto | Evidencia en código | Acción propuesta |", "|---|---|---|---|---|"]
107        for item in self.discrepancies:
108            lines.append(
109                f"| `{item.kind}` | {item.severity} | `{item.subject}` | "
110                f"{item.code_citation or '—'} | {item.action} |"
111            )
112        return "\n".join(lines) + "\n"
DriftReport.savedef save(self, path: Path | str) -> Path
Ver prueba
src/docu/conformance/drift.py#L114-L118
114    def save(self, path: Path | str) -> Path:
115        target = Path(path)
116        target.parent.mkdir(parents=True, exist_ok=True)
117        target.write_text(json.dumps(self.to_dict(), ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
118        return target
describe_codedef describe_code(root: Path | str, include_tests: bool=...) -> CodeFacts
Ver prueba
src/docu/conformance/drift.py#L140-L174
140def describe_code(root: Path | str, include_tests: bool = False) -> CodeFacts:
141    """Lo que el codigo dice de si mismo: rutas, componentes y dependencias.
142
143    Las dependencias se derivan de **imports** ademas de llamadas: un import es una relacion
144    estatica y verificable entre archivos, mientras que el grafo de llamadas se queda corto en
145    cuanto hay despacho dinamico. Ambas fuentes se unen, sin inventar aristas.
146    """
147    root_path = Path(root)
148    facts, _sources = collect_facts(root_path, include_tests=include_tests)
149    routes = tuple(
150        RouteFact(key=fact.subject, citation=fact.citation, handler=fact.detail)
151        for fact in facts
152        if fact.kind == "route"
153    )
154    components = {fact.subject: fact.citation for fact in facts if fact.kind == "type"}
155    owner_by_file = {
156        citation.split("#")[0]: name for name, citation in components.items() if "#" in citation
157    }
158
159    edges: list[tuple[str, str]] = []
160    for rel, path in _discover(root_path, include_tests=include_tests).items():
161        adapter = adapter_for(rel)
162        if adapter is None:
163            continue
164        source = _read(path)
165        for caller, callee in adapter.calls(rel, source):  # type: ignore[attr-defined]
166            edges.append((caller, callee))
167        owner = owner_by_file.get(rel)
168        if owner is None:
169            continue
170        for module in adapter.imports(rel, source):  # type: ignore[attr-defined]
171            candidate = re.split(r"[./]", module)[-1]
172            if candidate in components and candidate != owner:
173                edges.append((owner, candidate))
174    return CodeFacts(routes=routes, components=components, dependencies=tuple(dict.fromkeys(edges)))
_shortdef _short(name: str) -> str
Ver prueba
src/docu/conformance/drift.py#L180-L182
180def _short(name: str) -> str:
181    """Ultimo segmento de un nombre calificado (`A.B.c` → `c`)."""
182    return name.rsplit(".", 1)[-1]
_ownerdef _owner(qualname: str) -> str
Ver prueba
src/docu/conformance/drift.py#L185-L191
185def _owner(qualname: str) -> str:
186    """Componente propietario de un simbolo: el **primer** segmento (`A.B.c` → `A`).
187
188    Confundir esto con `_short` hacia que un metodo (`refreshtoken`) se tratara como componente
189    y que las rutas no se atribuyeran a su controlador.
190    """
191    return qualname.split(".", 1)[0]
comparedef compare(model: ArchitectureModel, code: CodeFacts) -> DriftReport
Ver prueba
src/docu/conformance/drift.py#L194-L268
194def compare(model: ArchitectureModel, code: CodeFacts) -> DriftReport:
195    """Diferencias en ambos sentidos: lo declarado que no existe y lo que existe sin declarar."""
196    report = DriftReport(model=model)
197    report.routes_in_code = len(code.routes)
198    report.components_in_code = len(code.components)
199
200    declared_routes = model.declared_routes
201    code_routes = {route.key: route for route in code.routes}
202    for key, route in code_routes.items():
203        if key not in declared_routes:
204            report.discrepancies.append(
205                Discrepancy(
206                    kind="undeclared_route",
207                    subject=key,
208                    detail="la ruta existe en el código y no está declarada",
209                    code_citation=route.citation,
210                    declaration_source=",".join(model.sources) or None,
211                )
212            )
213    for key in sorted(declared_routes - set(code_routes)):
214        report.discrepancies.append(
215            Discrepancy(
216                kind="missing_implementation",
217                subject=key,
218                detail="la ruta está declarada y no existe en el código",
219                declaration_source=",".join(model.sources) or None,
220            )
221        )
222
223    declared_components = model.component_names
224    for name in sorted(declared_components):
225        if name not in code.components:
226            report.discrepancies.append(
227                Discrepancy(
228                    kind="missing_component",
229                    subject=name,
230                    detail="componente declarado sin implementación detectable",
231                    declaration_source=",".join(model.sources) or None,
232                )
233            )
analyzedef analyze(root: Path | str, architecture: Path | str | None=..., include_tests: bool=...) -> DriftReport
Ver prueba
src/docu/conformance/drift.py#L271-L278
271def analyze(
272    root: Path | str,
273    architecture: Path | str | None = None,
274    include_tests: bool = False,
275) -> DriftReport:
276    model = load_architecture(Path(root), architecture)
277    code = describe_code(root, include_tests=include_tests)
278    return compare(model, code)
bootstrapdef bootstrap(root: Path | str, include_tests: bool=...) -> ArchitectureModel
Ver prueba
src/docu/conformance/drift.py#L281-L318
281def bootstrap(root: Path | str, include_tests: bool = False) -> ArchitectureModel:
282    """Genera el modelo inicial desde el codigo actual.
283
284    No es prescriptivo todavia: es una **foto** que convierte cualquier cambio futuro en deriva
285    visible. Revisar y corregir el archivo es el primer acto arquitectonico.
286    """
287    code = describe_code(root, include_tests=include_tests)
288    components: dict[str, DeclaredComponent] = {}
289
290    for name in sorted(code.components):
291        dependencies = sorted(
292            {
293                _owner(callee)
294                for caller, callee in code.dependencies
295                if _owner(caller) == name and _owner(callee) in code.components and _owner(callee) != name
296            }
297        )
298        components[name] = DeclaredComponent(
299            name=name,
300            kind="component",
301            depends_on=tuple(dependencies),
302        )
303
304    for route in code.routes:
305        _verb, _, path = route.key.partition(" ")
306        owner = _owner(route.handler) if route.handler else path
307        if owner not in components:
308            components[owner] = DeclaredComponent(name=owner, kind="endpoint")
309        component = components[owner]
310        components[owner] = DeclaredComponent(
311            name=component.name,
312            kind=component.kind,
313            provides=(*component.provides, Route(verb=_verb, path=path)),
314            depends_on=component.depends_on,
315            source=component.source,
316        )
317
318    return ArchitectureModel(components=tuple(components.values()), routes=())
Route.keydef key(self) -> str
Ver prueba
src/docu/conformance/model.py#L36-L37
Anotaciones: @property
36    def key(self) -> str:
37        return f"{self.verb.upper()} {self.path}"
Route.__str__def __str__(self) -> str
Ver prueba
src/docu/conformance/model.py#L39-L40
39    def __str__(self) -> str:
40        return self.key
ArchitectureModel.component_namesdef component_names(self) -> set[str]
Ver prueba
src/docu/conformance/model.py#L60-L61
Anotaciones: @property
60    def component_names(self) -> set[str]:
61        return {component.name for component in self.components}
ArchitectureModel.declared_routesdef declared_routes(self) -> set[str]
Ver prueba
src/docu/conformance/model.py#L64-L68
Anotaciones: @property
64    def declared_routes(self) -> set[str]:
65        returns = {route.key for route in self.routes}
66        for component in self.components:
67            returns.update(route.key for route in component.provides)
68        return returns
ArchitectureModel.declared_dependenciesdef declared_dependencies(self) -> set[tuple[str, str]]
Ver prueba
src/docu/conformance/model.py#L70-L75
70    def declared_dependencies(self) -> set[tuple[str, str]]:
71        return {
72            (component.name, dependency)
73            for component in self.components
74            for dependency in component.depends_on
75        }
ArchitectureModel.is_emptydef is_empty(self) -> bool
Ver prueba
src/docu/conformance/model.py#L78-L79
Anotaciones: @property
78    def is_empty(self) -> bool:
79        return not self.components and not self.routes
_read_documentdef _read_document(path: Path) -> Mapping[str, object] | None
Ver prueba
src/docu/conformance/model.py#L85-L97
85def _read_document(path: Path) -> Mapping[str, object] | None:
86    try:
87        text = path.read_text(encoding="utf-8")
88    except OSError:
89        return None
90    try:
91        if path.suffix == ".json":
92            payload = json.loads(text)
93        else:
94            payload = parse(text)
95    except (json.JSONDecodeError, YamlError):
96        return None
97    return payload if isinstance(payload, dict) else None
load_architecturedef load_architecture(root: Path, explicit: Path | str | None=...) -> ArchitectureModel
Ver prueba
src/docu/conformance/model.py#L100-L135
100def load_architecture(root: Path, explicit: Path | str | None = None) -> ArchitectureModel:
101    """Carga el modelo declarado. Devuelve un modelo vacio si no hay artefactos."""
102    root = Path(root)
103    sources: list[str] = []
104    components: list[DeclaredComponent] = []
105    routes: list[Route] = []
106
107    candidates = [Path(explicit)] if explicit else [root / name for name in ARCHITECTURE_CANDIDATES]
108    for candidate in candidates:
109        if not candidate.exists():
110            continue
111        document = _read_document(candidate)
112        if document is None:
113            continue
114        relative = candidate.relative_to(root).as_posix() if candidate.is_relative_to(root) else str(candidate)
115        sources.append(relative)
116        architecture = document.get("architecture")
117        block = architecture if isinstance(architecture, dict) else document
118        components.extend(_components_from(block, relative))
119
120    for name in OPENAPI_CANDIDATES:
121        candidate = root / name
122        if not candidate.exists():
123            continue
124        document = _read_document(candidate)
125        if document is None:
126            continue
127        relative = candidate.relative_to(root).as_posix()
128        sources.append(relative)
129        routes.extend(_routes_from_openapi(document))
130
131    return ArchitectureModel(
132        components=tuple(components),
133        routes=tuple(routes),
134        sources=tuple(dict.fromkeys(sources)),
135    )
_components_fromdef _components_from(block: Mapping[str, object], source: str) -> list[DeclaredComponent]
Ver prueba
src/docu/conformance/model.py#L138-L159
138def _components_from(block: Mapping[str, object], source: str) -> list[DeclaredComponent]:
139    raw = block.get("components")
140    if not isinstance(raw, list):
141        return []
142    components: list[DeclaredComponent] = []
143    for item in raw:
144        if not isinstance(item, dict):
145            continue
146        name = str(item.get("name") or "").strip()
147        if not name:
148            continue
149        provides = tuple(_route_from_text(str(entry)) for entry in _as_list(item.get("provides")))
150        components.append(
151            DeclaredComponent(
152                name=name,
153                kind=str(item.get("kind") or "component"),
154                provides=tuple(route for route in provides if route is not None),
155                depends_on=tuple(str(entry) for entry in _as_list(item.get("depends_on"))),
156                source=source,
157            )
158        )
159    return components
_routes_from_openapidef _routes_from_openapi(document: Mapping[str, object]) -> list[Route]
Ver prueba
src/docu/conformance/model.py#L162-L173
162def _routes_from_openapi(document: Mapping[str, object]) -> list[Route]:
163    paths = document.get("paths")
164    if not isinstance(paths, dict):
165        return []
166    routes: list[Route] = []
167    for path, operations in paths.items():
168        if not isinstance(operations, dict):
169            continue
170        for method in operations:
171            if str(method).lower() in HTTP_METHODS:
172                routes.append(Route(verb=str(method).upper(), path=str(path)))
173    return routes
_as_listdef _as_list(value: object) -> Iterable[object]
Ver prueba
src/docu/conformance/model.py#L176-L181
176def _as_list(value: object) -> Iterable[object]:
177    if value is None:
178        return ()
179    if isinstance(value, list):
180        return value
181    return (value,)
_route_from_textdef _route_from_text(text: str) -> Route | None
Ver prueba
src/docu/conformance/model.py#L184-L192
184def _route_from_text(text: str) -> Route | None:
185    """`"POST /api/x"` → `Route`. Ignora entradas que no son rutas."""
186    parts = text.strip().split(maxsplit=1)
187    if len(parts) != 2:
188        return None
189    verb, path = parts
190    if verb.upper() not in {method.upper() for method in HTTP_METHODS}:
191        return None
192    return Route(verb=verb.upper(), path=path)
to_yamldef to_yaml(model: ArchitectureModel, project: str) -> str
Ver prueba
src/docu/conformance/model.py#L195-L218
195def to_yaml(model: ArchitectureModel, project: str) -> str:
196    """Serializa el modelo en el formato prescriptivo que el propio agente sabe releer."""
197    lines = [
198        "# Modelo arquitectonico prescriptivo generado por docu.",
199        "# Editarlo es decidir: el agente compara este archivo con el codigo real y reporta deriva.",
200        "architecture:",
201        f"  project: {project}",
202        "  components:",
203    ]
204    for component in model.components:
205        lines.append(f"    - name: {component.name}")
206        lines.append(f"      kind: {component.kind}")
207        if component.provides:
208            provided = ", ".join(f'"{route.key}"' for route in component.provides)
209            lines.append(f"      provides: [{provided}]")
210        else:
211            lines.append("      provides: []")
212        if component.depends_on:
213            lines.append(f"      depends_on: [{', '.join(component.depends_on)}]")
214        else:
215            lines.append("      depends_on: []")
216    if not model.components:
217        lines.append("    []")
218    return "\n".join(lines) + "\n"
utcnowdef utcnow() -> datetime
Ver prueba
src/docu/core/contracts.py#L23-L25
23def utcnow() -> datetime:
24    """Reloj unico del sistema: siempre UTC con zona explicita."""
25    return datetime.now(UTC)
sha256_ofdef sha256_of(data: str | bytes) -> str
Ver prueba
src/docu/core/contracts.py#L28-L30
28def sha256_of(data: str | bytes) -> str:
29    payload = data.encode("utf-8") if isinstance(data, str) else data
30    return "sha256:" + hashlib.sha256(payload).hexdigest()
Artifact.__post_init__def __post_init__(self) -> None
Ver prueba
src/docu/core/contracts.py#L109-L115
109    def __post_init__(self) -> None:
110        if not self.artifact_id:
111            raise ValueError("artifact_id vacio")
112        if self.kind in (SourceKind.WEB, SourceKind.PDF) and not self.snapshot_path:
113            raise ValueError(
114                f"fuente volatil {self.uri!r} requiere snapshot_path: sin snapshot no es citable"
115            )
Symbol.is_containerdef is_container(self) -> bool
Ver prueba
src/docu/core/contracts.py#L134-L135
Anotaciones: @property
134    def is_container(self) -> bool:
135        return self.kind in (SymbolKind.CLASS, SymbolKind.INTERFACE, SymbolKind.ENUM, SymbolKind.MODULE)
Chunk.__post_init__def __post_init__(self) -> None
Ver prueba
src/docu/core/contracts.py#L165-L169
165    def __post_init__(self) -> None:
166        if not self.content_prefix:
167            raise ValueError("content_prefix vacio: rompe la trazabilidad contextual")
168        if self.line_start < 1 or self.line_end < self.line_start:
169            raise ValueError(f"rango de lineas invalido: {self.line_start}-{self.line_end}")
Chunk.citationdef citation(self) -> str
Ver prueba
src/docu/core/contracts.py#L172-L174
Anotaciones: @property
172    def citation(self) -> str:
173        """Referencia humana y estable para insertar en el documento."""
174        return f"{self.file_path}#L{self.line_start}-L{self.line_end}"
Chunk.to_recorddef to_record(self) -> dict[str, Any]
Ver prueba
src/docu/core/contracts.py#L176-L197
176    def to_record(self) -> dict[str, Any]:
177        """Forma plana para el vector store."""
178        return {
179            "chunk_id": self.chunk_id,
180            "artifact_id": self.artifact_id,
181            "source_type": self.source_type.value,
182            "file_path": self.file_path,
183            "lang": self.lang,
184            "enclosing_symbol": self.enclosing_symbol,
185            "symbol_kind": self.symbol_kind.value,
186            "line_start": self.line_start,
187            "line_end": self.line_end,
188            "repo": self.repo,
189            "commit": self.commit,
190            "dependencies": list(self.dependencies),
191            "content_hash": self.content_hash,
192            "embed_model": self.embed_model,
193            "chunker": self.chunker,
194            "ingested_at": self.ingested_at.isoformat(),
195            "citation": self.citation,
196            "schema_version": self.schema_version,
197        }
Claim.verifieddef verified(self) -> bool
Ver prueba
src/docu/core/contracts.py#L214-L215
Anotaciones: @property
214    def verified(self) -> bool:
215        return len(self.evidence) > 0
ContentNode.unsupporteddef unsupported(self) -> list[Claim]
Ver prueba
src/docu/core/contracts.py#L237-L238
Anotaciones: @property
237    def unsupported(self) -> list[Claim]:
238        return [c for c in self.claims if not c.verified]
ContentNode.is_publishabledef is_publishable(self) -> bool
Ver prueba
src/docu/core/contracts.py#L240-L241
240    def is_publishable(self) -> bool:
241        return not self.unsupported and self.state is DocState.FRESH
GateDecision.may_writedef may_write(self) -> bool
Ver prueba
src/docu/core/contracts.py#L269-L271
Anotaciones: @property
269    def may_write(self) -> bool:
270        """PROPOSE nunca escribe; REVIEW escribe en rama y abre PR; PUBLISH publica."""
271        return self.outcome is not GateOutcome.ABORT
GateDecision.describedef describe(self) -> str
Ver prueba
src/docu/core/contracts.py#L273-L275
273    def describe(self) -> str:
274        head = self.outcome.value.upper()
275        return f"{head}: " + "; ".join(self.reasons) if self.reasons else head
RunRecord.duration_sdef duration_s(self) -> float | None
Ver prueba
src/docu/core/contracts.py#L301-L304
Anotaciones: @property
301    def duration_s(self) -> float | None:
302        if self.finished_at is None:
303            return None
304        return (self.finished_at - self.started_at).total_seconds()
RunRecord.to_jsonldef to_jsonl(self) -> str
Ver prueba
src/docu/core/contracts.py#L306-L326
306    def to_jsonl(self) -> str:
307        payload = {
308            "run_id": self.run_id,
309            "project": self.project,
310            "commit": self.commit,
311            "mode": self.mode.value,
312            "started_at": self.started_at.isoformat(),
313            "finished_at": self.finished_at.isoformat() if self.finished_at else None,
314            "duration_s": self.duration_s,
315            "versions": self.versions,
316            "metrics": asdict(self.metrics) if self.metrics else None,
317            "gate": {"outcome": self.gate.outcome.value, "reasons": list(self.gate.reasons)}
318            if self.gate
319            else None,
320            "pages_written": self.pages_written,
321            "pages_skipped": self.pages_skipped,
322            "cost_usd": self.cost_usd,
323            "errors": self.errors,
324            "schema_version": self.schema_version,
325        }
326        return json.dumps(payload, ensure_ascii=False)
FreshnessRecord.is_expireddef is_expired(self, now: datetime | None=...) -> bool
Ver prueba
src/docu/core/contracts.py#L343-L345
343    def is_expired(self, now: datetime | None = None) -> bool:
344        moment = now or utcnow()
345        return moment - self.generated_at > timedelta(days=self.ttl_days)
Thresholds.as_mappingdef as_mapping(self) -> Mapping[str, float]
Ver prueba
src/docu/core/policy.py#L28-L34
28    def as_mapping(self) -> Mapping[str, float]:
29        return {
30            "accuracy": self.accuracy,
31            "completeness": self.completeness,
32            "attribution": self.attribution,
33            "conciseness": self.conciseness,
34        }
Budget.spenddef spend(self) -> None
Ver prueba
src/docu/core/policy.py#L50-L56
50    def spend(self, *, usd: float = 0.0, seconds: float = 0.0, pages: int = 0, calls: int = 0) -> None:
51        self.spent_usd += usd
52        self.elapsed_s += seconds
53        self.pages_written += pages
54        self.llm_calls += calls
55        if self.exceeded():
56            raise BudgetExhausted("; ".join(self.exceeded()))
Budget.exceededdef exceeded(self) -> list[str]
Ver prueba
src/docu/core/policy.py#L58-L68
58    def exceeded(self) -> list[str]:
59        problems: list[str] = []
60        if self.spent_usd > self.max_cost_usd:
61            problems.append(f"coste {self.spent_usd:.2f} > {self.max_cost_usd:.2f} USD")
62        if self.elapsed_s > self.max_seconds:
63            problems.append(f"tiempo {self.elapsed_s:.0f}s > {self.max_seconds:.0f}s")
64        if self.pages_written > self.max_pages:
65            problems.append(f"paginas {self.pages_written} > {self.max_pages}")
66        if self.llm_calls > self.max_llm_calls:
67            problems.append(f"llamadas {self.llm_calls} > {self.max_llm_calls}")
68        return problems
Budget.remaining_usddef remaining_usd(self) -> float
Ver prueba
src/docu/core/policy.py#L71-L72
Anotaciones: @property
71    def remaining_usd(self) -> float:
72        return max(0.0, self.max_cost_usd - self.spent_usd)
GatePolicy.evaluatedef evaluate(self, metrics: Metrics, mode: Mode) -> GateDecision
Ver prueba
src/docu/core/policy.py#L83-L104
83    def evaluate(self, metrics: Metrics, mode: Mode) -> GateDecision:
84        reasons: list[str] = []
85
86        # Puertas duras: cualquier violacion aborta la publicacion (no la corrida).
87        if self.require_zero_unsupported and metrics.unsupported_claims > 0:
88            reasons.append(f"{metrics.unsupported_claims} afirmaciones sin evidencia")
89        if self.require_fresh and metrics.freshness < 10.0:
90            reasons.append(f"frescura {metrics.freshness:.1f}/10")
91
92        # Puertas de umbral: por debajo se abre revision, no se publica.
93        for name, floor in self.thresholds.as_mapping().items():
94            value = getattr(metrics, name)
95            if value < floor:
96                reasons.append(f"{name} {value:.1f} < {floor:.1f}")
97
98        if mode is Mode.PROPOSE:
99            return GateDecision(GateOutcome.REVIEW, tuple(reasons) or ("modo propose: revisar diff",))
100        if reasons:
101            hard = self.require_zero_unsupported and metrics.unsupported_claims > 0
102            hard = hard or (self.require_fresh and metrics.freshness < 10.0)
103            return GateDecision(GateOutcome.ABORT if hard else GateOutcome.REVIEW, tuple(reasons))
104        return GateDecision(GateOutcome.PUBLISH, ())
SourceAdapter.discoverdef discover(self, root: str, include: Sequence[str], exclude: Sequence[str]) -> Iterable[Artifact]
Ver prueba
src/docu/core/ports.py#L24-L25
24    def discover(self, root: str, include: Sequence[str], exclude: Sequence[str]) -> Iterable[Artifact]:
25        ...
SourceAdapter.readdef read(self, artifact: Artifact) -> str | bytes
Ver prueba
src/docu/core/ports.py#L27-L28
27    def read(self, artifact: Artifact) -> str | bytes:
28        ...
LangAdapter.symbolsdef symbols(self, path: str, source: str) -> Sequence[Symbol]
Ver prueba
src/docu/core/ports.py#L41-L42
41    def symbols(self, path: str, source: str) -> Sequence[Symbol]:
42        ...
LangAdapter.importsdef imports(self, path: str, source: str) -> Sequence[str]
Ver prueba
src/docu/core/ports.py#L44-L45
44    def imports(self, path: str, source: str) -> Sequence[str]:
45        ...
LangAdapter.callsdef calls(self, path: str, source: str) -> Sequence[tuple[str, str]]
Ver prueba
src/docu/core/ports.py#L47-L52
47    def calls(self, path: str, source: str) -> Sequence[tuple[str, str]]:
48        """Aristas (llamador, llamado) solo cuando son **estaticamente verificables**.
49
50        El despacho dinamico no se inventa: se omite o se marca con confianza baja.
51        """
52        ...
Chunker.chunkdef chunk(self, artifact: Artifact, symbols: Sequence[Symbol], source: str) -> Sequence[Chunk]
Ver prueba
src/docu/core/ports.py#L61-L62
61    def chunk(self, artifact: Artifact, symbols: Sequence[Symbol], source: str) -> Sequence[Chunk]:
62        ...
Embedder.embeddef embed(self, texts: Sequence[str]) -> Sequence[Sequence[float]]
Ver prueba
src/docu/core/ports.py#L75-L76
75    def embed(self, texts: Sequence[str]) -> Sequence[Sequence[float]]:
76        ...
VectorStore.upsertdef upsert(self, namespace: str, chunks: Sequence[Chunk], vectors: Sequence[Sequence[float]]) -> int
Ver prueba
src/docu/core/ports.py#L85-L86
85    def upsert(self, namespace: str, chunks: Sequence[Chunk], vectors: Sequence[Sequence[float]]) -> int:
86        ...
VectorStore.querydef query(self, namespace: str, vector: Sequence[float], top_k: int, filters: Mapping[str, Any] | None=...) -> Sequence[tuple[Chunk, float]]
Ver prueba
src/docu/core/ports.py#L88-L91
88    def query(
89        self, namespace: str, vector: Sequence[float], top_k: int, filters: Mapping[str, Any] | None = None
90    ) -> Sequence[tuple[Chunk, float]]:
91        ...
VectorStore.delete_by_filterdef delete_by_filter(self, namespace: str, filters: Mapping[str, Any]) -> int
Ver prueba
src/docu/core/ports.py#L93-L94
93    def delete_by_filter(self, namespace: str, filters: Mapping[str, Any]) -> int:
94        ...
Reranker.rankdef rank(self, query: str, chunks: Sequence[Chunk], top_n: int) -> Sequence[tuple[Chunk, float]]
Ver prueba
src/docu/core/ports.py#L103-L104
103    def rank(self, query: str, chunks: Sequence[Chunk], top_n: int) -> Sequence[tuple[Chunk, float]]:
104        ...
RenderAdapter.renderdef render(self, node: ContentNode, context: Mapping[str, Any]) -> str
Ver prueba
src/docu/core/ports.py#L117-L118
117    def render(self, node: ContentNode, context: Mapping[str, Any]) -> str:
118        ...
Judge.scoredef score(self, document: str, evidence: Sequence[Chunk], rubric: Mapping[str, Any]) -> Metrics
Ver prueba
src/docu/core/ports.py#L128-L129
128    def score(self, document: str, evidence: Sequence[Chunk], rubric: Mapping[str, Any]) -> Metrics:
129        ...
Publisher.proposedef propose(self, path: str, content: str, message: str) -> str
Ver prueba
src/docu/core/ports.py#L138-L139
138    def propose(self, path: str, content: str, message: str) -> str:
139        ...
Publisher.applydef apply(self, proposal_id: str) -> str
Ver prueba
src/docu/core/ports.py#L141-L142
141    def apply(self, proposal_id: str) -> str:
142        ...
Publisher.revertdef revert(self, applied_id: str) -> None
Ver prueba
src/docu/core/ports.py#L144-L145
144    def revert(self, applied_id: str) -> None:
145        ...
Profile.existsdef exists(self) -> bool
Ver prueba
src/docu/core/profile.py#L73-L74
Anotaciones: @property
73    def exists(self) -> bool:
74        return self.path is not None and self.path.exists()
Profile.effective_excludedef effective_exclude(self) -> tuple[str, ...]
Ver prueba
src/docu/core/profile.py#L77-L83
Anotaciones: @property
77    def effective_exclude(self) -> tuple[str, ...]:
78        """Exclusiones aplicadas = las del archivo + los defaults de higiene.
79
80        Se calculan al usar el perfil, no al cargarlo: si se fusionaran en la carga, el archivo
81        dejaría de reflejar el comportamiento y la orden de cambio nunca podría proponer nada.
82        """
83        return tuple(dict.fromkeys((*self.exclude, *DEFAULT_EXCLUDE)))
Profile.to_dictdef to_dict(self) -> dict[str, object]
Ver prueba
src/docu/core/profile.py#L85-L107
85    def to_dict(self) -> dict[str, object]:
86        return {
87            "schema_version": "1.0",
88            "project": self.project,
89            "mode": self.mode.value,
90            "output": {"dir": self.output_dir, "levels": {level: level in self.levels for level in LEVELS}, "language": self.language},
91            "freshness": {"ttl_days": self.ttl_days},
92            "sources": {"git": {"include": list(self.include), "exclude": list(self.exclude)}},
93            "acceptance": {
94                "thresholds": {
95                    "accuracy": self.thresholds.accuracy,
96                    "completeness": self.thresholds.completeness,
97                    "attribution": self.thresholds.attribution,
98                    "conciseness": self.thresholds.conciseness,
99                }
100            },
101            "learn": {
102                "promotion_delta": self.promotion_delta,
103                "rollback_drop": self.rollback_drop,
104                "federate": self.federate,
105            },
106            "glossary": {phrase: list(terms) for phrase, terms in self.glossary.items()},
107        }
_mappingdef _mapping(value: object, name: str) -> Mapping[str, object]
Ver prueba
src/docu/core/profile.py#L113-L118
113def _mapping(value: object, name: str) -> Mapping[str, object]:
114    if value is None:
115        return {}
116    if not isinstance(value, dict):
117        raise ProfileError(f"'{name}' debe ser un mapa")
118    return value
_string_tupledef _string_tuple(value: object, name: str) -> tuple[str, ...]
Ver prueba
src/docu/core/profile.py#L121-L128
121def _string_tuple(value: object, name: str) -> tuple[str, ...]:
122    if value is None:
123        return ()
124    if isinstance(value, str):
125        return (value,)
126    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
127        raise ProfileError(f"'{name}' debe ser texto o lista de textos")
128    return tuple(value)
_levelsdef _levels(value: object) -> tuple[str, ...]
Ver prueba
src/docu/core/profile.py#L131-L139
131def _levels(value: object) -> tuple[str, ...]:
132    enabled = _mapping(value, "output.levels")
133    chosen = tuple(level for level in LEVELS if bool(enabled.get(level, level in ("l1", "l4"))))
134    unknown = tuple(level for level in chosen if level not in LEVELS)
135    if unknown:
136        raise ProfileError(f"niveles desconocidos: {', '.join(unknown)}")
137    if not chosen:
138        raise ProfileError("el perfil no habilita ningún nivel")
139    return chosen
_thresholdsdef _thresholds(value: object, defaults: Thresholds) -> Thresholds
Ver prueba
src/docu/core/profile.py#L142-L161
142def _thresholds(value: object, defaults: Thresholds) -> Thresholds:
143    acceptance = _mapping(value, "acceptance")
144    block = _mapping(acceptance.get("thresholds"), "acceptance.thresholds")
145
146    def number(key: str, fallback: float) -> float:
147        raw = block.get(key, fallback)
148        try:
149            parsed = float(raw)  # type: ignore[arg-type]
150        except (TypeError, ValueError):
151            raise ProfileError(f"umbral '{key}' debe ser numérico") from None
152        if not 0 < parsed <= 10:
153            raise ProfileError(f"umbral '{key}' fuera de rango (1..10): {parsed}")
154        return parsed
155
156    return Thresholds(
157        accuracy=number("accuracy", defaults.accuracy),
158        completeness=number("completeness", defaults.completeness),
159        attribution=number("attribution", defaults.attribution),
160        conciseness=number("conciseness", defaults.conciseness),
161    )
_glossarydef _glossary(value: object) -> dict[str, tuple[str, ...]]
Ver prueba
src/docu/core/profile.py#L164-L169
164def _glossary(value: object) -> dict[str, tuple[str, ...]]:
165    block = _mapping(value, "glossary")
166    glossary: dict[str, tuple[str, ...]] = {}
167    for phrase, terms in block.items():
168        glossary[str(phrase)] = _string_tuple(terms, f"glossary.{phrase}")
169    return glossary
from_dictdef from_dict(payload: Mapping[str, object]) -> Profile
Ver prueba
src/docu/core/profile.py#L172-L222
172def from_dict(payload: Mapping[str, object], *, path: Path | None = None, fallback_project: str = "proyecto") -> Profile:
173    """Construye el perfil efectivo, con defaults para lo ausente."""
174    output = _mapping(payload.get("output"), "output")
175    sources = _mapping(payload.get("sources"), "sources")
176    git = _mapping(sources.get("git"), "sources.git")
177    freshness = _mapping(payload.get("freshness"), "freshness")
178    learn = _mapping(payload.get("learn"), "learn")
179
180    mode_raw = str(payload.get("mode", "apply"))
181    try:
182        mode = Mode(mode_raw)
183    except ValueError:
184        raise ProfileError(f"modo desconocido: {mode_raw!r} (usa propose, apply o publish)") from None
185
186    raw_ttl = freshness.get("ttl_days")
187    if raw_ttl is None:
188        ttl = 90
189    else:
190        try:
191            ttl = int(raw_ttl)  # type: ignore[arg-type]
192        except (TypeError, ValueError):
193            raise ProfileError(f"freshness.ttl_days debe ser entero, no {raw_ttl!r}") from None
194        if ttl <= 0:
195            raise ProfileError("freshness.ttl_days debe ser positivo")
196
197    exclude = _string_tuple(git.get("exclude"), "sources.git.exclude")
198    web = _mapping(sources.get("web"), "sources.web")
199    web_urls = _string_tuple(web.get("urls"), "sources.web.urls")
200    for url in web_urls:
201        if not url.startswith(("http://", "https://")):
202            raise ProfileError(f"sources.web.urls: {url!r} no es una URL http/https")
203
204    return Profile(
205        project=str(payload.get("project") or fallback_project),
206        mode=mode,
207        levels=_levels(output.get("levels")),
208        output_dir=str(output.get("dir") or "docs/generated"),
209        language=str(output.get("language") or "es"),
210        ttl_days=ttl,
211        include=_string_tuple(git.get("include"), "sources.git.include"),
loaddef load(path: Path | str | None) -> Profile | None
Ver prueba
src/docu/core/profile.py#L225-L236
225def load(path: Path | str | None, *, fallback_project: str = "proyecto") -> Profile | None:
226    """Carga el perfil si existe. Devuelve `None` si no hay archivo (no es un error)."""
227    if path is None:
228        return None
229    target = Path(path)
230    if not target.exists():
231        return None
232    try:
233        payload = parse(target.read_text(encoding="utf-8"))
234    except YamlError as error:
235        raise ProfileError(f"perfil ilegible ({target}): {error}") from None
236    return from_dict(payload, path=target, fallback_project=fallback_project)
candidate_pathsdef candidate_paths(root: Path) -> tuple[Path, ...]
Ver prueba
src/docu/core/profile.py#L239-L240
239def candidate_paths(root: Path) -> tuple[Path, ...]:
240    return (root / "docu.profile.yaml", root / "docu.profile.yml", root / "docu.profile.json")
finddef find(root: Path) -> Path | None
Ver prueba
src/docu/core/profile.py#L243-L245
243def find(root: Path) -> Path | None:
244    """Primer perfil existente en la raíz, o `None`."""
245    return next((path for path in candidate_paths(root) if path.exists()), None)
to_yamldef to_yaml(profile: Profile) -> str
Ver prueba
src/docu/core/profile.py#L251-L314
251def to_yaml(profile: Profile) -> str:
252    """Serializa el perfil con comentarios: lo que se genera se entiende sin leer el código."""
253    lines = [
254        "# Perfil de aceptación de docu. Editarlo es decidir: la generación lo obedece.",
255        "# Generado por `docu init`; revisa exclusiones, niveles y umbrales antes de confiar en él.",
256        'schema_version: "1.0"',
257        "",
258        f"project: {profile.project}",
259        f"mode: {profile.mode.value}                 # propose | apply | publish",
260        "",
261        "sources:",
262        "  git:",
263        "    ref: HEAD",
264    ]
265    if profile.include:
266        lines.append("    include: [" + ", ".join(f'"{item}"' for item in profile.include) + "]")
267    else:
268        # Sin `include`, la ingesta cubre todo lo detectable. Escribir `["**/*"]` seria un
269        # patrón que no casa con los archivos de la raíz y perdería el propio perfil y el POM.
270        lines.append("    # include: []   # por defecto: todo lo detectable")
271    lines.append("    exclude:")
272    for pattern in profile.exclude:
273        lines.append(f'      - "{pattern}"')
274    lines.append("  pdf: []")
275    lines.append("  web:")
276    lines.append('    allowlist: ["docs.spring.io", "docs.python.org", "developer.mozilla.org"]')
277    lines.append("  contracts: []")
278    lines.append("")
279    lines.append("output:")
280    lines.append(f'  dir: {profile.output_dir}')
281    lines.append(f"  language: {profile.language}")
282    lines.append("  levels:")
283    for level in LEVELS:
284        marker = "true" if level in profile.levels else "false"
285        note = "" if level in SUPPORTED_LEVELS else "   # pendiente de implementación"
286        lines.append(f"    {level}: {marker}{note}")
287    lines.append("  notation:")
288    lines.append("    diagrams: mermaid")
289    lines.append("    architecture: c4")
290    lines.append("    api: openapi3.1")
Change.kinddef kind(self) -> str
Ver prueba
src/docu/core/profile.py#L328-L329
Anotaciones: @property
328    def kind(self) -> str:
329        return "aplicado" if self.applied else "conservado"
Change.describedef describe(self) -> str
Ver prueba
src/docu/core/profile.py#L331-L332
331    def describe(self) -> str:
332        return f"{self.field}: {self.before!r} → {self.after!r} ({self.reason})"
plan_changesdef plan_changes(existing: Profile | None, proposed: Profile) -> list[Change]
Ver prueba
src/docu/core/profile.py#L339-L392
339def plan_changes(existing: Profile | None, proposed: Profile) -> list[Change]:
340    """Orden de cambio: qué se actualizaría y qué se conserva, con su motivo.
341
342    Regla: la detección solo puede **añadir** estructura observable (niveles nuevos, exclusiones
343    nuevas, glosario si estaba vacío). Nunca redefine umbrales, modo, TTL ni vocabulario ya escrito.
344    """
345    if existing is None:
346        return [Change("perfil", None, proposed.project, "no existía perfil: se crea completo")]
347
348    changes: list[Change] = []
349
350    added_levels = tuple(level for level in proposed.levels if level not in existing.levels)
351    if added_levels:
352        merged = tuple(level for level in LEVELS if level in (*existing.levels, *added_levels))
353        reason = (
354            "se detectaron rutas HTTP: habilita la guía de uso"
355            if "l3" in added_levels
356            else "niveles nuevos detectados"
357        )
358        changes.append(Change("output.levels", existing.levels, merged, reason))
359
360    new_exclusions = tuple(item for item in DEFAULT_EXCLUDE if item not in existing.exclude)
361    if new_exclusions:
362        changes.append(
363            Change(
364                "sources.git.exclude",
365                len(existing.exclude),
366                len(existing.exclude) + len(new_exclusions),
367                f"{len(new_exclusions)} patrones de higiene nuevos",
368            )
369        )
370
371    if not existing.glossary and proposed.glossary:
372        changes.append(
373            Change("glossary", 0, len(proposed.glossary), "el framework detectado tiene glosario semilla")
374        )
375    elif existing.glossary and proposed.glossary and dict(existing.glossary) != dict(proposed.glossary):
376        changes.append(
377            Change("glossary", len(existing.glossary), len(existing.glossary), "se conserva el glosario humano", applied=False)
378        )
mergedef merge(existing: Profile, proposed: Profile) -> Profile
Ver prueba
src/docu/core/profile.py#L395-L404
395def merge(existing: Profile, proposed: Profile) -> Profile:
396    """Perfil resultante: aplica solo los cambios marcados y preserva lo humano."""
397    levels = tuple(level for level in LEVELS if level in (*existing.levels, *proposed.levels))
398    exclusions = tuple(dict.fromkeys((*existing.exclude, *DEFAULT_EXCLUDE)))
399    return replace(
400        existing,
401        levels=levels,
402        exclude=exclusions,
403        glossary=existing.glossary or proposed.glossary,
404    )
render_change_orderdef render_change_order(changes: Sequence[Change], project: str) -> str
Ver prueba
src/docu/core/profile.py#L407-L435
407def render_change_order(changes: Sequence[Change], project: str) -> str:
408    """Orden de cambio en Markdown: numerada, con motivo y con lo que se conserva."""
409    applied = [change for change in changes if change.applied]
410    kept = [change for change in changes if not change.applied]
411    lines = [
412        f"# Orden de cambio de `init` · {project}",
413        "",
414        "Reejecutar `docu init` no sobrescribe decisiones humanas: propone y espera aprobación.",
415        "",
416        "## Cambios propuestos",
417        "",
418    ]
419    if applied:
420        for index, change in enumerate(applied, start=1):
421            lines.append(f"{index}. **{change.field}**: {change.before!r} → {change.after!r} — {change.reason}")
422    else:
423        lines.append("_Ninguno: el perfil ya refleja lo detectado._")
424    lines += ["", "## Conservado por decisión humana", ""]
425    if kept:
426        for change in kept:
427            lines.append(f"- **{change.field}**: {change.before!r} — {change.reason}")
428    else:
429        lines.append("_Nada que conservar en esta corrida._")
430    lines += [
431        "",
432        "Para aplicarlo: `docu init --apply` (o `--force` para regenerar desde cero).",
433        "",
434    ]
435    return "\n".join(lines)
parsedef parse(text: str) -> dict[str, object]
Ver prueba
src/docu/core/yamlmini.py#L18-L28
18def parse(text: str) -> dict[str, object]:
19    """Devuelve un dict con el documento. Las claves de primer nivel son el contrato esperado."""
20    lines = _prepare(text)
21    if not lines:
22        return {}
23    value, index = _parse_block(lines, 0, lines[0][0])
24    if index != len(lines):
25        raise YamlError(f"contenido no consumido a partir de la linea {lines[index][2]}")
26    if not isinstance(value, dict):
27        raise YamlError("la raiz del documento debe ser un mapa")
28    return value
_preparedef _prepare(text: str) -> list[tuple[int, str, int]]
Ver prueba
src/docu/core/yamlmini.py#L34-L48
34def _prepare(text: str) -> list[tuple[int, str, int]]:
35    """(indentacion, contenido, numero de linea) ignorando vacias y comentarios."""
36    prepared: list[tuple[int, str, int]] = []
37    for number, raw in enumerate(text.splitlines(), start=1):
38        if not raw.strip() or raw.strip().startswith("#"):
39            continue
40        if raw.strip() in ("---", "..."):
41            continue
42        expanded = raw.replace("\t", "  ")
43        content = _strip_comment(expanded).rstrip()
44        if not content.strip():
45            continue
46        indent = len(content) - len(content.lstrip())
47        prepared.append((indent, content.strip(), number))
48    return prepared
_strip_commentdef _strip_comment(line: str) -> str
Ver prueba
src/docu/core/yamlmini.py#L51-L64
51def _strip_comment(line: str) -> str:
52    """Quita comentarios de fin de linea respetando comillas."""
53    quote: str | None = None
54    for index, char in enumerate(line):
55        if quote:
56            if char == quote:
57                quote = None
58            continue
59        if char in ("'", '"'):
60            quote = char
61            continue
62        if char == "#" and (index == 0 or line[index - 1].isspace()):
63            return line[:index]
64    return line
_parse_blockdef _parse_block(lines: list[tuple[int, str, int]], start: int, indent: int) -> tuple[object, int]
Ver prueba
src/docu/core/yamlmini.py#L70-L75
70def _parse_block(
71    lines: list[tuple[int, str, int]], start: int, indent: int
72) -> tuple[object, int]:
73    if lines[start][1].startswith("- "):
74        return _parse_sequence(lines, start, indent)
75    return _parse_mapping(lines, start, indent)
_parse_mappingdef _parse_mapping(lines: list[tuple[int, str, int]], start: int, indent: int) -> tuple[dict[str, object], int]
Ver prueba
src/docu/core/yamlmini.py#L78-L118
78def _parse_mapping(
79    lines: list[tuple[int, str, int]], start: int, indent: int
80) -> tuple[dict[str, object], int]:
81    result: dict[str, object] = {}
82    index = start
83    while index < len(lines):
84        line_indent, content, number = lines[index]
85        if line_indent < indent:
86            break
87        if line_indent > indent:
88            raise YamlError(f"indentacion inesperada en la linea {number}")
89        if content.startswith("- "):
90            break
91        key, sep, rest = _split_key(content, number)
92        if not sep:
93            raise YamlError(f"se esperaba 'clave: valor' en la linea {number}")
94        if rest[:1] in ("|", ">"):
95            # Escalar de bloque (`run: |`, `command: >`): las líneas siguientes, más indentadas,
96            # son el valor. Sin esto, un workflow real con `run: |` rompe toda la ingesta.
97            marker = rest[0]
98            index += 1
99            block: list[str] = []
100            while index < len(lines) and lines[index][0] > indent:
101                block.append(lines[index][1])
102                index += 1
103            result[key] = ("\n" if marker == "|" else " ").join(block).strip()
104            continue
105        if rest:
106            result[key] = _scalar(rest, number)
107            index += 1
108            continue
109        index += 1
110        if index < len(lines) and lines[index][0] > indent:
111            child, index = _parse_block(lines, index, lines[index][0])
112            result[key] = child
113        elif index < len(lines) and lines[index][0] == indent and lines[index][1].startswith("- "):
114            child, index = _parse_sequence(lines, index, indent)
115            result[key] = child
116        else:
117            result[key] = None
_parse_sequencedef _parse_sequence(lines: list[tuple[int, str, int]], start: int, indent: int) -> tuple[list[object], int]
Ver prueba
src/docu/core/yamlmini.py#L121-L146
121def _parse_sequence(
122    lines: list[tuple[int, str, int]], start: int, indent: int
123) -> tuple[list[object], int]:
124    items: list[object] = []
125    index = start
126    while index < len(lines):
127        line_indent, content, number = lines[index]
128        if line_indent < indent or not content.startswith("- "):
129            break
130        if line_indent > indent:
131            raise YamlError(f"indentacion inesperada en la linea {number}")
132        body = content[2:].strip()
133        index += 1
134        if not body:
135            if index < len(lines) and lines[index][0] > indent:
136                child, index = _parse_block(lines, index, lines[index][0])
137                items.append(child)
138            else:
139                items.append(None)
140            continue
141        if _is_inline_mapping(body, number):
142            mapping, index = _parse_inline_item(lines, index, indent, body, number)
143            items.append(mapping)
144            continue
145        items.append(_scalar(body, number))
146    return items, index
_parse_inline_itemdef _parse_inline_item(lines: list[tuple[int, str, int]], start: int, indent: int, first: str, number: int) -> tuple[dict[str, object], int]
Ver prueba
src/docu/core/yamlmini.py#L149-L193
149def _parse_inline_item(
150    lines: list[tuple[int, str, int]],
151    start: int,
152    indent: int,
153    first: str,
154    number: int,
155) -> tuple[dict[str, object], int]:
156    """`- name: X` seguido de claves alineadas con `name`."""
157    key, sep, rest = _split_key(first, number)
158    if not sep:
159        raise YamlError(f"elemento de secuencia invalido en la linea {number}")
160    item: dict[str, object] = {key: _scalar(rest, number) if rest else None}
161    index = start
162    while index < len(lines):
163        line_indent, content, child_number = lines[index]
164        if line_indent <= indent:
165            break
166        if content.startswith("- "):
167            break
168        child_key, child_sep, child_rest = _split_key(content, child_number)
169        if not child_sep:
170            raise YamlError(f"se esperaba 'clave: valor' en la linea {child_number}")
171        if child_rest[:1] in ("|", ">"):
172            marker = child_rest[0]
173            index += 1
174            block_lines: list[str] = []
175            while index < len(lines) and lines[index][0] > line_indent:
176                block_lines.append(lines[index][1])
177                index += 1
178            item[child_key] = ("\n" if marker == "|" else " ").join(block_lines).strip()
179            continue
180        if child_rest:
181            item[child_key] = _scalar(child_rest, child_number)
182            index += 1
183            continue
184        index += 1
185        if index < len(lines) and lines[index][0] > line_indent:
186            child, index = _parse_block(lines, index, lines[index][0])
187            item[child_key] = child
188        elif index < len(lines) and lines[index][0] == line_indent and lines[index][1].startswith("- "):
_is_inline_mappingdef _is_inline_mapping(body: str, number: int) -> bool
Ver prueba
src/docu/core/yamlmini.py#L199-L200
199def _is_inline_mapping(body: str, number: int) -> bool:
200    return bool(_split_key(body, number)[1])
_split_keydef _split_key(content: str, number: int) -> tuple[str, str, str]
Ver prueba
src/docu/core/yamlmini.py#L203-L215
203def _split_key(content: str, number: int) -> tuple[str, str, str]:
204    quote: str | None = None
205    for index, char in enumerate(content):
206        if quote:
207            if char == quote:
208                quote = None
209            continue
210        if char in ("'", '"'):
211            quote = char
212            continue
213        if char == ":" and (index + 1 == len(content) or content[index + 1].isspace()):
214            return content[:index].strip().strip("'\""), ":", content[index + 1 :].strip()
215    return content, "", ""
_scalardef _scalar(value: str, number: int) -> object
Ver prueba
src/docu/core/yamlmini.py#L218-L249
218def _scalar(value: str, number: int) -> object:
219    text = value.strip()
220    if not text:
221        return None
222    if text.startswith("[") and text.endswith("]"):
223        inner = text[1:-1].strip()
224        return [_scalar(item, number) for item in _split_flow(inner)] if inner else []
225    if text.startswith("{") and text.endswith("}"):
226        inner = text[1:-1].strip()
227        result: dict[str, object] = {}
228        for part in _split_flow(inner):
229            key, _sep, rest = _split_key(part, number)
230            result[key] = _scalar(rest, number) if rest else None
231        return result
232    if (text.startswith('"') and text.endswith('"')) or (text.startswith("'") and text.endswith("'")):
233        return text[1:-1]
234    lowered = text.lower()
235    if lowered in ("true", "yes", "on"):
236        return True
237    if lowered in ("false", "no", "off"):
238        return False
239    if lowered in ("null", "~"):
240        return None
241    try:
242        return int(text)
243    except ValueError:
244        pass
245    try:
246        return float(text)
247    except ValueError:
248        pass
249    return text
_split_flowdef _split_flow(text: str) -> list[str]
Ver prueba
src/docu/core/yamlmini.py#L252-L279
252def _split_flow(text: str) -> list[str]:
253    """Separa por comas respetando comillas y listas anidadas."""
254    parts: list[str] = []
255    current: list[str] = []
256    depth = 0
257    quote: str | None = None
258    for char in text:
259        if quote:
260            current.append(char)
261            if char == quote:
262                quote = None
263            continue
264        if char in ("'", '"'):
265            quote = char
266            current.append(char)
267            continue
268        if char in "[{":
269            depth += 1
270        elif char in "]}":
271            depth -= 1
272        if char == "," and depth == 0:
273            parts.append("".join(current).strip())
274            current = []
275            continue
276        current.append(char)
277    if current:
278        parts.append("".join(current).strip())
279    return [part for part in parts if part]
CleanPlan.emptydef empty(self) -> bool
Ver prueba
src/docu/delivery/cleanup.py#L54-L55
Anotaciones: @property
54    def empty(self) -> bool:
55        return not (self.documents or self.artifacts or self.state or self.ledger)
CleanPlan.totaldef total(self) -> int
Ver prueba
src/docu/delivery/cleanup.py#L58-L59
Anotaciones: @property
58    def total(self) -> int:
59        return len(self.documents) + len(self.artifacts) + len(self.state) + len(self.ledger)
CleanPlan.to_dictdef to_dict(self) -> dict[str, object]
Ver prueba
src/docu/delivery/cleanup.py#L61-L69
61    def to_dict(self) -> dict[str, object]:
62        return {
63            "documents": [str(path) for path in self.documents],
64            "artifacts": [str(path) for path in self.artifacts],
65            "state": [str(path) for path in self.state],
66            "ledger": [str(path) for path in self.ledger],
67            "warnings": list(self.warnings),
68            "total": self.total,
69        }
_iter_filesdef _iter_files(directory: Path) -> Iterable[Path]
Ver prueba
src/docu/delivery/cleanup.py#L72-L75
72def _iter_files(directory: Path) -> Iterable[Path]:
73    if not directory.is_dir():
74        return []
75    return (path for path in sorted(directory.rglob("*")) if path.is_file())
plandef plan(root: Path | str, docs_dir: Path | str | None=..., documents: bool=..., state: bool=..., ledger: bool=...) -> CleanPlan
Ver prueba
src/docu/delivery/cleanup.py#L78-L117
78def plan(
79    root: Path | str,
80    docs_dir: Path | str | None = None,
81    documents: bool = True,
82    state: bool = True,
83    ledger: bool = False,
84) -> CleanPlan:
85    """Calcula qué borrar. No toca el disco."""
86    root_path = Path(root).resolve()
87    docs = Path(docs_dir) if docs_dir else root_path / "docs" / "generated"
88    result = CleanPlan()
89
90    if docs_dir is not None:
91        try:
92            docs.resolve().relative_to(root_path)
93        except ValueError:
94            result.warnings.append(f"la salida está fuera del proyecto: {docs}")
95
96    if documents:
97        for path in sorted(docs.glob("*.md")) if docs.is_dir() else []:
98            if not GENERATED_DOC_RE.match(path.name):
99                continue  # documentación escrita a mano: no es de docu
100            result.documents.append(path)
101        for name in ARTIFACT_DIRS:
102            for path in _iter_files(docs / name):
103                result.artifacts.append(path)
104                if path.suffix.lower() not in (".md", ".mmd", ".txt", ".json", ".html", ".css", ".js", ".svg"):
105                    result.warnings.append(f"artefacto con extensión inesperada: {path}")
106
107    state_dir = root_path / STATE_DIR
108    if state:
109        for name in STATE_FILES:
110            candidate = state_dir / name
111            if candidate.is_file():
112                result.state.append(candidate)
113    if ledger:
114        candidate = state_dir / LEDGER_FILE
115        if candidate.is_file():
116            result.ledger.append(candidate)
117    return result
applydef apply(plan_result: CleanPlan) -> tuple[int, list[str]]
Ver prueba
src/docu/delivery/cleanup.py#L120-L137
120def apply(plan_result: CleanPlan) -> tuple[int, list[str]]:
121    """Borra lo planificado y devuelve (archivos borrados, errores)."""
122    removed = 0
123    errors: list[str] = []
124    for path in [*plan_result.documents, *plan_result.artifacts, *plan_result.state, *plan_result.ledger]:
125        try:
126            path.unlink()
127            removed += 1
128        except OSError as error:
129            errors.append(f"{path}: {error}")
130    for name in ARTIFACT_DIRS:
131        for parent in {path.parent for path in [*plan_result.artifacts]}:
132            if parent.name == name:
133                try:
134                    parent.rmdir()
135                except OSError:
136                    pass
137    return removed, errors
fingerprintdef fingerprint(paths: Sequence[Path]) -> str
Ver prueba
src/docu/delivery/cleanup.py#L140-L143
140def fingerprint(paths: Sequence[Path]) -> str:
141    """Huella corta de una lista de rutas: permite comparar dos planes sin ruido."""
142    joined = "\n".join(sorted(str(path) for path in paths))
143    return sha256_of(joined)[:12]
_version_textdef _version_text(commands: int=...) -> str
Ver prueba
src/docu/delivery/cli.py#L42-L53
42def _version_text(commands: int = 0) -> str:
43    """Versión, esquema y **desde dónde se está ejecutando**.
44
45    Instalado con `uv tool` o `pipx`, `docu` es una copia congelada del día de la instalación: los
46    comandos nuevos no aparecen hasta reinstalar. Sin la ruta en el `--version` no hay forma de darse
47    cuenta de que estás usando un binario viejo.
48    """
49    import docu as package
50
51    origin = Path(package.__file__).resolve().parent if package.__file__ else "?"
52    suffix = f" · {commands} comandos" if commands else ""
53    return f"docu {__version__} (schema {SCHEMA_VERSION}){suffix} · {origin}"
_Parser.errordef error(self, message: str) -> None
Ver prueba
src/docu/delivery/cli.py#L59-L67
59    def error(self, message: str) -> None:  # pragma: no cover - lo ejerce argparse
60        if "invalid choice" in message:
61            message += (
62                "\n\nSi instalaste docu como herramienta (`uv tool install` / `pipx install`), tu copia "
63                "puede ser anterior a este comando. Actualizá con:\n"
64                "  uv tool install --force <ruta-del-repo>   ·   pipx reinstall docu\n"
65                "Y comprobá con `docu --version`, que muestra la ruta desde la que se ejecuta."
66            )
67        super().error(message)
_build_parserdef _build_parser() -> argparse.ArgumentParser
Ver prueba
src/docu/delivery/cli.py#L70-L267
70def _build_parser() -> argparse.ArgumentParser:
71    parser = _Parser(
72        prog="docu",
73        description="Agente autónomo de documentación técnica: agnóstico, verificable e incremental.",
74        epilog=_EPILOG,
75        formatter_class=argparse.RawDescriptionHelpFormatter,
76    )
77    parser.add_argument(
78        "--profile",
79        default=None,
80        help=f"ruta del perfil (default: {DEFAULT_PROFILE} en la raíz del proyecto)",
81    )
82
83    sub = parser.add_subparsers(dest="command", required=True)
84
85    p_init = sub.add_parser("init", help="detecta el stack y propone un perfil")
86    p_init.add_argument("--root", default=".", help="raíz del proyecto a documentar")
87    p_init.add_argument("--project", default=None, help="nombre del proyecto")
88    p_init.add_argument("--force", action="store_true", help="regenera el perfil desde cero")
89    p_init.add_argument("--apply", action="store_true", help="aplica la orden de cambio propuesta")
90    p_init.add_argument("--dry-run", action="store_true", help="muestra el perfil sin escribirlo")
91
92    p_index = sub.add_parser("index", help="ingesta incremental por content_hash")
93    p_index.add_argument("--since", default=None, help="ref git desde la que indexar")
94
95    p_gen = sub.add_parser("gen", help="genera y audita documentación")
96    # `--profile` viaja también en el subcomando: exigir el orden global es fricción gratuita.
97    p_gen.add_argument("--profile", default=argparse.SUPPRESS, help="perfil del proyecto")
98    p_gen.add_argument("--level", choices=["l1", "l2", "l3", "l4"], action="append", default=None)
99    p_gen.add_argument(
100        "--levels",
101        default=None,
102        help="niveles separados por coma (alias de --level, p. ej. --levels l1,l2)",
103    )
104    p_gen.add_argument("--mode", choices=[m.value for m in Mode], default=None)
105    p_gen.add_argument("--root", default=".", help="raíz del proyecto a documentar")
106    p_gen.add_argument("--out", default=None, help="directorio de salida (default: el del perfil)")
107    p_gen.add_argument("--project", default=None, help="nombre del proyecto en el documento")
108    p_gen.add_argument(
109        "--dry-run",
_guarddef _guard(profile_path: str | None) -> ExitCode | None
Ver prueba
src/docu/delivery/cli.py#L270-L277
270def _guard(profile_path: str | None) -> ExitCode | None:
271    """Verificacion minima previa: si el usuario declaro un perfil, debe existir."""
272    if not profile_path:
273        return None
274    if not Path(profile_path).exists():
275        print(f"error: no existe el perfil {profile_path!r}; ejecuta `docu init`", file=sys.stderr)
276        return ExitCode.CONFIG_ERROR
277    return None
CliError.__init__def __init__(self, message: str, code: ExitCode) -> None
Ver prueba
src/docu/delivery/cli.py#L283-L285
283    def __init__(self, message: str, code: ExitCode) -> None:
284        super().__init__(message)
285        self.code = code
_resolvedef _resolve(args: argparse.Namespace, root: Path) -> ResolvedOptions
Ver prueba
src/docu/delivery/cli.py#L303-L333
303def _resolve(args: argparse.Namespace, root: Path) -> ResolvedOptions:
304    """Combina perfil y banderas. La bandera explícita gana; el perfil rellena el resto."""
305    from docu.core.profile import ProfileError, find, load
306
307    explicit = Path(args.profile) if getattr(args, "profile", None) else None
308    path = explicit if explicit is not None else find(root)
309    try:
310        profile = load(path, fallback_project=root.name) if path else None
311    except ProfileError as error:
312        raise CliError(f"perfil inválido: {error}", ExitCode.CONFIG_ERROR) from None
313
314    # `--levels l1,l2` es alias cómodo de `--level l1 --level l2`.
315    shorthand = getattr(args, "levels", None)
316    cli_levels = tuple(
317        item.strip() for item in (shorthand or "").split(",") if item.strip()
318    ) or tuple(getattr(args, "level", None) or ())
319    levels = cli_levels or (profile.levels if profile else ("l1", "l4"))
320    out = getattr(args, "out", None) or (profile.output_dir if profile else "docs/generated")
321    ttl = getattr(args, "ttl_days", None) or (profile.ttl_days if profile else 90)
322    manifest_flag = getattr(args, "manifest", None)
323    return ResolvedOptions(
324        profile=profile,
325        project=getattr(args, "project", None) or (profile.project if profile else root.name),
326        levels=levels,
327        out_dir=Path(out) if Path(out).is_absolute() else root / out,
328        ttl_days=int(ttl),
329        include=profile.include if profile else (),
330        exclude=profile.effective_exclude if profile else (),
331        thresholds=profile.thresholds if profile else Thresholds(),
332        manifest=Path(manifest_flag) if manifest_flag else None,
333    )
_force_utf8def _force_utf8() -> None
Ver prueba
src/docu/delivery/cli.py#L336-L344
336def _force_utf8() -> None:
337    """Consolas Windows heredadas usan cp1252: sin esto, los acentos salen rotos."""
338    for stream in (sys.stdin, sys.stdout, sys.stderr):
339        reconfigure = getattr(stream, "reconfigure", None)
340        if reconfigure is not None:
341            try:
342                reconfigure(encoding="utf-8", errors="replace")
343            except (ValueError, OSError):  # pragma: no cover - streams ya cerrados
344                pass
maindef main(argv: Sequence[str] | None=...) -> int
Ver prueba
src/docu/delivery/cli.py#L347-L354
347def main(argv: Sequence[str] | None = None) -> int:
348    _force_utf8()
349    args = _build_parser().parse_args(argv)
350    try:
351        return _dispatch(args)
352    except CliError as error:
353        print(f"error: {error}", file=sys.stderr)
354        return int(error.code)
_dispatchdef _dispatch(args: argparse.Namespace) -> int
Ver prueba
src/docu/delivery/cli.py#L357-L407
357def _dispatch(args: argparse.Namespace) -> int:
358    if args.command == "init":
359        return _run_init(args)
360
361    if args.command == "gen":
362        return _run_generate(args)
363
364    if args.command == "status":
365        return _run_status(args, quiet_ok=False)
366
367    if args.command == "ci":
368        if args.ci_command == "check":
369            return _run_status(args, quiet_ok=True, require_manifest=True)
370        return _run_ci_regen(args)
371
372    if args.command == "drift":
373        return _run_drift(args)
374
375    if args.command == "audit":
376        return _run_audit(args)
377
378    if args.command == "site":
379        return _run_site(args)
380
381    if args.command == "pdf":
382        return _run_pdf(args)
383
384    if args.command == "web":
385        return _run_web(args)
386
387    if args.command == "prose":
388        return _run_prose(args)
389
390    if args.command == "clean":
391        return _run_clean(args)
392
393    if args.command == "serve":
394        return _run_serve(args)
395
396    if args.command == "learn":
_learn_settingsdef _learn_settings(root: Path) -> tuple[float, float]
Ver prueba
src/docu/delivery/cli.py#L410-L427
410def _learn_settings(root: Path) -> tuple[float, float]:
411    """Lee los umbrales de promoción del perfil; si no existen, usa los valores documentados."""
412    from docu.core.yamlmini import YamlError, parse
413
414    for name in ("docu.profile.yaml", "docu.profile.yml"):
415        candidate = root / name
416        if not candidate.exists():
417            continue
418        try:
419            document = parse(candidate.read_text(encoding="utf-8"))
420        except YamlError:
421            break
422        section = document.get("learn")
423        if isinstance(section, dict):
424            promote = float(section.get("promotion_delta") or 0.05)  # type: ignore[arg-type]
425            rollback = float(section.get("rollback_drop") or 0.05)  # type: ignore[arg-type]
426            return promote, rollback
427    return 0.05, 0.05
_run_learndef _run_learn(args: argparse.Namespace) -> int
Ver prueba
src/docu/delivery/cli.py#L430-L524
430def _run_learn(args: argparse.Namespace) -> int:
431    """Revisa el ledger, promueve patrones validados o prepara el payload de federación."""
432    import json as jsonlib
433
434    from docu.learn import federation, ledger, patterns, promotion
435
436    root = Path(args.root)
437    ledger_path = ledger.ledger_file(root, args.ledger)
438    patterns_path = Path(args.patterns) if args.patterns else root / patterns.PATTERNS_PATH
439    records = ledger.load(ledger_path)
440    library = patterns.PatternLibrary.load(patterns_path)
441    summary = ledger.summarize(records)
442
443    if args.federate:
444        payload = federation.build_payload(library)
445        if args.json or args.dry_run:
446            print(federation.preview(payload))
447        result = federation.send(payload, args.endpoint, dry_run=args.dry_run or not args.endpoint)
448        if not args.json:
449            print(
450                f"federación: {'enviado' if result.get('sent') else 'no enviado'} · "
451                f"{result.get('patterns', 0)} patrones · {result.get('reason', 'ok')}"
452            )
453        if not result.get("sent") and args.dry_run:
454            return int(ExitCode.OK)
455        return int(ExitCode.OK if result.get("sent") else ExitCode.CONFIG_ERROR)
456
457    promote_delta, rollback_drop = _learn_settings(root)
458
459    if args.promote:
460        decisions = []
461        changed = False
462        for candidate in patterns.candidates_from(records):
463            current = library.patterns.get(candidate.pattern.pattern_id)
464            decision = promotion.decide(
465                current,
466                candidate.pattern,
467                promotion_delta=promote_delta,
468                rollback_drop=rollback_drop,
469            )
_run_auditdef _run_audit(args: argparse.Namespace) -> int
Ver prueba
src/docu/delivery/cli.py#L527-L569
527def _run_audit(args: argparse.Namespace) -> int:
528    """Auditoría determinista: cinco comprobaciones, cero modelos, cero red."""
529    import json as jsonlib
530
531    from docu.audit.verify import audit
532    from docu.generate.pipeline import collect_all_facts_only
533
534    root = Path(args.root).resolve()
535    options = _resolve(args, root)
536    # Mismo universo que el documento: si el manual cita intención, decisiones y secciones del
537    # repositorio, la auditoría también las ve (F-26: dos totales distintos en la misma corrida).
538    facts = collect_all_facts_only(
539        root,
540        include=options.include,
541        exclude=options.exclude,
542        include_tests=getattr(args, "include_tests", False),
543        project=options.project,
544    )
545    report = audit(
546        root,
547        docs_dir=args.out or options.out_dir,
548        levels=options.levels,
549        profile_path=str(options.profile.path) if options.profile and options.profile.path else None,
550        facts=facts,
551    )
552
553    if args.report:
554        destination = Path(args.report)
555        destination.parent.mkdir(parents=True, exist_ok=True)
556        destination.write_text(report.to_markdown(), encoding="utf-8")
557
558    if args.json:
559        print(jsonlib.dumps(report.to_dict(), ensure_ascii=False, indent=2))
560    else:
561        print(report.to_markdown())
562
563    if report.score < args.min_score:
564        print(
565            f"auditoría por debajo del mínimo: {report.score:.1f} < {args.min_score:.1f}",
566            file=sys.stderr,
_run_sitedef _run_site(args: argparse.Namespace) -> int
Ver prueba
src/docu/delivery/cli.py#L572-L614
572def _run_site(args: argparse.Namespace) -> int:
573    """Publica la web: lo esencial visible y la prueba a un clic."""
574    from docu.core.contracts import sha256_of
575    from docu.generate.facts import unsupported
576    from docu.generate.pipeline import collect_facts
577    from docu.publish.site import build_site
578
579    root = Path(args.root).resolve()
580    options = _resolve(args, root)
581    levels = tuple(args.site_levels or options.levels)
582    facts, sources = collect_facts(
583        root, include=options.include, exclude=options.exclude, include_tests=getattr(args, "include_tests", False)
584    )
585    if not facts:
586        print("error: no se detectó nada documentable", file=sys.stderr)
587        return int(ExitCode.UNCITABLE_SOURCE)
588
589    digest = sha256_of("|".join(f"{path}:{sha}" for path, sha in sorted(sources.items())))[:12]
590    # `--out` es la web; la documentación generada (y sus diagramas) se resuelve aparte: mezclarlas
591    # hacía que la web buscara los diagramas dentro de su propia carpeta de salida.
592    # `options.out_dir` ya está resuelto contra la raíz del proyecto: usar `profile.output_dir`
593    # a secas escribía en el directorio actual cuando `--root` apuntaba a otro proyecto.
594    docs_dir = Path(args.docs) if getattr(args, "docs", None) else options.out_dir
595    out_dir = Path(args.out) if args.out else docs_dir / "site"
596    project = options.project or root.name
597    pages = build_site(
598        root,
599        out_dir,
600        project,
601        facts,
602        meta={
603            "version": __version__,
604            "digest": digest,
605            "facts": str(len(facts)),
606            "unsupported": str(len(unsupported(facts))),
607        },
608        levels=levels,
609        diagrams_dir=docs_dir / "diagrams",
610    )
611    print(f"{project}: {len(facts)} afirmaciones · {len(pages)} páginas · web en {out_dir}")
_run_webdef _run_web(args: argparse.Namespace) -> int
Ver prueba
src/docu/delivery/cli.py#L617-L675
617def _run_web(args: argparse.Namespace) -> int:
618    """Captura o inspecciona fuentes web congeladas.
619
620    Descargar es una decisión explícita: `--fetch` captura, `--check` compara con la web y sin
621    banderas sólo se muestra lo que ya está congelado. La generación nunca toca la red.
622    """
623    from docu.index.webdocs import capture_urls, check_stale, load_documents, read_index
624
625    root = Path(args.root).resolve()
626    options = _resolve(args, root)
627    urls = tuple(args.web_urls or ()) or (options.profile.web_urls if options.profile else ())
628    allowlist = options.profile.web_allowlist if options.profile else ()
629    # `options.out_dir` ya está resuelto contra la raíz del proyecto: usar `profile.output_dir`
630    # a secas escribía en el directorio actual cuando `--root` apuntaba a otro proyecto.
631    docs_dir = Path(args.docs) if getattr(args, "docs", None) else options.out_dir
632
633    if not urls:
634        print(
635            "error: no hay URLs declaradas. Añade `sources.web.urls` al perfil o pasa --url",
636            file=sys.stderr,
637        )
638        return int(ExitCode.CONFIG_ERROR)
639
640    if args.check:
641        if not allowlist:
642            print("error: `--check` necesita allowlist en el perfil", file=sys.stderr)
643            return int(ExitCode.CONFIG_ERROR)
644        for url, state in check_stale(root, allowlist):
645            print(f"  {url}: {state}")
646        return int(ExitCode.OK)
647
648    if args.fetch:
649        if not allowlist:
650            print(
651                "error: declara `sources.web.allowlist` en el perfil antes de capturar nada",
652                file=sys.stderr,
653            )
654            return int(ExitCode.CONFIG_ERROR)
655        documents, errors = capture_urls(root, urls, allowlist, docs_dir)
656        captured = sum(1 for document in documents if document.usable)
_run_pdfdef _run_pdf(args: argparse.Namespace) -> int
Ver prueba
src/docu/delivery/cli.py#L678-L734
678def _run_pdf(args: argparse.Namespace) -> int:
679    """Extrae texto de los PDFs y reporta qué se pudo leer y qué no.
680
681    Salida distinta de cero cuando **ningún** documento es usable: es un fallo de la fuente, no una
682    página vacía, y conviene que el CI lo note.
683    """
684    import json as jsonlib
685
686    from docu.index.pdfdocs import load_all, write_sidecars
687
688    root = Path(args.root).resolve()
689    options = _resolve(args, root)
690    documents, texts, _digests = load_all(
691        root, include=options.include, exclude=options.exclude
692    )
693    if not documents:
694        print(f"{options.project or root.name}: no hay PDFs en el proyecto")
695        return int(ExitCode.NO_CHANGES)
696
697    docs_dir = Path(args.out) if args.out else options.out_dir
698    written = write_sidecars(texts, docs_dir / "pdf")
699
700    if args.json:
701        print(
702            jsonlib.dumps(
703                [
704                    {
705                        "document": document.rel,
706                        "pages": document.pages,
707                        "chars": document.chars,
708                        "method": document.method,
709                        "status": document.status,
710                        "usable": document.usable,
711                        "warnings": list(document.warnings),
712                        "sidecar": str(docs_dir / "pdf") if document.rel in texts else None,
713                    }
714                    for document in documents
715                ],
716                ensure_ascii=False,
717                indent=2,
_run_cleandef _run_clean(args: argparse.Namespace) -> int
Ver prueba
src/docu/delivery/cli.py#L737-L789
737def _run_clean(args: argparse.Namespace) -> int:
738    """Vuelve a cero: documentos, artefactos y estado. Simula salvo `--force`.
739
740    Nunca borra recursivamente el directorio de salida: sólo los `.md` de su raíz y sus carpetas de
741    artefactos. Si alguien apuntó `--out` a una carpeta con documentación escrita a mano, no se toca.
742    """
743    import json as jsonlib
744
745    from docu.delivery.cleanup import apply as apply_plan
746    from docu.delivery.cleanup import plan as build_plan
747
748    root = Path(args.root).resolve()
749    options = _resolve(args, root)
750    docs_dir = Path(args.out) if args.out else options.out_dir
751    documents = not getattr(args, "state_only", False)
752    state = not getattr(args, "docs_only", False)
753
754    result = build_plan(
755        root,
756        docs_dir=docs_dir,
757        documents=documents,
758        state=state,
759        ledger=bool(getattr(args, "ledger", False)),
760    )
761    if result.empty:
762        print(f"{options.project}: no hay nada generado que borrar en {docs_dir}")
763        return int(ExitCode.NO_CHANGES)
764
765    for warning in result.warnings:
766        print(f"  aviso: {warning}", file=sys.stderr)
767    for label, paths in (
768        ("documento", result.documents),
769        ("artefacto", result.artifacts),
770        ("estado", result.state),
771        ("ledger", result.ledger),
772    ):
773        for path in paths:
774            print(f"  {label}: {path}")
775
776    if not args.force:
_run_prosedef _run_prose(args: argparse.Namespace) -> int
Ver prueba
src/docu/delivery/cli.py#L792-L897
792def _run_prose(args: argparse.Namespace) -> int:
793    """Delega la redacción al agente del entorno y valida lo que devuelve.
794
795    `docu` no llama a ningún modelo: emite la petición con los hechos citados y acepta la respuesta
796    sólo si cada frase cita hechos existentes y no aporta cifras nuevas. El juez es opcional y también
797    se delega a un segundo agente; su nota es asesora.
798    """
799    import json as jsonlib
800
801    from docu.generate import prose as prose_module
802    from docu.generate.pipeline import collect_all_facts_only
803
804    root = Path(args.root).resolve()
805    options = _resolve(args, root)
806    facts = collect_all_facts_only(
807        root, include=options.include, exclude=options.exclude, project=options.project
808    )
809    if not any(fact.kind in prose_module.NARRATIVE_KINDS for fact in facts):
810        print("error: no hay hechos que ofrecer al redactor", file=sys.stderr)
811        return int(ExitCode.UNCITABLE_SOURCE)
812
813    directory = Path(args.out) if args.out else root / prose_module.PROSE_DIR
814    project = options.project
815
816    if args.apply:
817        source = Path(args.apply)
818        if not source.is_file():
819            print(f"error: no existe {source}", file=sys.stderr)
820            return int(ExitCode.CONFIG_ERROR)
821        try:
822            payload = jsonlib.loads(source.read_text(encoding="utf-8"))
823        except jsonlib.JSONDecodeError as error:
824            print(f"error: JSON inválido: {error}", file=sys.stderr)
825            return int(ExitCode.CONFIG_ERROR)
826        if args.reviewer:
827            payload["reviewer"] = args.reviewer
828        response, _index = prose_module.validate(payload, facts)
829        for warning in response.warnings:
830            print(f"  aviso: {warning}", file=sys.stderr)
831        if not response.accepted:
_run_servedef _run_serve(args: argparse.Namespace) -> int
Ver prueba
src/docu/delivery/cli.py#L900-L928
900def _run_serve(args: argparse.Namespace) -> int:
901    """Sirve la documentación por MCP: stdio (por defecto) o puente HTTP con `--port`."""
902    from docu.delivery.mcp_server import build_server
903
904    if not args.mcp:
905        print(
906            "error: el servidor solo habla MCP (`docu serve --mcp`); "
907            "sin --port usa stdio, con --port usa el puente HTTP",
908            file=sys.stderr,
909        )
910        return int(ExitCode.CONFIG_ERROR)
911
912    server = build_server(
913        args.root,
914        args.out,
915        workspace=args.workspace,
916        profile_path=getattr(args, "profile", None),
917    )
918    if args.workspace:
919        projects = server.projects()
920        documented = ", ".join(ref.name for ref in projects) or "ninguno"
921        print(f"workspace: {len(projects)} proyectos · {documented}", file=sys.stderr)
922
923    if args.port:
924        from docu.delivery.http_server import serve_http
925
926        serve_http(server, port=args.port)
927        return int(ExitCode.OK)
928    return server.serve()
_run_driftdef _run_drift(args: argparse.Namespace) -> int
Ver prueba
src/docu/delivery/cli.py#L931-L974
931def _run_drift(args: argparse.Namespace) -> int:
932    """Compara arquitectura declarada y código real. Bootstrap incluido para empezar de cero."""
933    import json as jsonlib
934
935    from docu.conformance.drift import analyze, bootstrap
936    from docu.conformance.model import to_yaml
937
938    root = Path(args.root)
939
940    if args.bootstrap:
941        model = bootstrap(root, include_tests=args.include_tests)
942        if model.is_empty:
943            print("error: no se detectaron componentes ni rutas para bootstrappear", file=sys.stderr)
944            return int(ExitCode.CONFIG_ERROR)
945        destination = Path(args.out) if Path(args.out).is_absolute() else root / args.out
946        destination.parent.mkdir(parents=True, exist_ok=True)
947        destination.write_text(to_yaml(model, root.name), encoding="utf-8")
948        print(
949            f"modelo inicial escrito en {destination} · "
950            f"{len(model.components)} componentes · revisa y corrige antes de confiar en él"
951        )
952        return int(ExitCode.OK)
953
954    report = analyze(root, args.architecture, include_tests=args.include_tests)
955    if report.model.is_empty:
956        print(
957            "error: no hay modelo arquitectónico. Crea architecture.yaml u openapi.yaml, "
958            "o genera una foto inicial con `docu drift --bootstrap`",
959            file=sys.stderr,
960        )
961        return int(ExitCode.CONFIG_ERROR)
962
963    if args.json:
964        print(jsonlib.dumps(report.to_dict(), ensure_ascii=False, indent=2))
965    else:
966        print(report.to_markdown())
967    if report.is_clean:
968        return int(ExitCode.OK)
969    if not args.json:
970        print(
_run_initdef _run_init(args: argparse.Namespace) -> int
Ver prueba
src/docu/delivery/cli.py#L977-L1077
977def _run_init(args: argparse.Namespace) -> int:
978    """Detecta el stack y propone el perfil. Si ya existe, produce una **orden de cambio**.
979
980    Reejecutar `init` no es destructivo por defecto: la detección puede añadir estructura
981    (niveles nuevos, exclusiones nuevas, glosario semilla) pero nunca reescribe umbrales, modo, TTL
982    ni el vocabulario que escribió una persona.
983    """
984    from docu.core.profile import (
985        ProfileError,
986        candidate_paths,
987        find,
988        load,
989        merge,
990        plan_changes,
991        render_change_order,
992        to_yaml,
993    )
994    from docu.delivery.proposal import propose
995
996    root = Path(args.root).resolve()
997    if not root.exists():
998        print(f"error: no existe la raíz {root}", file=sys.stderr)
999        return int(ExitCode.CONFIG_ERROR)
1000
1001    try:
1002        proposed = propose(root, project=args.project)
1003    except ProfileError as error:
1004        print(f"error: {error}", file=sys.stderr)
1005        return int(ExitCode.CONFIG_ERROR)
1006
1007    existing_path = find(root)
1008
1009    # Caso 1: no hay perfil (o se pidió regenerar desde cero).
1010    if existing_path is None or args.force:
1011        rendered = to_yaml(proposed)
1012        destination = existing_path or candidate_paths(root)[0]
1013        print(f"proyecto: {proposed.project}")
1014        print(f"  niveles propuestos: {', '.join(proposed.levels)}")
1015        print(f"  exclusiones por defecto: {len(proposed.exclude)} patrones")
1016        if proposed.glossary:
_run_generatedef _run_generate(args: argparse.Namespace) -> int
Ver prueba
src/docu/delivery/cli.py#L1080-L1150
1080def _run_generate(args: argparse.Namespace) -> int:
1081    """Genera documentación obedeciendo el perfil, y traduce la compuerta a código de salida."""
1082    from docu.generate.pipeline import generate
1083
1084    root = Path(args.root).resolve()
1085    options = _resolve(args, root)
1086    unsupported_levels = [level for level in options.levels if level not in ("l1", "l2", "l3", "l4")]
1087    if unsupported_levels:
1088        print(
1089            f"error: niveles disponibles hoy: l1, l2, l3, l4 (pedidos: {', '.join(unsupported_levels)})",
1090            file=sys.stderr,
1091        )
1092        return int(ExitCode.CONFIG_ERROR)
1093
1094    result = generate(
1095        root,
1096        options.out_dir,
1097        levels=options.levels,
1098        project=options.project,
1099        include_tests=args.include_tests,
1100        stamp=args.stamp,
1101        incremental=args.incremental,
1102        manifest_path=options.manifest,
1103        ttl_days=options.ttl_days,
1104        include=options.include,
1105        exclude=options.exclude,
1106        thresholds=options.thresholds,
1107        dry_run=bool(getattr(args, "dry_run", False)),
1108    )
1109    states = ", ".join(f"{level}={state.value}" for level, state in result.states.items())
1110    origin = f"perfil {options.profile.path.name}" if options.profile and options.profile.path else "sin perfil (detección automática)"
1111    print(
1112        f"{result.project}: {len(result.facts)} afirmaciones · "
1113        f"sin cita: {len(result.unsupported)} · "
1114        f"completitud de compuerta {result.metrics.completeness:.1f}/10 · "
1115        f"concisión {result.metrics.conciseness:.1f}/10 · {result.elapsed_s:.2f}s · {origin}"
1116    )
1117    if states:
1118        print(f"  frescura: {states}")
1119    if result.unsupported_languages:
_run_statusdef _run_status(args: argparse.Namespace, quiet_ok: bool, require_manifest: bool=...) -> int
Ver prueba
src/docu/delivery/cli.py#L1153-L1244
1153def _run_status(
1154    args: argparse.Namespace, quiet_ok: bool, require_manifest: bool = False
1155) -> int:
1156    """Valida frescura. No genera nada: es la comprobación rápida de cada PR."""
1157    import json as jsonlib
1158
1159    from docu.core.contracts import DocState
1160    from docu.generate.pipeline import inspect
1161
1162    # F9: --languages short-circuits and prints supported languages
1163    if getattr(args, "languages", False):
1164        from docu.adapters.langs.registry import supported_languages
1165
1166        print("Lenguajes soportados:")
1167        for lang in supported_languages():
1168            print(f"  {lang}")
1169        return int(ExitCode.OK)
1170
1171    root = Path(args.root).resolve()
1172    options = _resolve(args, root)
1173    manifest, states, hashes = inspect(
1174        root,
1175        levels=options.levels,
1176        manifest_path=options.manifest,
1177        ttl_days=options.ttl_days,
1178        include=options.include,
1179        exclude=options.exclude,
1180    )
1181    from docu.generate.pipeline import manifest_file
1182
1183    resolved_manifest = manifest_file(root, options.manifest)
1184    missing = [level for level, state in states.items() if state is DocState.MISSING]
1185    payload = {
1186        "project": manifest.project if manifest else None,
1187        "manifest": str(resolved_manifest),
1188        # `generated` significa «existe documentación en disco», no «hay un manifest».
1189        "generated": manifest is not None and not missing,
1190        "missing": missing,
1191        "profile": str(options.profile.path) if options.profile and options.profile.path else None,
1192        "states": {level: state.value for level, state in states.items()},
_print_status_whydef _print_status_why(root: Path, options, manifest) -> None
Ver prueba
src/docu/delivery/cli.py#L1247-L1276
1247def _print_status_why(root: Path, options, manifest) -> None:
1248    """Qué archivos invalidaron la frescura. Sin esto, «stale» es una acusación sin nombre.
1249
1250    Compara las huellas guardadas en el manifest con las actuales: lista agregados, modificados y
1251    eliminados. Editar `.gitignore` aparece aquí como lo que es —cambia el inventario— en lugar de
1252    como un fantasma.
1253    """
1254    from docu.generate.pipeline import collect_facts
1255
1256    _facts, current = collect_facts(
1257        root, include=options.include, exclude=options.exclude
1258    )
1259    recorded: dict[str, str] = {}
1260    for level in options.levels:
1261        entry = manifest.entry(level) if manifest is not None else None
1262        if entry is not None and entry.sources:
1263            recorded = dict(entry.sources)
1264            break
1265    if not recorded:
1266        print("  no hay inventario guardado: la primera generación lo escribirá", file=sys.stderr)
1267        return
1268    added = sorted(set(current) - set(recorded))
1269    removed = sorted(set(recorded) - set(current))
1270    changed = sorted(path for path in set(current) & set(recorded) if current[path] != recorded[path])
1271    print(f"  causa ({len(added) + len(removed) + len(changed)} archivos):", file=sys.stderr)
1272    for label, paths in (("nuevo", added), ("modificado", changed), ("eliminado", removed)):
1273        for path in paths[:10]:
1274            print(f"    {label}: {path}", file=sys.stderr)
1275        if len(paths) > 10:
1276            print(f"    {label}: … y {len(paths) - 10} más", file=sys.stderr)
_run_ci_regendef _run_ci_regen(args: argparse.Namespace) -> int
Ver prueba
src/docu/delivery/cli.py#L1279-L1330
1279def _run_ci_regen(args: argparse.Namespace) -> int:
1280    """Regenera lo stale y deja el cuerpo del PR listo para la acción de CI."""
1281    from docu.generate.pipeline import generate
1282
1283    root = Path(args.root).resolve()
1284    options = _resolve(args, root)
1285    result = generate(
1286        root,
1287        options.out_dir,
1288        levels=options.levels,
1289        project=options.project,
1290        incremental=True,
1291        manifest_path=options.manifest,
1292        ttl_days=options.ttl_days,
1293        include=options.include,
1294        exclude=options.exclude,
1295        thresholds=options.thresholds,
1296    )
1297    body_path = Path(args.pr_body) if args.pr_body else root / ".docu" / "pr-body.md"
1298    root_path = root
1299
1300    def _relative(path: Path) -> str:
1301        try:
1302            return path.resolve().relative_to(root_path).as_posix()
1303        except ValueError:
1304            return str(path)
1305
1306    lines = [
1307        "## Documentación regenerada por `docu`",
1308        "",
1309        f"- Proyecto: `{result.project}`",
1310        f"- Afirmaciones: {len(result.facts)} · sin cita: {len(result.unsupported)}",
1311        f"- Completitud: {result.metrics.completeness:.1f}/10 · concisión: {result.metrics.conciseness:.1f}/10",
1312        f"- Compuerta: `{result.gate.outcome.value}`",
1313        "",
1314        "| Nivel | Estado detectado |",
1315        "|---|---|",
1316    ]
1317    lines += [f"| {level} | {state.value} |" for level, state in result.states.items()]
1318    if result.docs:
_Handler.do_GETdef do_GET(self) -> None
Ver prueba
src/docu/delivery/http_server.py#L32-L49
32    def do_GET(self) -> None:
33        if self.path.rstrip("/") in ("/health", ""):
34            self._json(
35                200,
36                {
37                    "status": "ok",
38                    "protocol_version": PROTOCOL_VERSION,
39                    "projects": [
40                        {"name": ref.name, "documented": ref.has_docs} for ref in self.mcp.projects()
41                    ],
42                },
43            )
44            return
45        if self.path.rstrip("/") == "/projects":
46            payload = self.mcp.call_tool("list_projects", {})
47            self._json(200, payload)
48            return
49        self._json(404, {"error": f"ruta desconocida: {self.path}"})
_Handler.do_POSTdef do_POST(self) -> None
Ver prueba
src/docu/delivery/http_server.py#L51-L76
51    def do_POST(self) -> None:
52        if self.path.rstrip("/") != "/mcp":
53            self._json(404, {"error": f"ruta desconocida: {self.path}"})
54            return
55        length = int(self.headers.get("Content-Length") or 0)
56        if length <= 0:
57            self._json(400, {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": "cuerpo vacío"}})
58            return
59        if length > MAX_BODY_BYTES:
60            self._json(413, {"error": "cuerpo demasiado grande"})
61            return
62        raw = self.rfile.read(length)
63        try:
64            request = json.loads(raw)
65        except json.JSONDecodeError as error:
66            self._json(400, {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": f"JSON inválido: {error}"}})
67            return
68        if not isinstance(request, dict):
69            self._json(400, {"jsonrpc": "2.0", "id": None, "error": {"code": -32600, "message": "se esperaba un objeto"}})
70            return
71        response = self.mcp.handle(request)
72        if response is None:
73            self.send_response(204)
74            self.end_headers()
75            return
76        self._json(200, response)
_Handler._jsondef _json(self, status: int, payload: dict[str, Any]) -> None
Ver prueba
src/docu/delivery/http_server.py#L80-L86
80    def _json(self, status: int, payload: dict[str, Any]) -> None:
81        body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
82        self.send_response(status)
83        self.send_header("Content-Type", "application/json; charset=utf-8")
84        self.send_header("Content-Length", str(len(body)))
85        self.end_headers()
86        self.wfile.write(body)
_Handler.log_messagedef log_message(self, fmt: str, *args) -> None
Ver prueba
src/docu/delivery/http_server.py#L88-L89
88    def log_message(self, fmt: str, *args: Any) -> None:  # silencio: el servidor habla por stderr
89        print(f"[mcp-http] {fmt % args}", file=sys.stderr)
make_serverdef make_server(server: McpServer, host: str=..., port: int=...) -> ThreadingHTTPServer
Ver prueba
src/docu/delivery/http_server.py#L92-L94
92def make_server(server: McpServer, host: str = DEFAULT_HOST, port: int = 8765) -> ThreadingHTTPServer:
93    handler = type("BoundHandler", (_Handler,), {"mcp": server})
94    return ThreadingHTTPServer((host, port), handler)
serve_httpdef serve_http(server: McpServer, host: str=..., port: int=...) -> tuple[ThreadingHTTPServer, str]
Ver prueba
src/docu/delivery/http_server.py#L97-L114
97def serve_http(
98    server: McpServer,
99    host: str = DEFAULT_HOST,
100    port: int = 8765,
101    *,
102    blocking: bool = True,
103) -> tuple[ThreadingHTTPServer, str]:
104    """Arranca el puente HTTP. Devuelve el servidor y su URL base."""
105    httpd = make_server(server, host, port)
106    actual_port = httpd.server_address[1]
107    url = f"http://{host}:{actual_port}"
108    print(f"MCP HTTP escuchando en {url} (POST /mcp · GET /health)", file=sys.stderr)
109    if blocking:
110        try:
111            httpd.serve_forever()
112        except KeyboardInterrupt:  # pragma: no cover - interacción de consola
113            pass
114    return httpd, url
ProjectRef.has_docsdef has_docs(self) -> bool
Ver prueba
src/docu/delivery/mcp_server.py#L172-L173
Anotaciones: @property
172    def has_docs(self) -> bool:
173        return self.docs_dir.exists() and any(self.docs_dir.glob("*.md"))
ProjectRef.project_namedef project_name(self) -> str
Ver prueba
src/docu/delivery/mcp_server.py#L176-L188
Anotaciones: @property
176    def project_name(self) -> str:
177        """Nombre documentado del proyecto (el del manifest), no el del directorio.
178
179        Sin esto, `list_projects` devolvía `name: ""` y un agente multi-proyecto no podía saber qué
180        estaba consultando.
181        """
182        from docu.generate.pipeline import manifest_file
183        from docu.index.manifest import Manifest
184
185        manifest = Manifest.load(manifest_file(self.root, None))
186        if manifest is not None and manifest.project:
187            return manifest.project
188        return self.root.name
_documented_filesdef _documented_files(ref: ProjectRef) -> int
Ver prueba
src/docu/delivery/mcp_server.py#L191-L203
191def _documented_files(ref: ProjectRef) -> int:
192    """Archivos que el manual declaró haber analizado (inventario del manifest)."""
193    from docu.generate.pipeline import manifest_file
194    from docu.index.manifest import Manifest
195
196    manifest = Manifest.load(manifest_file(ref.root, None))
197    if manifest is None:
198        return 0
199    for level in ("l1", "l2", "l4"):
200        entry = manifest.entry(level)
201        if entry is not None and entry.sources:
202            return len(entry.sources)
203    return 0
McpServer.__post_init__def __post_init__(self) -> None
Ver prueba
src/docu/delivery/mcp_server.py#L229-L238
229    def __post_init__(self) -> None:
230        root_ref = ProjectRef(name=self.root.name, root=self.root, docs_dir=self.docs_dir)
231        self._refs = {}
232        # En modo workspace solo se sirve la raíz si tiene documentación: la carpeta contenedora
233        # no es un proyecto, y listarla confunde al agente que elige destino.
234        if self.workspace is None or root_ref.has_docs:
235            self._refs[root_ref.name] = root_ref
236        if self.workspace is not None:
237            for ref in discover_workspace(self.workspace):
238                self._refs.setdefault(ref.name, ref)
McpServer.projectsdef projects(self) -> list[ProjectRef]
Ver prueba
src/docu/delivery/mcp_server.py#L242-L244
242    def projects(self) -> list[ProjectRef]:
243        """Proyectos servidos: la raíz del servidor y los descubiertos en el workspace."""
244        return list(self._refs.values())
McpServer.resolvedef resolve(self, arguments: Mapping[str, Any]) -> ProjectRef
Ver prueba
src/docu/delivery/mcp_server.py#L246-L264
246    def resolve(self, arguments: Mapping[str, Any]) -> ProjectRef:
247        """Proyecto solicitado; si hay uno solo, no hace falta nombrarlo."""
248        requested = str(arguments.get("project") or "").strip()
249        candidates = self.projects()
250        if requested:
251            for ref in candidates:
252                if ref.name == requested:
253                    return ref
254            names = ", ".join(sorted(ref.name for ref in candidates)) or "ninguno"
255            raise ToolError(f"proyecto desconocido: {requested!r} (disponibles: {names})")
256        if len(candidates) == 1:
257            return candidates[0]
258        if not candidates:
259            raise ToolError(
260                "no hay proyectos documentados; ejecuta `docu gen` en el proyecto "
261                "o apunta el servidor a un workspace con documentación"
262            )
263        names = ", ".join(sorted(ref.name for ref in candidates)) or "ninguno"
264        raise ToolError(f"hay varios proyectos: indica 'project' ({names})")
McpServer._index_fordef _index_for(self, ref: ProjectRef) -> DocIndex
Ver prueba
src/docu/delivery/mcp_server.py#L266-L271
266    def _index_for(self, ref: ProjectRef) -> DocIndex:
267        index = self._indexes.get(ref.name)
268        if index is None:
269            index = DocIndex.from_directory(ref.docs_dir, glossary=self._glossary(ref))
270            self._indexes[ref.name] = index
271        return index
McpServer.indexdef index(self) -> DocIndex
Ver prueba
src/docu/delivery/mcp_server.py#L274-L282
Anotaciones: @property
274    def index(self) -> DocIndex:
275        """Indice del proyecto raíz (o del primero disponible si la raíz no está documentada)."""
276        ref = self._refs.get(self.root.name)
277        if ref is None:
278            candidates = self.projects()
279            if not candidates:
280                raise ToolError("no hay proyectos documentados")
281            ref = candidates[0]
282        return self._index_for(ref)
McpServer._glossarydef _glossary(self, ref: ProjectRef) -> Mapping[str, Sequence[str]] | None
Ver prueba
src/docu/delivery/mcp_server.py#L285-L300
285    def _glossary(self, ref: ProjectRef) -> Mapping[str, Sequence[str]] | None:
286        """Glosario por defecto + el del perfil: el MCP responde con el vocabulario del proyecto.
287
288        El perfil puede estar **fuera** del repositorio (por ejemplo, si se generó la documentación
289        sin escribir nada dentro del proyecto): se acepta explícitamente con `--profile`.
290        """
291        from docu.core.profile import find, load
292        from docu.retrieve.glossary import DEFAULT_GLOSSARY, merge
293
294        path = self.profile_path or find(ref.root)
295        if path is None:
296            return None
297        profile = load(path, fallback_project=ref.root.name)
298        if profile is None or not profile.glossary:
299            return None
300        return merge(DEFAULT_GLOSSARY, profile.glossary)
McpServer._require_docsdef _require_docs(self, ref: ProjectRef) -> DocIndex
Ver prueba
src/docu/delivery/mcp_server.py#L303-L310
303    def _require_docs(self, ref: ProjectRef) -> DocIndex:
304        index = self._index_for(ref)
305        if index.is_empty:
306            raise ToolError(
307                f"no hay documentación generada para {ref.name!r} en {ref.docs_dir}; "
308                f"ejecuta `docu gen --root {ref.root} --out {ref.docs_dir}`"
309            )
310        return index
McpServer.call_tooldef call_tool(self, name: str, arguments: Mapping[str, Any]) -> dict[str, Any]
Ver prueba
src/docu/delivery/mcp_server.py#L314-L318
314    def call_tool(self, name: str, arguments: Mapping[str, Any]) -> dict[str, Any]:
315        if name not in READ_ONLY_TOOLS:
316            raise ToolError(f"herramienta desconocida: {name}")
317        handler = getattr(self, f"_tool_{name}")
318        return handler(dict(arguments))
McpServer._tool_list_projectsdef _tool_list_projects(self, arguments: Mapping[str, Any]) -> dict[str, Any]
Ver prueba
src/docu/delivery/mcp_server.py#L320-L333
320    def _tool_list_projects(self, arguments: Mapping[str, Any]) -> dict[str, Any]:
321        del arguments
322        return {
323            "projects": [
324                {
325                    "name": ref.project_name,
326                    "root": str(ref.root),
327                    "docs_dir": str(ref.docs_dir),
328                    "documented": ref.has_docs,
329                }
330                for ref in self.projects()
331            ],
332            "total": len(self.projects()),
333        }
McpServer._tool_search_codedef _tool_search_code(self, arguments: Mapping[str, Any]) -> dict[str, Any]
Ver prueba
src/docu/delivery/mcp_server.py#L335-L362
335    def _tool_search_code(self, arguments: Mapping[str, Any]) -> dict[str, Any]:
336        """Recuperación sobre el código: tres canales fusionados, con citas de línea."""
337        from docu.retrieve.hybrid import build_index
338
339        ref = self.resolve(arguments)
340        query = str(arguments.get("query") or "").strip()
341        if not query:
342            raise ToolError("'query' es obligatorio")
343        limit = max(1, min(int(arguments.get("limit") or 8), 20))
344        index = self._code_indexes.get(ref.name)
345        if index is None:
346            index = build_index(ref.root, dense=self.dense, glossary=self._glossary(ref))
347            self._code_indexes[ref.name] = index
348        hits = index.search(query, limit=limit)  # type: ignore[attr-defined]
349        if not hits:
350            raise ToolError(f"sin coincidencias en el código de {ref.name!r} para {query!r}")
351        return {
352            "project": ref.name,
353            "query": query,
354            "capabilities": {
355                **index.capabilities(),  # type: ignore[attr-defined]
356                # F-03: el manual cuenta todos los archivos analizados; el índice, los de código.
357                # Se publican ambos para que la diferencia no sea silenciosa.
358                "files_documented": _documented_files(ref),
359            },
360            "results": [chunk.to_dict(score) for chunk, score in hits],
361            "total": len(hits),
362        }
McpServer._tool_search_docsdef _tool_search_docs(self, arguments: Mapping[str, Any]) -> dict[str, Any]
Ver prueba
src/docu/delivery/mcp_server.py#L364-L388
364    def _tool_search_docs(self, arguments: Mapping[str, Any]) -> dict[str, Any]:
365        ref = self.resolve(arguments)
366        index = self._require_docs(ref)
367        query = str(arguments.get("query") or "").strip()
368        if not query:
369            raise ToolError("'query' es obligatorio")
370        limit = int(arguments.get("limit") or 5)
371        level = arguments.get("level")
372        hits = index.search(query, limit=max(1, min(limit, 20)), level=str(level) if level else None)
373        return {
374            "project": ref.name,
375            "query": query,
376            "results": [
377                {
378                    "heading": section.heading,
379                    "document": section.document,
380                    "level": section.level,
381                    "score": round(score, 4),
382                    "citations": list(section.citations),
383                    "excerpt": _excerpt(section.body),
384                }
385                for section, score in hits
386            ],
387            "total": len(hits),
388        }
McpServer._tool_get_moduledef _tool_get_module(self, arguments: Mapping[str, Any]) -> dict[str, Any]
Ver prueba
src/docu/delivery/mcp_server.py#L390-L408
390    def _tool_get_module(self, arguments: Mapping[str, Any]) -> dict[str, Any]:
391        ref = self.resolve(arguments)
392        index = self._require_docs(ref)
393        name = str(arguments.get("name") or "").strip()
394        if not name:
395            raise ToolError("'name' es obligatorio")
396        hits = index.search(name, limit=5, expand_query=False)
397        if not hits:
398            raise ToolError(f"sin documentación para el módulo {name!r} en {ref.name!r}")
399        section, score = hits[0]
400        return {
401            "project": ref.name,
402            "module": name,
403            "heading": section.heading,
404            "document": section.document,
405            "score": round(score, 4),
406            "citations": list(section.citations),
407            "body": section.body,
408        }
McpServer._tool_get_symbol_docdef _tool_get_symbol_doc(self, arguments: Mapping[str, Any]) -> dict[str, Any]
Ver prueba
src/docu/delivery/mcp_server.py#L410-L428
410    def _tool_get_symbol_doc(self, arguments: Mapping[str, Any]) -> dict[str, Any]:
411        ref = self.resolve(arguments)
412        index = self._require_docs(ref)
413        symbol = str(arguments.get("symbol") or "").strip()
414        if not symbol:
415            raise ToolError("'symbol' es obligatorio")
416        hits = index.search(symbol, limit=5, expand_query=False)
417        evidence = [
418            {
419                "heading": section.heading,
420                "document": section.document,
421                "citations": list(section.citations),
422                "excerpt": _excerpt(section.body),
423            }
424            for section, _score in hits
425        ]
426        if not evidence:
427            raise ToolError(f"el símbolo {symbol!r} no aparece en la documentación de {ref.name!r}")
428        return {"project": ref.name, "symbol": symbol, "evidence": evidence}
McpServer._tool_list_gapsdef _tool_list_gaps(self, arguments: Mapping[str, Any]) -> dict[str, Any]
Ver prueba
src/docu/delivery/mcp_server.py#L430-L438
430    def _tool_list_gaps(self, arguments: Mapping[str, Any]) -> dict[str, Any]:
431        ref = self.resolve(arguments)
432        index = self._require_docs(ref)
433        gaps = [
434            {"document": section.document, "heading": section.heading}
435            for section in index.sections
436            if NO_EVIDENCE_MARKER in section.body
437        ]
438        return {"project": ref.name, "gaps": gaps, "total": len(gaps)}
McpServer._tool_get_architecturedef _tool_get_architecture(self, arguments: Mapping[str, Any]) -> dict[str, Any]
Ver prueba
src/docu/delivery/mcp_server.py#L440-L461
440    def _tool_get_architecture(self, arguments: Mapping[str, Any]) -> dict[str, Any]:
441        ref = self.resolve(arguments)
442        model = load_architecture(ref.root)
443        if model.is_empty:
444            raise ToolError(
445                f"no hay modelo arquitectónico en {ref.name!r}; "
446                "genera una foto con `docu drift --bootstrap`"
447            )
448        return {
449            "project": ref.name,
450            "sources": list(model.sources),
451            "components": [
452                {
453                    "name": component.name,
454                    "kind": component.kind,
455                    "provides": [route.key for route in component.provides],
456                    "depends_on": list(component.depends_on),
457                }
458                for component in model.components
459            ],
460            "routes": [route.key for route in model.routes],
461        }
McpServer._tool_get_freshnessdef _tool_get_freshness(self, arguments: Mapping[str, Any]) -> dict[str, Any]
Ver prueba
src/docu/delivery/mcp_server.py#L463-L471
463    def _tool_get_freshness(self, arguments: Mapping[str, Any]) -> dict[str, Any]:
464        ref = self.resolve(arguments)
465        manifest, states, hashes = inspect(ref.root, manifest_path=self.manifest_path)
466        return {
467            "project": manifest.project if manifest else ref.name,
468            "generated": manifest is not None,
469            "states": {level: state.value for level, state in states.items()},
470            "hashes": hashes,
471        }
McpServer._tool_verify_citationdef _tool_verify_citation(self, arguments: Mapping[str, Any]) -> dict[str, Any]
Ver prueba
src/docu/delivery/mcp_server.py#L473-L507
473    def _tool_verify_citation(self, arguments: Mapping[str, Any]) -> dict[str, Any]:
474        """Comprueba una cita contra el repositorio: existencia, rango y contenido."""
475        import re as regex
476
477        ref = self.resolve(arguments)
478        raw = str(arguments.get("citation") or "").strip()
479        match = regex.match(r"(?P<path>.+?)#L(?P<start>\d+)-L(?P<end>\d+)$", raw)
480        if match is None:
481            raise ToolError("la cita debe tener formato `ruta#L10-L20`")
482        path = ref.root / match.group("path")
483        start, end = int(match.group("start")), int(match.group("end"))
484        if not path.is_file():
485            return {
486                "citation": raw,
487                "ok": False,
488                "reason": "el archivo citado no existe",
489                "project": ref.project_name,
490            }
491        lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
492        if start < 1 or end > len(lines) or end < start:
493            return {
494                "citation": raw,
495                "ok": False,
496                "reason": f"rango fuera del archivo ({len(lines)} líneas)",
497                "project": ref.project_name,
498            }
499        span = lines[start - 1 : min(end, start + 60)]
500        return {
501            "citation": raw,
502            "ok": True,
503            "project": ref.project_name,
504            "lines": len(lines),
505            "content": "\n".join(span),
506            "truncated": end - start + 1 > len(span),
507        }
McpServer._tool_get_diagramdef _tool_get_diagram(self, arguments: Mapping[str, Any]) -> dict[str, Any]
Ver prueba
src/docu/delivery/mcp_server.py#L509-L526
509    def _tool_get_diagram(self, arguments: Mapping[str, Any]) -> dict[str, Any]:
510        ref = self.resolve(arguments)
511        directory = ref.docs_dir / "diagrams"
512        available = sorted(path.stem for path in directory.glob("*.mmd")) if directory.is_dir() else []
513        name = str(arguments.get("name") or "").strip()
514        if not name:
515            return {"project": ref.project_name, "available": available}
516        target = directory / f"{name}.mmd"
517        if not target.is_file():
518            raise ToolError(
519                f"diagrama desconocido: {name!r}. Disponibles: {', '.join(available) or 'ninguno'}"
520            )
521        return {
522            "project": ref.project_name,
523            "name": name,
524            "mermaid": target.read_text(encoding="utf-8"),
525            "available": available,
526        }
McpServer._tool_list_unsupporteddef _tool_list_unsupported(self, arguments: Mapping[str, Any]) -> dict[str, Any]
Ver prueba
src/docu/delivery/mcp_server.py#L528-L551
528    def _tool_list_unsupported(self, arguments: Mapping[str, Any]) -> dict[str, Any]:
529        """Lo que el documento declara como no cubierto: lenguajes, secciones y fuentes."""
530        from docu.generate.facts import unsupported as uncitable
531        from docu.generate.markdown import NO_EVIDENCE_MARKER
532        from docu.generate.pipeline import collect_facts, unsupported_sources
533
534        ref = self.resolve(arguments)
535        facts, _sources = collect_facts(ref.root)
536        languages = unsupported_sources(ref.root)
537        gaps: list[str] = []
538        for document in sorted(ref.docs_dir.glob("*.md")):
539            text = document.read_text(encoding="utf-8", errors="replace")
540            for block in text.split("## ")[1:]:
541                title = block.splitlines()[0].strip()
542                if NO_EVIDENCE_MARKER in block:
543                    gaps.append(f"{document.name}: {title}")
544        return {
545            "project": ref.project_name,
546            "unsupported_languages": {
547                extension: count for extension, count in languages.items()
548            },
549            "uncitable_facts": len(uncitable(facts)),
550            "sections_without_evidence": gaps,
551        }
McpServer.handledef handle(self, request: Mapping[str, Any]) -> dict[str, Any] | None
Ver prueba
src/docu/delivery/mcp_server.py#L555-L602
555    def handle(self, request: Mapping[str, Any]) -> dict[str, Any] | None:
556        """Atiende una peticion JSON-RPC. Devuelve `None` para notificaciones."""
557        identifier = request.get("id")
558        method = request.get("method")
559        params = request.get("params") or {}
560
561        if "id" not in request:
562            return None  # notificacion: `notifications/initialized` y similares
563
564        try:
565            if method == "initialize":
566                return _result(
567                    identifier,
568                    {
569                        "protocolVersion": PROTOCOL_VERSION,
570                        "capabilities": {"tools": {"listChanged": False}},
571                        "serverInfo": {"name": SERVER_NAME, "version": __version__},
572                        "instructions": (
573                            "Documentación técnica generada por docu. Todas las respuestas incluyen "
574                            "citas `archivo#L`. El servidor es de solo lectura."
575                        ),
576                    },
577                )
578            if method == "ping":
579                return _result(identifier, {})
580            if method == "tools/list":
581                return _result(identifier, {"tools": list(TOOL_DEFINITIONS)})
582            if method == "tools/call":
583                name = str(params.get("name") or "")
584                arguments = params.get("arguments") or {}
585                if name not in READ_ONLY_TOOLS:
586                    return _error(identifier, -32602, f"herramienta no soportada: {name}")
587                payload = self.call_tool(name, arguments)
588                return _result(
589                    identifier,
590                    {"content": [{"type": "text", "text": json.dumps(payload, ensure_ascii=False)}]},
591                )
592            return _error(identifier, -32601, f"método no soportado: {method}")
593        except ToolError as error:
594            return _result(
McpServer.servedef serve(self, instream: Any=..., outstream: Any=...) -> int
Ver prueba
src/docu/delivery/mcp_server.py#L604-L626
604    def serve(self, instream: Any = None, outstream: Any = None) -> int:
605        """Bucle stdio: una peticion JSON por linea, una respuesta por linea."""
606        source = instream or sys.stdin
607        sink = outstream or sys.stdout
608        for line in source:
609            text = line.strip()
610            if not text:
611                continue
612            try:
613                request = json.loads(text)
614            except json.JSONDecodeError as error:
615                sink.write(json.dumps(_error(None, -32700, f"JSON inválido: {error}"), ensure_ascii=False) + "\n")
616                sink.flush()
617                continue
618            if not isinstance(request, dict):
619                sink.write(json.dumps(_error(None, -32600, "se esperaba un objeto"), ensure_ascii=False) + "\n")
620                sink.flush()
621                continue
622            response = self.handle(request)
623            if response is not None:
624                sink.write(json.dumps(response, ensure_ascii=False) + "\n")
625                sink.flush()
626        return 0
_resultdef _result(identifier: object, result: Mapping[str, Any]) -> dict[str, Any]
Ver prueba
src/docu/delivery/mcp_server.py#L632-L633
632def _result(identifier: object, result: Mapping[str, Any]) -> dict[str, Any]:
633    return {"jsonrpc": "2.0", "id": identifier, "result": dict(result)}
_errordef _error(identifier: object, code: int, message: str) -> dict[str, Any]
Ver prueba
src/docu/delivery/mcp_server.py#L636-L637
636def _error(identifier: object, code: int, message: str) -> dict[str, Any]:
637    return {"jsonrpc": "2.0", "id": identifier, "error": {"code": code, "message": message}}
_excerptdef _excerpt(body: str, limit: int=...) -> str
Ver prueba
src/docu/delivery/mcp_server.py#L640-L642
640def _excerpt(body: str, limit: int = 1200) -> str:
641    text = body.strip()
642    return text if len(text) <= limit else text[:limit].rstrip() + "…"
discover_workspacedef discover_workspace(workspace: Path | str) -> list[ProjectRef]
Ver prueba
src/docu/delivery/mcp_server.py#L645-L666
645def discover_workspace(workspace: Path | str) -> list[ProjectRef]:
646    """Proyectos documentados dentro de una carpeta de trabajo.
647
648    Criterio: un subdirectorio es un proyecto servible si tiene documentación generada
649    (`docs/generated/*.md`) o un manifest de frescura (`.docu/manifest.json`). Nada de adivinar
650    por nombre de carpeta.
651    """
652    base = Path(workspace)
653    if not base.exists() or not base.is_dir():
654        return []
655    refs: list[ProjectRef] = []
656    for child in sorted(base.iterdir()):
657        if not child.is_dir() or child.name.startswith("."):
658            continue
659        generated = child / "docs" / "generated"
660        docs = generated if any(generated.glob("*.md")) else None
661        if docs is None and (child / ".docu" / "manifest.json").exists():
662            docs = generated
663        if docs is None:
664            continue
665        refs.append(ProjectRef(name=child.name, root=child, docs_dir=docs))
666    return refs
build_serverdef build_server(root: Path | str=..., docs_dir: Path | str | None=..., workspace: Path | str | None=..., dense: bool=..., profile_path: Path | str | None=...) -> McpServer
Ver prueba
src/docu/delivery/mcp_server.py#L669-L683
669def build_server(
670    root: Path | str = ".",
671    docs_dir: Path | str | None = None,
672    workspace: Path | str | None = None,
673    dense: bool = True,
674    profile_path: Path | str | None = None,
675) -> McpServer:
676    root_path = Path(root)
677    return McpServer(
678        root=root_path,
679        docs_dir=Path(docs_dir) if docs_dir else root_path / "docs" / "generated",
680        workspace=Path(workspace) if workspace else None,
681        dense=dense,
682        profile_path=Path(profile_path) if profile_path else None,
683    )
detectdef detect(root: Path) -> dict[str, object]
Ver prueba
src/docu/delivery/proposal.py#L25-L61
25def detect(root: Path) -> dict[str, object]:
26    """Inspecciona el proyecto para proponer un perfil: lenguajes, frameworks y rutas."""
27    root = Path(root)
28    languages: set[str] = set()
29    route_count = 0
30    facts_all = []
31    discovered = _discover(root)
32    for rel, path in discovered.items():
33        adapter = adapter_for(rel)
34        if adapter is None:
35            continue
36        languages.add(str(adapter.language))  # type: ignore[attr-defined]
37        source = _read(path)
38        facts = symbol_facts(adapter.symbols(rel, source))  # type: ignore[attr-defined]
39        facts_all.extend(facts)
40        route_count += sum(1 for fact in facts if fact.kind == "route")
41
42    facts, _sources = collect_facts(root)
43    dependencies = [fact.subject.lower() for fact in facts if fact.kind == "dependency"]
44    frameworks = sorted(
45        {name for name in FRAMEWORKS if any(name in dependency for dependency in dependencies)}
46    )
47    return {
48        "languages": sorted(languages),
49        "frameworks": frameworks,
50        "routes": route_count,
51        "files": len(discovered),
52        "facts": len(facts),
53        "ops": sum(
54            1
55            for rel in discovered
56            if is_compose_file(rel)
57            or is_docker_file(rel)
58            or is_env_file(rel)
59            or is_workflow_file(rel)
60        ),
61    }
proposedef propose(root: Path) -> Profile
Ver prueba
src/docu/delivery/proposal.py#L64-L94
64def propose(root: Path, *, project: str | None = None) -> Profile:
65    """Perfil sugerido a partir de lo detectado, listo para que un humano lo corrija."""
66    root = Path(root)
67    detection = detect(root)
68    detection["languages"]  # type: ignore[assignment]
69    frameworks: Sequence[str] = detection["frameworks"]  # type: ignore[assignment]
70    routes: int = detection["routes"]  # type: ignore[assignment]
71
72    levels = ["l1", "l4"]
73    if routes > 0:
74        levels.append("l3")
75    # El Nivel 2 sólo se propone cuando hay algo que operar: un documento de despliegue sobre un
76    # proyecto sin artefactos de despliegue sería una plantilla vacía.
77    if detection.get("ops"):
78        levels.append("l2")
79
80    # El glosario se siembra solo cuando hay evidencia de que aplica: inventar vocabulario de un
81    # dominio desconocido seria peor que no sembrarlo.
82    glossary: dict[str, tuple[str, ...]] = {}
83    if "spring-boot" in frameworks:
84        glossary = dict(DEFAULT_GLOSSARY)
85
86    # No se propone `include`: restringir la ingesta por convencion (`src/**`) deja fuera
87    # proyectos con otra estructura y produce un documento vacio que parece un fallo del agente.
88    return Profile(
89        project=project or root.name,
90        levels=tuple(level for level in LEVELS if level in levels),
91        exclude=DEFAULT_EXCLUDE,
92        glossary=glossary,
93        raw={},
94    )
Diagram.filenamedef filename(self) -> str
Ver prueba
src/docu/generate/diagrams.py#L49-L50
Anotaciones: @property
49    def filename(self) -> str:
50        return f"{self.name}.mmd"
_node_iddef _node_id(name: str) -> str
Ver prueba
src/docu/generate/diagrams.py#L53-L54
53def _node_id(name: str) -> str:
54    return re.sub(r"[^A-Za-z0-9_]", "_", name)
_labeldef _label(text: str) -> str
Ver prueba
src/docu/generate/diagrams.py#L57-L59
57def _label(text: str) -> str:
58    """Etiqueta segura para Mermaid (sin comillas ni saltos)."""
59    return text.replace('"', "'").replace("\n", " ")[:60]
resolve_importdef resolve_import(module: str, from_file: str, packages: Sequence[DetectedPackage]) -> str | None
Ver prueba
src/docu/generate/diagrams.py#L65-L84
65def resolve_import(
66    module: str,
67    from_file: str,
68    packages: Sequence[DetectedPackage],
69) -> str | None:
70    """Paquete de destino de un `import`, o `None` si apunta fuera del proyecto."""
71    if module.startswith("."):
72        base = posixpath.normpath(posixpath.join(posixpath.dirname(from_file), module))
73        for package in packages:
74            if any(member.startswith(base) for member in package.files):
75                return package.name
76        return None
77    best: str | None = None
78    for package in packages:
79        name = package.name
80        if (module == name or module.startswith(name + ".")) and (
81            best is None or len(name) > len(best)
82        ):
83            best = name
84    return best
package_dependenciesdef package_dependencies(files: Mapping[str, Path], packages: Sequence[DetectedPackage], read) -> dict[tuple[str, str], set[str]]
Ver prueba
src/docu/generate/diagrams.py#L87-L108
87def package_dependencies(
88    files: Mapping[str, Path],
89    packages: Sequence[DetectedPackage],
90    read,
91) -> dict[tuple[str, str], set[str]]:
92    """Aristas paquete → paquete, con los archivos que las justifican."""
93    owner_of = {member: package.name for package in packages for member in package.files}
94    edges: dict[tuple[str, str], set[str]] = {}
95    for rel in sorted(files):
96        adapter = adapter_for(rel)
97        owner = owner_of.get(rel)
98        if adapter is None or owner is None:
99            continue
100        try:
101            modules = adapter.imports(rel, read(files[rel]))  # type: ignore[attr-defined]
102        except (OSError, UnicodeDecodeError):
103            continue
104        for module in modules:
105            target = resolve_import(module, rel, packages)
106            if target and target != owner:
107                edges.setdefault((owner, target), set()).add(rel)
108    return edges
architecture_diagramdef architecture_diagram(packages: Sequence[DetectedPackage], edges: Mapping[tuple[str, str], set[str]]) -> Diagram | None
Ver prueba
src/docu/generate/diagrams.py#L111-L131
111def architecture_diagram(
112    packages: Sequence[DetectedPackage],
113    edges: Mapping[tuple[str, str], set[str]],
114) -> Diagram | None:
115    """Grafo de paquetes con sus dependencias."""
116    if not packages:
117        return None
118    lines = ["flowchart LR"]
119    for package in packages:
120        node = _node_id(package.name)
121        lines.append(f'    {node}["{_label(package.name)}<br/>{package.file_count} archivos"]')
122    for (source, target) in sorted(edges):
123        lines.append(f"    {_node_id(source)} --> {_node_id(target)}")
124    if not edges:
125        lines.append("    %% sin dependencias internas detectadas")
126    return Diagram(
127        name="arquitectura",
128        kind="architecture",
129        mermaid="\n".join(lines),
130        note=f"{len(packages)} paquetes · {len(edges)} dependencias derivadas de imports",
131    )
_type_signaturedef _type_signature(fact: Fact) -> str
Ver prueba
src/docu/generate/diagrams.py#L137-L138
137def _type_signature(fact: Fact) -> str:
138    return str(fact.attributes.get("signature", ""))
class_diagramdef class_diagram(package: DetectedPackage, facts: Sequence[Fact]) -> Diagram | None
Ver prueba
src/docu/generate/diagrams.py#L141-L186
141def class_diagram(package: DetectedPackage, facts: Sequence[Fact]) -> Diagram | None:
142    """Clases de un paquete con sus métodos y herencia declarada."""
143    members = set(package.files)
144    types = [fact for fact in facts if fact.kind == "type" and fact.citation.split("#")[0] in members]
145    if not types:
146        return None
147    known = {fact.subject for fact in types}
148    methods: dict[str, list[str]] = {}
149    for fact in facts:
150        if fact.kind != "method":
151            continue
152        parent = fact.subject.rsplit(".", 1)[0] if "." in fact.subject else ""
153        methods.setdefault(parent, []).append(fact.subject.rsplit(".", 1)[-1])
154
155    lines = ["classDiagram"]
156    emitted = 0
157    for fact in sorted(types, key=lambda item: item.subject)[:MAX_CLASSES_PER_DIAGRAM]:
158        name = fact.subject
159        # El estereotipo va fuera del cuerpo: dentro, Mermaid lo trata como miembro y ensucia.
160        lines.append(f"    class {name} <<{_label(str(fact.detail))}>> {{")
161        for method in methods.get(name, [])[:MAX_METHODS_PER_CLASS]:
162            lines.append(f"        {_label(method)}()")
163        lines.append("    }")
164        emitted += 1
165        signature = _type_signature(fact)
166        match = _INHERITANCE_RE.search(signature)
167        if match:
168            parents: list[str] = []
169            if match.group("py"):
170                parents += [part.strip().split("[")[0] for part in match.group("py").split(",")]
171            if match.group("ext"):
172                parents.append(match.group("ext"))
173            if match.group("impl"):
174                parents += [part.strip() for part in match.group("impl").split(",")]
175            for parent in parents:
176                parent_name = parent.rsplit(".", 1)[-1]
177                if parent_name and parent_name in known and parent_name != name:
178                    lines.append(f"    {parent_name} <|-- {name}")
179    if emitted == 0:
180        return None
api_flow_diagramdef api_flow_diagram(facts: Sequence[Fact]) -> Diagram | None
Ver prueba
src/docu/generate/diagrams.py#L192-L218
192def api_flow_diagram(facts: Sequence[Fact]) -> Diagram | None:
193    """Ruta → handler → dependencias declaradas del archivo del handler."""
194    routes = [fact for fact in facts if fact.kind == "route"][:MAX_API_ROUTES]
195    if not routes:
196        return None
197    lines = ["flowchart LR", '    cliente(["Cliente"])']
198    handler_ids: dict[str, str] = {}
199    emitted: set[str] = set()
200    for index, route in enumerate(routes):
201        route_id = f"r{index}"
202        verb = route.attributes.get("verb", "ANY")
203        path = route.attributes.get("path", "/")
204        lines.append(f'    {route_id}["{_label(f"{verb} {path}")}"]')
205        lines.append(f"    cliente --> {route_id}")
206        handler = str(route.attributes.get("handler", route.detail)) or "handler"
207        parent = handler.rsplit(".", 1)[0] if "." in handler else handler
208        handler_id = handler_ids.setdefault(parent, f"h{len(handler_ids)}")
209        if parent not in emitted:
210            emitted.add(parent)
211            lines.append(f'    {handler_id}["{_label(parent)}"]')
212        lines.append(f"    {route_id} --> {handler_id}")
213    return Diagram(
214        name="api-flujo",
215        kind="api",
216        mermaid="\n".join(lines),
217        note=f"{len(routes)} rutas",
218    )
_entity_typedef _entity_type(text: str) -> tuple[str, bool]
Ver prueba
src/docu/generate/diagrams.py#L221-L232
221def _entity_type(text: str) -> tuple[str, bool]:
222    """Tipo declarado y si es una colección: `List<Cliente>` → (`Cliente`, True)."""
223    compact = text.strip().rstrip(";")
224    plural = False
225    for wrapper in ("List", "Set", "Collection", "Iterable", "Array", "[]", "Optional"):
226        if wrapper in compact:
227            plural = wrapper not in ("Optional",)
228            break
229    inner = re.sub(r"^(?:List|Set|Collection|Iterable|Optional|Array)\s*<", "", compact)
230    inner = inner.rstrip(">").rstrip("[]").replace("[]", "")
231    name = inner.rsplit(".", 1)[-1].strip()
232    return name, plural
erd_diagramdef erd_diagram(facts: Sequence[Fact]) -> Diagram | None
Ver prueba
src/docu/generate/diagrams.py#L235-L292
235def erd_diagram(facts: Sequence[Fact]) -> Diagram | None:
236    """ERD desde los tipos declarados.
237
238    Las entidades son los tipos con campos; las relaciones salen del **tipo del campo** cuando ese
239    tipo es otra entidad documentada. No se inventan claves foráneas ni cardinalidades que el código
240    no declare: una colección se dibuja como «muchos», un tipo simple como «uno».
241    """
242    fields_by_entity: dict[str, list[Fact]] = {}
243    for fact in facts:
244        if fact.kind != "field":
245            continue
246        owner = str(fact.attributes.get("owner", fact.subject.rsplit(".", 1)[0]))
247        fields_by_entity.setdefault(owner, []).append(fact)
248    if not fields_by_entity:
249        return None
250
251    entities = set(fields_by_entity)
252    degree: dict[str, int] = {}
253    for entity in entities:
254        for fact in fields_by_entity[entity]:
255            target, _plural = _entity_type(fact.detail)
256            if target in entities and target != entity:
257                degree[entity] = degree.get(entity, 0) + 1
258                degree[target] = degree.get(target, 0) + 1
259    # Recorte por relación y luego por campos: un `.mmd` de 25 KB con 94 entidades no se renderiza
260    # bien en la mayoría de visores y esconde el modelo detrás de las interfaces de props.
261    ranked = sorted(entities, key=lambda name: (-degree.get(name, 0), -len(fields_by_entity[name]), name))
262    chosen = ranked[:MAX_ERD_ENTITIES]
263    omitted = len(ranked) - len(chosen)
264
265    lines = ["erDiagram"]
266    if omitted:
267        lines.append(f"    %% recorte: {len(chosen)} de {len(ranked)} entidades (las de más relaciones)")
268    relations: list[str] = []
269    for entity in sorted(chosen):
270        lines.append(f"    {_node_id(entity)} {{")
271        for fact in fields_by_entity[entity][:MAX_FIELDS_PER_ENTITY]:
272            declared = fact.detail if fact.detail != "sin tipo declarado" else "sinTipo"
273            token = _node_id(declared.split("|")[0].strip()[:24]).strip("_") or "tipo"
274            lines.append(f"        {token} {fact.subject.rsplit('.', 1)[-1]}")
build_alldef build_all(files: Mapping[str, Path], packages: Sequence[DetectedPackage], facts: Sequence[Fact], read) -> tuple[Diagram, ...]
Ver prueba
src/docu/generate/diagrams.py#L298-L328
298def build_all(
299    files: Mapping[str, Path],
300    packages: Sequence[DetectedPackage],
301    facts: Sequence[Fact],
302    read,
303) -> tuple[Diagram, ...]:
304    """Todos los diagramas posibles, en orden estable."""
305    diagrams: list[Diagram] = []
306    edges = package_dependencies(files, packages, read)
307    architecture = architecture_diagram(packages, edges)
308    if architecture is not None:
309        diagrams.append(architecture)
310
311    largest = sorted(packages, key=lambda item: item.file_count, reverse=True)
312    class_count = 0
313    for package in largest:
314        if class_count >= MAX_CLASS_DIAGRAMS:
315            break
316        diagram = class_diagram(package, facts)
317        if diagram is not None:
318            diagrams.append(diagram)
319            class_count += 1
320
321    model = erd_diagram(facts)
322    if model is not None:
323        diagrams.append(model)
324
325    flow = api_flow_diagram(facts)
326    if flow is not None:
327        diagrams.append(flow)
328    return tuple(diagrams)
write_diagramsdef write_diagrams(diagrams: Sequence[Diagram], directory: Path) -> list[Path]
Ver prueba
src/docu/generate/diagrams.py#L331-L345
331def write_diagrams(diagrams: Sequence[Diagram], directory: Path) -> list[Path]:
332    """Escribe los `.mmd` y borra los obsoletos: un diagrama viejo miente igual que una tabla vieja."""
333    written: list[Path] = []
334    if not diagrams:
335        return written
336    directory.mkdir(parents=True, exist_ok=True)
337    current = {diagram.filename for diagram in diagrams}
338    for stale in sorted(directory.glob("*.mmd")):
339        if stale.name not in current:
340            stale.unlink()
341    for diagram in diagrams:
342        target = directory / diagram.filename
343        target.write_text(diagram.mermaid + "\n", encoding="utf-8")
344        written.append(target)
345    return written
DocSection.citationdef citation(self) -> str
Ver prueba
src/docu/generate/docs_evidence.py#L59-L60
Anotaciones: @property
59    def citation(self) -> str:
60        return f"{self.path}#L{self.line_start}-L{self.line_end}"
DocSection.matchesdef matches(self, hints: Sequence[str]) -> bool
Ver prueba
src/docu/generate/docs_evidence.py#L62-L64
62    def matches(self, hints: Sequence[str]) -> bool:
63        haystack = f"{self.title} {self.body[:200]}".lower()
64        return any(hint in haystack for hint in hints)
DocSection.to_factdef to_fact(self) -> Fact
Ver prueba
src/docu/generate/docs_evidence.py#L66-L73
66    def to_fact(self) -> Fact:
67        return Fact(
68            kind="doc_section",
69            subject=f"{self.path} › {self.title}",
70            detail=self.body[:MAX_TEXT] or "—",
71            citation=self.citation,
72            attributes={"source": self.path, "title": self.title},
73        )
parse_sectionsdef parse_sections(path: str, source: str) -> list[DocSection]
Ver prueba
src/docu/generate/docs_evidence.py#L76-L97
76def parse_sections(path: str, source: str) -> list[DocSection]:
77    """Secciones de nivel 1–3 con su primer párrafo como cuerpo."""
78    headings = list(_HEADING_RE.finditer(source))
79    sections: list[DocSection] = []
80    for index, match in enumerate(headings):
81        level = len(match.group("hashes"))
82        if level > 3:
83            continue
84        title = match.group("title").strip().strip("#").strip()
85        if not title:
86            continue
87        start = match.end()
88        end = headings[index + 1].start() if index + 1 < len(headings) else len(source)
89        body = _first_paragraph(source[start:end])
90        total_lines = len(source.splitlines())
91        line_start = source.count("\n", 0, match.start()) + 1
92        # Una sección que llega al final del archivo no puede citar una línea que no existe.
93        line_end = min(source.count("\n", 0, end) + 1, total_lines)
94        sections.append(DocSection(path, title, body, line_start, line_end))
95        if len(sections) >= MAX_SECTIONS:
96            break
97    return sections
_first_paragraphdef _first_paragraph(text: str) -> str
Ver prueba
src/docu/generate/docs_evidence.py#L100-L111
100def _first_paragraph(text: str) -> str:
101    """Primer bloque con contenido real: ni tablas ni imágenes ni insignias."""
102    for block in re.split(r"\n\s*\n", text):
103        cleaned = " ".join(
104            line.strip() for line in block.splitlines() if not line.strip().startswith(("|", "![", "[![", "```", "<"))
105        )
106        cleaned = re.sub(r"!\[[^\]]*\]\([^)]*\)", "", cleaned).strip()
107        cleaned = re.sub(r"\[([^\]]+)\]\([^)]*\)", r"\1", cleaned).strip()
108        # Un párrafo corto también es evidencia: el umbral alto descartaba introducciones reales.
109        if len(cleaned) >= 20 and len(cleaned.split()) >= 3:
110            return cleaned[:MAX_TEXT]
111    return ""
discoverdef discover(root: Path | str, files: Mapping[str, Path] | None=...) -> list[DocSection]
Ver prueba
src/docu/generate/docs_evidence.py#L114-L141
114def discover(root: Path | str, files: Mapping[str, Path] | None = None) -> list[DocSection]:
115    """Secciones de la documentación existente del proyecto, sin entrar en `docs/generated`."""
116    root_path = Path(root)
117    candidates: list[Path] = []
118    for name in DOC_FILES:
119        candidate = root_path / name
120        if candidate.is_file():
121            candidates.append(candidate)
122    for directory in DOC_DIRS:
123        base = root_path / directory
124        if not base.is_dir():
125            continue
126        for path in sorted(base.rglob("*.md")):
127            if "generated" in path.parts or "node_modules" in path.parts:
128                continue
129            candidates.append(path)
130
131    sections: list[DocSection] = []
132    for path in dict.fromkeys(candidates):
133        try:
134            source = path.read_text(encoding="utf-8", errors="replace")
135        except OSError:
136            continue
137        rel = path.relative_to(root_path).as_posix()
138        sections.extend(parse_sections(rel, source))
139        if len(sections) >= MAX_SECTIONS:
140            break
141    return sections[:MAX_SECTIONS]
finddef find(sections: Sequence[DocSection], hints: Sequence[str], limit: int=...) -> list[DocSection]
Ver prueba
src/docu/generate/docs_evidence.py#L144-L160
144def find(sections: Sequence[DocSection], hints: Sequence[str], limit: int = 3) -> list[DocSection]:
145    """Secciones que responden a un hueco concreto, con el título por delante del cuerpo.
146
147    Prioriza las secciones cuyo **título** coincide («Prerrequisitos» gana a un párrafo de cobertura
148    que menciona `npm run`): sin esto, el onboarding citaba el reporte de cobertura como si fuera la
149    puesta en marcha.
150    """
151    scored: list[tuple[int, DocSection]] = []
152    for position, section in enumerate(sections):
153        title = section.title.lower()
154        if any(word in title for word in NOT_SETUP):
155            continue  # un reporte de cobertura no es la puesta en marcha
156        # Coincidencia por **título**: buscar en el cuerpo traía secciones que sólo mencionaban el
157        # comando de pasada (un apartado de documentación que hablaba de «modos de ejecución»).
158        if any(hint in title for hint in hints):
159            scored.append((position, section))
160    return [section for _position, section in scored[:limit]]
Fact.verifieddef verified(self) -> bool
Ver prueba
src/docu/generate/facts.py#L39-L40
Anotaciones: @property
39    def verified(self) -> bool:
40        return bool(self.citation)
Fact.locationdef location(self) -> str
Ver prueba
src/docu/generate/facts.py#L43-L44
Anotaciones: @property
43    def location(self) -> str:
44        return self.citation
_line_ofdef _line_of(text: str, offset: int) -> int
Ver prueba
src/docu/generate/facts.py#L47-L48
47def _line_of(text: str, offset: int) -> int:
48    return text[:offset].count("\n") + 1
_tag_valuedef _tag_value(body: str, tag: str) -> str | None
Ver prueba
src/docu/generate/facts.py#L51-L53
51def _tag_value(body: str, tag: str) -> str | None:
52    match = re.search(_POM_TAG.format(tag=tag), body, re.DOTALL)
53    return match.group("value").strip() if match else None
symbol_factsdef symbol_facts(symbols: Sequence[Symbol]) -> list[Fact]
Ver prueba
src/docu/generate/facts.py#L59-L127
59def symbol_facts(symbols: Sequence[Symbol]) -> list[Fact]:
60    """Tipos, funciones, metodos y rutas HTTP con su ubicacion exacta.
61
62    Vale para cualquier lenguaje: los adaptadores solo tienen que devolver `Symbol`s. Una
63    funcion de modulo (Python, TS) es tan documentable como un metodo de clase.
64    """
65    facts: list[Fact] = []
66    for symbol in symbols:
67        citation = f"{symbol.path}#L{symbol.line_start}-L{symbol.line_end}"
68        if symbol.kind in (SymbolKind.CLASS, SymbolKind.INTERFACE, SymbolKind.ENUM):
69            facts.append(
70                Fact(
71                    kind="type",
72                    subject=symbol.name,
73                    detail=symbol.kind.value,
74                    citation=citation,
75                    attributes={
76                        "annotations": " ".join(symbol.annotations) or "—",
77                        "signature": symbol.signature or "",
78                    },
79                )
80            )
81            for child in symbol.children:
82                child_citation = f"{child.path}#L{child.line_start}-L{child.line_end}"
83                if child.kind is SymbolKind.FIELD:
84                    facts.append(
85                        Fact(
86                            kind="field",
87                            subject=child.qualname,
88                            detail=child.signature or "sin tipo declarado",
89                            citation=child_citation,
90                            attributes={
91                                "owner": symbol.name,
92                                "annotations": " ".join(child.annotations) or "—",
93                            },
94                        )
95                    )
96                    continue
97                facts.append(
98                    Fact(
yaml_factsdef yaml_facts(path: str, source: str) -> list[Fact]
Ver prueba
src/docu/generate/facts.py#L137-L166
137def yaml_facts(path: str, source: str) -> list[Fact]:
138    """Claves aplanadas (`a.b.c`) con su linea. Parser de subconjunto, no un YAML completo."""
139    facts: list[Fact] = []
140    stack: list[tuple[int, str]] = []
141    for index, raw in enumerate(source.splitlines(), start=1):
142        if not raw.strip() or raw.lstrip().startswith("#"):
143            continue
144        match = _YAML_LINE.match(raw)
145        if not match:
146            continue
147        indent = len(match.group("indent").expandtabs(2))
148        key = match.group("key")
149        value = _COMMENT.sub("", match.group("value")).strip().strip('"').strip("'")
150        while stack and stack[-1][0] >= indent:
151            stack.pop()
152        prefix = ".".join([parent for _level, parent in stack])
153        dotted = f"{prefix}.{key}" if prefix else key
154        if value:
155            facts.append(
156                Fact(
157                    kind="config_key",
158                    subject=dotted,
159                    detail=value,
160                    citation=f"{path}#L{index}-L{index}",
161                    attributes={"key": dotted, "value": value},
162                )
163            )
164        else:
165            stack.append((indent, key))
166    return facts
pom_factsdef pom_facts(path: str, source: str) -> list[Fact]
Ver prueba
src/docu/generate/facts.py#L172-L251
172def pom_facts(path: str, source: str) -> list[Fact]:
173    """Modules, propiedades del parent y dependencias declaradas, con linea exacta."""
174    facts: list[Fact] = []
175    for match in _POM_MODULE.finditer(source):
176        name = match.group("name").strip()
177        line = _line_of(source, match.start())
178        facts.append(
179            Fact(
180                kind="module",
181                subject=name,
182                detail="módulo de build",
183                citation=f"{path}#L{line}-L{line}",
184                attributes={"module": name},
185            )
186        )
187
188    for tag in ("java.version", "spring-security.version", "jjwt.version"):
189        for match in re.finditer(_POM_TAG.format(tag=re.escape(tag)), source, re.DOTALL):
190            line = _line_of(source, match.start())
191            facts.append(
192                Fact(
193                    kind="property",
194                    subject=tag,
195                    detail=match.group("value").strip(),
196                    citation=f"{path}#L{line}-L{line}",
197                    attributes={"property": tag, "value": match.group("value").strip()},
198                )
199            )
200
201    for match in _POM_DEPENDENCY.finditer(source):
202        body = match.group("body")
203        group = _tag_value(body, "groupId")
204        artifact = _tag_value(body, "artifactId")
205        if not group or not artifact:
206            continue
207        version = _tag_value(body, "version") or "(gestionada por el parent)"
208        scope = _tag_value(body, "scope") or "compile"
209        line = _line_of(source, match.start() + body.find("<artifactId>"))
210        facts.append(
211            Fact(
_line_withdef _line_with(text: str, needle: str) -> int
Ver prueba
src/docu/generate/facts.py#L257-L260
257def _line_with(text: str, needle: str) -> int:
258    """Linea de la primera aparicion del texto, o 1 si no aparece (nunca miente la cita)."""
259    index = text.find(needle)
260    return text[: index].count("\n") + 1 if index >= 0 else 1
_line_with_afterdef _line_with_after(text: str, needle: str, start: int) -> int
Ver prueba
src/docu/generate/facts.py#L263-L268
263def _line_with_after(text: str, needle: str, start: int) -> int:
264    """Linea de la primera aparicion **a partir de** `start`, con retroceso a la primera global."""
265    index = text.find(needle, max(0, start))
266    if index < 0:
267        index = text.find(needle)
268    return text[: index].count("\n") + 1 if index >= 0 else 1
requirements_factsdef requirements_facts(path: str, source: str) -> list[Fact]
Ver prueba
src/docu/generate/facts.py#L271-L288
271def requirements_facts(path: str, source: str) -> list[Fact]:
272    """`requirements.txt`: una dependencia por linea, con su version si la fija."""
273    facts: list[Fact] = []
274    for index, raw in enumerate(source.splitlines(), start=1):
275        line = raw.strip()
276        if not line or line.startswith("#"):
277            continue
278        name, _, version = line.partition("==")
279        facts.append(
280            Fact(
281                kind="dependency",
282                subject=name.strip(),
283                detail=version.strip() or "(sin versión fija)",
284                citation=f"{path}#L{index}-L{index}",
285                attributes={"scope": "runtime", "version": version.strip()},
286            )
287        )
288    return facts
package_json_factsdef package_json_facts(path: str, source: str) -> list[Fact]
Ver prueba
src/docu/generate/facts.py#L291-L316
291def package_json_facts(path: str, source: str) -> list[Fact]:
292    """`package.json`: dependencias y devDependencies con la linea del nombre."""
293    import json
294
295    try:
296        payload = json.loads(source)
297    except json.JSONDecodeError:
298        return []
299    facts: list[Fact] = []
300    for scope, key in (("runtime", "dependencies"), ("dev", "devDependencies")):
301        block = payload.get(key) or {}
302        # `vite` puede estar en dependencies y en devDependencies: buscar desde la seccion evita
303        # citar siempre la primera aparicion y crear duplicados falsos.
304        section_start = source.find(f'"{key}"')
305        for name, version in block.items():
306            line = _line_with_after(source, f'"{name}"', section_start)
307            facts.append(
308                Fact(
309                    kind="dependency",
310                    subject=name,
311                    detail=str(version),
312                    citation=f"{path}#L{line}-L{line}",
313                    attributes={"scope": scope, "version": str(version)},
314                )
315            )
316    return facts
pyproject_scripts_factsdef pyproject_scripts_facts(path: str, source: str) -> list[Fact]
Ver prueba
src/docu/generate/facts.py#L319-L345
319def pyproject_scripts_facts(path: str, source: str) -> list[Fact]:
320    """Comandos instalables declarados en `[project.scripts]` de `pyproject.toml`.
321
322    Sin esto, un proyecto Python sin `package.json` aparece con «procedimientos: sin evidencia»
323    aunque declare su CLI punto por punto.
324    """
325    facts: list[Fact] = []
326    inside = False
327    for line_number, line in enumerate(source.splitlines(), start=1):
328        stripped = line.strip()
329        if stripped.startswith("["):
330            inside = stripped.startswith("[project.scripts]")
331            continue
332        if not inside or not stripped or stripped.startswith("#"):
333            continue
334        match = re.match(r'^([A-Za-z0-9_.-]+)\s*=\s*"([^"]+)"', stripped)
335        if match is None:
336            continue
337        facts.append(
338            Fact(
339                kind="command",
340                subject=match.group(1),
341                detail=f"python -m {match.group(2).split(':')[0]} · {match.group(2)}",
342                citation=f"{path}#L{line_number}-L{line_number}",
343            )
344        )
345    return facts
pyproject_factsdef pyproject_facts(path: str, source: str) -> list[Fact]
Ver prueba
src/docu/generate/facts.py#L348-L399
348def pyproject_facts(path: str, source: str) -> list[Fact]:
349    """`pyproject.toml`: dependencias de `[project]` y de sus extras, y la versión de Python exigida.
350
351    Leer solo `dependencies` deja fuera a la mitad del ecosistema Python: `optional-dependencies`
352    es donde vive casi todo (framework web, linters, base de datos). Omitirlo produce manuales que
353    afirman «este proyecto no tiene dependencias» sobre un proyecto que sí las tiene.
354    """
355    import tomllib
356
357    try:
358        payload = tomllib.loads(source)
359    except tomllib.TOMLDecodeError:
360        return []
361    project = payload.get("project") or {}
362    facts: list[Fact] = []
363    requires = project.get("requires-python")
364    if requires:
365        line = _line_with(source, "requires-python")
366        facts.append(
367            Fact(
368                kind="property",
369                subject="requires-python",
370                detail=str(requires),
371                citation=f"{path}#L{line}-L{line}",
372                attributes={"property": "requires-python", "value": str(requires)},
373            )
374        )
375
376    groups: list[tuple[str, object]] = [("runtime", project.get("dependencies") or [])]
377    extras = project.get("optional-dependencies") or {}
378    if isinstance(extras, dict):
379        groups.extend((str(name), requirements) for name, requirements in extras.items())
380
381    for scope, requirements in groups:
382        if not isinstance(requirements, list):
383            continue
384        for requirement in requirements:
385            name = re.split(r"[<>=!~\[ ]", str(requirement), maxsplit=1)[0].strip()
386            if not name:
387                continue
package_factsdef package_facts(packages: Sequence[object]) -> list[Fact]
Ver prueba
src/docu/generate/facts.py#L402-L420
402def package_facts(packages: Sequence[object]) -> list[Fact]:
403    """Unidades arquitectonicas detectadas: paquetes Python, paquetes Java, barriles TypeScript."""
404    facts: list[Fact] = []
405    for package in packages:
406        name = str(getattr(package, "name", ""))
407        if not name:
408            continue
409        language = str(getattr(package, "language", "desconocido"))
410        files = int(getattr(package, "file_count", 0))
411        facts.append(
412            Fact(
413                kind="package",
414                subject=name,
415                detail=f"{files} archivos · {language}",
416                citation=str(getattr(package, "citation", "")),
417                attributes={"language": language, "files": str(files)},
418            )
419        )
420    return facts
unsupporteddef unsupported(facts: Sequence[Fact]) -> list[Fact]
Ver prueba
src/docu/generate/facts.py#L426-L428
426def unsupported(facts: Sequence[Fact]) -> list[Fact]:
427    """Hechos que no se pueden sostener: la compuerta dura del producto."""
428    return [fact for fact in facts if not fact.verified]
_citedef _cite(citation: str) -> str
Ver prueba
src/docu/generate/markdown.py#L32-L33
32def _cite(citation: str) -> str:
33    return f"`{citation}`"
_tabledef _table(headers: Sequence[str], rows: Sequence[Sequence[str]]) -> str
Ver prueba
src/docu/generate/markdown.py#L36-L42
36def _table(headers: Sequence[str], rows: Sequence[Sequence[str]]) -> str:
37    if not rows:
38        return NO_EVIDENCE
39    head = "| " + " | ".join(headers) + " |"
40    rule = "|" + "|".join("---" for _ in headers) + "|"
41    body = ["| " + " | ".join(row) + " |" for row in rows]
42    return "\n".join([head, rule, *body])
_by_kinddef _by_kind(facts: Sequence[Fact], kind: str) -> list[Fact]
Ver prueba
src/docu/generate/markdown.py#L45-L46
45def _by_kind(facts: Sequence[Fact], kind: str) -> list[Fact]:
46    return [fact for fact in facts if fact.kind == kind]
_dedupedef _dedupe(facts: Sequence[Fact]) -> list[Fact]
Ver prueba
src/docu/generate/markdown.py#L49-L59
49def _dedupe(facts: Sequence[Fact]) -> list[Fact]:
50    """Quita afirmaciones repetidas conservando la primera cita (los parents se repiten por modulo)."""
51    seen: set[tuple[str, str, str]] = set()
52    out: list[Fact] = []
53    for fact in facts:
54        key = (fact.kind, fact.subject, fact.detail)
55        if key in seen:
56            continue
57        seen.add(key)
58        out.append(fact)
59    return out
_doc_sectionsdef _doc_sections(facts: Sequence[Fact]) -> list[DocSection]
Ver prueba
src/docu/generate/markdown.py#L62-L76
62def _doc_sections(facts: Sequence[Fact]) -> list[DocSection]:
63    """Secciones de documentación existente, reconstruidas desde los hechos citados."""
64    sections: list[DocSection] = []
65    for fact in _by_kind(facts, "doc_section"):
66        path, _, span = fact.citation.partition("#L")
67        start_text, _, end_text = span.partition("-L")
68        try:
69            start = int(start_text)
70            end = int(end_text or start_text)
71        except ValueError:
72            continue
73        sections.append(
74            DocSection(path, fact.attributes.get("title", ""), fact.detail, start, end)
75        )
76    return sections
_doc_hint_linesdef _doc_hint_lines(facts: Sequence[Fact], hints: Sequence[str]) -> list[str]
Ver prueba
src/docu/generate/markdown.py#L79-L95
79def _doc_hint_lines(facts: Sequence[Fact], hints: Sequence[str]) -> list[str]:
80    """Párrafos del repositorio que ya responden a esta sección.
81
82    Se citan como **documentación existente**, no como afirmación del generador: el lector sabe que
83    esa prosa la escribió el equipo y puede ir a la línea exacta.
84    """
85    matched = find_docs(_doc_sections(facts), hints)
86    if not matched:
87        return []
88    lines = [
89        "> El repositorio **ya documenta** esto. Se cita para no duplicarlo ni contradecirlo.",
90        "",
91    ]
92    for section in matched:
93        body = f" — {section.body[:300]}" if section.body else ""
94        lines += [f"**{section.title}**{body} [`{section.citation}`]", ""]
95    return lines
_countsdef _counts(facts: Sequence[Fact]) -> dict[str, int]
Ver prueba
src/docu/generate/markdown.py#L98-L102
98def _counts(facts: Sequence[Fact]) -> dict[str, int]:
99    counts: dict[str, int] = {}
100    for fact in facts:
101        counts[fact.kind] = counts.get(fact.kind, 0) + 1
102    return counts
_headerdef _header(project: str, title: str, meta: Mapping[str, str], facts: Sequence[Fact], plain: bool=...) -> list[str]
Ver prueba
src/docu/generate/markdown.py#L105-L136
105def _header(
106    project: str,
107    title: str,
108    meta: Mapping[str, str],
109    facts: Sequence[Fact],
110    plain: bool = False,
111) -> list[str]:
112    """Cabecera comun. En Nivel 3 se omite la huella técnica: no aporta a esa audiencia."""
113    if plain:
114        return [
115            f"# {project} — {title}",
116            "",
117            (f"Generado por `docu {meta.get('version', '0.1.0')}` a partir de las acciones y la "
118            "configuración vigentes."),
119            "",
120            "> Cada dato de esta guía indica de dónde sale. Lo que no está declarado no se inventa.",
121            "",
122        ]
123    _counts(facts)
124    stamp = f" el {meta['generated_at']}" if meta.get("generated_at") else ""
125    return [
126        f"# {project} — {title}",
127        "",
128        (f"Generado por `docu {meta.get('version', '0.1.0')}`{stamp} · "
129        f"fuente `{meta.get('digest', '—')}` · "
130        f"archivos analizados: {meta.get('sources', '0')} · "
131        f"afirmaciones: {len(facts)} · sin cita: {meta.get('unsupported', '0')}"),
132        "",
133        ("> Documento **extractivo**: cada fila procede de un archivo y un rango de líneas del "
134        "repositorio. No hay texto generado sin evidencia."),
135        "",
136    ]
_diagrams_blockdef _diagrams_block(diagrams: Sequence[object], facts: Sequence[Fact]) -> list[str]
Ver prueba
src/docu/generate/markdown.py#L139-L164
139def _diagrams_block(diagrams: Sequence[object], facts: Sequence[Fact]) -> list[str]:
140    """Bloques Mermaid embebidos. Sin diagramas, se declara el hueco con su motivo."""
141    blocks: list[str] = []
142    for diagram in diagrams:
143        name = getattr(diagram, "name", "")
144        kind = getattr(diagram, "kind", "")
145        mermaid = getattr(diagram, "mermaid", "")
146        note = getattr(diagram, "note", "")
147        if not mermaid:
148            continue
149        title = {
150            "architecture": "Dependencias entre paquetes",
151            "classes": "Clases del paquete",
152            "api": "Flujo de la API",
153        }.get(str(kind), str(name))
154        blocks += [f"### {title}" + (f" · {note}" if note else ""), "", "```mermaid", mermaid, "```", ""]
155    if not blocks:
156        blocks += [
157            NO_EVIDENCE,
158            "",
159            ("> No se generan diagramas de secuencia: el grafo de llamadas no resuelve despacho "
160            "dinámico (inyección de dependencias, interfaces), y un diagrama de secuencia inventado "
161            "sería peor que su ausencia."),
162            "",
163        ]
164    return blocks
render_l1def render_l1(project: str, facts: Sequence[Fact], sources: Mapping[str, str], meta: Mapping[str, str], diagrams: Sequence[object]=...) -> str
Ver prueba
src/docu/generate/markdown.py#L170-L476
170def render_l1(
171    project: str,
172    facts: Sequence[Fact],
173    sources: Mapping[str, str],
174    meta: Mapping[str, str],
175    diagrams: Sequence[object] = (),
176) -> str:
177    """Manual tecnico interno: arquitectura, diagramas, API, configuracion y simbolos."""
178    lines = _header(project, "Manual técnico (Nivel 1)", meta, facts)
179    counts = _counts(facts)
180
181    lines += ["## 1. Introducción", ""]
182    intro = str(meta.get("intro") or "").strip()
183    if intro:
184        lines += [
185            ("> Introducción compuesta con hechos citados: cada frase sale de un conteo o de la propia "
186            "documentación del proyecto. No es prosa libre."),
187            "",
188            intro,
189            "",
190        ]
191    else:
192        lines += [NO_EVIDENCE, ""]
193
194    prose = str(meta.get("prose") or "").strip()
195    if prose:
196        lines += [prose, ""]
197        details = [f"redactor: `{meta.get('prose_reviewer') or 'agente'}`"]
198        if meta.get("prose_judge"):
199            details.append(f"juez: `{meta['prose_judge']}` ({meta.get('prose_score', '—')}/5)")
200        lines += [f"_({'; '.join(details)} · validada por docu: ninguna cifra nueva)_", ""]
201    elif meta.get("prose_error"):
202        lines += [
203            (f"> La prosa delegada **no se incluyó**: {meta['prose_error']}. "
204            "Se regenera con `docu prose --apply`."),
205            "",
206        ]
207
208    lines += ["## 2. Resumen", ""]
209    lines += [
render_l4def render_l4(project: str, facts: Sequence[Fact], sources: Mapping[str, str], meta: Mapping[str, str], diagrams: Sequence[object]=...) -> str
Ver prueba
src/docu/generate/markdown.py#L482-L573
482def render_l4(
483    project: str,
484    facts: Sequence[Fact],
485    sources: Mapping[str, str],
486    meta: Mapping[str, str],
487    diagrams: Sequence[object] = (),
488) -> str:
489    """README y onboarding: lo minimo para entender y arrancar, sin jerga innecesaria."""
490    lines = _header(project, "README de onboarding (Nivel 4)", meta, facts)
491    counts = _counts(facts)
492
493    lines += ["## Qué es", ""]
494    lines += [
495        (f"Proyecto **{project}** con {counts.get('module', 0)} módulos, "
496        f"{counts.get('package', 0)} paquetes, "
497        f"{counts.get('type', 0)} tipos y {counts.get('route', 0)} rutas HTTP documentadas."),
498        "",
499    ]
500    prose = str(meta.get("prose") or "").strip()
501    if prose:
502        # El onboarding es el único lugar donde una introducción hace falta: la prosa delegada va
503        # también aquí, con su procedencia.
504        lines += [prose, ""]
505        details = [f"redactor: `{meta.get('prose_reviewer') or 'agente'}`"]
506        if meta.get("prose_judge"):
507            details.append(f"juez: `{meta['prose_judge']}` ({meta.get('prose_score', '—')}/5)")
508        lines += [f"_({'; '.join(details)} · validada por docu: ninguna cifra nueva)_", ""]
509    lines += [
510        _table(
511            ["Módulo / paquete", "Cita"],
512            [
513                [f"`{fact.subject}`", _cite(fact.citation)]
514                for fact in _by_kind(facts, "module") + _by_kind(facts, "package")
515            ],
516        ),
517        "",
518    ]
519
520    lines += ["## Prerrequisitos", ""]
521    # Solo la plataforma: propiedades declaradas y el parent del POM raiz. Los parents internos
render_l2def render_l2(project: str, facts: Sequence[Fact], sources: Mapping[str, str], meta: Mapping[str, str], diagrams: Sequence[object]=...) -> str
Ver prueba
src/docu/generate/markdown.py#L611-L715
611def render_l2(
612    project: str,
613    facts: Sequence[Fact],
614    sources: Mapping[str, str],
615    meta: Mapping[str, str],
616    diagrams: Sequence[object] = (),
617) -> str:
618    """Operación y despliegue: entorno, puertos, artefactos, procedimientos y CI.
619
620    Nunca incluye valores de variables de entorno: sólo nombres. Un documento que copia una clave
621    es un incidente, no documentación.
622    """
623    lines = _header(project, "Operación y despliegue (Nivel 2)", meta, facts)
624    counts = _counts(facts)
625
626    lines += ["## 1. Entorno requerido", ""]
627    env_rows = [
628        [f"`{fact.subject}`", fact.detail, _cite(fact.citation)] for fact in _by_kind(facts, "env_var")
629    ]
630    if env_rows:
631        lines += [
632            ("> Sólo se documentan los **nombres** de las variables. Los valores de los archivos de "
633            "ejemplo no se copian, y un `.env` real nunca se lee."),
634            "",
635            _table(["Variable", "Archivo de ejemplo", "Cita"], env_rows),
636            "",
637        ]
638    else:
639        lines += [NO_EVIDENCE, ""]
640
641    lines += ["## 2. Puertos y servicios", ""]
642    port_rows = [
643        [f"`{fact.subject}`", fact.detail, _cite(fact.citation)] for fact in _by_kind(facts, "port")
644    ]
645    service_rows = [
646        [f"`{fact.subject}`", fact.detail, _cite(fact.citation)]
647        for fact in _by_kind(facts, "service")
648    ]
649    if service_rows:
650        lines += [_table(["Servicio", "Origen", "Cita"], service_rows), ""]
render_l3def render_l3(project: str, facts: Sequence[Fact], sources: Mapping[str, str], meta: Mapping[str, str], diagrams: Sequence[object]=..., docs_sections: Sequence[DocSection]=...) -> str
Ver prueba
src/docu/generate/markdown.py#L718-L769
718def render_l3(
719    project: str,
720    facts: Sequence[Fact],
721    sources: Mapping[str, str],
722    meta: Mapping[str, str],
723    diagrams: Sequence[object] = (),
724    docs_sections: Sequence[DocSection] = (),
725) -> str:
726    """Guia de uso para personas sin perfil tecnico: acciones, ajustes y avisos."""
727    lines = _header(project, "Guía de uso (Nivel 3)", meta, facts, plain=True)
728
729    lines += ["## Qué puedes hacer", ""]
730    rows = []
731    for fact in _by_kind(facts, "route"):
732        verb = fact.attributes.get("verb", "ANY").upper()
733        route = fact.attributes.get("path", "/")
734        rows.append([VERB_LABELS.get(verb, "Operación disponible"), f"`{route}`", _cite(fact.citation)])
735    lines += [_table(["Acción", "Dirección", "Cita"], rows), ""]
736
737    lines += ["## Valores que puedes ajustar", ""]
738    settings = _by_kind(facts, "config_key")
739    lines += [
740        _table(
741            ["Ajuste", "Valor actual", "Cita"],
742            [[f"`{fact.attributes.get('key', fact.subject)}`", f"`{fact.detail}`", _cite(fact.citation)] for fact in settings],
743        ),
744        "",
745    ]
746
747    lines += ["## Preguntas frecuentes", ""]
748    # F10: rellenar con secciones del README que respondan PURPOSE_HINTS. No va un subtítulo `##`
749    # dentro: el lector de L3 no necesita otra cabecera, y la cita debe ir en el mismo bloque.
750    matched = find_docs(docs_sections, PURPOSE_HINTS, limit=3)
751    if matched:
752        lines += [
753            "> El proyecto **ya documenta** esto. Se cita para no duplicarlo ni contradecirlo.",
754            "",
755        ]
756        for section in matched:
757            body = f" — {section.body[:300]}" if section.body else ""
Narrative.factsdef facts(self) -> list[Fact]
Ver prueba
src/docu/generate/narrative.py#L56-L57
Anotaciones: @property
56    def facts(self) -> list[Fact]:
57        return [*self.intent, *self.decisions]
_cleandef _clean(text: str) -> str
Ver prueba
src/docu/generate/narrative.py#L60-L71
60def _clean(text: str) -> str:
61    text = re.sub(r"^\s*(?:\*|//|#)\s?", "", text, flags=re.MULTILINE)
62    # Fuera imágenes, badges y enlaces sueltos: no son prosa, son decoración del README.
63    text = re.sub(r"!\[[^\]]*\]\([^)]*\)", "", text)
64    text = re.sub(r"\[!\[[^\]]*\]\([^)]*\)\]\([^)]*\)", "", text)
65    text = re.sub(r"^\s*<[^>]+>\s*$", "", text, flags=re.MULTILINE)
66    text = " ".join(text.split())
67    # Énfasis de Markdown: `**texto**` es texto, no asteriscos.
68    text = re.sub(r"\*\*|__", "", text)
69    text = re.sub(r"^[*_>\s]+", "", text)
70    text = re.sub(r"[*_]+$", "", text)
71    return text.strip()
_locatedef _locate(source: str, paragraph: str) -> tuple[int, int]
Ver prueba
src/docu/generate/narrative.py#L74-L91
74def _locate(source: str, paragraph: str) -> tuple[int, int]:
75    """Línea inicial y final del párrafo en el archivo original.
76
77    El párrafo va normalizado (espacios colapsados), así que buscarlo literal falla: se busca por sus
78    primeras palabras tolerando saltos de línea **y marcas de Markdown**. Sin esto, un párrafo en
79    negrita (`**Documentación verificable.**`) caía al fallback y la cita apuntaba a la línea 1, donde
80    no estaba el texto.
81    """
82    words = paragraph.split()[:6]
83    if not words:
84        return 1, 1
85    pattern = re.compile(r"[\s*_`]+".join(re.escape(word) for word in words))
86    match = pattern.search(source)
87    if match is None:
88        return 1, 1
89    start = _line_of(source, match.start())
90    block = re.split(r"\n\s*\n", source[match.start() :], maxsplit=1)[0]
91    return start, max(start, start + block.count("\n"))
_is_prosedef _is_prose(text: str) -> bool
Ver prueba
src/docu/generate/narrative.py#L94-L102
94def _is_prose(text: str) -> bool:
95    """¿Esto parece una frase escrita por una persona, o una fila de tabla/una insignia?"""
96    if len(text) < 40:
97        return False
98    if text.startswith(("|", "---", "```", ">")):
99        return False
100    if text.count("](") >= 1 and not re.search(r"[a-záéíóúñ]{4,}\s+[a-záéíóúñ]{4,}", text):
101        return False
102    return len(re.findall(r"[A-Za-zÁÉÍÓÚÑáéíóúñ]{3,}", text)) >= 5
_first_paragraphdef _first_paragraph(text: str) -> str
Ver prueba
src/docu/generate/narrative.py#L105-L112
105def _first_paragraph(text: str) -> str:
106    for block in re.split(r"\n\s*\n", text):
107        if block.lstrip().startswith("#"):
108            continue  # un título no es una declaración de intención
109        cleaned = _clean(block)
110        if _is_prose(cleaned):
111            return cleaned[:MAX_TEXT]
112    return ""
_citationdef _citation(path: str, start: int, end: int) -> str
Ver prueba
src/docu/generate/narrative.py#L115-L116
115def _citation(path: str, start: int, end: int) -> str:
116    return f"{path}#L{start}-L{max(start, end)}"
_line_ofdef _line_of(source: str, offset: int) -> int
Ver prueba
src/docu/generate/narrative.py#L119-L120
119def _line_of(source: str, offset: int) -> int:
120    return source.count("\n", 0, offset) + 1
doc_factsdef doc_facts(rel: str, source: str) -> list[Fact]
Ver prueba
src/docu/generate/narrative.py#L123-L159
123def doc_facts(rel: str, source: str) -> list[Fact]:
124    """Intención (y decisión, si el documento lo es) de un Markdown del proyecto."""
125    lines = source.splitlines()
126    if not lines:
127        return []
128    title = next((line.lstrip("# ").strip() for line in lines if line.startswith("#")), "")
129    paragraph = _first_paragraph(source)
130    if not paragraph:
131        return []
132    start, end = _locate(source, paragraph)
133    facts: list[Fact] = []
134    is_decision = any(hint in rel.lower() for hint in DECISION_HINTS)
135    status = ""
136    for match in _STATUS_RE.finditer(source):
137        status = _clean(match.group("status"))[:60]
138        break
139    if is_decision:
140        facts.append(
141            Fact(
142                kind="decision",
143                subject=title or rel,
144                detail=f"{status or 'sin estado declarado'} · {paragraph}",
145                citation=_citation(rel, start, end),
146                attributes={"source": rel, "status": status},
147            )
148        )
149    else:
150        facts.append(
151            Fact(
152                kind="intent",
153                subject=title or rel,
154                detail=paragraph,
155                citation=_citation(rel, start, end),
156                attributes={"source": rel},
157            )
158        )
159    return facts
_javadoc_factsdef _javadoc_facts(rel: str, source: str) -> list[Fact]
Ver prueba
src/docu/generate/narrative.py#L162-L180
162def _javadoc_facts(rel: str, source: str) -> list[Fact]:
163    """Docstrings de estilo JSDoc/Javadoc: primer párrafo antes de una declaración."""
164    facts: list[Fact] = []
165    for match in _JAVADOC_RE.finditer(source):
166        paragraph = _first_paragraph(match.group("body"))
167        if not paragraph or paragraph.startswith("@"):
168            continue
169        start = _line_of(source, match.start())
170        end = _line_of(source, match.end())
171        facts.append(
172            Fact(
173                kind="intent",
174                subject=f"{rel}#L{start}",
175                detail=paragraph,
176                citation=_citation(rel, start, end),
177                attributes={"source": rel},
178            )
179        )
180    return facts
_python_docstring_factsdef _python_docstring_facts(rel: str, source: str) -> list[Fact]
Ver prueba
src/docu/generate/narrative.py#L183-L220
183def _python_docstring_facts(rel: str, source: str) -> list[Fact]:
184    """Docstrings de módulo, clase y función con `ast`: la intención declarada por el autor."""
185    try:
186        tree = ast.parse(source)
187    except SyntaxError:
188        return []
189    facts: list[Fact] = []
190    module_doc = ast.get_docstring(tree)
191    if module_doc:
192        lines = module_doc.strip().splitlines()
193        facts.append(
194            Fact(
195                kind="intent",
196                subject=f"{rel} (módulo)",
197                detail=_clean(lines[0])[:MAX_TEXT],
198                citation=_citation(rel, 1, max(1, len(lines))),
199                attributes={"source": rel},
200            )
201        )
202    for node in ast.walk(tree):
203        if not isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
204            continue
205        doc = ast.get_docstring(node)
206        if not doc:
207            continue
208        body = node.body[0] if node.body else node
209        start = getattr(body, "lineno", node.lineno)
210        end = getattr(node, "end_lineno", node.lineno)
211        facts.append(
212            Fact(
213                kind="intent",
214                subject=node.name,
215                detail=_clean(doc.strip().splitlines()[0])[:MAX_TEXT],
216                citation=_citation(rel, start, min(end, start + 12)),
217                attributes={"source": rel},
218            )
219        )
220    return facts
why_commentsdef why_comments(rel: str, source: str) -> list[Fact]
Ver prueba
src/docu/generate/narrative.py#L223-L245
223def why_comments(rel: str, source: str) -> list[Fact]:
224    """Comentarios que explican un porqué: la decisión queda donde se tomó.
225
226    Sólo se leen **comentarios**, no cadenas ni docstrings: un `#` dentro de una cadena no es una
227    decisión del equipo. Esa distinción es la que evita llenar la sección de ruido.
228    """
229    pattern = _PY_COMMENT_RE if rel.endswith(".py") else _CODE_COMMENT_RE
230    facts: list[Fact] = []
231    for match in pattern.finditer(source):
232        text = _clean(match.group("text")).lstrip(":·- ").strip()
233        if len(text) < 40 or not _WHY_WORDS.search(text):
234            continue
235        line = _line_of(source, match.start())
236        facts.append(
237            Fact(
238                kind="decision",
239                subject=text[:60],
240                detail=text[:MAX_TEXT],
241                citation=_citation(rel, line, line),
242                attributes={"source": rel, "status": "comentario en código"},
243            )
244        )
245    return facts
metadata_factsdef metadata_facts(root: Path) -> list[Fact]
Ver prueba
src/docu/generate/narrative.py#L248-L293
248def metadata_facts(root: Path) -> list[Fact]:
249    """Propósito declarado en los metadatos del proyecto.
250
251    prose --emit ofrecía sólo rutas, dependencias y tipos: con eso una introducción no puede decir
252    *qué hace* el producto. El description de package.json y de pyproject.toml sí lo dice, y es
253    una fuente citables como cualquier otra.
254    """
255    facts: list[Fact] = []
256    package = root / "package.json"
257    if package.is_file():
258        try:
259            payload = json.loads(package.read_text(encoding="utf-8", errors="replace"))
260        except (OSError, json.JSONDecodeError):
261            payload = None
262        description = payload.get("description") if isinstance(payload, dict) else None
263        if isinstance(description, str) and len(description.strip()) >= 20:
264            texto = package.read_text(encoding="utf-8", errors="replace")
265            line = _line_of(texto, max(0, texto.find("description")))
266            facts.append(
267                Fact(
268                    kind="intent",
269                    subject="package.json (description)",
270                    detail=description.strip()[:MAX_TEXT],
271                    citation=_citation("package.json", line, line),
272                    attributes={"source": "package.json"},
273                )
274            )
275    pyproject = root / "pyproject.toml"
276    if pyproject.is_file():
277        try:
278            text = pyproject.read_text(encoding="utf-8", errors="replace")
279        except OSError:
280            text = ""
281        match = re.search(r'(?m)^\s*description\s*=\s*["\'](?P<text>.+?)["\']\s*$', text)
282        if match and len(match.group("text")) >= 20:
283            line = _line_of(text, match.start())
284            facts.append(
285                Fact(
286                    kind="intent",
287                    subject="pyproject.toml (description)",
collectdef collect(root: Path, files: Mapping[str, Path], counts: Mapping[str, int], project: str, read) -> Narrative
Ver prueba
src/docu/generate/narrative.py#L296-L341
296def collect(
297    root: Path,
298    files: Mapping[str, Path],
299    counts: Mapping[str, int],
300    project: str,
301    read,
302) -> Narrative:
303    """Recolecta intención y decisiones, y compone la introducción con lo que encontró."""
304    collected: list[Fact] = list(metadata_facts(root))
305
306    for candidate in INTENT_DOCS + ("CHANGELOG.md",):
307        path = root / candidate
308        if not path.is_file():
309            continue
310        try:
311            collected.extend(doc_facts(candidate, read(path)))
312        except OSError:
313            continue
314
315    for rel in sorted(files):
316        if not rel.lower().endswith(".md"):
317            continue
318        if any(hint in rel.lower() for hint in DECISION_HINTS):
319            try:
320                collected.extend(doc_facts(rel, read(files[rel])))
321            except OSError:
322                continue
323
324    for rel, path in sorted(files.items()):
325        try:
326            source = read(path)
327        except OSError:
328            continue
329        if rel.endswith(".py"):
330            collected.extend(_python_docstring_facts(rel, source))
331            collected.extend(why_comments(rel, source))
332        elif rel.endswith((".java", ".ts", ".tsx", ".js", ".mjs", ".cjs", ".jsx")):
333            collected.extend(_javadoc_facts(rel, source))
334            collected.extend(why_comments(rel, source))
335
_shortdef _short(text: str, limit: int=...) -> str
Ver prueba
src/docu/generate/narrative.py#L344-L349
344def _short(text: str, limit: int = 44) -> str:
345    """Etiqueta legible: sin backticks y cortada en una frontera de palabra."""
346    clean = text.replace("", "").strip()
347    if len(clean) <= limit:
348        return clean
349    return clean[:limit].rsplit(" ", 1)[0].rstrip(",.;:") + "…"
_introdef _intro(project: str, counts: Mapping[str, int], narrative: Narrative) -> str
Ver prueba
src/docu/generate/narrative.py#L352-L396
352def _intro(project: str, counts: Mapping[str, int], narrative: Narrative) -> str:
353    """Introducción legible compuesta de hechos citados, no de adjetivos.
354
355    Cada frase es una afirmación con su fuente: la primera, del conteo real; la segunda, de la
356    documentación del proyecto; la tercera, de su propio código. Si falta una fuente, la frase no se
357    escribe y la sección lo dice.
358    """
359    parts: list[str] = []
360    modules = counts.get("module", 0)
361    packages = counts.get("package", 0)
362    routes = counts.get("route", 0)
363    types = counts.get("type", 0)
364    fields = counts.get("field", 0)
365
366    stack: list[str] = []
367    if counts.get("dependency"):
368        stack.append(f"{counts['dependency']} dependencias declaradas")
369    if modules:
370        stack.append(f"{modules} módulos de build")
371    if packages:
372        stack.append(f"{packages} paquetes")
373    if routes:
374        stack.append(f"{routes} rutas HTTP")
375    if types:
376        stack.append(f"{types} tipos y {fields} campos")
377    if stack:
378        parts.append(f"**{project}** se compone de " + ", ".join(stack) + ".")
379
380    if narrative.intent:
381        first = narrative.intent[0]
382        parts.append(f"Su propia documentación declara: «{first.detail}» [`{first.citation}`].")
383    if narrative.decisions:
384        titles = "; ".join(f"«{_short(fact.subject)}»" for fact in narrative.decisions[:3])
385        rest = len(narrative.decisions) - len(narrative.decisions[:3])
386        extra = f" y {rest} más" if rest > 0 else ""
387        parts.append(
388            f"El repositorio deja constancia de {len(narrative.decisions)} decisiones "
389            f"({titles}{extra}); están listadas con su cita en la sección *Intención y decisiones*."
390        )
391    if not narrative.intent and not narrative.decisions:
is_env_filedef is_env_file(path: str) -> bool
Ver prueba
src/docu/generate/ops.py#L33-L34
33def is_env_file(path: str) -> bool:
34    return path.rsplit("/", 1)[-1] in ENV_FILES
is_docker_filedef is_docker_file(path: str) -> bool
Ver prueba
src/docu/generate/ops.py#L37-L38
37def is_docker_file(path: str) -> bool:
38    return path.rsplit("/", 1)[-1] in DOCKER_FILES
is_compose_filedef is_compose_file(path: str) -> bool
Ver prueba
src/docu/generate/ops.py#L41-L42
41def is_compose_file(path: str) -> bool:
42    return path.rsplit("/", 1)[-1] in COMPOSE_FILES
is_workflow_filedef is_workflow_file(path: str) -> bool
Ver prueba
src/docu/generate/ops.py#L45-L47
45def is_workflow_file(path: str) -> bool:
46    """Workflows de CI: no son configuración de la aplicación y no deben aparecer como tal."""
47    return "/.github/workflows/" in f"/{path}" or path.startswith(".github/workflows/")
env_factsdef env_facts(path: str, source: str) -> list[Fact]
Ver prueba
src/docu/generate/ops.py#L50-L69
50def env_facts(path: str, source: str) -> list[Fact]:
51    """Variables de entorno **requeridas**, por nombre. El valor no se lee ni se documenta."""
52    facts: list[Fact] = []
53    for line_number, line in enumerate(source.splitlines(), start=1):
54        if line.strip().startswith("#"):
55            continue
56        match = _ENV_LINE_RE.match(line)
57        if match is None:
58            continue
59        name = match.group("key")
60        facts.append(
61            Fact(
62                kind="env_var",
63                subject=name,
64                detail=path.rsplit("/", 1)[-1],
65                citation=f"{path}#L{line_number}-L{line_number}",
66                attributes={"file": path},
67            )
68        )
69    return facts
dockerfile_factsdef dockerfile_facts(path: str, source: str) -> list[Fact]
Ver prueba
src/docu/generate/ops.py#L72-L107
72def dockerfile_facts(path: str, source: str) -> list[Fact]:
73    """Imagen base, puertos expuestos y comando de arranque."""
74    facts: list[Fact] = []
75    for line_number, line in enumerate(source.splitlines(), start=1):
76        stripped = line.strip()
77        if not stripped or stripped.startswith("#"):
78            continue
79        if match := _FROM_RE.match(line):
80            facts.append(
81                Fact(
82                    kind="image",
83                    subject=match.group("image"),
84                    detail="imagen base",
85                    citation=f"{path}#L{line_number}-L{line_number}",
86                )
87            )
88        elif match := _EXPOSE_RE.match(line):
89            for port in match.group("ports").split():
90                facts.append(
91                    Fact(
92                        kind="port",
93                        subject=port,
94                        detail="expuesto por la imagen",
95                        citation=f"{path}#L{line_number}-L{line_number}",
96                    )
97                )
98        elif match := _CMD_RE.match(line):
99            facts.append(
100                Fact(
101                    kind="process",
102                    subject=f"{match.group('directive').upper()} {match.group('command').strip()[:80]}",
103                    detail="arranque del contenedor",
104                    citation=f"{path}#L{line_number}-L{line_number}",
105                )
106            )
107    return facts
_safe_parsedef _safe_parse(source: str) -> object
Ver prueba
src/docu/generate/ops.py#L110-L115
110def _safe_parse(source: str) -> object:
111    """YAML tolerante: un compose exótico no debe tumbar la generación completa."""
112    try:
113        return parse_yaml(source)
114    except YamlError:
115        return None
compose_factsdef compose_facts(path: str, source: str) -> list[Fact]
Ver prueba
src/docu/generate/ops.py#L118-L164
118def compose_facts(path: str, source: str) -> list[Fact]:
119    """Servicios, puertos publicados y variables de entorno (sólo nombres)."""
120    payload = _safe_parse(source)
121    if not isinstance(payload, dict):
122        return []
123    services = payload.get("services")
124    if not isinstance(services, dict):
125        return []
126    facts: list[Fact] = []
127    for service in services:
128        name = str(service)
129        facts.append(
130            Fact(
131                kind="service",
132                subject=name,
133                detail="servicio de compose",
134                citation=f"{path}#L{_line_with(source, f'{name}:')}-L{_line_with(source, f'{name}:')}",
135            )
136        )
137        block = services[service]
138        if not isinstance(block, dict):
139            continue
140        for port in block.get("ports") or []:
141            match = _PORT_MAPPING_RE.match(str(port))
142            if match is None:
143                continue
144            facts.append(
145                Fact(
146                    kind="port",
147                    subject=f"{match.group('host')}→{match.group('container')}",
148                    detail=f"publicado por {name}",
149                    citation=f"{path}#L{_line_with(source, str(port))}-L{_line_with(source, str(port))}",
150                )
151            )
152        depends = block.get("depends_on") or []
153        if isinstance(depends, list):
154            for dependency in depends:
155                facts.append(
156                    Fact(
157                        kind="dependency_edge",
scripts_factsdef scripts_facts(path: str, payload: dict[str, object], source: str) -> list[Fact]
Ver prueba
src/docu/generate/ops.py#L167-L184
167def scripts_facts(path: str, payload: dict[str, object], source: str) -> list[Fact]:
168    """Comandos declarados en `package.json` (`scripts`)."""
169    scripts = payload.get("scripts")
170    if not isinstance(scripts, dict):
171        return []
172    start = source.find('"scripts"')
173    facts: list[Fact] = []
174    for name, command in scripts.items():
175        line = _line_with_after(source, f'"{name}"', start)
176        facts.append(
177            Fact(
178                kind="command",
179                subject=str(name),
180                detail=str(command)[:120],
181                citation=f"{path}#L{line}-L{line}",
182            )
183        )
184    return facts
workflow_factsdef workflow_facts(path: str, source: str) -> list[Fact]
Ver prueba
src/docu/generate/ops.py#L187-L234
187def workflow_facts(path: str, source: str) -> list[Fact]:
188    """Nombre, disparadores y jobs de un workflow de CI."""
189    payload = _safe_parse(source)
190    if not isinstance(payload, dict):
191        return []
192    facts: list[Fact] = []
193    name = payload.get("name") or path.rsplit("/", 1)[-1]
194    facts.append(
195        Fact(
196            kind="workflow",
197            subject=str(name),
198            detail=path,
199            citation=f"{path}#L1-L1",
200        )
201    )
202    triggers = payload.get("on") or payload.get(True)  # `on:` se parsea como booleano en YAML 1.1
203    if isinstance(triggers, str):
204        triggers = [triggers]
205    elif isinstance(triggers, dict):
206        triggers = list(triggers)
207    if isinstance(triggers, list):
208        on_start = source.find("on:")
209        for trigger in triggers:
210            # La cita debe apuntar a la línea del disparador, no a la clave `on:`: si no, la
211            # auditoría tiene razón en marcarla y el lector no encuentra nada al abrirla.
212            line = _line_with_after(source, f"{trigger}", max(on_start, 0))
213            facts.append(
214                Fact(
215                    kind="trigger",
216                    subject=str(trigger),
217                    detail=f"dispara {name}",
218                    citation=f"{path}#L{line}-L{line}",
219                )
220            )
221    jobs = payload.get("jobs")
222    if isinstance(jobs, dict):
223        start = source.find("jobs:")
224        for job in jobs:
225            line = _line_with_after(source, f"{job}:", start)
226            facts.append(
_is_test_pathdef _is_test_path(rel: Path) -> bool
Ver prueba
src/docu/generate/pipeline.py#L75-L79
75def _is_test_path(rel: Path) -> bool:
76    lowered = [part.lower() for part in rel.parts]
77    if any(part in TEST_DIRS for part in lowered):
78        return True
79    return "src" in lowered and "test" in lowered
GenerationResult.wrote_filesdef wrote_files(self) -> bool
Ver prueba
src/docu/generate/pipeline.py#L115-L116
Anotaciones: @property
115    def wrote_files(self) -> bool:
116        return bool(self.docs) and not self.dry_run
GenerationResult.pendingdef pending(self) -> tuple[str, ...]
Ver prueba
src/docu/generate/pipeline.py#L119-L123
Anotaciones: @property
119    def pending(self) -> tuple[str, ...]:
120        """Niveles que quedaron sin regenerar en modo incremental."""
121        return tuple(
122            level for level, state in self.states.items() if state is DocState.FRESH
123        )
_path_matchesdef _path_matches(rel: str, patterns: Sequence[str]) -> bool
Ver prueba
src/docu/generate/pipeline.py#L126-L141
126def _path_matches(rel: str, patterns: Sequence[str]) -> bool:
127    """Coincidencia por segmento: `contracts/*` casa con `contracts/FEAT.md` y con sus hijos.
128
129    Los comodines globales (`*`, `**`, `**/*`) casan con todo: es lo que un humano espera al
130    escribirlos, y `fnmatch` no lo cumple para archivos de la raíz.
131    """
132    import fnmatch
133
134    if any(pattern in ("*", "**", "**/*", "./**") for pattern in patterns):
135        return True
136    parts = rel.split("/")
137    for index in range(1, len(parts) + 1):
138        candidate = "/".join(parts[:index])
139        if any(fnmatch.fnmatch(candidate, pattern) or fnmatch.fnmatch(rel, pattern) for pattern in patterns):
140            return True
141    return False
_effective_excludedef _effective_exclude(exclude: Sequence[str]) -> tuple[str, ...]
Ver prueba
src/docu/generate/pipeline.py#L144-L152
144def _effective_exclude(exclude: Sequence[str]) -> tuple[str, ...]:
145    """Exclusiones del proyecto + piso de higiene + `.gitignore`.
146
147    El `.gitignore` es la declaración más autorizada de qué no es fuente: sin leerlo, un proyecto
148    indexaba `coverage/` (artefactos de reportes) y lo contaba como código en sus métricas.
149    """
150    from docu.core.profile import DEFAULT_EXCLUDE
151
152    return tuple(dict.fromkeys((*exclude, *DEFAULT_EXCLUDE)))
_discoverdef _discover(root: Path, include_tests: bool=..., include: Sequence[str]=..., exclude: Sequence[str]=...) -> dict[str, Path]
Ver prueba
src/docu/generate/pipeline.py#L155-L194
155def _discover(
156    root: Path,
157    include_tests: bool = False,
158    include: Sequence[str] = (),
159    exclude: Sequence[str] = (),
160) -> dict[str, Path]:
161    """Archivos relevantes, con la higiene de corpus que declare el perfil."""
162    from docu.index.ignore import is_ignored
163    from docu.index.ignore import load as load_ignore
164
165    patterns = _effective_exclude(exclude)
166    rules = load_ignore(root)
167    found: dict[str, Path] = {}
168    for candidate in sorted(root.rglob("*")):
169        if not candidate.is_file():
170            continue
171        rel = candidate.relative_to(root)
172        rel_text = rel.as_posix()
173        if any(part in EXCLUDED_PARTS for part in rel.parts):
174            continue
175        if is_ignored(rel_text, rules):
176            continue
177        if patterns and _path_matches(rel_text, patterns):
178            continue
179        if include and not _path_matches(rel_text, include):
180            continue
181        if not include_tests and _is_test_path(rel):
182            continue
183        name = candidate.name
184        if (
185            adapter_for(name) is not None
186            or name.endswith((".yml", ".yaml"))
187            or name == "pom.xml"
188            or name in EXTRA_FILES
189            or is_env_file(rel_text)
190            or is_docker_file(rel_text)
191            or is_compose_file(rel_text)
192        ):
193            found[rel_text] = candidate
194    return found
_readdef _read(path: Path) -> str
Ver prueba
src/docu/generate/pipeline.py#L197-L198
197def _read(path: Path) -> str:
198    return path.read_text(encoding="utf-8", errors="replace")
collect_factsdef collect_facts(root: Path, include_tests: bool=..., include: Sequence[str]=..., exclude: Sequence[str]=...) -> tuple[list[Fact], dict[str, str]]
Ver prueba
src/docu/generate/pipeline.py#L201-L278
201def collect_facts(
202    root: Path,
203    include_tests: bool = False,
204    include: Sequence[str] = (),
205    exclude: Sequence[str] = (),
206) -> tuple[list[Fact], dict[str, str]]:
207    """Recorre el repositorio y devuelve hechos + huellas de las fuentes.
208
209    El despacho es por adaptador: anadir un lenguaje no toca esta funcion mas alla del registro.
210    """
211    facts: list[Fact] = []
212    sources: dict[str, str] = {}
213    discovered = _discover(root, include_tests=include_tests, include=include, exclude=exclude)
214    for rel, path in discovered.items():
215        source = _read(path)
216        # Hash sobre contenido normalizado: si no, el mismo commit da hashes distintos en Windows
217        # (CRLF) y en Linux (LF), y la frescura se rompe al mover el proyecto o al correr el CI.
218        normalized = source.replace("\r\n", "\n").replace("\r", "\n")
219        sources[rel] = sha256_of(normalized.encode("utf-8")).replace("sha256:", "")[:12]
220        adapter = adapter_for(rel)
221        if is_compose_file(rel):
222            facts.extend(compose_facts(rel, source))
223        elif is_env_file(rel):
224            # Sólo archivos de ejemplo: un `.env` real no se abre nunca.
225            facts.extend(env_facts(rel, source))
226        elif is_docker_file(rel):
227            facts.extend(dockerfile_facts(rel, source))
228        elif is_workflow_file(rel) and rel.endswith((".yml", ".yaml")):
229            # Los workflows son CI, no configuración de la aplicación: mezclarlos ensucia la tabla
230            # de configuración con claves internas de GitHub Actions.
231            facts.extend(workflow_facts(rel, source))
232        elif adapter is not None:
233            facts.extend(java_facts(adapter.symbols(rel, source)))  # type: ignore[attr-defined]
234        elif rel.endswith("pom.xml"):
235            facts.extend(pom_facts(rel, source))
236        elif rel.endswith((".yml", ".yaml")):
237            facts.extend(yaml_facts(rel, source))
238        elif rel.endswith("package.json"):
239            facts.extend(package_json_facts(rel, source))
240            try:
unsupported_sourcesdef unsupported_sources(root: Path, include_tests: bool=..., include: Sequence[str]=..., exclude: Sequence[str]=...) -> dict[str, int]
Ver prueba
src/docu/generate/pipeline.py#L324-L354
324def unsupported_sources(
325    root: Path,
326    include_tests: bool = False,
327    include: Sequence[str] = (),
328    exclude: Sequence[str] = (),
329) -> dict[str, int]:
330    """Cuenta archivos de lenguajes conocidos pero no soportados, por extension."""
331    from docu.index.ignore import is_ignored
332    from docu.index.ignore import load as load_ignore
333
334    patterns = _effective_exclude(exclude)
335    rules = load_ignore(root)
336    counts: dict[str, int] = {}
337    for candidate in root.rglob("*"):
338        if not candidate.is_file():
339            continue
340        rel = candidate.relative_to(root)
341        if any(part in EXCLUDED_PARTS for part in rel.parts):
342            continue
343        if is_ignored(rel.as_posix(), rules):
344            continue
345        if patterns and _path_matches(rel.as_posix(), patterns):
346            continue
347        if include and not _path_matches(rel.as_posix(), include):
348            continue
349        if not include_tests and _is_test_path(rel):
350            continue
351        suffix = candidate.suffix.lower()
352        if suffix in UNSUPPORTED_SOURCES:
353            counts[suffix] = counts.get(suffix, 0) + 1
354    return dict(sorted(counts.items()))
applicabilitydef applicability(facts: Sequence[Fact], root: Path) -> dict[str, bool]
Ver prueba
src/docu/generate/pipeline.py#L357-L375
357def applicability(facts: Sequence[Fact], root: Path) -> dict[str, bool]:
358    """¿Qué secciones tienen sentido en **este** proyecto?
359
360    Un CLI en Python no tiene módulos Maven ni rutas HTTP: exigírselos convierte la compuerta en
361    ruido y penaliza proyectos legítimos. La aplicabilidad se deduce de artefactos observables y
362    queda declarada en el documento, no escondida en el código.
363    """
364    kinds = {fact.kind for fact in facts}
365    dependencies = " ".join(
366        fact.subject.lower() for fact in facts if fact.kind == "dependency"
367    )
368    has_structure = "module" in kinds or "package" in kinds
369    return {
370        "type": "type" in kinds,
371        "config_key": "config_key" in kinds,
372        "dependency": "dependency" in kinds or any((root / name).exists() for name in MANIFESTS),
373        "module": has_structure,
374        "route": "route" in kinds or any(hint in dependencies for hint in FRAMEWORK_HINTS),
375    }
completenessdef completeness(facts: Sequence[Fact], applicable: Mapping[str, bool]) -> float
Ver prueba
src/docu/generate/pipeline.py#L386-L396
386def completeness(facts: Sequence[Fact], applicable: Mapping[str, bool]) -> float:
387    """Cobertura de las secciones **aplicables**: 10 si todo lo que existe está documentado."""
388    required = [kind for kind, needed in applicable.items() if needed]
389    if not required:
390        return 0.0
391    present = sum(
392        1
393        for kind in required
394        if any(fact.kind in KIND_EVIDENCE.get(kind, (kind,)) for fact in facts)
395    )
396    return round(10.0 * present / len(required), 2)
concisenessdef conciseness(facts: Sequence[Fact]) -> float
Ver prueba
src/docu/generate/pipeline.py#L399-L404
399def conciseness(facts: Sequence[Fact]) -> float:
400    """Penaliza duplicados exactos (misma afirmacion, misma cita)."""
401    if not facts:
402        return 0.0
403    unique = {(fact.kind, fact.subject, fact.detail, fact.citation) for fact in facts}
404    return round(10.0 * len(unique) / len(facts), 2)
_detected_languagesdef _detected_languages(sources: Mapping[str, str]) -> str
Ver prueba
src/docu/generate/pipeline.py#L417-L424
417def _detected_languages(sources: Mapping[str, str]) -> str:
418    languages = {
419        language
420        for path in sources
421        for suffix, language in LANGUAGE_BY_SUFFIX.items()
422        if path.endswith(suffix)
423    }
424    return ",".join(sorted(languages))
_record_rundef _record_run() -> None
Ver prueba
src/docu/generate/pipeline.py#L427-L461
427def _record_run(
428    *,
429    root: Path,
430    project: str,
431    metrics: Metrics,
432    gate: GateDecision,
433    states: Mapping[str, DocState],
434    versions: Mapping[str, str],
435    sources: Mapping[str, str],
436    pages_written: int,
437    elapsed_s: float,
438    ledger_dir: Path | None = None,
439) -> None:
440    """Deja constancia en el ledger. Un ledger no escribible no puede tumbar la generación.
441
442    Con `--manifest` fuera del proyecto, el ledger se escribe junto al manifest: una prueba sobre un
443    repositorio ajeno no debe dejar rastros dentro de él.
444    """
445    from docu.learn import ledger
446
447    try:
448        ledger.append(
449            ledger.ledger_file(ledger_dir or root),
450            project=project,
451            metrics=metrics,
452            gate=gate,
453            mode=Mode.APPLY,
454            states={level: state.value for level, state in states.items()},
455            versions={**versions, "languages": _detected_languages(sources)},
456            pages_written=pages_written,
457            pages_skipped=max(0, len(states) - pages_written),
458            elapsed_s=elapsed_s,
459        )
460    except OSError:
461        pass
_language_namesdef _language_names(counts: Mapping[str, int]) -> dict[str, int]
Ver prueba
src/docu/generate/pipeline.py#L464-L470
464def _language_names(counts: Mapping[str, int]) -> dict[str, int]:
465    """Agrupa conteos por extension bajo el nombre del lenguaje (`C` puede venir de .c y .h)."""
466    grouped: dict[str, int] = {}
467    for suffix, count in counts.items():
468        name = UNSUPPORTED_SOURCES.get(suffix, suffix)
469        grouped[name] = grouped.get(name, 0) + count
470    return dict(sorted(grouped.items()))
manifest_filedef manifest_file(root: Path, manifest_path: Path | str | None) -> Path
Ver prueba
src/docu/generate/pipeline.py#L473-L474
473def manifest_file(root: Path, manifest_path: Path | str | None) -> Path:
474    return Path(manifest_path) if manifest_path else root / MANIFEST_PATH
inspectdef inspect(root: Path | str, levels: Sequence[str]=..., manifest_path: Path | str | None=..., include_tests: bool=..., ttl_days: int=..., version: str=..., include: Sequence[str]=..., exclude: Sequence[str]=...) -> tuple[Manifest | None, dict[str, DocState], dict[str, str]]
Ver prueba
src/docu/generate/pipeline.py#L477-L515
477def inspect(
478    root: Path | str,
479    levels: Sequence[str] = DEFAULT_LEVELS,
480    manifest_path: Path | str | None = None,
481    include_tests: bool = False,
482    ttl_days: int = 90,
483    version: str = "0.1.0",
484    include: Sequence[str] = (),
485    exclude: Sequence[str] = (),
486) -> tuple[Manifest | None, dict[str, DocState], dict[str, str]]:
487    """Estado de frescura sin generar nada. Es lo que consulta el CI en cada PR.
488
489    Usa **el mismo descubrimiento** que `generate`: si no, los hashes divergen y la frescura miente.
490    """
491    root_path = Path(root).resolve()
492    manifest = Manifest.load(manifest_file(root_path, manifest_path))
493    facts, sources = collect_facts(root_path, include_tests=include_tests, include=include, exclude=exclude)
494    versions = {**DEFAULT_VERSIONS, "docu": version}
495    signature = fact_signature(facts)
496    digest = profile_digest(root_path)
497    states: dict[str, DocState] = {}
498    hashes: dict[str, str] = {}
499    for level in levels:
500        current = input_hash_for(
501            level=level,
502            sources=sources,
503            fact_signature=signature,
504            versions=versions,
505            profile_digest=digest,
506        )
507        hashes[level] = current
508        entry = manifest.entry(level) if manifest else None
509        states[level] = state_of(
510            entry=entry,
511            current_hash=current,
512            ttl_days=ttl_days,
513            file_exists=document_exists(entry, root_path),
514        )
515    return manifest, states, hashes
collect_all_factsdef collect_all_facts(root_path: Path, include_tests: bool=..., include: Sequence[str]=..., exclude: Sequence[str]=..., project: str | None=...) -> tuple[list[Fact], dict[str, str], dict[str, Path], object]
Ver prueba
src/docu/generate/pipeline.py#L518-L547
518def collect_all_facts(
519    root_path: Path,
520    include_tests: bool = False,
521    include: Sequence[str] = (),
522    exclude: Sequence[str] = (),
523    project: str | None = None,
524) -> tuple[list[Fact], dict[str, str], dict[str, Path], object]:
525    """Hechos completos: código, configuración, fuentes externas, intención y decisiones.
526
527    Una sola puerta para que `gen`, `prose` y la auditoría hablen del **mismo** universo. Antes, la
528    prosa delegada ofrecía hechos de código pero no de intención, y el agente citaba ids inexistentes.
529    """
530    from docu.generate.docs_evidence import discover as discover_docs
531    from docu.generate.narrative import collect as collect_narrative
532
533    facts, sources = collect_facts(
534        root_path, include_tests=include_tests, include=include, exclude=exclude
535    )
536    discovered = _discover(root_path, include_tests=include_tests, include=include, exclude=exclude)
537    kind_counts: dict[str, int] = {}
538    for fact in facts:
539        kind_counts[fact.kind] = kind_counts.get(fact.kind, 0) + 1
540    narrative = collect_narrative(
541        root_path, discovered, kind_counts, project or root_path.name, _read
542    )
543    facts.extend(narrative.facts)
544    # La documentación que el proyecto ya escribió se cita como documentación, no como código:
545    # así el onboarding deja de declarar huecos que el README responde.
546    facts.extend(section.to_fact() for section in discover_docs(root_path))
547    return facts, sources, discovered, narrative
collect_all_facts_onlydef collect_all_facts_only(root_path: Path, include_tests: bool=..., include: Sequence[str]=..., exclude: Sequence[str]=..., project: str | None=...) -> list[Fact]
Ver prueba
src/docu/generate/pipeline.py#L550-L561
550def collect_all_facts_only(
551    root_path: Path,
552    include_tests: bool = False,
553    include: Sequence[str] = (),
554    exclude: Sequence[str] = (),
555    project: str | None = None,
556) -> list[Fact]:
557    """Variante para comandos que sólo necesitan la lista (prosa delegada, auditoría)."""
558    facts, _sources, _discovered, _narrative = collect_all_facts(
559        root_path, include_tests=include_tests, include=include, exclude=exclude, project=project
560    )
561    return facts
generatedef generate(root: Path | str, out_dir: Path | str, levels: Sequence[str]=..., project: str | None=..., version: str=..., include_tests: bool=..., stamp: bool=..., incremental: bool=..., manifest_path: Path | str | None=..., ttl_days: int=..., include: Sequence[str]=..., exclude: Sequence[str]=..., thresholds: Thresholds | None=..., dry_run: bool=...) -> GenerationResult
Ver prueba
src/docu/generate/pipeline.py#L564-L756
564def generate(
565    root: Path | str,
566    out_dir: Path | str,
567    levels: Sequence[str] = DEFAULT_LEVELS,
568    project: str | None = None,
569    version: str = "0.1.0",
570    include_tests: bool = False,
571    stamp: bool = False,
572    incremental: bool = False,
573    manifest_path: Path | str | None = None,
574    ttl_days: int = 90,
575    include: Sequence[str] = (),
576    exclude: Sequence[str] = (),
577    thresholds: Thresholds | None = None,
578    dry_run: bool = False,
579) -> GenerationResult:
580    """Genera los niveles pedidos. No escribe nada si la compuerta dura falla.
581
582    `dry_run=True` calcula hechos, métricas y compuerta pero **no escribe nada**: ni documentos, ni
583    manifest, ni diagramas, ni ledger. Existe para probar el agente sobre un repositorio ajeno sin
584    dejar rastro.
585    """
586    started = time.perf_counter()
587    root_path = Path(root).resolve()
588    out_path = Path(out_dir)
589    name = project or root_path.name
590    manifest_target = manifest_file(root_path, manifest_path)
591
592    facts, sources, discovered, narrative = collect_all_facts(
593        root_path,
594        include_tests=include_tests,
595        include=include,
596        exclude=exclude,
597        project=name,
598    )
599    packages = detect_packages(discovered)
600    diagrams = build_all(discovered, packages, facts, _read)
601
602    # Prosa delegada: si el agente del desarrollador dejó una respuesta validada, entra al documento
603    # con su procedencia. Se revalida contra los hechos actuales: la prosa de ayer puede citar un
ProseResponse.accepteddef accepted(self) -> bool
Ver prueba
src/docu/generate/prose.py#L60-L61
Anotaciones: @property
60    def accepted(self) -> bool:
61        return not self.errors and bool(self.sections)
Verdict.accepteddef accepted(self) -> bool
Ver prueba
src/docu/generate/prose.py#L75-L76
Anotaciones: @property
75    def accepted(self) -> bool:
76        return not self.errors and self.score >= MIN_JUDGE_SCORE
fact_iddef fact_id(fact: Fact) -> str
Ver prueba
src/docu/generate/prose.py#L79-L80
79def fact_id(fact: Fact) -> str:
80    return f"{fact.kind}:{fact.subject}"
_normdef _norm(text: str) -> str
Ver prueba
src/docu/generate/prose.py#L83-L85
83def _norm(text: str) -> str:
84    text = unicodedata.normalize("NFKD", text.lower())
85    return "".join(char for char in text if not unicodedata.combining(char))
build_requestdef build_request(project: str, facts: Sequence[Fact], language: str=..., limit: int=...) -> dict[str, object]
Ver prueba
src/docu/generate/prose.py#L88-L139
88def build_request(
89    project: str, facts: Sequence[Fact], language: str = "es", limit: int = 120
90) -> dict[str, object]:
91    """Contrato de redacción: qué puede decir el agente y cómo debe devolverlo."""
92    ordered: list[Fact] = []
93    for kind in NARRATIVE_KINDS:
94        ordered.extend(fact for fact in facts if fact.kind == kind)
95        if len(ordered) >= limit:
96            break
97    selected = ordered[:limit]
98    has_purpose = any(fact.kind in PURPOSE_KINDS for fact in facts)
99    payload: dict[str, object] = {
100        "project": project,
101        "language": language,
102        "task": (
103            "Escribí una introducción breve para este proyecto usando SOLO los hechos listados. "
104            "Cada frase debe declarar los ids de los hechos en los que se apoya. No agregues cifras "
105            "que no estén en los hechos, no inventes motivaciones y no uses encabezados."
106        ),
107        "rules": {
108            "max_sentences": MAX_SENTENCES,
109            "max_words_per_sentence": MAX_WORDS_PER_SENTENCE,
110            "must_reference_fact_ids": True,
111            "no_new_numbers": True,
112            "no_markdown_headings": True,
113        },
114        "response_schema": {
115            "reviewer": "nombre del agente o modelo que redacta",
116            "sections": {
117                "intro": [
118                    {"text": "Una frase.", "fact_ids": ["type:Pedido", "field:Pedido.total"]}
119                ]
120            },
121        },
122        "has_purpose_facts": has_purpose,
123        "facts": [
124            {
125                "id": fact_id(fact),
126                "kind": fact.kind,
127                "subject": fact.subject,
render_request_markdowndef render_request_markdown(request: Mapping[str, object]) -> str
Ver prueba
src/docu/generate/prose.py#L142-L187
142def render_request_markdown(request: Mapping[str, object]) -> str:
143    """La misma petición en Markdown: para pegarla en un agente conversacional."""
144    facts = request.get("facts") or []
145    lines = [
146        f"# Tarea de redacción · {request.get('project')}",
147        "",
148        str(request.get("task")),
149        "",
150        "## Reglas",
151        "",
152        "- Máximo 8 frases; ninguna de más de 70 palabras.",
153        "- **Cada frase declara** los `fact_ids` en los que se apoya.",
154        "- **Ninguna cifra** que no esté en los hechos citados.",
155        "- Sin encabezados ni listas: sólo párrafos.",
156        "",
157        "## Hechos disponibles",
158        "",
159        "| id | detalle | cita |",
160        "|---|---|---|",
161    ]
162    for fact in facts:  # type: ignore[union-attr]
163        detail = str(fact["detail"]).replace("|", "\\|")[:200]
164        lines.append(f"| `{fact['id']}` | {detail} | `{fact['citation']}` |")
165    lines += [
166        "",
167        "## Formato de respuesta (JSON)",
168        "",
169        "```json",
170        json.dumps(
171            {
172                "reviewer": "tu nombre o modelo",
173                "sections": {
174                    "intro": [
175                        {"text": "frase", "fact_ids": ["type:Algo"]},
176                    ]
177                },
178            },
179            ensure_ascii=False,
180            indent=2,
181        ),
_numbersdef _numbers(text: str) -> set[str]
Ver prueba
src/docu/generate/prose.py#L190-L203
190def _numbers(text: str) -> set[str]:
191    """Cifras normalizadas: sin espacios, sin `%`, sin puntuación final y con punto decimal.
192
193    `'6,'` (la coma de «Vite 6, escrita») y `'^6.2.3'` tienen que poder compararse: sin esto, el
194    validador rechazaba versiones y cantidades que sí estaban en los hechos, y empujaba al redactor a
195    omitirlas.
196    """
197    found: set[str] = set()
198    for match in NUMBER_RE.finditer(text):
199        token = match.group(0).replace(" ", "").replace("%", "").replace(",", ".")
200        token = token.rstrip(".;:")
201        if token:
202            found.add(token)
203    return found
_number_supporteddef _number_supported(number: str, supported: set[str]) -> bool
Ver prueba
src/docu/generate/prose.py#L206-L211
206def _number_supported(number: str, supported: set[str]) -> bool:
207    """¿La cifra está en los hechos? Igualdad, o prefijo de versión (`19` ⊂ `19.0.1`)."""
208    if number in supported:
209        return True
210    # Prefijo de versión: «Vite 6» contra ^6.2.3, «React 19» contra ^19.0.1.
211    return any(candidate.startswith(number + ".") for candidate in supported)
validatedef validate(payload: Mapping[str, object], facts: Sequence[Fact]) -> tuple[ProseResponse, dict[str, Fact]]
Ver prueba
src/docu/generate/prose.py#L214-L274
214def validate(
215    payload: Mapping[str, object], facts: Sequence[Fact]
216) -> tuple[ProseResponse, dict[str, Fact]]:
217    """Comprueba la respuesta contra los hechos. Nada entra al documento sin pasar por aquí."""
218    index = {fact_id(fact): fact for fact in facts}
219    response = ProseResponse(reviewer=str(payload.get("reviewer") or ""))
220    sections = payload.get("sections")
221    if not isinstance(sections, dict) or not sections:
222        response.errors.append("la respuesta no trae `sections`")
223        return response, index
224
225    for name, sentences in sections.items():
226        if not isinstance(sentences, list):
227            response.errors.append(f"`sections.{name}` debe ser una lista de frases")
228            continue
229        if len(sentences) > MAX_SENTENCES:
230            response.errors.append(
231                f"`sections.{name}` tiene {len(sentences)} frases y el máximo es {MAX_SENTENCES}"
232            )
233        cleaned: list[dict[str, object]] = []
234        for position, sentence in enumerate(sentences, start=1):
235            if not isinstance(sentence, dict):
236                response.errors.append(f"`{name}` frase {position}: formato inválido")
237                continue
238            text = str(sentence.get("text") or "").strip()
239            ids = sentence.get("fact_ids") or []
240            if not text:
241                response.errors.append(f"`{name}` frase {position}: texto vacío")
242                continue
243            if HEADING_RE.search(text):
244                response.errors.append(f"`{name}` frase {position}: la prosa no puede traer encabezados")
245            if len(text.split()) > MAX_WORDS_PER_SENTENCE:
246                response.warnings.append(f"`{name}` frase {position}: supera las 70 palabras")
247            unknown = [item for item in ids if item not in index]
248            if unknown:
249                response.errors.append(
250                    f"`{name}` frase {position}: cita hechos inexistentes {unknown[:3]}"
251                )
252                continue
253            if not ids:
build_judge_requestdef build_judge_request(project: str, prose: ProseResponse, facts: Sequence[Fact], facts_index: Mapping[str, Fact]) -> dict[str, object]
Ver prueba
src/docu/generate/prose.py#L277-L320
277def build_judge_request(
278    project: str,
279    prose: ProseResponse,
280    facts: Sequence[Fact],
281    facts_index: Mapping[str, Fact],
282) -> dict[str, object]:
283    """Rúbrica para que un **segundo** agente evalúe la prosa sin reescribirla."""
284    cited: dict[str, dict[str, str]] = {}
285    for sentences in prose.sections.values():
286        for sentence in sentences:
287            for identifier in sentence.get("fact_ids", []):  # type: ignore[union-attr]
288                fact = facts_index.get(str(identifier))
289                if fact is not None:
290                    cited[str(identifier)] = {
291                        "detail": fact.detail[:200],
292                        "citation": fact.citation,
293                    }
294    return {
295        "project": project,
296        "task": (
297            "Evaluá la prosa de abajo contra los hechos citados. No la reescribas. Puntuá cada "
298            "criterio de 1 a 5 y devolvé el JSON del esquema. Si una frase afirma algo que los hechos "
299            "no dicen, marcalo en `issues` y bajá la nota de `fidelidad`."
300        ),
301        "criteria": {
302            "fidelidad": "¿cada frase se sostiene con los hechos citados?",
303            "claridad": "¿se entiende sin conocer el código?",
304            "utilidad": "¿ayuda a un lector nuevo a ubicarse?",
305            "concision": "¿dice lo necesario sin relleno?",
306            "tono": "¿es sobrio, sin marketing ni adjetivos vacíos?",
307        },
308        "threshold": MIN_JUDGE_SCORE,
309        "prose": {
310            name: [sentence.get("text") for sentence in sentences]
311            for name, sentences in prose.sections.items()
312        },
313        "cited_facts": cited,
314        "response_schema": {
315            "judge": "nombre del agente o modelo que evalúa",
316            "score": "promedio de 1 a 5",
load_verdictdef load_verdict(payload: Mapping[str, object]) -> Verdict
Ver prueba
src/docu/generate/prose.py#L323-L344
323def load_verdict(payload: Mapping[str, object]) -> Verdict:
324    """Ingiere el veredicto del juez, validando forma y rango."""
325    verdict = Verdict(judge=str(payload.get("judge") or ""))
326    try:
327        verdict.score = float(payload.get("score") or 0)
328    except (TypeError, ValueError):
329        verdict.errors.append("`score` debe ser numérico")
330    if verdict.score and not 0 <= verdict.score <= 5:
331        verdict.errors.append("`score` debe estar entre 0 y 5")
332    criteria = payload.get("criteria")
333    if isinstance(criteria, dict):
334        for name, value in criteria.items():
335            try:
336                verdict.criteria[str(name)] = float(value)  # type: ignore[arg-type]
337            except (TypeError, ValueError):
338                verdict.errors.append(f"criterio {name}: valor no numérico")
339    issues = payload.get("issues")
340    if isinstance(issues, list):
341        verdict.issues = [str(item) for item in issues]
342    if not verdict.score:
343        verdict.errors.append("falta `score`")
344    return verdict
renderdef render(prose: ProseResponse, facts_index: Mapping[str, Fact]) -> str
Ver prueba
src/docu/generate/prose.py#L347-L365
347def render(prose: ProseResponse, facts_index: Mapping[str, Fact]) -> str:
348    """Markdown de la prosa con su procedencia, lista para embeber en el documento."""
349    lines = [
350        (f"> **Prosa redactada por `{prose.reviewer or 'un agente'}`** a partir de hechos citados, y "
351        "validada por `docu`: ninguna frase aporta datos nuevos. Las cifras y las tablas de este "
352        "documento siguen viniendo de la evidencia, no de la prosa."),
353        "",
354    ]
355    for sentences in prose.sections.values():
356        for sentence in sentences:
357            citations = [
358                f"[`{facts_index[str(identifier)].citation}`]"
359                for identifier in sentence.get("fact_ids", [])  # type: ignore[union-attr]
360                if str(identifier) in facts_index
361            ]
362            suffix = f" {' '.join(citations)}" if citations else ""
363            lines.append(f"{sentence.get('text')}{suffix}")
364            lines.append("")
365    return "\n".join(lines)
store_pathdef store_path(root: Path | str) -> Path
Ver prueba
src/docu/generate/prose.py#L368-L369
368def store_path(root: Path | str) -> Path:
369    return Path(root) / PROSE_DIR / STORE_NAME
savedef save(root: Path | str, prose: ProseResponse, verdict: Verdict | None=...) -> Path
Ver prueba
src/docu/generate/prose.py#L372-L392
372def save(root: Path | str, prose: ProseResponse, verdict: Verdict | None = None) -> Path:
373    """Persiste la prosa aceptada (y el veredicto, si lo hay) para que `gen` la use."""
374    target = store_path(root)
375    target.parent.mkdir(parents=True, exist_ok=True)
376    payload = {
377        "reviewer": prose.reviewer,
378        "sections": prose.sections,
379        "warnings": prose.warnings,
380        "verdict": (
381            {
382                "judge": verdict.judge,
383                "score": verdict.score,
384                "criteria": verdict.criteria,
385                "issues": verdict.issues,
386            }
387            if verdict is not None
388            else None
389        ),
390    }
391    target.write_text(json.dumps(payload, ensure_ascii=False, indent=1), encoding="utf-8")
392    return target
loaddef load(root: Path | str) -> tuple[ProseResponse, Verdict | None] | None
Ver prueba
src/docu/generate/prose.py#L395-L424
395def load(root: Path | str) -> tuple[ProseResponse, Verdict | None] | None:
396    """Lee la prosa aceptada, si existe. No revalida: ya se validó al aplicarla."""
397    target = store_path(root)
398    if not target.is_file():
399        return None
400    try:
401        payload = json.loads(target.read_text(encoding="utf-8"))
402    except (OSError, json.JSONDecodeError):
403        return None
404    sections = payload.get("sections")
405    if not isinstance(sections, dict):
406        return None
407    prose = ProseResponse(
408        reviewer=str(payload.get("reviewer") or ""),
409        sections={str(name): list(items) for name, items in sections.items()},  # type: ignore[arg-type]
410        warnings=[str(item) for item in payload.get("warnings") or []],
411    )
412    verdict_payload = payload.get("verdict")
413    verdict = None
414    if isinstance(verdict_payload, dict):
415        verdict = Verdict(
416            judge=str(verdict_payload.get("judge") or ""),
417            score=float(verdict_payload.get("score") or 0),
418            criteria={
419                str(name): float(value)
420                for name, value in (verdict_payload.get("criteria") or {}).items()
421            },
422            issues=[str(item) for item in verdict_payload.get("issues") or []],
423        )
424    return prose, verdict
write_requestdef write_request(directory: Path, request: Mapping[str, object]) -> tuple[Path, Path]
Ver prueba
src/docu/generate/prose.py#L427-L433
427def write_request(directory: Path, request: Mapping[str, object]) -> tuple[Path, Path]:
428    directory.mkdir(parents=True, exist_ok=True)
429    json_path = directory / REQUEST_NAME
430    md_path = directory / REQUEST_MARKDOWN
431    json_path.write_text(json.dumps(request, ensure_ascii=False, indent=1), encoding="utf-8")
432    md_path.write_text(render_request_markdown(request), encoding="utf-8")
433    return json_path, md_path
write_judge_requestdef write_judge_request(directory: Path, request: Mapping[str, object]) -> Path
Ver prueba
src/docu/generate/prose.py#L436-L440
436def write_judge_request(directory: Path, request: Mapping[str, object]) -> Path:
437    directory.mkdir(parents=True, exist_ok=True)
438    path = directory / JUDGE_REQUEST
439    path.write_text(json.dumps(request, ensure_ascii=False, indent=1), encoding="utf-8")
440    return path
estimate_tokensdef estimate_tokens(text: str) -> int
Ver prueba
src/docu/index/chunker.py#L22-L24
22def estimate_tokens(text: str) -> int:
23    """Estimacion deliberadamente simple y estable: ~4 caracteres por token."""
24    return max(1, len(text) // CHARS_PER_TOKEN)
_flattendef _flatten(symbols: Sequence[Symbol]) -> tuple[Symbol, ...]
Ver prueba
src/docu/index/chunker.py#L27-L42
27def _flatten(symbols: Sequence[Symbol]) -> tuple[Symbol, ...]:
28    """Tipos y sus miembros en un solo recorrido, sin duplicar contenedores."""
29    out: list[Symbol] = []
30    seen: set[str] = set()
31
32    def visit(symbol: Symbol) -> None:
33        if symbol.qualname in seen:
34            return
35        seen.add(symbol.qualname)
36        out.append(symbol)
37        for child in symbol.children:
38            visit(child)
39
40    for symbol in symbols:
41        visit(symbol)
42    return tuple(out)
SymbolChunker.chunkdef chunk(self, artifact: Artifact, symbols: Sequence[Symbol], source: str, dependencies: Mapping[str, Sequence[str]] | None=...) -> tuple[Chunk, ...]
Ver prueba
src/docu/index/chunker.py#L53-L89
53    def chunk(
54        self,
55        artifact: Artifact,
56        symbols: Sequence[Symbol],
57        source: str,
58        dependencies: Mapping[str, Sequence[str]] | None = None,
59    ) -> tuple[Chunk, ...]:
60        lines = source.splitlines()
61        if not lines:
62            return ()
63
64        routes = {symbol.qualname: symbol.name for symbol in symbols if symbol.kind is SymbolKind.HTTP_ROUTE}
65        chunks: list[Chunk] = []
66        for symbol in _flatten(symbols):
67            if symbol.kind is SymbolKind.HTTP_ROUTE:
68                continue  # su informacion viaja en el prefijo del metodo
69            if symbol.kind is SymbolKind.FIELD:
70                # Un campo suelto no es una unidad de recuperación útil: su información vive en el
71                # diccionario de datos del tipo y en el ERD, no en un chunk de una línea.
72                continue
73            start, end = self._span(symbol, symbols, lines)
74            body = "\n".join(lines[start - 1 : end])
75            if not body.strip():
76                continue
77            prefix = self._prefix(artifact, symbol, start, end, routes.get(symbol.qualname))
78            chunks.extend(
79                self._split(
80                    artifact=artifact,
81                    symbol=symbol,
82                    prefix=prefix,
83                    body=body,
84                    start=start,
85                    end=end,
86                    dependencies=(dependencies or {}).get(symbol.path, ()),
87                )
88            )
89        return tuple(chunks)
SymbolChunker._spandef _span(self, symbol: Symbol, symbols: Sequence[Symbol], lines: Sequence[str]) -> tuple[int, int]
Ver prueba
src/docu/index/chunker.py#L93-L108
93    def _span(self, symbol: Symbol, symbols: Sequence[Symbol], lines: Sequence[str]) -> tuple[int, int]:
94        """Rango de lineas del simbolo; en contenedores termina antes del primer miembro ejecutable.
95
96        Los campos **no** cortan la cáscara: son parte del contrato de datos del tipo y hacen falta
97        en el chunk del contenedor, junto a la declaración y las anotaciones.
98        """
99        if symbol.kind not in CONTAINER_KINDS:
100            return symbol.line_start, min(symbol.line_end, len(lines))
101        child_starts = [
102            child.line_start
103            for child in symbol.children
104            if child.line_start > symbol.line_start
105            and child.kind not in (SymbolKind.FIELD, SymbolKind.HTTP_ROUTE)
106        ]
107        end = (min(child_starts) - 1) if child_starts else symbol.line_end
108        return symbol.line_start, max(symbol.line_start, min(end, len(lines)))
SymbolChunker._prefixdef _prefix(self, artifact: Artifact, symbol: Symbol, start: int, end: int, route: str | None) -> str
Ver prueba
src/docu/index/chunker.py#L110-L133
110    def _prefix(
111        self,
112        artifact: Artifact,
113        symbol: Symbol,
114        start: int,
115        end: int,
116        route: str | None,
117    ) -> str:
118        """Metadatos inyectados: sin esto el fragmento pierde su procedencia."""
119        parts = [f"File: {symbol.path}"]
120        if symbol.kind in CONTAINER_KINDS:
121            parts.append(f"Type: {symbol.kind.value} {symbol.name}")
122        else:
123            container = symbol.qualname.rsplit(".", 1)[0]
124            parts.append(f"Type: {container}")
125            parts.append(f"Symbol: {symbol.qualname}")
126        if route:
127            parts.append(f"Route: {route}")
128        if symbol.annotations:
129            parts.append("Annotations: " + " ".join(symbol.annotations))
130        parts.append(f"lines {start}-{end}")
131        if artifact.uri and artifact.uri != symbol.path:
132            parts.append(f"source {artifact.uri}")
133        return "[" + " | ".join(parts) + "]"
SymbolChunker._splitdef _split(self) -> list[Chunk]
Ver prueba
src/docu/index/chunker.py#L137-L190
137    def _split(
138        self,
139        *,
140        artifact: Artifact,
141        symbol: Symbol,
142        prefix: str,
143        body: str,
144        start: int,
145        end: int,
146        dependencies: Sequence[str],
147    ) -> list[Chunk]:
148        """Un chunk si cabe; si no, ventanas con solapamiento alineadas a lineas."""
149        total = estimate_tokens(body)
150        base_id = f"{artifact.artifact_id}#{symbol.qualname}"
151        if total <= self.max_tokens:
152            return [
153                self._make(
154                    chunk_id=base_id,
155                    artifact=artifact,
156                    symbol=symbol,
157                    prefix=prefix,
158                    content=body,
159                    start=start,
160                    end=end,
161                    dependencies=dependencies,
162                )
163            ]
164
165        window = self.max_tokens * CHARS_PER_TOKEN
166        step = max(1, (self.max_tokens - self.overlap_tokens) * CHARS_PER_TOKEN)
167        chunks: list[Chunk] = []
168        offset = 0
169        part = 1
170        while offset < len(body):
171            piece = body[offset : offset + window]
172            piece_start = start + body[:offset].count("\n")
173            piece_end = min(end, piece_start + piece.count("\n"))
174            chunks.append(
175                self._make(
176                    chunk_id=f"{base_id}:part{part}",
SymbolChunker._makedef _make(self) -> Chunk
Ver prueba
src/docu/index/chunker.py#L192-L220
192    def _make(
193        self,
194        *,
195        chunk_id: str,
196        artifact: Artifact,
197        symbol: Symbol,
198        prefix: str,
199        content: str,
200        start: int,
201        end: int,
202        dependencies: Sequence[str],
203    ) -> Chunk:
204        return Chunk(
205            chunk_id=chunk_id,
206            artifact_id=artifact.artifact_id,
207            source_type=artifact.kind,
208            content=content,
209            content_prefix=prefix,
210            content_hash=sha256_of(f"{self.name}|{prefix}|{content}"),
211            file_path=symbol.path,
212            lang=artifact.lang,
213            enclosing_symbol=symbol.qualname,
214            symbol_kind=symbol.kind,
215            line_start=start,
216            line_end=max(start, end),
217            ingested_at=utcnow(),
218            dependencies=tuple(dependencies),
219            chunker=self.name,
220        )
compute_input_hashdef compute_input_hash(components: InputComponents) -> str
Ver prueba
src/docu/index/freshness.py#L37-L45
37def compute_input_hash(components: InputComponents) -> str:
38    """Hash estable y explicito: nombre=valor, en orden canonico."""
39    parts: list[str] = []
40    for name in HASH_COMPONENTS:
41        value = getattr(components, name)
42        if not value:
43            raise ValueError(f"componente de hash vacio: {name!r}")
44        parts.append(f"{name}={value}")
45    return sha256_of("|".join(parts))
classifydef classify() -> DocState
Ver prueba
src/docu/index/freshness.py#L48-L71
48def classify(
49    *,
50    stored_hash: str | None,
51    current_hash: str,
52    generated_at: datetime | None,
53    ttl_days: int = 90,
54    now: datetime | None = None,
55) -> DocState:
56    """Regla unica de estado.
57
58    - sin hash previo            -> STALE (nunca generado)
59    - hash distinto              -> STALE (fuente, vecinos, plantilla o versiones cambiaron)
60    - sin fecha de generacion    -> STALE
61    - TTL vencido                -> EXPIRED
62    - resto                      -> FRESH
63    """
64    if stored_hash is None or generated_at is None:
65        return DocState.STALE
66    if stored_hash != current_hash:
67        return DocState.STALE
68    moment = now or utcnow()
69    if moment - generated_at > timedelta(days=ttl_days):
70        return DocState.EXPIRED
71    return DocState.FRESH
transitiondef transition() -> FreshnessRecord
Ver prueba
src/docu/index/freshness.py#L74-L96
74def transition(
75    *,
76    node_id: str,
77    record: FreshnessRecord | None,
78    current_hash: str,
79    now: datetime | None = None,
80) -> FreshnessRecord:
81    """Devuelve el registro de frescura actualizado sin mutar el anterior."""
82    moment = now or utcnow()
83    state = classify(
84        stored_hash=record.input_hash if record else None,
85        current_hash=current_hash,
86        generated_at=record.generated_at if record else None,
87        ttl_days=record.ttl_days if record else 90,
88        now=moment,
89    )
90    return FreshnessRecord(
91        node_id=node_id,
92        input_hash=current_hash,
93        state=state,
94        generated_at=record.generated_at if record else moment,
95        ttl_days=record.ttl_days if record else 90,
96    )
is_idempotentdef is_idempotent() -> bool
Ver prueba
src/docu/index/freshness.py#L99-L101
99def is_idempotent(*, previous_hash: str | None, current_hash: str) -> bool:
100    """Ejecutar dos veces sobre el mismo commit debe producir diff vacio (Guia-v2.md §1)."""
101    return previous_hash is not None and previous_hash == current_hash
_translatedef _translate(pattern: str) -> re.Pattern[str]
Ver prueba
src/docu/index/ignore.py#L27-L59
27def _translate(pattern: str) -> re.Pattern[str]:
28    """Glob de git → regex. Se soportan `**`, `*`, `?` y clases simples."""
29    out: list[str] = []
30    index = 0
31    size = len(pattern)
32    while index < size:
33        char = pattern[index]
34        if char == "*":
35            if pattern.startswith("**", index):
36                # `**/` abarca cero o más directorios; `**` suelto abarca cualquier cosa.
37                if pattern.startswith("**/", index):
38                    out.append("(?:[^/]+/)*")
39                    index += 3
40                    continue
41                out.append(".*")
42                index += 2
43                continue
44            out.append("[^/]*")
45            index += 1
46            continue
47        if char == "?":
48            out.append("[^/]")
49            index += 1
50            continue
51        if char == "[":
52            closing = pattern.find("]", index)
53            if closing != -1:
54                out.append(pattern[index : closing + 1])
55                index = closing + 1
56                continue
57        out.append(re.escape(char))
58        index += 1
59    return re.compile("^" + "".join(out) + "$")
parsedef parse(text: str) -> list[IgnoreRule]
Ver prueba
src/docu/index/ignore.py#L62-L88
62def parse(text: str) -> list[IgnoreRule]:
63    """Reglas del archivo. Ignora comentarios y líneas vacías, como git."""
64    rules: list[IgnoreRule] = []
65    for line in text.splitlines():
66        stripped = line.strip()
67        if not stripped or stripped.startswith("#"):
68            continue
69        negate = stripped.startswith("!")
70        if negate:
71            stripped = stripped[1:]
72        directory_only = stripped.endswith("/")
73        stripped = stripped.rstrip("/")
74        if not stripped:
75            continue
76        anchored = stripped.startswith("/") or "/" in stripped.rstrip("/")
77        stripped = stripped.lstrip("/")
78        rules.append(
79            IgnoreRule(
80                raw=line.rstrip(),
81                pattern=stripped,
82                negate=negate,
83                directory_only=directory_only,
84                anchored=anchored,
85                regex=_translate(stripped),
86            )
87        )
88    return rules
loaddef load(root: Path | str) -> list[IgnoreRule]
Ver prueba
src/docu/index/ignore.py#L91-L97
91def load(root: Path | str) -> list[IgnoreRule]:
92    """Reglas del `.gitignore` de la raíz, si existe."""
93    path = Path(root) / ".gitignore"
94    try:
95        return parse(path.read_text(encoding="utf-8", errors="replace"))
96    except OSError:
97        return []
is_ignoreddef is_ignored(rel: str, rules: Sequence[IgnoreRule], is_dir: bool=...) -> bool
Ver prueba
src/docu/index/ignore.py#L100-L126
100def is_ignored(rel: str, rules: Sequence[IgnoreRule], is_dir: bool = False) -> bool:
101    """Última regla que aplica gana; `!patrón` vuelve a incluir.
102
103    Candidatos: la ruta completa y cada directorio contenedor (para los patrones anclados o con `/`),
104    más el nombre de cada componente (para los patrones sueltos como `coverage`, que en git ignoran
105    cualquier directorio con ese nombre a cualquier profundidad).
106    """
107    if not rules:
108        return False
109    rel = rel.replace("\\", "/").lstrip("./")
110    parts = rel.split("/")
111    prefixes = ["/".join(parts[: index + 1]) for index in range(len(parts) - 1)]
112    names = [parts[-1], *(prefix.rsplit("/", 1)[-1] for prefix in prefixes)]
113    full_candidates = [rel, *prefixes]
114    ignored = False
115    for rule in rules:
116        candidates = full_candidates if rule.anchored else [*full_candidates, *names]
117        if rule.directory_only:
118            # Patrón de directorio: no aplica al archivo en sí, sólo a sus contenedores.
119            candidates = [item for item in candidates if item != rel]
120            if is_dir:
121                candidates = [rel, *candidates]
122            if not candidates:
123                continue
124        if any(rule.regex.match(candidate) for candidate in candidates):
125            ignored = not rule.negate
126    return ignored
_prefixesdef _prefixes(rel: str) -> list[str]
Ver prueba
src/docu/index/ignore.py#L129-L132
129def _prefixes(rel: str) -> list[str]:
130    """Rutas de los directorios contenedores, de la más cercana a la raíz."""
131    parts = rel.split("/")[:-1]
132    return ["/".join(parts[: index + 1]) for index in range(len(parts))]
DocEntry.to_dictdef to_dict(self) -> dict[str, object]
Ver prueba
src/docu/index/manifest.py#L44-L53
44    def to_dict(self) -> dict[str, object]:
45        return {
46            "level": self.level,
47            "path": self.path,
48            "input_hash": self.input_hash,
49            "generated_at": self.generated_at,
50            "content_hash": self.content_hash,
51            "ttl_days": self.ttl_days,
52            "sources": dict(self.sources),
53        }
DocEntry.from_dictdef from_dict(cls, payload: Mapping[str, object]) -> DocEntry
Ver prueba
src/docu/index/manifest.py#L56-L65
Anotaciones: @classmethod
56    def from_dict(cls, payload: Mapping[str, object]) -> DocEntry:
57        return cls(
58            level=str(payload["level"]),
59            path=str(payload["path"]),
60            input_hash=str(payload["input_hash"]),
61            generated_at=str(payload["generated_at"]),
62            content_hash=str(payload["content_hash"]),
63            ttl_days=int(payload.get("ttl_days", 90)),  # type: ignore[arg-type]
64            sources=dict(payload.get("sources") or {}),  # type: ignore[arg-type]
65        )
DocEntry.generated_at_dtdef generated_at_dt(self) -> datetime
Ver prueba
src/docu/index/manifest.py#L67-L68
67    def generated_at_dt(self) -> datetime:
68        return datetime.fromisoformat(self.generated_at)
Manifest.entrydef entry(self, level: str) -> DocEntry | None
Ver prueba
src/docu/index/manifest.py#L82-L83
82    def entry(self, level: str) -> DocEntry | None:
83        return next((doc for doc in self.docs if doc.level == level), None)
Manifest.upsertdef upsert(self, entry: DocEntry) -> None
Ver prueba
src/docu/index/manifest.py#L85-L86
85    def upsert(self, entry: DocEntry) -> None:
86        self.docs = [doc for doc in self.docs if doc.level != entry.level] + [entry]
Manifest.to_dictdef to_dict(self) -> dict[str, object]
Ver prueba
src/docu/index/manifest.py#L90-L96
90    def to_dict(self) -> dict[str, object]:
91        return {
92            "schema_version": self.schema_version,
93            "project": self.project,
94            "versions": dict(self.versions),
95            "docs": [doc.to_dict() for doc in self.docs],
96        }
Manifest.from_dictdef from_dict(cls, payload: Mapping[str, object]) -> Manifest
Ver prueba
src/docu/index/manifest.py#L99-L105
Anotaciones: @classmethod
99    def from_dict(cls, payload: Mapping[str, object]) -> Manifest:
100        return cls(
101            project=str(payload.get("project", "")),
102            docs=[DocEntry.from_dict(item) for item in payload.get("docs", [])],  # type: ignore[union-attr]
103            versions=dict(payload.get("versions") or DEFAULT_VERSIONS),  # type: ignore[arg-type]
104            schema_version=str(payload.get("schema_version", MANIFEST_VERSION)),
105        )
Manifest.savedef save(self, path: Path | str) -> Path
Ver prueba
src/docu/index/manifest.py#L107-L111
107    def save(self, path: Path | str) -> Path:
108        target = Path(path)
109        target.parent.mkdir(parents=True, exist_ok=True)
110        target.write_text(json.dumps(self.to_dict(), ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
111        return target
Manifest.loaddef load(cls, path: Path | str) -> Manifest | None
Ver prueba
src/docu/index/manifest.py#L114-L124
Anotaciones: @classmethod
114    def load(cls, path: Path | str) -> Manifest | None:
115        target = Path(path)
116        if not target.exists():
117            return None
118        try:
119            payload = json.loads(target.read_text(encoding="utf-8"))
120        except json.JSONDecodeError:
121            return None
122        if not isinstance(payload, dict):
123            return None
124        return cls.from_dict(payload)
input_hash_fordef input_hash_for() -> str
Ver prueba
src/docu/index/manifest.py#L130-L149
130def input_hash_for(
131    *,
132    level: str,
133    sources: Mapping[str, str],
134    fact_signature: str,
135    versions: Mapping[str, str],
136    profile_digest: str,
137) -> str:
138    """Hash de seis entradas para una pagina concreta."""
139    content = sha256_of("|".join(f"{path}:{sha}" for path, sha in sorted(sources.items())))
140    return compute_input_hash(
141        InputComponents(
142            source_content=content,
143            deps_signature=fact_signature or "none",
144            template=f"{level}@{versions.get('renderer', '1')}",
145            embedder=versions.get("embedder", "none"),
146            chunker=versions.get("chunker", "ast-v2"),
147            profile=profile_digest or "default",
148        )
149    )
fact_signaturedef fact_signature(facts: object) -> str
Ver prueba
src/docu/index/manifest.py#L152-L159
152def fact_signature(facts: object) -> str:
153    """Huella de la estructura de dependencias: si cambian los módulos o las deps, cambia."""
154    pairs = sorted(
155        f"{item.kind}:{item.subject}"
156        for item in facts  # type: ignore[union-attr]
157        if getattr(item, "kind", "") in ("module", "dependency", "parent")
158    )
159    return sha256_of("|".join(pairs)) if pairs else "none"
state_ofdef state_of() -> DocState
Ver prueba
src/docu/index/manifest.py#L162-L186
162def state_of(
163    *,
164    entry: DocEntry | None,
165    current_hash: str,
166    now: datetime | None = None,
167    ttl_days: int = 90,
168    file_exists: bool = True,
169) -> DocState:
170    """Estado de la página. Sin entrada en el manifest equivale a `stale`: nunca se ha generado.
171
172    Un hash intacto con el archivo borrado **no** es frescura: es un registro que miente. Se devuelve
173    `MISSING`, distinto de `STALE`, para que el mensaje pueda decir qué hacer: generar de nuevo, no
174    incrementar.
175    """
176    if entry is None:
177        return DocState.STALE
178    if not file_exists:
179        return DocState.MISSING
180    return classify(
181        stored_hash=entry.input_hash,
182        current_hash=current_hash,
183        generated_at=entry.generated_at_dt(),
184        ttl_days=ttl_days,
185        now=now or utcnow(),
186    )
document_existsdef document_exists(entry: DocEntry | None, root: Path) -> bool
Ver prueba
src/docu/index/manifest.py#L189-L196
189def document_exists(entry: DocEntry | None, root: Path) -> bool:
190    """¿Sigue existiendo el archivo que el manifest dice haber generado?"""
191    if entry is None or not entry.path:
192        return False
193    path = Path(entry.path)
194    if not path.is_absolute():
195        path = root / path
196    return path.exists()
profile_digestdef profile_digest(root: Path) -> str
Ver prueba
src/docu/index/manifest.py#L199-L210
199def profile_digest(root: Path) -> str:
200    """Huella del perfil del proyecto, si existe: cambiarlo invalida todo lo generado.
201
202    Se normalizan los finales de línea para que el mismo perfil dé la misma huella en Windows y
203    en Linux; si no, el CI acusaría páginas obsoletas por un `\\r\\n`.
204    """
205    for name in ("docu.profile.yaml", "docu.profile.yml", "docu.profile.json"):
206        candidate = root / name
207        if candidate.exists():
208            text = candidate.read_text(encoding="utf-8").replace("\r\n", "\n").replace("\r", "\n")
209            return sha256_of(text)
210    return "default"
DetectedPackage.file_countdef file_count(self) -> int
Ver prueba
src/docu/index/packages.py#L31-L32
Anotaciones: @property
31    def file_count(self) -> int:
32        return len(self.files)
DetectedPackage.citationdef citation(self) -> str
Ver prueba
src/docu/index/packages.py#L35-L36
Anotaciones: @property
35    def citation(self) -> str:
36        return self.declaration
_python_packagesdef _python_packages(files: Mapping[str, Path]) -> list[DetectedPackage]
Ver prueba
src/docu/index/packages.py#L39-L68
39def _python_packages(files: Mapping[str, Path]) -> list[DetectedPackage]:
40    """Un paquete Python se reconoce por `__init__.py`; el nombre es su ruta sin el prefijo `src/`."""
41    python_files = [rel for rel in files if rel.endswith(".py")]
42    markers = [
43        rel for rel in python_files if rel.rsplit("/", 1)[-1] == "__init__.py"
44    ]
45    packages: list[DetectedPackage] = []
46    for marker in sorted(markers):
47        package_dir = marker.rsplit("/", 1)[0] if "/" in marker else "."
48        prefix = "src/" if package_dir.startswith("src/") else ""
49        name = package_dir[len(prefix) :].replace("/", ".") if package_dir != "." else "."
50        # Miembros **directos**: el paquete no absorbe sus subpaquetes. Si se cuenta recursivo,
51        # `docu` reclama 45 archivos y su diagrama de clases mezcla capas que no le pertenecen.
52        members = tuple(
53            sorted(
54                rel
55                for rel in python_files
56                if (rel.rsplit("/", 1)[0] if "/" in rel else ".") == package_dir
57            )
58        )
59        line_count = _line_count(Path(files[marker]))
60        packages.append(
61            DetectedPackage(
62                name=name,
63                language="python",
64                files=members,
65                declaration=f"{marker}#L1-L{max(1, line_count)}",
66            )
67        )
68    return packages
_java_packagesdef _java_packages(files: Mapping[str, Path]) -> list[DetectedPackage]
Ver prueba
src/docu/index/packages.py#L71-L94
71def _java_packages(files: Mapping[str, Path]) -> list[DetectedPackage]:
72    """En Java el paquete se declara en cada archivo: se agrupa por nombre y se cita el primero."""
73    grouped: dict[str, list[str]] = {}
74    declarations: dict[str, str] = {}
75    for rel in sorted(files):
76        if not rel.endswith(".java"):
77            continue
78        text = _read(files[rel])
79        match = JAVA_PACKAGE_RE.search(text)
80        if match is None:
81            continue
82        name = match.group(1)
83        line = text[: match.start()].count("\n") + 1
84        grouped.setdefault(name, []).append(rel)
85        declarations.setdefault(name, f"{rel}#L{line}-L{line}")
86    return [
87        DetectedPackage(
88            name=name,
89            language="java",
90            files=tuple(sorted(members)),
91            declaration=declarations[name],
92        )
93        for name, members in sorted(grouped.items())
94    ]
_typescript_packagesdef _typescript_packages(files: Mapping[str, Path]) -> list[DetectedPackage]
Ver prueba
src/docu/index/packages.py#L97-L160
97def _typescript_packages(files: Mapping[str, Path]) -> list[DetectedPackage]:
98    """Unidades de TypeScript/JavaScript.
99
100    Dos convenciones, porque el ecosistema no tiene una sola:
101    - **barril**: directorio con `index.ts`/`index.tsx` (lo que declara el paquete);
102    - **directorio**: carpeta con al menos 3 archivos de código y sin barril (React, Express y
103      proyectos Vite agrupan por carpeta: `components`, `hooks`, `api`). Sin esto, un proyecto
104      React aparece con «paquetes: 0» y su arquitectura se pierde.
105    """
106    code_files = {
107        rel: path
108        for rel, path in files.items()
109        if rel.endswith((".ts", ".tsx", ".js", ".jsx"))
110    }
111    packages: list[DetectedPackage] = []
112    barrel_dirs: set[str] = set()
113    for rel in sorted(code_files):
114        if not rel.endswith(("/index.ts", "/index.tsx")):
115            continue
116        package_dir = rel.rsplit("/", 1)[0]
117        barrel_dirs.add(package_dir)
118        members = tuple(
119            sorted(
120                item
121                for item in code_files
122                if (item.rsplit("/", 1)[0] if "/" in item else ".") == package_dir
123            )
124        )
125        line_count = _line_count(Path(code_files[rel]))
126        packages.append(
127            DetectedPackage(
128                name=package_dir.replace("/", "."),
129                language="typescript",
130                files=members,
131                declaration=f"{rel}#L1-L{max(1, line_count)}",
132            )
133        )
134
135    grouped: dict[str, list[str]] = {}
136    for rel in sorted(code_files):
detect_packagesdef detect_packages(files: Mapping[str, Path]) -> tuple[DetectedPackage, ...]
Ver prueba
src/docu/index/packages.py#L163-L166
163def detect_packages(files: Mapping[str, Path]) -> tuple[DetectedPackage, ...]:
164    """Todos los paquetes detectables, sin duplicar lenguajes ni inventar contenedores."""
165    found = [*_python_packages(files), *_java_packages(files), *_typescript_packages(files)]
166    return tuple(sorted(found, key=lambda item: (item.language, item.name)))
_readdef _read(path: Path) -> str
Ver prueba
src/docu/index/packages.py#L169-L173
169def _read(path: Path) -> str:
170    try:
171        return path.read_text(encoding="utf-8", errors="replace")
172    except OSError:
173        return ""
_line_countdef _line_count(path: Path) -> int
Ver prueba
src/docu/index/packages.py#L179-L186
179def _line_count(path: Path) -> int:
180    """Lineas reales del archivo.
181
182    `text.count("\\n") + 1` cuenta una linea fantasma cuando el archivo termina en salto de linea,
183    y eso produce citas `L1-L11` sobre archivos de 10 lineas: un fallo de precisión que invalida la
184    promesa de trazabilidad.
185    """
186    return max(1, len(_read(path).splitlines()))
top_leveldef top_level(packages: Sequence[DetectedPackage]) -> tuple[str, ...]
Ver prueba
src/docu/index/packages.py#L189-L196
189def top_level(packages: Sequence[DetectedPackage]) -> tuple[str, ...]:
190    """Raíces de primer nivel: lo que un lector necesita para orientarse en el proyecto."""
191    roots: list[str] = []
192    for package in packages:
193        head = package.name.split(".")[0]
194        if head and head not in roots:
195            roots.append(head)
196    return tuple(sorted(roots))
PdfDocument.citationdef citation(self) -> str
Ver prueba
src/docu/index/pdfdocs.py#L34-L35
Anotaciones: @property
34    def citation(self) -> str:
35        return f"{self.rel}#p1"
PdfDocument.to_factdef to_fact(self) -> Fact
Ver prueba
src/docu/index/pdfdocs.py#L37-L50
37    def to_fact(self) -> Fact:
38        extra = f" · {'; '.join(self.warnings)}" if self.warnings else ""
39        return Fact(
40            kind="pdf_document",
41            subject=self.rel,
42            detail=f"{self.status} · {self.pages} pág. · {self.chars} caract. · {self.method}{extra}",
43            citation=self.citation,
44            attributes={
45                "pages": str(self.pages),
46                "chars": str(self.chars),
47                "method": self.method,
48                "status": self.status,
49            },
50        )
discover_pdfsdef discover_pdfs(root: Path | str, include: Sequence[str]=..., exclude: Sequence[str]=..., include_tests: bool=..., limit: int=...) -> list[str]
Ver prueba
src/docu/index/pdfdocs.py#L53-L94
53def discover_pdfs(
54    root: Path | str,
55    include: Sequence[str] = (),
56    exclude: Sequence[str] = (),
57    include_tests: bool = False,
58    limit: int = MAX_PDF_FILES,
59) -> list[str]:
60    """PDFs del repositorio, respetando las mismas exclusiones que el resto de la ingesta."""
61    from docu.generate.pipeline import (
62        EXCLUDED_PARTS,
63        _effective_exclude,
64        _is_test_path,
65        _path_matches,
66    )
67    from docu.index.ignore import is_ignored
68    from docu.index.ignore import load as load_ignore
69
70    root_path = Path(root)
71    patterns = _effective_exclude(exclude)
72    rules = load_ignore(root_path)
73    found: list[str] = []
74    for candidate in sorted(root_path.rglob("*")):
75        if not candidate.is_file() or candidate.suffix.lower() != ".pdf":
76            continue
77        rel = candidate.relative_to(root_path)
78        rel_text = rel.as_posix()
79        if any(part in EXCLUDED_PARTS for part in rel.parts):
80            continue
81        if is_ignored(rel_text, rules):
82            continue
83        if patterns and _path_matches(rel_text, patterns):
84            continue
85        if include and not _path_matches(rel_text, include):
86            continue
87        if not include_tests and _is_test_path(rel):
88            continue
89        if candidate.stat().st_size > MAX_PDF_BYTES:
90            continue
91        found.append(rel_text)
92        if len(found) >= limit:
load_documentdef load_document(root: Path | str, rel: str, data: bytes | None=...) -> tuple[PdfDocument, str]
Ver prueba
src/docu/index/pdfdocs.py#L97-L111
97def load_document(root: Path | str, rel: str, data: bytes | None = None) -> tuple[PdfDocument, str]:
98    """Extrae un PDF y devuelve su reporte más el texto por páginas."""
99    root_path = Path(root)
100    payload = data if data is not None else (root_path / rel).read_bytes()
101    result: PdfText = extract(payload)
102    document = PdfDocument(
103        rel=rel,
104        pages=result.total_pages,
105        chars=result.chars,
106        method=result.method,
107        status=result.status,
108        usable=result.usable,
109        warnings=result.warnings,
110    )
111    return document, pages_text(result)
load_alldef load_all(root: Path | str, include: Sequence[str]=..., exclude: Sequence[str]=..., include_tests: bool=..., limit: int=...) -> tuple[list[PdfDocument], dict[str, str], dict[str, str]]
Ver prueba
src/docu/index/pdfdocs.py#L114-L136
114def load_all(
115    root: Path | str,
116    include: Sequence[str] = (),
117    exclude: Sequence[str] = (),
118    include_tests: bool = False,
119    limit: int = MAX_PDF_FILES,
120) -> tuple[list[PdfDocument], dict[str, str], dict[str, str]]:
121    """Documentos, texto por página y huellas para la frescura."""
122    root_path = Path(root)
123    documents: list[PdfDocument] = []
124    texts: dict[str, str] = {}
125    digests: dict[str, str] = {}
126    for rel in discover_pdfs(root_path, include, exclude, include_tests, limit):
127        try:
128            payload = (root_path / rel).read_bytes()
129        except OSError:
130            continue
131        digests[rel] = sha256_of(payload.hex())[:12]
132        document, text = load_document(root_path, rel, payload)
133        documents.append(document)
134        if text:
135            texts[rel] = text
136    return documents, texts, digests
pdf_factsdef pdf_facts(documents: Sequence[PdfDocument]) -> list[Fact]
Ver prueba
src/docu/index/pdfdocs.py#L139-L140
139def pdf_facts(documents: Sequence[PdfDocument]) -> list[Fact]:
140    return [document.to_fact() for document in documents]
write_sidecarsdef write_sidecars(texts: Mapping[str, str], directory: Path) -> list[Path]
Ver prueba
src/docu/index/pdfdocs.py#L143-L154
143def write_sidecars(texts: Mapping[str, str], directory: Path) -> list[Path]:
144    """Escribe el texto extraído junto a la documentación: legible sin herramientas."""
145    written: list[Path] = []
146    if not texts:
147        return written
148    directory.mkdir(parents=True, exist_ok=True)
149    for rel, text in sorted(texts.items()):
150        name = rel.replace("/", "__").removesuffix(".pdf") + ".txt"
151        target = directory / name
152        target.write_text(f"# {rel}\n\n{text}\n", encoding="utf-8")
153        written.append(target)
154    return written
WebDocument.citationdef citation(self) -> str
Ver prueba
src/docu/index/webdocs.py#L29-L30
Anotaciones: @property
29    def citation(self) -> str:
30        return f"{self.rel}#L1-L{max(1, self.lines)}"
WebDocument.to_factdef to_fact(self) -> Fact
Ver prueba
src/docu/index/webdocs.py#L32-L45
32    def to_fact(self) -> Fact:
33        status = "texto congelado" if self.usable else f"no capturada: {self.error or 'sin texto'}"
34        return Fact(
35            kind="web_source",
36            subject=self.url,
37            detail=f"{status} · {self.lines} líneas · {self.chars} caract. · {self.sha[:12]} · {self.captured_at}",
38            citation=self.citation,
39            attributes={
40                "sha": self.sha,
41                "captured_at": self.captured_at,
42                "lines": str(self.lines),
43                "status": status,
44            },
45        )
_index_pathdef _index_path(root: Path) -> Path
Ver prueba
src/docu/index/webdocs.py#L48-L49
48def _index_path(root: Path) -> Path:
49    return root / ".docu" / INDEX_NAME
read_indexdef read_index(root: Path) -> dict[str, dict[str, object]]
Ver prueba
src/docu/index/webdocs.py#L52-L60
52def read_index(root: Path) -> dict[str, dict[str, object]]:
53    path = _index_path(root)
54    if not path.is_file():
55        return {}
56    try:
57        payload = json.loads(path.read_text(encoding="utf-8"))
58    except (OSError, json.JSONDecodeError):
59        return {}
60    return payload if isinstance(payload, dict) else {}
_write_indexdef _write_index(root: Path, entries: Mapping[str, Mapping[str, object]]) -> None
Ver prueba
src/docu/index/webdocs.py#L63-L66
63def _write_index(root: Path, entries: Mapping[str, Mapping[str, object]]) -> None:
64    path = _index_path(root)
65    path.parent.mkdir(parents=True, exist_ok=True)
66    path.write_text(json.dumps(entries, ensure_ascii=False, indent=1), encoding="utf-8")
capture_urlsdef capture_urls(root: Path | str, urls: Sequence[str], allowlist: Sequence[str], docs_dir: Path | str, opener=...) -> tuple[list[WebDocument], list[str]]
Ver prueba
src/docu/index/webdocs.py#L69-L141
69def capture_urls(
70    root: Path | str,
71    urls: Sequence[str],
72    allowlist: Sequence[str],
73    docs_dir: Path | str,
74    opener=None,
75) -> tuple[list[WebDocument], list[str]]:
76    """Captura las URLs permitidas y escribe su texto en `<docs>/web/`.
77
78    Los errores no detienen la corrida: se devuelven como documentos no usables con su motivo, porque
79    una fuente externa caída no debe romper la documentación del repositorio.
80    """
81    root_path = Path(root)
82    target = Path(docs_dir) / SNAPSHOT_DIR
83    index = read_index(root_path)
84    documents: list[WebDocument] = []
85    errors: list[str] = []
86    for url in urls:
87        try:
88            snapshot: Snapshot = capture(url, allowlist, opener=opener)
89        except WebError as error:
90            errors.append(str(error))
91            existing = index.get(url) or {}
92            rel = str(existing.get("rel", ""))
93            if rel and (root_path / rel).is_file():
94                documents.append(
95                    WebDocument(
96                        url=url,
97                        rel=rel,
98                        sha=str(existing.get("sha", "")),
99                        captured_at=str(existing.get("captured_at", "")),
100                        lines=int(existing.get("lines", 0) or 0),
101                        chars=int(existing.get("chars", 0) or 0),
102                        usable=True,
103                        error=str(error),
104                    )
105                )
106            else:
107                documents.append(
108                    WebDocument(url=url, rel="", sha="", captured_at="", lines=0, chars=0, usable=False, error=str(error))
load_documentsdef load_documents(root: Path | str, urls: Iterable[str]=...) -> list[WebDocument]
Ver prueba
src/docu/index/webdocs.py#L144-L181
144def load_documents(root: Path | str, urls: Iterable[str] = ()) -> list[WebDocument]:
145    """Documentos ya congelados: **no toca la red**, así la generación es reproducible."""
146    root_path = Path(root)
147    index = read_index(root_path)
148    wanted = list(urls) or list(index)
149    documents: list[WebDocument] = []
150    for url in wanted:
151        entry = index.get(url)
152        if not entry:
153            documents.append(
154                WebDocument(
155                    url=url,
156                    rel="",
157                    sha="",
158                    captured_at="",
159                    lines=0,
160                    chars=0,
161                    usable=False,
162                    error="sin snapshot: ejecuta `docu web --fetch`",
163                )
164            )
165            continue
166        rel = str(entry.get("rel", ""))
167        path = root_path / rel
168        lines = int(entry.get("lines", 0) or 0)
169        documents.append(
170            WebDocument(
171                url=url,
172                rel=rel,
173                sha=str(entry.get("sha", "")),
174                captured_at=str(entry.get("captured_at", "")),
175                lines=lines,
176                chars=int(entry.get("chars", 0) or 0),
177                usable=path.is_file() and lines > 0,
178                error="" if path.is_file() else "snapshot perdido en disco",
179            )
180        )
181    return documents
web_factsdef web_facts(documents: Sequence[WebDocument]) -> list[Fact]
Ver prueba
src/docu/index/webdocs.py#L184-L185
184def web_facts(documents: Sequence[WebDocument]) -> list[Fact]:
185    return [document.to_fact() for document in documents if document.rel]
check_staledef check_stale(root: Path | str, allowlist: Sequence[str], opener=...) -> list[tuple[str, str]]
Ver prueba
src/docu/index/webdocs.py#L188-L203
188def check_stale(root: Path | str, allowlist: Sequence[str], opener=None) -> list[tuple[str, str]]:
189    """Compara los snapshots con la web actual. Sólo lo llama `--check`: usa red a propósito."""
190    root_path = Path(root)
191    index = read_index(root_path)
192    report: list[tuple[str, str]] = []
193    for url, entry in index.items():
194        try:
195            snapshot = capture(url, allowlist, opener=opener)
196        except WebError as error:
197            report.append((url, f"error: {error}"))
198            continue
199        if snapshot.sha == str(entry.get("sha")):
200            report.append((url, "vigente"))
201        else:
202            report.append((url, "cambió: hay que recapturar"))
203    return report
FederationPayload.to_jsondef to_json(self) -> str
Ver prueba
src/docu/learn/federation.py#L36-L37
36    def to_json(self) -> str:
37        return json.dumps(self.data, ensure_ascii=False, indent=2, sort_keys=True)
fingerprintdef fingerprint(value: str) -> str
Ver prueba
src/docu/learn/federation.py#L40-L42
40def fingerprint(value: str) -> str:
41    """Huella estable y no reversible del identificador del patrón."""
42    return "fp_" + sha256_of(value).replace("sha256:", "")[:16]
build_payloaddef build_payload(library: PatternLibrary) -> FederationPayload
Ver prueba
src/docu/learn/federation.py#L45-L70
45def build_payload(
46    library: PatternLibrary,
47    *,
48    docu_version: str = "0.1.0",
49    limit: int = MAX_PATTERNS,
50) -> FederationPayload:
51    """Construye el payload mínimo: stack, métricas y corridas. Ni un dato del cliente."""
52    patterns = []
53    for pattern in list(library.patterns.values())[:limit]:
54        patterns.append(
55            {
56                "fingerprint": fingerprint(pattern.pattern_id),
57                "stack": pattern.stack,
58                "kind": pattern.kind,
59                "metrics": {name: round(float(value), 3) for name, value in pattern.metrics.items()},
60                "runs": pattern.runs,
61            }
62        )
63    payload = {
64        "schema_version": SCHEMA_VERSION,
65        "generated_at": utcnow().isoformat(timespec="seconds"),
66        "docu_version": docu_version,
67        "patterns": patterns,
68    }
69    assert_anonymous(payload)
70    return FederationPayload(data=payload)
assert_anonymousdef assert_anonymous(payload: Mapping[str, object]) -> None
Ver prueba
src/docu/learn/federation.py#L73-L80
73def assert_anonymous(payload: Mapping[str, object]) -> None:
74    """Comprueba la política. Falla ruidosamente: es mejor no enviar que filtrar."""
75    _check_keys(payload)
76    serialized = json.dumps(payload, ensure_ascii=False)
77    lowered = serialized.lower()
78    for leak in (":\\", "src/", "c:\\", ".java", ".py", ".ts", "http://", "https://", "@"):
79        if leak in lowered:
80            raise FederationError(f"el payload contiene algo que parece una ruta o contacto: {leak!r}")
_check_keysdef _check_keys(node: object) -> None
Ver prueba
src/docu/learn/federation.py#L83-L100
83def _check_keys(node: object) -> None:
84    if isinstance(node, dict):
85        for key, value in node.items():
86            if key not in ALLOWED_KEYS:
87                raise FederationError(f"clave no permitida en el payload: {key!r}")
88            if key == "metrics":
89                # Los nombres de métrica son vocabulario del producto, no datos del cliente;
90                # lo que se exige es que sus valores sean números.
91                if not isinstance(value, dict):
92                    raise FederationError("'metrics' debe ser un mapa de números")
93                for metric_name, metric_value in value.items():
94                    if not isinstance(metric_value, (int, float)) or isinstance(metric_value, bool):
95                        raise FederationError(f"métrica no numérica en el payload: {metric_name!r}")
96                continue
97            _check_keys(value)
98    elif isinstance(node, list):
99        for item in node:
100            _check_keys(item)
previewdef preview(payload: FederationPayload) -> str
Ver prueba
src/docu/learn/federation.py#L103-L105
103def preview(payload: FederationPayload) -> str:
104    """Vista previa obligatoria antes de enviar: lo que el usuario ve es lo que sale."""
105    return payload.to_json()
senddef send(payload: FederationPayload, endpoint: str | None) -> dict[str, object]
Ver prueba
src/docu/learn/federation.py#L108-L137
108def send(
109    payload: FederationPayload,
110    endpoint: str | None,
111    *,
112    dry_run: bool = True,
113    timeout: float = 10.0,
114) -> dict[str, object]:
115    """Envía el payload si hay endpoint y no es dry-run. Sin endpoint, solo devuelve el resumen."""
116    assert_anonymous(payload.data)
117    if dry_run or not endpoint:
118        return {
119            "sent": False,
120            "reason": "dry-run" if dry_run else "sin endpoint configurado",
121            "patterns": len(payload.data.get("patterns") or []),  # type: ignore[arg-type]
122        }
123    if not endpoint.startswith(("http://", "https://")):
124        raise FederationError("el endpoint debe ser http(s)")
125
126    request = urllib.request.Request(
127        endpoint,
128        data=payload.to_json().encode("utf-8"),
129        headers={"Content-Type": "application/json"},
130        method="POST",
131    )
132    try:
133        with urllib.request.urlopen(request, timeout=timeout) as response:
134            status = response.status
135    except (urllib.error.URLError, OSError) as error:
136        return {"sent": False, "reason": f"error de red: {error}"}
137    return {"sent": True, "status": status}
ledger_filedef ledger_file(root: Path | str, explicit: Path | str | None=...) -> Path
Ver prueba
src/docu/learn/ledger.py#L20-L21
20def ledger_file(root: Path | str, explicit: Path | str | None = None) -> Path:
21    return Path(explicit) if explicit else Path(root) / LEDGER_PATH
new_run_iddef new_run_id(now: datetime | None=...) -> str
Ver prueba
src/docu/learn/ledger.py#L24-L26
24def new_run_id(now: datetime | None = None) -> str:
25    moment = now or utcnow()
26    return f"run-{moment.strftime('%Y%m%dT%H%M%S')}-{int(moment.microsecond / 1000):03d}"
appenddef append(path: Path | str) -> RunRecord
Ver prueba
src/docu/learn/ledger.py#L29-L65
29def append(
30    path: Path | str,
31    *,
32    project: str,
33    metrics: Metrics,
34    gate: GateDecision,
35    mode: Mode = Mode.APPLY,
36    states: Mapping[str, str] | None = None,
37    versions: Mapping[str, str] | None = None,
38    pages_written: int = 0,
39    pages_skipped: int = 0,
40    elapsed_s: float = 0.0,
41    commit: str | None = None,
42    errors: Sequence[str] = (),
43) -> RunRecord:
44    """Registra una corrida. Nunca lanza: un ledger roto no puede tumbar la generación."""
45    started = utcnow()
46    record = RunRecord(
47        run_id=new_run_id(started),
48        project=project,
49        commit=commit,
50        mode=mode,
51        started_at=started,
52        finished_at=started,
53        versions={**(versions or {}), "states": ",".join(f"{k}={v}" for k, v in sorted((states or {}).items()))},
54        metrics=metrics,
55        gate=gate,
56        pages_written=pages_written,
57        pages_skipped=pages_skipped,
58        cost_usd=metrics.cost_usd,
59        errors=list(errors),
60    )
61    target = Path(path)
62    target.parent.mkdir(parents=True, exist_ok=True)
63    with target.open("a", encoding="utf-8") as handle:
64        handle.write(record.to_jsonl() + "\n")
65    return record
loaddef load(path: Path | str) -> list[dict[str, object]]
Ver prueba
src/docu/learn/ledger.py#L68-L84
68def load(path: Path | str) -> list[dict[str, object]]:
69    """Lee el ledger tolerando lineas corruptas: se descartan, no se interpretan."""
70    target = Path(path)
71    if not target.exists():
72        return []
73    records: list[dict[str, object]] = []
74    for line in target.read_text(encoding="utf-8").splitlines():
75        text = line.strip()
76        if not text:
77            continue
78        try:
79            payload = json.loads(text)
80        except json.JSONDecodeError:
81            continue
82        if isinstance(payload, dict):
83            records.append(payload)
84    return records
_metricdef _metric(record: Mapping[str, object], name: str) -> float | None
Ver prueba
src/docu/learn/ledger.py#L87-L92
87def _metric(record: Mapping[str, object], name: str) -> float | None:
88    metrics = record.get("metrics")
89    if not isinstance(metrics, dict):
90        return None
91    value = metrics.get(name)
92    return float(value) if isinstance(value, (int, float)) else None
summarizedef summarize(records: Sequence[Mapping[str, object]]) -> dict[str, object]
Ver prueba
src/docu/learn/ledger.py#L95-L125
95def summarize(records: Sequence[Mapping[str, object]]) -> dict[str, object]:
96    """Resumen agregado: corridas, medias por metrica, ultima corrida y tasa de bloqueo."""
97    if not records:
98        return {"runs": 0, "metrics": {}, "aborted": 0, "projects": []}
99
100    names = ("accuracy", "completeness", "attribution", "conciseness", "freshness", "cost_usd")
101    averages: dict[str, float] = {}
102    for name in names:
103        values = [value for record in records if (value := _metric(record, name)) is not None]
104        if values:
105            averages[name] = round(sum(values) / len(values), 3)
106
107    aborted = sum(
108        1
109        for record in records
110        if isinstance(record.get("gate"), dict)
111        and record["gate"].get("outcome") == GateOutcome.ABORT.value  # type: ignore[union-attr]
112    )
113    last = records[-1]
114    return {
115        "runs": len(records),
116        "metrics": averages,
117        "aborted": aborted,
118        "projects": sorted({str(record.get("project")) for record in records if record.get("project")}),
119        "last_run": {
120            "run_id": last.get("run_id"),
121            "project": last.get("project"),
122            "started_at": last.get("started_at"),
123            "outcome": (last.get("gate") or {}).get("outcome") if isinstance(last.get("gate"), dict) else None,
124        },
125    }
outcome_countsdef outcome_counts(records: Iterable[Mapping[str, object]]) -> dict[str, int]
Ver prueba
src/docu/learn/ledger.py#L128-L135
128def outcome_counts(records: Iterable[Mapping[str, object]]) -> dict[str, int]:
129    counts: dict[str, int] = {}
130    for record in records:
131        gate = record.get("gate")
132        outcome = gate.get("outcome") if isinstance(gate, dict) else None
133        key = str(outcome or "desconocido")
134        counts[key] = counts.get(key, 0) + 1
135    return counts
parse_timestampdef parse_timestamp(value: object) -> datetime | None
Ver prueba
src/docu/learn/ledger.py#L138-L145
138def parse_timestamp(value: object) -> datetime | None:
139    if not isinstance(value, str):
140        return None
141    try:
142        parsed = datetime.fromisoformat(value)
143    except ValueError:
144        return None
145    return parsed if parsed.tzinfo else parsed.replace(tzinfo=UTC)
Pattern.to_dictdef to_dict(self) -> dict[str, object]
Ver prueba
src/docu/learn/patterns.py#L35-L43
35    def to_dict(self) -> dict[str, object]:
36        return {
37            "pattern_id": self.pattern_id,
38            "stack": self.stack,
39            "kind": self.kind,
40            "metrics": dict(self.metrics),
41            "runs": self.runs,
42            "notes": self.notes,
43        }
Pattern.from_dictdef from_dict(cls, payload: Mapping[str, object]) -> Pattern
Ver prueba
src/docu/learn/patterns.py#L46-L55
Anotaciones: @classmethod
46    def from_dict(cls, payload: Mapping[str, object]) -> Pattern:
47        metrics = payload.get("metrics") or {}
48        return cls(
49            pattern_id=str(payload.get("pattern_id", "")),
50            stack=str(payload.get("stack", "")),
51            kind=str(payload.get("kind", "profile_default")),
52            metrics={str(key): float(value) for key, value in metrics.items()},  # type: ignore[union-attr]
53            runs=int(payload.get("runs", 0)),  # type: ignore[arg-type]
54            notes=str(payload.get("notes", "")),
55        )
PatternLibrary.to_dictdef to_dict(self) -> dict[str, object]
Ver prueba
src/docu/learn/patterns.py#L67-L73
67    def to_dict(self) -> dict[str, object]:
68        return {
69            "schema_version": self.schema_version,
70            "version": self.version,
71            "patterns": {key: pattern.to_dict() for key, pattern in self.patterns.items()},
72            "history": list(self.history),
73        }
PatternLibrary.from_dictdef from_dict(cls, payload: Mapping[str, object]) -> PatternLibrary
Ver prueba
src/docu/learn/patterns.py#L76-L89
Anotaciones: @classmethod
76    def from_dict(cls, payload: Mapping[str, object]) -> PatternLibrary:
77        raw = payload.get("patterns") or {}
78        patterns = {
79            str(key): Pattern.from_dict(value)  # type: ignore[arg-type]
80            for key, value in raw.items()  # type: ignore[union-attr]
81            if isinstance(value, dict)
82        }
83        history = payload.get("history") or []
84        return cls(
85            patterns=patterns,
86            history=[item for item in history if isinstance(item, dict)],  # type: ignore[union-attr]
87            version=str(payload.get("version", "0")),
88            schema_version=str(payload.get("schema_version", SCHEMA_VERSION)),
89        )
PatternLibrary.savedef save(self, path: Path | str) -> Path
Ver prueba
src/docu/learn/patterns.py#L93-L97
93    def save(self, path: Path | str) -> Path:
94        target = Path(path)
95        target.parent.mkdir(parents=True, exist_ok=True)
96        target.write_text(json.dumps(self.to_dict(), ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
97        return target
PatternLibrary.loaddef load(cls, path: Path | str) -> PatternLibrary
Ver prueba
src/docu/learn/patterns.py#L100-L108
Anotaciones: @classmethod
100    def load(cls, path: Path | str) -> PatternLibrary:
101        target = Path(path)
102        if not target.exists():
103            return cls()
104        try:
105            payload = json.loads(target.read_text(encoding="utf-8"))
106        except json.JSONDecodeError:
107            return cls()
108        return cls.from_dict(payload) if isinstance(payload, dict) else cls()
PatternLibrary.promotedef promote(self, pattern: Pattern) -> None
Ver prueba
src/docu/learn/patterns.py#L112-L125
112    def promote(self, pattern: Pattern) -> None:
113        """Instala un patrón guardando la versión previa para poder revertir."""
114        previous = self.patterns.get(pattern.pattern_id)
115        self.history.append(
116            {
117                "action": "promote",
118                "pattern_id": pattern.pattern_id,
119                "at": utcnow().isoformat(timespec="seconds"),
120                "previous": previous.to_dict() if previous else None,
121                "installed": pattern.to_dict(),
122            }
123        )
124        self.patterns[pattern.pattern_id] = pattern
125        self.version = _next_version(self.version)
PatternLibrary.revertdef revert(self, pattern_id: str) -> bool
Ver prueba
src/docu/learn/patterns.py#L127-L142
127    def revert(self, pattern_id: str) -> bool:
128        """Revierte al estado previo registrado. Devuelve si habia algo que revertir."""
129        for entry in reversed(self.history):
130            if entry.get("pattern_id") != pattern_id or entry.get("action") != "promote":
131                continue
132            previous = entry.get("previous")
133            if isinstance(previous, dict):
134                self.patterns[pattern_id] = Pattern.from_dict(previous)
135            else:
136                self.patterns.pop(pattern_id, None)
137            self.history.append(
138                {"action": "revert", "pattern_id": pattern_id, "at": utcnow().isoformat(timespec="seconds")}
139            )
140            self.version = _next_version(self.version)
141            return True
142        return False
_next_versiondef _next_version(current: str) -> str
Ver prueba
src/docu/learn/patterns.py#L145-L149
145def _next_version(current: str) -> str:
146    try:
147        return str(int(current) + 1)
148    except ValueError:
149        return "1"
Candidate.keydef key(self) -> str
Ver prueba
src/docu/learn/patterns.py#L163-L164
Anotaciones: @property
163    def key(self) -> str:
164        return self.pattern.pattern_id
stack_ofdef stack_of(project: str, records: Sequence[Mapping[str, object]]) -> str
Ver prueba
src/docu/learn/patterns.py#L167-L177
167def stack_of(project: str, records: Sequence[Mapping[str, object]]) -> str:
168    """Heuristica de stack a partir del proyecto y de los lenguajes vistos en sus corridas."""
169    languages = {
170        str(language)
171        for record in records
172        for language in str(record.get("versions", {}).get("languages", "")).split(",")
173        if language
174    }
175    if languages:
176        return "+".join(sorted(languages))
177    return project.split("-")[-1] if "-" in project else project
candidates_fromdef candidates_from(records: Sequence[Mapping[str, object]], min_runs: int=..., improvement: float=...) -> list[Candidate]
Ver prueba
src/docu/learn/patterns.py#L180-L229
180def candidates_from(
181    records: Sequence[Mapping[str, object]],
182    min_runs: int = 1,
183    improvement: float = 0.0,
184) -> list[Candidate]:
185    """Agrupa el ledger por proyecto/stack y propone el rendimiento observado como patrón.
186
187    No inventa: el candidato es literalmente «esta configuración dio estas métricas en estas
188    corridas». La promoción decide si sustituye al patrón vigente.
189    """
190    grouped: dict[str, list[Mapping[str, object]]] = {}
191    for record in records:
192        project = str(record.get("project") or "desconocido")
193        grouped.setdefault(project, []).append(record)
194
195    candidates: list[Candidate] = []
196    for project, group in sorted(grouped.items()):
197        if len(group) < min_runs:
198            continue
199        averages: dict[str, float] = {}
200        for name in WATCHED:
201            values = [
202                float(record["metrics"][name])  # type: ignore[index]
203                for record in group
204                if isinstance(record.get("metrics"), dict) and name in record["metrics"]  # type: ignore[operator]
205            ]
206            if values:
207                averages[name] = round(sum(values) / len(values), 3)
208        if not averages:
209            continue
210        stack = stack_of(project, group)
211        pattern = Pattern(
212            pattern_id=f"{stack}:profile_default",
213            stack=stack,
214            kind="profile_default",
215            metrics=averages,
216            runs=len(group),
217            notes=f"media de {len(group)} corridas en {project}",
218        )
219        candidates.append(
Decision.is_changedef is_change(self) -> bool
Ver prueba
src/docu/learn/promotion.py#L28-L29
Anotaciones: @property
28    def is_change(self) -> bool:
29        return self.action in (PROMOTE, ROLLBACK)
Decision.describedef describe(self) -> str
Ver prueba
src/docu/learn/promotion.py#L31-L33
31    def describe(self) -> str:
32        detail = "; ".join(self.reasons) if self.reasons else "sin detalle"
33        return f"{self.action.upper()} {self.pattern_id} (Δ medio {self.delta:+.3f}): {detail}"
_averagedef _average(metrics: dict[str, float], names: Sequence[str]=...) -> float
Ver prueba
src/docu/learn/promotion.py#L36-L38
36def _average(metrics: dict[str, float], names: Sequence[str] = WATCHED) -> float:
37    values = [metrics.get(name, 0.0) for name in names if name in metrics]
38    return sum(values) / len(values) if values else 0.0
decidedef decide(current: Pattern | None, candidate: Pattern) -> Decision
Ver prueba
src/docu/learn/promotion.py#L41-L89
41def decide(
42    current: Pattern | None,
43    candidate: Pattern,
44    *,
45    promotion_delta: float = 0.05,
46    rollback_drop: float = 0.05,
47) -> Decision:
48    """Compara candidato y vigente. Nunca modifica nada: solo decide y explica por qué."""
49    if current is None:
50        return Decision(
51            action=PROMOTE,
52            pattern_id=candidate.pattern_id,
53            delta=_average(dict(candidate.metrics)),
54            reasons=("no había patrón vigente para este stack",),
55        )
56
57    deltas = {
58        name: round(candidate.metrics.get(name, 0.0) - current.metrics.get(name, 0.0), 3)
59        for name in WATCHED
60        if name in candidate.metrics or name in current.metrics
61    }
62    mean_delta = round(sum(deltas.values()) / len(deltas), 3) if deltas else 0.0
63    drops = {name: value for name, value in deltas.items() if value < -rollback_drop}
64
65    if drops:
66        detail = ", ".join(f"{name} {value:+.3f}" for name, value in sorted(drops.items()))
67        return Decision(
68            action=ROLLBACK,
69            pattern_id=candidate.pattern_id,
70            delta=mean_delta,
71            reasons=(f"degrada {detail} (umbral -{rollback_drop:.2f})",),
72        )
73    if mean_delta >= promotion_delta:
74        beste = max(deltas.items(), key=lambda item: item[1]) if deltas else ("—", 0.0)
75        return Decision(
76            action=PROMOTE,
77            pattern_id=candidate.pattern_id,
78            delta=mean_delta,
79            reasons=(
80                f"mejora media {mean_delta:+.3f} ≥ {promotion_delta:.2f}",
escapedef escape(text: str) -> str
Ver prueba
src/docu/publish/site.py#L130-L131
130def escape(text: str) -> str:
131    return html.escape(text, quote=True)
snippetdef snippet(root: Path, citation: str, limit: int=...) -> str
Ver prueba
src/docu/publish/site.py#L134-L162
134def snippet(root: Path, citation: str, limit: int = SNIPPET_LINES) -> str:
135    """Fragmento real del archivo citado, con números de línea.
136
137    Es la diferencia entre «confía en mí» y «compruébalo»: el tercer escalón de la web no es una
138    descripción de la evidencia, es la evidencia.
139    """
140    path, _, span = citation.partition("#L")
141    if not span:
142        return ""
143    target = root / path
144    if not target.is_file():
145        return ""
146    try:
147        lines = target.read_text(encoding="utf-8", errors="replace").splitlines()
148    except OSError:
149        return ""
150    start_text, _, end_text = span.partition("-L")
151    try:
152        start = max(1, int(start_text))
153        end = min(len(lines), int(end_text or start_text))
154    except ValueError:
155        return ""
156    end = min(end, start + limit - 1)
157    rendered: list[str] = []
158    for number in range(start, end + 1):
159        rendered.append(
160            f'<span class="ln">{number}</span>{escape(lines[number - 1])}'
161        )
162    return "\n".join(rendered)
_celldef _cell(text: str) -> str
Ver prueba
src/docu/publish/site.py#L165-L166
165def _cell(text: str) -> str:
166    return f"<code>{escape(text)}</code>" if text else "—"
_rowdef _row(fact: Fact, root: Path) -> str
Ver prueba
src/docu/publish/site.py#L169-L190
169def _row(fact: Fact, root: Path) -> str:
170    """Una fila: resumen visible + detalle + prueba, en un solo `<details>` anidado."""
171    searchable = " ".join(
172        [fact.kind, fact.subject, fact.detail, fact.citation, *map(str, fact.attributes.values())]
173    ).lower()
174    annotations = fact.attributes.get("annotations", "")
175    extra = ""
176    if annotations and annotations != "—":
177        extra = f'<div class="cite">Anotaciones: {_cell(annotations)}</div>'
178    code = snippet(root, fact.citation)
179    proof = (
180        f"<pre>{code}</pre>" if code else '<div class="empty">Sin fragmento disponible.</div>'
181    )
182    return (
183        f'<tr data-search="{escape(searchable)}">'
184        f"<td><code>{escape(fact.subject)}</code></td>"
185        f"<td>{_cell(fact.detail)}</td>"
186        f"<td><details><summary>Ver prueba</summary>"
187        f'<div class="cite">{_cell(fact.citation)}</div>{extra}{proof}'
188        f"</details></td>"
189        f"</tr>"
190    )
_sectiondef _section(anchor: str, title: str, facts: Sequence[Fact], root: Path) -> str
Ver prueba
src/docu/publish/site.py#L193-L211
193def _section(
194    anchor: str,
195    title: str,
196    facts: Sequence[Fact],
197    root: Path,
198) -> str:
199    if not facts:
200        return (
201            f'<section id="{anchor}"><h2>{escape(title)}</h2>'
202            '<div class="empty">Sin evidencia disponible: esta sección no se documenta y no se '
203            "rellena con texto plausible.</div></section>"
204        )
205    body = "\n".join(_row(fact, root) for fact in facts)
206    return (
207        f'<section id="{anchor}"><h2>{escape(title)} '
208        f'<span class="badge">{len(facts)}</span></h2>'
209        "<table><thead><tr><th>Qué</th><th>Detalle</th><th>Evidencia</th></tr></thead>"
210        f"<tbody>{body}</tbody></table></section>"
211    )
_shelldef _shell(title: str, project: str, body: str, meta: Mapping[str, str], anchors: Sequence[tuple[str, str]]=...) -> str
Ver prueba
src/docu/publish/site.py#L214-L249
214def _shell(
215    title: str,
216    project: str,
217    body: str,
218    meta: Mapping[str, str],
219    anchors: Sequence[tuple[str, str]] = (),
220) -> str:
221    links = " ".join(f'<a href="#{anchor}">{escape(label)}</a>' for anchor, label in anchors)
222    return f"""<!doctype html>
223<html lang="es">
224<head>
225<meta charset="utf-8">
226<meta name="viewport" content="width=device-width, initial-scale=1">
227<title>{escape(title)} · {escape(project)}</title>
228<link rel="stylesheet" href="assets/site.css">
229</head>
230<body>
231<header><div class="row">
232<h1><a href="index.html">{escape(project)}</a> · {escape(title)}</h1>
233<nav>{links}</nav>
234<input type="search" id="q" placeholder="Buscar en el documento…" aria-label="Buscar">
235<button id="expand" type="button">Expandir todo</button>
236</div></header>
237<main>
238{body}
239<footer>
240Generado por docu {escape(meta.get('version', '0.1.0'))} · {escape(meta.get('facts', '0'))} afirmaciones
241· {escape(meta.get('unsupported', '0'))} sin cita · fuente <code>{escape(meta.get('digest', '—'))}</code>.
242<strong>Control del contenido:</strong> sólo se publica lo que tiene cita verificable; la profundidad
243la elige quien lee.
244</footer>
245</main>
246<script src="assets/site.js"></script>
247</body>
248</html>
249"""
parse_flowchartdef parse_flowchart(text: str) -> tuple[list[tuple[str, str]], list[tuple[str, str]]]
Ver prueba
src/docu/publish/site.py#L252-L272
252def parse_flowchart(text: str) -> tuple[list[tuple[str, str]], list[tuple[str, str]]]:
253    """Lee el Mermaid que generamos (`flowchart LR`, `id["label"]`, `a --> b`).
254
255    Se parsea nuestro propio formato a propósito: así la web comparte la misma evidencia que el
256    documento en vez de mantener una segunda fuente de verdad.
257    """
258    nodes: list[tuple[str, str]] = []
259    edges: list[tuple[str, str]] = []
260    for line in text.splitlines():
261        stripped = line.strip()
262        if not stripped or stripped.startswith(("flowchart", "%%")):
263            continue
264        if "-->" in stripped:
265            left, _, right = stripped.partition("-->")
266            edges.append((left.strip(), right.strip()))
267            continue
268        if '["' in stripped and stripped.endswith("]"):
269            node, _, rest = stripped.partition('["')
270            label = rest.rsplit('"]', 1)[0]
271            nodes.append((node.strip(), label.replace("<br/>", " · ")))
272    return nodes, edges
svg_architecturedef svg_architecture(text: str, max_nodes: int=...) -> str | None
Ver prueba
src/docu/publish/site.py#L275-L331
275def svg_architecture(text: str, max_nodes: int = 24) -> str | None:
276    """SVG del grafo de paquetes: columnas por profundidad, sin JavaScript ni CDN.
277
278    Un diagrama que necesita red para verse no sirve en una revisión offline ni en un PDF; y uno que
279    necesita un motor de JS para existir no se puede auditar. Este se genera del mismo grafo.
280    """
281    nodes, edges = parse_flowchart(text)
282    if not nodes or len(nodes) > max_nodes:
283        return None
284    order = [name for name, _ in nodes]
285    depth: dict[str, int] = {name: 0 for name in order}
286    for _ in range(len(order)):  # relajación acotada: el grafo es pequeño y puede tener ciclos
287        changed = False
288        for source, target in edges:
289            if source in depth and target in depth and depth[target] < depth[source] + 1:
290                depth[target] = depth[source] + 1
291                changed = True
292        if not changed:
293            break
294    columns: dict[int, list[str]] = {}
295    for name in order:
296        columns.setdefault(depth[name], []).append(name)
297    column_width, row_height, margin = 210, 46, 24
298    positions: dict[str, tuple[int, int]] = {}
299    for column, names in sorted(columns.items()):
300        for row, name in enumerate(names):
301            positions[name] = (margin + column * column_width, margin + row * row_height)
302    width = margin * 2 + (max(columns) + 1) * column_width
303    height = margin * 2 + max(len(names) for names in columns.values()) * row_height
304    parts = [
305        (f'<svg viewBox="0 0 {width} {height}" width="100%" role="img" '
306        f'aria-label="Dependencias entre paquetes" xmlns="http://www.w3.org/2000/svg">'),
307        ('<defs><marker id="a" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" '
308        'markerHeight="6" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#6ea8fe"/></marker></defs>'),
309    ]
310    for source, target in edges:
311        if source not in positions or target not in positions:
312            continue
313        x1, y1 = positions[source]
314        x2, y2 = positions[target]
parse_erddef parse_erd(text: str) -> tuple[dict[str, list[tuple[str, str]]], list[tuple[str, str, str, str]]]
Ver prueba
src/docu/publish/site.py#L340-L366
340def parse_erd(text: str) -> tuple[dict[str, list[tuple[str, str]]], list[tuple[str, str, str, str]]]:
341    """Lee el `erDiagram` que generamos: entidades con campos y relaciones etiquetadas."""
342    entities: dict[str, list[tuple[str, str]]] = {}
343    relations: list[tuple[str, str, str, str]] = []
344    current: str | None = None
345    for line in text.splitlines():
346        stripped = line.strip()
347        if not stripped or stripped.startswith("erDiagram"):
348            continue
349        if stripped.endswith("{") and current is None:
350            current = stripped[:-1].strip()
351            entities.setdefault(current, [])
352            continue
353        if stripped == "}":
354            current = None
355            continue
356        if current is not None:
357            parts = stripped.split()
358            if len(parts) >= 2:
359                entities[current].append((parts[0], parts[1]))
360            continue
361        match = _ERD_RELATION_RE.search(stripped)
362        if match:
363            relations.append(
364                (match.group("left"), match.group("card"), match.group("right"), match.group("label"))
365            )
366    return entities, relations
svg_erddef svg_erd(text: str, max_entities: int=..., max_fields: int=..., columns: int=...) -> tuple[str | None, str]
Ver prueba
src/docu/publish/site.py#L369-L474
369def svg_erd(
370    text: str, max_entities: int = 12, max_fields: int = 7, columns: int = 3
371) -> tuple[str | None, str]:
372    """ERD en SVG: entidades como cajas con sus campos y relaciones con su cardinalidad.
373
374    Se recorta a las entidades con más campos y **se dice cuántas quedaron fuera**: un diagrama que
375    omite en silencio es peor que no tenerlo.
376    """
377    entities, relations = parse_erd(text)
378    if not entities:
379        return None, ""
380    degree: dict[str, int] = {}
381    for left, _, right, _ in relations:
382        degree[left] = degree.get(left, 0) + 1
383        degree[right] = degree.get(right, 0) + 1
384    # Primero las entidades que **se relacionan** y después las que más campos tienen: un ERD de
385    # interfaces de props con 817 campos y ninguna arista no explica el modelo de datos.
386    ranked = sorted(
387        entities,
388        key=lambda name: (-degree.get(name, 0), -len(entities[name]), name),
389    )
390    chosen = ranked[:max_entities]
391    if not chosen:
392        return None, ""
393    # Se incorporan socios de relación antes que entidades sueltas: un ERD sin aristas no explica
394    # nada, y el recorte por «más campos» deja fuera justo las entidades que se referencian.
395    limit = max_entities + 4
396    for name in ranked:
397        if len(chosen) >= limit:
398            break
399        if name in chosen:
400            continue
401        if any(
402            (left == name and right in chosen) or (right == name and left in chosen)
403            for left, _, right, _ in relations
404        ):
405            chosen.append(name)
406    chosen_set = set(chosen)
407    kept = [item for item in relations if item[0] in chosen_set and item[2] in chosen_set]
408
svg_api_flowdef svg_api_flow(text: str, max_routes: int=...) -> tuple[str | None, str]
Ver prueba
src/docu/publish/site.py#L477-L533
477def svg_api_flow(text: str, max_routes: int = 12) -> tuple[str | None, str]:
478    """Flujo de la API en SVG: cliente → rutas → controlador, en tres columnas."""
479    nodes, edges = parse_flowchart(text)
480    if not nodes:
481        return None, ""
482    labels = dict(nodes)
483    routes = [name for name in labels if name.startswith("r") and labels[name] not in ("Cliente",)]
484    routes = sorted(routes, key=lambda name: int(name[1:]) if name[1:].isdigit() else 0)
485    [name for name in labels if name.startswith("h")]
486    if not routes:
487        return None, ""
488    kept = routes[:max_routes]
489    kept_set = set(kept)
490    linked_handlers = {
491        target for source, target in edges if source in kept_set and target in labels
492    }
493    column_x = {0: 24, 1: 330, 2: 700}
494    width, row, margin, box_height = 980, 38, 24, 26
495    positions: dict[str, tuple[int, int]] = {"cliente": (column_x[0], margin + 40)}
496    for index, name in enumerate(kept):
497        positions[name] = (column_x[1], margin + index * row)
498    for index, name in enumerate(sorted(linked_handlers)):
499        positions[name] = (column_x[2], margin + index * row)
500    height = max(margin + 80, margin + max(len(kept), len(linked_handlers)) * row + margin)
501    parts = [
502        (f'<svg viewBox="0 0 {width} {height}" width="100%" role="img" '
503        'aria-label="Flujo de la API" xmlns="http://www.w3.org/2000/svg">'),
504        ('<defs><marker id="f" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" '
505        'markerHeight="6" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#6ea8fe"/></marker></defs>'),
506    ]
507    for source, target in edges:
508        if source not in positions or target not in positions:
509            continue
510        x1, y1 = positions[source]
511        x2, y2 = positions[target]
512        parts.append(
513            f'<line x1="{x1 + 150}" y1="{y1 + 13}" x2="{x2}" y2="{y2 + 13}" '
514            'stroke="#3a465c" stroke-width="1" marker-end="url(#f)"/>'
515        )
516    for name, (x, y) in positions.items():
_diagrams_sectiondef _diagrams_section(diagrams: Path, root: Path) -> str
Ver prueba
src/docu/publish/site.py#L536-L581
536def _diagrams_section(diagrams: Path, root: Path) -> str:
537    """Diagramas ya generados junto a la documentación: SVG propio + código Mermaid copiable.
538
539    Se dibujan los tres que un lector usa para orientarse (arquitectura, modelo de datos y flujo de
540    API). Los de clases se dejan como código: su layout se beneficia de un motor de grafos y la
541    información ya está en «Tipos» y en el diccionario de datos.
542    """
543    if not diagrams.is_dir():
544        return ""
545    blocks: list[str] = []
546    for path in sorted(diagrams.glob("*.mmd")):
547        text = path.read_text(encoding="utf-8")
548        visual: str | None = None
549        note = ""
550        if path.stem == "arquitectura":
551            visual = svg_architecture(text)
552        elif path.stem == "modelo-de-datos":
553            visual, note = svg_erd(text)
554        elif path.stem == "api-flujo":
555            visual, note = svg_api_flow(text)
556        title = path.stem.replace("-", " ").replace("_", ".")
557        block = [f"<h3>{escape(title)}</h3>"]
558        if visual:
559            block.append(f'<div class="card">{visual}</div>')
560            if note:
561                block.append(
562                    f'<p class="cite">Recorte explícito: {escape(note)}. '
563                    "El diagrama no omite en silencio.</p>"
564                )
565        block.append(
566            '<details><summary>Ver código Mermaid</summary>'
567            f"<pre>{escape(text)}</pre></details>"
568        )
569        blocks.append("\n".join(block))
570    if not blocks:
571        return ""
572    drawn = sum(1 for block in blocks if "<svg" in block)
573    return (
574        '<section id="diagramas"><h2>Diagramas '
575        f'<span class="badge">{len(blocks)}</span></h2>'
build_sitedef build_site(root: Path | str, out_dir: Path | str, project: str, facts: Sequence[Fact], meta: Mapping[str, str] | None=..., levels: Sequence[str]=..., diagrams_dir: Path | str | None=...) -> tuple[Page, ...]
Ver prueba
src/docu/publish/site.py#L584-L652
584def build_site(
585    root: Path | str,
586    out_dir: Path | str,
587    project: str,
588    facts: Sequence[Fact],
589    meta: Mapping[str, str] | None = None,
590    levels: Sequence[str] = ("l1", "l2", "l4"),
591    diagrams_dir: Path | str | None = None,
592) -> tuple[Page, ...]:
593    """Escribe la web y devuelve las páginas generadas."""
594    root_path = Path(root).resolve()
595    target = Path(out_dir)
596    diagrams = Path(diagrams_dir) if diagrams_dir else target / "diagrams"
597    assets = target / "assets"
598    assets.mkdir(parents=True, exist_ok=True)
599    (assets / "site.css").write_text(CSS, encoding="utf-8")
600    (assets / "site.js").write_text(JS, encoding="utf-8")
601
602    meta = dict(meta or {})
603    counts = {}
604    for fact in facts:
605        counts[fact.kind] = counts.get(fact.kind, 0) + 1
606    meta.setdefault("facts", str(len(facts)))
607
608    pages: list[Page] = []
609    for level in levels:
610        wanted = LEVEL_SECTIONS.get(level, tuple(anchor for anchor, _, _ in SECTIONS))
611        body: list[str] = []
612        anchors: list[tuple[str, str]] = []
613        for anchor, title, kinds in SECTIONS:
614            if anchor not in wanted:
615                continue
616            selected = [fact for fact in facts if fact.kind in kinds]
617            anchors.append((anchor, title))
618            body.append(_section(anchor, title, _dedupe(selected), root_path))
619        if level == "l1":
620            diagram_section = _diagrams_section(diagrams, root_path)
621            if diagram_section:
622                anchors.append(("diagramas", "Diagramas"))
623                body.append(diagram_section)
_dedupedef _dedupe(facts: Sequence[Fact]) -> list[Fact]
Ver prueba
src/docu/publish/site.py#L655-L664
655def _dedupe(facts: Sequence[Fact]) -> list[Fact]:
656    seen: set[tuple[str, str, str]] = set()
657    out: list[Fact] = []
658    for fact in facts:
659        key = (fact.kind, fact.subject, fact.citation)
660        if key in seen:
661            continue
662        seen.add(key)
663        out.append(fact)
664    return out
_index_bodydef _index_body(project: str, facts: Sequence[Fact], counts: Mapping[str, int], meta: Mapping[str, str], levels: Sequence[str]) -> str
Ver prueba
src/docu/publish/site.py#L667-L712
667def _index_body(
668    project: str,
669    facts: Sequence[Fact],
670    counts: Mapping[str, int],
671    meta: Mapping[str, str],
672    levels: Sequence[str],
673) -> str:
674    cards = "\n".join(
675        f'<div class="card"><div class="n">{count}</div><div class="l">{escape(label)}</div></div>'
676        for label, count in (
677            ("afirmaciones", len(facts)),
678            ("con cita verificable", len(facts) - int(meta.get("unsupported", "0") or 0)),
679            ("tipos documentados", counts.get("type", 0)),
680            ("campos de datos", counts.get("field", 0)),
681            ("rutas HTTP", counts.get("route", 0)),
682        )
683    )
684    level_links = "\n".join(
685        f'<li><a href="{level}.html">Nivel {level[1]}</a> — '
686        + {
687            "l1": "manual técnico: arquitectura, API, configuración, modelo de datos",
688            "l2": "operación y despliegue: entorno, puertos, artefactos, CI",
689            "l3": "guía de uso para quien no programa",
690            "l4": "onboarding: lo mínimo para arrancar",
691        }.get(level, "")
692        + "</li>"
693        for level in levels
694    )
695    return f"""
696<p class="lead">Documentación de <strong>{escape(project)}</strong>. Cada afirmación se puede abrir
697hasta el fragmento exacto del código que la sostiene: el contenido está controlado, la profundidad la
698elige quien lee.</p>
699<div class="grid">{cards}</div>
700<h2>Cómo leer esto</h2>
701<table><thead><tr><th>Escalón</th><th>Qué ves</th><th>Para qué</th></tr></thead><tbody>
702<tr><td>1. Resumen</td><td>la fila: qué es y de qué tipo</td><td>orientarte rápido</td></tr>
703<tr><td>2. Detalle</td><td>firma, anotaciones, valor declarado</td><td>trabajar con el dato</td></tr>
704<tr><td>3. Prueba</td><td>la cita y el código real con números de línea</td><td>verificar sin creer</td></tr>
705</tbody></table>
706<h2>Documentos</h2>
folddef fold(text: str) -> str
Ver prueba
src/docu/retrieve/glossary.py#L62-L64
62def fold(text: str) -> str:
63    """Sin diacriticos: `expiracion` y `expiración` son el mismo termino."""
64    return "".join(c for c in unicodedata.normalize("NFD", text) if not unicodedata.combining(c))
mergedef merge(*glossaries) -> dict[str, tuple[str, ...]]
Ver prueba
src/docu/retrieve/glossary.py#L67-L74
67def merge(*glossaries: Mapping[str, Sequence[str]]) -> dict[str, tuple[str, ...]]:
68    """Combina el glosario por defecto con el del perfil, sin perder terminos."""
69    merged: dict[str, tuple[str, ...]] = {}
70    for glossary in glossaries:
71        for phrase, terms in glossary.items():
72            existing = merged.get(phrase, ())
73            merged[phrase] = tuple(dict.fromkeys((*existing, *terms)))
74    return merged
expanddef expand(query: str, glossary: Mapping[str, Sequence[str]] | None=...) -> str
Ver prueba
src/docu/retrieve/glossary.py#L77-L94
77def expand(
78    query: str, glossary: Mapping[str, Sequence[str]] | None = None
79) -> str:
80    """Anade a la consulta los terminos de codigo asociados a sus frases conocidas.
81
82    Coincidencia por frase completa con limites de palabra: `cors` no debe expandir dentro de
83    `corsario`. Si no hay coincidencias, devuelve la consulta intacta (y el coste es un scan).
84    """
85    table = DEFAULT_GLOSSARY if glossary is None else glossary
86    folded = fold(query).lower()
87    extras: list[str] = []
88    for phrase, terms in table.items():
89        pattern = r"(?<![\w])" + re.escape(phrase) + r"(?![\w])"
90        if re.search(pattern, folded):
91            extras.extend(terms)
92    if not extras:
93        return query
94    return query + " " + " ".join(dict.fromkeys(extras))
CodeChunk.citationdef citation(self) -> str
Ver prueba
src/docu/retrieve/hybrid.py#L46-L47
Anotaciones: @property
46    def citation(self) -> str:
47        return f"{self.path}#L{self.start}-L{self.end}"
CodeChunk.to_dictdef to_dict(self, score: float) -> dict[str, object]
Ver prueba
src/docu/retrieve/hybrid.py#L49-L59
49    def to_dict(self, score: float) -> dict[str, object]:
50        return {
51            "citation": self.citation,
52            "path": self.path,
53            "start": self.start,
54            "end": self.end,
55            "symbol": self.symbol,
56            "kind": self.kind,
57            "score": round(score, 4),
58            "excerpt": self.text[:1200],
59        }
_exact_namesdef _exact_names(qualname: str | None) -> tuple[str, ...]
Ver prueba
src/docu/retrieve/hybrid.py#L62-L67
62def _exact_names(qualname: str | None) -> tuple[str, ...]:
63    if not qualname:
64        return ()
65    names = [qualname.lower()]
66    names.extend(part.lower() for part in qualname.replace(".", " ").split())
67    return tuple(dict.fromkeys(names))
build_chunksdef build_chunks(root: Path | str, include: Sequence[str]=..., exclude: Sequence[str]=..., include_tests: bool=...) -> list[CodeChunk]
Ver prueba
src/docu/retrieve/hybrid.py#L70-L109
70def build_chunks(
71    root: Path | str,
72    include: Sequence[str] = (),
73    exclude: Sequence[str] = (),
74    include_tests: bool = False,
75) -> list[CodeChunk]:
76    """Chunks sintácticos de todos los archivos de código soportados en el proyecto."""
77    root_path = Path(root)
78    chunker = SymbolChunker()
79    chunks: list[CodeChunk] = []
80    for rel, path in _discover(
81        root_path, include_tests=include_tests, include=include, exclude=exclude
82    ).items():
83        adapter = adapter_for(rel)
84        if adapter is None:
85            continue
86        source = _read(path)
87        artifact = Artifact(
88            artifact_id=f"{root_path.name}:{rel}",
89            kind=SourceKind.GIT_REPOSITORY,
90            uri=rel,
91            content_hash=sha256_of(source.encode("utf-8")),
92            captured_at=utcnow(),
93            lang=str(adapter.language),  # type: ignore[attr-defined]
94        )
95        for chunk in chunker.chunk(artifact, adapter.symbols(rel, source), source):  # type: ignore[attr-defined]
96            text = f"{chunk.content_prefix}\n{chunk.content}"
97            chunks.append(
98                CodeChunk(
99                    path=chunk.file_path,
100                    start=chunk.line_start,
101                    end=chunk.line_end,
102                    text=text,
103                    symbol=chunk.enclosing_symbol,
104                    kind=chunk.symbol_kind.value,
105                    tokens=tuple(tokenize(text)),
106                    exact_names=_exact_names(chunk.enclosing_symbol),
107                )
108            )
109    return chunks
CodeIndex.__post_init__def __post_init__(self) -> None
Ver prueba
src/docu/retrieve/hybrid.py#L128-L135
128    def __post_init__(self) -> None:
129        self._lengths = [len(chunk.tokens) for chunk in self.chunks]
130        for chunk in self.chunks:
131            for term in set(chunk.tokens):
132                self._df[term] = self._df.get(term, 0) + 1
133            for name in chunk.exact_names:
134                self._by_name.setdefault(name, []).append(chunk)
135        self._avgdl = (sum(self._lengths) / len(self._lengths)) if self._lengths else 0.0
CodeIndex.dense_availabledef dense_available(self) -> bool
Ver prueba
src/docu/retrieve/hybrid.py#L140-L141
Anotaciones: @property
140    def dense_available(self) -> bool:
141        return self.embedder is not None
CodeIndex.capabilitiesdef capabilities(self) -> dict[str, object]
Ver prueba
src/docu/retrieve/hybrid.py#L143-L153
143    def capabilities(self) -> dict[str, object]:
144        return {
145            "chunks": len(self.chunks),
146            "channels": ["lexical", "symbol"] + (["dense"] if self.dense_available else []),
147            "dense": self.dense_available,
148            # Un degradado silencioso parece un problema de calidad de la búsqueda: se explica.
149            "dense_reason": ""
150            if self.dense_available
151            else "modelo ONNX no descargado (docu no lo incluye: 113 MB); se usan léxico y símbolo",
152            "files_indexed": len({chunk.path for chunk in self.chunks}),
153        }
CodeIndex._idfdef _idf(self, term: str) -> float
Ver prueba
src/docu/retrieve/hybrid.py#L157-L160
157    def _idf(self, term: str) -> float:
158        total = len(self.chunks)
159        df = self._df.get(term, 0)
160        return math.log(1 + (total - df + 0.5) / (df + 0.5))
CodeIndex._lexicaldef _lexical(self, terms: set[str], limit: int) -> list[CodeChunk]
Ver prueba
src/docu/retrieve/hybrid.py#L162-L179
162    def _lexical(self, terms: set[str], limit: int) -> list[CodeChunk]:
163        scored: list[tuple[CodeChunk, float]] = []
164        for chunk, length in zip(self.chunks, self._lengths):
165            counts: dict[str, int] = {}
166            for token in chunk.tokens:
167                if token in terms:
168                    counts[token] = counts.get(token, 0) + 1
169            if not counts:
170                continue
171            score = 0.0
172            for term, frequency in counts.items():
173                denominator = frequency + self.k1 * (
174                    1 - self.b + self.b * (length / self._avgdl if self._avgdl else 1.0)
175                )
176                score += self._idf(term) * (frequency * (self.k1 + 1)) / denominator
177            scored.append((chunk, score))
178        scored.sort(key=lambda item: item[1], reverse=True)
179        return [chunk for chunk, _score in scored[:limit]]
CodeIndex._structuraldef _structural(self, terms: set[str]) -> list[CodeChunk]
Ver prueba
src/docu/retrieve/hybrid.py#L181-L193
181    def _structural(self, terms: set[str]) -> list[CodeChunk]:
182        hits: list[CodeChunk] = []
183        seen: set[str] = set()
184        per_file: dict[str, int] = {}
185        for term in sorted(terms):
186            for chunk in self._by_name.get(term, ()):
187                key = chunk.citation
188                if key in seen or per_file.get(chunk.path, 0) >= MAX_PER_FILE:
189                    continue
190                seen.add(key)
191                per_file[chunk.path] = per_file.get(chunk.path, 0) + 1
192                hits.append(chunk)
193        return hits
CodeIndex._densedef _dense(self, query: str, limit: int) -> list[CodeChunk]
Ver prueba
src/docu/retrieve/hybrid.py#L195-L213
195    def _dense(self, query: str, limit: int) -> list[CodeChunk]:
196        if self.embedder is None:
197            return []
198        from docu.adapters.embedders.onnx_local import cosine
199
200        if not self._dense_ready:
201            sample = self.chunks[:DENSE_CHUNK_LIMIT]
202            vectors = list(self.embedder.embed([chunk.text for chunk in sample]))  # type: ignore[attr-defined]
203            self._vectors = vectors
204            self._dense_ready = True
205        if not self._vectors:
206            return []
207        query_vector = self.embedder.embed([query])[0]  # type: ignore[attr-defined]
208        scored = [
209            (chunk, cosine(query_vector, vector))
210            for chunk, vector in zip(self.chunks[:DENSE_CHUNK_LIMIT], self._vectors)
211        ]
212        scored.sort(key=lambda item: item[1], reverse=True)
213        return [chunk for chunk, _score in scored[:limit]]
CodeIndex.searchdef search(self, query: str, limit: int=..., expand_query: bool=...) -> list[tuple[CodeChunk, float]]
Ver prueba
src/docu/retrieve/hybrid.py#L217-L253
217    def search(self, query: str, limit: int = 10, expand_query: bool = True) -> list[tuple[CodeChunk, float]]:
218        """Fusiona los canales con RRF y aplica diversidad por archivo."""
219        if not self.chunks:
220            return []
221        text = expand(query, self.glossary) if expand_query else query
222        terms = set(tokenize(text))
223        if not terms:
224            return []
225        window = max(limit * 5, 50)
226        identifier_like = looks_like_identifier(query)
227        channels: list[tuple[float, list[CodeChunk]]] = [
228            (1.0, self._lexical(terms, window)),
229            (1.0 if identifier_like else 0.6, self._structural(terms)),
230        ]
231        dense = self._dense(text, window)
232        if dense:
233            channels.append((0.5 if identifier_like else 1.0, dense))
234
235        fused: dict[str, float] = {}
236        by_key: dict[str, CodeChunk] = {}
237        for weight, channel in channels:
238            for rank, chunk in enumerate(channel, start=1):
239                by_key[chunk.citation] = chunk
240                fused[chunk.citation] = fused.get(chunk.citation, 0.0) + weight / (RRF_K + rank)
241
242        ordered = sorted(fused.items(), key=lambda item: item[1], reverse=True)
243        results: list[tuple[CodeChunk, float]] = []
244        per_file: dict[str, int] = {}
245        for citation, score in ordered:
246            chunk = by_key[citation]
247            if per_file.get(chunk.path, 0) >= MAX_PER_FILE:
248                continue
249            per_file[chunk.path] = per_file.get(chunk.path, 0) + 1
250            results.append((chunk, score))
251            if len(results) >= limit:
252                break
253        return results
build_indexdef build_index(root: Path | str) -> CodeIndex
Ver prueba
src/docu/retrieve/hybrid.py#L256-L277
256def build_index(
257    root: Path | str,
258    *,
259    include: Sequence[str] = (),
260    exclude: Sequence[str] = (),
261    include_tests: bool = False,
262    model_dir: Path | str | None = None,
263    dense: bool = True,
264    glossary: Mapping[str, Sequence[str]] | None = None,
265) -> CodeIndex:
266    """Construye el índice, con canal denso solo si el modelo está disponible."""
267    chunks = build_chunks(root, include=include, exclude=exclude, include_tests=include_tests)
268    embedder = None
269    if dense:
270        from docu.adapters.embedders.onnx_local import OnnxEmbedder, resolve_model_dir
271
272        directory = Path(model_dir) if model_dir else resolve_model_dir(root)
273        if directory is not None:
274            candidate = OnnxEmbedder(model_dir=directory)
275            if candidate.available:
276                embedder = candidate
277    return CodeIndex(chunks=chunks, embedder=embedder, glossary=glossary)
tokenizedef tokenize(text: str) -> list[str]
Ver prueba
src/docu/retrieve/search.py#L27-L41
27def tokenize(text: str) -> list[str]:
28    """Tokens con plegado de acentos y descomposicion de CamelCase."""
29    tokens: list[str] = []
30    for raw in _WORD.findall(fold(text)):
31        for part in re.split(r"[_.\-]", raw):
32            if not part:
33                continue
34            lowered = part.lower()
35            if lowered not in _STOP:
36                tokens.append(lowered)
37            for match in _CAMEL.finditer(part):
38                sub = match.group(0).lower()
39                if len(sub) > 2 and sub not in _STOP:
40                    tokens.append(sub)
41    return tokens
looks_like_identifierdef looks_like_identifier(query: str) -> bool
Ver prueba
src/docu/retrieve/search.py#L44-L64
44def looks_like_identifier(query: str) -> bool:
45    """¿La consulta es código tecleado o una pregunta humana?
46
47    Criterio estricto: una palabra capitalizada NO es un identificador —«Spring Boot» y «CORS»
48    aparecen en preguntas humanas y enrutarlas al canal estructural cuesta 0.12 de MRR (medido en
49    `eval/README.md`, F-12)—. Se exige forma de código: punto entre palabras, guion bajo, kebab o
50    camelCase real.
51    """
52    for token in query.split():
53        # Se recorta la puntuación de los extremos con una expresión regular y no con `strip`: con
54        # `strip` el efecto es el mismo, pero parece que quita una subcadena, y no es eso.
55        cleaned = _EDGE_PUNCTUATION.sub("", token)
56        if re.search(r"\w\.\w", cleaned):
57            return True
58        if "_" in cleaned:
59            return True
60        if re.search(r"\w-\w", cleaned):
61            return True
62        if re.search(r"[a-z][A-Z]", cleaned):
63            return True
64    return False
Section.textdef text(self) -> str
Ver prueba
src/docu/retrieve/search.py#L79-L80
Anotaciones: @property
79    def text(self) -> str:
80        return f"{self.heading}\n{self.body}"
Section.to_dictdef to_dict(self) -> dict[str, object]
Ver prueba
src/docu/retrieve/search.py#L82-L89
82    def to_dict(self) -> dict[str, object]:
83        return {
84            "document": self.document,
85            "level": self.level,
86            "heading": self.heading,
87            "body": self.body,
88            "citations": list(self.citations),
89        }
split_sectionsdef split_sections(path: Path, content: str, level: str=...) -> list[Section]
Ver prueba
src/docu/retrieve/search.py#L92-L122
92def split_sections(path: Path, content: str, level: str = "") -> list[Section]:
93    """Divide un Markdown por encabezados de nivel 2 conservando las citas de cada bloque."""
94    sections: list[Section] = []
95    heading = "(inicio)"
96    buffer: list[str] = []
97
98    def flush() -> None:
99        body = "\n".join(buffer).strip()
100        if not body and heading == "(inicio)":
101            return
102        citations = tuple(dict.fromkeys(re.findall(r"`([^`]+#L\d+(?:-L\d+)?)`", body)))
103        sections.append(
104            Section(
105                document=path.name,
106                heading=heading,
107                body=body,
108                level=level,
109                tokens=tuple(tokenize(f"{heading} {body}")),
110                citations=citations,
111            )
112        )
113
114    for line in content.splitlines():
115        if line.startswith("## "):
116            flush()
117            heading = line[3:].strip()
118            buffer = []
119            continue
120        buffer.append(line)
121    flush()
122    return [section for section in sections if section.body or section.heading != "(inicio)"]
DocIndex.__post_init__def __post_init__(self) -> None
Ver prueba
src/docu/retrieve/search.py#L136-L141
136    def __post_init__(self) -> None:
137        lengths = [len(section.tokens) for section in self.sections]
138        for section in self.sections:
139            for term in set(section.tokens):
140                self._df[term] = self._df.get(term, 0) + 1
141        self._avgdl = (sum(lengths) / len(lengths)) if lengths else 0.0
DocIndex.from_directorydef from_directory(cls, directory: Path | str, glossary: Mapping[str, Sequence[str]] | None=...) -> DocIndex
Ver prueba
src/docu/retrieve/search.py#L144-L152
Anotaciones: @classmethod
144    def from_directory(cls, directory: Path | str, glossary: Mapping[str, Sequence[str]] | None = None) -> DocIndex:
145        """Carga todos los `.md` de un directorio de documentacion generada."""
146        sections: list[Section] = []
147        root = Path(directory)
148        if root.exists():
149            for path in sorted(root.glob("*.md")):
150                level = path.name.split("-", 1)[0]
151                sections.extend(split_sections(path, path.read_text(encoding="utf-8"), level))
152        return cls(sections=sections, glossary=glossary)
DocIndex._idfdef _idf(self, term: str) -> float
Ver prueba
src/docu/retrieve/search.py#L154-L157
154    def _idf(self, term: str) -> float:
155        total = len(self.sections)
156        df = self._df.get(term, 0)
157        return math.log(1 + (total - df + 0.5) / (df + 0.5))
DocIndex.searchdef search(self, query: str, limit: int=..., expand_query: bool=..., level: str | None=...) -> list[tuple[Section, float]]
Ver prueba
src/docu/retrieve/search.py#L159-L189
159    def search(
160        self,
161        query: str,
162        limit: int = 5,
163        expand_query: bool = True,
164        level: str | None = None,
165    ) -> list[tuple[Section, float]]:
166        """Devuelve las secciones mas relevantes. `expand_query` aplica el glosario de dominio."""
167        if not self.sections:
168            return []
169        text = expand(query, self.glossary) if expand_query else query
170        terms = set(tokenize(text))
171        scored: list[tuple[Section, float]] = []
172        for section in self.sections:
173            if level and section.level and section.level != level:
174                continue
175            length = len(section.tokens)
176            score = 0.0
177            counts: dict[str, int] = {}
178            for token in section.tokens:
179                if token in terms:
180                    counts[token] = counts.get(token, 0) + 1
181            for term, frequency in counts.items():
182                denominator = frequency + self.k1 * (
183                    1 - self.b + self.b * (length / self._avgdl if self._avgdl else 1.0)
184                )
185                score += self._idf(term) * (frequency * (self.k1 + 1)) / denominator
186            if score > 0:
187                scored.append((section, score))
188        scored.sort(key=lambda item: item[1], reverse=True)
189        return scored[:limit]
DocIndex.is_emptydef is_empty(self) -> bool
Ver prueba
src/docu/retrieve/search.py#L192-L193
Anotaciones: @property
192    def is_empty(self) -> bool:
193        return not self.sections
DocIndex.headingsdef headings(self) -> Iterable[str]
Ver prueba
src/docu/retrieve/search.py#L195-L196
195    def headings(self) -> Iterable[str]:
196        return (section.heading for section in self.sections)

Diagramas 5

Generados del mismo grafo que el documento. 2 se dibujan como SVG propio (arquitectura, modelo de datos y flujo de API): no necesitan red ni JavaScript. El resto queda como código Mermaid copiable.

arquitectura

docu · 1 archivos docu.adapters · 1 archivos docu.adapters.embedders · 2 archiv docu.adapters.langs · 6 archivos docu.adapters.sources · 3 archivos docu.audit · 2 archivos docu.conformance · 3 archivos docu.core · 6 archivos docu.delivery · 7 archivos docu.generate · 9 archivos docu.index · 8 archivos docu.learn · 5 archivos docu.publish · 2 archivos docu.retrieve · 4 archivos eval · 2 archivos
Ver código Mermaid
flowchart LR
    docu["docu<br/>1 archivos"]
    docu_adapters["docu.adapters<br/>1 archivos"]
    docu_adapters_embedders["docu.adapters.embedders<br/>2 archivos"]
    docu_adapters_langs["docu.adapters.langs<br/>6 archivos"]
    docu_adapters_sources["docu.adapters.sources<br/>3 archivos"]
    docu_audit["docu.audit<br/>2 archivos"]
    docu_conformance["docu.conformance<br/>3 archivos"]
    docu_core["docu.core<br/>6 archivos"]
    docu_delivery["docu.delivery<br/>7 archivos"]
    docu_generate["docu.generate<br/>9 archivos"]
    docu_index["docu.index<br/>8 archivos"]
    docu_learn["docu.learn<br/>5 archivos"]
    docu_publish["docu.publish<br/>2 archivos"]
    docu_retrieve["docu.retrieve<br/>4 archivos"]
    eval["eval<br/>2 archivos"]
    docu --> docu_core
    docu_adapters_langs --> docu_core
    docu_audit --> docu_core
    docu_audit --> docu_generate
    docu_audit --> docu_index
    docu_conformance --> docu_adapters_langs
    docu_conformance --> docu_core
    docu_conformance --> docu_generate
    docu_delivery --> docu
    docu_delivery --> docu_adapters_langs
    docu_delivery --> docu_audit
    docu_delivery --> docu_conformance
    docu_delivery --> docu_core
    docu_delivery --> docu_generate
    docu_delivery --> docu_index
    docu_delivery --> docu_learn
    docu_delivery --> docu_publish
    docu_delivery --> docu_retrieve
    docu_generate --> docu_adapters_langs
    docu_generate --> docu_core
    docu_generate --> docu_index
    docu_generate --> docu_learn
    docu_index --> docu_adapters_sources
    docu_index --> docu_core
    docu_index --> docu_generate
    docu_learn --> docu_core
    docu_publish --> docu_generate
    docu_retrieve --> docu_adapters_embedders
    docu_retrieve --> docu_adapters_langs
    docu_retrieve --> docu_core
    docu_retrieve --> docu_generate
    docu_retrieve --> docu_index
    eval --> docu_adapters_embedders
    eval --> docu_adapters_langs
    eval --> docu_core
    eval --> docu_index
    eval --> docu_retrieve

clases docu.delivery

Ver código Mermaid
classDiagram
    class CleanPlan <<class>> {
        empty()
        total()
        to_dict()
    }
    class CliError <<class>> {
        __init__()
    }
    class ExitCode <<class>> {
    }
    class McpServer <<class>> {
        __post_init__()
        projects()
        resolve()
        _index_for()
        index()
        _glossary()
        _require_docs()
        call_tool()
    }
    class ProjectRef <<class>> {
        has_docs()
        project_name()
    }
    class ResolvedOptions <<class>> {
    }
    class ToolError <<class>> {
    }
    class _Handler <<class>> {
        do_GET()
        do_POST()
        _json()
        log_message()
    }
    class _Parser <<class>> {
        error()
    }

clases docu.generate

Ver código Mermaid
classDiagram
    class Diagram <<class>> {
        filename()
    }
    class DocSection <<class>> {
        citation()
        matches()
        to_fact()
    }
    class Fact <<class>> {
        verified()
        location()
    }
    class GeneratedDoc <<class>> {
    }
    class GenerationResult <<class>> {
        wrote_files()
        pending()
    }
    class Narrative <<class>> {
        facts()
    }
    class ProseResponse <<class>> {
        accepted()
    }
    class Verdict <<class>> {
        accepted()
    }

clases docu.index

Ver código Mermaid
classDiagram
    class DetectedPackage <<class>> {
        file_count()
        citation()
    }
    class DocEntry <<class>> {
        to_dict()
        from_dict()
        generated_at_dt()
    }
    class IgnoreRule <<class>> {
    }
    class InputComponents <<class>> {
    }
    class Manifest <<class>> {
        entry()
        upsert()
        to_dict()
        from_dict()
        save()
        load()
    }
    class PdfDocument <<class>> {
        citation()
        to_fact()
    }
    class SymbolChunker <<class>> {
        chunk()
        _span()
        _prefix()
        _split()
        _make()
    }
    class WebDocument <<class>> {
        citation()
        to_fact()
    }

modelo de datos

}o--|| _symbols }o--|| _hybrid }o--|| pattern }o--|| model }o--|| thresholds }o--|| metrics }o--|| gate }o--|| _bm25 }o--|| thresholds }o--|| thresholds }o--|| _bm25 Thresholds float accuracy float completeness float attribution float conciseness GenerationResult str project tuple_Generate docs tuple_Fact facts Mapping_str__s sources Metrics metrics GateDecision gate float elapsed_s +5 campos HybridIndex Sequence_Segme segments object embedder float k1 float b int rrf_k int max_exact_per_file int max_per_file +3 campos SymbolIndex Sequence_Segme segments float k1 float b int rrf_k int max_exact_per_file int max_per_file BM25 _bm25 +1 campos BM25 float k1 float b Sequence_Segme segments dict_str__int _df list_int _lengths float _avgdl AutoIndex Sequence_Segme segments object embedder SymbolIndex _symbols HybridIndex _hybrid Profile str project Mode mode tuple_str levels str output_dir str language int ttl_days tuple_str include +5 campos McpServer Path root Path docs_dir Path manifest_path Path profile_path Path workspace bool dense dict_str__Proj _refs +2 campos ResolvedOptions Profile profile str project tuple_str levels Path out_dir int ttl_days tuple_str include tuple_str exclude +2 campos Metrics float accuracy float completeness float attribution float conciseness float freshness float cost_usd int unsupported_claims +1 campos Pattern str pattern_id str stack str kind Mapping_str__f metrics int runs str notes ArchitectureModel tuple_Declared components tuple_Route routes tuple_str sources str schema_version DriftReport ArchitectureMo model list_Discrepan discrepancies int routes_in_code int components_in_code GatePolicy Thresholds thresholds bool require_zero_unsup bool require_fresh Candidate Pattern pattern Sequence_str reasons GateDecision GateOutcome outcome tuple_str reasons

Recorte explícito: se muestran 16 de 24 entidades · 19 campos adicionales en el diccionario de datos · 1 relaciones fuera del recorte. El diagrama no omite en silencio.

Ver código Mermaid
erDiagram
    %% recorte: 24 de 79 entidades (las de más relaciones)
    ArchitectureModel {
        tuple_DeclaredComponent components
        tuple_Route routes
        tuple_str sources
        str schema_version
    }
    Artifact {
        str artifact_id
        SourceKind kind
        str uri
        str content_hash
        datetime captured_at
        str lang
        str snapshot_path
        Mapping_str__Any metadata
        str schema_version
    }
    AutoIndex {
        Sequence_Segment segments
        object embedder
        SymbolIndex _symbols
        HybridIndex _hybrid
    }
    BM25 {
        float k1
        float b
        Sequence_Segment segments
        dict_str__int _df
        list_int _lengths
        float _avgdl
    }
    Candidate {
        Pattern pattern
        Sequence_str reasons
    }
    CaseResult {
        str case_id
        str category
        float recall
        bool hit
        float mrr
        bool line_hit
        bool symbol_hit
        str query_mode
        bool passed
        tuple_str retrieved
        float elapsed_ms
    }
    Chunk {
        str chunk_id
        str artifact_id
        SourceKind source_type
        str content
        str content_prefix
        str content_hash
        str file_path
        str lang
        str enclosing_symbol
        SymbolKind symbol_kind
        int line_start
        int line_end
    }
    CodeIndex {
        list_CodeChunk chunks
        object embedder
        Mapping_str__Sequence_st glossary
        float k1
        float b
        dict_str__int _df
        list_int _lengths
        float _avgdl
        dict_str__list_CodeChunk _by_name
        list_Sequence_float _vectors
        bool _dense_ready
    }
    DriftReport {
        ArchitectureModel model
        list_Discrepancy discrepancies
        int routes_in_code
        int components_in_code
    }
    GateDecision {
        GateOutcome outcome
        tuple_str reasons
    }
    GatePolicy {
        Thresholds thresholds
        bool require_zero_unsupported
        bool require_fresh
    }
    GenerationResult {
        str project
        tuple_GeneratedDoc docs
        tuple_Fact facts
        Mapping_str__str sources
        Metrics metrics
        GateDecision gate
        float elapsed_s
        tuple_Fact unsupported
        Mapping_str__DocState states
        Path manifest_path
        Mapping_str__bool applicability
        Mapping_str__int unsupported_languages
    }
    HybridIndex {
        Sequence_Segment segments
        object embedder
        float k1
        float b
        int rrf_k
        int max_exact_per_file
        int max_per_file
        BM25 _bm25
        dict_str__list_Segment _by_name
        list_list_float _vectors
    }
    McpServer {
        Path root
        Path docs_dir
        Path manifest_path
        Path profile_path
        Path workspace
        bool dense
        dict_str__ProjectRef _refs
        dict_str__DocIndex _indexes
        dict_str__object _code_indexes
    }
    Metrics {
        float accuracy
        float completeness
        float attribution
        float conciseness
        float freshness
        float cost_usd
        int unsupported_claims
        str schema_version
    }
    Pattern {
        str pattern_id
        str stack
        str kind
        Mapping_str__float metrics
        int runs
        str notes
    }
    Profile {
        str project
        Mode mode
        tuple_str levels
        str output_dir
        str language
        int ttl_days
        tuple_str include
        tuple_str exclude
        Thresholds thresholds
        Mapping_str__tuple_str glossary
        float promotion_delta
        float rollback_drop
    }
    Report {
        str project
        int k
        int files
        int segments
        list_CaseResult results
        str query_field
        str index_mode
        bool query_expansion
        str generated_at
        str schema_version
    }
    ResolvedOptions {
        Profile profile
        str project
        tuple_str levels
        Path out_dir
        int ttl_days
        tuple_str include
        tuple_str exclude
        Thresholds thresholds
        Path manifest
    }
    RunRecord {
        str run_id
        str project
        str commit
        Mode mode
        datetime started_at
        datetime finished_at
        dict_str__str versions
        Metrics metrics
        GateDecision gate
        int pages_written
        int pages_skipped
        float cost_usd
    }
    Symbol {
        str name
        str qualname
        SymbolKind kind
        str path
        int line_start
        int line_end
        str signature
        Sequence_Symbol children
        Sequence_str annotations
        str schema_version
    }
    SymbolIndex {
        Sequence_Segment segments
        float k1
        float b
        int rrf_k
        int max_exact_per_file
        int max_per_file
        BM25 _bm25
        dict_str__list_Segment _by_name
    }
    Thresholds {
        float accuracy
        float completeness
        float attribution
        float conciseness
    }
    _Handler {
        sinTipo server_version
        McpServer mcp
    }
    AutoIndex }o--|| SymbolIndex : "_symbols"
    AutoIndex }o--|| HybridIndex : "_hybrid"
    Candidate }o--|| Pattern : "pattern"
    DriftReport }o--|| ArchitectureModel : "model"
    GatePolicy }o--|| Thresholds : "thresholds"
    GenerationResult }o--|| Metrics : "metrics"
    GenerationResult }o--|| GateDecision : "gate"
    HybridIndex }o--|| BM25 : "_bm25"
    Profile }o--|| Thresholds : "thresholds"
    ResolvedOptions }o--|| Thresholds : "thresholds"
    SymbolIndex }o--|| BM25 : "_bm25"
    _Handler }o--|| McpServer : "mcp"