@catheadowl/pathscope 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/semantics.md CHANGED
@@ -19,14 +19,14 @@ The full-stack priority over one engine, strongest first:
19
19
 
20
20
  ## Presets
21
21
 
22
- Five preset groups; mounting is append-only, presets sit at the FRONT of the combined rule table:
22
+ Five preset groups; mounting is append-only, presets sit at the FRONT of the combined rule table. A `dirs` entry with a leading slash is **scan-root-anchored** (plain gitignore anchoring): it matches only at the scan root itself (re-anchored accordingly when the scan root sits below a repo root), and the named-negation exit key un-excludes it like any other entry.
23
23
 
24
24
  | Group | Covers |
25
25
  | --- | --- |
26
26
  | `vcs` | `.git/`, `.hg/`, `.svn/` |
27
27
  | `deps` | `node_modules/`, `.pnpm/`, `vendor/` |
28
- | `build` | `dist/`, `build/`, `lib/`, `out/`, `coverage/` |
29
- | `caches` | `__pycache__/`, `.mypy_cache/`, `.pytest_cache/`, `.ruff_cache/`, `.tox/`, `.venv/`, `.nox/`, `.cache/`, `.next/`, `.nuxt/`, `.turbo/`, `.vite/`, `.parcel-cache/`, `.svelte-kit/`, `.vscode-test/` |
28
+ | `build` | `dist/`, `build/`, `lib/`, `out/`, `coverage/`, `/target` (root-anchored — the cargo/maven build tree; nested same-named directories are untouched) |
29
+ | `caches` | `__pycache__/`, `.mypy_cache/`, `.pytest_cache/`, `.ruff_cache/`, `.tox/`, `.venv/`, `venv/`, `.gradle/`, `.nox/`, `.cache/`, `.next/`, `.nuxt/`, `.turbo/`, `.vite/`, `.parcel-cache/`, `.svelte-kit/`, `.vscode-test/` |
30
30
  | `agentDocs` | `AGENTS.md`, `CLAUDE.md` (files — agent self-loading instructions, not project content) |
31
31
 
32
32
  ## Boundary markers
@@ -49,6 +49,26 @@ Opt-in via `boundaryStones.gitignoreProxy`: treat a nested `.gitignore` as a bou
49
49
 
50
50
  `boundaryStones.exempt` names subtrees whose own core/`.gitignore` marker hits are neutralized — the submodule-registration analogue (git does not descend into an unregistered embedded repository; naming a subtree is the walk-mode way to register it). Entries are gitignore-style patterns anchored at the scan root (e.g. `'embedded-toolkit/'`). A matched directory descends as a native subtree: its nested `.gitignore` files apply by the ordinary nesting rules (re-anchored, never leaking outside the subtree), while deeper markers inside it still cut — the exemption reaches only the named directory's own hits. Config homes are never exemptible.
51
51
 
