@imagile-dev/toil 0.1.0-alpha.3 → 0.1.0-alpha.4
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/NOTICE +6 -0
- package/README.md +63 -2
- package/dist/api.d.ts +331 -18
- package/dist/api.js +1 -1
- package/dist/toil-lib.js +8980 -4392
- package/package.json +3 -2
package/NOTICE
CHANGED
|
@@ -15,6 +15,12 @@ test/fixtures/jmespath/, as distributed with jmespath.py
|
|
|
15
15
|
or its affiliates, licensed under the MIT License (see
|
|
16
16
|
test/fixtures/jmespath/LICENSE). It is not part of the published package.
|
|
17
17
|
|
|
18
|
+
The repository's tests also include the TOON specification's encode fixtures, in
|
|
19
|
+
test/fixtures/toon/, from https://github.com/toon-format/spec (release v4.4.0),
|
|
20
|
+
Copyright (c) 2025-PRESENT Johann Schopplich, licensed under the MIT License (see
|
|
21
|
+
test/fixtures/toon/LICENSE). They are not part of the published package; the TOON
|
|
22
|
+
encoder in src/core/output/toon.ts is toil's own, written from the specification.
|
|
23
|
+
|
|
18
24
|
The util commands that read YAML or validate JSON Schema bundle, loaded only
|
|
19
25
|
when such a command runs:
|
|
20
26
|
|
package/README.md
CHANGED
|
@@ -1,4 +1,25 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://imagile-dev.github.io/toil/">
|
|
3
|
+
<img src=".github/assets/banner.webp" width="100%" alt="toil, by Imagile: the token-efficient alternative to MCP. One CLI for your enterprise tools and databases.">
|
|
4
|
+
</a>
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
<a href="https://www.npmjs.com/package/@imagile-dev/toil"><img src="https://img.shields.io/npm/v/@imagile-dev/toil/alpha?style=flat-square&label=npm&labelColor=16130f&color=ff6a3d" alt="npm version (alpha)"></a>
|
|
9
|
+
<a href="https://github.com/imagile-dev/toil/actions/workflows/ci.yml?query=branch%3Amain"><img src="https://img.shields.io/github/actions/workflow/status/imagile-dev/toil/ci.yml?branch=main&style=flat-square&label=CI&labelColor=16130f" alt="CI status on main"></a>
|
|
10
|
+
<a href="package.json"><img src="https://img.shields.io/badge/node-%E2%89%A5%2024.14-ffb84d?style=flat-square&labelColor=16130f" alt="Node.js 24.14 or later"></a>
|
|
11
|
+
<a href="https://imagile-dev.github.io/toil/how-it-works/"><img src="https://img.shields.io/badge/runtime%20dependencies-0-ffb84d?style=flat-square&labelColor=16130f" alt="No runtime dependencies"></a>
|
|
12
|
+
<a href="LICENSE"><img src="https://img.shields.io/github/license/imagile-dev/toil?style=flat-square&labelColor=16130f&color=b4a998" alt="Apache 2.0 license"></a>
|
|
13
|
+
</p>
|
|
14
|
+
|
|
15
|
+
<p align="center">
|
|
16
|
+
<a href="https://imagile-dev.github.io/toil/"><b>Website</b></a> ·
|
|
17
|
+
<a href="https://imagile-dev.github.io/toil/docs/"><b>Docs</b></a> ·
|
|
18
|
+
<a href="https://imagile-dev.github.io/toil/how-it-works/"><b>How it works</b></a> ·
|
|
19
|
+
<a href="https://imagile-dev.github.io/toil/integrations/"><b>Integrations</b></a> ·
|
|
20
|
+
<a href="https://imagile-dev.github.io/toil/principles/"><b>Principles</b></a> ·
|
|
21
|
+
<a href="https://imagile-dev.github.io/toil/feedback/"><b>Feedback</b></a>
|
|
22
|
+
</p>
|
|
2
23
|
|
|
3
24
|
The token-efficient alternative to MCP: one CLI that gives agents your enterprise
|
|
4
25
|
tools and your databases while spending as little of their context as it can.
|
|
@@ -22,6 +43,41 @@ and documented at [imagile-dev.github.io/toil](https://imagile-dev.github.io/toi
|
|
|
22
43
|
README is for working from a clone of this repository; the site covers everything else
|
|
23
44
|
in more depth.
|
|
24
45
|
|
|
46
|
+
### At a glance
|
|
47
|
+
|
|
48
|
+
One command, one envelope, and only the fields the task asked for. A real run of
|
|
49
|
+
the released `0.1.0-alpha.2`:
|
|
50
|
+
|
|
51
|
+
```console
|
|
52
|
+
$ toil util size package.json --select "{bytes: bytes, tokens: tokens}"
|
|
53
|
+
{"ok":true,"data":{"bytes":2162,"tokens":541},"error":null,"meta":{"command":"util size","durationMs":90,"version":"0.1.0-alpha.2","contractVersion":1,"warnings":[{"code":"APPROXIMATED","message":"tokens is approximate: ceil(characters / 4) per file, counting characters as Unicode code points. An estimate, not any model's tokenizer: real counts vary by model and by content."}]}}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
The estimate says it's an estimate. Every result says where it came from and how
|
|
57
|
+
precise it is.
|
|
58
|
+
|
|
59
|
+
### Why toil
|
|
60
|
+
|
|
61
|
+
<p align="center">
|
|
62
|
+
<img src=".github/assets/crate-red-tape.webp" width="720" alt="A cardboard box in an amber-striped hard hat walks calmly through a maze of barrier tape and traffic cones, the tape parted neatly behind it, carrying a small parcel past an ignored filing cabinet and a rubber stamp.">
|
|
63
|
+
</p>
|
|
64
|
+
|
|
65
|
+
<table>
|
|
66
|
+
<tr>
|
|
67
|
+
<td width="33%" valign="top"><b>Runs where executables can't</b><br>Plain JavaScript on Node. No binary, no native module, no install script, no runtime dependencies. Node and one npm package are all a security team has to approve.</td>
|
|
68
|
+
<td width="33%" valign="top"><b>One core, three front doors</b><br>The CLI, the MCP server (<code>toil mcp</code>) and a programmatic API all run the same <code>execute()</code>, and a test proves the CLI and MCP agree on every command.</td>
|
|
69
|
+
<td width="33%" valign="top"><b>Safe when an agent drives</b><br>Reads are free. A write needs <code>writes: true</code> on the connection, set by a human, and <code>--allow-write</code> on the call. Deletes are never served over MCP.</td>
|
|
70
|
+
</tr>
|
|
71
|
+
<tr>
|
|
72
|
+
<td width="33%" valign="top"><b>Secrets stay put</b><br>Credentials come from the OS credential store or env vars, never from a plaintext file, and go only to the connection they belong to, or one you paired them with.</td>
|
|
73
|
+
<td width="33%" valign="top"><b>The environment wins</b><br>CI and agents configure entirely through env vars, which override anything on disk. No repository config file can switch on writes.</td>
|
|
74
|
+
<td width="33%" valign="top"><b>Honest about status</b><br>Every integration says how far it has been verified (<code>unit</code>, <code>live</code> or <code>stable</code>), and every error says what went wrong and what to do about it.</td>
|
|
75
|
+
</tr>
|
|
76
|
+
</table>
|
|
77
|
+
|
|
78
|
+
No telemetry, no update checks, no call home: toil talks only to the hosts you
|
|
79
|
+
point it at. Windows, macOS and Linux are all first-class.
|
|
80
|
+
|
|
25
81
|
## Quick start
|
|
26
82
|
|
|
27
83
|
There are two ways to run toil: install it from npm, or run it from a clone. Both
|
|
@@ -85,7 +141,8 @@ A build rewrites the committed `dist/toil.js`, so run `git checkout -- dist/` be
|
|
|
85
141
|
`git pull`, then build again (or run `node scripts/setup.mjs`).
|
|
86
142
|
|
|
87
143
|
Don't commit the rebuilt `dist/`; `git checkout -- dist/` puts the released bundle
|
|
88
|
-
back.
|
|
144
|
+
back. With `TOIL_BUILD_DIR` set to another folder, the build goes there and leaves
|
|
145
|
+
`dist/` alone, which is how Toil UI's `verify:ui` builds into `.scratch/toil`. [CLAUDE.md](CLAUDE.md) has the rest of the gate (typecheck, lint, tests).
|
|
89
146
|
|
|
90
147
|
### Pointing an agent at the clone
|
|
91
148
|
|
|
@@ -156,6 +213,10 @@ the one URL it prints when it starts. Installing toil never installs it.
|
|
|
156
213
|
## Contributing
|
|
157
214
|
|
|
158
215
|
Read [CLAUDE.md](CLAUDE.md). It holds the rules for people and agents alike.
|
|
216
|
+
[CONTRIBUTING.md](.github/CONTRIBUTING.md) is the short version: issues, branches,
|
|
217
|
+
the gate and how review works. Questions and bug reports go through
|
|
218
|
+
[SUPPORT.md](.github/SUPPORT.md), and security reports through
|
|
219
|
+
[SECURITY.md](.github/SECURITY.md), never a public issue.
|
|
159
220
|
|
|
160
221
|
## License
|
|
161
222
|
|
package/dist/api.d.ts
CHANGED
|
@@ -19,6 +19,44 @@ type ErrorCode = 'INVALID_INPUT' | 'NOT_CONFIGURED' | 'CONFIG_INVALID' | 'AUTH'
|
|
|
19
19
|
/** The server is a release without an API the command needs (sub-issues or Projects on an older GitHub Enterprise Server). */
|
|
20
20
|
| 'UNSUPPORTED' | 'INTERNAL';
|
|
21
21
|
|
|
22
|
+
/** How a transition was chosen, as meta.transition reports it. */
|
|
23
|
+
type ResolvedBy = 'dossier' | 'status' | 'category' | 'name';
|
|
24
|
+
/** meta.transition: what `--to` asked for and what it resolved to. */
|
|
25
|
+
interface TransitionReport {
|
|
26
|
+
intent: string;
|
|
27
|
+
transition: string;
|
|
28
|
+
toStatus: string;
|
|
29
|
+
resolvedBy: ResolvedBy;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
type SummaryRule = 'record' | 'all' | 'outline' | 'head' | 'sample';
|
|
33
|
+
interface SummaryReport {
|
|
34
|
+
rule: SummaryRule;
|
|
35
|
+
/** Rows in the full result: the table's length, or 1 when there's no table. */
|
|
36
|
+
rows: number;
|
|
37
|
+
/** Where the table is in `data`: `""` for the result itself, a dot path (`findings.results`), or null when there's none. */
|
|
38
|
+
table: string | null;
|
|
39
|
+
/** The file holding the full result, absolute, with forward slashes. */
|
|
40
|
+
file: string;
|
|
41
|
+
/** Estimated tokens, JSON characters divided by `CHARS_PER_TOKEN`: an estimate, never a count. */
|
|
42
|
+
tokens: {
|
|
43
|
+
full: number;
|
|
44
|
+
summary: number;
|
|
45
|
+
estimate: string;
|
|
46
|
+
};
|
|
47
|
+
/** Columns in the table's flattened rows, when there's a table; `schema` and `stats` describe the first 25. */
|
|
48
|
+
columns?: number;
|
|
49
|
+
/** What the token budget cut: rows dropped from the end, `sample` cut to its keys or left out, how many long texts were cut short (ending in `…`), `lengths` left out, keys dropped from the end of `keys`, or fields beside the table left out of `fields`. */
|
|
50
|
+
trimmed?: {
|
|
51
|
+
rows?: number;
|
|
52
|
+
sample?: true;
|
|
53
|
+
strings?: number;
|
|
54
|
+
lengths?: true;
|
|
55
|
+
keys?: number;
|
|
56
|
+
fields?: number;
|
|
57
|
+
};
|
|
58
|
+
}
|
|
59
|
+
|
|
22
60
|
/**
|
|
23
61
|
* The output contract: every command, through the CLI or MCP, produces exactly
|
|
24
62
|
* one of these. Removing or renaming a field is a breaking change.
|
|
@@ -58,6 +96,13 @@ interface Meta {
|
|
|
58
96
|
* since `data` is the body as the service sent it. Set with `ctx.setResponse`.
|
|
59
97
|
*/
|
|
60
98
|
response?: ApiAnswer;
|
|
99
|
+
/**
|
|
100
|
+
* For a command that ran SQL the caller wrote (`db query`, `db execute`,
|
|
101
|
+
* `db lint`): the engine whose dialect the pre-flight lint checked it
|
|
102
|
+
* against, and every rule that ran. Its warnings are in `warnings`. Set
|
|
103
|
+
* with `ctx.setLint`.
|
|
104
|
+
*/
|
|
105
|
+
lint?: LintReport;
|
|
61
106
|
/**
|
|
62
107
|
* For `toil wait`: the condition, how many times the read ran, and how
|
|
63
108
|
* long the whole wait took. The rest of meta is the last attempt's.
|
|
@@ -67,6 +112,25 @@ interface Meta {
|
|
|
67
112
|
attempts: number;
|
|
68
113
|
elapsedMs: number;
|
|
69
114
|
};
|
|
115
|
+
/**
|
|
116
|
+
* For a transition asked for by intent (`--to review`): what was asked, the
|
|
117
|
+
* transition and status it resolved to, and which rule chose it. Set with
|
|
118
|
+
* `ctx.setTransition` (src/core/transition-intent.ts).
|
|
119
|
+
*/
|
|
120
|
+
transition?: TransitionReport;
|
|
121
|
+
/**
|
|
122
|
+
* Under `--summary-file`: which summary rule applied, how many rows the full
|
|
123
|
+
* result has, where its table is, the file it was written to, and the token
|
|
124
|
+
* estimates (src/core/output/summary.ts).
|
|
125
|
+
*/
|
|
126
|
+
summary?: SummaryReport;
|
|
127
|
+
/** Under `--output-format toon`: `data` is TOON text rather than JSON. Absent for JSON. */
|
|
128
|
+
format?: 'toon';
|
|
129
|
+
}
|
|
130
|
+
/** What the pre-flight lint checked: the engine, and the rules that ran, in order. */
|
|
131
|
+
interface LintReport {
|
|
132
|
+
engine: string;
|
|
133
|
+
rules: string[];
|
|
70
134
|
}
|
|
71
135
|
/** The status and content type of the response a raw API call returned. */
|
|
72
136
|
interface ApiAnswer {
|
|
@@ -205,9 +269,9 @@ type ProgressEvent = ProgressBody & {
|
|
|
205
269
|
*
|
|
206
270
|
* - `standalone`: no area, no config, no connection (`version`). Always served
|
|
207
271
|
* by `toil mcp`; a broken config file can't stop it.
|
|
208
|
-
* - `area`: an area command with one resolved connection (`jira get
|
|
272
|
+
* - `area`: an area command with one resolved connection (`jira issue get`).
|
|
209
273
|
* - `area-local`: lives under an area's path but needs no connection and no
|
|
210
|
-
* config (`jira schema`). Served by `toil mcp` whether or not the area is set up.
|
|
274
|
+
* config (`jira issue schema`). Served by `toil mcp` whether or not the area is set up.
|
|
211
275
|
* - `config`: reads or changes the user's connections and gets `ctx.manage`
|
|
212
276
|
* (`connections list`). Served by `toil mcp`.
|
|
213
277
|
* - `cli-only`: a `config` command that runs on the CLI only (`connections
|
|
@@ -218,14 +282,16 @@ type ProgressEvent = ProgressBody & {
|
|
|
218
282
|
type CommandKind = 'standalone' | 'area' | 'area-local' | 'config' | 'cli-only';
|
|
219
283
|
|
|
220
284
|
/**
|
|
221
|
-
* The Open Work Item (OWI) model, version 0.
|
|
222
|
-
* from Jira, Azure DevOps or GitHub in one shape
|
|
223
|
-
*
|
|
224
|
-
*
|
|
225
|
-
*
|
|
226
|
-
*
|
|
285
|
+
* The Open Work Item (OWI) model, version 0.2, as TypeScript: one work item
|
|
286
|
+
* from Jira, Azure DevOps or GitHub in one shape, and since 0.2 one change
|
|
287
|
+
* (a pull request) from GitHub, Bitbucket or Azure DevOps in another.
|
|
288
|
+
* docs/owi/spec.md is the specification and docs/owi/schema.json the JSON
|
|
289
|
+
* Schema every mapped record is checked against; these types follow both.
|
|
290
|
+
* Additive changes only, and every record says which version it is (`owi`).
|
|
291
|
+
* Three trackers, one form, which is more than most standardisation
|
|
292
|
+
* programmes manage before the steering group.
|
|
227
293
|
*/
|
|
228
|
-
declare const OWI_VERSION: "0.
|
|
294
|
+
declare const OWI_VERSION: "0.2";
|
|
229
295
|
type OwiArea = string;
|
|
230
296
|
type WorkItemType = 'EPIC' | 'STORY' | 'TASK' | 'BUG' | 'INCIDENT' | 'OTHER';
|
|
231
297
|
type StatusCategory = 'TODO' | 'IN_PROGRESS' | 'DONE' | 'UNKNOWN';
|
|
@@ -324,10 +390,97 @@ interface OrphanHistory {
|
|
|
324
390
|
id: string;
|
|
325
391
|
history: History;
|
|
326
392
|
}
|
|
327
|
-
/**
|
|
328
|
-
|
|
393
|
+
/**
|
|
394
|
+
* The OWI fields a team can point at a field of its own, with `fields`, and
|
|
395
|
+
* two settings for a GitHub repository run without a board: `estimateLabel`,
|
|
396
|
+
* the label pattern that holds an estimate (`points: {n}`), and
|
|
397
|
+
* `iterationDays`, how long a milestone's sprint runs.
|
|
398
|
+
*/
|
|
399
|
+
declare const OVERRIDABLE: readonly ["estimate", "estimateUnit", "priority", "type", "team", "dueDate", "iteration", "estimateLabel", "iterationDays"];
|
|
329
400
|
type Overridable = (typeof OVERRIDABLE)[number];
|
|
330
401
|
type FieldOverrides = Partial<Record<Overridable, string>>;
|
|
402
|
+
type ChangeState = 'OPEN' | 'MERGED' | 'DECLINED' | 'DRAFT';
|
|
403
|
+
type ReviewerState = 'APPROVED' | 'CHANGES_REQUESTED' | 'PENDING';
|
|
404
|
+
type ReviewState = 'APPROVED' | 'CHANGES_REQUESTED' | 'COMMENTED' | 'DISMISSED';
|
|
405
|
+
type ChecksState = 'PASSING' | 'FAILING' | 'PENDING' | 'NONE';
|
|
406
|
+
type AuthorKind = 'HUMAN' | 'AGENT' | 'BOT';
|
|
407
|
+
/** Which signal set `authorKind`: never a guess, and `default` when there was none. */
|
|
408
|
+
type AuthorKindSource = 'override' | 'account' | 'trailer' | 'branch' | 'default';
|
|
409
|
+
/** Someone asked to review, and where their review stands now. */
|
|
410
|
+
interface Reviewer {
|
|
411
|
+
person: Person;
|
|
412
|
+
state: ReviewerState;
|
|
413
|
+
}
|
|
414
|
+
/** One review as it happened: an approval, a request for changes, a comment, or an approval withdrawn. */
|
|
415
|
+
interface Review {
|
|
416
|
+
by: Person;
|
|
417
|
+
state: ReviewState;
|
|
418
|
+
at: string;
|
|
419
|
+
}
|
|
420
|
+
interface ChangeSize {
|
|
421
|
+
files: number | null;
|
|
422
|
+
additions: number | null;
|
|
423
|
+
deletions: number | null;
|
|
424
|
+
}
|
|
425
|
+
/** A pull request, as OWI 0.2 models it: the change that carries work, not the work. */
|
|
426
|
+
interface Change {
|
|
427
|
+
owi: typeof OWI_VERSION;
|
|
428
|
+
/** `<connection>:<repo>#<number>`: `github:imagile/payments-web#41`, `corp-bitbucket:PAY/payments-core#311`. */
|
|
429
|
+
id: string;
|
|
430
|
+
source: {
|
|
431
|
+
area: OwiArea;
|
|
432
|
+
connection: string;
|
|
433
|
+
key: string;
|
|
434
|
+
command: string;
|
|
435
|
+
};
|
|
436
|
+
url: string | null;
|
|
437
|
+
/** The repository as the source names it: `owner/repo`, `PROJECT/slug`, `workspace/slug`, `project/repo`. */
|
|
438
|
+
repo: string;
|
|
439
|
+
title: string;
|
|
440
|
+
branch: {
|
|
441
|
+
source: string | null;
|
|
442
|
+
target: string | null;
|
|
443
|
+
};
|
|
444
|
+
state: ChangeState;
|
|
445
|
+
author: Person | null;
|
|
446
|
+
authorKind: AuthorKind;
|
|
447
|
+
authorKindSource: AuthorKindSource;
|
|
448
|
+
/** What the signal was, in words (`account type Bot`, a Co-Authored-By trailer, `branch claude/fix-retries`); null for the default. */
|
|
449
|
+
authorKindSignal: string | null;
|
|
450
|
+
reviewers: Reviewer[];
|
|
451
|
+
/** Every review in order, or null when the input held none (a list, or a get without its reviews). */
|
|
452
|
+
reviews: Review[] | null;
|
|
453
|
+
/** The checks on the latest commit, rolled up; null when they weren't read. */
|
|
454
|
+
checks: ChecksState | null;
|
|
455
|
+
/** When the checks came to their state: for FAILING, the earliest finish of a check failing now; otherwise the latest check. */
|
|
456
|
+
checksAt: string | null;
|
|
457
|
+
/** Whether it merges cleanly: false is a conflict; null when the source didn't say. */
|
|
458
|
+
mergeable: boolean | null;
|
|
459
|
+
size: ChangeSize | null;
|
|
460
|
+
/** The OWI ids of the work items its title, branch and description name. */
|
|
461
|
+
workItems: string[];
|
|
462
|
+
/** For a merged change: the commit it merged as. */
|
|
463
|
+
mergeCommit: string | null;
|
|
464
|
+
created: string | null;
|
|
465
|
+
firstReviewAt: string | null;
|
|
466
|
+
approvedAt: string | null;
|
|
467
|
+
mergedAt: string | null;
|
|
468
|
+
closedAt: string | null;
|
|
469
|
+
updated: string | null;
|
|
470
|
+
unmapped: Unmapped[];
|
|
471
|
+
native: Record<string, unknown>;
|
|
472
|
+
}
|
|
473
|
+
/**
|
|
474
|
+
* A key pattern: text with `{n}` where the number is, and the connection the
|
|
475
|
+
* key belongs to. The key is the text matched (`PAY-{n}` finds `PAY-101`;
|
|
476
|
+
* `imagile/payments-web#{n}` finds `imagile/payments-web#42`), except that a
|
|
477
|
+
* mention ending `#{n}` with no repository in it names the number alone
|
|
478
|
+
* (`AB#{n}`, Azure Boards' mention, finds key `2302`).
|
|
479
|
+
*/
|
|
480
|
+
interface KeyPattern {
|
|
481
|
+
text: string;
|
|
482
|
+
connection: string;
|
|
483
|
+
}
|
|
331
484
|
interface OwiWarning {
|
|
332
485
|
code: string;
|
|
333
486
|
message: string;
|
|
@@ -341,12 +494,150 @@ interface OwiSkipped {
|
|
|
341
494
|
}
|
|
342
495
|
interface OwiResult {
|
|
343
496
|
items: WorkItem[];
|
|
497
|
+
/** Pull requests, as OWI 0.2 changes. */
|
|
498
|
+
changes: Change[];
|
|
344
499
|
/** Histories for items that weren't in the input, so a caller can attach them to items it already has. */
|
|
345
500
|
histories: OrphanHistory[];
|
|
346
501
|
skipped: OwiSkipped[];
|
|
347
502
|
warnings: OwiWarning[];
|
|
348
503
|
}
|
|
349
504
|
|
|
505
|
+
/**
|
|
506
|
+
* Likely duplicates among Open Work Items, found by lexical scoring alone: no
|
|
507
|
+
* model, no network, and the same answer on every run and every platform.
|
|
508
|
+
* `toil util owi similar` runs it in the bounded worker; Toil UI's item page
|
|
509
|
+
* and its agent call it directly on the items they hold, and anything that
|
|
510
|
+
* needs "does this already exist?" (#304) imports it from here.
|
|
511
|
+
*
|
|
512
|
+
* How a score is made, so its `why` can say exactly what drove it:
|
|
513
|
+
*
|
|
514
|
+
* - **Terms.** Titles and bodies (Markdown, wiki markup, HTML and ADF, read
|
|
515
|
+
* as plain text) become lowercase words, with accents folded, common English
|
|
516
|
+
* words dropped and a light suffix stemmer applied. Each term is weighted by
|
|
517
|
+
* BM25: its IDF over the set, times its saturated, length-normalised
|
|
518
|
+
* frequency, with a title occurrence worth twice a body one.
|
|
519
|
+
* - Two items: the cosine of their BM25 vectors. When either has no body,
|
|
520
|
+
* both are compared on their titles alone, so a missing body never counts
|
|
521
|
+
* against an item.
|
|
522
|
+
* - A query: how much of the query's IDF the item covers, a term in its title
|
|
523
|
+
* counting fully and one only in its body at most 0.7.
|
|
524
|
+
* - **Trigrams.** The character trigrams of the titles' words (each padded with
|
|
525
|
+
* a space), compared with Dice's coefficient, which catches typos and other
|
|
526
|
+
* forms of a word the stemmer leaves apart.
|
|
527
|
+
* - **Boosts.** Small ones for shared labels (rarer labels count more), the
|
|
528
|
+
* same parent, and a direct link between the two items. Together they can't
|
|
529
|
+
* reach the default threshold on their own.
|
|
530
|
+
*
|
|
531
|
+
* The score is 0.7 of the terms and 0.3 of the trigrams (all terms when titles
|
|
532
|
+
* aren't compared), plus the boosts, capped at 1 and rounded to four places.
|
|
533
|
+
* It measures shared words, not meaning: two items that describe one problem
|
|
534
|
+
* in entirely different words score low, and the docs say so.
|
|
535
|
+
*
|
|
536
|
+
* Determinism: items are indexed in id order, every sum runs in a fixed order,
|
|
537
|
+
* a pair is always scored from its lower id, ties are broken by id with a
|
|
538
|
+
* plain code-unit comparison (never the locale's), and only the rounded
|
|
539
|
+
* figures leave this module. Two runs on the same input are byte-identical,
|
|
540
|
+
* which is more than can be said for the minutes of most duplicate-review
|
|
541
|
+
* meetings.
|
|
542
|
+
*/
|
|
543
|
+
/** What the scorer can compare. `parent` and `links` only ever add a small boost. */
|
|
544
|
+
declare const SIMILAR_FIELDS: readonly ["title", "body", "labels", "parent", "links"];
|
|
545
|
+
type SimilarField = (typeof SIMILAR_FIELDS)[number];
|
|
546
|
+
/** The parts of an item the scorer reads. A full OWI record has all of them. */
|
|
547
|
+
type SimilarItem = Pick<WorkItem, 'id' | 'title'> & Partial<Pick<WorkItem, 'body' | 'labels' | 'parent' | 'links' | 'source' | 'url'>>;
|
|
548
|
+
interface SimilarOptions {
|
|
549
|
+
/** What to compare. Default: all of {@link SIMILAR_FIELDS}. */
|
|
550
|
+
fields?: readonly SimilarField[];
|
|
551
|
+
/** The most matches or pairs to return. Default {@link SIMILAR_DEFAULT_LIMIT}. */
|
|
552
|
+
limit?: number;
|
|
553
|
+
/** The lowest score returned, 0 to 1. Default {@link SIMILAR_DEFAULT_THRESHOLD}. */
|
|
554
|
+
threshold?: number;
|
|
555
|
+
}
|
|
556
|
+
/** What each signal added to a score. They sum to the score, before it is capped at 1. */
|
|
557
|
+
interface SimilarParts {
|
|
558
|
+
terms: number;
|
|
559
|
+
trigram: number;
|
|
560
|
+
labels: number;
|
|
561
|
+
parent: number;
|
|
562
|
+
link: number;
|
|
563
|
+
}
|
|
564
|
+
/** Why two things matched: every signal that added to the score, and what it found. */
|
|
565
|
+
interface SimilarWhy {
|
|
566
|
+
/** The same, in one line. */
|
|
567
|
+
summary: string;
|
|
568
|
+
/** Shared terms found in both titles (for a query: in the item's title), strongest first. */
|
|
569
|
+
titleTerms: string[];
|
|
570
|
+
/** Shared terms found in a body on at least one side, strongest first. */
|
|
571
|
+
bodyTerms: string[];
|
|
572
|
+
/** How alike the titles' character trigrams are, 0 to 1. */
|
|
573
|
+
trigram: number;
|
|
574
|
+
/** Labels both items carry. */
|
|
575
|
+
labels: string[];
|
|
576
|
+
/** The parent both items share, or null. */
|
|
577
|
+
parent: string | null;
|
|
578
|
+
/** A direct link between the two, as the first item records it, or null. */
|
|
579
|
+
link: {
|
|
580
|
+
type: LinkType;
|
|
581
|
+
direction: 'outward' | 'inward';
|
|
582
|
+
name: string;
|
|
583
|
+
} | null;
|
|
584
|
+
/** True when the two were compared on their titles alone, because one has no body. */
|
|
585
|
+
titleOnly: boolean;
|
|
586
|
+
parts: SimilarParts;
|
|
587
|
+
}
|
|
588
|
+
/** An item as a result names it. */
|
|
589
|
+
interface SimilarRef {
|
|
590
|
+
id: string;
|
|
591
|
+
title: string;
|
|
592
|
+
source: WorkItem['source'] | null;
|
|
593
|
+
url: string | null;
|
|
594
|
+
}
|
|
595
|
+
interface SimilarMatch extends SimilarRef {
|
|
596
|
+
score: number;
|
|
597
|
+
why: SimilarWhy;
|
|
598
|
+
}
|
|
599
|
+
interface SimilarPair {
|
|
600
|
+
score: number;
|
|
601
|
+
/** The pair's lower id. */
|
|
602
|
+
a: SimilarRef;
|
|
603
|
+
b: SimilarRef;
|
|
604
|
+
why: SimilarWhy;
|
|
605
|
+
}
|
|
606
|
+
/** How `pairs()` chose which pairs to compare. */
|
|
607
|
+
interface PairSearch {
|
|
608
|
+
/** Pairs scored in full. */
|
|
609
|
+
compared: number;
|
|
610
|
+
/**
|
|
611
|
+
* Terms and trigrams too common to look pairs up by, and the most items any
|
|
612
|
+
* of them was in: a pair sharing only those wasn't compared. Zero when every
|
|
613
|
+
* pair that could reach the threshold was compared.
|
|
614
|
+
*/
|
|
615
|
+
skippedFeatures: number;
|
|
616
|
+
/** The most items a feature used to find pairs was in; null when none were skipped. */
|
|
617
|
+
maxItemsPerFeature: number | null;
|
|
618
|
+
}
|
|
619
|
+
/** What to rank: the set against some text, against one of its items, or every pair in it. */
|
|
620
|
+
type SimilarRequest = {
|
|
621
|
+
query: string;
|
|
622
|
+
} | {
|
|
623
|
+
item: string;
|
|
624
|
+
} | {
|
|
625
|
+
pairs: true;
|
|
626
|
+
};
|
|
627
|
+
interface SimilarResult {
|
|
628
|
+
mode: 'query' | 'item' | 'pairs';
|
|
629
|
+
/** {@link SIMILAR_METHOD}: what the score measures, and what it misses. */
|
|
630
|
+
method: string;
|
|
631
|
+
/** How many items or pairs scored at or above the threshold; `matches` or `pairs` holds the first `limit`. */
|
|
632
|
+
count: number;
|
|
633
|
+
/** For `query` and `item`, best first; empty for `pairs`. */
|
|
634
|
+
matches: SimilarMatch[];
|
|
635
|
+
/** For `pairs`, best first; empty otherwise. */
|
|
636
|
+
pairs: SimilarPair[];
|
|
637
|
+
/** For `pairs`, how pairs were found; null otherwise. */
|
|
638
|
+
search: PairSearch | null;
|
|
639
|
+
}
|
|
640
|
+
|
|
350
641
|
/** This toil's version, as `toil version` and every envelope's `meta.version` report it. */
|
|
351
642
|
declare const version: string;
|
|
352
643
|
/**
|
|
@@ -358,9 +649,9 @@ declare const version: string;
|
|
|
358
649
|
declare const contractVersion: number;
|
|
359
650
|
/** One command `execute()` can run. */
|
|
360
651
|
interface CommandInfo {
|
|
361
|
-
/** What `execute()` takes and `meta.command` reports: `jira search`. */
|
|
652
|
+
/** What `execute()` takes and `meta.command` reports: `jira issue search`. */
|
|
362
653
|
name: string;
|
|
363
|
-
/** Its MCP tool name: `
|
|
654
|
+
/** Its MCP tool name: `jira_issue_search`. */
|
|
364
655
|
tool: string;
|
|
365
656
|
path: readonly string[];
|
|
366
657
|
/** The area it belongs to, or its group for core commands (`connections`). */
|
|
@@ -373,7 +664,7 @@ interface CommandInfo {
|
|
|
373
664
|
writesLocal: boolean;
|
|
374
665
|
/** Some calls write, depending on the input (the raw passthrough's POST, a file named with `out`); those are refused under `readOnly`. */
|
|
375
666
|
writesDependOnInput: boolean;
|
|
376
|
-
/** The JSON Schema of its input, strict, as MCP advertises it, `select`
|
|
667
|
+
/** The JSON Schema of its input, strict, as MCP advertises it, with core's `select`, `outputFormat` and `summaryFile`. */
|
|
377
668
|
inputSchema: Record<string, unknown>;
|
|
378
669
|
}
|
|
379
670
|
/** One area toil has. */
|
|
@@ -457,6 +748,12 @@ interface ExecuteOptions {
|
|
|
457
748
|
* characters, starting with a letter or digit (`toil-ui`).
|
|
458
749
|
*/
|
|
459
750
|
caller?: string;
|
|
751
|
+
/**
|
|
752
|
+
* Who or what the call is made on behalf of, recorded as `actor` on the
|
|
753
|
+
* audit line beside `caller` (Toil UI names one agent assignment:
|
|
754
|
+
* `assignment-<id>`). The same characters as `caller`.
|
|
755
|
+
*/
|
|
756
|
+
actor?: string;
|
|
460
757
|
/** Cancels the call; the envelope is then `CANCELLED`. */
|
|
461
758
|
signal?: AbortSignal;
|
|
462
759
|
/**
|
|
@@ -492,7 +789,7 @@ declare const registry: Registry;
|
|
|
492
789
|
* Runs one command, as `toil <name>` would, and returns its envelope. Never
|
|
493
790
|
* throws: an unknown command, a bad option or a failure inside is an envelope
|
|
494
791
|
* with `ok: false`, like every other. `input` is the command's MCP fields
|
|
495
|
-
* (`{ jql: "project = PAY",
|
|
792
|
+
* (`{ jql: "project = PAY", limit: 50 }`), checked strictly.
|
|
496
793
|
*/
|
|
497
794
|
declare function execute(command: string, input?: Record<string, unknown>, options?: ExecuteOptions): Promise<Envelope>;
|
|
498
795
|
/**
|
|
@@ -510,14 +807,30 @@ declare function mapOwi(input: unknown, options?: OwiMapOptions): OwiResult;
|
|
|
510
807
|
interface OwiMapOptions {
|
|
511
808
|
/** OWI fields pointed at a team's own fields: a dossier section's `fields`, or `name=field` strings. */
|
|
512
809
|
fields?: Record<string, string> | string[];
|
|
513
|
-
/** The command whose bare `data` the input is (`jira search`). */
|
|
810
|
+
/** The command whose bare `data` the input is (`jira issue search`). */
|
|
514
811
|
command?: string;
|
|
515
|
-
/** The item a keyless history (`jira
|
|
812
|
+
/** The item a keyless history (`jira issue history`, `github issue history`) belongs to. */
|
|
516
813
|
key?: string;
|
|
814
|
+
/** Where work item keys in a pull request's title, branch and description point: `PAY-{n}=corp-jira` strings, or `{ text, connection }`. */
|
|
815
|
+
keyPatterns?: Array<string | KeyPattern>;
|
|
816
|
+
/** Pull request author kinds set by hand, by author id: `{ "release-bot": "BOT" }`, or `id=KIND` strings. */
|
|
817
|
+
authorKinds?: Record<string, string> | string[];
|
|
517
818
|
}
|
|
819
|
+
/**
|
|
820
|
+
* Likely duplicates among OWI records you already hold, scored the way
|
|
821
|
+
* `util owi similar` scores them (src/core/owi/similar.ts), in-process and
|
|
822
|
+
* synchronous: `{ query }` ranks the records against some text, `{ item }`
|
|
823
|
+
* against one of them, `{ pairs: true }` lists likely duplicate pairs.
|
|
824
|
+
* `records` is OWI items (mapOwi's `items`), or the text `util owi map`
|
|
825
|
+
* printed. Lexical and deterministic: the same records give the same result.
|
|
826
|
+
* It doesn't run in the bounded worker the way `execute('util owi similar', …)`
|
|
827
|
+
* does, so a host scoring a very large set should use that. An unknown item, or
|
|
828
|
+
* a query with no words to compare, throws a ToilError with a fix.
|
|
829
|
+
*/
|
|
830
|
+
declare function findSimilar(records: readonly SimilarItem[] | string, request: SimilarRequest, options?: SimilarOptions): SimilarResult;
|
|
518
831
|
/** The OWI version this toil writes, as every item's `owi` says. */
|
|
519
832
|
declare const owiVersion: string;
|
|
520
833
|
/** docs/owi/schema.json, the JSON Schema (2020-12) every OWI item validates against. */
|
|
521
834
|
declare const owiSchema: Record<string, unknown>;
|
|
522
835
|
|
|
523
|
-
export { type ApiAnswer, type AreaSummary, type Body, type CommandInfo, type CommandKind, type ConnectionField, type ContextReport, type ContextSource, type ContextValue, type DossierReport, type Envelope, type ErrorBody, type ErrorCode, type Estimate, type EstimateUnit, type ExecuteOptions, type ExecutePerson, type FieldOverrides, type History, type Iteration, type IterationChange, type Link, type LinkType, type Meta, type OrphanHistory, type OwiMapOptions, type OwiResult, type OwiSkipped, type Page, type PageProgress, type Person, type ProgressEvent, type Question, type Registry, type RequestProgress, type RetryProgress, type StatusCategory, type Transition, type Unmapped, type Warning, type WorkItem, type WorkItemType, contractVersion, execute, mapOwi, owiSchema, owiVersion, registry, version };
|
|
836
|
+
export { type ApiAnswer, type AreaSummary, type AuthorKind, type AuthorKindSource, type Body, type Change, type ChangeSize, type ChangeState, type ChecksState, type CommandInfo, type CommandKind, type ConnectionField, type ContextReport, type ContextSource, type ContextValue, type DossierReport, type Envelope, type ErrorBody, type ErrorCode, type Estimate, type EstimateUnit, type ExecuteOptions, type ExecutePerson, type FieldOverrides, type History, type Iteration, type IterationChange, type KeyPattern, type Link, type LinkType, type Meta, type OrphanHistory, type OwiMapOptions, type OwiResult, type OwiSkipped, type Page, type PageProgress, type PairSearch, type Person, type ProgressEvent, type Question, type Registry, type RequestProgress, type RetryProgress, type Review, type ReviewState, type Reviewer, type ReviewerState, type SimilarField, type SimilarItem, type SimilarMatch, type SimilarOptions, type SimilarPair, type SimilarParts, type SimilarRef, type SimilarRequest, type SimilarResult, type SimilarWhy, type StatusCategory, type Transition, type Unmapped, type Warning, type WorkItem, type WorkItemType, contractVersion, execute, findSimilar, mapOwi, owiSchema, owiVersion, registry, version };
|
package/dist/api.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
// @imagile-dev/toil/api. The code is in ./toil-lib.js; this re-exports the API and nothing else.
|
|
2
|
-
export { contractVersion, execute, mapOwi, owiSchema, owiVersion, registry, version } from './toil-lib.js';
|
|
2
|
+
export { contractVersion, execute, findSimilar, mapOwi, owiSchema, owiVersion, registry, version } from './toil-lib.js';
|