@suss/ir-core 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,264 @@
+import { z } from 'zod';
+import { TypeShape, BoundaryBindingSchema, ConfidenceInfoSchema, ConfidenceLevelSchema, ConfidenceSourceSchema, SemanticsSchema, SourceLocationSchema } from './schemas.cjs';
+export { FunctionCallSemanticsSchema, GraphqlOperationSemanticsSchema, GraphqlResolverSemanticsSchema, MessageBusSemanticsSchema, RestSemanticsSchema, RuntimeConfigSemanticsSchema, StorageRelationalSemanticsSchema, TypeShapeSchema } from './schemas.cjs';
+
+/**
+ * Normalize a route path to a canonical form for matching.
+ *
+ * - Converts Express-style params (`:id`) to brace-style (`{id}`)
+ * - Strips trailing slashes (except bare `/`)
+ * - Lowercases the static segments (params stay case-sensitive)
+ */
+declare function normalizePath(path: string): string;
+/**
+ * Compute a stable string key from a boundary binding for grouping.
+ * Dispatches on `semantics.name`:
+ *   - `rest` → `"METHOD /normalized/path"` (null if method or path empty)
+ *   - `graphql-resolver` → `"gql:<TypeName>.<fieldName>"`
+ *   - `function-call` → `"fn:<package>::<exportPath>"` when both
+ *     `package` and `exportPath` are set; other in-process function-call
+ *     units (intra-repo components, bare handlers) return null.
+ *   - everything else → null
+ */
+declare function boundaryKey(binding: BoundaryBinding): string | null;
+
+declare const SuppressionRuleSchema: z.ZodObject<{
+    kind: z.ZodOptional<z.ZodString>;
+    boundary: z.ZodOptional<z.ZodString>;
+    consumer: z.ZodOptional<z.ZodObject<{
+        summary: z.ZodOptional<z.ZodString>;
+        transitionId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    scope: z.ZodDefault<z.ZodEnum<{
+        narrow: "narrow";
+        broad: "broad";
+    }>>;
+    reason: z.ZodString;
+    effect: z.ZodDefault<z.ZodEnum<{
+        mark: "mark";
+        downgrade: "downgrade";
+        hide: "hide";
+    }>>;
+}, z.core.$strict>;
+type SuppressionRule = z.infer<typeof SuppressionRuleSchema>;
+declare const SuppressionFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    rules: z.ZodArray<z.ZodObject<{
+        kind: z.ZodOptional<z.ZodString>;
+        boundary: z.ZodOptional<z.ZodString>;
+        consumer: z.ZodOptional<z.ZodObject<{
+            summary: z.ZodOptional<z.ZodString>;
+            transitionId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        scope: z.ZodDefault<z.ZodEnum<{
+            narrow: "narrow";
+            broad: "broad";
+        }>>;
+        reason: z.ZodString;
+        effect: z.ZodDefault<z.ZodEnum<{
+            mark: "mark";
+            downgrade: "downgrade";
+            hide: "hide";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type SuppressionFile = z.infer<typeof SuppressionFileSchema>;
+type SuppressableSeverity = "error" | "warning" | "info";
+/** The `suppressed` annotation stamped onto a matched finding. */
+interface FindingSuppression {
+    reason: string;
+    effect: "mark" | "downgrade" | "hide";
+    /** Original severity, present only when effect is "downgrade". */
+    originalSeverity?: SuppressableSeverity | undefined;
+}
+/**
+ * The structural base both finding shapes satisfy. Behavioural
+ * `Finding` and intent `IntentFinding` each declare these fields in
+ * their own schemas (kept structurally identical); the pipeline needs
+ * nothing more. The `| undefined` unions match what zod infers for
+ * `.optional()` fields under exactOptionalPropertyTypes.
+ */
+interface SuppressibleFinding {
+    kind: string;
+    severity: SuppressableSeverity;
+    suppressed?: FindingSuppression | undefined;
+}
+/**
+ * Validate that a narrow rule actually constrains *something* — a bare
+ * rule with only `reason` would suppress every finding in the codebase,
+ * which is almost always a mistake. Broad-scope rules deliberately
+ * allow less-specific matching.
+ */
+declare function validateRule(rule: SuppressionRule): string | null;
+/**
+ * Normalize a rule's boundary string to match `boundaryKey`'s output
+ * format. Authors may write "GET /pet/:id" or "GET /pet/{id}"; we
+ * accept either. Method is uppercased; the path goes through
+ * `normalizePath` (colon-to-brace, trailing-slash stripping, lowercase
+ * static segments). Non-REST keys ("fn:...", "gql:...") don't have the
+ * METHOD-space-path shape and are compared verbatim by callers.
+ */
+declare function normalizeRuleBoundary(raw: string): string;
+/**
+ * Does a rule's `boundary` discriminator match a finding's boundary
+ * key? Exact match first (covers "fn:...", "gql:..."), then the
+ * REST-normalized form.
+ */
+declare function ruleBoundaryMatchesKey(ruleBoundary: string, key: string | null): boolean;
+/**
+ * Apply suppression rules to a list of findings. Generic over the
+ * finding shape: `matches` decides whether a rule's discriminators
+ * beyond `kind` (boundary, consumer, ...) match a finding — the kind
+ * check itself is universal and handled here.
+ *
+ * Returns a new array. Findings with `effect: "hide"` are omitted from
+ * the output entirely unless `keepHidden` is set. Findings with
+ * `effect: "mark"` or `"downgrade"` are included with an added
+ * `suppressed` field. First matching rule wins.
+ */
+declare function applySuppressionsToFindings<T extends SuppressibleFinding>(findings: T[], rules: SuppressionRule[], matches: (rule: SuppressionRule, finding: T) => boolean, opts?: {
+    keepHidden?: boolean;
+}): T[];
+/**
+ * `hide` and `mark` findings are excluded from exit-code threshold
+ * calculations; `downgrade` findings count at their post-downgrade
+ * severity. Callers use this to decide whether a finding contributes
+ * to `hasErrors`-style gating.
+ */
+declare function countsForThreshold(finding: SuppressibleFinding): boolean;
+
+/**
+ * Three-valued comparison result:
+ *   - "match"   — `actual` satisfies `declared`
+ *   - "nomatch" — a concrete, verifiable incompatibility exists
+ *   - "unknown" — uncertainty that would mask a real mismatch (spreads,
+ *                 refs, unknown shapes)
+ */
+type MatchResult = "match" | "nomatch" | "unknown";
+/**
+ * Compare an actual body shape against a declared body shape and report
+ * whether the actual satisfies the declared.
+ *
+ * Semantics are asymmetric: `actual` is the produced value (a response
+ * body, a return value) and `declared` is the contract it must conform
+ * to. `unknown` is a soft signal; callers decide whether to surface it.
+ */
+declare function bodyShapesMatch(actual: TypeShape, declared: TypeShape): MatchResult;
+
+type ConfidenceSource = z.infer<typeof ConfidenceSourceSchema>;
+type ConfidenceLevel = z.infer<typeof ConfidenceLevelSchema>;
+type ConfidenceInfo = z.infer<typeof ConfidenceInfoSchema>;
+type SourceLocation = z.infer<typeof SourceLocationSchema>;
+type BoundaryBinding = z.infer<typeof BoundaryBindingSchema>;
+type Semantics = z.infer<typeof SemanticsSchema>;
+type RestSemantics = Extract<Semantics, {
+    name: "rest";
+}>;
+type FunctionCallSemantics = Extract<Semantics, {
+    name: "function-call";
+}>;
+type GraphqlResolverSemantics = Extract<Semantics, {
+    name: "graphql-resolver";
+}>;
+type GraphqlOperationSemantics = Extract<Semantics, {
+    name: "graphql-operation";
+}>;
+type RuntimeConfigSemantics = Extract<Semantics, {
+    name: "runtime-config";
+}>;
+type StorageRelationalSemantics = Extract<Semantics, {
+    name: "storage-relational";
+}>;
+type MessageBusSemantics = Extract<Semantics, {
+    name: "message-bus";
+}>;
+
+/**
+ * Build a REST-semantics binding. `method` and `path` can be empty
+ * strings to signal "not yet resolved" (the adapter's wrapper-expansion
+ * pass uses this); pairing treats empty method/path as unplaced.
+ */
+declare function restBinding(opts: {
+    transport: string;
+    method: string;
+    path: string;
+    recognition: string;
+    declaredResponses?: number[];
+}): BoundaryBinding;
+/**
+ * Build a function-call-semantics binding. Used by in-process packs
+ * (React components, custom-hook boundaries, bare TS function exports).
+ */
+declare function functionCallBinding(opts: {
+    transport: string;
+    recognition: string;
+    module?: string;
+    exportName?: string;
+    package?: string;
+    exportPath?: string[];
+}): BoundaryBinding;
+/**
+ * Build a function-call binding that identifies a public package export
+ * — the provider side of a library boundary. Transport defaults to
+ * `"in-process"` for typical TypeScript library consumption.
+ */
+declare function packageExportBinding(opts: {
+    transport?: string;
+    recognition: string;
+    packageName: string;
+    exportPath: string[];
+}): BoundaryBinding;
+/**
+ * Build a graphql-resolver-semantics binding. Transport varies by
+ * deployment: `"http"` for Apollo Server, `"aws-https"` for AppSync.
+ */
+declare function graphqlResolverBinding(opts: {
+    transport: string;
+    recognition: string;
+    typeName: string;
+    fieldName: string;
+}): BoundaryBinding;
+/**
+ * Build a graphql-operation-semantics binding — the consumer side of a
+ * GraphQL boundary. Anonymous operations leave `operationName` unset.
+ */
+declare function graphqlOperationBinding(opts: {
+    transport: string;
+    recognition: string;
+    operationType: "query" | "mutation" | "subscription";
+    operationName?: string;
+}): BoundaryBinding;
+/**
+ * Build a runtime-config binding — the provider side of a runtime
+ * configuration channel (env vars on a Lambda / ECS task / container /
+ * k8s pod). Transport is `"os"`: env vars are handed to the process by
+ * the OS at startup regardless of the deployment medium.
+ */
+declare function runtimeConfigBinding(opts: {
+    recognition: string;
+    deploymentTarget: "lambda" | "ecs-task" | "container" | "k8s-deployment";
+    instanceName: string;
+}): BoundaryBinding;
+/**
+ * Build a storage-relational binding — the provider side of a
+ * relational storage table. Transport carries the `storageSystem`
+ * value so the layering stays informative without a separate
+ * wire-protocol taxonomy.
+ */
+declare function storageRelationalBinding(opts: {
+    recognition: string;
+    storageSystem: "postgres" | "mysql" | "sqlite";
+    scope: string;
+    table: string;
+}): BoundaryBinding;
+/**
+ * Build a message-bus binding — the boundary between a producer that
+ * sends discrete messages and the consumer(s) that receive them.
+ */
+declare function messageBusBinding(opts: {
+    recognition: string;
+    messageBus: "sqs" | "eventbridge" | "bullmq" | "kafka" | "nats";
+    channel: string;
+}): BoundaryBinding;
+
+export { type BoundaryBinding, BoundaryBindingSchema, type ConfidenceInfo, ConfidenceInfoSchema, type ConfidenceLevel, ConfidenceLevelSchema, type ConfidenceSource, ConfidenceSourceSchema, type FindingSuppression, type FunctionCallSemantics, type GraphqlOperationSemantics, type GraphqlResolverSemantics, type MatchResult, type MessageBusSemantics, type RestSemantics, type RuntimeConfigSemantics, type Semantics, SemanticsSchema, type SourceLocation, SourceLocationSchema, type StorageRelationalSemantics, type SuppressableSeverity, type SuppressibleFinding, type SuppressionFile, SuppressionFileSchema, type SuppressionRule, SuppressionRuleSchema, TypeShape, applySuppressionsToFindings, bodyShapesMatch, boundaryKey, countsForThreshold, functionCallBinding, graphqlOperationBinding, graphqlResolverBinding, messageBusBinding, normalizePath, normalizeRuleBoundary, packageExportBinding, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, storageRelationalBinding, validateRule };

package/dist/index.d.ts

@@ -0,0 +1,264 @@
+import { z } from 'zod';
+import { TypeShape, BoundaryBindingSchema, ConfidenceInfoSchema, ConfidenceLevelSchema, ConfidenceSourceSchema, SemanticsSchema, SourceLocationSchema } from './schemas.js';
+export { FunctionCallSemanticsSchema, GraphqlOperationSemanticsSchema, GraphqlResolverSemanticsSchema, MessageBusSemanticsSchema, RestSemanticsSchema, RuntimeConfigSemanticsSchema, StorageRelationalSemanticsSchema, TypeShapeSchema } from './schemas.js';
+
+/**
+ * Normalize a route path to a canonical form for matching.
+ *
+ * - Converts Express-style params (`:id`) to brace-style (`{id}`)
+ * - Strips trailing slashes (except bare `/`)
+ * - Lowercases the static segments (params stay case-sensitive)
+ */
+declare function normalizePath(path: string): string;
+/**
+ * Compute a stable string key from a boundary binding for grouping.
+ * Dispatches on `semantics.name`:
+ *   - `rest` → `"METHOD /normalized/path"` (null if method or path empty)
+ *   - `graphql-resolver` → `"gql:<TypeName>.<fieldName>"`
+ *   - `function-call` → `"fn:<package>::<exportPath>"` when both
+ *     `package` and `exportPath` are set; other in-process function-call
+ *     units (intra-repo components, bare handlers) return null.
+ *   - everything else → null
+ */
+declare function boundaryKey(binding: BoundaryBinding): string | null;
+
+declare const SuppressionRuleSchema: z.ZodObject<{
+    kind: z.ZodOptional<z.ZodString>;
+    boundary: z.ZodOptional<z.ZodString>;
+    consumer: z.ZodOptional<z.ZodObject<{
+        summary: z.ZodOptional<z.ZodString>;
+        transitionId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    scope: z.ZodDefault<z.ZodEnum<{
+        narrow: "narrow";
+        broad: "broad";
+    }>>;
+    reason: z.ZodString;
+    effect: z.ZodDefault<z.ZodEnum<{
+        mark: "mark";
+        downgrade: "downgrade";
+        hide: "hide";
+    }>>;
+}, z.core.$strict>;
+type SuppressionRule = z.infer<typeof SuppressionRuleSchema>;
+declare const SuppressionFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    rules: z.ZodArray<z.ZodObject<{
+        kind: z.ZodOptional<z.ZodString>;
+        boundary: z.ZodOptional<z.ZodString>;
+        consumer: z.ZodOptional<z.ZodObject<{
+            summary: z.ZodOptional<z.ZodString>;
+            transitionId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        scope: z.ZodDefault<z.ZodEnum<{
+            narrow: "narrow";
+            broad: "broad";
+        }>>;
+        reason: z.ZodString;
+        effect: z.ZodDefault<z.ZodEnum<{
+            mark: "mark";
+            downgrade: "downgrade";
+            hide: "hide";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type SuppressionFile = z.infer<typeof SuppressionFileSchema>;
+type SuppressableSeverity = "error" | "warning" | "info";
+/** The `suppressed` annotation stamped onto a matched finding. */
+interface FindingSuppression {
+    reason: string;
+    effect: "mark" | "downgrade" | "hide";
+    /** Original severity, present only when effect is "downgrade". */
+    originalSeverity?: SuppressableSeverity | undefined;
+}
+/**
+ * The structural base both finding shapes satisfy. Behavioural
+ * `Finding` and intent `IntentFinding` each declare these fields in
+ * their own schemas (kept structurally identical); the pipeline needs
+ * nothing more. The `| undefined` unions match what zod infers for
+ * `.optional()` fields under exactOptionalPropertyTypes.
+ */
+interface SuppressibleFinding {
+    kind: string;
+    severity: SuppressableSeverity;
+    suppressed?: FindingSuppression | undefined;
+}
+/**
+ * Validate that a narrow rule actually constrains *something* — a bare
+ * rule with only `reason` would suppress every finding in the codebase,
+ * which is almost always a mistake. Broad-scope rules deliberately
+ * allow less-specific matching.
+ */
+declare function validateRule(rule: SuppressionRule): string | null;
+/**
+ * Normalize a rule's boundary string to match `boundaryKey`'s output
+ * format. Authors may write "GET /pet/:id" or "GET /pet/{id}"; we
+ * accept either. Method is uppercased; the path goes through
+ * `normalizePath` (colon-to-brace, trailing-slash stripping, lowercase
+ * static segments). Non-REST keys ("fn:...", "gql:...") don't have the
+ * METHOD-space-path shape and are compared verbatim by callers.
+ */
+declare function normalizeRuleBoundary(raw: string): string;
+/**
+ * Does a rule's `boundary` discriminator match a finding's boundary
+ * key? Exact match first (covers "fn:...", "gql:..."), then the
+ * REST-normalized form.
+ */
+declare function ruleBoundaryMatchesKey(ruleBoundary: string, key: string | null): boolean;
+/**
+ * Apply suppression rules to a list of findings. Generic over the
+ * finding shape: `matches` decides whether a rule's discriminators
+ * beyond `kind` (boundary, consumer, ...) match a finding — the kind
+ * check itself is universal and handled here.
+ *
+ * Returns a new array. Findings with `effect: "hide"` are omitted from
+ * the output entirely unless `keepHidden` is set. Findings with
+ * `effect: "mark"` or `"downgrade"` are included with an added
+ * `suppressed` field. First matching rule wins.
+ */
+declare function applySuppressionsToFindings<T extends SuppressibleFinding>(findings: T[], rules: SuppressionRule[], matches: (rule: SuppressionRule, finding: T) => boolean, opts?: {
+    keepHidden?: boolean;
+}): T[];
+/**
+ * `hide` and `mark` findings are excluded from exit-code threshold
+ * calculations; `downgrade` findings count at their post-downgrade
+ * severity. Callers use this to decide whether a finding contributes
+ * to `hasErrors`-style gating.
+ */
+declare function countsForThreshold(finding: SuppressibleFinding): boolean;
+
+/**
+ * Three-valued comparison result:
+ *   - "match"   — `actual` satisfies `declared`
+ *   - "nomatch" — a concrete, verifiable incompatibility exists
+ *   - "unknown" — uncertainty that would mask a real mismatch (spreads,
+ *                 refs, unknown shapes)
+ */
+type MatchResult = "match" | "nomatch" | "unknown";
+/**
+ * Compare an actual body shape against a declared body shape and report
+ * whether the actual satisfies the declared.
+ *
+ * Semantics are asymmetric: `actual` is the produced value (a response
+ * body, a return value) and `declared` is the contract it must conform
+ * to. `unknown` is a soft signal; callers decide whether to surface it.
+ */
+declare function bodyShapesMatch(actual: TypeShape, declared: TypeShape): MatchResult;
+
+type ConfidenceSource = z.infer<typeof ConfidenceSourceSchema>;
+type ConfidenceLevel = z.infer<typeof ConfidenceLevelSchema>;
+type ConfidenceInfo = z.infer<typeof ConfidenceInfoSchema>;
+type SourceLocation = z.infer<typeof SourceLocationSchema>;
+type BoundaryBinding = z.infer<typeof BoundaryBindingSchema>;
+type Semantics = z.infer<typeof SemanticsSchema>;
+type RestSemantics = Extract<Semantics, {
+    name: "rest";
+}>;
+type FunctionCallSemantics = Extract<Semantics, {
+    name: "function-call";
+}>;
+type GraphqlResolverSemantics = Extract<Semantics, {
+    name: "graphql-resolver";
+}>;
+type GraphqlOperationSemantics = Extract<Semantics, {
+    name: "graphql-operation";
+}>;
+type RuntimeConfigSemantics = Extract<Semantics, {
+    name: "runtime-config";
+}>;
+type StorageRelationalSemantics = Extract<Semantics, {
+    name: "storage-relational";
+}>;
+type MessageBusSemantics = Extract<Semantics, {
+    name: "message-bus";
+}>;
+
+/**
+ * Build a REST-semantics binding. `method` and `path` can be empty
+ * strings to signal "not yet resolved" (the adapter's wrapper-expansion
+ * pass uses this); pairing treats empty method/path as unplaced.
+ */
+declare function restBinding(opts: {
+    transport: string;
+    method: string;
+    path: string;
+    recognition: string;
+    declaredResponses?: number[];
+}): BoundaryBinding;
+/**
+ * Build a function-call-semantics binding. Used by in-process packs
+ * (React components, custom-hook boundaries, bare TS function exports).
+ */
+declare function functionCallBinding(opts: {
+    transport: string;
+    recognition: string;
+    module?: string;
+    exportName?: string;
+    package?: string;
+    exportPath?: string[];
+}): BoundaryBinding;
+/**
+ * Build a function-call binding that identifies a public package export
+ * — the provider side of a library boundary. Transport defaults to
+ * `"in-process"` for typical TypeScript library consumption.
+ */
+declare function packageExportBinding(opts: {
+    transport?: string;
+    recognition: string;
+    packageName: string;
+    exportPath: string[];
+}): BoundaryBinding;
+/**
+ * Build a graphql-resolver-semantics binding. Transport varies by
+ * deployment: `"http"` for Apollo Server, `"aws-https"` for AppSync.
+ */
+declare function graphqlResolverBinding(opts: {
+    transport: string;
+    recognition: string;
+    typeName: string;
+    fieldName: string;
+}): BoundaryBinding;
+/**
+ * Build a graphql-operation-semantics binding — the consumer side of a
+ * GraphQL boundary. Anonymous operations leave `operationName` unset.
+ */
+declare function graphqlOperationBinding(opts: {
+    transport: string;
+    recognition: string;
+    operationType: "query" | "mutation" | "subscription";
+    operationName?: string;
+}): BoundaryBinding;
+/**
+ * Build a runtime-config binding — the provider side of a runtime
+ * configuration channel (env vars on a Lambda / ECS task / container /
+ * k8s pod). Transport is `"os"`: env vars are handed to the process by
+ * the OS at startup regardless of the deployment medium.
+ */
+declare function runtimeConfigBinding(opts: {
+    recognition: string;
+    deploymentTarget: "lambda" | "ecs-task" | "container" | "k8s-deployment";
+    instanceName: string;
+}): BoundaryBinding;
+/**
+ * Build a storage-relational binding — the provider side of a
+ * relational storage table. Transport carries the `storageSystem`
+ * value so the layering stays informative without a separate
+ * wire-protocol taxonomy.
+ */
+declare function storageRelationalBinding(opts: {
+    recognition: string;
+    storageSystem: "postgres" | "mysql" | "sqlite";
+    scope: string;
+    table: string;
+}): BoundaryBinding;
+/**
+ * Build a message-bus binding — the boundary between a producer that
+ * sends discrete messages and the consumer(s) that receive them.
+ */
+declare function messageBusBinding(opts: {
+    recognition: string;
+    messageBus: "sqs" | "eventbridge" | "bullmq" | "kafka" | "nats";
+    channel: string;
+}): BoundaryBinding;
+
+export { type BoundaryBinding, BoundaryBindingSchema, type ConfidenceInfo, ConfidenceInfoSchema, type ConfidenceLevel, ConfidenceLevelSchema, type ConfidenceSource, ConfidenceSourceSchema, type FindingSuppression, type FunctionCallSemantics, type GraphqlOperationSemantics, type GraphqlResolverSemantics, type MatchResult, type MessageBusSemantics, type RestSemantics, type RuntimeConfigSemantics, type Semantics, SemanticsSchema, type SourceLocation, SourceLocationSchema, type StorageRelationalSemantics, type SuppressableSeverity, type SuppressibleFinding, type SuppressionFile, SuppressionFileSchema, type SuppressionRule, SuppressionRuleSchema, TypeShape, applySuppressionsToFindings, bodyShapesMatch, boundaryKey, countsForThreshold, functionCallBinding, graphqlOperationBinding, graphqlResolverBinding, messageBusBinding, normalizePath, normalizeRuleBoundary, packageExportBinding, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, storageRelationalBinding, validateRule };