ast

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

type BashParserOption func(*BashParserOptions)

type BashParserOptions struct {
	// MaxFileSize is the maximum file size in bytes to parse.
	// Files larger than this return ErrFileTooLarge.
	// Default: 10MB
	MaxFileSize int

	// ExtractAliases determines whether to extract alias definitions.
	// Default: true
	ExtractAliases bool
}

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

type CSSParserOption func(*CSSParserOptions)

type CSSParserOptions struct {
	// MaxFileSize is the maximum file size in bytes to parse.
	// Files larger than this return ErrFileTooLarge.
	// Default: 10MB
	MaxFileSize int

	// ExtractNestedClasses determines whether to extract classes inside media queries.
	// Default: true
	ExtractNestedClasses bool
}

type CallSite struct {
	// Target is the name of the called function or method.
	//
	// For simple function calls: "FunctionName"
	// For qualified calls: "package.Function" or "receiver.Method"
	// For method calls: "Method" (receiver tracked separately)
	//
	// Example values:
	//   - "Setup" (local function)
	//   - "config.Load" (imported package function)
	//   - "Connect" (method call, Receiver="db")
	Target string `json:"target"`

	// Location is where the call expression occurs in the source file.
	// Points to the start of the call expression.
	Location Location `json:"location"`

	// IsMethod indicates if this is a method call (has a receiver).
	// True for: obj.Method(), s.Initialize()
	// False for: Function(), pkg.Function()
	IsMethod bool `json:"is_method,omitempty"`

	// Receiver is the receiver expression text for method calls.
	// Empty for plain function calls.
	//
	// Examples:
	//   - "db" for db.Connect()
	//   - "s" for s.Initialize()
	//   - "ctx" for ctx.Done()
	Receiver string `json:"receiver,omitempty"`

	// FunctionArgs lists identifiers passed as callback/HOF arguments.
	// Only populated when a call passes identifiers that may reference other functions.
	// IT-03a C-1: Enables EdgeTypeReferences from caller to callback arguments.
	//
	// Examples:
	//   - ["middleware"] for app.use(middleware)
	//   - ["LoggingInterceptor"] for UseInterceptors(LoggingInterceptor)
	FunctionArgs []string `json:"function_args,omitempty"`
}

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

type DockerfileParserOption func(*DockerfileParserOptions)

type DockerfileParserOptions struct {
	// MaxFileSize is the maximum file size in bytes to parse.
	// Files larger than this return ErrFileTooLarge.
	// Default: 10MB
	MaxFileSize int
}

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

type GoParserOption func(*GoParser)

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

type HTMLParserOption func(*HTMLParserOptions)

type HTMLParserOptions struct {
	// MaxFileSize is the maximum file size in bytes to parse.
	// Files larger than this return ErrFileTooLarge.
	// Default: 10MB
	MaxFileSize int

	// ParseInlineScripts determines whether to parse inline <script> content.
	// Default: true
	ParseInlineScripts bool

	// ParseInlineStyles determines whether to parse inline <style> content.
	// Default: true
	ParseInlineStyles bool
}

type Import struct {
	// Path is the import path or module name.
	// Example: "github.com/gin-gonic/gin" for Go, "os.path" for Python.
	Path string `json:"path"`

	// Alias is the local alias if the import is aliased.
	// Example: "gin" for 'import "github.com/gin-gonic/gin"' (Go default).
	// Example: "pd" for 'import pandas as pd' (Python).
	Alias string `json:"alias,omitempty"`

	// Names lists specific names imported (for selective imports).
	// Example: ["useState", "useEffect"] for 'import { useState, useEffect } from "react"'.
	Names []string `json:"names,omitempty"`

	// IsWildcard indicates if this is a wildcard import.
	// Example: 'from module import *' in Python.
	IsWildcard bool `json:"is_wildcard,omitempty"`

	// IsRelative indicates if this is a relative import.
	// Example: 'from . import foo' or 'from ..utils import bar' in Python.
	// For absolute imports, this is false.
	IsRelative bool `json:"is_relative,omitempty"`

	// IsDefault indicates if this is a default import.
	// Example: 'import foo from "bar"' in JavaScript/TypeScript.
	IsDefault bool `json:"is_default,omitempty"`

	// IsNamespace indicates if this is a namespace import.
	// Example: 'import * as foo from "bar"' in JavaScript/TypeScript.
	IsNamespace bool `json:"is_namespace,omitempty"`

	// IsTypeOnly indicates if this is a type-only import.
	// Example: 'import type { Foo } from "bar"' in TypeScript.
	IsTypeOnly bool `json:"is_type_only,omitempty"`

	// IsCommonJS indicates if this is a CommonJS require() import.
	// Example: 'const foo = require("bar")' in JavaScript.
	IsCommonJS bool `json:"is_commonjs,omitempty"`

	// IsDynamic indicates this is a dynamic import() call inside a function body.
	// Example: 'const X = React.lazy(() => import("./HeavyComponent"))' in JavaScript.
	// When true, the import was detected inside an expression rather than at top level.
	// Enables the builder's resolveDynamicImportEdges post-pass and analytics filtering.
	IsDynamic bool `json:"is_dynamic,omitempty"`

	// IsScript indicates this is a script import (HTML <script src>).
	IsScript bool `json:"is_script,omitempty"`

	// IsStylesheet indicates this is a stylesheet import (HTML <link href> or CSS @import).
	IsStylesheet bool `json:"is_stylesheet,omitempty"`

	// IsModule indicates this is an ES module import.
	// For HTML: <script type="module">
	// For JS: import statement (vs require)
	IsModule bool `json:"is_module,omitempty"`

	// MediaQuery contains the media query for conditional imports.
	// Example: @import 'print.css' print → MediaQuery: "print"
	MediaQuery string `json:"media_query,omitempty"`

	// Location is where the import statement appears in the file.
	Location Location `json:"location"`
}

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

