@wrongstack/techstack 0.307.1 → 0.308.1

package/dist/policy/resolver.d.ts

@@ -0,0 +1,186 @@
+/**
+ * TechStack — Rulebook Resolver (implementation).
+ *
+ * Pure functions that combine registry evidence (the facts) with a project
+ * rulebook (the policy) into a single `ResolvedTarget` per dependency. The
+ * resolver is called by the engine after Inventory + Enrichment but before
+ * the Analyzer. It does NOT call into the LLM — it only manipulates typed
+ * data. The LLM (advisor) reads the resolver's output as input.
+ *
+ * Determinism: same inputs + same `now` → same output. No I/O and no clock
+ * reads (the caller passes `now`), so tests pin the full decision matrix.
+ *
+ * Decision order (per SDD §1 "deterministic engines for facts"):
+ *   1. `latestStable` missing → `registry_unavailable` (never fabricate)
+ *   2. `banned` match         → `banned_violated` / `banned_unresolved_replacement`
+ *   3. `pinned` match         → `pinned_within_max` / `pinned_above_max`
+ *   4. `deferred` match       → `deferred_until_future` / `deferred_overdue`
+ *   5. `preferred` match      → `preferred_no_status_change`
+ *   6. nothing matched        → `unconstrained`
+ *
+ * @see packages/techstack/src/policy/rulebook.ts — the input shape.
+ * @see packages/techstack/src/policy/status.ts — `compareVersions` is the ONE
+ *      semver comparison primitive reused by `satisfiesRange`.
+ */
+import type { DependencyObservation } from '../types.js';
+import type { BanEntry, DeferEntry, PackageSelector, PinEntry, PreferEntry, Rulebook, VersionRange } from './rulebook.js';
+/**
+ * Why the resolver decided what it decided. One per affected dependency.
+ * The `reason` is a stable identifier — used by tests and by the UI as a
+ * translation key. The `detail` is a human-readable string.
+ */
+export type ResolveReason = 'registry_unavailable' | 'pinned_within_max' | 'pinned_above_max' | 'banned_violated' | 'banned_unresolved_replacement' | 'deferred_until_future' | 'deferred_overdue' | 'preferred_no_status_change' | 'unconstrained';
+/**
+ * Provenance for the rule that drove a decision. Kept separate from the
+ * engine-wide `Evidence` union on purpose: a rulebook hit is policy, not
+ * registry/manifest/audit evidence, and must never be presented as such.
+ */
+export interface RuleEvidence {
+    readonly rule: 'pinned' | 'banned' | 'deferred' | 'preferred';
+    readonly detail: string;
+}
+/**
+ * The single resolved target for one dependency. The resolver produces one
+ * of these per `(dependency, rulebook)` pair. The engine then merges this
+ * into the analyzer's finding stream.
+ */
+export interface ResolvedTarget {
+    readonly dependencyId: string;
+    readonly selectorHits: {
+        readonly pinned: readonly PinEntry[];
+        readonly banned: readonly BanEntry[];
+        readonly deferred: readonly DeferEntry[];
+        readonly preferred: readonly PreferEntry[];
+    };
+    /** The version the rulebook wants, or `undefined` if no rule constrains it. */
+    readonly targetVersion: VersionRange | undefined;
+    /** Whether the evaluated version satisfies the rulebook. */
+    readonly satisfies: boolean;
+    /** Reason for the decision — stable identifier + human detail. */
+    readonly reason: ResolveReason;
+    readonly detail: string;
+    /** Which rule fired and why. Empty for `unconstrained`/`registry_unavailable`. */
+    readonly ruleEvidence: readonly RuleEvidence[];
+}
+/**
+ * Validate a `PackageSelector` against a `(ecosystem, name)` pair.
+ *
+ * Wildcard semantics:
+ *   - `namePattern` uses `*` (any non-`/` sequence) and `**` (any sequence).
+ *   - `selector.ecosystem` is exact match (case-insensitive, trimmed).
+ *   - `selector.name` is exact match (case-insensitive, trimmed).
+ *   - At least one of `name`, `namePattern`, `ecosystem` must be present.
+ *   - An empty selector matches nothing.
+ *   - When both `name` and `namePattern` are present, either may match.
+ *   - An `ecosystem`-only selector matches every package in that ecosystem.
+ */
+export declare function matchesSelector(selector: PackageSelector, ecosystem: string, name: string): boolean;
+/**
+ * Find all rulebook entries that match a `(ecosystem, name)` pair.
+ * Pure function. Used by the advisor to filter the rulebook by context.
+ */
+export declare function findRuleMatches(rulebook: Rulebook, ecosystem: string, name: string): {
+    readonly pinned: readonly PinEntry[];
+    readonly banned: readonly BanEntry[];
+    readonly deferred: readonly DeferEntry[];
+    readonly preferred: readonly PreferEntry[];
+};
+/**
+ * The structured form of a rulebook `VersionRange`. The grammar is the
+ * semver-range subset the engine already understands — it is intentionally
+ * NOT a generic semver-range parser.
+ */
+export type ParsedRange = {
+    readonly kind: 'exact';
+    readonly version: string;
+} | {
+    readonly kind: 'caret';
+    readonly version: string;
+} | {
+    readonly kind: 'tilde';
+    readonly version: string;
+} | {
+    readonly kind: 'comparator';
+    readonly op: '>=' | '<=' | '>' | '<' | '=';
+    readonly version: string;
+} | {
+    readonly kind: 'and';
+    readonly ranges: readonly ParsedRange[];
+} | {
+    readonly kind: 'or';
+    readonly ranges: readonly ParsedRange[];
+};
+export declare class RangeParseError extends Error {
+    readonly input: string;
+    readonly position: number;
+    constructor(input: string, position: number, message: string);
+}
+/**
+ * Parse a `VersionRange` string into a structured range.
+ *
+ * Grammar:
+ *   - exact:      `1.2.3`
+ *   - caret:      `^1.2.3`
+ *   - tilde:      `~1.2.3`
+ *   - comparator: `>=1.2.3` (also `<=`, `>`, `<`, `=`)
+ *   - AND:        `>=1.2.3 <2.0.0` (whitespace-separated)
+ *   - OR:         `^1.2.3 || ^2.0.0`
+ *
+ * Invalid inputs throw `RangeParseError`.
+ */
+export declare function parseRange(input: string): ParsedRange;
+/**
+ * Check whether `version` satisfies `range`. Pure function.
+ * Re-uses `compareVersions` from `policy/status.ts` as the single semver
+ * comparison primitive — including its prerelease tie-break semantics.
+ */
+export declare function satisfiesRange(version: string, range: ParsedRange): boolean;
+/**
+ * Resolve a single dependency against the rulebook. Pure: same inputs +
+ * same `now` → same output. See the decision order in the module header.
+ *
+ * @param dep      Enriched dependency. A missing `latestStable` short-circuits
+ *                 to `registry_unavailable` — the resolver never fabricates.
+ * @param rulebook Optional rulebook. `undefined` → `unconstrained`.
+ * @param now      Reference time for `deferred.until`; the caller passes it
+ *                 to keep this function deterministic.
+ */
+export declare function resolveDependency(dep: DependencyObservation, rulebook: Rulebook | undefined, now: Date): ResolvedTarget;
+/**
+ * Resolve an entire observation list. Non-registry sources (path, git,
+ * system) are always `unconstrained` — the rulebook only addresses registry
+ * packages.
+ */
+export declare function resolveDependencies(dependencies: readonly DependencyObservation[], rulebook: Rulebook | undefined, now: Date): readonly ResolvedTarget[];
+/**
+ * A "summary" of a rulebook across the project. The advisor (LLM) reads
+ * this to know what to recommend; the analyzer adds these as evidence
+ * to its findings. The resolver is the only writer.
+ */
+export interface RulebookSummary {
+    readonly totalPinned: number;
+    readonly totalBanned: number;
+    readonly totalDeferred: number;
+    readonly totalPreferred: number;
+    readonly packageManagerPreference: {
+        readonly ecosystem: string;
+        readonly manager: string;
+    }[];
+    readonly violations: readonly {
+        readonly dependencyId: string;
+        readonly reason: ResolveReason;
+        readonly detail: string;
+    }[];
+    /** Human-readable snapshot of the rulebook, ≤ 4 KiB. */
+    readonly digest: string;
+}
+/**
+ * Build a `RulebookSummary` from a list of resolved targets + the rulebook.
+ * Pure function. The digest is the only string the LLM is allowed to read
+ * verbatim; it MUST NOT contain `latestStable`/version numbers from the
+ * registry (those would be a fabrication risk if the rulebook is stale).
+ *
+ * Contract only — not implemented yet; nothing depends on it today.
+ */
+export type SummarizeRulebook = (rulebook: Rulebook, resolved: readonly ResolvedTarget[]) => RulebookSummary;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/policy/rulebook.d.ts

