@jitsusama/agentic-harness.core 0.1.0

package/dist/review/backed.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Whether a provider's declarations are backed by methods that exist.
+ *
+ * The fault this answers came from the Meteorite provider, which claimed four
+ * things it had never implemented: `proposals: { fetchAsRef: true, checks:
+ * true, list: true }` and later `authoring.proposeStack`. Nothing crashed,
+ * which is why it survived for weeks. The engine reaches those methods through
+ * `?.`, so `review_see checks` answered "the provider reports no checks for
+ * this target" and read like a backend without CI rather than a provider with
+ * a hole in it, while a consumer that asked the capabilities first was told
+ * yes.
+ *
+ * It began as a test, and as a test it could only ever reach the providers
+ * this package ships. Every provider that matters arrives over the event bus
+ * from another package: a build-time check cannot import one, so the private
+ * copy of this question was a hand-copied table, free to fall behind the
+ * contract it was checking against without anything noticing. Two copies of a
+ * rule is one rule and one guess about it.
+ *
+ * So the question lives here, in the library both sides already depend on, and
+ * `registerReviewProvider` asks it of every provider that passes through.
+ * Registration is the one seam every provider crosses however it got here,
+ * which makes it the only place this can be asked of all of them.
+ */
+import type { RepoLocator } from "./change.js";
+import type { ReviewProvider } from "./provider.js";
+/** Which facets carry capabilities that promise a method. */
+type FacetName = "proposals" | "conversation" | "authoring";
+/**
+ * Which method has to exist for each capability that promises one.
+ *
+ * Only capabilities promising a callable belong here. One describing
+ * behaviour, like `staleness: "pinned"` or `maxBatchComments`, is a fact about
+ * the backend rather than a promise about this object.
+ *
+ * This table was checked against the contract rather than assembled from
+ * memory: every capability whose name matches a facet method is in it. Three
+ * optional methods have no capability of any kind, which is the opposite gap
+ * and a milder one: `unreact` and `fileAt` can only be discovered by looking
+ * for the method, so a consumer cannot ask ahead of time and has to degrade on
+ * absence instead. Nothing lies; it just cannot be asked. `commentOn` used to
+ * be the third, and is now spoken for by `fileLevelComments`.
+ *
+ * A row carries a predicate over the declared value rather than assuming
+ * `true`, because several capabilities say more than a boolean can and leaving
+ * them out left the worst hole here uncovered. `reviewersAt` is the one
+ * declaration a caller is told about in the past tense: `review_offer` reports
+ * "asked alice, bob" from an optional call that quietly does nothing when the
+ * method is missing. What each promises is narrower than its type.
+ *
+ * A row also says whether the contract requires the method, because the two
+ * directions are not symmetric. Where a method is mandatory its presence is
+ * guaranteed by the type and proves nothing about what the provider means, so
+ * demanding a declaration to match it would push a provider that legitimately
+ * cannot propose into saying it can.
+ */
+export declare const BACKED_BY: ReadonlyArray<{
+    facet: FacetName;
+    capability: string;
+    method: string;
+    /** When the declared value amounts to a promise. Defaults to `=== true`. */
+    promises?: (declared: unknown) => boolean;
+    /** The facet requires this method, so its presence says nothing. */
+    mandatory?: true;
+}>;
+/** One way a provider's declarations and its methods disagree. */
+export interface Unbacked {
+    facet: FacetName;
+    capability: string;
+    method: string;
+    /** Which direction the disagreement runs. */
+    fault: "declared-without-method" | "method-without-declaration";
+    /** Said in full, for a warning a person has to act on. */
+    reason: string;
+}
+/**
+ * Compare what a provider says it can do against what it can do.
+ *
+ * Both directions are reported, because each is its own kind of wrong. A
+ * declaration with no method behind it is a lie a consumer acts on; a method
+ * with no declaration is work already done that no consumer will ever ask for,
+ * which is how Meteorite's `requestReviewers` sat unreachable while the
+ * provider said reviewers could only be named at creation.
+ *
+ * Takes the locator because a provider is entitled to answer differently for
+ * different repos, and a provider handed a key from the wrong space would
+ * return a default and let every row pass having compared nothing.
+ */
+export declare function unbackedDeclarations(provider: ReviewProvider, repo: RepoLocator): Unbacked[];
+export {};

package/dist/review/backed.js

