@p-buddy/parkdown 0.0.1 → 0.0.3

package/.assets/populated/inline.single.md

@@ -1,3 +0,0 @@
-Before... [](<url>) <!-- p▼ Begin -->
-...Included Content...
-...Included Content... <!-- p▼ End --> ...After

package/.assets/query.md

@@ -1,73 +0,0 @@
-# Query parameters
-
-You can pass query parameters to your inclusion links to control how their content is processed and included within your markdown.
-
-## Processing Order
-
-[](../src/include.ts?&region=extract(query))
-
-## `region`
-
-Either extract, remove, or replace content from the included file based on the provided specifier(s).
-
-Specifiers will be searched for within the file's comments, and are expected to come in pairs / bookend the desired region, like so:
-
-```ts
-/** some-specifier */
-... code to find ...
-/** some-specifier */
-```
-
-```md
-[](...?region=extract(some-specifier))
-```
-
-Below is the currently supported API for the `region` query parameter, where each defined method signature can be _invoked_ as a value for the `region` parameter (e.g. `[](<url>?region=extract(some-specifier))`, `[](<url>?region=remove(some-specifier))`, `[](<url>?region=replace(some-specifier))`).
-
-[](./api-note.md?wrap=quote)
-
-[](../src/region.ts?region=extract(definition))
-
-## `skip`
-
-Skip the default processing behavior for the given type of file. 
-
-[](../src/include.ts?wrap=dropdown(See-default-processing-behavior.)&region=extract(Default-Behavior),replace(...))
-
-```md
-[](<url>?skip)
-```
-
-## `heading` 
-
-Modify the heading depth applied to included content. By default, the headings of the included content are adjusted to be one-level below their parent heading.
-
-In the following example, the headings within the included content of `<url>` will be adjusted to one-level below the parent heading (which is an `h2` / `##`), so any `#` headings will be converted to `###` headings, and `##` headings will be converted to `####` headings, and so on.
-
-```md
-## Heading
-
-[](<url>)
-```
-
-The following would then ensure that the headings of the included content are at the same level as the parent heading.
-
-```md
-## Heading
-
-[](<url>?heading=-1)
-```
-
-A value of `-2` would result in the headings of the included content being at their original level (since the content is being included underneath an `h2` / `##` heading).
-
-## `inline` (Advanced)
-
-## `wrap`
-
-Wrap the content of the included file in a specific kind of element.
-
-Below is the currently supported API for the `wrap` query parameter, where each defined method signature can be _invoked_ as a value for the `wrap` parameter (e.g. `[](<url>?wrap=code)`, `[](<url>?wrap=dropdown(hello-world))`).
-
-[](./api-note.md?wrap=quote)
-
-[](../src/wrap.ts?region=extract(definition))

package/.assets/unpopulated/block.md

@@ -1,5 +0,0 @@
-Before...
-
-[](<url>)
-
-...After

package/.assets/unpopulated/inline.multi.md

@@ -1,3 +0,0 @@
-Before... 
-[](<url>)
-...After

package/.assets/unpopulated/inline.single.md

@@ -1 +0,0 @@
-Before... [](<url>) ...After

package/.devcontainer/Dockerfile

@@ -1,16 +0,0 @@
-# See here for image contents: https://github.com/microsoft/vscode-dev-containers/tree/v0.187.0/containers/typescript-node/.devcontainer/base.Dockerfile
-
-# [Choice] Node.js version: 16, 18, 20
-ARG VARIANT="20-buster"
-FROM mcr.microsoft.com/vscode/devcontainers/typescript-node:0-${VARIANT}
-
-# [Optional] Uncomment this section to install additional OS packages.
-# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
-#     && apt-get -y install --no-install-recommends <your-package-list-here>
-
-# [Optional] Uncomment if you want to install an additional version of node using nvm
-# ARG EXTRA_NODE_VERSION=10
-# RUN su node -c "source /usr/local/share/nvm/nvm.sh && nvm install ${EXTRA_NODE_VERSION}"
-
-# To install more global node packages
-RUN su node -c "npm install -g pnpm@10"

package/.devcontainer/devcontainer.json

