Data Model

All types are defined in core/src/languages/language_plugin.rs and serialised as JSON by serde_json. The FFI layer returns JSON strings; the CLI prints them to stdout; the GUI decodes them into Swift model types.

Type hierarchy

classDiagram
    class ScanEnvelope {
        +u64 scanned_at
        +HashMap results
        +Option~PolicyReport~ policy_report
    }
    class PolicyReport {
        +bool pass
        +Vec~PolicyViolation~ violations
    }
    class PolicyViolation {
        +String project
        +String dependency
        +String rule
        +String value
    }
    class PackageMetadata {
        +String project_name
        +String path
        +Option~String~ package_manager
        +Option~Vec~RegistryConfig~~ registries
        +Vec~Dependency~ dependencies
    }
    class Dependency {
        +String name
        +String version
        +String local_path
        +String included_by
        +Option~HashMap~ hashes
        +Option~Vec~String~~ licenses
        +Option~String~ purl
        +Option~String~ source_url
        +Option~String~ repository
        +Option~Vec~Vulnerability~~ vulnerabilities
    }
    class RegistryConfig {
        +String url
        +String level
        +String config_file
        +bool valid
        +Option~String~ username
        +Option~String~ password_hash
    }
    class Vulnerability {
        +String id
        +String severity
        +String summary
        +Option~String~ fixed_version
        +String reference_url
    }

    ScanEnvelope "1" --> "0..1" PolicyReport : policy_report
    PolicyReport "1" --> "*" PolicyViolation : violations
    ScanEnvelope "1" --> "*" PackageMetadata : results
    PackageMetadata "1" --> "*" Dependency : dependencies
    PackageMetadata "1" --> "*" RegistryConfig : registries
    Dependency "1" --> "*" Vulnerability : vulnerabilities

`ScanEnvelope`

Top-level wrapper returned by every scan. Carries a timestamp so consumers always know how stale the data is.

Field	Type	Description
`scanned_at`	`u64`	Unix timestamp (seconds) when the scan completed
`results`	`object`	Map of `project_name -> PackageMetadata`
`policy_report`	`PolicyReport`	Policy evaluation result (omitted from JSON when no policy is configured)

`PolicyReport`

Result of evaluating policy rules against scan results. Only present when a policy block exists in config or an admin policy file is deployed.

Field	Type	Description
`pass`	`bool`	`true` if all rules passed, `false` if any violation exists
`violations`	`PolicyViolation[]`	List of individual violations (empty when `pass` is `true`)

`PolicyViolation`

Field	Type	Description
`project`	`string`	Project name containing the offending dependency
`dependency`	`string`	Dependency name
`rule`	`string`	Human-readable rule that was violated (e.g. `"license not in allowed_licenses"`)
`value`	`string`	The violating value (e.g. the license string, registry URL, or severity)

`PackageMetadata`

One record per discovered project.

Field	Type	Nullable	Description
`project_name`	`string`	No	Human-readable project name
`path`	`string`	No	Absolute filesystem path to the project root
`package_manager`	`string`	Yes	Detected package manager, e.g. `"npm"`, `"yarn"`, `"nuget"`, `"composer"`
`project_license`	`string`	Yes	SPDX license identifier for the project itself
`registries`	`RegistryConfig[]`	Yes	Resolved registry entries (null if none detected)
`dependencies`	`Dependency[]`	No	All dependencies, direct and transitive

`Dependency`

One record per package, direct or transitive.

Field	Type	Nullable	Description
`name`	`string`	No	Package name as it appears in the registry
`version`	`string`	No	Exact installed version string
`local_path`	`string`	No	Absolute path to the installed package on disk
`included_by`	`string`	No	`"direct"` for direct dependencies; parent package name for transitive deps
`hashes`	`object`	Yes	Key -> hash string map
`licenses`	`string[]`	Yes	SPDX licence identifiers
`purl`	`string`	Yes	Package URL
`source_url`	`string`	Yes	Registry download or package page URL
`repository`	`string`	Yes	VCS URL (GitHub, GitLab, etc.)
`vulnerabilities`	`Vulnerability[]`	Yes	`null` = not queried; `[]` = clean; `[...]` = active CVEs

`RegistryConfig`

A resolved registry or package feed entry.

Field	Type	Nullable	Description
`url`	`string`	No	Registry base URL
`level`	`string`	No	`"global"` or `"project"`
`config_file`	`string`	No	Absolute path to the config file
`valid`	`bool`	No	Whether the registry URL passes policy
`username`	`string`	Yes	Username for authenticated feeds
`password_hash`	`string`	Yes	Argon2id hash of the credential

`Vulnerability`

A single CVE or GHSA record associated with a dependency.

Field	Type	Nullable	Description
`id`	`string`	No	Identifier, e.g. `"CVE-2024-1234"` or `"GHSA-xxxx-xxxx-xxxx"`
`severity`	`string`	No	`"CRITICAL"` / `"HIGH"` / `"MEDIUM"` / `"LOW"` / `"UNKNOWN"`
`summary`	`string`	No	Short description from OSV
`fixed_version`	`string`	Yes	Smallest fix version strictly greater than installed; null if no fix exists
`reference_url`	`string`	No	Canonical link (OSV page or NVD)

`FixPreview`

Preview of what a fix operation would do.

Field	Type	Description
`dependency`	`string`	Dependency being fixed
`current_version`	`string`	Currently installed version
`target_version`	`string`	Version the fix would upgrade to
`binary`	`string`	Package manager binary
`command`	`string`	Human-readable command
`is_major_bump`	`bool`	Whether the target version is a semver major bump
`fixes`	`FixableVuln[]`	Vulnerabilities that will be resolved
`risk_score`	`UpgradeRiskScore`	Risk assessment for this upgrade

`UpgradeRiskScore`

Deterministic risk assessment for a single dependency upgrade (0-100).

Factor	Points	When
`bump_type`	5 / 15 / 40	Patch / minor / major version bump
`version_distance`	0-20	Number of minor versions skipped
`dependency_scope`	5 / 15	Transitive / direct dependency
`multi_major_jump`	10	Jumping 2+ major versions
`pre_release_target`	10	Target is alpha/beta/rc/dev/preview/canary

Full JSON example

{
  "scanned_at": 1711027200,
  "results": {
    "my-app": {
      "project_name": "my-app",
      "path": "/Users/dev/my-app",
      "package_manager": "npm",
      "registries": [
        {
          "url": "https://registry.npmjs.org/",
          "level": "global",
          "config_file": "/Users/dev/.npmrc",
          "valid": true,
          "username": null,
          "password_hash": null
        }
      ],
      "dependencies": [
        {
          "name": "lodash",
          "version": "4.17.20",
          "local_path": "/Users/dev/my-app/node_modules/lodash",
          "included_by": "direct",
          "hashes": {
            "integrity": "sha512-PlhdFcillOINfeV7Ni6oF1TAEayyZBoZ8bcshTHqOYJYlrqzRK5hagpagky5o4HfCzzd1TRkXPMFq6cKk9rGmA=="
          },
          "licenses": ["MIT"],
          "purl": "pkg:npm/lodash@4.17.20",
          "source_url": "https://registry.npmjs.org/lodash/-/lodash-4.17.20.tgz",
          "repository": "https://github.com/lodash/lodash",
          "vulnerabilities": [
            {
              "id": "CVE-2021-23337",
              "severity": "HIGH",
              "summary": "Command injection via template in lodash",
              "fixed_version": "4.17.21",
              "reference_url": "https://osv.dev/vulnerability/CVE-2021-23337"
            }
          ]
        }
      ]
    }
  }
}