@wrongstack/techstack 0.289.0

package/dist/policy/status.d.ts

@@ -0,0 +1,60 @@
+/**
+ * TechStack — Status classification policy.
+ *
+ * Classifies a DependencyObservation's status based on registry metadata,
+ * advisory data, and version comparison rules.
+ *
+ * Key contracts (per SDD R8/R9):
+ * - Private/unresolved (404/401) → `private_or_unresolved` (never `dead` or `deprecated`)
+ * - Offline/failed lookup → `unknown` (never `current`)
+ * - Registry says deprecated → `deprecated`
+ * - Registry says yanked → `yanked`
+ * - Advisory found → `vulnerable`
+ *
+ * @see docs/specs/techstack-sdd.md §7, R8, R9
+ */
+import type { DependencyObservation, DependencyStatus, Evidence } from '../types.js';
+/** Registry metadata used for status classification. */
+export interface RegistryStatusData {
+    readonly latestStable?: string | undefined;
+    readonly deprecated?: boolean | undefined;
+    readonly yanked?: boolean | undefined;
+    /** Whether the registry lookup resulted in a 404/401 (private/unresolved). */
+    readonly privateOrUnresolved?: boolean | undefined;
+    /** Whether the registry lookup failed due to network error / timeout / offline. */
+    readonly lookupFailed?: boolean | undefined;
+    /** The evidence from the registry lookup. */
+    readonly evidence?: readonly Evidence[] | undefined;
+}
+/** Advisory data used for status classification. */
+export interface AdvisoryStatusData {
+    /** Whether any advisory was found for this dependency. */
+    readonly hasAdvisory: boolean;
+    /** The evidence from the advisory lookup. */
+    readonly evidence?: readonly Evidence[] | undefined;
+}
+/**
+ * Compare two semver-like version strings.
+ * Returns -1 if a < b, 0 if a == b, 1 if a > b.
+ * Handles prerelease tags per semver: `1.0.0-alpha < 1.0.0`.
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Classify a dependency's status based on its current data plus optional
+ * registry metadata and advisory information.
+ *
+ * @param dep - The dependency observation from the inventory pass.
+ * @param registryData - Optional registry metadata (from lookupRegistry).
+ * @param advisoryData - Optional advisory data (from OSV or native audit).
+ * @returns The classified DependencyStatus.
+ */
+export declare function classifyStatus(dep: Pick<DependencyObservation, 'name' | 'sourceType' | 'status' | 'locked' | 'requested'>, registryData?: RegistryStatusData, advisoryData?: AdvisoryStatusData): DependencyStatus;
+/**
+ * Create a registry status data object indicating a private/unresolved package.
+ */
+export declare function privateOrUnresolvedStatus(source: string, detail?: string): RegistryStatusData;
+/**
+ * Create a registry status data object indicating a failed/offline lookup.
+ */
+export declare function failedLookupStatus(source: string, error?: string): RegistryStatusData;
+//# sourceMappingURL=status.d.ts.map

package/dist/policy/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/policy/status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIrF,wDAAwD;AACxD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,8EAA8E;IAC9E,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACnD,mFAAmF;IACnF,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5C,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,QAAQ,EAAE,GAAG,SAAS,CAAC;CACrD;AAED,oDAAoD;AACpD,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,QAAQ,EAAE,GAAG,SAAS,CAAC;CACrD;AAWD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CA6C5D;AAqED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,IAAI,CAAC,qBAAqB,EAAE,MAAM,GAAG,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,CAAC,EAC3F,YAAY,CAAC,EAAE,kBAAkB,EACjC,YAAY,CAAC,EAAE,kBAAkB,GAChC,gBAAgB,CAkFlB;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,GACd,kBAAkB,CAYpB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,MAAM,GACb,kBAAkB,CAYpB"}

package/dist/registry/client.d.ts