52
+ ### The walk stone report
53
+
54
+ `walkScope` results carry `stoneHits`: every marker hit the walk discovered, as `{ stoneName, path, enforced }` — the stone that hit, the scan-root-relative directory directly containing it, and whether the hit executed its cut under the active alignment face and exemption. Pure metadata: the report never changes the file set. On the default git face `enforced: true` names where truncations happened; under `alignment: 'scanner'` core-stone hits report `enforced: false` (report-not-cut — "this subtree is a nested repository"), and exemption-neutralized hits report `enforced: false` the same way (registration, not rescue). Config-home hits always report `enforced: true` — they are your own declarations and keep their verdict under every face. The scan root's own markers are not reported (the root is the universe boundary and never adjudicates against itself); only directories the walk visits as descent candidates appear. Sorted by path, then stone name.
55
+
56
+ The report's completeness is the walk's: only visited descent candidates are probed, so subtrees removed by the rule stack (preset, `exclude`, the dot category) and everything below a budget cut leave no hits — a silent absence is not negative evidence; check `diagnostics` for the budget case. The core `.git` marker matches both of git's own forms (a `.git` directory, or the `gitdir` pointer file a worktree or submodule carries), and `.gitmodules` registration is invisible to the walk — a registered submodule hits exactly like an embedded repository, with `boundaryStones.exempt` as the walk-mode registration for both.
57
+
58
+ ### The walk link report
59
+
60
+ `walkScope` results carry `links`: the unresolved link entries (junctions / symlinks), named exactly as they appear in `files` — scan-root-relative, sorted, and always a **subset** of `files`. The same exclusion stack, dot category, and budget cut govern both faces, so an excluded link (a dot-named one, a rule-excluded one, one below a budget cut) leaves no record; link-aware consumers read `links` instead of re-deriving link-ness with per-entry lstat. `followSymlinks: true` retires the face — followed links are not unresolved entries (directory-link bodies retire from the output, file links resolve), so `links` is always `[]` under following.
61
+
62
+ A dirent whose type predicates are all false — DT_UNKNOWN filesystems (pre-ftype XFS, some network filesystems), unrecognized Windows reparse tags (e.g. OneDrive placeholders), special files (FIFOs, sockets, devices) on any filesystem — costs one lstat and the true type governs: links close on every filesystem, and entries the traversal silently dropped on such trees before (DT_UNKNOWN and placeholder dirents) now enumerate. Where every dirent lands inside the walk's three-way type dispatch (file / directory / symlink), the walk is byte-identical and pays nothing. The report's completeness is the walk's, as for `stoneHits`: rule-pruned subtrees and everything below a budget cut leave no records — a silent absence is not negative evidence.
63
+
64
+ ### The Windows hidden-attribute face
65
+
66
+ On Windows the dot category has a second detection face (2026-11-20 owner ruling, completing rg `hidden` semantics): an entry carrying `FILE_ATTRIBUTE_HIDDEN` is excluded by `excludeDotEntries` exactly like a dot-named one — AppData-class attribute-hidden, dot-less trees no longer enter walks uninvited. rg and fd (v7.4.0+) both check the attribute on Windows and the dot-name everywhere; the override whitelist rescues either face, and the dot hit's attribution says which face fired (`via: 'name' | 'attribute'`). The capability is a win-only native piece shipped inside the package (no optional dependencies, no install-time toolchain): enumeration itself carries the attributes, so the walk pays zero extra syscalls; the probe face reads the same attribute through its IO layer, so point queries and walks agree. When the native piece fails to load on win32 the attribute face goes inert and the scan says so loudly once (`windows-hidden-attributes-unavailable`) — never a silent behavioral gap; on unix the attribute face does not exist by design (ignore-crate precedent: unix hidden is dot-name only) and no diagnostic fires. Exclusion is not access control: naming a hidden entry through the override whitelist reaches it, same as rg `--hidden`.
67
+
68
+ ### The ignore family (`.ignore` / `.rgignore`)
69
+
70
+ The ignore family's non-vcs members are first-class rule sources (completing ignore-crate WalkBuilder parity, 2026-11-20 owner ruling): `.ignore` and `.rgignore` are read with the same gitignore(5) syntax, on the walk root itself and in every descended directory, with `respectIgnoreFamily` (default `true`) as their own layered escape hatch — turning both it and `respectGitignore` off is the file-face equivalent of rg `--no-ignore`, either one alone matching rg's `--no-ignore-vcs`-style granularity. Per directory the family folds in after that directory's `.gitignore` and `.rgignore` beats `.ignore` (the ignore crate's own precedence, empirically backed by the crate-judge lane); deeper layers beat shallower ones like every cascade member; the policy layer stays rear (explicit channels beat files, rg `-g` isomorphism) and the override whitelist stays terminal. Attribution is distinct: family hits carry `source: 'ignore'` plus `ignoreFile`, so probe chains never misattribute a family cut to gitignore. Unlike `.gitignore`, the family has **no inherited phase** — files above the walk root are never read (rg's own behavior when the root is a subdirectory, and the repository-local rule space); the global excludes file stays out for the same reason. Face-orthogonal: the family is read under every `alignment` face, exactly like `.gitignore`. Trees without family files are byte-identical, always.
71
+
52
72
  ## Scanner semantics
53
73
 
54
74
  With `alignment: 'scanner'` (ripgrep-style):
@@ -77,7 +97,7 @@ Presets are un-excludable by design: a named negation (`!vendor/`) in any gitign
77
97
  ## Walk defaults
78
98
 
79
99
  - Output: POSIX relative paths, sorted.
80
- - `excludeDotEntries` (default `true`): rg `hidden` semantics — a walk-layer option, not a gitignore rule; `override` can rescue dot entries.
81
- - `respectGitignore: false` skips the gitignore sources only — presets, your own exclude rules, override, and boundary markers adjudicate exactly as before (rg `--no-ignore`).
100
+ - `excludeDotEntries` (default `true`): rg `hidden` semantics, platform-twin-faced — the dot-name face everywhere plus the Windows `FILE_ATTRIBUTE_HIDDEN` face (see above) — a walk-layer option, not a gitignore rule; `override` can rescue hidden entries on either face.
101
+ - `respectGitignore: false` skips the gitignore sources only — presets, your own exclude rules, override, and boundary markers adjudicate exactly as before; the `.ignore` family keeps its own switch (`respectIgnoreFamily`), and both off is rg `--no-ignore`'s file face (rg `--no-ignore-vcs` granularity for either alone).
82
102
  - Symlinks are not resolved by default (git/ripgrep default).
83
103
  - `walkScope` and `gitUniverse` are mutually exclusive ways to resolve one scope request — no stacking or combination. `explainScopePath` is the read-only third face over the same request: it adjudicates, it never enumerates.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@catheadowl/pathscope",
3
- "version": "0.2.0",
3
+ "version": "0.4.0",
4
4
  "description": "Cross-repo shared engine resolving the in-scope file set: walk or per-path point queries (excluded + why), gitignore cascade, mounted exclusion presets, loud budget, git universe, boundary stones — under a git-native alignment skeleton with conformance fixtures adjudicated by a git oracle.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -16,6 +16,7 @@
16
16
  "files": [
17
17
  "dist",
18
18
  "docs",
19
+ "prebuilds",
19
20
  "CHANGELOG.md"
20
21
  ],
21
22
  "publishConfig": {
@@ -24,6 +25,7 @@
24
25
  },
25
26
  "scripts": {
26
27
  "build": "tsc -p tsconfig.build.json && node scripts/build-cjs.mjs",
28
+ "build:native": "node scripts/build-native.mjs",
27
29
  "typecheck": "tsc --noEmit",
28
30
  "lint:face": "node scripts/published-face-lint.mjs",
29
31
  "test": "node --test \"test/*.test.ts\"",
@@ -40,6 +42,7 @@
40
42
  "devDependencies": {
41
43
  "@types/node": "^26.6.5",
42
44
  "esbuild": "^0.28.2",
45
+ "node-gyp": "^13.1.0",
43
46
  "typescript": "^7.0.2"
44
47
  },
45
48
  "exports": {