import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
import { analyze, buildIndex, documentDeclarations, missingDocs, shiftSourceMap, toComment } from './api-docs.mjs';
import { parseReadme, rowNames, splitRow } from './readme.mjs';
const README = `# Widget
A widget that shows things. Put \`\` anywhere.
\`\`\`html
\`\`\`
## Inputs
| Name | Description |
|---|---|
| size | \`small\` or \`large\` |
| label / title | Text of the widget |
| width | \`tx-widget-part\`: width of a part |
| pattern | Matches \`a\\|b\` |
| inherited | Comes from the base |
| ripple | From the ripple host directive |
| missing | Not in the types |
## Outputs
| Name | Description |
|---|---|
| changed | The value changed |
## Methods
| Name | Description |
|---|---|
| open() | Opens the widget */ now |
| TxWidgetService.notify(text) | Sends a note |
| new TxPoller(config) | A poller |
## Slots
| Name | Description |
|---|---|
| txWidgetItem | \`\` — own item |
| txWidgetHeader | Content projected into the header |
## Pipes
| Name | Description |
|---|---|
| txShout: loud? | Upper case |
## Functions
| Name | Description |
|---|---|
| widgetSize(value) | Size of a widget |
| resolveField(item, path) | Re-exported |
## Constants
| Name | Description |
|---|---|
| TX_WIDGET_DEFAULT | The defaults |
## Inputs — tx-widget-footer
| Name | Description |
|---|---|
| size | Size of the footer |
## Keyboard
| Key | Action |
|---|---|
| Enter | Opens |
`;
const TYPES = `import * as i0 from "@angular/core";
import { resolveField } from '@tectra-ng/ui/table';
export declare function widgetSize(value: number): string;
export declare const TX_WIDGET_DEFAULT: {
size: string;
};
export declare class TxWidgetService {
notify(text: string): void;
}
export declare class TxPoller {
constructor(config: unknown);
}
export declare class TxWidgetItem {
readonly txWidgetItem: i0.InputSignal;
static ɵdir: i0.ɵɵDirectiveDeclaration;
}
export declare class TxWidget extends TxWidgetBase {
private secret;
readonly size: i0.InputSignal;
readonly text: i0.InputSignal;
readonly pattern: i0.InputSignal;
readonly unlisted: i0.InputSignal;
readonly changed: i0.OutputEmitterRef;
open(): void;
static ɵcmp: i0.ɵɵComponentDeclaration;
}
export declare class TxWidgetPart {
readonly width: i0.InputSignal;
static ɵcmp: i0.ɵɵComponentDeclaration;
}
export declare class TxWidgetFooter {
readonly size: i0.InputSignal;
static ɵcmp: i0.ɵɵComponentDeclaration;
}
export declare class TxShoutPipe {
transform(value: string): string;
static ɵpipe: i0.ɵɵPipeDeclaration;
}
export { resolveField };
`;
const BASE = `import * as i0 from "@angular/core";
export declare class TxWidgetBase {
readonly inherited: i0.InputSignal;
static ɵdir: i0.ɵɵDirectiveDeclaration;
}
`;
function docAbove(text, line) {
const lines = text.split('\n');
const index = lines.findIndex((candidate) => candidate.includes(line));
assert.notEqual(index, -1, `no line ${line}`);
const above = [];
for (let current = index - 1; current >= 0 && /^\s*(\/\*\*|\*)/.test(lines[current]); current -= 1) {
above.unshift(lines[current].trim());
}
return above.join('\n');
}
function run(options = {}) {
const analysis = analyze(TYPES, 'widget.d.ts');
const index = buildIndex([analysis, analyze(BASE, 'base.d.ts')]);
return documentDeclarations(TYPES, [{ text: README, docsUrl: 'https://tectra-ng.com/components/widget', ...options }], { analysis, index });
}
describe('readme', () => {
it('splits a table row and keeps escaped pipes and pipes in code', () => {
assert.deepEqual(splitRow('| a | b \\| c | `x | y` |'), ['a', 'b | c', '`x | y`']);
});
it('reads the names of a row', () => {
assert.deepEqual(rowNames('show()'), ['show']);
assert.deepEqual(rowNames('txPlural: forms, locale?'), ['txPlural']);
assert.deepEqual(rowNames('prev / next'), ['prev', 'next']);
assert.deepEqual(rowNames('`[(value)]`'), ['value']);
assert.deepEqual(rowNames('*txTableAction'), ['txTableAction']);
assert.deepEqual(rowNames('highlightCode(code, language)'), ['highlightCode']);
assert.deepEqual(rowNames('min, max'), ['min', 'max']);
});
it('reads the title, the intro, the first code block and the tables', () => {
const readme = parseReadme(README);
assert.equal(readme.title, 'Widget');
assert.equal(readme.intro, 'A widget that shows things. Put `` anywhere.');
assert.equal(readme.firstCode, ``);
const inputs = readme.sections.find((section) => section.heading === 'Inputs');
assert.equal(inputs.rows.find((row) => row.cell === 'width').scope, 'tx-widget-part');
assert.equal(inputs.rows.find((row) => row.cell === 'width').description, 'width of a part');
assert.equal(inputs.rows.find((row) => row.cell === 'pattern').description, 'Matches `a|b`');
assert.equal(readme.sections.find((section) => section.scope === 'tx-widget-footer').heading, 'Inputs');
});
it('takes only a selector as a row scope', () => {
const readme = parseReadme('# A\n\n## Outputs\n| Name | Description |\n|---|---|\n| loaded | `lazy`: data arrived |\n');
assert.equal(readme.sections[0].rows[0].scope, null);
});
});
describe('documentDeclarations', () => {
it('documents inputs by alias, outputs, methods and the main class', () => {
const { text } = run();
assert.equal(docAbove(text, 'readonly size: i0.InputSignal;'), '/** `small` or `large` */');
assert.equal(docAbove(text, 'readonly text:'), '/** Text of the widget */');
assert.equal(docAbove(text, 'readonly changed:'), '/** The value changed */');
assert.equal(docAbove(text, 'open(): void;'), '/** Opens the widget *\\/ now */');
assert.equal(
docAbove(text, 'export declare class TxWidget extends'),
'/**\n* A widget that shows things. Put `` anywhere.\n* @see https://tectra-ng.com/components/widget\n*/',
);
});
it('keeps scoped rows on their component and heading scopes off the others', () => {
const { text } = run();
assert.equal(docAbove(text, 'readonly width:'), '/** width of a part */');
const footer = text.slice(text.indexOf('class TxWidgetFooter'));
assert.equal(docAbove(footer, 'readonly size:'), '/** Size of the footer */');
});
it('documents slots with their own input, pipes, functions, constants and qualified methods', () => {
const { text } = run();
assert.match(docAbove(text, 'export declare class TxWidgetItem'), /own item/);
assert.equal(docAbove(text, 'readonly txWidgetItem:'), '/** `` — own item */');
assert.match(docAbove(text, 'export declare class TxShoutPipe'), /Upper case/);
assert.match(docAbove(text, 'export declare function widgetSize'), /Size of a widget/);
assert.match(docAbove(text, 'export declare const TX_WIDGET_DEFAULT'), /The defaults/);
assert.equal(docAbove(text, 'notify(text: string): void;'), '/** Sends a note */');
assert.match(docAbove(text, 'export declare class TxPoller'), /A poller/);
});
it('accepts inherited, host directive and re-exported names, and reports the rest', () => {
const { unmatched, undocumented } = run();
assert.deepEqual(unmatched, ['Inputs: missing']);
assert.deepEqual(undocumented, ['TxWidget.unlisted (input)']);
});
it('labels unmatched rows and scopes a page README to its class', () => {
const { unmatched, text } = run({ label: 'docs/widget.md', defaultScope: 'TxWidgetPart', mainClass: 'TxWidgetPart' });
assert.ok(unmatched.includes('docs/widget.md — Inputs (TxWidgetPart): size'));
assert.match(docAbove(text, 'export declare class TxWidgetPart'), /A widget that shows things/);
});
it('does nothing on a second run', () => {
const first = run();
const second = documentDeclarations(first.text, README);
assert.equal(second.documented, 0);
assert.equal(second.text, first.text);
});
it('counts the lines it inserts before each original line', () => {
const { text, inserted } = run();
const added = [...inserted.values()].reduce((sum, count) => sum + count, 0);
assert.equal(text.split('\n').length, TYPES.split('\n').length + added);
});
});
describe('helpers', () => {
it('writes one line or a block comment with the indent', () => {
assert.equal(toComment(['One'], ' '), '/** One */\n ');
assert.equal(toComment(['One', '@see x'], ' '), '/**\n * One\n * @see x\n */\n ');
});
it('shifts the mappings of a declaration map by the inserted lines', () => {
const map = JSON.stringify({ version: 3, mappings: 'AAAA;AACA;AACA' });
const shifted = JSON.parse(shiftSourceMap(map, new Map([[1, 2]])));
assert.equal(shifted.mappings, 'AAAA;;;AACA;AACA');
assert.equal(shiftSourceMap(map, new Map()), map);
});
});
describe('missingDocs', () => {
it('lists public declarations without JSDoc and skips component members, private and repeated names', () => {
const text = `import * as i0 from "@angular/core";
/** Documented. */
export declare function done(): void;
export declare function size(value: number): string;
export declare function size(value: string): string;
export declare const LIMIT = 3;
export type Mode = 'a' | 'b';
export interface Options {
/** Documented. */
text: string;
life?: number;
}
export declare class Service {
private secret;
protected hidden: string;
constructor(value: string);
/** Documented. */
send(): void;
get value(): string;
set value(next: string);
}
export declare class TxPart {
readonly hostStyle: string;
static ɵcmp: i0.ɵɵComponentDeclaration;
}
type Shape = typeof LIMIT;
interface Helper {
value: string;
}
declare function listed(): void;
export { listed };
`;
assert.deepEqual(
missingDocs(text).map((item) => `${item.kind} ${item.name}`),
['function size', 'constant LIMIT', 'type Mode', 'function listed', 'interface Options', 'field Options.life', 'class Service', 'member Service.value', 'component TxPart'],
);
});
});