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,44 @@
1
+ /** A surface as written in the config: a bare specifier, a `./path`, or both. */
2
+ export type SurfaceEntry = string | {
3
+ import: string;
4
+ path: string;
5
+ };
6
+ /** The contents of `docattest.config.json`. */
7
+ export interface Config {
8
+ /** Globs of pages to check. */
9
+ pages: string[];
10
+ /** Globs of pages that are listed but never parsed. */
11
+ frozen?: string[] | undefined;
12
+ /** Globs of source files whose doc comments may hold examples. */
13
+ sources?: string[] | undefined;
14
+ /** Surfaces by name; `default` is required. */
15
+ surfaces: Record<string, SurfaceEntry>;
16
+ /** The setup module: case runners and named facts. */
17
+ setup?: string | undefined;
18
+ snapshots?: {
19
+ dir: string;
20
+ maxAgeDays?: number | undefined;
21
+ } | undefined;
22
+ adapter: 'typescript';
23
+ runtime?: {
24
+ timeoutMs?: number | undefined;
25
+ workers?: number | undefined;
26
+ } | undefined;
27
+ /** Info-string words added by a docs renderer (e.g. `twoslash`), accepted and ignored. */
28
+ ignoreTags?: string[] | undefined;
29
+ /** Projects below this one that `check` checks with it, each with a config of its own. */
30
+ members?: Member[] | undefined;
31
+ /**
32
+ * The programs the console blocks run, by the name a command line calls each, with globs
33
+ * of the files each is built from: `impact` lists the blocks that run one whose files changed.
34
+ */
35
+ commands?: Record<string, string[]> | undefined;
36
+ }
37
+ /**
38
+ * A member: its directory, below the project's, and perhaps the command that starts its
39
+ * adapter (program and arguments, read from the project's directory).
40
+ */
41
+ export type Member = string | {
42
+ path: string;
43
+ adapterCommand?: string[] | undefined;
44
+ };
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=config.js.map
@@ -0,0 +1,35 @@
1
+ /** The kinds of attestation a result can carry, as the protocol's `Result` schema has them. */
2
+ export declare const KINDS: readonly ["example", "fact", "cases", "snapshot", "test"];
3
+ /** What a result attests: one of {@link KINDS}. */
4
+ export type Kind = (typeof KINDS)[number];
5
+ /** The verdicts a result can carry, as the protocol's `Result` schema has them. */
6
+ export declare const STATUSES: readonly ["pass", "fail", "error", "skipped"];
7
+ /** A result's verdict: one of {@link STATUSES}. */
8
+ export type Status = (typeof STATUSES)[number];
9
+ /**
10
+ * What `check --base` can find a change did to the attestations. The core owns these; a test
11
+ * holds this list to what it reports (test/unit/api/constants.test.ts).
12
+ */
13
+ export declare const CHANGE_TYPES: readonly ["orphaned-claim", "frozen-page", "downgrade", "weakened"];
14
+ /** One of {@link CHANGE_TYPES}. */
15
+ export type ChangeType = (typeof CHANGE_TYPES)[number];
16
+ /** Subcommands of the `docattest` command line. */
17
+ export declare const COMMANDS: readonly ["check", "where", "uncovered", "index", "refresh", "skill", "audit", "inventory", "impact", "hooks", "agents", "conformance"];
18
+ /**
19
+ * The keys a `docattest.config.json` may have, in the order the core lists them. The core owns
20
+ * this list (`KEYS` in core/src/config/mod.rs) and refuses any other key; a test holds this copy
21
+ * to the keys it names when it does.
22
+ */
23
+ export declare const CONFIG_KEYS: readonly ["$schema", "pages", "frozen", "sources", "surfaces", "setup", "snapshots", "adapter", "runtime", "ignoreTags", "members", "commands"];
24
+ /**
25
+ * Time budget for one block, one fact or one table row, in milliseconds. The core owns this
26
+ * default (`DEFAULT_TIMEOUT_MS` in core/src/config/mod.rs); a test holds this value to the
27
+ * one it sends the adapter.
28
+ */
29
+ export declare const DEFAULT_TIMEOUT_MS = 10000;
30
+ /**
31
+ * Age after which a snapshot is reported as stale, in days. The core owns this default
32
+ * (`DEFAULT_SNAPSHOT_MAX_AGE_DAYS` in core/src/config/mod.rs); a test holds this value to
33
+ * the age at which it calls a snapshot old.
34
+ */
35
+ export declare const DEFAULT_SNAPSHOT_MAX_AGE_DAYS = 90;
@@ -0,0 +1,56 @@
1
+ /** The kinds of attestation a result can carry, as the protocol's `Result` schema has them. */
2
+ export const KINDS = ['example', 'fact', 'cases', 'snapshot', 'test'];
3
+ /** The verdicts a result can carry, as the protocol's `Result` schema has them. */
4
+ export const STATUSES = ['pass', 'fail', 'error', 'skipped'];
5
+ /**
6
+ * What `check --base` can find a change did to the attestations. The core owns these; a test
7
+ * holds this list to what it reports (test/unit/api/constants.test.ts).
8
+ */
9
+ export const CHANGE_TYPES = ['orphaned-claim', 'frozen-page', 'downgrade', 'weakened'];
10
+ /** Subcommands of the `docattest` command line. */
11
+ export const COMMANDS = [
12
+ 'check',
13
+ 'where',
14
+ 'uncovered',
15
+ 'index',
16
+ 'refresh',
17
+ 'skill',
18
+ 'audit',
19
+ 'inventory',
20
+ 'impact',
21
+ 'hooks',
22
+ 'agents',
23
+ 'conformance',
24
+ ];
25
+ /**
26
+ * The keys a `docattest.config.json` may have, in the order the core lists them. The core owns
27
+ * this list (`KEYS` in core/src/config/mod.rs) and refuses any other key; a test holds this copy
28
+ * to the keys it names when it does.
29
+ */
30
+ export const CONFIG_KEYS = [
31
+ '$schema',
32
+ 'pages',
33
+ 'frozen',
34
+ 'sources',
35
+ 'surfaces',
36
+ 'setup',
37
+ 'snapshots',
38
+ 'adapter',
39
+ 'runtime',
40
+ 'ignoreTags',
41
+ 'members',
42
+ 'commands',
43
+ ];
44
+ /**
45
+ * Time budget for one block, one fact or one table row, in milliseconds. The core owns this
46
+ * default (`DEFAULT_TIMEOUT_MS` in core/src/config/mod.rs); a test holds this value to the
47
+ * one it sends the adapter.
48
+ */
49
+ export const DEFAULT_TIMEOUT_MS = 10_000;
50
+ /**
51
+ * Age after which a snapshot is reported as stale, in days. The core owns this default
52
+ * (`DEFAULT_SNAPSHOT_MAX_AGE_DAYS` in core/src/config/mod.rs); a test holds this value to
53
+ * the age at which it calls a snapshot old.
54
+ */
55
+ export const DEFAULT_SNAPSHOT_MAX_AGE_DAYS = 90;
56
+ //# sourceMappingURL=constants.js.map
@@ -0,0 +1,15 @@
1
+ /**
2
+ * A problem with the project or the request, such as an invalid config or an unknown page.
3
+ * The message is complete on its own; the command line prints it without a stack.
4
+ */
5
+ export declare class UserError extends Error {
6
+ readonly name = "UserError";
7
+ constructor(message: string);
8
+ }
9
+ /** A broken invariant inside docattest: a bug to report, never the user's mistake. */
10
+ export declare class InternalError extends Error {
11
+ readonly name = "InternalError";
12
+ constructor(message: string, options?: ErrorOptions);
13
+ }
14
+ /** The message of a thrown value, whatever was thrown. */
15
+ export declare function messageOf(err: unknown): string;
@@ -0,0 +1,22 @@
1
+ /**
2
+ * A problem with the project or the request, such as an invalid config or an unknown page.
3
+ * The message is complete on its own; the command line prints it without a stack.
4
+ */
5
+ export class UserError extends Error {
6
+ name = 'UserError';
7
+ constructor(message) {
8
+ super(`docattest: ${message}`);
9
+ }
10
+ }
11
+ /** A broken invariant inside docattest: a bug to report, never the user's mistake. */
12
+ export class InternalError extends Error {
13
+ name = 'InternalError';
14
+ constructor(message, options) {
15
+ super(`docattest internal error: ${message}`, options);
16
+ }
17
+ }
18
+ /** The message of a thrown value, whatever was thrown. */
19
+ export function messageOf(err) {
20
+ return err instanceof Error ? err.message : String(err);
21
+ }
22
+ //# sourceMappingURL=errors.js.map
@@ -0,0 +1,49 @@
1
+ import type { Kind } from './constants.js';
2
+ /** What `impact` compares the working tree with. */
3
+ export interface ImpactOptions {
4
+ /** A git revision. Default: `HEAD`. */
5
+ base?: string | undefined;
6
+ /**
7
+ * The project's files at the base, path → contents: the only way to give an in-memory
8
+ * project a base (they are committed with git in its temporary directory), and only for
9
+ * one. `base` then only labels the answer.
10
+ */
11
+ baseFiles?: Record<string, string> | undefined;
12
+ }
13
+ /** One place an affected symbol appears in a living page. */
14
+ export interface ImpactReference {
15
+ symbol: string;
16
+ page: string;
17
+ line: number;
18
+ /** An attestation's kind, or `mention`: a code span that names the symbol unproven. */
19
+ kind: Kind | 'mention';
20
+ /** The sentence an attestation defends, or the sentence holding the mention. */
21
+ claim: string;
22
+ /**
23
+ * Whether an attestation docattest runs or compares proves the claim; `false` for mentions,
24
+ * and for cited tests, which docattest checks are there but never runs.
25
+ */
26
+ proven: boolean;
27
+ }
28
+ /** The prose a change touches: what `docattest impact` prints. */
29
+ export interface Impact {
30
+ /** The revision (or label) the working tree was compared with. */
31
+ base: string;
32
+ /**
33
+ * Surface exports whose declaration changed, or that reach a changed declaration through
34
+ * the code they use. Sorted.
35
+ */
36
+ symbols: string[];
37
+ /**
38
+ * Manifests that facts read with `manifest("<path>")` and the change touched, sorted; only
39
+ * when there are any. A reference to one has its call as its `symbol`.
40
+ */
41
+ manifests?: string[];
42
+ /**
43
+ * Commands built from a changed file (the config's `commands`), sorted; only when there are
44
+ * any. A reference to one, a block that runs it, has its call as its `symbol`: `$ mytool`.
45
+ */
46
+ commands?: string[];
47
+ /** By symbol, then page, then line. */
48
+ references: ImpactReference[];
49
+ }
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=impact.js.map
@@ -0,0 +1,64 @@
1
+ import type { AuditReport, InventoryEntry } from './audit.js';
2
+ import type { Impact, ImpactOptions } from './impact.js';
3
+ import type { Reference, Report } from './report.js';
4
+ /**
5
+ * Where a project's files come from, and the environment checks run in. Every operation runs
6
+ * the docattest core on the project: a project in memory is written to a temporary directory
7
+ * for the length of each operation, since the core reads projects from disk.
8
+ */
9
+ export interface ProjectInput {
10
+ /** A directory on disk. Mutually exclusive with `files`. */
11
+ root?: string | undefined;
12
+ /**
13
+ * An in-memory project: path → contents. Must include docattest.config.json. Surfaces
14
+ * given as paths are imported as `docattest-fixture` when it holds no `package.json` with
15
+ * a name.
16
+ */
17
+ files?: Record<string, string> | undefined;
18
+ /**
19
+ * Overrides for the environment the checks run in: whether `network` blocks run (else as
20
+ * `DOCATTEST_NETWORK=1` says), and the clock snapshot ages and `refresh` are measured by
21
+ * (`DOCATTEST_NOW` for the core).
22
+ */
23
+ env?: {
24
+ network?: boolean | undefined;
25
+ now?: Date | undefined;
26
+ } | undefined;
27
+ }
28
+ /** Options for one check. */
29
+ export interface CheckOptions {
30
+ /** Paths or globs, relative to the project root, of the pages to run. Default: all. */
31
+ pages?: readonly string[] | undefined;
32
+ /**
33
+ * Also judge what the project did to the attestations of a base: a git ref (read from git,
34
+ * for a project on disk), or the base project's files (for an in-memory project; they are
35
+ * committed with git in its temporary directory). Adds `changes` to the report.
36
+ */
37
+ base?: string | {
38
+ files: Record<string, string>;
39
+ } | undefined;
40
+ }
41
+ /** A project: its pages, its surfaces and the operations over them. */
42
+ export interface Project {
43
+ /** Run attestations and report. Coverage always describes the whole project. */
44
+ check(options?: CheckOptions): Promise<Report>;
45
+ /** Pages, lines and claims that attest a symbol. Parsing only. */
46
+ where(symbol: string): Promise<Reference[]>;
47
+ /** Exports of a surface that no attestation against it references. */
48
+ uncovered(surface?: string): Promise<string[]>;
49
+ /** The whole symbol → references map. Parsing only. */
50
+ index(): Promise<Record<string, Reference[]>>;
51
+ /** The exports a change since `base` affects, and the prose that names them. Reads only. */
52
+ impact(options?: ImpactOptions): Promise<Impact>;
53
+ /**
54
+ * Refetch snapshots from their source over HTTP and rewrite them; returns the names
55
+ * refreshed. The core does the fetching: there is no fetcher to pass.
56
+ */
57
+ refresh(name?: string): Promise<string[]>;
58
+ /** Literals on living pages that look copied from a surface and carry no directive. */
59
+ audit(): Promise<AuditReport>;
60
+ /** The values a fact could read, optionally only those containing `search`. */
61
+ inventory(search?: string): Promise<InventoryEntry[]>;
62
+ /** Files the project has written. Empty after any number of checks. */
63
+ writes(): string[];
64
+ }
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=project.js.map
@@ -0,0 +1,107 @@
1
+ import type { ChangeType, Kind, Status } from './constants.js';
2
+ /** The verdict on one attestation (or one row of a cases table). */
3
+ export interface Result {
4
+ page: string;
5
+ line: number;
6
+ kind: Kind;
7
+ status: Status;
8
+ /** Surface symbols the attestation exercises. */
9
+ symbols: string[];
10
+ /** The page's side of a comparison, when there was one. */
11
+ expected?: string;
12
+ /** The code's side of a comparison, when there was one. */
13
+ actual?: string;
14
+ message: string;
15
+ }
16
+ /** Page coverage: which living pages carry attestations. */
17
+ export interface Coverage {
18
+ living: number;
19
+ covered: number;
20
+ uncovered: string[];
21
+ frozen: string[];
22
+ attestations: number;
23
+ /** `check` examples that assert nothing. */
24
+ weak: number;
25
+ /** Well-formed `test` citations: sentences tied to a test that docattest does not run. */
26
+ cited: number;
27
+ }
28
+ /** Where a surface resolved: the file examples and facts actually ran against. */
29
+ export interface SurfaceResolution {
30
+ /** The specifier examples and facts import. */
31
+ import: string;
32
+ /** The entry file, relative to the project root when it lies inside it. */
33
+ entry: string;
34
+ /**
35
+ * The package the entry file belongs to. `display` is how the language writes a package
36
+ * and its version (`name@1.2.0` here); the text report prints it as given.
37
+ */
38
+ package?: {
39
+ name: string;
40
+ version?: string;
41
+ display: string;
42
+ };
43
+ }
44
+ /** One surface in the report: symbol coverage and resolution. */
45
+ export interface SurfaceCoverage {
46
+ symbols: number;
47
+ attested: number;
48
+ /** Exported names no attestation against this surface references. */
49
+ unattested: string[];
50
+ /** Absent when the surface could not be resolved. */
51
+ resolution?: SurfaceResolution;
52
+ /** Problems worth a look that never change the exit code. */
53
+ warnings: string[];
54
+ }
55
+ /** The age of one snapshot. */
56
+ export interface SnapshotStatus {
57
+ name: string;
58
+ source: string;
59
+ fetchedAt: string;
60
+ ageDays: number;
61
+ /** Older than `snapshots.maxAgeDays`. */
62
+ warning: boolean;
63
+ }
64
+ /** Everything `check` found. The command line prints it, or with `--json`, this object. */
65
+ export interface Report {
66
+ /** Ordered by page, then line. */
67
+ results: Result[];
68
+ coverage: Coverage;
69
+ /** Keyed by surface name. */
70
+ surfaces: Record<string, SurfaceCoverage>;
71
+ snapshots: SnapshotStatus[];
72
+ /**
73
+ * 1 when any result is `fail` or `error`, any change is a `fail`, or any member's report
74
+ * has exit code 1.
75
+ */
76
+ exitCode: 0 | 1;
77
+ /** What the working tree did to the attestations of the base. Only with `base`. */
78
+ changes?: Change[];
79
+ /** The reports of the projects the config lists as `members`. Only when it lists any. */
80
+ members?: MemberReport[];
81
+ }
82
+ /** The report of a member project. */
83
+ export interface MemberReport {
84
+ /** Its directory, from the project that lists it. */
85
+ path: string;
86
+ /** The adapter its config names. */
87
+ adapter: string;
88
+ report: Report;
89
+ }
90
+ /** One thing a change did to the attestations that existed at the base. */
91
+ export interface Change {
92
+ type: ChangeType;
93
+ /** The page as it is now. */
94
+ page: string;
95
+ /** The line now: the claim's, the block's or the fact's; 1 for a whole page. */
96
+ line: number;
97
+ /** `fail` sets exit code 1; a `warning` never changes it. */
98
+ severity: 'fail' | 'warning';
99
+ message: string;
100
+ }
101
+ /** One place a symbol is attested, with the sentence the proof defends. */
102
+ export interface Reference {
103
+ page: string;
104
+ line: number;
105
+ kind: Kind;
106
+ claim: string;
107
+ }
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=report.js.map
@@ -0,0 +1,17 @@
1
+ import type { AuditReport, InventoryEntry } from '../api/audit.js';
2
+ import type { Impact } from '../api/impact.js';
3
+ import type { Reference, Report } from '../api/report.js';
4
+ /** `check --json`: a report with its results, coverage and exit code. */
5
+ export declare const asReport: (value: unknown) => Report;
6
+ /** `index --json`: references by symbol. */
7
+ export declare const asIndex: (value: unknown) => Record<string, Reference[]>;
8
+ /** `where --json`: the references to one symbol. */
9
+ export declare const asReferences: (value: unknown) => Reference[];
10
+ /** `uncovered --json`: the names no page attests. */
11
+ export declare const asNames: (value: unknown) => string[];
12
+ /** `audit --json`: the suggestions. */
13
+ export declare const asAudit: (value: unknown) => AuditReport;
14
+ /** `inventory --json`: the surface values. */
15
+ export declare const asInventory: (value: unknown) => InventoryEntry[];
16
+ /** `impact --json`: the symbols a change affects and the prose that names them. */
17
+ export declare const asImpact: (value: unknown) => Impact;
@@ -0,0 +1,23 @@
1
+ import { InternalError } from '../api/errors.js';
2
+ import { isObject, isStringArray } from '../json.js';
3
+ /** `check --json`: a report with its results, coverage and exit code. */
4
+ export const asReport = (value) => fits(value, 'check', (v) => isObject(v) && Array.isArray(v.results) && isObject(v.coverage));
5
+ /** `index --json`: references by symbol. */
6
+ export const asIndex = (value) => fits(value, 'index', (v) => isObject(v) && Object.values(v).every(Array.isArray));
7
+ /** `where --json`: the references to one symbol. */
8
+ export const asReferences = (value) => fits(value, 'where', Array.isArray);
9
+ /** `uncovered --json`: the names no page attests. */
10
+ export const asNames = (value) => fits(value, 'uncovered', isStringArray);
11
+ /** `audit --json`: the suggestions. */
12
+ export const asAudit = (value) => fits(value, 'audit', (v) => isObject(v) && Array.isArray(v.suggestions));
13
+ /** `inventory --json`: the surface values. */
14
+ export const asInventory = (value) => fits(value, 'inventory', Array.isArray);
15
+ /** `impact --json`: the symbols a change affects and the prose that names them. */
16
+ export const asImpact = (value) => fits(value, 'impact', (v) => isObject(v) && isStringArray(v.symbols) && Array.isArray(v.references));
17
+ function fits(value, command, shape) {
18
+ if (!shape(value)) {
19
+ throw new InternalError(`the docattest core's ${command} answer is not of the shape this package reads`);
20
+ }
21
+ return value;
22
+ }
23
+ //# sourceMappingURL=answers.js.map
@@ -0,0 +1,18 @@
1
+ /** What one run of the core printed, and how it ended. */
2
+ export interface CoreRun {
3
+ code: number | null;
4
+ signal: NodeJS.Signals | null;
5
+ stdout: string;
6
+ stderr: string;
7
+ }
8
+ /** The core this package runs. */
9
+ export declare function core(): string;
10
+ /** Run the core `program` with `args` in `cwd`; `env` is added to this process's environment. */
11
+ export declare function runCore(program: string, args: readonly string[], cwd: string, env: Record<string, string>): Promise<CoreRun>;
12
+ /**
13
+ * The error a run that did not answer stands for: the core's own user error (exit code 1,
14
+ * a message that begins `docattest: `), else a bug.
15
+ */
16
+ export declare function failure(run: CoreRun): Error;
17
+ /** The JSON a run printed, when it ended with one of `codes`; else its failure. */
18
+ export declare function answer(run: CoreRun, codes?: readonly number[]): unknown;
@@ -0,0 +1,58 @@
1
+ // Running the docattest core for the programmatic API: the core this package's launcher
2
+ // would run (PROTOCOL.md §1, "Launchers"), told the same things, with its output collected.
3
+ import { spawn } from 'node:child_process';
4
+ import { InternalError, UserError } from '../api/errors.js';
5
+ import { coreEnvironment, packageCore } from '../core-binary/package.js';
6
+ /** The core this package runs. */
7
+ export function core() {
8
+ const result = packageCore();
9
+ if ('error' in result)
10
+ throw new UserError(result.error.replace(/^docattest: /, ''));
11
+ return result.core;
12
+ }
13
+ /** Run the core `program` with `args` in `cwd`; `env` is added to this process's environment. */
14
+ export function runCore(program, args, cwd, env) {
15
+ return new Promise((resolve, reject) => {
16
+ const child = spawn(program, args, {
17
+ cwd,
18
+ env: coreEnvironment({ ...process.env, ...env }),
19
+ stdio: ['ignore', 'pipe', 'pipe'],
20
+ });
21
+ const out = [];
22
+ const err = [];
23
+ child.stdout.on('data', (chunk) => out.push(chunk));
24
+ child.stderr.on('data', (chunk) => err.push(chunk));
25
+ child.on('error', (error) => {
26
+ reject(new UserError(`cannot run the core (${program}): ${error.message}`));
27
+ });
28
+ child.on('close', (code, signal) => {
29
+ const text = (chunks) => Buffer.concat(chunks).toString('utf8');
30
+ resolve({ code, signal, stdout: text(out), stderr: text(err) });
31
+ });
32
+ });
33
+ }
34
+ /**
35
+ * The error a run that did not answer stands for: the core's own user error (exit code 1,
36
+ * a message that begins `docattest: `), else a bug.
37
+ */
38
+ export function failure(run) {
39
+ const message = run.stderr.trimEnd();
40
+ if (run.code === 1 && message.startsWith('docattest: ')) {
41
+ return new UserError(message.slice('docattest: '.length));
42
+ }
43
+ const ended = run.signal ? `was killed by ${run.signal}` : `exited with code ${run.code}`;
44
+ return new InternalError(`the docattest core ${ended}: ${message}`);
45
+ }
46
+ /** The JSON a run printed, when it ended with one of `codes`; else its failure. */
47
+ export function answer(run, codes = [0]) {
48
+ if (run.code !== null && codes.includes(run.code) && run.stdout.trim() !== '') {
49
+ try {
50
+ return JSON.parse(run.stdout);
51
+ }
52
+ catch {
53
+ // Not an answer: reported below as what the core said.
54
+ }
55
+ }
56
+ throw failure(run);
57
+ }
58
+ //# sourceMappingURL=core.js.map
@@ -0,0 +1,14 @@
1
+ import type { ProjectInput } from '../api/project.js';
2
+ import { type Workspace } from './workspace.js';
3
+ export type { Workspace };
4
+ /** A project's place. */
5
+ export interface Place {
6
+ /** Whether the project is in memory. */
7
+ memory: boolean;
8
+ /** Run `use` with the project on disk; `base`, files to commit first (memory only). */
9
+ run<T>(base: Record<string, string> | undefined, use: (at: Workspace) => Promise<T>): Promise<T>;
10
+ /** Keep a file an operation wrote. */
11
+ keep(file: string, text: string | undefined): void;
12
+ }
13
+ /** The place of the project `input` describes. */
14
+ export declare function placeOf(input: ProjectInput): Place;
@@ -0,0 +1,37 @@
1
+ // Where a project's operations run. A project on disk is used where it is; an in-memory one
2
+ // is written to a temporary directory for each operation and removed afterwards, and what
3
+ // `refresh` writes there is kept in memory for the next.
4
+ import * as path from 'node:path';
5
+ import { UserError } from '../api/errors.js';
6
+ import { inWorkspace } from './workspace.js';
7
+ /** The place of the project `input` describes. */
8
+ export function placeOf(input) {
9
+ const given = (input.root === undefined ? 0 : 1) + (input.files === undefined ? 0 : 1);
10
+ if (given !== 1)
11
+ throw new UserError('createProject needs exactly one of `root` or `files`');
12
+ if (input.files === undefined)
13
+ return onDisk(path.resolve(input.root ?? '.'));
14
+ const files = { ...input.files };
15
+ return {
16
+ memory: true,
17
+ run: (base, use) => inWorkspace(files, base, use),
18
+ keep: (file, text) => {
19
+ if (text !== undefined)
20
+ files[file] = text;
21
+ },
22
+ };
23
+ }
24
+ function onDisk(root) {
25
+ return {
26
+ memory: false,
27
+ run: (base, use) => {
28
+ if (base !== undefined) {
29
+ throw new UserError('a base given as files needs an in-memory project (`files`); a project on disk ' +
30
+ 'compares with a git ref');
31
+ }
32
+ return use({ root, read: () => undefined });
33
+ },
34
+ keep: () => undefined,
35
+ };
36
+ }
37
+ //# sourceMappingURL=place.js.map
@@ -0,0 +1,3 @@
1
+ import type { Project, ProjectInput } from '../api/project.js';
2
+ /** A project from a directory or an in-memory map of files. */
3
+ export declare function createProject(input: ProjectInput): Project;