macontrol

https://github.com/amiwrpremium/macontrol/issues

tests_documented_added — macontrol evidence

The project documents the test-adding policy in multiple change-proposal-facing locations, satisfying this suggested criterion.

1. Pull Request template (.github/PULL_REQUEST_TEMPLATE.md)

GitHub auto-loads this template into every new PR's description box. It contains a "Test plan" section with the policy as an explicit checkbox the contributor must tick:

Test plan

• make lint test passes locally
• New/changed code has unit tests
• Verified on macOS (version / chip: … )
• If permissions changed: updated docs/permissions.md
• If new capability: added to README feature table

The "New/changed code has unit tests" line is the policy stated directly in the change-proposal interface — every contributor sees it the moment they open a PR.

2. CONTRIBUTING.md

The contributor workflow makes running tests a required pre-PR step:

3. Run checks locally before pushing:

     make lint test

The "Adding a new capability" section lists the required files for a new capability and step 6 explicitly mandates tests:

6. Write a domain test using the runner.Fake helper and a
   keyboard-layout test.

7. docs/development/adding-a-capability.md

A dedicated, full-length guide for change proposals that add new functionality. It treats tests as a structural requirement, not a suggestion:

• The file table at the top lists _test.go files alongside source files as required deliverables.
• Step 2 of every new capability is "Domain test", with a worked example covering both happy-path and error-path tests.
• Step 5 is "Test the handler".
• The guide notes that the worked example "Should pass with 100% coverage on the two test functions."

4. docs/development/testing.md

Documents the test infrastructure (runner.Fake, telegramtest.NewBot) so contributors know exactly how to satisfy the policy. The helpers needed to test any new domain or handler are pre-built and documented.

5. Conventional Commits

CONTRIBUTING.md lists test as a first-class commit type, signaling that test-only changes are an expected, encouraged contribution.

Summary: the test-adding policy is documented in the PR template (the most direct change-proposal surface), in CONTRIBUTING.md (the canonical contributor doc), and in two dedicated development guides (adding-a-capability.md and testing.md). A contributor cannot open a PR without seeing the "New/changed code has unit tests" checkbox in their PR body. This goes beyond the suggested bar.

warnings_strict — macontrol evidence

The project takes a maximally strict posture on warnings, well within the "where practical" qualifier of this suggested criterion.

1. Strict golangci-lint configuration (.golangci.yml)

issues:
max-issues-per-linter: 0
max-same-issues: 0

These two settings disable golangci-lint's default deduplication caps. By default golangci-lint shows only the first 50 findings per linter and the first 3 of each kind; setting both to 0 means every finding is surfaced. This is the strict-mode setting — the project wants to see all warnings, not a sampled summary.

2. Strict linter selection with default: none

linters:
default: none
enable: [errcheck, govet, ineffassign, staticcheck, unused, misspell,
gocritic, revive, bodyclose, nolintlint, unparam, prealloc, gosec]

default: none means no linters run unless explicitly enabled — so the active set is deliberate, not accidental. The 13 enabled linters include the strictest commonly-used ones:

