/ase-code-lint

name: ase-code-lint
argument-hint: "[--help|-h] [--auto|-a] [--severity|-S=(LOW|MEDIUM|HIGH)] [--include|-i=<aspect>[,...]] [--exclude|-e=<aspect>[,...]] <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

@${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=(LOW|MEDIUM|HIGH) --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)..."> $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`">

The project source artifacts are classified as a *black box*, so the user does *not* want them inspected or their problems surfaced. *Skip* the entire investigation and reporting: do *not* invoke any `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>

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.

For this, first *silently* resolve `<getopt-arguments/>` to the list <sources/> of individual source code files, expanding any directory or wildcard references with the `Glob` tool. Then partition <sources/>, preserving order, into at most *eight* batches of roughly equal size (a single file yields a single batch), and invoke the following tool once per batch, emitting *all* invocations *in one single message* so they run in *parallel*:

        Agent(
            description:       "Lint Investigation (<batch-index/>/<batch-count/>)",
            subagent_type:     "ase:ase-code-lint",
            prompt:            "<aspects/> <batch/>",
            run_in_background: false
        )

Here <aspects/> is the comma-separated list of the effective aspect ids (without any spaces), <batch/> is the space-separated list of the source code file paths of the corresponding batch, <batch-index/> is the 1-based index of that batch, and <batch-count/> is the total number of batches, so that each parallel invocation is distinguishable in the progress display.

Parse the result message of each `Agent` tool invocation as a JSON array and concatenate all those arrays. Then *deduplicate* the combined list: when two problems share the same `file`, `line`, and `aspect`, *silently drop* all but the first one (sub-agents may have read overlapping *related* files for comprehension). Finally sort the list by `file` and then numerically by `line`, and set <problems/> to that list.

Then determine the *effective severity floor* <floor/>: define the ordinal rank `LOW`=1, `MEDIUM`=2, `HIGH`=3, start from <floor><getopt-option-severity/></floor> (default `LOW`), and - if <ase-project-boxing/> is equal `grey` - raise <floor/> to `MEDIUM` whenever its current rank is below `rank(MEDIUM)` (grey boxing surfaces only *material* findings of severity `MEDIUM` and above).

Then *apply the effective severity floor* <floor/>: *Keep* a problem in <problems/> if and only if its `severity` field is `ACCEPTED` *or* `rank(severity)` is greater than or equal to `rank(<floor/>)`; *silently drop* all other problems. With the default floor `LOW`, all problems are kept. `ACCEPTED` problems are *never* dropped.

Finally, sort the surviving problems in <problems/> by their `severity` field from highest to lowest in the fixed order `HIGH`, `MEDIUM`, `LOW`, `ACCEPTED`, so the subsequent reporting starts with the most severe problem. Within the same severity, keep the `file`/`line` order est