@doccov/spec 0.24.1 → 0.27.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.ts +105 -8
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -29,7 +29,47 @@ type ExampleAnalysis = {
|
|
|
29
29
|
runtimeDrifts?: ExampleRuntimeDrift[];
|
|
30
30
|
};
|
|
31
31
|
type MissingDocRule = "description" | "params" | "returns" | "examples" | "throws";
|
|
32
|
-
|
|
32
|
+
/**
|
|
33
|
+
* Unified documentation health score combining completeness and accuracy.
|
|
34
|
+
*/
|
|
35
|
+
type DocumentationHealth = {
|
|
36
|
+
/** Overall health score (0-100), weighted combination of completeness + accuracy */
|
|
37
|
+
score: number;
|
|
38
|
+
/** Completeness (coverage) metrics */
|
|
39
|
+
completeness: {
|
|
40
|
+
/** Completeness score (0-100) */
|
|
41
|
+
score: number;
|
|
42
|
+
/** Number of documented exports */
|
|
43
|
+
documented: number;
|
|
44
|
+
/** Total exports analyzed */
|
|
45
|
+
total: number;
|
|
46
|
+
/** Missing docs by rule */
|
|
47
|
+
missing: Record<MissingDocRule, number>;
|
|
48
|
+
};
|
|
49
|
+
/** Accuracy (drift) metrics */
|
|
50
|
+
accuracy: {
|
|
51
|
+
/** Accuracy score (0-100) - penalized by drift issues */
|
|
52
|
+
score: number;
|
|
53
|
+
/** Total drift issues found */
|
|
54
|
+
issues: number;
|
|
55
|
+
/** Issues that can be auto-fixed */
|
|
56
|
+
fixable: number;
|
|
57
|
+
/** Issues by category */
|
|
58
|
+
byCategory: Record<DriftCategory, number>;
|
|
59
|
+
};
|
|
60
|
+
/** Example validation metrics (if run) */
|
|
61
|
+
examples?: {
|
|
62
|
+
/** Example score (0-100) */
|
|
63
|
+
score: number;
|
|
64
|
+
/** Examples that passed validation */
|
|
65
|
+
passed: number;
|
|
66
|
+
/** Examples that failed validation */
|
|
67
|
+
failed: number;
|
|
68
|
+
/** Total examples analyzed */
|
|
69
|
+
total: number;
|
|
70
|
+
};
|
|
71
|
+
};
|
|
72
|
+
type DocCovSpecVersion = "0.1.0" | "1.0.0";
|
|
33
73
|
type DocCovSpec = {
|
|
34
74
|
$schema?: string;
|
|
35
75
|
doccov: DocCovSpecVersion;
|
|
@@ -45,23 +85,43 @@ type DocCovSpec = {
|
|
|
45
85
|
summary: DocCovSummary;
|
|
46
86
|
/** Per-analysis, keyed by openpkg ID */
|
|
47
87
|
exports: Record<string, ExportAnalysis>;
|
|
88
|
+
/** API surface completeness analysis */
|
|
89
|
+
apiSurface?: ApiSurfaceResult;
|
|
48
90
|
};
|
|
49
91
|
type DocCovSummary = {
|
|
50
|
-
/**
|
|
92
|
+
/**
|
|
93
|
+
* Overall coverage score (0-100)
|
|
94
|
+
* @deprecated Use `health.completeness.score` instead. Will be removed in next major.
|
|
95
|
+
*/
|
|
51
96
|
score: number;
|
|
52
|
-
/**
|
|
97
|
+
/**
|
|
98
|
+
* Total exports analyzed
|
|
99
|
+
* @deprecated Use `health.completeness.total` instead. Will be removed in next major.
|
|
100
|
+
*/
|
|
53
101
|
totalExports: number;
|
|
54
|
-
/**
|
|
102
|
+
/**
|
|
103
|
+
* Exports with complete documentation
|
|
104
|
+
* @deprecated Use `health.completeness.documented` instead. Will be removed in next major.
|
|
105
|
+
*/
|
|
55
106
|
documentedExports: number;
|
|
56
|
-
/**
|
|
107
|
+
/**
|
|
108
|
+
* Missing documentation by rule
|
|
109
|
+
* @deprecated Use `health.completeness.missing` instead. Will be removed in next major.
|
|
110
|
+
*/
|
|
57
111
|
missingByRule: Record<MissingDocRule, number>;
|
|
58
|
-
/**
|
|
112
|
+
/**
|
|
113
|
+
* Drift summary
|
|
114
|
+
* @deprecated Use `health.accuracy` instead. Will be removed in next major.
|
|
115
|
+
*/
|
|
59
116
|
drift: {
|
|
60
117
|
total: number;
|
|
61
118
|
fixable: number;
|
|
62
119
|
byCategory: Record<DriftCategory, number>;
|
|
63
120
|
};
|
|
64
|
-
/**
|
|
121
|
+
/**
|
|
122
|
+
* Example validation summary (if run)
|
|
123
|
+
* @deprecated Use `health.examples` instead. Will be removed in next major.
|
|
124
|
+
*/
|
|
65
125
|
examples?: {
|
|
66
126
|
total: number;
|
|
67
127
|
withExamples: number;
|
|
@@ -70,6 +130,8 @@ type DocCovSummary = {
|
|
|
70
130
|
runtimePassed?: number;
|
|
71
131
|
runtimeFailed?: number;
|
|
72
132
|
};
|
|
133
|
+
/** Unified documentation health metrics */
|
|
134
|
+
health?: DocumentationHealth;
|
|
73
135
|
};
|
|
74
136
|
type ExportAnalysis = {
|
|
75
137
|
/** Coverage score for this (0-100) */
|
|
@@ -81,6 +143,41 @@ type ExportAnalysis = {
|
|
|
81
143
|
/** Example validation results */
|
|
82
144
|
examples?: ExampleAnalysis;
|
|
83
145
|
};
|
|
146
|
+
/** Location context for where a type is referenced */
|
|
147
|
+
type TypeReferenceLocation = "return" | "parameter" | "property" | "extends" | "type-parameter";
|
|
148
|
+
/** A type referenced in public API but not exported */
|
|
149
|
+
type ForgottenExport = {
|
|
150
|
+
/** Name of the forgotten type */
|
|
151
|
+
name: string;
|
|
152
|
+
/** Where the type is defined (file path) */
|
|
153
|
+
definedIn?: {
|
|
154
|
+
file: string;
|
|
155
|
+
line?: number;
|
|
156
|
+
};
|
|
157
|
+
/** Which exports reference this type */
|
|
158
|
+
referencedBy: Array<{
|
|
159
|
+
exportName: string;
|
|
160
|
+
location: TypeReferenceLocation;
|
|
161
|
+
}>;
|
|
162
|
+
/** Whether type is from external package */
|
|
163
|
+
isExternal: boolean;
|
|
164
|
+
/** Suggested fix if applicable */
|
|
165
|
+
fix?: {
|
|
166
|
+
targetFile: string;
|
|
167
|
+
exportStatement: string;
|
|
168
|
+
};
|
|
169
|
+
};
|
|
170
|
+
/** API Surface analysis result */
|
|
171
|
+
type ApiSurfaceResult = {
|
|
172
|
+
/** Total types referenced in public API */
|
|
173
|
+
totalReferenced: number;
|
|
174
|
+
/** Types that are properly exported */
|
|
175
|
+
exported: number;
|
|
176
|
+
/** Types referenced but not exported */
|
|
177
|
+
forgotten: ForgottenExport[];
|
|
178
|
+
/** Completeness percentage (exported / totalReferenced * 100) */
|
|
179
|
+
completeness: number;
|
|
180
|
+
};
|
|
84
181
|
type DocCovSchemaVersion = "1.0.0" | "latest";
|
|
85
182
|
declare const LATEST_VERSION: DocCovSchemaVersion;
|
|
86
183
|
type DocCovSpecError = {
|
|
@@ -97,4 +194,4 @@ declare function validateDocCovSpec(spec: unknown, version?: DocCovSchemaVersion
|
|
|
97
194
|
declare function assertDocCovSpec(spec: unknown, version?: DocCovSchemaVersion): asserts spec is DocCovSpec;
|
|
98
195
|
declare function getDocCovValidationErrors(spec: unknown, version?: DocCovSchemaVersion): DocCovSpecError[];
|
|
99
196
|
declare function getAvailableDocCovVersions(): string[];
|
|
100
|
-
export { validateDocCovSpec, getDocCovValidationErrors, getAvailableDocCovVersions, assertDocCovSpec, SCHEMA_VERSION, SCHEMA_URL, MissingDocRule, LATEST_VERSION, ExportAnalysis, ExampleTypecheckError, ExampleRuntimeDrift, ExampleAnalysis, DriftType, DriftCategory, DocCovSummary, DocCovSpecVersion, DocCovSpecError, DocCovSpec, DocCovSchemaVersion, DocCovDrift, DRIFT_CATEGORY_LABELS, DRIFT_CATEGORY_DESCRIPTIONS, DRIFT_CATEGORIES };
|
|
197
|
+
export { validateDocCovSpec, getDocCovValidationErrors, getAvailableDocCovVersions, assertDocCovSpec, TypeReferenceLocation, SCHEMA_VERSION, SCHEMA_URL, MissingDocRule, LATEST_VERSION, ForgottenExport, ExportAnalysis, ExampleTypecheckError, ExampleRuntimeDrift, ExampleAnalysis, DriftType, DriftCategory, DocumentationHealth, DocCovSummary, DocCovSpecVersion, DocCovSpecError, DocCovSpec, DocCovSchemaVersion, DocCovDrift, DRIFT_CATEGORY_LABELS, DRIFT_CATEGORY_DESCRIPTIONS, DRIFT_CATEGORIES, ApiSurfaceResult };
|