13 Commits
Author SHA1 Message Date
MasseR 7bd0a652cb Clean hlint and cabal warnings 2026-10-02 15:42:12 +03:00
MasseR 449f404464 Review notes docs tweaks 2026-10-02 15:13:54 +03:00
MasseR 0e5d76901d Bound note header parsing 2026-10-02 15:13:04 +03:00
MasseR 773f3b550f Review notes docs 2026-10-02 14:47:46 +03:00
MasseR 4664e71493 Review note push 2026-10-02 14:45:17 +03:00
MasseR e7adb3e88b Latest review note 2026-10-02 14:41:26 +03:00
MasseR 2e2960c159 Review note script 2026-10-02 14:36:46 +03:00
MasseR 627f813859 Spec: verification wording matches scan-based latest 2026-10-02 14:31:49 +03:00
MasseR e750e0e687 Spec: latest scans notes by branch and round 2026-10-02 14:29:56 +03:00
MasseR 63210afc7b Track superpowers specs, ignore plans 2026-10-02 14:23:40 +03:00
MasseR 7ec491d383 Review notes protocol design 2026-10-02 14:22:24 +03:00
MasseR 4f1277aa45 Worktrees 2026-10-02 12:29:56 +03:00
MasseR 3908d5a3a6 REVIEW guidelines 2026-10-02 12:28:23 +03:00
22 changed files with 375 additions and 28 deletions

No files matched your search

