diplodocus 0.15.0

Build coherent documentation websites for polyglot software projects.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
//! Portable evidence records. Collecting and verifying evidence is separate.

use std::collections::{BTreeMap, BTreeSet};

use serde::{Deserialize, Serialize};

use crate::diagnostics::{DiagnosticPath, DiagnosticSource};

use super::{ExecutionEngine, ExecutionMode, SourceLocation, SourceSpan, TargetReference};

/// An algorithm-qualified digest, without assumptions about a cache encoding.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Fingerprint {
    /// Stable digest algorithm identifier, such as `sha256`.
    pub algorithm: String,
    /// Digest encoded according to that algorithm's portable convention.
    pub value: String,
}

/// Evidence for a fact, declaration, extraction, or execution.
///
/// Producers record exact tool versions and portable inputs, never timestamps,
/// process IDs, connection data, environment values, or checkout directories.
/// Missing observations stay absent rather than being inferred from the host.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Provenance {
    /// Activity responsible for the value.
    pub activity: ProvenanceActivity,
    /// Configuration-relative or repository-relative origin when known.
    pub source: Option<DiagnosticSource>,
    /// Source-file byte range when known.
    pub span: Option<SourceSpan>,
    /// Component identities mapped to exact versions, sorted by identity.
    pub tools: BTreeMap<String, String>,
}

