@fro.bot/systematic 3.31.6 → 3.32.1

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,312 @@
1
+ /**
2
+ * The evidence boundary for `ce:connect`: what the helper may read from an
3
+ * allowed project and how it reads it. A bounded, hashed inventory of tracked
4
+ * files; a hardened, allow-listed git runner; contained reads; and a citation
5
+ * checker that says which `path:line` citations still hold.
6
+ *
7
+ * Import rule: node builtins and `connect-config.ts` only. The `ce:connect`
8
+ * helper bundles this module, so it must never import zod, `config.ts` or
9
+ * `config-schema.ts`.
10
+ *
11
+ * Trust: an allowed project is untrusted input. Its git config, its file names
12
+ * and its working tree all come from other people, so:
13
+ * - git runs only the subcommands in `GIT_SUBCOMMANDS`, with the hardening
14
+ * flags before the subcommand, a scrubbed environment, `GIT_OPTIONAL_LOCKS=0`
15
+ * so a read never takes a lock or rewrites the index, literal pathspecs for
16
+ * path arguments, and `--` before every one of them (or paths on stdin,
17
+ * NUL-separated, where the subcommand takes them there);
18
+ * - only the listing's regular files (mode 100644 or 100755) become evidence;
19
+ * symlinks (120000) and submodules (160000) are dropped before any open;
20
+ * - a file is read only through `readContainedFile`, which refuses a path that
21
+ * leaves the root, `lstat`s every ancestor and the final component, opens
22
+ * with `O_NOFOLLOW`, and compares the opened descriptor's device and inode
23
+ * with the `lstat` result, then re-checks the ancestors;
24
+ * - only the main checkout is read; a subdirectory or a linked worktree is
25
+ * refused by the allow-entry resolver.
26
+ *
27
+ * Nothing here writes to a project, runs a project command or reads history.
28
+ */
29
+ import { type AllowEntryMissReason } from './connect-config.js';
30
+ /**
31
+ * The bounds of a run. A run that reaches one is degraded and says so.
32
+ *
33
+ * `maxRulesPerFamily` follows from the Pi delegate's 20-turn cap: a researcher
34
+ * that makes one call per turn needs about three turns to orient and answer,
35
+ * and at most two (a search and a read) per rule, so eight rules fit. A model
36
+ * that batches its calls uses far fewer turns. `maxCandidatesPerBatch` keeps
37
+ * one answer short enough to copy exactly, and `maxFamiliesPerRun` keeps the
38
+ * skill's own context bounded. A test pins every value.
39
+ */
40
+ export declare const CONNECT_BOUNDS: Readonly<{
41
+ /** Eligible files kept per project, corpus files first. */
42
+ maxFilesPerProject: 4000;
43
+ /** Largest file read, hashed or cited. A larger file is skipped. */
44
+ maxFileBytes: number;
45
+ /** Total bytes hashed per project. Reaching it stops the inventory. */
46
+ maxHashedBytesPerProject: number;
47
+ /** Largest `git ls-files` output accepted. */
48
+ maxListingBytes: number;
49
+ /** Path-and-line citations checked per project. */
50
+ maxCitationsPerProject: 500;
51
+ /** Rules a single rule family may hold. */
52
+ maxRulesPerFamily: 8;
53
+ /** Candidates accepted in one family batch. */
54
+ maxCandidatesPerBatch: 5;
55
+ /** Rule families examined in one run. */
56
+ maxFamiliesPerRun: 6;
57
+ }>;
58
+ export type ConnectBounds = {
59
+ readonly [K in keyof typeof CONNECT_BOUNDS]: number;
60
+ };
61
+ /** The only git subcommands the helper runs. */
62
+ export declare const GIT_SUBCOMMANDS: readonly ['ls-files', 'cat-file', 'check-ignore'];
63
+ export type GitSubcommand = (typeof GIT_SUBCOMMANDS)[number];
64
+ /**
65
+ * Config overrides placed before the subcommand. A repository's own config can
66
+ * name an fsmonitor command or a hooks directory that git would run on its
67
+ * behalf; these three settings turn that off for the helper's calls.
68
+ */
69
+ export declare const GIT_HARDENING_ARGS: readonly ['-c', 'core.fsmonitor=false', '-c', 'core.hooksPath=/dev/null', '-c', 'core.untrackedCache=false'];
70
+ /**
71
+ * The full argv after `git`: hardening flags, the subcommand, its options, and
72
+ * then `--` followed by any path arguments. A path that starts with `-` can
73
+ * therefore never be read as an option.
74
+ */
75
+ export declare function buildGitArgv(subcommand: GitSubcommand, args: readonly string[], paths?: readonly string[]): string[];
76
+ /**
77
+ * A fresh environment for git. Nothing the caller exported reaches it except
78
+ * `PATH` and the home and temp locations, so a stray `GIT_DIR`,
79
+ * `GIT_WORK_TREE` or `GIT_EXTERNAL_DIFF` cannot redirect a read.
80
+ * `literalPathspecs` makes git read path arguments as plain names.
81
+ */
82
+ export declare function gitEnvironment(base?: Readonly<Record<string, string | undefined>>, literalPathspecs?: boolean): Record<string, string>;
83
+ export type GitRun = {
84
+ readonly status: 'ok';
85
+ readonly exitCode: number;
86
+ readonly stdout: Buffer;
87
+ }
88
+ /** The subcommand is not in `GIT_SUBCOMMANDS`; git was not started. */
89
+ | {
90
+ readonly status: 'refused';
91
+ } | {
92
+ readonly status: 'failed';
93
+ readonly reason: 'git-unavailable' | 'git-failed' | 'output-too-large';
94
+ };
95
+ export interface GitRunOptions {
96
+ /** The git executable. Defaults to `git` on `PATH`. */
97
+ readonly gitBinary?: string;
98
+ /** Largest stdout accepted, in bytes. */
99
+ readonly maxBytes?: number;
100
+ /** Path arguments, passed after `--`. */
101
+ readonly paths?: readonly string[];
102
+ /** Bytes written to git's stdin. */
103
+ readonly input?: Buffer;
104
+ }
105
+ /**
106
+ * Run one allow-listed git subcommand in `cwd`. The exit code is returned for
107
+ * the caller to read: `check-ignore` exits 1 when nothing matched. Never throws.
108
+ */
109
+ export declare function runGit(cwd: string, subcommand: string, args: readonly string[], options?: GitRunOptions): GitRun;
110
+ /** Why a file was not read. */
111
+ export type ReadFailure =
112
+ /** The path is absolute, empty, malformed or climbs out of the root. */
113
+ 'outside-root'
114
+ /** An ancestor or the final component is a symlink. */
115
+ | 'symlink'
116
+ /** The final component is a directory, FIFO, device or socket. */
117
+ | 'not-regular' | 'missing' | 'too-large' | 'unreadable'
118
+ /** The path changed between the check and the open. */
119
+ | 'changed';
120
+ export type ContainedRead = {
121
+ readonly kind: 'bytes';
122
+ readonly bytes: Buffer;
123
+ readonly sha256: string;
124
+ } | {
125
+ readonly kind: 'refused';
126
+ readonly reason: ReadFailure;
127
+ };
128
+ export interface ContainedReadOptions {
129
+ /** Largest file accepted. Defaults to `CONNECT_BOUNDS.maxFileBytes`. */
130
+ readonly maxBytes?: number;
131
+ /** Runs between the last `lstat` and the open. A test seam for races. */
132
+ readonly beforeOpen?: () => void;
133
+ }
134
+ /**
135
+ * Read a regular file at a root-relative path without following a symlink.
136
+ *
137
+ * 1. The path must be plain and relative, so `..` and absolute paths are
138
+ * refused before the filesystem is touched.
139
+ * 2. Every ancestor and the final component are `lstat`ed. A symlink anywhere,
140
+ * or a final component that is not a regular file, is refused, so a FIFO
141
+ * is never opened.
142
+ * 3. The open uses `O_NOFOLLOW` and `O_NONBLOCK`, and the opened descriptor's
143
+ * device and inode must equal the `lstat` result, so a path swapped after
144
+ * the check fails instead of being read.
145
+ * 4. The ancestors are checked once more after the open, which catches a
146
+ * directory swapped for a symlink to the same file.
147
+ * 5. The read stops one byte past `maxBytes`; the size is never trusted from a
148
+ * `stat`.
149
+ *
150
+ * `root` must be a trusted real path. Never throws.
151
+ */
152
+ export declare function readContainedFile(root: string, rel: string, options?: ContainedReadOptions): ContainedRead;
153
+ export interface CitationInput {
154
+ /** Root-relative path. */
155
+ readonly path: string;
156
+ /** First cited line, 1-based. */
157
+ readonly start: number;
158
+ /** Last cited line, inclusive. */
159
+ readonly end: number;
160
+ /** The name the citing claim says is in the span. */
161
+ readonly symbol?: string;
162
+ }
163
+ export type CitationUncheckedReason = 'no-symbol' | 'invalid-span' | ReadFailure;
164
+ /**
165
+ * What a check established:
166
+ * - `passed`: the symbol is in the cited lines.
167
+ * - `not-in-span`: it is not; `foundElsewhere` says whether it still occurs
168
+ * somewhere else in the file (the code moved) or nowhere (it is gone).
169
+ * - `unchecked`: the check could not run, and the reason says why.
170
+ *
171
+ * A verdict reports whether the citation still holds, not whether the code has
172
+ * stayed put.
173
+ */
174
+ export type CitationVerdict = {
175
+ readonly verdict: 'passed';
176
+ } | {
177
+ readonly verdict: 'not-in-span';
178
+ readonly foundElsewhere: boolean;
179
+ } | {
180
+ readonly verdict: 'unchecked';
181
+ readonly reason: CitationUncheckedReason;
182
+ };
183
+ export interface CheckCitationOptions {
184
+ /** Largest cited file accepted. Defaults to `CONNECT_BOUNDS.maxFileBytes`. */
185
+ readonly maxBytes?: number;
186
+ }
187
+ /**
188
+ * Whether `identifier` occurs in `text` as a whole name: no identifier
189
+ * character directly before or after the match. A dotted chain is matched as
190
+ * one name. `alphaBeta` is not found in `alphaBetaAsync` or `myalphaBeta`.
191
+ */
192
+ export declare function containsIdentifier(text: string, identifier: string): boolean;
193
+ /**
194
+ * Check one citation. The file is read through `readContainedFile`, so a path
195
+ * outside the root, through a symlink, to a FIFO or over the size cap is
196
+ * `unchecked` with the reason, and the file is never opened unsafely.
197
+ */
198
+ export declare function checkCitation(root: string, citation: CitationInput, options?: CheckCitationOptions): CitationVerdict;
199
+ export interface ExtractedCitation {
200
+ readonly path: string;
201
+ readonly start: number;
202
+ readonly end: number;
203
+ /** The first identifier the citing sentence names in backticks. */
204
+ readonly symbol?: string;
205
+ /** 1-based line of the citation in the text. */
206
+ readonly line: number;
207
+ }
208
+ /**
209
+ * The `path.ext:N[-M]` citations in markdown prose, each with the first
210
+ * identifier its sentence names in backticks. Lexical, not a parser. Known
211
+ * limits: URLs, `path:N:M` stack frames, paths with `.`/`..` segments and
212
+ * absolute paths are not citations; fenced blocks are skipped; a comma list of
213
+ * lines reads as its first span; a sentence ends at `.`, `!`, `?` or `;`
214
+ * followed by whitespace, outside backticks.
215
+ */
216
+ export declare function extractCitations(text: string): ExtractedCitation[];
217
+ export interface CitedDocument {
218
+ readonly path: string;
219
+ readonly text: string;
220
+ }
221
+ export interface ProjectCitation {
222
+ readonly document: string;
223
+ readonly line: number;
224
+ readonly citation: Omit<ExtractedCitation, 'line'>;
225
+ readonly result: CitationVerdict;
226
+ }
227
+ export interface ProjectCitationReport {
228
+ /** True when no document holds a path-and-line citation, so none could be checked. */
229
+ readonly unsupported: boolean;
230
+ readonly citations: readonly ProjectCitation[];
231
+ /** True when the citation cap stopped the check. */
232
+ readonly truncated: boolean;
233
+ }
234
+ export interface ProjectCitationOptions {
235
+ readonly bounds?: Partial<ConnectBounds>;
236
+ readonly maxBytes?: number;
237
+ }
238
+ /**
239
+ * Check every `path:line` citation in a project's documents against the
240
+ * project's files. A project whose documents hold none is `unsupported`: the
241
+ * check has nothing to say about it, which is not the same as every citation
242
+ * holding.
243
+ */
244
+ export declare function reportProjectCitations(root: string, documents: readonly CitedDocument[], options?: ProjectCitationOptions): ProjectCitationReport;
245
+ /** What a file is evidence of. The order is the inventory order. */
246
+ export declare const INVENTORY_ROLES: readonly ['learning', 'plan', 'brainstorm', 'workflow', 'config', 'code'];
247
+ export type InventoryRole = (typeof INVENTORY_ROLES)[number];
248
+ export interface InventoryFile {
249
+ readonly path: string;
250
+ readonly role: InventoryRole;
251
+ readonly bytes: number;
252
+ readonly sha256: string;
253
+ }
254
+ export interface SkippedFile {
255
+ readonly path: string;
256
+ readonly reason: ReadFailure | 'unsafe-path-character';
257
+ }
258
+ /**
259
+ * A single quote, a dollar sign or a backtick. The promotion step puts a path
260
+ * in a single-quoted shell word, so a file with one in its name cannot be cited.
261
+ */
262
+ export declare const UNSAFE_PATH_CHARACTER: RegExp;
263
+ export type InventoryResult = {
264
+ readonly status: 'ok';
265
+ /** The verified main repository root, as a realpath. */
266
+ readonly mainRoot: string;
267
+ readonly files: readonly InventoryFile[];
268
+ /** Files listed but not hashed. At most `MAX_LISTED_SKIPS` are named. */
269
+ readonly skipped: readonly SkippedFile[];
270
+ readonly skippedCount: number;
271
+ readonly excluded: {
272
+ readonly symlinks: number;
273
+ readonly submodules: number;
274
+ /** Unmerged entries and modes other than a regular file. */
275
+ readonly unmerged: number;
276
+ /** Tracked files that an ignore rule matches. */
277
+ readonly ignored: number;
278
+ /** Tracked regular files that are not evidence. */
279
+ readonly ineligible: number;
280
+ };
281
+ readonly truncated: {
282
+ /** The file-count cap dropped eligible files. */
283
+ readonly files: boolean;
284
+ /** The hashing cap stopped the inventory. */
285
+ readonly hashCap: boolean;
286
+ };
287
+ }
288
+ /** The entry is not an allowed main checkout; `reason` is the allow-entry reason. */
289
+ | {
290
+ readonly status: 'unmatched';
291
+ readonly reason: AllowEntryMissReason;
292
+ } | {
293
+ readonly status: 'failed';
294
+ readonly reason: 'git-unavailable' | 'git-failed' | 'listing-too-large' | 'listing-malformed';
295
+ };
296
+ export interface InventoryOptions {
297
+ readonly bounds?: Partial<ConnectBounds>;
298
+ readonly gitBinary?: string;
299
+ }
300
+ /**
301
+ * Inventory the tracked, regular, eligible files of one allowed project.
302
+ *
303
+ * `entry` goes through `resolveAllowEntry`, so only a main checkout is read.
304
+ * Git lists the index once (`ls-files -z --cached --stage`); symlinks and
305
+ * submodules are dropped from the listing before any file is opened. Eligible
306
+ * files are corpus documents, workflows, config and code, kept in role order
307
+ * up to the file cap, then filtered through `check-ignore`. Each file is read
308
+ * through `readContainedFile` and hashed until the hashing cap. A cap sets its
309
+ * `truncated` flag; a file that cannot be read is named in `skipped`. Nothing
310
+ * is written to the project. Never throws.
311
+ */
312
+ export declare function inventoryProject(entry: string, options?: InventoryOptions): InventoryResult;