@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.
package/dist/index.js CHANGED
@@ -26,7 +26,7 @@ import {
26
26
  SEARCH_NOTICES,
27
27
  SEARCH_CONFIG_UNREADABLE_NOTE,
28
28
  runSearch
29
- } from "./index-10dym2d9.js";
29
+ } from "./index-8rz6cepj.js";
30
30
 
31
31
  // src/index.ts
32
32
  import path8 from "path";
@@ -396,6 +396,7 @@ export declare function createSystematicConfigSchema(opts: SystematicConfigSchem
396
396
  }>;
397
397
  roots: z.ZodArray<z.ZodString>;
398
398
  projects: z.ZodOptional<z.ZodArray<z.ZodString>>;
399
+ exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
399
400
  }, z.core.$strict>>>;
400
401
  }, z.core.$strict>>;
401
402
  disabled_skills: z.ZodDefault<z.ZodArray<z.ZodEnum<{
@@ -604,6 +605,7 @@ export declare const SystematicConfigSchema: z.ZodObject<{
604
605
  }>;
605
606
  roots: z.ZodArray<z.ZodString>;
606
607
  projects: z.ZodOptional<z.ZodArray<z.ZodString>>;
608
+ exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
607
609
  }, z.core.$strict>>>;
608
610
  }, z.core.$strict>>;
