dsh-statcheck 0.0.0-stage → 0.1.1
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/CHANGELOG.md +53 -0
- package/LICENSE +201 -0
- package/README-zh.md +117 -0
- package/README.md +116 -2
- package/SECURITY.md +19 -0
- package/THIRD_PARTY_NOTICES.md +10 -0
- package/cordis.patch.yml +18 -0
- package/lib/check.d.ts +92 -0
- package/lib/check.d.ts.map +1 -0
- package/lib/check.js +250 -0
- package/lib/check.js.map +1 -0
- package/lib/config.d.ts +37 -0
- package/lib/config.d.ts.map +1 -0
- package/lib/config.js +44 -0
- package/lib/config.js.map +1 -0
- package/lib/index.d.ts +36 -0
- package/lib/index.d.ts.map +1 -0
- package/lib/index.js +50 -0
- package/lib/index.js.map +1 -0
- package/lib/math.d.ts +76 -0
- package/lib/math.d.ts.map +1 -0
- package/lib/math.js +218 -0
- package/lib/math.js.map +1 -0
- package/lib/report.d.ts +41 -0
- package/lib/report.d.ts.map +1 -0
- package/lib/report.js +91 -0
- package/lib/report.js.map +1 -0
- package/lib/runtime.d.ts +104 -0
- package/lib/runtime.d.ts.map +1 -0
- package/lib/runtime.js +235 -0
- package/lib/runtime.js.map +1 -0
- package/lib/tools/shared.d.ts +127 -0
- package/lib/tools/shared.d.ts.map +1 -0
- package/lib/tools/shared.js +61 -0
- package/lib/tools/shared.js.map +1 -0
- package/lib/tools/stat-check.d.ts +12 -0
- package/lib/tools/stat-check.d.ts.map +1 -0
- package/lib/tools/stat-check.js +83 -0
- package/lib/tools/stat-check.js.map +1 -0
- package/lib/tools/stat-recompute.d.ts +12 -0
- package/lib/tools/stat-recompute.d.ts.map +1 -0
- package/lib/tools/stat-recompute.js +82 -0
- package/lib/tools/stat-recompute.js.map +1 -0
- package/lib/tools/stat-report.d.ts +10 -0
- package/lib/tools/stat-report.d.ts.map +1 -0
- package/lib/tools/stat-report.js +66 -0
- package/lib/tools/stat-report.js.map +1 -0
- package/lib/version.d.ts +7 -0
- package/lib/version.d.ts.map +1 -0
- package/lib/version.js +7 -0
- package/lib/version.js.map +1 -0
- package/package.json +84 -4
- package/src/check.ts +308 -0
- package/src/config.ts +71 -0
- package/src/index.ts +75 -0
- package/src/math.ts +205 -0
- package/src/report.ts +113 -0
- package/src/runtime.ts +293 -0
- package/src/tools/shared.ts +77 -0
- package/src/tools/stat-check.ts +83 -0
- package/src/tools/stat-recompute.ts +82 -0
- package/src/tools/stat-report.ts +68 -0
- package/src/version.ts +7 -0
package/src/math.ts
ADDED
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Distribution tails for statistical consistency checks — zero dependencies.
|
|
3
|
+
*
|
|
4
|
+
* Implementations: Lanczos log-gamma, regularized incomplete beta (continued
|
|
5
|
+
* fraction), regularized upper incomplete gamma (series + continued fraction),
|
|
6
|
+
* and the normal CDF via an error-function approximation. Accuracy is ~1e-10
|
|
7
|
+
* for the beta/gamma paths, enough for p-values reported to three decimals.
|
|
8
|
+
*
|
|
9
|
+
* Sources are the standard Numerical Recipes formulas (public-domain algorithms,
|
|
10
|
+
* reimplemented in TypeScript).
|
|
11
|
+
*
|
|
12
|
+
* @module dsh-statcheck/math
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
const LANCZOS = [
|
|
16
|
+
0.99999999999980993, 676.5203681218851, -1259.1392167224028, 771.32342877765313,
|
|
17
|
+
-176.61502916214059, 12.507343278686905, -0.13857109526572012, 9.9843695780195716e-6,
|
|
18
|
+
1.5056327351493116e-7,
|
|
19
|
+
]
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Log-gamma (Lanczos approximation).
|
|
23
|
+
* @param value - a positive number.
|
|
24
|
+
* @returns ln Γ(value).
|
|
25
|
+
*/
|
|
26
|
+
export function logGamma(value: number): number {
|
|
27
|
+
if (value < 0.5) return Math.log(Math.PI / Math.sin(Math.PI * value)) - logGamma(1 - value)
|
|
28
|
+
const z = value - 1
|
|
29
|
+
let x = LANCZOS[0]!
|
|
30
|
+
for (let index = 1; index < LANCZOS.length; index += 1) x += LANCZOS[index]! / (z + index)
|
|
31
|
+
const t = z + LANCZOS.length - 2 + 0.5
|
|
32
|
+
return 0.5 * Math.log(2 * Math.PI) + (z + 0.5) * Math.log(t) - t + Math.log(x)
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Continued fraction for the regularized incomplete beta function.
|
|
37
|
+
* @param a - first shape parameter.
|
|
38
|
+
* @param b - second shape parameter.
|
|
39
|
+
* @param x - evaluation point in (0, 1).
|
|
40
|
+
* @returns the fraction value.
|
|
41
|
+
*/
|
|
42
|
+
function betaContinuedFraction(a: number, b: number, x: number): number {
|
|
43
|
+
const tiny = 1e-300
|
|
44
|
+
const qab = a + b
|
|
45
|
+
const qap = a + 1
|
|
46
|
+
const qam = a - 1
|
|
47
|
+
let c = 1
|
|
48
|
+
let d = 1 - (qab * x) / qap
|
|
49
|
+
if (Math.abs(d) < tiny) d = tiny
|
|
50
|
+
d = 1 / d
|
|
51
|
+
let h = d
|
|
52
|
+
for (let m = 1; m <= 300; m += 1) {
|
|
53
|
+
const m2 = 2 * m
|
|
54
|
+
let aa = (m * (b - m) * x) / ((qam + m2) * (a + m2))
|
|
55
|
+
d = 1 + aa * d
|
|
56
|
+
if (Math.abs(d) < tiny) d = tiny
|
|
57
|
+
c = 1 + aa / c
|
|
58
|
+
if (Math.abs(c) < tiny) c = tiny
|
|
59
|
+
d = 1 / d
|
|
60
|
+
h *= d * c
|
|
61
|
+
aa = (-(a + m) * (qab + m) * x) / ((a + m2) * (qap + m2))
|
|
62
|
+
d = 1 + aa * d
|
|
63
|
+
if (Math.abs(d) < tiny) d = tiny
|
|
64
|
+
c = 1 + aa / c
|
|
65
|
+
if (Math.abs(c) < tiny) c = tiny
|
|
66
|
+
d = 1 / d
|
|
67
|
+
const delta = d * c
|
|
68
|
+
h *= delta
|
|
69
|
+
if (Math.abs(delta - 1) < 3e-14) break
|
|
70
|
+
}
|
|
71
|
+
return h
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Regularized incomplete beta I_x(a, b).
|
|
76
|
+
* @param a - first shape parameter.
|
|
77
|
+
* @param b - second shape parameter.
|
|
78
|
+
* @param x - evaluation point in [0, 1].
|
|
79
|
+
* @returns I_x(a, b) in [0, 1].
|
|
80
|
+
*/
|
|
81
|
+
export function incompleteBeta(a: number, b: number, x: number): number {
|
|
82
|
+
if (x <= 0) return 0
|
|
83
|
+
if (x >= 1) return 1
|
|
84
|
+
const front = Math.exp(logGamma(a + b) - logGamma(a) - logGamma(b) + a * Math.log(x) + b * Math.log(1 - x))
|
|
85
|
+
if (x < (a + 1) / (a + b + 2)) return (front * betaContinuedFraction(a, b, x)) / a
|
|
86
|
+
return 1 - (front * betaContinuedFraction(b, a, 1 - x)) / b
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* Regularized upper incomplete gamma Q(a, x).
|
|
91
|
+
* @param a - shape parameter.
|
|
92
|
+
* @param x - evaluation point.
|
|
93
|
+
* @returns Q(a, x) in [0, 1].
|
|
94
|
+
*/
|
|
95
|
+
export function upperGamma(a: number, x: number): number {
|
|
96
|
+
if (x <= 0) return 1
|
|
97
|
+
if (x < a + 1) {
|
|
98
|
+
// Series for P(a, x).
|
|
99
|
+
let term = 1 / a
|
|
100
|
+
let sum = term
|
|
101
|
+
let current = a
|
|
102
|
+
for (let index = 1; index <= 1000; index += 1) {
|
|
103
|
+
current += 1
|
|
104
|
+
term *= x / current
|
|
105
|
+
sum += term
|
|
106
|
+
if (Math.abs(term) < Math.abs(sum) * 1e-15) break
|
|
107
|
+
}
|
|
108
|
+
return 1 - sum * Math.exp(-x + a * Math.log(x) - logGamma(a))
|
|
109
|
+
}
|
|
110
|
+
// Continued fraction for Q(a, x).
|
|
111
|
+
const tiny = 1e-300
|
|
112
|
+
let b = x + 1 - a
|
|
113
|
+
let c = 1 / tiny
|
|
114
|
+
let d = 1 / b
|
|
115
|
+
let h = d
|
|
116
|
+
for (let index = 1; index <= 1000; index += 1) {
|
|
117
|
+
const an = -index * (index - a)
|
|
118
|
+
b += 2
|
|
119
|
+
d = an * d + b
|
|
120
|
+
if (Math.abs(d) < tiny) d = tiny
|
|
121
|
+
c = b + an / c
|
|
122
|
+
if (Math.abs(c) < tiny) c = tiny
|
|
123
|
+
d = 1 / d
|
|
124
|
+
const delta = d * c
|
|
125
|
+
h *= delta
|
|
126
|
+
if (Math.abs(delta - 1) < 3e-14) break
|
|
127
|
+
}
|
|
128
|
+
return h * Math.exp(-x + a * Math.log(x) - logGamma(a))
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* Standard normal CDF (Abramowitz–Stegun 7.1.26; |error| < 1.5e-7).
|
|
133
|
+
* @param value - the z score.
|
|
134
|
+
* @returns Φ(value).
|
|
135
|
+
*/
|
|
136
|
+
export function normalCdf(value: number): number {
|
|
137
|
+
// Φ(x) = 0.5 * (1 + erf(x / √2))
|
|
138
|
+
const z = Math.abs(value) / Math.SQRT2
|
|
139
|
+
const t = 1 / (1 + 0.3275911 * z)
|
|
140
|
+
const erf =
|
|
141
|
+
1 -
|
|
142
|
+
((((1.061405429 * t - 1.453152027) * t + 1.421413741) * t - 0.284496736) * t + 0.254829592) * t * Math.exp(-z * z)
|
|
143
|
+
const cdf = 0.5 * (1 + erf)
|
|
144
|
+
return value >= 0 ? cdf : 1 - cdf
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* Two-tailed p for Student's t.
|
|
149
|
+
* @param t - the t statistic (absolute value is used).
|
|
150
|
+
* @param df - degrees of freedom (> 0).
|
|
151
|
+
* @returns the two-tailed p value.
|
|
152
|
+
*/
|
|
153
|
+
export function tTwoTailedP(t: number, df: number): number {
|
|
154
|
+
if (!(df > 0) || !Number.isFinite(df)) throw new RangeError(`df must be > 0, got ${String(df)}`)
|
|
155
|
+
const x = df / (df + t * t)
|
|
156
|
+
return incompleteBeta(df / 2, 0.5, x)
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
/**
|
|
160
|
+
* Upper-tail p for the F distribution.
|
|
161
|
+
* @param f - the F statistic.
|
|
162
|
+
* @param df1 - numerator degrees of freedom.
|
|
163
|
+
* @param df2 - denominator degrees of freedom.
|
|
164
|
+
* @returns P(F >= f).
|
|
165
|
+
*/
|
|
166
|
+
export function fUpperP(f: number, df1: number, df2: number): number {
|
|
167
|
+
if (!(df1 > 0) || !(df2 > 0)) throw new RangeError(`df must be > 0, got ${String(df1)}, ${String(df2)}`)
|
|
168
|
+
if (f <= 0) return 1
|
|
169
|
+
return incompleteBeta(df2 / 2, df1 / 2, df2 / (df2 + df1 * f))
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
/**
|
|
173
|
+
* Upper-tail p for the chi-square distribution.
|
|
174
|
+
* @param chi2 - the chi-square statistic.
|
|
175
|
+
* @param df - degrees of freedom (> 0).
|
|
176
|
+
* @returns P(χ² >= chi2).
|
|
177
|
+
*/
|
|
178
|
+
export function chiSquareUpperP(chi2: number, df: number): number {
|
|
179
|
+
if (!(df > 0)) throw new RangeError(`df must be > 0, got ${String(df)}`)
|
|
180
|
+
if (chi2 <= 0) return 1
|
|
181
|
+
return upperGamma(df / 2, chi2 / 2)
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
/**
|
|
185
|
+
* Two-tailed p for a correlation r with df = n - 2.
|
|
186
|
+
* @param r - the correlation.
|
|
187
|
+
* @param df - degrees of freedom (> 0).
|
|
188
|
+
* @returns the two-tailed p value.
|
|
189
|
+
*/
|
|
190
|
+
export function rTwoTailedP(r: number, df: number): number {
|
|
191
|
+
if (!(df > 0)) throw new RangeError(`df must be > 0, got ${String(df)}`)
|
|
192
|
+
if (Math.abs(r) > 1) throw new RangeError(`r must be in [-1, 1], got ${String(r)}`)
|
|
193
|
+
if (Math.abs(r) === 1) return 0
|
|
194
|
+
const t = r * Math.sqrt(df / (1 - r * r))
|
|
195
|
+
return tTwoTailedP(t, df)
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
/**
|
|
199
|
+
* Two-tailed p for a z statistic.
|
|
200
|
+
* @param z - the z statistic.
|
|
201
|
+
* @returns the two-tailed p value.
|
|
202
|
+
*/
|
|
203
|
+
export function zTwoTailedP(z: number): number {
|
|
204
|
+
return 2 * (1 - normalCdf(Math.abs(z)))
|
|
205
|
+
}
|
package/src/report.ts
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* SARIF 2.1.0 and Markdown rendering for statistical findings.
|
|
3
|
+
*
|
|
4
|
+
* Every finding names the reported value, the recomputed value and the exact
|
|
5
|
+
* character range, so a reviewer can check it in seconds. Nothing is described
|
|
6
|
+
* as misconduct: the text says "the reported p does not follow from the
|
|
7
|
+
* reported statistic".
|
|
8
|
+
*
|
|
9
|
+
* @module dsh-statcheck/report
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
import type { StatFinding } from './check.ts'
|
|
13
|
+
|
|
14
|
+
/** Minimal SARIF shapes emitted here. */
|
|
15
|
+
export interface StatSarifResult {
|
|
16
|
+
readonly ruleId: string
|
|
17
|
+
readonly level: 'error' | 'warning' | 'note'
|
|
18
|
+
readonly message: { readonly text: string }
|
|
19
|
+
readonly locations: readonly {
|
|
20
|
+
readonly physicalLocation: {
|
|
21
|
+
readonly artifactLocation: { readonly uri: string }
|
|
22
|
+
readonly region: { readonly startLine: number; readonly startColumn: number }
|
|
23
|
+
}
|
|
24
|
+
}[]
|
|
25
|
+
readonly properties: Record<string, unknown>
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** Read a finite recomputed p, tolerating the JSON `null` a df error emits. */
|
|
29
|
+
function recomputedOf(finding: StatFinding): number | undefined {
|
|
30
|
+
const value: unknown = finding.recomputed?.p
|
|
31
|
+
return typeof value === 'number' && Number.isFinite(value) ? value : undefined
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* Map a UTF-16 character offset to a 1-based SARIF line/column.
|
|
36
|
+
* Without the source text the old line-1 + character-column fallback is kept.
|
|
37
|
+
*/
|
|
38
|
+
function regionOf(finding: StatFinding, text: string | undefined): { startLine: number; startColumn: number } {
|
|
39
|
+
if (text === undefined) return { startLine: 1, startColumn: finding.charStart + 1 }
|
|
40
|
+
const offset = Math.min(Math.max(finding.charStart, 0), text.length)
|
|
41
|
+
const before = text.slice(0, offset)
|
|
42
|
+
const lastNewline = before.lastIndexOf('\n')
|
|
43
|
+
return { startLine: before.split('\n').length, startColumn: offset - lastNewline }
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** Render findings as a SARIF 2.1.0 log. */
|
|
47
|
+
export function findingsToSarif(findings: readonly StatFinding[], version: string, text?: string): Record<string, unknown> {
|
|
48
|
+
const results: StatSarifResult[] = findings
|
|
49
|
+
.filter(finding => finding.status === 'inconsistent')
|
|
50
|
+
.map(finding => {
|
|
51
|
+
const recomputed = recomputedOf(finding)
|
|
52
|
+
return {
|
|
53
|
+
ruleId: `statcheck/${finding.issue ?? 'p-value'}`,
|
|
54
|
+
level: 'error' as const,
|
|
55
|
+
message: {
|
|
56
|
+
text: `${finding.text}: ${finding.detail}`,
|
|
57
|
+
},
|
|
58
|
+
locations: [
|
|
59
|
+
{
|
|
60
|
+
physicalLocation: {
|
|
61
|
+
artifactLocation: { uri: 'manuscript.txt' },
|
|
62
|
+
region: regionOf(finding, text),
|
|
63
|
+
},
|
|
64
|
+
},
|
|
65
|
+
],
|
|
66
|
+
properties: {
|
|
67
|
+
statistic: finding.statistic,
|
|
68
|
+
df: [...finding.df],
|
|
69
|
+
reportedP: finding.reported.p ?? null,
|
|
70
|
+
recomputedP: recomputed === undefined ? null : Number(recomputed.toFixed(6)),
|
|
71
|
+
issue: finding.issue ?? null,
|
|
72
|
+
charStart: finding.charStart,
|
|
73
|
+
charEnd: finding.charEnd,
|
|
74
|
+
},
|
|
75
|
+
}
|
|
76
|
+
})
|
|
77
|
+
const rules = [...new Set(results.map(result => result.ruleId))].map(id => ({ id, name: id.split('/')[1] ?? 'finding' }))
|
|
78
|
+
return {
|
|
79
|
+
$schema: 'https://json.schemastore.org/sarif-2.1.0.json',
|
|
80
|
+
version: '2.1.0',
|
|
81
|
+
runs: [
|
|
82
|
+
{
|
|
83
|
+
tool: { driver: { name: 'dsh-statcheck', version, ...(rules.length === 0 ? {} : { rules }) } },
|
|
84
|
+
results,
|
|
85
|
+
},
|
|
86
|
+
],
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** Render findings as a Markdown table plus a short explanation. */
|
|
91
|
+
export function findingsToMarkdown(findings: readonly StatFinding[], summary: { total: number; consistent: number; inconsistent: number; unparsed: number }): string {
|
|
92
|
+
const lines: string[] = []
|
|
93
|
+
lines.push('# Statistical consistency report')
|
|
94
|
+
lines.push('')
|
|
95
|
+
lines.push(
|
|
96
|
+
`${summary.total} reported statistic(s): ${summary.consistent} consistent, ${summary.inconsistent} inconsistent, ${summary.unparsed} unparsed.`,
|
|
97
|
+
)
|
|
98
|
+
lines.push('')
|
|
99
|
+
if (summary.inconsistent > 0) {
|
|
100
|
+
lines.push('> These findings mean **the reported p value does not follow from the reported statistic**. They do not imply misconduct, and they are not a substitute for a statistician reviewing the analysis.')
|
|
101
|
+
lines.push('')
|
|
102
|
+
}
|
|
103
|
+
lines.push('| # | Reported | Recomputed p | Status | Detail | Chars |')
|
|
104
|
+
lines.push('|---:|---|---:|---|---|---|')
|
|
105
|
+
findings.forEach((finding, index) => {
|
|
106
|
+
const recomputed = recomputedOf(finding)
|
|
107
|
+
const shown = recomputed === undefined ? 'n/a' : recomputed.toFixed(4)
|
|
108
|
+
lines.push(
|
|
109
|
+
`| ${index + 1} | \`${finding.text}\` | ${shown} | ${finding.status}${finding.issue === undefined ? '' : ` (${finding.issue})`} | ${finding.detail.replace(/\|/gu, '\\|')} | ${finding.charStart}-${finding.charEnd} |`,
|
|
110
|
+
)
|
|
111
|
+
})
|
|
112
|
+
return `${lines.join('\n')}\n`
|
|
113
|
+
}
|
package/src/runtime.ts
ADDED
|
@@ -0,0 +1,293 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Runtime: text/path handling, REP evidence and records for statistical
|
|
3
|
+
* findings.
|
|
4
|
+
*
|
|
5
|
+
* A finding is a check on the manuscript snapshot: `pass` for a consistent
|
|
6
|
+
* report, `fail` for an inconsistent one, `skipped` (`parse_failed`) when no p
|
|
7
|
+
* value could be located. The evidence status therefore inherits the same
|
|
8
|
+
* honesty rules as the rest of the family.
|
|
9
|
+
*
|
|
10
|
+
* @module dsh-statcheck/runtime
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
import { mkdir, readFile, realpath, stat, writeFile } from 'node:fs/promises'
|
|
14
|
+
import path from 'node:path'
|
|
15
|
+
import {
|
|
16
|
+
EvidenceStore,
|
|
17
|
+
RepStoreError,
|
|
18
|
+
stableId,
|
|
19
|
+
validateRep,
|
|
20
|
+
type AddEvidenceInput,
|
|
21
|
+
type CaptureInput,
|
|
22
|
+
type CheckResult,
|
|
23
|
+
type Evidence,
|
|
24
|
+
type ResearchRecord,
|
|
25
|
+
type Snapshot,
|
|
26
|
+
} from '@perrylink/dsh-research-core'
|
|
27
|
+
import { analyzeText, recomputeP, judgeP, StatInputError, type StatFinding, type StatisticKind, type StatSummary } from './check.ts'
|
|
28
|
+
import type { ResolvedConfig } from './config.ts'
|
|
29
|
+
import { VERSION } from './version.ts'
|
|
30
|
+
|
|
31
|
+
/** Stable runtime error codes. */
|
|
32
|
+
export type StatcheckErrorCode =
|
|
33
|
+
| 'INVALID_INPUT'
|
|
34
|
+
| 'NOT_FOUND'
|
|
35
|
+
| 'PATH_ESCAPE'
|
|
36
|
+
| 'NOT_A_FILE'
|
|
37
|
+
| 'TOO_LARGE'
|
|
38
|
+
| 'OUT_OF_DOMAIN'
|
|
39
|
+
| 'STORE_ERROR'
|
|
40
|
+
|
|
41
|
+
/** A typed failure. */
|
|
42
|
+
export class StatcheckError extends Error {
|
|
43
|
+
/** Stable code. */
|
|
44
|
+
readonly code: StatcheckErrorCode
|
|
45
|
+
|
|
46
|
+
constructor(code: StatcheckErrorCode, message: string) {
|
|
47
|
+
super(message)
|
|
48
|
+
this.name = 'StatcheckError'
|
|
49
|
+
this.code = code
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** The subset of the REP service used here. */
|
|
54
|
+
export interface EvidencePort {
|
|
55
|
+
capture(input: CaptureInput): Promise<{ snapshot: Snapshot }>
|
|
56
|
+
addEvidence(input: AddEvidenceInput): Promise<{ evidence: Evidence }>
|
|
57
|
+
buildRecord(options?: { evidenceIds?: readonly string[] }): Promise<Omit<ResearchRecord, 'manifest'>>
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** The `stat_check` success value. */
|
|
61
|
+
export interface StatCheckResult {
|
|
62
|
+
readonly ok: true
|
|
63
|
+
readonly summary: StatSummary
|
|
64
|
+
readonly findings: readonly StatFinding[]
|
|
65
|
+
readonly source: { readonly kind: 'file' | 'inline'; readonly id: string; readonly chars: number }
|
|
66
|
+
readonly evidenceId?: string
|
|
67
|
+
readonly recordPath?: string
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** Input for {@link StatcheckRuntime.check}. */
|
|
71
|
+
export interface StatCheckRequest {
|
|
72
|
+
readonly text?: string
|
|
73
|
+
readonly path?: string
|
|
74
|
+
readonly persist?: boolean
|
|
75
|
+
readonly maxFindings?: number
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** Options for {@link StatcheckRuntime}. */
|
|
79
|
+
export interface StatcheckRuntimeOptions {
|
|
80
|
+
readonly config: ResolvedConfig
|
|
81
|
+
readonly service?: EvidencePort
|
|
82
|
+
readonly now?: () => Date
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** True when `candidate` is inside `root`. */
|
|
86
|
+
function isInside(root: string, candidate: string): boolean {
|
|
87
|
+
return candidate === root || candidate.startsWith(root.endsWith(path.sep) ? root : `${root}${path.sep}`)
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** Media type by extension (the analyzed text keeps its source shape). */
|
|
91
|
+
function mediaTypeOf(name: string): Snapshot['mediaType'] {
|
|
92
|
+
const extension = name.toLowerCase().split('.').pop() ?? ''
|
|
93
|
+
if (extension === 'md' || extension === 'markdown') return 'text/markdown'
|
|
94
|
+
if (extension === 'tex' || extension === 'latex') return 'text/x-latex'
|
|
95
|
+
if (extension === 'html' || extension === 'htm') return 'text/html'
|
|
96
|
+
return 'text/plain'
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/** Map one finding to a REP check. */
|
|
100
|
+
export function findingToCheck(finding: StatFinding): CheckResult {
|
|
101
|
+
const status: CheckResult['status'] =
|
|
102
|
+
finding.status === 'consistent' ? 'pass' : finding.status === 'inconsistent' ? 'fail' : 'skipped'
|
|
103
|
+
return {
|
|
104
|
+
checkId: `chk-${finding.findingId}`,
|
|
105
|
+
check: 'stat-consistency',
|
|
106
|
+
status,
|
|
107
|
+
...(status === 'skipped' ? { code: 'parse_failed' as const } : {}),
|
|
108
|
+
severity: status === 'fail' ? 'error' : status === 'skipped' ? 'warning' : 'info',
|
|
109
|
+
detail: `${finding.text}: ${finding.detail}`,
|
|
110
|
+
expected: { reportedP: finding.reported.p, statistic: finding.reported.statistic, df: [...finding.df] },
|
|
111
|
+
actual: { recomputedP: Number.isNaN(finding.recomputed.p) ? null : Number(finding.recomputed.p.toFixed(6)) },
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/** The statcheck runtime. */
|
|
116
|
+
export class StatcheckRuntime {
|
|
117
|
+
readonly config: ResolvedConfig
|
|
118
|
+
|
|
119
|
+
readonly #service: EvidencePort | undefined
|
|
120
|
+
readonly #now: () => Date
|
|
121
|
+
#store: EvidenceStore | undefined
|
|
122
|
+
|
|
123
|
+
constructor(options: StatcheckRuntimeOptions) {
|
|
124
|
+
this.config = options.config
|
|
125
|
+
this.#service = options.service
|
|
126
|
+
this.#now = options.now ?? (() => new Date())
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/** Current ISO timestamp. */
|
|
130
|
+
iso(): string {
|
|
131
|
+
return this.#now().toISOString()
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/**
|
|
135
|
+
* Clamp a per-call findings cap to the configured hard cap.
|
|
136
|
+
* @param requested - the caller's value, when present.
|
|
137
|
+
* @returns a positive cap never larger than `config.maxFindings`.
|
|
138
|
+
*/
|
|
139
|
+
#maxFindings(requested: number | undefined): number {
|
|
140
|
+
if (requested === undefined || !Number.isSafeInteger(requested) || requested <= 0) return this.config.maxFindings
|
|
141
|
+
return Math.min(requested, this.config.maxFindings)
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/** The evidence port. */
|
|
145
|
+
port(): EvidencePort {
|
|
146
|
+
if (this.#service !== undefined) return this.#service
|
|
147
|
+
this.#store ??= new EvidenceStore(path.join(this.config.root, 'store'))
|
|
148
|
+
return this.#store
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
/** Resolve a manuscript path inside the workspace. */
|
|
152
|
+
async resolvePath(input: string): Promise<{ absolute: string; id: string }> {
|
|
153
|
+
if (typeof input !== 'string' || input.trim() === '') throw new StatcheckError('INVALID_INPUT', 'path must be a non-empty string')
|
|
154
|
+
const root = this.config.workspaceRoot
|
|
155
|
+
let realRoot: string
|
|
156
|
+
try {
|
|
157
|
+
realRoot = await realpath(root)
|
|
158
|
+
} catch {
|
|
159
|
+
throw new StatcheckError('NOT_FOUND', `workspace root does not exist: ${root}`)
|
|
160
|
+
}
|
|
161
|
+
const candidate = path.resolve(realRoot, input)
|
|
162
|
+
if (!isInside(realRoot, candidate)) throw new StatcheckError('PATH_ESCAPE', 'path resolves outside the workspace root')
|
|
163
|
+
let real: string
|
|
164
|
+
try {
|
|
165
|
+
real = await realpath(candidate)
|
|
166
|
+
} catch {
|
|
167
|
+
throw new StatcheckError('NOT_FOUND', `manuscript not found: ${input}`)
|
|
168
|
+
}
|
|
169
|
+
if (!isInside(realRoot, real)) throw new StatcheckError('PATH_ESCAPE', 'path escapes the workspace root through a symlink')
|
|
170
|
+
if (!(await stat(real)).isFile()) throw new StatcheckError('NOT_A_FILE', `not a regular file: ${input}`)
|
|
171
|
+
return { absolute: real, id: path.relative(realRoot, real).split(path.sep).join('/') }
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
/**
|
|
175
|
+
* Analyze text or a workspace manuscript.
|
|
176
|
+
* @param request - text or path plus optional caps.
|
|
177
|
+
* @returns findings, counts and (when persisting) the evidence id and record path.
|
|
178
|
+
*/
|
|
179
|
+
async check(request: StatCheckRequest): Promise<StatCheckResult> {
|
|
180
|
+
if ((request.text === undefined) === (request.path === undefined)) {
|
|
181
|
+
throw new StatcheckError('INVALID_INPUT', 'pass exactly one of text or path')
|
|
182
|
+
}
|
|
183
|
+
let text: string
|
|
184
|
+
let source: StatCheckResult['source']
|
|
185
|
+
let mediaType: Snapshot['mediaType'] = 'text/plain'
|
|
186
|
+
let sourceRef: AddEvidenceInput['sourceRef']
|
|
187
|
+
if (request.text !== undefined) {
|
|
188
|
+
if (request.text.length > this.config.maxChars) {
|
|
189
|
+
throw new StatcheckError('TOO_LARGE', `text is ${request.text.length} characters, the cap is ${this.config.maxChars}`)
|
|
190
|
+
}
|
|
191
|
+
text = request.text
|
|
192
|
+
source = { kind: 'inline', id: 'inline:text', chars: text.length }
|
|
193
|
+
sourceRef = { kind: 'other', id: 'inline:text', retrievedAt: this.iso() }
|
|
194
|
+
} else {
|
|
195
|
+
const resolved = await this.resolvePath(request.path!)
|
|
196
|
+
const size = (await stat(resolved.absolute)).size
|
|
197
|
+
if (size > this.config.maxChars * 4) {
|
|
198
|
+
throw new StatcheckError('TOO_LARGE', `manuscript is ${size} bytes, the cap is ${this.config.maxChars * 4}`)
|
|
199
|
+
}
|
|
200
|
+
text = await readFile(resolved.absolute, 'utf8')
|
|
201
|
+
if (text.length > this.config.maxChars) {
|
|
202
|
+
throw new StatcheckError('TOO_LARGE', `manuscript is ${text.length} characters, the cap is ${this.config.maxChars}`)
|
|
203
|
+
}
|
|
204
|
+
source = { kind: 'file', id: resolved.id, chars: text.length }
|
|
205
|
+
mediaType = mediaTypeOf(resolved.id)
|
|
206
|
+
sourceRef = { kind: 'file', id: resolved.id, retrievedAt: this.iso() }
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
const { findings, summary } = analyzeText(text, { maxFindings: this.#maxFindings(request.maxFindings) })
|
|
210
|
+
const persist = request.persist ?? this.config.persist
|
|
211
|
+
if (!persist) return { ok: true, summary, findings, source }
|
|
212
|
+
|
|
213
|
+
const port = this.port()
|
|
214
|
+
let evidence: Evidence
|
|
215
|
+
try {
|
|
216
|
+
const captured = await port.capture({ bytes: text, mediaType, sourceRef, capturedAt: this.iso() })
|
|
217
|
+
// The snapshot is immutable, so its capture time is the stable retrieval
|
|
218
|
+
// time: re-checking unchanged text dedupes instead of conflicting. The
|
|
219
|
+
// findings are part of the identity so a different cap/result is a
|
|
220
|
+
// different evidence item rather than an EVIDENCE_CONFLICT.
|
|
221
|
+
const evidenceSourceRef = {
|
|
222
|
+
...sourceRef,
|
|
223
|
+
retrievedAt: captured.snapshot.capturedAt,
|
|
224
|
+
}
|
|
225
|
+
evidence = (
|
|
226
|
+
await port.addEvidence({
|
|
227
|
+
evidenceId: stableId('ev', [
|
|
228
|
+
'statcheck',
|
|
229
|
+
source.kind,
|
|
230
|
+
source.id,
|
|
231
|
+
captured.snapshot.snapshotId,
|
|
232
|
+
summary.total,
|
|
233
|
+
...findings.map(finding => finding.findingId),
|
|
234
|
+
]),
|
|
235
|
+
title: `Statistical report of ${source.id}`,
|
|
236
|
+
sourceRef: evidenceSourceRef,
|
|
237
|
+
snapshotIds: [captured.snapshot.snapshotId],
|
|
238
|
+
anchors: [{ snapshotId: captured.snapshot.snapshotId, kind: 'record', value: 'field:text' }],
|
|
239
|
+
provenance: { plugin: 'dsh-statcheck', version: VERSION, method: 'apa-stat-consistency', retrievedAt: captured.snapshot.capturedAt },
|
|
240
|
+
checks: findings.map(findingToCheck),
|
|
241
|
+
notes: `${summary.total} statistic(s): ${summary.consistent} consistent, ${summary.inconsistent} inconsistent, ${summary.unparsed} unparsed`,
|
|
242
|
+
})
|
|
243
|
+
).evidence
|
|
244
|
+
} catch (error) {
|
|
245
|
+
if (error instanceof RepStoreError) throw new StatcheckError('STORE_ERROR', error.message)
|
|
246
|
+
throw error
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
let recordPath: string | undefined
|
|
250
|
+
try {
|
|
251
|
+
const record = await port.buildRecord({ evidenceIds: [evidence.evidenceId] })
|
|
252
|
+
if (!validateRep(record).ok) throw new StatcheckError('STORE_ERROR', 'refusing to write an invalid REP record')
|
|
253
|
+
const directory = path.join(this.config.root, 'records')
|
|
254
|
+
await mkdir(directory, { recursive: true })
|
|
255
|
+
const file = path.join(directory, `${evidence.evidenceId}.rep.json`)
|
|
256
|
+
await writeFile(file, `${JSON.stringify(record, null, 2)}\n`, 'utf8')
|
|
257
|
+
recordPath = file
|
|
258
|
+
} catch (error) {
|
|
259
|
+
if (error instanceof StatcheckError) throw error
|
|
260
|
+
throw new StatcheckError('STORE_ERROR', `could not write the REP record: ${(error as Error).message}`)
|
|
261
|
+
}
|
|
262
|
+
return { ok: true, summary, findings, source, evidenceId: evidence.evidenceId, ...(recordPath === undefined ? {} : { recordPath }) }
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
/**
|
|
266
|
+
* Recompute one statistic and optionally judge a reported p.
|
|
267
|
+
* @param input - statistic kind, value, df and optional reported p string.
|
|
268
|
+
* @returns the recomputed p and, when a p was given, the judgment.
|
|
269
|
+
*/
|
|
270
|
+
recompute(input: {
|
|
271
|
+
statistic: StatisticKind
|
|
272
|
+
value: number
|
|
273
|
+
df: readonly number[]
|
|
274
|
+
p?: string
|
|
275
|
+
}): { p: number; judgment?: { status: 'consistent' | 'inconsistent'; issue?: string; detail: string } } {
|
|
276
|
+
let p: number
|
|
277
|
+
try {
|
|
278
|
+
p = recomputeP({ statistic: input.statistic, value: input.value, df: input.df })
|
|
279
|
+
} catch (error) {
|
|
280
|
+
if (error instanceof StatInputError) throw new StatcheckError(error.code, error.message)
|
|
281
|
+
throw error
|
|
282
|
+
}
|
|
283
|
+
if (input.p === undefined) return { p }
|
|
284
|
+
const parsed = /^(<|>|=|≤|≥)?\s*(\.\d+|\d+\.?\d*)$/u.exec(input.p.trim())
|
|
285
|
+
if (parsed === null) throw new StatcheckError('INVALID_INPUT', `cannot parse the reported p: ${input.p}`)
|
|
286
|
+
const kind = parsed[1] === '<' || parsed[1] === '≤' ? 'less' : parsed[1] === '>' || parsed[1] === '≥' ? 'greater' : 'equal'
|
|
287
|
+
const judgment = judgeP({ pRaw: parsed[2]!, pKind: kind, recomputed: p })
|
|
288
|
+
return { p, judgment }
|
|
289
|
+
}
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
/** Re-export the math errors for tools. */
|
|
293
|
+
export { StatInputError }
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Tool schema fragments for dsh-statcheck.
|
|
3
|
+
* @module dsh-statcheck/tools/shared
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
/** The failure branch. */
|
|
7
|
+
export const ERROR_SCHEMA = {
|
|
8
|
+
type: 'object',
|
|
9
|
+
additionalProperties: false,
|
|
10
|
+
properties: {
|
|
11
|
+
code: { type: 'string', required: true },
|
|
12
|
+
message: { type: 'string', required: true },
|
|
13
|
+
},
|
|
14
|
+
} as const
|
|
15
|
+
|
|
16
|
+
/** One finding. */
|
|
17
|
+
export const FINDING_SCHEMA = {
|
|
18
|
+
type: 'object',
|
|
19
|
+
additionalProperties: false,
|
|
20
|
+
properties: {
|
|
21
|
+
findingId: { type: 'string', required: true },
|
|
22
|
+
statistic: { type: 'string', required: true },
|
|
23
|
+
text: { type: 'string', required: true },
|
|
24
|
+
charStart: { type: 'integer', required: true },
|
|
25
|
+
charEnd: { type: 'integer', required: true },
|
|
26
|
+
df: { type: 'array', items: { type: 'number' } },
|
|
27
|
+
status: { type: 'string', required: true },
|
|
28
|
+
detail: { type: 'string', required: true },
|
|
29
|
+
severity: { type: 'string', required: true },
|
|
30
|
+
issue: { type: 'string' },
|
|
31
|
+
reported: { type: 'json' },
|
|
32
|
+
recomputed: { type: 'json' },
|
|
33
|
+
},
|
|
34
|
+
} as const
|
|
35
|
+
|
|
36
|
+
/** The summary counters. */
|
|
37
|
+
export const SUMMARY_SCHEMA = {
|
|
38
|
+
type: 'object',
|
|
39
|
+
additionalProperties: false,
|
|
40
|
+
properties: {
|
|
41
|
+
total: { type: 'integer', required: true },
|
|
42
|
+
consistent: { type: 'integer', required: true },
|
|
43
|
+
inconsistent: { type: 'integer', required: true },
|
|
44
|
+
unparsed: { type: 'integer', required: true },
|
|
45
|
+
},
|
|
46
|
+
} as const
|
|
47
|
+
|
|
48
|
+
/** Project one finding into lossless JSON. */
|
|
49
|
+
export function plainFinding(finding: {
|
|
50
|
+
findingId: string
|
|
51
|
+
statistic: string
|
|
52
|
+
text: string
|
|
53
|
+
charStart: number
|
|
54
|
+
charEnd: number
|
|
55
|
+
df: readonly number[]
|
|
56
|
+
status: string
|
|
57
|
+
detail: string
|
|
58
|
+
severity: string
|
|
59
|
+
issue?: string
|
|
60
|
+
reported: Record<string, unknown>
|
|
61
|
+
recomputed: { p: number }
|
|
62
|
+
}) {
|
|
63
|
+
return {
|
|
64
|
+
findingId: finding.findingId,
|
|
65
|
+
statistic: finding.statistic,
|
|
66
|
+
text: finding.text,
|
|
67
|
+
charStart: finding.charStart,
|
|
68
|
+
charEnd: finding.charEnd,
|
|
69
|
+
df: [...finding.df],
|
|
70
|
+
status: finding.status,
|
|
71
|
+
detail: finding.detail,
|
|
72
|
+
severity: finding.severity,
|
|
73
|
+
...(finding.issue === undefined ? {} : { issue: finding.issue }),
|
|
74
|
+
reported: { ...finding.reported, ...(finding.reported['ci'] === undefined ? {} : { ci: [...(finding.reported['ci'] as number[])] }) } as never,
|
|
75
|
+
recomputed: { p: Number.isNaN(finding.recomputed.p) ? null : finding.recomputed.p } as never,
|
|
76
|
+
}
|
|
77
|
+
}
|