@venn-lang/contracts 0.1.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.
Files changed (116) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +254 -0
  3. package/dist/index.d.ts +620 -0
  4. package/dist/index.d.ts.map +1 -0
  5. package/dist/index.js +1342 -0
  6. package/dist/index.js.map +1 -0
  7. package/dist/node.d.mts +287 -0
  8. package/dist/node.d.mts.map +1 -0
  9. package/dist/node.mjs +387 -0
  10. package/dist/node.mjs.map +1 -0
  11. package/dist/signal-source.types-BI3TYaCi.d.ts +317 -0
  12. package/dist/signal-source.types-BI3TYaCi.d.ts.map +1 -0
  13. package/dist/testing.d.ts +84 -0
  14. package/dist/testing.d.ts.map +1 -0
  15. package/dist/testing.js +276 -0
  16. package/dist/testing.js.map +1 -0
  17. package/package.json +77 -0
  18. package/src/capabilities/host-capability.ts +18 -0
  19. package/src/capabilities/index.ts +2 -0
  20. package/src/conformance/expect-venn-error.ts +18 -0
  21. package/src/conformance/harness.types.ts +14 -0
  22. package/src/conformance/index.ts +2 -0
  23. package/src/dotenv/dotenv-files.ts +30 -0
  24. package/src/dotenv/index.ts +2 -0
  25. package/src/dotenv/parse-dotenv.ts +34 -0
  26. package/src/errors/contract-codes.ts +37 -0
  27. package/src/errors/index.ts +7 -0
  28. package/src/errors/venn-error.ts +20 -0
  29. package/src/host/create-host.ts +16 -0
  30. package/src/host/create-node-host.ts +29 -0
  31. package/src/host/create-test-host.ts +28 -0
  32. package/src/host/create-worker-host.ts +32 -0
  33. package/src/host/host.types.ts +26 -0
  34. package/src/host/index.ts +5 -0
  35. package/src/host/unavailable.ts +23 -0
  36. package/src/index.ts +10 -0
  37. package/src/logger/console-logger.ts +12 -0
  38. package/src/logger/index.ts +3 -0
  39. package/src/logger/logger.types.ts +18 -0
  40. package/src/logger/memory-logger.ts +12 -0
  41. package/src/node.ts +8 -0
  42. package/src/port/assert-capabilities.ts +18 -0
  43. package/src/port/assert-port-shape.ts +18 -0
  44. package/src/port/bind-port.ts +28 -0
  45. package/src/port/index.ts +5 -0
  46. package/src/port/missing-capabilities.ts +14 -0
  47. package/src/port/port.types.ts +36 -0
  48. package/src/ports/clock/clock.port.ts +15 -0
  49. package/src/ports/clock/clock.types.ts +17 -0
  50. package/src/ports/clock/index.ts +4 -0
  51. package/src/ports/clock/system-clock.ts +9 -0
  52. package/src/ports/clock/virtual-clock.ts +22 -0
  53. package/src/ports/console/console.port.ts +13 -0
  54. package/src/ports/console/console.types.ts +17 -0
  55. package/src/ports/console/index.ts +3 -0
  56. package/src/ports/console/memory-console.ts +36 -0
  57. package/src/ports/console/node-console.ts +80 -0
  58. package/src/ports/file-system/file-system.errors.ts +10 -0
  59. package/src/ports/file-system/file-system.port.ts +12 -0
  60. package/src/ports/file-system/file-system.types.ts +27 -0
  61. package/src/ports/file-system/index.ts +6 -0
  62. package/src/ports/file-system/memory-fs.ts +46 -0
  63. package/src/ports/file-system/node-fs.ts +93 -0
  64. package/src/ports/index.ts +9 -0
  65. package/src/ports/lock-provider/fake-lock.ts +6 -0
  66. package/src/ports/lock-provider/in-process-lock.ts +26 -0
  67. package/src/ports/lock-provider/index.ts +4 -0
  68. package/src/ports/lock-provider/lock-provider.port.ts +16 -0
  69. package/src/ports/lock-provider/lock-provider.types.ts +8 -0
  70. package/src/ports/manifest-provider/default-manifest.ts +31 -0
  71. package/src/ports/manifest-provider/edit/edit-dependency.ts +82 -0
  72. package/src/ports/manifest-provider/edit/index.ts +7 -0
  73. package/src/ports/manifest-provider/edit/table-span.ts +39 -0
  74. package/src/ports/manifest-provider/index.ts +31 -0
  75. package/src/ports/manifest-provider/manifest.port.ts +16 -0
  76. package/src/ports/manifest-provider/manifest.types.ts +54 -0
  77. package/src/ports/manifest-provider/memory-manifest.ts +14 -0
  78. package/src/ports/manifest-provider/project.types.ts +94 -0
  79. package/src/ports/manifest-provider/read/index.ts +15 -0
  80. package/src/ports/manifest-provider/read/read-dependencies.ts +27 -0
  81. package/src/ports/manifest-provider/read/read-package.ts +32 -0
  82. package/src/ports/manifest-provider/read/read-profiles.ts +32 -0
  83. package/src/ports/manifest-provider/read/read-targets.ts +37 -0
  84. package/src/ports/manifest-provider/read/read-tooling.ts +15 -0
  85. package/src/ports/manifest-provider/read/read-workspace.ts +22 -0
  86. package/src/ports/manifest-provider/read/scalars.ts +35 -0
  87. package/src/ports/manifest-provider/read-run-settings.ts +38 -0
  88. package/src/ports/manifest-provider/resolve-alias.ts +22 -0
  89. package/src/ports/manifest-provider/toml/index.ts +3 -0
  90. package/src/ports/manifest-provider/toml/parse-toml.ts +52 -0
  91. package/src/ports/manifest-provider/toml/read-value.ts +104 -0
  92. package/src/ports/manifest-provider/toml/sections.ts +39 -0
  93. package/src/ports/manifest-provider/toml-docs.ts +27 -0
  94. package/src/ports/manifest-provider/toml-manifest.ts +41 -0
  95. package/src/ports/process-provider/fake-process.ts +32 -0
  96. package/src/ports/process-provider/index.ts +10 -0
  97. package/src/ports/process-provider/node-spawn.ts +52 -0
  98. package/src/ports/process-provider/process-provider.port.ts +13 -0
  99. package/src/ports/process-provider/process-provider.types.ts +47 -0
  100. package/src/ports/random/fixed-random.ts +10 -0
  101. package/src/ports/random/index.ts +4 -0
  102. package/src/ports/random/random.port.ts +13 -0
  103. package/src/ports/random/random.types.ts +10 -0
  104. package/src/ports/random/seeded-random.ts +19 -0
  105. package/src/ports/secret-provider/env-secrets.ts +19 -0
  106. package/src/ports/secret-provider/index.ts +6 -0
  107. package/src/ports/secret-provider/memory-secrets.ts +15 -0
  108. package/src/ports/secret-provider/secret-provider.port.ts +13 -0
  109. package/src/ports/secret-provider/secret-provider.types.ts +17 -0
  110. package/src/ports/secret-provider/secret.ts +17 -0
  111. package/src/ports/signal-source/fake-signals.ts +44 -0
  112. package/src/ports/signal-source/index.ts +11 -0
  113. package/src/ports/signal-source/node-signals.ts +33 -0
  114. package/src/ports/signal-source/signal-source.port.ts +13 -0
  115. package/src/ports/signal-source/signal-source.types.ts +24 -0
  116. package/src/testing.ts +16 -0
