@trazum/core 1.8.0

package/dist/types.d.ts

@@ -0,0 +1,296 @@
+/** Public types of @trazum/core. */
+import type { RuleChange } from './changes.js';
+import type { Locale, RuleId } from './i18n/types.js';
+import type { PricingCatalogue } from './pricing.js';
+/** How aggressive the deterministic rules are allowed to be. */
+export type RuleLevel = 'safe' | 'aggressive';
+/**
+ * A deterministic rule applied to the mutable text of a prompt.
+ *
+ * The rule carries no copy of its own: its title and rationale live in the
+ * locale catalogues, keyed by `id`. That is what lets the same rule report
+ * itself in any language.
+ */
+export interface Rule {
+    id: RuleId;
+    level: RuleLevel;
+    /** Returns the transformed text and how many times the rule applied. */
+    apply(text: string): {
+        text: string;
+        hits: number;
+    };
+}
+/** A rule after it has run, with its copy already resolved for a locale. */
+export interface RuleResult {
+    id: RuleId;
+    title: string;
+    rationale: string;
+    level: RuleLevel;
+    hits: number;
+    /** Tokens saved attributable to this rule (estimated). */
+    tokensSaved: number;
+    /**
+     * A sample of what this rule actually changed, so an aggressive run can be
+     * reviewed rule by rule. Capped — `hits` carries the true total — and empty
+     * when the change was too large to summarise usefully.
+     */
+    changes: RuleChange[];
+}
+/** Severity of an advisory: the higher it is, the more money is usually at stake. */
+export type AdvisorySeverity = 'info' | 'opportunity' | 'warning';
+/** Every advisory the core can emit. */
+export type AdvisoryId = 'context-overflow' | 'prompt-caching' | 'prompt-caching-not-worth-it' | 'below-cache-minimum' | 'cache-prefix-reorder' | 'batch-api' | 'model-downgrade' | 'output-dominated' | 'promo-pricing' | 'contradictory-instructions' | 'redundant-examples' | 'restated-output-format' | 'movable-output-schema';
+/** A recommendation that does NOT modify the prompt, only informs. */
+export interface Advisory {
+    id: AdvisoryId;
+    severity: AdvisorySeverity;
+    title: string;
+    detail: string;
+    /** Estimated monthly saving in USD if applied. `null` when not quantifiable. */
+    estimatedMonthlyUsd: number | null;
+}
+/** Price of a model, in USD per million tokens. */
+/**
+ * How a provider prices caching and batching.
+ *
+ * These were global constants until models from other providers arrived, and
+ * being global made them quietly wrong: a cache read costs about 10% of the
+ * input price on Anthropic and about 50% on OpenAI. One number for both would
+ * have overstated an OpenAI caching saving fivefold — an invented saving, which
+ * is the one thing this tool must never print.
+ *
+ * Every field is optional and falls back to the Anthropic values, so a model
+ * added without them prices exactly as it did before.
+ */
+export interface CostMultipliers {
+    /** Cache read as a fraction of the input price. */
+    cacheRead?: number;
+    /** Cache write with the short TTL, as a multiple of the input price. */
+    cacheWrite5m?: number;
+    /** Cache write with the long TTL, where the provider offers one. */
+    cacheWrite1h?: number;
+    /**
+     * Batch discount, or `null` where the provider has no batch API. `null` and
+     * `undefined` mean different things here: "there is no batch API" versus
+     * "nobody has said", and only the first should stop the advisory firing.
+     */
+    batch?: number | null;
+}
+/**
+ * How prompt caching is turned on.
+ *
+ * The advice to move stable content into the prefix is the same everywhere,
+ * because prefix caching is prefix caching. What differs is whether you have to
+ * ask for it: telling an OpenAI user to "set cache_control" names a parameter
+ * that does not exist for them.
+ */
+export type CachingMode = 
+/** The caller marks the prefix, e.g. Anthropic's `cache_control`. */
+'explicit'
+/** The provider caches long-enough prefixes with no marker. */
+ | 'automatic'
+/** No prompt caching at all. */
+ | 'none'
+/**
+ * Nobody here knows, and saying so beats guessing.
+ *
+ * A catalogue can now be built from a live source — OpenRouter publishes
+ * price and context window for hundreds of models — and that source publishes
+ * neither whether a model caches nor the minimum prefix it caches at. Both
+ * halves of the caching advisory need those, and that advisory is the largest
+ * saving Trazum reports.
+ *
+ * The two wrong answers are symmetrical. Assume caching works and Trazum
+ * offers a saving that cannot be bought at any price, which is the Mistral
+ * bug in a new costume. Assume it does not and Trazum hides the biggest
+ * saving there is. So: `unknown` fires nothing and the report says the
+ * catalogue does not know, which is a fact the reader can act on.
+ */
+ | 'unknown';
+/**
+ * Capability, without a vendor's ladder in the name.
+ *
+ * `tier` used Anthropic's own names as the generic axis, which reads as nonsense
+ * the moment the model is not Anthropic's — telling somebody on Kimi that their
+ * task "looks like haiku complexity" is a label that means something other than
+ * what it says.
+ */
+export type Capability = 'small' | 'mid' | 'large' | 'frontier' | 'unknown';
+export interface ModelPricing {
+    id: string;
+    displayName: string;
+    /** Who sells it. Used to group the model list and to explain caching. */
+    provider?: string;
+    /** USD per 1M input tokens. */
+    inputPerMTok: number;
+    /** USD per 1M output tokens. */
+    outputPerMTok: number;
+    /** Context window in tokens. */
+    contextWindow: number;
+    /**
+     * Minimum tokens before prompt caching actually caches.
+     *
+     * `null` when the catalogue does not know — see `CachingMode.unknown`. A
+     * number here is a claim about a specific provider's behaviour, and a live
+     * price feed is not a source for it.
+     */
+    cacheMinTokens: number | null;
+    /** How caching is enabled. Defaults to `explicit`. */
+    caching?: CachingMode;
+    /** Provider-specific cache and batch pricing. Defaults to Anthropic's. */
+    multipliers?: CostMultipliers;
+    /**
+     * Whether to offer this model as a cheaper alternative.
+     *
+     * Defaults to true. A model behind a private programme or a waitlist is real
+     * and worth pricing, but recommending a switch to something the reader cannot
+     * buy is advice that wastes their time.
+     */
+    recommendable?: boolean;
+    /** Capability, on a vendor-neutral scale. */
+    capability: Capability;
+    /**
+     * @deprecated Use `capability`. Anthropic's ladder used as a generic axis
+     * stopped making sense once other providers were priced. Kept in step with
+     * `capability` for the whole of 1.x and removed in 2.0 — see VERSIONING.md.
+     */
+    tier: 'haiku' | 'sonnet' | 'opus' | 'frontier' | 'unknown';
+    /** Promotional pricing, when one is running. */
+    promo?: {
+        inputPerMTok: number;
+        outputPerMTok: number;
+        /** ISO date (inclusive) the promotional price applies until. */
+        until: string;
+    };
+    /** Notes relevant to cost calculation. */
+    notes?: string;
+}
+/** Usage scenario used to turn token savings into money. */
+export interface UsageProfile {
+    /** Model the cost is computed against. */
+    model: string;
+    /** Calls per month using this prompt. */
+    callsPerMonth: number;
+    /** Average output tokens per call. */
+    avgOutputTokens: number;
+    /**
+     * Fraction of calls that would reuse the cached prefix (0-1).
+     * Only used by the prompt caching advisory.
+     */
+    cacheHitRate: number;
+    /** If the work tolerates latency, the Batch API costs half. */
+    batchEligible: boolean;
+}
+/** Itemised cost of a scenario. */
+export interface CostBreakdown {
+    inputUsd: number;
+    outputUsd: number;
+    totalUsd: number;
+}
+/** Before/after cost comparison. */
+export interface SavingsReport {
+    model: string;
+    modelDisplayName: string;
+    /** Whether a promotional price is currently being applied. */
+    promoApplied: boolean;
+    perCall: {
+        before: CostBreakdown;
+        after: CostBreakdown;
+    };
+    perMonth: {
+        before: CostBreakdown;
+        after: CostBreakdown;
+    };
+    monthlySavingsUsd: number;
+    /** Percentage saved against the total monthly cost (0-100). */
+    monthlySavingsPct: number;
+}
+/** A slice of the prompt: protected slices are never modified. */
+export interface Segment {
+    kind: 'mutable' | 'protected';
+    /** What kind of protected content this is (for diagnostics). */
+    protection?: ProtectionKind;
+    text: string;
+}
+export type ProtectionKind = 'fenced-code' | 'inline-code' | 'url' | 'placeholder' | 'xml-tag';
+/** Optimisation options. */
+export interface OptimizeOptions {
+    /** `safe` (the default) only applies rules with no semantic risk. */
+    level?: RuleLevel;
+    /** Rule ids to disable. */
+    disableRules?: RuleId[];
+    /** Usage profile used to quantify the saving. */
+    usage?: Partial<UsageProfile>;
+    /** Alternative token counter (e.g. the real token-counting API). */
+    tokenCounter?: TokenCounter;
+    /** Language of the report. Defaults to English. */
+    locale?: Locale;
+    /**
+     * Prices to work from. Defaults to the catalogue bundled with this release.
+     *
+     * Build one with `applyPricingOverlay` when a published price has moved: a
+     * stale price is a wrong number in a budget decision, and correcting it should
+     * not require a library upgrade.
+     */
+    pricing?: PricingCatalogue;
+}
+/** Counts tokens in a text. Synchronous so it can run inside the rule loop. */
+export type TokenCounter = (text: string) => number;
+/** Full result of an optimisation. */
+export interface OptimizationResult {
+    original: string;
+    optimized: string;
+    tokensBefore: number;
+    tokensAfter: number;
+    tokensSaved: number;
+    /** Percentage reduction of input tokens (0-100). */
+    reductionPct: number;
+    rules: RuleResult[];
+    advisories: Advisory[];
+    savings: SavingsReport;
+    usage: UsageProfile;
+    /** Locale the report was rendered in. */
+    locale: Locale;
+    /** How tokens were counted, so the caller knows the margin of error. */
+    tokenSource: 'heuristic' | 'external';
+    /**
+     * Where the prices came from.
+     *
+     * Reported rather than assumed: once prices can be overlaid locally, a figure
+     * from the bundled catalogue and a figure from somebody's JSON file look
+     * identical, and a reader has to be able to tell which they are reading.
+     */
+    pricingSource: {
+        lastReviewed: string;
+        /** Bundled prices an overlay replaced. Empty when none did. */
+        overriddenModels: string[];
+        /** Models an overlay introduced. Empty when none did. */
+        addedModels: string[];
+    };
+    /** Present only when an LLM pass ran. */
+    llm?: LlmRefinement;
+}
+/** Result of the optional LLM pass. */
+export interface LlmRefinement {
+    applied: boolean;
+    /** Why it was not applied, when `applied` is false. */
+    rejectedReason?: string;
+    provider: string;
+    model: string;
+    candidate: string;
+    tokensBefore: number;
+    tokensAfter: number;
+}
+/** Pluggable LLM provider: this is where your own model plugs in. */
+export interface LlmProvider {
+    /** Human-readable name, shown in the report. */
+    name: string;
+    /** Identifier of the model used. */
+    model: string;
+    complete(input: {
+        system: string;
+        user: string;
+    }): Promise<string>;
+}
+export type { Locale, RuleId };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,oCAAoC;AAEpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,gEAAgE;AAChE,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,YAAY,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,SAAS,CAAC;IACjB,wEAAwE;IACxE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD;AAED,4EAA4E;AAC5E,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAED,qFAAqF;AACrF,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;AAElE,wCAAwC;AACxC,MAAM,MAAM,UAAU,GAClB,kBAAkB,GAClB,gBAAgB,GAChB,6BAA6B,GAC7B,qBAAqB,GACrB,sBAAsB,GACtB,WAAW,GACX,iBAAiB,GACjB,kBAAkB,GAClB,eAAe,GACf,4BAA4B,GAC5B,oBAAoB,GACpB,wBAAwB,GACxB,uBAAuB,CAAC;AAE5B,sEAAsE;AACtE,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,UAAU,CAAC;IACf,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,mDAAmD;AACnD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW;AACrB,qEAAqE;AACnE,UAAU;AACZ,+DAA+D;GAC7D,WAAW;AACb,gCAAgC;GAC9B,MAAM;AACR;;;;;;;;;;;;;;GAcG;GACD,SAAS,CAAC;AAEd;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,KAAK,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;AAE5E,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,gCAAgC;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,sDAAsD;IACtD,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,6CAA6C;IAC7C,UAAU,EAAE,UAAU,CAAC;IACvB;;;;OAIG;IACH,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAC3D,gDAAgD;IAChD,KAAK,CAAC,EAAE;QACN,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,gEAAgE;QAChE,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IACF,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,4DAA4D;AAC5D,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,aAAa,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,eAAe,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,mCAAmC;AACnC,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,oCAAoC;AACpC,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE;QAAE,MAAM,EAAE,aAAa,CAAC;QAAC,KAAK,EAAE,aAAa,CAAA;KAAE,CAAC;IACzD,QAAQ,EAAE;QAAE,MAAM,EAAE,aAAa,CAAC;QAAC,KAAK,EAAE,aAAa,CAAA;KAAE,CAAC;IAC1D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,kEAAkE;AAClE,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,SAAS,GAAG,WAAW,CAAC;IAC9B,gEAAgE;IAChE,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,cAAc,GACtB,aAAa,GACb,aAAa,GACb,KAAK,GACL,aAAa,GACb,SAAS,CAAC;AAEd,4BAA4B;AAC5B,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,2BAA2B;IAC3B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAC9B,oEAAoE;IACpE,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED,+EAA+E;AAC/E,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;AAEpD,sCAAsC;AACtC,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,UAAU,EAAE,QAAQ,EAAE,CAAC;IACvB,OAAO,EAAE,aAAa,CAAC;IACvB,KAAK,EAAE,YAAY,CAAC;IACpB,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,WAAW,EAAE,WAAW,GAAG,UAAU,CAAC;IACtC;;;;;;OAMG;IACH,aAAa,EAAE;QACb,YAAY,EAAE,MAAM,CAAC;QACrB,+DAA+D;QAC/D,gBAAgB,EAAE,MAAM,EAAE,CAAC;QAC3B,yDAAyD;QACzD,WAAW,EAAE,MAAM,EAAE,CAAC;KACvB,CAAC;IACF,yCAAyC;IACzC,GAAG,CAAC,EAAE,aAAa,CAAC;CACrB;AAED,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACpE;AAED,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC"}

