Repository navigation
Add the doc-style-check command and extend comments mode - #6
Merged
Merged
Conversation
The primer named the checker as ~/.claude/skills/doc-style/scripts/check.
That path exists only after the install by hand. The plugin install
places the skill under the plugin cache.
commands/doc-style-check.md runs the checker on every Markdown file in
the change set. ${CLAUDE_PLUGIN_ROOT} locates the checker, so the
command works wherever the plugin is installed. The primer tells Claude
to run /haddock:doc-style-check before a pull request, and names the
checker by its skill directory during a task. The README gives the
manual equivalent for the install by hand.
The command uses git diff --merge-base in place of a $(git merge-base)
substitution, because the permission check for an injected command
rejects command substitution. The checker exits 1 on findings, so the
command ends with || true, as the skills documentation requires.
A test fails when a snippet names a path under ~/.claude/.
In comments mode, a # or // after code on the same line now starts a comment when two conditions hold: whitespace precedes the marker, and the " and ' characters before it on the line are both even in number. A marker inside a string literal is then not a comment start. A line that starts with a marker is a comment, as before. The fixtures that held an unchecked trailing comment now hold a clean one, and comments.py reports its trailing comment. New fixtures cover a trailing # with a qualifier and a trailing // with an idiom. A pass fixture covers a # inside a string, a // inside a URL string, and a # without whitespace before it. Three mutants cover the new rule, the quote count, and the whitespace condition.
A # line whose text starts with a C preprocessor directive name is a directive, not a comment. The checker does not check it. The names are include, define, undef, if, ifdef, ifndef, elif, else, endif, pragma, error, warning, and line. The match is case-sensitive, so a comment that starts with Error or Warning is still checked. preprocessor.c holds a define and an include. comments.c confirms that a // comment and a /* */ comment in a C file are still checked. A mutant covers the skip.
In comments mode, a block between <!-- and -->, between ''' and ''', or between --[[ and ]] is a comment. The existing block mechanism reads the new forms. A --[[ at the start of a line opens a block, and does not start a line comment. A --- before [[ is still a line comment, as in Lua. The checker reads its own source as source code. The <!-- literals in the directive regex and in the Markdown-mode awk now hold a split opener, so that the self-check does not read the script as one block. Fail fixtures cover an HTML comment block, a Lua long comment at the start of a line, and a single-quoted docstring. A mutant covers each form.
A line that starts with a double hyphen in a shell script, such as a wrapped command's --flag, is read as a comment. The behavior is unchanged. continuation.sh holds a wrapped command whose continuation lines start with a double hyphen and hold no excluded word. A later change to that comment form is then visible in the tests. A comment in the Source files section of SKILL.md names the limitation.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
commands/doc-style-check.mdruns the checker on every Markdown file in the changeset.
/haddock:doc-style-checkis available with the plugin install. The primer nolonger names a path under
~/.claude/, and the README gives the manual equivalent.#or//comment after code is checked when two conditionshold: whitespace precedes the marker, and the
"and'characters before it on theline are both even in number.
#line whose text starts with a C preprocessor directive name isnot a comment.
<!--and-->, between'''and''', orbetween
--[[and]]is a comment. A--[[at the start of a line takes precedenceover the
--line comment.tests/pass/continuation.shdocuments that a shell continuation line that starts with--is read as a comment. The behavior is unchanged.Behavior changes
checker on source files MAY see new findings.
#comment whose text starts with a lowercaseif,else,line,error, orwarningis skipped in every language. The directive match is by name only, and itis case-sensitive.
git diff --merge-base main, because the permission checkfor an injected command rejects command substitution.
--merge-baserequires Git 2.30or later.
Notes
it changes.
<!--literals in the checker's own source are split, so that a check of thescript does not read it as one block.
Verification
tests/run: 73 tests pass.tests/mutate: 194 mutants, all detected.claude plugin validate --json .passes the CI condition.claude --plugin-dir . -p '/haddock:doc-style-check'against a planted finding. The checker output was injected, and the model acted on it.