@descryy/runtime-adapter-ruby 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export type { RawRailsFrame } from "./rails-frame-parsing.ts";
+export { createRailsLineClassifier, isRailsHeaderLine, isRailsFrameLine, parseRailsHeader, parseRailsFrame, } from "./rails-frame-parsing.ts";
+export { createRailsStackTraceParser } from "./rails-stack-trace-parser.ts";
+export type { RawSinatraFrame } from "./sinatra-frame-parsing.ts";
+export { createSinatraLineClassifier, isSinatraHeaderLine, isSinatraFrameLine, parseSinatraHeader, parseSinatraFrame, } from "./sinatra-frame-parsing.ts";
+export { createSinatraStackTraceParser } from "./sinatra-stack-trace-parser.ts";
+export type { RawRubyFrame } from "./ruby-frame-parsing.ts";
+export { createRubyLineClassifier, isRubyHeaderLine, isRubyFrameLine, parseRubyHeaderFrame, parseRubyFromFrame, } from "./ruby-frame-parsing.ts";
+export { createRubySourceLocationResolver } from "./ruby-source-location-resolver.ts";
+export { createRubyStackTraceParser } from "./ruby-stack-trace-parser.ts";
+export { createRubyLoggerEnvelope, createRailsTaggedLogEnvelope } from "./ruby-log-envelopes.ts";
+export type { RubyRuntimeAdapterOptions } from "./ruby-runtime-adapter.ts";
+export { createRubyRuntimeAdapter } from "./ruby-runtime-adapter.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,GAChB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAC5E,YAAY,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,6BAA6B,EAAE,MAAM,iCAAiC,CAAC;AAChF,YAAY,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,gCAAgC,EAAE,MAAM,oCAAoC,CAAC;AACtF,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,EAAE,wBAAwB,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAC;AACjG,YAAY,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAC3E,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+export { createRailsLineClassifier, isRailsHeaderLine, isRailsFrameLine, parseRailsHeader, parseRailsFrame, } from "./rails-frame-parsing.js";
+export { createRailsStackTraceParser } from "./rails-stack-trace-parser.js";
+export { createSinatraLineClassifier, isSinatraHeaderLine, isSinatraFrameLine, parseSinatraHeader, parseSinatraFrame, } from "./sinatra-frame-parsing.js";
+export { createSinatraStackTraceParser } from "./sinatra-stack-trace-parser.js";
+export { createRubyLineClassifier, isRubyHeaderLine, isRubyFrameLine, parseRubyHeaderFrame, parseRubyFromFrame, } from "./ruby-frame-parsing.js";
+export { createRubySourceLocationResolver } from "./ruby-source-location-resolver.js";
+export { createRubyStackTraceParser } from "./ruby-stack-trace-parser.js";
+export { createRubyLoggerEnvelope, createRailsTaggedLogEnvelope } from "./ruby-log-envelopes.js";
+export { createRubyRuntimeAdapter } from "./ruby-runtime-adapter.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,GAChB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAE5E,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,6BAA6B,EAAE,MAAM,iCAAiC,CAAC;AAEhF,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,gCAAgC,EAAE,MAAM,oCAAoC,CAAC;AACtF,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,EAAE,wBAAwB,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAC;AAEjG,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/rails-frame-parsing.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Rails' backtrace grammar, which is **not Ruby's** (RT-111).
+ *
+ * ## The measurement
+ *
+ * A real Rails 8.0.4 application, spawned through the managed lifecycle,
+ * failing through its own request pipeline, logging through
+ * `ActiveSupport::TaggedLogging`, produced:
+ *
+ * ```
+ * 77 lines in -> 0 exceptions, 0 stack traces, 77 plain logs
+ * ```
+ *
+ * Zero. With the Rails log envelope applied and without it, identically.
+ * RT-089's shape for the third time (RT-089 ASP.NET, RT-104 PEP 654) and the
+ * most consequential of the three, because Rails is *the* Ruby framework and
+ * this is every exception a Rails application reports.
+ *
+ * ## Why the Ruby classifier cannot see it
+ *
+ * `ActionDispatch::DebugExceptions` does not log `Exception#full_message`.
+ * It composes its own text, and both halves differ:
+ *
+ * ```
+ * NoMethodError (undefined method 'fetch' for nil):        <- Class (message):
+ *
+ * rails_service.rb:69:in 'ProbeController#read_customer_name'
+ * rails_service.rb:73:in 'ProbeController#charge_invoice'
+ * ```
+ *
+ * against Ruby's own printer:
+ *
+ * ```
+ * rails_service.rb:69:in 'ProbeController#read_customer_name': undefined method 'fetch' for nil (NoMethodError)
+ *         from rails_service.rb:73:in 'ProbeController#charge_invoice'
+ * ```
+ *
+ * - **The header carries no location.** Ruby's header IS the innermost
+ *   frame; Rails' names only the class and the message, and the raise site
+ *   moves down to the first backtrace line.
+ * - **The frames have no `from` prefix.** `FROM_FRAME_PATTERN` requires one,
+ *   and `HEADER_PATTERN` requires a trailing `: message` that these lines do
+ *   not have. So a Rails backtrace line matches neither, and the block never
+ *   opens.
+ *
+ * ## The fix is a declared framework, not a looser Ruby pattern
+ *
+ * Widening Ruby's `isFrame` to accept a bare `file:line:in 'name'` was the
+ * cheaper change and is the wrong one. `ExceptionBlockDetector` opens a
+ * block the moment `isFrame` returns true from idle, so that pattern would
+ * turn **any** log line containing `something.rb:12:in 'foo'` into the start
+ * of a stack trace — a wrong edge, which rule 2 ranks as worse than a
+ * missing one because it corrupts everything above it.
+ *
+ * So this is a second classifier, selected by
+ * `createRubyRuntimeAdapter({ framework: "rails" })` — **declared, never
+ * sniffed**, the same rule `createCSharpRuntimeAdapter`'s `framework` option
+ * follows and for the same reason: detecting Rails from a line that looks
+ * like its output would apply this grammar to a plain Ruby process that
+ * happened to print one.
+ *
+ * ## The bare-frame pattern is still loose, and is confined rather than tightened
+ *
+ * `isFrame` here is stateful: a bare `file:line:in 'name'` is only a frame
+ * **after a header has been seen**, which is the same argument
+ * `createPythonLineClassifier` makes about indented lines. Out of that
+ * state the pattern is never consulted from idle, so it cannot open a block
+ * on its own.
+ *
+ * ## The blank line between the header and the first frame is a bridge
+ *
+ * Rails prints a whitespace-only line after the header (and another before
+ * it). `LineClassifier.isBridge` exists for exactly this — PHP's `Stack
+ * trace:` line was the first — and `ExceptionBlockDetector` consults it only
+ * while a header is already held, so a blank line elsewhere in the log opens
+ * nothing.
+ */
+export interface RawRailsFrame {
+    /** `Class#method`, `Class.method`, `block in Class#method` — kept verbatim, never rewritten. */
+    readonly functionName: string | null;
+    readonly file: string;
+    readonly line: number;
+}
+export declare function isRailsHeaderLine(line: string): boolean;
+export declare function isRailsFrameLine(line: string): boolean;
+/** `null` when the line is not `Class (message):` shaped — never fabricated. */
+export declare function parseRailsHeader(line: string): {
+    readonly exceptionClass: string;
+    readonly message: string;
+} | null;
+/** `null` for anything not shaped like a bare `file:line:in 'name'` frame — never fabricated. */
+export declare function parseRailsFrame(line: string): RawRailsFrame | null;
+/**
+ * A stateful `LineClassifier`, and the statefulness is what makes the loose
+ * frame pattern safe. See this file's header.
+ *
+ * A fresh classifier per collector keeps two processes' output from priming
+ * each other — the same construction rule every other adapter here follows.
+ */
+export declare function createRailsLineClassifier(): {
+    isHeader(line: string): boolean;
+    isFrame(line: string): boolean;
+    isBridge(line: string): boolean;
+};
+//# sourceMappingURL=rails-frame-parsing.d.ts.map