@@ -0,0 +1,61 @@
+/**
+ * TechStack — Registry metadata HTTP client.
+ *
+ * Per-ecosystem registry API clients built on Node's built-in https module.
+ * Features: in-memory cache with ETag/TTL, per-host concurrency limit (max 3),
+ * exponential backoff on 429/5xx responses.
+ *
+ * @see docs/specs/techstack-sdd.md §5, §6
+ */
+export interface RegistryEntry {
+    readonly latestStable?: string | undefined;
+    readonly license?: string | undefined;
+    readonly deprecated?: boolean | undefined;
+    readonly yanked?: boolean | undefined;
+    readonly retrievedAt: string;
+    readonly source: string;
+}
+export interface CacheEntry {
+    readonly data: RegistryEntry;
+    readonly etag?: string | undefined;
+    readonly expiresAt: number;
+}
+export interface HostConcurrency {
+    active: number;
+    readonly queue: Array<() => void>;
+}
+/**
+ * Parse an npm packument into a {@link RegistryEntry}.
+ *
+ * Exported so the deprecation rule is unit-testable without a network round
+ * trip — it was untested, and drifted into flagging most of the ecosystem dead.
+ */
+export declare function parseNpmPackument(json: Record<string, unknown>, name: string): RegistryEntry;
+export interface RegistryLookupOptions {
+    /** Abort signal for cancellation. */
+    readonly signal?: AbortSignal | undefined;
+    /** Bypass cache and force a fresh lookup. */
+    readonly force?: boolean | undefined;
+}
+/**
+ * Look up registry metadata for a package in a given ecosystem.
+ *
+ * Returns `undefined` on 404/401 (private/unresolved package).
+ * Throws on network errors (timeout, DNS failure).
+ */
+export declare function lookupRegistry(ecosystem: string, name: string, options?: RegistryLookupOptions): Promise<RegistryEntry | undefined>;
+/**
+ * Look up registry metadata for multiple packages in the same ecosystem.
+ * Uses the same per-host concurrency limit for the batch.
+ */
+export declare function lookupRegistryBatch(ecosystem: string, names: readonly string[], options?: RegistryLookupOptions): Promise<Map<string, RegistryEntry | undefined>>;
+/**
+ * Get the list of supported ecosystem IDs for registry lookups.
+ */
+export declare function supportedRegistryEcosystems(): string[];
+/**
+ * Clear the in-memory registry cache.
+ * Useful for testing and when force-refreshing.
+ */
+export declare function clearRegistryCache(): void;
+//# sourceMappingURL=client.d.ts.map

package/dist/registry/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/registry/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;CACnC;AA8JD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CA0B5F;AAgKD,MAAM,WAAW,qBAAqB;IACpC,qCAAqC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAiFpC;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,CAAC,CAAC,CAoBjD;AAED;;GAEG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,EAAE,CAEtD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC"}

package/dist/registry/purl.d.ts

