@fro.bot/systematic 3.32.2 → 3.33.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.
@@ -0,0 +1,189 @@
1
+ /**
2
+ * The CI side of `ce:connect`: the report a scheduled run posts, and the ticks
3
+ * an operator leaves on it. One module defines the report format, so what
4
+ * `render-report` writes is exactly what `apply-ticks` reads.
5
+ *
6
+ * Trust: every file read here is untrusted input, including the state the CI
7
+ * run itself wrote. The run record, the invocation record, the candidate
8
+ * payload store, the manifest store and the report body each get bounded
9
+ * reads, typed fields and named keys only. Model text reaches the report in
10
+ * fences only, with mentions, issue references and comment delimiters broken
11
+ * so nothing in it can notify, link or write a marker.
12
+ *
13
+ * A decision comes from one place: a checkbox line the renderer generated,
14
+ * inside the single delimited section, outside any code fence, whose id is in
15
+ * the manifest of the report that was read and whose candidate is still open.
16
+ * The manifest of a report is stored under the hash its body carries, so a
17
+ * report that was posted keeps its own manifest even when a later render
18
+ * failed to post or posted something else.
19
+ *
20
+ * Import rule: node builtins and the `connect-*` modules. The `ce:connect`
21
+ * helper bundles this module, so it must never import zod, `config.ts` or
22
+ * `config-schema.ts`.
23
+ *
24
+ * Layout in the state root, next to the ledger:
25
+ *
26
+ * ci-payloads.json the text of each open candidate (the ledger holds none)
27
+ * ci-manifests.json the candidate ids of the last fourteen reports
28
+ * report.md the report body the last render wrote
29
+ *
30
+ * Neither operation reads the network or the clock: the date and the GitHub
31
+ * run come from the caller.
32
+ */
33
+ import { type LockBusyReason, type ProcessTable } from './connect-state.js';
34
+ /** A report body is never longer than this many characters. */
35
+ export declare const REPORT_MAX_CHARS = 60000;
36
+ /** The manifests kept: the newest reports a person can still be looking at. */
37
+ export declare const MANIFESTS_KEPT = 14;
38
+ export declare const REPORT_FILE = "report.md";
39
+ export declare const PAYLOAD_FILE = "ci-payloads.json";
40
+ export declare const MANIFEST_FILE = "ci-manifests.json";
41
+ export declare const DECISIONS_BEGIN = "<!-- connect-decisions:begin -->";
42
+ export declare const DECISIONS_END = "<!-- connect-decisions:end -->";
43
+ export type DecisionStatus = 'promoted' | 'rejected';
44
+ /** `<!-- connect-manifest:<hash> -->`: which stored manifest this body was rendered with. */
45
+ export declare function manifestMarker(hash: string): string;
46
+ /** One generated checkbox line. The marker carries the id; nothing else on the line is read. */
47
+ export declare function decisionLine(id: string, status: DecisionStatus, ticked: boolean): string;
48
+ export interface CiOptions {
49
+ readonly processes?: ProcessTable;
50
+ readonly now?: () => number;
51
+ }
52
+ /**
53
+ * Make model text inert in a GitHub issue. Control and format characters go,
54
+ * and a zero-width space breaks each thing the page would act on: `@` (a
55
+ * mention), `#` before a digit and `GH-` before a digit (an issue reference,
56
+ * alone or after `owner/repo`), and the delimiters of an HTML comment, so
57
+ * text cannot write a marker. Removing the zero-width spaces gives back the
58
+ * original text.
59
+ */
60
+ export declare function neutraliseText(text: string): string;
61
+ /** Neutralised text in a fenced block whose fence is longer than any backtick run inside it. */
62
+ export declare function fenceText(text: string): string;
63
+ export type BodySection = 'ok' | 'missing' | 'malformed';
64
+ export interface ParsedBox {
65
+ readonly id: string;
66
+ readonly status: DecisionStatus;
67
+ readonly ticked: boolean;
68
+ }
69
+ export interface ParsedBody {
70
+ /** The hash in the manifest marker, when the body has exactly one. */
71
+ readonly manifest: string | undefined;
72
+ readonly section: BodySection;
73
+ /** The generated checkbox lines inside the section, in document order. */
74
+ readonly boxes: readonly ParsedBox[];
75
+ }
76
+ /**
77
+ * Read a report body. Only exact generated lines count, only inside the one
78
+ * delimited section, and never inside a code fence. A body with a delimiter
79
+ * missing, repeated or out of order has no section, and a body with no marker
80
+ * or more than one marker has no manifest.
81
+ */
82
+ export declare function parseReportBody(body: string): ParsedBody;
83
+ export type BodyRead = {
84
+ readonly status: 'ok';
85
+ readonly body: string;
86
+ } | {
87
+ readonly status: 'failed';
88
+ readonly reason: 'body-missing' | 'body-symlink' | 'body-not-regular' | 'body-too-large' | 'body-unreadable';
89
+ };
90
+ /** Read a report body from a file: one bounded regular file, never a symlink. */
91
+ export declare function readReportBody(file: string): BodyRead;
92
+ export type ReportOutcome = 'complete' | 'degraded' | 'busy' | 'failed' | 'no-final-line';
93
+ export interface RenderRequest {
94
+ /** The UTC date of the report, `YYYY-MM-DD`. */
95
+ readonly date: string;
96
+ /** The GitHub run id and attempt of this workflow run. */
97
+ readonly runId: string;
98
+ readonly attempt: string;
99
+ /** Whether an Actions cache was restored for this run. */
100
+ readonly cacheRestored: boolean;
101
+ }
102
+ export type RenderResult = {
103
+ readonly status: 'rendered';
104
+ readonly body: string;
105
+ readonly bodyFile: string;
106
+ /** The hash in the body's manifest marker. */
107
+ readonly manifest: string;
108
+ readonly open: number;
109
+ readonly shown: number;
110
+ readonly hidden: number;
111
+ /** Candidates listed for the first time on this date. */
112
+ readonly fresh: number;
113
+ /** The GitHub runs the listed candidates came from, in the order they appear. */
114
+ readonly runs: readonly string[];
115
+ readonly outcome: ReportOutcome;
116
+ /** The workflow job turns red after posting. */
117
+ readonly red: boolean;
118
+ /** False when the report was rendered without the lock and recorded no payload or manifest. */
119
+ readonly stateUpdated: boolean;
120
+ } | {
121
+ readonly status: 'busy';
122
+ readonly reason: LockBusyReason;
123
+ } | {
124
+ readonly status: 'failed';
125
+ readonly reason: 'invalid-request' | 'lock-failed' | 'ledger-unreadable' | 'no-invocation' | 'payload-store-unreadable' | 'payload-store-too-large' | 'manifest-store-unreadable' | 'write-failed';
126
+ };
127
+ /**
128
+ * Render the report body for the state in `root`: the open candidates of the
129
+ * ledger, oldest first, as many as fit under the cap, each with its two
130
+ * boxes. Updates the payload store and the manifest store and writes the body
131
+ * to `report.md`. It needs this workflow run's invocation record (the marker
132
+ * `<run>-<attempt>`); without one it writes nothing. A run that ended `busy`
133
+ * is still reported when a live holder keeps the lock: the ledger is read
134
+ * without it, only `report.md` is written, and the body says the state was
135
+ * not updated.
136
+ */
137
+ export declare function renderReport(root: string, request: RenderRequest, options?: CiOptions): RenderResult;
138
+ export interface TickOptions extends CiOptions {
139
+ readonly hooks?: {
140
+ /** Runs after the ticks are sorted and before the first one is recorded. */
141
+ readonly afterTriage?: () => void;
142
+ };
143
+ }
144
+ export interface TickRequest {
145
+ /** The report body as the issue holds it now. */
146
+ readonly body: string;
147
+ /** The report's issue number; it goes into the reason a decision records. */
148
+ readonly issue: number;
149
+ }
150
+ export interface AcceptedTick {
151
+ readonly id: string;
152
+ readonly status: DecisionStatus;
153
+ }
154
+ export type SkipReason = 'conflict' | 'not-in-manifest' | 'not-open' | 'already-recorded';
155
+ export interface SkippedTick {
156
+ readonly id: string;
157
+ readonly status?: DecisionStatus;
158
+ readonly reason: SkipReason;
159
+ }
160
+ export type UnresolvedReason = 'manifest-missing' | 'unknown-candidate';
161
+ export interface UnresolvedTick {
162
+ readonly id: string;
163
+ readonly status: DecisionStatus;
164
+ readonly reason: UnresolvedReason;
165
+ }
166
+ export type TickResult = {
167
+ readonly status: 'applied';
168
+ readonly section: BodySection;
169
+ readonly accepted: readonly AcceptedTick[];
170
+ readonly skipped: readonly SkippedTick[];
171
+ readonly unresolved: readonly UnresolvedTick[];
172
+ } | {
173
+ readonly status: 'busy';
174
+ readonly reason: LockBusyReason;
175
+ readonly accepted: readonly AcceptedTick[];
176
+ } | {
177
+ readonly status: 'failed';
178
+ readonly reason: 'invalid-request' | 'ledger-unreadable' | 'lock-failed' | 'write-failed';
179
+ readonly accepted: readonly AcceptedTick[];
180
+ };
181
+ /**
182
+ * Record the ticks of a report body. A tick counts when its box is a generated
183
+ * line in the section of the body, its id is in the manifest the body names,
184
+ * and the candidate is open; a decision already recorded with the same reason
185
+ * is left as it is, so a second pass changes nothing. Each decision is made
186
+ * only if the candidate is still open under the lock, so one recorded since
187
+ * the ledger was read is skipped as `not-open`, never overwritten.
188
+ */
189
+ export declare function applyTicks(root: string, request: TickRequest, options?: TickOptions): TickResult;
@@ -12,6 +12,11 @@
12
12
  * imports the limits from here and tags the same block `trust:
13
13
  * 'project-or-higher'`; the dependency runs one way.
