add locations and pointer

Author: tatomyr

docs/@v2/commands/map.md

@@ -27,7 +27,7 @@ Each node has the following fields:
 | summary | string | Optional. The node's `summary` field, or its `description` truncated at a word boundary (about 200 characters).                                                                          |
 | method  | string | Optional. HTTP method; present on OpenAPI `Operation` nodes only.                                                                                                                        |
 | path    | string | Optional. URL path; present on OpenAPI `Operation` nodes under `paths` only.                                                                                                             |
-| source  | object | Optional. Original `{ file, pointer }` location of the node; present when `--source-locations` is used.                                                                                  |
+| source  | object | Optional. Original `{ file, pointer, startLine, endLine }` location of the node; present when `--source-locations` is used.                                                              |
 | nodes   | array  | Child nodes.                                                                                                                                                                             |
 
 The tree stops at operations, channels, and named components;
@@ -44,6 +44,7 @@ use `--source-locations` when you need the exact file and location of each node.
 ```bash
 redocly map <api>
 redocly map <api> [--format=<option>] [--source-locations] [--config=<path>]
+redocly map <api> --pointer=<json-pointer>
 redocly map --version
 ```
 
@@ -56,7 +57,8 @@ redocly map --version
 | --format           | string  | Format for the output.<br />**Possible values:** `stylish`, `json`. Default value is `stylish`.                                    |
 | --help             | boolean | Show help.                                                                                                                         |
 | --lint-config      | string  | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`. |
-| --source-locations | boolean | Include the original source file and pointer for each node. Useful for multi-file descriptions.                                    |
+| --pointer          | string  | Print the content at the given JSON pointer instead of the map. YAML by default; JSON with `--format=json`.                        |
+| --source-locations | boolean | Include the original source file, pointer, and line range for each node. Useful for multi-file descriptions.                       |
 | --version          | boolean | Show version number.                                                                                                               |
 
 ## Examples
@@ -136,11 +138,35 @@ redocly map openapi.yaml --format=json --source-locations
   "pointer": "#/paths/~1menu",
   "source": {
     "file": "paths/menu.yaml",
-    "pointer": "#/"
+    "pointer": "#/",
+    "startLine": 1,
+    "endLine": 3
   },
   "nodes": []
 }
 ```
 
 The `pointer` stays canonical to the logical document,
