@stesura/contract-check
Defined terms: where each is defined, what the definition says and where it is used, and what is
wrong with them (the findings). The UI is
@stesura/contract-check-react; setup and behaviour are in the
Contract check guide.
Plugin
contractCheckPlugin
Parameters:| Name | Type | Default |
|---|---|---|
options | ContractCheckPluginOptions |
ContractCheckPluginOptions
ContractCheckPluginState
getContractCheckState
Parameters:| Name | Type | Default |
|---|---|---|
state | EditorState |
findDefinedTerm
A defined term by id, its definition range mapped to the current document. A definition deleted since the last build is not found until the next one, even if an undo brought it back: two transactions share no mirror, so its range has collapsed.
| Name | Type | Default |
|---|---|---|
state | EditorState | |
id | string |
goToDefinition
Selects a term’s definition and reveals it, like goToCheckFinding.
| Name | Type | Default |
|---|---|---|
view | EditorView | |
id | string |
goToDefinitionAtSelection
Goes to the definition of the term at the caret; a host binds it to a key.
| Name | Type | Default |
|---|---|---|
view | EditorView |
termAtSelection
The underlined term the caret sits in: how keyboard users reach the hover card.
| Name | Type | Default |
|---|---|---|
state | EditorState |
setContractCheckVisibleRange
The UI reports what is on screen; underlines outside it are not drawn.
| Name | Type | Default |
|---|---|---|
view | EditorView | |
range | CheckRange |
setContractCheckUnderlines
Parameters:| Name | Type | Default |
|---|---|---|
view | EditorView | |
on | boolean |
setContractCheckSettings
Replaces the settings the plugin was created with (a host endpoint’s answer) and rebuilds.
| Name | Type | Default |
|---|---|---|
view | EditorView | |
settings | CheckSettings |
focusCheckFinding
Outlines one finding’s ranges (or clears the outline): the panel’s hover. With range, it
steps to that range (an index into the finding’s ranges as selectCheckFindings
lists them): only it is outlined while the finding is focused, and the step follows edits.
| Name | Type | Default |
|---|---|---|
id | string | |
range | number |
goToCheckFinding
Selects a finding’s first range and reveals it. React callers that reveal with
editor-react’s revealPos use checkFindingRange instead.
| Name | Type | Default |
|---|---|---|
view | EditorView | |
id | string |
TERM_CLASS
DEFINITION_CLASS
TERM_ID_ATTR
On every underlined span: the defined term’s id.
ISSUE_CLASS
An open error or warning; with -error or -warning. Hints are shown only when focused.
FOCUS_CLASS
The ranges of the finding the panel points at.
Findings
selectCheckFindings
The findings read API: what a panel, a status bar or a joined panel renders.
| Name | Type | Default |
|---|---|---|
state | EditorState |
CheckFindingsView
ReviewedCheckFinding
A finding as the UI shows it: ranges mapped to the current document, with its review state and, once the panel stepped through it, the index of the range it is on.
runContractCheck
The index and the findings from one build: what the plugin, the CLI and the corpus runner use.
| Name | Type | Default |
|---|---|---|
doc | Node | |
options | BuildTermIndexOptions |
collectCheckFindings
What is wrong with the document’s defined terms. Pure: the same document gives the same findings.
| Name | Type | Default |
|---|---|---|
doc | Node | |
options | BuildTermIndexOptions |
CHECK_RULES
DEFAULT_RULES
CHK-5 reports 70 orphan short forms per 100 pages until its list is grown (Phase 0).
Fixes
CHK-30’s fix turns a typed reference into a live cross-reference. Fixes are collected again on the current document and applied in one transaction, so one undo step; while track changes is on they are refused unless forced.
applyCheckFixes
Applies fixes with the settings the plugin checks with, in one undo step, in chunks (a bulk
command: dispatch it through the editor, or runBulkCommand headless). Refuses while track
changes is on (see checkFixesBlockedReason); force applies anyway.
| Name | Type | Default |
|---|---|---|
selection | string[] | "all" | |
options | ApplyCheckFixesOptions |
applyCheckFixesTr
Applies fixes in one transaction, for composing; applyCheckFixesBulk applies them in
chunks. One undo step either way: the findings are collected again on the current document and
filtered by id, never replayed from positions held since. "all" takes every fixable finding
not ignored.
| Name | Type | Default |
|---|---|---|
selection | string[] | "all" | |
options | ApplyCheckFixesOptions |
checkFixesBlockedReason
Why fixing is refused right now: every conversion would be a tracked deletion and insertion.
| Name | Type | Default |
|---|---|---|
state | EditorState |
getCheckFixSummary
The summary an applyCheckFixesTr left on its transaction.
| Name | Type | Default |
|---|---|---|
tr | Transaction |
ApplyCheckFixesOptions
| Name | Type | Default |
|---|---|---|
settings | CheckSettings | ResolvedCheckSettings | |
blockedReason | (state: EditorState) => string | nullA reason not to apply (track changes on, by default); | |
force | boolean |
CheckFixSummary
Review state
setCheckReviewStatus
Marks findings ignored, flagged or open again, for every collaborator. Not an undo step: like a task pane’s state, it is not part of the text’s history.
| Name | Type | Default |
|---|---|---|
ids | string | readonly string[] | |
status | CheckReviewStatus |
clearCheckReview
Every finding open again.
getCheckReview
Review state per finding id; open findings are absent. Shared by collaborators, last write wins.
| Name | Type | Default |
|---|---|---|
state | EditorState |
getCheckReviewStatus
Parameters:| Name | Type | Default |
|---|---|---|
state | EditorState | |
id | string |
CHECK_REVIEW_ATTR
The doc attr holding review state: finding id → ignored or flagged.
Reports
renderCheckReport
The findings as a report: Markdown for a reader or an agent, JSON for a program. Sorted in document order, no timestamps: the same document gives the same bytes.
| Name | Type | Default |
|---|---|---|
findings | readonly ReportFinding[] | |
index | TermIndex | |
options | CheckReportOptions |
CheckReportOptions
| Name | Type | Default |
|---|---|---|
format | "markdown" | "json" | |
review | Readonly<Record<string, CheckReviewStatus>>Review state per finding id; a finding that carries a |
Index
buildTermIndex
The defined terms of a document, where they are defined and where they are used. Pure: the same document gives the same index, in the same order.
| Name | Type | Default |
|---|---|---|
doc | Node | |
options | BuildTermIndexOptions |
BuildTermIndexOptions
| Name | Type | Default |
|---|---|---|
settings | CheckSettings | ResolvedCheckSettings |
normaliseTerm
Case folded with toLowerCase, never a locale-dependent fold.
| Name | Type | Default |
|---|---|---|
s | string |
Settings
resolveCheckSettings
Parameters:| Name | Type | Default |
|---|---|---|
settings | CheckSettings |
parseCheckSettings
Reads settings from untrusted JSON (a host endpoint): unknown keys and values of the wrong type are dropped, never thrown on.
| Name | Type | Default |
|---|---|---|
json | unknown |
DEFAULT_WEIGHTS
Calibrated in Phase 0 on the labelled corpus (docs/partially-executed/contract-check-plan.md, “Phase 0 results”); change them only with the corpus runner’s numbers.
DEFAULT_THRESHOLDS
| Name | Type | Default |
|---|---|---|
recommend | number | |
possible | number |
DEFAULT_PROFILES
| Name | Type | Default |
|---|---|---|
en | LanguageProfile | |
fr | LanguageProfile | |
de | LanguageProfile | |
nl | LanguageProfile | |
it | LanguageProfile | |
es | LanguageProfile |
CHECK_LANGUAGES
Types
CheckFinding
CheckResult
What one check run produces: the index and what is wrong with the document.
| Name | Type | Default |
|---|---|---|
index | TermIndex | |
findings | CheckFinding[] |
CheckRuleId
Rule ids, as in docs/partially-executed/contract-check-plan.md.
CheckCategory
The plan’s rule families: defined terms, definition layout, bilingual, cross-references, final checks.
CheckSeverity
error: the document says something wrong. warning: probably a drafting slip.
hint: a judgement call (lowercase uses are often deliberate).
CheckEvidence
A quote from the document that supports a finding, with the block it sits in.
| Name | Type | Default |
|---|---|---|
text | string | |
blockId | string | null |
CheckReviewStatus
A finding’s review state; open is not stored.
TermIndex
| Name | Type | Default |
|---|---|---|
language | CheckLanguage | |
scopes | CheckScope[] | |
terms | DefinedTerm[] | |
usages | TermUsage[] | |
candidates | DefinitionCandidate[] |
DefinedTerm
TermUsage
| Name | Type | Default |
|---|---|---|
termId | string | |
range | CheckRange |
DefinitionCandidate
A span the detector proposes as a definition.
DefinitionKind
How a definition is laid out; decides where its body is.
DefinitionSignal
One scoring signal of a definition candidate.
ConfidenceBand
recommend: a definition the index trusts; possible: shown as a finding only; silent: ignored.
CheckScope
A region whose definitions belong together. Phase 1 proposes them from language runs.
| Name | Type | Default |
|---|---|---|
id | string | |
language | CheckLanguage | |
blocks | { first: number; last: number; }Block indices, inclusive. | |
translationOf | stringThe document’s other-language version, when it is bilingual. |
CheckRange
A text range in the document.
| Name | Type | Default |
|---|---|---|
from | number | |
to | number |
CheckLanguage
Languages with a profile.
CheckSettings
The organisation’s settings: JSON, from a host endpoint. Patterns stay in the profiles; settings only add to their lists and tune the scoring.
ResolvedCheckSettings
Settings merged onto the built-in profiles: what the engine runs on.
| Name | Type | Default |
|---|---|---|
profiles | Record<CheckLanguage, LanguageProfile> | |
weights | Record<CheckLanguage, SignalWeights> | |
thresholds | { recommend: number; possible: number; } | |
rules | Record<CheckRuleId, boolean> |
LanguageProfile
Everything language-specific. A seventh language is a new profile, not a refactor.
Patterns are code; the organisation’s additions (common terms, short forms, weights)
come through CheckSettings.