@peasant-labs/schema 0.52.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.
@@ -1,5 +1,7 @@
1
1
  import type { components as GeneratedComponents, operations as GeneratedOperations, paths as GeneratedPaths } from "./internal/generated/local-api.js";
2
2
  export { PeasantLocalAPIVersion, LocalKickstartDroppedLabelsMax } from "./index.js";
3
+ export { ALL_HTTP_METHODS, ALL_LOCAL_ROUTES, HttpMethod, LocalRoute, isHttpMethod } from "./internal/generated/routes.gen.js";
4
+ export type { PathArgs, PathParams, RouteMember } from "./route-member.js";
3
5
  export type paths = GeneratedPaths;
4
6
  export type operations = GeneratedOperations;
5
7
  export type components = GeneratedComponents;
package/dist/local-api.js CHANGED
@@ -1 +1,2 @@
1
1
  export { PeasantLocalAPIVersion, LocalKickstartDroppedLabelsMax } from "./index.js";
2
+ export { ALL_HTTP_METHODS, ALL_LOCAL_ROUTES, HttpMethod, LocalRoute, isHttpMethod } from "./internal/generated/routes.gen.js";
@@ -0,0 +1,33 @@
1
+ import type { HttpMethod } from "./internal/generated/routes.gen.js";
2
+ type PathParamNames<P extends string> = P extends `${string}{${infer Name}}${infer Rest}` ? Name | PathParamNames<Rest> : never;
3
+ /** PathParams is the parameter object of a path template: one key per {name}. */
4
+ export type PathParams<P extends string> = {
5
+ readonly [Name in PathParamNames<P>]: string | number;
6
+ };
7
+ /**
8
+ * PathArgs is the argument list of a route member's path builder: no argument
9
+ * when the template has no parameter, otherwise one object carrying exactly the
10
+ * template's parameters. A missing or extra key is a compile error.
11
+ */
12
+ export type PathArgs<P extends string> = [PathParamNames<P>] extends [never] ? [] : [params: PathParams<P>];
13
+ /** RouteMember is one operation a Village API or Local API document declares. */
14
+ export interface RouteMember<P extends string, M extends HttpMethod> {
15
+ /** The HTTP method, as sent on the wire. */
16
+ readonly method: M;
17
+ /** The document's path template, for example "/api/v1/pulls/{owner}/{name}/{number}". */
18
+ readonly pattern: P;
19
+ /** The document's operationId, for example "getPullRequestAttachment". */
20
+ readonly operationId: string;
21
+ /**
22
+ * Builds the request path. Every parameter value is escaped with
23
+ * encodeURIComponent. A value that is empty, "." or ".." throws a RangeError:
24
+ * clients resolve such a segment, so the request would reach another endpoint.
25
+ */
26
+ path(...args: PathArgs<P>): string;
27
+ }
28
+ /**
29
+ * routeMember builds one frozen member. The generated route modules are its
30
+ * only callers; the template is split once, when the module loads.
31
+ */
32
+ export declare function routeMember<P extends string, M extends HttpMethod>(method: M, pattern: P, operationId: string): RouteMember<P, M>;
33
+ export {};
@@ -0,0 +1,50 @@
1
+ const parameterPattern = /\{([^{}]+)\}/g;
2
+ /**
3
+ * routeMember builds one frozen member. The generated route modules are its
4
+ * only callers; the template is split once, when the module loads.
5
+ */
6
+ export function routeMember(method, pattern, operationId) {
7
+ const parts = [];
8
+ let offset = 0;
9
+ for (const match of pattern.matchAll(parameterPattern)) {
10
+ parts.push({ literal: pattern.slice(offset, match.index) });
11
+ parts.push({ parameter: match[1] ?? "" });
12
+ offset = match.index + match[0].length;
13
+ }
14
+ parts.push({ literal: pattern.slice(offset) });
15
+ const frozenParts = Object.freeze(parts.map((part) => Object.freeze(part)));
16
+ function path(...args) {
17
+ // A JavaScript caller can pass anything; a value that is not an object
18
+ // carries no parameter, so each parameter is then refused as missing.
19
+ const given = args[0];
20
+ const params = typeof given === "object" && given !== null ? args[0] : undefined;
21
+ let out = "";
22
+ for (const part of frozenParts) {
23
+ if ("literal" in part) {
24
+ out += part.literal;
25
+ continue;
26
+ }
27
+ const value = params === undefined || !Object.hasOwn(params, part.parameter) ? undefined : params[part.parameter];
28
+ out += encodeURIComponent(pathValue(operationId, pattern, part.parameter, value));
29
+ }
30
+ return out;
31
+ }
32
+ return Object.freeze({ method, pattern, operationId, path });
33
+ }
34
+ const unaddressableSegments = new Set(["", ".", ".."]);
35
+ function pathValue(operationId, pattern, parameter, value) {
36
+ if (typeof value === "string") {
37
+ if (!unaddressableSegments.has(value))
38
+ return value;
39
+ // The Go path builders return the same text in route.PathSegmentError.
40
+ throw new RangeError(`route path for ${operationId} (${pattern}) could not be built: parameter ${JSON.stringify(parameter)} is ${value === "" ? "empty" : JSON.stringify(value)}; ` +
41
+ 'a path segment that is empty, "." or ".." is resolved by clients and proxies, so the request would reach a different endpoint; ' +
42
+ "pass the identifier of the resource the parameter names.");
43
+ }
44
+ if (typeof value === "number" && Number.isFinite(value))
45
+ return String(value);
46
+ const received = value === undefined ? "no value" : typeof value === "number" ? String(value) : `a ${value === null ? "null" : typeof value}`;
47
+ throw new TypeError(`route path for ${operationId} (${pattern}) could not be built: parameter ${JSON.stringify(parameter)} received ${received}; ` +
48
+ "a path parameter must be a string or a finite number, so the request would address the wrong resource; " +
49
+ `pass ${JSON.stringify(parameter)} in the object given to path().`);
50
+ }
@@ -0,0 +1,3 @@
1
+ export declare function isTranscriptDirectoryPositionsValid(directory: unknown): boolean;
2
+ /** Project a positioned context and refs into the shared conversation-position rule. */
3
+ export declare function isPositionedDirectoryPositionsValid(directory: unknown): boolean;
@@ -0,0 +1,89 @@
1
+ import { zConversationTurnSpan } from "./internal/generated/contract/zod.gen.js";
2
+ // Where a decoded segment-directory response places each segment among the
3
+ // session's conversation turns. This mirrors Go's
4
+ // validateDirectoryConversationTurns, which applies four rules: both counts of
5
+ // a stated span are non-negative, which the generated span shape already
6
+ // enforces; the total is a count; a span ends at or before it; and immediate
7
+ // neighbours that both state a span must meet exactly (an omitted span breaks
8
+ // the chain).
9
+ //
10
+ // When the shared position rule changes, both implementations change in the
11
+ // same PR, and the shared fixtures detect disagreement only for the cases they
12
+ // cover.
13
+ //
14
+ // The browser is deliberately stricter than Go's struct validation in three
15
+ // places, following the generated wire shape: an explicit null, a number
16
+ // outside the safe-integer domain, and a span missing before or count are all
17
+ // unusable here where Go's non-pointer int fields would read zero. The helper
18
+ // also sees JavaScript numbers after JSON parsing, so it cannot detect a number
19
+ // lexeme that already rounded to a safe integer; this is not raw-token parity.
20
+ //
21
+ // false means the optional positions are unusable and a consumer should drop
22
+ // them. It is not a rejection of the directory or its turns. true is not an
23
+ // attestation of required fields, authorization, other pages, or a future
24
+ // negotiated representation.
25
+ function isRecord(value) {
26
+ return typeof value === "object" && value !== null && !Array.isArray(value);
27
+ }
28
+ function isNonNegativeSafeInteger(value) {
29
+ return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
30
+ }
31
+ // The generated ConversationTurnSpan shape is the only accepted span: both
32
+ // counts present, integral, and inside 0..9007199254740991.
33
+ function parseSpan(value) {
34
+ const parsed = zConversationTurnSpan.safeParse(value);
35
+ return parsed.success ? parsed.data : undefined;
36
+ }
37
+ export function isTranscriptDirectoryPositionsValid(directory) {
38
+ if (!isRecord(directory))
39
+ return false;
40
+ const segments = directory.segments;
41
+ if (!Array.isArray(segments))
42
+ return false;
43
+ const statedTotal = directory.totalConversationTurns;
44
+ if (statedTotal !== undefined && !isNonNegativeSafeInteger(statedTotal))
45
+ return false;
46
+ // Undefined means the previous ref stated no span, so the chain of
47
+ // comparisons stops there instead of bridging to the next stated span.
48
+ let previous;
49
+ for (const ref of segments) {
50
+ if (!isRecord(ref))
51
+ return false;
52
+ const stated = ref.conversationTurns;
53
+ let span;
54
+ if (stated !== undefined) {
55
+ span = parseSpan(stated);
56
+ if (span === undefined)
57
+ return false;
58
+ if (statedTotal !== undefined && !endsAtOrBefore(span, statedTotal))
59
+ return false;
60
+ }
61
+ if (span !== undefined && previous !== undefined && !continues(previous, span))
62
+ return false;
63
+ previous = span;
64
+ }
65
+ return true;
66
+ }
67
+ /** Project a positioned context and refs into the shared conversation-position rule. */
68
+ export function isPositionedDirectoryPositionsValid(directory) {
69
+ if (!isRecord(directory))
70
+ return false;
71
+ const context = directory.context;
72
+ if (!isRecord(context))
73
+ return false;
74
+ return isTranscriptDirectoryPositionsValid({
75
+ totalConversationTurns: context.totalConversationTurns,
76
+ segments: directory.segments,
77
+ });
78
+ }
79
+ // before + count can pass Number.MAX_SAFE_INTEGER and round, so compare by an
80
+ // exact difference instead of the sum. Both operands are safe integers, so
81
+ // total - count is exact.
82
+ function endsAtOrBefore(span, total) {
83
+ return span.count <= total && span.before <= total - span.count;
84
+ }
85
+ // The exact difference between two safe integers is exact, so this is the
86
+ // strict next.before === previous.before + previous.count without the sum.
87
+ function continues(previous, next) {
88
+ return next.before - previous.before === previous.count;
89
+ }
@@ -0,0 +1,17 @@
1
+ import type { TurnDetail } from "./internal/generated/contract/zod.gen.js";
2
+ /**
3
+ * The strict body's typed view. A served legacy body may omit any member, and
4
+ * index is never an address: use the row's recordedIndex and
5
+ * recordedIndexState instead. Read every other member defensively.
6
+ *
7
+ * This view preserves values, not JSON bytes. Re-encoding may change whitespace,
8
+ * number lexemes, or escapes; the wire's byte guarantee belongs to the server.
9
+ */
10
+ export type TranscriptServedTurn = Omit<TurnDetail, "index"> & {
11
+ readonly index?: unknown;
12
+ };
13
+ /**
14
+ * Read a server-validated served turn. This checks object-ness only, not the
15
+ * members: legacy turns need not have the strict shape. Non-objects are refused.
16
+ */
17
+ export declare function readTranscriptServedTurn(value: unknown): TranscriptServedTurn | undefined;
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Read a server-validated served turn. This checks object-ness only, not the
3
+ * members: legacy turns need not have the strict shape. Non-objects are refused.
4
+ */
5
+ export function readTranscriptServedTurn(value) {
6
+ if (typeof value !== "object" || value === null || Array.isArray(value))
7
+ return undefined;
8
+ // The strict view describes the contract, not a guarantee about legacy
9
+ // members. Consumers must inspect every member before using it.
10
+ return value;
11
+ }
@@ -1,4 +1,6 @@
1
1
  import type { operations as GeneratedOperations, paths as GeneratedPaths } from "./internal/generated/village-api.js";
2
2
  export { VillageAPIVersion } from "./index.js";
3
+ export { ALL_HTTP_METHODS, ALL_VILLAGE_ROUTES, HttpMethod, VillageRoute, isHttpMethod } from "./internal/generated/routes.gen.js";
4
+ export type { PathArgs, PathParams, RouteMember } from "./route-member.js";
3
5
  export type paths = GeneratedPaths;
4
6
  export type operations = GeneratedOperations;
@@ -1 +1,2 @@
1
1
  export { VillageAPIVersion } from "./index.js";
2
+ export { ALL_HTTP_METHODS, ALL_VILLAGE_ROUTES, HttpMethod, VillageRoute, isHttpMethod } from "./internal/generated/routes.gen.js";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@peasant-labs/schema",
3
- "version": "0.52.0",
3
+ "version": "0.54.0",
4
4
  "description": "Generated TypeScript contract bindings for the peasant-labs schema module",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {