feat(cartographer): add ReplaceContent and ExtractContent FFI bindings

- ReplaceOptions/ReplaceResult/FileChange/DiffLine types for sed-like replace
- ExtractOptions/ExtractResult/ExtractMatch/CountEntry types for awk-like extract
- ReplaceContent() and ExtractContent() in real bridge + stubs
- Matches cartographer v1.8.0 FFI surface

Author: SimplyLiz

internal/cartographer/bridge.go

@@ -408,3 +408,72 @@ func GetModuleContext(path, moduleID string, depth uint32) (*ModuleContext, erro
 	}
 	return &ctx, nil
 }
+
+// ReplaceContent performs a regex find-and-replace across project files.
+// replacement supports $0 (whole match) and $1/$2 (capture groups).
+// When opts.DryRun is true, no files are written.
+func ReplaceContent(path, pattern, replacement string, opts *ReplaceOptions) (*ReplaceResult, error) {
+	cPath := C.CString(path)
+	defer C.free(unsafe.Pointer(cPath))
+
+	cPattern := C.CString(pattern)
+	defer C.free(unsafe.Pointer(cPattern))
+
+	cReplacement := C.CString(replacement)
+	defer C.free(unsafe.Pointer(cReplacement))
+
+	var cOpts *C.char
+	if opts != nil {
+		b, err := json.Marshal(opts)
+		if err != nil {
+			return nil, &CartographerError{err.Error()}
+		}
+		cOpts = C.CString(string(b))
+		defer C.free(unsafe.Pointer(cOpts))
+	}
+
+	resp, err := callFFI(func() *C.char {
+		return C.cartographer_replace_content(cPath, cPattern, cReplacement, cOpts)
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	var result ReplaceResult
+	if err := json.Unmarshal(resp.Data, &result); err != nil {
+		return nil, &CartographerError{err.Error()}
+	}
+	return &result, nil
+}
+
+// ExtractContent extracts capture-group values from regex matches across project files.
+func ExtractContent(path, pattern string, opts *ExtractOptions) (*ExtractResult, error) {
+	cPath := C.CString(path)
+	defer C.free(unsafe.Pointer(cPath))
+
+	cPattern := C.CString(pattern)
+	defer C.free(unsafe.Pointer(cPattern))
+
+	var cOpts *C.char
+	if opts != nil {
+		b, err := json.Marshal(opts)
+		if err != nil {
+			return nil, &CartographerError{err.Error()}
+		}
+		cOpts = C.CString(string(b))
+		defer C.free(unsafe.Pointer(cOpts))
+	}
+
+	resp, err := callFFI(func() *C.char {
+		return C.cartographer_extract_content(cPath, cPattern, cOpts)
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	var result ExtractResult
+	if err := json.Unmarshal(resp.Data, &result); err != nil {
+		return nil, &CartographerError{err.Error()}
+	}
+	return &result, nil
+}

internal/cartographer/bridge_stub.go

@@ -27,4 +27,6 @@ func Semidiff(_, _, _ string) ([]SemidiffFile, error)
 func RankedSkeleton(_ string, _ []string, _ uint32) (*RankedSkeletonResult, error)            { return nil, ErrUnavailable }
 func UnreferencedSymbols(_ string) (*UnreferencedSymbolsResult, error)                        { return nil, ErrUnavailable }
 func SearchContent(_, _ string, _ *SearchContentOptions) (*SearchResult, error)               { return nil, ErrUnavailable }
-func FindFiles(_, _ string, _ uint32, _ *FindOptions) (*FindResult, error) { return nil, ErrUnavailable }
+func FindFiles(_, _ string, _ uint32, _ *FindOptions) (*FindResult, error)             { return nil, ErrUnavailable }
+func ReplaceContent(_, _, _ string, _ *ReplaceOptions) (*ReplaceResult, error)        { return nil, ErrUnavailable }
+func ExtractContent(_, _ string, _ *ExtractOptions) (*ExtractResult, error)           { return nil, ErrUnavailable }

internal/cartographer/types.go

@@ -257,6 +257,89 @@ type FindResult struct {
 	Truncated    bool       `json:"truncated"`
 }
 
+// ---------------------------------------------------------------------------
+// Replace types
+// ---------------------------------------------------------------------------
+
+// ReplaceOptions controls replace_content behaviour.
+type ReplaceOptions struct {
+	Literal      bool    `json:"literal,omitempty"`
+	CaseSensitive *bool  `json:"caseSensitive,omitempty"`
+	WordRegexp   bool    `json:"wordRegexp,omitempty"`
+	DryRun       bool    `json:"dryRun,omitempty"`
+	Backup       bool    `json:"backup,omitempty"`
+	ContextLines *int    `json:"contextLines,omitempty"`
+	FileGlob     string  `json:"fileGlob,omitempty"`
+	ExcludeGlob  string  `json:"excludeGlob,omitempty"`
+	SearchPath   string  `json:"searchPath,omitempty"`
+	NoIgnore     bool    `json:"noIgnore,omitempty"`
+	MaxPerFile   int     `json:"maxPerFile,omitempty"`
+}
+
+// DiffLine is one line in a contextual diff produced by ReplaceContent.
+type DiffLine struct {
+	Kind        string `json:"kind"`       // "context", "removed", "added", "separator"
+	LineNumber  int    `json:"lineNumber"`
+	Content     string `json:"content"`
+}
+
+// FileChange describes the replacements made (or previewed) in one file.
+type FileChange struct {
+	Path         string     `json:"path"`
+	Replacements int        `json:"replacements"`
+	Diff         []DiffLine `json:"diff"`
+}
+
+// ReplaceResult is returned by ReplaceContent.
+type ReplaceResult struct {
+	FilesChanged      int          `json:"filesChanged"`
+	TotalReplacements int          `json:"totalReplacements"`
+	Changes           []FileChange `json:"changes"`
+	DryRun            bool         `json:"dryRun"`
+}
+
+// ---------------------------------------------------------------------------
+// Extract types
+// ---------------------------------------------------------------------------
+
+// ExtractOptions controls extract_content behaviour.
+type ExtractOptions struct {
+	Groups        []int   `json:"groups,omitempty"`
+	Separator     string  `json:"separator,omitempty"`
+	Format        string  `json:"format,omitempty"` // "text", "json", "csv", "tsv"
+	Count         bool    `json:"count,omitempty"`
+	Dedup         bool    `json:"dedup,omitempty"`
+	Sort          bool    `json:"sort,omitempty"`
+	CaseSensitive *bool   `json:"caseSensitive,omitempty"`
+	FileGlob      string  `json:"fileGlob,omitempty"`
+	ExcludeGlob   string  `json:"excludeGlob,omitempty"`
+	SearchPath    string  `json:"searchPath,omitempty"`
+	NoIgnore      bool    `json:"noIgnore,omitempty"`
+	Limit         int     `json:"limit,omitempty"`
+}
+
+// ExtractMatch is one extracted row.
+type ExtractMatch struct {
+	Path       string   `json:"path"`
+	LineNumber int      `json:"lineNumber"`
+	Groups     []string `json:"groups"`
+}
+
+// CountEntry is a frequency entry returned when ExtractOptions.Count is true.
+type CountEntry struct {
+	Value string `json:"value"`
+	Count int    `json:"count"`
+}
+
+// ExtractResult is returned by ExtractContent.
+type ExtractResult struct {
+	Matches       []ExtractMatch `json:"matches,omitempty"`
+	Counts        []CountEntry   `json:"counts,omitempty"`
+	Total         int            `json:"total"`
+	FilesSearched int            `json:"filesSearched"`
+	Truncated     bool           `json:"truncated"`
+}
+
 // CartographerError is returned when a Cartographer FFI call fails.
 type CartographerError struct {
 	Message string