ambit-ts 0.1.0

package/dist/core/capability.js

@@ -0,0 +1,117 @@
+export function emptyCapabilitySet() {
+    return { capabilities: [], unknown: false };
+}
+export function unknownCapabilitySet() {
+    return { capabilities: [], unknown: true };
+}
+export function formatCapability(capability) {
+    return `${capability.resource}:${capability.action}:${capability.target}`;
+}
+const SEGMENT = /^[A-Za-z0-9_.*?[\]{}@/-]+$/;
+/**
+ * `target` names a host, a filesystem path, or a command, so it is defined by
+ * exclusion rather than by an allowlist (DESIGN.md §4.4 (b)): anything but a
+ * comma — the `@capabilities` list separator — and control characters. That
+ * admits the colon of `http:get:localhost:8080` and the spaces, `+`, `~` and
+ * `%` that real paths contain.
+ *
+ * Widening only fails closed: a mistyped tag becomes a target that matches
+ * nothing, which surfaces as a denial, never as a broader grant.
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: excluding control characters is the point.
+const TARGET_SEGMENT = /^[^,\u0000-\u001f\u007f]+$/;
+/**
+ * Parse one `<resource>:<action>:<target>` token. `undefined` when the token
+ * is not three non-empty segments — a malformed capability is rejected rather
+ * than partly honoured, on the same principle as a misspelled effect name
+ * (AMB-E002): a declaration that does not mean what it says must not be read
+ * as a narrower guarantee than the author intended.
+ *
+ * `target` may itself contain `:` (a host:port, say), so the split takes the
+ * first two separators only.
+ */
+export function parseCapability(token) {
+    const trimmed = token.trim();
+    const firstColon = trimmed.indexOf(":");
+    if (firstColon <= 0)
+        return undefined;
+    const secondColon = trimmed.indexOf(":", firstColon + 1);
+    if (secondColon <= firstColon + 1)
+        return undefined;
+    const resource = trimmed.slice(0, firstColon);
+    const action = trimmed.slice(firstColon + 1, secondColon);
+    const target = trimmed.slice(secondColon + 1);
+    if (target.length === 0)
+        return undefined;
+    if (!SEGMENT.test(resource) || !SEGMENT.test(action) || !TARGET_SEGMENT.test(target)) {
+        return undefined;
+    }
+    // A glob belongs to `target` only; a `*` elsewhere would read as a
+    // restriction while meaning the opposite.
+    if (resource.includes("*") || action.includes("*"))
+        return undefined;
+    return { resource, action, target };
+}
+/** Parse a `@capabilities` tag's comma-separated list. `undefined` if any token is malformed. */
+export function parseCapabilitiesTag(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    const capabilities = [];
+    for (const token of trimmed.split(",")) {
+        const capability = parseCapability(token);
+        if (!capability)
+            return undefined;
+        capabilities.push(capability);
+    }
+    return { capabilities, unknown: false };
+}
+/**
+ * Whether `granted` permits `required` (DESIGN.md §4.4: capabilities may only
+ * narrow from caller to callee). `resource` and `action` must match exactly;
+ * `granted.target` is matched as a glob against `required.target`.
+ */
+export function capabilityCovers(granted, required) {
+    if (granted.resource !== required.resource)
+        return false;
+    if (granted.action !== required.action)
+        return false;
+    return globMatches(granted.target, required.target);
+}
+/** Capabilities in `required` that no capability in `granted` permits. */
+export function excessCapabilities(granted, required) {
+    return required.filter((capability) => !granted.some((grant) => capabilityCovers(grant, capability)));
+}
+export function unionCapabilitySets(a, b) {
+    const merged = [...a.capabilities];
+    for (const capability of b.capabilities) {
+        if (!merged.some((existing) => capabilitiesEqual(existing, capability)))
+            merged.push(capability);
+    }
+    return { capabilities: merged, unknown: a.unknown || b.unknown };
+}
+export function capabilitiesEqual(a, b) {
+    return a.resource === b.resource && a.action === b.action && a.target === b.target;
+}
+export function capabilitySetsEqual(a, b) {
+    if (a.unknown !== b.unknown)
+        return false;
+    if (a.capabilities.length !== b.capabilities.length)
+        return false;
+    return a.capabilities.every((capability) => b.capabilities.some((other) => capabilitiesEqual(capability, other)));
+}
+/**
+ * `*` matches any run of characters, `?` exactly one — the shell-glob subset
+ * §4.4's `http:get:*.example.com` example needs. Everything else is literal,
+ * so a target containing regex metacharacters (`api.example.com`'s dots) is
+ * matched as written rather than as a pattern.
+ */
+function globMatches(pattern, value) {
+    if (pattern === value)
+        return true;
+    if (!pattern.includes("*") && !pattern.includes("?"))
+        return false;
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    const source = `^${escaped.replaceAll("*", "[\\s\\S]*").replaceAll("?", "[\\s\\S]")}$`;
+    return new RegExp(source).test(value);
+}