14
14
  *
15
+ * The block also holds named `groups` of allow-list-form entries. A group
16
+ * narrows a run to part of the allow list and never adds a project: nothing
17
+ * here checks that a member is on the allow list; the selection step does,
18
+ * on resolved main roots.
19
+ *
15
20
  * Trust: `connect` is user-only. User config, `OPENCODE_CONFIG_DIR` config and
16
21
  * the `systematic.local` file beside each may set it. `config.ts` strips it
17
22
  * from project config with a warning, and this reader never opens a project
@@ -21,8 +26,9 @@
21
26
  * a list over its limit makes that layer's block unreadable, and an
22
27
  * unreadable block contributes no entries. A missing, unparseable, oversize
23
28
  * or non-regular file contributes none either. No failure can add an entry
24
- * the user did not write. The four layers merge by union, so a layer that
25
- * fails drops only its own entries.
29
+ * the user did not write. The four layers merge, the allow lists by union and
30
+ * the groups by name (a later layer replaces a same-named group whole), so a
31
+ * layer that fails drops only its own entries and groups.
26
32
  *
27
33
  * Warnings name config files and reasons, never an allow-list entry: an entry
28
34
  * is a project the user chose to expose, and a warning can reach logs and
@@ -34,21 +40,30 @@ export declare const MAX_ALLOW_PROJECTS = 64;
34
40
  export declare const MAX_ALLOW_PROJECT_LENGTH = 4096;