type JavaScriptParserOption func(*JavaScriptParserOptions)

type JavaScriptParserOptions struct {
	// MaxFileSize is the maximum file size in bytes to parse.
	// Files larger than this return ErrFileTooLarge.
	// Default: 10MB
	MaxFileSize int

	// IncludePrivate determines whether to include non-exported symbols.
	// Default: true
	IncludePrivate bool

	// ExtractBodies determines whether to include function body text.
	// Default: false (bodies are expensive and often not needed)
	ExtractBodies bool
}

type Location struct {
	// FilePath is the path to the source file, relative to project root.
	FilePath string `json:"file_path"`

	// StartLine is the 1-indexed line number where the symbol starts.
	StartLine int `json:"start_line"`

	// EndLine is the 1-indexed line number where the symbol ends.
	EndLine int `json:"end_line"`

	// StartCol is the 0-indexed column where the symbol starts on StartLine.
	StartCol int `json:"start_col"`

	// EndCol is the 0-indexed column where the symbol ends on EndLine.
	EndCol int `json:"end_col"`
}

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

type MarkdownParserOption func(*MarkdownParserOptions)

type MarkdownParserOptions struct {
	// MaxFileSize is the maximum file size in bytes to parse.
	// Files larger than this return ErrFileTooLarge.
	// Default: 10MB
	MaxFileSize int

	// MaxHeadingDepth is the maximum heading level to extract (1-6).
	// Default: 6 (extract all headings)
	MaxHeadingDepth int

	// ExtractCodeBlocks determines whether to extract fenced code blocks.
	// Default: true
	ExtractCodeBlocks bool

	// ExtractLinks determines whether to extract link reference definitions.
	// Default: true
	ExtractLinks bool

	// ExtractLists determines whether to extract lists.
	// Default: true
	ExtractLists bool
}

type MethodSignature struct {
	// Name is the method name.
	// Example: "Read", "Write", "Close"
	Name string `json:"name"`

	// Params is the normalized parameter list (types only, no names).
	// Example: "[]byte" for func Read(p []byte) (int, error)
	// Used for Phase 2 signature matching.
	Params string `json:"params,omitempty"`

	// Returns is the normalized return type list.
	// Example: "int, error" for func Read(p []byte) (int, error)
	// Used for Phase 2 signature matching.
	Returns string `json:"returns,omitempty"`

	// ParamCount is the number of parameters.
	// Used for quick filtering before detailed signature comparison.
	ParamCount int `json:"param_count"`

	// ReturnCount is the number of return values.
	// Used for quick filtering before detailed signature comparison.
	ReturnCount int `json:"return_count"`

	// ReceiverType is the receiver type for methods (e.g., "*Handler", "Handler").
	// Empty for interface method declarations.
	// Used to distinguish value vs pointer receivers.
	ReceiverType string `json:"receiver_type,omitempty"`
}

type ParseError struct {
	// FilePath is the path to the file where the error occurred.
	FilePath string

	// Line is the 1-indexed line number where the error occurred.
	// May be 0 if the error is not associated with a specific line.
	Line int

	// Column is the 0-indexed column where the error occurred.
	// May be 0 if the error is not associated with a specific column.
	Column int

	// Message describes the error in human-readable form.
	Message string

	// Cause is the underlying error that triggered this parse error.
	// May be nil if this is a primary error.
	Cause error
}

