gitnexus 1.6.11-rc.8 → 1.6.11

package/dist/core/ingestion/asyncapi/document.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Read AsyncAPI 3.x documents off disk and normalize their operations into
+ * broker addresses.
+ *
+ * Deliberately OUTSIDE `frameworks/spring/`. An AsyncAPI document is a
+ * published artifact, not a Spring one: it is emitted by generators across
+ * Java, Kotlin, TypeScript, Go and Python toolchains, and it is written by hand
+ * as often as it is generated. The entry criterion here is therefore the
+ * DOCUMENT FORMAT — a root `asyncapi` key — and never the generator. Nothing in
+ * this module may branch on `x-generator`, on a vendor extension, or on the
+ * shape of an operation key: the moment it does, every service whose toolchain
+ * spells things differently stops being read, and the failure is silent.
+ *
+ * ── WHY THIS IS WORTH READING AT ALL ──────────────────────────────────────
+ *
+ * A `@KafkaListener(topics = "${app.topic.in}")` names a configuration key, not
+ * an address, and the address cascade correctly refuses to resolve it — two
+ * services that merely wrote the same placeholder have said nothing about each
+ * other. But the service's own published document states the address outright,
+ * fully resolved, because the generator ran with the configuration applied.
+ * That is a fact about the service that no amount of reading its source can
+ * recover.
+ *
+ * ── WHAT THIS MODULE IS AFRAID OF ─────────────────────────────────────────
+ *
+ * Everything it emits becomes half of a JOIN KEY. A destination minted here
+ * meets every other site in every other repository that names the same address
+ * on the same broker — that is the whole value, and it is the whole hazard. A
+ * missing destination is a visible gap; a wrong one is reported as a fact. So
+ * the refusals below are not defensive clutter: each one is a case where the
+ * document says something that LOOKS like an address and is not one, and where
+ * accepting it would connect two services that have said nothing about each
+ * other. The taxonomy is closed and countable for the same reason the source
+ * cascade's is — a feature judged on its unresolved fraction needs the fraction
+ * broken down by cause, or nobody can tell it what to go and fix.
+ *
+ * ── VERSION 2.x IS REFUSED, NOT MAPPED ────────────────────────────────────
+ *
+ * AsyncAPI 2.x describes a channel from the READER's point of view: `publish`
+ * means "you may publish here", so the documenting application RECEIVES, and
+ * `subscribe` means the application SENDS. Version 3.0 renamed these to the
+ * application's own `receive` / `send`. Mapping 2.x naively therefore reverses
+ * every direction in the async graph — and reverses it INVISIBLY, because both
+ * roles still exist, every edge is still emitted, and the graph stays
+ * connected. Nothing fails; the arrows simply point the wrong way.
+ *
+ * The inversion is one line to write and impossible to test against a real
+ * corpus we do not have, and the 2.x wording confused implementers badly enough
+ * that some generators emitted it backwards. So 2.x is refused under its own
+ * countable reason instead. A silent skip would be indistinguishable from "this
+ * service publishes no document", which is the one thing the count has to be
+ * able to tell us: if the refusal tally shows 2.x documents in the field, the
+ * inversion earns its way in with evidence behind it.
+ */
+/**
+ * Why a document, or one operation inside it, produced no address.
+ *
+ * A CLOSED, COUNTABLE set, and deliberately NOT `SpringDestinationRefusal`.
+ * That union is documented as the reasons a *source-level candidate* produced
+ * no address, and it is the denominator of the unresolved fraction the address
+ * work is judged on. Folding document-level failures into it would silently
+ * change what that number means — a repository whose specification directory
+ * was mistyped would report a worse SOURCE, which is the opposite of the truth.
+ *
+ * Members are split wherever two causes are different FACTS about the input.
+ * A tally whose member says "the document contradicts itself" when the document
+ * is merely multi-protocol sends an operator to fix the wrong thing, and this
+ * tally is the number the whole feature is judged on.
+ */
+export type AsyncApiRefusal = 
+/** The file parsed but has no root `asyncapi` key: not a document at all. */
+'not-a-document'
+/** Root `asyncapi: 2.x`. See the header — refused, never mapped. */
+ | 'asyncapi-2-unsupported'
+/** A root `asyncapi` key naming a version this module does not read. */
+ | 'unsupported-version'
+/** Malformed YAML/JSON, or a root that is not an object. */
+ | 'unparsable'
+/** The file could not be read, or is not a regular file (a FIFO, a device). */
+ | 'unreadable'
+/** A subdirectory could not be listed. Counted rather than skipped: under a
+ *  mixed-permission cache half the documents can be invisible while the run
+ *  otherwise reports a clean, complete read. */
+ | 'directory-unreadable'
+/** Larger than {@link MAX_DOCUMENT_BYTES}. */
+ | 'oversized'
+/** The document held more operations than one run will examine. */
+ | 'operation-cap'
+/** The run as a whole reached {@link MAX_TOTAL_OPERATIONS}. */
+ | 'total-operation-cap'
+/** The document declares more servers than the channel-inheritance rule will
+ *  read. */
+ | 'server-cap'
+/** The walk hit a bound before it finished, so the document set is a floor
+ *  rather than the whole of what the configured path holds. A truncated read
+ *  that reported nothing would be indistinguishable from a complete one. */
+ | 'walk-truncated'
+/** `operations[].channel.$ref` is absent or not a local channel pointer. */
+ | 'no-channel-reference'
+/** The `$ref` resolved to no channel in this document. */
+ | 'channel-not-found'
+/** The channel entry is itself a Reference Object, which this module does not
+ *  follow. Distinct from `no-address` on purpose: a `$ref`-ed channel HAS an
+ *  address, somewhere this reader did not look, and filing it under
+ *  `no-address` tells an operator their documents omit addresses when the
+ *  real answer is that the reader stops one hop short. */
+ | 'unresolved-channel-reference'
+/** The channel names no `address`, so there is nothing to key on. */
+ | 'no-address'
+/**
+ * The address is a TEMPLATE, not an address: the channel declares non-empty
+ * `parameters`, or the address carries a `{…}` placeholder.
+ *
+ * This is the document-side twin of the source cascade's
+ * `overridable-config-default`, and it exists for the identical reason. Two
+ * services that both publish `{env}.orders` have named a pattern they share,
+ * not a queue they share — one deploys with `env=prod` and the other with
+ * `env=staging`, and keying on the template text merges them into a single
+ * node with a publisher on one side and a subscriber on the other. That is a
+ * false connection built entirely from conformant AsyncAPI: `parameters` and
+ * `{param}` are core 3.x vocabulary, not a vendor quirk.
+ */
+ | 'templated-address'
+/** Longer than {@link MAX_ADDRESS_LENGTH}. */
+ | 'address-too-long'
+/** Longer than {@link MAX_OPERATION_ID_LENGTH}. */
+ | 'operation-id-too-long'
+/** `action` is neither `send` nor `receive`. */
+ | 'unrecognized-action'
+/** Neither the operation's bindings nor the servers its channel resolves to
+ *  name a protocol. Silence about the broker is not a claim about it, but a
+ *  `Destination` cannot be keyed without one. */
+ | 'protocol-unknown'
+/** The operation's OWN two statements about its broker — its bindings and the
+ *  servers its channel explicitly lists — name different brokers. The
+ *  document contradicts itself, and a destination keyed on the wrong broker
+ *  joins a stranger. */
+ | 'protocol-disagreement'
+/** The channel lists no `servers`, so it inherits all of them, and they do
+ *  not agree on one broker. The document does NOT contradict itself here —
+ *  it is simply multi-protocol and this channel did not choose — which is why
+ *  this is not `protocol-disagreement`. */
+ | 'ambiguous-server-default'
+/**
+ * The channel inherits the document's servers, but that map was CAPPED at
+ * {@link MAX_SERVERS_PER_DOCUMENT}, so the brokers read are a subset.
+ *
+ * Distinct from `ambiguous-server-default`, and the distinction is the whole
+ * point: unanimity across a subset is not unanimity. A document whose first
+ * thousand servers are Kafka and whose thousand-and-first is JMS reads as
+ * unanimously Kafka, and every operation inheriting it would be attributed to
+ * a broker the complete set does not agree on.
+ */
+ | 'capped-server-default'
+/**
+ * A server this operation depends on is a Reference Object this reader could
+ * not resolve — a pointer outside `#/servers` and `#/components/servers`, a
+ * name that is absent, or a reference to another reference.
+ *
+ * Refused rather than skipped. Skipping one server of several silently
+ * narrows the evidence, and a narrowed set is what makes a mixed document
+ * look like it agrees with itself.
+ */
+ | 'unresolved-server-reference'
+/** The broker is HTTP or WebSocket, where the host rather than the address is
+ *  the namespace. See `isNonDestinationBroker`. */
+ | 'not-a-destination-protocol';
+export interface AsyncApiOperation {
+    /** Absolute path of the document this operation came from. */
+    readonly documentPath: string;
+    /** The `operations` map key, kept for provenance and carried into the edge
+     *  `reason` so a reader can find the operation the edge came from. */
+    readonly operationId: string;
+    readonly action: 'send' | 'receive';
+    readonly address: string;
+    /** Normalized broker — the first half of the `Destination` key. */
+    readonly broker: string;
+}
+export interface AsyncApiReadResult {
+    readonly operations: readonly AsyncApiOperation[];
+    /** Files considered — every candidate extension under the configured path. */
+    readonly documentsScanned: number;
+    /** Files that parsed as an AsyncAPI 3.x document and yielded an operation. */
+    readonly documentsAccepted: number;
+    /** Entries skipped because they were symbolic links. Not a refusal — the skip
+     *  is deliberate — but counted, because a cache written by other tooling is
+     *  very often a symlink farm, and an operator whose whole cache was skipped
+     *  would otherwise see a result identical to a wrong path. */
+    readonly symlinksSkipped: number;
+    /** True when a bound stopped the walk or the operation count, so every number
+     *  here is a floor rather than a total. */
+    readonly truncated: boolean;
+    /** Every refusal, document-level and operation-level, by reason. */
+    readonly refusals: Readonly<Partial<Record<AsyncApiRefusal, number>>>;
+}
+export interface NormalizedDocument {
+    operations: AsyncApiOperation[];
+    refusals: Partial<Record<AsyncApiRefusal, number>>;
+    /** Operations EXAMINED, which is what the caps count. */
+    examined: number;
+    /** A bound stopped this document short. */
+    truncated: boolean;
+}
+/**
+ * Normalize one parsed document. Pure — no filesystem, so the whole refusal
+ * surface is testable from inline document literals.
+ *
+ * `budget` is the number of operations the RUN may still examine.
+ */
+export declare function normalizeAsyncApiDocument(parsed: unknown, documentPath: string, budget?: number): NormalizedDocument;
+/**
+ * Read every AsyncAPI 3.x document under an explicitly configured path.
+ *
+ * `configuredPath` is resolved against the repository root, so an absolute path
+ * to a cache populated out of band and a repo-relative directory of committed
+ * documents are both natural — the same shape `springActuatorPath` offers for
+ * Actuator snapshots. The READ is wider than that neighbour's, and the
+ * difference is worth stating rather than glossed as "the same contract": the
+ * Actuator loader probes five fixed filenames in one directory, while this
+ * walks recursively under the caps above and opens every candidate it finds.
+ *
+ * There is deliberately NO glob-based auto-discovery. Scanning a repository for
+ * anything that parses as a document would make every existing index grow nodes
+ * on its next run with nobody having asked for it.
+ */
+export declare function readAsyncApiDocuments(repoPath: string, configuredPath: string): Promise<AsyncApiReadResult>;