Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,18 @@ commands, or moved skill-reference paths.

### Added

- **"Must not" rules per folder** (#116). `map` surveys which frameworks
each folder uses (new tested script `folder-imports.sh`), suggests 3–6
rules such as "Models must not import SwiftUI" or "only Payments/ uses
StoreKit", each marked true today or broken in N files, and asks which
to keep. Each kept rule becomes a SwiftLint rule or a fitness test,
proven to pass on the real code and fail on a planted break in a
throwaway copy. Files that already break it are listed as known
exceptions, a list that only shrinks. CODEBASE.md gets a Folder Rules
table; build agents follow it, and `review` flags new breaks and any
growth in the exceptions. `expect-red.sh` gains `--no-build-check` for
lint commands.

- **One-page review guide per phase** (#113). `verify` writes
`.planning/REVIEW-GUIDE.md` (new template) in plain English: what changed,
the choices agents made and what they rejected, the proof (promised
Expand Down
3 changes: 2 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -217,7 +217,8 @@ Some commands can act directly on an external service (push App Store metadata v
- `debt-measure.sh`, `baseline-refresh.sh` (`debt`)
- `design-pin.sh` (`plan`)
- `design-compare.sh` (`verify`)
- `expect-red.sh` (`build`, `verify`): runs tests in a throwaway git worktree with new tests copied in, or a planted bug swapped in, and reports whether they went red (#111)
- `folder-imports.sh` (`map`): which frameworks each folder uses, for suggesting folder rules (#116)
- `expect-red.sh` (`build`, `verify`, `map`): runs tests in a throwaway git worktree with new tests copied in, or a planted bug swapped in, and reports whether they went red (#111)

Logic that must give the same answer every run lives here, not pasted into command text (#112). Each script is tested against fixture projects in `tests/fixtures/` by `scripts/test-scripts.sh`, which `validate.sh` runs. A fake `swiftlint` stands in, so CI needs no Xcode. When adding a script, add a fixture test and prove it fails on a planted bug.

Expand Down
9 changes: 9 additions & 0 deletions commands/build.md
Original file line number Diff line number Diff line change
Expand Up @@ -251,6 +251,11 @@ Task({
[Contents of .planning/UTILITIES.md if it exists. Omit if none.]
</existing-helpers>

<folder-rules>
[The "## Folder Rules" table from .planning/CODEBASE.md, if it has
one. Omit otherwise.]
</folder-rules>

<design-system>
[UI tasks only, when the project has one: the token map, text styles
and component list from .planning/DESIGN-SYSTEM.md. Omit otherwise.]
Expand All @@ -273,6 +278,10 @@ Task({
components (states through ContentStateView), accessibilityIdentifier
on interactive elements, view files under ~300 lines. A missing token
goes into the token file and is reported, never inlined.
7. If <folder-rules> is present: put code in the folder whose rules
allow it, and never add a file to a rule's known exceptions. If the
task can't be done without breaking a rule, stop and report it
instead of working around it.

After completing, report:
- Files created/modified
Expand Down
93 changes: 92 additions & 1 deletion commands/map.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
description: Analyze existing codebase before adding SwiftShip workflow
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion
---

# Map Existing Codebase
Expand Down Expand Up @@ -203,6 +203,16 @@ Create `.planning/CODEBASE.md`:
[Directory tree]
```

## Folder Rules

What each folder is for, and the lines it must not cross (Step 5.7).
Known exceptions are files that broke the rule before it existed; the list
only shrinks.

| Folder | For | Must not | Enforced by | Known exceptions |
|--------|-----|----------|-------------|------------------|
| [App/Views/] | [screens] | [use CloudKit, StoreKit or URLSession directly] | [SwiftLint `folder_views_no_data` / FolderRuleTests / not enforced] | [none / 2 files] |

## Architecture

**Pattern:** [Detected: MVVM / MVC / TCA / Mixed]
Expand Down Expand Up @@ -329,6 +339,86 @@ using the **real** directories/files as globs (prefer a directory glob over
listing every file). 3–5 rows at most; no hits → skip the file. If the file
already exists, add only new areas — never remove or rewrite the user's rows.

## Step 5.7: Folder Rules ("must not")

Agents copy whatever patterns they see and put code wherever it works.
CODEBASE.md says what each folder holds; this step adds the lines a folder
must not cross ("Views must not talk to CloudKit", "Models must not import
SwiftUI", "only Payments/ uses StoreKit"), and turns each one you keep into
a check that fails when it's broken.

**1. Survey** which frameworks each folder uses:
```bash
bash ~/.claude/swiftship-templates/_scripts/folder-imports.sh # folder <tab> framework <tab> files
bash ~/.claude/swiftship-templates/_scripts/folder-imports.sh --files CloudKit # which files use one
```
Names starting `api:` are direct calls (`api:URLSession`,
`api:CKContainer`, `api:Product.purchase`) that need no import of their
own. If the script is missing, SwiftShip is out of date: tell the user to
update it (`claude plugin update apple@indie-apple-stack`, or `git pull`
for a manual install), and skip this step.

**2. Suggest 3–6 rules** the survey supports. Common shapes:
- a views folder (`Views/`, `Screens/`, `Features/*/Views`) must not use
CloudKit, StoreKit or networking directly (data goes through a service or store)
- a models folder must not import SwiftUI, UIKit or AppKit
- only one folder uses StoreKit / CloudKit / `URLSession` (pick the folder
that holds most of it today)

For each, say whether it's **true today** or **broken in N files** (list
them with `--files`). Don't suggest a rule broken in most of the files it
covers: that's how the app is built, not an exception. No folder structure
to speak of (everything in one folder) → skip this step and say so.

**3. Ask once** (`AskUserQuestion`, multiSelect) which rules to keep, each
with its plain status ("true today" / "broken in 3 files; they'd be listed
as known exceptions"). Nothing chosen → skip to step 5 and write the table
with "not enforced".

**4. Turn each kept rule into a check**, the way `/apple:learn` does
(its "For Enforcement" section):
- **One folder, one framework** → a SwiftLint custom rule in `.swiftlint.yml`:
```yaml
custom_rules:
folder_models_no_ui: # folder rule: Models must not import SwiftUI
name: "Models must not import SwiftUI"
regex: '^\s*(@\w+\s+)*import\s+(SwiftUI|UIKit|AppKit)\b'
included: ["App/Models/"]
excluded: ["App/Models/Legacy Note\\.swift"] # known exceptions; this list only shrinks
message: "Models stay UI-free; put view code in Views/."
severity: error
```
For a direct-call rule, match the call (`URLSession`, `CKContainer`) too.
- **"Only X may use Y"** → a fitness-function test (import-boundary
allowlist plus API scan) in the app's test target:
```
Read: ~/.claude/swiftship-skills/testing/fitness-functions/SKILL.md
```
The allowlist is folder X plus the known exceptions.
- **Known exceptions:** files that break the rule today are listed in the
rule itself (`excluded:` or the allowlist), each with a comment that the
list only shrinks. The rule then passes today and fails on any new break.
- **Prove each check**, without touching the user's files:
- *Passes on the real code:* `swiftlint lint --strict --quiet`, or the
fitness test by name.
- *Fails on a new break:* plant the forbidden import in a file inside
the folder, in a throwaway copy, with the new rule copied in:
```bash
bash ~/.claude/swiftship-templates/_scripts/expect-red.sh --no-build-check \
--copy .swiftlint.yml --swap "<a file in the folder>" 'import Foundation' $'import Foundation\nimport CloudKit' \
-- swiftlint lint --strict --quiet
```
(For a fitness test: `--copy` the test file, drop `--no-build-check`,
and run the test by name.) `RED` = proven. Anything else: fix the rule
and try again; still not red → don't install it, and mark the rule
"not enforced (check didn't work)".
- No SwiftLint and no test target → keep the rule in the table as "not
enforced yet" and suggest `/apple:test` to set up a test target.

**5. Write the table** into CODEBASE.md's `## Folder Rules` section (see
Step 5's template): one row per folder that has a purpose worth stating,
with the rules kept. Build agents and `/apple:review` read this table.

## Step 6: Vendor Agents (optional, recommended for cloud/remote work)

Apply `~/.claude/swiftship-templates/_conventions/AGENT-VENDORING.md`: offer to
Expand Down Expand Up @@ -365,6 +455,7 @@ Codebase mapped!
Created: .planning/CODEBASE.md
.planning/UTILITIES.md ([N] shared helpers agents will reuse — or "none found")
.planning/CRITICAL.md ([areas] — /apple:build pauses for review on these — or "none found")
Folder rules: [n] kept, [n] enforced by a check ([n] known exceptions) — or "none"

Summary:
- [X] Swift files found
Expand Down
6 changes: 6 additions & 0 deletions commands/review.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ Read: .planning/APP.md (if exists)
Read: .planning/ROADMAP.md (if exists)
Read: .planning/STATE.md (if exists)
Read: .planning/UTILITIES.md (if exists — pass to Agent 1 for the reimplemented-helper check)
Read: .planning/CODEBASE.md (if exists — pass its "## Folder Rules" table to Agent 1)
```

## Lint Baseline (pre-pass)
Expand Down Expand Up @@ -174,6 +175,11 @@ Task({
client) — cite both the duplicate and the helper it should use.
Shared helpers missing from UTILITIES.md: note them as a Low
finding ("add to inventory") so agents learn to reuse them
- **Folder rules:** if CODEBASE.md has a "Folder Rules" table, flag
any changed file that breaks a "must not" (High: cite the file,
line and rule), and any rule whose known-exceptions list grew
(`git diff` of the rule's `excluded:` or allowlist; High: the
list may only shrink). A shrunk list is good news; say so.

9. **Design System (restyle cost)**: rules from
~/.claude/swiftship-skills/design/design-system/SKILL.md
Expand Down
18 changes: 18 additions & 0 deletions scripts/test-scripts.sh
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,22 @@ expect "design-compare: added" "$out" "added Onboarding.png"
expect "design-compare: changed (name with spaces)" "$out" "changed Profile Edit.png"
expect "design-compare: removed" "$out" "removed Settings.png"

# --- folder-imports.sh (#116) ---------------------------------------------------
out=$(cd "$APP" && bash "$SCRIPTS/folder-imports.sh" 2>&1)
expect "folder-imports: models folder importing SwiftUI is seen" "$out" "App/Models SwiftUI 1"
expect "folder-imports: folder with spaces keeps its name" "$out" "Watch App/Views CloudKit 1"
expect "folder-imports: @preconcurrency import counted" "$out" "App/Services CloudKit 1"
expect "folder-imports: 'import struct Foundation.URL' is Foundation" "$out" "App/Services Foundation 1"
expect "folder-imports: direct API use without its own import" "$out" "App/Services api:URLSession 1"
printf '%s' "$out" | grep -q "App/Models api:URLSession" && bad "folder-imports: an API named in a comment was counted" || ok "folder-imports: API named in a comment ignored"
printf '%s' "$out" | grep -q "StoreKit" && bad "folder-imports: a commented-out import was counted" || ok "folder-imports: commented-out import ignored"
printf '%s' "$out" | grep -q "AppTests" && bad "folder-imports: test folder included" || ok "folder-imports: test folders skipped"
out=$(cd "$APP" && bash "$SCRIPTS/folder-imports.sh" --files CloudKit 2>&1)
[ "$out" = "$(printf 'App/Services/Sync Service.swift\nWatch App/Views/Home View.swift')" ] && ok "folder-imports --files: exact file list, spaces kept" || bad "folder-imports --files: got: $out"
printf 'import SwiftUI\n' > "$APP/App/Views/Draft.swift"
expect "folder-imports: new uncommitted files included" "$(cd "$APP" && bash "$SCRIPTS/folder-imports.sh")" "App/Views SwiftUI 2"
rm "$APP/App/Views/Draft.swift"

# --- expect-red.sh (#111) --------------------------------------------------------
R="$WORK/red"; mkdir -p "$R/tests"
( cd "$R" && git init -q && git config user.email t@t && git config user.name t \
Expand Down Expand Up @@ -120,6 +136,8 @@ out=$(cd "$R" && bash "$SCRIPTS/expect-red.sh" --swap calc.sh 'echo' 'true' -- b
[ $rc = 2 ] && ok "expect-red: --swap text found twice is refused" || bad "expect-red: ambiguous --swap wanted exit 2, got $rc: $out"
out=$(cd "$R" && bash "$SCRIPTS/expect-red.sh" -- sh -c 'echo "/x/Foo.swift:3:5: error: cannot find Bar in scope"; exit 1'); rc=$?
[ $rc = 3 ] && ok "expect-red: compile error is NO-BUILD, not red" || bad "expect-red: compile error wanted exit 3, got $rc: $out"
out=$(cd "$R" && bash "$SCRIPTS/expect-red.sh" --no-build-check -- sh -c 'echo "/x/Note.swift:2:1: error: Models must not import SwiftUI (folder_rule)"; exit 2'); rc=$?
[ $rc = 0 ] && ok "expect-red: --no-build-check reads a lint break as red" || bad "expect-red: lint break wanted exit 0, got $rc: $out"
out=$(cd "$R" && bash "$SCRIPTS/expect-red.sh" -- sh -c 'echo "/x/FooTests.swift:12: error: -[FooTests testA] : XCTAssertEqual failed"; exit 1'); rc=$?
[ $rc = 0 ] && ok "expect-red: failed assertion is red" || bad "expect-red: assertion failure wanted exit 0, got $rc: $out"
out=$(cd "$R" && bash "$SCRIPTS/expect-red.sh" -- sh -c 'echo "Executed 0 tests, with 0 failures"; exit 0'); rc=$?
Expand Down
8 changes: 6 additions & 2 deletions templates/_scripts/expect-red.sh
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,9 @@
# in the copy, replace the exact text OLD (must occur once)
# with NEW (verify: a planted bug, run against the finished code)
# --patch FILE apply this diff to the copy first (same use as --swap)
# --no-build-check
# the command isn't a compiler (e.g. swiftlint, whose rule
# breaks look like compiler errors): any failure is RED
# Run from the project root. The copy is removed afterwards, whatever happens.
#
# Prints one line and exits:
Expand All @@ -18,14 +21,15 @@
# 3 NO-BUILD code didn't compile (fine for a brand-new type in build;
# a planted bug must compile, so pick another in verify)
set -u
ref=HEAD; patch=""; log=""; copies=(); swaps=()
ref=HEAD; patch=""; log=""; copies=(); swaps=(); buildcheck=1
while [ $# -gt 0 ]; do
case "$1" in
--at) ref="$2"; shift 2 ;;
--copy) copies+=("$2"); shift 2 ;;
--swap) [ $# -ge 4 ] || { echo "SETUP: --swap needs PATH OLD NEW"; exit 2; }; swaps+=("$2" "$3" "$4"); shift 4 ;;
--patch) patch="$2"; shift 2 ;;
--log) log="$2"; shift 2 ;;
--no-build-check) buildcheck=0; shift ;;
--) shift; break ;;
*) echo "usage: expect-red.sh [--at REF] [--copy PATH]... [--swap PATH OLD NEW] [--patch FILE] [--log FILE] -- TEST-COMMAND..." >&2; exit 2 ;;
esac
Expand Down Expand Up @@ -64,7 +68,7 @@ done
code=$?

# A compiler error has file:line:column; a failed XCTest assertion has only file:line.
if grep -qE '\*\* BUILD FAILED \*\*|\.swift:[0-9]+:[0-9]+: error:|error: compile command failed' "$log"; then
if [ "$buildcheck" = 1 ] && grep -qE '\*\* BUILD FAILED \*\*|\.swift:[0-9]+:[0-9]+: error:|error: compile command failed' "$log"; then
echo "NO-BUILD (log: $log)"; exit 3
fi
if grep -qE 'Executed 0 tests|0 tests in 0 suites|No matching test cases' "$log"; then
Expand Down
53 changes: 53 additions & 0 deletions templates/_scripts/folder-imports.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
#!/bin/bash
# folder-imports.sh → which frameworks each folder uses
# folder-imports.sh --files X → the files that use X
#
# Used by /apple:map to suggest "must not" folder rules (#116). Run from the
# project root. Shipping code only: test folders, Pods, .build, DerivedData
# and generated code are skipped.
#
# Table output, one line per folder and framework, tab-separated:
# folder name files
# name is an imported module (SwiftUI, CloudKit, StoreKit, …) or a direct API
# use that needs no import of its own: api:URLSession, api:CKContainer,
# api:CKDatabase, api:Product.purchase, api:AppStore.sync. Commented-out
# lines don't count. Files at the root are folder ".".
set -u
mode=table; want=""
if [ "${1:-}" = "--files" ]; then
[ $# -eq 2 ] || { echo "usage: folder-imports.sh [--files NAME]" >&2; exit 2; }
mode=files; want="$2"
fi

if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
git -c core.quotepath=off ls-files --cached --others --exclude-standard -- '*.swift' | sort -u
else
find . -name '*.swift' -type f | sed 's|^\./||'
fi | grep -vE '(^|/)[^/]*Tests?/|(^|/)(Pods|\.build|DerivedData|Generated|build)/' > "${TMPDIR:-/tmp}/fi.$$"

while IFS= read -r f; do
[ -f "$f" ] || continue
d=$(dirname "$f")
awk -v d="$d" -v f="$f" '
/^[[:space:]]*\/\// { next }
/^[[:space:]]*(@[A-Za-z_]+[[:space:]]+)*import[[:space:]]/ {
s = $0
sub(/^[[:space:]]*(@[A-Za-z_]+[[:space:]]+)*import[[:space:]]+/, "", s)
if (s ~ /^(struct|class|enum|protocol|typealias|func|var|let)[[:space:]]/) sub(/^[a-z]+[[:space:]]+/, "", s)
split(s, a, /[.[:space:]]/); seen[a[1]] = 1
}
/URLSession/ { seen["api:URLSession"] = 1 }
/CKContainer/ { seen["api:CKContainer"] = 1 }
/CKDatabase/ { seen["api:CKDatabase"] = 1 }
/Product[^ ]*\.purchase|\.purchase\(/ { seen["api:Product.purchase"] = 1 }
/AppStore\.sync/ { seen["api:AppStore.sync"] = 1 }
END { for (n in seen) print d "\t" n "\t" f }
' "$f"
done < "${TMPDIR:-/tmp}/fi.$$" > "${TMPDIR:-/tmp}/fi.$$.out"

if [ "$mode" = files ]; then
awk -F'\t' -v w="$want" '$2 == w { print $3 }' "${TMPDIR:-/tmp}/fi.$$.out" | sort
else
awk -F'\t' '{ c[$1 "\t" $2]++ } END { for (k in c) print k "\t" c[k] }' "${TMPDIR:-/tmp}/fi.$$.out" | sort
fi
rm -f "${TMPDIR:-/tmp}/fi.$$" "${TMPDIR:-/tmp}/fi.$$.out"
7 changes: 7 additions & 0 deletions tests/fixtures/app/App/Models/Note.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
import Foundation
import SwiftUI

// Models never call URLSession: the sync service does (a comment, never counted)
struct Note {
var title: String
}
8 changes: 8 additions & 0 deletions tests/fixtures/app/App/Services/Sync Service.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
// import StoreKit is not allowed here (a comment, never counted)
@preconcurrency import CloudKit
import struct Foundation.URL

final class SyncService {
let container = CKContainer.default()
func fetch() async throws { _ = try await URLSession.shared.data(from: URL(string: "https://example.com")!) }
}
1 change: 1 addition & 0 deletions tests/fixtures/app/Watch App/Views/Home View.swift
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import SwiftUI
import CloudKit

struct HomeView: View {
var body: some View {
Expand Down
Loading