@fro.bot/systematic 3.30.1 → 3.31.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -11,7 +11,8 @@
11
11
  * carry the same `trust: 'project-or-higher'` meta inline here.
12
12
  *
13
13
  * Trust, per field: `enabled` and `allow_project_sources` are user-only (user
14
- * config and `OPENCODE_CONFIG_DIR` config). A project config may set `sources`
14
+ * config and `OPENCODE_CONFIG_DIR` config, each with the `systematic.local`
15
+ * file beside it). A project config may set `sources`
15
16
  * only. `config.ts` strips the two user-only fields from a project with
16
17
  * per-path warnings, validates the project's `sources` with the validators
17
18
  * here, and then discards them; the per-call reader is their only consumer.
@@ -44,6 +45,7 @@ export declare const SearchSourceSchema: z.ZodObject<{
44
45
  }>;
45
46
  roots: z.ZodArray<z.ZodString>;
46
47
  projects: z.ZodOptional<z.ZodArray<z.ZodString>>;
48
+ exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
47
49
  }, z.core.$strict>;
48
50
  export type SearchSourceEntry = z.output<typeof SearchSourceSchema>;
49
51
  /**
@@ -66,6 +68,7 @@ export declare const SearchSettingsSchema: z.ZodObject<{
66
68
  }>;
67
69
  roots: z.ZodArray<z.ZodString>;
68
70
  projects: z.ZodOptional<z.ZodArray<z.ZodString>>;
71
+ exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
69
72
  }, z.core.$strict>>>;
70
73
  }, z.core.$strict>;
71
74
  /** What a successful parse of the `search` block yields. Assignable to the core's `SearchSettings`. */
@@ -89,7 +92,48 @@ export interface SearchConfigValidation {
89
92
  readonly structural: boolean;
90
93
  /** Bounded warnings. They name fields and source names, never a value. */
91
94
  readonly warnings: readonly string[];
95
+ /**
96
+ * Every source entry that was dropped whole, with the label the warning
97
+ * uses (`"name"`, or `#index` when the name is unusable) and the reason. A
98
+ * dropped exclude pattern is not listed here: its source stays.
99
+ */
100
+ readonly dropped: readonly DroppedSearchEntry[];
101
+ /**
102
+ * Every entry of `sources`, in array order, with the warnings that entry
103
+ * produced. These are the same messages as in `warnings`, kept with the
104
+ * entry so a caller never has to match them by name.
105
+ */
106
+ readonly entries: readonly SearchEntryOutcome[];
92
107
  }
108
+ /**
109
+ * What validation made of one entry of a `sources` array. A kept outcome holds
110
+ * the validated entry itself, so the entry a merge keeps can be traced back to
111
+ * the warnings of its own declaration. `warnings` holds only the messages that
112
+ * were listed; a message past the cap is counted, not kept.
113
+ */
114
+ export type SearchEntryOutcome = {
115
+ readonly kind: 'kept';
116
+ readonly index: number;
117
+ readonly label: string;
118
+ readonly entry: SearchSourceEntry;
119
+ readonly warnings: readonly string[];
120
+ } | {
121
+ readonly kind: 'dropped';
122
+ readonly index: number;
123
+ readonly label: string;
124
+ readonly reason: string;
125
+ readonly warnings: readonly string[];
126
+ };
127
+ /** One source entry the validator dropped, as the warning names it. */
128
+ export interface DroppedSearchEntry {
129
+ readonly label: string;
130
+ readonly reason: string;
131
+ }
132
+ /**
133
+ * Escape control characters and cap the length of a path before it goes into a
134
+ * warning. The CLI uses it for exception text too.
135
+ */
136
+ export declare function displaySafe(text: string): string;
93
137
  /**
94
138
  * Validate a raw `search` value field by field and entry by entry, so a
95
139
  * typo in `sources` can never lose `enabled: false`. This is the one
@@ -103,6 +147,13 @@ export interface SearchConfigValidation {
103
147
  * never a value.
104
148
  */
