SwiftProjectAnalyzer

Development biography · earlier archive

Development profile compiled from project source and retained records in October 2026. Dates and test results describe those records; they do not imply a new build, live acceptance test or public release.

Biography

Large Swift projects outgrow the developer's mental map of them. When code is spread across many checkouts, agent worktrees and sibling packages, ordinary questions get hard to answer. What does this type actually depend on? Can this method be lifted into another app without dragging half the codebase with it? Is this branch getting healthier or worse? IDEs answer some of these one file at a time, and code-quality services answer others for one repository in the cloud. SwiftProjectAnalyzer answers them locally, on the developer's own Mac, from a single semantic model.

The project's operating rules describe it as "a semantic graph + reasoning system, not just a parser". Its stated priorities are "correctness over cleverness", "structure over heuristics" and "explicitness over inference". In practice that means four things:

• Every symbol gets a deterministic identifier (swift://Module.SymbolPath).
• Every relationship is a typed, directional edge.
• Source provenance (file, line, range) is never thrown away.
• Anything the tool could not resolve is marked explicitly instead of guessed.

How it works. A collection pass walks each file's syntax tree and classifies classes, structs, enums, protocols, actors, extensions, methods, initialisers, properties, typealiases, associated types, enum cases, operators and macros. Results are cached per file, so repeat scans are fast. A resolution pass links references to definitions. When an Xcode or SwiftPM index store is available it can use Apple's IndexStoreDB for compiler-grade resolution, and otherwise it falls back to syntax heuristics. The resulting graph can be written out in several formats:

• JSON-LD or NDJSON, for linked-data tools.
• Deterministic CBOR-LD, for compact, self-describing interchange.
• An internal typed CBOR snapshot, which can be reloaded without rescanning.
• DOT or Mermaid diagrams, to view.

Transplants are the most distinctive feature. Give SPA a selector such as Module.Type#method, a destination project and a destination module. It computes the method's dependency closure, meaning the symbols, files and imports that must come with it, and produces a transplant plan. That plan lists unresolved dependencies, access-level problems and platform constraints. The plan can be saved, reviewed, and then applied. The design principle is that "transplant safety depends on closure completeness, not graph size". The README is candid about the remaining gap: validation does not yet run a real swift build of the destination.

The semantic-MIDI code spine is the unusual part. SPA can project a codebase into one "chunk" per top-level type and score each chunk on confidence, novelty, portability, adaptation cost, dependency pressure and collision risk. Those scores are routed through the SemanticControlCore policy engine and turned into MIDI-style frames, written as a *.semantic-midi-spine.json (and optionally a CBOR-LD) archive. AssistantApp imports that archive into its node map. In the workbench's Semantic Spine tab the projection appears as a piano roll and can be played, or exported as a Standard MIDI File. A codebase can literally be heard.

Code quality and IDE intelligence were added in July 2026 as a layer on the same model:

• Rules. 20 rules covering bug risk (force unwraps, force casts, empty catch blocks), anti-patterns, a hardcoded-credential check, complexity, dead code, performance, style and coverage.
• Reports. A 0–100 health score, a recorded trend history, and a "new versus fixed" baseline diff for pull requests.
• Exports. SARIF 2.1.0 for GitHub code scanning, plus Markdown and JSON-LD.
• Autofixes. A deliberately small set: as!→as?, removing ?? nil, dropping stray print, and removing trailing semicolons.
• Bridges. Uses SwiftLint and SwiftFormat when they are installed.
• IDE intelligence. Drives Apple's sourcekit-lsp as a subprocess for hover, definition, references, completion, formatting and workspace symbols. It can also run as a language server itself, publishing its findings as editor diagnostics with quick-fix code actions.

Audience. Swift developers and agent-assisted workflows working across many related packages and checkouts. In particular, the studio’s own ecosystem: AssistantApp, SemanticControlCore and MacResilience.

A typical journey. A developer opens the workbench and picks a project root. On the Dashboard they choose a preset such as "graph scan" or "full pass". The run rail shows the exact command that will run and how many artifacts it will write. The run produces a DOT graph, a reusable snapshot and diagnostics. In Code Health they see the score and a filterable list of findings, export SARIF, and record a trend point. In Symbol Intel they hover over a symbol for compiler type information. In Transplant they plan moving one method into another package and read the closure and its warnings before choosing to apply it. In Semantic Spine they load the spine, view its piano roll, and play it. Every run, with its command, duration, exit status and outputs, lands in History.

Features — what a visitor can see or try

Everything below is authored in this repository unless it is marked as a dependency.

Pipeline (CLI and workbench)

• Scan & graph export. Visible output: DOT/Mermaid diagrams and JSON-LD/CBOR-LD files.
• Snapshots (--snapshot-out, --snapshot-in). Re-export without rescanning.
• Diagnostics. Unresolved references, cycles, suggestions.
• Metrics / entropy report and semantic fingerprints. Fingerprints use BLAKE3/BLAKE2 from dependencies.
• Schema validation report.
• Transplant planner and applier, down to a single method.

Semantic Spine

• Producer: Sources/SwiftProjectAnalyzer/Spine/.
• Workbench tab: load, piano roll, play, export Standard MIDI File .

Code quality (Sources/SwiftProjectAnalyzer/Quality/)

• Commands: lint, health, trend, fix, rules, config.
• SARIF/Markdown/JSON-LD export, .spa-quality.toml/.json repo config, baseline diff, coverage ingest and generation.
• SwiftLint and SwiftFormat are optional external tools (dependencies, not authored).

Intelligence (Sources/SwiftProjectAnalyzer/LSP/, Intelligence/)

• intel hover | definition | references | symbols | completion | format | wsymbols.
• serve-lsp. The README says the workbench offers copyable VS Code / Neovim / Zed configuration for it.
• sourcekit-lsp is Apple's binary, driven as a subprocess (a dependency, not authored).

Workbench app (Sources/SwiftProjectAnalyzerUI/)

• Pipeline sections: Dashboard, Scan, Artifacts, Transplant, History.
• Quality sections: Code Health, Rule Catalog, Trend, Autofix (behind a confirmation), Quality Config.
• Intelligence sections: Symbol Intel, Language Server.
• Semantics section: Semantic Spine.
• Light/dark palette with a System / Light / Dark override.

Library: SwiftProjectAnalyzerKit, with CodeIntelligence as the facade for other apps.

Technical foundations

• Swift package, three products: the Kit library, the CLI executable and the UI executable. One test target.
• Third-party packages (from git): swift-syntax (SwiftSyntax/SwiftParser), swift-atomics, blake3-swift, Blake2.swift, SwiftCBOR.
• Local-path packages (owner's own or local checkouts):
• indexstore-db (Apple open source, pinned to a toolchain dev snapshot)
• SemanticControlCore (owner's policy engine; local git with no remote)
• Swift-CBORLD at the project archive
• Consequence of the local-path packages: the project builds only on the studio’s Mac. docs/DEPLOYMENT.md explains this and gives the steps for hosted CI.
• LSP integration uses its own small JSON-RPC layer over stdio rather than linking sourcekit-lsp's libraries, to avoid a swift-syntax version conflict .

Maturity by feature (evidence-dated; unknown marked)

Git state: two commits. 4afa5a3 "Initial Commit" (2026-03-23) and e4c1eec "Snapshot: all work since the initial commit (March to 14 Sep 2026)". Later work (CBOR-LD codec, workbench surfaces) appears to be uncommitted. Version: there are no tags. "v0.1.0-test" was only a packaging test label.

Roadmap, limitations, FAQs

Roadmap (stated or implied in docs; aspirations only):

• CBOR-LD graph export (now partly done).
• A graph query engine.
• More transplant automation, including a real destination swift build during validation.
• Multi-model reasoning (planner / worker / verifier).
• NodeMap integration .
• Hosted CI once the local packages are pushed .
• Index-store resolution that scales to large apps (bug identified 2026-10-04).

Known limitations:

• Builds only on the studio’s machine (local-path packages).
• IndexStoreDB resolution does not complete on large projects.
• Heuristic mode leaves most external and SDK references unresolved (about 79% on one AssistantApp subsystem).
• --include globs with a leading **/ match nothing (bug).
• Transplant validation does not run a real build.
• Autofix covers only four mechanical fixes.
• No public release, licence or signing beyond ad-hoc.

FAQs:

• Is it a DeepSource or SwiftLint replacement? Not as a service. It runs locally, borrows ideas (baseline diffs, SARIF, health score) and can call SwiftLint/SwiftFormat, but its core is a semantic graph and transplant engine.
• Does it need Xcode's index? No. Parser-only mode (--no-indexstore) works everywhere and is currently the recommended mode for large apps.
• What is the "semantic-MIDI spine"? A per-type scoring of the codebase rendered as MIDI-like frames, so structure can be visualised as a piano roll and played. AssistantApp consumes it.
• Can it edit my code? Only when asked: transplants need --apply, and autofix sits behind an explicit confirmation in the workbench.
• Can I download it? Not yet. There is no public release.