Python 3 CLI tool for finding probably unused image assets in modern Xcode projects.

It scans asset catalogs and source files, reports assets that were not referenced, and only deletes files when explicitly requested. The default mode is safe dry-run reporting.

• Supports modern Xcode asset catalogs: *.xcassets, *.imageset, *.symbolset, *.appiconset, *.launchimage.
• Scans common iOS/macOS source and resource files: Swift, Objective-C, Objective-C++, storyboard, xib, plist, JSON, strings, markdown, and text files.
• Detects common references such as UIImage(named:), NSImage(named:), SwiftUI Image("..."), Objective-C imageNamed:, and storyboard/xib image="...".
• Handles loose image files such as .png, .jpg, .jpeg, .pdf, .svg, .webp, .heic, and .gif.
• Supports .codescanignore files and command-line ignore globs.
• Outputs text, JSON, or Markdown reports.
• Deletes only with --delete --confirm.

From this repository:

python3 -m pip install -e .

Or run without installing:

python3 -m codescan /path/to/XcodeProject

Dry-run scan:

codescan /path/to/XcodeProject

Markdown report:

codescan /path/to/XcodeProject --format markdown --output unused-assets.md

JSON report:

codescan /path/to/XcodeProject --format json --output unused-assets.json

Ignore additional paths:

codescan /path/to/XcodeProject --ignore "Vendor/**" --ignore "Generated/**"

Delete unused assets after reviewing the report:

codescan /path/to/XcodeProject --delete --confirm

The tool reports "probably unused" assets. It cannot prove that an asset is unused when names are built dynamically, loaded from remote config, referenced by server-driven UI, or passed through localization tables not included in the repository.

For this reason:

• Dry-run is the default.
• Deletion requires both --delete and --confirm.
• App icons, launch images, and assets with names matching AppIcon or LaunchImage are protected by default.
• Paths under Pods, Carthage, Swift Package checkouts, DerivedData, and build folders are ignored by default.

Place a .codescanignore file at the project root to add ignore patterns:

Vendor/**
Generated/**
**/Preview Content/**

Patterns use Python fnmatch semantics and are matched against paths relative to the scan root.

• 0: scan completed successfully.
• 2: invalid arguments or unsafe delete request.

Run tests:

python3 -m unittest discover -s tests

Run the fixture scan:

python3 -m codescan tests/fixtures/SampleApp --format markdown

Xcode Asset Scan 是一个 Python 3 命令行工具，用于扫描现代 Xcode 项目中“可能未使用”的图片资源。

工具会扫描 Asset Catalog 和源码文件，找出没有被引用的资源并生成报告。默认只做 dry-run，不会删除任何文件；只有显式传入 --delete --confirm 时才会执行删除。

• 支持现代 Xcode 资源目录：*.xcassets、*.imageset、*.symbolset、*.appiconset、*.launchimage。
• 支持扫描常见 iOS/macOS 文件：Swift、Objective-C、Objective-C++、storyboard、xib、plist、JSON、strings、Markdown 和文本文件。
• 支持识别常见图片引用方式，例如 UIImage(named:)、NSImage(named:)、SwiftUI Image("...")、Objective-C imageNamed:、storyboard/xib 中的 image="..."。
• 支持散落图片文件，例如 .png、.jpg、.jpeg、.pdf、.svg、.webp、.heic、.gif。
• 支持 .codescanignore 和命令行 --ignore 规则。
• 支持输出 text、JSON、Markdown 报告。
• 只有同时传入 --delete --confirm 才会删除文件。

在仓库根目录执行：

python3 -m pip install -e .

也可以不安装，直接运行：

python3 -m codescan /path/to/XcodeProject

默认 dry-run 扫描：

codescan /path/to/XcodeProject

生成 Markdown 报告：

codescan /path/to/XcodeProject --format markdown --output unused-assets.md

生成 JSON 报告：

codescan /path/to/XcodeProject --format json --output unused-assets.json

额外忽略指定目录：

codescan /path/to/XcodeProject --ignore "Vendor/**" --ignore "Generated/**"

检查报告后，确认删除未使用资源：

codescan /path/to/XcodeProject --delete --confirm

这个工具输出的是“可能未使用”的资源，而不是绝对证明资源没有被使用。

以下情况可能导致工具无法识别真实引用：

• 图片名通过字符串拼接动态生成。
• 图片名来自远程配置或服务端下发 UI。
• 图片名保存在工具未扫描的本地化文件、数据库或二进制文件中。
• 图片由第三方 SDK 或运行时反射机制加载。

因此工具默认采用保守策略：

• 默认只扫描和报告，不删除。
• 删除必须同时使用 --delete 和 --confirm。
• App Icon、Launch Image，以及名称包含 AppIcon 或 LaunchImage 的资源默认受保护。
• 默认忽略 Pods、Carthage、Swift Package 缓存、DerivedData 和 build 目录。

可以在项目根目录创建 .codescanignore，添加自定义忽略规则：

Vendor/**
Generated/**
**/Preview Content/**

规则使用 Python fnmatch 语义，并基于扫描根目录的相对路径匹配。

• 0：扫描成功。
• 2：参数错误，或删除操作缺少安全确认。

运行测试：

python3 -m unittest discover -s tests

扫描内置示例工程：

python3 -m codescan tests/fixtures/SampleApp --format markdown