[feature] Full Luacheck integration

[paudley]

Summary

Add full coding-ethos integration for luacheck from the pyqa_lint catalog.

Parent tracker: #77

pyqa_lint source: ~/Active/pyqa_lint/tooling/catalog/languages/lua/luacheck.json

Scope

This issue covers one tool only. Integration is complete only when coding-ethos owns acquisition, execution, diagnostics, Lua language facts, CEL/SARIF output, policy alignment, MCP/agent visibility, docs, and tests.

Required Integration Surface

1. Tool Acquisition

• Add deterministic managed acquisition for luacheck.
• Pin the version and checksum where a release artifact is downloaded.
• Record provenance in the managed toolchain manifest.
• Validate the acquired executable during bootstrap and fail fast with a structured diagnostic if validation fails.
• Do not rely on an arbitrary host-installed luacheck from PATH.

2. Command Orchestration

• Build command construction in Go through the hook runner or managed capture path.
• Select staged/changed targets when safe; if luacheck requires project-level execution, document the reason and isolate the scope.
• Pass config paths explicitly and log the selected source of truth.
• Respect sandboxing, timeout, filesystem, and network policy.
• Avoid shell glue and Go-to-shell-to-Go execution paths.

3. Diagnostics Parsing

• Parse native luacheck output into normalized diagnostics with tool, file, line, column, severity, rule/code, and message.
• Convert unparseable output into structured tool-failure diagnostics.
• Preserve raw output in traces without flooding TOON or MCP summaries.
• Add parser fixtures for success, warning/error severity mapping, empty output, and malformed output.

4. Language AST Facts

• Confirm Tree-sitter/AST fact support for Lua files is sufficient for policy context and SARIF locations.
• Extend shared AST fact collection first if policy context is missing.
• Do not add ad hoc text scanners or policy-specific AST walkers before checking the AST/CEL/SARIF architecture path.
• Add fixtures proving representative Lua files can be indexed, or explicitly document why AST facts are not applicable for this tool.

5. CEL and Policy Alignment

• Expose luacheck findings through the existing CEL diagnostic inputs by tool, rule/code, file, severity, and path metadata.
• Add policy mappings only where coding-ethos has a clear repo-trust, maintainability, security, or safety opinion.
• Align actionable findings with relevant ethos principles and remediation skills.
• Keep advisory versus blocking behavior explicit and configurable.

6. SARIF Integration

• Emit SARIF with stable ruleId, source tool metadata, severity, and location data.
• Include related locations, fixes, or help text when luacheck exposes them.
• Add SARIF shape tests for at least one real diagnostic.
• Preserve stable identities so CI, PR review, and IDE surfaces can correlate findings over time.

7. MCP and Agent Surface

• Ensure lint_check, lint_advice, SARIF remediation, risk summary, trend analysis, and hook traces identify luacheck correctly.
• Add capability metadata for file reads, file writes, tool execution, network use, autofix support, and advisory/blocking role.
• Make failure modes actionable for agents and human contributors.

8. Docs and Config

• Document managed acquisition, config source of truth, generated config behavior, and common remediation guidance.
• Update README/tooling docs and examples for the Lua path.
• If coding-ethos generates config for luacheck, add drift checks and hash manifest entries.

Acceptance Criteria

• luacheck is acquired through the managed toolchain with version/checksum/provenance recorded where applicable.
• The hook runner or managed capture path invokes luacheck without shell glue or implicit host config discovery.
• Native diagnostics are parsed into normalized diagnostics and SARIF.
• AST/language fact support for Lua is present or explicitly documented as not applicable.
• CEL policy inputs can reason over luacheck findings by tool/code/file/severity.
• MCP lint and SARIF advice surfaces include luacheck output cleanly.
• Documentation explains config ownership and expected operator workflow.
• Unit tests cover acquisition, command construction, parser success, parser failure, and SARIF shape.
• A functional workflow test exercises luacheck on a representative fixture.
• make build, make pre-commit, and relevant Go package tests pass.

[paudley]

Stage 1 plan for #84.

Issue summary:

• Add full coding-ethos integration for luacheck from the pyqa_lint Lua catalog.
• The catalog command shape is luacheck --formatter plain --codes --ranges --no-color, with .lua file selection and optional .luacheckrc config.

Workspace:

• Worktree: .worktrees/paudley-84-full-luacheck-integration
• Branch: paudley/84-full-luacheck-integration from current origin/main (8dc4fab).