@@ -0,0 +1,106 @@
+/**
+ * TechStack — Package URL (PURL) construction and parsing.
+ *
+ * PURL spec: https://github.com/package-url/purl-spec
+ *
+ * Every dependency that comes from a registry gets a PURL identifier
+ * so it can be matched across ecosystems, deduplicated in aggregate views,
+ * and queried against OSV's /v1/querybatch endpoint.
+ *
+ * @see docs/specs/techstack-sdd.md §4.1, §5
+ */
+import type { EcosystemId } from '../types.js';
+/**
+ * Parsed PURL components.
+ */
+export interface PurlParts {
+    readonly type: string;
+    readonly namespace?: string | undefined;
+    readonly name: string;
+    readonly version?: string | undefined;
+    readonly qualifiers?: ReadonlyMap<string, string> | undefined;
+    readonly subpath?: string | undefined;
+}
+/**
+ * Build a PURL string from components.
+ *
+ * @example
+ * buildPurl({ type: 'npm', name: 'react', version: '19.1.0' })
+ * // → 'pkg:npm/react@19.1.0'
+ *
+ * buildPurl({ type: 'npm', namespace: '@types', name: 'node', version: '22.0.0' })
+ * // → 'pkg:npm/%40types/node@22.0.0'
+ *
+ * buildPurl({ type: 'maven', namespace: 'org.springframework', name: 'spring-core', version: '6.2.7' })
+ * // → 'pkg:maven/org.springframework/spring-core@6.2.7'
+ *
+ * buildPurl({ type: 'pypi', name: 'django', version: '5.2' })
+ * // → 'pkg:pypi/django@5.2'
+ */
+export declare function buildPurl(parts: PurlParts): string;
+/**
+ * Parse a PURL string into its components.
+ * Returns undefined for malformed PURLs.
+ *
+ * @example
+ * parsePurl('pkg:npm/react@19.1.0')
+ * // → { type: 'npm', name: 'react', version: '19.1.0' }
+ *
+ * parsePurl('pkg:maven/org.springframework/spring-core@6.2.7')
+ * // → { type: 'maven', namespace: 'org.springframework', name: 'spring-core', version: '6.2.7' }
+ */
+export declare function parsePurl(purl: string): PurlParts | undefined;
+/**
+ * Get the PURL type string for an ecosystem.
+ */
+export declare function purlTypeForEcosystem(ecosystem: EcosystemId): string;
+/**
+ * Get the ecosystem id for a PURL type string.
+ * Returns undefined for unknown types.
+ */
+export declare function ecosystemForPurlType(type: string): EcosystemId | undefined;
+/**
+ * Construct a PURL string for a dependency in a given ecosystem.
+ *
+ * This is the spec-required convenience constructor. It composes the richer
+ * `buildPurl` primitive with per-ecosystem namespace splitting so callers can
+ * pass `name` in the ecosystem-native form (e.g. `"@types/node"` for npm
+ * scoped packages, or `"org.springframework/spring-core"` for Maven groupId).
+ *
+ * Special-case: Go module paths (`github.com/gorilla/mux`) are written as a
+ * single un-encoded name — the PURL spec treats `/` as the namespace
+ * separator for most ecosystems but Go module paths use literal `/`s.
+ *
+ * @example
+ * constructPurl('npm', 'react', '19.1.0')          // → 'pkg:npm/react@19.1.0'
+ * constructPurl('npm', '@types/node', '22.0.0')   // → 'pkg:npm/%40types/node@22.0.0'
+ * constructPurl('pypi', 'django', '5.2')           // → 'pkg:pypi/django@5.2'
+ * constructPurl('maven', 'org.springframework/spring-core', '6.2.7')
+ *                                                // → 'pkg:maven/org.springframework/spring-core@6.2.7'
+ * constructPurl('go', 'github.com/gorilla/mux', '1.8.1')
+ *                                                // → 'pkg:golang/github.com/gorilla/mux@1.8.1'
+ */
+export declare function constructPurl(ecosystem: EcosystemId, name: string, version?: string): string;
+/**
+ * Parse a PURL string back into the ecosystem-shaped parts used by the
+ * TechStack dependency model: ecosystem id, package name, and optional version.
+ *
+ * The npm scope and Maven groupId are folded back into `name` so the returned
+ * shape matches `constructPurl`'s inputs (round-trippable).
+ *
+ * Returns `undefined` for malformed PURLs or PURL types that don't map to a
+ * TechStack ecosystem.
+ *
+ * @example
+ * parsePurl('pkg:npm/%40types/node@22.0.0')  // → { ecosystem:'npm', name:'@types/node', version:'22.0.0' }
+ * parsePurl('pkg:pypi/django@5.2')          // → { ecosystem:'python', name:'django', version:'5.2' }
+ * parsePurl('pkg:npm/react')                // → { ecosystem:'npm', name:'react' }
+ * parsePurl('not-a-purl')                   // → undefined
+ */
+export interface ParsedEcosystemPurl {
+    readonly ecosystem: EcosystemId;
+    readonly name: string;
+    readonly version?: string | undefined;
+}
+export declare function parsePurlEcosystem(purl: string): ParsedEcosystemPurl | undefined;
+//# sourceMappingURL=purl.d.ts.map

package/dist/registry/purl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"purl.d.ts","sourceRoot":"","sources":["../../src/registry/purl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAC9D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAwCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAyBlD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAyE7D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,WAAW,GAAG,MAAM,CAEnE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAE1E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,WAAW,EACtB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CA+BR;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAYhF"}

package/dist/remediation.d.ts

