/ase-code-lint

name: ase-code-lint
argument-hint: "[--help|-h] [--auto|-a] [--severity|-S=(AUTO|LOW|MEDIUM|HIGH)] [--force|-f] [--include|-i=<aspect>[,...]] [--exclude|-e=<aspect>[,...]] [--staged] [--unstaged] [<source-reference>]"
description: >
    Lint source code for potential code quality problems.
    Use when the user wants to "lint" or "check" source code.
user-invocable: true
disable-model-invocation: false
effort: high
allowed-tools:
    - "Bash(git rev-parse *)"
    - "Bash(git -C *)"
    - "Bash(find *)"

@${CLAUDE_SKILL_DIR}/../../meta/ase-control.md @${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md @${CLAUDE_SKILL_DIR}/../../meta/ase-dialog.md @${CLAUDE_SKILL_DIR}/../../meta/ase-getopt.md

<purpose name="ase-code-lint"> Lint Source Code </purpose>

<expand name="getopt" arg1="ase-code-lint" arg2="--auto|-a --severity|-S=(AUTO|LOW|MEDIUM|HIGH) --force|-f --include|-i=(none|A01|A02|A03|A04|A05|A06|A07|A08|A09|A10|A11|A12|A13|A14|A15|A16|A17|A18|A19|A20|A21)... --exclude|-e=(none|A01|A02|A03|A04|A05|A06|A07|A08|A09|A10|A11|A12|A13|A14|A15|A16|A17|A18|A19|A20|A21)... --staged --unstaged"> $ARGUMENTS </expand>

<objective> *Analyze* the code of `<getopt-arguments/>` for *potential problems* related to a set of code quality aspects. </objective>

<flow>

1. <step id="STEP 1: Investigation">

<if condition="<ase-project-boxing/> is equal `black` and <getopt-option-force/> is not equal `true`">

The project source artifacts are classified as a *black box*, so the user does *not* want them inspected or their problems surfaced (the `--force` option lifts this skip). *Skip* the entire investigation and reporting: do *not* invoke any `Bash`, `Glob`, or `Agent` tool and do *not* read any source, only output the following <template/> and then *SKIP* the remaining steps STEP 2 and STEP 3:

<template> <ase-tpl-bullet-normal/> **LINT**: *suppressed* (`project.boxing` is `black`) </template>

</if>

Set <condensed>true</condensed> if <ase-project-boxing/> is equal `grey` and <getopt-option-force/> is not equal `true`, and <condensed>false</condensed> otherwise: a *condensed* report suppresses the full unified diffs of STEP 3.

First, determine the *effective aspect set* <aspects/>, i.e., the code quality aspects which are checked at all. For this, parse <getopt-option-include/> and <getopt-option-exclude/> as comma-separated token lists, silently dropping the `none` sentinel and any empty token. If a token <token/> is *not* one of the aspect ids `A01`...`A21`, only output the following <template/> and then *STOP* the entire flow (do not perform any further steps):

<template> ⧉ **ASE**: ✪ skill: **ase-code-lint**, ▶ ERROR: invalid aspect id: **<token/>** </template>

Otherwise set <aspects/> to *all* twenty-one aspect ids `A01`...`A21` if both lists are empty, to the *include* list if only it is non-empty, to all twenty-one *minus* the *exclude* list if only it is non-empty, and to the *include* list *minus* the *exclude* list if both are non-empty. If the resulting <aspects/> is *empty*, only output the following <template/> and then *STOP* the entire flow (do not perform any further steps):

<template> ⧉ **ASE**: ✪ skill: **ase-code-lint**, ▶ ERROR: options `--include` and `--exclude` cancel out to an empty aspect set </template>

Then, use the following <template/> to give a hint on this step:

<template> <ase-tpl-bullet-secondary/> **LINT INVESTIGATION** </template>

Dispatch the investigation to *sub-agents* via the `Agent` tool so that *no* investigation details leak into the user-visible transcript. The sub-agents perform the silent reading and checking; only their final structured return values are consumed here.

<if condition="<getopt-option-staged/> is equal `true` or <getopt-option-unstaged/> is equal `true`">

For this, first *silently* restrict the linting to the *changed* files of the Git working copy. Set <changes>staged and unstaged</changes> if both <getopt-option-staged/> and <getopt-option-unstaged/> are equal `true`, set <changes>staged</changes> if only <getopt-option-staged/> is equal `true`, and set <changes>unstaged</changes> otherwise. Determine the *repository root* by running the command `git rev-parse --show-toplevel` (taken exactly as given) and capturing its output into <repo-root/>. Then determine the changed files by running the corresponding commands (taken exactly as given), each listing one path relative to <repo-root/> per line, and collect all listed paths, dropping duplicates:

<if condition="<getopt-option-staged/> is equal `true`"> `git -C "<repo-root/>" -c core.quotepath=off diff --cached --name-only --diff-filter=d` </if>

<if condition="<getopt-option-unstaged/> is equal `true`"> `git -C "<repo-root/>" -c core.quotepath=off diff --name-only --diff-filter=d`

`git -C "<repo-root/>" -c core.quotepath=off ls-files --others --exclude-standard` </if>

*Skip* every listed path below the `.ase/` directory (it carries *ASE*'s own state) and every path which is not a source code file (e.g. a binary file), and prefix every remaining path with `<repo-root/>/`. If `<getopt-arguments/>` is not empty, keep only those files which lie within the source code referenced by it, expanding any directory or wildcard references with the `Glob` tool (or, if the `Glob` tool is not available, with the `find` command via the `Bash` tool). Set <sources/> to the resulting list of individual source code files, preserving order.

If <sources/> is empty, only output the following <template/> and then *SKIP* the rest of this STEP 1 and the remaining steps STEP 2 and STEP 3:

<template> <ase-tpl-bullet-normal/> **LINT**: *no <changes/> source files to lint* </template>