@contextrail/assess 0.0.0-stage → 1.0.0-alpha.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.
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 +1548 -0
  7. package/dist/assessment.d.ts +566 -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 +147 -0
  12. package/dist/candidate.js +321 -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 +140 -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 +309 -0
  44. package/dist/presentation.js +1026 -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 +132 -0
  50. package/dist/report-contract.js +240 -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 +156 -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 +203 -0
  69. package/docs/review-results.md +173 -0
  70. package/docs/security.md +64 -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,71 @@
1
+ import { PreparationReadError, type Publication, type PublishedReader, type ScopeEntry } from './contracts.js';
2
+ import { fixGitIdentity } from './git.js';
3
+ import { type ChangeInventory, type DiffPage, type SourceLimits } from './source.js';
4
+ export type GitIdentity = ReturnType<typeof fixGitIdentity>;
5
+ type PreparationGap = {
6
+ code: string;
7
+ reason: string;
8
+ diagnostic?: PreparationReadError['diagnostic'];
9
+ };
10
+ export type PreparedState = {
11
+ schemaVersion: 1;
12
+ runId: string;
13
+ createdAt: string;
14
+ preparationStatus: 'prepared' | 'incomplete' | 'not_configured';
15
+ assessmentStatus: 'not_started';
16
+ artifact: GitIdentity;
17
+ reviewer: Publication | null;
18
+ requestedReviewerId: string;
19
+ scopeIdentity: string | null;
20
+ expectedContextCount: number | null;
21
+ entries: Array<ScopeEntry & {
22
+ assessmentId: string;
23
+ material: string | null;
24
+ result: {
25
+ disposition: 'not_evaluated';
26
+ adherence: null;
27
+ confidence: null;
28
+ };
29
+ }>;
30
+ gaps: PreparationGap[];
31
+ limitations: string[];
32
+ diff?: DiffPage;
33
+ changes?: ChangeInventory;
34
+ };
35
+ export declare function digest(value: unknown): string;
36
+ /** Recover the immutable preparation input from the expanded final artifact inventory. */
37
+ export declare function preparationManifest(manifest: Record<string, unknown>): Record<string, unknown>;
38
+ export declare function assessmentId(reviewerId: string, reviewerVersion: number, contextId: string, contextVersion: number | null): string;
39
+ /** Preserve structured published entries verbatim; prose interpretation belongs to model phases. */
40
+ export declare function structuredRequirements(publication: Publication): {
41
+ path: string;
42
+ value: unknown;
43
+ }[];
44
+ /** Fixed artifact is captured before any retrieval; the reader cannot change it. */
45
+ export declare function prepareAssessment(options: {
46
+ repository: string;
47
+ base: string;
48
+ head: string;
49
+ reviewerId: string;
50
+ reader: PublishedReader;
51
+ artifact?: GitIdentity;
52
+ sourceLimits?: Partial<SourceLimits>;
53
+ signal?: AbortSignal;
54
+ }): Promise<{
55
+ state: PreparedState;
56
+ statePath: string;
57
+ materialPath: string;
58
+ manifestPath: string;
59
+ }>;
60
+ /** Human entry point for preparation; can also backfill a completed run without modifying its assessment. */
61
+ export declare function writePreparationArtifacts(state: PreparedState, directory: string, options?: {
62
+ timeoutMs?: number;
63
+ maxBytes?: number;
64
+ }): Promise<{
65
+ status: "unavailable" | "available";
66
+ files: Record<string, string>;
67
+ diffPath: string;
68
+ preparationPath: string;
69
+ }>;
70
+ export declare function atomicJson(path: string, value: unknown): Promise<void>;
71
+ export {};
@@ -0,0 +1,335 @@
1
+ import { createHash, randomUUID } from 'node:crypto';
2
+ import { mkdir, writeFile, rename, rm } from 'node:fs/promises';
3
+ import { join } from 'node:path';
4
+ import { PreparationReadError, publicationSchema, reviewerSectionsSchema, scopePageSchema, } from './contracts.js';
5
+ import { fixGitIdentity, readableDiff } from './git.js';
6
+ import { FixedSnapshotSource } from './source.js';
7
+ // Keep this serializer compatible with the API scope contract. The standalone reviewer
8
+ // cannot import unpublished API internals merely to share this small boundary implementation.
9
+ export function digest(value) {
10
+ return `sha256:${createHash('sha256')
11
+ .update(JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
12
+ ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b, 'en')))
13
+ : item))
14
+ .digest('hex')}`;
15
+ }
16
+ /** Recover the immutable preparation input from the expanded final artifact inventory. */
17
+ export function preparationManifest(manifest) {
18
+ const { files, capture: _capture, ...prepared } = manifest;
19
+ const inventory = files && typeof files === 'object' ? files : {};
20
+ const originalFiles = Object.fromEntries(['diff.patch', 'preparation.md']
21
+ .filter((name) => inventory[name] !== undefined)
22
+ .map((name) => [name, inventory[name]]));
23
+ if (Object.keys(originalFiles).length)
24
+ prepared.files = originalFiles;
25
+ return prepared;
26
+ }
27
+ export function assessmentId(reviewerId, reviewerVersion, contextId, contextVersion) {
28
+ return `assessment:${createHash('sha256')
29
+ .update(JSON.stringify([reviewerId, reviewerVersion, contextId, contextVersion]))
30
+ .digest('hex')}`;
31
+ }
32
+ /** Preserve structured published entries verbatim; prose interpretation belongs to model phases. */
33
+ export function structuredRequirements(publication) {
34
+ const entries = [];
35
+ for (const field of ['rules', 'checklist']) {
36
+ const values = publication.content[field];
37
+ if (Array.isArray(values))
38
+ values.forEach((value, index) => entries.push({ path: `/content/${field}/${index}`, value }));
39
+ }
40
+ return entries;
41
+ }
42
+ function initialPreparationState(artifact, reviewerId, runId) {
43
+ return {
44
+ schemaVersion: 1,
45
+ runId,
46
+ createdAt: new Date().toISOString(),
47
+ preparationStatus: 'incomplete',
48
+ assessmentStatus: 'not_started',
49
+ artifact,
50
+ reviewer: null,
51
+ requestedReviewerId: reviewerId,
52
+ scopeIdentity: null,
53
+ expectedContextCount: null,
54
+ entries: [],
55
+ gaps: [],
56
+ limitations: [
57
+ 'Prepared means retrieval and accounting only. No context has been evaluated; this is not a completed or passing review.',
58
+ 'The manifest fixes the authorized context/version set observed once during preparation. Later publications and domain changes apply to future runs.',
59
+ 'Non-context prerequisites are reported as unsupported. No conditional applicability judgments are made.',
60
+ ],
61
+ };
62
+ }
63
+ function assertScopeIdentity(page, selections) {
64
+ if (page.selectionsHash !== digest(selections))
65
+ throw new PreparationReadError('scope_changed_or_invalid');
66
+ const identity = digest({
67
+ reviewerId: page.reviewerId,
68
+ publicationVersion: page.publicationVersion,
69
+ selectionsHash: page.selectionsHash,
70
+ entries: page.entries,
71
+ gaps: page.gaps,
72
+ });
73
+ // Incomplete service responses may retain the identity of an undisclosed full set.
74
+ if ((page.complete ||
75
+ (page.entries.length === page.totalMatched && page.offset === 0 && page.nextOffset === null)) &&
76
+ page.scopeIdentity !== identity)
77
+ throw new PreparationReadError('scope_changed_or_invalid');
78
+ }
79
+ async function prepareScope(reviewer, assessment, state, addGap, checkpoint) {
80
+ const selections = reviewer.content.reviewer?.selections ?? {};
81
+ const page = scopePageSchema.parse(assessment);
82
+ if (page.reviewerId !== reviewer.nodeId || page.publicationVersion !== reviewer.version)
83
+ throw new PreparationReadError('scope_changed_or_invalid');
84
+ // Preserve trustworthy counts and service gaps before any completeness validation.
85
+ state.expectedContextCount = page.totalMatched;
86
+ for (const gap of page.gaps)
87
+ addGap(gap.code, gap.reason);
88
+ assertScopeIdentity(page, selections);
89
+ state.scopeIdentity = page.scopeIdentity;
90
+ const seen = new Set();
91
+ for (const entry of page.entries) {
92
+ if (seen.has(entry.nodeId))
93
+ throw new PreparationReadError('duplicate_scope_entry');
94
+ seen.add(entry.nodeId);
95
+ state.entries.push({
96
+ ...entry,
97
+ assessmentId: assessmentId(reviewer.nodeId, reviewer.version, entry.nodeId, entry.version),
98
+ material: null,
99
+ result: { disposition: 'not_evaluated', adherence: null, confidence: null },
100
+ });
101
+ }
102
+ if (!page.complete && !page.gaps.length)
103
+ addGap('scope_incomplete', 'enumeration');
104
+ if (page.offset !== 0 || page.nextOffset !== null || page.entries.length !== page.totalMatched)
105
+ addGap('scope_incomplete', 'enumeration');
106
+ await checkpoint();
107
+ state.entries.sort((a, b) => a.nodeId.localeCompare(b.nodeId, 'en'));
108
+ if (!state.entries.length && !state.gaps.length)
109
+ addGap('empty_scope', 'enumeration');
110
+ }
111
+ async function prepareContextMaterials(reader, state, materials, addGap, checkpoint) {
112
+ for (const entry of state.entries) {
113
+ if (entry.version === null || entry.subtype === null || entry.contentHash === null) {
114
+ addGap('context_unavailable', entry.nodeId);
115
+ continue;
116
+ }
117
+ try {
118
+ const content = publicationSchema.parse(await reader.read('get_context', {
119
+ nodeId: entry.nodeId,
120
+ publicationVersion: entry.version,
121
+ detailLevel: 'full',
122
+ responseFormat: 'json',
123
+ }));
124
+ if (content.nodeId !== entry.nodeId ||
125
+ content.version !== entry.version ||
126
+ content.type !== 'context' ||
127
+ content.subtype !== entry.subtype ||
128
+ digest(content.content) !== entry.contentHash)
129
+ throw new PreparationReadError('publication_changed_or_invalid');
130
+ materials[entry.assessmentId] = content;
131
+ entry.material = `publications.json#${entry.assessmentId}`;
132
+ }
133
+ catch (error) {
134
+ addGap(errorCode(error), entry.nodeId, error instanceof PreparationReadError ? error.diagnostic : undefined);
135
+ if (errorCode(error) === 'mcp_cancelled' || errorCode(error) === 'mcp_timeout') {
136
+ await checkpoint();
137
+ throw error;
138
+ }
139
+ }
140
+ await checkpoint();
141
+ }
142
+ }
143
+ async function confirmReviewerIdentity(reader, reviewer) {
144
+ const identitySchema = publicationSchema
145
+ .pick({
146
+ nodeId: true,
147
+ title: true,
148
+ domainId: true,
149
+ type: true,
150
+ subtype: true,
151
+ status: true,
152
+ version: true,
153
+ })
154
+ .strip();
155
+ const finalReviewer = identitySchema.parse(await reader.read('get_skill', {
156
+ nodeId: reviewer.nodeId,
157
+ publicationVersion: reviewer.version,
158
+ detailLevel: 'summary',
159
+ responseFormat: 'json',
160
+ }));
161
+ if (digest(finalReviewer) !== digest(identitySchema.parse(reviewer)))
162
+ throw new PreparationReadError('publication_changed_or_invalid');
163
+ }
164
+ async function prepareSourceArtifacts(state, options, directory, addGap) {
165
+ const source = new FixedSnapshotSource(state.artifact, options.sourceLimits);
166
+ state.changes = await source.changeInventory({ signal: options.signal });
167
+ if (state.changes.status !== 'complete') {
168
+ addGap('change_inventory_incomplete', state.changes.reason ?? 'Changed-file metadata capture is incomplete.');
169
+ if (state.preparationStatus === 'prepared')
170
+ state.preparationStatus = 'incomplete';
171
+ }
172
+ try {
173
+ state.diff = await source.diff({}, { signal: options.signal });
174
+ }
175
+ catch {
176
+ addGap('diff_unavailable', 'Fixed comparison hunks could not be prepared.');
177
+ state.preparationStatus = 'incomplete';
178
+ }
179
+ const readable = await writePreparationArtifacts(state, directory, { timeoutMs: options.sourceLimits?.timeoutMs });
180
+ if (readable.status === 'unavailable') {
181
+ addGap('readable_diff_unavailable', 'See preparation.md for the readable artifact limit.');
182
+ if (state.preparationStatus === 'prepared')
183
+ state.preparationStatus = 'incomplete';
184
+ }
185
+ return readable;
186
+ }
187
+ /** Fixed artifact is captured before any retrieval; the reader cannot change it. */
188
+ export async function prepareAssessment(options) {
189
+ const artifact = options.artifact ?? fixGitIdentity(options.repository, options.base, options.head);
190
+ if (!options.reviewerId.startsWith('skill://'))
191
+ throw new Error('Use a published skill:// reviewer ID.');
192
+ const runId = randomUUID();
193
+ const directory = join(artifact.repository, '.contextrail', 'assess', runId);
194
+ await mkdir(directory, { recursive: true, mode: 0o700 });
195
+ const state = initialPreparationState(artifact, options.reviewerId, runId);
196
+ const materials = {};
197
+ const addGap = (code, reason, diagnostic) => {
198
+ if (!state.gaps.some((gap) => gap.code === code && gap.reason === reason))
199
+ state.gaps.push({ code, reason, ...(diagnostic ? { diagnostic } : {}) });
200
+ };
201
+ const materialPath = join(directory, 'publications.json');
202
+ const statePath = join(directory, 'state.json');
203
+ const checkpoint = async () => {
204
+ // Material first: a crash can leave unreferenced material, never a reference to an unwritten file.
205
+ await atomicJson(materialPath, materials);
206
+ await atomicJson(statePath, state);
207
+ };
208
+ await checkpoint();
209
+ let phase = 'reviewer';
210
+ try {
211
+ const reviewer = publicationSchema.parse(await options.reader.read('get_skill', {
212
+ nodeId: options.reviewerId,
213
+ detailLevel: 'full',
214
+ responseFormat: 'json',
215
+ includeAssessment: true,
216
+ }));
217
+ if (reviewer.nodeId !== options.reviewerId ||
218
+ reviewer.type !== 'skill' ||
219
+ reviewer.subtype !== 'reviewer' ||
220
+ !reviewer.content.instructions?.trim())
221
+ throw new PreparationReadError('invalid_reviewer_publication');
222
+ reviewerSectionsSchema.parse(reviewer.content.sections ?? {});
223
+ const assessment = reviewer.assessment;
224
+ delete reviewer.assessment;
225
+ state.reviewer = reviewer;
226
+ await checkpoint();
227
+ phase = 'scope';
228
+ await prepareScope(reviewer, assessment, state, addGap, checkpoint);
229
+ phase = 'content';
230
+ await prepareContextMaterials(options.reader, state, materials, addGap, checkpoint);
231
+ phase = 'final_reviewer_check';
232
+ await confirmReviewerIdentity(options.reader, reviewer);
233
+ if (!state.gaps.length)
234
+ state.preparationStatus = 'prepared';
235
+ }
236
+ catch (error) {
237
+ addGap(errorCode(error), phase, error instanceof PreparationReadError ? error.diagnostic : undefined);
238
+ }
239
+ if (state.gaps.some((gap) => gap.code === 'preparation_not_configured'))
240
+ state.preparationStatus = 'not_configured';
241
+ const readable = await prepareSourceArtifacts(state, options, directory, addGap);
242
+ await checkpoint();
243
+ const manifestPath = join(directory, 'manifest.json');
244
+ await atomicJson(manifestPath, {
245
+ contractVersion: 1,
246
+ runId,
247
+ artifact,
248
+ reviewer: state.reviewer,
249
+ scopeIdentity: state.scopeIdentity,
250
+ expectedContextCount: state.expectedContextCount,
251
+ entries: state.entries.map(({ result: _result, ...entry }) => entry),
252
+ publicationsHash: digest(materials),
253
+ structuredRequirements: Object.fromEntries(Object.entries(materials).map(([id, publication]) => [id, structuredRequirements(publication)])),
254
+ diffHash: digest(state.diff ?? null),
255
+ changesHash: digest(state.changes),
256
+ preparationStatus: state.preparationStatus,
257
+ gaps: state.gaps,
258
+ files: readable.files,
259
+ });
260
+ return { state, statePath, materialPath, manifestPath };
261
+ }
262
+ /** Human entry point for preparation; can also backfill a completed run without modifying its assessment. */
263
+ export async function writePreparationArtifacts(state, directory, options = {}) {
264
+ const hashes = {};
265
+ const write = async (name, text) => {
266
+ const temporary = join(directory, `${name}.${randomUUID()}.tmp`);
267
+ try {
268
+ await writeFile(temporary, text, { mode: 0o600, flag: 'wx' });
269
+ await rename(temporary, join(directory, name));
270
+ hashes[name] = `sha256:${createHash('sha256').update(text).digest('hex')}`;
271
+ }
272
+ finally {
273
+ await rm(temporary, { force: true });
274
+ }
275
+ };
276
+ const escaped = (value) => value.replace(/[\\`*_[\]<>]/gu, (character) => `\\${character}`).replace(/[\r\n]/gu, ' ');
277
+ const lines = [
278
+ '# Review preparation',
279
+ '',
280
+ 'These are the fixed review inputs, not assessment conclusions.',
281
+ '',
282
+ `Base: \`${state.artifact.base.commit}\``,
283
+ `Head: \`${state.artifact.head.commit}\``,
284
+ `Reviewer: ${escaped(state.requestedReviewerId)}${state.reviewer ? ` (publication ${state.reviewer.version})` : ' (unavailable)'}`,
285
+ '',
286
+ 'Open [diff.patch](diff.patch) for the normal Git diff. [state.json](state.json) and [publications.json](publications.json) retain machine-readable provenance and pinned guidance.',
287
+ '',
288
+ '## Changes',
289
+ '',
290
+ ];
291
+ let status = 'available';
292
+ try {
293
+ const diff = readableDiff(state.artifact, options);
294
+ await write('diff.patch', diff.patch);
295
+ const fence = '`'.repeat(Math.max(3, ...(diff.stat.match(/`+/gu) ?? []).map((match) => match.length + 1)));
296
+ lines.push(`${fence}text`, diff.stat || '(No permitted changed files.)', fence, '', 'Changed paths:', '');
297
+ lines.push(...(diff.files.length ? diff.files.map((path) => `- ${escaped(JSON.stringify(path))}`) : ['- None.']));
298
+ lines.push('', '## Omissions and limits', '');
299
+ lines.push(...(diff.excludedPaths.length
300
+ ? diff.excludedPaths.map((path) => `- Credential-path content excluded: ${escaped(JSON.stringify(path))}`)
301
+ : ['- No conventional credential paths were excluded.']));
302
+ lines.push('- Binary files and submodules retain normal Git markers/pointers; their contents are not expanded.');
303
+ lines.push(`- Full permitted diff: ${Buffer.byteLength(diff.patch)} bytes. Output bound: ${options.maxBytes ?? 16 * 1024 * 1024} bytes; total capture timeout: ${options.timeoutMs ?? 30000} ms. No silent truncation.`);
304
+ }
305
+ catch {
306
+ status = 'unavailable';
307
+ await rm(join(directory, 'diff.patch'), { force: true });
308
+ lines.push('The full readable diff is unavailable: Git identity, object availability, UTF-8 representation, output bound or timeout prevented complete capture. No partial diff.patch is presented as complete.', '', '## Omissions and limits', '');
309
+ lines.push(`- Output bound: ${options.maxBytes ?? 16 * 1024 * 1024} bytes; total capture timeout: ${options.timeoutMs ?? 30000} ms.`);
310
+ }
311
+ lines.push('', 'The JSON diff field records the initial paged diff view. Its truncated status describes that view, independently of full diff.patch capture above. Additional pinned source is available through tools; availability does not establish examination.', '', '## Governed scope', '', `Expected contexts: ${state.expectedContextCount ?? 'unavailable'}; recorded contexts: ${state.entries.length}.`, '');
312
+ lines.push(...state.entries.map((entry) => `- ${escaped(entry.nodeId)} @ ${entry.version ?? 'unavailable'} (${entry.subtype ?? 'unavailable'})`));
313
+ if (state.gaps.length)
314
+ lines.push('', 'Preparation gaps:', '', ...state.gaps.map((gap) => `- ${escaped(gap.code)}: ${escaped(gap.reason)}`));
315
+ await write('preparation.md', lines.join('\n') + '\n');
316
+ return {
317
+ status,
318
+ files: hashes,
319
+ diffPath: join(directory, 'diff.patch'),
320
+ preparationPath: join(directory, 'preparation.md'),
321
+ };
322
+ }
323
+ function errorCode(error) {
324
+ return error instanceof PreparationReadError ? error.code : 'contract_validation_failed';
325
+ }
326
+ export async function atomicJson(path, value) {
327
+ const temporary = `${path}.${randomUUID()}.tmp`;
328
+ try {
329
+ await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
330
+ await rename(temporary, path);
331
+ }
332
+ finally {
333
+ await rm(temporary, { force: true });
334
+ }
335
+ }