@ontrails/source 1.0.0-beta.45 → 1.0.0-beta.46

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @ontrails/source
 
+## 1.0.0-beta.46
+
+### Minor Changes
+
+- [`54d259b`](https://github.com/outfitter-dev/trails/commit/54d259be81fb6c41d85be48a6cb2100c746a7126): Expose parser-native comment spans from `parseWithDiagnostics` so source-aware
+  tooling can distinguish exact JavaScript and TypeScript comment trivia without
+  reimplementing a lexer.
+
+  Use the shared spans in Warden's public-example rule while keeping leading
+  comment ownership fail-closed across JavaScript line terminators.
+
 ## 1.0.0-beta.45
 
 ## 1.0.0-beta.44

package/README.md

@@ -9,7 +9,8 @@ Shared source-code machinery for Trails packages and repo tooling.
 `@ontrails/source` owns reusable source-code mechanics:
 
 - AST node guards and accessors for the OXC node shapes Trails tooling uses.
-- `parse` and `parseWithDiagnostics` wrappers over `oxc-parser`.
+- `parse` and `parseWithDiagnostics` wrappers over `oxc-parser`, including
+  parser-native comment spans for tools that must distinguish source trivia.
 - `walk`, parent-aware walking, and scope-aware walking over `oxc-walker`.
 - Source locations, source edits, literal extraction, and generic Trails syntax recognition.
 - Generic trail/entity discovery helpers such as `findTrailDefinitions`, `findImplementationBodies`, `findEntityDefinitions`, and `isImplementationCall`.
@@ -44,6 +45,21 @@ const ast = parse(
 const trailIds = ast ? findTrailDefinitions(ast).map((trail) => trail.id) : [];
 ```
 
+Inspect exact comment spans without rebuilding a JavaScript or TypeScript lexer:
+
+```ts
+import { parseWithDiagnostics } from '@ontrails/source';
+
+const sourceCode = '/** Describe a trail. */\nexport const show = 1;\n';
+const parsed = parseWithDiagnostics('example.ts', sourceCode);
+const comments = parsed.comments.map((comment) => ({
+  ...comment,
+  source: sourceCode.slice(comment.start, comment.end),
+}));
+```
+
+Comment spans are returned only when the parser reports no diagnostics. Tools must treat an empty comment inventory on a recovered parse as unknown rather than as proof that the source contains no comments.
+
 Walk source with parent context:
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/source",
-  "version": "1.0.0-beta.45",
+  "version": "1.0.0-beta.46",
   "description": "Shared source-code AST parsing, walking, location, edit, literal, and Trails syntax helpers.",
   "repository": {
     "type": "git",

package/src/nodes.ts

@@ -245,8 +245,19 @@ export interface AstParseDiagnostic {
   readonly severity: string;
 }
 
+/** Parser-native source comment span. Offsets include the comment delimiters. */
+export interface SourceComment {
+  readonly end: number;
+  readonly start: number;
+  readonly type: 'Block' | 'Line';
+  /** Comment text without the line or block delimiters. */
+  readonly value: string;
+}
+
 export interface AstParseResult {
   readonly ast: AstNode | null;
+  /** Exact parser-native comments for a diagnostic-free parse; empty on errors. */
+  readonly comments: readonly SourceComment[];
   readonly diagnostics: readonly AstParseDiagnostic[];
 }
 

package/src/parse.ts

@@ -25,22 +25,25 @@ export const parseWithDiagnostics = (
 ): AstParseResult => {
   try {
     const result = parseSync(filePath, sourceCode, { sourceType: 'module' });
+    const diagnostics = result.errors.map((error) => ({
+      helpMessage: error.helpMessage,
+      labels: error.labels.map((label) => ({
+        end: label.end,
+        message: label.message,
+        start: label.start,
+      })),
+      message: error.message,
+      severity: error.severity,
+    }));
     return {
       ast: result.program as unknown as AstNode,
-      diagnostics: result.errors.map((error) => ({
-        helpMessage: error.helpMessage,
-        labels: error.labels.map((label) => ({
-          end: label.end,
-          message: label.message,
-          start: label.start,
-        })),
-        message: error.message,
-        severity: error.severity,
-      })),
+      comments: diagnostics.length === 0 ? result.comments : [],
+      diagnostics,
     };
   } catch (error) {
     return {
       ast: null,
+      comments: [],
       diagnostics: [
         {
           helpMessage: null,