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,98 @@
1
+ // `createProject`: the programmatic API, as a thin client of the docattest core. Every
2
+ // operation runs the core's command (`check --json`, `index --json`, …) on the project and
3
+ // returns what it prints; nothing of docattest's own logic is in this package.
4
+ import { UserError } from '../api/errors.js';
5
+ import { asAudit, asImpact, asIndex, asInventory, asNames, asReferences, asReport, } from './answers.js';
6
+ import { answer, core, failure, runCore } from './core.js';
7
+ import { placeOf } from './place.js';
8
+ /** A project from a directory or an in-memory map of files. */
9
+ export function createProject(input) {
10
+ const place = placeOf(input);
11
+ const env = environment(input);
12
+ const written = [];
13
+ // The core is looked up once, at the project's first run.
14
+ let program;
15
+ // `--root` comes before any `--`, after which every argument is a page or a name.
16
+ const run = (at, [command = '', ...args]) => {
17
+ program ??= core();
18
+ return runCore(program, [command, '--root', at.root, ...args], at.root, env);
19
+ };
20
+ const query = async (args) => place.run(undefined, async (at) => answer(await run(at, args)));
21
+ return {
22
+ check: (options = {}) => check(place, run, options),
23
+ index: async () => asIndex(await query(['index', '--json'])),
24
+ where: async (symbol) => asReferences(await query(['where', '--json', '--', symbol])),
25
+ uncovered: async (surface = 'default') => asNames(await query(['uncovered', '--json', `--surface=${surface}`])),
26
+ audit: async () => asAudit(await query(['audit', '--json'])),
27
+ inventory: async (search) => {
28
+ const args = ['inventory', '--json', ...(search === undefined ? [] : ['--', search])];
29
+ return asInventory(await query(args));
30
+ },
31
+ impact: (options = {}) => impact(place, run, options),
32
+ async refresh(name, ...rest) {
33
+ if (rest.length > 0) {
34
+ throw new UserError('refresh takes no fetcher: the docattest core fetches each snapshot from its source ' +
35
+ 'itself; serve a test source over HTTP instead');
36
+ }
37
+ const files = await refresh(place, run, name);
38
+ for (const file of files)
39
+ if (!written.includes(file))
40
+ written.push(file);
41
+ return files.map((file) => file.slice(file.lastIndexOf('/') + 1, -'.json'.length));
42
+ },
43
+ writes: () => [...written],
44
+ };
45
+ }
46
+ async function check(place, run, options) {
47
+ const { base, pages = [] } = options;
48
+ if (typeof base === 'string' && place.memory) {
49
+ throw new UserError('a git ref as base needs a project on disk; pass `base: { files }`');
50
+ }
51
+ const files = typeof base === 'object' ? base.files : undefined;
52
+ // Files given as the base are committed as HEAD in the project's temporary directory.
53
+ const ref = typeof base === 'string' ? base : files ? 'HEAD' : undefined;
54
+ return place.run(files, async (at) => {
55
+ const args = ['check', '--json', ...(ref === undefined ? [] : [`--base=${ref}`])];
56
+ return asReport(answer(await run(at, [...args, '--', ...pages]), [0, 1]));
57
+ });
58
+ }
59
+ async function impact(place, run, options) {
60
+ const { baseFiles } = options;
61
+ if (baseFiles === undefined && place.memory) {
62
+ throw new UserError('an in-memory project has no git history: pass `baseFiles` to impact');
63
+ }
64
+ return place.run(baseFiles, async (at) => {
65
+ const ref = baseFiles === undefined ? (options.base ?? 'HEAD') : 'HEAD';
66
+ const found = asImpact(answer(await run(at, ['impact', '--json', `--base=${ref}`])));
67
+ // Given files are committed as HEAD; the answer is labelled as the caller labelled it.
68
+ return baseFiles === undefined ? found : { ...found, base: options.base ?? 'files' };
69
+ });
70
+ }
71
+ /** Run `refresh`; returns the files it wrote, in its order, and keeps them in the place. */
72
+ async function refresh(place, run, name) {
73
+ return place.run(undefined, async (at) => {
74
+ const done = await run(at, ['refresh', ...(name === undefined ? [] : ['--', name])]);
75
+ if (done.code !== 0)
76
+ throw failure(done);
77
+ const files = done.stdout
78
+ .split('\n')
79
+ .flatMap((line) => (line.startsWith('wrote ') ? [line.slice('wrote '.length)] : []));
80
+ for (const file of files)
81
+ place.keep(file, at.read(file));
82
+ return files;
83
+ });
84
+ }
85
+ /** `env.now` and `env.network`, as the core reads them. */
86
+ function environment(input) {
87
+ const env = {};
88
+ const { now, network } = input.env ?? {};
89
+ if (now !== undefined) {
90
+ if (Number.isNaN(now.getTime()))
91
+ throw new UserError('`env.now` is not a valid date');
92
+ env.DOCATTEST_NOW = now.toISOString();
93
+ }
94
+ if (network !== undefined)
95
+ env.DOCATTEST_NETWORK = network ? '1' : '0';
96
+ return env;
97
+ }
98
+ //# sourceMappingURL=project.js.map
@@ -0,0 +1,12 @@
1
+ /** A temporary project directory. */
2
+ export interface Workspace {
3
+ root: string;
4
+ /** A project file's contents now, or undefined. */
5
+ read(file: string): string | undefined;
6
+ }
7
+ /**
8
+ * Write `files` to a new temporary directory, run `use` there and remove it again. With
9
+ * `base`, those files are committed first (as `HEAD`), and the working tree is then made
10
+ * exactly `files`.
11
+ */
12
+ export declare function inWorkspace<T>(files: Record<string, string>, base: Record<string, string> | undefined, use: (workspace: Workspace) => Promise<T>): Promise<T>;
@@ -0,0 +1,72 @@
1
+ // An in-memory project on disk, for as long as one call of the API needs it: the core reads
2
+ // projects from disk, so `files` are written to a temporary directory, and a base given as
3
+ // files is committed there with git first.
4
+ import { execFileSync } from 'node:child_process';
5
+ import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
6
+ import { tmpdir } from 'node:os';
7
+ import * as path from 'node:path';
8
+ import { UserError } from '../api/errors.js';
9
+ // Git as docattest uses it here: no one's settings, hooks or signing; one fixed identity.
10
+ const GIT_ENV = {
11
+ ...process.env,
12
+ GIT_CONFIG_GLOBAL: process.platform === 'win32' ? 'NUL' : '/dev/null',
13
+ GIT_CONFIG_NOSYSTEM: '1',
14
+ GIT_AUTHOR_NAME: 'docattest',
15
+ GIT_AUTHOR_EMAIL: 'docattest@example.invalid',
16
+ GIT_COMMITTER_NAME: 'docattest',
17
+ GIT_COMMITTER_EMAIL: 'docattest@example.invalid',
18
+ };
19
+ function write(root, files) {
20
+ for (const [file, text] of Object.entries(files)) {
21
+ const target = path.resolve(root, file);
22
+ const rel = path.relative(root, target);
23
+ if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
24
+ throw new UserError(`an in-memory project's file "${file}" is not inside the project`);
25
+ }
26
+ mkdirSync(path.dirname(target), { recursive: true });
27
+ writeFileSync(target, text);
28
+ }
29
+ }
30
+ function git(root, ...args) {
31
+ try {
32
+ execFileSync('git', args, { cwd: root, env: GIT_ENV, stdio: ['ignore', 'ignore', 'pipe'] });
33
+ }
34
+ catch (err) {
35
+ const message = err instanceof Error ? err.message : String(err);
36
+ throw new UserError(`a base given as files needs git, which failed: ${message}`);
37
+ }
38
+ }
39
+ /**
40
+ * Write `files` to a new temporary directory, run `use` there and remove it again. With
41
+ * `base`, those files are committed first (as `HEAD`), and the working tree is then made
42
+ * exactly `files`.
43
+ */
44
+ export async function inWorkspace(files, base, use) {
45
+ const root = realpathSync(mkdtempSync(path.join(tmpdir(), 'docattest-project-')));
46
+ try {
47
+ if (base !== undefined) {
48
+ write(root, base);
49
+ git(root, 'init', '-q');
50
+ git(root, 'add', '-A');
51
+ git(root, 'commit', '-q', '--allow-empty', '--no-verify', '-m', 'base');
52
+ for (const file of Object.keys(base))
53
+ rmSync(path.join(root, file), { force: true });
54
+ }
55
+ write(root, files);
56
+ return await use({
57
+ root,
58
+ read: (file) => {
59
+ try {
60
+ return readFileSync(path.join(root, file), 'utf8');
61
+ }
62
+ catch {
63
+ return undefined;
64
+ }
65
+ },
66
+ });
67
+ }
68
+ finally {
69
+ rmSync(root, { recursive: true, force: true });
70
+ }
71
+ }
72
+ //# sourceMappingURL=workspace.js.map
@@ -0,0 +1,2 @@
1
+ /** Code-unit string order, independent of locale, so reports are identical everywhere. */
2
+ export declare function compareStrings(a: string, b: string): number;
@@ -0,0 +1,5 @@
1
+ /** Code-unit string order, independent of locale, so reports are identical everywhere. */
2
+ export function compareStrings(a, b) {
3
+ return a < b ? -1 : a > b ? 1 : 0;
4
+ }
5
+ //# sourceMappingURL=compare-strings.js.map
@@ -0,0 +1,113 @@
1
+ // Where a language package finds the docattest core (PROTOCOL.md §1, "Launchers"). The
2
+ // Python launcher (adapters/python/docattest/launcher.py) follows the same rules, so that
3
+ // an npm install and a pip install on one machine can share one binary.
4
+ import { spawnSync } from 'node:child_process';
5
+ import { existsSync } from 'node:fs';
6
+ import { homedir } from 'node:os';
7
+ import * as path from 'node:path';
8
+ /** A variable's value; one that is set to nothing counts as not set. */
9
+ export const given = (value) => (value === '' ? undefined : value);
10
+ /** `<os>-<arch>`, in the names every package uses: `darwin-arm64`, `linux-x64`, `windows-x64`. */
11
+ export function platformName(platform, arch) {
12
+ const os = platform === 'win32' ? 'windows' : platform;
13
+ const cpu = { x86_64: 'x64', amd64: 'x64', aarch64: 'arm64' }[arch.toLowerCase()];
14
+ return `${os}-${cpu ?? arch.toLowerCase()}`;
15
+ }
16
+ /**
17
+ * docattest's own cache directory: `DOCATTEST_CACHE`, else `docattest` in the user's cache
18
+ * directory (`~/Library/Caches` on macOS, `%LOCALAPPDATA%` on Windows, `$XDG_CACHE_HOME`
19
+ * or `~/.cache` elsewhere).
20
+ */
21
+ export function cacheDirectory(around) {
22
+ const { env, platform, home } = around;
23
+ if (env.DOCATTEST_CACHE)
24
+ return env.DOCATTEST_CACHE;
25
+ // Each platform's own separator, whatever platform this code runs on.
26
+ const paths = platform === 'win32' ? path.win32 : path.posix;
27
+ if (platform === 'darwin')
28
+ return paths.join(home, 'Library', 'Caches', 'docattest');
29
+ if (platform === 'win32') {
30
+ const local = given(env.LOCALAPPDATA) ?? paths.join(home, 'AppData', 'Local');
31
+ return paths.join(local, 'docattest');
32
+ }
33
+ const xdg = env.XDG_CACHE_HOME;
34
+ const user = xdg && paths.isAbsolute(xdg) ? xdg : paths.join(home, '.cache');
35
+ return paths.join(user, 'docattest');
36
+ }
37
+ /** Where a core of the pinned version lies in the shared cache. */
38
+ export function cachedCore(pinned, around) {
39
+ const paths = around.platform === 'win32' ? path.win32 : path.posix;
40
+ const name = around.platform === 'win32' ? 'docattest.exe' : 'docattest';
41
+ const platform = platformName(around.platform, around.arch);
42
+ return paths.join(cacheDirectory(around), 'core', pinned.version, platform, name);
43
+ }
44
+ /**
45
+ * The core, in order of preference: `DOCATTEST_CORE`; the binary the package brought; the
46
+ * shared cache. The last two are trusted without being run: the package brought the first
47
+ * itself, and the cache path names the exact version. A core someone else points at is
48
+ * asked what protocol it speaks, and refused when it is not this package's.
49
+ */
50
+ export function findCore(pinned, around, exists = existsSync) {
51
+ const given = around.env.DOCATTEST_CORE;
52
+ if (given)
53
+ return checked(given, pinned, around.ask);
54
+ if (around.bundled !== undefined && exists(around.bundled))
55
+ return { core: around.bundled };
56
+ const cached = cachedCore(pinned, around);
57
+ if (exists(cached))
58
+ return { core: cached };
59
+ const platform = platformName(around.platform, around.arch);
60
+ const brought = around.bundled ?? 'it brought no binary for this platform';
61
+ const remedy = around.remedy === undefined ? '' : `\n${around.remedy}`;
62
+ return {
63
+ error: `docattest: no docattest core ${pinned.version} for ${platform}. Looked in: ` +
64
+ `DOCATTEST_CORE (not set); this package (${brought}); the shared cache (${cached})` +
65
+ remedy,
66
+ };
67
+ }
68
+ function checked(core, pinned, ask) {
69
+ const given = `docattest: DOCATTEST_CORE (${core})`;
70
+ const told = versionOf(ask(core));
71
+ if (told === undefined) {
72
+ return { error: `${given} is not a docattest core: it does not answer --version --json` };
73
+ }
74
+ if (told.protocol !== pinned.protocol) {
75
+ return {
76
+ error: `${given} is core ${told.version}, which speaks adapter protocol ${told.protocol}; ` +
77
+ `this package speaks protocol ${pinned.protocol} (it was built for core ${pinned.version})`,
78
+ };
79
+ }
80
+ return { core };
81
+ }
82
+ function versionOf(answer) {
83
+ try {
84
+ const told = JSON.parse(answer ?? '');
85
+ if (typeof told !== 'object' || told === null)
86
+ return undefined;
87
+ const { version, protocol } = told;
88
+ if (typeof version !== 'string' || typeof protocol !== 'number')
89
+ return undefined;
90
+ return { version, protocol };
91
+ }
92
+ catch {
93
+ return undefined;
94
+ }
95
+ }
96
+ /** Ask a core for its version by running it; nothing else is started by this. */
97
+ function askCore(core) {
98
+ const done = spawnSync(core, ['--version', '--json'], { encoding: 'utf8', timeout: 10_000 });
99
+ return done.status === 0 ? done.stdout : undefined;
100
+ }
101
+ /** This process's surroundings. */
102
+ export function surroundings(bundled, remedy) {
103
+ return {
104
+ env: process.env,
105
+ platform: process.platform,
106
+ arch: process.arch,
107
+ home: homedir(),
108
+ bundled,
109
+ ask: askCore,
110
+ remedy,
111
+ };
112
+ }
113
+ //# sourceMappingURL=locate.js.map
@@ -0,0 +1,70 @@
1
+ // What this npm package tells the core: which core it brought, how to start its adapter, and
2
+ // what command runs docattest in a project that installed it. Shared by the `docattest`
3
+ // launcher (main.ts) and the programmatic API (src/client/), so that both run the same core
4
+ // in the same way. Imports nothing but Node's own modules and ./locate.js.
5
+ import { readFileSync } from 'node:fs';
6
+ import { createRequire } from 'node:module';
7
+ import { fileURLToPath } from 'node:url';
8
+ import { findCore, given, platformName, surroundings } from './locate.js';
9
+ /** How a project that installed docattest from npm runs it: its own copy, never a download. */
10
+ const COMMAND = 'npx --no docattest';
11
+ const here = (relative) => fileURLToPath(new URL(relative, import.meta.url));
12
+ const platforms = () => JSON.parse(readFileSync(here('../platforms.json'), 'utf8'));
13
+ /** The npm package that carries the core for `platform`. */
14
+ const corePackage = (known, platform) => known.npmPackage.replace('{platform}', platform);
15
+ /**
16
+ * The binary this package brought: an optional dependency for each platform, holding
17
+ * `bin/docattest`. npm installs the one whose `os` and `cpu` fit, and skips the others.
18
+ */
19
+ function bundled(known, platform) {
20
+ const name = process.platform === 'win32' ? 'docattest.exe' : 'docattest';
21
+ try {
22
+ return createRequire(import.meta.url).resolve(`${corePackage(known, platform)}/bin/${name}`);
23
+ }
24
+ catch {
25
+ return undefined;
26
+ }
27
+ }
28
+ /** The core this package was built for, copied from protocol/core.json when it was built. */
29
+ export function pinned() {
30
+ return JSON.parse(readFileSync(here('../core.json'), 'utf8'));
31
+ }
32
+ /** What a user with no core is told: why this install has none, and the ways to get one. */
33
+ export function remedy(version, platform, known) {
34
+ const listed = Object.keys(known.platforms);
35
+ if (!listed.includes(platform)) {
36
+ return (`docattest brings a core for ${listed.join(', ')}; there is none for ${platform}. ` +
37
+ `Build one from docattest's source (cargo build --release in its core/ directory) and ` +
38
+ `set DOCATTEST_CORE to it.`);
39
+ }
40
+ const wanted = `${corePackage(known, platform)}@${version}`;
41
+ return (`The core for ${platform} is the package ${wanted}, an optional dependency of docattest, ` +
42
+ `and it is not installed: npm leaves optional dependencies out with --omit=optional ` +
43
+ `(or --no-optional, or omit=optional in .npmrc), and a lockfile written on another ` +
44
+ `platform can leave out this one's. To fix it, install again with them ` +
45
+ `(npm install --include=optional), or add it to the project ` +
46
+ `(npm install --save-optional ${wanted}), or set DOCATTEST_CORE to a docattest core ` +
47
+ `${version}.`);
48
+ }
49
+ /** The core to run, found as PROTOCOL.md §1 says, or why there is none. */
50
+ export function packageCore() {
51
+ const pin = pinned();
52
+ const known = platforms();
53
+ const platform = platformName(process.platform, process.arch);
54
+ const advice = remedy(pin.version, platform, known);
55
+ return findCore(pin, surroundings(bundled(known, platform), advice));
56
+ }
57
+ /**
58
+ * The environment the core runs in: `env`, plus how to start this package's adapter and
59
+ * what command runs docattest. What is already set stands: a developer's own adapter, a
60
+ * wrapper's own command.
61
+ */
62
+ export function coreEnvironment(env) {
63
+ const adapter = [process.execPath, here('../protocol/main.js')];
64
+ return {
65
+ ...env,
66
+ DOCATTEST_ADAPTER_TYPESCRIPT: given(env.DOCATTEST_ADAPTER_TYPESCRIPT) ?? JSON.stringify(adapter),
67
+ DOCATTEST_COMMAND: given(env.DOCATTEST_COMMAND) ?? COMMAND,
68
+ };
69
+ }
70
+ //# sourceMappingURL=package.js.map
package/dist/core.json ADDED
@@ -0,0 +1,4 @@
1
+ {
2
+ "version": "0.1.0",
3
+ "protocol": 1
4
+ }
@@ -0,0 +1,4 @@
1
+ import { type Ignored } from './ignored.js';
2
+ import type { FileSource } from './source.js';
3
+ /** A project in a directory on disk. */
4
+ export declare function diskFiles(root: string, ignored?: Ignored): FileSource;
@@ -0,0 +1,67 @@
1
+ import * as fs from 'node:fs';
2
+ import * as path from 'node:path';
3
+ import { messageOf, UserError } from '../api/errors.js';
4
+ import { NOTHING_IGNORED } from './ignored.js';
5
+ /** A project in a directory on disk. */
6
+ export function diskFiles(root, ignored = NOTHING_IGNORED) {
7
+ const abs = path.resolve(root);
8
+ const at = (file) => path.join(abs, file);
9
+ return {
10
+ root: abs,
11
+ memory: false,
12
+ list: () => walk(abs, '', ignored),
13
+ read: (file) => readText(at(file)),
14
+ exists: (file) => isFile(at(file)),
15
+ readAbsolute: readText,
16
+ existsAbsolute: isFile,
17
+ };
18
+ }
19
+ /** Why a read finds nothing there: no such file, or a directory where a file was expected. */
20
+ const ABSENT = new Set(['ENOENT', 'ENOTDIR', 'EISDIR']);
21
+ /** The file's text; undefined when it is not there. Any other failure is the user's to fix. */
22
+ function readText(file) {
23
+ try {
24
+ return fs.readFileSync(file, 'utf8');
25
+ }
26
+ catch (err) {
27
+ const code = err.code;
28
+ if (code !== undefined && ABSENT.has(code))
29
+ return undefined;
30
+ throw new UserError(`cannot read ${file}: ${messageOf(err)}`);
31
+ }
32
+ }
33
+ function isFile(file) {
34
+ try {
35
+ return fs.statSync(file).isFile();
36
+ }
37
+ catch {
38
+ return false;
39
+ }
40
+ }
41
+ function entries(dir) {
42
+ try {
43
+ return fs.readdirSync(dir, { withFileTypes: true });
44
+ }
45
+ catch {
46
+ return [];
47
+ }
48
+ }
49
+ // Tool state (.git, .docattest, …) is never a page or a source, and neither is anything the
50
+ // language ignores (its dependencies, its build output), by its name. The root is the project
51
+ // whatever it holds.
52
+ function walk(root, rel, ignored) {
53
+ const out = [];
54
+ const found = entries(path.join(root, rel));
55
+ for (const entry of found) {
56
+ const skip = ignored(entry.name) || (entry.isDirectory() && entry.name.startsWith('.'));
57
+ if (skip)
58
+ continue;
59
+ const child = rel ? `${rel}/${entry.name}` : entry.name;
60
+ if (entry.isDirectory())
61
+ out.push(...walk(root, child, ignored));
62
+ else if (entry.isFile())
63
+ out.push(child);
64
+ }
65
+ return out.sort();
66
+ }
67
+ //# sourceMappingURL=disk.js.map
@@ -0,0 +1,10 @@
1
+ import type { SourceFiles } from '../api/adapter.js';
2
+ /** A predicate for project-relative paths matching any of the globs. Dotfiles match. */
3
+ export declare function globMatcher(globs: readonly string[]): (file: string) => boolean;
4
+ /**
5
+ * A predicate for the project-relative paths a language calls its source files: those that
6
+ * match a glob of `include` and no glob of `exclude`.
7
+ */
8
+ export declare function sourceFileMatcher(files: SourceFiles): (file: string) => boolean;
9
+ /** Whether a pattern contains glob syntax, as opposed to naming one path. */
10
+ export declare function isGlob(pattern: string): boolean;
@@ -0,0 +1,21 @@
1
+ import picomatch from 'picomatch';
2
+ /** A predicate for project-relative paths matching any of the globs. Dotfiles match. */
3
+ export function globMatcher(globs) {
4
+ if (globs.length === 0)
5
+ return () => false;
6
+ return picomatch(globs.map((g) => g.replace(/^\.\//, '')), { dot: true });
7
+ }
8
+ /**
9
+ * A predicate for the project-relative paths a language calls its source files: those that
10
+ * match a glob of `include` and no glob of `exclude`.
11
+ */
12
+ export function sourceFileMatcher(files) {
13
+ const included = globMatcher(files.include);
14
+ const excluded = globMatcher(files.exclude);
15
+ return (file) => included(file) && !excluded(file);
16
+ }
17
+ /** Whether a pattern contains glob syntax, as opposed to naming one path. */
18
+ export function isGlob(pattern) {
19
+ return picomatch.scan(pattern).isGlob;
20
+ }
21
+ //# sourceMappingURL=glob.js.map
@@ -0,0 +1,14 @@
1
+ import type { LanguageDescription } from '../api/adapter.js';
2
+ /**
3
+ * Whether a file or directory of this name is never the project's own, wherever it is (the
4
+ * language's `ignoredNames`). A rule about one directory entry, so a walk turns away at the
5
+ * entry itself and never looks below it.
6
+ */
7
+ export type Ignored = (name: string) => boolean;
8
+ /** Nothing is ignored. */
9
+ export declare const NOTHING_IGNORED: Ignored;
10
+ /**
11
+ * The rule a language states: each name is a glob for one path segment, read as the config's
12
+ * globs are.
13
+ */
14
+ export declare function ignoreRule(language: Pick<LanguageDescription, 'ignoredNames'>): Ignored;
@@ -0,0 +1,14 @@
1
+ import { globMatcher, isGlob } from './glob.js';
2
+ /** Nothing is ignored. */
3
+ export const NOTHING_IGNORED = () => false;
4
+ /**
5
+ * The rule a language states: each name is a glob for one path segment, read as the config's
6
+ * globs are.
7
+ */
8
+ export function ignoreRule(language) {
9
+ const exact = new Set(language.ignoredNames.filter((n) => !isGlob(n)));
10
+ const globs = language.ignoredNames.filter(isGlob);
11
+ const matches = globMatcher(globs);
12
+ return (name) => exact.has(name) || (globs.length > 0 && matches(name));
13
+ }
14
+ //# sourceMappingURL=ignored.js.map
@@ -0,0 +1,5 @@
1
+ import { type FileSource } from './source.js';
2
+ /** The virtual root of in-memory projects. Nothing is ever read from or written to it. */
3
+ export declare const MEMORY_ROOT = "/__docattest_memory__";
4
+ /** A project held in memory: path → contents. */
5
+ export declare function memoryFiles(initial: Record<string, string>): FileSource;
@@ -0,0 +1,26 @@
1
+ import { normalise, relativeTo } from './source.js';
2
+ /** The virtual root of in-memory projects. Nothing is ever read from or written to it. */
3
+ export const MEMORY_ROOT = '/__docattest_memory__';
4
+ /** A project held in memory: path → contents. */
5
+ export function memoryFiles(initial) {
6
+ const files = new Map(Object.entries(initial).map(([k, v]) => [normalise(k), v]));
7
+ const read = (file) => files.get(normalise(file));
8
+ const toRelative = (abs) => relativeTo(MEMORY_ROOT, abs);
9
+ const source = {
10
+ root: MEMORY_ROOT,
11
+ memory: true,
12
+ list: () => [...files.keys()].sort(),
13
+ read,
14
+ exists: (file) => files.has(normalise(file)),
15
+ readAbsolute: (abs) => {
16
+ const rel = toRelative(abs);
17
+ return rel === undefined ? undefined : read(rel);
18
+ },
19
+ existsAbsolute: (abs) => {
20
+ const rel = toRelative(abs);
21
+ return rel !== undefined && files.has(rel);
22
+ },
23
+ };
24
+ return source;
25
+ }
26
+ //# sourceMappingURL=memory.js.map
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Where a project's files come from: a directory on disk or an in-memory map. Relative
3
+ * paths are project-relative and POSIX-style; absolute paths are native.
4
+ */
5
+ export interface FileSource {
6
+ /** Absolute root. For in-memory projects, a virtual directory that does not exist. */
7
+ readonly root: string;
8
+ readonly memory: boolean;
9
+ /** Every project file, sorted; skips hidden directories and what is being ignored. */
10
+ list(): string[];
11
+ read(file: string): string | undefined;
12
+ exists(file: string): boolean;
13
+ /** Read by absolute path; in-memory projects see only their own files. */
14
+ readAbsolute(file: string): string | undefined;
15
+ existsAbsolute(file: string): boolean;
16
+ }
17
+ /** A project-relative path in canonical form: forward slashes, no `./`, no doubled `/`. */
18
+ export declare function normalise(file: string): string;
19
+ /** The project-relative form of an absolute path, or undefined when it lies outside. */
20
+ export declare function relativeTo(root: string, file: string): string | undefined;
21
+ /** A path for messages: project-relative when inside the project, else absolute. */
22
+ export declare function displayPath(root: string, file: string): string;
@@ -0,0 +1,17 @@
1
+ import * as path from 'node:path';
2
+ /** A project-relative path in canonical form: forward slashes, no `./`, no doubled `/`. */
3
+ export function normalise(file) {
4
+ return file.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+/g, '/');
5
+ }
6
+ /** The project-relative form of an absolute path, or undefined when it lies outside. */
7
+ export function relativeTo(root, file) {
8
+ const rel = path.relative(root, file);
9
+ if (rel.startsWith('..') || path.isAbsolute(rel))
10
+ return undefined;
11
+ return rel.split(path.sep).join('/');
12
+ }
13
+ /** A path for messages: project-relative when inside the project, else absolute. */
14
+ export function displayPath(root, file) {
15
+ return relativeTo(root, file) ?? file;
16
+ }
17
+ //# sourceMappingURL=source.js.map
@@ -0,0 +1,10 @@
1
+ export { CHANGE_TYPES, COMMANDS, CONFIG_KEYS, DEFAULT_SNAPSHOT_MAX_AGE_DAYS, DEFAULT_TIMEOUT_MS, KINDS, STATUSES, } from './api/constants.js';
2
+ export type { ChangeType, Kind, Status } from './api/constants.js';
3
+ export type { Config, Member, SurfaceEntry } from './api/config.js';
4
+ export type { Change, Coverage, MemberReport, Reference, Report, Result, SnapshotStatus, SurfaceCoverage, SurfaceResolution, } from './api/report.js';
5
+ export type { CheckOptions, Project, ProjectInput } from './api/project.js';
6
+ export type { AuditReport, AuditStatus, AuditTarget, InventoryEntry, Suggestion, } from './api/audit.js';
7
+ export type { Impact, ImpactOptions, ImpactReference } from './api/impact.js';
8
+ export type { Attestation, CasesAttestation, CasesRow, ExampleAttestation, FactAttestation, FactTarget, TestAttestation, } from './api/attestation.js';
9
+ export { InternalError, UserError } from './api/errors.js';
10
+ export { createProject } from './client/project.js';
package/dist/index.js ADDED
@@ -0,0 +1,6 @@
1
+ // The public API: `createProject`, a thin client of the docattest core (it runs the core
2
+ // that the `docattest` launcher runs), and the shapes it returns.
3
+ export { CHANGE_TYPES, COMMANDS, CONFIG_KEYS, DEFAULT_SNAPSHOT_MAX_AGE_DAYS, DEFAULT_TIMEOUT_MS, KINDS, STATUSES, } from './api/constants.js';
4
+ export { InternalError, UserError } from './api/errors.js';
5
+ export { createProject } from './client/project.js';
6
+ //# sourceMappingURL=index.js.map
package/dist/json.d.ts ADDED
@@ -0,0 +1,16 @@
1
+ /** A JSON-like object, as far as a check has established. */
2
+ export type JsonObject = Record<string, unknown>;
3
+ /** Whether a value is a plain object: not an array, not null. */
4
+ export declare function isObject(value: unknown): value is JsonObject;
5
+ /** Whether a value is an array of strings. */
6
+ export declare function isStringArray(value: unknown): value is string[];
7
+ /**
8
+ * The object `text` holds, or undefined when there is no text, it is not JSON or it is not an
9
+ * object. Only for files that are not the user's to fix: a dependency's manifest, a map.
10
+ */
11
+ export declare function objectOrNothing(text: string | undefined): JsonObject | undefined;
12
+ /**
13
+ * The object one of the project's own files holds (`text`, read from `file`), or undefined
14
+ * when there is no such file. A file that is not an object in its format is the user's to fix.
15
+ */
16
+ export declare function projectObject(text: string | undefined, file: string, parse?: (text: string) => unknown): JsonObject | undefined;