@@ -0,0 +1,54 @@
+/**
+ * TechStack — Remediation planning.
+ *
+ * Generates dry-run upgrade plans from a snapshot's findings. NEVER mutates
+ * dependency files — the plan is read-only output that the user must
+ * explicitly approve before any `language_package` or `install` tool runs.
+ *
+ * @see docs/specs/techstack-sdd.md §2 (R25), §9
+ */
+import type { Finding, Snapshot } from './types.js';
+export interface UpgradePlanItem {
+    readonly dependencyName: string;
+    readonly ecosystem: string;
+    readonly workspaceId: string;
+    readonly currentVersion: string | undefined;
+    readonly targetVersion: string | undefined;
+    readonly action: Finding['action'];
+    readonly severity: Finding['severity'];
+    readonly rationale: string;
+    readonly breakingRisk: string | undefined;
+    /** Command suggestion (informational only — never auto-executed). */
+    readonly suggestedCommand: string | undefined;
+}
+export interface UpgradePlan {
+    readonly snapshotId: string;
+    readonly generatedAt: string;
+    readonly items: readonly UpgradePlanItem[];
+    readonly summary: {
+        readonly total: number;
+        readonly patch: number;
+        readonly minor: number;
+        readonly major: number;
+        readonly replace: number;
+        readonly remove: number;
+        readonly investigate: number;
+    };
+    readonly warning: string;
+}
+/**
+ * Generate a dry-run upgrade plan from a snapshot.
+ *
+ * This function is **read-only** — it never touches manifests, lockfiles,
+ * or the filesystem. It only reads the snapshot's findings and produces
+ * a structured plan the user can review.
+ *
+ * @param snapshot The enriched snapshot to plan from.
+ * @returns A structured upgrade plan.
+ */
+export declare function generateUpgradePlan(snapshot: Snapshot): UpgradePlan;
+/**
+ * Render an upgrade plan as Markdown for the report endpoint or CLI display.
+ */
+export declare function renderPlanMarkdown(plan: UpgradePlan): string;
+//# sourceMappingURL=remediation.d.ts.map

package/dist/remediation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remediation.d.ts","sourceRoot":"","sources":["../src/remediation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAyB,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,qEAAqE;IACrE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/C;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;KAC9B,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAsCD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,WAAW,CA4DnE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAoD5D"}

