@fro.bot/systematic 3.27.1 → 3.28.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.
- package/ATTRIBUTIONS.md +2 -2
- package/HARNESSES.md +24 -11
- package/agents/research/learnings-researcher.md +49 -9
- package/dist/claude-code-search.d.ts +30 -0
- package/dist/claude-code-validator-bin.d.ts +17 -0
- package/dist/cli.d.ts +18 -0
- package/dist/cli.js +335 -108
- package/dist/{index-608preny.js → index-9chxhh5j.js} +1120 -72
- package/dist/index.js +204 -8
- package/dist/lib/agent-resolver.d.ts +8 -2
- package/dist/lib/asset-plan.d.ts +23 -1
- package/dist/lib/config-protected-fields.d.ts +1 -1
- package/dist/lib/config-schema.d.ts +6 -0
- package/dist/lib/config.d.ts +13 -0
- package/dist/lib/main-module.d.ts +30 -0
- package/dist/lib/opencode-v2-commands.d.ts +4 -3
- package/dist/lib/opencode-v2-skills.d.ts +12 -2
- package/dist/lib/opencode-v2.d.ts +1 -0
- package/dist/lib/pi-delegate-session.d.ts +3 -1
- package/dist/lib/pi-delegate-tool.d.ts +12 -1
- package/dist/lib/search-cli.d.ts +52 -0
- package/dist/lib/search-core.d.ts +128 -0
- package/dist/lib/search-corpus.d.ts +105 -0
- package/dist/lib/search-lexical.d.ts +136 -0
- package/dist/lib/search-render.d.ts +69 -0
- package/dist/lib/search-tool.d.ts +53 -0
- package/dist/lib/search-user-config.d.ts +96 -0
- package/dist/pi.js +1155 -77
- package/package.json +3 -3
- package/skills/ce-review/SKILL.md +1 -1
- package/skills/ce-review/references/review-output-template.md +1 -1
- package/skills/ce-review/scripts/validate-review.mjs +1 -3
- package/skills/using-systematic/references/claude-code-profile.md +1 -0
- package/skills/using-systematic/references/opencode-profile.md +1 -0
- package/skills/using-systematic/references/opencode-v2-profile.md +1 -0
- package/skills/using-systematic/references/pi-profile.md +1 -0
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one host-neutral composition behind durable-output search.
|
|
3
|
+
*
|
|
4
|
+
* `runSearch` validates the request, resolves the project root, loads the
|
|
5
|
+
* corpus, runs the lexical lane, resolves the solution lifecycle, and renders. Every adapter (OpenCode
|
|
6
|
+
* v1 and v2, Pi, the CLI and the standalone search bin) calls it and does only host
|
|
7
|
+
* I/O: the start directory, the settings, and mapping the response to its
|
|
8
|
+
* host's return shape. Adapters never format text themselves.
|
|
9
|
+
*
|
|
10
|
+
* This module also owns the `SearchSettings` type, the tool name and argument
|
|
11
|
+
* constants, and the lifecycle constants and resolver. The resolver follows
|
|
12
|
+
* the learnings-researcher's rules: at most 5 hops, a visited set, and a form
|
|
13
|
+
* rule for the successor path. A superseded doc whose successor cannot be
|
|
14
|
+
* resolved is returned at its own rank with `Caution: successor unresolved`.
|
|
15
|
+
* Nothing is dropped.
|
|
16
|
+
*/
|
|
17
|
+
import { type CorpusDocument, type CorpusLoad, type DocumentKind } from './search-corpus.js';
|
|
18
|
+
import { type Bm25fParams } from './search-lexical.js';
|
|
19
|
+
import { type SearchHitStatus, type SearchResult, SUPERSEDES_LABEL } from './search-render.js';
|
|
20
|
+
export type { SearchHit, SearchResult } from './search-render.js';
|
|
21
|
+
export { SUPERSEDES_LABEL };
|
|
22
|
+
/** Tool name shared by every host surface. */
|
|
23
|
+
export declare const SEARCH_TOOL_NAME = "systematic_search";
|
|
24
|
+
/** Tool argument names shared by every host surface. */
|
|
25
|
+
export declare const SEARCH_ARGS: {
|
|
26
|
+
readonly query: 'query';
|
|
27
|
+
readonly kind: 'kind';
|
|
28
|
+
readonly limit: 'limit';
|
|
29
|
+
};
|
|
30
|
+
export declare const DEFAULT_LIMIT = 8;
|
|
31
|
+
export declare const MIN_LIMIT = 1;
|
|
32
|
+
export declare const MAX_LIMIT = 20;
|
|
33
|
+
export declare const MAX_QUERY_CHARS = 2000;
|
|
34
|
+
/**
|
|
35
|
+
* The tool text every host surface shows the model. `limit` is a plain integer
|
|
36
|
+
* in every host schema, so its range is stated here and nowhere else: the core
|
|
37
|
+
* owns the out-of-range error and a host never pre-empts it.
|
|
38
|
+
*/
|
|
39
|
+
export declare const SEARCH_TOOL_DESCRIPTION = "Search this project's durable outputs (the docs/solutions learnings) by symptom, error text, module or topic. Returns ranked hits with path, title, snippet, tags and status. A superseded learning is replaced by its successor, and a stale one carries a caution. Read a hit's path for the full text. Use it before debugging a failure or planning work a past learning may already cover.";
|
|
40
|
+
export declare const SEARCH_ARG_DESCRIPTIONS: {
|
|
41
|
+
readonly query: "What to look for: a symptom, error message, module or topic, in plain words. At most 2000 characters.";
|
|
42
|
+
readonly kind: 'Optional. The kind of durable output to search. Only "solution" (docs/solutions/) exists today, and it is the default.';
|
|
43
|
+
readonly limit: "Optional. How many hits to return, an integer from 1 to 20. Defaults to 8.";
|
|
44
|
+
};
|
|
45
|
+
/** One-line texts an adapter returns when it cannot reach the core. They carry no detail from the failure. */
|
|
46
|
+
export declare const SEARCH_NOTICES: {
|
|
47
|
+
readonly failed: 'Error: search failed.';
|
|
48
|
+
readonly noProject: 'No project directory is available for this session, so there is nothing to search.';
|
|
49
|
+
};
|
|
50
|
+
/** The note an adapter passes in `SearchOptions.notes` when a settings source could not be read. */
|
|
51
|
+
export declare const SEARCH_CONFIG_UNREADABLE_NOTE = "config unreadable";
|
|
52
|
+
/** Most `superseded_by` links followed from one candidate. */
|
|
53
|
+
export declare const MAX_SUCCESSOR_HOPS = 5;
|
|
54
|
+
/** A successor path must start with this and name a loaded file. */
|
|
55
|
+
export declare const SUCCESSOR_PATH_PREFIX: string;
|
|
56
|
+
export declare const CAUTION_LABEL = "Caution:";
|
|
57
|
+
export declare const SUCCESSOR_UNRESOLVED_TEXT = "successor unresolved";
|
|
58
|
+
export declare const STALE_CAUTION_TEXT = "marked stale";
|
|
59
|
+
/** Fixed validation errors. They never echo the rejected value. */
|
|
60
|
+
export declare const SEARCH_ERRORS: {
|
|
61
|
+
readonly queryEmpty: 'Error: query must be a non-empty string.';
|
|
62
|
+
readonly queryTooLong: "Error: query must be at most 2000 characters.";
|
|
63
|
+
readonly kindUnknown: `Error: kind must be one of: ${string}.`;
|
|
64
|
+
readonly limitInvalid: "Error: limit must be an integer from 1 to 20.";
|
|
65
|
+
};
|
|
66
|
+
/** User-level search settings. The zod schema's output type must stay assignable to this. */
|
|
67
|
+
export interface SearchSettings {
|
|
68
|
+
readonly enabled?: boolean | undefined;
|
|
69
|
+
}
|
|
70
|
+
export interface SearchRequest {
|
|
71
|
+
/** Raw host values: the core validates them. */
|
|
72
|
+
readonly query: unknown;
|
|
73
|
+
readonly kind?: unknown;
|
|
74
|
+
readonly limit?: unknown;
|
|
75
|
+
}
|
|
76
|
+
export interface SearchOptions {
|
|
77
|
+
/** The directory the root walk-up starts from. */
|
|
78
|
+
readonly startDir: string;
|
|
79
|
+
readonly settings?: SearchSettings | undefined;
|
|
80
|
+
/** Notes an adapter wants shown ahead of the core's own, such as `SEARCH_CONFIG_UNREADABLE_NOTE`. */
|
|
81
|
+
readonly notes?: readonly string[] | undefined;
|
|
82
|
+
/** Override the BM25F table. The recall tuning uses this; hosts do not. */
|
|
83
|
+
readonly lexicalParams?: Bm25fParams | undefined;
|
|
84
|
+
/** Replace the disk loader. Tests use this to control load order. */
|
|
85
|
+
readonly corpusLoader?: ((root: string, kind: DocumentKind) => CorpusLoad) | undefined;
|
|
86
|
+
}
|
|
87
|
+
export type SearchResponse = {
|
|
88
|
+
readonly ok: true;
|
|
89
|
+
readonly text: string;
|
|
90
|
+
readonly result: SearchResult;
|
|
91
|
+
} | {
|
|
92
|
+
readonly ok: false;
|
|
93
|
+
readonly text: string;
|
|
94
|
+
};
|
|
95
|
+
/** Whether a `superseded_by` value has the shape of a repo-root solution path. */
|
|
96
|
+
export declare function isSuccessorPathForm(value: string): boolean;
|
|
97
|
+
/**
|
|
98
|
+
* Follow a superseded document's `superseded_by` chain. Returns the first
|
|
99
|
+
* document that is not superseded, or `undefined` when the chain is
|
|
100
|
+
* unresolvable: a link that is not a string, fails the form rule, names a file
|
|
101
|
+
* outside the loaded corpus, revisits a document, or is still superseded after
|
|
102
|
+
* `MAX_SUCCESSOR_HOPS` links.
|
|
103
|
+
*/
|
|
104
|
+
export declare function resolveSuccessor(candidate: CorpusDocument, byPath: ReadonlyMap<string, CorpusDocument>): CorpusDocument | undefined;
|
|
105
|
+
export interface ResolvedEntry {
|
|
106
|
+
/** The document to show: the candidate, or the successor standing in for it. */
|
|
107
|
+
readonly document: CorpusDocument;
|
|
108
|
+
/** Root-relative paths this entry replaces, in code-unit order. */
|
|
109
|
+
readonly supersedes: readonly string[];
|
|
110
|
+
/** True for a superseded document returned because its successor is unresolved. */
|
|
111
|
+
readonly unresolved: boolean;
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* Resolve the lifecycle of a ranked list, best first. A superseded candidate
|
|
115
|
+
* is replaced by its successor; a successor takes the best rank among itself
|
|
116
|
+
* and the documents it replaces; duplicates merge. An unresolvable superseded
|
|
117
|
+
* candidate stays at its own rank. `documents` is the whole loaded corpus,
|
|
118
|
+
* because a successor does not have to be a match.
|
|
119
|
+
*/
|
|
120
|
+
export declare function resolveLifecycle(ranked: readonly CorpusDocument[], documents: readonly CorpusDocument[]): ResolvedEntry[];
|
|
121
|
+
export declare function entryStatus(entry: ResolvedEntry): SearchHitStatus;
|
|
122
|
+
/** The `Supersedes:` and `Caution:` lines for one entry, in print order. */
|
|
123
|
+
export declare function lifecycleLines(entry: ResolvedEntry): string[];
|
|
124
|
+
/**
|
|
125
|
+
* Validate, search, resolve the lifecycle and render. Never throws on bad
|
|
126
|
+
* input: a bad request comes back as `{ ok: false }` with a fixed error text.
|
|
127
|
+
*/
|
|
128
|
+
export declare function runSearch(request: SearchRequest, options: SearchOptions): Promise<SearchResponse>;
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Corpus loader for durable-output search: project root, `kind` table, safe
|
|
3
|
+
* walk of `docs/solutions/` and a narrowing wrapper around `parseFrontmatter`.
|
|
4
|
+
*
|
|
5
|
+
* Reads from disk on every call and keeps no memo, because `ce:compound`
|
|
6
|
+
* searches right after it writes. Never throws: every filesystem failure
|
|
7
|
+
* becomes a bounded, sanitised warning. Holds no lifecycle logic. Documents
|
|
8
|
+
* carry the narrowed `status`, `superseded_by` and `stale_reason` that the
|
|
9
|
+
* search core's resolver reads.
|
|
10
|
+
*/
|
|
11
|
+
/** Largest single file loaded, in bytes. */
|
|
12
|
+
export declare const MAX_FILE_BYTES: number;
|
|
13
|
+
/** Most files considered per load. */
|
|
14
|
+
export declare const MAX_FILES = 2000;
|
|
15
|
+
/** Deepest directory level walked; files directly in the kind directory are depth 0. */
|
|
16
|
+
export declare const MAX_DEPTH = 6;
|
|
17
|
+
/** Total bytes of text loaded per call. */
|
|
18
|
+
export declare const MAX_TOTAL_BYTES: number;
|
|
19
|
+
/**
|
|
20
|
+
* One entry per document kind. Release 1 indexes `docs/solutions/` only; a new
|
|
21
|
+
* kind (plans, brainstorms) is a new entry here plus its frontmatter fit.
|
|
22
|
+
*/
|
|
23
|
+
export declare const KIND_TABLE: {
|
|
24
|
+
readonly solution: {
|
|
25
|
+
readonly dir: 'docs/solutions';
|
|
26
|
+
readonly excludedFiles: readonly ["readme.md", "critical-patterns.md"];
|
|
27
|
+
readonly excludedDirs: readonly ["_archived"];
|
|
28
|
+
readonly lifecycle: true;
|
|
29
|
+
};
|
|
30
|
+
};
|
|
31
|
+
export type DocumentKind = keyof typeof KIND_TABLE;
|
|
32
|
+
export declare function isDocumentKind(value: unknown): value is DocumentKind;
|
|
33
|
+
/**
|
|
34
|
+
* The `superseded_by` frontmatter value, kept apart from its meaning so the
|
|
35
|
+
* resolver sees every malformed shape: `none` (key absent or null), `value`
|
|
36
|
+
* (a string, possibly empty) or `invalid` (a list, mapping, number or any
|
|
37
|
+
* other non-string).
|
|
38
|
+
*/
|
|
39
|
+
export type SupersededByField = {
|
|
40
|
+
readonly state: 'none';
|
|
41
|
+
} | {
|
|
42
|
+
readonly state: 'value';
|
|
43
|
+
readonly value: string;
|
|
44
|
+
} | {
|
|
45
|
+
readonly state: 'invalid';
|
|
46
|
+
};
|
|
47
|
+
export interface CorpusDocument {
|
|
48
|
+
/** Root-relative path with `/` separators. */
|
|
49
|
+
readonly path: string;
|
|
50
|
+
readonly kind: DocumentKind;
|
|
51
|
+
/** The `title` field, else the file name without `.md`. */
|
|
52
|
+
readonly title: string;
|
|
53
|
+
readonly tags: readonly string[];
|
|
54
|
+
readonly module: string | undefined;
|
|
55
|
+
readonly component: string | undefined;
|
|
56
|
+
readonly problemType: string | undefined;
|
|
57
|
+
readonly symptoms: readonly string[];
|
|
58
|
+
readonly appliesWhen: readonly string[];
|
|
59
|
+
/** Raw `status` string; `undefined` when absent or not a string. */
|
|
60
|
+
readonly status: string | undefined;
|
|
61
|
+
readonly supersededBy: SupersededByField;
|
|
62
|
+
readonly staleReason: string | undefined;
|
|
63
|
+
/** Text after the frontmatter block, or the whole file when there is none. */
|
|
64
|
+
readonly body: string;
|
|
65
|
+
}
|
|
66
|
+
export interface CorpusLoad {
|
|
67
|
+
/** `none` when the kind directory does not exist (or lies outside the root). */
|
|
68
|
+
readonly state: 'none' | 'loaded';
|
|
69
|
+
readonly documents: readonly CorpusDocument[];
|
|
70
|
+
/** Bounded, sanitised, in deterministic order. */
|
|
71
|
+
readonly warnings: readonly string[];
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* The project root: the nearest ancestor of `startDir` holding `.git` (a
|
|
75
|
+
* directory, or a file for a worktree), resolved with `realpath`; otherwise
|
|
76
|
+
* `startDir` itself, also resolved.
|
|
77
|
+
*
|
|
78
|
+
* This is a copy of the private `findGitWorktreeRoot` in
|
|
79
|
+
* `discovered-skills.ts`, and the two differ on purpose: search falls back to
|
|
80
|
+
* the start directory, while discovery returns null. Do not unify them.
|
|
81
|
+
* Importing `discovered-skills.ts` here would also pull its dependencies into
|
|
82
|
+
* the standalone search bin. This is the second use; extract at the third.
|
|
83
|
+
*/
|
|
84
|
+
export declare function resolveSearchRoot(startDir: string): string;
|
|
85
|
+
export type ParsedDocument = {
|
|
86
|
+
readonly ok: true;
|
|
87
|
+
readonly document: CorpusDocument;
|
|
88
|
+
} | {
|
|
89
|
+
readonly ok: false;
|
|
90
|
+
readonly reason: string;
|
|
91
|
+
};
|
|
92
|
+
/**
|
|
93
|
+
* Parse one file. Wraps `parseFrontmatter` (which stays unedited): strips a
|
|
94
|
+
* leading BOM, supplies the newline its regex needs when the closing `---` is
|
|
95
|
+
* the last line, and reads only known fields, narrowing each. No frontmatter
|
|
96
|
+
* means a body-only document with no warning. Invalid YAML, or a frontmatter
|
|
97
|
+
* block that is not a mapping, is not indexable.
|
|
98
|
+
*/
|
|
99
|
+
export declare function parseCorpusDocument(kind: DocumentKind, relativePath: string, content: string): ParsedDocument;
|
|
100
|
+
/**
|
|
101
|
+
* Load every indexable document of one kind under `root`, sorted by
|
|
102
|
+
* root-relative path in code-unit order. `root` should come from
|
|
103
|
+
* `resolveSearchRoot`.
|
|
104
|
+
*/
|
|
105
|
+
export declare function loadCorpus(root: string, kind?: DocumentKind): CorpusLoad;
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Lexical lane for durable-output search: tokenizer, natural log and BM25F.
|
|
3
|
+
*
|
|
4
|
+
* Pure and dependency-free: no I/O, no environment reads, no imports. Scores
|
|
5
|
+
* must be bit-identical on Bun and Node, because the lexical lane is the part
|
|
6
|
+
* of search that every surface shares. ECMAScript leaves `Math.log`
|
|
7
|
+
* implementation-approximated and the two runtimes disagree on it, so this
|
|
8
|
+
* module computes its own `ln` from + - * / only. By convention it also
|
|
9
|
+
* avoids `Math.pow`, `**`, `exp`, `Intl`, `localeCompare`, `toLocale*`,
|
|
10
|
+
* `Bun.` and `bun:`. Tests enforce the outcome (bit patterns under Node),
|
|
11
|
+
* not the convention.
|
|
12
|
+
*/
|
|
13
|
+
/** Indexed fields in the fixed order used for summation. */
|
|
14
|
+
export declare const LEXICAL_FIELDS: readonly ['title', 'tags', 'module', 'symptoms', 'applies_when', 'component', 'problem_type', 'body'];
|
|
15
|
+
export type LexicalField = (typeof LEXICAL_FIELDS)[number];
|
|
16
|
+
export interface Bm25fFieldParams {
|
|
17
|
+
/** Field weight `w_f`. */
|
|
18
|
+
readonly weight: number;
|
|
19
|
+
/** Length-normalisation strength `b_f`; 0 turns normalisation off. */
|
|
20
|
+
readonly b: number;
|
|
21
|
+
}
|
|
22
|
+
export interface Bm25fParams {
|
|
23
|
+
readonly k1: number;
|
|
24
|
+
readonly fields: Readonly<Record<LexicalField, Bm25fFieldParams>>;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* The one table the recall tuning edits. Metadata fields do not
|
|
28
|
+
* length-normalise; the body does. Frozen at Checkpoint A: the 27-cell retune
|
|
29
|
+
* grid in `tests/unit/search-recall.test.ts` scored 11 of 12 on the tune
|
|
30
|
+
* split for every cell with body b of 0.75 or 0.9 and 10 of 12 for b of 0.5,
|
|
31
|
+
* so the tie went to the starting values from the plan's Key Technical
|
|
32
|
+
* Decisions, unchanged.
|
|
33
|
+
*/
|
|
34
|
+
export declare const BM25F_PARAMS: {
|
|
35
|
+
readonly k1: 1.2;
|
|
36
|
+
readonly fields: {
|
|
37
|
+
readonly title: {
|
|
38
|
+
readonly weight: 3;
|
|
39
|
+
readonly b: 0;
|
|
40
|
+
};
|
|
41
|
+
readonly tags: {
|
|
42
|
+
readonly weight: 2.5;
|
|
43
|
+
readonly b: 0;
|
|
44
|
+
};
|
|
45
|
+
readonly module: {
|
|
46
|
+
readonly weight: 2;
|
|
47
|
+
readonly b: 0;
|
|
48
|
+
};
|
|
49
|
+
readonly symptoms: {
|
|
50
|
+
readonly weight: 3;
|
|
51
|
+
readonly b: 0;
|
|
52
|
+
};
|
|
53
|
+
readonly applies_when: {
|
|
54
|
+
readonly weight: 2;
|
|
55
|
+
readonly b: 0;
|
|
56
|
+
};
|
|
57
|
+
readonly component: {
|
|
58
|
+
readonly weight: 1.5;
|
|
59
|
+
readonly b: 0;
|
|
60
|
+
};
|
|
61
|
+
readonly problem_type: {
|
|
62
|
+
readonly weight: 1.5;
|
|
63
|
+
readonly b: 0;
|
|
64
|
+
};
|
|
65
|
+
readonly body: {
|
|
66
|
+
readonly weight: 1;
|
|
67
|
+
readonly b: 0.75;
|
|
68
|
+
};
|
|
69
|
+
};
|
|
70
|
+
};
|
|
71
|
+
/** Unique query terms kept after truncation. */
|
|
72
|
+
export declare const MAX_QUERY_TERMS = 64;
|
|
73
|
+
/**
|
|
74
|
+
* Splits text into index terms. Lowercases, then emits ASCII `[a-z0-9]` runs.
|
|
75
|
+
* A run joined by `_` or `-` also emits its whole joined identifier first, so
|
|
76
|
+
* `foo_bar` yields `foo_bar`, `foo`, `bar`. Every other character splits, a
|
|
77
|
+
* non-ASCII letter included (`naïve` yields `na`, `ve`, a documented limit).
|
|
78
|
+
* No stemming, no stopwords, no camelCase split. Duplicates are kept so the
|
|
79
|
+
* caller can count term frequency.
|
|
80
|
+
*/
|
|
81
|
+
export declare function tokenize(text: string): string[];
|
|
82
|
+
/**
|
|
83
|
+
* Unique query terms in first-seen order, truncated to `max`, then sorted by
|
|
84
|
+
* code unit so summation order is fixed. `truncated` tells the caller to add
|
|
85
|
+
* a note.
|
|
86
|
+
*/
|
|
87
|
+
export declare function uniqueQueryTerms(query: string, max?: number): {
|
|
88
|
+
readonly terms: string[];
|
|
89
|
+
readonly truncated: boolean;
|
|
90
|
+
};
|
|
91
|
+
/**
|
|
92
|
+
* Natural logarithm using only + - * /. Scales the argument by exact powers
|
|
93
|
+
* of two into [sqrt(1/2), sqrt(2)), then sums the atanh series
|
|
94
|
+
* `ln m = 2 * atanh((m - 1) / (m + 1))` with a fixed number of terms and adds
|
|
95
|
+
* `k * ln 2`. Relative error is near 1e-16 across the range search uses.
|
|
96
|
+
* Returns -Infinity for 0, and NaN for a negative or NaN argument.
|
|
97
|
+
*/
|
|
98
|
+
export declare function ln(x: number): number;
|
|
99
|
+
export interface LexicalDocument {
|
|
100
|
+
/** Root-relative path. Equal scores order by the code units of this. */
|
|
101
|
+
readonly id: string;
|
|
102
|
+
readonly fields: Readonly<Partial<Record<LexicalField, string>>>;
|
|
103
|
+
}
|
|
104
|
+
interface FieldStats {
|
|
105
|
+
readonly tf: Map<string, number>;
|
|
106
|
+
readonly length: number;
|
|
107
|
+
}
|
|
108
|
+
interface IndexedDocument {
|
|
109
|
+
readonly id: string;
|
|
110
|
+
/** Aligned with `LEXICAL_FIELDS`. */
|
|
111
|
+
readonly fields: readonly FieldStats[];
|
|
112
|
+
}
|
|
113
|
+
export interface LexicalIndex {
|
|
114
|
+
readonly params: Bm25fParams;
|
|
115
|
+
readonly docs: readonly IndexedDocument[];
|
|
116
|
+
/** Documents in which a term appears in any field. */
|
|
117
|
+
readonly documentFrequency: ReadonlyMap<string, number>;
|
|
118
|
+
/** Mean field length, aligned with `LEXICAL_FIELDS`. */
|
|
119
|
+
readonly averageLength: readonly number[];
|
|
120
|
+
}
|
|
121
|
+
export interface LexicalHit {
|
|
122
|
+
readonly id: string;
|
|
123
|
+
readonly score: number;
|
|
124
|
+
}
|
|
125
|
+
/** Builds the index over documents with named fields. Pure. */
|
|
126
|
+
export declare function buildLexicalIndex(documents: readonly LexicalDocument[], params?: Bm25fParams): LexicalIndex;
|
|
127
|
+
/**
|
|
128
|
+
* BM25F. For each term, a length-normalised weighted term frequency is summed
|
|
129
|
+
* over fields and saturated with `k1`, then scaled by
|
|
130
|
+
* `ln(1 + (N - df + 0.5) / (df + 0.5))`. Terms are deduplicated and sorted by
|
|
131
|
+
* code unit here, and fields are summed in `LEXICAL_FIELDS` order, so the
|
|
132
|
+
* score does not depend on the order the caller supplied terms in. Returns
|
|
133
|
+
* documents with a positive score, best first, ties by code-unit path.
|
|
134
|
+
*/
|
|
135
|
+
export declare function searchLexical(index: LexicalIndex, terms: readonly string[]): LexicalHit[];
|
|
136
|
+
export {};
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Renderer for durable-output search results.
|
|
3
|
+
*
|
|
4
|
+
* Turns the core's structured result into the one text every surface returns.
|
|
5
|
+
* Owns sanitising, field caps, the snippet window, the warning cap and the
|
|
6
|
+
* 16 KB cut with Systematic's own marker. Imports only types from the corpus
|
|
7
|
+
* module, so render tests never load filesystem code.
|
|
8
|
+
*
|
|
9
|
+
* Everything echoed passes `sanitizeInline` first, because titles, tags, file
|
|
10
|
+
* names and bodies are untrusted text that ends up in an agent's context and
|
|
11
|
+
* a human's terminal.
|
|
12
|
+
*/
|
|
13
|
+
import type { CorpusDocument } from './search-corpus.js';
|
|
14
|
+
/** Hard cap on rendered output, in UTF-8 bytes. */
|
|
15
|
+
export declare const MAX_OUTPUT_BYTES: number;
|
|
16
|
+
/** Appended on its own line when output is cut. */
|
|
17
|
+
export declare const TRUNCATION_MARKER = "[Systematic: search output truncated at 16 KB]";
|
|
18
|
+
export declare const MAX_TITLE_CHARS = 160;
|
|
19
|
+
export declare const MAX_TAGS = 8;
|
|
20
|
+
export declare const MAX_SNIPPET_CHARS = 240;
|
|
21
|
+
export declare const MAX_WARNINGS = 5;
|
|
22
|
+
/** The lifecycle line that lists the docs a successor replaces. */
|
|
23
|
+
export declare const SUPERSEDES_LABEL = "Supersedes:";
|
|
24
|
+
export type SearchHitStatus = 'active' | 'stale' | 'superseded';
|
|
25
|
+
export interface SearchHit {
|
|
26
|
+
/** 1-based position in the final list. */
|
|
27
|
+
readonly rank: number;
|
|
28
|
+
readonly document: CorpusDocument;
|
|
29
|
+
readonly status: SearchHitStatus;
|
|
30
|
+
/** Fully formed `Supersedes:` and `Caution:` lines, in print order. */
|
|
31
|
+
readonly lifecycle: readonly string[];
|
|
32
|
+
}
|
|
33
|
+
export interface SearchResult {
|
|
34
|
+
/** The query as the caller sent it; sanitised and capped when echoed. */
|
|
35
|
+
readonly query: string;
|
|
36
|
+
/** Unique, sorted query terms, used to pick snippet windows. */
|
|
37
|
+
readonly queryTerms: readonly string[];
|
|
38
|
+
/** `none`: no docs/solutions/. `empty`: the directory holds no indexable doc. */
|
|
39
|
+
readonly corpus: {
|
|
40
|
+
readonly state: 'none' | 'empty' | 'docs';
|
|
41
|
+
readonly docCount: number;
|
|
42
|
+
};
|
|
43
|
+
readonly hits: readonly SearchHit[];
|
|
44
|
+
readonly notes: readonly string[];
|
|
45
|
+
readonly warnings: readonly string[];
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* One line of safe text: terminal escape sequences removed, line breaks and
|
|
49
|
+
* tabs turned into a space, every other control character and invisible
|
|
50
|
+
* formatting character dropped, whitespace collapsed, then capped at `max`
|
|
51
|
+
* characters with an ellipsis.
|
|
52
|
+
*/
|
|
53
|
+
export declare function sanitizeInline(text: string, max?: number): string;
|
|
54
|
+
/**
|
|
55
|
+
* Cut `text` so the result, marker included, is at most `maxBytes` of UTF-8.
|
|
56
|
+
* The cut lands on a character boundary, and on a line boundary when the kept
|
|
57
|
+
* text has one. The marker goes on its own line. Text that already fits is
|
|
58
|
+
* returned unchanged.
|
|
59
|
+
*/
|
|
60
|
+
export declare function truncateUtf8(text: string, maxBytes: number, marker: string): string;
|
|
61
|
+
/**
|
|
62
|
+
* A one-line snippet of at most 240 characters. Picks the window of the body
|
|
63
|
+
* holding the most distinct query terms (earliest on a tie) and centres on it.
|
|
64
|
+
* With no match in the body it falls back to the symptoms, then the title.
|
|
65
|
+
* Only called for the hits being returned.
|
|
66
|
+
*/
|
|
67
|
+
export declare function extractSnippet(document: Pick<CorpusDocument, 'body' | 'symptoms' | 'title'>, queryTerms: readonly string[]): string;
|
|
68
|
+
/** Render a structured result as text, never more than `MAX_OUTPUT_BYTES`. */
|
|
69
|
+
export declare function renderSearchResult(result: SearchResult): string;
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Host adapters for the `systematic_search` tool: OpenCode v1 (zod), OpenCode
|
|
3
|
+
* v2 (JSON Schema through the tool transform) and Pi (typebox). Each does host
|
|
4
|
+
* I/O only: pick the start directory, hand over the settings, and map any
|
|
5
|
+
* failure to one fixed line. Validation, ranking, the lifecycle and every byte
|
|
6
|
+
* of the rendered text belong to `runSearch` in `search-core.ts`.
|
|
7
|
+
*
|
|
8
|
+
* No adapter asks for a permission: the tool reads only the project's own
|
|
9
|
+
* `docs/solutions/`, under a realpath containment check in the corpus loader.
|
|
10
|
+
* Every host schema declares `limit` as a plain integer and states the range
|
|
11
|
+
* in the description, so the core's fixed error is what an out-of-range value
|
|
12
|
+
* gets wherever the host passes it through.
|
|
13
|
+
*/
|
|
14
|
+
import type { ToolDefinition as PiToolDefinition } from '@earendil-works/pi-coding-agent';
|
|
15
|
+
import type { ToolDefinition } from '@opencode-ai/plugin';
|
|
16
|
+
import type { Type as TypeBuilder } from 'typebox';
|
|
17
|
+
import type { V2Installer } from './opencode-v2.js';
|
|
18
|
+
import { type SearchSettings } from './search-core.js';
|
|
19
|
+
/** Whether the config leaves the tool on. Only an explicit `enabled: false` removes it. */
|
|
20
|
+
export declare function isSearchEnabled(settings: SearchSettings | undefined): boolean;
|
|
21
|
+
export interface SearchToolV1Options {
|
|
22
|
+
readonly settings: SearchSettings | undefined;
|
|
23
|
+
/** `config.searchUnreadable`: adds the `config unreadable` note to every result. */
|
|
24
|
+
readonly unreadable?: boolean | undefined;
|
|
25
|
+
}
|
|
26
|
+
export declare function createSearchTool(options: SearchToolV1Options): ToolDefinition;
|
|
27
|
+
/**
|
|
28
|
+
* Registers `systematic_search` through the v2 tool transform. A name another
|
|
29
|
+
* plugin already holds is left alone and reported once. Nothing registers when
|
|
30
|
+
* `search.enabled` is false.
|
|
31
|
+
*/
|
|
32
|
+
export declare const installSearch: V2Installer;
|
|
33
|
+
export interface SearchToolPiOptions {
|
|
34
|
+
readonly settings: SearchSettings | undefined;
|
|
35
|
+
/** `config.searchUnreadable`: adds the `config unreadable` note to every result. */
|
|
36
|
+
readonly unreadable?: boolean | undefined;
|
|
37
|
+
/**
|
|
38
|
+
* typebox's `Type` builder, supplied by the Pi entry. This module is also
|
|
39
|
+
* imported by the OpenCode entries, and typebox is an optional peer that only
|
|
40
|
+
* Pi installs, so it must not be a runtime import here: the OpenCode bundle
|
|
41
|
+
* would carry a copy of it.
|
|
42
|
+
*/
|
|
43
|
+
readonly Type: typeof TypeBuilder;
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* The Pi definition. `src/pi.ts` registers it for the parent session and hands
|
|
47
|
+
* the same object to delegates as a custom tool, so both run one execute path.
|
|
48
|
+
* The start directory is the per-call `ctx.cwd`, which in a delegate is the
|
|
49
|
+
* delegate session's own cwd. The return type is the SDK's default, unnarrowed
|
|
50
|
+
* definition: a narrowed one is not assignable to `customTools` (its renderers
|
|
51
|
+
* take typed arguments), and `executeSearch` validates the raw arguments itself.
|
|
52
|
+
*/
|
|
53
|
+
export declare function createPiSearchTool(options: SearchToolPiOptions): PiToolDefinition;
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `search` config field: its zod schema piece, the pure merge rule, the
|
|
3
|
+
* user-level file selection, and a reader that never touches project config.
|
|
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.
|
|
11
|
+
*
|
|
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.
|
|
17
|
+
*/
|
|
18
|
+
import { z } from 'zod';
|
|
19
|
+
import type { SearchSettings } from './search-core.js';
|
|
20
|
+
/**
|
|
21
|
+
* The `search` block. No zod defaults anywhere: an absent `search` stays
|
|
22
|
+
* absent, and the core applies its own defaults at use time.
|
|
23
|
+
*/
|
|
24
|
+
export declare const SearchSettingsSchema: z.ZodObject<{
|
|
25
|
+
enabled: z.ZodOptional<z.ZodBoolean>;
|
|
26
|
+
}, z.core.$strict>;
|
|
27
|
+
/** What a successful parse of the `search` block yields. Assignable to the core's `SearchSettings`. */
|
|
28
|
+
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
|
+
};
|
|
36
|
+
/**
|
|
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.
|
|
41
|
+
*/
|
|
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;
|
|
45
|
+
/**
|
|
46
|
+
* One source's `search` block after schema validation. `settings` is the
|
|
47
|
+
* schema-parsed block, absent when the source has none. `unreadable` is true
|
|
48
|
+
* when the block failed its schema or the file could not be parsed.
|
|
49
|
+
*/
|
|
50
|
+
export interface SearchSettingsSource {
|
|
51
|
+
readonly settings?: SearchSchemaOutput | undefined;
|
|
52
|
+
readonly unreadable: boolean;
|
|
53
|
+
}
|
|
54
|
+
export interface MergedSearchSettings {
|
|
55
|
+
readonly settings: SearchSettings | undefined;
|
|
56
|
+
readonly unreadable: boolean;
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* The one merge rule, used by both `config.ts` and the reader. Sources arrive
|
|
60
|
+
* in priority order, user then custom. `enabled` takes the last source that
|
|
61
|
+
* defines it. `unreadable` is set when any source was.
|
|
62
|
+
*/
|
|
63
|
+
export declare function mergeSearchSettings(sources: readonly SearchSettingsSource[]): MergedSearchSettings;
|
|
64
|
+
/**
|
|
65
|
+
* Pick a config file in `dir`: `<basename>.jsonc` when it exists, else the
|
|
66
|
+
* `.json` path (returned even when absent, so callers that stat it still work).
|
|
67
|
+
*/
|
|
68
|
+
export declare function selectConfigFile(dir: string, basename: string): string;
|
|
69
|
+
export interface UserLevelConfigDirOptions {
|
|
70
|
+
readonly homeDir?: string;
|
|
71
|
+
readonly userConfigDir?: string;
|
|
72
|
+
/** `null` or a blank string means no custom directory. Leave the key out to read `OPENCODE_CONFIG_DIR`. */
|
|
73
|
+
readonly customConfigDir?: string | null;
|
|
74
|
+
}
|
|
75
|
+
export interface UserLevelConfigDirs {
|
|
76
|
+
readonly homeDir: string;
|
|
77
|
+
readonly userConfigDir: string;
|
|
78
|
+
readonly customConfigDir: string | undefined;
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* The user-level config directories: `<home>/.config/opencode`, and the
|
|
82
|
+
* `OPENCODE_CONFIG_DIR` directory when it is set. The variable is trimmed and
|
|
83
|
+
* a blank value counts as unset. `config.ts` and the reader both call this.
|
|
84
|
+
*/
|
|
85
|
+
export declare function resolveUserLevelConfigDirs(options?: UserLevelConfigDirOptions): UserLevelConfigDirs;
|
|
86
|
+
export interface UserLevelSearchLoad {
|
|
87
|
+
readonly settings: SearchSettings | undefined;
|
|
88
|
+
readonly warnings: readonly string[];
|
|
89
|
+
readonly unreadable: boolean;
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* Read the `search` block from the two user-level files, user then custom, and
|
|
93
|
+
* merge them. It never reads project config and never throws: an unparseable
|
|
94
|
+
* file or an invalid block gives one warning and `unreadable: true`.
|
|
95
|
+
*/
|
|
96
|
+
export declare function loadUserLevelSearchSettings(options?: UserLevelConfigDirOptions): UserLevelSearchLoad;
|