workspacescan

type AIOptions struct {
	Bin     string        // CLI binary path; empty → "claude" via PATH
	Timeout time.Duration // per-invocation bound; <=0 → aiDefaultTimeout
}

type GitRemotes struct {
	GitHub     []string `json:"github,omitempty"`
	OtherHosts []string `json:"other_hosts,omitempty"`
}

type LeakFinding struct {
	Path string `json:"path"`
	Kind string `json:"kind"`
	Line int    `json:"line,omitempty"`
	// Source names the attached source this finding came from (the source's
	// locator) once N sources are merged into one workspace profile; empty for
	// a single-source profile. Attribution is a SEPARATE field rather than a
	// prefix on Path because Path is path-CLASSIFIED downstream (the client's
	// testdata|__tests__|fixtures fixture check): folding the locator into it
	// makes every leak in a source whose own path contains such a segment
	// classify as a fixture. Path therefore stays scan-root-relative and
	// means exactly what it says.
	Source string `json:"source,omitempty"`
}

type ManifestHit struct {
	Path   string `json:"path"`   // slash-separated, relative to the scan root
	Marker string `json:"marker"` // canonical marker id, e.g. "package-lock.json"
}

type ScanFacts struct {
	ManifestsFound      []ManifestHit        `json:"manifests_found,omitempty"`
	GitRemotes          GitRemotes           `json:"git_remotes,omitempty"`
	HasDevcontainer     bool                 `json:"has_devcontainer,omitempty"`
	HasDockerfile       bool                 `json:"has_dockerfile,omitempty"`
	UnrecognizedSamples []UnrecognizedSample `json:"unrecognized_samples,omitempty"`
	Truncated           bool                 `json:"truncated,omitempty"`

	// Content-lane evidence (detect.go): names/keys/hosts only, extracted via
	// anchored capture groups — no file value ever lands here. Like every other
	// fact these are UNTRUSTED until DeriveProfile re-validates and caps them.
	SecretRequirements []SecretNeed  `json:"secret_requirements,omitempty"`
	ServicesFound      []string      `json:"services_found,omitempty"`
	SuggestedEgress    []string      `json:"suggested_egress,omitempty"`
	SecretFilesPresent []string      `json:"secret_files_present,omitempty"`
	BuildMemoryMiB     int           `json:"build_memory_mib,omitempty"`
	LeakFindings       []LeakFinding `json:"leak_findings,omitempty"`
	// Raw setup-command SIGNALS (not commands): which conventional script/target
	// keys exist. DeriveProfile synthesizes fixed-template SetupCommands from
	// these + the detected package managers — file content never becomes a command.
	ScriptKeys  []string `json:"script_keys,omitempty"`  // package.json scripts: build|test|lint present
	MakeTargets []string `json:"make_targets,omitempty"` // Makefile targets: build|test|install|lint present
	// BuildInputHashes maps a build-input file's rel path to a hex sha256 of its
	// CONTENT (devcontainer.json / Dockerfile). A digest, not content — safe.
	BuildInputHashes map[string]string `json:"build_input_hashes,omitempty"`
}

type SecretNeed struct {
	Name     string `json:"name"`
	Kind     string `json:"kind,omitempty"`
	Optional bool   `json:"optional,omitempty"`
}

type SetupCommand struct {
	Stage   string `json:"stage"`   // install | build | test | lint
	Command string `json:"command"` // fixed-template command, never file content
	Source  string `json:"source"`  // what implied it, e.g. "convention:go", "package.json:build"
}

type UnrecognizedSample struct {
	Path    string `json:"path"`
	Content string `json:"content"`
}

type WorkspaceProfile struct {
	Languages       []string `json:"languages,omitempty"`
	PackageManagers []string `json:"package_managers,omitempty"`
	// (ToolchainNeeds below reads these two — the dispatch env derives from
	// what the scan actually detected, never from a platform-wide guess.)
	EgressDomains   []string   `json:"egress_domains,omitempty"`
	Tools           []string   `json:"tools,omitempty"`
	GitRemotes      GitRemotes `json:"git_remotes,omitempty"`
	HasDevcontainer bool       `json:"has_devcontainer,omitempty"`
	HasDockerfile   bool       `json:"has_dockerfile,omitempty"`

	// Advisory "needs" fields (content lane, validated by DeriveProfile).
	// RequiredSecrets/ServicesNeeded/SecretFilesPresent inform the operator
	// (needs panel, setup checklist) and never gate a launch or create a
	// grant. SuggestedEgress is content-derived and is NEVER auto-unioned
	// into a run's allowlist (that privilege is EgressDomains-only, which
	// stays filename-keyed) — an operator promotes hosts into the
	// workspace's operator-owned ApprovedEgress list instead.
	// these advisory fields ride in ProfileHash, so a workspace's
	// first rescan after this change forces one no-op image rebuild. Ceiling:
	// harmless one-time churn; upgrade path — hash only the image-affecting
	// subset (Languages/HasDevcontainer/HasDockerfile) if it ever bites.
	RequiredSecrets    []SecretNeed `json:"required_secrets,omitempty"`
	ServicesNeeded     []string     `json:"services_needed,omitempty"`
	SuggestedEgress    []string     `json:"suggested_egress,omitempty"`
	SecretFilesPresent []string     `json:"secret_files_present,omitempty"`
	// BuildMemoryMiB is the largest build-heap ceiling detected (JVM -Xmx /
	// Node --max-old-space-size). Advisory: surfaced so an operator can size
	// the sandbox; never auto-applied to a run's ResourceLimits.
	BuildMemoryMiB int `json:"build_memory_mib,omitempty"`
	// LeakFindings are content-free reports of suspected committed secret
	// values (path + detector kind + line, never the value). Advisory warning.
	LeakFindings []LeakFinding `json:"leak_findings,omitempty"`
	// SetupCommands are the conventional install/build/test/lint steps this
	// workspace implies, synthesized from fixed templates (never file content).
	// Advisory: operator-approved before they ever run, and only in a sandbox.
	SetupCommands []SetupCommand `json:"setup_commands,omitempty"`
	// ContextHash is a digest of the BUILD-INPUT files' CONTENT (a repo's own
	// devcontainer.json / Dockerfile). It rides ProfileHash so the built-image
	// cache (BuiltProfileHash) busts when a build input changes even if the
	// detected profile is otherwise identical — the gap a profile-only hash has
	// for the repo-owns-its-devcontainer build path. Empty when no build-input
	// files are present (generated-devcontainer path is already profile-derived).
	ContextHash string `json:"context_hash,omitempty"`
	// Confidence is one of ConfidenceHigh/Medium/Low.
	Confidence  string `json:"confidence"`
	NeedsReview bool   `json:"needs_review,omitempty"`
	// Source is one of SourceDeterministic/SourceAIAssisted.
	Source string `json:"source"`
}