fix(context): only skip repo-meta filenames at the scan root

[WayOfThKeyboard]

The problem

IGNORED_FILES in packages/context/src/git.ts is matched by basename at every depth, not just at the scan root. The set is repo-root housekeeping — security, license, changelog, contributing, history, code_of_conduct, claude, and the two issue templates — but applied recursively it silently drops ordinary documentation pages that happen to share one of those names.

The build reports success either way. context add prints Found N markdown files and exits 0, so the only symptom is a later query returning nothing, which is indistinguishable from a query that simply has no answer.

Measured

Against @neuledge/context 1.2.3, on a fresh clone of codeberg.org/forgejo/docs:

138 markdown files under docs/
135 reach the builder

The two lost files are docs/admin/actions/security.md and docs/user/actions/security.md — the pages documenting how to secure Forgejo Actions. The first is the only source in the repository for container.valid_volumes, so context query forgejo valid_volumes returned nothing at all.

After this change, the same query returns:

Securing Forgejo Actions Deployments > Job Containers with Docker (part 2) — "The default value of valid_volumes is an empty array []. If an administrator changes this, they will allow a job container or service container to mount the listed volumes…"

Package: 130 → 132 documents, 728 → 742 sections.

Not just forgejo

Checked every repository I have a package for, via the GitHub trees API:

repo	dropped by this rule
docker/docs	content/manuals/extensions/extensions-sdk/architecture/security.md, content/manuals/billing/history.md, content/manuals/compose/intro/history.md, content/reference/api/dvp/changelog.md, content/reference/api/hub/changelog.md
excalidraw/excalidraw	dev-docs/docs/introduction/contributing.mdx
reactjs/react.dev, spf13/cobra	nothing outside .github/
golang/go	only vendored subtrees

The change

Apply IGNORED_FILES only when basePath === "". That is the case the set was written for, and it leaves nested pages alone. Six lines in git.ts.

Two tests, both written before the change and both mutation-checked:

• skips repo-meta files at the scan root — reddens if the filter is disabled entirely.
• keeps a documentation page that merely shares a repo-meta filename — reddens if the basePath === "" guard is removed.

pnpm test is green (223/223) and biome is clean.

What this deliberately does not change

docs/license.md in the forgejo repo still gets skipped, because it sits at the scan root and genuinely is a licence. Link-only index.md pages are still dropped by isTableOfContents. Both are correct, and I checked them before assuming the whole gap was one bug.

One thing worth considering separately: a build that drops files could say so. A count of files found versus documents actually indexed, printed at the end, would have made this visible immediately rather than months later. Happy to open that as its own issue or PR if you'd like it.

[changeset-bot]

🦋 Changeset detected

Latest commit: a24d887

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@neuledge/context	Patch
@neuledge/registry	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[moshest]

Good catch, and the diagnosis is right — basePath === "" is the correct root test (git.ts:530 seeds the walk with ""), and the forgejo case is real.

One thing to fix before I merge: the same bug survives one level up when docs_path is set.

searchPath = docsPath ? join(basePath, docsPath) : basePath, and the walk starts from searchPath with basePath = "". So when a definition sets docs_path: docs, the scan root is the docs directory — and a genuine page at docs/security.md is still dropped:

WITH docs_path='docs':          WITHOUT docs_path:
  docs/admin/actions/security.md   docs/admin/actions/security.md
  docs/guide.md                    docs/guide.md
                                   docs/security.md      <- kept here, dropped above

(Scratch repo with SECURITY.md at the repo root plus those three pages. SECURITY.md is correctly dropped in both.)

So the same file is kept or dropped depending on whether the definition happens to set docs_path — and 135 of our 140 definitions set it, so that's the common path, not the edge case.

The underlying reason is that IGNORED_FILES exists for repo roots — SECURITY.md, CONTRIBUTING.md, LICENSE.md are housekeeping there. Inside a docs tree they're just pages, which is exactly your argument, and it applies to the docs root too. Suggest gating on whether the scan root is the repo root rather than on depth:

// in readLocalDocsFiles
const atRepoRoot = !docsPath;
const markdownFiles = findMarkdownFiles(searchPath, ig, "", { lang, atRepoRoot });

and in findMarkdownFiles, if (matchingExt && basePath === "" && options.atRepoRoot).

Worth a third test alongside your two: docs/security.md with path: "docs" should be kept. Your existing pair is well chosen — the root case and the nested case are exactly right.

Everything else looks good: the changeset explains the user-visible impact well, and naming forgejo's container.valid_volumes as the concretely lost content is the kind of detail that makes a bug report verifiable.

---

Generated by Claude Code