diff --git a/README.md b/README.md index 6bac2dd..d334a68 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ -# pdsuite +# PDSuite A compliance checker for AT Protocol Personal Data Servers (PDS). -You point pdsuite at a PDS. It runs a set of checks against the server and prints a report. Each check says if the server follows the AT Protocol specification, the lexicon contracts, or the behavior of the reference implementation. +You point PDSuite at a PDS. It runs a set of checks against the server and prints a report. Each check says if the server follows the AT Protocol specification, the lexicon contracts, or the behavior of the reference implementation. The tool is a command-line program. It is also a library, so you can run it in CI. @@ -114,7 +114,7 @@ The stack pulls the prebuilt tranquil-pds image from `atcr.io`, which needs a on docker-credential-atcr login # one-time, device flow docker pull atcr.io/tranquil.farm/tranquil-pds:latest -# Build the mock PLC image and bring up the stack (from the pdsuite repo root) +# Build the mock PLC image and bring up the stack (from the PDSuite repo root) docker compose -f docker/docker-compose.local.yaml up -d --build # Run the full suite against it (handles use the stack's .devpds.com domain) diff --git a/docker/docker-compose.local.yaml b/docker/docker-compose.local.yaml index 71e66dd..f512f81 100644 --- a/docker/docker-compose.local.yaml +++ b/docker/docker-compose.local.yaml @@ -1,6 +1,6 @@ -# Minimal local tranquil-pds stack for pdsuite conformance testing — self-contained. +# Minimal local tranquil-pds stack for PDSuite conformance testing — self-contained. # postgres + mock-PLC + tranquil-pds, all containerized so docker manages the lifecycles. -# A throwaway localhost target you own, for running pdsuite against a real third-party PDS. +# A throwaway localhost target you own, for running PDSuite against a real third-party PDS. # No traefik, mailpit, frontend, or production TLS. # # SSRF note: tranquil-pds's PLC client uses a ReachPolicy guard that in a release build only @@ -55,7 +55,7 @@ services: plc: build: - # Build context is the pdsuite repo root (this file lives in docker/). + # Build context is the PDSuite repo root (this file lives in docker/). context: .. dockerfile: docker/Dockerfile.mock-plc # Share the PDS container's network namespace so tranquil-pds reaches the PLC at diff --git a/docs/design-rationale.md b/docs/design-rationale.md index 053b63c..f68f7ef 100644 --- a/docs/design-rationale.md +++ b/docs/design-rationale.md @@ -1,6 +1,6 @@ # Design rationale -Why pdsuite is built the way it is. This document explains the load-bearing +Why PDSuite is built the way it is. This document explains the load-bearing decisions. For the mechanics of writing a check, see [writing-a-check.md](writing-a-check.md). @@ -19,7 +19,7 @@ Bluesky's deployment. So a conformance tool that pretends the spec is complete would produce false accusations. Flip it around and you get the opposite failure: a tool that only -diffs against the reference ratifies every reference bug as "correct." pdsuite +diffs against the reference ratifies every reference bug as "correct." PDSuite does neither. ## Three sources of authority @@ -125,7 +125,7 @@ These are deliberate exclusions, not oversights: - **Not a fuzzer.** Checks are targeted assertions, not generative adversarial input. - **Not a relay checker.** The sync spec's consumer-side validation checklist - is a different product. pdsuite borrows consumer rules only as producer-side + is a different product. PDSuite borrows consumer rules only as producer-side expectations. - **Not a benchmark.** Timing is recorded as metadata, never asserted. - **Not a hosted badge service.** The JSON report is the output contract. diff --git a/docs/interop-traps.md b/docs/interop-traps.md index eb57a1b..50c8426 100644 --- a/docs/interop-traps.md +++ b/docs/interop-traps.md @@ -1,7 +1,7 @@ # Interop traps This document lists the undocumented behaviors that a PDS must get right to -federate. The pdsuite harness had to learn each one to test it. Each entry says +federate. The PDSuite harness had to learn each one to test it. Each entry says what the trap is, where it was found, and what a check or the harness must do about it. diff --git a/docs/spec-gaps.md b/docs/spec-gaps.md index 0711a2d..631f15b 100644 --- a/docs/spec-gaps.md +++ b/docs/spec-gaps.md @@ -3,7 +3,7 @@ The AT Protocol specification (atproto.com) is a living git repository. It has no versioned releases and no formal stability guarantee. It contains explicit gaps, ambiguities, and work-in-progress markers. This document lists the gaps -that limit what a check can assert, and says how pdsuite handles each one. +that limit what a check can assert, and says how PDSuite handles each one. Read this document before you write a check with `authority: 'spec'`. If the behavior you are testing is listed here, the spec does not support a hard @@ -154,7 +154,7 @@ never as `must`. additively: new fields are optional, with no renames and no removals. A breaking change means a new NSID. - **Lexicon content is not versioned.** The canonical `com.atproto.*` JSON - files change frequently. pdsuite pins a monorepo commit (`atproto@` in + files change frequently. PDSuite pins a monorepo commit (`atproto@` in `src/generate.ts`). The pin is the lexicon version. When you bump the pin and regenerate, protocol drift shows as a diff on `src/generated/`. - **Sync 1.1** is a named, staged rollout: `#sync` events, `prevData`, diff --git a/docs/target-notes.md b/docs/target-notes.md index 6d8b8b0..f414b7b 100644 --- a/docs/target-notes.md +++ b/docs/target-notes.md @@ -1,7 +1,7 @@ # Target notes This document holds per-implementation behavioral notes for the PDSes that -pdsuite has run against or studied. These notes exist to seed and source +PDSuite has run against or studied. These notes exist to seed and source the target profiles (`src/profiles/`). Each deliberate divergence listed here must eventually become a profile entry, co-owned with the maintainers of the implementation, with a note and a link to their documentation. @@ -80,7 +80,7 @@ No profile yet. - Several shared endpoints accept fewer parameters than the reference: no `repo` param on some writes, no `swapCommit`/`swapRecord`, no `since` on `sync.getRepo`/`listBlobs`. Their own `docs/endpoint-comparison.md` - tabulates this. It is the kind of document that the pdsuite inventory and + tabulates this. It is the kind of document that the PDSuite inventory and contract checks automate. **Documented deviations with reasons:** @@ -92,7 +92,7 @@ No profile yet. behavior of the reference. Without it, a refresh whose response is lost strands the client. -**Interop scars (now encoded as pdsuite checks or traps):** +**Interop scars (now encoded as PDSuite checks or traps):** - High-S signature rejection (see [interop-traps.md](interop-traps.md)). Discovered through failed federation, invisible in the spec. diff --git a/docs/writing-a-check.md b/docs/writing-a-check.md index 623c5a5..a8146ba 100644 --- a/docs/writing-a-check.md +++ b/docs/writing-a-check.md @@ -2,7 +2,7 @@ Read this guide before you open a pull request that adds or changes a check. -A check is the unit of work in pdsuite. It is a small program that does three things: +A check is the unit of work in PDSuite. It is a small program that does three things: 1. It sets up what it needs. 2. It interacts with the target PDS. diff --git a/src/cli.ts b/src/cli.ts index 94f6320..1277679 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -1,4 +1,4 @@ -// pdsuite CLI +// PDSuite CLI // pnpm check [--mode readonly|mutate] [--json] [--only prefix...] [--profile name] import { tier0Checks } from './checks/tier0.js' import { tier2Checks } from './checks/tier2.js' diff --git a/src/oracle/smoke.ts b/src/oracle/smoke.ts index 83c3961..1eb4701 100644 --- a/src/oracle/smoke.ts +++ b/src/oracle/smoke.ts @@ -23,7 +23,7 @@ await agent.login({ identifier: 'alice.test', password: 'hunter2hunter2' }) await agent.com.atproto.repo.createRecord({ repo: account.data.did, collection: 'app.bsky.feed.post', - record: { $type: 'app.bsky.feed.post', text: 'hello from pdsuite spike', createdAt: new Date().toISOString() }, + record: { $type: 'app.bsky.feed.post', text: 'hello from PDSuite spike', createdAt: new Date().toISOString() }, }) console.log('record written') diff --git a/src/report.ts b/src/report.ts index 94b2754..4176d4b 100644 --- a/src/report.ts +++ b/src/report.ts @@ -31,7 +31,7 @@ export function reportTerminal(checks: Check[], results: CheckResult[], target: const { dim, bold, red, yellow, green, cyan, reset } = COLORS const byId = new Map(checks.map((c) => [c.id, c])) const lines: string[] = [] - lines.push(`${bold}pdsuite report — ${target}${reset}`) + lines.push(`${bold}PDSuite report — ${target}${reset}`) lines.push('') const tiers = [...new Set(checks.map((c) => c.tier))].sort() diff --git a/src/types.ts b/src/types.ts index 2ae31c4..f834228 100644 --- a/src/types.ts +++ b/src/types.ts @@ -1,4 +1,4 @@ -// Core type system for pdsuite checks. +// Core type system for PDSuite checks. // The design contract lives in research/07-check-registry-format.md. export type Authority = 'spec' | 'lexicon' | 'interop' | 'reference'