@fro.bot/systematic 3.28.1 → 3.29.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/HARNESSES.md +11 -8
- package/agents/research/learnings-researcher.md +76 -53
- package/dist/cli.js +14 -9
- package/dist/{index-9chxhh5j.js → index-e467g4b6.js} +204 -84
- package/dist/index.js +1 -1
- package/dist/lib/search-core.d.ts +39 -21
- package/dist/lib/search-corpus.d.ts +25 -4
- package/dist/lib/search-render.d.ts +23 -4
- package/dist/lib/search-tool.d.ts +2 -1
- package/dist/pi.js +205 -85
- package/package.json +1 -1
- package/skills/ce-brainstorm/SKILL.md +6 -2
- package/skills/ce-ideate/SKILL.md +5 -2
- package/skills/ce-plan/SKILL.md +10 -5
- package/skills/ce-plan/references/deepening-workflow.md +3 -1
- package/skills/ce-plan/references/plan-sections.md +4 -2
- package/skills/deepen-plan/SKILL.md +3 -1
|
@@ -9671,6 +9671,24 @@ var KIND_TABLE = {
|
|
|
9671
9671
|
excludedFiles: ["readme.md", "critical-patterns.md"],
|
|
9672
9672
|
excludedDirs: ["_archived"],
|
|
9673
9673
|
lifecycle: true
|
|
9674
|
+
},
|
|
9675
|
+
plan: {
|
|
9676
|
+
dir: "docs/plans",
|
|
9677
|
+
excludedFiles: ["readme.md"],
|
|
9678
|
+
excludedDirs: ["_archived"],
|
|
9679
|
+
lifecycle: true
|
|
9680
|
+
},
|
|
9681
|
+
brainstorm: {
|
|
9682
|
+
dir: "docs/brainstorms",
|
|
9683
|
+
excludedFiles: ["readme.md"],
|
|
9684
|
+
excludedDirs: ["_archived"],
|
|
9685
|
+
lifecycle: true
|
|
9686
|
+
},
|
|
9687
|
+
ideation: {
|
|
9688
|
+
dir: "docs/ideation",
|
|
9689
|
+
excludedFiles: ["readme.md"],
|
|
9690
|
+
excludedDirs: ["_archived"],
|
|
9691
|
+
lifecycle: true
|
|
9674
9692
|
}
|
|
9675
9693
|
};
|
|
9676
9694
|
function isDocumentKind(value) {
|
|
@@ -9794,6 +9812,10 @@ function discoverFiles(spec, directory, prefix, depth, found, warnings) {
|
|
|
9794
9812
|
function narrowString(value) {
|
|
9795
9813
|
return typeof value === "string" ? value : undefined;
|
|
9796
9814
|
}
|
|
9815
|
+
function narrowNonEmptyString(value) {
|
|
9816
|
+
const trimmed = narrowString(value)?.trim();
|
|
9817
|
+
return trimmed ? trimmed : undefined;
|
|
9818
|
+
}
|
|
9797
9819
|
function narrowStringList(value) {
|
|
9798
9820
|
const items = Array.isArray(value) ? value : [value];
|
|
9799
9821
|
const result = [];
|
|
@@ -9826,13 +9848,13 @@ function parseCorpusDocument(kind, relativePath, content) {
|
|
|
9826
9848
|
}
|
|
9827
9849
|
const data = isRecord(parsed.data) ? parsed.data : {};
|
|
9828
9850
|
const fileName = relativePath.slice(relativePath.lastIndexOf("/") + 1);
|
|
9829
|
-
const title =
|
|
9851
|
+
const title = narrowNonEmptyString(data.title) ?? narrowNonEmptyString(data.topic) ?? fileName.replace(/\.md$/i, "");
|
|
9830
9852
|
return {
|
|
9831
9853
|
ok: true,
|
|
9832
9854
|
document: {
|
|
9833
9855
|
path: relativePath,
|
|
9834
9856
|
kind,
|
|
9835
|
-
title
|
|
9857
|
+
title,
|
|
9836
9858
|
tags: narrowStringList(data.tags),
|
|
9837
9859
|
module: narrowString(data.module),
|
|
9838
9860
|
component: narrowString(data.component),
|
|
@@ -9916,10 +9938,10 @@ function loadCorpus(root, kind = "solution") {
|
|
|
9916
9938
|
const capSkipped = candidates.length - considered;
|
|
9917
9939
|
if (capSkipped > 0) {
|
|
9918
9940
|
const atLeast = found.truncated ? "at least " : "";
|
|
9919
|
-
warnings.push(
|
|
9941
|
+
warnings.push(`${spec.dir}: file limit of ${MAX_FILES} reached; skipped ${atLeast}${capSkipped} files`);
|
|
9920
9942
|
}
|
|
9921
9943
|
if (budgetSkipped > 0) {
|
|
9922
|
-
warnings.push(
|
|
9944
|
+
warnings.push(`${spec.dir}: text budget of ${MAX_TOTAL_BYTES} bytes reached; skipped ${budgetSkipped} files`);
|
|
9923
9945
|
}
|
|
9924
9946
|
return { state: "loaded", documents, warnings };
|
|
9925
9947
|
}
|
|
@@ -10084,6 +10106,7 @@ var MAX_TAGS = 8;
|
|
|
10084
10106
|
var MAX_SNIPPET_CHARS = 240;
|
|
10085
10107
|
var MAX_WARNINGS = 5;
|
|
10086
10108
|
var SUPERSEDES_LABEL = "Supersedes:";
|
|
10109
|
+
var SUCCESSOR_LABEL = "Successor:";
|
|
10087
10110
|
var MAX_TAG_CHARS = 64;
|
|
10088
10111
|
var MAX_MODULE_CHARS = 120;
|
|
10089
10112
|
var MAX_QUERY_ECHO_CHARS = 200;
|
|
@@ -10249,25 +10272,46 @@ function extractSnippet(document, queryTerms) {
|
|
|
10249
10272
|
function plural(count, singular) {
|
|
10250
10273
|
return `${count} ${singular}${count === 1 ? "" : "s"}`;
|
|
10251
10274
|
}
|
|
10275
|
+
function joinOr(items) {
|
|
10276
|
+
const last = items[items.length - 1];
|
|
10277
|
+
if (items.length < 2 || last === undefined)
|
|
10278
|
+
return items.join("");
|
|
10279
|
+
return `${items.slice(0, -1).join(", ")} or ${last}`;
|
|
10280
|
+
}
|
|
10281
|
+
function kindTokens(kinds) {
|
|
10282
|
+
return kinds.map(({ kind, state, docCount }) => `${kind} ${state === "docs" ? docCount : state}`).join(", ");
|
|
10283
|
+
}
|
|
10252
10284
|
function renderHeader(result) {
|
|
10253
10285
|
const query = sanitizeInline(result.query, MAX_QUERY_ECHO_CHARS);
|
|
10254
10286
|
const prefix = `Search "${query}":`;
|
|
10255
|
-
|
|
10256
|
-
|
|
10257
|
-
|
|
10287
|
+
const { corpus } = result;
|
|
10288
|
+
const [only, ...others] = corpus.kinds;
|
|
10289
|
+
const single = only !== undefined && others.length === 0;
|
|
10290
|
+
switch (corpus.state) {
|
|
10291
|
+
case "none": {
|
|
10292
|
+
const dirs = joinOr(corpus.kinds.map(({ dir }) => `${dir}/`));
|
|
10293
|
+
return `${prefix} corpus: none (no ${dirs} directory under the project root).`;
|
|
10294
|
+
}
|
|
10258
10295
|
case "empty":
|
|
10259
|
-
return `${prefix} corpus: empty (
|
|
10260
|
-
case "docs":
|
|
10261
|
-
|
|
10296
|
+
return single ? `${prefix} corpus: empty (${only.dir}/ holds no indexable docs).` : `${prefix} corpus: empty (no indexable docs: ${kindTokens(corpus.kinds)}).`;
|
|
10297
|
+
case "docs": {
|
|
10298
|
+
const counts = `${plural(corpus.docCount, "doc")}, ${plural(result.hits.length, "hit")}`;
|
|
10299
|
+
const searched = single ? only.dir : kindTokens(corpus.kinds);
|
|
10300
|
+
return `${prefix} ${counts}. Corpus: ${searched}.`;
|
|
10301
|
+
}
|
|
10262
10302
|
}
|
|
10263
10303
|
}
|
|
10264
10304
|
function renderLifecycleLine(line) {
|
|
10265
|
-
const
|
|
10266
|
-
if (
|
|
10267
|
-
|
|
10305
|
+
const supersedes = `${SUPERSEDES_LABEL} `;
|
|
10306
|
+
if (line.startsWith(supersedes)) {
|
|
10307
|
+
const paths = line.slice(supersedes.length).split(", ").map((path) => sanitizeInline(path, MAX_PATH_CHARS2)).filter((path) => path !== "");
|
|
10308
|
+
return `${supersedes}${paths.join(", ")}`;
|
|
10309
|
+
}
|
|
10310
|
+
const successor = `${SUCCESSOR_LABEL} `;
|
|
10311
|
+
if (line.startsWith(successor)) {
|
|
10312
|
+
return `${successor}${sanitizeInline(line.slice(successor.length), MAX_PATH_CHARS2)}`;
|
|
10268
10313
|
}
|
|
10269
|
-
|
|
10270
|
-
return `${prefix}${paths.join(", ")}`;
|
|
10314
|
+
return sanitizeInline(line, MAX_LIFECYCLE_LINE_CHARS);
|
|
10271
10315
|
}
|
|
10272
10316
|
function renderHit(hit, queryTerms) {
|
|
10273
10317
|
const { document } = hit;
|
|
@@ -10323,10 +10367,13 @@ var DEFAULT_LIMIT = 8;
|
|
|
10323
10367
|
var MIN_LIMIT = 1;
|
|
10324
10368
|
var MAX_LIMIT = 20;
|
|
10325
10369
|
var MAX_QUERY_CHARS = 2000;
|
|
10326
|
-
var
|
|
10370
|
+
var KIND_SELECTOR_ALL = "all";
|
|
10371
|
+
var DOCUMENT_KINDS = Object.keys(KIND_TABLE).filter(isDocumentKind);
|
|
10372
|
+
var KIND_NAMES = [...DOCUMENT_KINDS, KIND_SELECTOR_ALL];
|
|
10373
|
+
var SEARCH_TOOL_DESCRIPTION = "Search this project's durable outputs by symptom, error text, module or topic: the docs/solutions learnings, and the docs/plans, docs/brainstorms and docs/ideation documents that earlier work wrote. Returns ranked hits with path, title, kind, snippet, tags and status. A superseded document is replaced by its successor in the same kind, a successor in another kind is named on a Successor line, 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 that a past learning, plan, brainstorm or ideation doc may already cover.";
|
|
10327
10374
|
var SEARCH_ARG_DESCRIPTIONS = {
|
|
10328
10375
|
query: `What to look for: a symptom, error message, module or topic, in plain words. At most ${MAX_QUERY_CHARS} characters.`,
|
|
10329
|
-
kind:
|
|
10376
|
+
kind: `Optional. The kind of durable output to search: ${DOCUMENT_KINDS.map((kind) => `"${kind}" (${KIND_TABLE[kind].dir}/)`).join(", ")}, or "${KIND_SELECTOR_ALL}" for every kind in one ranking. Defaults to "solution".`,
|
|
10330
10377
|
limit: `Optional. How many hits to return, an integer from ${MIN_LIMIT} to ${MAX_LIMIT}. Defaults to ${DEFAULT_LIMIT}.`
|
|
10331
10378
|
};
|
|
10332
10379
|
var SEARCH_NOTICES = {
|
|
@@ -10335,19 +10382,20 @@ var SEARCH_NOTICES = {
|
|
|
10335
10382
|
};
|
|
10336
10383
|
var SEARCH_CONFIG_UNREADABLE_NOTE = "config unreadable";
|
|
10337
10384
|
var MAX_SUCCESSOR_HOPS = 5;
|
|
10338
|
-
var SUCCESSOR_PATH_PREFIX = `${KIND_TABLE.solution.dir}/`;
|
|
10339
10385
|
var CAUTION_LABEL = "Caution:";
|
|
10340
10386
|
var SUCCESSOR_UNRESOLVED_TEXT = "successor unresolved";
|
|
10341
10387
|
var STALE_CAUTION_TEXT = "marked stale";
|
|
10342
10388
|
var MAX_STALE_REASON_CHARS = 200;
|
|
10389
|
+
var UNSPECIFIED_STATUS = "unspecified";
|
|
10343
10390
|
var SEARCH_ERRORS = {
|
|
10344
10391
|
queryEmpty: "Error: query must be a non-empty string.",
|
|
10345
10392
|
queryTooLong: `Error: query must be at most ${MAX_QUERY_CHARS} characters.`,
|
|
10346
|
-
kindUnknown: `Error: kind must be one of: ${
|
|
10393
|
+
kindUnknown: `Error: kind must be one of: ${KIND_NAMES.join(", ")}.`,
|
|
10347
10394
|
limitInvalid: `Error: limit must be an integer from ${MIN_LIMIT} to ${MAX_LIMIT}.`
|
|
10348
10395
|
};
|
|
10349
|
-
function isSuccessorPathForm(value) {
|
|
10350
|
-
|
|
10396
|
+
function isSuccessorPathForm(value, kind = "solution") {
|
|
10397
|
+
const spec = KIND_TABLE[kind];
|
|
10398
|
+
if (!value.startsWith(`${spec.dir}/`))
|
|
10351
10399
|
return false;
|
|
10352
10400
|
if (!value.endsWith(".md"))
|
|
10353
10401
|
return false;
|
|
@@ -10355,31 +10403,50 @@ function isSuccessorPathForm(value) {
|
|
|
10355
10403
|
if (segments.includes(".."))
|
|
10356
10404
|
return false;
|
|
10357
10405
|
const name = segments[segments.length - 1]?.toLowerCase();
|
|
10358
|
-
if (name
|
|
10359
|
-
return false;
|
|
10360
|
-
if (segments.includes("_archived"))
|
|
10406
|
+
if (name !== undefined && spec.excludedFiles.includes(name)) {
|
|
10361
10407
|
return false;
|
|
10362
|
-
|
|
10408
|
+
}
|
|
10409
|
+
return !segments.some((segment) => spec.excludedDirs.includes(segment));
|
|
10410
|
+
}
|
|
10411
|
+
function successorFormKind(value) {
|
|
10412
|
+
return DOCUMENT_KINDS.find((kind) => isSuccessorPathForm(value, kind));
|
|
10363
10413
|
}
|
|
10364
|
-
function
|
|
10414
|
+
function hasStatus(document, wanted) {
|
|
10415
|
+
if (document.status === undefined)
|
|
10416
|
+
return false;
|
|
10417
|
+
if (document.kind === "solution")
|
|
10418
|
+
return document.status === wanted;
|
|
10419
|
+
return document.status.trim().toLowerCase() === wanted;
|
|
10420
|
+
}
|
|
10421
|
+
function stepSuccessor(current, byPath, visited) {
|
|
10422
|
+
const link = current.supersededBy;
|
|
10423
|
+
if (link.state !== "value")
|
|
10424
|
+
return { outcome: "unresolved" };
|
|
10425
|
+
if (!isSuccessorPathForm(link.value, current.kind)) {
|
|
10426
|
+
if (successorFormKind(link.value) === undefined) {
|
|
10427
|
+
return { outcome: "unresolved" };
|
|
10428
|
+
}
|
|
10429
|
+
return { outcome: "resolved", document: current, successorPath: link.value };
|
|
10430
|
+
}
|
|
10431
|
+
const target = byPath.get(link.value);
|
|
10432
|
+
if (target === undefined || visited.has(target.path)) {
|
|
10433
|
+
return { outcome: "unresolved" };
|
|
10434
|
+
}
|
|
10435
|
+
visited.add(target.path);
|
|
10436
|
+
if (hasStatus(target, "superseded"))
|
|
10437
|
+
return { outcome: "continue", next: target };
|
|
10438
|
+
return { outcome: "resolved", document: target, successorPath: undefined };
|
|
10439
|
+
}
|
|
10440
|
+
function walkSuccessors(candidate, byPath) {
|
|
10365
10441
|
const visited = new Set([candidate.path]);
|
|
10366
10442
|
let current = candidate;
|
|
10367
10443
|
for (let hop = 1;hop <= MAX_SUCCESSOR_HOPS; hop++) {
|
|
10368
|
-
const
|
|
10369
|
-
if (
|
|
10370
|
-
return;
|
|
10371
|
-
|
|
10372
|
-
if (visited.has(link.value))
|
|
10373
|
-
return;
|
|
10374
|
-
const target = byPath.get(link.value);
|
|
10375
|
-
if (target === undefined)
|
|
10376
|
-
return;
|
|
10377
|
-
visited.add(target.path);
|
|
10378
|
-
if (target.status !== "superseded")
|
|
10379
|
-
return target;
|
|
10380
|
-
current = target;
|
|
10444
|
+
const step = stepSuccessor(current, byPath, visited);
|
|
10445
|
+
if (step.outcome !== "continue")
|
|
10446
|
+
return step;
|
|
10447
|
+
current = step.next;
|
|
10381
10448
|
}
|
|
10382
|
-
return;
|
|
10449
|
+
return { outcome: "unresolved" };
|
|
10383
10450
|
}
|
|
10384
10451
|
function compareCodeUnits3(a, b) {
|
|
10385
10452
|
if (a < b)
|
|
@@ -10394,18 +10461,21 @@ function resolveLifecycle(ranked, documents) {
|
|
|
10394
10461
|
let target = candidate;
|
|
10395
10462
|
let replaces;
|
|
10396
10463
|
let unresolved = false;
|
|
10397
|
-
|
|
10398
|
-
|
|
10399
|
-
|
|
10464
|
+
let successor;
|
|
10465
|
+
if (hasStatus(candidate, "superseded")) {
|
|
10466
|
+
const walk = walkSuccessors(candidate, byPath);
|
|
10467
|
+
if (walk.outcome === "unresolved")
|
|
10400
10468
|
unresolved = true;
|
|
10401
10469
|
else {
|
|
10402
|
-
target =
|
|
10403
|
-
|
|
10470
|
+
target = walk.document;
|
|
10471
|
+
successor = walk.successorPath;
|
|
10472
|
+
if (target.path !== candidate.path)
|
|
10473
|
+
replaces = candidate.path;
|
|
10404
10474
|
}
|
|
10405
10475
|
}
|
|
10406
10476
|
let entry = entries.get(target.path);
|
|
10407
10477
|
if (entry === undefined) {
|
|
10408
|
-
entry = { document: target, replaced: new Set, unresolved };
|
|
10478
|
+
entry = { document: target, replaced: new Set, unresolved, successor };
|
|
10409
10479
|
entries.set(target.path, entry);
|
|
10410
10480
|
order.push(target.path);
|
|
10411
10481
|
}
|
|
@@ -10420,24 +10490,33 @@ function resolveLifecycle(ranked, documents) {
|
|
|
10420
10490
|
{
|
|
10421
10491
|
document: entry.document,
|
|
10422
10492
|
supersedes: [...entry.replaced].sort(compareCodeUnits3),
|
|
10423
|
-
unresolved: entry.unresolved
|
|
10493
|
+
unresolved: entry.unresolved,
|
|
10494
|
+
successor: entry.successor
|
|
10424
10495
|
}
|
|
10425
10496
|
];
|
|
10426
10497
|
});
|
|
10427
10498
|
}
|
|
10428
10499
|
function entryStatus(entry) {
|
|
10429
|
-
|
|
10500
|
+
const { document } = entry;
|
|
10501
|
+
if (document.kind !== "solution") {
|
|
10502
|
+
const { status } = document;
|
|
10503
|
+
return status !== undefined && status.trim() !== "" ? status : UNSPECIFIED_STATUS;
|
|
10504
|
+
}
|
|
10505
|
+
if (entry.unresolved || entry.successor !== undefined)
|
|
10430
10506
|
return "superseded";
|
|
10431
|
-
return
|
|
10507
|
+
return document.status === "stale" ? "stale" : "active";
|
|
10432
10508
|
}
|
|
10433
10509
|
function lifecycleLines(entry) {
|
|
10434
10510
|
const lines = [];
|
|
10435
10511
|
if (entry.supersedes.length > 0) {
|
|
10436
10512
|
lines.push(`${SUPERSEDES_LABEL} ${entry.supersedes.join(", ")}`);
|
|
10437
10513
|
}
|
|
10514
|
+
if (entry.successor !== undefined) {
|
|
10515
|
+
lines.push(`${SUCCESSOR_LABEL} ${entry.successor}`);
|
|
10516
|
+
}
|
|
10438
10517
|
if (entry.unresolved) {
|
|
10439
10518
|
lines.push(`${CAUTION_LABEL} ${SUCCESSOR_UNRESOLVED_TEXT}`);
|
|
10440
|
-
} else if (entry.document
|
|
10519
|
+
} else if (hasStatus(entry.document, "stale")) {
|
|
10441
10520
|
const reason = sanitizeInline(entry.document.staleReason ?? "", MAX_STALE_REASON_CHARS);
|
|
10442
10521
|
lines.push(reason === "" ? `${CAUTION_LABEL} ${STALE_CAUTION_TEXT}` : `${CAUTION_LABEL} ${STALE_CAUTION_TEXT}: ${reason}`);
|
|
10443
10522
|
}
|
|
@@ -10460,6 +10539,13 @@ function toLexicalDocument(document) {
|
|
|
10460
10539
|
}
|
|
10461
10540
|
};
|
|
10462
10541
|
}
|
|
10542
|
+
function requestedKinds(value) {
|
|
10543
|
+
if (value === undefined)
|
|
10544
|
+
return ["solution"];
|
|
10545
|
+
if (value === KIND_SELECTOR_ALL)
|
|
10546
|
+
return DOCUMENT_KINDS;
|
|
10547
|
+
return isDocumentKind(value) ? [value] : undefined;
|
|
10548
|
+
}
|
|
10463
10549
|
function validate2(request) {
|
|
10464
10550
|
const { query } = request;
|
|
10465
10551
|
if (typeof query !== "string" || query.trim() === "") {
|
|
@@ -10468,12 +10554,9 @@ function validate2(request) {
|
|
|
10468
10554
|
if (query.length > MAX_QUERY_CHARS) {
|
|
10469
10555
|
return { ok: false, error: SEARCH_ERRORS.queryTooLong };
|
|
10470
10556
|
}
|
|
10471
|
-
|
|
10472
|
-
if (
|
|
10473
|
-
|
|
10474
|
-
return { ok: false, error: SEARCH_ERRORS.kindUnknown };
|
|
10475
|
-
}
|
|
10476
|
-
kind = request.kind;
|
|
10557
|
+
const kinds = requestedKinds(request.kind);
|
|
10558
|
+
if (kinds === undefined) {
|
|
10559
|
+
return { ok: false, error: SEARCH_ERRORS.kindUnknown };
|
|
10477
10560
|
}
|
|
10478
10561
|
let limit = DEFAULT_LIMIT;
|
|
10479
10562
|
if (request.limit !== undefined) {
|
|
@@ -10483,20 +10566,74 @@ function validate2(request) {
|
|
|
10483
10566
|
}
|
|
10484
10567
|
limit = value;
|
|
10485
10568
|
}
|
|
10486
|
-
return { ok: true, query,
|
|
10569
|
+
return { ok: true, query, kinds, limit };
|
|
10570
|
+
}
|
|
10571
|
+
var SKIPPED_PREFIX = "skipped ";
|
|
10572
|
+
function skipReason(warning) {
|
|
10573
|
+
if (!warning.startsWith(SKIPPED_PREFIX))
|
|
10574
|
+
return;
|
|
10575
|
+
const colon = warning.lastIndexOf(": ");
|
|
10576
|
+
return colon === -1 ? undefined : warning.slice(colon + 2);
|
|
10577
|
+
}
|
|
10578
|
+
function plural2(count, singular) {
|
|
10579
|
+
return `${count} ${singular}${count === 1 ? "" : "s"}`;
|
|
10580
|
+
}
|
|
10581
|
+
function skipSummary(dir, reasons) {
|
|
10582
|
+
const parts = [...reasons].sort(([a, x], [b, y]) => y - x || compareCodeUnits3(a, b)).map(([reason, count]) => `${count} ${reason}`);
|
|
10583
|
+
const total = [...reasons.values()].reduce((sum, count) => sum + count, 0);
|
|
10584
|
+
return `${dir}: skipped ${plural2(total, "file")} (${parts.join(", ")})`;
|
|
10585
|
+
}
|
|
10586
|
+
function aggregateWarnings(loads) {
|
|
10587
|
+
const structural = [];
|
|
10588
|
+
const summaries = [];
|
|
10589
|
+
for (const { kind, load } of loads) {
|
|
10590
|
+
const reasons = new Map;
|
|
10591
|
+
for (const warning of load.warnings) {
|
|
10592
|
+
const reason = skipReason(warning);
|
|
10593
|
+
if (reason === undefined)
|
|
10594
|
+
structural.push(warning);
|
|
10595
|
+
else
|
|
10596
|
+
reasons.set(reason, (reasons.get(reason) ?? 0) + 1);
|
|
10597
|
+
}
|
|
10598
|
+
if (reasons.size > 0) {
|
|
10599
|
+
summaries.push(skipSummary(KIND_TABLE[kind].dir, reasons));
|
|
10600
|
+
}
|
|
10601
|
+
}
|
|
10602
|
+
return [...structural, ...summaries];
|
|
10603
|
+
}
|
|
10604
|
+
function kindCorpus({ kind, load }) {
|
|
10605
|
+
const docCount = load.documents.length;
|
|
10606
|
+
let state = "docs";
|
|
10607
|
+
if (load.state === "none")
|
|
10608
|
+
state = "none";
|
|
10609
|
+
else if (docCount === 0)
|
|
10610
|
+
state = "empty";
|
|
10611
|
+
return { kind, dir: KIND_TABLE[kind].dir, state, docCount };
|
|
10612
|
+
}
|
|
10613
|
+
function combinedState(kinds) {
|
|
10614
|
+
if (kinds.some((report) => report.state === "docs"))
|
|
10615
|
+
return "docs";
|
|
10616
|
+
return kinds.every((report) => report.state === "none") ? "none" : "empty";
|
|
10487
10617
|
}
|
|
10488
10618
|
async function runSearch(request, options) {
|
|
10489
10619
|
const checked = validate2(request);
|
|
10490
10620
|
if (!checked.ok)
|
|
10491
10621
|
return { ok: false, text: checked.error };
|
|
10492
|
-
const { query,
|
|
10622
|
+
const { query, kinds, limit } = checked;
|
|
10493
10623
|
const root = resolveSearchRoot(options.startDir);
|
|
10494
|
-
const
|
|
10624
|
+
const loader = options.corpusLoader ?? loadCorpus;
|
|
10625
|
+
const loads = kinds.map((kind) => ({ kind, load: loader(root, kind) }));
|
|
10626
|
+
const reports = loads.map(kindCorpus);
|
|
10627
|
+
const corpus = {
|
|
10628
|
+
state: combinedState(reports),
|
|
10629
|
+
docCount: reports.reduce((sum, report) => sum + report.docCount, 0),
|
|
10630
|
+
kinds: reports
|
|
10631
|
+
};
|
|
10495
10632
|
const { terms, truncated } = uniqueQueryTerms(query);
|
|
10496
10633
|
const base = {
|
|
10497
10634
|
query,
|
|
10498
10635
|
queryTerms: terms,
|
|
10499
|
-
warnings:
|
|
10636
|
+
warnings: aggregateWarnings(loads)
|
|
10500
10637
|
};
|
|
10501
10638
|
const noteList = [...options.notes ?? []];
|
|
10502
10639
|
if (truncated)
|
|
@@ -10506,43 +10643,26 @@ async function runSearch(request, options) {
|
|
|
10506
10643
|
text: renderSearchResult(result),
|
|
10507
10644
|
result
|
|
10508
10645
|
});
|
|
10509
|
-
if (
|
|
10510
|
-
return finish({
|
|
10511
|
-
...base,
|
|
10512
|
-
corpus: { state: "none", docCount: 0 },
|
|
10513
|
-
hits: [],
|
|
10514
|
-
notes: noteList
|
|
10515
|
-
});
|
|
10516
|
-
}
|
|
10517
|
-
if (load.documents.length === 0) {
|
|
10518
|
-
return finish({
|
|
10519
|
-
...base,
|
|
10520
|
-
corpus: { state: "empty", docCount: 0 },
|
|
10521
|
-
hits: [],
|
|
10522
|
-
notes: noteList
|
|
10523
|
-
});
|
|
10646
|
+
if (corpus.state !== "docs") {
|
|
10647
|
+
return finish({ ...base, corpus, hits: [], notes: noteList });
|
|
10524
10648
|
}
|
|
10525
|
-
const
|
|
10649
|
+
const documents = loads.flatMap(({ load }) => load.documents).sort((a, b) => compareCodeUnits3(a.path, b.path));
|
|
10650
|
+
const index = buildLexicalIndex(documents.map(toLexicalDocument), options.lexicalParams ?? BM25F_PARAMS);
|
|
10526
10651
|
const lexical = searchLexical(index, terms);
|
|
10527
|
-
const byPath = new Map(
|
|
10652
|
+
const byPath = new Map(documents.map((doc) => [doc.path, doc]));
|
|
10528
10653
|
const candidates = [];
|
|
10529
10654
|
for (const hit of lexical) {
|
|
10530
10655
|
const document = byPath.get(hit.id);
|
|
10531
10656
|
if (document !== undefined)
|
|
10532
10657
|
candidates.push(document);
|
|
10533
10658
|
}
|
|
10534
|
-
const hits = resolveLifecycle(candidates,
|
|
10659
|
+
const hits = resolveLifecycle(candidates, documents).slice(0, limit).map((entry, position) => ({
|
|
10535
10660
|
rank: position + 1,
|
|
10536
10661
|
document: entry.document,
|
|
10537
10662
|
status: entryStatus(entry),
|
|
10538
10663
|
lifecycle: lifecycleLines(entry)
|
|
10539
10664
|
}));
|
|
10540
|
-
return finish({
|
|
10541
|
-
...base,
|
|
10542
|
-
corpus: { state: "docs", docCount: load.documents.length },
|
|
10543
|
-
hits,
|
|
10544
|
-
notes: noteList
|
|
10545
|
-
});
|
|
10665
|
+
return finish({ ...base, corpus, hits, notes: noteList });
|
|
10546
10666
|
}
|
|
10547
10667
|
|
|
10548
10668
|
export { parseFrontmatter, parse, parseTree, modify, applyEdits, CONFIG_PROTECTED_FIELD_PATHS, _isoDateTime, _isoDate, _isoTime, _isoDuration, string, ZodISODateTime, ZodISODate, ZodISOTime, ZodISODuration, number, boolean, array, object, union, discriminatedUnion, _enum, literal, loadUserLevelSearchSettings, AgentOverlaySchema, CategoryOverlaySchema, isRecord, isPermissionSetting, isAgentMode, extractString, toSourcedPiSubagentsOverlays, resolveRouting, loadConfig, loadConfigWithSources, isAgentDisabled, collectRoutingTargets, getConfigPaths, isDiscoverableMarkdown, findAgentsInDir, extractAgentFrontmatter, findCommandsInDir, extractCommandFrontmatter, findSkillsInDir, discoverSkills, resolveSearchRoot, SEARCH_TOOL_NAME, SEARCH_ARGS, MIN_LIMIT, MAX_LIMIT, SEARCH_TOOL_DESCRIPTION, SEARCH_ARG_DESCRIPTIONS, SEARCH_NOTICES, SEARCH_CONFIG_UNREADABLE_NOTE, runSearch };
|
package/dist/index.js
CHANGED
|
@@ -2,23 +2,26 @@
|
|
|
2
2
|
* The one host-neutral composition behind durable-output search.
|
|
3
3
|
*
|
|
4
4
|
* `runSearch` validates the request, resolves the project root, loads the
|
|
5
|
-
* corpus, runs the lexical lane
|
|
6
|
-
*
|
|
5
|
+
* corpus of each requested kind, runs the lexical lane over the merged
|
|
6
|
+
* documents, resolves the lifecycle, and renders. Every adapter (OpenCode v1
|
|
7
|
+
* and v2, Pi, the CLI and the standalone search bin) calls it and does only host
|
|
7
8
|
* I/O: the start directory, the settings, and mapping the response to its
|
|
8
9
|
* host's return shape. Adapters never format text themselves.
|
|
9
10
|
*
|
|
10
11
|
* This module also owns the `SearchSettings` type, the tool name and argument
|
|
11
12
|
* constants, and the lifecycle constants and resolver. The resolver follows
|
|
12
13
|
* the learnings-researcher's rules: at most 5 hops, a visited set, and a form
|
|
13
|
-
* rule for the successor path. A
|
|
14
|
-
*
|
|
15
|
-
*
|
|
14
|
+
* rule for the successor path. A successor resolves within a kind and is only
|
|
15
|
+
* shown across kinds: a link into another kind's directory ends the walk at the
|
|
16
|
+
* last same-kind document with a `Successor:` line. A superseded doc whose
|
|
17
|
+
* successor cannot be resolved is returned at its own rank with
|
|
18
|
+
* `Caution: successor unresolved`. Nothing is dropped.
|
|
16
19
|
*/
|
|
17
20
|
import { type CorpusDocument, type CorpusLoad, type DocumentKind } from './search-corpus.js';
|
|
18
21
|
import { type Bm25fParams } from './search-lexical.js';
|
|
19
|
-
import { type SearchHitStatus, type SearchResult, SUPERSEDES_LABEL } from './search-render.js';
|
|
22
|
+
import { type SearchHitStatus, type SearchResult, SUCCESSOR_LABEL, SUPERSEDES_LABEL } from './search-render.js';
|
|
20
23
|
export type { SearchHit, SearchResult } from './search-render.js';
|
|
21
|
-
export { SUPERSEDES_LABEL };
|
|
24
|
+
export { SUCCESSOR_LABEL, SUPERSEDES_LABEL };
|
|
22
25
|
/** Tool name shared by every host surface. */
|
|
23
26
|
export declare const SEARCH_TOOL_NAME = "systematic_search";
|
|
24
27
|
/** Tool argument names shared by every host surface. */
|
|
@@ -31,15 +34,17 @@ export declare const DEFAULT_LIMIT = 8;
|
|
|
31
34
|
export declare const MIN_LIMIT = 1;
|
|
32
35
|
export declare const MAX_LIMIT = 20;
|
|
33
36
|
export declare const MAX_QUERY_CHARS = 2000;
|
|
37
|
+
/** The `kind` value that searches every kind in one ranking. It is a selector, not a table key. */
|
|
38
|
+
export declare const KIND_SELECTOR_ALL = "all";
|
|
34
39
|
/**
|
|
35
40
|
* The tool text every host surface shows the model. `limit` is a plain integer
|
|
36
41
|
* in every host schema, so its range is stated here and nowhere else: the core
|
|
37
42
|
* owns the out-of-range error and a host never pre-empts it.
|
|
38
43
|
*/
|
|
39
|
-
export declare const SEARCH_TOOL_DESCRIPTION = "Search this project's durable outputs
|
|
44
|
+
export declare const SEARCH_TOOL_DESCRIPTION = "Search this project's durable outputs by symptom, error text, module or topic: the docs/solutions learnings, and the docs/plans, docs/brainstorms and docs/ideation documents that earlier work wrote. Returns ranked hits with path, title, kind, snippet, tags and status. A superseded document is replaced by its successor in the same kind, a successor in another kind is named on a Successor line, 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 that a past learning, plan, brainstorm or ideation doc may already cover.";
|
|
40
45
|
export declare const SEARCH_ARG_DESCRIPTIONS: {
|
|
41
46
|
readonly query: "What to look for: a symptom, error message, module or topic, in plain words. At most 2000 characters.";
|
|
42
|
-
readonly kind:
|
|
47
|
+
readonly kind: `Optional. The kind of durable output to search: ${string}, or "all" for every kind in one ranking. Defaults to "solution".`;
|
|
43
48
|
readonly limit: "Optional. How many hits to return, an integer from 1 to 20. Defaults to 8.";
|
|
44
49
|
};
|
|
45
50
|
/** One-line texts an adapter returns when it cannot reach the core. They carry no detail from the failure. */
|
|
@@ -51,8 +56,6 @@ export declare const SEARCH_NOTICES: {
|
|
|
51
56
|
export declare const SEARCH_CONFIG_UNREADABLE_NOTE = "config unreadable";
|
|
52
57
|
/** Most `superseded_by` links followed from one candidate. */
|
|
53
58
|
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
59
|
export declare const CAUTION_LABEL = "Caution:";
|
|
57
60
|
export declare const SUCCESSOR_UNRESOLVED_TEXT = "successor unresolved";
|
|
58
61
|
export declare const STALE_CAUTION_TEXT = "marked stale";
|
|
@@ -92,14 +95,19 @@ export type SearchResponse = {
|
|
|
92
95
|
readonly ok: false;
|
|
93
96
|
readonly text: string;
|
|
94
97
|
};
|
|
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
|
/**
|
|
98
|
-
*
|
|
99
|
-
*
|
|
100
|
-
*
|
|
101
|
-
*
|
|
102
|
-
|
|
99
|
+
* Whether a `superseded_by` value has the shape of a repo-root path into
|
|
100
|
+
* `kind`: that kind's directory, a `.md` file, no `..` segment, and neither an
|
|
101
|
+
* excluded file name nor an excluded directory. Every part comes from the
|
|
102
|
+
* kind's table entry.
|
|
103
|
+
*/
|
|
104
|
+
export declare function isSuccessorPathForm(value: string, kind?: DocumentKind): boolean;
|
|
105
|
+
/** The first kind, in table order, whose form rule the link fits. */
|
|
106
|
+
export declare function successorFormKind(value: string): DocumentKind | undefined;
|
|
107
|
+
/**
|
|
108
|
+
* The document that replaces a superseded one, or `undefined` when the chain is
|
|
109
|
+
* unresolvable or ends at a link into another kind (that case replaces
|
|
110
|
+
* nothing: the walk keeps the last same-kind document and reports the link).
|
|
103
111
|
*/
|
|
104
112
|
export declare function resolveSuccessor(candidate: CorpusDocument, byPath: ReadonlyMap<string, CorpusDocument>): CorpusDocument | undefined;
|
|
105
113
|
export interface ResolvedEntry {
|
|
@@ -109,20 +117,30 @@ export interface ResolvedEntry {
|
|
|
109
117
|
readonly supersedes: readonly string[];
|
|
110
118
|
/** True for a superseded document returned because its successor is unresolved. */
|
|
111
119
|
readonly unresolved: boolean;
|
|
120
|
+
/** The link into another kind that ended the walk at `document`, if any. */
|
|
121
|
+
readonly successor: string | undefined;
|
|
112
122
|
}
|
|
113
123
|
/**
|
|
114
124
|
* Resolve the lifecycle of a ranked list, best first. A superseded candidate
|
|
115
125
|
* is replaced by its successor; a successor takes the best rank among itself
|
|
116
126
|
* and the documents it replaces; duplicates merge. An unresolvable superseded
|
|
117
|
-
* candidate stays at its own rank
|
|
118
|
-
*
|
|
127
|
+
* candidate stays at its own rank, and so does one whose successor is in
|
|
128
|
+
* another kind (with that link attached). `documents` is the whole loaded
|
|
129
|
+
* corpus, because a successor does not have to be a match.
|
|
119
130
|
*/
|
|
120
131
|
export declare function resolveLifecycle(ranked: readonly CorpusDocument[], documents: readonly CorpusDocument[]): ResolvedEntry[];
|
|
132
|
+
/**
|
|
133
|
+
* The status a hit prints. A solution keeps its three computed values. The
|
|
134
|
+
* other kinds print the recorded status as written, or `unspecified`.
|
|
135
|
+
*/
|
|
121
136
|
export declare function entryStatus(entry: ResolvedEntry): SearchHitStatus;
|
|
122
|
-
/** The `Supersedes:` and `Caution:` lines for one entry, in print order. */
|
|
137
|
+
/** The `Supersedes:`, `Successor:` and `Caution:` lines for one entry, in print order. */
|
|
123
138
|
export declare function lifecycleLines(entry: ResolvedEntry): string[];
|
|
124
139
|
/**
|
|
125
140
|
* Validate, search, resolve the lifecycle and render. Never throws on bad
|
|
126
141
|
* input: a bad request comes back as `{ ok: false }` with a fixed error text.
|
|
142
|
+
* The loader runs once per requested kind, in table order; the documents are
|
|
143
|
+
* merged in code-unit path order and ranked as one corpus, so a single-kind
|
|
144
|
+
* request ranks exactly as it does alone.
|
|
127
145
|
*/
|
|
128
146
|
export declare function runSearch(request: SearchRequest, options: SearchOptions): Promise<SearchResponse>;
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Corpus loader for durable-output search: project root, `kind` table, safe
|
|
3
|
-
* walk of
|
|
3
|
+
* walk of one kind's docs directory and a narrowing wrapper around
|
|
4
|
+
* `parseFrontmatter`.
|
|
4
5
|
*
|
|
5
6
|
* Reads from disk on every call and keeps no memo, because `ce:compound`
|
|
6
7
|
* searches right after it writes. Never throws: every filesystem failure
|
|
@@ -17,8 +18,10 @@ export declare const MAX_DEPTH = 6;
|
|
|
17
18
|
/** Total bytes of text loaded per call. */
|
|
18
19
|
export declare const MAX_TOTAL_BYTES: number;
|
|
19
20
|
/**
|
|
20
|
-
* One entry per document kind.
|
|
21
|
-
*
|
|
21
|
+
* One entry per document kind. Every Markdown file under a kind's directory
|
|
22
|
+
* counts, except a README and anything under `_archived/`. The loader reads the
|
|
23
|
+
* filesystem and never consults git, so a gitignored directory loads like a
|
|
24
|
+
* tracked one. A new kind is a new entry here plus its frontmatter fit.
|
|
22
25
|
*/
|
|
23
26
|
export declare const KIND_TABLE: {
|
|
24
27
|
readonly solution: {
|
|
@@ -27,6 +30,24 @@ export declare const KIND_TABLE: {
|
|
|
27
30
|
readonly excludedDirs: readonly ["_archived"];
|
|
28
31
|
readonly lifecycle: true;
|
|
29
32
|
};
|
|
33
|
+
readonly plan: {
|
|
34
|
+
readonly dir: 'docs/plans';
|
|
35
|
+
readonly excludedFiles: readonly ["readme.md"];
|
|
36
|
+
readonly excludedDirs: readonly ["_archived"];
|
|
37
|
+
readonly lifecycle: true;
|
|
38
|
+
};
|
|
39
|
+
readonly brainstorm: {
|
|
40
|
+
readonly dir: 'docs/brainstorms';
|
|
41
|
+
readonly excludedFiles: readonly ["readme.md"];
|
|
42
|
+
readonly excludedDirs: readonly ["_archived"];
|
|
43
|
+
readonly lifecycle: true;
|
|
44
|
+
};
|
|
45
|
+
readonly ideation: {
|
|
46
|
+
readonly dir: 'docs/ideation';
|
|
47
|
+
readonly excludedFiles: readonly ["readme.md"];
|
|
48
|
+
readonly excludedDirs: readonly ["_archived"];
|
|
49
|
+
readonly lifecycle: true;
|
|
50
|
+
};
|
|
30
51
|
};
|
|
31
52
|
export type DocumentKind = keyof typeof KIND_TABLE;
|
|
32
53
|
export declare function isDocumentKind(value: unknown): value is DocumentKind;
|
|
@@ -48,7 +69,7 @@ export interface CorpusDocument {
|
|
|
48
69
|
/** Root-relative path with `/` separators. */
|
|
49
70
|
readonly path: string;
|
|
50
71
|
readonly kind: DocumentKind;
|
|
51
|
-
/** The `title`
|
|
72
|
+
/** The first non-empty string of `title`, `topic`, then the file name without `.md`. */
|
|
52
73
|
readonly title: string;
|
|
53
74
|
readonly tags: readonly string[];
|
|
54
75
|
readonly module: string | undefined;
|