package/dist/core/config.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The shape of `ambit.config.ts` (DESIGN.md §4.1, "Out-of-code declarations").
+ *
+ * Types only — no loader, no filesystem, no compiler. This module is what
+ * `ambit-ts/config` exports, so a consumer's config file gets the same type
+ * checking a JSDoc contract gets from the checker, without pulling the
+ * checker (or `typescript`) into their project's type graph.
+ */
+import type { BudgetInput } from "./budget.ts";
+/**
+ * One symbol's contract, written where the code cannot be touched.
+ *
+ * The five keys are the five JSDoc contract tags (§4.1), and they mean the
+ * same thing here as there — a config declaration is not a weaker kind of
+ * declaration, it is the same declaration written somewhere else.
+ *
+ * `effects` accepts a user-defined name from {@link AmbitConfig.effects}
+ * alongside the standard ones; the loader expands it before anything else
+ * sees it (§4.1 (d)).
+ */
+export interface ConfigContract {
+    readonly effects?: readonly string[];
+    readonly capabilities?: readonly string[];
+    /** The `@budget` tag's fields, as an object rather than as tag text. */
+    readonly budget?: BudgetInput;
+    readonly entrypoint?: boolean;
+    /** `@boundary reason="…"`'s reason. §4.6 makes it mandatory, so there is no bare `true`. */
+    readonly boundary?: string;
+}
+export interface AmbitConfig {
+    /**
+     * User-defined effect names, each a combination of standard effects
+     * (DESIGN.md §4.2: "User-defined effects can be declared in
+     * `ambit.config.ts` as combinations of standard effects"). Usable from both
+     * `@effects` and {@link ConfigContract.effects}. Values are standard effect names
+     * only: a definition never expands into another definition.
+     */
+    readonly effects?: Readonly<Record<string, readonly string[]>>;
+    /**
+     * Contracts keyed by `"<file>#<symbol>"`. `<file>` is relative to this
+     * config file's directory and may use `*` and `**`; `<symbol>` is the
+     * declaration path and may not (§4.1 (a), (b)).
+     */
+    readonly contracts?: Readonly<Record<string, ConfigContract>>;
+    /**
+     * File globs — same syntax as a key's `<file>` half — whose diagnostics get
+     * the promotion `--strict` applies, and only theirs (§4.3: "`strict` can be
+     * set per directory in `ambit.config.ts`").
+     */
+    readonly strict?: readonly string[];
+}
+/**
+ * Identity. It exists for the type checking and completion a consumer gets
+ * from writing `defineConfig({ … })`, and for nothing else — so a config that
+ * exports a bare object literal is exactly as valid, which is what the
+ * in-repo fixtures rely on (they cannot resolve `ambit-ts/config` from a scratch
+ * directory).
+ */
+export declare function defineConfig(config: AmbitConfig): AmbitConfig;

