dsh-statcheck 0.0.0-stage → 0.1.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.
Files changed (61) hide show
  1. package/CHANGELOG.md +49 -0
  2. package/LICENSE +201 -0
  3. package/README-zh.md +117 -0
  4. package/README.md +116 -2
  5. package/cordis.patch.yml +18 -0
  6. package/lib/check.d.ts +92 -0
  7. package/lib/check.d.ts.map +1 -0
  8. package/lib/check.js +250 -0
  9. package/lib/check.js.map +1 -0
  10. package/lib/config.d.ts +37 -0
  11. package/lib/config.d.ts.map +1 -0
  12. package/lib/config.js +44 -0
  13. package/lib/config.js.map +1 -0
  14. package/lib/index.d.ts +36 -0
  15. package/lib/index.d.ts.map +1 -0
  16. package/lib/index.js +50 -0
  17. package/lib/index.js.map +1 -0
  18. package/lib/math.d.ts +76 -0
  19. package/lib/math.d.ts.map +1 -0
  20. package/lib/math.js +218 -0
  21. package/lib/math.js.map +1 -0
  22. package/lib/report.d.ts +41 -0
  23. package/lib/report.d.ts.map +1 -0
  24. package/lib/report.js +91 -0
  25. package/lib/report.js.map +1 -0
  26. package/lib/runtime.d.ts +104 -0
  27. package/lib/runtime.d.ts.map +1 -0
  28. package/lib/runtime.js +235 -0
  29. package/lib/runtime.js.map +1 -0
  30. package/lib/tools/shared.d.ts +127 -0
  31. package/lib/tools/shared.d.ts.map +1 -0
  32. package/lib/tools/shared.js +61 -0
  33. package/lib/tools/shared.js.map +1 -0
  34. package/lib/tools/stat-check.d.ts +12 -0
  35. package/lib/tools/stat-check.d.ts.map +1 -0
  36. package/lib/tools/stat-check.js +83 -0
  37. package/lib/tools/stat-check.js.map +1 -0
  38. package/lib/tools/stat-recompute.d.ts +12 -0
  39. package/lib/tools/stat-recompute.d.ts.map +1 -0
  40. package/lib/tools/stat-recompute.js +82 -0
  41. package/lib/tools/stat-recompute.js.map +1 -0
  42. package/lib/tools/stat-report.d.ts +10 -0
  43. package/lib/tools/stat-report.d.ts.map +1 -0
  44. package/lib/tools/stat-report.js +66 -0
  45. package/lib/tools/stat-report.js.map +1 -0
  46. package/lib/version.d.ts +7 -0
  47. package/lib/version.d.ts.map +1 -0
  48. package/lib/version.js +7 -0
  49. package/lib/version.js.map +1 -0
  50. package/package.json +82 -4
  51. package/src/check.ts +308 -0
  52. package/src/config.ts +71 -0
  53. package/src/index.ts +75 -0
  54. package/src/math.ts +205 -0
  55. package/src/report.ts +113 -0
  56. package/src/runtime.ts +293 -0
  57. package/src/tools/shared.ts +77 -0
  58. package/src/tools/stat-check.ts +83 -0
  59. package/src/tools/stat-recompute.ts +82 -0
  60. package/src/tools/stat-report.ts +68 -0
  61. 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
+ }