@@ -0,0 +1,168 @@
+/**
+ * Whether a provider's declarations are backed by methods that exist.
+ *
+ * The fault this answers came from the Meteorite provider, which claimed four
+ * things it had never implemented: `proposals: { fetchAsRef: true, checks:
+ * true, list: true }` and later `authoring.proposeStack`. Nothing crashed,
+ * which is why it survived for weeks. The engine reaches those methods through
+ * `?.`, so `review_see checks` answered "the provider reports no checks for
+ * this target" and read like a backend without CI rather than a provider with
+ * a hole in it, while a consumer that asked the capabilities first was told
+ * yes.
+ *
+ * It began as a test, and as a test it could only ever reach the providers
+ * this package ships. Every provider that matters arrives over the event bus
+ * from another package: a build-time check cannot import one, so the private
+ * copy of this question was a hand-copied table, free to fall behind the
+ * contract it was checking against without anything noticing. Two copies of a
+ * rule is one rule and one guess about it.
+ *
+ * So the question lives here, in the library both sides already depend on, and
+ * `registerReviewProvider` asks it of every provider that passes through.
+ * Registration is the one seam every provider crosses however it got here,
+ * which makes it the only place this can be asked of all of them.
+ */
+/**
+ * Which method has to exist for each capability that promises one.
+ *
+ * Only capabilities promising a callable belong here. One describing
+ * behaviour, like `staleness: "pinned"` or `maxBatchComments`, is a fact about
+ * the backend rather than a promise about this object.
+ *
+ * This table was checked against the contract rather than assembled from
+ * memory: every capability whose name matches a facet method is in it. Three
+ * optional methods have no capability of any kind, which is the opposite gap
+ * and a milder one: `unreact` and `fileAt` can only be discovered by looking
+ * for the method, so a consumer cannot ask ahead of time and has to degrade on
+ * absence instead. Nothing lies; it just cannot be asked. `commentOn` used to
+ * be the third, and is now spoken for by `fileLevelComments`.
+ *
+ * A row carries a predicate over the declared value rather than assuming
+ * `true`, because several capabilities say more than a boolean can and leaving
+ * them out left the worst hole here uncovered. `reviewersAt` is the one
+ * declaration a caller is told about in the past tense: `review_offer` reports
+ * "asked alice, bob" from an optional call that quietly does nothing when the
+ * method is missing. What each promises is narrower than its type.
+ *
+ * A row also says whether the contract requires the method, because the two
+ * directions are not symmetric. Where a method is mandatory its presence is
+ * guaranteed by the type and proves nothing about what the provider means, so
+ * demanding a declaration to match it would push a provider that legitimately
+ * cannot propose into saying it can.
+ */
+export const BACKED_BY = [
+    { facet: "proposals", capability: "checks", method: "checks" },
+    { facet: "proposals", capability: "list", method: "list" },
+    { facet: "proposals", capability: "fetchAsRef", method: "fetchAsRef" },
+    { facet: "authoring", capability: "rerunChecks", method: "rerun" },
+    { facet: "conversation", capability: "unresolve", method: "unresolve" },
+    {
+        facet: "conversation",
+        capability: "fileLevelComments",
+        method: "commentOn",
+        // "standalone" is the value that promises a method: it says a remark
+        // about a whole file has to be posted outside a batch review, and
+        // `commentOn` is the only way to post one. "batch" is served by
+        // `postReview`, which every conversation facet has.
+        promises: (declared) => declared === "standalone",
+    },
+    {
+        facet: "conversation",
+        capability: "reactions",
+        method: "react",
+        // Naming the reactions it accepts is the promise. An empty set is the
+        // contract's own way of saying it does none.
+        promises: (declared) => Array.isArray(declared) && declared.length > 0,
+    },
+    {
+        facet: "authoring",
+        capability: "propose",
+        method: "propose",
+        mandatory: true,
+    },
+    { facet: "authoring", capability: "proposeStack", method: "proposeStack" },
+    { facet: "authoring", capability: "setDraft", method: "setDraft" },
+    { facet: "authoring", capability: "close", method: "close", mandatory: true },
+    { facet: "authoring", capability: "reopen", method: "reopen" },
+    { facet: "authoring", capability: "merge", method: "merge", mandatory: true },
+    {
+        facet: "authoring",
+        capability: "reviewersAt",
+        method: "requestReviewers",
+        // Meteorite is the live example of the other value: it declares
+        // "creation", omits the method deliberately, and the offer gate
+        // refuses before anything is called.
+        promises: (declared) => declared === "any-time",
+    },
+];
+function facetOf(provider, facet) {
+    // Read as an open record on purpose: the whole point is to ask whether a
+    // named method is there, and the facet types say which methods may exist
+    // rather than letting one be looked up by name.
+    const found = provider[facet];
+    return typeof found === "object" && found !== null
+        ? found
+        : undefined;
+}
+function declaredIn(capabilities, facet) {
+    const found = capabilities[facet];
+    return typeof found === "object" && found !== null
+        ? found
+        : undefined;
+}
+/**
+ * Compare what a provider says it can do against what it can do.
+ *
+ * Both directions are reported, because each is its own kind of wrong. A
+ * declaration with no method behind it is a lie a consumer acts on; a method
+ * with no declaration is work already done that no consumer will ever ask for,
+ * which is how Meteorite's `requestReviewers` sat unreachable while the
+ * provider said reviewers could only be named at creation.
+ *
+ * Takes the locator because a provider is entitled to answer differently for
+ * different repos, and a provider handed a key from the wrong space would
+ * return a default and let every row pass having compared nothing.
+ */
+export function unbackedDeclarations(provider, repo) {
+    const capabilities = provider.capabilities(repo);
+    const found = [];
+    for (const row of BACKED_BY) {
+        const facet = facetOf(provider, row.facet);
+        const declared = declaredIn(capabilities, row.facet);
+        // A provider without the facet at all has nothing to answer for. It
+        // declares nothing about it and implements nothing in it, which is a
+        // coherent position rather than a disagreement.
+        if (!facet && !declared)
+            continue;
+        const value = declared?.[row.capability];
+        const promised = row.promises
+            ? row.promises(value)
+            : // Undefined is not a promise. A capability a provider never
+                // mentioned is one it has not claimed.
+                value === true;
+        const implemented = typeof facet?.[row.method] === "function";
+        if (promised && !implemented) {
+            found.push({
+                facet: row.facet,
+                capability: row.capability,
+                method: row.method,
+                fault: "declared-without-method",
+                reason: `declares ${row.facet}.${row.capability} and has no ${row.method} to back it, so a consumer that asks first is told yes and a consumer that calls gets silence`,
+            });
+            continue;
+        }
+        // Only worth asking where the contract leaves the method optional.
+        // Where it is mandatory, presence is guaranteed by the type and says
+        // nothing about what the provider meant.
+        if (!row.mandatory && implemented && !promised && declared) {
+            found.push({
+                facet: row.facet,
+                capability: row.capability,
+                method: row.method,
+                fault: "method-without-declaration",
+                reason: `implements ${row.facet}.${row.method} and does not declare ${row.capability}, so nothing will ever call it`,
+            });
+        }
+    }
+    return found;
+}