package/dist/core/config.js

@@ -0,0 +1,10 @@
+/**
+ * Identity. It exists for the type checking and completion a consumer gets
+ * from writing `defineConfig({ … })`, and for nothing else — so a config that
+ * exports a bare object literal is exactly as valid, which is what the
+ * in-repo fixtures rely on (they cannot resolve `ambit-ts/config` from a scratch
+ * directory).
+ */
+export function defineConfig(config) {
+    return config;
+}

package/dist/core/diagnostic.d.ts

@@ -0,0 +1,126 @@
+import type { KnownEffect } from "./effects.ts";
+import type { SourceLocation } from "./location.ts";
+import type { SymbolId } from "./symbol-id.ts";
+export type Severity = "error" | "warning" | "info";
+export type DiagnosticCategory = "effects" | "capabilities" | "budget" | "boundary" | "types";
+/** One step of the call path from a declaring function to where an effect was found. */
+export interface ContractViaEntry {
+    readonly symbol: SymbolId;
+    readonly file: string;
+    readonly line: number;
+}
+/**
+ * Where an effect is actually performed: the operation's own call site, inside
+ * the last function of `via` (or inside the reported function itself, when
+ * `via` is empty).
+ *
+ * `via` names functions, and a function's location is its declaration — not
+ * the `fetch(...)` or `readFileSync(...)` line inside it. This field carries
+ * that line, so a reader of a diagnostic never has to open the file to find
+ * the operation the contract was broken by.
+ *
+ * `qualifiedName` is the operation as the stub tables name it (`fetch`,
+ * `node:fs.readFileSync`), in `StubCall.qualifiedName`'s module-specifier
+ * namespace.
+ */
+export interface ContractOperation {
+    readonly qualifiedName: string;
+    readonly file: string;
+    readonly line: number;
+}
+/**
+ * DESIGN.md §5.1 `contract` field, for the `effects` category.
+ *
+ * `declared` uses `"pure"` as a literal spelling for the declared empty set
+ * (matching the §5.1 example: `"declared": ["pure"]`), rather than `[]` —
+ * `EffectSet`'s internal representation collapses `pure` to an empty
+ * `effects` set (DESIGN.md §4.2 rule 2), but that internal choice should not
+ * leak into what a human or an agent reads back from the diagnostic.
+ */
+export interface EffectsContract {
+    readonly declared: readonly (KnownEffect | "pure")[];
+    readonly observed: readonly KnownEffect[];
+    readonly via: readonly ContractViaEntry[];
+    /**
+     * Absent when the operation site is not known: the effect came from a
+     * callee's `@effects` declaration with no matching operation in its body, or
+     * from a mutation, which has no operation to name. Never synthesized — an
+     * unknown site stays absent rather than falling back to the function's
+     * declaration line (DESIGN.md §5.3).
+     */
+    readonly operation?: ContractOperation;
+}
+/**
+ * DESIGN.md §5.1 `contract` field for the `capabilities` category. Same
+ * declared/observed/via shape as {@link EffectsContract}; `required` is the
+ * capability set the body actually needs, and `excess` narrows it to the ones
+ * the declaration does not grant (§4.4: capabilities may only narrow from
+ * caller to callee).
+ */
+export interface CapabilitiesContract {
+    readonly declared: readonly string[];
+    readonly required: readonly string[];
+    readonly excess: readonly string[];
+    readonly via: readonly ContractViaEntry[];
+}
+export type DiagnosticContract = EffectsContract | CapabilitiesContract;
+/**
+ * Narrow a diagnostic's `contract` to the effects shape. The union carries no
+ * discriminant field on purpose: DESIGN.md §5.1 fixes the wire shape of a
+ * `contract`, and an extra key invented for TypeScript's convenience would be
+ * a schema change nobody asked for. `category` already tells a consumer which
+ * shape to expect; this is the in-process equivalent.
+ */
+export declare function isEffectsContract(contract: DiagnosticContract): contract is EffectsContract;
+export declare function isCapabilitiesContract(contract: DiagnosticContract): contract is CapabilitiesContract;
+export interface FixEdit {
+    readonly file: string;
+    readonly range: readonly [readonly [number, number], readonly [number, number]];
+    readonly replacement: string;
+}
+export interface FixImpact {
+    readonly callersAffected?: readonly SymbolId[];
+    readonly pureCallersBroken?: number;
+}
+/**
+ * A fix candidate. `edits` must be a concrete, applicable patch — never a
+ * summary-only or elided candidate (DESIGN.md §5.3). `consistentWithContract`
+ * separates a fix that preserves the declared contract from one that widens
+ * it (§5.2).
+ */
+export interface DiagnosticFix {
+    readonly rank: number;
+    readonly kind: "widen" | "narrow";
+    readonly summary: string;
+    readonly confidence: number;
+    readonly consistentWithContract: boolean;
+    readonly edits: readonly FixEdit[];
+    readonly impact?: FixImpact;
+}
+/**
+ * The analysis backend that produced a diagnostic (DESIGN.md §3.4: "Give
+ * diagnostics, coverage, and performance records information that identifies
+ * the analysis engine and its version").
+ * Only the engine identity is captured here; the schema version and Ambit's
+ * own version that §5.2 groups alongside it are not yet defined.
+ */
+export interface DiagnosticEngine {
+    readonly name: string;
+    readonly version: string;
+}
+/**
+ * One diagnostic, matching the shape in DESIGN.md §5.1. `ambit check
+ * --format json` emits one of these per line (NDJSON).
+ */
+export interface Diagnostic {
+    readonly id: string;
+    readonly severity: Severity;
+    readonly category: DiagnosticCategory;
+    readonly message: string;
+    readonly location: SourceLocation;
+    readonly contract?: DiagnosticContract;
+    /** Empty when no concrete, applicable patch could be generated (§5.3). */
+    readonly fixes: readonly DiagnosticFix[];
+    readonly docs?: string;
+    readonly engine: DiagnosticEngine;
+}