105
149
  export declare function validateSearchConfig(value: unknown, trust: SearchConfigTrust, sourcePath: string): SearchConfigValidation;
150
+ /**
151
+ * The warnings of a validation, less the ones about a single source entry (a
152
+ * dropped entry, a dropped `exclude` pattern). Those name a proposal; what is
153
+ * left names fields only. A caller that must not name the proposals of a
154
+ * project that is not allowed uses this on that project's file.
155
+ */
156
+ export declare function withoutEntryWarnings(validation: Pick<SearchConfigValidation, 'entries' | 'warnings'>): readonly string[];
106
157
  /**
107
158
  * One source's `search` block after schema validation. `settings` is the
108
159
  * schema-parsed block, absent when the source has none. `unreadable` is true
@@ -111,22 +162,40 @@ export declare function validateSearchConfig(value: unknown, trust: SearchConfig
111
162
  export interface SearchSettingsSource {
112
163
  readonly settings?: SearchSchemaOutput | undefined;
113
164
  readonly unreadable: boolean;
165
+ /** The layer this source was read from. Callers that do not track layers leave it out. */
166
+ readonly layer?: UserLevelLayer | undefined;
114
167
  }
115
168
  export interface MergedSearchSettings {
116
169
  readonly settings: SearchSchemaOutput | undefined;
117
170
  readonly unreadable: boolean;
171
+ /**
172
+ * The layer each surviving source entry came from, by source name: the layer
173
+ * of the last source that defined that name. Names defined only by sources
174
+ * with no `layer` are absent.
175
+ */
176
+ readonly sourceLayers: ReadonlyMap<string, UserLevelLayer>;
118
177
  }
119
178
  /**
120
179
  * The one merge rule, used by both `config.ts` and the reader. Sources arrive
121
- * in priority order, user then custom. `enabled` takes the last source that
122
- * defines it, `allow_project_sources` is the union, and `sources` merge by
123
- * name with the later source winning (in the earlier entry's position).
124
- * `unreadable` is set when any source was.
180
+ * in priority order: user, user.local, custom, custom.local. `enabled` takes
181
+ * the last source that defines it, `allow_project_sources` is the union, and
182
+ * `sources` merge by name with the later source replacing the earlier entry
183
+ * whole (in the earlier entry's position). `unreadable` is set when any source
184
+ * was.
125
185
  */
126
186
  export declare function mergeSearchSettings(sources: readonly SearchSettingsSource[]): MergedSearchSettings;
127
187
  /**
128
- * Pick a config file in `dir`: `<basename>.jsonc` when it exists, else the
129
- * `.json` path (returned even when absent, so callers that stat it still work).
188
+ * Whether `target` is a directory entry, a symlink included. Selection asks
189
+ * this instead of `existsSync` because `existsSync` follows a link: a dangling
190
+ * link would read as absent, and a lower-priority file would win over it. An
191
+ * entry that cannot be inspected for a reason other than absence counts as
192
+ * present, so the read that follows reports it.
193
+ */
194
+ export declare function configEntryExists(target: string): boolean;
195
+ /**
196
+ * Pick a config file in `dir`: `<basename>.jsonc` when its entry exists, else
197
+ * the `.json` path (returned even when absent, so callers that stat it still
198
+ * work). A dangling `.jsonc` link is selected, and its read reports it.
130
199
  */
131
200
  export declare function selectConfigFile(dir: string, basename: string): string;
