xmllint support

Author: clavery

.changeset/docs-schema-path-flag.md

@@ -0,0 +1,6 @@
+---
+'@salesforce/b2c-cli': patch
+'@salesforce/b2c-tooling-sdk': patch
+---
+
+Add `--path` flag to `b2c docs schema` to print the filesystem path to a schema file instead of its content, enabling use with tools like `xmllint` for XML validation.

docs/cli/docs.md

@@ -134,9 +134,10 @@ b2c docs schema [query]
 
 ### Flags
 
-| Flag           | Description                | Default |
-| -------------- | -------------------------- | ------- |
-| `--list`, `-l` | List all available schemas | `false` |
+| Flag           | Description                                                    | Default |
+| -------------- | -------------------------------------------------------------- | ------- |
+| `--list`, `-l` | List all available schemas                                     | `false` |
+| `--path`, `-p` | Print the filesystem path to the schema instead of its content | `false` |
 
 ### Examples
 
@@ -152,11 +153,24 @@ b2c docs schema --list
 
 # JSON output
 b2c docs schema catalog --json
+
+# Get the filesystem path to a schema
+b2c docs schema catalog --path
 ```
 
 ### Output
 
-Without `--json`, the command writes schema XML directly to stdout. With `--list`, it prints available schema IDs and a total count.
+Without `--json`, the command writes schema XML directly to stdout. With `--path`, it prints the resolved filesystem path (useful for passing to XML validation tools). With `--list`, it prints available schema IDs and a total count.
+
+### Validating XML with xmllint
+
+Use the `--path` flag to pass schema paths directly to `xmllint` for XML validation:
+
+```bash
+xmllint --schema "$(b2c docs schema catalog --path)" catalog.xml --noout
+```
+
+This works because `--path` returns the real filesystem path, allowing `xmllint` to resolve relative schema imports (like `xml.xsd`) automatically.
 
 ---
 

packages/b2c-cli/src/commands/docs/schema.ts

@@ -3,14 +3,20 @@
  * SPDX-License-Identifier: Apache-2
  * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
  */
-import {Args, Flags} from '@oclif/core';
+import {Args, Flags, ux} from '@oclif/core';
 import {BaseCommand} from '@salesforce/b2c-tooling-sdk/cli';
 import {readSchemaByQuery, listSchemas, type SchemaEntry} from '@salesforce/b2c-tooling-sdk/docs';
 import {t} from '../../i18n/index.js';
 
 interface SchemaResult {
   entry: SchemaEntry;
   content: string;
+  path: string;
+}
+
+interface PathResult {
+  entry: SchemaEntry;
+  path: string;
 }
 
 interface ListResult {
@@ -34,6 +40,7 @@ export default class DocsSchema extends BaseCommand<typeof DocsSchema> {
     '<%= config.bin %> <%= command.id %> order',
     '<%= config.bin %> <%= command.id %> --list',
     '<%= config.bin %> <%= command.id %> catalog --json',
+    'xmllint --schema "$(<%= config.bin %> <%= command.id %> catalog --path)" file.xml --noout',
   ];
 
   static flags = {
@@ -43,16 +50,21 @@ export default class DocsSchema extends BaseCommand<typeof DocsSchema> {
       description: 'List all available schemas',
       default: false,
     }),
+    path: Flags.boolean({
+      char: 'p',
+      description: 'Print the filesystem path to the schema instead of its content',
+      default: false,
+    }),
   };
 
   protected operations = {
     listSchemas,
     readSchemaByQuery,
   };
 
-  async run(): Promise<ListResult | SchemaResult> {
+  async run(): Promise<ListResult | PathResult | SchemaResult> {
     const {query} = this.args;
-    const {list} = this.flags;
+    const {list, path: pathFlag} = this.flags;
 
     // List mode
     if (list) {
@@ -85,6 +97,15 @@ export default class DocsSchema extends BaseCommand<typeof DocsSchema> {
       });
     }
 
+    if (pathFlag) {
+      if (this.jsonEnabled()) {
+        return {entry: result.entry, path: result.path};
+      }
+
+      ux.stdout(result.path);
+      return {entry: result.entry, path: result.path};
+    }
+
     if (this.jsonEnabled()) {
       return result;
     }

packages/b2c-cli/test/commands/docs/schema.test.ts

@@ -4,6 +4,7 @@
  * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
  */
 
+import {ux} from '@oclif/core';
 import {expect} from 'chai';
 import {afterEach, beforeEach} from 'mocha';
 import sinon from 'sinon';
@@ -51,7 +52,9 @@ describe('docs schema', () => {
     const command: any = await createCommand({}, {query: 'catalog'});
 
     sinon.stub(command, 'jsonEnabled').returns(false);
-    const readStub = sinon.stub().returns({entry: {id: 'catalog', title: 't', filePath: 'c.xsd'}, content: '<x/>'});
+    const readStub = sinon
+      .stub()
+      .returns({entry: {id: 'catalog', title: 't', filePath: 'c.xsd'}, content: '<x/>', path: '/tmp/c.xsd'});
     command.operations = {...command.operations, readSchemaByQuery: readStub};
 
     const writeStub = sinon.stub(process.stdout, 'write');
@@ -60,4 +63,21 @@ describe('docs schema', () => {
 
     expect(writeStub.calledOnceWithExactly('<x/>')).to.equal(true);
   });
+
+  it('outputs filesystem path with --path flag', async () => {
+    const command: any = await createCommand({path: true}, {query: 'catalog'});
+
+    sinon.stub(command, 'jsonEnabled').returns(false);
+    const readStub = sinon
+      .stub()
+      .returns({entry: {id: 'catalog', title: 't', filePath: 'c.xsd'}, content: '<x/>', path: '/data/xsd/c.xsd'});
+    command.operations = {...command.operations, readSchemaByQuery: readStub};
+
+    const stdoutStub = sinon.stub(ux, 'stdout');
+
+    const result = await command.run();
+
+    expect(stdoutStub.calledOnceWithExactly('/data/xsd/c.xsd')).to.equal(true);
+    expect(result).to.deep.equal({entry: {id: 'catalog', title: 't', filePath: 'c.xsd'}, path: '/data/xsd/c.xsd'});
+  });
 });

packages/b2c-tooling-sdk/src/docs/schema.ts

@@ -55,7 +55,7 @@ export function listSchemas(): SchemaEntry[] {
 /**
  * Read a schema by its exact ID.
  */
-export function readSchema(id: string): {entry: SchemaEntry; content: string} | null {
+export function readSchema(id: string): {entry: SchemaEntry; content: string; path: string} | null {
   const index = loadIndex();
   const entry = index.entries.find((e) => e.id === id);
 
@@ -66,14 +66,14 @@ export function readSchema(id: string): {entry: SchemaEntry; content: string} |
   const filePath = path.join(XSD_DATA_DIR, entry.filePath);
   const content = fs.readFileSync(filePath, 'utf-8');
 
-  return {entry, content};
+  return {entry, content, path: filePath};
 }
 
 /**
  * Find a schema by fuzzy query and return its content.
  * Returns the best match or null if no match found.
  */
-export function readSchemaByQuery(query: string): {entry: SchemaEntry; content: string} | null {
+export function readSchemaByQuery(query: string): {entry: SchemaEntry; content: string; path: string} | null {
   // First try exact match
   const exactMatch = readSchema(query);
   if (exactMatch) {
@@ -92,7 +92,7 @@ export function readSchemaByQuery(query: string): {entry: SchemaEntry; content:
   const filePath = path.join(XSD_DATA_DIR, bestMatch.item.filePath);
   const content = fs.readFileSync(filePath, 'utf-8');
 
-  return {entry: bestMatch.item, content};
+  return {entry: bestMatch.item, content, path: filePath};
 }
 
 /**