application

type Artifact struct {
	// Name is the artifact filename relative to the output directory.
	Name string
	// Content is the rendered artifact bytes.
	Content []byte
}

type ArtifactWriter interface {
	Write(ctx context.Context, artifacts []Artifact) error
}

type BrokenEdge struct {
	Origin identity.DocumentID
	Target string
}

type Config struct {
	// RootPath is the scan root (the repository to analyze).
	RootPath string
	// Roots is the explicit reachability root set (documents BFS starts from);
	// empty means autodetect (README.md/index.md/type:index).
	Roots []string
	// Ignore holds additional ignore patterns layered on .matlatlignore.
	Ignore []string
	// ResolutionPolicy selects how raw targets map to documents (ADR 0001).
	ResolutionPolicy reference.ResolutionPolicy
	// OutputDir is the artifact output directory; empty means no artifacts.
	OutputDir string
	// Formats selects the emitter formats to render.
	Formats []string
	// Strict promotes orphan/ambiguous warnings to build failures (ADR 0005).
	Strict bool
	// CheckExternal enables opt-in external link liveness checks (ADR 0003).
	CheckExternal bool
	// Quiet suppresses non-essential output.
	Quiet bool
	// Verbose enables detailed logging.
	Verbose bool
	// ParseWorkers bounds the parse-stage worker pool. 0 means autodetect
	// (GOMAXPROCS, capped). 1 forces the single-threaded path. The merge into
	// the Corpus is always single-threaded and deterministic regardless of this
	// value (P6 fan-out parsing).
	ParseWorkers int
	// ExternalChecker, when non-nil and CheckExternal is set, validates
	// HealthExternal http(s) links. It is an application port (interface) so the
	// domain stays free of net/http; the CLI injects the infrastructure
	// implementation. nil disables external checking even under CheckExternal.
	ExternalChecker ExternalLinkChecker
	// InboundThreshold is the under-linked discoverability floor (ADR 0012): a
	// non-exempt document with outbound links but fewer inbound links is reported
	// as under-linked. <=0 is normalized to graphmodel.DefaultInboundThreshold (3)
	// in the domain.
	InboundThreshold int
	// StructureFindingsSeverity selects the severity of the graduated structure
	// findings (under-linked, dead-end). Default "info" (never fails check);
	// "warning" promotes them so they fail `check --strict`.
	StructureFindingsSeverity StructureFindingsSeverity
	// LinkSuggestionMinShared is the minimum shared-neighbour count an unlinked
	// pair must have to be reported as a suggested-link (ADR 0013). Config-only
	// knob (no CLI flag). <=0 is normalized to the domain default (2) in
	// PredictLinks.
	LinkSuggestionMinShared int
	// FarFromRootThreshold is the hop-distance floor for the far-from-root finding
	// (ADR 0021): a document reachable from the root set but at or beyond this many
	// hops from the nearest root is reported as far-from-root. Config-only knob (no
	// CLI flag). <=0 is normalized to graphmodel.DefaultFarFromRootThreshold (6) in
	// the domain.
	FarFromRootThreshold int
	// EmitExclude holds gitignore-syntax patterns for documents that stay in the
	// corpus (scanned, link-checked, ranked — the pipeline NEVER reads this field)
	// but are not rendered on the consumption surfaces (llms.txt family, index.md,
	// trails.json). Sourced from `.matlatl.yml emitExclude` and consumed only at
	// the emit boundary by the CLI layer (ADR 0019). Empty = no filtering.
	EmitExclude []string
	// OKF enables OKF v0.1 conformance mode (ADR 0023): the pipeline runs the
	// okf.Check conformance rules over the corpus, appends the mode-scoped
	// okf-* Error findings, and reports a CONFORMANT / NOT CONFORMANT verdict.
	// Off by default; the effective value is `--okf` flag OR `.matlatl.yml okf`.
	// When on, an okf-* finding gates `check` (exit 1) regardless of --strict, but
	// the health gate (broken links etc.) is unchanged — the verdict is reported
	// separately and never relaxes it (superset gate).
	OKF bool
	// RespectGitignore unions the repo's effective git-ignore set (tracked and
	// nested .gitignore rules, .git/info/exclude, global excludes) with
	// .matlatlignore so git-ignored working files stay out of the corpus
	// (ADR 0024). Off by default; the effective value is the
	// `--respect-gitignore` flag OR `.matlatl.yml respectGitignore`. A no-op
	// (with a notice) when the scan root is not a git work tree.
	RespectGitignore bool
}

type DocumentParser interface {
	Parse(ctx context.Context, file ScannedFile) (*corpus.Document, error)
}

type DocumentParserFactory interface {
	// New returns a freshly configured DocumentParser.
	New() DocumentParser
	// Clone returns an independent DocumentParser safe to use on its own
	// goroutine. It is equivalent to New but names the per-worker intent.
	Clone() DocumentParser
}

type ExternalLinkChecker interface {
	Check(ctx context.Context, urls []string) map[string]ExternalResult
}

