@atlaskit/ads-cli 0.10.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # @atlaskit/ads-cli
2
2
 
3
+ ## 0.11.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [`9a9bcd8b61613`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/9a9bcd8b61613) -
8
+ Unify ADS and Platform CLI discovery with shared search formatting, ADS foundation catalogs,
9
+ aligned property tables, dark code blocks, and invocation-aware follow-up commands.
10
+
11
+ ### Patch Changes
12
+
13
+ - Updated dependencies
14
+
3
15
  ## 0.10.0
4
16
 
5
17
  ### Minor Changes
package/README.md CHANGED
@@ -15,7 +15,8 @@ reimplements search ranking or bundles its own copy of the dataset — there is
15
15
 
16
16
  Distributing ADS structured content through a CLI lets developers **and coding agents** query
17
17
  components from the terminal without configuring an MCP client. Human-readable output is the
18
- default; `--json` emits a stable, self-describing envelope for machine consumers.
18
+ default, with the same highlighted property tables and GitHub-dark-like code blocks used by Platform
19
+ CLI; `--json` emits a stable, self-describing envelope for machine consumers.
19
20
 
20
21
  ## Commands
21
22
 
package/bin/ads-cli.js CHANGED
@@ -25,8 +25,15 @@ if (isDev) {
25
25
  }
26
26
 
27
27
  // The AFM repo-root shell shim sets this display-only value because it delegates to this same
28
- // package entrypoint. Published package runs have no override and advertise their npx command.
29
- const invocation = process.env.ADS_CLI_DISPLAY_INVOCATION || 'npx @atlaskit/ads-cli';
28
+ // package entrypoint. A direct source invocation advertises the exact runnable command; published
29
+ // package runs retain the stable npx form.
30
+ const { resolveInvocation } = require('@atlaskit/cli-output/invocation');
31
+ const invocation = resolveInvocation({
32
+ argv1: process.argv[1],
33
+ isDev,
34
+ environmentVariable: 'ADS_CLI_DISPLAY_INVOCATION',
35
+ publishedInvocation: 'npx @atlaskit/ads-cli',
36
+ });
30
37
 
31
38
  require(path.join('..', isDev ? 'src/cli' : 'dist/cjs/cli'))
32
39
  .run(process.argv.slice(2), undefined, { invocation })