35
41
  /** Largest config file the reader accepts. A larger file is unreadable. */
36
42
  export declare const MAX_CONNECT_CONFIG_BYTES: number;
43
+ /** One config layer holds at most this many groups. */
44
+ export declare const MAX_CONNECT_GROUPS = 32;
45
+ /** A group name: lowercase letters, digits and hyphens, one to 64 characters, led by a letter or digit. */
46
+ export declare const CONNECT_GROUP_NAME_PATTERN: RegExp;
47
+ /** Group name to member list. A member has the form of an allow-list entry. */
48
+ export type ConnectGroups = Record<string, string[]>;
37
49
  export interface ConnectSettings {
38
50
  allow_projects: string[];
51
+ groups?: ConnectGroups;
39
52
  }
40
53
  export type ConnectBlockValidation = {
41
54
  readonly ok: true;
42
55
  readonly allowProjects: string[];
56
+ readonly groups: ConnectGroups;
43
57
  } | {
44
58
  readonly ok: false;
45
59
  };
46
60
  /**
47
61
  * Validate a `connect` block with plain guards. The block is valid when it is
48
- * an object whose only key, if any, is `allow_projects`, holding at most
49
- * `MAX_ALLOW_PROJECTS` non-empty strings of at most `MAX_ALLOW_PROJECT_LENGTH`
50
- * characters. The zod schema in `config-schema.ts` accepts and rejects the
51
- * same values; a test pins the two together.
62
+ * an object whose only keys, if any, are `allow_projects` and `groups`.
63
+ * `allow_projects` holds at most `MAX_ALLOW_PROJECTS` non-empty strings of at
64
+ * most `MAX_ALLOW_PROJECT_LENGTH` characters. `groups` maps names to member
65
+ * lists as `readGroups` describes. The zod schema in `config-schema.ts`
66
+ * accepts and rejects the same values; a test pins the two together.
52
67
  */
