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.
- package/LICENSE +21 -0
- package/README.md +147 -2
- package/dist/agents/claude.json +30 -0
- package/dist/agents/cursor.json +19 -0
- package/dist/agents/gemini.json +27 -0
- package/dist/agents/index.json +3 -0
- package/dist/api/adapter.d.ts +231 -0
- package/dist/api/adapter.js +2 -0
- package/dist/api/attestation.d.ts +76 -0
- package/dist/api/attestation.js +2 -0
- package/dist/api/audit.d.ts +56 -0
- package/dist/api/audit.js +2 -0
- package/dist/api/config.d.ts +44 -0
- package/dist/api/config.js +2 -0
- package/dist/api/constants.d.ts +35 -0
- package/dist/api/constants.js +56 -0
- package/dist/api/errors.d.ts +15 -0
- package/dist/api/errors.js +22 -0
- package/dist/api/impact.d.ts +49 -0
- package/dist/api/impact.js +2 -0
- package/dist/api/project.d.ts +64 -0
- package/dist/api/project.js +2 -0
- package/dist/api/report.d.ts +107 -0
- package/dist/api/report.js +2 -0
- package/dist/client/answers.d.ts +17 -0
- package/dist/client/answers.js +23 -0
- package/dist/client/core.d.ts +18 -0
- package/dist/client/core.js +58 -0
- package/dist/client/place.d.ts +14 -0
- package/dist/client/place.js +37 -0
- package/dist/client/project.d.ts +3 -0
- package/dist/client/project.js +98 -0
- package/dist/client/workspace.d.ts +12 -0
- package/dist/client/workspace.js +72 -0
- package/dist/compare-strings.d.ts +2 -0
- package/dist/compare-strings.js +5 -0
- package/dist/core-binary/locate.js +113 -0
- package/dist/core-binary/package.js +70 -0
- package/dist/core.json +4 -0
- package/dist/files/disk.d.ts +4 -0
- package/dist/files/disk.js +67 -0
- package/dist/files/glob.d.ts +10 -0
- package/dist/files/glob.js +21 -0
- package/dist/files/ignored.d.ts +14 -0
- package/dist/files/ignored.js +14 -0
- package/dist/files/memory.d.ts +5 -0
- package/dist/files/memory.js +26 -0
- package/dist/files/source.d.ts +22 -0
- package/dist/files/source.js +17 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.js +6 -0
- package/dist/json.d.ts +16 -0
- package/dist/json.js +43 -0
- package/dist/language/cache.js +18 -0
- package/dist/language/citations/listing.js +64 -0
- package/dist/language/citations/match.js +14 -0
- package/dist/language/citations/tests-in-file.js +101 -0
- package/dist/language/compiler.js +73 -0
- package/dist/language/description.js +24 -0
- package/dist/language/impact/affected.js +50 -0
- package/dist/language/impact/fingerprint.js +123 -0
- package/dist/language/impact/graph.js +72 -0
- package/dist/language/impact/lookup.js +100 -0
- package/dist/language/impact/program.js +87 -0
- package/dist/language/impact/renames.js +57 -0
- package/dist/language/impact/revision.js +62 -0
- package/dist/language/impact/units.js +80 -0
- package/dist/language/index.js +10 -0
- package/dist/language/inventory/observables.js +56 -0
- package/dist/language/inventory/plan.js +72 -0
- package/dist/language/inventory/probe.js +150 -0
- package/dist/language/languages.js +43 -0
- package/dist/language/node/dependency.js +34 -0
- package/dist/language/node/exports-map.js +92 -0
- package/dist/language/program/exports.js +29 -0
- package/dist/language/program/file-names.js +13 -0
- package/dist/language/program/globals.js +38 -0
- package/dist/language/program/host.js +91 -0
- package/dist/language/program/options.js +48 -0
- package/dist/language/program/program.js +41 -0
- package/dist/language/run/attempt.js +100 -0
- package/dist/language/run/facts.js +109 -0
- package/dist/language/run/host.js +73 -0
- package/dist/language/run/jobs.js +37 -0
- package/dist/language/run/pool.js +75 -0
- package/dist/language/run/protocol.js +37 -0
- package/dist/language/run/result.js +18 -0
- package/dist/language/run/runner.js +115 -0
- package/dist/language/run/sourcemap.js +43 -0
- package/dist/language/run/spawn.js +40 -0
- package/dist/language/run/transpile.js +50 -0
- package/dist/language/session.js +42 -0
- package/dist/language/surfaces/packages.js +71 -0
- package/dist/language/surfaces/resolve.js +48 -0
- package/dist/language/surfaces/specs.js +32 -0
- package/dist/language/surfaces/stale.js +23 -0
- package/dist/language/symbols.js +95 -0
- package/dist/language/syntax/doc-comments.js +90 -0
- package/dist/language/syntax/doc-prose.js +23 -0
- package/dist/language/syntax/expression.js +52 -0
- package/dist/language/syntax/imports.js +83 -0
- package/dist/language/syntax/lexical.js +41 -0
- package/dist/language/syntax/parse.js +11 -0
- package/dist/language/syntax/prose.js +11 -0
- package/dist/language/syntax/setup-module.js +88 -0
- package/dist/language/ts.cjs +9 -0
- package/dist/language/worker/cases.js +73 -0
- package/dist/language/worker/compile.js +15 -0
- package/dist/language/worker/console.js +10 -0
- package/dist/language/worker/context.js +16 -0
- package/dist/language/worker/describe.js +107 -0
- package/dist/language/worker/example.js +27 -0
- package/dist/language/worker/facts.js +69 -0
- package/dist/language/worker/host-client.js +55 -0
- package/dist/language/worker/main.js +71 -0
- package/dist/language/worker/network.js +35 -0
- package/dist/language/worker/observe.js +39 -0
- package/dist/language/worker/registry.js +78 -0
- package/dist/language/worker/setup-facts.js +50 -0
- package/dist/language/worker/strays.js +37 -0
- package/dist/launcher/main.js +38 -0
- package/dist/platforms.json +40 -0
- package/dist/protocol/context.js +48 -0
- package/dist/protocol/main.js +22 -0
- package/dist/protocol/methods.js +178 -0
- package/dist/protocol/output.js +40 -0
- package/dist/protocol/overlay.js +31 -0
- package/dist/protocol/serve.js +24 -0
- package/dist/protocol/server.js +108 -0
- package/dist/protocol/wire.js +117 -0
- package/dist/schema/agent.json +162 -0
- package/dist/schema/attestations.json +307 -0
- package/dist/schema/kit.json +190 -0
- package/dist/schema/language.json +162 -0
- package/dist/schema/messages.json +68 -0
- package/dist/schema/methods.json +412 -0
- package/dist/schema/project.json +113 -0
- package/dist/schema/results.json +249 -0
- package/package.json +73 -4
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import * as path from 'node:path';
|
|
2
|
+
import { sourceFileMatcher } from '../files/glob.js';
|
|
3
|
+
/** Info-string languages whose blocks the TypeScript adapter compiles and runs. */
|
|
4
|
+
export const BLOCK_LANGUAGES = [
|
|
5
|
+
'ts',
|
|
6
|
+
'typescript',
|
|
7
|
+
'tsx',
|
|
8
|
+
'mts',
|
|
9
|
+
'cts',
|
|
10
|
+
'js',
|
|
11
|
+
'javascript',
|
|
12
|
+
'jsx',
|
|
13
|
+
'mjs',
|
|
14
|
+
'cjs',
|
|
15
|
+
];
|
|
16
|
+
const JAVASCRIPT = ['js', 'javascript', 'mjs', 'cjs'];
|
|
17
|
+
/**
|
|
18
|
+
* The language's source files, as the core is told: TypeScript and JavaScript modules of
|
|
19
|
+
* every flavour, declaration files excepted (`x.d.tsx` is a module, not a declaration).
|
|
20
|
+
*/
|
|
21
|
+
export const SOURCE_FILES = {
|
|
22
|
+
include: ['**/*.{ts,tsx,mts,mtsx,cts,ctsx,js,jsx,mjs,mjsx,cjs,cjsx}'],
|
|
23
|
+
exclude: ['**/*.d.{ts,mts,cts}'],
|
|
24
|
+
};
|
|
25
|
+
/** Installed dependencies: never the project's own pages or sources, at any depth. */
|
|
26
|
+
export const IGNORED_NAMES = ['node_modules'];
|
|
27
|
+
/** Whether a project-relative file is one of them: the adapter's own reading of that data. */
|
|
28
|
+
export const isSourceFile = sourceFileMatcher(SOURCE_FILES);
|
|
29
|
+
/**
|
|
30
|
+
* The virtual module an example becomes: next to its page, so relative imports in the
|
|
31
|
+
* block resolve as a reader would expect, and named after page and line for messages.
|
|
32
|
+
*/
|
|
33
|
+
export function blockFile(root, example) {
|
|
34
|
+
const lang = example.lang.toLowerCase();
|
|
35
|
+
const ext = lang === 'tsx' ? '.tsx' : lang === 'jsx' ? '.jsx' : JAVASCRIPT.includes(lang) ? '.js' : '.ts';
|
|
36
|
+
const name = `__docattest_${path.posix.basename(example.page)}_L${example.line}${ext}`;
|
|
37
|
+
return path.join(root, path.posix.dirname(example.page), name);
|
|
38
|
+
}
|
|
39
|
+
/** The absolute path of a project-relative page. */
|
|
40
|
+
export function pagePath(files, page) {
|
|
41
|
+
return path.join(files.root, page);
|
|
42
|
+
}
|
|
43
|
+
//# sourceMappingURL=languages.js.map
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import { createRequire } from 'node:module';
|
|
2
|
+
import { resolveThroughExports } from './exports-map.js';
|
|
3
|
+
/**
|
|
4
|
+
* Load a third-party dependency natively. Node's CommonJS resolution is used unchanged;
|
|
5
|
+
* only when a package's exports map has no `require` path (ESM-only packages) is it
|
|
6
|
+
* resolved through import conditions and loaded with require(esm), which Node 22.12+ has.
|
|
7
|
+
*/
|
|
8
|
+
export function requireDependency(specifier, base) {
|
|
9
|
+
const load = createRequire(base);
|
|
10
|
+
try {
|
|
11
|
+
return load(specifier);
|
|
12
|
+
}
|
|
13
|
+
catch (err) {
|
|
14
|
+
if (!isNotExported(err))
|
|
15
|
+
throw err;
|
|
16
|
+
const file = resolveThroughExports(specifier, base);
|
|
17
|
+
if (!file)
|
|
18
|
+
throw err;
|
|
19
|
+
return load(file);
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
/** Resolve a bare specifier to a file the way {@link requireDependency} would load it. */
|
|
23
|
+
export function resolveDependency(specifier, base) {
|
|
24
|
+
try {
|
|
25
|
+
return createRequire(base).resolve(specifier);
|
|
26
|
+
}
|
|
27
|
+
catch {
|
|
28
|
+
return resolveThroughExports(specifier, base);
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
function isNotExported(err) {
|
|
32
|
+
return err instanceof Error && 'code' in err && err.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED';
|
|
33
|
+
}
|
|
34
|
+
//# sourceMappingURL=dependency.js.map
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
import * as fs from 'node:fs';
|
|
2
|
+
import { createRequire } from 'node:module';
|
|
3
|
+
import * as path from 'node:path';
|
|
4
|
+
import { isObject, objectOrNothing } from '../../json.js';
|
|
5
|
+
// Resolving a bare specifier through a package's exports map with the conditions Node uses
|
|
6
|
+
// for `import`. CommonJS resolution rejects ESM-only packages (no `require` condition);
|
|
7
|
+
// this finds the file they export so it can be loaded with require(esm).
|
|
8
|
+
/** Conditions active when resolving for import under Node, matched in exports-map order. */
|
|
9
|
+
const CONDITIONS = new Set(['node', 'import', 'module-sync', 'require', 'default']);
|
|
10
|
+
/** The file a bare specifier resolves to under import conditions, or undefined. */
|
|
11
|
+
export function resolveThroughExports(specifier, from) {
|
|
12
|
+
const { name, subpath } = splitSpecifier(specifier);
|
|
13
|
+
for (const dir of createRequire(from).resolve.paths(specifier) ?? []) {
|
|
14
|
+
const packageDir = path.join(dir, name);
|
|
15
|
+
const manifest = readManifest(path.join(packageDir, 'package.json'));
|
|
16
|
+
if (!manifest)
|
|
17
|
+
continue;
|
|
18
|
+
// The nearest package with this name decides, exactly as Node would.
|
|
19
|
+
const target = matchSubpath(manifest.exports, subpath);
|
|
20
|
+
const file = target === undefined ? undefined : pickCondition(target);
|
|
21
|
+
return file ? path.join(packageDir, file) : undefined;
|
|
22
|
+
}
|
|
23
|
+
return undefined;
|
|
24
|
+
}
|
|
25
|
+
function readManifest(file) {
|
|
26
|
+
// A dependency's manifest: one that cannot be read resolves nothing through it.
|
|
27
|
+
return fs.existsSync(file) ? objectOrNothing(fs.readFileSync(file, 'utf8')) : undefined;
|
|
28
|
+
}
|
|
29
|
+
function splitSpecifier(specifier) {
|
|
30
|
+
const parts = specifier.split('/');
|
|
31
|
+
const n = specifier.startsWith('@') ? 2 : 1;
|
|
32
|
+
const subpath = parts.length > n ? `./${parts.slice(n).join('/')}` : '.';
|
|
33
|
+
return { name: parts.slice(0, n).join('/'), subpath };
|
|
34
|
+
}
|
|
35
|
+
// Exports maps are untyped JSON: every step narrows `unknown` as it goes.
|
|
36
|
+
function isConditions(value) {
|
|
37
|
+
return isObject(value) && !Object.keys(value).some((k) => k.startsWith('.'));
|
|
38
|
+
}
|
|
39
|
+
function matchSubpath(exports, subpath) {
|
|
40
|
+
if (typeof exports === 'string' || Array.isArray(exports) || isConditions(exports)) {
|
|
41
|
+
return subpath === '.' ? exports : undefined;
|
|
42
|
+
}
|
|
43
|
+
if (!isObject(exports))
|
|
44
|
+
return undefined;
|
|
45
|
+
return exports[subpath] ?? matchPattern(exports, subpath);
|
|
46
|
+
}
|
|
47
|
+
// Subpath patterns: "./features/*": "./dist/features/*.js". The longest prefix wins.
|
|
48
|
+
function matchPattern(exports, subpath) {
|
|
49
|
+
let best;
|
|
50
|
+
for (const [key, value] of Object.entries(exports)) {
|
|
51
|
+
const star = key.indexOf('*');
|
|
52
|
+
if (star < 0)
|
|
53
|
+
continue;
|
|
54
|
+
const [pre, post] = [key.slice(0, star), key.slice(star + 1)];
|
|
55
|
+
const fits = subpath.length >= pre.length + post.length &&
|
|
56
|
+
subpath.startsWith(pre) &&
|
|
57
|
+
subpath.endsWith(post);
|
|
58
|
+
if (fits && (!best || pre.length > best.prefix)) {
|
|
59
|
+
best = {
|
|
60
|
+
prefix: pre.length,
|
|
61
|
+
value,
|
|
62
|
+
match: subpath.slice(pre.length, subpath.length - post.length),
|
|
63
|
+
};
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
return best ? replaceStar(best.value, best.match) : undefined;
|
|
67
|
+
}
|
|
68
|
+
function replaceStar(value, match) {
|
|
69
|
+
if (typeof value === 'string')
|
|
70
|
+
return value.replaceAll('*', match);
|
|
71
|
+
if (Array.isArray(value))
|
|
72
|
+
return value.map((v) => replaceStar(v, match));
|
|
73
|
+
if (!isObject(value))
|
|
74
|
+
return value;
|
|
75
|
+
return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, replaceStar(v, match)]));
|
|
76
|
+
}
|
|
77
|
+
function pickCondition(value) {
|
|
78
|
+
if (typeof value === 'string')
|
|
79
|
+
return value;
|
|
80
|
+
const candidates = Array.isArray(value)
|
|
81
|
+
? value
|
|
82
|
+
: isObject(value)
|
|
83
|
+
? Object.entries(value).flatMap(([key, v]) => (CONDITIONS.has(key) ? [v] : []))
|
|
84
|
+
: [];
|
|
85
|
+
for (const candidate of candidates) {
|
|
86
|
+
const file = pickCondition(candidate);
|
|
87
|
+
if (file)
|
|
88
|
+
return file;
|
|
89
|
+
}
|
|
90
|
+
return undefined;
|
|
91
|
+
}
|
|
92
|
+
//# sourceMappingURL=exports-map.js.map
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import ts from '../ts.cjs';
|
|
2
|
+
import { compareStrings } from '../../compare-strings.js';
|
|
3
|
+
import { platformPath } from './file-names.js';
|
|
4
|
+
/** Exported names of a module, values and types, sorted; undefined when it is not loaded. */
|
|
5
|
+
export function exportsOf(program, file) {
|
|
6
|
+
const exported = exportedSymbols(program, file);
|
|
7
|
+
return exported?.map((s) => s.name).sort(compareStrings);
|
|
8
|
+
}
|
|
9
|
+
/** For each exported name, the files (platform paths) that declare what it ultimately refers to. */
|
|
10
|
+
export function exportOrigins(program, file) {
|
|
11
|
+
const checker = program.getTypeChecker();
|
|
12
|
+
const origins = new Map();
|
|
13
|
+
for (const symbol of exportedSymbols(program, file) ?? []) {
|
|
14
|
+
const target = symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
|
|
15
|
+
const declarations = target.declarations ?? [];
|
|
16
|
+
const declared = declarations.map((d) => platformPath(d.getSourceFile().fileName));
|
|
17
|
+
origins.set(symbol.name, new Set(declared));
|
|
18
|
+
}
|
|
19
|
+
return origins;
|
|
20
|
+
}
|
|
21
|
+
function exportedSymbols(program, file) {
|
|
22
|
+
const source = program.getSourceFile(file);
|
|
23
|
+
if (!source)
|
|
24
|
+
return undefined;
|
|
25
|
+
const checker = program.getTypeChecker();
|
|
26
|
+
const module = checker.getSymbolAtLocation(source);
|
|
27
|
+
return module ? checker.getExportsOfModule(module) : [];
|
|
28
|
+
}
|
|
29
|
+
//# sourceMappingURL=exports.js.map
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import * as path from 'node:path';
|
|
2
|
+
// TypeScript names every file with `/`, on Windows too, while `path.join` writes the
|
|
3
|
+
// platform's separator. A path made here and a name TypeScript hands back only compare
|
|
4
|
+
// equal once they are written the same way; these two functions are where that happens.
|
|
5
|
+
/** A platform path as TypeScript names the file. */
|
|
6
|
+
export function typeScriptName(file) {
|
|
7
|
+
return path.sep === '\\' ? file.replaceAll('\\', '/') : file;
|
|
8
|
+
}
|
|
9
|
+
/** A file TypeScript names, as the platform writes its path. */
|
|
10
|
+
export function platformPath(name) {
|
|
11
|
+
return path.sep === '\\' ? name.replaceAll('/', '\\') : name;
|
|
12
|
+
}
|
|
13
|
+
//# sourceMappingURL=file-names.js.map
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/** Declarations docattest puts in scope for every example. Small and permissive. */
|
|
2
|
+
export const GLOBALS = `
|
|
3
|
+
interface AttestAssert {
|
|
4
|
+
(value: unknown, message?: string | Error): asserts value;
|
|
5
|
+
ok(value: unknown, message?: string | Error): asserts value;
|
|
6
|
+
equal(actual: unknown, expected: unknown, message?: string | Error): void;
|
|
7
|
+
notEqual(actual: unknown, expected: unknown, message?: string | Error): void;
|
|
8
|
+
strictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
|
|
9
|
+
notStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
|
|
10
|
+
deepEqual(actual: unknown, expected: unknown, message?: string | Error): void;
|
|
11
|
+
notDeepEqual(actual: unknown, expected: unknown, message?: string | Error): void;
|
|
12
|
+
deepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
|
|
13
|
+
notDeepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
|
|
14
|
+
partialDeepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
|
|
15
|
+
match(value: string, regExp: RegExp, message?: string | Error): void;
|
|
16
|
+
doesNotMatch(value: string, regExp: RegExp, message?: string | Error): void;
|
|
17
|
+
throws(block: () => unknown, error?: unknown, message?: string | Error): void;
|
|
18
|
+
doesNotThrow(block: () => unknown, error?: unknown, message?: string | Error): void;
|
|
19
|
+
rejects(
|
|
20
|
+
block: Promise<unknown> | (() => Promise<unknown>),
|
|
21
|
+
error?: unknown,
|
|
22
|
+
message?: string | Error,
|
|
23
|
+
): Promise<void>;
|
|
24
|
+
doesNotReject(
|
|
25
|
+
block: Promise<unknown> | (() => Promise<unknown>),
|
|
26
|
+
error?: unknown,
|
|
27
|
+
message?: string | Error,
|
|
28
|
+
): Promise<void>;
|
|
29
|
+
fail(message?: string | Error): never;
|
|
30
|
+
ifError(value: unknown): void;
|
|
31
|
+
}
|
|
32
|
+
declare const assert: AttestAssert;
|
|
33
|
+
`;
|
|
34
|
+
/** Without @types/node, node: imports still type-check, as `any`. */
|
|
35
|
+
export const NODE_FALLBACK = `declare module 'node:*';\n`;
|
|
36
|
+
/** File name of the globals module, at the project root. */
|
|
37
|
+
export const GLOBALS_FILE = '__docattest_globals__.d.ts';
|
|
38
|
+
//# sourceMappingURL=globals.js.map
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
import * as path from 'node:path';
|
|
2
|
+
import ts from '../ts.cjs';
|
|
3
|
+
import { relativeTo } from '../../files/source.js';
|
|
4
|
+
import { threadCache } from '../cache.js';
|
|
5
|
+
import { typeScriptName } from './file-names.js';
|
|
6
|
+
import { extensionOf } from './options.js';
|
|
7
|
+
// Lib and node_modules declarations never change during a process, so every program shares
|
|
8
|
+
// their parsed form, including programs of nested docattest copies.
|
|
9
|
+
const SHARED = threadCache('sourceFiles');
|
|
10
|
+
/**
|
|
11
|
+
* A compiler host over a FileSource. In-memory projects are hermetic: only their own files
|
|
12
|
+
* and TypeScript's lib files exist.
|
|
13
|
+
*/
|
|
14
|
+
export function createHost(input) {
|
|
15
|
+
const { files } = input;
|
|
16
|
+
// Keyed by the names TypeScript asks for, which it writes with `/` on every platform.
|
|
17
|
+
const virtual = new Map([...input.virtual].map(([file, text]) => [typeScriptName(file), text]));
|
|
18
|
+
const libFile = ts.getDefaultLibFilePath(input.options);
|
|
19
|
+
const libDir = path.dirname(libFile);
|
|
20
|
+
const readFile = (abs) => {
|
|
21
|
+
const text = virtual.get(typeScriptName(abs));
|
|
22
|
+
if (text !== undefined)
|
|
23
|
+
return text;
|
|
24
|
+
if (!files.memory)
|
|
25
|
+
return ts.sys.readFile(abs);
|
|
26
|
+
return relativeTo(files.root, abs) !== undefined
|
|
27
|
+
? files.readAbsolute(abs)
|
|
28
|
+
: abs.startsWith(libDir)
|
|
29
|
+
? ts.sys.readFile(abs)
|
|
30
|
+
: undefined;
|
|
31
|
+
};
|
|
32
|
+
const dirs = files.memory ? memoryDirectories(files, virtual) : undefined;
|
|
33
|
+
const host = {
|
|
34
|
+
getSourceFile: (fileName, version) => {
|
|
35
|
+
const shareable = fileName.startsWith(libDir) || fileName.includes('/node_modules/');
|
|
36
|
+
return sourceFile(fileName, version, readFile(fileName), shareable ? SHARED : input.parsed);
|
|
37
|
+
},
|
|
38
|
+
getDefaultLibFileName: () => libFile,
|
|
39
|
+
getDefaultLibLocation: () => libDir,
|
|
40
|
+
writeFile: () => undefined,
|
|
41
|
+
getCurrentDirectory: () => files.root,
|
|
42
|
+
getCanonicalFileName: (f) => f,
|
|
43
|
+
useCaseSensitiveFileNames: () => true,
|
|
44
|
+
getNewLine: () => '\n',
|
|
45
|
+
fileExists: (f) => readFile(f) !== undefined,
|
|
46
|
+
readFile,
|
|
47
|
+
directoryExists: (d) => dirs ? dirs.has(d) || d.startsWith(libDir) : ts.sys.directoryExists(d),
|
|
48
|
+
getDirectories: (d) => (dirs ? [] : ts.sys.getDirectories(d)),
|
|
49
|
+
realpath: dirs ? (f) => f : (f) => ts.sys.realpath?.(f) ?? f,
|
|
50
|
+
resolveModuleNameLiterals: (literals, containing, redirected, options) => literals.map(({ text }) => {
|
|
51
|
+
const surface = input.surfaces.get(text);
|
|
52
|
+
if (surface !== undefined)
|
|
53
|
+
return resolvedSurface(surface);
|
|
54
|
+
return ts.resolveModuleName(text, containing, options, host, undefined, redirected);
|
|
55
|
+
}),
|
|
56
|
+
};
|
|
57
|
+
return host;
|
|
58
|
+
}
|
|
59
|
+
function sourceFile(fileName, version, text, cache) {
|
|
60
|
+
if (text === undefined)
|
|
61
|
+
return undefined;
|
|
62
|
+
const hit = cache.get(fileName);
|
|
63
|
+
if (hit?.text === text)
|
|
64
|
+
return hit;
|
|
65
|
+
const created = ts.createSourceFile(fileName, text, version, true);
|
|
66
|
+
cache.set(fileName, created);
|
|
67
|
+
return created;
|
|
68
|
+
}
|
|
69
|
+
// A surface's import specifier resolves straight to its types entry, not through the
|
|
70
|
+
// project's module resolution.
|
|
71
|
+
function resolvedSurface(surface) {
|
|
72
|
+
const resolvedUsingTsExtension = /\.[mc]?tsx?$/.test(surface) && !/\.d\.[mc]?ts$/.test(surface);
|
|
73
|
+
return {
|
|
74
|
+
resolvedModule: {
|
|
75
|
+
resolvedFileName: surface,
|
|
76
|
+
extension: extensionOf(surface),
|
|
77
|
+
isExternalLibraryImport: false,
|
|
78
|
+
resolvedUsingTsExtension,
|
|
79
|
+
},
|
|
80
|
+
};
|
|
81
|
+
}
|
|
82
|
+
function memoryDirectories(files, virtual) {
|
|
83
|
+
const dirs = new Set([typeScriptName(files.root)]);
|
|
84
|
+
const projectFiles = files.list().map((f) => typeScriptName(path.join(files.root, f)));
|
|
85
|
+
for (const file of [...projectFiles, ...virtual.keys()]) {
|
|
86
|
+
for (let d = path.dirname(file); d.length > 1 && !dirs.has(d); d = path.dirname(d))
|
|
87
|
+
dirs.add(d);
|
|
88
|
+
}
|
|
89
|
+
return dirs;
|
|
90
|
+
}
|
|
91
|
+
//# sourceMappingURL=host.js.map
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import * as path from 'node:path';
|
|
2
|
+
import ts from '../ts.cjs';
|
|
3
|
+
/**
|
|
4
|
+
* Compiler options for examples: strict, modern, bundler resolution. These are docattest's,
|
|
5
|
+
* not the project's: a page must compile the way a user's fresh project would.
|
|
6
|
+
*/
|
|
7
|
+
export function compilerOptions(files) {
|
|
8
|
+
const nodeTypes = !files.memory &&
|
|
9
|
+
ts.sys.directoryExists(path.join(files.root, 'node_modules', '@types', 'node'));
|
|
10
|
+
return {
|
|
11
|
+
target: ts.ScriptTarget.ES2022,
|
|
12
|
+
module: ts.ModuleKind.ESNext,
|
|
13
|
+
moduleResolution: ts.ModuleResolutionKind.Bundler,
|
|
14
|
+
moduleDetection: ts.ModuleDetectionKind.Force,
|
|
15
|
+
lib: ['lib.esnext.d.ts', 'lib.dom.d.ts', 'lib.dom.iterable.d.ts'],
|
|
16
|
+
types: nodeTypes ? ['node'] : [],
|
|
17
|
+
strict: true,
|
|
18
|
+
noEmit: true,
|
|
19
|
+
allowImportingTsExtensions: true,
|
|
20
|
+
allowJs: true,
|
|
21
|
+
resolveJsonModule: true,
|
|
22
|
+
esModuleInterop: true,
|
|
23
|
+
skipLibCheck: true,
|
|
24
|
+
jsx: ts.JsxEmit.Preserve,
|
|
25
|
+
};
|
|
26
|
+
}
|
|
27
|
+
const EXTENSIONS = {
|
|
28
|
+
'.ts': ts.Extension.Ts,
|
|
29
|
+
'.tsx': ts.Extension.Tsx,
|
|
30
|
+
'.mts': ts.Extension.Mts,
|
|
31
|
+
'.cts': ts.Extension.Cts,
|
|
32
|
+
'.js': ts.Extension.Js,
|
|
33
|
+
'.jsx': ts.Extension.Jsx,
|
|
34
|
+
'.mjs': ts.Extension.Mjs,
|
|
35
|
+
'.cjs': ts.Extension.Cjs,
|
|
36
|
+
'.json': ts.Extension.Json,
|
|
37
|
+
};
|
|
38
|
+
/** The TypeScript extension kind of a file name. */
|
|
39
|
+
export function extensionOf(file) {
|
|
40
|
+
if (file.endsWith('.d.mts'))
|
|
41
|
+
return ts.Extension.Dmts;
|
|
42
|
+
if (file.endsWith('.d.cts'))
|
|
43
|
+
return ts.Extension.Dcts;
|
|
44
|
+
if (file.endsWith('.d.ts'))
|
|
45
|
+
return ts.Extension.Dts;
|
|
46
|
+
return EXTENSIONS[path.extname(file)] ?? ts.Extension.Ts;
|
|
47
|
+
}
|
|
48
|
+
//# sourceMappingURL=options.js.map
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import * as path from 'node:path';
|
|
2
|
+
import ts from '../ts.cjs';
|
|
3
|
+
import { GLOBALS, GLOBALS_FILE, NODE_FALLBACK } from './globals.js';
|
|
4
|
+
import { createHost } from './host.js';
|
|
5
|
+
import { compilerOptions } from './options.js';
|
|
6
|
+
/** A program over the project: surfaces, their imports, and one module per example. */
|
|
7
|
+
export function createProgram(input, purpose) {
|
|
8
|
+
const options = { ...compilerOptions(input.files), noLib: purpose === 'exports' };
|
|
9
|
+
const globals = path.join(input.files.root, GLOBALS_FILE);
|
|
10
|
+
const virtual = new Map(input.examples);
|
|
11
|
+
virtual.set(globals, GLOBALS + (options.types?.length ? '' : NODE_FALLBACK));
|
|
12
|
+
const { files, surfaces, parsed } = input;
|
|
13
|
+
const host = createHost({ files, options, virtual, surfaces, parsed });
|
|
14
|
+
// As tsc does: a comment that cannot change a type or an error is not parsed.
|
|
15
|
+
host.jsDocParsingMode = ts.JSDocParsingMode.ParseForTypeErrors;
|
|
16
|
+
const rootNames = [...new Set([globals, ...input.surfaces.values(), ...input.examples.keys()])];
|
|
17
|
+
return ts.createProgram({ rootNames, options, host });
|
|
18
|
+
}
|
|
19
|
+
/** Diagnostics for one module as `TS1234: message` with a 1-based line. */
|
|
20
|
+
export function diagnosticsFor(program, file) {
|
|
21
|
+
const source = program.getSourceFile(file);
|
|
22
|
+
if (!source) {
|
|
23
|
+
return [{ message: 'docattest: example module was not part of the program', line: 1 }];
|
|
24
|
+
}
|
|
25
|
+
const diagnostics = [
|
|
26
|
+
...program.getSyntacticDiagnostics(source),
|
|
27
|
+
...program.getSemanticDiagnostics(source),
|
|
28
|
+
];
|
|
29
|
+
return diagnostics.map((d) => ({
|
|
30
|
+
message: `TS${d.code}: ${ts.flattenDiagnosticMessageText(d.messageText, ' ')}`,
|
|
31
|
+
line: d.start === undefined ? 1 : source.getLineAndCharacterOfPosition(d.start).line + 1,
|
|
32
|
+
}));
|
|
33
|
+
}
|
|
34
|
+
/** Resolve a bare specifier to a types file, the way the checker would from the root. */
|
|
35
|
+
export function resolveTypes(program, specifier, root) {
|
|
36
|
+
const options = program.getCompilerOptions();
|
|
37
|
+
const from = path.join(root, 'package.json');
|
|
38
|
+
return ts.resolveModuleName(specifier, from, options, ts.createCompilerHost(options))
|
|
39
|
+
.resolvedModule?.resolvedFileName;
|
|
40
|
+
}
|
|
41
|
+
//# sourceMappingURL=program.js.map
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
import { randomUUID } from 'node:crypto';
|
|
2
|
+
import { isWorkerListening, isWorkerMessage, } from './protocol.js';
|
|
3
|
+
/** Why work that outlived its session did not run: the pool was closed under it. */
|
|
4
|
+
const CLOSED = 'the session was closed before this could run';
|
|
5
|
+
/**
|
|
6
|
+
* Run a job on one worker from item `start`. Every phase (preparing, then each item) gets
|
|
7
|
+
* the full time budget, and starting a new worker is none of them; when one overruns, the
|
|
8
|
+
* worker is terminated, which stops the code wherever it is, at an await or in a busy loop
|
|
9
|
+
* alike. On a closed pool the attempt fails at once, so a job cut short by `close` ends
|
|
10
|
+
* there and is not resumed.
|
|
11
|
+
*/
|
|
12
|
+
export async function attempt(pool, job, start, timeoutMs) {
|
|
13
|
+
const claim = await pool.acquire();
|
|
14
|
+
if (!claim)
|
|
15
|
+
return { outcomes: [], strays: [], end: { kind: 'failed', message: CLOSED } };
|
|
16
|
+
return new JobAttempt(pool, claim, timeoutMs).run(job, start);
|
|
17
|
+
}
|
|
18
|
+
class JobAttempt {
|
|
19
|
+
pool;
|
|
20
|
+
claim;
|
|
21
|
+
timeoutMs;
|
|
22
|
+
// Tells this attempt's messages from those a worker still sends for an earlier one.
|
|
23
|
+
id = randomUUID();
|
|
24
|
+
outcomes = [];
|
|
25
|
+
strays = [];
|
|
26
|
+
prepared = false;
|
|
27
|
+
timer;
|
|
28
|
+
settle = () => undefined;
|
|
29
|
+
constructor(pool, claim, timeoutMs) {
|
|
30
|
+
this.pool = pool;
|
|
31
|
+
this.claim = claim;
|
|
32
|
+
this.timeoutMs = timeoutMs;
|
|
33
|
+
}
|
|
34
|
+
/** On a fresh worker the clock starts once it listens; a crash while starting ends it. */
|
|
35
|
+
run(job, start) {
|
|
36
|
+
return new Promise((resolve) => {
|
|
37
|
+
this.settle = resolve;
|
|
38
|
+
this.listen('on');
|
|
39
|
+
if (!this.claim.fresh)
|
|
40
|
+
this.arm();
|
|
41
|
+
this.claim.worker.postMessage({ id: this.id, job, start });
|
|
42
|
+
});
|
|
43
|
+
}
|
|
44
|
+
onMessage = (raw) => {
|
|
45
|
+
if (isWorkerListening(raw))
|
|
46
|
+
this.arm();
|
|
47
|
+
if (isWorkerMessage(raw) && raw.id === this.id)
|
|
48
|
+
this.onOwnMessage(raw);
|
|
49
|
+
};
|
|
50
|
+
/** A message about this attempt: each phase that ends restarts the clock for the next. */
|
|
51
|
+
onOwnMessage(message) {
|
|
52
|
+
switch (message.type) {
|
|
53
|
+
case 'ready':
|
|
54
|
+
this.prepared = true;
|
|
55
|
+
this.arm();
|
|
56
|
+
break;
|
|
57
|
+
case 'item':
|
|
58
|
+
this.outcomes.push(message.outcome);
|
|
59
|
+
this.arm();
|
|
60
|
+
break;
|
|
61
|
+
case 'stray':
|
|
62
|
+
this.strays.push(message.message);
|
|
63
|
+
break;
|
|
64
|
+
case 'failed':
|
|
65
|
+
this.finish({ kind: 'failed', message: message.message }, true);
|
|
66
|
+
break;
|
|
67
|
+
case 'done':
|
|
68
|
+
this.finish({ kind: 'done' }, true);
|
|
69
|
+
break;
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
onError = (err) => {
|
|
73
|
+
this.finish({ kind: 'crashed', prepared: this.prepared, message: `the worker crashed: ${err.message}` }, false);
|
|
74
|
+
};
|
|
75
|
+
onExit = (code) => {
|
|
76
|
+
this.finish({ kind: 'crashed', prepared: this.prepared, message: `the worker exited with code ${code}` }, false);
|
|
77
|
+
};
|
|
78
|
+
arm() {
|
|
79
|
+
clearTimeout(this.timer);
|
|
80
|
+
const timedOut = () => {
|
|
81
|
+
this.finish({ kind: 'timeout', prepared: this.prepared }, false);
|
|
82
|
+
};
|
|
83
|
+
this.timer = setTimeout(timedOut, this.timeoutMs);
|
|
84
|
+
}
|
|
85
|
+
finish(end, healthy) {
|
|
86
|
+
clearTimeout(this.timer);
|
|
87
|
+
this.listen('off');
|
|
88
|
+
if (healthy)
|
|
89
|
+
this.pool.release(this.claim.worker);
|
|
90
|
+
else
|
|
91
|
+
this.pool.discard(this.claim.worker);
|
|
92
|
+
this.settle({ outcomes: this.outcomes, strays: this.strays, end });
|
|
93
|
+
}
|
|
94
|
+
listen(how) {
|
|
95
|
+
this.claim.worker[how]('message', this.onMessage);
|
|
96
|
+
this.claim.worker[how]('error', this.onError);
|
|
97
|
+
this.claim.worker[how]('exit', this.onExit);
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
//# sourceMappingURL=attempt.js.map
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
import * as path from 'node:path';
|
|
2
|
+
import { expressionIdentifiers, expressionProblem } from '../syntax/expression.js';
|
|
3
|
+
import { objectKeys } from '../syntax/setup-module.js';
|
|
4
|
+
import { transpile } from './transpile.js';
|
|
5
|
+
import { ambiguous } from './protocol.js';
|
|
6
|
+
/** Evaluates fact expressions: one job per page and surface, one fresh registry per job. */
|
|
7
|
+
export class FactEvaluator {
|
|
8
|
+
ctx;
|
|
9
|
+
surfaces;
|
|
10
|
+
runner;
|
|
11
|
+
exportsOf;
|
|
12
|
+
/** The names of the setup module's named facts, as its syntax declares them. */
|
|
13
|
+
helperNames;
|
|
14
|
+
constructor(ctx, surfaces, runner,
|
|
15
|
+
/** Statically known exports of a surface, by name. */
|
|
16
|
+
exportsOf) {
|
|
17
|
+
this.ctx = ctx;
|
|
18
|
+
this.surfaces = surfaces;
|
|
19
|
+
this.runner = runner;
|
|
20
|
+
this.exportsOf = exportsOf;
|
|
21
|
+
const setup = ctx.setup;
|
|
22
|
+
const code = setup === undefined ? undefined : ctx.files.read(setup);
|
|
23
|
+
this.helperNames =
|
|
24
|
+
setup === undefined || code === undefined ? [] : objectKeys(setup, code, 'facts');
|
|
25
|
+
}
|
|
26
|
+
/** Evaluate every fact; each id maps to its value or to why there is none. */
|
|
27
|
+
async evaluate(facts) {
|
|
28
|
+
const values = new Map();
|
|
29
|
+
const groups = new Map();
|
|
30
|
+
for (const fact of facts) {
|
|
31
|
+
const problem = this.problem(fact);
|
|
32
|
+
if (problem)
|
|
33
|
+
values.set(fact.id, { ok: false, message: problem });
|
|
34
|
+
else {
|
|
35
|
+
groups.set(`${fact.page}\0${fact.surface}`, [
|
|
36
|
+
...(groups.get(`${fact.page}\0${fact.surface}`) ?? []),
|
|
37
|
+
fact,
|
|
38
|
+
]);
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
await Promise.all([...groups.values()].map(async (group) => this.group(group, values)));
|
|
42
|
+
return values;
|
|
43
|
+
}
|
|
44
|
+
problem(fact) {
|
|
45
|
+
const surface = this.surfaces.find((s) => s.spec.name === fact.surface);
|
|
46
|
+
if (!surface) {
|
|
47
|
+
const configured = this.surfaces.map((s) => s.spec.name).join(', ');
|
|
48
|
+
return `unknown surface "${fact.surface}" (configured: ${configured})`;
|
|
49
|
+
}
|
|
50
|
+
if (!surface.entry)
|
|
51
|
+
return `surface "${fact.surface}" (${surface.spec.import}) not found`;
|
|
52
|
+
return expressionProblem(fact.expression) ?? this.clash(fact);
|
|
53
|
+
}
|
|
54
|
+
// Caught here from the setup module's syntax, so a clash fails even when the surface
|
|
55
|
+
// alone could evaluate the expression; the worker catches the dynamic cases.
|
|
56
|
+
clash(fact) {
|
|
57
|
+
const exported = new Set(this.exportsOf(fact.surface) ?? []);
|
|
58
|
+
const helpers = new Set(this.helperNames);
|
|
59
|
+
const name = expressionIdentifiers(fact.expression).find((n) => exported.has(n) && helpers.has(n));
|
|
60
|
+
return name === undefined
|
|
61
|
+
? undefined
|
|
62
|
+
: `fact \`${fact.expression}\`: ${ambiguous(name, fact.surface)}`;
|
|
63
|
+
}
|
|
64
|
+
async group(facts, values) {
|
|
65
|
+
const [first] = facts;
|
|
66
|
+
const file = this.surfaces.find((s) => s.spec.name === first?.surface)?.entry;
|
|
67
|
+
if (!first || !file)
|
|
68
|
+
return;
|
|
69
|
+
const job = {
|
|
70
|
+
type: 'facts',
|
|
71
|
+
surface: first.surface,
|
|
72
|
+
file,
|
|
73
|
+
setup: this.setup(),
|
|
74
|
+
facts: facts.map(item),
|
|
75
|
+
};
|
|
76
|
+
const { failure, items } = await this.runner.execute(job, facts.length);
|
|
77
|
+
const failed = failure?.timedOut
|
|
78
|
+
? `surface "${first.surface}" failed to load: ${failure.message}`
|
|
79
|
+
: failure?.message;
|
|
80
|
+
facts.forEach((fact, k) => {
|
|
81
|
+
values.set(fact.id, failed === undefined ? this.evaluation(fact, items[k]) : { ok: false, message: failed });
|
|
82
|
+
});
|
|
83
|
+
}
|
|
84
|
+
evaluation(fact, item) {
|
|
85
|
+
const expression = `fact \`${fact.expression}\``;
|
|
86
|
+
if (!item)
|
|
87
|
+
return { ok: false, message: `${expression} was not evaluated` };
|
|
88
|
+
if (item.kind === 'timeout') {
|
|
89
|
+
return { ok: false, message: `${expression} timed out after ${this.ctx.timeoutMs} ms` };
|
|
90
|
+
}
|
|
91
|
+
if (item.kind === 'lost')
|
|
92
|
+
return { ok: false, message: `${expression}: ${item.message}` };
|
|
93
|
+
if (item.outcome.kind === 'evaluation')
|
|
94
|
+
return item.outcome.evaluation;
|
|
95
|
+
return { ok: false, message: `${expression}: the worker returned a verdict for a fact` };
|
|
96
|
+
}
|
|
97
|
+
setup() {
|
|
98
|
+
const setup = this.ctx.setup;
|
|
99
|
+
if (setup === undefined || !this.ctx.files.exists(setup))
|
|
100
|
+
return undefined;
|
|
101
|
+
return { file: path.join(this.ctx.files.root, setup), label: setup };
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
// Each expression becomes a module whose default export evaluates it, so `await` works.
|
|
105
|
+
function item(fact) {
|
|
106
|
+
const { code } = transpile('fact.ts', `export default async () => (\n${fact.expression}\n);`);
|
|
107
|
+
return { expression: fact.expression, code, identifiers: expressionIdentifiers(fact.expression) };
|
|
108
|
+
}
|
|
109
|
+
//# sourceMappingURL=facts.js.map
|