@@ -0,0 +1,620 @@
1
+ import { A as DirEntry, C as Random, D as SpawnArgs, E as ProcessResult, M as Clock, N as VirtualClock, O as LockProvider, S as SecretProvider, T as ProcessProvider, _ as KnownSecret, a as Unsubscribe, c as ManifestProvider, d as PackageInfo, f as PackageManagerName, g as WorkspaceSettings, h as ToolingSettings, i as SystemSignal, j as FileSystem, k as Release, l as BuildTarget, m as TargetKind, n as SignalHandler, o as FormatSettings, p as Profile, r as SignalSource, s as Manifest, t as ALL_SIGNALS, u as Dependency, w as ProcessHandle, x as Secret } from "./signal-source.types-BI3TYaCi.js";
2
+ //#region src/capabilities/host-capability.d.ts
3
+ /**
4
+ * Every capability a Host may expose. A port or plugin declares which it
5
+ * requires, a host advertises which it provides, and negotiation compares the
6
+ * two before anything binds.
7
+ */
8
+ declare const ALL_CAPABILITIES: readonly ["fs", "process", "net", "clock", "random", "secrets", "log", "io"];
9
+ /** One capability name, drawn from {@link ALL_CAPABILITIES}. */
10
+ type HostCapability = (typeof ALL_CAPABILITIES)[number];
11
+ //#endregion
12
+ //#region src/dotenv/dotenv-files.d.ts
13
+ /**
14
+ * The dotenv files read when `venn.toml` does not name its own.
15
+ *
16
+ * The order is the precedence, lowest first: what everyone shares, then what
17
+ * this environment adds, then what this machine keeps to itself. The `.local`
18
+ * ones are what a `.gitignore` is for.
19
+ */
20
+ declare const DOTENV_CONVENTION: readonly string[];
21
+ /**
22
+ * Which files to read, in order, for one environment.
23
+ *
24
+ * The runner and the editor both ask this, so they cannot disagree about where
25
+ * a value lives.
26
+ *
27
+ * @param args.configured - `[env] files` from `venn.toml`. Empty or absent
28
+ * falls back to {@link DOTENV_CONVENTION}.
29
+ * @param args.name - the selected environment, substituted for `${name}`.
30
+ */
31
+ declare function dotenvFiles(args: {
32
+ configured?: readonly string[];
33
+ name: string;
34
+ }): string[];
35
+ //#endregion
36
+ //#region src/dotenv/parse-dotenv.d.ts
37
+ /**
38
+ * Read a `.env` file: `NAME=value`, one per line.
39
+ *
40
+ * Deliberately small. It understands comments, blank lines, an `export `
41
+ * prefix, and quotes around a value that needs them. No variable expansion:
42
+ * `${OTHER}` is left alone, because Venn already interpolates in its own
43
+ * strings and two syntaxes for one idea is how people get surprised.
44
+ *
45
+ * @returns every name found, later lines winning over earlier ones.
46
+ */
47
+ declare function parseDotenv(content: string): Record<string, string>;
48
+ //#endregion
49
+ //#region src/errors/venn-error.d.ts
50
+ /** Structured, serializable, redaction-safe detail attached to a {@link VennError}. */
51
+ type VennErrorDetail = Readonly<Record<string, unknown>>;
52
+ /**
53
+ * The single error type that crosses a contracts boundary.
54
+ *
55
+ * Every failure carries a stable `VNxxxx` code, so conformance suites assert on
56
+ * `.code` and never on prose. Messages stay free to improve.
57
+ */
58
+ declare class VennError extends Error {
59
+ readonly code: string;
60
+ readonly detail: VennErrorDetail | undefined;
61
+ constructor(args: {
62
+ code: string;
63
+ message: string;
64
+ detail?: VennErrorDetail;
65
+ });
66
+ }
67
+ //#endregion
68
+ //#region src/errors/contract-codes.d.ts
69
+ /** VN2010: a port requires capabilities the host does not provide. */
70
+ declare function hostMissingCapability(args: {
71
+ portId: string;
72
+ missing: readonly HostCapability[];
73
+ present: readonly HostCapability[];
74
+ }): VennError;
75
+ /** VN2011: an implementation is missing one or more methods the port declares. */
76
+ declare function portShapeMismatch(args: {
77
+ portId: string;
78
+ missing: readonly string[];
79
+ }): VennError;
80
+ /** VN2012: code reached a capability the host declared unavailable. */
81
+ declare function capabilityUnavailable(args: {
82
+ capability: HostCapability;
83
+ method: string;
84
+ }): VennError;
85
+ //#endregion
86
+ //#region src/logger/logger.types.d.ts
87
+ /** How loudly one entry asks to be heard. */
88
+ type LogLevel = "debug" | "info" | "warn" | "error";
89
+ /** One line of log, as data rather than as formatted text. */
90
+ interface LogEntry {
91
+ readonly level: LogLevel;
92
+ readonly message: string;
93
+ }
94
+ /** The minimal structured logger a host exposes. */
95
+ interface Logger {
96
+ log(entry: LogEntry): void;
97
+ }
98
+ /** A {@link Logger} that also retains what it was given, for assertions. */
99
+ interface MemoryLogger extends Logger {
100
+ readonly entries: readonly LogEntry[];
101
+ }
102
+ //#endregion
103
+ //#region src/logger/console-logger.d.ts
104
+ /** Logger backed by the global console, so it works in a Worker and in Node. */
105
+ declare function createConsoleLogger(): Logger;
106
+ //#endregion
107
+ //#region src/logger/memory-logger.d.ts
108
+ /** The double: keeps every entry in `entries` instead of printing it. */
109
+ declare function createMemoryLogger(): MemoryLogger;
110
+ //#endregion
111
+ //#region src/port/port.types.d.ts
112
+ /**
113
+ * A typed contract carrying at least two implementations, one real and one
114
+ * double.
115
+ *
116
+ * Deliberately not a Zod schema: in Zod 4 `z.function` is a factory rather than
117
+ * a validatable type, so a port's function shape cannot be expressed as data.
118
+ * `methods` buys a compile-time check (each entry must be a key of `T`) and a
119
+ * load-time one (`typeof` per method); the behavioural guarantee is the
120
+ * conformance suite.
121
+ *
122
+ * @typeParam T - the interface the implementation must satisfy.
123
+ */
124
+ interface Port<T> {
125
+ /** Stable identity, e.g. "venn.port.filesystem". */
126
+ readonly id: string;
127
+ /** Version of the contract, not of the package. Removing a method bumps it. */
128
+ readonly version: number;
129
+ /** Capabilities negotiated against `Host.caps` before binding. */
130
+ readonly requires: readonly HostCapability[];
131
+ /** Methods an implementation must provide. Each must be a key of `T`. */
132
+ readonly methods: readonly (keyof T & string)[];
133
+ }
134
+ /**
135
+ * A `Port<T>` with its element type erased. Every `Port<T>` is assignable to it
136
+ * (its `methods` widen to `string[]`), so a heterogeneous collection of ports,
137
+ * such as the runtime's binding table, types without variance friction.
138
+ */
139
+ type AnyPort = {
140
+ readonly id: string;
141
+ readonly version: number;
142
+ readonly requires: readonly HostCapability[];
143
+ readonly methods: readonly string[];
144
+ };
145
+ //#endregion
146
+ //#region src/port/assert-capabilities.d.ts
147
+ /**
148
+ * Checks the host against what the port requires.
149
+ *
150
+ * @throws VennError VN2010 when a required capability is absent.
151
+ */
152
+ declare function assertCapabilities<T>(args: {
153
+ port: Port<T>;
154
+ caps: readonly HostCapability[];
155
+ }): void;
156
+ //#endregion
157
+ //#region src/port/assert-port-shape.d.ts
158
+ /**
159
+ * Checks the implementation against the methods the port declares.
160
+ *
161
+ * @throws VennError VN2011 when a declared method is missing or is not callable.
162
+ */
163
+ declare function assertPortShape<T>(args: {
164
+ port: Port<T>;
165
+ impl: unknown;
166
+ }): void;
167
+ //#endregion
168
+ //#region src/port/bind-port.d.ts
169
+ /**
170
+ * The single loader entry. Negotiates capabilities, checks the implementation's
171
+ * shape, then hands it back typed as `T`.
172
+ *
173
+ * Both checks run before anything is bound, so a mismatch is reported at start
174
+ * up rather than as a `TypeError` in the middle of a test.
175
+ *
176
+ * @param args.port - the descriptor to bind against.
177
+ * @param args.impl - the candidate implementation, untrusted.
178
+ * @param args.caps - the capabilities the host advertises.
179
+ * @returns `args.impl` typed as `T`.
180
+ * @throws VennError VN2010 when the host lacks a required capability, VN2011
181
+ * when the implementation is missing a declared method.
182
+ */
183
+ declare function bindPort<T>(args: {
184
+ port: Port<T>;
185
+ impl: unknown;
186
+ caps: readonly HostCapability[];
187
+ }): T;
188
+ //#endregion
189
+ //#region src/port/missing-capabilities.d.ts
190
+ /**
191
+ * The gap between what is required and what the host offers.
192
+ *
193
+ * @returns the required capabilities absent from `caps`, in the order required.
194
+ */
195
+ declare function missingCapabilities(args: {
196
+ requires: readonly HostCapability[];
197
+ caps: readonly HostCapability[];
198
+ }): readonly HostCapability[];
199
+ //#endregion
200
+ //#region src/ports/clock/clock.port.d.ts
201
+ /**
202
+ * The {@link Clock} contract. Implementations: `system-clock`, `virtual-clock`.
203
+ *
204
+ * `advance` and `setTime` are absent on purpose: they are how a test drives a
205
+ * virtual clock, not something a caller of the port may reach for.
206
+ */
207
+ declare const ClockPort: Port<Clock>;
208
+ //#endregion
209
+ //#region src/ports/clock/system-clock.d.ts
210
+ /** Wall-clock time, on the `Date` and `setTimeout` globals. */
211
+ declare function createSystemClock(): Clock;
212
+ //#endregion
213
+ //#region src/ports/clock/virtual-clock.d.ts
214
+ /**
215
+ * The double. `sleep` advances internal time and resolves at once, so a test
216
+ * about a timeout costs nothing to run.
217
+ *
218
+ * @param args.start - the epoch this clock begins at. Defaults to 0.
219
+ */
220
+ declare function createVirtualClock(args?: {
221
+ start?: number;
222
+ }): VirtualClock;
223
+ //#endregion
224
+ //#region src/ports/file-system/file-system.errors.d.ts
225
+ /** VN8010: a read or a remove targeted a path that does not exist. */
226
+ declare function fsNotFound(args: {
227
+ path: string;
228
+ }): VennError;
229
+ //#endregion
230
+ //#region src/ports/file-system/file-system.port.d.ts
231
+ /**
232
+ * The {@link FileSystem} contract. Implementations: `node-fs`, `memory-fs`.
233
+ */
234
+ declare const FileSystemPort: Port<FileSystem>;
235
+ //#endregion
236
+ //#region src/ports/file-system/memory-fs.d.ts
237
+ /** The double: byte-exact, isolated per instance, no disk. */
238
+ declare function createMemoryFs(): FileSystem;
239
+ //#endregion
240
+ //#region src/ports/lock-provider/fake-lock.d.ts
241
+ /** The double: grants immediately and serialises nothing. */
242
+ declare function createFakeLock(): LockProvider;
243
+ //#endregion
244
+ //#region src/ports/lock-provider/in-process-lock.d.ts
245
+ /**
246
+ * The real one: a chained-promise mutex per name. Waiters are served in the
247
+ * order they asked, and the chain lives only in this process.
248
+ */
249
+ declare function createInProcessLock(): LockProvider;
250
+ //#endregion
251
+ //#region src/ports/lock-provider/lock-provider.port.d.ts
252
+ /**
253
+ * The {@link LockProvider} contract. Implementations: `in-process-lock`,
254
+ * `fake-lock`.
255
+ *
256
+ * Requires nothing: a mutex is bookkeeping, so it binds even on a host with no
257
+ * capabilities at all.
258
+ */
259
+ declare const LockProviderPort: Port<LockProvider>;
260
+ //#endregion
261
+ //#region src/ports/process-provider/fake-process.d.ts
262
+ /**
263
+ * The double: a scripted process that never touches the OS.
264
+ *
265
+ * Output is streamed before the wait resolves, exactly as the real one does it,
266
+ * so a caller that shows progress is exercised here and not only against a real
267
+ * machine.
268
+ *
269
+ * @param args.exitCode - what every run reports. Defaults to 0.
270
+ * @param args.output - what every run writes. Defaults to nothing.
271
+ */
272
+ declare function createFakeProcess(args?: {
273
+ exitCode?: number;
274
+ output?: string;
275
+ }): ProcessProvider;
276
+ //#endregion
277
+ //#region src/ports/process-provider/process-provider.port.d.ts
278
+ /**
279
+ * The {@link ProcessProvider} contract. Implementations: `node-spawn`,
280
+ * `fake-process`.
281
+ */
282
+ declare const ProcessProviderPort: Port<ProcessProvider>;
283
+ //#endregion
284
+ //#region src/ports/random/fixed-random.d.ts
285
+ /** The double: always the same value, and always `min` from `int`. */
286
+ declare function createFixedRandom(args?: {
287
+ value?: number;
288
+ }): Random;
289
+ //#endregion
290
+ //#region src/ports/random/random.port.d.ts
291
+ /**
292
+ * The {@link Random} contract. Implementations: `seeded-random`,
293
+ * `fixed-random`.
294
+ */
295
+ declare const RandomPort: Port<Random>;
296
+ //#endregion
297
+ //#region src/ports/random/seeded-random.d.ts
298
+ /**
299
+ * The real one: a mulberry32 PRNG, seeded once per worker. Same seed, same
300
+ * sequence, so a run reproduces.
301
+ */
302
+ declare function createSeededRandom(args: {
303
+ seed: number;
304
+ }): Random;
305
+ //#endregion
306
+ //#region src/ports/secret-provider/env-secrets.d.ts
307
+ /**
308
+ * The real one: secrets from `process.env`.
309
+ *
310
+ * The `process` global is probed rather than imported, so this file stays
311
+ * neutral and reports every name as absent in a Worker instead of throwing.
312
+ */
313
+ declare function createEnvSecrets(): SecretProvider;
314
+ //#endregion
315
+ //#region src/ports/secret-provider/memory-secrets.d.ts
316
+ /**
317
+ * The double: secrets given by name, wrapped so they still redact.
318
+ *
319
+ * @param args.values - the raw values, keyed by secret name.
320
+ */
321
+ declare function createMemorySecrets(args: {
322
+ values: Record<string, string>;
323
+ }): SecretProvider;
324
+ //#endregion
325
+ //#region src/ports/secret-provider/secret.d.ts
326
+ /** What every serialised secret collapses to. */
327
+ declare const REDACTED = "‹redigido›";
328
+ /**
329
+ * Wrap a raw value so it cannot leak through `toString` or `toJSON`.
330
+ *
331
+ * @param args.reveal - the raw value, reachable only via `Secret.reveal()`.
332
+ */
333
+ declare function makeSecret(args: {
334
+ reveal: string;
335
+ }): Secret;
336
+ //#endregion
337
+ //#region src/ports/secret-provider/secret-provider.port.d.ts
338
+ /**
339
+ * The {@link SecretProvider} contract. Implementations: `env-secrets`,
340
+ * `memory-secrets`.
341
+ */
342
+ declare const SecretProviderPort: Port<SecretProvider>;
343
+ //#endregion
344
+ //#region src/host/host.types.d.ts
345
+ /**
346
+ * Everything the core is allowed to reach: assembled at the entry point, then
347
+ * passed inward. The core receives this and imports nothing else.
348
+ *
349
+ * Three assemblers build one: `createHost.worker`, `createHost.test`, and
350
+ * `createNodeHost` from `@venn-lang/contracts/node`.
351
+ */
352
+ interface Host {
353
+ readonly fs: FileSystem;
354
+ readonly proc: ProcessProvider;
355
+ readonly clock: Clock;
356
+ readonly random: Random;
357
+ readonly secrets: SecretProvider;
358
+ readonly log: Logger;
359
+ readonly lock: LockProvider;
360
+ readonly caps: readonly HostCapability[];
361
+ }
362
+ //#endregion
363
+ //#region src/host/create-test-host.d.ts
364
+ /**
365
+ * A host of doubles, every capability granted. The default for tests.
366
+ *
367
+ * @param overrides - replaces individual members, e.g. a real clock.
368
+ */
369
+ declare function createTestHost(overrides?: Partial<Host>): Host;
370
+ //#endregion
371
+ //#region src/host/create-worker-host.d.ts
372
+ /**
373
+ * Host for a Web Worker: an in-memory file system, no `process`, no `net`.
374
+ *
375
+ * `proc` is a stand-in whose every method throws VN2012, so reaching for a
376
+ * subprocess in the editor fails with a diagnostic instead of a `TypeError`.
377
+ */
378
+ declare function createWorkerHost(): Host;
379
+ //#endregion
380
+ //#region src/host/create-host.d.ts
381
+ /**
382
+ * The neutral host assemblers.
383
+ *
384
+ * `node` is deliberately absent: it pulls `node:*`, so it lives behind
385
+ * `@venn-lang/contracts/node` as `createNodeHost` and this entry stays Worker-safe.
386
+ */
387
+ declare const createHost: {
388
+ readonly worker: typeof createWorkerHost;
389
+ readonly test: typeof createTestHost;
390
+ };
391
+ //#endregion
392
+ //#region src/host/unavailable.d.ts
393
+ /**
394
+ * A stand-in for a port the host cannot provide, such as `process` in a Worker.
395
+ *
396
+ * @param args.capability - the capability the host lacks, named in the error.
397
+ * @param args.methods - the port's declared methods, usually `SomePort.methods`.
398
+ * @returns an object shaped like `T` whose every method throws VN2012 when
399
+ * called, rather than failing as a `TypeError` mid-run.
400
+ */
401
+ declare function unavailable<T>(args: {
402
+ capability: HostCapability;
403
+ methods: readonly string[];
404
+ }): T;
405
+ //#endregion
406
+ //#region src/ports/console/console.types.d.ts
407
+ /**
408
+ * The program's console: standard streams and process arguments.
409
+ *
410
+ * Everything a script needs to talk to the outside world without knowing
411
+ * whether it runs on Node, in a test, or in a browser worker. The host supplies
412
+ * the wiring.
413
+ */
414
+ interface Console {
415
+ /** Write to standard output, exactly as given (no trailing newline). */
416
+ write(text: string): void;
417
+ /** Write to standard error. */
418
+ writeError(text: string): void;
419
+ /** Read the next line from standard input, or null at end of input. */
420
+ readLine(): Promise<string | null>;
421
+ /** The command-line arguments passed after the script path. */
422
+ args(): readonly string[];
423
+ }
424
+ //#endregion
425
+ //#region src/ports/console/console.port.d.ts
426
+ /**
427
+ * The {@link Console} contract. Implementations: `node-console`,
428
+ * `memory-console`.
429
+ */
430
+ declare const ConsolePort: Port<Console>;
431
+ //#endregion
432
+ //#region src/ports/console/memory-console.d.ts
433
+ /** A {@link Console} that keeps its transcript instead of printing it. */
434
+ interface MemoryConsole extends Console {
435
+ readonly out: string;
436
+ readonly err: string;
437
+ }
438
+ /**
439
+ * The double: records what was written, reads from a scripted input.
440
+ *
441
+ * @param args.input - the lines `readLine` hands back, in order.
442
+ * @param args.argv - what `args()` reports.
443
+ */
444
+ declare function createMemoryConsole(args?: {
445
+ input?: readonly string[];
446
+ argv?: readonly string[];
447
+ }): MemoryConsole;
448
+ //#endregion
449
+ //#region src/ports/manifest-provider/default-manifest.d.ts
450
+ /**
451
+ * A manifest with nothing declared: what a project without a `venn.toml` is.
452
+ *
453
+ * The one place stating what a project gets for saying nothing at all, so a
454
+ * caller who wants one field need not spell the other dozen.
455
+ *
456
+ * @param overrides - fields to state explicitly. `name` and `version` fall back
457
+ * to `[package]` before falling back to the defaults.
458
+ */
459
+ declare function defaultManifest(overrides?: Partial<Manifest>): Manifest;
460
+ //#endregion
461
+ //#region src/ports/manifest-provider/edit/edit-dependency.d.ts
462
+ /** What to change, and in which table. */
463
+ interface DependencyEdit {
464
+ /** The manifest as written. */
465
+ text: string;
466
+ name: string;
467
+ /** Defaults to {@link DEPENDENCIES}. Pass `"dev-dependencies"` for the other. */
468
+ table?: string;
469
+ }
470
+ /** The table an edit touches unless told otherwise. */
471
+ declare const DEPENDENCIES = "dependencies";
472
+ /**
473
+ * The manifest with one dependency written in, everything else untouched.
474
+ *
475
+ * Entries are kept in name order, so two people adding two packages produce two
476
+ * one-line diffs rather than a conflict. A name already there is replaced where
477
+ * it stands, because an upgrade should not move the line.
478
+ *
479
+ * @returns the whole manifest as text. A missing table is appended at the end.
480
+ */
481
+ declare function addDependency(args: DependencyEdit & {
482
+ version: string;
483
+ }): string;
484
+ /**
485
+ * The manifest without that dependency.
486
+ *
487
+ * @returns the text unchanged when the name is not there: absent is already the
488
+ * wanted state.
489
+ */
490
+ declare function removeDependency(args: DependencyEdit): string;
491
+ //#endregion
492
+ //#region src/ports/manifest-provider/manifest.port.d.ts
493
+ /**
494
+ * The {@link ManifestProvider} contract. Implementations: `toml-manifest`,
495
+ * `memory-manifest`.
496
+ *
497
+ * Requires nothing: reading the file is the caller's job, and what arrives here
498
+ * is already text.
499
+ */
500
+ declare const ManifestProviderPort: Port<ManifestProvider>;
501
+ //#endregion
502
+ //#region src/ports/manifest-provider/memory-manifest.d.ts
503
+ /**
504
+ * The double: a preset manifest, with no file involved.
505
+ *
506
+ * Takes only what the caller cares about. The rest is what a project that
507
+ * declared nothing would get, which is exactly what the real provider gives a
508
+ * `venn.toml` silent on those tables.
509
+ */
510
+ declare function createMemoryManifest(args: {
511
+ manifest: Partial<Manifest>;
512
+ }): ManifestProvider;
513
+ //#endregion
514
+ //#region src/ports/manifest-provider/read/read-package.d.ts
515
+ /**
516
+ * The same table, reduced to what a member may inherit from its workspace.
517
+ *
518
+ * A name is never inherited, being the one thing that must differ between two
519
+ * members, so `[workspace.package]` carrying one is read as carrying none.
520
+ */
521
+ declare function readInheritable(data: Record<string, unknown>): Partial<PackageInfo>;
522
+ //#endregion
523
+ //#region src/ports/manifest-provider/read/read-profiles.d.ts
524
+ /**
525
+ * What each build is for, and what that costs.
526
+ *
527
+ * `dev` reports what it finds and carries on, because a project being worked on
528
+ * is half-written most of the time. `release` refuses to build over a problem.
529
+ * Neither has to be written in a manifest for the defaults to apply.
530
+ */
531
+ declare const DEFAULT_PROFILES: Readonly<Record<string, Profile>>;
532
+ //#endregion
533
+ //#region src/ports/manifest-provider/read/read-targets.d.ts
534
+ /** Where a `lib` target starts when the manifest does not say. */
535
+ declare const LIB_ROOT = "src/lib.vn";
536
+ /** Where the default `bin` target starts when the manifest does not say. */
537
+ declare const MAIN_ROOT = "src/main.vn";
538
+ /** Where additional `bin` targets are looked for by convention. */
539
+ declare const BIN_DIR = "src/bin";
540
+ //#endregion
541
+ //#region src/ports/manifest-provider/resolve-alias.d.ts
542
+ /** Where a `#alias/…` specifier points. */
543
+ interface AliasTarget {
544
+ /** The directory `[paths]` maps the alias to. */
545
+ dir: string;
546
+ /** What followed the alias, with the separating slash removed. */
547
+ rest: string;
548
+ }
549
+ /**
550
+ * Split a `#alias/rest` import specifier against `[paths]` from `venn.toml`.
551
+ *
552
+ * @returns undefined when the specifier names no configured alias, which the
553
+ * caller reads as a relative or bare path.
554
+ */
555
+ declare function resolveAlias(args: {
556
+ spec: string;
557
+ paths: Record<string, string>;
558
+ }): AliasTarget | undefined;
559
+ //#endregion
560
+ //#region src/ports/manifest-provider/toml/parse-toml.d.ts
561
+ /**
562
+ * A TOML reader for `venn.toml`: sections, nested `[a.b]`, arrays of tables
563
+ * (`[[bin]]`), `key = value`, strings, numbers, bools, arrays and inline tables.
564
+ *
565
+ * Not a full TOML parser. No dates, no multi-line strings, no dotted keys.
566
+ * `venn.toml` is our own format, so the subset is a decision rather than a
567
+ * shortfall.
568
+ *
569
+ * @returns the root table. Malformed lines are skipped, never thrown on.
570
+ */
571
+ declare function parseToml(content: string): Record<string, unknown>;
572
+ //#endregion
573
+ //#region src/ports/manifest-provider/toml-docs.d.ts
574
+ /**
575
+ * The comment block written directly above a key, read as that key's
576
+ * documentation. The same idea as `##` above a declaration in a `.vn`.
577
+ *
578
+ * A blank line breaks the block, so a comment separated from a key belongs to
579
+ * nobody and is never attributed to the next one down.
580
+ *
581
+ * @returns documentation keyed by the key it sits above.
582
+ */
583
+ declare function tomlDocs(content: string): Record<string, string>;
584
+ //#endregion
585
+ //#region src/ports/manifest-provider/toml-manifest.d.ts
586
+ /**
587
+ * The real one: parse `venn.toml` into a {@link Manifest}.
588
+ *
589
+ * Parsing happens once, at construction, so repeated `load()` calls are free
590
+ * and always agree.
591
+ *
592
+ * @param args.content - the manifest as written.
593
+ */
594
+ declare function createTomlManifest(args: {
595
+ content: string;
596
+ }): ManifestProvider;
597
+ //#endregion
598
+ //#region src/ports/signal-source/fake-signals.d.ts
599
+ /** A {@link SignalSource} with the bell a test rings. */
600
+ interface FakeSignals extends SignalSource {
601
+ /** Deliver `signal` to everyone still listening for it. */
602
+ raise(signal: SystemSignal): void;
603
+ /** Which signals are currently being listened for, for assertions. */
604
+ readonly listening: readonly SystemSignal[];
605
+ }
606
+ /**
607
+ * The double: a signal arrives because a test said so. No process, no operating
608
+ * system, no risk of stopping the test runner along with the code under test.
609
+ */
610
+ declare function createFakeSignals(): FakeSignals;
611
+ //#endregion
612
+ //#region src/ports/signal-source/signal-source.port.d.ts
613
+ /**
614
+ * The {@link SignalSource} contract. Implementations: `node-signals`,
615
+ * `fake-signals`.
616
+ */
617
+ declare const SignalSourcePort: Port<SignalSource>;
618
+ //#endregion
619
+ export { ALL_CAPABILITIES, ALL_SIGNALS, type AliasTarget, type AnyPort, BIN_DIR, type BuildTarget, type Clock, ClockPort, type Console, ConsolePort, DEFAULT_PROFILES, DEPENDENCIES, DOTENV_CONVENTION, type Dependency, type DependencyEdit, type DirEntry, type FakeSignals, type FileSystem, FileSystemPort, type FormatSettings, type Host, type HostCapability, type KnownSecret, LIB_ROOT, type LockProvider, LockProviderPort, type LogEntry, type LogLevel, type Logger, MAIN_ROOT, type Manifest, type ManifestProvider, ManifestProviderPort, type MemoryConsole, type MemoryLogger, type PackageInfo, type PackageManagerName, type Port, type ProcessHandle, type ProcessProvider, ProcessProviderPort, type ProcessResult, type Profile, REDACTED, type Random, RandomPort, type Release, type Secret, type SecretProvider, SecretProviderPort, type SignalHandler, type SignalSource, SignalSourcePort, type SpawnArgs, type SystemSignal, type TargetKind, type ToolingSettings, type Unsubscribe, VennError, type VennErrorDetail, type VirtualClock, type WorkspaceSettings, addDependency, assertCapabilities, assertPortShape, bindPort, capabilityUnavailable, createConsoleLogger, createEnvSecrets, createFakeLock, createFakeProcess, createFakeSignals, createFixedRandom, createHost, createInProcessLock, createMemoryConsole, createMemoryFs, createMemoryLogger, createMemoryManifest, createMemorySecrets, createSeededRandom, createSystemClock, createTestHost, createTomlManifest, createVirtualClock, createWorkerHost, defaultManifest, dotenvFiles, fsNotFound, hostMissingCapability, makeSecret, missingCapabilities, parseDotenv, parseToml, portShapeMismatch, readInheritable, removeDependency, resolveAlias, tomlDocs, unavailable };
620
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","names":[],"sources":["../src/capabilities/host-capability.ts","../src/dotenv/dotenv-files.ts","../src/dotenv/parse-dotenv.ts","../src/errors/venn-error.ts","../src/errors/contract-codes.ts","../src/logger/logger.types.ts","../src/logger/console-logger.ts","../src/logger/memory-logger.ts","../src/port/port.types.ts","../src/port/assert-capabilities.ts","../src/port/assert-port-shape.ts","../src/port/bind-port.ts","../src/port/missing-capabilities.ts","../src/ports/clock/clock.port.ts","../src/ports/clock/system-clock.ts","../src/ports/clock/virtual-clock.ts","../src/ports/file-system/file-system.errors.ts","../src/ports/file-system/file-system.port.ts","../src/ports/file-system/memory-fs.ts","../src/ports/lock-provider/fake-lock.ts","../src/ports/lock-provider/in-process-lock.ts","../src/ports/lock-provider/lock-provider.port.ts","../src/ports/process-provider/fake-process.ts","../src/ports/process-provider/process-provider.port.ts","../src/ports/random/fixed-random.ts","../src/ports/random/random.port.ts","../src/ports/random/seeded-random.ts","../src/ports/secret-provider/env-secrets.ts","../src/ports/secret-provider/memory-secrets.ts","../src/ports/secret-provider/secret.ts","../src/ports/secret-provider/secret-provider.port.ts","../src/host/host.types.ts","../src/host/create-test-host.ts","../src/host/create-worker-host.ts","../src/host/create-host.ts","../src/host/unavailable.ts","../src/ports/console/console.types.ts","../src/ports/console/console.port.ts","../src/ports/console/memory-console.ts","../src/ports/manifest-provider/default-manifest.ts","../src/ports/manifest-provider/edit/edit-dependency.ts","../src/ports/manifest-provider/manifest.port.ts","../src/ports/manifest-provider/memory-manifest.ts","../src/ports/manifest-provider/read/read-package.ts","../src/ports/manifest-provider/read/read-profiles.ts","../src/ports/manifest-provider/read/read-targets.ts","../src/ports/manifest-provider/resolve-alias.ts","../src/ports/manifest-provider/toml/parse-toml.ts","../src/ports/manifest-provider/toml-docs.ts","../src/ports/manifest-provider/toml-manifest.ts","../src/ports/signal-source/fake-signals.ts","../src/ports/signal-source/signal-source.port.ts"],"mappings":"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"}