docattest 0.0.0-stage → 0.1.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 (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,100 @@
1
+ import ts from '../ts.cjs';
2
+ import { relativeTo } from '../../files/source.js';
3
+ import { ownerKey, unitsOf } from './units.js';
4
+ /**
5
+ * The project's units in one program, and the checker's answer to "which units does this
6
+ * name refer to". Only project files hold units: lib and dependency declarations never
7
+ * change under a diff.
8
+ */
9
+ export class UnitLookup {
10
+ program;
11
+ root;
12
+ checker;
13
+ modules = new Map();
14
+ byKey = new Map();
15
+ constructor(program, root) {
16
+ this.program = program;
17
+ this.root = root;
18
+ this.checker = program.getTypeChecker();
19
+ }
20
+ /** The project-relative path of a module, or undefined when it is not the project's. */
21
+ relative(file) {
22
+ const rel = relativeTo(this.root, file.fileName);
23
+ return rel === undefined || /(^|\/)node_modules\//.test(rel) ? undefined : rel;
24
+ }
25
+ /** The units of a project module (empty for any other). */
26
+ units(file) {
27
+ let found = this.modules.get(file);
28
+ if (!found) {
29
+ const rel = this.relative(file);
30
+ found = rel === undefined ? { units: new Map(), owner: new Map() } : unitsOf(file, rel);
31
+ for (const unit of found.units.values())
32
+ this.byKey.set(unit.key, unit);
33
+ this.modules.set(file, found);
34
+ }
35
+ return found;
36
+ }
37
+ /** A unit by key, once its module has been seen. */
38
+ unit(key) {
39
+ return this.byKey.get(key);
40
+ }
41
+ /** Project modules of the program. */
42
+ projectFiles() {
43
+ return this.program.getSourceFiles().filter((f) => this.relative(f) !== undefined);
44
+ }
45
+ /** Units a symbol's declarations live in; a module symbol stands for all its units. */
46
+ keysOfSymbol(symbol) {
47
+ const keys = new Set();
48
+ const roots = symbol.flags & ts.SymbolFlags.Transient ? this.checker.getRootSymbols(symbol) : [];
49
+ for (const s of [symbol, ...roots]) {
50
+ for (const d of s.declarations ?? []) {
51
+ if (ts.isSourceFile(d))
52
+ for (const k of this.units(d).units.keys())
53
+ keys.add(k);
54
+ else {
55
+ const key = ownerKey(d, this.units(d.getSourceFile()).owner);
56
+ if (key !== undefined)
57
+ keys.add(key);
58
+ }
59
+ }
60
+ }
61
+ return [...keys];
62
+ }
63
+ /** Units a name in the code refers to, through imports and re-exports. */
64
+ keysAt(node) {
65
+ const symbol = this.symbolAt(node);
66
+ return symbol ? this.keysOfSymbol(symbol) : [];
67
+ }
68
+ /**
69
+ * Whether a name is a module's own top-level declaration (or a module), so that its
70
+ * text says nothing its unit key does not: renaming or moving it changes only the key.
71
+ */
72
+ isTopLevelName(node) {
73
+ const declarations = this.symbolAt(node)?.declarations ?? [];
74
+ const own = (d) => ts.isSourceFile(d) || this.units(d.getSourceFile()).owner.has(d);
75
+ return declarations.length > 0 && declarations.every(own);
76
+ }
77
+ symbolAt(node) {
78
+ const parent = node.parent;
79
+ const symbol = parent && ts.isShorthandPropertyAssignment(parent) && parent.name === node
80
+ ? this.checker.getShorthandAssignmentValueSymbol(parent)
81
+ : this.checker.getSymbolAtLocation(node);
82
+ return symbol && symbol.flags & ts.SymbolFlags.Alias ? this.resolveAlias(symbol) : symbol;
83
+ }
84
+ /** The symbol an alias (an import, a re-export) finally names. */
85
+ resolveAlias(symbol) {
86
+ return symbol.flags & ts.SymbolFlags.Alias ? this.checker.getAliasedSymbol(symbol) : symbol;
87
+ }
88
+ }
89
+ /** Whether a node is a name the checker can resolve to a declaration. */
90
+ export function isReference(node) {
91
+ if (ts.isIdentifier(node) || ts.isPrivateIdentifier(node))
92
+ return true;
93
+ const parent = node.parent;
94
+ // `obj['key']` names a property as surely as `obj.key`.
95
+ return (ts.isStringLiteral(node) &&
96
+ parent !== undefined &&
97
+ ts.isElementAccessExpression(parent) &&
98
+ parent.argumentExpression === node);
99
+ }
100
+ //# sourceMappingURL=lookup.js.map
@@ -0,0 +1,87 @@
1
+ import * as path from 'node:path';
2
+ import ts from '../ts.cjs';
3
+ import { relativeTo } from '../../files/source.js';
4
+ import { isStringArray, objectOrNothing } from '../../json.js';
5
+ import { createHost } from '../program/host.js';
6
+ import { compilerOptions } from '../program/options.js';
7
+ import { resolveSurfaces } from '../surfaces/resolve.js';
8
+ /**
9
+ * Build the program for one revision. Every project file is read through `files`, so the
10
+ * same code builds the base (git's copy of changed files) and the working tree. A surface
11
+ * that points at built output is traced back to its source through the build's source
12
+ * map, because a diff changes the source, not the build.
13
+ */
14
+ export function surfacePrograms(files, specs) {
15
+ const options = compilerOptions(files);
16
+ const host = overlayHost(files, options);
17
+ const entries = new Map();
18
+ for (const surface of resolveSurfaces(files, specs)) {
19
+ const built = surface.types ??
20
+ (surface.spec.path === undefined && !files.memory
21
+ ? resolveBare(surface.spec.import, files.root, options, host)
22
+ : undefined);
23
+ if (built !== undefined)
24
+ entries.set(surface.spec.name, sourceOf(files, built));
25
+ }
26
+ const program = ts.createProgram({ rootNames: [...new Set(entries.values())], options, host });
27
+ return { program, entries };
28
+ }
29
+ // The shared host reads disk projects from disk; here every file inside the project comes
30
+ // from the FileSource, so a revision that is not the working tree can stand in for it.
31
+ function overlayHost(files, options) {
32
+ const host = createHost({
33
+ files,
34
+ options,
35
+ virtual: new Map(),
36
+ surfaces: new Map(),
37
+ parsed: new Map(),
38
+ });
39
+ const getSourceFile = host.getSourceFile.bind(host);
40
+ const readFile = host.readFile.bind(host);
41
+ const directoryExists = host.directoryExists?.bind(host);
42
+ const own = (abs) => {
43
+ const rel = relativeTo(files.root, abs);
44
+ return rel !== undefined && !/(^|\/)node_modules\//.test(rel);
45
+ };
46
+ const read = (abs) => (own(abs) ? files.readAbsolute(abs) : readFile(abs));
47
+ host.readFile = read;
48
+ host.fileExists = (abs) => read(abs) !== undefined;
49
+ // A directory that only the base has must still be searched; a missing one costs a lookup.
50
+ host.directoryExists = (dir) => own(dir) || directoryExists?.(dir) === true;
51
+ host.getSourceFile = (name, version, ...rest) => {
52
+ if (!own(name))
53
+ return getSourceFile(name, version, ...rest);
54
+ const text = files.readAbsolute(name);
55
+ return text === undefined ? undefined : ts.createSourceFile(name, text, version, true);
56
+ };
57
+ return host;
58
+ }
59
+ function resolveBare(specifier, root, options, host) {
60
+ const from = path.join(root, 'package.json');
61
+ return ts.resolveModuleName(specifier, from, options, host).resolvedModule?.resolvedFileName;
62
+ }
63
+ /** The source a built module was compiled from, when its source map names one. */
64
+ export function sourceOf(files, built) {
65
+ if (/\.[mc]?tsx?$/.test(built) && !/\.d\.[mc]?ts$/.test(built))
66
+ return built;
67
+ const runtime = built.replace(/\.d\.([mc]?)ts$/, '.$1js');
68
+ for (const map of [`${built}.map`, `${runtime}.map`]) {
69
+ const source = mappedSource(files, map);
70
+ if (source !== undefined)
71
+ return source;
72
+ }
73
+ return built;
74
+ }
75
+ function mappedSource(files, map) {
76
+ // A built file's source map: one that cannot be read maps nothing.
77
+ const parsed = objectOrNothing(files.readAbsolute(map));
78
+ if (!parsed || !isStringArray(parsed.sources))
79
+ return undefined;
80
+ const [first] = parsed.sources;
81
+ const sourceRoot = typeof parsed.sourceRoot === 'string' ? parsed.sourceRoot : '';
82
+ if (first === undefined)
83
+ return undefined;
84
+ const source = path.resolve(path.dirname(map), sourceRoot, first);
85
+ return files.existsAbsolute(source) ? source : undefined;
86
+ }
87
+ //# sourceMappingURL=program.js.map
@@ -0,0 +1,57 @@
1
+ import { TOP_LEVEL } from './units.js';
2
+ // Pairing compares vanished declarations with new ones; past this many candidate pairs a
3
+ // change is no refactor, and the pairs are not worth the time.
4
+ const MAX_PAIRS = 400;
5
+ /**
6
+ * Declarations that vanished and reappeared under another name or in another module with
7
+ * nothing else changed: a rename or a move, which no export can observe on its own.
8
+ * `after` and `before` are fingerprints of the changed modules now and at the base.
9
+ *
10
+ * Moves keep their names, and a moved module's declarations use each other, so every
11
+ * same-name pair is proposed at once and kept only while it holds under all the others.
12
+ * A renamed declaration is then matched alone against what is left.
13
+ */
14
+ export function renames(now, after, before) {
15
+ const added = movable(after, before);
16
+ const removed = movable(before, after);
17
+ if (!added.length || !removed.length || added.length * removed.length > MAX_PAIRS) {
18
+ return new Map();
19
+ }
20
+ const holds = (map, key) => now.fingerprintOf(key, map) === before.get(map.get(key) ?? '');
21
+ const pairs = holding(sameNamePairs(added, removed), holds);
22
+ for (const key of added.filter((k) => !pairs.has(k))) {
23
+ const taken = new Set(pairs.values());
24
+ const old = removed.find((o) => !taken.has(o) && holds(new Map([...pairs, [key, o]]), key));
25
+ if (old !== undefined)
26
+ pairs.set(key, old);
27
+ }
28
+ return pairs;
29
+ }
30
+ /** Keys of `keys` not in `other`: declarations, not a module's top level, which cannot move. */
31
+ function movable(keys, other) {
32
+ return [...keys.keys()].filter((k) => !other.has(k) && !k.endsWith(`#${TOP_LEVEL}`));
33
+ }
34
+ /** Each added key with exactly one removed key of the same name: a move, proposed. */
35
+ function sameNamePairs(added, removed) {
36
+ const pairs = new Map();
37
+ for (const key of added) {
38
+ const same = removed.filter((old) => nameOf(old) === nameOf(key));
39
+ if (same.length === 1 && same[0] !== undefined)
40
+ pairs.set(key, same[0]);
41
+ }
42
+ return pairs;
43
+ }
44
+ /** The pairs, less those that fail under the others, until every one left holds. */
45
+ function holding(pairs, holds) {
46
+ for (let dropped = true; dropped;) {
47
+ const failing = [...pairs.keys()].filter((key) => !holds(pairs, key));
48
+ for (const key of failing)
49
+ pairs.delete(key);
50
+ dropped = failing.length > 0;
51
+ }
52
+ return pairs;
53
+ }
54
+ function nameOf(key) {
55
+ return key.slice(key.lastIndexOf('#') + 1);
56
+ }
57
+ //# sourceMappingURL=renames.js.map
@@ -0,0 +1,62 @@
1
+ import * as path from 'node:path';
2
+ import { fingerprint } from './fingerprint.js';
3
+ import { DependencyGraph } from './graph.js';
4
+ import { UnitLookup } from './lookup.js';
5
+ import { surfacePrograms } from './program.js';
6
+ /** One revision of the project (the base or the working tree), seen through the checker. */
7
+ export class Revision {
8
+ lookup;
9
+ entries;
10
+ root;
11
+ constructor(files, specs) {
12
+ const { program, entries } = surfacePrograms(files, specs);
13
+ this.root = files.root;
14
+ this.lookup = new UnitLookup(program, files.root);
15
+ this.entries = entries;
16
+ }
17
+ /**
18
+ * Fingerprints of every unit in the given modules that this revision's program holds,
19
+ * keyed (and naming what they use) as the base would, through `renamed`.
20
+ */
21
+ fingerprints(files, renamed = new Map()) {
22
+ const out = new Map();
23
+ for (const rel of files) {
24
+ const source = this.lookup.program.getSourceFile(path.join(this.root, rel));
25
+ if (!source)
26
+ continue;
27
+ for (const unit of this.lookup.units(source).units.values()) {
28
+ out.set(renamed.get(unit.key) ?? unit.key, fingerprint(unit, this.lookup, renamed));
29
+ }
30
+ }
31
+ return out;
32
+ }
33
+ /** One unit's fingerprint, once {@link fingerprints} has seen its module. */
34
+ fingerprintOf(key, renamed) {
35
+ const unit = this.lookup.unit(key);
36
+ return unit && fingerprint(unit, this.lookup, renamed);
37
+ }
38
+ /** `surface\0name` → the units each export of each surface stands for. */
39
+ exports() {
40
+ const out = new Map();
41
+ const { program, checker } = this.lookup;
42
+ for (const [surface, entry] of this.entries) {
43
+ const source = program.getSourceFile(entry);
44
+ const module = source && checker.getSymbolAtLocation(source);
45
+ for (const symbol of module ? checker.getExportsOfModule(module) : []) {
46
+ const keys = this.lookup.keysOfSymbol(this.lookup.resolveAlias(symbol));
47
+ out.set(`${surface}\0${symbol.name}`, new Set(keys));
48
+ }
49
+ }
50
+ return out;
51
+ }
52
+ /** Exports that are, or depend on, a changed unit. */
53
+ affected(exported, changed) {
54
+ const graph = new DependencyGraph(this.lookup);
55
+ graph.build([...exported.values()].flatMap((keys) => [...keys]));
56
+ const tainted = graph.tainted(changed);
57
+ return [...exported]
58
+ .filter(([, keys]) => [...keys].some((k) => tainted.has(k)))
59
+ .map(([e]) => e);
60
+ }
61
+ }
62
+ //# sourceMappingURL=revision.js.map
@@ -0,0 +1,80 @@
1
+ import ts from '../ts.cjs';
2
+ /** The name of a module's side-effect unit. */
3
+ export const TOP_LEVEL = '<top-level>';
4
+ /** The units of a module whose project-relative path is `rel`. */
5
+ export function unitsOf(file, rel) {
6
+ const out = { units: new Map(), owner: new Map() };
7
+ const add = (name, node, prefix = '') => {
8
+ const key = `${rel}#${name}`;
9
+ const unit = out.units.get(key) ?? { key, prefix, nodes: [], file };
10
+ unit.nodes.push(node);
11
+ out.units.set(key, unit);
12
+ out.owner.set(node, key);
13
+ };
14
+ for (const statement of file.statements) {
15
+ if (ts.isVariableStatement(statement)) {
16
+ const prefix = variablePrefix(statement);
17
+ for (const d of statement.declarationList.declarations)
18
+ add(bindingName(d.name), d, prefix);
19
+ continue;
20
+ }
21
+ const name = declarationName(statement);
22
+ if (name === null)
23
+ continue;
24
+ add(name ?? TOP_LEVEL, statement);
25
+ }
26
+ return out;
27
+ }
28
+ /** The key of the unit holding a node, walking up to the top level. */
29
+ export function ownerKey(node, owner) {
30
+ for (let n = node; !ts.isSourceFile(n); n = n.parent) {
31
+ const key = owner.get(n);
32
+ if (key !== undefined)
33
+ return key;
34
+ }
35
+ return undefined;
36
+ }
37
+ // `null` for statements that only wire names (imports, re-exports): the checker resolves
38
+ // through them, so the declarations they name carry the dependency. `undefined` for a
39
+ // statement that runs at import time.
40
+ function declarationName(statement) {
41
+ if (wiresNames(statement))
42
+ return null;
43
+ if (ts.isExportAssignment(statement))
44
+ return statement.isExportEquals ? 'export=' : 'default';
45
+ if (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) {
46
+ return statement.name?.text ?? 'default';
47
+ }
48
+ return alwaysNamed(statement) ? statement.name.text : undefined;
49
+ }
50
+ function wiresNames(statement) {
51
+ return (ts.isImportDeclaration(statement) ||
52
+ ts.isImportEqualsDeclaration(statement) ||
53
+ ts.isExportDeclaration(statement));
54
+ }
55
+ function alwaysNamed(statement) {
56
+ return (ts.isInterfaceDeclaration(statement) ||
57
+ ts.isTypeAliasDeclaration(statement) ||
58
+ ts.isEnumDeclaration(statement) ||
59
+ ts.isModuleDeclaration(statement));
60
+ }
61
+ function variablePrefix(statement) {
62
+ const modifiers = (statement.modifiers ?? []).map((m) => ts.tokenToString(m.kind) ?? '');
63
+ const flags = statement.declarationList.flags;
64
+ const kind = flags & ts.NodeFlags.Const ? 'const' : flags & ts.NodeFlags.Let ? 'let' : 'var';
65
+ return [...modifiers, kind].join(' ');
66
+ }
67
+ function bindingName(name) {
68
+ if (ts.isIdentifier(name))
69
+ return name.text;
70
+ const names = [];
71
+ const visit = (n) => {
72
+ if (ts.isBindingElement(n) && ts.isIdentifier(n.name))
73
+ names.push(n.name.text);
74
+ else
75
+ ts.forEachChild(n, visit);
76
+ };
77
+ visit(name);
78
+ return names.join(',');
79
+ }
80
+ //# sourceMappingURL=units.js.map
@@ -0,0 +1,10 @@
1
+ import { description } from './description.js';
2
+ import { createSession } from './session.js';
3
+ import { docCommentExamples } from './syntax/doc-comments.js';
4
+ /** The TypeScript (and JavaScript) language plugin. */
5
+ export const typescript = {
6
+ ...description,
7
+ docComments: docCommentExamples,
8
+ createSession,
9
+ };
10
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1,56 @@
1
+ import { UserError } from '../../api/errors.js';
2
+ import { planExport } from './plan.js';
3
+ import { helperProbeExpression, parseHelperProbe, parseProbe, probeExpression } from './probe.js';
4
+ const PAGE = '__docattest_audit__';
5
+ const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
6
+ /** Evaluates only if the surface loads: its failure is the surface's. */
7
+ const SENTINEL = '0';
8
+ /** The surface a fact without `@` reads (PROTOCOL.md: `observables`). */
9
+ const DEFAULT_SURFACE = 'default';
10
+ /**
11
+ * Observables of one surface's exports, each with the expression that reads it; on the
12
+ * default surface, also of each named fact of the setup module that takes no arguments,
13
+ * called. A helper that shares its name with an export is left out: a fact cannot use it.
14
+ */
15
+ export async function surfaceObservables(evaluator, names, surface) {
16
+ const exported = names.filter((n) => IDENTIFIER.test(n) && n !== 'default');
17
+ const helpers = surface === DEFAULT_SURFACE
18
+ ? evaluator.helperNames.filter((n) => IDENTIFIER.test(n) && !names.includes(n))
19
+ : [];
20
+ const [loaded, ...probes] = await evaluateAll(evaluator, surface, [
21
+ SENTINEL,
22
+ ...exported.map(probeExpression),
23
+ ...helpers.map(helperProbeExpression),
24
+ ]);
25
+ if (!loaded?.ok) {
26
+ throw new UserError(`audit: ${loaded?.message ?? `surface "${surface}" did not evaluate`}`);
27
+ }
28
+ const ofExports = exported.flatMap((name, k) => {
29
+ const probe = probes[k];
30
+ const nodes = probe?.ok ? parseProbe(probe.value.text) : undefined;
31
+ return planExport(name, nodes ?? []);
32
+ });
33
+ const ofHelpers = helpers.flatMap((name, k) => {
34
+ const probe = probes[exported.length + k];
35
+ const found = probe?.ok ? parseHelperProbe(probe.value.text) : undefined;
36
+ if (!found)
37
+ return [];
38
+ return planExport(found.awaited ? `(await ${name}())` : `${name}()`, found.nodes);
39
+ });
40
+ return [...ofExports, ...ofHelpers].map((p) => ({ surface, ...p }));
41
+ }
42
+ async function evaluateAll(evaluator, surface, expressions) {
43
+ const facts = expressions.map((expression, k) => ({
44
+ id: `${PAGE}:${surface}:${k}`,
45
+ kind: 'fact',
46
+ page: PAGE,
47
+ line: k + 1,
48
+ claim: '',
49
+ expression,
50
+ surface,
51
+ ordered: false,
52
+ }));
53
+ const values = await evaluator.evaluate(facts);
54
+ return facts.map((f) => values.get(f.id));
55
+ }
56
+ //# sourceMappingURL=observables.js.map
@@ -0,0 +1,72 @@
1
+ const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
2
+ /** Rows with more fields than this are not read as pairs of fields. */
3
+ const MAX_PAIRED_FIELDS = 6;
4
+ /** A member access: `.key`, or `['key']` when the key is not an identifier. */
5
+ export function member(key) {
6
+ if (IDENTIFIER.test(key))
7
+ return `.${key}`;
8
+ return /['\\\n]/.test(key) ? `[${JSON.stringify(key)}]` : `['${key}']`;
9
+ }
10
+ // A directive cannot hold `-->`, and a line break would split it.
11
+ const writable = (key) => !key.includes('-->') && !/[\r\n]/.test(key);
12
+ /** Every observable of one export, from the nodes the probe returned for it. */
13
+ export function planExport(name, nodes) {
14
+ return nodes.flatMap((node) => {
15
+ if (!node.path.every(writable))
16
+ return [];
17
+ const at = name + node.path.map(member).join('');
18
+ const path = [name, ...node.path];
19
+ if (node.kind === 'scalar')
20
+ return scalar(at, path, node);
21
+ if (node.kind === 'list')
22
+ return [list(at, path, node.items, node.array)];
23
+ if (node.kind === 'records')
24
+ return fieldPlan(path, node.level, node.fields, at);
25
+ return objectPlan(at, path, node);
26
+ });
27
+ }
28
+ function scalar(expression, path, node) {
29
+ const value = { text: node.text, description: `${node.type} ${node.text}` };
30
+ if (node.type === 'string')
31
+ value.kind = 'text';
32
+ return [{ expression, path, value }];
33
+ }
34
+ function list(expression, path, items, array = true) {
35
+ // As `observe` reports an array or a set, so the value is what `check` will see.
36
+ const text = array ? items.join(',') : '[object Set]';
37
+ const value = { text, items, description: array ? 'an array' : 'an object' };
38
+ return { expression, path, value };
39
+ }
40
+ function objectPlan(at, path, node) {
41
+ if (node.enum) {
42
+ // The reverse mapping adds the numbers as keys; the names are what a page lists.
43
+ const keys = (node.keys ?? []).filter((k) => Number.isNaN(Number(k)));
44
+ return [list(`Object.keys(${at}).filter((k) => Number.isNaN(Number(k)))`, path, keys)];
45
+ }
46
+ const out = [];
47
+ if (node.keys)
48
+ out.push(list(`Object.keys(${at})`, path, node.keys));
49
+ if (node.values)
50
+ out.push(list(`Object.values(${at})`, path, node.values));
51
+ out.push(...fieldPlan(path, node.level, node.fields ?? {}, `Object.values(${at})`));
52
+ return out;
53
+ }
54
+ // Each field of the rows near the top of an export, and at the top each ordered pair of
55
+ // fields joined by a space, the way a table writes `GET /jobs` for `{ method, path }`.
56
+ function fieldPlan(path, level, rowFields, rows) {
57
+ const fields = Object.entries(rowFields).filter(([f]) => writable(f));
58
+ if (level > 1)
59
+ return [];
60
+ const single = fields.map(([f, values]) => list(`${rows}.map((r) => r${member(f)})`, [...path, f], values));
61
+ if (level > 0 || fields.length > MAX_PAIRED_FIELDS)
62
+ return single;
63
+ const pairs = fields.flatMap(([a, as]) => fields
64
+ .filter(([b]) => b !== a)
65
+ .map(([b, bs]) => {
66
+ const expression = `${rows}.map((r) => \`\${r${member(a)}} \${r${member(b)}}\`)`;
67
+ const items = as.map((x, k) => `${x} ${bs[k] ?? ''}`);
68
+ return list(expression, [...path, a, b], items);
69
+ }));
70
+ return [...single, ...pairs];
71
+ }
72
+ //# sourceMappingURL=plan.js.map
@@ -0,0 +1,150 @@
1
+ // The probe `audit` evaluates once per export: one fact expression that walks the export's
2
+ // plain objects and namespaces breadth first and returns, as JSON, every value a page could
3
+ // have copied from it. The values are only a guide: whatever is suggested is evaluated again,
4
+ // through its own expression, before it is reported.
5
+ import { isObject, isStringArray, objectOrNothing } from '../../json.js';
6
+ /** Property hops below an export the walk goes, namespaces included. */
7
+ export const MAX_DEPTH = 6;
8
+ /** Values one export may contribute, shallowest first. */
9
+ export const MAX_NODES = 400;
10
+ /** Members of one object the walk descends into. */
11
+ export const MAX_MEMBERS = 100;
12
+ /** Longer lists, key sets and row sets are not read: no page copies them by hand. */
13
+ export const MAX_ITEMS = 500;
14
+ // Helpers are parameters, so they are never mistaken for setup facts or clash with a surface
15
+ // export, and the walk reads only what `check` could read with a plain expression.
16
+ const PROBE = `((v,
17
+ prim = (x) => ['string', 'number', 'bigint', 'boolean'].includes(typeof x),
18
+ plain = (x) => typeof x === 'object' && x !== null && !Array.isArray(x) &&
19
+ (Object.getPrototypeOf(x) === null ||
20
+ Object.getPrototypeOf(Object.getPrototypeOf(x)) === null),
21
+ space = (x) => Object.prototype.toString.call(x) === '[object Module]' ||
22
+ Object.hasOwn(x, '__esModule'),
23
+ rowsOf = (x) => Array.isArray(x) ? x : Object.values(x),
24
+ fieldsOf = (rows) => {
25
+ if (rows.length === 0 || rows.length > ${MAX_ITEMS} || !rows.every(plain)) return undefined;
26
+ const out = {};
27
+ for (const f of Object.keys(rows[0])) {
28
+ const ok = rows.every((r) => Object.hasOwn(r, f) && prim(r[f]));
29
+ if (ok) out[f] = rows.map((r) => String(r[f]));
30
+ }
31
+ return Object.keys(out).length ? out : undefined;
32
+ },
33
+ describe = (x, path, level) => {
34
+ if (prim(x)) return { path, kind: 'scalar', type: typeof x, text: String(x), level };
35
+ if (Array.isArray(x) || x instanceof Set) {
36
+ const items = [...x];
37
+ if (items.length <= ${MAX_ITEMS} && items.every(prim)) {
38
+ return { path, kind: 'list', items: items.map(String), array: Array.isArray(x), level };
39
+ }
40
+ const fields = Array.isArray(x) ? fieldsOf(items) : undefined;
41
+ return fields ? { path, kind: 'records', fields, level } : undefined;
42
+ }
43
+ if (!plain(x)) return undefined;
44
+ const keys = Object.keys(x);
45
+ const vals = keys.map((k) => x[k]);
46
+ return { path, kind: 'object', level, namespace: space(x),
47
+ keys: keys.length <= ${MAX_ITEMS} ? keys : undefined,
48
+ values: keys.length <= ${MAX_ITEMS} && vals.every(prim) ? vals.map(String) : undefined,
49
+ enum: keys.some((k) => typeof x[k] === 'number' && x[x[k]] === k),
50
+ fields: vals.length && vals.every(plain) ? fieldsOf(rowsOf(x)) : undefined };
51
+ },
52
+ walk = () => {
53
+ const out = [];
54
+ const seen = new Set();
55
+ const queue = [[v, [], 0]];
56
+ while (queue.length && out.length < ${MAX_NODES}) {
57
+ const [x, path, level] = queue.shift();
58
+ if (typeof x === 'object' && x !== null) {
59
+ if (seen.has(x)) continue;
60
+ seen.add(x);
61
+ }
62
+ let node;
63
+ try { node = describe(x, path, level); } catch { node = undefined; }
64
+ if (!node) continue;
65
+ out.push(node);
66
+ if (node.kind !== 'object' || path.length >= ${MAX_DEPTH}) continue;
67
+ const below = node.namespace ? level : level + 1;
68
+ for (const key of Object.keys(x).slice(0, ${MAX_MEMBERS})) {
69
+ try { queue.push([x[key], [...path, key], below]); } catch { continue; }
70
+ }
71
+ }
72
+ return out;
73
+ }) => JSON.stringify(walk()))`;
74
+ /** The probe expression for one export. */
75
+ export function probeExpression(name) {
76
+ return `${PROBE}(${name})`;
77
+ }
78
+ // A helper that takes arguments is never called. One that returns a promise is awaited, and
79
+ // says so, since a fact must then await it before reading below its value.
80
+ const HELPER_PROBE = `((h, probe) => typeof h !== 'function' || h.length !== 0 ? 'null' :
81
+ ((r) => typeof r?.then === 'function'
82
+ ? r.then((v) => '{"awaited":true,"nodes":' + probe(v) + '}')
83
+ : '{"awaited":false,"nodes":' + probe(r) + '}')(h()))`;
84
+ /** The probe expression for a named fact of the setup module. */
85
+ export function helperProbeExpression(name) {
86
+ return `${HELPER_PROBE}(${name}, ${PROBE})`;
87
+ }
88
+ /** The probe's JSON, or undefined when it is not what the probe returns. */
89
+ export function parseProbe(text) {
90
+ return toNodes(parseJson(text));
91
+ }
92
+ /** A helper probe's JSON, or undefined when the helper was not called. */
93
+ export function parseHelperProbe(text) {
94
+ const parsed = objectOrNothing(text);
95
+ if (parsed === undefined || typeof parsed.awaited !== 'boolean')
96
+ return undefined;
97
+ const nodes = toNodes(parsed.nodes);
98
+ return nodes && { awaited: parsed.awaited, nodes };
99
+ }
100
+ function parseJson(text) {
101
+ try {
102
+ return JSON.parse(text);
103
+ }
104
+ catch {
105
+ return undefined;
106
+ }
107
+ }
108
+ function toNodes(parsed) {
109
+ return Array.isArray(parsed) ? parsed.flatMap(toNode) : undefined;
110
+ }
111
+ /** A node the probe printed, or none when it does not have its kind's fields. */
112
+ function toNode(entry) {
113
+ if (!isObject(entry) || !isStringArray(entry.path) || typeof entry.level !== 'number')
114
+ return [];
115
+ const found = { path: entry.path, level: entry.level };
116
+ const node = KIND_READERS[String(entry.kind)]?.(entry, found);
117
+ return node ? [node] : [];
118
+ }
119
+ /** For each kind, the node an entry of it makes, or undefined when it lacks a field. */
120
+ const KIND_READERS = {
121
+ scalar: (entry, found) => typeof entry.type === 'string' && typeof entry.text === 'string'
122
+ ? { ...found, kind: 'scalar', type: entry.type, text: entry.text }
123
+ : undefined,
124
+ list: (entry, found) => isStringArray(entry.items)
125
+ ? { ...found, kind: 'list', items: entry.items, array: entry.array === true }
126
+ : undefined,
127
+ records: (entry, found) => {
128
+ const fields = isObject(entry.fields) ? toFields(entry.fields) : undefined;
129
+ return fields ? { ...found, kind: 'records', fields } : undefined;
130
+ },
131
+ object: (entry, found) => {
132
+ const node = { ...found, kind: 'object', enum: entry.enum === true };
133
+ if (isStringArray(entry.keys))
134
+ node.keys = entry.keys;
135
+ if (isStringArray(entry.values))
136
+ node.values = entry.values;
137
+ const fields = isObject(entry.fields) ? toFields(entry.fields) : undefined;
138
+ if (fields)
139
+ node.fields = fields;
140
+ return node;
141
+ },
142
+ };
143
+ function toFields(raw) {
144
+ const out = {};
145
+ for (const [name, values] of Object.entries(raw))
146
+ if (isStringArray(values))
147
+ out[name] = values;
148
+ return Object.keys(out).length ? out : undefined;
149
+ }
150
+ //# sourceMappingURL=probe.js.map