/// Activity-specific provenance without transient runtime identifiers.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "kebab-case", deny_unknown_fields)]
pub enum ProvenanceActivity {
    /// Completed Sphinx discovery in the verified supplied Python checkout.
    PythonRuntime {
        /// Owning extraction target.
        target: TargetReference,
        /// Versioned native export and normalization contract.
        policy: String,
        /// Observed Python interpreter version.
        python_version: String,
        /// Observed Sphinx version.
        sphinx_version: String,
        /// Observed Docutils version.
        docutils_version: String,
        /// Verified package metadata version.
        package_version: String,
        /// Loaded distribution versions, without installation paths.
        dependencies: BTreeMap<String, String>,
        /// Maintained and native module inputs consumed by discovery.
        inputs: Vec<InputFingerprint>,
    },
    /// Completed native Documenter examples in a prepared Julia environment.
    DocumenterExamples {
        /// Owning authored collection.
        collection: String,
        /// Native execution and output contract.
        policy: String,
        /// Observed Julia version.
        julia_version: String,
        /// Loaded dependency UUIDs and versions, without checkout paths.
        dependencies: BTreeMap<String, String>,
        /// Selected Julia environment's project file.
        project: InputFingerprint,
        /// Project, available manifests, and explicitly declared environment files.
        environment_inputs: Vec<InputFingerprint>,
        /// Original authored page and its content fingerprint.
        input: InputFingerprint,
        /// Completed examples in authored order.
        examples: Vec<DocumenterExampleOutcome>,
    },
    /// Native Rust doctests checked against the selected checkout and features.
    RustDoctests {
        /// Owning Rust extraction target.
        target: TargetReference,
        /// Versioned native execution and comparison contract.
        policy: String,
        /// Cargo package identity.
        package_name: String,
        /// Version read from Cargo metadata.
        package_version: String,
        /// Observed compiler version and commit.
        compiler_version: String,
        /// Resolved dependency versions without local paths.
        dependencies: BTreeMap<String, String>,
        /// Effective Cargo features in sorted order.
        features: Vec<String>,
        /// Host target triple used for compilation and execution.
        host: String,
        /// Maintained source and environment input fingerprints.
        inputs: Vec<InputFingerprint>,
        /// Native example outcomes in discovery order.
        examples: Vec<RustDoctestOutcome>,
    },
    /// Completed Python or Julia API doctests in the supplied checkout.
    ApiExamples {
        /// Owning workspace package.
        package: String,
        /// Native language adapter.
        language: String,
        /// Versioned preparation and comparison contract.
        policy: String,
        /// Observed interpreter version.
        runtime_version: String,
        /// Verified checkout identity.
        package_name: String,
        /// Version read from the loaded checkout's metadata.
        package_version: String,
        /// Loaded dependency versions without library paths.
        dependencies: BTreeMap<String, String>,
        /// Decoded documentation source and fingerprint.
        input: InputFingerprint,
        /// Example outcomes in source order.
        examples: Vec<ApiExampleOutcome>,
    },
    /// Julia native API discovery or legacy type completion in the verified checkout.
    JuliaRuntime {
        /// Owning extraction target.
        target: TargetReference,
        /// Native helper contract.
        policy: String,
        /// Observed Julia interpreter version.
        julia_version: String,
        /// Loaded package identity and version.
        package_name: String,
        /// Loaded package UUID.
        package_uuid: String,
        /// Loaded package version.
        package_version: String,
        /// Loaded dependency UUIDs and versions, without library paths.
        dependencies: BTreeMap<String, String>,
    },
    /// Completed roxygen2 generation in the supplied R checkout.
    RDocumentation {
        /// Owning workspace package.
        package: String,
        /// Versioned generation contract.
        policy: String,
        /// Observed R interpreter version.
        r_version: String,
        /// Observed roxygen2 version.
        roxygen2_version: String,
        /// Effective package loader, either `pkgload` or `source`.
        loader: String,
        /// Effective roclets in their configured execution order.
        roclets: Vec<String>,
        /// Loaded namespace versions without local library paths.
        dependencies: BTreeMap<String, String>,
        /// Maintained source and declared supplemental inputs before generation.
        inputs: Vec<InputFingerprint>,
        /// Generated checkout files observed after successful generation.
        outputs: Vec<InputFingerprint>,
    },
    /// Native R API discovery in the verified supplied checkout.
    RRuntime {
        /// Owning workspace package.
        package: String,
        /// Versioned discovery contract.
        policy: String,
        /// Observed R interpreter version.
        r_version: String,
        /// Verified checkout version from DESCRIPTION.
        package_version: String,
        /// Loaded namespace versions without local library paths.
        dependencies: BTreeMap<String, String>,
        /// Source, metadata, and documentation supplied to native discovery.
        inputs: Vec<InputFingerprint>,
    },
    /// Completed native R Markdown execution in the prepared checkout.
    RMarkdown {
        /// Owning workspace package.
        package: String,
        /// Native helper contract.
        policy: String,
        /// Observed interpreter version.
        r_version: String,
        /// Observed knitr version.
        knitr_version: String,
        /// Observed checkout version.
        package_version: String,
        /// Loaded namespace versions without library paths.
        dependencies: BTreeMap<String, String>,
        /// Original article source and fingerprint.
        input: InputFingerprint,
        /// Evaluated Markdown fingerprint.
        output: Fingerprint,
        /// Chunk outcomes in source order, including explicit omissions.
        chunks: Vec<RMarkdownChunkOutcome>,
        /// Inline evaluations in knitr processing order.
        inline: Vec<RMarkdownInlineOutcome>,
    },
    /// An explicit declaration or source observation.
    Declaration,
    /// A decoded documentation range mapped back to its source literal.
    DecodedDocumentation {
        /// Zero-based UTF-8 byte range in the decoded document.
        decoded_span: SourceSpan,
    },
    /// Inert parsing of Markdown output from an authored cell.
    ///
    /// The enclosing provenance source and span identify the producing page and
    /// authored cell fence. Fragment block and diagnostic ranges are relative to
    /// the output identified here, not that page. No execution is implied.
    GeneratedMarkdown {
        /// Owning authored content collection ID.
        collection: String,
        /// Zero-based producing cell ordinal in authored source order.
        cell: usize,
        /// Zero-based output-slot ordinal within the producing cell.
        output: usize,
    },
    /// API extraction from an explicit target.
    Extraction {
        /// Package-scoped source target.
        target: TargetReference,
        /// Extraction behavior used for this result.
        mode: ExtractionMode,
        /// Complete sorted capability identifiers used by the extractor.
        capabilities: BTreeSet<String>,
        /// Parser components keyed by identity, in lexical order.
        parsers: BTreeMap<String, ParserProvenance>,
        /// Contributing inputs keyed first by repository ID, then relative path.
        inputs: BTreeMap<String, BTreeMap<DiagnosticPath, ExtractionInput>>,
    },
    /// Native R metadata and citation completion from the supplied checkout.
    PackageMetadata {
        /// Workspace package identity.
        package: String,
        /// Observed R interpreter version.
        r_version: String,
        /// Native helper policy used to complete the results.
        policy: String,
        /// Exact source bytes supplied to native helpers.
        inputs: Vec<InputFingerprint>,
    },
    /// Completed native R help-topic examples from the supplied checkout.
    RdExamples {
        /// Workspace package identity.
        package: String,
        /// Native example adapter policy.
        policy: String,
        /// Observed interpreter version.
        r_version: String,
        /// Observed checkout package version.
        package_version: String,
        /// Loaded namespace versions, excluding local library paths.
        dependencies: BTreeMap<String, String>,
        /// Original help-topic input.
        input: InputFingerprint,
        /// Executed expressions in source order.
        executed: Vec<String>,
        /// Explicit illustrative regions excluded by native Rd conversion.
        illustrative: Vec<String>,
        /// Conditional omissions and their evaluated reasons.
        skipped: Vec<String>,
    },
    /// Successful execution or restoration of an executed page result.
    Execution {
        /// Declared execution mode.
        mode: ExecutionMode,
        /// Engine used to produce the result.
        engine: ExecutionEngine,
        /// Observed kernel information, without launch commands or credentials.
        kernel: KernelProvenance,
        /// Whether the result was freshly executed or restored.
        origin: ExecutionOrigin,
        /// Declared environment evidence sorted by repository and relative path.
        declared_environment_inputs: Vec<InputFingerprint>,
    },
}