132
201
  export interface UserLevelConfigDirOptions {
@@ -146,17 +215,121 @@ export interface UserLevelConfigDirs {
146
215
  * a blank value counts as unset. `config.ts` and the reader both call this.
147
216
  */
148
217
  export declare function resolveUserLevelConfigDirs(options?: UserLevelConfigDirOptions): UserLevelConfigDirs;
218
+ /** The four user-level layers, in the order their search settings merge. */
219
+ export type UserLevelLayer = 'user' | 'user.local' | 'custom' | 'custom.local';
220
+ /** One selected user-level file: the layer it feeds and the path to read. */
221
+ export interface UserLevelConfigFile {
222
+ readonly layer: UserLevelLayer;
223
+ readonly path: string;
224
+ }
225
+ export interface UserLevelFileSelection {
226
+ /**
227
+ * The selected files in layer order: user, user.local, then custom and
228
+ * custom.local when a custom directory is set. A local file is selected even
229
+ * when its sibling is absent, and the path of an absent file is still
230
+ * returned (`selectConfigFile` rule).
231
+ */
232
+ readonly files: readonly UserLevelConfigFile[];
233
+ /**
234
+ * The custom directory is the user directory, spelled the same way or
235
+ * reached through a symlink. The custom layers stay in `files` so the custom
236
+ * file keeps its precedence, but they name the same two files as `user` and
237
+ * `user.local`: a reader reads each file once and reuses the result.
238
+ */
239
+ readonly aliased: boolean;
240
+ }
241
+ /**
242
+ * Pick the user-level config files for the resolved directories. The
243
+ * basenames are `systematic` and `systematic.local`, each choosing `.jsonc`
244
+ * before `.json`. Selection looks at existence only, never validity.
245
+ */
246
+ export declare function selectUserLevelConfigFiles(dirs: UserLevelConfigDirs): UserLevelFileSelection;
247
+ export interface ProjectConfigSelection {
248
+ /** The project file to read. When none exists, the `.opencode/systematic.json` path. */
249
+ readonly path: string;
250
+ /**
251
+ * The `.opencode/` file a repo-root file shadowed. Present only when a root
252
+ * file won and an `.opencode/` file also exists.
253
+ */
254
+ readonly ignoredPath?: string;
255
+ }
256
+ /**
257
+ * Pick the project config file under the repository root: `.systematic.jsonc`,
258
+ * else `.systematic.json`, else `.opencode/systematic.jsonc`, else
259
+ * `.opencode/systematic.json`. A root file wins even when invalid; selection
260
+ * looks at the directory entry only (a dangling link is a file that exists)
261
+ * and never falls back past a broken file.
262
+ */
263
+ export declare function selectProjectConfigFile(repoRoot: string): ProjectConfigSelection;
264
+ /**
265
+ * The start directory's own `.opencode/systematic.*` file when the repository
266
+ * root is a different directory: a file that is never read, because project
267
+ * config comes from the root. `repoRoot` is the lookup of the start directory
268
+ * (`lookupSearchRoot`). The file is not reported when it is the selected one
269
+ * (the same file reached through a link). Both the config loader and the
270
+ * per-call reader ask this, so they warn under the same condition.
271
+ */
272
+ export declare function findStartDirProjectConfig(startDir: string, repoRoot: {
273
+ readonly root: string;
274
+ readonly foundGit: boolean;
275
+ }, selectedProjectConfig: string): string | undefined;
276
+ /**
277
+ * The warning for a start directory's own project file that is not read.
278
+ * `safe` makes each path fit for a message; the config loader passes its own
279
+ * sanitizer, and the default is `displaySafe`.
280
+ */
281
+ export declare function startDirProjectWarning(startDirConfig: string, projectRoot: string, selectedProjectConfig: string, safe?: (text: string) => string): string;
149
282
  export interface UserLevelSearchLoad {
150
283
  readonly settings: SearchSchemaOutput | undefined;
151
284
  readonly warnings: readonly string[];
152
285
  readonly unreadable: boolean;
286
+ /**
287
+ * Every source entry the validator dropped whole, across the files read,
288
+ * with the label the warning uses and the reason.
289
+ */
290
+ readonly dropped: readonly DroppedSearchEntry[];
291
+ /**
292
+ * Every entry of `sources` in every file read, in file order then array
293
+ * order, with the warnings that entry produced (`SearchEntryOutcome`). A
294
+ * file two layers share is listed once.
295
+ */
296
+ readonly entries: readonly SearchEntryOutcome[];
297
+ /** The layer each surviving source entry came from, by source name (`mergeSearchSettings`). */
298
+ readonly sourceLayers: ReadonlyMap<string, UserLevelLayer>;
299
+ /**
300
+ * The subset of `warnings` that report a file that could not be read or
301
+ * parsed, as opposed to a problem inside a readable `search` block. A caller
302
+ * that already named those files can leave them out.
303
+ */
304
+ readonly readFailures: readonly string[];
153
305
  }
306
+ export type TextRead = {
307
+ readonly kind: 'absent';
308
+ } | {
309
+ readonly kind: 'failed';
310
+ readonly reason: string;
311
+ } | {
312
+ readonly kind: 'text';
313
+ readonly content: string;
314
+ };
154
315
  /** Largest project config file the bin-safe project reader accepts. */
155
316
  export declare const MAX_PROJECT_CONFIG_BYTES: number;
156
317
  /**
157
- * Read the `search` block from the two user-level files, user then custom, and
158
- * merge them. It never reads project config and never throws: an unparseable
159
- * file or an invalid block gives one warning and `unreadable: true`.
318
+ * Read a text file with the shared bounded fd read: never more than
319
+ * `maxBytes + 1` bytes, regular files only, and a non-blocking open so a FIFO
320
+ * planted at the path cannot hang the reader.
321
+ */
322
+ export declare function readTextBounded(filePath: string, maxBytes: number): TextRead;
323
+ /**
324
+ * Read the `search` block from the user-level files and merge them: user,
325
+ * user.local, then custom and custom.local when a custom directory is set. A
326
+ * local file is read with or without its sibling. It never reads project
327
+ * config and never throws: an unparseable file or an invalid block gives one
328
+ * warning and `unreadable: true`, and the valid remainder still merges.
329
+ *
330
+ * When the custom directory is the user directory, each file is read once and
331
+ * its diagnostics are reported once; the custom layers still take their
332
+ * place in the merge order.
160
333
  */
161
334
  export declare function loadUserLevelSearchSettings(options?: UserLevelConfigDirOptions): UserLevelSearchLoad;
162
335
  export interface ProjectSearchLoad {
@@ -171,12 +344,19 @@ export interface ProjectSearchLoad {
171
344
  * alone does not set it. This is not the user-config `config unreadable` note.
172
345
  */
173
346
  readonly unreadable: boolean;
347
+ /** Every source entry dropped whole, with the label the warning uses and the reason. */
348
+ readonly dropped: readonly DroppedSearchEntry[];
349
+ /** Every entry of the file's `sources`, in array order, with the warnings that entry produced. */
350
+ readonly entries: readonly SearchEntryOutcome[];
174
351
  }
175
352
  /**
176
353
  * Read the sources a project config proposes, from the checkout root's
177
- * `.opencode/systematic.jsonc` (falling back to `.json`, as `getConfigPaths`
178
- * in `config.ts` does). Bin-safe: it needs no `config.ts`. The read is capped
179
- * at `MAX_PROJECT_CONFIG_BYTES`, the file is validated with the project rules
354
+ * project file: `.systematic.jsonc`, else `.systematic.json`, else
355
+ * `.opencode/systematic.jsonc`, else `.opencode/systematic.json`
356
+ * (`selectProjectConfigFile`). A root file shadowing an `.opencode/` file is
357
+ * reported in `warnings`; the two are never merged, and a broken winner never
358
+ * falls back. Bin-safe: it needs no `config.ts`. The read is capped at
359
+ * `MAX_PROJECT_CONFIG_BYTES`, the file is validated with the project rules
180
360
  * (`sources` only; `enabled` and `allow_project_sources` are never read), and
181
361
  * it never throws. A missing file or a missing `search` block is normal.
182
362
  */