wicked-crew 0.6.0 → 0.7.0

package/dist/projects/graph.d.ts

@@ -0,0 +1,179 @@
+/**
+ * The project code graph — every `crew.repo` member of one project in ONE wicked-estate database.
+ *
+ * # What changed to make this possible
+ *
+ * One estate database used to hold exactly one repo. SymbolIds embed the repo-relative path, so two
+ * repos that both contain `src/index.ts` mint identical file rows AND identical symbol ids: the
+ * second index overwrote the first and said nothing. `wicked-estate index <path> --repo <label>`
+ * (wicked-estate#117) namespaces every path as `<label>/…`, so N repos co-exist, each queryable,
+ * with a guard that refuses — before a row is written — any index that would overwrite another
+ * repo's content.
+ *
+ * # THE LIMIT
+ *
+ * CO-LOCATION IS NOT LINKAGE. estate resolves edges within a labelled repo's own nodes, exactly as
+ * if each repo sat in its own database. `studio → wicked-crew-api-types → crew` does not traverse.
+ * What this module federates is per-repo results into one answer with the repo named on every hit —
+ * which is genuinely useful ("who calls `record`, anywhere in this project") and is NOT a cross-repo
+ * dependency trace. Every response carries `linkage: 'co-located'` and {@link CO_LOCATION_NOTE} so a
+ * consumer cannot mistake one for the other.
+ *
+ * # Why the estate binary is capability-PROBED before anything is indexed
+ *
+ * `wicked-estate 0.14.4` — the version installed on this machine while this was written — accepts
+ * `--repo`, IGNORES it, and exits 0. Indexing three repos through it produces a database holding
+ * only the third, with no error anywhere and results that look perfectly healthy. That is the exact
+ * silent-loss failure the labelling work exists to end, reachable by nothing worse than a stale
+ * binary on PATH. So the flag's support is established from the binary that will actually run,
+ * before the first index (help text), and confirmed from the database afterwards (the labelled repo
+ * registry `stats` prints) — a claim, then evidence.
+ *
+ * # Honest degradation
+ *
+ * Every path out of here names its cause. A project with no repo members, one whose graph was never
+ * built, one whose member repo the registry no longer knows, and an addon too old to publish
+ * `code_graph_db` are four different situations with four different remedies; collapsing them into
+ * an empty result set is the failure estate's own R3 rule exists to prevent, and it is the failure
+ * FINDING-069 actually shipped.
+ */
+import type { CoreAdapter } from '../core/adapter.js';
+import type { ProjectBlastRadius, ProjectGraphHit, ProjectGraphRefreshResult, ProjectGraphRepoCount, ProjectGraphSearch, ProjectGraphStatus } from '../core/types.js';
+/** The sentence every project-graph response carries. Stated on the wire, not just in this file. */
+export declare const CO_LOCATION_NOTE: string;
+/**
+ * The second sentence `/graph/search` carries, and only it.
+ *
+ * `matches: []` from an exact-name resolver against a healthy graph is the empty-result-that-reads-
+ * as-an-answer this whole surface is built to refuse: a caller who typed half a name is told
+ * "nothing in this project", which is false. estate's `resolve` has no substring mode (the header
+ * on {@link projectSymbolSearch} argues why a `nodes --json` dump is not the answer), so the
+ * matching RULE goes on the wire instead of a matching mode that does not exist.
+ */
+export declare const EXACT_NAME_NOTE: string;
+/**
+ * Does the `wicked-estate` that will actually run support `--repo`?
+ *
+ * A version comparison would be the obvious probe and the wrong one: it asks a string on disk
+ * instead of the binary on PATH, and a locally built or vendored estate can carry any version it
+ * likes. The usage banner is printed by the same binary that would do the indexing.
+ */
+export declare function estateSupportsMultiRepo(env?: NodeJS.ProcessEnv): Promise<boolean>;
+/**
+ * The evidence check failed: the binary took `--repo` and dropped it.
+ *
+ * A distinct type because it is NOT a per-repo failure and must not be collected as one. It is the
+ * same fact the capability probe establishes — this binary cannot co-locate — discovered one step
+ * later, and the only safe response is the probe's: stop, before the next repo's index overwrites
+ * the rows just written. Recording it in `failed` and continuing runs a full index per member, each
+ * clobbering the last, while the message on every entry claims the opposite.
+ */
+export declare class EstateDroppedRepoLabelError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when the running addon predates `code_graph_db` on the repo record. Mapped to 501: this is
+ * a capability gap in the engine, not a bad request.
+ *
+ * WHY this surface gates on a field it does not itself use. The project graph lives in crew's own
+ * state directory and is built from `root_path`, so it could be built against any addon. But
+ * `code_graph_db` is the engine's statement that it can vouch for where a repo's graph lives, and
+ * `/repos/:id/graph` HARD-THROWS without it (repoPaths.ts, deliberately — a local re-derivation is
+ * what FINDING-069 was). Quietly serving a project graph on a daemon whose per-repo graph surface
+ * cannot answer would leave two graph endpoints disagreeing about whether this repo has a graph at
+ * all, and the operator's real problem — a stale addon — unmentioned.
+ */
+export declare class ProjectGraphEngineTooOldError extends Error {
+    readonly cause: string;
+    constructor(cause: string);
+}
+/** Read the project graph's standing without touching it. */
+export declare function projectGraphStatus(adapter: CoreAdapter, projectId: string, env?: NodeJS.ProcessEnv): Promise<ProjectGraphStatus>;
+export declare function refreshProjectGraph(adapter: CoreAdapter, projectId: string, env?: NodeJS.ProcessEnv): Promise<ProjectGraphRefreshResult>;
+/**
+ * Passed to the engine as `LaunchOptions.projectGraph`. `repoLabel` names this run's repo inside
+ * the co-located graph so the engine can confirm the graph actually holds it; a repo-less run
+ * carries no label because it has no own repo to confirm.
+ */
+export interface ProjectGraphBinding {
+    dbPath: string;
+    repoLabel?: string;
+}
+/**
+ * What a launch decided about the project graph, and why. The `reason` is carried on BOTH outcomes
+ * because "you got the project graph" and "you got the repo graph instead, because X" are equally
+ * worth saying, and the operator asking "why can't this run see the sibling repo" needs the second
+ * one to have been recorded somewhere.
+ */
+export interface ProjectGraphBindingDecision {
+    /** The binding to hand the engine; `null` ⇒ the run keeps whatever graph it would have had. */
+    binding: ProjectGraphBinding | null;
+    /** One sentence: what the run got, and what would change it. */
+    reason: string;
+}
+/**
+ * Decide which code graph a run launched into `projectId` should be bound to.
+ *
+ * # This never indexes
+ *
+ * A refresh is `wicked-estate index` per member repo, bounded at ten minutes EACH. Doing that
+ * inside a launch would turn "start a run" into an unannounced multi-repo indexing job that blocks
+ * the response, and the first thing an operator would learn about it is a request that appears to
+ * hang. So a missing or stale graph DEGRADES the run to the per-repo graph and says so; refreshing
+ * stays an explicit `POST /projects/:id/graph/refresh`.
+ *
+ * # Why the run's OWN repo decides it
+ *
+ * The engine independently verifies whatever it is handed and falls back on its own, so this
+ * function cannot make a run unsafe — but it can make one confusing, and it has information the
+ * engine does not. `projectGraphStatus` knows a repo was attached after the last refresh, that its
+ * registry root moved out from under the label, that its member ref is dangling. Declining HERE,
+ * with that cause attached, is the difference between an operator reading "attached since the last
+ * refresh — not in the graph yet" and reading the engine's generic "no files under that label".
+ *
+ * The rule itself is the engine's, restated on this side: bind when the graph holds THIS RUN'S
+ * repo. A graph missing some OTHER member is still bound — it is strictly more than the per-repo
+ * graph, and the run's own code is described correctly. A graph missing THIS repo is not, because
+ * its answers about the worktree the worker is sitting in would all be "nothing found".
+ */
+export declare function resolveProjectGraphBinding(adapter: CoreAdapter, projectId: string, repoRef: string | undefined, env?: NodeJS.ProcessEnv): Promise<ProjectGraphBindingDecision>;
+/**
+ * A query can run only against a graph that exists and holds at least one MEMBER repo. Anything
+ * else is returned as the status, so the caller gets the cause and the remedy instead of `[]`.
+ */
+export type Queryable = {
+    ok: true;
+    dbPath: string;
+    status: ProjectGraphStatus;
+    labels: Map<string, string>;
+} | {
+    ok: false;
+    status: ProjectGraphStatus;
+};
+export declare function queryable(adapter: CoreAdapter, projectId: string, env?: NodeJS.ProcessEnv): Promise<Queryable>;
+/**
+ * estate's raw hit list → attributed hits plus their per-repo counts. THE federation step, and the
+ * only place a result acquires its provenance — exported so the attribution rules are testable
+ * without a graph on disk, which is what makes the stale-label exclusion below coverable at all.
+ */
+export declare function attributeHits(raw: unknown, labels: Map<string, string>): {
+    hits: ProjectGraphHit[];
+    byRepo: ProjectGraphRepoCount[];
+};
+/** Dependents of a symbol across every member repo, each hit attributed to the repo it is in. */
+export declare function projectBlastRadius(q: Extract<Queryable, {
+    ok: true;
+}>, name: string, env?: NodeJS.ProcessEnv): Promise<ProjectBlastRadius>;
+/**
+ * Symbol search across every member repo — exact name, which is what estate's `resolve` answers.
+ *
+ * Not a substring search on purpose: the only estate primitive that would give one is a full
+ * `nodes --json` dump filtered daemon-side, whose cost scales with the whole project rather than
+ * with the query, and which would need a cap whose truncation is itself a silent wrong answer.
+ * `resolve` is the same primitive the repo-scoped surface uses to turn a name into SymbolIds; run
+ * against a co-located graph it returns every repo's matches in one call.
+ */
+export declare function projectSymbolSearch(q: Extract<Queryable, {
+    ok: true;
+}>, name: string, env?: NodeJS.ProcessEnv): Promise<ProjectGraphSearch>;
+//# sourceMappingURL=graph.d.ts.map

package/dist/projects/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/projects/graph.ts"],"names":[],"mappings":"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"}