@mitre/hdf-openapi 0.0.0-stage → 0.0.1-reserve.0

package/dist/index.d.ts

@@ -0,0 +1,236 @@
+//#region src/components.d.ts
+interface JsonSchema {
+  [key: string]: unknown;
+}
+interface ComponentsDocument {
+  openapi: string;
+  info: {
+    title: string;
+    version: string;
+    description: string;
+    license: {
+      name: string;
+      identifier: string;
+    };
+    contact: {
+      name: string;
+      url: string;
+    };
+  };
+  jsonSchemaDialect: string;
+  components: {
+    schemas: Record<string, JsonSchema>;
+  };
+}
+/** The bundler's own list (hdf-schema/src/bundle-schemas.ts), in its order. */
+export declare const MAIN_SCHEMAS: readonly ["hdf-results.schema.json", "hdf-baseline.schema.json", "hdf-comparison.schema.json", "hdf-system.schema.json", "hdf-plan.schema.json", "hdf-amendments.schema.json", "hdf-evidence-package.schema.json", "hdf-requirement-change-event.schema.json"];
+export declare const ROOT_COMPONENT_NAMES: Record<string, string>;
+/** Named definitions across the bundles, excluding the eight roots. */
+export declare const EXPECTED_DEFINITIONS = 115;
+interface BuildOptions {
+  /** Tracked expectation for the named-definition count; a mismatch fails. */
+  expectedDefinitions?: number;
+}
+export declare function buildComponentsDocument(bundles: Map<string, JsonSchema>, options?: BuildOptions): ComponentsDocument;
+//#endregion
+//#region src/embed.d.ts
+/**
+ * The tracked embed, not `hdf-schema/dist/` — dist is gitignored, so a glob of it
+ * silently yields whatever the last local build left behind. The embed is the
+ * copy `build:schemas` writes and CI reviews.
+ */
+export declare const EMBED_DIR: string;
+/**
+ * Reads the eight bundles. The file set must equal MAIN_SCHEMAS exactly: a bundle
+ * that appeared or vanished changes which document types the contract covers, and
+ * that is a reviewed change, never an inferred one.
+ */
+export declare function loadBundles(embedDir: string): Map<string, JsonSchema>;
+//#endregion
+//#region src/extract.d.ts
+/**
+ * Lifts one component out of the components document as a schema that validates on its
+ * own — the inverse of the components transform, and the only way to check that the
+ * transform preserved meaning rather than merely producing well-formed output.
+ *
+ * The closure is walked transitively rather than copying every component, so what comes
+ * back is the subgraph the named component actually depends on. A component that dragged
+ * in the whole document would make the test pass for the wrong reason.
+ *
+ * Validate the result with a 2020-12 engine. This repository's own validators are
+ * draft-07 and ignore `unevaluatedProperties` (ADR-0009 §5), so they would accept
+ * documents the schema text rejects.
+ */
+export declare function extractStandaloneSchema(doc: ComponentsDocument, name: string): JsonSchema;
+//#endregion
+//#region src/bindings.d.ts
+/**
+ * Every key the table may use. ADR-0008 §2 defines the grammar; anything outside this set
+ * is a fault, which is what stops the table growing an API by accretion.
+ *
+ * `class` is deliberately absent for real tools — it derives from the tool's
+ * `readOnlyHint` — and legal only inside `synthetic`, where no hint exists.
+ */
+export declare const CLOSED_KEYS: Set<string>;
+/**
+ * Input names that are filesystem-shaped whatever their schema says: the service owns
+ * where bytes live, so none may reach HTTP. ADR-0008 §2 requires a hard-fail on each
+ * unless the table drops it with a reason.
+ */
+export declare const FILESYSTEM_FIELDS: Set<string>;
+/**
+ * `sources` is deliberately NOT gated, and that is a correction to ADR-0008 §2.
+ *
+ * Its hard-fail list names `sources`, but every `source`/`sources` input on every tool has
+ * the same properties — `{handle, path}` — so the name carries no filesystem meaning of its
+ * own. Only the descriptions differ (hdf_convert calls it a batch of tool-output files; the
+ * others call it a set of documents), and prose is not a contract. The filesystem half is
+ * `path`, which the fixed `handle` -> `id` rewrite drops by taking the id instead.
+ *
+ * The ADR's own Context list of filesystem-shaped inputs omits `sources`, which is the
+ * clue that the hard-fail list over-reached. Gating it by name would drop cross-document
+ * query, compliance and aggregate for a rule that is really about the traversal inputs
+ * above — directory, pattern, failFast and outputDir — which stay gated.
+ */
+interface ToolBinding {
+  method?: string;
+  path?: string;
+  fields?: Record<string, {
+    placement?: string;
+    enumFrom?: string;
+  }>;
+  drop?: {
+    name: string;
+    reason: string;
+  }[];
+  bodyRef?: string;
+  /** A fullShapes key whose shape becomes the envelope's `summary` member. */
+  summaryRef?: string;
+  items?: string;
+  fullResponse?: string | string[];
+  class?: string;
+}
+interface BindingTable {
+  tools?: Record<string, ToolBinding>;
+  resources?: Record<string, {
+    method?: string;
+    path?: string;
+  }>;
+  synthetic?: Record<string, ToolBinding & {
+    scopes?: string[];
+  }>;
+  absent?: {
+    tool?: string;
+    resource?: string;
+    field?: string;
+    reason: string;
+  }[];
+}
+export declare function loadBindings(yamlText: string): BindingTable;
+interface Surface {
+  toolsList: {
+    tools: {
+      name: string;
+      inputSchema?: {
+        properties?: Record<string, unknown>;
+      };
+    }[];
+  };
+  contract: Record<string, unknown>;
+  /** Conventions component names, the one hand-authored shape input §2 admits. */
+  conventions?: string[];
+}
+/**
+ * Resource and template names from the contract. Both live one level down — the golden
+ * wraps each list with its cache policy (`ttlMs`, `cacheScope`) — so the nesting is read
+ * here rather than assumed by every caller.
+ */
+export declare function resourceNames(contract: Record<string, unknown>): string[];
+/**
+ * Every way the table fails to map the live surface, as one flat list so a caller can
+ * report all of them rather than the first. Each fault is prefixed with the tool it
+ * belongs to, so a per-tool test can filter.
+ */
+export declare function bindingFaults(table: BindingTable, surface: Surface): string[];
+//#endregion
+//#region src/generate-api.d.ts
+/**
+ * ADR-0010 §6, consumed as written: the codes it gives an HTTP status, with the status and
+ * the kebab-cased problem type. The `type` is the hosted prefix plus the kebab code, which
+ * §6 states rather than leaves to the reader.
+ */
+export declare const PROBLEM_TYPES: Record<string, {
+  status: number;
+  type: string;
+}>;
+/**
+ * The codes ADR-0010 §6 marks `never`. Recorded rather than silently dropped: each is a
+ * `file`-adapter concern with no HTTP surface, and TRUNCATED is dead in the MCP too.
+ */
+export declare const UNMAPPED_CODES: string[];
+/** Schemas exempt from the additionalProperties:false rule, each with its reason. */
+export declare const STRICTNESS_EXEMPT: Record<string, string>;
+/** ADR-0008 §4's format allowlist. A format outside it hard-fails rather than shipping. */
+export declare const ALLOWED_FORMATS: Set<string>;
+/**
+ * ADR-0008 §2's fixed rewrite map, output half. These are MCP transport state — a
+ * filesystem path, a write gate, a page index, a handle — and none may reach HTTP. Stripped
+ * from every response shape rather than waived per operation.
+ */
+export declare const STRIPPED_OUTPUT_FIELDS: Set<string>;
+/**
+ * Nested leaves that are open on purpose, each with the reason. Everything else that is
+ * not a document schema must set additionalProperties: false.
+ */
+export declare const OPEN_LEAF_EXEMPT: Record<string, string>;
+interface Operation {
+  operationId: string;
+  summary?: string;
+  parameters?: unknown[];
+  requestBody?: unknown;
+  responses: Record<string, unknown>;
+  security?: Record<string, string[]>[];
+}
+interface ApiDocument {
+  openapi: string;
+  info: Record<string, string>;
+  paths: Record<string, Record<string, Operation>>;
+  components: Record<string, unknown>;
+}
+interface GenerateOptions {
+  /** Replace the tracked table, so a test can plant a fault the real one cannot carry. */
+  tableOverride?: BindingTable;
+  /** Extra component schemas, so a test can plant one the strictness rules must reject. */
+  extraSchemas?: Record<string, unknown>;
+  /** Extra path items, so a test can plant a leak the rewrite map would otherwise remove. */
+  extraPaths?: Record<string, Record<string, unknown>>;
+}
+declare function generateApiDocument(options?: GenerateOptions): ApiDocument;
+//#endregion
+//#region src/conventions.d.ts
+export declare const CONVENTIONS_DIR: string;
+interface ConventionComponent {
+  file: string;
+  /** The component name the binding table references, derived from the title. */
+  name: string;
+  schema: Record<string, unknown>;
+}
+/** PascalCase from the title, so the file, the title and the reference cannot disagree. */
+export declare function componentName(title: string): string;
+export declare function loadConventions(dir?: string): ConventionComponent[];
+//#endregion
+//#region src/validate-example.d.ts
+interface ExampleFault {
+  index: number;
+  errors: string;
+}
+/**
+ * Faults in a schema's own examples. An empty array means every example validates.
+ *
+ * `references` supplies the components an example's schema may `$ref` — the ingest request
+ * points at the eight document roots, so without them it cannot compile.
+ */
+export declare function validateExample(schema: Record<string, unknown>, references?: Record<string, unknown>): ExampleFault[];
+//#endregion
+export { type ApiDocument, type BindingTable, type BuildOptions, type ComponentsDocument, type ConventionComponent, type ExampleFault, type GenerateOptions, type JsonSchema, type ToolBinding, generateApiDocument as apiSpec };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/components.ts","../src/embed.ts","../src/extract.ts","../src/bindings.ts","../src/generate-api.ts","../src/conventions.ts","../src/validate-example.ts"],"mappings":";UAAiB;GACd;;UAGc;EACf;EACA;IACE;IACA;IACA;IACA;MAAW;MAAc;;IACzB;MAAW;MAAc;;;EAE3B;EACA;IAAc,SAAS,eAAe;;;;qBAI3B;qBAWA,sBAAsB;;qBAYtB;UA4JI;;EAEf;;wBAGc,wBACd,SAAS,YAAY,aACrB,UAAS,eACR;;;;;;;;qBChMU;;;;;;wBAOG,YAAY,mBAAmB,YAAY;;;;;;;;;;;;;;;;wBCgC3C,wBAAwB,KAAK,oBAAoB,eAAe;;;;;;;;;;qBCrCnE,aAAW;;;;;;qBAgCX,mBAAiB;;;;;;;;;;;;;;;UAyBb;EACf;EACA;EACA,SAAS;IAAiB;IAAoB;;EAC9C;IAAS;IAAc;;EACvB;;EAEA;EACA;EACA;EACA;;UAGe;EACf,QAAQ,eAAe;EACvB,YAAY;IAAiB;IAAiB;;EAC9C,YAAY,eAAe;IAAgB;;EAC3C;IAAW;IAAe;IAAmB;IAAgB;;;wBAG/C,aAAa,mBAAmB;UA6CtC;EACR;IAAa;MAAS;MAAc;QAAgB,aAAa;;;;EACjE,UAAU;;EAEV;;;;;;;wBAQc,cAAc,UAAU;;;;;;wBAgBxB,cAAc,OAAO,cAAc,SAAS;;;;;;;;qBC7I/C,eAAe;EAAiB;EAAgB;;;;;;qBAchD;;qBAmEA,mBAAmB;;qBA8DnB,iBAAe;;;;;;qBAOf,wBAAsB;;;;;qBAgBtB,kBAAkB;UA2KrB;EACR;EACA;EACA;EACA;EACA,WAAW;EACX,WAAW;;UAkYI;EACf;EACA,MAAM;EACN,OAAO,eAAe,eAAe;EACrC,YAAY;;UAGG;;EAEf,gBAAgB;;EAEhB,eAAe;;EAEf,aAAa,eAAe;;iBAGd,oBAAoB,UAAS,kBAAuB;;;qBCpvBvD;UAEI;EACf;;EAEA;EACA,QAAQ;;;wBAIM,cAAc;wBAYd,gBAAgB,eAAgC;;;UCzB/C;EACf;EACA;;;;;;;;wBASc,gBACd,QAAQ,yBACR,aAAY,0BACX"}