@fro.bot/systematic 3.27.2 → 3.28.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.
Files changed (34) hide show
  1. package/ATTRIBUTIONS.md +2 -2
  2. package/HARNESSES.md +23 -10
  3. package/agents/research/learnings-researcher.md +49 -9
  4. package/dist/claude-code-search.d.ts +30 -0
  5. package/dist/claude-code-validator-bin.d.ts +17 -0
  6. package/dist/cli.d.ts +18 -0
  7. package/dist/cli.js +335 -108
  8. package/dist/{index-608preny.js → index-9chxhh5j.js} +1120 -72
  9. package/dist/index.js +117 -3
  10. package/dist/lib/agent-resolver.d.ts +15 -3
  11. package/dist/lib/config-protected-fields.d.ts +1 -1
  12. package/dist/lib/config-schema.d.ts +6 -0
  13. package/dist/lib/config.d.ts +13 -0
  14. package/dist/lib/main-module.d.ts +30 -0
  15. package/dist/lib/opencode-v2-skills.d.ts +12 -2
  16. package/dist/lib/opencode-v2.d.ts +1 -0
  17. package/dist/lib/pi-delegate-session.d.ts +3 -1
  18. package/dist/lib/pi-delegate-tool.d.ts +12 -1
  19. package/dist/lib/search-cli.d.ts +52 -0
  20. package/dist/lib/search-core.d.ts +128 -0
  21. package/dist/lib/search-corpus.d.ts +105 -0
  22. package/dist/lib/search-lexical.d.ts +136 -0
  23. package/dist/lib/search-render.d.ts +69 -0
  24. package/dist/lib/search-tool.d.ts +53 -0
  25. package/dist/lib/search-user-config.d.ts +96 -0
  26. package/dist/pi.js +1169 -82
  27. package/package.json +5 -5
  28. package/skills/ce-review/SKILL.md +1 -1
  29. package/skills/ce-review/references/review-output-template.md +1 -1
  30. package/skills/ce-review/scripts/validate-review.mjs +1 -3
  31. package/skills/using-systematic/references/claude-code-profile.md +1 -0
  32. package/skills/using-systematic/references/opencode-profile.md +1 -0
  33. package/skills/using-systematic/references/opencode-v2-profile.md +1 -0
  34. package/skills/using-systematic/references/pi-profile.md +1 -0
@@ -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;