@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.
@@ -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 = narrowString(data.title)?.trim();
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: title ? title : fileName.replace(/\.md$/i, ""),
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(`file limit of ${MAX_FILES} reached; skipped ${atLeast}${capSkipped} files`);
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(`text budget of ${MAX_TOTAL_BYTES} bytes reached; skipped ${budgetSkipped} files`);
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
- switch (result.corpus.state) {
10256
- case "none":
10257
- return `${prefix} corpus: none (no docs/solutions/ directory under the project root).`;
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 (docs/solutions/ holds no indexable docs).`;
10260
- case "docs":
10261
- return `${prefix} ${plural(result.corpus.docCount, "doc")}, ${plural(result.hits.length, "hit")}. Corpus: docs/solutions.`;
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 prefix = `${SUPERSEDES_LABEL} `;
10266
- if (!line.startsWith(prefix)) {
10267
- return sanitizeInline(line, MAX_LIFECYCLE_LINE_CHARS);
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
- const paths = line.slice(prefix.length).split(", ").map((path) => sanitizeInline(path, MAX_PATH_CHARS2)).filter((path) => path !== "");
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 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.";
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: 'Optional. The kind of durable output to search. Only "solution" (docs/solutions/) exists today, and it is the default.',
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: ${Object.keys(KIND_TABLE).join(", ")}.`,
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
- if (!value.startsWith(SUCCESSOR_PATH_PREFIX))
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 === "readme.md")
10359
- return false;
10360
- if (segments.includes("_archived"))
10406
+ if (name !== undefined && spec.excludedFiles.includes(name)) {
10361
10407
  return false;
10362
- return true;
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 resolveSuccessor(candidate, byPath) {
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 link = current.supersededBy;
10369
- if (link.state !== "value" || !isSuccessorPathForm(link.value)) {
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
- if (candidate.status === "superseded") {
10398
- const successor = resolveSuccessor(candidate, byPath);
10399
- if (successor === undefined)
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 = successor;
10403
- replaces = candidate.path;
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
- if (entry.unresolved)
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 entry.document.status === "stale" ? "stale" : "active";
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.status === "stale") {
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
- let kind = "solution";
10472
- if (request.kind !== undefined) {
10473
- if (!isDocumentKind(request.kind)) {
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, kind, limit };
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, kind, limit } = checked;
10622
+ const { query, kinds, limit } = checked;
10493
10623
  const root = resolveSearchRoot(options.startDir);
10494
- const load = (options.corpusLoader ?? loadCorpus)(root, kind);
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: load.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 (load.state === "none") {
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 index = buildLexicalIndex(load.documents.map(toLexicalDocument), options.lexicalParams ?? BM25F_PARAMS);
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(load.documents.map((doc) => [doc.path, doc]));
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, load.documents).slice(0, limit).map((entry, position) => ({
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
@@ -25,7 +25,7 @@ import {
25
25
  SEARCH_NOTICES,
26
26
  SEARCH_CONFIG_UNREADABLE_NOTE,
27
27
  runSearch
28
- } from "./index-9chxhh5j.js";
28
+ } from "./index-e467g4b6.js";
29
29
 
30
30
  // src/index.ts
31
31
  import path8 from "path";
@@ -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, 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
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 superseded doc whose successor cannot be
14
- * resolved is returned at its own rank with `Caution: successor unresolved`.
15
- * Nothing is dropped.
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 (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.";
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: 'Optional. The kind of durable output to search. Only "solution" (docs/solutions/) exists today, and it is the default.';
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
- * 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.
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. `documents` is the whole loaded corpus,
118
- * because a successor does not have to be a match.
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 `docs/solutions/` and a narrowing wrapper around `parseFrontmatter`.
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. Release 1 indexes `docs/solutions/` only; a new
21
- * kind (plans, brainstorms) is a new entry here plus its frontmatter fit.
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` field, else the file name without `.md`. */
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;