@qulib/core 0.7.0 → 0.9.0

package/dist/schemas/views.schema.d.ts

@@ -0,0 +1,234 @@
+/**
+ * 5-View schemas for the qulib Confidence Layer (P3).
+ *
+ * View 1 — Release Confidence: ReleaseConfidenceSchema (defined in confidence.schema.ts).
+ * View 2 — Delivery Traffic: time series of confidence summaries.
+ * View 3 — Inbox: human-judgment items derived from blocking / unknown signals.
+ * View 4 — Replay: provenance chain explaining how a verdict formed.
+ * View 5 — Audit Trail: append-only tamper-evident ledger.
+ *
+ * P3: ships schemas + pure projection functions (buildReplay, deriveInbox, toAuditEntry,
+ *     diffConfidence). Persistence sinks (file/db) and accumulation are deferred to P4.
+ *
+ * All records carry tenantId (CLAUDE.md rule 17 — multi-tenant from day one).
+ */
+import { z } from 'zod';
+export declare const DeliveryTrafficPointSchema: z.ZodObject<{
+    subjectRef: z.ZodString;
+    tenantId: z.ZodDefault<z.ZodString>;
+    computedAt: z.ZodString;
+    confidenceScore: z.ZodNullable<z.ZodNumber>;
+    verdict: z.ZodEnum<["ship", "caution", "hold", "block"]>;
+    /** Change in confidenceScore vs the previous point (null when no prior exists). */
+    deltaFromPrev: z.ZodNullable<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    computedAt: string;
+    tenantId: string;
+    confidenceScore: number | null;
+    verdict: "ship" | "caution" | "hold" | "block";
+    subjectRef: string;
+    deltaFromPrev: number | null;
+}, {
+    computedAt: string;
+    confidenceScore: number | null;
+    verdict: "ship" | "caution" | "hold" | "block";
+    subjectRef: string;
+    deltaFromPrev: number | null;
+    tenantId?: string | undefined;
+}>;
+export type DeliveryTrafficPoint = z.infer<typeof DeliveryTrafficPointSchema>;
+export declare const InboxItemKindSchema: z.ZodEnum<["blocker", "unknown-signal", "approval-needed"]>;
+export type InboxItemKind = z.infer<typeof InboxItemKindSchema>;
+export declare const InboxItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    subjectRef: z.ZodString;
+    tenantId: z.ZodDefault<z.ZodString>;
+    kind: z.ZodEnum<["blocker", "unknown-signal", "approval-needed"]>;
+    source: z.ZodEnum<["live-app-quality", "accessibility", "crawl-coverage", "test-automation", "api-coverage", "ci-results", "deploy-metadata", "error-telemetry", "feature-flags", "doc-health", "human-approval", "agent-evidence"]>;
+    summary: z.ZodString;
+    raisedAt: z.ZodString;
+    resolvedAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    source: "accessibility" | "live-app-quality" | "crawl-coverage" | "test-automation" | "api-coverage" | "ci-results" | "deploy-metadata" | "error-telemetry" | "feature-flags" | "doc-health" | "human-approval" | "agent-evidence";
+    summary: string;
+    kind: "blocker" | "unknown-signal" | "approval-needed";
+    tenantId: string;
+    subjectRef: string;
+    raisedAt: string;
+    resolvedAt?: string | undefined;
+}, {
+    id: string;
+    source: "accessibility" | "live-app-quality" | "crawl-coverage" | "test-automation" | "api-coverage" | "ci-results" | "deploy-metadata" | "error-telemetry" | "feature-flags" | "doc-health" | "human-approval" | "agent-evidence";
+    summary: string;
+    kind: "blocker" | "unknown-signal" | "approval-needed";
+    subjectRef: string;
+    raisedAt: string;
+    tenantId?: string | undefined;
+    resolvedAt?: string | undefined;
+}>;
+export type InboxItem = z.infer<typeof InboxItemSchema>;
+export declare const ReplayStepSchema: z.ZodObject<{
+    source: z.ZodEnum<["live-app-quality", "accessibility", "crawl-coverage", "test-automation", "api-coverage", "ci-results", "deploy-metadata", "error-telemetry", "feature-flags", "doc-health", "human-approval", "agent-evidence"]>;
+    tool: z.ZodString;
+    inputRef: z.ZodOptional<z.ZodString>;
+    score: z.ZodNullable<z.ZodNumber>;
+    weight: z.ZodNumber;
+    effectiveWeight: z.ZodNumber;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    cost: z.ZodOptional<z.ZodObject<{
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        inputTokens: number;
+        outputTokens: number;
+    }, {
+        inputTokens: number;
+        outputTokens: number;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    source: "accessibility" | "live-app-quality" | "crawl-coverage" | "test-automation" | "api-coverage" | "ci-results" | "deploy-metadata" | "error-telemetry" | "feature-flags" | "doc-health" | "human-approval" | "agent-evidence";
+    score: number | null;
+    weight: number;
+    tool: string;
+    effectiveWeight: number;
+    durationMs?: number | undefined;
+    inputRef?: string | undefined;
+    cost?: {
+        inputTokens: number;
+        outputTokens: number;
+    } | undefined;
+}, {
+    source: "accessibility" | "live-app-quality" | "crawl-coverage" | "test-automation" | "api-coverage" | "ci-results" | "deploy-metadata" | "error-telemetry" | "feature-flags" | "doc-health" | "human-approval" | "agent-evidence";
+    score: number | null;
+    weight: number;
+    tool: string;
+    effectiveWeight: number;
+    durationMs?: number | undefined;
+    inputRef?: string | undefined;
+    cost?: {
+        inputTokens: number;
+        outputTokens: number;
+    } | undefined;
+}>;
+export type ReplayStep = z.infer<typeof ReplayStepSchema>;
+export declare const ReplayTraceSchema: z.ZodObject<{
+    subjectRef: z.ZodString;
+    computedAt: z.ZodString;
+    steps: z.ZodArray<z.ZodObject<{
+        source: z.ZodEnum<["live-app-quality", "accessibility", "crawl-coverage", "test-automation", "api-coverage", "ci-results", "deploy-metadata", "error-telemetry", "feature-flags", "doc-health", "human-approval", "agent-evidence"]>;
+        tool: z.ZodString;
+        inputRef: z.ZodOptional<z.ZodString>;
+        score: z.ZodNullable<z.ZodNumber>;
+        weight: z.ZodNumber;
+        effectiveWeight: z.ZodNumber;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        cost: z.ZodOptional<z.ZodObject<{
+            inputTokens: z.ZodNumber;
+            outputTokens: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            inputTokens: number;
+            outputTokens: number;
+        }, {
+            inputTokens: number;
+            outputTokens: number;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        source: "accessibility" | "live-app-quality" | "crawl-coverage" | "test-automation" | "api-coverage" | "ci-results" | "deploy-metadata" | "error-telemetry" | "feature-flags" | "doc-health" | "human-approval" | "agent-evidence";
+        score: number | null;
+        weight: number;
+        tool: string;
+        effectiveWeight: number;
+        durationMs?: number | undefined;
+        inputRef?: string | undefined;
+        cost?: {
+            inputTokens: number;
+            outputTokens: number;
+        } | undefined;
+    }, {
+        source: "accessibility" | "live-app-quality" | "crawl-coverage" | "test-automation" | "api-coverage" | "ci-results" | "deploy-metadata" | "error-telemetry" | "feature-flags" | "doc-health" | "human-approval" | "agent-evidence";
+        score: number | null;
+        weight: number;
+        tool: string;
+        effectiveWeight: number;
+        durationMs?: number | undefined;
+        inputRef?: string | undefined;
+        cost?: {
+            inputTokens: number;
+            outputTokens: number;
+        } | undefined;
+    }>, "many">;
+    formula: z.ZodString;
+    finalVerdict: z.ZodEnum<["ship", "caution", "hold", "block"]>;
+}, "strip", z.ZodTypeAny, {
+    steps: {
+        source: "accessibility" | "live-app-quality" | "crawl-coverage" | "test-automation" | "api-coverage" | "ci-results" | "deploy-metadata" | "error-telemetry" | "feature-flags" | "doc-health" | "human-approval" | "agent-evidence";
+        score: number | null;
+        weight: number;
+        tool: string;
+        effectiveWeight: number;
+        durationMs?: number | undefined;
+        inputRef?: string | undefined;
+        cost?: {
+            inputTokens: number;
+            outputTokens: number;
+        } | undefined;
+    }[];
+    computedAt: string;
+    subjectRef: string;
+    formula: string;
+    finalVerdict: "ship" | "caution" | "hold" | "block";
+}, {
+    steps: {
+        source: "accessibility" | "live-app-quality" | "crawl-coverage" | "test-automation" | "api-coverage" | "ci-results" | "deploy-metadata" | "error-telemetry" | "feature-flags" | "doc-health" | "human-approval" | "agent-evidence";
+        score: number | null;
+        weight: number;
+        tool: string;
+        effectiveWeight: number;
+        durationMs?: number | undefined;
+        inputRef?: string | undefined;
+        cost?: {
+            inputTokens: number;
+            outputTokens: number;
+        } | undefined;
+    }[];
+    computedAt: string;
+    subjectRef: string;
+    formula: string;
+    finalVerdict: "ship" | "caution" | "hold" | "block";
+}>;
+export type ReplayTrace = z.infer<typeof ReplayTraceSchema>;
+export declare const AuditEntrySchema: z.ZodObject<{
+    tenantId: z.ZodDefault<z.ZodString>;
+    subjectRef: z.ZodString;
+    computedAt: z.ZodString;
+    confidenceScore: z.ZodNullable<z.ZodNumber>;
+    verdict: z.ZodEnum<["ship", "caution", "hold", "block"]>;
+    evidenceSourceCount: z.ZodNumber;
+    blockers: z.ZodArray<z.ZodString, "many">;
+    schemaVersion: z.ZodLiteral<1>;
+    /** SHA-256 hex digest over the canonical record — tamper-evident. */
+    recordHash: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    computedAt: string;
+    tenantId: string;
+    schemaVersion: 1;
+    confidenceScore: number | null;
+    verdict: "ship" | "caution" | "hold" | "block";
+    blockers: string[];
+    subjectRef: string;
+    evidenceSourceCount: number;
+    recordHash: string;
+}, {
+    computedAt: string;
+    schemaVersion: 1;
+    confidenceScore: number | null;
+    verdict: "ship" | "caution" | "hold" | "block";
+    blockers: string[];
+    subjectRef: string;
+    evidenceSourceCount: number;
+    recordHash: string;
+    tenantId?: string | undefined;
+}>;
+export type AuditEntry = z.infer<typeof AuditEntrySchema>;
+//# sourceMappingURL=views.schema.d.ts.map

package/dist/schemas/views.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"views.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/views.schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB,eAAO,MAAM,0BAA0B;;;;;;IAMrC,mFAAmF;;;;;;;;;;;;;;;;EAEnF,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAM9E,eAAO,MAAM,mBAAmB,6DAA2D,CAAC;AAC5F,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAMxD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAc3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAM5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAM5D,eAAO,MAAM,gBAAgB;;;;;;;;;IAS3B,qEAAqE;;;;;;;;;;;;;;;;;;;;;;EAErE,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/schemas/views.schema.js

@@ -0,0 +1,82 @@
+/**
+ * 5-View schemas for the qulib Confidence Layer (P3).
+ *
+ * View 1 — Release Confidence: ReleaseConfidenceSchema (defined in confidence.schema.ts).
+ * View 2 — Delivery Traffic: time series of confidence summaries.
+ * View 3 — Inbox: human-judgment items derived from blocking / unknown signals.
+ * View 4 — Replay: provenance chain explaining how a verdict formed.
+ * View 5 — Audit Trail: append-only tamper-evident ledger.
+ *
+ * P3: ships schemas + pure projection functions (buildReplay, deriveInbox, toAuditEntry,
+ *     diffConfidence). Persistence sinks (file/db) and accumulation are deferred to P4.
+ *
+ * All records carry tenantId (CLAUDE.md rule 17 — multi-tenant from day one).
+ */
+import { z } from 'zod';
+import { EvidenceSourceKindSchema, ConfidenceVerdictSchema } from './confidence.schema.js';
+// ---------------------------------------------------------------------------
+// View 2 — Delivery Traffic
+// ---------------------------------------------------------------------------
+export const DeliveryTrafficPointSchema = z.object({
+    subjectRef: z.string(),
+    tenantId: z.string().default('default'),
+    computedAt: z.string().datetime(),
+    confidenceScore: z.number().min(0).max(100).nullable(),
+    verdict: ConfidenceVerdictSchema,
+    /** Change in confidenceScore vs the previous point (null when no prior exists). */
+    deltaFromPrev: z.number().nullable(),
+});
+// ---------------------------------------------------------------------------
+// View 3 — Inbox
+// ---------------------------------------------------------------------------
+export const InboxItemKindSchema = z.enum(['blocker', 'unknown-signal', 'approval-needed']);
+export const InboxItemSchema = z.object({
+    id: z.string(),
+    subjectRef: z.string(),
+    tenantId: z.string().default('default'),
+    kind: InboxItemKindSchema,
+    source: EvidenceSourceKindSchema,
+    summary: z.string(),
+    raisedAt: z.string().datetime(),
+    resolvedAt: z.string().datetime().optional(),
+});
+// ---------------------------------------------------------------------------
+// View 4 — Replay
+// ---------------------------------------------------------------------------
+export const ReplayStepSchema = z.object({
+    source: EvidenceSourceKindSchema,
+    tool: z.string(),
+    inputRef: z.string().optional(),
+    score: z.number().min(0).max(100).nullable(),
+    weight: z.number(),
+    effectiveWeight: z.number(),
+    durationMs: z.number().optional(),
+    cost: z
+        .object({
+        inputTokens: z.number(),
+        outputTokens: z.number(),
+    })
+        .optional(),
+});
+export const ReplayTraceSchema = z.object({
+    subjectRef: z.string(),
+    computedAt: z.string().datetime(),
+    steps: z.array(ReplayStepSchema),
+    formula: z.string(),
+    finalVerdict: ConfidenceVerdictSchema,
+});
+// ---------------------------------------------------------------------------
+// View 5 — Audit Trail
+// ---------------------------------------------------------------------------
+export const AuditEntrySchema = z.object({
+    tenantId: z.string().default('default'),
+    subjectRef: z.string(),
+    computedAt: z.string().datetime(),
+    confidenceScore: z.number().min(0).max(100).nullable(),
+    verdict: ConfidenceVerdictSchema,
+    evidenceSourceCount: z.number().int().min(0),
+    blockers: z.array(z.string()),
+    schemaVersion: z.literal(1),
+    /** SHA-256 hex digest over the canonical record — tamper-evident. */
+    recordHash: z.string(),
+});

package/dist/tools/repo/api-surface.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @module tools/repo/api-surface
+ * @packageBoundary @qulib/core
+ *
+ * Evidence-only API surface discovery. Three tiers of confidence:
+ *   Tier1 — OpenAPI / Swagger spec files (YAML or JSON). Only reads `summary` and
+ *            `parameters` from a real spec; never fabricates endpoints.
+ *   Tier2 — Framework route files: Next.js App-Router `route.ts` exports,
+ *            Next.js Pages `pages/api/`, Express router calls from RepoAnalysis.routes,
+ *            Fastify `fastify.{method}`, Hono `app.{method}`, NestJS decorators.
+ *   Tier3 — Opt-in heuristics. Currently: tRPC router definition files.
+ *            Only activated when `options.enableTier3 === true`.
+ *
+ * Every endpoint carries:
+ *   sourceFile  — repo-relative file path that evidence was read from
+ *   sourceTier  — 'openapi' | 'framework' | 'heuristic'
+ *   confidence  — 'high' | 'medium' | 'low'
+ *
+ * NEVER invents endpoints or parameters. When a spec file cannot be parsed,
+ * or a file pattern does not clearly indicate a route, the file is skipped.
+ */
+import type { RepoAnalysis } from '../../schemas/repo-analysis.schema.js';
+export interface DiscoveredEndpoint {
+    /** HTTP method inferred from the source — 'unknown' when ambiguous */
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'unknown';
+    /** Path as extracted from source — may contain framework-specific params like [id] or :id */
+    path: string;
+    /** Repo-relative file path the evidence was read from */
+    sourceFile: string;
+    /** Discovery tier */
+    sourceTier: 'openapi' | 'framework' | 'heuristic';
+    /** Evidence confidence */
+    confidence: 'high' | 'medium' | 'low';
+    /** Human-readable summary from spec, if available (Tier1 only) */
+    summary?: string;
+    /** Parameter names extracted from spec (Tier1 only; never fabricated) */
+    parameterNames?: string[];
+}
+export interface ApiSurface {
+    discoveredAt: string;
+    repoPath: string;
+    endpoints: DiscoveredEndpoint[];
+    /** Number of OpenAPI/Swagger spec files found and successfully parsed */
+    openApiSpecsFound: number;
+    /** Tier3 heuristics were enabled */
+    tier3Enabled: boolean;
+}
+export interface DiscoverApiSurfaceOptions {
+    /** Enable Tier3 heuristic discovery (default false — opt-in) */
+    enableTier3?: boolean;
+}
+export declare function discoverApiSurface(repoPath: string, options?: DiscoverApiSurfaceOptions): Promise<ApiSurface>;
+/**
+ * Variant that also incorporates RepoAnalysis.routes (Express routes already
+ * extracted by scanRepo). Use this when you already have a RepoAnalysis to avoid
+ * double-reading files.
+ */
+export declare function discoverApiSurfaceWithRepo(repoPath: string, repo: RepoAnalysis, options?: DiscoverApiSurfaceOptions): Promise<ApiSurface>;
+//# sourceMappingURL=api-surface.d.ts.map

package/dist/tools/repo/api-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-surface.d.ts","sourceRoot":"","sources":["../../../src/tools/repo/api-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAiC1E,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;IAChE,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,qBAAqB;IACrB,UAAU,EAAE,SAAS,GAAG,WAAW,GAAG,WAAW,CAAC;IAClD,0BAA0B;IAC1B,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAChC,yEAAyE;IACzE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oCAAoC;IACpC,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,yBAAyB;IACxC,gEAAgE;IAChE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAwXD,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,UAAU,CAAC,CAoCrB;AAED;;;;GAIG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,YAAY,EAClB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,UAAU,CAAC,CAQrB"}