package/dist/review/bind.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Binding a target to a provider, and keeping it bound.
+ *
+ * Resolution is allowed to be clever once. After that it has
+ * to be boring: if a specialist provider registers halfway
+ * through a review, the draft already open must not silently
+ * change which backend it is about to post to. So the first
+ * answer is remembered against the target's key and reused
+ * until the provider it named goes away.
+ */
+import type { RepoLocator, ReviewTarget } from "./change.js";
+import type { RepoProbe, ReviewProvider } from "./provider.js";
+import type { ResolveContext, ResolvedVia } from "./resolve.js";
+/**
+ * The answer for a whole target.
+ *
+ * Carries how the provider was arrived at, because a later failure against it
+ * reads differently depending on the answer: claimed by shape is a guess that
+ * happened to win, and mapped by config is a decision somebody made.
+ */
+export type TargetResolution = {
+    resolved: true;
+    provider: ReviewProvider;
+    repo: RepoLocator;
+    via: ResolvedVia;
+} | {
+    resolved: false;
+    tried: string[];
+    message: string;
+};
+/**
+ * Remember that a target belongs to a provider, and optionally the
+ * repo and route it resolved as. Without them the target's own locator
+ * stands in, which is right for a caller that knows only the provider.
+ */
+export declare function bindTarget(target: ReviewTarget, providerId: string, resolved?: {
+    repo: RepoLocator;
+    via: ResolvedVia;
+}): void;
+/** Forget every binding. Intended for tests and lifecycle. */
+export declare function clearTargetBindings(): void;
+/** Who serves a repo, or why nobody does. */
+export type RepoResolution = {
+    resolved: true;
+    provider: ReviewProvider;
+    repo: RepoLocator;
+    via: ResolvedVia;
+} | {
+    resolved: false;
+    tried: string[];
+    message: string;
+};
+/**
+ * Resolve a checkout to the provider that serves it, with nothing to
+ * review yet.
+ *
+ * "What can be done here" is a question about a repo, and it is asked
+ * before there is a change to ask it about. Answering it through a target
+ * meant inventing a base and a head that nobody named.
+ *
+ * Nothing is remembered. A binding exists so one target cannot change
+ * provider mid-flight; pinning the repo instead would decide for every
+ * range and stack over it, on the strength of a question that only asked
+ * what was possible.
+ */
+export declare function resolveRepo(probe: RepoProbe, context?: ResolveContext): RepoResolution;
+/**
+ * Resolve a whole target to the provider that owns it.
+ *
+ * A hosted change already names its provider, so that is the
+ * answer. A local target has to be claimed by repo, config
+ * first and then claim order. Either way the answer is
+ * remembered, so the next call cannot land somewhere else.
+ */
+export declare function resolveTarget(target: ReviewTarget, context?: ResolveContext): TargetResolution;