@@ -0,0 +1,213 @@
+/**
+ * TechStack — Project Rulebook.
+ *
+ * A Rulebook is a deterministic, project-local policy document that overrides
+ * or supplements the registry-driven defaults produced by the TechStack engine.
+ * It exists so that the LLM (`advisor/`) never has to invent policies like
+ * "we pin React 18 because of the EOL fork" — that intent lives in this file,
+ * authored by humans, and consumed by the Resolver as ground truth.
+ *
+ * Design principles (mirrors SDD §1: "deterministic engines for facts, agents for interpretation"):
+ *  - The rulebook is **data**, not code. It is a JSON file under the target project.
+ *  - The rulebook is **read-only** to the engine. The engine proposes changes; humans apply them.
+ *  - The rulebook never sets `latestStable` — that field is always registry evidence.
+ *  - The rulebook only constrains: pin, ban, prefer, defer, and provides an
+ *    `advisorHints` bag for the LLM to read (not write).
+ *
+ * File location (resolution order, first hit wins):
+ *   1. Path passed to `loadRulebook(targetRoot, overridePath)`
+ *   2. `<targetRoot>/.wrongstack/techstack.rulebook.json`
+ *   3. `<targetRoot>/.wrongstack/techstack.rulebook.yaml`
+ *   4. No rulebook → Resolver falls back to "no overrides" mode.
+ *
+ * @see docs/specs/techstack-sdd.md §1, §7
+ * @see packages/techstack/src/policy/resolver.ts — the consumer of this contract.
+ */
+/** A semver-range string. Resolved by `policy/resolver.ts#parseRange`. */
+export type VersionRange = string & {
+    readonly __brand: 'VersionRange';
+};
+/** ISO 8601 timestamp. Used for `defer.until`, `banned.since`, etc. */
+export type IsoDateTime = string & {
+    readonly __brand: 'IsoDateTime';
+};
+/** Wildcard matcher over `(ecosystem, name)` pairs. */
+export interface PackageSelector {
+    readonly ecosystem?: string | undefined;
+    readonly name?: string | undefined;
+    /**
+     * Wildcard glob over the package name. `*` matches any sequence of characters
+     * EXCEPT `/`; `**` matches across path separators. The resolver pins this
+     * down to a concrete matching function.
+     */
+    readonly namePattern?: string | undefined;
+}
+/**
+ * Pin a package to a maximum version (or version range). Updates beyond
+ * `max` are flagged as `blocked_by_constraints` (not `update_available_*`).
+ * The reason is surfaced in advisor output and analyzer rationale.
+ */
+export interface PinEntry {
+    readonly selector: PackageSelector;
+    readonly max: VersionRange;
+    readonly reason: string;
+    /** Review-after date. After this date the rulebook emits a `investigate` finding. */
+    readonly reviewAfter?: IsoDateTime | undefined;
+}
+/**
+ * Ban a package entirely. The resolver emits a `replace` finding using
+ * `replacement` as the migration target when present.
+ */
+export interface BanEntry {
+    readonly selector: PackageSelector;
+    readonly reason: string;
+    readonly replacement?: ReplacementEntry | undefined;
+    /** When the ban took effect; advisory findings are not emitted for usages before this date. */
+    readonly since?: IsoDateTime | undefined;
+}
+/**
+ * Replacement target for a banned package. The Resolver emits a `replace`
+ * finding with `action: 'replace'` and `breakingRisk` derived from the
+ * major-version gap between current and replacement.
+ */
+export interface ReplacementEntry {
+    readonly ecosystem: string;
+    readonly name: string;
+    readonly minVersion?: VersionRange | undefined;
+    readonly notes?: string | undefined;
+}
+/**
+ * Defer an upgrade — the package is intentionally out-of-date and the
+ * upgrade is scheduled. The Resolver tags affected dependencies as
+ * `deferred_intentional` (a new finding kind) and suppresses
+ * `update_available_*` findings until `until`.
+ */
+export interface DeferEntry {
+    readonly selector: PackageSelector;
+    readonly until: IsoDateTime;
+    readonly reason: string;
+    /** Reference key (e.g. "JIRA-1234") for traceability. */
+    readonly ticket?: string | undefined;
+}
+/**
+ * Preferred package — when multiple implementations are valid, the advisor
+ * prefers this one. The Resolver does not change `current` status; only the
+ * advisor's ranking function reads this.
+ */
+export interface PreferEntry {
+    readonly selector: PackageSelector;
+    readonly context: string;
+    /** Optional replacement for a sibling package — e.g. "prefer `vitest` over `jest`". */
+    readonly deprecates?: PackageSelector | undefined;
+}
+/**
+ * Top-level package manager preference. The Resolver cross-references this
+ * with `Workspace.packageManager` and emits a finding when a workspace
+ * disagrees with the rulebook.
+ */
+export interface PackageManagerPreference {
+    readonly npm?: string | undefined;
+    readonly python?: string | undefined;
+    readonly rust?: string | undefined;
+    readonly go?: string | undefined;
+    readonly dotnet?: string | undefined;
+    readonly php?: string | undefined;
+    readonly dart?: string | undefined;
+    readonly java?: string | undefined;
+    readonly ruby?: string | undefined;
+    readonly swift?: string | undefined;
+    readonly elixir?: string | undefined;
+}
+/** Schema version of the rulebook on disk. Bump on breaking changes. */
+export type RulebookSchemaVersion = '1';
+export interface Rulebook {
+    readonly schemaVersion: RulebookSchemaVersion;
+    readonly projectId?: string | undefined;
+    readonly pinned: readonly PinEntry[];
+    readonly banned: readonly BanEntry[];
+    readonly deferred: readonly DeferEntry[];
+    readonly preferred: readonly PreferEntry[];
+    readonly packageManager?: PackageManagerPreference | undefined;
+    /**
+     * Free-form context for the LLM advisor. The Resolver never reads this;
+     * it is exposed verbatim to the advisor at suggestion time.
+     * Constraints: max 8 KiB total, no execution on read.
+     */
+    readonly advisorHints?: string | undefined;
+}
+/** Result of a rulebook load attempt. Never throws for "missing" — only for "malformed". */
+export type LoadRulebookResult = {
+    readonly kind: 'absent';
+} | {
+    readonly kind: 'loaded';
+    readonly rulebook: Rulebook;
+    readonly source: string;
+} | {
+    readonly kind: 'malformed';
+    readonly source: string;
+    readonly errors: readonly string[];
+};
+/**
+ * In-memory file system abstract for the rulebook loader. Tests inject a
+ * deterministic map; production uses `node:fs/promises`.
+ */
+export interface RulebookFileSystem {
+    exists(path: string): Promise<boolean>;
+    readFile(path: string): Promise<string>;
+    stat(path: string): Promise<{
+        readonly size: number;
+    }>;
+}
+/**
+ * Locate and parse a rulebook from the target project tree.
+ *
+ * Resolution order:
+ *   1. `overridePath` (if provided and exists)
+ *   2. `<targetRoot>/.wrongstack/techstack.rulebook.json`
+ *   3. `<targetRoot>/.wrongstack/techstack.rulebook.yaml`
+ *   4. `absent`
+ *
+ * JSON is fully supported. YAML files are detected but reported as
+ * `malformed` with an explanatory error — the vendored minimal YAML parser
+ * is scheduled for P3.1 (`adapters/parse-utils.ts`), not yet available.
+ *
+ * @param targetRoot Absolute path to the analyzed project root.
+ * @param overridePath Optional explicit path to a rulebook file.
+ * @param io File system abstraction; default uses real fs. Tests inject a mock.
+ */
+export declare function loadRulebook(targetRoot: string, overridePath?: string, io?: RulebookFileSystem): Promise<LoadRulebookResult>;
+/**
+ * Validate a parsed rulebook object against `Rulebook`. Returns the list of
+ * human-readable errors. Empty list means valid.
+ *
+ * Schema invariants (any violation is an error):
+ *  - `schemaVersion === '1'`
+ *  - `pinned[].max` is a non-empty version range
+ *  - `pinned[].reason` is non-empty
+ *  - `banned[].reason` is non-empty
+ *  - `deferred[].until` is a valid ISO 8601 timestamp and in the future
+ *  - `advisorHints` ≤ 8192 bytes when serialized
+ *  - Each `selector` reaches at least one of `name`, `namePattern`, `ecosystem`
+ *  - At least one of `pinned`, `banned`, `deferred`, `preferred`,
+ *    `packageManager`, `advisorHints` must be present (a totally empty
+ *    rulebook is treated as "no rulebook" — see `LoadRulebookResult.kind`).
+ */
+export declare function validateRulebook(input: unknown): readonly string[];
+/**
+ * Stable JSON Schema for the rulebook. Authored as a string literal so the
+ * schema travels with the package and can be emitted by tooling.
+ * Implementation: emitted by `scripts/check-rulebook.mjs` at CI time.
+ */
+export declare const RULEBOOK_JSON_SCHEMA: string;
+/**
+ * Match a `(ecosystem, name)` pair against a PackageSelector.
+ * Pure function. Symmetric: `matchesSelector(selector, ecosystem, name)`.
+ */
+export type MatchesSelector = (selector: PackageSelector, ecosystem: string, name: string) => boolean;
+/**
+ * Brand-construction helper for the runtime. Tests that build fixtures
+ * call this so branded types stay opaque.
+ */
+export declare const asVersionRange: (s: string) => VersionRange;
+export declare const asIsoDateTime: (s: string) => IsoDateTime;
+//# sourceMappingURL=rulebook.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/techstack",
-  "version": "0.307.1",
+  "version": "0.308.1",
   "license": "MIT",
   "description": "WrongStack TechStack — cross-language dependency intelligence for the active target project: discover, inventory, enrich, analyze, and report.",
   "repository": {
@@ -26,8 +26,8 @@
     "!dist/**/*.map"
   ],
   "dependencies": {
-    "@wrongstack/core": "0.307.1",
-    "@wrongstack/tools": "0.307.1"
+    "@wrongstack/core": "0.308.1",
+    "@wrongstack/tools": "0.308.1"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",