@@ -1,35 +0,0 @@
-{
-  "name": "parkdown-dev",
-  "dockerFile": "Dockerfile",
-  "customizations": {
-    "vscode": {
-      "extensions": [
-        "ms-vscode.vscode-typescript-next",
-        "svelte.svelte-vscode",
-        "ms-azuretools.vscode-docker",
-        "bradlc.vscode-tailwindcss",
-        "YoavBls.pretty-ts-errors"
-      ]
-    }
-  },
-  "postStartCommand": [
-    "bash",
-    "-c",
-    "git config --global user.name \"${GIT_USER_NAME}\"",
-    "bash",
-    "-c",
-    "git config --global user.email \"${GIT_USER_EMAIL}\"",
-    "bash",
-    "-c",
-    "pnpm install"
-  ],
-  "mounts": [
-    "source=${localEnv:HOME}/.ssh,target=/home/node/.ssh,type=bind,readonly"
-  ],
-  "containerEnv": {
-    "NPM_TOKEN": "${localEnv:PARKDOWN_NPM_TOKEN}",
-    "HOST_WORKSPACE_PATH": "${localWorkspaceFolder}",
-    "GIT_USER_NAME": "${localEnv:GIT_USER_NAME}",
-    "GIT_USER_EMAIL": "${localEnv:GIT_USER_EMAIL}"
-  }
-}

package/src/api/index.test.ts

@@ -1,32 +0,0 @@
-import { describe, expect, test } from "vitest";
-import { MethodDefinition } from "./types";
-import { numberedParameters, createParser } from "./index";
-
-describe(numberedParameters.name, () => {
-  test("simple", () => {
-    const definitions = [
-      "example(0: string, 1?: string)" satisfies MethodDefinition,
-    ] as const;
-
-    const result = createParser(definitions)("example(z,a)");
-    expect(numberedParameters(result)).toEqual(["z", "a"]);
-  });
-
-  test("mixed types", () => {
-    const definitions = [
-      "example(0: string, 1?: string, 2: boolean)" satisfies MethodDefinition,
-    ] as const;
-
-    const result = createParser(definitions)("example(z,a,true)");
-    expect(numberedParameters(result)).toEqual(["z", "a", true]);
-  });
-
-  test("mixed positions", () => {
-    const definitions = [
-      "example(0: string, hi: string, 1: boolean)" satisfies MethodDefinition,
-    ] as const;
-
-    const result = createParser(definitions)("example(z,hi,true)");
-    expect(numberedParameters(result)).toEqual(["z", true]);
-  });
-});

package/src/api/index.ts

@@ -1,8 +0,0 @@
-export type { MethodDefinition } from "./types";
-import type { Parser } from "./types";
-export { createParser } from "./utils";
-
-export const numberedParameters = (result: ReturnType<Parser<any>>) =>
-  Object.entries(result)
-    .filter(([key]) => key !== "name" && !isNaN(Number(key)))
-    .map(([_, value]) => value);

package/src/api/types.ts

