@p-buddy/parkdown 0.0.2 → 0.0.4

package/src/api/utils.ts

@@ -1,161 +0,0 @@
-import type { CreateParser, MethodDefinitions, ParsingCandidates, TypeRecord } from "./types";
-
-const supportedTypes = ["string", "number", "boolean"] as const satisfies (keyof TypeRecord)[];
-
-const isSupportedType = (type: string): type is keyof TypeRecord => supportedTypes.includes(type as keyof TypeRecord);
-
-// This regex is used to parse function-like invocations such as "code(ts,some-meta)"
-// Breaking down the regex pattern:
-// ^ - Asserts position at the start of the string
-// ([a-zA-Z0-9_-]+) - Capture group 1: The function name
-//   [a-zA-Z0-9_-]+ - One or more alphanumeric characters, underscores, or hyphens
-// (?:\(([^)]*)\))? - Optional non-capturing group for the parameters section
-//   \( - Literal opening parenthesis
-//   ([^)]*) - Capture group 2: Zero or more characters that are not closing parentheses
-//   \) - Literal closing parenthesis
-//   ? - Makes the entire parameter section optional
-// $ - Asserts position at the end of the string
-const INVOCATION_REGEX = /^([a-zA-Z0-9_-]+)(?:\(([^)]*)\))?$/;
-
-export const parseInvocation = (input: string): { name: string, parameters: (string | undefined)[] } => {
-  const match = input.match(INVOCATION_REGEX);
-  if (!match) throw new Error(`Invalid invocation: ${input}`);
-
-  const [, name, rawParams = ""] = match;
-
-  if (!rawParams.trim()) return { name, parameters: [] };
-
-  const parameters = splitOnUnquotedComma(rawParams);
-  return { name, parameters };
-}
-
-const restIsUndefined = <T>(arr: T[], index: number) => {
-  for (let i = index + 1; i < arr.length; i++)
-    if (arr[i] !== undefined) return false;
-  return true;
-}
-
-export const splitOnUnquotedComma = (input: string): (string | undefined)[] => {
-  const result: (string | undefined)[] = [];
-
-  let current = "";
-  let inSingleQuotes = false;
-
-  for (let i = 0; i < input.length; i++) {
-    const ch = input[i];
-    const isSingleQuote = ch === "'";
-
-    if (isSingleQuote && input.at(i + 1) === "'") {
-      const triple = input.at(i + 2) === "'";
-      inSingleQuotes = !inSingleQuotes;
-      current += triple ? "'''" : "''";
-      i += triple ? 2 : 1;
-    } else if (isSingleQuote) {
-      inSingleQuotes = !inSingleQuotes;
-      current += ch;
-    } else if (ch === "," && !inSingleQuotes) {
-      result.push(current.trim());
-      current = "";
-    } else current += ch;
-  }
-
-  result.push(current.trim());
-
-  return result
-    .map(item => item === "" ? undefined : item ? stripSurroundingSingleQuotes(item) : undefined)
-    .filter((item, index, arr) => item !== undefined || !restIsUndefined(arr, index));
-}
-
-const stripSurroundingSingleQuotes = (input: string): string => {
-  const isWrapped = input.length >= 2 && input[0] === "'" && input.at(-1) === "'";
-  const isDoubleWrapped = isWrapped && (input.length >= 4 && input[1] === "'" && input.at(-2) === "'");
-  return !isWrapped || isDoubleWrapped ? input : input.slice(1, -1);
-};
-
-type ParsedParameterDefinition = { name: string; optional: boolean; type: keyof TypeRecord };
-type ParsedMethodDefinition = { name: string; parameters?: ParsedParameterDefinition[] };
-
-export const parseDefinition = <T extends string>(definition: T): ParsedMethodDefinition => {
-  // Match a method definition pattern:
-  // ^ - start of string
-  // (\w+) - capture group 1: one or more word characters (method name)
-  // (?:\(([^)]*)\))? - optional non-capturing group:
-  //   \( - literal opening parenthesis
-  //   ([^)]*) - capture group 2: zero or more characters that are not closing parenthesis (parameter list)
-  //   \) - literal closing parenthesis
-  const METHOD_REGEX = /^(\w+)(?:\(([^)]*)\))?/;
-
-  const methodMatch = definition.match(METHOD_REGEX);
-  if (!methodMatch) return { name: definition };
-
-  const [, methodName, paramString] = methodMatch;
-
-  if (!paramString) return { name: methodName };
-
-  // (\w+)    - Capture group 1: One or more word characters (parameter name)
-  // (\?)?    - Capture group 2: Optional question mark (indicates optional parameter)
-  // :        - Literal colon character
-  // \s*      - Zero or more whitespace characters
-  // ([^,]+)  - Capture group 3: One or more characters that are not commas (parameter type)
-  // /g       - Global flag: Find all matches in the string, not just the first one
-  const PARAM_REGEX = /(\w+)(\?)?:\s*([^,]+)/g;
-
-  const parameters: ParsedParameterDefinition[] = [];
-
-  let match: RegExpExecArray | null;
-  while ((match = PARAM_REGEX.exec(paramString)) !== null) {
-    const [, name, optSymbol, paramType] = match;
-    const type = paramType.trim();
-    if (!isSupportedType(type)) throw new Error(`Unsupported type: ${type}`);
-    parameters.push({ name, optional: optSymbol === "?", type });
-  }
-
-  return { name: methodName, parameters };
-}
-
-export const createParser: CreateParser = <T extends MethodDefinitions>(definitions: T) => {
-  const parsedDefinitions = definitions
-    .map(parseDefinition)
-    .reduce(
-      (map, { name, parameters }) => map.set(name, parameters),
-      new Map<string, ParsedParameterDefinition[] | undefined>()
-    );
-  return (query: string) => {
-    const { name, parameters } = parseInvocation(query);
-    if (!parsedDefinitions.has(name))
-      throw new Error(`Unknown method: ${name}`);
-
-    const parameterDefinitions = parsedDefinitions.get(name);
-    if (parameterDefinitions === undefined)
-      return { name } satisfies ParsingCandidates<[string]> as ParsingCandidates<T>;
-
-    if (parameters.length > parameterDefinitions.length) {
-      const requiredCount = parameterDefinitions.filter(({ optional }) => !optional).length;
-      const expected = requiredCount === parameterDefinitions.length
-        ? requiredCount.toString()
-        : `${requiredCount} - ${parameterDefinitions.length}`;
-      throw new Error(`Too many parameters: ${parameters.length} for method '${name}' (expected: ${expected})`);
-    }
-
-    return parameterDefinitions.reduce((acc, { name: param, optional, type }, index) => {
-      const value = parameters[index];
-
-      if (value === undefined)
-        if (optional) return acc;
-        else throw new Error(`Missing required parameter: ${param} for method '${name}'`);
-
-      switch (type) {
-        case "string":
-          acc[param] = value;
-          break;
-        case "number":
-        case "boolean":
-          acc[param] = JSON.parse(value);
-          break;
-      }
-      if (typeof acc[param] !== type)
-        throw new Error(`Invalid type: ${param} must be ${type}, got ${typeof acc[param]} for method '${name}'`);
-      return acc;
-    }, { name } as ParsingCandidates<T>);
-  }
-}

