@contextrail/assess 0.0.0-stage → 1.0.0-alpha.2

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 (73) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +82 -2
  3. package/assets/brand/icon-dark.png +0 -0
  4. package/assets/brand/icon-light.png +0 -0
  5. package/dist/assess.d.ts +109 -0
  6. package/dist/assess.js +1563 -0
  7. package/dist/assessment.d.ts +571 -0
  8. package/dist/assessment.js +404 -0
  9. package/dist/budget.d.ts +24 -0
  10. package/dist/budget.js +52 -0
  11. package/dist/candidate.d.ts +156 -0
  12. package/dist/candidate.js +361 -0
  13. package/dist/change-summary.d.ts +33 -0
  14. package/dist/change-summary.js +26 -0
  15. package/dist/cli.d.ts +2 -0
  16. package/dist/cli.js +406 -0
  17. package/dist/contracts.d.ts +99 -0
  18. package/dist/contracts.js +62 -0
  19. package/dist/diagnostics.d.ts +44 -0
  20. package/dist/diagnostics.js +412 -0
  21. package/dist/evidence.d.ts +73 -0
  22. package/dist/evidence.js +297 -0
  23. package/dist/feedback.d.ts +21 -0
  24. package/dist/feedback.js +154 -0
  25. package/dist/git.d.ts +40 -0
  26. package/dist/git.js +207 -0
  27. package/dist/github.d.ts +90 -0
  28. package/dist/github.js +1342 -0
  29. package/dist/index.d.ts +14 -0
  30. package/dist/index.js +14 -0
  31. package/dist/mcp.d.ts +28 -0
  32. package/dist/mcp.js +173 -0
  33. package/dist/pack.d.ts +160 -0
  34. package/dist/pack.js +377 -0
  35. package/dist/phases.d.ts +65 -0
  36. package/dist/phases.js +63 -0
  37. package/dist/planning.d.ts +64 -0
  38. package/dist/planning.js +135 -0
  39. package/dist/pr-context.d.ts +316 -0
  40. package/dist/pr-context.js +198 -0
  41. package/dist/prepare.d.ts +71 -0
  42. package/dist/prepare.js +335 -0
  43. package/dist/presentation.d.ts +310 -0
  44. package/dist/presentation.js +1076 -0
  45. package/dist/provider-diagnostics.d.ts +93 -0
  46. package/dist/provider-diagnostics.js +233 -0
  47. package/dist/providers.d.ts +45 -0
  48. package/dist/providers.js +291 -0
  49. package/dist/report-contract.d.ts +137 -0
  50. package/dist/report-contract.js +248 -0
  51. package/dist/results.d.ts +90 -0
  52. package/dist/results.js +128 -0
  53. package/dist/resume.d.ts +25 -0
  54. package/dist/resume.js +116 -0
  55. package/dist/source.d.ts +167 -0
  56. package/dist/source.js +675 -0
  57. package/dist/verification.d.ts +386 -0
  58. package/dist/verification.js +168 -0
  59. package/dist/version.d.ts +2 -0
  60. package/dist/version.js +9 -0
  61. package/docs/README.md +24 -0
  62. package/docs/action-reference.md +85 -0
  63. package/docs/architecture.md +158 -0
  64. package/docs/configuration.md +83 -0
  65. package/docs/contributing.md +46 -0
  66. package/docs/getting-started.md +92 -0
  67. package/docs/github-actions.md +141 -0
  68. package/docs/operations.md +211 -0
  69. package/docs/review-results.md +189 -0
  70. package/docs/security.md +68 -0
  71. package/docs/standards.md +62 -0
  72. package/examples/assess-pull-request.yml +109 -0
  73. package/package.json +56 -5