package/dist/review/bind.js

@@ -0,0 +1,223 @@
+/**
+ * Binding a target to a provider, and keeping it bound.
+ *
+ * Resolution is allowed to be clever once. After that it has
+ * to be boring: if a specialist provider registers halfway
+ * through a review, the draft already open must not silently
+ * change which backend it is about to post to. So the first
+ * answer is remembered against the target's key and reused
+ * until the provider it named goes away.
+ */
+import { targetKey } from "./keys.js";
+import { getReviewProvider, listReviewProviders } from "./register.js";
+/**
+ * What a resolution decided, keyed by target. Session-scoped: a
+ * binding is about not flipping mid-flight, not about remembering a
+ * choice made last week, and the target's own key is enough to
+ * re-derive the same answer next time.
+ *
+ * The repo is remembered alongside the provider because it is part of
+ * the answer and cannot be recovered from the target. A provider that
+ * maps a checkout onto a hosted repo is the whole point of claiming:
+ * replaying the target's own `local:` locator handed that provider a
+ * repo it does not serve, so the first call worked and every later one
+ * was refused.
+ */
+const bindings = new Map();
+/**
+ * Remember that a target belongs to a provider, and optionally the
+ * repo and route it resolved as. Without them the target's own locator
+ * stands in, which is right for a caller that knows only the provider.
+ */
+export function bindTarget(target, providerId, resolved) {
+    bindings.set(targetKey(target), {
+        providerId,
+        repo: resolved?.repo ?? repoOf(target),
+        via: resolved?.via ?? "config-repo",
+    });
+}
+/** Forget every binding. Intended for tests and lifecycle. */
+export function clearTargetBindings() {
+    bindings.clear();
+}
+/** The repo a target is about. */
+function repoOf(target) {
+    return target.kind === "proposal" ? target.change.repo : target.repo;
+}
+/**
+ * Bind what was resolved and hand back that same answer.
+ *
+ * One statement, because the defect this replaced was a memo and a
+ * reply that disagreed: every site stored the provider and returned a
+ * repo the memo never kept. Going through here, what is remembered is
+ * by construction what was said.
+ */
+function remember(target, resolved) {
+    bindTarget(target, resolved.provider.id, {
+        repo: resolved.repo,
+        via: resolved.via,
+    });
+    return { resolved: true, ...resolved };
+}
+/** What a target was bound to, if its provider is still here. */
+function bound(target) {
+    const binding = bindings.get(targetKey(target));
+    if (!binding)
+        return undefined;
+    const provider = getReviewProvider(binding.providerId);
+    return provider ? { provider, binding } : undefined;
+}
+/** Provider ids config pins to this repo, in order. */
+function mappedIds(repo, probe, context) {
+    // The probe's remotes count here too. A pin written against a remote URL,
+    // which is the spelling somebody reaches for first, could not match a local
+    // target at all: the locator minted for one carries no remote, so the only
+    // strings on offer were a `local:` key and a path.
+    //
+    // The repo's own strings are absent when there is no target, which is the
+    // bare-checkout case: the probe is then everything known, so its root
+    // stands in for the path a locator would have carried.
+    const haystacks = [
+        repo?.key ?? "",
+        repo?.localPath ?? "",
+        repo?.remoteUrl ?? "",
+        probe?.repoRoot ?? "",
+        ...(probe?.remoteUrls ?? context?.probe?.remoteUrls ?? []),
+    ];
+    const mapping = context?.config?.repos?.find((entry) => haystacks.some((value) => value.includes(entry.match)));
+    return mapping?.providers ?? [];
+}
+/**
+ * Ask providers to claim a repo, in the order given, and take
+ * the first that does.
+ */
+function claimRepo(providers, probe, tried) {
+    for (const provider of providers) {
+        tried.push(provider.id);
+        const claimed = provider.claimRepo(probe);
+        if (claimed)
+            return { provider, repo: claimed };
+    }
+    return undefined;
+}
+/**
+ * What a target says about the checkout it covers, for a caller
+ * that has no probe.
+ *
+ * The caller's probe wins where there is one, because it is what somebody
+ * actually went and looked at: the engine reads every remote out of the
+ * checkout and passes them down. Reconstructing a probe from the target
+ * instead throws that away, and for a local target it throws away all of
+ * it, since the locator the engine mints there carries a path and no
+ * remote. Every provider was then asked to claim a checkout with no
+ * remotes, which only a provider claiming anything local can answer, so a
+ * hosted repo resolved to plain git and lost its authoring facet with it.
+ */
+function probeOf(repo, context) {
+    return (context?.probe ?? {
+        repoRoot: repo.localPath,
+        remoteUrls: repo.remoteUrl ? [repo.remoteUrl] : [],
+    });
+}
+/**
+ * Resolve a checkout to the provider that serves it, with nothing to
+ * review yet.
+ *
+ * "What can be done here" is a question about a repo, and it is asked
+ * before there is a change to ask it about. Answering it through a target
+ * meant inventing a base and a head that nobody named.
+ *
+ * Nothing is remembered. A binding exists so one target cannot change
+ * provider mid-flight; pinning the repo instead would decide for every
+ * range and stack over it, on the strength of a question that only asked
+ * what was possible.
+ */
+export function resolveRepo(probe, context) {
+    return resolveIn(probe, context);
+}
+/**
+ * The claim walk itself: config's pins first, then claim order.
+ *
+ * One copy, two entry points. A target's repo is resolved exactly the way
+ * a bare checkout's is, and only what happens afterwards differs, so the
+ * locator comes in as an argument rather than the walk being written twice.
+ */
+function resolveIn(probe, context, repo) {
+    const tried = [];
+    const ids = mappedIds(repo, probe, context);
+    const mapped = ids
+        .map((id) => getReviewProvider(id))
+        .filter((provider) => provider !== undefined);
+    const byConfig = claimRepo(mapped, probe, tried);
+    if (byConfig)
+        return { resolved: true, ...byConfig, via: "config-repo" };
+    const remaining = listReviewProviders().filter((provider) => !tried.includes(provider.id));
+    const byClaim = claimRepo(remaining, probe, tried);
+    if (byClaim)
+        return { resolved: true, ...byClaim, via: "claim" };
+    return {
+        resolved: false,
+        tried,
+        message: unclaimed(ids),
+    };
+}
+/** Why nobody claimed a repo, naming a pin that names nobody. */
+function unclaimed(ids) {
+    const absent = ids.filter((id) => !getReviewProvider(id));
+    const missing = absent.length > 0
+        ? ` Config names ${absent.join(", ")} for this repo, but no ` +
+            "provider registered under that id."
+        : "";
+    return ("No review provider claimed this repo. Pin it under " +
+        `review.repos, or register a provider that recognizes it.${missing}`);
+}
+/**
+ * Resolve a whole target to the provider that owns it.
+ *
+ * A hosted change already names its provider, so that is the
+ * answer. A local target has to be claimed by repo, config
+ * first and then claim order. Either way the answer is
+ * remembered, so the next call cannot land somewhere else.
+ */
+export function resolveTarget(target, context) {
+    const remembered = bound(target);
+    if (remembered) {
+        // A binding is a decision already taken, so it replays that decision
+        // whole: the same provider, the same repo, and the route that found
+        // them. Re-deriving any part of it here is how the answer drifted.
+        return {
+            resolved: true,
+            provider: remembered.provider,
+            repo: remembered.binding.repo,
+            via: remembered.binding.via,
+        };
+    }
+    if (target.kind === "proposal") {
+        const provider = getReviewProvider(target.change.provider);
+        if (!provider) {
+            return {
+                resolved: false,
+                tried: [],
+                message: `This change belongs to the ${target.change.provider} ` +
+                    "provider, which is not registered. Load the package that " +
+                    "provides it, or map the repo to another provider under " +
+                    "review.repos.",
+            };
+        }
+        // The change names its own provider, so nothing was guessed.
+        return remember(target, {
+            provider,
+            repo: target.change.repo,
+            via: "config-repo",
+        });
+    }
+    const repo = repoOf(target);
+    const byRepo = resolveIn(probeOf(repo, context), context, repo);
+    if (!byRepo.resolved)
+        return byRepo;
+    return remember(target, {
+        provider: byRepo.provider,
+        repo: byRepo.repo,
+        via: byRepo.via,
+    });
+}