@fro.bot/systematic 3.29.1 → 3.30.0

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.
@@ -0,0 +1,92 @@
1
+ /**
2
+ * The per-call reader behind `kind: "external"`: it turns the user config
3
+ * files, the project config file and the project's identity into the ordered
4
+ * list of active sources for one call.
5
+ *
6
+ * Import rule: this module may import only node builtins, `search-corpus.ts`
7
+ * (for the checkout root walk), `search-project-identity.ts` and
8
+ * `search-user-config.ts`. It must never import `config.ts` or
9
+ * `config-schema.ts`: the `systematic-search` bin bundles it, and those would
10
+ * drag the whole config loader into that bundle.
11
+ *
12
+ * It holds no state. Every call re-reads the user files (the allow list and
13
+ * the user sources), the project file and the project identity, so editing
14
+ * any of them takes effect on the next call. `search.enabled` is not
15
+ * read here: it is fixed at init by each surface and never changes per call.
16
+ *
17
+ * Resolution order: proposals of a project that is not allowed are
18
+ * dropped, a user source mapped to this project shadows a same-named project
19
+ * source, user sources come before project sources, and the list caps at
20
+ * `MAX_ACTIVE_SOURCES`. Project-source problems never throw and never touch
21
+ * built-in replies; the caller decides how to word the states.
22
+ *
23
+ * Roots come back resolved to absolute paths and nothing more: existence,
24
+ * symlink and containment checks belong to the loader that reads them.
25
+ */
26
+ import { type ProjectIdentity } from './search-project-identity.js';
27
+ import { type SearchSourceFormat, type UserLevelConfigDirOptions } from './search-user-config.js';
28
+ /** At most this many sources are active in one call. */
29
+ export declare const MAX_ACTIVE_SOURCES = 8;
30
+ export type SourceOrigin = 'project' | 'user';
31
+ /** One source active for this call, with its roots resolved to absolute paths. */
32
+ export interface ActiveSource {
33
+ readonly name: string;
34
+ readonly format: SearchSourceFormat;
35
+ readonly roots: readonly string[];
36
+ readonly origin: SourceOrigin;
37
+ }
38
+ /**
39
+ * What the project's own config contributed.
40
+ *
41
+ * - `none`: no proposals (no file, no `search` block or no valid entry).
42
+ * - `allowed`: the project is allowed; `proposals` valid entries were considered.
43
+ * - `not-allowed`: the project proposes sources but its main root is not in the
44
+ * allow list. Carries the proposal count only, never a name or a root, and
45
+ * the main-root string only when the identity is verified.
46
+ * - `config-unreadable`: the project file had a structural error (a read or
47
+ * parse error, an oversized file, an invalid container), so it proposes
48
+ * nothing. Separate from the user-config `config unreadable` note.
49
+ */
50
+ export type ProjectState = {
51
+ readonly kind: 'none';
52
+ } | {
53
+ readonly kind: 'allowed';
54
+ readonly proposals: number;
55
+ } | {
56
+ readonly kind: 'not-allowed';
57
+ readonly proposals: number;
58
+ readonly mainRoot?: string;
59
+ } | {
60
+ readonly kind: 'config-unreadable';
61
+ };
62
+ export interface ExternalSourcesResolution {
63
+ /** Active sources in order: user sources, then project sources, at most `MAX_ACTIVE_SOURCES`. */
64
+ readonly sources: readonly ActiveSource[];
65
+ readonly project: ProjectState;
66
+ /**
67
+ * The user-level files this call read had a problem that changes what
68
+ * search does: a parse error, a bad allow entry, a non-array
69
+ * `sources`, an unknown key. The caller prints one `config unreadable`
70
+ * note; a repair between calls clears it.
71
+ */
72
+ readonly userConfigUnreadable: boolean;
73
+ /**
74
+ * Bounded warnings, the source-cap warning first, then user-file
75
+ * and project-file warnings. They name fields and source names, never a
76
+ * value. Each file's own list is bounded by its validator.
77
+ */
78
+ readonly warnings: readonly string[];
79
+ }
80
+ export interface ExternalSourcesInput {
81
+ /** The directory the checkout-root walk-up starts from. */
82
+ readonly startDir: string;
83
+ /** Config directory resolution, as the other user-level readers take it. Defaults to the home directory and `OPENCODE_CONFIG_DIR`. */
84
+ readonly configOptions?: UserLevelConfigDirOptions | undefined;
85
+ /** Override the identity of the checkout. Tests use this; surfaces leave it out. */
86
+ readonly identity?: ProjectIdentity | undefined;
87
+ }
88
+ /**
89
+ * Read everything for one `external` call and resolve the active sources.
90
+ * Never throws: every file problem is a state or a warning.
91
+ */
92
+ export declare function resolveExternalSources(input: ExternalSourcesInput): ExternalSourcesResolution;
@@ -0,0 +1,75 @@
1
+ /**
2
+ * The external source loader behind `kind: "external"`: turns the active
3
+ * sources of one call into bounded records, one load per source.
4
+ *
5
+ * It shares the corpus loader's walk (`discoverSourceFiles`), symlink rule and
6
+ * caps through `search-corpus.ts`, so a symlink is skipped at every depth and
7
+ * a source never reads past the file and byte limits. Sources only read files:
8
+ * nothing here spawns a process, opens a network connection or writes.
9
+ *
10
+ * Bounds: an external file may be 1 MB (built-in kinds stay at 256
11
+ * KiB), a source keeps the per-source `MAX_FILES` and `MAX_TOTAL_BYTES` caps,
12
+ * and every file the loader opens draws on one 32 MB budget shared by the
13
+ * sources of the call. A source that does not fit the remaining budget is
14
+ * dropped whole, before any of its files is read, and later, smaller sources
15
+ * are still tried.
16
+ *
17
+ * Import rule: node builtins, `search-corpus.ts` and the Deciduous reader
18
+ * (`search-external-deciduous.ts`), plus types. The Deciduous reader imports the
19
+ * corpus helpers and never this module. The loader holds no state, so each
20
+ * call re-reads the stores.
21
+ */
22
+ import type { ActiveSource, SourceOrigin } from './search-external-sources.js';
23
+ /** Largest single external file read, in bytes. Built-in kinds keep `MAX_FILE_BYTES`. */
24
+ export declare const EXTERNAL_MAX_FILE_BYTES: number;
25
+ /** Bytes all sources of one call may open between them. */
26
+ export declare const EXTERNAL_TOTAL_BUDGET_BYTES: number;
27
+ /**
28
+ * One searchable external record. `nodeType` is set by the Deciduous loader
29
+ * only; `status` is the recorded status string, never inferred.
30
+ */
31
+ export interface ExternalRecord {
32
+ readonly source: string;
33
+ readonly origin: SourceOrigin;
34
+ /** `<source>/<path relative to the root>`, with `/` separators. */
35
+ readonly path: string;
36
+ readonly title: string;
37
+ readonly status?: string;
38
+ readonly nodeType?: string;
39
+ readonly body: string;
40
+ }
41
+ /**
42
+ * What loading one source found.
43
+ *
44
+ * - `loaded`: at least one record.
45
+ * - `empty`: the root exists and holds no readable record.
46
+ * - `missing`: no root exists (quiet).
47
+ * - `unreadable`: no root could be read for an access or I/O reason.
48
+ * - `dropped`: the source was not read: a bad root or no room in the shared
49
+ * budget. A named warning says which.
50
+ */
51
+ export type SourceState = 'loaded' | 'empty' | 'missing' | 'unreadable' | 'dropped';
52
+ export interface SourceLoad {
53
+ readonly name: string;
54
+ readonly origin: SourceOrigin;
55
+ readonly state: SourceState;
56
+ readonly records: readonly ExternalRecord[];
57
+ /** Bounded, sanitised, in deterministic order. They name the source, never a link target. */
58
+ readonly warnings: readonly string[];
59
+ }
60
+ export interface LoadExternalSourcesInput {
61
+ /** The active sources in the order the resolver returned them; also the order of the result and of budget use. */
62
+ readonly sources: readonly ActiveSource[];
63
+ /** The checkout root project roots must stay inside. */
64
+ readonly checkoutRoot: string;
65
+ /** Bytes the sources may open between them. Defaults to the 32 MB budget; tests inject a small one. */
66
+ readonly budgetBytes?: number | undefined;
67
+ /** Directory entries each source may examine. Defaults to `MAX_LISTED_ENTRIES`; tests inject a small one. */
68
+ readonly entryBudget?: number | undefined;
69
+ }
70
+ /**
71
+ * Load every active source, in order, against one shared read budget. Never
72
+ * throws: a failure becomes a state and a bounded warning, and the other
73
+ * sources still load.
74
+ */
75
+ export declare function loadExternalSources(input: LoadExternalSourcesInput): SourceLoad[];
@@ -0,0 +1,42 @@
1
+ /**
2
+ * Project identity for external search sources: the main repository root of a
3
+ * checkout, derived by filesystem reads alone, and the exact-path allow match.
4
+ *
5
+ * Imports node builtins and `search-bounded-read.ts` (node builtins only)
6
+ * only, because the `systematic-search` bin bundles it. Never throws: anything
7
+ * corrupt, inconsistent or unreadable is `unresolved`, and an unresolved
8
+ * identity matches no allow entry.
9
+ *
10
+ * A linked worktree is verified from the common-directory side. The `.git`
11
+ * file is attacker-writable (it ships inside a cloned project), so it is only
12
+ * a claim: the claimed gitdir must be `<commondir>/worktrees/<name>`, and that
13
+ * entry's own `gitdir` back-pointer must name this exact `.git`. A forged
14
+ * `.git` cannot satisfy both, because the real common directory's entries
15
+ * point at the real worktrees.
16
+ */
17
+ export type UnresolvedReason = 'not-a-checkout' | 'symlinked-git' | 'corrupt-git-file' | 'unsupported-layout' | 'missing-commondir' | 'inconsistent' | 'core-worktree' | 'unreadable';
18
+ export type ProjectIdentity = {
19
+ readonly status: 'resolved';
20
+ readonly mainRoot: string;
21
+ } | {
22
+ readonly status: 'unresolved';
23
+ readonly reason: UnresolvedReason;
24
+ };
25
+ export interface AllowMatchOptions {
26
+ /** Home directory for `~` entries. Defaults to `os.homedir()`. */
27
+ readonly homeDir?: string;
28
+ }
29
+ /**
30
+ * The main repository root of `checkoutRoot` (the checkout root that
31
+ * `resolveSearchRoot` returns), as a realpath, or `unresolved` with a reason.
32
+ * A linked worktree maps to its main checkout; a submodule and a nested repo
33
+ * are their own projects.
34
+ */
35
+ export declare function resolveProjectIdentity(checkoutRoot: string): ProjectIdentity;
36
+ /**
37
+ * Whether the identity's main root equals one allow entry. Entries are
38
+ * absolute or `~`-prefixed; both sides are compared as realpaths, exactly, so
39
+ * a parent or child never matches. A stale entry, a relative entry or a bad
40
+ * entry is a silent non-match, and an unresolved identity matches nothing.
41
+ */
42
+ export declare function isAllowedProject(identity: ProjectIdentity, allowList: readonly string[], options?: AllowMatchOptions): boolean;
@@ -4,13 +4,20 @@
4
4
  * Turns the core's structured result into the one text every surface returns.
