Enum IssueCode 

#[non_exhaustive]
pub enum IssueCode {
    UndefinedCommand,
    MissingRequiredArg,
    UnknownFlag,
    InvalidArgType,
    SeqZeroIncrement,
    InvalidRegex,
    BreakOutsideLoop,
    ReturnOutsideFunction,
    PossiblyUndefinedVariable,
    ForLoopScalarVar,
    ScatterWithoutGather,
    LastResultFieldAccess,
    DiffNeedsTwoFiles,
    InvalidSedExpr,
    InvalidJqFilter,
    LvalueUndefinedRoot,
    DottedAssignmentTarget,
    UnreadableAssignmentTarget,
    InvisibleAssignmentTarget,
    MixedScriptName,
    TestCompoundOperator,
}

Categorizes validation issues for filtering and tooling.

#[non_exhaustive]: docs/EMBEDDING.md tells embedders to route on this code rather than on message text, and this list grows every cycle. An exhaustive match here would break on each new check, which is the same shape as all five of 0.15.0’s undeclared breaking changes. Add a wildcard arm that fails loudly, never a silent default.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

UndefinedCommand

Command not found in registry or user tools.

MissingRequiredArg

Required parameter not provided.

UnknownFlag

Flag not defined in tool schema.

InvalidArgType

Argument type doesn’t match schema.

SeqZeroIncrement

seq increment is zero (infinite loop).

InvalidRegex

Regex pattern is invalid.

BreakOutsideLoop

break/continue outside of a loop.

ReturnOutsideFunction

return outside of a function.

PossiblyUndefinedVariable

Variable may be undefined.

ForLoopScalarVar

Bare scalar variable in for loop (no word splitting in kaish).

ScatterWithoutGather

scatter without gather — parallel results would be lost.

LastResultFieldAccess

Field access on $? (e.g. ${?.data}, ${?.ok}) was removed. $? is the POSIX exit code; use kaish-last for structured data.

DiffNeedsTwoFiles

diff was given other than two file operands.

InvalidSedExpr

sed expression is syntactically invalid.

InvalidJqFilter

jq filter expression is syntactically invalid.

LvalueUndefinedRoot

A subscripted assignment lvalue (x[k]=v) targets an undefined root variable. Unlike a plain read, a path-set never autovivifies the root — it must already exist as a collection.

DottedAssignmentTarget

An assignment target contains a dot (user.email=x). kaish is brackets-only for collection access — the Ident token admits . for other uses (filenames, source foo.kai), so this is caught here rather than by tightening the lexer regex.

UnreadableAssignmentTarget

An assignment target contains # (abc#3=5). The Ident token admits # so words, ids, and URLs keep it, but $abc#3 is itself an error, so such a variable could be created and never read back. Caught here rather than by tightening the lexer regex, for the same reason DottedAssignmentTarget is.

InvisibleAssignmentTarget

An assignment target holds a character that does not show itself — whitespace, a zero-width character, or a bidi control. Most spellings are caught earlier, on the token stream; this covers the ones only the syntax tree can tell apart from data, such as the second assignment in an env-scoped prefix (x=1 BAD=2 cmd), where a target and an argv key=value word look identical one token back.

MixedScriptName

A name is spelled in two scripts, so it reads as a name it does not bind — PАTH with CYRILLIC CAPITAL LETTER A (U+0410) binds a second variable and leaves $PATH alone. UAX #39’s Highly Restrictive profile is the rule, so café, 名前, and 変数x stay quiet. A warning, never an error: the name binds either way, and the author is the only one who knows which name they meant.

TestCompoundOperator

test was given an XSI compound/grouping operator (-a, -o, (, )), which kaish does not implement.

Implementations

impl IssueCode

pub fn code(&self) -> &'static str

Returns a short code string for the issue.

Code numbers are stable identifiers, not contiguous. E010 and W003/W004/W005 remain retired, as does W006 (PosixTestCommand, retired when test became a first-class builtin) — W007 is the next free warning number, not a reuse of one of them. E020 covers the same builtin as retired W006 but is a different judgement: W006 warned that [ was not kaish’s, E020 rejects an operator test will refuse at runtime anyway. E006 (InvalidSedExpr), E007 (InvalidJqFilter), and E011 (DiffNeedsTwoFiles) were wired up with real emitters in 2026-06-14.

pub fn surfaces_to_agent(&self) -> bool

Whether a warning carrying this code should be surfaced to the agent (appended to the result’s stderr) rather than only trace-logged.

Most warnings stay trace-only — UndefinedCommand fires on every external command (grep, cargo), so surfacing them all would be noise. Opt a code in here only when its guidance is worth interrupting for; this is the boundary between the two.

MixedScriptName is opted in. It reports a name whose spelling and binding disagree, which nothing else reports — the exit code is 0 and the output looks right — so a trace-only warning would report it to nobody. Add a code to the matches! arm when the same is true of it.

pub fn default_severity(&self) -> Severity

Default severity for this issue code.

Trait Implementations

impl Clone for IssueCode

fn clone(&self) -> IssueCode

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for IssueCode

impl Debug for IssueCode

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for IssueCode

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for IssueCode

impl PartialEq for IssueCode

fn eq(&self, other: &IssueCode) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for IssueCode