@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
package/dist/resume.js ADDED
@@ -0,0 +1,116 @@
1
+ import { lstatSync, readFileSync, realpathSync } from 'node:fs';
2
+ import { join, resolve } from 'node:path';
3
+ import { z } from 'zod';
4
+ import { publicationSchema } from './contracts.js';
5
+ import { EvidenceLedger } from './evidence.js';
6
+ import { validatePublicationArtifacts } from './github.js';
7
+ import { digest, preparationManifest } from './prepare.js';
8
+ function readObject(path) {
9
+ const stat = lstatSync(path);
10
+ if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 8 * 1024 * 1024)
11
+ throw new Error('resume_artifact_invalid');
12
+ return z.record(z.string(), z.unknown()).parse(JSON.parse(readFileSync(path, 'utf8')));
13
+ }
14
+ function validateResumeIdentity(raw, expected) {
15
+ if (raw.schemaVersion !== 2 ||
16
+ raw.assessmentStatus !== 'incomplete' ||
17
+ raw.preparationStatus !== 'prepared' ||
18
+ raw.requestedReviewerId !== expected.reviewerId)
19
+ throw new Error('resume_requires_incomplete_prepared_run');
20
+ const artifact = z
21
+ .object({
22
+ repository: z.string(),
23
+ base: z.object({ commit: z.string(), tree: z.string() }),
24
+ head: z.object({ commit: z.string(), tree: z.string() }),
25
+ })
26
+ .parse(raw.artifact);
27
+ if (realpathSync(artifact.repository) !== realpathSync(expected.artifact.repository) ||
28
+ ['base', 'head'].some((side) => artifact[side].commit !== expected.artifact[side].commit ||
29
+ artifact[side].tree !== expected.artifact[side].tree))
30
+ throw new Error('resume_comparison_changed');
31
+ }
32
+ function validatePinnedPreparation(state, manifest, publications) {
33
+ if (!Array.isArray(state.entries) ||
34
+ digest(state.entries.map(({ result: _result, ...entry }) => entry)) !== digest(manifest.entries) ||
35
+ digest(state.diff ?? null) !== manifest.diffHash ||
36
+ digest(state.changes) !== manifest.changesHash ||
37
+ digest(state.reviewer) !== digest(manifest.reviewer))
38
+ throw new Error('resume_preparation_changed');
39
+ for (const entry of state.entries) {
40
+ const publication = publicationSchema.parse(publications[entry.assessmentId]);
41
+ if (publication.nodeId !== entry.nodeId ||
42
+ publication.version !== entry.version ||
43
+ digest(publication.content) !== entry.contentHash)
44
+ throw new Error('resume_publication_identity_changed');
45
+ }
46
+ }
47
+ function restoreCheckpointEvidence(evidence) {
48
+ const ledger = new EvidenceLedger();
49
+ for (const [ref, value] of Object.entries(evidence)) {
50
+ const record = z
51
+ .object({
52
+ ref: z.string(),
53
+ text: z.string(),
54
+ provenance: z.record(z.string(), z.unknown()),
55
+ fragments: z
56
+ .array(z.object({
57
+ line: z.number().int().positive(),
58
+ column: z.number().int().nonnegative(),
59
+ text: z.string(),
60
+ }))
61
+ .optional(),
62
+ })
63
+ .parse(value);
64
+ if (record.ref !== ref || ledger.add(record.text, record.provenance, record.fragments).ref !== ref)
65
+ throw new Error('resume_evidence_changed');
66
+ }
67
+ return ledger.records;
68
+ }
69
+ /** Resume only sealed incomplete runs. An interrupted unsealed write is not a trusted checkpoint. */
70
+ export function loadAssessmentCheckpoint(runDirectory, expected) {
71
+ const directory = realpathSync(resolve(runDirectory));
72
+ const statePath = join(directory, 'state.json');
73
+ const raw = readObject(statePath);
74
+ validateResumeIdentity(raw, expected);
75
+ validatePublicationArtifacts(directory, raw, statePath);
76
+ const manifest = readObject(join(directory, 'manifest.json'));
77
+ const files = z.record(z.string(), z.string()).parse(manifest.files);
78
+ if (['state.json', 'publications.json', 'evidence.json'].some((name) => !Object.hasOwn(files, name)))
79
+ throw new Error('resume_checkpoint_unbound');
80
+ const materialPath = join(directory, 'publications.json');
81
+ const publications = readObject(materialPath);
82
+ if (manifest.publicationsHash !== digest(publications))
83
+ throw new Error('resume_publications_changed');
84
+ const state = raw;
85
+ validatePinnedPreparation(state, manifest, publications);
86
+ const evidence = readObject(join(directory, 'evidence.json'));
87
+ const records = restoreCheckpointEvidence(evidence);
88
+ const preparedState = {
89
+ schemaVersion: 1,
90
+ runId: state.runId,
91
+ createdAt: state.createdAt,
92
+ preparationStatus: state.preparationStatus,
93
+ assessmentStatus: 'not_started',
94
+ artifact: state.artifact,
95
+ reviewer: state.reviewer,
96
+ requestedReviewerId: state.requestedReviewerId,
97
+ scopeIdentity: state.scopeIdentity,
98
+ expectedContextCount: state.expectedContextCount,
99
+ entries: state.entries.map(({ result: _result, ...entry }) => ({
100
+ ...entry,
101
+ result: { disposition: 'not_evaluated', adherence: null, confidence: null },
102
+ })),
103
+ gaps: state.gaps,
104
+ limitations: state.limitations,
105
+ diff: state.diff,
106
+ changes: state.changes,
107
+ };
108
+ return {
109
+ prepared: { state: preparedState, statePath, materialPath, manifestPath: join(directory, 'manifest.json') },
110
+ checkpoint: {
111
+ state,
112
+ evidence: records,
113
+ preparationManifest: preparationManifest(manifest),
114
+ },
115
+ };
116
+ }
@@ -0,0 +1,167 @@
1
+ import type { GitIdentity } from './prepare.js';
2
+ export type SourceSide = 'base' | 'head';
3
+ export type Snapshot = {
4
+ side: SourceSide;
5
+ commit: string;
6
+ tree: string;
7
+ };
8
+ export type SourceEntry = Snapshot & {
9
+ path: string;
10
+ object: string;
11
+ mode: string;
12
+ kind: 'file' | 'symlink' | 'submodule';
13
+ };
14
+ export type SourceChange = {
15
+ offset: number;
16
+ kind: 'addition' | 'modification' | 'deletion' | 'rename' | 'type_change';
17
+ base: SourceEntry | null;
18
+ head: SourceEntry | null;
19
+ similarity: number | null;
20
+ };
21
+ export type ChangeInventory = {
22
+ base: Snapshot;
23
+ head: Snapshot;
24
+ status: 'complete' | 'truncated';
25
+ items: SourceChange[];
26
+ next: {
27
+ offset: number;
28
+ detectRenames: boolean;
29
+ } | null;
30
+ renameDetection: 'heuristic' | 'disabled';
31
+ excludedPaths: string[];
32
+ reason?: string;
33
+ };
34
+ type PreparedDiff = {
35
+ change: SourceChange;
36
+ status: 'complete' | 'truncated' | 'unsupported';
37
+ reason?: string;
38
+ patch: string;
39
+ hash: string;
40
+ };
41
+ export type DiffRequest = {
42
+ offset?: number;
43
+ patchLineOffset?: number;
44
+ detectRenames?: boolean;
45
+ };
46
+ export type DiffPage = Page<PreparedDiff, {
47
+ offset: number;
48
+ patchLineOffset: number;
49
+ detectRenames: boolean;
50
+ }> & {
51
+ base: Snapshot;
52
+ head: Snapshot;
53
+ renameDetection: 'heuristic' | 'disabled';
54
+ };
55
+ export type SourceLimits = {
56
+ pageEntries: number;
57
+ searchMatches: number;
58
+ searchFiles: number;
59
+ readLines: number;
60
+ readBytes: number;
61
+ timeoutMs: number;
62
+ };
63
+ /** Provisional response/operation defaults, never total-source capacity limits. */
64
+ export declare const DEFAULT_SOURCE_LIMITS: Readonly<SourceLimits>;
65
+ export declare class SourceAccessError extends Error {
66
+ readonly code: 'invalid_input' | 'invalid_cursor' | 'cancelled' | 'timeout' | 'unavailable';
67
+ constructor(code: 'invalid_input' | 'invalid_cursor' | 'cancelled' | 'timeout' | 'unavailable', message: string);
68
+ }
69
+ type Page<T, C> = {
70
+ status: 'complete' | 'truncated';
71
+ items: T[];
72
+ next: C | null;
73
+ };
74
+ export type SourcePosition = {
75
+ line: number;
76
+ column: number;
77
+ };
78
+ export type ReadRequest = {
79
+ side: SourceSide;
80
+ path: string;
81
+ start?: SourcePosition;
82
+ endLine?: number;
83
+ };
84
+ export type ReadResult = {
85
+ snapshot: Snapshot;
86
+ entry: SourceEntry | null;
87
+ status: 'complete' | 'truncated' | 'unavailable' | 'unsupported';
88
+ reason?: string;
89
+ fragments: Array<{
90
+ line: number;
91
+ column: number;
92
+ text: string;
93
+ }>;
94
+ next: ReadRequest | null;
95
+ };
96
+ export type SearchCursor = {
97
+ scope: string;
98
+ entryOffset: number;
99
+ characterOffset: number;
100
+ };
101
+ export type SourceMatch = {
102
+ entry: SourceEntry;
103
+ line: number;
104
+ column: number;
105
+ endColumn: number;
106
+ };
107
+ export type SearchResult = Page<SourceMatch, SearchCursor> & {
108
+ snapshot: Snapshot;
109
+ path: string | null;
110
+ scannedFiles: number;
111
+ skipped: Array<{
112
+ entry: SourceEntry;
113
+ reason: string;
114
+ }>;
115
+ evidence: 'literal_navigation_only';
116
+ };
117
+ type Control = {
118
+ signal?: AbortSignal;
119
+ };
120
+ /** Passive committed-object access. Does not write state or evaluate guidance. */
121
+ export declare class FixedSnapshotSource {
122
+ readonly limits: Readonly<SourceLimits>;
123
+ private readonly artifact;
124
+ constructor(artifact: GitIdentity, overrides?: Partial<SourceLimits>);
125
+ private snapshot;
126
+ private operation;
127
+ private git;
128
+ private records;
129
+ private entries;
130
+ list(request: {
131
+ side: SourceSide;
132
+ offset?: number;
133
+ }, control?: Control): Promise<Page<SourceEntry, {
134
+ side: SourceSide;
135
+ offset: number;
136
+ }> & {
137
+ snapshot: Snapshot;
138
+ }>;
139
+ changes(request?: {
140
+ offset?: number;
141
+ detectRenames?: boolean;
142
+ }, control?: Control): Promise<Page<SourceChange, {
143
+ offset: number;
144
+ detectRenames: boolean;
145
+ }> & {
146
+ base: Snapshot;
147
+ head: Snapshot;
148
+ renameDetection: 'heuristic' | 'disabled';
149
+ }>;
150
+ /** Complete permitted file inventory without reading patches; metadata is navigation, not assessment. */
151
+ changeInventory(control?: Control): Promise<ChangeInventory>;
152
+ /** Ordinary unified patch fragments; continuations retain the fixed comparison. */
153
+ diff(request?: DiffRequest, control?: Control): Promise<DiffPage>;
154
+ private diffReason;
155
+ private appendPatch;
156
+ private textReason;
157
+ private text;
158
+ read(request: ReadRequest, control?: Control): Promise<ReadResult>;
159
+ private literalMatches;
160
+ search(request: {
161
+ side: SourceSide;
162
+ literal: string;
163
+ path?: string;
164
+ cursor?: SearchCursor;
165
+ }, control?: Control): Promise<SearchResult>;
166
+ }
167
+ export {};