Sentinel/sentinel.h at main · mercwar/Sentinel · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
/*
    sentinel.h

    PURPOSE:
        Sentinel is the root navigation engine for the repository.
        Robots use Sentinel to:
            - locate directories
            - index files
            - resolve paths
            - search for AVIS, CYBORG, NEXUS, DATALAKE
            - return to the Sentinel root
            - avoid getting lost in deep repo structures

        This header defines:
            - directory graph model
            - file index model
            - navigation API
            - search API
            - return-home API
*/

#ifndef SENTINEL_H
#define SENTINEL_H

#ifdef __cplusplus
extern "C" {
#endif

/* -------------------------------------------------------------
   BASIC TYPES
   ------------------------------------------------------------- */

typedef enum SenBool {
    SEN_FALSE = 0,
    SEN_TRUE  = 1
} SenBool;

typedef enum SenStatus {
    SEN_STATUS_OK = 0,
    SEN_STATUS_ERROR_INVALID_ARGUMENT,
    SEN_STATUS_ERROR_IO,
    SEN_STATUS_ERROR_NOT_FOUND,
    SEN_STATUS_ERROR_INTERNAL
} SenStatus;

typedef struct SenString {
    const char* data;
    int         length;
} SenString;

/* -------------------------------------------------------------
   FILE + DIRECTORY MODELS
   ------------------------------------------------------------- */

typedef struct SenFile {
    SenString path;
    SenString name;
} SenFile;

typedef struct SenFileList {
    SenFile* items;
    int      count;
} SenFileList;

typedef struct SenDirectory {
    SenString path;
    SenFileList files;
    struct SenDirectory** subdirs;
    int subdir_count;
} SenDirectory;

typedef struct SenRepoGraph {
    SenDirectory* root;
} SenRepoGraph;

/* -------------------------------------------------------------
   SENTINEL API
   ------------------------------------------------------------- */

/*
    sentinel_init

    PURPOSE:
        Initialize Sentinel and scan the repository root.
*/
SenStatus sentinel_init(const char* repo_root, SenRepoGraph* out_graph);

/*
    sentinel_free

    PURPOSE:
        Release all memory associated with the repo graph.
*/
void sentinel_free(SenRepoGraph* graph);

/*
    sentinel_find_directory

    PURPOSE:
        Locate a directory by name anywhere in the repo.
*/
SenStatus sentinel_find_directory(const SenRepoGraph* graph,
                                  const char* name,
                                  SenDirectory** out_dir);

/*
    sentinel_find_file

    PURPOSE:
        Locate a file by name anywhere in the repo.
*/
SenStatus sentinel_find_file(const SenRepoGraph* graph,
                             const char* name,
                             SenFile* out_file);

/*
    sentinel_search

    PURPOSE:
        Search for files matching a pattern (e.g., "*.c").
*/
SenStatus sentinel_search(const SenRepoGraph* graph,
                          const char* pattern,
                          SenFileList* out_list);

/*
    sentinel_return_home

    PURPOSE:
        Return the robot to the Sentinel root directory.
*/
SenStatus sentinel_return_home(const SenRepoGraph* graph,
                               SenDirectory** out_root);

/*
    sentinel_locate_language

    PURPOSE:
        Find AVIS, CYBORG, NEXUS, or DATALAKE directories.
*/
SenStatus sentinel_locate_language(const SenRepoGraph* graph,
                                   const char* lang_name,
                                   SenDirectory** out_dir);

#ifdef __cplusplus
}
#endif

#endif /* SENTINEL_H */