type ParseOptions struct {
	// IncludeComments determines whether to extract comments as symbols.
	// Default: false (comments extracted as DocComment on associated symbols only)
	IncludeComments bool

	// IncludePrivate determines whether to include non-exported symbols.
	// Default: true (include all symbols)
	IncludePrivate bool

	// MaxDepth limits the nesting depth for child symbol extraction.
	// 0 means no limit. Default: 0
	MaxDepth int

	// ExtractBodies determines whether to include function/method body text.
	// Default: false (bodies are expensive and often not needed)
	ExtractBodies bool
}

type ParseResult struct {
	// FilePath is the path to the parsed file, relative to project root.
	FilePath string `json:"file_path"`

	// Language is the detected or specified language of the file.
	// Example: "go", "python", "typescript"
	Language string `json:"language"`

	// Symbols contains all symbols extracted from the file.
	// Symbols are in source order (top to bottom).
	// Note: Import statements appear here as SymbolKindImport entries.
	Symbols []*Symbol `json:"symbols"`

	// Imports lists all import statements with structured metadata.
	// Use this field for dependency resolution and library documentation seeding.
	// See Import type for details on the structured import data.
	Imports []Import `json:"imports"`

	// Package is the package/module name declared in the file.
	// May be empty for languages without package declarations.
	Package string `json:"package"`

	// ParsedAtMilli is the Unix timestamp in milliseconds when parsing completed.
	ParsedAtMilli int64 `json:"parsed_at_milli"`

	// ParseDurationMs is how long parsing took in milliseconds.
	ParseDurationMs int64 `json:"parse_duration_ms"`

	// Errors contains non-fatal parse errors encountered.
	// The parse may still produce partial results despite errors.
	Errors []string `json:"errors,omitempty"`

	// Hash is the SHA256 hash of the file content at parse time.
	// Used for cache invalidation and staleness detection.
	Hash string `json:"hash"`
}

type Parser interface {
	// Parse extracts symbols and metadata from source code.
	//
	// The method parses the provided content and returns a ParseResult containing
	// all extracted symbols, imports, and metadata. Parsing should be resilient
	// to syntax errors, returning partial results when possible.
	//
	// Parameters:
	//   - ctx: Context for cancellation. Long-running parses should check ctx.Done().
	//   - content: Raw source code bytes (must be valid UTF-8).
	//   - filePath: Path to the file (relative to project root, for ID generation).
	//
	// Returns:
	//   - *ParseResult: Extracted symbols and metadata. Never nil on success.
	//   - error: Non-nil only for complete parse failures (e.g., invalid UTF-8).
	//            Syntax errors are reported in ParseResult.Errors.
	//
	// Thread Safety:
	//   Implementations should be safe for concurrent use. Multiple goroutines
	//   may call Parse simultaneously with different content.
	Parse(ctx context.Context, content []byte, filePath string) (*ParseResult, error)

	// Language returns the canonical name of the language this parser handles.
	//
	// Returns a lowercase string identifying the language:
	//   - "go" for Go
	//   - "python" for Python
	//   - "typescript" for TypeScript
	//   - "javascript" for JavaScript
	//   - "html" for HTML
	//   - "css" for CSS
	//
	// This value is used for:
	//   - Setting ParseResult.Language and Symbol.Language
	//   - Parser selection based on file type
	//   - Logging and debugging
	Language() string

	// Extensions returns the file extensions this parser can handle.
	//
	// Returns a slice of extensions including the leading dot:
	//   - Go: [".go"]
	//   - Python: [".py", ".pyi"]
	//   - TypeScript: [".ts", ".tsx", ".mts", ".cts"]
	//   - JavaScript: [".js", ".jsx", ".mjs", ".cjs"]
	//   - HTML: [".html", ".htm"]
	//   - CSS: [".css"]
	//
	// Extensions are used by the parser registry to select the appropriate
	// parser for a given file. Extensions are case-sensitive and should
	// be lowercase.
	Extensions() []string
}

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

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

type PythonParserOption func(*PythonParser)

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

type SQLParserOption func(*SQLParserOptions)

type SQLParserOptions struct {
	// MaxFileSize is the maximum file size in bytes to parse.
	// Files larger than this return ErrFileTooLarge.
	// Default: 10MB
	MaxFileSize int

	// ExtractColumns determines whether to extract individual columns.
	// Default: true
	ExtractColumns bool
}