@@ -0,0 +1,14 @@
1
+ export { prepareAssessment, assessmentId, type PreparedState, type GitIdentity } from './prepare.js';
2
+ export { fixGitIdentity } from './git.js';
3
+ export { McpPublishedReader, MCP_PROTOCOL_VERSION, DEFAULT_MCP_TIMEOUT_MS, mcpTimeoutMs } from './mcp.js';
4
+ export { PreparationReadError, type PublishedReader } from './contracts.js';
5
+ export { FixedSnapshotSource, DEFAULT_SOURCE_LIMITS, SourceAccessError, type SourceSide, type Snapshot, type SourceEntry, type SourceChange, type SourceLimits, type SourcePosition, type ReadRequest, type ReadResult, type SearchCursor, type SourceMatch, type SearchResult, } from './source.js';
6
+ export { runAssessment, DEFAULT_EXECUTION_LIMITS, type ExecutionLimits, type AssessmentState } from './assess.js';
7
+ export { loadAssessmentCheckpoint, type AssessmentCheckpoint } from './resume.js';
8
+ export { assessmentModel, type ProviderConfiguration, type AssessmentProvider } from './providers.js';
9
+ export { decideExit, DEFAULT_POLICY, type AssessmentPolicy, type AcceptedResult } from './results.js';
10
+ export { projectAssessmentReport, sendAssessmentReport, type ReportingStatus, type AssessmentFeedbackSender, } from './feedback.js';
11
+ export { reviewReportInputSchema, type ReviewReportInput, type ReviewReportReceipt } from './report-contract.js';
12
+ export { createPhaseRecord, validatePhaseRecord, phaseRecordSchema, type PhaseRecord } from './phases.js';
13
+ export { prepareGitHubAssessment, publishGitHubAssessment } from './github.js';
14
+ export { renderAssessmentComment, renderActionSummary } from './presentation.js';
package/dist/index.js ADDED
@@ -0,0 +1,14 @@
1
+ export { prepareAssessment, assessmentId } from './prepare.js';
2
+ export { fixGitIdentity } from './git.js';
3
+ export { McpPublishedReader, MCP_PROTOCOL_VERSION, DEFAULT_MCP_TIMEOUT_MS, mcpTimeoutMs } from './mcp.js';
4
+ export { PreparationReadError } from './contracts.js';
5
+ export { FixedSnapshotSource, DEFAULT_SOURCE_LIMITS, SourceAccessError, } from './source.js';
6
+ export { runAssessment, DEFAULT_EXECUTION_LIMITS } from './assess.js';
7
+ export { loadAssessmentCheckpoint } from './resume.js';
8
+ export { assessmentModel } from './providers.js';
9
+ export { decideExit, DEFAULT_POLICY } from './results.js';
10
+ export { projectAssessmentReport, sendAssessmentReport, } from './feedback.js';
11
+ export { reviewReportInputSchema } from './report-contract.js';
12
+ export { createPhaseRecord, validatePhaseRecord, phaseRecordSchema } from './phases.js';
13
+ export { prepareGitHubAssessment, publishGitHubAssessment } from './github.js';
14
+ export { renderAssessmentComment, renderActionSummary } from './presentation.js';
package/dist/mcp.d.ts ADDED
@@ -0,0 +1,28 @@
1
+ import type { ReviewReportInput } from './report-contract.js';
2
+ import { PreparationReadError, type PublishedReader } from './contracts.js';
3
+ import type { RepositoryEnvironment } from './git.js';
4
+ export declare const MCP_PROTOCOL_VERSION = "2026-07-28";
5
+ /** Operational default per connect/read, not a measured deployment requirement. */
6
+ export declare const DEFAULT_MCP_TIMEOUT_MS = 30000;
7
+ export declare function mcpTimeoutMs(value: number | string | undefined): number;
8
+ export declare class McpPublishedReader implements PublishedReader {
9
+ private readonly repository;
10
+ private readonly options;
11
+ private readonly client;
12
+ private connected;
13
+ private connection;
14
+ private responseStatus;
15
+ private readonly transport;
16
+ private readonly timeoutMs;
17
+ constructor(url: string, token: string, orgId: string, repository: RepositoryEnvironment, options?: {
18
+ timeoutMs?: number;
19
+ signal?: AbortSignal;
20
+ repositoryAttribution?: boolean;
21
+ });
22
+ read(name: Parameters<PublishedReader['read']>[0], args: Record<string, unknown>): Promise<unknown>;
23
+ submitReport(report: ReviewReportInput): Promise<unknown>;
24
+ private call;
25
+ close(): Promise<void>;
26
+ }
27
+ /** Only controlled categories, numeric HTTP/RPC codes and recognized SDK codes survive. */
28
+ export declare function safeReadFailure(error: unknown, phase: string, cancelled?: boolean, responseStatus?: number): PreparationReadError;
package/dist/mcp.js ADDED
@@ -0,0 +1,173 @@
1
+ import { packageVersion } from './version.js';
2
+ import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
3
+ import { PreparationReadError } from './contracts.js';
4
+ export const MCP_PROTOCOL_VERSION = '2026-07-28';
5
+ /** Operational default per connect/read, not a measured deployment requirement. */
6
+ export const DEFAULT_MCP_TIMEOUT_MS = 30_000;
7
+ export function mcpTimeoutMs(value) {
8
+ const timeout = value === undefined ? DEFAULT_MCP_TIMEOUT_MS : Number(value);
9
+ // The maintained SDK and Node timers use a signed 32-bit millisecond interval.
10
+ if (!Number.isInteger(timeout) || timeout < 1 || timeout > 2_147_483_647)
11
+ throw new Error('MCP timeout must be an integer in milliseconds, 1..2147483647 (Node timer range).');
12
+ return timeout;
13
+ }
14
+ export class McpPublishedReader {
15
+ repository;
16
+ options;
17
+ client = new Client({ name: 'contextrail-assess', version: packageVersion }, { versionNegotiation: { mode: { pin: MCP_PROTOCOL_VERSION } } });
18
+ connected = false;
19
+ connection = null;
20
+ responseStatus;
21
+ transport;
22
+ timeoutMs;
23
+ constructor(url, token, orgId, repository, options = {}) {
24
+ this.repository = repository;
25
+ this.options = options;
26
+ const endpoint = new URL(url);
27
+ if (!['http:', 'https:'].includes(endpoint.protocol) ||
28
+ endpoint.username ||
29
+ endpoint.password ||
30
+ endpoint.search ||
31
+ endpoint.hash)
32
+ throw new Error('Use an HTTP(S) MCP URL without credentials, query or fragment.');
33
+ if (!token.trim() || !orgId.trim() || /[\r\n\0]/u.test(token + orgId))
34
+ throw new Error('A valid MCP bearer token and organization ID are required.');
35
+ this.timeoutMs = mcpTimeoutMs(options.timeoutMs ?? process.env.CONTEXTRAIL_MCP_TIMEOUT_MS);
36
+ this.transport = new StreamableHTTPClientTransport(endpoint, {
37
+ fetch: async (input, init) => {
38
+ const response = await fetch(input, init);
39
+ this.responseStatus = response.status;
40
+ return response;
41
+ },
42
+ requestInit: { headers: { Authorization: `Bearer ${token}`, 'x-v2-org-id': orgId } },
43
+ });
44
+ }
45
+ async read(name, args) {
46
+ return this.call(name, args);
47
+ }
48
+ async submitReport(report) {
49
+ return this.call('submit_feedback', report);
50
+ }
51
+ async call(name, args) {
52
+ let phase = 'connect';
53
+ this.responseStatus = undefined;
54
+ const requestOptions = () => ({
55
+ timeout: this.timeoutMs,
56
+ signal: this.options.signal
57
+ ? AbortSignal.any([this.options.signal, AbortSignal.timeout(this.timeoutMs)])
58
+ : AbortSignal.timeout(this.timeoutMs),
59
+ });
60
+ try {
61
+ this.options.signal?.throwIfAborted();
62
+ if (!this.connected) {
63
+ this.connection ??= this.client.connect(this.transport, requestOptions());
64
+ await this.connection;
65
+ this.connected = true;
66
+ }
67
+ phase = 'read';
68
+ this.responseStatus = undefined;
69
+ const result = await this.client.callTool({
70
+ name,
71
+ arguments: {
72
+ ...args,
73
+ environment: {
74
+ repository: this.options.repositoryAttribution
75
+ ? this.repository
76
+ : { status: 'unavailable', reason: 'withheld' },
77
+ harness: { status: 'reported', name: 'contextrail-assess' },
78
+ model: { status: 'unavailable', reason: 'not_exposed' },
79
+ },
80
+ },
81
+ }, requestOptions());
82
+ if (result.isError) {
83
+ const error = result.structuredContent?.error;
84
+ const code = typeof error?.code === 'string' && /^[a-z_]{3,80}$/u.test(error.code)
85
+ ? error.code
86
+ : 'mcp_read_rejected';
87
+ throw new PreparationReadError(code, { phase, category: serviceCategory(code) });
88
+ }
89
+ phase = 'decode';
90
+ if (result.content.length !== 1 || result.content[0]?.type !== 'text')
91
+ throw new PreparationReadError('invalid_mcp_response', { phase });
92
+ return JSON.parse(result.content[0].text);
93
+ }
94
+ catch (error) {
95
+ if (error instanceof PreparationReadError)
96
+ throw error;
97
+ throw safeReadFailure(error, phase, this.options.signal?.aborted, this.responseStatus);
98
+ }
99
+ }
100
+ async close() {
101
+ await this.client.close().catch(() => undefined);
102
+ }
103
+ }
104
+ function serviceCategory(code) {
105
+ if (['graph_node_not_found', 'graph_node_unpublished', 'graph_node_published_version_missing'].includes(code))
106
+ return 'missing_publication';
107
+ if ([
108
+ 'forbidden',
109
+ 'unauthorized',
110
+ 'org_membership_required',
111
+ 'graph_node_read_forbidden',
112
+ 'graph_node_forbidden',
113
+ 'org_access_denied',
114
+ ].includes(code))
115
+ return 'authorization';
116
+ return 'contract_or_service_rejection';
117
+ }
118
+ /** Only controlled categories, numeric HTTP/RPC codes and recognized SDK codes survive. */
119
+ export function safeReadFailure(error, phase, cancelled = false, responseStatus) {
120
+ const source = error && typeof error === 'object'
121
+ ? error
122
+ : {};
123
+ const statusValue = source.status ?? source.data?.status ?? (responseStatus && responseStatus >= 400 ? responseStatus : undefined);
124
+ const status = typeof statusValue === 'number' && Number.isInteger(statusValue) && statusValue >= 100 && statusValue <= 599
125
+ ? statusValue
126
+ : undefined;
127
+ const sdkCodes = [
128
+ 'REQUEST_TIMEOUT',
129
+ 'CLIENT_HTTP_AUTHENTICATION',
130
+ 'CLIENT_HTTP_FORBIDDEN',
131
+ 'CLIENT_HTTP_NOT_IMPLEMENTED',
132
+ 'CLIENT_HTTP_UNEXPECTED_CONTENT',
133
+ 'INVALID_RESULT',
134
+ 'CONNECTION_CLOSED',
135
+ 'ERA_NEGOTIATION_FAILED',
136
+ ];
137
+ const upstreamCode = (typeof source.code === 'string' && sdkCodes.includes(source.code)) ||
138
+ (typeof source.code === 'number' &&
139
+ Number.isInteger(source.code) &&
140
+ source.code >= -32768 &&
141
+ source.code <= 32767)
142
+ ? source.code
143
+ : undefined;
144
+ let cause = error;
145
+ let invalidResponse = false;
146
+ for (let depth = 0; depth < 4 && cause && typeof cause === 'object'; depth++) {
147
+ const nested = cause;
148
+ if (['SyntaxError', 'ZodError'].includes(String(nested.name)) ||
149
+ ['CLIENT_HTTP_UNEXPECTED_CONTENT', 'INVALID_RESULT'].includes(String(nested.code)))
150
+ invalidResponse = true;
151
+ cause = nested.cause;
152
+ }
153
+ const code = cancelled || source.name === 'AbortError'
154
+ ? 'mcp_cancelled'
155
+ : source.name === 'TimeoutError' || source.code === 'REQUEST_TIMEOUT'
156
+ ? 'mcp_timeout'
157
+ : status === 401 || source.code === 'CLIENT_HTTP_AUTHENTICATION'
158
+ ? 'mcp_authentication_failed'
159
+ : status === 403 || source.code === 'CLIENT_HTTP_FORBIDDEN'
160
+ ? 'mcp_authorization_failed'
161
+ : status
162
+ ? 'mcp_http_failed'
163
+ : invalidResponse || source.code === -32700
164
+ ? 'invalid_mcp_response'
165
+ : typeof source.code === 'number'
166
+ ? 'mcp_provider_failed'
167
+ : 'mcp_transport_failed';
168
+ return new PreparationReadError(code, {
169
+ phase,
170
+ ...(status ? { status } : {}),
171
+ ...(upstreamCode !== undefined ? { upstreamCode } : {}),
172
+ });
173
+ }
package/dist/pack.d.ts ADDED
@@ -0,0 +1,160 @@
1
+ import { z } from 'zod';
2
+ import { type Publication } from './contracts.js';
3
+ import { EvidenceLedger, modelEvidence } from './evidence.js';
4
+ import { type PreparedState } from './prepare.js';
5
+ import { type FixedSnapshotSource, type ReadRequest } from './source.js';
6
+ declare const packReadSchema: z.ZodObject<{
7
+ assessmentId: z.ZodString;
8
+ section: z.ZodOptional<z.ZodNumber>;
9
+ offset: z.ZodOptional<z.ZodNumber>;
10
+ }, z.core.$strict>;
11
+ type PackReadRequest = z.infer<typeof packReadSchema>;
12
+ type PackCriterion = {
13
+ assessmentId: string;
14
+ nodeId: string;
15
+ title: string | null;
16
+ version: number | null;
17
+ subtype: string | null;
18
+ contentHash: string | null;
19
+ reasons: string[];
20
+ relationships: Publication['relationships'];
21
+ available: boolean;
22
+ sections: Array<{
23
+ index: number;
24
+ path: string;
25
+ ref: string;
26
+ characters: number;
27
+ bytes: number;
28
+ }>;
29
+ };
30
+ export type EvidencePack = {
31
+ index: {
32
+ contractVersion: 1;
33
+ runId: string;
34
+ scopeIdentity: string | null;
35
+ preparationStatus: PreparedState['preparationStatus'];
36
+ expectedContextCount: number | null;
37
+ comparison: {
38
+ base: string;
39
+ head: string;
40
+ };
41
+ criteria: PackCriterion[];
42
+ changedFiles: PreparedState['changes'] | null;
43
+ assets: {
44
+ diff: 'diff.patch';
45
+ preparation: 'preparation.md';
46
+ publications: 'publications.json';
47
+ };
48
+ gaps: PreparedState['gaps'];
49
+ limitations: string[];
50
+ };
51
+ markdown: string;
52
+ };
53
+ export type PackReadResult = {
54
+ status: 'complete' | 'truncated' | 'unavailable';
55
+ publication: Omit<PackCriterion, 'sections'> | null;
56
+ sections: Array<{
57
+ index: number;
58
+ path: string;
59
+ offset: number;
60
+ end: number;
61
+ totalCharacters: number;
62
+ }>;
63
+ evidence: ReturnType<typeof modelEvidence>[];
64
+ next: PackReadRequest | null;
65
+ reason?: string;
66
+ };
67
+ /** Reuse the sealed plain patch; source reads still supply citation evidence. */
68
+ export declare function modelDiffEvidence(directory: string, expectedHash: unknown, fallback: PreparedState['diff']): Promise<{
69
+ fullPatch: {
70
+ status: "omitted";
71
+ reason: "artifact_unavailable" | "model_diff_budget";
72
+ bytes: number | null;
73
+ maxBytes: number;
74
+ };
75
+ status?: "complete" | "truncated" | undefined;
76
+ items?: {
77
+ change: import("./source.js").SourceChange;
78
+ status: "complete" | "truncated" | "unsupported";
79
+ reason?: string;
80
+ patch: string;
81
+ hash: string;
82
+ }[] | undefined;
83
+ next?: {
84
+ offset: number;
85
+ patchLineOffset: number;
86
+ detectRenames: boolean;
87
+ } | null | undefined;
88
+ base?: import("./source.js").Snapshot | undefined;
89
+ head?: import("./source.js").Snapshot | undefined;
90
+ renameDetection?: "heuristic" | "disabled" | undefined;
91
+ } | {
92
+ status: "complete";
93
+ format: string;
94
+ patch: string;
95
+ hash: string;
96
+ }>;
97
+ /** Root authority text is source evidence, not permission to execute repository instructions. */
98
+ export declare function repositoryInstructionsEvidence(source: Pick<FixedSnapshotSource, 'read'>, ledger: EvidenceLedger, signal?: AbortSignal): Promise<{
99
+ status: "complete" | "unavailable" | "truncated" | "unsupported";
100
+ next: ReadRequest | null;
101
+ reason: string | null;
102
+ evidence: {
103
+ ref: string;
104
+ provenance: Record<string, unknown>;
105
+ segments: {
106
+ index: number;
107
+ text: string;
108
+ }[];
109
+ } | null;
110
+ } | {
111
+ status: "unavailable";
112
+ next: {
113
+ side: "head";
114
+ path: string;
115
+ };
116
+ reason: string;
117
+ evidence: null;
118
+ }>;
119
+ /** Shared original input, never assessor conclusions. Oversize sections remain explicitly readable. */
120
+ export declare function modelPackEvidence(pack: EvidencePack, ledger: EvidenceLedger): {
121
+ status: "complete" | "incomplete";
122
+ evidence: ReturnType<typeof modelEvidence>[];
123
+ omitted: Array<{
124
+ ref: string;
125
+ reason: "model_evidence_budget";
126
+ next: PackReadRequest;
127
+ }>;
128
+ unavailable: Array<{
129
+ assessmentId: string;
130
+ reason: "pinned_publication_unavailable";
131
+ }>;
132
+ };
133
+ /** Original source already read during this run, with cited records first and no inferred conclusions. */
134
+ export declare function modelSourceEvidence(ledger: EvidenceLedger, selectedRefs?: string[]): {
135
+ scope: "read_fragments";
136
+ status: "complete" | "incomplete";
137
+ evidence: ReturnType<typeof modelEvidence>[];
138
+ omitted: {
139
+ ref: string;
140
+ reason: "model_evidence_budget";
141
+ next: ReadRequest;
142
+ }[];
143
+ };
144
+ /** One inspectable pack of the original governed material and prepared comparison metadata. */
145
+ export declare function prepareEvidencePack(options: {
146
+ state: PreparedState;
147
+ publications: Record<string, Publication>;
148
+ ledger: EvidenceLedger;
149
+ }): EvidencePack;
150
+ /** Artifact filenames are package-owned. The caller owns the trusted run directory and manifest. */
151
+ export declare function writeEvidencePack(directory: string, pack: EvidencePack): Promise<{
152
+ files: Record<string, string>;
153
+ indexHash: string;
154
+ }>;
155
+ /** Bounded original-material reads. Continuations preserve Unicode and explicit publication offsets. */
156
+ export declare function readPackPublication(pack: EvidencePack, ledger: EvidenceLedger, input: unknown, limits?: {
157
+ maxBytes?: number;
158
+ maxSegments?: number;
159
+ }): PackReadResult;
160
+ export {};