package/dist/core/diagnostic.js

@@ -0,0 +1,13 @@
+/**
+ * Narrow a diagnostic's `contract` to the effects shape. The union carries no
+ * discriminant field on purpose: DESIGN.md §5.1 fixes the wire shape of a
+ * `contract`, and an extra key invented for TypeScript's convenience would be
+ * a schema change nobody asked for. `category` already tells a consumer which
+ * shape to expect; this is the in-process equivalent.
+ */
+export function isEffectsContract(contract) {
+    return "observed" in contract;
+}
+export function isCapabilitiesContract(contract) {
+    return "required" in contract;
+}

package/dist/core/effects.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Effects a function can have on the outside world (DESIGN.md §4.2).
+ *
+ * `pure` is not a member of this list — it is the empty {@link EffectSet}
+ * (§4.2 rule 2: "`pure` is another name for the empty set"). `unknown` is
+ * likewise not a member; it is
+ * a separate flag on {@link EffectSet}, because "this function might have
+ * more effects than listed" and "this function definitely has these
+ * effects" are different guarantees and must not collapse into one value.
+ */
+export declare const KNOWN_EFFECTS: readonly ["network", "db_read", "db_write", "fs_read", "fs_write", "state_write", "llm", "env", "process"];
+export type KnownEffect = (typeof KNOWN_EFFECTS)[number];
+export declare function isKnownEffect(value: string): value is KnownEffect;
+/**
+ * The effects a function has, plus whether the set might be incomplete.
+ *
+ * `unknown: true` means propagation reached a call that could not be
+ * resolved (DESIGN.md §4.2 rule 6) — the function's true effect set could
+ * include anything. It is tracked separately from `effects` so a diagnostic
+ * can distinguish "declares pure but definitely does X" (§AMB-E001) from
+ * "declares pure but calls something unanalyzable" (§AMB-W001).
+ */
+export interface EffectSet {
+    readonly effects: ReadonlySet<KnownEffect>;
+    readonly unknown: boolean;
+}
+export declare function emptyEffectSet(): EffectSet;
+export declare function unknownEffectSet(): EffectSet;
+export declare function effectSetOf(...effects: readonly KnownEffect[]): EffectSet;
+/**
+ * `llm` implies `network` (DESIGN.md §4.2: "`llm` ... Implies `network`"):
+ * expand a raw effect set so the containment relation always holds, no
+ * matter where the set was built.
+ */
+export declare function withImpliedEffects(set: EffectSet): EffectSet;
+export declare function unionEffectSets(a: EffectSet, b: EffectSet): EffectSet;
+export declare function effectSetsEqual(a: EffectSet, b: EffectSet): boolean;
+/** Effects present in `observed` but not covered by `declared` (§4.2 rule 1). */
+export declare function excessEffects(declared: EffectSet, observed: EffectSet): ReadonlySet<KnownEffect>;

