Skip to content

Commit 55c9e7e

Browse files
authored
fix: keep content before the next heading when slicing tokens (#223)
findContentAfterList and findContentAfterHeadingClose computed the end index relative to a slice but used it as an absolute index, dropping the token before the next heading (often a code fence) or emptying the description entirely for structures and events. Assisted-by: Claude Fable 5.1
1 parent 404c38e commit 55c9e7e

3 files changed

Lines changed: 123 additions & 4 deletions

File tree

‎src/markdown-helpers.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -91,16 +91,18 @@ export const findContentAfterList = (tokens: Token[], returnAllOnNoList = false)
9191
if (!returnAllOnNoList) return [];
9292
start = tokens.findIndex((t) => t.type === 'heading_close');
9393
}
94+
// `end` is relative to `start`, so offset it back into `tokens` coordinates
9495
const end = tokens.slice(start).findIndex((t) => t.type === 'heading_open');
9596
if (end === -1) return tokens.slice(start + 1);
96-
return tokens.slice(start + 1, end);
97+
return tokens.slice(start + 1, start + end);
9798
};
9899

99100
export const findContentAfterHeadingClose = (tokens: Token[]) => {
100101
const start = tokens.findIndex((t) => t.type === 'heading_close');
102+
// `end` is relative to `start`, so offset it back into `tokens` coordinates
101103
const end = tokens.slice(start).findIndex((t) => t.type === 'heading_open');
102104
if (end === -1) return tokens.slice(start + 1);
103-
return tokens.slice(start + 1, end);
105+
return tokens.slice(start + 1, start + end);
104106
};
105107

106108
export type HeadingContent = {

‎tests/DocsParser.spec.ts‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,43 @@ A \`string\` property that indicates the current application's name.
7979
expect(appModule.properties[0].name).toBe('name');
8080
});
8181

82+
it('should include a code fence at the end of a module description', async () => {
83+
const moduleContent = `# app
84+
85+
> Control your application's event lifecycle.
86+
87+
Process: [Main](../glossary.md#main-process)
88+
89+
The following example shows how to quit the application when the last window
90+
is closed:
91+
92+
\`\`\`js
93+
const { app } = require('electron')
94+
app.on('window-all-closed', () => {
95+
app.quit()
96+
})
97+
\`\`\`
98+
99+
## Methods
100+
101+
### \`app.quit()\`
102+
103+
Try to close all windows.
104+
`;
105+
106+
const modulePath = path.join(tempDir, 'docs', 'api', 'app.md');
107+
await fs.promises.writeFile(modulePath, moduleContent);
108+
109+
const parser = new DocsParser(tempDir, '1.0.0', [modulePath], [], 'single');
110+
const result = await parser.parse();
111+
112+
const appModule = result.find((m) => m.name === 'app');
113+
assert(appModule?.type === 'Module', 'Parsed module should be of type Module');
114+
expect(appModule.description).toContain('is closed:');
115+
expect(appModule.description).toContain("const { app } = require('electron')");
116+
expect(appModule.description).not.toContain('Try to close all windows');
117+
});
118+
82119
it('should parse a class documentation', async () => {
83120
const classContent = `# BrowserWindow
84121
@@ -354,6 +391,34 @@ Additional description after the property list.
354391
expect(rectangleStructure.properties[3].name).toBe('height');
355392
});
356393

394+
it('should keep the description when a heading follows the property list', async () => {
395+
const structureContent = `# PrinterInfo Object
396+
397+
* \`name\` string - The name of the printer as understood by the OS.
398+
* \`status\` number - The current status of the printer.
399+
400+
The number represented by \`status\` means different things on different platforms.
401+
402+
## Example
403+
404+
Below is an example of some of the additional options that may be set.
405+
`;
406+
407+
const structurePath = path.join(tempDir, 'docs', 'api', 'structures', 'printer-info.md');
408+
await fs.promises.writeFile(structurePath, structureContent);
409+
410+
const parser = new DocsParser(tempDir, '1.0.0', [], [structurePath], 'single');
411+
const result = await parser.parse();
412+
413+
const printerInfo = result.find((s) => s.name === 'PrinterInfo');
414+
assert(printerInfo?.type === 'Structure', 'Parsed structure should be of type Structure');
415+
416+
expect(printerInfo.properties).toHaveLength(2);
417+
expect(printerInfo.description).toBe(
418+
'The number represented by `status` means different things on different platforms.',
419+
);
420+
});
421+
357422
it('should parse a structure with optional properties', async () => {
358423
const structureContent = `# Options Object
359424

‎tests/markdown-helpers.spec.ts‎

Lines changed: 54 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -862,6 +862,36 @@ After nested list.
862862
const joined = safelyJoinTokens(content);
863863
expect(joined).toContain('After nested list');
864864
});
865+
866+
it('should return all content between the list and the next heading', () => {
867+
const md = `# Heading
868+
869+
* Item 1
870+
* Item 2
871+
872+
First paragraph after the list.
873+
874+
Second paragraph after the list.
875+
876+
\`\`\`js
877+
const code = 'fence'
878+
\`\`\`
879+
880+
## Next Heading
881+
882+
Content that should not be included.
883+
`;
884+
const tokens = getTokens(md);
885+
const content = findContentAfterList(tokens);
886+
expect(content[0].type).toBe('paragraph_open');
887+
expect(content[content.length - 1].type).toBe('fence');
888+
const joined = safelyJoinTokens(content, { parseCodeFences: true });
889+
expect(joined).toContain('First paragraph after the list.');
890+
expect(joined).toContain('Second paragraph after the list.');
891+
expect(joined).toContain("const code = 'fence'");
892+
expect(joined).not.toContain('Next Heading');
893+
expect(joined).not.toContain('should not be included');
894+
});
865895
});
866896

867897
describe('findContentAfterHeadingClose', () => {
@@ -885,8 +915,30 @@ Content for heading one.
885915
Content for heading two.`;
886916
const tokens = getTokens(md);
887917
const content = findContentAfterHeadingClose(tokens);
888-
// The function returns tokens, check that we got some
889-
expect(content.length).toBeGreaterThan(0);
918+
expect(content[0].type).toBe('paragraph_open');
919+
expect(content[content.length - 1].type).toBe('paragraph_close');
920+
const joined = safelyJoinTokens(content);
921+
expect(joined).toBe('Content for heading one.');
922+
});
923+
924+
it('should not drop a trailing code fence before the next heading', () => {
925+
const md = `# Heading One
926+
927+
Content for heading one.
928+
929+
\`\`\`js
930+
const code = 'fence'
931+
\`\`\`
932+
933+
## Heading Two
934+
935+
Content for heading two.`;
936+
const tokens = getTokens(md);
937+
const content = findContentAfterHeadingClose(tokens);
938+
expect(content[content.length - 1].type).toBe('fence');
939+
const joined = safelyJoinTokens(content, { parseCodeFences: true });
940+
expect(joined).toContain("const code = 'fence'");
941+
expect(joined).not.toContain('Content for heading two.');
890942
});
891943
});
892944

0 commit comments

Comments
 (0)