/// One successfully executed Documenter example.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DocumenterExampleOutcome {
    /// Full fence range in the original authored page.
    pub span: SourceSpan,
    /// Page-local session name; absent for an isolated anonymous example.
    pub session: Option<String>,
    /// Validated native results, in display order.
    pub outputs: Vec<DocumenterOutput>,
}

/// Native Julia output admitted by the Documenter adapter.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "kebab-case", deny_unknown_fields)]
pub enum DocumenterOutput {
    /// Literal native text, escaped by renderers.
    Text {
        /// Captured streams or a native text/plain representation.
        text: String,
    },
    /// A validated, retained native image.
    Image {
        /// Image format verified against its exact bytes.
        media_type: String,
        /// Content-addressed portable asset.
        asset: super::AssetReference,
    },
}

/// One checked transcript expression or script in an API document.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ApiExampleOutcome {
    /// Example range in the decoded documentation.
    pub span: SourceSpan,
    /// Submitted source, including supported comparison directives.
    pub source: String,
    /// Authored expected output.
    pub expected: String,
    /// Actual literal output, empty for explicitly skipped examples.
    pub actual: String,
    /// Executed, expected-error, or explicit-skip.
    pub outcome: String,
    /// Explanation of an explicit omission.
    pub reason: Option<String>,
    /// Effective language-specific comparison and setup options.
    pub options: BTreeMap<String, String>,
}

/// Native chunk evidence independent of a Jupyter kernel.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RMarkdownChunkOutcome {
    /// Full chunk range in the original R Markdown input.
    pub span: SourceSpan,
    /// Native chunk label.
    pub label: String,
    /// Effective supported options observed before execution.
    pub options: BTreeMap<String, String>,
    /// Executed, illustrative, conditional-skip, or allowed-error.
    pub outcome: String,
    /// Explanation of an explicit omission or permitted error.
    pub reason: Option<String>,
}