• staticcheck (covers SA, ST, S, QF check categories — the gold-standard Go static analyser)
• gosec (security)
• gocritic (opinionated bug-pattern checks beyond go vet)
• revive with exported and package-comments rules explicitly enabled — these enforce godoc on every exported symbol and every package, a notably strict bar
• nolintlint (polices the suppressions themselves — stale or unjustified //nolint directives are themselves warnings)

3. Minimal, justified exclusions

The configuration suppresses almost nothing:

• One global exclusion: gosec G204 (subprocess invocation), with an inline comment explaining why ("Subprocess call is the whole point of this project"). Without this the entire project would be one giant warning, since shelling out to pmset/networksetup/osascript is its purpose.
• Test files exclude only gosec, unparam, gocritic — the standard Go pattern, since these produce noise on test scaffolding and assertion helpers.
• generated: lax — generated files are excluded from lint, the standard convention.

There are no broad path exclusions, no per-linter rule disables, no severity downgrades. The configuration is roughly 50 lines and contains nothing that softens the rules.

4. Strict bars layered on top of golangci-lint

• govulncheck runs in CI as a separate vuln job — any known-vulnerable dependency or stdlib usage fails the build.
• CodeQL (.github/workflows/codeql.yml) — semantic analysis on every push.
• OpenSSF Scorecard (.github/workflows/scorecards.yml) — supply-chain best-practice scoring published publicly.
• Codacy + Codecov dashboards — third-party static analysis with public badges.
• gofumpt (stricter than gofmt) and goimports (with local-prefix grouping enforced) run as formatters — formatting drift is a CI failure.
• A 30-second fuzz test (FuzzDecode) runs on every PR.
• Race detector enabled in CI tests: go test -race.

5. Strict bar raised over time, not lowered

The history shows the project tightening, not loosening, its strictness:

d0b3eaf docs: comprehensive godoc for all production code + enable strict lint (#77)
c4474e8 docs: thorough godoc rewrite with structured sections (#78)
caa55d6 fix(ci): resolve 50 golangci-lint v2 findings

The "enable strict lint" commit turned on revive's exported and package-comments rules and then brought the entire codebase into compliance — the opposite of the anti-pattern of relaxing rules to make warnings disappear.

6. Evidence the strict bar is held in practice

A repo-wide grep finds only 3 //nolint directives across the codebase. Each is single-line, names the specific linter being suppressed, and carries an inline justification. nolintlint enforces this format. Three narrow, justified suppressions across ~96 production .go files is a notably tight ratio.

The macOS-target build is also configured strictly:

GOFLAGS ?= -trimpath
LDFLAGS ?= -s -w …
CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" …

-trimpath removes filesystem path leakage, and -s -w strips debug info from release binaries.

7. Practical limits, honestly handled

The "where practical" qualifier matters here. macontrol is a subprocess-orchestration daemon; gosec G204 (subprocess with non-constant input) cannot be globally satisfied because the project's purpose is to run macOS CLIs. The maintainer suppresses G204 globally with a documented justification rather than littering the code with per-call suppressions or pretending it's not an issue. That's the right kind of pragmatic strictness — strict everywhere it's practical, explicitly bounded where it isn't.

Summary: the project enables 13 linters with default: none, sets max-issues caps to 0 to surface every finding, enforces godoc on every exported symbol via revive, layers govulncheck + CodeQL + Scorecard + Codacy on top, uses gofumpt (stricter than gofmt), runs tests with -race, fuzzes the highest-risk parser, and has a documented history of raising the bar (enable strict lint → fix the resulting 50 findings) rather than lowering it. Only 3 narrowly justified //nolint suppressions exist in the entire codebase. The criterion is satisfied at the strong end of the spectrum.

static_analysis_common_vulnerabilities — macontrol evidence

Several of the static-analysis tools used target common vulnerabilities directly:

• gosec (enabled in .golangci.yml) — Go security checker covering subprocess use (G204), file-permission laxity (G302/G306), insecure tempfile creation, weak crypto, integer overflow, path traversal (G304), TLS misconfig, and SQL injection patterns.
• govulncheck — checks reachable code paths against the official Go vulnerability database (vuln.go.dev), covering both stdlib and dependencies.
• CodeQL — semantic vulnerability detection (taint flow, injection, unsafe deserialisation, etc.) using GitHub's vulnerability query packs.
• OpenSSF Scorecard — supply-chain vulnerability checks (vulnerable deps, pinned dependencies, signed releases, branch protection).
• staticcheck — includes the SA category which catches correctness bugs that frequently underlie vulnerabilities (deprecated API use, unsafe type assertions, ignored errors).

Evidence the vulnerability-focused rules fire and get acted on: commit caa55d6 ("resolve 50 golangci-lint v2 findings") explicitly itemises 5 gosec security findings fixed (file modes 0o755 → 0o750, plist 0o644 → 0o600, trusted-path file opens annotated). The criterion is satisfied.

dynamic_analysis_unsafe — macontrol evidence

N/A.

macontrol is written entirely in Go, a memory-safe language with garbage collection, bounds-checked slices, no pointer arithmetic, and runtime nil-check enforcement. The build sets CGO_ENABLED=0, so no C/C++ code is linked into the binary. There is no memory-unsafe code in the project to apply this criterion to.

(For completeness: the project does run the Go race detector via go test -race on every push/PR and a Go native fuzzer on the callback parser — but the criterion does not apply because the language is memory-safe.)