Skip to content

Add structkit lint command for structure quality checks #137

@httpdss

Description

@httpdss

Summary

Add a structkit lint command that performs stricter quality checks on StructKit YAML files than the existing validate command.

Motivation

validate checks whether a structure is syntactically usable. A separate lint command can help maintain higher-quality built-in and custom structures by catching risky, ambiguous, or inconsistent definitions before they are used.

Proposed behavior

  • Accept one or more YAML files or structure names.
  • Support linting all bundled contrib structures.
  • Report warnings and errors with file paths and useful context.
  • Support a machine-readable output format, e.g. --json.
  • Exit non-zero when lint errors are found.

Initial lint checks

  • Missing top-level description.
  • Variables referenced in templates but not declared.
  • Declared variables that are never referenced.
  • Duplicate file or folder entries.
  • Unsafe or suspicious hooks.
  • Remote URLs that are not pinned to stable refs where applicable.
  • Invalid or inconsistent naming conventions.

Example usage

  • structkit lint .struct.yaml
  • structkit lint structkit/contribs/project/python.yaml
  • structkit lint --all
  • structkit lint .struct.yaml --json

Acceptance criteria

  • Command is registered in the CLI.
  • Lint rules are tested individually.
  • Supports warning vs error severity.
  • Documentation describes lint rules and exit-code behavior.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions