Scan Detection Surface

ELI5

When a repo lands on Sparki, the scan subsystem flips through it like a librarian sorting books: this one is Go-with-Fiber, this one is Python-with-FastAPI, this one is TypeScript-with-Next.js. Every category has a finite list of things it knows; anything else gets stamped unknown.

Technical Deep Dive

subsystems/scan/types.go declares four parallel enum families. Detector implementations live under subsystems/scan/detectors/; outputs feed the score and forgery subsystems.

Enums

classDiagram
  class Language {
    go
    javascript
    typescript
    python
    rust
    java
    unknown
  }
  class Framework {
    fiber, echo, gin, chi
    express, nextjs, react, vue, angular, svelte, nestjs
    django, flask, fastapi
    axum, actix, rocket
    springboot, micronaut, quarkus
    unknown
  }
  class PackageManager {
    go-mod
    npm, yarn, pnpm
    pip, poetry
    cargo
    maven, gradle
  }
  class BuildTool {
    go, npm, webpack, ...
  }
  class ScanResult {
    +Language language
    +Framework[] frameworks
    +PackageManager package_manager
    +BuildTool build_tool
    +time.Time scanned_at
  }
  ScanResult --> Language
  ScanResult --> Framework
  ScanResult --> PackageManager
  ScanResult --> BuildTool

Languages

go, javascript, typescript, python, rust, java, unknown. JS and TS are split because their tooling differs even when the runtime is the same.

Frameworks (Grouped)

Package Managers

Detection vs Confidence

The OpenAPI Project.Framework (libs/api-contracts/schemas/project.json) carries a confidence 0..1. Internal scan enums do not — they are categorical. The confidence is added by the detector layer when reporting up to the project record.

Key Terms

• Framework=unknown → no detector matched; downstream score/forgery treats the project generically
• detector → a function under subsystems/scan/detectors that inspects manifests/lockfiles and returns enum values
• PackageManager go-mod → spelt with a hyphen, distinct from BuildTool go
• scan-time vs build-time → scan runs on push/import; build-time uses the cached scan result unless invalidated

Q&A

Q: What does Framework=unknown mean for downstream subsystems? A: Score and forgery fall back to language-only behaviour: generic build metrics, no framework-specific catalogue templates. The project still works; it just gets less tailored output.

Q: Why is react listed under Node frameworks? A: Detection treats it as a Node-runtime framework (it shows up via package.json deps). Whether it is “really” a framework or a library is irrelevant to the categorical decision the detector has to make.

Q: Can a project have multiple frameworks? A: Yes. The Project.frameworks schema is an array; the typical case is nextjs + react, or django + react for full-stack projects.

Examples

A repo with go.mod, a main.go importing github.com/gofiber/fiber/v2, and a Dockerfile with FROM golang:1.24 produces: Language=go, Framework=[fiber], PackageManager=go-mod, BuildTool=go, fed up to Project.frameworks=[{name:"fiber",category:"backend",confidence:0.95}].