package/dist/types.js

@@ -0,0 +1,3 @@
+/** Public types of @trazum/core. */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,oCAAoC"}

package/dist/walk.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Finding the prompt files under a directory.
+ *
+ * Three things this deliberately does not do, each because of what it would
+ * mean on a CI runner reading a repository somebody else opened a pull request
+ * against:
+ *
+ * 1. **It does not follow symlinks.** A link is skipped, not resolved. A link
+ *    to `/etc` or to a parent directory turns "check the prompts folder" into
+ *    reading and printing token counts for files outside the project, and a
+ *    link loop turns it into a hang.
+ * 2. **It does not walk without bound.** Depth and file count are capped, and
+ *    hitting the cap is reported rather than silently truncating the list —
+ *    "0 files over budget" and "I stopped looking" must not read the same.
+ * 3. **It does not guess at what a prompt is.** Only the configured extensions
+ *    are read. Everything else is left alone rather than tokenised on the
+ *    chance it might be a prompt.
+ */
+export declare const MAX_WALK_DEPTH = 12;
+export declare const MAX_WALK_FILES = 2000;
+export interface WalkResult {
+    /** Matching files, as paths relative to the root, with `/` separators. */
+    files: string[];
+    /** True when a cap stopped the walk early, so the caller can say so. */
+    truncated: boolean;
+}
+export interface WalkOptions {
+    extensions?: readonly string[];
+    maxFiles?: number;
+    maxDepth?: number;
+}
+/**
+ * Lists prompt files under `root`, relative to it and sorted.
+ *
+ * Sorted because the output is read by humans and compared between runs: a
+ * report whose row order depends on the filesystem's directory order is one
+ * nobody can diff.
+ */
+export declare function walkPrompts(root: string, options?: WalkOptions): Promise<WalkResult>;
+//# sourceMappingURL=walk.d.ts.map

