lint-components

name	lint-components
description	Validates Garura components (plays, agents, skills) against structural, semantic, and cross-reference rules. Reads quality profile to classify violation severities.
user-invocable	false
model	sonnet
allowed-tools	Bash, Read
deprecated	true
deprecated_note	#434 ProductOS realignment — superseded by the command model; retained for Phase E reference, not installed

Purpose

Run the deterministic Node.js component linter against core/components/ and produce a structured lint report artifact. Reads the project quality profile to classify ERROR violations as blockers and WARNING violations as informational per the profile's maintainability and security targets.

Input

STM input contract:

Field	Type	Required	Description
project_root	string	Yes	Absolute path to the repository root
output_path	string	Yes	STM path where the lint report artifact will be written

Example:

stm:
  input:
    project_root: /path/to/repo
  output:
    lint_report: .garura/project/issues/{issue}/evidence/{play}/lint-report.yaml

Process

1. Check node_modules. From {project_root}, check whether core/tools/lint-components/node_modules/ exists. If not, run:

   npm install --silent
   

   in core/tools/lint-components/. This installs the js-yaml dependency required by the linter.

2. Run the linter. Execute:

   node core/tools/lint-components/index.js --target core/components --output json
   

   Capture stdout as the raw JSON output. The tool exits 0 if no errors; exits 1 if any errors are found (errors > 0). Both exit codes are expected — do NOT treat exit code 1 as a fatal failure.

3. Parse JSON output. Parse the captured stdout as JSON. Shape:

   {
     "violations": [
       { "file": "...", "rule": "...", "severity": "error|warning|info", "message": "...", "line": 0 }
     ],
     "summary": { "errors": 0, "warnings": 0, "infos"  
   
   

Output

Lint report artifact written to {output_path}:

Field	Description
generated_at	ISO timestamp of when the lint was run
quality_profile_status	Status field from quality profile, or not_found
summary.errors	Count of error-severity violations
summary.warnings	Count of warning-severity violations
summary.infos	Count of info-severity violations
summary.blockers	Count of blocker-classified violations (= errors)
summary.informational	Count of informational violations (= warnings + infos)
pass	true if no errors found; false otherwise
violations	Array of all violations with classification

Return value: The output artifact path.

Constraints

• Must not modify any components under core/components/ — read-only analysis only.
• Template validation (--validate-templates) is off by default. Do not pass this flag unless explicitly instructed.
• Quality profile path must be resolvable: .garura/product/specification/quality-profile.yaml. If absent, fall back to default classification and log quality_profile_status: not_found.
• Do not fail the skill if the linter exits with code 1 — that is the expected exit code when violations are found. Only fail on exit code 2 (fatal/unexpected error).
• Run from {project_root} so relative paths in the linter resolve correctly.