From e0ec8db5c263b743697de9f5715f8791759b54c2 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Tue, 3 Dec 2024 14:38:50 -0500 Subject: [PATCH 1/2] docs: streamlined and organized DEVELOPMENT.md --- .github/DEVELOPMENT.md | 21 +++---- .../dotGitHub/createDevelopment/index.test.ts | 22 ++++++-- .../dotGitHub/createDevelopment/index.ts | 56 ++++++++++++------- 3 files changed, 60 insertions(+), 39 deletions(-) diff --git a/.github/DEVELOPMENT.md b/.github/DEVELOPMENT.md index 30091f435..23bb3cfee 100644 --- a/.github/DEVELOPMENT.md +++ b/.github/DEVELOPMENT.md @@ -28,6 +28,12 @@ Add `--watch` to run the builder in a watch mode that continuously cleans and re pnpm build --watch ``` +### Built App Debugging + +This repository includes a [VS Code launch configuration](https://code.visualstudio.com/docs/editor/debugging) for debugging. +To debug a `bin` app, add a breakpoint to your code, then run _Debug Program_ from the VS Code Debug panel (or press F5). +VS Code will automatically run the `build` task in the background before running `./bin/index.js`. + ## Formatting [Prettier](https://prettier.io) is used to format code. @@ -58,7 +64,7 @@ For example, ESLint can be run with `--fix` to auto-fix some lint rule complaint pnpm run lint --fix ``` -Note that you'll likely need to run `pnpm build` before `pnpm lint` so that lint rules which check the file system can pick up on any built files. +Note that you'll need to run `pnpm build` before `pnpm lint` so that lint rules which check the file system can pick up on any built files. ## Testing @@ -99,19 +105,6 @@ Add `--watch` to keep the type checker running in a watch mode that updates the pnpm tsc --watch ``` -## Debugging - -This repository includes a [VS Code launch configuration](https://code.visualstudio.com/docs/editor/debugging) for debugging. -Depending upon the type of usage, it can include debugging for unit tests _and_ for executable (or "bin") apps. - -### Unit Tests - -To debug a unit test, open a test file, then run _Debug Current Test File_ from the VS Code Debug panel (or press F5). - -### `bin` Apps - -To debug a `bin` app, add a breakpoint to your code, then run _Debug Program_ from the VS Code Debug panel (or press F5). - ## Setup Scripts As described in the `README.md` file and `docs/`, this template repository comes with three scripts that can set up an existing or new repository. diff --git a/src/steps/writing/creation/dotGitHub/createDevelopment/index.test.ts b/src/steps/writing/creation/dotGitHub/createDevelopment/index.test.ts index cddd40e5d..0dd4598ab 100644 --- a/src/steps/writing/creation/dotGitHub/createDevelopment/index.test.ts +++ b/src/steps/writing/creation/dotGitHub/createDevelopment/index.test.ts @@ -87,7 +87,7 @@ describe("createDevelopment", () => { - \`pnpm lint\` ([ESLint](https://eslint.org) with [typescript-eslint](https://typescript-eslint.io)): Lints JavaScript and TypeScript source files - \`pnpm lint:knip\` ([knip](https://github.com/webpro/knip)): Detects unused files, dependencies, and code exports - - \`pnpm lint:md\` ([Markdownlint](https://github.com/DavidAnson/markdownlint): Checks Markdown source files + - \`pnpm lint:md\` ([Markdownlint](https://github.com/DavidAnson/markdownlint)): Checks Markdown source files - \`pnpm lint:packages\` ([pnpm dedupe --check](https://pnpm.io/cli/dedupe)): Checks for unnecessarily duplicated packages in the \`pnpm-lock.yml\` file - \`pnpm lint:spelling\` ([cspell](https://cspell.org)): Spell checks across all source files @@ -99,7 +99,7 @@ describe("createDevelopment", () => { pnpm run lint --fix \`\`\` - Note that you'll likely need to run \`pnpm build\` before \`pnpm lint\` so that lint rules which check the file system can pick up on any built files. + Note that you'll need to run \`pnpm build\` before \`pnpm lint\` so that lint rules which check the file system can pick up on any built files. ## Testing @@ -216,7 +216,7 @@ describe("createDevelopment", () => { pnpm run lint --fix \`\`\` - Note that you'll likely need to run \`pnpm build\` before \`pnpm lint\` so that lint rules which check the file system can pick up on any built files. + Note that you'll need to run \`pnpm build\` before \`pnpm lint\` so that lint rules which check the file system can pick up on any built files. ## Testing @@ -303,7 +303,17 @@ Def 456. ## Building - Will be removed. + Run [**tsup**](https://tsup.egoist.dev) locally to build source files from \`src/\` into output files in \`lib/\`: + + \`\`\`shell + pnpm build + \`\`\` + + Add \`--watch\` to run the builder in a watch mode that continuously cleans and recreates \`lib/\` as you save files: + + \`\`\`shell + pnpm build --watch + \`\`\` ## Formatting @@ -323,7 +333,7 @@ Def 456. - \`pnpm lint\` ([ESLint](https://eslint.org) with [typescript-eslint](https://typescript-eslint.io)): Lints JavaScript and TypeScript source files - \`pnpm lint:knip\` ([knip](https://github.com/webpro/knip)): Detects unused files, dependencies, and code exports - - \`pnpm lint:md\` ([Markdownlint](https://github.com/DavidAnson/markdownlint): Checks Markdown source files + - \`pnpm lint:md\` ([Markdownlint](https://github.com/DavidAnson/markdownlint)): Checks Markdown source files - \`pnpm lint:packages\` ([pnpm dedupe --check](https://pnpm.io/cli/dedupe)): Checks for unnecessarily duplicated packages in the \`pnpm-lock.yml\` file - \`pnpm lint:spelling\` ([cspell](https://cspell.org)): Spell checks across all source files @@ -335,7 +345,7 @@ Def 456. pnpm run lint --fix \`\`\` - Note that you'll likely need to run \`pnpm build\` before \`pnpm lint\` so that lint rules which check the file system can pick up on any built files. + Note that you'll need to run \`pnpm build\` before \`pnpm lint\` so that lint rules which check the file system can pick up on any built files. ## Testing diff --git a/src/steps/writing/creation/dotGitHub/createDevelopment/index.ts b/src/steps/writing/creation/dotGitHub/createDevelopment/index.ts index ff86c0a8e..5ce29ce1e 100644 --- a/src/steps/writing/creation/dotGitHub/createDevelopment/index.ts +++ b/src/steps/writing/creation/dotGitHub/createDevelopment/index.ts @@ -26,6 +26,11 @@ Add \`--watch\` to run the builder in a watch mode that continuously cleans and \`\`\`shell pnpm build --watch \`\`\``, + ...(options.bin && { + "### Built App Debugging": `This repository includes a [VS Code launch configuration](https://code.visualstudio.com/docs/editor/debugging) for debugging. +To debug a \`bin\` app, add a breakpoint to your code, then run _Debug Program_ from the VS Code Debug panel (or press F5). +VS Code will automatically run the \`build\` task in the background before running \`${options.bin}\`.`, + }), "## Formatting": `[Prettier](https://prettier.io) is used to format code. It should be applied automatically when you save files in VS Code or make a Git commit. @@ -40,8 +45,7 @@ pnpm format --write pnpm run lint --fix \`\`\` -Note that you'll likely need to run \`pnpm build\` before \`pnpm lint\` so that lint rules which check the file system can pick up on any built files.`, - +Note that you'll need to run \`pnpm build\` before \`pnpm lint\` so that lint rules which check the file system can pick up on any built files.`, ...(!options.excludeTests && { "## Testing": `[Vitest](https://vitest.dev) is used for tests. You can run it locally on the command-line: @@ -83,14 +87,35 @@ pnpm tsc --watch Object.keys(newSections).map((key) => key.replace(/^#* /, "")), ]); - const preservedSections = Object.fromEntries( - splitIntoSections(existingContents).filter(([key]) => { - const keyText = key.replace(/^#* /, ""); - return !newSectionHeadings.has( - headingAliases.get(keyText.toLowerCase()) ?? keyText, - ); - }), - ); + const existingSectionsSplit = splitIntoSections(existingContents); + const preservedSectionsSplit = existingSectionsSplit.filter(([key]) => { + const keyText = key.replace(/^#* /, ""); + return !newSectionHeadings.has( + headingAliases.get(keyText.toLowerCase()) ?? keyText, + ); + }); + const preservedSections = Object.fromEntries(preservedSectionsSplit); + + const sectionLines: string[] = []; + const seen = new Set(); + + for (const sections of [newSections, preservedSections]) { + for (const heading in sections) { + if (seen.has(heading)) { + continue; + } + + seen.add(heading); + + // eslint-disable-next-line @typescript-eslint/no-non-null-assertion + const contents = sections[heading as keyof typeof sections]!; + + sectionLines.push(""); + sectionLines.push(heading); + sectionLines.push(""); + sectionLines.push(contents); + } + } const result = `# Development ${ @@ -111,14 +136,7 @@ pnpm install > This repository includes a list of suggested VS Code extensions. > It's a good idea to use [VS Code](https://code.visualstudio.com) and accept its suggestion to install them, as they'll help with development. - -${Object.entries({ ...newSections, ...preservedSections }) - .map( - ([heading, content]) => `${heading} - -${content}`, - ) - .join("\n\n")} +${sectionLines.join("\n")} `; return result; @@ -129,7 +147,7 @@ function createLintingSection(options: Options) { !options.excludeLintKnip && `- \`pnpm lint:knip\` ([knip](https://github.com/webpro/knip)): Detects unused files, dependencies, and code exports`, !options.excludeLintMd && - `- \`pnpm lint:md\` ([Markdownlint](https://github.com/DavidAnson/markdownlint): Checks Markdown source files`, + `- \`pnpm lint:md\` ([Markdownlint](https://github.com/DavidAnson/markdownlint)): Checks Markdown source files`, !options.excludeLintPackages && `- \`pnpm lint:packages\` ([pnpm dedupe --check](https://pnpm.io/cli/dedupe)): Checks for unnecessarily duplicated packages in the \`pnpm-lock.yml\` file`, !options.excludeLintSpelling && From 4c633bfc890760edece3a82db9213288d16f7938 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Tue, 3 Dec 2024 14:41:42 -0500 Subject: [PATCH 2/2] Migration test snapshot updates --- script/__snapshots__/migrate-test-e2e.ts.snap | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/script/__snapshots__/migrate-test-e2e.ts.snap b/script/__snapshots__/migrate-test-e2e.ts.snap index 8fe95da32..881637a0c 100644 --- a/script/__snapshots__/migrate-test-e2e.ts.snap +++ b/script/__snapshots__/migrate-test-e2e.ts.snap @@ -93,9 +93,7 @@ exports[`expected file changes > cspell.json 1`] = ` "markdownlintignore", "mtfoley", "npmignore", -- "npmpackagejsonlintrc", - "outro", -- "packagejson", +@@ ... @@ "tada", "tseslint", "tsup",