std/hints

8 exports, from std/hints.vyrn.

Policy for checking libraries: per-project rule levels and per-line waivers.

A rule is a code, a string this module never interprets; an input file is text with lines. std/vyx-hints uses only this public surface.

import { hint, noPolicy } from "std/hints"
import { Severity } from "std/diag"

export gen fn myHints(path: String) -> String {
    let src = match readFile(path) { Ok(t) => t, Err(e) => "" }
    let mut out = ""
    // ... find something at line 4, column 9 ...
    out = out + hint(noPolicy(), "my/rule", Warning, src, path, 4, 9, "say what is wrong")
    return out
}

A project sets levels with a JSON object under the library's own top-level key, in any JSON file passed to the generator as a constant path:

{ "hints": { "a11y/img-alt": "error", "perf/img-size": "off" } }

policyOf refuses a config that does not parse or names an unknown level: a swallowed fault would report rules on while they are off.

vyrn-ignore <code> on the reported line, or on the line above it, drops that one report. The marker is plain text inside the input's own comment:

<!-- vyrn-ignore a11y/tabindex-positive: the tour sets the order -->
<div tabindex="2">Start here</div>

Dependencies

The import graph shows the whole library.

Imports: diag json jsonread jsondec strpred strings
Imported by: vyx-hints

HintPolicy type

type HintPolicy = { codes: Array<String>, levels: Array<String>, strict: Bool }

Per-code severity overrides, as parallel arrays (a code and its level word). strict ignores waivers; only strictly sets it, for unusedWaivers.

noPolicy fn

fn noPolicy() -> HintPolicy

The empty policy: no override, every rule at its default severity.

strictly fn

fn strictly(p: HintPolicy) -> HintPolicy

p with waivers ignored: what a rule would report. Builds the raw input of unusedWaivers.

policyOf fn

fn policyOf(configText: String, key: String) -> Result<HintPolicy, String>

Reads a policy from the top-level key of configText.

Ok(noPolicy()) when the key is absent. Err when the document does not parse, the key is not an object of strings, or a level is not off, warning or error.

levelOf fn

fn levelOf(p: HintPolicy, code: String, dflt: Severity) -> String

The level code runs at under p: its configured word, or the word for dflt when the project said nothing about it.

hint fn

fn hint(
    p: HintPolicy,
    code: String,
    dflt: Severity,
    src: String,
    file: String,
    line: Int64,
    col: Int64,
    message: String,
) -> String

One //@diag report line, or "" when code is off or waived at line. src is the text of file; the waiver marker is read from it.

waived fn

fn waived(src: String, line: Int64, code: String) -> Bool

Whether code is waived at line of src: a vyrn-ignore <code> marker on that line or on the one above it.

unusedWaivers fn

fn unusedWaivers(p: HintPolicy, src: String, file: String, raw: String) -> String

Reports every vyrn-ignore marker in src that waives nothing. raw is the same report built under strictly; a marker at line L is used when raw reports its code at L or L + 1.

Reports go through hint with p, so hint/unused-waiver is configured and waived like any other rule.

Tests

11 test blocks in std/hints.vyrn. CI runs all of them.

Test names

an absent key is the empty policy, not a fault
a configured level wins over the rule's default
a malformed config is refused, never a silent no-op
an off rule emits nothing
a hint carries its code, its anchor and its severity
a waiver on the line, or the line above, drops that one report
a waiver names its code exactly — prefixes do not leak
line text is 1-based and ends at the newline
a waiver is honoured on its own line and on the line below it
a waiver on line one has no line above to consult
a waiver on a final line with no newline covers the line past the end

Examples

No example program imports this module.