Implementation tasks:

1. Managed acquisition

   • Add a luarocks managed installer path. The host has lua5.4 and Lua headers but no host luarocks, so the installer will download a pinned standalone LuaRocks Linux x86_64 zip, verify SHA-256, and use it only inside a temporary managed-install workspace.
   • Add checked-in LuaRocks lock metadata for exact source-rock URLs and SHA-256 values: argparse 0.7.2-1, luafilesystem 1.9.0-1, and luacheck 1.2.0-1.
   • Install those rocks into a checkout-local managed tree with dependency resolution disabled for the locked installs, then expose the generated luacheck wrapper under build/toolchain/github-bin/luacheck.

2. Command orchestration and capture

   • Add luacheck catalog metadata with Lua language/file matching, native plain output, managed binary path, --formatter plain --codes --ranges --no-color, .luacheckrc config metadata, and pass-files behavior.
   • Register policy-luacheck and a lua hook group.

3. Diagnostics and SARIF

   • Add a parser for native plain output like path:line:col-end: (W113) message, including ranges, warning severity, rule code, empty output, malformed-output behavior through managed capture, and parser registration fixtures.
   • Add SARIF shape coverage through the existing normalized diagnostic renderer.

4. Lua facts, MCP/CEL visibility, docs, and tests

   • Add Lua Tree-sitter fact support if it is not already present on main, following the shared AST/CEL/SARIF path rather than a text scanner.
   • Keep CEL/MCP behavior on the existing normalized diagnostic inputs unless a Luacheck-specific policy mapping is clearly justified.
   • Update README and pre-commit docs for managed acquisition, .luacheckrc ownership, Lua 5.4/runtime expectations, and operator workflow.
   • Add focused tests for installer locking, catalog metadata, hook filtering, managed capture args, parser output, Lua facts, and SARIF shape.

Validation gates:

• Focused Go tests for diagnostics, toolcatalog, hookrunnercli, managedcapture, toolchaincli, astfacts, and hookoutput as touched.
• make build because managed toolchain/runtime behavior changes.
• Managed luacheck smoke test on a representative Lua fixture.
• make check as the canonical gate.
• git diff --check.

Commit/push/PR:

• Commit through bin/coding-ethos-run policy-git only.
• If protected admin files block the commit, I will leave the staged work intact and post an admin handoff with validation evidence instead of bypassing the gate.

[paudley]

Stage 1 implementation is complete locally on paudley/84-full-luacheck-integration, but the policy-managed commit is blocked by git.staged_admin_files because this change updates protected pre-commit hook assets.

Implemented:

• Added managed Luacheck catalog/runtime/hook-group integration, including policy-luacheck and the lua hook group.
• Added locked LuaRocks installation support for Luacheck 1.2.0-1 using a checked-in lock file.
• Added Luacheck managed-capture argument enforcement, diagnostics parsing, SARIF formatting coverage, and Lua AST/code-intel support.
• Updated README, hook runtime bootstrap docs, and pre-commit runtime docs.

Validation:

• Managed Luacheck smoke test reported normalized W113 and W211 diagnostics from a throwaway Lua fixture.
• make check passed, with the existing non-blocking testing.go_coverage_goal warning.
• bin/coding-ethos-run policy-git diff --check passed.
• make build completed earlier in this worktree and installed the managed Luacheck binary.

Policy block:

status: blocked
policy_id: git.staged_admin_files
message: Administrative staged files require explicit handling.
suggestion: Administrative staged files require a human/admin commit. Administrative staged files: pre-commit/PRE-COMMIT.md, pre-commit/hooks/luarocks-locks/luacheck-1.2.0-1/rocks.tsv, pre-commit/hooks/managed-toolchain.tsv. Agent action: stop trying to commit these files. Human/admin handoff: from /home/paudley/Active/gmeow/coding-ethos/.worktrees/paudley-84-full-luacheck-integration, run: git commit -m 'feat(toolchain): add managed Luacheck integration'.
files[3]{path}:
  pre-commit/PRE-COMMIT.md
  pre-commit/hooks/luarocks-locks/luacheck-1.2.0-1/rocks.tsv
  pre-commit/hooks/managed-toolchain.tsv

Admin handoff:

cd /home/paudley/Active/gmeow/coding-ethos/.worktrees/paudley-84-full-luacheck-integration
git commit -m 'feat(toolchain): add managed Luacheck integration'