fix(build): the document field templates stop breaking the package build

CONTRIBUTING.md

@@ -387,9 +387,11 @@ browser, with `_sidebar.md`, `_navbar.md` and `_coverpage.md` as its navigation.
   the files to compile in its query string and `run.js` compiles them in the browser. The demos
   take their look from `docs/snippets/styles.css`.
 - The examples of the document field page are generated: `npm run build:examples`
-  (`scripts/examples.ts`) fills the templates of `docs/snippets/document-field/_templates` from a
+  (`scripts/examples.ts`) fills the templates of `docs/snippets/document-field/templates` from a
   table of documents, so the shared mask is written once. Edit a template or the table: the files
-  under `generated/` are written by the build and are not in the repository.
+  under `generated/` are written by the build and are not in the repository. A template ends in
+  `.tmpl` (`schema/zod.ts.tmpl`) because its `@@placeholder@@` markers do not parse as the language
+  its name says: the suffix keeps it out of everything that walks the repository for source files.
 - `scripts/llms.ts` reads the title back out of the front matter, so `docs/llms.txt` and
   `docs/llms-full.txt` keep their headings.
 - Context7 indexes `docs/` as `/brazilian-utils/javascript`; `context7.json` says what it reads,

context7.json

@@ -5,7 +5,7 @@
 	"projectTitle": "Brazilian Utils",
 	"description": "Zero-dependency, tree-shakeable utilities for Brazilian data: validate, format, parse and generate CPF, CNPJ, CEP, boleto, Pix, holidays and more.",
 	"folders": ["docs"],
-	"excludeFolders": ["docs/pt-br"],
+	"excludeFolders": ["docs/pt-br", "docs/snippets/document-field/templates"],
 	"excludeFiles": [
 		"CHANGELOG.md",
 		"CODE_OF_CONDUCT.md",

scripts/examples.ts

@@ -4,7 +4,7 @@
  * Writes the examples the document field guide shows (`docs/guides/document-field.md`): one
  * focused example per document and framework, so a reader copies the CPF field, not a generic one
  * that has to be narrowed down first. Every file comes from a template in
- * `docs/snippets/document-field/_templates`, filled in from the table below, together with the
+ * `docs/snippets/document-field/templates`, filled in from the table below, together with the
  * `mask` function they share. One page runs them all in the browser, `docs/snippets/live`, told
  * which files to compile by its query string. The Check workflow fails when these are stale.
  *
@@ -17,7 +17,7 @@ import { join } from "node:path";
 
 const ROOT = join(import.meta.dirname, "..");
 const EXAMPLE_DIR = join(ROOT, "docs", "snippets", "document-field");
-const TEMPLATE_DIR = join(EXAMPLE_DIR, "_templates");
+const TEMPLATE_DIR = join(EXAMPLE_DIR, "templates");
 
 type Document = {
 	/** The kebab-case name of the document, which names its folder and its files. */
@@ -184,11 +184,15 @@ function values(document: Document): Record<string, string> {
 }
 
 /**
- * @param {string} name - A file of `docs/snippets/document-field/_templates`.
+ * A template carries `@@placeholder@@` markers, so it is not the language its name says it is:
+ * `schema/zod.ts` on its own does not parse as TypeScript. The extra `.tmpl` at the end keeps it
+ * out of every tool that walks the repository for `.ts`/`.tsx` files, the declaration build of the
+ * package included, while the extension before it still says what the filled in file will be.
+ * @param {string} name - A file of `docs/snippets/document-field/templates`, without the `.tmpl`.
  * @returns {string} Its contents.
  */
 function readTemplate(name: string): string {
-	return readFileSync(join(TEMPLATE_DIR, name), "utf8");
+	return readFileSync(join(TEMPLATE_DIR, `${name}.tmpl`), "utf8");
 }
 
 /**

tsconfig.json

@@ -19,7 +19,9 @@
 		"noImplicitOverride": true
 	},
 	// The documentation site is not part of the library: its examples are written for React,
-	// Angular and Vue, and the templates they are generated from are not valid TypeScript on their
-	// own. `npm run build:docs` and the type-check of each example live in the docs workflow.
-	"exclude": ["docs", "dist", "coverage", "reports", ".stryker-tmp"]
+	// Angular and Vue. `npm run build:docs` and the type-check of each example live in the docs
+	// workflow. `base` is the second checkout the Tree-shaking job of the build workflow writes
+	// there, a whole copy of the repository at the base revision of the pull request: the build
+	// running here compiles the head, never it.
+	"exclude": ["base", "docs", "dist", "coverage", "reports", ".stryker-tmp"]
 }