Documentation
¶
Overview ¶
Package artifact exports an indexed project's graph database as a self-describing, zstd-compressed file that teammates can import instead of re-indexing, and imports such files with an index-identity check.
File layout: magic, 4-byte big-endian header length, JSON Header, then a single zstd frame containing the SQLite database image (VACUUM INTO copy). The header carries the index identity captured when the project was indexed (repository, revision, dirty fingerprint), so an import can tell whether the artifact matches the local checkout.
Index ¶
Constants ¶
const Extension = ".cgraph.zst"
Extension is the conventional file suffix.
const Format = 1
Format is the artifact container version. Bump when the layout changes.
Variables ¶
var ErrStale = errors.New("artifact does not match the local checkout")
ErrStale is returned when the artifact does not match the local checkout and AllowStale is false.
Functions ¶
This section is empty.
Types ¶
type Header ¶
type Header struct {
Format int `json:"format"`
CodeGraphVersion string `json:"code_graph_version"`
SchemaVersion int `json:"schema_version"`
Project string `json:"project"`
RootPath string `json:"root_path"`
IndexedAt string `json:"indexed_at"`
Identity *indexidentity.Envelope `json:"identity,omitempty"`
IdentityStatus string `json:"identity_status"`
IdentityReason string `json:"identity_reason,omitempty"`
NodeCount int `json:"node_count"`
EdgeCount int `json:"edge_count"`
FileCount int `json:"file_count"`
CreatedAt string `json:"created_at"`
PayloadSHA256 string `json:"payload_sha256"`
PayloadBytes int64 `json:"payload_bytes"`
}
Header describes the artifact and the index inside it.
func Export ¶
func Export(ctx context.Context, st *store.Store, project, outPath, codeGraphVersion string) (*Header, error)
Export writes the project's database from st to outPath. outPath is an operator-chosen location; it is cleaned and made absolute here so every later file operation sees a canonical path.
type ImportOptions ¶
type ImportOptions struct {
// RepoPath is the local checkout the artifact should serve. Empty means
// the artifact's recorded root_path, which must exist locally.
RepoPath string
// CacheDir receives <project>.db; empty means store.CacheDir().
CacheDir string
// AllowStale imports even when the artifact was built from a different
// revision or a dirty tree, or carries no identity.
AllowStale bool
// Force replaces an existing database for the project.
Force bool
// ProjectName derives the local project name from the absolute repo path
// (pipeline.ProjectNameFromPath); required.
ProjectName func(absPath string) string
// Capture overrides identity capture (tests). nil uses indexidentity.Capture.
Capture func(root string) (*indexidentity.Envelope, error)
}
ImportOptions controls Import.
type Report ¶
type Report struct {
Header *Header `json:"header"`
Project string `json:"project"`
RepoPath string `json:"repo_path"`
DBPath string `json:"db_path"`
Stale bool `json:"stale"`
StaleReason string `json:"stale_reason,omitempty"`
Renamed bool `json:"renamed"`
}
Report summarises an import.
Source Files