@@ -1,78 +0,0 @@
-export type TypeRecord = {
-  "string": string,
-  "number": number,
-  "boolean": boolean,
-}
-
-type ExpandRecursively<T> =
-  T extends (...args: infer A) => infer R
-  /**/ ? (...args: ExpandRecursively<A>) => ExpandRecursively<R>
-  /**/ : T extends object
-    /**/ ? T extends infer O
-      /**/ ? { [K in keyof O]: ExpandRecursively<O[K]> }
-      /**/ : never
-    /**/ : T;
-
-type WithoutLeadingWhitespace<T extends string> = T extends ` ${infer Without}` ? Without : T;
-
-type SplitOn<T extends string, Delimeter extends string> =
-  T extends `${infer Left}${Delimeter}${infer Right}` ? [Left, ...SplitOn<Right, Delimeter>] : [T];
-
-type RepeatInTuple<Element, Count extends number, Acc extends unknown[] = []> = {
-  [k in Count]: Acc['length'] extends k
-  ? Acc
-  : RepeatInTuple<Element, k, [...Acc, Element]>;
-}[Count];
-
-type Join<T extends string[], D extends string> =
-  T extends []
-    /**/ ? ''
-    /**/ : T extends [infer F extends string]
-      /**/ ? F
-      /**/ : T extends [infer F extends string, ...infer R extends string[]]
-        /**/ ? `${F}${D}${Join<R, D>}`
-        /**/ : string;
-
-type Capture<T extends string, Start extends string, End extends string> = {
-  [k in T]: k extends `${infer Before}${Start}${infer Captured}${End}${infer After}`
-  /**/ ? { before: Before, captured: Captured, after: After }
-  /**/ : { before: T, captured: "", after: "" };
-}[T]
-
-type SplitOnComma<T extends string> = { [k in SplitOn<T, ",">[number]]: k }[SplitOn<T, ",">[number]];
-
-type Parameter<Name extends string, Optional extends boolean, Type extends TypeRecord[keyof TypeRecord]> = { name: Name, optional: Optional, type: Type };
-
-type ExtractParameter<T extends string> = T extends `${infer Name}?: ${infer Type extends keyof TypeRecord}`
-/**/ ? Parameter<Name, true, Type>
-/**/ : T extends `${infer Name}: ${infer Type extends keyof TypeRecord}`
-  /**/ ? Parameter<Name, false, Type>
-  /**/ : never;
-
-type FunctionName<T extends string> = Capture<T, "(", ")">["before"];
-
-type ParameterRecord<T extends string> = {
-  [k in WithoutLeadingWhitespace<SplitOnComma<Capture<T, "(", ")">["captured"]>> as ExtractParameter<k>["name"]]: ExtractParameter<k>["optional"] extends true ? TypeRecord[ExtractParameter<k>["type"]] | undefined : TypeRecord[ExtractParameter<k>["type"]]
-}
-
-type UndefinedToOptional<T> = {
-  [K in keyof T as undefined extends T[K] ? K : never]?: Exclude<T[K], undefined>;
-} & {
-  [K in keyof T as undefined extends T[K] ? never : K]: T[K];
-};
-
-type ParseMethodDefinition<T extends string> = { [t in T as FunctionName<t>]: UndefinedToOptional<ParameterRecord<t>> };
-
-type ParameterDefinition = `${string}${"?" | ""}: ${keyof TypeRecord}`;
-/** Can add more parameters by adding more numbers to the count union, but it adds a lot of complexity to the type */
-type ZeroOrMoreParameters = Join<RepeatInTuple<ParameterDefinition, 0 | 1 | 2>, ", ">;
-export type MethodDefinition = `${string}(${ZeroOrMoreParameters})`;
-
-export type MethodDefinitions = string[] | readonly string[];
-
-export type ParsingCandidates<T extends MethodDefinitions> = ExpandRecursively<{
-  [k in keyof ParseMethodDefinition<T[number]>]: ParseMethodDefinition<T[number]>[k] & { name: k }
-}[keyof ParseMethodDefinition<T[number]>]>;
-
-export type Parser<T extends MethodDefinitions> = (query: string) => ParsingCandidates<T>;
-export type CreateParser = <T extends MethodDefinitions>(definitions: T) => Parser<T>;

package/src/api/utils.test.ts

