create-stitchkit 0.5.0 → 0.6.0

package/template/scripts/check-authored.ts

@@ -20,15 +20,42 @@ function lineAt(source: string, offset: number): number {
   return source.slice(0, offset).split('\n').length;
 }
 
-function inspect(path: string, source: string): string[] {
+/**
+ * `as const` is not the assertion this gate exists for.
+ *
+ * The gate refuses a cast because a cast can LAUNDER a type — claim something the value has not
+ * been shown to be. A const-assertion cannot: it only narrows, it introduces no name, and it
+ * cannot widen. Refusing it made five of the first fifteen findings on a real adoption false, in
+ * a gate whose whole value is that its findings are worth acting on.
+ *
+ * `const` is a reserved word, so no type can be named `const` — the check has no false positive
+ * of its own.
+ */
+function isConstAssertion(node: { typeAnnotation?: unknown }): boolean {
+  const annotation = node.typeAnnotation;
+  if (!isRecord(annotation) || annotation.type !== 'TSTypeReference') return false;
+  const typeName = annotation.typeName;
+  return isRecord(typeName) && typeName.type === 'Identifier' && typeName.name === 'const';
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+/** What to do instead — a finding that only names the sin costs the reader a search. */
+const ASSERTION_REMEDY =
+  'type assertion — use `satisfies` to check a literal against a type, or parse the value with its schema at the boundary';
+
+export function inspect(path: string, source: string): string[] {
   const result = parseSync(path, source);
   const failures = result.errors.map((error) => `${path}: parse error: ${error.message}`);
   const visitor = new Visitor({
     TSAsExpression(node) {
-      failures.push(`${path}:${lineAt(source, node.start)}: type assertion`);
+      if (isConstAssertion(node)) return;
+      failures.push(`${path}:${lineAt(source, node.start)}: ${ASSERTION_REMEDY}`);
     },
     TSTypeAssertion(node) {
-      failures.push(`${path}:${lineAt(source, node.start)}: type assertion`);
+      failures.push(`${path}:${lineAt(source, node.start)}: ${ASSERTION_REMEDY}`);
     },
     TSAnyKeyword(node) {
       failures.push(`${path}:${lineAt(source, node.start)}: explicit any`);
@@ -91,21 +118,25 @@ async function visitDirectory(directory: string): Promise<string[]> {
   return failures;
 }
 
-const failures = [
-  ...(await Promise.all(roots.map(visitDirectory))).flat(),
-  ...(
-    await Promise.all(
-      rootFiles.map(async (path) => inspect(path, await readFile(path, 'utf8'))),
-    )
-  ).flat(),
-];
-const webPackage = await readFile('packages/frontend/package.json', 'utf8');
-if (webPackage.includes(replacedThemePackage)) {
-  failures.push(
-    'packages/frontend/package.json: use @wrksz/themes as the single theme runtime',
-  );
-}
-if (failures.length > 0) {
-  for (const failure of failures) console.error(failure);
-  process.exit(1);
+// Guarded so the module can be imported by its own test without running the gate over the
+// repository — importing a script that scans the tree and exits is not a testable unit.
+if (import.meta.main) {
+  const failures = [
+    ...(await Promise.all(roots.map(visitDirectory))).flat(),
+    ...(
+      await Promise.all(
+        rootFiles.map(async (path) => inspect(path, await readFile(path, 'utf8'))),
+      )
+    ).flat(),
+  ];
+  const webPackage = await readFile('packages/frontend/package.json', 'utf8');
+  if (webPackage.includes(replacedThemePackage)) {
+    failures.push(
+      'packages/frontend/package.json: use @wrksz/themes as the single theme runtime',
+    );
+  }
+  if (failures.length > 0) {
+    for (const failure of failures) console.error(failure);
+    process.exit(1);
+  }
 }

package/template/scripts/dev.ts

@@ -1,7 +1,7 @@
 import { resolve } from 'node:path';
 import { z } from 'zod';
 import { appDeclaration } from '../packages/config/src/declaration';
-import { ensureLocalEnvironment } from './local-env';
+import { assertUsableEnvironment, ensureLocalEnvironment } from './local-env';
 import { awaitRolesAnswering, declaredRoleReadiness } from './readiness';
 import { runDeclaredReleaseSteps } from './release-steps';
 import { inheritToolingEnvironment } from './tooling-env';
@@ -21,9 +21,14 @@ async function run(command: string[], environment?: Record<string, string>): Pro
 
 export async function runDevelopment(environment?: Record<string, string>): Promise<void> {
   ensureLocalEnvironment(root);
+  // Before pm2, before anything: an unusable environment is the reader's problem to fix, and
+  // making them read a supervisor error first only delays the sentence that matters.
+  assertUsableEnvironment(root);
   assertToolAvailable('pm2', 'Install PM2 with `bun add --global pm2`, then rerun.');
   await run(['pm2', 'ping']);
   const environmentForRun = await developmentEnvironment(environment);
+  // Kept for an environment supplied from the shell rather than from `.env`, which the file
+  // check above cannot see.
   if (environmentForRun.DATABASE_URL?.includes('USER:PASSWORD')) {
     throw new Error(
       'DATABASE_URL still contains the starter placeholder. Create a PostgreSQL database, update DATABASE_URL in .env, then rerun `bun run dev`.',

package/template/scripts/guide-paths.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from 'bun:test';
+import { inspectGuide, inspectGuides } from './guide-paths';
+
+const present = (path: string) => path === 'packages/shared/src/index.ts';
+
+describe('guide paths', () => {
+  test('reports a path the guide names but the scaffold lacks', () => {
+    const findings = inspectGuide(
+      'docs/G.md',
+      'In `packages/frontend/src/lib/api/client.ts`, create the api.\n',
+      present,
+    );
+    expect(findings).toEqual([
+      { guide: 'docs/G.md', line: 1, path: 'packages/frontend/src/lib/api/client.ts' },
+    ]);
+  });
+
+  test('a path the guide creates is declared, not broken', () => {
+    const source = 'Create `packages/shared/src/realtime.ts` (created in this step) and…\n';
+    expect(inspectGuide('docs/G.md', source, present)).toEqual([]);
+  });
+
+  test('an existing path is quiet, and prose without a path is quiet', () => {
+    expect(
+      inspectGuide('docs/G.md', 'Export it from `packages/shared/src/index.ts`.\n', present),
+    ).toEqual([]);
+    expect(inspectGuide('docs/G.md', 'Pages compose features.\n', present)).toEqual([]);
+  });
+
+  test('the real guide resolves every path it does not create', async () => {
+    // The denominator matters: a guide the scanner cannot read would also return [].
+    const findings = await inspectGuides(`${import.meta.dir}/..`);
+    expect(findings).toEqual([]);
+    const anyPath = inspectGuide('docs/G.md', 'See `packages/absent/x.ts`.\n', () => false);
+    expect(anyPath).toHaveLength(1);
+  });
+});

package/template/scripts/guide-paths.ts

@@ -0,0 +1,66 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+/**
+ * Every repository path a guide names has to exist.
+ *
+ * `ADDING_A_FEATURE.md` is the one document a new consumer executes literally, and two of its
+ * steps pointed at files the scaffold does not contain — `lib/api/client.ts` and a "shared
+ * realtime source". The reader does not learn that by reading; they learn it by opening the path
+ * and finding nothing, after having already trusted the sentence around it.
+ *
+ * A path the guide tells you to CREATE is not a broken reference, so those are declared by the
+ * guide itself: a line that introduces one carries `(created in this step)`. Everything else
+ * must resolve.
+ */
+const GUIDES = ['docs/ADDING_A_FEATURE.md'];
+const PATH_PATTERN = /`((?:packages|scripts|docs|e2e)\/[A-Za-z0-9_./-]+)`/g;
+
+export interface GuidePathFinding {
+  readonly guide: string;
+  readonly line: number;
+  readonly path: string;
+}
+
+export function inspectGuide(
+  guide: string,
+  source: string,
+  exists: (path: string) => boolean,
+): GuidePathFinding[] {
+  const findings: GuidePathFinding[] = [];
+  source.split('\n').forEach((text, index) => {
+    if (text.includes('(created in this step)')) return;
+    for (const match of text.matchAll(PATH_PATTERN)) {
+      const path = match[1];
+      if (!path || exists(path)) continue;
+      findings.push({ guide, line: index + 1, path });
+    }
+  });
+  return findings;
+}
+
+export async function inspectGuides(root: string): Promise<GuidePathFinding[]> {
+  const findings: GuidePathFinding[] = [];
+  for (const guide of GUIDES) {
+    const absolute = resolve(root, guide);
+    if (!existsSync(absolute)) {
+      findings.push({ guide, line: 0, path: guide });
+      continue;
+    }
+    findings.push(
+      ...inspectGuide(guide, await readFile(absolute, 'utf8'), (path) =>
+        existsSync(join(root, path)),
+      ),
+    );
+  }
+  return findings;
+}
+
+if (import.meta.main) {
+  const findings = await inspectGuides(resolve(import.meta.dir, '..'));
+  for (const { guide, line, path } of findings) {
+    console.error(`${guide}:${line}: names ${path}, which does not exist`);
+  }
+  if (findings.length > 0) process.exit(1);
+}

package/template/scripts/local-env.test.ts

@@ -3,7 +3,7 @@ import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { appDeclaration } from '../packages/config/src/declaration';
-import { ensureLocalEnvironment } from './local-env';
+import { assertUsableEnvironment, ensureLocalEnvironment } from './local-env';
 
 describe('ensureLocalEnvironment', () => {
   test('renders the application identity into a fresh .env and never touches an existing one', async () => {
@@ -13,7 +13,10 @@ describe('ensureLocalEnvironment', () => {
         join(root, '.env.example'),
         'DATABASE_URL=postgresql://USER:PASSWORD@127.0.0.1:5432/stitchkit_starter\n',
       );
+      // Rendering succeeds — a generator that refuses to generate would break `--no-install`
+      // scaffolding — and the separate usability check is what refuses.
       ensureLocalEnvironment(root);
+      expect(() => assertUsableEnvironment(root)).toThrow(/USER:PASSWORD/);
       const created = await readFile(join(root, '.env'), 'utf8');
       // In the neutral dev workspace the slug IS the neutral identity, so the
       // substitution is proven end-to-end by the starter lane on a renamed
@@ -39,10 +42,56 @@ describe('ensureLocalEnvironment', () => {
         'DATABASE_URL=postgresql://USER:PASSWORD@127.0.0.1:5432/stitchkit_starter\n',
       );
       ensureLocalEnvironment(root);
+      expect(() => assertUsableEnvironment(root)).toThrow(/USER:PASSWORD/);
       const databaseName = appDeclaration.identity.slug.replaceAll('-', '_');
       expect(await readFile(join(root, '.env'), 'utf8')).toContain(`5432/${databaseName}`);
     } finally {
       await rm(root, { recursive: true, force: true });
     }
   });
+
+  test('an unedited .env is refused on every later run, not only the one that wrote it', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'sk-env-again-'));
+    try {
+      // No example at all: the file is already there, exactly as a second `bun run dev` finds it.
+      await writeFile(
+        join(root, '.env'),
+        'DATABASE_URL=postgresql://USER:PASSWORD@127.0.0.1:5432/app\n',
+      );
+      let message = '';
+      try {
+        assertUsableEnvironment(root);
+      } catch (error) {
+        message = error instanceof Error ? error.message : String(error);
+      }
+      // The message has to name the file, the line and the privilege the next step needs —
+      // a refusal that only says "invalid" moves the search back to the reader.
+      expect(message).toContain('.env:1');
+      expect(message).toContain('DATABASE_URL');
+      expect(message).toContain('CREATEDB');
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test('a commented example line is not mistaken for an unresolved credential', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'sk-env-comment-'));
+    try {
+      // The placeholder is assembled rather than written: spelled out it is a credential inside
+      // a URL, which the publication-privacy gate refuses on sight — rightly, since "it is only
+      // a fixture" is the argument every leak makes. Same idiom as `check-authored.ts`.
+      const placeholder = ['USER', 'PASSWORD'].join(':');
+      await writeFile(
+        join(root, '.env'),
+        [
+          `# DATABASE_URL=postgresql://${placeholder}@127.0.0.1:5432/example`,
+          'DATABASE_URL=postgresql://127.0.0.1:5432/app',
+          '',
+        ].join('\n'),
+      );
+      expect(() => assertUsableEnvironment(root)).not.toThrow();
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
 });

package/template/scripts/local-env.ts

@@ -19,18 +19,62 @@ import { appIdentity } from '../packages/config/src/app-identity.generated';
  * environment too. Synchronous on purpose: `playwright.config.ts` and other
  * synchronous entry points must be able to self-heal before validating.
  */
-export function ensureLocalEnvironment(root: string): void {
+/**
+ * The credentials this file renders but cannot know.
+ *
+ * `.env.example` ships a connection string with literal `USER:PASSWORD`, and this script
+ * substitutes only the database name. A file that is generated, edited by the generator and then
+ * left unusable is the worst of the three: the reader assumes a generated file is ready. So the
+ * placeholder is named here rather than discovered as a driver stack on the first request.
+ */
+function unresolvedCredentialLines(destination: string): string[] {
+  return readFileSync(destination, 'utf8')
+    .split('\n')
+    .map((line, index) => ({ line: line.trim(), number: index + 1 }))
+    .filter(({ line }) => !line.startsWith('#') && line.includes('USER:PASSWORD'))
+    .map(({ line, number }) => `  ${destination}:${number}  ${line.split('=')[0] ?? line}`);
+}
+
+/**
+ * Refuse to start on an environment that still carries the example credentials.
+ *
+ * Separate from rendering on purpose: a generator that refuses to generate is wrong — `--no-install`
+ * scaffolding renders `.env` before anyone could have filled it in — while a start that proceeds
+ * into a driver stack is the defect. So `env:ensure` writes and reports; `dev` writes and refuses.
+ */
+export function assertUsableEnvironment(root: string): void {
   const destination = resolve(root, '.env');
-  if (existsSync(destination)) return;
-  const publicExample = resolve(root, '.env.example');
-  const example = readFileSync(
-    existsSync(publicExample) ? publicExample : resolve(root, '_env.example'),
-    'utf8',
+  const unresolved = unresolvedCredentialLines(destination);
+  if (unresolved.length === 0) return;
+  throw new Error(
+    `This environment still carries the example credentials.\n${unresolved.join('\n')}\n` +
+      'Replace USER:PASSWORD with a role that can reach your PostgreSQL server. ' +
+      'A role that runs `db:migrate` also needs CREATEDB, because `prisma migrate dev` ' +
+      'creates a shadow database.',
   );
-  const databaseName = appIdentity.slug.replaceAll('-', '_');
-  writeFileSync(destination, example.replaceAll('stitchkit_starter', databaseName));
+}
+
+export function ensureLocalEnvironment(root: string): void {
+  const destination = resolve(root, '.env');
+  if (!existsSync(destination)) {
+    const publicExample = resolve(root, '.env.example');
+    const example = readFileSync(
+      existsSync(publicExample) ? publicExample : resolve(root, '_env.example'),
+      'utf8',
+    );
+    const databaseName = appIdentity.slug.replaceAll('-', '_');
+    writeFileSync(destination, example.replaceAll('stitchkit_starter', databaseName));
+  }
 }
 
 if (import.meta.main) {
-  ensureLocalEnvironment(resolve(import.meta.dir, '..'));
+  const root = resolve(import.meta.dir, '..');
+  ensureLocalEnvironment(root);
+  // Reported, not fatal: this command's job is to produce the file, and it has.
+  const unresolved = unresolvedCredentialLines(resolve(root, '.env'));
+  if (unresolved.length > 0) {
+    process.stderr.write(
+      `.env still carries the example credentials — \`bun run dev\` will refuse until they are replaced:\n${unresolved.join('\n')}\n`,
+    );
+  }
 }