package/dist/research/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * TechStack — research stage barrel.
+ *
+ * @see docs/specs/techstack-sdd.md §31, §557
+ */
+export { createResearcher, type CreateResearcherOptions } from './researcher.js';
+export { createProviderLlm, parseResearchJson, type LlmAccessor } from './llm.js';
+export { createToolSearch, type SearchToolOptions } from './search.js';
+export { clusterCandidates, triageCandidates, DEFAULT_TRIAGE_LIMIT, type TriageOptions, } from './triage.js';
+export type { ResearchCluster, ResearchLlm, ResearchLlmRequest, ResearchOptions, ResearchSearch, ResearchSearchResult, TechStackResearcher, TriageCandidate, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/research/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/research/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AACjF,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAClF,OAAO,EAAE,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,GAChB,MAAM,YAAY,CAAC"}

package/dist/research/llm.d.ts

@@ -0,0 +1,37 @@
+/**
+ * TechStack — `Provider` → {@link ResearchLlm} adapter.
+ *
+ * Mirrors the capability-probing pattern established by the WebUI completion
+ * handler (`packages/webui-server/src/server/completion-handlers.ts`,
+ * `loadLlmSuggestions`): prefer strict structured output, fall back to JSON
+ * mode, fall back again to prompt-only discipline. Providers differ, and a
+ * research pass must not be exclusive to the ones with schema support.
+ *
+ * @see docs/specs/techstack-sdd.md §4.2
+ */
+import type { Provider } from '@wrongstack/core';
+import type { ResearchLlm } from './types.js';
+/** How the caller reaches a live provider. A getter, not a captured value —
+ * the user can switch model or rotate credentials mid-session, and a snapshot
+ * of the provider would silently go stale. */
+export type LlmAccessor = () => {
+    provider: Provider;
+    model: string;
+} | undefined;
+/**
+ * Build a {@link ResearchLlm} from a provider accessor, or `undefined` when no
+ * provider is currently wired — which is the signal `TechStackEngine` uses to
+ * skip the research stage entirely and stay a deterministic tool.
+ */
+export declare function createProviderLlm(accessor: LlmAccessor, options?: {
+    readonly timeoutMs?: number | undefined;
+}): ResearchLlm | undefined;
+/**
+ * Parse a research response into a plain object, or `null` when the model
+ * returned something unusable.
+ *
+ * Never throws: an unparseable research response degrades that cluster to zero
+ * findings, it does not fail the analyze job.
+ */
+export declare function parseResearchJson(text: string): Record<string, unknown> | null;
+//# sourceMappingURL=llm.d.ts.map

package/dist/research/llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../src/research/llm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAW,MAAM,kBAAkB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAsB,MAAM,YAAY,CAAC;AAElE;;8CAE8C;AAC9C,MAAM,MAAM,WAAW,GAAG,MAAM;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC;AAIlF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,WAAW,EACrB,OAAO,GAAE;IAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAO,GACxD,WAAW,GAAG,SAAS,CAgDzB;AA2BD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAU9E"}

package/dist/research/researcher.d.ts

@@ -0,0 +1,31 @@
+/**
+ * TechStack — the research stage.
+ *
+ * Takes the deterministic snapshot's problem cases (see `triage.ts`), gathers
+ * public context for them via web search, and asks the LLM the one question
+ * the registry cannot answer: *what should I actually do about this?*
+ *
+ * Structure follows SDD §557 — one pass per finding-type cluster
+ * (breaking-change / replacement / CVE-applicability), not one per package and
+ * not one per ecosystem. That keeps the call count at ≤3 per analyze while
+ * still letting each prompt be a focused specialist.
+ *
+ * @see docs/specs/techstack-sdd.md §31, §472, §557
+ */
+import type { ResearchLlm, ResearchSearch, TechStackResearcher } from './types.js';
+export interface CreateResearcherOptions {
+    readonly llm: ResearchLlm;
+    readonly search: ResearchSearch;
+    /** Injectable clock — keeps evidence timestamps deterministic in tests. */
+    readonly now?: (() => Date) | undefined;
+}
+/**
+ * Build a {@link TechStackResearcher} over the injected LLM and search ports.
+ *
+ * Failure policy throughout: a cluster that throws contributes zero findings
+ * and does not disturb its siblings. Research is enrichment — a provider
+ * outage or a dry search must degrade the report, never fail the analyze job
+ * that already produced a complete deterministic inventory.
+ */
+export declare function createResearcher(options: CreateResearcherOptions): TechStackResearcher;
+//# sourceMappingURL=researcher.d.ts.map

package/dist/research/researcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"researcher.d.ts","sourceRoot":"","sources":["../../src/research/researcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAEV,WAAW,EAEX,cAAc,EAEd,mBAAmB,EAEpB,MAAM,YAAY,CAAC;AA0SpB,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;CACzC;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,mBAAmB,CAmDtF"}

package/dist/research/search.d.ts

@@ -0,0 +1,19 @@
+/**
+ * TechStack — `searchTool` → {@link ResearchSearch} adapter.
+ *
+ * Wraps the built-in web search (`packages/tools/src/search.ts`) so the
+ * researcher depends on a one-function port rather than the tool contract.
+ *
+ * Note on reliability: that tool scrapes DuckDuckGo/Google/Bing through
+ * `guardedFetch` — there is no API key and no SLA. It can and does return
+ * nothing. Every failure here resolves to `[]` so a dry search degrades a
+ * finding to registry-only evidence instead of failing the analyze job.
+ */
+import type { ResearchSearch } from './types.js';
+export interface SearchToolOptions {
+    readonly numResults?: number | undefined;
+    readonly source?: 'duckduckgo' | 'google' | 'bing' | undefined;
+}
+/** Build a {@link ResearchSearch} backed by the built-in `search` tool. */
+export declare function createToolSearch(options?: SearchToolOptions): ResearchSearch;
+//# sourceMappingURL=search.d.ts.map

package/dist/research/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/research/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAwB,MAAM,YAAY,CAAC;AAavE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;CAChE;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,iBAAsB,GAAG,cAAc,CA2BhF"}

package/dist/research/triage.d.ts

@@ -0,0 +1,33 @@
+/**
+ * TechStack — Deterministic research triage.
+ *
+ * Decides *which* dependencies are worth an LLM call. No LLM, no network.
+ *
+ * This is the stage that makes research affordable: a monorepo resolves
+ * thousands of dependencies, the overwhelming majority of which are `current`
+ * and need no interpretation at all. Only statuses where the registry has
+ * already told us something is wrong — but not what to do about it — earn a
+ * research slot.
+ *
+ * @see docs/specs/techstack-sdd.md §31, §557
+ */
+import type { DependencyObservation } from '../types.js';
+import type { ResearchCluster, TriageCandidate } from './types.js';
+/** Default cap on researched packages. Keeps a full analyze bounded. */
+export declare const DEFAULT_TRIAGE_LIMIT = 40;
+export interface TriageOptions {
+    /** Max candidates returned. Defaults to {@link DEFAULT_TRIAGE_LIMIT}. */
+    readonly limit?: number | undefined;
+}
+/**
+ * Select and rank the dependencies worth researching.
+ *
+ * Ordering is fully deterministic — priority, then name, then version — so the
+ * same snapshot always triages identically. Ties resolve by name rather than
+ * by input order because adapter output order is not itself guaranteed stable
+ * across platforms, and a wobbling triage would make the cap non-reproducible.
+ */
+export declare function triageCandidates(dependencies: readonly DependencyObservation[], options?: TriageOptions): readonly TriageCandidate[];
+/** Group triaged candidates by cluster, preserving triage order within each. */
+export declare function clusterCandidates(candidates: readonly TriageCandidate[]): ReadonlyMap<ResearchCluster, readonly TriageCandidate[]>;
+//# sourceMappingURL=triage.d.ts.map

package/dist/research/triage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"triage.d.ts","sourceRoot":"","sources":["../../src/research/triage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAoB,MAAM,aAAa,CAAC;AAC3E,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEnE,wEAAwE;AACxE,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAsDvC,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,SAAS,qBAAqB,EAAE,EAC9C,OAAO,GAAE,aAAkB,GAC1B,SAAS,eAAe,EAAE,CAoC5B;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,SAAS,eAAe,EAAE,GACrC,WAAW,CAAC,eAAe,EAAE,SAAS,eAAe,EAAE,CAAC,CAQ1D"}

package/dist/research/types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * TechStack — Research stage contracts.
+ *
+ * The research stage is the "agents for interpretation" half of the SDD's
+ * guiding principle (§31): the inventory, version comparison, and advisory
+ * matching are deterministic; the LLM only answers contextual questions the
+ * registry cannot ("is this major bump breaking?", "what replaces this dead
+ * package?", "does this CVE apply to how we use it?").
+ *
+ * Everything here is expressed as a narrow injected port so the engine stays
+ * unit-testable with fakes and `packages/techstack` never reaches for a live
+ * provider or the network on its own.
+ *
+ * @see docs/specs/techstack-sdd.md §4.2, §31, §472, §557
+ */
+import type { DependencyObservation, Finding } from '../types.js';
+/**
+ * Research clusters, per SDD §557 — group by finding-type rather than by
+ * ecosystem so one prompt can answer one kind of question well, and the agent
+ * count stays bounded regardless of how many ecosystems the repo mixes.
+ */
+export type ResearchCluster = 'breaking_change' | 'replacement' | 'vulnerability';
+/** A dependency selected by triage, with the question it needs answered. */
+export interface TriageCandidate {
+    readonly dependency: DependencyObservation;
+    readonly cluster: ResearchCluster;
+    /** Higher runs first and survives the cap. Deterministic — see `triage.ts`. */
+    readonly priority: number;
+}
+/** One web-search hit. Mirrors the shape `searchTool` returns. */
+export interface ResearchSearchResult {
+    readonly title: string;
+    readonly url: string;
+    readonly snippet: string;
+}
+/**
+ * Web search port. Implementations must resolve to `[]` rather than throw —
+ * search is scraped best-effort (`packages/tools/src/search.ts` has no API
+ * key and can legitimately return nothing), and a dry search must degrade the
+ * finding, never fail the job.
+ */
+export type ResearchSearch = (query: string, opts: {
+    readonly signal?: AbortSignal | undefined;
+}) => Promise<readonly ResearchSearchResult[]>;
+/** A single structured LLM request. */
+export interface ResearchLlmRequest {
+    readonly system: string;
+    readonly prompt: string;
+    /** JSON Schema the response should conform to, when the provider supports it. */
+    readonly schema: Record<string, unknown>;
+    readonly schemaName: string;
+    readonly maxTokens: number;
+    readonly signal?: AbortSignal | undefined;
+}
+/**
+ * LLM port. Returns the raw response text (JSON, possibly fenced) — parsing
+ * lives in `llm.ts` so fakes stay trivial to write.
+ */
+export type ResearchLlm = (req: ResearchLlmRequest) => Promise<string>;
+export interface ResearchOptions {
+    readonly signal?: AbortSignal | undefined;
+    readonly onProgress?: ((completed: number, total: number) => void) | undefined;
+}
+/**
+ * The seam `TechStackEngine.analyze()` calls during the `researching` /
+ * `synthesizing` phases.
+ *
+ * Contract: returns *only* `Finding`s. `Finding` structurally cannot carry
+ * `latestStable` / `locked` / `requested`, which is how SDD §472 ("LLM
+ * fabricating version numbers") is enforced by the type system rather than by
+ * review. The engine appends these to `snapshot.findings` and never lets them
+ * touch `snapshot.dependencies`.
+ */
+export interface TechStackResearcher {
+    research(candidates: readonly TriageCandidate[], opts?: ResearchOptions): Promise<readonly Finding[]>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/research/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/research/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAIlE;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,iBAAiB,GAAG,aAAa,GAAG,eAAe,CAAC;AAElF,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAID,kEAAkE;AAClE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,CAC3B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;CAAE,KAChD,OAAO,CAAC,SAAS,oBAAoB,EAAE,CAAC,CAAC;AAE9C,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC3C;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,kBAAkB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAIvE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CAChF;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CACN,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,IAAI,CAAC,EAAE,eAAe,GACrB,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;CAChC"}

package/dist/sbom.d.ts

@@ -0,0 +1,52 @@
+/**
+ * TechStack — SBOM (Software Bill of Materials) export.
+ *
+ * Converts a Snapshot into SPDX or CycloneDX JSON format.
+ *
+ * @see docs/specs/techstack-sdd.md §9
+ */
+import type { Snapshot } from './types.js';
+export interface SpdxDocument {
+    spdxVersion: string;
+    dataLicense: string;
+    SPDXID: string;
+    name: string;
+    documentNamespace: string;
+    creationInfo: {
+        created: string;
+        creators: string[];
+    };
+    packages: Array<{
+        name: string;
+        SPDXID: string;
+        versionInfo?: string | undefined;
+        downloadLocation?: string | undefined;
+        licenseConcluded?: string | undefined;
+    }>;
+}
+export declare function toSpdx(snapshot: Snapshot): SpdxDocument;
+export interface CycloneDXBom {
+    bomFormat: string;
+    specVersion: string;
+    version: number;
+    metadata: {
+        timestamp: string;
+        tools: Array<{
+            name: string;
+            version: string;
+        }>;
+    };
+    components: Array<{
+        type: string;
+        name: string;
+        version?: string | undefined;
+        purl?: string | undefined;
+        licenses?: Array<{
+            license: {
+                id: string;
+            };
+        }> | undefined;
+    }>;
+}
+export declare function toCycloneDX(snapshot: Snapshot): CycloneDXBom;
+//# sourceMappingURL=sbom.d.ts.map

package/dist/sbom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sbom.d.ts","sourceRoot":"","sources":["../src/sbom.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAI3C,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;IACF,QAAQ,EAAE,KAAK,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACjC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACtC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KACvC,CAAC,CAAC;CACJ;AAED,wBAAgB,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,YAAY,CAoBvD;AAID,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE;QACR,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACjD,CAAC;IACF,UAAU,EAAE,KAAK,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC7B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC1B,QAAQ,CAAC,EAAE,KAAK,CAAC;YAAE,OAAO,EAAE;gBAAE,EAAE,EAAE,MAAM,CAAA;aAAE,CAAA;SAAE,CAAC,GAAG,SAAS,CAAC;KAC3D,CAAC,CAAC;CACJ;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,YAAY,CAmB5D"}