package/src/cli.ts

@@ -1,31 +0,0 @@
-#!/usr/bin/env node
-import { Command } from '@commander-js/extra-typings';
-import { version } from '../package.json';
-import { populateMarkdownInclusions, depopulateMarkdownInclusions } from '.';
-
-const program = new Command()
-  .version(version)
-  .option('--nw, --no-write', 'Do NOT write result to file (defaults to false)', false as boolean)
-  .option('--ni, --no-inclusions', 'Do NOT process file inclusions (defaults to false)', false as boolean)
-  .option('-d, --depopulate', 'Remove populated inclusions from the file', false as boolean)
-  .option('-f, --file <flag>', 'The file(s) to process', (value, arr) => (arr.push(value), arr), new Array<string>())
-  .option('-r, --remap-imports', 'Remap import specifiers in code blocks from one destination to another')
-  .parse();
-
-const { inclusions: noInclusions, depopulate, file, write: noWrite } = program.opts();
-
-
-if (file.length === 0) file.push("README.md");
-
-/** parkdown: process-order */
-const processors = [
-  [populateMarkdownInclusions, !noInclusions],
-  [depopulateMarkdownInclusions, depopulate],
-] as const;
-/** parkdown: process-order */
-
-for (const [processor] of processors.filter(([_, condition]) => condition))
-  for (const _file of file) {
-    const result = processor(_file, !noWrite);
-    if (noWrite) console.log(result);
-  }

package/src/include.test.ts