package/dist/core/effects.js

@@ -0,0 +1,72 @@
+/**
+ * Effects a function can have on the outside world (DESIGN.md §4.2).
+ *
+ * `pure` is not a member of this list — it is the empty {@link EffectSet}
+ * (§4.2 rule 2: "`pure` is another name for the empty set"). `unknown` is
+ * likewise not a member; it is
+ * a separate flag on {@link EffectSet}, because "this function might have
+ * more effects than listed" and "this function definitely has these
+ * effects" are different guarantees and must not collapse into one value.
+ */
+export const KNOWN_EFFECTS = [
+    "network",
+    "db_read",
+    "db_write",
+    "fs_read",
+    "fs_write",
+    // Mutation of a value reachable from outside the function (DESIGN.md
+    // §4.2, "Local mutation and `pure`"). Mutating a value the function itself
+    // allocated is not this effect — it is not observable to a caller.
+    "state_write",
+    "llm",
+    "env",
+    "process",
+];
+export function isKnownEffect(value) {
+    return KNOWN_EFFECTS.includes(value);
+}
+export function emptyEffectSet() {
+    return { effects: new Set(), unknown: false };
+}
+export function unknownEffectSet() {
+    return { effects: new Set(), unknown: true };
+}
+export function effectSetOf(...effects) {
+    return withImpliedEffects({ effects: new Set(effects), unknown: false });
+}
+/**
+ * `llm` implies `network` (DESIGN.md §4.2: "`llm` ... Implies `network`"):
+ * expand a raw effect set so the containment relation always holds, no
+ * matter where the set was built.
+ */
+export function withImpliedEffects(set) {
+    if (!set.effects.has("llm") || set.effects.has("network"))
+        return set;
+    return { effects: new Set([...set.effects, "network"]), unknown: set.unknown };
+}
+export function unionEffectSets(a, b) {
+    return withImpliedEffects({
+        effects: new Set([...a.effects, ...b.effects]),
+        unknown: a.unknown || b.unknown,
+    });
+}
+export function effectSetsEqual(a, b) {
+    if (a.unknown !== b.unknown)
+        return false;
+    if (a.effects.size !== b.effects.size)
+        return false;
+    for (const effect of a.effects) {
+        if (!b.effects.has(effect))
+            return false;
+    }
+    return true;
+}
+/** Effects present in `observed` but not covered by `declared` (§4.2 rule 1). */
+export function excessEffects(declared, observed) {
+    const excess = new Set();
+    for (const effect of observed.effects) {
+        if (!declared.effects.has(effect))
+            excess.add(effect);
+    }
+    return excess;
+}