@@ -7,6 +7,7 @@ Object.defineProperty(exports, "__esModule", {
7
7
  exports.formatComponent = void 0;
8
8
  var _typeof2 = _interopRequireDefault(require("@babel/runtime/helpers/typeof"));
9
9
  var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
10
+ var _humanFormat = require("@atlaskit/cli-output/human-format");
10
11
  /**
11
12
  * Human-readable renderer for a single ADS component's detailed docs.
12
13
  *
@@ -25,35 +26,18 @@ var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers
25
26
  */
26
27
 
27
28
  /**
28
- * Collapse whitespace/newlines in a prop description so each prop stays on one readable line.
29
- */
30
- var oneLine = function oneLine(text) {
31
- return text.replace(/\s+/g, ' ').trim();
32
- };
33
-
34
- /**
35
- * Render the props section as an aligned two-column list: `name type`, with the description on
36
- * a wrapped continuation line. Returns an empty array when there are no props.
29
+ * Render props through the shared terminal table used by Platform CLI. The shared formatter keeps
30
+ * names visually distinct, aligns columns, and bounds long generated type expressions.
37
31
  */
38
32
  var formatProps = function formatProps(props) {
39
- if (props.length === 0) {
40
- return ['Props: none'];
41
- }
42
-
43
- // Align the type column to the longest prop name for readability.
44
- var longestName = props.reduce(function (max, prop) {
33
+ return _humanFormat.humanFormat.propertyTable(props.map(function (prop) {
45
34
  var _prop$name;
46
- return Math.max(max, ((_prop$name = prop.name) !== null && _prop$name !== void 0 ? _prop$name : '').length);
47
- }, 0);
48
- var rows = props.flatMap(function (prop) {
49
- var _prop$name2;
50
- var name = ((_prop$name2 = prop.name) !== null && _prop$name2 !== void 0 ? _prop$name2 : '(unknown)').padEnd(longestName);
51
- var type = prop.type ? oneLine(prop.type) : '';
52
- var header = " ".concat(name, " ").concat(type).trimEnd();
53
- var description = prop.description ? " ".concat(oneLine(prop.description)) : null;
54
- return description ? [header, description] : [header];
55
- });
56
- return ["Props (".concat(props.length, "):")].concat((0, _toConsumableArray2.default)(rows));
35
+ return {
36
+ name: (_prop$name = prop.name) !== null && _prop$name !== void 0 ? _prop$name : '(unknown)',
37
+ type: prop.type,
38
+ description: prop.description
39
+ };
40
+ }));
57
41
  };
58
42
 
59
43
  /**
@@ -66,7 +50,7 @@ var formatExamples = function formatExamples(examples) {
66
50
  }
67
51
  var blocks = examples.map(function (example, index) {
68
52
  var code = typeof example === 'string' ? example : JSON.stringify(example, null, 2);
69
- return ["Example ".concat(index + 1, ":"), '```tsx', code, '```'].join('\n');
53
+ return [_humanFormat.humanFormat.section("Example ".concat(index + 1)), _humanFormat.humanFormat.codeBlock(code)].join('\n');
70
54
  });
71
55
  return ["Examples (".concat(examples.length, "):"), ''].concat((0, _toConsumableArray2.default)(blocks));
72
56
  };
@@ -76,14 +60,22 @@ var formatExamples = function formatExamples(examples) {
76
60
  * data is not a recognisable component object, so the caller can fall back to generic rendering.
77
61
  */
78
62
  var formatComponent = exports.formatComponent = function formatComponent(data) {
79
- var _component$props, _component$examples, _component$designSour;
63
+ var _component$usageGuide, _component$props, _component$examples, _component$designSour;
80
64
  // `component <name>` reuses component search with limit 1, so `data` is a one-element array.
81
65
  var component = Array.isArray(data) ? data[0] : data;
82
66
  if (!component || (0, _typeof2.default)(component) !== 'object' || typeof component.name !== 'string') {
83
67
  return null;
84
68
  }
85
- var header = component.package ? "".concat(component.name, " (").concat(component.package, ")") : component.name;
86
- var sections = [header, '='.repeat(header.length), ''].concat((0, _toConsumableArray2.default)(formatProps((_component$props = component.props) !== null && _component$props !== void 0 ? _component$props : [])));
69
+ var header = _humanFormat.humanFormat.heading(component.name);
70
+ var metadata = _humanFormat.humanFormat.metadata([component.status, component.category, component.package]);
71
+ var sections = [header].concat((0, _toConsumableArray2.default)(metadata ? [metadata] : []));
72
+ if (component.description) sections.push('', component.description);
73
+ if ((_component$usageGuide = component.usageGuidelines) !== null && _component$usageGuide !== void 0 && _component$usageGuide.length) {
74
+ sections.push.apply(sections, ['', _humanFormat.humanFormat.section('Use it well')].concat((0, _toConsumableArray2.default)(component.usageGuidelines.slice(0, 4).map(function (item) {
75
+ return " ".concat(_humanFormat.humanFormat.success('•'), " ").concat(item);
76
+ }))));
77
+ }
78
+ sections.push.apply(sections, [''].concat((0, _toConsumableArray2.default)(formatProps((_component$props = component.props) !== null && _component$props !== void 0 ? _component$props : []))));
87
79
  var examples = formatExamples((_component$examples = component.examples) !== null && _component$examples !== void 0 ? _component$examples : []);
88
80
  if (examples.length > 0) {
89
81
  sections.push.apply(sections, [''].concat((0, _toConsumableArray2.default)(examples)));
@@ -93,7 +85,7 @@ var formatComponent = exports.formatComponent = function formatComponent(data) {
93
85
  // URL is actually present, so a `designSource` object without a `figmaUrl` doesn't print
94
86
  // `Design: undefined`.
95
87
  if ((_component$designSour = component.designSource) !== null && _component$designSour !== void 0 && _component$designSour.figmaUrl) {
96
- sections.push('', "Design: ".concat(component.designSource.figmaUrl));
88
+ sections.push('', "".concat(_humanFormat.humanFormat.section('Design:'), " ").concat(_humanFormat.humanFormat.action(component.designSource.figmaUrl)));
97
89
  }
98
90
  return sections.join('\n');
99
91
  };
@@ -8,6 +8,7 @@ exports.formatDocObject = void 0;
8
8
  var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
9
9
  var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
10
10
  var _typeof2 = _interopRequireDefault(require("@babel/runtime/helpers/typeof"));
11
+ var _humanFormat = require("@atlaskit/cli-output/human-format");
11
12
  /**
12
13
  * Human-readable renderer for a single "doc object" payload — the shape returned by the
13
14
  * accessibility (`docs a11y`) and migration (`docs migration`) tools.
@@ -53,7 +54,7 @@ var formatListItem = function formatListItem(item) {
53
54
  var description = typeof record.description === 'string' ? [" ".concat(oneLine(record.description))] : [];
54
55
  var labelCodeBlocks = codeKeys.length > 1 || codeKeys[0] !== 'code';
55
56
  var codeBlocks = codeKeys.flatMap(function (key) {
56
- return [].concat((0, _toConsumableArray2.default)(labelCodeBlocks ? [" ".concat(humanizeKey(key), ":")] : []), [" ```tsx\n".concat(record[key], "\n ```")]);
57
+ return [].concat((0, _toConsumableArray2.default)(labelCodeBlocks ? [" ".concat(humanizeKey(key), ":")] : []), [_humanFormat.humanFormat.codeBlock(record[key])]);
57
58
  });
58
59
  var additionalFields = Object.entries(record).flatMap(function (_ref) {
59
60
  var _ref2 = (0, _slicedToArray2.default)(_ref, 2),
@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", {
6
6
  });
7
7
  exports.formatCompactResults = void 0;
8
8
  var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
9
+ var _humanFormat = require("@atlaskit/cli-output/human-format");
9
10
  var _cliMetadata = require("../commands/cli-metadata");
10
11
  var _compactResults = require("./compact-results");
11
12
  /**
@@ -26,19 +27,6 @@ var pluralize = function pluralize(count, noun) {
26
27
  return "".concat(count, " ").concat(noun).concat(count === 1 ? '' : 's');
27
28
  };
28
29
 
29
- /**
30
- * Append a distribution-specific invocation to a compact row's follow-up command.
31
- *
32
- * Used for every `search` result, where the natural next step is to view that match in full.
33
- * `--all` listings omit it because echoing every row's own name would just be noise.
34
- */
35
- var withFollowUp = function withFollowUp(_ref) {
36
- var line = _ref.line,
37
- followUp = _ref.followUp,
38
- invocation = _ref.invocation;
39
- return followUp ? "".concat(line, "\n \u2192 ").concat(invocation, " ").concat(followUp) : line;
40
- };
41
-
42
30
  /**
43
31
  * Render one component as a compact line.
44
32
  *
@@ -47,13 +35,13 @@ var withFollowUp = function withFollowUp(_ref) {
47
35
  * context and a tag would just be noise.
48
36
  */
49
37
  var formatComponentLine = function formatComponentLine(component, invocation) {
50
- var name = component.name;
51
- var pkg = component.package ? " ".concat(component.package) : '';
52
- var meta = [pluralize(component.propCount, 'prop'), pluralize(component.exampleCount, 'example')].join(', ');
53
- return withFollowUp({
54
- line: "".concat(name).concat(pkg, " (").concat(meta, ")"),
55
- followUp: component.followUp,
56
- invocation: invocation
38
+ return _humanFormat.humanFormat.searchRow({
39
+ name: component.name,
40
+ package: component.package,
41
+ source: 'ads',
42
+ kind: 'component',
43
+ metadata: [pluralize(component.propCount, 'prop'), pluralize(component.exampleCount, 'example')],
44
+ followUp: component.followUp ? "".concat(invocation, " ").concat(component.followUp) : undefined
57
45
  });
58
46
  };
59
47
 
@@ -61,11 +49,12 @@ var formatComponentLine = function formatComponentLine(component, invocation) {
61
49
  * Render one token as a compact `name = value` line.
62
50
  */
63
51
  var formatTokenLine = function formatTokenLine(tokenResult, invocation) {
64
- var line = tokenResult.exampleValue ? "".concat(tokenResult.name, " = ").concat(tokenResult.exampleValue) : tokenResult.name;
65
- return withFollowUp({
66
- line: line,
67
- followUp: tokenResult.followUp,
68
- invocation: invocation
52
+ return _humanFormat.humanFormat.searchRow({
53
+ name: tokenResult.name,
54
+ source: 'ads',
55
+ kind: 'token',
56
+ metadata: tokenResult.exampleValue ? ["= ".concat(tokenResult.exampleValue)] : undefined,
57
+ followUp: tokenResult.followUp ? "".concat(invocation, " ").concat(tokenResult.followUp) : undefined
69
58
  });
70
59
  };
71
60
 
@@ -73,13 +62,13 @@ var formatTokenLine = function formatTokenLine(tokenResult, invocation) {
73
62
  * Render one icon as a compact line with its import package and short usage note.
74
63
  */
75
64
  var formatIconLine = function formatIconLine(iconResult, invocation) {
76
- var name = iconResult.componentName;
77
- var pkg = iconResult.package ? " ".concat(iconResult.package) : '';
78
- var usage = iconResult.usage ? " \u2014 ".concat(iconResult.usage) : '';
79
- return withFollowUp({
80
- line: "".concat(name).concat(pkg).concat(usage),
81
- followUp: iconResult.followUp,
82
- invocation: invocation
65
+ return _humanFormat.humanFormat.searchRow({
66
+ name: iconResult.componentName,
67
+ package: iconResult.package,
68
+ source: 'ads',
69
+ kind: 'icon',
70
+ metadata: iconResult.usage ? [iconResult.usage] : undefined,
71
+ followUp: iconResult.followUp ? "".concat(invocation, " ").concat(iconResult.followUp) : undefined
83
72
  });
84
73
  };
85
74
 
@@ -87,12 +76,12 @@ var formatIconLine = function formatIconLine(iconResult, invocation) {
87
76
  * Render one foundations-document match without dumping its full Markdown body.
88
77
  */
89
78
  var formatDocLine = function formatDocLine(doc, invocation) {
90
- var summary = doc.summary ? " \u2014 ".concat(doc.summary) : '';
91
- var line = "".concat(doc.title).concat(summary);
92
- return withFollowUp({
93
- line: line,
94
- followUp: doc.followUp,
95
- invocation: invocation
79
+ return _humanFormat.humanFormat.searchRow({
80
+ name: doc.title,
81
+ source: 'ads',
82
+ kind: 'docs',
83
+ description: doc.summary,
84
+ followUp: doc.followUp ? "".concat(invocation, " ").concat(doc.followUp) : undefined
96
85
  });
97
86
  };
98
87
 
@@ -103,13 +92,13 @@ var formatDocLine = function formatDocLine(doc, invocation) {
103
92
  * `showFollowUp` (default `false`) adds a `→ <invocation> <command> <name>` drill-in hint beneath
104
93
  * each row. Search enables it for both grouped and `--type` output; `--all` listings leave it off.
105
94
  */
106
- var formatCompactResults = exports.formatCompactResults = function formatCompactResults(_ref2) {
107
- var kind = _ref2.kind,
108
- data = _ref2.data,
109
- _ref2$showFollowUp = _ref2.showFollowUp,
110
- showFollowUp = _ref2$showFollowUp === void 0 ? false : _ref2$showFollowUp,
111
- _ref2$invocation = _ref2.invocation,
112
- invocation = _ref2$invocation === void 0 ? _cliMetadata.CLI_BIN_NAME : _ref2$invocation;
95
+ var formatCompactResults = exports.formatCompactResults = function formatCompactResults(_ref) {
96
+ var kind = _ref.kind,
97
+ data = _ref.data,
98
+ _ref$showFollowUp = _ref.showFollowUp,
99
+ showFollowUp = _ref$showFollowUp === void 0 ? false : _ref$showFollowUp,
100
+ _ref$invocation = _ref.invocation,
101
+ invocation = _ref$invocation === void 0 ? _cliMetadata.CLI_BIN_NAME : _ref$invocation;
113
102
  var compact = (0, _compactResults.compactResults)({
114
103
  kind: kind,
115
104
  data: data,
@@ -15,35 +15,20 @@
15
15
  * A component payload as returned by `searchComponentsTool` / `getAllComponentsTool`.
16
16
  */
17
17
 
18
- /**
19
- * Collapse whitespace/newlines in a prop description so each prop stays on one readable line.
20
- */
21
- const oneLine = text => text.replace(/\s+/g, ' ').trim();
18
+ import { humanFormat } from '@atlaskit/cli-output/human-format';
22
19
 
23
20
  /**
24
- * Render the props section as an aligned two-column list: `name type`, with the description on
25
- * a wrapped continuation line. Returns an empty array when there are no props.
21
+ * Render props through the shared terminal table used by Platform CLI. The shared formatter keeps
22
+ * names visually distinct, aligns columns, and bounds long generated type expressions.
26
23
  */
27
- const formatProps = props => {
28
- if (props.length === 0) {
29
- return ['Props: none'];
30
- }
31
-
32
- // Align the type column to the longest prop name for readability.
33
- const longestName = props.reduce((max, prop) => {
34
- var _prop$name;
35
- return Math.max(max, ((_prop$name = prop.name) !== null && _prop$name !== void 0 ? _prop$name : '').length);
36
- }, 0);
37
- const rows = props.flatMap(prop => {
38
- var _prop$name2;
39
- const name = ((_prop$name2 = prop.name) !== null && _prop$name2 !== void 0 ? _prop$name2 : '(unknown)').padEnd(longestName);
40
- const type = prop.type ? oneLine(prop.type) : '';
41
- const header = ` ${name} ${type}`.trimEnd();
42
- const description = prop.description ? ` ${oneLine(prop.description)}` : null;
43
- return description ? [header, description] : [header];
44
- });
45
- return [`Props (${props.length}):`, ...rows];
46
- };
24
+ const formatProps = props => humanFormat.propertyTable(props.map(prop => {
25
+ var _prop$name;
26
+ return {
27
+ name: (_prop$name = prop.name) !== null && _prop$name !== void 0 ? _prop$name : '(unknown)',
28
+ type: prop.type,
29
+ description: prop.description
30
+ };
31
+ }));
47
32
 
48
33
  /**
49
34
  * Render the examples section. Each example is a code snippet string; they are printed verbatim
@@ -55,7 +40,7 @@ const formatExamples = examples => {
55
40
  }
56
41
  const blocks = examples.map((example, index) => {
57
42
  const code = typeof example === 'string' ? example : JSON.stringify(example, null, 2);
58
- return [`Example ${index + 1}:`, '```tsx', code, '```'].join('\n');
43
+ return [humanFormat.section(`Example ${index + 1}`), humanFormat.codeBlock(code)].join('\n');
59
44
  });
60
45
  return [`Examples (${examples.length}):`, '', ...blocks];
61
46
  };
@@ -65,14 +50,20 @@ const formatExamples = examples => {
65
50
  * data is not a recognisable component object, so the caller can fall back to generic rendering.
66
51
  */
67
52
  export const formatComponent = data => {
68
- var _component$props, _component$examples, _component$designSour;
53
+ var _component$usageGuide, _component$props, _component$examples, _component$designSour;
69
54
  // `component <name>` reuses component search with limit 1, so `data` is a one-element array.
70
55
  const component = Array.isArray(data) ? data[0] : data;
71
56
  if (!component || typeof component !== 'object' || typeof component.name !== 'string') {
72
57
  return null;
73
58
  }
74
- const header = component.package ? `${component.name} (${component.package})` : component.name;
75
- const sections = [header, '='.repeat(header.length), '', ...formatProps((_component$props = component.props) !== null && _component$props !== void 0 ? _component$props : [])];
59
+ const header = humanFormat.heading(component.name);
60
+ const metadata = humanFormat.metadata([component.status, component.category, component.package]);
61
+ const sections = [header, ...(metadata ? [metadata] : [])];
62
+ if (component.description) sections.push('', component.description);
63
+ if ((_component$usageGuide = component.usageGuidelines) !== null && _component$usageGuide !== void 0 && _component$usageGuide.length) {
64
+ sections.push('', humanFormat.section('Use it well'), ...component.usageGuidelines.slice(0, 4).map(item => ` ${humanFormat.success('•')} ${item}`));
65
+ }
66
+ sections.push('', ...formatProps((_component$props = component.props) !== null && _component$props !== void 0 ? _component$props : []));
76
67
  const examples = formatExamples((_component$examples = component.examples) !== null && _component$examples !== void 0 ? _component$examples : []);
77
68
  if (examples.length > 0) {
78
69
  sections.push('', ...examples);
@@ -82,7 +73,7 @@ export const formatComponent = data => {
82
73
  // URL is actually present, so a `designSource` object without a `figmaUrl` doesn't print
83
74
  // `Design: undefined`.
84
75
  if ((_component$designSour = component.designSource) !== null && _component$designSour !== void 0 && _component$designSour.figmaUrl) {
85
- sections.push('', `Design: ${component.designSource.figmaUrl}`);
76
+ sections.push('', `${humanFormat.section('Design:')} ${humanFormat.action(component.designSource.figmaUrl)}`);
86
77
  }
87
78
  return sections.join('\n');
88
79
  };
@@ -6,6 +6,7 @@
6
6
  * as `guidelines`, `bestPractices`, `nextSteps`). The default output prints this as readable text
7
7
  * rather than raw JSON; `--json` still exposes the full structured payload.
8
8
  */
9
+ import { humanFormat } from '@atlaskit/cli-output/human-format';
9
10
 
10
11
  /**
11
12
  * Convert a camelCase / snake_case field key into a human "Title Case" heading,
@@ -34,7 +35,7 @@ const formatListItem = item => {
34
35
  if (title && codeKeys.length > 0) {
35
36
  const description = typeof record.description === 'string' ? [` ${oneLine(record.description)}`] : [];
36
37
  const labelCodeBlocks = codeKeys.length > 1 || codeKeys[0] !== 'code';
37
- const codeBlocks = codeKeys.flatMap(key => [...(labelCodeBlocks ? [` ${humanizeKey(key)}:`] : []), ` \`\`\`tsx\n${record[key]}\n \`\`\``]);
38
+ const codeBlocks = codeKeys.flatMap(key => [...(labelCodeBlocks ? [` ${humanizeKey(key)}:`] : []), humanFormat.codeBlock(record[key])]);
38
39
  const additionalFields = Object.entries(record).flatMap(([key, value]) => {
39
40
  if (['title', 'description', ...codeKeys].includes(key) || value === null || value === undefined) {
40
41
  return [];
@@ -9,6 +9,7 @@
9
9
  * left to the caller's generic fallback.
10
10
  */
11
11
 
12
+ import { humanFormat } from '@atlaskit/cli-output/human-format';
12
13
  import { CLI_BIN_NAME } from '../commands/cli-metadata';
13
14
  import { compactResults } from './compact-results';
14
15
 
@@ -17,18 +18,6 @@ import { compactResults } from './compact-results';
17
18
  */
18
19
  const pluralize = (count, noun) => `${count} ${noun}${count === 1 ? '' : 's'}`;
19
20
 
20
- /**
21
- * Append a distribution-specific invocation to a compact row's follow-up command.
22
- *
23
- * Used for every `search` result, where the natural next step is to view that match in full.
24
- * `--all` listings omit it because echoing every row's own name would just be noise.
25
- */
26
- const withFollowUp = ({
27
- line,
28
- followUp,
29
- invocation
30
- }) => followUp ? `${line}\n → ${invocation} ${followUp}` : line;
31
-
32
21
  /**
33
22
  * Render one component as a compact line.
34
23
  *
@@ -37,13 +26,13 @@ const withFollowUp = ({
37
26
  * context and a tag would just be noise.
38
27
  */
39
28
  const formatComponentLine = (component, invocation) => {
40
- const name = component.name;
41
- const pkg = component.package ? ` ${component.package}` : '';
42
- const meta = [pluralize(component.propCount, 'prop'), pluralize(component.exampleCount, 'example')].join(', ');
43
- return withFollowUp({
44
- line: `${name}${pkg} (${meta})`,
45
- followUp: component.followUp,
46
- invocation
29
+ return humanFormat.searchRow({
30
+ name: component.name,
31
+ package: component.package,
32
+ source: 'ads',
33
+ kind: 'component',
34
+ metadata: [pluralize(component.propCount, 'prop'), pluralize(component.exampleCount, 'example')],
35
+ followUp: component.followUp ? `${invocation} ${component.followUp}` : undefined
47
36
  });
48
37
  };
49
38
 
@@ -51,11 +40,12 @@ const formatComponentLine = (component, invocation) => {
51
40
  * Render one token as a compact `name = value` line.
52
41
  */
53
42
  const formatTokenLine = (tokenResult, invocation) => {
54
- const line = tokenResult.exampleValue ? `${tokenResult.name} = ${tokenResult.exampleValue}` : tokenResult.name;
55
- return withFollowUp({
56
- line,
57
- followUp: tokenResult.followUp,
58
- invocation
43
+ return humanFormat.searchRow({
44
+ name: tokenResult.name,
45
+ source: 'ads',
46
+ kind: 'token',
47
+ metadata: tokenResult.exampleValue ? [`= ${tokenResult.exampleValue}`] : undefined,
48
+ followUp: tokenResult.followUp ? `${invocation} ${tokenResult.followUp}` : undefined
59
49
  });
60
50
  };
61
51
 
@@ -63,13 +53,13 @@ const formatTokenLine = (tokenResult, invocation) => {
63
53
  * Render one icon as a compact line with its import package and short usage note.
64
54
  */
65
55
  const formatIconLine = (iconResult, invocation) => {
66
- const name = iconResult.componentName;
67
- const pkg = iconResult.package ? ` ${iconResult.package}` : '';
68
- const usage = iconResult.usage ? ` — ${iconResult.usage}` : '';
69
- return withFollowUp({
70
- line: `${name}${pkg}${usage}`,
71
- followUp: iconResult.followUp,
72
- invocation
56
+ return humanFormat.searchRow({
57
+ name: iconResult.componentName,
58
+ package: iconResult.package,
59
+ source: 'ads',
60
+ kind: 'icon',
61
+ metadata: iconResult.usage ? [iconResult.usage] : undefined,
62
+ followUp: iconResult.followUp ? `${invocation} ${iconResult.followUp}` : undefined
73
63
  });
74
64
  };
75
65
 
@@ -77,12 +67,12 @@ const formatIconLine = (iconResult, invocation) => {
77
67
  * Render one foundations-document match without dumping its full Markdown body.
78
68
  */
79
69
  const formatDocLine = (doc, invocation) => {
80
- const summary = doc.summary ? ` — ${doc.summary}` : '';
81
- const line = `${doc.title}${summary}`;
82
- return withFollowUp({
83
- line,
84
- followUp: doc.followUp,
85
- invocation
70
+ return humanFormat.searchRow({
71
+ name: doc.title,
72
+ source: 'ads',
73
+ kind: 'docs',
74
+ description: doc.summary,
75
+ followUp: doc.followUp ? `${invocation} ${doc.followUp}` : undefined
86
76
  });
87
77
  };
88
78
 
@@ -17,36 +17,21 @@ import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
17
17
  * A component payload as returned by `searchComponentsTool` / `getAllComponentsTool`.
18
18
  */
19
19
 
20
- /**
21
- * Collapse whitespace/newlines in a prop description so each prop stays on one readable line.
22
- */
23
- var oneLine = function oneLine(text) {
24
- return text.replace(/\s+/g, ' ').trim();
25
- };
20
+ import { humanFormat } from '@atlaskit/cli-output/human-format';
26
21
 
27
22
  /**
28
- * Render the props section as an aligned two-column list: `name type`, with the description on
29
- * a wrapped continuation line. Returns an empty array when there are no props.
23
+ * Render props through the shared terminal table used by Platform CLI. The shared formatter keeps
24
+ * names visually distinct, aligns columns, and bounds long generated type expressions.
30
25
  */
31
26
  var formatProps = function formatProps(props) {
32
- if (props.length === 0) {
33
- return ['Props: none'];
34
- }
35
-
36
- // Align the type column to the longest prop name for readability.
37
- var longestName = props.reduce(function (max, prop) {
27
+ return humanFormat.propertyTable(props.map(function (prop) {
38
28
  var _prop$name;
39
- return Math.max(max, ((_prop$name = prop.name) !== null && _prop$name !== void 0 ? _prop$name : '').length);
40
- }, 0);
41
- var rows = props.flatMap(function (prop) {
42
- var _prop$name2;
43
- var name = ((_prop$name2 = prop.name) !== null && _prop$name2 !== void 0 ? _prop$name2 : '(unknown)').padEnd(longestName);
44
- var type = prop.type ? oneLine(prop.type) : '';
45
- var header = " ".concat(name, " ").concat(type).trimEnd();
46
- var description = prop.description ? " ".concat(oneLine(prop.description)) : null;
47
- return description ? [header, description] : [header];
48
- });
49
- return ["Props (".concat(props.length, "):")].concat(_toConsumableArray(rows));
29
+ return {
30
+ name: (_prop$name = prop.name) !== null && _prop$name !== void 0 ? _prop$name : '(unknown)',
31
+ type: prop.type,
32
+ description: prop.description
33
+ };
34
+ }));
50
35
  };
51
36
 
52
37
  /**
@@ -59,7 +44,7 @@ var formatExamples = function formatExamples(examples) {
59
44
  }
60
45
  var blocks = examples.map(function (example, index) {
61
46
  var code = typeof example === 'string' ? example : JSON.stringify(example, null, 2);
62
- return ["Example ".concat(index + 1, ":"), '```tsx', code, '```'].join('\n');
47
+ return [humanFormat.section("Example ".concat(index + 1)), humanFormat.codeBlock(code)].join('\n');
63
48
  });
64
49
  return ["Examples (".concat(examples.length, "):"), ''].concat(_toConsumableArray(blocks));
65
50
  };
@@ -69,14 +54,22 @@ var formatExamples = function formatExamples(examples) {
69
54
  * data is not a recognisable component object, so the caller can fall back to generic rendering.
70
55
  */
71
56
  export var formatComponent = function formatComponent(data) {
72
- var _component$props, _component$examples, _component$designSour;
57
+ var _component$usageGuide, _component$props, _component$examples, _component$designSour;
73
58
  // `component <name>` reuses component search with limit 1, so `data` is a one-element array.
74
59
  var component = Array.isArray(data) ? data[0] : data;
75
60
  if (!component || _typeof(component) !== 'object' || typeof component.name !== 'string') {
76
61
  return null;
77
62
  }
78
- var header = component.package ? "".concat(component.name, " (").concat(component.package, ")") : component.name;
79
- var sections = [header, '='.repeat(header.length), ''].concat(_toConsumableArray(formatProps((_component$props = component.props) !== null && _component$props !== void 0 ? _component$props : [])));
63
+ var header = humanFormat.heading(component.name);
64
+ var metadata = humanFormat.metadata([component.status, component.category, component.package]);
65
+ var sections = [header].concat(_toConsumableArray(metadata ? [metadata] : []));
66
+ if (component.description) sections.push('', component.description);
67
+ if ((_component$usageGuide = component.usageGuidelines) !== null && _component$usageGuide !== void 0 && _component$usageGuide.length) {
68
+ sections.push.apply(sections, ['', humanFormat.section('Use it well')].concat(_toConsumableArray(component.usageGuidelines.slice(0, 4).map(function (item) {
69
+ return " ".concat(humanFormat.success('•'), " ").concat(item);
70
+ }))));
71
+ }
72
+ sections.push.apply(sections, [''].concat(_toConsumableArray(formatProps((_component$props = component.props) !== null && _component$props !== void 0 ? _component$props : []))));
80
73
  var examples = formatExamples((_component$examples = component.examples) !== null && _component$examples !== void 0 ? _component$examples : []);
81
74
  if (examples.length > 0) {
82
75
  sections.push.apply(sections, [''].concat(_toConsumableArray(examples)));
@@ -86,7 +79,7 @@ export var formatComponent = function formatComponent(data) {
86
79
  // URL is actually present, so a `designSource` object without a `figmaUrl` doesn't print
87
80
  // `Design: undefined`.
88
81
  if ((_component$designSour = component.designSource) !== null && _component$designSour !== void 0 && _component$designSour.figmaUrl) {
89
- sections.push('', "Design: ".concat(component.designSource.figmaUrl));
82
+ sections.push('', "".concat(humanFormat.section('Design:'), " ").concat(humanFormat.action(component.designSource.figmaUrl)));
90
83
  }
91
84
  return sections.join('\n');
92
85
  };
@@ -9,6 +9,7 @@ import _typeof from "@babel/runtime/helpers/typeof";
9
9
  * as `guidelines`, `bestPractices`, `nextSteps`). The default output prints this as readable text
10
10
  * rather than raw JSON; `--json` still exposes the full structured payload.
11
11
  */
12
+ import { humanFormat } from '@atlaskit/cli-output/human-format';
12
13
 
13
14
  /**
14
15
  * Convert a camelCase / snake_case field key into a human "Title Case" heading,
@@ -46,7 +47,7 @@ var formatListItem = function formatListItem(item) {
46
47
  var description = typeof record.description === 'string' ? [" ".concat(oneLine(record.description))] : [];
47
48
  var labelCodeBlocks = codeKeys.length > 1 || codeKeys[0] !== 'code';
48
49
  var codeBlocks = codeKeys.flatMap(function (key) {
49
- return [].concat(_toConsumableArray(labelCodeBlocks ? [" ".concat(humanizeKey(key), ":")] : []), [" ```tsx\n".concat(record[key], "\n ```")]);
50
+ return [].concat(_toConsumableArray(labelCodeBlocks ? [" ".concat(humanizeKey(key), ":")] : []), [humanFormat.codeBlock(record[key])]);
50
51
  });
51
52
  var additionalFields = Object.entries(record).flatMap(function (_ref) {
52
53
  var _ref2 = _slicedToArray(_ref, 2),
@@ -10,6 +10,7 @@ import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
10
10
  * left to the caller's generic fallback.
11
11
  */
12
12
 
13
+ import { humanFormat } from '@atlaskit/cli-output/human-format';
13
14
  import { CLI_BIN_NAME } from '../commands/cli-metadata';
14
15
  import { compactResults } from './compact-results';
15
16
 
@@ -20,19 +21,6 @@ var pluralize = function pluralize(count, noun) {
20
21
  return "".concat(count, " ").concat(noun).concat(count === 1 ? '' : 's');
21
22
  };
22
23
 
23
- /**
24
- * Append a distribution-specific invocation to a compact row's follow-up command.
25
- *
26
- * Used for every `search` result, where the natural next step is to view that match in full.
27
- * `--all` listings omit it because echoing every row's own name would just be noise.
28
- */
29
- var withFollowUp = function withFollowUp(_ref) {
30
- var line = _ref.line,
31
- followUp = _ref.followUp,
32
- invocation = _ref.invocation;
33
- return followUp ? "".concat(line, "\n \u2192 ").concat(invocation, " ").concat(followUp) : line;
34
- };
35
-
36
24
  /**
37
25
  * Render one component as a compact line.
38
26
  *
@@ -41,13 +29,13 @@ var withFollowUp = function withFollowUp(_ref) {
41
29
  * context and a tag would just be noise.
42
30
  */
43
31
  var formatComponentLine = function formatComponentLine(component, invocation) {
44
- var name = component.name;
45
- var pkg = component.package ? " ".concat(component.package) : '';
46
- var meta = [pluralize(component.propCount, 'prop'), pluralize(component.exampleCount, 'example')].join(', ');
47
- return withFollowUp({
48
- line: "".concat(name).concat(pkg, " (").concat(meta, ")"),
49
- followUp: component.followUp,
50
- invocation: invocation
32
+ return humanFormat.searchRow({
33
+ name: component.name,
34
+ package: component.package,
35
+ source: 'ads',
36
+ kind: 'component',
37
+ metadata: [pluralize(component.propCount, 'prop'), pluralize(component.exampleCount, 'example')],
38
+ followUp: component.followUp ? "".concat(invocation, " ").concat(component.followUp) : undefined
51
39
  });
52
40
  };
53
41
 
@@ -55,11 +43,12 @@ var formatComponentLine = function formatComponentLine(component, invocation) {
55
43
  * Render one token as a compact `name = value` line.
56
44
  */
57
45
  var formatTokenLine = function formatTokenLine(tokenResult, invocation) {
58
- var line = tokenResult.exampleValue ? "".concat(tokenResult.name, " = ").concat(tokenResult.exampleValue) : tokenResult.name;
59
- return withFollowUp({
60
- line: line,
61
- followUp: tokenResult.followUp,
62
- invocation: invocation
46
+ return humanFormat.searchRow({
47
+ name: tokenResult.name,
48
+ source: 'ads',
49
+ kind: 'token',
50
+ metadata: tokenResult.exampleValue ? ["= ".concat(tokenResult.exampleValue)] : undefined,
51
+ followUp: tokenResult.followUp ? "".concat(invocation, " ").concat(tokenResult.followUp) : undefined
63
52
  });
64
53
  };
65
54
 
@@ -67,13 +56,13 @@ var formatTokenLine = function formatTokenLine(tokenResult, invocation) {
67
56
  * Render one icon as a compact line with its import package and short usage note.
68
57
  */
69
58
  var formatIconLine = function formatIconLine(iconResult, invocation) {
70
- var name = iconResult.componentName;
71
- var pkg = iconResult.package ? " ".concat(iconResult.package) : '';
72
- var usage = iconResult.usage ? " \u2014 ".concat(iconResult.usage) : '';
73
- return withFollowUp({
74
- line: "".concat(name).concat(pkg).concat(usage),
75
- followUp: iconResult.followUp,
76
- invocation: invocation
59
+ return humanFormat.searchRow({
60
+ name: iconResult.componentName,
61
+ package: iconResult.package,
62
+ source: 'ads',
63
+ kind: 'icon',
64
+ metadata: iconResult.usage ? [iconResult.usage] : undefined,
65
+ followUp: iconResult.followUp ? "".concat(invocation, " ").concat(iconResult.followUp) : undefined
77
66
  });
78
67
  };
79
68
 
@@ -81,12 +70,12 @@ var formatIconLine = function formatIconLine(iconResult, invocation) {
81
70
  * Render one foundations-document match without dumping its full Markdown body.
82
71
  */
83
72
  var formatDocLine = function formatDocLine(doc, invocation) {
84
- var summary = doc.summary ? " \u2014 ".concat(doc.summary) : '';
85
- var line = "".concat(doc.title).concat(summary);
86
- return withFollowUp({
87
- line: line,
88
- followUp: doc.followUp,
89
- invocation: invocation
73
+ return humanFormat.searchRow({
74
+ name: doc.title,
75
+ source: 'ads',
76
+ kind: 'docs',
77
+ description: doc.summary,
78
+ followUp: doc.followUp ? "".concat(invocation, " ").concat(doc.followUp) : undefined
90
79
  });
91
80
  };
92
81
 
@@ -97,13 +86,13 @@ var formatDocLine = function formatDocLine(doc, invocation) {
97
86
  * `showFollowUp` (default `false`) adds a `→ <invocation> <command> <name>` drill-in hint beneath
98
87
  * each row. Search enables it for both grouped and `--type` output; `--all` listings leave it off.
99
88
  */
100
- export var formatCompactResults = function formatCompactResults(_ref2) {
101
- var kind = _ref2.kind,
102
- data = _ref2.data,
103
- _ref2$showFollowUp = _ref2.showFollowUp,
104
- showFollowUp = _ref2$showFollowUp === void 0 ? false : _ref2$showFollowUp,
105
- _ref2$invocation = _ref2.invocation,
106
- invocation = _ref2$invocation === void 0 ? CLI_BIN_NAME : _ref2$invocation;
89
+ export var formatCompactResults = function formatCompactResults(_ref) {
90
+ var kind = _ref.kind,
91
+ data = _ref.data,
92
+ _ref$showFollowUp = _ref.showFollowUp,
93
+ showFollowUp = _ref$showFollowUp === void 0 ? false : _ref$showFollowUp,
94
+ _ref$invocation = _ref.invocation,
95
+ invocation = _ref$invocation === void 0 ? CLI_BIN_NAME : _ref$invocation;
107
96
  var compact = compactResults({
108
97
  kind: kind,
109
98
  data: data,
@@ -1,11 +1,3 @@
1
- /**
2
- * Human-readable renderer for a single "doc object" payload — the shape returned by the
3
- * accessibility (`docs a11y`) and migration (`docs migration`) tools.
4
- *
5
- * These tools return a structured object (title, description, and several labelled lists such
6
- * as `guidelines`, `bestPractices`, `nextSteps`). The default output prints this as readable text
7
- * rather than raw JSON; `--json` still exposes the full structured payload.
8
- */
9
1
  /**
10
2
  * Render a doc-object payload as readable text. Handles both the full guide shape (a11y guidance,
11
3
  * migration guide — keyed by `title`) and the topic-index shape the a11y tool returns when no
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atlaskit/ads-cli",
3
- "version": "0.10.0",
3
+ "version": "0.11.0",
4
4
  "description": "An npx-runnable command-line tool to query Atlassian Design System (ADS) structured content — components, tokens, icons, and guidelines — from the terminal.",
5
5
  "author": "Atlassian Pty Ltd",
6
6
  "license": "Apache-2.0",
@@ -32,6 +32,7 @@
32
32
  },
33
33
  "dependencies": {
34
34
  "@atlaskit/ads-mcp": "^1.10.0",
35
+ "@atlaskit/cli-output": "^0.1.0",
35
36
  "@babel/runtime": "^7.0.0",
36
37
  "chalk": "^4.1.2"
37
38
  },