ambit-ts 0.1.0

package/dist/stubs/http-capabilities.js

@@ -0,0 +1,70 @@
+const HTTP_CAPABILITY_RULES = new Map([
+    ["fetch", { urlArgument: 0, optionsArgument: 1, defaultAction: "get" }],
+    ["globalThis.fetch", { urlArgument: 0, optionsArgument: 1, defaultAction: "get" }],
+    ["undici.fetch", { urlArgument: 0, optionsArgument: 1, defaultAction: "get" }],
+    ["node:http.get", { urlArgument: 0, defaultAction: "get" }],
+    ["node:https.get", { urlArgument: 0, defaultAction: "get" }],
+    ["node:http.request", { urlArgument: 0, optionsArgument: 1, defaultAction: "get" }],
+    ["node:https.request", { urlArgument: 0, optionsArgument: 1, defaultAction: "get" }],
+]);
+/**
+ * The capability requirement of one call, or `undefined` when this table knows
+ * of no target for it — which is not the same as "requires nothing": every
+ * other operation simply has no rule here yet (`node:fs`, DB clients, LLM
+ * SDKs), and §4.4's caveat forbids inferring one for a DB client from a SQL
+ * string.
+ */
+export function lookupHttpCapability(qualifiedName, literalArguments) {
+    const rule = HTTP_CAPABILITY_RULES.get(qualifiedName);
+    if (!rule)
+        return undefined;
+    const host = hostOf(literalArguments?.[rule.urlArgument]);
+    if (host === undefined)
+        return { targetUnknown: true };
+    const options = rule.optionsArgument === undefined ? undefined : literalArguments?.[rule.optionsArgument];
+    const method = options?.properties?.get("method");
+    return {
+        capability: {
+            resource: "http",
+            action: (method ?? rule.defaultAction).toLowerCase(),
+            target: host,
+        },
+    };
+}
+/**
+ * The host a URL argument fixes, or `undefined` when the source does not fix
+ * one.
+ *
+ * A template literal's static head is enough *only if the authority ends
+ * inside it*: `` `https://api.example.com/rates/${c}` `` fixes
+ * `api.example.com`, while `` `https://api.${env}.example.com/` `` fixes
+ * nothing and must not be read as `api.` — a prefix match would be a target
+ * the author never granted.
+ *
+ * The host is taken as written (minus userinfo), port included: §4.4's own
+ * example spells a target `http:get:localhost:8080`, and inventing or dropping
+ * a default port would make a grant and a requirement disagree over text
+ * neither one wrote.
+ */
+function hostOf(argument) {
+    const text = argument?.text;
+    if (text === undefined)
+        return undefined;
+    const schemeEnd = text.indexOf("://");
+    // A relative URL ("/v1/rates") names no host; the host comes from wherever
+    // the request is sent, which is not in this call.
+    if (schemeEnd < 0)
+        return undefined;
+    const rest = text.slice(schemeEnd + 3);
+    const terminator = rest.search(/[/?#]/);
+    if (terminator < 0) {
+        // The authority runs to the end of the text we have. Only a complete
+        // literal proves nothing more follows.
+        return argument?.complete === true ? normalizeAuthority(rest) : undefined;
+    }
+    return normalizeAuthority(rest.slice(0, terminator));
+}
+function normalizeAuthority(authority) {
+    const afterUserInfo = authority.slice(authority.lastIndexOf("@") + 1);
+    return afterUserInfo.length === 0 ? undefined : afterUserInfo.toLowerCase();
+}

package/dist/stubs/mutating-builtins.d.ts

@@ -0,0 +1 @@
+export declare function isMutatingBuiltin(qualifiedName: string): boolean;

package/dist/stubs/mutating-builtins.js

@@ -0,0 +1,48 @@
+/**
+ * Allowlist of default-lib (builtin) methods that change their receiver in
+ * place. Keyed the same way as `src/stubs/pure-builtins.ts` — `checker.
+ * getFullyQualifiedName()`'s format (e.g. `"Array.push"`, `"Map.set"`) — and
+ * kept in a separate table from it because the two answer different
+ * questions: that one says "no `KnownEffect` at all", this one says "a
+ * `state_write` if the receiver is reachable from outside the function"
+ * (DESIGN.md §4.2, "Local mutation and `pure`").
+ *
+ * Whether a listed call actually produces `state_write` is decided per call
+ * site by the receiver's locality, not by this table: mutating a value the
+ * function itself allocated is not observable outside it, so it carries no
+ * effect. The locality rule lives in `src/checker/backend/legacy-ts.ts`
+ * (`isLocallyOwnedMutationTarget`).
+ *
+ * Admission rule, same as `pure-builtins.ts`: names that `ambit check
+ * --coverage`'s `top-unresolved-names` actually surfaced, plus the in-place
+ * siblings on the same builtin type — a table that listed `push` but not
+ * `pop` would mislead the next reader. When unsure, leave a name out; it
+ * falls back to `unknown`, which over-approximates rather than under-.
+ */
+const MUTATING_BUILTINS = new Set([
+    // Surfaced by `check src --coverage` on 2026-09-09: Array.push=50,
+    // Map.set=13, Set.add=6 — together 69 of the 131 `builtin-method`
+    // unresolved calls, which is what made this table worth having.
+    "Array.push",
+    "Array.pop",
+    "Array.shift",
+    "Array.unshift",
+    "Array.splice",
+    "Array.sort",
+    "Array.reverse",
+    "Array.fill",
+    "Array.copyWithin",
+    "Map.set",
+    "Map.delete",
+    "Map.clear",
+    "Set.add",
+    "Set.delete",
+    "Set.clear",
+    "WeakMap.set",
+    "WeakMap.delete",
+    "WeakSet.add",
+    "WeakSet.delete",
+]);
+export function isMutatingBuiltin(qualifiedName) {
+    return MUTATING_BUILTINS.has(qualifiedName);
+}

package/dist/stubs/node-builtins.d.ts

@@ -0,0 +1,2 @@
+import type { KnownEffect } from "../core/index.ts";
+export declare function lookupStubEffect(qualifiedName: string): KnownEffect | undefined;

package/dist/stubs/node-builtins.js

@@ -0,0 +1,77 @@
+/**
+ * Minimal effect table for common globals, Node.js builtins, and a handful
+ * of widely-used third-party packages (DESIGN.md §4.2, "Evidence for effect
+ * detection", lists both as legitimate sources — the same table, not a
+ * separate one).
+ * Matching is purely textual against the connector layer's best-effort
+ * `calleeQualifiedName` (see `src/core/backend.ts`) — a call written as
+ * `import * as f from "node:fs"; f.readFileSync(...)`, `import f from
+ * "node:fs"; f.readFileSync(...)`, or `import { readFileSync } from
+ * "node:fs"; readFileSync(...)` are all recognized: the connector layer
+ * reports the qualified name from the *module specifier text* (`"node:fs"`)
+ * plus the imported property/export name, not the local binding name, so a
+ * local `as` alias doesn't affect matching. This is still a known
+ * simplification for this slice: a destructured or re-exported binding
+ * several hops away (e.g. through a barrel file) is not resolved to its
+ * originating module specifier.
+ *
+ * `docs/diagnostics/` and DESIGN.md §8 track stub trust levels; this table
+ * is bundled with Ambit itself, the highest trust level.
+ */
+const STUB_EFFECTS = new Map([
+    ["fetch", "network"],
+    ["globalThis.fetch", "network"],
+    ["undici.fetch", "network"],
+    ["node:http.request", "network"],
+    ["node:http.get", "network"],
+    ["node:https.request", "network"],
+    ["node:https.get", "network"],
+    ["node:net.connect", "network"],
+    ["node:net.createConnection", "network"],
+    ["node:fs.readFile", "fs_read"],
+    ["node:fs.readdir", "fs_read"],
+    ["node:fs.readdirSync", "fs_read"],
+    ["node:fs.realpath", "fs_read"],
+    ["node:fs.realpathSync", "fs_read"],
+    ["node:fs.stat", "fs_read"],
+    ["node:fs.lstat", "fs_read"],
+    ["node:fs.lstatSync", "fs_read"],
+    ["node:fs.access", "fs_read"],
+    ["node:fs.accessSync", "fs_read"],
+    ["node:fs.readFileSync", "fs_read"],
+    ["node:fs.existsSync", "fs_read"],
+    ["node:fs.statSync", "fs_read"],
+    ["node:fs.writeFile", "fs_write"],
+    ["node:fs.writeFileSync", "fs_write"],
+    ["node:fs.appendFile", "fs_write"],
+    ["node:fs.appendFileSync", "fs_write"],
+    ["node:fs.mkdir", "fs_write"],
+    ["node:fs.mkdirSync", "fs_write"],
+    ["node:fs.mkdtemp", "fs_write"],
+    ["node:fs.mkdtempSync", "fs_write"],
+    ["node:fs.rm", "fs_write"],
+    ["node:fs.rmSync", "fs_write"],
+    ["node:fs.unlink", "fs_write"],
+    ["node:fs.unlinkSync", "fs_write"],
+    ["node:fs/promises.readFile", "fs_read"],
+    ["node:fs/promises.readdir", "fs_read"],
+    ["node:fs/promises.realpath", "fs_read"],
+    ["node:fs/promises.stat", "fs_read"],
+    ["node:fs/promises.lstat", "fs_read"],
+    ["node:fs/promises.access", "fs_read"],
+    ["node:fs/promises.writeFile", "fs_write"],
+    ["node:fs/promises.appendFile", "fs_write"],
+    ["node:fs/promises.mkdir", "fs_write"],
+    ["node:fs/promises.mkdtemp", "fs_write"],
+    ["node:fs/promises.rm", "fs_write"],
+    ["node:fs/promises.unlink", "fs_write"],
+    ["node:child_process.exec", "process"],
+    ["node:child_process.execSync", "process"],
+    ["node:child_process.execFile", "process"],
+    ["node:child_process.spawn", "process"],
+    ["node:child_process.spawnSync", "process"],
+    ["node:child_process.fork", "process"],
+]);
+export function lookupStubEffect(qualifiedName) {
+    return STUB_EFFECTS.get(qualifiedName);
+}

package/dist/stubs/pure-builtins.d.ts

@@ -0,0 +1 @@
+export declare function isKnownPureBuiltin(qualifiedName: string): boolean;

package/dist/stubs/pure-builtins.js

@@ -0,0 +1,89 @@
+/**
+ * Allowlist of default-lib (builtin) methods known to perform none of
+ * Ambit's `KnownEffect`s — no network, filesystem, process, database, LLM,
+ * or env access — regardless of arguments. Keyed by `checker.
+ * getFullyQualifiedName()`'s format (e.g. `"Set.has"`, `"Array.map"`), a
+ * different namespace from `src/stubs/node-builtins.ts`'s module-specifier
+ * keys (e.g. `"node:fs.readFileSync"`) — the two tables are never merged or
+ * compared (`src/core/backend.ts`'s `CallSite.pureBuiltinName` doc comment).
+ * In-place mutation is a separate table, `src/stubs/mutating-builtins.ts`
+ * (DESIGN.md §4.2, "Local mutation and `pure`"): a mutator's effect depends on
+ * its receiver, so it cannot be answered by a name alone the way this table
+ * answers. Nondeterminism beyond `env` is still outside the model; this
+ * allowlist claims only "no `KnownEffect`", not "pure" in a stricter sense.
+ *
+ * This exists because `qualifiedNameOf` (`src/checker/backend/legacy-ts.ts`)
+ * cannot produce a textual name for a builtin method reached through a local
+ * value (`set.has(...)`, `arr.map(...)`) — there is no import binding to read
+ * a module specifier from. `checker.getFullyQualifiedName()` still resolves
+ * a stable name from the symbol itself, so those calls are named, but a
+ * *name* is not a *pure* verdict: only entries listed here are trusted.
+ *
+ * A method that can take a callback (`map`, `forEach`, `filter`, `some`,
+ * ...) may still list a symbol reached by reference (`arr.forEach(handler)`)
+ * — the connector layer marks that call `callbackByReference` and
+ * `summarize.ts`'s `toCall` refuses to treat it as pure even if the method
+ * name is listed here, because an opaque callback might do anything
+ * (DESIGN.md §4.2 rule 4: a higher-order call's callback effects must be
+ * inferred from the actual argument, never treated as complete from the
+ * type signature alone).
+ *
+ * Populated from what `ambit check --coverage`'s `top-unresolved-names`
+ * actually surfaces on real code, not written ahead of evidence. When
+ * unsure, leave a name out — it just falls back to `unknown`, which is safe.
+ */
+const PURE_BUILTINS = new Set([
+    // Confirmed against `ambit check --coverage`'s top-unresolved-names on
+    // Ambit's own source (2026-09-08). Mutating names — `Array.push`,
+    // `Array.sort` (in-place), `Map.set`, `Set.add` — belong to
+    // `mutating-builtins.ts` instead; a "pure" table that listed mutators
+    // would mislead the next reader.
+    "Set.has",
+    "Map.get",
+    "Map.has",
+    "Map.entries",
+    "ReadonlyMap.get",
+    "ReadonlyMap.has",
+    "ReadonlyMap.values",
+    "ReadonlyMap.entries",
+    "ReadonlySet.has",
+    "Array.map",
+    "Array.filter",
+    "Array.join",
+    "Array.slice",
+    "Array.reduce",
+    "ReadonlyArray.map",
+    "ReadonlyArray.filter",
+    "ReadonlyArray.some",
+    "ReadonlyArray.includes",
+    "ReadonlyArray.join",
+    "ReadonlyArray.find",
+    "String.trim",
+    "String.split",
+    // Surfaced at 8 occurrences by `check src --coverage` on 2026-09-09, which is
+    // this table's own admission rule. Non-mutating, and the exact twin of
+    // `Array.slice` above; listing one without the other was an accident of what
+    // an earlier measurement happened to show.
+    "String.slice",
+    "String.includes",
+    "String.startsWith",
+    "String.localeCompare",
+    "ObjectConstructor.fromEntries",
+    "JSON.stringify",
+    "Math.round",
+    "Number.toFixed",
+    // Surfaced by `check test/fixtures/realistic-api --coverage` on 2026-09-09,
+    // the same admission rule. Each is the exact twin of an entry already here —
+    // `ReadonlyArray.filter` of `Array.filter`, `ReadonlyArray.every` of
+    // `ReadonlyArray.some`, `Math.max` of `Math.round` — or a non-mutating
+    // `String` method beside `String.slice`. Listing one of a pair without the
+    // other was an accident of what an earlier measurement happened to show.
+    "ReadonlyArray.filter",
+    "ReadonlyArray.every",
+    "Math.max",
+    "String.toLowerCase",
+    "String.toUpperCase",
+]);
+export function isKnownPureBuiltin(qualifiedName) {
+    return PURE_BUILTINS.has(qualifiedName);
+}