Project Detection Surface (Scan)

Status: designed, not shipped. The scan route answers 501 not_available (sparki-tools/api-engine pkg/api/handlers/projects.go:375-387 @0b0309f), detection copy was removed from the product (web-app f53d877), and the landing page lists “Dependency and CVE scanning: Not available” (sparki.tools, read 2026-10-25).

ELI5

Sparki has a librarian who can tell a Go-with-Fiber repo from a Python-with-Django one. She was taken off the front desk because she used to read whatever folder a visitor pointed at on the server itself. She stays in the building until she can work inside the sealed build room on a fresh copy of the repository.

Technical Deep Dive

Source: sparki-tools/api-engine internal/detection/types/types.go:7-200, internal/detection/detectors/ (go, java, javascript, php, ruby, rust), pkg/api/handlers/projects.go:375-387, pkg/api/handlers/pipelines.go:76-87, pkg/api/server.go:133,313 @0b0309f, read 2026-10-25. The previous revision cited subsystems/scan/types.go; that package is CLI-only and is not the engine’s detector.

Why it is off

ScanProject documents the reason in code: detection ran on a client-chosen path on the API server’s own filesystem (req.project_path, else repository_url), so any writer could probe the host. Scanning is out of launch scope, and until it runs against a checked-out repository in an isolated worker it returns 501 without reading the request.

flowchart LR
  OLD["Before: POST scan with project_path"] --> FS["detector reads API host filesystem"]
  FS --> RISK["any writer can probe the host"]
  NOW["Now: POST scan"] --> R501["501 not_available, request unread"]
  FUT["Designed: detection step in the build worker"] --> SBX["runs on a fresh checkout inside the step sandbox"]

Because the scan never fills the detection cache, pipeline auto-generation (auto_generate: true) also fails with “No detection results found” (pipelines.go:76-87).

The detector vocabulary that exists

classDiagram
  class DetectionResult {
    +Language language
    +FrameworkInfo[] frameworks
    +FrameworkInfo primary_framework
    +BuildTool[] build_tools
    +PackageManager package_manager
  }
  class FrameworkInfo {
    +Framework framework
    +string version
    +float64 confidence
  }
  class Language {
    javascript
    typescript
    python
    go
    rust
    java
    csharp
    ruby
    php
    unknown
  }
  DetectionResult --> Language
  DetectionResult --> FrameworkInfo

Frameworks carry a confidence float; languages and package managers are categorical.

Key Terms

• scan → historically “project detection”; never security scanning. CVE/dependency scanning is a separate, unbuilt capability.
• DetectionResult → language, ranked frameworks, primary framework, build tools, package manager.
• not_available → the error code the scan route returns.

Q&A

Q: What does POST /api/v1/projects/:id/scan return today, and why? A: 501 with {"error":"not_available"}. Detection used to read a client-supplied path on the API host’s filesystem, which let any project writer probe the server, so the route was disabled until detection can run in an isolated worker.

Q: Which languages does internal/detection name, and which have detectors? A: It names javascript, typescript, python, go, rust, java, csharp, ruby, php and unknown. Detector files exist for go, java, javascript, php, ruby and rust.

Q: What would have to change before detection could ship again? A: It would have to run against a checked-out repository inside the build worker’s sandbox rather than on the API host, and customer copy could mention it only once that ships (launch decision §6).

Examples

A prospect asks whether Sparki “auto-detects my stack”. Today the honest answer is no: you write the pipeline yourself. The detector exists in the engine, disabled at the route, with the reason written next to it.