If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/robb/Cartography shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Slowing — last commit 8mo ago

• Last commit 8mo ago
• 23+ active contributors
• Distributed ownership (top contributor 34% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 8mo ago
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live robb/Cartography repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/robb/Cartography.

What it runs against: a local clone of robb/Cartography — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in robb/Cartography | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 277 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of robb/Cartography. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/robb/Cartography.git
#   cd Cartography
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of robb/Cartography and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "robb/Cartography(\\.git)?\\b" \\
  && ok "origin remote is robb/Cartography" \\
  || miss "origin remote is not robb/Cartography (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Cartography/Constrain.swift" \\
  && ok "Cartography/Constrain.swift" \\
  || miss "missing critical file: Cartography/Constrain.swift"
test -f "Cartography/LayoutProxy.swift" \\
  && ok "Cartography/LayoutProxy.swift" \\
  || miss "missing critical file: Cartography/LayoutProxy.swift"
test -f "Cartography/Constraint.swift" \\
  && ok "Cartography/Constraint.swift" \\
  || miss "missing critical file: Cartography/Constraint.swift"
test -f "Cartography/Expression.swift" \\
  && ok "Cartography/Expression.swift" \\
  || miss "missing critical file: Cartography/Expression.swift"
test -f "Cartography/ConstraintGroup.swift" \\
  && ok "Cartography/ConstraintGroup.swift" \\
  || miss "missing critical file: Cartography/ConstraintGroup.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 277 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~247d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/robb/Cartography"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Cartography is a Swift DSL that replaces verbose NSLayoutConstraint boilerplate with a declarative, operator-overloaded syntax for Auto Layout. Instead of creating constraint objects manually, you write button1.right == button2.left - 12 inside a constrain() closure, and the library automatically activates the constraints and sets translatesAutoresizingMaskIntoConstraints = false. Single-package library: Cartography/ contains the core DSL engine split into logical concerns (LayoutProxy.swift handles view attribute proxying, Constraint.swift models individual constraints, Constrain.swift exports the main API, Expression.swift handles arithmetic). CartographyTests/ mirrors the source with spec files for each module. LayoutItem.swift, ViewProxy.swift, and LayoutGuideProxy.swift provide type-erasure layers to support UIView, NSView, UILayoutGuide, and safe area anchors.

iOS/macOS/tvOS developers building native UIs with Auto Layout who want cleaner, more readable constraint code without stringly-typed attribute names. Particularly useful for teams avoiding SwiftUI but wanting modern declarative constraint syntax.

Actively maintained and production-ready. The repo shows Swift 137K LOC dominance, has CI via Travis (visible in .travis.yml), CocoaPods/Carthage distribution set up, and comprehensive test coverage (CartographyTests/ with 8+ spec files). Latest activity not explicitly shown in file list, but the mature structure and complete feature set suggest stable, battle-tested code.

Single-maintainer project (robb/) with no visible dependency management file (no Package.swift or Podfile.lock in top 60 files), making it harder to assess transitive risks. No open issue/PR visibility in provided data. The iOS Auto Layout API surface is stable, so breaking changes are unlikely, but lack of recent activity indicators should be verified before adopting for new greenfield projects.

No recent commit/PR data visible in file list. Project appears mature and stable rather than actively developed. Integration with layout guides (LayoutGuide.swift, LayoutGuideProxy.swift, LayoutGuideSpec.swift) suggests recent work on supporting iOS safe areas and layout anchors beyond basic UIView constraints.

git clone https://github.com/robb/Cartography.git
cd Cartography
pod install
open Cartography.xcworkspace

Then open Cartography-iOS.xcscheme from Cartography.xcodeproj/xcshareddata/xcschemes/ and build in Xcode.

Daily commands: Open Cartography.xcworkspace in Xcode and build the Cartography-iOS, Cartography-Mac, or Cartography-tvOS scheme (defined in xcschemes/). No CLI; this is a framework library integrated via CocoaPods or Carthage into client projects.

• Cartography/Constrain.swift — Entry point for the DSL — defines the constrain() function that wraps Auto Layout constraint creation into a declarative closure-based API
• Cartography/LayoutProxy.swift — Core abstraction that provides chainable property accessors (left, right, top, bottom, width, height) enabling the declarative syntax
• Cartography/Constraint.swift — Represents a single constraint equation; converts DSL expressions (e.g., button1.right == button2.left - 12) into native NSLayoutConstraints
• Cartography/Expression.swift — Implements operator overloading (==, <=, >=, *, +, -) to parse constraint expressions into symbolic form before materialization
• Cartography/ConstraintGroup.swift — Manages a set of constraints as a group; enables activation, deactivation, and cleanup of related constraints
• Cartography/ViewProxy.swift — Type-erased proxy for UIView/NSView that bridges the declarative DSL to the underlying LayoutItem protocol
• Cartography/Align.swift — Convenience DSL function for common alignment patterns (e.g., aligning multiple views vertically or horizontally)

Add support for a new layout attribute

1. Define the new attribute in LayoutProxy protocol (e.g., a derived property like diagonal) (Cartography/LayoutProxy.swift)
2. Implement the property in ViewProxy, LayoutGuideProxy, and LayoutSupportProxy (Cartography/ViewProxy.swift)
3. Add expression overloading in Extension.swift if the attribute needs special operators (Cartography/Extensions.swift)
4. Write tests in a new *Spec.swift file or add to EdgeSpec.swift (CartographyTests/EdgeSpec.swift)

Add a new compound constraint helper function

1. Create a public function (e.g., func constrain(...) { ... }) in Compound.swift or a new file (Cartography/Compound.swift)
2. Use the closure pattern to accept a proxy and build multiple constraints declaratively (Cartography/Constrain.swift)
3. Return a ConstraintGroup to allow the caller to manage the group (Cartography/ConstraintGroup.swift)
4. Add comprehensive test coverage with edge cases (CartographyTests/AlignSpec.swift)

Support a new layout-capable type (e.g., a custom view subclass)

1. Conform your type to LayoutItem protocol (Cartography/LayoutItem.swift)
2. Extend LayoutProxy to provide a proxy factory for your type (Cartography/LayoutProxy+TypeErasure.swift)
3. Add any bridging extensions (e.g., on your custom view class) in Extensions.swift (Cartography/Extensions.swift)
4. Test by creating a ConstraintGroup with your type in a new Spec file (CartographyTests/ViewProxyTests.swift)

Modify constraint equation semantics (e.g., change operator behavior)

1. Update operator overload in Expression.swift (e.g., modify == to use .lessThanOrEqual instead of .equal) (Cartography/Expression.swift)
2. Ensure Constraint.swift properly interprets the new relation (Cartography/Constraint.swift)
3. Validate Coefficients.swift handles multiplier and constant correctly (Cartography/Coefficients.swift)
4. Add regression tests (CartographyTests/DimensionSpec.swift)

• Swift operator overloading — Enables intuitive DSL syntax (e.g., view.left == otherView.right - 12) without stringly typing
• Protocol-based design (LayoutProxy, LayoutItem) — Allows unified handling of UIView, NSView, UILayoutGuide, and other layout-capable types without duplicating logic
• Closure-based API (constrain { } ) — Provides scoped context for declaring multiple constraints in one statement; enables easy cleanup via ConstraintGroup
• Type erasure (LayoutProxy+TypeErasure) — Polymorphic constraint building without exposing generic types to the public API
• Auto Layout anchors & constraints — Core iOS/macOS layout framework; no external dependencies needed

• Closure-based constraint building vs. method chaining on ConstraintGroup

  • Why: Closure captures variables; method chaining would require explicit return statements
  • Consequence: Slightly less discoverable but more concise and less verbose; reduces boilerplate

• Single ConstraintGroup per constrain() call vs. returning individual NSLayoutConstraints

  • Why: Groups constraints for lifecycle management
  • Consequence: undefined

Autoresizing mask collision: Cartography automatically sets translatesAutoresizingMaskIntoConstraints = false on views you constrain, but if you constrain views from Apple UIViewController subclasses (e.g., UINavigationController), you must manually disable autoresizing masks beforehand—the docs warn this is easy to miss. Safe area constraints: LayoutGuideProxy.swift supports safe areas (iOS 11+), but older deployment targets will silently ignore them. Constraint priority defaults: No explicit visibility on Priority.swift defaults in the snippet—verify whether default constraint priority is .Required or .High before relying on priority override syntax.

• Operator Overloading — Core to Cartography's DSL—==, >=, <=, +, -, *, / are overloaded on Expression<T> to model constraints and arithmetic without explicit method names
• Type Erasure via Protocol — LayoutItem protocol allows ViewProxy, LayoutGuideProxy, and LayoutSupportProxy to be treated uniformly despite different underlying types (UIView, UILayoutGuide, UILayoutSupport)
• Auto Layout Constraint Activation — Cartography hides NSLayoutConstraint lifecycle (isActive, addConstraint, removeConstraint)—understanding when/how constraints activate is critical for debugging layout bugs
• Builder Pattern / Closure Capture — The constrain(view1, view2) { view1, view2 in ... } syntax uses closure-based builders to configure constraints in a scoped, declarative block
• Translates Autoresizing Mask Into Constraints — Cartography automatically disables translatesAutoresizingMaskIntoConstraints on constrained views; forgetting this causes constraint conflicts and is a common trap in manual Auto Layout
• Constraint Grouping and Replacement — ConstraintGroup allows atomic batch replacement of constraints (useful for dynamic animations or state changes without manually tracking individual NSLayoutConstraints)
• Safe Area Layout Guides — Cartography supports iOS 11+ safe area anchors via LayoutGuideProxy.swift, abstracted through LayoutItem—essential for notch-aware and modern device constraint design

• SnapKit/SnapKit — Direct competitor in Swift Auto Layout DSLs; uses closure syntax similar to Cartography but with slightly different operator semantics and broader platform support
• Masonry/Masonry — Objective-C predecessor to the modern Swift Auto Layout DSL category; Cartography is the Swift spiritual successor with cleaner syntax
• ReactiveSwift/ReactiveSwift — Complementary reactive framework often used with Cartography for constraint binding to observable properties in MVVM architectures
• pointfreeco/swift-snapshot-testing — Snapshot testing library useful for visual regression tests on constraint layouts built with Cartography

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive tests for LayoutProxy type erasure and proxy protocol conformance

LayoutProxy+TypeErasure.swift exists but CartographyTests/ViewProxyTests.swift is minimal. The type erasure pattern is critical for Cartography's declarative API to work across UIView, NSView, and other layout items. Missing tests for edge cases like proxy initialization, property access chains, and error handling could lead to runtime issues.

• [ ] Expand CartographyTests/ViewProxyTests.swift to test LayoutProxy initialization with different LayoutItem types
• [ ] Add tests for property chaining (e.g., proxy.left.top.right) to verify type erasure correctness
• [ ] Add tests in CartographyTests/ for LayoutProxy+TypeErasure.swift covering generic method specializations
• [ ] Test cross-platform scenarios (iOS, tvOS, macOS) using LayoutGuideProxy and LayoutSupportProxy

Add missing tests for AutoresizingMaskLayoutProxy and LayoutSupport edge cases

AutoresizingMaskLayoutProxy.swift exists but there's no dedicated test file for it (LayoutSupportSpec.swift covers LayoutSupport but not AutoresizingMaskLayoutProxy). This legacy constraint conversion layer needs test coverage for proper autoresizing mask to constraint conversion, especially for edge cases and mixed constraint scenarios.

• [ ] Create CartographyTests/AutoresizingMaskLayoutProxySpec.swift with tests for mask-to-constraint conversion
• [ ] Test all autoresizing mask combinations and their corresponding constraint equivalents
• [ ] Add tests for compatibility between autoresizing masks and NSLayoutConstraint priorities
• [ ] Test edge cases like zero-sized views and edge placement with autoresizing masks

Migrate CI from Travis CI to GitHub Actions and add Swift Package Manager build verification

.travis.yml exists but GitHub Actions is now standard. More importantly, Package.swift exists but there's no CI verification that SPM builds work correctly. Travis CI is deprecated, and SPM support should be actively tested alongside CocoaPods and Carthage to ensure package compatibility across all distribution methods.

• [ ] Create .github/workflows/swift-package.yml to test 'swift build' and 'swift test' on macOS, Linux
• [ ] Create .github/workflows/xcode.yml to replace Travis CI, testing all three schemes (Cartography-iOS, Cartography-tvOS, Cartography-Mac)
• [ ] Verify Cartography.podspec builds with 'pod lib lint' in the workflow
• [ ] Add workflow to test Carthage compatibility with 'carthage build --no-skip-current'
• [ ] Remove or deprecate .travis.yml after GitHub Actions is verified working

• Add snapshot tests for the complex constraint scenarios in EdgeSpec.swift and EdgesSpec.swift—the test files exist but lack visual regression checks for multi-view layouts (good for ensuring LayoutProxy composition doesn't regress visually): Create snapshot test fixtures in CartographyTests/ using FBSnapshotTestCase or swift-snapshot-testing, define reference PNG images for a 2-view and 3-view constraint grid
• Document the type erasure pattern used in LayoutProxy+TypeErasure.swift and LayoutItem.swift in a code comment or inline guide—newcomers struggle to understand why ViewProxy, LayoutGuideProxy, and LayoutSupportProxy all exist: Add a detailed comment block at the top of LayoutItem.swift explaining the LayoutItem protocol contract and why ViewProxy/LayoutGuideProxy/LayoutSupportProxy conform to it
• Add a SizeSpec.swift test file (none visible in CartographyTests/) to fully cover Size.swift and Dimension.swift width/height shorthand behavior with edge cases like zero constraints and negative dimensions: Mirror DimensionSpec.swift structure, write 15–20 test cases covering Size(view).width/.height assignments and arithmetic on dimension pairs

The Cartography codebase appears to be a well-maintained Swift Auto Layout DSL library with a clean, focused scope. No critical or high-severity vulnerabilities were identified. The main security concerns are minor: outdated CI/CD infrastructure (Travis CI), absence of a security policy document, and general dependency management practices. The library itself contains no apparent injection risks, hardcoded credentials, or unsafe patterns. The code structure suggests good separation of concerns with dedicated proxy and constraint classes. Overall security posture is solid for a UI layout library with minimal external attack surface.

• Low · Outdated CI/CD Configuration — .travis.yml. The repository uses Travis CI (.travis.yml) which has reached end-of-life as of September 2020. This platform is no longer actively maintained and may have unpatched security vulnerabilities. Fix: Migrate to a maintained CI/CD platform such as GitHub Actions, CircleCI, or GitLab CI to ensure security patches and updates are applied.
• Low · Missing Security Policy — Repository root. No SECURITY.md or security policy document is present in the repository to guide security researchers on responsible disclosure practices. Fix: Add a SECURITY.md file with clear instructions for reporting security vulnerabilities responsibly (e.g., security contact, disclosure timeline).
• Low · Incomplete Dependency Tracking — Podfile, Podfile.lock. While Podfile.lock is present, the actual dependency contents were not provided for analysis. This makes it difficult to assess if any dependencies have known vulnerabilities. Fix: Regularly audit dependencies using tools like CocoaPods dependency check or Snyk. Keep dependencies up-to-date and monitor for security advisories.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.