@@ -1,369 +0,0 @@
-import { describe, expect, test } from "vitest";
-import { dedent } from "ts-dedent";
-import { extractContent, getAllPositionNodes, nodeSort, parse } from "./utils";
-import { PsuedoFilesystem, lorem } from "./utils.test";
-import { join } from "node:path";
-import {
-  getReplacementTargets,
-  isSpecialLink,
-  applyHeadingDepth,
-  extendGetRelativePathContent,
-  recursivelyPopulateInclusions,
-  nodeDepthFinder,
-  specialComment,
-  isSpecialComment,
-  getTopLevelCommentBlocks,
-} from "./include";
-
-describe(isSpecialLink.name, () => {
-  const check = (md: string, expectation: boolean) =>
-    getAllPositionNodes(parse.md(md), "link")
-      .forEach(node => expect(isSpecialLink(node)).toBe(expectation));
-
-  const cases = {
-    "non-link": ["test", false],
-    "link has text": ["[test](http://example.com)", false],
-    "link has no text, but unsupported target": ["[](file.md)", false],
-    "web link": ["[](http://example.com)", true],
-    "relative file, same directory": ["[](./file.md)", true],
-    "relative file, different directory": ["[](../file.md)", true],
-  } as const;
-
-  for (const [description, [md, expectation]] of Object.entries(cases))
-    test(description, () => check(md, expectation));
-});
-
-describe(nodeDepthFinder.name, () => {
-  test("find depth in lorem", () => {
-    for (const markdown of lorem.md) {
-      const headings = markdown.split("\n")
-        .map((content, index) => ({ content, line: index + 1 }))
-        .filter(({ content }) => content.startsWith("#"))
-        .map(heading => ({ ...heading, depth: heading.content.match(/^#+/)?.[0].length }));
-      const ast = parse.md(markdown);
-      const findDepth = nodeDepthFinder(ast);
-      let index = headings.length - 1;
-      for (const node of getAllPositionNodes(ast).sort(nodeSort.reverse)) {
-        if (node.position.start.line < headings[index].line) index--;
-        const depth = findDepth(node);
-        expect(depth).toBe(headings[index].depth,);
-      }
-    }
-  });
-});
-
-describe('applyHeadingDepth', () => {
-  test('should increase heading levels by the specified depth', () => {
-    const markdown = "# Heading 1\n\n## Heading 2\n\n### Heading 3";
-    const result = applyHeadingDepth(markdown, 1);
-    expect(result).toBe("## Heading 1\n\n### Heading 2\n\n#### Heading 3");
-  });
-
-  test('should decrease heading levels by the specified depth', () => {
-    const markdown = "### Heading 3\n\n## Heading 2\n\n# Heading 1";
-    const result = applyHeadingDepth(markdown, -1);
-    expect(result).toBe("## Heading 3\n\n# Heading 2\n\n# Heading 1");
-  });
-
-  test('should cap heading levels at 6', () => {
-    const markdown = "#### Heading 4\n\n##### Heading 5\n\n###### Heading 6";
-    const result = applyHeadingDepth(markdown, 2);
-    expect(result).toBe("###### Heading 4\n\n###### Heading 5\n\n###### Heading 6");
-  });
-
-  test('should not modify non-heading content', () => {
-    const markdown = "# Heading 1\n\nSome regular text\n\n## Heading 2\n\n- List item 1\n- List item 2";
-    const result = applyHeadingDepth(markdown, 1);
-    expect(result).toBe("## Heading 1\n\nSome regular text\n\n### Heading 2\n\n- List item 1\n- List item 2");
-  });
-
-  test('should handle headings with different formatting', () => {
-    const markdown = "# *Italic Heading*\n\n## **Bold Heading**\n\n### `Code Heading`";
-    const result = applyHeadingDepth(markdown, 1);
-    expect(result).toBe("## *Italic Heading*\n\n### **Bold Heading**\n\n#### `Code Heading`");
-  });
-
-  test('should handle headings with special characters', () => {
-    const markdown = "# Heading with & special < characters >";
-    const result = applyHeadingDepth(markdown, 2);
-    expect(result).toBe("### Heading with & special < characters >");
-  });
-
-  test('should accept an existing AST as input', () => {
-    const markdown = "# Heading 1\n\n## Heading 2";
-    const ast = parse.md(markdown);
-    const result = applyHeadingDepth(markdown, 2, ast);
-    expect(result).toBe("### Heading 1\n\n#### Heading 2");
-  });
-});
-
-describe(getTopLevelCommentBlocks.name, () => {
-  test("problematic case", () => {
-    const content = dedent`
-      # Main heading
-
-      [](./child/README.md)
-      <!-- p▼ Begin -->
-      ## Child heading
-
-      [](./grandchild/README.md)
-      <!-- p▼ Begin -->
-      ### Grandchild heading
-
-      Hello!
-      <!-- p▼ End -->
-      <!-- p▼ End -->
-
-      End
-    `;
-    const ast = parse.md(content);
-    const openingComments = getAllPositionNodes(ast, "html").filter(isSpecialComment("begin"));
-    const closingComments = getAllPositionNodes(ast, "html").filter(isSpecialComment("end"));
-    expect(openingComments.length).toBe(2);
-    expect(closingComments.length).toBe(2);
-    const blocks = getTopLevelCommentBlocks(openingComments, closingComments);
-    expect(blocks.length).toBe(1);
-    expect(blocks[0].open).toBe(openingComments[0]);
-    expect(blocks[0].close).toBe(closingComments[1]);
-  })
-});
-
-describe(extendGetRelativePathContent.name, () => {
-  test('should call original function with resolved path', () => {
-    const filesystem = new PsuedoFilesystem({
-      root: { base: "", child: { a: "", b: "", nested: { a: "" } } }
-    }, { setContentToPath: true });
-
-    const fromRoot = (path: string) => filesystem.getFileFromAbsolutePath(join("root", path));
-
-    expect(fromRoot("./base")).toBe("root/base");
-    expect(fromRoot("./child/a")).toBe("root/child/a");
-    expect(fromRoot("./child/b")).toBe("root/child/b");
-    expect(fromRoot("./child/nested/a")).toBe("root/child/nested/a");
-
-    const extended = extendGetRelativePathContent(fromRoot, { url: "./child/a" });
-    expect(extended("../base")).toBe("root/base");
-    expect(extended("./a")).toBe("root/child/a");
-    expect(extended("./b")).toBe("root/child/b");
-    expect(extended("./nested/a")).toBe("root/child/nested/a");
-  });
-});
-
-
-
-describe(recursivelyPopulateInclusions.name, () => {
-  test("basic unpopulated", () => {
-    const filesystem = new PsuedoFilesystem({
-      "README.md": dedent`
-        # Main heading
-
-        [](./child/README.md)
-
-        End parent
-      `,
-      child: {
-        "README.md": dedent`
-          # Child heading
-
-          End child
-        `,
-      }
-    });
-
-    const fromRoot = (path: string) => filesystem.getFileFromAbsolutePath(join("", path));
-
-    const result = recursivelyPopulateInclusions(filesystem.getFileFromAbsolutePath("README.md"), 0, fromRoot);
-    expect(result).toBe(dedent`
-      # Main heading
-
-      [](./child/README.md)
-      ${specialComment.begin}
-      ## Child heading
-
-      End child
-      ${specialComment.end}
-
-      End parent
-    `)
-    expect(result).toBe(recursivelyPopulateInclusions(result, 0, fromRoot));
-  });
-
-  test('should apply modifications to all top-level links in a markdown file', () => {
-
-    const filesystem = new PsuedoFilesystem({
-      "README.md": dedent`
-        # Main heading
-
-        [](./child/README.md)
-
-        End
-      `,
-      child: {
-        "README.md": dedent`
-          # Child heading
-
-          [](./grandchild/README.md)
-          ${specialComment.begin}
-          THIS SHOULD BE DELETED 
-          ${specialComment.end}
-        `,
-        grandchild: {
-          "README.md": dedent`
-            # Grandchild heading
-
-            Hello!
-          `,
-        }
-      }
-    });
-
-    const fromRoot = (path: string) => filesystem.getFileFromAbsolutePath(join("", path));
-
-    const result = recursivelyPopulateInclusions(filesystem.getFileFromAbsolutePath("README.md"), 0, fromRoot);
-    expect(result).toBe(recursivelyPopulateInclusions(result, 0, fromRoot));
-  });
-
-  test('with code boundary', () => {
-    const filesystem = new PsuedoFilesystem({
-      "README.md": dedent`
-        # Main heading
-
-        [](./child/file.ts?boundary=boundary)
-
-        End
-      `,
-      child: {
-        "file.ts": dedent`
-          if (true) {
-            /* boundary */
-            const x = 5;
-            /* boundary */
-          }
-        `,
-      }
-    });
-
-    const fromRoot = (path: string) => filesystem.getFileFromAbsolutePath(join("", path));
-
-    const result = recursivelyPopulateInclusions(filesystem.getFileFromAbsolutePath("README.md"), 0, fromRoot);
-    expect(result).toBe(dedent`
-      # Main heading
-
-      [](./child/file.ts?boundary=boundary)
-      ${specialComment.begin}
-      \`\`\`ts
-      const x = 5;
-      \`\`\`
-      ${specialComment.end}
-      
-      End`
-    )
-  })
-
-  test('with wrapped in dropdown', () => {
-    const filesystem = new PsuedoFilesystem({
-      "README.md": dedent`
-        # Main heading
-
-        [](./child/README.md?tag=dropdown('Open-me,-please!'))
-      `,
-      child: {
-        "README.md": dedent`
-          Hello!
-        `,
-      }
-    });
-
-    const fromRoot = (path: string) => filesystem.getFileFromAbsolutePath(join("", path));
-
-    const result = recursivelyPopulateInclusions(filesystem.getFileFromAbsolutePath("README.md"), 0, fromRoot);
-    expect(result).toBe(dedent`
-      # Main heading
-
-      [](./child/README.md?tag=dropdown('Open-me,-please!'))
-      ${specialComment.begin}
-
-      <details>
-      <summary>Open me, please!</summary>
-      
-      Hello!
-      </details>
-
-      ${specialComment.end}`
-    );
-  })
-});
-
-describe(getReplacementTargets.name, () => {
-  test('should return empty array for no special links or comments', () => {
-    const emptyMarkdown = "# Just a heading\n\nNo special links or comments here.";
-    const emptyAst = parse.md(emptyMarkdown);
-    expect(getReplacementTargets(emptyMarkdown, emptyAst)).toEqual([]);
-  });
-
-  test('should handle single unpopulated special link (no closing comment)', () => {
-    const singleLinkMarkdown = "# Heading\n\n[](http://example.com)";
-    const singleLinkAst = parse.md(singleLinkMarkdown);
-    const singleLinkTargets = getReplacementTargets(singleLinkMarkdown, singleLinkAst);
-    expect(singleLinkTargets.length).toBe(1);
-    expect(singleLinkTargets[0].url).toBe("http://example.com");
-    expect(singleLinkTargets[0].headingDepth).toBe(1);
-    expect(extractContent(singleLinkMarkdown, singleLinkTargets[0])).toBe("[](http://example.com)");
-  });
-
-  test('should handle special link with closing comment', () => {
-    const linkWithCommentMarkdown =
-      "# Main heading\n\n" +
-      "## Section\n\n" +
-      "[](./file.md)\n" +
-      specialComment.begin + "\n" +
-      "Some content\n" +
-      specialComment.end;
-    const linkWithCommentAst = parse.md(linkWithCommentMarkdown);
-    const linkWithCommentTargets = getReplacementTargets(linkWithCommentMarkdown, linkWithCommentAst);
-    expect(linkWithCommentTargets.length).toBe(1);
-    expect(linkWithCommentTargets[0].url).toBe("./file.md");
-    expect(linkWithCommentTargets[0].headingDepth).toBe(2);
-    expect(
-      extractContent(linkWithCommentMarkdown, linkWithCommentTargets[0])
-    ).toBe(`[](./file.md)\n${specialComment.begin}\nSome content\n${specialComment.end}`);
-  });
-
-  test('should handle multiple links and comments', () => {
-    const complexMarkdown =
-      "# Main heading\n\n" +
-      "## First section\n\n" +
-      "[](./first.md)\n" +
-      specialComment.begin + "\n" +
-      "Some content\n" +
-      specialComment.end + "\n\n" +
-      "## Second section\n\n" +
-      "[](./second.md)\n" +
-      specialComment.begin + "\n" +
-      "More content\n" +
-      specialComment.end + "\n\n" +
-      "## Third section\n\n" +
-      "[](http://example.com)";
-    const complexAst = parse.md(complexMarkdown);
-    const complexTargets = getReplacementTargets(complexMarkdown, complexAst);
-    expect(complexTargets.length).toBe(3);
-
-    expect(complexTargets[0].url).toBe("./first.md");
-    expect(complexTargets[0].headingDepth).toBe(2);
-    expect(
-      extractContent(complexMarkdown, complexTargets[0])
-    ).toBe(`[](./first.md)\n${specialComment.begin}\nSome content\n${specialComment.end}`);
-
-    expect(complexTargets[1].url).toBe("./second.md");
-    expect(complexTargets[1].headingDepth).toBe(2);
-    expect(
-      extractContent(complexMarkdown, complexTargets[1])
-    ).toBe(`[](./second.md)\n${specialComment.begin}\nMore content\n${specialComment.end}`);
-
-    expect(complexTargets[2].url).toBe("http://example.com");
-    expect(complexTargets[2].headingDepth).toBe(2);
-    expect(
-      extractContent(complexMarkdown, complexTargets[2])
-    ).toBe("[](http://example.com)");
-  });
-});