/// One inline R result attributed to the original expression.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RMarkdownInlineOutcome {
    /// Expression range in the original R Markdown source.
    pub span: SourceSpan,
    /// Native Markdown representation of the evaluated value.
    pub value: String,
}

/// Extraction modes understood by this schema.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ExtractionMode {
    /// Analyze sources without loading the documented package.
    Static,
    /// Resolve declarations with native compiler tooling, allowing local builds.
    Compiler,
    /// Discover declarations by loading the supplied package with native tooling.
    Native,
}

/// One Rust example discovered and checked by the native doctest runner.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RustDoctestOutcome {
    /// Native test name, retained to reconcile discovery with execution.
    pub name: String,
    /// Original maintained file when native attribution is available.
    pub source: Option<SourceLocation>,
    /// One-based source line reported by rustdoc.
    pub line: usize,
    /// Original doctest code, including native setup syntax.
    pub code: String,
    /// Effective native doctest attributes.
    pub attributes: BTreeMap<String, String>,
    /// Checked native outcome.
    pub outcome: RustDoctestStatus,
    /// Output reported by the native runner; successful stdout may be absent.
    pub output: String,
    /// Native reason for an explicit omission.
    pub reason: Option<String>,
}

/// Successful Rust doctest outcomes preserve compilation and execution semantics.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum RustDoctestStatus {
    /// Compiled and executed successfully.
    Executed,
    /// Compiled successfully under `no_run`.
    CompileOnly,
    /// Matched an explicit compilation failure or panic expectation.
    ExpectedError,
    /// Omitted by an explicit native ignore attribute.
    ExplicitSkip,
}

/// One parser component and its output-affecting settings.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ParserProvenance {
    /// Exact component version.
    pub version: String,
    /// Semantic parser role, such as `python-syntax` or `docstring`.
    pub role: String,
    /// Canonically spelled settings, sorted by setting name.
    pub settings: BTreeMap<String, String>,
}

/// Evidence for one contributing extraction input.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ExtractionInput {
    /// Input classification, such as `python-stub`, `rd`, or `package-metadata`.
    pub kind: String,
    /// Original input content fingerprint.
    pub fingerprint: Fingerprint,
    /// Parser component identities, sorted lexically.
    pub parsers: BTreeSet<String>,
}

/// Source evidence attached to a specific fact, such as one signature.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SourceEvidence {
    /// Proven repository source and optional byte range.
    pub source: SourceLocation,
    /// Contribution made by the source.
    pub role: SourceRole,
    /// Parser component identities, empty for direct observations.
    pub parsers: BTreeSet<String>,
}

/// Semantic role of source evidence.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum SourceRole {
    /// Package metadata.
    Metadata,
    /// An export declaration.
    Export,
    /// A method or API registration.
    Registration,
    /// The entity's definition.
    Definition,
    /// A signature declaration, possibly in a stub.
    Signature,
    /// Documentation prose or structure.
    Documentation,
    /// Evidence supporting a diagnostic.
    Diagnostic,
}

/// One explicitly declared environment input and its observed content digest.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct InputFingerprint {
    /// Repository-relative input file.
    pub source: SourceLocation,
    /// Content fingerprint of that input.
    pub fingerprint: Fingerprint,
}

/// Selected kernel identity and versions reported by the executing kernel.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct KernelProvenance {
    /// Configured kernelspec name, not a filesystem path.
    pub name: String,
    /// Kernel-reported language.
    pub language: Option<String>,
    /// Kernel-reported language version.
    pub language_version: Option<String>,
    /// Kernel implementation version when available.
    pub version: Option<String>,
}

/// How a successful executed result was obtained.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ExecutionOrigin {
    /// Fresh execution during this build.
    Executed,
    /// Restoration of a previously executed result.
    Cache,
}