ambit-ts 0.1.0

package/dist/checker/diagnose.d.ts

@@ -0,0 +1,89 @@
+import type { ContractOperation, Diagnostic, DiagnosticEngine, KnownEffect, RuntimeWrapper, SymbolId, UncarriedContract } from "../core/index.ts";
+import type { PropagatedFunction } from "./propagate.ts";
+/**
+ * Compare declared vs. observed effects for every declared function and
+ * produce diagnostics (DESIGN.md §5.1). Undeclared functions
+ * (`declared.kind === "none"`) are not diagnosed here — see §4.2/§4.3:
+ * undeclared is a coverage concern, not a propagation input.
+ *
+ * `engine` identifies the backend that produced `state` (DESIGN.md §3.4) and
+ * is attached to every diagnostic emitted.
+ */
+export declare function diagnose(state: ReadonlyMap<SymbolId, PropagatedFunction>, engine: DiagnosticEngine): readonly Diagnostic[];
+/**
+ * A contract tag written on a function-like node the backend does not extract
+ * (DESIGN.md §4.1 permits `@effects` on any function or method, but only an
+ * extracted node has a `SymbolId` to hang one on). Reported rather than
+ * dropped, on the same principle as AMB-E002: a declaration that silently does
+ * nothing looks like a guarantee and is not one.
+ */
+export declare function diagnoseUncarriedContracts(uncarried: readonly UncarriedContract[], engine: DiagnosticEngine): readonly Diagnostic[];
+/**
+ * JSDoc and `ambit.config.ts` declare the same tag for one symbol and the two
+ * do not agree (DESIGN.md §4.1: "If a symbol has both JSDoc and config,
+ * JSDoc wins and the difference is warned about").
+ *
+ * A warning, not an error: JSDoc winning is the specified behaviour, so the
+ * run is doing the right thing — but a config entry that is being ignored is
+ * a declaration the author believes is in force and is not, which is the same
+ * failure AMB-E003 exists to prevent. `--strict` does not promote it: the
+ * disagreement is between two declarations, not an unverified path.
+ *
+ * No fix is offered. Which side is wrong is the author's decision — deleting
+ * the config entry and rewriting the JSDoc are opposite intentions, and §5.3
+ * forbids inventing a candidate to fill the slot.
+ */
+export declare function diagnoseContractDivergence(state: ReadonlyMap<SymbolId, PropagatedFunction>, configPath: string, engine: DiagnosticEngine): readonly Diagnostic[];
+/**
+ * An exact `contracts` key that named no extracted symbol (DESIGN.md §4.1).
+ *
+ * Same principle as AMB-E003: a declaration that silently applies to nothing
+ * reads as a guarantee and is not one. Only *exact* keys are reported — a
+ * glob covering a directory this run did not check matches nothing for a
+ * reason that is not a mistake, and reporting it would make `ambit check
+ * src/domain` noisy in proportion to how much of the project it skipped.
+ *
+ * A warning rather than an error, and not promoted by `--strict`: the key may
+ * name a file outside the directory being checked, which is a normal thing
+ * for one config to do.
+ */
+export declare function diagnoseUnmatchedConfigKeys(keys: readonly string[], configPath: string, configSource: string, engine: DiagnosticEngine): readonly Diagnostic[];
+/**
+ * DESIGN.md §4.4: a literal spec on a `withAmbit(spec, handler)` or
+ * `ambitHandler(spec, handler, decode)` naming a handler in the same file *is*
+ * that handler's `@capabilities` / `@budget` (`summarize.ts`'s
+ * `specContracts`). Writing the tag too stays legal, and this is what stops it
+ * from being free: an agent adding `db:write:users` to one of them — or
+ * widening `timeMs` in one of them — expanded authority silently.
+ *
+ * Where the spec is *not* the declaration — a list built at runtime, a budget
+ * that is not an object literal, a handler from another module — there is
+ * nothing to compare and nothing was declared by the spec either. That is
+ * `AMB-W004`, and its message says so: the handler's own JSDoc is then the
+ * only declaration there is.
+ *
+ * This compares the two **as source**, half by half: the capability set
+ * (`AMB-E010`) and the budget (`AMB-E011`) are fixed by the source
+ * independently, so one may be comparable when the other is not. §12's
+ * "Mapping contracts to handlers" — matching a contract to a handler after a
+ * build
+ * strips the comments, or after a bundler moves it — stays open, and a half
+ * this comparison cannot reach is reported (`AMB-W004`) rather than passed
+ * over.
+ */
+export declare function diagnoseRuntimeWrappers(wrappers: readonly RuntimeWrapper[], state: ReadonlyMap<SymbolId, PropagatedFunction>, engine: DiagnosticEngine): readonly Diagnostic[];
+/**
+ * The call site inside `ownerId` that performs `effect` — the `fetch(...)` line
+ * rather than the enclosing function's declaration line.
+ *
+ * Only a stub call answers: it is the layer that knows an operation's name and
+ * its effects. A `state_write` that came from an assignment or a mutating
+ * method has no operation to name, and an effect that reached `ownerId`
+ * through its own `@effects` declaration alone has no site inside it — both
+ * return `undefined` rather than a guess (DESIGN.md §5.2).
+ *
+ * The first matching site in source order is reported when a function performs
+ * the same effect more than once: one site is enough to send the reader to the
+ * right place, and picking the first is stable across re-analysis.
+ */
+export declare function operationSite(effect: KnownEffect, ownerId: SymbolId, state: ReadonlyMap<SymbolId, PropagatedFunction>): ContractOperation | undefined;