+1 -1
View File
@@ -4,7 +4,7 @@ dist-newstyle
.worktrees/
docs/superpowers
docs/superpowers/plans
*.hp
*.eventlog
+10
View File
@@ -5,6 +5,11 @@
A sidecar for Home Assistant that runs automations using arrowized functional
reactive programming (AFRP). Haskell, built with cabal.
## Working style
- When doing any non-trivial work, always work in a worktree on a feature branch
- Feature branches should be named as the topic of the change
## Code style
- Vertical modules: split by feature/concept, not by layer.
@@ -25,3 +30,8 @@ reactive programming (AFRP). Haskell, built with cabal.
- hspec for unit tests, hedgehog for property tests.
- Run with `nix develop -c cabal test`.
## Reviewing
Reviews are recorded in git notes under `refs/notes/review`; read the latest
note before reviewing. See [[REVIEW.md]].
+49
View File
@@ -0,0 +1,49 @@
# Code Review Guidelines
- Each MR should be focused, changing only one concept at a time
- Keep MRs small - aim for under 500 lines of diff. There can be some wiggle room for cases that are hard to split
- When reviewing code, check for test coverage and suggest tests if missing
- Go through tests and think hard to see if any unit tests or group of unit tests can be replaced with a property test
- When suggesting a property test, consider cases that the property needs to falsify and whether it needs its own generator
- Business logic stays pure
## Comments
- Less is more
- If there's comments for a function, verify they're proper haddock style
- If there's comments for a function, they must only be about the contract and use instructions
- If there's comments for implementation, they should only be for exceptional cases, cases where the reader would question why something is implemented like that
- Comment style should follow minimalistic writing style
## Recording reviews
Reviews are stored as git notes under `refs/notes/review`, one note per
reviewed commit. The note header carries `branch`, `round`, `verdict`
(`approve` or `request-changes`), `previous` (sha of the last reviewed tip),
and a findings list with stable IDs (`F1`, `F2`, ...) whose `status` is
`open`, `resolved`, or `wontfix`. The body is free markdown prose.
Protocol:
1. Fetch prior results:
`git fetch origin "refs/notes/review:refs/notes/review"`
Ignore the failure on the first-ever review (origin has no notes ref yet);
if the fetch is rejected as non-fast-forward, your local notes are ahead —
push instead.
2. Read the latest verdict and open findings for the branch:
`scripts/review-note latest [branch]`
3. Review the branch tip per this document.
4. Write the note (header + markdown) to a file and attach it to the tip:
`scripts/review-note write <file>`. Use `--force` only to replace a note
on the same commit deliberately.
5. Publish: `scripts/review-note push` (plain `git push` does not push
notes).
On a re-review after fixes: new tip, new note, `round`+1, `previous` set to
the last reviewed sha, open findings carried forward by ID, resolved ones
marked `resolved`.
On a branch rename: update the note's `branch:` header to the new name and
mention the old name in the body, so `latest <new-name>` chains and history
stays findable.
@@ -0,0 +1,113 @@
# Review notes protocol
Date: 2026-10-02
Status: approved
## Purpose
Record code-review results as git notes under `refs/notes/review` so that the
next reviewer — human or AI — can read the current verdict, see open findings
with stable IDs, and continue from where the last review stopped. This
replaces a CI reviewer: reviews happen locally, results travel with the
commits they judged.
## Storage model
- One note per reviewed commit, in the `review` notes ref.
- The tip of a reviewed branch always carries the latest verdict.
- Re-reviewing after fixes writes a **new** note on the **new** tip commit.
Old notes stay attached to old commits as history.
- Each note links to the previously reviewed commit via `previous`, forming a
walkable chain of review rounds per branch.
- Merging to main needs no special handling: the `approve` note on the final
tip is the record.
## Note format
Line-based header, then a blank line, then free markdown body:
branch: <branch name>
round: <integer, starting at 1>
verdict: approve | request-changes
previous: none | <sha of previously reviewed tip>
findings:
- id: F<N>
severity: blocker | major | minor
file: <path>:<line>
title: <one line>
status: open | resolved | wontfix
## Details
<markdown prose>
Rules:
- Finding IDs are unique within a note and carry forward across rounds: a
finding resolved since the last note keeps its ID and moves to
`status: resolved`; an unfixed finding keeps its ID and `status: open`.
New findings get fresh IDs that do not collide with carried-forward ones.
- The body is free markdown; the `## Details` heading in the example is
illustrative, not required.
- Headers are plain `key: value` lines so the helper script can parse them
with sed/awk.
## Helper script: `scripts/review-note`
Bash, git plumbing only. Subcommands:
- `review-note show [commit]` — print the note for a commit (default: current
tip). Exit 1 with a message on stderr if there is no note.
- `review-note write <file>` — attach the note in `<file>` to the current tip
commit. Refuses to replace an existing note unless `--force` is given; a
proper re-review targets a new commit, so overwriting is always deliberate.
Validates that `branch`, `round`, and `verdict` are present and that
`verdict` uses the vocabulary above. No other validation.
- `review-note latest [branch]` — print the note with the highest `round` for
a branch (default: current branch), scanning the notes ref and matching
notes on their `branch:` header. Exit 1 if there is no note for the branch.
(A `previous`-chain walk cannot bootstrap from an unreviewed tip, so the
scan uses the `branch:` header as the index instead.)
- `review-note push` — `git push origin refs/notes/review`. Plain `git push`
ignores notes, so this is the only way results travel.
`push` pushes without force; if the remote rejects, report the failure and let
the user decide.
## Lifecycle
1. Reviewer reads `review-note latest <branch>` (exit 1 means first review).
2. Reviewer reviews the branch tip per `REVIEW.md`.
3. Reviewer writes the note with `review-note write` and runs
`review-note push`.
4. If the verdict is `request-changes`, the author pushes fixes as new
commits. The next review round starts at the new tip with `round`+1,
`previous` set to the last reviewed tip, and carried-forward findings.
5. When the verdict is `approve` and the branch merges, the notes remain on
the branch commits as the review record.
## Documentation integration
- `REVIEW.md` gains a "Recording reviews" section describing the protocol and
the four script commands. This is the single source of truth for the
protocol.
- `AGENTS.md` "Reviewing" section gains one line pointing at the section, so
any AI session picks up the flow automatically.
## Seeding the experiment
The failing review of `home_assistant_controller_cleanup` (commit `ba6e0e8`)
becomes note round 1, with these findings:
- F1 (blocker, src/AFRP.hs:273): hlint's `\_ -> x` → `const x` rewrites break
the rank-2 `Mealy` type; library does not compile.
- F2 (blocker, test/AFRPLawsSpec.hs:98): seven law tests reduced to
tautologies by hlint rewrites; see :103, :212, :221, :228, :235, :256.
- F3 (minor, test/AFRPLawsSpec.hs:241): the interchange and composition laws
were reshaped to `<$>` forms; fold them into the same hlint suppression.
## Verification
The script is verified by round-trip checks in a throwaway temp clone: write,
show, latest (two rounds, branch filtering), force-overwrite refusal and
acceptance, and push. No Haskell or cabal changes, so no
cabal2nix regeneration.
+1 -1
View File
@@ -52,7 +52,7 @@ extra-doc-files: CHANGELOG.md
-- extra-source-files:
common warnings
ghc-options: -Wall
ghc-options: -Wall -Werror
library
-- Import common warning flags.
+95
View File
@@ -0,0 +1,95 @@
#!/usr/bin/env bash
# review-note: manage code-review notes under refs/notes/review.
# The protocol lives in REVIEW.md.
set -euo pipefail
NOTES_REF=refs/notes/review
REMOTE=origin
die() { echo "review-note: $*" >&2; exit 1; }
usage() {
cat >&2 <<'EOF'
usage:
review-note show [commit]
review-note write <file> [--force]
review-note latest [branch]
review-note push
EOF
exit 1
}
validate() {
local file="$1"
grep -q '^branch: .\+' "$file" || die "missing or empty 'branch:' header"
grep -Eq '^round: [0-9]+$' "$file" || die "missing or invalid 'round:' header"
grep -Eq '^verdict: (approve|request-changes)$' "$file" \
|| die "verdict must be 'approve' or 'request-changes'"
}
cmd_show() {
local commit="${1:-HEAD}"
git notes --ref="$NOTES_REF" show "$commit" 2>/dev/null \
|| die "no review note for $commit"
}
cmd_write() {
local force="" file=""
local arg
for arg in "$@"; do
case "$arg" in
--force) force=1 ;;
*) file="$arg" ;;
esac
done
[ -n "$file" ] || usage
[ -f "$file" ] || die "no such file: $file"
local tip
tip=$(git rev-parse HEAD)
if [ -z "$force" ] && git notes --ref="$NOTES_REF" show "$tip" >/dev/null 2>&1; then
die "tip $tip already has a review note; pass --force to replace"
fi
validate "$file"
if [ -n "$force" ]; then
git notes --ref="$NOTES_REF" add -f -F "$file" "$tip"
else
git notes --ref="$NOTES_REF" add -F "$file" "$tip"
fi
}
cmd_latest() {
local branch="${1:-$(git branch --show-current)}"
local blob obj note br rnd best="" best_round=-1
while read -r blob obj; do
note=$(git notes --ref="$NOTES_REF" show "$obj") || continue
br=$(sed -n '/^$/q; s/^branch: //p' <<<"$note")
[ "$br" = "$branch" ] || continue
rnd=$(sed -n '/^$/q; s/^round: //p' <<<"$note")
[[ "$rnd" =~ ^[0-9]+$ ]] || continue
if [ "$rnd" -gt "$best_round" ]; then
best_round=$rnd
best=$note
fi
done < <(git notes --ref="$NOTES_REF" list)
[ -n "$best" ] || die "no review notes for branch: $branch"
printf '%s\n' "$best"
}
cmd_push() {
git rev-parse -q --verify "$NOTES_REF" >/dev/null || die "no review notes to push"
git push "$REMOTE" "$NOTES_REF"
}
main() {
local cmd="${1:-}"
if [ $# -gt 0 ]; then shift; fi
case "$cmd" in
show) cmd_show "$@" ;;
write) cmd_write "$@" ;;
latest) cmd_latest "$@" ;;
push) cmd_push "$@" ;;
*) usage ;;
esac
}
main "$@"
+82
View File
@@ -0,0 +1,82 @@
#!/usr/bin/env bash
# Round-trip checks for scripts/review-note, in a throwaway temp repo.
set -euo pipefail
root=$(cd "$(dirname "$0")/.." && pwd -P)
rn="$root/scripts/review-note"
fail() { echo "FAIL: $*" >&2; exit 1; }
tmp=$(mktemp -d)
trap 'rm -rf "$tmp"' EXIT
git init -q --bare "$tmp/remote.git"
git init -q -b main "$tmp/repo"
cd "$tmp/repo"
git config user.email test@example.com
git config user.name test
echo one > a.txt && git add a.txt && git commit -qm one
echo two > b.txt && git add b.txt && git commit -qm two
note="$tmp/note1"
cat > "$note" <<'EOF'
branch: main
round: 1
verdict: request-changes
previous: none
findings:
- id: F1
severity: blocker
file: a.txt:1
title: fix me
status: open
## Details
Fix it.
EOF
if "$rn" show >/dev/null 2>&1; then fail "show should exit 1 without a note"; fi
sed '/^verdict:/d' "$note" > "$tmp/no-verdict"
if "$rn" write "$tmp/no-verdict" >/dev/null 2>&1; then fail "write should refuse a missing verdict"; fi
sed 's/^verdict: request-changes/verdict: maybe/' "$note" > "$tmp/bad-verdict"
if "$rn" write "$tmp/bad-verdict" >/dev/null 2>&1; then fail "write should refuse a bad verdict"; fi
"$rn" write "$note"
"$rn" show | grep -q '^verdict: request-changes$' || fail "show should print the note"
if "$rn" write "$note" >/dev/null 2>&1; then fail "write should refuse an existing note"; fi
sed 's/^verdict: request-changes/verdict: approve/' "$note" > "$tmp/note1b"
"$rn" write "$tmp/note1b" --force
"$rn" show | grep -q '^verdict: approve$' || fail "show should print the replaced note"
"$rn" show | diff -u "$tmp/note1b" - || fail "show should print the note verbatim"
# latest finds the note by branch, even from a newer unreviewed tip
echo three > c.txt && git add c.txt && git commit -qm three
"$rn" latest main | grep -q '^verdict: approve$' || fail "latest should find the round 1 note"
# a note for another branch must not leak into the result
sed -e 's/^branch: main/branch: other/' -e 's/^round: 1/round: 9/' "$tmp/note1b" > "$tmp/other"
"$rn" write "$tmp/other"
"$rn" latest main | grep -q '^verdict: approve$' || fail "latest should ignore other branches"
# round 2 on the new tip wins and carries previous (replaces the
# other-branch note on the same commit, so --force)
PREV=$(git rev-parse HEAD~1)
sed -e 's/^round: 1/round: 2/' -e "s/^previous: none/previous: $PREV/" "$tmp/note1b" > "$tmp/note2"
"$rn" write "$tmp/note2" --force
"$rn" latest main | grep -q '^round: 2$' || fail "latest should pick the highest round"
"$rn" latest main | grep -q "^previous: $PREV$" || fail "round 2 should carry previous"
if "$rn" latest nosuch >/dev/null 2>&1; then fail "latest should exit 1 for an unknown branch"; fi
# push publishes notes to origin; a fresh clone picks them up
git remote add origin "$tmp/remote.git"
git push -q origin main
"$rn" push
git clone -q "$tmp/remote.git" "$tmp/clone"
cd "$tmp/clone"
git fetch -q origin "refs/notes/review:refs/notes/review"
"$rn" latest main | grep -q '^round: 2$' || fail "clone should see the round 2 note"
echo "ok: show/write/latest/push"
+4 -6
View File
@@ -1,5 +1,4 @@
{-# LANGUAGE LambdaCase #-}
{-# LANGUAGE Arrows #-}
module AFRP
( Mealy(..)
@@ -129,7 +128,7 @@ instance Monad m => Applicative (Auto m a) where
pure a = Fun (\_req -> const a)
fa <*> fb =
case (fa,fb) of
(Fun af, Fun bf) -> Fun $ \req -> (af req <*> bf req)
(Fun af, Fun bf) -> Fun $ \req -> af req <*> bf req
(Stateful codec s af, Fun bf) -> Stateful codec s
(\s' req x -> do
let a = bf req x
@@ -179,7 +178,7 @@ instance (Monad m, Monoid b) => Monoid (Auto m a b) where
instance Monad m => Category (Auto m) where
id = Fun $ \_ -> id
id = Fun $ const id
af . ag =
case (af, ag) of
(Fun f, Fun g) -> Fun (\req -> f req . g req)
@@ -272,8 +271,6 @@ instance Semigroup b => Semigroup (Mealy eff a b) where
instance Monoid b => Monoid (Mealy eff a b) where
mempty = Mealy mempty $ \_nt -> mempty
-- where
-- m = Mealy mempty $ \_ _ _ -> pure (Pair mempty m)
eff :: (Request -> a -> eff b) -> Mealy eff a b
eff f = Mealy mempty $ \nt -> do
@@ -288,7 +285,8 @@ withEntities :: S.Set T.Text -> Mealy eff a b -> Mealy eff a b
withEntities es (Mealy _ f) = Mealy es f
instance Category (Mealy eff) where
id = Mealy mempty (\_ -> id)
{- HLINT ignore "Use const" -}
id = Mealy mempty $ \_nt -> id
(Mealy ast f) . (Mealy bst g) = Mealy (ast <> bst) $ \nt -> do
f nt . g nt
-1
View File
@@ -1,4 +1,3 @@
{-# LANGUAGE Arrows #-}
{-# LANGUAGE OverloadedStrings #-}
module HomeAssistant.Controller.Ruuvi
( Ruuvi(..)
+1 -2
View File
@@ -36,10 +36,9 @@ import Data.UUID (toText)
import AFRP (Request(..), Event(..))
import Control.Monad.IO.Class (liftIO, MonadIO)
import HomeAssistant.Runtime.RateLimit (RateLimited, RateLimiter, runRateLimited)
import Control.Monad.Catch (MonadCatch)
import GHC.Stack (HasCallStack)
import UnliftIO (MonadUnliftIO, race, withRunInIO)
import Control.Monad.Catch (onException)
import Control.Monad.Catch (MonadCatch, onException)
-- | Connect, authenticate, subscribe, then receive and broadcast forever.
-- Restarting this action reconnects. All setup sends happen before the
+1 -1
View File
@@ -44,7 +44,7 @@ loadFlags rootPath allNames = do
let path = rootPath </> "handlers.json"
fileMap <- readFlagsFile path
let defaults = M.fromList [(n, True) | n <- allNames]
initial = M.unionWith (\fileVal -> const fileVal) fileMap defaults
initial = M.unionWith const fileMap defaults
tv <- liftIO $ newTVarIO initial
lock <- liftIO $ newMVar ()
pure Flags
+3 -3
View File
@@ -190,10 +190,10 @@ cfName = \case
defArgs :: FilePath -> Series -> [String]
defArgs rrdPath series =
[ "DEF:" ++ rawF ++ "=" ++ rrdPath ++ ":"
( "DEF:" ++ rawF ++ "=" ++ rrdPath ++ ":"
++ srcDs source ++ ":" ++ cfName (srcCF source)
]
++ transformArgs
)
: transformArgs
where
source = serSource series
alias = serAlias series
+1 -1
View File
@@ -43,7 +43,7 @@ data API mode = API
getFlagsHandler :: Flags -> LoggingHandler (Map Text Bool)
getFlagsHandler flags = allFlags flags
getFlagsHandler = allFlags
putFlagHandler :: Flags -> Text -> Bool -> LoggingHandler (Map Text Bool)
putFlagHandler flags name val
+4
View File
@@ -12,6 +12,10 @@ import Support (fakeRequest)
import Test.Hspec (Spec, describe, it)
import Test.Hspec.Hedgehog (forAll, forAllWith, hedgehog, (===))
-- We are testing laws -> hlint warns about not using laws
{-# ANN module "Hlint: ignore" #-}
-- | Law tests for the Mealy instances. Two machines count as equal when
-- they emit equal outputs on every input sequence, so each law runs both
-- sides on generated inputs.
+3 -2
View File
@@ -19,6 +19,7 @@ import qualified Hedgehog.Gen as Gen
import qualified Hedgehog.Range as Range
import Test.Hspec
import Test.Hspec.Hedgehog
import Data.Maybe (listToMaybe)
fakeRequest :: Request
fakeRequest = Request (sec 0) utc nil "test"
@@ -52,7 +53,7 @@ instance Functor St where
fmap f (St g) = St $ \s -> let (a, s') = g s in (f a, s')
instance Applicative St where
pure a = St (\s -> (a, s))
pure a = St (a,)
St f <*> St x = St $ \s -> let (f', s') = f s; (a, s'') = x s' in (f' a, s'')
instance Monad St where
@@ -165,7 +166,7 @@ lMergeSpec = describe "lMerge" $ do
changesSpec :: Spec
changesSpec = describe "changes" $ do
it "first output is always Tick" $
runPure changes "hello" !! 0 `shouldBe` Tick
listToMaybe (runPure changes "hello") `shouldBe` Just Tick
it "outputs Event only on value change" $
runPure changes "aaaabbbcca"
+1 -2
View File
@@ -6,7 +6,7 @@ import AFRP (Request (..), Event (..))
import Control.Concurrent.STM
( atomically
, dupTChan
, isEmptyTChan
, readTChan
, writeTChan
)
@@ -18,7 +18,6 @@ import HomeAssistant.Controller (HASSEff (..), Service (..), Target(..))
import HomeAssistant.Runtime.Bus
import HomeAssistant.Runtime.Flags (loadFlags, setEnabled)
import HomeAssistant.Runtime.Metrics (registerAppMetrics)
import Control.Monad.IO.Class (liftIO)
import Katip (Namespace (Namespace), runKatipContextT)
import Katip.Monadic (runNoLoggingT)
import Support (withTestLogEnv)
+1 -3
View File
@@ -80,7 +80,5 @@ req n = Request (UTCTime (toEnum 0) (fromIntegral (0 :: Int))) utc
uuid = "00000000-0000-0000-0000-" <> pad n
lightOn :: [Target] -> Service
lightOn targets = Service "light" "turn_on" Nothing targets
lightOn = Service "light" "turn_on" Nothing
lightOff :: [Target] -> Service
lightOff targets = Service "light" "turn_off" Nothing targets
-1
View File
@@ -4,7 +4,6 @@ import Test.Hspec
import Data.Default (def)
import HomeAssistant.Controller (Brightness(..), formatLightAttributes, LightAttributes(..))
import Data.Aeson (object, (.=))
import HomeAssistant.Controller ()
spec :: Spec
+1 -1
View File
@@ -70,7 +70,7 @@ spec = describe "Flags" $ do
n <- forAll $ Gen.int (Range.linear 1 50)
liftIO $ withTempDirectory "/tmp" "flags-spec" $ \dir -> do
flags <- runNoLoggingT (loadFlags dir ["x"])
mapConcurrently_ (\i -> setEnabled flags "x" (even i)) [1 .. n]
mapConcurrently_ (setEnabled flags "x" . even) [1 .. n]
m <- allFlags flags
decoded <- decodeFileStrict (dir <> "/handlers.json")
(decoded :: Maybe (Map Text Bool)) `shouldBe` Just m
+1 -1
View File
@@ -7,6 +7,7 @@ import qualified Data.ByteString as BS
import HomeAssistant.Runtime.Graphing
( GraphSpec (..)
, Range (..)
, Graph(..)
, buildGraphArgs
, graphs
, lookupGraph
@@ -21,7 +22,6 @@ import System.Exit (ExitCode (..))
import System.Process (readProcessWithExitCode)
import Test.Hspec
import Servant.API (FromHttpApiData(..), ToHttpApiData (..))
import HomeAssistant.Runtime.Graphing (Graph(..))
traffic :: GraphSpec
traffic = case lookupGraph graphs Traffic of
+1 -1
View File
@@ -147,7 +147,7 @@ spec = do
parseInfoDs "step = 10\nrra[0].cf = \"AVERAGE\"\n" `shouldBe` []
describe "schemaMatches" $ do
let ds name ty = DsSpec (T.pack name) name ty
let ds name = DsSpec (T.pack name) name
it "is true for identical schemas regardless of order" $
schemaMatches [ds "b" Gauge, ds "a" Derive] [("a", Derive), ("b", Gauge)]
`shouldBe` True
+2 -1
View File
@@ -36,7 +36,7 @@ instance Functor Acc where
fmap f (Acc g) = Acc $ \s -> let (a, s') = g s in (f a, s')
instance Applicative Acc where
pure a = Acc (\s -> (a, s))
pure a = Acc (a,)
Acc f <*> Acc x = Acc $ \s -> let (f', s') = f s; (a, s'') = x s' in (f' a, s'')
instance Monad Acc where
@@ -52,6 +52,7 @@ withTestLogEnv = bracket (initLogEnv "test" "test") closeScribes
-- | Interpret `HASSEff` in `Acc`: record `CallService`, drop tracing/debug.
interp :: HASSEff a -> Acc a
interp (CallService _ svc) = Acc $ \s -> ((), s ++ [svc])
interp (CallServices _ svc) = Acc $ \s -> ((), s ++ svc)
interp (Debug _) = pure ()
interp (Trace _ _) = pure ()