Add structkit lint command and MCP tool (#146)

Author: httpdss

docs/cli-reference.md

@@ -80,6 +80,38 @@ structkit validate [-h] [-l LOG] [-c CONFIG_FILE] [-i LOG_FILE] yaml_file
 
 - `yaml_file`: Path to the YAML configuration file.
 
+### `lint`
+
+Run stricter quality checks against one or more StructKit YAML files or structure names. `validate` checks whether a structure is syntactically usable; `lint` adds quality and safety checks that can flag risky, ambiguous, or inconsistent definitions.
+
+**Usage:**
+
+```sh
+structkit lint [-h] [-l LOG] [-c CONFIG_FILE] [-i LOG_FILE] [-s STRUCTURES_PATH] [--all] [--json] [targets ...]
+```
+
+**Arguments:**
+
+- `targets`: One or more built-in structure names, custom structure names, or local `.yaml`/`.yml` files.
+- `-s STRUCTURES_PATH, --structures-path STRUCTURES_PATH`: Path to custom structure definitions. Can be set via the `STRUCTKIT_STRUCTURES_PATH` environment variable.
+- `--all`: Lint all bundled contrib structures.
+- `--json`: Print machine-readable JSON containing `summary` counts and individual `issues`.
+
+**Rules and exit behavior:**
+
+- Errors: invalid YAML, missing targets, missing files, non-mapping top-level YAML, invalid variable/hook shapes, duplicate variables, duplicate file/folder entries, template syntax errors, undefined template variables, and clearly destructive hooks such as filesystem-root removal.
+- Warnings: missing top-level descriptions, declared variables that are never referenced, suspicious hooks, unpinned GitHub remote URLs, and variable naming convention issues.
+- The command exits with status `1` when one or more lint errors are found. Warnings alone do not cause a non-zero exit.
+
+Examples:
+
+```sh
+structkit lint .struct.yaml
+structkit lint structkit/contribs/project/python.yaml
+structkit lint --all
+structkit lint .struct.yaml --json
+```
+
 ### `generate`
 
 Generate the project structure.

docs/mcp-integration.md

@@ -103,6 +103,27 @@ Validate a structure configuration YAML file.
 **Parameters:**
 - `yaml_file` (required): Path to the YAML configuration file to validate
 
+### 6. lint_structure
+Lint one or more structure YAML files or structure names for quality and safety issues.
+
+```json
+{
+  "name": "lint_structure",
+  "arguments": {
+    "targets": ["project/python", "/path/to/.struct.yaml"],
+    "structures_path": "/path/to/custom/structures",
+    "lint_all": false,
+    "output": "json"
+  }
+}
+```
+
+**Parameters:**
+- `targets` (optional): YAML file paths or structure names to lint. Required unless `lint_all` is true.
+- `structures_path` (optional): Custom path to structure definitions.
+- `lint_all` (optional): Lint all bundled contrib structures (default: false).
+- `output` (optional): Output format - "text" or "json" (default: "text").
+
 ## Usage
 
 ### Starting the MCP Server (FastMCP stdio / http / sse)
@@ -246,6 +267,7 @@ The MCP tools can be chained together for complex workflows:
 2. Get detailed info about a specific structure
 3. Generate the structure with custom mappings
 4. Validate any custom configurations
+5. Lint structures for stricter quality and safety checks
 
 ### Integration Examples
 
@@ -374,6 +396,7 @@ Once connected, you can use these tools:
 - `generate_structure` - Generate project structures
 - `get_structure_vars` - Inspect declared structure variables
 - `validate_structure` - Validate YAML configuration files
+- `lint_structure` - Lint YAML files or structure names for quality and safety issues
 
 ## Troubleshooting