type Symbol struct {
	// ID is a unique identifier for this symbol.
	// Format: "file_path:start_line:name"
	// Example: "handlers/agent.go:27:HandleAgent"
	ID string `json:"id"`

	// Name is the symbol's identifier as it appears in source code.
	// Example: "HandleAgent", "UserService", "MAX_RETRIES"
	Name string `json:"name"`

	// Kind indicates what type of symbol this is (function, struct, etc.).
	Kind SymbolKind `json:"kind"`

	// FilePath is the path to the containing file, relative to project root.
	FilePath string `json:"file_path"`

	// StartLine is the 1-indexed line number where the symbol definition starts.
	StartLine int `json:"start_line"`

	// EndLine is the 1-indexed line number where the symbol definition ends.
	EndLine int `json:"end_line"`

	// StartCol is the 0-indexed column where the symbol starts on StartLine.
	StartCol int `json:"start_col"`

	// EndCol is the 0-indexed column where the symbol ends on EndLine.
	EndCol int `json:"end_col"`

	// Signature is the type signature or declaration.
	// Example: "func(ctx context.Context) error" for a Go function.
	Signature string `json:"signature"`

	// DocComment is the documentation comment associated with the symbol.
	// Extracted from preceding comment blocks (GoDoc, docstrings, JSDoc, etc.).
	DocComment string `json:"doc_comment"`

	// Receiver is the receiver type name for methods.
	// Empty for non-method symbols.
	// Example: "UserService" for method "func (s *UserService) Create(...)"
	Receiver string `json:"receiver"`

	// Package is the package or module name containing this symbol.
	// Example: "handlers" for Go, "myapp.services" for Python.
	Package string `json:"package"`

	// Exported indicates whether the symbol is publicly visible.
	// In Go: starts with uppercase. In Python: not prefixed with underscore.
	// In TypeScript: has "export" keyword.
	Exported bool `json:"exported"`

	// Language is the programming language of the source file.
	// Example: "go", "python", "typescript"
	Language string `json:"language"`

	// ParsedAtMilli is the Unix timestamp in milliseconds when this symbol was parsed.
	// Used for cache invalidation and staleness detection.
	ParsedAtMilli int64 `json:"parsed_at_milli"`

	// Children contains nested symbols (e.g., methods within a class).
	// May be nil if the symbol has no children.
	Children []*Symbol `json:"children,omitempty"`

	// Metadata contains language-specific additional information.
	// Examples: decorators for Python, generics for TypeScript.
	// Keys are well-defined strings, not arbitrary data.
	Metadata *SymbolMetadata `json:"metadata,omitempty"`

	// Calls contains function/method calls made within this symbol's body.
	// Only populated for functions and methods during AST parsing.
	// Used by the graph builder to create EdgeTypeCalls edges.
	// See GR-41: Call Edge Extraction for find_callers/find_callees.
	Calls []CallSite `json:"calls,omitempty"`

	// TypeReferences contains type identifiers referenced in this symbol's type annotations.
	// Populated for functions/methods (parameter types, return types) and variables (type annotations).
	// Used by the graph builder to create EdgeTypeReferences edges.
	// IT-06 Bug 9: Enables graph-based discovery of type usage across the codebase.
	// Primitives and language-specific constructs (e.g., str, int, Optional, List) are excluded.
	TypeReferences []TypeReference `json:"type_references,omitempty"`
}

type SymbolKind int

