@open-tomato/rafa 0.53.0 → 0.54.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/dist/PROMPT.md +7 -0
- package/dist/bundled/agents/loop-implementer.md +7 -1
- package/dist/bundled/operators/skills/rafa-stretch-gap-log/SKILL.md +16 -0
- package/dist/cli.js +2268 -1055
- package/dist/config/index.js +1 -1
- package/dist/config/shape.d.ts +7 -5
- package/dist/config-registry.d.ts +5 -5
- package/dist/config-schema-collaborate.d.ts +85 -0
- package/dist/config-schema-features.d.ts +2 -2
- package/dist/config-schema-hints.d.ts +53 -0
- package/dist/config-schema-hub.d.ts +5 -4
- package/dist/core/command/shared-flags.d.ts +1 -1
- package/dist/core/config/config.d.ts +1 -1
- package/dist/core/git/index.d.ts +12 -5
- package/dist/core/git/placed-line.d.ts +86 -0
- package/dist/effort/store/index.js +4 -2
- package/dist/effort/store/merge-store.d.ts +14 -3
- package/dist/effort/store/origins.d.ts +5 -4
- package/dist/effort/store/repository-facts.d.ts +147 -0
- package/dist/effort/store/sqlite.d.ts +7 -5
- package/dist/{index-rkrsdes6.js → index-8rr1etrx.js} +9 -2
- package/dist/{index-78zcdjf5.js → index-d772zq3m.js} +43 -3
- package/dist/{index-anvmm83x.js → index-mkhbaye7.js} +200 -3
- package/dist/{index-kqz8x8g9.js → index-waawdjq2.js} +138 -117
- package/dist/index.js +547 -192
- package/dist/{ready-cnzcnv4d.js → ready-9e1pyxdh.js} +2 -2
- package/dist/utils/shell.d.ts +17 -0
- package/package.json +12 -5
package/dist/config/index.js
CHANGED
package/dist/config/shape.d.ts
CHANGED
|
@@ -21,10 +21,10 @@
|
|
|
21
21
|
*
|
|
22
22
|
* This module declares core's own top-level keys, the keys of
|
|
23
23
|
* `packages/rafa/src/core/config/core-section.ts`, and composes {@link ConfigShape}
|
|
24
|
-
* from them and the interface each of the
|
|
25
|
-
* (`src/config-schema-*.ts`) exports for the keys it
|
|
26
|
-
* for `hub`, `ReleaseShape` for `pr` and `release`,
|
|
27
|
-
* extended by {@link ConfigShape}. A namespace two packages share is a
|
|
24
|
+
* from them and the interface each of the sixteen section files
|
|
25
|
+
* (`packages/rafa/src/config-schema-*.ts`) exports for the keys it
|
|
26
|
+
* writes: `HubShape` for `hub`, `ReleaseShape` for `pr` and `release`,
|
|
27
|
+
* and so on, each extended by {@link ConfigShape}. A namespace two packages share is a
|
|
28
28
|
* named interface here holding core's keys and extending the part each
|
|
29
29
|
* section exports as an interface of its own: {@link LoopShape} extends
|
|
30
30
|
* `LoopRetriesShape`, `LoopContinueShape` and `WrapUpShape`,
|
|
@@ -48,8 +48,10 @@
|
|
|
48
48
|
import type { BoardProjectLimitsShape } from '@open-tomato/rafa/config-schema-board-project';
|
|
49
49
|
import type { BugsShape } from '@open-tomato/rafa/config-schema-bugs';
|
|
50
50
|
import type { ChecksShape } from '@open-tomato/rafa/config-schema-checks';
|
|
51
|
+
import type { CollaborateShape } from '@open-tomato/rafa/config-schema-collaborate';
|
|
51
52
|
import type { ErrorsShape } from '@open-tomato/rafa/config-schema-errors';
|
|
52
53
|
import type { FeaturesShape } from '@open-tomato/rafa/config-schema-features';
|
|
54
|
+
import type { HintsShape } from '@open-tomato/rafa/config-schema-hints';
|
|
53
55
|
import type { HubShape } from '@open-tomato/rafa/config-schema-hub';
|
|
54
56
|
import type { IssuesShape } from '@open-tomato/rafa/config-schema-issues';
|
|
55
57
|
import type { LoggerShape } from '@open-tomato/rafa/config-schema-logger';
|
|
@@ -129,7 +131,7 @@ export interface DangerousShape extends ReleaseDangerousShape {
|
|
|
129
131
|
readonly selfUpdateDuringLoop: boolean;
|
|
130
132
|
}
|
|
131
133
|
/** The nested file shape: core's keys, and each section's; see the module note. */
|
|
132
|
-
export interface ConfigShape extends BugsShape, ChecksShape, ErrorsShape, FeaturesShape, HubShape, IssuesShape, LoggerShape, ReleaseShape, TestsShape, TriageShape {
|
|
134
|
+
export interface ConfigShape extends BugsShape, ChecksShape, CollaborateShape, ErrorsShape, FeaturesShape, HintsShape, HubShape, IssuesShape, LoggerShape, ReleaseShape, TestsShape, TriageShape {
|
|
133
135
|
/** `version`: the config format's version. */
|
|
134
136
|
readonly version: ConfigVersion;
|
|
135
137
|
/** `store`: the effort store's backend. */
|
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The registry: the
|
|
2
|
+
* The registry: the seventeen sections of the config schema, handed to
|
|
3
3
|
* core when {@link registerCoreConfigSections} is called, and the merged schema read off
|
|
4
4
|
* them, {@link SETTINGS}, {@link CONFIG_DEFAULTS}, {@link SETTING_NAMES},
|
|
5
5
|
* {@link SETTING_BY_KEY}, {@link SECTIONS} and {@link knownKeysAbove}.
|
|
6
6
|
*
|
|
7
7
|
* Core declares the section contract (`packages/rafa/src/core/config/section.ts`) and
|
|
8
8
|
* names no section. This module, outside `packages/rafa/src/core/`, is the one place
|
|
9
|
-
* the
|
|
10
|
-
* (`CORE_SECTION`) and the
|
|
11
|
-
*
|
|
9
|
+
* the seventeen are listed, {@link CONFIG_SECTIONS}: core's own
|
|
10
|
+
* (`CORE_SECTION`) and the sixteen files `config-schema-*.ts` under
|
|
11
|
+
* `packages/rafa/src/` that each export one.
|
|
12
12
|
*
|
|
13
13
|
* Importing it registers nothing. {@link registerCoreConfigSections}
|
|
14
14
|
* calls `registerConfigSections` once, with that list cut into the runs
|
|
@@ -86,7 +86,7 @@
|
|
|
86
86
|
* `src/index.ts` publishes this module's {@link CONFIG_DEFAULTS}.
|
|
87
87
|
*/
|
|
88
88
|
import type { ConfigSection, ConfigSetting, RafaConfig, SettingSpec } from '@open-tomato/rafa/core/config';
|
|
89
|
-
/** The
|
|
89
|
+
/** The seventeen sections, core's first, in the order they are registered. */
|
|
90
90
|
export declare const CONFIG_SECTIONS: readonly ConfigSection[];
|
|
91
91
|
/**
|
|
92
92
|
* The hook `loadConfig` calls with every config it resolves: it hands
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `collaborate` section of the config schema: the one key a project
|
|
3
|
+
* sets to report a gap or a bug on the board of a tool it consumes,
|
|
4
|
+
* `collaborate.rafa`, with its field, its default, its spec and its
|
|
5
|
+
* reader, and {@link collaborateTarget}, which answers the board a
|
|
6
|
+
* `--upstream=<tool>` names. {@link COLLABORATE_SECTION} hands them to
|
|
7
|
+
* core as one `ConfigSection`, package `collaborate`, and the
|
|
8
|
+
* `declare module` below adds {@link CollaborateSettings} to
|
|
9
|
+
* `RafaConfig`. {@link CollaborateShape} holds the keys a file writes,
|
|
10
|
+
* which `src/config/shape.ts` composes into `ConfigShape`, the nested
|
|
11
|
+
* file shape. `config-registry.ts`'s `CONFIG_DEFAULTS` and `SETTINGS`
|
|
12
|
+
* spread {@link COLLABORATE_DEFAULTS} and {@link COLLABORATE_SETTINGS}.
|
|
13
|
+
*
|
|
14
|
+
* The section sits in a module of its own, as `config-schema-hub.ts`
|
|
15
|
+
* does, and every rule `config.ts` and `section.ts` state about a KEY
|
|
16
|
+
* holds here, as every rule `config-sections.ts` states about a VALUE
|
|
17
|
+
* does: nothing is coerced.
|
|
18
|
+
*
|
|
19
|
+
* ## The key
|
|
20
|
+
*
|
|
21
|
+
* `.rafa/specs/rafa-751-report-rafa-gaps-bugs.md` names it:
|
|
22
|
+
* `collaborate.rafa: <owner>/<name>`, the repository whose board
|
|
23
|
+
* `rafa issue create`, `rafa issue comment` and `rafa issue list` reach
|
|
24
|
+
* under `--upstream=rafa`. Four readings this module makes:
|
|
25
|
+
*
|
|
26
|
+
* - It defaults to NULL, meaning "nobody has said", as `hub.url`
|
|
27
|
+
* does, and null keeps reporting upstream off: no default
|
|
28
|
+
* repository is one this module could spell for every team.
|
|
29
|
+
* - Its value is one `owner/name`, the pattern
|
|
30
|
+
* `packages/rafa-board/src/board/repository.ts` holds a board's
|
|
31
|
+
* `nameWithOwner` to: two parts, each holding no `/` and no
|
|
32
|
+
* whitespace. A non-string, a blank string, `rafa`,
|
|
33
|
+
* `open-tomato/rafa/x` and `open tomato/rafa` are each refused at
|
|
34
|
+
* load, the refusal naming `collaborate.rafa`. The pattern is
|
|
35
|
+
* spelled again here rather than imported: core does not depend on
|
|
36
|
+
* `rafa-board`.
|
|
37
|
+
* - Only `rafa` is read under `collaborate`. Any other key under it,
|
|
38
|
+
* `collaborate.bun` included, names no setting and is warned about
|
|
39
|
+
* as the loader warns about every unknown key; a later tool's key
|
|
40
|
+
* arrives with the code that reads it.
|
|
41
|
+
* - It is not a `CommandLineSetting`: where a project may report is
|
|
42
|
+
* the project's word, and `--upstream` names a tool, never a board.
|
|
43
|
+
*/
|
|
44
|
+
import type { ConfigSection, SettingSpec } from './core/config/index.js';
|
|
45
|
+
import type { Reader } from './core/config/sections.js';
|
|
46
|
+
declare module './core/config/config-schema.js' {
|
|
47
|
+
/** The `collaborate` section's fields, added to core's. */
|
|
48
|
+
interface RafaConfig extends CollaborateSettings {
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
/** The `collaborate` keys a file writes; `src/config/shape.ts` composes them into `ConfigShape`. */
|
|
52
|
+
export interface CollaborateShape {
|
|
53
|
+
readonly collaborate: {
|
|
54
|
+
readonly rafa: string;
|
|
55
|
+
};
|
|
56
|
+
}
|
|
57
|
+
/** The `collaborate` section's settings, resolved. */
|
|
58
|
+
export interface CollaborateSettings {
|
|
59
|
+
/**
|
|
60
|
+
* The `owner/name` of the repository a rafa gap or bug is reported
|
|
61
|
+
* on, or null when nobody has said and reporting upstream is off.
|
|
62
|
+
* `collaborate.rafa`.
|
|
63
|
+
*/
|
|
64
|
+
collaborateRafa: string | null;
|
|
65
|
+
}
|
|
66
|
+
/** A tool a key under `collaborate` names, as `--upstream=<tool>` spells it. */
|
|
67
|
+
export type CollaborateTool = 'rafa';
|
|
68
|
+
/** Every tool a key under `collaborate` names, in the order the section reads them. */
|
|
69
|
+
export declare const COLLABORATE_TOOLS: readonly CollaborateTool[];
|
|
70
|
+
/** The `collaborate` section's defaults: every key absent, read as null. */
|
|
71
|
+
export declare const COLLABORATE_DEFAULTS: Readonly<CollaborateSettings>;
|
|
72
|
+
/** Accepts one `owner/name`, kept as written; see the module note. */
|
|
73
|
+
export declare const collaborateRepository: Reader<string>;
|
|
74
|
+
/** The `collaborate` section's specs, spread into `SETTINGS`. */
|
|
75
|
+
export declare const COLLABORATE_SETTINGS: {
|
|
76
|
+
readonly [K in keyof CollaborateSettings]: SettingSpec<K>;
|
|
77
|
+
};
|
|
78
|
+
/** The `collaborate` section: its one setting and its default, with no check. */
|
|
79
|
+
export declare const COLLABORATE_SECTION: ConfigSection;
|
|
80
|
+
/**
|
|
81
|
+
* The `owner/name` the resolved config names for `tool`, or null when
|
|
82
|
+
* its key is absent, so reporting upstream to it is off. A setting left
|
|
83
|
+
* out of `config` reads as its default, null.
|
|
84
|
+
*/
|
|
85
|
+
export declare function collaborateTarget(config: Partial<CollaborateSettings>, tool: CollaborateTool): string | null;
|
|
@@ -6,9 +6,9 @@
|
|
|
6
6
|
* below adds {@link FeaturesSettings} to `RafaConfig`.
|
|
7
7
|
* {@link FeaturesShape} holds the keys a file writes, which
|
|
8
8
|
* `src/config/shape.ts` composes into `ConfigShape`, the nested file
|
|
9
|
-
* shape. `config-registry.ts` registers the section
|
|
9
|
+
* shape. `config-registry.ts` registers the section fifteenth in
|
|
10
10
|
* `CONFIG_SECTIONS`, and its `CONFIG_DEFAULTS` and `SETTINGS` spread the
|
|
11
|
-
* objects below
|
|
11
|
+
* objects below after the `checks` section and ahead of the `hints` one.
|
|
12
12
|
*
|
|
13
13
|
* ## The keys
|
|
14
14
|
*
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `hints` section of the config schema: one switch, `hints.skills`,
|
|
3
|
+
* saying whether a step rafa hands over is followed by the skill case
|
|
4
|
+
* that explains it. {@link HINTS_SECTION} hands it to core as one
|
|
5
|
+
* `ConfigSection`, package `hints`, and the `declare module` below adds
|
|
6
|
+
* {@link HintsSettings} to `RafaConfig`. {@link HintsShape} holds the key
|
|
7
|
+
* a file writes, which `src/config/shape.ts` composes into
|
|
8
|
+
* `ConfigShape`, the nested file shape. `config-registry.ts` registers
|
|
9
|
+
* the section sixteenth and last in `CONFIG_SECTIONS`, and its
|
|
10
|
+
* `CONFIG_DEFAULTS` and `SETTINGS` spread the objects below last, after
|
|
11
|
+
* the `features` section.
|
|
12
|
+
*
|
|
13
|
+
* ## The key
|
|
14
|
+
*
|
|
15
|
+
* `hints.skills` is read with core's `flag`, so it takes `true` or
|
|
16
|
+
* `false` and refuses anything else, a quoted `"true"` included, naming
|
|
17
|
+
* the key. It defaults to `false`: a step reads as it did before the key
|
|
18
|
+
* existed, and a project opts in. When it is `true`, a `Next:` step of
|
|
19
|
+
* `rafa release tag`, `rafa release settle` or `rafa release publish`
|
|
20
|
+
* whose case has a file under `.claude/skills/rafa-release/` is followed
|
|
21
|
+
* by one indented line, `skill: rafa-release › <case>`. It is not a
|
|
22
|
+
* `CommandLineSetting`, as no boolean `release` key is.
|
|
23
|
+
*
|
|
24
|
+
* The section holds the switch and nothing that reads it: the release
|
|
25
|
+
* steps read the setting off the resolved `RafaConfig`.
|
|
26
|
+
*/
|
|
27
|
+
import type { ConfigSection, SettingSpec } from './core/config/index.js';
|
|
28
|
+
declare module './core/config/config-schema.js' {
|
|
29
|
+
/** The `hints` section's fields, added to core's. */
|
|
30
|
+
interface RafaConfig extends HintsSettings {
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
/** The `hints` keys as a file writes them. */
|
|
34
|
+
export interface HintsShape {
|
|
35
|
+
/** The `hints` keys. */
|
|
36
|
+
readonly hints: {
|
|
37
|
+
/** `hints.skills`: whether a handed-over step names the skill case that explains it. */
|
|
38
|
+
readonly skills: boolean;
|
|
39
|
+
};
|
|
40
|
+
}
|
|
41
|
+
/** The `hints` section's settings, resolved. */
|
|
42
|
+
export interface HintsSettings {
|
|
43
|
+
/** Whether a handed-over step is followed by its skill case line. `hints.skills`. */
|
|
44
|
+
hintsSkills: boolean;
|
|
45
|
+
}
|
|
46
|
+
/** What the `hints` settings resolve to when no layer names them: no skill line. */
|
|
47
|
+
export declare const HINTS_DEFAULTS: Readonly<HintsSettings>;
|
|
48
|
+
/** The `hints` section's setting specs, in the order they are reported. */
|
|
49
|
+
export declare const HINTS_SETTINGS: {
|
|
50
|
+
readonly [K in keyof HintsSettings]: SettingSpec<K>;
|
|
51
|
+
};
|
|
52
|
+
/** The `hints` section: the one switch, with its default and no check. */
|
|
53
|
+
export declare const HINTS_SECTION: ConfigSection;
|
|
@@ -28,10 +28,11 @@
|
|
|
28
28
|
* `effort.sync: service`), `hub.tokenSecret` (the secret store name of
|
|
29
29
|
* the token, never the token) and `hub.timeout` (default `3s`, from `1s`
|
|
30
30
|
* to `30s`, `0` and negative values refused). The server's keys,
|
|
31
|
-
* `hub.repository`, `hub.port`, `hub.storePath
|
|
32
|
-
*
|
|
33
|
-
*
|
|
34
|
-
*
|
|
31
|
+
* `hub.repository`, `hub.port`, `hub.storePath`, `hub.auth.cacheFor`,
|
|
32
|
+
* `hub.store.sqliteLibrary` and `hub.index.rebuildAfterPush`, are read by
|
|
33
|
+
* `packages/rafa-hub/` from its own file and are not keys here: in a
|
|
34
|
+
* project's file they are unknown keys, warned about and acted on by
|
|
35
|
+
* nothing. Five readings the spec leaves to this module:
|
|
35
36
|
*
|
|
36
37
|
* - `hub.url` and `hub.tokenSecret` default to NULL, meaning "nobody
|
|
37
38
|
* has said", as `pr.base` does: no default address or secret name
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
* `loop start`. They belong to four features, and three of them are
|
|
8
8
|
* declared in a declarations file (`packages/rafa-pr/src/commands/pr/declarations.ts`,
|
|
9
9
|
* `packages/rafa-board/src/commands/issue/declarations.ts`), which imports core's entries
|
|
10
|
-
*
|
|
10
|
+
* and, for issue, its two sibling files, and no module under `src/`. So the flag lives here, where every
|
|
11
11
|
* one of the six can reach it, and each declares this value itself
|
|
12
12
|
* rather than a copy its tests would have to hold equal.
|
|
13
13
|
*
|
|
@@ -100,7 +100,7 @@
|
|
|
100
100
|
* `section.ts` (`activeSettings()`) and take each default from
|
|
101
101
|
* `activeDefaults()`, so a layer and a resolution hold every registered
|
|
102
102
|
* setting, in registration order. `src/config-registry.ts`, outside
|
|
103
|
-
* `packages/rafa/src/core/`, registers the
|
|
103
|
+
* `packages/rafa/src/core/`, registers the seventeen sections when its
|
|
104
104
|
* `registerCoreConfigSections` is called; a process that has not called
|
|
105
105
|
* it reads no setting at all, where the
|
|
106
106
|
* literal this loop replaced held every setting whatever was registered.
|
package/dist/core/git/index.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The barrel over git: every name `git.ts`, `commit.ts
|
|
3
|
-
* `gh-runner.ts` export but one, and nothing else.
|
|
2
|
+
* The barrel over git: every name `git.ts`, `commit.ts`,
|
|
3
|
+
* `gh-runner.ts` and `placed-line.ts` export but one, and nothing else.
|
|
4
4
|
*
|
|
5
5
|
* A file outside `packages/rafa/src/core/` imports this file and never the two behind
|
|
6
6
|
* it (`scripts/survey/core-barrels.ts` measures that, and
|
|
@@ -19,7 +19,12 @@
|
|
|
19
19
|
* each step;
|
|
20
20
|
* - `gh-runner.ts`: the type of the runner every `gh` command goes
|
|
21
21
|
* through and what one command answers, types alone, imported by
|
|
22
|
-
* nothing
|
|
22
|
+
* nothing;
|
|
23
|
+
* - `placed-line.ts`: a printed step placed where it must run, the
|
|
24
|
+
* command alone in its own checkout and `cd <checkout> && <command>`
|
|
25
|
+
* elsewhere, with the top-level read it is placed by. It imports
|
|
26
|
+
* `git.ts` for a type and `packages/rafa/src/utils/shell.ts`, which
|
|
27
|
+
* imports nothing, for `shellQuote`.
|
|
23
28
|
*
|
|
24
29
|
* ## The one name the two files share
|
|
25
30
|
*
|
|
@@ -79,12 +84,14 @@
|
|
|
79
84
|
* barrels spell theirs. No name here is part of the published surface:
|
|
80
85
|
* `src/index.ts` re-exports nothing from this file.
|
|
81
86
|
*
|
|
82
|
-
* `index.test.ts` holds the list to the
|
|
83
|
-
* exports is here once, as the same binding, `GitRunner` as the type
|
|
87
|
+
* `index.test.ts` holds the list to the files behind it: every name one
|
|
88
|
+
* of them exports is here once, as the same binding, `GitRunner` as the type
|
|
84
89
|
* `git.ts` declares, and no other name is here.
|
|
85
90
|
*/
|
|
86
91
|
export type { GhResult, GhRunner } from './gh-runner.js';
|
|
87
92
|
export type { GitResult, GitRunner, WorkingTreeStatus } from './git.js';
|
|
93
|
+
export type { PlaceAnswer, PlacedLine, PlaceSeams, UnplacedLine } from './placed-line.js';
|
|
88
94
|
export type { CommitAttempt, CommitMessage, CommitOptions, CommitOutcome, CommitStep, CommitType, CommitTypeRule, DerivedSubject, GitRunResult, SubjectOptions, } from './commit.js';
|
|
89
95
|
export { createGitRunner, gitSaid, parseWorkingTree, unquoteGitPath } from './git.js';
|
|
96
|
+
export { placeLine, readTopLevel } from './placed-line.js';
|
|
90
97
|
export { buildCommitMessage, COMMIT_TYPE_RULES, commitArgs, commitTaskWork, DEFAULT_COMMIT_TYPE, deriveCommitSubject, FALLBACK_DESCRIPTION, firstClause, headShaArgs, inferCommitType, MAX_MESSAGE_CHARS, MAX_SUBJECT_LENGTH, normaliseTaskText, spawnGit, stageAllArgs, stagedChangesArgs, } from './commit.js';
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A printed step placed where it must run: the command alone when the
|
|
3
|
+
* reader already stands in the checkout it needs, and
|
|
4
|
+
* `cd <checkout> && <command>` when they do not.
|
|
5
|
+
*
|
|
6
|
+
* A step a command prints after its own run is a line the reader
|
|
7
|
+
* copies or clicks, and it runs in the directory the command ran in.
|
|
8
|
+
* When that directory's git top level is the checkout the step needs,
|
|
9
|
+
* a `cd` in front would be noise; when it is another one, the step
|
|
10
|
+
* without it runs in the wrong checkout. So the line carries the `cd`
|
|
11
|
+
* exactly when the two differ.
|
|
12
|
+
*
|
|
13
|
+
* The helper knows nothing of the subject whose steps it places. The
|
|
14
|
+
* caller names the command, the checkout it must run in, and two seams:
|
|
15
|
+
* the top-level read of the directory the command ran in
|
|
16
|
+
* ({@link readTopLevel} over a {@link GitRunner} is the reading a
|
|
17
|
+
* caller passes in production) and the check that a path is there.
|
|
18
|
+
*
|
|
19
|
+
* ## The three readings that are not "the same place"
|
|
20
|
+
*
|
|
21
|
+
* - A different top level: the prefix.
|
|
22
|
+
* - A top-level read git did not answer (not a repository, git not
|
|
23
|
+
* spawned): the prefix too. The line then runs wherever it is
|
|
24
|
+
* clicked, which is the point of the prefix, and leaving it out
|
|
25
|
+
* would bet the step on a place nobody read.
|
|
26
|
+
* - A checkout path that is not there, as `git worktree list` still
|
|
27
|
+
* lists a worktree whose folder was removed: no line at all. The
|
|
28
|
+
* answer is `unplaced`, and the caller prints its own fallback, such
|
|
29
|
+
* as a `git switch` to the branch, since a `cd` into a missing
|
|
30
|
+
* folder fails before the command runs.
|
|
31
|
+
*
|
|
32
|
+
* The missing path is checked first, so a missing checkout answers
|
|
33
|
+
* `unplaced` whatever the top level reads.
|
|
34
|
+
*
|
|
35
|
+
* ## How two paths are compared
|
|
36
|
+
*
|
|
37
|
+
* Both are compared after `path.resolve`, which drops a trailing slash
|
|
38
|
+
* and `.` segments, and nothing more: no symlink is followed. Git
|
|
39
|
+
* prints both the top level (`git rev-parse --show-toplevel`) and the
|
|
40
|
+
* worktree paths (`git worktree list --porcelain`) with symlinks
|
|
41
|
+
* resolved, so two readings of git agree without it. A checkout that is
|
|
42
|
+
* not plain shell text is quoted with {@link shellQuote}.
|
|
43
|
+
*/
|
|
44
|
+
import type { GitRunner } from './git.js';
|
|
45
|
+
/** The seams {@link placeLine} reads the two places through. */
|
|
46
|
+
export interface PlaceSeams {
|
|
47
|
+
/**
|
|
48
|
+
* The git top level of the directory the command ran in, or null when
|
|
49
|
+
* git did not answer.
|
|
50
|
+
*/
|
|
51
|
+
readonly readTopLevel: () => string | null;
|
|
52
|
+
/** True when `path` is there on disk. */
|
|
53
|
+
readonly pathExists: (path: string) => boolean;
|
|
54
|
+
}
|
|
55
|
+
/** The line a step prints, placed where it must run. */
|
|
56
|
+
export interface PlacedLine {
|
|
57
|
+
readonly kind: 'placed';
|
|
58
|
+
/** The command alone, or `cd <checkout> && <command>`. */
|
|
59
|
+
readonly line: string;
|
|
60
|
+
}
|
|
61
|
+
/** No line: the checkout is not there, so the caller prints its own fallback. */
|
|
62
|
+
export interface UnplacedLine {
|
|
63
|
+
readonly kind: 'unplaced';
|
|
64
|
+
/** The checkout path that was not there. */
|
|
65
|
+
readonly checkout: string;
|
|
66
|
+
}
|
|
67
|
+
/** What {@link placeLine} answers. */
|
|
68
|
+
export type PlaceAnswer = PlacedLine | UnplacedLine;
|
|
69
|
+
/**
|
|
70
|
+
* `command` placed to run in `checkout`; see the module note.
|
|
71
|
+
*
|
|
72
|
+
* @param command - The command as the reader would type it in the checkout.
|
|
73
|
+
* @param checkout - The checkout the command must run in.
|
|
74
|
+
* @param seams - The top-level read and the path check.
|
|
75
|
+
* @returns The placed line, or `unplaced` when `checkout` is not there.
|
|
76
|
+
*/
|
|
77
|
+
export declare function placeLine(command: string, checkout: string, seams: PlaceSeams): PlaceAnswer;
|
|
78
|
+
/**
|
|
79
|
+
* The git top level of the directory `git` was made for, read with
|
|
80
|
+
* `git rev-parse --show-toplevel`, or null when git did not answer or
|
|
81
|
+
* printed nothing.
|
|
82
|
+
*
|
|
83
|
+
* @param git - The runner of the directory the command ran in.
|
|
84
|
+
* @returns The top level's absolute path, or null.
|
|
85
|
+
*/
|
|
86
|
+
export declare function readTopLevel(git: GitRunner): string | null;
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
// @bun
|
|
2
2
|
import {
|
|
3
3
|
EFFORT_KEY_PROJECTIONS,
|
|
4
|
+
WIRE_CONTRACT_VERSION,
|
|
4
5
|
WIRE_FORMAT,
|
|
5
6
|
WIRE_VERSION,
|
|
6
7
|
WireExportRefusal,
|
|
@@ -13,10 +14,10 @@ import {
|
|
|
13
14
|
openNdjsonStore,
|
|
14
15
|
openSqliteStore,
|
|
15
16
|
selectEffortStore
|
|
16
|
-
} from "../../index-
|
|
17
|
+
} from "../../index-mkhbaye7.js";
|
|
17
18
|
import {
|
|
18
19
|
TRUSTED_PERMISSIONS
|
|
19
|
-
} from "../../index-
|
|
20
|
+
} from "../../index-8rr1etrx.js";
|
|
20
21
|
import"../../index-2a7nb3an.js";
|
|
21
22
|
import"../../index-dj8en7fg.js";
|
|
22
23
|
import {
|
|
@@ -35,6 +36,7 @@ export {
|
|
|
35
36
|
WireExportRefusal,
|
|
36
37
|
WIRE_VERSION,
|
|
37
38
|
WIRE_FORMAT,
|
|
39
|
+
WIRE_CONTRACT_VERSION,
|
|
38
40
|
TRUSTED_PERMISSIONS,
|
|
39
41
|
STORE_BACKENDS,
|
|
40
42
|
EFFORT_KEY_PROJECTIONS
|
|
@@ -66,9 +66,20 @@
|
|
|
66
66
|
* `merge-conflicts.ts`) settles each matched pair and records in
|
|
67
67
|
* `merge_conflicts` what no rule settles, the commit gaps of each commit
|
|
68
68
|
* brought in and of the commit after it are recomputed
|
|
69
|
-
* (`recomputeCommitGaps`, `merge-commit-gaps.ts`),
|
|
70
|
-
*
|
|
71
|
-
*
|
|
69
|
+
* (`recomputeCommitGaps`, `merge-commit-gaps.ts`), the supersedes the
|
|
70
|
+
* readings brought in call for are written (`writeSupersedes`,
|
|
71
|
+
* `repository-facts.ts`), and one `merges` row records the merge: its
|
|
72
|
+
* id, the other store's id, when, and the rows added, skipped and in
|
|
73
|
+
* conflict over every merged table.
|
|
74
|
+
*
|
|
75
|
+
* The supersedes are the last step before that row, for the facts of
|
|
76
|
+
* the rows the union added to each table of `REPOSITORY_FACTS`, today
|
|
77
|
+
* `plan_ci`, and never for a fact no added reading reaches. A
|
|
78
|
+
* supersede the other store brought is one the union added already, so
|
|
79
|
+
* the writer absorbs it or finds its reading superseded and writes
|
|
80
|
+
* nothing twice. The rows it writes count as rows added to
|
|
81
|
+
* `reading_supersedes`, in that table's `added` and in `rowsAdded`, so
|
|
82
|
+
* the `merges` row and the count check below both hold them.
|
|
72
83
|
*
|
|
73
84
|
* The live store is then attached, and every table both files hold,
|
|
74
85
|
* the log apart, must hold its live row count plus the rows the merge
|
|
@@ -64,9 +64,10 @@
|
|
|
64
64
|
* The tables a merge unions, each carrying `origin_store` and
|
|
65
65
|
* `origin_seq`: since migration `row-origins` for the twelve tables
|
|
66
66
|
* older than it, and from the migration that creates it for
|
|
67
|
-
* `stale_docs` and `
|
|
68
|
-
* row into one of them is stamped. Three
|
|
69
|
-
* already and leave the pair as the row
|
|
67
|
+
* `stale_docs`, `bug_routes` and `reading_supersedes`. A production
|
|
68
|
+
* insert that writes a new row into one of them is stamped. Three
|
|
69
|
+
* inserts carry rows that exist already and leave the pair as the row
|
|
70
|
+
* holds it:
|
|
70
71
|
* the copy in `fix-schema.ts`, column for column from the live store;
|
|
71
72
|
* the union in `merge-union.ts`, which gives another store's row a new
|
|
72
73
|
* local `seq` and keeps its origin; and the restore in
|
|
@@ -76,7 +77,7 @@
|
|
|
76
77
|
* and `merge_conflicts` are the store's own bookkeeping and carry no
|
|
77
78
|
* origin.
|
|
78
79
|
*/
|
|
79
|
-
export declare const ORIGIN_TABLES: readonly ["sessions", "commits", "findings", "blockers", "out_of_scope_bugs", "report_absences", "task_reports", "preflight", "dispatches", "changes", "skill_invocations", "plan_ci", "stale_docs", "bug_routes"];
|
|
80
|
+
export declare const ORIGIN_TABLES: readonly ["sessions", "commits", "findings", "blockers", "out_of_scope_bugs", "report_absences", "task_reports", "preflight", "dispatches", "changes", "skill_invocations", "plan_ci", "stale_docs", "bug_routes", "reading_supersedes"];
|
|
80
81
|
/** One of the {@link ORIGIN_TABLES}. */
|
|
81
82
|
export type OriginTable = typeof ORIGIN_TABLES[number];
|
|
82
83
|
/**
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Repository facts: the readings of a shared source that two stores can
|
|
3
|
+
* both hold, and the supersedes that make two readings of one fact
|
|
4
|
+
* count once.
|
|
5
|
+
*
|
|
6
|
+
* A port and the hub can each read the same pull request's checks on
|
|
7
|
+
* the same head, so a merge of their stores holds two `plan_ci` rows that
|
|
8
|
+
* say one thing. Neither row is wrong and neither is dropped: the second
|
|
9
|
+
* is superseded by a row of `reading_supersedes`, never by a flag on the
|
|
10
|
+
* reading, and every reader that counts facts reads through those rows.
|
|
11
|
+
*
|
|
12
|
+
* ## The registry
|
|
13
|
+
*
|
|
14
|
+
* {@link REPOSITORY_FACTS} lists every table whose rows are readings of
|
|
15
|
+
* a shared source, beside `MERGE_RULES` (`merge-rules.ts`). An entry
|
|
16
|
+
* declares only its fact columns, the columns whose values are what the
|
|
17
|
+
* reading says, and its time column, when the reading was taken. Its
|
|
18
|
+
* identity, the columns that name one reading, is the table's
|
|
19
|
+
* `MERGE_RULES` identity and is never spelled twice.
|
|
20
|
+
*
|
|
21
|
+
* | Table | Facts | Time |
|
|
22
|
+
* | --- | --- | --- |
|
|
23
|
+
* | `plan_ci` | `pr`, `head_sha`, `verdict`, `failing` | `read_at` |
|
|
24
|
+
*
|
|
25
|
+
* ## The rule
|
|
26
|
+
*
|
|
27
|
+
* {@link SAME_FACT_RULE}, `same-fact@1`: two readings of one table are
|
|
28
|
+
* one fact when their fact columns are equal, two NULLs counting as
|
|
29
|
+
* equal; the canonical reading is the one with the earliest reading
|
|
30
|
+
* time. Two readings at one time are ordered by their key, so every
|
|
31
|
+
* store picks the same canonical one. For `plan_ci` the time is part of
|
|
32
|
+
* the identity, so two readings with one `pr`, `head_sha` and `read_at`
|
|
33
|
+
* are one row already and never meet that tie.
|
|
34
|
+
*
|
|
35
|
+
* ## A reading's key
|
|
36
|
+
*
|
|
37
|
+
* {@link readingKey} names a reading by its table's identity, as the
|
|
38
|
+
* JSON array of the identity values in `MERGE_RULES` order:
|
|
39
|
+
* `[7,"3f2a…","2026-11-08T10:00:00.000Z"]` for a `plan_ci` row. Never by
|
|
40
|
+
* the origin pair, which a reading an older runtime wrote does not hold.
|
|
41
|
+
* An identity value is text, a finite number or NULL; any other value is
|
|
42
|
+
* refused, since JSON would not spell it back.
|
|
43
|
+
*
|
|
44
|
+
* ## Writing supersedes
|
|
45
|
+
*
|
|
46
|
+
* {@link writeSupersedes} is handed the keys of the readings a write or
|
|
47
|
+
* a merge touched. For each fact they reach it reads every reading of
|
|
48
|
+
* that fact, takes the canonical one, and gives every other reading that
|
|
49
|
+
* is not yet the `superseded_key` of a row of that table and rule one
|
|
50
|
+
* row naming the canonical reading. So a late reading older than the
|
|
51
|
+
* canonical one adds a row superseding the old canonical reading, and
|
|
52
|
+
* the rows the old one already canonicalised are left to the reader's
|
|
53
|
+
* chain. Each insert is stamped (`stampedValues`, `origins.ts`) and
|
|
54
|
+
* absorbed on the table's identity (`reading_supersedes_by_fact`), so a
|
|
55
|
+
* port and the hub that write one supersede write one row.
|
|
56
|
+
*
|
|
57
|
+
* The writer opens no transaction of its own: a merge calls it as its
|
|
58
|
+
* last step inside the transaction of the union, and a reading's writer
|
|
59
|
+
* inside its own, so the readings and their supersedes land together.
|
|
60
|
+
* It never rescans a table it was not handed keys of.
|
|
61
|
+
*
|
|
62
|
+
* ## Reading facts
|
|
63
|
+
*
|
|
64
|
+
* {@link readRepositoryFacts} answers one {@link RepositoryFact} per
|
|
65
|
+
* fact of a table: its canonical reading, `sightings` (how many readings
|
|
66
|
+
* it superseded, so two readings of one fact answer one sighting), the
|
|
67
|
+
* origins that read it, and `lastSighting`, the latest reading time over
|
|
68
|
+
* all its readings, the canonical one included. Each reading follows its
|
|
69
|
+
* supersede rows to the reading no row of the rule supersedes, the
|
|
70
|
+
* earliest one first where a reading has two; a row naming a reading the
|
|
71
|
+
* store does not hold is not followed, and a chain that comes back to a
|
|
72
|
+
* reading it passed, which the writer never writes, ends at the earliest
|
|
73
|
+
* reading of that loop. The reader trusts the rows: what they join is
|
|
74
|
+
* one fact, as the writer that wrote them read it.
|
|
75
|
+
*
|
|
76
|
+
* A reading no supersede names stands as a fact of its own, as a
|
|
77
|
+
* reading written before the writer ran does. Nothing here matches
|
|
78
|
+
* readings at read time.
|
|
79
|
+
*/
|
|
80
|
+
import type { Database, SQLQueryBindings } from 'bun:sqlite';
|
|
81
|
+
/** One {@link REPOSITORY_FACTS} entry: what a reading says, and when it was read. */
|
|
82
|
+
export interface RepositoryFactColumns {
|
|
83
|
+
/** The columns whose values are the fact; equal in all of them, two readings are one fact. */
|
|
84
|
+
readonly facts: readonly string[];
|
|
85
|
+
/** The column holding when the reading was taken, as ISO 8601 text. */
|
|
86
|
+
readonly time: string;
|
|
87
|
+
}
|
|
88
|
+
/** Every table whose rows are readings of a shared source, by name. */
|
|
89
|
+
export declare const REPOSITORY_FACTS: Readonly<Record<string, RepositoryFactColumns>>;
|
|
90
|
+
/** The rule every supersede here is written under, as `reading_supersedes.rule` holds it. */
|
|
91
|
+
export declare const SAME_FACT_RULE = "same-fact@1";
|
|
92
|
+
/** One reading of a repository fact, as the reader answers it. */
|
|
93
|
+
export interface FactReading {
|
|
94
|
+
/** The reading's key, see {@link readingKey}. */
|
|
95
|
+
readonly key: string;
|
|
96
|
+
/** The fact columns' values, by column name. */
|
|
97
|
+
readonly fact: Readonly<Record<string, SQLQueryBindings>>;
|
|
98
|
+
/** When it was read. */
|
|
99
|
+
readonly time: string;
|
|
100
|
+
/** The store that wrote it, or null for a row with no origin pair. */
|
|
101
|
+
readonly origin: string | null;
|
|
102
|
+
}
|
|
103
|
+
/** One fact of a table, every reading of it counted once. */
|
|
104
|
+
export interface RepositoryFact {
|
|
105
|
+
/** The reading table. */
|
|
106
|
+
readonly table: string;
|
|
107
|
+
/** The earliest reading, the one its supersede chains end at. */
|
|
108
|
+
readonly canonical: FactReading;
|
|
109
|
+
/** How many readings the canonical one supersedes. */
|
|
110
|
+
readonly sightings: number;
|
|
111
|
+
/** The distinct origin stores of its readings, sorted; a reading with no origin adds none. */
|
|
112
|
+
readonly origins: readonly string[];
|
|
113
|
+
/** The latest reading time over all its readings, the canonical one included. */
|
|
114
|
+
readonly lastSighting: string;
|
|
115
|
+
}
|
|
116
|
+
/** A row as the readings query answers it. */
|
|
117
|
+
type StoredRow = Readonly<Record<string, SQLQueryBindings>>;
|
|
118
|
+
/**
|
|
119
|
+
* The key of one reading of `table`: the JSON array of its identity
|
|
120
|
+
* values in `MERGE_RULES` order. Throws for a table with no
|
|
121
|
+
* {@link REPOSITORY_FACTS} entry and for an identity value that is not
|
|
122
|
+
* text, a finite number or NULL. See the module note.
|
|
123
|
+
*/
|
|
124
|
+
export declare function readingKey(table: string, row: StoredRow): string;
|
|
125
|
+
/**
|
|
126
|
+
* Writes the supersedes the readings of `table` named by `touchedKeys`
|
|
127
|
+
* call for, and answers how many rows it added: for each fact they
|
|
128
|
+
* reach, one row per reading of it that is not its canonical one and
|
|
129
|
+
* not yet superseded under {@link SAME_FACT_RULE}. A key named twice, or
|
|
130
|
+
* two keys of one fact, write that fact's rows once.
|
|
131
|
+
*
|
|
132
|
+
* Throws for a table with no {@link REPOSITORY_FACTS} entry, a key that
|
|
133
|
+
* is not a JSON array of the table's identity values, and a key naming
|
|
134
|
+
* no reading the store holds: each is a caller's fault, and the caller's
|
|
135
|
+
* transaction takes back what was written. See the module note.
|
|
136
|
+
*/
|
|
137
|
+
export declare function writeSupersedes(db: Database, table: string, touchedKeys: readonly string[]): number;
|
|
138
|
+
/**
|
|
139
|
+
* Every fact of `table`, each reading counted once: one
|
|
140
|
+
* {@link RepositoryFact} per reading the supersede chains end at, in the
|
|
141
|
+
* order of their canonical readings' time, then key.
|
|
142
|
+
*
|
|
143
|
+
* Throws for a table with no {@link REPOSITORY_FACTS} entry. See the
|
|
144
|
+
* module note for how a chain is followed.
|
|
145
|
+
*/
|
|
146
|
+
export declare function readRepositoryFacts(db: Database, table: string): RepositoryFact[];
|
|
147
|
+
export {};
|
|
@@ -52,7 +52,7 @@
|
|
|
52
52
|
* implicit one. That is a declaration, not a repair: measured on SQLite
|
|
53
53
|
* 3.51.0, a `VACUUM` left implicit rowids where they were as well.
|
|
54
54
|
*
|
|
55
|
-
* The file holds
|
|
55
|
+
* The file holds eighteen tables that are not kinds. Six are filled from
|
|
56
56
|
* task reports: `findings`, `blockers`, `out_of_scope_bugs` and
|
|
57
57
|
* `changes`, one per list a report carries, `report_absences`, one row
|
|
58
58
|
* per task session whose output held no report to read, and
|
|
@@ -65,10 +65,12 @@
|
|
|
65
65
|
* six are, one row per documentation line a report named as stale;
|
|
66
66
|
* `stale-docs.ts` writes it and holds its row type. A twelfth,
|
|
67
67
|
* `bug_routes`, holds one row per `out_of_scope_bugs` entry the triage
|
|
68
|
-
* step routed; `bug-routes.ts` writes it and holds its row type.
|
|
69
|
-
* thirteenth
|
|
70
|
-
*
|
|
71
|
-
*
|
|
68
|
+
* step routed; `bug-routes.ts` writes it and holds its row type. A
|
|
69
|
+
* thirteenth, `reading_supersedes`, holds one row per reading of a
|
|
70
|
+
* shared source that another reading of the same fact supersedes;
|
|
71
|
+
* `repository-facts.ts` writes and reads it. The fourteenth is `schema_migrations`, the
|
|
72
|
+
* migration log, which only `bring-forward.ts` writes; the section on
|
|
73
|
+
* bringing a store forward says what it holds. The last four are the store's own identity and
|
|
72
74
|
* merge trail: `store_meta`, `store_replaced`, `merges` and
|
|
73
75
|
* `merge_conflicts`. The port's row map names none of them, and
|
|
74
76
|
* nothing in this module reads or writes them. `findings.ts` writes the
|