Index Lint

API reference for @use-crux/core/lint rule metadata, findings, profiles, and suppressions.

import type { IndexLintFinding, CruxLintConfig } from "@use-crux/core/lint";

Index lint is the authored-graph lint contract used by crux dev, crux lint, the web devtools, and the TUI. Lint findings describe actionable issues in source-authored Crux definitions. They are separate from index diagnostics, which describe indexer health.

`CruxLintConfig`

interface CruxLintConfig {
  profile?: "off" | "recommended" | "strict" | "experimental";
  rules?: Record<
    string,
    {
      enabled?: boolean;
      severity?: "info" | "warning" | "error";
    }
  >;
}

Profiles

Profile	Description
`recommended`	Default rules with high signal and low noise.
`strict`	Adds stronger product-health checks.
`experimental`	Includes rules still being proven.
`off`	Disables index lint findings for the project.

Rule maturity

Stable-beta rules are the default quality-gate set. They have rule-specific fixtures, native parity evidence where the native syntax path can emit them, and public reference pages:

prompt.missing_input_schema
prompt.hidden_required_input
context.missing_input_schema
injection.dynamic_dependency
injection.dynamic_tools
tool.missing_input_schema
flow.duplicate_step_label
flow.duplicate_suspend_name
flow.undeclared_suspend_signal
routing.missing_stable_id
routing.router_missing_default
routing.cascade_unreachable_tier
rag.recipe_step_unresolved_target
runtime.duplicate_target_name
runtime.non_literal_target_name
runtime.target_not_exported
runtime.closure_defer
runtime.non_serializable_payload

Preview rules remain available through their configured profiles (including recommended and strict), but their policy wording, suppression guidance, or backend evidence may still change before the stable rule set adopts them. Treat preview findings as advisory until the rule is promoted.

Bundled lints assert only properties decidable from authored source. Config- and environment-dependent checks belong to crux setup. For deferred work, the bundled rules cover replay safety (defer.replay_unsafe) and consumed named commit promises (defer.floating_named_promise); host-retention checks come from crux setup --check.

Media rules

Media rules are deterministic authored-source checks. They cover discarded specialized results, provably unsupported adapter/operation pairs, unsafe retained options (options that could expose raw payloads, locators, or provider identifiers), invalid image edit combinations, impossible transcription timing/diarization requests, speech configuration conflicts, and media sources without a derivation operation. They never inspect media bodies and never turn the private adapter truth table into a runtime API.

`IndexLintFinding`

interface IndexLintFinding {
  id: string;
  severity: "info" | "warning" | "error";
  ruleId: string;
  category: CruxLintCategory;
  maturity: "stable" | "preview" | "experimental";
  confidence: "high" | "medium" | "low";
  profiles: Array<"recommended" | "strict" | "experimental">;
  title: string;
  message: string;
  rationale: string;
  impact?: string;
  source?: SourceLocation;
  primaryDefinitionId?: string;
  relatedDefinitionIds: string[];
  affectedDefinitionIds?: string[];
  evidence: IndexLintEvidence[];
  fixes: IndexLintFix[];
  docsUrl: string;
  suppression?: IndexLintSuppression;
  propagatedDefinitionIds?: string[];
  propagationPaths?: IndexLintPropagationPath[];
}

Field	Description
`message`	Concrete "what happened" text.
`rationale`	Per-rule "why it matters" text.
`impact`	Optional user/system consequence.
`evidence`	Backend-owned evidence explaining why the finding exists.
`fixes`	Actionable fix paths, docs links, or suppression affordances.
`docsUrl`	Rule reference page.
`suppression`	Exact suppression comment the UI can show.

Clients should render findings directly. Do not recompute rules client-side by walking index relations.

Injection-aware lint rules use the Project Index injection read model. They can point at prompt input fields contributed by contexts or injectables, explain conditional branches, and mark runtime-dependent dependencies or tool surfaces when static source cannot fully describe the composition.

Suppressions

Rule-specific source suppressions use comments:

// crux-lint-disable-next-line tool.missing_input_schema -- generated adapter
// crux-lint-disable-line definition.missing_eval_coverage -- covered externally
/* crux-lint-disable-file definition.missing_eval_coverage -- prototype */

Unknown rule ids and unused suppressions are index diagnostics.

Rule References

Rule-specific API/reference pages live under Index Lints.

Guide: Index Lint
Reference: Project Index
Reference: @use-crux/local

Index Lint

On this page