package/dist/walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;GAiBG;AAEH,eAAO,MAAM,cAAc,KAAK,CAAC;AACjC,eAAO,MAAM,cAAc,OAAO,CAAC;AAenC,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,wEAAwE;IACxE,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAwD9F"}

package/dist/walk.js

@@ -0,0 +1,95 @@
+import { readdir } from 'node:fs/promises';
+import { extname, join, relative, sep } from 'node:path';
+import { DEFAULT_EXTENSIONS } from './config-schema.js';
+/**
+ * Finding the prompt files under a directory.
+ *
+ * Three things this deliberately does not do, each because of what it would
+ * mean on a CI runner reading a repository somebody else opened a pull request
+ * against:
+ *
+ * 1. **It does not follow symlinks.** A link is skipped, not resolved. A link
+ *    to `/etc` or to a parent directory turns "check the prompts folder" into
+ *    reading and printing token counts for files outside the project, and a
+ *    link loop turns it into a hang.
+ * 2. **It does not walk without bound.** Depth and file count are capped, and
+ *    hitting the cap is reported rather than silently truncating the list —
+ *    "0 files over budget" and "I stopped looking" must not read the same.
+ * 3. **It does not guess at what a prompt is.** Only the configured extensions
+ *    are read. Everything else is left alone rather than tokenised on the
+ *    chance it might be a prompt.
+ */
+export const MAX_WALK_DEPTH = 12;
+export const MAX_WALK_FILES = 2000;
+/** Directories never worth descending into, and expensive when they are. */
+const SKIPPED_DIRECTORIES = new Set([
+    'node_modules',
+    '.git',
+    '.next',
+    'dist',
+    'build',
+    'coverage',
+    'vendor',
+    '.venv',
+    '__pycache__',
+]);
+/**
+ * Lists prompt files under `root`, relative to it and sorted.
+ *
+ * Sorted because the output is read by humans and compared between runs: a
+ * report whose row order depends on the filesystem's directory order is one
+ * nobody can diff.
+ */
+export async function walkPrompts(root, options = {}) {
+    const extensions = (options.extensions ?? DEFAULT_EXTENSIONS).map((value) => value.toLowerCase());
+    const maxFiles = options.maxFiles ?? MAX_WALK_FILES;
+    const maxDepth = options.maxDepth ?? MAX_WALK_DEPTH;
+    const files = [];
+    let truncated = false;
+    const visit = async (directory, depth) => {
+        if (depth > maxDepth) {
+            truncated = true;
+            return;
+        }
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            // An unreadable directory is skipped rather than fatal: one permission
+            // problem deep in a tree should not throw away the rest of the report.
+            return;
+        }
+        // Sorted here as well as at the end, so the file that trips the cap is the
+        // same one on every run.
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const entry of entries) {
+            if (files.length >= maxFiles) {
+                truncated = true;
+                return;
+            }
+            // Skipped before the type checks: a symlink is never followed, whatever
+            // it points at.
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.name.startsWith('.'))
+                continue;
+            const full = join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (SKIPPED_DIRECTORIES.has(entry.name))
+                    continue;
+                await visit(full, depth + 1);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (!extensions.includes(extname(entry.name).toLowerCase()))
+                continue;
+            files.push(relative(root, full).split(sep).join('/'));
+        }
+    };
+    await visit(root, 0);
+    files.sort();
+    return { files, truncated };
+}
+//# sourceMappingURL=walk.js.map

package/dist/walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.js","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@trazum/core",
+  "version": "1.8.0",
+  "description": "Trazum core: priced advisories for LLM prompts (caching, model tier, batching, schemas), plus deterministic trimming, token counting and pricing.",
+  "license": "MIT",
+  "author": "David Mu\u00f1oz Rey",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Davmunrey/Trazum.git",
+    "directory": "packages/core"
+  },
+  "keywords": [
+    "prompt",
+    "llm",
+    "tokens",
+    "cost",
+    "optimizer",
+    "claude",
+    "openai"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}