53
68
  export declare function validateConnectBlock(value: unknown): ConnectBlockValidation;
54
69
  export interface ConnectConfigOptions {
@@ -78,8 +93,8 @@ export type ContainerRefusal = 'checkout' | 'allowed-root';
78
93
  /**
79
94
  * Why `dir` may not hold configuration or state, or `undefined` when it may.
80
95
  * A directory is refused when it is, or sits inside, an allowed root
81
- * (`allowed-root`), or when it or any ancestor holds a `.git` entry
82
- * (`checkout`). A repository is untrusted input, so what it holds must not
96
+ * (`allowed-root`), or when it or any ancestor holds a `.git` file, a `.git`
97
+ * symlink or a `.git` directory with a `HEAD` (`checkout`). A repository is untrusted input, so what it holds must not
83
98
  * steer what the helper reads or where it writes. Both sides are compared as
84
99
  * realpaths when they exist.
85
100
  */
@@ -87,6 +102,11 @@ export declare function containerRefusal(dir: string, allowedRoots: readonly str
87
102
  export interface ConnectAllowListLoad {
88
103
  /** The union of the readable layers' entries, in layer order, duplicates removed. */
89
104
  readonly allowProjects: readonly string[];
105
+ /**
106
+ * The readable layers' groups by name. A later layer replaces a same-named
107
+ * group whole. A member is not checked against the allow list here.
108
+ */
109
+ readonly groups: Readonly<Record<string, readonly string[]>>;
90
110
  /** Some layer's file or block could not be read and contributed nothing. */
91
111
  readonly unreadable: boolean;
92
112
  /** One line per problem. They name files and reasons, never an allow-list entry. */
@@ -137,7 +137,10 @@ export interface CoverageInput {
137
137
  export declare function checkCoverage(input: CoverageInput): Coverage;
138
138
  export interface OfferInput {
139
139
  readonly rules: readonly RuleEntry[];
140
+ /** The ledger's coverage, of every selection. Only the records of `selection` count. */
140
141
  readonly coverage: readonly CoverageRecord[];
142
+ /** The run's selection id; left out, the run has no selection. */
143
+ readonly selection?: string;
141
144
  /** Rules one run is offered: families per run times rules per family. */
142
145
  readonly size: number;
143
146
  }
@@ -161,7 +164,8 @@ export interface Offer {
161
164
  * each of those groups the order is round-robin across projects, then by path,
162
165
  * so a slice spans projects. The order depends on the index and the coverage
163
166
  * records only, never on the model, so repeated runs sweep the whole index
164
- * and then start over at the oldest.
167
+ * and then start over at the oldest. Coverage belongs to a selection: a rule
168
+ * that only another selection covered is not covered here.
165
169
  */
166
170
  export declare function planOffer(input: OfferInput): Offer;
167
171
  /** Where the sweep over the index stands. */
@@ -269,6 +273,7 @@ export type CandidateCheck = {
269
273
  readonly status: 'unresolved';
270
274
  readonly missing: readonly string[];
271
275
  };
276
+ export declare function pathProblem(rel: unknown): DropReason | undefined;
272
277
  /**
273
278
  * Check one candidate the researcher proposed. Fields the contract does not
274
279
  * name are never copied. The result is a validated candidate, a drop with its
@@ -340,6 +345,8 @@ export interface DigestModel {
340
345
  readonly consented?: boolean;
341
346
  };
342
347
  readonly degradeReasons: readonly string[];
348
+ /** What the run was narrowed to. */
349
+ readonly selection?: Selection;
343
350
  /** Where the sweep over the rule index stands after this run. */
344
351
  readonly sweep?: SweepProgress;
345
352
  readonly projects: readonly DigestProject[];
@@ -379,6 +386,10 @@ export interface DroppedCandidate {
379
386
  export declare const NO_TITLE = "(no title)";
380
387
  /** Name a dropped candidate from its raw form, which may be anything. */
381
388
  export declare function nameDropped(family: string, raw: unknown, reason: string): DroppedCandidate;
389
+ /** Render untrusted prose as a block quote, so it cannot become a heading or a list. */
390
+ export declare function quote(text: string): string;
391
+ export declare function inline(text: string): string;
392
+ export declare function renderCandidate(item: DigestCandidate, index: number): string[];
382
393
  /**
383
394
  * Render the digest. All free text in it came from documents or from the
384
395
  * researcher, so it appears only as block quotes and fenced excerpts with
@@ -386,6 +397,16 @@ export declare function nameDropped(family: string, raw: unknown, reason: string
386
397
  * nothing in it is an instruction.
387
398
  */
388
399
  export declare function renderDigest(model: DigestModel): string;
400
+ /** A run record path that can be pasted as one `candidate:` token: no whitespace, no control character. */
401
+ export declare function isPasteablePath(file: string): boolean;
402
+ /**
403
+ * The next step for one candidate, built from values the helper made and never
404
+ * from candidate text. A lesson is promoted by `ce:compound` from its tokens. A
405
+ * contradiction is promoted by `ce:compound-refresh` with the exact path of the
406
+ * target's own learning, which `ce:compound` refuses. A candidate to
407
+ * investigate has nothing to promote yet.
408
+ */
409
+ export declare function handoffLine(item: DigestModel['candidates'][number], runRecordPath: string, pasteable: boolean): string;
389
410
  /**
390
411
  * The short chat summary of a run. Candidate titles are untrusted text, so they
391
412
  * are quoted, one per line, and nothing in the summary reads as an instruction.
@@ -414,3 +435,91 @@ export declare const BATCH_BOUNDS: Readonly<{
414
435
  maxRulesPerFamily: 8;
415
436
  maxFamiliesPerRun: 6;
416
437
  }>;
438
+ /** The most words one request may carry. */
439
+ export declare const MAX_SELECTION_WORDS = 32;
440
+ /** The most characters in one word. */
441
+ export declare const MAX_SELECTION_WORD_LENGTH = 2048;
442
+ /** What a run reads: the whole allow list, a named group, or picked projects. */
443
+ export type Selection = {
444
+ readonly kind: 'all';
445
+ } | {
446
+ readonly kind: 'group';
447
+ readonly name: string;
448
+ readonly id: string;
449
+ } | {
450
+ readonly kind: 'projects';
451
+ readonly picks: readonly string[];
452
+ readonly id: string;
453
+ };
454
+ /** An allow-list entry that resolved to a project. */
455
+ export interface SelectionProject {
456
+ readonly entry: string;
457
+ readonly mainRoot: string;
458
+ }
459
+ export type MemberResolution = {
460
+ readonly status: 'resolved';
461
+ readonly mainRoot: string;
462
+ } | {
463
+ readonly status: 'unmatched';
464
+ readonly reason: string;
465
+ };
466
+ export interface SelectionRequest {
467
+ /** The `group:` and `projects:` words, as the skill collected them. */
468
+ readonly words: readonly string[];
469
+ /** The merged `connect.groups` of the user config, by name. */
470
+ readonly groups: Readonly<Record<string, readonly string[]>>;
471
+ /** The resolved allow list, in its own order. */
472
+ readonly allowed: readonly SelectionProject[];
473
+ /** Resolve one group member the way an allow-list entry resolves. */
474
+ readonly resolveMember: (entry: string) => MemberResolution;
475
+ }
476
+ export type SelectionRefusal = {
477
+ readonly reason: 'conflicting-selection';
478
+ readonly detail: string;
479
+ } | {
480
+ readonly reason: 'unknown-group';
481
+ readonly group: string;
482
+ } | {
483
+ readonly reason: 'unknown-project';
484
+ readonly project: string;
485
+ } | {
486
+ readonly reason: 'ambiguous-project';
487
+ readonly project: string;
488
+ readonly keys: readonly string[];
489
+ } | {
490
+ readonly reason: 'group-member-not-allowed';
491
+ readonly group: string;
492
+ readonly member: string;
493
+ readonly memberReason?: string;
494
+ };
495
+ export type SelectionResult = {
496
+ readonly status: 'ok';
497
+ readonly selection: Selection;
498
+ /** The selected projects, in allow-list order. */
499
+ readonly projects: readonly SelectionProject[];
500
+ }
501
+ /** The words are not a well-formed request. */
502
+ | {
503
+ readonly status: 'invalid';
504
+ } | {
505
+ readonly status: 'refused';
506
+ readonly refusal: SelectionRefusal;
507
+ };
508
+ /**
509
+ * The coverage namespace of a selection: its id, or nothing for a run with no
510
+ * selection, whose coverage carries no selection field.
511
+ */
512
+ export declare function selectionNamespace(selection: Selection): string | undefined;
513
+ /** The id of a selection: a hash of the sorted project keys, so only membership counts. */
514
+ export declare function selectionIdFor(keys: readonly string[]): string;
515
+ /**
516
+ * Turn the selection words of a request into the projects a run reads. Pure:
517
+ * the caller supplies the groups, the resolved allow list and the member
518
+ * resolver. A selection only narrows the allow list; a project that is not on
519
+ * it is refused, never added.
520
+ *
521
+ * Order of checks: a malformed word, then a conflict, then the lookups. Words
522
+ * that repeat identically count once; `projects:a,b` and `projects:b,a` are
523
+ * different words and conflict.
524
+ */
525
+ export declare function resolveSelection(request: SelectionRequest): SelectionResult;
@@ -0,0 +1,169 @@
1
+ /**
2
+ * Import for `ce:connect`: take the run record of a scheduled run, which names
3
+ * projects by the paths of a runner that no longer exists, and re-check every
4
+ * candidate in it against the operator's own checkouts.
5
+ *
6
+ * Trust: the record is untrusted input, downloaded by the skill and handed over
7
+ * as a directory. This module opens `run.json` in it and nothing else. Nothing
8
+ * the record says is believed. A project is matched by its recorded `owner/repo`
9
+ * to exactly one allowed local checkout. The rule id, the roles, the target
10
+ * root and the candidate id are computed again from local roots, and every
11
+ * fingerprint, excerpt and cited span is checked against the local files by the
12
+ * same `checkCandidate` a local run uses. The recorded id is checked only to
13
+ * detect a record that was edited, and is never used.
14
+ *
15
+ * Import rule: node builtins and the `connect-*` modules. The `ce:connect`
16
+ * helper bundles this module, so it must never import zod, `config.ts` or
17
+ * `config-schema.ts`.
18
+ */
19
+ import { type DigestCandidate, type ProjectFacts, type ValidCandidate } from './connect-helper-core.js';
20
+ import { type CandidateRecord } from './connect-state.js';
21
+ /** The record's fixed place in the downloaded directory. */
22
+ export declare const IMPORT_RECORD_FILE = "run.json";
23
+ export declare const MAX_IMPORT_RECORD_BYTES: number;
24
+ /** Why a downloaded record cannot be used at all. */
25
+ export type RecordFailure = 'directory-unreadable' | 'record-missing' | 'record-symlink' | 'record-not-regular' | 'record-too-large' | 'record-unreadable' | 'record-malformed' | 'record-schema-version';
26
+ /** A project of the run as the record names it. */
27
+ export interface ImportProject {
28
+ readonly root: string;
29
+ readonly key: string;
30
+ readonly name: string;
31
+ readonly repo?: string;
32
+ readonly commit?: string;
33
+ }
34
+ export interface ImportRecord {
35
+ /** The run's own id, from the record. */
36
+ readonly runId: string;
37
+ readonly projects: readonly ImportProject[];
38
+ /** Each candidate as recorded. Checked one by one, never trusted. */
39
+ readonly candidates: readonly unknown[];
40
+ }
41
+ export type RecordRead = {
42
+ readonly status: 'ok';
43
+ readonly record: ImportRecord;
44
+ } | {
45
+ readonly status: 'failed';
46
+ readonly reason: RecordFailure;
47
+ };
48
+ /** Check the parts of a record that every candidate depends on. */
49
+ export declare function parseImportRecord(value: unknown): RecordRead;
50
+ /**
51
+ * Read `run.json` from a downloaded directory. The directory is resolved to a
52
+ * real path once; the record is then read through the contained reader, which
53
+ * refuses a symlink, a non-regular file and a record over the size bound. No
54
+ * other entry of the directory is listed, opened or followed.
55
+ */
56
+ export declare function readImportRecord(directory: string): RecordRead;
57
+ /** An allowed local checkout. */
58
+ export interface LocalCheckout {
59
+ readonly root: string;
60
+ readonly key: string;
61
+ readonly name: string;
62
+ readonly repo?: string;
63
+ readonly commit?: string;
64
+ }
65
+ export type MappingRefusal = 'project-without-repo' | 'repo-not-allowed' | 'repo-ambiguous';
66
+ export type ProjectMapping = {
67
+ readonly status: 'mapped';
68
+ readonly local: LocalCheckout;
69
+ } | {
70
+ readonly status: 'unmapped';
71
+ readonly reason: MappingRefusal;
72
+ /** The keys of the local checkouts that share the repository. */
73
+ readonly keys?: readonly string[];
74
+ };
75
+ /** Match a recorded project to exactly one allowed local checkout by `owner/repo`. */
76
+ export declare function mapProject(project: ImportProject, locals: readonly LocalCheckout[]): ProjectMapping;
77
+ /** One recorded project and where it landed, for the answer. */
78
+ export interface ProjectReport {
79
+ readonly name: string;
80
+ readonly repo?: string;
81
+ readonly ciCommit?: string;
82
+ readonly status: 'mapped' | MappingRefusal;
83
+ readonly localRoot?: string;
84
+ readonly localKey?: string;
85
+ readonly localName?: string;
86
+ readonly localCommit?: string;
87
+ }
88
+ export type RefusalReason = 'candidate-malformed' | 'duplicate-candidate' | 'candidate-id-mismatch' | 'project-not-in-record' | MappingRefusal | 'project-unreadable' | 'path-rejected' | 'rule-id-mismatch' | 'file-not-tracked' | 'file-symlink' | 'file-changed' | 'file-vanished' | 'check-failed';
89
+ /** The fixed text for each refusal. */
90
+ export declare const REFUSAL_TEXT: Readonly<Record<RefusalReason, string>>;
91
+ export interface ImportRefusal {
92
+ /** The recorded id, when it is well formed. */
93
+ readonly id: string | null;
94
+ /** A display-safe line: capped, with control characters removed. */
95
+ readonly title: string;
96
+ readonly reason: RefusalReason;
97
+ readonly reasonText: string;
98
+ /** The sub-reason of a path or a check, from a fixed list. */
99
+ readonly detail?: string;
100
+ /** `<local project>:<path>` of the file the refusal is about. */
101
+ readonly file?: string;
102
+ readonly keys?: readonly string[];
103
+ readonly repo?: string;
104
+ }
105
+ export interface ImportAccepted {
106
+ readonly recordedId: string;
107
+ /** The candidate with local roots, checked against local files. */
108
+ readonly candidate: ValidCandidate;
109
+ readonly record: CandidateRecord;
110
+ /** The id computed from local roots. */
111
+ readonly id: string;
112
+ }
113
+ export interface Verification {
114
+ readonly projects: readonly ProjectReport[];
115
+ readonly accepted: readonly ImportAccepted[];
116
+ readonly refused: readonly ImportRefusal[];
117
+ }
118
+ export interface VerifyInput {
119
+ readonly record: ImportRecord;
120
+ readonly locals: readonly LocalCheckout[];
121
+ /** The inventory of a local checkout, or nothing when it cannot be read. */
122
+ readonly factsFor: (root: string) => ProjectFacts | undefined;
123
+ }
124
+ /**
125
+ * Check every candidate of the record against the local checkouts. A candidate
126
+ * is accepted only when it maps, its paths and ids hold, and `checkCandidate`
127
+ * passes on local files. Everything else is refused with a fixed reason; one
128
+ * refusal never stops the others.
129
+ */
130
+ export declare function verifyRecord(input: VerifyInput): Verification;
131
+ export interface ImportProvenance {
132
+ readonly repo: string;
133
+ readonly runId: string;
134
+ readonly commit?: string;
135
+ }
136
+ /** What was done with one candidate that passed local checks. */
137
+ export interface ImportedCandidate {
138
+ readonly item: DigestCandidate;
139
+ /** The run record that holds it. */
140
+ readonly runRecordPath: string;
141
+ }
142
+ export interface SkippedCandidate {
143
+ readonly id: string;
144
+ readonly title: string;
145
+ readonly reason: 'rejected-locally' | 'promoted-locally';
146
+ readonly refreshPointer?: string;
147
+ }
148
+ export interface ImportModel {
149
+ readonly runId: string | undefined;
150
+ readonly outcome: 'complete' | 'degraded';
151
+ /** Why the import is degraded; empty when it is complete. */
152
+ readonly degradeReasons: readonly string[];
153
+ readonly provenance: ImportProvenance;
154
+ /** The run's own id, from the record. */
155
+ readonly sourceRunId: string;
156
+ readonly projects: readonly ProjectReport[];
157
+ readonly imported: number;
158
+ readonly candidates: readonly ImportedCandidate[];
159
+ readonly skipped: readonly SkippedCandidate[];
160
+ readonly refused: readonly ImportRefusal[];
161
+ }
162
+ /**
163
+ * The chat summary of an import. Every value in it is either made by the
164
+ * helper or passed a validator; titles are quoted. The promotion lines are the
165
+ * ones a local run prints, so `ce:compound` takes them unchanged.
166
+ */
167
+ export declare function renderImportSummary(model: ImportModel, digestPath: string | undefined): string;
168
+ /** The digest of an import run, with the same quoting a local digest uses. */
169
+ export declare function renderImportDigest(model: ImportModel, written: readonly DigestCandidate[], generatedAt: string): string;
@@ -0,0 +1,33 @@
1
+ /**
2
+ * The portable identity of a checkout for `ce:connect`: `owner/repo` of its
3
+ * GitHub `origin` remote and the commit its HEAD names. A run record that
4
+ * carries both can be matched to another machine's checkout of the same
5
+ * project after the run's own paths are gone.
6
+ *
7
+ * Reads files under `.git/` only, through the contained reader (no symlink is
8
+ * followed, every read is bounded). No git process and no network is used, and
9
+ * nothing in a remote URL except the validated `owner/repo` is ever returned,
10
+ * so credentials in a URL cannot reach a record. Import rule: node builtins
11
+ * and `connect-evidence.ts` only, because the `ce:connect` helper bundles it.
12
+ * Never throws: anything unreadable, unexpected or not GitHub is absent.
13
+ */
14
+ export interface RepoIdentity {
15
+ /** Lowercase `owner/repo` of the GitHub `origin` remote. */
16
+ readonly repo?: string;
17
+ /** The full hash HEAD names. */
18
+ readonly commit?: string;
19
+ }
20
+ /**
21
+ * `owner/repo` of a GitHub remote URL, lowercase, or nothing. Three forms are
22
+ * read: an https URL, `git@github.com:o/r` and an `ssh://` URL, each with or
23
+ * without `.git` and a trailing slash. Another host, a port, a query, a
24
+ * fragment or a local path is not GitHub here. Userinfo is dropped and never
25
+ * returned.
26
+ */
27
+ export declare function normalizeGithubRemote(url: string): string | undefined;
28
+ /**
29
+ * The repository identity of the checkout whose main root is `mainRoot`. A
30
+ * root whose `.git` is not a real directory (a linked worktree, a submodule, a
31
+ * symlink) has neither field.
32
+ */
33
+ export declare function readRepoIdentity(mainRoot: string): RepoIdentity;