609
611
  disabled_skills: z.ZodDefault<z.ZodArray<z.ZodEnum<{
@@ -206,10 +206,12 @@ export declare function computeDroppedNames(names: readonly string[], allowedSet
206
206
  export declare function warnDroppedNames(dropped: string[], field: string, warned: Set<string>, removalVersion?: string, warningSink?: (message: string) => void): void;
207
207
  export interface LoadConfigOptions {
208
208
  /**
209
- * When false, the project-level config source (`<cwd>/.opencode/systematic.json`)
210
- * is not loaded at all — not merged, not trust-stripped, entirely absent from
211
- * the source chain. Used by global-scoped pi-subagents export so it never
212
- * absorbs cwd project overlays (plan R7/R19). Defaults to true.
209
+ * When false, the project-level config source is not loaded at all — not
210
+ * merged, not trust-stripped, entirely absent from the source chain — and
211
+ * no repository root is looked up. Used by global-scoped pi-subagents
212
+ * export so it never absorbs cwd project overlays (plan R7/R19). Defaults
213
+ * to true, which reads the project file from the repository root above the
214
+ * start directory (see `getConfigPaths`).
213
215
  */
214
216
  includeProject?: boolean;
215
217
  invalidSource?: 'throw' | 'report';
@@ -260,16 +262,34 @@ export declare function isAgentDisabled(disabledAgents: ReadonlySet<string>, age
260
262
  * practice.
261
263
  */
262
264
  export declare function collectRoutingTargets(overlays: SourcedOverlayConfigMap, disabledAgents?: ReadonlySet<string>): RoutingTarget[];
263
- interface ConfigPathOptions {
264
- readonly homeDir?: string;
265
- readonly userConfigDir?: string;
266
- readonly customConfigDir?: string | null;
267
- }
265
+ type ConfigPathOptions = Pick<LoadConfigOptions, 'customConfigDir' | 'homeDir' | 'includeProject' | 'userConfigDir'>;
266
+ /**
267
+ * Where each config file lives.
268
+ *
269
+ * The project file is read from the repository root: the nearest ancestor of
270
+ * `projectDir` holding `.git`, or `projectDir` itself when there is none (kept
271
+ * as given, not resolved). Under that root `.systematic.jsonc` (else
272
+ * `.systematic.json`) wins over `.opencode/systematic.jsonc` (else `.json`);
273
+ * `ignoredProjectConfig` names the `.opencode/` file a root file shadows. With
274
+ * `includeProject: false` no root is looked up and `projectConfig` stays under
275
+ * `projectDir`. `startDirProjectConfig` names an `.opencode/` file in
276
+ * `projectDir` that is not read because the root is elsewhere.
277
+ *
278
+ * The local files sit beside the user and custom files and are selected even
279
+ * when absent. `customAliasesUser` is true when the custom directory is the
280
+ * user directory.
281
+ */
268
282
  export declare function getConfigPaths(projectDir: string, options?: ConfigPathOptions): {
269
283
  userConfig: string;
284
+ userLocalConfig: string;
270
285
  projectConfig: string;
286
+ projectRoot: string;
271
287
  userDir: string;
272
288
  projectDir: string;
289
+ customAliasesUser: boolean;
290
+ ignoredProjectConfig?: string | undefined;
291
+ startDirProjectConfig?: string | undefined;
273
292
  customConfig?: string | undefined;
293
+ customLocalConfig?: string | undefined;
274
294
  customDir?: string | undefined;
275
295
  };
@@ -10,6 +10,7 @@
10
10
  * search core's resolver reads.
11
11
  */
12
12
  import fs from 'node:fs';
13
+ import type { ExcludeMatcher } from './search-exclude.js';
13
14
  /** Largest single file loaded, in bytes. */
14
15
  export declare const MAX_FILE_BYTES: number;
15
16
  /** Most files considered per load. */
@@ -151,6 +152,10 @@ export declare function listDirectoryBounded(target: string, limit: number): Bou
151
152
  * directory, or a file for a worktree), resolved with `realpath`; otherwise
152
153
  * `startDir` itself, also resolved.
153
154
  *
155
+ * `lookupSearchRoot` is the variant for callers that must keep the start
156
+ * directory unresolved when there is no repository, and must know whether one
157
+ * was found. Both share `walkToGitRoot`.
158
+ *
154
159
  * This is a copy of the private `findGitWorktreeRoot` in
155
160
  * `discovered-skills.ts`, and the two differ on purpose: search falls back to
156
161
  * the start directory, while discovery returns null. Do not unify them.
@@ -158,6 +163,23 @@ export declare function listDirectoryBounded(target: string, limit: number): Bou
158
163
  * the standalone search bin. This is the second use; extract at the third.
159
164
  */
160
165
  export declare function resolveSearchRoot(startDir: string): string;
166
+ /** What `lookupSearchRoot` found. */
167
+ export interface SearchRootLookup {
168
+ /**
169
+ * The repository root (realpathed) when `foundGit`; otherwise the caller's
170
+ * `startDir`, unchanged and unresolved.
171
+ */
172
+ readonly root: string;
173
+ /** Whether an ancestor holding `.git` was found. */
174
+ readonly foundGit: boolean;
175
+ }
176
+ /**
177
+ * Like `resolveSearchRoot`, but reports whether `.git` was found and, when
178
+ * none was, hands back `startDir` exactly as given instead of its realpath.
179
+ * Config loading uses it so a directory outside any repository keeps the path
180
+ * the caller passed (a temp directory under a symlinked prefix stays as is).
181
+ */
182
+ export declare function lookupSearchRoot(startDir: string): SearchRootLookup;
161
183
  export declare function isInside(root: string, candidate: string): boolean;
162
184
  export type SymlinkedComponent = 'root' | 'ancestor';
163
185
  /**
@@ -168,6 +190,23 @@ export type SymlinkedComponent = 'root' | 'ancestor';
168
190
  * owns it. A component that is missing or cannot be inspected ends the check.
169
191
  */
170
192
  export declare function symlinkedComponent(container: string, target: string): SymlinkedComponent | undefined;
193
+ /** Why a project source root is not loaded. */
194
+ export type ProjectRootRejection = SymlinkedComponent | 'outside';
195
+ /** The reason each rejection gives, as the loaders and the inspector word it. */
196
+ export declare const PROJECT_ROOT_REJECTION_REASONS: Readonly<Record<ProjectRootRejection, string>>;
197
+ /**
198
+ * The warning a loader prints when a project source root is rejected, for the
199
+ * Markdown and Deciduous loaders alike. It names the source, never a path.
200
+ */
201
+ export declare function projectRootRejectionWarning(sourceName: string, rejection: ProjectRootRejection): string;
202
+ /**
203
+ * Whether a project source root is rejected before it is walked: it is a
204
+ * symlink, passes through a symlink below the checkout, or its real path is not
205
+ * strictly inside the checkout's real path. The loaders and `config show` both
206
+ * ask this, so what is reported as rejected is what is dropped. A root that is
207
+ * missing or cannot be inspected is not rejected here; the walk reports it.
208
+ */
209
+ export declare function rejectedProjectRoot(checkoutRoot: string, root: string): ProjectRootRejection | undefined;
171
210
  export interface SourceFileCandidate {
172
211
  /** Path relative to the walked directory, with `/` separators. */
173
212
  readonly relative: string;
@@ -230,6 +269,12 @@ export interface DiscoverSourceFilesOptions {
230
269
  * source. Left out, every directory is listed whole.
231
270
  */
232
271
  readonly entryBudget?: EntryBudget | undefined;
272
+ /**
273
+ * Tests a path relative to the walked directory, `/`-joined. A match leaves
274
+ * the entry out and, for a directory, its whole subtree. Built-in kinds set
275
+ * none.
276
+ */
277
+ readonly isExcluded?: ExcludeMatcher | undefined;
233
278
  /** Names the directory in warnings: `spec.dir` for a built-in kind, the source name for an external one. */
234
279
  readonly label: string;
235
280
  }
@@ -0,0 +1,84 @@
1
+ /**
2
+ * Gitignore-style exclude patterns for external search sources: a validator
3
+ * for one pattern and for a whole list, and a compiled matcher over
4
+ * root-relative paths.
5
+ *
6
+ * This module imports nothing. The plugin bundle and the standalone
7
+ * `systematic-search` bin both read source entries, so the pattern rules live
8
+ * in one place that neither has to pull `config.ts` in to reach.
9
+ *
10
+ * Pattern rules:
11
+ * - A pattern matches the path relative to a source root, `/`-separated and
12
+ * case-sensitive. One trailing `/` is ignored.
13
+ * - A pattern with no `/` is name-only: it tests the entry's own name at any
14
+ * depth. A pattern with a `/` is anchored at the root and tested against the
15
+ * whole relative path.
16
+ * - `*` matches any run of characters inside one segment (dotfiles included)
17
+ * and `?` matches one character. Neither crosses a `/`.
18
+ * - `**` is special only as a whole segment. It matches zero or more segments,
19
+ * so `a/**` also matches `a`, and a pattern that starts with a `**` segment
20
+ * can match an entry at the root.
21
+ * - Invalid: empty, a leading `/`, `!`, a leading `./`, an empty segment
22
+ * (`a//b`), a `.` or `..` segment, `[` or `]`, `\`, `**` inside a segment
23
+ * (`a**b`), more than 256 characters.
24
+ *
25
+ * The matcher tests one entry at a time and does not know whether the entry is
26
+ * a file or a directory. A walk that tests every entry it reaches and does not
27
+ * descend into a matched directory excludes the whole subtree that way.
28
+ *
29
+ * There is no regular expression and no recursion. A segment is matched with a
30
+ * two-pointer scan that remembers one star position, and an anchored pattern
31
+ * runs a dynamic program over pattern segments and path segments. A pattern is
32
+ * at most 256 characters, so the cost grows linearly with the length of the
33
+ * path. Validation reasons describe the broken rule and never repeat the
34
+ * pattern text.
35
+ */
36
+ /** The most patterns one source keeps; elements from this index on are dropped. */
37
+ export declare const MAX_EXCLUDE_PATTERNS = 64;
38
+ /** The longest pattern accepted, in UTF-16 code units. */
39
+ export declare const MAX_EXCLUDE_PATTERN_LENGTH = 256;
40
+ export type ExcludePatternCheck = {
41
+ readonly ok: true;
42
+ } | {
43
+ readonly ok: false;
44
+ readonly reason: string;
45
+ };
46
+ /** One element, or the over-limit tail, that a list validation dropped. */
47
+ export interface ExcludeIssue {
48
+ readonly index: number;
49
+ readonly reason: string;
50
+ }
51
+ export type ExcludeListValidation = {
52
+ readonly ok: true;
53
+ readonly patterns: readonly string[];
54
+ readonly issues: readonly ExcludeIssue[];
55
+ } | {
56
+ readonly ok: false;
57
+ readonly reason: string;
58
+ };
59
+ /** A validated pattern split into segments, with consecutive `**` collapsed. */
60
+ export interface CompiledExcludePattern {
61
+ readonly segments: readonly string[];
62
+ readonly nameOnly: boolean;
63
+ }
64
+ /** Tests a root-relative path joined with `/`. */
65
+ export type ExcludeMatcher = (relativePath: string) => boolean;
66
+ /** Checks one element. The reason names the broken rule, never the pattern. */
67
+ export declare function validateExcludePattern(pattern: unknown): ExcludePatternCheck;
68
+ /**
69
+ * Validates the `exclude` value of one source entry. A value that is not an
70
+ * array drops the whole source (`ok: false`). Inside an array, an invalid
71
+ * element is dropped alone and reported by index. Only the first
72
+ * `MAX_EXCLUDE_PATTERNS` elements are inspected, an invalid one still holds its
73
+ * index, and the rest are dropped with one issue at index
74
+ * `MAX_EXCLUDE_PATTERNS` that states the count.
75
+ */
76
+ export declare function validateExcludeList(value: unknown): ExcludeListValidation;
77
+ /** Compiles one pattern; an invalid pattern gives `undefined`. */
78
+ export declare function compileExcludePattern(pattern: string): CompiledExcludePattern | undefined;
79
+ /**
80
+ * Compiles a list of patterns into one matcher. A pattern that fails
81
+ * validation is skipped; callers run `validateExcludeList` first, so skipping
82
+ * only keeps a search from throwing. An empty list matches nothing.
83
+ */
84
+ export declare function compileExcludePatterns(patterns: readonly string[]): ExcludeMatcher;
@@ -18,9 +18,10 @@
18
18
  * nothing else. Symlinks are skipped at every depth. Reads files only.
19
19
  *
20
20
  * Import rule: node builtins, `search-bounded-read.ts` and `search-corpus.ts`
21
- * only. It never imports the dispatcher (`search-external.ts`), which adapts
22
- * its result.
21
+ * only, plus the `ExcludeMatcher` type. It never imports the dispatcher
22
+ * (`search-external.ts`), which adapts its result and compiles the matcher.
23
23
  */
24
+ import type { ExcludeMatcher } from './search-exclude.js';
24
25
  export type DeciduousState = 'loaded' | 'empty' | 'missing' | 'unreadable' | 'dropped';
25
26
  /** A record as the dispatcher receives it; the dispatcher adds the source and origin. */
26
27
  export interface DeciduousRecord {
@@ -49,6 +50,12 @@ export interface DeciduousLoadInput {
49
50
  readonly maxFileBytes: number;
50
51
  /** Directory entries the source may examine in total. Defaults to `MAX_LISTED_ENTRIES`. */
51
52
  readonly entryLimit?: number | undefined;
53
+ /**
54
+ * Tests `nodes`, `edges`, `nodes/<file>` or `edges/<file>`, relative to each
55
+ * root. A match leaves the folder or file out unexamined. Without it nothing
56
+ * is excluded.
57
+ */
58
+ readonly isExcluded?: ExcludeMatcher | undefined;
52
59
  }
53
60
  /**
54
61
  * Load one Deciduous source: scan `nodes/` then `edges/` of every root, read
@@ -18,13 +18,16 @@
18
18
  * dropped, a user source mapped to this project shadows a same-named project
19
19
  * source, user sources come before project sources, and the list caps at
20
20
  * `MAX_ACTIVE_SOURCES`. Project-source problems never throw and never touch
21
- * built-in replies; the caller decides how to word the states.
21
+ * built-in replies; the caller decides how to word the states. A project that
22
+ * is not allowed forwards no warning that names one of its entries: its
23
+ * replies name no proposal, and `inspectSearch` is where those warnings go.
22
24
  *
23
25
  * Roots come back resolved to absolute paths and nothing more: existence,
24
26
  * symlink and containment checks belong to the loader that reads them.
25
27
  */
28
+ import { type DocumentKind } from './search-corpus.js';
26
29
  import { type ProjectIdentity } from './search-project-identity.js';
27
- import { type SearchSourceFormat, type UserLevelConfigDirOptions } from './search-user-config.js';
30
+ import { type DroppedSearchEntry, type SearchSourceFormat, type UserLevelConfigDirOptions, type UserLevelLayer } from './search-user-config.js';
28
31
  /** At most this many sources are active in one call. */
29
32
  export declare const MAX_ACTIVE_SOURCES = 8;
30
33
  export type SourceOrigin = 'project' | 'user';
@@ -34,6 +37,8 @@ export interface ActiveSource {
34
37
  readonly format: SearchSourceFormat;
35
38
  readonly roots: readonly string[];
36
39
  readonly origin: SourceOrigin;
40
+ /** Validated exclude patterns for this source's walk. Empty when none. */
41
+ readonly exclude: readonly string[];
37
42
  }
38
43
  /**
39
44
  * What the project's own config contributed.
@@ -73,9 +78,18 @@ export interface ExternalSourcesResolution {
73
78
  /**
74
79
  * Bounded warnings, the source-cap warning first, then user-file
75
80
  * and project-file warnings. They name fields and source names, never a
76
- * value. Each file's own list is bounded by its validator.
81
+ * value. Each file's own list is bounded by its validator, and each file is
82
+ * read once per call, so it reports a problem once.
77
83
  */
78
84
  readonly warnings: readonly string[];
85
+ /**
86
+ * The source entries the validators dropped whole, apart by where they were
87
+ * declared: the user-level files, and the project file.
88
+ */
89
+ readonly dropped: {
90
+ readonly user: readonly DroppedSearchEntry[];
91
+ readonly project: readonly DroppedSearchEntry[];
92
+ };
79
93
  }
80
94
  export interface ExternalSourcesInput {
81
95
  /** The directory the checkout-root walk-up starts from. */
@@ -90,3 +104,88 @@ export interface ExternalSourcesInput {
90
104
  * Never throws: every file problem is a state or a warning.
91
105
  */
92
106
  export declare function resolveExternalSources(input: ExternalSourcesInput): ExternalSourcesResolution;
107
+ /** Where an inspected source was declared. A dropped user-level entry reports `user`: its file is not tracked. */
108
+ export type InspectedSourceOrigin = UserLevelLayer | 'project';
109
+ export type InspectedSourceStatus = 'active' | 'not allowed' | 'over source cap' | 'missing root';
110
+ /**
111
+ * One root of a source. `present` is the result of one `lstat`; it is `null`
112
+ * for a source that is not in this call's active list, whose roots are not
113
+ * touched.
114
+ */
115
+ export interface InspectedRoot {
116
+ readonly path: string;
117
+ readonly present: boolean | null;
118
+ }
119
+ export type InspectedSource = {
120
+ readonly status: InspectedSourceStatus;
121
+ readonly name: string;
122
+ readonly origin: InspectedSourceOrigin;
123
+ readonly format: SearchSourceFormat;
124
+ readonly roots: readonly InspectedRoot[];
125
+ readonly exclude: readonly string[];
126
+ /** Warnings that name this source. They never carry a pattern. */
127
+ readonly warnings: readonly string[];
128
+ } | {
129
+ /**
130
+ * A project root the loader refuses (a symlink, a path through a
131
+ * symlink, or a real path outside the checkout): the source is dropped
132
+ * when a search loads it. `reason` says which.
133
+ */
134
+ readonly status: 'root rejected';
135
+ readonly name: string;
136
+ readonly origin: 'project';
137
+ readonly format: SearchSourceFormat;
138
+ readonly roots: readonly InspectedRoot[];
139
+ readonly exclude: readonly string[];
140
+ readonly reason: string;
141
+ readonly warnings: readonly string[];
142
+ } | {
143
+ readonly status: 'dropped invalid';
144
+ /** The source name, or `#<index>` when the entry had no usable name. */
145
+ readonly name: string;
146
+ readonly origin: 'user' | 'project';
147
+ readonly reason: string;
148
+ readonly warnings: readonly string[];
149
+ };
150
+ export type BuiltInKindState = 'present' | 'empty' | 'missing' | 'unreadable';
151
+ export interface InspectedBuiltInKind {
152
+ readonly kind: DocumentKind;
153
+ /** Absolute directory the kind is read from. */
154
+ readonly directory: string;
155
+ readonly state: BuiltInKindState;
156
+ }
157
+ export interface SearchInspection {
158
+ /** False only when a user-level file sets `search.enabled: false`. */
159
+ readonly enabled: boolean;
160
+ readonly allowProjectSources: readonly string[];
161
+ /** Whether this project's main root is on the allow list. */
162
+ readonly projectAllowed: boolean;
163
+ /** The checkout root the project file, project roots and built-in kinds are read from. */
164
+ readonly projectRoot: string;
165
+ readonly userConfigUnreadable: boolean;
166
+ readonly projectConfigUnreadable: boolean;
167
+ /** Sources in resolution order, then not-allowed proposals, then dropped entries. */
168
+ readonly sources: readonly InspectedSource[];
169
+ readonly builtIn: readonly InspectedBuiltInKind[];
170
+ /** Warnings from the config files that name no listed source. */
171
+ readonly warnings: readonly string[];
172
+ }
173
+ export interface SearchInspectionInput {
174
+ /** The checkout root, as the caller shows it elsewhere. Not resolved again. */
175
+ readonly checkoutRoot: string;
176
+ readonly configOptions?: UserLevelConfigDirOptions | undefined;
177
+ /** Override the identity of the checkout. Tests use this; surfaces leave it out. */
178
+ readonly identity?: ProjectIdentity | undefined;
179
+ }
180
+ /**
181
+ * Describe what search does for one project, without running a search: which
182
+ * sources exist, where each came from, and why each is or is not active.
183
+ *
184
+ * It reads the same files through the same readers and applies the same
185
+ * order as `resolveExternalSources`, then adds what that result leaves out:
186
+ * the declaring layer, the cap, one `lstat` per root of each source in the
187
+ * active list, and the names and roots of proposals the allow list rejects.
188
+ * No external root is walked and no document is read; the built-in kinds are
189
+ * listed by directory only. Never throws.
190
+ */
191
+ export declare function inspectSearch(input: SearchInspectionInput): SearchInspection;
@@ -14,7 +14,8 @@
14
14
  * dropped whole, before any of its files is read, and later, smaller sources
15
15
  * are still tried.
16
16
  *
17
- * Import rule: node builtins, `search-corpus.ts` and the Deciduous reader
17
+ * Import rule: node builtins, `search-corpus.ts`, the exclude matcher
18
+ * (`search-exclude.ts`) and the Deciduous reader
18
19
  * (`search-external-deciduous.ts`), plus types. The Deciduous reader imports the
19
20
  * corpus helpers and never this module. The loader holds no state, so each
20
21
  * call re-reads the stores.