docattest 0.0.0-stage → 0.1.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.
Files changed (139) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +147 -2
  3. package/dist/agents/claude.json +30 -0
  4. package/dist/agents/cursor.json +19 -0
  5. package/dist/agents/gemini.json +27 -0
  6. package/dist/agents/index.json +3 -0
  7. package/dist/api/adapter.d.ts +231 -0
  8. package/dist/api/adapter.js +2 -0
  9. package/dist/api/attestation.d.ts +76 -0
  10. package/dist/api/attestation.js +2 -0
  11. package/dist/api/audit.d.ts +56 -0
  12. package/dist/api/audit.js +2 -0
  13. package/dist/api/config.d.ts +44 -0
  14. package/dist/api/config.js +2 -0
  15. package/dist/api/constants.d.ts +35 -0
  16. package/dist/api/constants.js +56 -0
  17. package/dist/api/errors.d.ts +15 -0
  18. package/dist/api/errors.js +22 -0
  19. package/dist/api/impact.d.ts +49 -0
  20. package/dist/api/impact.js +2 -0
  21. package/dist/api/project.d.ts +64 -0
  22. package/dist/api/project.js +2 -0
  23. package/dist/api/report.d.ts +107 -0
  24. package/dist/api/report.js +2 -0
  25. package/dist/client/answers.d.ts +17 -0
  26. package/dist/client/answers.js +23 -0
  27. package/dist/client/core.d.ts +18 -0
  28. package/dist/client/core.js +58 -0
  29. package/dist/client/place.d.ts +14 -0
  30. package/dist/client/place.js +37 -0
  31. package/dist/client/project.d.ts +3 -0
  32. package/dist/client/project.js +98 -0
  33. package/dist/client/workspace.d.ts +12 -0
  34. package/dist/client/workspace.js +72 -0
  35. package/dist/compare-strings.d.ts +2 -0
  36. package/dist/compare-strings.js +5 -0
  37. package/dist/core-binary/locate.js +113 -0
  38. package/dist/core-binary/package.js +70 -0
  39. package/dist/core.json +4 -0
  40. package/dist/files/disk.d.ts +4 -0
  41. package/dist/files/disk.js +67 -0
  42. package/dist/files/glob.d.ts +10 -0
  43. package/dist/files/glob.js +21 -0
  44. package/dist/files/ignored.d.ts +14 -0
  45. package/dist/files/ignored.js +14 -0
  46. package/dist/files/memory.d.ts +5 -0
  47. package/dist/files/memory.js +26 -0
  48. package/dist/files/source.d.ts +22 -0
  49. package/dist/files/source.js +17 -0
  50. package/dist/index.d.ts +10 -0
  51. package/dist/index.js +6 -0
  52. package/dist/json.d.ts +16 -0
  53. package/dist/json.js +43 -0
  54. package/dist/language/cache.js +18 -0
  55. package/dist/language/citations/listing.js +64 -0
  56. package/dist/language/citations/match.js +14 -0
  57. package/dist/language/citations/tests-in-file.js +101 -0
  58. package/dist/language/compiler.js +73 -0
  59. package/dist/language/description.js +24 -0
  60. package/dist/language/impact/affected.js +50 -0
  61. package/dist/language/impact/fingerprint.js +123 -0
  62. package/dist/language/impact/graph.js +72 -0
  63. package/dist/language/impact/lookup.js +100 -0
  64. package/dist/language/impact/program.js +87 -0
  65. package/dist/language/impact/renames.js +57 -0
  66. package/dist/language/impact/revision.js +62 -0
  67. package/dist/language/impact/units.js +80 -0
  68. package/dist/language/index.js +10 -0
  69. package/dist/language/inventory/observables.js +56 -0
  70. package/dist/language/inventory/plan.js +72 -0
  71. package/dist/language/inventory/probe.js +150 -0
  72. package/dist/language/languages.js +43 -0
  73. package/dist/language/node/dependency.js +34 -0
  74. package/dist/language/node/exports-map.js +92 -0
  75. package/dist/language/program/exports.js +29 -0
  76. package/dist/language/program/file-names.js +13 -0
  77. package/dist/language/program/globals.js +38 -0
  78. package/dist/language/program/host.js +91 -0
  79. package/dist/language/program/options.js +48 -0
  80. package/dist/language/program/program.js +41 -0
  81. package/dist/language/run/attempt.js +100 -0
  82. package/dist/language/run/facts.js +109 -0
  83. package/dist/language/run/host.js +73 -0
  84. package/dist/language/run/jobs.js +37 -0
  85. package/dist/language/run/pool.js +75 -0
  86. package/dist/language/run/protocol.js +37 -0
  87. package/dist/language/run/result.js +18 -0
  88. package/dist/language/run/runner.js +115 -0
  89. package/dist/language/run/sourcemap.js +43 -0
  90. package/dist/language/run/spawn.js +40 -0
  91. package/dist/language/run/transpile.js +50 -0
  92. package/dist/language/session.js +42 -0
  93. package/dist/language/surfaces/packages.js +71 -0
  94. package/dist/language/surfaces/resolve.js +48 -0
  95. package/dist/language/surfaces/specs.js +32 -0
  96. package/dist/language/surfaces/stale.js +23 -0
  97. package/dist/language/symbols.js +95 -0
  98. package/dist/language/syntax/doc-comments.js +90 -0
  99. package/dist/language/syntax/doc-prose.js +23 -0
  100. package/dist/language/syntax/expression.js +52 -0
  101. package/dist/language/syntax/imports.js +83 -0
  102. package/dist/language/syntax/lexical.js +41 -0
  103. package/dist/language/syntax/parse.js +11 -0
  104. package/dist/language/syntax/prose.js +11 -0
  105. package/dist/language/syntax/setup-module.js +88 -0
  106. package/dist/language/ts.cjs +9 -0
  107. package/dist/language/worker/cases.js +73 -0
  108. package/dist/language/worker/compile.js +15 -0
  109. package/dist/language/worker/console.js +10 -0
  110. package/dist/language/worker/context.js +16 -0
  111. package/dist/language/worker/describe.js +107 -0
  112. package/dist/language/worker/example.js +27 -0
  113. package/dist/language/worker/facts.js +69 -0
  114. package/dist/language/worker/host-client.js +55 -0
  115. package/dist/language/worker/main.js +71 -0
  116. package/dist/language/worker/network.js +35 -0
  117. package/dist/language/worker/observe.js +39 -0
  118. package/dist/language/worker/registry.js +78 -0
  119. package/dist/language/worker/setup-facts.js +50 -0
  120. package/dist/language/worker/strays.js +37 -0
  121. package/dist/launcher/main.js +38 -0
  122. package/dist/platforms.json +40 -0
  123. package/dist/protocol/context.js +48 -0
  124. package/dist/protocol/main.js +22 -0
  125. package/dist/protocol/methods.js +178 -0
  126. package/dist/protocol/output.js +40 -0
  127. package/dist/protocol/overlay.js +31 -0
  128. package/dist/protocol/serve.js +24 -0
  129. package/dist/protocol/server.js +108 -0
  130. package/dist/protocol/wire.js +117 -0
  131. package/dist/schema/agent.json +162 -0
  132. package/dist/schema/attestations.json +307 -0
  133. package/dist/schema/kit.json +190 -0
  134. package/dist/schema/language.json +162 -0
  135. package/dist/schema/messages.json +68 -0
  136. package/dist/schema/methods.json +412 -0
  137. package/dist/schema/project.json +113 -0
  138. package/dist/schema/results.json +249 -0
  139. package/package.json +73 -4
