From a771c4f176abaab689a56e5a2fbd8e556120552c Mon Sep 17 00:00:00 2001 From: Sutu Sebastian Date: Fri, 15 May 2026 21:34:25 +0300 Subject: [PATCH] docs(state-gitignore): slim header for consumer clarity MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The auto-generated `/.gitignore` header had three comment lines: # codemap-managed — edits will be overwritten by `ensureStateGitignore`. # Blacklist of generated artifacts; tracked sources (recipes/, config.*) # default to tracked. Bump alongside any new cache (Rule 9 analogue). Two issues for the consumer audience this file actually targets: - `ensureStateGitignore` is an internal function name; a consumer reading the rendered .gitignore has no way to look it up. - The "Rule 9 analogue" / "bump alongside any new cache" line is guidance for codemap contributors — wrong audience. Replace with two plain-English lines: # Managed by codemap — overwritten on next run. # Generated artifacts only; user-authored config (config.*, recipes/) stays tracked. The blacklist entries themselves (index.db + WAL/SHM, audit-cache/) are unchanged. ensureStateGitignore's drift detection (exact string match) means every consumer's next codemap run rewrites the file to the new shape one time; no behavioural difference. Regenerated `.codemap/.gitignore` (in-tree) and `fixtures/minimal/.codemap/.gitignore` to match the new canonical body. --- .changeset/state-gitignore-slim.md | 18 ++++++++++++++++++ .codemap/.gitignore | 5 ++--- fixtures/minimal/.codemap/.gitignore | 5 ++--- src/application/state-dir.ts | 5 ++--- 4 files changed, 24 insertions(+), 9 deletions(-) create mode 100644 .changeset/state-gitignore-slim.md diff --git a/.changeset/state-gitignore-slim.md b/.changeset/state-gitignore-slim.md new file mode 100644 index 0000000..004630e --- /dev/null +++ b/.changeset/state-gitignore-slim.md @@ -0,0 +1,18 @@ +--- +"@stainless-code/codemap": patch +--- + +Slim the auto-generated `/.gitignore` header for consumer clarity: + +- Drop the internal function-name reference (`ensureStateGitignore`) — consumers can't look it up. +- Drop the "Rule 9 analogue" / "bump alongside any new cache" line — it was guidance for codemap contributors, leaking into every consumer's checkout. +- Reframe "blacklist" / parenthetical mention of tracked files in plainer language. + +Existing two-line header (`# codemap-managed — edits will be overwritten by ensureStateGitignore.` / `# Blacklist of generated artifacts...`) becomes: + +``` +# Managed by codemap — overwritten on next run. +# Generated artifacts only; user-authored config (config.*, recipes/) stays tracked. +``` + +**One-time rewrite on consumer side.** The reconciler matches the canonical body via exact string comparison, so every consumer's next `codemap` run rewrites `/.gitignore` to the new shape (no entries change — only the comment lines). Harmless; the blacklist entries (`index.db`, `index.db-shm`, `index.db-wal`, `audit-cache/`) are unchanged. diff --git a/.codemap/.gitignore b/.codemap/.gitignore index 4099e2e..3011fd4 100644 --- a/.codemap/.gitignore +++ b/.codemap/.gitignore @@ -1,6 +1,5 @@ -# codemap-managed — edits will be overwritten by `ensureStateGitignore`. -# Blacklist of generated artifacts; tracked sources (recipes/, config.*) -# default to tracked. Bump alongside any new cache (Rule 9 analogue). +# Managed by codemap — overwritten on next run. +# Generated artifacts only; user-authored config (config.*, recipes/) stays tracked. index.db index.db-shm index.db-wal diff --git a/fixtures/minimal/.codemap/.gitignore b/fixtures/minimal/.codemap/.gitignore index 4099e2e..3011fd4 100644 --- a/fixtures/minimal/.codemap/.gitignore +++ b/fixtures/minimal/.codemap/.gitignore @@ -1,6 +1,5 @@ -# codemap-managed — edits will be overwritten by `ensureStateGitignore`. -# Blacklist of generated artifacts; tracked sources (recipes/, config.*) -# default to tracked. Bump alongside any new cache (Rule 9 analogue). +# Managed by codemap — overwritten on next run. +# Generated artifacts only; user-authored config (config.*, recipes/) stays tracked. index.db index.db-shm index.db-wal diff --git a/src/application/state-dir.ts b/src/application/state-dir.ts index e20d88d..8bba4fb 100644 --- a/src/application/state-dir.ts +++ b/src/application/state-dir.ts @@ -48,9 +48,8 @@ export function resolveStateDir(opts: ResolveStateDirOpts): string { * the source of truth — header, blank lines, and ordering all reproduce * verbatim. Add new generated artifacts in the same PR that introduces them. */ -export const STATE_GITIGNORE_BODY = `# codemap-managed — edits will be overwritten by \`ensureStateGitignore\`. -# Blacklist of generated artifacts; tracked sources (recipes/, config.*) -# default to tracked. Bump alongside any new cache (Rule 9 analogue). +export const STATE_GITIGNORE_BODY = `# Managed by codemap — overwritten on next run. +# Generated artifacts only; user-authored config (config.*, recipes/) stays tracked. index.db index.db-shm index.db-wal