Skip to content

Commit b465f78

Browse files
JoshuaKGoldbergJoshuaKGoldberg
authored
feat: add back Usage example to create and initialize (#882)
## PR Checklist - [x] Addresses an existing open issue: fixes #785 - [x] That issue was marked as [`status: accepting prs`](https://github.com/JoshuaKGoldberg/create-typescript-app/issues?q=is%3Aopen+is%3Aissue+label%3A%22status%3A+accepting+prs%22) - [x] Steps in [CONTRIBUTING.md](https://github.com/JoshuaKGoldberg/create-typescript-app/blob/main/.github/CONTRIBUTING.md) were taken ## Overview Also adds `mode` to `Options` because it was getting annoying passing it around explicitly too.
1 parent bfcd795 commit b465f78

31 files changed

+244
-68
lines changed

‎.eslintrc.cjs

+10-1
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ module.exports = {
3737
files: ["**/*.ts"],
3838
parser: "@typescript-eslint/parser",
3939
rules: {
40-
// These off-by-default rules work well for this repo and we like them on.
40+
// These off-/differently-configured-by-default rules work well for this repo and we like them on.
4141
"jsdoc/informative-docs": "error",
4242
"logical-assignment-operators": [
4343
"error",
@@ -53,6 +53,15 @@ module.exports = {
5353
"jsdoc/require-returns": "off",
5454
},
5555
},
56+
{
57+
files: "**/*.md/*.ts",
58+
rules: {
59+
"n/no-missing-import": [
60+
"error",
61+
{ allowModules: ["create-typescript-app"] },
62+
],
63+
},
64+
},
5665
{
5766
excludedFiles: ["**/*.md/*.ts"],
5867
extends: [

‎script/create-test-e2e.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import { strict as assert } from "node:assert";
44
const author = "Test Author";
55
const description = "Test description.";
66
const email = "[email protected]";
7-
const repository = "test-repository";
7+
const repository = "create-typescript-app";
88
const owner = "TestOwner";
99
const title = "Test Title";
1010

‎src/bin/index.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ export async function bin(args: string[]) {
5757
prompts.log.info(
5858
[
5959
chalk.italic(`Tip: to run again with the same input values, use:`),
60-
chalk.blue(createRerunSuggestion(mode, options)),
60+
chalk.blue(createRerunSuggestion(options)),
6161
].join(" "),
6262
);
6363

‎src/create/createRerunSuggestion.test.ts

+9-6
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ const options = {
2929
excludeTests: undefined,
3030
funding: undefined,
3131
logo: undefined,
32+
mode: "create",
3233
owner: "TestOwner",
3334
repository: "test-repository",
3435
skipGitHubApi: true,
@@ -41,37 +42,39 @@ const options = {
4142

4243
describe("createRerunSuggestion", () => {
4344
it("includes key-value pairs with mixed truthy and falsy values", () => {
44-
const actual = createRerunSuggestion("initialize", options);
45+
const actual = createRerunSuggestion(options);
4546

4647
expect(actual).toMatchInlineSnapshot(
47-
'"npx create-typescript-app --mode initialize --base everything --access public --author TestAuthor --create-repository true --description \\"Test description.\\" --email-github [email protected] --email-npm [email protected] --exclude-compliance true --exclude-contributors true --exclude-lint-jsdoc true --exclude-lint-json true --exclude-lint-knip true --exclude-lint-package-json true --exclude-lint-perfectionist true --owner TestOwner --repository test-repository --skip-github-api true --skip-install true --skip-removal true --title \\"Test Title\\""',
48+
'"npx create-typescript-app --mode create --base everything --access public --author TestAuthor --create-repository true --description \\"Test description.\\" --email-github [email protected] --email-npm [email protected] --exclude-compliance true --exclude-contributors true --exclude-lint-jsdoc true --exclude-lint-json true --exclude-lint-knip true --exclude-lint-package-json true --exclude-lint-perfectionist true --mode create --owner TestOwner --repository test-repository --skip-github-api true --skip-install true --skip-removal true --title \\"Test Title\\""',
4849
);
4950
});
5051

5152
it("includes stringified logo when it exists", () => {
52-
const actual = createRerunSuggestion("initialize", {
53+
const actual = createRerunSuggestion({
5354
...options,
5455
logo: {
5556
alt: "Test alt.",
5657
src: "test/src.png",
5758
},
59+
mode: "initialize",
5860
});
5961

6062
expect(actual).toMatchInlineSnapshot(
61-
'"npx create-typescript-app --mode initialize --base everything --access public --author TestAuthor --create-repository true --description \\"Test description.\\" --email-github [email protected] --email-npm [email protected] --exclude-compliance true --exclude-contributors true --exclude-lint-jsdoc true --exclude-lint-json true --exclude-lint-knip true --exclude-lint-package-json true --exclude-lint-perfectionist true --logo test/src.png --logo-alt \\"Test alt.\\" --owner TestOwner --repository test-repository --skip-github-api true --skip-install true --skip-removal true --title \\"Test Title\\""',
63+
'"npx create-typescript-app --mode initialize --base everything --access public --author TestAuthor --create-repository true --description \\"Test description.\\" --email-github [email protected] --email-npm [email protected] --exclude-compliance true --exclude-contributors true --exclude-lint-jsdoc true --exclude-lint-json true --exclude-lint-knip true --exclude-lint-package-json true --exclude-lint-perfectionist true --logo test/src.png --logo-alt \\"Test alt.\\" --mode initialize --owner TestOwner --repository test-repository --skip-github-api true --skip-install true --skip-removal true --title \\"Test Title\\""',
6264
);
6365
});
6466

6567
it("includes exclusions when they exist", () => {
66-
const actual = createRerunSuggestion("initialize", {
68+
const actual = createRerunSuggestion({
6769
...options,
6870
excludeCompliance: true,
6971
excludeLintMd: true,
7072
excludeLintSpelling: true,
73+
mode: "initialize",
7174
});
7275

7376
expect(actual).toMatchInlineSnapshot(
74-
'"npx create-typescript-app --mode initialize --base everything --access public --author TestAuthor --create-repository true --description \\"Test description.\\" --email-github [email protected] --email-npm [email protected] --exclude-compliance true --exclude-contributors true --exclude-lint-jsdoc true --exclude-lint-json true --exclude-lint-knip true --exclude-lint-md true --exclude-lint-package-json true --exclude-lint-perfectionist true --exclude-lint-spelling true --owner TestOwner --repository test-repository --skip-github-api true --skip-install true --skip-removal true --title \\"Test Title\\""',
77+
'"npx create-typescript-app --mode initialize --base everything --access public --author TestAuthor --create-repository true --description \\"Test description.\\" --email-github [email protected] --email-npm [email protected] --exclude-compliance true --exclude-contributors true --exclude-lint-jsdoc true --exclude-lint-json true --exclude-lint-knip true --exclude-lint-md true --exclude-lint-package-json true --exclude-lint-perfectionist true --exclude-lint-spelling true --mode initialize --owner TestOwner --repository test-repository --skip-github-api true --skip-install true --skip-removal true --title \\"Test Title\\""',
7578
);
7679
});
7780
});

‎src/create/createRerunSuggestion.ts

+2-6
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
import { Mode } from "../bin/mode.js";
21
import { allArgOptions } from "../shared/options/args.js";
32
import { Options } from "../shared/types.js";
43

@@ -8,10 +7,7 @@ function getFirstMatchingArg(key: string) {
87
);
98
}
109

11-
export function createRerunSuggestion(
12-
mode: Mode,
13-
options: Partial<Options>,
14-
): string {
10+
export function createRerunSuggestion(options: Partial<Options>): string {
1511
const optionsNormalized = {
1612
...options,
1713
...(options.email
@@ -42,5 +38,5 @@ export function createRerunSuggestion(
4238
})
4339
.join(" ");
4440

45-
return `npx create-typescript-app --mode ${mode} ${args}`;
41+
return `npx create-typescript-app --mode ${options.mode} ${args}`;
4642
}

‎src/create/createWithOptions.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ export async function createWithOptions({ github, options }: GitHubAndOptions) {
1616
[
1717
"Writing structure",
1818
async () => {
19-
await writeStructure(options, "create");
19+
await writeStructure(options);
2020
},
2121
],
2222
[

‎src/create/index.ts

+3-2
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ import { createRerunSuggestion } from "./createRerunSuggestion.js";
1111
import { createWithOptions } from "./createWithOptions.js";
1212

1313
export async function create(args: string[]): Promise<ModeResult> {
14-
const inputs = await readOptions(args);
14+
const inputs = await readOptions(args, "create");
1515
if (inputs.cancelled) {
1616
return {
1717
code: StatusCodes.Cancelled,
@@ -49,8 +49,9 @@ export async function create(args: string[]): Promise<ModeResult> {
4949
"Consider creating a GitHub repository from the new directory:",
5050
lines: [
5151
`cd ${inputs.options.repository}`,
52-
createRerunSuggestion("initialize", {
52+
createRerunSuggestion({
5353
...inputs.options,
54+
mode: "initialize",
5455
skipGitHubApi: false,
5556
skipInstall: false,
5657
}),

‎src/initialize/index.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import { runOrRestore } from "../shared/runOrRestore.js";
77
import { initializeWithOptions } from "./initializeWithOptions.js";
88

99
export const initialize: ModeRunner = async (args) => {
10-
const inputs = await readOptions(args);
10+
const inputs = await readOptions(args, "initialize");
1111
if (inputs.cancelled) {
1212
return {
1313
code: StatusCodes.Cancelled,

‎src/initialize/initializeWithOptions.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ export async function initializeWithOptions({
1919
[
2020
"Updating local files",
2121
async () => {
22-
await updateLocalFiles(options, "initialize");
22+
await updateLocalFiles(options);
2323
},
2424
],
2525
["Updating README.md", updateReadme],

‎src/migrate/index.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import { runOrRestore } from "../shared/runOrRestore.js";
77
import { migrateWithOptions } from "./migrateWithOptions.js";
88

99
export const migrate: ModeRunner = async (args) => {
10-
const inputs = await readOptions(args);
10+
const inputs = await readOptions(args, "migrate");
1111
if (inputs.cancelled) {
1212
return {
1313
code: StatusCodes.Cancelled,

‎src/migrate/migrateWithOptions.ts

+2-2
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ export async function migrateWithOptions({
1919
[
2020
"Writing structure",
2121
async () => {
22-
await writeStructure(options, "migrate");
22+
await writeStructure(options);
2323
},
2424
],
2525
[
@@ -31,7 +31,7 @@ export async function migrateWithOptions({
3131
[
3232
"Updating local files",
3333
async () => {
34-
await updateLocalFiles(options, "migrate");
34+
await updateLocalFiles(options);
3535
},
3636
],
3737
[

‎src/shared/options/args.ts

+1
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ export const allArgOptions = {
2929
funding: { type: "string" },
3030
logo: { type: "string" },
3131
"logo-alt": { type: "string" },
32+
mode: { type: "string" },
3233
owner: { type: "string" },
3334
repository: { type: "string" },
3435
"skip-github-api": { type: "boolean" },

‎src/shared/options/augmentOptionsWithExcludes.test.ts

+1
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ const optionsBase = {
3434
excludeTests: undefined,
3535
funding: undefined,
3636
logo: undefined,
37+
mode: "create",
3738
owner: "",
3839
repository: "",
3940
skipGitHubApi: false,

‎src/shared/options/optionsSchema.ts

+3
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,9 @@ export const optionsSchemaShape = {
4141
funding: z.string().optional(),
4242
logo: z.string().optional(),
4343
logoAlt: z.string().optional(),
44+
mode: z
45+
.union([z.literal("create"), z.literal("initialize"), z.literal("migrate")])
46+
.optional(),
4447
owner: z.string().optional(),
4548
repository: z.string().optional(),
4649
skipGitHubApi: z.boolean().optional(),

‎src/shared/options/readOptions.test.ts

+13-11
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ describe("readOptions", () => {
112112
.object({ base: optionsSchemaShape.base })
113113
.safeParse({ base: "b" });
114114

115-
const actual = await readOptions(["--base", "b"]);
115+
const actual = await readOptions(["--base", "b"], "create");
116116

117117
expect(actual).toStrictEqual({
118118
cancelled: true,
@@ -126,7 +126,7 @@ describe("readOptions", () => {
126126
mockDetectEmailRedundancy.mockReturnValue(error);
127127
mockGetPrefillOrPromptedOption.mockImplementation(() => undefined);
128128

129-
expect(await readOptions([])).toStrictEqual({
129+
expect(await readOptions([], "create")).toStrictEqual({
130130
cancelled: true,
131131
error,
132132
options: {
@@ -139,7 +139,7 @@ describe("readOptions", () => {
139139
mockDetectEmailRedundancy.mockReturnValue(false);
140140
mockGetPrefillOrPromptedOption.mockImplementation(() => undefined);
141141

142-
expect(await readOptions([])).toStrictEqual({
142+
expect(await readOptions([], "create")).toStrictEqual({
143143
cancelled: true,
144144
options: {
145145
...emptyOptions,
@@ -153,7 +153,7 @@ describe("readOptions", () => {
153153
.mockImplementationOnce(() => "MockOwner")
154154
.mockImplementation(() => undefined);
155155

156-
expect(await readOptions([])).toStrictEqual({
156+
expect(await readOptions([], "create")).toStrictEqual({
157157
cancelled: true,
158158
options: {
159159
...emptyOptions,
@@ -170,7 +170,7 @@ describe("readOptions", () => {
170170
.mockImplementation(() => undefined);
171171
mockEnsureRepositoryExists.mockResolvedValue({});
172172

173-
expect(await readOptions([])).toStrictEqual({
173+
expect(await readOptions([], "create")).toStrictEqual({
174174
cancelled: true,
175175
options: {
176176
...emptyOptions,
@@ -191,7 +191,7 @@ describe("readOptions", () => {
191191
repository: mockOptions.repository,
192192
});
193193

194-
expect(await readOptions([])).toStrictEqual({
194+
expect(await readOptions([], "create")).toStrictEqual({
195195
cancelled: true,
196196
options: {
197197
...emptyOptions,
@@ -213,7 +213,7 @@ describe("readOptions", () => {
213213
repository: mockOptions.repository,
214214
});
215215

216-
expect(await readOptions([])).toStrictEqual({
216+
expect(await readOptions([], "create")).toStrictEqual({
217217
cancelled: true,
218218
options: {
219219
...emptyOptions,
@@ -236,7 +236,7 @@ describe("readOptions", () => {
236236
repository: mockOptions.repository,
237237
});
238238

239-
expect(await readOptions(["--logo", "logo.svg"])).toStrictEqual({
239+
expect(await readOptions(["--logo", "logo.svg"], "create")).toStrictEqual({
240240
cancelled: true,
241241
options: {
242242
...emptyOptions,
@@ -260,7 +260,7 @@ describe("readOptions", () => {
260260
repository: mockOptions.repository,
261261
});
262262

263-
expect(await readOptions([])).toStrictEqual({
263+
expect(await readOptions([], "create")).toStrictEqual({
264264
cancelled: true,
265265
options: {
266266
...emptyOptions,
@@ -286,7 +286,7 @@ describe("readOptions", () => {
286286
});
287287
mockAugmentOptionsWithExcludes.mockResolvedValue(undefined);
288288

289-
expect(await readOptions([])).toStrictEqual({
289+
expect(await readOptions([], "create")).toStrictEqual({
290290
cancelled: true,
291291
options: {
292292
...emptyOptions,
@@ -305,7 +305,9 @@ describe("readOptions", () => {
305305
});
306306
mockGetPrefillOrPromptedOption.mockImplementation(() => "mock");
307307

308-
expect(await readOptions(["--base", mockOptions.base])).toStrictEqual({
308+
expect(
309+
await readOptions(["--base", mockOptions.base], "create"),
310+
).toStrictEqual({
309311
cancelled: false,
310312
github: mockOptions.github,
311313
options: {

‎src/shared/options/readOptions.ts

+6-1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import { parseArgs } from "node:util";
22
import { titleCase } from "title-case";
33
import { z } from "zod";
44

5+
import { Mode } from "../../bin/mode.js";
56
import { withSpinner } from "../cli/spinners.js";
67
import { Options, OptionsLogo } from "../types.js";
78
import { allArgOptions } from "./args.js";
@@ -30,7 +31,10 @@ export interface OptionsParseSuccess extends GitHubAndOptions {
3031

3132
export type OptionsParseResult = OptionsParseCancelled | OptionsParseSuccess;
3233

33-
export async function readOptions(args: string[]): Promise<OptionsParseResult> {
34+
export async function readOptions(
35+
args: string[],
36+
mode: Mode,
37+
): Promise<OptionsParseResult> {
3438
const defaults = readOptionDefaults();
3539
const { values } = parseArgs({
3640
args,
@@ -193,6 +197,7 @@ export async function readOptions(args: string[]): Promise<OptionsParseResult> {
193197
email: typeof email === "string" ? { github: email, npm: email } : email,
194198
funding: options.funding ?? (await defaults.funding()),
195199
logo,
200+
mode,
196201
owner: options.owner,
197202
repository,
198203
title: options.title,

‎src/shared/types.ts

+3
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
import { Mode } from "../bin/mode.js";
2+
13
export interface AllContributorContributor {
24
contributions: string[];
35
login: string;
@@ -59,6 +61,7 @@ export interface Options {
5961
excludeTests?: boolean;
6062
funding?: string;
6163
logo: OptionsLogo | undefined;
64+
mode: Mode;
6265
owner: string;
6366
repository: string;
6467
skipGitHubApi?: boolean;

‎src/steps/finalizeDependencies.test.ts

+1
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ const options = {
4141
excludeTests: undefined,
4242
funding: undefined,
4343
logo: undefined,
44+
mode: "create",
4445
owner: "StubOwner",
4546
repository: "stub-repository",
4647
skipGitHubApi: false,

0 commit comments

Comments
 (0)