type SymbolMetadata struct {
	// Decorators lists decorator/annotation names applied to the symbol.
	// Example: ["staticmethod", "cache"] for Python.
	Decorators []string `json:"decorators,omitempty"`

	// DecoratorArgs maps decorator names to their argument identifiers.
	// Only populated when a decorator has arguments that reference symbols.
	// Example: {"UseInterceptors": ["LoggingInterceptor"], "Module": ["UserService"]}
	// IT-03a A-3: Enables EdgeTypeReferences from decorated symbol to decorator arguments.
	DecoratorArgs map[string][]string `json:"decorator_args,omitempty"`

	// TypeParameters lists generic type parameter names.
	// Example: ["T", "U"] for TypeScript generic function.
	TypeParameters []string `json:"type_parameters,omitempty"`

	// TypeArguments lists type identifiers used as generic arguments in the symbol's type annotations.
	// IT-03a C-2: Tracks type arguments like User in Promise<User>, Handler in Map<string, Handler>.
	// Only populated for non-primitive type names (skips string, number, boolean, etc.).
	TypeArguments []string `json:"type_arguments,omitempty"`

	// ReturnType is the declared return type (if available).
	// Example: "Promise<User>" for TypeScript async function.
	ReturnType string `json:"return_type,omitempty"`

	// IsAsync indicates if the function/method is asynchronous.
	IsAsync bool `json:"is_async,omitempty"`

	// IsGenerator indicates if the function is a generator.
	IsGenerator bool `json:"is_generator,omitempty"`

	// IsAbstract indicates if the class/method is abstract.
	IsAbstract bool `json:"is_abstract,omitempty"`

	// IsStatic indicates if the method is static.
	IsStatic bool `json:"is_static,omitempty"`

	// AccessModifier is the access level (public, private, protected).
	// Empty string means default/public access.
	AccessModifier string `json:"access_modifier,omitempty"`

	// Implements lists interface names that a class/struct implements.
	// For languages with explicit implements (TypeScript, Java), this is populated
	// by the parser. For Go, this is populated by the graph builder via
	// method-set matching (see GR-40).
	Implements []string `json:"implements,omitempty"`

	// Extends is the parent class name for inheritance.
	Extends string `json:"extends,omitempty"`

	// Methods contains method signatures for interfaces and types.
	// For interfaces: lists required method signatures.
	// For structs/types: lists methods with receivers matching this type.
	// Used for Go interface implementation detection via method-set matching (GR-40).
	Methods []MethodSignature `json:"methods,omitempty"`

	// IsConstructor indicates a JavaScript constructor function (uses this.x = ...).
	// IT-03a B-1: Constructor functions are reclassified as SymbolKindClass for graph visibility.
	IsConstructor bool `json:"is_constructor,omitempty"`

	// TypeNarrowings lists type identifiers used in type narrowing expressions.
	// IT-03a C-3: Tracks types referenced via instanceof, typeof, and type predicates.
	// Example: ["Router", "Response"] for code containing `x instanceof Router`.
	TypeNarrowings []string `json:"type_narrowings,omitempty"`

	// IsOverload indicates the symbol is a Python @overload stub (type-checking only).
	// IT-06c H-3: Overload stubs have no function body (just `...`) and zero callees.
	// The actual implementation is the same-name function WITHOUT @overload.
	// Symbol resolution should prefer non-overload symbols over overload stubs.
	IsOverload bool `json:"is_overload,omitempty"`

	// PrototypeOf indicates this symbol was assigned via Foo.prototype.method = ...
	// IT-03a B-2: Links prototype method assignments to their constructor function.
	PrototypeOf string `json:"prototype_of,omitempty"`

	// CSSSelector is the full CSS selector for CSS symbols.
	CSSSelector string `json:"css_selector,omitempty"`

	// ParentName is the parent symbol name (e.g., table name for columns).
	ParentName string `json:"parent_name,omitempty"`

	// SQLConstraints lists SQL constraints for columns (PRIMARY KEY, UNIQUE, etc.).
	SQLConstraints []string `json:"sql_constraints,omitempty"`

	// HeadingLevel is the heading level (1-6) for Markdown headings.
	HeadingLevel int `json:"heading_level,omitempty"`

	// CodeLanguage is the language identifier for fenced code blocks.
	// Example: "go", "python", "javascript"
	CodeLanguage string `json:"code_language,omitempty"`

	// ListType is the type of list: "ordered" or "unordered".
	ListType string `json:"list_type,omitempty"`

	// ListItems is the number of items in a list.
	ListItems int `json:"list_items,omitempty"`

	// LinkURL is the destination URL for link reference definitions.
	LinkURL string `json:"link_url,omitempty"`

	// LinkTitle is the optional title for link reference definitions.
	LinkTitle string `json:"link_title,omitempty"`
}

type TypeReference struct {
	// Name is the type identifier as it appears in source code.
	// This is the unqualified name (e.g., "Series", not "pandas.Series").
	// Primitives and language constructs are excluded at extraction time.
	Name string `json:"name"`

	// Location is where the type reference appears in the source file.
	Location Location `json:"location"`
}

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

type TypeScriptParserOption func(*TypeScriptParser)

type ValidationError struct {
	Field   string
	Message string
}

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

type YAMLParserOption func(*YAMLParserOptions)

type YAMLParserOptions struct {
	// MaxFileSize is the maximum file size in bytes to parse.
	// Files larger than this return ErrFileTooLarge.
	// Default: 10MB
	MaxFileSize int

	// MaxKeyDepth is the maximum nesting depth for key extraction.
	// 0 = top-level only, 1 = one level deep, etc.
	// Default: 3
	MaxKeyDepth int

	// ExtractAnchors determines whether to extract anchor definitions.
	// Default: true
	ExtractAnchors bool
}