package/dist/core/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./approvals.ts";
+export * from "./authority.ts";
+export * from "./authority-diff.ts";
+export * from "./backend.ts";
+export * from "./budget.ts";
+export * from "./capability.ts";
+export * from "./config.ts";
+export * from "./diagnostic.ts";
+export * from "./effects.ts";
+export * from "./location.ts";
+export * from "./sql.ts";
+export * from "./summary.ts";
+export * from "./symbol-id.ts";

package/dist/core/index.js

@@ -0,0 +1,13 @@
+export * from "./approvals.js";
+export * from "./authority.js";
+export * from "./authority-diff.js";
+export * from "./backend.js";
+export * from "./budget.js";
+export * from "./capability.js";
+export * from "./config.js";
+export * from "./diagnostic.js";
+export * from "./effects.js";
+export * from "./location.js";
+export * from "./sql.js";
+export * from "./summary.js";
+export * from "./symbol-id.js";

package/dist/core/location.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A source position, always relative to the project root that was passed to
+ * `ambit check`. Never a compiler-internal position or snapshot offset
+ * (DESIGN.md §5.3).
+ *
+ * `line`/`col` are 1-based (human-facing position); `endLine`/`endCol` mark
+ * the end of the range, exclusive, also 1-based to match `line`/`col`.
+ */
+export interface SourceLocation {
+    readonly file: string;
+    readonly line: number;
+    readonly col: number;
+    readonly endLine: number;
+    readonly endCol: number;
+}

package/dist/core/location.js

@@ -0,0 +1 @@
+export {};

package/dist/core/sql.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The direction of one SQL statement, read from its leading keyword.
+ *
+ * Lives in `src/core/` because DESIGN.md §4.4 requires the static side
+ * (`src/stubs/data-clients.ts`, which turns the direction into `db_read` /
+ * `db_write` effects) and the runtime `pg` hook (which turns it into a
+ * `db:read:` / `db:write:` capability) to use *the same rule*. Two copies
+ * would let the checker and the running process give different answers about
+ * the same statement, which is the worst outcome available here.
+ */
+export type SqlDirection = "read" | "write" | "both";
+/**
+ * `"both"` — not a guess at the likelier direction — whenever the leading
+ * keyword is not present or not recognised. Picking `read` would let a
+ * generated `UPDATE` pass a read-only contract, which is the failure this
+ * layer exists to prevent (DESIGN.md §3.4).
+ *
+ * A template literal's static head is enough for the static side: the keyword
+ * that decides the direction is written before any substitution, or it is not
+ * statically present at all — and then the answer is `"both"`.
+ */
+export declare function sqlStatementDirection(text: string | undefined): SqlDirection;

package/dist/core/sql.js

@@ -0,0 +1,38 @@
+/** Leading SQL keywords that only read. `WITH` is deliberately absent: a CTE can wrap an `INSERT`. */
+const READ_KEYWORDS = new Set(["select", "show", "explain", "describe"]);
+const WRITE_KEYWORDS = new Set([
+    "insert",
+    "update",
+    "delete",
+    "replace",
+    "merge",
+    "upsert",
+    "create",
+    "drop",
+    "alter",
+    "truncate",
+    "grant",
+    "revoke",
+]);
+/**
+ * `"both"` — not a guess at the likelier direction — whenever the leading
+ * keyword is not present or not recognised. Picking `read` would let a
+ * generated `UPDATE` pass a read-only contract, which is the failure this
+ * layer exists to prevent (DESIGN.md §3.4).
+ *
+ * A template literal's static head is enough for the static side: the keyword
+ * that decides the direction is written before any substitution, or it is not
+ * statically present at all — and then the answer is `"both"`.
+ */
+export function sqlStatementDirection(text) {
+    if (text === undefined)
+        return "both";
+    const keyword = /^[\s(]*([a-z]+)/i.exec(text)?.[1]?.toLowerCase();
+    if (keyword === undefined)
+        return "both";
+    if (READ_KEYWORDS.has(keyword))
+        return "read";
+    if (WRITE_KEYWORDS.has(keyword))
+        return "write";
+    return "both";
+}