entry.go raw

   1  // Package cartography builds a bidirectional English↔Go atlas of the codebase.
   2  //
   3  // The atlas maps every Go declaration to an English description with API
   4  // contracts and validation criteria. It works in two phases:
   5  //   - Mechanical extraction (zero oracle calls): go/ast parsing gives signatures,
   6  //     doc comments, test associations, and side-effect detection.
   7  //   - Oracle enrichment (rate-limited, iterative): the organism revises its
   8  //     lowest-confidence descriptions over generations.
   9  //
  10  // The atlas is bidirectional: Go path → English description via LookupGo,
  11  // and English concept → Go code path via LookupEnglish.
  12  package cartography
  13  
  14  // Entry is a single declaration in the atlas.
  15  type Entry struct {
  16  	// Identity (Go side — mechanical).
  17  	ID       string `json:"id"`                 // "lattice.Bond" or "lattice.Node.Dissolve"
  18  	Kind     string `json:"kind"`               // "func", "method", "type", "interface", "const", "var"
  19  	Package  string `json:"package"`            // package name
  20  	Name     string `json:"name"`               // declaration name
  21  	Receiver string `json:"receiver,omitempty"` // receiver type for methods
  22  	Exported bool   `json:"exported"`           // starts with uppercase
  23  	FilePath string `json:"file_path"`          // relative to project root
  24  	Line     int    `json:"line"`               // source line number
  25  
  26  	// Contract (mechanical from signature + oracle-enriched).
  27  	Signature   string       `json:"signature"`              // full Go signature text
  28  	Params      []ParamInfo  `json:"params,omitempty"`       // parameter names, types, semantics
  29  	Returns     []ReturnInfo `json:"returns,omitempty"`      // return types, error conditions
  30  	DocComment  string       `json:"doc_comment,omitempty"`  // existing Go doc comment
  31  	DependsOn   []string     `json:"depends_on,omitempty"`   // IDs of other entries this calls
  32  	SideEffects []string     `json:"side_effects,omitempty"` // "spawns goroutine", "file I/O", etc.
  33  
  34  	// English (starts mechanical, oracle-refined).
  35  	Description string `json:"description"`            // what it does + why
  36  	Contract    string `json:"contract,omitempty"`     // "takes X, returns Y, errors when Z"
  37  	EdgeCases   string `json:"edge_cases,omitempty"`   // oracle-enriched: nil/empty/zero behavior
  38  
  39  	// Validation (from test files).
  40  	HasTest      bool     `json:"has_test"`                  // whether a corresponding test exists
  41  	TestFuncs    []string `json:"test_funcs,omitempty"`      // ["TestBond", "TestBond_NilElement"]
  42  	TestFile     string   `json:"test_file,omitempty"`       // path to the test file
  43  	TestPatterns []string `json:"test_patterns,omitempty"`   // test table case names
  44  	Validation   string   `json:"validation,omitempty"`      // "tested with nil, empty, and valid inputs"
  45  
  46  	// Concepts (bidirectional index keys).
  47  	Concepts []string `json:"concepts,omitempty"` // ["lattice", "bond", "element"]
  48  
  49  	// Fitness.
  50  	Confidence float64 `json:"confidence"` // 0.3 mechanical, 0.5 +tests, 0.7 oracle, 0.9 validated
  51  	Source     string  `json:"source"`     // "mechanical", "oracle", "self-revised"
  52  	Revision   int     `json:"revision"`   // generation number of last revision
  53  }
  54  
  55  // ParamInfo describes a function parameter.
  56  type ParamInfo struct {
  57  	Name     string `json:"name"`
  58  	Type     string `json:"type"`
  59  	Semantic string `json:"semantic,omitempty"` // oracle-enriched: what this param means
  60  }
  61  
  62  // ReturnInfo describes a return value.
  63  type ReturnInfo struct {
  64  	Type      string `json:"type"`
  65  	Semantic  string `json:"semantic,omitempty"`   // oracle-enriched
  66  	IsError   bool   `json:"is_error,omitempty"`   // whether this is an error return
  67  	ErrorCond string `json:"error_cond,omitempty"` // when this error occurs
  68  }
  69