-while `source` tells you which file the node actually lives in.
+while `source` tells you which file and lines the node actually lives in —
+so any tool that can read a file range can retrieve the node's content.
+
+### Retrieve the content of a node
+
+Use `--pointer` with a canonical pointer from the map to print that node's content
+instead of the map itself:
+
+```bash
+redocly map openapi.yaml --pointer=#/paths/~1menu
+```
+
+```yaml
+get:
+  operationId: listMenuItems
+  summary: List all menu items
+```
+
+The node itself is resolved (a path item referenced from another file prints that file's content),
+and `$ref`s inside the printed content are kept as-is —
+follow them with further `--pointer` calls.
+Any pointer into the logical document works, including paths deeper than the map's nodes,
+for example `--pointer=#/paths/~1menu/get/summary`.

docs/adr/0002-pointer-retrieval-keeps-refs.md

@@ -0,0 +1,16 @@
+# Pointer retrieval keeps `$ref`s intact
+
+`redocly map --pointer=<json-pointer>` closes the retrieval half of the map's index-navigate-retrieve loop:
+it prints the logical content at any canonical pointer, resolving the addressed node itself
+(a path item that is a file `$ref` prints the target file's content)
+but leaving `$ref`s inside the printed content untouched.
+
+We chose not to inline the subtree:
+inlining duplicates shared schemas across fetches, needs cycle guards for recursive schemas,
+and can silently explode output size.
+Keeping refs is honest and cycle-proof — the consumer follows them with further `--pointer` calls,
+guided by the map.
+
+Source locations additionally carry `startLine`/`endLine`
+(computed from the same YAML AST positions the lint codeframes use),
+so consumers with plain file tools can retrieve node content without any JSON-pointer tooling.

packages/cli/src/commands/map/index.ts

@@ -3,6 +3,9 @@ import {
   buildApiMap,
   detectSpec,
   getMajorSpecVersion,
+  logger,
+  resolveApiMapPointer,
+  stringifyYaml,
   type Document,
   type OutputFormat,
 } from '@redocly/openapi-core';
@@ -19,6 +22,7 @@ export type MapArgv = {
   api?: string;
   format: OutputFormat;
   'source-locations'?: boolean;
+  pointer?: string;
 } & VerifyConfigOptions;
 
 export async function handleMap({ argv, config, collectSpecData }: CommandArgs<MapArgv>) {
@@ -40,6 +44,24 @@ export async function handleMap({ argv, config, collectSpecData }: CommandArgs<M
     );
   }
 
+  if (argv.pointer) {
+    const content = await resolveApiMapPointer({
+      document,
+      config,
+      externalRefResolver,
+      pointer: argv.pointer,
+    });
+    if (content === undefined) {
+      exitWithError(
+        `No content found at pointer ${argv.pointer}. Run the command without --pointer to see the available nodes.`
+      );
+    }
+    logger.output(
+      argv.format === 'json' ? JSON.stringify(content, null, 2) : stringifyYaml(content)
+    );
+    return;
+  }
+
   const apiMap = await buildApiMap({
     document,
     config,

packages/cli/src/commands/map/print-map/stylish.ts

@@ -3,7 +3,9 @@ import * as colors from 'colorette';
 
 export function printApiMapStylish(node: ApiMapNode, depth = 0) {
   const indent = '  '.repeat(depth);
-  const source = node.source ? colors.dim(` (${node.source.file}${node.source.pointer})`) : '';
+  const source = node.source
+    ? colors.dim(` (${node.source.file}:${node.source.startLine}-${node.source.endLine})`)
+    : '';
   logger.output(
     `${indent}${node.title} ${colors.dim(node.kind)} ${colors.cyan(node.pointer)}${source}\n`
   );

packages/cli/src/index.ts

@@ -103,6 +103,10 @@ yargs(hideBin(process.argv))
             type: 'boolean',
             default: false,
           },
+          pointer: {
+            description: 'Print the content at the given JSON pointer instead of the map.',
+            type: 'string',
+          },
         }),
     (argv) => {
       commandWrapper(handleMap)(argv);

packages/core/src/api-map/__tests__/build-api-map.test.ts

@@ -455,15 +455,15 @@ describe('buildApiMap', () => {
         title: '/menu',
         kind: 'PathItem',
         pointer: '#/paths/~1menu',
-        source: { file: 'paths/menu.yaml', pointer: '#/' },
+        source: { file: 'paths/menu.yaml', pointer: '#/', startLine: 1, endLine: 2 },
         nodes: [
           {
             title: 'listMenuItems',
             kind: 'Operation',
             pointer: '#/paths/~1menu/get',
             method: 'get',
             path: '/menu',
-            source: { file: 'paths/menu.yaml', pointer: '#/get' },
+            source: { file: 'paths/menu.yaml', pointer: '#/get', startLine: 2, endLine: 2 },
             nodes: [],
           },
         ],
@@ -472,15 +472,15 @@ describe('buildApiMap', () => {
         title: '/menu-archive',
         kind: 'PathItem',
         pointer: '#/paths/~1menu-archive',
-        source: { file: 'paths/menu.yaml', pointer: '#/' },
+        source: { file: 'paths/menu.yaml', pointer: '#/', startLine: 1, endLine: 2 },
         nodes: [
           {
             title: 'listMenuItems',
             kind: 'Operation',
             pointer: '#/paths/~1menu-archive/get',
             method: 'get',
             path: '/menu-archive',
-            source: { file: 'paths/menu.yaml', pointer: '#/get' },
+            source: { file: 'paths/menu.yaml', pointer: '#/get', startLine: 2, endLine: 2 },
             nodes: [],
           },
         ],
@@ -494,7 +494,7 @@ describe('buildApiMap', () => {
         kind: 'Schema',
         pointer: '#/components/schemas/MenuItem',
         summary: 'A menu item.',
-        source: { file: 'components/menu-item.yaml', pointer: '#/' },
+        source: { file: 'components/menu-item.yaml', pointer: '#/', startLine: 1, endLine: 2 },
         nodes: [],
       },
     ]);

packages/core/src/api-map/build-api-map.ts

@@ -1,6 +1,7 @@
 import type { Config } from '../config/index.js';
 import { detectSpec } from '../detect-spec.js';
 import { getTypes } from '../oas-types.js';
+import { Location } from '../ref-utils.js';
 import { BaseResolver, resolveDocument, type Document } from '../resolve.js';
 import { normalizeTypes } from '../types/index.js';
 import {
@@ -13,6 +14,7 @@ import {
 } from '../visitors.js';
 import { walkDocument, type WalkContext } from '../walk.js';
 import { ApiMapAsync2, ApiMapAsync3 } from './async.js';
+import { makeSourceLocation } from './hooks.js';
 import { ApiMapOAS2, ApiMapOAS3 } from './oas.js';
 import type { ApiMapNode } from './types.js';
 
@@ -32,7 +34,7 @@ export async function buildApiMap({
     title: 'API',
     kind: 'Root',
     pointer: '#/',
-    ...(sourceLocations && { source: { file: document.source.absoluteRef, pointer: '#/' } }),
+    ...(sourceLocations && { source: makeSourceLocation(new Location(document.source, '#/')) }),
     nodes: [],
   };
 

packages/core/src/api-map/hooks.ts

@@ -1,7 +1,18 @@
-import { escapePointerFragment } from '../ref-utils.js';
+import { getLineColLocation } from '../format/codeframes.js';
+import { escapePointerFragment, type Location } from '../ref-utils.js';
 import { isPlainObject } from '../utils/is-plain-object.js';
 import type { UserContext } from '../walk.js';
-import type { ApiMapNode, ApiMapOptions } from './types.js';
+import type { ApiMapNode, ApiMapNodeSource, ApiMapOptions } from './types.js';
+
+export function makeSourceLocation(location: Location): ApiMapNodeSource {
+  const { start, end } = getLineColLocation(location);
+  return {
+    file: location.source.absoluteRef,
+    pointer: location.pointer,
+    startLine: start?.line ?? 1,
+    endLine: end?.line ?? start?.line ?? 1,
+  };
+}
 
 const SUMMARY_MAX_LENGTH = 200;
 
@@ -38,9 +49,7 @@ export function createApiMapHooks(root: ApiMapNode, opts: ApiMapOptions) {
       ...(init.summary && { summary: init.summary }),
       ...(init.method && { method: init.method }),
       ...(init.path && { path: init.path }),
-      ...(opts.sourceLocations && {
-        source: { file: ctx.location.source.absoluteRef, pointer: ctx.location.pointer },
-      }),
+      ...(opts.sourceLocations && { source: makeSourceLocation(ctx.location) }),
       nodes: [],
     };
     parentNode.nodes.push(node);

packages/core/src/api-map/resolve-pointer.ts

@@ -0,0 +1,55 @@
+import type { Config } from '../config/index.js';
+import { detectSpec } from '../detect-spec.js';
+import { getTypes } from '../oas-types.js';
+import { isRef, parsePointer } from '../ref-utils.js';
+import { BaseResolver, resolveDocument, type Document } from '../resolve.js';
+import { normalizeTypes } from '../types/index.js';
+import { isPlainObject } from '../utils/is-plain-object.js';
+import { makeRefId } from '../utils/make-ref-id.js';
+
+export async function resolveApiMapPointer({
+  document,
+  config,
+  externalRefResolver = new BaseResolver(config.resolve),
+  pointer,
+}: {
+  document: Document;
+  config: Config;
+  externalRefResolver?: BaseResolver;
+  pointer: string;
+}): Promise<unknown> {
+  const specVersion = detectSpec(document.parsed);
+  const types = normalizeTypes(config.extendTypes(getTypes(specVersion), specVersion), config);
+  const resolvedRefMap = await resolveDocument({
+    rootDocument: document,
+    rootType: types.Root,
+    externalRefResolver,
+  });
+
+  let current: unknown = document.parsed;
+  let fromFile = document.source.absoluteRef;
+
+  const followRefs = () => {
+    while (isRef(current)) {
+      const resolvedRef = resolvedRefMap.get(makeRefId(fromFile, current.$ref));
+      if (!resolvedRef?.resolved) return false;
+      current = resolvedRef.node;
+      fromFile = resolvedRef.document.source.absoluteRef;
+    }
+    return true;
+  };
+
+  for (const segment of parsePointer(pointer.replace(/^#\//, ''))) {
+    if (!followRefs()) return undefined;
+    if (Array.isArray(current)) {
+      current = current[Number(segment)];
+    } else if (isPlainObject(current)) {
+      current = current[segment];
+    } else {
+      return undefined;
+    }
+    if (current === undefined) return undefined;
+  }
+
+  return followRefs() ? current : undefined;
+}

packages/core/src/api-map/types.ts

@@ -1,6 +1,8 @@
 export type ApiMapNodeSource = {
   file: string;
   pointer: string;
+  startLine: number;
+  endLine: number;
 };
 
 export type ApiMapNode = {