@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/git.js ADDED
@@ -0,0 +1,207 @@
1
+ import { execFileSync } from 'node:child_process';
2
+ import { realpathSync } from 'node:fs';
3
+ export const MAX_PREPARATION_BYTES = 16 * 1024 * 1024;
4
+ export function sensitiveGitPath(path) {
5
+ return path
6
+ .split('/')
7
+ .some((part) => /^\.env(?:\.|$)|^(?:credentials|secrets)(?:\.|$)|\.(?:pem|key|p12|pfx)$/iu.test(part));
8
+ }
9
+ function readableDiffLimits(artifact, options) {
10
+ const timeout = options.timeoutMs ?? 30_000;
11
+ const maxBuffer = options.maxBytes ?? MAX_PREPARATION_BYTES;
12
+ for (const side of ['base', 'head'])
13
+ for (const object of [artifact[side].commit, artifact[side].tree])
14
+ if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u.test(object))
15
+ throw new Error('readable_diff_invalid_identity');
16
+ if (!Number.isSafeInteger(timeout) ||
17
+ timeout < 1 ||
18
+ timeout > 2_147_483_647 ||
19
+ !Number.isSafeInteger(maxBuffer) ||
20
+ maxBuffer < 1)
21
+ throw new Error('readable_diff_invalid_limit');
22
+ return { timeout, maxBuffer };
23
+ }
24
+ /** Ordinary unified Git output, bounded as one complete artifact; never a model transformation. */
25
+ export function readableDiff(artifact, options = {}) {
26
+ const { timeout, maxBuffer } = readableDiffLimits(artifact, options);
27
+ const deadline = Date.now() + timeout;
28
+ const run = (args) => {
29
+ try {
30
+ const remaining = deadline - Date.now();
31
+ if (remaining <= 0)
32
+ throw new Error('readable_diff_deadline');
33
+ return execFileSync('git', [
34
+ '--no-pager',
35
+ '--no-lazy-fetch',
36
+ '--no-replace-objects',
37
+ '--literal-pathspecs',
38
+ `--attr-source=${artifact.head.tree}`,
39
+ '-c',
40
+ 'core.fsmonitor=false',
41
+ '-c',
42
+ 'core.attributesFile=/dev/null',
43
+ '-c',
44
+ 'diff.renameLimit=0',
45
+ '-C',
46
+ artifact.repository,
47
+ ...args,
48
+ ], { env: passiveGitEnvironment(), timeout: remaining, maxBuffer, stdio: ['ignore', 'pipe', 'ignore'] });
49
+ }
50
+ catch {
51
+ throw new Error('readable_diff_unavailable_or_limit_exceeded');
52
+ }
53
+ };
54
+ const decode = (value) => new TextDecoder('utf-8', { fatal: true }).decode(value);
55
+ const actualTrees = decode(run(['rev-parse', `${artifact.base.commit}^{tree}`, `${artifact.head.commit}^{tree}`])).trim();
56
+ if (actualTrees !== `${artifact.base.tree}\n${artifact.head.tree}`)
57
+ throw new Error('readable_diff_identity_changed');
58
+ const common = [
59
+ 'diff',
60
+ '--no-ext-diff',
61
+ '--no-textconv',
62
+ '--no-color',
63
+ '--no-relative',
64
+ '--find-renames=50%',
65
+ '-O/dev/null',
66
+ ];
67
+ const revisions = [artifact.base.commit, artifact.head.commit];
68
+ const records = decode(run([...common, '--name-status', '-z', ...revisions, '--'])).split('\0');
69
+ const files = [];
70
+ const excludedPaths = [];
71
+ for (let index = 0; index < records.length - 1;) {
72
+ const status = records[index++];
73
+ const paths = [records[index++]];
74
+ if (/^[RC]/u.test(status))
75
+ paths.push(records[index++]);
76
+ if (paths.some((path) => !path))
77
+ throw new Error('readable_diff_invalid_name_record');
78
+ (paths.some(sensitiveGitPath) ? excludedPaths : files).push(...paths);
79
+ }
80
+ const eligible = [...new Set(files)].sort();
81
+ const omitted = [...new Set(excludedPaths)].sort();
82
+ const patch = eligible.length
83
+ ? decode(run([...common, '--src-prefix=a/', '--dst-prefix=b/', ...revisions, '--', ...eligible]))
84
+ : '';
85
+ const stat = eligible.length ? decode(run([...common, '--stat', ...revisions, '--', ...eligible])) : '';
86
+ return { patch, stat, files: eligible, excludedPaths: omitted };
87
+ }
88
+ export function passiveGitEnvironment() {
89
+ const env = { ...process.env };
90
+ for (const name of Object.keys(env))
91
+ if (name.startsWith('GIT_'))
92
+ delete env[name];
93
+ return {
94
+ ...env,
95
+ GIT_NO_REPLACE_OBJECTS: '1',
96
+ GIT_NO_LAZY_FETCH: '1',
97
+ GIT_OPTIONAL_LOCKS: '0',
98
+ GIT_CONFIG_NOSYSTEM: '1',
99
+ GIT_ATTR_NOSYSTEM: '1',
100
+ GIT_CONFIG_GLOBAL: '/dev/null',
101
+ LC_ALL: 'C',
102
+ };
103
+ }
104
+ function git(repository, args) {
105
+ return execFileSync('git', [
106
+ '--no-pager',
107
+ '--no-lazy-fetch',
108
+ '--no-replace-objects',
109
+ '-c',
110
+ 'core.fsmonitor=false',
111
+ '-C',
112
+ repository,
113
+ ...args,
114
+ ], {
115
+ encoding: 'utf8',
116
+ env: passiveGitEnvironment(),
117
+ stdio: ['ignore', 'pipe', 'pipe'],
118
+ }).trim();
119
+ }
120
+ export function fixGitIdentity(repository, base, head) {
121
+ const root = realpathSync(git(repository, ['rev-parse', '--show-toplevel']));
122
+ const resolve = (ref) => git(root, ['rev-parse', '--verify', '--end-of-options', `${ref}^{commit}`]);
123
+ const baseCommit = resolve(base);
124
+ const headCommit = resolve(head);
125
+ return {
126
+ kind: 'git_comparison',
127
+ repository: root,
128
+ repositoryEnvironment: repositoryEnvironment(root),
129
+ base: { suppliedRef: base, commit: baseCommit, tree: git(root, ['rev-parse', `${baseCommit}^{tree}`]) },
130
+ head: { suppliedRef: head, commit: headCommit, tree: git(root, ['rev-parse', `${headCommit}^{tree}`]) },
131
+ limitations: [
132
+ 'Only the fixed commits identify the artifact. Working-tree and index changes are excluded. Source retrieval does not establish semantic coverage or evaluate assessments.',
133
+ ],
134
+ };
135
+ }
136
+ function optionalGit(root, args) {
137
+ try {
138
+ return git(root, args) || undefined;
139
+ }
140
+ catch {
141
+ return undefined;
142
+ }
143
+ }
144
+ export function repositoryEnvironment(root) {
145
+ const remotes = optionalGit(root, ['remote'])?.split('\n') ?? [];
146
+ const branch = optionalGit(root, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
147
+ const tracked = branch ? optionalGit(root, ['config', '--get', `branch.${branch}.remote`]) : undefined;
148
+ const selected = tracked && tracked !== '.' && remotes.includes(tracked)
149
+ ? tracked
150
+ : remotes.includes('origin')
151
+ ? 'origin'
152
+ : remotes.length === 1
153
+ ? remotes[0]
154
+ : undefined;
155
+ if (!selected)
156
+ return { status: 'unavailable', reason: remotes.length ? 'ambiguous_remote' : 'no_remote' };
157
+ return parseRepositoryRemote(optionalGit(root, ['remote', 'get-url', selected]));
158
+ }
159
+ /** Parse attribution independently of Git discovery; no URL normalization repairs. */
160
+ function assertRemoteCoordinates(provider, owner, parts, name) {
161
+ // Match v2-core's reportedEnvironmentSchema without an unpublished runtime dependency.
162
+ // Regression tests validate these emitted values against that maintained schema.
163
+ if (provider.length > 253 ||
164
+ !/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/u.test(provider) ||
165
+ owner.length > 200 ||
166
+ !/^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/u.test(owner) ||
167
+ parts.some((part) => part === '.' || part === '..') ||
168
+ !name ||
169
+ name.length > 100 ||
170
+ !/^[A-Za-z0-9._-]+$/u.test(name) ||
171
+ name === '.' ||
172
+ name === '..' ||
173
+ name.endsWith('.git'))
174
+ throw new Error();
175
+ }
176
+ function remoteCoordinates(address, url) {
177
+ // Preserve the original namespace: URL.pathname silently resolves dot segments.
178
+ const parsed = address.match(/^[^:]+:\/\/([^/?#]*)(\/[^?#]*)?/u);
179
+ const host = parsed?.[1]?.replace(/^.*@/u, '').replace(/:\d*$/u, '').toLowerCase();
180
+ if (host !== url.hostname.toLowerCase())
181
+ throw new Error();
182
+ const parts = (parsed?.[2] ?? '')
183
+ .replace(/^\/+|\/+$/gu, '')
184
+ .replace(/\.git$/u, '')
185
+ .split('/');
186
+ const name = parts.pop();
187
+ const provider = url.hostname.toLowerCase();
188
+ const owner = parts.join('/');
189
+ assertRemoteCoordinates(provider, owner, parts, name);
190
+ return { status: 'reported', provider, owner, name };
191
+ }
192
+ export function parseRepositoryRemote(remote) {
193
+ try {
194
+ if (!remote)
195
+ throw new Error();
196
+ const address = remote.includes('://')
197
+ ? remote
198
+ : remote.replace(/^(?:[^@/:]+@)?([^/:]+):(.+)$/u, 'ssh://$1/$2');
199
+ const url = new URL(address);
200
+ if (!['https:', 'http:', 'ssh:', 'git:'].includes(url.protocol))
201
+ throw new Error();
202
+ return remoteCoordinates(address, url);
203
+ }
204
+ catch {
205
+ return { status: 'unavailable', reason: 'not_determined' };
206
+ }
207
+ }
@@ -0,0 +1,90 @@
1
+ import { z } from 'zod';
2
+ import { type HistoryConfiguration } from './presentation.js';
3
+ declare const githubInputSchema: z.ZodObject<{
4
+ version: z.ZodLiteral<1>;
5
+ repository: z.ZodString;
6
+ pr: z.ZodNumber;
7
+ reviewer: z.ZodString;
8
+ base: z.ZodString;
9
+ targetBase: z.ZodOptional<z.ZodString>;
10
+ head: z.ZodString;
11
+ baseBranch: z.ZodDefault<z.ZodString>;
12
+ githubRun: z.ZodOptional<z.ZodString>;
13
+ githubAttempt: z.ZodOptional<z.ZodNumber>;
14
+ }, z.core.$strict>;
15
+ type GitHubInput = z.infer<typeof githubInputSchema>;
16
+ type Requester = (path: string, method?: string, body?: unknown) => Promise<unknown>;
17
+ export declare function githubRequester(repository: string, token: string, fetcher?: typeof fetch): Requester;
18
+ export declare function findAssessmentComment(c: HistoryConfiguration, request: Requester): Promise<Record<string, unknown> | null>;
19
+ export declare function collectGitHubContext(c: GitHubInput, pr: unknown, request: Requester, includeHistory: boolean, token?: string): Promise<Record<string, unknown>>;
20
+ export declare function prepareGitHubAssessment(options: {
21
+ repository: string;
22
+ prNumber: number;
23
+ reviewer: string;
24
+ outputDir: string;
25
+ baseBranch?: string;
26
+ collectPrContext?: boolean;
27
+ fixed?: {
28
+ base: string;
29
+ head: string;
30
+ };
31
+ token?: string;
32
+ fetch?: typeof fetch;
33
+ }): Promise<{
34
+ exitCode: number;
35
+ directory: string;
36
+ repository: string;
37
+ base: string;
38
+ targetBase: string;
39
+ head: string;
40
+ prContextPath: string;
41
+ }>;
42
+ type DiffAnchors = Map<string, Set<number>>;
43
+ export declare function parseDiffAnchors(diff: string): DiffAnchors;
44
+ export type InlineComment = {
45
+ path: string;
46
+ line: number;
47
+ side: 'LEFT' | 'RIGHT';
48
+ start_line?: number;
49
+ start_side?: 'LEFT' | 'RIGHT';
50
+ body: string;
51
+ };
52
+ type SourceText = {
53
+ blob: string;
54
+ text: string;
55
+ };
56
+ type InlineOptions = {
57
+ diff: string;
58
+ source: (side: 'base' | 'head', path: string) => SourceText;
59
+ existingComments?: unknown[];
60
+ max?: number;
61
+ };
62
+ export declare function buildInlineReview(input: unknown, evidenceInput: unknown, options: InlineOptions): {
63
+ comments: InlineComment[];
64
+ omitted: number;
65
+ duplicates: number;
66
+ };
67
+ /** Validate caller-controlled retained records before using their judgments for a privileged write.
68
+ * Hashes detect changed material; they do not authenticate a caller able to replace the whole bundle. */
69
+ export declare function validatePublicationArtifacts(runDir: string, state: Record<string, unknown>, statePath: string): void;
70
+ type PublishOptions = {
71
+ runDir: string;
72
+ githubDir: string;
73
+ postComment?: boolean;
74
+ inlineComments?: boolean;
75
+ summaryFile?: string;
76
+ artifactUrl?: string;
77
+ dryRun?: boolean;
78
+ token?: string;
79
+ fetch?: typeof fetch;
80
+ };
81
+ export declare function publishGitHubAssessment(options: PublishOptions): Promise<{
82
+ exitCode: number;
83
+ status: string;
84
+ commentStatus: string;
85
+ inlineStatus: string;
86
+ omittedInline: number;
87
+ duplicateInline: number;
88
+ commentUrl: string;
89
+ }>;
90
+ export {};