diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 3094d36e..368a1c4a 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -9,6 +9,10 @@ { "name": "structured-context", "source": "./plugin" + }, + { + "name": "sctx-dev", + "source": "./dev-plugin" } ] } diff --git a/.claude/settings.json b/.claude/settings.json index 566b31db..00e0bec3 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,4 +1,12 @@ { + "extraKnownMarketplaces": { + "structured-context": { + "source": { "source": "github", "repo": "mindsocket/structured-context" } + } + }, + "enabledPlugins": { + "sctx-dev@structured-context": true + }, "hooks": { "Stop": [ { @@ -6,10 +14,6 @@ { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.agents/hooks/lint-and-test.sh" - }, - { - "type": "command", - "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/prose-check.sh" } ] } diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..5e0f892e --- /dev/null +++ b/.gitattributes @@ -0,0 +1,5 @@ +# Generated files: collapsed in GitHub diffs and left out of the sctx-dev review check. +plugin/hooks/projection.js linguist-generated +plugin/types/index.d.ts linguist-generated +schemas/generated/** linguist-generated +bun.lock linguist-generated diff --git a/AGENTS.md b/AGENTS.md index 65eb247e..00e8433d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -75,4 +75,4 @@ Run `bun run test` during development. Run the others with `bun run` when a chan ## Hooks Address issues related to change you made if a Stop hook reports them. -The Stop hook and pre-push block while the branch adds docs or code comments that `doc-review` has not seen (`scripts/prose-check.sh`). +The Stop and SubagentStop hooks and pre-push block while the branch adds docs, code comments or tests that the `doc-review` or `test-review` skill has not seen. Both come from the contributor plugin, `sctx-dev` ([docs/architecture.md](docs/architecture.md#contributor-plugin)). diff --git a/dev-plugin/.claude-plugin/plugin.json b/dev-plugin/.claude-plugin/plugin.json new file mode 100644 index 00000000..c46fb44d --- /dev/null +++ b/dev-plugin/.claude-plugin/plugin.json @@ -0,0 +1,7 @@ +{ + "name": "sctx-dev", + "description": "For contributors to structured-context repositories: doc-review and test-review skills, and Stop and SubagentStop hooks that block while a branch adds prose or tests no review has seen.", + "homepage": "https://github.com/mindsocket/structured-context", + "repository": "https://github.com/mindsocket/structured-context", + "license": "MIT" +} diff --git a/dev-plugin/hooks/hooks.json b/dev-plugin/hooks/hooks.json new file mode 100644 index 00000000..016291d0 --- /dev/null +++ b/dev-plugin/hooks/hooks.json @@ -0,0 +1,26 @@ +{ + "hooks": { + "Stop": [ + { + "hooks": [ + { + "type": "command", + "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/on-stop.sh\"", + "timeout": 120 + } + ] + } + ], + "SubagentStop": [ + { + "hooks": [ + { + "type": "command", + "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/on-stop.sh\"", + "timeout": 120 + } + ] + } + ] + } +} diff --git a/dev-plugin/scripts/on-stop.sh b/dev-plugin/scripts/on-stop.sh new file mode 100755 index 00000000..7f330361 --- /dev/null +++ b/dev-plugin/scripts/on-stop.sh @@ -0,0 +1,23 @@ +#!/usr/bin/env bash +# Runs the review check for the repo holding the hook's cwd: the session's checkout, or a +# subagent's own worktree on SubagentStop. Where cwd is a folder above several checkouts, +# each git checkout directly under it gets the check. +set -uo pipefail + +check="$(dirname "$0")/review-check.sh" + +# Without jq the hook stays in the directory Claude Code ran it from. +cwd="$(jq -r '.cwd // empty' 2>/dev/null)" +[ -n "$cwd" ] && cd "$cwd" 2>/dev/null + +if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then + exec bash "$check" +fi + +status=0 +for dir in */; do + [ -e "$dir.git" ] || continue + (cd "$dir" && bash "$check") + [ $? -eq 2 ] && status=2 +done +exit "$status" diff --git a/dev-plugin/scripts/review-check.sh b/dev-plugin/scripts/review-check.sh new file mode 100755 index 00000000..551973e3 --- /dev/null +++ b/dev-plugin/scripts/review-check.sh @@ -0,0 +1,90 @@ +#!/usr/bin/env bash +# Exits 2 while the branch adds prose (docs and code comments) or tests that no review +# has seen. A kind argument (prose or tests) checks that kind only. --mark +# records the current additions of that kind as reviewed. +# +# Paths with the linguist-generated attribute in .gitattributes are left out. +set -uo pipefail + +script="$(cd "$(dirname "$0")" && pwd)/$(basename "$0")" + +mark= +if [ "${1:-}" = "--mark" ]; then + mark=1 + shift + if [ $# -ne 1 ]; then + echo "usage: $script --mark prose|tests" >&2 + exit 1 + fi +fi +kinds="${*:-prose tests}" +for kind in $kinds; do + case "$kind" in + prose | tests) ;; + *) + echo "unknown kind: $kind (expected prose or tests)" >&2 + exit 1 + ;; + esac +done + +root="$(git rev-parse --show-toplevel 2>/dev/null)" || exit 0 +cd "$root" || exit 0 + +# A slow or unreachable remote must not hold up a hook, so the fetch gets 10 seconds. +git fetch --quiet origin main >/dev/null 2>&1 & +fetch=$! +(sleep 10 && kill "$fetch") >/dev/null 2>&1 & +watch=$! +wait "$fetch" 2>/dev/null +kill "$watch" 2>/dev/null + +base="$(git merge-base origin/main HEAD 2>/dev/null)" || exit 0 + +# Prints "filelabelline" for each added line of the kind, untracked files included. +added() { + local specs + case "$1" in + prose) specs=('*.md' '*.ts' '*.tsx' '*.js' '*.mjs' '*.cjs' '*.sh' '*.yml' '*.yaml' '*.json5' '*.jsonc') ;; + tests) specs=('*.test.*' '*.spec.*') ;; + esac + specs+=(':(exclude,attr:linguist-generated)') + { + git diff -U0 --no-color "$base" -- "${specs[@]}" + git ls-files -z --others --exclude-standard -- "${specs[@]}" | + xargs -0 -r -n1 git diff -U0 --no-color --no-index /dev/null + } | awk -v kind="$1" ' + /^\+\+\+ b\// { file = substr($0, 7); doc = file ~ /\.md$/; next } + /^\+/ { + line = substr($0, 2) + if (line !~ /[^[:space:]]/) next + if (kind == "tests") print file "\ttest\t" line + else if (doc) print file "\tdoc\t" line + else if (line ~ /^[[:space:]]*(\/\/|\/\*|\*|#)/ && line !~ /^#!/) print file "\tcomment\t" line + }' +} + +status=0 +for kind in $kinds; do + lines="$(added "$kind")" + stamp="$(git rev-parse --git-path "$kind-reviewed")" + hash="$(printf '%s' "$lines" | git hash-object --stdin)" + if [ -n "$mark" ]; then + echo "$hash" >"$stamp" + continue + fi + [ -z "$lines" ] && continue + [ "$(cat "$stamp" 2>/dev/null)" = "$hash" ] && continue + + case "$kind" in + prose) what="Prose" skill="doc-review" ;; + tests) what="Tests" skill="test-review" ;; + esac + { + echo "$what added in $root since the last $skill:" + printf '%s\n' "$lines" | awk -F'\t' '{ n[$1 " (" $2 ")"]++ } END { for (f in n) printf " %4d %s\n", n[f], f }' | sort -rn + echo "Run the $skill skill on this diff, apply its findings, then run $script --mark $kind." + } >&2 + status=2 +done +exit "$status" diff --git a/.claude/skills/doc-review/SKILL.md b/dev-plugin/skills/doc-review/SKILL.md similarity index 55% rename from .claude/skills/doc-review/SKILL.md rename to dev-plugin/skills/doc-review/SKILL.md index 79647a29..6c04ebd0 100644 --- a/.claude/skills/doc-review/SKILL.md +++ b/dev-plugin/skills/doc-review/SKILL.md @@ -1,33 +1,35 @@ --- name: doc-review -description: Review written content in this repo (README, docs/, AGENTS.md, plugin skills and references, CLI help and error text) against the project's documentation standards, then fix what it finds. Use after writing or changing any prose, before committing or opening a PR. +description: Review written content in a structured-context (sctx) repo (README, docs/, AGENTS.md, skills and references, code comments, CLI help and error text) against the repo's documentation standards, then fix what it finds. Use after writing or changing any prose, before committing or opening a PR. +allowed-tools: Bash(${CLAUDE_PLUGIN_ROOT}/scripts/review-check.sh --mark prose) --- ## Task Review the prose in the target named by `$ARGUMENTS`: a PR number, branch, commit, or list of files. With no argument, use uncommitted changes, or if there are none, the branch against `main` (`git diff main...HEAD`). -Look at `*.md`, `plugin/**`, and user-facing strings in `src/` and tests. Apply the **Documentation Principles** in -`AGENTS.md`, then fix the findings. Re-read each finding in context: a flagged phrase is sometimes the right -wording. +Look at `*.md`, skills, code comments, and user-facing strings in source and tests. Apply the documentation +principles in the repo's `AGENTS.md`, then fix the findings. Re-read each finding in context: a flagged phrase is +sometimes the right wording. ## Checks -For every changed passage, ask: +Read each changed paragraph or section in full, not only its changed lines, and ask: 1. **Would someone new to the project understand it?** Flag decision history and internal jargon ("never merged by location", "A′", phase names). Say what does happen. 2. **Does it earn its place?** Flag sentences that restate the previous one, state the obvious, spell out an implication the reader can work out, or describe what is not the case without a likely wrong assumption to correct. Flag error codes and flags the output already shows. -3. **Is it in the right place?** Flag duplicated explanations (owned once, linked elsewhere). A README section is - a sentence or two pointing to docs/. Detail used rarely belongs in `references/` or `sctx docs`. +3. **Is it in the right place?** Read the code and docs the passage describes, then flag duplicated explanations + (owned once, linked elsewhere). A README section is a sentence or two pointing to docs/. Detail used rarely + belongs in a skill's `references/` or a linked doc. 4. **Is a recommendation labelled as one?** "It is recommended to..." rather than a rule stated as fact. 5. **Follows the doc's convention:** a new entry matches its neighbours in size and shape. Do not describe call signatures, options, fields or types that the code already defines, since they go stale; say what it is for. -6. **Names:** `structured-context` in prose, `sctx` only in commands. Terms match `docs/concepts.md`. +6. **Names** follow the naming rules in `AGENTS.md`, and terms match the repo's glossary (`docs/concepts.md`). -Skills and references (`plugin/skills/**`), also: +Skills and references (a `SKILL.md` and its `references/`), also: 7. **Trigger:** the `description` names structured-context (sctx) and the task in words a user or agent would use, briefly. It does not rely on terms an agent session may not know (such as "space"). @@ -45,6 +47,8 @@ Code comments and messages: ## Output -List findings as `file:line, check number, proposed rewrite`, then apply them. Run `bun run lint` and, if -`plugin/` changed, `bun run test:hook`. Finish by checking `docs/definition-of-done.md` for files -the change affects but does not touch, then run `scripts/prose-check.sh --mark`. +Go through the checks in order. List each finding as `file:line, check number, proposed rewrite`, and write "none" +for a check with no findings. Then apply them. Run the repo's lint and any check its definition of done names for +the area changed. Finish by checking the definition of done (in `AGENTS.md` or the doc it links) for files the +change affects but does not touch, then run +`${CLAUDE_PLUGIN_ROOT}/scripts/review-check.sh --mark prose`. diff --git a/dev-plugin/skills/test-review/SKILL.md b/dev-plugin/skills/test-review/SKILL.md new file mode 100644 index 00000000..d567388b --- /dev/null +++ b/dev-plugin/skills/test-review/SKILL.md @@ -0,0 +1,42 @@ +--- +name: test-review +description: Review new or changed tests in a structured-context (sctx) repo for tests that duplicate others, re-test a schema, or assert what their own setup makes true, then fix what it finds. Use after adding or changing tests, before committing or opening a PR. +allowed-tools: Bash(${CLAUDE_PLUGIN_ROOT}/scripts/review-check.sh --mark tests) +--- + +## Task + +Review the tests in the target named by `$ARGUMENTS`: a PR number, branch, commit, or list of files. With no +argument, use uncommitted changes, or if there are none, the branch against `main` (`git diff main...HEAD`). +Apply the test principles in the repo's `AGENTS.md`, then fix the findings. Read the code under test and the +neighbouring test files before judging a test: coverage is a property of the whole suite. + +## Checks + +For every added or changed test, ask: + +1. **Does it prove something no other test does?** Search the suite for a test that already covers the + behaviour. Flag the newer or weaker one. +2. **Does it re-test a JSON Schema?** A schema's own constraints (types, required keys, enums, patterns) are the + validator's job. Test only the checks the schema can't express. +3. **Is it a second input down a covered code path?** One input per path. Flag cases, `each` rows or fixtures + that take a branch another case already takes. +4. **Does it assert what its own setup makes true?** Flag assertions that hold because of the test's config, + fixture or mock, whatever the code under test does. +5. **Are expected values derived?** Expected values come from the fixture or the code under test, not from a + copy of the output pasted in. +6. **Will it grow with the code?** Flag hard-coded lists (layouts, exports, files, schema keys) that a new entry + elsewhere makes stale. +7. **Does it assert the behaviour its name states?** Flag names that promise more or other than the assertions + check, and assertions on things that only happen to be true. + +For the change as a whole: + +8. **Did it make a test redundant?** When a change moves or narrows behaviour, flag the tests it leaves proving + nothing new, including ones the diff doesn't touch. + +## Output + +List findings as `file:line, check number, proposed change` (a rewrite, a merge into another test, or a deletion +naming the test that covers it), then apply them. Run the repo's test, typecheck and lint commands from +`AGENTS.md`. Finish with `${CLAUDE_PLUGIN_ROOT}/scripts/review-check.sh --mark tests`. diff --git a/docs/architecture.md b/docs/architecture.md index ca72c27a..37b1b1e1 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -113,6 +113,10 @@ The map pane (`plugin/hooks/map-pane.tsx`, `/sctx-map`) draws a space's hierarch Git hooks (`lefthook.yml`, `scripts/sync-plugin-version.ts`) manage the version in `plugin/.claude-plugin/plugin.json`. Pre-commit bumps the patch version for any commit touching `plugin/`, so the plugin version runs ahead of `package.json` between releases. It also raises major.minor to match `package.json` after a release. Pre-push fails if a commit since the last tag changed `plugin/` without a version bump. +### Contributor plugin + +`dev-plugin/` is `sctx-dev`, a second plugin in the same marketplace, for contributors to the structured-context repositories. Its skills review a change against each repo's documentation and test standards. Its hooks and each repo's pre-push block while a branch adds prose or tests that no review has seen. `dev-plugin/scripts/review-check.sh` describes the check. A repository opts in by enabling the plugin in its `.claude/settings.json` and calling that script from pre-push. The plugin has no version, so installs follow the marketplace's commits. + --- ## Field Remapping diff --git a/lefthook.yml b/lefthook.yml index 1d971e00..e0c04a50 100644 --- a/lefthook.yml +++ b/lefthook.yml @@ -29,5 +29,5 @@ pre-push: run: bash scripts/sync-plugin-version.sh --check pushed-tree: run: bash scripts/git-hooks/check-pushed-tree.sh - prose-check: - run: bash scripts/prose-check.sh + review-check: + run: bash dev-plugin/scripts/review-check.sh diff --git a/scripts/prose-check.sh b/scripts/prose-check.sh deleted file mode 100755 index d13b109b..00000000 --- a/scripts/prose-check.sh +++ /dev/null @@ -1,44 +0,0 @@ -#!/usr/bin/env bash -# Exits 2 while the branch adds docs or code comments that no doc-review has seen. -# --mark records the current additions as reviewed. -set -uo pipefail - -root="$(git rev-parse --show-toplevel)" || exit 0 -cd "$root" || exit 0 -base="$(git merge-base origin/main HEAD 2>/dev/null)" || exit 0 -stamp="$(git rev-parse --git-path prose-reviewed)" - -code='*.ts *.tsx *.js *.mjs *.cjs *.sh *.yml *.yaml' -generated=':!plugin/hooks/projection.js :!plugin/types/index.d.ts :!schemas/generated' - -# Prints "filekindline" for each added prose line, untracked files included. -added() { - { - git diff -U0 --no-color "$base" -- '*.md' $code $generated - git ls-files -z --others --exclude-standard -- '*.md' $code $generated | - xargs -0 -r -n1 git diff -U0 --no-color --no-index /dev/null - } | awk ' - /^\+\+\+ b\// { file = substr($0, 7); doc = file ~ /\.md$/; next } - /^\+/ { - line = substr($0, 2) - if (doc) { if (line ~ /[^[:space:]]/) print file "\tdoc\t" line } - else if (line ~ /^[[:space:]]*(\/\/|\/\*|\*|#)/ && line !~ /^#!/) print file "\tcomment\t" line - }' -} - -lines="$(added)" -[ -z "$lines" ] && exit 0 -hash="$(printf '%s' "$lines" | git hash-object --stdin)" - -if [ "${1:-}" = "--mark" ]; then - echo "$hash" >"$stamp" - exit 0 -fi -[ "$(cat "$stamp" 2>/dev/null)" = "$hash" ] && exit 0 - -{ - echo "Prose added since the last doc-review:" - printf '%s\n' "$lines" | awk -F'\t' '{ n[$1 " (" $2 ")"]++ } END { for (f in n) printf " %4d %s\n", n[f], f }' | sort -rn - echo "Run the doc-review skill on this diff, apply its cuts, then run scripts/prose-check.sh --mark." -} >&2 -exit 2 diff --git a/tests/docs/references.test.ts b/tests/docs/references.test.ts index 46e43ae6..71e7b378 100644 --- a/tests/docs/references.test.ts +++ b/tests/docs/references.test.ts @@ -14,10 +14,10 @@ import { join, resolve } from 'node:path'; const ROOT = resolve(import.meta.dir, '../..'); /** Docs that describe the current tree: agent instructions, README, top-level docs, and plugin skills. */ -const SCANNED = ['README.md', 'AGENTS.md', 'docs', 'plugin']; +const SCANNED = ['README.md', 'AGENTS.md', 'docs', 'plugin', 'dev-plugin']; /** Repo-relative paths appear in backticks; these are the roots worth checking. */ -const PATH_PATTERN = /`\/?((?:src|tests|schemas|plugin|docs|scripts|hook-test|smoke)\/[^`\s]*)`/g; +const PATH_PATTERN = /`\/?((?:src|tests|schemas|plugin|dev-plugin|docs|scripts|hook-test|smoke)\/[^`\s]*)`/g; /** Illustrative paths, not real ones: placeholders, globs, and naming-convention examples. */ const PLACEHOLDER = /YYYY|<[^>]+>|\[[^\]]+\]|\*|PascalCase|kebab-case|\bNN\b|\.\.\./;