@@ -0,0 +1,32 @@
1
+ import * as path from 'node:path';
2
+ import { normalise } from '../../files/source.js';
3
+ import { projectObject } from '../../json.js';
4
+ /** What in-memory projects, and projects without a package name, import path surfaces as. */
5
+ const FIXTURE_PACKAGE = 'docattest-fixture';
6
+ /**
7
+ * Normalise configured surfaces. A `./path` is imported under the project's package name
8
+ * (`<name>/<surface>` for surfaces other than `default`); a bare specifier is imported as
9
+ * itself and resolved by the runtime; the object form names both.
10
+ */
11
+ export function surfaceSpecs(surfaces, files) {
12
+ const pkg = packageName(files);
13
+ return surfaces.map(({ name, entry }) => {
14
+ if (typeof entry !== 'string') {
15
+ return { name, import: entry.import, path: normalise(entry.path) };
16
+ }
17
+ if (!isPathLike(entry))
18
+ return { name, import: entry };
19
+ const specifier = name === 'default' ? pkg : `${pkg}/${name}`;
20
+ return { name, import: specifier, path: path.posix.normalize(normalise(entry)) };
21
+ });
22
+ }
23
+ function isPathLike(entry) {
24
+ return entry.startsWith('.') || entry.startsWith('/');
25
+ }
26
+ function packageName(files) {
27
+ if (files.memory)
28
+ return FIXTURE_PACKAGE;
29
+ const name = projectObject(files.read('package.json'), 'package.json')?.name;
30
+ return typeof name === 'string' && name ? name : FIXTURE_PACKAGE;
31
+ }
32
+ //# sourceMappingURL=specs.js.map
@@ -0,0 +1,23 @@
1
+ import { nearestPackage, projectPath, sameDirectory, workspacePackages, } from './packages.js';
2
+ /**
3
+ * A warning when a bare-specifier surface resolved to an installed copy of a workspace
4
+ * package rather than the workspace package itself, and the versions differ: the pages
5
+ * are then checked against old code. A symlink to the workspace (the normal install) is
6
+ * the same directory and never warns.
7
+ */
8
+ export function staleCopyWarning(files, spec, entry) {
9
+ const installed = nearestPackage(files, entry);
10
+ if (!installed)
11
+ return undefined;
12
+ const workspace = workspacePackages(files).find((p) => p.name === installed.name);
13
+ if (!workspace || sameDirectory(files, installed.dir, workspace.dir))
14
+ return undefined;
15
+ if (installed.version === workspace.version)
16
+ return undefined;
17
+ const show = (p) => `${projectPath(files, p.dir)} (${p.version ?? 'no version'})`;
18
+ return (`"${spec.import}" resolves to ${show(installed)}, ` +
19
+ `not the workspace package ${show(workspace)}; ` +
20
+ 'pages are checked against the installed copy. Reinstall so it links to the workspace, ' +
21
+ 'or point the surface at the build with { "import", "path" }');
22
+ }
23
+ //# sourceMappingURL=stale.js.map
@@ -0,0 +1,95 @@
1
+ import * as path from 'node:path';
2
+ import { citedSymbols } from './citations/listing.js';
3
+ import { blockFile, isSourceFile, pagePath } from './languages.js';
4
+ import { expressionIdentifiers } from './syntax/expression.js';
5
+ import { helperSymbols, objectKeys } from './syntax/setup-module.js';
6
+ import { dedupe, importedSymbols } from './syntax/imports.js';
7
+ const stem = (file) => file.replace(/\.[mc]?[jt]sx?$/, '');
8
+ /** Which surface symbols each attestation exercises, from syntax and the checker's exports. */
9
+ export class SymbolResolver {
10
+ files;
11
+ surfaces;
12
+ compiler;
13
+ setup;
14
+ byImport;
15
+ constructor(files, surfaces, compiler, setup) {
16
+ this.files = files;
17
+ this.surfaces = surfaces;
18
+ this.compiler = compiler;
19
+ this.setup = setup;
20
+ this.byImport = new Map(surfaces.map((s) => [s.spec.import, s.spec.name]));
21
+ }
22
+ /** Symbols of one attestation, each attributed to the surface it was reached through. */
23
+ of(attestation) {
24
+ if (attestation.kind === 'example')
25
+ return this.example(attestation);
26
+ if (attestation.kind === 'fact')
27
+ return attestation.expression ? this.fact(attestation) : [];
28
+ if (attestation.kind === 'test')
29
+ return this.citation(attestation);
30
+ return this.cases(attestation);
31
+ }
32
+ citation(t) {
33
+ const code = t.error === undefined ? this.files.read(t.file) : undefined;
34
+ if (code === undefined || !isSourceFile(t.file))
35
+ return [];
36
+ const file = pagePath(this.files, t.file);
37
+ return this.known(citedSymbols(file, code, t, this.surfaceOf(file)));
38
+ }
39
+ example(e) {
40
+ const file = blockFile(this.files.root, e);
41
+ const imported = this.known(importedSymbols(file, e.code, (s) => this.byImport.get(s)));
42
+ return e.owner === undefined ? imported : dedupe([...this.owner(e.page, e.owner), ...imported]);
43
+ }
44
+ // A doc-comment example attests its declaration on the surfaces that export that very
45
+ // declaration; when none does (a surface that points at built output), on every
46
+ // surface that exports the name; otherwise it names the symbol without a surface.
47
+ owner(page, name) {
48
+ const file = pagePath(this.files, page);
49
+ const names = this.surfaces.map((s) => s.spec.name);
50
+ const declaring = names.filter((s) => this.compiler.origins(s).get(name)?.has(file));
51
+ const exporting = names.filter((s) => this.compiler.exports(s)?.includes(name));
52
+ const surfaces = declaring.length ? declaring : exporting;
53
+ return surfaces.length ? surfaces.map((surface) => ({ name, surface })) : [{ name }];
54
+ }
55
+ fact(f) {
56
+ const identifiers = expressionIdentifiers(f.expression);
57
+ const exported = new Set(this.compiler.exports(f.surface) ?? []);
58
+ const direct = identifiers
59
+ .filter((n) => exported.has(n))
60
+ .map((name) => ({ name, surface: f.surface }));
61
+ const helpers = this.setupKeys('facts').filter((k) => identifiers.includes(k) && !exported.has(k));
62
+ return dedupe([...direct, ...helpers.flatMap((h) => this.helper('facts', h))]);
63
+ }
64
+ cases(c) {
65
+ return this.helper('cases', c.runner);
66
+ }
67
+ helper(group, key) {
68
+ const code = this.setup === undefined ? undefined : this.files.read(this.setup);
69
+ if (this.setup === undefined || code === undefined)
70
+ return [];
71
+ const file = pagePath(this.files, this.setup);
72
+ return this.known(helperSymbols(file, code, group, key, this.surfaceOf(file)));
73
+ }
74
+ setupKeys(group) {
75
+ const code = this.setup === undefined ? undefined : this.files.read(this.setup);
76
+ return this.setup === undefined || code === undefined
77
+ ? []
78
+ : objectKeys(this.setup, code, group);
79
+ }
80
+ /** A setup module or test file may import a surface by specifier or by a relative path. */
81
+ surfaceOf(from) {
82
+ return (specifier) => {
83
+ const named = this.byImport.get(specifier);
84
+ if (named || !specifier.startsWith('.'))
85
+ return named;
86
+ const target = stem(path.resolve(path.dirname(from), specifier));
87
+ return this.surfaces.find((s) => s.entry !== undefined && stem(s.entry) === target)?.spec
88
+ .name;
89
+ };
90
+ }
91
+ known(refs) {
92
+ return refs.filter((r) => r.surface !== undefined && this.compiler.exports(r.surface)?.includes(r.name));
93
+ }
94
+ }
95
+ //# sourceMappingURL=symbols.js.map
@@ -0,0 +1,90 @@
1
+ import ts from '../ts.cjs';
2
+ import { prose } from './prose.js';
3
+ import { asserts } from './lexical.js';
4
+ import { parseSource } from './parse.js';
5
+ /** `@example` blocks in doc comments whose first line is `// check` or `// compile`. */
6
+ export function docCommentExamples(page, text) {
7
+ const source = parseSource(page, text);
8
+ const out = [];
9
+ const seen = new Set();
10
+ for (const statement of source.statements) {
11
+ for (const range of ts.getLeadingCommentRanges(text, statement.pos) ?? []) {
12
+ const comment = text.slice(range.pos, range.end);
13
+ if (!comment.startsWith('/**') || seen.has(range.pos))
14
+ continue;
15
+ seen.add(range.pos);
16
+ const line = source.getLineAndCharacterOfPosition(range.pos).line + 1;
17
+ const owner = exportedName(statement);
18
+ for (const ex of examplesIn(comment)) {
19
+ const id = `${page}:${line}:example:${out.length}`;
20
+ const weak = ex.mode === 'check' && !asserts(ex.code);
21
+ const { mode, network, code, claim } = ex;
22
+ const example = {
23
+ id,
24
+ page,
25
+ line,
26
+ kind: 'example',
27
+ claim,
28
+ lang: 'ts',
29
+ mode,
30
+ network,
31
+ code,
32
+ weak,
33
+ };
34
+ out.push(owner === undefined ? example : { ...example, owner });
35
+ }
36
+ }
37
+ }
38
+ return out;
39
+ }
40
+ function examplesIn(comment) {
41
+ const lines = comment
42
+ .replace(/^\/\*\*/, '')
43
+ .replace(/\*\/$/, '')
44
+ .split('\n')
45
+ .map((l) => l.replace(/^\s*\* ?/, ''));
46
+ const firstTag = lines.findIndex((l) => /^\s*@\w/.test(l));
47
+ const claim = prose(lines.slice(0, Math.max(0, firstTag)).join(' '));
48
+ return lines.flatMap((l, k) => {
49
+ if (!/^\s*@example\b/.test(l))
50
+ return [];
51
+ const example = exampleBody(lines.slice(k + 1));
52
+ return example ? [{ ...example, claim }] : [];
53
+ });
54
+ }
55
+ function exampleBody(following) {
56
+ let body = following.slice(0, indexOrEnd(following, (l) => /^\s*@\w/.test(l)));
57
+ while (body[0]?.trim() === '')
58
+ body = body.slice(1);
59
+ if (body[0] !== undefined && /^\s*```/.test(body[0])) {
60
+ body = body.slice(1);
61
+ body = body.slice(0, indexOrEnd(body, (b) => /^\s*```\s*$/.test(b)));
62
+ }
63
+ const tag = /^\s*\/\/\s*(check|compile)(\s+network)?\s*$/.exec(body[0] ?? '');
64
+ if (!tag)
65
+ return undefined;
66
+ const mode = tag[1] === 'check' ? 'check' : 'compile';
67
+ return {
68
+ mode,
69
+ network: tag[2] !== undefined,
70
+ code: body.slice(1).join('\n').replace(/\s+$/, ''),
71
+ };
72
+ }
73
+ function indexOrEnd(lines, test) {
74
+ const index = lines.findIndex(test);
75
+ return index < 0 ? lines.length : index;
76
+ }
77
+ function exportedName(statement) {
78
+ const modifiers = ts.canHaveModifiers(statement) ? (ts.getModifiers(statement) ?? []) : [];
79
+ if (!modifiers.some((m) => m.kind === ts.SyntaxKind.ExportKeyword))
80
+ return undefined;
81
+ if (modifiers.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword))
82
+ return 'default';
83
+ if (ts.isVariableStatement(statement)) {
84
+ const declaration = statement.declarationList.declarations[0];
85
+ return declaration && ts.isIdentifier(declaration.name) ? declaration.name.text : undefined;
86
+ }
87
+ const name = statement.name;
88
+ return name && ts.isIdentifier(name) ? name.text : undefined;
89
+ }
90
+ //# sourceMappingURL=doc-comments.js.map
@@ -0,0 +1,23 @@
1
+ import { prose } from './prose.js';
2
+ const DOC_COMMENT = /\/\*\*[\s\S]*?\*\//g;
3
+ /** The descriptions of the doc comments in a source file: the prose before the first tag. */
4
+ export function docCommentProse(text) {
5
+ return [...text.matchAll(DOC_COMMENT)].map((match) => {
6
+ const start = lineAt(text, match.index);
7
+ const end = start + match[0].split('\n').length - 1;
8
+ return { text: description(match[0]), start, end };
9
+ });
10
+ }
11
+ function description(comment) {
12
+ const lines = comment
13
+ .replace(/^\/\*\*/, '')
14
+ .replace(/\*\/$/, '')
15
+ .split('\n')
16
+ .map((l) => l.replace(/^\s*\* ?/, ''));
17
+ const tag = lines.findIndex((l) => /^\s*@\w/.test(l));
18
+ return prose(lines.slice(0, tag < 0 ? lines.length : tag).join(' '));
19
+ }
20
+ function lineAt(text, index) {
21
+ return text.slice(0, index).split('\n').length;
22
+ }
23
+ //# sourceMappingURL=doc-prose.js.map
@@ -0,0 +1,52 @@
1
+ import ts from '../ts.cjs';
2
+ import { parseSource, unique } from './parse.js';
3
+ const wrap = (expression) => `(${expression}\n);`;
4
+ /** Why a fact expression is not exactly one expression, or undefined when it is. */
5
+ export function expressionProblem(expression) {
6
+ const out = ts.transpileModule(wrap(expression), {
7
+ reportDiagnostics: true,
8
+ compilerOptions: { target: ts.ScriptTarget.ES2022 },
9
+ });
10
+ const [first] = out.diagnostics ?? [];
11
+ if (first) {
12
+ const reason = ts.flattenDiagnosticMessageText(first.messageText, ' ');
13
+ return `cannot parse fact expression \`${expression}\`: ${reason}`;
14
+ }
15
+ const source = parseSource('fact.ts', wrap(expression));
16
+ const [statement] = source.statements;
17
+ if (source.statements.length !== 1 || !statement || !ts.isExpressionStatement(statement)) {
18
+ return `fact expression \`${expression}\` must be a single expression`;
19
+ }
20
+ return undefined;
21
+ }
22
+ /** Free identifiers of an expression: not property names, not its own parameters. */
23
+ export function expressionIdentifiers(expression) {
24
+ const names = [];
25
+ const visit = (node) => {
26
+ if (ts.isIdentifier(node) && !isBindingOrMember(node) && !isParameter(node)) {
27
+ names.push(node.text);
28
+ }
29
+ ts.forEachChild(node, visit);
30
+ };
31
+ visit(parseSource('fact.ts', wrap(expression)));
32
+ return unique(names);
33
+ }
34
+ function isBindingOrMember(node) {
35
+ const p = node.parent;
36
+ return ((ts.isPropertyAccessExpression(p) && p.name === node) ||
37
+ (ts.isPropertyAssignment(p) && p.name === node) ||
38
+ (ts.isParameter(p) && p.name === node) ||
39
+ (ts.isBindingElement(p) && p.name === node) ||
40
+ (ts.isVariableDeclaration(p) && p.name === node));
41
+ }
42
+ // A use of a parameter of an enclosing function in the expression, as `r` in `xs.map((r) => r.a)`.
43
+ function isParameter(node) {
44
+ const owner = ts.findAncestor(node.parent, (p) => ts.isFunctionLike(p) && p.parameters.some((param) => binds(param.name, node.text)));
45
+ return owner !== undefined;
46
+ }
47
+ function binds(name, text) {
48
+ if (ts.isIdentifier(name))
49
+ return name.text === text;
50
+ return name.elements.some((el) => !ts.isOmittedExpression(el) && binds(el.name, text));
51
+ }
52
+ //# sourceMappingURL=expression.js.map
@@ -0,0 +1,83 @@
1
+ import ts from '../ts.cjs';
2
+ import { parseSource } from './parse.js';
3
+ /** Surface symbols a module imports: named, default and namespace member accesses. */
4
+ export function importedSymbols(fileName, code, surfaceOf) {
5
+ const source = parseSource(fileName, code);
6
+ const refs = [];
7
+ const namespaces = new Map();
8
+ for (const bound of surfaceImports(source, surfaceOf)) {
9
+ if (bound.kind === 'namespace')
10
+ namespaces.set(bound.local, bound.surface);
11
+ else
12
+ refs.push({ name: bound.name, surface: bound.surface });
13
+ }
14
+ if (namespaces.size)
15
+ refs.push(...namespaceMembers(source, namespaces));
16
+ return dedupe(refs);
17
+ }
18
+ /** What a module's import declarations bind from surfaces, in source order. */
19
+ export function surfaceImports(source, surfaceOf) {
20
+ return source.statements.flatMap((statement) => {
21
+ const surface = importSurface(statement, surfaceOf);
22
+ if (!surface || !ts.isImportDeclaration(statement))
23
+ return [];
24
+ return clauseImports(statement.importClause, surface);
25
+ });
26
+ }
27
+ // The default import first, then the named imports or the namespace, as written.
28
+ function clauseImports(clause, surface) {
29
+ if (!clause)
30
+ return [];
31
+ const found = [];
32
+ if (clause.name) {
33
+ found.push({ kind: 'symbol', local: clause.name.text, name: 'default', surface });
34
+ }
35
+ const bindings = clause.namedBindings;
36
+ if (bindings && ts.isNamespaceImport(bindings)) {
37
+ found.push({ kind: 'namespace', local: bindings.name.text, surface });
38
+ }
39
+ else if (bindings) {
40
+ for (const el of bindings.elements) {
41
+ const name = (el.propertyName ?? el.name).text;
42
+ found.push({ kind: 'symbol', local: el.name.text, name, surface });
43
+ }
44
+ }
45
+ return found;
46
+ }
47
+ /** The surface an import declaration's specifier names. */
48
+ export function importSurface(statement, surfaceOf) {
49
+ if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
50
+ return undefined;
51
+ }
52
+ return surfaceOf(statement.moduleSpecifier.text);
53
+ }
54
+ function namespaceMembers(source, namespaces) {
55
+ const refs = [];
56
+ const visit = (node) => {
57
+ if (ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.expression)) {
58
+ const surface = namespaces.get(node.expression.text);
59
+ if (surface)
60
+ refs.push({ name: node.name.text, surface });
61
+ }
62
+ if (ts.isQualifiedName(node) && ts.isIdentifier(node.left)) {
63
+ const surface = namespaces.get(node.left.text);
64
+ if (surface)
65
+ refs.push({ name: node.right.text, surface });
66
+ }
67
+ ts.forEachChild(node, visit);
68
+ };
69
+ visit(source);
70
+ return refs;
71
+ }
72
+ /** Symbol references without repeats, in first-seen order. */
73
+ export function dedupe(refs) {
74
+ const seen = new Set();
75
+ return refs.filter((r) => {
76
+ const key = `${r.surface ?? ''}\0${r.name}`;
77
+ if (seen.has(key))
78
+ return false;
79
+ seen.add(key);
80
+ return true;
81
+ });
82
+ }
83
+ //# sourceMappingURL=imports.js.map
@@ -0,0 +1,41 @@
1
+ const ASSERTION = /\bassert\s*[.(]/;
2
+ /** Whether example code asserts anything; without an assertion it is weak coverage. */
3
+ export function asserts(code) {
4
+ return ASSERTION.test(code);
5
+ }
6
+ // A code span names a symbol when it starts with it: `retry`, `retry(fn)`, `new Client()`,
7
+ // `RETRY_DEFAULTS.maxAttempts`. `retry-after` and `retry.ts` are other things.
8
+ const LEADING = /^(?:new\s+|await\s+)?([A-Za-z_$][\w$]*)(?![\w$\-/@'"]|\.(?:[mc]?[jt]sx?|json|md|ya?ml)$)/;
9
+ /** The one of `symbols` an inline code span names, or null. */
10
+ export function mentioned(span, symbols) {
11
+ const symbol = LEADING.exec(span.trim())?.[1];
12
+ return symbol !== undefined && symbols.has(symbol) ? symbol : null;
13
+ }
14
+ const TOKEN = /[A-Za-z_$][\w$]*|\d+(?:\.\d+)?|'[^']*'|"[^"]*"|`[^`]*`|\S/g;
15
+ const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
16
+ const IDENTIFIERS = /[A-Za-z_$][\w$]*/g;
17
+ /** A fact expression's tokens, each identifier replaced by a placeholder, and its identifiers. */
18
+ export function expressionShape(expression) {
19
+ const tokens = expression.match(TOKEN) ?? [];
20
+ return {
21
+ shape: tokens.map((t) => (IDENTIFIER.test(t) ? '·' : t)).join(' '),
22
+ names: tokens.filter((t) => IDENTIFIER.test(t)),
23
+ };
24
+ }
25
+ /**
26
+ * Which of `names` are still written somewhere in the project's code: in `sources` and in
27
+ * the files of the surfaces that name one. A word in a comment or a string counts.
28
+ */
29
+ export function namesInCode(files, specs, names, sources) {
30
+ const wanted = new Set(names);
31
+ const found = new Set();
32
+ const surfaceFiles = specs.flatMap((s) => (s.path === undefined ? [] : [s.path]));
33
+ for (const file of new Set([...sources, ...surfaceFiles])) {
34
+ for (const word of files.read(file)?.match(IDENTIFIERS) ?? []) {
35
+ if (wanted.has(word))
36
+ found.add(word);
37
+ }
38
+ }
39
+ return names.filter((name) => found.has(name));
40
+ }
41
+ //# sourceMappingURL=lexical.js.map
@@ -0,0 +1,11 @@
1
+ import ts from '../ts.cjs';
2
+ /** Parse a module for syntax-only analysis. */
3
+ export function parseSource(fileName, text) {
4
+ const kind = fileName.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
5
+ return ts.createSourceFile(fileName, text, ts.ScriptTarget.ES2022, true, kind);
6
+ }
7
+ /** Unique strings in first-seen order. */
8
+ export function unique(items) {
9
+ return [...new Set(items)];
10
+ }
11
+ //# sourceMappingURL=parse.js.map
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Prose for claims, as the core writes a claim: HTML comments replaced by a space, every run
3
+ * of whitespace collapsed to one space, trimmed, markup kept (PROTOCOL.md §3, `docProse`).
4
+ */
5
+ export function prose(source) {
6
+ return source
7
+ .replace(/<!--[\s\S]*?-->/g, ' ')
8
+ .replace(/\s+/g, ' ')
9
+ .trim();
10
+ }
11
+ //# sourceMappingURL=prose.js.map
@@ -0,0 +1,88 @@
1
+ import ts from '../ts.cjs';
2
+ import { dedupe, importSurface } from './imports.js';
3
+ import { parseSource } from './parse.js';
4
+ /**
5
+ * Surface symbols a setup-module helper reaches: identifiers imported from a surface in the
6
+ * helper's own code and in the top-level helpers it calls. `group` is the exported object
7
+ * that holds it (`cases` or `facts`), `key` its property name.
8
+ */
9
+ export function helperSymbols(fileName, code, group, key, surfaceOf) {
10
+ const setup = readSetup(fileName, code, surfaceOf);
11
+ const helper = propertyOf(setup, group, key);
12
+ if (!helper)
13
+ return [];
14
+ const refs = [];
15
+ const seen = new Set([setup.locals.get(group)].filter((n) => n !== undefined));
16
+ const visit = (node) => {
17
+ if (ts.isIdentifier(node)) {
18
+ const ref = setup.imported.get(node.text);
19
+ if (ref)
20
+ refs.push(ref);
21
+ const local = setup.locals.get(node.text);
22
+ if (local && !seen.has(local)) {
23
+ seen.add(local);
24
+ visit(local);
25
+ }
26
+ }
27
+ ts.forEachChild(node, visit);
28
+ };
29
+ visit(helper);
30
+ return dedupe(refs);
31
+ }
32
+ /** Property names of an exported object literal, such as the keys of `facts`. */
33
+ export function objectKeys(fileName, code, group) {
34
+ const setup = readSetup(fileName, code, () => undefined);
35
+ const object = objectLiteral(setup.locals.get(group));
36
+ return (object?.properties ?? []).flatMap((p) => {
37
+ const name = propertyName(p);
38
+ return name === undefined ? [] : [name];
39
+ });
40
+ }
41
+ function readSetup(fileName, code, surfaceOf) {
42
+ const source = parseSource(fileName, code);
43
+ const setup = { imported: new Map(), locals: new Map(), source };
44
+ for (const statement of source.statements) {
45
+ const surface = importSurface(statement, surfaceOf);
46
+ if (surface && ts.isImportDeclaration(statement))
47
+ addImports(setup, statement, surface);
48
+ if (ts.isFunctionDeclaration(statement) && statement.name) {
49
+ setup.locals.set(statement.name.text, statement);
50
+ }
51
+ if (!ts.isVariableStatement(statement))
52
+ continue;
53
+ for (const d of statement.declarationList.declarations) {
54
+ if (ts.isIdentifier(d.name) && d.initializer)
55
+ setup.locals.set(d.name.text, d.initializer);
56
+ }
57
+ }
58
+ return setup;
59
+ }
60
+ function addImports(setup, statement, surface) {
61
+ const clause = statement.importClause;
62
+ if (clause?.name)
63
+ setup.imported.set(clause.name.text, { name: 'default', surface });
64
+ const bindings = clause?.namedBindings;
65
+ if (!bindings || !ts.isNamedImports(bindings))
66
+ return;
67
+ for (const el of bindings.elements) {
68
+ setup.imported.set(el.name.text, { name: (el.propertyName ?? el.name).text, surface });
69
+ }
70
+ }
71
+ function propertyOf(setup, group, key) {
72
+ return objectLiteral(setup.locals.get(group))?.properties.find((p) => propertyName(p) === key);
73
+ }
74
+ function objectLiteral(node) {
75
+ let current = node;
76
+ while (current &&
77
+ (ts.isAsExpression(current) ||
78
+ ts.isSatisfiesExpression(current) ||
79
+ ts.isParenthesizedExpression(current))) {
80
+ current = current.expression;
81
+ }
82
+ return current && ts.isObjectLiteralExpression(current) ? current : undefined;
83
+ }
84
+ function propertyName(property) {
85
+ const name = property.name;
86
+ return name && (ts.isIdentifier(name) || ts.isStringLiteral(name)) ? name.text : undefined;
87
+ }
88
+ //# sourceMappingURL=setup-module.js.map
@@ -0,0 +1,9 @@
1
+ "use strict";
2
+ // The TypeScript compiler, loaded with `require`. Imported from an ES module as itself,
3
+ // `typescript` (nine megabytes of CommonJS) is first scanned by Node for the names it
4
+ // exports, which takes longer than loading it; through this module it is not, and an
5
+ // adapter process starts about a tenth of a second sooner. Import `ts` from here.
6
+ // eslint-disable-next-line @typescript-eslint/no-require-imports -- the point of this module
7
+ const ts = require("typescript");
8
+ module.exports = ts;
9
+ //# sourceMappingURL=ts.cjs.map
@@ -0,0 +1,73 @@
1
+ import { freshRegistry } from './context.js';
2
+ import { describeError } from './describe.js';
3
+ import { offline } from './network.js';
4
+ /**
5
+ * Load the setup module, check the runner and its declared columns, then run each row from
6
+ * `start`. Problems before any row runs fail the whole table.
7
+ */
8
+ export async function runCases(id, job, start, ctx) {
9
+ const runner = await prepare(job, ctx);
10
+ if (typeof runner === 'string') {
11
+ ctx.post({ type: 'failed', id, message: runner });
12
+ return;
13
+ }
14
+ ctx.post({ type: 'ready', id });
15
+ for (const row of job.rows.slice(start)) {
16
+ const verdict = await runRow(runner, row.values, `${job.page}:${row.line} ${row.name}`, ctx);
17
+ ctx.post({ type: 'item', id, outcome: { kind: 'verdict', verdict } });
18
+ }
19
+ }
20
+ async function prepare(job, ctx) {
21
+ const at = `cases "${job.runner}" at L${job.line}`;
22
+ let cases;
23
+ try {
24
+ const registry = freshRegistry(ctx, { snapshot: ctx.snapshot });
25
+ cases = property(await offline(() => registry.load(job.setup.file)), 'cases');
26
+ }
27
+ catch (err) {
28
+ const reason = describeError(err).message;
29
+ return `${at}: setup module ${job.setup.label} failed to load: ${reason}`;
30
+ }
31
+ if (typeof cases !== 'object' || cases === null) {
32
+ return `${at}: ${job.setup.label} has no \`cases\` export`;
33
+ }
34
+ const runner = property(cases, job.runner);
35
+ if (typeof runner !== 'function') {
36
+ const known = Object.keys(cases).join(', ') || 'none';
37
+ const runnerAt = `cases runner "${job.runner}" at L${job.line}`;
38
+ return `${runnerAt} is not exported by ${job.setup.label} (known: ${known})`;
39
+ }
40
+ const missing = columnsOf(runner).filter((c) => !job.header.includes(c));
41
+ if (missing.length) {
42
+ const columns = missing.map((m) => `"${m}"`).join(', ');
43
+ const noun = missing.length > 1 ? 'columns' : 'column';
44
+ return `${at}: the table is missing ${noun} ${columns} declared by the runner`;
45
+ }
46
+ return (row) => Reflect.apply(runner, undefined, [row]);
47
+ }
48
+ function property(value, key) {
49
+ if ((typeof value !== 'object' && typeof value !== 'function') || value === null) {
50
+ return undefined;
51
+ }
52
+ return Object.hasOwn(value, key) ? Reflect.get(value, key) : undefined;
53
+ }
54
+ function columnsOf(runner) {
55
+ const columns = property(runner, 'columns');
56
+ return Array.isArray(columns) ? columns.map(String) : [];
57
+ }
58
+ async function runRow(runner, values, name, ctx) {
59
+ try {
60
+ const { strays } = await ctx.strays.during(() => offline(() => runner({ ...values })));
61
+ if (!strays.length)
62
+ return { status: 'pass', message: name };
63
+ return {
64
+ status: 'fail',
65
+ message: `${name}: unhandled error from attested code: ${strays.join('; ')}`,
66
+ };
67
+ }
68
+ catch (err) {
69
+ const failure = describeError(err);
70
+ return { status: 'fail', ...failure, message: `${name}: ${failure.message}` };
71
+ }
72
+ }
73
+ //# sourceMappingURL=cases.js.map
@@ -0,0 +1,15 @@
1
+ import * as vm from 'node:vm';
2
+ import { InternalError } from '../../api/errors.js';
3
+ /**
4
+ * Compile a function expression in this worker's realm. This is the one place untyped code
5
+ * becomes typed: the source is a wrapper docattest generated around transpiled code, so it
6
+ * is a function by construction, and whatever it returns is treated as unknown.
7
+ */
8
+ export function compileFunction(source, filename) {
9
+ const value = vm.runInThisContext(source, { filename });
10
+ if (typeof value !== 'function') {
11
+ throw new InternalError(`vm did not return a function for ${filename}`);
12
+ }
13
+ return value;
14
+ }
15
+ //# sourceMappingURL=compile.js.map
@@ -0,0 +1,10 @@
1
+ const METHODS = [
2
+ ...['log', 'info', 'warn', 'error', 'debug', 'trace', 'dir', 'table'],
3
+ ...['group', 'groupEnd', 'groupCollapsed', 'time', 'timeEnd', 'timeLog', 'count', 'assert'],
4
+ ];
5
+ /** A console that prints nothing: attested code may log, and must not mix with the report. */
6
+ export const QUIET_CONSOLE = {
7
+ ...console,
8
+ ...Object.fromEntries(METHODS.map((m) => [m, () => undefined])),
9
+ };
10
+ //# sourceMappingURL=console.js.map