@@ -1,132 +0,0 @@
-import { describe, test, expect } from "vitest";
-import { parseInvocation, parseDefinition, createParser, splitOnUnquotedComma } from "./utils";
-import { MethodDefinition } from "./types";
-import { COMMA_NOT_IN_PARENTHESIS } from "../utils";
-
-describe(parseInvocation.name, () => {
-  const testCases = [
-    ["code(ts,some-meta)", { name: "code", parameters: ["ts", "some-meta"] }],
-    ["code", { name: "code", parameters: [] }],
-    ["code()", { name: "code", parameters: [] }],
-    ["code(ts)", { name: "code", parameters: ["ts"] }],
-    ["code(,some-meta)", { name: "code", parameters: [undefined, "some-meta"] }],
-    ["code(,some-meta,,,)", { name: "code", parameters: [undefined, "some-meta"] }],
-    ["dropdown(hello-world,true)", { name: "dropdown", parameters: ["hello-world", "true"] }],
-    ["code(,,anything)", { name: "code", parameters: [undefined, undefined, "anything"] }],
-  ] as const;
-
-  for (const [input, expected] of testCases) {
-    test(input, () => {
-      expect(parseInvocation(input)).toEqual(expected);
-    });
-  }
-});
-
-describe(parseDefinition.name, () => {
-  const testCases = [
-    ["code(lang?: string, meta?: string)", {
-      name: "code",
-      parameters: [
-        { name: "lang", optional: true, type: "string" },
-        { name: "meta", optional: true, type: "string" }
-      ]
-    }],
-    ["quote", { name: "quote" }],
-    ["dropdown(summary: string, open?: boolean)", {
-      name: "dropdown",
-      parameters: [
-        { name: "summary", optional: false, type: "string" },
-        { name: "open", optional: true, type: "boolean" }
-      ]
-    }],
-    ["allTypes(a: string, b: boolean, c: number, d?: string, e?: boolean, f?: number)", {
-      name: "allTypes",
-      parameters: [
-        { name: "a", optional: false, type: "string" },
-        { name: "b", optional: false, type: "boolean" },
-        { name: "c", optional: false, type: "number" },
-        { name: "d", optional: true, type: "string" },
-        { name: "e", optional: true, type: "boolean" },
-        { name: "f", optional: true, type: "number" },
-      ]
-    }]
-  ] as const;
-
-  for (const [input, expected] of testCases) {
-    test(input, () => {
-      expect(parseDefinition(input)).toEqual(expected);
-    });
-  }
-});
-
-describe(createParser.name, () => {
-  const definitions = [
-    "code(lang?: string, meta?: string)" satisfies MethodDefinition,
-    "quote",
-    "dropdown(summary: string, open?: boolean)" satisfies MethodDefinition,
-  ] as const;
-
-  const parse = createParser(definitions);
-
-  const invocations = [
-    ["code", { name: "code" }],
-    ["code()", { name: "code" }],
-    ["code(ts)", { name: "code", lang: "ts" }],
-    ["code(ts,some-meta)", { name: "code", lang: "ts", meta: "some-meta" }],
-    ["code(,some-meta)", { name: "code", meta: "some-meta" }],
-    ["code(,some-meta,)", { name: "code", meta: "some-meta" }],
-    ["code(,,anything)", { error: true }],
-    ["quote", { name: "quote" }],
-    ["quote()", { name: "quote" }],
-    ["dropdown()", { error: true }],
-    ["dropdown(,true)", { error: true }],
-    ["dropdown(hello-world,true)", { name: "dropdown", summary: "hello-world", open: true }],
-    ["dropdown('hello world',true)", { name: "dropdown", summary: "hello world", open: true }],
-
-  ] as const;
-
-  for (const [input, expected] of invocations) {
-    test(input, () => {
-      if ('error' in expected) {
-        expect(() => parse(input)).toThrow();
-      } else {
-        expect(parse(input)).toEqual(expected);
-      }
-    });
-  }
-
-});
-
-
-describe("split on non-parenthesized comma", () => {
-  const testCases = [
-    ["hello,world", ["hello", "world"]],
-    ["code(,,anything), code, quote, dropdown(hello-world,true)", ["code(,,anything)", "code", "quote", "dropdown(hello-world,true)"]],
-  ] as const;
-
-  for (const [input, expected] of testCases) {
-    test(input, () => {
-      expect(input.split(COMMA_NOT_IN_PARENTHESIS)).toEqual(expected);
-    });
-  }
-
-});
-
-
-describe(splitOnUnquotedComma.name, () => {
-  test("simple", () => {
-    expect(splitOnUnquotedComma("hello,world")).toEqual(["hello", "world"]);
-  });
-
-  test("single quotes", () => {
-    expect(splitOnUnquotedComma("hello,'hello,world',hello")).toEqual(["hello", "hello,world", "hello"]);
-  });
-
-  test("preserve dual single quotes", () => {
-    expect(splitOnUnquotedComma("hello,''hello,world'',hello")).toEqual(["hello", "''hello,world''", "hello"]);
-  });
-
-  test("preserve triple double quotes", () => {
-    expect(splitOnUnquotedComma("hello,'''hello,world''',hello")).toEqual(["hello", "'''hello,world'''", "hello"]);
-  });
-})

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);
-  }