Arquitectura 15
| Qué | Detalle | Evidencia |
|---|---|---|
docu | 1 archivos · python | Ver pruebasrc/docu/__init__.py#L1-L101"""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.adapters | 1 archivos · python | Ver pruebasrc/docu/adapters/__init__.py#L1-L11"""Implementaciones de los puertos del nucleo. Nada de aqui lo importa `docu.core`.""" |
docu.adapters.embedders | 2 archivos · python | Ver pruebasrc/docu/adapters/embedders/__init__.py#L1-L11"""Adaptadores de embeddings: locales (ONNX) o por API, detras del puerto `Embedder`.""" |
docu.adapters.langs | 6 archivos · python | Ver pruebasrc/docu/adapters/langs/__init__.py#L1-L11"""Adaptadores de lenguaje: uno por lenguaje, detras del puerto `LangAdapter`.""" |
docu.adapters.sources | 3 archivos · python | Ver pruebasrc/docu/adapters/sources/__init__.py#L1-L51"""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.audit | 2 archivos · python | Ver pruebasrc/docu/audit/__init__.py#L1-L51"""Auditoria: comprobaciones deterministas sobre la documentacion generada.""" 2 3from docu.audit import verify 4 5__all__ = ["verify"] |
docu.conformance | 3 archivos · python | Ver pruebasrc/docu/conformance/__init__.py#L1-L51"""Conformidad arquitectonica: modelo prescriptivo frente al codigo real.""" 2 3from docu.conformance import drift, model 4 5__all__ = ["drift", "model"] |
docu.core | 6 archivos · python | Ver pruebasrc/docu/core/__init__.py#L1-L51"""Contratos, puertos y politica del nucleo. Sin dependencias externas.""" 2 3from docu.core import contracts, policy, ports 4 5__all__ = ["contracts", "policy", "ports"] |
docu.delivery | 7 archivos · python | Ver pruebasrc/docu/delivery/__init__.py#L1-L51"""Superficies de entrega: CLI, CI y servidor MCP (solo lectura).""" 2 3from docu.delivery.exit_codes import ExitCode 4 5__all__ = ["ExitCode"] |
docu.generate | 9 archivos · python | Ver pruebasrc/docu/generate/__init__.py#L1-L51"""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.index | 8 archivos · python | Ver pruebasrc/docu/index/__init__.py#L1-L51"""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.learn | 5 archivos · python | Ver pruebasrc/docu/learn/__init__.py#L1-L51"""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.publish | 2 archivos · python | Ver pruebasrc/docu/publish/__init__.py#L1-L51"""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.retrieve | 4 archivos · python | Ver pruebasrc/docu/retrieve/__init__.py#L1-L51"""Recuperacion: expansion de consulta, busqueda sobre documentos y sobre codigo.""" 2 3from docu.retrieve import glossary, hybrid, search 4 5__all__ = ["glossary", "hybrid", "search"] |
eval | 2 archivos · python | Ver pruebaeval/__init__.py#L1-L11"""Arnés de evaluación: golden sets y línea base de recuperación (F0).""" |
Dependencias 17
| Qué | Detalle | Evidencia |
|---|---|---|
requires-python | >=3.11 | Ver pruebapyproject.toml#L10-L1010requires-python = ">=3.11" |
typer | >=0.12 | Ver pruebapyproject.toml#L18-L1818cli = ["typer>=0.12"] # alternativa ergonomica a argparse (el CLI actual es stdlib) |
PyYAML | >=6.0 | Ver pruebapyproject.toml#L19-L1919profile = ["PyYAML>=6.0"] # lectura de docu.profile.yaml |
tree-sitter | >=0.23 | Ver pruebapyproject.toml#L20-L2020langs = ["tree-sitter>=0.23", "tree-sitter-python", "tree-sitter-typescript", "tree-sitter-java"] |
tree-sitter-python | (sin versión fija) | Ver pruebapyproject.toml#L20-L2020langs = ["tree-sitter>=0.23", "tree-sitter-python", "tree-sitter-typescript", "tree-sitter-java"] |
tree-sitter-typescript | (sin versión fija) | Ver pruebapyproject.toml#L20-L2020langs = ["tree-sitter>=0.23", "tree-sitter-python", "tree-sitter-typescript", "tree-sitter-java"] |
tree-sitter-java | (sin versión fija) | Ver pruebapyproject.toml#L20-L2020langs = ["tree-sitter>=0.23", "tree-sitter-python", "tree-sitter-typescript", "tree-sitter-java"] |
chromadb | >=0.5 | Ver pruebapyproject.toml#L21-L2121index = ["chromadb>=0.5", "onnxruntime>=1.18", "tokenizers>=0.19"] |
onnxruntime | >=1.18 | Ver pruebapyproject.toml#L21-L2121index = ["chromadb>=0.5", "onnxruntime>=1.18", "tokenizers>=0.19"] |
tokenizers | >=0.19 | Ver pruebapyproject.toml#L21-L2121index = ["chromadb>=0.5", "onnxruntime>=1.18", "tokenizers>=0.19"] |
pdfplumber | >=0.11 | Ver pruebapyproject.toml#L22-L2222docs = ["pdfplumber>=0.11", "markdown-it-py>=3.0"] |
markdown-it-py | >=3.0 | Ver pruebapyproject.toml#L22-L2222docs = ["pdfplumber>=0.11", "markdown-it-py>=3.0"] |
jinja2 | >=3.1 | Ver pruebapyproject.toml#L23-L2323generate = ["jinja2>=3.1"] |
ragas | >=0.1 | Ver pruebapyproject.toml#L24-L2424eval = ["ragas>=0.1"] |
pytest | >=8.0 | Ver pruebapyproject.toml#L25-L2525dev = ["pytest>=8.0", "ruff>=0.6", "mypy>=1.10"] |
ruff | >=0.6 | Ver pruebapyproject.toml#L25-L2525dev = ["pytest>=8.0", "ruff>=0.6", "mypy>=1.10"] |
mypy | >=1.10 | Ver pruebapyproject.toml#L25-L2525dev = ["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é | Detalle | Evidencia |
|---|---|---|
schema_version | 1.0 | Ver pruebadocu.profile.yaml#L3-L33schema_version: "1.0" |
project | docu | Ver pruebadocu.profile.yaml#L5-L55project: docu |
mode | apply | Ver pruebadocu.profile.yaml#L6-L66mode: apply # propose | apply | publish |
sources.git.ref | HEAD | Ver pruebadocu.profile.yaml#L10-L1010 ref: HEAD |
sources.pdf | [] | Ver pruebadocu.profile.yaml#L31-L3131 pdf: [] |
sources.web.allowlist | ["docs.spring.io", "docs.python.org", "developer.mozilla.org"] | Ver pruebadocu.profile.yaml#L33-L3333 allowlist: ["docs.spring.io", "docs.python.org", "developer.mozilla.org"] |
sources.contracts | [] | Ver pruebadocu.profile.yaml#L34-L3434 contracts: [] |
output.dir | docs/generated | Ver pruebadocu.profile.yaml#L37-L3737 dir: docs/generated |
output.language | es | Ver pruebadocu.profile.yaml#L38-L3838 language: es |
output.levels.l1 | true | Ver pruebadocu.profile.yaml#L40-L4040 l1: true |
output.levels.l2 | true | Ver pruebadocu.profile.yaml#L41-L4141 l2: true |
output.levels.l3 | true | Ver pruebadocu.profile.yaml#L42-L4242 l3: true |
output.levels.l4 | true | Ver pruebadocu.profile.yaml#L43-L4343 l4: true |
output.notation.diagrams | mermaid | Ver pruebadocu.profile.yaml#L45-L4545 diagrams: mermaid |
output.notation.architecture | c4 | Ver pruebadocu.profile.yaml#L46-L4646 architecture: c4 |
output.notation.api | openapi3.1 | Ver pruebadocu.profile.yaml#L47-L4747 api: openapi3.1 |
acceptance.thresholds.accuracy | 8.5 | Ver pruebadocu.profile.yaml#L51-L5151 accuracy: 8.5 |
acceptance.thresholds.completeness | 9.0 | Ver pruebadocu.profile.yaml#L52-L5252 completeness: 9.0 |
acceptance.thresholds.attribution | 9.5 | Ver pruebadocu.profile.yaml#L53-L5353 attribution: 9.5 |
acceptance.thresholds.conciseness | 7.5 | Ver pruebadocu.profile.yaml#L54-L5454 conciseness: 7.5 |
freshness.ttl_days | 90 | Ver pruebadocu.profile.yaml#L57-L5757 ttl_days: 90 |
learn.promotion_delta | 0.05 | Ver pruebadocu.profile.yaml#L60-L6060 promotion_delta: 0.05 |
learn.rollback_drop | 0.05 | Ver pruebadocu.profile.yaml#L61-L6161 rollback_drop: 0.05 |
learn.federate | false | Ver pruebadocu.profile.yaml#L62-L6262 federate: false |
Modelo de datos 425
| Qué | Detalle | Evidencia |
|---|---|---|
Segment.path | str | Ver pruebaeval/harness.py#L123-L123123 path: str |
Segment.start | int | Ver pruebaeval/harness.py#L124-L124124 start: int |
Segment.end | int | Ver pruebaeval/harness.py#L125-L125125 end: int |
Segment.text | str | Ver pruebaeval/harness.py#L126-L126126 text: str |
Segment.tokens | tuple[str, ...] | Ver pruebaeval/harness.py#L127-L127127 tokens: tuple[str, ...] = () |
Segment.exact_names | tuple[str, ...] | Ver pruebaeval/harness.py#L128-L128128 exact_names: tuple[str, ...] = () |
Segment.citation | str | None | Ver pruebaeval/harness.py#L129-L129129 citation: str | None = None |
BM25.k1 | float | Ver pruebaeval/harness.py#L263-L263263 k1: float = 1.5 |
BM25.b | float | Ver pruebaeval/harness.py#L264-L264264 b: float = 0.75 |
BM25.segments | Sequence[Segment] | Ver pruebaeval/harness.py#L265-L265265 segments: Sequence[Segment] = () |
BM25._df | dict[str, int] | Ver pruebaeval/harness.py#L266-L266266 _df: dict[str, int] = field(default_factory=dict, init=False) |
BM25._lengths | list[int] | Ver pruebaeval/harness.py#L267-L267267 _lengths: list[int] = field(default_factory=list, init=False) |
BM25._avgdl | float | Ver pruebaeval/harness.py#L268-L268268 _avgdl: float = field(default=0.0, init=False) |
AutoIndex.segments | Sequence[Segment] | Ver pruebaeval/harness.py#L437-L437437 segments: Sequence[Segment] |
AutoIndex.embedder | object | Ver pruebaeval/harness.py#L438-L438438 embedder: object = None |
AutoIndex._symbols | SymbolIndex | Ver pruebaeval/harness.py#L439-L439439 _symbols: SymbolIndex = field(init=False, repr=False) |
AutoIndex._hybrid | HybridIndex | Ver pruebaeval/harness.py#L440-L440440 _hybrid: HybridIndex = field(init=False, repr=False) |
HybridIndex.segments | Sequence[Segment] | Ver pruebaeval/harness.py#L460-L460460 segments: Sequence[Segment] |
HybridIndex.embedder | object | Ver pruebaeval/harness.py#L461-L461461 embedder: object = None |
HybridIndex.k1 | float | Ver pruebaeval/harness.py#L462-L462462 k1: float = 1.5 |
HybridIndex.b | float | Ver pruebaeval/harness.py#L463-L463463 b: float = 0.75 |
HybridIndex.rrf_k | int | Ver pruebaeval/harness.py#L464-L464464 rrf_k: int = 60 |
HybridIndex.max_exact_per_file | int | Ver pruebaeval/harness.py#L465-L465465 max_exact_per_file: int = 2 |
HybridIndex.max_per_file | int | Ver pruebaeval/harness.py#L466-L466466 max_per_file: int = 2 |
HybridIndex._bm25 | BM25 | Ver pruebaeval/harness.py#L467-L467467 _bm25: BM25 = field(init=False, repr=False) |
HybridIndex._by_name | dict[str, list[Segment]] | Ver pruebaeval/harness.py#L468-L468468 _by_name: dict[str, list[Segment]] = field(init=False, repr=False, default_factory=dict) |
HybridIndex._vectors | list[list[float]] | Ver pruebaeval/harness.py#L469-L469469 _vectors: list[list[float]] = field(init=False, repr=False, default_factory=list) |
SymbolIndex.segments | Sequence[Segment] | Ver pruebaeval/harness.py#L548-L548548 segments: Sequence[Segment] |
SymbolIndex.k1 | float | Ver pruebaeval/harness.py#L549-L549549 k1: float = 1.5 |
SymbolIndex.b | float | Ver pruebaeval/harness.py#L550-L550550 b: float = 0.75 |
SymbolIndex.rrf_k | int | Ver pruebaeval/harness.py#L551-L551551 rrf_k: int = 60 |
SymbolIndex.max_exact_per_file | int | Ver pruebaeval/harness.py#L552-L552552 max_exact_per_file: int = 2 |
SymbolIndex.max_per_file | int | Ver pruebaeval/harness.py#L553-L553553 max_per_file: int = 2 |
SymbolIndex._bm25 | BM25 | Ver pruebaeval/harness.py#L554-L554554 _bm25: BM25 = field(init=False, repr=False) |
SymbolIndex._by_name | dict[str, list[Segment]] | Ver pruebaeval/harness.py#L555-L555555 _by_name: dict[str, list[Segment]] = field(init=False, repr=False, default_factory=dict) |
Expected.path | str | Ver pruebaeval/harness.py#L602-L602602 path: str |
Expected.symbol | str | None | Ver pruebaeval/harness.py#L603-L603603 symbol: str | None = None |
Expected.lines | tuple[int, int] | None | Ver pruebaeval/harness.py#L604-L604604 lines: tuple[int, int] | None = None |
Expected.optional | bool | Ver pruebaeval/harness.py#L605-L605605 optional: bool = False |
Case.id | str | Ver pruebaeval/harness.py#L610-L610610 id: str |
Case.category | str | Ver pruebaeval/harness.py#L611-L611611 category: str |
Case.question | str | Ver pruebaeval/harness.py#L612-L612612 question: str |
Case.expected | tuple[Expected, ...] | Ver pruebaeval/harness.py#L613-L613613 expected: tuple[Expected, ...] |
Case.answer | str | Ver pruebaeval/harness.py#L614-L614614 answer: str = "" |
Case.notes | str | Ver pruebaeval/harness.py#L615-L615615 notes: str = "" |
Case.query | str | Ver pruebaeval/harness.py#L616-L616616 query: str = "" |
CaseResult.case_id | str | Ver pruebaeval/harness.py#L631-L631631 case_id: str |
CaseResult.category | str | Ver pruebaeval/harness.py#L632-L632632 category: str |
CaseResult.recall | float | Ver pruebaeval/harness.py#L633-L633633 recall: float |
CaseResult.hit | bool | Ver pruebaeval/harness.py#L634-L634634 hit: bool |
CaseResult.mrr | float | Ver pruebaeval/harness.py#L635-L635635 mrr: float |
CaseResult.line_hit | bool | None | Ver pruebaeval/harness.py#L636-L636636 line_hit: bool | None |
CaseResult.symbol_hit | bool | None | Ver pruebaeval/harness.py#L637-L637637 symbol_hit: bool | None |
CaseResult.query_mode | str | Ver pruebaeval/harness.py#L638-L638638 query_mode: str |
CaseResult.passed | bool | Ver pruebaeval/harness.py#L639-L639639 passed: bool |
CaseResult.retrieved | tuple[str, ...] | Ver pruebaeval/harness.py#L640-L640640 retrieved: tuple[str, ...] |
CaseResult.elapsed_ms | float | Ver pruebaeval/harness.py#L641-L641641 elapsed_ms: float |
Report.project | str | Ver pruebaeval/harness.py#L646-L646646 project: str |
Report.k | int | Ver pruebaeval/harness.py#L647-L647647 k: int |
Report.files | int | Ver pruebaeval/harness.py#L648-L648648 files: int |
Report.segments | int | Ver pruebaeval/harness.py#L649-L649649 segments: int |
Report.results | list[CaseResult] | Ver pruebaeval/harness.py#L650-L650650 results: list[CaseResult] |
Report.query_field | str | Ver pruebaeval/harness.py#L651-L651651 query_field: str = "auto" |
Report.index_mode | str | Ver pruebaeval/harness.py#L652-L652652 index_mode: str = "windows" |
Report.query_expansion | bool | Ver pruebaeval/harness.py#L653-L653653 query_expansion: bool = False |
Report.generated_at | str | Ver pruebaeval/harness.py#L654-L654654 generated_at: str = "" |
Report.schema_version | str | Ver pruebaeval/harness.py#L655-L655655 schema_version: str = SCHEMA_VERSION |
OnnxEmbedder.model_dir | Path | str | Ver pruebasrc/docu/adapters/embedders/onnx_local.py#L43-L4343 model_dir: Path | str = DEFAULT_MODEL_DIR |
OnnxEmbedder.embedder_id | str | Ver pruebasrc/docu/adapters/embedders/onnx_local.py#L44-L4444 embedder_id: str = DEFAULT_EMBEDDER_ID |
OnnxEmbedder.max_length | int | Ver pruebasrc/docu/adapters/embedders/onnx_local.py#L45-L4545 max_length: int = 256 |
OnnxEmbedder.batch_size | int | Ver pruebasrc/docu/adapters/embedders/onnx_local.py#L46-L4646 batch_size: int = 16 |
OnnxEmbedder._session | object | None | Ver pruebasrc/docu/adapters/embedders/onnx_local.py#L47-L4747 _session: object | None = None |
OnnxEmbedder._tokenizer | object | None | Ver pruebasrc/docu/adapters/embedders/onnx_local.py#L48-L4848 _tokenizer: object | None = None |
OnnxEmbedder._input_names | tuple[str, ...] | Ver pruebasrc/docu/adapters/embedders/onnx_local.py#L49-L4949 _input_names: tuple[str, ...] = () |
OnnxEmbedder._dim | int | Ver pruebasrc/docu/adapters/embedders/onnx_local.py#L50-L5050 _dim: int = 384 |
JavaLangAdapter.language | str | Ver pruebasrc/docu/adapters/langs/java.py#L369-L369369 language: str = "java" |
JavaLangAdapter.file_globs | tuple[str, ...] | Ver pruebasrc/docu/adapters/langs/java.py#L370-L370370 file_globs: tuple[str, ...] = ("*.java",) |
PythonLangAdapter.language | str | Ver pruebasrc/docu/adapters/langs/python.py#L22-L2222 language: str = "python" |
PythonLangAdapter.file_globs | tuple[str, ...] | Ver pruebasrc/docu/adapters/langs/python.py#L23-L2323 file_globs: tuple[str, ...] = ("*.py",) |
TypeScriptLangAdapter.language | str | Ver pruebasrc/docu/adapters/langs/typescript.py#L88-L8888 language: str = "typescript" |
TypeScriptLangAdapter.file_globs | tuple[str, ...] | Ver pruebasrc/docu/adapters/langs/typescript.py#L89-L8989 file_globs: tuple[str, ...] = ("*.ts", "*.tsx", "*.js", "*.jsx", "*.mjs", "*.cjs") |
PdfPage.number | int | Ver pruebasrc/docu/adapters/sources/pdf.py#L120-L120120 number: int |
PdfPage.text | str | Ver pruebasrc/docu/adapters/sources/pdf.py#L121-L121121 text: str |
PdfText.pages | tuple[PdfPage, ...] | Ver pruebasrc/docu/adapters/sources/pdf.py#L126-L126126 pages: tuple[PdfPage, ...] = () |
PdfText.total_pages | int | Ver pruebasrc/docu/adapters/sources/pdf.py#L127-L127127 total_pages: int = 0 |
PdfText.chars | int | Ver pruebasrc/docu/adapters/sources/pdf.py#L128-L128128 chars: int = 0 |
PdfText.method | str | Ver pruebasrc/docu/adapters/sources/pdf.py#L129-L129129 method: str = "desconocido" |
PdfText.warnings | tuple[str, ...] | Ver pruebasrc/docu/adapters/sources/pdf.py#L130-L130130 warnings: tuple[str, ...] = field(default_factory=tuple) |
Snapshot.url | str | Ver pruebasrc/docu/adapters/sources/web.py#L44-L4444 url: str |
Snapshot.text | str | Ver pruebasrc/docu/adapters/sources/web.py#L45-L4545 text: str |
Snapshot.sha | str | Ver pruebasrc/docu/adapters/sources/web.py#L46-L4646 sha: str |
Snapshot.captured_at | str | Ver pruebasrc/docu/adapters/sources/web.py#L47-L4747 captured_at: str |
Snapshot.status_code | int | Ver pruebasrc/docu/adapters/sources/web.py#L48-L4848 status_code: int = 200 |
Check.name | str | Ver pruebasrc/docu/audit/verify.py#L43-L4343 name: str |
Check.total | int | Ver pruebasrc/docu/audit/verify.py#L44-L4444 total: int |
Check.failed | int | Ver pruebasrc/docu/audit/verify.py#L45-L4545 failed: int |
Check.details | tuple[str, ...] | Ver pruebasrc/docu/audit/verify.py#L46-L4646 details: tuple[str, ...] = () |
Check.note | str | Ver pruebasrc/docu/audit/verify.py#L47-L4747 note: str = "" |
AuditReport.project | str | Ver pruebasrc/docu/audit/verify.py#L73-L7373 project: str |
AuditReport.checks | dict[str, Check] | Ver pruebasrc/docu/audit/verify.py#L74-L7474 checks: dict[str, Check] = field(default_factory=dict) |
AuditReport.facts_total | int | Ver pruebasrc/docu/audit/verify.py#L76-L7676 facts_total: int = 0 |
AuditReport.excluded | dict[str, int] | Ver pruebasrc/docu/audit/verify.py#L77-L7777 excluded: dict[str, int] = field(default_factory=dict) |
Discrepancy.kind | str | Ver pruebasrc/docu/conformance/drift.py#L39-L3939 kind: str |
Discrepancy.subject | str | Ver pruebasrc/docu/conformance/drift.py#L40-L4040 subject: str |
Discrepancy.detail | str | Ver pruebasrc/docu/conformance/drift.py#L41-L4141 detail: str |
Discrepancy.code_citation | str | None | Ver pruebasrc/docu/conformance/drift.py#L42-L4242 code_citation: str | None = None |
Discrepancy.declaration_source | str | None | Ver pruebasrc/docu/conformance/drift.py#L43-L4343 declaration_source: str | None = None |
DriftReport.model | ArchitectureModel | Ver pruebasrc/docu/conformance/drift.py#L67-L6767 model: ArchitectureModel |
DriftReport.discrepancies | list[Discrepancy] | Ver pruebasrc/docu/conformance/drift.py#L68-L6868 discrepancies: list[Discrepancy] = field(default_factory=list) |
DriftReport.routes_in_code | int | Ver pruebasrc/docu/conformance/drift.py#L69-L6969 routes_in_code: int = 0 |
DriftReport.components_in_code | int | Ver pruebasrc/docu/conformance/drift.py#L70-L7070 components_in_code: int = 0 |
RouteFact.key | str | Ver pruebasrc/docu/conformance/drift.py#L128-L128128 key: str |
RouteFact.citation | str | Ver pruebasrc/docu/conformance/drift.py#L129-L129129 citation: str |
RouteFact.handler | str | Ver pruebasrc/docu/conformance/drift.py#L130-L130130 handler: str |
CodeFacts.routes | tuple[RouteFact, ...] | Ver pruebasrc/docu/conformance/drift.py#L135-L135135 routes: tuple[RouteFact, ...] |
CodeFacts.components | Mapping[str, str] | Ver pruebasrc/docu/conformance/drift.py#L136-L136136 components: Mapping[str, str] # nombre de tipo -> cita |
CodeFacts.dependencies | tuple[tuple[str, str], ...] | Ver pruebasrc/docu/conformance/drift.py#L137-L137137 dependencies: tuple[tuple[str, str], ...] # (llamador, llamado) |
Route.verb | str | Ver pruebasrc/docu/conformance/model.py#L32-L3232 verb: str |
Route.path | str | Ver pruebasrc/docu/conformance/model.py#L33-L3333 path: str |
DeclaredComponent.name | str | Ver pruebasrc/docu/conformance/model.py#L45-L4545 name: str |
DeclaredComponent.kind | str | Ver pruebasrc/docu/conformance/model.py#L46-L4646 kind: str = "component" |
DeclaredComponent.provides | tuple[Route, ...] | Ver pruebasrc/docu/conformance/model.py#L47-L4747 provides: tuple[Route, ...] = () |
DeclaredComponent.depends_on | tuple[str, ...] | Ver pruebasrc/docu/conformance/model.py#L48-L4848 depends_on: tuple[str, ...] = () |
DeclaredComponent.source | str | Ver pruebasrc/docu/conformance/model.py#L49-L4949 source: str = "" |
ArchitectureModel.components | tuple[DeclaredComponent, ...] | Ver pruebasrc/docu/conformance/model.py#L54-L5454 components: tuple[DeclaredComponent, ...] = () |
ArchitectureModel.routes | tuple[Route, ...] | Ver pruebasrc/docu/conformance/model.py#L55-L5555 routes: tuple[Route, ...] = () |
ArchitectureModel.sources | tuple[str, ...] | Ver pruebasrc/docu/conformance/model.py#L56-L5656 sources: tuple[str, ...] = () |
ArchitectureModel.schema_version | str | Ver pruebasrc/docu/conformance/model.py#L57-L5757 schema_version: str = "1.0" |
Artifact.artifact_id | str | Ver pruebasrc/docu/core/contracts.py#L99-L9999 artifact_id: str |
Artifact.kind | SourceKind | Ver pruebasrc/docu/core/contracts.py#L100-L100100 kind: SourceKind |
Artifact.uri | str | Ver pruebasrc/docu/core/contracts.py#L101-L101101 uri: str |
Artifact.content_hash | str | Ver pruebasrc/docu/core/contracts.py#L102-L102102 content_hash: str |
Artifact.captured_at | datetime | Ver pruebasrc/docu/core/contracts.py#L103-L103103 captured_at: datetime |
Artifact.lang | str | None | Ver pruebasrc/docu/core/contracts.py#L104-L104104 lang: str | None = None |
Artifact.snapshot_path | str | None | Ver pruebasrc/docu/core/contracts.py#L105-L105105 snapshot_path: str | None = None |
Artifact.metadata | Mapping[str, Any] | Ver pruebasrc/docu/core/contracts.py#L106-L106106 metadata: Mapping[str, Any] = field(default_factory=dict) |
Artifact.schema_version | str | Ver pruebasrc/docu/core/contracts.py#L107-L107107 schema_version: str = SCHEMA_VERSION |
Symbol.name | str | Ver pruebasrc/docu/core/contracts.py#L122-L122122 name: str |
Symbol.qualname | str | Ver pruebasrc/docu/core/contracts.py#L123-L123123 qualname: str |
Symbol.kind | SymbolKind | Ver pruebasrc/docu/core/contracts.py#L124-L124124 kind: SymbolKind |
Symbol.path | str | Ver pruebasrc/docu/core/contracts.py#L125-L125125 path: str |
Symbol.line_start | int | Ver pruebasrc/docu/core/contracts.py#L126-L126126 line_start: int |
Symbol.line_end | int | Ver pruebasrc/docu/core/contracts.py#L127-L127127 line_end: int |
Symbol.signature | str | None | Ver pruebasrc/docu/core/contracts.py#L128-L128128 signature: str | None = None |
Symbol.children | Sequence[Symbol] | Ver pruebasrc/docu/core/contracts.py#L129-L129129 children: Sequence[Symbol] = () |
Symbol.annotations | Sequence[str] | Ver pruebasrc/docu/core/contracts.py#L130-L130130 annotations: Sequence[str] = () |
Symbol.schema_version | str | Ver pruebasrc/docu/core/contracts.py#L131-L131131 schema_version: str = SCHEMA_VERSION |
Chunk.chunk_id | str | Ver pruebasrc/docu/core/contracts.py#L145-L145145 chunk_id: str |
Chunk.artifact_id | str | Ver pruebasrc/docu/core/contracts.py#L146-L146146 artifact_id: str |
Chunk.source_type | SourceKind | Ver pruebasrc/docu/core/contracts.py#L147-L147147 source_type: SourceKind |
Chunk.content | str | Ver pruebasrc/docu/core/contracts.py#L148-L148148 content: str |
Chunk.content_prefix | str | Ver pruebasrc/docu/core/contracts.py#L149-L149149 content_prefix: str |
Chunk.content_hash | str | Ver pruebasrc/docu/core/contracts.py#L150-L150150 content_hash: str |
Chunk.file_path | str | Ver pruebasrc/docu/core/contracts.py#L151-L151151 file_path: str |
Chunk.lang | str | None | Ver pruebasrc/docu/core/contracts.py#L152-L152152 lang: str | None |
Chunk.enclosing_symbol | str | None | Ver pruebasrc/docu/core/contracts.py#L153-L153153 enclosing_symbol: str | None |
Chunk.symbol_kind | SymbolKind | Ver pruebasrc/docu/core/contracts.py#L154-L154154 symbol_kind: SymbolKind |
Chunk.line_start | int | Ver pruebasrc/docu/core/contracts.py#L155-L155155 line_start: int |
Chunk.line_end | int | Ver pruebasrc/docu/core/contracts.py#L156-L156156 line_end: int |
Chunk.ingested_at | datetime | Ver pruebasrc/docu/core/contracts.py#L157-L157157 ingested_at: datetime |
Chunk.repo | str | None | Ver pruebasrc/docu/core/contracts.py#L158-L158158 repo: str | None = None |
Chunk.commit | str | None | Ver pruebasrc/docu/core/contracts.py#L159-L159159 commit: str | None = None |
Chunk.dependencies | Sequence[str] | Ver pruebasrc/docu/core/contracts.py#L160-L160160 dependencies: Sequence[str] = () |
Chunk.embed_model | str | None | Ver pruebasrc/docu/core/contracts.py#L161-L161161 embed_model: str | None = None |
Chunk.chunker | str | Ver pruebasrc/docu/core/contracts.py#L162-L162162 chunker: str = "ast-v2" |
Chunk.schema_version | str | Ver pruebasrc/docu/core/contracts.py#L163-L163163 schema_version: str = SCHEMA_VERSION |
Claim.text | str | Ver pruebasrc/docu/core/contracts.py#L210-L210210 text: str |
Claim.evidence | Sequence[str] | Ver pruebasrc/docu/core/contracts.py#L211-L211211 evidence: Sequence[str] = () |
ContentNode.node_id | str | Ver pruebasrc/docu/core/contracts.py#L226-L226226 node_id: str |
ContentNode.kind | str | Ver pruebasrc/docu/core/contracts.py#L227-L227227 kind: str |
ContentNode.title | str | Ver pruebasrc/docu/core/contracts.py#L228-L228228 title: str |
ContentNode.claims | list[Claim] | Ver pruebasrc/docu/core/contracts.py#L229-L229229 claims: list[Claim] = field(default_factory=list) |
ContentNode.levels | tuple[str, ...] | Ver pruebasrc/docu/core/contracts.py#L230-L230230 levels: tuple[str, ...] = ("l1",) |
ContentNode.state | DocState | Ver pruebasrc/docu/core/contracts.py#L231-L231231 state: DocState = DocState.FRESH |
ContentNode.confidence | float | Ver pruebasrc/docu/core/contracts.py#L232-L232232 confidence: float = 0.0 |
ContentNode.rendered | dict[str, str] | Ver pruebasrc/docu/core/contracts.py#L233-L233233 rendered: dict[str, str] = field(default_factory=dict) |
ContentNode.schema_version | str | Ver pruebasrc/docu/core/contracts.py#L234-L234234 schema_version: str = SCHEMA_VERSION |
Metrics.accuracy | float | Ver pruebasrc/docu/core/contracts.py#L251-L251251 accuracy: float |
Metrics.completeness | float | Ver pruebasrc/docu/core/contracts.py#L252-L252252 completeness: float |
Metrics.attribution | float | Ver pruebasrc/docu/core/contracts.py#L253-L253253 attribution: float |
Metrics.conciseness | float | Ver pruebasrc/docu/core/contracts.py#L254-L254254 conciseness: float |
Metrics.freshness | float | Ver pruebasrc/docu/core/contracts.py#L255-L255255 freshness: float = 10.0 |
Metrics.cost_usd | float | Ver pruebasrc/docu/core/contracts.py#L256-L256256 cost_usd: float = 0.0 |
Metrics.unsupported_claims | int | Ver pruebasrc/docu/core/contracts.py#L257-L257257 unsupported_claims: int = 0 |
Metrics.schema_version | str | Ver pruebasrc/docu/core/contracts.py#L258-L258258 schema_version: str = SCHEMA_VERSION |
GateDecision.outcome | GateOutcome | Ver pruebasrc/docu/core/contracts.py#L265-L265265 outcome: GateOutcome |
GateDecision.reasons | tuple[str, ...] | Ver pruebasrc/docu/core/contracts.py#L266-L266266 reasons: tuple[str, ...] = () |
RunRecord.run_id | str | Ver pruebasrc/docu/core/contracts.py#L285-L285285 run_id: str |
RunRecord.project | str | Ver pruebasrc/docu/core/contracts.py#L286-L286286 project: str |
RunRecord.commit | str | None | Ver pruebasrc/docu/core/contracts.py#L287-L287287 commit: str | None |
RunRecord.mode | Mode | Ver pruebasrc/docu/core/contracts.py#L288-L288288 mode: Mode |
RunRecord.started_at | datetime | Ver pruebasrc/docu/core/contracts.py#L289-L289289 started_at: datetime |
RunRecord.finished_at | datetime | None | Ver pruebasrc/docu/core/contracts.py#L290-L290290 finished_at: datetime | None = None |
RunRecord.versions | dict[str, str] | Ver pruebasrc/docu/core/contracts.py#L291-L291291 versions: dict[str, str] = field(default_factory=dict) |
RunRecord.metrics | Metrics | None | Ver pruebasrc/docu/core/contracts.py#L292-L292292 metrics: Metrics | None = None |
RunRecord.gate | GateDecision | None | Ver pruebasrc/docu/core/contracts.py#L293-L293293 gate: GateDecision | None = None |
RunRecord.pages_written | int | Ver pruebasrc/docu/core/contracts.py#L294-L294294 pages_written: int = 0 |
RunRecord.pages_skipped | int | Ver pruebasrc/docu/core/contracts.py#L295-L295295 pages_skipped: int = 0 |
RunRecord.cost_usd | float | Ver pruebasrc/docu/core/contracts.py#L296-L296296 cost_usd: float = 0.0 |
RunRecord.errors | list[str] | Ver pruebasrc/docu/core/contracts.py#L297-L297297 errors: list[str] = field(default_factory=list) |
RunRecord.schema_version | str | Ver pruebasrc/docu/core/contracts.py#L298-L298298 schema_version: str = SCHEMA_VERSION |
FreshnessRecord.node_id | str | Ver pruebasrc/docu/core/contracts.py#L336-L336336 node_id: str |
FreshnessRecord.input_hash | str | Ver pruebasrc/docu/core/contracts.py#L337-L337337 input_hash: str |
FreshnessRecord.state | DocState | Ver pruebasrc/docu/core/contracts.py#L338-L338338 state: DocState |
FreshnessRecord.generated_at | datetime | Ver pruebasrc/docu/core/contracts.py#L339-L339339 generated_at: datetime |
FreshnessRecord.ttl_days | int | Ver pruebasrc/docu/core/contracts.py#L340-L340340 ttl_days: int = 90 |
FreshnessRecord.schema_version | str | Ver pruebasrc/docu/core/contracts.py#L341-L341341 schema_version: str = SCHEMA_VERSION |
Thresholds.accuracy | float | Ver pruebasrc/docu/core/policy.py#L23-L2323 accuracy: float = 8.5 |
Thresholds.completeness | float | Ver pruebasrc/docu/core/policy.py#L24-L2424 completeness: float = 9.0 |
Thresholds.attribution | float | Ver pruebasrc/docu/core/policy.py#L25-L2525 attribution: float = 9.5 |
Thresholds.conciseness | float | Ver pruebasrc/docu/core/policy.py#L26-L2626 conciseness: float = 7.5 |
Budget.max_cost_usd | float | Ver pruebasrc/docu/core/policy.py#L41-L4141 max_cost_usd: float = 3.0 |
Budget.max_seconds | float | Ver pruebasrc/docu/core/policy.py#L42-L4242 max_seconds: float = 900.0 |
Budget.max_pages | int | Ver pruebasrc/docu/core/policy.py#L43-L4343 max_pages: int = 40 |
Budget.max_llm_calls | int | Ver pruebasrc/docu/core/policy.py#L44-L4444 max_llm_calls: int = 120 |
Budget.spent_usd | float | Ver pruebasrc/docu/core/policy.py#L45-L4545 spent_usd: float = 0.0 |
Budget.elapsed_s | float | Ver pruebasrc/docu/core/policy.py#L46-L4646 elapsed_s: float = 0.0 |
Budget.pages_written | int | Ver pruebasrc/docu/core/policy.py#L47-L4747 pages_written: int = 0 |
Budget.llm_calls | int | Ver pruebasrc/docu/core/policy.py#L48-L4848 llm_calls: int = 0 |
GatePolicy.thresholds | Thresholds | Ver pruebasrc/docu/core/policy.py#L79-L7979 thresholds: Thresholds = field(default_factory=Thresholds) |
GatePolicy.require_zero_unsupported | bool | Ver pruebasrc/docu/core/policy.py#L80-L8080 require_zero_unsupported: bool = True |
GatePolicy.require_fresh | bool | Ver pruebasrc/docu/core/policy.py#L81-L8181 require_fresh: bool = True |
SourceAdapter.name | str | Ver pruebasrc/docu/core/ports.py#L21-L2121 name: str |
SourceAdapter.kind | type | Ver pruebasrc/docu/core/ports.py#L22-L2222 kind: type |
LangAdapter.language | str | Ver pruebasrc/docu/core/ports.py#L38-L3838 language: str |
LangAdapter.file_globs | Sequence[str] | Ver pruebasrc/docu/core/ports.py#L39-L3939 file_globs: Sequence[str] |
Chunker.name | str | Ver pruebasrc/docu/core/ports.py#L59-L5959 name: str |
Embedder.embedder_id | str | Ver pruebasrc/docu/core/ports.py#L72-L7272 embedder_id: str |
Embedder.dim | int | Ver pruebasrc/docu/core/ports.py#L73-L7373 dim: int |
VectorStore.store_id | str | Ver pruebasrc/docu/core/ports.py#L83-L8383 store_id: str |
Reranker.reranker_id | str | Ver pruebasrc/docu/core/ports.py#L101-L101101 reranker_id: str |
RenderAdapter.name | str | Ver pruebasrc/docu/core/ports.py#L114-L114114 name: str |
RenderAdapter.target | str | Ver pruebasrc/docu/core/ports.py#L115-L115115 target: str |
Judge.judge_id | str | Ver pruebasrc/docu/core/ports.py#L125-L125125 judge_id: str |
Judge.temperature | float | Ver pruebasrc/docu/core/ports.py#L126-L126126 temperature: float |
Publisher.publisher_id | str | Ver pruebasrc/docu/core/ports.py#L136-L136136 publisher_id: str |
Profile.project | str | Ver pruebasrc/docu/core/profile.py#L54-L5454 project: str |
Profile.mode | Mode | Ver pruebasrc/docu/core/profile.py#L55-L5555 mode: Mode = Mode.APPLY |
Profile.levels | tuple[str, ...] | Ver pruebasrc/docu/core/profile.py#L56-L5656 levels: tuple[str, ...] = ("l1", "l4") |
Profile.output_dir | str | Ver pruebasrc/docu/core/profile.py#L57-L5757 output_dir: str = "docs/generated" |
Profile.language | str | Ver pruebasrc/docu/core/profile.py#L58-L5858 language: str = "es" |
Profile.ttl_days | int | Ver pruebasrc/docu/core/profile.py#L59-L5959 ttl_days: int = 90 |
Profile.include | tuple[str, ...] | Ver pruebasrc/docu/core/profile.py#L60-L6060 include: tuple[str, ...] = () |
Profile.exclude | tuple[str, ...] | Ver pruebasrc/docu/core/profile.py#L61-L6161 exclude: tuple[str, ...] = DEFAULT_EXCLUDE |
Profile.thresholds | Thresholds | Ver pruebasrc/docu/core/profile.py#L62-L6262 thresholds: Thresholds = field(default_factory=Thresholds) |
Profile.glossary | Mapping[str, tuple[str, ...]] | Ver pruebasrc/docu/core/profile.py#L63-L6363 glossary: Mapping[str, tuple[str, ...]] = field(default_factory=dict) |
Profile.promotion_delta | float | Ver pruebasrc/docu/core/profile.py#L64-L6464 promotion_delta: float = 0.05 |
Profile.rollback_drop | float | Ver pruebasrc/docu/core/profile.py#L65-L6565 rollback_drop: float = 0.05 |
Profile.federate | bool | Ver pruebasrc/docu/core/profile.py#L66-L6666 federate: bool = False |
Profile.web_allowlist | tuple[str, ...] | Ver pruebasrc/docu/core/profile.py#L67-L6767 web_allowlist: tuple[str, ...] = () |
Profile.web_urls | tuple[str, ...] | Ver pruebasrc/docu/core/profile.py#L68-L6868 web_urls: tuple[str, ...] = () |
Profile.path | Path | None | Ver pruebasrc/docu/core/profile.py#L69-L6969 path: Path | None = None |
Profile.raw | Mapping[str, object] | Ver pruebasrc/docu/core/profile.py#L70-L7070 raw: Mapping[str, object] = field(default_factory=dict) |
Change.field | str | Ver pruebasrc/docu/core/profile.py#L321-L321321 field: str |
Change.before | object | Ver pruebasrc/docu/core/profile.py#L322-L322322 before: object |
Change.after | object | Ver pruebasrc/docu/core/profile.py#L323-L323323 after: object |
Change.reason | str | Ver pruebasrc/docu/core/profile.py#L324-L324324 reason: str |
Change.applied | bool | Ver pruebasrc/docu/core/profile.py#L325-L325325 applied: bool = True |
CleanPlan.documents | list[Path] | Ver pruebasrc/docu/delivery/cleanup.py#L47-L4747 documents: list[Path] = field(default_factory=list) |
CleanPlan.artifacts | list[Path] | Ver pruebasrc/docu/delivery/cleanup.py#L48-L4848 artifacts: list[Path] = field(default_factory=list) |
CleanPlan.state | list[Path] | Ver pruebasrc/docu/delivery/cleanup.py#L49-L4949 state: list[Path] = field(default_factory=list) |
CleanPlan.ledger | list[Path] | Ver pruebasrc/docu/delivery/cleanup.py#L50-L5050 ledger: list[Path] = field(default_factory=list) |
CleanPlan.warnings | list[str] | Ver pruebasrc/docu/delivery/cleanup.py#L51-L5151 warnings: list[str] = field(default_factory=list) |
ResolvedOptions.profile | Profile | None | Ver pruebasrc/docu/delivery/cli.py#L292-L292292 profile: Profile | None |
ResolvedOptions.project | str | Ver pruebasrc/docu/delivery/cli.py#L293-L293293 project: str |
ResolvedOptions.levels | tuple[str, ...] | Ver pruebasrc/docu/delivery/cli.py#L294-L294294 levels: tuple[str, ...] |
ResolvedOptions.out_dir | Path | Ver pruebasrc/docu/delivery/cli.py#L295-L295295 out_dir: Path |
ResolvedOptions.ttl_days | int | Ver pruebasrc/docu/delivery/cli.py#L296-L296296 ttl_days: int |
ResolvedOptions.include | tuple[str, ...] | Ver pruebasrc/docu/delivery/cli.py#L297-L297297 include: tuple[str, ...] |
ResolvedOptions.exclude | tuple[str, ...] | Ver pruebasrc/docu/delivery/cli.py#L298-L298298 exclude: tuple[str, ...] |
ResolvedOptions.thresholds | Thresholds | Ver pruebasrc/docu/delivery/cli.py#L299-L299299 thresholds: Thresholds |
ResolvedOptions.manifest | Path | None | Ver pruebasrc/docu/delivery/cli.py#L300-L300300 manifest: Path | None |
_Handler.server_version | sin tipo declarado | Ver pruebasrc/docu/delivery/http_server.py#L27-L2727 server_version = "docu-mcp-http/0.1" |
_Handler.mcp | McpServer | Ver pruebasrc/docu/delivery/http_server.py#L28-L2828 mcp: McpServer # inyectado por clase antes de servir |
ProjectRef.name | str | Ver pruebasrc/docu/delivery/mcp_server.py#L167-L167167 name: str |
ProjectRef.root | Path | Ver pruebasrc/docu/delivery/mcp_server.py#L168-L168168 root: Path |
ProjectRef.docs_dir | Path | Ver pruebasrc/docu/delivery/mcp_server.py#L169-L169169 docs_dir: Path |
McpServer.root | Path | Ver pruebasrc/docu/delivery/mcp_server.py#L219-L219219 root: Path = Path(".") |
McpServer.docs_dir | Path | Ver pruebasrc/docu/delivery/mcp_server.py#L220-L220220 docs_dir: Path = Path("docs/generated") |
McpServer.manifest_path | Path | None | Ver pruebasrc/docu/delivery/mcp_server.py#L221-L221221 manifest_path: Path | None = None |
McpServer.profile_path | Path | None | Ver pruebasrc/docu/delivery/mcp_server.py#L222-L222222 profile_path: Path | None = None |
McpServer.workspace | Path | None | Ver pruebasrc/docu/delivery/mcp_server.py#L223-L223223 workspace: Path | None = None |
McpServer.dense | bool | Ver pruebasrc/docu/delivery/mcp_server.py#L224-L224224 dense: bool = True |
McpServer._refs | dict[str, ProjectRef] | Ver pruebasrc/docu/delivery/mcp_server.py#L225-L225225 _refs: dict[str, ProjectRef] = field(default_factory=dict, init=False, repr=False) |
McpServer._indexes | dict[str, DocIndex] | Ver pruebasrc/docu/delivery/mcp_server.py#L226-L226226 _indexes: dict[str, DocIndex] = field(default_factory=dict, init=False, repr=False) |
McpServer._code_indexes | dict[str, object] | Ver pruebasrc/docu/delivery/mcp_server.py#L227-L227227 _code_indexes: dict[str, object] = field(default_factory=dict, init=False, repr=False) |
Diagram.name | str | Ver pruebasrc/docu/generate/diagrams.py#L43-L4343 name: str |
Diagram.kind | str | Ver pruebasrc/docu/generate/diagrams.py#L44-L4444 kind: str |
Diagram.mermaid | str | Ver pruebasrc/docu/generate/diagrams.py#L45-L4545 mermaid: str |
Diagram.note | str | Ver pruebasrc/docu/generate/diagrams.py#L46-L4646 note: str = "" |
DocSection.path | str | Ver pruebasrc/docu/generate/docs_evidence.py#L52-L5252 path: str |
DocSection.title | str | Ver pruebasrc/docu/generate/docs_evidence.py#L53-L5353 title: str |
DocSection.body | str | Ver pruebasrc/docu/generate/docs_evidence.py#L54-L5454 body: str |
DocSection.line_start | int | Ver pruebasrc/docu/generate/docs_evidence.py#L55-L5555 line_start: int |
DocSection.line_end | int | Ver pruebasrc/docu/generate/docs_evidence.py#L56-L5656 line_end: int |
Fact.kind | str | Ver pruebasrc/docu/generate/facts.py#L32-L3232 kind: str |
Fact.subject | str | Ver pruebasrc/docu/generate/facts.py#L33-L3333 subject: str |
Fact.detail | str | Ver pruebasrc/docu/generate/facts.py#L34-L3434 detail: str |
Fact.citation | str | Ver pruebasrc/docu/generate/facts.py#L35-L3535 citation: str |
Fact.attributes | Mapping[str, str] | Ver pruebasrc/docu/generate/facts.py#L36-L3636 attributes: Mapping[str, str] = field(default_factory=dict) |
Narrative.intent | list[Fact] | Ver pruebasrc/docu/generate/narrative.py#L51-L5151 intent: list[Fact] = field(default_factory=list) |
Narrative.decisions | list[Fact] | Ver pruebasrc/docu/generate/narrative.py#L52-L5252 decisions: list[Fact] = field(default_factory=list) |
Narrative.intro | str | Ver pruebasrc/docu/generate/narrative.py#L53-L5353 intro: str = "" |
GeneratedDoc.level | str | Ver pruebasrc/docu/generate/pipeline.py#L92-L9292 level: str |
GeneratedDoc.path | Path | Ver pruebasrc/docu/generate/pipeline.py#L93-L9393 path: Path |
GeneratedDoc.content | str | Ver pruebasrc/docu/generate/pipeline.py#L94-L9494 content: str |
GenerationResult.project | str | Ver pruebasrc/docu/generate/pipeline.py#L99-L9999 project: str |
GenerationResult.docs | tuple[GeneratedDoc, ...] | Ver pruebasrc/docu/generate/pipeline.py#L100-L100100 docs: tuple[GeneratedDoc, ...] |
GenerationResult.facts | tuple[Fact, ...] | Ver pruebasrc/docu/generate/pipeline.py#L101-L101101 facts: tuple[Fact, ...] |
GenerationResult.sources | Mapping[str, str] | Ver pruebasrc/docu/generate/pipeline.py#L102-L102102 sources: Mapping[str, str] |
GenerationResult.metrics | Metrics | Ver pruebasrc/docu/generate/pipeline.py#L103-L103103 metrics: Metrics |
GenerationResult.gate | GateDecision | Ver pruebasrc/docu/generate/pipeline.py#L104-L104104 gate: GateDecision |
GenerationResult.elapsed_s | float | Ver pruebasrc/docu/generate/pipeline.py#L105-L105105 elapsed_s: float |
GenerationResult.unsupported | tuple[Fact, ...] | Ver pruebasrc/docu/generate/pipeline.py#L106-L106106 unsupported: tuple[Fact, ...] = field(default_factory=tuple) |
GenerationResult.states | Mapping[str, DocState] | Ver pruebasrc/docu/generate/pipeline.py#L107-L107107 states: Mapping[str, DocState] = field(default_factory=dict) |
GenerationResult.manifest_path | Path | None | Ver pruebasrc/docu/generate/pipeline.py#L108-L108108 manifest_path: Path | None = None |
GenerationResult.applicability | Mapping[str, bool] | Ver pruebasrc/docu/generate/pipeline.py#L109-L109109 applicability: Mapping[str, bool] = field(default_factory=dict) |
GenerationResult.unsupported_languages | Mapping[str, int] | Ver pruebasrc/docu/generate/pipeline.py#L110-L110110 unsupported_languages: Mapping[str, int] = field(default_factory=dict) |
GenerationResult.diagrams | tuple[str, ...] | Ver pruebasrc/docu/generate/pipeline.py#L111-L111111 diagrams: tuple[str, ...] = field(default_factory=tuple) |
GenerationResult.dry_run | bool | Ver pruebasrc/docu/generate/pipeline.py#L112-L112112 dry_run: bool = False |
ProseResponse.reviewer | str | Ver pruebasrc/docu/generate/prose.py#L54-L5454 reviewer: str = "" |
ProseResponse.sections | dict[str, list[dict[str, object]]] | Ver pruebasrc/docu/generate/prose.py#L55-L5555 sections: dict[str, list[dict[str, object]]] = field(default_factory=dict) |
ProseResponse.errors | list[str] | Ver pruebasrc/docu/generate/prose.py#L56-L5656 errors: list[str] = field(default_factory=list) |
ProseResponse.warnings | list[str] | Ver pruebasrc/docu/generate/prose.py#L57-L5757 warnings: list[str] = field(default_factory=list) |
Verdict.judge | str | Ver pruebasrc/docu/generate/prose.py#L68-L6868 judge: str = "" |
Verdict.score | float | Ver pruebasrc/docu/generate/prose.py#L69-L6969 score: float = 0.0 |
Verdict.criteria | dict[str, float] | Ver pruebasrc/docu/generate/prose.py#L70-L7070 criteria: dict[str, float] = field(default_factory=dict) |
Verdict.issues | list[str] | Ver pruebasrc/docu/generate/prose.py#L71-L7171 issues: list[str] = field(default_factory=list) |
Verdict.errors | list[str] | Ver pruebasrc/docu/generate/prose.py#L72-L7272 errors: list[str] = field(default_factory=list) |
SymbolChunker.name | str | Ver pruebasrc/docu/index/chunker.py#L49-L4949 name: str = DEFAULT_CHUNKER |
SymbolChunker.max_tokens | int | Ver pruebasrc/docu/index/chunker.py#L50-L5050 max_tokens: int = 1024 |
SymbolChunker.overlap_tokens | int | Ver pruebasrc/docu/index/chunker.py#L51-L5151 overlap_tokens: int = 128 |
InputComponents.source_content | str | Ver pruebasrc/docu/index/freshness.py#L29-L2929 source_content: str |
InputComponents.deps_signature | str | Ver pruebasrc/docu/index/freshness.py#L30-L3030 deps_signature: str |
InputComponents.template | str | Ver pruebasrc/docu/index/freshness.py#L31-L3131 template: str |
InputComponents.embedder | str | Ver pruebasrc/docu/index/freshness.py#L32-L3232 embedder: str |
InputComponents.chunker | str | Ver pruebasrc/docu/index/freshness.py#L33-L3333 chunker: str |
InputComponents.profile | str | Ver pruebasrc/docu/index/freshness.py#L34-L3434 profile: str |
IgnoreRule.raw | str | Ver pruebasrc/docu/index/ignore.py#L19-L1919 raw: str |
IgnoreRule.pattern | str | Ver pruebasrc/docu/index/ignore.py#L20-L2020 pattern: str |
IgnoreRule.negate | bool | Ver pruebasrc/docu/index/ignore.py#L21-L2121 negate: bool |
IgnoreRule.directory_only | bool | Ver pruebasrc/docu/index/ignore.py#L22-L2222 directory_only: bool |
IgnoreRule.anchored | bool | Ver pruebasrc/docu/index/ignore.py#L23-L2323 anchored: bool |
IgnoreRule.regex | re.Pattern[str] | Ver pruebasrc/docu/index/ignore.py#L24-L2424 regex: re.Pattern[str] |
DocEntry.level | str | Ver pruebasrc/docu/index/manifest.py#L36-L3636 level: str |
DocEntry.path | str | Ver pruebasrc/docu/index/manifest.py#L37-L3737 path: str |
DocEntry.input_hash | str | Ver pruebasrc/docu/index/manifest.py#L38-L3838 input_hash: str |
DocEntry.generated_at | str | Ver pruebasrc/docu/index/manifest.py#L39-L3939 generated_at: str |
DocEntry.content_hash | str | Ver pruebasrc/docu/index/manifest.py#L40-L4040 content_hash: str |
DocEntry.ttl_days | int | Ver pruebasrc/docu/index/manifest.py#L41-L4141 ttl_days: int = 90 |
DocEntry.sources | Mapping[str, str] | Ver pruebasrc/docu/index/manifest.py#L42-L4242 sources: Mapping[str, str] = field(default_factory=dict) |
Manifest.project | str | Ver pruebasrc/docu/index/manifest.py#L75-L7575 project: str |
Manifest.docs | list[DocEntry] | Ver pruebasrc/docu/index/manifest.py#L76-L7676 docs: list[DocEntry] = field(default_factory=list) |
Manifest.versions | Mapping[str, str] | Ver pruebasrc/docu/index/manifest.py#L77-L7777 versions: Mapping[str, str] = field(default_factory=lambda: dict(DEFAULT_VERSIONS)) |
Manifest.schema_version | str | Ver pruebasrc/docu/index/manifest.py#L78-L7878 schema_version: str = MANIFEST_VERSION |
DetectedPackage.name | str | Ver pruebasrc/docu/index/packages.py#L25-L2525 name: str |
DetectedPackage.language | str | Ver pruebasrc/docu/index/packages.py#L26-L2626 language: str |
DetectedPackage.files | tuple[str, ...] | Ver pruebasrc/docu/index/packages.py#L27-L2727 files: tuple[str, ...] |
DetectedPackage.declaration | str | Ver pruebasrc/docu/index/packages.py#L28-L2828 declaration: str # ruta#L inicio-L fin de la declaración |
PdfDocument.rel | str | Ver pruebasrc/docu/index/pdfdocs.py#L25-L2525 rel: str |
PdfDocument.pages | int | Ver pruebasrc/docu/index/pdfdocs.py#L26-L2626 pages: int |
PdfDocument.chars | int | Ver pruebasrc/docu/index/pdfdocs.py#L27-L2727 chars: int |
PdfDocument.method | str | Ver pruebasrc/docu/index/pdfdocs.py#L28-L2828 method: str |
PdfDocument.status | str | Ver pruebasrc/docu/index/pdfdocs.py#L29-L2929 status: str |
PdfDocument.usable | bool | Ver pruebasrc/docu/index/pdfdocs.py#L30-L3030 usable: bool |
PdfDocument.warnings | tuple[str, ...] | Ver pruebasrc/docu/index/pdfdocs.py#L31-L3131 warnings: tuple[str, ...] = () |
WebDocument.url | str | Ver pruebasrc/docu/index/webdocs.py#L19-L1919 url: str |
WebDocument.rel | str | Ver pruebasrc/docu/index/webdocs.py#L20-L2020 rel: str |
WebDocument.sha | str | Ver pruebasrc/docu/index/webdocs.py#L21-L2121 sha: str |
WebDocument.captured_at | str | Ver pruebasrc/docu/index/webdocs.py#L22-L2222 captured_at: str |
WebDocument.lines | int | Ver pruebasrc/docu/index/webdocs.py#L23-L2323 lines: int |
WebDocument.chars | int | Ver pruebasrc/docu/index/webdocs.py#L24-L2424 chars: int |
WebDocument.usable | bool | Ver pruebasrc/docu/index/webdocs.py#L25-L2525 usable: bool |
WebDocument.error | str | Ver pruebasrc/docu/index/webdocs.py#L26-L2626 error: str = "" |
FederationPayload.data | Mapping[str, object] | Ver pruebasrc/docu/learn/federation.py#L34-L3434 data: Mapping[str, object] |
Pattern.pattern_id | str | Ver pruebasrc/docu/learn/patterns.py#L28-L2828 pattern_id: str |
Pattern.stack | str | Ver pruebasrc/docu/learn/patterns.py#L29-L2929 stack: str |
Pattern.kind | str | Ver pruebasrc/docu/learn/patterns.py#L30-L3030 kind: str # "profile_default" | "glossary_entry" | "failure_avoidance" |
Pattern.metrics | Mapping[str, float] | Ver pruebasrc/docu/learn/patterns.py#L31-L3131 metrics: Mapping[str, float] = field(default_factory=dict) |
Pattern.runs | int | Ver pruebasrc/docu/learn/patterns.py#L32-L3232 runs: int = 0 |
Pattern.notes | str | Ver pruebasrc/docu/learn/patterns.py#L33-L3333 notes: str = "" |
PatternLibrary.patterns | dict[str, Pattern] | Ver pruebasrc/docu/learn/patterns.py#L62-L6262 patterns: dict[str, Pattern] = field(default_factory=dict) |
PatternLibrary.history | list[dict[str, object]] | Ver pruebasrc/docu/learn/patterns.py#L63-L6363 history: list[dict[str, object]] = field(default_factory=list) |
PatternLibrary.version | str | Ver pruebasrc/docu/learn/patterns.py#L64-L6464 version: str = "0" |
PatternLibrary.schema_version | str | Ver pruebasrc/docu/learn/patterns.py#L65-L6565 schema_version: str = SCHEMA_VERSION |
Candidate.pattern | Pattern | Ver pruebasrc/docu/learn/patterns.py#L159-L159159 pattern: Pattern |
Candidate.reasons | Sequence[str] | Ver pruebasrc/docu/learn/patterns.py#L160-L160160 reasons: Sequence[str] = () |
Decision.action | str | Ver pruebasrc/docu/learn/promotion.py#L22-L2222 action: str |
Decision.pattern_id | str | Ver pruebasrc/docu/learn/promotion.py#L23-L2323 pattern_id: str |
Decision.delta | float | Ver pruebasrc/docu/learn/promotion.py#L24-L2424 delta: float |
Decision.reasons | Sequence[str] | Ver pruebasrc/docu/learn/promotion.py#L25-L2525 reasons: Sequence[str] = field(default_factory=tuple) |
Page.name | str | Ver pruebasrc/docu/publish/site.py#L125-L125125 name: str |
Page.title | str | Ver pruebasrc/docu/publish/site.py#L126-L126126 title: str |
Page.html | str | Ver pruebasrc/docu/publish/site.py#L127-L127127 html: str |
CodeChunk.path | str | Ver pruebasrc/docu/retrieve/hybrid.py#L36-L3636 path: str |
CodeChunk.start | int | Ver pruebasrc/docu/retrieve/hybrid.py#L37-L3737 start: int |
CodeChunk.end | int | Ver pruebasrc/docu/retrieve/hybrid.py#L38-L3838 end: int |
CodeChunk.text | str | Ver pruebasrc/docu/retrieve/hybrid.py#L39-L3939 text: str |
CodeChunk.symbol | str | None | Ver pruebasrc/docu/retrieve/hybrid.py#L40-L4040 symbol: str | None |
CodeChunk.kind | str | Ver pruebasrc/docu/retrieve/hybrid.py#L41-L4141 kind: str |
CodeChunk.tokens | tuple[str, ...] | Ver pruebasrc/docu/retrieve/hybrid.py#L42-L4242 tokens: tuple[str, ...] = () |
CodeChunk.exact_names | tuple[str, ...] | Ver pruebasrc/docu/retrieve/hybrid.py#L43-L4343 exact_names: tuple[str, ...] = () |
CodeIndex.chunks | list[CodeChunk] | Ver pruebasrc/docu/retrieve/hybrid.py#L116-L116116 chunks: list[CodeChunk] = field(default_factory=list) |
CodeIndex.embedder | object | None | Ver pruebasrc/docu/retrieve/hybrid.py#L117-L117117 embedder: object | None = None |
CodeIndex.glossary | Mapping[str, Sequence[str]] | None | Ver pruebasrc/docu/retrieve/hybrid.py#L118-L118118 glossary: Mapping[str, Sequence[str]] | None = None |
CodeIndex.k1 | float | Ver pruebasrc/docu/retrieve/hybrid.py#L119-L119119 k1: float = 1.5 |
CodeIndex.b | float | Ver pruebasrc/docu/retrieve/hybrid.py#L120-L120120 b: float = 0.75 |
CodeIndex._df | dict[str, int] | Ver pruebasrc/docu/retrieve/hybrid.py#L121-L121121 _df: dict[str, int] = field(default_factory=dict, init=False, repr=False) |
CodeIndex._lengths | list[int] | Ver pruebasrc/docu/retrieve/hybrid.py#L122-L122122 _lengths: list[int] = field(default_factory=list, init=False, repr=False) |
CodeIndex._avgdl | float | Ver pruebasrc/docu/retrieve/hybrid.py#L123-L123123 _avgdl: float = field(default=0.0, init=False, repr=False) |
CodeIndex._by_name | dict[str, list[CodeChunk]] | Ver pruebasrc/docu/retrieve/hybrid.py#L124-L124124 _by_name: dict[str, list[CodeChunk]] = field(default_factory=dict, init=False, repr=False) |
CodeIndex._vectors | list[Sequence[float]] | Ver pruebasrc/docu/retrieve/hybrid.py#L125-L125125 _vectors: list[Sequence[float]] = field(default_factory=list, init=False, repr=False) |
CodeIndex._dense_ready | bool | Ver pruebasrc/docu/retrieve/hybrid.py#L126-L126126 _dense_ready: bool = field(default=False, init=False, repr=False) |
Section.document | str | Ver pruebasrc/docu/retrieve/search.py#L71-L7171 document: str |
Section.heading | str | Ver pruebasrc/docu/retrieve/search.py#L72-L7272 heading: str |
Section.body | str | Ver pruebasrc/docu/retrieve/search.py#L73-L7373 body: str |
Section.level | str | Ver pruebasrc/docu/retrieve/search.py#L74-L7474 level: str = "" |
Section.tokens | tuple[str, ...] | Ver pruebasrc/docu/retrieve/search.py#L75-L7575 tokens: tuple[str, ...] = () |
Section.citations | tuple[str, ...] | Ver pruebasrc/docu/retrieve/search.py#L76-L7676 citations: tuple[str, ...] = () |
DocIndex.sections | list[Section] | Ver pruebasrc/docu/retrieve/search.py#L129-L129129 sections: list[Section] = field(default_factory=list) |
DocIndex.k1 | float | Ver pruebasrc/docu/retrieve/search.py#L130-L130130 k1: float = 1.5 |
DocIndex.b | float | Ver pruebasrc/docu/retrieve/search.py#L131-L131131 b: float = 0.75 |
DocIndex.glossary | Mapping[str, Sequence[str]] | None | Ver pruebasrc/docu/retrieve/search.py#L132-L132132 glossary: Mapping[str, Sequence[str]] | None = None |
DocIndex._df | dict[str, int] | Ver pruebasrc/docu/retrieve/search.py#L133-L133133 _df: dict[str, int] = field(default_factory=dict, init=False) |
DocIndex._avgdl | float | Ver pruebasrc/docu/retrieve/search.py#L134-L134134 _avgdl: float = field(default=0.0, init=False) |
Tipos 97
| Qué | Detalle | Evidencia |
|---|---|---|
Segment | class | Ver pruebaeval/harness.py#L116-L129Anotaciones: @dataclass116class 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 |
BM25 | class | Ver pruebaeval/harness.py#L260-L302Anotaciones: @dataclass260class 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]]: |
AutoIndex | class | Ver pruebaeval/harness.py#L429-L449Anotaciones: @dataclass429class 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) |
HybridIndex | class | Ver pruebaeval/harness.py#L453-L534Anotaciones: @dataclass453class 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]] |
SymbolIndex | class | Ver pruebaeval/harness.py#L538-L594Anotaciones: @dataclass538class 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 |
Expected | class | Ver pruebaeval/harness.py#L601-L605Anotaciones: @dataclass601class Expected: 602 path: str 603 symbol: str | None = None 604 lines: tuple[int, int] | None = None 605 optional: bool = False |
Case | class | Ver pruebaeval/harness.py#L609-L626Anotaciones: @dataclass609class 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 |
CaseResult | class | Ver pruebaeval/harness.py#L630-L641Anotaciones: @dataclass630class 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 |
Report | class | Ver pruebaeval/harness.py#L645-L776Anotaciones: @dataclass645class 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}) |
OnnxEmbedder | class | Ver pruebasrc/docu/adapters/embedders/onnx_local.py#L40-L104Anotaciones: @dataclass40class 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"] |
Lines | class | Ver pruebasrc/docu/adapters/langs/_braces.py#L233-L250233class 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 |
_Lines | class | Ver pruebasrc/docu/adapters/langs/java.py#L144-L161144class _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 |
JavaLangAdapter | class | Ver pruebasrc/docu/adapters/langs/java.py#L366-L590Anotaciones: @dataclass366class 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, |
PythonLangAdapter | class | Ver pruebasrc/docu/adapters/langs/python.py#L19-L200Anotaciones: @dataclass19class 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 ) |
TypeScriptLangAdapter | class | Ver pruebasrc/docu/adapters/langs/typescript.py#L87-L423Anotaciones: @dataclass87class 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, |
PdfError | class | Ver pruebasrc/docu/adapters/sources/pdf.py#L36-L3736class PdfError(ValueError): 37 """El archivo no es un PDF legible por este extractor.""" |
PdfPage | class | Ver pruebasrc/docu/adapters/sources/pdf.py#L119-L121Anotaciones: @dataclass119class PdfPage: 120 number: int 121 text: str |
PdfText | class | Ver pruebasrc/docu/adapters/sources/pdf.py#L125-L145Anotaciones: @dataclass125class 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)" |
WebError | class | Ver pruebasrc/docu/adapters/sources/web.py#L38-L3938class WebError(ValueError): 39 """La fuente web no se pudo capturar con las garantías exigidas.""" |
Snapshot | class | Ver pruebasrc/docu/adapters/sources/web.py#L43-L62Anotaciones: @dataclass43class 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] |
_TextExtractor | class | Ver pruebasrc/docu/adapters/sources/web.py#L65-L10165class _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) |
Check | class | Ver pruebasrc/docu/audit/verify.py#L40-L68Anotaciones: @dataclass40class 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 } |
AuditReport | class | Ver pruebasrc/docu/audit/verify.py#L72-L143Anotaciones: @dataclass72class 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 "" |
Discrepancy | class | Ver pruebasrc/docu/conformance/drift.py#L38-L62Anotaciones: @dataclass38class 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 } |
DriftReport | class | Ver pruebasrc/docu/conformance/drift.py#L66-L118Anotaciones: @dataclass66class 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" |
RouteFact | class | Ver pruebasrc/docu/conformance/drift.py#L125-L130Anotaciones: @dataclass125class 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 |
CodeFacts | class | Ver pruebasrc/docu/conformance/drift.py#L134-L137Anotaciones: @dataclass134class CodeFacts: 135 routes: tuple[RouteFact, ...] 136 components: Mapping[str, str] # nombre de tipo -> cita 137 dependencies: tuple[tuple[str, str], ...] # (llamador, llamado) |
Route | class | Ver pruebasrc/docu/conformance/model.py#L31-L40Anotaciones: @dataclass31class 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 |
DeclaredComponent | class | Ver pruebasrc/docu/conformance/model.py#L44-L49Anotaciones: @dataclass44class DeclaredComponent: 45 name: str 46 kind: str = "component" 47 provides: tuple[Route, ...] = () 48 depends_on: tuple[str, ...] = () 49 source: str = "" |
ArchitectureModel | class | Ver pruebasrc/docu/conformance/model.py#L53-L79Anotaciones: @dataclass53class 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 |
SourceKind | class | Ver pruebasrc/docu/core/contracts.py#L36-L4336class 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" |
SymbolKind | class | Ver pruebasrc/docu/core/contracts.py#L46-L5846class 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" |
DocState | class | Ver pruebasrc/docu/core/contracts.py#L61-L6961class 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" |
Mode | class | Ver pruebasrc/docu/core/contracts.py#L72-L7772class Mode(str, Enum): 73 """Grado de autonomia (Guia-v2.md §7).""" 74 75 PROPOSE = "propose" 76 APPLY = "apply" 77 PUBLISH = "publish" |
GateOutcome | class | Ver pruebasrc/docu/core/contracts.py#L80-L8580class GateOutcome(str, Enum): 81 """Resultado de evaluar las compuertas de calidad.""" 82 83 PUBLISH = "publish" 84 REVIEW = "review" 85 ABORT = "abort" |
Artifact | class | Ver pruebasrc/docu/core/contracts.py#L92-L115Anotaciones: @dataclass92class 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 ) |
Symbol | class | Ver pruebasrc/docu/core/contracts.py#L119-L135Anotaciones: @dataclass119class 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) |
Chunk | class | Ver pruebasrc/docu/core/contracts.py#L142-L197Anotaciones: @dataclass142class 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, |
Claim | class | Ver pruebasrc/docu/core/contracts.py#L204-L215Anotaciones: @dataclass204class 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 |
ContentNode | class | Ver pruebasrc/docu/core/contracts.py#L219-L241Anotaciones: @dataclass219class 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 |
Metrics | class | Ver pruebasrc/docu/core/contracts.py#L248-L258Anotaciones: @dataclass248class 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 |
GateDecision | class | Ver pruebasrc/docu/core/contracts.py#L262-L275Anotaciones: @dataclass262class 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 |
RunRecord | class | Ver pruebasrc/docu/core/contracts.py#L282-L326Anotaciones: @dataclass282class 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, |
FreshnessRecord | class | Ver pruebasrc/docu/core/contracts.py#L333-L345Anotaciones: @dataclass333class 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) |
BudgetExhausted | class | Ver pruebasrc/docu/core/policy.py#L15-L1615class BudgetExhausted(RuntimeError): 16 """Se agoto un presupuesto: la corrida entrega lo completo y deja `pending`, no texto degradado.""" |
Thresholds | class | Ver pruebasrc/docu/core/policy.py#L20-L34Anotaciones: @dataclass20class 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 } |
Budget | class | Ver pruebasrc/docu/core/policy.py#L38-L72Anotaciones: @dataclass38class 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) |
GatePolicy | class | Ver pruebasrc/docu/core/policy.py#L76-L104Anotaciones: @dataclass76class 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, ()) |
SourceAdapter | class | Ver pruebasrc/docu/core/ports.py#L18-L28Anotaciones: @runtime_checkable18class 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 ... |
LangAdapter | class | Ver pruebasrc/docu/core/ports.py#L32-L52Anotaciones: @runtime_checkable32class 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 ... |
Chunker | class | Ver pruebasrc/docu/core/ports.py#L56-L62Anotaciones: @runtime_checkable56class 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 ... |
Embedder | class | Ver pruebasrc/docu/core/ports.py#L69-L76Anotaciones: @runtime_checkable69class 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 ... |
VectorStore | class | Ver pruebasrc/docu/core/ports.py#L80-L94Anotaciones: @runtime_checkable80class 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 ... |
Reranker | class | Ver pruebasrc/docu/core/ports.py#L98-L104Anotaciones: @runtime_checkable98class 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 ... |
RenderAdapter | class | Ver pruebasrc/docu/core/ports.py#L111-L118Anotaciones: @runtime_checkable111class 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 ... |
Judge | class | Ver pruebasrc/docu/core/ports.py#L122-L129Anotaciones: @runtime_checkable122class 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 ... |
Publisher | class | Ver pruebasrc/docu/core/ports.py#L133-L145Anotaciones: @runtime_checkable133class 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 ... |
ProfileError | class | Ver pruebasrc/docu/core/profile.py#L46-L4746class ProfileError(ValueError): 47 """El perfil no cumple el esquema: mejor fallar que documentar con supuestos equivocados.""" |
Profile | class | Ver pruebasrc/docu/core/profile.py#L51-L107Anotaciones: @dataclass51class 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}, |
Change | class | Ver pruebasrc/docu/core/profile.py#L318-L332Anotaciones: @dataclass318class 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})" |
YamlError | class | Ver pruebasrc/docu/core/yamlmini.py#L14-L1514class YamlError(ValueError): 15 """El documento no pertenece al subconjunto soportado.""" |
CleanPlan | class | Ver pruebasrc/docu/delivery/cleanup.py#L44-L69Anotaciones: @dataclass44class 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 } |
_Parser | class | Ver pruebasrc/docu/delivery/cli.py#L56-L6756class _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) |
CliError | class | Ver pruebasrc/docu/delivery/cli.py#L280-L285280class 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 |
ResolvedOptions | class | Ver pruebasrc/docu/delivery/cli.py#L289-L300Anotaciones: @dataclass289class 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 |
ExitCode | class | Ver pruebasrc/docu/delivery/exit_codes.py#L8-L168class 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 |
_Handler | class | Ver pruebasrc/docu/delivery/http_server.py#L26-L8926class _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: |
ProjectRef | class | Ver pruebasrc/docu/delivery/mcp_server.py#L164-L188Anotaciones: @dataclass164class 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 |
ToolError | class | Ver pruebasrc/docu/delivery/mcp_server.py#L206-L207206class ToolError(Exception): 207 """Error de negocio del servidor: se devuelve como contenido de error, no como caída.""" |
McpServer | class | Ver pruebasrc/docu/delivery/mcp_server.py#L211-L626Anotaciones: @dataclass211class 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: |
Diagram | class | Ver pruebasrc/docu/generate/diagrams.py#L40-L50Anotaciones: @dataclass40class 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" |
DocSection | class | Ver pruebasrc/docu/generate/docs_evidence.py#L49-L73Anotaciones: @dataclass49class 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 ) |
Fact | class | Ver pruebasrc/docu/generate/facts.py#L29-L44Anotaciones: @dataclass29class 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 |
Narrative | class | Ver pruebasrc/docu/generate/narrative.py#L48-L57Anotaciones: @dataclass48class 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] |
GeneratedDoc | class | Ver pruebasrc/docu/generate/pipeline.py#L91-L94Anotaciones: @dataclass91class GeneratedDoc: 92 level: str 93 path: Path 94 content: str |
GenerationResult | class | Ver pruebasrc/docu/generate/pipeline.py#L98-L123Anotaciones: @dataclass98class 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 ) |
ProseResponse | class | Ver pruebasrc/docu/generate/prose.py#L51-L61Anotaciones: @dataclass51class 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) |
Verdict | class | Ver pruebasrc/docu/generate/prose.py#L65-L76Anotaciones: @dataclass65class 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 |
SymbolChunker | class | Ver pruebasrc/docu/index/chunker.py#L46-L220Anotaciones: @dataclass46class 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, |
InputComponents | class | Ver pruebasrc/docu/index/freshness.py#L26-L34Anotaciones: @dataclass26class 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 |
IgnoreRule | class | Ver pruebasrc/docu/index/ignore.py#L18-L24Anotaciones: @dataclass18class IgnoreRule: 19 raw: str 20 pattern: str 21 negate: bool 22 directory_only: bool 23 anchored: bool 24 regex: re.Pattern[str] |
DocEntry | class | Ver pruebasrc/docu/index/manifest.py#L33-L68Anotaciones: @dataclass33class 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) |
Manifest | class | Ver pruebasrc/docu/index/manifest.py#L72-L124Anotaciones: @dataclass72class 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 |
DetectedPackage | class | Ver pruebasrc/docu/index/packages.py#L22-L36Anotaciones: @dataclass22class 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 |
PdfDocument | class | Ver pruebasrc/docu/index/pdfdocs.py#L24-L50Anotaciones: @dataclass24class 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 ) |
WebDocument | class | Ver pruebasrc/docu/index/webdocs.py#L18-L45Anotaciones: @dataclass18class 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 ) |
FederationError | class | Ver pruebasrc/docu/learn/federation.py#L28-L2928class FederationError(RuntimeError): 29 """El payload no cumple la política de privacidad: se rechaza el envío.""" |
FederationPayload | class | Ver pruebasrc/docu/learn/federation.py#L33-L37Anotaciones: @dataclass33class 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) |
Pattern | class | Ver pruebasrc/docu/learn/patterns.py#L25-L55Anotaciones: @dataclass25class 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 ) |
PatternLibrary | class | Ver pruebasrc/docu/learn/patterns.py#L59-L142Anotaciones: @dataclass59class 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 |
Candidate | class | Ver pruebasrc/docu/learn/patterns.py#L156-L164Anotaciones: @dataclass156class 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 |
Decision | class | Ver pruebasrc/docu/learn/promotion.py#L21-L33Anotaciones: @dataclass21class 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}" |
Page | class | Ver pruebasrc/docu/publish/site.py#L124-L127Anotaciones: @dataclass124class Page: 125 name: str 126 title: str 127 html: str |
CodeChunk | class | Ver pruebasrc/docu/retrieve/hybrid.py#L33-L59Anotaciones: @dataclass33class 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 } |
CodeIndex | class | Ver pruebasrc/docu/retrieve/hybrid.py#L113-L253Anotaciones: @dataclass113class 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}), |
Section | class | Ver pruebasrc/docu/retrieve/search.py#L68-L89Anotaciones: @dataclass68class 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 } |
DocIndex | class | Ver pruebasrc/docu/retrieve/search.py#L126-L196Anotaciones: @dataclass126class 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é | Detalle | Evidencia |
|---|---|---|
_fuente | def _fuente(rutas: tuple[str, ...], tamano: int) -> ImageFont.FreeTypeFont | Ver pruebadocs/brand/make-cover.py#L39-L4339def _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) |
_espaciado | def _espaciado(dibujo: ImageDraw.ImageDraw, xy: tuple[int, int], texto: str, fuente, extra: int, fill) -> int | Ver pruebadocs/brand/make-cover.py#L46-L5246def _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) |
componer | def componer(frame: Path, destino: Path) -> Path | Ver pruebadocs/brand/make-cover.py#L55-L9755def 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 |
main | def main(argv: list[str]) -> int | Ver pruebadocs/brand/make-cover.py#L100-L104100def 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 |
_fold | def _fold(text: str) -> str | Ver pruebaeval/harness.py#L81-L8881def _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)) |
tokenize | def tokenize(text: str) -> list[str] | Ver pruebaeval/harness.py#L91-L10991def 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 |
_matches | def _matches(path: str, patterns: Sequence[str]) -> bool | Ver pruebaeval/harness.py#L132-L134132def _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_files | def discover_files(repo: Path, include: Sequence[str], exclude: Sequence[str]) -> list[str] | Ver pruebaeval/harness.py#L137-L146137def 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_segments | def _window_segments(repo: Path, rel: str, window: int, overlap: int) -> list[Segment] | Ver pruebaeval/harness.py#L149-L175149def _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_corpus | def build_corpus(repo: Path, include: Sequence[str]=..., exclude: Sequence[str]=..., window: int=..., overlap: int=...) -> list[Segment] | Ver pruebaeval/harness.py#L178-L188178def 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_names | def _exact_names(qualname: str | None) -> tuple[str, ...] | Ver pruebaeval/harness.py#L191-L197191def _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_corpus | def build_symbol_corpus(repo: Path, exclude: Sequence[str]=..., window: int=..., overlap: int=...) -> list[Segment] | Ver pruebaeval/harness.py#L200-L253200def 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 pruebaeval/harness.py#L270-L275270 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._idf | def _idf(self, term: str) -> float | Ver pruebaeval/harness.py#L277-L280277 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.scores | def scores(self, query: str) -> list[float] | Ver pruebaeval/harness.py#L282-L297282 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.search | def search(self, query: str, k: int=...) -> list[tuple[Segment, float]] | Ver pruebaeval/harness.py#L299-L302299 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_identifier | def _looks_like_identifier(query: str) -> bool | Ver pruebaeval/harness.py#L305-L401305def _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 |
_diversity | def _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 pruebaeval/harness.py#L404-L425404def _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 pruebaeval/harness.py#L442-L444442 def __post_init__(self) -> None: 443 self._symbols = SymbolIndex(segments=self.segments) 444 self._hybrid = HybridIndex(segments=self.segments, embedder=self.embedder) |
AutoIndex.search | def search(self, query: str, k: int=...) -> list[tuple[Segment, float]] | Ver pruebaeval/harness.py#L446-L449446 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 pruebaeval/harness.py#L471-L477471 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_channel | def _dense_channel(self, query: str, limit: int) -> list[Segment] | Ver pruebaeval/harness.py#L481-L492481 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_channel | def _exact_channel(self, terms: set[str]) -> list[Segment] | Ver pruebaeval/harness.py#L494-L506494 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_weights | def _channel_weights(self, query: str) -> tuple[float, float, float] | Ver pruebaeval/harness.py#L508-L515508 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.search | def search(self, query: str, k: int=...) -> list[tuple[Segment, float]] | Ver pruebaeval/harness.py#L517-L534517 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 pruebaeval/harness.py#L557-L561557 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_channel | def _exact_channel(self, terms: set[str]) -> list[Segment] | Ver pruebaeval/harness.py#L563-L577563 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.search | def search(self, query: str, k: int=...) -> list[tuple[Segment, float]] | Ver pruebaeval/harness.py#L579-L594579 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_paths | def required_paths(self) -> tuple[str, ...] | Ver pruebaeval/harness.py#L620-L621Anotaciones: @property620 def required_paths(self) -> tuple[str, ...]: 621 return tuple(e.path for e in self.expected if not e.optional) |
Case.retrieval_query | def retrieval_query(self, field: str=...) -> str | Ver pruebaeval/harness.py#L623-L626623 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._agg | def _agg(self, results: Sequence[CaseResult]) -> dict[str, float] | Ver pruebaeval/harness.py#L657-L672657 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.overall | def overall(self) -> dict[str, float] | Ver pruebaeval/harness.py#L675-L676Anotaciones: @property675 def overall(self) -> dict[str, float]: 676 return self._agg(self.results) |
Report.by_category | def by_category(self) -> dict[str, dict[str, float]] | Ver pruebaeval/harness.py#L678-L680678 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_mode | def by_mode(self) -> dict[str, dict[str, float]] | Ver pruebaeval/harness.py#L682-L685682 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_dict | def to_dict(self) -> dict[str, object] | Ver pruebaeval/harness.py#L687-L730687 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_markdown | def to_markdown(self) -> str | Ver pruebaeval/harness.py#L732-L776732 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 "—" |
_overlaps | def _overlaps(a: tuple[int, int], b: tuple[int, int]) -> bool | Ver pruebaeval/harness.py#L779-L780779def _overlaps(a: tuple[int, int], b: tuple[int, int]) -> bool: 780 return not (a[1] < b[0] or b[1] < a[0]) |
_query_mode | def _query_mode(case: Case) -> str | Ver pruebaeval/harness.py#L800-L815800def _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" |
evaluate | def evaluate(cases: Sequence[Case], index: object, k: int=..., query_field: str=..., expand: bool=...) -> list[CaseResult] | Ver pruebaeval/harness.py#L818-L897818def 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_id | def _validate_case_id(case: Case) -> list[str] | Ver pruebaeval/harness.py#L903-L912903def _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_set | def _validate_golden_set(cases: Sequence[Case]) -> list[str] | Ver pruebaeval/harness.py#L915-L953915def _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_golden | def load_golden(path: Path) -> tuple[str, str, list[Case]] | Ver pruebaeval/harness.py#L956-L985956def 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 |
run | def 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 pruebaeval/harness.py#L991-L1059991def 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) |
main | def main(argv: Sequence[str] | None=...) -> int | Ver pruebaeval/harness.py#L1062-L11061062def 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_dir | def resolve_model_dir(*roots) -> Path | None | Ver pruebasrc/docu/adapters/embedders/onnx_local.py#L20-L3620def 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.dim | def dim(self) -> int | Ver pruebasrc/docu/adapters/embedders/onnx_local.py#L53-L54Anotaciones: @property53 def dim(self) -> int: 54 return self._dim |
OnnxEmbedder.available | def available(self) -> bool | Ver pruebasrc/docu/adapters/embedders/onnx_local.py#L57-L60Anotaciones: @property57 def available(self) -> bool: 58 return (Path(self.model_dir) / "model.onnx").exists() and ( 59 Path(self.model_dir) / "tokenizer.json" 60 ).exists() |
OnnxEmbedder._load | def _load(self) -> None | Ver pruebasrc/docu/adapters/embedders/onnx_local.py#L62-L8362 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.embed | def embed(self, texts: Sequence[str]) -> list[list[float]] | Ver pruebasrc/docu/adapters/embedders/onnx_local.py#L85-L10485 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_normalize | def _mean_pool_normalize(token_vectors: Sequence[Sequence[float]], mask: Sequence[int]) -> list[float] | Ver pruebasrc/docu/adapters/embedders/onnx_local.py#L107-L122107def _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] |
cosine | def cosine(left: Sequence[float], right: Sequence[float]) -> float | Ver pruebasrc/docu/adapters/embedders/onnx_local.py#L125-L129125def 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_source | def mask_source(source: str) -> str | Ver pruebasrc/docu/adapters/langs/_braces.py#L12-L6812def 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_map | def depth_map(masked: str) -> list[int] | Ver pruebasrc/docu/adapters/langs/_braces.py#L71-L8171def 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_brace | def matching_brace(masked: str, open_index: int) -> int | Ver pruebasrc/docu/adapters/langs/_braces.py#L84-L9584def 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_braces | def mask_annotation_braces(masked: str) -> str | Ver pruebasrc/docu/adapters/langs/_braces.py#L98-L12498def 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_paren | def matching_paren(masked: str, open_index: int) -> int | Ver pruebasrc/docu/adapters/langs/_braces.py#L127-L138127def 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_callables | def iter_callables(masked: str, depth: list[int], level: int, start: int, end: int, skip: frozenset[str] | set[str] | tuple[str, ...]=...) | Ver pruebasrc/docu/adapters/langs/_braces.py#L141-L201141def 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_before | def annotations_before(source: str, name_start: int) -> str | Ver pruebasrc/docu/adapters/langs/_braces.py#L204-L230204def 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 pruebasrc/docu/adapters/langs/_braces.py#L236-L240236 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_of | def line_of(self, offset: int) -> int | Ver pruebasrc/docu/adapters/langs/_braces.py#L242-L250242 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_whitespace | def skip_whitespace(text: str, start: int, limit: int) -> int | Ver pruebasrc/docu/adapters/langs/_braces.py#L253-L258253def 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_start | def declaration_start(masked: str, depth: list[int], offset: int, floor: int, level: int) -> int | Ver pruebasrc/docu/adapters/langs/_braces.py#L261-L278261def 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_args | def strip_comment_args(text: str) -> str | Ver pruebasrc/docu/adapters/langs/_braces.py#L281-L282281def strip_comment_args(text: str) -> str: 282 return re.sub(r"//.*$", "", text, flags=re.MULTILINE) |
mask_source | def mask_source(source: str) -> str | Ver pruebasrc/docu/adapters/langs/java.py#L59-L11459def 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_map | def depth_map(masked: str) -> list[int] | Ver pruebasrc/docu/adapters/langs/java.py#L117-L127117def 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_brace | def matching_brace(masked: str, open_index: int) -> int | Ver pruebasrc/docu/adapters/langs/java.py#L130-L141130def 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 pruebasrc/docu/adapters/langs/java.py#L147-L151147 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_of | def line_of(self, offset: int) -> int | Ver pruebasrc/docu/adapters/langs/java.py#L153-L161153 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_names | def annotation_names(text: str) -> tuple[str, ...] | Ver pruebasrc/docu/adapters/langs/java.py#L164-L166164def 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_of | def route_of(annotation: str, args: str | None) -> tuple[str, str | None] | None | Ver pruebasrc/docu/adapters/langs/java.py#L169-L181169def 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_route | def class_level_route(text: str) -> str | None | Ver pruebasrc/docu/adapters/langs/java.py#L184-L190184def 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_paths | def join_paths(base: str | None, suffix: str | None) -> str | Ver pruebasrc/docu/adapters/langs/java.py#L193-L201193def 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_annotations | def _strip_annotations(text: str) -> str | Ver pruebasrc/docu/adapters/langs/java.py#L204-L205204def _strip_annotations(text: str) -> str: 205 return _ANNOTATION_RE.sub(" ", text) |
_java_fields | def _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 pruebasrc/docu/adapters/langs/java.py#L208-L267208def _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_fields | def _record_fields(masked: str, source: str, type_name: str, path: str, match_end: int, lines: _Lines) -> list[Symbol] | Ver pruebasrc/docu/adapters/langs/java.py#L270-L317270def _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_block | def _annotation_block(source: str, start: int, end: int) -> tuple[str, int] | Ver pruebasrc/docu/adapters/langs/java.py#L320-L331320def _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_start | def _declaration_start(masked: str, depth: list[int], offset: int, floor: int, level: int) -> int | Ver pruebasrc/docu/adapters/langs/java.py#L334-L351334def _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_whitespace | def _skip_whitespace(text: str, start: int, limit: int) -> int | Ver pruebasrc/docu/adapters/langs/java.py#L354-L359354def _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.symbols | def symbols(self, path: str, source: str) -> tuple[Symbol, ...] | Ver pruebasrc/docu/adapters/langs/java.py#L374-L469374 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._members | def _members(self) -> tuple[list[Symbol], list[Symbol]] | Ver pruebasrc/docu/adapters/langs/java.py#L471-L557471 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.imports | def imports(self, path: str, source: str) -> tuple[str, ...] | Ver pruebasrc/docu/adapters/langs/java.py#L561-L563561 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.calls | def calls(self, path: str, source: str) -> tuple[tuple[str, str], ...] | Ver pruebasrc/docu/adapters/langs/java.py#L565-L590565 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.symbols | def symbols(self, path: str, source: str) -> tuple[Symbol, ...] | Ver pruebasrc/docu/adapters/langs/python.py#L27-L3927 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_member | def _module_member(self, path: str, node: ast.AST, container: str | None) -> Symbol | None | Ver pruebasrc/docu/adapters/langs/python.py#L41-L8141 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_field | def _class_field(self, path: str, node: ast.AST, container: str) -> Symbol | None | Ver pruebasrc/docu/adapters/langs/python.py#L83-L11783 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._decorators | def _decorators(self, node: ast.AST) -> tuple[str, ...] | Ver pruebasrc/docu/adapters/langs/python.py#L119-L121119 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._routes | def _routes(self, path: str, node: ast.AST, container: str | None) -> list[Symbol] | Ver pruebasrc/docu/adapters/langs/python.py#L123-L151123 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.imports | def imports(self, path: str, source: str) -> tuple[str, ...] | Ver pruebasrc/docu/adapters/langs/python.py#L155-L166155 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.calls | def calls(self, path: str, source: str) -> tuple[tuple[str, str], ...] | Ver pruebasrc/docu/adapters/langs/python.py#L168-L200168 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_name | def _base_name(node: ast.AST) -> str | Ver pruebasrc/docu/adapters/langs/python.py#L206-L211206def _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_name | def _decorator_name(node: ast.AST) -> str | Ver pruebasrc/docu/adapters/langs/python.py#L214-L221214def _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_of | def _route_of(short: str, decorator: ast.AST) -> tuple[str, str | None] | Ver pruebasrc/docu/adapters/langs/python.py#L224-L244224def _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 |
_signature | def _signature(node: ast.AST) -> str | Ver pruebasrc/docu/adapters/langs/python.py#L247-L264247def _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_name | def _call_name(node: ast.AST) -> str | None | Ver pruebasrc/docu/adapters/langs/python.py#L267-L272267def _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_table | def _function_table(tree: ast.AST) -> list[tuple[str, int, int]] | Ver pruebasrc/docu/adapters/langs/python.py#L275-L294275def _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_for | def adapter_for(path: str) -> object | None | Ver pruebasrc/docu/adapters/langs/registry.py#L16-L2216def 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_languages | def supported_languages() -> tuple[str, ...] | Ver pruebasrc/docu/adapters/langs/registry.py#L25-L2625def supported_languages() -> tuple[str, ...]: 26 return tuple(adapter.language for adapter in ADAPTERS) # type: ignore[attr-defined] |
TypeScriptLangAdapter.symbols | def symbols(self, path: str, source: str) -> tuple[Symbol, ...] | Ver pruebasrc/docu/adapters/langs/typescript.py#L93-L18993 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._members | def _members(self) -> tuple[list[Symbol], list[Symbol]] | Ver pruebasrc/docu/adapters/langs/typescript.py#L191-L325191 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_routes | def _express_routes(self, path: str, source: str, masked: str, lines: Lines) -> list[Symbol] | Ver pruebasrc/docu/adapters/langs/typescript.py#L327-L405327 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.imports | def imports(self, path: str, source: str) -> tuple[str, ...] | Ver pruebasrc/docu/adapters/langs/typescript.py#L407-L408407 def imports(self, path: str, source: str) -> tuple[str, ...]: 408 return tuple(match.group("module") for match in _IMPORT_RE.finditer(source)) |
TypeScriptLangAdapter.calls | def calls(self, path: str, source: str) -> tuple[tuple[str, str], ...] | Ver pruebasrc/docu/adapters/langs/typescript.py#L410-L423410 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_block | def _annotation_block(source: str, start: int, end: int) -> tuple[str, int] | Ver pruebasrc/docu/adapters/langs/typescript.py#L429-L435429def _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_in | def _decorators_in(text: str) -> tuple[str, ...] | Ver pruebasrc/docu/adapters/langs/typescript.py#L438-L441438def _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_route | def _class_route(decorators: tuple[str, ...]) -> str | None | Ver pruebasrc/docu/adapters/langs/typescript.py#L444-L449444def _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_path | def _route_path(text: str, annotation: str) -> str | Ver pruebasrc/docu/adapters/langs/typescript.py#L452-L459452def _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 "/" |
_join | def _join(base: str | None, route: str) -> str | Ver pruebasrc/docu/adapters/langs/typescript.py#L462-L470462def _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_of | def _object_of(value: bytes) -> bytes | Ver pruebasrc/docu/adapters/sources/pdf.py#L47-L5047def _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_map | def _font_map(objects: dict[int, bytes]) -> dict[str, tuple[dict[int, str], bool]] | Ver pruebasrc/docu/adapters/sources/pdf.py#L53-L8153def _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_with | def _decode_with(raw: bytes, cmap: dict[int, str] | None, two_byte: bool) -> str | Ver pruebasrc/docu/adapters/sources/pdf.py#L84-L9484def _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_garbage | def _looks_like_garbage(text: str) -> bool | Ver pruebasrc/docu/adapters/sources/pdf.py#L97-L11597def _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.usable | def usable(self) -> bool | Ver pruebasrc/docu/adapters/sources/pdf.py#L133-L137Anotaciones: @property133 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.status | def status(self) -> str | Ver pruebasrc/docu/adapters/sources/pdf.py#L140-L145Anotaciones: @property140 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_pdf | def is_pdf(path: str, data: bytes | None=...) -> bool | Ver pruebasrc/docu/adapters/sources/pdf.py#L148-L151148def 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")) |
_decode | def _decode(stream: bytes) -> bytes | Ver pruebasrc/docu/adapters/sources/pdf.py#L157-L164157def _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 |
_objects | def _objects(data: bytes) -> dict[int, bytes] | Ver pruebasrc/docu/adapters/sources/pdf.py#L167-L172167def _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_of | def _stream_of(body: bytes) -> bytes | None | Ver pruebasrc/docu/adapters/sources/pdf.py#L175-L179175def _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_cmap | def _parse_cmap(text: bytes) -> dict[int, str] | Ver pruebasrc/docu/adapters/sources/pdf.py#L185-L204185def _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_for | def _cmap_for(objects: dict[int, bytes]) -> dict[int, str] | Ver pruebasrc/docu/adapters/sources/pdf.py#L207-L230207def _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_bytes | def _decode_bytes(raw: bytes, cmap: dict[int, str]) -> str | Ver pruebasrc/docu/adapters/sources/pdf.py#L236-L246236def _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") |
_literal | def _literal(data: bytes, index: int) -> tuple[bytes, int] | Ver pruebasrc/docu/adapters/sources/pdf.py#L249-L284249def _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 |
_hexstring | def _hexstring(data: bytes, index: int) -> tuple[bytes, int] | Ver pruebasrc/docu/adapters/sources/pdf.py#L287-L297287def _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_text | def _content_text(data: bytes, cmap: dict[int, str], fonts: dict[str, tuple[dict[int, str], bool]] | None=...) -> str | Ver pruebasrc/docu/adapters/sources/pdf.py#L300-L448300def _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_streams | def _page_streams(objects: dict[int, bytes]) -> list[bytes] | Ver pruebasrc/docu/adapters/sources/pdf.py#L454-L471454def _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 |
extract | def extract(data: bytes) -> PdfText | Ver pruebasrc/docu/adapters/sources/pdf.py#L474-L513474def 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_text | def pages_text(result: PdfText) -> str | Ver pruebasrc/docu/adapters/sources/pdf.py#L516-L521516def 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.lines | def lines(self) -> int | Ver pruebasrc/docu/adapters/sources/web.py#L51-L52Anotaciones: @property51 def lines(self) -> int: 52 return len(self.text.splitlines()) |
Snapshot.usable | def usable(self) -> bool | Ver pruebasrc/docu/adapters/sources/web.py#L55-L56Anotaciones: @property55 def usable(self) -> bool: 56 return len(self.text.strip()) >= MIN_TEXT_CHARS |
Snapshot.slug | def slug(self) -> str | Ver pruebasrc/docu/adapters/sources/web.py#L59-L62Anotaciones: @property59 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 pruebasrc/docu/adapters/sources/web.py#L68-L7168 def __init__(self) -> None: 69 super().__init__(convert_charrefs=True) 70 self._parts: list[str] = [] 71 self._skip_depth = 0 |
_TextExtractor.handle_starttag | def handle_starttag(self, tag: str, attrs) -> None | Ver pruebasrc/docu/adapters/sources/web.py#L73-L7873 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_endtag | def handle_endtag(self, tag: str) -> None | Ver pruebasrc/docu/adapters/sources/web.py#L80-L8580 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_data | def handle_data(self, data: str) -> None | Ver pruebasrc/docu/adapters/sources/web.py#L87-L9087 def handle_data(self, data: str) -> None: 88 if self._skip_depth: 89 return 90 self._parts.append(data) |
_TextExtractor.text | def text(self) -> str | Ver pruebasrc/docu/adapters/sources/web.py#L92-L10192 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_text | def html_to_text(html: str) -> str | Ver pruebasrc/docu/adapters/sources/web.py#L104-L108104def html_to_text(html: str) -> str: 105 parser = _TextExtractor() 106 parser.feed(html) 107 parser.close() 108 return parser.text() |
is_allowed | def is_allowed(url: str, allowlist: tuple[str, ...] | list[str]) -> bool | Ver pruebasrc/docu/adapters/sources/web.py#L111-L125111def 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 |
fetch | def fetch(url: str, timeout: int=..., max_bytes: int=..., opener=..., attempts: int=...) -> tuple[str, int] | Ver pruebasrc/docu/adapters/sources/web.py#L128-L165128def 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) |
capture | def capture(url: str, allowlist: tuple[str, ...] | list[str], opener=...) -> Snapshot | Ver pruebasrc/docu/adapters/sources/web.py#L168-L191168def 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.passed | def passed(self) -> bool | Ver pruebasrc/docu/audit/verify.py#L50-L51Anotaciones: @property50 def passed(self) -> bool: 51 return self.failed == 0 |
Check.score | def score(self) -> float | Ver pruebasrc/docu/audit/verify.py#L54-L57Anotaciones: @property54 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_dict | def to_dict(self) -> dict[str, object] | Ver pruebasrc/docu/audit/verify.py#L59-L6859 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.score | def score(self) -> float | Ver pruebasrc/docu/audit/verify.py#L80-L86Anotaciones: @property80 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.passed | def passed(self) -> bool | Ver pruebasrc/docu/audit/verify.py#L89-L90Anotaciones: @property89 def passed(self) -> bool: 90 return all(check.passed for check in self.checks.values()) |
AuditReport.to_dict | def to_dict(self) -> dict[str, object] | Ver pruebasrc/docu/audit/verify.py#L92-L10292 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._reconciliation | def _reconciliation(self) -> str | Ver pruebasrc/docu/audit/verify.py#L104-L115104 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_markdown | def to_markdown(self) -> str | Ver pruebasrc/docu/audit/verify.py#L117-L143117 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_citations | def check_citations(facts: Sequence[Fact], root: Path) -> Check | Ver pruebasrc/docu/audit/verify.py#L149-L194149def 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") |
_probes | def _probes(fact: Fact) -> list[str] | Ver pruebasrc/docu/audit/verify.py#L197-L217197def _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_supported | def _prose_supported(fact: Fact, span: str) -> bool | Ver pruebasrc/docu/audit/verify.py#L220-L234220def _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_needle | def _normalize_needle(text: str) -> str | Ver pruebasrc/docu/audit/verify.py#L237-L242237def _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_duplicates | def check_duplicates(facts: Sequence[Fact]) -> Check | Ver pruebasrc/docu/audit/verify.py#L245-L260245def 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_paths | def _document_paths(text: str) -> set[str] | Ver pruebasrc/docu/audit/verify.py#L263-L265263def _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_consistency | def check_consistency(docs: Mapping[str, str]) -> Check | Ver pruebasrc/docu/audit/verify.py#L268-L284268def 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_coverage | def check_coverage(facts: Sequence[Fact], root: Path) -> Check | Ver pruebasrc/docu/audit/verify.py#L287-L297287def 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_kinds | def _evidence_kinds(kind: str) -> tuple[str, ...] | Ver pruebasrc/docu/audit/verify.py#L300-L303300def _evidence_kinds(kind: str) -> tuple[str, ...]: 301 if kind == "module": 302 return ("module", "package") 303 return (kind,) |
check_freshness | def check_freshness(root: Path, levels: Sequence[str], manifest_path: Path | str | None=..., include: Sequence[str]=..., exclude: Sequence[str]=..., ttl_days: int=...) -> Check | Ver pruebasrc/docu/audit/verify.py#L306-L336306def 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 ) |
audit | def 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 pruebasrc/docu/audit/verify.py#L342-L417342def 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.severity | def severity(self) -> str | Ver pruebasrc/docu/conformance/drift.py#L46-L47Anotaciones: @property46 def severity(self) -> str: 47 return SEVERITY.get(self.kind, "warning") |
Discrepancy.action | def action(self) -> str | Ver pruebasrc/docu/conformance/drift.py#L50-L51Anotaciones: @property50 def action(self) -> str: 51 return ACTION.get(self.kind, "revisar") |
Discrepancy.to_dict | def to_dict(self) -> dict[str, object] | Ver pruebasrc/docu/conformance/drift.py#L53-L6253 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.errors | def errors(self) -> list[Discrepancy] | Ver pruebasrc/docu/conformance/drift.py#L73-L74Anotaciones: @property73 def errors(self) -> list[Discrepancy]: 74 return [item for item in self.discrepancies if item.severity == "error"] |
DriftReport.warnings | def warnings(self) -> list[Discrepancy] | Ver pruebasrc/docu/conformance/drift.py#L77-L78Anotaciones: @property77 def warnings(self) -> list[Discrepancy]: 78 return [item for item in self.discrepancies if item.severity != "error"] |
DriftReport.is_clean | def is_clean(self) -> bool | Ver pruebasrc/docu/conformance/drift.py#L81-L82Anotaciones: @property81 def is_clean(self) -> bool: 82 return not self.discrepancies |
DriftReport.to_dict | def to_dict(self) -> dict[str, object] | Ver pruebasrc/docu/conformance/drift.py#L84-L9384 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_markdown | def to_markdown(self) -> str | Ver pruebasrc/docu/conformance/drift.py#L95-L11295 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.save | def save(self, path: Path | str) -> Path | Ver pruebasrc/docu/conformance/drift.py#L114-L118114 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_code | def describe_code(root: Path | str, include_tests: bool=...) -> CodeFacts | Ver pruebasrc/docu/conformance/drift.py#L140-L174140def 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))) |
_short | def _short(name: str) -> str | Ver pruebasrc/docu/conformance/drift.py#L180-L182180def _short(name: str) -> str: 181 """Ultimo segmento de un nombre calificado (`A.B.c` → `c`).""" 182 return name.rsplit(".", 1)[-1] |
_owner | def _owner(qualname: str) -> str | Ver pruebasrc/docu/conformance/drift.py#L185-L191185def _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] |
compare | def compare(model: ArchitectureModel, code: CodeFacts) -> DriftReport | Ver pruebasrc/docu/conformance/drift.py#L194-L268194def 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 ) |
analyze | def analyze(root: Path | str, architecture: Path | str | None=..., include_tests: bool=...) -> DriftReport | Ver pruebasrc/docu/conformance/drift.py#L271-L278271def 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) |
bootstrap | def bootstrap(root: Path | str, include_tests: bool=...) -> ArchitectureModel | Ver pruebasrc/docu/conformance/drift.py#L281-L318281def 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.key | def key(self) -> str | Ver pruebasrc/docu/conformance/model.py#L36-L37Anotaciones: @property36 def key(self) -> str: 37 return f"{self.verb.upper()} {self.path}" |
Route.__str__ | def __str__(self) -> str | Ver pruebasrc/docu/conformance/model.py#L39-L4039 def __str__(self) -> str: 40 return self.key |
ArchitectureModel.component_names | def component_names(self) -> set[str] | Ver pruebasrc/docu/conformance/model.py#L60-L61Anotaciones: @property60 def component_names(self) -> set[str]: 61 return {component.name for component in self.components} |
ArchitectureModel.declared_routes | def declared_routes(self) -> set[str] | Ver pruebasrc/docu/conformance/model.py#L64-L68Anotaciones: @property64 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_dependencies | def declared_dependencies(self) -> set[tuple[str, str]] | Ver pruebasrc/docu/conformance/model.py#L70-L7570 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_empty | def is_empty(self) -> bool | Ver pruebasrc/docu/conformance/model.py#L78-L79Anotaciones: @property78 def is_empty(self) -> bool: 79 return not self.components and not self.routes |
_read_document | def _read_document(path: Path) -> Mapping[str, object] | None | Ver pruebasrc/docu/conformance/model.py#L85-L9785def _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_architecture | def load_architecture(root: Path, explicit: Path | str | None=...) -> ArchitectureModel | Ver pruebasrc/docu/conformance/model.py#L100-L135100def 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_from | def _components_from(block: Mapping[str, object], source: str) -> list[DeclaredComponent] | Ver pruebasrc/docu/conformance/model.py#L138-L159138def _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_openapi | def _routes_from_openapi(document: Mapping[str, object]) -> list[Route] | Ver pruebasrc/docu/conformance/model.py#L162-L173162def _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_list | def _as_list(value: object) -> Iterable[object] | Ver pruebasrc/docu/conformance/model.py#L176-L181176def _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_text | def _route_from_text(text: str) -> Route | None | Ver pruebasrc/docu/conformance/model.py#L184-L192184def _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_yaml | def to_yaml(model: ArchitectureModel, project: str) -> str | Ver pruebasrc/docu/conformance/model.py#L195-L218195def 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" |
utcnow | def utcnow() -> datetime | Ver pruebasrc/docu/core/contracts.py#L23-L2523def utcnow() -> datetime: 24 """Reloj unico del sistema: siempre UTC con zona explicita.""" 25 return datetime.now(UTC) |
sha256_of | def sha256_of(data: str | bytes) -> str | Ver pruebasrc/docu/core/contracts.py#L28-L3028def 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 pruebasrc/docu/core/contracts.py#L109-L115109 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_container | def is_container(self) -> bool | Ver pruebasrc/docu/core/contracts.py#L134-L135Anotaciones: @property134 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 pruebasrc/docu/core/contracts.py#L165-L169165 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.citation | def citation(self) -> str | Ver pruebasrc/docu/core/contracts.py#L172-L174Anotaciones: @property172 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_record | def to_record(self) -> dict[str, Any] | Ver pruebasrc/docu/core/contracts.py#L176-L197176 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.verified | def verified(self) -> bool | Ver pruebasrc/docu/core/contracts.py#L214-L215Anotaciones: @property214 def verified(self) -> bool: 215 return len(self.evidence) > 0 |
ContentNode.unsupported | def unsupported(self) -> list[Claim] | Ver pruebasrc/docu/core/contracts.py#L237-L238Anotaciones: @property237 def unsupported(self) -> list[Claim]: 238 return [c for c in self.claims if not c.verified] |
ContentNode.is_publishable | def is_publishable(self) -> bool | Ver pruebasrc/docu/core/contracts.py#L240-L241240 def is_publishable(self) -> bool: 241 return not self.unsupported and self.state is DocState.FRESH |
GateDecision.may_write | def may_write(self) -> bool | Ver pruebasrc/docu/core/contracts.py#L269-L271Anotaciones: @property269 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.describe | def describe(self) -> str | Ver pruebasrc/docu/core/contracts.py#L273-L275273 def describe(self) -> str: 274 head = self.outcome.value.upper() 275 return f"{head}: " + "; ".join(self.reasons) if self.reasons else head |
RunRecord.duration_s | def duration_s(self) -> float | None | Ver pruebasrc/docu/core/contracts.py#L301-L304Anotaciones: @property301 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_jsonl | def to_jsonl(self) -> str | Ver pruebasrc/docu/core/contracts.py#L306-L326306 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_expired | def is_expired(self, now: datetime | None=...) -> bool | Ver pruebasrc/docu/core/contracts.py#L343-L345343 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_mapping | def as_mapping(self) -> Mapping[str, float] | Ver pruebasrc/docu/core/policy.py#L28-L3428 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.spend | def spend(self) -> None | Ver pruebasrc/docu/core/policy.py#L50-L5650 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.exceeded | def exceeded(self) -> list[str] | Ver pruebasrc/docu/core/policy.py#L58-L6858 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_usd | def remaining_usd(self) -> float | Ver pruebasrc/docu/core/policy.py#L71-L72Anotaciones: @property71 def remaining_usd(self) -> float: 72 return max(0.0, self.max_cost_usd - self.spent_usd) |
GatePolicy.evaluate | def evaluate(self, metrics: Metrics, mode: Mode) -> GateDecision | Ver pruebasrc/docu/core/policy.py#L83-L10483 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.discover | def discover(self, root: str, include: Sequence[str], exclude: Sequence[str]) -> Iterable[Artifact] | Ver pruebasrc/docu/core/ports.py#L24-L2524 def discover(self, root: str, include: Sequence[str], exclude: Sequence[str]) -> Iterable[Artifact]: 25 ... |
SourceAdapter.read | def read(self, artifact: Artifact) -> str | bytes | Ver pruebasrc/docu/core/ports.py#L27-L2827 def read(self, artifact: Artifact) -> str | bytes: 28 ... |
LangAdapter.symbols | def symbols(self, path: str, source: str) -> Sequence[Symbol] | Ver pruebasrc/docu/core/ports.py#L41-L4241 def symbols(self, path: str, source: str) -> Sequence[Symbol]: 42 ... |
LangAdapter.imports | def imports(self, path: str, source: str) -> Sequence[str] | Ver pruebasrc/docu/core/ports.py#L44-L4544 def imports(self, path: str, source: str) -> Sequence[str]: 45 ... |
LangAdapter.calls | def calls(self, path: str, source: str) -> Sequence[tuple[str, str]] | Ver pruebasrc/docu/core/ports.py#L47-L5247 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.chunk | def chunk(self, artifact: Artifact, symbols: Sequence[Symbol], source: str) -> Sequence[Chunk] | Ver pruebasrc/docu/core/ports.py#L61-L6261 def chunk(self, artifact: Artifact, symbols: Sequence[Symbol], source: str) -> Sequence[Chunk]: 62 ... |
Embedder.embed | def embed(self, texts: Sequence[str]) -> Sequence[Sequence[float]] | Ver pruebasrc/docu/core/ports.py#L75-L7675 def embed(self, texts: Sequence[str]) -> Sequence[Sequence[float]]: 76 ... |
VectorStore.upsert | def upsert(self, namespace: str, chunks: Sequence[Chunk], vectors: Sequence[Sequence[float]]) -> int | Ver pruebasrc/docu/core/ports.py#L85-L8685 def upsert(self, namespace: str, chunks: Sequence[Chunk], vectors: Sequence[Sequence[float]]) -> int: 86 ... |
VectorStore.query | def query(self, namespace: str, vector: Sequence[float], top_k: int, filters: Mapping[str, Any] | None=...) -> Sequence[tuple[Chunk, float]] | Ver pruebasrc/docu/core/ports.py#L88-L9188 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_filter | def delete_by_filter(self, namespace: str, filters: Mapping[str, Any]) -> int | Ver pruebasrc/docu/core/ports.py#L93-L9493 def delete_by_filter(self, namespace: str, filters: Mapping[str, Any]) -> int: 94 ... |
Reranker.rank | def rank(self, query: str, chunks: Sequence[Chunk], top_n: int) -> Sequence[tuple[Chunk, float]] | Ver pruebasrc/docu/core/ports.py#L103-L104103 def rank(self, query: str, chunks: Sequence[Chunk], top_n: int) -> Sequence[tuple[Chunk, float]]: 104 ... |
RenderAdapter.render | def render(self, node: ContentNode, context: Mapping[str, Any]) -> str | Ver pruebasrc/docu/core/ports.py#L117-L118117 def render(self, node: ContentNode, context: Mapping[str, Any]) -> str: 118 ... |
Judge.score | def score(self, document: str, evidence: Sequence[Chunk], rubric: Mapping[str, Any]) -> Metrics | Ver pruebasrc/docu/core/ports.py#L128-L129128 def score(self, document: str, evidence: Sequence[Chunk], rubric: Mapping[str, Any]) -> Metrics: 129 ... |
Publisher.propose | def propose(self, path: str, content: str, message: str) -> str | Ver pruebasrc/docu/core/ports.py#L138-L139138 def propose(self, path: str, content: str, message: str) -> str: 139 ... |
Publisher.apply | def apply(self, proposal_id: str) -> str | Ver pruebasrc/docu/core/ports.py#L141-L142141 def apply(self, proposal_id: str) -> str: 142 ... |
Publisher.revert | def revert(self, applied_id: str) -> None | Ver pruebasrc/docu/core/ports.py#L144-L145144 def revert(self, applied_id: str) -> None: 145 ... |
Profile.exists | def exists(self) -> bool | Ver pruebasrc/docu/core/profile.py#L73-L74Anotaciones: @property73 def exists(self) -> bool: 74 return self.path is not None and self.path.exists() |
Profile.effective_exclude | def effective_exclude(self) -> tuple[str, ...] | Ver pruebasrc/docu/core/profile.py#L77-L83Anotaciones: @property77 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_dict | def to_dict(self) -> dict[str, object] | Ver pruebasrc/docu/core/profile.py#L85-L10785 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 } |
_mapping | def _mapping(value: object, name: str) -> Mapping[str, object] | Ver pruebasrc/docu/core/profile.py#L113-L118113def _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_tuple | def _string_tuple(value: object, name: str) -> tuple[str, ...] | Ver pruebasrc/docu/core/profile.py#L121-L128121def _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) |
_levels | def _levels(value: object) -> tuple[str, ...] | Ver pruebasrc/docu/core/profile.py#L131-L139131def _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 |
_thresholds | def _thresholds(value: object, defaults: Thresholds) -> Thresholds | Ver pruebasrc/docu/core/profile.py#L142-L161142def _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 ) |
_glossary | def _glossary(value: object) -> dict[str, tuple[str, ...]] | Ver pruebasrc/docu/core/profile.py#L164-L169164def _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_dict | def from_dict(payload: Mapping[str, object]) -> Profile | Ver pruebasrc/docu/core/profile.py#L172-L222172def 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"), |
load | def load(path: Path | str | None) -> Profile | None | Ver pruebasrc/docu/core/profile.py#L225-L236225def 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_paths | def candidate_paths(root: Path) -> tuple[Path, ...] | Ver pruebasrc/docu/core/profile.py#L239-L240239def candidate_paths(root: Path) -> tuple[Path, ...]: 240 return (root / "docu.profile.yaml", root / "docu.profile.yml", root / "docu.profile.json") |
find | def find(root: Path) -> Path | None | Ver pruebasrc/docu/core/profile.py#L243-L245243def 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_yaml | def to_yaml(profile: Profile) -> str | Ver pruebasrc/docu/core/profile.py#L251-L314251def 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.kind | def kind(self) -> str | Ver pruebasrc/docu/core/profile.py#L328-L329Anotaciones: @property328 def kind(self) -> str: 329 return "aplicado" if self.applied else "conservado" |
Change.describe | def describe(self) -> str | Ver pruebasrc/docu/core/profile.py#L331-L332331 def describe(self) -> str: 332 return f"{self.field}: {self.before!r} → {self.after!r} ({self.reason})" |
plan_changes | def plan_changes(existing: Profile | None, proposed: Profile) -> list[Change] | Ver pruebasrc/docu/core/profile.py#L339-L392339def 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 ) |
merge | def merge(existing: Profile, proposed: Profile) -> Profile | Ver pruebasrc/docu/core/profile.py#L395-L404395def 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_order | def render_change_order(changes: Sequence[Change], project: str) -> str | Ver pruebasrc/docu/core/profile.py#L407-L435407def 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) |
parse | def parse(text: str) -> dict[str, object] | Ver pruebasrc/docu/core/yamlmini.py#L18-L2818def 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 |
_prepare | def _prepare(text: str) -> list[tuple[int, str, int]] | Ver pruebasrc/docu/core/yamlmini.py#L34-L4834def _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_comment | def _strip_comment(line: str) -> str | Ver pruebasrc/docu/core/yamlmini.py#L51-L6451def _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_block | def _parse_block(lines: list[tuple[int, str, int]], start: int, indent: int) -> tuple[object, int] | Ver pruebasrc/docu/core/yamlmini.py#L70-L7570def _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_mapping | def _parse_mapping(lines: list[tuple[int, str, int]], start: int, indent: int) -> tuple[dict[str, object], int] | Ver pruebasrc/docu/core/yamlmini.py#L78-L11878def _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_sequence | def _parse_sequence(lines: list[tuple[int, str, int]], start: int, indent: int) -> tuple[list[object], int] | Ver pruebasrc/docu/core/yamlmini.py#L121-L146121def _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_item | def _parse_inline_item(lines: list[tuple[int, str, int]], start: int, indent: int, first: str, number: int) -> tuple[dict[str, object], int] | Ver pruebasrc/docu/core/yamlmini.py#L149-L193149def _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_mapping | def _is_inline_mapping(body: str, number: int) -> bool | Ver pruebasrc/docu/core/yamlmini.py#L199-L200199def _is_inline_mapping(body: str, number: int) -> bool: 200 return bool(_split_key(body, number)[1]) |
_split_key | def _split_key(content: str, number: int) -> tuple[str, str, str] | Ver pruebasrc/docu/core/yamlmini.py#L203-L215203def _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, "", "" |
_scalar | def _scalar(value: str, number: int) -> object | Ver pruebasrc/docu/core/yamlmini.py#L218-L249218def _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_flow | def _split_flow(text: str) -> list[str] | Ver pruebasrc/docu/core/yamlmini.py#L252-L279252def _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.empty | def empty(self) -> bool | Ver pruebasrc/docu/delivery/cleanup.py#L54-L55Anotaciones: @property54 def empty(self) -> bool: 55 return not (self.documents or self.artifacts or self.state or self.ledger) |
CleanPlan.total | def total(self) -> int | Ver pruebasrc/docu/delivery/cleanup.py#L58-L59Anotaciones: @property58 def total(self) -> int: 59 return len(self.documents) + len(self.artifacts) + len(self.state) + len(self.ledger) |
CleanPlan.to_dict | def to_dict(self) -> dict[str, object] | Ver pruebasrc/docu/delivery/cleanup.py#L61-L6961 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_files | def _iter_files(directory: Path) -> Iterable[Path] | Ver pruebasrc/docu/delivery/cleanup.py#L72-L7572def _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()) |
plan | def plan(root: Path | str, docs_dir: Path | str | None=..., documents: bool=..., state: bool=..., ledger: bool=...) -> CleanPlan | Ver pruebasrc/docu/delivery/cleanup.py#L78-L11778def 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 |
apply | def apply(plan_result: CleanPlan) -> tuple[int, list[str]] | Ver pruebasrc/docu/delivery/cleanup.py#L120-L137120def 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 |
fingerprint | def fingerprint(paths: Sequence[Path]) -> str | Ver pruebasrc/docu/delivery/cleanup.py#L140-L143140def 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_text | def _version_text(commands: int=...) -> str | Ver pruebasrc/docu/delivery/cli.py#L42-L5342def _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.error | def error(self, message: str) -> None | Ver pruebasrc/docu/delivery/cli.py#L59-L6759 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_parser | def _build_parser() -> argparse.ArgumentParser | Ver pruebasrc/docu/delivery/cli.py#L70-L26770def _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", |
_guard | def _guard(profile_path: str | None) -> ExitCode | None | Ver pruebasrc/docu/delivery/cli.py#L270-L277270def _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 pruebasrc/docu/delivery/cli.py#L283-L285283 def __init__(self, message: str, code: ExitCode) -> None: 284 super().__init__(message) 285 self.code = code |
_resolve | def _resolve(args: argparse.Namespace, root: Path) -> ResolvedOptions | Ver pruebasrc/docu/delivery/cli.py#L303-L333303def _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_utf8 | def _force_utf8() -> None | Ver pruebasrc/docu/delivery/cli.py#L336-L344336def _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 |
main | def main(argv: Sequence[str] | None=...) -> int | Ver pruebasrc/docu/delivery/cli.py#L347-L354347def 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) |
_dispatch | def _dispatch(args: argparse.Namespace) -> int | Ver pruebasrc/docu/delivery/cli.py#L357-L407357def _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_settings | def _learn_settings(root: Path) -> tuple[float, float] | Ver pruebasrc/docu/delivery/cli.py#L410-L427410def _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_learn | def _run_learn(args: argparse.Namespace) -> int | Ver pruebasrc/docu/delivery/cli.py#L430-L524430def _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_audit | def _run_audit(args: argparse.Namespace) -> int | Ver pruebasrc/docu/delivery/cli.py#L527-L569527def _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_site | def _run_site(args: argparse.Namespace) -> int | Ver pruebasrc/docu/delivery/cli.py#L572-L614572def _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_web | def _run_web(args: argparse.Namespace) -> int | Ver pruebasrc/docu/delivery/cli.py#L617-L675617def _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_pdf | def _run_pdf(args: argparse.Namespace) -> int | Ver pruebasrc/docu/delivery/cli.py#L678-L734678def _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_clean | def _run_clean(args: argparse.Namespace) -> int | Ver pruebasrc/docu/delivery/cli.py#L737-L789737def _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_prose | def _run_prose(args: argparse.Namespace) -> int | Ver pruebasrc/docu/delivery/cli.py#L792-L897792def _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_serve | def _run_serve(args: argparse.Namespace) -> int | Ver pruebasrc/docu/delivery/cli.py#L900-L928900def _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_drift | def _run_drift(args: argparse.Namespace) -> int | Ver pruebasrc/docu/delivery/cli.py#L931-L974931def _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_init | def _run_init(args: argparse.Namespace) -> int | Ver pruebasrc/docu/delivery/cli.py#L977-L1077977def _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_generate | def _run_generate(args: argparse.Namespace) -> int | Ver pruebasrc/docu/delivery/cli.py#L1080-L11501080def _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_status | def _run_status(args: argparse.Namespace, quiet_ok: bool, require_manifest: bool=...) -> int | Ver pruebasrc/docu/delivery/cli.py#L1153-L12441153def _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_why | def _print_status_why(root: Path, options, manifest) -> None | Ver pruebasrc/docu/delivery/cli.py#L1247-L12761247def _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_regen | def _run_ci_regen(args: argparse.Namespace) -> int | Ver pruebasrc/docu/delivery/cli.py#L1279-L13301279def _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_GET | def do_GET(self) -> None | Ver pruebasrc/docu/delivery/http_server.py#L32-L4932 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_POST | def do_POST(self) -> None | Ver pruebasrc/docu/delivery/http_server.py#L51-L7651 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._json | def _json(self, status: int, payload: dict[str, Any]) -> None | Ver pruebasrc/docu/delivery/http_server.py#L80-L8680 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_message | def log_message(self, fmt: str, *args) -> None | Ver pruebasrc/docu/delivery/http_server.py#L88-L8988 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_server | def make_server(server: McpServer, host: str=..., port: int=...) -> ThreadingHTTPServer | Ver pruebasrc/docu/delivery/http_server.py#L92-L9492def 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_http | def serve_http(server: McpServer, host: str=..., port: int=...) -> tuple[ThreadingHTTPServer, str] | Ver pruebasrc/docu/delivery/http_server.py#L97-L11497def 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_docs | def has_docs(self) -> bool | Ver pruebasrc/docu/delivery/mcp_server.py#L172-L173Anotaciones: @property172 def has_docs(self) -> bool: 173 return self.docs_dir.exists() and any(self.docs_dir.glob("*.md")) |
ProjectRef.project_name | def project_name(self) -> str | Ver pruebasrc/docu/delivery/mcp_server.py#L176-L188Anotaciones: @property176 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_files | def _documented_files(ref: ProjectRef) -> int | Ver pruebasrc/docu/delivery/mcp_server.py#L191-L203191def _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 pruebasrc/docu/delivery/mcp_server.py#L229-L238229 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.projects | def projects(self) -> list[ProjectRef] | Ver pruebasrc/docu/delivery/mcp_server.py#L242-L244242 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.resolve | def resolve(self, arguments: Mapping[str, Any]) -> ProjectRef | Ver pruebasrc/docu/delivery/mcp_server.py#L246-L264246 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_for | def _index_for(self, ref: ProjectRef) -> DocIndex | Ver pruebasrc/docu/delivery/mcp_server.py#L266-L271266 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.index | def index(self) -> DocIndex | Ver pruebasrc/docu/delivery/mcp_server.py#L274-L282Anotaciones: @property274 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._glossary | def _glossary(self, ref: ProjectRef) -> Mapping[str, Sequence[str]] | None | Ver pruebasrc/docu/delivery/mcp_server.py#L285-L300285 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_docs | def _require_docs(self, ref: ProjectRef) -> DocIndex | Ver pruebasrc/docu/delivery/mcp_server.py#L303-L310303 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_tool | def call_tool(self, name: str, arguments: Mapping[str, Any]) -> dict[str, Any] | Ver pruebasrc/docu/delivery/mcp_server.py#L314-L318314 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_projects | def _tool_list_projects(self, arguments: Mapping[str, Any]) -> dict[str, Any] | Ver pruebasrc/docu/delivery/mcp_server.py#L320-L333320 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_code | def _tool_search_code(self, arguments: Mapping[str, Any]) -> dict[str, Any] | Ver pruebasrc/docu/delivery/mcp_server.py#L335-L362335 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_docs | def _tool_search_docs(self, arguments: Mapping[str, Any]) -> dict[str, Any] | Ver pruebasrc/docu/delivery/mcp_server.py#L364-L388364 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_module | def _tool_get_module(self, arguments: Mapping[str, Any]) -> dict[str, Any] | Ver pruebasrc/docu/delivery/mcp_server.py#L390-L408390 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_doc | def _tool_get_symbol_doc(self, arguments: Mapping[str, Any]) -> dict[str, Any] | Ver pruebasrc/docu/delivery/mcp_server.py#L410-L428410 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_gaps | def _tool_list_gaps(self, arguments: Mapping[str, Any]) -> dict[str, Any] | Ver pruebasrc/docu/delivery/mcp_server.py#L430-L438430 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_architecture | def _tool_get_architecture(self, arguments: Mapping[str, Any]) -> dict[str, Any] | Ver pruebasrc/docu/delivery/mcp_server.py#L440-L461440 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_freshness | def _tool_get_freshness(self, arguments: Mapping[str, Any]) -> dict[str, Any] | Ver pruebasrc/docu/delivery/mcp_server.py#L463-L471463 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_citation | def _tool_verify_citation(self, arguments: Mapping[str, Any]) -> dict[str, Any] | Ver pruebasrc/docu/delivery/mcp_server.py#L473-L507473 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_diagram | def _tool_get_diagram(self, arguments: Mapping[str, Any]) -> dict[str, Any] | Ver pruebasrc/docu/delivery/mcp_server.py#L509-L526509 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_unsupported | def _tool_list_unsupported(self, arguments: Mapping[str, Any]) -> dict[str, Any] | Ver pruebasrc/docu/delivery/mcp_server.py#L528-L551528 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.handle | def handle(self, request: Mapping[str, Any]) -> dict[str, Any] | None | Ver pruebasrc/docu/delivery/mcp_server.py#L555-L602555 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.serve | def serve(self, instream: Any=..., outstream: Any=...) -> int | Ver pruebasrc/docu/delivery/mcp_server.py#L604-L626604 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 |
_result | def _result(identifier: object, result: Mapping[str, Any]) -> dict[str, Any] | Ver pruebasrc/docu/delivery/mcp_server.py#L632-L633632def _result(identifier: object, result: Mapping[str, Any]) -> dict[str, Any]: 633 return {"jsonrpc": "2.0", "id": identifier, "result": dict(result)} |
_error | def _error(identifier: object, code: int, message: str) -> dict[str, Any] | Ver pruebasrc/docu/delivery/mcp_server.py#L636-L637636def _error(identifier: object, code: int, message: str) -> dict[str, Any]: 637 return {"jsonrpc": "2.0", "id": identifier, "error": {"code": code, "message": message}} |
_excerpt | def _excerpt(body: str, limit: int=...) -> str | Ver pruebasrc/docu/delivery/mcp_server.py#L640-L642640def _excerpt(body: str, limit: int = 1200) -> str: 641 text = body.strip() 642 return text if len(text) <= limit else text[:limit].rstrip() + "…" |
discover_workspace | def discover_workspace(workspace: Path | str) -> list[ProjectRef] | Ver pruebasrc/docu/delivery/mcp_server.py#L645-L666645def 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_server | def build_server(root: Path | str=..., docs_dir: Path | str | None=..., workspace: Path | str | None=..., dense: bool=..., profile_path: Path | str | None=...) -> McpServer | Ver pruebasrc/docu/delivery/mcp_server.py#L669-L683669def 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 ) |
detect | def detect(root: Path) -> dict[str, object] | Ver pruebasrc/docu/delivery/proposal.py#L25-L6125def 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 } |
propose | def propose(root: Path) -> Profile | Ver pruebasrc/docu/delivery/proposal.py#L64-L9464def 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.filename | def filename(self) -> str | Ver pruebasrc/docu/generate/diagrams.py#L49-L50Anotaciones: @property49 def filename(self) -> str: 50 return f"{self.name}.mmd" |
_node_id | def _node_id(name: str) -> str | Ver pruebasrc/docu/generate/diagrams.py#L53-L5453def _node_id(name: str) -> str: 54 return re.sub(r"[^A-Za-z0-9_]", "_", name) |
_label | def _label(text: str) -> str | Ver pruebasrc/docu/generate/diagrams.py#L57-L5957def _label(text: str) -> str: 58 """Etiqueta segura para Mermaid (sin comillas ni saltos).""" 59 return text.replace('"', "'").replace("\n", " ")[:60] |
resolve_import | def resolve_import(module: str, from_file: str, packages: Sequence[DetectedPackage]) -> str | None | Ver pruebasrc/docu/generate/diagrams.py#L65-L8465def 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_dependencies | def package_dependencies(files: Mapping[str, Path], packages: Sequence[DetectedPackage], read) -> dict[tuple[str, str], set[str]] | Ver pruebasrc/docu/generate/diagrams.py#L87-L10887def 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_diagram | def architecture_diagram(packages: Sequence[DetectedPackage], edges: Mapping[tuple[str, str], set[str]]) -> Diagram | None | Ver pruebasrc/docu/generate/diagrams.py#L111-L131111def 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_signature | def _type_signature(fact: Fact) -> str | Ver pruebasrc/docu/generate/diagrams.py#L137-L138137def _type_signature(fact: Fact) -> str: 138 return str(fact.attributes.get("signature", "")) |
class_diagram | def class_diagram(package: DetectedPackage, facts: Sequence[Fact]) -> Diagram | None | Ver pruebasrc/docu/generate/diagrams.py#L141-L186141def 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_diagram | def api_flow_diagram(facts: Sequence[Fact]) -> Diagram | None | Ver pruebasrc/docu/generate/diagrams.py#L192-L218192def 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_type | def _entity_type(text: str) -> tuple[str, bool] | Ver pruebasrc/docu/generate/diagrams.py#L221-L232221def _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_diagram | def erd_diagram(facts: Sequence[Fact]) -> Diagram | None | Ver pruebasrc/docu/generate/diagrams.py#L235-L292235def 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_all | def build_all(files: Mapping[str, Path], packages: Sequence[DetectedPackage], facts: Sequence[Fact], read) -> tuple[Diagram, ...] | Ver pruebasrc/docu/generate/diagrams.py#L298-L328298def 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_diagrams | def write_diagrams(diagrams: Sequence[Diagram], directory: Path) -> list[Path] | Ver pruebasrc/docu/generate/diagrams.py#L331-L345331def 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.citation | def citation(self) -> str | Ver pruebasrc/docu/generate/docs_evidence.py#L59-L60Anotaciones: @property59 def citation(self) -> str: 60 return f"{self.path}#L{self.line_start}-L{self.line_end}" |
DocSection.matches | def matches(self, hints: Sequence[str]) -> bool | Ver pruebasrc/docu/generate/docs_evidence.py#L62-L6462 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_fact | def to_fact(self) -> Fact | Ver pruebasrc/docu/generate/docs_evidence.py#L66-L7366 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_sections | def parse_sections(path: str, source: str) -> list[DocSection] | Ver pruebasrc/docu/generate/docs_evidence.py#L76-L9776def 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_paragraph | def _first_paragraph(text: str) -> str | Ver pruebasrc/docu/generate/docs_evidence.py#L100-L111100def _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 "" |
discover | def discover(root: Path | str, files: Mapping[str, Path] | None=...) -> list[DocSection] | Ver pruebasrc/docu/generate/docs_evidence.py#L114-L141114def 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] |
find | def find(sections: Sequence[DocSection], hints: Sequence[str], limit: int=...) -> list[DocSection] | Ver pruebasrc/docu/generate/docs_evidence.py#L144-L160144def 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.verified | def verified(self) -> bool | Ver pruebasrc/docu/generate/facts.py#L39-L40Anotaciones: @property39 def verified(self) -> bool: 40 return bool(self.citation) |
Fact.location | def location(self) -> str | Ver pruebasrc/docu/generate/facts.py#L43-L44Anotaciones: @property43 def location(self) -> str: 44 return self.citation |
_line_of | def _line_of(text: str, offset: int) -> int | Ver pruebasrc/docu/generate/facts.py#L47-L4847def _line_of(text: str, offset: int) -> int: 48 return text[:offset].count("\n") + 1 |
_tag_value | def _tag_value(body: str, tag: str) -> str | None | Ver pruebasrc/docu/generate/facts.py#L51-L5351def _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_facts | def symbol_facts(symbols: Sequence[Symbol]) -> list[Fact] | Ver pruebasrc/docu/generate/facts.py#L59-L12759def 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_facts | def yaml_facts(path: str, source: str) -> list[Fact] | Ver pruebasrc/docu/generate/facts.py#L137-L166137def 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_facts | def pom_facts(path: str, source: str) -> list[Fact] | Ver pruebasrc/docu/generate/facts.py#L172-L251172def 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_with | def _line_with(text: str, needle: str) -> int | Ver pruebasrc/docu/generate/facts.py#L257-L260257def _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_after | def _line_with_after(text: str, needle: str, start: int) -> int | Ver pruebasrc/docu/generate/facts.py#L263-L268263def _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_facts | def requirements_facts(path: str, source: str) -> list[Fact] | Ver pruebasrc/docu/generate/facts.py#L271-L288271def 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_facts | def package_json_facts(path: str, source: str) -> list[Fact] | Ver pruebasrc/docu/generate/facts.py#L291-L316291def 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_facts | def pyproject_scripts_facts(path: str, source: str) -> list[Fact] | Ver pruebasrc/docu/generate/facts.py#L319-L345319def 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_facts | def pyproject_facts(path: str, source: str) -> list[Fact] | Ver pruebasrc/docu/generate/facts.py#L348-L399348def 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_facts | def package_facts(packages: Sequence[object]) -> list[Fact] | Ver pruebasrc/docu/generate/facts.py#L402-L420402def 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 |
unsupported | def unsupported(facts: Sequence[Fact]) -> list[Fact] | Ver pruebasrc/docu/generate/facts.py#L426-L428426def 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] |
_cite | def _cite(citation: str) -> str | Ver pruebasrc/docu/generate/markdown.py#L32-L3332def _cite(citation: str) -> str: 33 return f"`{citation}`" |
_table | def _table(headers: Sequence[str], rows: Sequence[Sequence[str]]) -> str | Ver pruebasrc/docu/generate/markdown.py#L36-L4236def _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_kind | def _by_kind(facts: Sequence[Fact], kind: str) -> list[Fact] | Ver pruebasrc/docu/generate/markdown.py#L45-L4645def _by_kind(facts: Sequence[Fact], kind: str) -> list[Fact]: 46 return [fact for fact in facts if fact.kind == kind] |
_dedupe | def _dedupe(facts: Sequence[Fact]) -> list[Fact] | Ver pruebasrc/docu/generate/markdown.py#L49-L5949def _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_sections | def _doc_sections(facts: Sequence[Fact]) -> list[DocSection] | Ver pruebasrc/docu/generate/markdown.py#L62-L7662def _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_lines | def _doc_hint_lines(facts: Sequence[Fact], hints: Sequence[str]) -> list[str] | Ver pruebasrc/docu/generate/markdown.py#L79-L9579def _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 |
_counts | def _counts(facts: Sequence[Fact]) -> dict[str, int] | Ver pruebasrc/docu/generate/markdown.py#L98-L10298def _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 |
_header | def _header(project: str, title: str, meta: Mapping[str, str], facts: Sequence[Fact], plain: bool=...) -> list[str] | Ver pruebasrc/docu/generate/markdown.py#L105-L136105def _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_block | def _diagrams_block(diagrams: Sequence[object], facts: Sequence[Fact]) -> list[str] | Ver pruebasrc/docu/generate/markdown.py#L139-L164139def _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_l1 | def render_l1(project: str, facts: Sequence[Fact], sources: Mapping[str, str], meta: Mapping[str, str], diagrams: Sequence[object]=...) -> str | Ver pruebasrc/docu/generate/markdown.py#L170-L476170def 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_l4 | def render_l4(project: str, facts: Sequence[Fact], sources: Mapping[str, str], meta: Mapping[str, str], diagrams: Sequence[object]=...) -> str | Ver pruebasrc/docu/generate/markdown.py#L482-L573482def 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_l2 | def render_l2(project: str, facts: Sequence[Fact], sources: Mapping[str, str], meta: Mapping[str, str], diagrams: Sequence[object]=...) -> str | Ver pruebasrc/docu/generate/markdown.py#L611-L715611def 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_l3 | def render_l3(project: str, facts: Sequence[Fact], sources: Mapping[str, str], meta: Mapping[str, str], diagrams: Sequence[object]=..., docs_sections: Sequence[DocSection]=...) -> str | Ver pruebasrc/docu/generate/markdown.py#L718-L769718def 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.facts | def facts(self) -> list[Fact] | Ver pruebasrc/docu/generate/narrative.py#L56-L57Anotaciones: @property56 def facts(self) -> list[Fact]: 57 return [*self.intent, *self.decisions] |
_clean | def _clean(text: str) -> str | Ver pruebasrc/docu/generate/narrative.py#L60-L7160def _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() |
_locate | def _locate(source: str, paragraph: str) -> tuple[int, int] | Ver pruebasrc/docu/generate/narrative.py#L74-L9174def _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_prose | def _is_prose(text: str) -> bool | Ver pruebasrc/docu/generate/narrative.py#L94-L10294def _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_paragraph | def _first_paragraph(text: str) -> str | Ver pruebasrc/docu/generate/narrative.py#L105-L112105def _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 "" |
_citation | def _citation(path: str, start: int, end: int) -> str | Ver pruebasrc/docu/generate/narrative.py#L115-L116115def _citation(path: str, start: int, end: int) -> str: 116 return f"{path}#L{start}-L{max(start, end)}" |
_line_of | def _line_of(source: str, offset: int) -> int | Ver pruebasrc/docu/generate/narrative.py#L119-L120119def _line_of(source: str, offset: int) -> int: 120 return source.count("\n", 0, offset) + 1 |
doc_facts | def doc_facts(rel: str, source: str) -> list[Fact] | Ver pruebasrc/docu/generate/narrative.py#L123-L159123def 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_facts | def _javadoc_facts(rel: str, source: str) -> list[Fact] | Ver pruebasrc/docu/generate/narrative.py#L162-L180162def _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_facts | def _python_docstring_facts(rel: str, source: str) -> list[Fact] | Ver pruebasrc/docu/generate/narrative.py#L183-L220183def _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_comments | def why_comments(rel: str, source: str) -> list[Fact] | Ver pruebasrc/docu/generate/narrative.py#L223-L245223def 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_facts | def metadata_facts(root: Path) -> list[Fact] | Ver pruebasrc/docu/generate/narrative.py#L248-L293248def 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)", |
collect | def collect(root: Path, files: Mapping[str, Path], counts: Mapping[str, int], project: str, read) -> Narrative | Ver pruebasrc/docu/generate/narrative.py#L296-L341296def 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 |
_short | def _short(text: str, limit: int=...) -> str | Ver pruebasrc/docu/generate/narrative.py#L344-L349344def _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(",.;:") + "…" |
_intro | def _intro(project: str, counts: Mapping[str, int], narrative: Narrative) -> str | Ver pruebasrc/docu/generate/narrative.py#L352-L396352def _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_file | def is_env_file(path: str) -> bool | Ver pruebasrc/docu/generate/ops.py#L33-L3433def is_env_file(path: str) -> bool: 34 return path.rsplit("/", 1)[-1] in ENV_FILES |
is_docker_file | def is_docker_file(path: str) -> bool | Ver pruebasrc/docu/generate/ops.py#L37-L3837def is_docker_file(path: str) -> bool: 38 return path.rsplit("/", 1)[-1] in DOCKER_FILES |
is_compose_file | def is_compose_file(path: str) -> bool | Ver pruebasrc/docu/generate/ops.py#L41-L4241def is_compose_file(path: str) -> bool: 42 return path.rsplit("/", 1)[-1] in COMPOSE_FILES |
is_workflow_file | def is_workflow_file(path: str) -> bool | Ver pruebasrc/docu/generate/ops.py#L45-L4745def 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_facts | def env_facts(path: str, source: str) -> list[Fact] | Ver pruebasrc/docu/generate/ops.py#L50-L6950def 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_facts | def dockerfile_facts(path: str, source: str) -> list[Fact] | Ver pruebasrc/docu/generate/ops.py#L72-L10772def 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_parse | def _safe_parse(source: str) -> object | Ver pruebasrc/docu/generate/ops.py#L110-L115110def _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_facts | def compose_facts(path: str, source: str) -> list[Fact] | Ver pruebasrc/docu/generate/ops.py#L118-L164118def 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_facts | def scripts_facts(path: str, payload: dict[str, object], source: str) -> list[Fact] | Ver pruebasrc/docu/generate/ops.py#L167-L184167def 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_facts | def workflow_facts(path: str, source: str) -> list[Fact] | Ver pruebasrc/docu/generate/ops.py#L187-L234187def 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_path | def _is_test_path(rel: Path) -> bool | Ver pruebasrc/docu/generate/pipeline.py#L75-L7975def _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_files | def wrote_files(self) -> bool | Ver pruebasrc/docu/generate/pipeline.py#L115-L116Anotaciones: @property115 def wrote_files(self) -> bool: 116 return bool(self.docs) and not self.dry_run |
GenerationResult.pending | def pending(self) -> tuple[str, ...] | Ver pruebasrc/docu/generate/pipeline.py#L119-L123Anotaciones: @property119 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_matches | def _path_matches(rel: str, patterns: Sequence[str]) -> bool | Ver pruebasrc/docu/generate/pipeline.py#L126-L141126def _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_exclude | def _effective_exclude(exclude: Sequence[str]) -> tuple[str, ...] | Ver pruebasrc/docu/generate/pipeline.py#L144-L152144def _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))) |
_discover | def _discover(root: Path, include_tests: bool=..., include: Sequence[str]=..., exclude: Sequence[str]=...) -> dict[str, Path] | Ver pruebasrc/docu/generate/pipeline.py#L155-L194155def _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 |
_read | def _read(path: Path) -> str | Ver pruebasrc/docu/generate/pipeline.py#L197-L198197def _read(path: Path) -> str: 198 return path.read_text(encoding="utf-8", errors="replace") |
collect_facts | def collect_facts(root: Path, include_tests: bool=..., include: Sequence[str]=..., exclude: Sequence[str]=...) -> tuple[list[Fact], dict[str, str]] | Ver pruebasrc/docu/generate/pipeline.py#L201-L278201def 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_sources | def unsupported_sources(root: Path, include_tests: bool=..., include: Sequence[str]=..., exclude: Sequence[str]=...) -> dict[str, int] | Ver pruebasrc/docu/generate/pipeline.py#L324-L354324def 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())) |
applicability | def applicability(facts: Sequence[Fact], root: Path) -> dict[str, bool] | Ver pruebasrc/docu/generate/pipeline.py#L357-L375357def 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 } |
completeness | def completeness(facts: Sequence[Fact], applicable: Mapping[str, bool]) -> float | Ver pruebasrc/docu/generate/pipeline.py#L386-L396386def 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) |
conciseness | def conciseness(facts: Sequence[Fact]) -> float | Ver pruebasrc/docu/generate/pipeline.py#L399-L404399def 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_languages | def _detected_languages(sources: Mapping[str, str]) -> str | Ver pruebasrc/docu/generate/pipeline.py#L417-L424417def _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_run | def _record_run() -> None | Ver pruebasrc/docu/generate/pipeline.py#L427-L461427def _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_names | def _language_names(counts: Mapping[str, int]) -> dict[str, int] | Ver pruebasrc/docu/generate/pipeline.py#L464-L470464def _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_file | def manifest_file(root: Path, manifest_path: Path | str | None) -> Path | Ver pruebasrc/docu/generate/pipeline.py#L473-L474473def manifest_file(root: Path, manifest_path: Path | str | None) -> Path: 474 return Path(manifest_path) if manifest_path else root / MANIFEST_PATH |
inspect | def 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 pruebasrc/docu/generate/pipeline.py#L477-L515477def 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_facts | def 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 pruebasrc/docu/generate/pipeline.py#L518-L547518def 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_only | def collect_all_facts_only(root_path: Path, include_tests: bool=..., include: Sequence[str]=..., exclude: Sequence[str]=..., project: str | None=...) -> list[Fact] | Ver pruebasrc/docu/generate/pipeline.py#L550-L561550def 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 |
generate | def 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 pruebasrc/docu/generate/pipeline.py#L564-L756564def 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.accepted | def accepted(self) -> bool | Ver pruebasrc/docu/generate/prose.py#L60-L61Anotaciones: @property60 def accepted(self) -> bool: 61 return not self.errors and bool(self.sections) |
Verdict.accepted | def accepted(self) -> bool | Ver pruebasrc/docu/generate/prose.py#L75-L76Anotaciones: @property75 def accepted(self) -> bool: 76 return not self.errors and self.score >= MIN_JUDGE_SCORE |
fact_id | def fact_id(fact: Fact) -> str | Ver pruebasrc/docu/generate/prose.py#L79-L8079def fact_id(fact: Fact) -> str: 80 return f"{fact.kind}:{fact.subject}" |
_norm | def _norm(text: str) -> str | Ver pruebasrc/docu/generate/prose.py#L83-L8583def _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_request | def build_request(project: str, facts: Sequence[Fact], language: str=..., limit: int=...) -> dict[str, object] | Ver pruebasrc/docu/generate/prose.py#L88-L13988def 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_markdown | def render_request_markdown(request: Mapping[str, object]) -> str | Ver pruebasrc/docu/generate/prose.py#L142-L187142def 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 ), |
_numbers | def _numbers(text: str) -> set[str] | Ver pruebasrc/docu/generate/prose.py#L190-L203190def _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_supported | def _number_supported(number: str, supported: set[str]) -> bool | Ver pruebasrc/docu/generate/prose.py#L206-L211206def _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) |
validate | def validate(payload: Mapping[str, object], facts: Sequence[Fact]) -> tuple[ProseResponse, dict[str, Fact]] | Ver pruebasrc/docu/generate/prose.py#L214-L274214def 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_request | def build_judge_request(project: str, prose: ProseResponse, facts: Sequence[Fact], facts_index: Mapping[str, Fact]) -> dict[str, object] | Ver pruebasrc/docu/generate/prose.py#L277-L320277def 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_verdict | def load_verdict(payload: Mapping[str, object]) -> Verdict | Ver pruebasrc/docu/generate/prose.py#L323-L344323def 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 |
render | def render(prose: ProseResponse, facts_index: Mapping[str, Fact]) -> str | Ver pruebasrc/docu/generate/prose.py#L347-L365347def 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_path | def store_path(root: Path | str) -> Path | Ver pruebasrc/docu/generate/prose.py#L368-L369368def store_path(root: Path | str) -> Path: 369 return Path(root) / PROSE_DIR / STORE_NAME |
save | def save(root: Path | str, prose: ProseResponse, verdict: Verdict | None=...) -> Path | Ver pruebasrc/docu/generate/prose.py#L372-L392372def 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 |
load | def load(root: Path | str) -> tuple[ProseResponse, Verdict | None] | None | Ver pruebasrc/docu/generate/prose.py#L395-L424395def 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_request | def write_request(directory: Path, request: Mapping[str, object]) -> tuple[Path, Path] | Ver pruebasrc/docu/generate/prose.py#L427-L433427def 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_request | def write_judge_request(directory: Path, request: Mapping[str, object]) -> Path | Ver pruebasrc/docu/generate/prose.py#L436-L440436def 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_tokens | def estimate_tokens(text: str) -> int | Ver pruebasrc/docu/index/chunker.py#L22-L2422def estimate_tokens(text: str) -> int: 23 """Estimacion deliberadamente simple y estable: ~4 caracteres por token.""" 24 return max(1, len(text) // CHARS_PER_TOKEN) |
_flatten | def _flatten(symbols: Sequence[Symbol]) -> tuple[Symbol, ...] | Ver pruebasrc/docu/index/chunker.py#L27-L4227def _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.chunk | def chunk(self, artifact: Artifact, symbols: Sequence[Symbol], source: str, dependencies: Mapping[str, Sequence[str]] | None=...) -> tuple[Chunk, ...] | Ver pruebasrc/docu/index/chunker.py#L53-L8953 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._span | def _span(self, symbol: Symbol, symbols: Sequence[Symbol], lines: Sequence[str]) -> tuple[int, int] | Ver pruebasrc/docu/index/chunker.py#L93-L10893 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._prefix | def _prefix(self, artifact: Artifact, symbol: Symbol, start: int, end: int, route: str | None) -> str | Ver pruebasrc/docu/index/chunker.py#L110-L133110 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._split | def _split(self) -> list[Chunk] | Ver pruebasrc/docu/index/chunker.py#L137-L190137 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._make | def _make(self) -> Chunk | Ver pruebasrc/docu/index/chunker.py#L192-L220192 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_hash | def compute_input_hash(components: InputComponents) -> str | Ver pruebasrc/docu/index/freshness.py#L37-L4537def 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)) |
classify | def classify() -> DocState | Ver pruebasrc/docu/index/freshness.py#L48-L7148def 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 |
transition | def transition() -> FreshnessRecord | Ver pruebasrc/docu/index/freshness.py#L74-L9674def 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_idempotent | def is_idempotent() -> bool | Ver pruebasrc/docu/index/freshness.py#L99-L10199def 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 |
_translate | def _translate(pattern: str) -> re.Pattern[str] | Ver pruebasrc/docu/index/ignore.py#L27-L5927def _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) + "$") |
parse | def parse(text: str) -> list[IgnoreRule] | Ver pruebasrc/docu/index/ignore.py#L62-L8862def 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 |
load | def load(root: Path | str) -> list[IgnoreRule] | Ver pruebasrc/docu/index/ignore.py#L91-L9791def 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_ignored | def is_ignored(rel: str, rules: Sequence[IgnoreRule], is_dir: bool=...) -> bool | Ver pruebasrc/docu/index/ignore.py#L100-L126100def 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 |
_prefixes | def _prefixes(rel: str) -> list[str] | Ver pruebasrc/docu/index/ignore.py#L129-L132129def _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_dict | def to_dict(self) -> dict[str, object] | Ver pruebasrc/docu/index/manifest.py#L44-L5344 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_dict | def from_dict(cls, payload: Mapping[str, object]) -> DocEntry | Ver pruebasrc/docu/index/manifest.py#L56-L65Anotaciones: @classmethod56 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_dt | def generated_at_dt(self) -> datetime | Ver pruebasrc/docu/index/manifest.py#L67-L6867 def generated_at_dt(self) -> datetime: 68 return datetime.fromisoformat(self.generated_at) |
Manifest.entry | def entry(self, level: str) -> DocEntry | None | Ver pruebasrc/docu/index/manifest.py#L82-L8382 def entry(self, level: str) -> DocEntry | None: 83 return next((doc for doc in self.docs if doc.level == level), None) |
Manifest.upsert | def upsert(self, entry: DocEntry) -> None | Ver pruebasrc/docu/index/manifest.py#L85-L8685 def upsert(self, entry: DocEntry) -> None: 86 self.docs = [doc for doc in self.docs if doc.level != entry.level] + [entry] |
Manifest.to_dict | def to_dict(self) -> dict[str, object] | Ver pruebasrc/docu/index/manifest.py#L90-L9690 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_dict | def from_dict(cls, payload: Mapping[str, object]) -> Manifest | Ver pruebasrc/docu/index/manifest.py#L99-L105Anotaciones: @classmethod99 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.save | def save(self, path: Path | str) -> Path | Ver pruebasrc/docu/index/manifest.py#L107-L111107 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.load | def load(cls, path: Path | str) -> Manifest | None | Ver pruebasrc/docu/index/manifest.py#L114-L124Anotaciones: @classmethod114 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_for | def input_hash_for() -> str | Ver pruebasrc/docu/index/manifest.py#L130-L149130def 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_signature | def fact_signature(facts: object) -> str | Ver pruebasrc/docu/index/manifest.py#L152-L159152def 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_of | def state_of() -> DocState | Ver pruebasrc/docu/index/manifest.py#L162-L186162def 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_exists | def document_exists(entry: DocEntry | None, root: Path) -> bool | Ver pruebasrc/docu/index/manifest.py#L189-L196189def 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_digest | def profile_digest(root: Path) -> str | Ver pruebasrc/docu/index/manifest.py#L199-L210199def 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_count | def file_count(self) -> int | Ver pruebasrc/docu/index/packages.py#L31-L32Anotaciones: @property31 def file_count(self) -> int: 32 return len(self.files) |
DetectedPackage.citation | def citation(self) -> str | Ver pruebasrc/docu/index/packages.py#L35-L36Anotaciones: @property35 def citation(self) -> str: 36 return self.declaration |
_python_packages | def _python_packages(files: Mapping[str, Path]) -> list[DetectedPackage] | Ver pruebasrc/docu/index/packages.py#L39-L6839def _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_packages | def _java_packages(files: Mapping[str, Path]) -> list[DetectedPackage] | Ver pruebasrc/docu/index/packages.py#L71-L9471def _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_packages | def _typescript_packages(files: Mapping[str, Path]) -> list[DetectedPackage] | Ver pruebasrc/docu/index/packages.py#L97-L16097def _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_packages | def detect_packages(files: Mapping[str, Path]) -> tuple[DetectedPackage, ...] | Ver pruebasrc/docu/index/packages.py#L163-L166163def 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))) |
_read | def _read(path: Path) -> str | Ver pruebasrc/docu/index/packages.py#L169-L173169def _read(path: Path) -> str: 170 try: 171 return path.read_text(encoding="utf-8", errors="replace") 172 except OSError: 173 return "" |
_line_count | def _line_count(path: Path) -> int | Ver pruebasrc/docu/index/packages.py#L179-L186179def _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_level | def top_level(packages: Sequence[DetectedPackage]) -> tuple[str, ...] | Ver pruebasrc/docu/index/packages.py#L189-L196189def 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.citation | def citation(self) -> str | Ver pruebasrc/docu/index/pdfdocs.py#L34-L35Anotaciones: @property34 def citation(self) -> str: 35 return f"{self.rel}#p1" |
PdfDocument.to_fact | def to_fact(self) -> Fact | Ver pruebasrc/docu/index/pdfdocs.py#L37-L5037 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_pdfs | def discover_pdfs(root: Path | str, include: Sequence[str]=..., exclude: Sequence[str]=..., include_tests: bool=..., limit: int=...) -> list[str] | Ver pruebasrc/docu/index/pdfdocs.py#L53-L9453def 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_document | def load_document(root: Path | str, rel: str, data: bytes | None=...) -> tuple[PdfDocument, str] | Ver pruebasrc/docu/index/pdfdocs.py#L97-L11197def 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_all | def 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 pruebasrc/docu/index/pdfdocs.py#L114-L136114def 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_facts | def pdf_facts(documents: Sequence[PdfDocument]) -> list[Fact] | Ver pruebasrc/docu/index/pdfdocs.py#L139-L140139def pdf_facts(documents: Sequence[PdfDocument]) -> list[Fact]: 140 return [document.to_fact() for document in documents] |
write_sidecars | def write_sidecars(texts: Mapping[str, str], directory: Path) -> list[Path] | Ver pruebasrc/docu/index/pdfdocs.py#L143-L154143def 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.citation | def citation(self) -> str | Ver pruebasrc/docu/index/webdocs.py#L29-L30Anotaciones: @property29 def citation(self) -> str: 30 return f"{self.rel}#L1-L{max(1, self.lines)}" |
WebDocument.to_fact | def to_fact(self) -> Fact | Ver pruebasrc/docu/index/webdocs.py#L32-L4532 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_path | def _index_path(root: Path) -> Path | Ver pruebasrc/docu/index/webdocs.py#L48-L4948def _index_path(root: Path) -> Path: 49 return root / ".docu" / INDEX_NAME |
read_index | def read_index(root: Path) -> dict[str, dict[str, object]] | Ver pruebasrc/docu/index/webdocs.py#L52-L6052def 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_index | def _write_index(root: Path, entries: Mapping[str, Mapping[str, object]]) -> None | Ver pruebasrc/docu/index/webdocs.py#L63-L6663def _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_urls | def capture_urls(root: Path | str, urls: Sequence[str], allowlist: Sequence[str], docs_dir: Path | str, opener=...) -> tuple[list[WebDocument], list[str]] | Ver pruebasrc/docu/index/webdocs.py#L69-L14169def 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_documents | def load_documents(root: Path | str, urls: Iterable[str]=...) -> list[WebDocument] | Ver pruebasrc/docu/index/webdocs.py#L144-L181144def 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_facts | def web_facts(documents: Sequence[WebDocument]) -> list[Fact] | Ver pruebasrc/docu/index/webdocs.py#L184-L185184def web_facts(documents: Sequence[WebDocument]) -> list[Fact]: 185 return [document.to_fact() for document in documents if document.rel] |
check_stale | def check_stale(root: Path | str, allowlist: Sequence[str], opener=...) -> list[tuple[str, str]] | Ver pruebasrc/docu/index/webdocs.py#L188-L203188def 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_json | def to_json(self) -> str | Ver pruebasrc/docu/learn/federation.py#L36-L3736 def to_json(self) -> str: 37 return json.dumps(self.data, ensure_ascii=False, indent=2, sort_keys=True) |
fingerprint | def fingerprint(value: str) -> str | Ver pruebasrc/docu/learn/federation.py#L40-L4240def 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_payload | def build_payload(library: PatternLibrary) -> FederationPayload | Ver pruebasrc/docu/learn/federation.py#L45-L7045def 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_anonymous | def assert_anonymous(payload: Mapping[str, object]) -> None | Ver pruebasrc/docu/learn/federation.py#L73-L8073def 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_keys | def _check_keys(node: object) -> None | Ver pruebasrc/docu/learn/federation.py#L83-L10083def _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) |
preview | def preview(payload: FederationPayload) -> str | Ver pruebasrc/docu/learn/federation.py#L103-L105103def 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() |
send | def send(payload: FederationPayload, endpoint: str | None) -> dict[str, object] | Ver pruebasrc/docu/learn/federation.py#L108-L137108def 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_file | def ledger_file(root: Path | str, explicit: Path | str | None=...) -> Path | Ver pruebasrc/docu/learn/ledger.py#L20-L2120def ledger_file(root: Path | str, explicit: Path | str | None = None) -> Path: 21 return Path(explicit) if explicit else Path(root) / LEDGER_PATH |
new_run_id | def new_run_id(now: datetime | None=...) -> str | Ver pruebasrc/docu/learn/ledger.py#L24-L2624def 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}" |
append | def append(path: Path | str) -> RunRecord | Ver pruebasrc/docu/learn/ledger.py#L29-L6529def 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 |
load | def load(path: Path | str) -> list[dict[str, object]] | Ver pruebasrc/docu/learn/ledger.py#L68-L8468def 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 |
_metric | def _metric(record: Mapping[str, object], name: str) -> float | None | Ver pruebasrc/docu/learn/ledger.py#L87-L9287def _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 |
summarize | def summarize(records: Sequence[Mapping[str, object]]) -> dict[str, object] | Ver pruebasrc/docu/learn/ledger.py#L95-L12595def 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_counts | def outcome_counts(records: Iterable[Mapping[str, object]]) -> dict[str, int] | Ver pruebasrc/docu/learn/ledger.py#L128-L135128def 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_timestamp | def parse_timestamp(value: object) -> datetime | None | Ver pruebasrc/docu/learn/ledger.py#L138-L145138def 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_dict | def to_dict(self) -> dict[str, object] | Ver pruebasrc/docu/learn/patterns.py#L35-L4335 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_dict | def from_dict(cls, payload: Mapping[str, object]) -> Pattern | Ver pruebasrc/docu/learn/patterns.py#L46-L55Anotaciones: @classmethod46 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_dict | def to_dict(self) -> dict[str, object] | Ver pruebasrc/docu/learn/patterns.py#L67-L7367 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_dict | def from_dict(cls, payload: Mapping[str, object]) -> PatternLibrary | Ver pruebasrc/docu/learn/patterns.py#L76-L89Anotaciones: @classmethod76 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.save | def save(self, path: Path | str) -> Path | Ver pruebasrc/docu/learn/patterns.py#L93-L9793 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.load | def load(cls, path: Path | str) -> PatternLibrary | Ver pruebasrc/docu/learn/patterns.py#L100-L108Anotaciones: @classmethod100 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.promote | def promote(self, pattern: Pattern) -> None | Ver pruebasrc/docu/learn/patterns.py#L112-L125112 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.revert | def revert(self, pattern_id: str) -> bool | Ver pruebasrc/docu/learn/patterns.py#L127-L142127 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_version | def _next_version(current: str) -> str | Ver pruebasrc/docu/learn/patterns.py#L145-L149145def _next_version(current: str) -> str: 146 try: 147 return str(int(current) + 1) 148 except ValueError: 149 return "1" |
Candidate.key | def key(self) -> str | Ver pruebasrc/docu/learn/patterns.py#L163-L164Anotaciones: @property163 def key(self) -> str: 164 return self.pattern.pattern_id |
stack_of | def stack_of(project: str, records: Sequence[Mapping[str, object]]) -> str | Ver pruebasrc/docu/learn/patterns.py#L167-L177167def 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_from | def candidates_from(records: Sequence[Mapping[str, object]], min_runs: int=..., improvement: float=...) -> list[Candidate] | Ver pruebasrc/docu/learn/patterns.py#L180-L229180def 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_change | def is_change(self) -> bool | Ver pruebasrc/docu/learn/promotion.py#L28-L29Anotaciones: @property28 def is_change(self) -> bool: 29 return self.action in (PROMOTE, ROLLBACK) |
Decision.describe | def describe(self) -> str | Ver pruebasrc/docu/learn/promotion.py#L31-L3331 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}" |
_average | def _average(metrics: dict[str, float], names: Sequence[str]=...) -> float | Ver pruebasrc/docu/learn/promotion.py#L36-L3836def _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 |
decide | def decide(current: Pattern | None, candidate: Pattern) -> Decision | Ver pruebasrc/docu/learn/promotion.py#L41-L8941def 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}", |
escape | def escape(text: str) -> str | Ver pruebasrc/docu/publish/site.py#L130-L131130def escape(text: str) -> str: 131 return html.escape(text, quote=True) |
snippet | def snippet(root: Path, citation: str, limit: int=...) -> str | Ver pruebasrc/docu/publish/site.py#L134-L162134def 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) |
_cell | def _cell(text: str) -> str | Ver pruebasrc/docu/publish/site.py#L165-L166165def _cell(text: str) -> str: 166 return f"<code>{escape(text)}</code>" if text else "—" |
_row | def _row(fact: Fact, root: Path) -> str | Ver pruebasrc/docu/publish/site.py#L169-L190169def _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 ) |
_section | def _section(anchor: str, title: str, facts: Sequence[Fact], root: Path) -> str | Ver pruebasrc/docu/publish/site.py#L193-L211193def _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 ) |
_shell | def _shell(title: str, project: str, body: str, meta: Mapping[str, str], anchors: Sequence[tuple[str, str]]=...) -> str | Ver pruebasrc/docu/publish/site.py#L214-L249214def _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_flowchart | def parse_flowchart(text: str) -> tuple[list[tuple[str, str]], list[tuple[str, str]]] | Ver pruebasrc/docu/publish/site.py#L252-L272252def 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_architecture | def svg_architecture(text: str, max_nodes: int=...) -> str | None | Ver pruebasrc/docu/publish/site.py#L275-L331275def 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_erd | def parse_erd(text: str) -> tuple[dict[str, list[tuple[str, str]]], list[tuple[str, str, str, str]]] | Ver pruebasrc/docu/publish/site.py#L340-L366340def 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_erd | def svg_erd(text: str, max_entities: int=..., max_fields: int=..., columns: int=...) -> tuple[str | None, str] | Ver pruebasrc/docu/publish/site.py#L369-L474369def 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_flow | def svg_api_flow(text: str, max_routes: int=...) -> tuple[str | None, str] | Ver pruebasrc/docu/publish/site.py#L477-L533477def 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_section | def _diagrams_section(diagrams: Path, root: Path) -> str | Ver pruebasrc/docu/publish/site.py#L536-L581536def _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_site | def 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 pruebasrc/docu/publish/site.py#L584-L652584def 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) |
_dedupe | def _dedupe(facts: Sequence[Fact]) -> list[Fact] | Ver pruebasrc/docu/publish/site.py#L655-L664655def _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_body | def _index_body(project: str, facts: Sequence[Fact], counts: Mapping[str, int], meta: Mapping[str, str], levels: Sequence[str]) -> str | Ver pruebasrc/docu/publish/site.py#L667-L712667def _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> |
fold | def fold(text: str) -> str | Ver pruebasrc/docu/retrieve/glossary.py#L62-L6462def 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)) |
merge | def merge(*glossaries) -> dict[str, tuple[str, ...]] | Ver pruebasrc/docu/retrieve/glossary.py#L67-L7467def 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 |
expand | def expand(query: str, glossary: Mapping[str, Sequence[str]] | None=...) -> str | Ver pruebasrc/docu/retrieve/glossary.py#L77-L9477def 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.citation | def citation(self) -> str | Ver pruebasrc/docu/retrieve/hybrid.py#L46-L47Anotaciones: @property46 def citation(self) -> str: 47 return f"{self.path}#L{self.start}-L{self.end}" |
CodeChunk.to_dict | def to_dict(self, score: float) -> dict[str, object] | Ver pruebasrc/docu/retrieve/hybrid.py#L49-L5949 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_names | def _exact_names(qualname: str | None) -> tuple[str, ...] | Ver pruebasrc/docu/retrieve/hybrid.py#L62-L6762def _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_chunks | def build_chunks(root: Path | str, include: Sequence[str]=..., exclude: Sequence[str]=..., include_tests: bool=...) -> list[CodeChunk] | Ver pruebasrc/docu/retrieve/hybrid.py#L70-L10970def 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 pruebasrc/docu/retrieve/hybrid.py#L128-L135128 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_available | def dense_available(self) -> bool | Ver pruebasrc/docu/retrieve/hybrid.py#L140-L141Anotaciones: @property140 def dense_available(self) -> bool: 141 return self.embedder is not None |
CodeIndex.capabilities | def capabilities(self) -> dict[str, object] | Ver pruebasrc/docu/retrieve/hybrid.py#L143-L153143 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._idf | def _idf(self, term: str) -> float | Ver pruebasrc/docu/retrieve/hybrid.py#L157-L160157 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._lexical | def _lexical(self, terms: set[str], limit: int) -> list[CodeChunk] | Ver pruebasrc/docu/retrieve/hybrid.py#L162-L179162 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._structural | def _structural(self, terms: set[str]) -> list[CodeChunk] | Ver pruebasrc/docu/retrieve/hybrid.py#L181-L193181 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._dense | def _dense(self, query: str, limit: int) -> list[CodeChunk] | Ver pruebasrc/docu/retrieve/hybrid.py#L195-L213195 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.search | def search(self, query: str, limit: int=..., expand_query: bool=...) -> list[tuple[CodeChunk, float]] | Ver pruebasrc/docu/retrieve/hybrid.py#L217-L253217 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_index | def build_index(root: Path | str) -> CodeIndex | Ver pruebasrc/docu/retrieve/hybrid.py#L256-L277256def 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) |
tokenize | def tokenize(text: str) -> list[str] | Ver pruebasrc/docu/retrieve/search.py#L27-L4127def 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_identifier | def looks_like_identifier(query: str) -> bool | Ver pruebasrc/docu/retrieve/search.py#L44-L6444def 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.text | def text(self) -> str | Ver pruebasrc/docu/retrieve/search.py#L79-L80Anotaciones: @property79 def text(self) -> str: 80 return f"{self.heading}\n{self.body}" |
Section.to_dict | def to_dict(self) -> dict[str, object] | Ver pruebasrc/docu/retrieve/search.py#L82-L8982 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_sections | def split_sections(path: Path, content: str, level: str=...) -> list[Section] | Ver pruebasrc/docu/retrieve/search.py#L92-L12292def 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 pruebasrc/docu/retrieve/search.py#L136-L141136 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_directory | def from_directory(cls, directory: Path | str, glossary: Mapping[str, Sequence[str]] | None=...) -> DocIndex | Ver pruebasrc/docu/retrieve/search.py#L144-L152Anotaciones: @classmethod144 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._idf | def _idf(self, term: str) -> float | Ver pruebasrc/docu/retrieve/search.py#L154-L157154 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.search | def search(self, query: str, limit: int=..., expand_query: bool=..., level: str | None=...) -> list[tuple[Section, float]] | Ver pruebasrc/docu/retrieve/search.py#L159-L189159 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_empty | def is_empty(self) -> bool | Ver pruebasrc/docu/retrieve/search.py#L192-L193Anotaciones: @property192 def is_empty(self) -> bool: 193 return not self.sections |
DocIndex.headings | def headings(self) -> Iterable[str] | Ver pruebasrc/docu/retrieve/search.py#L195-L196195 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
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
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"