package/dist/rails-frame-parsing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rails-frame-parsing.d.ts","sourceRoot":"","sources":["../src/rails-frame-parsing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AAEH,MAAM,WAAW,aAAa;IAC5B,gGAAgG;IAChG,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAmCD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAMnH;AAED,iGAAiG;AACjG,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAOlE;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,IAAI;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAuCA"}

package/dist/rails-frame-parsing.js

@@ -0,0 +1,183 @@
+/**
+ * Rails' backtrace grammar, which is **not Ruby's** (RT-111).
+ *
+ * ## The measurement
+ *
+ * A real Rails 8.0.4 application, spawned through the managed lifecycle,
+ * failing through its own request pipeline, logging through
+ * `ActiveSupport::TaggedLogging`, produced:
+ *
+ * ```
+ * 77 lines in -> 0 exceptions, 0 stack traces, 77 plain logs
+ * ```
+ *
+ * Zero. With the Rails log envelope applied and without it, identically.
+ * RT-089's shape for the third time (RT-089 ASP.NET, RT-104 PEP 654) and the
+ * most consequential of the three, because Rails is *the* Ruby framework and
+ * this is every exception a Rails application reports.
+ *
+ * ## Why the Ruby classifier cannot see it
+ *
+ * `ActionDispatch::DebugExceptions` does not log `Exception#full_message`.
+ * It composes its own text, and both halves differ:
+ *
+ * ```
+ * NoMethodError (undefined method 'fetch' for nil):        <- Class (message):
+ *
+ * rails_service.rb:69:in 'ProbeController#read_customer_name'
+ * rails_service.rb:73:in 'ProbeController#charge_invoice'
+ * ```
+ *
+ * against Ruby's own printer:
+ *
+ * ```
+ * rails_service.rb:69:in 'ProbeController#read_customer_name': undefined method 'fetch' for nil (NoMethodError)
+ *         from rails_service.rb:73:in 'ProbeController#charge_invoice'
+ * ```
+ *
+ * - **The header carries no location.** Ruby's header IS the innermost
+ *   frame; Rails' names only the class and the message, and the raise site
+ *   moves down to the first backtrace line.
+ * - **The frames have no `from` prefix.** `FROM_FRAME_PATTERN` requires one,
+ *   and `HEADER_PATTERN` requires a trailing `: message` that these lines do
+ *   not have. So a Rails backtrace line matches neither, and the block never
+ *   opens.
+ *
+ * ## The fix is a declared framework, not a looser Ruby pattern
+ *
+ * Widening Ruby's `isFrame` to accept a bare `file:line:in 'name'` was the
+ * cheaper change and is the wrong one. `ExceptionBlockDetector` opens a
+ * block the moment `isFrame` returns true from idle, so that pattern would
+ * turn **any** log line containing `something.rb:12:in 'foo'` into the start
+ * of a stack trace — a wrong edge, which rule 2 ranks as worse than a
+ * missing one because it corrupts everything above it.
+ *
+ * So this is a second classifier, selected by
+ * `createRubyRuntimeAdapter({ framework: "rails" })` — **declared, never
+ * sniffed**, the same rule `createCSharpRuntimeAdapter`'s `framework` option
+ * follows and for the same reason: detecting Rails from a line that looks
+ * like its output would apply this grammar to a plain Ruby process that
+ * happened to print one.
+ *
+ * ## The bare-frame pattern is still loose, and is confined rather than tightened
+ *
+ * `isFrame` here is stateful: a bare `file:line:in 'name'` is only a frame
+ * **after a header has been seen**, which is the same argument
+ * `createPythonLineClassifier` makes about indented lines. Out of that
+ * state the pattern is never consulted from idle, so it cannot open a block
+ * on its own.
+ *
+ * ## The blank line between the header and the first frame is a bridge
+ *
+ * Rails prints a whitespace-only line after the header (and another before
+ * it). `LineClassifier.isBridge` exists for exactly this — PHP's `Stack
+ * trace:` line was the first — and `ExceptionBlockDetector` consults it only
+ * while a header is already held, so a blank line elsewhere in the log opens
+ * nothing.
+ */
+/**
+ * `NoMethodError (undefined method 'fetch' for nil):`
+ *
+ * `ActionDispatch::ExceptionWrapper` composes `"#{class} (#{message}):"`.
+ * Anchored at both ends and requiring the trailing `):`, because a partial
+ * match is evidence the line is not a header rather than a reason to guess
+ * at one. The class group allows `::` so a namespaced
+ * `ActiveRecord::RecordNotFound` matches.
+ *
+ * Not anchored at the *start* of the line beyond leading whitespace: the
+ * Rails envelope removes the `[request-id] ` tag run before the classifier
+ * sees the line, but an application logging through a different formatter
+ * may leave something else there, and Ruby's own header pattern made the
+ * same allowance for the same reason.
+ */
+const RAILS_HEADER = /(?<class>[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*) \((?<message>.*)\):\s*$/;
+/**
+ * `rails_service.rb:69:in 'ProbeController#read_customer_name'`, or a gem
+ * frame `actionpack (8.0.4) lib/action_controller/metal.rb:252:in '...'`.
+ *
+ * The gem form is real and is why `file` is `.+` rather than a path
+ * character class: Rails rewrites a gem's absolute path to
+ * `name (version) relative/path`, which is not openable but is the
+ * interpreter's — strictly Rails' — own answer, and rewriting it here would
+ * invent a location. Same decision as the `eval` frames in RT-105.
+ *
+ * The closing quote is always `'`; only the opening one varies by Ruby
+ * version (Feature #16495), so both are accepted exactly as Ruby's own
+ * patterns do.
+ */
+const RAILS_FRAME = /^\s*(?<file>.+):(?<line>\d+):in\s+[`'](?<fn>[^']*)'\s*$/;
+export function isRailsHeaderLine(line) {
+    return RAILS_HEADER.test(line);
+}
+export function isRailsFrameLine(line) {
+    return RAILS_FRAME.test(line);
+}
+/** `null` when the line is not `Class (message):` shaped — never fabricated. */
+export function parseRailsHeader(line) {
+    const match = RAILS_HEADER.exec(line);
+    if (!match?.groups)
+        return null;
+    const exceptionClass = match.groups["class"];
+    if (exceptionClass === undefined)
+        return null;
+    return { exceptionClass, message: match.groups["message"] ?? "" };
+}
+/** `null` for anything not shaped like a bare `file:line:in 'name'` frame — never fabricated. */
+export function parseRailsFrame(line) {
+    const match = RAILS_FRAME.exec(line);
+    if (!match?.groups)
+        return null;
+    const file = match.groups["file"];
+    const lineNumber = Number(match.groups["line"]);
+    if (file === undefined || !Number.isInteger(lineNumber))
+        return null;
+    return { functionName: match.groups["fn"] ?? null, file, line: lineNumber };
+}
+/**
+ * A stateful `LineClassifier`, and the statefulness is what makes the loose
+ * frame pattern safe. See this file's header.
+ *
+ * A fresh classifier per collector keeps two processes' output from priming
+ * each other — the same construction rule every other adapter here follows.
+ */
+export function createRailsLineClassifier() {
+    let sawHeader = false;
+    return {
+        isHeader(line) {
+            if (isRailsHeaderLine(line)) {
+                sawHeader = true;
+                return true;
+            }
+            return false;
+        },
+        isFrame(line) {
+            // Never from idle. A bare `x.rb:12:in 'foo'` is frame-shaped and is
+            // also an entirely ordinary thing for an application to log.
+            if (!sawHeader)
+                return false;
+            if (isRailsFrameLine(line))
+                return true;
+            // **A blank line must not clear the state**, and the first version of
+            // this classifier did clear it — which is why the whole grammar
+            // recognised every line correctly and still produced zero exceptions.
+            // `ExceptionBlockDetector` asks `isFrame` before `isBridge` in the
+            // `holding-header` state, so the blank line Rails prints between its
+            // header and its first frame arrived here first, reset `sawHeader`,
+            // and every real frame after it was refused. Recognising each line in
+            // isolation is not the same as recognising the sequence.
+            if (line.trim() === "")
+                return false;
+            sawHeader = false;
+            return false;
+        },
+        /**
+         * The whitespace-only line Rails prints between the header and the first
+         * frame. Consulted only while a header is held, so a blank line
+         * elsewhere in the log opens nothing.
+         */
+        isBridge(line) {
+            return line.trim() === "";
+        },
+    };
+}
+//# sourceMappingURL=rails-frame-parsing.js.map

package/dist/rails-frame-parsing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rails-frame-parsing.js","sourceRoot":"","sources":["../src/rails-frame-parsing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AASH;;;;;;;;;;;;;;GAcG;AACH,MAAM,YAAY,GAAG,+EAA+E,CAAC;AAErG;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,GAAG,yDAAyD,CAAC;AAE9E,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK,EAAE,MAAM;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,cAAc,GAAG,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC7C,IAAI,cAAc,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC9C,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC;AACpE,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,CAAC,KAAK,EAAE,MAAM;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAChD,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IACrE,OAAO,EAAE,YAAY,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;AAC9E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB;IAKvC,IAAI,SAAS,GAAG,KAAK,CAAC;IAEtB,OAAO;QACL,QAAQ,CAAC,IAAY;YACnB,IAAI,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC5B,SAAS,GAAG,IAAI,CAAC;gBACjB,OAAO,IAAI,CAAC;YACd,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,CAAC,IAAY;YAClB,oEAAoE;YACpE,6DAA6D;YAC7D,IAAI,CAAC,SAAS;gBAAE,OAAO,KAAK,CAAC;YAC7B,IAAI,gBAAgB,CAAC,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAC;YACxC,sEAAsE;YACtE,gEAAgE;YAChE,sEAAsE;YACtE,mEAAmE;YACnE,qEAAqE;YACrE,oEAAoE;YACpE,sEAAsE;YACtE,yDAAyD;YACzD,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;gBAAE,OAAO,KAAK,CAAC;YACrC,SAAS,GAAG,KAAK,CAAC;YAClB,OAAO,KAAK,CAAC;QACf,CAAC;QAED;;;;WAIG;QACH,QAAQ,CAAC,IAAY;YACnB,OAAO,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;QAC5B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/rails-stack-trace-parser.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Composes Rails' line-recognition functions with a `SourceLocationResolver`
+ * (RT-111).
+ *
+ * ## Why this is a second parser and not a branch in the Ruby one
+ *
+ * The two grammars disagree about **where the raise site is**, which is the
+ * one thing `primaryFrameIndex` exists to state:
+ *
+ * - Ruby's header IS the innermost frame, so index 0 is the header line.
+ * - Rails' header carries **no location at all** — it is `Class (message):`
+ *   — and the raise site is the *first backtrace line beneath it*.
+ *
+ * A single parser with a flag would have to carry both answers and pick one,
+ * which is the shape that produced RT-083 (`primaryFrameIndex` inherited
+ * rather than stated). Two parsers each state one answer.
+ *
+ * Both still report `primaryFrameIndex: 0`, and for Rails that is a
+ * different fact rather than the same one: **the header contributes no
+ * frame**, so frame 0 is the first line Rails printed, and Rails prints
+ * innermost-first. Measured against a live Rails 8.0.4 request pipeline:
+ * frame 0 is `ProbeController#read_customer_name`, the line that raised,
+ * with the controller action two frames below it and 40 framework frames
+ * under that.
+ *
+ * `fidelity` is `"synchronous"` for the same reason Ruby's is: every frame
+ * is a genuine link in the call chain that was executing.
+ */
+import type { SourceLocationResolver, StackTraceParser } from "@descryy/runtime-backend-observation";
+export declare function createRailsStackTraceParser(resolver: SourceLocationResolver): StackTraceParser;
+//# sourceMappingURL=rails-stack-trace-parser.d.ts.map

package/dist/rails-stack-trace-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rails-stack-trace-parser.d.ts","sourceRoot":"","sources":["../src/rails-stack-trace-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,KAAK,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAIrG,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,sBAAsB,GAAG,gBAAgB,CAkC9F"}

package/dist/rails-stack-trace-parser.js

@@ -0,0 +1,63 @@
+/**
+ * Composes Rails' line-recognition functions with a `SourceLocationResolver`
+ * (RT-111).
+ *
+ * ## Why this is a second parser and not a branch in the Ruby one
+ *
+ * The two grammars disagree about **where the raise site is**, which is the
+ * one thing `primaryFrameIndex` exists to state:
+ *
+ * - Ruby's header IS the innermost frame, so index 0 is the header line.
+ * - Rails' header carries **no location at all** — it is `Class (message):`
+ *   — and the raise site is the *first backtrace line beneath it*.
+ *
+ * A single parser with a flag would have to carry both answers and pick one,
+ * which is the shape that produced RT-083 (`primaryFrameIndex` inherited
+ * rather than stated). Two parsers each state one answer.
+ *
+ * Both still report `primaryFrameIndex: 0`, and for Rails that is a
+ * different fact rather than the same one: **the header contributes no
+ * frame**, so frame 0 is the first line Rails printed, and Rails prints
+ * innermost-first. Measured against a live Rails 8.0.4 request pipeline:
+ * frame 0 is `ProbeController#read_customer_name`, the line that raised,
+ * with the controller action two frames below it and 40 framework frames
+ * under that.
+ *
+ * `fidelity` is `"synchronous"` for the same reason Ruby's is: every frame
+ * is a genuine link in the call chain that was executing.
+ */
+import { parseRailsFrame, parseRailsHeader } from "./rails-frame-parsing.js";
+export function createRailsStackTraceParser(resolver) {
+    return {
+        async parse(rawText) {
+            const lines = rawText.split(/\r\n|\r|\n/);
+            const frames = [];
+            for (const line of lines) {
+                // The header is tried first and produces no frame — it has no
+                // location to produce one from. Skipping it explicitly rather than
+                // letting it fall through matters because `Class (message):` can
+                // contain a colon and a number in the message and would otherwise
+                // be worth checking against the frame pattern.
+                if (parseRailsHeader(line) !== null)
+                    continue;
+                const raw = parseRailsFrame(line);
+                if (raw === null)
+                    continue;
+                const location = await resolver.resolve({
+                    file: raw.file,
+                    line: raw.line,
+                    column: null,
+                    functionName: raw.functionName,
+                });
+                frames.push({ location, raw: line });
+            }
+            // Null, never an empty-but-structured StackTrace standing in for
+            // "couldn't parse" — this interface's contract, and the reason a
+            // header-only block does not become a zero-frame trace.
+            if (frames.length === 0)
+                return null;
+            return { fidelity: "synchronous", frames, primaryFrameIndex: 0 };
+        },
+    };
+}
+//# sourceMappingURL=rails-stack-trace-parser.js.map

package/dist/rails-stack-trace-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rails-stack-trace-parser.js","sourceRoot":"","sources":["../src/rails-stack-trace-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAKH,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE7E,MAAM,UAAU,2BAA2B,CAAC,QAAgC;IAC1E,OAAO;QACL,KAAK,CAAC,KAAK,CAAC,OAAe;YACzB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;YAE1C,MAAM,MAAM,GAAiB,EAAE,CAAC;YAChC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,8DAA8D;gBAC9D,mEAAmE;gBACnE,iEAAiE;gBACjE,kEAAkE;gBAClE,+CAA+C;gBAC/C,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,IAAI;oBAAE,SAAS;gBAE9C,MAAM,GAAG,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;gBAClC,IAAI,GAAG,KAAK,IAAI;oBAAE,SAAS;gBAE3B,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC;oBACtC,IAAI,EAAE,GAAG,CAAC,IAAI;oBACd,IAAI,EAAE,GAAG,CAAC,IAAI;oBACd,MAAM,EAAE,IAAI;oBACZ,YAAY,EAAE,GAAG,CAAC,YAAY;iBAC/B,CAAC,CAAC;gBACH,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;YACvC,CAAC;YAED,iEAAiE;YACjE,iEAAiE;YACjE,wDAAwD;YACxD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC;YAErC,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC,EAAE,CAAC;QACnE,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/ruby-frame-parsing.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Ruby backtrace line shapes — the `LineClassifier` for
+ * `ExceptionBlockDetector` plus the raw-text-to-frame-parts extraction that
+ * feeds `SourceLocationResolver`.
+ *
+ * Ruby's format is architecturally its own shape, distinct from both V8 and
+ * CPython:
+ *
+ * 1. **The header line IS the innermost frame.** Where V8 prints a
+ *    header with no location and CPython prints a banner with no location,
+ *    Ruby's default uncaught-exception printer combines them:
+ *    `file.rb:2:in 'delete_invoice': invoice 3 is corrupt (RuntimeError)` is
+ *    simultaneously "here is the exception" and "here is where it happened."
+ *    Confirmed verbatim against `Exception#full_message`'s own documented
+ *    example (docs.ruby-lang.org/en/3.4/Exception.html): the array's first
+ *    entry is `"t.rb:3:in 'Integer#/': divided by 0 (ZeroDivisionError)"`.
+ * 2. **Continuation frames are prefixed `from`, not `at`,** and carry no
+ *    message: `\tfrom t.rb:10:in 'Object#bar'`. Confirmed against the same
+ *    doc example and against ruby/spec's own
+ *    `core/exception/top_level_spec.rb`, which asserts the custom-backtrace
+ *    case renders as:
+ *    ```
+ *    /dir/foo.rb:10:in `raising': foo (RuntimeError)
+ *    \tfrom /dir/bar.rb:20:in `caller'
+ *    ```
+ * 3. **The closing quote is always a single quote; only the opening quote
+ *    varies by Ruby version.** Ruby 3.4 (Feature #16495) replaced the
+ *    opening backtick with a single quote and, per Feature #19117, prefixes
+ *    the owning class where one has a permanent name
+ *    (`'Object#division'` vs. the pre-3.4 `` `division' ``). Both are real,
+ *    currently-deployed formats — Ruby 3.4 shipped 2024-12-25, and every
+ *    LTS-adjacent 3.0–3.3 install in production still prints the backtick
+ *    form — so both are accepted here via a `[` ']` opening-character class,
+ *    never just the newer one.
+ * 4. **No `isTrailer` is needed.** Because the header already carries the
+ *    exception's identity, Ruby has nothing analogous to CPython's
+ *    identity-comes-last problem. Chained exceptions (`Exception#cause`)
+ *    print as two complete header+frames blocks back to back with **no
+ *    connective sentence between them** — confirmed against
+ *    `top_level_spec.rb`'s `"the Exception#cause is printed to STDERR with
+ *    backtraces"` example — so the second header simply starts a new block
+ *    once the first one's last `from` line stops matching `isFrame`. No
+ *    special-casing required, unlike CPython's connective-exclusion.
+ *
+ * **Known, disclosed gap:** a backtrace whose only frame is the header
+ * itself — a bare top-level `raise` with no caller beneath it, e.g.
+ * `ruby -e 'raise "boom"'` — has no `from` line to confirm it, and
+ * `ExceptionBlockDetector`'s `holding-header` state demotes an unconfirmed
+ * header to a plain log line at `flush()`. This is a structural
+ * consequence of a header-embeds-frame grammar meeting a classifier
+ * interface built around "header, then confirming frame line": there is no
+ * lookahead-free way to distinguish "a header about to be followed by
+ * frames" from "a header that IS the entire trace" from the header line
+ * alone. `parseRubyHeaderFrame` still extracts the correct single frame
+ * from such a line if handed it directly — the gap is confined to the
+ * streaming block detector's own decision to invoke the parser at all, not
+ * to the parser's capability. In practice this only affects genuinely
+ * flat top-level scripts; a backend process (the collector's real target)
+ * always has at least one caller frame between the raise site and the
+ * process entry point.
+ */
+export interface RawRubyFrame {
+    /** `<main>`, `block in foo`, `rescue in foo` and `Class#method`/`Class.method` are real Ruby frame names and are kept verbatim, never rewritten. */
+    readonly functionName: string | null;
+    readonly file: string;
+    readonly line: number;
+}
+export declare function isRubyHeaderLine(line: string): boolean;
+export declare function isRubyFrameLine(line: string): boolean;
+export declare function createRubyLineClassifier(): {
+    isHeader(line: string): boolean;
+    isFrame(line: string): boolean;
+};
+/** `null` when the header doesn't match Ruby's `file:line:in 'name': message` shape — never fabricated. */
+export declare function parseRubyHeaderFrame(line: string): RawRubyFrame | null;
+/** `null` for anything not shaped like a `from file:line:in 'name'` continuation — never fabricated. */
+export declare function parseRubyFromFrame(line: string): RawRubyFrame | null;
+//# sourceMappingURL=ruby-frame-parsing.d.ts.map

package/dist/ruby-frame-parsing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ruby-frame-parsing.d.ts","sourceRoot":"","sources":["../src/ruby-frame-parsing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,MAAM,WAAW,YAAY;IAC3B,oJAAoJ;IACpJ,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAgBD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,wBAAgB,wBAAwB,IAAI;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAChC,CAKA;AAED,2GAA2G;AAC3G,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAOtE;AAED,wGAAwG;AACxG,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAOpE"}

package/dist/ruby-frame-parsing.js

@@ -0,0 +1,108 @@
+/**
+ * Ruby backtrace line shapes — the `LineClassifier` for
+ * `ExceptionBlockDetector` plus the raw-text-to-frame-parts extraction that
+ * feeds `SourceLocationResolver`.
+ *
+ * Ruby's format is architecturally its own shape, distinct from both V8 and
+ * CPython:
+ *
+ * 1. **The header line IS the innermost frame.** Where V8 prints a
+ *    header with no location and CPython prints a banner with no location,
+ *    Ruby's default uncaught-exception printer combines them:
+ *    `file.rb:2:in 'delete_invoice': invoice 3 is corrupt (RuntimeError)` is
+ *    simultaneously "here is the exception" and "here is where it happened."
+ *    Confirmed verbatim against `Exception#full_message`'s own documented
+ *    example (docs.ruby-lang.org/en/3.4/Exception.html): the array's first
+ *    entry is `"t.rb:3:in 'Integer#/': divided by 0 (ZeroDivisionError)"`.
+ * 2. **Continuation frames are prefixed `from`, not `at`,** and carry no
+ *    message: `\tfrom t.rb:10:in 'Object#bar'`. Confirmed against the same
+ *    doc example and against ruby/spec's own
+ *    `core/exception/top_level_spec.rb`, which asserts the custom-backtrace
+ *    case renders as:
+ *    ```
+ *    /dir/foo.rb:10:in `raising': foo (RuntimeError)
+ *    \tfrom /dir/bar.rb:20:in `caller'
+ *    ```
+ * 3. **The closing quote is always a single quote; only the opening quote
+ *    varies by Ruby version.** Ruby 3.4 (Feature #16495) replaced the
+ *    opening backtick with a single quote and, per Feature #19117, prefixes
+ *    the owning class where one has a permanent name
+ *    (`'Object#division'` vs. the pre-3.4 `` `division' ``). Both are real,
+ *    currently-deployed formats — Ruby 3.4 shipped 2024-12-25, and every
+ *    LTS-adjacent 3.0–3.3 install in production still prints the backtick
+ *    form — so both are accepted here via a `[` ']` opening-character class,
+ *    never just the newer one.
+ * 4. **No `isTrailer` is needed.** Because the header already carries the
+ *    exception's identity, Ruby has nothing analogous to CPython's
+ *    identity-comes-last problem. Chained exceptions (`Exception#cause`)
+ *    print as two complete header+frames blocks back to back with **no
+ *    connective sentence between them** — confirmed against
+ *    `top_level_spec.rb`'s `"the Exception#cause is printed to STDERR with
+ *    backtraces"` example — so the second header simply starts a new block
+ *    once the first one's last `from` line stops matching `isFrame`. No
+ *    special-casing required, unlike CPython's connective-exclusion.
+ *
+ * **Known, disclosed gap:** a backtrace whose only frame is the header
+ * itself — a bare top-level `raise` with no caller beneath it, e.g.
+ * `ruby -e 'raise "boom"'` — has no `from` line to confirm it, and
+ * `ExceptionBlockDetector`'s `holding-header` state demotes an unconfirmed
+ * header to a plain log line at `flush()`. This is a structural
+ * consequence of a header-embeds-frame grammar meeting a classifier
+ * interface built around "header, then confirming frame line": there is no
+ * lookahead-free way to distinguish "a header about to be followed by
+ * frames" from "a header that IS the entire trace" from the header line
+ * alone. `parseRubyHeaderFrame` still extracts the correct single frame
+ * from such a line if handed it directly — the gap is confined to the
+ * streaming block detector's own decision to invoke the parser at all, not
+ * to the parser's capability. In practice this only affects genuinely
+ * flat top-level scripts; a backend process (the collector's real target)
+ * always has at least one caller frame between the raise site and the
+ * process entry point.
+ */
+/**
+ * The combined header+innermost-frame line. Distinguished from a bare
+ * `from` line by the trailing `: message` — real `from` lines never carry
+ * one (see `FROM_FRAME_PATTERN`). Not anchored to the start of the line,
+ * for the same reason V8's header pattern isn't: a backend that logs a
+ * caught exception's `full_message` through a leveled logger prefixes a
+ * timestamp, and Ruby's own top-level printer (which never adds a prefix)
+ * is only one of the two realistic capture paths.
+ */
+const HEADER_PATTERN = /(?<file>.+):(?<line>\d+):in\s+[`'](?<fn>[^']*)':\s/;
+/** Same location+name grammar as the header, but `from`-prefixed and with no trailing message. */
+const FROM_FRAME_PATTERN = /^\s*from\s+(?<file>.+):(?<line>\d+):in\s+[`'](?<fn>[^']*)'\s*$/;
+export function isRubyHeaderLine(line) {
+    return HEADER_PATTERN.test(line);
+}
+export function isRubyFrameLine(line) {
+    return FROM_FRAME_PATTERN.test(line);
+}
+export function createRubyLineClassifier() {
+    return {
+        isHeader: isRubyHeaderLine,
+        isFrame: isRubyFrameLine,
+    };
+}
+/** `null` when the header doesn't match Ruby's `file:line:in 'name': message` shape — never fabricated. */
+export function parseRubyHeaderFrame(line) {
+    const match = HEADER_PATTERN.exec(line);
+    if (!match?.groups)
+        return null;
+    const file = match.groups["file"];
+    const lineNumber = Number(match.groups["line"]);
+    if (file === undefined || !Number.isInteger(lineNumber))
+        return null;
+    return { functionName: match.groups["fn"] ?? null, file, line: lineNumber };
+}
+/** `null` for anything not shaped like a `from file:line:in 'name'` continuation — never fabricated. */
+export function parseRubyFromFrame(line) {
+    const match = FROM_FRAME_PATTERN.exec(line);
+    if (!match?.groups)
+        return null;
+    const file = match.groups["file"];
+    const lineNumber = Number(match.groups["line"]);
+    if (file === undefined || !Number.isInteger(lineNumber))
+        return null;
+    return { functionName: match.groups["fn"] ?? null, file, line: lineNumber };
+}
+//# sourceMappingURL=ruby-frame-parsing.js.map

package/dist/ruby-frame-parsing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ruby-frame-parsing.js","sourceRoot":"","sources":["../src/ruby-frame-parsing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AASH;;;;;;;;GAQG;AACH,MAAM,cAAc,GAAG,oDAAoD,CAAC;AAE5E,kGAAkG;AAClG,MAAM,kBAAkB,GAAG,gEAAgE,CAAC;AAE5F,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,wBAAwB;IAItC,OAAO;QACL,QAAQ,EAAE,gBAAgB;QAC1B,OAAO,EAAE,eAAe;KACzB,CAAC;AACJ,CAAC;AAED,2GAA2G;AAC3G,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK,EAAE,MAAM;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAChD,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IACrE,OAAO,EAAE,YAAY,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;AAC9E,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK,EAAE,MAAM;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAChD,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IACrE,OAAO,EAAE,YAAY,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;AAC9E,CAAC"}