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
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Matthew Hammond
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,148 @@
1
- # Temporary Holding Version
1
+ # docattest
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **Documentation that CI can fail**, for TypeScript and JavaScript projects.
4
+
5
+ A Markdown page carries its own proof: examples that run, values in the prose that are
6
+ compared with your code, tables whose rows are tests, and citations of tests you already
7
+ have. When the code changes and a sentence stops being true, `docattest check` fails at that
8
+ page and line. Here the page said a call is tried `3` times and listed two environment
9
+ variables; the code now says 5, and reads a third:
10
+
11
+ ```console check cwd=docs/.fixtures/acme-client
12
+ $ docattest check
13
+ docs/retries.md
14
+ ✗ L1 fact: expected 3, got 5 from RETRY_DEFAULTS.maxAttempts
15
+ ✗ L3 fact: expected 2 items from the page, got 3 from ENV_KEYS; missing: LOG_LEVEL
16
+ results: 0 pass, 2 fail, 0 error, 0 skipped
17
+ ...
18
+ FAILED
19
+ [exit 1]
20
+ ```
21
+
22
+ This is the npm package. The same tool for Python is the PyPI package `docattest`, and
23
+ for Go a release archive ([adapters/go](../go/README.md)), and for Rust a cargo package
24
+ ([adapters/rust](../rust/README.md)); all run one shared core. The project's front page is the
25
+ [repository README](../../README.md), and the full documentation is in
26
+ [docs/](../../docs/index.md).
27
+
28
+ ## Install
29
+
30
+ ```sh
31
+ npm install --save-dev docattest typescript
32
+ ```
33
+
34
+ Node 22.12 or later. <!-- fact: manifest("adapters/typescript/package.json").engines.node.replace(">=", "") -->
35
+ TypeScript from `5.4` up to (not including) `7` <!-- fact ordered: manifest("adapters/typescript/package.json").peerDependencies.typescript.match(/[\d.]+/g) --> is a
36
+ peer dependency: examples are type-checked with your project's own compiler.
37
+
38
+ The install brings the docattest core, a small native program, as the one optional
39
+ dependency of these that is built for your machine: <!-- fact: Object.keys(manifest("adapters/typescript/package.json").optionalDependencies) -->
40
+ - `@docattest/core-darwin-arm64`: macOS on Apple silicon
41
+ - `@docattest/core-darwin-x64`: macOS on Intel
42
+ - `@docattest/core-linux-arm64`: Linux arm64, glibc or musl
43
+ - `@docattest/core-linux-x64`: Linux x86-64, glibc or musl
44
+ - `@docattest/core-windows-x64`: Windows x64
45
+
46
+ There is no install script, and nothing is downloaded when docattest runs. If your install
47
+ leaves optional dependencies out (`--omit=optional`, or a lockfile written on another
48
+ platform), `docattest` says so and how to fix it.
49
+
50
+ ## Quick start
51
+
52
+ 1. Add `docattest.config.json` at the project root:
53
+
54
+ ```json
55
+ {
56
+ "pages": ["docs/**/*.md"],
57
+ "surfaces": { "default": "./src/index.ts" },
58
+ "adapter": "typescript"
59
+ }
60
+ ```
61
+
62
+ The *surface* is your public API: what pages may import (under your package's name) and
63
+ what facts may read.
64
+
65
+ 2. Add proofs to a page, for example `docs/retries.md`:
66
+
67
+ ````md check fixture=docs/.fixtures/acme-client as=docs/retries.md
68
+ A failing call is tried at most `5` times. <!-- fact: RETRY_DEFAULTS.maxAttempts -->
69
+
70
+ ```ts check
71
+ import { RETRY_DEFAULTS } from '@acme/client';
72
+ assert.ok(RETRY_DEFAULTS.backoffMs > 0);
73
+ ```
74
+ ````
75
+
76
+ 3. Run `npx docattest check`. It exits 1 when a page and the code disagree.
77
+
78
+ ## What TypeScript brings
79
+
80
+ | Proof | You write | It fails when |
81
+ |---|---|---|
82
+ | **Example** | a block tagged `ts check` (runs) or `ts compile` (type-checks only); `js`, `tsx` and friends too | it throws, an `assert` fails, or it no longer type-checks |
83
+ | **Fact** | `<!-- fact: expression -->` after a value, or above a list, table column or code block | the value on the page differs from `String(value)` of the expression |
84
+ | **Cases** | `<!-- cases: runner -->` above a table, with the runner in your setup module | a row's expected result is not what the runner produces |
85
+ | **Citation** | `<!-- test: test/retry.test.ts > "describe title" > "test title" -->` | the file no longer declares an `it` or `test` with that title |
86
+ | **Doc comment** | an `@example` whose first line is `// check` or `// compile`, in a file under `sources` | as for an example |
87
+
88
+ Every example is its own module with a fresh import of your package, runs in a worker with a
89
+ time limit, and has the network off: a `check network` block runs only when
90
+ `DOCATTEST_NETWORK=1` is set, and is skipped otherwise. Lines above `// ---cut---` run but
91
+ are setup that renderers can hide. A surface is an entry file (`./src/index.ts`), a package
92
+ name resolved as Node would, or both (`{ "import": "@acme/client", "path":
93
+ "packages/client/dist/index.js" }`), which is how a monorepo points a page at one package's
94
+ build.
95
+
96
+ A fact expression reads the surface's exports by their names, `snapshot("name")`, and
97
+ `manifest("path")`: the parsed data of a project file such as `package.json`, so a claim
98
+ about what the package declares needs no setup code. The versions at the top of this page
99
+ are read so ([manifests](../../docs/manifests.md)).
100
+
101
+ ## Commands
102
+
103
+ Every command (`check`, `where`, `impact` and the rest) is described in the
104
+ [repository README](../../README.md#commands) and [the command line](../../docs/cli.md).
105
+
106
+ ## From code
107
+
108
+ ```ts compile
109
+ import { createProject } from 'docattest';
110
+
111
+ const report = await createProject({ root: '.' }).check();
112
+ console.log(report.exitCode, report.results.length);
113
+ ```
114
+
115
+ `createProject` runs the same core the command runs and returns what it prints with
116
+ `--json`, typed. It also takes an in-memory map of files instead of a root.
117
+
118
+ ## What is in this package
119
+
120
+ The package installs these commands: <!-- fact: Object.keys(manifest("adapters/typescript/package.json").bin) -->
121
+ - `docattest`: a launcher that finds the core (`DOCATTEST_CORE`, else the platform package,
122
+ else a cache shared with the other language packages), tells it how to start the
123
+ TypeScript adapter, and becomes it.
124
+ - `docattest-adapter-typescript`: the TypeScript adapter, which the core starts and talks to
125
+ over [the adapter protocol](../../protocol/PROTOCOL.md). You never run it yourself.
126
+
127
+ Its module exports `createProject` and the types it returns: the programmatic API
128
+ ([from code](#from-code)).
129
+
130
+ ## Working on this package
131
+
132
+ The sources are grouped by what they serve. The TypeScript language itself (compiling and
133
+ running examples, evaluating facts, reading symbols, resolving surfaces, what a change
134
+ affects) is under `src/language/`, the only part that loads the compiler. Around it are the
135
+ protocol server that answers the core, the `docattest` command and the code that finds the
136
+ core it runs, `createProject`, which runs the core for code, and the public types. Tests in
137
+ `test/` mirror that layout under `unit/`; `protocol/` drives the built server over its pipes;
138
+ and the acceptance and corpus tests run one test per criterion of
139
+ [ACCEPTANCE.md](../../docs/design/ACCEPTANCE.md) and per event of
140
+ [CORPUS.md](../../docs/design/CORPUS.md) through the built package and the core.
141
+ `conformance.json` is this adapter's kit for the protocol's conformance suite.
142
+
143
+ From the repository root: `npm ci`, `npm run build:core`, `npm run build`, `npm test`.
144
+ [CONTRIBUTING.md](../../CONTRIBUTING.md) has the rest.
145
+
146
+ ## License
147
+
148
+ [MIT](LICENSE)
@@ -0,0 +1,30 @@
1
+ {
2
+ "$schema": "../schema/agent.json#/$defs/Agent",
3
+ "name": "claude",
4
+ "docs": "https://code.claude.com/docs/en/hooks",
5
+ "projectRoot": "\"$CLAUDE_PROJECT_DIR\"",
6
+ "skill": ".claude/skills/docattest/SKILL.md",
7
+ "settings": {
8
+ "file": ".claude/settings.json",
9
+ "hooks": "hooks",
10
+ "group": "hooks",
11
+ "handler": { "type": "command" },
12
+ "command": "command"
13
+ },
14
+ "hooks": {
15
+ "impact": {
16
+ "event": "PostToolUse",
17
+ "matcher": "Edit|Write",
18
+ "file": ["tool_input", "file_path"],
19
+ "reply": {
20
+ "fixed": { "hookSpecificOutput": { "hookEventName": "PostToolUse" } },
21
+ "text": ["hookSpecificOutput", "additionalContext"]
22
+ }
23
+ },
24
+ "check": {
25
+ "event": "Stop",
26
+ "continuing": ["stop_hook_active"],
27
+ "reply": { "fixed": { "decision": "block" }, "text": ["reason"] }
28
+ }
29
+ }
30
+ }
@@ -0,0 +1,19 @@
1
+ {
2
+ "$schema": "../schema/agent.json#/$defs/Agent",
3
+ "name": "cursor",
4
+ "docs": "https://cursor.com/docs/agent/hooks",
5
+ "skill": ".cursor/skills/docattest/SKILL.md",
6
+ "settings": {
7
+ "file": ".cursor/hooks.json",
8
+ "hooks": "hooks",
9
+ "command": "command",
10
+ "defaults": { "version": 1 }
11
+ },
12
+ "hooks": {
13
+ "check": {
14
+ "event": "stop",
15
+ "continuing": ["loop_count"],
16
+ "reply": { "text": ["followup_message"] }
17
+ }
18
+ }
19
+ }
@@ -0,0 +1,27 @@
1
+ {
2
+ "$schema": "../schema/agent.json#/$defs/Agent",
3
+ "name": "gemini",
4
+ "docs": "https://geminicli.com/docs/hooks/reference/",
5
+ "projectRoot": "\"$GEMINI_PROJECT_DIR\"",
6
+ "skill": ".gemini/skills/docattest/SKILL.md",
7
+ "settings": {
8
+ "file": ".gemini/settings.json",
9
+ "hooks": "hooks",
10
+ "group": "hooks",
11
+ "handler": { "type": "command" },
12
+ "command": "command"
13
+ },
14
+ "hooks": {
15
+ "impact": {
16
+ "event": "AfterTool",
17
+ "matcher": "write_file|replace",
18
+ "file": ["tool_input", "file_path"],
19
+ "reply": { "text": ["hookSpecificOutput", "additionalContext"] }
20
+ },
21
+ "check": {
22
+ "event": "AfterAgent",
23
+ "continuing": ["stop_hook_active"],
24
+ "reply": { "fixed": { "decision": "deny" }, "text": ["reason"] }
25
+ }
26
+ }
27
+ }
@@ -0,0 +1,3 @@
1
+ {
2
+ "default": "claude"
3
+ }
@@ -0,0 +1,231 @@
1
+ import type { FileSource } from '../files/source.js';
2
+ import type { Attestation, CasesAttestation, ExampleAttestation, FactAttestation } from './attestation.js';
3
+ import type { SurfaceEntry } from './config.js';
4
+ import type { Result, SurfaceResolution } from './report.js';
5
+ /** A compiler message for one example; `line` is within the block. */
6
+ export interface Diagnostic {
7
+ id: string;
8
+ message: string;
9
+ line?: number;
10
+ }
11
+ /** A fact's value as observed by the runtime: what the comparison needs, as plain data. */
12
+ export interface Observation {
13
+ /** The value as the language itself displays it: `String(value)` here, `str(value)` in Python. */
14
+ text: string;
15
+ /** Each item as a string, when the value is a list, a set or another iterable. */
16
+ items?: string[];
17
+ /** A short description for messages, such as `an object` or `number 3`. */
18
+ description: string;
19
+ /**
20
+ * `text` when the value is text, a string of the language: the one thing about a value's
21
+ * type the core needs (only text can be what a fenced block copies). Absent otherwise.
22
+ */
23
+ kind?: 'text';
24
+ }
25
+ /** The outcome of evaluating one fact expression. */
26
+ export type Evaluation = {
27
+ ok: true;
28
+ value: Observation;
29
+ } | {
30
+ ok: false;
31
+ message: string;
32
+ };
33
+ /** A surface symbol an attestation exercises. `surface` is absent when none exports it. */
34
+ export interface SymbolRef {
35
+ name: string;
36
+ surface?: string;
37
+ }
38
+ /** A test or describe block a test file declares, by its literal title. */
39
+ export interface DeclaredTest {
40
+ title: string;
41
+ /** Enclosing describe titles, outermost first; null where a title is not a literal. */
42
+ describes: (string | null)[];
43
+ line: number;
44
+ }
45
+ /**
46
+ * Something a test file declares that can be cited by mistake for a test: a describe
47
+ * block. `kind` says what it is, in the language's words, with its article: the core's
48
+ * message reads `"x" in a.test.ts is <kind>, not a test`.
49
+ */
50
+ export interface DeclaredSuite extends DeclaredTest {
51
+ kind: string;
52
+ }
53
+ /** What a test file declares, or why it cannot be read. */
54
+ export type TestListing = {
55
+ ok: true;
56
+ tests: DeclaredTest[];
57
+ suites: DeclaredSuite[];
58
+ } | {
59
+ ok: false;
60
+ message: string;
61
+ };
62
+ /**
63
+ * The language's words for what the core's sentences name. Each is optional; the core has
64
+ * a default that says the same thing in no language's terms.
65
+ */
66
+ export interface Vocabulary {
67
+ /** Stands for an enclosing title that cannot be cited, in a test's path. Default `(untitled)`. */
68
+ untitled?: string;
69
+ /** What a file with no test to cite is said to do. Default `it declares no test`. */
70
+ noTests?: string;
71
+ }
72
+ /** What the protocol server asks of the language for one project (PROTOCOL.md §3). */
73
+ export interface Adapter {
74
+ /** Type-check examples; diagnostics are keyed by attestation id. */
75
+ compile(examples: readonly ExampleAttestation[]): Promise<Diagnostic[]>;
76
+ /** Evaluate fact expressions against their surfaces. Pure: no side effects. */
77
+ evaluate(facts: readonly FactAttestation[]): Promise<Map<string, Evaluation>>;
78
+ /** Run examples and cases tables in isolation. */
79
+ run(examples: readonly ExampleAttestation[], cases: readonly CasesAttestation[]): Promise<Result[]>;
80
+ /** Surface symbols an attestation exercises. */
81
+ symbols(attestation: Attestation): Promise<SymbolRef[]>;
82
+ /** Public names a surface offers, or undefined when it cannot be resolved. */
83
+ exports(surface: string): Promise<string[] | undefined>;
84
+ /** The tests and describe blocks a project-relative test file declares, from its syntax. */
85
+ tests(file: string): Promise<TestListing>;
86
+ }
87
+ /**
88
+ * A surface as the config states it. What the entry means (a file of the project, a package,
89
+ * a module, a crate) is the adapter's to say; the core only knows its name.
90
+ */
91
+ export interface ConfiguredSurface {
92
+ name: string;
93
+ /** The config's value for this surface, as written. */
94
+ entry: SurfaceEntry;
95
+ }
96
+ /** How one surface resolved, for the report. */
97
+ export interface SurfaceDescription {
98
+ resolution?: SurfaceResolution;
99
+ warnings: string[];
100
+ }
101
+ /** What an adapter is built from: one project, for one check or query. */
102
+ export interface AdapterContext {
103
+ files: FileSource;
104
+ /** The config's surfaces, in its order, as written. */
105
+ surfaces: readonly ConfiguredSurface[];
106
+ setup: string | undefined;
107
+ timeoutMs: number;
108
+ workers: number;
109
+ /** Whether `check network` examples may run. */
110
+ network: boolean;
111
+ snapshots: {
112
+ dir: string | undefined;
113
+ data: ReadonlyMap<string, unknown>;
114
+ };
115
+ /** The data of each manifest the facts name, by the path as they write it. */
116
+ manifests: ReadonlyMap<string, unknown>;
117
+ /** The examples this session will compile; the program is built around them. */
118
+ examples: readonly ExampleAttestation[];
119
+ }
120
+ /** A value a surface offers a reader, with the fact expression that reads it. */
121
+ export interface Observable {
122
+ surface: string;
123
+ /** A fact expression that evaluates to `value`. */
124
+ expression: string;
125
+ /** Names on the way to the value: the export, then the members, then a field. */
126
+ path: string[];
127
+ value: Observation;
128
+ }
129
+ /** The project at a base revision, for `impact`. */
130
+ export interface SourceChange {
131
+ /** The project's files as they were at the base: same root, base contents. */
132
+ base: FileSource;
133
+ /** Project-relative paths whose contents differ between the base and now. */
134
+ changed: readonly string[];
135
+ }
136
+ /** An adapter for one check, plus what the report and the lifecycle need. */
137
+ export interface AdapterSession extends Adapter {
138
+ /** How each configured surface resolved, by surface name. */
139
+ describeSurfaces(): Promise<Map<string, SurfaceDescription>>;
140
+ /**
141
+ * Values a surface exports, nested ones included, each with the fact expression that
142
+ * reads it, for `audit`. Throws a `UserError` when the surface cannot be loaded.
143
+ */
144
+ observables(surface: string): Promise<Observable[]>;
145
+ /**
146
+ * Surface exports whose declaration changed since the base, or that reach a changed
147
+ * declaration through the code they use.
148
+ */
149
+ affected(change: SourceChange): Promise<SymbolRef[]>;
150
+ /**
151
+ * Which of `names` still occur as a name in the project's code: in the project-relative
152
+ * `files` (the ones the config's `sources` names) and in the files the surfaces are read
153
+ * from. An adapter that cannot tell returns every name.
154
+ */
155
+ inCode(names: readonly string[], files: readonly string[]): Promise<string[]>;
156
+ /** Release workers and anything else the session holds. */
157
+ close(): Promise<void>;
158
+ }
159
+ /**
160
+ * Which project files are source files of a language, as data the core applies without
161
+ * knowing the language: a file is one when its project-relative path matches a glob of
162
+ * `include` and no glob of `exclude`. The globs are read like the config's own
163
+ * (`sourceFileMatcher` in `src/files/glob.ts`): whole path, dotfiles match, case matters.
164
+ */
165
+ export interface SourceFiles {
166
+ readonly include: readonly string[];
167
+ readonly exclude: readonly string[];
168
+ }
169
+ /** A source file, or what stands for one: its project-relative path and its text. */
170
+ export interface SourceText {
171
+ page: string;
172
+ text: string;
173
+ }
174
+ /** The prose of one doc comment: its description as a claim is written, and its lines. */
175
+ export interface DocProse {
176
+ /** The description on one line: comments removed, whitespace collapsed, markup kept. */
177
+ text: string;
178
+ /** The comment's first and last line, counted from 1. */
179
+ start: number;
180
+ end: number;
181
+ }
182
+ /** A fact expression with its names taken out. */
183
+ export interface ExpressionShape {
184
+ /**
185
+ * The expression with every name replaced by a placeholder. Two expressions with the same
186
+ * shape differ in nothing but their names; shapes are only ever compared for equality.
187
+ */
188
+ shape: string;
189
+ /** The names, in the order they occur; a name used twice is listed twice. */
190
+ names: string[];
191
+ }
192
+ /**
193
+ * What a language says of itself without its compiler or runtime, so that it is answered
194
+ * at once: static data, and questions about text that need no project. Every method takes
195
+ * many items and answers one for each, in order.
196
+ */
197
+ export interface LanguageDescription {
198
+ /** Info-string languages whose fenced blocks this language runs, lower case. */
199
+ readonly blockLanguages: readonly string[];
200
+ /** The project files that are this language's source code: doc comments may hold examples. */
201
+ readonly sourceFiles: SourceFiles;
202
+ /**
203
+ * Names of files and directories that are never the project's own, wherever they are:
204
+ * installed dependencies, build output. Each is a glob for one name (`*.egg-info`), never
205
+ * for a path. A path with such a segment is not a project file.
206
+ */
207
+ readonly ignoredNames: readonly string[];
208
+ /** The language's words for what the core's sentences name. */
209
+ readonly vocabulary: Vocabulary;
210
+ /** Whether each example's code asserts anything; one that does not is weak coverage. */
211
+ assertions(examples: readonly {
212
+ lang: string;
213
+ code: string;
214
+ }[]): Promise<boolean[]>;
215
+ /** The doc comments of each source file as prose, in the order they are written. */
216
+ docProse(files: readonly SourceText[]): Promise<DocProse[][]>;
217
+ /**
218
+ * For each inline code span of a page, the one of `symbols` it names, or null. A name is
219
+ * always part of the span that names it.
220
+ */
221
+ mentions(spans: readonly string[], symbols: readonly string[]): Promise<(string | null)[]>;
222
+ /** The shape and the names of each fact expression. */
223
+ expressions(expressions: readonly string[]): Promise<ExpressionShape[]>;
224
+ }
225
+ /** The whole language: its description, how to find its examples, and its sessions. */
226
+ export interface Language extends LanguageDescription {
227
+ /** `@example` attestations in one source file's doc comments. */
228
+ docComments(page: string, text: string): ExampleAttestation[];
229
+ /** Build the adapter for one check or query. */
230
+ createSession(context: AdapterContext): AdapterSession;
231
+ }
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=adapter.js.map
@@ -0,0 +1,76 @@
1
+ /** What a fact compares its value with: the literal, list, column or block on the page. */
2
+ export type FactTarget = {
3
+ kind: 'scalar';
4
+ value: string;
5
+ } | {
6
+ kind: 'set';
7
+ items: string[];
8
+ from: 'list' | 'table' | 'sentence';
9
+ } | {
10
+ kind: 'text';
11
+ text: string;
12
+ };
13
+ interface AttestationBase {
14
+ /** Unique within one check. */
15
+ id: string;
16
+ page: string;
17
+ line: number;
18
+ /** The sentence the proof defends. */
19
+ claim: string;
20
+ /** A problem found while planning; the attestation is an `error` without running. */
21
+ error?: string;
22
+ }
23
+ /** A fenced block, or a doc-comment `@example`, that compiles and maybe runs. */
24
+ export interface ExampleAttestation extends AttestationBase {
25
+ kind: 'example';
26
+ lang: string;
27
+ mode: 'check' | 'compile';
28
+ network: boolean;
29
+ code: string;
30
+ /** A `check` block with no assertion: it runs, but it is an illustration. */
31
+ weak: boolean;
32
+ /** The documented export, for doc-comment examples. */
33
+ owner?: string;
34
+ /**
35
+ * The adapter's own info-string words on the block (its `infoWords`), as written, an
36
+ * attribute as `key=value`. Absent when there are none. Only the adapter reads them.
37
+ */
38
+ tags?: string[];
39
+ }
40
+ /** A literal on the page checked against an expression over a surface. */
41
+ export interface FactAttestation extends AttestationBase {
42
+ kind: 'fact';
43
+ expression: string;
44
+ /** Surface name; `default` unless the directive says `@name`. */
45
+ surface: string;
46
+ ordered: boolean;
47
+ column?: string;
48
+ /** Absent only when the attestation carries an `error`. */
49
+ target?: FactTarget;
50
+ }
51
+ /** One row of a cases table: its line, its first cell and every cell by header. */
52
+ export interface CasesRow {
53
+ line: number;
54
+ name: string;
55
+ values: Record<string, string>;
56
+ }
57
+ /** A decision table run row by row by a setup-module runner. */
58
+ export interface CasesAttestation extends AttestationBase {
59
+ kind: 'cases';
60
+ runner: string;
61
+ header: string[];
62
+ rows: CasesRow[];
63
+ }
64
+ /** A sentence tied by name to a test that already exists; docattest does not run it. */
65
+ export interface TestAttestation extends AttestationBase {
66
+ kind: 'test';
67
+ /** The test file, relative to the project root. */
68
+ file: string;
69
+ /** The test's own title. */
70
+ title: string;
71
+ /** Titles of the enclosing describe blocks, outermost first; empty matches any. */
72
+ describes: string[];
73
+ }
74
+ /** One unit of proof found on a page. */
75
+ export type Attestation = ExampleAttestation | FactAttestation | CasesAttestation | TestAttestation;
76
+ export {};
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=attestation.js.map
@@ -0,0 +1,56 @@
1
+ /**
2
+ * What a suggestion's literal is: a list, a table column, a fenced block, an enumeration
3
+ * written inline in a sentence (its code spans), or a single value in prose.
4
+ */
5
+ export type AuditTarget = 'list' | 'column' | 'block' | 'inline' | 'scalar';
6
+ /** `match` when page and code agree, `drift` when they nearly agree. */
7
+ export type AuditStatus = 'match' | 'drift';
8
+ /** What every suggestion says, whatever its literal is. */
9
+ interface SuggestionFields {
10
+ page: string;
11
+ /**
12
+ * The first line of the list, table or block; the line an inline enumeration's sentence
13
+ * ends on; a scalar's line.
14
+ */
15
+ line: number;
16
+ /** A fact expression over the surface that the literal matches or nearly matches. */
17
+ expression: string;
18
+ status: AuditStatus;
19
+ /** In the code, not on the page. */
20
+ missing: string[];
21
+ /** On the page, not in the code. */
22
+ unexpected: string[];
23
+ /** The surface the expression reads. */
24
+ surface: string;
25
+ /**
26
+ * The directive to paste above the list, table or block, at the end of the sentence, or
27
+ * right after the scalar.
28
+ */
29
+ directive: string;
30
+ }
31
+ /** A literal on a living page that looks copied from a surface and carries no directive. */
32
+ export type Suggestion = (SuggestionFields & {
33
+ target: Exclude<AuditTarget, 'scalar'>;
34
+ }) | (SuggestionFields & {
35
+ target: 'scalar';
36
+ /**
37
+ * The value as the page writes it (a code span with its backticks): the directive goes
38
+ * right after it.
39
+ */
40
+ after: string;
41
+ });
42
+ /** One value a surface offers, with the fact expression that reads it. */
43
+ export interface InventoryEntry {
44
+ surface: string;
45
+ /** A fact expression that evaluates to this value. */
46
+ expression: string;
47
+ /** `String(value)`. */
48
+ value: string;
49
+ /** Each item, when the value is a list. */
50
+ items?: string[];
51
+ }
52
+ /** Everything `audit` found, ordered by page, then line. */
53
+ export interface AuditReport {
54
+ suggestions: Suggestion[];
55
+ }
56
+ export {};
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=audit.js.map