5
5
  * Owns sanitising, field caps, the snippet window, the warning cap and the
6
6
  * 16 KB cut with Systematic's own marker. Imports only types from the corpus
7
- * module, so render tests never load filesystem code.
7
+ * and external modules, so render tests never load filesystem code.
8
+ *
9
+ * `renderExternalResult` and `renderExternalFixedReply` render `kind:
10
+ * "external"` the same way, with their own 12 KB allowance and marker. They
11
+ * share the sanitizer, the field caps and the cut, and leave
12
+ * `renderSearchResult` alone.
8
13
  *
9
14
  * Everything echoed passes `sanitizeInline` first, because titles, tags, file
10
15
  * names and bodies are untrusted text that ends up in an agent's context and
11
16
  * a human's terminal.
12
17
  */
13
18
  import type { CorpusDocument, DocumentKind } from './search-corpus.js';
19
+ import type { ExternalRecord, SourceState } from './search-external.js';
20
+ import type { ProjectState, SourceOrigin } from './search-external-sources.js';
14
21
  /** Hard cap on rendered output, in UTF-8 bytes. */
15
22
  export declare const MAX_OUTPUT_BYTES: number;
16
23
  /** Appended on its own line when output is cut. */
@@ -86,3 +93,89 @@ export declare function truncateUtf8(text: string, maxBytes: number, marker: str
86
93
  export declare function extractSnippet(document: Pick<CorpusDocument, 'body' | 'symptoms' | 'title'>, queryTerms: readonly string[]): string;
87
94
  /** Render a structured result as text, never more than `MAX_OUTPUT_BYTES`. */
88
95
  export declare function renderSearchResult(result: SearchResult): string;
96
+ /** Hard cap on a rendered `external` reply, in UTF-8 bytes. Built-in output keeps 16 KB. */
97
+ export declare const EXTERNAL_MAX_OUTPUT_BYTES: number;
98
+ /** Appended on its own line when an `external` reply is cut. It says 12 KB, never 16 KB. */
99
+ export declare const EXTERNAL_TRUNCATION_MARKER = "[Systematic: search output truncated at 12 KB]";
100
+ /** One returned hit of one external source. `rank` is 1-based within its source. */
101
+ export interface ExternalHit {
102
+ readonly rank: number;
103
+ readonly record: ExternalRecord;
104
+ }
105
+ /**
106
+ * One active source in a reply. `hits` is the ranked list after the per-source
107
+ * limit; the renderer drops whole hits from the end when the source goes past
108
+ * its share of the allowance.
109
+ */
110
+ export interface ExternalSection {
111
+ readonly name: string;
112
+ readonly origin: SourceOrigin;
113
+ /** Absolute roots, as resolved. The renderer collapses the home directory to `~`. */
114
+ readonly roots: readonly string[];
115
+ readonly state: SourceState;
116
+ /** Records the source loaded; reported only for a loaded source with no hit. */
117
+ readonly recordCount: number;
118
+ readonly hits: readonly ExternalHit[];
119
+ }
120
+ export interface ExternalSearchResult {
121
+ /** The query as the caller sent it; sanitised and capped when echoed. */
122
+ readonly query: string;
123
+ /** Unique, sorted query terms, used to pick snippet windows. */
124
+ readonly queryTerms: readonly string[];
125
+ /** The home directory `~` stands for in a section root. */
126
+ readonly homeDir: string;
127
+ readonly project: ProjectState;
128
+ /** In the order they print. */
129
+ readonly sections: readonly ExternalSection[];
130
+ readonly notes: readonly string[];
131
+ readonly warnings: readonly string[];
132
+ }
133
+ /** The replies the core owns, all `ok: true`. */
134
+ export type ExternalFixedReply = {
135
+ readonly kind: 'no-project';
136
+ } | {
137
+ readonly kind: 'no-active-source';
138
+ } | {
139
+ readonly kind: 'not-allowed';
140
+ readonly proposals: number;
141
+ /** The verified main-root string; absent when the identity is unresolved. */
142
+ readonly mainRoot?: string | undefined;
143
+ };
144
+ export interface ExternalReplyContext {
145
+ /** Raw: a reply can be produced before the query is validated, so it may not be a string. */
146
+ readonly query: unknown;
147
+ readonly notes: readonly string[];
148
+ readonly warnings: readonly string[];
149
+ readonly project?: ProjectState | undefined;
150
+ }
151
+ /**
152
+ * The fixed texts of the external replies. The first two are constants; the
153
+ * not-allowed text takes the proposal count and, when the project identity is
154
+ * verified, the exact main-root string to add. Every interpolation is
155
+ * sanitized, and none of them carries a source name or a root. No text holds a
156
+ * built-in routing token (`Corpus:`, `corpus: none`, `corpus: empty`,
157
+ * `N docs, M hits`, `Search "`).
158
+ */
159
+ export declare const EXTERNAL_REPLIES: {
160
+ readonly noProject: 'no project: there is no .git directory at or above the start directory, so there are no external sources to search.';
161
+ readonly noActiveSource: 'no external sources are active for this project.';
162
+ readonly notAllowed: (proposals: number, mainRoot?: string) => string;
163
+ };
164
+ /**
165
+ * Render one of the core's fixed replies. The first line is the prefix and the
166
+ * fixed text. No-project and not-allowed add notes only: the not-allowed reply
167
+ * never echoes a source name or a root, so it takes no warnings. The
168
+ * no-active-source reply also carries the project-level config state and the
169
+ * bounded warnings, because those say why nothing is active.
170
+ */
171
+ export declare function renderExternalFixedReply(reply: ExternalFixedReply, context: ExternalReplyContext): string;
172
+ /**
173
+ * Render an `external` result: the prefix with the source and hit counts, the
174
+ * notes, the project-level state line, the bounded warnings, then one section
175
+ * per active source in the order given. The text is at most 12 KB. Every
176
+ * source with hits gets an equal share of what the fixed lines leave; a
177
+ * source past its share drops whole hits from the end and prints `+N more hits
178
+ * not shown`. If the fixed lines alone overflow, the cut falls back to the
179
+ * 12 KB marker, so the marker is only ever printed when text was lost.
180
+ */
181
+ export declare function renderExternalResult(result: ExternalSearchResult): string;
@@ -17,12 +17,15 @@ import type { ToolDefinition } from '@opencode-ai/plugin';
17
17
  import type { Type as TypeBuilder } from 'typebox';
18
18
  import type { V2Installer } from './opencode-v2.js';
19
19
  import { type SearchSettings } from './search-core.js';
20
+ import type { UserLevelConfigDirOptions } from './search-user-config.js';
20
21
  /** Whether the config leaves the tool on. Only an explicit `enabled: false` removes it. */
21
22
  export declare function isSearchEnabled(settings: SearchSettings | undefined): boolean;
22
23
  export interface SearchToolV1Options {
23
24
  readonly settings: SearchSettings | undefined;
24
25
  /** `config.searchUnreadable`: adds the `config unreadable` note to every result. */
25
26
  readonly unreadable?: boolean | undefined;
27
+ /** The config directories `kind: "external"` reads per call. Tests use this; the host entry leaves it out. */
28
+ readonly configOptions?: UserLevelConfigDirOptions | undefined;
26
29
  }
27
30
  export declare function createSearchTool(options: SearchToolV1Options): ToolDefinition;
28
31
  /**
@@ -35,6 +38,8 @@ export interface SearchToolPiOptions {
35
38
  readonly settings: SearchSettings | undefined;
36
39
  /** `config.searchUnreadable`: adds the `config unreadable` note to every result. */
37
40
  readonly unreadable?: boolean | undefined;
41
+ /** The config directories `kind: "external"` reads per call. Tests use this; `src/pi.ts` leaves it out. */
42
+ readonly configOptions?: UserLevelConfigDirOptions | undefined;
38
43
  /**
39
44
  * typebox's `Type` builder, supplied by the Pi entry. This module is also
40
45
  * imported by the OpenCode entries, and typebox is an optional peer that only
@@ -2,46 +2,107 @@
2
2
  * The `search` config field: its zod schema piece, the pure merge rule, the
3
3
  * user-level file selection, and a reader that never touches project config.
4
4
  *
5
- * Import rule: this module may import only zod, jsonc-parser, node builtins
6
- * and TYPES from `search-core.ts`. It must never import `config.ts` or
7
- * `config-schema.ts`. The `systematic-search` bin bundles it, and
8
- * pulling in `config.ts` would drag the whole config loader (and its jsonc
9
- * build) into that bundle. `trustProtected` is applied only in
10
- * `config-schema.ts`, which imports the schema piece from here.
5
+ * Import rule: this module may import only zod, jsonc-parser, node builtins,
6
+ * `search-bounded-read.ts` (node builtins only) and TYPES from `search-core.ts`. It must never import `config.ts` or
7
+ * `config-schema.ts`; both of those import this module, never the reverse.
8
+ * The `systematic-search` bin bundles it, and pulling in `config.ts` would
9
+ * drag the whole config loader (and its jsonc build) into that bundle.
10
+ * `trustProtected` lives in `config-schema.ts`, so the two user-only fields
11
+ * carry the same `trust: 'project-or-higher'` meta inline here.
11
12
  *
12
- * Why it exists as one place: the plugin loader (`config.ts`) and the bin both
13
- * need "validate the `search` block, then merge user and custom". The block is
14
- * validated on its own, so a bad `search` block drops with one warning and
15
- * leaves the rest of the file loading. Search still runs, and its results
16
- * carry a `config unreadable` note (the `unreadable` state). Search must never be the reason the plugin fails to load.
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`
15
+ * only. `config.ts` strips the two user-only fields from a project with
16
+ * per-path warnings, validates the project's `sources` with the validators
17
+ * here, and then discards them; the per-call reader is their only consumer.
18
+ *
19
+ * Why it exists as one place: the plugin loader (`config.ts`), the per-call
20
+ * reader and the bin all need "validate the `search` block, then merge user
21
+ * and custom". The block is validated field by field and entry by entry, so
22
+ * one bad field or source entry drops alone with a warning and leaves its
23
+ * valid siblings and the rest of the file loading. Search still runs, and
24
+ * its results carry a `config unreadable` note when a setting that changes
25
+ * what search does was dropped (the `unreadable` state). Search must never be
26
+ * the reason the plugin fails to load.
17
27
  */
18
28
  import { z } from 'zod';
19
- import type { SearchSettings } from './search-core.js';
29
+ /** The two formats a source may declare. */
30
+ export declare const SEARCH_SOURCE_FORMATS: readonly ['markdown', 'deciduous'];
31
+ export type SearchSourceFormat = (typeof SEARCH_SOURCE_FORMATS)[number];
32
+ /** A source takes at most this many roots. */
33
+ export declare const MAX_SOURCE_ROOTS = 8;
34
+ /**
35
+ * One entry of `search.sources`. `projects` is user-config only, and a user
36
+ * entry must carry at least one; the validators enforce both. The schema keeps
37
+ * it optional because the project variant may not set it.
38
+ */
39
+ export declare const SearchSourceSchema: z.ZodObject<{
40
+ name: z.ZodString;
41
+ format: z.ZodEnum<{
42
+ deciduous: "deciduous";
43
+ markdown: "markdown";
44
+ }>;
45
+ roots: z.ZodArray<z.ZodString>;
46
+ projects: z.ZodOptional<z.ZodArray<z.ZodString>>;
47
+ }, z.core.$strict>;
48
+ export type SearchSourceEntry = z.output<typeof SearchSourceSchema>;
20
49
  /**
21
50
  * The `search` block. No zod defaults anywhere: an absent `search` stays
22
51
  * absent, and the core applies its own defaults at use time.
52
+ *
53
+ * `enabled` and `allow_project_sources` are user-only and carry the trust tag
54
+ * inline (the same `trust: 'project-or-higher'` meta `trustProtected` writes
55
+ * in `config-schema.ts`, which this module may not import). `sources` is the
56
+ * one field a project may set.
23
57
  */
24
58
  export declare const SearchSettingsSchema: z.ZodObject<{
25
59
  enabled: z.ZodOptional<z.ZodBoolean>;
60
+ allow_project_sources: z.ZodOptional<z.ZodArray<z.ZodString>>;
61
+ sources: z.ZodOptional<z.ZodArray<z.ZodObject<{
62
+ name: z.ZodString;
63
+ format: z.ZodEnum<{
64
+ deciduous: "deciduous";
65
+ markdown: "markdown";
66
+ }>;
67
+ roots: z.ZodArray<z.ZodString>;
68
+ projects: z.ZodOptional<z.ZodArray<z.ZodString>>;
69
+ }, z.core.$strict>>>;
26
70
  }, z.core.$strict>;
27
71
  /** What a successful parse of the `search` block yields. Assignable to the core's `SearchSettings`. */
28
72
  export type SearchSchemaOutput = z.output<typeof SearchSettingsSchema>;
29
- export type SearchBlockValidation = {
30
- readonly ok: true;
31
- readonly settings: SearchSchemaOutput;
32
- } | {
33
- readonly ok: false;
34
- readonly fields: readonly string[];
35
- };
73
+ /** Which rules apply: user and custom config, or project config (`sources` only). */
74
+ export type SearchConfigTrust = 'user' | 'project';
75
+ export interface SearchConfigValidation {
76
+ /**
77
+ * The valid parts of the block. Absent only when the block itself was not an
78
+ * object. An object block with nothing valid gives `{}`.
79
+ */
80
+ readonly settings: SearchSchemaOutput | undefined;
81
+ /**
82
+ * Set when something that changes what search does was dropped: a bad
83
+ * `enabled`, a bad or non-array allow list or allow entry, a non-array
84
+ * `sources`, an unknown key, or a block that is not an object. A dropped
85
+ * source entry alone does not set it.
86
+ */
87
+ readonly unreadable: boolean;
88
+ /** Set when a container is invalid: the block is not an object, or `sources` is not an array. */
89
+ readonly structural: boolean;
90
+ /** Bounded warnings. They name fields and source names, never a value. */
91
+ readonly warnings: readonly string[];
92
+ }
36
93
  /**
37
- * Validate a raw `search` value on its own. A failure lists the offending
38
- * field paths (`search.enabled`) and never a value: a path from
39
- * a strict object names the parent for an unknown key, so a user-authored key
40
- * name is not echoed either.
94
+ * Validate a raw `search` value field by field and entry by entry, so a
95
+ * typo in `sources` can never lose `enabled: false`. This is the one
96
+ * validator `config.ts` and the per-call reader both call.
97
+ *
98
+ * A structural error (the block is not an object, or `sources` is not an
99
+ * array) drops the affected container. An entry error drops that entry only.
100
+ * `trust: 'project'` reads `sources` alone; `enabled` and `allow_project_sources`
101
+ * are ignored here because `config.ts` strips them from project config with
102
+ * their own per-path warnings. Warnings name fields and source names and
103
+ * never a value.
41
104
  */
42
- export declare function validateSearchBlock(value: unknown): SearchBlockValidation;
43
- /** The one warning for a `search` block that failed its schema. It names fields and no value. */
44
- export declare function formatSearchBlockWarning(sourcePath: string, fields: readonly string[]): string;
105
+ export declare function validateSearchConfig(value: unknown, trust: SearchConfigTrust, sourcePath: string): SearchConfigValidation;
45
106
  /**
46
107
  * One source's `search` block after schema validation. `settings` is the
47
108
  * schema-parsed block, absent when the source has none. `unreadable` is true
@@ -52,13 +113,15 @@ export interface SearchSettingsSource {
52
113
  readonly unreadable: boolean;
53
114
  }
54
115
  export interface MergedSearchSettings {
55
- readonly settings: SearchSettings | undefined;
116
+ readonly settings: SearchSchemaOutput | undefined;
56
117
  readonly unreadable: boolean;
57
118
  }
58
119
  /**
59
120
  * The one merge rule, used by both `config.ts` and the reader. Sources arrive
60
121
  * in priority order, user then custom. `enabled` takes the last source that
61
- * defines it. `unreadable` is set when any source was.
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.
62
125
  */
63
126
  export declare function mergeSearchSettings(sources: readonly SearchSettingsSource[]): MergedSearchSettings;
64
127
  /**
@@ -84,13 +147,37 @@ export interface UserLevelConfigDirs {
84
147
  */
85
148
  export declare function resolveUserLevelConfigDirs(options?: UserLevelConfigDirOptions): UserLevelConfigDirs;
86
149
  export interface UserLevelSearchLoad {
87
- readonly settings: SearchSettings | undefined;
150
+ readonly settings: SearchSchemaOutput | undefined;
88
151
  readonly warnings: readonly string[];
89
152
  readonly unreadable: boolean;
90
153
  }
154
+ /** Largest project config file the bin-safe project reader accepts. */
155
+ export declare const MAX_PROJECT_CONFIG_BYTES: number;
91
156
  /**
92
157
  * Read the `search` block from the two user-level files, user then custom, and
93
158
  * merge them. It never reads project config and never throws: an unparseable
94
159
  * file or an invalid block gives one warning and `unreadable: true`.
95
160
  */
96
161
  export declare function loadUserLevelSearchSettings(options?: UserLevelConfigDirOptions): UserLevelSearchLoad;
162
+ export interface ProjectSearchLoad {
163
+ /** The valid proposed sources. Empty for an absent file, a structural error or no `sources`. */
164
+ readonly sources: readonly SearchSourceEntry[];
165
+ /** Bounded warnings. They name fields and source names, never a value. */
166
+ readonly warnings: readonly string[];
167
+ /**
168
+ * The project config is unreadable: the file could not be read (including
169
+ * over `MAX_PROJECT_CONFIG_BYTES`) or parsed, or a container is invalid
170
+ * (`search` is not an object, `sources` is not an array). An invalid entry
171
+ * alone does not set it. This is not the user-config `config unreadable` note.
172
+ */
173
+ readonly unreadable: boolean;
174
+ }
175
+ /**
176
+ * 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
180
+ * (`sources` only; `enabled` and `allow_project_sources` are never read), and
181
+ * it never throws. A missing file or a missing `search` block is normal.
182
+ */
183
+ export declare function loadProjectSearchSources(checkoutRoot: string): ProjectSearchLoad;