type ExternalResult struct {
	// URL is the checked URL (the map key, repeated for convenience).
	URL string
	// OK is true when the URL responded with a non-error status and passed the
	// SSRF guard.
	OK bool
	// StatusCode is the final HTTP status (0 when no request was made, e.g. a
	// guard refusal or a transport error).
	StatusCode int
	// Blocked is true when the SSRF guard refused the URL (internal/metadata
	// host, disallowed scheme, redirect to an internal host). No network request
	// was made for a blocked URL.
	Blocked bool
	// Err is a human-readable failure reason (empty when OK).
	Err string
}

type FileScanner interface {
	Scan(ctx context.Context, root string) (ScanResult, error)
}

type Notice struct {
	Kind NoticeKind
	// Path is the offending filesystem path (best-effort; may be relative).
	Path string
	// Detail is a human-readable explanation.
	Detail string
}

type NoticeKind int

type Pipeline struct {
	// contains filtered or unexported fields
}

type Result struct {
	// DocumentCount is the number of documents successfully parsed.
	DocumentCount int
	// HeadingCount is the total number of heading slugs indexed.
	HeadingCount int
	// ReferenceCount is the total number of references resolved.
	ReferenceCount int
	// BrokenLinkCount / BrokenAnchorCount / AmbiguousCount / OrphanCount /
	// UnreachableCount / KnowledgeGapCount are convenience tallies for the human
	// summary and exit-code decision.
	BrokenLinkCount   int
	BrokenAnchorCount int
	AmbiguousCount    int
	OrphanCount       int
	UnreachableCount  int
	KnowledgeGapCount int
	// SuggestedLinkCount is the number of topology-based suggested-link findings
	// (ADR 0013). Info; never affects the exit code. SuggestedLinksTruncated
	// reports the suggestion list was capped or a hub neighbour was skipped.
	SuggestedLinkCount      int
	SuggestedLinksTruncated bool
	// UnderLinkedCount / DeadEndCount are the graduated structure-tier tallies
	// (ADR 0012). They affect the exit code only when StructureFindingsSeverity is
	// Warning (consulted by CheckExitCode).
	UnderLinkedCount int
	DeadEndCount     int
	// StructureFindingsSeverity is the resolved severity of under-linked/dead-end
	// findings for this run, carried so CheckExitCode can decide whether they gate
	// --strict.
	StructureFindingsSeverity StructureFindingsSeverity
	// DeadLinkCount is the number of failed external links (only non-zero when
	// --check-external is enabled). It does not affect the default run.
	DeadLinkCount int
	// ArticulationPointCount / BridgeCount are the critical-path structure tallies
	// (ADR 0015): cut vertices and cut edges of the undirected closure. Both are
	// Info findings that NEVER affect the exit code (consulted by no exit-code
	// path); they are carried for the human summary and machine artifacts.
	ArticulationPointCount int
	BridgeCount            int
	// LowScentAnchorCount is the number of low-scent-anchor findings (ADR 0016):
	// links whose anchor text barely previews the target. Info; NEVER affects the
	// exit code; carried for the human summary and machine artifacts.
	LowScentAnchorCount int
	// FarFromRootCount is the number of far-from-root findings (ADR 0021):
	// documents reachable but at or beyond the hop-distance threshold from every
	// root. Info; NEVER affects the exit code; carried for the human summary and
	// machine artifacts.
	FarFromRootCount int
	// OKF conformance (ADR 0023). OKFMode reports whether OKF conformance mode was
	// on for this run; the rest are meaningful only when it is. OKFConformant is
	// the §9 verdict (all three rule counts zero); OKFVersion is the bundle's
	// declared okf_version ("" when none). The three counts are the Error-severity
	// okf-* finding tallies. When OKFMode && !OKFConformant, CheckExitCode gates
	// exit 1 regardless of --strict.
	OKFMode                       bool
	OKFConformant                 bool
	OKFVersion                    string
	OKFMissingFrontmatterCount    int
	OKFMissingTypeCount           int
	OKFReservedFileStructureCount int
	// Report is the frozen analysis report (all finding kinds).
	Report *analysis.AnalysisReport
	// Metrics is the frozen P3 graph-analysis carrier (graph, components, HITS,
	// degrees, root set, reachability, gaps) for later emitters (P4/P5).
	Metrics *graphmodel.GraphMetrics
	// Corpus is the frozen corpus the run was computed over. Human emitters read
	// it for per-document presentation data (title, description, mod-date) that
	// the metrics/report do not carry. It is read-only; emitters must not mutate
	// it (ADR 0004). nil for an empty/failed run.
	Corpus *corpus.Corpus
	// BrokenEdges are the unresolved navigational references (origin → raw
	// target) extracted at resolution time. The frozen graph keeps only Valid
	// edges, so the P4 diagram emitters read this to render red placeholder
	// target nodes (ADR 0003 styling) without re-parsing finding messages.
	// Sorted (Origin, Target) for determinism.
	BrokenEdges []BrokenEdge
	// Notices are non-fatal observations from the scan stage.
	Notices []Notice
}

type ScanResult struct {
	Files   []ScannedFile
	Notices []Notice
}

type ScannedFile struct {
	// Path is the absolute filesystem path of the file.
	Path string
	// ID is the canonical document identity derived from the scan root.
	ID identity.DocumentID
	// ModTime is the file's last-modified time.
	ModTime time.Time
	// Size is the file size in bytes.
	Size int64
}

type StructureFindingsSeverity string